Skip to content

refactor(orchestration): make subagent spawning async-only - #520

Merged
senamakel merged 61 commits into
tinyhumansai:epic/8088-tinyagents-slimfrom
senamakel:epic-8088-58-async-only
Oct 22, 2026
Merged

senamakel merged 61 commits into
tinyhumansai:epic/8088-tinyagents-slimfrom
senamakel:epic-8088-58-async-only

Conversation

@senamakel

@senamakel senamakel commented Oct 21, 2026 •

Copy link
Copy Markdown
Member

Makes spawn_subagent the single subagent tool and removes the legacy synchronous SubAgent API, inline mode, delegation, teams, parallel fan-out, and orchestration workflows. Driver-backed calls now return a job immediately even without a delivery target; hosts wait through the owned job registry separately. Completion delivery remains conditional on its target.

Moves the policy types from graph into orchestration and reverses that dependency while the graph crate remains for its separate deletion leaf. Preserves owned-child waiting, pause/resume, cancellation, attempt tracking, and panic settlement through JobSettleGuard. Rewrites surviving job tests onto the driver; graph-node tests move intact into the graph crate.

Refs senamakel#58. Part of tinyhumansai/openhuman#8088.

This PR is stacked on #519 and remains a draft until that dependency lands on the epic base branch. The final 3.0 release and downstream adoption are separate epic leaves.

Validation:

  • Workspace all-target compilation and strict all-target Clippy passed with default features and with all features enabled.
  • Default workspace tests: 5,739 passed, 0 failed, 31 ignored. All-features workspace tests: 6,492 passed, 0 failed, 31 ignored. Enabled subagent suite: 194 passed, including 32 driver tests.
  • Formatting and strict broken-link documentation passed with default features and with multimodal enabled. A cfg-dependent documentation link was corrected.
  • Dependency trees confirm no graph dependency from orchestration; graph temporarily imports orchestration policy types.

The retained and rewritten behavior cases are mapped in tinyagents-58-test-migration.json in the epic evidence ledger. Failed compile/lint attempts remain preserved there.

senamakel and others added 30 commits October 21, 2026 16:26
…agents-runtime/src/tool_registr

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
…tests.rs

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The README now explains that sub-agent turns are leaf turns by default and
that hosts must opt in via ToolAdmission::nested_spawn_depth, noting the
runtime's allowlist and depth-ceiling checks and the host's remaining
responsibility. The re-export list and a test assertion were reformatted
without behaviour changes.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Update the module and field documentation to describe that spawn and
delegate tools are withheld from sub-agent runs by default rather than
never handed out, and that a host may grant bounded nested spawning for a
turn. The new wording also notes that granted tools must still pass the
ordinary allowlist and that the host enforces the depth ceiling when a
child executes.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Split the terminal-child case into its own test that asserts a finished
child routes through the fallback with thread and agent metadata while
leaving the stale handle undrained. The previous assertions mixed this
scenario with the unknown, unowned, and terminal rejection checks, which
made the fallback behaviour hard to see.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Rename two steering tests so their names describe what they actually assert, and adjust the terminal transition test to expect a fallback selection instead of an unknown error. The unused sender binding is prefixed with an underscore to silence the warning.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Terminal tasks with retained metadata are no longer rejected as unknown; they now fall through to the host fallback like tasks without a live steering handle. This makes steering idempotent for finished tasks and updates the docs to match.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Introduce a RecordedSteer type alias for the captured fallback payload and
import Mutex directly, replacing the inline tuple type. Also reflow the
status send and closure body to satisfy rustfmt.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
SubAgentBudget, SubAgentOutput and SubAgentPolicy now live in
tinyagents-orchestration, and tinyagents-graph re-exports them so existing
call sites keep working. The policy logic moved with the types, letting the
orchestration layer own subagent policy without depending on the graph crate.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
…tions

