@xzzpig/pi-subagents 0.7.0 → 0.9.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 (234) hide show
  1. package/CHANGELOG.md +456 -4
  2. package/README.md +3 -3
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +13 -3
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +154 -42
  12. package/docs/configuration.md +85 -26
  13. package/docs/extension-api.md +81 -16
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +75 -11
  16. package/docs/observability.md +34 -21
  17. package/docs/tool-reference.md +142 -18
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +148 -4
  20. package/index.ts +10 -1
  21. package/install.mjs +1 -1
  22. package/package.json +7 -6
  23. package/prompts/council.md +19 -7
  24. package/prompts/parallel-review.md +5 -1
  25. package/prompts/review-loop.md +11 -7
  26. package/skills/council-mode/SKILL.md +44 -215
  27. package/skills/council-mode/references/pass-contracts.md +150 -0
  28. package/skills/pi-subagents/SKILL.md +90 -32
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +34 -223
  30. package/skills/pi-subagents/references/execution-controls.md +104 -19
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +16 -4
  33. package/skills/pi-subagents/references/prompting-and-roles.md +71 -36
  34. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  35. package/src/agents/agent-management.ts +471 -114
  36. package/src/agents/agent-refinements.ts +4 -4
  37. package/src/agents/agent-serializer.ts +16 -4
  38. package/src/agents/agents.ts +1076 -351
  39. package/src/agents/builtin-names.ts +6 -0
  40. package/src/agents/runtime-agent-events.ts +70 -0
  41. package/src/agents/runtime-agent-registry.ts +31 -20
  42. package/src/api/agents.ts +10 -5
  43. package/src/api/background-work.ts +12 -3
  44. package/src/api/capability-ceiling.ts +0 -1
  45. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  46. package/src/api/delegation.ts +0 -7
  47. package/src/api/external-job-provider.ts +10 -1
  48. package/src/api/external-runs.ts +67 -4
  49. package/src/api/preflight.ts +97 -34
  50. package/src/api/project-panes.ts +2 -0
  51. package/src/api/shared-types.ts +6 -0
  52. package/src/extension/config.ts +90 -0
  53. package/src/extension/doctor.ts +15 -13
  54. package/src/extension/fanout-child.ts +17 -16
  55. package/src/extension/index.ts +139 -41
  56. package/src/extension/public-execution.ts +113 -22
  57. package/src/extension/rpc.ts +182 -13
  58. package/src/extension/schemas.ts +63 -21
  59. package/src/extension/tool-description.ts +48 -23
  60. package/src/extension/tool-result.ts +19 -0
  61. package/src/inspectors/herdr/actions.ts +2 -1
  62. package/src/inspectors/herdr/client.ts +3 -3
  63. package/src/inspectors/herdr/focus.ts +55 -0
  64. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  65. package/src/inspectors/herdr/project-panes.ts +228 -44
  66. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  67. package/src/integrations/herdr-status.ts +75 -5
  68. package/src/intercom/native-supervisor-channel.ts +138 -60
  69. package/src/intercom/result-intercom.ts +2 -0
  70. package/src/intercom/supervisor-ui.ts +243 -0
  71. package/src/profiles/profiles.ts +5 -6
  72. package/src/runs/background/active-async-capacity.ts +103 -18
  73. package/src/runs/background/async-execution.ts +492 -125
  74. package/src/runs/background/async-job-tracker.ts +127 -28
  75. package/src/runs/background/async-resume.ts +67 -29
  76. package/src/runs/background/async-retention.ts +21 -4
  77. package/src/runs/background/async-status-snapshot.ts +23 -261
  78. package/src/runs/background/async-status.ts +199 -14
  79. package/src/runs/background/auto-drain.ts +1 -1
  80. package/src/runs/background/chain-append.ts +8 -3
  81. package/src/runs/background/chain-root-attachment.ts +79 -8
  82. package/src/runs/background/control-channel.ts +101 -214
  83. package/src/runs/background/fleet-view.ts +38 -22
  84. package/src/runs/background/inspect-rpc.ts +8 -8
  85. package/src/runs/background/notify.ts +295 -8
  86. package/src/runs/background/process-terminal.ts +16 -0
  87. package/src/runs/background/result-delivery-ownership.ts +45 -0
  88. package/src/runs/background/result-files.ts +28 -14
  89. package/src/runs/background/result-watcher.ts +43 -19
  90. package/src/runs/background/resume-guidance.ts +2 -2
  91. package/src/runs/background/retained-children.ts +1 -1
  92. package/src/runs/background/run-child-session.ts +613 -0
  93. package/src/runs/background/run-status.ts +99 -18
  94. package/src/runs/background/runner-aliases.ts +125 -0
  95. package/src/runs/background/runner-child-sessions.ts +31 -0
  96. package/src/runs/background/scheduled-runs.ts +174 -18
  97. package/src/runs/background/stale-run-reconciler.ts +13 -4
  98. package/src/runs/background/steering.ts +8 -15
  99. package/src/runs/background/subagent-runner.ts +959 -1159
  100. package/src/runs/background/subagent-wait.ts +86 -31
  101. package/src/runs/background/terminal-run-index.ts +1 -1
  102. package/src/runs/background/wait-completions.ts +45 -2
  103. package/src/runs/background/wait-config.ts +23 -9
  104. package/src/runs/background/wait-tool.ts +27 -19
  105. package/src/runs/foreground/async-steering-action.ts +3 -19
  106. package/src/runs/foreground/async-stop-action.ts +23 -2
  107. package/src/runs/foreground/execution.ts +585 -481
  108. package/src/runs/foreground/foreground-control.ts +13 -0
  109. package/src/runs/foreground/foreground-history.ts +26 -3
  110. package/src/runs/foreground/subagent-executor.ts +1549 -410
  111. package/src/runs/foreground/workflow-detach-reconcile.ts +141 -104
  112. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  113. package/src/runs/shared/abort-recovery.ts +119 -0
  114. package/src/runs/shared/acceptance.ts +147 -39
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +565 -0
  117. package/src/runs/shared/background-process-options.ts +9 -0
  118. package/src/runs/shared/capability-ceiling.ts +2 -2
  119. package/src/runs/shared/child-hooks.ts +25 -0
  120. package/src/runs/shared/child-identity.ts +62 -0
  121. package/src/runs/shared/child-launch-plan.ts +151 -0
  122. package/src/runs/shared/child-launch.ts +314 -0
  123. package/src/runs/shared/child-lifecycle.ts +25 -0
  124. package/src/runs/shared/child-runtime-config.ts +126 -0
  125. package/src/runs/shared/child-session.ts +342 -0
  126. package/src/runs/shared/child-tool-plan.ts +540 -0
  127. package/src/runs/shared/claude-code-adapter.ts +133 -0
  128. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  129. package/src/runs/shared/completion-evidence.ts +89 -0
  130. package/src/runs/shared/completion-guard.ts +57 -6
  131. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  132. package/src/runs/shared/dynamic-fanout.ts +4 -4
  133. package/src/runs/shared/extension-bindings.ts +78 -0
  134. package/src/runs/shared/external-cli-contract.ts +167 -0
  135. package/src/runs/shared/external-cli-preflight.ts +138 -0
  136. package/src/runs/shared/external-cli-runner.ts +349 -54
  137. package/src/runs/shared/external-job-bridge.ts +53 -37
  138. package/src/runs/shared/external-job-runner.ts +126 -23
  139. package/src/runs/shared/fast-mode-extension.ts +10 -0
  140. package/src/runs/shared/host-step-status.ts +231 -0
  141. package/src/runs/shared/lane-metadata.ts +126 -0
  142. package/src/runs/shared/launch-cwd.ts +16 -0
  143. package/src/runs/shared/long-running-guard.ts +2 -1
  144. package/src/runs/shared/mcp-config-sources.ts +422 -0
  145. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  146. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  147. package/src/runs/shared/model-exclusions.ts +141 -10
  148. package/src/runs/shared/model-fallback.ts +187 -33
  149. package/src/runs/shared/model-scope.ts +106 -39
  150. package/src/runs/shared/mutation-evidence.ts +199 -0
  151. package/src/runs/shared/nested-events.ts +38 -48
  152. package/src/runs/shared/nested-path.ts +0 -14
  153. package/src/runs/shared/nested-render.ts +9 -5
  154. package/src/runs/shared/orca-progress-tabs.ts +83 -16
  155. package/src/runs/shared/parallel-handoff.ts +423 -7
  156. package/src/runs/shared/parallel-utils.ts +28 -5
  157. package/src/runs/shared/permissions.ts +1 -14
  158. package/src/runs/shared/pi-spawn.ts +69 -35
  159. package/src/runs/shared/process-signal.ts +16 -0
  160. package/src/runs/shared/run-fanout-budget.ts +0 -13
  161. package/src/runs/shared/run-history.ts +21 -1
  162. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  163. package/src/runs/shared/single-output.ts +89 -22
  164. package/src/runs/shared/structured-output.ts +61 -7
  165. package/src/runs/shared/subagent-control.ts +6 -2
  166. package/src/runs/shared/subagent-prompt-runtime.ts +216 -360
  167. package/src/runs/shared/task-intent.ts +21 -7
  168. package/src/runs/shared/tool-availability.ts +18 -64
  169. package/src/runs/shared/tool-budget.ts +0 -14
  170. package/src/runs/shared/tool-timeout.ts +1 -1
  171. package/src/runs/shared/workflow-graph.ts +16 -0
  172. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  173. package/src/runs/shared/worktree.ts +571 -62
  174. package/src/shared/atomic-json.ts +3 -1
  175. package/src/shared/child-session-name.ts +46 -0
  176. package/src/shared/extension-context.ts +24 -0
  177. package/src/shared/fork-context.ts +21 -12
  178. package/src/shared/fork-session-cwd.ts +27 -0
  179. package/src/shared/formatters.ts +18 -3
  180. package/src/shared/jsonl-writer.ts +11 -0
  181. package/src/shared/launch-contract.ts +20 -6
  182. package/src/shared/pruned-fork.ts +450 -0
  183. package/src/shared/session-file-trust.ts +19 -0
  184. package/src/shared/session-tokens.ts +14 -3
  185. package/src/shared/settings.ts +21 -102
  186. package/src/shared/shortcuts.ts +17 -0
  187. package/src/shared/thinking-ceiling.ts +46 -0
  188. package/src/shared/types.ts +644 -75
  189. package/src/shared/utils.ts +60 -93
  190. package/src/shared/workflow-child-permit.ts +207 -0
  191. package/src/slash/delegation-adapters.ts +1 -9
  192. package/src/slash/delegation-request.ts +0 -4
  193. package/src/slash/prompt-template-bridge.ts +37 -1
  194. package/src/slash/slash-bridge.ts +1 -2
  195. package/src/slash/slash-commands.ts +383 -116
  196. package/src/slash/slash-live-state.ts +22 -11
  197. package/src/slash/subagents-admin.ts +29 -12
  198. package/src/tui/fleet-native-transcript.ts +4 -0
  199. package/src/tui/fleet-status.ts +278 -90
  200. package/src/tui/fleet-transcript.ts +11 -5
  201. package/src/tui/fleet.ts +54 -28
  202. package/src/tui/render-helpers.ts +31 -0
  203. package/src/tui/render.ts +1433 -166
  204. package/src/watchdog/change-signature.ts +40 -1
  205. package/src/watchdog/child-status.ts +54 -34
  206. package/src/watchdog/diff-tool.ts +77 -0
  207. package/src/watchdog/emission-guard.ts +5 -3
  208. package/src/watchdog/guidance.ts +20 -0
  209. package/src/watchdog/permission-arbiter.ts +59 -52
  210. package/src/watchdog/register-child.ts +28 -25
  211. package/src/watchdog/register-main.ts +10 -9
  212. package/src/watchdog/render.ts +4 -5
  213. package/src/watchdog/review.ts +15 -4
  214. package/src/watchdog/rules.ts +70 -0
  215. package/src/watchdog/runtime.ts +75 -92
  216. package/src/watchdog/scope.ts +0 -11
  217. package/src/watchdog/settings.ts +48 -104
  218. package/src/watchdog/turn-delta.ts +1 -1
  219. package/src/watchdog/types.ts +18 -32
  220. package/src/watchdog/warning-format.ts +0 -1
  221. package/src/workflows/chat-progress.ts +7 -3
  222. package/src/workflows/host-command.ts +235 -0
  223. package/src/workflows/scripted-workflow.ts +1142 -69
  224. package/src/workflows/workflow-checklist.ts +439 -0
  225. package/src/workflows/workflow-child-summary.ts +121 -0
  226. package/src/workflows/workflow-preflight.ts +297 -0
  227. package/src/workflows/workflow-receipt.ts +232 -6
  228. package/src/workflows/workflow-resources.ts +150 -0
  229. package/src/workflows/workflow-settlement.ts +246 -0
  230. package/src/runs/shared/child-protocol.ts +0 -401
  231. package/src/runs/shared/pi-args.ts +0 -858
  232. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  233. package/src/runs/shared/turn-budget.ts +0 -98
  234. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -9,6 +9,7 @@ import type { AsyncStatus } from "../../shared/types.ts";
