@xzzpig/pi-subagents 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/CHANGELOG.md +175 -0
  2. package/README.md +4 -0
  3. package/agents/oracle.md +3 -1
  4. package/agents/reviewer.md +1 -0
  5. package/agents/scout.md +2 -2
  6. package/agents/worker.md +2 -1
  7. package/async-retention-discovery-worker.mjs +180 -0
  8. package/docs/agents.md +41 -3
  9. package/docs/configuration.md +41 -13
  10. package/docs/extension-api.md +65 -2
  11. package/docs/models.md +2 -0
  12. package/docs/observability.md +41 -5
  13. package/docs/tool-reference.md +38 -39
  14. package/docs/workflows.md +173 -3
  15. package/package.json +14 -10
  16. package/prompts/council.md +48 -0
  17. package/skills/council-mode/SKILL.md +230 -0
  18. package/skills/pi-subagents/SKILL.md +8 -4
  19. package/skills/pi-subagents/references/constraints-and-recipes.md +13 -6
  20. package/skills/pi-subagents/references/execution-controls.md +40 -15
  21. package/skills/pi-subagents/references/management-authoring-rpc.md +3 -3
  22. package/skills/pi-subagents/references/multi-lane-orchestration.md +39 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +4 -2
  24. package/src/agents/agent-management.ts +471 -377
  25. package/src/agents/agent-serializer.ts +2 -0
  26. package/src/agents/agents.ts +186 -44
  27. package/src/agents/builtin-names.ts +9 -0
  28. package/src/agents/runtime-agent-registry.ts +418 -0
  29. package/src/agents/skills.ts +1 -1
  30. package/src/api/agent-management.ts +9 -0
  31. package/src/api/agents.ts +7 -0
  32. package/src/api/external-job-provider.ts +186 -0
  33. package/src/api/preflight.ts +45 -13
  34. package/src/api/shared-types.ts +2 -0
  35. package/src/extension/config.ts +6 -3
  36. package/src/extension/doctor.ts +4 -6
  37. package/src/extension/fanout-child.ts +2 -2
  38. package/src/extension/index.ts +183 -90
  39. package/src/extension/public-execution.ts +31 -2
  40. package/src/extension/rpc.ts +41 -1
  41. package/src/extension/schemas.ts +17 -37
  42. package/src/extension/tool-description.ts +35 -24
  43. package/src/inspectors/herdr/actions.ts +2 -2
  44. package/src/inspectors/herdr/inspector-runner.ts +2 -1
  45. package/src/inspectors/herdr/project-panes.ts +2 -2
  46. package/src/intercom/native-supervisor-channel.ts +32 -10
  47. package/src/missions/lifecycle.ts +6 -1
  48. package/src/missions/store.ts +4 -9
  49. package/src/missions/workflow-state.ts +2 -2
  50. package/src/profiles/profiles.ts +3 -1
  51. package/src/runs/background/active-run-index.ts +31 -8
  52. package/src/runs/background/async-execution.ts +70 -41
  53. package/src/runs/background/async-job-tracker.ts +24 -7
  54. package/src/runs/background/async-resume.ts +49 -16
  55. package/src/runs/background/async-retention.ts +886 -0
  56. package/src/runs/background/async-status-snapshot.ts +14 -5
  57. package/src/runs/background/async-status.ts +39 -53
  58. package/src/runs/background/auto-drain.ts +1 -0
  59. package/src/runs/background/chain-append.ts +3 -33
  60. package/src/runs/background/completion-dedupe.ts +5 -1
  61. package/src/runs/background/completion-replay.ts +22 -12
  62. package/src/runs/background/control-channel.ts +14 -68
  63. package/src/runs/background/fleet-view.ts +68 -19
  64. package/src/runs/background/index-segment.ts +59 -0
  65. package/src/runs/background/inspect-rpc.ts +443 -0
  66. package/src/runs/background/notify.ts +31 -5
  67. package/src/runs/background/result-files.ts +158 -90
  68. package/src/runs/background/result-watcher.ts +124 -20
  69. package/src/runs/background/resume-guidance.ts +8 -5
  70. package/src/runs/background/retained-children.ts +13 -3
  71. package/src/runs/background/run-id-query.ts +7 -0
  72. package/src/runs/background/run-id-resolver.ts +11 -9
  73. package/src/runs/background/run-status.ts +27 -18
  74. package/src/runs/background/scheduled-runs.ts +24 -4
  75. package/src/runs/background/stale-run-reconciler.ts +6 -3
  76. package/src/runs/background/steering.ts +11 -1
  77. package/src/runs/background/subagent-runner.ts +260 -144
  78. package/src/runs/background/subagent-wait.ts +17 -13
  79. package/src/runs/background/terminal-run-index.ts +138 -0
  80. package/src/runs/background/wait-completions.ts +21 -4
  81. package/src/runs/background/wait-subscriptions.ts +81 -2
  82. package/src/runs/background/wait-tool.ts +1 -0
  83. package/src/runs/foreground/async-steering-action.ts +21 -14
  84. package/src/runs/foreground/execution.ts +104 -71
  85. package/src/runs/foreground/subagent-executor.ts +816 -1593
  86. package/src/runs/foreground/workflow-detach-reconcile.ts +262 -0
  87. package/src/runs/foreground/workflow-foreground-steering.ts +6 -5
  88. package/src/runs/shared/acceptance.ts +48 -5
  89. package/src/runs/shared/chain-outputs.ts +1 -3
  90. package/src/runs/shared/external-job-bridge.ts +444 -0
  91. package/src/runs/shared/external-job-runner.ts +286 -0
  92. package/src/runs/shared/mcp-direct-tool-allowlist.ts +14 -0
  93. package/src/runs/shared/model-exclusions.ts +242 -0
  94. package/src/runs/shared/model-fallback.ts +153 -40
  95. package/src/runs/shared/orca-progress-tabs.ts +84 -22
  96. package/src/runs/shared/parallel-handoff.ts +46 -4
  97. package/src/runs/shared/parallel-utils.ts +4 -15
  98. package/src/runs/shared/permissions.ts +5 -1
  99. package/src/runs/shared/pi-args.ts +8 -1
  100. package/src/runs/shared/session-lease.ts +0 -6
  101. package/src/runs/shared/subagent-control.ts +51 -7
  102. package/src/runs/shared/subagent-prompt-runtime.ts +12 -6
  103. package/src/runs/shared/workflow-graph.ts +1 -23
  104. package/src/runs/shared/worktree.ts +14 -2
  105. package/src/shared/atomic-json.ts +22 -2
  106. package/src/shared/capacity-resilient-json.ts +102 -0
  107. package/src/shared/completion-owner.ts +14 -0
  108. package/src/shared/file-system-retry.ts +49 -1
  109. package/src/shared/fork-context.ts +59 -1
  110. package/src/shared/model-info.ts +20 -0
  111. package/src/shared/prompt-resources.ts +0 -40
  112. package/src/shared/settings.ts +5 -29
  113. package/src/shared/types.ts +106 -26
  114. package/src/shared/utils.ts +8 -0
  115. package/src/shared/watch-strategy.ts +10 -0
  116. package/src/slash/slash-bridge.ts +2 -1
  117. package/src/slash/slash-commands.ts +47 -7
  118. package/src/slash/slash-live-state.ts +3 -3
  119. package/src/tui/fleet-status.ts +86 -1
  120. package/src/tui/fleet.ts +117 -16
  121. package/src/tui/render.ts +73 -3
  122. package/src/watchdog/change-signature.ts +1 -1
  123. package/src/watchdog/lsp-diagnostics.ts +1 -0
  124. package/src/workflows/chat-progress.ts +2 -2
  125. package/src/workflows/scripted-workflow.ts +320 -79
  126. package/src/workflows/workflow-receipt.ts +140 -0
  127. package/src/runs/foreground/chain-clarify.ts +0 -1354
  128. package/src/runs/foreground/chain-execution.ts +0 -1581
