pi-legion 5.0.1 → 5.2.0

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.
Files changed (79) hide show
  1. package/CHANGELOG.md +858 -0
  2. package/CONTRIBUTING.md +33 -2
  3. package/README.md +10 -5
  4. package/agents/centurion.md +32 -7
  5. package/agents/scout.md +11 -0
  6. package/docs/contracts/abort-soft-interrupt-v1.md +162 -0
  7. package/docs/contracts/centurion-declared-phases-v1.md +104 -0
  8. package/docs/contracts/declarative-phase-machine-v5.md +43 -0
  9. package/docs/contracts/extension-inheritance-wiring-v1.md +88 -0
  10. package/docs/contracts/finished-cache-eviction-v1.md +169 -0
  11. package/docs/contracts/galaxy-scratch-v1.md +78 -0
  12. package/docs/contracts/legion-chart-frame-buckets-v1.md +201 -0
  13. package/docs/contracts/legion-main-screen-mount-v1.md +161 -0
  14. package/docs/contracts/legion-page-floor-v1.md +129 -0
  15. package/docs/contracts/legion-session-continuity-v1.md +118 -0
  16. package/docs/contracts/mailbox-delivery-v1.md +162 -0
  17. package/docs/contracts/notice-claim-v1.md +206 -0
  18. package/docs/contracts/partial-failure-exit-v1.md +235 -0
  19. package/docs/contracts/proc-sweep-v1.md +107 -0
  20. package/docs/contracts/provider-empty-generation-retry-v1.md +161 -0
  21. package/docs/contracts/stall-visibility-v1.md +218 -0
  22. package/docs/contracts/subagent-renewal-v1.md +5 -3
  23. package/docs/contracts/vexillatio-nonblocking-launch-v1.md +1 -0
  24. package/docs/contracts/viz-frame-alloc-v1.md +123 -0
  25. package/docs/contracts/wait-mail-preempt-v1.md +117 -0
  26. package/docs/contracts/wait-not-stop.md +1 -1
  27. package/docs/design.md +4 -1
  28. package/docs/inprocess-supervisor.md +9 -3
  29. package/docs/legion-v2-contract.md +122 -20
  30. package/docs/vexillatio-contract.md +5 -1
  31. package/index.ts +1903 -130
  32. package/package.json +5 -5
  33. package/skills/pi-legion/SKILL.md +2 -1
  34. package/src/agents/agents.ts +26 -1
  35. package/src/agents/settings.ts +67 -2
  36. package/src/api.ts +17 -0
  37. package/src/extension/child-guard.ts +2 -1
  38. package/src/extension/join.ts +54 -0
  39. package/src/extension/legion-commands.ts +15 -4
  40. package/src/extension/legion-doctor.ts +48 -6
  41. package/src/extension/legion-status.ts +44 -2
  42. package/src/extension/legion-tools.ts +1044 -109
  43. package/src/extension/notify.ts +31 -2
  44. package/src/extension/playbook.ts +6 -3
  45. package/src/extension/runtime.ts +882 -81
  46. package/src/extension/spawn-hints.ts +52 -12
  47. package/src/extension/summary.ts +7 -15
  48. package/src/extension/timing.ts +4 -15
  49. package/src/legion/db.ts +23 -1
  50. package/src/legion/events.ts +7 -0
  51. package/src/legion/interrupt.ts +98 -0
  52. package/src/legion/mail-release.ts +266 -0
  53. package/src/legion/mail.ts +456 -29
  54. package/src/legion/nodes.ts +31 -0
  55. package/src/legion/phase-conditions.ts +7 -1
  56. package/src/legion/phase-machine.ts +160 -8
  57. package/src/legion/state-machine.ts +34 -2
  58. package/src/runs/acceptance.ts +105 -6
  59. package/src/runs/args.ts +16 -0
  60. package/src/runs/child-scope.ts +323 -0
  61. package/src/runs/extension-inheritance.ts +145 -19
  62. package/src/runs/orchestrator.ts +613 -55
  63. package/src/runs/store.ts +149 -5
  64. package/src/shared/proc-sweep.ts +317 -0
  65. package/src/shared/progress.ts +11 -2
  66. package/src/shared/session-map.ts +29 -0
  67. package/src/shared/session.ts +308 -6
  68. package/src/shared/types.ts +34 -0
  69. package/src/supervisor/inprocess-supervisor.ts +158 -12
  70. package/src/supervisor/race-timeout.ts +55 -0
  71. package/src/supervisor/routing-supervisor.ts +55 -4
  72. package/src/supervisor/rpc-supervisor.ts +215 -29
  73. package/src/supervisor/types.ts +439 -2
  74. package/src/tui/status.ts +2 -1
  75. package/src/tui/viz/canvas.ts +358 -36
  76. package/src/tui/viz/palette.ts +18 -2
  77. package/src/tui/viz/panels.ts +507 -104
  78. package/src/tui/viz/rate.ts +120 -15
  79. package/src/tui/viz/view.ts +72 -4
