openhuman/docs/tinyagents-harness-migration-audit.md

TinyAgents Harness Migration Audit

Date: 2026-07-01

Scope: current openhuman-5 checkout on branch issue/4249-finish-tinyagents-migration.

TinyAgents refresh: reviewed tinyhumansai/tinyagents main at 348a0e7dc71a1f9039f3d523a2a384661a7a9acd after the current audit was first written. That repo is now materially ahead of the assumptions in the older OpenHuman migration docs: it has harness cache/store/session primitives, sub-agent reuse, graph subgraph/sub-agent nodes, lineage-aware events/status, and JSONL-backed append stores.

This is a documentation-only audit of how much of the OpenHuman agent harness is actually migrated to TinyAgents, and which remaining OpenHuman files are good candidates to port, collapse, or keep as product-specific adapters.

Bottom Line

The core turn loop is migrated. The live chat turn, channel/CLI turn, and sub-agent turn all route through src/openhuman/tinyagents::run_turn_via_tinyagents_shared. That means the model/tool iteration loop, TinyAgents middleware stack, event bridge, stop hooks, context compression, unknown-tool recovery, and tool policy boundary are on the TinyAgents harness path.

The repository still has a large OpenHuman harness shell around that path:

Area	Rust files	Lines	Current role
src/openhuman/agent/harness/	83	30,521	Agent session assembly, transcript compatibility, prompt/tool filtering, context product logic, sub-agent build pipeline, leftover generic loop seams
src/openhuman/tinyagents/	13	6,481	TinyAgents adapters, middleware, event bridge, graph helpers, checkpoint adapter
src/openhuman/agent_orchestration/	58	21,704	Product orchestration tools, durable workflow/team/session state, graph-backed fanout/delegation wrappers

The migration should not be read as "OpenHuman can delete agent/harness/ now." The correct read is: the execution core is on TinyAgents, but much of the surrounding runtime was preserved for product compatibility. After reviewing the current TinyAgents code, more of that surrounding runtime is now portable than this audit originally assumed: session transcript tracking, prompt/response cache handling, and sub-agent pipeline orchestration can be expressed through TinyAgents store/cache/subgraph/sub-agent-node primitives, with OpenHuman keeping only product policy and compatibility adapters.

What Is Migrated

Turn execution chokepoints

• src/openhuman/agent/harness/session/turn/core.rs routes the main chat turn through super::graph::run_chat_turn_graph, which is a thin wrapper over run_turn_via_tinyagents_shared.
• src/openhuman/agent/harness/graph.rs routes channel/CLI turns through run_turn_via_tinyagents_shared.
• src/openhuman/agent/harness/subagent_runner/ops/graph.rs routes sub-agent turns through run_turn_via_tinyagents_shared.
• src/openhuman/tinyagents/mod.rs owns the shared harness assembly: OpenHuman provider adapter, tool adapters, event bridge, middleware, steering, early-exit hooks, stop hooks, model/tool call caps, and outcome capture.

Practical status: the old in-tree model/tool loop is no longer the live execution engine for those three entry points.

Middleware and policy

Already migrated into TinyAgents middleware or the TinyAgents adapter seam:

• Approval and security gating at the tool boundary.
• CLI/RPC-only tool denial.
• Channel permission ceiling and tool policy checks.
• Unknown-tool recovery via an internal sentinel.
• Non-object tool-argument recovery.
• Cost budget pre-checks before model calls.
• Repeated tool failure halting.
• Context compression and message trimming via TinyAgents middleware.
• OpenHuman tool-output budgets and payload summarizer hooks as TinyAgents tool middleware.
• Stop-hook checks via src/openhuman/tinyagents/stop_hooks.rs.

This is real migration, but not complete ownership transfer: OpenHuman still keeps rich policy metadata outside TinyAgents because the SDK tool schema does not yet carry all OpenHuman policy fields.

Graph-backed orchestration

The codebase has several real TinyAgents graph uses:

• src/openhuman/tinyagents/delegation.rs: durable plan -> execute -> review -> finalize graph.
• src/openhuman/agent_orchestration/workflow_runs/graph.rs: workflow phase DAG scheduler graph.
• src/openhuman/agent_orchestration/agent_teams/graph.rs: member execution conditional-routing graph.
• src/openhuman/tinyagents/orchestration.rs: reusable run_parallel_fanout helper, used by spawn_parallel_agents and workflow phase fanout.
• src/openhuman/tinyagents/topology.rs: topology export for fixed graph structures.
• src/openhuman/agent_orchestration/running_subagents.rs: detached sub-agent lifecycle is mirrored into TinyAgents InMemoryTaskStore.

Practical status: graph adoption is meaningful but uneven. The larger product tools still own validation, persistence, cancellation semantics, compatibility events, and result formatting.

What Is Still Mostly OpenHuman-Owned

Session, transcript, and cache shell

Largest remaining harness surface: src/openhuman/agent/harness/session/ at roughly 13.2k lines.

Current OpenHuman role:

• Session transcript migration and compatibility.
• Product-level AgentBuilder configuration.
• Prompt section assembly and prompt-cache stability decisions.
• Memory/context injection policy.
• Post-turn hooks, transcript persistence, and OpenHuman-specific history shape.
• Tool dispatcher compatibility for persisted native/XML/P-format transcript suffixes.

Updated TinyAgents target:

• Use TinyAgents harness::store::{Store, AppendStore, FileStore, JsonlAppendStore} as the durable substrate for message history, event journals, tool/model call records, artifacts, and local migration outputs.
• Use TinyAgents harness::cache::{ResponseCache, PromptCacheLayout, CacheLayoutEvent, CachePolicy} for response-cache and provider KV-cache layout protection instead of keeping prompt-cache reasoning as OpenHuman-only session logic.
• Use TinyAgents run/event/status lineage (root_run_id, parent_run_id, offsets, status stores) as the canonical internal transcript/run inspection surface, then project into legacy OpenHuman views where needed.
• Write a one-time migration script for old OpenHuman session_raw/*.jsonl and legacy Markdown session files into TinyAgents store/journal records. The script should preserve original session ids, transcript stems, timestamps, provider/model metadata, tool-call ids, and parent/child links, and should be idempotent with a marker/version row so it can be safely re-run.

Keep in OpenHuman:

• The legacy reader/writer compatibility layer until migrated sessions are proven equivalent.
• Product-specific prompt assembly, memory source identity, approval/security context, and JSON-RPC response shapes.

Sub-agent build pipeline

Remaining surface: src/openhuman/agent/harness/subagent_runner/ at roughly 6.1k lines.

Keep in OpenHuman:

• Agent definition lookup and allowlist enforcement.
• Prompt assembly for archetypes.
• Parent context, memory context, action root, sandbox, and toolkit filtering.
• Worker-thread mirroring and transcript compatibility.
• Integrations-agent preflight and handoff cache behavior.

Updated TinyAgents target:

• Map the OpenHuman sub-agent build pipeline into TinyAgents SubAgent, SubAgentSession, and SubAgentTool once registry/policy adapters are ready.
• Express multi-step sub-agent work as graph structure using graph::subagent_node for harness-agent leaves and graph::subgraph for reusable pipelines. The current OpenHuman "prepare prompt -> filter tools -> run child -> checkpoint/handback -> mirror transcript" flow can become a subgraph rather than a sidecar runner.
• Use TinyAgents parent/root run lineage and UsageTotals for child usage/cost rollup instead of carrying separate OpenHuman aggregation structs.
• Keep OpenHuman-specific preflight nodes for agent definition lookup, allowlists, toolkit gates, sandbox/action-root narrowing, and worker-thread mirroring.

Detached sub-agent registry

Remaining surface: src/openhuman/agent_orchestration/running_subagents.rs at roughly 1.0k lines.

Current state: it uses TinyAgents InMemoryTaskStore as a typed lifecycle ledger, but still owns watch channels, abort handles, wait/steer/cancel control, tombstones, ownership checks, and session lookup.

Updated TinyAgents target:

• Durable TaskStore support.
• Typed wait/steer/cancel APIs.
• Parent/root run tree queries.
• Cancellation requests and hard abort lifecycle events.

TinyAgents now has more of the lifecycle substrate than this audit originally assumed, including harness/graph status records, lineage-aware events, SubAgentSession reuse, and append stores. The migration should therefore be an adapter exercise first: map existing durable OpenHuman sub-agent session rows and worker-thread records into TinyAgents session/status/journal records, then keep OpenHuman controllers as compatibility projections.

Keep in OpenHuman until parity is proven:

• Desktop restart/resume compatibility.
• Existing JSON-RPC/tool response shapes.
• Durable OpenHuman session and worker-thread ledgers.

Parallel agents and workflow fanout

Remaining surfaces:

• src/openhuman/agent_orchestration/tools/spawn_parallel_agents.rs
• src/openhuman/agent_orchestration/workflow_runs/engine.rs
• src/openhuman/tinyagents/orchestration.rs

Current state: fanout execution uses a TinyAgents graph helper, but spawn_parallel_agents is not yet a first-class graph tool. It still owns validation, worktree setup, overlap/stale-read checks, compatibility events, and JSON output formatting.

Good TinyAgents candidates:

• Re-express spawn_parallel_agents as validate -> dispatch -> worker -> collect -> finalize using graph Send or an SDK map/reduce helper.
• Move deterministic ordering, cancellation boundaries, graph status, and child lineage into TinyAgents graph state.
• Keep result formatting and OpenHuman worktree policy in a thin wrapper.

Per-agent graph selectors

There are 32 src/openhuman/agent_registry/agents/*/graph.rs files and all currently return AgentGraph::Default.

This is mostly scaffolding, not migrated behavior. It proves the extension seam exists, but there are no bespoke per-agent TinyAgents graphs yet.

Good candidates for first real custom graphs:

• orchestrator: planning/delegation/parallelism policy can become explicit graph routing instead of prompt-only convention.
• researcher: search -> read -> synthesize -> cite can be bounded and checkpointed.
• tool_maker: detect missing capability -> generate -> validate -> expose can become a graph with explicit review gates.

Candidate cleanup: replace boilerplate default graph.rs files with registry defaults once at least one real custom graph proves the API shape.

Porting Candidates By Priority

P0: Update stale active docs and comments

Evidence: active architecture docs still described the old engine::run_turn_engine loop in sections below the TinyAgents status callout.

Action:

• Rewrite active sections to describe TinyAgents as the live loop.
• Move the removed in-house loop details into a short historical appendix.
• Sweep code comments that still say run_turn_engine, run_tool_call_loop, or run_inner_loop when they now mean the TinyAgents harness path.

Why first: stale docs make it hard to tell whether remaining files are live runtime, compatibility shell, or historical residue.

Status (2026-07-01): done. gitbooks/developing/architecture/agent-harness.md active sections now describe the TinyAgents path (loop, dialects-as-transcript- compat, middleware context management, steering-channel cancellation, corrected file map, 1.2 pin); pre-migration loop details are confined to the marked historical sections. The retired-loop comment sweep landed earlier (f5a6b5196); remaining run_turn_engine/run_inner_loop mentions in code are explicit "legacy parity" references, not current-behavior claims.

P1: Migrate old OpenHuman sessions into TinyAgents stores

Design: docs/tinyagents-session-migration-design.md (2026-07-01) — source format inventory, target store layout, lineage-key mapping, idempotency ledger, fixture matrix, and phasing.

Status (2026-07-01): Phase 1 (write-only importer) implemented in src/openhuman/session_import/ as openhuman.session_import_run, with the full fixture matrix as tests. Phases 2–4 (read-side shadow, cutover, retirement of legacy readers) remain.

Current OpenHuman files:

• src/openhuman/agent/harness/session/transcript.rs
• src/openhuman/agent/harness/session/migration.rs
• session_raw/*.jsonl and legacy Markdown session directories under user workspaces.

Target shape:

• Add a one-time migration command/script that reads old OpenHuman session JSONL and Markdown transcripts, normalizes them into TinyAgents message/event/store records, and writes them through TinyAgents-compatible Store/AppendStore semantics.
• Preserve compatibility metadata so old UI surfaces and run-ledger lookups can still answer by OpenHuman session key while new internals read by TinyAgents thread_id, run_id, root_run_id, and stream offset.
• Make the migration idempotent and observable: dry-run mode, per-file summary, warning list, migrated-count counters, and a marker/version record.

Risk: transcript shape is user data. This needs fixture coverage over current flat session_raw/*.jsonl, older date-folder JSONL, Markdown sessions, sub-agent transcript stems, native tool-call envelopes, XML/P-format tool history, and malformed partial files.

P2: Make event/status journals canonical

Current OpenHuman files:

• src/openhuman/tinyagents/observability.rs
• src/openhuman/agent/harness/engine/progress.rs
• src/openhuman/session_db/run_ledger/*
• src/core/event_bus/*

Target shape:

• TinyAgents journals/status stores become the internal source for model/tool events, usage, graph steps, child run lineage, and resumable inspection.
• AgentProgress and DomainEvent become compatibility projections.

Risk: this crosses UI streaming, cost footer, run ledgers, and desktop reconnect behavior. It needs focused parity tests before deletion.

P3: Port detached task lifecycle beyond the OpenHuman registry

Current OpenHuman files:

• src/openhuman/agent_orchestration/running_subagents.rs
• src/openhuman/agent_orchestration/tools/{wait_subagent,steer_subagent,close_subagent,continue_subagent}.rs

Target shape:

• TinyAgents owns typed task lifecycle, wait/steer/cancel semantics, parent/root run lineage, and terminal history.
• OpenHuman owns durable SQL/JSON projection and product response formatting.

This is no longer just waiting on SDK primitives. Current TinyAgents exposes session reuse, lineage-aware events/status, graph/harness observability, and JSONL append storage. The concrete blocker is now designing the OpenHuman compatibility adapter and proving restart/resume parity against existing controllers.

P4: Re-express spawn_parallel_agents as a graph tool

Current OpenHuman files:

• src/openhuman/agent_orchestration/tools/spawn_parallel_agents.rs
• src/openhuman/agent_orchestration/worktree.rs
• src/openhuman/tinyagents/orchestration.rs

Target shape:

• A graph with nodes for validation, dispatch, worker, collect, finalize.
• Deterministic reducer state for per-task result order.
• Child run lineage and cancellation through graph status.
• Thin OpenHuman wrapper for the existing JSON result and worktree policy.

Why: this is a high-value migration because it converts a large product-visible orchestration loop without touching the basic chat turn.

P5: Replace generic checkpoint/progress seams

Current OpenHuman files:

• src/openhuman/agent/harness/engine/checkpoint.rs
• src/openhuman/agent/harness/engine/progress.rs
• src/openhuman/agent/harness/subagent_runner/ops/checkpoint.rs

Target shape:

• Model-call cap, early-exit pause, resumable checkpoint summary, and progress projection represented as TinyAgents status/events/middleware.

Keep only the OpenHuman-specific compatibility formatting for existing transcripts and tool outputs.

P6: Retire boilerplate per-agent graph selectors

Current OpenHuman files:

• src/openhuman/agent/harness/agent_graph.rs
• src/openhuman/agent_registry/agents/*/graph.rs

Target shape:

• Default graph supplied centrally.
• Only agents with custom graph behavior keep a graph.rs.
• Registry diagnostics show which graph each agent actually uses.

This should happen after at least one bespoke graph lands, so the cleanup does not remove a seam before it has proved useful.

Code That Should Probably Stay In OpenHuman

Do not port these blindly into TinyAgents:

• Agent registry definitions and built-in prompt semantics.
• Tool allowlists/denylists that encode product policy.
• Security policy, sandbox roots, approval records, credential access, and workspace/action-dir boundaries.
• Session transcript migration and persisted compatibility formats.
• OpenHuman model provider routing, billing classification, and credential ownership.
• UI-facing JSON-RPC response shapes and DomainEvent compatibility until every subscriber is moved.
• Worktree isolation policy and dirty-worktree safeguards.
• Memory stores, retrieval policy, and context source identity.

TinyAgents should own generic runtime machinery. OpenHuman should own product semantics and compatibility boundaries.

Main SDK Gaps Blocking More Deletion

The most important upstream gaps are tracked in docs/tinyagents-sdk-gaps.md, but that file must be refreshed against TinyAgents main at 348a0e7dc71a1f9039f3d523a2a384661a7a9acd. Several older "missing" items now exist as concrete TinyAgents modules:

• harness::cache has response caching and prompt/KV-cache layout protection.
• harness::store has key-value stores and JsonlAppendStore.
• harness::subagent has SubAgent, SubAgentSession, and SubAgentTool.
• graph::subgraph and graph::subagent_node can express nested graph and sub-agent pipelines.
• harness/graph observability and status types carry root_run_id / parent_run_id lineage.

Remaining blockers are narrower:

• Rich tool policy metadata in TinyAgents schemas.
• Recoverable unknown-tool policy without the OpenHuman sentinel.
• Full OpenHuman policy mapping for approval/security/sandbox/workspace roots.
• A migration adapter from OpenHuman session JSONL/Markdown/run-ledger rows into TinyAgents store/journal/status records.
• SQLite/native-link compatibility if OpenHuman wants to use TinyAgents' embedded SQLite backend directly rather than its own SQLite adapter.
• Redaction/cursor/backfill rules for production UI replay.
• OpenHuman controller compatibility during the migration window.

Suggested Next Documentation Pass

1. Rewrite the active gitbooks/developing/architecture/agent-harness.md sections below the status block so they describe the TinyAgents path instead of the removed in-house loop.
2. Add a one-time transcript/session migration design for old OpenHuman session_raw/*.jsonl and Markdown sessions into TinyAgents store/journal records. Done: docs/tinyagents-session-migration-design.md.
3. Add a small "Historical pre-TinyAgents loop" appendix for details that are still useful context.
4. Add per-folder READMEs or module docs for:
   • src/openhuman/agent/harness/session/: product session shell over TinyAgents.
   • src/openhuman/agent/harness/subagent_runner/: OpenHuman sub-agent build pipeline over TinyAgents.
   • src/openhuman/agent_orchestration/: product orchestration wrappers over TinyAgents graphs/task lifecycle.
5. Keep docs/tinyagents-migration-spec.md as the backlog, and use this audit as the current inventory snapshot.