@@ -0,0 +1,286 @@
1
+ import { createHash } from "node:crypto";
2
+ import * as fs from "node:fs";
3
+ import * as path from "node:path";
4
+ import { ExternalJobProviderError, type ExternalJobHandle, type ExternalJobResult, type ExternalJobState } from "../../api/external-job-provider.ts";
5
+ import type { ExternalJobStatus } from "../../shared/types.ts";
6
+ import { requestExternalJobOperation } from "./external-job-bridge.ts";
7
+
8
+ const STATUS_POLL_INTERVAL_MS = 1_000;
9
+
10
+ export interface ExternalJobRunResult {
11
+ output: string;
12
+ exitCode: number;
13
+ error?: string;
14
+ timedOut?: boolean;
15
+ stopped?: boolean;
16
+ externalJob: ExternalJobStatus;
17
+ }
18
+
19
+ export function externalJobPromptDigest(prompt: string): string {
20
+ return createHash("sha256").update(prompt).digest("hex");
21
+ }
22
+
23
+ function sleep(ms: number): Promise<void> {
24
+ return new Promise((resolve) => setTimeout(resolve, ms));
25
+ }
26
+
27
+ function terminal(state: ExternalJobState): boolean {
28
+ return state === "completed" || state === "failed" || state === "stopped" || state === "blocked";
29
+ }
30
+
31
+ function formatError(error: ExternalJobProviderError, provider: string): string {
32
+ const blocking = error.blockingJobId ? ` Blocking provider job: ${error.blockingJobId}.` : "";
33
+ return `External-job provider '${provider}' failed closed (${error.code}): ${error.message}.${blocking}`;
34
+ }
35
+
36
+ function isNotFound(error: unknown): boolean {
37
+ return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
38
+ }
39
+
40
+ function isRecord(value: unknown): value is Record<string, unknown> {
41
+ return typeof value === "object" && value !== null && !Array.isArray(value);
42
+ }
43
+
44
+ function malformedStatus(statusPath: string): ExternalJobProviderError {
45
+ return new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable" });
46
+ }
47
+
48
+ function parseExternalJobStatus(value: unknown, statusPath: string): ExternalJobStatus {
49
+ if (!isRecord(value)) throw malformedStatus(statusPath);
50
+ const provider = value.provider;
51
+ const promptDigest = value.promptDigest;
52
+ const state = value.state;
53
+ if (typeof provider !== "string" || provider.length === 0) throw malformedStatus(statusPath);
54
+ if (typeof promptDigest !== "string" || promptDigest.length === 0) throw malformedStatus(statusPath);
55
+ if (state !== "queued" && state !== "running" && state !== "completed" && state !== "failed" && state !== "stopped" && state !== "blocked") throw malformedStatus(statusPath);
56
+ if (value.options !== undefined && !isRecord(value.options)) throw malformedStatus(statusPath);
57
+ const providerJobId = value.providerJobId;
58
+ const handleUrl = value.handleUrl;
59
+ const conversationUrl = value.conversationUrl;
60
+ const resultArtifactPath = value.resultArtifactPath;
61
+ const failureCode = value.failureCode;
62
+ const failureMessage = value.failureMessage;
63
+ const blockingJobId = value.blockingJobId;
64
+ const startedAt = value.startedAt;
65
+ const updatedAt = value.updatedAt;
66
+ if (providerJobId !== undefined && (typeof providerJobId !== "string" || providerJobId.length === 0)) throw malformedStatus(statusPath);
67
+ if (handleUrl !== undefined && typeof handleUrl !== "string") throw malformedStatus(statusPath);
68
+ if (conversationUrl !== undefined && typeof conversationUrl !== "string") throw malformedStatus(statusPath);
69
+ if (resultArtifactPath !== undefined && typeof resultArtifactPath !== "string") throw malformedStatus(statusPath);
70
+ if (failureCode !== undefined && typeof failureCode !== "string") throw malformedStatus(statusPath);
71
+ if (failureMessage !== undefined && typeof failureMessage !== "string") throw malformedStatus(statusPath);
72
+ if (blockingJobId !== undefined && typeof blockingJobId !== "string") throw malformedStatus(statusPath);
73
+ if (startedAt !== undefined && typeof startedAt !== "number") throw malformedStatus(statusPath);
74
+ if (updatedAt !== undefined && typeof updatedAt !== "number") throw malformedStatus(statusPath);
75
+ return {
76
+ provider,
77
+ promptDigest,
78
+ options: value.options ?? {},
79
+ state,
80
+ ...(providerJobId ? { providerJobId } : {}),
81
+ ...(handleUrl ? { handleUrl } : {}),
82
+ ...(conversationUrl ? { conversationUrl } : {}),
83
+ ...(resultArtifactPath ? { resultArtifactPath } : {}),
84
+ ...(failureCode ? { failureCode } : {}),
85
+ ...(failureMessage ? { failureMessage } : {}),
86
+ ...(blockingJobId ? { blockingJobId } : {}),
87
+ ...(startedAt !== undefined ? { startedAt } : {}),
88
+ ...(updatedAt !== undefined ? { updatedAt } : {}),
89
+ };
90
+ }
91
+
92
+ function readExistingExternalJob(asyncDir: string, stepIndex: number): ExternalJobStatus | undefined {
93
+ const statusPath = path.join(asyncDir, "status.json");
94
+ let raw: string;
95
+ try {
96
+ raw = fs.readFileSync(statusPath, "utf-8");
97
+ } catch (error) {
98
+ if (isNotFound(error)) return undefined;
99
+ throw new ExternalJobProviderError(`Unreadable external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
100
+ }
101
+ let parsed: unknown;
102
+ try {
103
+ parsed = JSON.parse(raw);
104
+ } catch (error) {
105
+ throw new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
106
+ }
107
+ if (!isRecord(parsed) || !Array.isArray(parsed.steps)) throw malformedStatus(statusPath);
108
+ const step = parsed.steps[stepIndex];
109
+ if (step === undefined || !isRecord(step)) throw malformedStatus(statusPath);
110
+ if (step.externalJob === undefined) return undefined;
111
+ return parseExternalJobStatus(step.externalJob, statusPath);
112
+ }
113
+
114
+ function statusFromHandle(input: {
115
+ provider: string;
116
+ promptDigest: string;
117
+ options: Record<string, unknown>;
118
+ startedAt?: number;
119
+ previous?: ExternalJobStatus;
120
+ handle: ExternalJobHandle;
121
+ resultArtifactPath?: string;
122
+ }): ExternalJobStatus {
123
+ return {
124
+ provider: input.provider,
125
+ providerJobId: input.handle.providerJobId,
126
+ promptDigest: input.promptDigest,
127
+ options: input.options,
128
+ handleUrl: input.handle.handleUrl ?? input.previous?.handleUrl,
129
+ conversationUrl: input.handle.conversationUrl ?? input.previous?.conversationUrl,
130
+ resultArtifactPath: input.resultArtifactPath ?? input.previous?.resultArtifactPath,
131
+ state: input.handle.state,
132
+ failureCode: input.handle.failureCode,
133
+ failureMessage: input.handle.failureMessage,
134
+ blockingJobId: input.handle.blockingJobId,
135
+ startedAt: input.previous?.startedAt ?? input.startedAt,
136
+ updatedAt: Date.now(),
137
+ };
138
+ }
139
+
140
+ function failureStatus(input: {
141
+ provider: string;
142
+ promptDigest: string;
143
+ options: Record<string, unknown>;
144
+ previous?: ExternalJobStatus;
145
+ code: string;
146
+ message: string;
147
+ blockingJobId?: string;
148
+ }): ExternalJobStatus {
149
+ return {
150
+ provider: input.provider,
151
+ providerJobId: input.previous?.providerJobId,
152
+ promptDigest: input.promptDigest,
153
+ options: input.options,
154
+ handleUrl: input.previous?.handleUrl,
155
+ conversationUrl: input.previous?.conversationUrl,
156
+ resultArtifactPath: input.previous?.resultArtifactPath,
157
+ state: input.blockingJobId ? "blocked" : "failed",
158
+ failureCode: input.code,
159
+ failureMessage: input.message,
160
+ blockingJobId: input.blockingJobId,
161
+ startedAt: input.previous?.startedAt,
162
+ updatedAt: Date.now(),
163
+ };
164
+ }
165
+
166
+ function resultOutput(result: ExternalJobResult, artifactPath: string | undefined): string {
167
+ if (result.output?.trim()) return result.output.trim();
168
+ if (artifactPath) return `External job finished. Result artifact: ${artifactPath}`;
169
+ return "External job finished without text output.";
170
+ }
171
+
172
+ function blocksStartRedispatch(status: ExternalJobStatus, provider: string, promptDigest: string): boolean {
173
+ return status.provider === provider
174
+ && status.promptDigest === promptDigest
175
+ && !status.providerJobId
176
+ && status.failureCode !== "provider-unavailable";
177
+ }
178
+
179
+ export async function runExternalJob(input: {
180
+ provider: string;
181
+ options?: Record<string, unknown>;
182
+ cwd: string;
183
+ prompt: string;
184
+ asyncDir: string;
185
+ stepIndex: number;
186
+ runId: string;
187
+ agent: string;
188
+ sessionId?: string;
189
+ registerTimeout?: (stop: (() => void) | undefined) => void;
190
+ registerStop?: (stop: (() => void) | undefined) => void;
191
+ timeoutMessage?: string;
192
+ stopMessage?: string;
193
+ onExternalJob?: (status: ExternalJobStatus) => void;
194
+ }): Promise<ExternalJobRunResult> {
195
+ const provider = input.provider;
196
+ const options = input.options ?? {};
197
+ const promptDigest = externalJobPromptDigest(input.prompt);
198
+ const startedAt = Date.now();
199
+ let timedOut = false;
200
+ let stopped = false;
201
+ let current: ExternalJobStatus | undefined;
202
+ const timeout = () => { timedOut = true; };
203
+ const stop = () => { stopped = true; };
204
+ input.registerTimeout?.(timeout);
205
+ input.registerStop?.(stop);
206
+ const publish = (status: ExternalJobStatus) => {
207
+ current = status;
208
+ input.onExternalJob?.(status);
209
+ };
210
+ const localCancellation = () => {
211
+ if (!timedOut && !stopped) return undefined;
212
+ const message = stopped
213
+ ? input.stopMessage ?? `Subagent stopped locally before external provider '${provider}' returned a job id. The provider start may still be running.`
214
+ : input.timeoutMessage ?? `Subagent timed out locally before external provider '${provider}' returned a job id. The provider start may still be running.`;
215
+ return new ExternalJobProviderError(message, { code: stopped ? "local-stop" : "local-timeout" });
216
+ };
217
+ try {
218
+ current = readExistingExternalJob(input.asyncDir, input.stepIndex);
219
+ let handle: ExternalJobHandle;
220
+ if (current?.providerJobId) {
221
+ if (current.provider !== provider || current.promptDigest !== promptDigest) {
222
+ const message = `Existing external job '${current.providerJobId}' does not match provider or prompt digest. Refusing to redispatch prompt.`;
223
+ const status = failureStatus({ provider, promptDigest, options, previous: current, code: "recovery-mismatch", message });
224
+ publish(status);
225
+ return { output: message, exitCode: 1, error: message, externalJob: status };
226
+ }
227
+ handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "reattach", provider, providerJobId: current.providerJobId });
228
+ } else {
229
+ if (current && blocksStartRedispatch(current, provider, promptDigest)) {
230
+ const message = `External-job start for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
231
+ const status = failureStatus({ provider, promptDigest, options, previous: current, code: "start-redispatch-blocked", message });
232
+ publish(status);
233
+ return { output: message, exitCode: 1, error: message, externalJob: status };
234
+ }
235
+ publish({ provider, promptDigest, options, state: "queued", startedAt, updatedAt: Date.now() });
236
+ handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
237
+ operation: "start",
238
+ provider,
239
+ start: {
240
+ prompt: input.prompt,
241
+ promptDigest,
242
+ cwd: input.cwd,
243
+ runId: input.runId,
244
+ stepIndex: input.stepIndex,
245
+ agent: input.agent,
246
+ options,
247
+ ...(input.sessionId ? { sessionId: input.sessionId } : {}),
248
+ },
249
+ }, undefined, localCancellation);
250
+ }
251
+ publish(statusFromHandle({ provider, promptDigest, options, startedAt, previous: current, handle }));
252
+ while (!terminal(handle.state)) {
253
+ if (timedOut || stopped) {
254
+ const message = stopped
255
+ ? input.stopMessage ?? `Subagent stopped locally; external provider job '${handle.providerJobId}' may still be running.`
256
+ : input.timeoutMessage ?? `Subagent timed out locally; external provider job '${handle.providerJobId}' may still be running.`;
257
+ return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: current! };
258
+ }
259
+ await sleep(STATUS_POLL_INTERVAL_MS);
260
+ handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "status", provider, providerJobId: handle.providerJobId });
261
+ publish(statusFromHandle({ provider, promptDigest, options, previous: current, handle }));
262
+ }
263
+ const result = await requestExternalJobOperation<ExternalJobResult>(input.asyncDir, { operation: "result", provider, providerJobId: handle.providerJobId });
264
+ let artifactPath = result.artifactPath;
265
+ if (!artifactPath && result.output !== undefined) {
266
+ artifactPath = path.join(input.asyncDir, `external-job-${input.stepIndex}.result.md`);
267
+ fs.writeFileSync(artifactPath, result.output, "utf-8");
268
+ }
269
+ const finalStatus = statusFromHandle({ provider, promptDigest, options, previous: current, handle: result, resultArtifactPath: artifactPath });
270
+ publish(finalStatus);
271
+ const output = resultOutput(result, artifactPath);
272
+ const error = result.state === "completed" ? undefined : result.failureMessage ?? `External job ${result.state}.`;
273
+ return { output, exitCode: result.state === "completed" ? 0 : 1, ...(error ? { error } : {}), externalJob: finalStatus };
274
+ } catch (error) {
275
+ const providerError = error instanceof ExternalJobProviderError
276
+ ? error
277
+ : new ExternalJobProviderError(error instanceof Error ? error.message : String(error), { code: "provider-error", cause: error });
278
+ const message = formatError(providerError, provider);
279
+ const status = failureStatus({ provider, promptDigest, options, previous: current, code: providerError.code, message, ...(providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {}) });
280
+ publish(status);
281
+ return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: status };
282
+ } finally {
283
+ input.registerTimeout?.(undefined);
284
+ input.registerStop?.(undefined);
285
+ }
286
+ }
@@ -32,6 +32,12 @@ interface ServerEntry {
32
32
  cwd?: string;
33
33
  url?: string;
34
34
  headers?: Record<string, string>;
35
+ requestHeadersCommand?: {
36
+ command: string;
37
+ args?: string[];
38
+ env?: Record<string, string>;
39
+ timeoutMs?: number;
40
+ };
35
41
  auth?: "oauth" | "bearer" | false;
36
42
  bearerToken?: string;
37
43
  bearerTokenEnv?: string;
@@ -279,6 +285,14 @@ export function computeMcpServerHash(definition: ServerEntry): string {
279
285
  cwd: resolveConfigPath(definition.cwd),
280
286
  url: resolveServerUrl(definition),
281
287
  headers: interpolateEnvRecord(definition.headers),
288
+ requestHeadersCommand: definition.requestHeadersCommand
289
+ ? {
290
+ command: interpolateEnvVars(definition.requestHeadersCommand.command),
291
+ args: definition.requestHeadersCommand.args?.map(interpolateEnvVars),
292
+ env: interpolateEnvRecord(definition.requestHeadersCommand.env),
293
+ timeoutMs: definition.requestHeadersCommand.timeoutMs,
294
+ }
295
+ : undefined,
282
296
  auth: definition.auth,
283
297
  bearerToken: resolveBearerToken(definition),
284
298
  bearerTokenEnv: definition.bearerTokenEnv,
@@ -0,0 +1,242 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { TEMP_ROOT_DIR } from "../../shared/types.ts";
4
+
5
+ export const EXCLUSIONS_PATH_ENV = "PI_MODEL_EXCLUSIONS_PATH";
6
+
7
+ type ModelExclusionTarget = { modelId: string; provider?: string } | { provider: string; modelId?: never };
8
+
9
+ export type ModelExclusion = ModelExclusionTarget & {
10
+ reason?: string;
11
+ recordedAt: number;
12
+ expiresAt: number;
13
+ };
14
+
15
+ type RecordModelFailureOptions = ModelExclusionTarget & {
16
+ reason?: string;
17
+ ttlMs?: number;
18
+ };
19
+
20
+ let exclusions: ModelExclusion[] = [];
21
+ let loaded = false;
22
+ let defaultTTLMs = 24 * 60 * 60_000; // 24 hours, overridable via setDefaultTTL
23
+ let persistTimer: ReturnType<typeof setTimeout> | null = null;
24
+ let persistSeq = 0;
25
+
26
+ /** Override the default exclusion TTL. */
27
+ export function setDefaultTTL(ms: number): void {
28
+ if (!Number.isFinite(ms) || ms <= 0) throw new Error("Default model exclusion TTL must be a finite positive number.");
29
+ defaultTTLMs = ms;
30
+ }
31
+
32
+ /**
33
+ * Resolve the persistence path. Honors PI_MODEL_EXCLUSIONS_PATH; defaults to
34
+ * <TEMP_ROOT_DIR>/model-exclusions.json. Resolved lazily so tests can point the
35
+ * store at an isolated location after module load.
36
+ */
37
+ export function getExclusionsFilePath(): string {
38
+ const envPath = process.env[EXCLUSIONS_PATH_ENV];
39
+ if (typeof envPath === "string" && envPath.trim()) return envPath.trim();
40
+ return path.join(TEMP_ROOT_DIR, "model-exclusions.json");
41
+ }
42
+
43
+ /**
44
+ * Persist exclusions to disk immediately (atomic write via tmp + rename).
45
+ * The store otherwise debounces writes; call this when durability matters
46
+ * (and in tests).
47
+ */
48
+ export function flushPersist(): void {
49
+ const file = getExclusionsFilePath();
50
+ try {
51
+ fs.mkdirSync(path.dirname(file), { recursive: true });
52
+ const tmpPath = `${file}.${process.pid}.${persistSeq++}.tmp`;
53
+ fs.writeFileSync(tmpPath, JSON.stringify({
54
+ version: 1,
55
+ exclusions: deduplicate(exclusions),
56
+ }, null, 2), "utf-8");
57
+ fs.renameSync(tmpPath, file);
58
+ } catch (error) {
59
+ console.error(`[model-exclusions] Failed to persist exclusions to ${file}:`, error);
60
+ }
61
+ }
62
+
63
+ function schedulePersist(): void {
64
+ if (persistTimer) clearTimeout(persistTimer);
65
+ persistTimer = setTimeout(() => {
66
+ persistTimer = null;
67
+ flushPersist();
68
+ }, 5000);
69
+ // Never hold the process open just to flush exclusions.
70
+ persistTimer.unref?.();
71
+ }
72
+
73
+ function ensureLoaded(): void {
74
+ if (loaded) return;
75
+ loaded = true;
76
+ try {
77
+ const raw = fs.readFileSync(getExclusionsFilePath(), "utf-8");
78
+ const data = JSON.parse(raw);
79
+ if (data.version === 1) {
80
+ const now = Date.now();
81
+ exclusions = (data.exclusions ?? []).filter((e: ModelExclusion) => e.expiresAt > now);
82
+ exclusions = deduplicate(exclusions);
83
+ }
84
+ } catch (error) {
85
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
86
+ console.error(`[model-exclusions] Failed to load exclusions from ${getExclusionsFilePath()}:`, error);
87
+ }
88
+ }
89
+ }
90
+
91
+ function dedupKey(entry: ModelExclusion): string {
92
+ return `${entry.provider ?? ""}|${entry.modelId ?? ""}`;
93
+ }
94
+
95
+ function deduplicate(items: ModelExclusion[]): ModelExclusion[] {
96
+ const map = new Map<string, ModelExclusion>();
97
+ for (const entry of items) {
98
+ const key = dedupKey(entry);
99
+ const existing = map.get(key);
100
+ if (!existing || entry.recordedAt > existing.recordedAt) {
101
+ map.set(key, entry);
102
+ }
103
+ }
104
+ return Array.from(map.values());
105
+ }
106
+
107
+ /**
108
+ * Record a model failure as a temporary exclusion. While the exclusion is
109
+ * active, {@link isExcluded} returns true for the model (or for every model of
110
+ * the provider when modelId is omitted), and {@link filterFallbackCandidates}
111
+ * removes matching candidates from fallback lists.
112
+ */
113
+ export function recordModelFailure(options: RecordModelFailureOptions): void {
114
+ ensureLoaded();
115
+ const ttl = options.ttlMs ?? defaultTTLMs;
116
+ const now = Date.now();
117
+ const target: ModelExclusionTarget = options.modelId !== undefined
118
+ ? { modelId: options.modelId, ...(options.provider ? { provider: options.provider } : {}) }
119
+ : { provider: options.provider };
120
+ const exclusion: ModelExclusion = {
121
+ ...target,
122
+ reason: options.reason ?? "runtime-failure",
123
+ recordedAt: now,
124
+ expiresAt: now + ttl,
125
+ };
126
+ exclusions.unshift(exclusion);
127
+ exclusions = deduplicate(exclusions);
128
+ if (exclusions.length > 200) exclusions.length = 200;
129
+ flushPersist();
130
+ }
131
+
132
+ /**
133
+ * Drop all expired exclusions from memory and schedule a persist.
134
+ */
135
+ export function clearExpiredExclusions(): void {
136
+ ensureLoaded();
137
+ prune(exclusions, Date.now());
138
+ schedulePersist();
139
+ }
140
+
141
+ /**
142
+ * Remove every exclusion (e.g. after the operator fixes credentials).
143
+ */
144
+ export function clearExclusions(): void {
145
+ ensureLoaded();
146
+ exclusions.length = 0;
147
+ schedulePersist();
148
+ }
149
+
150
+ /**
151
+ * Whether an exclusion entry matches a candidate.
152
+ *
153
+ * Semantics:
154
+ * - Entry with modelId: model-specific exclusion. Matches only that modelId;
155
+ * when both the entry and the candidate carry a provider, the providers must
156
+ * also agree so `openai/gpt-4` does not exclude `github-copilot/gpt-4`.
157
+ * - Entry without modelId: provider-wide exclusion (e.g. quota or auth failure).
158
+ * Matches every model of that provider.
159
+ */
160
+ function entryMatches(entry: ModelExclusion, candidateModelId: string, candidateProvider: string | undefined, now: number): boolean {
161
+ if (entry.expiresAt <= now) return false;
162
+ if (entry.modelId) {
163
+ if (entry.modelId !== candidateModelId) return false;
164
+ return !entry.provider || !candidateProvider || entry.provider === candidateProvider;
165
+ }
166
+ return Boolean(entry.provider) && entry.provider === candidateProvider;
167
+ }
168
+
169
+ /**
170
+ * Whether a model (or its provider) is currently excluded.
171
+ */
172
+ export function isExcluded(modelId: string, provider: string): boolean {
173
+ ensureLoaded();
174
+ return exclusions.some((entry) => entryMatches(entry, modelId, provider, Date.now()));
175
+ }
176
+
177
+ /**
178
+ * Number of live (non-expired) exclusions.
179
+ */
180
+ export function getExcludedCount(): number {
181
+ ensureLoaded();
182
+ clearExpiredExclusions();
183
+ return exclusions.length;
184
+ }
185
+
186
+ /**
187
+ * Split a candidate fullId into its provider + modelId components.
188
+ *
189
+ * A fullId may carry a thinking suffix (`provider/model:thinking`) which is
190
+ * stripped before parsing, and the modelId itself may contain slashes
191
+ * (e.g. `openrouter/google/gemini-flash`). The first `/`-segment is the
192
+ * provider; everything after is the modelId. This MUST stay in lock-step with
193
+ * the matching inside {@link isExcluded} so that a failure recorded via
194
+ * {@link recordModelFailure} is later recognised by the candidate filter.
195
+ */
196
+ export function parseModelKey(fullId: string): { provider?: string; modelId: string } {
197
+ const base = fullId.includes(":") ? fullId.substring(0, fullId.lastIndexOf(":")) : fullId;
198
+ if (!base.includes("/")) return { modelId: base };
199
+ const slash = base.indexOf("/");
200
+ return { provider: base.slice(0, slash), modelId: base.slice(slash + 1) };
201
+ }
202
+
203
+ /**
204
+ * Filter a list of candidate fullIds, removing excluded models/providers and
205
+ * duplicates while preserving order.
206
+ */
207
+ export function filterFallbackCandidates(candidates: string[], opts?: { now?: number }): string[] {
208
+ ensureLoaded();
209
+ const timestamp = opts?.now ?? Date.now();
210
+ const seen = new Set<string>();
211
+ const filtered: string[] = [];
212
+ for (const raw of candidates) {
213
+ if (!raw || seen.has(raw)) continue;
214
+ const { provider: candidateProvider, modelId: candidateModelId } = parseModelKey(raw);
215
+ const excluded = exclusions.some((entry) => entryMatches(entry, candidateModelId, candidateProvider, timestamp));
216
+ if (excluded) continue;
217
+ seen.add(raw);
218
+ filtered.push(raw);
219
+ }
220
+ return filtered;
221
+ }
222
+
223
+ /**
224
+ * Reload exclusions from disk (for tests and config hot-reload).
225
+ * Discards any in-memory-only exclusions that were not yet persisted.
226
+ */
227
+ export function reloadFromDisk(): void {
228
+ loaded = false;
229
+ exclusions = [];
230
+ ensureLoaded();
231
+ }
232
+
233
+ function prune(items: ModelExclusion[], now: number): void {
234
+ let write = 0;
235
+ for (let i = 0; i < items.length; i++) {
236
+ const entry = items[i]!;
237
+ if (entry.expiresAt > now) {
238
+ items[write++] = entry;
239
+ }
240
+ }
241
+ items.length = write;
242
+ }