@sema-agent/core 7.9.2 → 7.10.0

package/dist/orchestration/workflow.js

@@ -11,14 +11,14 @@ import { combinePolicies, createAllowDenyPolicy } from "../core/tool-policy.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
 import { callKeyOrdinal, oversizeJournalResult, journalOversizeTombstone, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES } from "../core/workflow-journal-store.js";
 import { isWorkflowRunActive, closeWorkflowChannel, markWorkflowActive, publishWorkflowEvent } from "./workflow-observe.js";
-import { isDurablePause, mapNestedSuspend } from "../agents/suspend-guard.js";
+import { isDurablePause } from "../agents/suspend-guard.js";
 import { RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
 import { boundInputHashOf } from "../core/canonical-json.js";
 import { boundedRedactedSummary } from "../core/untrusted-egress.js";
 import { delimitUntrusted } from "../core/untrusted-text.js";
 import { OUTPUT_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
-import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
+import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
 export * from "./workflow-types.js";
 const MAX_TRANSCRIPT_CHARS = 4000;
@@ -206,10 +206,9 @@ export class WorkflowJournalIncompatibleError extends Error {
     fromRunId;
     ordinal;
     code = "workflow.journal_incompatible";
-    constructor(fromRunId, ordinal) {
-        super(`startWorkflow: resume from "${fromRunId}" was REFUSED — journal entry #${ordinal} carries no terminal cause ` +
-            "(a journal written before TaskResult.terminal, or a malformed entry). Completed work must not run again; " +
-            "start a fresh run instead of resuming this journal.");
+    constructor(fromRunId, ordinal, reason) {
+        super(`startWorkflow: resume from "${fromRunId}" was REFUSED — ${reason ?? `journal entry #${ordinal} carries no terminal cause (a journal written before TaskResult.terminal, or a malformed entry)`}. ` +
+            "Completed work must not run again; start a fresh run instead of resuming this journal.");
         this.fromRunId = fromRunId;
         this.ordinal = ordinal;
         this.name = "WorkflowJournalIncompatibleError";
@@ -448,6 +447,12 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     if (opts.resumeFromRunId !== undefined && opts.journalStore === undefined) {
         throw new Error("runWorkflow: resumeFromRunId requires a journalStore to load the prior run's journal");
     }
+    if (opts.defaultDurableApproval !== undefined && opts.store === undefined) {
+        throw new Error("runWorkflow: defaultDurableApproval requires a WorkflowRunStore — a workflow child's park is recorded on its wa* row, and without a store there is no durable row for a host to route the parked approval by");
+    }
+    if (opts.parkedResume !== undefined && opts.resumeFromRunId === undefined) {
+        throw new Error("runWorkflow: parkedResume drives a PARKED ordinal of a prior run and requires resumeFromRunId");
+    }
     const now = opts.now ?? (() => Date.now());
     const scope = opts.scope ?? "default";
     const runId = opts.runId ?? randomUUID();
@@ -769,6 +774,60 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     let resumeClaim;
     const replayByOrdinal = [];
     let diverged = false;
+    let parkedLeg;
+    const parkedError = () => {
+        const p = parkedLeg;
+        return new WorkflowAgentParkedError(p.label, p.paused.terminal.gate.kind, p.paused.terminal.checkpointId);
+    };
+    const parkedResumeFor = (token) => opts.parkedResume?.find((d) => d.token === token);
+    const parkedCallChangedError = (ordinal) => Object.assign(new Error(`workflow resume: ordinal ${ordinal} is PARKED on an approval checkpoint, but the call at that ordinal changed (its call key differs from the journaled one) — ` +
+        "the script or its args were edited at a parked call, and a fresh spawn there would run beside the pinned child. Restore the call and resume again, or decide the checkpoint " +
+        "through the deployment's approval channel and start a fresh run."), { code: "workflow.parked_call_changed" });
+    let inFlightLegs = 0;
+    let legsIdleResolve;
+    const legStart = () => {
+        inFlightLegs += 1;
+    };
+    const legEnd = () => {
+        inFlightLegs -= 1;
+        if (inFlightLegs <= 0) {
+            inFlightLegs = 0;
+            const r = legsIdleResolve;
+            legsIdleResolve = undefined;
+            r?.();
+        }
+    };
+    const awaitLegsIdle = async (signal) => {
+        while (inFlightLegs > 0 && signal?.aborted !== true) {
+            await new Promise((resolve) => {
+                legsIdleResolve = resolve;
+                signal?.addEventListener("abort", () => resolve(), { once: true });
+            });
+        }
+    };
+    const writtenOrdinals = new Set();
+    const carryUnresolvedParks = async () => {
+        if (opts.resumeFromRunId === undefined || !journalStore)
+            return;
+        for (const e of replayByOrdinal) {
+            if (e?.parked === undefined)
+                continue;
+            const ord = callKeyOrdinal(e.callKey);
+            if (writtenOrdinals.has(ord))
+                continue;
+            if (workflowSignal.aborted) {
+                emitLogLine(`resume-journal: the prior run's PARKED leg at ordinal ${ord} was NOT carried into this run's journal (the run was cancelled or timed out first) — resume from the prior run, not from this one.`);
+                continue;
+            }
+            const outcome = await finalizeWithin(timers, journalAppendParked(e.callKey, e.parked).then(() => "ok", (err) => ({ err })), "timeout");
+            if (outcome !== "ok") {
+                const why = outcome === "timeout" ? `the append did not settle within ${WORKFLOW_RESUME_CLAIM_FINALIZE_TIMEOUT_MS}ms` : outcome.err instanceof Error ? outcome.err.message : String(outcome.err);
+                emitLogLine(`resume-journal: the prior run's PARKED leg at ordinal ${ord} could not be carried into this run's journal (${why}) — resume from the prior run, not from this one.`);
+            }
+        }
+    };
+    const driveNeverStarted = (r) => r.terminal.kind === "failed" && (r.terminal.code === "resume.reopened_unstarted" || r.terminal.code === "resume.reopen_failed_unstarted");
+    const isPausedResult = (r) => isDurablePause(r.terminal);
     let isolationAdvised = false;
     const adviseIsolationIfConcurrent = (opts) => {
         if (isolationAdvised || opts.isolation || sem.active <= 1)
@@ -783,6 +842,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     };
     let journalTail = Promise.resolve();
     const JOURNAL_DRAIN_MAX_MS = 5_000;
+    const durableApprovalInherit = (s) => s.durableApproval === undefined && opts.defaultDurableApproval !== undefined ? { durableApproval: { ...opts.defaultDurableApproval } } : {};
     const journalDurableResult = (result) => {
         const t = result.terminal;
         if (t === undefined || t.kind !== "failed" || typeof t.message !== "string" || t.message === "")
@@ -821,8 +881,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if (dbg)
                     console.error(`[sema:wf-journal] runId=${runId} callKey=${callKey} TOMBSTONE-ERROR ${err instanceof Error ? err.message : String(err)}`);
             }
+            writtenOrdinals.add(callKeyOrdinal(callKey));
             return;
         }
+        writtenOrdinals.add(callKeyOrdinal(callKey));
         const p = journalStore.append(runId, scope, { callKey, result: stored });
         journalTail = journalTail.then(() => p).catch(() => undefined);
         try {
@@ -836,6 +898,56 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             throw err;
         }
     };
+    const journalAppendParked = async (callKey, paused) => {
+        if (!journalStore)
+            return;
+        writtenOrdinals.add(callKeyOrdinal(callKey));
+        let lastErr;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const p = journalStore.append(runId, scope, { callKey, parked: paused });
+            journalTail = journalTail.then(() => p).catch(() => undefined);
+            try {
+                await p;
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt < 2)
+                    await new Promise((r) => timers.setTimeout(r, 25 * (attempt + 1)));
+            }
+        }
+        throw lastErr;
+    };
+    const parkAgentLeg = async (rec, paused, activityTail, chargeLive) => {
+        const s = paused.stats;
+        accumulateStats(paused, chargeLive);
+        rec.status = "parked";
+        rec.parkedCheckpointToken = paused.terminal.token;
+        rec.taskStatus = terminalProjection(paused.terminal).status;
+        if (paused.sessionId)
+            rec.sessionId = paused.sessionId;
+        setLegRunId(rec, paused);
+        rec.endedAt = now();
+        rec.stats = { tokens: s.tokens ?? 0, turns: s.turns ?? 0, costMicroUsd: s.costMicroUsd };
+        if (s.toolCalls !== undefined)
+            rec.toolCalls = s.toolCalls;
+        if (activityTail.length > 0)
+            rec.activity = activityTail.slice();
+        foldLegApprovalReport(rec, paused);
+        emit({ type: "agent_end", runId, label: rec.label, phase: rec.phase, ...(rec.groupId !== undefined ? { groupId: rec.groupId } : {}), status: "parked", ...(paused.model !== undefined ? { modelResolved: paused.model } : {}), ts: rec.endedAt });
+        void persist("update");
+        bceLive.delete(waIdOf(rec.callKey));
+        if (parkedLeg === undefined)
+            parkedLeg = { label: rec.label, callKey: rec.callKey, paused };
+        try {
+            await journalAppendParked(rec.callKey, paused);
+        }
+        catch (err) {
+            emitRunLog(`resume-journal: the PARKED leg at ordinal ${callKeyOrdinal(rec.callKey)} ("${rec.label.slice(0, 80)}") could not be recorded (${err instanceof Error ? err.message : String(err)}) — ` +
+                "a resume of this run will NOT find the park at its ordinal; decide the checkpoint through the deployment's approval channel and start a fresh run instead of resuming this one.");
+        }
+        throw parkedError();
+    };
     const createActivityCapture = (callKey, label, groupId, rec) => {
         const tail = [];
         let beatCount = 0;
@@ -1191,9 +1303,34 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         async agent(spec, agentOpts = {}) {
             const effectiveSignal = assertAgentSpawnAllowed("ctx.agent", spec, agentOpts);
             const { label, phase, phaseInstance, groupId, inheritedModelSnap, inheritedModelError, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
+            let drive;
+            const cached = opts.resumeFromRunId !== undefined ? replayByOrdinal[run.agents.length] : undefined;
+            if (cached?.parked !== undefined) {
+                if (cached.callKey !== callKey)
+                    throw parkedCallChangedError(run.agents.length);
+                {
+                    const decision = parkedResumeFor(cached.parked.terminal.token);
+                    if (decision === undefined) {
+                        if (finalized)
+                            return cached.parked;
+                        const at = now();
+                        const reparkRec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(cached.parked.model !== undefined ? { model: cached.parked.model } : {}), replayed: true, status: "running", queuedAt: at, startedAt: at };
+                        if (run.resume)
+                            run.resume.replayed += 1;
+                        run.agents.push(reparkRec);
+                        if (phaseInstance)
+                            agentPhaseOf.set(reparkRec, phaseInstance);
+                        emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(cached.parked.model !== undefined ? { model: cached.parked.model } : {}), replayed: true, ts: at });
+                        bceSpawn(callKey, label, agentOpts.agentType, true, cached.parked.sessionId || undefined, cached.parked.model);
+                        return await parkAgentLeg(reparkRec, cached.parked, [], false);
+                    }
+                    drive = { token: decision.token, outcome: decision.outcome, ...(decision.inheritedGate !== undefined ? { inheritedGate: decision.inheritedGate } : {}), sessionId: cached.parked.sessionId || undefined, paused: cached.parked };
+                }
+            }
+            if (parkedLeg !== undefined && drive === undefined)
+                throw parkedError();
             if (opts.resumeFromRunId !== undefined && !diverged) {
-                const cached = replayByOrdinal[run.agents.length];
-                if (cached && cached.callKey === callKey && TERMINAL_CAUSE_IS_REPLAYABLE[cached.result.terminal.kind]) {
+                if (drive === undefined && cached && cached.callKey === callKey && cached.result !== undefined && TERMINAL_CAUSE_IS_REPLAYABLE[cached.result.terminal.kind]) {
                     if (finalized)
                         return cached.result;
                     const r = cached.result;
@@ -1237,18 +1374,20 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     }
                     return r;
                 }
-                noteDivergence(run.agents.length, cached === undefined
-                    ? run.resume?.journalEntries === 0
-                        ? "the journal loaded no entries"
-                        : run.agents.length >= replayByOrdinal.length
-                            ? "a new call past the journaled prefix — the prior run ended before this point (the intended extend-the-script resume shape)"
-                            : "no journal entry at this ordinal (never recorded, e.g. an oversize result under a pre-tombstone engine, or dropped)"
-                    : cached.callKey !== callKey
-                        ? "the call key changed — the script or its args differ here"
-                        : cached.result.terminal?.kind === "failed" && cached.result.terminal.code === JOURNAL_OVERSIZE_ERROR_CODE
-                            ? "the prior result exceeded the journal size cap and was never cached"
-                            : `the journaled result was ${cached.result.terminal?.kind ?? "(no terminal record)"}, not completed`);
-                diverged = true;
+                if (drive === undefined) {
+                    noteDivergence(run.agents.length, cached === undefined
+                        ? run.resume?.journalEntries === 0
+                            ? "the journal loaded no entries"
+                            : run.agents.length >= replayByOrdinal.length
+                                ? "a new call past the journaled prefix — the prior run ended before this point (the intended extend-the-script resume shape)"
+                                : "no journal entry at this ordinal (never recorded, e.g. an oversize result under a pre-tombstone engine, or dropped)"
+                        : cached.callKey !== callKey
+                            ? "the call key changed — the script or its args differ here"
+                            : cached.result?.terminal?.kind === "failed" && cached.result.terminal.code === JOURNAL_OVERSIZE_ERROR_CODE
+                                ? "the prior result exceeded the journal size cap and was never cached"
+                                : `the journaled result was ${cached.result?.terminal?.kind ?? "(no terminal record)"}, not completed`);
+                    diverged = true;
+                }
             }
             if (budgetTotal !== null && spent() >= budgetTotal) {
                 throw new WorkflowBudgetExceededError(spent(), budgetTotal);
@@ -1260,6 +1399,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 agentPhaseOf.set(rec, phaseInstance);
             emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(model !== undefined ? { model } : {}), queuedAt: rec.queuedAt, ts: rec.queuedAt });
             void persist("update");
