@vercel/factory 0.0.12 → 0.0.13

package/dist/eve/index.d.mts

@@ -1,5 +1,5 @@
-import { A as FactoryStores, P as Task, c as Finding, t as ApprovalPolicy } from "../approval-CIXB8IF8.mjs";
-import { T as PullRequestReviewComment, b as GitHubReviewComment, j as SubmittedPullRequestReview } from "../github-wThBfbm-.mjs";
+import { H as FactoryStores, f as ApprovalPolicy, l as AgentRouteRegistry, r as DispatchBudget, s as AgentRoute, y as Finding, zt as Task } from "../dispatch-B77cuPxh.mjs";
+import { O as PullRequestReviewComment, P as SubmittedPullRequestReview, S as GitHubReviewComment } from "../github-DXsxboUL.mjs";
 import { z } from "zod";
 //#region src/eve/fetch.d.ts
 /** The subset of the eve sandbox handle a credentialed git operation needs. */
@@ -38,6 +38,10 @@ type FetchPullRequestResult = {
   prUrl: string;
   branch: string;
   headSha: string;
+  baseBranch: string;
+  baseSha: string;
+  mergeBaseSha: string;
+  diffCommand: string;
 };
 /**
  * The verifier's way in to the change under review. The sandbox has no
@@ -342,6 +346,19 @@ interface InvokeAgentOptions {
   token?: () => Promise<string | undefined>;
   /** Extra headers for the session request, e.g. a deployment protection bypass. */
   headers?: (task: Task) => Record<string, string> | Promise<Record<string, string>>;
+  /**
+   * Reserve-before-execution limits for the handoff dispatch, resolved at
+   * call time. Without it, handoff tasks run outside the budget.
+   */
+  budget?: () => DispatchBudget | undefined;
+  fetch?: typeof fetch;
+}
+interface DelegateAgentOptions {
+  routes: AgentRouteRegistry;
+  targetUrl: (route: AgentRoute) => string;
+  token?: (route: AgentRoute) => Promise<string | undefined>;
+  headers?: (task: Task, route: AgentRoute) => Record<string, string> | Promise<Record<string, string>>;
+  budget?: (route: AgentRoute) => DispatchBudget | undefined;
   fetch?: typeof fetch;
 }
 /**
@@ -362,7 +379,7 @@ declare function invokeAgentTool(stores: FactoryStores, options: InvokeAgentOpti
 }, {
   taskId: string;
   kind: string;
-  state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+  state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
 }> & {
   execute(input: {
     repositoryIds: string[];
@@ -374,23 +391,83 @@ declare function invokeAgentTool(stores: FactoryStores, options: InvokeAgentOpti
   }, ctx: import("eve/tools").ToolContext): Promise<{
     taskId: string;
     kind: string;
-    state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+  }>;
+};
+/**
+ * Give a conversational agent one bounded delegation surface backed by the
+ * application's route registry. The caller selects a declared route; trusted
+ * code owns task creation, budget enforcement, and the fresh target session.
+ */
+declare function delegateAgentTool(stores: FactoryStores, options: DelegateAgentOptions): import("eve/tools").ToolDefinition<{
+  routeId: string;
+  repositoryIds: string[];
+  channel: string;
+  address: string;
+  brief: string;
+  signalId?: string | undefined;
+  parentTaskId?: string | undefined;
+  changeId?: string | undefined;
+}, {
+  taskId: string;
+  childTaskIds: string[];
+  routeId: string;
+  agent: string;
+  state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+} | {
+  taskId: string;
+  routeId: string;
+  agent: string;
+  state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+  childTaskIds?: undefined;
+}> & {
+  execute(input: {
+    routeId: string;
+    repositoryIds: string[];
+    channel: string;
+    address: string;
+    brief: string;
+    signalId?: string | undefined;
+    parentTaskId?: string | undefined;
+    changeId?: string | undefined;
+  }, ctx: import("eve/tools").ToolContext): Promise<{
+    taskId: string;
+    childTaskIds: string[];
+    routeId: string;
+    agent: string;
+    state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+  } | {
+    taskId: string;
+    routeId: string;
+    agent: string;
+    state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    childTaskIds?: undefined;
   }>;
 };
 //#endregion
 //#region src/eve/post-review.d.ts
