@inflexa-ai/harness 0.1.1

package/dist/tools/bio/search-toxcast.js

@@ -0,0 +1,141 @@
+/**
+ * searchToxcast — search EPA ToxCast/Tox21 high-throughput screening data
+ * for a chemical via the CTX Bioactivity API.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { EPA_CCTE_BASE, getEpaCcteHeaders } from "../lib/toxcast-config.js";
+// Raw CTX Bioactivity API wire shapes, validated at the fetch boundary. Fields
+// are optional because the API omits absent values; `dtxsid` stays required
+// because `resolveDtxsid` reads it without a guard, so a row missing it is a
+// contract break surfaced as `invalid_response` rather than a runtime error.
+// The row-shaping/filtering logic in `execute` stays put — it depends on the
+// resolved chemical, the assay-name map, and the `activeOnly`/`limit` inputs.
+const CtxChemicalSearchRowSchema = z.object({
+    dtxsid: z.string(),
+    preferredName: z.string().optional(),
+    casrn: z.string().nullable().optional(),
+});
+const ToxcastMc5ParamSchema = z.object({
+    ac50: z.number().optional(),
+    acc: z.number().optional(),
+});
+const ToxcastMc6ParamSchema = z.object({
+    flag: z.unknown().optional(),
+});
+const ToxcastBioactivityRowSchema = z.object({
+    aeid: z.number().optional(),
+    hitc: z.number().optional(),
+    maxMean: z.number().nullable().optional(),
+    modl: z.string().optional(),
+    mc5Param: ToxcastMc5ParamSchema.nullable().optional(),
+    mc6Param: ToxcastMc6ParamSchema.nullable().optional(),
+});
+const ToxcastAssaySummaryRowSchema = z.object({
+    aeid: z.number().optional(),
+    aenm: z.string().optional(),
+});
+export function createSearchToxcastTool(deps) {
+    return defineTool({
+        id: "search_toxcast",
+        description: "Search EPA ToxCast/Tox21 high-throughput screening data for a chemical via the CTX Bioactivity API. " +
+            "Returns in-vitro bioactivity results across hundreds of assay endpoints " +
+            "(nuclear receptors, stress response, mitochondrial toxicity, etc.). " +
+            "Use to assess toxicological liability of compounds or drug targets. " +
+            "Requires EPA_CCTE_API_KEY environment variable.",
+        inputSchema: z.object({
+            query: z.string().describe("Chemical identifier: DTXSID (e.g. DTXSID7020182), CASRN (e.g. 80-05-7), " + "or chemical name (e.g. bisphenol A)"),
+            activeOnly: z.boolean().default(true).describe("Return only active (hit) assays. Set false for all tested assays."),
+            limit: z.number().int().min(1).max(200).default(50).describe("Max assay results to return (sorted by AC50 ascending for actives)"),
+        }),
+        execute: async ({ query, activeOnly = true, limit = 50 }) => {
+            const headers = getEpaCcteHeaders(deps.apiKey);
+            const resolved = await resolveDtxsid(query, headers);
+            // "No chemical found" is an expected outcome — a data variant, not an error.
+            if (!resolved)
+                return ok({ found: false, query });
+            const { dtxsid, preferredName, casrn } = resolved;
+            const aeidMap = await fetchAssayNames(dtxsid, headers);
+            const bioUrl = `${EPA_CCTE_BASE}/bioactivity/data/search/by-dtxsid/${dtxsid}`;
+            const bioRes = await apiFetchValidated(bioUrl, z.array(ToxcastBioactivityRowSchema), { headers });
+            if (bioRes.isErr())
+                throw new Error(describeApiError(bioRes.error));
+            const allResults = bioRes.value ?? [];
+            const totalAssays = allResults.length;
+            const activeAssays = allResults.filter((r) => r.hitc === 1).length;
+            const filtered = activeOnly ? allResults.filter((r) => r.hitc === 1) : allResults;
+            filtered.sort((a, b) => extractAc50(a) - extractAc50(b));
+            const results = filtered.slice(0, limit).map((r) => {
+                const aeid = r.aeid ?? 0;
+                const mc6 = r.mc6Param ?? {};
+                const flags = Array.isArray(mc6.flag) ? mc6.flag : [];
+                return {
+                    aeid,
+                    assayEndpoint: aeidMap.get(aeid) ?? `aeid:${aeid}`,
+                    ac50: extractAc50Raw(r),
+                    hitCall: r.hitc ?? 0,
+                    maxMean: r.maxMean ?? null,
+                    model: r.modl ?? "",
+                    flags,
+                };
+            });
+            return ok({
+                found: true,
+                chemical: {
+                    dtxsid,
+                    preferredName,
+                    casrn,
+                    totalAssays,
+                    activeAssays,
+                    activeHitRate: totalAssays > 0 ? Math.round((activeAssays / totalAssays) * 1000) / 1000 : 0,
+                    results,
+                },
+            });
+        },
+    });
+}
+function extractAc50(r) {
+    return extractAc50Raw(r) ?? Infinity;
+}
+function extractAc50Raw(r) {
+    const mc5 = r.mc5Param;
+    if (mc5 && typeof mc5 === "object") {
+        if (typeof mc5.ac50 === "number")
+            return mc5.ac50;
+        if (typeof mc5.acc === "number")
+            return mc5.acc;
+    }
+    return null;
+}
+async function resolveDtxsid(query, headers) {
+    if (query.startsWith("DTXSID")) {
+        return { dtxsid: query, preferredName: query, casrn: null };
+    }
+    const searchUrl = `${EPA_CCTE_BASE}/chemical/search/equal/${encodeURIComponent(query)}`;
+    const searchRes = await apiFetchValidated(searchUrl, z.array(CtxChemicalSearchRowSchema), { headers });
+    if (searchRes.isErr())
+        throw new Error(describeApiError(searchRes.error));
+    if (!searchRes.value?.length)
+        return null;
+    const chem = searchRes.value[0];
+    return {
+        dtxsid: chem.dtxsid,
+        preferredName: chem.preferredName ?? query,
+        casrn: chem.casrn ?? null,
+    };
+}
+async function fetchAssayNames(dtxsid, headers) {
+    const map = new Map();
+    const url = `${EPA_CCTE_BASE}/bioactivity/data/summary/search/by-dtxsid/${dtxsid}`;
+    const res = await apiFetchValidated(url, z.array(ToxcastAssaySummaryRowSchema), { headers });
+    if (res.isOk() && Array.isArray(res.value)) {
+        for (const s of res.value) {
+            if (s.aeid != null && s.aenm) {
+                map.set(s.aeid, s.aenm);
+            }
+        }
+    }
+    return map;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * The harness tool primitive.
+ *
+ * `defineTool` packages a `Tool` and emits its AI SDK input schema
+ * from the Zod `inputSchema` via Zod 4's native `z.toJSONSchema()`. It is
+ * dependency-agnostic (see the harness-durable-runtime spec): a pure tool is a module-scope
+ * `defineTool(...)`; a dependency-bearing tool is a factory closure that
+ * captures its deps and calls `defineTool`.
+ *
+ * `ToolContext` carries exactly the four request-scoped values every tool
+ * may need — no pool, no sandbox, no 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 }`.
+ */
+import type { Result } from "neverthrow";
+import { z } from "zod";
+import type { AgentSession } from "../auth/types.js";
+import type { EmitFn, RunStep } from "../loop/types.js";
+export type { EmitFn };
+/**
+ * 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
+ * re-issuing the call could plausibly succeed; `cause` keeps the underlying
+ * value for classification if the error is later rethrown. A tool rarely
+ * builds one by hand — most failures stay thrown and the loop's backstop
+ * derives the same shape via `classifyProviderError`.
+ */
+export interface ToolError {
+    readonly error: string;
+    readonly retryable: boolean;
+    readonly cause?: unknown;
+}
+export type ToolExecutionMode = "step" | "workflow" | "inline";
+/** Runtime guard — does a `Result`'s error value carry the `ToolError` shape? */
+export declare function isToolError(value: unknown): value is ToolError;
+/**
+ * The request-scoped values passed to every tool's `execute`. No injected
+ * dependencies (see the harness-durable-runtime spec) — `session`, `signal`, `emit`, plus the `runStep`
+ * durability seam (`passthroughStep` in chat, `DBOS.runStep` in workflows)
+ * a tool uses to wrap its own durable work.
+ */
+export interface ToolContext {
+    readonly session: AgentSession;
+    readonly signal: AbortSignal;
+    readonly emit: EmitFn;
+    /**
+     * Wrap durable work in a replay-cached step. The loop namespaces the name
+     * under the tool's own step name, so a tool just passes a short local label.
+     */
+    readonly runStep: RunStep;
+}
+/**
+ * A packaged tool: identity, the Zod input contract, the emitted AI SDK input
+ * schema, execution mode, and the executor.
+ */
+export interface Tool<Input = unknown, Output = unknown> {
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodType;
+    readonly jsonSchema: Record<string, unknown>;
+    readonly executionMode: ToolExecutionMode;
+    execute(input: Input, ctx: ToolContext): Promise<Result<Output, ToolError>>;
+}
+export interface ToolDefinition<Schema extends z.ZodType, Output> {
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: Schema;
+    readonly executionMode?: ToolExecutionMode;
+    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`
+ * emits a top-level `oneOf`; this throws at construction (fail fast — not at
+ * 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>;

package/dist/tools/define-tool.js

@@ -0,0 +1,48 @@
+/**
+ * The harness tool primitive.
+ *
+ * `defineTool` packages a `Tool` and emits its AI SDK input schema
+ * from the Zod `inputSchema` via Zod 4's native `z.toJSONSchema()`. It is
+ * dependency-agnostic (see the harness-durable-runtime spec): a pure tool is a module-scope
+ * `defineTool(...)`; a dependency-bearing tool is a factory closure that
+ * captures its deps and calls `defineTool`.
+ *
+ * `ToolContext` carries exactly the four request-scoped values every tool
+ * may need — no pool, no sandbox, no 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 }`.
+ */
+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";
+}
+/**
+ * Package a `Tool`. The emitted JSON Schema must have a top-level
+ * `"type": "object"` — model tool calling rejects anything else. A `z.discriminatedUnion`
+ * emits a top-level `oneOf`; this throws at construction (fail fast — not at
+ * the first LLM call). Union-shaped inputs must be modelled as a flat object
+ * with a discriminator field.
+ */
+export function defineTool(def) {
+    const jsonSchema = z.toJSONSchema(def.inputSchema);
+    delete jsonSchema.$schema;
+    if (jsonSchema.type !== "object") {
+        throw new Error(`defineTool("${def.id}"): inputSchema must emit a top-level JSON Schema ` +
+            `'"type":"object"', got ${JSON.stringify(jsonSchema.type)}. ` +
+            `Union-shaped inputs (z.discriminatedUnion) emit "oneOf" with no ` +
+            `top-level "type" — model the input as a flat object with a ` +
+            `discriminator field instead.`);
+    }
+    const executionMode = def.executionMode ?? "step";
+    return {
+        id: def.id,
+        description: def.description,
+        inputSchema: def.inputSchema,
+        jsonSchema,
+        executionMode,
+        execute: def.execute,
+    };
+}

