@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/knowledge/client.js

@@ -0,0 +1,319 @@
+/**
+ * The knowledge service interface of the harness.
+ *
+ * `KnowledgeClient` is the one contract between the harness and the remote
+ * knowledge service: four typed operations and the snapshot they answer
+ * from. The harness never knows about a license. It sees a client, or it sees
+ * nothing, and an absent client is a normal state in which no knowledge tool
+ * attaches. `createHttpKnowledgeClient` is the shipped realization over plain
+ * HTTPS with the retry and timeout policy of the other external tools.
+ *
+ * Every operation answers a data variant. A service that is configured but
+ * unreachable gives `{ match: "unavailable" }` after the retry policy, and the
+ * caller continues from the prose skills. A 400 names the field and the
+ * permitted values, thus a model corrects itself in one turn. A 404 on the
+ * contract lookup names the `template` field the same way. The response
+ * shapes below are the harness copy of the wire contract of the service, kept
+ * lenient with `looseObject`, thus a richer answer of a later snapshot still
+ * parses.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { parseJsonAs, safeParseJsonAs } from "../../lib/parse-json.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
+// ── The answers, as the harness reads them ──────────────────────────
+const SnapshotRefSchema = z.object({ date: z.string(), digest: z.string() });
+/** A method of the catalog by id and label. */
+const MethodRefSchema = z.looseObject({ id: z.string(), label: z.string() });
+/** Two rules of equal specificity and strength disagree on a parameter. The step omits the parameter and names both. */
+const ProcedureConflictSchema = z.looseObject({
+    parameter: z.string(),
+    entries: z.array(z.looseObject({ rule: z.string(), value: z.json() })),
+});
+/** The step method is a declared substitute: `for` names the method of record it stands in for. */
+const ProcedureSubstitutionSchema = z.looseObject({ for: z.string(), label: z.string(), template: z.string() });
+/**
+ * No template of the requested language is eligible; the step keeps the first template that is. A skipped template
+ * lacks a design requirement (`missing`), or its slot refuses a value that the rules give (`refused`).
+ */
+const ProcedureLimitSchema = z.looseObject({
+    requested_language: z.enum(["R", "python"]),
+    reason: z.string(),
+    skipped: z.array(z.looseObject({ template: z.string(), missing: z.array(z.string()), refused: z.string().optional() })),
+});
+/** The rules select a method for the step, and no template of the method holds: the knowledge covers the step, and no vetted script does. */
+const ProcedureUnrealizedSchema = z.looseObject({
+    reason: z.string(),
+    templates: z.array(z.looseObject({ template: z.string(), why: z.string() })),
+});
+const ProcedureStepSchema = z.looseObject({
+    step: z.string(),
+    method: MethodRefSchema.optional(),
+    template: z.string().optional(),
+    rules: z.array(z.string()),
+    flags: z.array(z.looseObject({ rule: z.string(), severity: z.string(), message: z.string(), outcome: z.string().optional() })).optional(),
+    alternatives: z.array(z.looseObject({ method: z.string(), label: z.string(), when: z.string(), rules: z.array(z.string()) })).optional(),
+    disputed: z.looseObject({ rule: z.string(), sides: z.array(z.string()) }).optional(),
+    parameters: z.array(z.looseObject({ name: z.string(), value: z.json(), default_source: z.string().optional() })).optional(),
+    conflicts: z.array(ProcedureConflictSchema).optional(),
+    substitution: ProcedureSubstitutionSchema.optional(),
+    limit: ProcedureLimitSchema.optional(),
+    unrealized: ProcedureUnrealizedSchema.optional(),
+    /** The runtime package the step installs, when the service names one. */
+    package: z.looseObject({ name: z.string() }).optional(),
+    /** The forbidden method ids, read defensively by the grounding report. */
+    forbids: z.json().optional(),
+});
+const ClaimSchema = z.looseObject({
+    id: z.string(),
+    statement: z.string(),
+    strength: z.string(),
+    evidence: z.array(z.looseObject({ doi: z.string().optional(), pmid: z.string().optional(), title: z.string(), year: z.number(), direction: z.string() })),
+});
+export const RecommendResponseSchema = z.looseObject({
+    match: z.enum(["applicable", "none", "flag"]),
+    snapshot: SnapshotRefSchema,
+    procedure: z.array(ProcedureStepSchema),
+    uncovered: z.array(z.string()),
+    /** The steps whose method has no eligible template in this situation. Absent when none. */
+    unrealized: z.array(z.string()).optional(),
+    flags: z.array(z.looseObject({ rule: z.string(), severity: z.string(), message: z.string(), outcome: z.string().optional() })),
+    claims: z.array(ClaimSchema),
+    nearest: z.array(z.looseObject({ claim: z.string(), title: z.string(), failed: z.array(z.string()) })).optional(),
+    reason: z.string().optional(),
+});
+const FindingSchema = z.looseObject({
+    step_type: z.string(),
+    severity: z.string(),
+    rule: z.string(),
+    message: z.string(),
+    permitted: z.array(z.string()).optional(),
+});
+/** A drafted step that no rule covers in the situation: neither passed nor failed. */
+const NotAssessedSchema = z.looseObject({ step_type: z.string(), reason: z.string(), message: z.string() });
+export const CheckResponseSchema = z.looseObject({
+    /** True when the assessed steps carry no violation and no warning. A step in `not_assessed` does not count. */
+    ok: z.boolean(),
+    snapshot: SnapshotRefSchema,
+    violations: z.array(FindingSchema),
+    warnings: z.array(FindingSchema),
+    not_assessed: z.array(NotAssessedSchema).optional(),
+});
+export const RenderResponseSchema = z.looseObject({
+    ok: z.literal(true),
+    snapshot: SnapshotRefSchema,
+    template: z.looseObject({
+        id: z.string(),
+        version: z.string(),
+        label: z.string(),
+        /** The method the script runs: the substitute when the template is one. */
+        method: MethodRefSchema,
+        /** The method of record when the template is a declared substitute. */
+        substitute_for: MethodRefSchema.optional(),
+        language: z.string(),
+    }),
+    /** The script with each local slot as its marker `{{name}}`. The host binds the local values before it writes the file. */
+    script: z.string(),
+    /** A local slot entry has no value: the host binds it. */
+    slots: z.array(z.looseObject({
+        name: z.string(),
+        value: z.json().optional(),
+        source: z.string(),
+        adaptable: z.boolean(),
+        lines: z.array(z.number()),
+        read: z.boolean().optional(),
+    })),
+    /** The local slots the host must bind: each marker still in `script`. */
+    local_slots: z.array(z.string()).optional(),
+    environment: z.looseObject({ match: z.string() }),
+    syntax: z.looseObject({ status: z.string() }),
+    outputs: z.array(z.looseObject({ name: z.string(), path: z.string(), description: z.string().optional() })),
+    decision_record: z.record(z.string(), z.json()),
+});
+// ── The template contract ───────────────────────────────────────────
+/** A scalar on the wire. */
+const SlotScalarSchema = z.union([z.string(), z.number(), z.boolean()]);
+/** A slot value on the wire: a scalar, or a list of strings — the contract the service states for a default. */
+const SlotValueSchema = z.union([SlotScalarSchema, z.array(z.string())]);
+/**
+ * One slot of a template with the constraint a caller value must obey.
+ * `adaptable: false` marks a pinned slot: the render refuses a caller value
+ * for it. An adaptable slot without a default is required unless `required`
+ * is false.
+ */
+const TemplateParameterSchema = z.looseObject({
+    name: z.string(),
+    type: z.string(),
+    description: z.string(),
+    adaptable: z.boolean(),
+    /** True for a slot whose value is a fact of the machine (a path, a column name, a level label, a formula): the host binds it, and the service never sees it. */
+    local: z.boolean().optional(),
+    required: z.boolean().optional(),
+    /** A `null` default is a slot with no default: it parses to an absent value. */
+    default: SlotValueSchema.nullish()
+        .transform((value) => value ?? undefined)
+        .optional(),
+    default_source: z.string().optional(),
+    enum: z.array(z.string()).optional(),
+    pattern: z.string().optional(),
+    minimum: z.number().optional(),
+    maximum: z.number().optional(),
+});
+/** A file the script reads. The path names the slot that gives it, for example `{{counts_path}}`. */
+const TemplateInputSchema = z.looseObject({ name: z.string(), path: z.string(), description: z.string().optional() });
+/**
+ * The contract of one template as `GET /v1/templates/{id}` serves it: every
+ * slot, pinned ones included, the inputs, and the outputs. The service adds
+ * fields such as `step_types` and `environment`; they pass through the loose
+ * remainder.
+ */
+export const TemplateContractSchema = z.looseObject({
+    id: z.string(),
+    version: z.string(),
+    label: z.string(),
+    /** The catalog id of the method the script runs. */
+    method: z.string(),
+    /** The catalog id of the method of record when the template is a declared substitute. */
+    substitute_for: z.string().optional(),
+    language: z.string(),
+    /** The design requirements the script realizes. Absent: not subject to them. */
+    honors: z.array(z.string()).optional(),
+    parameters: z.array(TemplateParameterSchema),
+    inputs: z.array(TemplateInputSchema).optional(),
+    outputs: z.array(z.looseObject({ name: z.string(), path: z.string(), description: z.string().optional() })),
+    /** The input requirements in prose, from the applicability of the template. */
+    notes: z.string().optional(),
+});
+const ValidationFailureSchema = z.looseObject({
+    error: z.literal("validation"),
+    message: z.string(),
+    issues: z.array(z.looseObject({
+        message: z.string().optional(),
+        reason: z.string().optional(),
+        field: z.string().optional(),
+        slot: z.string().optional(),
+        permitted: z.array(z.string()).optional(),
+    })),
+});
+/** The runtime shape of that answer, for the paths whose type says it cannot arrive. */
+const SnapshotMismatchAnswerSchema = z.looseObject({
+    match: z.literal("snapshot_mismatch"),
+    message: z.string(),
+});
+/** True when `call` answered a mismatch envelope on a route whose type says it cannot carry one. */
+function isSnapshotMismatchAnswer(answer) {
+    return SnapshotMismatchAnswerSchema.safeParse(answer).success;
+}
+/** The `message` of an error envelope, or the body itself when it is not one. */
+function messageOf(body) {
+    try {
+        const message = parseUnknownRecord(parseJsonAs(body, z.json()))?.["message"];
+        if (typeof message === "string")
+            return message;
+    }
+    catch {
+        // Not JSON: the body is the message.
+    }
+    return body || undefined;
+}
+/** The template id of a reference: `tpl-x@1.0.0` gives `tpl-x`. The service serves one version, thus the route takes the id alone. */
+function templateIdOf(reference) {
+    const at = reference.indexOf("@");
+    return at < 0 ? reference : reference.slice(0, at);
+}
+const SnapshotMismatchSchema = z.looseObject({
+    error: z.literal("snapshot_mismatch"),
+    message: z.string(),
+    expected: z.string(),
+    served: SnapshotRefSchema,
+});
+/**
+ * A 400 is a rejection that names the field and the permitted values. A 404
+ * is one only on a lookup route, where `notFoundField` names the field whose
+ * value the service does not hold. A 409 is a snapshot mismatch: the service
+ * serves another release than the pinned one. Every other failure is
+ * `unavailable`.
+ */
+function refusalOf(error, notFoundField) {
+    if (error.type !== "http_status")
+        return undefined;
+    if (error.status === 404 && notFoundField) {
+        const message = messageOf(error.body) ?? `no such ${notFoundField}`;
+        return { match: "rejected", message, issues: [{ field: notFoundField, message }] };
+    }
+    if (error.status === 409) {
+        let parsed;
+        try {
+            parsed = safeParseJsonAs(error.body, SnapshotMismatchSchema);
+        }
+        catch {
+            return undefined;
+        }
+        if (!parsed.success)
+            return undefined;
+        return { match: "snapshot_mismatch", message: parsed.data.message, expected: parsed.data.expected, served: parsed.data.served };
+    }
+    if (error.status !== 400)
+        return undefined;
+    let parsed;
+    try {
+        parsed = safeParseJsonAs(error.body, ValidationFailureSchema);
+    }
+    catch {
+        return { match: "rejected", message: error.body || "the service refused the request", issues: [] };
+    }
+    if (!parsed.success)
+        return { match: "rejected", message: error.body, issues: [] };
+    return { match: "rejected", message: parsed.data.message, issues: parsed.data.issues };
+}
+export function createHttpKnowledgeClient(config) {
+    // Trim the trailing slashes with a loop, not a regex: CodeQL flags `/\/+$/` on library input as polynomial.
+    let base = config.baseUrl;
+    while (base.endsWith("/"))
+        base = base.slice(0, -1);
+    const authorization = `Bearer ${config.apiKey}`;
+    const policy = { timeoutMs: config.timeoutMs ?? 30_000, maxRetries: config.maxRetries ?? 2, retryDelayMs: 500 };
+    /** One call of the service: a POST with a JSON body, or a GET without one. Every call carries the bearer key. */
+    async function call(method, path, body, schema, notFoundField) {
+        const headers = body === undefined ? { authorization } : { "content-type": "application/json", authorization };
+        const result = await apiFetchValidated(`${base}${path}`, schema, {
+            ...policy,
+            method,
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (result.isOk())
+            return result.value;
+        const refusal = refusalOf(result.error, notFoundField);
+        if (refusal)
+            return refusal;
+        return { match: "unavailable", reason: describeApiError(result.error) };
+    }
+    /** A contract lookup carries no pin, thus a mismatch cannot come back; the type says so. */
+    async function lookup(path, schema, notFoundField) {
+        const answer = await call("GET", path, undefined, schema, notFoundField);
+        // A GET without a body has no pin, thus a 409 is not among its answers; the guard keeps the type honest.
+        if (isSnapshotMismatchAnswer(answer)) {
+            return { match: "unavailable", reason: answer.message };
+        }
+        return answer;
+    }
+    return {
+        recommend: (situation, responseFormat, preferences, expectedSnapshot) => call("POST", "/v1/recommend", {
+            situation,
+            response_format: responseFormat,
+            preferences,
+            expected_snapshot: expectedSnapshot,
+        }, RecommendResponseSchema),
+        check: (situation, steps, expectedSnapshot) => call("POST", "/v1/check", { situation, steps, expected_snapshot: expectedSnapshot }, CheckResponseSchema),
+        render: (template, slots, farm, options) => call("POST", "/v1/template/render", {
+            template,
+            slots,
+            farm,
+            step: options?.step,
+            claims: options?.claims,
+            expected_snapshot: options?.expectedSnapshot,
+        }, RenderResponseSchema),
+        contract: (template) => lookup(`/v1/templates/${encodeURIComponent(templateIdOf(template))}`, TemplateContractSchema, "template"),
+    };
+}

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

@@ -0,0 +1,78 @@
+/**
+ * The environment join of a procedure: which package of each step the farm
+ * holds, at which version, and which collection of the reference store the
+ * enrichment step names. The service knows the methods and the collections
+ * by name; the host knows what is installed. Joined here, the answer of
+ * `knowledge_recommend` carries the environment, and a planner has no reason
+ * to call the listing tools for the packages and the collection it was told
+ * to use. A model that hunts for what it already has was the cost of the
+ * Phase 0 campaigns on a small model.
+ *
+ * The installed packages come from two records the host reads, never from a
+ * list in the code: the `inflexa.lock` of the farm names the packages the
+ * store links, and the `image-packages.json` of the store names what the
+ * sandbox image itself ships, among them the R packages of the R runtime
+ * (`stats`, `survival`, `MASS`), which no farm lock lists. Both records are
+ * written by their producers and validated here.
+ *
+ * Absence is data: a package neither record names reads `present: false`,
+ * and a collection the store lacks reads `present: false`. The join never
+ * fills a gap and never names a path it did not read.
+ */
+import type { FarmPackage, RecommendResponse } from "./client.js";
+export type EnvironmentPaths = {
+    /** Host path of the farm `inflexa.lock`. Absent, the packages read as unknown. */
+    readonly farmLockFile?: string;
+    /** Host path of the `image-packages.json` of the store. Absent, the packages the image ships are unknown. */
+    readonly imagePackagesFile?: string;
+    /** Host path of the reference store. Absent, the collection reads as unknown. */
+    readonly refStorePath?: string;
+};
+export type StepEnvironment = {
+    readonly package?: {
+        readonly name: string;
+        readonly present: boolean;
+        readonly version?: string;
+    };
+    readonly collection?: {
+        readonly name: string;
+        readonly present: boolean;
+        readonly path?: string;
+        readonly title?: string;
+    };
+};
+/** Where each fact of the environment came from: a record the host read, or nothing. */
+export type EnvironmentSource = {
+    readonly farm: "lock" | "unknown";
+    /** `record` when the store carries the `image-packages.json` of the sandbox image. */
+    readonly image: "record" | "unknown";
+    readonly references: "store" | "unknown";
+};
+/** The recommend answer with an `environment` per step. */
+export type RecommendWithEnvironment = RecommendResponse & {
+    readonly environment_source?: EnvironmentSource;
+    readonly procedure: readonly (RecommendResponse["procedure"][number] & {
+        readonly environment?: StepEnvironment;
+    })[];
+};
+/**
+ * The packages installed in the sandbox, as the two records report them, with
+ * one entry per name. The farm lock comes first and it wins a collision,
+ * because a farm that links its own copy of a package is what a step loads.
+ * `packages` is absent when neither record is readable, thus a caller sends
+ * nothing to the knowledge service rather than an empty farm, and the answer
+ * reads `unknown` instead of "absent".
+ *
+ * Of the image record only the R runtime track joins the list. The conda
+ * tools and the Node packages of the image are not of the package tracks a
+ * template pins, and a name of one of them must not answer for a package.
+ *
+ * The same list serves the environment join of the recommend answer and the
+ * environment match of a rendered template, thus the two agree.
+ */
+export declare function installedPackages(paths: Pick<EnvironmentPaths, "farmLockFile" | "imagePackagesFile">): {
+    readonly packages?: readonly FarmPackage[];
+    readonly farm: EnvironmentSource["farm"];
+    readonly image: EnvironmentSource["image"];
+};
+export declare function joinEnvironment(answer: RecommendResponse, paths: EnvironmentPaths): Promise<RecommendWithEnvironment>;

package/dist/tools/knowledge/environment.js

@@ -0,0 +1,116 @@
+/**
+ * The environment join of a procedure: which package of each step the farm
+ * holds, at which version, and which collection of the reference store the
+ * enrichment step names. The service knows the methods and the collections
+ * by name; the host knows what is installed. Joined here, the answer of
+ * `knowledge_recommend` carries the environment, and a planner has no reason
+ * to call the listing tools for the packages and the collection it was told
+ * to use. A model that hunts for what it already has was the cost of the
+ * Phase 0 campaigns on a small model.
+ *
+ * The installed packages come from two records the host reads, never from a
+ * list in the code: the `inflexa.lock` of the farm names the packages the
+ * store links, and the `image-packages.json` of the store names what the
+ * sandbox image itself ships, among them the R packages of the R runtime
+ * (`stats`, `survival`, `MASS`), which no farm lock lists. Both records are
+ * written by their producers and validated here.
+ *
+ * Absence is data: a package neither record names reads `present: false`,
+ * and a collection the store lacks reads `present: false`. The join never
+ * fills a gap and never names a path it did not read.
+ */
+import { readFarmLockFile } from "../../sandbox/farm.js";
+import { readImagePackagesFile } from "../../sandbox/image-packages.js";
+import { readReferenceInventory } from "../sandbox/list-available-refs.js";
+/**
+ * The packages installed in the sandbox, as the two records report them, with
+ * one entry per name. The farm lock comes first and it wins a collision,
+ * because a farm that links its own copy of a package is what a step loads.
+ * `packages` is absent when neither record is readable, thus a caller sends
+ * nothing to the knowledge service rather than an empty farm, and the answer
+ * reads `unknown` instead of "absent".
+ *
+ * Of the image record only the R runtime track joins the list. The conda
+ * tools and the Node packages of the image are not of the package tracks a
+ * template pins, and a name of one of them must not answer for a package.
+ *
+ * The same list serves the environment join of the recommend answer and the
+ * environment match of a rendered template, thus the two agree.
+ */
+export function installedPackages(paths) {
+    const lock = paths.farmLockFile ? readFarmLockFile(paths.farmLockFile).unwrapOr(undefined) : undefined;
+    const record = paths.imagePackagesFile ? readImagePackagesFile(paths.imagePackagesFile).unwrapOr(undefined) : undefined;
+    if (!lock && !record)
+        return { farm: "unknown", image: "unknown" };
+    const packages = [];
+    const seen = new Set();
+    for (const pkg of [...(lock?.packages ?? []), ...(record?.r_base ?? [])]) {
+        const key = pkg.name.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        packages.push({ name: pkg.name, version: pkg.version });
+    }
+    return { packages, farm: lock ? "lock" : "unknown", image: record ? "record" : "unknown" };
+}
+function tokens(text) {
+    const tokens = [];
+    let token = "";
+    const flush = () => {
+        if (token.length > 1)
+            tokens.push(token);
+        token = "";
+    };
+    for (const char of text.toLowerCase()) {
+        if ((char >= "a" && char <= "z") || (char >= "0" && char <= "9"))
+            token += char;
+        else
+            flush();
+    }
+    flush();
+    return tokens;
+}
+/** A collection term of the tree (`msigdb_hallmark_human`) matches an entry whose labels hold every token of the term. */
+function findCollection(term, entries) {
+    const wanted = tokens(term);
+    if (wanted.length === 0)
+        return undefined;
+    const candidates = entries.filter((entry) => {
+        const haystack = tokens([entry.path, entry.metadata?.datasetId ?? "", entry.metadata?.title ?? ""].join(" "));
+        return wanted.every((token) => haystack.includes(token));
+    });
+    // A directory entry names the dataset; a file inside it is the concrete artifact. Prefer the file.
+    return candidates.find((entry) => entry.kind === "file") ?? candidates[0];
+}
+export async function joinEnvironment(answer, paths) {
+    if (answer.match !== "applicable" && answer.match !== "flag")
+        return answer;
+    const installed = installedPackages(paths);
+    const farm = installed.packages ? new Map(installed.packages.map((pkg) => [pkg.name.toLowerCase(), pkg.version])) : undefined;
+    const inventory = paths.refStorePath ? await readReferenceInventory(paths.refStorePath).catch(() => undefined) : undefined;
+    const entries = inventory?.available ? inventory.entries : undefined;
+    const procedure = answer.procedure.map((step) => {
+        const environment = {};
+        const pkg = step.package;
+        if (pkg && farm) {
+            const version = farm.get(pkg.name.toLowerCase());
+            environment.package = { name: pkg.name, present: version !== undefined, version };
+        }
+        const collection = step.parameters?.find((parameter) => parameter.name === "gene_set_collection");
+        if (collection && typeof collection.value === "string" && entries) {
+            const found = findCollection(collection.value, entries);
+            environment.collection = {
+                name: collection.value,
+                present: found !== undefined,
+                path: found?.path,
+                title: found?.metadata?.title,
+            };
+        }
+        return Object.keys(environment).length > 0 ? { ...step, environment } : step;
+    });
+    return {
+        ...answer,
+        procedure,
+        environment_source: { farm: installed.farm, image: installed.image, references: entries ? "store" : "unknown" },
+    };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Knowledge barrel — the three tools of the knowledge plane and the client
+ * interface they share.
+ *
+ * `createKnowledgeTools` gives the two planner tools when a client is bound,
+ * and nothing when it is not. Absence is the default state of the open-source
+ * host, and it is a normal condition: no tool attaches, no description enters
+ * the context, and the planner works from the prose skills as it does today.
+ * The template tool binds per step, because it needs the mutator of the step.
+ */
+import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
+import type { Tool } from "../define-tool.js";
+import type { KnowledgeClient } from "./client.js";
+import { type KnowledgeRecommendDeps } from "./recommend.js";
+export * from "./client.js";
+export * from "./environment.js";
+export * from "./local-slots.js";
+export * from "./pin.js";
+export * from "./skeleton.js";
+export * from "./check.js";
+export * from "./recommend.js";
+export * from "./situation.js";
+export * from "./template.js";
+export type KnowledgeToolsDeps = {
+    readonly client?: KnowledgeClient;
+    /** Host path of the farm `inflexa.lock`, or its resolver for each analysis, for the environment join of the recommend answer. */
+    readonly farmLockFile?: EnvironmentStorePaths["farmLockFile"];
+    /** Host path of the `image-packages.json` of the store, for the same join: the packages the sandbox image ships. */
+    readonly imagePackagesFile?: string;
+    /** Host path of the reference store, for the same join. */
+    readonly refStorePath?: string;
+    /** Receives each recommend answer the planner sees; see `KnowledgeRecommendDeps.onAnswer`. */
+    readonly onRecommend?: KnowledgeRecommendDeps["onAnswer"];
+};
+/**
+ * The planner tools: `knowledge_recommend` and `knowledge_check`, or an empty
+ * list with no client. The two share one pin: the first recommend answer
+ * fixes the release of the plan, and each later call carries it.
+ */
+export declare function createKnowledgeTools(deps: KnowledgeToolsDeps): Tool[];
+/**
+ * The digest of the three tool definitions as this host registers them: the
+ * id, the description, and the input schema of each, in id order. The
+ * snapshot of the service pins its wire contract under its own tool
+ * definition hash; this one names what the model saw, and a run records it,
+ * thus a changed description or schema is a visible change of the run and
+ * not a silent one.
+ */
+export declare function knowledgeToolDefinitionHash(): string;

package/dist/tools/knowledge/index.js

@@ -0,0 +1,70 @@
+/**
+ * Knowledge barrel — the three tools of the knowledge plane and the client
+ * interface they share.
+ *
+ * `createKnowledgeTools` gives the two planner tools when a client is bound,
+ * and nothing when it is not. Absence is the default state of the open-source
+ * host, and it is a normal condition: no tool attaches, no description enters
+ * the context, and the planner works from the prose skills as it does today.
+ * The template tool binds per step, because it needs the mutator of the step.
+ */
+import { createHash } from "node:crypto";
+import { createKnowledgeCheckTool } from "./check.js";
+import { createSnapshotPin } from "./pin.js";
+import { createKnowledgeRecommendTool } from "./recommend.js";
+import { createKnowledgeTemplateTool } from "./template.js";
+export * from "./client.js";
+export * from "./environment.js";
+export * from "./local-slots.js";
+export * from "./pin.js";
+export * from "./skeleton.js";
+export * from "./check.js";
+export * from "./recommend.js";
+export * from "./situation.js";
+export * from "./template.js";
+/**
+ * The planner tools: `knowledge_recommend` and `knowledge_check`, or an empty
+ * list with no client. The two share one pin: the first recommend answer
+ * fixes the release of the plan, and each later call carries it.
+ */
+export function createKnowledgeTools(deps) {
+    if (!deps.client)
+        return [];
+    const pin = createSnapshotPin();
+    return [
+        createKnowledgeRecommendTool({
+            client: deps.client,
+            pin,
+            farmLockFile: deps.farmLockFile,
+            imagePackagesFile: deps.imagePackagesFile,
+            refStorePath: deps.refStorePath,
+            onAnswer: deps.onRecommend,
+        }),
+        createKnowledgeCheckTool({ client: deps.client, pin }),
+    ];
+}
+/** A client that answers nothing: the definitions of the tools do not depend on the answers. */
+const NO_CLIENT = {
+    recommend: () => Promise.resolve({ match: "unavailable", reason: "no service" }),
+    check: () => Promise.resolve({ match: "unavailable", reason: "no service" }),
+    render: () => Promise.resolve({ match: "unavailable", reason: "no service" }),
+    contract: () => Promise.resolve({ match: "unavailable", reason: "no service" }),
+};
+/** A mutator that writes nothing: the definition of the template tool does not depend on the workspace. */
+const NO_MUTATOR = {
+    writeFile: ({ path }) => Promise.resolve({ status: "out_of_scope", path }),
+    recordWrite: () => undefined,
+};
+/**
+ * The digest of the three tool definitions as this host registers them: the
+ * id, the description, and the input schema of each, in id order. The
+ * snapshot of the service pins its wire contract under its own tool
+ * definition hash; this one names what the model saw, and a run records it,
+ * thus a changed description or schema is a visible change of the run and
+ * not a silent one.
+ */
+export function knowledgeToolDefinitionHash() {
+    const tools = [...createKnowledgeTools({ client: NO_CLIENT }), createKnowledgeTemplateTool({ client: NO_CLIENT, mutator: NO_MUTATOR })];
+    const definitions = tools.map((tool) => ({ id: tool.id, description: tool.description, schema: tool.jsonSchema })).sort((a, b) => (a.id < b.id ? -1 : 1));
+    return `sha256:${createHash("sha256").update(JSON.stringify(definitions), "utf8").digest("hex")}`;
+}