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

package/dist/prime-fork.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Fork FACTS for prime-agent (PrimeIntellect-ai/prime-agent) — the constants,
+ * dialects and refusal reasons every executor that drives the fork needs, with
+ * no `node:fs` and no executor assumptions. The agent-dir MATERIALIZATION that
+ * consumes them lives in `./index.ts`; both consumers (cli-bridge's host-spawn
+ * backend on `--mode rpc`, sdk-provider-prime's in-sandbox adapter on
+ * `--mode acp`) read these instead of each keeping a private copy, because a
+ * fork bump must move one file, not two repositories.
+ *
+ * Every value here is verified against the pinned clone named by
+ * {@link PRIME_FORK_PIN}; `tests/prime-fork-pin.test.ts` re-asserts them
+ * against that clone when it is present, so a fork bump fails loudly in one
+ * place.
+ */
+/** The prime-agent clone every constant in this module was read from. */
+export declare const PRIME_FORK_PIN: {
+    readonly repo: "PrimeIntellect-ai/prime-agent";
+    readonly version: "0.7.0";
+    readonly commit: "be9e2fa0";
+    /** Local clone used by the fork-pin test when it exists. */
+    readonly clonePath: "/home/drew/bench-cache/prime-agent";
+    /** Package root inside the clone that the file:line citations are relative to. */
+    readonly packageRoot: "packages/coding-agent/src";
+};
+/**
+ * The fork's package identity, and why it cannot be installed from the npm
+ * registry.
+ *
+ * `@earendil-works/pi-coding-agent` on registry.npmjs.org serves the UPSTREAM
+ * pi line (0.84.x); the fork's 0.7.x versions were never published there. The
+ * two are wire-incompatible — different daemon schema revision, different
+ * config dir, different agent-dir env var (see
+ * {@link PRIME_AGENT_DIR_ENV_VARS}) — so `npm install -g` under that name
+ * yields an agent none of this lowering was verified against. The fork must be
+ * built from source and exposed under a `prime-agent` command name; its own
+ * `bin` entry is `pi` (fork package.json `bin`), which is exactly how the wrong
+ * binary ends up on `PATH` under the right-looking name.
+ */
+export declare const PRIME_FORK_INSTALL: {
+    readonly npmName: "@earendil-works/pi-coding-agent";
+    /** The fork's own bin name — deliberately NOT the command to install it as. */
+    readonly forkBinName: "pi";
+    /** Command name an executor's binary path is expected to resolve to. */
+    readonly expectedCommandName: "prime-agent";
+    readonly sourceRepo: "https://github.com/PrimeIntellect-ai/prime-agent";
+    /** Built entrypoint to expose as `prime-agent`. */
+    readonly sourceEntrypoint: "packages/coding-agent/dist/bundle/cli.js";
+    readonly reason: string;
+};
+/**
+ * Env vars the agent resolves its config dir from, most-specific first.
+ *
+ * The fork derives the name from its own package identity —
+ * `ENV_AGENT_DIR = \`${envPrefix}_CODING_AGENT_DIR\`` where `envPrefix` comes
+ * from `package.json` `piConfig.name` (config.ts:485-498) — so the fork reads
+ * `PRIME_AGENT_CODING_AGENT_DIR` and upstream pi reads `PI_CODING_AGENT_DIR`.
+ * An executor that sets only the fork's name has its isolation SILENTLY
+ * disabled when the binary on PATH turns out to be upstream pi: `getAgentDir()`
+ * falls back to `homedir()/<CONFIG_DIR_NAME>` (config.ts:520-527), one shared
+ * dir — and therefore one shared self-modifying `harness_state.json` — for
+ * every session on the box. Setting BOTH names costs nothing and keeps the
+ * isolation fail-closed under either binary.
+ */
+export declare const PRIME_AGENT_DIR_ENV_VARS: readonly ["PRIME_AGENT_CODING_AGENT_DIR", "PI_CODING_AGENT_DIR"];
+/** Canonical agent-dir env var for the fork itself (config.ts:498). */
+export declare const PRIME_AGENT_DIR_ENV_VAR: "PRIME_AGENT_CODING_AGENT_DIR";
+/** Pin `agentDir` under every name the agent could resolve its config dir from. */
+export declare function primeAgentDirEnv(agentDir: string): Record<string, string>;
+/**
+ * Operator knobs an executor forwards into the agent when they are set.
+ *
+ * `PRIME_AGENT_KERNEL_VENV` is load-bearing for any executor that also pins
+ * HOME: the kernel venv defaults under `homedir()/.prime/agent/kernel-venv`
+ * (kernel/bootstrap.ts:331-342), so a fresh HOME re-bootstraps it through uv on
+ * every run unless the operator's venv path is forwarded
+ * (bootstrap.ts:340 override, :358 branch).
+ */
+export declare const PRIME_KERNEL_ENV_PASSTHROUGH: readonly ["PRIME_AGENT_INSTALL_UV", "PRIME_AGENT_KERNEL_PYTHON", "PRIME_AGENT_KERNEL_VENV"];
+/**
+ * Env vars an executor must NEVER forward from its own environment.
+ *
+ * These re-point the self-modifying continual-harness store OUTSIDE the agent
+ * dir (agent-session.ts:8805 hands the kernel its store location), which
+ * defeats per-session isolation without changing anything an executor inspects.
+ * Isolation is the fail-closed default; sharing state is an explicit opt-in
+ * that names a directory, never an inherited env var.
+ */
+export declare const PRIME_HARNESS_STATE_ENV_DENYLIST: readonly ["RLM_GLOBAL_HARNESS_STATE_DIR", "RLM_HARNESS_STATE_DIR"];
+/**
+ * A prime-agent IPython kernel that dies is never re-provisioned headlessly —
+ * every later `ipython` call fails with one of these markers until the process
+ * is replaced. An executor that cannot recognize them either reports a generic
+ * turn failure or burns its whole timeout against a permanently dead tool.
+ *
+ * Verified in `core/kernel/index.ts`: :723 ("forked kernel exited
+ * unexpectedly"), :750 ("Kernel exited before resolving ports"), :779 ("Kernel
+ * exited during startup"), :820/:837/:1172/:1295 ("Kernel has been shut down").
+ */
+export declare const PRIME_KERNEL_DEAD_MARKERS: readonly string[];
+/** The first kernel-death marker present in `text`, or undefined. */
+export declare function matchPrimeKernelDeadMarker(text: string): string | undefined;
+/**
+ * `--thinking` rungs the fork's argument parser accepts
+ * (cli/args.ts:62 `VALID_THINKING_LEVELS`, rejected at :175). Read from the
+ * fork itself rather than borrowed from upstream pi's measured table: the two
+ * agreeing today is a coincidence this module must not depend on.
+ */
+export declare const PRIME_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type PrimeThinkingLevel = (typeof PRIME_THINKING_LEVELS)[number];
+/**
+ * Map the portable reasoning ladder onto the fork's `--thinking` value.
+ *
+ * Throws on an effort with no rung instead of returning undefined: omitting the
+ * flag runs the agent at its default thinking level while the caller believes
+ * the requested effort is in force, which is a silently dropped control.
+ */
+export declare function primeThinkingLevel(effort: string | null | undefined): PrimeThinkingLevel | undefined;
+/**
+ * Why `profile.mcp` (and any hub connection that resolves to MCP) is refused.
+ *
+ * The fork's `mcpServers` settings surface IS read at startup
+ * (settings-manager.ts:98-120,219) but a user-declared server never becomes
+ * model-visible: the host McpManager registers OAuth providers and serves
+ * mcp.config/refresh host-requests only (core/mcp/mcp-manager.ts:62-124),
+ * skips stdio servers entirely (mcp-manager.ts:73), and nothing generates a
+ * skill or prompt section for one. Model-visible MCP is exactly the built-in
+ * catalog skills, which are hand-written Python `McpIntegration` subclasses
+ * (prime-agent-runtime/src/rlm/mcp_base.py:112-125; only linear and notion
+ * ship). Materializing a per-run entry would run the agent WITHOUT the
+ * requested tools while the config on disk says otherwise.
+ */
+export declare const PRIME_MCP_UNSUPPORTED_REASON: string;
+/** Which half of a profile refusal this is: a fork limit, or a bad declaration. */
+export type PrimeProfileErrorKind = "unsupported" | "invalid";
+/**
+ * Refusal raised by the shared prime lowering, carrying the control and the
+ * reason separately so each executor can render them in its own error contract
+ * (an HTTP backend's typed `BackendError`, an SDK adapter's plain `Error`)
+ * without the reason text — which is where the fork evidence lives — being
+ * rewritten per repository.
+ */
+export declare class PrimeProfileError extends Error {
+    readonly kind: PrimeProfileErrorKind;
+    readonly control: string;
+    readonly reason: string;
+    constructor(kind: PrimeProfileErrorKind, control: string, reason: string);
+}
+/** Raise the "the fork cannot honor this control" half of the refusal. */
+export declare function rejectPrimeControl(control: string, reason: string): never;
+/** Raise the "this declaration is malformed" half of the refusal. */
+export declare function rejectPrimeDeclaration(control: string, reason: string): never;
+/**
+ * The fork's continual-harness store exists but no longer parses.
+ *
+ * The store is the agent's own self-modification state — refinements, learned
+ * prompts, subagents it created mid-session — so an executor that reseeds it
+ * from empty destroys evidence and silently mutates the thing under study. The
+ * turn is failed instead; the file is the operator's to repair or remove.
+ */
+export declare class PrimeHarnessStateError extends Error {
+    readonly statePath: string;
+    constructor(statePath: string, detail: string);
+}
+/**
+ * Strip `//` line comments and trailing commas, leaving string literals
+ * untouched — byte-for-byte the fork's own `stripJsonComments`
+ * (core/model-registry.ts), so a models.json the agent accepts is never refused
+ * by an executor and vice versa.
+ */
+export declare function stripPrimeJsonComments(input: string): string;
+/**
+ * Parse a models.json with the fork's own laxness and assert the one structural
+ * invariant it requires (a `providers` object). Throws naming `sourcePath`.
+ *
+ * This is the SHAPE and DIALECT only. Producing the file is deliberately not
+ * shared: an executor holding real operator credentials copies an
+ * operator-authored file and forwards only the env var names its `apiKey`
+ * entries reference, while an in-sandbox executor synthesizes a one-provider
+ * entry with a literal key that is a proxy dummy. Same schema, opposite threat
+ * models.
+ */
+export declare function parsePrimeModelsJson(text: string, sourcePath: string): Record<string, unknown>;
+/**
+ * Environment variables a models.json names as `apiKey` sources.
+ *
+ * prime resolves an `apiKey` value env-var first and LITERAL second
+ * (core/resolve-config-value.ts), so an executor that forwards exactly the
+ * named variables lets an operator keep secrets out of the file — and an
+ * executor that forwards NONE of them silently turns the variable name itself
+ * into the credential string.
+ */
+export declare function primeApiKeyEnvNames(modelsConfig: Record<string, unknown>): string[];

