pi-subagents 0.81.0 → 0.82.0

package/src/workflows/workflow-resume.js

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { normalizePublicSubagentExecution } from "../extension/public-execution.js";
+import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
+import { ownsRun } from "../runs/shared/run-ownership.js";
+import { readStatus } from "../shared/utils.js";
+import { readWorkflowLaunchRecord } from "./workflow-launch-record.js";
+import { claimWorkflowResume, refusalSentence, relaunchByHandText, resumeByHandText } from "./workflow-resume-claim.js";
+import { workflowScriptDigest } from "./workflow-reuse.js";
+import { isRunId } from "./workflow-revival.js";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_OWNER_EXITED } from "./workflow-stop-cause.js";
+/** A run may be resumed again after at most this many resumes that followed Pi exits (auto-resume only). */
+const MAX_WORKFLOW_RESUME_ATTEMPTS = 3;
+export function workflowResumeRefusal(code, reason, runId) {
+    const byHand = code === "launch-missing" || code === "launch-invalid" || code === "structured" || code === "digest" || code === "authority"
+        ? relaunchByHandText(runId)
+        : code === "capacity" || code === "attempts" || code === "launch-failed" ? resumeByHandText(runId) : "";
+    return { code, reason, byHand };
+}
+/** The tool error for a resume by id; the resume form is not repeated to a caller that just tried it. */
+export function manualWorkflowResumeRefusalText(runId, refusal) {
+    return `Cannot resume workflow '${runId}': ${refusalSentence(refusal.reason, refusal.byHand === relaunchByHandText(runId) ? refusal.byHand : "")}`;
+}
+/**
+ * The run id a resume action relaunches: no message, task, chain or index, and an id naming a
+ * top-level workflow run. Anything else is a child resume.
+ */
+export function workflowResumeTargetId(asyncDirRoot, params) {
+    if (params.message !== undefined || params.task !== undefined || params.index !== undefined)
+        return undefined;
+    if (Array.isArray(params.chain) && params.chain.length > 0)
+        return undefined;
+    const id = params.id ?? params.runId;
+    if (!isRunId(id))
+        return undefined;
+    let status;
+    try {
+        status = readStatus(path.join(asyncDirRoot, id));
+    }
+    catch {
+        return undefined;
+    }
+    return status?.mode === "workflow" && status.parentWorkflowRunId === undefined ? id : undefined;
+}
+/**
+ * Checks a stopped workflow run can be resumed and claims it for a new run id. Synchronous and
+ * cheap: the launch itself happens in the executor.
+ * `newRunId` presets the new run's id: a reload claims a run again under the id of the launch it cancelled.
+ */
+export function prepareWorkflowResume(input) {
+    const { asyncDirRoot, sourceRunId, trigger } = input;
+    const refuse = (code, reason) => ({ ok: false, ...workflowResumeRefusal(code, reason, sourceRunId) });
+    const sourceAsyncDir = path.join(asyncDirRoot, sourceRunId);
+    // Only the session that owns the run (itself or one it replaced) may resume it, and nothing is
+    // written into another session's run, so this comes before the reconcile.
+    const stored = readStatus(sourceAsyncDir);
+    if (stored && !ownsRun(input.currentSessionId, stored.sessionId))
+        return refuse("not-owned", "it was started in another session; reopen that session to resume it");
+    // Session start has already reconciled this session's runs; a resume by id may come later.
+    if (trigger === "manual")
+        reconcileAsyncRun(sourceAsyncDir);
+    const status = readStatus(sourceAsyncDir);
+    if (!status || status.mode !== "workflow" || !isReusableWorkflowStopCause(status.workflow?.stopCause))
+        return refuse("not-interrupted", "not interrupted; pass message to revive one of its children");
+    // The attempt the resumed run records: only resumes that follow a Pi exit count.
+    const attempt = (status.workflow?.resumeOrigin?.attempt ?? 0) + (status.workflow?.stopCause === WORKFLOW_STOP_CAUSE_OWNER_EXITED ? 1 : 0);
+    if (trigger === "auto" && attempt > MAX_WORKFLOW_RESUME_ATTEMPTS)
+        return refuse("attempts", `${MAX_WORKFLOW_RESUME_ATTEMPTS} resumes already followed Pi exits`);
+    const read = readWorkflowLaunchRecord(sourceAsyncDir);
+    if (!read.ok)
+        return read.missing ? refuse("launch-missing", "launch.json is missing (the run started before launches were saved)") : refuse("launch-invalid", `launch.json is invalid: ${read.error}`);
+    const record = read.record;
+    if (record.source === "structured")
+        return refuse("structured", "launched from tasks/chain");
+    if (record.source === "script" && (typeof record.params.workflowScript !== "string" || workflowScriptDigest(record.params.workflowScript) !== record.scriptDigest)) {
+        return refuse("launch-invalid", "launch.json is invalid: its script does not match its scriptDigest");
+    }
+    const normalized = normalizePublicSubagentExecution(record.params);
+    if (!normalized.ok)
+        return refuse("launch-invalid", `launch.json is invalid: ${normalized.error}`);
+    const newRunId = input.newRunId ?? randomUUID();
+    const claim = claimWorkflowResume(sourceAsyncDir, { newRunId, trigger, now: input.now });
+    if (claim.kind === "resumed")
+        return refuse("claim-resumed", `resumed as ${claim.newRunId}; wait on it or stop it`);
+    if (claim.kind === "busy")
+        return refuse("claim-busy", `being resumed by pid ${claim.pid}`);
+    if (claim.kind === "unreadable")
+        return refuse("claim-busy", "its resume claim cannot be read; wait or remove it");
+    return {
+        ok: true,
+        prepared: {
+            sourceRunId,
+            sourceAsyncDir,
+            newRunId,
+            trigger,
+            params: {
+                ...record.params,
+                async: true,
+                reuseFrom: sourceRunId,
+                ...(status.admissionCapabilityCeiling ? { capabilityCeiling: status.admissionCapabilityCeiling } : {}),
+            },
+            expectedScriptDigest: record.scriptDigest,
+            resumeOrigin: { sourceRunId, attempt },
+        },
+    };
+}

