@xzzpig/pi-subagents 0.8.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 (218) hide show
  1. package/CHANGELOG.md +443 -0
  2. package/README.md +2 -2
  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 +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +151 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +5 -4
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +370 -114
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +12 -2
  35. package/src/agents/agents.ts +919 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +31 -20
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +48 -18
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +57 -21
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +2 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +366 -128
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +45 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +189 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +676 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +468 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1172 -400
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +314 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +342 -0
  115. package/src/runs/shared/child-tool-plan.ts +540 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +142 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +38 -48
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +15 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/single-output.ts +89 -22
  149. package/src/runs/shared/structured-output.ts +49 -9
  150. package/src/runs/shared/subagent-control.ts +6 -2
  151. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  152. package/src/runs/shared/task-intent.ts +21 -7
  153. package/src/runs/shared/tool-availability.ts +18 -62
  154. package/src/runs/shared/tool-budget.ts +0 -14
  155. package/src/runs/shared/tool-timeout.ts +1 -1
  156. package/src/runs/shared/workflow-graph.ts +16 -0
  157. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  158. package/src/runs/shared/worktree.ts +571 -62
  159. package/src/shared/atomic-json.ts +3 -1
  160. package/src/shared/child-session-name.ts +46 -0
  161. package/src/shared/extension-context.ts +24 -0
  162. package/src/shared/fork-context.ts +21 -12
  163. package/src/shared/fork-session-cwd.ts +27 -0
  164. package/src/shared/formatters.ts +18 -3
  165. package/src/shared/jsonl-writer.ts +11 -0
  166. package/src/shared/launch-contract.ts +8 -1
  167. package/src/shared/pruned-fork.ts +450 -0
  168. package/src/shared/session-file-trust.ts +19 -0
  169. package/src/shared/session-tokens.ts +14 -3
  170. package/src/shared/settings.ts +19 -105
  171. package/src/shared/shortcuts.ts +17 -0
  172. package/src/shared/thinking-ceiling.ts +0 -6
  173. package/src/shared/types.ts +524 -70
  174. package/src/shared/utils.ts +60 -93
  175. package/src/shared/workflow-child-permit.ts +207 -0
  176. package/src/slash/delegation-adapters.ts +1 -9
  177. package/src/slash/delegation-request.ts +0 -4
  178. package/src/slash/prompt-template-bridge.ts +37 -1
  179. package/src/slash/slash-bridge.ts +1 -2
  180. package/src/slash/slash-commands.ts +383 -116
  181. package/src/slash/slash-live-state.ts +22 -11
  182. package/src/slash/subagents-admin.ts +29 -12
  183. package/src/tui/fleet-native-transcript.ts +4 -0
  184. package/src/tui/fleet-status.ts +217 -82
  185. package/src/tui/fleet-transcript.ts +11 -5
  186. package/src/tui/fleet.ts +54 -28
  187. package/src/tui/render-helpers.ts +31 -0
  188. package/src/tui/render.ts +1429 -163
  189. package/src/watchdog/change-signature.ts +40 -1
  190. package/src/watchdog/child-status.ts +54 -34
  191. package/src/watchdog/diff-tool.ts +77 -0
  192. package/src/watchdog/emission-guard.ts +5 -3
  193. package/src/watchdog/guidance.ts +20 -0
  194. package/src/watchdog/register-child.ts +28 -25
  195. package/src/watchdog/register-main.ts +10 -9
  196. package/src/watchdog/render.ts +4 -5
  197. package/src/watchdog/review.ts +15 -4
  198. package/src/watchdog/rules.ts +70 -0
  199. package/src/watchdog/runtime.ts +75 -92
  200. package/src/watchdog/scope.ts +0 -11
  201. package/src/watchdog/settings.ts +48 -104
  202. package/src/watchdog/turn-delta.ts +1 -1
  203. package/src/watchdog/types.ts +18 -32
  204. package/src/watchdog/warning-format.ts +0 -1
  205. package/src/workflows/chat-progress.ts +7 -3
  206. package/src/workflows/host-command.ts +235 -0
  207. package/src/workflows/scripted-workflow.ts +988 -59
  208. package/src/workflows/workflow-checklist.ts +439 -0
  209. package/src/workflows/workflow-child-summary.ts +121 -0
  210. package/src/workflows/workflow-preflight.ts +297 -0
  211. package/src/workflows/workflow-receipt.ts +232 -6
  212. package/src/workflows/workflow-resources.ts +150 -0
  213. package/src/workflows/workflow-settlement.ts +246 -0
  214. package/src/runs/shared/child-protocol.ts +0 -401
  215. package/src/runs/shared/pi-args.ts +0 -935
  216. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  217. package/src/runs/shared/turn-budget.ts +0 -98
  218. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -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[] {