@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/tools/execute-analysis.js

@@ -3,18 +3,21 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import { randomUUID } from "node:crypto";
-import { err, ok } from "neverthrow";
+import { err, ok, okAsync, ResultAsync } from "neverthrow";
 import { z } from "zod";
+import { capabilityDataRequirement } from "../agents/sandbox-catalog.js";
 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 { readInstalledDatasetIds } from "./sandbox/list-available-refs.js";
+import { tryQuery, withTransaction } from "../lib/db-result.js";
 import { deliverNotice, passGate } from "../lib/hooks.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { buildRunCardData } from "../memory/card-builders.js";
 import { formatQuery, parseQuery } from "../sandbox/package-identity.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
 import { validatePlan } from "../schemas/validate-plan.js";
-import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, suspendAnalysis, updateRunStatus, upsertPlan } from "../state/index.js";
+import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, queryNewestPlanRun, reserveRunById, suspendAnalysis, 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";
@@ -92,6 +95,66 @@ export class PlanPackagesMissingError extends Error {
         this.name = "PlanPackagesMissingError";
     }
 }
+/**
+ * A declared dataset that the reference store does not hold, found at the pre-launch pass. The
+ * message names the datasets and no remedy command — the remedy belongs to the embedder, and its
+ * wrapper appends it.
+ */
+export class PlanReferencesMissingError extends Error {
+    missing;
+    unavailable;
+    constructor(missing, unavailable) {
+        const parts = [
+            // The store-level reason FIRST, for the same reason the package error leads with it:
+            // with an unanswerable store, no per-dataset claim below it is trustworthy.
+            unavailable !== undefined
+                ? `the store cannot answer (${unavailable}) — this says nothing about the datasets themselves, so do not re-request them`
+                : null,
+            missing.length > 0 ? `the store does not hold: ${missing.join(", ")}` : null,
+        ].filter((part) => part !== null);
+        super(`The reference data of this plan is not installed — ${parts.join(" ")}`);
+        this.missing = missing;
+        this.unavailable = unavailable;
+        this.name = "PlanReferencesMissingError";
+    }
+}
+/**
+ * Resolve the reference data that the capabilities of a plan declare, before the run reserves
+ * anything. A step names its capability, the agent of the step holds the declaration, and the
+ * declaration names catalog ids. An absent dataset refuses the launch with the ids named.
+ *
+ * Nothing is read when no step declares a requirement: the common plan touches no store at all.
+ *
+ * @returns How many datasets reached the store. Zero says that nothing was checked — a plan that
+ * declares none, or a store the embedder bound nowhere — which a launch record must be able to tell
+ * from a checked launch.
+ */
+async function resolvePlanReferences(refStorePath, plan) {
+    const declared = new Set();
+    for (const step of plan.steps) {
+        if (!step.agent || !step.capability)
+            continue;
+        for (const dataset of capabilityDataRequirement(step.agent, step.capability))
+            declared.add(dataset);
+    }
+    if (declared.size === 0)
+        return ok(0);
+    // An unbound store is an embedder that provisions reference data some other way, exactly as an
+    // unbound farm seam leaves the package pass at once. Reading the container path here instead
+    // would fail on every host and refuse every launch that declares a capability.
+    if (refStorePath === undefined)
+        return ok(0);
+    const installed = await readInstalledDatasetIds({ refStorePath });
+    if (installed === undefined) {
+        // The path is named, because the reason is a fault of the environment and the reader has to
+        // know WHICH store did not answer. A bare "could not be read" sends a caller round in circles.
+        return err({ type: "references_missing", missing: [], unavailable: `the reference store at ${refStorePath} could not be read` });
+    }
+    const missing = [...declared].filter((dataset) => !installed.has(dataset)).sort();
+    if (missing.length > 0)
+        return err({ type: "references_missing", missing });
+    return ok(declared.size);
+}
 /**
  * Link the packages of the plan into the farm of the analysis, before the
  * run reserves anything. The linked set is the union of the queries of each
@@ -103,9 +166,9 @@ export class PlanPackagesMissingError extends Error {
  * is what the launch record must carry to tell a checked launch from an
  * unchecked one.
  */
