@xzzpig/pi-subagents 0.8.0 → 0.10.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 +477 -0
- package/README.md +2 -2
- package/agents/claude-code-writer.md +15 -0
- package/agents/claude-code.md +15 -0
- package/agents/codex-exec-writer.md +15 -0
- package/agents/codex-exec.md +15 -0
- package/agents/cursor-agent-writer.md +14 -0
- package/agents/cursor-agent.md +14 -0
- package/agents/reviewer.md +1 -1
- package/agents/scout.md +1 -1
- package/docs/agents.md +195 -39
- package/docs/configuration.md +81 -22
- package/docs/extension-api.md +69 -14
- package/docs/missions.md +2 -0
- package/docs/models.md +32 -9
- package/docs/observability.md +22 -20
- package/docs/tool-reference.md +123 -14
- package/docs/watchdog.md +92 -114
- package/docs/workflows.md +142 -4
- package/install.mjs +1 -1
- package/package.json +7 -6
- package/prompts/review-loop.md +2 -2
- package/skills/council-mode/SKILL.md +48 -243
- package/skills/council-mode/references/pass-contracts.md +150 -0
- package/skills/pi-subagents/SKILL.md +89 -35
- package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
- package/skills/pi-subagents/references/execution-controls.md +91 -15
- package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
- package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
- package/skills/pi-subagents/references/review-and-validation.md +73 -0
- package/src/agents/agent-management.ts +384 -115
- package/src/agents/agent-refinements.ts +4 -4
- package/src/agents/agent-serializer.ts +14 -2
- package/src/agents/agents.ts +935 -372
- package/src/agents/builtin-names.ts +6 -0
- package/src/agents/runtime-agent-events.ts +70 -0
- package/src/agents/runtime-agent-registry.ts +42 -21
- package/src/api/agents.ts +10 -5
- package/src/api/background-work.ts +12 -3
- package/src/api/capability-ceiling.ts +0 -1
- package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
- package/src/api/delegation.ts +0 -7
- package/src/api/external-runs.ts +67 -4
- package/src/api/preflight.ts +77 -21
- package/src/api/shared-types.ts +6 -0
- package/src/extension/config.ts +90 -0
- package/src/extension/doctor.ts +5 -13
- package/src/extension/fanout-child.ts +14 -14
- package/src/extension/index.ts +115 -37
- package/src/extension/public-execution.ts +103 -15
- package/src/extension/rpc.ts +120 -25
- package/src/extension/schemas.ts +65 -29
- package/src/extension/tool-description.ts +48 -26
- package/src/inspectors/herdr/actions.ts +2 -1
- package/src/inspectors/herdr/inspector-runner.ts +21 -23
- package/src/inspectors/herdr/session-roots-codec.ts +42 -0
- package/src/integrations/herdr-status.ts +51 -3
- package/src/intercom/native-supervisor-channel.ts +138 -60
- package/src/intercom/result-intercom.ts +7 -0
- package/src/intercom/supervisor-ui.ts +243 -0
- package/src/profiles/profiles.ts +5 -6
- package/src/runs/background/active-async-capacity.ts +103 -18
- package/src/runs/background/async-execution.ts +417 -133
- package/src/runs/background/async-job-tracker.ts +95 -15
- package/src/runs/background/async-resume.ts +60 -28
- package/src/runs/background/async-retention.ts +20 -3
- package/src/runs/background/async-status-snapshot.ts +23 -261
- package/src/runs/background/async-status.ts +204 -14
- package/src/runs/background/auto-drain.ts +1 -1
- package/src/runs/background/chain-append.ts +8 -3
- package/src/runs/background/chain-root-attachment.ts +74 -8
- package/src/runs/background/control-channel.ts +4 -205
- package/src/runs/background/fleet-view.ts +38 -22
- package/src/runs/background/inspect-rpc.ts +8 -8
- package/src/runs/background/notify.ts +238 -12
- package/src/runs/background/process-terminal.ts +16 -0
- package/src/runs/background/result-delivery-ownership.ts +45 -0
- package/src/runs/background/result-files.ts +28 -14
- package/src/runs/background/result-watcher.ts +39 -16
- package/src/runs/background/resume-guidance.ts +2 -2
- package/src/runs/background/retained-children.ts +1 -1
- package/src/runs/background/run-child-session.ts +613 -0
- package/src/runs/background/run-status.ts +84 -17
- package/src/runs/background/runner-aliases.ts +125 -0
- package/src/runs/background/runner-child-sessions.ts +31 -0
- package/src/runs/background/scheduled-runs.ts +174 -18
- package/src/runs/background/stale-run-reconciler.ts +10 -4
- package/src/runs/background/steering.ts +8 -15
- package/src/runs/background/subagent-runner.ts +718 -1161
- package/src/runs/background/subagent-wait.ts +86 -31
- package/src/runs/background/terminal-run-index.ts +1 -1
- package/src/runs/background/wait-completions.ts +43 -2
- package/src/runs/background/wait-config.ts +23 -9
- package/src/runs/background/wait-tool.ts +26 -19
- package/src/runs/foreground/async-steering-action.ts +3 -19
- package/src/runs/foreground/execution.ts +489 -499
- package/src/runs/foreground/foreground-control.ts +13 -0
- package/src/runs/foreground/foreground-history.ts +23 -1
- package/src/runs/foreground/subagent-executor.ts +1223 -402
- package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
- package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
- package/src/runs/shared/abort-recovery.ts +119 -0
- package/src/runs/shared/acceptance.ts +138 -36
- package/src/runs/shared/async-status-projection.ts +565 -0
- package/src/runs/shared/background-process-options.ts +9 -0
- package/src/runs/shared/capability-ceiling.ts +2 -2
- package/src/runs/shared/child-hooks.ts +25 -0
- package/src/runs/shared/child-identity.ts +32 -6
- package/src/runs/shared/child-launch-plan.ts +151 -0
- package/src/runs/shared/child-launch.ts +364 -0
- package/src/runs/shared/child-lifecycle.ts +25 -0
- package/src/runs/shared/child-runtime-config.ts +126 -0
- package/src/runs/shared/child-session.ts +366 -0
- package/src/runs/shared/child-tool-plan.ts +632 -0
- package/src/runs/shared/claude-code-adapter.ts +133 -0
- package/src/runs/shared/codex-exec-adapter.ts +129 -0
- package/src/runs/shared/completion-evidence.ts +89 -0
- package/src/runs/shared/completion-guard.ts +6 -5
- package/src/runs/shared/cursor-agent-adapter.ts +114 -0
- package/src/runs/shared/dynamic-fanout.ts +3 -3
- package/src/runs/shared/external-cli-contract.ts +167 -0
- package/src/runs/shared/external-cli-preflight.ts +138 -0
- package/src/runs/shared/external-cli-runner.ts +348 -55
- package/src/runs/shared/fast-mode-extension.ts +5 -5
- package/src/runs/shared/host-step-status.ts +231 -0
- package/src/runs/shared/lane-metadata.ts +126 -0
- package/src/runs/shared/launch-cwd.ts +16 -0
- package/src/runs/shared/long-running-guard.ts +2 -1
- package/src/runs/shared/mcp-config-sources.ts +422 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
- package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
- package/src/runs/shared/model-exclusions.ts +139 -9
- package/src/runs/shared/model-fallback.ts +146 -14
- package/src/runs/shared/mutation-evidence.ts +57 -3
- package/src/runs/shared/nested-events.ts +99 -77
- package/src/runs/shared/nested-path.ts +0 -14
- package/src/runs/shared/nested-render.ts +9 -5
- package/src/runs/shared/orca-progress-tabs.ts +12 -7
- package/src/runs/shared/parallel-handoff.ts +423 -7
- package/src/runs/shared/parallel-utils.ts +20 -7
- package/src/runs/shared/permissions.ts +1 -14
- package/src/runs/shared/pi-spawn.ts +69 -35
- package/src/runs/shared/process-signal.ts +16 -0
- package/src/runs/shared/run-fanout-budget.ts +0 -13
- package/src/runs/shared/run-history.ts +21 -1
- package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
- package/src/runs/shared/sandbox-profile-guard.ts +85 -0
- package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
- package/src/runs/shared/single-output.ts +89 -22
- package/src/runs/shared/structured-output.ts +49 -9
- package/src/runs/shared/subagent-control.ts +6 -2
- package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
- package/src/runs/shared/task-intent.ts +21 -7
- package/src/runs/shared/tool-availability.ts +18 -62
- package/src/runs/shared/tool-budget.ts +0 -14
- package/src/runs/shared/tool-timeout.ts +1 -1
- package/src/runs/shared/workflow-graph.ts +16 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
- package/src/runs/shared/worktree.ts +571 -62
- package/src/shared/atomic-json.ts +3 -1
- package/src/shared/child-session-name.ts +46 -0
- package/src/shared/extension-context.ts +24 -0
- package/src/shared/fork-context.ts +21 -12
- package/src/shared/fork-session-cwd.ts +27 -0
- package/src/shared/formatters.ts +18 -3
- package/src/shared/jsonl-writer.ts +11 -0
- package/src/shared/launch-contract.ts +11 -1
- package/src/shared/pruned-fork.ts +450 -0
- package/src/shared/sandbox-profile.ts +23 -0
- package/src/shared/session-file-trust.ts +19 -0
- package/src/shared/session-tokens.ts +14 -3
- package/src/shared/settings.ts +19 -105
- package/src/shared/shortcuts.ts +17 -0
- package/src/shared/thinking-ceiling.ts +0 -6
- package/src/shared/types.ts +545 -70
- package/src/shared/utils.ts +60 -93
- package/src/shared/workflow-child-permit.ts +207 -0
- package/src/slash/delegation-adapters.ts +1 -9
- package/src/slash/delegation-request.ts +0 -4
- package/src/slash/prompt-template-bridge.ts +37 -1
- package/src/slash/slash-bridge.ts +1 -2
- package/src/slash/slash-commands.ts +383 -116
- package/src/slash/slash-live-state.ts +22 -11
- package/src/slash/subagents-admin.ts +29 -12
- package/src/tui/fleet-native-transcript.ts +4 -0
- package/src/tui/fleet-status.ts +217 -82
- package/src/tui/fleet-transcript.ts +11 -5
- package/src/tui/fleet.ts +54 -28
- package/src/tui/render-helpers.ts +31 -0
- package/src/tui/render.ts +1429 -163
- package/src/watchdog/change-signature.ts +40 -1
- package/src/watchdog/child-status.ts +54 -34
- package/src/watchdog/diff-tool.ts +77 -0
- package/src/watchdog/emission-guard.ts +5 -3
- package/src/watchdog/guidance.ts +20 -0
- package/src/watchdog/register-child.ts +28 -25
- package/src/watchdog/register-main.ts +10 -9
- package/src/watchdog/render.ts +4 -5
- package/src/watchdog/review.ts +15 -4
- package/src/watchdog/rules.ts +70 -0
- package/src/watchdog/runtime.ts +75 -92
- package/src/watchdog/scope.ts +0 -11
- package/src/watchdog/settings.ts +48 -104
- package/src/watchdog/turn-delta.ts +1 -1
- package/src/watchdog/types.ts +18 -32
- package/src/watchdog/warning-format.ts +0 -1
- package/src/workflows/chat-progress.ts +7 -3
- package/src/workflows/host-command.ts +235 -0
- package/src/workflows/scripted-workflow.ts +988 -59
- package/src/workflows/workflow-checklist.ts +439 -0
- package/src/workflows/workflow-child-summary.ts +121 -0
- package/src/workflows/workflow-preflight.ts +297 -0
- package/src/workflows/workflow-receipt.ts +232 -6
- package/src/workflows/workflow-resources.ts +150 -0
- package/src/workflows/workflow-settlement.ts +246 -0
- package/src/runs/shared/child-protocol.ts +0 -401
- package/src/runs/shared/pi-args.ts +0 -935
- package/src/runs/shared/subagent-startup-retry.ts +0 -116
- package/src/runs/shared/turn-budget.ts +0 -98
- package/src/shared/post-exit-stdio-guard.ts +0 -85
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
ExternalCliReceiptMetadata,
|
|
3
|
+
ExternalCliCapabilityNarrowing,
|
|
4
|
+
ExternalCliRunnerStatus,
|
|
5
|
+
ExternalProcessStatus,
|
|
6
|
+
} from "../../shared/types.ts";
|
|
7
|
+
|
|
8
|
+
const UNSUPPORTED = {
|
|
9
|
+
steer: "The one-shot stdin adapter closes input after launch and cannot accept live steer messages.",
|
|
10
|
+
resume: "The one-shot stdin adapter has no durable external session identity.",
|
|
11
|
+
structuredOutput: "The generic external CLI adapter does not parse a trusted structured result.",
|
|
12
|
+
toolEvents: "The generic external CLI adapter treats stdout as untrusted text, not native Pi tool events.",
|
|
13
|
+
supervisor: "The generic external CLI adapter has no trusted supervisor event transport.",
|
|
14
|
+
forkContext: "Native Pi fork context is not available without an adapter-owned handoff artifact.",
|
|
15
|
+
extensionBindings: "Native Pi extension bindings are never passed to external runners.",
|
|
16
|
+
} as const;
|
|
17
|
+
|
|
18
|
+
const CAPABILITY_KEYS = new Set(Object.keys(UNSUPPORTED));
|
|
19
|
+
const PROMPT_FILE_UNSUPPORTED = {
|
|
20
|
+
...UNSUPPORTED,
|
|
21
|
+
steer: "The one-shot prompt-file adapter closes input after launch and cannot accept live steer messages.",
|
|
22
|
+
resume: "The one-shot prompt-file adapter does not retain a durable external session identity.",
|
|
23
|
+
} as const;
|
|
24
|
+
|
|
25
|
+
export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS = [
|
|
26
|
+
"codex-exec",
|
|
27
|
+
"codex-exec-writer",
|
|
28
|
+
"claude-code",
|
|
29
|
+
"claude-code-writer",
|
|
30
|
+
"cursor-agent",
|
|
31
|
+
"cursor-agent-writer",
|
|
32
|
+
] as const;
|
|
33
|
+
export type CodeOwnedExternalCliAdapterId = typeof CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS[number];
|
|
34
|
+
|
|
35
|
+
const CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET = new Set<string>(CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS);
|
|
36
|
+
export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL = CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS.map((id) => `'${id}'`).join(", ");
|
|
37
|
+
|
|
38
|
+
export function isCodeOwnedExternalCliAdapterId(value: unknown): value is CodeOwnedExternalCliAdapterId {
|
|
39
|
+
return typeof value === "string" && CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET.has(value);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
const RESERVED_READ_ONLY_ADAPTERS = [
|
|
43
|
+
{ name: "claude-code", writer: "claude-code-writer", access: "file-write" },
|
|
44
|
+
{ name: "codex-exec", writer: "codex-exec-writer", access: "workspace-write" },
|
|
45
|
+
{ name: "cursor-agent", writer: "cursor-agent-writer", access: "workspace-write" },
|
|
46
|
+
] as const;
|
|
47
|
+
|
|
48
|
+
export function validateCodeOwnedProfileRunner(
|
|
49
|
+
agent: {
|
|
50
|
+
name: string;
|
|
51
|
+
localName?: string;
|
|
52
|
+
aliases?: readonly string[];
|
|
53
|
+
runner?: { type: string; adapter?: string };
|
|
54
|
+
},
|
|
55
|
+
): string | undefined {
|
|
56
|
+
const selectionNames = [agent.name, ...(agent.localName ? [agent.localName] : []), ...(agent.aliases ?? [])];
|
|
57
|
+
for (const adapter of RESERVED_READ_ONLY_ADAPTERS) {
|
|
58
|
+
if (selectionNames.includes(adapter.name) && !(agent.runner?.type === "external-cli" && agent.runner.adapter === adapter.name)) {
|
|
59
|
+
return `Selection name '${adapter.name}' is reserved for the read-only '${adapter.name}' adapter. Use '${adapter.writer}' for explicit ${adapter.access} access.`;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return undefined;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export function parseExternalCliCapabilityNarrowing(value: unknown, label: string): ExternalCliCapabilityNarrowing | undefined {
|
|
66
|
+
if (value === undefined) return undefined;
|
|
67
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
|
|
68
|
+
const input = value as Record<string, unknown>;
|
|
69
|
+
const unknown = Object.keys(input).filter((key) => !CAPABILITY_KEYS.has(key));
|
|
70
|
+
if (unknown.length > 0) throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
|
|
71
|
+
for (const [key, setting] of Object.entries(input)) {
|
|
72
|
+
if (setting !== false) throw new Error(`${label}.${key} may only be false; user config cannot widen code-owned external adapter capabilities.`);
|
|
73
|
+
}
|
|
74
|
+
return input as ExternalCliCapabilityNarrowing;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export function resolveExternalCliRunnerStatus(input: {
|
|
78
|
+
adapter?: CodeOwnedExternalCliAdapterId;
|
|
79
|
+
command: string;
|
|
80
|
+
args?: string[];
|
|
81
|
+
promptDelivery?: "stdin";
|
|
82
|
+
capabilities?: ExternalCliCapabilityNarrowing;
|
|
83
|
+
}): ExternalCliRunnerStatus {
|
|
84
|
+
const codexExec = input.adapter === "codex-exec";
|
|
85
|
+
const codexExecWriter = input.adapter === "codex-exec-writer";
|
|
86
|
+
const claudeCode = input.adapter === "claude-code";
|
|
87
|
+
const claudeCodeWriter = input.adapter === "claude-code-writer";
|
|
88
|
+
const cursorAgent = input.adapter === "cursor-agent";
|
|
89
|
+
const cursorAgentWriter = input.adapter === "cursor-agent-writer";
|
|
90
|
+
const cursor = cursorAgent || cursorAgentWriter;
|
|
91
|
+
const unsupported = cursor ? PROMPT_FILE_UNSUPPORTED : UNSUPPORTED;
|
|
92
|
+
return {
|
|
93
|
+
type: "external-cli",
|
|
94
|
+
command: input.command,
|
|
95
|
+
args: input.args ?? [],
|
|
96
|
+
promptDelivery: cursor ? "prompt-file" : input.promptDelivery ?? "stdin",
|
|
97
|
+
adapter: { id: input.adapter ?? "external-cli", version: 1, executionMode: cursor ? "one-shot-prompt-file" : "one-shot-stdin" },
|
|
98
|
+
...(codexExec ? { safety: { sandbox: "read-only" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
|
|
99
|
+
...(codexExecWriter ? { safety: { access: "workspace-write" as const, sandbox: "workspace-write" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
|
|
100
|
+
...(claudeCode ? { safety: { access: "read-only" as const, authentication: "existing-cli-required" as const, permissionMode: "plan" as const, tools: "none" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
|
|
101
|
+
...(claudeCodeWriter ? { safety: { access: "workspace-write" as const, authentication: "existing-cli-required" as const, permissionMode: "acceptEdits" as const, tools: "Read,Write,Edit,Glob,Grep" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
|
|
102
|
+
...(cursorAgent ? { safety: { access: "read-only" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "ask" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
|
|
103
|
+
...(cursorAgentWriter ? { safety: { access: "workspace-write" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "print" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
|
|
104
|
+
capabilities: {
|
|
105
|
+
stop: true,
|
|
106
|
+
steer: false,
|
|
107
|
+
resume: false,
|
|
108
|
+
structuredOutput: false,
|
|
109
|
+
toolEvents: false,
|
|
110
|
+
supervisor: "unsupported",
|
|
111
|
+
forkContext: false,
|
|
112
|
+
extensionBindings: false,
|
|
113
|
+
},
|
|
114
|
+
unsupportedReasons: unsupported,
|
|
115
|
+
nonResumableReason: unsupported.resume,
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRunnerStatus | undefined {
|
|
120
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
|
|
121
|
+
const input = value as Record<string, unknown>;
|
|
122
|
+
if (input.type !== "external-cli" || typeof input.command !== "string" || !input.command.trim()) return undefined;
|
|
123
|
+
const args = Array.isArray(input.args) && input.args.every((arg) => typeof arg === "string")
|
|
124
|
+
? input.args
|
|
125
|
+
: undefined;
|
|
126
|
+
const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
|
|
127
|
+
const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter)
|
|
128
|
+
? (input.adapter as Record<string, unknown>).id
|
|
129
|
+
: undefined;
|
|
130
|
+
if (adapterId === "grok-build") {
|
|
131
|
+
return {
|
|
132
|
+
type: "external-cli",
|
|
133
|
+
command: input.command,
|
|
134
|
+
args: args ?? [],
|
|
135
|
+
promptDelivery: "prompt-file",
|
|
136
|
+
adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
|
|
137
|
+
capabilities: { stop: true, steer: false, resume: false, structuredOutput: false, toolEvents: false, supervisor: "unsupported", forkContext: false, extensionBindings: false },
|
|
138
|
+
unsupportedReasons: PROMPT_FILE_UNSUPPORTED,
|
|
139
|
+
nonResumableReason: PROMPT_FILE_UNSUPPORTED.resume,
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
|
|
143
|
+
return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}) });
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export function externalCliReceiptMetadata(input: {
|
|
147
|
+
runner: ExternalCliRunnerStatus;
|
|
148
|
+
externalProcess?: ExternalProcessStatus;
|
|
149
|
+
outputReference?: string;
|
|
150
|
+
}): ExternalCliReceiptMetadata {
|
|
151
|
+
const { runner } = input;
|
|
152
|
+
return {
|
|
153
|
+
adapter: { ...runner.adapter },
|
|
154
|
+
capabilities: { ...runner.capabilities },
|
|
155
|
+
...(runner.safety ? { safety: { ...runner.safety } } : {}),
|
|
156
|
+
...(input.externalProcess ? {
|
|
157
|
+
outputArtifacts: {
|
|
158
|
+
stdoutPath: input.externalProcess.stdoutPath,
|
|
159
|
+
stderrPath: input.externalProcess.stderrPath,
|
|
160
|
+
...(input.outputReference || input.externalProcess.finalOutputPath ? { finalOutputPath: input.outputReference ?? input.externalProcess.finalOutputPath } : {}),
|
|
161
|
+
},
|
|
162
|
+
} : input.outputReference ? { outputArtifacts: { finalOutputPath: input.outputReference } } : {}),
|
|
163
|
+
handoff: { mode: "fresh" },
|
|
164
|
+
supervisor: { mode: "unsupported", reason: runner.unsupportedReasons.supervisor },
|
|
165
|
+
nonResumableReason: runner.nonResumableReason,
|
|
166
|
+
};
|
|
167
|
+
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
2
|
+
import * as fs from "node:fs";
|
|
3
|
+
import * as path from "node:path";
|
|
4
|
+
|
|
5
|
+
const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
|
|
6
|
+
const MAX_PROBE_TIMEOUT_MS = 5_000;
|
|
7
|
+
const MAX_CACHE_ENTRIES = 64;
|
|
8
|
+
const MAX_AVAILABILITY_REASON_LENGTH = 256;
|
|
9
|
+
|
|
10
|
+
export type ExternalCliPreflightInvalidationReason = "launch" | "auth" | "parser" | "permission";
|
|
11
|
+
|
|
12
|
+
export interface ExternalCliPreflightSpec {
|
|
13
|
+
id: string;
|
|
14
|
+
versionArgs: readonly string[];
|
|
15
|
+
helpArgs: readonly string[];
|
|
16
|
+
evidenceArgs?: readonly string[];
|
|
17
|
+
evidenceLabel?: string;
|
|
18
|
+
probeTimeoutMs?: number;
|
|
19
|
+
validate?: (result: ExternalCliPreflightResult) => void;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface ExternalCliPreflightResult {
|
|
23
|
+
binaryPath: string;
|
|
24
|
+
binaryMtimeMs: number;
|
|
25
|
+
version: string;
|
|
26
|
+
help: string;
|
|
27
|
+
evidence?: string;
|
|
28
|
+
cacheHit: boolean;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
type CachedPreflight = Omit<ExternalCliPreflightResult, "cacheHit">;
|
|
32
|
+
|
|
33
|
+
const cache = new Map<string, CachedPreflight>();
|
|
34
|
+
const lookup = new Map<string, string>();
|
|
35
|
+
|
|
36
|
+
export type ExternalCliBinaryAvailability =
|
|
37
|
+
| { available: true }
|
|
38
|
+
| { available: false; unavailableReason: string };
|
|
39
|
+
|
|
40
|
+
function resolveBinary(command: string, env: NodeJS.ProcessEnv): string {
|
|
41
|
+
if (path.isAbsolute(command) || command.includes(path.sep)) {
|
|
42
|
+
const resolved = path.resolve(command);
|
|
43
|
+
fs.accessSync(resolved, fs.constants.X_OK);
|
|
44
|
+
return resolved;
|
|
45
|
+
}
|
|
46
|
+
const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
|
|
47
|
+
for (const directory of (env.PATH ?? "").split(path.delimiter)) {
|
|
48
|
+
if (!directory) continue;
|
|
49
|
+
for (const extension of extensions) {
|
|
50
|
+
const candidate = path.join(directory, `${command}${extension}`);
|
|
51
|
+
try {
|
|
52
|
+
fs.accessSync(candidate, fs.constants.X_OK);
|
|
53
|
+
return fs.realpathSync(candidate);
|
|
54
|
+
} catch {}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
throw new Error(`External CLI binary '${command}' was not found on PATH.`);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Resolve only the configured command; unlike preflight, this never starts a child process. */
|
|
61
|
+
export function resolveExternalCliBinaryAvailability(command: string, env: NodeJS.ProcessEnv): ExternalCliBinaryAvailability {
|
|
62
|
+
try {
|
|
63
|
+
resolveBinary(command, env);
|
|
64
|
+
return { available: true };
|
|
65
|
+
} catch (error) {
|
|
66
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
67
|
+
return { available: false, unavailableReason: reason.slice(0, MAX_AVAILABILITY_REASON_LENGTH) };
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function probeWithTimeout(binaryPath: string, args: readonly string[], env: NodeJS.ProcessEnv, label: string, timeoutMs: number, cwd?: string): string {
|
|
72
|
+
const result = spawnSync(binaryPath, [...args], {
|
|
73
|
+
cwd,
|
|
74
|
+
env,
|
|
75
|
+
encoding: "utf-8",
|
|
76
|
+
killSignal: "SIGKILL",
|
|
77
|
+
maxBuffer: MAX_PROBE_OUTPUT_BYTES,
|
|
78
|
+
timeout: timeoutMs,
|
|
79
|
+
windowsHide: true,
|
|
80
|
+
});
|
|
81
|
+
if (result.error) throw new Error(`External CLI ${label} preflight failed: ${result.error.message}`, { cause: result.error });
|
|
82
|
+
if (result.status !== 0) throw new Error(`External CLI ${label} preflight exited with code ${result.status}: ${(result.stderr || result.stdout).trim()}`);
|
|
83
|
+
return result.stdout.trim();
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
function narrowPositiveInteger(value: number | undefined, ceiling: number, label: string): number {
|
|
87
|
+
if (value === undefined) return ceiling;
|
|
88
|
+
if (!Number.isSafeInteger(value) || value <= 0 || value > ceiling) throw new Error(`${label} may only narrow the code-owned ceiling of ${ceiling}.`);
|
|
89
|
+
return value;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function specKey(spec: ExternalCliPreflightSpec): string {
|
|
93
|
+
return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export function preflightExternalCli(command: string, spec: ExternalCliPreflightSpec, env: NodeJS.ProcessEnv, cwd?: string): ExternalCliPreflightResult {
|
|
97
|
+
const binaryPath = resolveBinary(command, env);
|
|
98
|
+
const binaryMtimeMs = fs.statSync(binaryPath).mtimeMs;
|
|
99
|
+
const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
|
|
100
|
+
const cachedKey = lookup.get(lookupKey);
|
|
101
|
+
const cached = cachedKey ? cache.get(cachedKey) : undefined;
|
|
102
|
+
const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
|
|
103
|
+
const base = cached ?? {
|
|
104
|
+
binaryPath,
|
|
105
|
+
binaryMtimeMs,
|
|
106
|
+
version: probeWithTimeout(binaryPath, spec.versionArgs, env, "version", probeTimeoutMs, cwd),
|
|
107
|
+
help: probeWithTimeout(binaryPath, spec.helpArgs, env, "help", probeTimeoutMs, cwd),
|
|
108
|
+
};
|
|
109
|
+
const evidence = spec.evidenceArgs
|
|
110
|
+
? probeWithTimeout(binaryPath, spec.evidenceArgs, env, spec.evidenceLabel ?? "evidence", probeTimeoutMs, cwd)
|
|
111
|
+
: undefined;
|
|
112
|
+
const result = { ...base, ...(evidence !== undefined ? { evidence } : {}), cacheHit: Boolean(cached) };
|
|
113
|
+
spec.validate?.(result);
|
|
114
|
+
if (!cached) {
|
|
115
|
+
const cacheKey = JSON.stringify([binaryPath, base.version, binaryMtimeMs, specKey(spec)]);
|
|
116
|
+
cache.set(cacheKey, base);
|
|
117
|
+
lookup.set(lookupKey, cacheKey);
|
|
118
|
+
while (cache.size > MAX_CACHE_ENTRIES) {
|
|
119
|
+
const oldest = cache.keys().next().value as string;
|
|
120
|
+
cache.delete(oldest);
|
|
121
|
+
for (const [candidateLookup, candidateCache] of lookup) if (candidateCache === oldest) lookup.delete(candidateLookup);
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
return result;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
export function invalidateExternalCliPreflight(command: string, spec: ExternalCliPreflightSpec, _reason: ExternalCliPreflightInvalidationReason): void {
|
|
128
|
+
const key = specKey(spec);
|
|
129
|
+
for (const [cacheKey, entry] of cache) {
|
|
130
|
+
if (entry.binaryPath === command || entry.binaryPath.endsWith(`${path.sep}${command}`) || cacheKey.includes(key)) cache.delete(cacheKey);
|
|
131
|
+
}
|
|
132
|
+
for (const [lookupKey, cacheKey] of lookup) if (!cache.has(cacheKey)) lookup.delete(lookupKey);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export function clearExternalCliPreflightCacheForTests(): void {
|
|
136
|
+
cache.clear();
|
|
137
|
+
lookup.clear();
|
|
138
|
+
}
|