@bastani/atomic 0.9.11-alpha.4 → 0.9.11-alpha.6

package/dist/builtin/workflows/src/runs/foreground/stage-runner-types.ts

@@ -45,6 +45,12 @@ export interface StageSessionRuntime {
   sealWorkflowStageGeneration?(): void;
   closeWorkflowStageGeneration?(): Promise<void>;
   transferWorkflowStageDeliveriesTo?(target: object): void;
+  /** True when this runtime implements a native queued-message pause gate. */
+  readonly queuedMessagesPaused?: boolean;
+  /** Optional native optimization that synchronously holds queued work. */
+  pauseQueuedMessages?(): void;
+  /** Optional native release; calls `beforeRelease` at the final synchronous boundary. */
+  resumeQueuedMessages?(beforeRelease?: () => void): boolean | Promise<boolean>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
   subscribe(listener: (event: StageSessionEvent) => void): () => void;
@@ -112,6 +118,8 @@ export interface StageRunnerOpts {
   stageOptions?: StageOptions;
   /** Run ID of the containing workflow execution — forwarded to session adapter metadata. */
   runId: string;
+  /** Runtime-owned home group shared by this top-level workflow invocation. */
+  workflowIntercomGroup?: string;
   /** AbortSignal from the executor's own AbortController — forwarded to session adapter metadata. */
   signal?: AbortSignal;
   /** Optional model catalog used for fallback validation/resolution. */
@@ -159,8 +167,12 @@ export interface InternalStageContext extends StageContext {
   __modelFallbackMeta(): StageModelFallbackMeta;
   /** Internal: register a controlled-pause request. */
   __requestPause(): Promise<void>;
-  /** Internal: complete a pending controlled pause. */
-  __resume(message?: string): Promise<void>;
+  /** Internal: complete a pending controlled pause and report its released raw work. */
+  __resume(
+    message?: string,
+    beforeResolve?: (result: import("./stage-runner-pause.js").StageSessionPauseResumeResult) => void,
+    beforeRelease?: () => void,
+  ): Promise<import("./stage-runner-pause.js").StageSessionPauseResumeResult>;
   /** Internal: true while a controlled pause is in flight. */
   __isPaused(): boolean;
   /** Internal: true once a schema-backed prompt captured its final structured output. */

package/dist/builtin/workflows/src/runs/shared/model-fallback-candidates.ts

@@ -1,4 +1,3 @@
-import { getModelDefaultContextWindow, getSupportedContextWindows, parseContextWindowValue } from "@bastani/atomic";
 import type { CreateAgentSessionOptions } from "@bastani/atomic";
 import type {
   WorkflowModelCatalogPort,
@@ -11,135 +10,20 @@ export interface WorkflowResolvedModelCandidate {
   readonly id: string;
   readonly value: WorkflowModelValue;
   readonly reasoningLevel?: WorkflowThinkingLevel;
-  /**
-   * Resolved context-window token budget for this candidate's session, parsed
-   * from a parenthesized authoring token in the model string (e.g.
-   * `github-copilot/claude-opus-4.8 (1m):xhigh` or `...:xhigh (1m)`). Resolved
-   * against the candidate model's advertised windows: a `(long)` marker or a
-   * request above the model's default selects the long tier (exact match wins,
-   * otherwise the smallest window >= the request, rounding UP so `(1m)`/`(1.1m)`
-   * select a long tier even when it sits slightly above the marker size). Left
-   * `undefined` when the model exposes no long tier, so the session keeps the
-   * model's default (short) window.
-   */
-  readonly contextWindow?: number;
 }
 
 function makeCandidate(
   id: string,
   value: WorkflowModelValue,
   level: WorkflowThinkingLevel | undefined,
-  contextWindow?: number,
 ): WorkflowResolvedModelCandidate {
   return {
     id,
     value,
     ...(level !== undefined ? { reasoningLevel: level } : {}),
-    ...(contextWindow !== undefined ? { contextWindow } : {}),
   };
 }
 
-/**
- * Result of extracting a trailing parenthesized context-window authoring token.
- * - `requestedContextWindow`: a numeric size token (e.g. `1m`, `1.1m`, `272k`).
- * - `requestedLongContext`: the generic `(long)` marker, which selects the
- *   model's advertised long tier regardless of its exact size.
- */
-interface ExtractedContextWindowToken {
-  readonly baseModel: string;
-  readonly requestedContextWindow?: number;
-  readonly requestedLongContext?: boolean;
-}
-
-/**
- * Extract a trailing parenthesized context-window authoring token, e.g. the
- * `(1m)` in `github-copilot/claude-opus-4.8 (1m)`. Mirrors GitHub Copilot's
- * model-name convention (`Claude Opus 4.8 (1M context)`) and intentionally
- * lives in the model-name portion — *not* a `:` suffix — so it never collides
- * with the `:off|minimal|low|medium|high|xhigh` reasoning-level suffix.
- *
- * Accepted token forms, all selecting the model's long tier when one exists:
- *   - `(long)` — a generic, size-agnostic long-context marker (case-insensitive);
- *   - a rounded size matching the model's long tier, e.g. `(1m)` for a ~1M tier
- *     (claude-opus-4.8) or `(1.1m)` for a ~1.05M tier (gpt-5.5), resolved by
- *     rounding UP to the long tier (see `resolveRequestedContextWindow`);
- *   - any exact/partial size (e.g. `(272k)` keeps the short tier).
- *
- * Parsed with plain string scanning rather than a regular expression so that
- * adversarial model strings (e.g. `(` followed by long whitespace runs) cannot
- * trigger super-linear backtracking (CodeQL js/polynomial-redos).
- */
-function extractContextWindowToken(model: string): ExtractedContextWindowToken {
-  const trimmedEnd = model.trimEnd();
-  if (!trimmedEnd.endsWith(")")) return { baseModel: model };
-  const open = trimmedEnd.lastIndexOf("(");
-  // Require at least one character before the `(` so a bare `(1m)` is not a model.
-  if (open <= 0) return { baseModel: model };
-  const inner = trimmedEnd.slice(open + 1, -1);
-  // The token must be a single flat `(...)` group with no nested parentheses.
-  if (inner.includes("(") || inner.includes(")")) return { baseModel: model };
-  const token = inner.trim();
-  const baseModel = trimmedEnd.slice(0, open).trim();
-  if (token.length === 0 || baseModel.length === 0) return { baseModel: model };
-  // `(long)` is a generic long-context marker: select the model's advertised
-  // long tier regardless of its exact size, so the same token works across
-  // models with different long tiers (e.g. claude-opus-4.8 1m vs gpt-5.5 1.1m).
-  if (token.toLowerCase() === "long") return { baseModel, requestedLongContext: true };
-  const parsed = parseContextWindowValue(token);
-  // A parenthesized token that does not parse as a context size (e.g. an
-  // accidental `(preview)`) is left attached to the model id so the normal
-  // "not available" lookup surfaces the typo instead of being silently dropped.
-  if (parsed.value === undefined) return { baseModel: model };
-  return { baseModel, requestedContextWindow: parsed.value };
-}
-
-/**
- * Resolve a requested context-window budget against a candidate model's
- * advertised windows. A request at or below the model's default window keeps
- * the default (no upgrade). A request above the default selects the long tier:
- * the exact value when supported, otherwise the smallest advertised window that
- * meets the request, rounding UP so a `(1m)` token lands on a long tier even
- * when it sits slightly above 1m (e.g. gpt-5.5's 1.05m full-context tier). When
- * no advertised window meets the request, the largest window is chosen so the
- * token always selects the long tier when one exists. Returns `undefined` when
- * the resolution lands back on the model's default (no upgrade) or the model
- * value is a plain string (not resolved against the live catalog).
- */
-function resolveRequestedContextWindow(
-  value: WorkflowModelValue,
-  requested: number,
-): number | undefined {
-  if (typeof value === "string") return undefined;
-  const supported = getSupportedContextWindows(value);
-  if (supported.length === 0) return undefined;
-  const defaultContextWindow = getModelDefaultContextWindow(value);
-  // A request at or below the default window keeps the default (no upgrade).
-  if (requested <= defaultContextWindow) return undefined;
-  if (supported.includes(requested)) return requested;
-  // Round UP to the smallest advertised window that meets the request; when no
-  // window meets it, fall back to the largest window (the long tier) so the
-  // token still selects the long tier. `supported` is sorted ascending.
-  const atOrAbove = supported.filter((window) => window >= requested);
-  const longTier = atOrAbove.length > 0 ? Math.min(...atOrAbove) : supported[supported.length - 1]!;
-  return longTier === defaultContextWindow ? undefined : longTier;
-}
-
-/**
- * Resolve the generic `(long)` long-context marker against a candidate model's
- * advertised windows: select the largest advertised window that exceeds the
- * model's default (the long tier). Returns `undefined` for single-window models
- * or plain string values, so the session keeps the model's default window.
- */
-function resolveLongContextWindow(value: WorkflowModelValue): number | undefined {
-  if (typeof value === "string") return undefined;
-  const supported = getSupportedContextWindows(value);
-  if (supported.length <= 1) return undefined;
-  const defaultContextWindow = getModelDefaultContextWindow(value);
-  // `supported` is sorted ascending; the largest window is the long tier.
-  const longTier = supported[supported.length - 1]!;
-  return longTier > defaultContextWindow ? longTier : undefined;
-}
-
 const WORKFLOW_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const satisfies readonly WorkflowThinkingLevel[];
 const WORKFLOW_THINKING_LEVEL_SET: ReadonlySet<string> = new Set(WORKFLOW_THINKING_LEVELS);
 
@@ -154,7 +38,7 @@ export function splitReasoningSuffix(model: string): { readonly baseModel: strin
 }
 
 function candidateKey(candidate: WorkflowResolvedModelCandidate): string {
-  return `${candidate.id}::${candidate.reasoningLevel ?? ""}::${candidate.contextWindow ?? ""}`;
+  return `${candidate.id}::${candidate.reasoningLevel ?? ""}`;
 }
 
 interface ModelResolutionFailure {
@@ -219,34 +103,10 @@ function resolveStringModel(
 ): WorkflowResolvedModelCandidate | ModelResolutionFailure {
   const input = rawInput.trim();
   if (!input) return { input: rawInput, reason: "empty model id" };
-  // Extract the trailing context-window token, split the reasoning suffix, then
-  // extract the token once more. This handles both `model (1m):level` (token
-  // before the suffix) and `model:level (1m)` (token after the suffix) without
-  // letting the token collide with the `:off|minimal|low|medium|high|xhigh`
-  // reasoning suffix.
-  const tokenFirst = extractContextWindowToken(input);
-  const { baseModel: afterReasoning, level } = splitReasoningSuffix(tokenFirst.baseModel);
-  let baseModel = afterReasoning;
-  let requestedContextWindow = tokenFirst.requestedContextWindow;
-  let requestedLongContext = tokenFirst.requestedLongContext;
-  if (requestedContextWindow === undefined && requestedLongContext === undefined) {
-    const retry = extractContextWindowToken(afterReasoning);
-    baseModel = retry.baseModel;
-    requestedContextWindow = retry.requestedContextWindow;
-    requestedLongContext = retry.requestedLongContext;
-  }
+  const { baseModel, level } = splitReasoningSuffix(input);
 
   const candidate = (id: string, value: WorkflowModelValue): WorkflowResolvedModelCandidate =>
-    makeCandidate(
-      id,
-      value,
-      level,
-      requestedLongContext
-        ? resolveLongContextWindow(value)
-        : requestedContextWindow === undefined
-          ? undefined
-          : resolveRequestedContextWindow(value, requestedContextWindow),
-    );
+    makeCandidate(id, value, level);
 
   if (availableModels === undefined) {
     return candidate(baseModel, baseModel);

package/dist/builtin/workflows/src/sdk-surface.ts

@@ -34,7 +34,7 @@ export type { StageNode } from "./engine/graph-inference.js";
 export { setupGitWorktree } from "./runs/shared/worktree.js";
 export type { GitWorktreeSetupOptions, GitWorktreeSetupResult } from "./runs/shared/worktree.js";
 export { createStore, store } from "./shared/store.js";
-export type { RunStatus, StageStatus, ToolEvent, StageSnapshot, RunSnapshot, StoreSnapshot, WorkflowNotice, NoticeLevel, WorkflowOverlayAdapter, PromptKind, CustomPromptIdentitySource, PendingPrompt } from "./shared/store-types.js";
+export type { RunStatus, StageStatus, ToolEvent, ToolNodeSnapshot, StageSnapshot, RunSnapshot, StoreSnapshot, WorkflowNotice, NoticeLevel, WorkflowOverlayAdapter, PromptKind, CustomPromptIdentitySource, PendingPrompt } from "./shared/store-types.js";
 
 // Phase D — cancellation registry
 export { createCancellationRegistry, cancellationRegistry } from "./runs/background/cancellation-registry.js";

package/dist/builtin/workflows/src/shared/authoring-contract-stage.d.ts

@@ -118,17 +118,6 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
     /** Optional structured final-answer schema. When set, the stage receives a schema-specific final-answer tool. */
     readonly schema?: TSchemaDef;
     readonly model?: WorkflowModelValue;
-    /**
-     * Context-window token budget for the stage session. May also be expressed
-     * per-model via a parenthesized token in a `model`/`fallbackModels` entry
-     * (e.g. `github-copilot/claude-opus-4.8 (1m):xhigh`), which is preferred when
-     * only specific fallbacks should use a larger window. Non-strict by default:
-     * an unsupported value keeps the model's default window (see
-     * `contextWindowStrict`).
-     */
-    readonly contextWindow?: number;
-    /** Treat an unsupported `contextWindow` as an error instead of falling back to the model default. */
-    readonly contextWindowStrict?: boolean;
     readonly mcp?: StageMcpOptions;
     readonly tools?: readonly string[];
     readonly noTools?: "all" | "builtin";
@@ -209,6 +198,12 @@ export interface StageSessionRuntime {
     sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
     steer(text: string): Promise<void>;
     followUp(text: string): Promise<void>;
+    /** True when this runtime implements a native queued-message pause gate. */
+    readonly queuedMessagesPaused?: boolean;
+    /** Optional native optimization that synchronously holds queued steer/follow-up work. */
+    pauseQueuedMessages?(): void;
+    /** Optional native release; calls `beforeRelease` at final admission. */
+    resumeQueuedMessages?(beforeRelease?: () => void): boolean | Promise<boolean>;
     /**
      * Must emit `agent_start` when a submitted user-message turn takes ownership and
      * `agent_end` when that owned turn terminates. Registration may replay state

package/dist/builtin/workflows/src/shared/authoring-contract-stage.ts

@@ -155,17 +155,6 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
   /** Optional structured final-answer schema. When set, the stage receives a schema-specific final-answer tool. */
   readonly schema?: TSchemaDef;
   readonly model?: WorkflowModelValue;
-  /**
-   * Context-window token budget for the stage session. May also be expressed
-   * per-model via a parenthesized token in a `model`/`fallbackModels` entry
-   * (e.g. `github-copilot/claude-opus-4.8 (1m):xhigh`), which is preferred when
-   * only specific fallbacks should use a larger window. Non-strict by default:
-   * an unsupported value keeps the model's default window (see
-   * `contextWindowStrict`).
-   */
-  readonly contextWindow?: number;
-  /** Treat an unsupported `contextWindow` as an error instead of falling back to the model default. */
-  readonly contextWindowStrict?: boolean;
   readonly mcp?: StageMcpOptions;
   readonly tools?: readonly string[];
   readonly noTools?: "all" | "builtin";
@@ -253,6 +242,12 @@ export interface StageSessionRuntime {
   sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
+  /** True when this runtime implements a native queued-message pause gate. */
+  readonly queuedMessagesPaused?: boolean;
+  /** Optional native optimization that synchronously holds queued steer/follow-up work. */
+  pauseQueuedMessages?(): void;
+  /** Optional native release; calls `beforeRelease` at final admission. */
+  resumeQueuedMessages?(beforeRelease?: () => void): boolean | Promise<boolean>;
   /**
    * Must emit `agent_start` when a submitted user-message turn takes ownership and
    * `agent_end` when that owned turn terminates. Registration may replay state

package/dist/builtin/workflows/src/shared/authoring-contract-ui.d.ts

@@ -67,19 +67,48 @@ export interface WorkflowRunContext<TInputs extends WorkflowInputValues = Workfl
      */
     tool: WorkflowToolPrimitive;
 }
-/**
- * `ctx.tool` primitive signature. Runs an async function and caches the result.
- */
-export interface WorkflowToolPrimitive {
-    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options?: WorkflowToolOptions): Promise<TValue>;
+/** Serializable process details copied from an exhausted `ctx.tool` callback error. */
+export interface WorkflowToolError extends WorkflowSerializableObject {
+    readonly name: string;
+    readonly message: string;
+    readonly exitCode?: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+}
+export interface WorkflowToolSuccess<TValue extends WorkflowSerializableValue> extends WorkflowSerializableObject {
+    readonly ok: true;
+    readonly value: TValue;
+    readonly attempts: number;
+    readonly cached: boolean;
 }
-/** Options for `ctx.tool`. */
+export interface WorkflowToolFailure extends WorkflowSerializableObject {
+    readonly ok: false;
+    readonly error: WorkflowToolError;
+    readonly attempts: number;
+    readonly cached: boolean;
+}
+/** Typed result returned when `failureMode: "return"` is selected. */
+export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> = WorkflowToolSuccess<TValue> | WorkflowToolFailure;
+/** Options for `ctx.tool`. Throwing after exhausted retries remains the default. */
 export interface WorkflowToolOptions {
+    readonly failureMode?: "throw" | "return";
     readonly retriesAllowed?: boolean;
     readonly maxAttempts?: number;
     readonly intervalMs?: number;
     readonly backoffRate?: number;
 }
+export type WorkflowToolReturnOptions = WorkflowToolOptions & {
+    readonly failureMode: "return";
+};
+export type WorkflowToolThrowOptions = WorkflowToolOptions & {
+    readonly failureMode?: "throw";
+};
+/** `ctx.tool` runs an async function and durably caches its serializable result. */
+export interface WorkflowToolPrimitive {
+    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options: WorkflowToolReturnOptions): Promise<WorkflowToolOutcome<TValue>>;
+    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options?: WorkflowToolThrowOptions): Promise<TValue>;
+    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options?: WorkflowToolOptions): Promise<TValue | WorkflowToolOutcome<TValue>>;
+}
 export type WorkflowRunFn<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues, TDefinitionBrand extends object = {}> = (ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>) => Promise<TOutputs> | TOutputs;
 export interface WorkflowRuntimeConfig {
     readonly maxDepth: number;
@@ -210,15 +239,37 @@ export interface StageSnapshot extends WorkflowSerializableObject {
     readonly result?: WorkflowSerializableValue;
     readonly error?: string;
 }
+export interface ToolNodeSnapshot extends WorkflowSerializableObject {
+    readonly kind: "tool";
+    /** Stable durable node identity. */
+    readonly id: string;
+    readonly name: string;
+    readonly argsHash: string;
+    readonly ordinal: number;
+    readonly parentIds: readonly string[];
+    readonly status: "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
+    readonly topologyState?: "unavailable";
+    readonly replayed?: boolean;
+    readonly executionOrder?: number;
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+    readonly resultSummary?: string;
+    readonly error?: string;
+    readonly attachable: false;
+}
 export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
     readonly runId: string;
     readonly status: RunStatus;
     readonly result?: Partial<TOutputs>;
     readonly error?: string;
+    /** Tool node whose rejection supplied the selected terminal failure. */
+    readonly failedToolNodeId?: string;
     /** True when the run reached its terminal status through ctx.exit(). */
     readonly exited?: boolean;
     readonly exitReason?: string;
     readonly stages: readonly StageSnapshot[];
+    /** Always populated by the runtime; optional for legacy structural literals. */
+    readonly toolNodes?: readonly ToolNodeSnapshot[];
 }
 export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> & WorkflowSerializableObject;
 export interface GitWorktreeSetupOptions extends WorkflowSerializableObject {

package/dist/builtin/workflows/src/shared/authoring-contract-ui.ts

@@ -115,26 +115,68 @@ export interface WorkflowRunContext<
   tool: WorkflowToolPrimitive;
 }
 
-/**
- * `ctx.tool` primitive signature. Runs an async function and caches the result.
- */
-export interface WorkflowToolPrimitive {
-  <TValue extends WorkflowSerializableValue>(
-    name: string,
-    args: Readonly<Record<string, WorkflowSerializableValue>>,
-    fn: () => Promise<TValue>,
-    options?: WorkflowToolOptions,
-  ): Promise<TValue>;
+/** Serializable process details copied from an exhausted `ctx.tool` callback error. */
+export interface WorkflowToolError extends WorkflowSerializableObject {
+  readonly name: string;
+  readonly message: string;
+  readonly exitCode?: number;
+  readonly stdout?: string;
+  readonly stderr?: string;
+}
+
+export interface WorkflowToolSuccess<TValue extends WorkflowSerializableValue> extends WorkflowSerializableObject {
+  readonly ok: true;
+  readonly value: TValue;
+  readonly attempts: number;
+  readonly cached: boolean;
+}
+
+export interface WorkflowToolFailure extends WorkflowSerializableObject {
+  readonly ok: false;
+  readonly error: WorkflowToolError;
+  readonly attempts: number;
+  readonly cached: boolean;
 }
 
-/** Options for `ctx.tool`. */
+/** Typed result returned when `failureMode: "return"` is selected. */
+export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> =
+  | WorkflowToolSuccess<TValue>
+  | WorkflowToolFailure;
+
+/** Options for `ctx.tool`. Throwing after exhausted retries remains the default. */
 export interface WorkflowToolOptions {
+  readonly failureMode?: "throw" | "return";
   readonly retriesAllowed?: boolean;
   readonly maxAttempts?: number;
   readonly intervalMs?: number;
   readonly backoffRate?: number;
 }
 
+export type WorkflowToolReturnOptions = WorkflowToolOptions & { readonly failureMode: "return" };
+export type WorkflowToolThrowOptions = WorkflowToolOptions & { readonly failureMode?: "throw" };
+
+/** `ctx.tool` runs an async function and durably caches its serializable result. */
+export interface WorkflowToolPrimitive {
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options: WorkflowToolReturnOptions,
+  ): Promise<WorkflowToolOutcome<TValue>>;
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options?: WorkflowToolThrowOptions,
+  ): Promise<TValue>;
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options?: WorkflowToolOptions,
+  ): Promise<TValue | WorkflowToolOutcome<TValue>>;
+}
+
 export type WorkflowRunFn<
   TInputs extends WorkflowInputValues = WorkflowInputValues,
   TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
@@ -290,15 +332,38 @@ export interface StageSnapshot extends WorkflowSerializableObject {
   readonly error?: string;
 }
 
+export interface ToolNodeSnapshot extends WorkflowSerializableObject {
+  readonly kind: "tool";
+  /** Stable durable node identity. */
+  readonly id: string;
+  readonly name: string;
+  readonly argsHash: string;
+  readonly ordinal: number;
+  readonly parentIds: readonly string[];
+  readonly status: "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
+  readonly topologyState?: "unavailable";
+  readonly replayed?: boolean;
+  readonly executionOrder?: number;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly resultSummary?: string;
+  readonly error?: string;
+  readonly attachable: false;
+}
+
 export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
   readonly runId: string;
   readonly status: RunStatus;
   readonly result?: Partial<TOutputs>;
   readonly error?: string;
+  /** Tool node whose rejection supplied the selected terminal failure. */
+  readonly failedToolNodeId?: string;
   /** True when the run reached its terminal status through ctx.exit(). */
   readonly exited?: boolean;
   readonly exitReason?: string;
   readonly stages: readonly StageSnapshot[];
+  /** Always populated by the runtime; optional for legacy structural literals. */
+  readonly toolNodes?: readonly ToolNodeSnapshot[];
 }
 
 export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> & WorkflowSerializableObject;