package/dist/tools/display/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Display barrel — user-facing presentation cards streamed to chat.
+ */
+export * from "./show-user.js";

package/dist/tools/display/index.js

@@ -0,0 +1,4 @@
+/**
+ * Display barrel — user-facing presentation cards streamed to chat.
+ */
+export * from "./show-user.js";

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

@@ -0,0 +1,33 @@
+/**
+ * showUser tool — emits agent-synthesized content as a UI stream event.
+ *
+ * For content the agent is INVENTING — charts, markdown, code snippets,
+ * SVG diagrams, tables. Content is serialized inline (bytes on the wire).
+ *
+ * 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
+ * per-request `Set` smuggled through an ambient context bag.
+ *
+ * For stored plans, use `show_plan`. For existing files, use `show_file`.
+ */
+type ShowUserOutput = {
+    shown: false;
+    reason: "invalid_path";
+} | {
+    id: string;
+};
+export declare const showUserTool: import("../define-tool.js").Tool<{
+    kind: "code" | "echart" | "markdown" | "svg" | "table";
+    title?: string | undefined;
+    spec?: Record<string, unknown> | undefined;
+    dataPath?: string | undefined;
+    body?: string | undefined;
+    code?: string | undefined;
+    language?: string | undefined;
+    markup?: string | undefined;
+    headers?: string[] | undefined;
+    rows?: string[][] | undefined;
+    caption?: string | undefined;
+}, ShowUserOutput>;
+export {};

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

