@agentproto/workflow-runtime 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -110,6 +110,19 @@ interface TolerantFanOutResult<T = unknown> {
 /** Default for {@link MapStep.maxConsecutiveSpawnFailures} /
  *  {@link PipelineStep.maxConsecutiveSpawnFailures}. */
 declare const DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES = 3;
+/** An {@link AgentStep}'s transport-failure retry policy — the same shape as
+ *  {@link GateStep.retry}. `initialMs` is the wait before the first retry;
+ *  `"exponential"` doubles it on each further one. */
+interface AgentStepRetry {
+    maxAttempts: number;
+    backoff: "fixed" | "exponential";
+    initialMs?: number;
+}
+/** What an {@link AgentStep} without its own `retry` gets: two attempts —
+ *  one retry after a 1 s pause — so a single dropped connection doesn't fail
+ *  a long run. Applies to a session lost mid-turn only, never to a spawn
+ *  failure or a completed turn (see {@link AgentStep.retry}). */
+declare const DEFAULT_AGENT_TRANSPORT_RETRY: Readonly<AgentStepRetry>;
 /** Default for {@link ToolStep.timeoutMs} / {@link GateStep.timeoutMs} when
  *  the step declares none — 10 minutes. Bounds an otherwise-unbounded `tool`
  *  or `gate` step dispatch (F45). */
@@ -404,6 +417,22 @@ interface AgentStep {
     outputSchema?: OutputSchemaLike;
     /** Re-prompt-and-retry attempts on schema mismatch before failing. Default 2. */
     maxRetries?: number;
+    /** Re-spawn on a TRANSPORT failure, up to `maxAttempts` total attempts —
+     *  the same shape as {@link GateStep.retry}. Only a failure that is the
+     *  session's plumbing, never its content, is retried: the spawn rejected
+     *  ({@link AgentSpawnError}), or the session died before its FIRST turn
+     *  ended (the host threw an error marked `transport: true`, e.g.
+     *  {@link AgentSessionLostError} for a killed session or a closed ACP
+     *  connection). A step whose turn completed — including one that then
+     *  failed its `outputSchema` re-prompts, or died during one — is never
+     *  retried, nor is a cancelled run or a `sessionRef` reuse (there is no
+     *  fresh session to spawn). Each retry spawns a NEW session with the same
+     *  resolved prompt, cwd and harness, in the same run workspace.
+     *  Unset ⇒ {@link DEFAULT_AGENT_TRANSPORT_RETRY} (one retry), and then
+     *  for a session lost mid-turn ONLY — a spawn failure is usually
+     *  deterministic (bad cwd, missing adapter), so it is re-spawned past only
+     *  when the step declares `retry` itself. `maxAttempts: 1` disables it. */
+    retry?: AgentStepRetry;
     /** Cache this step's output under the run's cacheKey; the resolved prompt +
      *  adapter + model + sessionRef are hashed. Default false — most agent steps have
      *  side effects. */
@@ -555,6 +584,20 @@ interface GateReportEvent {
     report: unknown;
     attempt: number;
 }
+/** One transport-failure retry of a `kind: "agent"` step, reported right
+ *  before the fresh session is spawned — the `step.retrying` event. */
+interface AgentRetryEvent {
+    stepId: string;
+    /** The attempt that is about to start (2 for the first retry). */
+    attempt: number;
+    maxAttempts: number;
+    /** The failed attempt's error message. */
+    error: string;
+    /** The failed attempt's session, when it got far enough to have one. */
+    sessionId?: string;
+    /** How long the runtime waits before spawning the next attempt. */
+    delayMs: number;
+}
 /** What a declarative agent-step's `agent.ref` resolves to — the adapter to
  *  spawn under plus any adapter options that pick which concrete agent runs
  *  (e.g. mastra-agent's `agent` option, an emitted AGENT.md path). Built by
@@ -616,6 +659,14 @@ interface RuntimeWorkflow {
      *  every top-level step finishes successfully. See {@link OutputsFileContract}
      *  and `run-workflow.ts`'s `checkOutputsFiles`. */
     outputsFiles?: Readonly<Record<string, OutputsFileContract>>;
+    /**
+     * `false` ⇒ no step anywhere in this workflow reuses another step's session
+     * (`sessionRef`), so each top-level step's sessions are released as soon as
+     * that step finishes instead of being held until the run ends (a run parked
+     * on an approval would otherwise keep every finished step's session live).
+     * Omitted/`true` ⇒ the conservative default: release at run end.
+     */
+    reusesSessions?: boolean;
 }
 /** A human/host decision on one approval request. `who` records WHO decided
  *  ("human", "timeout", "cancelled", …); `note` is optional free text. */
@@ -847,6 +898,9 @@ interface RunWorkflowArgs {
     /** Called once per `kind: "gate"` command attempt (every attempt, not just
      *  the last) — the `gate-report` lifecycle event. */
     onGateReport?: (ev: GateReportEvent) => void;
+    /** Called before each transport-failure retry of a `kind: "agent"` step
+     *  (see {@link AgentStep.retry}) — never for the first attempt. */
+    onAgentRetry?: (ev: AgentRetryEvent) => void;
 }
 interface WorkflowRunResult {
     output: unknown;
@@ -921,6 +975,28 @@ declare class AgentSpawnError extends Error {
     readonly cause: unknown;
     constructor(stepId: string, cause: unknown);
 }
+/**
+ * Thrown by an {@link AgentSessionHost} when a spawned session died under a
+ * step before its turn ended — killed or crashed mid-turn, its ACP
+ * connection closed, its prompt never delivered — as opposed to a turn that
+ * ended and produced the wrong thing. The `transport: true` marker (not the
+ * class identity) is what {@link isAgentTransportFailure} reads, so a host
+ * bundling its own copy of this package still classifies correctly.
+ */
+declare class AgentSessionLostError extends Error {
+    readonly sessionId: string;
+    readonly cause?: unknown | undefined;
+    readonly transport: true;
+    constructor(sessionId: string, message: string, cause?: unknown | undefined);
+}
+/**
+ * True when `err` is a transport failure an {@link AgentStep}'s `retry` may
+ * re-spawn past: an {@link AgentSpawnError}, or any error carrying
+ * `transport: true` (see {@link AgentSessionLostError}). Everything else —
+ * an empty or errored turn, a schema mismatch, a budget cap — is the step's
+ * own outcome and is never retried.
+ */
+declare function isAgentTransportFailure(err: unknown): boolean;
 /**
  * Thrown instead of dispatching a step whose run was cancelled
  * (`ctx.signal.aborted`) — checked BEFORE any work for the step begins (see
@@ -1155,6 +1231,8 @@ interface AgentStepFields {
     policy?: AgentStep["policy"];
     outputSchema?: AgentStep["outputSchema"];
     maxRetries?: number;
+    /** See {@link AgentStep.retry}. */
+    retry?: AgentStep["retry"];
     options?: Record<string, boolean | number | string>;
     harness?: AgentHarness;
     agentTools?: readonly string[];
@@ -1215,4 +1293,4 @@ declare class NodeFsPort implements FsPort {
     lock(): Promise<FsLockHandle>;
 }
 
-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, DEFAULT_STEP_TIMEOUT_MS, 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, WorkflowCancelledError, WorkflowCompileError, type WorkflowInputValidation, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };
+export { type AgentHarness, AgentInputRequiredError, type AgentRefResolution, type AgentRetryEvent, type AgentSandboxRef, type AgentSessionHost, AgentSessionLostError, AgentSpawnError, type AgentStep, type AgentStepFields, type AgentStepRetry, type ApprovalDecision, type ApprovalRequest, type ApprovalStep, type ArtifactEntry, type ArtifactStep, type Bindings, type BranchStep, type CompileWorkflowOptions, DEFAULT_AGENT_TRANSPORT_RETRY, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, DEFAULT_STEP_TIMEOUT_MS, 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, WorkflowCancelledError, WorkflowCompileError, type WorkflowInputValidation, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isAgentTransportFailure, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };

package/dist/index.mjs

@@ -33,6 +33,7 @@ function buildAgentStep(id, fields) {
     policy: fields.policy ?? { awaiting: "fail" },
     ...fields.outputSchema !== void 0 ? { outputSchema: fields.outputSchema } : {},
     ...fields.maxRetries !== void 0 ? { maxRetries: fields.maxRetries } : {},
+    ...fields.retry !== void 0 ? { retry: fields.retry } : {},
     ...fields.harness !== void 0 ? { harness: fields.harness } : {},
     ...fields.agentTools !== void 0 ? { agentTools: fields.agentTools } : {}
   };
@@ -355,6 +356,16 @@ function collectStepIds(steps, ids = /* @__PURE__ */ new Set()) {
   }
   return ids;
 }
