@agentproto/workflow-runtime 0.11.1 → 0.13.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { DriverHandle, ResolverContext } from '@agentproto/driver';
 import { ToolContext, ToolHandle } from '@agentproto/tool';
-import { ZodType } from 'zod';
 import { WorkflowHandle } from '@agentproto/workflow';
 import { FsPort, FsStat, FsLockHandle } from '@agentproto/corpus';
 
@@ -27,6 +26,13 @@ interface Bindings {
     readonly item?: unknown;
     /** Present inside a `map` body — the element's index. */
     readonly index?: number;
+    /** AIP-58 §4 Run workspace — present when the host wires
+     *  {@link RunWorkflowArgs.workspace}. `$run.workspace` / `{{run.workspace}}`
+     *  is a convenience alias for the same absolute path AIP-16 injects as
+     *  `$input._workflowFsRoot` — steps may use either. */
+    readonly run?: {
+        readonly workspace: string;
+    };
 }
 /** The AIP-16 IO seam: read a value out of the run bindings. */
 type Selector<T> = (bindings: Bindings) => T;
@@ -67,6 +73,14 @@ type FanOutOutcome<T = unknown> = {
     readonly item: unknown;
     /** `err.message` if the throw was an `Error`, else `String(err)`. */
     readonly error: string;
+} | {
+    /** Never started: the fan-out's spawn circuit breaker opened first
+     *  (see {@link MapStep.maxConsecutiveSpawnFailures}). */
+    readonly status: "skipped";
+    readonly index: number;
+    readonly item: unknown;
+    /** `circuit-open: <first error of the failure streak>`. */
+    readonly reason: string;
 };
 /**
  * The bound output of a `map`/`pipeline` step run with `onError: "collect"`:
@@ -77,7 +91,17 @@ interface TolerantFanOutResult<T = unknown> {
     readonly results: readonly FanOutOutcome<T>[];
     readonly succeeded: number;
     readonly failed: number;
+    /** Items never started because the spawn circuit breaker opened. */
+    readonly skipped: number;
+    /** Set when the breaker opened: the first error of the spawn-failure
+     *  streak that tripped it. */
+    readonly circuitOpen?: {
+        readonly error: string;
+    };
 }
+/** Default for {@link MapStep.maxConsecutiveSpawnFailures} /
+ *  {@link PipelineStep.maxConsecutiveSpawnFailures}. */
+declare const DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES = 3;
 /**
  * Run a sub-step once per element of an array, optionally with bounded
  * concurrency. The element + index are exposed to the body via `bindings.item`
@@ -99,6 +123,17 @@ interface MapStep {
      * silently dropped.
      */
     onError?: "throw" | "collect";
+    /**
+     * `"collect"` only: once this many items IN A ROW fail because an agent
+     * step's session could not be spawned ({@link AgentSpawnError}), stop
+     * starting new items — the failure is systemic, not per-item. In-flight
+     * items finish; every item not yet started is reported skipped
+     * (`circuit-open: <first error>`) and the map returns normally. A settled
+     * item that isn't a spawn failure resets the streak. Default
+     * {@link DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES}; `0` disables the breaker.
+     * (`"throw"` already stops at the first failure of any kind.)
+     */
+    maxConsecutiveSpawnFailures?: number;
 }
 /**
  * Run N items through K sequential stage bodies with NO cross-item barrier:
@@ -120,6 +155,8 @@ interface PipelineStep {
      *  `"collect"` runs every item's chain to completion and binds a
      *  {@link TolerantFanOutResult} instead of a bare array. */
     onError?: "throw" | "collect";
