@vercel/factory 0.0.13 → 0.0.15

package/dist/eve/index.d.mts

@@ -1,1599 +1,181 @@
-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. */
-interface CommandSandbox {
-  run(options: {
-    command: string;
-  }): PromiseLike<{
-    stdout: string;
-    stderr?: string;
-    exitCode?: number;
-  }>;
+import { Signal, SignalOutcome } from "../schema/signal.mjs";
+import { ChangeId, RepositoryIds, SignalId, TaskId } from "../schema/id.mjs";
+import { JsonValue } from "../schema/work.mjs";
+import { Task, TaskQuestion } from "../schema/task.mjs";
+import { MaybePromise } from "../schema/common.mjs";
+import { Receipt, ReceiptKind, ReceiptState } from "../schema/receipt.mjs";
+import { AnswerQuestionResult, FactoryStores } from "../store/engine.mjs";
+import { EveTranscriptMaterializer, EveTranscriptMaterializerOptions, EveTranscriptRequestScope, TranscriptMaterializationInput, createEveTranscriptMaterializer } from "./transcript.mjs";
+import { ConversationBinding, FactoryConversationSessionBinding, 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 { CancelEveSessionOptions, EveSessionEvent, EveSessionStream, EveSessionStreamInput, ForwardEveSessionRequestOptions, ReadCompletedEveTurnOptions, StartEveSessionOptions, cancelEveSession, forwardEveSessionRequest, readCompletedEveTurn, startEveSession } from "./session-client.mjs";
+import { DelegateAgentLaunchInput, DelegateAgentTool, DelegateAgentToolInput, DelegateAgentToolOptions, DelegateAgentToolStores, DelegateWorkflowInput, DelegateWorkflowPolicy, DelegateWorkflowResult, InvokeAgentTool, InvokeAgentToolInput, InvokeAgentToolOptions, InvokeAgentToolResult, InvokeAgentToolStores, createDelegateAgentTool, createInvokeAgentTool } from "./invoke.mjs";
+import { HookDefinition } from "eve/hooks";
+import { ToolContext, ToolDefinition } from "eve/tools";
+//#region src/eve/index.d.ts
+/** Receipt, Signal, and Task capabilities used by the provider-neutral Eve tool bundle. */
+type TaskToolsStores = Pick<FactoryStores, "receipts" | "signals" | "tasks">;
+/** Task capability used to project Eve lifecycle events onto durable Factory state. */
+type FactoryHooksStores = Pick<FactoryStores, "tasks">;
+/** Configures the provider-neutral Task, signal, question, and receipt Eve tools. */
+interface TaskToolsOptions {
+  /** Present a persisted human question through the application's Foreman communication boundary. */
+  presentQuestion?: (task: Task) => Promise<void>;
+  /** Return a refusal reason when this task must use a more specific outcome tool. */
+  finishTaskPolicy?: (task: Task) => MaybePromise<string | null>;
 }
-interface FetchPullRequestOptions<S extends CommandSandbox = CommandSandbox> {
-  /**
-   * Runs one git command against `slug` with a credential the sandbox does not
-   * otherwise have, and removes it again before resolving. Supplied by the
-   * app, which owns how credentials are minted and where they are injected;
-   * the library only decides what is fetched.
-   */
-  withCredential: (sandbox: S, slug: string, command: string) => Promise<{
-    stdout: string;
-    stderr?: string;
-    exitCode?: number;
-  }>;
-  /** Path of the checkout inside the sandbox. Defaults to `repo`. */
-  repoPath?: string;
-  /** Fetch depth for the pull request head. Defaults to 50. */
-  depth?: number;
+/** Delivers a persisted human-question Task through an application-owned channel. */
+type PresentQuestion = NonNullable<TaskToolsOptions["presentQuestion"]>;
+/** Identifies the Task to read through the provider-neutral task tool. */
+interface GetTaskToolInput {
+  taskId: TaskId;
 }
-type FetchPullRequestResult = {
-  fetched: false;
-  reason: string;
-} | {
-  fetched: true;
-  prNumber: number;
-  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
- * GitHub credential while the agent runs, so trusted code does the one fetch
- * the agent cannot: the pull request number and repository come from the
- * change record, never from the agent, and the credential is gone again
- * before control returns. Mirrors how publication reads commits out of the
- * sandbox instead of letting the agent push.
- */
-declare function fetchPullRequestTool<S extends CommandSandbox>(stores: FactoryStores, options: FetchPullRequestOptions<S>): import("eve/tools").ToolDefinition<{
-  changeId: string;
-}, FetchPullRequestResult> & {
-  execute(input: {
-    changeId: string;
-  }, ctx: import("eve/tools").ToolContext): Promise<FetchPullRequestResult>;
-};
-//#endregion
-//#region src/eve/conflict.d.ts
-declare const mergeConflictPayloadSchema: z.ZodObject<{
-  repository: z.ZodString;
-  prNumber: z.ZodNumber;
-  prUrl: z.ZodURL;
-  headBranch: z.ZodString;
-  headSha: z.ZodString;
-  baseBranch: z.ZodString;
-  baseSha: z.ZodString;
-}, z.core.$strict>;
-type MergeConflictPayload = z.infer<typeof mergeConflictPayloadSchema>;
-interface MergeConflictToolOptions<S extends CommandSandbox = CommandSandbox> {
-  withCredential: (sandbox: S, repository: string, command: string) => Promise<{
-    stdout: string;
-    stderr?: string;
-    exitCode?: number;
-  }>;
-  repoPath?: string;
-}
-declare function mergeConflictTools<S extends CommandSandbox>(stores: FactoryStores, options: MergeConflictToolOptions<S>): {
-  fetch_merge_conflict: import("eve/tools").ToolDefinition<{
-    taskId: string;
-  }, {
-    conflictedFiles: string[];
-    repository: string;
-    prNumber: number;
-    prUrl: string;
-    headBranch: string;
-    headSha: string;
-    baseBranch: string;
-    baseSha: string;
-  }> & {
-    execute(input: {
-      taskId: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      conflictedFiles: string[];
-      repository: string;
-      prNumber: number;
-      prUrl: string;
-      headBranch: string;
-      headSha: string;
-      baseBranch: string;
-      baseSha: string;
-    }>;
-  };
-  publish_merge_resolution: import("eve/tools").ToolDefinition<{
-    taskId: string;
-    summary: string;
-  }, {
-    updated: true;
-    prNumber: number;
-    prUrl: string;
-  }> & {
-    execute(input: {
-      taskId: string;
-      summary: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      updated: true;
-      prNumber: number;
-      prUrl: string;
-    }>;
-  };
-};
-//#endregion
-//#region src/eve/finding.d.ts
-interface RecordFindingOptions {
-  /** Signal source the findings are recorded under. Defaults to security_scan. */
-  source?: string;
-  /** Which resulting tasks wait for a human. Defaults to the standard policy. */
-  approval?: ApprovalPolicy;
+/** Explicit not-found result returned when a requested Task does not exist. */
+interface TaskNotFoundResult {
+  readonly found: false;
+  readonly taskId: TaskId;
 }
-type RecordFindingResult = {
-  recorded: false;
-  reason: string;
-  duplicate?: true;
-  signalId?: string;
-} | {
-  recorded: true;
-  signalId: string;
-  taskId: string;
-  approval: "required" | "not_required";
-};
-/**
- * Turn one finding into a signal and a fix task. The fingerprint is the
- * signal's delivery id, so the same problem reported twice is a no-op. The
- * signal is accepted on the reporter's own verification (a human gate follows
- * when the approval policy says so), and the task carries the approval
- * decision from the moment it exists. Shared by record_finding and scanner
- * tools that record on the agent's behalf.
- */
-declare function recordFinding(stores: FactoryStores, repositoryId: string, finding: Finding, options?: RecordFindingOptions): Promise<RecordFindingResult>;
-/**
- * The scanner's outcome tool: turns one finding into a signal and a fix task
- * in a single deterministic step. The finding's fingerprint is the signal's
- * delivery id, so reporting the same problem twice is a no-op. The signal is
- * accepted on the reporter's own verification (a human gate follows when the
- * approval policy says so), and the task carries the approval decision from
- * the moment it exists.
- */
-declare function recordFindingTool(stores: FactoryStores, options?: RecordFindingOptions): import("eve/tools").ToolDefinition<{
-  repositoryId: string;
-  finding: {
-    title: string;
-    body: string;
-    priority: "P0" | "P1" | "P2" | "P3";
-    category: "security" | "correctness" | "reliability" | "performance" | "compatibility" | "accessibility" | "documentation" | "maintainability" | "testing" | "usability";
-    verification: {
-      level: "unverified" | "supported" | "confirmed";
-      method: "documentation" | "code_inspection" | "static_analysis" | "manual_reproduction" | "unit_test" | "integration_test" | "e2e_test" | "runtime_observation";
-      summary: string;
-      limitations?: string | undefined;
-    };
-    path?: string | undefined;
-    line?: number | undefined;
-    endLine?: number | undefined;
-    tool?: string | undefined;
-    ruleId?: string | undefined;
-  };
-}, RecordFindingResult> & {
-  execute(input: {
-    repositoryId: string;
-    finding: {
-      title: string;
-      body: string;
-      priority: "P0" | "P1" | "P2" | "P3";
-      category: "security" | "correctness" | "reliability" | "performance" | "compatibility" | "accessibility" | "documentation" | "maintainability" | "testing" | "usability";
-      verification: {
-        level: "unverified" | "supported" | "confirmed";
-        method: "documentation" | "code_inspection" | "static_analysis" | "manual_reproduction" | "unit_test" | "integration_test" | "e2e_test" | "runtime_observation";
-        summary: string;
-        limitations?: string | undefined;
-      };
-      path?: string | undefined;
-      line?: number | undefined;
-      endLine?: number | undefined;
-      tool?: string | undefined;
-      ruleId?: string | undefined;
-    };
-  }, ctx: import("eve/tools").ToolContext): Promise<RecordFindingResult>;
-};
-//#endregion
-//#region src/eve/deepsec.d.ts
-interface DeepsecScanOptions<S extends CommandSandbox = CommandSandbox> extends RecordFindingOptions {
-  /**
-   * Runs one shell command with the model credential deepsec's gateway route
-   * expects, and removes it again before resolving. Supplied by the app, which
-   * owns where the credential comes from: on Vercel it is the deployment's own
-   * OIDC identity (VERCEL_OIDC_TOKEN), so nothing has to be configured.
-   */
-  withModelCredential: (sandbox: S, command: string) => Promise<{
-    stdout: string;
-    stderr?: string;
-    exitCode?: number;
-  }>;
-  /** deepsec agent backend: claude, codex, or pi. */
-  agent?: "claude" | "codex" | "pi";
-  /** Model deepsec's investigation agent uses, through the AI Gateway (e.g. claude-sonnet-4-6). */
-  model?: string;
-  /** Reasoning effort for the investigation: minimal, low, medium, high, or xhigh. */
-  thinkingLevel?: "minimal" | "low" | "medium" | "high" | "xhigh";
-  /** Parallel investigation batches. */
-  concurrency?: number;
-  /** deepsec version to install. */
-  version?: string;
-  /** Repository checkout inside the sandbox. Defaults to `repo`. */
-  repoPath?: string;
-  /** deepsec workspace inside the sandbox. Defaults to `deepsec`. */
-  workspacePath?: string;
-  /** Shell run before every deepsec command, e.g. to put a Node 24 on PATH. */
-  commandPrefix?: string;
-  /**
-   * Candidate files investigated per run. deepsec keeps state, so successive
-   * scans continue where the last one stopped; the cap keeps one run inside
-   * the deployment's time limit on large repositories. Defaults to 40.
-   */
-  filesPerRun?: number;
+/** Existing Task or explicit not-found result returned by the task lookup tool. */
+type GetTaskToolResult = Task | TaskNotFoundResult;
+/** Provider-neutral Eve tool for reading one Factory Task. */
+interface GetTaskTool extends ToolDefinition<GetTaskToolInput, GetTaskToolResult> {
+  execute(input: GetTaskToolInput, ctx: ToolContext): Promise<GetTaskToolResult>;
 }
-/** deepsec's exported finding shape, as far as we depend on it. */
-declare const deepsecFindingSchema: z.ZodObject<{
-  title: z.ZodString;
-  description: z.ZodString;
-  severity: z.ZodString;
-  metadata: z.ZodOptional<z.ZodObject<{
-    filePath: z.ZodOptional<z.ZodString>;
-    lineNumbers: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
-    vulnSlug: z.ZodOptional<z.ZodString>;
-    confidence: z.ZodOptional<z.ZodString>;
-    runId: z.ZodOptional<z.ZodString>;
-  }, z.core.$loose>>;
-}, z.core.$loose>;
-/** Convert one deepsec finding into the factory's Finding. Pure; exported for tests. */
-declare function findingFromDeepsec(raw: z.infer<typeof deepsecFindingSchema>): Finding;
-/**
- * Runs deepsec (vercel-labs/deepsec) against the sandbox checkout and records
- * what it finds through the same path as record_finding, so every deepsec
- * finding becomes a fix task subject to the approval policy. Trusted code
- * owns the command sequence and the credential; the agent chooses when to
- * scan and reports the outcome.
- */
-declare function deepsecScanTool<S extends CommandSandbox>(stores: FactoryStores, options: DeepsecScanOptions<S>): import("eve/tools").ToolDefinition<{
-  repositoryId: string;
-  limit?: number | undefined;
-}, {
-  scanned: false;
+/** One final triage decision submitted for a pending Signal. */
+interface DecideSignalToolInput {
+  signalId: SignalId;
+  outcome: Exclude<SignalOutcome, "pending">;
   reason: string;
-  tool?: undefined;
-  found?: undefined;
-  recorded?: undefined;
-  duplicates?: undefined;
-  awaitingApproval?: undefined;
-  findings?: undefined;
-} | {
-  scanned: true;
-  tool: string;
-  found: number;
-  recorded: number;
-  duplicates: number;
-  awaitingApproval: number;
-  findings: ({
-    taskId: string;
-    approval: "required" | "not_required";
-    title: string;
-    priority: "P0" | "P1" | "P2" | "P3";
-    path: string | undefined;
-    line: number | undefined;
-  } | {
-    duplicate: boolean;
-    title: string;
-    priority: "P0" | "P1" | "P2" | "P3";
-    path: string | undefined;
-    line: number | undefined;
-  })[];
-  reason?: undefined;
-}> & {
-  execute(input: {
-    repositoryId: string;
-    limit?: number | undefined;
-  }, ctx: import("eve/tools").ToolContext): Promise<{
-    scanned: false;
-    reason: string;
-    tool?: undefined;
-    found?: undefined;
-    recorded?: undefined;
-    duplicates?: undefined;
-    awaitingApproval?: undefined;
-    findings?: undefined;
-  } | {
-    scanned: true;
-    tool: string;
-    found: number;
-    recorded: number;
-    duplicates: number;
-    awaitingApproval: number;
-    findings: ({
-      taskId: string;
-      approval: "required" | "not_required";
-      title: string;
-      priority: "P0" | "P1" | "P2" | "P3";
-      path: string | undefined;
-      line: number | undefined;
-    } | {
-      duplicate: boolean;
-      title: string;
-      priority: "P0" | "P1" | "P2" | "P3";
-      path: string | undefined;
-      line: number | undefined;
-    })[];
-    reason?: undefined;
-  }>;
-};
-//#endregion
-//#region src/eve/invoke.d.ts
-interface InvokeAgentOptions {
-  /** The factory task kind the handoff creates, e.g. "verification". */
-  kind: string;
-  /** Model-facing description of what the target agent does and when to invoke it. */
-  description: string;
-  /**
-   * Base URL of the target agent's eve transport, e.g.
-   * `https://factory.example.com/eve/agents/verifier`. Resolved at call time so
-   * a deployment can derive it from its own origin.
-   */
-  targetUrl: () => string;
-  /** Bearer token for the target agent's eve channel, when it requires auth. */
-  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;
+  detail?: string;
 }
-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;
+/** Provider-neutral Eve tool for recording a Signal decision. */
+interface DecideSignalTool extends ToolDefinition<DecideSignalToolInput, Signal> {
+  execute(input: DecideSignalToolInput, ctx: ToolContext): Promise<Signal>;
 }
-/**
- * A tool that lets one agent hand work to another, NMA-style: the caller
- * decides to invoke; trusted code owns the how. The handoff is recorded as a
- * factory task (single-winner dispatch, receipts), then a fresh session is
- * started on the target agent carrying only the task id — never the caller's
- * context. The session start is create-once on the task id, so a retried
- * tool call cannot start a second session.
- */
-declare function invokeAgentTool(stores: FactoryStores, options: InvokeAgentOptions): import("eve/tools").ToolDefinition<{
-  repositoryIds: string[];
-  channel: string;
-  address: string;
-  brief: string;
-  parentTaskId?: string | undefined;
-  changeId?: string | undefined;
-}, {
-  taskId: string;
-  kind: string;
-  state: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-}> & {
-  execute(input: {
-    repositoryIds: string[];
-    channel: string;
-    address: string;
-    brief: string;
-    parentTaskId?: string | undefined;
-    changeId?: string | undefined;
-  }, ctx: import("eve/tools").ToolContext): Promise<{
-    taskId: string;
-    kind: string;
-    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 CompletedReview {
-  taskId: string;
-  changeId: string;
-  repository: string;
-  pullRequestNumber: number;
-  headSha: string;
-  verdict: "approve" | "request_changes" | "comment";
+/** Running Task and summary supplied to the generic completion tool. */
+interface FinishTaskToolInput {
+  taskId: TaskId;
   summary: string;
-  comments: readonly CompletedReviewFinding[];
 }
-interface CompletedReviewFinding extends PullRequestReviewComment {
-  fingerprint: string;
-  key: string;
-  title: string;
+/** Successful generic Task completion. */
+interface FinishTaskSuccess {
+  readonly finished: true;
+  readonly taskState: "succeeded";
 }
-interface PublishedReview extends CompletedReview {
-  review: SubmittedPullRequestReview;
+/** Policy or lifecycle refusal returned by the generic Task completion tool. */
+interface FinishTaskRefusal {
+  readonly finished: false;
+  readonly reason: string;
 }
-interface PostReviewToolOptions {
-  tokenForRepository: (repository: string) => Promise<string>;
-  publishReviews?: boolean;
-  onCompleted?: (completed: CompletedReview) => Promise<void>;
-  onPublished?: (published: PublishedReview) => Promise<void>;
-  fetch?: typeof globalThis.fetch;
+/** Completion or bounded refusal returned by the generic Task completion tool. */
+type FinishTaskToolResult = FinishTaskSuccess | FinishTaskRefusal;
+/** Provider-neutral Eve tool for completing a running Task. */
+interface FinishTaskTool extends ToolDefinition<FinishTaskToolInput, FinishTaskToolResult> {
+  execute(input: FinishTaskToolInput, ctx: ToolContext): Promise<FinishTaskToolResult>;
 }
-/**
- * Publish an independent review of an existing pull request and finish the
- * review task without changing the pull request's factory lifecycle.
- */
-declare function postReviewTool(stores: FactoryStores, options: PostReviewToolOptions): import("eve/tools").ToolDefinition<{
-  taskId: string;
-  changeId: string;
-  verdict: "approve" | "request_changes" | "comment";
-  headSha: string;
-  summary: string;
-  comments: {
-    path: string;
-    line: number;
-    body: string;
-    key?: string | undefined;
-    title?: string | undefined;
-  }[];
-}, {
-  recorded: false;
-  reason: string;
-} | {
-  taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-  review?: SubmittedPullRequestReview | undefined;
-  recorded: true;
-  verdict: "approve" | "request_changes" | "comment";
-  published: boolean;
-  reason?: undefined;
-}> & {
-  execute(input: {
-    taskId: string;
-    changeId: string;
-    verdict: "approve" | "request_changes" | "comment";
-    headSha: string;
-    summary: string;
-    comments: {
-      path: string;
-      line: number;
-      body: string;
-      key?: string | undefined;
-      title?: string | undefined;
-    }[];
-  }, ctx: import("eve/tools").ToolContext): Promise<{
-    recorded: false;
-    reason: string;
-  } | {
-    taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-    review?: SubmittedPullRequestReview | undefined;
-    recorded: true;
-    verdict: "approve" | "request_changes" | "comment";
-    published: boolean;
-    reason?: undefined;
-  }>;
-};
-//#endregion
-//#region src/eve/review.d.ts
-interface ReviewCommentToolOptions<S extends CommandSandbox = CommandSandbox> {
-  tokenForRepository: (repository: string) => Promise<string>;
-  withCredential?: (sandbox: S, repository: string, command: string) => Promise<{
-    stdout: string;
-    stderr?: string;
-    exitCode?: number;
-  }>;
-  fetch?: typeof globalThis.fetch;
-  repoPath?: string;
+/** Unanswered question shape accepted when a Task requests human input. */
+type HumanInputQuestion = Omit<TaskQuestion, "answer" | "answeredBy">;
+/** Currently running parent Task and its single human question for this execution. */
+interface RequestHumanInputToolInput {
+  parentTaskId: TaskId;
+  question: HumanInputQuestion;
 }
-declare function reviewCommentTools<S extends CommandSandbox>(stores: FactoryStores, options: ReviewCommentToolOptions<S>): {
-  read_review_comment: import("eve/tools").ToolDefinition<{
-    changeId: string;
-    commentId: number;
-  }, GitHubReviewComment> & {
-    execute(input: {
-      changeId: string;
-      commentId: number;
-    }, ctx: import("eve/tools").ToolContext): Promise<GitHubReviewComment>;
-  };
-  answer_review_comment: import("eve/tools").ToolDefinition<{
-    changeId: string;
-    commentId: number;
-    body: string;
-  }, GitHubReviewComment> & {
-    execute(input: {
-      changeId: string;
-      commentId: number;
-      body: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<GitHubReviewComment>;
-  };
-  suggest_review_fix: import("eve/tools").ToolDefinition<{
-    changeId: string;
-    commentId: number;
-    confidence: "medium";
-    replacement: string;
-    summary: string;
-  }, GitHubReviewComment> & {
-    execute(input: {
-      changeId: string;
-      commentId: number;
-      confidence: "medium";
-      replacement: string;
-      summary: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<GitHubReviewComment>;
-  };
-  apply_review_fix: import("eve/tools").ToolDefinition<{
-    changeId: string;
-    commentId: number;
-    confidence: "high";
-    summary: string;
-  }, {
-    updated: true;
-    prNumber: number;
-    prUrl: string;
-    reply: GitHubReviewComment;
-  }> & {
-    execute(input: {
-      changeId: string;
-      commentId: number;
-      confidence: "high";
-      summary: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      updated: true;
-      prNumber: number;
-      prUrl: string;
-      reply: GitHubReviewComment;
-    }>;
-  };
-};
-//#endregion
-//#region src/eve/verification.d.ts
-interface RecordVerificationOptions {
-  presentResult?: (input: {
-    taskId: string;
-    changeId: string;
-    verdict: "pass" | "fail";
-    summary: string;
-  }) => Promise<void>;
+/** Provider-neutral Eve tool for pausing one running execution on one persisted human question. */
+interface RequestHumanInputTool extends ToolDefinition<RequestHumanInputToolInput, Task> {
+  execute(input: RequestHumanInputToolInput, ctx: ToolContext): Promise<Task>;
 }
-/**
- * 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
- * verifying with the evidence recorded, and the verification task itself
- * ends with a receipt either way. The change's own code_change task follows
- * the verdict too: succeeded on pass, failed on fail with the verifier's
- * summary as the reason, so the ledger never shows a verified-and-rejected fix
- * as still in progress. Fail closed: the agent cannot mark a change ready
- * without supplying every evidence field.
- */
-declare function recordVerificationTool(stores: FactoryStores, options?: RecordVerificationOptions): import("eve/tools").ToolDefinition<{
-  taskId: string;
-  changeId: string;
-  verdict: "pass" | "fail";
-  evidence: {
-    reproVerified: boolean;
-    testsAdded: number;
-    checksGreen: boolean;
-    attackPassed: boolean;
-    scopeMatches: boolean;
-    previewUrl?: string | undefined;
-  };
-  confidence: "low" | "medium" | "high";
-  summary: string;
-}, {
-  recorded: false;
-  reason: string;
-  verdict?: undefined;
-  changeState?: undefined;
-  taskState?: undefined;
-} | {
-  recorded: true;
-  verdict: "pass" | "fail";
-  changeState: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
-  taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-  reason?: undefined;
-}> & {
-  execute(input: {
-    taskId: string;
-    changeId: string;
-    verdict: "pass" | "fail";
-    evidence: {
-      reproVerified: boolean;
-      testsAdded: number;
-      checksGreen: boolean;
-      attackPassed: boolean;
-      scopeMatches: boolean;
-      previewUrl?: string | undefined;
-    };
-    confidence: "low" | "medium" | "high";
-    summary: string;
-  }, ctx: import("eve/tools").ToolContext): Promise<{
-    recorded: false;
-    reason: string;
-    verdict?: undefined;
-    changeState?: undefined;
-    taskState?: undefined;
-  } | {
-    recorded: true;
-    verdict: "pass" | "fail";
-    changeState: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
-    taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-    reason?: undefined;
-  }>;
-};
-//#endregion
-//#region src/eve/index.d.ts
-declare const recordChangeInputSchema: z.ZodObject<{
-  taskId: z.ZodString;
-  repositoryId: z.ZodString;
-  prNumber: z.ZodNumber;
-  prUrl: z.ZodURL;
-  risk: z.ZodEnum<{
-    low: "low";
-    medium: "medium";
-    high: "high";
-  }>;
-  confidence: z.ZodEnum<{
-    low: "low";
-    medium: "medium";
-    high: "high";
-  }>;
-  summary: z.ZodString;
-}, z.core.$strip>;
-type RecordChangeInput = z.infer<typeof recordChangeInputSchema>;
-type GateVerdict = {
-  ok: true;
-} | {
-  ok: false;
-  reason: string;
-};
-interface FactoryToolsOptions {
-  /**
-   * Pre-action gate for record_change, run as an eve approval policy before
-   * the tool executes. Refusals reach the model as a denial with the reason.
-   * 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>;
+/** Question Task and authenticated answer supplied to the answer tool. */
+interface AnswerQuestionToolInput {
+  questionTaskId: TaskId;
+  answer: string;
+}
+/** Provider-neutral Eve tool for answering a persisted human question. */
+interface AnswerQuestionTool extends ToolDefinition<AnswerQuestionToolInput, AnswerQuestionResult> {
+  execute(input: AnswerQuestionToolInput, ctx: ToolContext): Promise<AnswerQuestionResult>;
+}
+/** Immutable audit event accepted by the generic receipt tool. */
+interface AppendReceiptToolInput {
+  repositoryIds: RepositoryIds;
+  taskId?: TaskId;
+  changeId?: ChangeId;
+  kind: ReceiptKind;
+  state: ReceiptState;
+  reason?: string;
+  dedupeKey?: string;
+}
+/** Provider-neutral Eve tool for appending one immutable audit Receipt. */
+interface AppendReceiptTool extends ToolDefinition<AppendReceiptToolInput, Receipt> {
+  execute(input: AppendReceiptToolInput, ctx: ToolContext): Promise<Receipt>;
+}
+/** The provider-neutral Task, Signal, question, and Receipt tools exposed to an Eve agent. */
+interface TaskTools {
+  readonly get_task: GetTaskTool;
+  readonly decide_signal: DecideSignalTool;
+  readonly finish_task: FinishTaskTool;
+  readonly request_human_input: RequestHumanInputTool;
+  readonly answer_question: AnswerQuestionTool;
+  readonly append_receipt: AppendReceiptTool;
 }
-type PresentQuestion = NonNullable<FactoryToolsOptions["presentQuestion"]>;
 /**
- * The factory's store operations wrapped as eve tools. Expose a tool to an
+ * 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 factoryTools(stores).get_task;`. Every write goes through
+ * `export default createTaskTools(stores).get_task;`. Every write goes through
  * the engine, so agents inherit transition legality and receipts.
  */
-declare function factoryTools(stores: FactoryStores, options?: FactoryToolsOptions): {
-  get_task: import("eve/tools").ToolDefinition<{
-    taskId: string;
-  }, {
-    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;
-  } | {
-    found: false;
-    taskId: string;
-  }> & {
-    execute(input: {
-      taskId: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      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;
-    } | {
-      found: false;
-      taskId: string;
-    }>;
-  };
-  decide_signal: import("eve/tools").ToolDefinition<{
-    signalId: string;
-    outcome: "accepted" | "duplicate" | "unactionable" | "low_confidence" | "ignored";
-    reason: string;
-    detail?: string | undefined;
-  }, {
-    schemaVersion: 1;
-    id: string;
-    repositoryId: string;
-    source: string;
-    deliveryId: string;
-    replyTo: {
-      channel: string;
-      address: string;
-    };
-    payload: unknown;
-    receivedAt: string;
-    outcome: "accepted" | "duplicate" | "unactionable" | "low_confidence" | "ignored" | "pending";
-    detail?: string | undefined;
-    reason?: string | undefined;
-    decidedAt?: string | undefined;
-  }> & {
-    execute(input: {
-      signalId: string;
-      outcome: "accepted" | "duplicate" | "unactionable" | "low_confidence" | "ignored";
-      reason: string;
-      detail?: string | undefined;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      schemaVersion: 1;
-      id: string;
-      repositoryId: string;
-      source: string;
-      deliveryId: string;
-      replyTo: {
-        channel: string;
-        address: string;
-      };
-      payload: unknown;
-      receivedAt: string;
-      outcome: "accepted" | "duplicate" | "unactionable" | "low_confidence" | "ignored" | "pending";
-      detail?: string | undefined;
-      reason?: string | undefined;
-      decidedAt?: string | undefined;
-    }>;
-  };
-  record_change: import("eve/tools").ToolDefinition<{
-    taskId: string;
-    repositoryId: string;
-    prNumber: number;
-    prUrl: string;
-    risk: "low" | "medium" | "high";
-    confidence: "low" | "medium" | "high";
-    summary: string;
-  }, {
-    change: {
-      schemaVersion: 1;
-      id: string;
-      repositoryId: string;
-      prNumber: number;
-      prUrl: string;
-      author: string;
-      risk: "low" | "medium" | "high";
-      confidence: "low" | "medium" | "high";
-      evidence: {
-        reproVerified: boolean;
-        testsAdded: number;
-        checksGreen: boolean;
-        attackPassed: boolean;
-        scopeMatches: boolean;
-        previewUrl?: string | undefined;
-      };
-      state: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
-      createdAt: string;
-      updatedAt: string;
-      taskId?: string | undefined;
-      groupId?: string | undefined;
-      mergeSha?: string | undefined;
-      decidedBy?: string | undefined;
-    };
-    task: {
-      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;
-    };
-  }> & {
-    execute(input: {
-      taskId: string;
-      repositoryId: string;
-      prNumber: number;
-      prUrl: string;
-      risk: "low" | "medium" | "high";
-      confidence: "low" | "medium" | "high";
-      summary: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      change: {
-        schemaVersion: 1;
-        id: string;
-        repositoryId: string;
-        prNumber: number;
-        prUrl: string;
-        author: string;
-        risk: "low" | "medium" | "high";
-        confidence: "low" | "medium" | "high";
-        evidence: {
-          reproVerified: boolean;
-          testsAdded: number;
-          checksGreen: boolean;
-          attackPassed: boolean;
-          scopeMatches: boolean;
-          previewUrl?: string | undefined;
-        };
-        state: "verifying" | "ready" | "merged" | "deployed" | "rolled_out" | "rolled_back" | "closed";
-        createdAt: string;
-        updatedAt: string;
-        taskId?: string | undefined;
-        groupId?: string | undefined;
-        mergeSha?: string | undefined;
-        decidedBy?: string | undefined;
-      };
-      task: {
-        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;
-      };
-    }>;
-  };
-  finish_task: import("eve/tools").ToolDefinition<{
-    taskId: string;
-    summary: string;
-  }, {
-    finished: false;
-    reason: string;
-    taskState?: undefined;
-  } | {
-    finished: true;
-    taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-    reason?: undefined;
-  }> & {
-    execute(input: {
-      taskId: string;
-      summary: string;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      finished: false;
-      reason: string;
-      taskState?: undefined;
-    } | {
-      finished: true;
-      taskState: "queued" | "running" | "stalled" | "verifying" | "succeeded" | "failed" | "needs_human" | "cancelled";
-      reason?: undefined;
-    }>;
-  };
-  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" | "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;
-  }> & {
-    execute(input: {
-      parentTaskId: string;
-      question: {
-        text: string;
-        options: string[];
-      };
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      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;
-    }>;
-  };
-  answer_question: import("eve/tools").ToolDefinition<{
-    questionTaskId: string;
-    answer: string;
-  }, {
-    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;
-    };
-  }> & {
-    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<{
-    repositoryIds: string[];
-    kind: string;
-    state: string;
-    taskId?: string | undefined;
-    changeId?: string | undefined;
-    reason?: string | undefined;
-    dedupeKey?: string | undefined;
-  }, {
-    schemaVersion: 1;
-    receiptId: string;
-    repositoryIds: string[];
-    kind: string;
-    state: string;
-    attempt: number;
-    recordedAt: string;
-    taskId?: string | undefined;
-    changeId?: string | undefined;
-    phase?: string | undefined;
-    reason?: string | undefined;
-    cost?: {
-      totalUsd: number;
-    } | undefined;
-    decidedBy?: string | undefined;
-  }> & {
-    execute(input: {
-      repositoryIds: string[];
-      kind: string;
-      state: string;
-      taskId?: string | undefined;
-      changeId?: string | undefined;
-      reason?: string | undefined;
-      dedupeKey?: string | undefined;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-      schemaVersion: 1;
-      receiptId: string;
-      repositoryIds: string[];
-      kind: string;
-      state: string;
-      attempt: number;
-      recordedAt: string;
-      taskId?: string | undefined;
-      changeId?: string | undefined;
-      phase?: string | undefined;
-      reason?: string | undefined;
-      cost?: {
-        totalUsd: number;
-      } | undefined;
-      decidedBy?: string | undefined;
-    }>;
-  };
-};
-type FactoryTools = ReturnType<typeof factoryTools>;
+declare function createTaskTools(stores: TaskToolsStores, options?: TaskToolsOptions): TaskTools;
+/** Completed conversation output, or `false` when the Task is not a conversation. */
+type ConversationCompletionResult = {
+  readonly output: JsonValue;
+} | false;
+/** Configures attempt recovery, conversation completion, and transcript projection for Eve hooks. */
 interface FactoryHooksOptions {
   /** Session auth attribute naming the task a dispatched session works on. Default `factoryTaskId`. */
   taskIdAttribute?: string;
+  /** Session auth attribute naming the execution attempt. Default `factoryTaskAttempt`. */
+  taskAttemptAttribute?: string;
+  /** Attempts allowed before an explicit provider failure becomes terminal. Default: 3. */
+  maxAttempts?: number;
   /** 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. */
+  isConversation?: (task: Task) => MaybePromise<boolean>;
+  /** Return the actual completed response for an opted-in discussion, or false for other work. */
+  completeConversation?: (task: Task) => Promise<ConversationCompletionResult>;
+  /** Persist the browser-safe transcript projection after Eve durably records a response boundary. */
+  materializeTranscript?: EveTranscriptMaterializer;
+}
+/** Observe-only hook for agents that do not use the Factory task-lifecycle hook. */
+declare function createTranscriptSnapshotHook(materialize: EveTranscriptMaterializer): TranscriptSnapshotHook;
+/** Observe-only Eve hook that materializes transcript snapshots at response boundaries. */
+type TranscriptSnapshotHook = HookDefinition<"session.waiting" | "session.completed" | "session.failed">;
+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 {
+  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 factoryHooks(stores, { presentQuestion }).factory;`.
+ * `export default createFactoryHooks(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.failed/session.failed: immediately 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
- * 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.
+ * 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.
  *
  * 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.
  */
-declare function factoryHooks(stores: FactoryStores, options: FactoryHooksOptions): {
-  factory: import("eve/hooks").HookDefinition<"step.completed" | "turn.completed">;
-};
-type FactoryHooks = ReturnType<typeof factoryHooks>;
+declare function createFactoryHooks(stores: FactoryHooksStores, options: FactoryHooksOptions): FactoryHooks;
 //#endregion
-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 };
+export { AnswerQuestionTool, AnswerQuestionToolInput, AppendReceiptTool, AppendReceiptToolInput, type CancelEveSessionOptions, type ConversationBinding, ConversationCompletionResult, DecideSignalTool, DecideSignalToolInput, type DelegateAgentLaunchInput, type DelegateAgentTool, type DelegateAgentToolInput, type DelegateAgentToolOptions, type DelegateAgentToolStores, type DelegateWorkflowInput, type DelegateWorkflowPolicy, type DelegateWorkflowResult, type EveSessionEvent, type EveSessionStream, type EveSessionStreamInput, type EveTranscriptMaterializer, type EveTranscriptMaterializerOptions, type EveTranscriptRequestScope, type FactoryConversationSessionBinding, FactoryHooks, FactoryHooksOptions, FactoryHooksStores, FinishTaskRefusal, FinishTaskSuccess, FinishTaskTool, FinishTaskToolInput, FinishTaskToolResult, type ForwardEveSessionRequestOptions, GetTaskTool, GetTaskToolInput, GetTaskToolResult, HumanInputQuestion, type InvokeAgentTool, type InvokeAgentToolInput, type InvokeAgentToolOptions, type InvokeAgentToolResult, type InvokeAgentToolStores, PresentQuestion, type ReadCompletedEveTurnOptions, RequestHumanInputTool, RequestHumanInputToolInput, type StartEveSessionOptions, TaskNotFoundResult, TaskTools, TaskToolsOptions, TaskToolsStores, type TranscriptMaterializationInput, TranscriptSnapshotHook, cancelEveSession, conversationBinding, conversationBindingForSession, conversationHeaders, createDelegateAgentTool, createEveTranscriptMaterializer, createFactoryHooks, createInvokeAgentTool, createTaskTools, createTranscriptSnapshotHook, factoryReplyAddressAttribute, factoryReplyAddressHeader, factoryReplyChannelAttribute, factoryReplyChannelHeader, factoryRepositoryIdsAttribute, factoryRepositoryIdsHeader, factoryTaskAttemptAttribute, factoryTaskAttemptHeader, factoryTaskAttribute, factoryTaskHeader, forwardEveSessionRequest, hasFactoryTaskBinding, optionalTaskIdForSession, readCompletedEveTurn, replyToForSession, repositoryIdsForSession, requireTaskIdForSession, startEveSession, taskBindingForSession, taskHeaders, taskSessionAuth, withFactoryTask, withOptionalFactoryTask };
 //# sourceMappingURL=index.d.mts.map