package/dist/prime-fork.js

@@ -0,0 +1,303 @@
+/**
+ * Fork FACTS for prime-agent (PrimeIntellect-ai/prime-agent) — the constants,
+ * dialects and refusal reasons every executor that drives the fork needs, with
+ * no `node:fs` and no executor assumptions. The agent-dir MATERIALIZATION that
+ * consumes them lives in `./index.ts`; both consumers (cli-bridge's host-spawn
+ * backend on `--mode rpc`, sdk-provider-prime's in-sandbox adapter on
+ * `--mode acp`) read these instead of each keeping a private copy, because a
+ * fork bump must move one file, not two repositories.
+ *
+ * Every value here is verified against the pinned clone named by
+ * {@link PRIME_FORK_PIN}; `tests/prime-fork-pin.test.ts` re-asserts them
+ * against that clone when it is present, so a fork bump fails loudly in one
+ * place.
+ */
+/** The prime-agent clone every constant in this module was read from. */
+export const PRIME_FORK_PIN = {
+    repo: "PrimeIntellect-ai/prime-agent",
+    version: "0.7.0",
+    commit: "be9e2fa0",
+    /** Local clone used by the fork-pin test when it exists. */
+    clonePath: "/home/drew/bench-cache/prime-agent",
+    /** Package root inside the clone that the file:line citations are relative to. */
+    packageRoot: "packages/coding-agent/src",
+};
+/**
+ * The fork's package identity, and why it cannot be installed from the npm
+ * registry.
+ *
+ * `@earendil-works/pi-coding-agent` on registry.npmjs.org serves the UPSTREAM
+ * pi line (0.84.x); the fork's 0.7.x versions were never published there. The
+ * two are wire-incompatible — different daemon schema revision, different
+ * config dir, different agent-dir env var (see
+ * {@link PRIME_AGENT_DIR_ENV_VARS}) — so `npm install -g` under that name
+ * yields an agent none of this lowering was verified against. The fork must be
+ * built from source and exposed under a `prime-agent` command name; its own
+ * `bin` entry is `pi` (fork package.json `bin`), which is exactly how the wrong
+ * binary ends up on `PATH` under the right-looking name.
+ */
+export const PRIME_FORK_INSTALL = {
+    npmName: "@earendil-works/pi-coding-agent",
+    /** The fork's own bin name — deliberately NOT the command to install it as. */
+    forkBinName: "pi",
+    /** Command name an executor's binary path is expected to resolve to. */
+    expectedCommandName: "prime-agent",
+    sourceRepo: "https://github.com/PrimeIntellect-ai/prime-agent",
+    /** Built entrypoint to expose as `prime-agent`. */
+    sourceEntrypoint: "packages/coding-agent/dist/bundle/cli.js",
+    reason: "registry.npmjs.org serves the upstream pi line under @earendil-works/pi-coding-agent " +
+        "(0.84.x); the prime-agent fork's 0.7.x versions do not exist there. Installing from " +
+        "the registry yields a wire-incompatible agent with a different daemon schema, a " +
+        "different config dir, and a different agent-dir env var. Build from source and expose " +
+        "packages/coding-agent/dist/bundle/cli.js as `prime-agent`.",
+};
+/**
+ * Env vars the agent resolves its config dir from, most-specific first.
+ *
+ * The fork derives the name from its own package identity —
+ * `ENV_AGENT_DIR = \`${envPrefix}_CODING_AGENT_DIR\`` where `envPrefix` comes
+ * from `package.json` `piConfig.name` (config.ts:485-498) — so the fork reads
+ * `PRIME_AGENT_CODING_AGENT_DIR` and upstream pi reads `PI_CODING_AGENT_DIR`.
+ * An executor that sets only the fork's name has its isolation SILENTLY
+ * disabled when the binary on PATH turns out to be upstream pi: `getAgentDir()`
+ * falls back to `homedir()/<CONFIG_DIR_NAME>` (config.ts:520-527), one shared
+ * dir — and therefore one shared self-modifying `harness_state.json` — for
+ * every session on the box. Setting BOTH names costs nothing and keeps the
+ * isolation fail-closed under either binary.
+ */
+export const PRIME_AGENT_DIR_ENV_VARS = [
+    "PRIME_AGENT_CODING_AGENT_DIR",
+    "PI_CODING_AGENT_DIR",
+];
+/** Canonical agent-dir env var for the fork itself (config.ts:498). */
+export const PRIME_AGENT_DIR_ENV_VAR = PRIME_AGENT_DIR_ENV_VARS[0];
+/** Pin `agentDir` under every name the agent could resolve its config dir from. */
+export function primeAgentDirEnv(agentDir) {
+    const env = {};
+    for (const name of PRIME_AGENT_DIR_ENV_VARS)
+        env[name] = agentDir;
+    return env;
+}
+/**
+ * Operator knobs an executor forwards into the agent when they are set.
+ *
+ * `PRIME_AGENT_KERNEL_VENV` is load-bearing for any executor that also pins
+ * HOME: the kernel venv defaults under `homedir()/.prime/agent/kernel-venv`
+ * (kernel/bootstrap.ts:331-342), so a fresh HOME re-bootstraps it through uv on
+ * every run unless the operator's venv path is forwarded
+ * (bootstrap.ts:340 override, :358 branch).
+ */
+export const PRIME_KERNEL_ENV_PASSTHROUGH = [
+    /** "1" lets a headless first run install uv itself; "0" forbids it. */
+    "PRIME_AGENT_INSTALL_UV",
+    /** Offline escape hatch: pin the kernel venv python instead of uv-provisioning. */
+    "PRIME_AGENT_KERNEL_PYTHON",
+    /** Reuse an operator-provisioned kernel venv instead of re-bootstrapping it. */
+    "PRIME_AGENT_KERNEL_VENV",
+];
+/**
+ * Env vars an executor must NEVER forward from its own environment.
+ *
+ * These re-point the self-modifying continual-harness store OUTSIDE the agent
+ * dir (agent-session.ts:8805 hands the kernel its store location), which
+ * defeats per-session isolation without changing anything an executor inspects.
+ * Isolation is the fail-closed default; sharing state is an explicit opt-in
+ * that names a directory, never an inherited env var.
+ */
+export const PRIME_HARNESS_STATE_ENV_DENYLIST = [
+    "RLM_GLOBAL_HARNESS_STATE_DIR",
+    "RLM_HARNESS_STATE_DIR",
+];
+/**
+ * A prime-agent IPython kernel that dies is never re-provisioned headlessly —
+ * every later `ipython` call fails with one of these markers until the process
+ * is replaced. An executor that cannot recognize them either reports a generic
+ * turn failure or burns its whole timeout against a permanently dead tool.
+ *
+ * Verified in `core/kernel/index.ts`: :723 ("forked kernel exited
+ * unexpectedly"), :750 ("Kernel exited before resolving ports"), :779 ("Kernel
+ * exited during startup"), :820/:837/:1172/:1295 ("Kernel has been shut down").
+ */
+export const PRIME_KERNEL_DEAD_MARKERS = [
+    "Kernel has been shut down",
+    "Kernel exited before resolving ports",
+    "Kernel exited during startup",
+    "forked kernel exited unexpectedly",
+];
+/** The first kernel-death marker present in `text`, or undefined. */
+export function matchPrimeKernelDeadMarker(text) {
+    return PRIME_KERNEL_DEAD_MARKERS.find((marker) => text.includes(marker));
+}
+/**
+ * `--thinking` rungs the fork's argument parser accepts
+ * (cli/args.ts:62 `VALID_THINKING_LEVELS`, rejected at :175). Read from the
+ * fork itself rather than borrowed from upstream pi's measured table: the two
+ * agreeing today is a coincidence this module must not depend on.
+ */
+export const PRIME_THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+/** Canonical portable effort → fork `--thinking` rung. */
+const PRIME_THINKING_BY_EFFORT = {
+    none: "off",
+    minimal: "minimal",
+    low: "low",
+    medium: "medium",
+    high: "high",
+    xhigh: "xhigh",
+    // The fork carries `max` above `xhigh`, so the ceiling level reaches it.
+    ultracode: "max",
+};
+/**
+ * Map the portable reasoning ladder onto the fork's `--thinking` value.
+ *
+ * Throws on an effort with no rung instead of returning undefined: omitting the
+ * flag runs the agent at its default thinking level while the caller believes
+ * the requested effort is in force, which is a silently dropped control.
+ */
+export function primeThinkingLevel(effort) {
+    if (effort === undefined || effort === null || effort === "")
+        return undefined;
+    const level = PRIME_THINKING_BY_EFFORT[effort];
+    if (level === undefined) {
+        throw new PrimeProfileError("invalid", "model.reasoningEffort", `prime-agent has no --thinking rung for ${JSON.stringify(effort)} ` +
+            `(fork cli/args.ts:62 accepts ${PRIME_THINKING_LEVELS.join(", ")}).`);
+    }
+    return level;
+}
+/**
+ * Why `profile.mcp` (and any hub connection that resolves to MCP) is refused.
+ *
+ * The fork's `mcpServers` settings surface IS read at startup
+ * (settings-manager.ts:98-120,219) but a user-declared server never becomes
+ * model-visible: the host McpManager registers OAuth providers and serves
+ * mcp.config/refresh host-requests only (core/mcp/mcp-manager.ts:62-124),
+ * skips stdio servers entirely (mcp-manager.ts:73), and nothing generates a
+ * skill or prompt section for one. Model-visible MCP is exactly the built-in
+ * catalog skills, which are hand-written Python `McpIntegration` subclasses
+ * (prime-agent-runtime/src/rlm/mcp_base.py:112-125; only linear and notion
+ * ship). Materializing a per-run entry would run the agent WITHOUT the
+ * requested tools while the config on disk says otherwise.
+ */
+export const PRIME_MCP_UNSUPPORTED_REASON = "a user-declared mcpServers entry is read from the fork's settings.json at startup but never " +
+    "becomes model-visible: the host only registers OAuth/config for it (fork core/mcp/" +
+    "mcp-manager.ts:62-124), skips stdio servers entirely (mcp-manager.ts:73), and generates no " +
+    "skill or prompt section for it. Model-visible MCP is exactly the built-in Python " +
+    "McpIntegration catalog skills (prime-agent-runtime/src/rlm/mcp_base.py:112-125), which no " +
+    "per-run configuration creates — so materializing it would be a silently dropped control.";
+/**
+ * Refusal raised by the shared prime lowering, carrying the control and the
+ * reason separately so each executor can render them in its own error contract
+ * (an HTTP backend's typed `BackendError`, an SDK adapter's plain `Error`)
+ * without the reason text — which is where the fork evidence lives — being
+ * rewritten per repository.
+ */
+export class PrimeProfileError extends Error {
+    kind;
+    control;
+    reason;
+    constructor(kind, control, reason) {
+        super(kind === "unsupported"
+            ? `prime does not support AgentProfile ${control}: ${reason}`
+            : `prime cannot accept AgentProfile ${control}: ${reason}`);
+        this.name = "PrimeProfileError";
+        this.kind = kind;
+        this.control = control;
+        this.reason = reason;
+    }
+}
+/** Raise the "the fork cannot honor this control" half of the refusal. */
+export function rejectPrimeControl(control, reason) {
+    throw new PrimeProfileError("unsupported", control, reason);
+}
+/** Raise the "this declaration is malformed" half of the refusal. */
+export function rejectPrimeDeclaration(control, reason) {
+    throw new PrimeProfileError("invalid", control, reason);
+}
+/**
+ * The fork's continual-harness store exists but no longer parses.
+ *
+ * The store is the agent's own self-modification state — refinements, learned
+ * prompts, subagents it created mid-session — so an executor that reseeds it
+ * from empty destroys evidence and silently mutates the thing under study. The
+ * turn is failed instead; the file is the operator's to repair or remove.
+ */
+export class PrimeHarnessStateError extends Error {
+    statePath;
+    constructor(statePath, detail) {
+        super(`prime harness state ${statePath} is not valid JSON and may hold agent self-modification ` +
+            `state; refusing to overwrite it — repair or remove the file to continue (${detail})`);
+        this.name = "PrimeHarnessStateError";
+        this.statePath = statePath;
+    }
+}
+/**
+ * Strip `//` line comments and trailing commas, leaving string literals
+ * untouched — byte-for-byte the fork's own `stripJsonComments`
+ * (core/model-registry.ts), so a models.json the agent accepts is never refused
+ * by an executor and vice versa.
+ */
+export function stripPrimeJsonComments(input) {
+    return input
+        .replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*/g, (m) => (m[0] === '"' ? m : ""))
+        .replace(/"(?:\\.|[^"\\])*"|,(\s*[}\]])/g, (m, tail) => tail !== undefined ? tail : m[0] === '"' ? m : "");
+}
+/**
+ * Parse a models.json with the fork's own laxness and assert the one structural
+ * invariant it requires (a `providers` object). Throws naming `sourcePath`.
+ *
+ * This is the SHAPE and DIALECT only. Producing the file is deliberately not
+ * shared: an executor holding real operator credentials copies an
+ * operator-authored file and forwards only the env var names its `apiKey`
+ * entries reference, while an in-sandbox executor synthesizes a one-provider
+ * entry with a literal key that is a proxy dummy. Same schema, opposite threat
+ * models.
+ */
+export function parsePrimeModelsJson(text, sourcePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripPrimeJsonComments(text));
+    }
+    catch (err) {
+        throw new Error(`prime models.json ${sourcePath} is not valid JSON: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`prime models.json ${sourcePath} must be a JSON object`);
+    }
+    const providers = parsed.providers;
+    if (!providers || typeof providers !== "object" || Array.isArray(providers)) {
+        throw new Error(`prime models.json ${sourcePath} must carry a "providers" object (prime's models.json schema)`);
+    }
+    return parsed;
+}
+/**
+ * Environment variables a models.json names as `apiKey` sources.
+ *
+ * prime resolves an `apiKey` value env-var first and LITERAL second
+ * (core/resolve-config-value.ts), so an executor that forwards exactly the
+ * named variables lets an operator keep secrets out of the file — and an
+ * executor that forwards NONE of them silently turns the variable name itself
+ * into the credential string.
+ */
+export function primeApiKeyEnvNames(modelsConfig) {
+    const names = [];
+    const providers = modelsConfig.providers;
+    if (!providers || typeof providers !== "object")
+        return names;
+    for (const provider of Object.values(providers)) {
+        if (!provider || typeof provider !== "object")
+            continue;
+        const key = provider.apiKey;
+        if (typeof key !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(key))
+            continue;
+        if (!names.includes(key))
+            names.push(key);
+    }
+    return names;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.11.0",
+  "version": "0.13.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",