+    /** Same semantics as {@link MapStep.maxConsecutiveSpawnFailures}. */
+    maxConsecutiveSpawnFailures?: number;
 }
 /** Run one of two branches based on a predicate over the bindings. */
 interface BranchStep {
@@ -128,6 +165,10 @@ interface BranchStep {
     cond: Selector<boolean>;
     then: readonly RunStep[];
     otherwise?: readonly RunStep[];
+    /** The authored step this node was compiled from, when it differs from
+     *  `id` — a multi-arm manifest `kind: branch` compiles to a chain of
+     *  nodes (`<id>`, `<id>__branch1`, …); skip reports name `<id>`. */
+    sourceId?: string;
 }
 /** Repeat a body while a predicate holds, up to a hard iteration ceiling. */
 interface LoopStep {
@@ -268,6 +309,37 @@ type AgentSandboxRef = string | {
     provider: string;
     [k: string]: unknown;
 };
+/**
+ * The minimal structural contract {@link AgentStep.outputSchema} must
+ * satisfy — exactly the `safeParse` shape `execAgentStep` consumes (never
+ * `.parse`, `._def`, or any other zod-specific member). A real zod
+ * `ZodType` satisfies this automatically (structural typing — zod's own
+ * `SafeParseReturnType` is a superset of this shape), so a TS-authored step
+ * can still pass a zod schema directly. `compileAgentStep` additionally
+ * builds one of these from a WORKFLOW.md-authored JSON Schema object (ajv
+ * `validateAgainstJsonSchema`-backed) for the declarative manifest path,
+ * where `outputSchema` is plain JSON Schema, not a zod instance.
+ */
+interface OutputSchemaLike {
+    safeParse(value: unknown): {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: {
+            issues: readonly {
+                path: readonly PropertyKey[];
+                message: string;
+            }[];
+        };
+    };
+    /** Set by `compileAgentStep`'s declarative (WORKFLOW.md) path to the raw
+     *  JSON Schema object it wrapped — lets F27's prompt-affordance render the
+     *  EXACT schema text instead of re-deriving it from the `safeParse`
+     *  closure. Absent on a TS-authored zod schema (rendered via
+     *  `z.toJSONSchema` instead — see `describeOutputSchemaForPrompt`). */
+    jsonSchema?: unknown;
+}
 /**
  * Spawn or reuse an agent session and send it a prompt, waiting for the
  * turn to complete. The host injects an {@link AgentSessionHost} — this
@@ -278,7 +350,12 @@ interface AgentStep {
     id: string;
     /** Adapter slug to spawn a NEW session. Omit to reuse via sessionRef. */
     adapter?: Selector<string> | string;
-    /** Reuse an earlier AgentStep's spawned session, by that step's id. */
+    /** Reuse an earlier AgentStep's spawned session, by that step's id. Inside
+     *  a `map`/`pipeline` body, a `{{index}}` placeholder resolves to the
+     *  current item index — `"review[{{index}}]"` names the session THIS item's
+     *  `review` step spawned (the host indexes every fan-out spawn under its
+     *  `stepKey`, `<stepId>[<index>]`), where a bare `"review"` would resolve to
+     *  whichever item spawned last. */
     sessionRef?: string;
     /** Model id override for this spawn — same semantics as `agent_start.model`
      *  (a literal string or a per-run selector resolving to one; `undefined` ⇒
@@ -308,8 +385,11 @@ interface AgentStep {
     } | {
         awaiting: "fail";
     };
-    /** Validate the session's final message against this schema; re-prompt on mismatch. */
-    outputSchema?: ZodType<unknown>;
+    /** Validate the session's final message against this schema; re-prompt on
+     *  mismatch. A zod `ZodType` (TS-authored steps) or anything else
+     *  satisfying {@link OutputSchemaLike} (a WORKFLOW.md-authored JSON
+     *  Schema object compiles into one of these — see `compileAgentStep`). */
+    outputSchema?: OutputSchemaLike;
     /** Re-prompt-and-retry attempts on schema mismatch before failing. Default 2. */
     maxRetries?: number;
     /** Cache this step's output under the run's cacheKey; the resolved prompt +
@@ -324,6 +404,54 @@ interface AgentStep {
     options?: Record<string, boolean | number | string>;
     /** Harness pinning for this step's spawn. See {@link AgentHarness}. */
     harness?: AgentHarness;
+    /** The resolved agent manifest's declared `tools` (AGENT.md `tools:`), set
+     *  by {@link CompileWorkflowOptions.agentRefs} resolution. Forwarded to the
+     *  host's `spawn` so it can mount its own tool gateway scoped to this list
+     *  (names the gateway doesn't serve — harness-native tools — match
+     *  nothing). Unset ⇒ the agent declared no tools list. Only meaningful
+     *  with `adapter`; ignored on a `sessionRef` reuse. */
+    agentTools?: readonly string[];
+}
+/**
+ * AIP-58 §4 Run workspace — declare a file under the run workspace
+ * (`$run.workspace` / `_workflowFsRoot`) as a run artifact: hashed, sized,
+ * and copied into the host's `artifactsDir` (`<runsRoot>/<runId>/artifacts/`).
+ * Bound output (and the value passed to {@link RunWorkflowArgs.onArtifact})
+ * is the resulting {@link ArtifactEntry}.
+ *
+ * Cache-aware when the run has `cache`/`cacheKey` wired (independent of any
+ * `cacheable` flag — there is none on this step; declaring the same key/path
+ * again under the same cacheKey is always cheap to re-verify): a hit COPIES
+ * the previously-cached file forward from its original `artifactsDir` into
+ * THIS run's own — never shares a directory across runs (AIP-58 §4 "two runs
+ * MUST NEVER share a workspace") — so a step declaring an artifact from a
+ * cache-hit-replayed upstream step still works. See `run-workflow.ts`'s
+ * `case "artifact"` for the exact mechanics.
+ */
+interface ArtifactStep {
+    kind: "artifact";
+    id: string;
+    /** Artifact key — also becomes its filename under `artifactsDir` (sanitized). */
+    key: Selector<string> | string;
+    /** Path to the source file. Relative to `$run.workspace`; MUST resolve
+     *  inside it (an absolute path or a `..`-escaping relative one throws). */
+    path: Selector<string> | string;
+    contentType?: Selector<string> | string;
+}
+/**
+ * AIP-58 §4/§1 `ArtifactEntry` — one run-scoped copy of a declared output
+ * file. `path` is always `"artifacts/<sanitized key>"`, relative to the RUN
+ * WORKSPACE ROOT (`<runsRoot>/<runId>/`, the parent of `$run.workspace`
+ * itself) — never the original in-workspace location the file was read
+ * from.
+ */
+interface ArtifactEntry {
+    key: string;
+    path: string;
+    sha256: string;
+    size: number;
+    stepId: string;
+    contentType?: string;
 }
 /**
  * `kind: "gate"` — run a shell command through the host's subprocess runner
@@ -407,6 +535,13 @@ interface AgentRefResolution {
     adapter: string;
     /** Adapter option id → value merged onto the compiled step's `options`. */
     options?: Record<string, boolean | number | string>;
+    /** AGENT.md's declared `model` — the compiled step's DEFAULT when the
+     *  step itself sets none (a step-level `model:` still wins). Forwarded
+     *  through the same `harness.model` channel a step-level `model` uses. */
+    model?: string;
+    /** AGENT.md's declared `tools` (string ids only) — becomes the compiled
+     *  step's {@link AgentStep.agentTools}. */
+    tools?: readonly string[];
 }
 /**
  * The element generics on `ToolStep` are erased to `any` so heterogeneous
@@ -417,13 +552,41 @@ interface AgentRefResolution {
  * issue #21534); tightening the union to `ToolStep<unknown, …>` rejects a
  * concrete `ToolStep<MarketSearchInput, …>` on the zod `ZodType<T>` variance.
  */
