@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/tools/define-tool.d.ts

@@ -12,16 +12,20 @@
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
- * or a throw. The loop (`dispatchTool`) owns the `is_error` envelope — it maps
- * both `err` and a thrown error to one `tool_result { is_error: true }`.
+ * or a throw. The tool adapter of the loop (`loop/tool-adapter.ts`) maps both
+ * `err` and a thrown error to one error result.
+ *
+ * Each call runs as one durable step inside a workflow. Thus a tool body must be
+ * safe to run again from its start, and its result must carry each fact that a
+ * caller reads later.
  */
 import type { Result } from "neverthrow";
 import { z } from "zod";
 import type { AgentSession } from "../auth/types.js";
 import type { AgentRunUsage } from "../loop/metrics.js";
 import type { EmitFn } from "../loop/types.js";
-import type { AskApproval, AskRequest } from "./approval/contract.js";
-export type { EmitFn };
+import type { AskRequest } from "./approval/contract.js";
+export type { EmitFn } from "../loop/types.js";
 /**
  * The error channel of a tool's `Result`. `error` is the message surfaced to
  * the model in the `is_error` `tool_result`; `retryable` tells it whether
@@ -30,18 +34,11 @@ export type { EmitFn };
  * builds one by hand — most failures stay thrown and the loop's backstop
  * derives the same shape via `classifyProviderError`.
  */
-export interface ToolError {
+export type ToolError = {
     readonly error: string;
     readonly retryable: boolean;
     readonly cause?: unknown;
-}
-/**
- * How the loop runs a tool call. `step` (the default) wraps the whole call in
- * one durable step, thus a replay returns the cached result and never runs the
- * body again. `inline` runs the call with no step, for a tool whose effects are
- * not durable work.
- */
-export type ToolExecutionMode = "step" | "inline";
+};
 /** Runtime guard — does a `Result`'s error value carry the `ToolError` shape? */
 export declare function isToolError(value: unknown): value is ToolError;
 /**
@@ -51,10 +48,10 @@ export declare function isToolError(value: unknown): value is ToolError;
  * an image content block. Thus the model sees the picture, and the JSON text
  * holds no bytes.
  */
-export interface ToolResultImage {
+export type ToolResultImage = {
     readonly base64: string;
     readonly mediaType: string;
-}
+};
 /**
  * The reserved key that carries the pictures on a tool ok value. It is a symbol,
  * thus it never collides with a data field. `JSON.stringify` also omits a symbol
@@ -89,10 +86,10 @@ export declare function readToolResultImages(value: unknown): ToolResultImage[];
  *
  * A call record is what a call leaves for process-local state, for example the
  * lineage collector of a sandbox step. A replay returns the cached result of a
- * step-mode call and never runs its body, thus a side effect of the body on
- * such state is lost on recovery. The record goes into the cached dispatch
- * instead, and the loop hands it to `foldCallRecord` after the call settles, on
- * the first run and on each replay alike.
+ * call and never runs its body, thus a side effect of the body on such state is
+ * lost on recovery. The record goes into the output of the step instead, and
+ * the loop hands it to `foldCallRecord` after each round, on the first run and
+ * on each replay alike.
  *
  * It is a symbol, thus `JSON.stringify` omits it and the model never reads it.
  * The record itself must be plain JSON, because the step cache serializes it.
@@ -113,59 +110,58 @@ export declare function readToolCallRecord(value: unknown): unknown;
 /**
  * The request-scoped values passed to every tool's `execute`. No injected
  * dependencies (see the harness-durable-runtime spec) — invocation identity,
- * `session`, `signal`, `emit`, the `ask` user-approval seam, and the turn's
- * usage accumulator a sub-agent-running tool hands to its child loop.
+ * `session`, `signal`, `emit`, and the turn's usage accumulator a
+ * sub-agent-running tool hands to its child loop.
  */
