@xzzpig/pi-subagents 0.13.0 → 0.15.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 (202) hide show
  1. package/CHANGELOG.md +243 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +93 -15
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +67 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/CHANGELOG.md +19 -0
  19. package/node_modules/@xzzpig/pi-components/README.md +28 -0
  20. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +46 -4
  21. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +65 -17
  22. package/node_modules/@xzzpig/pi-components/package.json +1 -1
  23. package/node_modules/@xzzpig/pi-components/src/transcript.ts +107 -14
  24. package/package.json +10 -5
  25. package/prompts/parallel-review.md +1 -1
  26. package/runner-peer-loader.mjs +24 -0
  27. package/runner-peer-preload.mjs +36 -0
  28. package/skills/pi-subagents/SKILL.md +34 -22
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  30. package/skills/pi-subagents/references/execution-controls.md +27 -8
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  33. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  34. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  35. package/src/agents/advertised-agent-prompt.ts +94 -0
  36. package/src/agents/agent-management.ts +71 -59
  37. package/src/agents/agent-serializer.ts +6 -3
  38. package/src/agents/agents.ts +198 -72
  39. package/src/agents/builtin-names.ts +1 -0
  40. package/src/agents/chain-serializer.ts +5 -0
  41. package/src/agents/runtime-agent-registry.ts +7 -6
  42. package/src/api/delegation.ts +4 -0
  43. package/src/api/preflight.ts +110 -71
  44. package/src/api/required-child-extensions.ts +6 -0
  45. package/src/api/shared-types.ts +3 -1
  46. package/src/api/workflow-resources.ts +6 -0
  47. package/src/extension/config.ts +14 -37
  48. package/src/extension/fanout-child.ts +68 -5
  49. package/src/extension/herdr-pi-bridge.ts +164 -0
  50. package/src/extension/index.ts +141 -51
  51. package/src/extension/public-execution.ts +7 -6
  52. package/src/extension/rpc.ts +8 -21
  53. package/src/extension/schemas.ts +86 -84
  54. package/src/extension/tool-description.ts +32 -79
  55. package/src/inspectors/actions.ts +148 -0
  56. package/src/inspectors/ghostty/actions.ts +74 -0
  57. package/src/inspectors/ghostty/plugin.ts +17 -0
  58. package/src/inspectors/herdr/actions.ts +99 -179
  59. package/src/inspectors/herdr/plugin.ts +20 -0
  60. package/src/inspectors/herdr/project-panes.ts +4 -1
  61. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  62. package/src/inspectors/plugins.ts +8 -0
  63. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  64. package/src/inspectors/types.ts +51 -0
  65. package/src/integrations/pi-web-session-liveness.ts +73 -0
  66. package/src/intercom/intercom-bridge.ts +50 -8
  67. package/src/intercom/native-supervisor-channel.ts +142 -115
  68. package/src/intercom/supervisor-ui.ts +3 -2
  69. package/src/missions/workflow-state.ts +37 -16
  70. package/src/policy/authority.ts +4 -0
  71. package/src/profiles/profiles.ts +12 -6
  72. package/src/runs/background/active-async-capacity.ts +22 -18
  73. package/src/runs/background/active-run-index.ts +17 -1
  74. package/src/runs/background/async-execution.ts +359 -176
  75. package/src/runs/background/async-job-tracker.ts +41 -7
  76. package/src/runs/background/async-resume.ts +19 -12
  77. package/src/runs/background/async-retention.ts +20 -0
  78. package/src/runs/background/async-status-snapshot.ts +10 -12
  79. package/src/runs/background/async-status.ts +32 -13
  80. package/src/runs/background/auto-drain.ts +59 -35
  81. package/src/runs/background/binary-bootstrap.ts +38 -0
  82. package/src/runs/background/chain-append.ts +1 -1
  83. package/src/runs/background/chain-root-attachment.ts +22 -33
  84. package/src/runs/background/control-channel.ts +78 -44
  85. package/src/runs/background/fleet-view.ts +30 -2
  86. package/src/runs/background/notify.ts +193 -19
  87. package/src/runs/background/owned-process-tree.ts +35 -8
  88. package/src/runs/background/process-terminal.ts +23 -23
  89. package/src/runs/background/result-files.ts +8 -4
  90. package/src/runs/background/result-watcher.ts +19 -2
  91. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  92. package/src/runs/background/run-child-session.ts +118 -41
  93. package/src/runs/background/run-status.ts +78 -5
  94. package/src/runs/background/runner-aliases.ts +22 -5
  95. package/src/runs/background/runner-child-launch.ts +93 -0
  96. package/src/runs/background/runner-child-sessions.ts +5 -4
  97. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  98. package/src/runs/background/scheduled-runs.ts +51 -18
  99. package/src/runs/background/stale-run-reconciler.ts +38 -12
  100. package/src/runs/background/steering.ts +20 -2
  101. package/src/runs/background/subagent-runner.ts +766 -432
  102. package/src/runs/background/subagent-wait.ts +179 -28
  103. package/src/runs/background/wait-completions.ts +79 -27
  104. package/src/runs/background/wait-subscriptions.ts +9 -3
  105. package/src/runs/background/wait-tool.ts +5 -3
  106. package/src/runs/foreground/async-steering-action.ts +37 -7
  107. package/src/runs/foreground/async-stop-action.ts +93 -3
  108. package/src/runs/foreground/execution.ts +174 -194
  109. package/src/runs/foreground/foreground-history.ts +5 -2
  110. package/src/runs/foreground/prompt-audit.ts +12 -6
  111. package/src/runs/foreground/subagent-executor.ts +896 -397
  112. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  113. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  114. package/src/runs/shared/acceptance.ts +54 -14
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +172 -78
  117. package/src/runs/shared/capability-ceiling.ts +2 -0
  118. package/src/runs/shared/child-hooks.ts +167 -3
  119. package/src/runs/shared/child-launch-plan.ts +15 -3
  120. package/src/runs/shared/child-launch.ts +44 -16
  121. package/src/runs/shared/child-lifecycle.ts +6 -3
  122. package/src/runs/shared/child-runtime-config.ts +8 -1
  123. package/src/runs/shared/child-session.ts +130 -24
  124. package/src/runs/shared/child-tool-plan.ts +145 -14
  125. package/src/runs/shared/completion-evidence.ts +2 -2
  126. package/src/runs/shared/completion-guard.ts +6 -3
  127. package/src/runs/shared/dynamic-fanout.ts +2 -2
  128. package/src/runs/shared/effective-system-prompt.ts +33 -0
  129. package/src/runs/shared/external-cli-contract.ts +11 -1
  130. package/src/runs/shared/external-cli-preflight.ts +6 -2
  131. package/src/runs/shared/external-cli-runner.ts +9 -7
  132. package/src/runs/shared/herdr-connection.ts +134 -0
  133. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  134. package/src/runs/shared/herdr-machine.ts +279 -0
  135. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  136. package/src/runs/shared/herdr-placed-run.ts +263 -0
  137. package/src/runs/shared/host-step-status.ts +11 -11
  138. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  139. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  140. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  141. package/src/runs/shared/model-scope.ts +1 -1
  142. package/src/runs/shared/nested-events.ts +19 -10
  143. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  144. package/src/runs/shared/parallel-handoff.ts +57 -12
  145. package/src/runs/shared/parallel-utils.ts +10 -4
  146. package/src/runs/shared/pi-spawn.ts +10 -0
  147. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  148. package/src/runs/shared/run-fanout-budget.ts +8 -8
  149. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  150. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  151. package/src/runs/shared/task-intent.ts +46 -13
  152. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  153. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  154. package/src/runs/shared/worktree-setup-command.ts +213 -0
  155. package/src/runs/shared/worktree.ts +437 -214
  156. package/src/shared/child-cache-retention.ts +43 -0
  157. package/src/shared/fork-context.ts +15 -72
  158. package/src/shared/launch-contract.ts +70 -8
  159. package/src/shared/model-response-aliases.ts +13 -0
  160. package/src/shared/opencode-session-headers.ts +30 -0
  161. package/src/shared/pruned-fork.ts +1 -1
  162. package/src/shared/required-child-extensions.ts +81 -0
  163. package/src/shared/settings.ts +5 -2
  164. package/src/shared/shortcuts.ts +0 -4
  165. package/src/shared/types.ts +164 -90
  166. package/src/shared/utils.ts +10 -2
  167. package/src/shared/watch-strategy.ts +2 -0
  168. package/src/shared/workflow-child-permit.ts +18 -13
  169. package/src/slash/delegation-adapters.ts +3 -1
  170. package/src/slash/delegation-request.ts +14 -0
  171. package/src/slash/slash-commands.ts +2 -7
  172. package/src/slash/subagents-admin.ts +31 -14
  173. package/src/tui/fleet-native-transcript.ts +50 -6
  174. package/src/tui/fleet-status.ts +165 -20
  175. package/src/tui/fleet.ts +52 -21
  176. package/src/tui/render.ts +210 -50
  177. package/src/watchdog/child-status.ts +28 -28
  178. package/src/watchdog/lsp-diagnostics.ts +1 -1
  179. package/src/watchdog/model-selection.ts +21 -1
  180. package/src/watchdog/permission-arbiter.ts +5 -2
  181. package/src/watchdog/register-child.ts +10 -2
  182. package/src/watchdog/register-main.ts +39 -35
  183. package/src/watchdog/render.ts +1 -1
  184. package/src/watchdog/review.ts +122 -74
  185. package/src/watchdog/rules.ts +1 -1
  186. package/src/watchdog/runtime.ts +100 -27
  187. package/src/watchdog/scope.ts +1 -1
  188. package/src/watchdog/settings.ts +3 -0
  189. package/src/watchdog/tool-actions.ts +13 -12
  190. package/src/watchdog/turn-delta.ts +23 -0
  191. package/src/watchdog/types.ts +5 -3
  192. package/src/watchdog/warning-format.ts +1 -1
  193. package/src/workflows/chat-progress.ts +3 -3
  194. package/src/workflows/scripted-workflow.ts +349 -26
  195. package/src/workflows/workflow-checklist.ts +17 -20
  196. package/src/workflows/workflow-child-summary.ts +57 -8
  197. package/src/workflows/workflow-preflight.ts +19 -19
  198. package/src/workflows/workflow-receipt.ts +24 -6
  199. package/src/workflows/workflow-resources.ts +108 -22
  200. package/src/workflows/workflow-settlement.ts +3 -0
  201. package/src/runs/shared/model-exclusions.ts +0 -373
  202. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -2,10 +2,10 @@ import { randomUUID } from "node:crypto";