package/src/workflows/workflow-reuse.d.ts

@@ -1,11 +1,11 @@
+import { type WorkflowResumeClaimOutcome } from "./workflow-resume-claim.ts";
 import { type WorkflowScriptChildResult } from "./scripted-workflow.ts";
-/** Stop cause recorded when the extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
-declare const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
-type WorkflowStopCause = typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED;
-export declare function workflowRuntimeReplacedRelaunchNotice(runId: string): string;
+import { WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED } from "./workflow-stop-cause.ts";
+/** What a runtime replacement left; the notice's resume line says how the run continues. */
+export declare const WORKFLOW_RUNTIME_REPLACED_STOP_NOTICE = "Async children that were still running keep running, and finished children are kept.";
 /** Abort reason for workflow controllers torn down by runtime replacement; carries the cause as data, not text. */
 export declare function runtimeReplacedAbortReason(): Error;
-export declare function workflowStopCause(reason: unknown): WorkflowStopCause | undefined;
+export declare function workflowStopCause(reason: unknown): typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED | undefined;
 export declare function workflowScriptDigest(script: string): string;
 /** Hash of the canonical launch params the script host uses to detect duplicate keys. */
 export declare function workflowChildFingerprint(params: Record<string, unknown>): string;
@@ -40,16 +40,22 @@ type WorkflowReuseMatch = {
     kind: "started";
     runId: string;
 };
+/** Why a relaunch of `runId` is refused when another relaunch already continues it. */
+export declare function claimedWorkflowRunRefusal(runId: string, claim: Exclude<WorkflowResumeClaimOutcome, {
+    kind: "owner";
+}>, named: boolean): string;
 /**
  * The newest terminal workflow of this session with the same script and args,
- * when that run stopped because its runtime was replaced.
+ * when that run stopped because its runtime was replaced or its Pi process exited.
+ * Throws when another relaunch already continues that run.
  */
 export declare function findWorkflowReuseSource(asyncDirRoot: string, sessionId: string, scriptDigest: string, argsDigest: string | undefined): WorkflowReuseSource | undefined;
 /**
- * The runtime-replaced workflow run named by `options.reuseFrom`, from any session. Only the script
- * must match: each child is still reused only when its key and launch params match.
+ * The interrupted workflow run named by `options.reuseFrom`, from any session. Only the script
+ * must match: each child is still reused only when its key and launch params match. The run is
+ * reconciled first, so a run whose Pi process died is marked `owner-exited` before it is read.
  */
-export declare function readNamedWorkflowReuseSource(asyncDirRoot: string, runId: string, scriptDigest: string, cwd: string): WorkflowReuseSource;
+export declare function readNamedWorkflowReuseSource(asyncDirRoot: string, runId: string, scriptDigest: string, cwd: string, claimOwnerRunId?: string): WorkflowReuseSource;
 /** A settled match is reusable only when that child succeeded; failed or stopped children run again. */
 export declare function matchWorkflowReuse(source: WorkflowReuseSource, key: string, fingerprint: string): WorkflowReuseMatch | undefined;
 export {};

package/src/workflows/workflow-reuse.js

@@ -2,14 +2,15 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readRecentTerminalRunIndex } from "../runs/background/terminal-run-index.js";
+import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
 import { readStatus } from "../shared/utils.js";
+import { workflowResumeClaimState } from "./workflow-resume-claim.js";
+import { isRunId } from "./workflow-revival.js";
 import { workflowRunParamsFingerprint } from "./scripted-workflow.js";