-interface PublishedReview {
+interface CompletedReview {
   taskId: string;
   changeId: string;
   repository: string;
+  pullRequestNumber: number;
   headSha: string;
   verdict: "approve" | "request_changes" | "comment";
   summary: string;
-  comments: readonly PullRequestReviewComment[];
+  comments: readonly CompletedReviewFinding[];
+}
+interface CompletedReviewFinding extends PullRequestReviewComment {
+  fingerprint: string;
+  key: string;
+  title: string;
+}
+interface PublishedReview extends CompletedReview {
   review: SubmittedPullRequestReview;
 }
 interface PostReviewToolOptions {
   tokenForRepository: (repository: string) => Promise<string>;
+  publishReviews?: boolean;
+  onCompleted?: (completed: CompletedReview) => Promise<void>;
   onPublished?: (published: PublishedReview) => Promise<void>;
   fetch?: typeof globalThis.fetch;
 }
@@ -408,18 +485,18 @@ declare function postReviewTool(stores: FactoryStores, options: PostReviewToolOp
     path: string;
     line: number;
     body: string;
+    key?: string | undefined;
+    title?: string | undefined;
   }[];
 }, {
   recorded: false;
   reason: string;
-  verdict?: undefined;
-  review?: undefined;
-  taskState?: undefined;
 } | {
+  taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+  review?: SubmittedPullRequestReview | undefined;
   recorded: true;
   verdict: "approve" | "request_changes" | "comment";
-  review: SubmittedPullRequestReview;
-  taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+  published: boolean;
   reason?: undefined;
 }> & {
   execute(input: {
@@ -432,18 +509,18 @@ declare function postReviewTool(stores: FactoryStores, options: PostReviewToolOp
       path: string;
       line: number;
       body: string;
+      key?: string | undefined;
+      title?: string | undefined;
     }[];
   }, ctx: import("eve/tools").ToolContext): Promise<{
     recorded: false;
     reason: string;
-    verdict?: undefined;
-    review?: undefined;
-    taskState?: undefined;
   } | {
+    taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    review?: SubmittedPullRequestReview | undefined;
     recorded: true;
     verdict: "approve" | "request_changes" | "comment";
-    review: SubmittedPullRequestReview;
-    taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    published: boolean;
     reason?: undefined;
   }>;
 };
@@ -521,6 +598,14 @@ declare function reviewCommentTools<S extends CommandSandbox>(stores: FactorySto
 };
 //#endregion
 //#region src/eve/verification.d.ts
+interface RecordVerificationOptions {
+  presentResult?: (input: {
+    taskId: string;
+    changeId: string;
+    verdict: "pass" | "fail";
+    summary: string;
+  }) => Promise<void>;
+}
 /**
  * The verifier's outcome tool. Writes evidence onto the change and moves it
  * to ready only when the verdict is pass; a failed verdict leaves the change
@@ -531,7 +616,7 @@ declare function reviewCommentTools<S extends CommandSandbox>(stores: FactorySto
  * as still in progress. Fail closed: the agent cannot mark a change ready
  * without supplying every evidence field.
  */
