Skip to content

feat(runtime): decouple Swarm with asynchronous wakeups - #2384

Merged
likun666661 merged 6 commits into
apache:mainfrom
likun666661:feat/async-swarm-wake
Aug 7, 2026
Merged

feat(runtime): decouple Swarm with asynchronous wakeups#2384
likun666661 merged 6 commits into
apache:mainfrom
likun666661:feat/async-swarm-wake

Conversation

@likun666661

@likun666661likun666661 commented Aug 7, 2026

Copy link
Copy Markdown
Member

Summary

  • make Swarm Mode schedule independent work through the durable Agent Graph and yield instead of waiting synchronously
  • wake the parent only when an item fails or blocks, or when every item has settled
  • add agent_swarm_status, a compact status-only projection that excludes child logs, tool activity, reasoning, instructions, and partial output
  • preserve a selected subagent_id model and connection when Graph provisions child sessions; the resolved agent id remains the durable topology key
  • remove the synchronous agent_swarm executor, adaptive scheduler, exports, catalog entry, and host bindings from Desktop, CLI, and Headless
  • retain only the legacy result decoder and projections required to read existing session history

Behavior

  1. The parent calls agent_list and schedules up to 32 preset-backed work items with update_agent_graph.
  2. The parent calls yield_agent_graph; dispatch and normal running transitions do not wake it.
  3. A durable host wake occurs on failure or attention, or after the entire batch settles.
  4. The parent reads compact statuses and committed final results, replaces failed work explicitly, and yields again or finishes.
  5. Loading the Agent tool group never exposes agent_swarm; the asynchronous Graph path is the only batch execution path.

Validation

  • @maka/core, @maka/runtime, CLI, Headless, and Desktop main-process builds pass
  • 203 cross-host tool-surface tests pass
  • 154 Runtime and Headless execution-boundary tests pass
  • full Runtime suite: 3329 passed, 9 skipped, 1 unrelated existing environment assertion failed because the local macOS sandbox argv did not contain the hard-coded /usr/local executable root expected by builtin-tools.test

Notes

This is intentionally a draft for hands-on behavior testing. It reuses the existing SQLite-backed Agent Graph control plane instead of introducing a second background scheduler. Historical agent_swarm result decoding remains data compatibility only and is not callable.

@likun666661
likun666661 marked this pull request as ready for review August 7, 2026 06:37
@xxhZs

xxhZs commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Thanks for pushing the Swarm orchestration onto the durable Agent Graph. I found three blocking behavior gaps at 4d439dcf:

  1. Headless stops the graph immediately after the yielding parent turn.packages/headless/src/runner.ts drains only the initial sendMessage, then calls sessionCapabilities.settle(). settle() calls graphCoordinator.stop(sessionId) before waiting for managed operations. With the new flow (update_agent_graphyield_agent_graph), this cancels the asynchronous children before any supervisor wake or synthesis turn can run. The Task Agent and Harbor paths share this settlement behavior. Please add a Headless E2E covering schedule → yield → children settle → supervisor wake → synthesis, and keep the graph alive until it is actually finished.

  2. A failed or blocked item cannot wake the parent while siblings are still running.reconcileAgentGraphSchedule() awaits Promise.all() over every dispatched item, while hosts call the wake coordinator only from AgentGraphCoordinator.onReconciliation, after that promise returns. Runtime attention/terminal events only update the projection and request another drive. If item A fails or blocks quickly while item B runs for a long time, the parent is not woken until B settles, contrary to the PR contract. The wake path needs to be driven from the durable attention/terminal checkpoint rather than only the completed reconciliation batch.

  3. Reconciliation failures are invisible in agent_swarm_status. Desktop wakes when result.failures.length > 0, but the status tool projects only scheduled work and operator runtime state. Provision/render/dispatch failures therefore remain queued or running, and the wake prompt does not include the failed work id. The supervisor cannot know which work to replace and can enter a yield/retry loop. Please persist/project a bounded failure state keyed by work id (including phase/reason), so the same information survives recovery.

There is also a cross-host consistency gap: the Swarm-specific shouldWake/renderWake policy is wired only in Desktop and checks the persisted Session header. CLI and Runtime Host still use the generic Graph wake, and a one-shot /swarm <task> on a default Desktop Session also misses the Swarm path because only the Run carries the turn override. This policy should be shared across hosts and keyed by the durable orchestration identity of the active graph/run, not only the Session default.

The focused Runtime/Runtime Host tests pass, but they do not exercise these end-to-end host lifecycle cases.

@likun666661

Copy link
Copy Markdown
MemberAuthor

@xxhZs Thanks for the detailed review. Addressed all four gaps in 9336ed0:

  1. Headless lifecycle: runner, Task Agent, and Harbor now keep the graph and wake coordinator alive after the yielding parent turn. Root turns share the same activity registry as supervisor wakes, so a fast child checkpoint cannot start a competing supervisor turn. Added an E2E covering schedule -> yield -> children settle -> parent completion -> supervisor wake -> status read -> synthesis/finish.

  2. Early failure wake: reconciliation now emits a durable work-keyed failure checkpoint as soon as an individual provision/render/dispatch fails, without waiting for slower siblings. Runtime attention/terminal projection transitions also notify the wake coordinator, with transition de-duplication.

  3. Durable failure status: bounded reconciliation failures (work id, phase, reason) are persisted in the graph read model, survive coordinator recovery, and override the corresponding agent_swarm_status item to failed.

  4. Cross-host identity/policy: the first durable schedule source records graph vs swarm orchestration identity, including one-shot turn overrides. Desktop, CLI, Runtime Host, and Headless now use the shared swarm shouldWake/renderWake policy instead of relying only on the Session default.

Validation:

  • Headless related suites: 162/162
  • Runtime focused suites: 37/37
  • Runtime Host full suite: 733/733
  • Core, Runtime, CLI, Runtime Host, Headless, and Desktop builds pass
  • Biome and git diff --check pass

I left the review state unresolved so you can verify the behavior and close it when satisfied.

# Conflicts:
#	packages/runtime/src/__tests__/agent-swarm-tools.test.ts
@likun666661
likun666661 merged commit 08b7450 into apache:mainAug 7, 2026
12 checks passed
Astro-Han pushed a commit that referenced this pull request Aug 23, 2026
* docs: correct the multi-agent orchestration documents
`docs/agent-swarm.md` still documented an `agent_swarm` tool that takes
`items`, a `prompt_template` and `resume_run_ids`. That tool was removed
in #2384, which deleted `agent-swarm-tools.ts` (where
`AGENT_SWARM_TOOL_NAME = 'agent_swarm'` was defined) together with
`adaptive-swarm.ts`, and replaced them with asynchronous supervision over
the Agent Graph. `agent_swarm` survives only as a tool-result kind.
Rewritten to describe what swarm is now: an orchestration mode rather
than a tool. The mode is entered with `/swarm on|off|status|<task>` and
changes four things — the system prompt, a guaranteed tool set that
omits `view_agent_graph`, the durable `agentSwarmAuthorization` field on
the Run header, and its own supervisor-wake rule in
`isSwarmCheckpointTransition`. Items are ordinary child Sessions
scheduled as graph work, and `agent_swarm_status` is a projection over
the same graph snapshot, where `swarmId` is the `graphId`.
The Agent Graph chapter carried four smaller defects, corrected in both
languages:
- `apps/desktop/src/main/agent-graph-ipc-main.ts` does not exist. Graph
change events travel through `runtime-host-session-domains-ipc-main.ts`
as `agentGraphChanged`, and the panel takes its types straight from
`@maka/runtime-host/client` and `@maka/runtime-host/protocol`.
- `apps/desktop/src/main/__tests__/graph-mode-host-contract.test.ts` was
deleted and has no successor.
- The comparison table described Agent Swarm as "one foreground tool call
owns a bounded worker pool", which is the removed synchronous model.
- The same table listed Agent Team beside four real mechanisms, but
`AgentTeam` / `agent_team` / `mailbox` appear nowhere in the code.
`docs/side-conversation.md` was audited as part of this group and needs
no change: its unresolved symbols all sit in the Codex Reference and
Desktop Architecture Snapshot sections, which describe OpenAI Codex
rather than Maka.
Refs #3522
Generated-by: Claude Opus 5 via Claude Code
* docs: separate swarm's supervision policy from the graph's machinery
The rewrite said swarm adds no execution machinery of its own and that
wake state lives in the graph control plane, then described a
mode-specific wake rule a few paragraphs later. Both are true — the
graph stores wake state, while `isSwarmCheckpointTransition` decides
when a swarm checkpoint is worth waking the supervisor for — but stated
side by side they read as a contradiction.
Say the split once, up front: one scheduler, one ledger, one control
plane, all the graph's; what the mode adds is supervision policy over
them.
Refs #3522
Generated-by: Claude Opus 5 via Claude Code
Sign up for freeto 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.

2 participants

@likun666661@xxhZs