-export interface ToolContext {
+export type ToolContext = {
     /** Stable identity of this AI SDK tool call. Redelivery preserves it; a new
      * model-issued call receives a new value. */
     readonly invocationId: string;
     readonly session: AgentSession;
     readonly signal: AbortSignal;
     readonly emit: EmitFn;
-    /**
-     * Pause for an explicit user decision on a concrete action. Resolves with the
-     * approval (`once`/`always`) or throws `AskRejectedError` on denial. Resolves
-     * to a deny-by-default realization when the embedder wires none, so a tool
-     * that calls it in a non-interactive context is denied rather than left
-     * waiting on a surface that cannot answer.
-     */
-    readonly ask: (request: AskRequest) => Promise<AskApproval>;
     /**
      * The turn's usage accumulator — the mutable total every loop under this
-     * turn folds its LLM calls into. A tool that drives a child `runAgent`
+     * turn folds its LLM calls into. A tool that drives a child loop
      * passes it straight into that run's options, which is what puts the
      * child's tokens in the turn total its root loop reports. A tool that runs
      * no child agent ignores it.
      */
     readonly turnUsage?: AgentRunUsage;
-}
+};
+/** What the approval hook of a tool reads of its call. */
+export type ToolApprovalContext = {
+    readonly invocationId: string;
+    readonly session: AgentSession;
+};
 /**
  * A packaged tool: identity, the Zod input contract, the emitted AI SDK input
- * schema, execution mode, the optional hooks, and the executor.
+ * schema, the optional hooks, and the executor.
  */
-export interface Tool<Input = unknown, Output = unknown> {
+export type Tool<Input = unknown, Output = unknown> = {
     readonly id: string;
     readonly description: string;
-    readonly inputSchema: z.ZodType;
+    readonly inputSchema: z.ZodType<Input>;
     readonly jsonSchema: Record<string, unknown>;
-    readonly executionMode: ToolExecutionMode;
     /** See {@link ToolDefinition.describeCall}. Absent when the tool declares none. */
-    describeCall?(input: Input): string;
+    describeCall?(input: Input): string | undefined;
     /** See {@link ToolDefinition.describeResult}. Absent when the tool declares none. */
-    describeResult?(input: Input, result: Output): string;
+    describeResult?(input: Input, result: Output): string | undefined;
     /**
      * See {@link ToolDefinition.foldCallRecord}. The record arrives untyped: the
      * loop passes back only what the `execute` of the same tool attached.
      */
     foldCallRecord?(record: unknown): void;
+    /** See {@link ToolDefinition.approval}. Absent when the call of the tool never needs the decision of a user. */
+    approval?(input: Input, ctx: ToolApprovalContext): AskRequest | undefined | Promise<AskRequest | undefined>;
+    /** See {@link ToolDefinition.startsWorkflow}. */
+    readonly startsWorkflow?: boolean;
     execute(input: Input, ctx: ToolContext): Promise<Result<Output, ToolError>>;
-}
-export interface ToolDefinition<Schema extends z.ZodType, Output> {
+};
+export type ToolDefinition<Schema extends z.ZodType<z.output<Schema>>, Output> = {
     readonly id: string;
     readonly description: string;
     readonly inputSchema: Schema;
-    readonly executionMode?: ToolExecutionMode;
     /**
      * One line that names what THIS call does — the call-time counterpart of
      * `description`. `description` self-describes the tool at attach time, so an
@@ -198,7 +194,7 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      *
      * The hook never reaches the model.
      */
-    describeCall: ((input: z.infer<Schema>) => string) | "none";
+    describeCall: ((input: z.infer<Schema>) => string | undefined) | "none";
     /**
      * One line that names what THIS call PRODUCED — the outcome-time counterpart
      * of `describeCall`. A page path, a recorded id, and a listed count are facts
@@ -228,12 +224,12 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      *
      * The hook never reaches the model.
      */
-    readonly describeResult?: (input: z.infer<Schema>, result: Output) => string;
+    readonly describeResult?: (input: z.infer<Schema>, result: Output) => string | undefined;
     /**
      * Fold the call record of one settled call into process-local state. The
      * record is the one that `execute` attached with `withToolCallRecord`.
      *
-     * The loop runs the hook after the round settles, in the order of the tool
+     * The loop runs the hook after each round, in the order of the tool
      * calls, on the first run and on each replay alike. Thus state that a
      * replay rebuilds from scratch sees the same records in the same order. A
      * call whose ok value carries no record, and a failed call, never reach it.
@@ -242,8 +238,21 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      * and its result may already be cached. The loop logs a throw and goes on.
      */
     readonly foldCallRecord?: (record: ToolCallRecordOf<Output>) => void;
+    /**
+     * The approval that a call needs, decided from its input before `execute` runs. The hook gives the request that
+     * a surface shows the user, or nothing when the call runs with no question. It can read the disk and the
+     * database, and it changes nothing. `execute` checks its input again, because a file can change while the user
+     * decides. A loop where no surface can answer denies each request.
+     */
+    readonly approval?: (input: z.infer<Schema>, ctx: ToolApprovalContext) => AskRequest | undefined | Promise<AskRequest | undefined>;
+    /**
+     * The call starts a child workflow, for example a sub-agent. A step cannot start a workflow, thus such a call
+     * runs in the body of the workflow, and its child holds the checkpoints of its work. `execute` must start the
+     * child before its first `await`, thus the parallel calls of one reply keep their order on a replay.
+     */
+    readonly startsWorkflow?: boolean;
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
-}
+};
 /**
  * Package a `Tool`. The emitted JSON Schema must have a top-level
  * `"type": "object"` — model tool calling rejects anything else. A `z.discriminatedUnion`
@@ -251,4 +260,4 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
  * the first LLM call). Union-shaped inputs must be modelled as a flat object
  * with a discriminator field.
  */
