@xzzpig/pi-subagents 0.1.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.
- package/CHANGELOG.md +1621 -0
- package/LICENSE +21 -0
- package/README.md +118 -0
- package/agents/delegate.md +14 -0
- package/agents/oracle.md +74 -0
- package/agents/researcher.md +52 -0
- package/agents/reviewer.md +79 -0
- package/agents/scout.md +50 -0
- package/agents/worker.md +58 -0
- package/index.ts +1 -0
- package/inspector-runner.mjs +11 -0
- package/install.mjs +93 -0
- package/package.json +105 -0
- package/prompts/gather-context-and-clarify.md +13 -0
- package/prompts/parallel-cleanup.md +59 -0
- package/prompts/parallel-research.md +50 -0
- package/prompts/parallel-review.md +54 -0
- package/prompts/review-loop.md +43 -0
- package/skills/pi-subagents/SKILL.md +41 -0
- package/skills/pi-subagents/references/constraints-and-recipes.md +251 -0
- package/skills/pi-subagents/references/execution-controls.md +428 -0
- package/skills/pi-subagents/references/management-authoring-rpc.md +161 -0
- package/skills/pi-subagents/references/prompting-and-roles.md +242 -0
- package/src/agents/agent-management.ts +1256 -0
- package/src/agents/agent-memory.ts +254 -0
- package/src/agents/agent-refinements.ts +624 -0
- package/src/agents/agent-scope.ts +6 -0
- package/src/agents/agent-selection.ts +25 -0
- package/src/agents/agent-serializer.ts +163 -0
- package/src/agents/agents.ts +1889 -0
- package/src/agents/chain-serializer.ts +280 -0
- package/src/agents/frontmatter.ts +149 -0
- package/src/agents/identity.ts +30 -0
- package/src/agents/proactive-skills.ts +194 -0
- package/src/agents/skills.ts +761 -0
- package/src/api/background-work.ts +197 -0
- package/src/api/capability-ceiling.ts +17 -0
- package/src/api/control-channel.ts +4 -0
- package/src/api/delegation.ts +119 -0
- package/src/api/external-runs.ts +129 -0
- package/src/api/intercom-bridge.ts +3 -0
- package/src/api/pi-args.ts +5 -0
- package/src/api/preflight.ts +403 -0
- package/src/api/shared-types.ts +19 -0
- package/src/extension/config.ts +76 -0
- package/src/extension/control-notices.ts +58 -0
- package/src/extension/doctor.ts +230 -0
- package/src/extension/fanout-child.ts +201 -0
- package/src/extension/index.ts +805 -0
- package/src/extension/public-execution.ts +71 -0
- package/src/extension/rpc.ts +653 -0
- package/src/extension/schemas.ts +375 -0
- package/src/extension/steering-notices.ts +35 -0
- package/src/extension/tool-description.ts +164 -0
- package/src/inspectors/herdr/actions.ts +229 -0
- package/src/inspectors/herdr/client.ts +130 -0
- package/src/inspectors/herdr/inspector-runner.ts +141 -0
- package/src/inspectors/herdr/project-panes.ts +154 -0
- package/src/integrations/herdr-status.ts +330 -0
- package/src/intercom/intercom-bridge.ts +187 -0
- package/src/intercom/native-supervisor-channel.ts +715 -0
- package/src/intercom/result-intercom.ts +421 -0
- package/src/missions/actions.ts +410 -0
- package/src/missions/goal-driver.ts +162 -0
- package/src/missions/lifecycle.ts +346 -0
- package/src/missions/store.ts +507 -0
- package/src/missions/types.ts +157 -0
- package/src/missions/workflow-state.ts +250 -0
- package/src/policy/authority.ts +46 -0
- package/src/profiles/profiles.ts +661 -0
- package/src/runs/background/async-execution.ts +1574 -0
- package/src/runs/background/async-job-tracker.ts +511 -0
- package/src/runs/background/async-resume.ts +539 -0
- package/src/runs/background/async-status.ts +542 -0
- package/src/runs/background/auto-drain.ts +67 -0
- package/src/runs/background/chain-append.ts +328 -0
- package/src/runs/background/chain-root-attachment.ts +199 -0
- package/src/runs/background/completion-batcher.ts +168 -0
- package/src/runs/background/completion-dedupe.ts +54 -0
- package/src/runs/background/control-channel.ts +692 -0
- package/src/runs/background/fleet-view.ts +540 -0
- package/src/runs/background/notify.ts +332 -0
- package/src/runs/background/parallel-groups.ts +45 -0
- package/src/runs/background/process-terminal.ts +280 -0
- package/src/runs/background/result-watcher.ts +414 -0
- package/src/runs/background/retained-children.ts +68 -0
- package/src/runs/background/run-id-resolver.ts +167 -0
- package/src/runs/background/run-status.ts +504 -0
- package/src/runs/background/scheduled-runs.ts +753 -0
- package/src/runs/background/stale-run-reconciler.ts +396 -0
- package/src/runs/background/steering.ts +239 -0
- package/src/runs/background/subagent-runner.ts +4718 -0
- package/src/runs/background/subagent-wait.ts +661 -0
- package/src/runs/background/top-level-async.ts +14 -0
- package/src/runs/background/wait-completions.ts +112 -0
- package/src/runs/background/wait-config.ts +36 -0
- package/src/runs/background/wait-subscriptions.ts +253 -0
- package/src/runs/background/wait-tool.ts +34 -0
- package/src/runs/foreground/async-steering-action.ts +256 -0
- package/src/runs/foreground/async-stop-action.ts +65 -0
- package/src/runs/foreground/chain-clarify.ts +1354 -0
- package/src/runs/foreground/chain-execution.ts +1527 -0
- package/src/runs/foreground/execution.ts +1868 -0
- package/src/runs/foreground/foreground-control.ts +132 -0
- package/src/runs/foreground/subagent-executor.ts +5532 -0
- package/src/runs/shared/acceptance.ts +1365 -0
- package/src/runs/shared/agent-contract.ts +38 -0
- package/src/runs/shared/capability-ceiling.ts +209 -0
- package/src/runs/shared/chain-outputs.ts +118 -0
- package/src/runs/shared/child-protocol.ts +401 -0
- package/src/runs/shared/completion-guard.ts +95 -0
- package/src/runs/shared/context-mode.ts +44 -0
- package/src/runs/shared/dynamic-fanout.ts +297 -0
- package/src/runs/shared/external-cli-runner.ts +130 -0
- package/src/runs/shared/long-running-guard.ts +220 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +406 -0
- package/src/runs/shared/model-fallback.ts +336 -0
- package/src/runs/shared/model-scope.ts +128 -0
- package/src/runs/shared/nested-events.ts +1076 -0
- package/src/runs/shared/nested-path.ts +52 -0
- package/src/runs/shared/nested-render.ts +123 -0
- package/src/runs/shared/parallel-handoff.ts +238 -0
- package/src/runs/shared/parallel-utils.ts +256 -0
- package/src/runs/shared/permissions.ts +95 -0
- package/src/runs/shared/pi-args.ts +808 -0
- package/src/runs/shared/pi-spawn.ts +163 -0
- package/src/runs/shared/process-signal.ts +19 -0
- package/src/runs/shared/run-history.ts +181 -0
- package/src/runs/shared/runtime-acknowledged-extensions.ts +71 -0
- package/src/runs/shared/session-lease.ts +299 -0
- package/src/runs/shared/single-output.ts +235 -0
- package/src/runs/shared/spawn-budget.ts +128 -0
- package/src/runs/shared/structured-output.ts +182 -0
- package/src/runs/shared/subagent-control.ts +231 -0
- package/src/runs/shared/subagent-prompt-runtime.ts +588 -0
- package/src/runs/shared/subagent-startup-retry.ts +104 -0
- package/src/runs/shared/task-intent.ts +181 -0
- package/src/runs/shared/tool-availability.ts +83 -0
- package/src/runs/shared/tool-budget.ts +80 -0
- package/src/runs/shared/turn-budget.ts +98 -0
- package/src/runs/shared/usage-budget.ts +65 -0
- package/src/runs/shared/workflow-graph.ts +231 -0
- package/src/runs/shared/worktree.ts +759 -0
- package/src/shared/accessible-dir.ts +47 -0
- package/src/shared/artifacts.ts +285 -0
- package/src/shared/atomic-json.ts +61 -0
- package/src/shared/child-transcript.ts +264 -0
- package/src/shared/file-coalescer.ts +40 -0
- package/src/shared/file-system-retry.ts +47 -0
- package/src/shared/fork-context.ts +213 -0
- package/src/shared/formatters.ts +133 -0
- package/src/shared/jsonl-writer.ts +81 -0
- package/src/shared/launch-contract.ts +124 -0
- package/src/shared/model-info.ts +81 -0
- package/src/shared/post-exit-stdio-guard.ts +85 -0
- package/src/shared/session-identity.ts +10 -0
- package/src/shared/session-tokens.ts +44 -0
- package/src/shared/settings.ts +501 -0
- package/src/shared/status-format.ts +55 -0
- package/src/shared/types.ts +2069 -0
- package/src/shared/utils.ts +613 -0
- package/src/slash/delegation-adapters.ts +434 -0
- package/src/slash/delegation-json.ts +108 -0
- package/src/slash/delegation-request.ts +166 -0
- package/src/slash/prompt-template-bridge.ts +383 -0
- package/src/slash/prompt-workflows.ts +300 -0
- package/src/slash/selector.ts +147 -0
- package/src/slash/slash-bridge.ts +192 -0
- package/src/slash/slash-commands.ts +994 -0
- package/src/slash/slash-live-state.ts +296 -0
- package/src/slash/subagents-admin.ts +432 -0
- package/src/tui/fleet-status.ts +564 -0
- package/src/tui/fleet-transcript.ts +577 -0
- package/src/tui/fleet.ts +879 -0
- package/src/tui/render-helpers.ts +80 -0
- package/src/tui/render.ts +2029 -0
- package/src/types/pi-runtime-compat.d.ts +8 -0
- package/src/watchdog/change-signature.ts +220 -0
- package/src/watchdog/child-status.ts +205 -0
- package/src/watchdog/emission-guard.ts +123 -0
- package/src/watchdog/lsp-diagnostics.ts +537 -0
- package/src/watchdog/model-selection.ts +167 -0
- package/src/watchdog/permission-arbiter.ts +145 -0
- package/src/watchdog/register-child.ts +117 -0
- package/src/watchdog/register-main.ts +440 -0
- package/src/watchdog/render.ts +54 -0
- package/src/watchdog/review.ts +302 -0
- package/src/watchdog/runtime.ts +868 -0
- package/src/watchdog/scope.ts +62 -0
- package/src/watchdog/settings.ts +568 -0
- package/src/watchdog/tool-actions.ts +155 -0
- package/src/watchdog/turn-delta.ts +161 -0
- package/src/watchdog/types.ts +198 -0
- package/src/watchdog/warning-format.ts +73 -0
- package/src/workflows/chat-progress.ts +140 -0
- package/src/workflows/scripted-workflow.ts +506 -0
|
@@ -0,0 +1,2069 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Type definitions for the subagent extension
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
import * as os from "node:os";
|
|
6
|
+
import * as path from "node:path";
|
|
7
|
+
import type { Message } from "@earendil-works/pi-ai";
|
|
8
|
+
import type { AgentConfig } from "../agents/agents.ts";
|
|
9
|
+
import type { FSWatcher } from "node:fs";
|
|
10
|
+
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
11
|
+
import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
|
|
12
|
+
import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
|
|
13
|
+
import type { AuthorityPolicyConfig } from "../policy/authority.ts";
|
|
14
|
+
import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
|
|
15
|
+
|
|
16
|
+
// ============================================================================
|
|
17
|
+
// Basic Types
|
|
18
|
+
// ============================================================================
|
|
19
|
+
|
|
20
|
+
export interface MaxOutputConfig {
|
|
21
|
+
bytes?: number;
|
|
22
|
+
lines?: number;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export type OutputMode = "inline" | "file-only";
|
|
26
|
+
|
|
27
|
+
export type AcceptanceRole = "read-only" | "writer";
|
|
28
|
+
|
|
29
|
+
export type JsonSchemaObject = Record<string, unknown>;
|
|
30
|
+
|
|
31
|
+
export interface ChainOutputMapEntry {
|
|
32
|
+
text: string;
|
|
33
|
+
structured?: unknown;
|
|
34
|
+
agent: string;
|
|
35
|
+
stepIndex: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
|
|
39
|
+
|
|
40
|
+
export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "stopped" | "detached" | "rejected";
|
|
41
|
+
|
|
42
|
+
export interface WorkflowGraphNode {
|
|
43
|
+
id: string;
|
|
44
|
+
kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent" | "checkpoint";
|
|
45
|
+
agent?: string;
|
|
46
|
+
phase?: string;
|
|
47
|
+
label: string;
|
|
48
|
+
status: WorkflowNodeStatus;
|
|
49
|
+
flatIndex?: number;
|
|
50
|
+
stepIndex?: number;
|
|
51
|
+
children?: WorkflowGraphNode[];
|
|
52
|
+
dynamic?: {
|
|
53
|
+
sourceOutput: string;
|
|
54
|
+
sourcePath: string;
|
|
55
|
+
itemName: string;
|
|
56
|
+
maxItems?: number;
|
|
57
|
+
collectAs?: string;
|
|
58
|
+
};
|
|
59
|
+
itemKey?: string;
|
|
60
|
+
outputName?: string;
|
|
61
|
+
structured?: boolean;
|
|
62
|
+
acceptanceStatus?: AcceptanceLedgerStatus;
|
|
63
|
+
error?: string;
|
|
64
|
+
checkpoint?: ChainCheckpointState;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export interface ChainCheckpointState {
|
|
68
|
+
name: string;
|
|
69
|
+
message?: string;
|
|
70
|
+
status: "pending" | "approved" | "rejected";
|
|
71
|
+
stepIndex: number;
|
|
72
|
+
approvedAt?: number;
|
|
73
|
+
rejectedAt?: number;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export interface WorkflowGraphSnapshot {
|
|
77
|
+
runId: string;
|
|
78
|
+
mode: SubagentRunMode;
|
|
79
|
+
phases: Array<{ title: string; nodeIds: string[] }>;
|
|
80
|
+
nodes: WorkflowGraphNode[];
|
|
81
|
+
currentNodeId?: string;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export interface SavedOutputReference {
|
|
85
|
+
path: string;
|
|
86
|
+
bytes: number;
|
|
87
|
+
lines: number;
|
|
88
|
+
message: string;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
interface TruncationResult {
|
|
92
|
+
text: string;
|
|
93
|
+
truncated: boolean;
|
|
94
|
+
originalBytes?: number;
|
|
95
|
+
originalLines?: number;
|
|
96
|
+
artifactPath?: string;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
export interface Usage {
|
|
100
|
+
input: number;
|
|
101
|
+
output: number;
|
|
102
|
+
cacheRead: number;
|
|
103
|
+
cacheWrite: number;
|
|
104
|
+
cost: number;
|
|
105
|
+
turns: number;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export interface TurnBudgetConfig {
|
|
109
|
+
maxTurns: number;
|
|
110
|
+
graceTurns?: number;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export interface ResolvedTurnBudget {
|
|
114
|
+
maxTurns: number;
|
|
115
|
+
graceTurns: number;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
export interface ToolBudgetConfig {
|
|
119
|
+
soft?: number;
|
|
120
|
+
hard: number;
|
|
121
|
+
block?: string[] | "*";
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
export interface ResolvedToolBudget {
|
|
125
|
+
soft?: number;
|
|
126
|
+
hard: number;
|
|
127
|
+
block: string[] | "*";
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
export type ToolBudgetOutcome = "within-budget" | "soft-reached" | "hard-blocked";
|
|
131
|
+
|
|
132
|
+
export interface ToolBudgetState extends ResolvedToolBudget {
|
|
133
|
+
outcome: ToolBudgetOutcome;
|
|
134
|
+
toolCount: number;
|
|
135
|
+
softReachedAt?: number;
|
|
136
|
+
hardReachedAt?: number;
|
|
137
|
+
blockedTool?: string;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
export type TurnBudgetOutcome = "within-budget" | "wrap-up-requested" | "termination-deferred" | "exceeded";
|
|
141
|
+
|
|
142
|
+
export interface TurnBudgetState extends ResolvedTurnBudget {
|
|
143
|
+
outcome: TurnBudgetOutcome;
|
|
144
|
+
turnCount: number;
|
|
145
|
+
wrapUpRequestedAtTurn?: number;
|
|
146
|
+
terminationDeferredAtTurn?: number;
|
|
147
|
+
exceededAtTurn?: number;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
export interface TokenUsage {
|
|
151
|
+
input: number;
|
|
152
|
+
output: number;
|
|
153
|
+
total: number;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export type ActivityState = "active_long_running" | "needs_attention";
|
|
157
|
+
export type ControlEventType = "active_long_running" | "needs_attention";
|
|
158
|
+
export type ControlNotificationChannel = "event" | "async" | "intercom";
|
|
159
|
+
|
|
160
|
+
export interface ControlConfig {
|
|
161
|
+
enabled?: boolean;
|
|
162
|
+
needsAttentionAfterMs?: number;
|
|
163
|
+
activeNoticeAfterMs?: number;
|
|
164
|
+
activeNoticeAfterTurns?: number;
|
|
165
|
+
activeNoticeAfterTokens?: number;
|
|
166
|
+
failedToolAttemptsBeforeAttention?: number;
|
|
167
|
+
notifyOn?: ControlEventType[];
|
|
168
|
+
notifyChannels?: ControlNotificationChannel[];
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
export interface ResolvedControlConfig {
|
|
172
|
+
enabled: boolean;
|
|
173
|
+
needsAttentionAfterMs: number;
|
|
174
|
+
activeNoticeAfterMs: number;
|
|
175
|
+
activeNoticeAfterTurns?: number;
|
|
176
|
+
activeNoticeAfterTokens?: number;
|
|
177
|
+
failedToolAttemptsBeforeAttention: number;
|
|
178
|
+
notifyOn: ControlEventType[];
|
|
179
|
+
notifyChannels: ControlNotificationChannel[];
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Smart completion batching for async-completion notifications. Successful
|
|
184
|
+
* sibling completions are held briefly so they arrive as one grouped message;
|
|
185
|
+
* failure and attention signals bypass grouping and always fire immediately.
|
|
186
|
+
*/
|
|
187
|
+
export interface CompletionBatchConfig {
|
|
188
|
+
enabled?: boolean;
|
|
189
|
+
/** Idle window after each arrival; resets on every new item. */
|
|
190
|
+
debounceMs?: number;
|
|
191
|
+
/** Hard cap measured from the first item in a group. */
|
|
192
|
+
maxWaitMs?: number;
|
|
193
|
+
/** Shorter idle window for straggler groups. */
|
|
194
|
+
stragglerDebounceMs?: number;
|
|
195
|
+
/** Shorter hard cap for straggler groups. */
|
|
196
|
+
stragglerMaxWaitMs?: number;
|
|
197
|
+
/** Arrivals within this window after an emit join a straggler group. */
|
|
198
|
+
stragglerWindowMs?: number;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
export interface WaitToolConfigObject {
|
|
202
|
+
enabled?: boolean;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
export type WaitToolConfig = boolean | WaitToolConfigObject;
|
|
206
|
+
|
|
207
|
+
export interface ControlEvent {
|
|
208
|
+
type: ControlEventType;
|
|
209
|
+
from?: ActivityState;
|
|
210
|
+
to: ActivityState;
|
|
211
|
+
ts: number;
|
|
212
|
+
agent: string;
|
|
213
|
+
index?: number;
|
|
214
|
+
runId: string;
|
|
215
|
+
nestedRunId?: string;
|
|
216
|
+
nestingPath?: NestedRunAddress["path"];
|
|
217
|
+
message: string;
|
|
218
|
+
reason?: "idle" | "completion_guard" | "active_long_running" | "tool_failures" | "supervisor_request" | "time_threshold" | "turn_threshold" | "token_threshold";
|
|
219
|
+
turns?: number;
|
|
220
|
+
tokens?: number;
|
|
221
|
+
toolCount?: number;
|
|
222
|
+
currentTool?: string;
|
|
223
|
+
currentToolDurationMs?: number;
|
|
224
|
+
currentPath?: string;
|
|
225
|
+
elapsedMs?: number;
|
|
226
|
+
recentFailureSummary?: string;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
|
|
230
|
+
export type SubagentOutputState = "present" | "absent" | "unknown";
|
|
231
|
+
export type SubagentRunMode = "single" | "parallel" | "chain" | "workflow";
|
|
232
|
+
export type SubagentResultMode = SubagentRunMode;
|
|
233
|
+
|
|
234
|
+
export interface ParallelHandoffPatch {
|
|
235
|
+
path: string;
|
|
236
|
+
branch: string;
|
|
237
|
+
changed: boolean;
|
|
238
|
+
diffStat: string;
|
|
239
|
+
filesChanged: number;
|
|
240
|
+
insertions: number;
|
|
241
|
+
deletions: number;
|
|
242
|
+
error?: string;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
export interface ParallelHandoffChild {
|
|
246
|
+
index: number;
|
|
247
|
+
taskIndex: number;
|
|
248
|
+
agent: string;
|
|
249
|
+
status: SubagentResultStatus;
|
|
250
|
+
summary: string;
|
|
251
|
+
outputPath?: string;
|
|
252
|
+
structuredOutput?: unknown;
|
|
253
|
+
structuredOutputPath?: string;
|
|
254
|
+
sessionPath?: string;
|
|
255
|
+
patch: ParallelHandoffPatch;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
export interface ParallelHandoffCleanupTask {
|
|
259
|
+
index: number;
|
|
260
|
+
path: string;
|
|
261
|
+
branch: string;
|
|
262
|
+
worktreeRemoved: boolean;
|
|
263
|
+
branchRemoved: boolean;
|
|
264
|
+
preserved?: boolean;
|
|
265
|
+
reason?: string;
|
|
266
|
+
errors?: string[];
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
export interface ParallelHandoffGroup {
|
|
270
|
+
stepIndex: number;
|
|
271
|
+
baseCommit: string;
|
|
272
|
+
repoRoot: string;
|
|
273
|
+
children: ParallelHandoffChild[];
|
|
274
|
+
cleanup: {
|
|
275
|
+
state: "complete" | "partial";
|
|
276
|
+
tasks: ParallelHandoffCleanupTask[];
|
|
277
|
+
pruned: boolean;
|
|
278
|
+
errors?: string[];
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
export interface ParallelHandoffManifest {
|
|
283
|
+
version: 1;
|
|
284
|
+
runId: string;
|
|
285
|
+
mode: "parallel" | "chain";
|
|
286
|
+
source: "foreground" | "async";
|
|
287
|
+
cwd: string;
|
|
288
|
+
createdAt: number;
|
|
289
|
+
updatedAt: number;
|
|
290
|
+
groups: ParallelHandoffGroup[];
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
export interface ParallelHandoffReference {
|
|
294
|
+
version: 1;
|
|
295
|
+
path: string;
|
|
296
|
+
groupCount: number;
|
|
297
|
+
childCount: number;
|
|
298
|
+
changedPatches: number;
|
|
299
|
+
cleanupState: "complete" | "partial";
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
export interface AgentContract {
|
|
303
|
+
version: 1;
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
export type ChainGateLayer = "execution" | "acceptance";
|
|
307
|
+
|
|
308
|
+
export type ExecutionProjectionStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
|
|
309
|
+
|
|
310
|
+
export interface ExecutionProjection {
|
|
311
|
+
status: ExecutionProjectionStatus;
|
|
312
|
+
success: boolean;
|
|
313
|
+
exitCode: number;
|
|
314
|
+
error?: string;
|
|
315
|
+
interrupted?: boolean;
|
|
316
|
+
timedOut?: boolean;
|
|
317
|
+
stopped?: boolean;
|
|
318
|
+
detached?: boolean;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
export interface ReviewProjection {
|
|
322
|
+
status: "not-requested" | "review-required" | "reviewed" | "blockers";
|
|
323
|
+
findings?: AcceptanceReviewResult["findings"];
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
export interface FileMutationEffect {
|
|
327
|
+
status: "not-requested" | "not-applicable" | "observed" | "missing";
|
|
328
|
+
expected: boolean;
|
|
329
|
+
attempted: boolean;
|
|
330
|
+
message?: string;
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
export interface EffectsProjection {
|
|
334
|
+
fileMutation?: FileMutationEffect;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
export const SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 3;
|
|
338
|
+
export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFACT_VERSION;
|
|
339
|
+
|
|
340
|
+
export type ProcessTerminalState = "pending" | "observed" | "unknown" | "not-started";
|
|
341
|
+
export type ProcessTerminalReason =
|
|
342
|
+
| "observer-unavailable"
|
|
343
|
+
| "runner-candidate-missing"
|
|
344
|
+
| "runner-instance-mismatch"
|
|
345
|
+
| "writer-close-unverified"
|
|
346
|
+
| "canonical-session-unavailable"
|
|
347
|
+
| "canonical-session-lease-active"
|
|
348
|
+
| "canonical-session-release-unverified"
|
|
349
|
+
| "proof-write-failed"
|
|
350
|
+
| "stale-repair";
|
|
351
|
+
|
|
352
|
+
export interface RunnerProcessInstanceExitV1 {
|
|
353
|
+
processInstanceId: string;
|
|
354
|
+
kind: "runner";
|
|
355
|
+
closeObservedAt: number;
|
|
356
|
+
exitCode: number | null;
|
|
357
|
+
signal: string | null;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
export interface PiWriterProcessInstanceExitV1 {
|
|
361
|
+
processInstanceId: string;
|
|
362
|
+
kind: "pi-writer";
|
|
363
|
+
attempt: number;
|
|
364
|
+
closeObservedAt: number;
|
|
365
|
+
exitCode: number | null;
|
|
366
|
+
signal: string | null;
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
export type ProcessInstanceExitV1 = RunnerProcessInstanceExitV1 | PiWriterProcessInstanceExitV1;
|
|
370
|
+
|
|
371
|
+
export interface CanonicalSessionTerminalV1 {
|
|
372
|
+
canonicalSessionId: string;
|
|
373
|
+
leaseDisposition: "released" | "not-held";
|
|
374
|
+
freeAtObservation: true;
|
|
375
|
+
canonicalSessionLeaseReleased?: true;
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
interface ProcessTerminalBaseV1 {
|
|
379
|
+
version: 1;
|
|
380
|
+
runId: string;
|
|
381
|
+
childIndex?: number;
|
|
382
|
+
runnerProcessInstanceId: string;
|
|
383
|
+
observedAt?: number;
|
|
384
|
+
reason?: ProcessTerminalReason;
|
|
385
|
+
resumeDisposition?: "resumable" | "non-resumable" | "unavailable";
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
export type ProcessTerminalV1 =
|
|
389
|
+
| (ProcessTerminalBaseV1 & { state: "pending" | "not-started" })
|
|
390
|
+
| (ProcessTerminalBaseV1 & {
|
|
391
|
+
state: "observed";
|
|
392
|
+
observedAt: number;
|
|
393
|
+
instances: ProcessInstanceExitV1[];
|
|
394
|
+
canonicalSession?: CanonicalSessionTerminalV1;
|
|
395
|
+
})
|
|
396
|
+
| (ProcessTerminalBaseV1 & {
|
|
397
|
+
state: "unknown";
|
|
398
|
+
reason: ProcessTerminalReason;
|
|
399
|
+
diagnostic?: string;
|
|
400
|
+
});
|
|
401
|
+
|
|
402
|
+
export type SteeringActionState = "delivered" | "scheduled" | "pending" | "partial" | "recovered" | "failed";
|
|
403
|
+
export type SteeringTargetState = "scheduled" | "pending" | "routed" | "queued" | "delivered" | "late" | "failed" | "recovered";
|
|
404
|
+
|
|
405
|
+
export interface SteeringTargetStatus {
|
|
406
|
+
index: number;
|
|
407
|
+
state: SteeringTargetState;
|
|
408
|
+
routedAt?: number;
|
|
409
|
+
deliveredAt?: number;
|
|
410
|
+
lateDeliveredAt?: number;
|
|
411
|
+
failedAt?: number;
|
|
412
|
+
recoveredAt?: number;
|
|
413
|
+
reason?: string;
|
|
414
|
+
replacementRunId?: string;
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
export interface SteeringRequestStatus {
|
|
418
|
+
id: string;
|
|
419
|
+
requestedAt: number;
|
|
420
|
+
source?: string;
|
|
421
|
+
messagePreview: string;
|
|
422
|
+
targets: SteeringTargetStatus[];
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
export interface SteeringStatus {
|
|
426
|
+
requested: number;
|
|
427
|
+
scheduled: number;
|
|
428
|
+
pending: number;
|
|
429
|
+
delivered: number;
|
|
430
|
+
failed: number;
|
|
431
|
+
recovered: number;
|
|
432
|
+
lastRequestedAt?: number;
|
|
433
|
+
lastDeliveredAt?: number;
|
|
434
|
+
recent: SteeringRequestStatus[];
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
export interface SteerActionTarget {
|
|
438
|
+
index: number;
|
|
439
|
+
state: SteeringTargetState;
|
|
440
|
+
deliveredAt?: number;
|
|
441
|
+
lateDeliveredAt?: number;
|
|
442
|
+
reason?: string;
|
|
443
|
+
replacementRunId?: string;
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
export interface SteerActionResult {
|
|
447
|
+
requestId: string;
|
|
448
|
+
state: SteeringActionState;
|
|
449
|
+
deliveryStatus: "delivered" | "queued";
|
|
450
|
+
sourceRunId: string;
|
|
451
|
+
replacementRunId?: string;
|
|
452
|
+
targets: SteerActionTarget[];
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
export interface SteeringNotice {
|
|
456
|
+
type: "subagent.steering.notice";
|
|
457
|
+
ts: number;
|
|
458
|
+
runId: string;
|
|
459
|
+
requestId: string;
|
|
460
|
+
state: "failed" | "partial" | "recovered";
|
|
461
|
+
message: string;
|
|
462
|
+
currentSessionId?: string;
|
|
463
|
+
}
|
|
464
|
+
|
|
465
|
+
export interface SteeringRecoveryDescriptor {
|
|
466
|
+
version: 1;
|
|
467
|
+
launchContractDigest?: string;
|
|
468
|
+
sourceRunId: string;
|
|
469
|
+
agentContract?: AgentContract;
|
|
470
|
+
agent: string;
|
|
471
|
+
sessionFile?: string;
|
|
472
|
+
cwd: string;
|
|
473
|
+
model?: string;
|
|
474
|
+
fallbackModels?: string[];
|
|
475
|
+
thinking?: string;
|
|
476
|
+
tools?: string[];
|
|
477
|
+
extensions?: string[];
|
|
478
|
+
subagentOnlyExtensions?: string[];
|
|
479
|
+
mcpDirectTools?: string[];
|
|
480
|
+
systemPrompt?: string;
|
|
481
|
+
systemPromptMode: "append" | "replace";
|
|
482
|
+
inheritProjectContext: boolean;
|
|
483
|
+
inheritSkills: boolean;
|
|
484
|
+
skills?: string[];
|
|
485
|
+
skillPath?: string[];
|
|
486
|
+
agentFilePath?: string;
|
|
487
|
+
completionGuard?: boolean;
|
|
488
|
+
memory?: { scope: "project" | "user"; path: string };
|
|
489
|
+
outputPath?: string;
|
|
490
|
+
outputMode: "inline" | "file-only";
|
|
491
|
+
structuredOutputSchema?: JsonSchemaObject;
|
|
492
|
+
acceptance?: AcceptanceInput;
|
|
493
|
+
controlConfig?: ResolvedControlConfig;
|
|
494
|
+
absoluteDeadlineAt?: number;
|
|
495
|
+
initialTurnBudget?: ResolvedTurnBudget;
|
|
496
|
+
initialToolBudget?: ResolvedToolBudget;
|
|
497
|
+
maxSubagentDepth: number;
|
|
498
|
+
maxOutput?: MaxOutputConfig;
|
|
499
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
500
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
501
|
+
share: boolean;
|
|
502
|
+
sessionDir?: string;
|
|
503
|
+
artifactsDir?: string;
|
|
504
|
+
artifactConfig?: ArtifactConfig;
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
export type PublicNestedStepSummary = Pick<
|
|
508
|
+
NestedStepSummary,
|
|
509
|
+
"agent" | "status" | "model" | "thinking" | "sessionFile" | "transcriptPath" | "transcriptError" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "startedAt" | "endedAt" | "error" | "timedOut" | "stopped"
|
|
510
|
+
> & {
|
|
511
|
+
children?: PublicNestedRunSummary[];
|
|
512
|
+
};
|
|
513
|
+
|
|
514
|
+
export type CostSummary = {
|
|
515
|
+
inputTokens: number;
|
|
516
|
+
outputTokens: number;
|
|
517
|
+
costUsd: number;
|
|
518
|
+
};
|
|
519
|
+
|
|
520
|
+
export type PublicNestedRunSummary = Pick<
|
|
521
|
+
NestedRunSummary,
|
|
522
|
+
"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "model" | "thinking" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "totalTokens" | "totalCost" | "startedAt" | "endedAt" | "lastUpdate" | "error" | "timeoutMs" | "deadlineAt" | "timedOut" | "stopped" | "turnBudget" | "turnBudgetExceeded" | "wrapUpRequested"
|
|
523
|
+
> & {
|
|
524
|
+
steps?: PublicNestedStepSummary[];
|
|
525
|
+
children?: PublicNestedRunSummary[];
|
|
526
|
+
};
|
|
527
|
+
|
|
528
|
+
export interface SubagentResultIntercomChild {
|
|
529
|
+
agent: string;
|
|
530
|
+
/** Process/lifecycle status. It does not establish semantic task completion. */
|
|
531
|
+
status: SubagentResultStatus;
|
|
532
|
+
/** Whether the child produced substantive output before its process ended. */
|
|
533
|
+
outputState?: SubagentOutputState;
|
|
534
|
+
summary: string;
|
|
535
|
+
index?: number;
|
|
536
|
+
artifactPath?: string;
|
|
537
|
+
sessionPath?: string;
|
|
538
|
+
intercomTarget?: string;
|
|
539
|
+
children?: PublicNestedRunSummary[];
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
export interface SubagentResultIntercomPayload {
|
|
543
|
+
to: string;
|
|
544
|
+
message: string;
|
|
545
|
+
requestId?: string;
|
|
546
|
+
runId: string;
|
|
547
|
+
mode: SubagentRunMode;
|
|
548
|
+
status: SubagentResultStatus;
|
|
549
|
+
summary: string;
|
|
550
|
+
source: "foreground" | "async";
|
|
551
|
+
children: SubagentResultIntercomChild[];
|
|
552
|
+
asyncId?: string;
|
|
553
|
+
asyncDir?: string;
|
|
554
|
+
chainSteps?: number;
|
|
555
|
+
agent?: string;
|
|
556
|
+
index?: number;
|
|
557
|
+
artifactPath?: string;
|
|
558
|
+
sessionPath?: string;
|
|
559
|
+
parallelHandoff?: ParallelHandoffReference;
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
// ============================================================================
|
|
563
|
+
// Progress Tracking
|
|
564
|
+
// ============================================================================
|
|
565
|
+
|
|
566
|
+
export interface ChildWatchdogProgress {
|
|
567
|
+
phase: "idle" | "reviewing" | "autofollow" | "settling" | "stale" | "failed";
|
|
568
|
+
seq: number;
|
|
569
|
+
lastUpdate: number;
|
|
570
|
+
followUpPending: boolean;
|
|
571
|
+
reason?: string;
|
|
572
|
+
timedOut?: boolean;
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
export interface AgentProgress {
|
|
576
|
+
index: number;
|
|
577
|
+
agent: string;
|
|
578
|
+
status: "pending" | "running" | "completed" | "failed" | "detached";
|
|
579
|
+
activityState?: ActivityState;
|
|
580
|
+
task: string;
|
|
581
|
+
skills?: string[];
|
|
582
|
+
lastActivityAt?: number;
|
|
583
|
+
currentTool?: string;
|
|
584
|
+
currentToolArgs?: string;
|
|
585
|
+
currentToolStartedAt?: number;
|
|
586
|
+
currentPath?: string;
|
|
587
|
+
recentTools: Array<{ tool: string; args: string; endMs: number }>;
|
|
588
|
+
recentOutput: string[];
|
|
589
|
+
toolCount: number;
|
|
590
|
+
turnCount?: number;
|
|
591
|
+
tokens: number;
|
|
592
|
+
/** Resolved launch model/effort and split usage for public live projections. */
|
|
593
|
+
model?: string;
|
|
594
|
+
thinking?: string;
|
|
595
|
+
inputTokens?: number;
|
|
596
|
+
outputTokens?: number;
|
|
597
|
+
durationMs: number;
|
|
598
|
+
error?: string;
|
|
599
|
+
failedTool?: string;
|
|
600
|
+
watchdog?: ChildWatchdogProgress;
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
export interface ToolCallSummary {
|
|
604
|
+
text: string;
|
|
605
|
+
expandedText: string;
|
|
606
|
+
}
|
|
607
|
+
|
|
608
|
+
interface ProgressSummary {
|
|
609
|
+
index?: number;
|
|
610
|
+
agent?: string;
|
|
611
|
+
status?: AgentProgress["status"];
|
|
612
|
+
activityState?: ActivityState;
|
|
613
|
+
skills?: string[];
|
|
614
|
+
lastActivityAt?: number;
|
|
615
|
+
currentTool?: string;
|
|
616
|
+
currentToolArgs?: string;
|
|
617
|
+
currentToolStartedAt?: number;
|
|
618
|
+
recentTools?: Array<{ tool: string; args: string; endMs: number }>;
|
|
619
|
+
recentOutput?: string[];
|
|
620
|
+
toolCount: number;
|
|
621
|
+
tokens: number;
|
|
622
|
+
model?: string;
|
|
623
|
+
thinking?: string;
|
|
624
|
+
durationMs: number;
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
// ============================================================================
|
|
628
|
+
// Results
|
|
629
|
+
// ============================================================================
|
|
630
|
+
|
|
631
|
+
export interface ModelAttempt {
|
|
632
|
+
model: string;
|
|
633
|
+
success: boolean;
|
|
634
|
+
exitCode?: number | null;
|
|
635
|
+
error?: string;
|
|
636
|
+
usage?: Usage;
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
export type AcceptanceLevel = "auto" | "none" | "attested" | "checked" | "verified";
|
|
640
|
+
|
|
641
|
+
export type AcceptanceEvidenceKind =
|
|
642
|
+
| "changed-files"
|
|
643
|
+
| "tests-added"
|
|
644
|
+
| "commands-run"
|
|
645
|
+
| "validation-output"
|
|
646
|
+
| "residual-risks"
|
|
647
|
+
| "no-staged-files"
|
|
648
|
+
| "diff-summary"
|
|
649
|
+
| "review-findings"
|
|
650
|
+
| "manual-notes";
|
|
651
|
+
|
|
652
|
+
export interface AcceptanceGate {
|
|
653
|
+
id: string;
|
|
654
|
+
must: string;
|
|
655
|
+
evidence?: AcceptanceEvidenceKind[];
|
|
656
|
+
severity?: "required" | "recommended";
|
|
657
|
+
}
|
|
658
|
+
|
|
659
|
+
export interface AcceptanceVerifyCommand {
|
|
660
|
+
id: string;
|
|
661
|
+
command: string;
|
|
662
|
+
timeoutMs?: number;
|
|
663
|
+
cwd?: string;
|
|
664
|
+
env?: Record<string, string>;
|
|
665
|
+
allowFailure?: boolean;
|
|
666
|
+
}
|
|
667
|
+
|
|
668
|
+
export interface AcceptanceReviewGate {
|
|
669
|
+
agent?: string;
|
|
670
|
+
focus?: string;
|
|
671
|
+
required?: boolean;
|
|
672
|
+
}
|
|
673
|
+
|
|
674
|
+
export interface AcceptanceConfig {
|
|
675
|
+
level?: AcceptanceLevel;
|
|
676
|
+
criteria?: Array<string | AcceptanceGate>;
|
|
677
|
+
evidence?: AcceptanceEvidenceKind[];
|
|
678
|
+
verify?: AcceptanceVerifyCommand[];
|
|
679
|
+
review?: AcceptanceReviewGate | false;
|
|
680
|
+
stopRules?: string[];
|
|
681
|
+
reason?: string;
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
/** Bare "none" and "verified" are not accepted; verified policies require object form with runtime commands. */
|
|
685
|
+
export type AcceptanceInput = Exclude<AcceptanceLevel, "none" | "verified"> | false | AcceptanceConfig;
|
|
686
|
+
|
|
687
|
+
export interface ResolvedAcceptanceGate extends AcceptanceGate {
|
|
688
|
+
id: string;
|
|
689
|
+
must: string;
|
|
690
|
+
evidence: AcceptanceEvidenceKind[];
|
|
691
|
+
severity: "required" | "recommended";
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
export interface ResolvedAcceptanceConfig {
|
|
695
|
+
level: Exclude<AcceptanceLevel, "auto">;
|
|
696
|
+
explicit: boolean;
|
|
697
|
+
inferredReason: string[];
|
|
698
|
+
criteria: ResolvedAcceptanceGate[];
|
|
699
|
+
evidence: AcceptanceEvidenceKind[];
|
|
700
|
+
verify: AcceptanceVerifyCommand[];
|
|
701
|
+
review?: AcceptanceReviewGate | false;
|
|
702
|
+
stopRules: string[];
|
|
703
|
+
reason?: string;
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
export interface AcceptanceReport {
|
|
707
|
+
criteriaSatisfied?: Array<{
|
|
708
|
+
id?: string;
|
|
709
|
+
status: "satisfied" | "not-satisfied" | "not-applicable";
|
|
710
|
+
evidence: string;
|
|
711
|
+
}>;
|
|
712
|
+
changedFiles?: string[];
|
|
713
|
+
testsAddedOrUpdated?: string[];
|
|
714
|
+
commandsRun?: Array<{
|
|
715
|
+
command: string;
|
|
716
|
+
result: "passed" | "failed" | "not-run";
|
|
717
|
+
summary: string;
|
|
718
|
+
}>;
|
|
719
|
+
validationOutput?: string[];
|
|
720
|
+
residualRisks?: string[];
|
|
721
|
+
noStagedFiles?: boolean;
|
|
722
|
+
diffSummary?: string;
|
|
723
|
+
reviewFindings?: string[];
|
|
724
|
+
manualNotes?: string;
|
|
725
|
+
notes?: string;
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
export type AcceptanceRuntimeCheckStatus = "passed" | "failed" | "not-applicable";
|
|
729
|
+
|
|
730
|
+
export interface AcceptanceRuntimeCheck {
|
|
731
|
+
id: string;
|
|
732
|
+
status: AcceptanceRuntimeCheckStatus;
|
|
733
|
+
message: string;
|
|
734
|
+
}
|
|
735
|
+
|
|
736
|
+
export interface AcceptanceVerifyResult {
|
|
737
|
+
id: string;
|
|
738
|
+
command: string;
|
|
739
|
+
cwd?: string;
|
|
740
|
+
exitCode: number | null;
|
|
741
|
+
status: "passed" | "failed" | "timed-out" | "allowed-failure";
|
|
742
|
+
stdout?: string;
|
|
743
|
+
stderr?: string;
|
|
744
|
+
durationMs: number;
|
|
745
|
+
artifactPath?: string;
|
|
746
|
+
cacheKey?: string;
|
|
747
|
+
memoized?: boolean;
|
|
748
|
+
envKeys?: string[];
|
|
749
|
+
envHash?: string;
|
|
750
|
+
workspaceState?: {
|
|
751
|
+
kind: "git-tracked";
|
|
752
|
+
repoRoot: string;
|
|
753
|
+
cwdRelative: string;
|
|
754
|
+
head: string;
|
|
755
|
+
diffHash: string;
|
|
756
|
+
};
|
|
757
|
+
artifactError?: string;
|
|
758
|
+
}
|
|
759
|
+
|
|
760
|
+
export interface AcceptanceReviewResult {
|
|
761
|
+
status: "review-required" | "reviewed" | "blockers";
|
|
762
|
+
findings: Array<{
|
|
763
|
+
severity: "blocker" | "non-blocking";
|
|
764
|
+
file?: string;
|
|
765
|
+
issue: string;
|
|
766
|
+
rationale: string;
|
|
767
|
+
}>;
|
|
768
|
+
}
|
|
769
|
+
|
|
770
|
+
export type AcceptanceEvidenceStatus =
|
|
771
|
+
| "pending"
|
|
772
|
+
| "not-required"
|
|
773
|
+
| "claimed"
|
|
774
|
+
| "attested"
|
|
775
|
+
| "checked"
|
|
776
|
+
| "verified"
|
|
777
|
+
| "rejected";
|
|
778
|
+
|
|
779
|
+
export type AcceptanceLedgerStatus =
|
|
780
|
+
| AcceptanceEvidenceStatus
|
|
781
|
+
| "review-required"
|
|
782
|
+
| "reviewed"
|
|
783
|
+
| "accepted";
|
|
784
|
+
|
|
785
|
+
export interface AcceptanceLedger {
|
|
786
|
+
status: AcceptanceLedgerStatus;
|
|
787
|
+
evidenceStatus: AcceptanceEvidenceStatus;
|
|
788
|
+
explicit: boolean;
|
|
789
|
+
effectiveAcceptance: ResolvedAcceptanceConfig;
|
|
790
|
+
inferredReason: string[];
|
|
791
|
+
criteria: ResolvedAcceptanceGate[];
|
|
792
|
+
childReport?: AcceptanceReport;
|
|
793
|
+
childReportParseError?: string;
|
|
794
|
+
runtimeChecks: AcceptanceRuntimeCheck[];
|
|
795
|
+
verifyRuns: AcceptanceVerifyResult[];
|
|
796
|
+
reviewResult?: AcceptanceReviewResult;
|
|
797
|
+
parentDecision?: {
|
|
798
|
+
status: "accepted" | "rejected";
|
|
799
|
+
at: string;
|
|
800
|
+
reason?: string;
|
|
801
|
+
};
|
|
802
|
+
}
|
|
803
|
+
|
|
804
|
+
export interface ProtocolOutputLimit {
|
|
805
|
+
code: "protocol_output_limit";
|
|
806
|
+
stream: "stdout" | "stderr";
|
|
807
|
+
limitBytes: number;
|
|
808
|
+
observedBytes: number;
|
|
809
|
+
diagnosticPrefix: string;
|
|
810
|
+
diagnosticTail: string;
|
|
811
|
+
}
|
|
812
|
+
|
|
813
|
+
export interface LaunchResolvedChildExtensionsV1 {
|
|
814
|
+
version: 1;
|
|
815
|
+
/** This is parent-resolved launch intent, not child-runtime acknowledgement that extensions loaded. */
|
|
816
|
+
source: "launch-resolved";
|
|
817
|
+
disableAmbientExtensions: boolean;
|
|
818
|
+
runtime: string[];
|
|
819
|
+
configured: string[];
|
|
820
|
+
effective: string[];
|
|
821
|
+
omitted: {
|
|
822
|
+
runtime: number;
|
|
823
|
+
configured: number;
|
|
824
|
+
effective: number;
|
|
825
|
+
};
|
|
826
|
+
}
|
|
827
|
+
|
|
828
|
+
export interface RuntimeAcknowledgedChildExtensionsV1 {
|
|
829
|
+
version: 1;
|
|
830
|
+
/** Best-effort child-runtime registration acknowledgement, not extension health. */
|
|
831
|
+
source: "child-runtime";
|
|
832
|
+
ids: string[];
|
|
833
|
+
omitted: number;
|
|
834
|
+
}
|
|
835
|
+
|
|
836
|
+
export interface UsageBudgetLimitConfig {
|
|
837
|
+
soft?: number;
|
|
838
|
+
hard: number;
|
|
839
|
+
}
|
|
840
|
+
|
|
841
|
+
export interface UsageBudgetConfig {
|
|
842
|
+
tokens?: UsageBudgetLimitConfig;
|
|
843
|
+
costUsd?: UsageBudgetLimitConfig;
|
|
844
|
+
}
|
|
845
|
+
|
|
846
|
+
export interface UsageBudgetMetricState extends UsageBudgetLimitConfig {
|
|
847
|
+
used: number;
|
|
848
|
+
outcome: "within-budget" | "soft-exceeded" | "hard-exceeded";
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
export interface UsageBudgetState {
|
|
852
|
+
version: 1;
|
|
853
|
+
/** Enforced from usage reported by completed or streaming child runs; no reservation estimates. */
|
|
854
|
+
source: "reported";
|
|
855
|
+
tokens?: UsageBudgetMetricState;
|
|
856
|
+
costUsd?: UsageBudgetMetricState;
|
|
857
|
+
exhausted: boolean;
|
|
858
|
+
reason?: "tokens" | "costUsd";
|
|
859
|
+
}
|
|
860
|
+
|
|
861
|
+
export interface SingleResult {
|
|
862
|
+
/**
|
|
863
|
+
* Stable child identity within the foreground run. Pair with Details.runId for
|
|
864
|
+
* cross-run correlation. This is assigned in launch order, remains stable across
|
|
865
|
+
* partial progress snapshots and the final result, and is independent of the
|
|
866
|
+
* result row's array position.
|
|
867
|
+
*/
|
|
868
|
+
index: number;
|
|
869
|
+
agent: string;
|
|
870
|
+
task: string;
|
|
871
|
+
/** Resolved launch context for this child. */
|
|
872
|
+
context?: "fresh" | "fork";
|
|
873
|
+
exitCode: number;
|
|
874
|
+
processSignal?: string | null;
|
|
875
|
+
detached?: boolean;
|
|
876
|
+
detachedReason?: string;
|
|
877
|
+
interrupted?: boolean;
|
|
878
|
+
timedOut?: boolean;
|
|
879
|
+
stopped?: boolean;
|
|
880
|
+
turnBudget?: TurnBudgetState;
|
|
881
|
+
turnBudgetExceeded?: boolean;
|
|
882
|
+
wrapUpRequested?: boolean;
|
|
883
|
+
toolBudget?: ToolBudgetState;
|
|
884
|
+
toolBudgetBlocked?: boolean;
|
|
885
|
+
messages?: Message[];
|
|
886
|
+
usage: Usage;
|
|
887
|
+
model?: string;
|
|
888
|
+
/** Effective thinking level used by this foreground child, when known. */
|
|
889
|
+
thinking?: string;
|
|
890
|
+
attemptedModels?: string[];
|
|
891
|
+
modelAttempts?: ModelAttempt[];
|
|
892
|
+
controlEvents?: ControlEvent[];
|
|
893
|
+
error?: string;
|
|
894
|
+
protocolError?: ProtocolOutputLimit;
|
|
895
|
+
sessionFile?: string;
|
|
896
|
+
skills?: string[];
|
|
897
|
+
skillsWarning?: string;
|
|
898
|
+
progress?: AgentProgress;
|
|
899
|
+
progressSummary?: ProgressSummary;
|
|
900
|
+
toolCalls?: ToolCallSummary[];
|
|
901
|
+
artifactPaths?: ArtifactPaths;
|
|
902
|
+
truncation?: TruncationResult;
|
|
903
|
+
finalOutput?: string;
|
|
904
|
+
/** Provenance-aware state for substantive child output, excluding synthetic lifecycle messages. */
|
|
905
|
+
outputState?: SubagentOutputState;
|
|
906
|
+
outputMode?: OutputMode;
|
|
907
|
+
savedOutputPath?: string;
|
|
908
|
+
outputReference?: SavedOutputReference;
|
|
909
|
+
outputSaveError?: string;
|
|
910
|
+
/** Best-effort metadata persistence failure; execution and receipt publication continue. */
|
|
911
|
+
metadataSaveError?: string;
|
|
912
|
+
structuredOutput?: unknown;
|
|
913
|
+
structuredOutputFailed?: boolean;
|
|
914
|
+
structuredOutputPath?: string;
|
|
915
|
+
structuredOutputSchemaPath?: string;
|
|
916
|
+
acceptance?: AcceptanceLedger;
|
|
917
|
+
agentContract?: AgentContract;
|
|
918
|
+
launchContractDigest?: string;
|
|
919
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
920
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
921
|
+
execution?: ExecutionProjection;
|
|
922
|
+
review?: ReviewProjection;
|
|
923
|
+
effects?: EffectsProjection;
|
|
924
|
+
transcriptPath?: string;
|
|
925
|
+
transcriptError?: string;
|
|
926
|
+
children?: NestedRunSummary[];
|
|
927
|
+
watchdog?: ChildWatchdogProgress;
|
|
928
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
929
|
+
capabilityAudit?: SubagentCapabilityAudit;
|
|
930
|
+
}
|
|
931
|
+
|
|
932
|
+
export interface SpawnBudgetGrant {
|
|
933
|
+
sessionId: string;
|
|
934
|
+
amount: number;
|
|
935
|
+
grantedAt: number;
|
|
936
|
+
previousLimit: number;
|
|
937
|
+
limit: number;
|
|
938
|
+
}
|
|
939
|
+
|
|
940
|
+
export interface SpawnBudgetSnapshot {
|
|
941
|
+
used: number;
|
|
942
|
+
configuredLimit: number | null;
|
|
943
|
+
granted: number;
|
|
944
|
+
limit: number | null;
|
|
945
|
+
remaining: number | null;
|
|
946
|
+
grantRemaining: number | null;
|
|
947
|
+
grantHistory: SpawnBudgetGrant[];
|
|
948
|
+
}
|
|
949
|
+
|
|
950
|
+
/** Slim per-child projection of a terminal result payload, safe to surface in tool_result details. */
|
|
951
|
+
export interface WaitCompletionChild {
|
|
952
|
+
agent?: string;
|
|
953
|
+
/** Child run identity where the producer records one (workflow children); artifact files are keyed by it. */
|
|
954
|
+
runId?: string;
|
|
955
|
+
success?: boolean;
|
|
956
|
+
outputState?: SubagentOutputState;
|
|
957
|
+
error?: string;
|
|
958
|
+
model?: string;
|
|
959
|
+
artifactPaths?: Partial<ArtifactPaths>;
|
|
960
|
+
}
|
|
961
|
+
|
|
962
|
+
/**
|
|
963
|
+
* Terminal completion observed for a run a subagent_wait call covered. Carries run
|
|
964
|
+
* identity and the artifact trail; output text stays in the tool result content.
|
|
965
|
+
*/
|
|
966
|
+
export interface WaitCompletion {
|
|
967
|
+
runId: string;
|
|
968
|
+
agent?: string;
|
|
969
|
+
mode?: string;
|
|
970
|
+
state?: string;
|
|
971
|
+
success?: boolean;
|
|
972
|
+
results?: WaitCompletionChild[];
|
|
973
|
+
}
|
|
974
|
+
|
|
975
|
+
export interface Details {
|
|
976
|
+
mode: SubagentResultMode | "management";
|
|
977
|
+
runId?: string;
|
|
978
|
+
/** Host tool-call id retained when it differs from the internal run id. */
|
|
979
|
+
toolCallId?: string;
|
|
980
|
+
/** Run-level context summary. "mixed" when children resolved to different modes. */
|
|
981
|
+
context?: "fresh" | "fork" | "mixed";
|
|
982
|
+
results: SingleResult[];
|
|
983
|
+
/**
|
|
984
|
+
* Terminal completion payloads for runs this subagent_wait call observed
|
|
985
|
+
* finishing. Async completions travel as result files that are consumed and
|
|
986
|
+
* deleted after text delivery, so without this field their run and artifact
|
|
987
|
+
* identity never reaches tool_result details.
|
|
988
|
+
*/
|
|
989
|
+
completions?: WaitCompletion[];
|
|
990
|
+
controlEvents?: ControlEvent[];
|
|
991
|
+
steering?: SteerActionResult;
|
|
992
|
+
asyncId?: string;
|
|
993
|
+
asyncDir?: string;
|
|
994
|
+
timeoutMs?: number;
|
|
995
|
+
deadlineAt?: number;
|
|
996
|
+
timedOut?: boolean;
|
|
997
|
+
stopped?: boolean;
|
|
998
|
+
turnBudget?: ResolvedTurnBudget;
|
|
999
|
+
toolBudget?: ResolvedToolBudget;
|
|
1000
|
+
usageBudget?: UsageBudgetState;
|
|
1001
|
+
progress?: AgentProgress[];
|
|
1002
|
+
progressSummary?: ProgressSummary;
|
|
1003
|
+
artifacts?: {
|
|
1004
|
+
dir: string;
|
|
1005
|
+
files: ArtifactPaths[];
|
|
1006
|
+
};
|
|
1007
|
+
truncation?: {
|
|
1008
|
+
truncated: boolean;
|
|
1009
|
+
originalBytes?: number;
|
|
1010
|
+
originalLines?: number;
|
|
1011
|
+
artifactPath?: string;
|
|
1012
|
+
};
|
|
1013
|
+
// Chain metadata for observability
|
|
1014
|
+
chainAgents?: string[]; // Agent names in order, e.g., ["scout", "planner"]
|
|
1015
|
+
totalSteps?: number; // Total steps in chain
|
|
1016
|
+
currentStepIndex?: number; // 0-indexed current step (for running chains)
|
|
1017
|
+
workflowGraph?: WorkflowGraphSnapshot;
|
|
1018
|
+
checkpoint?: ChainCheckpointState;
|
|
1019
|
+
outputs?: ChainOutputMap;
|
|
1020
|
+
// Aggregated child usage across all agents in the run
|
|
1021
|
+
totalChildUsage?: Usage;
|
|
1022
|
+
// Aggregated cost across all agents in the run
|
|
1023
|
+
totalCost?: CostSummary;
|
|
1024
|
+
spawnBudget?: SpawnBudgetSnapshot;
|
|
1025
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1026
|
+
capabilityAudit?: SubagentCapabilityAudit;
|
|
1027
|
+
parallelHandoff?: ParallelHandoffReference;
|
|
1028
|
+
lifecycleStatus?: {
|
|
1029
|
+
processTerminal?: ProcessTerminalV1;
|
|
1030
|
+
};
|
|
1031
|
+
launchContractDigest?: string;
|
|
1032
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
1033
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
1034
|
+
/** Original launch contract whose persisted session is being revived. */
|
|
1035
|
+
sourceLaunchContractDigest?: string;
|
|
1036
|
+
/** Durable mission attached to this run, when mission mode was explicitly used. */
|
|
1037
|
+
missionId?: string;
|
|
1038
|
+
missionPath?: string;
|
|
1039
|
+
/** Non-fatal automatic mission persistence failure. */
|
|
1040
|
+
missionWarning?: string;
|
|
1041
|
+
mission?: MissionRecord;
|
|
1042
|
+
workflow?: {
|
|
1043
|
+
value?: unknown;
|
|
1044
|
+
trace: Array<{
|
|
1045
|
+
operation: "run" | "status";
|
|
1046
|
+
key: string;
|
|
1047
|
+
state: "started" | "completed" | "failed" | "reused";
|
|
1048
|
+
runId?: string;
|
|
1049
|
+
phase?: string;
|
|
1050
|
+
label?: string;
|
|
1051
|
+
durationMs?: number;
|
|
1052
|
+
error?: string;
|
|
1053
|
+
}>;
|
|
1054
|
+
emits: unknown[];
|
|
1055
|
+
console: Array<{ level: "log" | "info" | "warn" | "error"; text: string }>;
|
|
1056
|
+
};
|
|
1057
|
+
chatProgress?: {
|
|
1058
|
+
mode: "off" | "live-card";
|
|
1059
|
+
repoRelation: "same" | "other";
|
|
1060
|
+
repoLabel?: string;
|
|
1061
|
+
};
|
|
1062
|
+
missions?: {
|
|
1063
|
+
records?: MissionRecord[];
|
|
1064
|
+
globalEntries?: GlobalMissionIndexRecord[];
|
|
1065
|
+
warnings: string[];
|
|
1066
|
+
};
|
|
1067
|
+
/** Project-scoped recurring schedule records and run history for management actions. */
|
|
1068
|
+
schedules?: {
|
|
1069
|
+
records?: unknown[];
|
|
1070
|
+
runs?: unknown[];
|
|
1071
|
+
};
|
|
1072
|
+
}
|
|
1073
|
+
|
|
1074
|
+
// ============================================================================
|
|
1075
|
+
// Artifacts
|
|
1076
|
+
// ============================================================================
|
|
1077
|
+
|
|
1078
|
+
export interface ArtifactPaths {
|
|
1079
|
+
inputPath: string;
|
|
1080
|
+
outputPath: string;
|
|
1081
|
+
jsonlPath: string;
|
|
1082
|
+
transcriptPath: string;
|
|
1083
|
+
metadataPath: string;
|
|
1084
|
+
}
|
|
1085
|
+
|
|
1086
|
+
export type ArtifactDirPreference = "project" | "session" | "temp";
|
|
1087
|
+
|
|
1088
|
+
export interface ArtifactConfig {
|
|
1089
|
+
enabled: boolean;
|
|
1090
|
+
dir?: ArtifactDirPreference;
|
|
1091
|
+
includeInput: boolean;
|
|
1092
|
+
includeOutput: boolean;
|
|
1093
|
+
includeJsonl: boolean;
|
|
1094
|
+
includeTranscript?: boolean;
|
|
1095
|
+
includeMetadata: boolean;
|
|
1096
|
+
cleanupDays: number;
|
|
1097
|
+
}
|
|
1098
|
+
|
|
1099
|
+
// ============================================================================
|
|
1100
|
+
// Async Execution
|
|
1101
|
+
// ============================================================================
|
|
1102
|
+
|
|
1103
|
+
export interface AsyncParallelGroupStatus {
|
|
1104
|
+
start: number;
|
|
1105
|
+
count: number;
|
|
1106
|
+
stepIndex: number;
|
|
1107
|
+
}
|
|
1108
|
+
|
|
1109
|
+
export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
|
|
1110
|
+
export type NestedOwnerState = "live" | "gone" | "unknown";
|
|
1111
|
+
|
|
1112
|
+
export interface NestedRunAddress {
|
|
1113
|
+
id: string;
|
|
1114
|
+
parentRunId: string;
|
|
1115
|
+
parentStepIndex?: number;
|
|
1116
|
+
parentAgent?: string;
|
|
1117
|
+
depth: number;
|
|
1118
|
+
path: Array<{ runId: string; stepIndex?: number; agent?: string }>;
|
|
1119
|
+
}
|
|
1120
|
+
|
|
1121
|
+
export interface NestedStepSummary {
|
|
1122
|
+
agent: string;
|
|
1123
|
+
status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
|
|
1124
|
+
model?: string;
|
|
1125
|
+
thinking?: string;
|
|
1126
|
+
sessionFile?: string;
|
|
1127
|
+
transcriptPath?: string;
|
|
1128
|
+
transcriptError?: string;
|
|
1129
|
+
activityState?: ActivityState;
|
|
1130
|
+
lastActivityAt?: number;
|
|
1131
|
+
currentTool?: string;
|
|
1132
|
+
currentToolStartedAt?: number;
|
|
1133
|
+
currentPath?: string;
|
|
1134
|
+
turnCount?: number;
|
|
1135
|
+
toolCount?: number;
|
|
1136
|
+
startedAt?: number;
|
|
1137
|
+
endedAt?: number;
|
|
1138
|
+
error?: string;
|
|
1139
|
+
watchdog?: ChildWatchdogProgress;
|
|
1140
|
+
timedOut?: boolean;
|
|
1141
|
+
stopped?: boolean;
|
|
1142
|
+
turnBudget?: TurnBudgetState;
|
|
1143
|
+
turnBudgetExceeded?: boolean;
|
|
1144
|
+
wrapUpRequested?: boolean;
|
|
1145
|
+
toolBudget?: ToolBudgetState;
|
|
1146
|
+
toolBudgetBlocked?: boolean;
|
|
1147
|
+
processTerminal?: ProcessTerminalV1;
|
|
1148
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
1149
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
1150
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1151
|
+
capabilityAudit?: SubagentCapabilityAudit;
|
|
1152
|
+
children?: NestedRunSummary[];
|
|
1153
|
+
}
|
|
1154
|
+
|
|
1155
|
+
export interface NestedRunSummary extends NestedRunAddress {
|
|
1156
|
+
asyncDir?: string;
|
|
1157
|
+
pid?: number;
|
|
1158
|
+
sessionId?: string;
|
|
1159
|
+
sessionFile?: string;
|
|
1160
|
+
intercomTarget?: string;
|
|
1161
|
+
ownerIntercomTarget?: string;
|
|
1162
|
+
leafIntercomTarget?: string;
|
|
1163
|
+
ownerState?: NestedOwnerState;
|
|
1164
|
+
controlInbox?: string;
|
|
1165
|
+
capabilityToken?: string;
|
|
1166
|
+
mode?: SubagentRunMode;
|
|
1167
|
+
processTerminal?: ProcessTerminalV1;
|
|
1168
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
1169
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
1170
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1171
|
+
capabilityAudit?: SubagentCapabilityAudit;
|
|
1172
|
+
state: NestedRunState;
|
|
1173
|
+
agent?: string;
|
|
1174
|
+
agents?: string[];
|
|
1175
|
+
model?: string;
|
|
1176
|
+
thinking?: string;
|
|
1177
|
+
currentStep?: number;
|
|
1178
|
+
chainStepCount?: number;
|
|
1179
|
+
parallelGroups?: AsyncParallelGroupStatus[];
|
|
1180
|
+
steps?: NestedStepSummary[];
|
|
1181
|
+
children?: NestedRunSummary[];
|
|
1182
|
+
activityState?: ActivityState;
|
|
1183
|
+
lastActivityAt?: number;
|
|
1184
|
+
currentTool?: string;
|
|
1185
|
+
currentToolStartedAt?: number;
|
|
1186
|
+
currentPath?: string;
|
|
1187
|
+
turnCount?: number;
|
|
1188
|
+
toolCount?: number;
|
|
1189
|
+
totalTokens?: TokenUsage;
|
|
1190
|
+
totalCost?: CostSummary;
|
|
1191
|
+
startedAt?: number;
|
|
1192
|
+
endedAt?: number;
|
|
1193
|
+
lastUpdate?: number;
|
|
1194
|
+
timeoutMs?: number;
|
|
1195
|
+
deadlineAt?: number;
|
|
1196
|
+
timedOut?: boolean;
|
|
1197
|
+
stopped?: boolean;
|
|
1198
|
+
turnBudget?: TurnBudgetState;
|
|
1199
|
+
turnBudgetExceeded?: boolean;
|
|
1200
|
+
wrapUpRequested?: boolean;
|
|
1201
|
+
toolBudget?: ToolBudgetState;
|
|
1202
|
+
toolBudgetBlocked?: boolean;
|
|
1203
|
+
error?: string;
|
|
1204
|
+
}
|
|
1205
|
+
|
|
1206
|
+
export interface NestedRouteInfo {
|
|
1207
|
+
rootRunId: string;
|
|
1208
|
+
eventSink: string;
|
|
1209
|
+
controlInbox: string;
|
|
1210
|
+
capabilityToken: string;
|
|
1211
|
+
}
|
|
1212
|
+
|
|
1213
|
+
export interface AsyncStartedEvent {
|
|
1214
|
+
lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
|
|
1215
|
+
id?: string;
|
|
1216
|
+
asyncDir?: string;
|
|
1217
|
+
/** Parent-resolved launch directory, used as a trusted artifact root while this session is live. */
|
|
1218
|
+
cwd?: string;
|
|
1219
|
+
pid?: number;
|
|
1220
|
+
sessionId?: string;
|
|
1221
|
+
mode?: SubagentRunMode;
|
|
1222
|
+
agent?: string;
|
|
1223
|
+
agents?: string[];
|
|
1224
|
+
/** Truncated first child task retained for backwards compatibility. */
|
|
1225
|
+
task?: string;
|
|
1226
|
+
/** Workflow-level caller task, falling back to the first child task. */
|
|
1227
|
+
goal?: string;
|
|
1228
|
+
chain?: string[];
|
|
1229
|
+
chainStepCount?: number;
|
|
1230
|
+
parallelGroups?: AsyncParallelGroupStatus[];
|
|
1231
|
+
workflowGraph?: WorkflowGraphSnapshot;
|
|
1232
|
+
checkpoint?: ChainCheckpointState;
|
|
1233
|
+
launchContractDigest?: string;
|
|
1234
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
1235
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
1236
|
+
usageBudget?: UsageBudgetState;
|
|
1237
|
+
timeoutMs?: number;
|
|
1238
|
+
deadlineAt?: number;
|
|
1239
|
+
turnBudget?: TurnBudgetState;
|
|
1240
|
+
nestedRoute?: NestedRouteInfo;
|
|
1241
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1242
|
+
parentWorkflowRunId?: string;
|
|
1243
|
+
workflowKey?: string;
|
|
1244
|
+
}
|
|
1245
|
+
|
|
1246
|
+
export type AgentRunnerConfig =
|
|
1247
|
+
| { type: "pi" }
|
|
1248
|
+
| {
|
|
1249
|
+
type: "external-cli";
|
|
1250
|
+
command: string;
|
|
1251
|
+
args?: string[];
|
|
1252
|
+
promptDelivery?: "stdin";
|
|
1253
|
+
};
|
|
1254
|
+
|
|
1255
|
+
export interface ExternalCliRunnerStatus {
|
|
1256
|
+
type: "external-cli";
|
|
1257
|
+
command: string;
|
|
1258
|
+
args: string[];
|
|
1259
|
+
promptDelivery: "stdin";
|
|
1260
|
+
capabilities: {
|
|
1261
|
+
stop: true;
|
|
1262
|
+
steer: false;
|
|
1263
|
+
resume: false;
|
|
1264
|
+
structuredOutput: false;
|
|
1265
|
+
toolEvents: false;
|
|
1266
|
+
};
|
|
1267
|
+
}
|
|
1268
|
+
|
|
1269
|
+
export interface ExternalProcessStatus {
|
|
1270
|
+
pid?: number;
|
|
1271
|
+
startedAt: number;
|
|
1272
|
+
endedAt?: number;
|
|
1273
|
+
durationMs?: number;
|
|
1274
|
+
exitCode?: number | null;
|
|
1275
|
+
processSignal?: string | null;
|
|
1276
|
+
stdoutPath: string;
|
|
1277
|
+
stderrPath: string;
|
|
1278
|
+
}
|
|
1279
|
+
|
|
1280
|
+
export interface AsyncStatus {
|
|
1281
|
+
lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
|
|
1282
|
+
runId: string;
|
|
1283
|
+
/** Host tool-call id retained when it differs from the internal run id. */
|
|
1284
|
+
toolCallId?: string;
|
|
1285
|
+
sessionId?: string;
|
|
1286
|
+
mode: SubagentRunMode;
|
|
1287
|
+
context?: "fresh" | "fork" | "mixed";
|
|
1288
|
+
isNested?: boolean;
|
|
1289
|
+
state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
|
|
1290
|
+
error?: string;
|
|
1291
|
+
activityState?: ActivityState;
|
|
1292
|
+
lastActivityAt?: number;
|
|
1293
|
+
currentTool?: string;
|
|
1294
|
+
currentToolStartedAt?: number;
|
|
1295
|
+
currentPath?: string;
|
|
1296
|
+
turnCount?: number;
|
|
1297
|
+
toolCount?: number;
|
|
1298
|
+
steering?: SteeringStatus;
|
|
1299
|
+
startedAt: number;
|
|
1300
|
+
endedAt?: number;
|
|
1301
|
+
lastUpdate?: number;
|
|
1302
|
+
timeoutMs?: number;
|
|
1303
|
+
deadlineAt?: number;
|
|
1304
|
+
timedOut?: boolean;
|
|
1305
|
+
stopped?: boolean;
|
|
1306
|
+
turnBudget?: TurnBudgetState;
|
|
1307
|
+
turnBudgetExceeded?: boolean;
|
|
1308
|
+
wrapUpRequested?: boolean;
|
|
1309
|
+
toolBudget?: ToolBudgetState;
|
|
1310
|
+
toolBudgetBlocked?: boolean;
|
|
1311
|
+
usageBudget?: UsageBudgetState;
|
|
1312
|
+
pid?: number;
|
|
1313
|
+
cwd?: string;
|
|
1314
|
+
currentStep?: number;
|
|
1315
|
+
chainStepCount?: number;
|
|
1316
|
+
pendingAppends?: number;
|
|
1317
|
+
parallelGroups?: AsyncParallelGroupStatus[];
|
|
1318
|
+
workflowGraph?: WorkflowGraphSnapshot;
|
|
1319
|
+
checkpoint?: ChainCheckpointState;
|
|
1320
|
+
processTerminal?: ProcessTerminalV1;
|
|
1321
|
+
launchContractDigest?: string;
|
|
1322
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
1323
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
1324
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1325
|
+
capabilityAudit?: SubagentCapabilityAudit;
|
|
1326
|
+
workflow?: Details["workflow"];
|
|
1327
|
+
parentWorkflowRunId?: string;
|
|
1328
|
+
workflowKey?: string;
|
|
1329
|
+
steps?: Array<{
|
|
1330
|
+
agent: string;
|
|
1331
|
+
runner?: ExternalCliRunnerStatus;
|
|
1332
|
+
externalProcess?: ExternalProcessStatus;
|
|
1333
|
+
/** Resolved launch context for this child step. */
|
|
1334
|
+
context?: "fresh" | "fork";
|
|
1335
|
+
/** Short caller-facing task/goal shown in fleet surfaces when available. */
|
|
1336
|
+
description?: string;
|
|
1337
|
+
phase?: string;
|
|
1338
|
+
label?: string;
|
|
1339
|
+
workflowKey?: string;
|
|
1340
|
+
parentWorkflowRunId?: string;
|
|
1341
|
+
outputName?: string;
|
|
1342
|
+
structured?: boolean;
|
|
1343
|
+
checkpoint?: ChainCheckpointState;
|
|
1344
|
+
status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
|
|
1345
|
+
children?: NestedRunSummary[];
|
|
1346
|
+
sessionFile?: string;
|
|
1347
|
+
transcriptPath?: string;
|
|
1348
|
+
transcriptError?: string;
|
|
1349
|
+
activityState?: ActivityState;
|
|
1350
|
+
lastActivityAt?: number;
|
|
1351
|
+
currentTool?: string;
|
|
1352
|
+
currentToolArgs?: string;
|
|
1353
|
+
currentToolStartedAt?: number;
|
|
1354
|
+
currentPath?: string;
|
|
1355
|
+
recentTools?: Array<{ tool: string; args: string; endMs: number }>;
|
|
1356
|
+
recentOutput?: string[];
|
|
1357
|
+
turnCount?: number;
|
|
1358
|
+
toolCount?: number;
|
|
1359
|
+
startedAt?: number;
|
|
1360
|
+
endedAt?: number;
|
|
1361
|
+
durationMs?: number;
|
|
1362
|
+
exitCode?: number | null;
|
|
1363
|
+
timedOut?: boolean;
|
|
1364
|
+
stopped?: boolean;
|
|
1365
|
+
turnBudget?: TurnBudgetState;
|
|
1366
|
+
turnBudgetExceeded?: boolean;
|
|
1367
|
+
wrapUpRequested?: boolean;
|
|
1368
|
+
toolBudget?: ToolBudgetState;
|
|
1369
|
+
toolBudgetBlocked?: boolean;
|
|
1370
|
+
tokens?: TokenUsage;
|
|
1371
|
+
skills?: string[];
|
|
1372
|
+
model?: string;
|
|
1373
|
+
thinking?: string;
|
|
1374
|
+
attemptedModels?: string[];
|
|
1375
|
+
modelAttempts?: ModelAttempt[];
|
|
1376
|
+
totalCost?: CostSummary;
|
|
1377
|
+
steering?: SteeringStatus;
|
|
1378
|
+
error?: string;
|
|
1379
|
+
structuredOutput?: unknown;
|
|
1380
|
+
structuredOutputPath?: string;
|
|
1381
|
+
structuredOutputSchemaPath?: string;
|
|
1382
|
+
acceptance?: AcceptanceLedger;
|
|
1383
|
+
agentContract?: AgentContract;
|
|
1384
|
+
launchContractDigest?: string;
|
|
1385
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
1386
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
1387
|
+
execution?: ExecutionProjection;
|
|
1388
|
+
review?: ReviewProjection;
|
|
1389
|
+
effects?: EffectsProjection;
|
|
1390
|
+
watchdog?: ChildWatchdogProgress;
|
|
1391
|
+
processTerminal?: ProcessTerminalV1;
|
|
1392
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1393
|
+
capabilityAudit?: SubagentCapabilityAudit;
|
|
1394
|
+
}>;
|
|
1395
|
+
sessionDir?: string;
|
|
1396
|
+
outputFile?: string;
|
|
1397
|
+
totalTokens?: TokenUsage;
|
|
1398
|
+
totalCost?: CostSummary;
|
|
1399
|
+
sessionFile?: string;
|
|
1400
|
+
outputs?: ChainOutputMap;
|
|
1401
|
+
parallelHandoff?: ParallelHandoffReference;
|
|
1402
|
+
}
|
|
1403
|
+
|
|
1404
|
+
export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
|
|
1405
|
+
index?: number;
|
|
1406
|
+
description?: string;
|
|
1407
|
+
};
|
|
1408
|
+
|
|
1409
|
+
export interface AsyncJobState {
|
|
1410
|
+
asyncId: string;
|
|
1411
|
+
asyncDir: string;
|
|
1412
|
+
/** Parent-resolved launch directory retained for trusted live artifact lookup. */
|
|
1413
|
+
cwd?: string;
|
|
1414
|
+
status: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
|
|
1415
|
+
/** Short caller-facing task/goal shown in fleet surfaces when available. */
|
|
1416
|
+
description?: string;
|
|
1417
|
+
pid?: number;
|
|
1418
|
+
sessionId?: string;
|
|
1419
|
+
activityState?: ActivityState;
|
|
1420
|
+
lastActivityAt?: number;
|
|
1421
|
+
currentTool?: string;
|
|
1422
|
+
currentToolStartedAt?: number;
|
|
1423
|
+
currentPath?: string;
|
|
1424
|
+
turnCount?: number;
|
|
1425
|
+
toolCount?: number;
|
|
1426
|
+
steering?: SteeringStatus;
|
|
1427
|
+
mode?: SubagentRunMode;
|
|
1428
|
+
/** Run-level context summary derived from step contexts. */
|
|
1429
|
+
context?: "fresh" | "fork" | "mixed";
|
|
1430
|
+
agents?: string[];
|
|
1431
|
+
currentStep?: number;
|
|
1432
|
+
chainStepCount?: number;
|
|
1433
|
+
parallelGroups?: AsyncParallelGroupStatus[];
|
|
1434
|
+
steps?: AsyncJobStep[];
|
|
1435
|
+
checkpoint?: ChainCheckpointState;
|
|
1436
|
+
stepsTotal?: number;
|
|
1437
|
+
runningSteps?: number;
|
|
1438
|
+
completedSteps?: number;
|
|
1439
|
+
hasParallelGroups?: boolean;
|
|
1440
|
+
activeParallelGroup?: boolean;
|
|
1441
|
+
startedAt?: number;
|
|
1442
|
+
updatedAt?: number;
|
|
1443
|
+
timeoutMs?: number;
|
|
1444
|
+
deadlineAt?: number;
|
|
1445
|
+
timedOut?: boolean;
|
|
1446
|
+
stopped?: boolean;
|
|
1447
|
+
turnBudget?: TurnBudgetState;
|
|
1448
|
+
turnBudgetExceeded?: boolean;
|
|
1449
|
+
wrapUpRequested?: boolean;
|
|
1450
|
+
toolBudget?: ToolBudgetState;
|
|
1451
|
+
toolBudgetBlocked?: boolean;
|
|
1452
|
+
sessionDir?: string;
|
|
1453
|
+
outputFile?: string;
|
|
1454
|
+
totalTokens?: TokenUsage;
|
|
1455
|
+
totalCost?: CostSummary;
|
|
1456
|
+
usageBudget?: UsageBudgetState;
|
|
1457
|
+
sessionFile?: string;
|
|
1458
|
+
controlEventCursor?: number;
|
|
1459
|
+
nestedRoute?: NestedRouteInfo;
|
|
1460
|
+
nestedChildren?: NestedRunSummary[];
|
|
1461
|
+
parentWorkflowRunId?: string;
|
|
1462
|
+
workflowKey?: string;
|
|
1463
|
+
workflow?: Details["workflow"];
|
|
1464
|
+
}
|
|
1465
|
+
|
|
1466
|
+
export interface ForegroundResumeChild {
|
|
1467
|
+
agent: string;
|
|
1468
|
+
index: number;
|
|
1469
|
+
context?: "fresh" | "fork";
|
|
1470
|
+
sessionFile?: string;
|
|
1471
|
+
model?: string;
|
|
1472
|
+
thinking?: string;
|
|
1473
|
+
status: SubagentResultStatus;
|
|
1474
|
+
activityState?: ActivityState;
|
|
1475
|
+
lastActivityAt?: number;
|
|
1476
|
+
currentTool?: string;
|
|
1477
|
+
currentToolStartedAt?: number;
|
|
1478
|
+
currentPath?: string;
|
|
1479
|
+
turnCount?: number;
|
|
1480
|
+
tokens?: number;
|
|
1481
|
+
toolCount?: number;
|
|
1482
|
+
exitCode?: number;
|
|
1483
|
+
error?: string;
|
|
1484
|
+
finalOutput?: string;
|
|
1485
|
+
outputState?: SubagentOutputState;
|
|
1486
|
+
outputMode?: OutputMode;
|
|
1487
|
+
savedOutputPath?: string;
|
|
1488
|
+
outputSaveError?: string;
|
|
1489
|
+
artifactPaths?: ArtifactPaths;
|
|
1490
|
+
transcriptPath?: string;
|
|
1491
|
+
transcriptError?: string;
|
|
1492
|
+
detachedReason?: string;
|
|
1493
|
+
acceptance?: AcceptanceLedger;
|
|
1494
|
+
agentContract?: AgentContract;
|
|
1495
|
+
launchContractDigest?: string;
|
|
1496
|
+
launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
|
|
1497
|
+
runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
|
|
1498
|
+
execution?: ExecutionProjection;
|
|
1499
|
+
review?: ReviewProjection;
|
|
1500
|
+
effects?: EffectsProjection;
|
|
1501
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1502
|
+
capabilityAudit?: SubagentCapabilityAudit;
|
|
1503
|
+
updatedAt?: number;
|
|
1504
|
+
}
|
|
1505
|
+
|
|
1506
|
+
export interface ForegroundResumeRun {
|
|
1507
|
+
runId: string;
|
|
1508
|
+
mode: SubagentRunMode;
|
|
1509
|
+
cwd: string;
|
|
1510
|
+
/** Originating parent session. Detached exits can outlive the active session. */
|
|
1511
|
+
sessionId?: string;
|
|
1512
|
+
updatedAt: number;
|
|
1513
|
+
checkpoint?: ChainCheckpointState;
|
|
1514
|
+
children: ForegroundResumeChild[];
|
|
1515
|
+
}
|
|
1516
|
+
|
|
1517
|
+
export interface ForegroundChildControl {
|
|
1518
|
+
index: number;
|
|
1519
|
+
agent: string;
|
|
1520
|
+
description?: string;
|
|
1521
|
+
startedAt: number;
|
|
1522
|
+
updatedAt: number;
|
|
1523
|
+
currentActivityState?: ActivityState;
|
|
1524
|
+
lastActivityAt?: number;
|
|
1525
|
+
currentTool?: string;
|
|
1526
|
+
currentToolStartedAt?: number;
|
|
1527
|
+
currentPath?: string;
|
|
1528
|
+
turnCount?: number;
|
|
1529
|
+
tokens?: number;
|
|
1530
|
+
inputTokens?: number;
|
|
1531
|
+
outputTokens?: number;
|
|
1532
|
+
model?: string;
|
|
1533
|
+
thinking?: string;
|
|
1534
|
+
toolCount?: number;
|
|
1535
|
+
interrupt?: () => boolean;
|
|
1536
|
+
detach?: () => boolean;
|
|
1537
|
+
}
|
|
1538
|
+
|
|
1539
|
+
export interface ForegroundRunControl {
|
|
1540
|
+
runId: string;
|
|
1541
|
+
/** Originating parent session; required for public fleet projection. */
|
|
1542
|
+
sessionId?: string;
|
|
1543
|
+
mode: SubagentRunMode;
|
|
1544
|
+
startedAt: number;
|
|
1545
|
+
updatedAt: number;
|
|
1546
|
+
/** Effective working directory used to resolve live transcript artifacts. */
|
|
1547
|
+
cwd?: string;
|
|
1548
|
+
currentAgent?: string;
|
|
1549
|
+
currentIndex?: number;
|
|
1550
|
+
/** Short caller-facing task/goal shown in fleet surfaces when available. */
|
|
1551
|
+
description?: string;
|
|
1552
|
+
currentActivityState?: ActivityState;
|
|
1553
|
+
lastActivityAt?: number;
|
|
1554
|
+
currentTool?: string;
|
|
1555
|
+
currentToolStartedAt?: number;
|
|
1556
|
+
currentPath?: string;
|
|
1557
|
+
turnCount?: number;
|
|
1558
|
+
tokens?: number;
|
|
1559
|
+
inputTokens?: number;
|
|
1560
|
+
outputTokens?: number;
|
|
1561
|
+
model?: string;
|
|
1562
|
+
thinking?: string;
|
|
1563
|
+
toolCount?: number;
|
|
1564
|
+
/** Independently tracked children for foreground parallel work and fleet inspection. */
|
|
1565
|
+
activeChildren?: Map<number, ForegroundChildControl>;
|
|
1566
|
+
/** Scheduling owners that may still launch another child. Removal is safe only at zero. */
|
|
1567
|
+
schedulingOwners?: number;
|
|
1568
|
+
nestedRoute?: NestedRouteInfo;
|
|
1569
|
+
nestedChildren?: NestedRunSummary[];
|
|
1570
|
+
interrupt?: () => boolean;
|
|
1571
|
+
detach?: () => boolean;
|
|
1572
|
+
}
|
|
1573
|
+
|
|
1574
|
+
export interface WaitSubscriptionRecord {
|
|
1575
|
+
version: 1;
|
|
1576
|
+
token: string;
|
|
1577
|
+
sessionId: string;
|
|
1578
|
+
targetKind: "async" | "foreground";
|
|
1579
|
+
runId: string;
|
|
1580
|
+
requestedId: string;
|
|
1581
|
+
createdAt: number;
|
|
1582
|
+
expiresAt: number;
|
|
1583
|
+
}
|
|
1584
|
+
|
|
1585
|
+
export interface SubagentState {
|
|
1586
|
+
baseCwd: string;
|
|
1587
|
+
currentSessionId: string | null;
|
|
1588
|
+
/** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
|
|
1589
|
+
artifactDirPreference?: ArtifactDirPreference;
|
|
1590
|
+
/** Runtime authority snapshot used by optional inspector controls. */
|
|
1591
|
+
authorityPolicy?: AuthorityPolicyConfig;
|
|
1592
|
+
/** Runtime mission-store snapshot used by optional inspector context. */
|
|
1593
|
+
missionStoreConfig?: MissionStoreConfig;
|
|
1594
|
+
parentSessionFile?: string | null;
|
|
1595
|
+
/** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
|
|
1596
|
+
lastParentModel?: { provider: string; id: string };
|
|
1597
|
+
subagentInProgress?: boolean;
|
|
1598
|
+
subagentSpawns?: {
|
|
1599
|
+
sessionId: string | null;
|
|
1600
|
+
count: number;
|
|
1601
|
+
configuredLimit?: number | null;
|
|
1602
|
+
granted?: number;
|
|
1603
|
+
grantHistory?: SpawnBudgetGrant[];
|
|
1604
|
+
};
|
|
1605
|
+
asyncJobs: Map<string, AsyncJobState>;
|
|
1606
|
+
/** Current-session active and recent async runs for the native fleet inspector. */
|
|
1607
|
+
fleetJobs?: Map<string, AsyncJobState>;
|
|
1608
|
+
/** Suppress dynamic status widgets while the fleet overlay owns the viewport. */
|
|
1609
|
+
fleetInspectorOpen?: boolean;
|
|
1610
|
+
foregroundRuns?: Map<string, ForegroundResumeRun>;
|
|
1611
|
+
foregroundControls: Map<string, ForegroundRunControl>;
|
|
1612
|
+
lastForegroundControlId: string | null;
|
|
1613
|
+
cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
|
|
1614
|
+
lastUiContext: ExtensionContext | null;
|
|
1615
|
+
poller: NodeJS.Timeout | null;
|
|
1616
|
+
completionSeen: Map<string, number>;
|
|
1617
|
+
/** Terminal result payloads observed by the result watcher, keyed by run id and pruned by the completion TTL. */
|
|
1618
|
+
completedResults?: Map<string, { seenAt: number; completion: WaitCompletion }>;
|
|
1619
|
+
watcher: FSWatcher | null;
|
|
1620
|
+
watcherRestartTimer: ReturnType<typeof setTimeout> | null;
|
|
1621
|
+
resultFileCoalescer: {
|
|
1622
|
+
schedule(file: string, delayMs?: number): boolean;
|
|
1623
|
+
clear(): void;
|
|
1624
|
+
};
|
|
1625
|
+
/** Current-session durable non-blocking wait registrations. */
|
|
1626
|
+
waitSubscriptions?: Map<string, WaitSubscriptionRecord>;
|
|
1627
|
+
/** Live in-process workflow controllers. Durable status remains on disk after settlement. */
|
|
1628
|
+
workflowControllers?: Map<string, AbortController>;
|
|
1629
|
+
}
|
|
1630
|
+
|
|
1631
|
+
// ============================================================================
|
|
1632
|
+
// Display
|
|
1633
|
+
// ============================================================================
|
|
1634
|
+
|
|
1635
|
+
export type DisplayItem =
|
|
1636
|
+
| { type: "text"; text: string }
|
|
1637
|
+
| { type: "tool"; name: string; args: Record<string, unknown> };
|
|
1638
|
+
|
|
1639
|
+
// ============================================================================
|
|
1640
|
+
// Error Handling
|
|
1641
|
+
// ============================================================================
|
|
1642
|
+
|
|
1643
|
+
export interface ErrorInfo {
|
|
1644
|
+
hasError: boolean;
|
|
1645
|
+
exitCode?: number;
|
|
1646
|
+
errorType?: string;
|
|
1647
|
+
details?: string;
|
|
1648
|
+
}
|
|
1649
|
+
|
|
1650
|
+
export interface IntercomEventBus {
|
|
1651
|
+
on(channel: string, handler: (data: unknown) => void): () => void;
|
|
1652
|
+
emit(channel: string, data: unknown): void;
|
|
1653
|
+
}
|
|
1654
|
+
|
|
1655
|
+
export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
|
|
1656
|
+
export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
|
|
1657
|
+
export const SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
|
|
1658
|
+
export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
|
|
1659
|
+
export const SUBAGENT_PROCESS_TERMINAL_EVENT = "subagent:process-terminal";
|
|
1660
|
+
export const SUBAGENT_FOREGROUND_COMPLETE_EVENT = "subagent:foreground-complete";
|
|
1661
|
+
export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
|
|
1662
|
+
export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
|
|
1663
|
+
export const SUBAGENT_STEERING_NOTICE_EVENT = "subagent:steering-notice";
|
|
1664
|
+
export const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
|
|
1665
|
+
export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
|
|
1666
|
+
|
|
1667
|
+
// ============================================================================
|
|
1668
|
+
// Execution Options
|
|
1669
|
+
// ============================================================================
|
|
1670
|
+
|
|
1671
|
+
export interface RunSyncOptions {
|
|
1672
|
+
/** Opt-in global permission rules; missing tools remain allowed. */
|
|
1673
|
+
permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
|
|
1674
|
+
/** Session id of the direct parent session for permission-system ask forwarding. */
|
|
1675
|
+
parentSessionId?: string;
|
|
1676
|
+
/** Resolved launch context for this child. */
|
|
1677
|
+
context?: "fresh" | "fork";
|
|
1678
|
+
cwd?: string;
|
|
1679
|
+
signal?: AbortSignal;
|
|
1680
|
+
interruptSignal?: AbortSignal;
|
|
1681
|
+
timeoutMs?: number;
|
|
1682
|
+
deadlineAt?: number;
|
|
1683
|
+
turnBudget?: ResolvedTurnBudget;
|
|
1684
|
+
usageBudget?: UsageBudgetConfig;
|
|
1685
|
+
/** Enforce maxTurns + graceTurns as a hard model-turn boundary. */
|
|
1686
|
+
enforceHardTurnLimit?: boolean;
|
|
1687
|
+
toolBudget?: ResolvedToolBudget;
|
|
1688
|
+
allowZeroToolBudget?: boolean;
|
|
1689
|
+
allowIntercomDetach?: boolean;
|
|
1690
|
+
intercomEvents?: IntercomEventBus;
|
|
1691
|
+
onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
|
|
1692
|
+
onControlEvent?: (event: ControlEvent) => void;
|
|
1693
|
+
/** Exposes a non-terminating detach callback while the child is active. */
|
|
1694
|
+
onDetachReady?: (detach: (reason?: string) => boolean) => void;
|
|
1695
|
+
/** Internal foreground receipt proposal; returns true only when the outer waiter accepted it. */
|
|
1696
|
+
onDetachReceipt?: (result: SingleResult) => boolean;
|
|
1697
|
+
/** Authoritative terminal result, emitted only after the full detached run finalizes. */
|
|
1698
|
+
onDetachedExit?: (result: SingleResult) => void;
|
|
1699
|
+
controlConfig?: ResolvedControlConfig;
|
|
1700
|
+
intercomSessionName?: string;
|
|
1701
|
+
orchestratorIntercomTarget?: string;
|
|
1702
|
+
maxOutput?: MaxOutputConfig;
|
|
1703
|
+
artifactsDir?: string;
|
|
1704
|
+
artifactConfig?: ArtifactConfig;
|
|
1705
|
+
runId: string;
|
|
1706
|
+
index?: number;
|
|
1707
|
+
sessionDir?: string;
|
|
1708
|
+
sessionFile?: string;
|
|
1709
|
+
share?: boolean;
|
|
1710
|
+
outputPath?: string;
|
|
1711
|
+
outputMode?: OutputMode;
|
|
1712
|
+
maxSubagentDepth?: number;
|
|
1713
|
+
/** Effective parent wait-tool setting propagated to the child runtime. */
|
|
1714
|
+
waitToolEnabled?: boolean;
|
|
1715
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
|
|
1716
|
+
nestedRoute?: NestedRouteInfo;
|
|
1717
|
+
/** Override the agent's default model (format: "provider/id" or just "id") */
|
|
1718
|
+
modelOverride?: string;
|
|
1719
|
+
/** Override the agent's default thinking level for this run */
|
|
1720
|
+
thinkingOverride?: AgentConfig["thinking"];
|
|
1721
|
+
/** Registry models available for heuristic bare-model resolution */
|
|
1722
|
+
availableModels?: Array<{ provider: string; id: string; fullId: string }>;
|
|
1723
|
+
/** Current parent-session provider to prefer for ambiguous bare model ids */
|
|
1724
|
+
preferredModelProvider?: string;
|
|
1725
|
+
/** Optional subagent model-scope enforcement for fallback candidates */
|
|
1726
|
+
modelScope?: ModelScopeConfig;
|
|
1727
|
+
/** Skills to make available (overrides agent default if provided) */
|
|
1728
|
+
skills?: string[];
|
|
1729
|
+
structuredOutput?: {
|
|
1730
|
+
schema: JsonSchemaObject;
|
|
1731
|
+
schemaPath: string;
|
|
1732
|
+
outputPath: string;
|
|
1733
|
+
};
|
|
1734
|
+
agentContract?: AgentContract;
|
|
1735
|
+
acceptance?: AcceptanceInput;
|
|
1736
|
+
acceptanceContext?: {
|
|
1737
|
+
mode?: SubagentRunMode;
|
|
1738
|
+
async?: boolean;
|
|
1739
|
+
dynamic?: boolean;
|
|
1740
|
+
dynamicGroup?: boolean;
|
|
1741
|
+
};
|
|
1742
|
+
}
|
|
1743
|
+
|
|
1744
|
+
export type IntercomBridgeMode = "off" | "fork-only" | "always";
|
|
1745
|
+
|
|
1746
|
+
export interface IntercomBridgeConfig {
|
|
1747
|
+
mode?: IntercomBridgeMode;
|
|
1748
|
+
instructionFile?: string;
|
|
1749
|
+
/** Deliver grouped completion messages through an external acknowledged intercom listener. */
|
|
1750
|
+
resultDelivery?: boolean;
|
|
1751
|
+
}
|
|
1752
|
+
|
|
1753
|
+
interface TopLevelParallelConfig {
|
|
1754
|
+
maxTasks?: number;
|
|
1755
|
+
concurrency?: number;
|
|
1756
|
+
}
|
|
1757
|
+
|
|
1758
|
+
interface ExtensionChainConfig {
|
|
1759
|
+
dynamicFanout?: {
|
|
1760
|
+
maxItems?: number;
|
|
1761
|
+
};
|
|
1762
|
+
}
|
|
1763
|
+
|
|
1764
|
+
export interface ProactiveSkillSubagentsConfig {
|
|
1765
|
+
enabled?: boolean;
|
|
1766
|
+
minReferences?: number;
|
|
1767
|
+
maxRecommendations?: number;
|
|
1768
|
+
preferredAgent?: string;
|
|
1769
|
+
}
|
|
1770
|
+
|
|
1771
|
+
export type ToolDescriptionMode = "full" | "compact" | "custom";
|
|
1772
|
+
export type InlineToolDisplay = "rich" | "summary";
|
|
1773
|
+
|
|
1774
|
+
export interface ScheduledRunsConfig {
|
|
1775
|
+
enabled?: boolean;
|
|
1776
|
+
maxPending?: number;
|
|
1777
|
+
/** Absolute or `~/` root for per-project durable schedules. */
|
|
1778
|
+
storeRoot?: string;
|
|
1779
|
+
}
|
|
1780
|
+
|
|
1781
|
+
export type FleetViewPlacement = "aboveEditor" | "belowEditor";
|
|
1782
|
+
|
|
1783
|
+
export interface ExtensionConfig {
|
|
1784
|
+
asyncByDefault?: boolean;
|
|
1785
|
+
/** Show the Claude Code-style navigable fleet. Defaults to true. */
|
|
1786
|
+
fleetView?: boolean;
|
|
1787
|
+
/** Place the persistent FleetView above or below the editor. Defaults to belowEditor. */
|
|
1788
|
+
fleetViewPlacement?: FleetViewPlacement;
|
|
1789
|
+
/** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
|
|
1790
|
+
asyncWidget?: boolean;
|
|
1791
|
+
/** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
|
|
1792
|
+
toolDescriptionMode?: ToolDescriptionMode;
|
|
1793
|
+
/** Inline chat rendering for the subagent tool. Defaults to rich. */
|
|
1794
|
+
inlineToolDisplay?: InlineToolDisplay;
|
|
1795
|
+
forceTopLevelAsync?: boolean;
|
|
1796
|
+
waitTool?: WaitToolConfig;
|
|
1797
|
+
defaultSessionDir?: string;
|
|
1798
|
+
singleRunOutputBaseDir?: string;
|
|
1799
|
+
maxSubagentDepth?: number;
|
|
1800
|
+
/** Optional cumulative session cap. Unset or 0 means unlimited. */
|
|
1801
|
+
maxSubagentSpawnsPerSession?: number;
|
|
1802
|
+
/** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
|
|
1803
|
+
globalConcurrencyLimit?: number;
|
|
1804
|
+
control?: ControlConfig;
|
|
1805
|
+
completionBatch?: CompletionBatchConfig;
|
|
1806
|
+
turnBudget?: TurnBudgetConfig;
|
|
1807
|
+
toolBudget?: ToolBudgetConfig;
|
|
1808
|
+
/** Opt-in native tool permissions. Bash remains outside this policy. */
|
|
1809
|
+
permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
|
|
1810
|
+
usageBudget?: UsageBudgetConfig;
|
|
1811
|
+
parallel?: TopLevelParallelConfig;
|
|
1812
|
+
chain?: ExtensionChainConfig;
|
|
1813
|
+
worktreeSetupHook?: string;
|
|
1814
|
+
worktreeSetupHookTimeoutMs?: number;
|
|
1815
|
+
worktreeBaseDir?: string;
|
|
1816
|
+
/** Where to store subagent artifact files. Defaults to "project" (cwd/.pi-subagents). Set to "session" for pi session dir, or "temp" for OS temp. */
|
|
1817
|
+
artifactDir?: ArtifactDirPreference;
|
|
1818
|
+
intercomBridge?: IntercomBridgeConfig;
|
|
1819
|
+
proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
|
|
1820
|
+
scheduledRuns?: ScheduledRunsConfig;
|
|
1821
|
+
/** Durable mission behavior. Missions are automatic by default; set enabled:false to disable auto-create. Explicit mission actions/fields still work. */
|
|
1822
|
+
missions?: MissionStoreConfig;
|
|
1823
|
+
/** Small fixed authority policy for the supported operational actions. */
|
|
1824
|
+
authorityPolicy?: AuthorityPolicyConfig;
|
|
1825
|
+
}
|
|
1826
|
+
|
|
1827
|
+
// ============================================================================
|
|
1828
|
+
// Constants
|
|
1829
|
+
// ============================================================================
|
|
1830
|
+
|
|
1831
|
+
export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
|
|
1832
|
+
bytes: 200 * 1024,
|
|
1833
|
+
lines: 5000,
|
|
1834
|
+
};
|
|
1835
|
+
|
|
1836
|
+
export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
|
|
1837
|
+
enabled: true,
|
|
1838
|
+
dir: "project",
|
|
1839
|
+
includeInput: true,
|
|
1840
|
+
includeOutput: true,
|
|
1841
|
+
includeJsonl: false,
|
|
1842
|
+
includeTranscript: true,
|
|
1843
|
+
includeMetadata: true,
|
|
1844
|
+
cleanupDays: 7,
|
|
1845
|
+
};
|
|
1846
|
+
|
|
1847
|
+
function sanitizeTempScopeSegment(value: string): string {
|
|
1848
|
+
const sanitized = value
|
|
1849
|
+
.trim()
|
|
1850
|
+
.replace(/[^A-Za-z0-9._-]+/g, "-")
|
|
1851
|
+
.replace(/^-+|-+$/g, "");
|
|
1852
|
+
return sanitized || "unknown";
|
|
1853
|
+
}
|
|
1854
|
+
|
|
1855
|
+
export function resolveTempScopeId(options?: {
|
|
1856
|
+
env?: NodeJS.ProcessEnv;
|
|
1857
|
+
getuid?: (() => number) | undefined;
|
|
1858
|
+
userInfo?: (() => { username?: string | null }) | undefined;
|
|
1859
|
+
homedir?: (() => string) | undefined;
|
|
1860
|
+
}): string {
|
|
1861
|
+
const env = options?.env ?? process.env;
|
|
1862
|
+
const getuid = options && Object.hasOwn(options, "getuid")
|
|
1863
|
+
? options.getuid
|
|
1864
|
+
: process.getuid?.bind(process);
|
|
1865
|
+
if (typeof getuid === "function") {
|
|
1866
|
+
return `uid-${getuid()}`;
|
|
1867
|
+
}
|
|
1868
|
+
|
|
1869
|
+
for (const key of ["USERNAME", "USER", "LOGNAME"] as const) {
|
|
1870
|
+
const value = env[key];
|
|
1871
|
+
if (value) return `user-${sanitizeTempScopeSegment(value)}`;
|
|
1872
|
+
}
|
|
1873
|
+
|
|
1874
|
+
const userInfo = options && Object.hasOwn(options, "userInfo")
|
|
1875
|
+
? options.userInfo
|
|
1876
|
+
: os.userInfo;
|
|
1877
|
+
try {
|
|
1878
|
+
const username = userInfo?.().username;
|
|
1879
|
+
if (username) return `user-${sanitizeTempScopeSegment(username)}`;
|
|
1880
|
+
} catch {
|
|
1881
|
+
// Fall through to home-directory-based scoping.
|
|
1882
|
+
}
|
|
1883
|
+
|
|
1884
|
+
const homedir = env.USERPROFILE ?? env.HOME;
|
|
1885
|
+
if (homedir) return `home-${sanitizeTempScopeSegment(homedir)}`;
|
|
1886
|
+
|
|
1887
|
+
const resolveHomedir = options && Object.hasOwn(options, "homedir")
|
|
1888
|
+
? options.homedir
|
|
1889
|
+
: os.homedir;
|
|
1890
|
+
try {
|
|
1891
|
+
const fallbackHomedir = resolveHomedir?.();
|
|
1892
|
+
if (fallbackHomedir) return `home-${sanitizeTempScopeSegment(fallbackHomedir)}`;
|
|
1893
|
+
} catch {
|
|
1894
|
+
// Fall through to the last-resort shared scope.
|
|
1895
|
+
}
|
|
1896
|
+
|
|
1897
|
+
return "shared";
|
|
1898
|
+
}
|
|
1899
|
+
|
|
1900
|
+
const MAX_PARALLEL = 8;
|
|
1901
|
+
export const MAX_CONCURRENCY = 4;
|
|
1902
|
+
export const TEMP_ROOT_DIR = path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
|
|
1903
|
+
export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
|
|
1904
|
+
export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
|
|
1905
|
+
export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
|
|
1906
|
+
export const TEMP_ARTIFACTS_DIR = path.join(TEMP_ROOT_DIR, "artifacts");
|
|
1907
|
+
|
|
1908
|
+
export const DIRS = {
|
|
1909
|
+
results: RESULTS_DIR,
|
|
1910
|
+
async: ASYNC_DIR,
|
|
1911
|
+
chain: CHAIN_RUNS_DIR,
|
|
1912
|
+
artifacts: TEMP_ARTIFACTS_DIR,
|
|
1913
|
+
};
|
|
1914
|
+
export const WIDGET_KEY = "subagent-async";
|
|
1915
|
+
export const SLASH_RESULT_TYPE = "subagent-slash-result";
|
|
1916
|
+
export const SLASH_TEXT_RESULT_TYPE = "subagent-slash-text-result";
|
|
1917
|
+
export const SLASH_SUBAGENT_REQUEST_EVENT = "subagent:slash:request";
|
|
1918
|
+
export const SLASH_SUBAGENT_STARTED_EVENT = "subagent:slash:started";
|
|
1919
|
+
export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
|
|
1920
|
+
export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
|
|
1921
|
+
export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
|
|
1922
|
+
export const POLL_INTERVAL_MS = 250;
|
|
1923
|
+
export const MAX_WIDGET_JOBS = 4;
|
|
1924
|
+
export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
|
|
1925
|
+
export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
|
|
1926
|
+
|
|
1927
|
+
export const DEFAULT_FORK_PREAMBLE =
|
|
1928
|
+
"You are a delegated subagent running from a fork of the parent session. " +
|
|
1929
|
+
"Treat the inherited conversation as reference-only context, not a live thread to continue. " +
|
|
1930
|
+
"Do not continue or answer prior messages as if they are waiting for a reply. " +
|
|
1931
|
+
"Your sole job is to execute the task below and return a focused result for that task using your tools.";
|
|
1932
|
+
|
|
1933
|
+
function normalizeTopLevelParallelValue(value: unknown): number | undefined {
|
|
1934
|
+
const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
|
|
1935
|
+
if (!Number.isInteger(parsed) || parsed < 1) return undefined;
|
|
1936
|
+
return parsed;
|
|
1937
|
+
}
|
|
1938
|
+
|
|
1939
|
+
export function resolveTopLevelParallelMaxTasks(value: unknown): number {
|
|
1940
|
+
return normalizeTopLevelParallelValue(value) ?? MAX_PARALLEL;
|
|
1941
|
+
}
|
|
1942
|
+
|
|
1943
|
+
export function resolveTopLevelParallelConcurrency(
|
|
1944
|
+
override: unknown,
|
|
1945
|
+
configValue: unknown,
|
|
1946
|
+
): number {
|
|
1947
|
+
return normalizeTopLevelParallelValue(override)
|
|
1948
|
+
?? normalizeTopLevelParallelValue(configValue)
|
|
1949
|
+
?? MAX_CONCURRENCY;
|
|
1950
|
+
}
|
|
1951
|
+
|
|
1952
|
+
export function getAsyncConfigPath(suffix: string): string {
|
|
1953
|
+
return path.join(TEMP_ROOT_DIR, `async-cfg-${suffix}.json`);
|
|
1954
|
+
}
|
|
1955
|
+
|
|
1956
|
+
export function wrapForkTask(task: string, preamble?: string | false): string {
|
|
1957
|
+
if (preamble === false) return task;
|
|
1958
|
+
const effectivePreamble = preamble ?? DEFAULT_FORK_PREAMBLE;
|
|
1959
|
+
const wrappedPrefix = `${effectivePreamble}\n\nTask:\n`;
|
|
1960
|
+
if (task.startsWith(wrappedPrefix)) return task;
|
|
1961
|
+
return `${wrappedPrefix}${task}`;
|
|
1962
|
+
}
|
|
1963
|
+
|
|
1964
|
+
// ============================================================================
|
|
1965
|
+
// Recursion Depth Guard
|
|
1966
|
+
// ============================================================================
|
|
1967
|
+
|
|
1968
|
+
function normalizeNonNegativeInteger(value: unknown): number | undefined {
|
|
1969
|
+
const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
|
|
1970
|
+
if (!Number.isInteger(parsed) || parsed < 0) return undefined;
|
|
1971
|
+
return parsed;
|
|
1972
|
+
}
|
|
1973
|
+
|
|
1974
|
+
export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
|
|
1975
|
+
return normalizeNonNegativeInteger(value);
|
|
1976
|
+
}
|
|
1977
|
+
|
|
1978
|
+
export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
|
|
1979
|
+
return normalizeMaxSubagentDepth(process.env.PI_SUBAGENT_MAX_DEPTH)
|
|
1980
|
+
?? normalizeMaxSubagentDepth(configMaxDepth)
|
|
1981
|
+
?? DEFAULT_SUBAGENT_MAX_DEPTH;
|
|
1982
|
+
}
|
|
1983
|
+
|
|
1984
|
+
export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDepth?: number): number {
|
|
1985
|
+
const normalizedParent = normalizeMaxSubagentDepth(parentMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
|
|
1986
|
+
const normalizedAgent = normalizeMaxSubagentDepth(agentMaxDepth);
|
|
1987
|
+
return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
|
|
1988
|
+
}
|
|
1989
|
+
|
|
1990
|
+
export function checkSubagentDepth(configMaxDepth?: number): { blocked: boolean; depth: number; maxDepth: number } {
|
|
1991
|
+
const depth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
|
|
1992
|
+
const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
|
|
1993
|
+
const blocked = Number.isFinite(depth) && depth >= maxDepth;
|
|
1994
|
+
return { blocked, depth, maxDepth };
|
|
1995
|
+
}
|
|
1996
|
+
|
|
1997
|
+
export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
|
|
1998
|
+
const parentDepth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
|
|
1999
|
+
const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
|
|
2000
|
+
return {
|
|
2001
|
+
PI_SUBAGENT_DEPTH: String(nextDepth),
|
|
2002
|
+
PI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
|
|
2003
|
+
};
|
|
2004
|
+
}
|
|
2005
|
+
|
|
2006
|
+
export function normalizeMaxSubagentSpawnsPerSession(value: unknown): number | undefined {
|
|
2007
|
+
return normalizeNonNegativeInteger(value);
|
|
2008
|
+
}
|
|
2009
|
+
|
|
2010
|
+
export function resolveMaxSubagentSpawnsPerSession(configMaxSpawns?: number): number | undefined {
|
|
2011
|
+
const envMaxSpawns = normalizeMaxSubagentSpawnsPerSession(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_SESSION);
|
|
2012
|
+
if (envMaxSpawns !== undefined) return envMaxSpawns === 0 ? undefined : envMaxSpawns;
|
|
2013
|
+
const configuredMaxSpawns = normalizeMaxSubagentSpawnsPerSession(configMaxSpawns);
|
|
2014
|
+
return configuredMaxSpawns === 0 ? undefined : configuredMaxSpawns;
|
|
2015
|
+
}
|
|
2016
|
+
|
|
2017
|
+
// ============================================================================
|
|
2018
|
+
// Utility Functions
|
|
2019
|
+
// ============================================================================
|
|
2020
|
+
|
|
2021
|
+
function formatBytes(bytes: number): string {
|
|
2022
|
+
if (bytes < 1024) return `${bytes}B`;
|
|
2023
|
+
if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
|
|
2024
|
+
return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
|
|
2025
|
+
}
|
|
2026
|
+
|
|
2027
|
+
export function truncateOutput(
|
|
2028
|
+
output: string,
|
|
2029
|
+
config: Required<MaxOutputConfig>,
|
|
2030
|
+
artifactPath?: string,
|
|
2031
|
+
): TruncationResult {
|
|
2032
|
+
const lines = output.split("\n");
|
|
2033
|
+
const bytes = Buffer.byteLength(output, "utf-8");
|
|
2034
|
+
|
|
2035
|
+
if (bytes <= config.bytes && lines.length <= config.lines) {
|
|
2036
|
+
return { text: output, truncated: false };
|
|
2037
|
+
}
|
|
2038
|
+
|
|
2039
|
+
let truncatedLines = lines;
|
|
2040
|
+
if (lines.length > config.lines) {
|
|
2041
|
+
truncatedLines = lines.slice(0, config.lines);
|
|
2042
|
+
}
|
|
2043
|
+
|
|
2044
|
+
let result = truncatedLines.join("\n");
|
|
2045
|
+
if (Buffer.byteLength(result, "utf-8") > config.bytes) {
|
|
2046
|
+
let low = 0;
|
|
2047
|
+
let high = result.length;
|
|
2048
|
+
while (low < high) {
|
|
2049
|
+
const mid = Math.floor((low + high + 1) / 2);
|
|
2050
|
+
if (Buffer.byteLength(result.slice(0, mid), "utf-8") <= config.bytes) {
|
|
2051
|
+
low = mid;
|
|
2052
|
+
} else {
|
|
2053
|
+
high = mid - 1;
|
|
2054
|
+
}
|
|
2055
|
+
}
|
|
2056
|
+
result = result.slice(0, low);
|
|
2057
|
+
}
|
|
2058
|
+
|
|
2059
|
+
const keptLines = result.split("\n").length;
|
|
2060
|
+
const marker = `[TRUNCATED: showing first ${keptLines} of ${lines.length} lines, ${formatBytes(Buffer.byteLength(result))} of ${formatBytes(bytes)}${artifactPath ? ` - full output at ${artifactPath}` : ""}]\n`;
|
|
2061
|
+
|
|
2062
|
+
return {
|
|
2063
|
+
text: marker + result,
|
|
2064
|
+
truncated: true,
|
|
2065
|
+
originalBytes: bytes,
|
|
2066
|
+
originalLines: lines.length,
|
|
2067
|
+
artifactPath,
|
|
2068
|
+
};
|
|
2069
|
+
}
|