-
-
-
-
diff --git a/docs/tinyagents-migration-spec.md b/docs/tinyagents-migration-spec.md
new file mode 100644
index 000000000..db35c502d
--- /dev/null
+++ b/docs/tinyagents-migration-spec.md
@@ -0,0 +1,726 @@
+# TinyAgents Migration Spec
+
+Status: draft migration backlog
+
+TinyAgents source reviewed: `tinyhumansai/tinyagents` `origin/main` at
+`8f226f1`, crate version `1.1.0`.
+
+OpenHuman already depends on `tinyagents = "1.1"` and already routes the live
+agent turn through `src/openhuman/tinyagents/`. This spec is not a proposal to
+add TinyAgents. It is a todo list for moving the rest of OpenHuman's generic
+agent runtime behavior onto TinyAgents primitives while keeping OpenHuman-owned
+product semantics in OpenHuman.
+
+## Goal
+
+Use TinyAgents as the generic runtime for:
+
+- model/provider abstraction and model selection
+- tools and tool schemas
+- middleware around model/tool calls
+- streaming, events, traces, and replayable run status
+- token usage and cost rollups
+- state graphs, fanout, reducers, checkpoints, and interrupts
+- sub-agent recursion, steering, cancellation, and reusable sessions
+- deterministic testkit coverage for the runtime seams
+
+OpenHuman should continue to own:
+
+- desktop product UX and Tauri/RPC boundaries
+- user/workspace config, credentials, keychain, and approval records
+- OpenHuman memory stores, thread transcripts, run ledgers, and controllers
+- security policy, sandboxing, tool permission tiers, and workspace roots
+- product-specific built-in agents, prompts, MCP setup, Composio, channels, and
+ native tools
+- compatibility with existing JSON-RPC method names and persisted state
+
+## Sources Reviewed
+
+TinyAgents SDK:
+
+- `src/lib.rs`
+- `src/harness/*`
+- `src/graph/*`
+- `src/registry/*`
+- `src/language/*`
+- `src/repl/*`
+- `docs/modules/harness/*.md`
+- `docs/modules/graph/*.md`
+- `docs/modules/registry/*.md`
+- `docs/modules/expressive-language/README.md`
+- `docs/modules/repl-language/README.md`
+- examples: `agent_loop_tools`, `orchestrator_subagents`, `durable_graph`,
+ `openai_graph_agent`, `openai_self_blueprint`
+
+OpenHuman Rust core:
+
+- `src/openhuman/tinyagents/*`
+- `src/openhuman/agent/**`
+- `src/openhuman/agent_orchestration/**`
+- `src/openhuman/agent_registry/**`
+- `src/openhuman/tools/**`
+- `src/openhuman/inference/**`
+- `src/openhuman/cost/**`
+- `src/openhuman/context/**`
+- `src/openhuman/approval/**`
+- `src/openhuman/security/**`
+- `src/openhuman/mcp_registry/**`
+- `src/core/event_bus/**`
+- `src/core/all.rs`
+- `gitbooks/developing/architecture/agent-harness.md`
+
+## Current Adoption Inventory
+
+Already done or partially done:
+
+- `Cargo.toml` pins `tinyagents = "1.1"` with default features only.
+- `src/openhuman/tinyagents/mod.rs` registers OpenHuman `Provider` and `Tool`
+ adapters on `tinyagents::harness::runtime::AgentHarness`.
+- `ProviderModel` maps OpenHuman `ChatRequest`/`ChatResponse` into
+ `tinyagents::harness::model::{ModelRequest, ModelResponse, ModelStream}`.
+- `ToolAdapter` and `SharedToolAdapter` map OpenHuman tools into
+ `tinyagents::harness::tool::Tool`.
+- `OpenhumanEventBridge` maps TinyAgents `AgentEvent` into `AgentProgress` and
+ the global cost tracker.
+- `StopHookMiddleware`, `ContextCompressionMiddleware`, and
+ `MessageTrimMiddleware` are already used on the TinyAgents path.
+- `SqlRunLedgerCheckpointer` implements TinyAgents `Checkpointer` on top of the
+ OpenHuman session DB because TinyAgents' `sqlite` feature conflicts with the
+ current `rusqlite` native-link version.
+- `run_parallel_fanout` uses `GraphBuilder`, reducers, command routing, and a
+ fan-in barrier for reusable concurrent fanout.
+- `model_council`, `workflow_runs`, `agent_teams`, and
+ `tinyagents/delegation.rs` already use TinyAgents graphs.
+- Built-in agents already have `graph.rs` selectors, but most return
+ `AgentGraph::Default`.
+
+Important current gaps:
+
+- OpenHuman still has separate registries for agents, tools, MCP tools, model
+ providers, controllers, cost, and event bus projections.
+- Tool safety metadata exists in OpenHuman traits but is not fully expressed as
+ TinyAgents tool safety/runtime metadata.
+- Cost/usage is still converted through a bridge, not an end-to-end TinyAgents
+ usage/cost journal.
+- Event streams are mirrored into `AgentProgress`, but TinyAgents event journals
+ and status stores are not the canonical durable inspection surface.
+- Provider model profiles, model resolution, and fallback remain primarily in
+ OpenHuman inference/router logic.
+- Sub-agent lifecycle, durable state, worker threads, and wait/abort controls
+ still live in OpenHuman orchestration stores.
+
+Some todos below are local adapter work. Others require upstream TinyAgents SDK
+extensions first. In particular, the SDK has a strong tool/runtime boundary
+today (`ToolSchema`, `ToolExecutionContext`, middleware hooks), but OpenHuman's
+full tool safety metadata is richer than the current SDK schema. Durable task
+storage is another SDK gap: TinyAgents exposes an `InMemoryTaskStore`, while
+OpenHuman needs restart-safe SQL/JSON ledgers.
+
+## Migration Rules
+
+- Keep every product-facing JSON-RPC contract stable unless a migration plan is
+ written next to the code change.
+- Do not bypass OpenHuman approval, security policy, sandbox, workspace root, or
+ credential boundaries by adopting a generic TinyAgents tool API.
+- Prefer adapters first, then flip ownership once tests prove parity.
+- Preserve existing transcript and run-ledger compatibility. TinyAgents may
+ become the internal runtime without changing persisted public records in the
+ same PR.
+- Every migration task needs unit coverage plus at least one JSON-RPC or
+ harness-level e2e when behavior crosses controller, tool, provider, or graph
+ boundaries.
+
+## Phase 0 - Baseline And Drift Control
+
+- [x] Add a version/feature compatibility note to the OpenHuman architecture doc.
+ - OpenHuman files: `gitbooks/developing/architecture/agent-harness.md`,
+ `Cargo.toml`.
+ - TinyAgents components: crate features `default`, `openai`, `sqlite`, `repl`.
+ - Acceptance: document why default features are used, why TinyAgents `sqlite`
+ is disabled, and which OpenHuman adapters replace feature-gated SDK
+ providers.
+ - **Done:** added "TinyAgents crate: features & compatibility" section to
+ agent-harness.md (default-only, `openai`/`sqlite`/`repl` rationale, adapter
+ map) + fixed stale `council_graph.rs`/`member_graph.rs` links.
+
+## Phase 1 - Tools
+
+- [~] Make OpenHuman tool metadata round-trip into TinyAgents tool metadata.
+ - OpenHuman files: `src/openhuman/tools/traits.rs`,
+ `src/openhuman/tinyagents/tools.rs`, `src/openhuman/tinyagents/convert.rs`.
+ - TinyAgents components: `harness::tool::{ToolSchema, ToolFormat,
+ ToolExecutionContext, ToolResult}`.
+ - Migrate: permission level, external effect, generated runtime context,
+ timeout policy, concurrency safety, result-size cap, display label/detail,
+ markdown support.
+ - Acceptance: a TinyAgents tool call has enough metadata for middleware to
+ enforce approval, security, timeout, concurrency, truncation, and display
+ behavior without re-querying OpenHuman trait methods ad hoc.
+ - **SDK gap + side-lookup adapter:** crate `ToolSchema` carries only
+ name/description/parameters/format — it has **no** metadata/extension map and
+ `ToolExecutionContext` is run-scoped, so none of OpenHuman's safety/runtime
+ fields have a crate home. The adopted pattern is a shared
+ `name → Arc` lookup the runner builds from `tool_sets`; middleware
+ calls the (often args-aware) trait methods live. Landed uses of it:
+ `ApprovalSecurityMiddleware` reads `external_effect_with_args`;
+ `ToolOutputMiddleware` now honors each tool's own `max_result_size_chars()`
+ (was a flat hardcoded budget). Remaining fields (timeout, concurrency,
+ display, generated context) can ride the same lookup as their middlewares
+ land; full crate round-trip is blocked pending an SDK `ToolSchema` extension
+ map.
+
+- [x] Move unknown-tool recovery into a reusable middleware or tool policy layer.
+ - Current shim: `UNKNOWN_TOOL_SENTINEL` in `src/openhuman/tinyagents/tools.rs`.
+ - TinyAgents components: `ToolRegistry`, `ToolMiddleware`,
+ `AgentEvent::ToolStarted/ToolCompleted`, repairable tool results.
+ - Acceptance: hallucinated tool names remain recoverable, sub-agent wording is
+ preserved, and TinyAgents event stream records the original requested tool
+ name without exposing the sentinel as a model-visible tool.
+ - **Done:** `UnknownToolRewriteMiddleware` (`before_tool`) rewrites a call to
+ an unadvertised tool onto the sentinel at the tool boundary, before the
+ harness resolves it — removing the `valid_tools` plumbing from `ProviderModel`
+ (`with_valid_tools`, the field, and the `response_to_model_response` rewrite
+ all deleted). Sub-agent vs top-level wording is preserved by the sentinel
+ handler; the sentinel is still never advertised. SDK gaps: no
+ "tool-not-found → repair" hook (the sentinel handler must stay), and no
+ dedicated unknown-tool `AgentEvent` variant (recording the original name in
+ the crate event stream would need a manual `ToolStarted` — deferred).
+
+- [x] Route approval and security through TinyAgents middleware.
+ - Current OpenHuman files: `src/openhuman/approval/*`,
+ `src/openhuman/security/*`, `src/openhuman/tinyagents/tools.rs`.
+ - TinyAgents components: `ToolMiddleware`, `ToolExecutionContext`,
+ tool safety metadata.
+ - Acceptance: approval checks happen in `before_tool`/`wrap_tool`, emit typed
+ events, preserve audit rows, and return model-consumable denial results.
+ - **Done:** `ApprovalSecurityMiddleware` (`tinyagents/middleware.rs`, a
+ `wrap_tool` middleware) replaces the inline approval block in
+ `execute_openhuman_tool`. Denials short-circuit with a model-consumable
+ result; approved external-effect calls now record a terminal audit row
+ (`record_execution`) the old path dropped. Typed approval events still ride
+ `DomainEvent` (the crate `AgentEvent` enum has no approval variant — SDK gap).
+ Tool-*internal* security (path/command `live_policy`) stays per-tool by
+ design. Follow-ups: channel permission-ceiling threading; per-tool metadata
+ side-lookup (Task C).
+
+- [ ] Use TinyAgents bounded-concurrent tool execution where safe.
+ - OpenHuman files: `src/openhuman/tools/traits.rs`,
+ `src/openhuman/tinyagents/tools.rs`.
+ - TinyAgents components: graph `Send`, graph fanout, or harness tool
+ execution policy.
+ - Acceptance: read-only/concurrency-safe tool batches can run in parallel
+ with deterministic result ordering and identical transcript semantics.
+
+## Phase 2 - Models And Providers
+
+- [ ] Register OpenHuman inference providers as TinyAgents model registry entries.
+ - OpenHuman files: `src/openhuman/inference/provider/*`,
+ `src/openhuman/inference/model_ids.rs`, `src/openhuman/tinyagents/model.rs`.
+ - TinyAgents components: `harness::model::{ChatModel, ModelRegistry,
+ ModelProfile, CapabilitySet, ModelRequest, ModelResponse}`.
+ - Acceptance: every workload route (`agentic`, `reasoning`, `coding`,
+ `memory`, `subconscious`, etc.) can resolve to a TinyAgents model entry
+ while retaining OpenHuman provider strings and config compatibility.
+
+- [ ] Translate OpenHuman provider capability data into TinyAgents model profiles.
+ - OpenHuman files: `src/openhuman/inference/provider/traits.rs`,
+ `src/openhuman/inference/provider/factory.rs`,
+ `docs/inference-provider-catalog.md`.
+ - TinyAgents components: `ModelProfile`, `CapabilitySet`, registry model
+ catalog.
+ - Acceptance: context window, tool calling, streaming, vision, structured
+ output, reasoning, local/cloud source, and provider-family metadata are
+ available before dispatch.
+
+- [ ] Move model fallback and retry policy to TinyAgents policy/middleware.
+ - OpenHuman files: `src/openhuman/inference/provider/reliable.rs`,
+ `src/openhuman/inference/provider/router.rs`,
+ `src/openhuman/tinyagents/mod.rs`.
+ - TinyAgents components: `RunPolicy`, `RetryPolicy`, `FallbackPolicy`,
+ `ModelFallbackMiddleware`, `AgentEvent::RetryScheduled`,
+ `AgentEvent::FallbackSelected`.
+ - Acceptance: OpenHuman provider retry does not double-retry under
+ TinyAgents, fallback events are typed, and tests cover transient 429/5xx,
+ config rejection, and billing exhaustion.
+
+- [ ] Preserve provider-specific metadata in the TinyAgents message model.
+ - OpenHuman files: `src/openhuman/inference/provider/traits.rs`,
+ `src/openhuman/tinyagents/convert.rs`,
+ `src/openhuman/tinyagents/model.rs`.
+ - TinyAgents components: `ContentBlock`, `AssistantMessage`, provider
+ metadata, tool-call ids.
+ - Acceptance: Gemini thought signatures, reasoning content, native tool-call
+ ids, cached tokens, and raw provider metadata survive multi-turn history.
+
+## Phase 3 - Middleware
+
+- [ ] Convert OpenHuman turn cross-cuts into named TinyAgents middleware.
+ - Current OpenHuman surfaces: stop hooks, approval gate, security policy,
+ output caps, context compression, memory injection, tool allowlists,
+ cost/usage, prompt cache stability, event bridge.
+ - TinyAgents components: `Middleware`, `ModelMiddleware`, `ToolMiddleware`,
+ `MiddlewareStack`, `RunContext`.
+ - Acceptance: each cross-cut has a stable middleware name, tests for ordering,
+ emitted events, and explicit interaction with streaming/retry/fallback.
+
+- [ ] Add OpenHuman policy middleware for dynamic tool exposure.
+ - OpenHuman files: `src/openhuman/agent_registry/*`,
+ `src/openhuman/agent/harness/subagent_runner/**`,
+ `src/openhuman/tools/user_filter.rs`.
+ - TinyAgents components: `before_model`, `before_tool`, `ToolRegistry`.
+ - Acceptance: agent `tool_allowlist`, `tool_denylist`, sub-agent tool scope,
+ MCP tool visibility, and channel permission ceilings are enforced through
+ middleware rather than scattered pre-filtering.
+
+- [ ] Add prompt/cache-layout middleware tests.
+ - OpenHuman files: `src/openhuman/context/*`,
+ `src/openhuman/agent/harness/session/turn/core.rs`,
+ `src/openhuman/tinyagents/summarize.rs`.
+ - TinyAgents components: `CachePolicy`, `CacheLayoutEvent`,
+ `ContextCompressionMiddleware`, `MessageTrimMiddleware`.
+ - Acceptance: system prompt prefix remains stable across later turns; volatile
+ memory, timestamps, tool results, and steering messages land in the tail.
+
+## Phase 4 - Events, Status, And Observability
+
+- [ ] Make TinyAgents event journals the canonical internal run event stream.
+ - OpenHuman files: `src/openhuman/tinyagents/observability.rs`,
+ `src/core/event_bus/*`, `src/openhuman/notifications/*`,
+ `src/openhuman/session_db/run_ledger/*`.
+ - TinyAgents components: `HarnessEventJournal`, `HarnessStatusStore`,
+ `GraphEventJournal`, `GraphStatusStore`, `AgentEvent`, `GraphEvent`.
+ - Acceptance: UIs can reconstruct a running or completed agent turn from
+ persisted TinyAgents events without relying only on transient
+ `AgentProgress`.
+
+- [ ] Bridge TinyAgents events into `DomainEvent` as a compatibility projection.
+ - OpenHuman files: `src/core/event_bus/events.rs`,
+ `src/openhuman/agent/bus.rs`, `src/openhuman/tinyagents/observability.rs`.
+ - Acceptance: existing subscribers continue to receive `DomainEvent`, but new
+ code reads TinyAgents events/status first.
+
+- [ ] Persist graph run status and checkpoint metadata in OpenHuman run ledger.
+ - OpenHuman files: `src/openhuman/tinyagents/checkpoint.rs`,
+ `src/openhuman/session_db/run_ledger/store.rs`,
+ `src/openhuman/agent_orchestration/**`.
+ - TinyAgents components: `Checkpoint`, `CheckpointMetadata`,
+ `GraphRunStatus`, `GraphObservation`.
+ - Acceptance: command center, workflow runs, delegation, and team runs can
+ list checkpoints, current node/task status, and replay offsets from one DB
+ source.
+
+- [~] Export graph topology for debugging and UI inspection.
+ - OpenHuman files: built-in `graph.rs` files, `agent_orchestration/*/graph.rs`,
+ `model_council/graph.rs`.
+ - TinyAgents components: `GraphTopology`, `to_json`, `to_mermaid`,
+ validation report.
+ - Acceptance: every custom OpenHuman graph has a debug endpoint or test
+ snapshot that exports topology and validates missing nodes/routes.
+ - **Foundation landed:** new `tinyagents/topology.rs` — `GraphTopologyReport`
+ (mermaid + JSON + validation errors/warnings), `describe()`, and
+ `all_graph_topologies()`. Pattern: each graph exposes a `build_*_graph`
+ (structure) reused by both the runner and a `*_topology()` that builds it
+ with no-op stub closures and returns `CompiledGraph::topology()`. Done for
+ `agent_teams:member`. Follow-ups (same pattern): `delegation` (injected
+ `run_stage` — clean) and `workflow_runs` scheduler (needs a small refactor —
+ its node closures capture engine locals). Fan-outs (council,
+ `run_parallel_fanout`) are the dispatch→N→collect pattern, not a fixed
+ topology. Debug endpoint = call `all_graph_topologies()` (RPC wiring is a
+ thin follow-up).
+
+## Phase 5 - Usage, Cost, And Budgets
+
+- [~] Replace bridge-only usage accounting with TinyAgents usage records.
+ - OpenHuman files: `src/openhuman/cost/*`,
+ `src/openhuman/tinyagents/observability.rs`,
+ `src/openhuman/inference/provider/traits.rs`.
+ - TinyAgents components: `harness::usage::{Usage, UsageTotals}`,
+ `harness::cost::CostTotals`, `AgentEvent::UsageRecorded`.
+ - Acceptance: input, output, cached input, reasoning, image/audio, embedding,
+ tool/model call counts, and estimated/provider-reported source are recorded
+ in normalized records.
+ - **Partial (real bug fixed):** the bridge hardcoded `charged_amount_usd: 0.0`
+ and `ProviderModel` dropped cached tokens, so EVERY tinyagents turn recorded
+ **$0 cost**. Now `model.rs` carries `cached_input_tokens` via crate
+ `Usage.cache_read_tokens`, and the bridge estimates per-call cost from
+ catalogued per-MTok rates (`cost::catalog::estimate_cost_usd`). Remaining:
+ reasoning/image/audio/embedding token fields, model/tool call counts, and an
+ explicit estimated-vs-provider-charged `cost_source` tag on `TokenUsage`
+ (provider-charged preservation needs an out-of-band carry — crate `Usage` has
+ no USD field).
+
+- [~] Move budget checks to pre-call TinyAgents middleware.
+ - OpenHuman files: `src/openhuman/cost/tracker.rs`,
+ `src/openhuman/tinyagents/mod.rs`.
+ - TinyAgents components: `RunPolicy`, cost middleware, `before_model`,
+ `before_tool`.
+ - Acceptance: per-run, per-thread, daily, and monthly budgets can warn or
+ fail before spend where enough data exists, then reconcile after provider
+ usage is known.
+ - **Partial:** `CostBudgetMiddleware` (`before_model`) fails the run before a
+ model call when the global daily/monthly budget is already exceeded
+ (`CostTracker::check_budget`), and logs on the warning threshold. Self-gating
+ on `config.enabled`; previously daily/monthly enforcement was dormant on the
+ tinyagents path. Remaining: per-run/per-thread budgets (need new
+ `CostConfig` fields + thread-id threading into the runner) and projecting the
+ *next* call's cost pre-spend (needs an input-token estimate).
+
+- [ ] Add cost rollup across sub-agents and graphs.
+ - OpenHuman files: `src/openhuman/agent_orchestration/**`,
+ `src/openhuman/cost/global.rs`.
+ - TinyAgents components: run ids, parent/root run lineage,
+ `SubAgentStarted`, `SubAgentCompleted`, graph child runs.
+ - Acceptance: parent run totals include child agent/model/tool usage without
+ double counting dashboard totals.
+
+## Phase 6 - Graph Runtime And Orchestration
+
+- [ ] Convert remaining ad hoc control loops into explicit TinyAgents graphs.
+ - Candidate OpenHuman files: `src/openhuman/agent_orchestration/*`,
+ `src/openhuman/subconscious/*`, `src/openhuman/cron/*`,
+ `src/openhuman/learning/*`, `src/openhuman/tools/ops.rs`.
+ - TinyAgents components: `GraphBuilder`, `Command`, conditional routing,
+ reducers, `Send`, barriers, recursion policy.
+ - Acceptance: every long-running multi-step orchestration has named nodes,
+ route tests, recursion bounds, cancellation checks, and topology export.
+
+- [ ] Replace simple fanout helpers with graph `Send` where payload-specific
+ fanout matters.
+ - Current helper: `src/openhuman/tinyagents/orchestration.rs`.
+ - TinyAgents components: `Command::send`, `GraphInput`, `NodeContext::send_arg`.
+ - Acceptance: map-reduce style flows can schedule multiple invocations of the
+ same node with distinct payloads instead of materializing one node per item.
+
+- [ ] Make `spawn_parallel_agents` a first-class TinyAgents graph tool.
+ - Current OpenHuman files:
+ `src/openhuman/agent_orchestration/tools/spawn_parallel_agents.rs`,
+ `src/openhuman/tinyagents/orchestration.rs`,
+ `src/openhuman/agent_orchestration/worktree.rs`,
+ `src/openhuman/agent_orchestration/workflow_runs/engine.rs`.
+ - Current behavior: validates at least two tasks, checks parent context,
+ enforces `max_parallel_tools`, resolves `AgentDefinition`s, enforces the
+ parent `subagents.allowlist`, optionally creates per-worker git worktrees,
+ fans workers out through `run_parallel_fanout`, collects results in input
+ order, emits `DomainEvent` + `AgentProgress`, detects stale parent file
+ reads and cross-worker changed-file overlaps, and returns a structured
+ `parallel_agents` JSON payload.
+ - TinyAgents components: `GraphBuilder`, `Command`, `Send`,
+ `NodeContext::send_arg`, `ChannelSet`/reducers, `GraphEventSink`,
+ `SubAgentNode` or OpenHuman `run_subagent` adapter, `RecursionPolicy`,
+ `RunPolicy`, `CancellationToken`.
+ - Required migration shape:
+ - `validate` node: parse tasks, enforce min/max count, parent context,
+ allowlist, toolkit requirements, and worktree preflight.
+ - `dispatch` node: use `Send` to schedule one worker invocation per task
+ instead of generating one static worker node per task.
+ - `worker` node: run the OpenHuman sub-agent build pipeline with inherited
+ model/tool/security policy, optional `worktree_action_dir`, child task id,
+ and bounded turn/output budgets.
+ - `collect` reducer: aggregate successes, failures, elapsed time,
+ iterations, worktree status, changed files, and stale read markers in
+ deterministic task order.
+ - `finalize` node: emit compatibility `DomainEvent`/`AgentProgress`
+ projections, overlap warnings, and the existing JSON result shape.
+ - Acceptance: parallel agent runs are checkpointable, cancellable at graph
+ boundaries, bounded by parent policy, observable through TinyAgents graph
+ events/status, compatible with existing `spawn_parallel_agents` tool
+ output, and able to run edit-capable workers in isolated worktrees without
+ silently falling back to shared workspace.
+
+- [ ] Define parallel-agent ownership and scheduling policy explicitly.
+ - OpenHuman files: `src/openhuman/agent_registry/agents/orchestrator/prompt.md`,
+ `src/openhuman/agent_orchestration/tools/spawn_parallel_agents.rs`,
+ `src/openhuman/tools/traits.rs`.
+ - TinyAgents components: graph route metadata, `RunPolicy`, task metadata,
+ tool safety metadata.
+ - Required policy:
+ - The parent must provide disjoint ownership boundaries for write-capable
+ tasks, or the graph rejects/falls back to serial delegation.
+ - Read-only workers may share the parent workspace; write-capable workers
+ should request `isolation = "worktree"`.
+ - Parent and children inherit one root run id for cost/event rollups, but
+ each child gets its own task id and optional worker-thread id.
+ - A child cannot widen tools, model choice, sandbox mode, trusted roots, or
+ budget beyond the parent-granted policy.
+ - Cancellation, steering, and wait/collect must be delivered at graph or
+ harness safe boundaries only.
+ - Acceptance: the orchestrator can ask for parallelism without prompt-only
+ conventions; policy violations become structured graph/tool errors.
+
+- [ ] Make per-agent `graph.rs` selectors real customization points.
+ - OpenHuman files: `src/openhuman/agent_registry/agents/*/graph.rs`,
+ `src/openhuman/agent/harness/agent_graph.rs`.
+ - TinyAgents components: `CompiledGraph`, sub-agent nodes, graph testkit.
+ - Acceptance: at least three agents get bespoke graphs where useful:
+ orchestrator, researcher, and tool_maker are good first candidates.
+
+- [ ] Keep durable orchestration stores OpenHuman-owned until TinyAgents has a
+ durable `TaskStore`.
+ - Current OpenHuman files: `running_subagents.rs`, `workflow_runs`,
+ `agent_teams`, `command_center`, `subagent_sessions`.
+ - TinyAgents limitation: `InMemoryTaskStore` is useful for lifecycle shape but
+ not sufficient for desktop restart/resume.
+ - Acceptance: do not migrate durable SQL/JSON state to TinyAgents in-memory
+ task storage. Use TinyAgents task types as an adapter only.
+
+- [ ] Add graph interrupt/resume for human review points.
+ - OpenHuman files: `src/openhuman/approval/*`,
+ `src/openhuman/agent_orchestration/workflow_runs/*`,
+ `src/openhuman/tinyagents/delegation.rs`.
+ - TinyAgents components: `Interrupt`, `ResumeTarget`, `Command::resume`,
+ checkpoints.
+ - Acceptance: approval/review pauses are durable graph interrupts where the
+ run can resume from the exact checkpoint after user action.
+
+## Phase 7 - Sub-Agents, Steering, And Recursion
+
+- [ ] Represent `spawn_subagent`, `steer_subagent`, `wait_subagent`, and
+ follow-ups as TinyAgents steering commands plus OpenHuman projections.
+ - OpenHuman files: `src/openhuman/agent_orchestration/tools.rs`,
+ `src/openhuman/agent_orchestration/running_subagents.rs`,
+ `src/openhuman/agent/harness/subagent_runner/**`.
+ - TinyAgents components: `SteeringCommand`, `SteeringHandle`,
+ `SubAgentSession`, `SubAgentTool`, recursion depth events.
+ - Acceptance: mid-flight messages are delivered only at safe loop boundaries,
+ accepted/rejected steering emits events, and tool/model allowlists can only
+ narrow from parent policy.
+
+- [ ] Reconcile OpenHuman spawn depth with TinyAgents recursion policy.
+ - OpenHuman files: `src/openhuman/agent/harness/spawn_depth_context.rs`,
+ `src/openhuman/agent/harness/subagent_runner/**`.
+ - TinyAgents components: `RecursionPolicy`, `RecursionStack`,
+ `SubAgentDepth`.
+ - Acceptance: there is one authoritative recursion cap and one error shape,
+ with compatibility conversion for existing UI/JSON-RPC responses.
+
+- [ ] Keep OpenHuman's sub-agent build pipeline as product logic.
+ - Product-owned pieces: agent definition resolution, prompt assembly, memory
+ context, worker-thread mirroring, handoff cache, tool filtering, provider
+ routing, sandbox scope.
+ - TinyAgents components to adopt beneath it: `SubAgentSession`,
+ `ToolExecutionContext`, event lineage, cancellation, usage/cost rollup.
+ - Acceptance: use TinyAgents for execution and lineage without flattening
+ OpenHuman's agent registry semantics into generic SDK defaults.
+
+## Phase 8 - Registry And Capability Catalog
+
+- [ ] Build a `CapabilityRegistry` projection from OpenHuman registries.
+ - OpenHuman files: `agent_registry`, `tools`, `mcp_registry`, `inference`,
+ `cost`, `approval`, `security`, controller registry in `src/core/all.rs`.
+ - TinyAgents components: `CapabilityRegistry`, `ComponentId`,
+ `ComponentKind`, model catalog, graph/tool/agent/store/middleware entries.
+ - Acceptance: OpenHuman models, tools, agents, graphs, stores, and middleware
+ can be looked up through one policy-aware capability projection.
+
+- [ ] Add registry diagnostics for duplicate names and unsafe aliases.
+ - OpenHuman files: `src/openhuman/tools/generated.rs`,
+ `mcp_registry`, `composio`, `agent_registry`.
+ - TinyAgents components: component names, `ToolRegistry`, diagnostics.
+ - Acceptance: duplicate tool names, provider-specific aliases, MCP names, and
+ generated tool names fail closed before model dispatch.
+
+- [ ] Use TinyAgents model catalog shape for local provider catalog snapshots.
+ - OpenHuman files: `docs/inference-provider-catalog.md`,
+ `src/openhuman/inference/presets.rs`,
+ `src/openhuman/inference/provider/factory.rs`.
+ - TinyAgents components: registry model catalog, local snapshots, price and
+ context metadata.
+ - Acceptance: model picker, router, budget estimator, and capability filter
+ read one normalized catalog projection.
+
+## Phase 9 - Memory, Retrieval, Embeddings, And Context
+
+- [ ] Adapt OpenHuman memory/retrieval to TinyAgents retriever interfaces.
+ - OpenHuman files: `memory`, `memory_search`, `memory_tree`,
+ `agent/memory_loader.rs`, `context/*`.
+ - TinyAgents components: `EmbeddingModel`, `Retriever`, `VectorStore`,
+ `ScoredDoc`, context events.
+ - Acceptance: the agent harness can load retrieval context through a
+ TinyAgents retriever facade while OpenHuman stores remain authoritative.
+
+- [ ] Move context compaction provenance into TinyAgents events.
+ - OpenHuman files: `context/README.md`, `tinyagents/summarize.rs`,
+ `agent/harness/payload_summarizer.rs`.
+ - TinyAgents components: `SummaryRecord`, `Compressed` events, cache layout
+ events.
+ - Acceptance: every summary records source ids, before/after token estimates,
+ policy version, and whether stable prompt prefix was preserved.
+
+- [ ] Normalize embedding usage/cost records.
+ - OpenHuman files: `embeddings`, `memory_sync`, `cost`.
+ - TinyAgents components: embedding usage fields, model catalog pricing.
+ - Acceptance: embedding calls contribute usage and cost with provider/model,
+ dimensions, vector count, and source.
+
+## Phase 10 - Dead Code And TinyAgents Re-Expression Audit
+
+Do not delete these blindly. Treat this as an audit list for code that is dead,
+vestigial, or generic runtime behavior now expressible through TinyAgents
+harness/graph primitives. Delete only after call-site search, compatibility
+assessment, and migration coverage are complete.
+
+- [ ] Audit `src/openhuman/agent/harness/engine/*`.
+ - Current role: surviving seams from the retired in-house turn loops:
+ `CheckpointStrategy`, `ProgressReporter`, and `TurnProgress`.
+ - TinyAgents expression: `RunPolicy`, `AgentEvent`, `GraphEvent`,
+ `EventSink`, `HarnessStatusStore`, cap/stop middleware.
+ - Candidate outcome: move max-iteration and progress projection into
+ TinyAgents middleware/events, then delete `engine/*` if no product-specific
+ compatibility seam remains.
+
+- [ ] Audit `src/openhuman/agent/harness/agent_graph.rs` and built-in
+ `agent_registry/agents/*/graph.rs` default selectors.
+ - Current role: per-agent graph hook, but most built-ins return
+ `AgentGraph::Default`.
+ - TinyAgents expression: a registry of `CompiledGraph`/graph factories keyed
+ by agent id, with default graph supplied by the runtime and custom graphs
+ registered only where they differ.
+ - Candidate outcome: replace dozens of boilerplate default `graph.rs` files
+ with registry defaults, keeping files only for agents with custom graphs.
+
+- [~] Audit stale architecture references to removed in-house graph/loop code.
+ - Current files: `gitbooks/developing/architecture/agent-harness.md`,
+ `src/openhuman/context/README.md`.
+ - Candidate stale names: `src/openhuman/agent_graph/`, `GraphBlueprint`,
+ `run_turn_engine`, `run_tool_call_loop`, `harness/tool_loop.rs`, old
+ context summarizer files.
+ - TinyAgents expression: link to live `src/openhuman/tinyagents/*`,
+ `GraphBuilder`, `AgentHarness`, `ContextCompressionMiddleware`, and
+ graph-export/status surfaces.
+ - Candidate outcome: move historical details into a short "pre-migration
+ history" appendix or remove them from active architecture docs.
+ - **Partial:** flagged the `agent-harness.md` `agent_graph`/`GraphBlueprint`
+ section as HISTORICAL-removed (strong inline callout pointing at the live
+ tinyagents surfaces); fixed `context/README.md` "Used by" line that still
+ referenced the deleted `reduce_before_call`/`ProviderSummarizer`/
+ `SegmentRecapSummarizer`/`unified_compaction_enabled`. Remaining: a sweep of
+ code doc-comments across many `.rs` files that still name `run_turn_engine`,
+ `run_tool_call_loop`, `tool_loop.rs` (comments only — no behavior).
+
+- [ ] Audit `src/openhuman/context/{pipeline,guard,microcompact}.rs`.
+ - Current role: context stats/session-memory bookkeeping plus older
+ compaction concepts; live history reduction moved to
+ `ContextCompressionMiddleware` and `MessageTrimMiddleware`.
+ - TinyAgents expression: context-window middleware, `Compressed` events,
+ cache layout events, `SummaryRecord`, usage/context pressure status.
+ - Candidate outcome: keep only stats/session-memory state that remains
+ OpenHuman-specific; move compression policy/provenance into TinyAgents
+ middleware and delete unused reduction paths.
+
+- [ ] Audit `src/openhuman/agent/harness/payload_summarizer.rs`.
+ - Current role: oversized tool-result compression via a `summarizer`
+ sub-agent with a local circuit breaker.
+ - TinyAgents expression: `ToolMiddleware::after_tool`,
+ `ContextCompressionMiddleware`, `SummaryRecord`, tool artifact/result
+ compaction events.
+ - Candidate outcome: convert to middleware over TinyAgents tool results so
+ the summarizer is no longer a separate OpenHuman-only hook.
+
+- [ ] Audit `src/openhuman/agent_orchestration/running_subagents.rs`.
+ - Current role: bespoke live-task registry layered on TinyAgents
+ `InMemoryTaskStore`, plus watch channels, abort handles, tombstones,
+ task/session lookup, wait, steer, and cancel operations.
+ - TinyAgents expression: `TaskStore`, `SteeringCommand`, `SteeringHandle`,
+ `CancellationToken`, run tree/status store, durable OpenHuman ledger
+ projections.
+ - Candidate outcome: keep OpenHuman durable session/worker-thread records,
+ but collapse transient lifecycle mechanics into TinyAgents task/status
+ primitives once they can represent wait/steer/hard-abort needs.
+
+- [ ] Audit `src/openhuman/agent_orchestration/tools/spawn_parallel_agents.rs`
+ after the graph-tool migration.
+ - Current role: validation, preflight, fanout, worktree setup, event
+ projection, overlap detection, result formatting.
+ - TinyAgents expression: graph nodes (`validate`, `dispatch`, `worker`,
+ `collect`, `finalize`) with `Send` fanout and reducers.
+ - Candidate outcome: keep a thin tool wrapper that invokes the graph and
+ formats the existing JSON payload; move orchestration mechanics into the
+ graph module.
+
+- [ ] Audit hand-rolled `join_all` fanouts that are workflow orchestration, not
+ simple IO batching.
+ - Candidate files from current search: `src/openhuman/mcp_registry/registry.rs`,
+ `src/openhuman/learning/reflection.rs`,
+ `src/openhuman/inference/local/service/ollama_admin/diagnostics.rs`.
+ - TinyAgents expression: only migrate fanouts that need agent/run lineage,
+ checkpointing, policy, cancellation, or graph observability. Leave simple
+ independent IO probes as ordinary Rust concurrency.
+ - Candidate outcome: document why each fanout stays as `join_all` or move it
+ to `run_parallel_fanout` / graph `Send`.
+
+- [ ] Audit tool registry comments and docs that still describe retired
+ direct-loop behavior.
+ - Current files: `src/openhuman/tools/traits.rs`,
+ `src/openhuman/tools/README.md`,
+ `src/openhuman/agent/harness/session/turn/tools.rs`.
+ - TinyAgents expression: `ToolRegistry`, `ToolMiddleware`, graph tool nodes,
+ tool safety metadata, `ToolExecutionContext`.
+ - Candidate outcome: update comments to describe the TinyAgents execution
+ path and delete references to the retired serial `harness::tool_loop`
+ dispatcher once no code path uses it.
+
+## Phase 11 - Testing And Conformance
+
+- [ ] Create a focused parity test matrix for the current TinyAgents route.
+ - OpenHuman files: `src/openhuman/tinyagents/tests.rs`,
+ `tests/agent_harness_e2e.rs`, `tests/agent_tool_loop_raw_coverage_e2e.rs`.
+ - TinyAgents components: `AgentHarness`, `AgentEvent`, `ToolRegistry`,
+ `ModelRegistry`, `MessageTrimMiddleware`, `ContextCompressionMiddleware`.
+ - Acceptance: chat turn, channel turn, sub-agent turn, unknown tool recovery,
+ approval denial, streaming text, streaming tool args, reasoning deltas,
+ early-exit pause, model-call cap, and cost footer all have tests on the
+ TinyAgents path.
+
+- [ ] Add a TinyAgents adapter inventory test.
+ - OpenHuman files: `src/openhuman/tinyagents/mod.rs`,
+ `src/openhuman/tinyagents/tests.rs`.
+ - Acceptance: one test asserts that the shared runner registers model, tools,
+ middleware, event bridge, context compression, stop hooks, and unknown-tool
+ sentinel in the intended order.
+
+- [ ] Port behavior clusters to TinyAgents testkit.
+ - OpenHuman files: `src/openhuman/agent/harness/*_tests.rs`,
+ `tests/agent_*`.
+ - TinyAgents components: harness `testkit`, graph `assert_graph`,
+ `GraphEventRecorder`, mock models/tools.
+ - Acceptance: legacy assertions over loop wording are replaced by assertions
+ over TinyAgents events, checkpoints, graph metadata, and final transcript.
+
+- [ ] Add cross-module e2e tests for graph/sub-agent/model/tool composition.
+ - Candidate tests: workflow run with child sub-agents, delegation with review
+ loop, council fanout, MCP tool call, Composio approval denial, memory
+ retrieval plus summarization.
+ - Acceptance: tests cover default features, `openai`-feature compatible code
+ paths where available, and all-features where dependency constraints allow.
+
+- [ ] Add fuzz-style graph composition tests.
+ - TinyAgents components: graph testkit, reducers, command routing, subgraph
+ nodes, sub-agent fake nodes.
+ - Acceptance: generated small graphs cover direct edges, conditional routes,
+ `Send` fanout, joins, interrupts, recursion caps, and checkpoint resume.
+
+## Suggested Execution Order
+
+1. Confirm version/feature compatibility and SDK-extension gaps.
+2. Move tool safety/approval/security into TinyAgents middleware.
+3. Normalize usage/cost records and parent/child rollups.
+4. Persist TinyAgents event/status journals to the OpenHuman run ledger.
+5. Build the OpenHuman `CapabilityRegistry` projection.
+6. Convert one high-value built-in agent to a bespoke TinyAgents graph.
+7. Adapt memory/retrieval/context surfaces where the TinyAgents interfaces are
+ a good fit.
+8. Audit and remove or re-express dead/vestigial runtime code through
+ TinyAgents harness/graph primitives.
+9. Finish with parity, adapter-inventory, conformance, e2e, and fuzz-style tests.
+
+## Non-Goals For The First Migration Wave
+
+- Do not enable TinyAgents `sqlite` until the `rusqlite` native-link conflict is
+ solved.
+- Do not replace OpenHuman's durable run ledgers with TinyAgents
+ `InMemoryTaskStore`.
+- Do not expose TinyAgents' OpenAI provider directly to product code while
+ OpenHuman provider config, credentials, OAuth, and billing classification are
+ still the product source of truth.
+- Do not remove `DomainEvent` until all existing subscribers have a TinyAgents
+ event/status replacement.
diff --git a/docs/tinyagents-sdk-gaps.md b/docs/tinyagents-sdk-gaps.md
new file mode 100644
index 000000000..c15d6a5a0
--- /dev/null
+++ b/docs/tinyagents-sdk-gaps.md
@@ -0,0 +1,464 @@
+# TinyAgents SDK Gaps
+
+This document lists TinyAgents SDK features that are missing or only partially
+available from the perspective of migrating OpenHuman's Rust agent core onto
+TinyAgents.
+
+Scope:
+
+- Source baseline: local TinyAgents checkout at `6f898fb`.
+- OpenHuman evidence: `src/openhuman/tinyagents/*`,
+ `src/openhuman/agent/*`, `src/openhuman/cost/*`, and
+ `src/openhuman/tokenjuice/*`.
+- This is not the OpenHuman migration plan. That plan lives in
+ `docs/tinyagents-migration-spec.md`.
+- Items here are upstream TinyAgents implementation candidates.
+- Tests should be implemented last, after the API and storage surfaces settle.
+
+## Executive Summary
+
+TinyAgents already has strong primitives for harness runs, graph execution,
+middleware, event streams, model profiles, usage/cost accounting, checkpointers,
+and sub-agent orchestration. The biggest remaining gaps are production-grade
+policy metadata, durable orchestration stores, richer streaming events,
+recoverable tool-call behavior, graph fanout ergonomics, and SDK-owned adapters
+for the lifecycle controls OpenHuman currently implements around the SDK.
+
+OpenHuman can migrate more of `src/openhuman/agent/` if TinyAgents grows these
+features:
+
+- Rich tool metadata for safety, permissions, timeouts, retries, idempotency,
+ side effects, workspace access, and approval requirements.
+- A recoverable unknown-tool policy so invalid model tool calls do not always
+ abort the run.
+- First-class reasoning and tool-call argument streaming events.
+- Durable `TaskStore` and event/status stores with replay, lineage, cursors,
+ redaction, and cancellation semantics.
+- Storage compatibility options for SQLite users that already depend on a
+ different `rusqlite` / `libsqlite3-sys` version.
+- Higher-level map/reduce and parallel-agent orchestration helpers on top of
+ graph `Send`.
+- Budget enforcement and provider/model catalog metadata that can drive
+ preflight, fallback, and reconciliation.
+- Conformance suites for providers, tools, middleware, graph stores, and
+ checkpointers.
+
+## Backlog
+
+### 1. Rich Tool Policy Metadata
+
+Status: partially present.
+
+TinyAgents has `ToolSchema { name, description, parameters, format }` and
+`ToolExecutionContext { run_id, thread_id, depth, max_turn_output_tokens,
+events }`. That is enough for model-visible tool calls, but not enough for
+OpenHuman's approval gate, command classifier, workspace policy, sandbox
+handoff, or tool-result budgeting.
+
+OpenHuman currently keeps that metadata outside TinyAgents in domain tool
+registries and adapters. That means the SDK cannot make fail-closed decisions
+about whether a tool should be exposed, approved, retried, timed out, or allowed
+to touch the filesystem/network.
+
+Implement:
+
+- Add SDK-owned tool metadata, probably `ToolPolicy` or `ToolSafety`.
+- Represent side effects: `read_only`, `writes_files`, `network`,
+ `installs_dependencies`, `destructive`, `external_service`, `payment`.
+- Represent runtime requirements: timeout, retry policy, idempotency,
+ cancellation behavior, sandbox mode, max result bytes, streaming support.
+- Represent access requirements: workspace root policy, trusted roots,
+ credentials needed, user approval required, background-safe vs interactive.
+- Add helper middleware for policy enforcement before model-visible exposure and
+ before execution.
+
+Acceptance criteria:
+
+- Callers can build a dynamic per-run tool set from policy metadata.
+- Unknown or under-classified tools fail closed by default.
+- Tool policy can be serialized for registry introspection and audit logs.
+- Existing plain `ToolSchema` remains supported as the model-visible projection.
+
+### 2. Recoverable Unknown Tool Calls
+
+Status: missing.
+
+TinyAgents currently returns `TinyAgentsError::ToolNotFound` when the model calls
+an unregistered tool. OpenHuman's legacy loop treated this as a recoverable tool
+result and let the model correct itself. The TinyAgents adapter now rewrites
+unknown calls to an internal `__openhuman_unknown_tool__` sentinel so the loop can
+continue.
+
+Implement:
+
+- Add `UnknownToolPolicy`.
+- Suggested variants:
+ - `Fail`: current behavior.
+ - `ReturnToolError`: inject a tool result with the original requested name.
+ - `Rewrite { tool_name }`: adapter-controlled compatibility mode.
+ - `RepairWithMiddleware`: allow a tool middleware to transform the call.
+- Preserve the original requested tool name, original arguments, and model call
+ id in events and observations.
+
+Acceptance criteria:
+
+- OpenHuman can delete `UNKNOWN_TOOL_SENTINEL`.
+- Harness events distinguish "tool not found" from "tool executed and failed".
+- The policy can vary by run, sub-agent, or tool allowlist.
+
+### 3. Reasoning And Tool-Argument Streaming
+
+Status: partially present.
+
+TinyAgents has `MessageDelta { text, tool_call }`, and `ModelDelta` events carry
+that delta. OpenHuman providers also emit reasoning/thinking deltas and
+tool-call argument fragments. The current adapter uses an out-of-band
+`ThinkingForwarder` because those provider deltas do not round-trip through the
+TinyAgents stream in a UI-compatible way.
+
+Implement:
+
+- Extend streaming deltas with explicit channels:
+ - visible text delta
+ - reasoning/thinking delta
+ - tool call start
+ - tool call argument delta
+ - tool call completed/assembled
+ - provider metadata/raw event summary
+- Keep channel semantics provider-neutral.
+- Emit the same data through `AgentEvent`, `AgentObservation`, journals, and live
+ stream items.
+- Attribute every delta to run id, model call id, optional thread id, parent run
+ id, and root run id.
+
+Acceptance criteria:
+
+- OpenHuman can delete `ThinkingForwarder`.
+- UI consumers can render visible text, reasoning, and tool argument assembly
+ from TinyAgents events alone.
+- Non-streaming providers can still emit post-hoc reasoning as one event.
+
+### 4. Durable Orchestration Task Store
+
+Status: partially present.
+
+TinyAgents defines a `TaskStore` trait and an `InMemoryTaskStore`. OpenHuman
+still owns durable detached-sub-agent state, cancellation handles, wait/reuse
+semantics, tombstones, and task lifecycle persistence around that store.
+
+Implement:
+
+- Add durable `TaskStore` implementations:
+ - JSONL append store.
+ - SQLite store behind a storage feature.
+ - Optional caller-supplied store adapter.
+- Persist task spec, status, timestamps, result, error, parent/root run ids,
+ cancellation requests, timeouts, and control decisions.
+- Add lifecycle history, not only latest state.
+- Support replay/listing by parent run, root run, thread id, task kind, status,
+ and created-at window.
+
+Acceptance criteria:
+
+- A process restart does not lose detached or awaiting orchestration tasks.
+- Supervisors can list, wait, cancel, kill, and inspect tasks through the SDK
+ store contract.
+- OpenHuman can retire most bespoke task status/tombstone persistence in
+ `running_subagents.rs`.
+
+### 5. SQLite Storage Compatibility
+
+Status: partially present.
+
+TinyAgents has a `SqliteCheckpointer`, but enabling the `sqlite` feature pulls a
+specific `rusqlite` / `libsqlite3-sys` version. OpenHuman already depends on a
+different SQLite native-link version, so it cannot enable that feature and had
+to implement `SqlRunLedgerCheckpointer`.
+
+Implement one or more compatibility paths:
+
+- Make SQLite support trait-first and allow external connection adapters.
+- Provide a version-flexible storage layer, possibly via `sqlx` or a separate
+ crate feature matrix.
+- Split schema helpers from dependency ownership so apps can create the tables
+ using their own SQLite connection.
+- Expose a small `CheckpointStore` persistence trait below `Checkpointer`.
+
+Acceptance criteria:
+
+- Applications that already own SQLite can use TinyAgents durable checkpoints
+ without native-link conflicts.
+- OpenHuman can replace `SqlRunLedgerCheckpointer` with an SDK-supported adapter
+ or a thin schema integration.
+- Storage features remain opt-in and keep the default crate dependency-light.
+
+### 6. Production Event And Status Journals
+
+Status: partially present.
+
+TinyAgents has `HarnessEventJournal`, `StoreEventJournal`, `HarnessStatusStore`,
+and `HarnessRunStatus`. OpenHuman still bridges TinyAgents events into its own
+progress system, cost tracker, run ledger, and UI status stream.
+
+Implement:
+
+- Durable event journals with cursors, replay windows, filters, compaction, and
+ redaction hooks.
+- Status stores with parent/root lineage, thread-scoped listing, phase details,
+ active tool/model call ids, usage totals, cost totals, and terminal summaries.
+- Event filters for UI surfaces: text stream only, tool timeline, cost updates,
+ graph lifecycle, errors, task lifecycle.
+- Redaction policies for prompts, tool args, tool results, PII, secrets, and
+ provider payloads.
+- Stable event ids and offset semantics across process restarts.
+
+Acceptance criteria:
+
+- A UI can attach late and reconstruct a run without subscribing at start time.
+- A supervisor can query every active descendant of a root run.
+- OpenHuman event bridges become mostly format adapters, not state owners.
+
+### 7. Cost, Usage, And Budget Enforcement
+
+Status: partially present.
+
+TinyAgents has `Usage`, `UsageTotals`, `CostTotals`, and accounting middleware.
+OpenHuman still owns richer budget behavior, global cost trackers, per-session
+rollups, budget stop hooks, and token/cost dashboard data.
+
+Implement:
+
+- A budget middleware that can preflight, enforce, and reconcile costs.
+- Per-run and recursive root-run budgets for input, output, cached input,
+ reasoning tokens, total tokens, and money.
+- Distinguish provider-reported usage from estimated usage.
+- Track cached-token pricing, reasoning pricing, embeddings, image/audio usage,
+ and tool/provider fees where present.
+- Add budget events: preflight, reservation, spend, refund/reconcile, warn,
+ exceeded, blocked.
+
+Acceptance criteria:
+
+- A caller can stop a recursive harness/graph run when a root budget is
+ exhausted.
+- Budget totals roll up from child/sub-agent runs without custom side channels.
+- OpenHuman cost UI can read TinyAgents-normalized records or a thin projection.
+
+### 8. Model Catalog And Provider Resolution
+
+Status: partially present.
+
+TinyAgents has `ModelProfile`, including provider, model, modalities, tool
+calling, streaming, structured output, reasoning, and token windows. OpenHuman
+still has provider catalog logic and local model capability inference that drive
+fallback, token budgeting, and routing.
+
+Implement:
+
+- SDK-owned model catalog snapshots with provider, model id, display name,
+ lifecycle status, context windows, modalities, streaming support, reasoning,
+ structured-output support, and pricing keys.
+- Capability-driven model resolution: required capabilities, fallback chains,
+ local/cloud preferences, and provider health.
+- Runtime profile discovery hooks for local models.
+- Pricing table integration that maps `ModelProfile` to `CostTotals`.
+
+Acceptance criteria:
+
+- Model selection can be expressed in TinyAgents policy instead of
+ OpenHuman-only routing code.
+- Fallback can reject models that lack required tool, vision, structured-output,
+ context-window, or reasoning capabilities.
+- Token budgeting can use the resolved model's real context window.
+
+### 9. Dynamic Tool Exposure And Allowlist Policy
+
+Status: partially present.
+
+TinyAgents can run with a provided tool registry, but OpenHuman needs per-agent,
+per-tier, per-sub-agent, and per-task allowlists. Tool visibility depends on
+security tier, workspace roots, parent/child delegation policy, model
+capabilities, and whether the run is background or interactive.
+
+Implement:
+
+- A tool selection middleware that receives run context, agent identity, task
+ kind, parent policy, and model profile.
+- Allowlist/denylist composition with explicit inheritance rules.
+- Explainable exposure decisions for audit/debugging.
+- Fail-closed behavior when policy metadata is missing.
+
+Acceptance criteria:
+
+- Sub-agents inherit only the tools they are allowed to call.
+- Tool exposure decisions are visible in run events or observations.
+- OpenHuman can remove adapter-local allowlist enforcement from most call paths.
+
+### 10. Graph Fanout And Parallel Agent Ergonomics
+
+Status: partially present.
+
+TinyAgents graph has `Send`, `Command`, reducers, interrupts, parallel execution,
+and max concurrency. OpenHuman still added `run_parallel_fanout` to provide an
+ordered, bounded map/reduce helper for council runs and `spawn_parallel_agents`.
+
+Implement:
+
+- Add a generic SDK helper for parallel map/reduce:
+ - preserve input order
+ - limit concurrency
+ - collect per-item success/failure
+ - support cancellation
+ - support reducer updates
+ - support timeout per item and total timeout
+ - expose graph lifecycle events
+- Add a higher-level parallel-agent builder:
+ - validate task specs
+ - dispatch workers through `Send`
+ - collect result envelopes
+ - merge usage/cost/events
+ - detect worker failure policy: fail-fast, collect-all, quorum, best-effort
+
+Acceptance criteria:
+
+- OpenHuman can delete most of `run_parallel_fanout` and use the SDK helper.
+- `spawn_parallel_agents` can be expressed as graph configuration plus
+ OpenHuman policy adapters.
+- Results remain deterministic in input order even when workers complete out of
+ order.
+
+### 11. Sub-Agent Steering, Waiting, And Reuse
+
+Status: partially present.
+
+TinyAgents has sub-agent and steering primitives, but OpenHuman still owns
+session reuse, wait handles, detached run tracking, user-facing cancellation,
+early-exit handling, and parent-child progress aggregation.
+
+Implement:
+
+- First-class detached sub-agent sessions.
+- `wait`, `cancel`, `kill`, `resume`, `steer`, and `close` controls backed by
+ `TaskStore`.
+- Reusable child sessions with explicit lifecycle state.
+- Parent/root event correlation for every child run.
+- Early-exit policy that can pause a run and surface a structured payload.
+
+Acceptance criteria:
+
+- Callers can spawn a detached child run, wait for it later, and survive process
+ restart if durable stores are configured.
+- Parent and child usage/cost/events roll up without bespoke registries.
+- OpenHuman can reduce `running_subagents.rs` to policy and UI projection code.
+
+### 12. Workspace Isolation And Sandbox Hooks
+
+Status: missing as an SDK-owned abstraction.
+
+OpenHuman has workspace/action-root policy, internal workspace protection,
+trusted roots, worktree isolation, sandbox modes, and command permission tiers.
+TinyAgents should not own OpenHuman's policy, but it needs generic hooks for
+agents that run tools over real files or command executors.
+
+Implement:
+
+- A `WorkspaceIsolation` or `ExecutionEnvironment` interface.
+- Hooks for preparing per-agent worktrees/sandboxes and cleaning them up.
+- Tool execution context fields for workspace root, logical task root, sandbox
+ descriptor, and policy identity.
+- Events for isolation setup, violation, cleanup, and failure.
+
+Acceptance criteria:
+
+- Parallel agents can run with isolated workspaces using SDK lifecycle hooks.
+- Tools can discover their allowed root from context instead of app globals.
+- Policy engines can block unsafe paths before tool execution.
+
+### 13. Middleware Control Outcomes
+
+Status: partially present.
+
+TinyAgents middleware is rich enough for wrapping model and tool calls, and the
+graph layer has `Command` and `Interrupt`. Some OpenHuman behaviors still need
+direct control outcomes: pause after early-exit tools, stop on budget, reroute
+on fallback, and defer work to sub-agents.
+
+Implement:
+
+- Standard control outcomes from middleware:
+ - continue
+ - replace request/response
+ - retry
+ - fallback
+ - pause/interrupt
+ - stop with final response
+ - route/goto graph node
+ - defer to task/sub-agent
+- Consistent event emission for each control outcome.
+- Clear precedence when multiple middleware layers request control changes.
+
+Acceptance criteria:
+
+- Early-exit tools and budget stop hooks do not require adapter-local steering
+ side channels.
+- Graph and harness middleware use compatible control vocabulary.
+- Control decisions are visible in journals for audit/replay.
+
+### 15. Registry Diagnostics And Introspection
+
+Status: partially present.
+
+TinyAgents has registry primitives. OpenHuman still needs richer diagnostics for
+duplicate components, alias resolution, component health, model/provider/tool
+capabilities, and event listener wiring.
+
+Implement:
+
+- Registry snapshot export with models, tools, middleware, graph nodes,
+ checkpointers, task stores, event listeners, and aliases.
+- Duplicate and shadowing diagnostics.
+- Health/status probes for registered providers and stores.
+- Machine-readable component dependency graph.
+- Optional DOT/JSON graph export for runtime components, not only graph nodes.
+
+Acceptance criteria:
+
+- A CLI or UI can show exactly what TinyAgents components are active.
+- Registry failures are actionable without inspecting app-specific logs.
+- OpenHuman dead-code audits can map old modules to SDK-owned registry entries.
+
+### 17. Storage And Graph Conformance
+
+Status: missing as a standardized SDK suite.
+
+Durable graphs and task stores are hard to migrate safely without a shared
+contract test suite.
+
+Implement:
+
+- Checkpointer conformance for memory, file, SQLite, and caller-supplied stores.
+- TaskStore conformance for lifecycle transitions, filters, cancellation,
+ timeout, kill, restart/replay, and concurrent writes.
+- Graph conformance for `Send`, reducers, interrupts, resume, max concurrency,
+ dynamic routing, fanout failure policy, and deterministic result collection.
+
+Acceptance criteria:
+
+- Storage adapters can be swapped without changing graph behavior.
+- Durable interrupt/resume semantics are proven across backends.
+- Parallel-agent helpers have regression tests for order, failure, timeout, and
+ cancellation.
+
+## Implementation Order
+
+1. Define API contracts for tool policy, unknown-tool handling, streaming delta
+ channels, durable task storage, storage adapters, and control outcomes.
+2. Implement the lowest-level data types and traits behind non-breaking
+ defaults.
+3. Add in-memory implementations first.
+4. Add durable stores and compatibility adapters second.
+5. Add middleware helpers and high-level graph helpers.
+6. Migrate OpenHuman adapters to the new SDK surfaces.
+7. Remove OpenHuman-specific compatibility shims once the SDK behavior is
+ equivalent.
+8. Implement conformance and regression tests last.
diff --git a/examples/mouse_smoke.rs b/examples/mouse_smoke.rs
deleted file mode 100644
index e03665025..000000000
--- a/examples/mouse_smoke.rs
+++ /dev/null
@@ -1,89 +0,0 @@
-//! Manual smoke test for humanized MouseTool (#682).
-//!
-//! Run with: `cargo run --example mouse_smoke --release`
-//!
-//! Watch your cursor — it should curve, not teleport. Keep your hand
-//! off the mouse during the run.
-
-use openhuman_core::openhuman::security::SecurityPolicy;
-use openhuman_core::openhuman::tools::{MouseTool, Tool};
-use serde_json::json;
-use std::sync::Arc;
-use std::time::Instant;
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
- tracing_subscriber::fmt()
- .with_env_filter(
- tracing_subscriber::EnvFilter::try_from_default_env()
- .unwrap_or_else(|_| "debug".into()),
- )
- .init();
-
- let policy = Arc::new(SecurityPolicy {
- max_actions_per_hour: 1000,
- ..SecurityPolicy::default()
- });
- let tool = MouseTool::new(policy);
-
- println!("\n=== smoke 1: humanized move (default) ===");
- let t0 = Instant::now();
- let res = tool
- .execute(json!({ "action": "move", "x": 800, "y": 500 }))
- .await?;
- println!("elapsed = {:?}", t0.elapsed());
- println!("result = {res:?}");
- assert!(!res.is_error, "humanized move should succeed");
-
- tokio::time::sleep(std::time::Duration::from_millis(800)).await;
-
- println!("\n=== smoke 2: instant teleport (human_like=false) ===");
- let t0 = Instant::now();
- let res = tool
- .execute(json!({ "action": "move", "x": 200, "y": 200, "human_like": false }))
- .await?;
- println!("elapsed = {:?}", t0.elapsed());
- println!("result = {res:?}");
- assert!(!res.is_error, "teleport move should succeed");
-
- tokio::time::sleep(std::time::Duration::from_millis(800)).await;
-
- println!("\n=== smoke 3: humanized move long distance ===");
- let t0 = Instant::now();
- let res = tool
- .execute(json!({ "action": "move", "x": 1400, "y": 800 }))
- .await?;
- println!("elapsed = {:?}", t0.elapsed());
- println!("result = {res:?}");
- assert!(!res.is_error);
-
- tokio::time::sleep(std::time::Duration::from_millis(800)).await;
-
- println!("\n=== smoke 4: humanized drag ===");
- let t0 = Instant::now();
- let res = tool
- .execute(json!({
- "action": "drag",
- "start_x": 600, "start_y": 400,
- "x": 1000, "y": 600,
- }))
- .await?;
- println!("elapsed = {:?}", t0.elapsed());
- println!("result = {res:?}");
- assert!(!res.is_error, "drag should succeed");
-
- tokio::time::sleep(std::time::Duration::from_millis(800)).await;
-
- println!("\n=== smoke 5: humanized click ===");
- // Click in dead screen area to avoid collateral.
- let t0 = Instant::now();
- let res = tool
- .execute(json!({ "action": "click", "x": 50, "y": 50 }))
- .await?;
- println!("elapsed = {:?}", t0.elapsed());
- println!("result = {res:?}");
- assert!(!res.is_error);
-
- println!("\n✓ smoke complete — verify visually that motion was curved + paced for human-like runs and instant for the teleport.");
- Ok(())
-}
diff --git a/gitbooks/developing/architecture/agent-harness.md b/gitbooks/developing/architecture/agent-harness.md
index d01a421ed..2ea3d71d0 100644
--- a/gitbooks/developing/architecture/agent-harness.md
+++ b/gitbooks/developing/architecture/agent-harness.md
@@ -7,6 +7,57 @@ icon: layer-group
# Agent Harness
+> **Status (issue #4249 — tinyagents migration):** the agent turn no longer runs
+> on the in-tree `run_turn_engine` loop. **All three entry points (`Agent::turn`,
+> the channel/CLI bus path, and `run_subagent`) now drive every turn through the
+> published [`tinyagents`](https://crates.io/crates/tinyagents) 1.1 agent-loop
+> harness** via the adapter seam in [`src/openhuman/tinyagents/`](../../../src/openhuman/tinyagents/)
+> (`run_turn_via_tinyagents_shared`). The legacy `run_turn_engine`, the three
+> hand-rolled loops, `turn_engine_adapter`, and the custom `agent_graph/` engine
+> described later in this page have been **removed**; the surviving shared seams
+> (`CheckpointStrategy`, `TurnProgress`) live in `agent/harness/engine/`. The dead
+> `token_budget.rs` (context trimming is now `MessageTrimMiddleware`) and the
+> vestigial `interrupt.rs` fence (cancellation is the tinyagents steering channel)
+> are gone; policy **stop hooks** (budget / thread-goal / iteration caps) now fire
+> through a `StopHookMiddleware` ([`tinyagents/stop_hooks.rs`](../../../src/openhuman/tinyagents/stop_hooks.rs))
+> that pauses the run on the first stop vote, and the channel route forwards live
+> `AgentProgress` like the chat route.
+>
+> Multi-agent **orchestration** is expressed on tinyagents' **graph layer** via the
+> shared helpers in [`tinyagents/orchestration.rs`](../../../src/openhuman/tinyagents/orchestration.rs)
+> (`run_parallel_fanout` — a `dispatch → parallel workers → collect` `CompiledGraph`
+> map step — plus the re-exported `graph::orchestration` `TaskStore` lifecycle
+> primitives):
+>
+> - the model-council member fan-out runs on a real `StateGraph`
+> ([`model_council/graph.rs`](../../../src/openhuman/model_council/graph.rs));
+> - [`tinyagents/delegation.rs`](../../../src/openhuman/tinyagents/delegation.rs)
+> is a `plan → execute ⇄ review → finalize` `CompiledGraph` (conditional routing,
+> `RecursionPolicy`, durable `FileCheckpointer`, `CancellationToken`, `GraphTracingSink`);
+> - the **workflow phase engine** fans each phase's agents out on the graph
+> (`with_max_concurrency`), keeping the durable `WorkflowRun` ledger as the resume
+> source of truth;
+> - `spawn_parallel_agents` runs its fan-out through `run_parallel_fanout`;
+> - the **agent-teams** member runtime is a conditional-routing graph
+> (`execute → complete | fail → done`, [`agent_teams/graph.rs`](../../../src/openhuman/agent_orchestration/agent_teams/graph.rs));
+> - the **detached-sub-agent** registry is backed by a typed `TaskStore` lifecycle
+> ledger (Pending → Running → Completed/Failed/Cancelled).
+>
+> The sections below describing a bespoke `agent_graph/` module + per-agent
+> `GraphBlueprint`s are **historical** (the pre-migration design) and are retained
+> only for context.
+
+## TinyAgents crate: features & compatibility
+
+OpenHuman pins `tinyagents = "1.1"` with **default features only** (see [`Cargo.toml`](../../../Cargo.toml)). The rationale, so future upgrades don't silently regress it:
+
+- **Default (offline) features only.** We do **not** enable the crate's `openai` feature. OpenHuman owns provider transport, credentials, OAuth, and billing classification, so the live model is always OpenHuman's `Provider` wrapped as [`ProviderModel`](../../../src/openhuman/tinyagents/model.rs) — never the crate's bundled OpenAI client. The `ChatModel` adapter is the seam that replaces the feature-gated SDK provider.
+- **`sqlite` feature deliberately disabled.** The crate's `SqliteCheckpointer` pulls `rusqlite 0.40` (`libsqlite3-sys 0.38`), which conflicts with OpenHuman's own `rusqlite 0.37` over the `links = "sqlite3"` native lib — enabling it breaks the build. Durable graph checkpoints are instead provided by [`SqlRunLedgerCheckpointer`](../../../src/openhuman/tinyagents/checkpoint.rs), a custom `Checkpointer` over OpenHuman's session DB. This holds until the upstream native-link conflict is resolved.
+- **`repl` / expressive-language features unused.** OpenHuman drives graphs from Rust (`GraphBuilder`), not the crate's `.rag` REPL language.
+- **Adapter map (feature-gated SDK piece → OpenHuman replacement):** OpenAI provider → `ProviderModel`; bundled SQLite checkpointer → `SqlRunLedgerCheckpointer`; in-memory-only durable task storage → OpenHuman SQL/JSON run ledgers (`running_subagents`, `workflow_runs`, `agent_teams`, `command_center`). The generic harness/graph/middleware/event primitives are used as-is.
+
+Migration backlog and per-phase tasks live in [`docs/tinyagents-migration-spec.md`](../../../docs/tinyagents-migration-spec.md).
+
The agent harness is the runtime that turns a user message (or a webhook fire, or a cron tick) into a complete, tool-using LLM interaction. It owns the tool-call loop, sub-agent dispatch, the trigger-triage pipeline, and the hook surface around them. It does **not** own provider HTTP transport, tool implementations, prompt-section assembly, or memory storage - those are separate domains the harness composes.
This page walks through what happens in one turn, then zooms in on each of the moving parts.
@@ -330,6 +381,80 @@ The harness lives entirely under `src/openhuman/agent/`. The README in that dire
| `progress.rs` | Real-time progress events to the UI. |
| `memory_loader.rs` | Memory-Tree context injection per user message. |
+## Agent state graphs (`agent_graph`) — HISTORICAL (removed)
+
+> **⚠️ This section describes a design that was never shipped and has been removed.**
+> The bespoke `src/openhuman/agent_graph/` engine, `GraphBlueprint`, and the
+> `SqliteCheckpointer` described below **do not exist**. The live system runs on
+> the published **tinyagents** crate — see the status banner at the top of this
+> page and "Agent engine + orchestration on tinyagents (live)" below. Graphs are
+> built with `tinyagents::graph::GraphBuilder` (`model_council/graph.rs`,
+> `agent_orchestration/*/graph.rs`, `tinyagents/delegation.rs`), durable
+> checkpoints use `SqlRunLedgerCheckpointer`, and per-agent graph selection is
+> `AgentGraph` (`agent/harness/agent_graph.rs`) with each agent's
+> `agent_registry/agents//graph.rs`. The text below is retained only as
+> pre-migration design history.
+
+Alongside the linear tool-call loop, the harness ships a **LangGraph-style state-machine engine** under [`src/openhuman/agent_graph/`](../../../src/openhuman/agent_graph/) (issue #4249). Where the loop is an implicit "prompt → tool → result → next prompt" cycle, a graph models agent execution as an explicit directed graph of **nodes** (states) and **edges** (transitions), with typed working state that survives across transitions, parallel branches, and checkpoints.
+
+```
+StateGraph::new(name)
+ .add_node(id, node) // a unit of work: async fn(State) -> (State, Command)
+ .add_edge(from, to) // static transition
+ .add_conditional_edges(...) // route by inspecting state
+ .add_fork(from, [a, b]) // fan out in parallel; merge via State::merge
+ .set_entry_point(id) / .set_finish_point(id)
+ .compile()? -> CompiledGraph // validated; .invoke(state) / .resume_with(...)
+```
+
+| Subfolder | Role |
+| ----------------- | ------------------------------------------------------------------------------------------------- |
+| `graph/` | The engine: `GraphState` (merge reducer), `Node` trait, builder + `compile()` validation, Pregel super-step `executor` with cycle / cancel / step-cap guards, `invoke`/`resume`. |
+| `checkpoint/` | `Checkpointer` trait (type-erased JSON state) → `InMemoryCheckpointer` (tests) + `SqliteCheckpointer` at `{workspace}/.openhuman/agent_graph/checkpoints.db`. Durable pause/resume. |
+| `hitl/` | Human-in-the-loop: `approval`/`clarification` interrupt builders + `ApplyResume` (folds the human's answer into state on resume). A node returns `Command::Interrupt` to pause. |
+| `observability/` | `EventBusSink` (a `ProgressSink`) emits `tracing` spans + publishes the `GraphRun*`/`GraphNode*` `DomainEvent` family (new `agent_graph` event domain). |
+| `summarization/` | Node-boundary wrapper over `context::summarize_chat_history`. |
+| `memory/` | Pre-node wrapper over `DefaultMemoryLoader::load_context`. |
+| `definitions/` | Built-in graphs over a shared `ProductState`: `canonical_turn` (the agent turn as a `dispatch → parse → stop_check → tools → compact → loop / finalize` graph) and `plan_execute_review` (composes the `planner` + `code_executor` archetypes around a HITL review gate), plus a deterministic `demo_review` twin for tests. A registry (`list_definitions`/`build_definition`) + `runner` (`run_graph`/`resume_graph`) persist runs to the checkpointer and emit bus events. |
+| `blueprint/` | The per-agent chain type. Every built-in agent declares its LangGraph-compatible chain in a `graph.rs` next to `prompt.rs` (`pub fn graph() -> GraphBlueprint`), wired into `BuiltinAgent.graph_fn`. `GraphBlueprint` is serializable (typed `NodeKind`/`EdgeSpec`), structurally validated, and `compile()`s to a real `CompiledGraph`. Reusable shapes: `canonical_turn` (most agents), `single_shot`, `orchestrator`, `plan_execute_review`. Inspect via `openhuman.agent_graph_{agent_list,agent_graph}`. |
+
+### Per-agent graphs (`graph.rs`)
+
+Each agent folder under `src/openhuman/agent_registry/agents//` (and the four agents that live in their own domains) now contains, alongside `agent.toml` + `prompt.rs`:
+
+- **`graph.rs`** — `pub fn graph() -> GraphBlueprint`. `prompt.rs` defines what the agent *says*; `graph.rs` defines how it *runs* — its node/edge chain. A loader test asserts **every** built-in agent's chain validates and compiles, so a malformed chain fails CI.
+
+Most agents reuse `blueprint::canonical_turn(id)` (the standard tool-calling loop); one-pass agents use `single_shot`, the orchestrator uses the delegation chain, and the planner uses `plan_execute_review`.
+
+**RPC surface** (`schemas.rs` + `ops.rs`, registered in `src/core/all.rs`): `openhuman.agent_graph_definition_list`, `_run`, `_run_list`, `_run_get`, `_checkpoint_list`, `_resume`.
+
+> **Status (issue #4249 — superseded by the published `tinyagents` crate):** the in-house `agent_graph` engine described in this section **no longer exists**. openhuman's agent engine + orchestration now run on the published [`tinyagents`](https://crates.io/crates/tinyagents) **1.1** crate (the same LangGraph-style harness + durable graph runtime), via the adapter seam in `src/openhuman/tinyagents/`. The sections above are retained as design history; the subsection below describes the live architecture.
+
+## Agent engine + orchestration on tinyagents (live)
+
+Every agent turn — chat (`session/turn/core.rs`), channel/CLI (`harness/channel_route.rs`), and sub-agent (`harness/subagent_runner/ops/graph_route.rs`) — drives through `crate::openhuman::tinyagents::run_turn_via_tinyagents_shared`, which runs the crate's `AgentHarness`. There is no in-house turn engine, tool loop, or routing gate left; dispatch is unconditional. The seam:
+
+| File (`src/openhuman/tinyagents/`) | Role |
+| --- | --- |
+| `mod.rs` | The runner (`run_turn_via_tinyagents_shared`): registers openhuman's `Provider`/`Tool` on an `AgentHarness`, runs one turn, caps output via `ProviderModel::with_max_tokens`, mirrors progress, forwards steering, and pauses gracefully at the model-call cap. |
+| `model.rs` / `tools.rs` / `convert.rs` | `ChatModel` / `Tool` / message adapters (incl. out-of-band reasoning forwarding and unknown-tool recovery). |
+| `observability.rs` | Harness `AgentEvent` → `AgentProgress` + cost; `GraphTracingSink` for graph events. |
+| `orchestration.rs` | `run_parallel_fanout` (the shared `dispatch → workers → collect` graph) + re-exported `graph::orchestration` task-store types. |
+| `checkpoint.rs` | `SqlRunLedgerCheckpointer` — a `Checkpointer` over openhuman's SQLite (`graph_checkpoints` table), since the crate's `SqliteCheckpointer` is dependency-blocked and it has no durable `TaskStore`. |
+| `delegation.rs` | The durable `plan → execute ⇄ review → finalize` delegation graph (production worker wired in `agent_orchestration::delegation`). |
+
+**Orchestration on graphs** (`src/openhuman/agent_orchestration/`):
+
+- **Workflow phase DAG** (`workflow_runs/engine.rs`) runs on a `dispatch ⇄ run_phase → done` conditional-routing graph; each phase fans its agents out via `run_parallel_fanout`. The durable `workflow_runs` row stays the source of truth (controllers + resume read it).
+- **Team member runtime** (`agent_teams/member_graph.rs`) is a conditional-routing graph (`execute → complete|fail → done`).
+- **Multi-stage delegation** (`agent_orchestration::delegation` + the `delegate` tool) runs `delegation.rs`, checkpointed to the session DB.
+- **Detached sub-agents** (`running_subagents.rs`) track lifecycle on the crate's `InMemoryTaskStore`; the executor (abort/steer/await) stays bespoke because the store can't inject messages, block-await, or hard-abort a task.
+
+**Deliberately kept off the crate's primitives** (documented engineering decisions, not gaps):
+
+- **Sub-agent build pipeline** (`subagent_runner/`) — definition resolution, archetype tool filtering, provider resolution, narrow prompt building, memory context, worker-thread mirror, handoff cache, checkpoint/resume — stays openhuman-owned. Sub-agents already *execute* on the harness; the crate's generic `SubAgentTool` would discard this pipeline for marginal crate-native depth tracking (openhuman's `spawn_depth_context` already bounds recursion).
+- **Durable run ledgers** (`workflow_runs`, `agent_teams`, `command_center`, `subagent_sessions`) stay on openhuman SQLite/JSON: the crate's only `TaskStore` is in-memory, so moving them would lose durability and diverge from the controllers that read them. The `agent_teams` race-safe SQL compare-and-swap task claim has no crate equivalent.
+
## See also
* [Architecture overview](README.md) - where the harness sits in the bigger picture.
diff --git a/remotion/.gitignore b/remotion/.gitignore
deleted file mode 100644
index ed2e0ee45..000000000
--- a/remotion/.gitignore
+++ /dev/null
@@ -1,9 +0,0 @@
-node_modules
-dist
-.DS_Store
-.env
-
-# Ignore the output video from Git but not videos you import into src/.
-out
-
-build
\ No newline at end of file
diff --git a/remotion/.prettierrc b/remotion/.prettierrc
deleted file mode 100644
index 37d507174..000000000
--- a/remotion/.prettierrc
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "useTabs": false,
- "bracketSpacing": true,
- "tabWidth": 2
-}
diff --git a/remotion/README.md b/remotion/README.md
deleted file mode 100644
index 39e1fc235..000000000
--- a/remotion/README.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# Remotion video
-
-
- })
-