+            legStart();
             const release = await sem.acquire();
             adviseIsolationIfConcurrent(agentOpts);
             let result;
@@ -1268,11 +1408,13 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     throw new Error("workflow aborted");
                 if (finalized)
                     throw new Error("workflow run already finalized — ctx.agent cannot spawn after the run ended");
+                if (parkedLeg !== undefined && drive === undefined)
+                    throw parkedError();
                 if (budgetTotal !== null && spent() >= budgetTotal) {
                     throw new WorkflowBudgetExceededError(spent(), budgetTotal);
                 }
                 rec.startedAt = now();
-                const bornChildSessionId = resolveChildSessionIdAtSpawn(spec);
+                const bornChildSessionId = drive !== undefined ? drive.sessionId : resolveChildSessionIdAtSpawn(spec);
                 bceSpawn(callKey, label, agentOpts.agentType, false, bornChildSessionId, model);
                 if (inheritedModelError !== undefined)
                     throw inheritedModelError;
@@ -1280,9 +1422,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
                 const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
                 const authInherit = framedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
+                const parkInherit = durableApprovalInherit(framedSpec);
                 const preReviewSpec = agentOpts.schema
-                    ? { ...framedSpec, ...authInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
-                    : { ...framedSpec, ...authInherit, signal: effectiveSignal };
+                    ? { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
+                    : { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agent", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForward = opts.onForwardEvent !== undefined
                     ? (e) => {
@@ -1319,7 +1462,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     const onCallerAbort = () => attemptCtl.abort(new Error("workflow aborted"));
                     effectiveSignal?.addEventListener("abort", onCallerAbort, { once: true });
                     armWatchdog();
-                    const attemptSessionId = attempts === 1 ? bornChildSessionId : resolveChildSessionIdAtSpawn(runSpec);
+                    const attemptSessionId = drive !== undefined ? drive.sessionId : attempts === 1 ? bornChildSessionId : resolveChildSessionIdAtSpawn(runSpec);
                     const attemptSpec = attemptSessionId !== undefined ? { ...runSpec, sessionId: attemptSessionId, signal: attemptCtl.signal } : { ...runSpec, signal: attemptCtl.signal };
                     if (attemptSessionId !== undefined && !finalized) {
                         rec.sessionId = attemptSessionId;
@@ -1373,10 +1516,15 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     activeUsageBeats.add(activeBeat);
                     try {
                         attemptResult = await workflowDepthStore.run({ depth: depth + 1 }, async () => {
-                            if (typeof runner.runTaskStream !== "function") {
+                            if (drive === undefined && typeof runner.runTaskStream !== "function") {
                                 return runner.runTask(attemptSpec, attemptInternals);
                             }
-                            const stream = runner.runTaskStream(attemptSpec, undefined, attemptInternals);
+                            const stream = drive === undefined
+                                ? runner.runTaskStream(attemptSpec, undefined, attemptInternals)
+                                : await (() => {
+                                    const { objective: _o, sessionId: _s, ...resumeConfig } = attemptSpec;
+                                    return runner.resumeStream(drive.token, drive.outcome, resumeConfig, { ...attemptInternals, ...(drive.inheritedGate !== undefined ? { inheritedGate: drive.inheritedGate } : {}) });
+                                })();
                             for await (const ev of stream) {
                                 if (ev.type === "text_delta" || ev.type === "reasoning_delta")
                                     onStreamProgress();
@@ -1409,7 +1557,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         }
                         throw new Error("workflow aborted");
                     }
-                    if (stallFired && attemptResult?.terminal.kind !== "completed") {
+                    if (drive === undefined && stallFired && attemptResult?.terminal.kind !== "completed") {
                         if (attemptResult !== undefined && !finalized)
                             accumulateStats(attemptResult, true);
                         if (attemptResult !== undefined && !finalized)
@@ -1438,7 +1586,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         (result.stats.outputTokens ?? Number.POSITIVE_INFINITY) < 50 &&
                         lastStopReason === undefined &&
                         durationMs > stallMs * 0.5;
-                    if (degraded && attempts === 1 && !throttleRetried) {
+                    if (degraded && attempts === 1 && !throttleRetried && drive === undefined) {
                         throttleRetried = true;
                         lastAttemptReason = "throttled";
                         emitRunLog(`[${label}] throttled response (${(result.result ?? "").trim().length} chars in ${Math.round(durationMs / 1000)}s) — sleeping ${Math.round(throttleBackoffMs / 1000)}s before retry`);
@@ -1474,6 +1622,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 }
             }
             catch (err) {
+                if (drive !== undefined && !finalized && !(err instanceof WorkflowAgentParkedError)) {
+                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${err instanceof Error ? err.message : String(err)}); the park stands.`);
+                    return await parkAgentLeg(rec, drive.paused, activityTail, false);
+                }
                 if (!finalized) {
                     rec.status = "failed";
                     rec.endedAt = now();
@@ -1520,7 +1672,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         },
                         stats: { turns: 0, tokens: 0, costMicroUsd: 0 },
                     }, label).catch(() => undefined);
-                    if (!(err instanceof WorkflowBudgetExceededError && rec.startedAt === undefined))
+                    if (!((err instanceof WorkflowBudgetExceededError || err instanceof WorkflowAgentParkedError) && rec.startedAt === undefined))
                         await journaled;
                     bceTerminal(callKey, "failed", rec.output ?? (err instanceof Error ? err.message : String(err)), rec.sessionId, rec.stats);
                 }
@@ -1528,11 +1680,16 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             finally {
                 release();
+                legEnd();
             }
             if (finalized)
                 return result;
-            if (isDurablePause(result.terminal)) {
-                result = mapNestedSuspend(result);
+            if (isPausedResult(result)) {
+                return await parkAgentLeg(rec, result, activityTail, true);
+            }
+            if (drive !== undefined && driveNeverStarted(result)) {
+                emitRunLog(`[park] the parked leg "${label}" was driven but the approved action never started (${result.terminal.kind === "failed" ? result.terminal.code : ""}); the park stands.`);
+                return await parkAgentLeg(rec, drive.paused, activityTail, false);
             }
             await settleAgentResult(rec, result, activityTail, agentOpts, "awaited");
             return result;
@@ -1543,8 +1700,30 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 throw new WorkflowBudgetExceededError(spent(), budgetTotal);
             }
             const { label, phase, phaseInstance, groupId, inheritedModelSnap, inheritedModelError, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
-            noteDivergence(run.agents.length, "ctx.agentStream results are never replayed");
-            diverged = true;
+            let drive;
+            const parkedHere = opts.resumeFromRunId !== undefined ? replayByOrdinal[run.agents.length] : undefined;
+            if (parkedHere?.parked !== undefined) {
+                if (parkedHere.callKey !== callKey)
+                    throw parkedCallChangedError(run.agents.length);
+                const decision = parkedResumeFor(parkedHere.parked.terminal.token);
+                if (decision === undefined) {
+                    const at = now();
+                    const reparkRec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(parkedHere.parked.model !== undefined ? { model: parkedHere.parked.model } : {}), replayed: true, status: "running", queuedAt: at, startedAt: at };
+                    if (run.resume)
+                        run.resume.replayed += 1;
+                    run.agents.push(reparkRec);
+                    if (phaseInstance)
+                        agentPhaseOf.set(reparkRec, phaseInstance);
+                    emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(parkedHere.parked.model !== undefined ? { model: parkedHere.parked.model } : {}), replayed: true, ts: at });
+                    bceSpawn(callKey, label, agentOpts.agentType, true, parkedHere.parked.sessionId || undefined, parkedHere.parked.model);
+                    return await parkAgentLeg(reparkRec, parkedHere.parked, [], false);
+                }
+                drive = { token: decision.token, outcome: decision.outcome, ...(decision.inheritedGate !== undefined ? { inheritedGate: decision.inheritedGate } : {}), sessionId: parkedHere.parked.sessionId || undefined, paused: parkedHere.parked };
+            }
+            if (drive === undefined) {
+                noteDivergence(run.agents.length, "ctx.agentStream results are never replayed");
+                diverged = true;
+            }
             const rec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(model !== undefined ? { model } : {}), status: "running", queuedAt: now() };
             const { tail: activityTail, onActivity } = createActivityCapture(callKey, label, groupId, rec);
             run.agents.push(rec);
@@ -1552,6 +1731,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 agentPhaseOf.set(rec, phaseInstance);
             emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(model !== undefined ? { model } : {}), queuedAt: rec.queuedAt, ts: rec.queuedAt });
             void persist("update");
+            legStart();
             const release = await sem.acquire();
             adviseIsolationIfConcurrent(agentOpts);
             let released = false;
@@ -1569,17 +1749,34 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     void persist("update");
                 }
             };
+            const releaseLeg = () => {
+                if (!released)
+                    legEnd();
+                releaseOnce();
+            };
             if (effectiveSignal?.aborted || finalized) {
                 recordFailed();
-                releaseOnce();
+                releaseLeg();
                 throw new Error(finalized ? "workflow run already finalized — ctx.agentStream cannot spawn after the run ended" : "workflow aborted");
             }
+            if (parkedLeg !== undefined && drive === undefined) {
+                const parked = parkedError();
+                rec.errorMessage = boundedRedactedSummary(parked.message, MAX_TRANSCRIPT_CHARS);
+                recordFailed();
+                releaseLeg();
+                throw parked;
+            }
             if (budgetTotal !== null && spent() >= budgetTotal) {
+                if (drive !== undefined) {
+                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the run's token ceiling was reached before its turn; the park stands.`);
+                    releaseLeg();
+                    return await parkAgentLeg(rec, drive.paused, [], false);
+                }
                 const refusal = new WorkflowBudgetExceededError(spent(), budgetTotal);
                 rec.errorCode = refusal.code;
                 rec.errorMessage = boundedRedactedSummary(refusal.message, MAX_TRANSCRIPT_CHARS);
                 recordFailed();
-                releaseOnce();
+                releaseLeg();
                 void journalAppend(callKey, {
                     taskId: callKey,
                     sessionId: "",
@@ -1590,7 +1787,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 throw refusal;
             }
             rec.startedAt = now();
-            const childSessionId = resolveChildSessionIdAtSpawn(spec);
+            const childSessionId = drive !== undefined ? drive.sessionId : resolveChildSessionIdAtSpawn(spec);
             bceSpawn(callKey, label, agentOpts.agentType, false, childSessionId, model);
             let stream;
             try {
@@ -1600,9 +1797,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
                 const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
                 const authInherit = framedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
+                const parkInherit = durableApprovalInherit(framedSpec);
                 const baseRunSpec = agentOpts.schema
-                    ? { ...framedSpec, ...authInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
-                    : { ...framedSpec, ...authInherit, signal: effectiveSignal };
+                    ? { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
+                    : { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
                 const preReviewSpec = childSessionId !== undefined ? { ...baseRunSpec, sessionId: childSessionId } : baseRunSpec;
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agentStream", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForwardS = opts.onForwardEvent !== undefined
@@ -1634,9 +1832,20 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         }
                         : {}),
                 };
-                stream = workflowDepthStore.run({ depth: depth + 1 }, () => runner.runTaskStream(runSpec, undefined, runInternals));
+                stream = drive === undefined
+                    ? workflowDepthStore.run({ depth: depth + 1 }, () => runner.runTaskStream(runSpec, undefined, runInternals))
+                    : await workflowDepthStore.run({ depth: depth + 1 }, () => {
+                        const d = drive;
+                        const { objective: _o, sessionId: _s, ...resumeConfig } = runSpec;
+                        return runner.resumeStream(d.token, d.outcome, resumeConfig, { ...runInternals, ...(d.inheritedGate !== undefined ? { inheritedGate: d.inheritedGate } : {}) });
+                    });
             }
             catch (err) {
+                if (drive !== undefined && !finalized) {
+                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${err instanceof Error ? err.message : String(err)}); the park stands.`);
+                    releaseLeg();
+                    return await parkAgentLeg(rec, drive.paused, [], false);
+                }
                 if (!finalized && rec.errorMessage === undefined && err instanceof Error && err.message !== "")
                     rec.errorMessage = boundedRedactedSummary(err.message, MAX_TRANSCRIPT_CHARS);
                 if (!finalized && err instanceof WorkflowAgentBlockedError) {
@@ -1651,7 +1860,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     }).catch(() => undefined);
                 }
                 recordFailed();
-                releaseOnce();
+                releaseLeg();
                 bceTerminal(callKey, "failed", err instanceof Error ? err.message : String(err), undefined, undefined);
                 throw err;
             }
@@ -1691,7 +1900,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         accumulateStats({ stats: partialSpend }, true);
                     }
                     recordFailed();
-                    releaseOnce();
+                    releaseLeg();
                     void journalAppend(callKey, {
                         taskId: callKey,
                         sessionId: "",
@@ -1704,11 +1913,15 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 }
                 rollbackUsageBeat();
                 activeUsageBeats.delete(activeBeat);
-                releaseOnce();
+                releaseLeg();
                 if (finalized)
                     return result;
-                if (isDurablePause(result.terminal)) {
-                    result = mapNestedSuspend(result);
+                if (isPausedResult(result)) {
+                    return await parkAgentLeg(rec, result, activityTail, true);
+                }
+                if (drive !== undefined && driveNeverStarted(result)) {
+                    emitRunLog(`[park] the parked leg "${label}" was driven but the approved action never started (${result.terminal.kind === "failed" ? result.terminal.code : ""}); the park stands.`);
+                    return await parkAgentLeg(rec, drive.paused, activityTail, false);
                 }
                 await settleAgentResult(rec, result, activityTail, agentOpts, "best-effort");
                 return result;
@@ -1866,12 +2079,40 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     }
                     const entries = await journalStore.load(opts.resumeFromRunId, scope);
                     for (const e of entries) {
+                        const parked = e.parked;
+                        if (parked !== undefined) {
+                            const pt = parked?.terminal;
+                            if (pt === null || typeof pt !== "object" || pt.kind !== "paused" || typeof pt.token !== "string" || pt.token.length === 0) {
+                                throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), callKeyOrdinal(e.callKey));
+                            }
+                            replayByOrdinal[callKeyOrdinal(e.callKey)] = e;
+                            continue;
+                        }
                         const t = e.result?.terminal;
                         if (t === null || typeof t !== "object" || !isTerminalCauseKind(t.kind)) {
                             throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), callKeyOrdinal(e.callKey));
                         }
                         replayByOrdinal[callKeyOrdinal(e.callKey)] = e;
                     }
+                    if (opts.store !== undefined) {
+                        let prior;
+                        try {
+                            prior = await opts.store.get(opts.resumeFromRunId);
+                        }
+                        catch (err) {
+                            throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), -1, `the prior run's record could not be read from the run store (${err instanceof Error ? err.message : String(err)}), so a lost park cannot be ruled out`);
+                        }
+                        if (prior !== null && prior.scope === scope) {
+                            for (const row of prior.agents) {
+                                if (row.status !== "parked")
+                                    continue;
+                                const ord = callKeyOrdinal(row.callKey);
+                                if (replayByOrdinal[ord]?.parked === undefined) {
+                                    throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), ord, `the prior run's agent #${ord} ("${row.label.slice(0, 80)}") is PARKED on an approval checkpoint but its journal entry is missing (the park was not recorded) — a resume would run that call live beside the pinned child`);
+                                }
+                            }
+                        }
+                    }
                     run.resume = {
                         fromRunId: clampRunIdText(opts.resumeFromRunId),
                         journalEntries: entries.length,
@@ -1912,6 +2153,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             else {
                 result = await bodyPromise;
             }
+            if (parkedLeg !== undefined) {
+                await awaitLegsIdle(workflowSignal);
+                throw parkedError();
+            }
+            await carryUnresolvedParks();
             if (maxResultChars !== undefined) {
                 let size = 0;
                 try {
@@ -1944,6 +2190,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             return { result, runId, run };
         }
         catch (err) {
+            if (parkedLeg !== undefined)
+                await awaitLegsIdle(workflowSignal);
+            await carryUnresolvedParks();
             finalized = true;
             const unsettledOnFailure = settleActiveUsageBeats();
             stampBudgetOvershoot(unsettledOnFailure);
@@ -1952,6 +2201,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             run.status = "failed";
             run.completionId ??= uuidv7();
             run.endedAt = now();
+            if (parkedLeg !== undefined && !(err instanceof WorkflowAgentParkedError))
+                err = parkedError();
             run.error = err instanceof Error ? err.message : String(err);
             closeAbandonedAgents(run.endedAt);
             restampPhaseFailures();

package/dist/stores/file/workflow-journal-store.js

@@ -7,6 +7,11 @@ import { canonicalStoreKey, sanitizePathComponent, writeThenLink } from "./fs-at
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { oversizeJournalResult } from "../../core/workflow-journal-store.js";
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
+function entryOf(rec) {
+    if (rec.parked !== undefined)
+        return { callKey: rec.callKey, parked: rec.parked };
+    return { callKey: rec.callKey, result: rec.result };
+}
 export const RESUME_CLAIM_TTL_MS = 60 * 60 * 1000;
 export const RESUME_CLAIM_RELEASE_GRACE_MS = 5_000;
 export const RESUME_CLAIM_SWEEP_INTERVAL_MS = 60_000;
@@ -82,12 +87,12 @@ export class FileWorkflowJournalStore {
             scope = scope ?? rec.scope;
             if (rec.scope !== scope)
                 continue;
-            byOrdinal.set(rec.ordinal, { callKey: rec.callKey, result: rec.result });
+            byOrdinal.set(rec.ordinal, entryOf(rec));
         }
         return scope === undefined ? undefined : { scope, byOrdinal };
     }
     async append(runId, scope, entry) {
-        const serialized = JSON.stringify(entry.result);
+        const serialized = JSON.stringify(entry.parked !== undefined ? entry.parked : entry.result);
         if (oversizeJournalResult(serialized))
             return;
         const committed = this.scopes.get(runId) ?? this.replay(runId)?.scope;
@@ -115,7 +120,9 @@ export class FileWorkflowJournalStore {
             catch {
             }
         }
-        const line = { scope, ordinal: callKeyOrdinal(entry.callKey), callKey: entry.callKey, result: entry.result };
+        const line = entry.parked !== undefined
+            ? { scope, ordinal: callKeyOrdinal(entry.callKey), callKey: entry.callKey, parked: entry.parked }
+            : { scope, ordinal: callKeyOrdinal(entry.callKey), callKey: entry.callKey, result: entry.result };
         log.append(line, this.fsyncEnabled);
     }
     async load(runId, scope) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.9.2",
+  "version": "7.10.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",