@sema-agent/core 7.9.1 → 7.10.0

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

@@ -1,7 +1,9 @@
 import type { TaskResult, TaskStatus, ToolActivity } from "../core/types.js";
 export type WorkflowRunStatus = "running" | "completed" | "failed";
-/** Status of one phase / agent-run within a workflow. */
-export type WorkflowItemStatus = "running" | "completed" | "failed";
+/** Status of one phase / agent-run within a workflow. `"parked"` (#642) is an AGENT row's word only — the
+ *  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";
 export interface WorkflowPhase {
     title: string;
     /** F7/B7 (CC pretty.js:446478): a phase PRE-REGISTERED from `meta.phases` starts as `"pending"` — the plan
@@ -119,6 +121,16 @@ export interface WorkflowAgentRun {
      *  (`fork(sessionId)→runTask`, or `runTask({sessionId})`) instead of a fresh re-run. An opaque id (not
      *  content) → scope-gated via `getWorkflowRun`, no redaction needed. Absent for a stub run that minted none. */
     sessionId?: string;
+    /**
+     * #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.
+     */
+    parkedCheckpointToken?: string;
     /**
      * #499 — the ENGINE-minted identity of the task run behind this record (= its `TaskResult.runId`).
      *
@@ -515,6 +527,29 @@ export declare class WorkflowAgentBlockedError extends Error {
     /** Human-readable cause, already bounded + redacted by the engine (classifier text is model output). */
     reason: string);
 }
+/** #642 — the machine code of a run that SUSPENDED on a parked agent (the thrown error's `code`, the run's
+ *  failed terminal). Not a script fault and not a host fault: an approval a person still has to decide. */
+export declare const WORKFLOW_AGENT_PARKED_ERROR_CODE = "workflow.agent_parked";
+/**
+ * #642 — thrown by `ctx.agent` / `ctx.agentStream().result()` when the child durably PAUSED at an approval gate
+ * under the host's forwarded `durableApproval` (the workflow lane's park family, the background delegation's
+ * twin): the wa* row records `status:"parked"` + `parkedCheckpointToken`, the journal records the parked leg at
+ * its ordinal, and the RUN SUSPENDS — every later spawn is refused with this same error and the run's terminal
+ * is this park whatever the script body returns (the team-discussion `teamPause` shape). Nothing after the
+ * parked call runs; the script must not retry it (an identical call parks again). A resume of the run
+ * (`resumeFromRunId`) with the host's decision for the token drives the parked child on and the script
+ * continues from here; without a decision the ordinal re-parks.
+ *
+ * Carries the non-secret `checkpointId` (display/correlation) and the gate kind — never the token (the resume
+ * capability lives on the wa* row, a durable row, exactly as on the background lane).
+ */
+export declare class WorkflowAgentParkedError extends Error {
+    readonly label: string;
+    readonly gateKind: string;
+    readonly checkpointId?: string | undefined;
+    readonly code = "workflow.agent_parked";
+    constructor(label: string, gateKind: string, checkpointId?: string | undefined);
+}
 /** design/98 §D.6 hard cap: thrown by `ctx.agent` once the workflow has spawned `max` agents (a runaway
  *  LLM-authored script is bounded, not trusted — this counts cumulative spawns, so it binds even when the
  *  token budget has room left, or when no budget was set at all). */

package/dist/orchestration/workflow-types.js

@@ -55,6 +55,22 @@ export class WorkflowAgentBlockedError extends Error {
         this.name = "WorkflowAgentBlockedError";
     }
 }