-type RunStep = ToolStep<any, any, any> | TransformStep | MapStep | PipelineStep | BranchStep | LoopStep | ParallelStep | ApprovalStep | SuspendStep | GroupStep | SubworkflowStep | AgentStep | GateStep;
+type RunStep = ToolStep<any, any, any> | TransformStep | MapStep | PipelineStep | BranchStep | LoopStep | ParallelStep | ApprovalStep | SuspendStep | GroupStep | SubworkflowStep | AgentStep | GateStep | ArtifactStep;
+/** One `outputsFiles.<key>` declaration carried onto a compiled
+ *  {@link RuntimeWorkflow} — the AIP-16 file contract, amended with
+ *  `required` (AIP-58 §4). `path` MAY use the `<runId>`/`<workflowId>`/
+ *  `<isoDate>` interpolation tokens AIP-16 names (`<toolId>` is not
+ *  resolvable at the workflow level and is left literal). */
+interface OutputsFileContract {
+    path: string;
+    /** `true`: missing when the run's steps finish ⇒ `failed { code:
+     *  "missing-artifact" }` (AIP-58 §4/§10). Absent (the default) or `false`
+     *  ⇒ advisory only — a `console.warn`, the run still succeeds (mirrors
+     *  `StepRecord.hint`'s "advisory, never load-bearing" posture; matches the
+     *  AIP-58 V3 vector's own note: "with required absent or false, the same
+     *  scenario would be a warning"). */
+    required?: boolean;
+    contentType?: string;
+}
 interface RuntimeWorkflow {
     id: string;
     description?: string;
     steps: readonly RunStep[];
+    /**
+     * Cleanup steps that ALWAYS run once `steps` ends — succeeded, failed, or
+     * cancelled (they run without the abort signal). They see the same
+     * bindings (a step that never ran is simply absent). A failing `finally`
+     * step fails an otherwise-successful run; after a failed or cancelled run
+     * the original outcome wins and the cleanup error is only reported.
+     */
+    finally?: readonly RunStep[];
     /** Pick the run's final output (default: the last top-level step's output). */
     output?: Selector<unknown>;
+    /** AIP-16 `outputsFiles` (as amended by AIP-58 §4) — checked ONCE, after
+     *  every top-level step finishes successfully. See {@link OutputsFileContract}
+     *  and `run-workflow.ts`'s `checkOutputsFiles`. */
+    outputsFiles?: Readonly<Record<string, OutputsFileContract>>;
 }
 /** A human/host decision on one approval request. `who` records WHO decided
  *  ("human", "timeout", "cancelled", …); `note` is optional free text. */
@@ -445,6 +608,16 @@ interface ResumeRequest {
     stepId: string;
     on: readonly string[];
 }
