Swarm — fan-out dan orkestrasi agen dalam mode kode

Status: Telah dirilis — digantikan oleh docs/tools/swarm.md. Dokumen ini tetap tersedia sebagai catatan desain implementasi.

1. Apa dan mengapa

Sebuah swarm adalah banyak subagen yang diorkestrasi secara deterministik dari skrip mode kode: fan-out N pembaca, verifikasi temuan secara adversarial, sintesis melalui pemrioritas berstatus, perulangan pada gerbang keputusan. Alur kontrol (Promise.all, while, if) merupakan orkestrasi tersebut — sengaja tidak ada DSL graf, tidak ada mode baru, tidak ada permukaan alat tingkat atas baru.

Mode kode OpenClaw (QuickJS-WASI, snapshot/resume, permintaan bridge) adalah landasannya. Panggilan bridge yang diparkir bertahan melewati snapshot VM, mulai ulang gateway, dan dilanjutkan tepat di tempat berhenti — lebih kuat daripada desain pemutaran ulang jurnal, tanpa batasan determinisme pada skrip.

Penamaan: nama produk/dokumentasi adalah Swarm. Pengidentifikasi kode tetap literal: API tamu agents.*, konfigurasi tools.swarm, kolom grup swarm.

2. Keputusan (pengelola, 2026-07-17)

• Biaya: batas konfigurasi diberlakukan; anggaran token per swarm bersifat opsional. Tidak ada anggaran wajib.
• Persetujuan: turunan berjalan secara fail-closed / noninteraktif. Tindakan yang memerlukan persetujuan ditolak; penolakan dilaporkan dalam hasil turunan; skrip yang memutuskan. Tidak ada spam permintaan operator dari fan-out.
• v1 hanya berupa skrip ad hoc yang ditulis model. Alur kerja tersimpan/bernama, entri CLI/cron: nanti (mode kode headless sudah tersedia untuk cron).
• Identitas turunan: agen pekerja khusus secara default melalui konfigurasi tools.swarm.defaultAgentId (divalidasi terhadap daftar izin target subagen yang ada); penggantian agentId per spawn. Core tidak menyediakan id agen bawaan; dokumentasi merekomendasikan konfigurasi agen worker yang ramping.
• Tidak ada perubahan sumber Codex. Harness Codex menggunakan idiom spawn/wait (§8).

3. Ikhtisar arsitektur

skrip mode kode (VM QuickJS, gateway)            skrip Codex V8 (proses codex)  agents.run(...) ── panggilan bridge diparkir      tools.sessions_spawn / tools.agents_wait        │                                                │ RPC item/alat/panggilan (≤600 dtk masing-masing)        ▼                                                ▼             CORE (tidak bergantung pada harness, repo ini)  sessions_spawn {collect:true, outputSchema, fastMode, groupId}  agents_wait {ids, timeoutSeconds}        │  registri subagen (SQLite): catatan penyelesaian kolektor, id grup swarm        │  turunan = sesi subagen biasa (dibatasi lane, persetujuan fail-closed)        │  sessions.changed SSE ──► titik Control UI / bilah sisi / pesan status saluran

Satu pemilik kanonis semantik spawn/complete/settle (alat core + registri). Dua transpor await: QuickJS memarkir panggilan bridge tanpa batas waktu (snapshot); Codex melakukan polling agents_wait dalam RPC berbatas.

4. Gerbang konfigurasi (v1)

tools.swarm baru (global + penggantian per agen, pola penggabungan yang sama seperti tools.codeMode):

"tools": {  "swarm": {    "enabled": false,            // gerbang utama, default NONAKTIF    "maxConcurrent": 8,          // turunan yang berjalan bersamaan (batas lane swarm)    "maxChildrenPerGroup": 50,   // turunan aktif per grup swarm    "maxTotalPerGroup": 200,     // jumlah spawn sepanjang masa per grup (penahan proses tak terkendali)    "waitTimeoutSecondsMax": 600,    "defaultAgentId": ""         // opsional; id agen turunan ketika spawn menghilangkan agentId  }}

• Zod: union boolean | strict object seperti CodeModeSchema (src/config/zod-schema.agent-runtime.ts); swarm: true → {enabled: true}.
• Tipe di src/config/types.tools.ts (baik per agen maupun tools tingkat atas), label di schema.labels.ts, bantuan di schema.help.runtime.ts.
• Pembantu resolusi resolveSwarmConfig(cfg, agentId) yang mencerminkan resolveCodeModeConfig (src/agents/code-mode.ts:215), membatasi semua angka.
• Efek gerbang saat dinonaktifkan: alat agents_wait tidak ada dalam katalog; parameter collect/outputSchema/fastMode/groupId pada sessions_spawn ditolak dengan galat jelas yang menyebutkan kunci konfigurasi. Tidak ada perubahan perilaku lain.
• defaultAgentId divalidasi melalui resolveSubagentAllowedTargetIds (src/agents/subagent-target-policy.ts); id tidak dikenal → galat spawn, bukan fallback.

5. Core: spawn mode kolektor + agents_wait (v1)

5.1 Penambahan sessions_spawn (semuanya digerbangi oleh swarm yang diaktifkan)

• collect: boolean — jika true, proses turunan didaftarkan dengan expectsCompletionMessage: false dan catatan penyelesaian kolektor alih-alih pengiriman pengumuman/pengarahan. Alat segera mengembalikan { runId, sessionKey }. Tidak ada pengikatan saluran/thread.
• outputSchema: object — JSON Schema. Turunan mendapatkan alat sintetis structured_output yang ditambahkan ke permukaan alatnya; adendum prompt sistem menginstruksikannya untuk memanggil alat itu tepat sekali dengan hasil akhirnya. Jika validasi gagal, turunan mendapatkan satu percobaan ulang dengan dorongan; setelah itu catatan penyelesaian memuat structured: undefined beserta teks mentah dan schemaError.
• fastMode: true | "auto" | false — diteruskan ke patch sesi turunan bersama model/thinking melalui resolveSubagentModelAndThinkingPlan (src/agents/subagent-spawn-plan.ts), menggunakan sumbu FastMode yang ada (src/shared/fast-mode.ts). Dihilangkan = mewarisi.
• groupId: string — stempel grup swarm. Default ke swarm:<requesterSessionKey>:<runId-of-requesting-run>. Dipertahankan pada catatan registri dan baris sesi turunan. Digunakan untuk batas, pencantuman, pengarsipan batch, dan titik.
• label: string sudah ada — muncul dalam titik dan subagents list.
• Id agen turunan: params.agentId → jika tidak, tools.swarm.defaultAgentId → jika tidak, agen pemohon (perilaku yang ada).

5.2 Persetujuan fail-closed

Turunan kolektor berjalan dengan konteks persetujuan noninteraktif: setiap panggilan alat yang memerlukan persetujuan operator diselesaikan sebagai penolakan terstruktur (approval_required) yang terlihat oleh turunan, yang diharapkan melaporkan hambatan tersebut dalam hasilnya. Implementasi: gunakan kembali plumbing kebijakan persetujuan exec/alat yang ada dengan resolver deny yang dipaksakan untuk proses turunan mode kolektor. Tidak ada peristiwa persetujuan yang dipancarkan ke permukaan operator dari turunan kolektor.

5.3 Alat agents_wait (baru, digerbangi)

agents_wait({ ids: string[], timeoutSeconds?: number })→ {    completed: [{ runId, status: "done"|"failed"|"killed"|"timeout",                  result: string, structured?: unknown, schemaError?: string,                  sessionKey, label?, usage?: {inputTokens, outputTokens} }],    pending: string[]  }

• Kembali segera setelah setidaknya satu id selesai (semantik penyelesaian pertama / race, memungkinkan pipeline), atau saat waktu habis dengan completed: [].
• timeoutSeconds default 30, dibatasi hingga waitTimeoutSecondsMax.
• Idempoten: id yang sudah selesai mengembalikan catatannya lagi (catatan disimpan hingga pengarsipan grup). Id tidak dikenal → entri galat per id, bukan throw.
• Kepemilikan: hanya sesi yang melakukan spawn suatu proses (atau rantai induknya) yang boleh menunggu proses tersebut — aturan kepemilikan yang sama seperti wait dalam mode kode (code-mode.ts:1684).
• Registri: catatan penyelesaian berada di penyimpanan SQLite registri subagen yang ada (subagent-registry.store.sqlite.ts) — bidang baru, tanpa penyimpanan baru, tanpa kenaikan versi skema (hanya kolom aditif; lihat batasan §9).

5.4 Pemberlakuan batas

• maxConcurrent: turunan kolektor berjalan pada lane subagen yang ada, tetapi dihitung per grup swarm; spawn yang melampaui batas masuk antrean FIFO (sisi host, dalam jalur spawn — segera kembalikan runId, proses dimulai ketika slot tersedia).
• maxChildrenPerGroup / maxTotalPerGroup: spawn ditolak dengan galat bertipe setelah terlampaui; teks galat menyebutkan kunci konfigurasi.
• Kedalaman: turunan kolektor mempertahankan semantik DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH (turunan adalah daun kecuali penyarangan dikonfigurasi secara eksplisit).

6. Kontrak pengujian (v1, lane A)

• Unit: resolusi/pembatasan konfigurasi; penolakan gerbang saat dinonaktifkan; default groupId; pemberlakuan batas (antrean + penolakan); semantik race wait; idempotensi wait; penolakan kepemilikan; validasi keluaran terstruktur + percobaan ulang dengan dorongan + jalur schemaError; plumbing fastMode ke patch sesi; validasi defaultAgentId.
• Integrasi (vitest, runtime model tiruan): spawn 3 turunan kolektor, tunggu dalam perulangan, tegaskan urutan penyelesaian pertama dan pengurasan akhir; simulasi mulai ulang gateway: muat ulang registri → wait diselesaikan dari penyelesaian yang dipertahankan.
• Semua pengujian ditempatkan bersama di *.test.ts; tanpa panggilan model langsung.

7. Permukaan tamu QuickJS (lane B, setelah core)

• Global tamu dipasang di CONTROLLER_SOURCE (src/agents/code-mode.worker.ts:190-374), nama yang dicadangkan ditambahkan di code-mode-namespaces.ts:
  • agents.run(prompt, opts) → Promise<result|structured> — pemanis: spawn kolektor + await yang diparkir pada metode bridge khusus (agentWait) yang diselesaikan host saat rampung (tanpa polling; aman untuk snapshot).
  • agents.session(system, opts) → Promise<handle>; handle.send(input, opts) → Promise<...>; handle.close(). (v1.1 — dirilis setelah run(); menggunakan mode:"session" + catatan kolektor per giliran.)
  • phase(title), log(message) — notifikasi bridge fire-and-forget → peristiwa progres swarm.
• Metode bridge ditambahkan ke CodeModeBridgeMethod (code-mode.ts:91): agentSpawn, agentWait, swarmNote. agentSpawn/agentWait aman untuk pemutaran ulang berdasarkan konstruksi: kunci idempotensi (codeModeRunId, bridgeId) disimpan pada catatan registri; mulai ulang menyelesaikan ulang dari penyelesaian yang dipertahankan dan tidak pernah melakukan spawn ganda.
• Panggilan bridge agentWait yang tertunda memperpanjang TTL snapshot proses (kumpulan agen tertunda adalah sinyalnya; tanpa flag).
• Berkas virtual API.read("agents.d.ts") mendokumentasikan permukaan bertipe + idiom fan-out / gerbang / siklus (createCodeModeApiVirtualFiles, code-mode-namespaces.ts:876).

8. Proyeksi harness Codex (lane berikutnya)

• sessions_spawn (dengan parameter baru) dan agents_wait mengalir melalui bridge alat dinamis yang ada; di dalam skrip mode kode Codex, keduanya muncul sebagai tools.* secara otomatis (terverifikasi: codex-rs/code-mode/src/runtime/globals.rs:14-65, codex-rs/core/src/tools/spec_plan.rs:448-507).
• agents_wait mendapatkan kelas waktu habis alat dinamis yang panjang (batas 600 dtk; extensions/codex/src/app-server/dynamic-tool-execution.ts:37-39) dan ditandai aman untuk waktu habis/pemutaran ulang.
• Kunci grup untuk induk Codex: swarm:<parentSessionKey>:<turnId>.
• Subagen spawn_agent bawaan Codex berdampingan; baris cermin tugasnya memasok permukaan progres yang sama.

9. Persistensi dan retensi

• Tidak ada penyimpanan baru. Catatan registri memperluas tabel SQLite registri subagen yang ada; turunan adalah baris sessions biasa. Hanya kolom aditif — setiap perubahan yang memerlukan kenaikan versi skema SQLite harus terlebih dahulu mendapatkan persetujuan eksplisit pengelola (kebijakan repo).
• Id grup swarm pada catatan registri + metadata sesi turunan.
• Retensi: catatan kolektor yang selesai bertahan hingga pengarsipan grup: saat proses induk selesai (atau TTL kedaluwarsa), turunan grup diarsipkan sebagai batch (perluas sweep DEFAULT_SUBAGENT_ARCHIVE_AFTER_MINUTES yang ada agar beroperasi per grup).

10. Permukaan progres ("titik-titik") — lane berikutnya

• Implisit, digerakkan oleh harness. Diturunkan dari SSE sessions.changed + registri yang ada; catatan phase/log menambahkan semantik. Tidak ada rendering yang digerakkan agen.
• Control UI: perender swarm dalam keluarga widget ruang kerja (ui/src/lib/workspace/widgets/) — kisi titik yang dikelompokkan menurut fase, baris narator, status/label/model per titik; pohon turunan bilah sisi tidak berubah.
• Saluran: satu pesan status yang diedit dan dibatasi lajunya per grup (ikuti docs/concepts/streaming.md; jangan pernah mengirim pesan per turunan).

11. Halaman Labs (UI Kontrol, jalur independen)

Settings → Labs: tombol fitur eksperimental, entri pertama Mode Kode dan Swarm. Setiap baris: nama, deskripsi satu baris, tautan dokumentasi, tombol yang terhubung melalui RPC config.patch yang sudah ada (merge-patch RFC 7396 — tetapkan tools.codeMode.enabled / tools.swarm.enabled), ditambah petunjuk "perlu dimulai ulang" jika berlaku. Mudah ditemukan, tetapi teksnya memperjelas status eksperimental. i18n: semua string melalui pipeline en.ts + sinkronisasi normal.

12. Penempatan (nanti)

• placement pilihan saat spawn: "local" (default) | "cloud:<profile>" melalui pengiriman lingkungan worker yang sudah ada (sessions.dispatch); penempatan terkelompok nanti jika proses turunan sandbox SSH pada shared-box terbukti tidak memadai.
• VM Orchestrator selalu tetap berada di gateway; settle/dots/budget tidak bergantung pada penempatan.

13. Bukan tujuan

• Tidak ada DSL graf — alur kontrol adalah grafnya (disengaja, terdokumentasi).
• Tidak ada perubahan sumber Codex; tidak ada penggunaan ulang internal Mode Kode Codex.
• Tidak ada alur kerja tersimpan/bernama dalam v1; tidak ada titik masuk CLI.
• Tidak ada penerusan persetujuan operator per proses turunan.
• Tidak ada penyediaan cloud 1:1 pada skala fan-out.
• Tidak ada shim kompatibilitas runtime dalam kondisi stabil; swarm adalah permukaan baru yang dibatasi.

14. Fase pembangunan / pembagian PR

1. Jalur A (inti): konfigurasi §4 + spawn/wait/caps/approvals §5 + pengujian §6.
2. Jalur C (halaman Labs): §11 — independen, dapat digabungkan lebih dahulu.
3. Jalur B (permukaan QuickJS): §7 — setelah kontrak A digabungkan.
4. Perender dots (§10), proyeksi Codex (§8), agents.session (§7 v1.1), penempatan (§12), penulisan ulang dokumentasi pengguna — PR tindak lanjut dalam urutan tersebut.

Setiap PR: Pipeline CI hijau, $autoreview bersih, dinonaktifkan secara default, main siap dirilis.