+export const WORKFLOW_AGENT_PARKED_ERROR_CODE = "workflow.agent_parked";
+export class WorkflowAgentParkedError extends Error {
+    label;
+    gateKind;
+    checkpointId;
+    code = WORKFLOW_AGENT_PARKED_ERROR_CODE;
+    constructor(label, gateKind, checkpointId) {
+        super(`workflow agent "${label}" is parked at an approval gate (${gateKind}${checkpointId !== undefined ? `, checkpoint ${checkpointId}` : ""}) — ` +
+            "the workflow is suspended until the approval is decided; nothing after this call runs. Do not re-issue the call: " +
+            "a resume of this run carrying the decision continues from here.");
+        this.label = label;
+        this.gateKind = gateKind;
+        this.checkpointId = checkpointId;
+        this.name = "WorkflowAgentParkedError";
+    }
+}
 export class WorkflowMaxAgentsError extends Error {
     max;
     budgetTotal;

package/dist/orchestration/workflow.d.ts

@@ -1,5 +1,6 @@
 import type { TSchema } from "typebox";
-import type { RunnerSelfSeat } from "../core/runner/contracts.js";
+import type { InheritedGate, RunnerSelfSeat } from "../core/runner/contracts.js";
+import type { CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
 import type { AgentDefinition, TaskEvent, TaskResult, TaskSpec } from "../core/types.js";
 import type { WorkflowRunStore } from "../core/workflow-run-store.js";
 import type { WorkflowJournalStore, ResumeClaimArgs } from "../core/workflow-journal-store.js";
@@ -120,7 +121,9 @@ export declare class WorkflowJournalIncompatibleError extends Error {
     readonly fromRunId: string;
     readonly ordinal: number;
     readonly code = "workflow.journal_incompatible";
-    constructor(fromRunId: string, ordinal: number);
+    constructor(fromRunId: string, ordinal: number, 
+    /** #642: an alternative reason clause (the parked-row cross-check); absent ⇒ the no-terminal-cause wording. */
+    reason?: string);
 }
 /**
  * A TRUSTED, run-scoped internal channel carrying the workflow **nesting depth** across a process boundary
@@ -282,6 +285,18 @@ export interface WorkflowRunContext {
     /** Emit a narrator log line (observability only — not stored on the run). */
     log(message: string): void;
 }
+/**
+ * #642 — one decision a resume carries for a PARKED ordinal of the prior run ({@link RunWorkflowOptions.parkedResume}):
+ * 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.
+ */
+export interface WorkflowParkedResume {
+    token: CheckpointToken;
+    outcome: ResumeOutcome;
+    inheritedGate?: InheritedGate;
+}
 export interface RunWorkflowOptions {
     /** Trusted caller-supplied run id. Used by the unified task registry so tool-launched workflows expose
      *  `task_id === runId` (`w*`) without making the model choose an id. Omit for the legacy UUID mint path. */
@@ -435,6 +450,30 @@ export interface RunWorkflowOptions {
      *  credential half of model inheritance; scripts can never set it — governance strips it — so
      *  this is always the host's). NOT call identity (auth, not behavior; a function, not data). */
     defaultGetApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
+    /**
+     * #642 — the HOST run's `durableApproval` opt-in (value copy), inherited into every spawned agent whose
+     * fold left the seat unpinned (a deployment baseline that pins `durableApproval` wins; scripts can never set
+     * it — governance strips it). With it a workflow child's plain policy `ask` — an ask the host's approver
+     * answers `unavailable` for, or a durable mandate — PARKS durably instead of denying fail-closed, exactly as
+     * a background delegation child's does under the §7.3 park family: the wa* row records `status:"parked"` +
+     * the token, the run SUSPENDS (the script cannot continue past a parked call), and a resume drives the
+     * 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.
+     */
+    defaultDurableApproval?: TaskSpec["durableApproval"];
+    /**
+     * #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
+     * resume — `runner.resumeStream(token, outcome, …)` on the pinned session, the child's spec rebuilt from
+     * the script call exactly as at spawn — and settles its result at that ordinal, so the script continues past
+     * the call it parked on. A parked ordinal with NO decision here re-parks (the row and the journal say the
+     * same thing again, the run suspends again); it is never run live. `inheritedGate` is the cross-process
+     * re-supply of the checkpoint's opaque parent constraints (the same seat the background lane's drive
+     * takes). TRUSTED: a host-supplied decision, never a script/model argument; requires `resumeFromRunId`.
+     */
+    parkedResume?: ReadonlyArray<WorkflowParkedResume>;
     /** design/148 S1 — the HOST run's adopted center artifact (trusted, threaded by the Workflow tool
      *  from ctx): every spawned agent composes the same closure. */
     parentCenterArtifactDigest?: string;