@tangle-network/agent-interface 2.18.0 → 2.20.0

package/README.md

@@ -116,6 +116,7 @@ Providers that support recoverable workspace copies expose `workspaceBranching`
 Checkpoint and fork requests bind an idempotency key to a canonical request digest.
 Every returned resource repeats and validates that identity, lookups recover remote success after caller restart, changed-input key reuse returns a conflict, and cleanup binds its acknowledgement to the exact provider and target.
 A checkpoint with dependent forks returns `in_use` plus the blocking environment identifiers and remains recoverable until those forks are destroyed.
+A provider whose forks hold their own copy of the checkpoint deletes it without waiting for them.
 The older `checkpoint()` and `fork()` methods remain source-compatible for providers that have not yet implemented recovery semantics, but clients must not present them as durable workspace branching.
 
 `CreateAgentEnvironmentInput.idempotencyKey` makes generic environment creation one retry-safe operation.
@@ -194,9 +195,15 @@ 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.
+`@tangle-network/agent-interface/profile-kb` holds dated harness and model facts, conditional guidance, and reproduced platform learnings.
+Sources guide investigation; they do not prove that a technique improves this platform's behavior.
+
+Entries can expose optional `claims`, each with `text`, `basis` (`documented`, `vendor-guidance`, `local-observation`, or `hypothesis`), `audience` (`agent` or `operator`), and supporting `sources`.
+A source has a URL and check date, with optional `authority` (`primary`, `secondary`, or `local`) and `locator` for the supporting section or artifact.
+Authority describes the source, independently of the claim's basis.
+The maintained entries derive the legacy `prompt`, `operator`, and `sources` arrays from these claims; hypotheses stay inspectable but contribute no prompt or operator text.
+Only agent guidance enters the profile prompt. An empty `prompt` is legitimate when no supported instruction is needed; do not pad it with generic advice.
+Keep applicability conditions in the claim's text so composition preserves them.
 
 `withProfileKb(profile)` composes harness guidance, then model guidance, then the profile's own text into the profile's prompt:
 