The invocation types module now only declares the shared state and
registries used by driver-backed asynchronous subagent jobs, with the
harness-based sub-agent, session, and tool types removed.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Job creation now takes the parent run and thread identifiers directly
instead of a JobLink, and the unused inline creation helpers were removed
so only driver-backed jobs remain. The settle guard was renamed to
JobSettleGuard to reflect that it is no longer specific to inline jobs.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The driver subagent tool no longer accepts a mode parameter, so callers
can no longer force inline execution and the delivery target is always
consulted. The inline job guard was renamed to JobSettleGuard to match
its broader role.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The multi-target delegation adapter and its supporting policy, admission, and
inline test modules were removed from the subagent invocation layer. The
delegation flow is now handled elsewhere, so these host-owned tool
implementations and their tests are no longer needed.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The subagent module no longer re-exports the step and delegation helpers, and the module docs now describe only the lifecycle traits and driver. This narrows the public surface to the pieces hosts actually consume.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The orchestration crate no longer exposes the parallel, status, teams,
topology, and workflow modules, and the fleet tool set helpers in the
subagent role module are gone. Admission is now documented as enforced
solely by the async driver, and status mapping imports come from
tinyagents-tasks.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The job registration now takes an optional parent thread id instead of a
required string, so callers without a parent thread can register jobs
without fabricating one. Unused imports were dropped alongside the change.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Drops the mark_result, mark_result_applied, and mark_budget_overrun
methods from the job registry along with the now-unused IncompleteKind
import, since these paths are no longer called.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The driver tool now reads the registered job directly instead of waiting on
ownership or spawning a detached task, and awaiting_input is treated as a
successful status. This removes the duplicated completion plumbing so the
adapter only reports the current job state.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The test now exercises a background request that has no delivery target and
asserts the job is spawned and tracked in the registry rather than run inline.
It waits on the job separately and checks the completed status and output.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Delete the parallel, teams, workflow, subagent, status, and topology
modules along with their tests, examples, and integration tests. These
components are being dropped from the orchestration crate, leaving the
remaining surface to be rebuilt without them.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The async spawn tool is now exposed as `spawn_subagent`, so the spawn tool
allowlist and the orchestrator fixture were updated to match. The subagent
module also re-exports `SubAgentOutput` from its policy module.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Condense the orchestration README to describe the host-neutral policy and
lifecycle surface, dropping the long inventory of tool wrappers that now live
in tinyagents-harness-tools. The subagent README is trimmed to match the same
framing.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The subagent session and tool dispatch cases were removed from the mock
capabilities suite, leaving the fuzz matrix to exercise only regular tools.
This trims the test surface to the capabilities still under test.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The fuzz-style matrix test was reduced to a single loop over the lookup flag, dropping the always-false subagent dimension and its nested loop. The scenario label and doc comment were updated to match the narrower coverage.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
…ties test

Reindent the mock matrix test body and correct the expected tool count to
only account for the lookup tool, since the subagent flag is not part of
this scenario.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Documentation and doc comments now point at `DriverSubAgentTool` in
`tinyagents-harness-tools` instead of the removed `SubAgent`/`SubAgentTool`
types in `tinyagents-orchestration`, and the orchestration subagent README
drops the stale agent-step section in favour of a short note on the temporary
graph re-exports.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The status tool result now only returns a successful JSON result for completed, running, and queued statuses, so awaiting_input falls through to the error branch. This makes the tool report awaiting_input as a failure rather than a normal state.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Rename and rewrite the concurrent driver alias tests so they assert the
async dispatch path returns a running job snapshot immediately and
coalesces followers onto the same task id, rather than blocking until the
shared result completes. The replay test now uses a single async tool
with a completion handler and verifies the snapshot is returned before
the job settles.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Introduce a RegistryTestHelpers trait and JobLink fixture builder so
registry tests register jobs through the same driver path used by
DriverSubAgentTool, with helpers for marking results and budget overruns.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Adjust the test helper to match the result by reference and simplify the
budget overrun call to the new single-argument signature, keeping the
race-with-cancel test aligned with the current registry API.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
senamakel and others added 21 commits October 21, 2026 21:37
The spawn tool name list now contains only spawn_subagent, dropping
spawn_parallel_agents and spawn_worker_thread so that scope detection no longer
treats those retired names as spawn tools. A test pins the roster and the
detection behaviour for the removed names.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The module documentation now states that every accepted call starts a
background job and returns its status immediately, with waiting and
completion delivery handled as separate host operations. This makes the
non-blocking contract of the tool adapter explicit.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Add a test that runs a detached subagent whose policy times out while the
executor is still blocked, asserting the job is recorded as incomplete with a
timeout kind. Also drop the delivery target from an unrelated alias pause test
so it no longer relies on a parent thread.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The driver tool documentation now states that every call starts a detached
job and returns its task reference immediately, with the delivery target only
controlling host completion callbacks. The README was updated to drop the
reference to dropped inline calls, since inline execution no longer occurs.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The orchestration crate no longer references tinyagents-runtime in its
dev-dependencies, so the entry was removed to keep the manifest accurate.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The driver subagent tool no longer accepts a mode field, so the test
fixtures and schemas that still passed mode were updated to match the
current parameter surface.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Replace references to the removed `SubAgentTool` and `SubAgentSession` with the
async `DriverSubAgentTool` and host-planned `SubagentDriver`, which return a job
reference instead of running child work inline. The runtime comparison pages and
steering README are updated to match the new delegation model.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Update Cargo.lock to reflect the current dependency graph, adding
tinyagents-orchestration and dropping tinyagents-graph and
tinyagents-runtime from the affected packages.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Replaced fully qualified crate paths with the already imported
SubAgentOutput, SubAgentPolicy, and SubAgentIncompleteKind names, and
dropped an unused serde_json::Value import. No behaviour change.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
…nd imports

