@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/execute-analysis.js

@@ -3,24 +3,30 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import { randomUUID } from "node:crypto";
-import { err, ok, ResultAsync } from "neverthrow";
+import { err, ok, okAsync, ResultAsync } from "neverthrow";
+import { errorNameOf } from "../lib/thrown.js";
 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, queryRun, reserveRunById, updateRunStatus, upsertPlan, } from "../state/index.js";
 import { routeAdHocRequest } from "./ad-hoc-router.js";
-import { adHocPlanId, adHocRunId } from "./analysis-invocation.js";
+import { adHocPlanId, adHocRunId, callRunId, durableCallKey } from "./analysis-invocation.js";
 import { defineTool } from "./define-tool.js";
 import { queryPackages, readInventorySections } from "./sandbox/list-available-packages.js";
 import { callExtendAnalysisFarm } from "./sandbox/link-packages.js";
-const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
+import { PLAN_ID_RE } from "../contracts/schemas/chat-parts.js";
+import { collapseWhitespace } from "../lib/text.js";
+const planIdSchema = z.string().regex(PLAN_ID_RE, "planId must be a pln-<8hex> value");
 const inputSchema = z
     .object({
     mode: z
@@ -64,7 +70,7 @@ export class PlanValidationError extends Error {
     }
 }
 function isDedupCollision(err) {
-    return err instanceof RunDedupCollisionError || (err instanceof Error && err.name === "RunDedupCollisionError");
+    return err instanceof RunDedupCollisionError || errorNameOf(err) === "RunDedupCollisionError";
 }
 /**
  * A pool miss at the pre-launch link pass. The message names the missing
@@ -92,6 +98,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
@@ -166,7 +232,7 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, planId, plan) {
     const collisions = outcomes
         .filter((o) => o.kind === "collision")
         .map((o) => `${o.spelling} — two store directories claim it, ${o.storeDirs[0]} and ${o.storeDirs[1]}` +
-        `${o.detail === undefined ? "" : ` (${o.detail})`}` +
+        (o.detail === undefined ? "" : ` (${o.detail})`) +
         `; 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) {
@@ -202,14 +268,13 @@ function workflowInput(planId, plan, args) {
         planId,
         planSummary: planSummary(plan),
         threadId: args.threadId,
-        steps: plan.steps.map((step) => ({ id: step.id, depends_on: step.depends_on ?? [] })),
+        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: args.resourcesByStepId,
-        timeoutByStepId: Object.fromEntries(plan.steps.filter((step) => step.timeout !== undefined).map((step) => [step.id, step.timeout])),
+        timeoutByStepId: Object.fromEntries(plan.steps.flatMap((step) => (step.timeout === undefined ? [] : [[step.id, step.timeout]]))),
         budget: args.budget,
         runSession: args.runSession,
-        ownsMandate: args.ownsMandate,
         synthesisEnabled: args.synthesisEnabled,
     };
 }
@@ -226,11 +291,11 @@ function parseStoredPlan(raw, planId) {
 function validateStoredPlan(raw, planId) {
     const parsed = parseStoredPlan(raw, planId);
     if (parsed.isErr())
-        return throwLaunchRefusal(parsed.error);
+        return throwLaunchRefusal(parsed.error, planId);
     return parsed.value;
 }
 function adHocTitle(request) {
-    const compact = request.trim().replace(/\s+/g, " ");
+    const compact = collapseWhitespace(request);
     return compact.length <= 80 ? compact : `${compact.slice(0, 77)}…`;
 }
 /** How a dropped entry reads to the step agent, in the terms of its own reason. */
@@ -286,6 +351,7 @@ export function buildAdHocPlan(request, route, createdAt = new Date().toISOStrin
                 status: "pending",
                 resources: route.resources,
                 agent: route.agentId,
+                capability: route.capability,
                 maxSteps: meta?.defaultMaxSteps ?? DEFAULT_SANDBOX_MAX_STEPS,
             },
         ],
