@inflexa-ai/harness 0.44.0 → 0.45.1

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;

package/dist/tools/research/generate-plan.js

@@ -23,7 +23,7 @@
  * `Session`. The planner prompt injects the agent catalog and exposes the
  * terminal-tool surface above.
  */
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { formatAgentCatalog } from "../../agents/sandbox-catalog.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
@@ -36,21 +36,24 @@ import { createReadToolOutputTool } from "../read-tool-output.js";
 import { createListAvailablePackagesTool } from "../sandbox/list-available-packages.js";
 import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
 import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
+import { degenerateTerminalText } from "../terminal-text.js";
 import { searchGeoDatasetsTool } from "../bio/search-geo-datasets.js";
 import { createNcbiTools } from "../bio/keys.js";
+import { createKnowledgeTools } from "../knowledge/index.js";
 import { queryDocsTool, resolveLibraryIdTool } from "./context7-docs.js";
 import { searchArxivTool } from "./search-arxiv.js";
 import { createSearchGithubReposTool } from "./search-github-repos.js";
 import { createSearchSemanticScholarTool } from "./search-semantic-scholar.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../../app/data-profile-orientation.js";
 import { DEFAULT_SANDBOX_MAX_STEPS } from "../../config/resource-limits.js";
+import { guardRepeatedCalls } from "../../loop/call-guard.js";
 import { plannerPrompt } from "../../prompts/planner.js";
 import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.js";
 import { validatePlan } from "../../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { unwrapOrThrow } from "../../lib/result.js";
-import { hintForZodIssue } from "../../lib/zod-issues.js";
+import { decodeObjectString, hintForZodIssue } from "../../lib/zod-issues.js";
 import { insertPlan, loadDataProfileStatus, loadPlan } from "../../state/index.js";
 // ── Tool-level config ──────────────────────────────────────────────
 /** Sub-agent identity for the planner — provenance only. */
@@ -69,6 +72,14 @@ const PLANNER_AGENT_ID = "planner";
 const PLANNER_MAX_ITERATIONS = 300;
 /** Wall-clock guard for a single plan-generation invocation. */
 const PLAN_TIMEOUT_MS = 1_800_000;
+/**
+ * The refusals of the call guard that end the search phase of one plan. A
+ * planner that the guard refused this many times is not searching, it is
+ * looping, and the wrap-up plus the salvage turn give it the plan it has. Six
+ * is above any count a frontier planner reached in the Phase 0 campaign
+ * (zero) and far below the hundred-plus refused calls of a looping run.
+ */
+const PLANNER_REFUSAL_LIMIT = 6;
 // ── Diagnostic bounds ───────────────────────────────────────────────
 //
 // This tool runs on `passthroughStep`: it writes no ledger row and owns no
@@ -297,14 +308,150 @@ function zodIssuesToValidationIssues(error, input, rootPath = "plan") {
         hint: hintForZodIssue(i, input),
     }));
 }