+function usesSessionRef(steps) {
+  for (const s of steps) {
+    if (s?.sessionRef !== void 0 || s?.kind === "subworkflow") return true;
+    if (Array.isArray(s?.steps) && usesSessionRef(s.steps)) return true;
+    if (Array.isArray(s?.branches)) {
+      for (const br of s.branches) if (Array.isArray(br?.steps) && usesSessionRef(br.steps)) return true;
+    }
+  }
+  return false;
+}
 function compileWorkflow(handle, opts) {
   const steps = handle.steps;
   if (handle.start && handle.start !== steps[0]?.id) {
@@ -374,7 +385,8 @@ function compileWorkflow(handle, opts) {
     steps: compileSiblingsToSteps(steps, ctx),
     ...finallySteps?.length ? { finally: compileSiblingsToSteps(finallySteps, finallyCtx) } : {},
     ...output ? { output } : {},
-    ...outputsFiles ? { outputsFiles } : {}
+    ...outputsFiles ? { outputsFiles } : {},
+    ...usesSessionRef([...steps, ...finallySteps ?? []]) ? {} : { reusesSessions: false }
   };
 }
 function compileSiblingsToSteps(steps, ctx) {
@@ -548,6 +560,7 @@ function compileAgentStep(step, id, ctx) {
   }
   const rawCwd = step.cwd;
   const cwd = typeof rawCwd === "function" ? rawCwd : typeof rawCwd === "string" ? (b) => resolveRefString(id, "cwd", rawCwd, b, "error") : void 0;
+  const retry = compileAgentRetry(step.retry, id);
   return buildAgentStep(id, {
     prompt: (b) => renderPrompt(prompt, b),
     ...adapter !== void 0 ? { adapter } : {},
@@ -560,10 +573,31 @@ function compileAgentStep(step, id, ctx) {
     policy: step.policy,
     ...outputSchema !== void 0 ? { outputSchema } : {},
     ...step.maxRetries !== void 0 ? { maxRetries: step.maxRetries } : {},
+    ...retry !== void 0 ? { retry } : {},
     ...step.harness !== void 0 ? { harness: step.harness } : {},
     ...agentTools !== void 0 ? { agentTools } : {}
   });
 }
+function compileAgentRetry(raw, id) {
+  if (raw === void 0) return void 0;
+  if (typeof raw !== "object" || raw === null) {
+    throw new WorkflowCompileError(`agent step '${id}': 'retry' must be an object { max_attempts, backoff?, initial_ms? }`);
+  }
+  const r = raw;
+  const maxAttempts = r.max_attempts ?? r.maxAttempts;
+  if (typeof maxAttempts !== "number" || !Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 20) {
+    throw new WorkflowCompileError(`agent step '${id}': 'retry.max_attempts' must be an integer between 1 and 20`);
+  }
+  const backoff = r.backoff ?? "fixed";
+  if (backoff !== "fixed" && backoff !== "exponential") {
+    throw new WorkflowCompileError(`agent step '${id}': 'retry.backoff' must be "fixed" or "exponential"`);
+  }
+  const initialMs = r.initial_ms ?? r.initialMs;
+  if (initialMs !== void 0 && (typeof initialMs !== "number" || !Number.isInteger(initialMs) || initialMs < 0)) {
+    throw new WorkflowCompileError(`agent step '${id}': 'retry.initial_ms' must be a non-negative integer`);
+  }
+  return { maxAttempts, backoff, ...initialMs !== void 0 ? { initialMs } : {} };
+}
 function compileGateStep(step, id) {
   const command = f(step, "command");
   if (typeof command !== "string" || command.trim().length === 0) {
@@ -784,6 +818,11 @@ function resolveRefString(stepId, field, value, b, onUnmatched = "passthrough")
 
 // src/types.ts
 var DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES = 3;
+var DEFAULT_AGENT_TRANSPORT_RETRY = Object.freeze({
+  maxAttempts: 2,
+  backoff: "fixed",
+  initialMs: 1e3
+});
 var DEFAULT_STEP_TIMEOUT_MS = 10 * 60 * 1e3;
 var NodeFsPort = class {
   root;
@@ -1026,6 +1065,23 @@ var AgentSpawnError = class extends Error {
   stepId;
   cause;
 };
+var AgentSessionLostError = class extends Error {
+  constructor(sessionId, message, cause) {
+    super(message);
+    this.sessionId = sessionId;
+    this.cause = cause;
+    this.name = "AgentSessionLostError";
+  }
+  sessionId;
+  cause;
+  transport = true;
+};
+function isAgentTransportFailure(err) {
+  return err instanceof AgentSpawnError || isAgentSessionLost(err);
+}
+function isAgentSessionLost(err) {
+  return typeof err === "object" && err !== null && err.transport === true;
+}
 var WorkflowCancelledError = class extends Error {
   constructor(stepId) {
     super(`step '${stepId}': run cancelled \u2014 not started`);
@@ -1055,7 +1111,7 @@ function view(ctx, item, index) {
 }
 function withIndexedHooks(ctx, index) {
   const cacheKeySuffix = `${ctx.cacheKeySuffix ?? ""}[${index}]`;
-  if (!ctx.onStepStart && !ctx.onStepComplete && !ctx.onStepSkipped && !ctx.onStepFailed) {
+  if (!ctx.onStepStart && !ctx.onStepComplete && !ctx.onStepSkipped && !ctx.onStepFailed && !ctx.onAgentRetry) {
     return { ...ctx, cacheKeySuffix };
   }
   return {
@@ -1064,7 +1120,8 @@ function withIndexedHooks(ctx, index) {
     onStepStart: ctx.onStepStart ? (id, info) => ctx.onStepStart(`${id}[${index}]`, info) : void 0,
     onStepComplete: ctx.onStepComplete ? (id, out, info) => ctx.onStepComplete(`${id}[${index}]`, out, info) : void 0,
     onStepSkipped: ctx.onStepSkipped ? (id, info) => ctx.onStepSkipped(`${id}[${index}]`, info) : void 0,
-    onStepFailed: ctx.onStepFailed ? (id, info) => ctx.onStepFailed(`${id}[${index}]`, info) : void 0
+    onStepFailed: ctx.onStepFailed ? (id, info) => ctx.onStepFailed(`${id}[${index}]`, info) : void 0,
+    onAgentRetry: ctx.onAgentRetry ? (ev) => ctx.onAgentRetry({ ...ev, stepId: `${ev.stepId}[${index}]` }) : void 0
   };
 }
 var failureOrigin = /* @__PURE__ */ new WeakMap();
@@ -1299,25 +1356,90 @@ async function runSequence(steps, ctx, item, index) {
   return last;
 }
 async function sendPromptAndAwaitOutcome(ctx, step, sessionId, prompt) {
-  let next = prompt;
+  await ctx.agents.sendPromptAndWait(sessionId, prompt);
+  await settleInputRequests(ctx, step, sessionId);
+}
+async function settleInputRequests(ctx, step, sessionId) {
   for (; ; ) {
-    await ctx.agents.sendPromptAndWait(sessionId, next);
     const req = ctx.agents.takeInputRequest?.(sessionId);
     if (!req) return;
     if (!ctx.onInputRequired) {
       throw new AgentInputRequiredError(step.id, req.prompt, req.schema);
     }
     const payload = await ctx.onInputRequired({ stepId: step.id, prompt: req.prompt, schema: req.schema });
-    next = JSON.stringify(payload);
+    await ctx.agents.sendPromptAndWait(sessionId, JSON.stringify(payload));
+  }
+}
+function agentRetryDelayMs(retry, attempt) {
+  if (!retry.initialMs) return 0;
+  return retry.backoff === "exponential" ? retry.initialMs * 2 ** (attempt - 2) : retry.initialMs;
+}
+function sleepUnlessAborted(ms, signal) {
+  if (ms <= 0 || signal?.aborted) return Promise.resolve();
+  return new Promise((resolve2) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve2();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function spawnOrResolveSession(step, ctx, b, spawnOpts) {
+  let sessionId;
+  if (step.adapter) {
+    if (ctx.signal?.aborted) throw new WorkflowCancelledError(step.id);
+    const { cwd, sandbox, harness } = spawnOpts;
+    try {
+      sessionId = await ctx.agents.spawn(resolveSel(step.adapter, b), {
+        cwd,
+        workspaceSlug: ctx.workspaceSlug,
+        stepId: step.id,
+        ...sandbox !== void 0 ? { sandbox } : {},
+        ...step.options !== void 0 ? { options: step.options } : {},
+        ...harness !== void 0 ? { harness } : {},
+        ...step.agentTools !== void 0 ? { agentTools: step.agentTools } : {},
+        ...b.index !== void 0 ? { stepKey: `${step.id}[${b.index}]` } : {}
+      });
+    } catch (err) {
+      throw new AgentSpawnError(step.id, err);
+    }
+  } else {
+    sessionId = ctx.agents.resolveByLabel(resolveSessionRef(step.sessionRef, b));
+  }
+  if (!sessionId) throw new Error(`step '${step.id}': no session (adapter and sessionRef both unresolved)`);
+  return sessionId;
+}
+async function retireLostSession(ctx, sessionId) {
+  const agents = ctx.agents;
+  if (agents.readCostUsd) {
+    try {
+      ctx.state.costBySession.set(sessionId, await agents.readCostUsd(sessionId));
+    } catch {
+    }
+  }
+  const idx = ctx.spawned?.indexOf(sessionId) ?? -1;
+  if (idx >= 0) ctx.spawned.splice(idx, 1);
+  if (agents.releaseSession) {
+    try {
+      await agents.releaseSession(sessionId);
+    } catch {
+    }
   }
 }
 async function execAgentStep(step, ctx, b) {
   ctx.onStepStart?.(step.id);
-  if (step.adapter && ctx.state.maxTotalCostUsd !== void 0 && spentUsd(ctx.state) >= ctx.state.maxTotalCostUsd) {
-    throw new Error(
-      `step '${step.id}': budget_exceeded \u2014 run spend $${spentUsd(ctx.state).toFixed(4)} >= cap $${ctx.state.maxTotalCostUsd}`
-    );
-  }
+  const assertBudget = () => {
+    if (step.adapter && ctx.state.maxTotalCostUsd !== void 0 && spentUsd(ctx.state) >= ctx.state.maxTotalCostUsd) {
+      throw new Error(
+        `step '${step.id}': budget_exceeded \u2014 run spend $${spentUsd(ctx.state).toFixed(4)} >= cap $${ctx.state.maxTotalCostUsd}`
+      );
+    }
+  };
+  assertBudget();
   const stepCwd = step.cwd ? resolveSel(step.cwd, b) : void 0;
   const cwd = step.harness?.cwd ?? (stepCwd !== void 0 ? ctx.cwd !== void 0 ? resolve(ctx.cwd, stepCwd) : stepCwd : ctx.cwd);
   let knowledgeOut;
@@ -1351,45 +1473,53 @@ ${inner(b2)}` };
     ...step.harness ?? {},
     ...model !== void 0 && step.harness?.model === void 0 ? { model } : {}
   } : void 0;
+  const inputRequestAffordance = ctx.agents.takeInputRequest ? "\n\nIf you need information you don't have, call the run_request_input tool instead of asking in your reply." : "";
+  const outputSchemaNote = step.outputSchema ? describeOutputSchemaForPrompt(step.outputSchema) : void 0;
+  const outputSchemaAffordance = outputSchemaNote ? `
+
+${outputSchemaNote}` : "";
+  const firstPrompt = step.prompt(b) + inputRequestAffordance + outputSchemaAffordance;
+  const retry = step.adapter ? step.retry ?? DEFAULT_AGENT_TRANSPORT_RETRY : void 0;
+  const maxAttempts = Math.max(1, Math.floor(retry?.maxAttempts ?? 1));
   let sessionId;
-  if (step.adapter) {
-    if (ctx.signal?.aborted) throw new WorkflowCancelledError(step.id);
+  for (let attempt = 1; ; attempt++) {
+    let attemptSession;
     try {
-      sessionId = await ctx.agents.spawn(resolveSel(step.adapter, b), {
-        cwd,
-        workspaceSlug: ctx.workspaceSlug,
+      attemptSession = await spawnOrResolveSession(step, ctx, b, { cwd, sandbox, harness });
+      if (step.adapter) ctx.spawned?.push(attemptSession);
+      if (knowledgeWarnings.length > 0 && ctx.agents.emitHarnessWarning) {
+        ctx.agents.emitHarnessWarning({
+          sessionId: attemptSession,
+          warnings: knowledgeWarnings,
+          label: step.id
+        });
+      }
+      await ctx.agents.sendPromptAndWait(attemptSession, firstPrompt);
+      sessionId = attemptSession;
+      break;
+    } catch (err) {
+      const retryable = step.retry !== void 0 ? isAgentTransportFailure(err) : isAgentSessionLost(err);
+      if (attempt >= maxAttempts || !retryable || ctx.signal?.aborted) throw err;
+      if (attemptSession !== void 0) await retireLostSession(ctx, attemptSession);
+      const delayMs = agentRetryDelayMs(retry, attempt + 1);
+      ctx.onAgentRetry?.({
         stepId: step.id,
-        ...sandbox !== void 0 ? { sandbox } : {},
-        ...step.options !== void 0 ? { options: step.options } : {},
-        ...harness !== void 0 ? { harness } : {},
-        ...step.agentTools !== void 0 ? { agentTools: step.agentTools } : {},
-        ...b.index !== void 0 ? { stepKey: `${step.id}[${b.index}]` } : {}
+        attempt: attempt + 1,
+        maxAttempts,
+        error: errorMessage(err),
+        ...attemptSession !== void 0 ? { sessionId: attemptSession } : {},
+        delayMs
       });
-    } catch (err) {
-      throw new AgentSpawnError(step.id, err);
+      await sleepUnlessAborted(delayMs, ctx.signal);
+      if (ctx.signal?.aborted) throw new WorkflowCancelledError(step.id);
+      assertBudget();
     }
-  } else {
-    sessionId = ctx.agents.resolveByLabel(resolveSessionRef(step.sessionRef, b));
-  }
-  if (!sessionId) throw new Error(`step '${step.id}': no session (adapter and sessionRef both unresolved)`);
-  if (step.adapter) ctx.spawned?.push(sessionId);
-  if (knowledgeWarnings.length > 0 && ctx.agents.emitHarnessWarning) {
-    ctx.agents.emitHarnessWarning({
-      sessionId,
-      warnings: knowledgeWarnings,
-      label: step.id
-    });
   }
+  await settleInputRequests(ctx, step, sessionId);
   const harnessOut = harness !== void 0 ? {
     ...harness,
     ...harness.tools && harness.tools.length > 0 ? { toolsApplied: false } : {}
   } : void 0;
-  const inputRequestAffordance = ctx.agents.takeInputRequest ? "\n\nIf you need information you don't have, call the run_request_input tool instead of asking in your reply." : "";
-  const outputSchemaNote = step.outputSchema ? describeOutputSchemaForPrompt(step.outputSchema) : void 0;
-  const outputSchemaAffordance = outputSchemaNote ? `
-
-${outputSchemaNote}` : "";
-  await sendPromptAndAwaitOutcome(ctx, step, sessionId, step.prompt(b) + inputRequestAffordance + outputSchemaAffordance);
   if (step.policy && ctx.agents.onAwaitingInput) {
     await ctx.agents.onAwaitingInput(sessionId, step.policy);
   }
@@ -1877,6 +2007,7 @@ async function execStepBody(step, ctx, item, index) {
         cacheKey: ctx.cacheKey,
         runGateCommand: ctx.runGateCommand,
         onGateReport: ctx.onGateReport,
+        onAgentRetry: ctx.onAgentRetry,
         spawned: ctx.spawned,
         usedArtifactNames: ctx.usedArtifactNames
       });
@@ -2034,6 +2165,7 @@ async function runWorkflowInner(workflow, input, hooks, maxTotalCostUsd) {
       const out = await execStep(step, ctx, void 0, void 0);
       state.steps[step.id] = out;
       completeStep(ctx, step.id, out);
+      if (ownsScope && workflow.reusesSessions === false) await releaseScope(ctx);
       lastId = step.id;
     }
     await checkOutputsFiles(workflow.outputsFiles, ctx, workflow.id, lastId);
@@ -2071,7 +2203,8 @@ async function runWorkflow(args) {
     onStepSkipped: args.onStepSkipped,
     onStepFailed: args.onStepFailed,
     runGateCommand: args.runGateCommand,
-    onGateReport: args.onGateReport
+    onGateReport: args.onGateReport,
+    onAgentRetry: args.onAgentRetry
   }, args.maxTotalCostUsd);
 }
 function compileWorkflowManifest(source, opts) {
@@ -2080,6 +2213,6 @@ function compileWorkflowManifest(source, opts) {
   return compileWorkflow(handle, opts);
 }
 
-export { AgentInputRequiredError, AgentSpawnError, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, DEFAULT_STEP_TIMEOUT_MS, MissingArtifactError, NodeFsPort, StepOutcomeError, WorkflowCancelledError, WorkflowCompileError, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };
+export { AgentInputRequiredError, AgentSessionLostError, AgentSpawnError, DEFAULT_AGENT_TRANSPORT_RETRY, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, DEFAULT_STEP_TIMEOUT_MS, MissingArtifactError, NodeFsPort, StepOutcomeError, WorkflowCancelledError, WorkflowCompileError, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isAgentTransportFailure, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map