2
2
  import { stableJsonDigest } from "../shared/launch-contract.ts";
3
3
  import {
4
4
  createWorkflowResourcePermit,
5
- type WorkflowResourceAuthority,
5
+ type WorkflowResourceHostAuthority,
6
6
  type WorkflowResourcePermit,
7
7
  } from "../shared/workflow-child-permit.ts";
8
- import type { WorkflowResourceProvenanceV1 } from "../shared/types.ts";
8
+ import type { WorkflowResourceProvenance } from "../shared/types.ts";
9
9
 
10
10
  const RESOURCE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
11
11
  const MAX_ARGS_BYTES = 16 * 1024;
@@ -14,18 +14,75 @@ const MAX_STRING_BYTES = 16 * 1024;
14
14
  export interface ResolvedWorkflowResource {
15
15
  script: string;
16
16
  permit: WorkflowResourcePermit;
17
- provenance: WorkflowResourceProvenanceV1;
17
+ provenance: WorkflowResourceProvenance;
18
18
  }
19
19
 
20
20
  export type WorkflowResourceResolution =
21
21
  | { ok: true; resource: ResolvedWorkflowResource }
22
22
  | { ok: false; error: string };
23
23
 
24
- type WorkflowResourceDefinition = {
24
+ export interface WorkflowResourceDefinition {
25
25
  name: string;
26
26
  version: number;
27
- resolve: (args: Record<string, unknown>) => { script: string; authority: WorkflowResourceAuthority } | { error: string };
28
- };
27
+ /** Trusted synchronous validation/expansion. The extension owns semantic command binding. */
28
+ resolve: (args: Readonly<Record<string, unknown>>) => { script: string; hostCommands?: readonly WorkflowResourceHostAuthority[] } | { error: string };
29
+ }
30
+
31
+ export interface WorkflowResourceRegistration {
32
+ dispose(): void;
33
+ }
34
+
35
+ export interface RegisterWorkflowResourceInput {
36
+ sessionId: string;
37
+ definition: WorkflowResourceDefinition;
38
+ }
39
+
40
+ interface WorkflowResourceRegistry {
41
+ version: 1;
42
+ bySession: Map<string, Map<string, WorkflowResourceDefinition>>;
43
+ }
44
+
45
+ function registry(): WorkflowResourceRegistry {
46
+ const key = Symbol.for("pi-subagents.workflow-resources.v1");
47
+ const globalObject = globalThis as Record<PropertyKey, unknown>;
48
+ const existing = globalObject[key];
49
+ if (existing === undefined) {
50
+ const created: WorkflowResourceRegistry = { version: 1, bySession: new Map() };
51
+ globalObject[key] = created;
52
+ return created;
53
+ }
54
+ if (!isPlainRecord(existing) || existing.version !== 1 || !(existing.bySession instanceof Map)) throw new Error("Malformed or unsupported workflow resource registry.");
55
+ return existing as unknown as WorkflowResourceRegistry;
56
+ }
57
+
58
+ /** Session ID scopes lookup, not authentication. Dispose on session_shutdown; issued permits remain valid. */
59
+ export function registerWorkflowResource(input: RegisterWorkflowResourceInput): WorkflowResourceRegistration {
60
+ if (!isPlainRecord(input) || Object.keys(input).some((key) => key !== "sessionId" && key !== "definition")) throw new Error("Workflow registration requires only sessionId and definition.");
61
+ const { sessionId, definition } = input;
62
+ if (typeof sessionId !== "string" || !sessionId || sessionId.trim() !== sessionId || sessionId.length > 256 || sessionId.includes("\0")) throw new Error("Workflow registration requires a non-empty trimmed sessionId of at most 256 characters without NUL.");
63
+ if (!isPlainRecord(definition) || Object.keys(definition).some((key) => !["name", "version", "resolve"].includes(key))) throw new Error("Workflow definition requires only name, version and resolve.");
64
+ const { name, version, resolve } = definition;
65
+ if (typeof name !== "string" || !RESOURCE_NAME_PATTERN.test(name)) throw new Error("Workflow definition requires a safe resource name.");
66
+ if (!Number.isSafeInteger(version) || version < 1) throw new Error("Workflow definition version must be a positive safe integer.");
67
+ if (typeof resolve !== "function") throw new Error("Workflow definition requires a synchronous resolve function.");
68
+ if (findWorkflowResource(name)) throw new Error(`Workflow resource '${name}' is a protected builtin.`);
69
+ const current = registry();
70
+ const bucket = current.bySession.get(sessionId) ?? new Map<string, WorkflowResourceDefinition>();
71
+ if (!(bucket instanceof Map)) throw new Error("Malformed workflow resource session registry.");
72
+ if (bucket.has(name)) throw new Error(`Workflow resource '${name}' is already registered in this session; dispose it first.`);
73
+ const snapshot = Object.freeze({ name, version, resolve });
74
+ bucket.set(name, snapshot);
75
+ current.bySession.set(sessionId, bucket);
76
+ let disposed = false;
77
+ return {
78
+ dispose() {
79
+ if (disposed) return;
80
+ disposed = true;
81
+ if (bucket.get(name) === snapshot) bucket.delete(name);
82
+ if (bucket.size === 0 && current.bySession.get(sessionId) === bucket) current.bySession.delete(sessionId);
83
+ },
84
+ };
85
+ }
29
86
 
