@sema-agent/core 7.16.0 → 7.17.0

package/dist/orchestration/run-workflow-tool.js

@@ -6,7 +6,15 @@ import { withDelegationProvenance } from "../core/tool-policy.js";
 import { LAUNCH_RECEIPT_OWN_WORDS_CLAUSE, launchReceiptNoQuoteClause } from "../agents/launch-receipt-contract.js";
 import { startWorkflow } from "./workflow.js";
 import { WORKFLOW_AGENT_PARKED_ERROR_CODE } from "./workflow-types.js";
+import { checkpointStoreOfSeat } from "../core/checkpoint-seat.js";
 import { buildWorkflowPrimitives } from "./workflow-primitives.js";
+import { stripSpawnTurnQuestionFace } from "../core/ask-question.js";
+import { parentSpecSeatOfCtx } from "../core/parent-spec-seat.js";
+import { assertNoRetiredKeys } from "../core/retired-keys.js";
+const RETIRED_RUN_WORKFLOW_TOOL_DEPS_KEYS = {
+    principal: "the host run's principal rides `RunWorkflowToolDeps.parentSpecSeat.principal` (the parent SPEC seat the host's prepare mints), never a seat of its own",
+    oneShot: "the host run's one-shot fact rides `RunWorkflowToolDeps.parentSpecSeat.oneShot` (only `true` travels), never a seat of its own",
+};
 import { parseWorkflowMeta, splitWorkflowMeta, workflowScriptReadsClockOrRandom } from "./workflow-meta.js";
 import { mergeWorkflowArgs, normalizeStringArg } from "./workflow-script-store.js";
 import { builtinWorkflowListings, canonicalWorkflowName, resolveBuiltinWorkflow, workflowNameProbeOrder } from "./builtin-workflows.js";