@@ -25,9 +25,12 @@ import {
25
25
  type UIProxy,
26
26
  } from "./ui-proxy.ts";
27
27
  import {
28
+ type AbortOutcome,
29
+ type ChildActivity,
28
30
  type ChildHandle,
29
31
  type DescendantInfo,
30
32
  type EventSubscriptionOptions,
33
+ type InFlightToolStack,
31
34
  type LegionSupervisor,
32
35
  type RpcClientFactory,
33
36
  type RpcClientLike,
@@ -36,11 +39,20 @@ import {
36
39
  type RpcSupervisorOptions,
37
40
  type SettleResult,
38
41
  type SpawnInput,
42
+ type SteerDisposition,
39
43
  type SupervisorEvent,
40
44
  type SupervisorEventListener,
41
45
  type UsageSnapshot,
42
46
  } from "./types.ts";
47
+ import {
48
+ countClearedQueue,
49
+ DEFAULT_ABORT_TIMEOUT_MS,
50
+ MAX_ABORT_TIMER_DELAY_MS,
51
+ nextInFlightTool,
52
+ toSteerDisposition,
53
+ } from "./types.ts";
43
54
  import { currentPgid, enumerateDescendants } from "./proc-tree.ts";
55
+ import { raceWithTimeout } from "./race-timeout.ts";
44
56
 
45
57
  interface EventSubscription {
46
58
  listener: SupervisorEventListener;
@@ -76,6 +88,14 @@ interface ChildRecord {
76
88
  unsubscribeRpcEvents?: () => void;
77
89
  retirePromise?: Promise<void>;
78
90
  abortedPending: boolean;
91
+ /**
92
+ * The tool calls this child is inside right now (#315, #331), folded from its
93
+ * own RPC event stream — no extra IPC, no polling. The stack is LIFO: the last
94
+ * frame is the innermost call. A frame is removed by the `tool_execution_end`
95
+ * that names it, and `agent_settled` empties the stack: a settled turn has no
96
+ * tool running, so nothing may be left claiming one. Display-only.
97
+ */
98
+ inFlightTools?: InFlightToolStack;
79
99
  }
80
100
 
81
101
  export type { RpcSupervisorOptions } from "./types.ts";
@@ -201,6 +221,12 @@ function usageSnapshot(value: unknown): UsageSnapshot | null {
201
221
  * Registry entries are isolated by name and own their event listeners/tempfiles.
202
222
  */
203
223
  export class RpcSupervisor implements LegionSupervisor {
224
+ /**
225
+ * RPC reads the prompt reply's disposition, so `prompt()` can tell "a run
226
+ * started" from "it did not" (#323 D1). See the seam doc for why the
227
+ * in-process backend cannot claim this.
228
+ */
229
+ readonly capabilities = { promptDisposition: true } as const;
204
230
  private readonly children = new Map<string, ChildRecord>();
205
231
  private readonly subscriptionsBeforeSpawn = new Map<
206
232
  string,
@@ -366,14 +392,34 @@ export class RpcSupervisor implements LegionSupervisor {
366
392
  }
367
393
  registration.state = "idle";
368
394
  this.beginTurn(registration);
369
- await client.prompt(
370
- formatChildTask(input.task, {
371
- allowNested: input.allowNestedSubagents === true,
372
- ...(input.worktreeBranch
373
- ? { worktreeBranch: input.worktreeBranch }
374
- : {}),
375
- }),
395
+ const firstTurn = toSteerDisposition(
396
+ await client.prompt(
397
+ formatChildTask(input.task, {
398
+ allowNested: input.allowNestedSubagents === true,
399
+ ...(input.worktreeBranch
400
+ ? { worktreeBranch: input.worktreeBranch }
401
+ : {}),
402
+ }),
403
+ ),
404
+ "prompt",
376
405
  );
406
+ if (firstTurn === "intercepted") {
407
+ // An input handler swallowed the launch prompt, so no run started for it
408
+ // (#313): `agent_start`/`agent_settled` will never arrive to end the turn
409
+ // `beginTurn` just claimed. Failing the spawn is the only honest answer —
410
+ // returning a handle that is born `running` would park every waiter and
411
+ // make the child look busy forever.
412
+ //
413
+ // #323 5: this is a DETERMINISTIC failure — the same input handler eats
414
+ // the same prompt for every model — so it gets the one code
415
+ // `canFallbackStart` refuses. `START_FAILED` would make the orchestrator
416
+ // spawn one process per fallback model and roll each one back.
417
+ throw this.startFailure(
418
+ registration,
419
+ "first prompt was intercepted by an input handler before any run started",
420
+ ErrorCodes.PROMPT_INTERCEPTED,
421
+ );
422
+ }
377
423
  if (!this.isAlive(input.name)) {
378
424
  throw this.startFailure(registration, "Pi RPC process exited after its first prompt");
379
425
  }
@@ -395,10 +441,17 @@ export class RpcSupervisor implements LegionSupervisor {
395
441
  await this.dispatch(child, "prompt", text);
396
442
  }
397
443
 
398
- /** Use the RPC steer command while running; idle children start a prompt. */
399
- async steer(name: string, text: string): Promise<void> {
444
+ /**
445
+ * Use the RPC steer command while running; idle children start a prompt.
446
+ *
447
+ * Returns what actually happened to the text (#313 D4): the disposition the
448
+ * RPC answered with, normalized by `toSteerDisposition` — `"intercepted"`
449
+ * when an input handler swallowed it, `"queued"` when it waits for the next
450
+ * turn boundary, `"accepted"` when this call started a turn.
451
+ */
452
+ steer(name: string, text: string): Promise<SteerDisposition> {
400
453
  const child = this.requireChild(name);
401
- await this.dispatch(child, "steer", text);
454
+ return this.dispatch(child, "steer", text);
402
455
  }
403
456
 
404
457
  /** Queue a follow-up behind a running turn; idle children start a prompt. */
@@ -407,11 +460,71 @@ export class RpcSupervisor implements LegionSupervisor {
407
460
  await this.dispatch(child, "followUp", text);
408
461
  }
409
462
 
410
- async abort(name: string): Promise<void> {
463
+ /**
464
+ * Soft interrupt (#314): clear the queue FIRST (#314 D3), then interrupt the
465
+ * running turn, and wait no longer than one `bound` for either step
466
+ * (#314 D2 default, #314 D4 bound).
467
+ *
468
+ * - `requireChild` + `assertCanSend` run first, so a retired/unavailable child
469
+ * keeps throwing `NOT_FOUND` exactly as before;
470
+ * - `turnActive === false` ⇒ `"no-turn"`, and nothing is called at all: no
471
+ * clear, no interrupt (#314 D1);
472
+ * - the clear is best-effort AND bounded: a throwing, absent or unresponsive
473
+ * `clearQueue` reports zeros and must never hold the interrupt back — the
474
+ * only reason this path runs is that the child is unresponsive (#314 D2
475
+ * counts, #314 D4 bound);
476
+ * - a timeout resolves with `"timeout"` and touches neither `turnActive` nor
477
+ * `state` — convergence stays with `agent_settled` (#314 D4).
478
+ */
479
+ async abort(
480
+ name: string,
481
+ opts?: { clearQueued?: boolean; timeoutMs?: number },
482
+ ): Promise<AbortOutcome> {
411
483
  const child = this.requireChild(name);
412
484
  this.assertCanSend(child);
413
- if (!child.turnActive) return;
414
- await this.requireClient(child).abort();
485
+ // #314 D2: normalize once per call. Node turns any delay outside
486
+ // `[1, MAX_ABORT_TIMER_DELAY_MS]` into 1 ms, so BOTH kinds of junk — a
487
+ // non-finite / ≤0 value and an over-large one like `1e12` — would bound the
488
+ // clear and the interrupt at ~0 and make every abort a fake `"timeout"`:
489
+ // hence the fallback to the shared default AND the cap at the largest delay
490
+ // a timer actually honours.
491
+ const t = opts?.timeoutMs;
492
+ const bound = Math.min(
493
+ Number.isFinite(t) && (t as number) > 0
494
+ ? (t as number)
495
+ : DEFAULT_ABORT_TIMEOUT_MS,
496
+ MAX_ABORT_TIMER_DELAY_MS,
497
+ );
498
+ if (!child.turnActive) {
499
+ return { status: "no-turn", cleared: { steering: 0, followUp: 0 }, timeoutMs: bound };
500
+ }
501
+ let cleared = { steering: 0, followUp: 0 };
502
+ if (opts?.clearQueued !== false) {
503
+ try {
504
+ // Bounded by the same `bound` as the interrupt (#314 D4), which is the whole
505
+ // point on this backend: the clear goes through `RpcClient.send()`, whose only
506
+ // bound is a hard-coded 30 s request timeout, so awaiting it would delay the
507
+ // interrupt by up to 30 s — exactly on the unresponsive child this path exists
508
+ // for. A timer win reports `{0, 0}`: what we could learn, never a promise that
509
+ // the queue is empty.
510
+ cleared = await raceWithTimeout(
511
+ Promise.resolve()
512
+ .then(() => this.requireClient(child).clearQueue?.())
513
+ .then(countClearedQueue),
514
+ bound,
515
+ () => ({ steering: 0, followUp: 0 }),
516
+ );
517
+ } catch {
518
+ // Best effort: a clear that cannot answer must not swallow the interrupt.
519
+ // `cleared` already holds the zeros, since a throw means the assignment
520
+ // above never happened.
521
+ }
522
+ }
523
+ const work = (async (): Promise<"interrupted"> => {
524
+ await this.requireClient(child).abort();
525
+ return "interrupted";
526
+ })();
527
+ return { status: await raceWithTimeout<"interrupted" | "timeout">(work, bound, () => "timeout"), cleared, timeoutMs: bound };
415
528
  }
416
529
 
417
530
  waitSettled(name: string, timeoutMs = 900_000, signal?: AbortSignal): Promise<SettleResult> {
@@ -482,6 +595,31 @@ export class RpcSupervisor implements LegionSupervisor {
482
595
  return child.state !== "retired" && child.state !== "exited";
483
596
  }
484
597
 
598
+ /**
599
+ * The tool call this child is inside right now (#315), or `undefined`.
600
+ *
601
+ * Gated on {@link isAlive}: a child whose process is gone holds no handle and
602
+ * therefore cannot be inside a tool, whatever a leftover record field still
603
+ * says (display-liveness §6 — never attribute live activity to a process that
604
+ * is gone).
605
+ */
606
+ inFlightTool(name: string): ChildActivity | undefined {
607
+ if (!this.isAlive(name)) return undefined;
608
+ const stack = this.children.get(name)?.inFlightTools;
609
+ return stack?.[stack.length - 1];
610
+ }
611
+
612
+ /**
613
+ * The whole stack (#331), innermost last. Same `isAlive` gate as
614
+ * {@link inFlightTool}: a dead child holds no live handle and cannot be inside
615
+ * a tool, whatever a leftover record field still says.
616
+ */
617
+ inFlightToolStack(name: string): InFlightToolStack | undefined {
618
+ if (!this.isAlive(name)) return undefined;
619
+ const stack = this.children.get(name)?.inFlightTools;
620
+ return stack !== undefined && stack.length > 0 ? stack : undefined;
621
+ }
622
+
485
623
  async stats(name: string): Promise<UsageSnapshot | null> {
486
624
  const child = this.children.get(name);
487
625
  if (!child || !child.client || !this.isAlive(name)) return null;
@@ -541,7 +679,7 @@ export class RpcSupervisor implements LegionSupervisor {
541
679
  child: ChildRecord,
542
680
  kind: "prompt" | "steer" | "followUp",
543
681
  text: string,
544
- ): Promise<void> {
682
+ ): Promise<SteerDisposition> {
545
683
  this.assertCanSend(child);
546
684
  const client = this.requireClient(child);
547
685
  const wasActive = child.turnActive;
@@ -550,28 +688,62 @@ export class RpcSupervisor implements LegionSupervisor {
550
688
  try {
551
689
  if (kind === "followUp" && wasActive) {
552
690
  await client.followUp(text);
691
+ // A follow-up is banked behind the turn that is already running.
692
+ return "queued";
553
693
  } else if ((kind === "steer" || kind === "prompt") && wasActive) {
554
694
  // A prompt addressed to a busy child is an immediate correction;
555
695
  // use the explicit RPC steer command, never a second prompt command.
556
- await client.steer(text);
696
+ // The value is never discarded: `"handled"` means an input handler
697
+ // swallowed the text, `"queued"` that it waits for a turn boundary.
698
+ return toSteerDisposition(await client.steer(text), "steer");
557
699
  } else {
558
- await client.prompt(text);
700
+ // This call started the turn: a busy child took a branch above, so the
701
+ // prompt reached the client at a turn boundary. `prompt()` reports a
702
+ // disposition of its own (`dist/modes/rpc/rpc-client.js:135-137`), and
703
+ // `"handled"` there means *no run started* — read it, never assume it.
704
+ const disposition = toSteerDisposition(await client.prompt(text), "prompt");
705
+ if (disposition === "intercepted") {
706
+ // `beginTurn` above claimed a turn the client never started, and no
707
+ // `agent_start`/`agent_settled` will ever arrive to end it. Leaving
708
+ // `turnActive` set would park every later `waitSettled` on its timeout
709
+ // and route all further work into `client.steer`, which only queues and
710
+ // never starts a turn — a permanently mute child that still reports
711
+ // `running`. Roll the claim back like the rejection path does; the
712
+ // disposition still travels to the caller (this is not an error).
713
+ this.abandonTurn(child, "prompt was intercepted before any run started");
714
+ }
715
+ return disposition;
559
716
  }
560
717
  } catch (error) {
561
- if (!wasActive && child.turnActive) {
562
- child.turnActive = false;
563
- child.state = "idle";
564
- child.lastTurnResult = {
565
- settled: false,
566
- abnormal: false,
567
- reason: "RPC command was rejected",
568
- };
569
- this.resolveWaiters(child, child.lastTurnResult);
570
- }
718
+ if (!wasActive) this.abandonTurn(child, "RPC command was rejected");
571
719
  throw error;
572
720
  }
573
721
  }
574
722
 
723
+ /**
724
+ * Release a turn claim for a turn that never actually started (#313).
725
+ *
726
+ * `beginTurn` sets `turnActive`/`running` *before* the client is asked, so a
727
+ * send that throws — or one whose answer proves no run started (`intercepted`)
728
+ * — has to undo it, or the child looks busy forever and every waiter parks on
729
+ * the settle timeout.
730
+ */
731
+ private abandonTurn(child: ChildRecord, reason: string): void {
732
+ if (!child.turnActive) return;
733
+ child.turnActive = false;
734
+ // Same invariant `updateTurnState` keeps (#323 4): a concurrent retire has
735
+ // already moved the record to `retiring`, and rolling a turn back must not
736
+ // rewrite that into `idle` — `idle` means "holds a live slot, can take a
737
+ // turn", which a retiring child is about to lose.
738
+ if (child.state !== "retiring") child.state = "idle";
739
+ child.lastTurnResult = {
740
+ settled: false,
741
+ abnormal: false,
742
+ reason,
743
+ };
744
+ this.resolveWaiters(child, child.lastTurnResult);
745
+ }
746
+
575
747
  private beginTurn(child: ChildRecord): void {
576
748
  child.lastTurnResult = undefined;
577
749
  child.exitResult = undefined;
@@ -662,6 +834,11 @@ export class RpcSupervisor implements LegionSupervisor {
662
834
  return;
663
835
  }
664
836
 
837
+ // #315/#331: the in-flight stack rides the RPC event stream this backend
838
+ // already consumes. Nothing new is asked of the child, and the fold is
839
+ // total, so an event about anything else leaves the stack untouched.
840
+ child.inFlightTools = nextInFlightTool(child.inFlightTools ?? [], record, Date.now());
841
+
665
842
  this.updateTurnState(child, record);
666
843
 
667
844
  this.publishEvent(child, record);
@@ -693,6 +870,11 @@ export class RpcSupervisor implements LegionSupervisor {
693
870
  };
694
871
  child.abortedPending = false;
695
872
  child.turnActive = false;
873
+ // #315: an abort or a child-side interruption can end a turn while a tool
874
+ // is mid-flight, in which case no `tool_execution_end` ever arrives. A
875
+ // settled turn holds no tool, so the stack is dropped here instead of
876
+ // outliving the turn it described.
877
+ child.inFlightTools = [];
696
878
  child.lastTurnResult = result;
697
879
  if (child.state !== "retiring") child.state = "idle";
698
880
  this.resolveWaiters(child, result);
@@ -1027,7 +1209,11 @@ export class RpcSupervisor implements LegionSupervisor {
1027
1209
  );
1028
1210
  }
1029
1211
 
1030
- private startFailure(child: ChildRecord, message: string): SubagentError {
1212
+ private startFailure(
1213
+ child: ChildRecord,
1214
+ message: string,
1215
+ code: string = ErrorCodes.START_FAILED,
1216
+ ): SubagentError {
1031
1217
  const stderr = child.client?.getStderr?.();
1032
1218
  const base = `${message}${stderr ? `: ${stderr.trim().slice(0, 500)}` : ""}`;
1033
1219
  return new SubagentError(
@@ -1035,10 +1221,10 @@ export class RpcSupervisor implements LegionSupervisor {
1035
1221
  name: child.name,
1036
1222
  stderr,
1037
1223
  args: child.lastArgs,
1038
- code: ErrorCodes.START_FAILED,
1224
+ code,
1039
1225
  cwd: child.cwd,
1040
1226
  }),
1041
- ErrorCodes.START_FAILED,
1227
+ code,
1042
1228
  );
1043
1229
  }
1044
1230