-declare function recordVerificationTool(stores: FactoryStores): import("eve/tools").ToolDefinition<{
+declare function recordVerificationTool(stores: FactoryStores, options?: RecordVerificationOptions): import("eve/tools").ToolDefinition<{
   taskId: string;
   changeId: string;
   verdict: "pass" | "fail";
@@ -555,7 +640,7 @@ declare function recordVerificationTool(stores: FactoryStores): import("eve/tool
   recorded: true;
   verdict: "pass" | "fail";
   changeState: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
-  taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+  taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
   reason?: undefined;
 }> & {
   execute(input: {
@@ -582,7 +667,7 @@ declare function recordVerificationTool(stores: FactoryStores): import("eve/tool
     recorded: true;
     verdict: "pass" | "fail";
     changeState: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
-    taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
     reason?: undefined;
   }>;
 };
@@ -619,7 +704,19 @@ interface FactoryToolsOptions {
    * Gates must fail closed: when they cannot verify, they refuse.
    */
   recordChangeGate?: (input: RecordChangeInput) => Promise<GateVerdict>;
+  /** Whether recorded code changes wait for an independent verification task. Default: required. */
+  verification?: "required" | "disabled";
+  /** Present the pull request after record_change persists its durable state. */
+  presentChange?: (input: {
+    taskId: string;
+    changeId: string;
+    verification: "required" | "disabled";
+    summary: string;
+  }) => Promise<void>;
+  /** Present a persisted human question through the application's Foreman communication boundary. */
+  presentQuestion?: (task: Task) => Promise<void>;
 }
+type PresentQuestion = NonNullable<FactoryToolsOptions["presentQuestion"]>;
 /**
  * The factory's store operations wrapped as eve tools. Expose a tool to an
  * agent by re-exporting it from a file under agent/tools/, e.g.
@@ -634,7 +731,7 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
     id: string;
     repositoryIds: string[];
     kind: string;
-    state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
     origin: {
       signalId?: string | undefined;
       parentTaskId?: string | undefined;
@@ -650,12 +747,26 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
     area?: string | undefined;
     approval?: "required" | "granted" | "denied" | undefined;
     dependsOn?: string[] | undefined;
-    devbox?: {
-      devboxId: string;
-      remoteId: string;
-      harness: string;
+    execution?: {
+      provider: string;
+      sessionId: string;
+      environmentId?: string | undefined;
+      harness?: string | undefined;
+      traceId?: string | undefined;
     } | undefined;
+    lastProgressAt?: string | undefined;
+    stalledAt?: string | undefined;
+    stalledReason?: string | undefined;
     reservedUsd?: number | undefined;
+    reservedAt?: string | undefined;
+    usage?: {
+      costUsd: number;
+      inputTokens: number;
+      outputTokens: number;
+      cacheReadTokens: number;
+      cacheWriteTokens: number;
+      steps: Record<string, number>;
+    } | undefined;
     settledUsd?: number | undefined;
     question?: {
       text: string;
@@ -676,7 +787,7 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       id: string;
       repositoryIds: string[];
       kind: string;
-      state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
       origin: {
         signalId?: string | undefined;
         parentTaskId?: string | undefined;
@@ -692,12 +803,26 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       area?: string | undefined;
       approval?: "required" | "granted" | "denied" | undefined;
       dependsOn?: string[] | undefined;
-      devbox?: {
-        devboxId: string;
-        remoteId: string;
-        harness: string;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
       } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
       reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
       settledUsd?: number | undefined;
       question?: {
         text: string;
@@ -796,7 +921,7 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       id: string;
       repositoryIds: string[];
       kind: string;
-      state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
       origin: {
         signalId?: string | undefined;
         parentTaskId?: string | undefined;
@@ -812,12 +937,26 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       area?: string | undefined;
       approval?: "required" | "granted" | "denied" | undefined;
       dependsOn?: string[] | undefined;
-      devbox?: {
-        devboxId: string;
-        remoteId: string;
-        harness: string;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
       } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
       reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
       settledUsd?: number | undefined;
       question?: {
         text: string;
@@ -868,7 +1007,7 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
         id: string;
         repositoryIds: string[];
         kind: string;
-        state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+        state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
         origin: {
           signalId?: string | undefined;
           parentTaskId?: string | undefined;
@@ -884,12 +1023,26 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
         area?: string | undefined;
         approval?: "required" | "granted" | "denied" | undefined;
         dependsOn?: string[] | undefined;
-        devbox?: {
-          devboxId: string;
-          remoteId: string;
-          harness: string;
+        execution?: {
+          provider: string;
+          sessionId: string;
+          environmentId?: string | undefined;
+          harness?: string | undefined;
+          traceId?: string | undefined;
         } | undefined;
+        lastProgressAt?: string | undefined;
+        stalledAt?: string | undefined;
+        stalledReason?: string | undefined;
         reservedUsd?: number | undefined;
+        reservedAt?: string | undefined;
+        usage?: {
+          costUsd: number;
+          inputTokens: number;
+          outputTokens: number;
+          cacheReadTokens: number;
+          cacheWriteTokens: number;
+          steps: Record<string, number>;
+        } | undefined;
         settledUsd?: number | undefined;
         question?: {
           text: string;
@@ -911,7 +1064,7 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
     taskState?: undefined;
   } | {
     finished: true;
-    taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
     reason?: undefined;
   }> & {
     execute(input: {
@@ -923,19 +1076,22 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       taskState?: undefined;
     } | {
       finished: true;
-      taskState: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
       reason?: undefined;
     }>;
   };
-  report_blocked: import("eve/tools").ToolDefinition<{
-    taskId: string;
-    reason: string;
+  request_human_input: import("eve/tools").ToolDefinition<{
+    parentTaskId: string;
+    question: {
+      text: string;
+      options: string[];
+    };
   }, {
     schemaVersion: 1;
     id: string;
     repositoryIds: string[];
     kind: string;
-    state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+    state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
     origin: {
       signalId?: string | undefined;
       parentTaskId?: string | undefined;
@@ -951,12 +1107,26 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
     area?: string | undefined;
     approval?: "required" | "granted" | "denied" | undefined;
     dependsOn?: string[] | undefined;
-    devbox?: {
-      devboxId: string;
-      remoteId: string;
-      harness: string;
+    execution?: {
+      provider: string;
+      sessionId: string;
+      environmentId?: string | undefined;
+      harness?: string | undefined;
+      traceId?: string | undefined;
     } | undefined;
+    lastProgressAt?: string | undefined;
+    stalledAt?: string | undefined;
+    stalledReason?: string | undefined;
     reservedUsd?: number | undefined;
+    reservedAt?: string | undefined;
+    usage?: {
+      costUsd: number;
+      inputTokens: number;
+      outputTokens: number;
+      cacheReadTokens: number;
+      cacheWriteTokens: number;
+      steps: Record<string, number>;
+    } | undefined;
     settledUsd?: number | undefined;
     question?: {
       text: string;
@@ -968,14 +1138,17 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
     reportRef?: string | undefined;
   }> & {
     execute(input: {
-      taskId: string;
-      reason: string;
+      parentTaskId: string;
+      question: {
+        text: string;
+        options: string[];
+      };
     }, ctx: import("eve/tools").ToolContext): Promise<{
       schemaVersion: 1;
       id: string;
       repositoryIds: string[];
       kind: string;
-      state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
       origin: {
         signalId?: string | undefined;
         parentTaskId?: string | undefined;
@@ -991,12 +1164,26 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       area?: string | undefined;
       approval?: "required" | "granted" | "denied" | undefined;
       dependsOn?: string[] | undefined;
-      devbox?: {
-        devboxId: string;
-        remoteId: string;
-        harness: string;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
       } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
       reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
       settledUsd?: number | undefined;
       question?: {
         text: string;
@@ -1008,67 +1195,120 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       reportRef?: string | undefined;
     }>;
   };
-  ask_question: import("eve/tools").ToolDefinition<{
-    repositoryIds: string[];
-    channel: string;
-    address: string;
-    question: {
-      text: string;
-      options: string[];
-    };
-    parentTaskId?: string | undefined;
+  answer_question: import("eve/tools").ToolDefinition<{
+    questionTaskId: string;
+    answer: string;
   }, {
-    schemaVersion: 1;
-    id: string;
-    repositoryIds: string[];
-    kind: string;
-    state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-    origin: {
-      signalId?: string | undefined;
-      parentTaskId?: string | undefined;
-      operator?: string | undefined;
-    };
-    replyTo: {
-      channel: string;
-      address: string;
-    };
-    attempt: number;
-    createdAt: string;
-    updatedAt: string;
-    area?: string | undefined;
-    approval?: "required" | "granted" | "denied" | undefined;
-    dependsOn?: string[] | undefined;
-    devbox?: {
-      devboxId: string;
-      remoteId: string;
-      harness: string;
-    } | undefined;
-    reservedUsd?: number | undefined;
-    settledUsd?: number | undefined;
-    question?: {
-      text: string;
-      options: string[];
-      answer?: string | undefined;
-      answeredBy?: string | undefined;
-    } | undefined;
-    changeId?: string | undefined;
-    reportRef?: string | undefined;
-  }> & {
-    execute(input: {
+    questionTask: {
+      schemaVersion: 1;
+      id: string;
       repositoryIds: string[];
-      channel: string;
-      address: string;
-      question: {
+      kind: string;
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      origin: {
+        signalId?: string | undefined;
+        parentTaskId?: string | undefined;
+        operator?: string | undefined;
+      };
+      replyTo: {
+        channel: string;
+        address: string;
+      };
+      attempt: number;
+      createdAt: string;
+      updatedAt: string;
+      area?: string | undefined;
+      approval?: "required" | "granted" | "denied" | undefined;
+      dependsOn?: string[] | undefined;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
+      } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
+      reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
+      settledUsd?: number | undefined;
+      question?: {
         text: string;
         options: string[];
+        answer?: string | undefined;
+        answeredBy?: string | undefined;
+      } | undefined;
+      changeId?: string | undefined;
+      reportRef?: string | undefined;
+    };
+    parentTask: null;
+  } | {
+    questionTask: {
+      schemaVersion: 1;
+      id: string;
+      repositoryIds: string[];
+      kind: string;
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      origin: {
+        signalId?: string | undefined;
+        parentTaskId?: string | undefined;
+        operator?: string | undefined;
       };
-      parentTaskId?: string | undefined;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
+      replyTo: {
+        channel: string;
+        address: string;
+      };
+      attempt: number;
+      createdAt: string;
+      updatedAt: string;
+      area?: string | undefined;
+      approval?: "required" | "granted" | "denied" | undefined;
+      dependsOn?: string[] | undefined;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
+      } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
+      reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
+      settledUsd?: number | undefined;
+      question?: {
+        text: string;
+        options: string[];
+        answer?: string | undefined;
+        answeredBy?: string | undefined;
+      } | undefined;
+      changeId?: string | undefined;
+      reportRef?: string | undefined;
+    };
+    parentTask: {
       schemaVersion: 1;
       id: string;
       repositoryIds: string[];
       kind: string;
-      state: "queued" | "running" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+      state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
       origin: {
         signalId?: string | undefined;
         parentTaskId?: string | undefined;
@@ -1084,12 +1324,26 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       area?: string | undefined;
       approval?: "required" | "granted" | "denied" | undefined;
       dependsOn?: string[] | undefined;
-      devbox?: {
-        devboxId: string;
-        remoteId: string;
-        harness: string;
+      execution?: {
+        provider: string;
+        sessionId: string;
+        environmentId?: string | undefined;
+        harness?: string | undefined;
+        traceId?: string | undefined;
       } | undefined;
+      lastProgressAt?: string | undefined;
+      stalledAt?: string | undefined;
+      stalledReason?: string | undefined;
       reservedUsd?: number | undefined;
+      reservedAt?: string | undefined;
+      usage?: {
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        steps: Record<string, number>;
+      } | undefined;
       settledUsd?: number | undefined;
       question?: {
         text: string;
@@ -1099,6 +1353,167 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
       } | undefined;
       changeId?: string | undefined;
       reportRef?: string | undefined;
+    };
+  }> & {
+    execute(input: {
+      questionTaskId: string;
+      answer: string;
+    }, ctx: import("eve/tools").ToolContext): Promise<{
+      questionTask: {
+        schemaVersion: 1;
+        id: string;
+        repositoryIds: string[];
+        kind: string;
+        state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+        origin: {
+          signalId?: string | undefined;
+          parentTaskId?: string | undefined;
+          operator?: string | undefined;
+        };
+        replyTo: {
+          channel: string;
+          address: string;
+        };
+        attempt: number;
+        createdAt: string;
+        updatedAt: string;
+        area?: string | undefined;
+        approval?: "required" | "granted" | "denied" | undefined;
+        dependsOn?: string[] | undefined;
+        execution?: {
+          provider: string;
+          sessionId: string;
+          environmentId?: string | undefined;
+          harness?: string | undefined;
+          traceId?: string | undefined;
+        } | undefined;
+        lastProgressAt?: string | undefined;
+        stalledAt?: string | undefined;
+        stalledReason?: string | undefined;
+        reservedUsd?: number | undefined;
+        reservedAt?: string | undefined;
+        usage?: {
+          costUsd: number;
+          inputTokens: number;
+          outputTokens: number;
+          cacheReadTokens: number;
+          cacheWriteTokens: number;
+          steps: Record<string, number>;
+        } | undefined;
+        settledUsd?: number | undefined;
+        question?: {
+          text: string;
+          options: string[];
+          answer?: string | undefined;
+          answeredBy?: string | undefined;
+        } | undefined;
+        changeId?: string | undefined;
+        reportRef?: string | undefined;
+      };
+      parentTask: null;
+    } | {
+      questionTask: {
+        schemaVersion: 1;
+        id: string;
+        repositoryIds: string[];
+        kind: string;
+        state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+        origin: {
+          signalId?: string | undefined;
+          parentTaskId?: string | undefined;
+          operator?: string | undefined;
+        };
+        replyTo: {
+          channel: string;
+          address: string;
+        };
+        attempt: number;
+        createdAt: string;
+        updatedAt: string;
+        area?: string | undefined;
+        approval?: "required" | "granted" | "denied" | undefined;
+        dependsOn?: string[] | undefined;
+        execution?: {
+          provider: string;
+          sessionId: string;
+          environmentId?: string | undefined;
+          harness?: string | undefined;
+          traceId?: string | undefined;
+        } | undefined;
+        lastProgressAt?: string | undefined;
+        stalledAt?: string | undefined;
+        stalledReason?: string | undefined;
+        reservedUsd?: number | undefined;
+        reservedAt?: string | undefined;
+        usage?: {
+          costUsd: number;
+          inputTokens: number;
+          outputTokens: number;
+          cacheReadTokens: number;
+          cacheWriteTokens: number;
+          steps: Record<string, number>;
+        } | undefined;
+        settledUsd?: number | undefined;
+        question?: {
+          text: string;
+          options: string[];
+          answer?: string | undefined;
+          answeredBy?: string | undefined;
+        } | undefined;
+        changeId?: string | undefined;
+        reportRef?: string | undefined;
+      };
+      parentTask: {
+        schemaVersion: 1;
+        id: string;
+        repositoryIds: string[];
+        kind: string;
+        state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
+        origin: {
+          signalId?: string | undefined;
+          parentTaskId?: string | undefined;
+          operator?: string | undefined;
+        };
+        replyTo: {
+          channel: string;
+          address: string;
+        };
+        attempt: number;
+        createdAt: string;
+        updatedAt: string;
+        area?: string | undefined;
+        approval?: "required" | "granted" | "denied" | undefined;
+        dependsOn?: string[] | undefined;
+        execution?: {
+          provider: string;
+          sessionId: string;
+          environmentId?: string | undefined;
+          harness?: string | undefined;
+          traceId?: string | undefined;
+        } | undefined;
+        lastProgressAt?: string | undefined;
+        stalledAt?: string | undefined;
+        stalledReason?: string | undefined;
+        reservedUsd?: number | undefined;
+        reservedAt?: string | undefined;
+        usage?: {
+          costUsd: number;
+          inputTokens: number;
+          outputTokens: number;
+          cacheReadTokens: number;
+          cacheWriteTokens: number;
+          steps: Record<string, number>;
+        } | undefined;
+        settledUsd?: number | undefined;
+        question?: {
+          text: string;
+          options: string[];
+          answer?: string | undefined;
+          answeredBy?: string | undefined;
+        } | undefined;
+        changeId?: string | undefined;
+        reportRef?: string | undefined;
+      };
     }>;
   };
   append_receipt: import("eve/tools").ToolDefinition<{
@@ -1154,20 +1569,31 @@ declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptio
   };
 };
 type FactoryTools = ReturnType<typeof factoryTools>;
+interface FactoryHooksOptions {
+  /** Session auth attribute naming the task a dispatched session works on. Default `factoryTaskId`. */
+  taskIdAttribute?: string;
+  /** Present the recovery question created when a task turn ends without an outcome. */
+  presentQuestion: PresentQuestion;
+}
 /**
  * Observe-only eve hooks that keep the ledger honest about session outcomes.
  * Mount by re-exporting from agent/hooks/, e.g.
- * `export default factoryHooks(stores).factory;`.
+ * `export default factoryHooks(stores, { presentQuestion }).factory;`.
+ *
+ * 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).
+ *
+ * turn.completed: settles the bound task's recorded usage if the task is
+ * already terminal (the sweep handles tasks that end later), then moves any
+ * still-running task at this session's reply address behind a surfaced human
+ * question, because the agent finished talking without recording an outcome.
  *
- * turn.completed: a turn that ends while its task is still running means the
- * agent finished talking without recording an outcome; the task moves to
- * needs_human instead of rotting. The task is found by the session's
- * channel address, which dispatch set from the task's replyTo.
+ * Every store call is swallowed: a hook throw fails the turn.
  */
-declare function factoryHooks(stores: FactoryStores): {
-  factory: import("eve/hooks").HookDefinition<"turn.completed">;
+declare function factoryHooks(stores: FactoryStores, options: FactoryHooksOptions): {
+  factory: import("eve/hooks").HookDefinition<"step.completed" | "turn.completed">;
 };
 type FactoryHooks = ReturnType<typeof factoryHooks>;
 //#endregion
-export { type CommandSandbox, type DeepsecScanOptions, FactoryHooks, FactoryTools, FactoryToolsOptions, type FetchPullRequestOptions, type FetchPullRequestResult, GateVerdict, type InvokeAgentOptions, type MergeConflictPayload, type MergeConflictToolOptions, type PostReviewToolOptions, type PublishedReview, RecordChangeInput, type RecordFindingOptions, type RecordFindingResult, type ReviewCommentToolOptions, deepsecScanTool, factoryHooks, factoryTools, fetchPullRequestTool, findingFromDeepsec, invokeAgentTool, mergeConflictPayloadSchema, mergeConflictTools, postReviewTool, recordFinding, recordFindingTool, recordVerificationTool, reviewCommentTools };
+export { type CommandSandbox, type CompletedReview, type CompletedReviewFinding, type DeepsecScanOptions, type DelegateAgentOptions, FactoryHooks, FactoryHooksOptions, FactoryTools, FactoryToolsOptions, type FetchPullRequestOptions, type FetchPullRequestResult, GateVerdict, type InvokeAgentOptions, type MergeConflictPayload, type MergeConflictToolOptions, type PostReviewToolOptions, type PublishedReview, RecordChangeInput, type RecordFindingOptions, type RecordFindingResult, type RecordVerificationOptions, type ReviewCommentToolOptions, deepsecScanTool, delegateAgentTool, factoryHooks, factoryTools, fetchPullRequestTool, findingFromDeepsec, invokeAgentTool, mergeConflictPayloadSchema, mergeConflictTools, postReviewTool, recordFinding, recordFindingTool, recordVerificationTool, reviewCommentTools };
 //# sourceMappingURL=index.d.mts.map