-async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
+async function linkPlanPackages(extendAnalysisFarm, analysisId, planId, plan) {
     if (!extendAnalysisFarm)
-        return 0;
+        return ok(0);
     // The union dedupes EQUAL queries only: two entries are one ask when their
     // spelling, their track, and their version are equal. A bare entry beside a
     // qualified entry of one spelling stays two asks, because the bare one
@@ -118,7 +181,12 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
             if (parsed.isErr()) {
                 // `validatePlan` parsed every entry of this plan already, thus a
                 // refusal here means that the two readers disagree.
-                throw new Error(`Step "${step.id}" carries the package entry "${entry}", which the plan validation should have refused`);
+                return err({
+                    type: "plan_invalid",
+                    planId,
+                    malformed: false,
+                    errors: [`Step "${step.id}" carries the package entry "${entry}", which the plan validation should have refused`],
+                });
             }
             const query = parsed.value;
             const key = formatQuery(query);
@@ -128,12 +196,12 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     }
     const queries = [...union.values()];
     if (queries.length === 0)
-        return 0;
+        return ok(0);
     const linked = await callExtendAnalysisFarm(extendAnalysisFarm, analysisId, queries);
     if (linked.isErr()) {
         // A call that gave no answer is an `unavailable` answer, not a driver
         // error: the planner can act on "the store cannot answer".
-        throw new PlanPackagesMissingError([], [], linked.error);
+        return err({ type: "packages_missing", missing: [], collisions: [], unavailable: linked.error });
     }
     const outcomes = linked.value;
     // An `unavailable` outcome preempts everything: the link pass could not
@@ -141,7 +209,7 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     // absence list would be a fabrication. One reason covers the batch.
     const unavailable = outcomes.find((o) => o.kind === "unavailable");
     if (unavailable !== undefined) {
-        throw new PlanPackagesMissingError([], [], unavailable.reason);
+        return err({ type: "packages_missing", missing: [], collisions: [], unavailable: unavailable.reason });
     }
     // A seam-supplied detail classifies the miss in host terms (in flight,
     // failed with its reason, never requested), and it rides beside the name
@@ -165,13 +233,32 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
         `; when the two directories are one spelling in two tracks, name the track in the plan, as ` +
         `${formatQuery({ spelling: o.spelling, track: "python" })} or ${formatQuery({ spelling: o.spelling, track: "r" })}`);
     if (missing.length > 0 || collisions.length > 0) {
-        throw new PlanPackagesMissingError(missing, collisions);
+        return err({ type: "packages_missing", missing, collisions });
     }
-    return queries.length;
+    return ok(queries.length);
 }
 function planSummary(plan) {
     return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
 }
+/**
+ * The resources of each step. `validatePlan` refuses a step without them, thus
+ * a missing entry here means that the two readers disagree.
+ */
+function stepResources(planId, plan) {
+    const byStepId = {};
+    for (const step of plan.steps) {
+        if (!step.resources) {
+            return err({
+                type: "plan_invalid",
+                planId,
+                malformed: false,
+                errors: [`Step "${step.id}" has no resources — validation should have rejected it`],
+            });
+        }
+        byStepId[step.id] = step.resources;
+    }
+    return ok(byStepId);
+}
 function workflowInput(planId, plan, args) {
     return {
         analysisId: args.analysisId,
@@ -181,11 +268,7 @@ function workflowInput(planId, plan, args) {
         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];
-        })),
+        resourcesByStepId: args.resourcesByStepId,
         timeoutByStepId: Object.fromEntries(plan.steps.filter((step) => step.timeout !== undefined).map((step) => [step.id, step.timeout])),
         budget: args.budget,
         runSession: args.runSession,
