@tangle-network/agent-interface 2.10.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

@@ -519,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

@@ -173,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "2.10.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": {