@vercel/factory 0.0.15 → 0.0.16

package/dist/dispatch.mjs

@@ -3,12 +3,18 @@ import { InvalidTransitionError } from "./schema/transitions.mjs";
 import { routeKey } from "./agent-routes.mjs";
 import { RecordNotFoundError, VersionConflictError } from "./store/driver.mjs";
 //#region src/dispatch.ts
-/** The provider may have accepted the request. Keep this attempt for recovery using its original launch key. */
+/**
+* The provider may have accepted the request, so the running attempt must remain available for
+* recovery with its original launch key. Catchers must not queue a replacement attempt blindly.
+*/
 var ExecutionLaunchPendingError = class extends Error {};
 /** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */
 var DispatchRefusedError = class extends Error {
+	/** Exact Task whose current dispatch attempt was refused. */
 	taskId;
+	/** Stable gate or race category suitable for branching and telemetry. */
 	code;
+	/** Human-readable refusal context; canonical Task state remains authoritative. */
 	reason;
 	constructor(taskId, code, reason) {
 		super(`dispatch of "${taskId}" refused: ${reason}`);
@@ -24,8 +30,11 @@ var DispatchRefusedError = class extends Error {
 * the sweep. Operator retry recovers it once budget frees up.
 */
 var BudgetExhaustedError = class extends Error {
+	/** Exact Task already transitioned to `failed` by the exhausted admission. */
 	taskId;
+	/** UTC budget month whose limit refused the reservation. */
 	month;
+	/** Counted settled cost and live reservations observed for that month. */
 	spendUsd;
 	constructor(taskId, month, spendUsd) {
 		super(`dispatch of "${taskId}" refused: budget for ${month} is exhausted at $${spendUsd}`);
@@ -38,11 +47,61 @@ var BudgetExhaustedError = class extends Error {
 /** Default launch-attempt allowance covering delayed identity provisioning. */
 const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;
 /**
-* The handshake between recorded work and execution: win the store-gated
-* transition (at most one dispatcher can succeed), then start the run. A
-* launch failure re-queues the task (bumping its attempt) until the attempt
-* limit, then fails it; a crash between the transition and the launch leaves
-* a running task with no execution, which the sweep reaps.
+* Claims one queued Task and starts its exact execution mode.
+*
+* @remarks
+* Dispatch first checks route, approval, dependency, and optional budget gates, then atomically
+* transitions the Task from `queued` to `running`. Only the winner invokes `launch`. A successful
+* provider dispatch returns only after its execution reference is stored; it does not mean the
+* Task completed. `workflowOwned: true` returns the claimed running Task without starting a
+* provider session.
+*
+* An ordinary launch failure is rethrown after a best-effort transition back to `queued`, or to
+* `failed` once `maxLaunchAttempts` is exhausted. `ExecutionLaunchPendingError` instead leaves the
+* attempt running because the provider may have accepted the request; recovery must inspect or
+* repeat the launch with the original idempotency key. Budget exhaustion fails and receipts the
+* Task before throwing `BudgetExhaustedError`. Since compensating transitions are best-effort,
+* callers handling any thrown launch error should reread canonical Task state before deciding
+* whether to schedule another attempt.
+*
+* @param stores - Task, graph, and receipt stores that own the dispatch gates.
+* @param input - Exact Task identity plus either a launcher or workflow-owned marker.
+* @returns The running Task, including its durably recorded execution when a launcher was used.
+* @throws `RecordNotFoundError` when the Task is absent.
+* @throws `DispatchRefusedError` when routing, approval, dependencies, or a budget-admission race refuses dispatch.
+* @throws `InvalidTransitionError` when the Task is no longer queued when this caller claims it.
+* @throws `BudgetExhaustedError` after the Task has been failed because no reservation fits.
+* @throws `ExecutionLaunchPendingError` when provider acceptance is ambiguous and requires recovery.
+* @see The shipped `docs/recipes/eve-agent.md` and `docs/recipes/retry-recovery.md` recipes.
+*
+* @example
+* ```ts
+* import {
+*   DispatchRefusedError,
+*   dispatchTask,
+*   type DispatchStores,
+* } from "@vercel/factory/execution";
+* import type { TaskId } from "@vercel/factory/tasks";
+* import { parseAgentRouteBinding } from "@vercel/factory/workflows";
+*
+* declare const stores: DispatchStores;
+* declare const taskId: TaskId;
+* const route = parseAgentRouteBinding({ id: "worker", version: 1 });
+*
+* try {
+*   await dispatchTask(stores, {
+*     taskId,
+*     route,
+*     launch: async () => ({ provider: "eve", sessionId: "ses_example" }),
+*   });
+* } catch (error) {
+*   if (error instanceof DispatchRefusedError) {
+*     // `error.code` identifies the gate; canonical Task state remains authoritative.
+*   } else {
+*     throw error;
+*   }
+* }
+* ```
 */
 async function dispatchTask(stores, input) {
 	const { taskId } = input;
@@ -62,13 +121,13 @@ async function dispatchTask(stores, input) {
 	if (options.budget !== void 0 && task.state === "queued") {
 		const budgetNow = (options.budget.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
 		const month = options.budget.month ?? budgetMonthOf(budgetNow);
-		const rows = (options.budget.tasks ?? await stores.tasks.list()).map((row) => row.id === taskId ? {
+		const rows = (options.budget.enforce === false ? [] : options.budget.tasks ?? await stores.tasks.list()).map((row) => row.id === taskId ? {
 			...row,
 			reservedUsd: void 0
 		} : row);
 		const spendUsd = computeMonthSpendUsd(rows, month);
 		const { totalUsd, perTaskReservationUsd } = options.budget.limits;
-		if (!canReserve(spendUsd, options.budget.limits)) {
+		if (options.budget.enforce !== false && !canReserve(spendUsd, options.budget.limits)) {
 			const reason = `budget exhausted: ${month} spend $${spendUsd} cannot fit a $${perTaskReservationUsd} reservation under $${totalUsd}`;
 			try {
 				await stores.tasks.transition(taskId, "failed", {
@@ -103,7 +162,7 @@ async function dispatchTask(stores, input) {
 			reservedUsd: reservation.reservedUsd,
 			reservedAt: reservation.reservedAt
 		} },
-		...task.attempt > 1 ? { phase: "retry" } : {}
+		...task.attempt > 1 ? { phase: options.continuationAttempt === task.attempt ? "workflow" : "retry" } : {}
 	});
 	if (options.workflowOwned === true) return running;
 	let execution;

package/dist/dispatch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.mjs","names":[],"sources":["../src/dispatch.ts"],"sourcesContent":["import { budgetMonthOf, canReserve, computeMonthSpendUsd } from \"./budget\";\nimport type { AgentRouteBinding } from \"./agent-routes\";\nimport type { BudgetLimits, BudgetMonth } from \"./schema/budget\";\nimport type { DateClock } from \"./schema/common\";\nimport type { TaskId } from \"./schema/id\";\nimport type { ExecutionReference, Task } from \"./schema/task\";\nimport { routeKey } from \"./agent-routes\";\nimport { InvalidTransitionError } from \"./schema/transitions\";\nimport { RecordNotFoundError, VersionConflictError } from \"./store/driver\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Minimal persistence capabilities required to gate and record one dispatch. */\nexport type DispatchStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/** The provider may have accepted the request. Keep this attempt for recovery using its original launch key. */\nexport class ExecutionLaunchPendingError extends Error {}\n\n/** Stable machine-readable reason a Task could not be dispatched. */\nexport type DispatchRefusalCode =\n  | \"route_mismatch\"\n  | \"awaiting_approval\"\n  | \"approval_denied\"\n  | \"dependencies_unsatisfied\"\n  | \"dispatch_race\";\n\n/** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */\nexport class DispatchRefusedError extends Error {\n  readonly taskId: TaskId;\n  readonly code: DispatchRefusalCode;\n  readonly reason: string;\n\n  constructor(taskId: TaskId, code: DispatchRefusalCode, reason: string) {\n    super(`dispatch of \"${taskId}\" refused: ${reason}`);\n    this.name = \"DispatchRefusedError\";\n    this.taskId = taskId;\n    this.code = code;\n    this.reason = reason;\n  }\n}\n\n/**\n * An exhausted budget is definitive, not a retryable refusal: the task has\n * already been failed and receipted when this throws, so it never re-enters\n * the sweep. Operator retry recovers it once budget frees up.\n */\nexport class BudgetExhaustedError extends Error {\n  readonly taskId: TaskId;\n  readonly month: BudgetMonth;\n  readonly spendUsd: number;\n\n  constructor(taskId: TaskId, month: BudgetMonth, spendUsd: number) {\n    super(`dispatch of \"${taskId}\" refused: budget for ${month} is exhausted at $${spendUsd}`);\n    this.name = \"BudgetExhaustedError\";\n    this.taskId = taskId;\n    this.month = month;\n    this.spendUsd = spendUsd;\n  }\n}\n\n/** Factory-wide reservation limits and snapshot used to gate one dispatch. */\nexport interface DispatchBudget {\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\">;\n  /** Defaults to the current UTC month. */\n  month?: BudgetMonth;\n  now?: DateClock;\n  /** A dispatcher-wide snapshot used to calculate spend without another list. */\n  tasks?: readonly Task[];\n}\n\ninterface DispatchContext {\n  /** How many launches to try before the task fails for good; a failure re-queues for the next sweep. */\n  maxLaunchAttempts?: number;\n  /** Reserve-before-execution policy for this dispatch. */\n  budget?: DispatchBudget;\n}\n\n/** Exact provider launch or explicit workflow-owned execution for one Task dispatch. */\nexport type DispatchOptions = DispatchContext &\n  (\n    | {\n        /** Required exact binding when the Task declares an agent route. */\n        route?: AgentRouteBinding;\n        /**\n         * Starts the durable execution for the task (an Eve agent run). Runs after\n         * the task has won the queued -> running transition. Its provider reference\n         * is mandatory so recovery can always find an accepted run.\n         */\n        launch: (task: Task) => Promise<ExecutionReference>;\n        workflowOwned?: never;\n      }\n    | {\n        /** Marks work whose workflow advances the running Task without a provider session. */\n        workflowOwned: true;\n        route?: never;\n        launch?: never;\n      }\n  );\n\n/** Task identity and exact launch mode supplied to one dispatch attempt. */\nexport type DispatchTaskInput = { readonly taskId: TaskId } & DispatchOptions;\n\n// A fresh Vercel project rejects its own agents' sessions until its identity\n// finishes provisioning; at one sweep per minute the budget must outlast that.\n/** Default launch-attempt allowance covering delayed identity provisioning. */\nexport const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;\n\n/**\n * The handshake between recorded work and execution: win the store-gated\n * transition (at most one dispatcher can succeed), then start the run. A\n * launch failure re-queues the task (bumping its attempt) until the attempt\n * limit, then fails it; a crash between the transition and the launch leaves\n * a running task with no execution, which the sweep reaps.\n */\nexport async function dispatchTask(\n  stores: DispatchStores,\n  input: DispatchTaskInput,\n): Promise<Task> {\n  const { taskId } = input;\n  const options: DispatchOptions = input;\n  const task = await stores.tasks.get(taskId);\n  if (task === null) {\n    throw new RecordNotFoundError(\"tasks\", taskId);\n  }\n  const route = task.work.route;\n  if (route !== undefined && options.workflowOwned === true) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `agent route ${routeKey(route)} requires a launcher`,\n    );\n  }\n  if (\n    route !== undefined &&\n    (options.route?.id !== route.id || options.route?.version !== route.version)\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `launch requires exact agent route ${routeKey(route)}`,\n    );\n  }\n  if (task.approval === \"required\") {\n    throw new DispatchRefusedError(taskId, \"awaiting_approval\", \"awaiting human approval\");\n  }\n  if (task.approval === \"denied\") {\n    throw new DispatchRefusedError(taskId, \"approval_denied\", \"approval was denied\");\n  }\n  if (\n    !(await stores.graphs.dependenciesSatisfied({\n      rootTaskId: task.rootTaskId,\n      taskId: task.id,\n    }))\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"dependencies_unsatisfied\",\n      \"graph dependencies must all be succeeded before dispatch\",\n    );\n  }\n\n  // The reservation gates queued -> running only; any other state falls\n  // through to the transition below, which rejects it as invalid.\n  let reservation: { reservedUsd: number; reservedAt: string } | undefined;\n  if (options.budget !== undefined && task.state === \"queued\") {\n    const budgetNow = (options.budget.now ?? (() => new Date()))().toISOString();\n    const month = options.budget.month ?? budgetMonthOf(budgetNow);\n    // This task's own retained reservation from a prior attempt is excluded,\n    // because re-reserving overwrites it. Its settled cost stays counted:\n    // that money was actually spent and a retry must not reopen it.\n    const rows = (options.budget.tasks ?? (await stores.tasks.list())).map((row) =>\n      row.id === taskId ? { ...row, reservedUsd: undefined } : row,\n    );\n    const spendUsd = computeMonthSpendUsd(rows, month);\n    const { totalUsd, perTaskReservationUsd } = options.budget.limits;\n    if (!canReserve(spendUsd, options.budget.limits)) {\n      const reason = `budget exhausted: ${month} spend $${spendUsd} cannot fit a $${perTaskReservationUsd} reservation under $${totalUsd}`;\n      // Fail first, so BudgetExhaustedError's contract (task already failed)\n      // holds; losing the task to a concurrent dispatcher surfaces as a\n      // refusal, never as a false exhaustion with a misleading receipt.\n      try {\n        await stores.tasks.transition(taskId, \"failed\", { reason, expectFrom: \"queued\" });\n      } catch (error) {\n        if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) {\n          throw new DispatchRefusedError(\n            taskId,\n            \"dispatch_race\",\n            \"another dispatcher took the task\",\n          );\n        }\n        throw error;\n      }\n      // Best-effort: the failed transition above already wrote its own\n      // receipt carrying this reason, so losing this supplementary one\n      // cannot lose the evidence.\n      await stores.receipts\n        .append({\n          repositoryIds: task.repositoryIds,\n          taskId,\n          kind: task.kind,\n          state: \"reservation_refused\",\n          phase: \"budget\",\n          reason,\n          attempt: task.attempt,\n          dedupeKey: `task:${taskId}:reservation_refused:${task.attempt}`,\n        })\n        .catch(() => undefined);\n      throw new BudgetExhaustedError(taskId, month, spendUsd);\n    }\n    reservation = { reservedUsd: perTaskReservationUsd, reservedAt: budgetNow };\n  }\n\n  const running = await stores.tasks.transition(taskId, \"running\", {\n    expectFrom: \"queued\",\n    expectAttempt: task.attempt,\n    ...(reservation === undefined\n      ? {}\n      : {\n          patch: {\n            reservedUsd: reservation.reservedUsd,\n            reservedAt: reservation.reservedAt,\n          },\n        }),\n    ...(task.attempt > 1 ? { phase: \"retry\" } : {}),\n  });\n  if (options.workflowOwned === true) return running;\n  let execution: ExecutionReference;\n  try {\n    execution = await options.launch(running);\n  } catch (error) {\n    if (error instanceof ExecutionLaunchPendingError) throw error;\n    const reason = (error instanceof Error ? error.message : String(error)).slice(0, 500);\n    const limit = options.maxLaunchAttempts ?? DEFAULT_MAX_LAUNCH_ATTEMPTS;\n    if (running.attempt < limit) {\n      const retryReason = `launch failed (attempt ${running.attempt} of ${limit}), will retry: ${reason}`;\n      await stores.tasks\n        .transition(taskId, \"queued\", {\n          reason: retryReason,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    } else {\n      await stores.tasks\n        .transition(taskId, \"failed\", {\n          reason: `launch failed after ${running.attempt} attempts: ${reason}`,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    }\n    throw error;\n  }\n  // Surface a failed binding so a durable caller can recover the same launch;\n  // never report acceptance with an unrecorded or stale execution.\n  return stores.tasks.recordExecution(taskId, {\n    execution,\n    expectAttempt: running.attempt,\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../src/dispatch.ts"],"sourcesContent":["import { budgetMonthOf, canReserve, computeMonthSpendUsd } from \"./budget\";\nimport type { AgentRouteBinding } from \"./agent-routes\";\nimport type { BudgetLimits, BudgetMonth } from \"./schema/budget\";\nimport type { DateClock } from \"./schema/common\";\nimport type { TaskId } from \"./schema/id\";\nimport type { ExecutionReference, Task } from \"./schema/task\";\nimport { routeKey } from \"./agent-routes\";\nimport { InvalidTransitionError } from \"./schema/transitions\";\nimport { RecordNotFoundError, VersionConflictError } from \"./store/driver\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Minimal persistence capabilities required to gate and record one dispatch. */\nexport type DispatchStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/**\n * The provider may have accepted the request, so the running attempt must remain available for\n * recovery with its original launch key. Catchers must not queue a replacement attempt blindly.\n */\nexport class ExecutionLaunchPendingError extends Error {}\n\n/** Stable machine-readable reason a Task could not be dispatched. */\nexport type DispatchRefusalCode =\n  | \"route_mismatch\"\n  | \"awaiting_approval\"\n  | \"approval_denied\"\n  | \"dependencies_unsatisfied\"\n  | \"dispatch_race\";\n\n/** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */\nexport class DispatchRefusedError extends Error {\n  /** Exact Task whose current dispatch attempt was refused. */\n  readonly taskId: TaskId;\n  /** Stable gate or race category suitable for branching and telemetry. */\n  readonly code: DispatchRefusalCode;\n  /** Human-readable refusal context; canonical Task state remains authoritative. */\n  readonly reason: string;\n\n  constructor(taskId: TaskId, code: DispatchRefusalCode, reason: string) {\n    super(`dispatch of \"${taskId}\" refused: ${reason}`);\n    this.name = \"DispatchRefusedError\";\n    this.taskId = taskId;\n    this.code = code;\n    this.reason = reason;\n  }\n}\n\n/**\n * An exhausted budget is definitive, not a retryable refusal: the task has\n * already been failed and receipted when this throws, so it never re-enters\n * the sweep. Operator retry recovers it once budget frees up.\n */\nexport class BudgetExhaustedError extends Error {\n  /** Exact Task already transitioned to `failed` by the exhausted admission. */\n  readonly taskId: TaskId;\n  /** UTC budget month whose limit refused the reservation. */\n  readonly month: BudgetMonth;\n  /** Counted settled cost and live reservations observed for that month. */\n  readonly spendUsd: number;\n\n  constructor(taskId: TaskId, month: BudgetMonth, spendUsd: number) {\n    super(`dispatch of \"${taskId}\" refused: budget for ${month} is exhausted at $${spendUsd}`);\n    this.name = \"BudgetExhaustedError\";\n    this.taskId = taskId;\n    this.month = month;\n    this.spendUsd = spendUsd;\n  }\n}\n\n/** Factory-wide reservation limits and snapshot used to gate one dispatch. */\nexport interface DispatchBudget {\n  /** Factory-wide monthly ceiling and amount reserved for each admitted Task. */\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\">;\n  /** Defaults to true. False records reservations without enforcing the monthly ceiling. */\n  enforce?: boolean;\n  /** Defaults to the current UTC month. */\n  month?: BudgetMonth;\n  /** Clock used only to derive the reservation month and timestamp. Defaults to `new Date()`. */\n  now?: DateClock;\n  /** A dispatcher-wide snapshot used to calculate spend without another list. */\n  tasks?: readonly Task[];\n}\n\ninterface DispatchContext {\n  /** Exact workflow-confirmed continuation attempt; other replacement attempts count as retries. */\n  continuationAttempt?: number;\n  /**\n   * Maximum Task attempt number allowed for launch failure retries. Defaults to 45. A normal\n   * failure below the limit requeues the Task, which increments its attempt for the next sweep.\n   */\n  maxLaunchAttempts?: number;\n  /** Reserve-before-execution policy for this dispatch. */\n  budget?: DispatchBudget;\n}\n\n/** Exact provider launch or explicit workflow-owned execution for one Task dispatch. */\nexport type DispatchOptions = DispatchContext &\n  (\n    | {\n        /** Required exact binding when the Task declares an agent route. */\n        route?: AgentRouteBinding;\n        /**\n         * Starts the durable execution for the task (an Eve agent run). Runs after\n         * the task has won the queued -> running transition. Its provider reference\n         * is mandatory so recovery can always find an accepted run.\n         */\n        launch: (task: Task) => Promise<ExecutionReference>;\n        workflowOwned?: never;\n      }\n    | {\n        /**\n         * Marks route-less work whose workflow advances the running Task without a provider\n         * session. The caller must schedule that workflow after this admission returns.\n         */\n        workflowOwned: true;\n        route?: never;\n        launch?: never;\n      }\n  );\n\n/** Task identity and exact launch mode supplied to one dispatch attempt. */\nexport type DispatchTaskInput = { readonly taskId: TaskId } & DispatchOptions;\n\n// A fresh Vercel project rejects its own agents' sessions until its identity\n// finishes provisioning; at one sweep per minute the budget must outlast that.\n/** Default launch-attempt allowance covering delayed identity provisioning. */\nexport const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;\n\n/**\n * Claims one queued Task and starts its exact execution mode.\n *\n * @remarks\n * Dispatch first checks route, approval, dependency, and optional budget gates, then atomically\n * transitions the Task from `queued` to `running`. Only the winner invokes `launch`. A successful\n * provider dispatch returns only after its execution reference is stored; it does not mean the\n * Task completed. `workflowOwned: true` returns the claimed running Task without starting a\n * provider session.\n *\n * An ordinary launch failure is rethrown after a best-effort transition back to `queued`, or to\n * `failed` once `maxLaunchAttempts` is exhausted. `ExecutionLaunchPendingError` instead leaves the\n * attempt running because the provider may have accepted the request; recovery must inspect or\n * repeat the launch with the original idempotency key. Budget exhaustion fails and receipts the\n * Task before throwing `BudgetExhaustedError`. Since compensating transitions are best-effort,\n * callers handling any thrown launch error should reread canonical Task state before deciding\n * whether to schedule another attempt.\n *\n * @param stores - Task, graph, and receipt stores that own the dispatch gates.\n * @param input - Exact Task identity plus either a launcher or workflow-owned marker.\n * @returns The running Task, including its durably recorded execution when a launcher was used.\n * @throws `RecordNotFoundError` when the Task is absent.\n * @throws `DispatchRefusedError` when routing, approval, dependencies, or a budget-admission race refuses dispatch.\n * @throws `InvalidTransitionError` when the Task is no longer queued when this caller claims it.\n * @throws `BudgetExhaustedError` after the Task has been failed because no reservation fits.\n * @throws `ExecutionLaunchPendingError` when provider acceptance is ambiguous and requires recovery.\n * @see The shipped `docs/recipes/eve-agent.md` and `docs/recipes/retry-recovery.md` recipes.\n *\n * @example\n * ```ts\n * import {\n *   DispatchRefusedError,\n *   dispatchTask,\n *   type DispatchStores,\n * } from \"@vercel/factory/execution\";\n * import type { TaskId } from \"@vercel/factory/tasks\";\n * import { parseAgentRouteBinding } from \"@vercel/factory/workflows\";\n *\n * declare const stores: DispatchStores;\n * declare const taskId: TaskId;\n * const route = parseAgentRouteBinding({ id: \"worker\", version: 1 });\n *\n * try {\n *   await dispatchTask(stores, {\n *     taskId,\n *     route,\n *     launch: async () => ({ provider: \"eve\", sessionId: \"ses_example\" }),\n *   });\n * } catch (error) {\n *   if (error instanceof DispatchRefusedError) {\n *     // `error.code` identifies the gate; canonical Task state remains authoritative.\n *   } else {\n *     throw error;\n *   }\n * }\n * ```\n */\nexport async function dispatchTask(\n  stores: DispatchStores,\n  input: DispatchTaskInput,\n): Promise<Task> {\n  const { taskId } = input;\n  const options: DispatchOptions = input;\n  const task = await stores.tasks.get(taskId);\n  if (task === null) {\n    throw new RecordNotFoundError(\"tasks\", taskId);\n  }\n  const route = task.work.route;\n  if (route !== undefined && options.workflowOwned === true) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `agent route ${routeKey(route)} requires a launcher`,\n    );\n  }\n  if (\n    route !== undefined &&\n    (options.route?.id !== route.id || options.route?.version !== route.version)\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `launch requires exact agent route ${routeKey(route)}`,\n    );\n  }\n  if (task.approval === \"required\") {\n    throw new DispatchRefusedError(taskId, \"awaiting_approval\", \"awaiting human approval\");\n  }\n  if (task.approval === \"denied\") {\n    throw new DispatchRefusedError(taskId, \"approval_denied\", \"approval was denied\");\n  }\n  if (\n    !(await stores.graphs.dependenciesSatisfied({\n      rootTaskId: task.rootTaskId,\n      taskId: task.id,\n    }))\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"dependencies_unsatisfied\",\n      \"graph dependencies must all be succeeded before dispatch\",\n    );\n  }\n\n  // The reservation gates queued -> running only; any other state falls\n  // through to the transition below, which rejects it as invalid.\n  let reservation: { reservedUsd: number; reservedAt: string } | undefined;\n  if (options.budget !== undefined && task.state === \"queued\") {\n    const budgetNow = (options.budget.now ?? (() => new Date()))().toISOString();\n    const month = options.budget.month ?? budgetMonthOf(budgetNow);\n    // This task's own retained reservation from a prior attempt is excluded,\n    // because re-reserving overwrites it. Its settled cost stays counted:\n    // that money was actually spent and a retry must not reopen it.\n    const rows = (\n      options.budget.enforce === false ? [] : (options.budget.tasks ?? (await stores.tasks.list()))\n    ).map((row) => (row.id === taskId ? { ...row, reservedUsd: undefined } : row));\n    const spendUsd = computeMonthSpendUsd(rows, month);\n    const { totalUsd, perTaskReservationUsd } = options.budget.limits;\n    if (options.budget.enforce !== false && !canReserve(spendUsd, options.budget.limits)) {\n      const reason = `budget exhausted: ${month} spend $${spendUsd} cannot fit a $${perTaskReservationUsd} reservation under $${totalUsd}`;\n      // Fail first, so BudgetExhaustedError's contract (task already failed)\n      // holds; losing the task to a concurrent dispatcher surfaces as a\n      // refusal, never as a false exhaustion with a misleading receipt.\n      try {\n        await stores.tasks.transition(taskId, \"failed\", { reason, expectFrom: \"queued\" });\n      } catch (error) {\n        if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) {\n          throw new DispatchRefusedError(\n            taskId,\n            \"dispatch_race\",\n            \"another dispatcher took the task\",\n          );\n        }\n        throw error;\n      }\n      // Best-effort: the failed transition above already wrote its own\n      // receipt carrying this reason, so losing this supplementary one\n      // cannot lose the evidence.\n      await stores.receipts\n        .append({\n          repositoryIds: task.repositoryIds,\n          taskId,\n          kind: task.kind,\n          state: \"reservation_refused\",\n          phase: \"budget\",\n          reason,\n          attempt: task.attempt,\n          dedupeKey: `task:${taskId}:reservation_refused:${task.attempt}`,\n        })\n        .catch(() => undefined);\n      throw new BudgetExhaustedError(taskId, month, spendUsd);\n    }\n    reservation = { reservedUsd: perTaskReservationUsd, reservedAt: budgetNow };\n  }\n\n  const running = await stores.tasks.transition(taskId, \"running\", {\n    expectFrom: \"queued\",\n    expectAttempt: task.attempt,\n    ...(reservation === undefined\n      ? {}\n      : {\n          patch: {\n            reservedUsd: reservation.reservedUsd,\n            reservedAt: reservation.reservedAt,\n          },\n        }),\n    ...(task.attempt > 1\n      ? { phase: options.continuationAttempt === task.attempt ? \"workflow\" : \"retry\" }\n      : {}),\n  });\n  if (options.workflowOwned === true) return running;\n  let execution: ExecutionReference;\n  try {\n    execution = await options.launch(running);\n  } catch (error) {\n    if (error instanceof ExecutionLaunchPendingError) throw error;\n    const reason = (error instanceof Error ? error.message : String(error)).slice(0, 500);\n    const limit = options.maxLaunchAttempts ?? DEFAULT_MAX_LAUNCH_ATTEMPTS;\n    if (running.attempt < limit) {\n      const retryReason = `launch failed (attempt ${running.attempt} of ${limit}), will retry: ${reason}`;\n      await stores.tasks\n        .transition(taskId, \"queued\", {\n          reason: retryReason,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    } else {\n      await stores.tasks\n        .transition(taskId, \"failed\", {\n          reason: `launch failed after ${running.attempt} attempts: ${reason}`,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    }\n    throw error;\n  }\n  // Surface a failed binding so a durable caller can recover the same launch;\n  // never report acceptance with an unrecorded or stale execution.\n  return stores.tasks.recordExecution(taskId, {\n    execution,\n    expectAttempt: running.attempt,\n  });\n}\n"],"mappings":"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"}

package/dist/eve/index.d.mts

@@ -108,18 +108,45 @@ interface AppendReceiptTool extends ToolDefinition<AppendReceiptToolInput, Recei
 }
 /** The provider-neutral Task, Signal, question, and Receipt tools exposed to an Eve agent. */
 interface TaskTools {
+  /** Read one Task by ID; applications decide which agents may expose this cross-Task lookup. */
   readonly get_task: GetTaskTool;
+  /** Record the one final decision for a pending Signal. */
   readonly decide_signal: DecideSignalTool;
+  /** Complete generic `task@1` work after authenticating the current Eve execution. */
   readonly finish_task: FinishTaskTool;
+  /** Persist and present one human question for the authenticated running Task. */
   readonly request_human_input: RequestHumanInputTool;
+  /** Answer a question only from its authenticated reply conversation. */
   readonly answer_question: AnswerQuestionTool;
+  /** Append immutable application audit evidence with optional deduplication. */
   readonly append_receipt: AppendReceiptTool;
 }
 /**
- * The factory's provider-neutral store operations wrapped as Eve tools. Expose a tool to an
- * agent by re-exporting it from a file under agent/tools/, e.g.
- * `export default createTaskTools(stores).get_task;`. Every write goes through
- * the engine, so agents inherit transition legality and receipts.
+ * Wraps provider-neutral Factory store operations as Eve tools.
+ *
+ * @remarks
+ * Expose only the returned tools each agent role needs. Every write goes through the validating
+ * engine, but tool visibility remains application authorization policy. `finish_task` and
+ * `request_human_input` recheck the current authenticated Task attempt and Eve session before
+ * mutating state. `get_task`, signal decisions, and generic receipts are broader capabilities and
+ * should be mounted only for agents allowed to use them.
+ *
+ * The generic `finish_task` records `{ summary }` for `task@1`. Schema-specific workflows should
+ * define a narrow tool that calls `requireTaskExecution` and `stores.work.completeWorkflow`, as in
+ * the shipped `docs/recipes/typed-eve-result.md` recipe.
+ *
+ * @param stores - Receipt, Signal, and Task capabilities available to the tool bundle.
+ * @param options - Optional question presentation and generic-completion policy.
+ * @returns A new named Eve tool bundle ready for selective mounting under `agent/tools/`.
+ *
+ * @example
+ * ```ts
+ * import { createTaskTools, type TaskToolsStores } from "@vercel/factory";
+ *
+ * declare const stores: TaskToolsStores;
+ * const tools = createTaskTools(stores);
+ * export default tools.get_task;
+ * ```
  */
 declare function createTaskTools(stores: TaskToolsStores, options?: TaskToolsOptions): TaskTools;
 /** Completed conversation output, or `false` when the Task is not a conversation. */
@@ -134,6 +161,11 @@ interface FactoryHooksOptions {
   taskAttemptAttribute?: string;
   /** Attempts allowed before an explicit provider failure becomes terminal. Default: 3. */
   maxAttempts?: number;
+  /**
+   * Recover a saved workflow result for the exact bound execution before failure retry or
+   * unresolved-turn escalation. Return true when handled; a throw defers generic lifecycle changes.
+   */
+  recoverResult?: (task: Task) => Promise<boolean>;
   /** Present the recovery question created when a task turn ends without an outcome. */
   presentQuestion: PresentQuestion;
   /** Classify discussion Tasks on failure or cancellation without collecting a successful response. */
@@ -150,30 +182,58 @@ type TranscriptSnapshotHook = HookDefinition<"session.waiting" | "session.comple
 type FactoryHookEvent = "step.completed" | "turn.failed" | "session.failed" | "session.waiting" | "session.completed" | "turn.cancelled" | "turn.completed";
 /** The Eve lifecycle hook projected onto durable Factory Task state. */
 interface FactoryHooks {
+  /** Hook definition to export from the target Eve agent's `hooks/` directory. */
   readonly factory: HookDefinition<FactoryHookEvent>;
 }
 /**
- * Observe-only eve hooks that keep the ledger honest about session outcomes.
- * Mount by re-exporting from agent/hooks/, e.g.
- * `export default createFactoryHooks(stores, { presentQuestion }).factory;`.
+ * Creates observe-only Eve hooks that project session outcomes onto durable Factory state.
  *
+ * @remarks
  * step.completed: records the step's tokens and AI Gateway cost on the bound
- * task. Delivery is at least once; recordUsage dedupes by (turnId, stepIndex).
+ * task. Delivery is at least once; recordUsage dedupes by (sessionId, turnId, stepIndex).
  *
- * turn.failed/session.failed: immediately re-queues the current attempt, or
+ * turn.failed/session.failed: first recovers an opted-in saved workflow result, then re-queues the current attempt, or
  * fails it when its configured attempts are exhausted. turn.cancelled marks
  * the current Task cancelled. Late events from prior attempts are ignored.
  *
- * turn.completed: settles the bound task's recorded usage if the task is
+ * turn.completed: recovers an opted-in saved workflow result before generic escalation, and
+ * settles the bound task's recorded usage if the task is
  * already terminal, and enforces the turn contract otherwise: a still-running
  * bound task (or a still-running task at this session's reply address, for
  * conversational continuations that never got their own bound session)
  * escalates immediately to a surfaced human question instead of waiting out
  * the stall window, because the agent finished without recording an outcome.
+ * When the bound session matches the persisted execution, that question's work input includes
+ * `systemReason: "unresolved_turn"` and `completedSessionId`. Application recovery can distinguish
+ * this completed execution from an agent's genuine request for human input.
  *
  * Every store call is swallowed: a hook throw fails the turn.
  * Transcript projection writes at session response boundaries are likewise
  * best-effort; the API can rebuild a missing projection from durable events.
+ *
+ * Export the returned `factory` hook from the target agent's `hooks/` directory. The hook reads
+ * the Task ID and attempt written by `withFactoryTask`; late events from replaced attempts cannot
+ * advance current work. Provider failure recovery requeues below `maxAttempts` and fails the Task
+ * at the limit. A clean turn that records no outcome creates a human question instead of silently
+ * retrying the same brief.
+ *
+ * @param stores - Task store used for usage, recovery, cancellation, and completion projection.
+ * @param options - Attempt limits plus application-owned question and conversation callbacks.
+ * @returns An Eve hook definition under the `factory` property.
+ * @see The shipped `docs/recipes/retry-recovery.md` recipe for bounded replacement attempts.
+ *
+ * @example
+ * ```ts
+ * import { createFactoryHooks, type FactoryHooksStores } from "@vercel/factory";
+ *
+ * declare const stores: FactoryHooksStores;
+ * const hooks = createFactoryHooks(stores, {
+ *   presentQuestion: async (questionTask) => {
+ *     // Deliver the persisted question through the application's operator channel.
+ *   },
+ * });
+ * export default hooks.factory;
+ * ```
  */
 declare function createFactoryHooks(stores: FactoryHooksStores, options: FactoryHooksOptions): FactoryHooks;
 //#endregion

package/dist/eve/index.mjs

@@ -1,9 +1,9 @@
 import { changeIdSchema, repositoryIdsSchema, signalIdSchema, taskIdSchema } from "../schema/id.mjs";
 import { taskWork } from "../schema/work.mjs";
 import { taskQuestionSchema } from "../schema/task.mjs";
-import { receiptKindSchema, receiptStateSchema } from "../schema/receipt.mjs";
 import { conversationBinding, conversationBindingForSession, conversationHeaders, factoryReplyAddressAttribute, factoryReplyAddressHeader, factoryReplyChannelAttribute, factoryReplyChannelHeader, factoryRepositoryIdsAttribute, factoryRepositoryIdsHeader, factoryTaskAttemptAttribute, factoryTaskAttemptHeader, factoryTaskAttribute, factoryTaskHeader, hasFactoryTaskBinding, optionalTaskIdForSession, replyToForSession, repositoryIdsForSession, requireTaskIdForSession, taskBindingForSession, taskHeaders, taskSessionAuth, withFactoryTask, withOptionalFactoryTask } from "./task-session.mjs";
 import { requireTaskExecution } from "./task-execution.mjs";
+import { receiptKindSchema, receiptStateSchema } from "../schema/receipt.mjs";
 import { createEveTranscriptMaterializer } from "./transcript.mjs";
 import { cancelEveSession, forwardEveSessionRequest, readCompletedEveTurn, startEveSession } from "./session-client.mjs";
 import { createDelegateAgentTool, createInvokeAgentTool } from "./invoke.mjs";
@@ -18,7 +18,7 @@ const decidedOutcomeSchema = z.enum([
 	"low_confidence",
 	"ignored"
 ]);
-async function createAndPresentQuestion(stores, parent, question, presentQuestion) {
+async function createAndPresentQuestion(stores, parent, question, presentQuestion, completedSessionId) {
 	const needsHumanAction = question.text.trim();
 	if (needsHumanAction === "") throw new Error("A human question must contain non-blank text.");
 	const task = await stores.tasks.create({
@@ -26,7 +26,13 @@ async function createAndPresentQuestion(stores, parent, question, presentQuestio
 		kind: "question",
 		work: taskWork({
 			title: needsHumanAction.slice(0, 256),
-			input: { question }
+			input: {
+				question,
+				...completedSessionId ? {
+					systemReason: "unresolved_turn",
+					completedSessionId
+				} : {}
+			}
 		}),
 		parentTaskId: parent.id,
 		parentTaskAttempt: parent.attempt,
@@ -68,10 +74,31 @@ async function createAndPresentQuestion(stores, parent, question, presentQuestio
 	}
 }
 /**
-* The factory's provider-neutral store operations wrapped as Eve tools. Expose a tool to an
-* agent by re-exporting it from a file under agent/tools/, e.g.
-* `export default createTaskTools(stores).get_task;`. Every write goes through
-* the engine, so agents inherit transition legality and receipts.
+* Wraps provider-neutral Factory store operations as Eve tools.
+*
+* @remarks
+* Expose only the returned tools each agent role needs. Every write goes through the validating
+* engine, but tool visibility remains application authorization policy. `finish_task` and
+* `request_human_input` recheck the current authenticated Task attempt and Eve session before
+* mutating state. `get_task`, signal decisions, and generic receipts are broader capabilities and
+* should be mounted only for agents allowed to use them.
+*
+* The generic `finish_task` records `{ summary }` for `task@1`. Schema-specific workflows should
+* define a narrow tool that calls `requireTaskExecution` and `stores.work.completeWorkflow`, as in
+* the shipped `docs/recipes/typed-eve-result.md` recipe.
+*
+* @param stores - Receipt, Signal, and Task capabilities available to the tool bundle.
+* @param options - Optional question presentation and generic-completion policy.
+* @returns A new named Eve tool bundle ready for selective mounting under `agent/tools/`.
+*
+* @example
+* ```ts
+* import { createTaskTools, type TaskToolsStores } from "@vercel/factory";
+*
+* declare const stores: TaskToolsStores;
+* const tools = createTaskTools(stores);
+* export default tools.get_task;
+* ```
 */
 function createTaskTools(stores, options = {}) {
 	return {
@@ -224,27 +251,54 @@ const UNRESOLVED_TURN_QUESTION = {
 	closingOptions: ["Close the task"]
 };
 /**
-* Observe-only eve hooks that keep the ledger honest about session outcomes.
-* Mount by re-exporting from agent/hooks/, e.g.
-* `export default createFactoryHooks(stores, { presentQuestion }).factory;`.
+* Creates observe-only Eve hooks that project session outcomes onto durable Factory state.
 *
+* @remarks
 * step.completed: records the step's tokens and AI Gateway cost on the bound
-* task. Delivery is at least once; recordUsage dedupes by (turnId, stepIndex).
+* task. Delivery is at least once; recordUsage dedupes by (sessionId, turnId, stepIndex).
 *
-* turn.failed/session.failed: immediately re-queues the current attempt, or
+* turn.failed/session.failed: first recovers an opted-in saved workflow result, then re-queues the current attempt, or
 * fails it when its configured attempts are exhausted. turn.cancelled marks
 * the current Task cancelled. Late events from prior attempts are ignored.
 *
-* turn.completed: settles the bound task's recorded usage if the task is
+* turn.completed: recovers an opted-in saved workflow result before generic escalation, and
+* settles the bound task's recorded usage if the task is
 * already terminal, and enforces the turn contract otherwise: a still-running
 * bound task (or a still-running task at this session's reply address, for
 * conversational continuations that never got their own bound session)
 * escalates immediately to a surfaced human question instead of waiting out
 * the stall window, because the agent finished without recording an outcome.
+* When the bound session matches the persisted execution, that question's work input includes
+* `systemReason: "unresolved_turn"` and `completedSessionId`. Application recovery can distinguish
+* this completed execution from an agent's genuine request for human input.
 *
 * Every store call is swallowed: a hook throw fails the turn.
 * Transcript projection writes at session response boundaries are likewise
 * best-effort; the API can rebuild a missing projection from durable events.
+*
+* Export the returned `factory` hook from the target agent's `hooks/` directory. The hook reads
+* the Task ID and attempt written by `withFactoryTask`; late events from replaced attempts cannot
+* advance current work. Provider failure recovery requeues below `maxAttempts` and fails the Task
+* at the limit. A clean turn that records no outcome creates a human question instead of silently
+* retrying the same brief.
+*
+* @param stores - Task store used for usage, recovery, cancellation, and completion projection.
+* @param options - Attempt limits plus application-owned question and conversation callbacks.
+* @returns An Eve hook definition under the `factory` property.
+* @see The shipped `docs/recipes/retry-recovery.md` recipe for bounded replacement attempts.
+*
+* @example
+* ```ts
+* import { createFactoryHooks, type FactoryHooksStores } from "@vercel/factory";
+*
+* declare const stores: FactoryHooksStores;
+* const hooks = createFactoryHooks(stores, {
+*   presentQuestion: async (questionTask) => {
+*     // Deliver the persisted question through the application's operator channel.
+*   },
+* });
+* export default hooks.factory;
+* ```
 */
 function createFactoryHooks(stores, options) {
 	const taskIdAttribute = options.taskIdAttribute ?? "factoryTaskId";
@@ -263,9 +317,19 @@ function createFactoryHooks(stores, options) {
 			attempt: attempt.data
 		} : void 0;
 	}
-	async function recoverFailedAttempt(binding, failure) {
+	async function recoverBoundResult(task, ctx) {
+		const binding = boundExecution(ctx);
+		if (binding?.taskId !== task.id || binding.attempt !== task.attempt || task.execution?.provider !== "eve" || task.execution.sessionId !== ctx.session.id) return false;
+		return await options.recoverResult?.(task) ?? false;
+	}
+	async function recoverFailedAttempt(binding, failure, ctx) {
 		const task = await stores.tasks.get(binding.taskId);
-		if (task?.state !== "running" || task.attempt !== binding.attempt) return;
+		if (!task || task.attempt !== binding.attempt || options.recoverResult && task.execution && (task.execution.provider !== "eve" || task.execution.sessionId !== ctx.session.id)) return;
+		if (await recoverBoundResult(task, ctx)) {
+			await settleIfTerminal(task.id);
+			return;
+		}
+		if (task.state !== "running") return;
 		const exhausted = task.attempt >= maxAttempts;
 		await stores.tasks.transition(task.id, exhausted ? "failed" : "queued", {
 			expectFrom: "running",
@@ -299,8 +363,8 @@ function createFactoryHooks(stores, options) {
 			reason: "measured usage settled at turn end"
 		});
 	}
-	async function escalateUnresolvedTurn(task) {
-		await createAndPresentQuestion(stores, task, UNRESOLVED_TURN_QUESTION, options.presentQuestion).catch(() => void 0);
+	async function escalateUnresolvedTurn(task, completedSessionId) {
+		await createAndPresentQuestion(stores, task, UNRESOLVED_TURN_QUESTION, options.presentQuestion, completedSessionId).catch(() => void 0);
 	}
 	return { factory: defineHook({ events: {
 		async "step.completed"(event, ctx) {
@@ -312,7 +376,7 @@ function createFactoryHooks(stores, options) {
 				if ((await stores.tasks.get(taskId).catch(() => null))?.attempt !== binding.attempt) return;
 			}
 			await stores.tasks.recordUsage(taskId, { step: {
-				turnId: event.data.turnId,
+				turnId: JSON.stringify([ctx.session.id, event.data.turnId]),
 				stepIndex: event.data.stepIndex,
 				...usage
 			} }).catch(() => void 0);
@@ -320,7 +384,7 @@ function createFactoryHooks(stores, options) {
 		async "turn.failed"(event, ctx) {
 			const binding = boundExecution(ctx);
 			if (binding !== void 0) {
-				await recoverFailedAttempt(binding, `provider turn failed (${event.data.code}): ${event.data.message}`).catch(() => void 0);
+				await recoverFailedAttempt(binding, `provider turn failed (${event.data.code}): ${event.data.message}`, ctx).catch(() => void 0);
 				return;
 			}
 			const taskId = boundTaskId(ctx);
@@ -335,7 +399,7 @@ function createFactoryHooks(stores, options) {
 		},
 		async "session.failed"(event, ctx) {
 			const binding = boundExecution(ctx);
-			if (binding !== void 0) await recoverFailedAttempt(binding, `provider session failed (${event.data.code}): ${event.data.message}`).catch(() => void 0);
+			if (binding !== void 0) await recoverFailedAttempt(binding, `provider session failed (${event.data.code}): ${event.data.message}`, ctx).catch(() => void 0);
 			await options.materializeTranscript?.(materializationInput(ctx)).catch(() => void 0);
 		},
 		async "session.waiting"(_event, ctx) {
@@ -366,7 +430,14 @@ function createFactoryHooks(stores, options) {
 			if (taskId !== void 0) {
 				const task = await stores.tasks.get(taskId).catch(() => null);
 				if (binding !== void 0 && task?.attempt !== binding.attempt) return;
-				if (task?.state === "running" && !task.waitingForMessages) {
+				if (binding && options.recoverResult && task?.execution && (task.execution.provider !== "eve" || task.execution.sessionId !== ctx.session.id)) return;
+				let recovered;
+				try {
+					recovered = task !== null && await recoverBoundResult(task, ctx);
+				} catch {
+					return;
+				}
+				if (!recovered && task?.state === "running" && !task.waitingForMessages) {
 					const completion = await options.completeConversation?.(task).catch(() => false);
 					if (completion) await stores.tasks.transition(taskId, "succeeded", {
 						expectFrom: "running",
@@ -374,7 +445,7 @@ function createFactoryHooks(stores, options) {
 						reason: "Conversation turn completed",
 						output: completion.output
 					}).catch(() => void 0);
-					else await escalateUnresolvedTurn(task);
+					else await escalateUnresolvedTurn(task, binding && task.execution?.provider === "eve" && task.execution.sessionId === ctx.session.id ? ctx.session.id : void 0);
 				}
 				await settleIfTerminal(taskId).catch(() => void 0);
 			}