@tangle-network/agent-profile-materialize 0.10.2 → 0.11.0

package/dist/index.d.ts

@@ -21,6 +21,7 @@
  * `node:fs` IO consumer. It was previously copied byte-for-byte into both
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
+export { modelIdsMatch, qualifyModelId } from "./model-id.js";
 import type { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileActivation, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, AgentProfile, AgentProfileConfigValue, AgentProfileMcpServer, AgentProfileSecretProvider, AgentProfileSecretRef, Sha256Digest } from "@tangle-network/agent-interface";
 export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecretProvider;
 /**
@@ -28,7 +29,7 @@ export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecr
  * the canonical harness enum, so a rename upstream is a compile error here rather than an
  * `isMaterializerHarness` that silently returns false for a harness that still exists.
  */
-export declare const MATERIALIZER_HARNESSES: readonly ["claude-code", "nanoclaw", "codex", "opencode", "kimi-code", "pi", "gemini", "hermes", "openclaw"];
+export declare const MATERIALIZER_HARNESSES: readonly ["claude-code", "nanoclaw", "codex", "opencode", "kimi-code", "pi", "prime", "gemini", "hermes", "openclaw"];
 export type HarnessId = (typeof MATERIALIZER_HARNESSES)[number];
 export declare function isMaterializerHarness(harness: string): harness is HarnessId;
 export interface PlanFile {
@@ -95,6 +96,22 @@ export interface Unsupported {
 export declare const SKIPPABLE_DIMENSIONS: readonly ["mcp", "extensions"];
 export type SkippableDimension = (typeof SKIPPABLE_DIMENSIONS)[number];
 export declare function isSkippableDimension(value: string): value is SkippableDimension;
+/**
+ * Launcher controls an executor can declare it OWNS via `materializeProfile`'s
+ * `binds` option.
+ *
+ * Some harness controls live outside any workspace: opencode's exact
+ * system-prompt replacement (`agent.<name>.prompt`) binds to the ONE agent
+ * whoever starts the process selects, which a plan-forwarding executor cannot
+ * guarantee — so the plan refuses the intent (harnessSystemPromptIntents in
+ * @tangle-network/agent-interface answers `replace: false` for opencode). An
+ * executor that really applies the plan's launch flags to the spawn it owns
+ * (selecting the generated primary agent via the plan's `--agent` flag) states
+ * so with `binds: ["systemPrompt"]`, which turns that refusal into the
+ * primary-agent lowering the executor must then apply.
+ */
+export declare const BINDABLE_LAUNCH_CONTROLS: readonly ["systemPrompt"];
+export type BindableLaunchControl = (typeof BINDABLE_LAUNCH_CONTROLS)[number];
 /** The plan a caller writes into the run cwd, then applies to the spawn. */
 export interface WorkspacePlan {
     harness: HarnessId;
@@ -106,6 +123,16 @@ export interface WorkspacePlan {
     flags: WorkspacePlanArgument[];
     /** Exact system-prompt replacement supplied to the harness. */
     systemPrompt?: string;
+    /**
+     * Additive system-prompt text: the harness's own prompt stays in force and
+     * this text is added after it. The OPPOSITE intent of {@link systemPrompt} on
+     * the same channel — an executor must never bind one to the other's control
+     * (an addition on the replacement flag deletes the prompt the caller asked to
+     * keep; a replacement on the additive flag leaves the harness's prompt
+     * running). Set only for harnesses whose own control executes the addition
+     * (harnessSystemPromptIntents in @tangle-network/agent-interface).
+     */
+    appendSystemPrompt?: string;
     /** Dimensions requested but with NO cwd path on this harness — fail-closed record. */
     unsupported: Unsupported[];
     /**
@@ -157,6 +184,7 @@ export interface WorkspacePlanReceipt {
     /** Public launch identity only; templates retain opaque secret references. */
     flags: WorkspacePlanArgument[];
     systemPrompt?: string;
+    appendSystemPrompt?: string;
     unsupported: Unsupported[];
     written: string[];
 }
@@ -165,6 +193,7 @@ export interface WorkspacePlanSpawnInputs {
     env: Record<string, string>;
     flags: string[];
     systemPrompt?: string;
+    appendSystemPrompt?: string;
 }
 /** Result of applying a public plan at the private executor boundary. */
 export interface WorkspacePlanApplication {
@@ -207,6 +236,7 @@ export interface AgentCandidateWorkspacePlan {
     env: Record<string, AgentCandidateConfigValue>;
     flags: AgentCandidateConfigValue[];
     systemPrompt?: AgentCandidateConfigValue;
+    appendSystemPrompt?: AgentCandidateConfigValue;
     unsupported: Unsupported[];
 }
 export interface AgentCandidateWorkspacePlanReceipt {
@@ -215,6 +245,7 @@ export interface AgentCandidateWorkspacePlanReceipt {
     env: Record<string, AgentCandidateConfigValue>;
     flags: AgentCandidateConfigValue[];
     systemPrompt?: AgentCandidateConfigValue;
+    appendSystemPrompt?: AgentCandidateConfigValue;
     unsupported: Unsupported[];
 }
 export interface MaterializeCandidateProfileOptions {
@@ -277,6 +308,8 @@ export declare function normalizeSkillMd(name: string, raw: string): string;
  */
 export declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
     skip?: SkippableDimension[];
+    /** Launcher controls the calling executor owns — see {@link BINDABLE_LAUNCH_CONTROLS}. */
+    binds?: readonly BindableLaunchControl[];
 }): WorkspacePlan;
 /**
  * Materialize a sealed candidate profile without weakening its process values.
@@ -339,3 +372,45 @@ export type OpenCodeMcpConfig = Record<string, {
 }>;
 /** Lower canonical MCP definitions to OpenCode's native startup configuration. */
 export declare function openCodeMcpConfig(mcp: Record<string, AgentProfileMcpServer>): OpenCodeMcpConfig;
+export interface PrimeProfileSkill {
+    name: string;
+    content: string;
+}
+export interface PrimeProfileSubagent {
+    name: string;
+    description?: string;
+    prompt?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Validated, materialization-ready view of the profile controls prime applies. */
+export interface PrimeProfileControls {
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    skills: PrimeProfileSkill[];
+    subagents: PrimeProfileSubagent[];
+}
+/**
+ * Validate and extract the profile controls the prime agent-dir lowering
+ * materializes. Throws on any control (or control facet) the fork has no
+ * verified read path for — partial acceptance would silently drop the rest.
+ */
+export declare function readPrimeProfileControls(profile: AgentProfile | undefined): PrimeProfileControls;
+/** Deterministic harness-state entry id for a profile subagent name. */
+export declare function primeSubagentEntryId(name: string): string;
+/**
+ * Materialize the validated controls into `agentDir` and return the extra
+ * spawn args that bind them. Runs before every spawn (same place models.json
+ * is materialized), so a continual agent dir is re-pinned to the current
+ * profile on each fresh prime process.
+ */
+export declare function materializePrimeProfileControls(agentDir: string, controls: PrimeProfileControls, warn: (msg: string, meta?: Record<string, unknown>) => void): string[];
+/**
+ * Upsert profile subagent specs into the fork's global continual-harness
+ * store and remove profile-sourced entries the current profile no longer
+ * declares. Agent-written entries (`source: "agent"`) are never touched.
+ *
+ * A pre-existing unparsable store degrades to empty exactly like the fork's
+ * own loader (refinement.ts:290-300 — "a corrupt state file must degrade to
+ * empty rather than throw"), with a warning so the reset is visible.
+ */
+export declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn: (msg: string, meta?: Record<string, unknown>) => void): void;

package/dist/index.js

@@ -21,8 +21,9 @@
  * `node:fs` IO consumer. It was previously copied byte-for-byte into both
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
+export { modelIdsMatch, qualifyModelId } from "./model-id.js";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
 import { agentCandidateProfileActivationSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, agentProfileSchema, agentProfileSecretRefSchema, canonicalCandidateBytes, canonicalCandidateDigest, resolveNativeWebTools, } from "@tangle-network/agent-interface";
 export const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER = Object.freeze({
@@ -71,6 +72,7 @@ export const MATERIALIZER_HARNESSES = [
     "opencode",
     "kimi-code",
     "pi",
+    "prime",
     "gemini",
     "hermes",
     "openclaw",
@@ -110,6 +112,33 @@ function assertSkippableDimensions(skip) {
     }
     return skip;
 }
+/**
+ * Launcher controls an executor can declare it OWNS via `materializeProfile`'s
+ * `binds` option.
+ *
+ * Some harness controls live outside any workspace: opencode's exact
+ * system-prompt replacement (`agent.<name>.prompt`) binds to the ONE agent
+ * whoever starts the process selects, which a plan-forwarding executor cannot
+ * guarantee — so the plan refuses the intent (harnessSystemPromptIntents in
+ * @tangle-network/agent-interface answers `replace: false` for opencode). An
+ * executor that really applies the plan's launch flags to the spawn it owns
+ * (selecting the generated primary agent via the plan's `--agent` flag) states
+ * so with `binds: ["systemPrompt"]`, which turns that refusal into the
+ * primary-agent lowering the executor must then apply.
+ */
+export const BINDABLE_LAUNCH_CONTROLS = ["systemPrompt"];
+const BINDABLE_LAUNCH_CONTROL_SET = new Set(BINDABLE_LAUNCH_CONTROLS);
+/** Reject a binding declaration this materializer has no lowering for, rather than ignoring it. */
+function assertBindableLaunchControls(binds) {
+    if (!binds)
+        return new Set();
+    const unknown = binds.filter((control) => !BINDABLE_LAUNCH_CONTROL_SET.has(control));
+    if (unknown.length > 0) {
+        throw new Error(`materializeProfile: cannot bind ${unknown.join(", ")}. ` +
+            `Bindable launch controls are: ${BINDABLE_LAUNCH_CONTROLS.join(", ")}.`);
+    }
+    return new Set(binds);
+}
 /** The plan was applied, but one or more private staging files remain. */
 export class WorkspacePlanCleanupError extends AggregateError {
     receipt;
@@ -183,6 +212,10 @@ const CONTEXT_FILE = {
     opencode: ".opencode/profile-instructions.md",
     "kimi-code": "AGENTS.md",
     pi: "AGENTS.md",
+    // prime (PrimeIntellect-ai/prime-agent v0.7.0, be9e2fa0) walks cwd and its
+    // ancestors for AGENTS.md/CLAUDE.md, cwd first (fork resource-loader.ts:59
+    // candidates, :94-109 walk from cwd inside loadProjectContextFiles).
+    prime: "AGENTS.md",
     gemini: "GEMINI.md", // current default; AGENTS.md only via .gemini/settings.json context.fileName
     hermes: "HERMES.md", // highest-priority native name; only ONE context loads (first match)
     openclaw: "AGENTS.md",
@@ -202,6 +235,12 @@ export const HARNESS_SKILL_DIRS = {
     opencode: ".opencode/skills",
     "kimi-code": ".kimi/skills",
     pi: ".pi/skills",
+    // prime auto-discovers project skills from <cwd>/<configDir>/skills where the
+    // fork ships configDir ".prime/agent" (fork package.json piConfig, config.ts:494;
+    // package-manager.ts:885 projectBaseDir, :2175-2180 projectDirs.skills,
+    // :2209-2213 collectAutoSkillEntries). The loader recurses into
+    // <name>/SKILL.md subdirs (skills.ts:328-372).
+    prime: ".prime/agent/skills",
     gemini: ".gemini/skills",
     hermes: null, // skills are ~/.hermes/skills (user) only — no cwd discovery
     openclaw: "skills", // <workspace>/skills/<name>/SKILL.md
@@ -226,11 +265,14 @@ const DEFAULT_FILE_MODE = 0o644;
 const PRIVATE_FILE_MODE = 0o600;
 const EXECUTABLE_FILE_MODE = 0o755;
 const DEFAULT_RESOURCE_FETCH_TIMEOUT_MS = 30_000;
+const OPENCODE_PRIMARY_AGENT_PREFIX = "tangle-profile-";
 const MAX_RESOURCE_BYTES = 10 * 1024 * 1024;
 const MAX_PROFILE_RESOURCE_BYTES = 32 * 1024 * 1024;
 const MAX_PROFILE_RESOURCE_REFS = 128;
 const MAX_CONCURRENT_RESOURCE_FETCHES = 8;
 const CLAUDE_SETTINGS_PATH = ".tangle/claude-settings.json";
+const CODEX_SYSTEM_PROMPT_PATH = ".codex/system-prompt.md";
+const OPENCODE_APPEND_SYSTEM_PROMPT_PATH = ".opencode/agent-system-prompt.md";
 const SAFE_WRITE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |
     fsConstants.O_EXCL |
@@ -575,6 +617,7 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
     const profile = agentProfileSchema.parse(inputProfile);
     const h = harness;
     const skip = new Set(assertSkippableDimensions(opts.skip));
+    const binds = assertBindableLaunchControls(opts.binds);
     const plan = {
         harness: h,
         files: [],
@@ -682,15 +725,60 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
             }
         }
     }
-    // 4) PROMPT. A system prompt is a replacement, while instructions are
-    // additive workspace context. Never lower one into the other.
+    // 4) PROMPT. A system prompt is a replacement, an appended system prompt is
+    // an addition on the SAME channel, and instructions are additive workspace
+    // context. Never lower one into another: substituting controls is a silent
+    // semantic change nothing in the run would reveal. Which harness owns which
+    // intent is the measured harnessSystemPromptIntents table in
+    // @tangle-network/agent-interface; the mechanics per owned cell live here.
+    //
+    // opencode registers every additive prompt file in ONE generated
+    // opencode.json `instructions` array (top-level JSON merge is last-wins per
+    // key, so two writers would clobber each other). Order is privilege order:
+    // the profile's explicit addition leads, project instructions follow.
+    const openCodeInstructionFiles = [];
     if (profile.prompt?.systemPrompt !== undefined) {
-        if (h === "claude-code" ||
-            h === "codex" ||
-            h === "opencode" ||
-            h === "pi") {
+        if (h === "opencode") {
+            const systemPrompt = profile.prompt.systemPrompt;
+            if (systemPrompt.trim().length === 0) {
+                throw new Error("opencode cannot express an empty exact system-prompt replacement");
+            }
+            if (!binds.has("systemPrompt")) {
+                // opencode's exact replacement (`agent.<name>.prompt`) binds to the one
+                // agent selected at launch, which a plan-forwarding executor cannot
+                // guarantee — its only system-prompt replacement is per-agent. An
+                // executor that selects the plan's generated primary agent declares
+                // binds: ["systemPrompt"].
+                unsupported("systemPrompt", "opencode: only system-prompt replacement is per-agent (`agent.<name>.prompt` " +
+                    "binds to the agent selected at launch, which a workspace plan cannot " +
+                    'guarantee); an executor that applies the plan\'s "--agent" flag to its own ' +
+                    'spawn declares binds: ["systemPrompt"]');
+            }
+            else {
+                const primaryAgentName = `${OPENCODE_PRIMARY_AGENT_PREFIX}${sha256(systemPrompt).slice(0, 16)}`;
+                const primaryAgentPath = `.opencode/agents/${primaryAgentName}.md`;
+                if (profile.subagents?.[primaryAgentName] !== undefined) {
+                    throw new Error(`opencode: subagent name "${primaryAgentName}" is reserved for the profile primary agent`);
+                }
+                plan.systemPrompt = systemPrompt;
+                add(primaryAgentPath, ["---", "mode: primary", "---", systemPrompt, ""].join("\n"));
+                plan.flags.push("--agent", primaryAgentName);
+            }
+        }
+        else if (h === "claude-code" || h === "pi" || h === "prime") {
+            // Launch-argument channel: claude-code/pi `--system-prompt`; prime
+            // inherits the same flag pair from its pi line (fork cli/args.ts:139-143
+            // → resourceLoaderOptions main.ts:745-746, replacement deletes the
+            // built-in prompt: resource-loader.ts:482-485, system-prompt.ts:72-73).
             plan.systemPrompt = profile.prompt.systemPrompt;
         }
+        else if (h === "codex") {
+            // codex's replacement is a config file, never a launch-argument string:
+            // `model_instructions_file` becomes the request's entire instructions
+            // text (measured against codex 0.146.0).
+            add(CODEX_SYSTEM_PROMPT_PATH, profile.prompt.systemPrompt);
+            plan.flags.push("-c", `model_instructions_file=${CODEX_SYSTEM_PROMPT_PATH}`);
+        }
         else if (h === "gemini") {
             add(".gemini/system.md", profile.prompt.systemPrompt);
             plan.env.GEMINI_SYSTEM_MD = "1";
@@ -699,6 +787,40 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
             unsupported("systemPrompt", `${h}: no verified exact system-prompt replacement control`);
         }
     }
+    if (profile.prompt?.appendSystemPrompt !== undefined) {
+        const appendSystemPrompt = profile.prompt.appendSystemPrompt;
+        if (appendSystemPrompt.trim().length === 0) {
+            throw new Error("prompt.appendSystemPrompt must be non-empty text");
+        }
+        if (h === "claude-code" || h === "pi" || h === "prime") {
+            // `--append-system-prompt` leaves the harness's own prompt in place and
+            // adds this text after it (claude-code/pi measured; prime fork
+            // cli/args.ts:139-143, addition appends after the built-in prompt:
+            // system-prompt.ts:61,109-110).
+            plan.appendSystemPrompt = appendSystemPrompt;
+        }
+        else if (h === "opencode") {
+            // opencode composes config-declared `instructions[]` files into the same
+            // single role:"system" message as its built-in prompt, which stays in
+            // place — a real additive channel, distinct from the instructions
+            // surface only by position (registered first, below).
+            add(OPENCODE_APPEND_SYSTEM_PROMPT_PATH, appendSystemPrompt.endsWith("\n")
+                ? appendSystemPrompt
+                : `${appendSystemPrompt}\n`);
+            openCodeInstructionFiles.push(OPENCODE_APPEND_SYSTEM_PROMPT_PATH);
+        }
+        else if (h === "codex") {
+            unsupported("systemPrompt", "codex: no verified additive system-prompt control — its AGENTS.md lands in a " +
+                "developer/user message, not the system channel");
+        }
+        else if (h === "gemini") {
+            unsupported("systemPrompt", "gemini: the only additive system-prompt channel is GEMINI.md memory, which IS " +
+                "the instructions surface — use prompt.instructions");
+        }
+        else {
+            unsupported("systemPrompt", `${h}: no verified additive system-prompt control`);
+        }
+    }
     const instr = [];
     if (profile.prompt?.instructions?.length)
         instr.push(...profile.prompt.instructions);
@@ -713,14 +835,16 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
     if (instr.length) {
         const instructionPath = CONTEXT_FILE[h];
         add(instructionPath, `${instr.join("\n\n")}\n`);
-        if (h === "opencode") {
-            add("opencode.json", serializeWorkspacePlanJson({
-                $schema: "https://opencode.ai/config.json",
-                instructions: [instructionPath],
-            }));
-        }
+        if (h === "opencode")
+            openCodeInstructionFiles.push(instructionPath);
         // gemini reads AGENTS.md only via settings; we write GEMINI.md so no extra step.
     }
+    if (openCodeInstructionFiles.length > 0) {
+        add("opencode.json", serializeWorkspacePlanJson({
+            $schema: "https://opencode.ai/config.json",
+            instructions: openCodeInstructionFiles,
+        }));
+    }
     // 5) ACTIVE EXECUTION CONTROLS. These alter the tools visible to the primary
     // process and its permission policy, so they must be lowered into native
     // launch/config inputs rather than merely retained in profile metadata.
@@ -836,6 +960,11 @@ export function materializeCandidateProfile(profile, harness, opts = {}) {
         ...(classicPlan.systemPrompt === undefined
             ? {}
             : { systemPrompt: candidatePublicValue(classicPlan.systemPrompt) }),
+        ...(classicPlan.appendSystemPrompt === undefined
+            ? {}
+            : {
+                appendSystemPrompt: candidatePublicValue(classicPlan.appendSystemPrompt),
+            }),
         unsupported: classicPlan.unsupported,
     };
 }
@@ -1229,6 +1358,9 @@ export function hashWorkspacePlan(plan) {
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: plan.systemPrompt }),
+        ...(plan.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: plan.appendSystemPrompt }),
         unsupported,
         ...(requires.length === 0 ? {} : { requires }),
     });
@@ -1249,6 +1381,9 @@ export function agentCandidateProfilePlanMaterial(plan) {
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: plan.systemPrompt }),
+        ...(plan.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: plan.appendSystemPrompt }),
         unsupported: [...plan.unsupported].sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`)),
     };
     return agentCandidateProfilePlanMaterialSchema.parse(material);
@@ -1311,6 +1446,11 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: candidatePublicString(plan.systemPrompt) }),
+        ...(plan.appendSystemPrompt === undefined
+            ? {}
+            : {
+                appendSystemPrompt: candidatePublicString(plan.appendSystemPrompt),
+            }),
         unsupported: plan.unsupported,
     }, workspaceDir);
     return {
@@ -1325,6 +1465,9 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: plan.systemPrompt }),
+        ...(plan.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: plan.appendSystemPrompt }),
         unsupported: [...plan.unsupported],
     };
 }
@@ -1412,6 +1555,9 @@ function resolvePublicWorkspacePlan(plan) {
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: plan.systemPrompt }),
+        ...(plan.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: plan.appendSystemPrompt }),
     };
 }
 async function resolvePrivateWorkspacePlan(plan, secretProvider) {
@@ -1480,6 +1626,9 @@ async function resolvePrivateWorkspacePlan(plan, secretProvider) {
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: plan.systemPrompt }),
+        ...(plan.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: plan.appendSystemPrompt }),
     };
 }
 function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorkspacePlan(plan)) {
@@ -1493,6 +1642,9 @@ function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorks
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: plan.systemPrompt }),
+        ...(plan.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: plan.appendSystemPrompt }),
         unsupported: plan.unsupported.map((entry) => ({ ...entry })),
         written: [...written],
     };
@@ -1613,6 +1765,9 @@ function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, opti
             ...(resolvedPlan.systemPrompt === undefined
                 ? {}
                 : { systemPrompt: resolvedPlan.systemPrompt }),
+            ...(resolvedPlan.appendSystemPrompt === undefined
+                ? {}
+                : { appendSystemPrompt: resolvedPlan.appendSystemPrompt }),
         },
         runtimeOnlyFiles: privateRuntimeFiles,
     };
@@ -2214,6 +2369,19 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
             });
             break;
         }
+        case "prime":
+            // The fork's MCP config surface (`mcpServers` in <agentDir>/settings.json,
+            // fork settings-manager.ts:98-120,219) IS read at startup, but a
+            // user-declared server never becomes model-visible: the host McpManager
+            // only registers OAuth providers and serves mcp.config/refresh
+            // host-requests (fork core/mcp/mcp-manager.ts:62-124,156-181), skips
+            // stdio servers entirely (mcp-manager.ts:73), and nothing generates a
+            // skill or prompt section for it — materializing profile.mcp would be a
+            // silently dropped control.
+            unsupported("mcp", "prime: settings.json mcpServers never becomes model-visible (fork mcp-manager.ts:62-124 " +
+                "registers OAuth providers only and skips stdio servers) — model-visible MCP is exactly " +
+                "the fork's built-in catalog skills");
+            break;
         case "hermes":
             unsupported("mcp", "hermes MCP is global config.yaml (mcp_servers), no cwd discovery — write to the hermes global config or pass a config flag");
             break;
@@ -2418,6 +2586,9 @@ function materializeHooks(h, hooks, add, unsupported, plan) {
         case "pi":
             unsupported("hooks", "pi hooks are TS extensions (.pi/extensions/*.ts) — build an extension");
             break;
+        case "prime":
+            unsupported("hooks", "prime hooks are TS extensions (fork core/extensions), not command hooks — build an extension");
+            break;
         case "hermes":
             unsupported("hooks", "hermes project plugins do not expose an exact command-hook mapping");
             break;
@@ -2678,6 +2849,16 @@ function materializeSubagent(h, name, sa, plan, add, unsupported) {
             registerCodexAgent(plan, name, relPath, sa.description ?? name);
             break;
         }
+        case "prime":
+            // Prime subagents ARE expressible — as entries in the continual-harness
+            // store at <agentDir>/harness/harness_state.json (fork refinement.ts:269-279,
+            // re-read on every system-prompt build: agent-session.ts:7548-7554) — but
+            // that store lives under the executor-owned agent dir, which no
+            // workspace-relative plan file can reach. Executors that own the agent
+            // dir seed it with seedPrimeProfileSubagents; the plan stays fail-closed
+            // so a plan-forwarding caller can never believe the roster is in force.
+            unsupported("subagents", `prime: subagents live in the agent-dir continual-harness store (<agentDir>/harness/harness_state.json), outside any workspace plan — seed "${name}" with seedPrimeProfileSubagents from the executor that owns the agent dir`);
+            break;
         default:
             unsupported("subagents", `${h}: subagents have no cwd file (config/flag/global only); "${name}" not mounted`);
     }
@@ -2721,6 +2902,12 @@ function materializeCommand(h, name, body, add, unsupported) {
         case "pi":
             add(`.pi/prompts/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
             break;
+        case "prime":
+            // Auto-discovered project prompt templates: <cwd>/.prime/agent/prompts
+            // (fork prompt-templates.ts:218 resolves CONFIG_DIR_NAME "prompts";
+            // package-manager.ts:2176-2180 auto-adds the same projectDirs.prompts).
+            add(`.prime/agent/prompts/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
+            break;
         case "kimi-code":
             unsupported("commands", "kimi commands ARE skills (/skill:<name>) — provide as a skill instead");
             break;
@@ -2731,3 +2918,347 @@ function materializeCommand(h, name, body, add, unsupported) {
             unsupported("commands", `${h}: no cwd command path`);
     }
 }
+// ─── Prime agent-dir lowering ────────────────────────────────────────────────
+//
+// Prime (PrimeIntellect-ai/prime-agent v0.7.0, be9e2fa0) reads several profile
+// dimensions from its AGENT DIR — a per-process config root the EXECUTOR owns
+// (env PRIME_AGENT_CODING_AGENT_DIR, fork config.ts:498,521-527), which no
+// workspace-relative plan file can reach. The helpers below are that lowering,
+// shared so cli-bridge's prime backend and sdk-provider-prime consume one
+// implementation instead of hand-rolling byte-divergent copies. Every control
+// accepted here is backed by a verified read path in the pinned fork; every
+// other control is rejected loudly so a caller can never believe a
+// behavior-relevant setting is in force when it is not. The verified paths:
+//
+// - `prompt.systemPrompt` / `prompt.appendSystemPrompt` → `--system-prompt` /
+//   `--append-system-prompt` (cli/args.ts:139-143). Both ride
+//   `AgentSessionRuntimeConfig` (main.ts:643-644) through BOTH acp spawn
+//   paths — the daemon-client create request (main.ts:1512-1520 →
+//   daemon-mode.ts:1310/1478) and the in-process fallback — into
+//   `resourceLoaderOptions` (main.ts:745-746), where the replacement DELETES
+//   the built-in prompt (resource-loader.ts:482-485, system-prompt.ts:72-73)
+//   and the addition appends after it (system-prompt.ts:61,109-110). Values
+//   are materialized as FILES under the agent dir because the flag value is
+//   read as a file when the path exists (resource-loader.ts:41-56), which
+//   keeps literal-vs-path resolution deterministic.
+//
+// - `resources.skills` (inline refs) → `--skill <agentDir>/profile/skills`
+//   (cli/args.ts:207-209 → main.ts:652 → agent-session-config.ts:67 →
+//   additionalSkillPaths, resource-loader.ts:437-442). The loader recurses
+//   into `<name>/SKILL.md` subdirs (skills.ts:328-372) and loaded skills are
+//   rendered into the system prompt (agent-session.ts:4272-4291,
+//   system-prompt.ts:87-89). The fork silently DROPS a SKILL.md without a
+//   frontmatter description (skills.ts:416-419), so content is normalized
+//   through {@link normalizeSkillMd}, which guarantees one.
+//
+// - `subagents` → `subagent` entries in the fork's continual-harness store at
+//   `<agentDir>/harness/harness_state.json` (refinement.ts:269-279). The
+//   store is re-read on every system-prompt build (agent-session.ts:4288,
+//   7548-7554) and subagent entries render as a task-shaped roster the model
+//   spawns via `await rlm('<task>')` (refinement.ts:483-496); the kernel
+//   reaches the same store through the host-set RLM_GLOBAL_HARNESS_STATE_DIR
+//   (agent-session.ts:8805).
+//
+// Kept REJECTED with the fork evidence:
+//
+// - `mcp`: the fork's MCP config surface (`mcpServers` in
+//   `<agentDir>/settings.json`, settings-manager.ts:98-120,219) IS read at
+//   startup, but a user-declared server never becomes model-visible: the host
+//   McpManager only registers OAuth providers and serves mcp.config/refresh
+//   host-requests (core/mcp/mcp-manager.ts:62-124,156-181), skips stdio
+//   servers entirely (mcp-manager.ts:73), and nothing generates a skill or
+//   prompt section for it — model-visible MCP is exactly the built-in
+//   linear/notion catalog skills (packages/coding-agent/skills/…). Wiring
+//   `profile.mcp` into settings.json would materialize config the model can
+//   never discover: a silently dropped control.
+//
+// - `prompt.instructions`: the fork's caller-instruction surface is the
+//   workspace AGENTS.md/CLAUDE.md context file (resource-loader.ts:58-66),
+//   i.e. caller workspace content this agent-dir lowering must not write
+//   into. (`materializeProfile(profile, "prime")` lowers instructions to the
+//   cwd AGENTS.md instead, which the fork walks from cwd:
+//   resource-loader.ts:94-109.)
+/** Skill name rules enforced by the fork's Agent Skills loader (skills.ts:122-147). */
+const PRIME_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PRIME_MAX_SKILL_NAME_LENGTH = 64;
+const PRIME_PROFILE_DIR_NAME = "profile";
+const PRIME_SKILLS_DIR_NAME = "skills";
+const PRIME_SYSTEM_PROMPT_FILE = "system-prompt.md";
+const PRIME_APPEND_SYSTEM_PROMPT_FILE = "append-system-prompt.md";
+/** Fork continual-harness store location under the agent dir (refinement.ts:269-279). */
+const PRIME_HARNESS_DIR_NAME = "harness";
+const PRIME_HARNESS_STATE_FILE = "harness_state.json";
+const PRIME_HARNESS_KINDS = ["prompt", "memory", "skill", "subagent"];
+/**
+ * Provenance marker for entries pinned from the profile. Stale removal keys on
+ * it, so agent-written (`source: "agent"`) and user-written entries are never
+ * touched.
+ */
+const PRIME_PROFILE_ENTRY_SOURCE = "profile";
+function rejectPrimeControl(control, reason) {
+    throw new Error(`prime does not support AgentProfile ${control}: ${reason}`);
+}
+/**
+ * Validate and extract the profile controls the prime agent-dir lowering
+ * materializes. Throws on any control (or control facet) the fork has no
+ * verified read path for — partial acceptance would silently drop the rest.
+ */
+export function readPrimeProfileControls(profile) {
+    const controls = { skills: [], subagents: [] };
+    if (!profile)
+        return controls;
+    if (profile.harness !== undefined && profile.harness !== "prime") {
+        throw new Error(`prime cannot run a profile pinned to harness "${profile.harness}" — ` +
+            'only "prime" (or an unset harness preference) is accepted.');
+    }
+    if (profile.prompt) {
+        const { systemPrompt, appendSystemPrompt, instructions } = profile.prompt;
+        const knownPromptFields = new Set([
+            "systemPrompt",
+            "appendSystemPrompt",
+            "instructions",
+        ]);
+        const unknown = Object.entries(profile.prompt)
+            .filter(([key, value]) => !knownPromptFields.has(key) && value !== undefined)
+            .map(([key]) => key);
+        if (unknown.length > 0) {
+            rejectPrimeControl(`prompt fields: ${unknown.join(", ")}`, "no verified prime-agent read path exists for them.");
+        }
+        if (instructions !== undefined) {
+            rejectPrimeControl("prompt.instructions", "prime-agent's caller-instruction surface is the workspace " +
+                "AGENTS.md context file (fork resource-loader.ts:58-66), which is " +
+                "caller workspace content this adapter must not write into. Use " +
+                "prompt.appendSystemPrompt instead.");
+        }
+        if (systemPrompt !== undefined) {
+            if (typeof systemPrompt !== "string" || systemPrompt.trim() === "") {
+                rejectPrimeControl("prompt.systemPrompt", "an empty replacement would delete the built-in system prompt and " +
+                    "install nothing.");
+            }
+            controls.systemPrompt = systemPrompt;
+        }
+        if (appendSystemPrompt !== undefined) {
+            if (typeof appendSystemPrompt !== "string" ||
+                appendSystemPrompt.trim() === "") {
+                rejectPrimeControl("prompt.appendSystemPrompt", "must be non-empty text.");
+            }
+            controls.appendSystemPrompt = appendSystemPrompt;
+        }
+    }
+    if (profile.resources) {
+        const { skills, failOnError, ...unsupported } = profile.resources;
+        const rejectedKeys = Object.entries(unsupported)
+            .filter(([, value]) => value !== undefined)
+            .map(([key]) => key);
+        if (rejectedKeys.length > 0) {
+            rejectPrimeControl(`resources: ${rejectedKeys.join(", ")}`, "only resources.skills has a verified prime-agent read path " +
+                "(--skill dirs, fork resource-loader.ts:437-442).");
+        }
+        if (failOnError === false) {
+            rejectPrimeControl("resources.failOnError: false", "this adapter always fails loud on a resource it cannot " +
+                "materialize; lenient materialization is not implemented.");
+        }
+        const seen = new Set();
+        for (const ref of skills ?? []) {
+            if (ref.kind !== "inline") {
+                rejectPrimeControl(`resources.skills ref "${"path" in ref ? ref.path : ""}"`, "only inline skill refs are accepted — resolve GitHub refs " +
+                    "(resolveAgentProfileResources) before handing the profile to " +
+                    "this adapter.");
+            }
+            const name = ref.name;
+            if (!PRIME_SKILL_NAME_RE.test(name) ||
+                name.length > PRIME_MAX_SKILL_NAME_LENGTH) {
+                rejectPrimeControl(`resources.skills name "${name}"`, "prime-agent skill names must be lowercase a-z0-9 with single " +
+                    `hyphens, at most ${PRIME_MAX_SKILL_NAME_LENGTH} chars (fork skills.ts:122-147).`);
+            }
+            if (seen.has(name)) {
+                rejectPrimeControl(`resources.skills name "${name}"`, "duplicate skill names collide in the fork's skill registry.");
+            }
+            seen.add(name);
+            if (ref.content.trim() === "") {
+                rejectPrimeControl(`resources.skills "${name}"`, "skill content is empty.");
+            }
+            controls.skills.push({ name, content: ref.content });
+        }
+    }
+    if (profile.subagents) {
+        const usedIds = new Map();
+        for (const [name, spec] of Object.entries(profile.subagents)) {
+            if (name.trim() === "") {
+                rejectPrimeControl("subagents", "a subagent name must be non-empty.");
+            }
+            const inexpressible = [
+                ["model", spec.model],
+                ["tools", spec.tools],
+                ["permissions", spec.permissions],
+                ["maxSteps", spec.maxSteps],
+            ]
+                .filter(([, value]) => value !== undefined)
+                .map(([key]) => key);
+            if (inexpressible.length > 0) {
+                rejectPrimeControl(`subagents["${name}"] fields: ${inexpressible.join(", ")}`, "a prime continual-harness subagent spec is prompt-roster " +
+                    "guidance for `await rlm('<task>')` (fork refinement.ts:483-496) " +
+                    "and pins no model, tool set, permission, or step budget on the " +
+                    "spawned child.");
+            }
+            if (!spec.description?.trim() && !spec.prompt?.trim()) {
+                rejectPrimeControl(`subagents["${name}"]`, "a spec needs a description and/or prompt — an empty entry gives " +
+                    "the model an empty roster line.");
+            }
+            const id = primeSubagentEntryId(name);
+            const clash = usedIds.get(id);
+            if (clash !== undefined) {
+                rejectPrimeControl(`subagents["${name}"]`, `its id "${id}" collides with subagent "${clash}".`);
+            }
+            usedIds.set(id, name);
+            controls.subagents.push({
+                name,
+                description: spec.description,
+                prompt: spec.prompt,
+                metadata: spec.metadata,
+            });
+        }
+    }
+    return controls;
+}
+/** Deterministic harness-state entry id for a profile subagent name. */
+export function primeSubagentEntryId(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `profile-${slug || "subagent"}`;
+}
+/**
+ * Materialize the validated controls into `agentDir` and return the extra
+ * spawn args that bind them. Runs before every spawn (same place models.json
+ * is materialized), so a continual agent dir is re-pinned to the current
+ * profile on each fresh prime process.
+ */
+export function materializePrimeProfileControls(agentDir, controls, warn) {
+    const args = [];
+    const profileDir = join(agentDir, PRIME_PROFILE_DIR_NAME);
+    if (controls.systemPrompt !== undefined) {
+        mkdirSync(profileDir, { recursive: true });
+        const promptPath = join(profileDir, PRIME_SYSTEM_PROMPT_FILE);
+        writeFileSync(promptPath, controls.systemPrompt, "utf8");
+        args.push("--system-prompt", promptPath);
+    }
+    if (controls.appendSystemPrompt !== undefined) {
+        mkdirSync(profileDir, { recursive: true });
+        const appendPath = join(profileDir, PRIME_APPEND_SYSTEM_PROMPT_FILE);
+        writeFileSync(appendPath, controls.appendSystemPrompt, "utf8");
+        args.push("--append-system-prompt", appendPath);
+    }
+    if (controls.skills.length > 0) {
+        const skillsRoot = join(profileDir, PRIME_SKILLS_DIR_NAME);
+        for (const skill of controls.skills) {
+            const skillDir = join(skillsRoot, skill.name);
+            mkdirSync(skillDir, { recursive: true });
+            writeFileSync(join(skillDir, "SKILL.md"), normalizeSkillMd(skill.name, skill.content), "utf8");
+        }
+        args.push("--skill", skillsRoot);
+    }
+    seedPrimeProfileSubagents(agentDir, controls.subagents, warn);
+    return args;
+}
+function emptyPrimeHarnessState() {
+    const entries = {};
+    for (const kind of PRIME_HARNESS_KINDS)
+        entries[kind] = {};
+    return { schema: 1, entries, refinements: [] };
+}
+/**
+ * Upsert profile subagent specs into the fork's global continual-harness
+ * store and remove profile-sourced entries the current profile no longer
+ * declares. Agent-written entries (`source: "agent"`) are never touched.
+ *
+ * A pre-existing unparsable store degrades to empty exactly like the fork's
+ * own loader (refinement.ts:290-300 — "a corrupt state file must degrade to
+ * empty rather than throw"), with a warning so the reset is visible.
+ */
+export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
+    const statePath = join(agentDir, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_STATE_FILE);
+    let state = emptyPrimeHarnessState();
+    if (existsSync(statePath)) {
+        try {
+            const raw = JSON.parse(readFileSync(statePath, "utf8"));
+            if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+                const parsed = raw;
+                state.schema =
+                    typeof parsed.schema === "number" ? parsed.schema : state.schema;
+                for (const kind of PRIME_HARNESS_KINDS) {
+                    const records = parsed.entries?.[kind];
+                    if (records && typeof records === "object") {
+                        state.entries[kind] = { ...records };
+                    }
+                }
+                if (Array.isArray(parsed.refinements)) {
+                    state.refinements = parsed.refinements;
+                }
+            }
+            else {
+                warn("prime: existing harness_state.json is not an object — reseeding", {
+                    statePath,
+                });
+            }
+        }
+        catch (err) {
+            warn("prime: existing harness_state.json is unparsable — reseeding", {
+                statePath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            state = emptyPrimeHarnessState();
+        }
+    }
+    else if (subagents.length === 0) {
+        // Nothing to pin and nothing stale to remove.
+        return;
+    }
+    const existing = state.entries.subagent ?? {};
+    const desiredIds = new Set(subagents.map((s) => primeSubagentEntryId(s.name)));
+    let changed = false;
+    for (const [id, entry] of Object.entries(existing)) {
+        if (entry?.source === PRIME_PROFILE_ENTRY_SOURCE && !desiredIds.has(id)) {
+            delete existing[id];
+            changed = true;
+        }
+    }
+    const now = new Date().toISOString();
+    for (const spec of subagents) {
+        const id = primeSubagentEntryId(spec.name);
+        const content = [spec.description?.trim(), spec.prompt?.trim()]
+            .filter((part) => !!part)
+            .join("\n\n");
+        const previous = existing[id];
+        if (previous &&
+            previous.source === PRIME_PROFILE_ENTRY_SOURCE &&
+            previous.title === spec.name &&
+            previous.content === content) {
+            continue;
+        }
+        existing[id] = {
+            id,
+            kind: "subagent",
+            title: spec.name,
+            content,
+            path: "profile",
+            scope: "global",
+            reference: {},
+            arguments: {},
+            metadata: spec.metadata ?? {},
+            source: PRIME_PROFILE_ENTRY_SOURCE,
+            created_at: previous?.created_at ?? now,
+            updated_at: now,
+            version: previous && typeof previous.version === "number"
+                ? previous.version + 1
+                : 1,
+        };
+        changed = true;
+    }
+    state.entries.subagent = existing;
+    if (!changed)
+        return;
+    mkdirSync(join(agentDir, PRIME_HARNESS_DIR_NAME), { recursive: true });
+    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}

package/dist/model-id.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The one canonicalization of a model id, shared by everything that writes a
+ * model id into an {@link AgentProfile} and everything that later compares one
+ * against it.
+ *
+ * A model id is qualified by prepending provider segments, and the same model
+ * is legitimately spelled at more than one qualification level as it travels:
+ * the caller sends `{ provider: "openai-compat", model: "deepseek/deepseek-v4-flash" }`,
+ * the profile records the qualified `openai-compat/deepseek/deepseek-v4-flash`,
+ * and the CLI is spawned with that qualified form. Two spellings, one model.
+ *
+ * Every writer and every reader must run both sides through here, so a
+ * comparison cannot mistake two spellings of one model for a conflict. Two
+ * independent copies of this rule are exactly how that bug arises.
+ */
+/**
+ * Qualify `modelId` with `provider` — the canonical form of a model id.
+ *
+ * The already-qualified check is prefix-SPECIFIC rather than "already contains
+ * a slash": a router slug legitimately carries an upstream segment of its own
+ * (`deepseek/deepseek-v4-flash`, `zai/glm-4.7`), so a generic slash test would
+ * leave those unqualified, while an unconditional prefix would double-qualify
+ * an id that has already been through here.
+ *
+ * Idempotent by construction:
+ * `qualifyModelId(p, qualifyModelId(p, m)) === qualifyModelId(p, m)`.
+ */
+export declare function qualifyModelId<T extends string | undefined>(provider: string | undefined, modelId: T): T;
+/**
+ * Do two model ids name the same model?
+ *
+ * Both operands are qualified by `provider` before comparison, so the
+ * qualification level a caller happened to use is not a difference. Two
+ * different model names are still different — this narrows a comparison to the
+ * model's identity, it does not make the comparison permissive.
+ *
+ * `provider` is optional because a profile may carry a `model.default` that was
+ * qualified by a writer which did not also record `model.provider`. With no
+ * provider to qualify by, a bare id and its single-segment-qualified spelling
+ * are still the same model, which is the only tolerance the undeclared case gets.
+ */
+export declare function modelIdsMatch(a: string | undefined, b: string | undefined, provider?: string): boolean;

package/dist/model-id.js

@@ -0,0 +1,59 @@
+/**
+ * The one canonicalization of a model id, shared by everything that writes a
+ * model id into an {@link AgentProfile} and everything that later compares one
+ * against it.
+ *
+ * A model id is qualified by prepending provider segments, and the same model
+ * is legitimately spelled at more than one qualification level as it travels:
+ * the caller sends `{ provider: "openai-compat", model: "deepseek/deepseek-v4-flash" }`,
+ * the profile records the qualified `openai-compat/deepseek/deepseek-v4-flash`,
+ * and the CLI is spawned with that qualified form. Two spellings, one model.
+ *
+ * Every writer and every reader must run both sides through here, so a
+ * comparison cannot mistake two spellings of one model for a conflict. Two
+ * independent copies of this rule are exactly how that bug arises.
+ */
+/**
+ * Qualify `modelId` with `provider` — the canonical form of a model id.
+ *
+ * The already-qualified check is prefix-SPECIFIC rather than "already contains
+ * a slash": a router slug legitimately carries an upstream segment of its own
+ * (`deepseek/deepseek-v4-flash`, `zai/glm-4.7`), so a generic slash test would
+ * leave those unqualified, while an unconditional prefix would double-qualify
+ * an id that has already been through here.
+ *
+ * Idempotent by construction:
+ * `qualifyModelId(p, qualifyModelId(p, m)) === qualifyModelId(p, m)`.
+ */
+export function qualifyModelId(provider, modelId) {
+    if (!provider || !modelId)
+        return modelId;
+    if (modelId === provider || modelId.startsWith(`${provider}/`))
+        return modelId;
+    return `${provider}/${modelId}`;
+}
+/**
+ * Do two model ids name the same model?
+ *
+ * Both operands are qualified by `provider` before comparison, so the
+ * qualification level a caller happened to use is not a difference. Two
+ * different model names are still different — this narrows a comparison to the
+ * model's identity, it does not make the comparison permissive.
+ *
+ * `provider` is optional because a profile may carry a `model.default` that was
+ * qualified by a writer which did not also record `model.provider`. With no
+ * provider to qualify by, a bare id and its single-segment-qualified spelling
+ * are still the same model, which is the only tolerance the undeclared case gets.
+ */
+export function modelIdsMatch(a, b, provider) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    if (qualifyModelId(provider, a) === qualifyModelId(provider, b))
+        return true;
+    if (provider)
+        return false;
+    return ((!a.includes("/") && b.endsWith(`/${a}`)) ||
+        (!b.includes("/") && a.endsWith(`/${b}`)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-dev-container, and VB).",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,13 +20,13 @@
     "dist"
   ],
   "devDependencies": {
-    "@tangle-network/agent-interface": "0.43.0",
+    "@tangle-network/agent-interface": "0.45.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@tangle-network/agent-interface": ">=0.38.0 <0.44.0"
+    "@tangle-network/agent-interface": ">=0.45.0 <0.46.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",