You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by "Joob1n (via GitHub)" <gi...@apache.org> on 2026/08/23 05:21:44 UTC
[PR] docs: correct the multi-agent orchestration documents [maka]
Joob1n opened a new pull request, #3555:
URL: https://github.com/apache/maka/pull/3555
## Summary
The Multi-agent orchestration group from #3522. Four documents were audited; three needed changes.
**`docs/agent-swarm.md` documented a tool that no longer exists.** The whole document was built around an `agent_swarm` tool taking `items`, a `prompt_template` and `resume_run_ids`. #2384 deleted `packages/runtime/src/agent-swarm-tools.ts` — where `AGENT_SWARM_TOOL_NAME = 'agent_swarm'` was defined — along with `adaptive-swarm.ts`, and replaced synchronous fan-out with asynchronous supervision over the Agent Graph. `agent_swarm` survives only as a tool-result kind on historical records, so a reader following this document would call a tool that is not in the catalog.
Rewritten around what swarm actually is now: an orchestration mode, not a tool. It is entered with `/swarm on|off|status|<task>` and changes four things — the system prompt, a guaranteed tool set that deliberately omits `view_agent_graph`, the durable `agentSwarmAuthorization` field on the Run header, and its own supervisor-wake rule. Items are ordinary child Sessions scheduled as graph work, and `agent_swarm_status` projects the same graph snapshot, where `swarmId` is the `graphId`.
**The Agent Graph chapter had four smaller defects**, corrected in both languages so `translation_status: synced` stays true:
- `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 `agent-graph-panel.tsx` imports 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" — the removed synchronous model.
- The same table listed Agent Team beside four real mechanisms, but `AgentTeam`, `agent_team` and `mailbox` appear nowhere in the code. The row was removed and the section heading updated to match the rows that remain.
**`docs/side-conversation.md` needs no change.** Its unresolved symbols (`excludeTurns`, `moveTabTo`, `receiveMovedTab`, `preserveOnClose`, `onBeforeClose`) all sit inside the Codex Reference and Desktop Architecture Snapshot sections, which describe OpenAI Codex and carry their own inspection date.
Refs #3522
## Verification
Claims in the rewritten document, each checked against the code:
| Claim | Check | Result |
|---|---|---|
| `agent_swarm` tool existed and was deleted | `git show 08b745028^:packages/runtime/src/agent-swarm-tools.ts \| grep TOOL_NAME` | `AGENT_SWARM_TOOL_NAME = 'agent_swarm'`; file deleted by that commit |
| no `agent_swarm` tool today | `grep -n "name: 'agent" packages/core/src/tool-catalog.ts` | `agent_spawn`, `agent_list`, `agent_output`, `agent_swarm_status` |
| `/swarm` grammar | `packages/core/src/swarm-command.ts` | `status` / `on` / `off` / `run_once` |
| prompt injection | `packages/runtime/src/ai-sdk-backend.ts:1734` | appended when `mode === 'swarm'` |
| guaranteed tool set | `packages/runtime/src/ai-sdk-backend.ts:1670-1687` | swarm set omits `view_agent_graph`; graph set includes it |
| durable authorization | `packages/core/src/orchestration.ts:84,91`, `agent-run.ts:165` | `session_mode` / `turn_override` / `none` |
| swarm wake rule | `packages/runtime/src/stream-graph-coordinator.ts:1715` | `isSwarmCheckpointTransition` |
| `swarmId` is `graphId` | `packages/runtime/src/agent-swarm-status-tool.ts:79` | `swarmId: snapshot.graphId` |
| status enums | same file, lines 28-70 | 9 item statuses; attention set is blocked/failed/aborted/cancelled |
| the missing IPC file | `ls apps/desktop/src/main/agent-graph-ipc-main.ts` | No such file |
| the missing test | `find . -name 'graph-mode-host-contract*'` | no matches |
| Agent Team absent | `grep -rn "AgentTeam\|agent_team\|mailbox" packages/ apps/` | no matches outside docs |
Every `packages/...` and `apps/...` path in both reading maps was re-checked after the edit; all resolve.
Repository checks:
```
npm run format:check Checked 1597 files. No fixes applied.
npm run check:asf-source fail 0
```
No test covers prose and this PR changes no code, so no suite was added. `npm test` was not run.
## AI use
Select exactly one:
- [ ] No generative tool made a substantive contribution
- [x] Generative tooling made a substantive contribution
Tool(s) and scope: Claude Opus 5 via Claude Code — audited the four documents against the code, traced the swarm removal through `git show`, drafted the rewrite and the bilingual corrections. Every row in the table above was produced by running the listed command. The commit carries a `Generated-by` trailer.
## Checklist
- [ ] Tests cover the change and fail without it
- [x] Lint, format, typecheck and the affected suites pass locally
Does this PR entail a change in behavior?
- [ ] Yes — described under Summary above
- [x] No
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [PR] docs: correct the multi-agent orchestration documents [maka]
Posted by "Astro-Han (via GitHub)" <gi...@apache.org>.
Astro-Han merged PR #3555:
URL: https://github.com/apache/maka/pull/3555
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org