@@ -193,14 +276,21 @@ function workflowInput(planId, plan, args) {
         synthesisEnabled: args.synthesisEnabled,
     };
 }
-function validateStoredPlan(raw, planId) {
+function parseStoredPlan(raw, planId) {
     const parsed = AnalysisPlanSchema.safeParse(raw);
     if (!parsed.success)
-        throw new PlanMalformedError(planId);
+        return err({ type: "plan_invalid", planId, malformed: true, errors: [] });
     const result = validatePlan(parsed.data);
     if (!result.valid)
-        throw new PlanValidationError(planId, result.errors);
-    return parsed.data;
+        return err({ type: "plan_invalid", planId, malformed: false, errors: result.errors });
+    return ok(parsed.data);
+}
+/** The error that a tool body throws for a stored plan that the parse refused. */
+function validateStoredPlan(raw, planId) {
+    const parsed = parseStoredPlan(raw, planId);
+    if (parsed.isErr())
+        return throwLaunchRefusal(parsed.error, planId);
+    return parsed.value;
 }
 function adHocTitle(request) {
     const compact = request.trim().replace(/\s+/g, " ");
@@ -259,6 +349,7 @@ export function buildAdHocPlan(request, route, createdAt = new Date().toISOStrin
                 status: "pending",
                 resources: route.resources,
                 agent: route.agentId,
+                ...(route.capability ? { capability: route.capability } : {}),
                 maxSteps: meta?.defaultMaxSteps ?? DEFAULT_SANDBOX_MAX_STEPS,
             },
         ],
@@ -320,8 +411,227 @@ async function persistedAdHocPlan(deps, args) {
         throw new Error(`Internal ad hoc plan ${args.planId} could not be reloaded`);
     return validateStoredPlan(stored, args.planId);
 }
-export function createExecuteAnalysisTool(deps) {
+/**
+ * The half of a launch that the plan mode and the ad hoc mode share: the link pass, the reservation,
+ * the authorization, and the workflow start. It gives each outcome as a `Result`.
+ */
+async function launchReservedRun(deps, args) {
     const logger = (deps.logger ?? createNoopLogger()).named("execute-analysis-tool");
+    const { session, planId, plan } = args;
+    const analysisId = session.scope.analysisId;
+    const threadId = session.scope.threadId ?? null;
+    const resources = stepResources(planId, plan);
+    if (resources.isErr())
+        return err(resources.error);
+    // Reference data first: it is a read, so it costs nothing to learn before the farm link
+    // writes. Both passes come before the run reserves anything, thus a miss of either leaves no
+    // run row and no revoked authorization behind.
+    const references = await resolvePlanReferences(deps.refStorePath, plan);
+    if (references.isErr())
+        return err(references.error);
+    // The link pass comes before the run reserves anything, thus a pool
+    // miss leaves no run row and no revoked authorization behind.
+    const linked = await linkPlanPackages(deps.extendAnalysisFarm, analysisId, planId, plan);
+    if (linked.isErr())
+        return err(linked.error);
+    const packageQueries = linked.value;
+    const reservation = await args.reserve({ analysisId, threadId });
+    if (reservation.isErr())
+        return err(reservation.error);
+    if (!reservation.value.started)
+        return reservation;
+    const runId = reservation.value.runId;
+    const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
+        auth: session.auth,
+        scope: session.scope,
+        provenance: session.provenance,
+        frame: { runId },
+    }));
+    if (authorized.isErr()) {
+        // The refusal ends the run before a workflow exists, thus the
+        // reserved row must not stay `running`.
+        const { kind, reason } = authorized.error;
+        if (kind === "suspended") {
+            await updateRunStatus(deps.pool, runId, "suspended_insufficient_funds", reason).match(() => { }, () => { });
+            const suspension = await suspendAnalysis(deps.pool, analysisId);
+            if (suspension.isErr())
+                return err({ type: "store_failed", cause: suspension.error });
+            return err({ type: "suspended", reason });
+        }
+        await updateRunStatus(deps.pool, runId, "failed", reason).match(() => { }, () => { });
+        return err({ type: "not_authorized", reason });
+    }
+    const authorization = authorized.value;
+    const wfInput = workflowInput(planId, plan, {
+        analysisId,
+        threadId,
+        runSession: authorization.runSession,
+        ownsMandate: authorization.ownsMandate,
+        budget: deps.resourcePolicy?.budget,
+        synthesisEnabled: args.mode === "plan",
+        resourcesByStepId: resources.value,
+    });
+    try {
+        await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
+    }
+    catch (cause) {
+        await deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, "workflow-start-failed"));
+        // A failed write leaves the row `running` with no workflow. The boot repair (`reconcileOrphanedRuns`) fails it.
+        await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, (error) => logger.warn("the failed status of a run whose start failed was not written", { runId, ...logger.errorFields(error) }));
+        return err({ type: "launch_failed", cause });
+    }
+    logger.info("analysis launched", { analysisId, runId, planId, mode: args.mode, packageQueries });
+    return ok({ runId, started: true });
+}
+function staleViewOf(newest, seen) {
+    if (newest !== null)
+        return newest === seen ? null : { type: "newer", runId: newest };
+    return seen === null ? null : { type: "missing", runId: seen };
+}
+/** A stale view starts nothing: it gives the newest run with `started: false`, or `run_not_found` when the plan has no run. */
+function refuseStaleView(view) {
+    return view.type === "newer" ? ok({ runId: view.runId, started: false }) : err({ type: "run_not_found", runId: view.runId });
+}
+function lockPlanLaunch(client, planId) {
+    return tryQuery("execute-analysis.lockPlanLaunch", () => client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [`plan-launch:${planId}`])).map(() => undefined);
+}
+/**
+ * Reserve a fresh run for a plan under the lock of the plan, thus the reservations of one plan occur one
+ * after the other. A caller with a `newestRunId` reserves nothing when the newest run of the plan is a
+ * different run. The new row starts after the newest start, thus it is the newest run of the plan. A
+ * concurrent launch of the same plan can hold the active-plan slot, and its run is the answer.
+ */
+async function reservePlanRun(deps, args) {
+    const runId = randomUUID();
+    try {
+        const reserved = await withTransaction(deps.pool, "execute-analysis.reservePlanRun", (client) => lockPlanLaunch(client, args.planId)
+            .andThen(() => queryNewestPlanRun(client, { analysisId: args.analysisId, planId: args.planId }))
+            .andThen((newest) => {
+            const stale = args.newestRunId === undefined ? null : staleViewOf(newest?.runId ?? null, args.newestRunId);
+            if (stale)
+                return okAsync({ type: "stale", view: stale });
+            const startedAt = newest === null ? undefined : new Date(Math.max(Date.now(), Date.parse(newest.startedAt) + 1)).toISOString();
+            return insertRun(client, {
+                runId,
+                analysisId: args.analysisId,
+                threadId: args.threadId,
+                workflowName: "executeAnalysis",
+                planId: args.planId,
+                ...(startedAt === undefined ? {} : { startedAt }),
+            }).map(() => ({ type: "inserted" }));
+        }));
+        if (reserved.isErr())
+            return err({ type: "store_failed", cause: reserved.error });
+        if (reserved.value.type === "stale")
+            return refuseStaleView(reserved.value.view);
+        return ok({ runId, started: true });
+    }
+    catch (cause) {
+        // `insertRun` rejects its promise on a collision of the active-plan index, and on nothing else. The
+        // transaction is rolled back and released by now, so the read goes to the pool.
+        if (!isDedupCollision(cause))
+            return err({ type: "store_failed", cause });
+        const active = await queryActiveRun(deps.pool, args.analysisId, args.planId);
+        if (active.isErr())
+            return err({ type: "store_failed", cause: active.error });
+        // The slot was free again when the read ran, so no run holds it and the collision stays the cause.
+        if (!active.value)
+            return err({ type: "store_failed", cause });
+        return ok({ runId: active.value.runId, started: false });
+    }
+}
+/**
+ * Reserve the run of an ad hoc call under its deterministic id, and treat a reservation that exists
+ * as a redelivery of the same call.
+ */
+async function reserveAdHocRun(deps, args) {
+    try {
+        const reservation = await reserveRunById(deps.pool, {
+            runId: args.runId,
+            analysisId: args.analysisId,
+            threadId: args.threadId,
+            workflowName: "executeAnalysis",
+            planId: args.planId,
+        });
+        if (reservation.isErr())
+            return err({ type: "store_failed", cause: reservation.error });
+        return ok({ runId: reservation.value.row.runId, started: reservation.value.inserted });
+    }
+    catch (cause) {
+        // `reserveRunById` rejects its promise when the run id belongs to another analysis.
+        return err({ type: "store_failed", cause });
+    }
+}
+async function launchStoredPlan(deps, input) {
+    const { session, planId, newestRunId } = input;
+    const analysisId = session.scope.analysisId;
+    const raw = await loadPlan(deps.pool, planId, { analysisId });
+    if (raw.isErr())
+        return err({ type: "store_failed", cause: raw.error });
+    if (!raw.value)
+        return err({ type: "plan_not_found", planId });
+    const plan = parseStoredPlan(raw.value, planId);
+    if (plan.isErr())
+        return err(plan.error);
+    if (newestRunId !== undefined) {
+        const newest = await queryNewestPlanRun(deps.pool, { analysisId, planId });
+        if (newest.isErr())
+            return err({ type: "store_failed", cause: newest.error });
+        const stale = staleViewOf(newest.value?.runId ?? null, newestRunId);
+        if (stale)
+            return refuseStaleView(stale);
+    }
+    const active = await queryActiveRun(deps.pool, analysisId, planId);
+    if (active.isErr())
+        return err({ type: "store_failed", cause: active.error });
+    if (active.value)
+        return ok({ runId: active.value.runId, started: false });
+    return launchReservedRun(deps, {
+        session,
+        planId,
+        plan: plan.value,
+        mode: "plan",
+        reserve: (frame) => reservePlanRun(deps, { ...frame, planId, ...(newestRunId === undefined ? {} : { newestRunId }) }),
+    });
+}
+/**
+ * Start the run of a stored plan. It reads the plan under the analysis of the session, validates it,
+ * compares the newest run of the plan with `newestRunId`, links its packages, reserves a run,
+ * authorizes it, and starts the workflow. It gives the run id, or the refusal, and it emits no chat
+ * part. `started` is false when this call started nothing: a run of the plan was already active, or the
+ * newest run of the plan is not the run that the caller saw. `runId` then names that run.
+ *
+ * This is an API boundary: a host calls it outside a tool body, thus no outcome above rejects the
+ * promise.
+ */
+export function launchPlanRun(deps, input) {
+    return new ResultAsync(launchStoredPlan(deps, input));
+}
+/** Throw the error that the tool body threw before the launch gave a `Result`. */
+function throwLaunchRefusal(refusal, planId) {
+    switch (refusal.type) {
+        case "run_not_found":
+            throw new Error(`Plan ${planId} has no run ${refusal.runId}`);
+        case "plan_not_found":
+            throw new PlanNotFoundError(refusal.planId);
+        case "plan_invalid":
+            throw refusal.malformed ? new PlanMalformedError(refusal.planId) : new PlanValidationError(refusal.planId, refusal.errors);
+        case "packages_missing":
+            throw new PlanPackagesMissingError(refusal.missing, refusal.collisions, refusal.unavailable);
+        case "references_missing":
+            throw new PlanReferencesMissingError(refusal.missing, refusal.unavailable);
+        case "store_failed":
+            return unwrapOrThrow(err(refusal.cause));
+        case "launch_failed":
+            // The cause is the value that the launcher threw, and the tool rethrows it unchanged.
+            throw refusal.cause;
+        default: {
+            const unreachable = refusal;
+            return unreachable;
+        }
+    }
+}
+export function createExecuteAnalysisTool(deps) {
     return defineTool({
         id: "execute_analysis",
         description: "Launch analysis computation asynchronously. Use mode=plan with the planId only after the user approved that stored plan. " +
@@ -340,104 +650,36 @@ export function createExecuteAnalysisTool(deps) {
             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 });
-            }
-            // The link pass comes before the run reserves anything, thus a pool
-            // miss leaves no run row and no revoked authorization behind.
-            const packageQueries = await linkPlanPackages(deps.extendAnalysisFarm, analysisId, plan);
-            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",
+            const launch = async () => {
+                if (input.mode === "plan")
+                    return launchPlanRun(deps, { session: ctx.session, planId });
+                const plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
+                const runId = adHocRunId(analysisId, ctx.invocationId);
+                return launchReservedRun(deps, {
+                    session: ctx.session,
                     planId,
-                }));
-                if (!reservation.inserted) {
-                    await emitRunCard(reservation.row.runId);
-                    return ok({ runId: reservation.row.runId, status: "in_progress" });
-                }
-            }
-            const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
-                auth: ctx.session.auth,
-                scope: ctx.session.scope,
-                provenance: ctx.session.provenance,
-                frame: { runId },
-            }));
-            if (authorized.isErr()) {
-                // The refusal ends the run before a workflow exists, thus the
-                // reserved row must not stay `running`.
-                const { kind, reason } = authorized.error;
-                if (kind === "suspended") {
-                    await updateRunStatus(deps.pool, runId, "canceled", reason).match(() => { }, () => { });
-                    unwrapOrThrow(await suspendAnalysis(deps.pool, analysisId));
-                    return err({ error: `The analysis is suspended: ${reason}`, retryable: false });
-                }
-                await updateRunStatus(deps.pool, runId, "failed", reason).match(() => { }, () => { });
-                return err({ error: `The run was not authorized: ${reason}`, retryable: false });
-            }
-            const authorization = authorized.value;
-            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 deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, "workflow-start-failed"));
-                await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
-                throw error;
+                    plan,
+                    mode: "adhoc",
+                    reserve: (frame) => reserveAdHocRun(deps, { ...frame, planId, runId }),
+                });
+            };
+            const launched = await launch();
+            if (launched.isErr()) {
+                const refusal = launched.error;
+                if (refusal.type === "suspended")
+                    return err({ error: `The analysis is suspended: ${refusal.reason}`, retryable: false });
+                if (refusal.type === "not_authorized")
+                    return err({ error: `The run was not authorized: ${refusal.reason}`, retryable: false });
+                return throwLaunchRefusal(refusal, planId);
             }
