@tangle-network/agent-interface 2.9.0 → 2.11.0

package/README.md

@@ -172,6 +172,30 @@ When caller environment values merge into a bridge or harness process, reject na
 Use `isCredentialBearingProfileConfigName(name)` before retaining public config.
 These checks do not apply to a replacement environment owned by caller code.
 
+## Profile knowledge base
+
+`@tangle-network/agent-interface/profile-kb` holds how to get the best from each frontier harness and model this platform runs.
+Every entry cites a vendor source or a command run on a dated check.
+Guidance is specific to one harness or model and never compares models.
+
+`withProfileKb(profile)` composes harness guidance, then model guidance, then the profile's own text into the profile's prompt:
+
+```ts
+import { withProfileKb } from "@tangle-network/agent-interface/profile-kb";
+
+const worker = withProfileKb({
+  harness: "claude-code",
+  model: { default: "claude-opus-5-5" },
+  prompt: { appendSystemPrompt: "Cite the file you read." },
+});
+```
+
+Guidance goes into `appendSystemPrompt` where the harness owns an additive system-prompt control, and into `instructions` otherwise.
+Recomposing replaces earlier guidance, so a second call, or a call with an executor's harness or model override, yields a stable profile.
+`composeAgentProfileGuidance` is the underlying composer for other knowledge layers.
+
+The module also exports the data (`profileKbHarnesses`, `profileKbModels`), operator notes for launching each harness and model, platform learnings (admitted only after an agent-eval check reproduced them), and `profileKbDiscrepancies`, which records where a vendor source states a requested name differently.
+
 ## Failed execution accounting
 
 An adapter can reject with `AgentExecutionError` and retain observed usage and timing in its immutable `receipt`.

package/dist/agent-profile.d.ts

@@ -12,6 +12,7 @@
  * fixed. This package is the canonical public home for these symbols.
  */
 import type { HarnessType } from "./harness.js";
+import type { Sha256Digest } from "./agent-candidate.js";
 /**
  * Permission policy value for a capability.
  */
@@ -343,6 +344,53 @@ export interface AgentProfileConnection {
      */
     alias?: string;
 }
+/** Router namespace reserved for checkpoint-backed models. Receipt-free profiles cannot use it. */
+export declare const TRAINED_MODEL_PREFIX = "tangle-trained/";
+/** An immutable Router alias; serving must independently attest this artifact-to-route binding. */
+export declare function trainedModelIdForArtifact(digest: Sha256Digest): string;
+/** Identity of a task whose data was exposed to training or model selection. */
+export interface AgentTrainingTask {
+    benchmark: string;
+    task: string;
+    contentDigest: Sha256Digest;
+}
+/** Complete exposure inventory, derived from the exact dataset delivered to a trainer. */
+export interface AgentTrainingDatasetIdentity {
+    digest: Sha256Digest;
+    taskSetDigest: Sha256Digest;
+    tasks: AgentTrainingTask[];
+}
+export interface AgentTrainingReceipt {
+    version: 1;
+    dataset: AgentTrainingDatasetIdentity;
+    parentProfileDigest: Sha256Digest;
+    /** Null only when the parent has no training receipt. */
+    parentReceiptDigest: Sha256Digest | null;
+    executionRef: Sha256Digest;
+    trainer: {
+        mode: "command" | "managed";
+        id: string;
+        revision: Sha256Digest;
+        /** Public hyperparameters only; credentials belong to the private executor. */
+        parameters: Record<string, string | number | boolean | null>;
+    };
+    checkpoint: {
+        artifactDigest: Sha256Digest;
+        artifactBytes: number;
+        routerModelId: string;
+        /** Digest of independently verified serving evidence, not trainer stdout. */
+        servingDigest: Sha256Digest;
+    };
+}
+export interface AgentProfileTraining {
+    receipt: AgentTrainingReceipt;
+    /** Immediate parent first, terminating at a receipt with parentReceiptDigest=null. */
+    ancestors: AgentTrainingReceipt[];
+}
+export interface AgentProfileMetadata extends Record<string, unknown> {
+    /** Reserved: a trained model is admitted only with a complete checkpoint receipt. */
+    training?: AgentProfileTraining;
+}
 /**
  * Public provider-neutral agent profile contract.
  */
@@ -374,7 +422,7 @@ export interface AgentProfile {
     hooks?: Record<string, AgentProfileHookCommand[]>;
     modes?: Record<string, AgentProfileMode>;
     confidential?: AgentProfileConfidential;
-    metadata?: Record<string, unknown>;
+    metadata?: AgentProfileMetadata;
     /**
      * Non-portable backend-specific extensions.
      *
@@ -471,4 +519,35 @@ export interface AgentProfileValidationResult {
  * base-first with a blank line between them.
  */
 export declare function mergeAgentProfiles(base: AgentProfile | undefined, overlay: AgentProfile | undefined): AgentProfile | undefined;
+/**
+ * One block of standing guidance composed into a profile's prompt.
+ *
+ * `source` names the layer the text came from (`harness`, `model`, or another
+ * knowledge layer) and `id` names the subject, so a composed block can be
+ * found and replaced later. The profile's own prompt text is never a block:
+ * it is what the blocks are composed in front of.
+ */
+export interface AgentProfileGuidanceBlock {
+    source: string;
+    id: string;
+    text: string;
+}
+/**
+ * Where composed guidance lands. `appendSystemPrompt` keeps the harness's
+ * system prompt and adds the guidance to it; `instructions` uses the
+ * harness's caller-instruction surface, for harnesses that own no additive
+ * system-prompt control.
+ */
+export type AgentProfileGuidanceChannel = "appendSystemPrompt" | "instructions";
+/**
+ * Compose harness, model, and other layered guidance into a profile's prompt.
+ *
+ * The blocks come first, in the order given, and the profile's own text comes
+ * last, so the most specific instruction (the profile's) is the one a model
+ * reads after the general guidance. Composition replaces any blocks a previous
+ * composition added, on both channels, so recomposing after a harness or
+ * model change never stacks stale guidance. Composing the same blocks twice
+ * yields the same profile, and with it the same canonical identity.
+ */
+export declare function composeAgentProfileGuidance(profile: AgentProfile, blocks: readonly AgentProfileGuidanceBlock[], channel: AgentProfileGuidanceChannel): AgentProfile;
 export {};

package/dist/agent-profile.js

@@ -63,6 +63,12 @@ export function defineAgentProfileSecretRef(key, format) {
         ...(format === undefined ? {} : { format }),
     };
 }
+/** Router namespace reserved for checkpoint-backed models. Receipt-free profiles cannot use it. */
+export const TRAINED_MODEL_PREFIX = "tangle-trained/";
+/** An immutable Router alias; serving must independently attest this artifact-to-route binding. */
+export function trainedModelIdForArtifact(digest) {
+    return `${TRAINED_MODEL_PREFIX}${digest.slice("sha256:".length)}`;
+}
 /**
  * Helper for declaring typed profiles in application code.
  */
@@ -167,3 +173,62 @@ export function mergeAgentProfiles(base, overlay) {
         extensions: mergeRecord(base?.extensions, overlay?.extensions),
     });
 }