@@ -305,9 +371,9 @@ function adHocPackageResolver(deps, analysisId) {
     if (!deps.farmLockFile && !deps.imagePackagesFile && !deps.readPoolInventory)
         return undefined;
     const inventory = {
-        ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
-        ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
-        ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+        farmLockFile: deps.farmLockFile,
+        imagePackagesFile: deps.imagePackagesFile,
+        readPoolInventory: deps.readPoolInventory,
     };
     return async (names) => {
         const read = await readInventorySections(inventory, analysisId);
@@ -330,14 +396,14 @@ async function persistedAdHocPlan(deps, args) {
         pool: deps.pool,
         resourcePolicy: deps.resourcePolicy,
         logger: deps.logger,
-        ...(resolvePackages ? { resolvePackages } : {}),
-        ...(deps.usageRecorder ? { usageRecorder: deps.usageRecorder } : {}),
+        resolvePackages,
+        usageRecorder: deps.usageRecorder,
     }, {
         analysisId: args.analysisId,
         request: args.request,
         session: args.ctx.session,
         signal: args.ctx.signal,
-        ...(args.ctx.turnUsage ? { turnUsage: args.ctx.turnUsage } : {}),
+        turnUsage: args.ctx.turnUsage,
         invocationId: args.ctx.invocationId,
     });
     const candidate = buildAdHocPlan(args.request, route);
@@ -350,6 +416,10 @@ async function persistedAdHocPlan(deps, args) {
 /**
  * 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`.
+ *
+ * A launch of the run of this call always authorizes and starts, also when its row exists. A rerun of
+ * the call can come after the reservation and before the start, and the launcher starts one workflow for
+ * each run id. A rerun after the start mints a second mandate that no run uses.
  */
 async function launchReservedRun(deps, args) {
     const logger = (deps.logger ?? createNoopLogger()).named("execute-analysis-tool");
@@ -359,6 +429,12 @@ async function launchReservedRun(deps, args) {
     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);
@@ -368,9 +444,10 @@ async function launchReservedRun(deps, args) {
     const reservation = await args.reserve({ analysisId, threadId });
     if (reservation.isErr())
         return err(reservation.error);
-    if (!reservation.value.started)
+    // A different run holds the slot of the plan, or the view of the caller is stale: this call starts nothing.
+    if (reservation.value.runId !== args.runId)
         return reservation;
-    const runId = reservation.value.runId;
+    const runId = args.runId;
     const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
         auth: session.auth,
         scope: session.scope,
@@ -378,25 +455,17 @@ async function launchReservedRun(deps, args) {
         frame: { runId },
     }));
     if (authorized.isErr()) {
-        // The refusal ends the run before a workflow exists, thus the
-        // reserved row must not stay `running`.
+        // The refusal ends the run before a workflow exists, thus the reserved row must not stay `running`. No work
+        // exists yet, thus a refusal with the suspend flag does not pause, and it marks no analysis.
         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 });
+        return err(kind === "suspended" ? { type: "suspended", reason } : { type: "not_authorized", reason });
     }
-    const authorization = authorized.value;
+    const runSession = authorized.value;
     const wfInput = workflowInput(planId, plan, {
         analysisId,
         threadId,
-        runSession: authorization.runSession,
-        ownsMandate: authorization.ownsMandate,
+        runSession,
         budget: deps.resourcePolicy?.budget,
         synthesisEnabled: args.mode === "plan",
         resourcesByStepId: resources.value,
@@ -405,7 +474,7 @@ async function launchReservedRun(deps, args) {
         await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
     }
     catch (cause) {
-        await deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, "workflow-start-failed"));
+        await deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(runSession, "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 });
@@ -413,26 +482,57 @@ async function launchReservedRun(deps, args) {
     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. A concurrent launch of the same plan holds the active-plan slot,
- * and its run is the answer.
+ * Reserve the run `runId` for a plan under the lock of the plan, thus the reservations of one plan occur
+ * one after the other. A row of `runId` that exists is the reservation of a first attempt of the same
+ * call. 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();
+    const { runId } = args;
     try {
-        const inserted = await insertRun(deps.pool, {
-            runId,
-            analysisId: args.analysisId,
-            threadId: args.threadId,
-            workflowName: "executeAnalysis",
-            planId: args.planId,
-        });
-        if (inserted.isErr())
-            return err({ type: "store_failed", cause: inserted.error });
+        const reserved = await withTransaction(deps.pool, "execute-analysis.reservePlanRun", (client) => lockPlanLaunch(client, args.planId)
+            .andThen(() => queryRun(client, runId))
+            .andThen((own) => {
+            if (own !== null)
+                return okAsync({ type: "reserved" });
+            return 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,
+                }).map(() => ({ type: "reserved" }));
+            });
+        }));
+        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.
+        // `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);
@@ -467,8 +567,9 @@ async function reserveAdHocRun(deps, args) {
     }
 }
 async function launchStoredPlan(deps, input) {
-    const { session, planId } = input;
+    const { session, planId, newestRunId } = input;
     const analysisId = session.scope.analysisId;
+    const runId = input.runId ?? randomUUID();
     const raw = await loadPlan(deps.pool, planId, { analysisId });
     if (raw.isErr())
         return err({ type: "store_failed", cause: raw.error });
@@ -477,23 +578,40 @@ async function launchStoredPlan(deps, input) {
     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 });