30
87
  function isPlainRecord(value: unknown): value is Record<string, unknown> {
31
88
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
@@ -68,19 +125,30 @@ function validatePlainJson(value: unknown, path: string, depth = 0): void {
68
125
  }
69
126
  }
70
127
 
71
- function normalizeArgs(value: unknown): { args?: Record<string, unknown>; error?: string } {
128
+ export function normalizeWorkflowArgs(value: unknown): { args: Record<string, unknown> } | { error: string } {
72
129
  if (value === undefined) return { args: {} };
73
130
  if (!isPlainRecord(value)) return { error: "workflow args must be a plain JSON object." };
74
131
  try {
75
132
  validatePlainJson(value, "workflow args");
76
133
  if (jsonByteLength(value) > MAX_ARGS_BYTES) return { error: `workflow args exceed ${MAX_ARGS_BYTES} bytes.` };
77
- return { args: { ...value } };
134
+ return { args: JSON.parse(JSON.stringify(value)) };
78
135
  } catch (error) {
79
136
  return { error: error instanceof Error ? error.message : String(error) };
80
137
  }
81
138
  }
82
139
 
83
- function resolveRunCi(args: Record<string, unknown>): { script: string; authority: WorkflowResourceAuthority } | { error: string } {
140
+ export function deepFreezeWorkflowArgs<T extends Record<string, unknown>>(args: T): Readonly<T> {
141
+ deepFreezeWorkflowValue(args);
142
+ return args;
143
+ }
144
+
145
+ function deepFreezeWorkflowValue(value: unknown): void {
146
+ if (!Array.isArray(value) && !isPlainRecord(value)) return;
147
+ for (const entry of Object.values(value)) deepFreezeWorkflowValue(entry);
148
+ Object.freeze(value);
149
+ }
150
+
151
+ function resolveRunCi(args: Readonly<Record<string, unknown>>): ReturnType<WorkflowResourceDefinition["resolve"]> {
84
152
  const allowed = new Set(["command", "timeoutMs"]);
85
153
  const unsupported = Object.keys(args).filter((key) => !allowed.has(key));
86
154
  if (unsupported.length > 0) return { error: `workflow 'run-ci' args contain unsupported fields: ${unsupported.join(", ")}.` };
@@ -91,18 +159,17 @@ function resolveRunCi(args: Record<string, unknown>): { script: string; authorit
91
159
  const params = { kind: "command", command, timeoutMs, role: "ci" };
92
160
  return {
93
161
  script: `return await runs.host("ci", ${JSON.stringify(params)});`,
94
- authority: { host: { keys: ["ci"], commands: [command] } },
162
+ hostCommands: [{ key: "ci", command }],
95
163
  };
96
164
  }
97
165
 
98
- function resolveReview(args: Record<string, unknown>): { script: string; authority: WorkflowResourceAuthority } | { error: string } {
166
+ function resolveReview(args: Readonly<Record<string, unknown>>): ReturnType<WorkflowResourceDefinition["resolve"]> {
99
167
  const unsupported = Object.keys(args).filter((key) => key !== "task");
100
168
  if (unsupported.length > 0) return { error: `workflow 'review' args contain unsupported fields: ${unsupported.join(", ")}.` };
101
169
  const task = args.task;
102
170
  if (typeof task !== "string" || !task.trim()) return { error: "workflow 'review' requires a non-empty string args.task." };
103
171
  return {
104
172
  script: `return (await runs.run("review", { agent: "reviewer", task: ${JSON.stringify(task.trim())} })).output;`,
105
- authority: {},
106
173
  };
107
174
  }
108
175
 
@@ -120,25 +187,44 @@ function listWorkflowResourceNames(): string[] {
120
187
  }
121
188
 
122
189
  /** Resolve only extension-owned resources so policy can distinguish them from raw scripts; caller-provided script text is never consulted. */
123
- export function resolveWorkflowResource(nameValue: unknown, argsValue?: unknown): WorkflowResourceResolution {
190
+ export function resolveWorkflowResource(nameValue: unknown, argsValue?: unknown, sessionId?: string): WorkflowResourceResolution {
191
+ try {
192
+ const result = resolveResource(nameValue, argsValue, sessionId);
193
+ return result.ok ? result : { ok: false, error: result.error.slice(0, 4096) };
194
+ } catch (error) {
195
+ return { ok: false, error: error instanceof Error ? error.message.slice(0, 4096) : "Workflow resource resolution failed." };
196
+ }
197
+ }
198
+
199
+ function resolveResource(nameValue: unknown, argsValue?: unknown, sessionId?: string): WorkflowResourceResolution {
124
200
  if (typeof nameValue !== "string" || !nameValue.trim()) return { ok: false, error: "workflow must be a non-empty resource name." };
125
201
  const name = nameValue.trim();
126
202
  if (!RESOURCE_NAME_PATTERN.test(name)) return { ok: false, error: "workflow must use a safe resource name." };
127
- const resource = findWorkflowResource(name);
203
+ const resource = findWorkflowResource(name) ?? (sessionId ? registry().bySession.get(sessionId)?.get(name) : undefined);
128
204
  if (!resource) return { ok: false, error: `Unknown workflow resource '${name}'. Available resources: ${listWorkflowResourceNames().join(", ")}.` };
129
- const normalizedArgs = normalizeArgs(argsValue);
130
- if (normalizedArgs.error) return { ok: false, error: normalizedArgs.error };
131
- const resolved = resource.resolve(normalizedArgs.args!);
132
- if ("error" in resolved) return { ok: false, error: resolved.error };
205
+ const normalizedArgs = normalizeWorkflowArgs(argsValue);
206
+ if ("error" in normalizedArgs) return { ok: false, error: normalizedArgs.error };
207
+ const resolved = resource.resolve(normalizedArgs.args);
208
+ if (resolved && typeof (resolved as unknown as { then?: unknown }).then === "function") {
209
+ void Promise.resolve(resolved).catch(() => {});
210
+ throw new Error("Workflow resource resolve must be synchronous.");
211
+ }
212
+ if (!isPlainRecord(resolved)) throw new Error("Workflow resource resolve must return an expansion or error object.");
213
+ if ("error" in resolved) {
214
+ if (Object.keys(resolved).some((key) => key !== "error") || typeof resolved.error !== "string" || !resolved.error.trim()) throw new Error("Workflow resource returned an invalid error.");
215
+ return { ok: false, error: resolved.error };
216
+ }
217
+ const { script, hostCommands } = resolved;
218
+ if (Object.keys(resolved).some((key) => key !== "script" && key !== "hostCommands") || typeof script !== "string" || !script.trim()) throw new Error("Workflow resource returned an invalid expansion.");
133
219
  const resourceId = randomUUID();
134
220
  const permit = createWorkflowResourcePermit({
135
221
  resourceName: resource.name,
136
222
  resourceVersion: resource.version,
137
223
  resourceId,
138
- scriptDigest: stableJsonDigest(resolved.script),
139
- authority: resolved.authority,
224
+ scriptDigest: stableJsonDigest(script),
225
+ authority: { host: hostCommands },
140
226
  });
141
- const provenance: WorkflowResourceProvenanceV1 = Object.freeze({
227
+ const provenance: WorkflowResourceProvenance = Object.freeze({
142
228
  kind: "workflow",
143
229
  name: resource.name,
144
230
  version: resource.version,
@@ -146,5 +232,5 @@ export function resolveWorkflowResource(nameValue: unknown, argsValue?: unknown)
146
232
  expansion: "resolved",
147
233
  id: resourceId,
148
234
  });
149
- return { ok: true, resource: { script: resolved.script, permit, provenance } };
235
+ return { ok: true, resource: { script, permit, provenance } };
150
236
  }
@@ -209,6 +209,8 @@ export function planWorkflowSettlement(input: {
209
209
  if (!resolution) resolution = classifyWorkflowSettlement(status);
210
210
  }
211
211
  const recovery = workflowRecoveryActions(receipt);
212
+ delete status.workflowReceiptPath;
213
+ if (receipt && input.receiptPath) status.workflowReceiptPath = input.receiptPath;
212
214
  if (receipt) {
213
215
  receipt = {
214
216
  ...receipt,
@@ -233,6 +235,7 @@ export function planWorkflowSettlement(input: {
233
235
  timestamp: now,
234
236
  };
235
237
  const terminal = status.state === "complete" || status.state === "failed" || status.state === "partial" || status.state === "stopped";
238
+ if (!status.workflowReceiptPath) delete publicResult.workflowReceipt;
236
239
  const completionEvent = terminal ? {
237
240
  type: "subagent.workflow.completed",
238
241
  state: status.state,
@@ -1,373 +0,0 @@
1
- import * as fs from "node:fs";
2
- import * as path from "node:path";
3
- import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
4
- import { TEMP_ROOT_DIR } from "../../shared/types.ts";
5
- import { getAgentDir } from "../../shared/utils.ts";
6
-
7
- export const EXCLUSIONS_PATH_ENV = "PI_MODEL_EXCLUSIONS_PATH";
8
-
9
- type ModelExclusionTarget = { modelId: string; provider?: string } | { provider: string; modelId?: never };
10
-
11
- export type ModelExclusion = ModelExclusionTarget & {
12
- reason?: string;
13
- recordedAt: number;
14
- expiresAt: number;
15
- };
16
-
17
- type RecordModelFailureOptions = ModelExclusionTarget & {
18
- reason?: string;
19
- ttlMs?: number;
20
- };
21
-
22
- let exclusions: ModelExclusion[] = [];
23
- let loaded = false;
24
- /** Default duration for a new model exclusion when no per-record TTL is supplied. */
25
- export const DEFAULT_MODEL_EXCLUSION_TTL_MS = 24 * 60 * 60_000;
26
- /** Keeps a new expiry safely below JavaScript's maximum Date timestamp. */
27
- export const MAX_MODEL_EXCLUSION_TTL_MS = 8_000_000_000_000_000;
28
- const MAX_DATE_TIMESTAMP_MS = 8_640_000_000_000_000;
29
- let defaultTTLMs = DEFAULT_MODEL_EXCLUSION_TTL_MS;
30
- let loadedTTLCeilingMs: number | undefined;
31
- let persistTimer: ReturnType<typeof setTimeout> | null = null;
32
- let persistSeq = 0;
33
-
34
- const AUTH_FAILURE_PATTERNS = [
35
- /auth(?:entication)?/i,
36
- /unauthori[sz]ed/i,
37
- /forbidden/i,
38
- /api key/i,
39
- /token expired/i,
40
- /invalid key/i,
41
- ];
42
-
43
- function isAuthModelExclusion(entry: ModelExclusion): boolean {
44
- const reason = entry.reason;
45
- return typeof reason === "string" && AUTH_FAILURE_PATTERNS.some((pattern) => pattern.test(reason));
46
- }
47
-
48
- function getAuthStoreMtimeMs(): number | undefined {
49
- const authStorePath = path.join(getAgentDir(), "auth.json");
50
- try {
51
- const stats = fs.statSync(authStorePath);
52
- return stats.isFile() && Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : undefined;
53
- } catch (error) {
54
- if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
55
- console.error(`[model-exclusions] Failed to stat Pi auth store at ${authStorePath}; preserving auth-related exclusions:`, error);
56
- }
57
- return undefined;
58
- }
59
- }
60
-
61
- function invalidateAuthExclusions(): void {
62
- if (!exclusions.some(isAuthModelExclusion)) return;
63
- const authStoreMtimeMs = getAuthStoreMtimeMs();
64
- if (authStoreMtimeMs === undefined) return;
65
- const retained = exclusions.filter((entry) => !isAuthModelExclusion(entry) || authStoreMtimeMs <= entry.recordedAt);
66
- if (retained.length === exclusions.length) return;
67
- exclusions = retained;
68
- schedulePersist();
69
- }
70
-
71
- /**
72
- * Override the default TTL applied to newly recorded model exclusions.
73
- *
74
- * @param ms Duration in milliseconds. Must be finite and positive.
75
- * @returns Nothing.
76
- */
77
- // TEST:test/unit/model-exclusions.test.ts[model exclusions — TTL expiry]
78
- export function setDefaultTTL(ms: number, options?: { shortenExisting?: boolean }): void {
79
- if (!Number.isFinite(ms) || ms <= 0 || ms > MAX_MODEL_EXCLUSION_TTL_MS) {
80
- throw new Error(`Default model exclusion TTL must be a finite positive number no greater than ${MAX_MODEL_EXCLUSION_TTL_MS}.`);
81
- }
82
- defaultTTLMs = ms;
83
- loadedTTLCeilingMs = options?.shortenExisting ? ms : undefined;
84
- if (loaded && loadedTTLCeilingMs !== undefined && shortenExclusionsToTTL(exclusions, loadedTTLCeilingMs, Date.now())) schedulePersist();
85
- }
86
-
87
- /**
88
- * Resolve the persistence path. Honors PI_MODEL_EXCLUSIONS_PATH; defaults to
89
- * <TEMP_ROOT_DIR>/model-exclusions.json. Resolved lazily so tests can point the
90
- * store at an isolated location after module load.
91
- */
92
- export function getExclusionsFilePath(): string {
93
- const envPath = process.env[EXCLUSIONS_PATH_ENV];
94
- if (typeof envPath === "string" && envPath.trim()) return envPath.trim();
95
- return path.join(TEMP_ROOT_DIR, "model-exclusions.json");
96
- }
97
-
98
- /**
99
- * Persist exclusions to disk immediately (atomic write via tmp + rename).
100
- * The store otherwise debounces writes; call this when durability matters
101
- * (and in tests).
102
- */
103
- export function flushPersist(): void {
104
- const file = getExclusionsFilePath();
105
- try {
106
- fs.mkdirSync(path.dirname(file), { recursive: true });
107
- const tmpPath = `${file}.${process.pid}.${persistSeq++}.tmp`;
108
- fs.writeFileSync(tmpPath, JSON.stringify({
109
- version: 1,
110
- exclusions: deduplicate(exclusions),
111
- }, null, 2), "utf-8");
112
- fs.renameSync(tmpPath, file);
113
- } catch (error) {
114
- console.error(`[model-exclusions] Failed to persist exclusions to ${file}:`, error);
115
- }
116
- }
117
-
118
- function schedulePersist(): void {
119
- if (persistTimer) clearTimeout(persistTimer);
120
- persistTimer = setTimeout(() => {
121
- persistTimer = null;
122
- flushPersist();
123
- }, 5000);
124
- // Never hold the process open just to flush exclusions.
125
- persistTimer.unref?.();
126
- }
127
-
128
- function ensureLoaded(): void {
129
- if (loaded) return;
130
- loaded = true;
131
- try {
132
- const raw = fs.readFileSync(getExclusionsFilePath(), "utf-8");
133
- const data = JSON.parse(raw);
134
- if (data.version === 1) {
135
- if (!Array.isArray(data.exclusions)) throw new Error("Model exclusion store version 1 must contain an exclusions array.");
136
- const now = Date.now();
137
- let droppedInvalid = false;
138
- exclusions = data.exclusions.flatMap((entry: unknown, index: number) => {
139
- const result = readPersistedExclusion(entry, index);
140
- if (!result.ok) {
141
- droppedInvalid = true;
142
- console.warn(`[model-exclusions] Ignoring invalid exclusion: ${result.message}`);
143
- return [];
144
- }
145
- return [result.exclusion];
146
- }).filter((e: ModelExclusion) => e.expiresAt > now);
147
- const shortened = loadedTTLCeilingMs !== undefined && shortenExclusionsToTTL(exclusions, loadedTTLCeilingMs, now);
148
- exclusions = deduplicate(exclusions);
149
- if (droppedInvalid) flushPersist();
150
- else if (shortened) schedulePersist();
151
- }
152
- invalidateAuthExclusions();
153
- } catch (error) {
154
- if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
155
- console.error(`[model-exclusions] Failed to load exclusions from ${getExclusionsFilePath()}:`, error);
156
- }
157
- }
158
- }
159
-
160
- type PersistedExclusionRead =
161
- | { ok: true; exclusion: ModelExclusion }
162
- | { ok: false; message: string };
163
-
164
- function invalidPersistedExclusion(index: number, message: string): PersistedExclusionRead {
165
- return { ok: false, message: `Model exclusion store entry ${index} ${message}.` };
166
- }
167
-
168
- function readPersistedExclusion(entry: unknown, index: number): PersistedExclusionRead {
169
- if (!entry || typeof entry !== "object" || Array.isArray(entry)) return invalidPersistedExclusion(index, "must be an object");
170
- const candidate = entry as { modelId?: unknown; provider?: unknown; reason?: unknown; recordedAt?: unknown; expiresAt?: unknown };
171
- const { modelId, provider, reason } = candidate;
172
- if (modelId !== undefined && (typeof modelId !== "string" || modelId.length === 0)) return invalidPersistedExclusion(index, "has an invalid modelId");
173
- if (provider !== undefined && (typeof provider !== "string" || provider.length === 0)) return invalidPersistedExclusion(index, "has an invalid provider");
174
- if (reason !== undefined && typeof reason !== "string") return invalidPersistedExclusion(index, "has an invalid reason");
175
- const { recordedAt, expiresAt } = candidate;
176
- if (typeof recordedAt !== "number" || !Number.isFinite(recordedAt) || recordedAt <= 0 || recordedAt > MAX_DATE_TIMESTAMP_MS) return invalidPersistedExclusion(index, "has an invalid recordedAt");
177
- if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= 0 || expiresAt > MAX_DATE_TIMESTAMP_MS) return invalidPersistedExclusion(index, "has an invalid expiresAt");
178
- const metadata = { ...(reason === undefined ? {} : { reason }), recordedAt, expiresAt };
179
- if (modelId === undefined) {
180
- if (provider === undefined) return invalidPersistedExclusion(index, "must include modelId or provider");
181
- return { ok: true, exclusion: { provider, ...metadata } };
182
- }
183
- return { ok: true, exclusion: { modelId, ...(provider === undefined ? {} : { provider }), ...metadata } };
184
- }
185
-
186
- function dedupKey(entry: ModelExclusion): string {
187
- return `${entry.provider ?? ""}|${entry.modelId ?? ""}`;
188
- }
189
-
190
- function deduplicate(items: ModelExclusion[]): ModelExclusion[] {
191
- const map = new Map<string, ModelExclusion>();
192
- for (const entry of items) {
193
- const key = dedupKey(entry);
194
- const existing = map.get(key);
195
- if (!existing || entry.recordedAt > existing.recordedAt) {
196
- map.set(key, entry);
197
- }
198
- }
199
- return Array.from(map.values());
200
- }
201
-
202
- /**
203
- * Record a model failure as a temporary exclusion. While the exclusion is
204
- * active, {@link isExcluded} returns true for the model (or for every model of
205
- * the provider when modelId is omitted), and {@link filterFallbackCandidates}
206
- * removes matching candidates from fallback lists.
207
- */
208
- export function recordModelFailure(options: RecordModelFailureOptions): void {
209
- ensureLoaded();
210
- const ttl = options.ttlMs ?? defaultTTLMs;
211
- const now = Date.now();
212
- const target: ModelExclusionTarget = options.modelId !== undefined
213
- ? { modelId: options.modelId, ...(options.provider ? { provider: options.provider } : {}) }
214
- : { provider: options.provider };
215
- const exclusion: ModelExclusion = {
216
- ...target,
217
- reason: options.reason ?? "runtime-failure",
218
- recordedAt: now,
219
- expiresAt: now + ttl,
220
- };
221
- exclusions.unshift(exclusion);
222
- exclusions = deduplicate(exclusions);
223
- if (exclusions.length > 200) exclusions.length = 200;
224
- flushPersist();
225
- }
226
-
227
- /**
228
- * Drop all expired exclusions from memory and schedule a persist.
229
- */
230
- export function clearExpiredExclusions(): void {
231
- ensureLoaded();
232
- invalidateAuthExclusions();
233
- prune(exclusions, Date.now());
234
- schedulePersist();
235
- }
236
-
237
- /**
238
- * Remove every exclusion (e.g. after the operator fixes credentials).
239
- */
240
- export function clearExclusions(): void {
241
- ensureLoaded();
242
- exclusions.length = 0;
243
- schedulePersist();
244
- }
245
-
246
- /**
247
- * Whether an exclusion entry matches a candidate.
248
- *
249
- * Semantics:
250
- * - Entry with modelId: model-specific exclusion. Matches only that modelId;
251
- * when both the entry and the candidate carry a provider, the providers must
252
- * also agree so `openai/gpt-4` does not exclude `github-copilot/gpt-4`.
253
- * - Entry without modelId: provider-wide exclusion (e.g. quota or auth failure).
254
- * Matches every model of that provider.
255
- */
256
- function entryMatches(entry: ModelExclusion, candidateModelId: string, candidateProvider: string | undefined, now: number): boolean {
257
- if (entry.expiresAt <= now) return false;
258
- if (entry.modelId !== undefined) {
259
- if (entry.modelId !== candidateModelId) return false;
260
- return !entry.provider || !candidateProvider || entry.provider === candidateProvider;
261
- }
262
- return Boolean(entry.provider) && entry.provider === candidateProvider;
263
- }
264
-
265
- /**
266
- * Whether a model (or its provider) is currently excluded.
267
- */
268
- export function isExcluded(modelId: string, provider: string): boolean {
269
- ensureLoaded();
270
- invalidateAuthExclusions();
271
- return exclusions.some((entry) => entryMatches(entry, modelId, provider, Date.now()));
272
- }
273
-
274
- /**
275
- * Return the active exclusion matching a full model id, if any.
276
- *
277
- * The caller uses this for hard-fail diagnostics; fallback filtering should
278
- * continue to use {@link filterFallbackCandidates}.
279
- */
280
- export function findModelExclusion(fullId: string, now = Date.now()): Readonly<ModelExclusion> | undefined {
281
- ensureLoaded();
282
- invalidateAuthExclusions();
283
- const { provider, modelId } = parseModelKey(fullId);
284
- return exclusions.find((entry) => entryMatches(entry, modelId, provider, now));
285
- }
286
-
287
- /**
288
- * Number of live (non-expired) exclusions.
289
- */
290
- export function getExcludedCount(): number {
291
- ensureLoaded();
292
- clearExpiredExclusions();
293
- return exclusions.length;
294
- }
295
-
296
- /**
297
- * Split a candidate fullId into its provider + modelId components.
298
- *
299
- * A fullId may carry a thinking suffix (`provider/model:thinking`) which is
300
- * stripped before parsing, and the modelId itself may contain slashes
301
- * (e.g. `openrouter/google/gemini-flash`). The first `/`-segment is the
302
- * provider; everything after is the modelId. This MUST stay in lock-step with
303
- * the matching inside {@link isExcluded} so that a failure recorded via
304
- * {@link recordModelFailure} is later recognised by the candidate filter.
305
- */
306
- export function parseModelKey(fullId: string): { provider?: string; modelId: string } {
307
- const base = splitKnownThinkingSuffix(fullId).baseModel;
308
- if (!base.includes("/")) return { modelId: base };
309
- const slash = base.indexOf("/");
310
- return { provider: base.slice(0, slash), modelId: base.slice(slash + 1) };
311
- }
312
-
313
- /**
314
- * Filter a list of candidate fullIds, removing excluded models/providers and
315
- * duplicates while preserving order.
316
- */
317
- export function filterFallbackCandidates(candidates: string[], opts?: {
318
- now?: number;
319
- onExcluded?: (candidate: string, exclusion: Readonly<ModelExclusion>) => void;
320
- }): string[] {
321
- ensureLoaded();
322
- invalidateAuthExclusions();
323
- const timestamp = opts?.now ?? Date.now();
324
- const seen = new Set<string>();
325
- const filtered: string[] = [];
326
- for (const raw of candidates) {
327
- if (!raw || seen.has(raw)) continue;
328
- const { provider: candidateProvider, modelId: candidateModelId } = parseModelKey(raw);
329
- const exclusion = exclusions.find((entry) => entryMatches(entry, candidateModelId, candidateProvider, timestamp));
330
- if (exclusion) {
331
- opts?.onExcluded?.(raw, exclusion);
332
- continue;
333
- }
334
- seen.add(raw);
335
- filtered.push(raw);
336
- }
337
- return filtered;
338
- }
339
-
340
- /**
341
- * Reload exclusions from disk (for tests and config hot-reload).
342
- * Discards any in-memory-only exclusions that were not yet persisted.
343
- */
344
- export function reloadFromDisk(): void {
345
- loaded = false;
346
- exclusions = [];
347
- ensureLoaded();
348
- }
349
-
350
- function prune(items: ModelExclusion[], now: number): void {
351
- let write = 0;
352
- for (let i = 0; i < items.length; i++) {
353
- const entry = items[i]!;
354
- if (entry.expiresAt > now) {
355
- items[write++] = entry;
356
- }
357
- }
358
- items.length = write;
359
- }
360
-
361
- function shortenExclusionsToTTL(items: ModelExclusion[], ttlMs: number, now: number): boolean {
362
- let changed = false;
363
- for (const entry of items) {
364
- const configuredExpiry = entry.recordedAt + ttlMs;
365
- if (entry.expiresAt > configuredExpiry) {
366
- entry.expiresAt = configuredExpiry;
367
- changed = true;
368
- }
369
- }
370
- const previousLength = items.length;
371
- prune(items, now);
372
- return changed || items.length !== previousLength;
373
- }