@inflexa-ai/harness 0.12.0 → 0.14.0

package/dist/tools/bio/target-safety.d.ts

@@ -0,0 +1,59 @@
+/**
+ * targetSafety — target-level, mechanism-based safety liability from the two
+ * sources that carry it: the curated secondary-pharmacology panel that ships
+ * with the harness, and Open Targets' curated liabilities.
+ *
+ * These were `check_safety_panel` and `opentargets({action:'safety'})`, and the
+ * panel tool's own description instructed calling them together — a pairing
+ * every caller had to remember, expressed in prose that had already gone stale
+ * (it named two tools that no longer exist). Both are keyed on the same target
+ * and answer the same question, so the pairing belongs in the tool.
+ *
+ * Identifier resolution is the tool's job, not the caller's: Open Targets
+ * accepts ONLY an Ensembl gene id, and it is taken from the panel entry when
+ * there is one and resolved from the gene symbol when there is not.
+ */
+import { type SafetyTarget } from "../../data/safety-panel-schema.js";
+import { type SafetyLiability } from "../lib/opentargets-client.js";
+declare const SOURCES: readonly ["panel", "opentargets"];
+type Source = (typeof SOURCES)[number];
+type ConcreteType = "chembl_id" | "gene_symbol" | "uniprot" | "ensembl_id";
+interface TargetRow {
+    input: string;
+    identifierType: ConcreteType;
+    /** The Ensembl id Open Targets was queried with, when one could be obtained. */
+    ensemblId?: string;
+    panelEntry?: SafetyTarget | null;
+    liabilities?: SafetyLiability[];
+    /** Liabilities Open Targets held before `liabilityLimit` trimmed them. */
+    liabilityCount?: number;
+    /** Why the Open Targets half is absent for this identifier, when it is. */
+    opentargetsNote?: string;
+}
+interface SourceOutcome {
+    source: Source;
+    status: "ok" | "no_data" | "unavailable";
+    /** Identifiers this source returned something for. */
+    matched: number;
+    detail?: string;
+}
+export declare const targetSafetyTool: import("../define-tool.js").Tool<{
+    identifiers: string[];
+    identifierType?: "auto" | "gene_symbol" | "uniprot" | "chembl_id" | "ensembl_id" | undefined;
+    sources?: ("opentargets" | "panel")[] | undefined;
+    filterOrgan?: "hematologic" | "metabolic" | "immune" | "hepatic" | "cns" | "renal" | "respiratory" | "cardiac" | "gi" | undefined;
+    minSeverity?: "high" | "medium" | "low" | undefined;
+    liabilityLimit?: number | undefined;
+}, {
+    perSource: SourceOutcome[];
+    summary: {
+        totalInput: number;
+        panelMatched: number;
+        bySeverity: Record<"high" | "medium" | "low", number>;
+        byOrgan: Record<string, number>;
+        openTargetsWithLiabilities: number;
+    };
+    targets: TargetRow[];
+    panelVersion: string;
+}>;
+export {};

package/dist/tools/bio/target-safety.js