-export declare function defineTool<Schema extends z.ZodType, Output>(def: ToolDefinition<Schema, Output>): Tool<z.infer<Schema>, Output>;
+export declare function defineTool<Schema extends z.ZodType<z.output<Schema>>, Output>(def: ToolDefinition<Schema, Output>): Tool<z.infer<Schema>, Output>;

package/dist/tools/define-tool.js

@@ -12,13 +12,22 @@
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
- * or a throw. The loop (`dispatchTool`) owns the `is_error` envelope — it maps
- * both `err` and a thrown error to one `tool_result { is_error: true }`.
+ * or a throw. The tool adapter of the loop (`loop/tool-adapter.ts`) maps both
+ * `err` and a thrown error to one error result.
+ *
+ * Each call runs as one durable step inside a workflow. Thus a tool body must be
+ * safe to run again from its start, and its result must carry each fact that a
+ * caller reads later.
  */
 import { z } from "zod";
 /** Runtime guard — does a `Result`'s error value carry the `ToolError` shape? */
 export function isToolError(value) {
-    return typeof value === "object" && value !== null && typeof value.error === "string" && typeof value.retryable === "boolean";
+    return (typeof value === "object" &&
+        value !== null &&
+        "error" in value &&
+        typeof value.error === "string" &&
+        "retryable" in value &&
+        typeof value.retryable === "boolean");
 }
 /**
  * The reserved key that carries the pictures on a tool ok value. It is a symbol,
@@ -46,8 +55,7 @@ export function withToolResultImages(value, images) {
 function isToolResultImage(entry) {
     if (typeof entry !== "object" || entry === null)
         return false;
-    const { base64, mediaType } = entry;
-    return typeof base64 === "string" && typeof mediaType === "string";
+    return "base64" in entry && typeof entry.base64 === "string" && "mediaType" in entry && typeof entry.mediaType === "string";
 }
 /**
  * Read the pictures that a tool ok value carries, in order. A value with none
@@ -58,7 +66,7 @@ function isToolResultImage(entry) {
 export function readToolResultImages(value) {
     if (typeof value !== "object" || value === null)
         return [];
-    const carried = value[toolResultImageKey];
+    const carried = toolResultImageKey in value ? value[toolResultImageKey] : undefined;
     const entries = Array.isArray(carried) ? carried : [carried];
     return entries.filter(isToolResultImage);
 }
@@ -67,10 +75,10 @@ export function readToolResultImages(value) {
  *
  * A call record is what a call leaves for process-local state, for example the
  * lineage collector of a sandbox step. A replay returns the cached result of a
- * step-mode call and never runs its body, thus a side effect of the body on
- * such state is lost on recovery. The record goes into the cached dispatch
- * instead, and the loop hands it to `foldCallRecord` after the call settles, on
- * the first run and on each replay alike.
+ * call and never runs its body, thus a side effect of the body on such state is
+ * lost on recovery. The record goes into the output of the step instead, and
+ * the loop hands it to `foldCallRecord` after each round, on the first run and
+ * on each replay alike.
  *
  * It is a symbol, thus `JSON.stringify` omits it and the model never reads it.
  * The record itself must be plain JSON, because the step cache serializes it.
@@ -84,7 +92,7 @@ export function withToolCallRecord(value, record) {
 export function readToolCallRecord(value) {
     if (typeof value !== "object" || value === null)
         return undefined;
-    return value[toolCallRecordKey];
+    return toolCallRecordKey in value ? value[toolCallRecordKey] : undefined;
 }
 /**
  * Package a `Tool`. The emitted JSON Schema must have a top-level
@@ -103,25 +111,29 @@ export function defineTool(def) {
             `top-level "type" — model the input as a flat object with a ` +
             `discriminator field instead.`);
     }
-    const executionMode = def.executionMode ?? "step";
-    return {
+    const packaged = {
         id: def.id,
         description: def.description,
         inputSchema: def.inputSchema,
         jsonSchema,
-        executionMode,
-        // Spread rather than assigned: a tool that declines carries no
-        // `describeCall` key at all, so "has a hook" is one property check.
-        // `typeof` is the discriminator, not equality with the sentinel, so a
-        // hook that returns the string `"none"` still packages as a hook.
-        ...(typeof def.describeCall === "function" ? { describeCall: def.describeCall } : {}),
-        // The same property-presence pattern as `describeCall`: a tool that
-        // declares no result hook carries no key, thus "has a hook" is one
-        // property check on either side.
-        ...(typeof def.describeResult === "function" ? { describeResult: def.describeResult } : {}),
-        // The loop passes back only a record that this tool's `execute`
-        // attached, thus the record has the declared type.
-        ...(typeof def.foldCallRecord === "function" ? { foldCallRecord: def.foldCallRecord } : {}),
-        execute: def.execute,
+        execute: def.execute.bind(def),
     };
+    if (typeof def.foldCallRecord === "function")
+        packaged.foldCallRecord = def.foldCallRecord.bind(def);
+    if (typeof def.approval === "function")
+        packaged.approval = def.approval.bind(def);
+    // A tool that declines carries no `describeCall` key at all, so "has a
+    // hook" is one property check. The test is equality with the `"none"`
+    // sentinel: a function never equals it, so a hook that returns the string
+    // `"none"` still packages as a hook.
+    if (def.describeCall !== "none")
+        packaged.describeCall = def.describeCall;
+    // The same property-presence pattern as `describeCall`: a tool that
+    // declares no result hook carries no key, thus "has a hook" is one
+    // property check on either side.
+    if (def.describeResult !== undefined)
+        packaged.describeResult = def.describeResult;
+    if (def.startsWorkflow === true)
+        return { ...packaged, startsWorkflow: true };
+    return packaged;
 }

package/dist/tools/display/normalize-echart-spec.d.ts

@@ -20,13 +20,13 @@
  * Pure: the input spec is never mutated. Modified branches are copy-on-write; untouched branches are
  * shared by reference. `normalize(normalize(x))` deep-equals `normalize(x)`.
  */