+const GUIDANCE_OPEN = /^<profile-guidance source="[^"]*" id="[^"]*">\n/;
+const GUIDANCE_BLOCK = /<profile-guidance source="[^"]*" id="[^"]*">\n[\s\S]*?\n<\/profile-guidance>(\n\n)?/g;
+function renderGuidanceBlock(block) {
+    if (/["\n]/.test(block.source) || /["\n]/.test(block.id)) {
+        throw new TypeError("profile guidance source and id must not contain quotes or newlines");
+    }
+    if (block.text.includes("</profile-guidance>")) {
+        throw new TypeError("profile guidance text must not contain the closing block marker");
+    }
+    return `<profile-guidance source="${block.source}" id="${block.id}">\n${block.text}\n</profile-guidance>`;
+}
+/** Remove every previously composed guidance block from appended prompt text. */
+function stripGuidanceText(text) {
+    if (text === undefined || text === "")
+        return text;
+    const stripped = text.replace(GUIDANCE_BLOCK, "");
+    return stripped === "" ? undefined : stripped;
+}
+/**
+ * Compose harness, model, and other layered guidance into a profile's prompt.
+ *
+ * The blocks come first, in the order given, and the profile's own text comes
+ * last, so the most specific instruction (the profile's) is the one a model
+ * reads after the general guidance. Composition replaces any blocks a previous
+ * composition added, on both channels, so recomposing after a harness or
+ * model change never stacks stale guidance. Composing the same blocks twice
+ * yields the same profile, and with it the same canonical identity.
+ */
+export function composeAgentProfileGuidance(profile, blocks, channel) {
+    const prompt = profile.prompt ?? {};
+    const ownAppend = stripGuidanceText(prompt.appendSystemPrompt);
+    const ownInstructions = prompt.instructions?.filter((line) => !GUIDANCE_OPEN.test(line));
+    const rendered = blocks.map(renderGuidanceBlock);
+    const next = { ...prompt };
+    delete next.appendSystemPrompt;
+    delete next.instructions;
+    if (channel === "appendSystemPrompt") {
+        const parts = [...rendered, ...(ownAppend ? [ownAppend] : [])];
+        if (parts.length > 0)
+            next.appendSystemPrompt = parts.join("\n\n");
+        else if (ownAppend !== undefined)
+            next.appendSystemPrompt = ownAppend;
+        if (ownInstructions !== undefined)
+            next.instructions = ownInstructions;
+    }
+    else {
+        if (ownAppend !== undefined)
+            next.appendSystemPrompt = ownAppend;
+        const lines = [...rendered, ...(ownInstructions ?? [])];
+        if (lines.length > 0 || prompt.instructions !== undefined) {
+            next.instructions = lines;
+        }
+    }
+    const result = { ...profile };
+    if (Object.keys(next).length > 0 || profile.prompt !== undefined) {
+        result.prompt = next;
+    }
+    return result;
+}

package/dist/environment-interactive-start.d.ts

@@ -216,7 +216,7 @@ export declare const AgentInteractiveSessionStartSchema: z.ZodObject<{
             sealed: z.ZodOptional<z.ZodBoolean>;
             attestationRefresh: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
-        metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        metadata: z.ZodOptional<z.ZodType<import("./agent-profile.js").AgentProfileMetadata, unknown, z.core.$ZodTypeInternals<import("./agent-profile.js").AgentProfileMetadata, unknown>>>;
         extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
     }, z.core.$strict>;
     requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

package/dist/profile-kb/harnesses.d.ts

@@ -0,0 +1,9 @@
+import type { ProfileKbHarness } from "./types.js";
+/**
+ * The frontier coding harnesses this platform runs, checked against the
+ * installed CLI on 2026-09-22.
+ *
+ * `prompt` lines go into the agent's prompt; `operator` lines are launch
+ * facts. Each harness is described on its own terms.
+ */
+export declare const profileKbHarnesses: readonly ProfileKbHarness[];

package/dist/profile-kb/harnesses.js

@@ -0,0 +1,115 @@
+const CHECKED = "2026-09-22";
+/**
+ * The frontier coding harnesses this platform runs, checked against the
+ * installed CLI on 2026-09-22.
+ *
+ * `prompt` lines go into the agent's prompt; `operator` lines are launch
+ * facts. Each harness is described on its own terms.
+ */
+export const profileKbHarnesses = [
+    {
+        id: "claude-code",
+        name: "Claude Code",
+        version: "2.1.280",
+        sources: [
+            {
+                url: "https://code.claude.com/docs/en/cli-reference",
+                checkedAt: CHECKED,
+            },
+            { url: "cli:claude --help", checkedAt: CHECKED, note: "2.1.280" },
+        ],
+        prompt: [
+            "Delegate independent slices to subagents, several in one turn so they run in parallel, then synthesize their results.",
+            "Use the skills listed in your session for procedures they cover.",
+            "Run long commands in the background and keep working while they finish.",
+        ],
+        operator: [
+            "Headless: `claude -p <prompt> --model <id> --effort <level> --output-format stream-json`.",
+            "`--append-system-prompt` adds to the built-in prompt; `--system-prompt` replaces it.",
+            "`--max-budget-usd` caps spend; `--json-schema` validates structured output; `--mcp-config` loads MCP servers.",
+            "`--bg` starts a background session; `--bare` skips hooks, plugins, memory, and CLAUDE.md discovery.",
+        ],
+    },
+    {
+        id: "codex",
+        name: "Codex CLI",
+        version: "0.152.1",
+        sources: [
+            { url: "https://learn.chatgpt.com/docs/models", checkedAt: CHECKED },
+            {
+                url: "cli:codex exec --help; codex features list",
+                checkedAt: CHECKED,
+                note: "0.152.1; multi_agent stable and enabled",
+            },
+        ],
+        prompt: [
+            "Split independent work across child agents with spawn_agent, and join them with wait_agent.",
+            "Edit with apply_patch and search with rg.",
+            "Carry the task end to end in this turn: gather context, implement, run the checks, and report the evidence.",
+        ],
+        operator: [
+            "Headless: `codex exec <prompt> -m <model> -c model_reasoning_effort=<level> --json -o <last-message-file>`.",
+            "`--output-schema <file>` enforces structured output. `codex review` runs a non-interactive review.",
+            "Reasoning levels are per model; read them from `$CODEX_HOME/models_cache.json`.",
+            "System-prompt replacement uses the `model_instructions_file` config key; standing instructions go in AGENTS.md.",
+            "`/goal` runs long unattended work; `resume` and `fork` continue a session.",
+        ],
+    },
+    {
+        id: "opencode",
+        name: "OpenCode",
+        version: "1.18.18",
+        sources: [
+            { url: "https://opencode.ai/docs/cli/", checkedAt: CHECKED },
+            { url: "cli:opencode run --help", checkedAt: CHECKED, note: "1.18.18" },
+        ],
+        prompt: [
+            "Delegate a focused subtask to a named agent when its persona or model fits the subtask.",
+            "Use the mounted MCP tools for external actions.",
+        ],
+        operator: [
+            "Headless: `opencode run <message> -m <provider/model> --agent <name> --variant <effort> --format json`.",
+            "Standing text goes through `instructions` files or appended system text; the built-in prompt stays in place.",
+            "`opencode serve` with `run --attach <url>`, or `opencode acp`, gives a parent live control.",
+        ],
+    },
+    {
+        id: "pi",
+        name: "Pi",
+        version: "0.83.0",
+        sources: [
+            { url: "cli:pi --help", checkedAt: CHECKED, note: "0.83.0" },
+        ],
+        prompt: [
+            "Expect steering messages mid-run and fold each one into the current plan.",
+            "Fan out independent work by running `pi -p <task> --mode json` from bash, several at once, and read the results back.",
+        ],
+        operator: [
+            "Headless: `pi -p <prompt> --model <provider/id[:thinking]> --mode json`.",
+            "`--mode rpc` takes JSONL commands on stdin (steer, follow-up, set model, compact, fork) for live control.",
+            "`--thinking` takes off, minimal, low, medium, high, xhigh, or max.",
+            "`--system-prompt` replaces the default; `--append-system-prompt` adds to it.",
+        ],
+    },
+    {
+        id: "kimi-code",
+        name: "Kimi Code CLI",
+        version: "0.36.1",
+        sources: [
+            { url: "https://moonshotai.github.io/kimi-code/", checkedAt: CHECKED },
+            {
+                url: "cli:kimi --help; ~/.kimi-code/config.toml",
+                checkedAt: CHECKED,
+                note: "0.36.1",
+            },
+        ],
+        prompt: [
+            "Plan the change first, then edit and verify each step against tests and runtime output.",
+        ],
+        operator: [
+            "Headless: `kimi -p <prompt> -m kimi-code/k3 --output-format stream-json`.",
+            "`--auto` runs fully autonomous; `--agent-file <path>` loads an agent definition; `--plan` starts in plan mode.",
+            "Effort is the `[thinking] effort` key in `~/.kimi-code/config.toml`: low, high, or max.",
+        ],
+    },
+];

package/dist/profile-kb/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Profile knowledge base: how to get the best from each frontier harness and
+ * model this platform runs, from current vendor sources, composed into an
+ * {@link AgentProfile}'s prompt.
+ *
+ * The data is plain, dated, and sourced. Composition is pure: the same profile
+ * yields the same composed profile, so profile identity stays deterministic.
+ */
+import { type AgentProfile, type AgentProfileGuidanceBlock } from "../agent-profile.js";
+import type { HarnessType } from "../harness.js";
+import { profileKbHarnesses } from "./harnesses.js";
+import { profileKbModels } from "./models.js";
+import { profileKbDiscrepancies, profileKbLearnings } from "./records.js";
+import type { ProfileKbHarness, ProfileKbModel } from "./types.js";
+export type * from "./types.js";
+export { profileKbDiscrepancies, profileKbHarnesses, profileKbLearnings, profileKbModels, };
+/** Date the knowledge base was last checked against its sources. */
+export declare const PROFILE_KB_CHECKED_AT = "2026-09-22";
+/** Find a harness entry by its {@link HarnessType}. */
+export declare function findProfileKbHarness(harness: HarnessType | string | undefined): ProfileKbHarness | undefined;
+/**
+ * Find a model entry by id or alias.
+ *
+ * Accepts the spellings harnesses and routers use: a provider prefix
+ * (`anthropic/claude-opus-5-5`), a route prefix
+ * (`pi/tangle-router/deepseek/deepseek-v4.1-flash`), and a trailing `:suffix`
+ * such as pi's thinking level or a router's `:batch`. A different version is a
+ * different model and never matches.
+ */
+export declare function findProfileKbModel(model: string | undefined): ProfileKbModel | undefined;
+/** Which harness and model to compose guidance for. */
+export interface ProfileKbSelection {
+    harness?: HarnessType | string;
+    model?: string;
+}
+/**
+ * The guidance blocks for one harness and model: the harness's, then the
+ * model's, then any reproduced platform learnings for either. Unknown names
+ * contribute nothing.
+ */
+export declare function profileKbGuidance(selection: ProfileKbSelection): AgentProfileGuidanceBlock[];
+/**
+ * Compose harness, model, and profile guidance into the profile's prompt.
+ *
+ * The harness and model default to the profile's own `harness` and
+ * `model.default`; pass a selection to compose for an executor's override.
+ * Guidance goes into `appendSystemPrompt` where the harness owns an additive
+ * system-prompt control and into `instructions` otherwise, so a harness that
+ * refuses appended system text still receives it. The profile's own text
+ * stays last. Recomposing replaces earlier guidance, so the result is stable.
+ */
+export declare function withProfileKb(profile: AgentProfile, selection?: ProfileKbSelection): AgentProfile;

package/dist/profile-kb/index.js

@@ -0,0 +1,127 @@
+/**
+ * Profile knowledge base: how to get the best from each frontier harness and
+ * model this platform runs, from current vendor sources, composed into an
+ * {@link AgentProfile}'s prompt.
+ *
+ * The data is plain, dated, and sourced. Composition is pure: the same profile
+ * yields the same composed profile, so profile identity stays deterministic.
+ */
+import { composeAgentProfileGuidance, } from "../agent-profile.js";
+import { harnessSystemPromptIntents } from "../harness-capabilities.js";
+import { profileKbHarnesses } from "./harnesses.js";
+import { profileKbModels } from "./models.js";
+import { profileKbDiscrepancies, profileKbLearnings } from "./records.js";
+export { profileKbDiscrepancies, profileKbHarnesses, profileKbLearnings, profileKbModels, };
+/** Date the knowledge base was last checked against its sources. */
+export const PROFILE_KB_CHECKED_AT = "2026-09-22";
+/** Find a harness entry by its {@link HarnessType}. */
+export function findProfileKbHarness(harness) {
+    if (!harness)
+        return undefined;
+    return profileKbHarnesses.find((entry) => entry.id === harness);
+}
+const modelIndex = (() => {
+    const index = new Map();
+    for (const model of profileKbModels) {
+        for (const name of [model.id, ...model.aliases]) {
+            const key = name.toLowerCase();
+            if (index.has(key)) {
+                throw new Error(`profile-kb: model name ${name} is declared twice`);
+            }
+            index.set(key, model);
+        }
+    }
+    return index;
+})();
+/**
+ * Find a model entry by id or alias.
+ *
+ * Accepts the spellings harnesses and routers use: a provider prefix
+ * (`anthropic/claude-opus-5-5`), a route prefix
+ * (`pi/tangle-router/deepseek/deepseek-v4.1-flash`), and a trailing `:suffix`
+ * such as pi's thinking level or a router's `:batch`. A different version is a
+ * different model and never matches.
+ */
+export function findProfileKbModel(model) {
+    if (!model)
+        return undefined;
+    const colon = model.lastIndexOf(":");
+    let candidate = (colon > 0 ? model.slice(0, colon) : model)
+        .trim()
+        .toLowerCase();
+    for (;;) {
+        const found = modelIndex.get(candidate);
+        if (found)
+            return found;
+        const slash = candidate.indexOf("/");
+        if (slash < 0)
+            return undefined;
+        candidate = candidate.slice(slash + 1);
+    }
+}
+function learningsFor(harness, model) {
+    return profileKbLearnings.filter((learning) => {
+        const scope = learning.appliesTo;
+        if (scope.harness !== undefined && scope.harness !== harness?.id) {
+            return false;
+        }
+        if (scope.model !== undefined && scope.model !== model?.id)
+            return false;
+        return scope.harness !== undefined || scope.model !== undefined;
+    });
+}
+function bullets(lines) {
+    return lines.map((line) => `- ${line}`).join("\n");
+}
+/**
+ * The guidance blocks for one harness and model: the harness's, then the
+ * model's, then any reproduced platform learnings for either. Unknown names
+ * contribute nothing.
+ */
+export function profileKbGuidance(selection) {
+    const harness = findProfileKbHarness(selection.harness);
+    const model = findProfileKbModel(selection.model);
+    const blocks = [];
+    if (harness && harness.prompt.length > 0) {
+        blocks.push({
+            source: "harness",
+            id: harness.id,
+            text: `You are running in ${harness.name}.\n${bullets(harness.prompt)}`,
+        });
+    }
+    if (model && model.prompt.length > 0) {
+        blocks.push({
+            source: "model",
+            id: model.id,
+            text: `You are ${model.name}.\n${bullets(model.prompt)}`,
+        });
+    }
+    const learnings = learningsFor(harness, model);
+    if (learnings.length > 0) {
+        blocks.push({
+            source: "learning",
+            id: learnings.map((learning) => learning.id).join(","),
+            text: bullets(learnings.map((learning) => learning.text)),
+        });
+    }
+    return blocks;
+}
+/**
+ * Compose harness, model, and profile guidance into the profile's prompt.
+ *
+ * The harness and model default to the profile's own `harness` and
+ * `model.default`; pass a selection to compose for an executor's override.
+ * Guidance goes into `appendSystemPrompt` where the harness owns an additive
+ * system-prompt control and into `instructions` otherwise, so a harness that
+ * refuses appended system text still receives it. The profile's own text
+ * stays last. Recomposing replaces earlier guidance, so the result is stable.
+ */
+export function withProfileKb(profile, selection = {}) {
+    const harness = selection.harness ?? profile.harness;
+    const model = selection.model ?? profile.model?.default;
+    const blocks = profileKbGuidance({ harness, model });
+    const channel = harnessSystemPromptIntents(findProfileKbHarness(harness)?.id ?? harness).append
+        ? "appendSystemPrompt"
+        : "instructions";
+    return composeAgentProfileGuidance(profile, blocks, channel);
+}

package/dist/profile-kb/models.d.ts

@@ -0,0 +1,9 @@
+import type { ProfileKbModel } from "./types.js";
+/**
+ * Current frontier models, from vendor sources read on 2026-09-22.
+ *
+ * `prompt` lines go into the model's prompt; `operator` lines configure the
+ * run. Vendor facts carry their source. Nothing here compares one model with
+ * another.
+ */
+export declare const profileKbModels: readonly ProfileKbModel[];

package/dist/profile-kb/models.js

@@ -0,0 +1,321 @@
+const CHECKED = "2026-09-22";
+const claudeDocs = "https://platform.claude.com/docs/en";
+/**
+ * Current frontier models, from vendor sources read on 2026-09-22.
+ *
+ * `prompt` lines go into the model's prompt; `operator` lines configure the
+ * run. Vendor facts carry their source. Nothing here compares one model with
+ * another.
+ */
+export const profileKbModels = [
+    {
+        id: "claude-opus-5-5",
+        name: "Claude Opus 5.5",
+        vendor: "Anthropic",
+        surfaces: ["api", "router"],
+        aliases: ["anthropic/claude-opus-5-5", "anthropic.claude-opus-5-5"],
+        defaultEffort: "medium",
+        sources: [
+            { url: `${claudeDocs}/models/opus-5-5/overview`, checkedAt: CHECKED },
+            {
+                url: `${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-opus-5-5`,
+                checkedAt: CHECKED,
+            },
+            {
+                url: "https://www.anthropic.com/claude-opus-5-5-system-card",
+                checkedAt: CHECKED,
+                note: "system card, linked from the model overview",
+            },
+        ],
+        prompt: [
+            "Keep the task's parts in a checklist you update, and keep working until every item is done or blocked.",
+            "Put status notes and recommendations in the same message as your next tool call; end the turn only when the work is complete or nothing can move without the user.",
+            "Before acting on a loosely specified task, explore the relevant files, records, and sources, including ones the task does not name, and use what you find.",
+            "When a lead agent can delegate, run independent slices in parallel subagents and pace the work to finish early.",
+            "For dense charts, diagrams, or screenshots, crop and zoom with the available image tools before reading values.",
+        ],
+        operator: [
+            "Model id claude-opus-5-5; 1M context, 128K max output; released 2026-09-22.",
+            "Adaptive thinking is always on. Start at effort medium, measure low for cost, and reserve xhigh and max for measured gains.",
+            "Set max_tokens to 128000 for long agentic turns: thinking counts toward it.",
+            "Keep history append-only and pass thinking blocks back unchanged; change instructions with mid-conversation system messages.",
+            "Set thinking display to updates to receive progress notes between tool calls.",
+            "For unattended loops, treat a text-only end of turn as a report: name the open items in a short user message, at most two or three times.",
+            "For multi-agent runs, append elapsed time against a budget (for example `elapsed 340s / 1200s`) to each message.",
+        ],
+    },
+    {
+        id: "claude-fable-5-1",
+        name: "Claude Fable 5.1",
+        vendor: "Anthropic",
+        surfaces: ["api", "router"],
+        aliases: ["anthropic/claude-fable-5-1", "anthropic.claude-fable-5-1"],
+        defaultEffort: "high",
+        sources: [
+            { url: `${claudeDocs}/models/fable-5-1/overview`, checkedAt: CHECKED },
+            {
+                url: `${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-fable-5-1`,
+                checkedAt: CHECKED,
+            },
+        ],
+        prompt: [
+            "You are operating autonomously: for reversible actions that follow from the request, proceed without asking; stop only for destructive actions or scope changes the user must decide.",
+            "Before ending your turn, check your last paragraph: if it is a plan, a list of next steps, or a promise, do that work now with tool calls.",
+            "The request sets the scope: deliver all of it, keep changes to what it needs, and report other findings as follow-ups.",
+            "First privately list what you need next; then request every item that does not depend on another's result in one response.",
+            "Say in a line what you are about to do, give brief updates while you work, and close with a recap that stands on its own.",
+            "Edit files surgically when a targeted edit gives the same result.",
+            "Write plainly: when a literal phrase is available, use it.",
+        ],
+        operator: [
+            "Model id claude-fable-5-1; 1M context, 128K max output; released 2026-09-01. For demanding reasoning and long-horizon agentic work.",
+            "Adaptive thinking only. Start at effort high and sweep low, medium, xhigh, and max against your evals.",
+            "Keep history append-only; send per-turn reminders as turn-scoped system messages (clear_at next_user_message).",
+            "Let the lead agent keep working while subagents run: return from the spawn tool immediately and deliver results in a later user message.",
+            "At xhigh and max, leave max_tokens room for thinking plus the deliverable.",
+        ],
+    },
+    {
+        id: "claude-sonnet-5",
+        name: "Claude Sonnet 5",
+        vendor: "Anthropic",
+        surfaces: ["api", "router"],
+        aliases: ["anthropic/claude-sonnet-5", "anthropic.claude-sonnet-5"],
+        defaultEffort: "high",
+        sources: [
+            { url: `${claudeDocs}/models/overview`, checkedAt: CHECKED },
+            {
+                url: `${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-sonnet-5`,
+                checkedAt: CHECKED,
+            },
+        ],
+        prompt: [
+            "Apply each instruction to every case it names; where an instruction should apply broadly, the prompt says so.",
+            "For review work, report every issue you find with a confidence and severity; a later step filters them.",
+            "Give regular, short progress updates through long agentic work.",
+        ],
+        operator: [
+            "Model id claude-sonnet-5; 1M context, 128K max output.",
+            "Adaptive thinking is on by default. Effort defaults to high; use xhigh for the hardest coding and agentic tasks.",
+            "Instructions are followed literally, especially at low effort: state scope explicitly.",
+            "Give the task, intent, and constraints up front in the first turn.",
+            "Temperature, top_p, and top_k stay at defaults; steer tone and variety in the prompt.",
+        ],
+    },
+    {
+        id: "claude-haiku-4-5",
+        name: "Claude Haiku 4.5",
+        vendor: "Anthropic",
+        surfaces: ["api", "router"],
+        aliases: [
+            "claude-haiku-4-5-20251001",
+            "anthropic/claude-haiku-4-5",
+            "anthropic.claude-haiku-4-5",
+        ],
+        sources: [
+            { url: `${claudeDocs}/models/haiku-4-5/overview`, checkedAt: CHECKED },
+        ],
+        prompt: [
+            "Answer directly and keep each step scoped to the task in hand.",
+        ],
+        operator: [
+            "Model id claude-haiku-4-5-20251001 (alias claude-haiku-4-5); 200K context, 64K max output. The fastest model in the current lineup.",
+            "Uses manual extended thinking (thinking.type enabled with budget_tokens); it takes no effort parameter.",
+            "Retirement not sooner than 2026-10-15.",
+        ],
+    },
+    {
+        id: "gpt-6-pro",
+        name: "GPT-6 Pro",
+        vendor: "OpenAI",
+        surfaces: ["chatgpt"],
+        aliases: ["GPT-6 Pro"],
+        sources: [
+            {
+                url: "https://help.openai.com/en/articles/20001354-gpt-56-and-gpt-6-pro-in-chatgpt",
+                checkedAt: CHECKED,
+                note: "read through search results; direct fetch returned HTTP 403",
+            },
+            { url: "https://learn.chatgpt.com/docs/prompting", checkedAt: CHECKED },
+        ],
+        prompt: [
+            "Start with the result you want, then give the goal, the context that helps, the output format, and what must stay unchanged.",
+            "Describe a process only when the process itself matters; otherwise leave room to search, compare, and adjust.",
+            "End with a final check: confirm each deliverable and flag anything you could not verify.",
+        ],
+        operator: [
+            "A ChatGPT model mode powered by GPT-6 Astra, on Pro, Business, and Enterprise plans. It has a weekly usage limit.",
+            "No API model id; reach it through ChatGPT (chatgpt-fleet).",
+        ],
+    },
+    {
+        id: "gpt-5.6-sol",
+        name: "GPT-5.6 Sol",
+        vendor: "OpenAI",
+        surfaces: ["codex", "api", "router"],
+        aliases: ["openai/gpt-5.6-sol"],
+        defaultEffort: "medium",
+        sources: [
+            {
+                url: "https://developers.openai.com/api/docs/models/gpt-5.6-sol",
+                checkedAt: CHECKED,
+            },
+            {
+                url: "https://openai.com/index/builders-guide-to-gpt-5-6/",
+                checkedAt: CHECKED,
+                note: "read through search results; direct fetch returned HTTP 403",
+            },
+            {
+                url: "file://~/.codex/models_cache.json",
+                checkedAt: CHECKED,
+                note: "codex-cli 0.152.1 served list; `codex exec -m gpt-5.6-sol` returned OK",
+            },
+        ],
+        prompt: [
+            "Work from the outcome: know what good looks like and the stopping condition, then choose the method yourself.",
+            "Carry the task to completion: gather context, plan, implement, verify, and report the evidence.",
+            "Run independent reads and checks in parallel.",
+        ],
+        operator: [
+            "Flagship GPT-5.6 tier for complex professional work: architecture, security review, repo-wide debugging.",
+            "Keep the system prompt lean: objective, context, hard constraints, approval boundaries, success criteria, required evidence, and output format.",
+            "Efforts: none, low, medium (API default), high, xhigh, max; Codex adds ultra, which runs parallel agents. Codex lists low as its default for this model.",
+            "1,050,000-token context, 128K max output.",
+        ],
+    },
+    {
+        id: "gpt-5.6-terra",
+        name: "GPT-5.6 Terra",
+        vendor: "OpenAI",
+        surfaces: ["codex", "api", "router"],
+        aliases: ["openai/gpt-5.6-terra"],
+        defaultEffort: "medium",
+        sources: [
+            {
+                url: "https://developers.openai.com/api/docs/models/gpt-5.6-terra",
+                checkedAt: CHECKED,
+            },
+            {
+                url: "file://~/.codex/models_cache.json",
+                checkedAt: CHECKED,
+                note: "codex-cli 0.152.1 served list; `codex exec -m gpt-5.6-terra` returned OK",
+            },
+        ],
+        prompt: [
+            "Work from the outcome and the stopping condition; choose the method yourself and verify before you report.",
+        ],
+        operator: [
+            "Balanced GPT-5.6 tier for everyday professional coding.",
+            "Efforts: none, low, medium (default), high, xhigh, max; Codex adds ultra.",
+            "1,050,000-token context, 128K max output.",
+        ],
+    },
+    {
+        id: "gpt-5.6-luna",
+        name: "GPT-5.6 Luna",
+        vendor: "OpenAI",
+        surfaces: ["codex", "api", "router"],
+        aliases: ["openai/gpt-5.6-luna"],
+        defaultEffort: "medium",
+        sources: [
+            {
+                url: "https://developers.openai.com/api/docs/models/gpt-5.6-luna",
+                checkedAt: CHECKED,
+            },
+            {
+                url: "file://~/.codex/models_cache.json",
+                checkedAt: CHECKED,
+                note: "codex-cli 0.152.1 served list; `codex exec -m gpt-5.6-luna` returned OK",
+            },
+        ],
+        prompt: [
+            "Follow the stated format exactly and finish each item before moving to the next.",
+        ],
+        operator: [
+            "GPT-5.6 tier for cost-sensitive, high-volume work: summarizing, labeling, extraction, scaffolds.",
+            "Efforts: none, low, medium (default), high, xhigh, max. Raise effort for harder items.",
+            "1,050,000-token context, 128K max output.",
+        ],
+    },
+    {
+        id: "deepseek-v4.1-flash",
+        name: "DeepSeek V4.1 Flash",
+        vendor: "DeepSeek",
+        surfaces: ["api", "router"],
+        aliases: ["deepseek-flash", "deepseek/deepseek-v4.1-flash"],
+        sources: [
+            {
+                url: "https://api-docs.deepseek.com/news/news260910/",
+                checkedAt: CHECKED,
+            },
+            {
+                url: "https://api-docs.deepseek.com/quick_start/pricing",
+                checkedAt: CHECKED,
+            },
+            {
+                url: "https://router.tangle.tools/v1/chat/completions",
+                checkedAt: CHECKED,
+                note: "deepseek/deepseek-v4.1-flash returned HTTP 200 and served that id",
+            },
+        ],
+        prompt: [
+            "State the goal and the finished result up front, and use the tools you are given to check your work.",
+        ],
+        operator: [
+            "Vendor API id deepseek-flash (released 2026-09-10); on the Tangle router, deepseek/deepseek-v4.1-flash.",
+            "1M context, 384K max output; thinking mode is the default and non-thinking is available. Native vision.",
+            "OpenCode supports it as an official partner harness.",
+        ],
+    },
+    {
+        id: "glm-5.3",
+        name: "GLM-5.3",
+        vendor: "Z.ai",
+        surfaces: ["api", "router"],
+        aliases: ["z-ai/glm-5.3", "zai-coding-plan/glm-5.3"],
+        defaultEffort: "ultracode",
+        sources: [
+            { url: "https://docs.z.ai/guides/llm/glm-5.3", checkedAt: CHECKED },
+            {
+                url: "https://router.tangle.tools/v1/chat/completions",
+                checkedAt: CHECKED,
+                note: "glm-5.3 returned HTTP 200, served as z-ai/glm-5.3",
+            },
+        ],
+        prompt: [
+            "Work the task through to a verified result, using the tools to run and check each change.",
+        ],
+        operator: [
+            "Model id glm-5.3; text only; 1M context, 128K max output. Built for long-horizon software engineering.",
+            "Reasoning is always on: thinking.type enabled with reasoning_effort low, high, or max (default). Use max for coding.",
+        ],
+    },
+    {
+        id: "kimi-k3",
+        name: "Kimi K3",
+        vendor: "Moonshot AI",
+        surfaces: ["api", "router"],
+        aliases: ["moonshotai/kimi-k3", "kimi-code/k3"],
+        defaultEffort: "ultracode",
+        sources: [
+            {
+                url: "https://platform.kimi.ai/docs/guide/kimi-k3-quickstart",
+                checkedAt: CHECKED,
+            },
+            {
+                url: "https://router.tangle.tools/v1/chat/completions",
+                checkedAt: CHECKED,
+                note: "kimi-k3 returned HTTP 200, served as moonshotai/kimi-k3",
+            },
+        ],
+        prompt: [
+            "Navigate the repository, run the code, and iterate against tests, logs, and runtime output until the result holds.",
+        ],
+        operator: [
+            "Model id kimi-k3; 1M context; native vision. For long-horizon coding, knowledge work, and reasoning.",
+            "Thinking is always on: reasoning_effort low, high, or max (default).",
+            "Sampling is fixed (temperature 1.0, top_p 0.95); omit sampling parameters.",
+            "Return the complete assistant message unchanged in multi-turn and tool-call histories.",
+        ],
+    },
+];

package/dist/profile-kb/records.d.ts

@@ -0,0 +1,12 @@
+import type { ProfileKbDiscrepancy, ProfileKbLearning } from "./types.js";
+/**
+ * Lessons this platform measured itself. A lesson enters only after an
+ * agent-eval check reproduced it strongly; none has met that bar yet, so the
+ * list is empty rather than filled with single-run observations.
+ */
+export declare const profileKbLearnings: readonly ProfileKbLearning[];
+/**
+ * Names the platform asked for that vendor sources state differently, as read
+ * on 2026-09-22. Recorded instead of guessed.
+ */
+export declare const profileKbDiscrepancies: readonly ProfileKbDiscrepancy[];

package/dist/profile-kb/records.js

@@ -0,0 +1,62 @@
+const CHECKED = "2026-09-22";
+/**
+ * Lessons this platform measured itself. A lesson enters only after an
+ * agent-eval check reproduced it strongly; none has met that bar yet, so the
+ * list is empty rather than filled with single-run observations.
+ */
+export const profileKbLearnings = [];
+/**
+ * Names the platform asked for that vendor sources state differently, as read
+ * on 2026-09-22. Recorded instead of guessed.
+ */
+export const profileKbDiscrepancies = [
+    {
+        subject: "OpenAI Codex models",
+        requested: "gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna as the current Codex models",
+        observed: "OpenAI's Codex model page lists GPT-6 Astra, GPT-6 Sol, and GPT-6 Luna as the current recommended models. " +
+            "On this box, codex-cli 0.152.1 on a ChatGPT account serves gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna (each returned OK) " +
+            "and labels them 'Older'; gpt-6-sol and gpt-6-luna return 'not supported when using Codex with a ChatGPT account', " +
+            "and gpt-6-astra returns 'requires a newer version of Codex'. The knowledge base keeps the gpt-5.6 tiers because they are what this box can run.",
+        sources: [
+            { url: "https://learn.chatgpt.com/docs/models", checkedAt: CHECKED },
+            {
+                url: "cli:codex exec -m <model> 'Reply with exactly: OK'",
+                checkedAt: CHECKED,
+            },
+        ],
+    },
+    {
+        subject: "DeepSeek V4.1 Pro",
+        requested: "DeepSeek V4.1 Pro",
+        observed: "DeepSeek has released V4.1 Flash only (2026-09-10). Its changelog says the V4 Pro API continues, its pricing page maps " +
+            "deepseek-v4-pro to DeepSeek-V4-Pro-0813, and its V4.1 Flash announcement says deepseek-v4-pro routes to V4.1 Flash from 2026-09-14. " +
+            "On the Tangle router, deepseek-v4-pro returned HTTP 503 (provider quota exhausted). No V4.1 Pro entry exists until DeepSeek ships it.",
+        sources: [
+            { url: "https://api-docs.deepseek.com/updates/", checkedAt: CHECKED },
+            { url: "https://api-docs.deepseek.com/quick_start/pricing", checkedAt: CHECKED },
+            { url: "https://api-docs.deepseek.com/news/news260910/", checkedAt: CHECKED },
+        ],
+    },
+    {
+        subject: "DeepSeek V4.1 Flash router id",
+        requested: "deepseek-flash (the vendor id)",
+        observed: "On the Tangle router, deepseek-flash returned HTTP 503 (provider_pricing_unavailable); deepseek/deepseek-v4.1-flash returned HTTP 200.",
+        sources: [
+            {
+                url: "https://router.tangle.tools/v1/chat/completions",
+                checkedAt: CHECKED,
+            },
+        ],
+    },
+    {
+        subject: "GPT-6 Pro",
+        requested: "GPT-6 Pro in ChatGPT",
+        observed: "OpenAI's help center names GPT-6 Pro as a ChatGPT mode powered by GPT-6 Astra; it has no API model id.",
+        sources: [
+            {
+                url: "https://help.openai.com/en/articles/20001354-gpt-56-and-gpt-6-pro-in-chatgpt",
+                checkedAt: CHECKED,
+            },
+        ],
+    },
+];

package/dist/profile-kb/types.d.ts

@@ -0,0 +1,76 @@
+import type { HarnessType } from "../harness.js";
+import type { ReasoningEffort } from "../agent-profile.js";
+/** A vendor or measured source, with the date someone read or ran it. */
+export interface ProfileKbSource {
+    url: string;
+    /** ISO date (YYYY-MM-DD) the source was read or the command was run. */
+    checkedAt: string;
+    /** What the source is, when the URL alone does not say. */
+    note?: string;
+}
+/**
+ * How to get the best from one harness.
+ *
+ * `prompt` lines are addressed to the agent running inside the harness and
+ * are composed into its profile. `operator` lines are for whoever launches
+ * the harness; they are never sent to a model.
+ */
+export interface ProfileKbHarness {
+    id: HarnessType;
+    name: string;
+    /** Installed version the guidance was checked against. */
+    version: string;
+    sources: ProfileKbSource[];
+    prompt: string[];
+    operator: string[];
+}
+/** Where a model is reached. A model id means different things on each surface. */
+export type ProfileKbSurface = "api" | "codex" | "chatgpt" | "router";
+/**
+ * How to get the best from one model.
+ *
+ * Vendor guidance only, each entry citing its source and date. The guidance is
+ * positive and specific to this model; it never ranks the model against
+ * another.
+ */
+export interface ProfileKbModel {
+    /** Canonical vendor id. */
+    id: string;
+    name: string;
+    vendor: string;
+    surfaces: ProfileKbSurface[];
+    /** Other spellings that resolve to this model: router ids, harness aliases. */
+    aliases: string[];
+    /** Vendor default reasoning effort, mapped onto the portable scale. */
+    defaultEffort?: ReasoningEffort;
+    sources: ProfileKbSource[];
+    prompt: string[];
+    operator: string[];
+}
+/**
+ * A lesson this platform learned itself. It enters the knowledge base only
+ * after an agent-eval check reproduced it, and it stays scoped to the
+ * harness or model it was measured on.
+ */
+export interface ProfileKbLearning {
+    id: string;
+    appliesTo: {
+        harness?: HarnessType;
+        model?: string;
+    };
+    text: string;
+    evidence: {
+        /** The agent-eval check that reproduced the lesson. */
+        check: string;
+        /** Independent reproductions that passed. */
+        reproductions: number;
+        source: ProfileKbSource;
+    };
+}
+/** A name the platform asked for that a vendor source does not confirm as stated. */
+export interface ProfileKbDiscrepancy {
+    subject: string;
+    requested: string;
+    observed: string;
+    sources: ProfileKbSource[];
+}

package/dist/profile-kb/types.js

@@ -0,0 +1 @@
+export {};

package/dist/profile-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type AgentProfile, type AgentProfileMcpServer } from "./agent-profile.js";
+import { type AgentProfile, type AgentProfileMetadata, type AgentTrainingTask, type AgentProfileMcpServer } from "./agent-profile.js";
 import type { AgentProfileDiff } from "./profile-diff.js";
 import { type SandboxSizePreset } from "./sandbox-size.js";
 export declare const agentProfilePermissionValueSchema: z.ZodEnum<{
@@ -326,6 +326,116 @@ export declare const agentProfileDiffRemovalSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     extensions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
+export declare const agentTrainingTaskSchema: z.ZodObject<{
+    benchmark: z.ZodString;
+    task: z.ZodString;
+    contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+/** The same order is used by dataset ingestion, receipt admission and holdout checks. */
+export declare function agentTrainingTaskKey(task: AgentTrainingTask): string;
+export declare const agentTrainingDatasetIdentitySchema: z.ZodObject<{
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    tasks: z.ZodArray<z.ZodObject<{
+        benchmark: z.ZodString;
+        task: z.ZodString;
+        contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const agentTrainingParametersSchema: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+export declare const agentTrainingReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    dataset: z.ZodObject<{
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        tasks: z.ZodArray<z.ZodObject<{
+            benchmark: z.ZodString;
+            task: z.ZodString;
+            contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    parentProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    parentReceiptDigest: z.ZodNullable<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+    executionRef: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    trainer: z.ZodObject<{
+        mode: z.ZodEnum<{
+            command: "command";
+            managed: "managed";
+        }>;
+        id: z.ZodString;
+        revision: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        parameters: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+    }, z.core.$strict>;
+    checkpoint: z.ZodObject<{
+        artifactDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        artifactBytes: z.ZodNumber;
+        routerModelId: z.ZodString;
+        servingDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const agentProfileTrainingSchema: z.ZodObject<{
+    receipt: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        dataset: z.ZodObject<{
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            tasks: z.ZodArray<z.ZodObject<{
+                benchmark: z.ZodString;
+                task: z.ZodString;
+                contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        parentProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        parentReceiptDigest: z.ZodNullable<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        executionRef: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        trainer: z.ZodObject<{
+            mode: z.ZodEnum<{
+                command: "command";
+                managed: "managed";
+            }>;
+            id: z.ZodString;
+            revision: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            parameters: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+        }, z.core.$strict>;
+        checkpoint: z.ZodObject<{
+            artifactDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            artifactBytes: z.ZodNumber;
+            routerModelId: z.ZodString;
+            servingDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    ancestors: z.ZodArray<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        dataset: z.ZodObject<{
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            tasks: z.ZodArray<z.ZodObject<{
+                benchmark: z.ZodString;
+                task: z.ZodString;
+                contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        parentProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        parentReceiptDigest: z.ZodNullable<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        executionRef: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        trainer: z.ZodObject<{
+            mode: z.ZodEnum<{
+                command: "command";
+                managed: "managed";
+            }>;
+            id: z.ZodString;
+            revision: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            parameters: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+        }, z.core.$strict>;
+        checkpoint: z.ZodObject<{
+            artifactDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            artifactBytes: z.ZodNumber;
+            routerModelId: z.ZodString;
+            servingDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const agentProfileMetadataSchema: z.ZodType<AgentProfileMetadata>;
 /**
  * The complete provider-neutral agent profile schema — the runtime validator for
  * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
@@ -523,7 +633,7 @@ export declare const agentProfileSchema: z.ZodObject<{
         sealed: z.ZodOptional<z.ZodBoolean>;
         attestationRefresh: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
-    metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+    metadata: z.ZodOptional<z.ZodType<AgentProfileMetadata, unknown, z.core.$ZodTypeInternals<AgentProfileMetadata, unknown>>>;
     extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
 }, z.core.$strict>;
 /**

package/dist/profile-schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { REASONING_EFFORTS, } from "./agent-profile.js";
-import { environmentNameSchema, headerNameSchema, isSafeExecutable, isSafeRelativePath, isWellFormedUnicode, looksLikeCredential, } from "./agent-candidate-schema-common.js";
+import { REASONING_EFFORTS, TRAINED_MODEL_PREFIX, trainedModelIdForArtifact, } from "./agent-profile.js";
+import { canonicalCandidateDigest, sha256DigestSchema, environmentNameSchema, headerNameSchema, isSafeExecutable, isSafeRelativePath, isWellFormedUnicode, looksLikeCredential, } from "./agent-candidate-schema-common.js";
 import { harnessTypeSchema } from "./harness.js";
 import { SANDBOX_SIZE_PRESET_NAMES, } from "./sandbox-size.js";
 /**
@@ -322,6 +322,88 @@ export const agentProfileDiffRemovalSchema = z.strictObject({
     metadata: removeListSchema.optional(),
     extensions: removeListSchema.optional(),
 });
+const trainingIdentitySchema = z.string().min(1).max(500).refine((value) => value.trim() === value && isWellFormedUnicode(value) &&
+    !controlCharacterPattern.test(value) && !looksLikeCredential(value), "training identity must be canonical public text");
+export const agentTrainingTaskSchema = z.strictObject({
+    benchmark: trainingIdentitySchema,
+    task: trainingIdentitySchema,
+    contentDigest: sha256DigestSchema,
+});
+/** The same order is used by dataset ingestion, receipt admission and holdout checks. */
+export function agentTrainingTaskKey(task) {
+    return JSON.stringify([task.benchmark, task.task, task.contentDigest]);
+}
+export const agentTrainingDatasetIdentitySchema = z.strictObject({
+    digest: sha256DigestSchema,
+    taskSetDigest: sha256DigestSchema,
+    tasks: z.array(agentTrainingTaskSchema).min(1).max(10_000),
+}).superRefine((dataset, context) => {
+    const keys = dataset.tasks.map(agentTrainingTaskKey);
+    if (keys.some((key, index) => index > 0 && key <= keys[index - 1])) {
+        context.addIssue({ code: "custom", path: ["tasks"], message: "training tasks must be sorted and unique" });
+    }
+    if (canonicalCandidateDigest(dataset.tasks) !== dataset.taskSetDigest) {
+        context.addIssue({ code: "custom", path: ["taskSetDigest"], message: "training task inventory digest mismatch" });
+    }
+});
+export const agentTrainingParametersSchema = ownPropertyRecordSchema(z.union([z.string().max(2_048).pipe(publicProfileConfigStringSchema), z.number().finite(), z.boolean(), z.null()])).superRefine((parameters, context) => {
+    if (Object.keys(parameters).length > 100) {
+        context.addIssue({ code: "custom", message: "at most 100 public training parameters are allowed" });
+    }
+    for (const name of Object.keys(parameters)) {
+        if (!trainingIdentitySchema.safeParse(name).success || isCredentialBearingProfileConfigName(name)) {
+            context.addIssue({ code: "custom", path: [name], message: "training parameter name must be public and non-credential" });
+        }
+    }
+});
+export const agentTrainingReceiptSchema = z.strictObject({
+    version: z.literal(1),
+    dataset: agentTrainingDatasetIdentitySchema,
+    parentProfileDigest: sha256DigestSchema,
+    parentReceiptDigest: sha256DigestSchema.nullable(),
+    executionRef: sha256DigestSchema,
+    trainer: z.strictObject({
+        mode: z.enum(["command", "managed"]),
+        id: trainingIdentitySchema,
+        revision: sha256DigestSchema,
+        parameters: agentTrainingParametersSchema,
+    }),
+    checkpoint: z.strictObject({
+        artifactDigest: sha256DigestSchema,
+        artifactBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+        routerModelId: trainingIdentitySchema,
+        servingDigest: sha256DigestSchema,
+    }),
+}).superRefine((receipt, context) => {
+    if (receipt.checkpoint.routerModelId !== trainedModelIdForArtifact(receipt.checkpoint.artifactDigest)) {
+        context.addIssue({ code: "custom", path: ["checkpoint", "routerModelId"], message: "trained Router model must be artifact-addressed" });
+    }
+});
+export const agentProfileTrainingSchema = z.strictObject({
+    receipt: agentTrainingReceiptSchema,
+    ancestors: z.array(agentTrainingReceiptSchema).max(8),
+}).superRefine((training, context) => {
+    const chain = [training.receipt, ...training.ancestors];
+    const digests = chain.map(canonicalCandidateDigest);
+    if (new Set(digests).size !== digests.length) {
+        context.addIssue({ code: "custom", message: "training receipt ancestry must not repeat" });
+    }
+    for (let index = 0; index < chain.length; index++) {
+        if (chain[index].parentReceiptDigest !== (digests[index + 1] ?? null)) {
+            context.addIssue({ code: "custom", message: "training receipt ancestry is incomplete or has been altered" });
+        }
+    }
+});
+export const agentProfileMetadataSchema = ownPropertyRecordSchema(z.unknown()).superRefine((metadata, context) => {
+    if (!Object.hasOwn(metadata, "training"))
+        return;
+    const result = agentProfileTrainingSchema.safeParse(metadata.training);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            context.addIssue({ code: "custom", path: ["training", ...issue.path], message: issue.message });
+        }
+    }
+});
 /**
  * The complete provider-neutral agent profile schema — the runtime validator for
  * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
@@ -345,11 +427,27 @@ export const agentProfileSchema = z
     hooks: ownPropertyRecordSchema(z.array(agentProfileHookCommandSchema)).optional(),
     modes: ownPropertyRecordSchema(agentProfileModeSchema).optional(),
     confidential: agentProfileConfidentialSchema.optional(),
-    metadata: ownPropertyRecordSchema(z.unknown()).optional(),
+    metadata: agentProfileMetadataSchema.optional(),
     extensions: ownPropertyRecordSchema(z.union([ownPropertyRecordSchema(z.unknown()), z.undefined()])).optional(),
 })
     .superRefine((profile, context) => {
     validateNestedRecordKeys(profile, context, [], new Set());
+    const training = agentProfileTrainingSchema.safeParse(profile.metadata?.training);
+    if (profile.model?.default?.startsWith(TRAINED_MODEL_PREFIX) && !training.success) {
+        context.addIssue({ code: "custom", path: ["metadata", "training"], message: "trained model requires a checkpoint receipt" });
+    }
+    const auxiliaryModels = [
+        profile.model?.small,
+        ...Object.values(profile.subagents ?? {}).map((agent) => agent.model),
+        ...Object.values(profile.modes ?? {}).map((mode) => mode.model),
+    ];
+    if (auxiliaryModels.some((model) => model?.startsWith(TRAINED_MODEL_PREFIX) &&
+        (!training.success || model !== training.data.receipt.checkpoint.routerModelId))) {
+        context.addIssue({ code: "custom", message: "trained auxiliary models require the same receipted checkpoint" });
+    }
+    if (training.success && profile.model?.default !== training.data.receipt.checkpoint.routerModelId) {
+        context.addIssue({ code: "custom", path: ["model", "default"], message: "trained profile model must equal the receipt's Router model" });
+    }
 });
 const encodedRecordKeyPattern = "^u(?:[0-9a-f]{4})*$";
 function isEncodedRecordKeyPropertyNames(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -66,6 +66,11 @@
       "import": "./dist/interaction.js",
       "types": "./dist/interaction.d.ts",
       "default": "./dist/interaction.js"
+    },
+    "./profile-kb": {
+      "import": "./dist/profile-kb/index.js",
+      "types": "./dist/profile-kb/index.d.ts",
+      "default": "./dist/profile-kb/index.js"
     }
   },
   "repository": {