@inflexa-ai/harness 0.45.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, ResultAsync } 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
@@ -226,7 +289,7 @@ 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) {
@@ -286,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,
             },
         ],
@@ -359,6 +423,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);
@@ -413,26 +483,52 @@ 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 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 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(() => 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.
+        // `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,7 +563,7 @@ 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 raw = await loadPlan(deps.pool, planId, { analysisId });
     if (raw.isErr())
@@ -477,6 +573,14 @@ 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 });
@@ -487,13 +591,15 @@ async function launchStoredPlan(deps, input) {
         planId,
         plan: plan.value,
         mode: "plan",
-        reserve: (frame) => reservePlanRun(deps, { ...frame, planId }),
+        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,
- * 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 +608,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":
@@ -566,7 +676,7 @@ export function createExecuteAnalysisTool(deps) {
                     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);
+                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,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>;

package/dist/tools/knowledge/check.js

@@ -0,0 +1,92 @@
+/**
+ * `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 { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { SituationFieldsSchema, toSituation } from "./situation.js";
+/** The checks one plan generation may run. Two is a draft and one revision; the third is slack. */
+export const CHECK_CALL_LIMIT = 3;
+const DraftedStepSchema = z.object({
+    step_type: z
+        .enum([
+        "cohort_assembly",
+        "qc_sample_structure",
+        "filter_low_counts",
+        "normalize",
+        "model_design",
+        "differential_expression",
+        "shrink_lfc",
+        "multiple_testing",
+        "enrichment",
+        "variance_partition",
+        "tf_activity",
+        "pathway_activity",
+        "signature_scoring",
+        "deconvolution",
+        "coexpression",
+        "clustering",
+        "survival",
+        "transcript_level",
+        "annotation",
+        "report",
+    ])
+        .describe("The kind of work the drafted step does."),
+    method: z.string().min(1).describe("The method as the step names it, for example `DESeq2 Wald test` or `edgeR quasi-likelihood`."),
+    method_id: z
+        .string()
+        .regex(/^M-\d{4}$/)
+        .optional()
+        .describe("The `method.id` of the step in the `knowledge_recommend` answer (for example `M-0001`), copied when the step uses that method. With it the check matches the method exactly and ignores the wording."),
+    package: z.string().optional().describe("The main package of the step, for example `DESeq2`."),
+    parameters: z
+        .array(z.object({ name: z.string().min(1), value: z.union([z.string(), z.number(), z.boolean()]) }))
+        .optional()
+        .describe("The key parameters of the step, for example `alpha`, `min_count`, `lfc_shrink`, `rank_metric`."),
+    outcome: z
+        .string()
+        .optional()
+        .describe("The outcome the step states when a flag of `knowledge_recommend` removes inference, copied from the flag, for example `descriptive_only`."),
+});
+/** `ok`, or the counts of the findings, plus the steps the check did not assess when there are any. */
+function describeFindings(result) {
+    const findings = result.ok ? "ok" : `${result.violations.length} violation(s), ${result.warnings.length} warning(s)`;
+    const notAssessed = result.not_assessed?.length ?? 0;
+    return notAssessed > 0 ? `${findings}, ${notAssessed} not assessed` : findings;
+}
+export function createKnowledgeCheckTool(deps) {
+    let calls = 0;
+    return defineTool({
+        id: "knowledge_check",
+        description: "Check the method steps you drafted for a bulk RNA-seq analysis against the rules of the Inflexa knowledge service, once, after the draft and before `submit_plan`. " +
+            "Send the same situation you sent to `knowledge_recommend` and the drafted steps: the step type, the method as the step names it, its package, and its key parameters. " +
+            "The answer lists `violations` (a forbidden method, or an inferential test on a design that a flag limits) and `warnings` (a method outside the set the rules name, a parameter that differs from a sourced default, or a required parameter that the step does not state), each with the rule id and the permitted alternatives. " +
+            "Revise a violated step once, then submit. A warning is advice: keep the step when the data gives a reason, and state the reason in the step. `ok: true` means no finding on the assessed steps. " +
+            "`not_assessed` lists the steps that no rule covers; the check neither passed nor failed them, so submit them as drafted. " +
+            "`match: unavailable` means the service did not answer, and `match: snapshot_mismatch` means the service moved to another release than the one your recommend answer came from; in both cases submit the draft as it is. " +
+            `The host accepts ${CHECK_CALL_LIMIT} checks per plan; after that the tool refuses and you submit with the findings you have.`,
+        inputSchema: SituationFieldsSchema.extend({
+            steps: z.array(DraftedStepSchema).min(1).describe("The drafted method steps, one entry per step type."),
+        }),
+        describeCall: ({ steps }) => `${steps.length} drafted step(s)`,
+        describeResult: (_input, result) => ("ok" in result ? describeFindings(result) : result.match),
+        execute: async (input) => {
+            calls += 1;
+            if (calls > CHECK_CALL_LIMIT) {
+                return ok({
+                    match: "rejected",
+                    message: `The host accepts ${CHECK_CALL_LIMIT} checks per plan, and this is call ${calls}. Submit the plan with the findings of the last check.`,
+                    issues: [],
+                });
+            }
+            const { steps, ...fields } = input;
+            const answer = await deps.client.check(toSituation(fields), steps, deps.pin?.get());
+            return ok(answer);
+        },
+    });
+}