@@ -169,6 +177,7 @@ async function collectNamedWorkflowListings(store, builtinsEnabled) {
     return [...byName.values()];
 }
 export async function createRunWorkflowTool(d) {
+    assertNoRetiredKeys(d, RETIRED_RUN_WORKFLOW_TOOL_DEPS_KEYS, "RunWorkflowToolDeps");
     if (d.scriptRunner.safeForUntrustedScripts !== true) {
         throw new Error("createRunWorkflowTool: refusing to mount run_workflow on a runner that is not safeForUntrustedScripts (design/98 fail-closed)");
     }
@@ -304,7 +313,8 @@ export async function createRunWorkflowTool(d) {
             "concurrent agents WRITE THE SAME FILES/REPO and must not clobber each other — even as a parallel fan-out " +
             "(plain parallel would clobber); this takes precedence over plain parallel. A separate-working-copy need, " +
             "NOT merely 'several agents'.\n" +
-            "• resumeFromRunId (this tool's arg): RESUME a prior/crashed run — replay its completed agents, run only new work.\n" +
+            "• resumeFromRunId (this tool's arg): RESUME a prior/crashed run — replay its completed agents, run only new work " +
+            "(a run that could park must have finished — a crashed park-capable run is decided through the deployment's approval channel, not resumed).\n" +
             "• scriptPath / name (this tool's args): when a script store is wired, every run persists its script and " +
             "returns its scriptPath — to iterate, EDIT that file and re-invoke with {scriptPath} instead of resending " +
             "the full script; {name} runs a saved workflow.\n" +
@@ -392,7 +402,10 @@ export async function createRunWorkflowTool(d) {
             const rawResume = rawArgs.resumeFromRunId;
             const resumeFromRunId = typeof rawResume === "string" && rawResume.length > 0 ? rawResume : undefined;
             const sourceTaskId = ctx.taskId ?? d.sourceTaskId;
-            const principal = ctx.principal ?? d.principal;
+            const hostSeat = parentSpecSeatOfCtx(ctx) ?? d.parentSpecSeat;
+            const detachedSeat = hostSeat !== undefined ? stripSpawnTurnQuestionFace(hostSeat) : undefined;
+            const parentSpecSeat = detachedSeat?.spec;
+            const principal = parentSpecSeat?.principal;
             const taskScope = ctx.principal ?? d.scope;
             let script;
             let registeredDefaultArgs;
@@ -487,8 +500,10 @@ export async function createRunWorkflowTool(d) {
                     },
                 }
                 : governance;
+            const childParkSeat = ctx.checkpointStoreForChildren ?? d.parentCheckpointStore;
+            const parkStore = checkpointStoreOfSeat(childParkSeat);
             const scriptFn = (wfCtx) => {
-                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, principal, ctx.checkpointStoreForChildren ?? d.parentCheckpointStore, d.parentReadFace, d.parentReadDenyPatterns, ctx.handsReadOnly === true || d.parentHandsReadOnly === true, ctx.interactiveTools === false || d.parentInteractiveTools === false);
+                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, childParkSeat, d.parentReadFace, d.parentReadDenyPatterns, ctx.handsReadOnly === true || d.parentHandsReadOnly === true, ctx.interactiveTools === false || d.parentInteractiveTools === false);
                 return d.scriptRunner.run({ scriptSource: script, primitives, scriptArgs: effectiveArgs, signal: wfCtx.signal }).then((r) => r.result);
             };
             if (ctx.signal?.aborted) {
@@ -503,6 +518,7 @@ export async function createRunWorkflowTool(d) {
             try {
                 handle = startWorkflow(d.runner, scriptFn, {
                     store: d.store,
+                    ...(parkStore !== undefined ? { checkpointStore: parkStore } : {}),
                     ...(d.agents !== undefined ? { agents: d.agents } : {}),
                     ...(d.builtinAgents !== undefined ? { builtinAgents: d.builtinAgents } : {}),
                     name: meta.name,
@@ -548,7 +564,9 @@ export async function createRunWorkflowTool(d) {
                     ...(d.parentModel !== undefined ? { defaultModel: d.parentModel } : {}),
                     ...(d.parentThinking !== undefined ? { defaultThinking: d.parentThinking } : {}),
                     ...(d.parentGetApiKeyAndHeaders !== undefined ? { defaultGetApiKeyAndHeaders: d.parentGetApiKeyAndHeaders } : {}),
-                    ...(hostDurableApproval !== undefined && d.store !== undefined ? { defaultDurableApproval: { ...hostDurableApproval } } : {}),
+                    ...(parentSpecSeat !== undefined ? { parentSpecSeat } : {}),
+                    ...(detachedSeat?.internalsFlag.questionFaceStripped === true || ctx.questionFaceStripped === true || d.parentQuestionFaceStripped === true ? { questionFaceStripped: true } : {}),
+                    ...(hostDurableApproval !== undefined && d.store !== undefined && parkStore !== undefined ? { defaultDurableApproval: { ...hostDurableApproval } } : {}),
                     ...(resumeFromRunId !== undefined && d.parkedResume !== undefined && d.parkedResume(resumeFromRunId) !== undefined ? { parkedResume: d.parkedResume(resumeFromRunId) } : {}),
                     ...(parentCenterArtifactDigest !== undefined ? { parentCenterArtifactDigest } : {}),
                     ...(parentCenterSourceRevision !== undefined ? { parentCenterSourceRevision } : {}),
@@ -662,7 +680,7 @@ export async function createRunWorkflowTool(d) {
                         const carries = pollExpr
                             ? ` A terminal ${pollExpr} reply carries its result AND per-agent rows — read them${journalRef !== undefined ? ` (full journal: ${journalRef})` : ""} before assuming an empty or unexpected result.`
                             : "";
-                        if (d.oneShot === true) {
+                        if (parentSpecSeat?.oneShot === true) {
                             return blockingPollExpr
                                 ? `This is a ONE-SHOT submission (e.g. headless \`-p\`) — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: ${blockingPollExpr}. If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.${carries}`
                                 : "This is a one-shot submission (e.g. headless `-p`) and no poll path is available — the workflow's outcome may not be recoverable after this turn ends.";

package/dist/orchestration/workflow-primitives.d.ts

@@ -34,9 +34,11 @@ export interface WorkflowGovernance {
  * `agent` primitive is GOVERNED when `governance` is set (LLM-authored), else a trusted pass-through.
  * The host's model and thinking are NOT injected here: both are seats the launch site (`workflow.ts`,
  * `withWorkflowChildSeats`) fills AFTER the agentType fold, so a definition's own value is the explicit rung
- * — filling them here ran ahead of the fold and made the fold's "when unset" guard permanently false.
+ * — filling them here ran ahead of the fold and made the fold's "when unset" guard permanently false. The parent
+ * SPEC seat (principal, oneShot, clientContext, the question face, the fs-fence widening, envFacts, the persistence
+ * statement) is applied there for the same reason (`applyParentSpecSeat`).
  */
-export declare function buildWorkflowPrimitives(ctx: WorkflowRunContext, governance?: WorkflowGovernance, onAgentSpawn?: (handle: WorkflowAgentHandle) => void, parentPrincipal?: string, 
+export declare function buildWorkflowPrimitives(ctx: WorkflowRunContext, governance?: WorkflowGovernance, onAgentSpawn?: (handle: WorkflowAgentHandle) => void, 
 /** The host run's RESOLVED checkpoint seat — the store object it parks in, else the word `"disabled"`.
  *  Every agent this workflow spawns inherits it; see the injection below. */
 parentCheckpointStore?: CheckpointStore | "disabled", 

package/dist/orchestration/workflow-primitives.js

@@ -65,7 +65,7 @@ function formatResourceClampNote(notes) {
     const parts = notes.map((n) => `${n.field}: requested ${n.requested === undefined ? "unset" : n.requested} → applied ${n.applied}`);
     return `workflow governance tightened this agent's resource limits (${parts.join("; ")})`;
 }
-export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentPrincipal, parentCheckpointStore, parentReadFace, parentReadDenyPatterns, parentHandsReadOnly, parentInteractiveToolsOff) {
+export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentCheckpointStore, parentReadFace, parentReadDenyPatterns, parentHandsReadOnly, parentInteractiveToolsOff) {
     const agent = (spec, opts) => {
         if (typeof spec === "string")
             spec = { objective: spec };
@@ -74,9 +74,6 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentPri
         const childSpec = governance
             ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)), governance.onNotice)
             : { ...spec };
-        if (childSpec.principal === undefined && parentPrincipal !== undefined) {
-            childSpec.principal = parentPrincipal;
-        }
         if (parentCheckpointStore !== undefined && (parentCheckpointStore === "disabled" || childSpec.checkpointStore === undefined)) {
             childSpec.checkpointStore = parentCheckpointStore;
         }

package/dist/orchestration/workflow-types.d.ts

@@ -4,6 +4,17 @@ export type WorkflowRunStatus = "running" | "completed" | "failed";
  *  agent durably paused at an approval gate and the run suspended on it (the row carries the token, see
  *  {@link WorkflowAgentRun.parkedCheckpointToken}); a phase or group never parks (a parked agent ends the run). */
 export type WorkflowItemStatus = "running" | "completed" | "failed" | "parked";
+/** The arm a `workflow.park_truth_unreadable` resume refusal fired on (`detail.reason`): the prior run's record could not
+ *  be read (`store_threw`), is absent under this scope (`record_missing`), is not terminal (`record_not_terminal`) or
+ *  carries no `parks` array (`parks_unreadable`); a candidate's checkpoint could not be read (`checkpoint_store_threw`);
+ *  or the record/journal name parks while this workflow holds no checkpoint seat to prove them (`capability_not_armed`).
+ *  Registered in docs/CLOSED-SETS.md with a mint obligation: every throw site spells its word. */
+export declare const PARK_TRUTH_UNREADABLE_REASONS: readonly ["store_threw", "record_missing", "record_not_terminal", "parks_unreadable", "checkpoint_store_threw", "capability_not_armed"];
+export type ParkTruthUnreadableReason = (typeof PARK_TRUTH_UNREADABLE_REASONS)[number];
+/** What the checkpoint store said about a parked ordinal's token when a resume carried no acknowledgement for it
+ *  (`workflow.park_not_pending`, `detail.status`): the row's own word, or `absent` when the store holds no row. */
+export declare const PARK_NOT_PENDING_STATUSES: readonly ["resolved", "expired", "absent"];
+export type ParkNotPendingStatus = (typeof PARK_NOT_PENDING_STATUSES)[number];
 export interface WorkflowPhase {
     title: string;
     /** F7/B7 (CC pretty.js:446478): a phase PRE-REGISTERED from `meta.phases` starts as `"pending"` — the plan
@@ -125,10 +136,11 @@ export interface WorkflowAgentRun {
      * #642 — the durable-approval checkpoint token this agent is PARKED on (`status: "parked"` only): the child
      * durably paused at an approval gate under the host's forwarded `durableApproval`, the run recorded the
      * park here and suspended. The mirror of the background agent row's `parkedCheckpointToken`, and the
-     * workflow-origin JOIN a host routes a parked approval by: a checkpoint whose `sourceTaskId` equals this
-     * row's {@link sessionId} is a workflow child's park, and this token is the same row's redemption key —
-     * the checkpoint row itself carries no workflow key. It is the resume CAPABILITY (never log it or put it
-     * in a URL); a durable row is its home exactly as on the background lane. Absent on every other status.
+     * workflow-origin JOIN a host routes a parked approval by: the checkpoint row whose `sessionId` equals this
+     * row's {@link sessionId} and whose token equals this one is a workflow child's park (the engine's own
+     * truth read binds on the same two facts — `WorkflowRun.parks`); the checkpoint row itself carries no
+     * workflow key. It is the resume CAPABILITY (never log it or put it in a URL); a durable row is its home
+     * exactly as on the background lane. Absent on every other status.
      */
     parkedCheckpointToken?: string;
     /**
@@ -374,6 +386,24 @@ export interface WorkflowRun {
         divergedAtOrdinal?: number;
         divergedReason?: string;
     };
+    /**
+     * Every park this run is RESPONSIBLE for: its own (written at the park) and the ones it inherited from the run
+     * it resumed and did not settle (written at resume admission). KEYS ONLY — the truth of a park is the checkpoint
+     * store (`get(token).status`), never this list: a listed token may be resolved, expired or reaped, and the next
+     * resume reads the store for every entry. Present on every record this engine writes (`[]` when there is none)
+     * EXCEPT a record whose resume admission refused before its inherited set was established (deliberately absent:
+     * not a resume base). It is an ADMISSION INPUT of the next resume, so a store must project it verbatim and keep
+     * it through any size degrade; a reader treats absence as a state (an older engine's record, a stripped
+     * projection), never as `[]`. `token` is the same capability as {@link WorkflowAgentRun.parkedCheckpointToken}
+     * (never log it, never put it in a URL); `originRunId` is the run whose journal holds the `parked` entry for
+     * `callKey` (the re-park material).
+     */
+    parks?: Array<{
+        callKey: string;
+        sessionId: string;
+        token: string;
+        originRunId: string;
+    }>;
     /** RB-243: how many agent results were NOT journaled because they exceeded the per-entry size
      *  cap ({@link MAX_JOURNAL_RESULT_BYTES}) — each skip also logs and journals a tombstone. Additive
      *  observation; absent when 0. */

package/dist/orchestration/workflow-types.js

@@ -1,3 +1,5 @@
+export const PARK_TRUTH_UNREADABLE_REASONS = ["store_threw", "record_missing", "record_not_terminal", "parks_unreadable", "checkpoint_store_threw", "capability_not_armed"];
+export const PARK_NOT_PENDING_STATUSES = ["resolved", "expired", "absent"];
 export class WorkflowBudgetExceededError extends Error {
     spent;
     total;

package/dist/orchestration/workflow.d.ts

@@ -1,7 +1,8 @@
 import type { TSchema } from "typebox";
 import type { InheritedGate, RunnerSelfSeat } from "../core/runner/contracts.js";
-import type { CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
+import type { CheckpointStore, CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
 import type { AgentDefinition, TaskEvent, TaskResult, TaskSpec, ThinkingLevel } from "../core/types.js";
+import { type ParentSpecSeat } from "../core/parent-spec-seat.js";
 import type { WorkflowRunStore } from "../core/workflow-run-store.js";
 import type { WorkflowJournalStore, ResumeClaimArgs } from "../core/workflow-journal-store.js";
 import type { WorkflowRun, WorkflowEvent } from "./workflow-types.js";
@@ -123,9 +124,7 @@ export declare class WorkflowJournalIncompatibleError extends Error {
     readonly fromRunId: string;
     readonly ordinal: number;
     readonly code = "workflow.journal_incompatible";
-    constructor(fromRunId: string, ordinal: number, 
-    /** #642: an alternative reason clause (the parked-row cross-check); absent ⇒ the no-terminal-cause wording. */
-    reason?: string);
+    constructor(fromRunId: string, ordinal: number);
 }
 /**
  * A TRUSTED, run-scoped internal channel carrying the workflow **nesting depth** across a process boundary
@@ -292,11 +291,16 @@ export interface WorkflowRunContext {
  * the checkpoint token the wa* row is parked on (the row's `parkedCheckpointToken`, the redemption key), the
  * caller's decision for it (the same {@link ResumeOutcome} a top-level `runner.resume` takes), and the optional
  * cross-process re-supply of the checkpoint's opaque parent constraints. The token is matched by string equality
- * against the journaled parked entry — an entry whose token no decision names re-parks.
+ * against the parked ordinal's token — an ordinal whose token no entry names re-parks.
+ *
+ * `outcome` is OPTIONAL. `{ token, outcome }` is a DECISION: a pending checkpoint is driven with it; one the store no
+ * longer calls pending is settled (the acknowledgement is implied). `{ token }` alone is an ACKNOWLEDGEMENT: it settles an
+ * ordinal whose checkpoint is resolved / expired / absent as a failed row (`workflow.park_not_pending`) so the script
+ * continues; if the re-read finds the checkpoint pending again it RE-PARKS — an acknowledgement never authorizes a drive.
  */
 export interface WorkflowParkedResume {
     token: CheckpointToken;
-    outcome: ResumeOutcome;
+    outcome?: ResumeOutcome;
     inheritedGate?: InheritedGate;
 }
 export interface RunWorkflowOptions {
@@ -468,9 +472,37 @@ export interface RunWorkflowOptions {
      * parked child on with the caller's decision ({@link parkedResume}). Tighten-only: a park capability,
      * never a widening — the decision stays with a person. REQUIRES {@link store} (the wa* row's durable home;
      * refused loudly at entry without it). Threaded by the Workflow tool from the host's trusted seat; a
-     * directly-started workflow passes its own. NOT call identity.
+     * directly-started workflow passes its own. NOT call identity. REQUIRES {@link checkpointStore} as well: a
+     * durable approval whose checkpoint this workflow cannot read back is a park no resume can prove.
      */
     defaultDurableApproval?: TaskSpec["durableApproval"];
+    /**
+     * The HOST run's parent SPEC seat ({@link import("../core/parent-spec-seat.js").ParentSpecSeat}: principal / oneShot /
+     * clientContext / the frozen question face / the fs-fence widening / envFacts / the declared persistence statement),
+     * applied onto every spawned agent at the launch site AFTER the agentType fold by {@link applyParentSpecSeat} — the
+     * Task delegation lane's one law: a value the child spec carries (script, definition, baseline) WINS, the seat FILLS
+     * an unset one, the two removals (`oneShot: true`, `memoryPersistenceCapable: false`) land unconditionally. Threaded
+     * by the Workflow tool from the host's seat; a directly-started workflow passes its own. NOT call identity (host
+     * wiring, like the checkpoint seat). Absent ⇒ nothing is applied. The seat the Workflow tool threads carries NO
+     * `onQuestion`: the tool strips the host's per-request face (every agent it spawns outlives the launching request)
+     * and says so through {@link questionFaceStripped}; a directly-started workflow passes what its own lifetime allows.
+     */
+    parentSpecSeat?: ParentSpecSeat;
+    /** The engine stripped the spawn turn's per-request question face from the seat above (pair-produced with the strip,
+     *  `stripSpawnTurnQuestionFace`); rides every spawned agent's internals as `RunInternals.questionFaceStripped` — the
+     *  wiring manifest's `question.wired: "stripped_bg_lane"` and the posture door's exemption read it. */
+    questionFaceStripped?: true;
+    /**
+     * The checkpoint store this run's children park in — the RESOLVED seat object itself (the same value the Workflow
+     * tool injects onto every child spec; a directly-started workflow passes the store its children park in). Its
+     * presence ARMS the park lane: a resume then proves every parked ordinal against `get(token)` before anything is
+     * dispatched (`WorkflowRun.parks` supplies the keys), and a child whose effective `checkpointStore` is a DIFFERENT
+     * object is refused at spawn (`config.invalid_checkpoint_store` — identity, not duck-typing: a caller-built `{get}`
+     * wrapper is not the seat). REQUIRES {@link store} (the park's durable row). Absent ⇒ the lane is not armed: a
+     * resume of a run that recorded parks is refused (`workflow.park_truth_unreadable` / `capability_not_armed`), a run
+     * without parks resumes as before. NOT call identity (deployment wiring, like the store seats).
+     */
+    checkpointStore?: CheckpointStore;
     /**
      * #642 — the decisions a resume ({@link resumeFromRunId}) carries for PARKED ordinals of the prior run: at
      * an ordinal whose journal entry is `parked` (a matching call key), the run drives the parked child's own