@xzzpig/pi-subagents 0.14.0 → 0.15.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 (198) hide show
  1. package/CHANGELOG.md +233 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +92 -14
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +63 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
  19. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
  20. package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
  21. package/package.json +9 -4
  22. package/prompts/parallel-review.md +1 -1
  23. package/runner-peer-loader.mjs +24 -0
  24. package/runner-peer-preload.mjs +36 -0
  25. package/skills/pi-subagents/SKILL.md +34 -22
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  27. package/skills/pi-subagents/references/execution-controls.md +27 -8
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  31. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  32. package/src/agents/advertised-agent-prompt.ts +94 -0
  33. package/src/agents/agent-management.ts +71 -59
  34. package/src/agents/agent-serializer.ts +6 -3
  35. package/src/agents/agents.ts +198 -72
  36. package/src/agents/builtin-names.ts +1 -0
  37. package/src/agents/chain-serializer.ts +5 -0
  38. package/src/agents/runtime-agent-registry.ts +7 -6
  39. package/src/api/delegation.ts +4 -0
  40. package/src/api/preflight.ts +110 -71
  41. package/src/api/required-child-extensions.ts +6 -0
  42. package/src/api/shared-types.ts +3 -1
  43. package/src/api/workflow-resources.ts +6 -0
  44. package/src/extension/config.ts +14 -37
  45. package/src/extension/fanout-child.ts +68 -5
  46. package/src/extension/herdr-pi-bridge.ts +164 -0
  47. package/src/extension/index.ts +141 -51
  48. package/src/extension/public-execution.ts +7 -6
  49. package/src/extension/rpc.ts +8 -21
  50. package/src/extension/schemas.ts +86 -84
  51. package/src/extension/tool-description.ts +32 -79
  52. package/src/inspectors/actions.ts +148 -0
  53. package/src/inspectors/ghostty/actions.ts +74 -0
  54. package/src/inspectors/ghostty/plugin.ts +17 -0
  55. package/src/inspectors/herdr/actions.ts +99 -179
  56. package/src/inspectors/herdr/plugin.ts +20 -0
  57. package/src/inspectors/herdr/project-panes.ts +4 -1
  58. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  59. package/src/inspectors/plugins.ts +8 -0
  60. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  61. package/src/inspectors/types.ts +51 -0
  62. package/src/integrations/pi-web-session-liveness.ts +73 -0
  63. package/src/intercom/intercom-bridge.ts +50 -8
  64. package/src/intercom/native-supervisor-channel.ts +142 -115
  65. package/src/intercom/supervisor-ui.ts +3 -2
  66. package/src/missions/workflow-state.ts +37 -16
  67. package/src/policy/authority.ts +4 -0
  68. package/src/profiles/profiles.ts +12 -6
  69. package/src/runs/background/active-async-capacity.ts +22 -18
  70. package/src/runs/background/active-run-index.ts +17 -1
  71. package/src/runs/background/async-execution.ts +359 -176
  72. package/src/runs/background/async-job-tracker.ts +41 -7
  73. package/src/runs/background/async-resume.ts +19 -12
  74. package/src/runs/background/async-retention.ts +20 -0
  75. package/src/runs/background/async-status-snapshot.ts +10 -12
  76. package/src/runs/background/async-status.ts +32 -13
  77. package/src/runs/background/auto-drain.ts +59 -35
  78. package/src/runs/background/binary-bootstrap.ts +38 -0
  79. package/src/runs/background/chain-append.ts +1 -1
  80. package/src/runs/background/chain-root-attachment.ts +22 -33
  81. package/src/runs/background/control-channel.ts +78 -44
  82. package/src/runs/background/fleet-view.ts +30 -2
  83. package/src/runs/background/notify.ts +193 -19
  84. package/src/runs/background/owned-process-tree.ts +35 -8
  85. package/src/runs/background/process-terminal.ts +23 -23
  86. package/src/runs/background/result-files.ts +8 -4
  87. package/src/runs/background/result-watcher.ts +19 -2
  88. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  89. package/src/runs/background/run-child-session.ts +118 -41
  90. package/src/runs/background/run-status.ts +78 -5
  91. package/src/runs/background/runner-aliases.ts +22 -5
  92. package/src/runs/background/runner-child-launch.ts +93 -0
  93. package/src/runs/background/runner-child-sessions.ts +5 -4
  94. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  95. package/src/runs/background/scheduled-runs.ts +51 -18
  96. package/src/runs/background/stale-run-reconciler.ts +38 -12
  97. package/src/runs/background/steering.ts +20 -2
  98. package/src/runs/background/subagent-runner.ts +766 -432
  99. package/src/runs/background/subagent-wait.ts +179 -28
  100. package/src/runs/background/wait-completions.ts +79 -27
  101. package/src/runs/background/wait-subscriptions.ts +9 -3
  102. package/src/runs/background/wait-tool.ts +5 -3
  103. package/src/runs/foreground/async-steering-action.ts +37 -7
  104. package/src/runs/foreground/async-stop-action.ts +93 -3
  105. package/src/runs/foreground/execution.ts +174 -194
  106. package/src/runs/foreground/foreground-history.ts +5 -2
  107. package/src/runs/foreground/prompt-audit.ts +12 -6
  108. package/src/runs/foreground/subagent-executor.ts +896 -397
  109. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  110. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  111. package/src/runs/shared/acceptance.ts +54 -14
  112. package/src/runs/shared/agent-contract.ts +1 -1
  113. package/src/runs/shared/async-status-projection.ts +172 -78
  114. package/src/runs/shared/capability-ceiling.ts +2 -0
  115. package/src/runs/shared/child-hooks.ts +167 -3
  116. package/src/runs/shared/child-launch-plan.ts +15 -3
  117. package/src/runs/shared/child-launch.ts +44 -16
  118. package/src/runs/shared/child-lifecycle.ts +6 -3
  119. package/src/runs/shared/child-runtime-config.ts +8 -1
  120. package/src/runs/shared/child-session.ts +130 -24
  121. package/src/runs/shared/child-tool-plan.ts +145 -14
  122. package/src/runs/shared/completion-evidence.ts +2 -2
  123. package/src/runs/shared/completion-guard.ts +6 -3
  124. package/src/runs/shared/dynamic-fanout.ts +2 -2
  125. package/src/runs/shared/effective-system-prompt.ts +33 -0
  126. package/src/runs/shared/external-cli-contract.ts +11 -1
  127. package/src/runs/shared/external-cli-preflight.ts +6 -2
  128. package/src/runs/shared/external-cli-runner.ts +9 -7
  129. package/src/runs/shared/herdr-connection.ts +134 -0
  130. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  131. package/src/runs/shared/herdr-machine.ts +279 -0
  132. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  133. package/src/runs/shared/herdr-placed-run.ts +263 -0
  134. package/src/runs/shared/host-step-status.ts +11 -11
  135. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  136. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  137. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  138. package/src/runs/shared/model-scope.ts +1 -1
  139. package/src/runs/shared/nested-events.ts +19 -10
  140. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  141. package/src/runs/shared/parallel-handoff.ts +57 -12
  142. package/src/runs/shared/parallel-utils.ts +10 -4
  143. package/src/runs/shared/pi-spawn.ts +10 -0
  144. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  145. package/src/runs/shared/run-fanout-budget.ts +8 -8
  146. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  147. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  148. package/src/runs/shared/task-intent.ts +46 -13
  149. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  150. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  151. package/src/runs/shared/worktree-setup-command.ts +213 -0
  152. package/src/runs/shared/worktree.ts +437 -214
  153. package/src/shared/child-cache-retention.ts +43 -0
  154. package/src/shared/fork-context.ts +15 -72
  155. package/src/shared/launch-contract.ts +70 -8
  156. package/src/shared/model-response-aliases.ts +13 -0
  157. package/src/shared/opencode-session-headers.ts +30 -0
  158. package/src/shared/pruned-fork.ts +1 -1
  159. package/src/shared/required-child-extensions.ts +81 -0
  160. package/src/shared/settings.ts +5 -2
  161. package/src/shared/shortcuts.ts +0 -4
  162. package/src/shared/types.ts +163 -90
  163. package/src/shared/utils.ts +10 -2
  164. package/src/shared/watch-strategy.ts +2 -0
  165. package/src/shared/workflow-child-permit.ts +18 -13
  166. package/src/slash/delegation-adapters.ts +3 -1
  167. package/src/slash/delegation-request.ts +14 -0
  168. package/src/slash/slash-commands.ts +2 -7
  169. package/src/slash/subagents-admin.ts +31 -14
  170. package/src/tui/fleet-status.ts +165 -20
  171. package/src/tui/fleet.ts +30 -19
  172. package/src/tui/render.ts +210 -50
  173. package/src/watchdog/child-status.ts +28 -28
  174. package/src/watchdog/lsp-diagnostics.ts +1 -1
  175. package/src/watchdog/model-selection.ts +21 -1
  176. package/src/watchdog/permission-arbiter.ts +5 -2
  177. package/src/watchdog/register-child.ts +10 -2
  178. package/src/watchdog/register-main.ts +39 -35
  179. package/src/watchdog/render.ts +1 -1
  180. package/src/watchdog/review.ts +122 -74
  181. package/src/watchdog/rules.ts +1 -1
  182. package/src/watchdog/runtime.ts +100 -27
  183. package/src/watchdog/scope.ts +1 -1
  184. package/src/watchdog/settings.ts +3 -0
  185. package/src/watchdog/tool-actions.ts +13 -12
  186. package/src/watchdog/turn-delta.ts +23 -0
  187. package/src/watchdog/types.ts +5 -3
  188. package/src/watchdog/warning-format.ts +1 -1
  189. package/src/workflows/chat-progress.ts +3 -3
  190. package/src/workflows/scripted-workflow.ts +349 -26
  191. package/src/workflows/workflow-checklist.ts +17 -20
  192. package/src/workflows/workflow-child-summary.ts +57 -8
  193. package/src/workflows/workflow-preflight.ts +19 -19
  194. package/src/workflows/workflow-receipt.ts +24 -6
  195. package/src/workflows/workflow-resources.ts +108 -22
  196. package/src/workflows/workflow-settlement.ts +3 -0
  197. package/src/runs/shared/model-exclusions.ts +0 -373
  198. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -15,6 +15,7 @@ import { previewSimpleWorkflowRun } from "../../workflows/scripted-workflow.ts";