-/** Stop cause recorded when the extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
-const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED } from "./workflow-stop-cause.js";
 const WORKFLOW_CHILD_JOURNAL_FILE = "workflow-children.jsonl";
-export function workflowRuntimeReplacedRelaunchNotice(runId) {
-    return `Async children that were still running keep running. Relaunching the same workflow script with the same args from this session reuses finished children and re-attaches to running ones; from another session, add options: { reuseFrom: "${runId}" }.`;
-}
+/** What a runtime replacement left; the notice's resume line says how the run continues. */
+export const WORKFLOW_RUNTIME_REPLACED_STOP_NOTICE = "Async children that were still running keep running, and finished children are kept.";
 /** Abort reason for workflow controllers torn down by runtime replacement; carries the cause as data, not text. */
 export function runtimeReplacedAbortReason() {
     return Object.assign(new Error("Workflow stopped because the extension session was replaced or reloaded."), { workflowStopCause: WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED });
@@ -67,9 +68,63 @@ function readWorkflowChildJournal(runId, workflowAsyncDir) {
     }
     return source;
 }
+const WORKFLOW_REUSE_CHAIN_MAX_LINKS = 16;
+/**
+ * The head run's journal plus the journals of the runs it was relaunched from (`workflow.reusedFrom`).
+ * A child's start record is written only once it gets a concurrency slot, so a key the head never
+ * reached is still in an earlier run's journal. For each key the newest run that recorded it wins. A
+ * status file is parsed, not validated, so a corrupt `reusedFrom` may be any JSON value.
+ */
+function readWorkflowReuseChain(asyncDirRoot, headRunId, headStatus) {
+    const source = readWorkflowChildJournal(headRunId, path.join(asyncDirRoot, headRunId));
+    const visited = new Set([headRunId]);
+    let next = headStatus.workflow?.reusedFrom;
+    for (let links = 0; isRunId(next) && links < WORKFLOW_REUSE_CHAIN_MAX_LINKS && !visited.has(next); links++) {
+        visited.add(next);
+        const asyncDir = path.join(asyncDirRoot, next);
+        let status;
+        try {
+            status = readStatus(asyncDir);
+        }
+        catch {
+            break;
+        }
+        if (status?.mode !== "workflow" || status.workflow?.scriptDigest !== headStatus.workflow?.scriptDigest)
+            break;
+        const link = readWorkflowChildJournal(next, asyncDir);
+        for (const key of new Set([...link.started.keys(), ...link.settled.keys()])) {
+            if (source.started.has(key) || source.settled.has(key))
+                continue;
+            const started = link.started.get(key);
+            const settled = link.settled.get(key);
+            if (started)
+                source.started.set(key, started);
+            if (settled)
+                source.settled.set(key, settled);
+        }
+        next = status.workflow?.reusedFrom;
+    }
+    return source;
+}
+/** Why a relaunch of `runId` is refused when another relaunch already continues it. */
+export function claimedWorkflowRunRefusal(runId, claim, named) {
+    const run = `${named ? "options.reuseFrom: workflow" : "Workflow"} run '${runId}'`;
+    if (claim.kind === "resumed")
+        return `${run} was resumed as ${claim.newRunId}; wait on it or stop it.`;
+    if (claim.kind === "busy")
+        return `${run} is being resumed by pid ${claim.pid}; wait for it.`;
+    return `${run} has a resume claim that cannot be read; wait or remove it.`;
+}
+function assertWorkflowRunNotClaimed(asyncDir, runId, named, claimOwnerRunId) {
+    const claim = workflowResumeClaimState(asyncDir);
+    if (claim.kind === "none" || (claim.kind !== "unreadable" && claim.newRunId === claimOwnerRunId))
+        return;
+    throw new Error(claimedWorkflowRunRefusal(runId, claim, named));
+}
 /**
  * The newest terminal workflow of this session with the same script and args,
- * when that run stopped because its runtime was replaced.
+ * when that run stopped because its runtime was replaced or its Pi process exited.
+ * Throws when another relaunch already continues that run.
  */
 export function findWorkflowReuseSource(asyncDirRoot, sessionId, scriptDigest, argsDigest) {
     let runIds;
@@ -90,28 +145,36 @@ export function findWorkflowReuseSource(asyncDirRoot, sessionId, scriptDigest, a
         }
         if (status?.mode !== "workflow" || status.workflow?.scriptDigest !== scriptDigest || status.workflow.argsDigest !== argsDigest)
             continue;
-        return status.workflow.stopCause === WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED ? readWorkflowChildJournal(runId, asyncDir) : undefined;
+        if (!isReusableWorkflowStopCause(status.workflow.stopCause))
+            return undefined;
+        assertWorkflowRunNotClaimed(asyncDir, runId, false);
+        return readWorkflowReuseChain(asyncDirRoot, runId, status);
     }
     return undefined;
 }
 /**
- * The runtime-replaced workflow run named by `options.reuseFrom`, from any session. Only the script
- * must match: each child is still reused only when its key and launch params match.
+ * The interrupted workflow run named by `options.reuseFrom`, from any session. Only the script
+ * must match: each child is still reused only when its key and launch params match. The run is
+ * reconciled first, so a run whose Pi process died is marked `owner-exited` before it is read.
  */