9
9
  import { MISSION_BINDING_FILE } from "../../missions/lifecycle.ts";
10
10
  import { ACTIVE_RUN_INDEX_DIR } from "./active-run-index.ts";
11
11
  import { encodeIndexSegment } from "./index-segment.ts";
12
+ import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
12
13
 
13
14
  export const ASYNC_RETENTION_DAYS = 30;
14
15
  export const ASYNC_RETENTION_BATCH_SIZE = 100;
@@ -96,11 +97,13 @@ export interface AsyncRetentionOptions {
96
97
  lstatSync?: typeof fs.lstatSync;
97
98
  signal?: AbortSignal;
98
99
  discoveryWorkerUrl?: URL;
100
+ reconcileKill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
99
101
  }
100
102
 
101
103
  export interface AsyncRetentionResult {
102
104
  acquired: boolean;
103
105
  scanned: number;
106
+ repairedRuns: number;
104
107
  deletedRuns: number;
105
108
  deletedResults: number;
106
109
  reapedTombstones: number;
@@ -135,7 +138,7 @@ function listDir(dir: string): fs.Dirent[] {
135
138
 
136
139
  function readJson(filePath: string): Record<string, unknown> | undefined {
137
140
  try {
138
- const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
141
+ const parsed = JSON.parse(fs.readFileSync(filePath).toString("utf8")) as unknown;
139
142
  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : undefined;
140
143
  } catch {
141
144
  return undefined;
@@ -320,7 +323,7 @@ function readCursor(root: string): RetentionCursor {
320
323
  function processStartIdentity(pid: number): string | undefined {
321
324
  if (process.platform === "linux") {
322
325
  try {
323
- const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
326
+ const stat = fs.readFileSync(`/proc/${pid}/stat`).toString("utf8");
324
327
  const commandEnd = stat.lastIndexOf(")");
325
328
  if (commandEnd === -1) return undefined;
326
329
  const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
@@ -504,6 +507,7 @@ function appendMaintenanceLog(root: string, result: AsyncRetentionResult, now: n
504
507
  at: new Date(now).toISOString(),
505
508
  acquired: result.acquired,
506
509
  scanned: result.scanned,
510
+ repairedRuns: result.repairedRuns,
507
511
  deletedRuns: result.deletedRuns,
508
512
  deletedResults: result.deletedResults,
509
513
  reapedTombstones: result.reapedTombstones,
@@ -600,7 +604,7 @@ function runRetentionDiscovery(input: {
600
604
  };
601
605
  const onAbort = (): void => fail(new RetentionCancelledError("Retention discovery was cancelled."));
602
606
  input.signal?.addEventListener("abort", onAbort, { once: true });
603
- worker.once("error", (error) => fail(error));
607
+ worker.once("error", (error) => fail(error instanceof Error ? error : new Error(String(error))));
604
608
  worker.once("exit", (code) => {
605
609
  if (!settled) fail(new Error(`Retention discovery worker exited before replying (${code}).`));
606
610
  });
@@ -654,6 +658,7 @@ export async function cleanupAsyncRetention(options: AsyncRetentionOptions): Pro
654
658
  const result: AsyncRetentionResult = {
655
659
  acquired: false,
656
660
  scanned: 0,
661
+ repairedRuns: 0,
657
662
  deletedRuns: 0,
658
663
  deletedResults: 0,
659
664
  reapedTombstones: 0,
@@ -750,7 +755,19 @@ export async function cleanupAsyncRetention(options: AsyncRetentionOptions): Pro
750
755
  increment(result.skipped, "unsafe-run-path");
751
756
  continue;
752
757
  }
753
- const status = readStatus(runDir);
758
+ let status = readStatus(runDir);
759
+ if (status?.state === "running"
760
+ && validRunId(status.runId)
761
+ && path.basename(runDir) === status.runId
762
+ && !protectedRunIds.has(status.runId)) {
763
+ const reconciliation = reconcileAsyncRun(runDir, {
764
+ resultsDir: options.resultsDir,
765
+ kill: options.reconcileKill,
766
+ now,
767
+ });
768
+ status = reconciliation.status ?? undefined;
769
+ if (reconciliation.repaired) result.repairedRuns += 1;
770
+ }
754
771
  const initialReason = runSkipReason({ runDir, status, asyncDirRoot: options.asyncDirRoot, resultsDir: options.resultsDir, cutoff, protectedRunIds, waitRunIds: waitReferences.runIds });
755
772
  if (initialReason) {
756
773
  increment(result.skipped, initialReason);
@@ -1,268 +1,30 @@
1
- import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-text.ts";
2
- import type { AsyncJobState, AsyncJobStep, NestedRunSummary, NestedStepSummary, SubagentRunMode, SubagentState } from "../../shared/types.ts";
1
+ import type { AsyncJobState, SubagentState } from "../../shared/types.ts";
2
+ import {
3
+ projectAsyncStatusSnapshot,
4
+ type AsyncStatusSnapshotOptions,
5
+ type AsyncStatusSnapshotV1,
6
+ } from "../shared/async-status-projection.ts";
7
+
8
+ export {
9
+ ASYNC_STATUS_SNAPSHOT_KIND,
10
+ ASYNC_STATUS_SNAPSHOT_VERSION,
11
+ } from "../shared/async-status-projection.ts";
12
+ export type {
13
+ AsyncStatusSnapshotActivityV1,
14
+ AsyncStatusSnapshotCapsV1,
15
+ AsyncStatusSnapshotHostStepV1,
16
+ AsyncStatusSnapshotKind,
17
+ AsyncStatusSnapshotNodeV1,
18
+ AsyncStatusSnapshotOmittedV1,
19
+ AsyncStatusSnapshotOptions,
20
+ AsyncStatusSnapshotState,
21
+ AsyncStatusSnapshotV1,
22
+ } from "../shared/async-status-projection.ts";
3
23
 
4
- export const ASYNC_STATUS_SNAPSHOT_KIND = "pi-subagents.async-status-snapshot";
5
- export const ASYNC_STATUS_SNAPSHOT_VERSION = 1;
6
24
  export const ASYNC_STATUS_SNAPSHOT_WIDGET_PREFIX = "PI_SUBAGENT_ASYNC_JSON:";
7
25
 
8
- const DEFAULT_MAX_RUNS = 20;
9
- const DEFAULT_MAX_CHILDREN_PER_NODE = 8;
10
- const DEFAULT_MAX_DEPTH = 3;
11
- const DEFAULT_MAX_STRING_LENGTH = 160;
12
- const DEFAULT_MAX_SERIALIZED_BYTES = 32 * 1024;
13
-
14
- export type AsyncStatusSnapshotState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
15
- export type AsyncStatusSnapshotKind = "subagent" | "workflow" | "step";
16
-
17
- export interface AsyncStatusSnapshotActivityV1 {
18
- state?: string;
19
- currentTool?: string;
20
- lastActivityAt?: number;
21
- currentToolStartedAt?: number;
22
- turnCount?: number;
23
- toolCount?: number;
24
- }
25
-
26
- export interface AsyncStatusSnapshotNodeV1 {
27
- id: string;
28
- kind: AsyncStatusSnapshotKind;
29
- label: string;
30
- state: AsyncStatusSnapshotState;
31
- startedAt?: number;
32
- updatedAt?: number;
33
- endedAt?: number;
34
- activity?: AsyncStatusSnapshotActivityV1;
35
- children?: AsyncStatusSnapshotNodeV1[];
36
- }
37
-
38
- export interface AsyncStatusSnapshotCapsV1 {
39
- maxRuns: number;
40
- maxChildrenPerNode: number;
41
- maxDepth: number;
42
- maxStringLength: number;
43
- maxSerializedBytes: number;
44
- }
45
-
46
- export interface AsyncStatusSnapshotOmittedV1 {
47
- runs: number;
48
- children: number;
49
- byteLimitExceeded: boolean;
50
- }
51
-
52
- export interface AsyncStatusSnapshotV1 {
53
- kind: typeof ASYNC_STATUS_SNAPSHOT_KIND;
54
- version: typeof ASYNC_STATUS_SNAPSHOT_VERSION;
55
- generatedAt: number;
56
- caps: AsyncStatusSnapshotCapsV1;
57
- omitted: AsyncStatusSnapshotOmittedV1;
58
- runs: AsyncStatusSnapshotNodeV1[];
59
- }
60
-
61
- export interface AsyncStatusSnapshotOptions {
62
- generatedAt?: number;
63
- maxRuns?: number;
64
- maxChildrenPerNode?: number;
65
- maxDepth?: number;
66
- maxStringLength?: number;
67
- maxSerializedBytes?: number;
68
- }
69
-
70
- interface BuildContext {
71
- caps: AsyncStatusSnapshotCapsV1;
72
- omitted: AsyncStatusSnapshotOmittedV1;
73
- }
74
-
75
- function resolveCaps(options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotCapsV1 {
76
- return {
77
- maxRuns: Math.max(0, Math.floor(options.maxRuns ?? DEFAULT_MAX_RUNS)),
78
- maxChildrenPerNode: Math.max(0, Math.floor(options.maxChildrenPerNode ?? DEFAULT_MAX_CHILDREN_PER_NODE)),
79
- maxDepth: Math.max(0, Math.floor(options.maxDepth ?? DEFAULT_MAX_DEPTH)),
80
- maxStringLength: Math.max(0, Math.floor(options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH)),
81
- maxSerializedBytes: Math.max(256, Math.floor(options.maxSerializedBytes ?? DEFAULT_MAX_SERIALIZED_BYTES)),
82
- };
83
- }
84
-
85
- function publicText(value: unknown, fallback: string, maxLength: number): string {
86
- if (typeof value !== "string") return fallback;
87
- const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
88
- return truncateDisplayText(normalized || fallback, maxLength);
89
- }
90
-
91
- function publicOptionalText(value: unknown, maxLength: number): string | undefined {
92
- if (typeof value !== "string") return undefined;
93
- const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
94
- return normalized ? truncateDisplayText(normalized, maxLength) : undefined;
95
- }
96
-
97
- function publicTime(value: unknown): number | undefined {
98
- return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
99
- }
100
-
101
- function publicCount(value: unknown): number | undefined {
102
- return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
103
- }
104
-
105
- function normalizeState(value: string): AsyncStatusSnapshotState {
106
- if (value === "completed") return "complete";
107
- if (value === "pending") return "queued";
108
- return value as AsyncStatusSnapshotState;
109
- }
110
-
111
- function terminalState(state: AsyncStatusSnapshotState): boolean {
112
- return state === "complete" || state === "failed" || state === "paused" || state === "stopped" || state === "rejected";
113
- }
114
-
115
- function kindForMode(mode: SubagentRunMode | undefined): AsyncStatusSnapshotKind {
116
- return mode === "workflow" ? "workflow" : "subagent";
117
- }
118
-
119
- function labelForAgents(agents: readonly string[] | undefined, fallback: string, maxLength: number): string {
120
- if (!agents?.length) return publicText(fallback, fallback, maxLength);
121
- const visible = agents.slice(0, 3).map((agent) => publicText(agent, "agent", maxLength)).join(", ");
122
- const suffix = agents.length > 3 ? `, +${agents.length - 3} more` : "";
123
- return truncateDisplayText(`${visible}${suffix}`, maxLength);
124
- }
125
-
126
- function activityFor(source: {
127
- activityState?: unknown;
128
- currentTool?: unknown;
129
- lastActivityAt?: unknown;
130
- currentToolStartedAt?: unknown;
131
- turnCount?: unknown;
132
- toolCount?: unknown;
133
- }, ctx: BuildContext): AsyncStatusSnapshotActivityV1 | undefined {
134
- const activity: AsyncStatusSnapshotActivityV1 = {
135
- ...(typeof source.activityState === "string" ? { state: publicText(source.activityState, "unknown", ctx.caps.maxStringLength) } : {}),
136
- ...(publicOptionalText(source.currentTool, ctx.caps.maxStringLength) ? { currentTool: publicOptionalText(source.currentTool, ctx.caps.maxStringLength) } : {}),
137
- ...(publicTime(source.lastActivityAt) !== undefined ? { lastActivityAt: publicTime(source.lastActivityAt) } : {}),
138
- ...(publicTime(source.currentToolStartedAt) !== undefined ? { currentToolStartedAt: publicTime(source.currentToolStartedAt) } : {}),
139
- ...(publicCount(source.turnCount) !== undefined ? { turnCount: publicCount(source.turnCount) } : {}),
140
- ...(publicCount(source.toolCount) !== undefined ? { toolCount: publicCount(source.toolCount) } : {}),
141
- };
142
- return Object.keys(activity).length ? activity : undefined;
143
- }
144
-
145
- function appendBoundedChildren(children: AsyncStatusSnapshotNodeV1[], source: readonly AsyncStatusSnapshotNodeV1[], ctx: BuildContext): void {
146
- const remaining = Math.max(0, ctx.caps.maxChildrenPerNode - children.length);
147
- children.push(...source.slice(0, remaining));
148
- ctx.omitted.children += Math.max(0, source.length - remaining);
149
- }
150
-
151
- function buildStepNode(step: AsyncJobStep | NestedStepSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
152
- const state = normalizeState(step.status);
153
- const updatedAt = publicTime(step.endedAt) ?? publicTime(step.lastActivityAt) ?? publicTime(step.startedAt);
154
- const node: AsyncStatusSnapshotNodeV1 = {
155
- id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
156
- kind: "step",
157
- label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
158
- state,
159
- ...(publicTime(step.startedAt) !== undefined ? { startedAt: publicTime(step.startedAt) } : {}),
160
- ...(updatedAt !== undefined ? { updatedAt } : {}),
161
- ...(terminalState(state) && publicTime(step.endedAt) !== undefined ? { endedAt: publicTime(step.endedAt) } : {}),
162
- ...(activityFor(step, ctx) ? { activity: activityFor(step, ctx) } : {}),
163
- };
164
- if (depth < ctx.caps.maxDepth && step.children?.length) {
165
- const nested = step.children.map((child, childIndex) => buildNestedNode(child, childIndex, depth + 1, ctx));
166
- const bounded: AsyncStatusSnapshotNodeV1[] = [];
167
- appendBoundedChildren(bounded, nested, ctx);
168
- if (bounded.length) node.children = bounded;
169
- } else if (step.children?.length) {
170
- ctx.omitted.children += step.children.length;
171
- }
172
- return node;
173
- }
174
-
175
- function buildNestedNode(child: NestedRunSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
176
- const state = normalizeState(child.state);
177
- const updatedAt = publicTime(child.lastUpdate) ?? publicTime(child.endedAt) ?? publicTime(child.lastActivityAt) ?? publicTime(child.startedAt);
178
- const node: AsyncStatusSnapshotNodeV1 = {
179
- id: publicText(child.id, `nested:${index}`, ctx.caps.maxStringLength),
180
- kind: kindForMode(child.mode),
181
- label: child.agent ? publicText(child.agent, "subagent", ctx.caps.maxStringLength) : labelForAgents(child.agents, child.mode ?? "subagent", ctx.caps.maxStringLength),
182
- state,
183
- ...(publicTime(child.startedAt) !== undefined ? { startedAt: publicTime(child.startedAt) } : {}),
184
- ...(updatedAt !== undefined ? { updatedAt } : {}),
185
- ...(terminalState(state) && publicTime(child.endedAt) !== undefined ? { endedAt: publicTime(child.endedAt) } : {}),
186
- ...(activityFor(child, ctx) ? { activity: activityFor(child, ctx) } : {}),
187
- };
188
- if (depth < ctx.caps.maxDepth) {
189
- const nestedSteps = child.steps?.map((step, stepIndex) => buildStepNode(step, stepIndex, depth + 1, ctx)) ?? [];
190
- const nestedChildren = child.children?.map((nested, childIndex) => buildNestedNode(nested, childIndex, depth + 1, ctx)) ?? [];
191
- const bounded: AsyncStatusSnapshotNodeV1[] = [];
192
- appendBoundedChildren(bounded, [...nestedSteps, ...nestedChildren], ctx);
193
- if (bounded.length) node.children = bounded;
194
- } else {
195
- ctx.omitted.children += (child.steps?.length ?? 0) + (child.children?.length ?? 0);
196
- }
197
- return node;
198
- }
199
-
200
- function buildRunNode(job: AsyncJobState, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
201
- const state = normalizeState(job.status);
202
- const updatedAt = publicTime(job.updatedAt) ?? publicTime(job.startedAt);
203
- const node: AsyncStatusSnapshotNodeV1 = {
204
- id: publicText(job.asyncId, "async", ctx.caps.maxStringLength),
205
- kind: kindForMode(job.mode),
206
- label: labelForAgents(job.agents, job.mode ?? "subagent", ctx.caps.maxStringLength),
207
- state,
208
- ...(publicTime(job.startedAt) !== undefined ? { startedAt: publicTime(job.startedAt) } : {}),
209
- ...(updatedAt !== undefined ? { updatedAt } : {}),
210
- ...(terminalState(state) && updatedAt !== undefined ? { endedAt: updatedAt } : {}),
211
- ...(activityFor(job, ctx) ? { activity: activityFor(job, ctx) } : {}),
212
- };
213
- if (ctx.caps.maxDepth > 0) {
214
- const stepChildren = job.steps?.map((step, index) => buildStepNode(step, step.index ?? index, 1, ctx)) ?? [];
215
- const nestedChildren = job.nestedChildren?.map((child, index) => buildNestedNode(child, index, 1, ctx)) ?? [];
216
- const bounded: AsyncStatusSnapshotNodeV1[] = [];
217
- appendBoundedChildren(bounded, [...stepChildren, ...nestedChildren], ctx);
218
- if (bounded.length) node.children = bounded;
219
- } else {
220
- ctx.omitted.children += (job.steps?.length ?? 0) + (job.nestedChildren?.length ?? 0);
221
- }
222
- return node;
223
- }
224
-
225
- function snapshotBytes(snapshot: AsyncStatusSnapshotV1): number {
226
- return Buffer.byteLength(JSON.stringify(snapshot), "utf8");
227
- }
228
-
229
- function enforceByteLimit(snapshot: AsyncStatusSnapshotV1): void {
230
- if (snapshotBytes(snapshot) <= snapshot.caps.maxSerializedBytes) return;
231
- snapshot.omitted.byteLimitExceeded = true;
232
- const runs = snapshot.runs;
233
- const initialOmittedRuns = snapshot.omitted.runs;
234
- let lower = 0;
235
- let upper = Math.max(0, runs.length - 1);
236
- while (lower < upper) {
237
- const retained = Math.ceil((lower + upper) / 2);
238
- snapshot.runs = runs.slice(0, retained);
239
- snapshot.omitted.runs = initialOmittedRuns + runs.length - retained;
240
- if (snapshotBytes(snapshot) <= snapshot.caps.maxSerializedBytes) lower = retained;
241
- else upper = retained - 1;
242
- }
243
- snapshot.runs = runs.slice(0, lower);
244
- snapshot.omitted.runs = initialOmittedRuns + runs.length - lower;
245
- }
246
-
247
26
  export function buildAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
248
- const caps = resolveCaps(options);
249
- const ctx: BuildContext = { caps, omitted: { runs: 0, children: 0, byteLimitExceeded: false } };
250
- const sorted = [...jobs].sort((left, right) => {
251
- const leftUpdated = left.updatedAt ?? left.startedAt ?? 0;
252
- const rightUpdated = right.updatedAt ?? right.startedAt ?? 0;
253
- return rightUpdated - leftUpdated || left.asyncId.localeCompare(right.asyncId);
254
- });
255
- ctx.omitted.runs += Math.max(0, sorted.length - caps.maxRuns);
256
- const snapshot: AsyncStatusSnapshotV1 = {
257
- kind: ASYNC_STATUS_SNAPSHOT_KIND,
258
- version: ASYNC_STATUS_SNAPSHOT_VERSION,
259
- generatedAt: options.generatedAt ?? Date.now(),
260
- caps,
261
- omitted: ctx.omitted,
262
- runs: sorted.slice(0, caps.maxRuns).map((job) => buildRunNode(job, ctx)),
263
- };
264
- enforceByteLimit(snapshot);
265
- return snapshot;
27
+ return projectAsyncStatusSnapshot(jobs, options);
266
28
  }
267
29
 
268
30
  export function asyncStatusSnapshotJobsForState(state: SubagentState | undefined, sessionId: string | null | undefined): AsyncJobState[] {