@@ -0,0 +1,67 @@
+/**
+ * showUser tool — emits agent-synthesized content as a UI stream event.
+ *
+ * For content the agent is INVENTING — charts, markdown, code snippets,
+ * SVG diagrams, tables. Content is serialized inline (bytes on the wire).
+ *
+ * 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
+ * per-request `Set` smuggled through an ambient context bag.
+ *
+ * For stored plans, use `show_plan`. For existing files, use `show_file`.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { buildPresentationCardData } from "../../memory/card-builders.js";
+import { defineTool } from "../define-tool.js";
+import { validatePath } from "../lib/path-validation.js";
+// Flat object schema — Anthropic requires top-level "type": "object" in tool
+// input_schema. A z.discriminatedUnion produces a top-level "oneOf" without
+// "type", which the API rejects. Variant-specific fields are optional; the
+// LLM picks the right ones based on `kind`.
+const ShowUserInputSchema = z.object({
+    kind: z.enum(["echart", "markdown", "code", "svg", "table"]).describe("The type of agent-synthesized content to display"),
+    title: z.string().optional().describe("Title shown above the content"),
+    spec: z.record(z.string(), z.unknown()).optional().describe("Full ECharts option spec as JSON (kind=echart)"),
+    dataPath: z
+        .string()
+        .optional()
+        .describe("echart only: analysis-rooted CSV artifact path (e.g. 'runs/run-abc/step-2/output/de-summary.csv') the host loads as the ECharts `dataset.source` at render time. Author `encode`/dimensions against the CSV's column names and omit `dataset.source` from the spec — the data is never pulled through the context window."),
+    body: z.string().optional().describe("Markdown content to render (kind=markdown)"),
+    code: z.string().optional().describe("Code content (kind=code)"),
+    language: z.string().optional().describe("Language identifier, e.g. r, python, bash (kind=code)"),
+    markup: z.string().optional().describe("SVG markup string (kind=svg)"),
+    headers: z.array(z.string()).optional().describe("Column headers (kind=table)"),
+    rows: z.array(z.array(z.string())).optional().describe("Row data as array of string arrays (kind=table)"),
+    caption: z.string().optional().describe("Caption (kind=table)"),
+});
+export const showUserTool = defineTool({
+    id: "show_user",
+    description: "Display agent-synthesized content to the user: ECharts visualizations, " +
+        "markdown, code blocks, SVG diagrams, or tables. " +
+        "Use for content you are INVENTING (a chart you just built, a code snippet you are proposing, " +
+        "a markdown synthesis, a table you constructed). " +
+        "For an echart backed by a chart-ready CSV artifact a step already wrote, pass `dataPath` (analysis-rooted) " +
+        "and author `encode`/dimensions by column name with no `dataset.source` — the host loads the CSV as the " +
+        "dataset at render time, so you never inline the rows. " +
+        "For stored plans, use `show_plan`. For existing analysis files (images, CSVs, etc.), use `show_file`. " +
+        "Call once per distinct content item; an identical repeat call resolves to the same card.",
+    inputSchema: ShowUserInputSchema,
+    execute: async (input, ctx) => {
+        // `dataPath` is a reference the host resolves at render time; validate its
+        // shape only (existence is a render-time host concern), and treat a
+        // malformed path as an expected outcome the model can self-correct.
+        if (typeof input.dataPath === "string" && validatePath(input.dataPath) !== null) {
+            return ok({ shown: false, reason: "invalid_path" });
+        }
+        // Non-null: the input passed Zod validation, so `kind` is present.
+        const card = buildPresentationCardData(input);
+        await ctx.emit({
+            type: "data-presentation",
+            source: ctx.session.provenance,
+            data: card,
+        });
+        return ok({ id: card.id });
+    },
+});

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

@@ -0,0 +1,64 @@
+/**
+ * executePlan — launch the DBOS `executeAnalysis` parent workflow for an
+ * approved plan.
+ *
+ * Results are pull-only: the tool does NOT register a `.then(saveRunResult)`
+ * or any completion callback that writes to the conversation thread. The
+ * conversation agent retrieves run results via `inspectRun` on a later turn.
+ *
+ * Authorization contract: the tool runs in the chat HTTP route, so its session
+ * carries the live auth. It authorizes through the injected `RunAuthorizer`
+ * seam and never reads a credential. The flow is dedup → reserve → authorize
+ * → startWorkflow:
+ *
+ *   1. Dedup pre-check via `queryActiveRun`. On hit, return the existing
+ *      `runId` with no authorization and no `startWorkflow`.
+ *   2. Reserve the slot: `insertRun` the `cortex_runs` row (`runId =
+ *      randomUUID()`, the bare UUID that IS the DBOS workflowID) BEFORE
+ *      authorizing. The partial-unique index is the race backstop; the loser
+ *      returns the winner's `runId` without authorizing — nothing to revoke.
+ *   3. `runAuthorizer.authorize({ ..., frame: { runId } })` — authorizes the
+ *      run; the authorizer's persisted handle now lands because the row
+ *      exists. On failure, mark the reserved row `failed` (releasing the dedup
+ *      slot for a retry) and rethrow.
+ *   4. `runLauncher.launch(executeAnalysis, { workflowId: runId }, ...)`,
+ *      passing the `RunSession` in the workflow input. On failure, revoke + mark
+ *      failed.
+ */
+import type { Pool } from "pg";
+import type { ResourcePolicy } from "../config/resource-limits.js";
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { RunLauncher } from "../execution/run-launcher.js";
+import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
+type ExecuteAnalysisWorkflow = (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
+export interface ExecutePlanToolDeps {
+    readonly pool: Pool;
+    /** Registered `executeAnalysis` workflow callable — produced by `registerExecuteAnalysis` (wired by `assembleCoreRuntime`). */
+    readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
+    /** Authorizes the run at the async edge and revokes on the abort paths. */
+    readonly runAuthorizer: RunAuthorizer;
+    /** Starts the durable run — the durability engine stays behind this seam. */
+    readonly runLauncher: RunLauncher;
+    /**
+     * Host resource policy. The machine budget is snapshotted into the workflow
+     * input here at the async edge — the workflow body never reads live config,
+     * so a mid-run config edit cannot change a running run's admission decisions.
+     */
+    readonly resourcePolicy?: ResourcePolicy;
+}
+export declare class PlanNotFoundError extends Error {
+    constructor(planId: string);
+}
+export declare class PlanMalformedError extends Error {
+    constructor(planId: string);
+}
+export declare class PlanValidationError extends Error {
+    readonly errors: string[];
+    constructor(planId: string, errors: string[]);
+}
+export declare function createExecutePlanTool(deps: ExecutePlanToolDeps): import("./define-tool.js").Tool<{
+    planId: string;
+}, {
+    runId: string;
+}>;
+export {};

package/dist/tools/execute-plan.js

@@ -0,0 +1,208 @@
+/**
+ * executePlan — launch the DBOS `executeAnalysis` parent workflow for an
+ * approved plan.
+ *
+ * Results are pull-only: the tool does NOT register a `.then(saveRunResult)`
+ * or any completion callback that writes to the conversation thread. The
+ * conversation agent retrieves run results via `inspectRun` on a later turn.
+ *
+ * Authorization contract: the tool runs in the chat HTTP route, so its session
+ * carries the live auth. It authorizes through the injected `RunAuthorizer`
+ * seam and never reads a credential. The flow is dedup → reserve → authorize
+ * → startWorkflow:
+ *
+ *   1. Dedup pre-check via `queryActiveRun`. On hit, return the existing
+ *      `runId` with no authorization and no `startWorkflow`.
+ *   2. Reserve the slot: `insertRun` the `cortex_runs` row (`runId =
+ *      randomUUID()`, the bare UUID that IS the DBOS workflowID) BEFORE
+ *      authorizing. The partial-unique index is the race backstop; the loser
+ *      returns the winner's `runId` without authorizing — nothing to revoke.
+ *   3. `runAuthorizer.authorize({ ..., frame: { runId } })` — authorizes the
+ *      run; the authorizer's persisted handle now lands because the row
+ *      exists. On failure, mark the reserved row `failed` (releasing the dedup
+ *      slot for a retry) and rethrow.
+ *   4. `runLauncher.launch(executeAnalysis, { workflowId: runId }, ...)`,
+ *      passing the `RunSession` in the workflow input. On failure, revoke + mark
+ *      failed.
+ */
+import { randomUUID } from "node:crypto";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { buildRunCardData } from "../memory/card-builders.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { validatePlan } from "../schemas/validate-plan.js";
+import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
+import { renderStepPrompt } from "../schemas/render-step-prompt.js";
+import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, updateRunStatus } from "../state/index.js";
+import { defineTool } from "./define-tool.js";
+const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
+const inputSchema = z.object({
+    planId: planIdSchema,
+});
+export class PlanNotFoundError extends Error {
+    constructor(planId) {
+        super(`Plan ${planId} not found for this analysis`);
+        this.name = "PlanNotFoundError";
+    }
+}
+export class PlanMalformedError extends Error {
+    constructor(planId) {
+        super(`Plan ${planId} is malformed`);
+        this.name = "PlanMalformedError";
+    }
+}
+export class PlanValidationError extends Error {
+    errors;
+    constructor(planId, errors) {
+        super(`Plan ${planId} failed validation: ${errors.length} error(s)`);
+        this.errors = errors;
+        this.name = "PlanValidationError";
+    }
+}
+function isDedupCollision(err) {
+    return err instanceof RunDedupCollisionError || (err instanceof Error && err.name === "RunDedupCollisionError");
+}
+export function createExecutePlanTool(deps) {
+    const { pool, executeAnalysisWorkflow, runAuthorizer, runLauncher, resourcePolicy } = deps;
+    return defineTool({
+        id: "execute_plan",
+        description: "Execute an approved analysis plan by its planId. " +
+            "Pass the planId returned from generatePlan — the tool resolves the plan " +
+            "server-side, validates the DAG, and starts the executeAnalysis workflow " +
+            "asynchronously. Returns the runId on success. " +
+            "The user sees a run card in chat (also tracked in the Runs panel); " +
+            "run results become available for inspection on a later turn. " +
+            "Do not instruct the user to invoke any tool.",
+        inputSchema,
+        execute: async (input, ctx) => {
+            const { planId } = input;
+            // Mirror show_plan: emit a live display card so chat renders a run card
+            // rather than a generic "used 1 tool" chip. Null (plan/run unresolvable)
+            // simply skips the card — the run still starts.
+            const emitRunCard = async (analysisId, runId) => {
+                const card = await buildRunCardData(pool, {
+                    planId,
+                    analysisId,
+                    runId,
+                }).unwrapOr(null);
+                if (card) {
+                    await ctx.emit({
+                        type: "data-run-card",
+                        source: ctx.session.provenance,
+                        data: card,
+                    });
+                }
+            };
+            const { session } = ctx;
+            if (session.scope.kind !== "analysis") {
+                throw new Error("executePlan can only be invoked on an analysis-scoped session");
+            }
+            if (!session.auth) {
+                throw new Error("executePlan: session is missing its auth capability");
+            }
+            const analysisId = session.scope.analysisId;
+            const threadId = session.scope.threadId ?? null;
+            const raw = unwrapOrThrow(await loadPlan(pool, planId, { analysisId }));
+            if (!raw)
+                throw new PlanNotFoundError(planId);
+            const parsed = AnalysisPlanSchema.safeParse(raw);
+            if (!parsed.success)
+                throw new PlanMalformedError(planId);
+            const plan = parsed.data;
+            const result = validatePlan(plan);
+            if (!result.valid) {
+                throw new PlanValidationError(planId, result.errors);
+            }
+            // (1) Dedup pre-check — common case is the user re-clicked Execute on
+            // an in-flight plan. A hit avoids both the authorization and the DBOS
+            // startWorkflow.
+            const existingPre = unwrapOrThrow(await queryActiveRun(pool, analysisId, planId));
+            if (existingPre) {
+                await emitRunCard(analysisId, existingPre.runId);
+                return ok({ runId: existingPre.runId });
+            }
+            // (2) Reserve the dedup slot by inserting the run row BEFORE authorizing.
+            // The partial-unique index is the race backstop for two callers that both
+            // passed the pre-check; the loser returns the winner's runId without
+            // having authorized — there is nothing to revoke. The authorization handle is left
+            // null here and populated by the authorizer, whose UPDATE lands
+            // because the row now exists.
+            const runId = randomUUID();
+            try {
+                // On the dedup collision `insertRun` throws `RunDedupCollisionError`
+                // (a control-flow signal that rides out of the ResultAsync as a
+                // rejection) — `unwrapOrThrow` never sees it; the catch below does.
+                unwrapOrThrow(await insertRun(pool, {
+                    runId,
+                    analysisId,
+                    threadId,
+                    workflowName: "executeAnalysis",
+                    planId,
+                }));
+            }
+            catch (err) {
+                if (isDedupCollision(err)) {
+                    const existing = unwrapOrThrow(await queryActiveRun(pool, analysisId, planId));
+                    if (existing) {
+                        await emitRunCard(analysisId, existing.runId);
+                        return ok({ runId: existing.runId });
+                    }
+                }
+                throw err;
+            }
+            // (3) Authorize the run. The row exists, so the authorizer's persisted handle
+            // persists. On failure, mark the reserved row failed — releasing the
+            // partial-unique slot so a retry can re-run — and rethrow.
+            let authorization;
+            try {
+                authorization = await runAuthorizer.authorize({
+                    auth: session.auth,
+                    scope: session.scope,
+                    provenance: session.provenance,
+                    frame: { runId },
+                });
+            }
+            catch (err) {
+                await updateRunStatus(pool, runId, "failed", "run authorization failed").match(() => { }, () => { });
+                throw err;
+            }
+            const { runSession } = authorization;
+            const planSummary = plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
+            const workflowInput = {
+                analysisId,
+                planId,
+                planSummary,
+                threadId,
+                steps: plan.steps.map((s) => ({
+                    id: s.id,
+                    depends_on: s.depends_on ?? [],
+                })),
+                promptByStepId: Object.fromEntries(plan.steps.map((s) => [s.id, renderStepPrompt(s)])),
+                agentByStepId: Object.fromEntries(plan.steps.map((s) => [s.id, s.agent ?? "unknown"])),
+                resourcesByStepId: Object.fromEntries(plan.steps.map((s) => {
+                    if (!s.resources) {
+                        throw new Error(`Step "${s.id}" has no resources — validatePlan should have rejected this plan`);
+                    }
+                    return [s.id, s.resources];
+                })),
+                timeoutByStepId: Object.fromEntries(plan.steps.filter((s) => s.timeout !== undefined).map((s) => [s.id, s.timeout])),
+                budget: resourcePolicy?.budget,
+                runSession,
+                ownsMandate: authorization.ownsMandate, // oss-core-managed-ok
+            };
+            // (4) Dispatch the workflow. `workflowId = runId` — both are the same
+            // bare UUID. On failure after insert + authorize, revoke the authorization and
+            // mark the row failed.
+            try {
+                await runLauncher.launch(executeAnalysisWorkflow, { workflowId: runId }, workflowInput);
+            }
+            catch (err) {
+                await runAuthorizer.revoke(authorization, "workflow-start-failed").catch(() => { });
+                await updateRunStatus(pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
+                throw err;
+            }
+            await emitRunCard(analysisId, runId);
+            return ok({ runId });
+        },
+    });
+}