admin/openhuman
1
0
Fork 0
mirror of https://github.com/tinyhumansai/openhuman.git synced 2026-07-27 21:08:00 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7a67f6ca353c1fc0a57441ddec77994ee104eb15
openhuman/docs/tinyagents-migration-spec.md
T

38 KiB
Raw Blame History

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

  • 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<dyn Tool> 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.

  • 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).

  • 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 AgentDefinitions, 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.
Reference in New Issue View Git Blame Copy Permalink