@sigmacamellia/dsh-dynamic-workflow 0.0.0-stage → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,794 @@
1
+ # Dynamic workflow patterns
2
+
3
+ A catalogue of orchestration shapes. Each entry states when the shape is right, then shows
4
+ it written correctly. Interfaces are elided where they are obvious — your script must
5
+ define every type it names.
6
+
7
+ The snippets here are **fragments, not runnable scripts**: they name types and subagents that
8
+ the surrounding prose leaves to you. Complete scripts live in `examples.md`.
9
+
10
+ **Start with the pipeline shapes.** Most scripts have more than one stage, and the stages
11
+ should work at the same time, each item moving on as soon as it is ready (SKILL.md §7). #10
12
+ chains stages that map one to one inside one fan-out; #11 streams items between stages through
13
+ channels; #12 adds a feedback loop from a later stage to an earlier one. The other shapes are
14
+ the pieces those pipelines are built from.
15
+
16
+ For the API surface itself, read SKILL.md §16. For the reasoning behind these choices, read
17
+ the rest of `SKILL.md`.
18
+
19
+ ---
20
+
21
+ ## 1. Fan-out / fan-in over a glob
22
+
23
+ **When:** the same independent question about every file in a set, and you want them
24
+ answered at once.
25
+
26
+ ```ts
27
+ phase("Find the files to audit");
28
+ const paths = await files.glob("src/**/*.ts");
29
+ log(`fanning out over ${paths.length} files`);
30
+
31
+ phase("Security-audit each file independently");
32
+ // The report below needs every verdict, so this join is the right one.
33
+ const verdicts = await Promise.all(
34
+ paths.map((p) =>
35
+ agent(`auditor-${p}`).ask<Verdict>(`Security-review ${p}. Report only real issues.`),
36
+ ),
37
+ );
38
+
39
+ phase("Report the files that failed");
40
+ return verdicts.filter((v) => !v.approved).map((v) => ({ path: v.path, reason: v.reason }));
41
+ ```
42
+
43
+ A fresh subagent per path is the point: the questions are unrelated, so there is nothing to
44
+ share and everything to parallelize. Do not hoist `agent(...)` above the `map`.
45
+
46
+ The name carries the path because subagent names must be unique within a run: `agent("auditor")`
47
+ inside the `map` would create one subagent per file all claiming the same name, which is rejected
48
+ at compile time. `` `auditor-${p}` `` is also what lets a revised re-run (`amend_workflow`) keep
49
+ the verdicts for files whose question did not change. Anonymous — `agent()` — is legal too,
50
+ and starts every file with an empty context.
51
+
52
+ **Narrow before you fan out.** A glob over a large repository is a large fan-out. If only
53
+ some files can possibly matter, find them first:
54
+
55
+ ```ts
56
+ const hits = await files.grep("dangerouslySetInnerHTML", "src/**/*.tsx");
57
+ const paths = [...new Set(hits.map((h) => h.path))];
58
+ ```
59
+
60
+ `files.grep` rejects rather than truncating when it overruns its cap, so a pattern that is
61
+ too broad fails loudly instead of handing you a partial file list to fan out over.
62
+
63
+ ---
64
+
65
+ ## 2. Changed-file review sweep
66
+
67
+ **When:** reviewing work in progress rather than the whole tree.
68
+
69
+ ```ts
70
+ phase("Find the work in progress");
71
+ let paths: string[];
72
+ try {
73
+ paths = await git.changedFiles("origin/main");
74
+ } catch {
75
+ paths = await files.glob("src/**/*.ts");
76
+ }
77
+
78
+ phase("Review each changed file for bugs");
79
+ const reviews = await Promise.all(
80
+ paths.map((p) => agent(`reviewer-${p}`).ask<Review>(`Review ${p} for correctness bugs.`)),
81
+ );
82
+ ```
83
+
84
+ Every `git` call rejects outside a repository or with no `git` available, so the `try`/`catch`
85
+ with a `files.glob` fallback is the idiom, not defensive padding.
86
+
87
+ When the reviewer needs the change rather than the file, hand it the diff — but per path, so
88
+ no single prompt carries the whole changeset:
89
+
90
+ ```ts
91
+ const perFile = await Promise.all(
92
+ paths.map(async (p) => {
93
+ const patch = await git.diff("origin/main", p);
94
+ return agent(`reviewer-${p}`).ask<Review>(`Review this change to ${p}:\n\n${patch}`);
95
+ }),
96
+ );
97
+ ```
98
+
99
+ `git.diff` is capped and rejects rather than truncating, so narrow it to a path when the
100
+ whole-workspace diff would be large.
101
+
102
+ Then confirm before you report — per file, as each review lands, not after all of them. The
103
+ reviewer that raised a finding does not get to confirm it — a subagent asked to check its own
104
+ work grades generously — so each finding goes to a fresh confirmer that reproduces it from the
105
+ evidence alone and is told not to fix anything. Chaining the confirmers inside the same
106
+ callback means the slowest reviewer holds up only its own file:
107
+
108
+ ```ts
109
+ phase("Review each changed file and confirm its findings as they land");
110
+ const confirmed = (
111
+ await Promise.all(
112
+ paths.map(async (p) => {
113
+ const review = await agent(`reviewer-${p}`).ask<Review>(`Review ${p} for correctness bugs.`);
114
+ return Promise.all(
115
+ review.findings.map(async (finding, index) => {
116
+ const check = await agent(`confirmer-${p}-${index}`).ask<Confirmation>(
117
+ `Reproduce this finding from its evidence alone. Do not edit any file.\n${JSON.stringify(finding)}`,
118
+ );
119
+ const reported = { ...finding, status: check.reproduced ? "verified" : "unconfirmed" };
120
+ report(reported);
121
+ return reported;
122
+ }),
123
+ );
124
+ }),
125
+ )
126
+ ).flat();
127
+ ```
128
+
129
+ What fails confirmation is kept and labelled, not dropped. The review fan-out above and this
130
+ one are the same shape written twice for exposition; in a real script write only this one.
131
+
132
+ ---
133
+
134
+ ## 3. Planner ↔ reviewer loop
135
+
136
+ **When:** the first attempt at something is rarely right, and a critic can say why.
137
+
138
+ ```ts
139
+ const planner = agent("planner", "You write concrete, minimal implementation plans.");
140
+ const reviewer = agent("reviewer", "You find the flaw in a plan. Approve only when you cannot. You never edit files.");
141
+
142
+ let feedback = "none";
143
+ for (let round = 0; round < 5; round++) {
144
+ phase("Draft a plan for the change");
145
+ const plan = await planner.ask<Plan>(`Plan the change. Previous critique: ${feedback}`);
146
+ phase("Critique the plan until it holds");
147
+ const review = await reviewer.ask<Review>(`Critique this plan:\n${JSON.stringify(plan)}`);
148
+ if (review.approved) return plan;
149
+ log(`round ${round + 1} rejected: ${review.feedback}`);
150
+ feedback = review.feedback;
151
+ }
152
+ ```
153
+
154
+ Both subagents are created **once, outside the loop**. That is what makes the loop cheap: each
155
+ keeps its accumulated context across rounds, so the planner remembers what it already tried
156
+ and the reviewer remembers what it already objected to. Creating them inside the loop throws
157
+ that away every round and pays full price for it.
158
+
159
+ The reviewer's persona says it never edits files: that is what keeps it critiquing the plan
160
+ instead of quietly "fixing" it. When critiquing the plan is reading a string, it simply never
161
+ opens a file; when the plan is about code, tell it to read the code — a reviewer that has not
162
+ opened the files can only judge whether the plan is coherent, not whether it is right.
163
+
164
+ By the last round the persistent reviewer is anchored on its own earlier objections. Put the
165
+ final plan in front of eyes that have seen nothing else, and ask for failures rather than
166
+ approval:
167
+
168
+ ```ts
169
+ phase("Independent review of the final plan");
170
+ const second = await agent("independent-reviewer", "You review plans and never edit files.").ask<Review>(
171
+ `You have not seen this plan before. Read it against the codebase. What would break it, and what is missing?
172
+ ${JSON.stringify(plan)}`,
173
+ );
174
+ if (!second.approved) feedback = second.feedback;
175
+ ```
176
+
177
+ ---
178
+
179
+ ## 4. Judge panel: independent, or calibrated
180
+
181
+ **When:** a finding needs a second opinion. Two shapes, and the difference matters.
182
+
183
+ **Independent** — N fresh contexts, each blind to the others. Use for a majority vote,
184
+ where correlated judges would defeat the purpose:
185
+
186
+ ```ts
187
+ phase("Judge the finding from three angles");
188
+ // A majority needs every vote, so the join waits for all three.
189
+ const votes = await Promise.all(
190
+ ["correctness", "security", "does-it-reproduce"].map((lens) =>
191
+ agent(`judge-${lens}`)
192
+ .ask<Verdict>(`Judge this finding through the ${lens} lens. Try to refute it:\n${claim}`),
193
+ ),
194
+ );
195
+ const survives = votes.filter((v) => !v.refuted).length >= 2;
196
+ ```
197
+
198
+ Giving each judge a distinct lens beats three identical refuters: diversity catches failure
199
+ modes that redundancy cannot.
200
+
201
+ **Calibrated** — one context that sees every item, so its verdicts are consistent with each
202
+ other. Use for ranking and severity, where "high" has to mean the same thing twice:
203
+
204
+ ```ts
205
+ phase("Rank every finding on one scale");
206
+ const triage = agent("triage", "You rank findings on one consistent scale across a whole batch.");
207
+
208
+ const ranked: Ranked[] = [];
209
+ for (const finding of findings) {
210
+ ranked.push(await triage.ask<Ranked>(`Rank: ${JSON.stringify(finding)}`));
211
+ }
212
+ ```
213
+
214
+ The `for`/`await` is deliberate here — asks on one subagent queue FIFO anyway, so writing it as
215
+ a `Promise.all` would only hide the serialization, not remove it.
216
+
217
+ A queue is not a barrier, though. The calibrated subagent does not need the whole batch in
218
+ hand before it starts: feed it each item as the stage before produces it (from inside that
219
+ stage's fan-out callback, SKILL.md §11) and its verdicts stay consistent while the pipeline
220
+ keeps moving.
221
+
222
+ Either way, a judge's verdict is a judgement, not a reproduction: a finding that survived the
223
+ panel still enters the report as `unconfirmed` unless a confirmer or a `world.run` check
224
+ reproduced it.
225
+
226
+ ---
227
+
228
+ ## 5. Loop until approved, with a real escape
229
+
230
+ **When:** a bounded loop that must still return something useful when it runs out of rounds.
231
+
232
+ ```ts
233
+ let best: Attempt | undefined;
234
+ for (let round = 0; round < 6; round++) {
235
+ phase("Attempt the fix");
236
+ const attempt = await worker.ask<Attempt>(`Attempt the fix. Prior failure: ${lastError ?? "none"}`);
237
+ phase("Check whether it actually passes");
238
+ const check = await checker.ask<Check>(`Does this pass? ${JSON.stringify(attempt)}`);
239
+ if (check.passed) return { attempt, rounds: round + 1, converged: true };
240
+ best = attempt;
241
+ lastError = check.reason;
242
+ }
243
+ return { attempt: best, rounds: 6, converged: false };
244
+ ```
245
+
246
+ Return the shape that says **whether it converged**, not just the result. A caller that
247
+ cannot tell "approved on round two" from "gave up after six" will treat the second as the
248
+ first. Never let the loop fall off the end returning nothing.
249
+
250
+ ---
251
+
252
+ ## 6. Staged handoff with typed results
253
+
254
+ **When:** each stage narrows or transforms what the next one works on, and the last stage
255
+ needs everything the one before it produced.
256
+
257
+ ```ts
258
+ phase("Survey which modules touch auth");
259
+ const survey = await agent("surveyor").ask<Survey>("List the modules that touch auth.");
260
+ log(`${survey.modules.length} modules in scope`);
261
+
262
+ phase("Analyse each module for auth bypasses");
263
+ // The write-up deduplicates across modules, so it needs every analysis at once.
264
+ const analyses = await Promise.all(
265
+ survey.modules.map((m) =>
266
+ agent(`analyst-${m.path}`).ask<Analysis>(
267
+ `Analyse ${m.path} for auth bypasses. Purpose: ${m.purpose}`,
268
+ ),
269
+ ),
270
+ );
271
+
272
+ phase("Write the findings up for the engineer who fixes them");
273
+ const synth = agent("synthesist", "You write findings up for an engineer who will fix them.");
274
+ return synth.ask<Writeup>(`Write these up, deduplicated:\n${JSON.stringify(analyses)}`);
275
+ ```
276
+
277
+ Each stage's result is the next stage's input, and the type argument is what makes the
278
+ handoff safe — `survey.modules.map` only compiles because `Survey` says what came back.
279
+
280
+ Note the shape of the last call: a single synthesis subagent gets everything at once, because
281
+ deduplicating across findings is exactly the job that needs to see all of them. Do not
282
+ parallelize a stage whose whole purpose is cross-item comparison.
283
+
284
+ The converse holds too. The analysis stage maps one to one onto the survey's modules, so if a
285
+ per-module check followed it, that check would belong inside the same callback as the
286
+ analysis — not behind a second `Promise.all` (shape 10). Reserve the barrier for the stage
287
+ that needs everyone.
288
+
289
+ ---
290
+
291
+ ## 7. Bounded discovery
292
+
293
+ **When:** the work has no natural size — "find the bugs" rather than "check these twelve
294
+ files."
295
+
296
+ ```ts
297
+ const MAX_ROUNDS = 6;
298
+ const found: Bug[] = [];
299
+ const seen = new Set<string>();
300
+
301
+ for (let round = 1; round <= MAX_ROUNDS; round++) {
302
+ phase("Hunt for bugs not already found");
303
+ const batch = await agent("hunter").ask<Bugs>(
304
+ `Find bugs not already in this list: ${JSON.stringify([...seen])}`,
305
+ );
306
+ const fresh = batch.bugs.filter((b) => !seen.has(`${b.path}:${b.line}`));
307
+ if (fresh.length === 0) break; // dry: stop, the remaining rounds would only repeat
308
+
309
+ for (const bug of fresh) {
310
+ seen.add(`${bug.path}:${bug.line}`);
311
+ report(bug);
312
+ found.push(bug);
313
+ }
314
+ log(`${found.length} found after round ${round}`);
315
+ }
316
+ return found;
317
+ ```
318
+
319
+ Two guards, and you need both: the round cap keeps the loop from running forever when the
320
+ hunter keeps finding things, and the dry check stops it once the hunter stops finding anything
321
+ new. The cap is a knob you pick and amend in the script — the harness enforces no node limit,
322
+ so a loop without one only ends when the user cancels the run. Deduplicate against everything
323
+ **seen**, not against everything kept — dedup against the kept list makes rejected findings
324
+ reappear every round and the loop never converges.
325
+
326
+ ---
327
+
328
+ ## 8. Salvage by report
329
+
330
+ **When:** always, in any run long enough to fail partway.
331
+
332
+ ```ts
333
+ // Wrong: forty tasks of work, and a failure on task twelve returns nothing.
334
+ const results: Result[] = [];
335
+ for (const item of items) results.push(await worker.ask<Result>(`Handle ${item.id}`));
336
+ return results;
337
+
338
+ // Right: each result is published the moment it exists.
339
+ phase("Handle each item and publish as it lands");
340
+ const results: Result[] = [];
341
+ for (const item of items) {
342
+ const result = await worker.ask<Result>(`Handle ${item.id}`);
343
+ report(result);
344
+ results.push(result);
345
+ }
346
+ return results;
347
+ ```
348
+
349
+ Reported items are delivered with the completion notification on errored and stopped runs
350
+ as well as successful ones, and they are recorded, so a resumed run does not re-emit them.
351
+ The return value only survives if the script reaches its `return`; reported items survive
352
+ regardless. Report findings, not chatter — there is a per-run item cap, and overrunning it
353
+ fails the run.
354
+
355
+ The same call can feed a picture. Tag the item with a preset artifact id —
356
+ `report(result, "progress")` — and it lands both in the run's results and on the chart,
357
+ table, metrics or board of that name, live as the loop goes (SKILL.md §10).
358
+
359
+ A `try`/`catch` around a single task turns one **logic** failure — a subagent result that
360
+ failed validation, a gate that did not pass, a world read over its cap, an artifact publish
361
+ whose file is missing — into a partial result instead of a dead run. It is not for provider
362
+ errors: model-side errors never reach the script. Transient ones (rate limits, overload,
363
+ network errors, timeouts, unknown provider errors) are retried by the runtime without limit;
364
+ deterministic ones (sign-in expired, model not in the plan, quota cap) stop the whole run as
365
+ `stopped` so the user can fix the cause and resume it. A retry loop around an ask for their
366
+ sake is dead code. The one model-adjacent error a script can catch is `ContextLimit`: the
367
+ ask itself was too large for the model even after compaction, and the fix is a smaller ask.
368
+
369
+ ```ts
370
+ for (const item of items) {
371
+ try {
372
+ report(await worker.ask<Result>(`Handle ${item.id}`));
373
+ } catch (error) {
374
+ log(`skipped ${item.id}: ${String(error)}`);
375
+ }
376
+ }
377
+ ```
378
+
379
+ ---
380
+
381
+ ## 9. Gated verifier loop (world.run)
382
+
383
+ **When:** the stopping condition is machine-checkable — a build, a proof checker, a test
384
+ suite — and a subagent's claim of success is not worth trusting.
385
+
386
+ ```ts
387
+ const prover = agent("prover", "You repair the proof. Fix exactly what the checker reports.");
388
+
389
+ phase("Write the first proof attempt");
390
+ await prover.ask<Attempt>(`Prove the open theorem in ${FILE}.`);
391
+ let clean = false;
392
+ for (let round = 1; round <= 8; round++) {
393
+ phase("Check the file with the fast checker");
394
+ const check = await world.run("lake", ["env", "lean", FILE], { timeoutMs: 600_000 });
395
+ clean = check.exitCode === 0 && !check.stderr.includes("sorry");
396
+ if (clean) break;
397
+ log(`round ${round}: checker rejected`);
398
+ phase("Repair what the checker rejected");
399
+ await prover.ask<Attempt>(`The checker rejected the file:\n${check.stderr}\nRepair ${FILE}.`);
400
+ }
401
+ if (!clean) return { proved: false };
402
+
403
+ phase("Build the whole project once before handing over");
404
+ const build = await world.run("lake", ["build"], { timeoutMs: 1_800_000 });
405
+ return { proved: build.exitCode === 0 };
406
+ ```
407
+
408
+ The subagent does the open-ended work; the script does the judging, and the judgment is not
409
+ delegable. `world.run` executes the checker for real, so "verified" is never a claim — only
410
+ an exit code. A nonzero exit is a **value**, which is why the loop reads `check.exitCode`
411
+ and feeds `check.stderr` forward instead of catching anything; rejections are reserved for
412
+ the world failing to answer (spawn failure, timeout, output over the cap), and a
413
+ `try`/`catch` around the call is how a script chooses a fallback for those.
414
+
415
+ Two tiers, and the difference is the whole point. The per-file checker is the fast tier: it
416
+ answers in seconds, so it drives the rounds. It is not the verdict — `lake env lean` exits
417
+ 0 on a proof that still says `sorry` and only warns on stderr, which is why the loop reads
418
+ stderr too. The whole-project build is the strong tier: it is what the request was about,
419
+ and it runs once at the end even though the fast tier already said yes. Pick both tiers by
420
+ reading the repository — the README's "run this to verify" line, the `Makefile`, the
421
+ `package.json` scripts — never from habit; the strongest check the repository offers for
422
+ what the user asked is the one that decides (SKILL.md §5).
423
+
424
+ The command name is a compile-time literal by rule — the user approves the script's command
425
+ set at confirmation — so interpolate paths, flags and round numbers into the **args**,
426
+ never into the command. Compare shape 5: same loop, but there the checker was a subagent;
427
+ prefer this shape whenever a real command can render the verdict.
428
+
429
+ ---
430
+
431
+ ## 10. Per-item pipeline
432
+
433
+ **When:** two or more stages map one to one — a hunter per file and a confirmer per finding,
434
+ a migrator per file and a checker per file — and nothing in the later stage needs to see the
435
+ whole earlier stage.
436
+
437
+ ```ts
438
+ phase("Hunt for bugs in each file and confirm them as they are found");
439
+ const confirmed = (
440
+ await Promise.all(
441
+ paths.map(async (p) => {
442
+ const hunt = await agent(`hunter-${p}`).ask<Hunt>(`Hunt for correctness bugs in ${p}.`);
443
+ return Promise.all(
444
+ hunt.bugs.map(async (bug, index) => {
445
+ const check = await agent(`confirmer-${p}-${index}`).ask<Confirmation>(
446
+ `Reproduce this bug from its evidence alone. Do not edit any file.\n${JSON.stringify(bug)}`,
447
+ );
448
+ const reported = { ...bug, status: check.reproduced ? "verified" : "unconfirmed" };
449
+ report(reported);
450
+ return reported;
451
+ }),
452
+ );
453
+ }),
454
+ )
455
+ ).flat();
456
+ ```
457
+
458
+ One join, at the end, where the report needs every item. Compare the two-barrier version —
459
+ `Promise.all` over the hunters, then `Promise.all` over the confirmers — which starts no
460
+ confirmer until the slowest hunter is done and leaves the concurrency slots idle in between.
461
+ The cache identity of a revised re-run is unchanged: each subagent is still named and asked in
462
+ the same order.
463
+
464
+ One phase covers the whole pipeline, named for what it does to each item. Do not put a marker
465
+ per stage inside the callback: the run has one current phase, and concurrent callbacks
466
+ re-entering two markers out of order would stamp each other's steps.
467
+
468
+ When one item failing should cost one item, catch inside the callback (examples #3) or use
469
+ `Promise.allSettled` and read each outcome; a rejection inside a plain `Promise.all` rejects
470
+ the join and the siblings with it.
471
+
472
+ ## 11. Streaming pipeline with channels
473
+
474
+ **When:** items should flow to the next stage as they are produced, and the shape is one
475
+ chaining (#10) cannot write: a pool of K shared workers serving a stage, a producer still
476
+ finding items while consumers work, a later stage sending work back (#12), or stages you want
477
+ to read as separate blocks. Each stage is a
478
+ `future` whose body opens with its own phase marker; a `channel` carries items between two
479
+ stages; the producing stage owns the `close()` in a `finally`.
480
+
481
+ ```ts
482
+ const leads = channel<Lead>("leads");
483
+ const facts = channel<Fact>("facts");
484
+ const checked: Checked[] = [];
485
+
486
+ const seed = future(async () => {
487
+ phase("Decide what to look into");
488
+ try {
489
+ const plan = await agent("planner").ask<{ questions: string[] }>(`List the questions to answer about ${topic}.`);
490
+ for (const question of plan.questions) leads.send({ question });
491
+ } finally {
492
+ leads.close();
493
+ }
494
+ });
495
+
496
+ const research = future(async () => {
497
+ phase("Research each question");
498
+ try {
499
+ await Promise.all(
500
+ Array.from({ length: RESEARCHERS }, async (_, k) => {
501
+ // One context per worker, hoisted out of the loop: a name is minted once per worker,
502
+ // and what one worker learnt on an earlier question is there for its next.
503
+ const researcher = agent(`researcher-${k + 1}`);
504
+ for await (const lead of leads) {
505
+ const found = await researcher.ask<Research>(`Research: ${lead.question}`);
506
+ found.facts.forEach((fact, index) => facts.send({ ...fact, id: `${lead.question}-${index + 1}` }));
507
+ }
508
+ }),
509
+ );
510
+ } finally {
511
+ facts.close(); // a failed researcher still ends the stream for the verifiers
512
+ }
513
+ });
514
+
515
+ const verify = future(async () => {
516
+ phase("Check each fact as it arrives");
517
+ await Promise.all(
518
+ Array.from({ length: VERIFIERS }, async (_, k) => {
519
+ const verifier = agent(`verifier-${k + 1}`);
520
+ for await (const fact of facts) {
521
+ const verdict = await verifier.ask<Verdict>(`Check: ${JSON.stringify(fact)}`);
522
+ checked.push({ ...fact, ...verdict });
523
+ report({ ...fact, ...verdict });
524
+ }
525
+ }),
526
+ );
527
+ });
528
+
529
+ // Start every stage first, then join all of them once. No await between the two: while the
530
+ // script awaits one stage, a failure in another has no listener and surfaces as an unhandled
531
+ // rejection instead of failing the run with its error.
532
+ await Promise.all([seed, research, verify]);
533
+
534
+ phase("Write the report from the checked facts");
535
+ const summary = await agent("writer").ask<string>(`Write up:\n${JSON.stringify(checked)}`);
536
+ ```
537
+
538
+ Three stages, three markers, one join. The writer comes after the join, not on a channel: it
539
+ needs every checked fact, so a shared array and the join is the right hand-off there. A
540
+ channel where the next stage should start early; a join where it cannot.
541
+
542
+ The pools here (`researcher-1…3`, `verifier-1…4`) share a context across the items each
543
+ worker happens to receive, which is what you want when the items must be judged on one scale
544
+ or when what was learnt on one item helps with the next. The price is cache locality on a
545
+ revised run: which item lands on which worker depends on timing, so an amendment that changes
546
+ one upstream item shifts the assignment and misses the cache for the whole pool. When the items
547
+ are independent and you expect to amend, spawn a fresh, item-named subagent per item inside the
548
+ `for await` instead — a `future` pushed into an array and joined before the stage ends
549
+ (examples #6).
550
+
551
+ ## 12. Feedback loop with a counted close
552
+
553
+ **When:** a later stage sends work back to an earlier one — a verifier that doubts a fact asks
554
+ for more research on it. The feedback channel has no single producer who knows when it is
555
+ done, so the script counts open work items and closes the channel when the count hits zero. A
556
+ depth field on each item bounds the loop.
557
+
558
+ ```ts
559
+ const leads = channel<Lead>("leads");
560
+ const facts = channel<Fact>("facts");
561
+ // Open work items: every lead sent and not yet researched, every fact sent and not yet judged.
562
+ // The feedback channel closes when this reaches zero, and nobody else may close it.
563
+ let open = 0;
564
+ function finished(): void {
565
+ open -= 1;
566
+ if (open === 0) leads.close();
567
+ }
568
+
569
+ for (const question of seeds) {
570
+ open += 1;
571
+ leads.send({ question, depth: 0 });
572
+ }
573
+
574
+ const research = future(async () => {
575
+ phase("Research each lead");
576
+ try {
577
+ await Promise.all(
578
+ Array.from({ length: WORKERS }, async (_, k) => {
579
+ const researcher = agent(`researcher-${k + 1}`);
580
+ for await (const lead of leads) {
581
+ const found = await researcher.ask<Research>(`Research: ${lead.question}`);
582
+ // Invariant 1: count every child BEFORE finishing the parent, so `open` never
583
+ // touches zero while work is still being produced.
584
+ found.facts.forEach((fact, index) => {
585
+ open += 1;
586
+ facts.send({ ...fact, id: `${lead.question}-${index + 1}`, depth: lead.depth });
587
+ });
588
+ finished();
589
+ }
590
+ }),
591
+ );
592
+ } finally {
593
+ // Invariant 2: a researcher sends facts only from inside its loop, so this close runs after
594
+ // the last researcher has left the loop and nothing can send to `facts` any more.
595
+ facts.close();
596
+ }
597
+ });
598
+
599
+ const verify = future(async () => {
600
+ phase("Check each fact, and send doubts back for more research");
601
+ const checks: Promise<void>[] = [];
602
+ for await (const fact of facts) {
603
+ checks.push(
604
+ future(async () => {
605
+ const verdict = await agent(`verifier-${fact.id}`).ask<Verdict>(`Check: ${JSON.stringify(fact)}`);
606
+ if (verdict.holds) passed.push(fact);
607
+ else if (verdict.followUp !== undefined && fact.depth < MAX_DEPTH) {
608
+ // This fact is still open, so `open` is at least 1 and `leads` cannot have closed:
609
+ // the follow-up is counted before the fact that produced it is finished.
610
+ open += 1;
611
+ leads.send({ question: verdict.followUp, depth: fact.depth + 1 });
612
+ } else rejected.push(fact.claim);
613
+ finished();
614
+ }),
615
+ );
616
+ }
617
+ await Promise.all(checks); // the stage is done when its checks are, not when `facts` closes
618
+ });
619
+
620
+ await Promise.all([research, verify]);
621
+ ```
622
+
623
+ Why the count closes `leads` and nothing else can: an item is finished only after every item
624
+ it produced has been counted, so `open` reaches zero exactly once, when the last item of the
625
+ last generation has been judged and produced nothing. The researchers then leave their loops,
626
+ the research stage closes `facts`, the verify stage's `for await` ends, and its join settles.
627
+ Forget the increment-before-finish order and `open` can hit zero with a follow-up about to be
628
+ sent — `leads.send` then throws `ChannelClosed`. Forget the join over `checks` and the stage
629
+ ends early with verdicts still running; the deadlock detector cannot see that one, because
630
+ nothing is parked. Forget the depth bound and two subagents can keep each other busy forever.
631
+
632
+ ## 13. Model routing
633
+
634
+ **When:** the user asked for cheaper or faster models where they are enough, and one subagent
635
+ can tell which requests need the strong model. A router on the light model answers with a
636
+ typed key; code maps the key to a model the script declared. The router never writes a model
637
+ name, so it can only pick among models the user approved in the window. Never on your own,
638
+ and never a model under another provider the user did not name; when you see the fit,
639
+ propose it and ask before the call (SKILL.md §2).
640
+
641
+ <!-- compile -->
642
+ ```ts
643
+ // Every model the run can use, declared once; names come from list_subagent_models.
644
+ const MODELS = {
645
+ light: model("GLM-5.3-Flash"),
646
+ strong: model("GLM-5.3$high"),
647
+ };
648
+
649
+ interface Route {
650
+ /** "strong" only when the request needs multi-step reasoning or careful writing. */
651
+ tier: "light" | "strong";
652
+ }
653
+
654
+ interface Reply {
655
+ answer: string;
656
+ }
657
+
658
+ const questions: string[] = ["Rename the config key in the README", "Explain the retry design"];
659
+
660
+ // Routing and answering map one to one, so each question goes to its answerer the moment
661
+ // its route is decided; the one join is for the return, which needs every answer.
662
+ phase("Route each question to the model it needs and answer it there");
663
+ const replies = await Promise.all(
664
+ questions.map(async (question, index) => {
665
+ const route = await agent(`分诊-${index + 1}`, { model: MODELS.light }).ask<Route>(
666
+ `Would answering this well need the strong model? ${question}`,
667
+ );
668
+ return agent(`答复者-${index + 1}`, { model: MODELS[route.tier] }).ask<Reply>(question);
669
+ }),
670
+ );
671
+ return replies.map((reply) => reply.answer);
672
+ ```
673
+
674
+ A fixed choice needs no table: `agent("评审员", { model: "GLM-5.3-Flash" })`. Keep the table at
675
+ the top of the script: an amend changes a model in one place, and the finished work of a
676
+ subagent whose model changed is still reused — its next live ask runs on the new model.
677
+
678
+ ---
679
+
680
+ ## 14. Growth by tail holes
681
+
682
+ **When:** the task is complicated enough that its workflow cannot be planned from the request
683
+ — the next step depends on what the last one found. Write what is known and end the script
684
+ with a tail hole. The script then grows by nesting: each fill is the statements of the
685
+ innermost body, does one step, and ends in the next tail hole; the last fill returns.
686
+ (`SKILL.md` §15; the complete chain with its fill files is `examples.md` #7.)
687
+
688
+ ```ts
689
+ // 0. The seed, submitted with create_workflow.
690
+ phase("盘点仓库顶层目录");
691
+ const survey = await agent("勘察员").ask<Survey>("列出顶层目录,各用一句话说明作用。");
692
+ return await hole<Guide>("第1步:决定导览结构", `盘点:${JSON.stringify(survey.dirs)}`);
693
+ ```
694
+
695
+ ```ts
696
+ // 1. The effective script after the first fill_workflow_hole: the hole gained a body
697
+ // that does one step and leaves the next hole. Only the body's statements were sent.
698
+ return await hole<Guide>("第1步:决定导览结构", `盘点:…`, async () => {
699
+ phase("分章并行撰写初稿");
700
+ const drafts = await Promise.all(
701
+ survey.dirs.map((d) => agent(`写手·${d.path}`).ask<Chapter>(`写「${d.path}」一章:${d.purpose}`)),
702
+ );
703
+ return await hole<Guide>("第2步:审读与交付", `${drafts.length} 章初稿已就绪`);
704
+ });
705
+ ```
706
+
707
+ ```ts
708
+ // 2. After the second fill: the chain closes with a value. Each hole's site id comes
709
+ // from its name, so ids stay short at any depth; the timeline shows one head per step.
710
+ return await hole<Guide>("第1步:决定导览结构", `盘点:…`, async () => {
711
+ /* step 1 as above; `survey` and `drafts` are in scope below */
712
+ return await hole<Guide>("第2步:审读与交付", `…`, async () => {
713
+ phase("独立审读并修订");
714
+ const critique = await agent("审读员").ask<string>(`只凭文本挑毛病:${JSON.stringify(drafts)}`);
715
+ const chapters = await agent("修订编辑").ask<Chapter[]>(`按意见修订:${critique}\n${JSON.stringify(drafts)}`);
716
+ return { title: "仓库导览", chapters, notCovered: [] };
717
+ });
718
+ });
719
+ ```
720
+
721
+ The rules that make a chain work: every hole name is unique across the whole effective
722
+ script, so name each step for what it does (`第N步:…`), never the same name twice; the prompt
723
+ carries the progress the next author needs (counts, titles, what failed), because it is the
724
+ only channel for values; results live in bindings (`survey`, `drafts`), which every inner
725
+ body reads, so nothing needs re-asking; a step may open phases, create subagents, fan out and
726
+ gate with `world.run` like any script. The chain ends when a fill returns instead of leaving
727
+ a hole. A restart resumes the chain where it waited, with the finished steps replayed from
728
+ the journal.
729
+
730
+ ---
731
+
732
+ ## 15. A stage shaped by discovery
733
+
734
+ **When:** the survey decides the *topology* of the next stage, not just its inputs — how many
735
+ reviewers, fanned out or sequential, which check gates them. The survey's value goes to the
736
+ script as data; the fill writes the stage.
737
+
738
+ ```ts
739
+ phase("剖析热点");
740
+ const hot = await agent("剖析员").ask<Hotspots>("找出最慢的三个模块,说明各自的耦合。");
741
+ const reviews = await hole<Review[]>("怎么审查这些热点", `热点:${JSON.stringify(hot.modules)}`);
742
+ phase("汇总");
743
+ return await agent("汇总员").ask<Report>(`汇总审查结果:${JSON.stringify(reviews)}`);
744
+ ```
745
+
746
+ A fill written once `hot` says two modules are independent and one is shared by both: the
747
+ independent pair reviewed in parallel, the shared one by a calibrated reviewer that has seen
748
+ the other two reviews, then a bounded fix-and-recheck loop gated by the project's own test
749
+ command. None of that topology was knowable before the survey.
750
+
751
+ ```ts
752
+ phase("并行审查独立模块");
753
+ const [a, b] = await Promise.all(
754
+ hot.modules.slice(0, 2).map((m) => agent(`审查员·${m.path}`).ask<Review>(`审查 ${m.path}:${m.coupling}`)),
755
+ );
756
+ phase("在前两份审查的基础上审查共享模块");
757
+ const shared = hot.modules[2];
758
+ const reviewer = agent("共享模块审查员", "你在别人的审查基础上工作,只找他们没看到的问题。");
759
+ let review = await reviewer.ask<Review>(`已有审查:${JSON.stringify([a, b])}\n现在审查 ${shared.path}`);
760
+ for (let round = 1; round <= 3 && review.findings.length > 0; round += 1) {
761
+ const fix = await world.run("pnpm", ["test", "--", shared.path]);
762
+ if (fix.exitCode === 0) break;
763
+ review = await reviewer.ask<Review>(`测试仍失败:${fix.stderr}\n复审 ${shared.path}`);
764
+ }
765
+ return [a, b, review];
766
+ ```
767
+
768
+ Contrast with a plain subagent ask: had the survey only said *which* modules to review, the
769
+ script could have fanned out over `hot.modules` itself and no hole was needed.
770
+
771
+ ---
772
+
773
+ ## 16. A remedy the plan could not enumerate
774
+
775
+ **When:** a gate fails and the fix may need phases and subagents nobody planned. If the
776
+ remedies were known — retry, narrow, skip — the script would hold a `Remedy` value and an
777
+ `if`; the hole is for the case where the remedy is a piece of workflow decided with the
778
+ failure in hand.
779
+
780
+ ```ts
781
+ phase("跑完整测试");
782
+ const gate = await world.run("pnpm", ["test"], { timeoutMs: 1_800_000 });
783
+ if (gate.exitCode !== 0) {
784
+ await hole<void>("测试没过怎么办", `退出码 ${gate.exitCode}:\n${gate.stderr.slice(0, 2000)}`);
785
+ }
786
+ phase("交付");
787
+ return await agent("报告员").ask<Report>("写交付报告。");
788
+ ```
789
+
790
+ A fill after a flaky-looking failure: a bisect over the last commits by `world.run`, a
791
+ second opinion from a fresh subagent on whether the failure is real, and — only if it is —
792
+ a fixer loop bounded by three rounds. A fill after a clear failure is one fixer and one
793
+ recheck. The script did not have to guess which, and the user sees the remedy as phases of
794
+ its own under the hole's head.