The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
docs(documentation): update architecture and feature documentation
Steven Enamakelff726733701b
diff --git a/crates/openhuman-core/src/channels/README.md b/crates/openhuman-core/src/channels/README.mdindex 2dc7dc61f9..920668f24e 100644--- a/crates/openhuman-core/src/channels/README.md+++ b/crates/openhuman-core/src/channels/README.md@@ -50,12 +50,12 @@ or shell-based substitute.## Layout-| Path | Purpose |-| --- | --- |-| [`mod.rs`](./mod.rs) | Feature gates, TinyBus module setup, and host-facing channel contracts. |-| [`tinychannels-bus channel contracts`](../../../../vendor/tinychannels/crates/tinychannels-bus/src/channel/) | Portable message and typed send contracts. |-| [`controllers/`](./controllers/) | OpenHuman `channels.*` operations and host-side backend transport adaptation. |-| [`host/`](./host/) | Typed module callbacks, event subscribers, and remote-control host operations. |-| [`runtime/`](./runtime/README.md) | Module lease startup, account lifetime, and the OpenHuman dispatch pipeline. |-| [`bus/`](./bus/) | Hosted-channel inbound and durable progressive delivery integration. |-| [`providers/relay/`](./providers/relay/README.md) | Gateway relay RPC surface and host-side relay orchestration. |+| Path | Purpose |+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |+| [`mod.rs`](./mod.rs) | Feature gates, TinyBus module setup, and host-facing channel contracts. |+| [`tinychannels-bus channel contracts`](../../../../vendor/tinychannels/crates/tinychannels-bus/src/channel/) | Portable message and typed send contracts. |+| [`controllers/`](./controllers/) | OpenHuman `channels.*` operations and host-side backend transport adaptation. |+| [`host/`](./host/) | Typed module callbacks, event subscribers, and remote-control host operations. |+| [`runtime/`](./runtime/README.md) | Module lease startup, account lifetime, and the OpenHuman dispatch pipeline. |+| [`bus/`](./bus/) | Hosted-channel inbound and durable progressive delivery integration. |+| [`providers/relay/`](./providers/relay/README.md) | Gateway relay RPC surface and host-side relay orchestration. |diff --git a/docs/gitbooks/en/developing/architecture/agent-harness.md b/docs/gitbooks/en/developing/architecture/agent-harness.mdindex 29688ed892..a8ede68e1e 100644--- a/docs/gitbooks/en/developing/architecture/agent-harness.md+++ b/docs/gitbooks/en/developing/architecture/agent-harness.md@@ -192,11 +192,11 @@ Freezing the prompt is only one third of the contract, and the other two are eas- The tool block counts, and it comes _first_. Every prefix cache in production renders the tool catalogue ahead of the conversation, a chat template has to put it somewhere the model reads before the first user turn. OpenAI's automatic cache, Anthropic's `cache_control` (tools → system → messages), DeepSeek's context cache and any vLLM/SGLang radix cache all work this way. So a `tools` array that changes between turns invalidates the frozen system prompt too, and the JSON key order of the request body (which puts `messages` before `tools`) says nothing about it. The mid-session Composio reconcile is still correct, a tool surface that lies about what the model can call is worse than a cold prefill, but it must fire only on a real capability change and be byte-stable otherwise. `connected_set_hash` sorts before hashing so a reordered backend response never reaches a rebuild, and `collect_orchestrator_tools` sorts the connected-toolkit enum for the same reason.- History must be append-only. Turn N's serialization has to survive verbatim as the opening of turn N+1. `pair_tool_cycles` drops half-finished tool cycles at serialization time, so its verdict for an entry must depend only on that entry and its immediate neighbour, never on anything appended later, or an earlier message's presence flips retroactively and the prefix moves under the cache. Context compaction is the one deliberate exception; it rewrites the middle and pays for a re-prefill.-A resumed session's replayed prefix is folded into `Agent::history` rather than spliced into one request, so the request, the following turn and the persisted transcript all read the same sequence. Splicing it cost the conversation twice: the next turn went out without it, and the transcript written afterwards (serialized from `history`) held only the new turn, which the *next* resume then read back, truncating the thread a little further on every restart.+A resumed session's replayed prefix is folded into `Agent::history` rather than spliced into one request, so the request, the following turn and the persisted transcript all read the same sequence. Splicing it cost the conversation twice: the next turn went out without it, and the transcript written afterwards (serialized from `history`) held only the new turn, which the _next_ resume then read back, truncating the thread a little further on every restart.#### A stable prefix only pays out when the wire says so-Keeping the bytes stable is necessary, not sufficient: the provider still has to be *told* to cache, and two providers need telling explicitly.+Keeping the bytes stable is necessary, not sufficient: the provider still has to be _told_ to cache, and two providers need telling explicitly.- Anthropic caches nothing without `cache_control` markers, and its OpenAI-compatible endpoint cannot carry them, Anthropic documents prompt caching as unsupported on that path and reports `prompt_tokens_details` as always empty. A `cloud_providers` entry with `auth_style = "anthropic"` is therefore built as the crate's native Messages adapter (`tinyinference_llm::providers::anthropic`), which places markers on the last tool, the last system block, and the final message so a growing tool loop reuses the previous iteration's cache rather than only the system prompt. The one exception is text mode (`native_tools = false`, prompt-guided tools), which only the Chat Completions adapter implements and which keeps the compat client, and so keeps paying full price.- OpenRouter forwards markers to Anthropic and Gemini but adds none itself; hosted OpenAI rejects unknown content-part fields. The OpenRouter slug (and any endpoint on `openrouter.ai`) enables `OpenAiModel::with_explicit_cache_control`, which marks the last system and last user message; every other Chat Completions endpoint stays unmarked.@@ -367,7 +367,7 @@ Path hardening is fail-closed. `resolve_artifact_path` rejects absolute paths, `Writes log `[artifact] wrote worker artifact under action_dir`; each path a handoff carries logs `[artifact] handoff carried an artifact path to the parent`, on both the producing and the consuming side, so a run journal shows both ends of every pointer.-### TokenJuice: content-aware tool-output compaction+### TokenJuice: content-aware tool-output compactionBefore a fresh tool result enters history (and ahead of the byte-budget backstop), it passes through the TokenJuice content router inside the compiled TinyJuice module, with OpenHuman adapters in `crates/openhuman-core/src/inference/tokenjuice/`. Inspired by Headroom, the router _detects the content kind_ (JSON, code, log, search, diff, HTML, plain text) from the bytes and/or a hint derived from the tool name and arguments, then dispatches to a specialised compressor:@@ -402,26 +402,26 @@ A single agent that knows everything also has a system prompt the size of a smalEach archetype lives under `agents/<name>/` with an `agent.toml` (metadata, tool scope, model hint) and a prompt. The orchestrator's chat delegates are the ones in its `[subagents]` allowlist:-| Archetype | When the orchestrator picks it |-| ---------------------- | ---------------------------------------------------------------------------------------------- |-| `orchestrator` | The Master Agent: top-level, direct-capable default. Never spawned by another orchestrator. |-| `task_manager_agent` | Adding, previewing, fetching, updating or removing task sources, workflow bundles, artifacts. |-| `vision_agent` | Anything that depends on the content of an image (describe, OCR, UI elements). |-| `image_agent` | Generating or editing an image. |-| `video_agent` | Generating a video or animating an image. |-| `presentation_agent` | Building a slide deck with grounding and citations (feature `documents`). |-| `skill_setup` | Finding, installing and managing skills from registries (`setup_skills`). |-| `workflow_builder` | Authoring or editing a saved workflow (`build_workflow`); returns a proposal, never saves. |-| `flow_discovery` | Suggesting workflows worth setting up (`discover_workflows`). |+| Archetype | When the orchestrator picks it |+| -------------------- | --------------------------------------------------------------------------------------------- |+| `orchestrator` | The Master Agent: top-level, direct-capable default. Never spawned by another orchestrator. |+| `task_manager_agent` | Adding, previewing, fetching, updating or removing task sources, workflow bundles, artifacts. |+| `vision_agent` | Anything that depends on the content of an image (describe, OCR, UI elements). |+| `image_agent` | Generating or editing an image. |+| `video_agent` | Generating a video or animating an image. |+| `presentation_agent` | Building a slide deck with grounding and citations (feature `documents`). |+| `skill_setup` | Finding, installing and managing skills from registries (`setup_skills`). |+| `workflow_builder` | Authoring or editing a saved workflow (`build_workflow`); returns a proposal, never saves. |+| `flow_discovery` | Suggesting workflows worth setting up (`discover_workflows`). |Other built-ins are never chat delegates:-| Archetype | Who runs it |-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |-| `planner`, `critic` | Only the `parallel_research_cross_check` workflow-run template (decompose and research = `planner`, cross_check = `critic`). |-| `summarizer` | The harness, to compress oversized tool results; also the synthesize phase of that workflow-run template. |-| `trigger_triage` / `trigger_reactor` | Classifying an incoming external event, and the lightweight reaction to one. |-| `morning_briefing` | Cron: the daily digest, on a named read-only tool belt. |+| Archetype | Who runs it |+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |+| `planner`, `critic` | Only the `parallel_research_cross_check` workflow-run template (decompose and research = `planner`, cross_check = `critic`). |+| `summarizer` | The harness, to compress oversized tool results; also the synthesize phase of that workflow-run template. |+| `trigger_triage` / `trigger_reactor` | Classifying an incoming external event, and the lightweight reaction to one. |+| `morning_briefing` | Cron: the daily digest, on a named read-only tool belt. |The orchestrator itself handles coding, crypto, settings, scheduling, product docs and MCP servers through inline skills: `use_skill` loads a tool pack's guide and schemas (`coding`, `web3`, `system`, `scheduling`, `docs`, `mcp`), and the same tools are `Deferred` so `tool_search` finds any single one. Running an installed skill is the orchestrator's own `run_workflow`. See [`tools/toolpacks/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/tools/toolpacks/README.md).@@ -468,11 +468,11 @@ Primary (direct-capable, Master Agent on `coding` hint)Each `AgentDefinition` carries an `agent_tier` field (`chat` / `reasoning` / `worker`, default `worker`). The contract:-| Tier | May spawn | Must NOT spawn | Typical members |-| ----------- | --------------------- | ------------------------------- | ------------------------------------------------------------------------------- |-| `chat` | `reasoning`, `worker` | another `chat` | `orchestrator` |-| `reasoning` | `worker` | another `reasoning`, any `chat` | `planner` (today the canonical one) |-| `worker` | nothing[^1] | anything | critic, image_agent, task_manager_agent, … |+| Tier | May spawn | Must NOT spawn | Typical members |+| ----------- | --------------------- | ------------------------------- | ------------------------------------------ |+| `chat` | `reasoning`, `worker` | another `chat` | `orchestrator` |+| `reasoning` | `worker` | another `reasoning`, any `chat` | `planner` (today the canonical one) |+| `worker` | nothing[^1] | anything | critic, image_agent, task_manager_agent, … |[^1]: Skill-wildcard entries (`{ skills = "*" }`) are exempt because they name no agent: they expand to the connected Composio actions as `Deferred` tools the agent reaches through `tool_search`, not to a spawn.@@ -623,24 +623,24 @@ None of these change the loop's shape, they just make the common failure modes rThe harness shell lives under `crates/openhuman-core/src/agent/`, with the tinyagents adapter seam in `crates/openhuman-core/src/agent/tinyagents/` and archetype definitions in `crates/openhuman-core/src/agent/registry/`. The README in `crates/openhuman-core/src/agent/` enumerates the public surface; the most load-bearing files (paths relative to `crates/openhuman-core/src/agent/` unless prefixed) are:-| File / dir | What lives there |-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |-| `session_host/runtime_session.rs` | `Agent::turn`: the lifecycle described above; routes into the tinyagents runner via `tinyagents/turn_exec.rs`. |-| `tinyagents/mod.rs` | `TurnSpec::run`: the shared tinyagents harness assembly (the live loop). |-| `tinyagents/middleware.rs` | The named OpenHuman middleware stack (approval/security, tool policy, recovery, budgets, circuit breaker). |-| `harness/graph.rs` | The channel/CLI bus turn route into the tinyagents runner. |-| `subagent_host/` | Direct OpenHuman planner/executor/persistence adapters for `tinyagents-orchestration::subagent`; product prompt/tool/model/security/artifact/progress behavior remains here. |-| `orchestration/subagent_sessions/` | Durable reusable sub-agent identity, compatibility matching, persisted status/history. |-| `harness/host_definition.rs` | Host extension and registry over `tinyagents_definition::AgentDefinition`. |-| `subagent_host/ops/runner.rs` | Integration-tool ranking and the host execution leaf; generic lifecycle stays in `tinyagents-orchestration`. |-| `tinyagents/payload_summarizer.rs` | The model call behind TinyJuice's oversized-tool-result summary. |-| `session_host/tool_progress.rs` | Surviving OpenHuman seam: `TurnProgress`. |-| `message_convert.rs` | Concrete durable/provider conversion around canonical tool-call dialect APIs. |-| `triage/` | External-trigger classification + escalation. |-| `registry/agents/` | Built-in archetypes: one subdirectory per agent. |-| `hooks.rs` / `stop_hooks.rs` | Post-turn and mid-turn hook surfaces. |-| `cost.rs` | Per-turn USD/token accounting. |-| `progress.rs` | Real-time progress events to the UI. |+| File / dir | What lives there |+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `session_host/runtime_session.rs` | `Agent::turn`: the lifecycle described above; routes into the tinyagents runner via `tinyagents/turn_exec.rs`. |+| `tinyagents/mod.rs` | `TurnSpec::run`: the shared tinyagents harness assembly (the live loop). |+| `tinyagents/middleware.rs` | The named OpenHuman middleware stack (approval/security, tool policy, recovery, budgets, circuit breaker). |+| `harness/graph.rs` | The channel/CLI bus turn route into the tinyagents runner. |+| `subagent_host/` | Direct OpenHuman planner/executor/persistence adapters for `tinyagents-orchestration::subagent`; product prompt/tool/model/security/artifact/progress behavior remains here. |+| `orchestration/subagent_sessions/` | Durable reusable sub-agent identity, compatibility matching, persisted status/history. |+| `harness/host_definition.rs` | Host extension and registry over `tinyagents_definition::AgentDefinition`. |+| `subagent_host/ops/runner.rs` | Integration-tool ranking and the host execution leaf; generic lifecycle stays in `tinyagents-orchestration`. |+| `tinyagents/payload_summarizer.rs` | The model call behind TinyJuice's oversized-tool-result summary. |+| `session_host/tool_progress.rs` | Surviving OpenHuman seam: `TurnProgress`. |+| `message_convert.rs` | Concrete durable/provider conversion around canonical tool-call dialect APIs. |+| `triage/` | External-trigger classification + escalation. |+| `registry/agents/` | Built-in archetypes: one subdirectory per agent. |+| `hooks.rs` / `stop_hooks.rs` | Post-turn and mid-turn hook surfaces. |+| `cost.rs` | Per-turn USD/token accounting. |+| `progress.rs` | Real-time progress events to the UI. |## Agent engine and orchestration on tinyagents@@ -649,13 +649,13 @@ session/turn host, while a sub-agent call enters `agent/subagent_host` and itsdirect `tinyagents-orchestration::subagent` lifecycle. There is no`harness/subagent_runner` compatibility path. The surrounding OpenHuman seam:-| File (`crates/openhuman-core/src/agent/tinyagents/`) | Role |-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| `mod.rs` | The runner (`TurnSpec::run`): installs the native `ChatModel`, host tool adapters, and middleware on an `AgentHarness`; runs one turn; caps output through `MaxTokensModel` (`agent/tinyagents/model.rs`); mirrors progress; forwards steering; and pauses gracefully at the model-call cap. |-| `mod.rs` / `model.rs` / `tools.rs` / `convert.rs` | `RunPolicy` / `ChatModel` / `Tool` / message adapters (incl. unknown-tool policy and out-of-band reasoning forwarding). |-| `observability.rs` | Harness `AgentEvent` → `AgentProgress` + cost; `GraphTracingSink` for graph events. |-| `orchestration.rs` | Re-exported `graph::orchestration` task-store types; map-reduce fanout uses the TinyAgents SDK surface directly. |-| `delegation.rs` | The durable `plan → execute ⇄ review → finalize` delegation graph (production worker wired in `orchestration::delegation`), checkpointed via TinyAgents' own `SqliteCheckpointer`. |+| File (`crates/openhuman-core/src/agent/tinyagents/`) | Role |+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `mod.rs` | The runner (`TurnSpec::run`): installs the native `ChatModel`, host tool adapters, and middleware on an `AgentHarness`; runs one turn; caps output through `MaxTokensModel` (`agent/tinyagents/model.rs`); mirrors progress; forwards steering; and pauses gracefully at the model-call cap. |+| `mod.rs` / `model.rs` / `tools.rs` / `convert.rs` | `RunPolicy` / `ChatModel` / `Tool` / message adapters (incl. unknown-tool policy and out-of-band reasoning forwarding). |+| `observability.rs` | Harness `AgentEvent` → `AgentProgress` + cost; `GraphTracingSink` for graph events. |+| `orchestration.rs` | Re-exported `graph::orchestration` task-store types; map-reduce fanout uses the TinyAgents SDK surface directly. |+| `delegation.rs` | The durable `plan → execute ⇄ review → finalize` delegation graph (production worker wired in `orchestration::delegation`), checkpointed via TinyAgents' own `SqliteCheckpointer`. |Orchestration on graphs (`crates/openhuman-core/src/agent/orchestration/`):diff --git a/docs/gitbooks/en/developing/architecture/frontend.md b/docs/gitbooks/en/developing/architecture/frontend.mdindex 45839f599a..f52571819f 100644--- a/docs/gitbooks/en/developing/architecture/frontend.md+++ b/docs/gitbooks/en/developing/architecture/frontend.md@@ -15,23 +15,23 @@ The tree also carries a mobile shell: `AppRoutesIOS.tsx`, `pages/ios/`, the `ser## Quick reference-| Section | Covers |-| -------------------------------------------- | --------------------------------------------------------------- |-| [Architecture](#architecture-overview) | Provider chain, build, layout, conventions |-| [State management](#state-management) | Redux Toolkit slices, selectors, persistence |-| [Services layer](#services-layer) | `apiClient`, `socketService`, `coreRpcClient` |-| [Providers](#providers) | `ThemeProvider`, `CoreState`, `Socket`, `ChatRuntime` providers |-| [Pages and routing](#pages-and-routing) | `HashRouter`, route guards, main routes |-| [Components](#components) | UI / settings component patterns |-| [Hooks and utilities](#hooks-and-utilities) | Shared hooks, helpers, config |+| Section | Covers |+| ------------------------------------------- | --------------------------------------------------------------- |+| [Architecture](#architecture-overview) | Provider chain, build, layout, conventions |+| [State management](#state-management) | Redux Toolkit slices, selectors, persistence |+| [Services layer](#services-layer) | `apiClient`, `socketService`, `coreRpcClient` |+| [Providers](#providers) | `ThemeProvider`, `CoreState`, `Socket`, `ChatRuntime` providers |+| [Pages and routing](#pages-and-routing) | `HashRouter`, route guards, main routes |+| [Components](#components) | UI / settings component patterns |+| [Hooks and utilities](#hooks-and-utilities) | Shared hooks, helpers, config |## Scale-| Metric | How to read it |-| --------------------------------------- | -------------------------------------------------------------- |-| TypeScript / TSX files under `app/src/` | `find app/src -name '*.ts' -o -name '*.tsx' \| wc -l` |-| App-level hooks | `ls app/src/hooks/*.ts app/src/hooks/*.tsx \| wc -l` |-| Test runner | Vitest (`app/test/vitest.config.ts`) |+| Metric | How to read it |+| --------------------------------------- | ----------------------------------------------------- |+| TypeScript / TSX files under `app/src/` | `find app/src -name '*.ts' -o -name '*.tsx' \| wc -l` |+| App-level hooks | `ls app/src/hooks/*.ts app/src/hooks/*.tsx \| wc -l` |+| Test runner | Vitest (`app/test/vitest.config.ts`) |## Directory layout@@ -77,7 +77,7 @@ its separate channel terminal event.| File | Purpose || ----------------------- | -------------------------------------------------------------------------------- || `app/src/main.tsx` | React root, polyfills, Sentry boundary, store, global styles |-| `app/src/App.tsx` | Provider chain (see below) + desktop/mobile shells, Settings |+| `app/src/App.tsx` | Provider chain (see below) + desktop/mobile shells, Settings || `app/src/AppRoutes.tsx` | `HashRouter` routes, `ProtectedRoute` / `PublicRoute` / `DefaultRedirect` guards |### Provider chain@@ -86,20 +86,20 @@ its separate channel terminal event._Generated from `app/src/App.tsx` by `scripts/generate-architecture-docs.mjs`. Do not edit by hand — run `pnpm docs:generate` to refresh._-| # | Component | Role |-| --- | --- | --- |-| 1 | `Sentry.ErrorBoundary` | Crash boundary; renders ErrorFallbackScreen |-| 2 | `Provider` | Redux store; enables useAppSelector / dispatch app-wide |-| 3 | `PersistGate` | Holds UI until persisted Redux slices rehydrate |-| 4 | `ThemeProvider` | Theme tokens and dark-mode handling |-| 5 | `I18nProvider` | Localization context consumed via useT |-| 6 | `BootCheckGate` | Blocks render until the core boot snapshot resolves |-| 7 | `CoreStateProvider` | Core app snapshot: auth, session, onboarding state |-| 8 | `SocketProvider` | Core socket.io events; desktop only (mobile uses the TunnelTransport relay) |-| 9 | `ChatRuntimeProvider` | Chat runtime events, tool timeline, and approvals |-| 10 | `Router` | HashRouter navigation for all routes |-| 11 | `CommandProvider` | Command palette context |-| 12 | `ServiceBlockingGate` | Blocks the shell until required services are configured |+| # | Component | Role |+| --- | ---------------------- | --------------------------------------------------------------------------- |+| 1 | `Sentry.ErrorBoundary` | Crash boundary; renders ErrorFallbackScreen |+| 2 | `Provider` | Redux store; enables useAppSelector / dispatch app-wide |+| 3 | `PersistGate` | Holds UI until persisted Redux slices rehydrate |+| 4 | `ThemeProvider` | Theme tokens and dark-mode handling |+| 5 | `I18nProvider` | Localization context consumed via useT |+| 6 | `BootCheckGate` | Blocks render until the core boot snapshot resolves |+| 7 | `CoreStateProvider` | Core app snapshot: auth, session, onboarding state |+| 8 | `SocketProvider` | Core socket.io events; desktop only (mobile uses the TunnelTransport relay) |+| 9 | `ChatRuntimeProvider` | Chat runtime events, tool timeline, and approvals |+| 10 | `Router` | HashRouter navigation for all routes |+| 11 | `CommandProvider` | Command palette context |+| 12 | `ServiceBlockingGate` | Blocks the shell until required services are configured |<!-- END GENERATED: provider-chain -->@@ -168,31 +168,31 @@ The application uses Redux Toolkit with Redux-Persist. There is no single root pAuthoritative list = the `reducer` map in `store/index.ts`. One-line purposes:-| Slice | Purpose | Persisted? |-| --------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------- |-| `accounts` | Connected web-app accounts + rail ordering | `accounts`, `order`, `lastActiveAccountId` (not the active id) |-| `announcement` | Harness-init announcement banner, seen ids | `shownIds` |-| `channelConnections` | Messaging channel connections (WhatsApp, Slack, …) | connections + migration/default-channel fields |-| `chatRuntime` | Streaming buffers, tool timelines, inference status, artifacts | only `artifactsByThread` (ready snapshots) |-| `connectivity` | navigator.onLine, core health, renderer to core socket, core to hosted link | no |-| `coreMode` | Pre-login core mode selection (embedded / self-hosted / cloud) | `mode` (plain localStorage) |-| `followupSuggestions` | Follow-up chips for each thread's latest settled turn | no (in-memory only) |-| `githubStar` | Whether the user dismissed the in-app "Star us on GitHub" CTA | `dismissed` |-| `layout` | Two-pane layout geometry (sidebar visibility, dragged widths) | `panels` |-| `locale` | UI language | `current` (plain localStorage) |-| `mascot` | Mascot appearance / voice selection | `color`, `voiceId`, `customMascotGifUrl`, `selectedMascotId` |-| `notifications` | Notification items + preferences | `items`, `preferences` |-| `persona` | Cosmetic persona display name + description (SOUL.md lives in the core) | `displayName`, `description` |-| `ptt` | Push-to-talk hotkey + session prefs (`isHeld` deliberately excluded) | `shortcut`, `speakReplies`, `showOverlay` |-| `queue` | The core's per-thread run queue plus the composer's pending follow-up messages | no (in-memory only) |-| `runMode` | Per-thread plan/build run mode | no (in-memory only) |-| `socket` | Per-user socket connection status / socket ids | no (reconnects on boot) |-| `theme` | Theme mode, font size, message view mode, custom themes | plain localStorage |-| `thread` | Chat thread list + per-thread message caches | only `selectedThreadId` |-| `threadGoal` | Durable per-thread goal state | no (in-memory only) |-| `threadTodos` | Live per-thread todo list | no (in-memory only) |-| `userErrors` | User-actionable runtime errors | no (in-memory only) |-| `walletPreferences` | Hidden-token preferences for the wallet view | `hiddenTokenKeys` |+| Slice | Purpose | Persisted? |+| --------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |+| `accounts` | Connected web-app accounts + rail ordering | `accounts`, `order`, `lastActiveAccountId` (not the active id) |+| `announcement` | Harness-init announcement banner, seen ids | `shownIds` |+| `channelConnections` | Messaging channel connections (WhatsApp, Slack, …) | connections + migration/default-channel fields |+| `chatRuntime` | Streaming buffers, tool timelines, inference status, artifacts | only `artifactsByThread` (ready snapshots) |+| `connectivity` | navigator.onLine, core health, renderer to core socket, core to hosted link | no |+| `coreMode` | Pre-login core mode selection (embedded / self-hosted / cloud) | `mode` (plain localStorage) |+| `followupSuggestions` | Follow-up chips for each thread's latest settled turn | no (in-memory only) |+| `githubStar` | Whether the user dismissed the in-app "Star us on GitHub" CTA | `dismissed` |+| `layout` | Two-pane layout geometry (sidebar visibility, dragged widths) | `panels` |+| `locale` | UI language | `current` (plain localStorage) |+| `mascot` | Mascot appearance / voice selection | `color`, `voiceId`, `customMascotGifUrl`, `selectedMascotId` |+| `notifications` | Notification items + preferences | `items`, `preferences` |+| `persona` | Cosmetic persona display name + description (SOUL.md lives in the core) | `displayName`, `description` |+| `ptt` | Push-to-talk hotkey + session prefs (`isHeld` deliberately excluded) | `shortcut`, `speakReplies`, `showOverlay` |+| `queue` | The core's per-thread run queue plus the composer's pending follow-up messages | no (in-memory only) |+| `runMode` | Per-thread plan/build run mode | no (in-memory only) |+| `socket` | Per-user socket connection status / socket ids | no (reconnects on boot) |+| `theme` | Theme mode, font size, message view mode, custom themes | plain localStorage |+| `thread` | Chat thread list + per-thread message caches | only `selectedThreadId` |+| `threadGoal` | Durable per-thread goal state | no (in-memory only) |+| `threadTodos` | Live per-thread todo list | no (in-memory only) |+| `userErrors` | User-actionable runtime errors | no (in-memory only) |+| `walletPreferences` | Hidden-token preferences for the wallet view | `hiddenTokenKeys` |Ephemeral chat state (streaming buffers, tool timelines) must not survive a restart: the UI would try to resume a turn whose live driver is gone. The one exception, agent-generated artifacts, goes through the `artifactsReadyOnlyTransform` in `store/index.ts` (pure logic in `store/artifactsPersistFilter.ts`).@@ -357,7 +357,7 @@ disagree about the same setting.| Module | Role || ----------------------- | --------------------------------------------------------------------------------------------------------- |-| `ChatMascotContext.tsx` | Shared dock/stage refs and the send binding. Every value is stable: see the re-render note below. |+| `ChatMascotContext.tsx` | Shared dock/stage refs and the send binding. Every value is stable: see the re-render note below. || `ChatMascotDock.tsx` | The small mascot standing on the composer's input box. An anchor + hit area; it draws nothing. || `ChatMascotStage.tsx` | The scaled-up voice surface: `MicComposer`, input-device selector, speak-replies switch, collapse button. || `ChatMascotOverlay.tsx` | The single Rive instance, moved between dock and stage with a `transform`. |@@ -479,29 +479,29 @@ The application uses HashRouter with protected and public route guards. Desktop`app/src/AppRoutes.tsx` is the authoritative table and is heavily commented with the rationale for each entry. The desktop routes it declares:-| Route | Renders | Guard |-| --- | --- | --- |-| `/` | `Welcome` | `PublicRoute` (signed in: forwards to `/home`) |-| `/auth` | `WebCallbackPage`, the auth callback | none |-| `/callback/:kind`, `/callback/:kind/:status` | `WebCallbackPage`, generic OAuth and provider callbacks | none |-| `/onboarding/*` | `Onboarding` stepper | `ProtectedRoute` |-| `/human` | `HumanPage`, the dedicated mascot stage | `ProtectedRoute` |-| `/chat/:threadId?` | `Accounts`, the unified chat (agent plus connected web apps) | `ProtectedRoute` |-| `/flows` | `FlowsPage` | `ProtectedRoute` |-| `/flows/draft` | `FlowCanvasDraftPage`, an unsaved proposed graph passed in `location.state` | `ProtectedRoute` |-| `/flows/:id` | `FlowCanvasPage` | `ProtectedRoute` |-| `/workflows` | `Activity`, the `SKILL.md` workflow hub | `ProtectedRoute` |-| `/workflows/run` | `WorkflowsRun`, the single-purpose Skill runner | `ProtectedRoute` |-| `/connections` | `Skills`, the connections hub | `ProtectedRoute` |-| `/invites` | `Invites` | `ProtectedRoute` |-| `/notifications` | `Notifications` | `ProtectedRoute` |-| `/settings/*` | `Settings` | `ProtectedRoute` |-| `/ptt-overlay` | `PttOverlayPage`, the push-to-talk overlay window | none |-| `/dev/agent-insights` | `AgentInsightsPreview` | dev only |-| `/dev/ui` | `UiGallery`, every shared UI primitive in the active theme | dev only |-| `/dev/tools` | `ToolCallGallery`, every tool-call state and the whole core catalog | dev only |-| `/dev/assistant-ui` | The upstream assistant-ui demo on a mock runtime | dev only |-| `*` | `DefaultRedirect` | none |+| Route | Renders | Guard |+| -------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------- |+| `/` | `Welcome` | `PublicRoute` (signed in: forwards to `/home`) |+| `/auth` | `WebCallbackPage`, the auth callback | none |+| `/callback/:kind`, `/callback/:kind/:status` | `WebCallbackPage`, generic OAuth and provider callbacks | none |+| `/onboarding/*` | `Onboarding` stepper | `ProtectedRoute` |+| `/human` | `HumanPage`, the dedicated mascot stage | `ProtectedRoute` |+| `/chat/:threadId?` | `Accounts`, the unified chat (agent plus connected web apps) | `ProtectedRoute` |+| `/flows` | `FlowsPage` | `ProtectedRoute` |+| `/flows/draft` | `FlowCanvasDraftPage`, an unsaved proposed graph passed in `location.state` | `ProtectedRoute` |+| `/flows/:id` | `FlowCanvasPage` | `ProtectedRoute` |+| `/workflows` | `Activity`, the `SKILL.md` workflow hub | `ProtectedRoute` |+| `/workflows/run` | `WorkflowsRun`, the single-purpose Skill runner | `ProtectedRoute` |+| `/connections` | `Skills`, the connections hub | `ProtectedRoute` |+| `/invites` | `Invites` | `ProtectedRoute` |+| `/notifications` | `Notifications` | `ProtectedRoute` |+| `/settings/*` | `Settings` | `ProtectedRoute` |+| `/ptt-overlay` | `PttOverlayPage`, the push-to-talk overlay window | none |+| `/dev/agent-insights` | `AgentInsightsPreview` | dev only |+| `/dev/ui` | `UiGallery`, every shared UI primitive in the active theme | dev only |+| `/dev/tools` | `ToolCallGallery`, every tool-call state and the whole core catalog | dev only |+| `/dev/assistant-ui` | The upstream assistant-ui demo on a mock runtime | dev only |+| `*` | `DefaultRedirect` | none |The four `/dev/*` routes are registered inside an `IS_DEV` branch (`utils/config`), so `import.meta.env.DEV` is substituted at build time, the branch folds away, and their component trees leave a production bundle entirely. They are previews, never part of the shipped product.@@ -509,18 +509,18 @@ Memory is a surface of `/connections`, not a route of its own: `?tab=brain&brainBack-compat redirects, all `Navigate replace`. The `ForwardSearch` ones copy the query string to the destination so old deep links still land on the right sub-tab:-| From | To |-| --- | --- |-| `/home` | `/chat` |-| `/accounts` | `/chat` |-| `/brain` | `/connections?tab=brain` (`BrainRedirect` remaps the old `?tab=` to `?brain=`) |-| `/skills` | `/connections` (`ForwardSearch`) |-| `/channels` | `/connections?tab=messaging` |-| `/activity` | `/settings/account` |-| `/intelligence` | `/settings/account` |-| `/feedback` | `/settings/feedback` |-| `/routines` | `/flows` |-| `/webhooks` | `/settings/integrations` (`ForwardSearch`) |+| From | To |+| --------------- | ------------------------------------------------------------------------------ |+| `/home` | `/chat` |+| `/accounts` | `/chat` |+| `/brain` | `/connections?tab=brain` (`BrainRedirect` remaps the old `?tab=` to `?brain=`) |+| `/skills` | `/connections` (`ForwardSearch`) |+| `/channels` | `/connections?tab=messaging` |+| `/activity` | `/settings/account` |+| `/intelligence` | `/settings/account` |+| `/feedback` | `/settings/feedback` |+| `/routines` | `/flows` |+| `/webhooks` | `/settings/integrations` (`ForwardSearch`) |There is no `/login` route: authentication flows through the Welcome page, the `/auth` callback, and deep links. `/agents` does not exist either, and Settings is an ordinary route rather than an overlay (see [Settings](#settings)).@@ -599,7 +599,7 @@ components/├── ProtectedRoute / PublicRoute / DefaultRedirect # Route guards├── layout/shell/ # RootShellLayout, AppSidebar, SidebarSlot (two-pane app chrome)├── settings/ # Settings registry, layout, panels, controls (see above)-├── accounts/ # Connected-app provider icons+├── accounts/ # Connected-app provider icons├── BootCheckGate/, daemon/ # Boot + service gates in the provider chain├── commands/ # CommandProvider (command palette)├── Announcement/, upsell/, notices/, walkthrough/ # Shell-level overlays@@ -721,15 +721,15 @@ const result = await callCoreRpc<Snapshot>({These names still turn up in older code and notes. Use the replacement:-| Removed | Replaced by |-| --- | --- |-| `SettingsModal`, `SettingsModalFrame`, `SettingsModalLayout`, `settingsOverlay.ts` | `/settings/*` as an ordinary route rendered by `Settings` |-| `SettingsPanelLayout`, `useSettingsAnimation`, `ProfilePanel` | The `settingsRouteRegistry` plus `components/settings/layout/` |-| `components/settings/search/` and `settingsSearchRegistry` | Nothing: the sidebar search field was removed. `searchKeywords` stays on the registry entries. |-| `WebviewHost` overlay in `components/accounts/` | Nothing: it went with the CEF provider webviews |-| The frontend QuickJS skills engine | Skill execution in the Rust core |-| `UserProvider`, `AIProvider`, `SkillProvider` | `CoreStateProvider` for auth and user state; AI configuration and skills in the core |-| `/conversations`, `/accounts` as standalone pages | `/chat/:threadId?` (`Accounts`), the unified chat surface |+| Removed | Replaced by |+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |+| `SettingsModal`, `SettingsModalFrame`, `SettingsModalLayout`, `settingsOverlay.ts` | `/settings/*` as an ordinary route rendered by `Settings` |+| `SettingsPanelLayout`, `useSettingsAnimation`, `ProfilePanel` | The `settingsRouteRegistry` plus `components/settings/layout/` |+| `components/settings/search/` and `settingsSearchRegistry` | Nothing: the sidebar search field was removed. `searchKeywords` stays on the registry entries. |+| `WebviewHost` overlay in `components/accounts/` | Nothing: it went with the CEF provider webviews |+| The frontend QuickJS skills engine | Skill execution in the Rust core |+| `UserProvider`, `AIProvider`, `SkillProvider` | `CoreStateProvider` for auth and user state; AI configuration and skills in the core |+| `/conversations`, `/accounts` as standalone pages | `/chat/:threadId?` (`Accounts`), the unified chat surface |## See alsodiff --git a/docs/gitbooks/en/features/channels.md b/docs/gitbooks/en/features/channels.mdindex a56e1aa406..ad357a6c1b 100644--- a/docs/gitbooks/en/features/channels.md+++ b/docs/gitbooks/en/features/channels.md@@ -47,23 +47,23 @@ an unsupported operation.OpenHuman has 15 channel providers. 14 are built into the shipped desktop app. WhatsApp Web sits behind the `whatsapp-web` build feature, which the shipped app does not enable, so you can't switch it on. The in-app Web chat is built in and is not a provider. A separate `cli` channel serves the `openhuman-core` terminal binary. Eight channels have a setup flow in the app: Telegram, Discord, Web, iMessage, Lark/Feishu, DingTalk, Email and 元宝 (Yuanbao). You turn on the rest by hand in `config.toml`.-| Channel | Direction | Inbound transport | Credentials | In Settings UI |-| ------------------ | ------------- | ---------------------------- | ------------------------------------------------------------------ | -------------- |-| Telegram | Two-way | Bot API long-poll | Connect via OpenHuman (managed DM) or your own BotFather token | Yes |-| Discord | Two-way | Gateway | Your own bot token, OAuth install, or managed account link | Yes |-| Web | Two-way | In-app | Built in, no setup (local) | Yes |-| iMessage | Two-way | macOS Messages (AppleScript) | Local only, no credentials (needs Full Disk Access) | Yes |-| Lark / Feishu | Two-way | WebSocket or webhook | Your own app id and secret | Yes |-| DingTalk | Two-way | Stream Mode WebSocket | Your own client id and secret | Yes |-| 元宝 (Yuanbao) | Two-way | WebSocket | Your own AppID and AppSecret | Yes |-| Slack | Two-way | Events/socket | Your own bot token | `config.toml` |-| WhatsApp | Two-way | Meta Cloud webhook | Your own access token | `config.toml` |-| IRC | Two-way | Persistent socket | Your own server and nick | `config.toml` |-| Signal | Two-way | signal-cli REST events | Your own linked signal-cli account | `config.toml` |-| Mattermost | Two-way | WebSocket | Your own bot token | `config.toml` |-| QQ | Two-way | WebSocket | Your own bot credentials | `config.toml` |-| Linq | Two-way (SMS) | Webhook | Your own API token | `config.toml` |-| Email | Two-way | IMAP IDLE and SMTP | Your own mailbox credentials | Yes |+| Channel | Direction | Inbound transport | Credentials | In Settings UI |+| -------------- | ------------- | ---------------------------- | -------------------------------------------------------------- | -------------- |+| Telegram | Two-way | Bot API long-poll | Connect via OpenHuman (managed DM) or your own BotFather token | Yes |+| Discord | Two-way | Gateway | Your own bot token, OAuth install, or managed account link | Yes |+| Web | Two-way | In-app | Built in, no setup (local) | Yes |+| iMessage | Two-way | macOS Messages (AppleScript) | Local only, no credentials (needs Full Disk Access) | Yes |+| Lark / Feishu | Two-way | WebSocket or webhook | Your own app id and secret | Yes |+| DingTalk | Two-way | Stream Mode WebSocket | Your own client id and secret | Yes |+| 元宝 (Yuanbao) | Two-way | WebSocket | Your own AppID and AppSecret | Yes |+| Slack | Two-way | Events/socket | Your own bot token | `config.toml` |+| WhatsApp | Two-way | Meta Cloud webhook | Your own access token | `config.toml` |+| IRC | Two-way | Persistent socket | Your own server and nick | `config.toml` |+| Signal | Two-way | signal-cli REST events | Your own linked signal-cli account | `config.toml` |+| Mattermost | Two-way | WebSocket | Your own bot token | `config.toml` |+| QQ | Two-way | WebSocket | Your own bot credentials | `config.toml` |+| Linq | Two-way (SMS) | Webhook | Your own API token | `config.toml` |+| Email | Two-way | IMAP IDLE and SMTP | Your own mailbox credentials | Yes |WhatsApp also has an experimental peer-to-peer variant behind the `whatsapp-web` feature. Channels that use a webhook receive messages by HTTP push, so they need an HTTPS endpoint that the provider can reach.diff --git a/docs/gitbooks/en/features/chat.md b/docs/gitbooks/en/features/chat.mdindex 65efcc7be5..88ab6e75e7 100644--- a/docs/gitbooks/en/features/chat.md+++ b/docs/gitbooks/en/features/chat.md@@ -45,12 +45,12 @@ An assistant turn has copy, regenerate, thumbs up or down (remembered), read aloThe agent can stop for four reasons, all shown inline:-| Stop | What you see |-| --- | --- |-| Approval | A card naming the tool and a redacted one-line summary. Approve once, always allow that tool, or deny. See [Approval gate](approval-gate.md). |-| Permission | A connector or provider needs authorizing. The card asks for exactly the fields that provider needs. |-| Clarification | The agent asks a direct question and waits. |-| Plan review | A proposed plan. Approve it, reject it, or ask for a revision with feedback. |+| Stop | What you see |+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |+| Approval | A card naming the tool and a redacted one-line summary. Approve once, always allow that tool, or deny. See [Approval gate](approval-gate.md). |+| Permission | A connector or provider needs authorizing. The card asks for exactly the fields that provider needs. |+| Clarification | The agent asks a direct question and waits. |+| Plan review | A proposed plan. Approve it, reject it, or ask for a revision with feedback. |A background or scheduled turn has nobody to ask. Approvals raised outside a live chat collect in a deck you can decide later. Undecided requests are denied after ten minutes.@@ -84,14 +84,14 @@ after reload; dictation sends text only.## Keyboard-| Shortcut | Action |-| --- | --- |-| `⌘K` / `⌘P` | Command palette |-| `⌘N` | New conversation |-| `⌘F` | Find in this conversation |-| `⌘B` | Toggle the sidebar |-| `⌘,` | Settings |-| `⌘/` or `?` | Shortcut sheet |+| Shortcut | Action |+| ----------- | ------------------------- |+| `⌘K` / `⌘P` | Command palette |+| `⌘N` | New conversation |+| `⌘F` | Find in this conversation |+| `⌘B` | Toggle the sidebar |+| `⌘,` | Settings |+| `⌘/` or `?` | Shortcut sheet |## Not here yet