@@ -217,7 +224,24 @@ The knowledge base owns the block sources `harness`, `model`, and `learning` (`P
 Give each layer its own source name and pass it as `replaceSources`: the composition then replaces only those sources and keeps every other block in place. Without `replaceSources`, it replaces every block.
 The block marker is reserved for composers: a hand-written `<profile-guidance source="model" ...>` block counts as a knowledge-base block and is replaced.
 
-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.
+The module also exports the data (`profileKbHarnesses`, `profileKbModels`), operator notes, platform learnings (admitted only after an agent-eval check reproduced them), and `profileKbDiscrepancies`, which preserves dated naming and availability checks.
+The source audit is retained in [Anthropic and OpenAI](src/profile-kb/research/anthropic-openai.md), [open harnesses and model APIs](src/profile-kb/research/open-harnesses.md), and the [distillation and consumer review](src/profile-kb/research/distillation-review.md).
+
+### Applicability and evidence
+
+Read vendor guidance within its documented, dated scope. Papers and social posts propose hypotheses to evaluate; they do not establish universal agent constraints. A measured conclusion applies to the configuration, tasks, environment, and evidence that supported it.
+
+Keep that scope with the existing evaluation record and link it from the learning's evidence source:
+
+- Requested model and observed served identity, provider route and adapter revision, harness and CLI version, and the authored and effective `AgentProfile` revisions or digests.
+- Reasoning settings, tool, MCP server and hook versions or definitions, permissions, and the loaded skill and instruction revisions. Distinguish declared configuration from observed delivery and use.
+- Task and acceptance-check revisions, environment and relevant resource limits, sampling and budget, measured outcome, errors and counterexamples, and source traces or artifacts.
+
+Unknown identity, usage, or cost stays unknown. A requested model name does not prove which model served the run; partial accounting supports a floor, not a complete total or zero spend.
+
+Before reusing a conclusion after a material change to any of these conditions, review its applicability against the retained evidence. State what still transfers and what needs a new check; use the existing registration and resource authorization for any experiment. Preserve the original record and append the changed scope or new evidence.
+
+The current [learning selector](src/profile-kb/index.ts) matches only harness and model; it does not validate the other conditions above. Keep narrower limits explicit in the learning text, or retain the finding in its evaluation record until it is suitable for composed guidance. The [learning records](src/profile-kb/records.ts) remain the single admission surface. Claim provenance does not automatically revalidate a run or authorize an experiment.
 
 ## Failed execution accounting
 

package/dist/harness-capabilities.d.ts

@@ -21,13 +21,76 @@ import type { HarnessType } from "./harness.js";
 export declare const reasoningLadder: readonly ReasoningEffort[];
 /** Provider prefix of a canonical model id (`anthropic/claude-…` → `anthropic`), or null. */
 export declare function modelProvider(modelId: string): string | null;
+/**
+ * The provider a model id belongs to: its explicit prefix, else the provider of its bare-id family
+ * (`claude-sonnet-5-5` → `anthropic`). `null` for an id outside every family, such as the `default`
+ * sentinel, whose provider only the serving harness knows.
+ */
+export declare function resolveModelProvider(modelId: string): string | null;
 /** The providers a harness is locked to, or `null` when it is router-backed (any model). */
 export declare function harnessProviders(harness: HarnessType): readonly string[] | null;
+/** A harness × model pair that a production run measured to fail at its first model call. */
+export interface HarnessModelExclusion {
+    readonly harness: HarnessType;
+    /** Canonical `provider/model` ids the measurement covers. */
+    readonly models: RegExp;
+    /**
+     * The failure needs a reasoning effort above `none`: the harness sends the rejected control only
+     * then, so the same pair without a reasoning effort is not excluded.
+     */
+    readonly onlyWithReasoningEffort: boolean;
+    /** What the provider rejected, and why the harness triggers it. */
+    readonly reason: string;
+    /** ISO date of the production measurement. */
+    readonly measuredOn: string;
+    /** Where the measurement is recorded. */
+    readonly evidence: string;
+}
+/**
+ * Pairs a router-backed harness cannot run, measured on production with the Router credential: one
+ * prompt per pair, profile reasoning effort `medium` (2026-10-05). The same run passed pi with
+ * `openai/gpt-5.5` and `zai/glm-5.3`, and opencode with every model listed here. Pairs not listed
+ * were not measured to fail. An entry is removed when its harness adapter or the Router is fixed and
+ * the pair passes a new production measurement.
+ *
+ * pi's chat-completions client (pi-ai 0.85.1) marks a model as reasoning only when the profile asks
+ * for a reasoning effort, and only a reasoning model is sent the `developer` role and
+ * `reasoning_effort`; that is why the first two entries need a reasoning effort.
+ */
+export declare const harnessModelExclusions: readonly HarnessModelExclusion[];
+/** The answer to "can this harness run this model", with the refusal a caller can show as-is. */
+export type HarnessModelSupport = {
+    readonly supported: true;
+    /** Canonical `provider/model` id when the provider resolved, else the id as given. */
+    readonly model: string;
+    readonly provider: string | null;
+} | {
+    readonly supported: false;
+    readonly model: string;
+    readonly provider: string | null;
+    /** The providers a vendor-locked harness accepts; absent for a measured exclusion. */
+    readonly allowedProviders?: readonly string[];
+    /** The measurement behind a refusal of a router-backed pair. */
+    readonly exclusion?: HarnessModelExclusion;
+    /** One sentence naming the harness, the model and the reason. */
+    readonly message: string;
+};
+export interface HarnessModelSupportOptions {
+    /** The run's reasoning effort; `null`, `undefined` and `none` all mean no reasoning effort. */
+    readonly reasoningEffort?: ReasoningEffort | null;
+}
+/**
+ * Whether a harness can run a model, and why not. A bare id resolves its provider through
+ * {@link resolveModelProvider}; an id whose provider cannot be resolved (a sentinel like `default`)
+ * is left to the harness, because its provider only the serving harness knows. A vendor-locked
+ * harness refuses every other provider; a router-backed harness refuses only the measured
+ * {@link harnessModelExclusions}.
+ */
+export declare function harnessModelSupport(harness: HarnessType, modelId: string, options?: HarnessModelSupportOptions): HarnessModelSupport;
 /**
- * Whether a harness can run a model. Router-backed harnesses (no provider lock) accept anything;
- * a model id with no provider prefix (a sentinel like `default`) is treated as compatible too.
+ * Whether a harness can run a model; {@link harnessModelSupport} gives the reason when it cannot.
  */
-export declare function harnessSupportsModel(harness: HarnessType, modelId: string): boolean;
+export declare function harnessSupportsModel(harness: HarnessType, modelId: string, options?: HarnessModelSupportOptions): boolean;
 /** The harness to adopt for a model whose provider is vendor-locked (`anthropic` → `claude-code`,
  *  `openai` → `codex`, `moonshot` → `kimi-code`); `null` when any router-backed harness will do. */
 export declare function preferredHarnessForModel(modelId: string): HarnessType | null;

package/dist/harness-capabilities.js

@@ -21,7 +21,8 @@ export const reasoningLadder = REASONING_EFFORTS;
 // ── Harness ↔ model compatibility ────────────────────────────────────────────
 /**
  * Provider prefixes a harness is vendor-locked to (canonical-id prefix, e.g. `anthropic`, `openai`).
- * A harness with no entry is router-backed: it runs any model.
+ * A harness with no entry is router-backed: it runs any model, except the measured exclusions in
+ * {@link harnessModelExclusions}.
  *
  * `nanoclaw` is deliberately absent despite the "claw" name: its runner routes every provider through
  * the Tangle router (canonical model id straight to the gateway), so it is router-backed like
@@ -37,25 +38,141 @@ export function modelProvider(modelId) {
     const slash = modelId.indexOf("/");
     return slash > 0 ? modelId.slice(0, slash) : null;
 }
+/**
+ * Model families whose bare ids belong to one provider. The Router catalog serves most ids without a
+ * prefix (`claude-sonnet-5-5`, `gpt-5.5`, `glm-5.3`) and names the provider beside them, so a check
+ * that read every bare id as "any provider" offered `claude-code` with `glm-5.3`.
+ */
+const bareModelFamilyProviders = [
+    [/^claude-/, "anthropic"],
+    [/^(gpt-|chatgpt-|codex-|o\d+(-|$))/, "openai"],
+    [/^(kimi-|moonshot-)/, "moonshot"],
+    [/^gemini-/, "google"],
+    [/^glm-/, "zai"],
+    [/^deepseek-/, "deepseek"],
+    [/^grok-/, "xai"],
+];
+/**
+ * The provider a model id belongs to: its explicit prefix, else the provider of its bare-id family
+ * (`claude-sonnet-5-5` → `anthropic`). `null` for an id outside every family, such as the `default`
+ * sentinel, whose provider only the serving harness knows.
+ */
+export function resolveModelProvider(modelId) {
+    const explicit = modelProvider(modelId);
+    if (explicit)
+        return explicit;
+    const id = modelId.trim().toLowerCase();
+    for (const [family, provider] of bareModelFamilyProviders) {
+        if (family.test(id))
+            return provider;
+    }
+    return null;
+}
 /** The providers a harness is locked to, or `null` when it is router-backed (any model). */
 export function harnessProviders(harness) {
     return harnessProviderLock[harness] ?? null;
 }
+const SANDBOX_HARNESS_MATRIX_EVIDENCE = "https://github.com/tangle-network/agent-dev-container/issues/9382";
+/**
+ * Pairs a router-backed harness cannot run, measured on production with the Router credential: one
+ * prompt per pair, profile reasoning effort `medium` (2026-10-05). The same run passed pi with
+ * `openai/gpt-5.5` and `zai/glm-5.3`, and opencode with every model listed here. Pairs not listed
+ * were not measured to fail. An entry is removed when its harness adapter or the Router is fixed and
+ * the pair passes a new production measurement.
+ *
+ * pi's chat-completions client (pi-ai 0.85.1) marks a model as reasoning only when the profile asks
+ * for a reasoning effort, and only a reasoning model is sent the `developer` role and
+ * `reasoning_effort`; that is why the first two entries need a reasoning effort.
+ */
+export const harnessModelExclusions = [
+    {
+        harness: "pi",
+        models: /^anthropic\//,
+        onlyWithReasoningEffort: true,
+        reason: 'the Router\'s chat-completions route for Anthropic models rejects the "developer" role pi sends ' +
+            'to a reasoning model (400 Unexpected role "developer")',
+        measuredOn: "2026-10-05",
+        evidence: SANDBOX_HARNESS_MATRIX_EVIDENCE,
+    },
+    {
+        harness: "pi",
+        models: /^openai\/gpt-5\.6-luna$/,
+        onlyWithReasoningEffort: true,
+        reason: "OpenAI does not accept function tools together with reasoning_effort for this model on " +
+            "/v1/chat/completions, the only route pi speaks",
+        measuredOn: "2026-10-05",
+        evidence: SANDBOX_HARNESS_MATRIX_EVIDENCE,
+    },
+    {
+        harness: "pi",
+        models: /^google\/gemini-3\.8-flash$/,
+        onlyWithReasoningEffort: false,
+        reason: "the model requires each function call to return its thought_signature, which pi's " +
+            "chat-completions client does not send back (400 Function call is missing a thought_signature)",
+        measuredOn: "2026-10-05",
+        evidence: SANDBOX_HARNESS_MATRIX_EVIDENCE,
+    },
+];
+/**
+ * Whether a harness can run a model, and why not. A bare id resolves its provider through
+ * {@link resolveModelProvider}; an id whose provider cannot be resolved (a sentinel like `default`)
+ * is left to the harness, because its provider only the serving harness knows. A vendor-locked
+ * harness refuses every other provider; a router-backed harness refuses only the measured
+ * {@link harnessModelExclusions}.
+ */
+export function harnessModelSupport(harness, modelId, options = {}) {
+    const trimmed = modelId.trim();
+    const provider = resolveModelProvider(trimmed);
+    const model = provider !== null && modelProvider(trimmed) === null
+        ? `${provider}/${trimmed}`
+        : trimmed;
+    if (provider === null)
+        return { supported: true, model, provider };
+    const allowedProviders = harnessProviders(harness);
+    if (allowedProviders && !allowedProviders.includes(provider)) {
+        return {
+            supported: false,
+            model,
+            provider,
+            allowedProviders,
+            message: `Harness ${harness} runs only ${allowedProviders.join(" or ")} models; ` +
+                `${model} is a ${provider} model. Choose a model whose id starts with ` +
+                `${allowedProviders.map((p) => `${p}/`).join(" or ")}, or a harness that runs ` +
+                `${provider} models, such as opencode.`,
+        };
+    }
+    const reasoning = options.reasoningEffort !== undefined &&
+        options.reasoningEffort !== null &&
+        options.reasoningEffort !== "none";
+    const exclusion = harnessModelExclusions.find((entry) => entry.harness === harness &&
+        entry.models.test(model) &&
+        (!entry.onlyWithReasoningEffort || reasoning));
+    if (exclusion) {
+        return {
+            supported: false,
+            model,
+            provider,
+            exclusion,
+            message: `Harness ${harness} cannot run ${model}` +
+                (exclusion.onlyWithReasoningEffort ? " with a reasoning effort" : "") +
+                `: ${exclusion.reason} (measured ${exclusion.measuredOn}, ${exclusion.evidence}). ` +
+                (exclusion.onlyWithReasoningEffort
+                    ? "Remove model.reasoningEffort, or choose another harness or model."
+                    : "Choose another harness or model."),
+        };
+    }
+    return { supported: true, model, provider };
+}
 /**
- * Whether a harness can run a model. Router-backed harnesses (no provider lock) accept anything;
- * a model id with no provider prefix (a sentinel like `default`) is treated as compatible too.
+ * Whether a harness can run a model; {@link harnessModelSupport} gives the reason when it cannot.
  */
-export function harnessSupportsModel(harness, modelId) {
-    const providers = harnessProviders(harness);
-    if (!providers)
-        return true;
-    const provider = modelProvider(modelId);
-    return provider === null || providers.includes(provider);
+export function harnessSupportsModel(harness, modelId, options) {
+    return harnessModelSupport(harness, modelId, options).supported;
 }
 /** The harness to adopt for a model whose provider is vendor-locked (`anthropic` → `claude-code`,
  *  `openai` → `codex`, `moonshot` → `kimi-code`); `null` when any router-backed harness will do. */
 export function preferredHarnessForModel(modelId) {
-    const provider = modelProvider(modelId);
+    const provider = resolveModelProvider(modelId);
     if (!provider)
         return null;
     for (const [harness, providers] of Object.entries(harnessProviderLock)) {

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

@@ -0,0 +1,12 @@
+import type { ProfileKbClaim, ProfileKbSource, ProfileKbSurface } from "./types.js";
+export declare function claim(text: string, source: ProfileKbSource, basis?: ProfileKbClaim["basis"], audience?: ProfileKbClaim["audience"]): ProfileKbClaim;
+/** Keep public string arrays and entry citations derived from the same claim records. */
+export declare function kbEntry<const T extends {
+    claims: ProfileKbClaim[];
+    surfaces?: ProfileKbSurface[];
+    aliases?: string[];
+}>(entry: T): T & {
+    sources: ProfileKbSource[];
+    prompt: string[];
+    operator: string[];
+};

package/dist/profile-kb/entry.js

@@ -0,0 +1,20 @@
+export function claim(text, source, basis = "documented", audience = "operator") {
+    return { text, basis, audience, sources: [source] };
+}
+/** Keep public string arrays and entry citations derived from the same claim records. */
+export function kbEntry(entry) {
+    const sources = new Map();
+    for (const claim of entry.claims) {
+        for (const source of claim.sources)
+            sources.set(JSON.stringify(source), source);
+    }
+    const textFor = (audience) => entry.claims
+        .filter((claim) => claim.audience === audience && claim.basis !== "hypothesis")
+        .map((claim) => claim.text);
+    return {
+        ...entry,
+        sources: [...sources.values()],
+        prompt: textFor("agent"),
+        operator: textFor("operator"),
+    };
+}

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

@@ -1,9 +1,3 @@
 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.
- */
+/** Source-qualified launch knowledge; versions describe checked sources, not every host's installation. */
 export declare const profileKbHarnesses: readonly ProfileKbHarness[];

package/dist/profile-kb/harnesses.js

@@ -1,123 +1,84 @@
-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.
- */
+import { claim, kbEntry } from "./entry.js";
+const CHECKED = "2026-10-04";
+const source = (url, locator) => ({
+    url,
+    locator,
+    checkedAt: CHECKED,
+    authority: "primary",
+});
+const claudeCli = source("https://code.claude.com/docs/en/cli-reference", "CLI flags: --print, --bg, --bare, system prompt flags");
+const claudeAgents = source("https://code.claude.com/docs/en/sub-agents", "How subagents work; forked subagents");
+const codexConfig = source("https://learn.chatgpt.com/docs/config-file/config-reference", "model_instructions_file; model_reasoning_effort");
+const codexAgents = source("https://learn.chatgpt.com/docs/agent-configuration/subagents", "Availability; approvals and sandbox controls");
+const codexCommands = source("https://learn.chatgpt.com/docs/developer-commands", "Set or view a task goal with /goal");
+const piBase = "https://github.com/earendil-works/pi/blob/200387122ca450d6387f033949423114a270b96c/packages/coding-agent/";
+const piCli = source(`${piBase}docs/cli.md`, "Invocation and output; models; prompts and process");
+const piRpc = source(`${piBase}docs/rpc.md#run-lifecycle`, "Run lifecycle");
+const piCommands = source(`${piBase}docs/rpc-commands.md`, "steer; follow_up; get_available_thinking_levels");
+const opencodeCli = source("https://opencode.ai/docs/cli/", "run; serve; acp");
+const opencodePrompt = source("https://github.com/anomalyco/opencode/blob/907b3bc518fa48e90e8ec24dd327d13eee71c36c/packages/opencode/src/session/llm/request.ts#L51-L70", "LLMRequestPrep.prepare");
+const kimiCli = source("https://moonshotai.github.io/kimi-code/en/reference/kimi-command.html", "Flag conflict rules; non-interactive execution");
+const kimiConfig = source("https://moonshotai.github.io/kimi-code/en/configuration/config-files.html", "Config file location; thinking; complete example");
+/** Source-qualified launch knowledge; versions describe checked sources, not every host's installation. */
 export const profileKbHarnesses = [
-    {
+    kbEntry({
         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.",
+        version: "2.1.289",
+        claims: [
+            claim("For a non-forked subagent, supply the context needed for its task; forked subagents inherit the parent conversation.", claudeAgents, "documented", "agent"),
+            claim("Headless: claude -p <prompt> --model <id> --effort <level> --output-format stream-json --verbose. --bg is a separate background-session mode and cannot combine with -p.", claudeCli),
+            claim("--append-system-prompt adds to the default; --system-prompt replaces it. On resume, prompt changes may wait for compaction.", claudeCli),
+            claim("--bare skips automatic discovery; explicitly supplied context can still load. It is not an established speed improvement for this workload.", claudeCli),
+            claim("--max-budget-usd caps the print invocation's spend, excluding restored prior spend; --json-schema constrains output structure, not correctness.", claudeCli),
         ],
-        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.",
-        ],
-    },
-    {
+    }),
+    kbEntry({
         id: "codex",
         name: "Codex CLI",
-        version: "0.156.1",
-        sources: [
-            { url: "https://learn.chatgpt.com/docs/models", checkedAt: CHECKED },
-            {
-                url: "cli:codex exec --help; codex features list",
+        version: "0.160.0",
+        claims: [
+            claim("Observed on the Mac: codex exec <prompt> -m <model> -c model_reasoning_effort=<level> --json -o <file>; --output-schema, review, resume and fork are available.", {
+                url: "cli:codex --version; codex exec --help",
                 checkedAt: CHECKED,
-                note: "0.156.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.",
+                authority: "local",
+                locator: "Codex 0.160.0, Mac; research/anthropic-openai.md#local-codex-catalog-evidence",
+            }, "local-observation"),
+            claim("model_instructions_file replaces model instructions. Reasoning support is model/client-specific; a requested effort does not establish the effective effort.", codexConfig),
+            claim("Current local Codex spawns subagents after a direct request or applicable project/skill instruction. Enabled features do not establish tool exposure in another integration.", codexAgents),
+            claim("/goal tracks an interactive objective; it does not establish recovery across host or process restarts.", codexCommands),
         ],
-        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.",
-        ],
-    },
-    {
+    }),
+    kbEntry({
         id: "opencode",
         name: "OpenCode",
-        version: "1.18.32",
-        sources: [
-            { url: "https://opencode.ai/docs/cli/", checkedAt: CHECKED },
-            { url: "cli:opencode run --help", checkedAt: CHECKED, note: "1.18.32" },
-        ],
-        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.",
+        version: "1.18.34",
+        claims: [
+            claim("Headless: opencode run <message> -m <provider/model> --agent <name> --variant <variant> --format json. Variants are provider-specific.", opencodeCli),
+            claim("A configured agent.prompt replaces the provider prompt before system/user additions; plugins can transform it further. Do not assume the provider prompt is retained.", opencodePrompt),
+            claim("serve exposes an HTTP API, run --attach reuses that server, and acp exposes an IDE protocol; these capabilities do not establish a particular parent adapter's support.", opencodeCli),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "pi",
         name: "Pi",
-        version: "0.87.1",
-        sources: [
-            {
-                url: "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md",
-                checkedAt: CHECKED,
-            },
-            {
-                url: "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md",
-                checkedAt: CHECKED,
-            },
-            { url: "cli:pi --help", checkedAt: CHECKED, note: "0.87.1" },
-        ],
-        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.",
+        version: "1.0.2",
+        claims: [
+            claim("Headless: pi -p <prompt> --model <provider/id[:thinking]> --mode json. Model arguments can fuzzy-match; inspect the selected identity. --thinking clamps to model capability.", piCli),
+            claim("--system-prompt replaces the default; --append-system-prompt adds to it. JSON mode exits after supplied prompts; RPC stays alive on stdin/stdout.", piCli),
+            claim("In Pi 1.0.2 RPC, prompt acceptance and agent_end do not prove settlement: wait for agent_settled, except a handled prompt that began no run.", piRpc),
+            claim("RPC steering arrives after current tool calls, before the next model call; follow-ups wait for tool calls and steering to drain. Query get_available_thinking_levels for the selected model.", piCommands),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "kimi-code",
         name: "Kimi Code CLI",
-        version: "2.0.2",
-        sources: [
-            { url: "https://moonshotai.github.io/kimi-code/", checkedAt: CHECKED },
-            {
-                url: "cli:kimi --help; ~/.kimi-code/config.toml",
-                checkedAt: CHECKED,
-                note: "2.0.2",
-            },
-        ],
-        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.",
+        version: "2.1.1",
+        claims: [
+            claim("Headless: kimi -p <prompt> -m <configured-alias> --output-format stream-json. Print mode already uses auto policy with static deny rules; it rejects --auto, --yolo and --plan.", kimiCli),
+            claim("--agent-file selects a new session's custom agent and cannot combine with resume/continue.", kimiCli),
+            claim("kimi-code/k3 is a configured coding-provider alias, not Moonshot's public API ID kimi-k3. Configuration lives under KIMI_CODE_HOME or ~/.kimi-code.", kimiConfig),
+            claim("[thinking].effort is model-dependent; unsupported settings fall back to the model default. The documented K3 configuration supports low, high and max.", kimiConfig),
         ],
-    },
+    }),
 ];

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

@@ -20,8 +20,8 @@ export { composeAgentProfileGuidance, profileKbDiscrepancies, profileKbHarnesses
  * replaces blocks from these sources and keeps blocks any other layer added.
  */
 export declare const PROFILE_KB_SOURCES: readonly ["harness", "model", "learning"];
-/** Date the knowledge base was last checked against its sources. */
-export declare const PROFILE_KB_CHECKED_AT = "2026-09-22";
+/** Date of the latest source audit; individual historical observations retain their own dates. */
+export declare const PROFILE_KB_CHECKED_AT = "2026-10-04";
 /** Find a harness entry by its {@link HarnessType}. */
 export declare function findProfileKbHarness(harness: HarnessType | string | undefined): ProfileKbHarness | undefined;
 /**

package/dist/profile-kb/index.js

@@ -18,8 +18,8 @@ export { composeAgentProfileGuidance, profileKbDiscrepancies, profileKbHarnesses
  * replaces blocks from these sources and keeps blocks any other layer added.
  */
 export const PROFILE_KB_SOURCES = ["harness", "model", "learning"];
-/** Date the knowledge base was last checked against its sources. */
-export const PROFILE_KB_CHECKED_AT = "2026-09-22";
+/** Date of the latest source audit; individual historical observations retain their own dates. */
+export const PROFILE_KB_CHECKED_AT = "2026-10-04";
 /** Find a harness entry by its {@link HarnessType}. */
 export function findProfileKbHarness(harness) {
     if (!harness)
@@ -118,14 +118,14 @@ export function profileKbGuidance(selection) {
         blocks.push({
             source: "harness",
             id: harness.id,
-            text: `You are running in ${harness.name}.\n${bullets(harness.prompt)}`,
+            text: `Harness guidance: ${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)}`,
+            text: `Model guidance: ${model.name}.\n${bullets(model.prompt)}`,
         });
     }
     const learnings = learningsFor(harness, model);

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

@@ -1,9 +1,3 @@
 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.
- */
+/** Source-backed facts and conditional advice. API controls never become agent instructions. */
 export declare const profileKbModels: readonly ProfileKbModel[];