+    if (active.value && active.value.runId !== runId) {
+        // A rerun of a call whose run ended keeps its run, also when a later launch holds the slot.
+        const own = await queryRun(deps.pool, runId);
+        if (own.isErr())
+            return err({ type: "store_failed", cause: own.error });
+        if (own.value === null)
+            return ok({ runId: active.value.runId, started: false });
+    }
     return launchReservedRun(deps, {
         session,
         planId,
         plan: plan.value,
         mode: "plan",
-        reserve: (frame) => reservePlanRun(deps, { ...frame, planId }),
+        runId,
+        reserve: (frame) => reservePlanRun(deps, { ...frame, planId, runId, newestRunId }),
     });
 }
 /**
  * Start the run of a stored plan. It reads the plan under the analysis of the session, validates it,
- * 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 a run of the plan was already active.
+ * 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.
@@ -502,14 +620,18 @@ 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) {
+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":
@@ -535,20 +657,28 @@ export function createExecuteAnalysisTool(deps) {
         // running is a different event from an ad hoc request being routed.
         describeCall: (input) => (input.mode === "plan" ? `plan ${input.planId ?? ""}` : `ad hoc: ${input.request ?? ""}`),
         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 planId = input.mode === "plan" ? input.planId : adHocPlanId(analysisId, ctx.invocationId);
+            let planId;
+            if (input.mode === "plan") {
+                if (input.planId === undefined)
+                    throw new Error("plan mode requires planId");
+                planId = input.planId;
+            }
+            else {
+                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 });
             };
             const launch = async () => {
-                if (input.mode === "plan")
-                    return launchPlanRun(deps, { session: ctx.session, planId });
+                if (input.mode === "plan") {
+                    const callKey = durableCallKey(ctx.invocationId);
+                    return launchPlanRun(deps, { session: ctx.session, planId, runId: callKey === undefined ? undefined : callRunId(callKey) });
+                }
+                if (input.request === undefined)
+                    throw new Error("adhoc mode requires request");
                 const plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
                 const runId = adHocRunId(analysisId, ctx.invocationId);
                 return launchReservedRun(deps, {
@@ -556,6 +686,7 @@ export function createExecuteAnalysisTool(deps) {
                     planId,
                     plan,
                     mode: "adhoc",
+                    runId,
                     reserve: (frame) => reserveAdHocRun(deps, { ...frame, planId, runId }),
                 });
             };
@@ -563,10 +694,10 @@ export function createExecuteAnalysisTool(deps) {
             if (launched.isErr()) {
                 const refusal = launched.error;
                 if (refusal.type === "suspended")
-                    return err({ error: `The analysis is suspended: ${refusal.reason}`, retryable: false });
+                    return err({ error: `The host refused the run: ${refusal.reason}`, retryable: false });
                 if (refusal.type === "not_authorized")
                     return err({ error: `The run was not authorized: ${refusal.reason}`, retryable: false });
-                return throwLaunchRefusal(refusal);
+                return throwLaunchRefusal(refusal, planId);
             }
             await emitRunCard(launched.value.runId);
             return ok({ runId: launched.value.runId, status: "in_progress" });

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

@@ -0,0 +1,182 @@
+/**
+ * `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 { z } from "zod";
+import { type Tool } from "../define-tool.js";
+import type { CheckResponse, KnowledgeClient, KnowledgeRejected, KnowledgeSnapshotMismatch, KnowledgeUnavailable } from "./client.js";
+import type { SnapshotPin } from "./pin.js";
+export type 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;
+declare const KnowledgeCheckInputSchema: z.ZodObject<{
+    question: z.ZodEnum<{
+        clustering: "clustering";
+        coexpression: "coexpression";
+        deconvolution: "deconvolution";
+        differential_expression: "differential_expression";
+        enrichment: "enrichment";
+        full_plan: "full_plan";
+        qc: "qc";
+        signature_scoring: "signature_scoring";
+        survival: "survival";
+        tf_activity: "tf_activity";
+    }>;
+    modality: z.ZodLiteral<"bulk_rna_seq">;
+    data_state: z.ZodEnum<{
+        counts: "counts";
+        fastq: "fastq";
+        log_normalized: "log_normalized";
+        tpm_or_fpkm: "tpm_or_fpkm";
+    }>;
+    count_source: z.ZodOptional<z.ZodEnum<{
+        kallisto: "kallisto";
+        rsem: "rsem";
+        salmon: "salmon";
+        star_featurecounts: "star_featurecounts";
+        unknown: "unknown";
+    }>>;
+    import_state: z.ZodOptional<z.ZodEnum<{
+        corrected_counts: "corrected_counts";
+        estimated_counts_with_lengths: "estimated_counts_with_lengths";
+        integer_counts: "integer_counts";
+        quantifications: "quantifications";
+        unknown: "unknown";
+    }>>;
+    organism: z.ZodEnum<{
+        human: "human";
+        mouse: "mouse";
+        other: "other";
+    }>;
+    n_groups: z.ZodNumber;
+    n_per_group_min: z.ZodNumber;
+    n_per_group_max: z.ZodNumber;
+    n_samples: z.ZodOptional<z.ZodNumber>;
+    n_events: z.ZodOptional<z.ZodNumber>;
+    paired: z.ZodBoolean;
+    blocking_factor: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        cell_line: "cell_line";
+        individual: "individual";
+        litter: "litter";
+        other: "other";
+        pair: "pair";
+        site: "site";
+    }>>>;
+    block_structure: z.ZodOptional<z.ZodEnum<{
+        crossed: "crossed";
+        nested: "nested";
+    }>>;
+    batch: z.ZodEnum<{
+        known_balanced: "known_balanced";
+        known_confounded: "known_confounded";
+        known_unbalanced: "known_unbalanced";
+        none: "none";
+        suspected: "suspected";
+    }>;
+    covariates: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        age: "age";
+        clinical: "clinical";
+        other: "other";
+        sex: "sex";
+        technical: "technical";
+    }>>>;
+    n_timepoints: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    continuous_predictor: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        age: "age";
+        dose: "dose";
+        other: "other";
+        score: "score";
+        time: "time";
+    }>>>;
+    technical_replicates: z.ZodOptional<z.ZodBoolean>;
+    sample_exclusions: z.ZodOptional<z.ZodBoolean>;
+    feature_level: z.ZodOptional<z.ZodEnum<{
+        exon: "exon";
+        gene: "gene";
+        transcript: "transcript";
+    }>>;
+    library_type: z.ZodOptional<z.ZodEnum<{
+        polyA: "polyA";
+        three_prime: "three_prime";
+        total: "total";
+        unknown: "unknown";
+    }>>;
+    strandedness: z.ZodOptional<z.ZodEnum<{
+        declared_unverified: "declared_unverified";
+        unknown: "unknown";
+        verified: "verified";
+    }>>;
+    interaction: z.ZodOptional<z.ZodBoolean>;
+    classifier: z.ZodOptional<z.ZodBoolean>;
+    extra_analyses: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        annotation: "annotation";
+        clustering: "clustering";
+        coexpression: "coexpression";
+        deconvolution: "deconvolution";
+        pathway_activity: "pathway_activity";
+        signature_scoring: "signature_scoring";
+        survival: "survival";
+        tf_activity: "tf_activity";
+        transcript_level: "transcript_level";
+        variance_partition: "variance_partition";
+    }>>>;
+    preferred_language: z.ZodOptional<z.ZodEnum<{
+        R: "R";
+        python: "python";
+    }>>;
+    enrichment_input: z.ZodOptional<z.ZodEnum<{
+        gene_list: "gene_list";
+        ranked_list: "ranked_list";
+        sample_scores: "sample_scores";
+    }>>;
+    quality_flags: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        degraded_rna: "degraded_rna";
+        high_duplication: "high_duplication";
+        low_depth_sample: "low_depth_sample";
+        outlier_sample: "outlier_sample";
+        sample_identity_doubt: "sample_identity_doubt";
+    }>>>;
+    steps: z.ZodArray<z.ZodObject<{
+        step_type: z.ZodEnum<{
+            annotation: "annotation";
+            clustering: "clustering";
+            coexpression: "coexpression";
+            cohort_assembly: "cohort_assembly";
+            deconvolution: "deconvolution";
+            differential_expression: "differential_expression";
+            enrichment: "enrichment";
+            filter_low_counts: "filter_low_counts";
+            model_design: "model_design";
+            multiple_testing: "multiple_testing";
+            normalize: "normalize";
+            pathway_activity: "pathway_activity";
+            qc_sample_structure: "qc_sample_structure";
+            report: "report";
+            shrink_lfc: "shrink_lfc";
+            signature_scoring: "signature_scoring";
+            survival: "survival";
+            tf_activity: "tf_activity";
+            transcript_level: "transcript_level";
+            variance_partition: "variance_partition";
+        }>;
+        method: z.ZodString;
+        method_id: z.ZodOptional<z.ZodString>;
+        package: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        }, z.core.$strip>>>;
+        outcome: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function createKnowledgeCheckTool(deps: KnowledgeCheckDeps): Tool<z.infer<typeof KnowledgeCheckInputSchema>, KnowledgeCheckOutput>;
+export {};