@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/tools/knowledge/skeleton.js

@@ -0,0 +1,202 @@
+/**
+ * The plan skeleton: the procedure of the service folded into the steps of a
+ * plan, with the agent, the packages, the dependencies, the caveats, the
+ * alternatives, the disputed sides, the forbidden methods, the environment,
+ * and the grounding of each step filled from the answer. It is
+ * the one representation the planner receives: the procedure itself never
+ * reaches the model, thus nothing the procedure holds may be lost here. A
+ * small model edits a skeleton where it fails to compose a plan from a
+ * procedure; a frontier model pays nothing for it. The skeleton carries only
+ * the fields the answer can fill. The question, the acceptance criteria, the
+ * resources, and the step budget come from the data profile, and the planner
+ * adds them.
+ *
+ * The fold is fixed: one cohort assembly step when the procedure holds one
+ * (the sample exclusions and the sum of technical replicates, before any
+ * other step reads the counts), one QC step, one differential expression
+ * step that holds the filter, the normalization, the design, the test, the
+ * shrinkage, and the multiple testing (the templates cover the same span),
+ * one enrichment step on its own track, and one report step. A group with
+ * no step in the procedure is absent from the skeleton.
+ *
+ * The central step of a group names the method of the skeleton step, and it
+ * gives the alternatives, the template, and the environment: an alternative
+ * of a folded step (a normalization in the differential expression group)
+ * is not a permitted replacement of the step method, and it stays out. The
+ * settings, the caveats, and the forbidden methods come from every step of
+ * the group, each setting with the step it belongs to. A parameter is a
+ * setting of the grounding, never a constraint of the step: the value is the
+ * vetted default, and the agent can state another value with its reason.
+ */
+const GROUPS = [
+    { id: "T0S1", track: "T1", step_type: "data_preparation", agent: "bulk-transcriptomics-agent", steps: ["cohort_assembly"], name: "Cohort assembly" },
+    { id: "T1S1", track: "T1", step_type: "qc", agent: "bulk-transcriptomics-agent", steps: ["qc_sample_structure"], name: "Sample structure QC" },
+    {
+        id: "T1S2",
+        track: "T1",
+        step_type: "analysis",
+        agent: "bulk-transcriptomics-agent",
+        steps: ["filter_low_counts", "normalize", "model_design", "differential_expression", "shrink_lfc", "multiple_testing"],
+        name: "Differential expression",
+    },
+    { id: "T2S1", track: "T2", step_type: "enrichment", agent: "enrichment-agent", steps: ["enrichment"], name: "Gene set enrichment" },
+    {
+        id: "T2S2",
+        track: "T2",
+        step_type: "activity",
+        agent: "enrichment-agent",
+        steps: ["tf_activity", "pathway_activity"],
+        name: "Regulator and pathway activity",
+    },
+    { id: "T1S4", track: "T1", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["variance_partition"], name: "Variance partition" },
+    { id: "T3S1", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["signature_scoring"], name: "Signature scoring" },
+    { id: "T3S2", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["deconvolution"], name: "Cell type deconvolution" },
+    { id: "T3S3", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["coexpression"], name: "Co-expression modules" },
+    { id: "T3S4", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["clustering"], name: "Sample clustering" },
+    { id: "T3S5", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["survival"], name: "Outcome association" },
+    { id: "T1S5", track: "T1", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["transcript_level"], name: "Transcript-level analysis" },
+    { id: "T1S6", track: "T1", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["annotation"], name: "Identifier annotation" },
+    { id: "T1S3", track: "T1", step_type: "report", agent: "bulk-transcriptomics-agent", steps: ["report"], name: "Report" },
+];
+/**
+ * The dependencies of each group. The QC depends on the cohort assembly when
+ * one is present, a group depends on the QC, on the differential expression
+ * when its input is a results table, and the report depends on every group
+ * that is present.
+ */
+const DEPENDS = {
+    T0S1: [],
+    T1S1: ["T0S1"],
+    T1S2: ["T1S1"],
+    T2S1: ["T1S2"],
+    T2S2: ["T1S2", "T1S1"],
+    T1S4: ["T1S1"],
+    T3S1: ["T1S1"],
+    T3S2: ["T1S1"],
+    T3S3: ["T1S1"],
+    T3S4: ["T1S1"],
+    T3S5: ["T3S1", "T1S1"],
+    T1S5: ["T1S1"],
+    T1S6: ["T1S1"],
+    T1S3: ["T1S2", "T2S1", "T2S2", "T1S4", "T3S1", "T3S2", "T3S3", "T3S4", "T3S5", "T1S5", "T1S6"],
+};
+/** A parameter value as a setting: a scalar stays, a list becomes a list of strings, anything else its text. */
+function settingValue(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (Array.isArray(value))
+        return value.map(String);
+    return String(value);
+}
+/** The settings of the steps of a group: one entry per parameter, with the step it belongs to. */
+function stepSettings(steps) {
+    return steps.flatMap((step) => (step.parameters ?? []).map((parameter) => ({
+        step: step.step,
+        name: parameter.name,
+        value: settingValue(parameter.value),
+        ...(parameter.default_source ? { source: parameter.default_source } : {}),
+    })));
+}
+/** The forbidden method ids of a step. The client schema reads the field through the loose object. */
+function forbidsOf(step) {
+    const forbids = step.forbids;
+    return Array.isArray(forbids) ? forbids.filter((method) => typeof method === "string") : [];
+}
+/** `a and b`, or `a, b and c` for a longer list. */
+function joinWithAnd(items) {
+    if (items.length <= 1)
+        return items.join("");
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+/**
+ * The caveats a step carries beside its warn flags. A parameter conflict, a
+ * substitution, and a language limit each render as a caveat, never as a
+ * setting: a setting is a value, and none of the three is a value.
+ */
+function stepCaveats(step) {
+    const caveats = [];
+    for (const conflict of step.conflicts ?? []) {
+        caveats.push(`${step.step}: ${conflict.parameter} conflicts between ${joinWithAnd(conflict.entries.map((entry) => entry.rule))}`);
+    }
+    if (step.substitution && step.method) {
+        caveats.push(`${step.method.label} stands in for ${step.substitution.label}`);
+    }
+    if (step.limit) {
+        // Only two languages exist, thus the named template is in the other one. A slot that refuses a value of the
+        // rules is not a fact of the design, thus with a refusal the caveat names the cause of each skipped template.
+        const named = step.limit.requested_language === "python" ? "R" : "Python";
+        const refused = step.limit.skipped.some((entry) => entry.refused !== undefined);
+        const causes = step.limit.skipped.map((entry) => entry.refused !== undefined ? `${entry.template}: ${entry.refused}` : `${entry.template} does not honor ${entry.missing.join(", ")}`);
+        const cause = refused ? `because ${causes.join("; ")}` : "for this design";
+        caveats.push(`the requested language has no template that realizes ${step.method?.label ?? step.step} ${cause}; the ${named} template is named`);
+    }
+    if (step.unrealized) {
+        // The knowledge covers the step and no vetted script does: the plan says so, and it invents no template.
+        const why = step.unrealized.templates.map((entry) => `${entry.template}: ${entry.why}`).join("; ");
+        caveats.push(`no vetted template realizes ${step.method?.label ?? step.step} for this design (${why || "the method lists no template for the step"}); the step runs without a template of the service`);
+    }
+    return caveats;
+}
+/** The present dependencies of a group; a group whose own dependency is absent falls back to the QC, and the two first groups to nothing. */
+function dependsOn(id, kept) {
+    const present = (DEPENDS[id] ?? []).filter((dependency) => kept.has(dependency));
+    if (present.length > 0)
+        return [...new Set(present)];
+    return id !== "T0S1" && id !== "T1S1" && kept.has("T1S1") ? ["T1S1"] : [];
+}
+export function buildPlanSkeleton(answer) {
+    const byStep = new Map(answer.procedure.map((step) => [step.step, step]));
+    const present = new Set(answer.procedure.map((step) => step.step));
+    const kept = GROUPS.filter((group) => group.steps.some((step) => present.has(step)));
+    const keptIds = new Set(kept.map((group) => group.id));
+    return kept.map((group) => {
+        const steps = group.steps.map((step) => byStep.get(step)).filter((step) => step !== undefined);
+        const central = steps.find((step) => step.step === "differential_expression") ?? steps.find((step) => step.method !== undefined) ?? steps[0];
+        const flags = steps.flatMap((step) => step.flags ?? []);
+        const hardFlag = flags.find((flag) => flag.severity === "flag");
+        const claims = [...new Set(steps.flatMap((step) => step.rules))];
+        const packages = [
+            ...new Set(steps.map((step) => step.package?.name).filter((name) => name !== undefined)),
+        ];
+        const caveats = [...flags.filter((flag) => flag.severity === "warn").map((flag) => flag.message), ...steps.flatMap(stepCaveats)];
+        const method = central?.method;
+        // A rule covers the group when a step of the group carries one. A method
+        // is not necessary: the report step carries the reporting rules and no
+        // method, and it is grounded by those rules.
+        const covered = method !== undefined || claims.length > 0;
+        const status = hardFlag ? "flagged" : covered ? "grounded" : "ungrounded";
+        const name = method && group.id !== "T1S1" && group.id !== "T1S3" ? method.label : group.name;
+        const alternatives = (central?.alternatives ?? []).map(({ method: id, label, when, rules }) => ({ method: id, label, when, rules }));
+        // One dispute per skeleton step: the central step first, else the first folded step that carries one.
+        const disputed = central?.disputed ?? steps.find((step) => step.disputed !== undefined)?.disputed;
+        const forbids = [...new Set(steps.flatMap(forbidsOf))];
+        return {
+            id: group.id,
+            name,
+            track: group.track,
+            step_type: group.step_type,
+            agent: group.agent,
+            packages,
+            depends_on: dependsOn(group.id, keptIds),
+            caveats: hardFlag ? [hardFlag.message, ...caveats] : caveats,
+            alternatives,
+            ...(disputed ? { disputed: { rule: disputed.rule, sides: disputed.sides } } : {}),
+            forbids,
+            ...(central?.environment ? { environment: central.environment } : {}),
+            grounding: {
+                status,
+                snapshot: answer.snapshot.digest,
+                claims,
+                ...(central?.template ? { template: central.template } : {}),
+                settings: stepSettings(steps),
+                reason: hardFlag
+                    ? `flagged by ${hardFlag.rule}`
+                    : method
+                        ? `${method.label} per ${claims[0] ?? "the procedure"}`
+                        : covered
+                            ? `${group.name} per ${claims[0]}`
+                            : "no rule covers this step",
+            },
+        };
+    });
+}

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

@@ -0,0 +1,137 @@
+/**
+ * `knowledge_template` — the model emits slot values, and the tool writes the
+ * rendered script and the decision record into the step workspace through
+ * the same `WorkspaceMutator` as `write_file`. The script is never output tokens.
+ *
+ * The installed versions ride from the tool, not from the model: the tool
+ * reads the `inflexa.lock` of the farm and the `image-packages.json` of the
+ * store when the host names them (`installedPackages`), and the service
+ * answers with the environment match, which the decision record keeps.
+ *
+ * The plan settings ride from the host, not from the model: the step input
+ * carries a `TemplateBinding` when the plan step grounds on a template, and
+ * the tool merges the bound slots under the model values. A model value that
+ * differs from a bound value is refused before the service call unless an
+ * `overrides` entry names the slot with a reason, and the decision record
+ * keeps the bound slots and the overrides beside the script path.
+ *
+ * The facts of the machine never ride at all: a local slot of the template
+ * (a path, a column name, a level label, a design formula) is split off the
+ * request, the service renders it as its marker, and the tool binds the
+ * value on the machine before it writes the file. The request carries the
+ * step, its claims, and the release digest the plan pinned, thus the record
+ * binds the cited decision to the bytes, and a service on another release
+ * refuses the render instead of moving the plan in silence. The call runs as
+ * one durable step, thus a replay returns the cached result and renders
+ * nothing again.
+ */
+import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
+import { type WithToolCallRecord } from "../define-tool.js";
+import type { WorkspaceMutator, WriteFileResult, WriteRecord } from "../workspace/mutator.js";
+import type { KnowledgeClient, KnowledgeRejected, KnowledgeSnapshotMismatch, KnowledgeUnavailable, TemplateParameter } from "./client.js";
+/** A slot value the plan binds: a scalar, or a list of strings. JSON-serialisable, as the durable step input needs. */
+export type TemplateBindingValue = string | number | boolean | readonly string[];
+/**
+ * The plan settings bound to the template of one step, composed by the host
+ * at dispatch and carried on the durable step input. `slots` holds the bound
+ * value per slot name, and `sources` the source of each value (a doi, a
+ * document, or the plan) under the same name. The rest binds the render to
+ * the plan step: its id, its claims, the release the plan pinned, and the
+ * local slots of the contract that the tool binds on the machine.
+ */
+export interface TemplateBinding {
+    /** The template reference of the plan step, with its version, for example `tpl-deseq2-two-group@1.0.0`. */
+    readonly template: string;
+    readonly slots: Readonly<Record<string, TemplateBindingValue>>;
+    readonly sources: Readonly<Record<string, string>>;
+    /** The id of the plan step. */
+    readonly step?: string;
+    /** The claims of the plan step, as `knowledge_recommend` returned them. */
+    readonly claims?: readonly string[];
+    /** The release digest the plan pinned. Absent when the step is ungrounded. */
+    readonly snapshot?: string;
+    /** The local slots of the served contract. Absent on a binding made before the contract carried the flag. */
+    readonly local?: readonly TemplateParameter[];
+    /** The names of every adaptable slot of the served contract, thus the tool refuses an unknown name before anything leaves the machine. */
+    readonly adaptable?: readonly string[];
+}
+export interface KnowledgeTemplateDeps {
+    readonly client: KnowledgeClient;
+    readonly mutator: WorkspaceMutator;
+    /** Host path of the farm `inflexa.lock`, or its resolver for each analysis. Absent with no image record, the environment match reads as unknown. */
+    readonly farmLockFile?: EnvironmentStorePaths["farmLockFile"];
+    /** Host path of the `image-packages.json` of the store: the packages the sandbox image ships, among them the R packages of the R runtime. */
+    readonly imagePackagesFile?: string;
+    /** The plan settings bound to the template of the step. Absent, the model values ride alone. */
+    readonly binding?: TemplateBinding;
+}
+/** One bound slot as the decision record keeps it. */
+export interface BoundSlotRecord {
+    readonly slot: string;
+    readonly value: TemplateBindingValue;
+    readonly source: string;
+}
+/** One change of a bound value that an `overrides` entry declared, as the decision record keeps it. */
+export interface SettingsOverrideRecord {
+    readonly slot: string;
+    readonly plan_value: TemplateBindingValue;
+    readonly new_value: unknown;
+    readonly reason: string;
+}
+export type KnowledgeTemplateOutput = {
+    readonly status: "ok";
+    readonly script_path: string;
+    readonly decision_record_path: string;
+    readonly template: {
+        readonly id: string;
+        readonly version: string;
+        readonly label: string;
+        readonly method: {
+            readonly id: string;
+            readonly label: string;
+        };
+        readonly substitute_for?: {
+            readonly id: string;
+            readonly label: string;
+        };
+    };
+    readonly snapshot: {
+        readonly date: string;
+        readonly digest: string;
+    };
+    readonly slots: readonly {
+        readonly name: string;
+        readonly value?: unknown;
+        readonly source: string;
+        readonly adaptable: boolean;
+        readonly lines: readonly number[];
+    }[];
+    /** The local slots the tool bound on this machine. */
+    readonly local_slots: readonly string[];
+    /** The digest of the script as written. */
+    readonly written_sha256: string;
+    readonly environment_match: string;
+    readonly syntax: string;
+    readonly expected_outputs: readonly {
+        readonly name: string;
+        readonly path: string;
+        readonly description?: string;
+    }[];
+    readonly run_with: string;
+} | {
+    readonly status: "write_refused";
+    readonly path: string;
+    readonly reason: Exclude<WriteFileResult["status"], "ok">;
+} | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch;
+/** The result of a `knowledge_template` call: each landed write rides as the call record, for the fold. */
+type KnowledgeTemplateResult = KnowledgeTemplateOutput | WithToolCallRecord<KnowledgeTemplateOutput, readonly WriteRecord[]>;
+export declare function createKnowledgeTemplateTool(deps: KnowledgeTemplateDeps): import("../define-tool.js").Tool<{
+    template: string;
+    slots: Record<string, unknown>;
+    overrides?: {
+        slot: string;
+        reason: string;
+    }[] | undefined;
+    script_name?: string | undefined;
+}, KnowledgeTemplateResult>;
+export {};

package/dist/tools/knowledge/template.js

@@ -0,0 +1,267 @@
+/**
+ * `knowledge_template` — the model emits slot values, and the tool writes the
+ * rendered script and the decision record into the step workspace through
+ * the same `WorkspaceMutator` as `write_file`. The script is never output tokens.
+ *
+ * The installed versions ride from the tool, not from the model: the tool
+ * reads the `inflexa.lock` of the farm and the `image-packages.json` of the
+ * store when the host names them (`installedPackages`), and the service
+ * answers with the environment match, which the decision record keeps.
+ *
+ * The plan settings ride from the host, not from the model: the step input
+ * carries a `TemplateBinding` when the plan step grounds on a template, and
+ * the tool merges the bound slots under the model values. A model value that
+ * differs from a bound value is refused before the service call unless an
+ * `overrides` entry names the slot with a reason, and the decision record
+ * keeps the bound slots and the overrides beside the script path.
+ *
+ * The facts of the machine never ride at all: a local slot of the template
+ * (a path, a column name, a level label, a design formula) is split off the
+ * request, the service renders it as its marker, and the tool binds the
+ * value on the machine before it writes the file. The request carries the
+ * step, its claims, and the release digest the plan pinned, thus the record
+ * binds the cited decision to the bytes, and a service on another release
+ * refuses the render instead of moving the plan in silence. The call runs as
+ * one durable step, thus a replay returns the cached result and renders
+ * nothing again.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool, withToolCallRecord } from "../define-tool.js";
+import { decisionRecordPath, scriptSha256 } from "../workspace/decision-record.js";
+import { installedPackages } from "./environment.js";
+import { bindLocalSlots, localParameters, validateLocalSlot } from "./local-slots.js";
+const TEMPLATE_REF = /^tpl-[a-z0-9-]+(@\d+\.\d+\.\d+)?$/;
+/** A model value equals a bound value when the scalars are identical, or when two lists hold the same strings in order. */
+function sameValue(bound, value) {
+    if (Array.isArray(bound)) {
+        return Array.isArray(value) && value.length === bound.length && bound.every((item, index) => item === value[index]);
+    }
+    return bound === value;
+}
+/** The source of a bound slot as the issue names it. A binding without a source for the slot reads as the plan. */
+function sourceOf(binding, slot) {
+    return binding.sources[slot] ?? "plan";
+}
+/**
+ * The refusal of a render request against the binding, or `undefined` when
+ * the request obeys it. A different template reference is one issue on the
+ * field `template`. Each bound slot whose model value differs without an
+ * override is one issue that names the slot, the bound value, and its source.
+ */
+function refusedByBinding(binding, template, slots, overridden) {
+    if (template !== binding.template) {
+        const message = `the plan binds the template ${binding.template}; this step renders that reference only`;
+        return { match: "rejected", message, issues: [{ field: "template", message, permitted: [binding.template] }] };
+    }
+    const issues = [];
+    for (const [slot, bound] of Object.entries(binding.slots)) {
+        const value = slots[slot];
+        if (value === undefined || sameValue(bound, value) || overridden.has(slot))
+            continue;
+        const shown = JSON.stringify(bound);
+        issues.push({
+            slot,
+            reason: "bound by the plan",
+            message: `the plan binds ${slot} = ${shown} (${sourceOf(binding, slot)}); send that value, or name the slot in overrides with the reason for the change`,
+            permitted: [shown],
+        });
+    }
+    if (issues.length === 0)
+        return undefined;
+    return { match: "rejected", message: "one or more slot values differ from the plan settings without an override", issues };
+}
+/** A contract answer that is a refusal. The contract itself is a loose object, thus `in` alone cannot tell the two apart. */
+function isContractRefusal(answer) {
+    return "match" in answer && (answer.match === "unavailable" || answer.match === "rejected");
+}
+/** The slots of `slots` whose names are in `names`, and the rest, as two records. */
+function splitSlots(slots, names) {
+    const local = {};
+    const remote = {};
+    for (const [name, value] of Object.entries(slots))
+        (names.has(name) ? local : remote)[name] = value;
+    return { local, remote };
+}
+export function createKnowledgeTemplateTool(deps) {
+    return defineTool({
+        id: "knowledge_template",
+        description: "Render a tested analysis script from a knowledge template and write it into your working directory. " +
+            "Use it for a step whose briefing names a template in its Grounding (for example `tpl-deseq2-two-group@1.0.0`). " +
+            "The briefing lists the slots of the template and the values the plan binds. " +
+            "Send the template id and the slot values only: the file paths of your inputs (absolute `/<analysisId>/...` paths), the column names, the levels of the contrast, and the design. " +
+            "A slot the briefing marks local (a path, a column name, a level, a formula) is bound on this machine and never sent to the service; send it as any other slot. " +
+            "A bound value rides into the script as it is; send it unchanged, or omit it. To change a bound value, send the new value and add an `overrides` entry with the slot and the reason. A changed value without an override is refused before the service call. " +
+            "Prefer the template over a script of your own: it is tested, and it carries the settings of the plan. When the template does not fit the step (a design it does not cover, or an input it cannot read), write the script yourself with `write_file`, and state the reason in your summary. " +
+            "The tool writes `scripts/<template>.R` or `scripts/<template>.py` and `output/decision_record_<script>.json`, one record per rendered script (the step, its claims, the template, the snapshot, each slot with its source, the bound slots, the overrides, the environment match, the citations, and the digest of the script as written), then you run the script with `execute_command` using the command in `run_with`. " +
+            "A slot value the template refuses comes back as `match: rejected` with the slot and the permitted values; correct it and call again. " +
+            "A change the slots do not cover: use `edit_file` on a line marked `# [adaptable: ...]` in the rendered script, and keep the edit small; the record lists each such edit. " +
+            "`match: unavailable` means the service did not answer, and `match: snapshot_mismatch` means the service moved to another release than the plan pinned; in both cases write the script yourself as you would without this tool, and state it in your summary.",
+        inputSchema: z.object({
+            template: z
+                .string()
+                .regex(TEMPLATE_REF, "a template id, optionally with @version")
+                .describe("The template id from the Grounding of the step, with its version, for example `tpl-deseq2-two-group@1.0.0`."),
+            slots: z
+                .record(z.string(), z.unknown())
+                .describe("The slot values, by slot name. Only the adaptable slots of the template; a pinned slot is refused. Strings, numbers, booleans, and lists of strings."),
+            overrides: z
+                .array(z.object({
+                slot: z.string().min(1).describe("The name of the bound slot whose value you change."),
+                reason: z.string().min(1).describe("Why the plan value does not hold for this step, in one sentence."),
+            }))
+                .optional()
+                .describe("One entry per bound slot whose value you change from the plan value. Absent when you send every bound value as it is."),
+            script_name: z
+                .string()
+                .regex(/^[A-Za-z0-9_.-]+$/)
+                .optional()
+                .describe("The file name under `scripts/`. Defaults to `<template id>.R` or `<template id>.py` by the language of the template."),
+        }),
+        describeCall: ({ template }) => template,
+        describeResult: (_input, result) => "status" in result ? (result.status === "ok" ? `${result.script_path} (${result.environment_match})` : result.status) : result.match,
+        execute: async ({ template, slots, overrides, script_name }, ctx) => {
+            const binding = deps.binding;
+            const reasons = new Map((overrides ?? []).map((entry) => [entry.slot, entry.reason]));
+            if (binding) {
+                const refused = refusedByBinding(binding, template, slots, new Set(reasons.keys()));
+                if (refused)
+                    return ok(refused);
+            }
+            // The local slots and the adaptable names come from the binding the host composed at dispatch, else from
+            // the contract itself. Without them no free-text value can be told from a fact of the machine, and an
+            // unknown name could carry one, thus no render happens without them.
+            let locals;
+            let adaptable;
+            if (binding?.local && binding.adaptable) {
+                locals = binding.local;
+                adaptable = binding.adaptable;
+            }
+            else {
+                const contract = await deps.client.contract(template);
+                if (isContractRefusal(contract))
+                    return ok(contract);
+                locals = localParameters(contract.parameters);
+                adaptable = contract.parameters.filter((parameter) => parameter.adaptable).map((parameter) => parameter.name);
+            }
+            const unknown = Object.keys(slots).filter((name) => !adaptable.includes(name));
+            if (unknown.length > 0) {
+                return ok({
+                    match: "rejected",
+                    message: "one or more slot names are not adaptable slots of this template",
+                    issues: unknown.map((slot) => ({ slot, reason: "the template has no such adaptable slot", permitted: [...adaptable] })),
+                });
+            }
+            const localNames = new Set(locals.map((parameter) => parameter.name));
+            const split = splitSlots(slots, localNames);
+            const boundSplit = splitSlots(binding?.slots ?? {}, localNames);
+            const merged = { ...boundSplit.remote, ...split.remote };
+            // A bound local slot is bound on the machine like a model value, under the model value.
+            const localValues = { ...boundSplit.local, ...split.local };
+            const localByName = new Map(locals.map((parameter) => [parameter.name, parameter]));
+            // A local value the contract refuses is refused before the service call, thus a bad path costs no render.
+            const localIssues = Object.entries(localValues).flatMap(([name, value]) => {
+                const issue = validateLocalSlot(localByName.get(name), value);
+                return issue ? [issue] : [];
+            });
+            if (localIssues.length > 0) {
+                return ok({ match: "rejected", message: "one or more local slot values are not valid for this template", issues: localIssues });
+            }
+            const farmLockFile = typeof deps.farmLockFile === "function" ? deps.farmLockFile(ctx.session.scope.analysisId) : deps.farmLockFile;
+            const installed = installedPackages({
+                ...(farmLockFile ? { farmLockFile } : {}),
+                ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
+            });
+            const answer = await deps.client.render(template, merged, installed.packages, {
+                ...(binding?.step ? { step: binding.step } : {}),
+                ...(binding?.claims ? { claims: binding.claims } : {}),
+                ...(binding?.snapshot ? { expectedSnapshot: binding.snapshot } : {}),
+            });
+            // A rendered answer carries `ok: true`; the refusals carry `match` and no `ok`.
+            if (!("ok" in answer))
+                return ok(answer);
+            const bound = bindLocalSlots({ language: answer.template.language, parameters: locals }, answer.script, localValues, answer.slots);
+            if (!bound.ok) {
+                return ok({ match: "rejected", message: "one or more local slot values are not valid for this template", issues: bound.issues });
+            }
+            const scriptFile = script_name ?? `${answer.template.id}.${answer.template.language === "R" ? "R" : "py"}`;
+            const scriptPath = `scripts/${scriptFile}`;
+            // Each landed write rides the call record, also when a later write is refused.
+            const records = [];
+            const write = async (path, content) => {
+                const outcome = await deps.mutator.writeFile({
+                    path,
+                    content,
+                    toolName: "knowledge_template",
+                    invocationId: ctx.invocationId,
+                    session: ctx.session,
+                });
+                if (outcome.status === "ok")
+                    records.push(outcome.record);
+                return outcome;
+            };
+            const scriptWrite = await write(scriptPath, bound.script);
+            if (scriptWrite.status !== "ok")
+                return ok({ status: "write_refused", path: scriptWrite.path, reason: scriptWrite.status });
+            const boundSlots = Object.entries(binding?.slots ?? {}).map(([slot, value]) => ({
+                slot,
+                value: value,
+                source: binding ? sourceOf(binding, slot) : "plan",
+            }));
+            const settingsOverrides = boundSlots.flatMap(({ slot, value }) => {
+                const reason = reasons.get(slot);
+                const sent = slots[slot];
+                if (reason === undefined || sent === undefined || sameValue(value, sent))
+                    return [];
+                return [{ slot, plan_value: value, new_value: sent, reason }];
+            });
+            // The slot report of the record: the service entries, with each local marker entry replaced by the slot as
+            // bound here. An optional local slot with no value has no entry, as in a full render.
+            const boundByName = new Map(bound.slots.map((slot) => [slot.name, slot]));
+            const reportedSlots = answer.slots.flatMap((slot) => {
+                if (slot.source !== "local")
+                    return [slot];
+                const local = boundByName.get(slot.name);
+                return local ? [local] : [];
+            });
+            const record = {
+                ...answer.decision_record,
+                slots: reportedSlots,
+                script_path: scriptWrite.path,
+                written_sha256: scriptSha256(bound.script),
+                bound_slots: boundSlots,
+                settings_overrides: settingsOverrides,
+            };
+            const recordWrite = await write(decisionRecordPath(scriptFile), `${JSON.stringify(record, null, 2)}\n`);
+            if (recordWrite.status !== "ok") {
+                return ok(withToolCallRecord({ status: "write_refused", path: recordWrite.path, reason: recordWrite.status }, records));
+            }
+            return ok(withToolCallRecord({
+                status: "ok",
+                script_path: scriptWrite.path,
+                decision_record_path: recordWrite.path,
+                template: {
+                    id: answer.template.id,
+                    version: answer.template.version,
+                    label: answer.template.label,
+                    method: { id: answer.template.method.id, label: answer.template.method.label },
+                    ...(answer.template.substitute_for
+                        ? { substitute_for: { id: answer.template.substitute_for.id, label: answer.template.substitute_for.label } }
+                        : {}),
+                },
+                snapshot: answer.snapshot,
+                slots: reportedSlots,
+                local_slots: bound.slots.map((slot) => slot.name),
+                written_sha256: record.written_sha256,
+                environment_match: answer.environment.match,
+                syntax: answer.syntax.status,
+                expected_outputs: answer.outputs,
+                run_with: `${answer.template.language === "R" ? "Rscript" : "python3"} ${scriptPath}`,
+            }, records));
+        },
+        foldCallRecord: (records) => {
+            for (const record of records)
+                deps.mutator.recordWrite(record);
+        },
+    });
+}

package/dist/tools/research/generate-plan.d.ts

@@ -30,6 +30,7 @@ import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import { type BioToolKeys } from "../bio/keys.js";
+import { type KnowledgeClient, type KnowledgeRecommendAnswer } from "../knowledge/index.js";
 import { type ResourcePolicy } from "../../config/resource-limits.js";
 import type { Logger } from "../../lib/logger.js";
 export interface GeneratePlanDeps extends EnvironmentStorePaths {
@@ -58,6 +59,28 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
     readonly toolOutputStore?: ToolOutputStore;
     /** API keys for the search tools the planner uses to ground a plan. */
     readonly bioKeys: BioToolKeys;
+    /**
+     * The knowledge service client. Bound, the planner gains `knowledge_recommend`
+     * and `knowledge_check`. Absent, no knowledge tool attaches and no
+     * description of one enters the context, which is the default state of
+     * the open-source host.
+     */
+    readonly knowledge?: KnowledgeClient;
 }
+/**
+ * The search tools of the planner — built one time, not per invocation.
+ *
+ * The set answers the two questions that a seed cannot. "What did a study of
+ * this kind do before?" reaches the public dataset records and the literature.
+ * "What does this package actually give me?" reaches the developer docs. The
+ * planner reads its reference and package inventories from the seed, thus the
+ * docs pair is what turns a package name into a real function.
+ *
+ * A tool here never writes and never computes. Thus the worst outcome of a
+ * needless call is latency, and the prompt is what bounds that.
+ */
+export declare function buildPlannerSearchTools(deps: GeneratePlanDeps, hooks?: {
+    readonly onRecommend?: (answer: KnowledgeRecommendAnswer) => void;
+}): Tool[];
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;