Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

docs(tools): update orchestrator and toolpack docs for spawn_subagent

Steven Enamakelab83a78fadd4
diff --git a/crates/openhuman-core/src/tools/README.md b/crates/openhuman-core/src/tools/README.md
index ab60caebcb..79f1ade7a4 100644
--- a/crates/openhuman-core/src/tools/README.md
+++ b/crates/openhuman-core/src/tools/README.md
@@ -74,11 +74,9 @@ for tests and the lightweight CLI surface.
### Orchestrator tools
-The orchestrator agent does not get one generic `spawn_subagent` mega-tool.
-`orchestrator_tools::collect_orchestrator_tools` synthesizes one named
-`delegate_*` tool per `SubagentEntry::AgentId` in the orchestrator's
-`[subagents]` allowlist, with its description taken live from the target's
-`AgentDefinition::when_to_use`. A `SubagentEntry::Skills` wildcard expands to
+The orchestrator uses the single `spawn_subagent` tool, whose `agent_id` enum
+is derived from the `[subagents]` allowlist. `orchestrator_tools::collect_orchestrator_tools`
+only expands a `SubagentEntry::Skills` wildcard to
one `ToolExposure::Deferred` `ComposioActionTool` per action of every
connected Composio toolkit. Deferred tools never reach the wire: an agent that
opted into discovery finds them through the harness's `tool_search` bridge and
diff --git a/crates/openhuman-core/src/tools/ops.rs b/crates/openhuman-core/src/tools/ops.rs
index d2f099fb6e..f7865f080a 100644
--- a/crates/openhuman-core/src/tools/ops.rs
+++ b/crates/openhuman-core/src/tools/ops.rs
@@ -530,11 +530,8 @@ pub fn all_tools_with_runtime(
tools.len()
);
- // Append the two always-on pack tools. They resolve packed tools by name
- // out of the agent's live registry (bound after `Arc::new`), so they also
- // cover the `delegate_*` tools synthesised later by
- // `orchestrator_tools::collect_orchestrator_tools` — which never pass
- // through this function.
+ // Append the always-on pack proxy. It resolves packed tools by name out of
+ // the agent's live registry (bound after `Arc::new`).
crate::tools::toolpacks::append_pack_tools(&mut tools);
// The lookup half of `ToolExposure::Deferred` is not registered here: the
// tinyagents harness advertises its intrinsic `tool_search` bridge
diff --git a/crates/openhuman-core/src/tools/toolpacks/README.md b/crates/openhuman-core/src/tools/toolpacks/README.md
index 0e964ca630..d8ca458e53 100644
--- a/crates/openhuman-core/src/tools/toolpacks/README.md
+++ b/crates/openhuman-core/src/tools/toolpacks/README.md
@@ -24,7 +24,7 @@ constructed and executable but unadvertised: the agent sees one small tool,
`DELIBERATELY_UNPACKED_FLEET_TOOLS` list names the delegation family that is
kept *off* packs because it is used on almost every turn;
Tool packs withhold their schemas from the model until a matching pack is
- requested; hidden synthesized tools remain registered for dispatch.
+ requested; hidden tools remain registered for dispatch.
- `tools::UseSkillTool` (`USE_SKILL = "use_skill"`) is the one always-on proxy
tool. Called with `skill` alone it renders that pack's tool schemas into the
conversation; with `skill` + `tool` + `args` it resolves the real tool
@@ -36,10 +36,9 @@ constructed and executable but unadvertised: the agent sees one small tool,
produced by the tinyagents policy middleware, which is the only layer that
holds the session (see below).
- `tinyagents_harness_tools::skills::PackRegistryHandle` is the late-bound, non-owning (`Weak`) view the
- proxy dispatches through. It holds two registries: the durable tool `Arc`
- and the agent's `synthesized_tools` `Arc`, where every `delegate_*` tool
- lives. Each must be rebound after its `Arc` is replaced, or packed
- tools degrade to "skill unavailable" / "no tool in skill". The handle rides
+ proxy dispatches through. It can hold the durable tool `Arc` and, for hosts
+ that provide synthesized tools, a second `Arc`. Each must be rebound after
+ replacement, or packed tools degrade to "skill unavailable" / "no tool in skill". The handle rides
on `Tool::host_extension` and is read back by
`tools::host_extensions::pack_registry_handle`. The proxy itself
(`UseSkillTool`, `PackCatalog`, `ToolPack`, the listing/scoping renderers) lives in
@@ -122,12 +121,9 @@ pack must be named in its guide, and a loaded skill renders its guide before
its schemas.
Running an installed skill is not a pack concern: the orchestrator uses its
-own `run_workflow`. The install hand-off `setup_skills` (into `skill_setup`)
-is a member of the `skills` pack, like the other packed hand-offs
-(`build_workflow`, `manage_tasks`): it was ~270 tokens on every orchestrator
-request for a family used a few times a week. Being packed, it no longer
-closes the `skills` pack through `ops::closed_by_direct_handoff`, so the
-listing offers the hand-off beside the raw registry tools.
+own `run_workflow`. Skill installation, workflow authoring, task management,
+image understanding, and presentation generation are routed through
+`spawn_subagent` with the corresponding specialist `agent_id`.
## Called by