+/**
+ * AIP-58 §3(a) explicit signal, recorded by the host when the step's own
+ * session calls `run.requestInput` before its turn ends. Passed to
+ * {@link RunWorkflowArgs.onInputRequired} to durably suspend the step.
+ */
+interface InputRequiredRequest {
+    stepId: string;
+    prompt: string;
+    schema?: Record<string, unknown>;
+}
 interface AgentSessionHost {
     /** Spawn a new agent session and return its id. A `sandbox` ref asks the
      *  host to run the session inside that sandbox (provider slug or inline
@@ -459,13 +632,40 @@ interface AgentSessionHost {
         options?: Record<string, boolean | number | string>;
         /** Harness pinning for this spawn (see {@link AgentStep.harness}). */
         harness?: AgentHarness;
+        /** The agent manifest's declared tools (see {@link AgentStep.agentTools}). */
+        agentTools?: readonly string[];
+        /** Run-unique key of the spawning step when it runs inside a
+         *  `map`/`pipeline` item: `stepId[<index>]`, the same key the run's step
+         *  hooks report. Absent outside a fan-out (the key is then `stepId`). */
+        stepKey?: string;
     }): Promise<string>;
+    /**
+     * The run is done with a session it spawned: end it (if still live) and
+     * archive it. Called once per spawned session — when its `map`/`pipeline`
+     * item settles, else when the run itself ends (ok or error) — never
+     * earlier, so a later step's `sessionRef` can still reuse it. The session's
+     * id stays on the step's output. Best-effort: a throw is swallowed.
+     */
+    releaseSession?(sessionId: string): Promise<void>;
     /** Send a prompt to an existing session and wait for its turn to end. */
     sendPromptAndWait(sessionId: string, prompt: string): Promise<void>;
     /** Look up a session by the step id that spawned it (for sessionRef reuse). */
     resolveByLabel(stepId: string): string | undefined;
     /** Handle an awaiting-input policy for a session. */
     onAwaitingInput?(sessionId: string, policy: AgentStep["policy"]): Promise<void>;
+    /**
+     * AIP-58 §3(a) explicit signal: consume (and clear) a pending
+     * `run.requestInput` recorded for this session — checked by
+     * {@link AgentStep} execution right after a turn ends, before the
+     * outputSchema retry loop (and again inside it, after every reprompt).
+     * `undefined` when no request is pending. Optional: a host that omits
+     * this never suspends a step on this signal — the outcome rule's other
+     * branches (missing-output / vacuous success) still apply.
+     */
+    takeInputRequest?(sessionId: string): {
+        prompt: string;
+        schema?: Record<string, unknown>;
+    } | undefined;
     /** Return the session's final assistant message text (for outputSchema validation). */
     readFinalMessage?(sessionId: string): Promise<string>;
     /** Current cumulative cost (USD) of a session, for run-level budgeting. */