15
15
  import { resolveGitRepositoryIdentity } from "../../workflows/chat-progress.ts";
16
16
  import { getConfigDirName } from "../../shared/utils.ts";
17
17
  import { normalizeWorktreeBaseRef } from "../shared/worktree.ts";
18
+ import { deepFreezeWorkflowArgs, normalizeWorkflowArgs } from "../../workflows/workflow-resources.ts";
18
19
 
19
20
  export const SCHEDULED_RUN_ACTIONS = [
20
21
  "schedule.create",
@@ -40,7 +41,7 @@ export type ScheduleRunState = "running" | "skipped" | "missed" | "completed" |
40
41
  export type ScheduleTrigger =
41
42
  | { kind: "once"; at: string; nextRunAt?: string }
42
43
  | { kind: "interval"; every: string; everyMs: number; anchorAt: string; nextRunAt: string };
43
- export type ScheduleTarget = { workflowScript: string; baseRef?: string };
44
+ export type ScheduleTarget = { workflowScript: string; args: Record<string, unknown>; baseRef?: string };
44
45
 
45
46
  export interface ScheduleRecord {
46
47
  schemaVersion: 1;
@@ -54,6 +55,7 @@ export interface ScheduleRecord {
54
55
  timeoutMs?: number;
55
56
  paused: boolean;
56
57
  sessionOnly?: boolean;
58
+ quiet?: boolean;
57
59
  ownerSessionFile?: string;
58
60
  createdAt: string;
59
61
  updatedAt: string;
@@ -282,14 +284,17 @@ function readJson(file: string, label: string): unknown {
282
284
 
283
285
  function parseScheduleTarget(value: unknown, file: string): ScheduleTarget {
284
286
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Schedule record '${file}' has invalid trigger or target.`);
285
- const target = value as { workflowScript?: unknown; baseRef?: unknown; agent?: unknown; task?: unknown };
287
+ const target = value as { workflowScript?: unknown; args?: unknown; baseRef?: unknown; agent?: unknown; task?: unknown };
286
288
  if (typeof target.workflowScript === "string" && target.workflowScript.trim()) {
289
+ let baseRef: string | undefined;
287
290
  try {
288
- const baseRef = normalizeWorktreeBaseRef(target.baseRef);
289
- return { workflowScript: target.workflowScript.trim(), ...(baseRef === undefined ? {} : { baseRef }) };
291
+ baseRef = normalizeWorktreeBaseRef(target.baseRef);
290
292
  } catch (error) {
291
293
  throw new Error(`Schedule record '${file}' has an invalid baseRef: ${error instanceof Error ? error.message : String(error)}`);
292
294
  }
295
+ const normalizedArgs = normalizeWorkflowArgs(target.args);
296
+ if ("error" in normalizedArgs) throw new Error(`Schedule record '${file}' has invalid args: ${normalizedArgs.error}`);
297
+ return { workflowScript: target.workflowScript.trim(), args: deepFreezeWorkflowArgs(normalizedArgs.args), ...(baseRef === undefined ? {} : { baseRef }) };
293
298
  }
294
299
  if (target.agent !== undefined || target.task !== undefined) throw new Error(`Schedule record '${file}' uses a removed legacy agent target; recreate it with target.workflowScript.`);
295
300
  throw new Error(`Schedule record '${file}' requires a workflowScript target.`);
@@ -308,6 +313,7 @@ function parseSchedule(value: unknown, file: string): ScheduleRecord {
308
313
  if (typeof record.trigger.every !== "string" || typeof record.trigger.everyMs !== "number" || typeof record.trigger.anchorAt !== "string" || typeof record.trigger.nextRunAt !== "string") throw new Error(`Schedule record '${file}' has an invalid interval trigger.`);
309
314
  } else throw new Error(`Schedule record '${file}' has an unsupported trigger.`);
310
315
  if (record.sessionOnly !== undefined && typeof record.sessionOnly !== "boolean") throw new Error(`Schedule record '${file}' has invalid sessionOnly.`);
316
+ if (record.quiet !== undefined && typeof record.quiet !== "boolean") throw new Error(`Schedule record '${file}' has invalid quiet.`);
311
317
  if (record.sessionOnly === true && (typeof record.ownerSessionFile !== "string" || !record.ownerSessionFile.trim())) throw new Error(`Schedule record '${file}' is session-only but has no owner session file.`);
312
318
  return { ...record, target: parseScheduleTarget(record.target, file) } as ScheduleRecord;
313
319
  }
@@ -445,10 +451,12 @@ function sanitizeTarget(params: SubagentParamsLike): { target?: ScheduleTarget;
445
451
  }
446
452
  const acceptanceErrors = validateExecutionAcceptance(params as Parameters<typeof validateExecutionAcceptance>[0]);
447
453
  if (acceptanceErrors.length) return { error: acceptanceErrors.join(" ") };
448
- return { target: { workflowScript: params.workflowScript.trim(), ...(baseRef === undefined ? {} : { baseRef }) } };
454
+ const normalizedArgs = normalizeWorkflowArgs(params.args);
455
+ if ("error" in normalizedArgs) return { error: normalizedArgs.error };
456
+ return { target: { workflowScript: params.workflowScript.trim(), args: deepFreezeWorkflowArgs(normalizedArgs.args), ...(baseRef === undefined ? {} : { baseRef }) } };
449
457
  }
450
458
 
451
- function executionParams(schedule: ScheduleRecord): SubagentParamsLike {
459
+ function executionParams(schedule: ScheduleRecord, quiet = false): SubagentParamsLike {
452
460
  return {
453
461
  ...schedule.target,
454
462
  async: true,
@@ -456,7 +464,7 @@ function executionParams(schedule: ScheduleRecord): SubagentParamsLike {
456
464
  cwd: schedule.cwd,
457
465
  mission: false,
458
466
  // Scheduled fires have no operator watching, so completions must name the origin.
459
- scheduleOrigin: { id: schedule.id, ...(schedule.name ? { name: schedule.name } : {}) },
467
+ scheduleOrigin: { id: schedule.id, ...(schedule.name ? { name: schedule.name } : {}), ...(quiet ? { quiet: true } : {}) },
460
468
  ...(schedule.timeoutMs === undefined ? {} : { timeoutMs: schedule.timeoutMs }),
461
469
  };
462
470
  }
@@ -612,6 +620,8 @@ export class ScheduledRunManager {
612
620
  if (params.catchUp !== undefined && params.catchUp !== "none" && params.catchUp !== "latest") return textResult("catchUp must be 'none' or 'latest'.", undefined, undefined, true);
613
621
  if (params.missionId !== undefined || params.mission !== undefined || params.missionUpdate !== undefined || params.missionStatus !== undefined || params.missionScope !== undefined) return textResult("Mission attachment is deferred from this first schedule slice.", undefined, undefined, true);
614
622
  if (params.on !== undefined || params.timezone !== undefined || every === "day" || every === "week" || every === "month" || every === "year") return textResult("Calendar schedules are deferred from this first safe slice. Use a fixed interval such as every:'24h' or every:'7d'.", undefined, undefined, true);
623
+ if (params.quiet !== undefined && typeof params.quiet !== "boolean") return textResult("quiet must be a boolean.", undefined, undefined, true);
624
+ if (at && params.quiet === true) return textResult("quiet is only supported for recurring schedules.", undefined, undefined, true);
615
625
  const sessionOnly = params.sessionOnly === true;
616
626
  if (sessionOnly && params.cwd !== undefined && !samePath(params.cwd, ctx.cwd)) return textResult("sessionOnly schedules cannot use an explicit cross-project cwd.", undefined, undefined, true);
617
627
  const ownerSessionFile = sessionOnly ? ctx.sessionManager.getSessionFile() : undefined;
@@ -644,13 +654,14 @@ export class ScheduledRunManager {
644
654
  ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }),
645
655
  paused: false,
646
656
  ...(sessionOnly ? { sessionOnly: true, ownerSessionFile: path.resolve(ownerSessionFile!) } : {}),
657
+ ...(trigger.kind === "interval" && params.quiet === true ? { quiet: true } : {}),
647
658
  createdAt: timestamp(now),
648
659
  updatedAt: timestamp(now),
649
660
  };
650
661
  store.write(schedule);
651
662
  store.appendEvent(schedule, "schedule.created");
652
663
  this.arm(schedule, store);
653
- return textResult(`Created schedule ${id}.\nName: ${schedule.name}\nTrigger: ${at ? `at ${at}` : `every ${every}`}\nSession only: ${schedule.sessionOnly === true ? "yes" : "no"}\nNext: ${schedule.trigger.nextRunAt}\nTarget: ${targetLabel(schedule.target)}`, [schedule]);
664
+ return textResult(`Created schedule ${id}.\nName: ${schedule.name}\nTrigger: ${at ? `at ${at}` : `every ${every}`}\nSession only: ${schedule.sessionOnly === true ? "yes" : "no"}\nQuiet: ${schedule.quiet === true ? "yes" : "no"}\nNext: ${schedule.trigger.nextRunAt}\nTarget: ${targetLabel(schedule.target)}`, [schedule]);
654
665
  }
655
666
 
656
667
  private list(): AgentToolResult<Details> {
@@ -661,7 +672,7 @@ export class ScheduledRunManager {
661
672
 
662
673
  private show(params: SubagentParamsLike): AgentToolResult<Details> {
663
674
  const schedule = this.resolve(params);
664
- return textResult([`Schedule: ${schedule.id}`, `Name: ${schedule.name}`, `State: ${schedule.paused ? "paused" : schedule.activeRunId ? "running" : "scheduled"}`, `Session only: ${schedule.sessionOnly === true ? "yes" : "no"}`, `Target: ${targetLabel(schedule.target)}`, `CWD: ${shortenPath(schedule.cwd)}`, `Next: ${schedule.trigger.nextRunAt ?? "none"}`, `Catch up: ${schedule.catchUp}`, schedule.activeRunId ? `Active run: ${schedule.activeRunId}` : undefined].filter(Boolean).join("\n"), [schedule]);
675
+ return textResult([`Schedule: ${schedule.id}`, `Name: ${schedule.name}`, `State: ${schedule.paused ? "paused" : schedule.activeRunId ? "running" : "scheduled"}`, `Session only: ${schedule.sessionOnly === true ? "yes" : "no"}`, `Quiet: ${schedule.quiet === true ? "yes" : "no"}`, `Target: ${targetLabel(schedule.target)}`, `CWD: ${shortenPath(schedule.cwd)}`, `Next: ${schedule.trigger.nextRunAt ?? "none"}`, `Catch up: ${schedule.catchUp}`, schedule.activeRunId ? `Active run: ${schedule.activeRunId}` : undefined].filter(Boolean).join("\n"), [schedule]);
665
676
  }
666
677
 
667
678
  private history(params: SubagentParamsLike): AgentToolResult<Details> {
@@ -689,7 +700,18 @@ export class ScheduledRunManager {
689
700
  if (!scheduleBelongsToSession(schedule, context)) {
690
701
  return textResult(`Skipped schedule ${schedule.id}: current session is not its owner.`, [schedule]);
691
702
  }
692
- const run = await this.launch(store, schedule, this.now(), "manual", false);
703
+ if (params.quiet !== undefined && typeof params.quiet !== "boolean") return textResult("quiet must be a boolean.", undefined, undefined, true);
704
+ const run = await this.launch(store, schedule, this.now(), "manual", false, params.quiet === true);
705
+ const updated = store.get(schedule.id);
706
+ if (run.state === "running") {
707
+ const now = this.now();
708
+ if (updated.trigger.kind === "interval") updated.trigger.nextRunAt = timestamp(now + updated.trigger.everyMs);
709
+ else updated.trigger.nextRunAt = undefined;
710
+ updated.updatedAt = timestamp(now);
711
+ store.write(updated);
712
+ store.appendEvent(updated, "schedule.manual_satisfied");
713
+ this.arm(updated, store);
714
+ }
693
715
  return textResult(`Manual schedule run ${run.id}: ${run.state}${run.asyncId ? ` (async ${run.asyncId})` : ""}.`, [store.get(schedule.id)], [run], run.state === "failed_launch");
694
716
  }
695
717
 
@@ -708,8 +730,16 @@ export class ScheduledRunManager {
708
730
 
709
731
  private remove(params: SubagentParamsLike): AgentToolResult<Details> {
710
732
  const schedule = this.resolve(params);
711
- if (schedule.activeRunId) return textResult(`Schedule ${schedule.id} has active run ${schedule.activeRunId}; stop that run before deleting the schedule.`, [schedule], undefined, true);
712
733
  const store = this.requireStore();
734
+ if (schedule.activeRunId) {
735
+ const run = store.history(schedule.id).find((item) => item.id === schedule.activeRunId);
736
+ let terminal = false;
737
+ if (run?.scheduleId === schedule.id && run.state === "running" && run.asyncId && run.asyncDir) {
738
+ const status = readJson(path.join(run.asyncDir, "status.json"), "async status") as Partial<AsyncStatus>;
739
+ terminal = status.runId === run.asyncId && typeof status.state === "string" && ["complete", "failed", "stopped", "rejected"].includes(status.state);
740
+ }
741
+ if (!terminal) return textResult(`Schedule ${schedule.id} has active run ${schedule.activeRunId}; stop that run before deleting the schedule.`, [schedule], undefined, true);
742
+ }
713
743
  this.clearTimer(store, schedule.id);
714
744
  store.appendEvent(schedule, "schedule.deleted");
715
745
  store.delete(schedule.id);
@@ -807,8 +837,9 @@ export class ScheduledRunManager {
807
837
  await this.launch(store, schedule, planned, "timer", true);
808
838
  }
809
839
 
810
- private async launch(store: ScheduleStore, schedule: ScheduleRecord, planned: number, dueReason: ScheduleRunRecord["dueReason"], advance: boolean): Promise<ScheduleRunRecord> {
840
+ private async launch(store: ScheduleStore, schedule: ScheduleRecord, planned: number, dueReason: ScheduleRunRecord["dueReason"], advance: boolean, quiet?: boolean): Promise<ScheduleRunRecord> {
811
841
  const now = this.now();
842
+ const nextRunAtBeforeClaim = schedule.trigger.nextRunAt;
812
843
  const run: ScheduleRunRecord = { schemaVersion: 1, id: this.randomId(), scheduleId: schedule.id, plannedAt: timestamp(planned), dueReason, state: "running", startedAt: timestamp(now) };
813
844
  if (schedule.activeRunId) {
814
845
  run.state = "skipped";
@@ -849,7 +880,7 @@ export class ScheduledRunManager {
849
880
  store.write(schedule);
850
881
  store.writeRun(schedule, run, "schedule.run.started");
851
882
  try {
852
- const result = await this.deps.launch(executionParams(schedule), this.requireContext(store), new AbortController().signal);
883
+ const result = await this.deps.launch(executionParams(schedule, dueReason === "manual" ? quiet === true : schedule.quiet === true), this.requireContext(store), new AbortController().signal);
853
884
  const asyncId = result.details?.asyncId ?? result.details?.runId;
854
885
  if (result.isError || !asyncId) throw new Error(result.content.find((item) => item.type === "text")?.text ?? "Scheduled launch failed.");
855
886
  run.asyncId = asyncId;
@@ -862,12 +893,14 @@ export class ScheduledRunManager {
862
893
  run.state = "failed_launch";
863
894
  run.completedAt = timestamp(this.now());
864
895
  run.error = error instanceof Error ? error.message : String(error);
865
- schedule.activeRunId = undefined;
866
- schedule.updatedAt = timestamp(this.now());
867
- store.write(schedule);
868
- store.writeRun(schedule, run, "schedule.run.failed");
896
+ const latest = store.get(schedule.id);
897
+ latest.activeRunId = undefined;
898
+ if (!advance && nextRunAtBeforeClaim) latest.trigger.nextRunAt = nextRunAtBeforeClaim;
899
+ latest.updatedAt = timestamp(this.now());
900
+ store.write(latest);
901
+ store.writeRun(latest, run, "schedule.run.failed");
869
902
  fs.rmSync(lockPath, { force: true });
870
- this.arm(schedule, store);
903
+ this.arm(latest, store);
871
904
  return run;
872
905
  }
873
906
  }
@@ -9,6 +9,7 @@ import { resolveEffectiveThinking } from "../../shared/model-info.ts";
9
9
  import { normalizeParallelGroups } from "./parallel-groups.ts";
10
10
  import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent, type NestedRoute } from "../shared/nested-events.ts";
11
11
  import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.ts";
12
+ import type { RawDrainStatusObserver } from "../shared/readonly-drain-observation.ts";
12
13
 
13
14
  export type PidLiveness = "alive" | "dead" | "unknown";
14
15
 
@@ -98,13 +99,13 @@ interface ResultChildOutcome {
98
99
  sessionFile?: string;
99
100
  model?: string;
100
101
  thinking?: string;
101
- attemptedModels?: string[];
102
- modelAttempts?: NonNullable<AsyncStatus["steps"]>[number]["modelAttempts"];
102
+ requestedModel?: string;
103
103
  contextOverflow?: boolean;
104
104
  }
105
105
 
106
106
  interface ResultRepairData {
107
107
  state: "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
108
+ error?: string;
108
109
  results?: ResultChildOutcome[];
109
110
  }
110
111
 
@@ -119,7 +120,8 @@ function regularFileExists(filePath: string): boolean {
119
120
 
120
121
  function readResultRepairData(resultPath: string): ResultRepairData | undefined {
121
122
  try {
122
- const data = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as { success?: boolean; state?: string; exitCode?: number; results?: unknown };
123
+ const data = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as { success?: boolean; state?: string; exitCode?: number; error?: unknown; results?: unknown };
124
+ if (data.error !== undefined && typeof data.error !== "string") throw new Error(`Invalid async result file '${resultPath}': error must be a string.`);
123
125
  const state = data.success ? "complete" : data.state === "stopped" ? "stopped" : data.state === "rejected" ? "rejected" : data.state === "partial" ? "partial" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
124
126
  const results = Array.isArray(data.results)
125
127
  ? data.results.map((entry, index) => {
@@ -130,7 +132,7 @@ function readResultRepairData(resultPath: string): ResultRepairData | undefined
130
132
  return child;
131
133
  })
132
134
  : undefined;
133
- return { state, ...(results ? { results } : {}) };
135
+ return { state, ...(data.error ? { error: data.error } : {}), ...(results ? { results } : {}) };
134
136
  } catch (error) {
135
137
  if (isNotFoundError(error)) return undefined;
136
138
  throw new Error(`Failed to read async result file '${resultPath}': ${getErrorMessage(error)}`, {
@@ -145,9 +147,16 @@ function childState(overallState: ResultRepairData["state"], child: ResultChildO
145
147
  return overallState;
146
148
  }
147
149
 
150
+ function failureDiagnostic(value: unknown): string | undefined {
151
+ return typeof value === "string" && value.trim() ? value : undefined;
152
+ }
153
+
148
154
  function terminalStatusFromResult(status: AsyncStatus, resultPath: string, now: number): AsyncStatus | undefined {
149
155
  const repair = readResultRepairData(resultPath);
150
156
  if (!repair) return undefined;
157
+ const rootError = failureDiagnostic(status.error)
158
+ ?? failureDiagnostic(repair.error)
159
+ ?? repair.results?.map((child) => child.success === false ? failureDiagnostic(child.error) : undefined).find(Boolean);
151
160
  const steps = (status.steps ?? []).map((step, index) => {
152
161
  if (step.status !== "running" && step.status !== "pending") return step;
153
162
  const child = repair.results?.[index];
@@ -166,14 +175,14 @@ function terminalStatusFromResult(status: AsyncStatus, resultPath: string, now:
166
175
  sessionFile: step.sessionFile ?? child?.sessionFile,
167
176
  model,
168
177
  thinking,
169
- attemptedModels: child?.attemptedModels ?? step.attemptedModels,
170
- modelAttempts: child?.modelAttempts ?? step.modelAttempts,
178
+ requestedModel: child?.requestedModel ?? step.requestedModel,
171
179
  contextOverflow: child?.contextOverflow ?? step.contextOverflow,
172
180
  };
173
181
  });
174
182
  const terminalStatus: AsyncStatus = {
175
183
  ...status,
176
184
  state: repair.state,
185
+ ...(rootError && (repair.state === "failed" || repair.state === "partial") ? { error: rootError } : {}),
177
186
  ...(status.lifecycleArtifactVersion === 3 && (!status.processTerminal || status.processTerminal.state === "pending") ? {
178
187
  processTerminal: { version: 1 as const, state: "unknown" as const, runId: status.runId, runnerProcessInstanceId: "observer-unavailable", reason: "observer-unavailable" as const },
179
188
  } : {}),
@@ -263,8 +272,7 @@ function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, r
263
272
  error: step.status === "complete" || step.status === "completed" ? undefined : step.error ?? message,
264
273
  success: step.status === "complete" || step.status === "completed",
265
274
  model: step.model,
266
- attemptedModels: step.attemptedModels,
267
- modelAttempts: step.modelAttempts,
275
+ requestedModel: step.requestedModel,
268
276
  contextOverflow: step.contextOverflow,
269
277
  sessionFile: step.sessionFile,
270
278
  })),
@@ -352,9 +360,10 @@ export function checkPidLiveness(pid: number, kill: KillFn = process.kill): PidL
352
360
  }
353
361
  }
354
362
 
355
- export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOptions = {}): ReconcileAsyncRunResult {
363
+ export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOptions = {}, observeStatus?: RawDrainStatusObserver): ReconcileAsyncRunResult {
356
364
  const now = options.now?.() ?? Date.now();
357
365
  const status = readStatus(asyncDir);
366
+ observeStatus?.(status);
358
367
  const startedStatus = !status && options.startedRun ? buildStartedStatus(asyncDir, options.startedRun, now) : undefined;
359
368
  const effectiveStatus = status ?? startedStatus;
360
369
  if (!effectiveStatus) return { status: null, repaired: false };
@@ -376,9 +385,26 @@ export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOp
376
385
  ? terminalStatusFromResult(effectiveStatus, existingResultPath, now)
377
386
  : undefined;
378
387
  if (terminalStatus) {
379
- writeAtomicJson(path.join(asyncDir, "status.json"), terminalStatus);
380
- updateActiveRunIndex(asyncDir, terminalStatus.state, terminalStatus.toolCallId);
381
- return { status: terminalStatus, repaired: true, resultPath: existingResultPath, message: "Existing async result file was used to repair stale running status." };
388
+ const currentStatus = readStatus(asyncDir);
389
+ const currentRootError = failureDiagnostic(currentStatus?.error);
390
+ const currentTerminal = currentStatus?.processTerminal?.state === "observed" || currentStatus?.processTerminal?.state === "unknown"
391
+ ? currentStatus.processTerminal
392
+ : undefined;
393
+ const steps = terminalStatus.steps?.map((step, index) => {
394
+ const currentStepTerminal = currentStatus?.steps?.[index]?.processTerminal;
395
+ return currentStepTerminal?.state === "observed" || currentStepTerminal?.state === "unknown"
396
+ ? { ...step, processTerminal: currentStepTerminal }
397
+ : step;
398
+ });
399
+ const statusToWrite: AsyncStatus = {
400
+ ...terminalStatus,
401
+ ...(currentRootError ? { error: currentRootError } : {}),
402
+ ...(currentTerminal ? { processTerminal: currentTerminal } : {}),
403
+ ...(steps ? { steps } : {}),
404
+ };
405
+ writeAtomicJson(statusPath, statusToWrite);
406
+ updateActiveRunIndex(asyncDir, statusToWrite.state, statusToWrite.toolCallId);
407
+ return { status: statusToWrite, repaired: true, resultPath: existingResultPath, message: "Existing async result file was used to repair stale running status." };
382
408
  }
383
409
  if (effectiveStatus.displayDismissedAt === undefined) return { status: effectiveStatus, repaired: false, resultPath: existingResultPath };
384
410
  }
@@ -14,6 +14,7 @@ import type {
14
14
  import { readStatus } from "../../shared/utils.ts";
15
15
  import { previewDisplayText } from "../../shared/display-text.ts";
16
16
  import { redactSecretValues } from "../shared/permissions.ts";
17
+ import type { SteerDeliveryMode } from "./control-channel.ts";
17
18
 
18
19
  export const MAX_STEERING_REQUESTS = 20;
19
20
  export const STEERING_MESSAGE_PREVIEW_LIMIT = 160;
@@ -22,6 +23,21 @@ export function steeringMessagePreview(message: string): string {
22
23
  return previewDisplayText(redactSecretValues(message), STEERING_MESSAGE_PREVIEW_LIMIT);
23
24
  }
24
25
 
26
+ /** FIFO match of one accepted steer to an emitted user message; equal text claims the oldest entry. */
27
+ export function takeMatchingAcceptedSteer<T extends { text: string }>(accepted: T[], messageText: string): T | undefined {
28
+ const index = accepted.findIndex((entry) => entry.text === messageText);
29
+ if (index < 0) return undefined;
30
+ const [entry] = accepted.splice(index, 1);
31
+ return entry;
32
+ }
33
+
34
+ /** Settlement reason for one accepted request that never got a matching user `message_end`. */
35
+ export function unconsumedSteerReason(mode?: SteerDeliveryMode): string {
36
+ return mode === "follow_up"
37
+ ? "child completed before consuming follow-up"
38
+ : "child completed before consuming steering";
39
+ }
40
+
25
41
  export function steeringReceipt(message: string, receipt: string): string {
26
42
  const preview = steeringMessagePreview(message);
27
43
  const longestFence = Math.max(2, ...[...preview.matchAll(/`{3,}/g)].map((match) => match[0]!.length));
@@ -93,7 +109,9 @@ export function updateSteeringTarget(
93
109
  if (fields.replacementRunId) target.replacementRunId = fields.replacementRunId;
94
110
  return target;
95
111
  }
96
- if ((target.state === "routed" || target.state === "queued") && state !== "routed" && state !== "queued") status.pending = Math.max(0, status.pending - 1);
112
+ const wasPending = target.state === "routed" || target.state === "queued";
113
+ const nowPending = state === "routed" || state === "queued";
114
+ if (wasPending && !nowPending) status.pending = Math.max(0, status.pending - 1);
97
115
  target.state = state;
98
116
  if (state === "routed") target.routedAt = now;
99
117
  if (state === "delivered") {
@@ -108,7 +126,7 @@ export function updateSteeringTarget(
108
126
  if (state === "recovered") target.recoveredAt = now;
109
127
  if (fields.reason) target.reason = fields.reason;
110
128
  if (fields.replacementRunId) target.replacementRunId = fields.replacementRunId;
111
- incrementStateCount(status, state);
129
+ if (!wasPending || !nowPending) incrementStateCount(status, state);
112
130
  return target;
113
131
  }
114
132