-export function readNamedWorkflowReuseSource(asyncDirRoot, runId, scriptDigest, cwd) {
+export function readNamedWorkflowReuseSource(asyncDirRoot, runId, scriptDigest, cwd, claimOwnerRunId) {
     // A user-supplied id: it must name one run directory, never a path.
-    const status = runId === path.basename(runId) && runId !== "." && runId !== ".." ? readStatus(path.join(asyncDirRoot, runId)) : null;
+    const runName = isRunId(runId);
+    if (runName)
+        reconcileAsyncRun(path.join(asyncDirRoot, runId));
+    const status = runName ? readStatus(path.join(asyncDirRoot, runId)) : null;
     if (!status)
         throw new Error(`options.reuseFrom: workflow run '${runId}' was not found.`);
     if (status.mode !== "workflow")
         throw new Error(`options.reuseFrom: run '${runId}' is not a workflow run.`);
-    if (status.workflow?.stopCause !== WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED)
-        throw new Error(`options.reuseFrom: workflow run '${runId}' did not stop because its session was replaced, so its children cannot be reused.`);
+    if (!isReusableWorkflowStopCause(status.workflow?.stopCause))
+        throw new Error(`options.reuseFrom: workflow run '${runId}' did not stop because its session was replaced or its Pi process exited, so its children cannot be reused.`);
     if (status.workflow.scriptDigest !== scriptDigest)
         throw new Error(`options.reuseFrom: workflow run '${runId}' ran a different workflow script.`);
     if (status.cwd !== cwd)
         throw new Error(`options.reuseFrom: workflow run '${runId}' ran in '${status.cwd}', not '${cwd}'.`);
-    return readWorkflowChildJournal(runId, path.join(asyncDirRoot, runId));
+    assertWorkflowRunNotClaimed(path.join(asyncDirRoot, runId), runId, true, claimOwnerRunId);
+    return readWorkflowReuseChain(asyncDirRoot, runId, status);
 }
 /** A settled match is reusable only when that child succeeded; failed or stopped children run again. */
 export function matchWorkflowReuse(source, key, fingerprint) {

package/src/workflows/workflow-revival.d.ts

@@ -9,6 +9,8 @@ export interface WorkflowKeyRevival {
     /** State of the latest revived run; undefined when its status is unreadable. */
     state?: AsyncStatus["state"];
 }
+/** A run directory name, never a path. */
+export declare function isRunId(value: unknown): value is string;
 /**
  * Links a detached revival to the workflow key of its source run when the source failed and is
  * an async workflow child or an earlier revival of one. Throws when the source status cannot be

package/src/workflows/workflow-revival.js

@@ -13,7 +13,8 @@ export const REVIVAL_ORIGIN_FILE = "workflow-revival-origin.json";
 /** Recording refuses a deeper link, so readers bounded by this always reach the chain's end. */
 const MAX_REVIVAL_DEPTH = 16;
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-function isRunId(value) {
+/** A run directory name, never a path. */
+export function isRunId(value) {
     return typeof value === "string" && value.length > 0 && value.length <= 255 && path.basename(value) === value && value !== "." && value !== "..";
 }
 function readLink(file) {

package/src/workflows/workflow-stop-cause.d.ts

@@ -0,0 +1,6 @@
+/** The extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
+export declare const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
+/** Stale-run reconciliation found the Pi process that ran the workflow dead (crash, kill, reboot). */
+export declare const WORKFLOW_STOP_CAUSE_OWNER_EXITED = "owner-exited";
+export type WorkflowStopCause = typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED | typeof WORKFLOW_STOP_CAUSE_OWNER_EXITED;
+export declare function isReusableWorkflowStopCause(cause: unknown): cause is WorkflowStopCause;

package/src/workflows/workflow-stop-cause.js

@@ -0,0 +1,8 @@
+// Leaf module with no imports, so any module can use it without an import cycle.
+/** The extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
+export const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
+/** Stale-run reconciliation found the Pi process that ran the workflow dead (crash, kill, reboot). */
+export const WORKFLOW_STOP_CAUSE_OWNER_EXITED = "owner-exited";
+export function isReusableWorkflowStopCause(cause) {
+    return cause === WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED || cause === WORKFLOW_STOP_CAUSE_OWNER_EXITED;
+}