-            logger.info("analysis launched", { analysisId, runId, planId, mode: input.mode, packageQueries });
-            await emitRunCard(runId);
-            return ok({ runId, status: "in_progress" });
+            await emitRunCard(launched.value.runId);
+            return ok({ runId: launched.value.runId, status: "in_progress" });
         },
     });
 }

package/dist/tools/knowledge/check.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `knowledge_check` — the drafted steps against the rules, once, before
+ * `submit_plan`. A violation names the rule and the permitted alternatives.
+ * The planner revises once. There is no loop: the host counts the calls of
+ * one plan generation, and past `CHECK_CALL_LIMIT` the tool answers with a
+ * typed refusal and never reaches the service. A small model that cannot
+ * satisfy a finding otherwise rephrases the step until the plan times out.
+ */
+import type { CheckResponse, KnowledgeClient, KnowledgeRejected, KnowledgeSnapshotMismatch, KnowledgeUnavailable } from "./client.js";
+import type { SnapshotPin } from "./pin.js";
+export interface KnowledgeCheckDeps {
+    readonly client: KnowledgeClient;
+    /** The release the plan pinned on its first recommend answer. The check sends it, thus another release refuses the call. */
+    readonly pin?: SnapshotPin;
+}
+export type KnowledgeCheckOutput = CheckResponse | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch;
+/** The checks one plan generation may run. Two is a draft and one revision; the third is slack. */
+export declare const CHECK_CALL_LIMIT = 3;
+export declare function createKnowledgeCheckTool(deps: KnowledgeCheckDeps): import("../define-tool.js").Tool<{
+    question: "enrichment" | "differential_expression" | "qc" | "full_plan" | "tf_activity" | "deconvolution" | "coexpression" | "clustering" | "survival" | "signature_scoring";
+    modality: "bulk_rna_seq";
+    data_state: "fastq" | "counts" | "tpm_or_fpkm" | "log_normalized";
+    organism: "other" | "human" | "mouse";
+    n_groups: number;
+    n_per_group_min: number;
+    n_per_group_max: number;
+    paired: boolean;
+    batch: "none" | "known_balanced" | "known_confounded" | "known_unbalanced" | "suspected";
+    steps: {
+        step_type: "normalize" | "enrichment" | "differential_expression" | "report" | "tf_activity" | "deconvolution" | "coexpression" | "clustering" | "survival" | "signature_scoring" | "variance_partition" | "pathway_activity" | "transcript_level" | "annotation" | "cohort_assembly" | "qc_sample_structure" | "filter_low_counts" | "model_design" | "shrink_lfc" | "multiple_testing";
+        method: string;
+        method_id?: string | undefined;
+        package?: string | undefined;
+        parameters?: {
+            name: string;
+            value: string | number | boolean;
+        }[] | undefined;
+        outcome?: string | undefined;
+    }[];
+    count_source?: "unknown" | "salmon" | "kallisto" | "star_featurecounts" | "rsem" | undefined;
+    import_state?: "unknown" | "quantifications" | "estimated_counts_with_lengths" | "corrected_counts" | "integer_counts" | undefined;
+    n_samples?: number | undefined;
+    n_events?: number | undefined;
+    blocking_factor?: "other" | "individual" | "cell_line" | "litter" | "site" | "pair" | null | undefined;
+    block_structure?: "crossed" | "nested" | undefined;
+    covariates?: ("other" | "technical" | "sex" | "age" | "clinical")[] | undefined;
+    n_timepoints?: number | null | undefined;
+    continuous_predictor?: "other" | "score" | "time" | "age" | "dose" | null | undefined;
+    technical_replicates?: boolean | undefined;
+    sample_exclusions?: boolean | undefined;
+    feature_level?: "gene" | "exon" | "transcript" | undefined;
+    library_type?: "unknown" | "total" | "polyA" | "three_prime" | undefined;
+    strandedness?: "unknown" | "verified" | "declared_unverified" | undefined;
+    interaction?: boolean | undefined;
+    classifier?: boolean | undefined;
+    extra_analyses?: ("tf_activity" | "deconvolution" | "coexpression" | "clustering" | "survival" | "signature_scoring" | "variance_partition" | "pathway_activity" | "transcript_level" | "annotation")[] | undefined;
+    preferred_language?: "R" | "python" | undefined;
+    enrichment_input?: "ranked_list" | "gene_list" | "sample_scores" | undefined;
+    quality_flags?: ("low_depth_sample" | "outlier_sample" | "sample_identity_doubt" | "high_duplication" | "degraded_rna")[] | undefined;
+}, KnowledgeCheckOutput>;