+function rememberAnswer(memory, answer) {
+    memory.steps.clear();
+    memory.claims.clear();
+    memory.digest = answer.snapshot.digest;
+    for (const step of answer.plan_skeleton) {
+        memory.steps.set(step.id, step);
+        for (const claim of step.grounding.claims)
+            memory.claims.add(claim);
+        for (const alternative of step.alternatives)
+            for (const rule of alternative.rules)
+                memory.claims.add(rule);
+        if (step.disputed !== undefined)
+            memory.claims.add(step.disputed.rule);
+    }
+    for (const claim of answer.claims)
+        memory.claims.add(claim.id);
+    for (const flag of answer.flags)
+        memory.claims.add(flag.rule);
+}
+/** The rule of a claim id: `R-0001` of `R-0001@e7d0`. */
+function ruleOf(claim) {
+    return claim.split("@")[0] ?? claim;
+}
+/** One claim id per rule of the answer. A rule with two ids in one answer cannot be repaired, and it is absent. */
+function claimsByRule(claims) {
+    const byRule = new Map();
+    const ambiguous = new Set();
+    for (const claim of claims) {
+        const rule = ruleOf(claim);
+        if (byRule.has(rule))
+            ambiguous.add(rule);
+        else
+            byRule.set(rule, claim);
+    }
+    for (const rule of ambiguous)
+        byRule.delete(rule);
+    return byRule;
+}
+/**
+ * Restore the grounding fields the host owns on each candidate step, from the
+ * last answer. A model copies the skeleton into the plan, and it drops the
+ * template field at times, or it miscopies the 64-character digest or the
+ * hash of a claim id, while it keeps the claims and the settings.
+ *
+ * On a step that copies a skeleton step, by step id, the host stamps the
+ * snapshot digest of the answer and restores a dropped template: the digest
+ * is what pins the step to the snapshot, and the template is what the host
+ * binds the contract to. A step whose snapshot is `none` states that it does
+ * not use the answer, and it stays as it is. A step whose status is
+ * `ungrounded` states a departure from the answer: the digest is stamped,
+ * and no template is restored, because the template realizes the method the
+ * step left.
+ *
+ * On every step, a claim id the answer did not return is repaired when the
+ * answer holds one claim of the same rule: one snapshot holds one version of
+ * a rule, thus the rule names the claim. A claim of a rule the answer does
+ * not hold is an issue that rejects the plan, so the model cites a claim of
+ * the answer or removes it.
+ *
+ * A step the skeleton does not hold, for example a robustness step the model
+ * adds under its own id, gets the digest stamped too when one of its claims
+ * is a claim of the answer: the claim vouches that the step consulted the
+ * answer, and the digest it typed is as prone to a miscopy as any other. A
+ * step with no claim of the answer stays as the model wrote it, because
+ * nothing of the answer vouches for it. Returns the stamped steps, the
+ * restored steps, the repaired claims, and the issues beside the new
+ * candidate. A candidate that is not a plan-shaped object, or a plan with no
+ * answer, comes back as it is.
+ */
+function restoreSkeletonGrounding(candidate, memory) {
+    const decoded = decodeObjectString(candidate);
+    if (memory.steps.size === 0 || typeof decoded !== "object" || decoded === null || !Array.isArray(decoded.steps)) {
+        return { candidate: decoded, stamped: [], restored: [], repaired: [], unknown: [] };
+    }
+    const byRule = claimsByRule(memory.claims);
+    const stamped = [];
+    const restored = [];
+    const repaired = [];
+    const unknown = [];
+    const steps = decoded.steps.map((step, index) => {
+        if (typeof step !== "object" || step === null)
+            return step;
+        const { id, grounding } = step;
+        if (typeof grounding !== "object" || grounding === null)
+            return step;
+        const current = grounding;
+        const label = typeof id === "string" ? id : String(index);
+        let next = current;
+        const source = typeof id === "string" ? memory.steps.get(id) : undefined;
+        if (source !== undefined && current.snapshot !== "none") {
+            if (next.snapshot !== source.grounding.snapshot) {
+                stamped.push(label);
+                next = { ...next, snapshot: source.grounding.snapshot };
+            }
+            if (next.template === undefined && source.grounding.template !== undefined && current.status !== "ungrounded") {
+                restored.push(label);
+                next = { ...next, template: source.grounding.template };
+            }
+        }
+        if (Array.isArray(current.claims)) {
+            let changed = false;
+            const claims = current.claims.map((claim, position) => {
+                if (typeof claim !== "string" || memory.claims.has(claim))
+                    return claim;
+                const match = byRule.get(ruleOf(claim));
+                if (match !== undefined) {
+                    repaired.push({ step: label, from: claim, to: match });
+                    changed = true;
+                    return match;
+                }
+                unknown.push({
+                    path: `plan.steps.${index}.grounding.claims.${position}`,
+                    code: "semantic",
+                    message: `Claim ${claim} is not a claim of the knowledge_recommend answer of this run. Cite a claim id the answer returned, or remove it.`,
+                });
+                return claim;
+            });
+            if (changed)
+                next = { ...next, claims };
+        }
+        // The repaired claims are the ones compared, thus a step whose only claim was miscopied still gets the digest.
+        const vouched = Array.isArray(next.claims) && next.claims.some((claim) => typeof claim === "string" && memory.claims.has(claim));
+        if (source === undefined && vouched && memory.digest !== undefined && current.snapshot !== "none" && next.snapshot !== memory.digest) {
+            stamped.push(label);
+            next = { ...next, snapshot: memory.digest };
+        }
+        return next === current ? step : { ...step, grounding: next };
+    });
+    return { candidate: { ...decoded, steps }, stamped, restored, repaired, unknown };
+}
 /**
  * Full validation: Zod schema + semantic checks. The plan is valid only if
  * BOTH pass.
  */
 function fullyValidate(candidate, resourcePolicy) {
-    const parsed = PlannerPlanSchema.safeParse(candidate);
+    // The permissive arg schema of the planner tools accepts a string, thus the
+    // loop-boundary repair never sees a plan that a model sent as a JSON-encoded
+    // string. A small model does this on a large nested schema. Decode it here,
+    // the same as run-synthesis does, so the schema issues describe the plan
+    // inside the string and not the string.
+    const decoded = decodeObjectString(candidate);
+    const parsed = PlannerPlanSchema.safeParse(decoded);
     if (!parsed.success) {
-        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, candidate) };
+        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, decoded) };
     }
     // Semantic checks operate on the AnalysisPlan shape — PlannerPlan omits
     // maxSteps, so inject the execution-time default to satisfy the validator.