@@ -485,6 +685,12 @@ interface AgentSessionHost {
 interface StepCacheEntry {
     output: unknown;
     resolvedInputHash: string;
+    /** Set only by a `kind: "artifact"` step (see {@link ArtifactStep}): the
+     *  absolute `artifactsDir` this entry's file was copied into when first
+     *  cached. A hit in a LATER run (a different `artifactsDir`, since AIP-58
+     *  §4 forbids two runs sharing a workspace) copies the file forward from
+     *  here into the new run's own `artifactsDir` instead of re-declaring it. */
+    artifactsDirAtCache?: string;
 }
 /** Opt-in journal for cacheable steps. Host-injected; file-backed in the runtime. */
 interface StepCache {
@@ -493,6 +699,31 @@ interface StepCache {
     /** Write/overwrite a step's journal entry. */
     set(stepCacheKey: string, entry: StepCacheEntry): Promise<void>;
 }
+/** Extra context passed to `onStepStart`/`onStepComplete`. */
+interface StepHookInfo {
+    /** The step's output was replayed from the {@link StepCache} journal —
+     *  it was not executed (no spawn, no tool dispatch) this run. */
+    cached?: boolean;
+}
+/** Why `onStepSkipped` fired. */
+interface StepSkippedInfo {
+    /** `"branch-not-taken"`: the step sits in an untaken `branch` arm.
+     *  `"circuit-open"`: a `map`/`pipeline` item never started because the
+     *  fan-out's spawn circuit breaker opened
+     *  ({@link MapStep.maxConsecutiveSpawnFailures}). */
+    reason: "branch-not-taken" | "circuit-open";
+    /** Id of the authored step whose decision skipped the step — the `branch`
+     *  step, or (circuit-open) the `map`/`pipeline` step. */
+    branchId: string;
+    /** `"circuit-open"` only: the first error of the spawn-failure streak
+     *  that tripped the breaker. */
+    message?: string;
+}
+/** What `onStepFailed` reports. */
+interface StepFailedInfo {
+    /** `err.message` if the throw was an `Error`, else `String(err)`. */
+    error: string;
+}
 interface RunWorkflowArgs {
     workflow: RuntimeWorkflow;
     input?: unknown;
@@ -503,12 +734,41 @@ interface RunWorkflowArgs {
     approve?: (req: ApprovalRequest) => boolean | ApprovalDecision | Promise<boolean | ApprovalDecision>;
     /** Supply a {@link SuspendStep}'s resume payload. Default: throw + suspend. */
     resume?: (req: ResumeRequest) => unknown | Promise<unknown>;
+    /**
+     * AIP-58 §3(a)/§5 outcome rule: suspend an {@link AgentStep} that
+     * signalled `run.requestInput` (see
+     * {@link AgentSessionHost.takeInputRequest}), resolving with the resume
+     * payload once an external event supplies one. The runtime sends that
+     * payload (JSON) as the step's next prompt to the SAME session and
+     * re-applies the outcome rule — the step may suspend again, fail
+     * `missing-output`, or succeed. Default (undefined) ⇒
+     * {@link AgentInputRequiredError} throws instead, the same
+     * no-hook-supplied shape {@link WorkflowSuspendedError} uses for
+     * {@link SuspendStep}.
+     */
+    onInputRequired?: (req: InputRequiredRequest) => unknown | Promise<unknown>;
     /** Host-injected agent session runtime. Undefined ⇒ {@link AgentStep} throws. */
     agents?: AgentSessionHost;
     /** Working directory for spawned agent sessions. */
     cwd?: string;
     /** Workspace slug for spawned agent sessions. */
     workspaceSlug?: string;
+    /** AIP-58 §4 Run workspace — absolute path to this run's own scratch
+     *  directory (AIP-16's `_workflowFsRoot`), exposed to steps as
+     *  `$run.workspace` / `{{run.workspace}}`. Undefined ⇒ the `run` binding
+     *  and `kind: "artifact"` steps are unavailable. */
+    workspace?: string;
+    /** AIP-58 §4 — absolute path to this run's `artifacts/` directory. Required
+     *  alongside `workspace` for a `kind: "artifact"` step (or a declared
+     *  `RuntimeWorkflow.outputsFiles`) to run. */
+    artifactsDir?: string;
+    /** This run's id — used only to interpolate the `<runId>` token in a
+     *  declared `outputsFiles.<key>.path` (AIP-16). Purely informational
+     *  otherwise. */
+    runId?: string;
+    /** Called once per {@link ArtifactEntry} recorded — by a `kind: "artifact"`
+     *  step, or by the end-of-run `outputsFiles` check — cache hit or fresh. */
+    onArtifact?: (entry: ArtifactEntry) => void;
     /** Run-level cost ceiling (USD). Once the summed cost of spawned sessions
      *  reaches this, the next AgentStep spawn fails with `budget_exceeded`. */
     maxTotalCostUsd?: number;
@@ -517,10 +777,24 @@ interface RunWorkflowArgs {
     /** Namespacing label for this run's cache lookups (the workflow_start cacheKey).
      *  Both `cache` and `cacheKey` must be set for any caching to happen. */
     cacheKey?: string;
-    /** Called when a step begins execution (before spawn/prompt). */
-    onStepStart?: (stepId: string) => void;
-    /** Called when a step completes execution, with its output. */
-    onStepComplete?: (stepId: string, output: unknown) => void;
+    /** Called when a step begins execution (before spawn/prompt). A cacheable
+     *  step replayed from the journal still fires this, with `info.cached`. */
+    onStepStart?: (stepId: string, info?: StepHookInfo) => void;
+    /** Called when a step completes execution, with its output — `info.cached`
+     *  when the output was replayed from the journal instead of executed. */
+    onStepComplete?: (stepId: string, output: unknown, info?: StepHookInfo) => void;
+    /** Called for every step in a `branch` arm that was NOT taken, once the
+     *  branch decides — the step will not run this time. Only statically-known
+     *  steps are reported (a `map`/`pipeline`/`subworkflow` step under the arm
+     *  reports its own id, not its body's); a step id that also sits in the
+     *  taken path is never reported. */
+    onStepSkipped?: (stepId: string, info: StepSkippedInfo) => void;
+    /** Called when a step inside a tolerant (`onError: "collect"`) `map`/
+     *  `pipeline` item throws — the item is recorded as rejected and the run
+     *  goes on, so this is the only signal the failing step gets. `stepId` is
+     *  the innermost step that threw, indexed like `onStepStart`'s. A throw
+     *  that fails the run is NOT reported here (the run's own failure is). */
+    onStepFailed?: (stepId: string, info: StepFailedInfo) => void;
     /** Host-injectable subprocess runner for `kind: "gate"` steps. Undefined ⇒
      *  the runtime's own `node:child_process`-backed default. */
     runGateCommand?: GateCommandRunner;
@@ -548,6 +822,59 @@ declare class WorkflowSuspendedError extends Error {
     readonly on: readonly string[];
     constructor(stepId: string, on: readonly string[]);
 }
+/**
+ * AIP-58 §3(a) — thrown when an {@link AgentStep}'s session signals
+ * `run.requestInput` but no host `onInputRequired` hook is provided (the
+ * same "no resume hook supplied" shape {@link WorkflowSuspendedError} uses
+ * for {@link SuspendStep}). A host that wires `onInputRequired` never sees
+ * this thrown — it durably suspends the step instead.
+ */
+declare class AgentInputRequiredError extends Error {
+    readonly stepId: string;
+    readonly prompt: string;
+    readonly schema?: Record<string, unknown> | undefined;
+    constructor(stepId: string, prompt: string, schema?: Record<string, unknown> | undefined);
+}
+/**
+ * AIP-58 §3 Outcome rule — thrown when an {@link AgentStep} declares an
+ * `outputSchema` and its turn ends (after exhausting retries) without ever
+ * producing output that validates against it, and no explicit
+ * input-required signal (§3(a)/(b)) was observed either. `hint` is set when
+ * the final message matches the "trailing question mark" heuristic — it is
+ * ONLY a triage aid; it never changes the outcome (still `missing-output`).
+ */
+declare class StepOutcomeError extends Error {
+    readonly stepId: string;
+    readonly code: "missing-output";
+    readonly hint?: "possible-input-request" | undefined;
+    constructor(stepId: string, code: "missing-output", message: string, hint?: "possible-input-request" | undefined);
+}
+/**
+ * AIP-58 §4/§10 — thrown when a declared `outputsFiles.<key>` (`required`
+ * absent or `true`) does not exist under the run workspace once every
+ * top-level step has finished. `stepId` is the last top-level step that ran
+ * (the manifest names no step for a workflow-level contract, so the last one
+ * to finish is the best available attribution).
+ */
+declare class MissingArtifactError extends Error {
+    readonly key: string;
+    readonly stepId: string | undefined;
+    readonly code: "missing-artifact";
+    constructor(key: string, stepId: string | undefined);
+}
+/**
+ * Thrown when an {@link AgentStep}'s session could not be spawned at all
+ * (`AgentSessionHost.spawn` rejected) — distinct from a session that spawned
+ * and then failed its turn. A tolerant fan-out counts these toward its spawn
+ * circuit breaker ({@link MapStep.maxConsecutiveSpawnFailures}): a spawn that
+ * fails for one item usually fails for every item (missing cwd, adapter
+ * gone, process limits), so burning through the rest is pure noise.
+ */
+declare class AgentSpawnError extends Error {
+    readonly stepId: string;
+    readonly cause: unknown;
+    constructor(stepId: string, cause: unknown);
+}
 declare function runWorkflow(args: RunWorkflowArgs): Promise<WorkflowRunResult>;
 
 /**
@@ -561,6 +888,10 @@ declare function runWorkflow(args: RunWorkflowArgs): Promise<WorkflowRunResult>;
  *
  *   - data refs:   `$input` · `$input.a.b` · `$steps.<id>` · `$steps.<id>.a`
  *                  · `$item` · `$item.a` · `$index`   (`$$` escapes a literal `$`)
+ *   - prompts:     the above refs PLUS mustache-style `{{name}}` /
+ *                  `{{a.b}}` interpolation, `{{#name}}…{{/name}}` conditional
+ *                  and `{{^name}}…{{/name}}` inverted sections (see
+ *                  {@link interpolateTemplate})
  *   - `step.inputs`: a JSON object whose leaf strings may be refs (resolved
  *                    recursively); non-`$` strings are literals
  *   - `map.over`:    a ref to an array
@@ -570,9 +901,12 @@ declare function runWorkflow(args: RunWorkflowArgs): Promise<WorkflowRunResult>;
  * Scope: the **linear / structured subset** of AIP-15 — steps run in document
  * order; `map`/`loop`/`parallel` nest their child step lists. Non-linear `next`
  * gotos are rejected with a clear diagnostic. `kind:"branch"` compiles in its
- * **forward-only** form: every `branches[].next`/`default` must name a later
- * sibling in the SAME step list (not backward, not into a nested map/loop/
- * parallel body) — see `compileBranchChain` below. Compiling a full goto graph
+ * **forward-only** form: every `branches[].next`/`default`/`join` must name a
+ * later sibling in the SAME step list (not backward, not into a nested map/
+ * loop/parallel body). Arms are EXCLUSIVE by default — exactly one arm body
+ * runs, then execution continues at the join (see `compileExclusiveBranch`);
+ * `fallthrough: true` opts into the legacy "target + everything after it"
+ * semantics (see `compileBranchChain`). Compiling a full goto graph
  * (backward jumps, cross-scope targets) is a separable follow-up; hand-author
  * a `loop` step for retry-style control flow instead.
  */
@@ -610,6 +944,19 @@ declare function resolveRefPrefixed(value: string, b: Bindings): {
     resolved: unknown;
     rest: string;
 } | undefined;
+/**
+ * Interpolate mustache-style `{{…}}` templates against the run bindings.
+ *
+ *   - `{{name}}` / `{{a.b}}` → the resolved value stringified; a MISSING
+ *     value leaves the placeholder as-is (never crashes, never renders
+ *     "undefined" into an agent prompt).
+ *   - `{{#name}}…{{/name}}` renders the inner text only when `name` is
+ *     truthy; `{{^name}}…{{/name}}` only when falsy. When a section tag
+ *     sits alone on its line (only whitespace around it), the whole line
+ *     collapses too — so a dropped section doesn't leave blank lines behind.
+ *   - Sections nest: inner text is interpolated recursively.
+ */
+declare function interpolateTemplate(template: string, b: Bindings): string;
 /** Recursively resolve a value node: refs in strings, into arrays/objects. */
 declare function resolveValue(node: unknown, b: Bindings): unknown;
 /** Evaluate a `while`/`when` predicate string against the bindings. */
@@ -643,6 +990,90 @@ declare function compileWorkflow(handle: WorkflowHandle, opts: CompileWorkflowOp
  */
 declare function compileWorkflowManifest(source: string, opts: CompileWorkflowOptions): RuntimeWorkflow;
 
+/**
+ * AIP-58 §3 Outcome rule — "invalid or missing required input is checked
+ * before any step runs". AIP-16 declares a workflow's `inputs` block as
+ * JSON Schema, but most existing WORKFLOW.md authors write a shorthand flat
+ * map instead (`inputs: { url: { type, description, default } }` — see
+ * `youtube-transcriber`'s `transcribe/WORKFLOW.md`). This module normalizes
+ * that shorthand into real JSON Schema, then validates a run's input
+ * against it with the same ajv machinery `@agentproto/tool` already uses for
+ * TOOL contracts (`define-tool.ts`'s `validateJsonSchema`).
+ */
+/**
+ * Normalize a WORKFLOW.md `inputs` field to a JSON Schema object.
+ *
+ * Already-canonical JSON Schema (`{ type: "object", properties, required?
+ * }`) passes through unchanged — its own `required[]`, if any, is honored
+ * as-is (this is the shape AIP-58's V1 vector authors directly).
+ *
+ * The shorthand flat map (`{ <name>: { type, description?, default?,
+ * required? } }`) is lifted: each key becomes a `properties` entry (minus
+ * its shorthand-only `required` marker); a property gets added to the
+ * schema's `required[]` ONLY when its shorthand spec sets `required: true`
+ * AND declares no `default` — a `default` always makes a field optional to
+ * omit, regardless of `required`. A shorthand property with no `required`
+ * marker at all stays optional, so normalizing an existing manifest that
+ * never used the marker (e.g. `youtube-transcriber`'s `transcribe/
+ * WORKFLOW.md`) never newly fails validation for it.
+ */
+declare function normalizeWorkflowInputsSchema(inputs: unknown): Record<string, unknown>;
+type WorkflowInputValidation = {
+    valid: true;
+    schema: Record<string, unknown>;
+} | {
+    valid: false;
+    schema: Record<string, unknown>;
+    /** AIP-58 §10 error code — this validator only ever produces one. */
+    code: "invalid-input";
+    /** Missing/invalid field names (deduped), for a caller that wants to
+     *  point at exactly what's wrong without re-parsing `message`. */
+    fields: readonly string[];
+    /** Human-readable message naming the missing/invalid fields. */
+    message: string;
+};
+/**
+ * AIP-58 §9 `run.requestInput`/`run.resume`: `true` when `schema` is a
+ * usable JSON Schema (ajv can compile it) — a plain object is necessary but
+ * not sufficient (e.g. `{ type: "not-a-type" }` compiles-fails). Used to
+ * reject a malformed `schema` argument before it's ever recorded as a
+ * step's `StepRecord.suspend.schema`.
+ */
+declare function isCompilableJsonSchema(schema: unknown): schema is Record<string, unknown>;
+/** One structural (zod-`ZodIssue`-shaped) validation failure — the common
+ *  currency between ajv's `ErrorObject[]` and zod's `ZodError.issues`, see
+ *  {@link OutputSchemaLikeIssue}. */
+interface SchemaValidationIssue {
+    path: readonly (string | number)[];
+    message: string;
+}
+/**
+ * Generic JSON Schema validation, used both by AIP-58 §3/§9 (validate a
+ * `run.resume` payload against the suspended step's `StepRecord.suspend
+ * .schema` BEFORE the resume transition happens — an invalid payload MUST
+ * leave the run suspended, never transition it) and by `compileAgentStep`
+ * (adapt a WORKFLOW.md-authored JSON Schema `outputSchema` into the
+ * {@link OutputSchemaLike} shape `execAgentStep` consumes). `issues` mirrors
+ * zod's `ZodError.issues` shape so both call sites format errors the same
+ * way regardless of which schema language declared the contract.
+ */
+declare function validateAgainstJsonSchema(schema: Record<string, unknown>, value: unknown): {
+    valid: true;
+} | {
+    valid: false;
+    message: string;
+    issues: readonly SchemaValidationIssue[];
+};
+/**
+ * Validate a run's `input` against a WORKFLOW.md's declared `inputs`
+ * (shorthand or canonical JSON Schema — see
+ * {@link normalizeWorkflowInputsSchema}). The caller is responsible for
+ * calling this BEFORE dispatching any step and BEFORE spawning any session
+ * on an invalid result — this function only judges the input, it doesn't
+ * gate execution itself.
+ */
+declare function validateWorkflowInput(inputsField: unknown, input: unknown): WorkflowInputValidation;
+
 /**
  * Shared `AgentStep` construction — the one place that applies AgentStep's
  * defaults (`policy` → `{ awaiting: "fail" }`, a literal `prompt` wrapped as
@@ -657,6 +1088,8 @@ interface AgentStepFields {
      *  steps resolve `$steps.*` refs into one before calling this). */
     prompt: string | Selector<string>;
     adapter?: string;
+    /** See {@link AgentStep.cwd}. */
+    cwd?: Selector<string>;
     model?: Selector<string> | string;
     sessionRef?: string;
     sandbox?: AgentSandboxRef;
@@ -666,6 +1099,7 @@ interface AgentStepFields {
     maxRetries?: number;
     options?: Record<string, boolean | number | string>;
     harness?: AgentHarness;
+    agentTools?: readonly string[];
 }
 /** Build a runtime {@link AgentStep} from field values, applying the same
  *  defaults everywhere: `policy` defaults to `{ awaiting: "fail" }`. */
@@ -723,4 +1157,4 @@ declare class NodeFsPort implements FsPort {
     lock(): Promise<FsLockHandle>;
 }
 
-export { type AgentHarness, type AgentRefResolution, type AgentSandboxRef, type AgentSessionHost, type AgentStep, type AgentStepFields, type ApprovalDecision, type ApprovalRequest, type ApprovalStep, type Bindings, type BranchStep, type CompileWorkflowOptions, type FanOutOutcome, type GateCommandResult, type GateCommandRunner, type GateReportEvent, type GateStep, type GroupStep, type HarnessKnowledgeSelector, type KnowledgeAppliedRecord, type LoopStep, type MapStep, type MaterializedKnowledge, NodeFsPort, type ParallelStep, type PipelineStep, type ResumeRequest, type RunStep, type RunWorkflowArgs, type RuntimeWorkflow, type Selector, type StepCache, type StepCacheEntry, type SubworkflowStep, type SuspendStep, type TolerantFanOutResult, type ToolStep, type TransformStep, WorkflowCompileError, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, materializeKnowledge, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow };
+export { type AgentHarness, AgentInputRequiredError, type AgentRefResolution, type AgentSandboxRef, type AgentSessionHost, AgentSpawnError, type AgentStep, type AgentStepFields, type ApprovalDecision, type ApprovalRequest, type ApprovalStep, type ArtifactEntry, type ArtifactStep, type Bindings, type BranchStep, type CompileWorkflowOptions, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, type FanOutOutcome, type GateCommandResult, type GateCommandRunner, type GateReportEvent, type GateStep, type GroupStep, type HarnessKnowledgeSelector, type InputRequiredRequest, type KnowledgeAppliedRecord, type LoopStep, type MapStep, type MaterializedKnowledge, MissingArtifactError, NodeFsPort, type OutputSchemaLike, type OutputsFileContract, type ParallelStep, type PipelineStep, type ResumeRequest, type RunStep, type RunWorkflowArgs, type RuntimeWorkflow, type SchemaValidationIssue, type Selector, type StepCache, type StepCacheEntry, type StepFailedInfo, type StepHookInfo, StepOutcomeError, type StepSkippedInfo, type SubworkflowStep, type SuspendStep, type TolerantFanOutResult, type ToolStep, type TransformStep, WorkflowCompileError, type WorkflowInputValidation, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };