openhuman/docs/tinyagents-sdk-gaps.md

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:

• Original source baseline: local TinyAgents checkout at 6f898fb.
• Refresh note: TinyAgents 1.3.0 was re-verified from the published crate source. Several older "missing" items are now shipped in 1.2.0-1.3.0: tool policy metadata, recoverable unknown-tool calls, reasoning/tool-call stream deltas, orchestration task stores, budget reservation/reconciliation, ordered parallel map/reduce, sub-agent steering/task controls, workspace isolation hooks, and middleware control outcomes. The backlog below keeps only the residual OpenHuman migration pressure and SDK surface gaps.
• 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 follow each migrated surface; only broad end-to-end parity suites should wait for the final cutover.

Executive Summary

TinyAgents already has strong primitives for harness runs, graph execution, middleware, event streams, model profiles, usage/cost accounting, checkpointers, policy metadata, recoverable tool-call behavior, workspace isolation, and sub-agent orchestration. The biggest remaining gaps are now narrower: OpenHuman adapter migration, transcript/session migration, richer replay and redaction rules, model/provider catalog integration, registry diagnostics, and a few still-missing SDK fields.

OpenHuman can migrate more of src/openhuman/agent/ by adopting the newer TinyAgents surfaces and filling the remaining gaps:

• A free-form metadata map on ToolSchema for model-visible schema annotations; SDK-owned enforcement metadata now lives in ToolPolicy.
• A reasoning field on the middleware-facing harness::model::ModelDelta; AgentEvent::ModelDelta already carries nested MessageDelta.reasoning.
• A one-time migration path from old OpenHuman session_raw/*.jsonl and Markdown transcripts into TinyAgents store/journal/status records.
• Production replay rules over TinyAgents stores/status: redaction, cursors, backfill, cancellation, and OpenHuman controller compatibility.
• Storage compatibility options for SQLite users that already own a connection, schema, or native sqlite patch policy.
• A root_run_id field on harness RunConfig; lineage exists in graph and observability records, but not on the harness config itself.
• A money/USD field on Usage; token usage and cost totals remain separate.
• 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: shipped in 1.3.0; residual schema metadata gap remains.

TinyAgents now has SDK-owned ToolPolicy, ToolSideEffects, ToolRuntime, ToolAccess, WorkspaceAccess, SandboxMode, Tool::policy, registry policy snapshots, and ToolPolicyMiddleware. Strict policy can fail closed on unclassified tools, enforce sandbox and result-byte requirements, and keep plain ToolSchema as the model-visible projection.

Residual:

• ToolSchema still has no free-form metadata map for model-visible schema annotations or app-specific hints. Use ToolPolicy for enforcement metadata and keep this as the remaining SDK shape gap.
• OpenHuman still needs to map domain tool registry metadata into Tool::policy snapshots before deleting adapter-local policy plumbing.

2. Recoverable Unknown Tool Calls

Status: shipped in 1.3.0.

TinyAgents now has UnknownToolPolicy::{Fail, ReturnToolError, Rewrite} and emits AgentEvent::UnknownToolCall with the original requested name and arguments. This distinguishes "tool not found" from "tool executed and failed" and lets a run keep going so the model can correct itself.

OpenHuman follow-up:

• Replace the adapter-local __openhuman_unknown_tool__ sentinel with UnknownToolPolicy once the surrounding compatibility surface is migrated.

3. Reasoning And Tool-Argument Streaming

Status: shipped in 1.3.0; residual middleware event-shape gap remains.

TinyAgents MessageDelta now carries provider-neutral text, reasoning, and tool_call channels, and AgentEvent::ModelDelta carries the delta with an explicit run_id and call_id.

Residual:

• The middleware-facing harness::model::ModelDelta still has no reasoning field, and the agent loop drops reasoning when converting stream items into that middleware shape. Event consumers can read reasoning from AgentEvent::ModelDelta.delta.reasoning.
• OpenHuman still needs to route provider reasoning/tool-argument deltas through the TinyAgents stream before deleting UI-specific forwarding shims.

4. Durable Orchestration Task Store

Status: shipped as SDK primitives in 1.3.0; OpenHuman migration remains.

TinyAgents now has TaskStore, InMemoryTaskStore, JsonlTaskStore, OrchestrationTaskRecord, lifecycle transitions, cancel/kill outcomes, filters, graph/harness status with lineage, graph::subagent_node, and graph::subgraph.

OpenHuman follow-up:

• Map durable sub-agent session rows and worker-thread records into TinyAgents task/status/journal records while preserving controller compatibility.
• Retire bespoke task status/tombstone persistence in running_subagents.rs only after restart/replay behavior is projected through the SDK records.

5. SQLite Storage Compatibility

Status: partially present.

TinyAgents 1.3 has SqliteCheckpointer, from_connection, and schema_sql, and OpenHuman now enables the sqlite feature by aligning both Cargo worlds on rusqlite 0.40 / libsqlite3-sys 0.38. The remaining gap is not feature enablement or basic schema access; it is ownership. OpenHuman still patches the sqlite crates locally for the current toolchain, owns existing session/checkpoint tables through SqlRunLedgerCheckpointer, and needs a clean way to adopt or bridge SDK checkpoint storage without surrendering dependency or schema control.

Implement one or more OpenHuman compatibility paths:

• Provide a version-flexible storage layer, possibly via sqlx or a separate crate feature matrix.
• Expose a small CheckpointStore persistence trait below Checkpointer.
• Add an adapter/cutover path that can project OpenHuman run-ledger checkpoints into SDK checkpoint storage without breaking existing resume semantics.

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: shipped in 1.3.0; residual money field gap remains.

TinyAgents now has Usage, UsageTotals, CostTotals, BudgetLimits.max_cached_input_tokens, budget middleware, and AgentEvent::{BudgetReserved, BudgetReconciled, BudgetWarning, BudgetExceeded}. The SDK can preflight, reserve, enforce, and reconcile token budgets.

Residual:

• Usage still has no USD/money field. Token usage and money remain separate (Usage/UsageTotals vs. CostTotals), so OpenHuman cost UI still needs a projection that joins token usage with pricing/cost records.

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: map/reduce helper shipped in 1.2.1-1.3.0; OpenHuman builder migration remains.

TinyAgents now has ordered map_reduce, FailurePolicy, ParallelOptions, max concurrency, per-item timeout, total timeout, and cooperative cancellation. OpenHuman council runs and spawn_parallel_agents can use this helper directly.

Residual:

• The higher-level parallel-agent builder remains OpenHuman-specific policy glue: task validation, Send dispatch shape, result envelopes, usage/cost merging, and ownership/worktree policy adapters.

11. Sub-Agent Steering, Waiting, And Reuse

Status: SDK primitives shipped in 1.3.0; OpenHuman lifecycle projection remains.

TinyAgents now has sub-agent sessions/tools, steering, task stores, cancel/kill control outcomes, graph/harness lineage, and reusable child-run primitives.

OpenHuman follow-up:

• Project existing detached run tracking, wait handles, user-facing cancellation, early-exit handling, and parent-child progress aggregation onto TinyAgents task/status records before reducing running_subagents.rs.

12. Workspace Isolation And Sandbox Hooks

Status: shipped in 1.3.0; OpenHuman policy integration remains.

TinyAgents now has WorkspaceDescriptor, WorkspaceIsolation, SharedRootWorkspace, sandbox descriptors, ToolExecutionContext.workspace, and WorkspaceDescriptor::enforce(path, events) which emits AgentEvent::WorkspaceViolation and fails closed when a path leaves the allowed roots.

OpenHuman follow-up:

• Implement OpenHuman's action-root, trusted-root, internal-workspace, worktree, sandbox, and command-tier policy as a WorkspaceIsolation provider and tool middleware projection.

13. Middleware Control Outcomes

Status: shipped in 1.3.0.

TinyAgents now has MiddlewareControl::{StopWithFinal, Interrupt}, RunContext::request_control, precedence handling via MiddlewareControl::precedence(), stable kind() labels, and AgentEvent::ControlApplied so control decisions are visible in journals.

OpenHuman follow-up:

• Route early-exit tools and budget stop hooks through MiddlewareControl before deleting adapter-local steering side channels.

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: partially present.

TinyAgents 1.3 includes storage conformance coverage for built-in checkpointers and task stores, including SQLite under the feature. Durable OpenHuman adapters and fuller graph behavior are still hard to migrate safely without shared contract coverage.

Implement:

• Checkpointer conformance for OpenHuman adapters 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.