The orchestration crate now depends on tinyagents-runtime for its tests, and the subagent test modules import IncompleteKind directly instead of aliasing SubAgentIncompleteKind.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Remove the unused RunConfig import from the subagent node types and have the registry test helper record a completed SubagentOutcome for successful driver results so the fixture matches real invocation behaviour.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The in-crate test_support module and its ledger_in fixture were no longer referenced by any test, so the module declaration and the now-unused IncompleteKind import in policy_tests were dropped.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The boundary tests module is no longer gated behind cfg(test), so it is compiled in all builds.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Move the cfg(test) attribute above the boundary_tests module declaration so the test-only module is only compiled during test builds.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Reword the SubAgentNode deprecation note to point at SubagentDriver and note
the node's removal in a follow-up migration, and correct the module docs to
describe the actual dependency direction between orchestration and graph.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The fixture metadata literals already specify every field, so the
functional update to the default value was unnecessary. Removing it keeps
the test setup consistent with the struct's current shape.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The job registry's insert_job took a long positional argument list, so the
parameters are now grouped into a JobInsert struct that is destructured on
entry. This keeps call sites readable and makes the metadata fields explicit
at the point of construction. An unused test module declaration was also
dropped.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Reformat the subagent driver tool and its tests, and simplify the
invocation and policy modules without changing behaviour. The
restructuring keeps the job registry and status mapping logic easier to
follow ahead of further subagent work.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Removed the Cargo test target declaration for live_subagents, which is no
longer needed now that the test is gated elsewhere.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The README, hosting guide, and LangChain parity notes now describe child
execution as host-planned through `SubagentDriver`, where every call starts an
asynchronous job and returns a stable job id. This removes references to the
retired inline/background mode split and the `invoke_hosted_in_parent` path so
the docs match the current orchestration surface.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The crate-level docs referenced the `multimodal` module with an intra-doc link that fails to resolve when the feature is disabled, so the link is replaced with plain text pointing at the module.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
@coderabbitai

coderabbitai Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 30d1cdba-0d88-4e38-9539-9ca497064289

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

senamakel and others added 4 commits October 21, 2026 22:04
The driver tool no longer references SubagentOutcomeKind, so the import was dropped to keep the module free of unused-import warnings.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The driver subagent tool test now records the planner request and verifies
the tool returns a running job that later completes with the driver result,
rather than expecting the output inline. This covers the asynchronous
spawn-and-settle behaviour and checks the task key and input passed to the
planner.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
The driver subagent tool test now expects the job agent to be "subagent" rather than "worker", matching the name the driver actually assigns.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
Wrap the recorded request assertions in an explicit block so the mutex guard is released at the end of the scope instead of relying on an explicit drop, keeping the test's locking behaviour unchanged while making the guard's lifetime clearer.

Auto-committed-on: cuttlefish
Co-authored-by: Medulla <medulla@tinyhumans.ai>
@senamakel
senamakel marked this pull request as ready for review October 22, 2026 05:29
@tinysweeper

tinysweeper Bot commented Oct 22, 2026

Copy link
Copy Markdown

Tiny Sweeper review

⏳ Reviewing 89499b2d1002 now. The last completed report, when available, remains below until this pass finishes.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-22T05:30:59.428965Z 89499b2 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@senamakel
senamakel merged commit 17c085d into tinyhumansai:epic/8088-tinyagents-slim Oct 22, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant