@xzzpig/pi-subagents 0.18.0 → 0.20.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 +129 -0
- package/README.md +1 -1
- package/docs/agents.md +32 -16
- package/docs/configuration.md +76 -9
- package/docs/extension-api.md +6 -5
- package/docs/missions.md +28 -14
- package/docs/models.md +8 -4
- package/docs/observability.md +10 -5
- package/docs/standalone-background.md +1 -1
- package/docs/tool-reference.md +90 -88
- package/docs/workflows.md +171 -173
- package/node_modules/@xzzpig/pi-components/package.json +4 -4
- package/package.json +6 -6
- package/prompts/review-loop.md +1 -1
- package/skills/council-mode/SKILL.md +1 -1
- package/skills/pi-subagents/SKILL.md +12 -5
- package/skills/pi-subagents/references/constraints-and-recipes.md +3 -3
- package/skills/pi-subagents/references/execution-controls.md +68 -67
- package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
- package/skills/pi-subagents/references/multi-lane-orchestration.md +1 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +45 -48
- package/src/agents/advertised-agent-prompt.ts +21 -41
- package/src/agents/agent-management.ts +2 -2
- package/src/agents/agents.ts +66 -3
- package/src/api/preflight.ts +109 -63
- package/src/extension/config.ts +15 -4
- package/src/extension/control-notices.ts +3 -0
- package/src/extension/doctor.ts +1 -0
- package/src/extension/fanout-child.ts +12 -3
- package/src/extension/herdr-pi-bridge.ts +2 -0
- package/src/extension/index.ts +90 -174
- package/src/extension/public-execution.ts +72 -35
- package/src/extension/reply-workflow-script.ts +58 -0
- package/src/extension/rpc.ts +29 -10
- package/src/extension/schemas.ts +40 -135
- package/src/extension/tool-activation.ts +57 -108
- package/src/extension/tool-description.ts +62 -27
- package/src/extension/upgrade-notice.ts +40 -0
- package/src/integrations/herdr-status.ts +19 -3
- package/src/intercom/native-supervisor-channel.ts +4 -1
- package/src/missions/goal-driver.ts +44 -31
- package/src/missions/store.ts +10 -1
- package/src/profiles/profiles.ts +5 -2
- package/src/runs/background/async-execution.ts +146 -59
- package/src/runs/background/async-job-tracker.ts +66 -24
- package/src/runs/background/async-retention.ts +46 -16
- package/src/runs/background/await-async-run.ts +78 -0
- package/src/runs/background/chain-root-attachment.ts +4 -4
- package/src/runs/background/control-channel.ts +61 -2
- package/src/runs/background/notify.ts +5 -0
- package/src/runs/background/run-child-session.ts +17 -7
- package/src/runs/background/run-status.ts +6 -0
- package/src/runs/background/runner-aliases.ts +37 -6
- package/src/runs/background/runner-child-launch.ts +3 -0
- package/src/runs/background/scheduled-runs.ts +33 -18
- package/src/runs/background/stale-run-reconciler.ts +13 -2
- package/src/runs/background/subagent-runner.ts +58 -5
- package/src/runs/foreground/async-stop-action.ts +17 -3
- package/src/runs/foreground/command-action.ts +41 -0
- package/src/runs/foreground/execution.ts +145 -131
- package/src/runs/foreground/subagent-executor.ts +546 -296
- package/src/runs/shared/async-status-projection.ts +5 -0
- package/src/runs/shared/child-commands.ts +228 -0
- package/src/runs/shared/child-launch.ts +15 -2
- package/src/runs/shared/child-session.ts +184 -24
- package/src/runs/shared/child-tool-plan.ts +16 -4
- package/src/runs/shared/claude-code-adapter.ts +157 -2
- package/src/runs/shared/dynamic-fanout.ts +2 -2
- package/src/runs/shared/external-cli-preflight.ts +54 -6
- package/src/runs/shared/external-cli-runner.ts +5 -1
- package/src/runs/shared/mcp-config-sources.ts +2 -1
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -11
- package/src/runs/shared/model-resolution.ts +38 -10
- package/src/runs/shared/model-scope.ts +28 -9
- package/src/runs/shared/nested-events.ts +55 -55
- package/src/runs/shared/parallel-utils.ts +4 -0
- package/src/runs/shared/pi-spawn.ts +7 -95
- package/src/runs/shared/run-history.ts +87 -0
- package/src/runs/shared/subagent-control.ts +32 -17
- package/src/runs/shared/subagent-prompt-runtime.ts +14 -6
- package/src/runs/shared/worktree.ts +1 -1
- package/src/shared/disabled-features.ts +123 -0
- package/src/shared/extension-context.ts +13 -0
- package/src/shared/model-info.ts +9 -0
- package/src/shared/required-child-extensions.ts +39 -5
- package/src/shared/settings.ts +1 -1
- package/src/shared/types.ts +27 -1
- package/src/slash/prompt-template-bridge.ts +2 -2
- package/src/slash/slash-commands.ts +10 -5
- package/src/slash/subagent-cost.ts +9 -5
- package/src/slash/subagents-admin.ts +24 -24
- package/src/tui/fleet-status.ts +14 -6
- package/src/tui/fleet.ts +14 -2
- package/src/tui/render.ts +117 -56
- package/src/tui/running-tone.ts +28 -0
- package/src/watchdog/diff-tool.ts +23 -9
- package/src/watchdog/register-child.ts +3 -3
- package/src/watchdog/register-main.ts +3 -3
- package/src/watchdog/review.ts +2 -2
- package/src/watchdog/turn-delta.ts +1 -1
- package/src/workflows/chat-progress.ts +2 -2
- package/src/workflows/scripted-workflow.ts +117 -37
- package/src/workflows/structured-workflow-scripts.ts +177 -0
- package/src/workflows/workflow-checklist.ts +6 -0
- package/src/workflows/workflow-receipt.ts +10 -4
- package/src/workflows/workflow-resources.ts +44 -16
- package/src/workflows/workflow-reuse.ts +120 -0
- package/src/workflows/workflow-revival.ts +123 -0
|
@@ -6,6 +6,7 @@ import type { WorkflowReceiptResumeReference, WorkflowScriptChildResult } from "
|
|
|
6
6
|
import { parseWorkflowChildSummary } from "./workflow-child-summary.ts";
|
|
7
7
|
import { HOST_STEP_MAX_COUNT, assertUniqueHostStepIds, parseHostStepNode } from "../runs/shared/host-step-status.ts";
|
|
8
8
|
import { assertWorkflowLaneKey, normalizeWorkflowLaneMetadata } from "../runs/shared/lane-metadata.ts";
|
|
9
|
+
import { projectWorkflowKeyRevival } from "./workflow-revival.ts";
|
|
9
10
|
|
|
10
11
|
export type { WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState } from "../shared/types.ts";
|
|
11
12
|
|
|
@@ -320,9 +321,9 @@ export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string)
|
|
|
320
321
|
if ((error as NodeJS.ErrnoException).code === "ENOENT") {
|
|
321
322
|
const workflowDir = path.dirname(receiptPath);
|
|
322
323
|
if (fs.existsSync(path.join(workflowDir, "status.json")) || fs.existsSync(path.join(workflowDir, "events.jsonl"))) {
|
|
323
|
-
throw new Error(`Workflow receipt '${workflowRunId}' is not available because the workflow may still be active or terminal receipt writing failed. Use direct child run IDs from status/events for direct resume after the normal retained-child checks
|
|
324
|
+
throw new Error(`Workflow receipt '${workflowRunId}' is not available because the workflow may still be active or terminal receipt writing failed. Use direct child run IDs from status/events for direct resume after the normal retained-child checks.`, { cause: error });
|
|
324
325
|
}
|
|
325
|
-
throw new Error(`Workflow receipt '${workflowRunId}' was not found
|
|
326
|
+
throw new Error(`Workflow receipt '${workflowRunId}' was not found.`, { cause: error });
|
|
326
327
|
}
|
|
327
328
|
throw new Error(`Workflow receipt '${workflowRunId}' could not be read: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
|
|
328
329
|
}
|
|
@@ -362,8 +363,13 @@ export function resolveWorkflowReceiptResumeEntry(input: {
|
|
|
362
363
|
if (input.reference.latest !== true) throw new Error("Keyed workflow receipt resume requires latest: true.");
|
|
363
364
|
const key = assertKey(input.reference.key, "keyed resume key");
|
|
364
365
|
const receipt = readWorkflowReceipt(input.asyncDirRoot, input.reference.workflowRunId.trim());
|
|
365
|
-
const
|
|
366
|
-
if (!
|
|
366
|
+
const recorded = receipt.entries[key];
|
|
367
|
+
if (!recorded) throw new Error(`Workflow receipt '${receipt.workflowRunId}' has no child key '${key}'.`);
|
|
368
|
+
// A detached top-level revival after the receipt was written continues this key's lineage.
|
|
369
|
+
const revival = recorded.latestRunId ? projectWorkflowKeyRevival(input.asyncDirRoot, receipt.workflowRunId, key, recorded.latestRunId) : undefined;
|
|
370
|
+
const entry = revival
|
|
371
|
+
? { ...recorded, latestRunId: revival.latestRunId, continuation: { runIds: [...recorded.continuation.runIds, ...revival.revivedRunIds] } }
|
|
372
|
+
: recorded;
|
|
367
373
|
assertResumableEntry(entry, receipt.workflowRunId, key);
|
|
368
374
|
input.assertResumable?.(entry.latestRunId);
|
|
369
375
|
return entry;
|
|
@@ -6,9 +6,13 @@ import {
|
|
|
6
6
|
type WorkflowResourcePermit,
|
|
7
7
|
} from "../shared/workflow-child-permit.ts";
|
|
8
8
|
import type { WorkflowResourceProvenance } from "../shared/types.ts";
|
|
9
|
+
import { buildStructuredWorkflowScript, isPlainRecord } from "./structured-workflow-scripts.ts";
|
|
9
10
|
|
|
10
11
|
const RESOURCE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
|
|
11
|
-
const MAX_ARGS_BYTES = 16 * 1024;
|
|
12
|
+
export const MAX_ARGS_BYTES = 16 * 1024;
|
|
13
|
+
export const MAX_ARGS_FIELDS = 16;
|
|
14
|
+
export const MAX_ARGS_ITEMS = 64;
|
|
15
|
+
export const MAX_ARGS_DEPTH = 8;
|
|
12
16
|
const MAX_STRING_BYTES = 16 * 1024;
|
|
13
17
|
|
|
14
18
|
export interface ResolvedWorkflowResource {
|
|
@@ -65,7 +69,7 @@ export function registerWorkflowResource(input: RegisterWorkflowResourceInput):
|
|
|
65
69
|
if (typeof name !== "string" || !RESOURCE_NAME_PATTERN.test(name)) throw new Error("Workflow definition requires a safe resource name.");
|
|
66
70
|
if (!Number.isSafeInteger(version) || version < 1) throw new Error("Workflow definition version must be a positive safe integer.");
|
|
67
71
|
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.`);
|
|
72
|
+
if (findWorkflowResource(name) || STRUCTURED_WORKFLOW_RESOURCE_NAMES.includes(name)) throw new Error(`Workflow resource '${name}' is a protected builtin.`);
|
|
69
73
|
const current = registry();
|
|
70
74
|
const bucket = current.bySession.get(sessionId) ?? new Map<string, WorkflowResourceDefinition>();
|
|
71
75
|
if (!(bucket instanceof Map)) throw new Error("Malformed workflow resource session registry.");
|
|
@@ -84,12 +88,6 @@ export function registerWorkflowResource(input: RegisterWorkflowResourceInput):
|
|
|
84
88
|
};
|
|
85
89
|
}
|
|
86
90
|
|
|
87
|
-
function isPlainRecord(value: unknown): value is Record<string, unknown> {
|
|
88
|
-
if (!value || typeof value !== "object" || Array.isArray(value)) return false;
|
|
89
|
-
const prototype = Object.getPrototypeOf(value);
|
|
90
|
-
return prototype === Object.prototype || prototype === null;
|
|
91
|
-
}
|
|
92
|
-
|
|
93
91
|
function jsonByteLength(value: unknown): number {
|
|
94
92
|
try {
|
|
95
93
|
const encoded = JSON.stringify(value);
|
|
@@ -101,7 +99,7 @@ function jsonByteLength(value: unknown): number {
|
|
|
101
99
|
}
|
|
102
100
|
|
|
103
101
|
function validatePlainJson(value: unknown, path: string, depth = 0): void {
|
|
104
|
-
if (depth >
|
|
102
|
+
if (depth > MAX_ARGS_DEPTH) throw new Error(`${path} is too deeply nested.`);
|
|
105
103
|
if (value === null || typeof value === "boolean") return;
|
|
106
104
|
if (typeof value === "string") {
|
|
107
105
|
if (!value.trim()) throw new Error(`${path} must not be empty.`);
|
|
@@ -113,12 +111,12 @@ function validatePlainJson(value: unknown, path: string, depth = 0): void {
|
|
|
113
111
|
return;
|
|
114
112
|
}
|
|
115
113
|
if (Array.isArray(value)) {
|
|
116
|
-
if (value.length >
|
|
114
|
+
if (value.length > MAX_ARGS_ITEMS) throw new Error(`${path} contains too many items.`);
|
|
117
115
|
for (const [index, entry] of value.entries()) validatePlainJson(entry, `${path}[${index}]`, depth + 1);
|
|
118
116
|
return;
|
|
119
117
|
}
|
|
120
118
|
if (!isPlainRecord(value)) throw new Error(`${path} must contain plain JSON data.`);
|
|
121
|
-
if (Object.keys(value).length >
|
|
119
|
+
if (Object.keys(value).length > MAX_ARGS_FIELDS) throw new Error(`${path} contains too many fields.`);
|
|
122
120
|
for (const [key, entry] of Object.entries(value)) {
|
|
123
121
|
if (!key.trim()) throw new Error(`${path} contains an empty field name.`);
|
|
124
122
|
validatePlainJson(entry, `${path}.${key}`, depth + 1);
|
|
@@ -186,6 +184,32 @@ function listWorkflowResourceNames(): string[] {
|
|
|
186
184
|
return WORKFLOW_RESOURCES.map((resource) => resource.name);
|
|
187
185
|
}
|
|
188
186
|
|
|
187
|
+
/** Internal resources for the data-only tasks/chain inputs: reserved against registration, never resolvable or listed by name. */
|
|
188
|
+
const STRUCTURED_WORKFLOW_RESOURCE_NAMES: readonly string[] = ["tasks", "chain"];
|
|
189
|
+
const STRUCTURED_WORKFLOW_RESOURCE_VERSION = 1;
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* Expand data-only `tasks` or `chain` input into a package-owned workflow script with a one-use permit.
|
|
193
|
+
* Only the executor calls this, after its own feature and input checks; public named lookup cannot reach it.
|
|
194
|
+
*/
|
|
195
|
+
export function resolveStructuredWorkflowResource(input: { kind: "tasks" | "chain"; steps: unknown; task?: unknown }): WorkflowResourceResolution {
|
|
196
|
+
try {
|
|
197
|
+
if (!isPlainRecord(input) || (input.kind !== "tasks" && input.kind !== "chain")) return { ok: false, error: "Structured workflow kind must be 'tasks' or 'chain'." };
|
|
198
|
+
const { kind, steps, task } = input;
|
|
199
|
+
if (!Array.isArray(steps) || steps.length === 0) return { ok: false, error: `${kind} must be a non-empty array.` };
|
|
200
|
+
validatePlainJson(steps, kind);
|
|
201
|
+
if (task !== undefined) {
|
|
202
|
+
if (typeof task !== "string" || !task.trim()) return { ok: false, error: "task must be a non-empty string when provided." };
|
|
203
|
+
validatePlainJson(task, "task");
|
|
204
|
+
}
|
|
205
|
+
if (jsonByteLength({ [kind]: steps, task }) > MAX_ARGS_BYTES) return { ok: false, error: `${kind} input exceeds ${MAX_ARGS_BYTES} bytes.` };
|
|
206
|
+
const script = buildStructuredWorkflowScript(kind, JSON.parse(JSON.stringify(steps)), task);
|
|
207
|
+
return { ok: true, resource: issueWorkflowResource(kind, STRUCTURED_WORKFLOW_RESOURCE_VERSION, script) };
|
|
208
|
+
} catch (error) {
|
|
209
|
+
return { ok: false, error: error instanceof Error ? error.message.slice(0, 4096) : "Structured workflow resolution failed." };
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
|
|
189
213
|
/** Resolve only extension-owned resources so policy can distinguish them from raw scripts; caller-provided script text is never consulted. */
|
|
190
214
|
export function resolveWorkflowResource(nameValue: unknown, argsValue?: unknown, sessionId?: string): WorkflowResourceResolution {
|
|
191
215
|
try {
|
|
@@ -216,21 +240,25 @@ function resolveResource(nameValue: unknown, argsValue?: unknown, sessionId?: st
|
|
|
216
240
|
}
|
|
217
241
|
const { script, hostCommands } = resolved;
|
|
218
242
|
if (Object.keys(resolved).some((key) => key !== "script" && key !== "hostCommands") || typeof script !== "string" || !script.trim()) throw new Error("Workflow resource returned an invalid expansion.");
|
|
243
|
+
return { ok: true, resource: issueWorkflowResource(resource.name, resource.version, script, hostCommands) };
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
function issueWorkflowResource(name: string, version: number, script: string, hostCommands?: readonly WorkflowResourceHostAuthority[]): ResolvedWorkflowResource {
|
|
219
247
|
const resourceId = randomUUID();
|
|
220
248
|
const permit = createWorkflowResourcePermit({
|
|
221
|
-
resourceName:
|
|
222
|
-
resourceVersion:
|
|
249
|
+
resourceName: name,
|
|
250
|
+
resourceVersion: version,
|
|
223
251
|
resourceId,
|
|
224
252
|
scriptDigest: stableJsonDigest(script),
|
|
225
253
|
authority: { host: hostCommands },
|
|
226
254
|
});
|
|
227
255
|
const provenance: WorkflowResourceProvenance = Object.freeze({
|
|
228
256
|
kind: "workflow",
|
|
229
|
-
name
|
|
230
|
-
version
|
|
257
|
+
name,
|
|
258
|
+
version,
|
|
231
259
|
invocation: "named",
|
|
232
260
|
expansion: "resolved",
|
|
233
261
|
id: resourceId,
|
|
234
262
|
});
|
|
235
|
-
return {
|
|
263
|
+
return { script, permit, provenance };
|
|
236
264
|
}
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import * as fs from "node:fs";
|
|
3
|
+
import * as path from "node:path";
|
|
4
|
+
import { readRecentTerminalRunIndex } from "../runs/background/terminal-run-index.ts";
|
|
5
|
+
import { readStatus } from "../shared/utils.ts";
|
|
6
|
+
import { workflowRunParamsFingerprint, type WorkflowScriptChildResult } from "./scripted-workflow.ts";
|
|
7
|
+
|
|
8
|
+
/** Stop cause recorded when the extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
|
|
9
|
+
const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
|
|
10
|
+
type WorkflowStopCause = typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED;
|
|
11
|
+
|
|
12
|
+
const WORKFLOW_CHILD_JOURNAL_FILE = "workflow-children.jsonl";
|
|
13
|
+
|
|
14
|
+
export const WORKFLOW_RUNTIME_REPLACED_RELAUNCH_NOTICE = "Async children that were still running keep running; relaunch the same workflow script with the same args to reuse finished children and re-attach to running ones.";
|
|
15
|
+
|
|
16
|
+
/** Abort reason for workflow controllers torn down by runtime replacement; carries the cause as data, not text. */
|
|
17
|
+
export function runtimeReplacedAbortReason(): Error {
|
|
18
|
+
return Object.assign(new Error("Workflow stopped because the extension session was replaced or reloaded."), { workflowStopCause: WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED });
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export function workflowStopCause(reason: unknown): WorkflowStopCause | undefined {
|
|
22
|
+
return reason instanceof Error && "workflowStopCause" in reason && reason.workflowStopCause === WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED
|
|
23
|
+
? WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED
|
|
24
|
+
: undefined;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function sha256(text: string): string {
|
|
28
|
+
return createHash("sha256").update(text).digest("hex");
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function workflowScriptDigest(script: string): string {
|
|
32
|
+
return sha256(script);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Hash of the canonical launch params the script host uses to detect duplicate keys. */
|
|
36
|
+
export function workflowChildFingerprint(params: Record<string, unknown>): string {
|
|
37
|
+
return sha256(workflowRunParamsFingerprint(params));
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
type WorkflowChildJournalRecord =
|
|
41
|
+
| { type: "start"; key: string; fingerprint: string; runId: string }
|
|
42
|
+
| { type: "settle"; key: string; fingerprint: string; result: WorkflowScriptChildResult };
|
|
43
|
+
|
|
44
|
+
/** Appends synchronously. A lost record only means a later relaunch runs that child again. */
|
|
45
|
+
export function appendWorkflowChildJournal(workflowAsyncDir: string, record: WorkflowChildJournalRecord): void {
|
|
46
|
+
const journalPath = path.join(workflowAsyncDir, WORKFLOW_CHILD_JOURNAL_FILE);
|
|
47
|
+
try {
|
|
48
|
+
fs.appendFileSync(journalPath, `${JSON.stringify(record)}\n`, "utf-8");
|
|
49
|
+
} catch (error) {
|
|
50
|
+
console.error(`Failed to append workflow child journal '${journalPath}':`, error);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
interface WorkflowReuseSource {
|
|
55
|
+
runId: string;
|
|
56
|
+
started: Map<string, { fingerprint: string; runId: string }>;
|
|
57
|
+
settled: Map<string, { fingerprint: string; result: WorkflowScriptChildResult }>;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
type WorkflowReuseMatch =
|
|
61
|
+
| { kind: "settled"; result: WorkflowScriptChildResult }
|
|
62
|
+
| { kind: "started"; runId: string };
|
|
63
|
+
|
|
64
|
+
function readWorkflowChildJournal(runId: string, workflowAsyncDir: string): WorkflowReuseSource {
|
|
65
|
+
const source: WorkflowReuseSource = { runId, started: new Map(), settled: new Map() };
|
|
66
|
+
let text = "";
|
|
67
|
+
try {
|
|
68
|
+
text = fs.readFileSync(path.join(workflowAsyncDir, WORKFLOW_CHILD_JOURNAL_FILE), "utf-8");
|
|
69
|
+
} catch {
|
|
70
|
+
return source;
|
|
71
|
+
}
|
|
72
|
+
for (const line of text.split("\n")) {
|
|
73
|
+
let record: Partial<WorkflowChildJournalRecord> | undefined;
|
|
74
|
+
try {
|
|
75
|
+
record = line.trim() ? JSON.parse(line) as Partial<WorkflowChildJournalRecord> : undefined;
|
|
76
|
+
} catch {
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
79
|
+
if (!record || typeof record.key !== "string" || typeof record.fingerprint !== "string") continue;
|
|
80
|
+
if (record.type === "start" && typeof record.runId === "string") {
|
|
81
|
+
source.started.set(record.key, { fingerprint: record.fingerprint, runId: record.runId });
|
|
82
|
+
} else if (record.type === "settle" && record.result && typeof record.result === "object") {
|
|
83
|
+
source.settled.set(record.key, { fingerprint: record.fingerprint, result: record.result });
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
return source;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* The newest terminal workflow of this session with the same script and args,
|
|
91
|
+
* when that run stopped because its runtime was replaced.
|
|
92
|
+
*/
|
|
93
|
+
export function findWorkflowReuseSource(asyncDirRoot: string, sessionId: string, scriptDigest: string, argsDigest: string | undefined): WorkflowReuseSource | undefined {
|
|
94
|
+
let runIds: string[];
|
|
95
|
+
try {
|
|
96
|
+
runIds = readRecentTerminalRunIndex(asyncDirRoot, { sessionId });
|
|
97
|
+
} catch {
|
|
98
|
+
return undefined;
|
|
99
|
+
}
|
|
100
|
+
for (const runId of runIds) {
|
|
101
|
+
const asyncDir = path.join(asyncDirRoot, runId);
|
|
102
|
+
let status: ReturnType<typeof readStatus>;
|
|
103
|
+
try {
|
|
104
|
+
status = readStatus(asyncDir);
|
|
105
|
+
} catch {
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
if (status?.mode !== "workflow" || status.workflow?.scriptDigest !== scriptDigest || status.workflow.argsDigest !== argsDigest) continue;
|
|
109
|
+
return status.workflow.stopCause === WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED ? readWorkflowChildJournal(runId, asyncDir) : undefined;
|
|
110
|
+
}
|
|
111
|
+
return undefined;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** A settled match is reusable only when that child succeeded; failed or stopped children run again. */
|
|
115
|
+
export function matchWorkflowReuse(source: WorkflowReuseSource, key: string, fingerprint: string): WorkflowReuseMatch | undefined {
|
|
116
|
+
const settled = source.settled.get(key);
|
|
117
|
+
if (settled) return settled.fingerprint === fingerprint && settled.result.ok ? { kind: "settled", result: settled.result } : undefined;
|
|
118
|
+
const started = source.started.get(key);
|
|
119
|
+
return started?.fingerprint === fingerprint ? { kind: "started", runId: started.runId } : undefined;
|
|
120
|
+
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import * as fs from "node:fs";
|
|
2
|
+
import * as path from "node:path";
|
|
3
|
+
import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
|
|
4
|
+
import type { AsyncStatus } from "../shared/types.ts";
|
|
5
|
+
import { readStatus } from "../shared/utils.ts";
|
|
6
|
+
import type { WorkflowScriptChildResult } from "./scripted-workflow.ts";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* A top-level resume of a failed async workflow child starts a detached run. These records
|
|
10
|
+
* link that run back to its workflow key without writing the workflow's own status or receipt.
|
|
11
|
+
* The source run is terminal, so the live workflow host never writes its directory.
|
|
12
|
+
*/
|
|
13
|
+
const REVIVAL_LINK_FILE = "workflow-revival.json";
|
|
14
|
+
/** The same link, kept in the revived run's directory so reviving it again keeps the key. */
|
|
15
|
+
export const REVIVAL_ORIGIN_FILE = "workflow-revival-origin.json";
|
|
16
|
+
/** Recording refuses a deeper link, so readers bounded by this always reach the chain's end. */
|
|
17
|
+
const MAX_REVIVAL_DEPTH = 16;
|
|
18
|
+
const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
|
|
19
|
+
|
|
20
|
+
interface WorkflowRevivalLink {
|
|
21
|
+
version: 1;
|
|
22
|
+
workflowRunId: string;
|
|
23
|
+
workflowKey: string;
|
|
24
|
+
sourceRunId: string;
|
|
25
|
+
revivedRunId: string;
|
|
26
|
+
/** 1 for a revival of the workflow's own child, one more for each revival of a revival. */
|
|
27
|
+
depth: number;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface WorkflowKeyRevival {
|
|
31
|
+
/** Revived runs after the given run, oldest first. */
|
|
32
|
+
revivedRunIds: string[];
|
|
33
|
+
latestRunId: string;
|
|
34
|
+
/** State of the latest revived run; undefined when its status is unreadable. */
|
|
35
|
+
state?: AsyncStatus["state"];
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function isRunId(value: unknown): value is string {
|
|
39
|
+
return typeof value === "string" && value.length > 0 && value.length <= 255 && path.basename(value) === value && value !== "." && value !== "..";
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function readLink(file: string): WorkflowRevivalLink | undefined {
|
|
43
|
+
let value: unknown;
|
|
44
|
+
try {
|
|
45
|
+
value = JSON.parse(fs.readFileSync(file, "utf-8"));
|
|
46
|
+
} catch {
|
|
47
|
+
return undefined;
|
|
48
|
+
}
|
|
49
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
|
|
50
|
+
const link = value as Record<string, unknown>;
|
|
51
|
+
if (link.version !== 1 || !isRunId(link.workflowRunId) || typeof link.workflowKey !== "string" || !KEY_PATTERN.test(link.workflowKey) || !isRunId(link.sourceRunId) || !isRunId(link.revivedRunId)) return undefined;
|
|
52
|
+
if (!Number.isInteger(link.depth) || (link.depth as number) < 1 || (link.depth as number) > MAX_REVIVAL_DEPTH) return undefined;
|
|
53
|
+
return { version: 1, workflowRunId: link.workflowRunId, workflowKey: link.workflowKey, sourceRunId: link.sourceRunId, revivedRunId: link.revivedRunId, depth: link.depth as number };
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Links a detached revival to the workflow key of its source run when the source failed and is
|
|
58
|
+
* an async workflow child or an earlier revival of one. Throws when the source status cannot be
|
|
59
|
+
* read or the key's revival chain is full; the caller reports that on the revive receipt.
|
|
60
|
+
*/
|
|
61
|
+
export function recordWorkflowRevival(asyncDirRoot: string, sourceRunId: string, revivedRunId: string): void {
|
|
62
|
+
const sourceDir = path.join(asyncDirRoot, sourceRunId);
|
|
63
|
+
const status = readStatus(sourceDir);
|
|
64
|
+
if (status?.runId !== sourceRunId || status.state !== "failed") return;
|
|
65
|
+
const origin = isRunId(status.parentWorkflowRunId) && typeof status.workflowKey === "string" && KEY_PATTERN.test(status.workflowKey)
|
|
66
|
+
? { workflowRunId: status.parentWorkflowRunId, workflowKey: status.workflowKey, depth: 0 }
|
|
67
|
+
: readLink(path.join(sourceDir, REVIVAL_ORIGIN_FILE));
|
|
68
|
+
if (!origin || ("revivedRunId" in origin && origin.revivedRunId !== sourceRunId)) return;
|
|
69
|
+
if (origin.depth >= MAX_REVIVAL_DEPTH) throw new Error(`workflow key '${origin.workflowKey}' of ${origin.workflowRunId} already has ${MAX_REVIVAL_DEPTH} chained revivals.`);
|
|
70
|
+
const link: WorkflowRevivalLink = { version: 1, workflowRunId: origin.workflowRunId, workflowKey: origin.workflowKey, sourceRunId, revivedRunId, depth: origin.depth + 1 };
|
|
71
|
+
const originFile = path.join(asyncDirRoot, revivedRunId, REVIVAL_ORIGIN_FILE);
|
|
72
|
+
writePrivateAtomicJson(originFile, link);
|
|
73
|
+
try {
|
|
74
|
+
writePrivateAtomicJson(path.join(sourceDir, REVIVAL_LINK_FILE), link);
|
|
75
|
+
} catch (error) {
|
|
76
|
+
// Keep the origin exactly when the published link names this revival: an unlinked origin
|
|
77
|
+
// would only pin the run against retention, and a linked one protects the key's chain.
|
|
78
|
+
if (readLink(path.join(sourceDir, REVIVAL_LINK_FILE))?.revivedRunId !== revivedRunId) fs.rmSync(originFile, { force: true });
|
|
79
|
+
throw error;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Follows revival links from one run of a workflow key by exact reads. Returns undefined when
|
|
85
|
+
* the run was never revived; malformed or mismatched links end the chain.
|
|
86
|
+
*/
|
|
87
|
+
export function projectWorkflowKeyRevival(asyncDirRoot: string, workflowRunId: string, workflowKey: string, runId: string): WorkflowKeyRevival | undefined {
|
|
88
|
+
if (!isRunId(runId)) return undefined;
|
|
89
|
+
const revivedRunIds: string[] = [];
|
|
90
|
+
let current = runId;
|
|
91
|
+
while (revivedRunIds.length < MAX_REVIVAL_DEPTH) {
|
|
92
|
+
const link = readLink(path.join(asyncDirRoot, current, REVIVAL_LINK_FILE));
|
|
93
|
+
if (!link || link.sourceRunId !== current || link.workflowRunId !== workflowRunId || link.workflowKey !== workflowKey) break;
|
|
94
|
+
revivedRunIds.push(link.revivedRunId);
|
|
95
|
+
current = link.revivedRunId;
|
|
96
|
+
}
|
|
97
|
+
if (revivedRunIds.length === 0) return undefined;
|
|
98
|
+
let status: AsyncStatus | null = null;
|
|
99
|
+
try {
|
|
100
|
+
status = readStatus(path.join(asyncDirRoot, current));
|
|
101
|
+
} catch {
|
|
102
|
+
// Readers show "status unavailable" instead of failing the workflow's status or notice.
|
|
103
|
+
}
|
|
104
|
+
return { revivedRunIds, latestRunId: current, ...(status?.runId === current ? { state: status.state } : {}) };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** `Revived → <run> [→ <run>]: <state>`, shown next to the key's original failure. */
|
|
108
|
+
export function formatWorkflowKeyRevival(revival: WorkflowKeyRevival): string {
|
|
109
|
+
return `Revived → ${revival.revivedRunIds.join(" → ")}: ${revival.state === "complete" ? "completed" : revival.state ?? "status unavailable"}`;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Adds each failed child's revivals to its lineage, so the receipt's latest run for that key is
|
|
114
|
+
* the newest revival. The child's own result and evidence stay as they were.
|
|
115
|
+
*/
|
|
116
|
+
export function withWorkflowRevivals<T extends WorkflowScriptChildResult>(asyncDirRoot: string, workflowRunId: string, children: T[]): Array<T & { revival?: WorkflowKeyRevival }> {
|
|
117
|
+
return children.map((child) => {
|
|
118
|
+
if (child.ok || child.state === "running" || !child.runId) return child;
|
|
119
|
+
const lineage = child.continuation?.runIds ?? [child.runId];
|
|
120
|
+
const revival = projectWorkflowKeyRevival(asyncDirRoot, workflowRunId, child.key, lineage.at(-1) ?? child.runId);
|
|
121
|
+
return revival ? { ...child, continuation: { runIds: [...lineage, ...revival.revivedRunIds] }, revival } : child;
|
|
122
|
+
});
|
|
123
|
+
}
|