@@ -336,7 +483,7 @@ function fullyValidate(candidate, resourcePolicy) {
  * shared `holder` so the outer `execute` reads the terminal outcome after the
  * loop finishes.
  */
-function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger) {
+function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger, memory) {
     const submitPlanTool = defineTool({
         id: "submit_plan",
         description: "Submit the final plan for persistence. Re-validates the plan; on " +
@@ -375,10 +522,20 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
                 });
             }
             const attempt = ++trace.submitAttempts;
-            const result = fullyValidate(input.plan, resourcePolicy);
-            if (!result.valid) {
+            const { candidate, stamped, restored, repaired, unknown } = restoreSkeletonGrounding(input.plan, memory);
+            if (stamped.length > 0)
+                logger.info("submit_plan stamped the snapshot digest of the answer on steps", { steps: stamped });
+            if (restored.length > 0)
+                logger.info("submit_plan restored the template of skeleton steps", { steps: restored });
+            if (repaired.length > 0)
+                logger.info("submit_plan repaired the claim ids of plan steps", { claims: repaired });
+            const result = fullyValidate(candidate, resourcePolicy);
+            // An unknown claim rejects a plan that the schema accepts, beside the
+            // schema issues when the schema rejects it, thus one attempt shows both.
+            if (!result.valid || unknown.length > 0) {
+                const issues = [...(result.valid ? [] : result.issues), ...unknown];
                 trace.rejectedAttempts++;
-                const rejection = toRejectionRecord(attempt, result.issues);
+                const rejection = toRejectionRecord(attempt, issues);
                 if (trace.rejections.length < MAX_LOGGED_REJECTIONS)
                     trace.rejections.push(rejection);
                 // `warn`, not `debug`: a rejection is non-terminal by design, so the model
@@ -386,7 +543,7 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
                 // an attempt was spent. A run that exhausts its budget on rejections ends
                 // looking identical to one that never tried, and this is the difference.
                 logger.warn("submit_plan rejected a plan", { ...rejection });
-                return ok({ accepted: false, issues: result.issues });
+                return ok({ accepted: false, issues });
             }
             const persisted = await persistPlan(result.plan, persistCtx, pool, logger);
             if (!persisted.ok) {
@@ -431,6 +588,11 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
         }),
         describeCall: "none",
         execute: async (input) => {
+            const degenerate = degenerateTerminalText(input.question);
+            if (degenerate) {
+                logger.warn("request_clarification refused a placeholder question", { question: input.question.slice(0, 80) });
+                return err({ error: `${degenerate} Ask the real question, or continue: submit the plan you have.`, retryable: true });
+            }
             if (holder.outcome !== null) {
                 trace.duplicateTerminalCalls++;
                 logger.warn("request_clarification called after a terminal outcome was recorded", {
@@ -657,7 +819,7 @@ const OUTCOME_LEVEL = {
  * 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.
  */
-function buildPlannerSearchTools(deps) {
+export function buildPlannerSearchTools(deps, hooks = {}) {
     const bioKeys = deps.bioKeys;
     const ncbi = createNcbiTools(bioKeys);
     return [
@@ -687,6 +849,15 @@ function buildPlannerSearchTools(deps) {
             ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
             ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
         }),
+        // The knowledge plane: one cited procedure per situation, and one check
+        // of the draft. Both attach only when the embedder binds a client.
+        ...createKnowledgeTools({
+            ...(deps.knowledge === undefined ? {} : { client: deps.knowledge }),
+            ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
+            ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
+            ...(deps.refStorePath === undefined ? {} : { refStorePath: deps.refStorePath }),
+            ...(hooks.onRecommend === undefined ? {} : { onRecommend: hooks.onRecommend }),
+        }),
     ];
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
@@ -872,12 +1043,28 @@ export function createGeneratePlanTool(deps) {
                 analysisId,
                 parentPlanId: input.parentPlanId ?? null,
             };
-            const innerTools = buildInnerTools(holder, trace, persistCtx, deps.pool, deps.resourcePolicy, logger);
+            // The last recommend answer of this invocation, thus `submit_plan`
+            // stamps the snapshot digest, restores a template the model dropped,
+            // and repairs or refuses a claim id the answer did not return.
+            const memory = { steps: new Map(), claims: new Set() };
+            const innerTools = buildInnerTools(holder, trace, persistCtx, deps.pool, deps.resourcePolicy, logger, memory);
             // Built here rather than at construction: a `describeCall` hook reads no
             // dep, thus the tool must stay constructible from an empty bag. The tool
             // definitions are identical across invocations, thus the request prefix
             // that the cache keys on does not move.
-            const searchTools = buildPlannerSearchTools(deps);
+            // The guard bounds the repeated calls of one plan: the third call with
+            // an input the plan already sent, or the call past the budget of one
+            // tool, answers a refusal that says to continue. The terminal tools
+            // stay outside it, because a refused submit would strand the plan.
+            let refusals = 0;
+            const searchTools = guardRepeatedCalls(buildPlannerSearchTools(deps, {
+                onRecommend: (answer) => rememberAnswer(memory, answer),
+            }), {
+                onRefusal: (refusal) => {
+                    refusals += 1;
+                    logger.warn("planner call refused by the guard", { ...refusal, refusals });
+                },
+            });
             const readTools = deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : [];
             const planner = {
                 id: PLANNER_AGENT_ID,
@@ -901,6 +1088,10 @@ export function createGeneratePlanTool(deps) {
                     emit: ctx.emit,
                     runStep: passthroughStep,
                     resolved: () => holder.outcome !== null,
+                    // A planner the guard refused too many times is looping:
+                    // the early cap ends the search, and the salvage turn
+                    // submits the plan it has.
+                    stopWhen: () => refusals >= PLANNER_REFUSAL_LIMIT,
                     // No forced tool choice: some Claude models reject it with a
                     // 400. The prompt names the terminal tools, and the salvage
                     // turn below recovers a run that ends on prose.

package/dist/tools/research/guarded-address.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The guarded-address classifier of the web research tools.
+ *
+ * One pure function over one address: `isGuardedAddress` answers whether the
+ * address falls in a range that `web_fetch` asks the user about before it
+ * connects. The ranges are a pinned subset of the special-purpose address
+ * ranges of the IANA registries — loopback, private, shared, link-local,
+ * multicast, reserved, documentation, and benchmarking space, IPv4 and IPv6.
+ * A public unicast address is never guarded.
+ *
+ * The caller owns the question "which address does the connection use": the
+ * classifier never resolves a name and it never reads the network.
+ */
+/**
+ * Is this address one the web tools guard? An IP literal of either family
+ * classifies against the pinned table; the IPv4-mapped IPv6 form
+ * (`::ffff:10.0.0.1`) classifies as its IPv4 half. A value that is not an IP
+ * address gives false — the caller resolves names before it reaches here.
+ */
+export declare function isGuardedAddress(ip: string): boolean;