@@ -0,0 +1,191 @@
+/**
+ * targetSafety — target-level, mechanism-based safety liability from the two
+ * sources that carry it: the curated secondary-pharmacology panel that ships
+ * with the harness, and Open Targets' curated liabilities.
+ *
+ * These were `check_safety_panel` and `opentargets({action:'safety'})`, and the
+ * panel tool's own description instructed calling them together — a pairing
+ * every caller had to remember, expressed in prose that had already gone stale
+ * (it named two tools that no longer exist). Both are keyed on the same target
+ * and answer the same question, so the pairing belongs in the tool.
+ *
+ * Identifier resolution is the tool's job, not the caller's: Open Targets
+ * accepts ONLY an Ensembl gene id, and it is taken from the panel entry when
+ * there is one and resolved from the gene symbol when there is not.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { CHEMBL_RE, ORGAN_SYSTEMS, SEVERITIES, SafetyPanelFileSchema, UNIPROT_RE, } from "../../data/safety-panel-schema.js";
+import panelData from "../../data/safety-panel.json" with { type: "json" };
+import { defineTool } from "../define-tool.js";
+import { resolveSymbolToEnsemblId } from "../lib/ensembl-client.js";
+import { getTargetSafetyLiabilities } from "../lib/opentargets-client.js";
+const PANEL = SafetyPanelFileSchema.parse(panelData);
+const BY_CHEMBL = new Map(PANEL.targets.map((t) => [t.chembl_id, t]));
+const BY_GENE = new Map(PANEL.targets.map((t) => [t.gene_symbol, t]));
+const BY_UNIPROT = new Map(PANEL.targets.map((t) => [t.uniprot, t]));
+const ENSG_RE = /^ENSG\d{11}$/;
+/** Ordered weakest → strongest so `minSeverity` can be a numeric floor. */
+const SEVERITY_ORDER = { low: 0, medium: 1, high: 2 };
+const SOURCES = ["panel", "opentargets"];
+/** Identifiers the panel can be swept for free; Open Targets costs a request each. */
+const MAX_PANEL_IDENTIFIERS = 200;
+const MAX_OPENTARGETS_IDENTIFIERS = 25;
+const DEFAULT_LIABILITY_LIMIT = 10;
+function detectType(id) {
+    if (CHEMBL_RE.test(id))
+        return "chembl_id";
+    if (ENSG_RE.test(id))
+        return "ensembl_id";
+    if (UNIPROT_RE.test(id))
+        return "uniprot";
+    return "gene_symbol";
+}
+function panelLookup(id, type) {
+    switch (type) {
+        case "chembl_id":
+            return BY_CHEMBL.get(id) ?? null;
+        case "gene_symbol":
+            return BY_GENE.get(id.toUpperCase()) ?? null;
+        case "uniprot":
+            return BY_UNIPROT.get(id) ?? null;
+        case "ensembl_id":
+            return PANEL.targets.find((t) => t.ensembl_gene_id === id) ?? null;
+    }
+}
+const inputSchema = z
+    .object({
+    identifiers: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(MAX_PANEL_IDENTIFIERS)
+        .describe(`Target identifiers, 1–${MAX_PANEL_IDENTIFIERS} — gene symbols, ChEMBL target IDs, UniProt accessions, or Ensembl gene IDs, mixed ` +
+        `freely. Capped at ${MAX_OPENTARGETS_IDENTIFIERS} when source 'opentargets' is included, since that source costs a request per target.`),
+    identifierType: z
+        .enum(["chembl_id", "gene_symbol", "uniprot", "ensembl_id", "auto"])
+        .optional()
+        .describe("Default 'auto', detecting per input by shape (CHEMBL…, ENSG…, UniProt accession, else a gene symbol). Set it only to force one reading."),
+    sources: z
+        .array(z.enum(SOURCES))
+        .min(1)
+        .optional()
+        .describe("Default BOTH — the panel is a local lookup with no request cost, and they cover different ground. " +
+        "'panel': the curated secondary-pharmacology panel — a fast first-pass off-target screen giving organ system, severity and clinical " +
+        "consequence with references. Finite and hand-curated, so absence is NOT evidence of safety. " +
+        "'opentargets': curated target liabilities — event, affected biosamples, direction of effect, source. Needs an Ensembl gene id, taken " +
+        "from the panel entry or resolved from the symbol for you."),
+    filterOrgan: z.enum(ORGAN_SYSTEMS).optional().describe("'panel' only. Keep only matches in this organ system, when screening one liability class."),
+    minSeverity: z.enum(SEVERITIES).optional().describe("'panel' only. Drop matches below this severity; default 'low'. Use 'high' to triage a large set."),
+    liabilityLimit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe(`'opentargets' only. Max liabilities per target (default ${DEFAULT_LIABILITY_LIMIT}, max 100); \`liabilityCount\` gives the true total.`),
+})
+    .refine((d) => (d.sources ?? [...SOURCES]).includes("opentargets") === false || d.identifiers.length <= MAX_OPENTARGETS_IDENTIFIERS, {
+    message: `identifiers is capped at ${MAX_OPENTARGETS_IDENTIFIERS} when source 'opentargets' is included (one request per target). ` +
+        `Either narrow the list, or pass sources: ['panel'] to sweep up to ${MAX_PANEL_IDENTIFIERS} against the local panel first and follow up on the hits.`,
+    path: ["identifiers"],
+});
+export const targetSafetyTool = defineTool({
+    id: "target_safety",
+    description: "TARGET-level, mechanism-based safety liability — the curated secondary-pharmacology panel and Open Targets' curated liabilities in one call. " +
+        "Judges what engaging a target is likely to do to an organ system, before any specific molecule exists. Identifiers may be gene symbols, ChEMBL " +
+        "target IDs, UniProt accessions or Ensembl gene IDs, mixed.\n" +
+        "This is the safety of the TARGET, not of a drug. For a marketed molecule's post-market adverse events use search_faers; for a chemical's " +
+        "toxicology use comptox; for what removing the gene does in vivo use gene_preclinical_profile.\n" +
+        "ABSENCE IS NOT SAFETY. The panel is finite and hand-curated, so no match means only 'not on the panel'; an empty Open Targets liability list " +
+        "means no CURATED liability, not that none exists. Both are valid no-data — do not retry. Read `perSource` and each row's `opentargetsNote`: a " +
+        "ChEMBL or UniProt identifier absent from the panel cannot be resolved to an Ensembl id, so its Open Targets half is skipped rather than empty.",
+    inputSchema,
+    execute: async ({ identifiers, identifierType, sources, filterOrgan, minSeverity, liabilityLimit }) => {
+        const selected = sources ?? [...SOURCES];
+        const wantPanel = selected.includes("panel");
+        const wantOpenTargets = selected.includes("opentargets");
+        const severityFloor = SEVERITY_ORDER[minSeverity ?? "low"];
+        const limit = liabilityLimit ?? DEFAULT_LIABILITY_LIMIT;
+        const rows = identifiers.map((input) => {
+            const type = identifierType && identifierType !== "auto" ? identifierType : detectType(input);
+            const row = { input, identifierType: type };
+            if (wantPanel) {
+                const entry = panelLookup(input, type);
+                const organMatches = !entry || !filterOrgan || entry.organ_system === filterOrgan;
+                const severityMatches = !entry || SEVERITY_ORDER[entry.severity] >= severityFloor;
+                row.panelEntry = entry && organMatches && severityMatches ? entry : null;
+            }
+            return row;
+        });
+        let opentargetsError;
+        if (wantOpenTargets) {
+            await Promise.all(rows.map(async (row) => {
+                // Open Targets takes an ENSG only. The panel entry carries one for
+                // free; a gene symbol can be resolved; a ChEMBL or UniProt id that
+                // is not on the panel cannot, and is skipped explicitly.
+                const panelEnsembl = panelLookup(row.input, row.identifierType)?.ensembl_gene_id;
+                let ensemblId = row.identifierType === "ensembl_id" ? row.input : (panelEnsembl ?? null);
+                if (!ensemblId && row.identifierType === "gene_symbol") {
+                    ensemblId = await resolveSymbolToEnsemblId(row.input);
+                    if (!ensemblId) {
+                        row.opentargetsNote = "gene symbol did not resolve to an Ensembl gene id";
+                        return;
+                    }
+                }
+                if (!ensemblId) {
+                    row.opentargetsNote = `no Ensembl gene id available for a ${row.identifierType} that is not on the panel`;
+                    return;
+                }
+                row.ensemblId = ensemblId;
+                try {
+                    const result = await getTargetSafetyLiabilities(ensemblId);
+                    if (!result) {
+                        row.opentargetsNote = "no Open Targets record for this Ensembl gene id";
+                        return;
+                    }
+                    row.liabilityCount = result.safetyLiabilities.length;
+                    row.liabilities = result.safetyLiabilities.slice(0, limit);
+                }
+                catch (error) {
+                    opentargetsError = error instanceof Error ? error.message : String(error);
+                    row.opentargetsNote = "Open Targets could not be reached";
+                }
+            }));
+        }
+        const bySeverity = { high: 0, medium: 0, low: 0 };
+        const byOrgan = {};
+        let panelMatched = 0;
+        for (const row of rows) {
+            if (!row.panelEntry)
+                continue;
+            panelMatched++;
+            bySeverity[row.panelEntry.severity]++;
+            byOrgan[row.panelEntry.organ_system] = (byOrgan[row.panelEntry.organ_system] ?? 0) + 1;
+        }
+        const withLiabilities = rows.filter((r) => (r.liabilities?.length ?? 0) > 0).length;
+        const perSource = [];
+        if (wantPanel) {
+            perSource.push({ source: "panel", status: panelMatched > 0 ? "ok" : "no_data", matched: panelMatched });
+        }
+        if (wantOpenTargets) {
+            perSource.push({
+                source: "opentargets",
+                status: opentargetsError ? "unavailable" : withLiabilities > 0 ? "ok" : "no_data",
+                matched: withLiabilities,
+                ...(opentargetsError ? { detail: opentargetsError } : {}),
+            });
+        }
+        return ok({
+            perSource,
+            summary: {
+                totalInput: identifiers.length,
+                panelMatched,
+                bySeverity,
+                byOrgan: byOrgan,
+                openTargetsWithLiabilities: withLiabilities,
+            },
+            targets: rows,
+            panelVersion: PANEL.panel_version,
+        });
+    },
+});

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

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`) — 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)`
@@ -39,11 +39,15 @@ export type ToolExecutionMode = "step" | "workflow" | "inline";
 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`, the `runStep`
+ * dependencies (see the harness-durable-runtime spec) — invocation identity,
+ * `session`, `signal`, `emit`, the `runStep`
  * durability seam (`passthroughStep` in chat, `DBOS.runStep` in workflows) a
  * tool uses to wrap its own durable work, and the `ask` user-approval seam.
  */
 export interface 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;

package/dist/tools/define-tool.js

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`) — 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)`

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

@@ -0,0 +1,44 @@
+/**
+ * Unified async edge for approved plans and explicitly requested one-step ad
+ * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
+ */
+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 { Logger } from "../lib/logger.js";
+import type { ChatProvider } from "../providers/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";
+type ExecuteAnalysisWorkflow = (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
+export interface ExecuteAnalysisToolDeps {
+    readonly pool: Pool;
+    readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
+    readonly runAuthorizer: RunAuthorizer;
+    readonly runLauncher: RunLauncher;
+    readonly resourcePolicy?: ResourcePolicy;
+    readonly utilityProvider: ChatProvider;
+    readonly utilityModel: string;
+    readonly logger?: Logger;
+}
+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 buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
+export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
+    mode: "plan" | "adhoc";
+    planId?: string | undefined;
+    request?: string | undefined;
+}, {
+    runId: string;
+    status: "in_progress";
+}>;
+export {};

package/dist/tools/execute-analysis.js

@@ -0,0 +1,252 @@
+/**
+ * Unified async edge for approved plans and explicitly requested one-step ad
+ * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
+ */
+import { randomUUID } from "node:crypto";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
+import { DEFAULT_SANDBOX_MAX_STEPS } from "../config/resource-limits.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { buildRunCardData } from "../memory/card-builders.js";
+import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
+import { validatePlan } from "../schemas/validate-plan.js";
+import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, updateRunStatus, upsertPlan } from "../state/index.js";
+import { routeAdHocRequest } from "./ad-hoc-router.js";
+import { adHocPlanId, adHocRunId } from "./analysis-invocation.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({
+    mode: z.enum(["plan", "adhoc"]),
+    planId: planIdSchema.optional(),
+    request: z.string().min(1).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (value.mode === "plan" && (value.planId === undefined || value.request !== undefined)) {
+        ctx.addIssue({ code: "custom", message: "plan mode requires planId and forbids request" });
+    }
+    if (value.mode === "adhoc" && (value.request === undefined || value.planId !== undefined)) {
+        ctx.addIssue({ code: "custom", message: "adhoc mode requires request and forbids planId" });
+    }
+});
+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");
+}
+function planSummary(plan) {
+    return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
+}
+function workflowInput(planId, plan, args) {
+    return {
+        analysisId: args.analysisId,
+        planId,
+        planSummary: planSummary(plan),
+        threadId: args.threadId,
+        steps: plan.steps.map((step) => ({ id: step.id, depends_on: step.depends_on ?? [] })),
+        planStepById: Object.fromEntries(plan.steps.map((step) => [step.id, step])),
+        agentByStepId: Object.fromEntries(plan.steps.map((step) => [step.id, step.agent ?? "unknown"])),
+        resourcesByStepId: Object.fromEntries(plan.steps.map((step) => {
+            if (!step.resources)
+                throw new Error(`Step "${step.id}" has no resources — validation should have rejected it`);
+            return [step.id, step.resources];
+        })),
+        timeoutByStepId: Object.fromEntries(plan.steps.filter((step) => step.timeout !== undefined).map((step) => [step.id, step.timeout])),
+        budget: args.budget,
+        runSession: args.runSession,
+        ownsMandate: args.ownsMandate,
+        synthesisEnabled: args.synthesisEnabled,
+    };
+}
+function validateStoredPlan(raw, planId) {
+    const parsed = AnalysisPlanSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new PlanMalformedError(planId);
+    const result = validatePlan(parsed.data);
+    if (!result.valid)
+        throw new PlanValidationError(planId, result.errors);
+    return parsed.data;
+}
+function adHocTitle(request) {
+    const compact = request.trim().replace(/\s+/g, " ");
+    return compact.length <= 80 ? compact : `${compact.slice(0, 77)}…`;
+}
+export function buildAdHocPlan(request, route, createdAt = new Date().toISOString()) {
+    const meta = SANDBOX_AGENT_META[route.agentId];
+    const plan = {
+        title: adHocTitle(request),
+        analytical_narrative: `Execute one targeted analysis step for the explicit request: ${request}`,
+        created_at: createdAt,
+        steps: [
+            {
+                id: "T1S1",
+                name: "Ad hoc analysis",
+                track: "ad-hoc",
+                step_type: "analysis",
+                question: request,
+                context: `Automatically routed to ${route.agentId}. Routing rationale: ${route.rationale}`,
+                constraints: [
+                    "Use the staged analysis inputs and persisted data profile; do not invent missing data.",
+                    "Complete only this targeted request; do not expand it into a multi-step plan.",
+                ],
+                acceptance_criteria: [
+                    "Persist every script needed to reproduce the computation.",
+                    "Persist machine-readable result file(s), even when the answer is a single scalar.",
+                    "Provide a direct result summary grounded in the persisted outputs.",
+                ],
+                caveats: route.fallbackClass ? [`Automatic routing fallback: ${route.fallbackClass}`] : undefined,
+                depends_on: [],
+                status: "pending",
+                resources: route.resources,
+                agent: route.agentId,
+                maxSteps: meta?.defaultMaxSteps ?? DEFAULT_SANDBOX_MAX_STEPS,
+            },
+        ],
+    };
+    return AnalysisPlanSchema.parse(plan);
+}
+async function persistedAdHocPlan(deps, args) {
+    const existing = unwrapOrThrow(await loadPlan(deps.pool, args.planId, { analysisId: args.analysisId }));
+    if (existing)
+        return validateStoredPlan(existing, args.planId);
+    const route = await routeAdHocRequest({
+        provider: deps.utilityProvider,
+        model: deps.utilityModel,
+        pool: deps.pool,
+        resourcePolicy: deps.resourcePolicy,
+        logger: deps.logger,
+    }, { analysisId: args.analysisId, request: args.request, session: args.ctx.session, signal: args.ctx.signal });
+    const candidate = buildAdHocPlan(args.request, route);
+    unwrapOrThrow(await upsertPlan(deps.pool, { planId: args.planId, analysisId: args.analysisId, plan: candidate }));
+    const stored = unwrapOrThrow(await loadPlan(deps.pool, args.planId, { analysisId: args.analysisId }));
+    if (!stored)
+        throw new Error(`Internal ad hoc plan ${args.planId} could not be reloaded`);
+    return validateStoredPlan(stored, args.planId);
+}
+export function createExecuteAnalysisTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("execute-analysis-tool");
+    return defineTool({
+        id: "execute_analysis",
+        description: "Launch analysis computation asynchronously. Use mode=plan with the planId only after the user approved that stored plan. " +
+            "Use mode=adhoc with the user's exact targeted computational request when they explicitly asked to run/compute/test/compare it; " +
+            "that explicit request is consent and needs no synthetic-plan approval. If computation is merely your suggestion, ask first. " +
+            "You never choose the sandbox specialist: ad hoc routing does that automatically. Returns runId with status=in_progress; inspect results on a later turn.",
+        inputSchema,
+        execute: async (input, ctx) => {
+            if (ctx.session.scope.kind !== "analysis")
+                throw new Error("execute_analysis requires an analysis-scoped session");
+            if (!ctx.session.auth)
+                throw new Error("execute_analysis: session is missing its auth capability");
+            const analysisId = ctx.session.scope.analysisId;
+            const threadId = ctx.session.scope.threadId ?? null;
+            const planId = input.mode === "plan" ? input.planId : adHocPlanId(analysisId, ctx.invocationId);
+            const emitRunCard = async (runId) => {
+                const card = await buildRunCardData(deps.pool, { planId, analysisId, runId }).unwrapOr(null);
+                if (card)
+                    await ctx.emit({ type: "data-run-card", source: ctx.session.provenance, data: card });
+            };
+            let plan;
+            if (input.mode === "plan") {
+                const raw = unwrapOrThrow(await loadPlan(deps.pool, planId, { analysisId }));
+                if (!raw)
+                    throw new PlanNotFoundError(planId);
+                plan = validateStoredPlan(raw, planId);
+                const active = unwrapOrThrow(await queryActiveRun(deps.pool, analysisId, planId));
+                if (active) {
+                    await emitRunCard(active.runId);
+                    return ok({ runId: active.runId, status: "in_progress" });
+                }
+            }
+            else {
+                plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
+            }
+            const runId = input.mode === "plan" ? randomUUID() : adHocRunId(analysisId, ctx.invocationId);
+            if (input.mode === "plan") {
+                try {
+                    unwrapOrThrow(await insertRun(deps.pool, {
+                        runId,
+                        analysisId,
+                        threadId,
+                        workflowName: "executeAnalysis",
+                        planId,
+                    }));
+                }
+                catch (error) {
+                    if (isDedupCollision(error)) {
+                        const active = unwrapOrThrow(await queryActiveRun(deps.pool, analysisId, planId));
+                        if (active) {
+                            await emitRunCard(active.runId);
+                            return ok({ runId: active.runId, status: "in_progress" });
+                        }
+                    }
+                    throw error;
+                }
+            }
+            else {
+                const reservation = unwrapOrThrow(await reserveRunById(deps.pool, {
+                    runId,
+                    analysisId,
+                    threadId,
+                    workflowName: "executeAnalysis",
+                    planId,
+                }));
+                if (!reservation.inserted) {
+                    await emitRunCard(reservation.row.runId);
+                    return ok({ runId: reservation.row.runId, status: "in_progress" });
+                }
+            }
+            let authorization;
+            try {
+                authorization = await deps.runAuthorizer.authorize({
+                    auth: ctx.session.auth,
+                    scope: ctx.session.scope,
+                    provenance: ctx.session.provenance,
+                    frame: { runId },
+                });
+            }
+            catch (error) {
+                await updateRunStatus(deps.pool, runId, "failed", "run authorization failed").match(() => { }, () => { });
+                throw error;
+            }
+            const wfInput = workflowInput(planId, plan, {
+                analysisId,
+                threadId,
+                runSession: authorization.runSession,
+                ownsMandate: authorization.ownsMandate,
+                budget: deps.resourcePolicy?.budget,
+                synthesisEnabled: input.mode === "plan",
+            });
+            try {
+                await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
+            }
+            catch (error) {
+                await deps.runAuthorizer.revoke(authorization, "workflow-start-failed").catch(() => { });
+                await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
+                throw error;
+            }
+            logger.info("analysis launched", { analysisId, runId, planId, mode: input.mode });
+            await emitRunCard(runId);
+            return ok({ runId, status: "in_progress" });
+        },
+    });
+}

package/dist/tools/iterate-report.js

@@ -130,7 +130,7 @@ const intentField = () => z
     .describe("Why this section exists and what to emphasize (e.g. 'hero — headline " +
     "finding', 'downplay if space is tight'). Emphasis, not layout — the " +
     "builder picks the components, sizing and alternation.");
-/** Free-text row transform — the reason to never pre-slice a CSV with `run_ephemeral`. */
+/** Free-text row transform — the reason to avoid launching analysis just to pre-slice a CSV. */
 const transformField = () => z
     .string()
     .optional()
@@ -138,7 +138,7 @@ const transformField = () => z
     "asset — filter, derive, aggregate, sort (e.g. 'filter padj < 0.05 and " +
     "abs(log2FoldChange) > 1', 'compute -log10(padj) as neg_log_padj', 'group " +
     "by sample and sum count', 'sort by mean_count desc, take top 50'). Use " +
-    "this instead of running `run_ephemeral` to pre-slice the file. The text " +
+    "this instead of launching an ad hoc analysis to pre-slice the file. The text " +
     "is rendered verbatim as a provenance footnote, so the data reads as " +
     "processed, not fabricated.");
 const SectionSchema = z.discriminatedUnion("type", [
@@ -359,14 +359,15 @@ treatment. Pass the composed brief as \`submit_report\`'s \`report\` field.
   their content reaches the report as prose you write into \`narrative\` /
   \`methods\` sections.
 
-## Do NOT reach for run_ephemeral first
+## Do NOT launch ad hoc analysis for a section transform
 - Not to peek at a CSV — pre-flight already parsed its columns and head rows.
 - Not to filter, slice, rank, or derive columns from a single CSV about to be
   rendered — \`chart.content.transform\` and \`table.content.transform\` do exactly
   that client-side, and the transform text renders as a provenance footnote.
-- run_ephemeral is only for computation no single section transform covers:
-  cross-file aggregation, statistics needing a real numerical library, or a
-  derived CSV the report then lists as a fresh source.
+- A durable ad hoc analysis is appropriate only when the user explicitly asks
+  for computation no single section transform covers: cross-file aggregation,
+  statistics needing a real numerical library, or a derived CSV the report then
+  lists as a fresh source.
 
 ## Choosing a section type
 - narrative — prose you wrote: context, story, interpretation.