-export interface NormalizeEchartSpecOptions {
+export type NormalizeEchartSpecOptions = {
     /**
      * The `show_user` `title` param — the card heading rendered above the chart canvas. Seeds the
      * `saveAsImage` download filename when the author supplied none.
      */
     title?: string;
-}
+};
 /**
  * Kebab-case download filename: `"HMGCR — VST Expression"` → `"hmgcr-vst-expression"`.
  * Diacritics are folded, every other non-alphanumeric run collapses to a single dash.

package/dist/tools/display/normalize-echart-spec.js

@@ -20,6 +20,7 @@
  * Pure: the input spec is never mutated. Modified branches are copy-on-write; untouched branches are
  * shared by reference. `normalize(normalize(x))` deep-equals `normalize(x)`.
  */
+import { isUnknownArray } from "../../lib/unknown-array.js";
 /** Max length of a derived `saveAsImage` filename. */
 const MAX_FILENAME_LEN = 64;
 /** Fallback download filename when no heading is available to derive one from. */
@@ -38,14 +39,29 @@ function axisEntries(axis) {
  * Diacritics are folded, every other non-alphanumeric run collapses to a single dash.
  */
 export function kebabFilename(source) {
-    const slug = (source ?? "")
-        .normalize("NFKD")
-        .replace(/[\u0300-\u036f]/g, "")
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .slice(0, MAX_FILENAME_LEN)
-        .replace(/^-+|-+$/g, "");
-    return slug.length > 0 ? slug : DEFAULT_FILENAME;
+    let out = "";
+    let inRun = false;
+    for (const char of (source ?? "").normalize("NFKD").toLowerCase()) {
+        if (char >= "\u0300" && char <= "\u036f")
+            continue;
+        const isSlugChar = (char >= "a" && char <= "z") || (char >= "0" && char <= "9");
+        if (!isSlugChar) {
+            inRun = true;
+            continue;
+        }
+        if (inRun && out.length > 0)
+            out += "-";
+        inRun = false;
+        out += char;
+        if (out.length >= MAX_FILENAME_LEN)
+            break;
+    }
+    // One append can add two characters, so the cap can land between a dash and the letter it introduces.
+    if (out.length > MAX_FILENAME_LEN)
+        out = out.slice(0, MAX_FILENAME_LEN);
+    if (out.endsWith("-"))
+        out = out.slice(0, -1);
+    return out.length > 0 ? out : DEFAULT_FILENAME;
 }
 /** Declared series count. `0` = none declared, which is also "nothing a legend could label". */
 function seriesCount(spec) {
@@ -164,7 +180,7 @@ export function normalizeEchartSpec(spec, opts = {}) {
         const axis = out[key];
         // A malformed entry is passed through rather than dropped — normalization rewrites layout,
         // never the shape of the spec it was handed.
-        if (Array.isArray(axis))
+        if (isUnknownArray(axis))
             out[key] = axis.map((entry) => (isRecord(entry) ? normalizeAxis(entry, key === "xAxis") : entry));
         else if (isRecord(axis))
             out[key] = normalizeAxis(axis, key === "xAxis");
@@ -178,13 +194,18 @@ export function normalizeEchartSpec(spec, opts = {}) {
     const gridNormalizable = cartesian && !Array.isArray(grid) && (grid === undefined || (isRecord(grid) && grid.width === undefined && grid.height === undefined));
     if (gridNormalizable) {
         const authored = isRecord(grid) ? grid : {};
-        out.grid = {
-            ...authored,
-            ...(authored.top === undefined ? { top: out.graphic !== undefined ? "12%" : "8%" } : {}),
-            ...(authored.bottom === undefined ? { bottom: rotated ? (bottomLegend ? "30%" : "25%") : "20%" } : {}),
-            ...(authored.left === undefined ? { left: "10%" } : {}),
-            ...(authored.right === undefined ? { right: "5%" } : {}),
-        };
+        const filled = { ...authored };
+        const annotated = out.graphic !== undefined && !(isUnknownArray(out.graphic) && out.graphic.length === 0);
+        if (authored.top === undefined)
+            filled.top = annotated ? "12%" : "8%";
+        // oxlint-disable-next-line no-unnecessary-condition -- tsgolint cannot see the normalizeAxis closure that sets rotated; the check is live (rotated labels get the larger bottom margin).
+        if (authored.bottom === undefined)
+            filled.bottom = rotated ? (bottomLegend ? "30%" : "25%") : "20%";
+        if (authored.left === undefined)
+            filled.left = "10%";
+        if (authored.right === undefined)
+            filled.right = "5%";
+        out.grid = filled;
     }
     // ── Toolbox ─────────────────────────────────────────────────────────
     if (!Array.isArray(out.toolbox)) {
@@ -194,18 +215,21 @@ export function normalizeEchartSpec(spec, opts = {}) {
         // The in-spec title is stripped, but it is still the author's own description of the chart —
         // a better filename seed than the generic fallback when no card title was given.
         const specTitleText = isRecord(specTitle) && typeof specTitle.text === "string" ? specTitle.text : undefined;
-        out.toolbox = {
-            ...authored,
-            ...(hasPlacement(authored) ? {} : { right: 0, top: 0 }),
-            feature: {
-                ...feature,
-                saveAsImage: {
-                    ...saveAsImage,
-                    ...(saveAsImage.type === undefined ? { type: "png" } : {}),
-                    ...(saveAsImage.name === undefined ? { name: kebabFilename(opts.title ?? specTitleText) } : {}),
-                },
-            },
+        const placed = { ...authored };
+        if (!hasPlacement(authored)) {
+            placed.right = 0;
+            placed.top = 0;
+        }
+        const saved = { ...saveAsImage };
+        if (saveAsImage.type === undefined)
+            saved.type = "png";
+        if (saveAsImage.name === undefined)
+            saved.name = kebabFilename(opts.title ?? specTitleText);
+        placed.feature = {
+            ...feature,
+            saveAsImage: saved,
         };
+        out.toolbox = placed;
     }
     return out;
 }

package/dist/tools/display/show-user.d.ts

@@ -9,7 +9,7 @@
  *
  * The presentation `id` is derived deterministically from the content, so
  * an identical re-emission carries the same id — duplicate suppression is a
- * downstream reconciliation concern of the emit pipeline (change 3), not a
+ * downstream reconciliation concern of the emit pipeline, not a
  * per-request `Set` smuggled through an ambient context bag.
  *
  * An `echart` spec's layout is normalized (`normalize-echart-spec.ts`) inside
@@ -26,7 +26,7 @@ type ShowUserOutput = {
     id: string;
 };
 export declare const showUserTool: import("../define-tool.js").Tool<{
-    kind: "code" | "echart" | "markdown" | "svg" | "table" | "structure";
+    kind: "code" | "echart" | "markdown" | "structure" | "svg" | "table";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;

package/dist/tools/display/show-user.js

@@ -9,7 +9,7 @@
  *
  * The presentation `id` is derived deterministically from the content, so
  * an identical re-emission carries the same id — duplicate suppression is a
- * downstream reconciliation concern of the emit pipeline (change 3), not a
+ * downstream reconciliation concern of the emit pipeline, not a
  * per-request `Set` smuggled through an ambient context bag.
  *
  * An `echart` spec's layout is normalized (`normalize-echart-spec.ts`) inside

package/dist/tools/execute-analysis.d.ts

@@ -3,7 +3,9 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import { ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
+import { type Connectable } from "../lib/db-result.js";
+import type { Querier } from "../state/db.js";
+import { z } from "zod";
 import type { AgentSession } from "../auth/types.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
@@ -16,9 +18,18 @@ import type { ExtendAnalysisFarm } from "../sandbox/types.js";
 import { type AnalysisPlan } from "../schemas/workflow-state.js";
 import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type AdHocRoute } from "./ad-hoc-router.js";
+import { type Tool } from "./define-tool.js";
+declare const inputSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        adhoc: "adhoc";
+        plan: "plan";
+    }>;
+    planId: z.ZodOptional<z.ZodString>;
+    request: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 type ExecuteAnalysisWorkflow = (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
-export interface ExecuteAnalysisToolDeps extends Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory" | "refStorePath"> {
-    readonly pool: Pool;
+export type ExecuteAnalysisToolDeps = Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory" | "refStorePath"> & {
+    readonly pool: Querier & Connectable;
     readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
     readonly runAuthorizer: RunAuthorizer;
     readonly runLauncher: RunLauncher;
@@ -34,7 +45,7 @@ export interface ExecuteAnalysisToolDeps extends Pick<EnvironmentStorePaths, "fa
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
     /** Falls back to the no-op recorder when omitted. */
     readonly usageRecorder?: UsageRecorder;
-}
+};
 export declare class PlanNotFoundError extends Error {
     constructor(planId: string);
 }
@@ -116,12 +127,14 @@ export type LaunchPlanRunRefusal = {
 export declare function buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
 /**
  * `newestRunId` is the newest run of the plan that the caller saw, or `null` when the caller saw no run.
- * Without it, the launch compares no run.
+ * Without it, the launch compares no run. `runId` is the id of the run that this launch starts, and a
+ * second launch with the same id starts nothing new. Without it, the launch takes a random id.
  */
 export type LaunchPlanRunInput = {
     session: AgentSession;
     planId: string;
     newestRunId?: string | null;
+    runId?: string;
 };
 /**
  * Start the run of a stored plan. It reads the plan under the analysis of the session, validates it,
@@ -134,11 +147,7 @@ export type LaunchPlanRunInput = {
  * promise.
  */
 export declare function launchPlanRun(deps: LaunchPlanRunDeps, input: LaunchPlanRunInput): ResultAsync<PlanLaunch, LaunchPlanRunRefusal>;
-export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
-    mode: "plan" | "adhoc";
-    planId?: string | undefined;
-    request?: string | undefined;
-}, {
+export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): Tool<z.infer<typeof inputSchema>, {
     runId: string;
     status: "in_progress";
 }>;