@tangle-network/agent-profile-materialize 0.15.2 → 0.17.0

package/dist/mcp.d.ts

@@ -0,0 +1,22 @@
+export declare function materializeMcp(h: HarnessId, mcp: Record<string, ActiveAgentProfileMcpServer>, plan: WorkspacePlan, add: AddPlanFile, unsupported: (d: Unsupported["dimension"], r: string) => void): void;
+/** OpenCode-native MCP configuration used by workspace and startup paths. */
+export type OpenCodeMcpConfig = Record<string, {
+    type: "remote";
+    url: string;
+    enabled: boolean;
+    headers?: Record<string, AgentProfileConfigValue>;
+} | {
+    type: "local";
+    command: Array<string | AgentProfileConfigValue>;
+    enabled: boolean;
+    environment?: Record<string, AgentProfileConfigValue>;
+}>;
+/** Lower canonical MCP definitions to OpenCode's native startup configuration. */
+export declare function openCodeMcpConfig(mcp: Record<string, AgentProfileMcpServer>): OpenCodeMcpConfig;
+import type { AgentProfileConfigValue, AgentProfileMcpServer } from "@tangle-network/agent-interface";
+import type { AddPlanFile } from "./plan-json.js";
+import type { HarnessId, Unsupported, WorkspacePlan } from "./plan-types.js";
+type ActiveAgentProfileMcpServer = Exclude<AgentProfileMcpServer, {
+    enabled: false;
+}>;
+export {};

package/dist/mcp.js

@@ -0,0 +1,244 @@
+export function materializeMcp(h, mcp, plan, add, unsupported) {
+    switch (h) {
+        case "claude-code": {
+            const servers = {};
+            for (const [name, server] of Object.entries(mcp)) {
+                if (server.url) {
+                    servers[name] = {
+                        type: server.transport ?? "http",
+                        url: server.url,
+                        ...(server.headers ? { headers: server.headers } : {}),
+                    };
+                    continue;
+                }
+                if (server.cwd !== undefined) {
+                    unsupported("mcp", `${h}: local MCP server "${name}" does not support a cwd field`);
+                }
+                servers[name] = {
+                    type: "stdio",
+                    command: server.command,
+                    ...(server.args ? { args: server.args } : {}),
+                    ...(server.env ? { env: server.env } : {}),
+                };
+            }
+            const relPath = ".tangle/claude-mcp.json";
+            add(relPath, serializeWorkspacePlanJson({ mcpServers: servers }));
+            plan.flags.push("--mcp-config", relPath, "--strict-mcp-config");
+            break;
+        }
+        case "nanoclaw":
+            unsupported("mcp", "nanoclaw MCP must be injected through options.mcpServers by its SDK adapter");
+            break;
+        case "codex": {
+            const servers = [];
+            for (const [name, server] of Object.entries(mcp).sort(([left], [right]) => compareStrings(left, right))) {
+                if (server.url && server.transport === "sse") {
+                    unsupported("mcp", `codex: remote MCP server "${name}" uses unsupported SSE transport`);
+                    continue;
+                }
+                servers.push(concatWorkspacePlanArguments(`${tomlStr(name)} = `, codexMcpServerToml(name, server, plan)));
+            }
+            if (servers.length > 0) {
+                // Runtime overrides do not require persisted project trust. Header values
+                // ride environment variables so credentials never appear in argv.
+                plan.flags.push("-c", concatWorkspacePlanArguments("mcp_servers={ ", joinWorkspacePlanArguments(servers, ", "), " }"));
+            }
+            break;
+        }
+        case "opencode":
+            // opencode.json "mcp" block (local|remote).
+            add("opencode.json", serializeWorkspacePlanJson({
+                $schema: "https://opencode.ai/config.json",
+                mcp: openCodeMcpConfig(mcp),
+            }));
+            break;
+        case "gemini": {
+            const servers = {};
+            for (const [name, server] of Object.entries(mcp)) {
+                if (server.url) {
+                    servers[name] = {
+                        [server.transport === "sse" ? "url" : "httpUrl"]: server.url,
+                        ...(server.headers ? { headers: server.headers } : {}),
+                    };
+                    continue;
+                }
+                servers[name] = {
+                    command: server.command,
+                    ...(server.args ? { args: server.args } : {}),
+                    ...(server.env ? { env: server.env } : {}),
+                    ...(server.cwd ? { cwd: server.cwd } : {}),
+                };
+            }
+            add(".gemini/settings.json", serializeWorkspacePlanJson({ mcpServers: servers }));
+            break;
+        }
+        case "kimi-code": {
+            // NO cwd auto-discovery — kimi needs an explicit --mcp-config-file FLAG.
+            const rel = ".kimi/mcp.json";
+            const servers = Object.fromEntries(Object.entries(mcp).map(([name, server]) => [
+                name,
+                kimiMcpServer(server),
+            ]));
+            add(rel, serializeWorkspacePlanJson({ mcpServers: servers }));
+            plan.flags.push("--mcp-config-file", rel);
+            break;
+        }
+        case "pi": {
+            // pi ships NO MCP. It arrives from the `pi-mcp-adapter` extension, which discovers
+            // `<cwd>/.pi/mcp.json` (adapter 2.17.0 config.ts:17) and also registers a `--mcp-config`
+            // flag (index.ts:252). The flag is registered BY the extension, so passing it when the
+            // extension is absent is not a fallback — it is an unknown flag.
+            //
+            // This was previously marked unsupported because a workspace file cannot install an
+            // extension. That reasoning was right about the constraint and wrong about the conclusion:
+            // the file half is perfectly materializable, and the half that is not becomes a declared
+            // requirement the executor enforces. Marking the whole dimension unsupported pushed both
+            // halves onto every consumer, and two of them independently rebuilt it.
+            const rel = ".pi/mcp.json";
+            const servers = Object.fromEntries(Object.entries(mcp).map(([name, server]) => [
+                name,
+                // `directTools` promotes this server's verbs to first-class pi tools. Without it the
+                // agent gets one generic `mcp` tool and must connect, then describe, then call — three
+                // round trips of discovery before it can do anything. Per-server, because the adapter
+                // lets a per-server value override the global `settings.directTools` (direct-tools.ts:135).
+                { ...piMcpServer(server), directTools: true },
+            ]));
+            // serializeWorkspacePlanJson, NOT JSON.stringify: it unwraps public config values to their
+            // bytes and lifts any secret-ref into a tracked slot the applier resolves. Stringifying
+            // straight would write `{"kind":"public","value":"..."}` into the file as an argv entry.
+            add(rel, serializeWorkspacePlanJson({ mcpServers: servers }));
+            plan.requires?.push({
+                kind: "harness-extension",
+                dimension: "mcp",
+                id: "npm:pi-mcp-adapter",
+                reason: "pi has no built-in MCP; without this extension the servers in .pi/mcp.json are never read and the agent starts with none of their tools",
+                remedy: "pi install npm:pi-mcp-adapter",
+            });
+            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;
+        case "openclaw":
+            unsupported("mcp", "openclaw MCP is central ~/.openclaw/openclaw.json (mcp.servers), no cwd discovery");
+            break;
+    }
+}
+function tomlInlineStringTable(values) {
+    return `{ ${Object.entries(values)
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([key, value]) => `${tomlStr(key)} = ${tomlStr(value)}`)
+        .join(", ")} }`;
+}
+function codexMcpServerToml(name, server, plan) {
+    const fields = [];
+    if (server.url) {
+        fields.push(`url = ${tomlStr(server.url)}`);
+        if (server.headers && Object.keys(server.headers).length > 0) {
+            const envHeaders = {};
+            for (const [header, value] of Object.entries(server.headers).sort(([left], [right]) => compareStrings(left, right))) {
+                const envName = `TANGLE_MCP_HEADER_${sha256(`${name}\0${header}`)
+                    .slice(0, 24)
+                    .toUpperCase()}`;
+                setPlanEnvironment(plan, envName, value);
+                envHeaders[header] = envName;
+            }
+            fields.push(`env_http_headers = ${tomlInlineStringTable(envHeaders)}`);
+        }
+    }
+    else {
+        if (!server.command) {
+            throw new Error(`Codex MCP server "${name}" must define url or command`);
+        }
+        fields.push(`command = ${tomlStr(server.command)}`);
+        if (server.args?.length) {
+            fields.push(concatWorkspacePlanArguments("args = [", joinWorkspacePlanArguments(server.args.map(tomlProfileConfigValue), ", "), "]"));
+        }
+        if (server.cwd)
+            fields.push(`cwd = ${tomlStr(server.cwd)}`);
+        if (server.env && Object.keys(server.env).length > 0) {
+            const envNames = Object.keys(server.env).sort(compareStrings);
+            for (const envName of envNames) {
+                setPlanEnvironment(plan, envName, server.env[envName]);
+            }
+            fields.push(`env_vars = [${envNames.map(tomlStr).join(", ")}]`);
+        }
+    }
+    return concatWorkspacePlanArguments("{ ", joinWorkspacePlanArguments(fields, ", "), " }");
+}
+/**
+ * Lower one canonical MCP server to the shape `pi-mcp-adapter` reads from `.pi/mcp.json`.
+ *
+ * The adapter consumes the same `{mcpServers: {...}}` document Claude and Kimi use, so this
+ * mirrors {@link kimiMcpServer} rather than inventing a pi dialect. `directTools` is added by the
+ * caller, not here, because it is a policy about tool surfacing rather than a property of the
+ * server definition.
+ */
+function piMcpServer(server) {
+    return kimiMcpServer(server);
+}
+function kimiMcpServer(server) {
+    if (server.url) {
+        return {
+            url: server.url,
+            transport: server.transport ?? "http",
+            ...(server.headers ? { headers: server.headers } : {}),
+        };
+    }
+    return {
+        command: server.command,
+        ...(server.args ? { args: server.args } : {}),
+        ...(server.env ? { env: server.env } : {}),
+        ...(server.cwd ? { cwd: server.cwd } : {}),
+    };
+}
+/** Lower canonical MCP definitions to OpenCode's native startup configuration. */
+export function openCodeMcpConfig(mcp) {
+    const out = {};
+    for (const [name, s] of Object.entries(mcp)) {
+        if (s.enabled === false)
+            continue;
+        if (s.url) {
+            if (s.transport === "sse") {
+                throw new Error(`OpenCode MCP server "${name}" uses unsupported SSE transport`);
+            }
+            out[name] = {
+                type: "remote",
+                url: s.url,
+                enabled: true,
+                ...(s.headers ? { headers: s.headers } : {}),
+            };
+            continue;
+        }
+        if (!s.command) {
+            throw new Error(`OpenCode MCP server "${name}" must define either url or command`);
+        }
+        if (s.cwd !== undefined) {
+            throw new Error(`OpenCode MCP server "${name}" does not support a cwd field`);
+        }
+        out[name] = {
+            type: "local",
+            command: [s.command, ...(s.args ?? [])],
+            enabled: true,
+            ...(s.env ? { environment: s.env } : {}),
+        };
+    }
+    return out;
+}
+import { sha256 } from "./plan-digest.js";
+import { concatWorkspacePlanArguments, joinWorkspacePlanArguments, serializeWorkspacePlanJson, tomlProfileConfigValue, tomlStr, } from "./plan-json.js";
+import { setPlanEnvironment } from "./profile-plan.js";
+import { compareStrings } from "./workspace-files.js";

package/dist/pi-models-config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One custom-model shape for upstream Pi and the Prime fork.
+ *
+ * Both agents read the same `models.json` provider schema.
+ * Callers own the file lifecycle, but they must not build different payloads.
+ */
+export interface PiModelsConfigInput {
+    /** Provider key in models.json and the matching `--provider` value. */
+    providerName: string;
+    /** Model id in models.json and the matching `--model` value. */
+    modelId: string;
+    /** Provider endpoint. OpenAI-compatible endpoints include `/v1`. */
+    baseUrl: string;
+    /** Literal in-box credential or an environment reference. */
+    apiKey: string;
+    /** Pi wire protocol. */
+    api?: "anthropic-messages" | "google-generative-ai" | "openai-completions" | "openai-responses";
+    contextWindow?: number;
+    maxTokens?: number;
+    reasoning?: boolean;
+}
+export interface PiModelsConfigFile {
+    path: string;
+    content: string;
+    mode: number;
+}
+export declare const PI_MODELS_CONFIG_PATH = ".pi/agent/models.json";
+export declare function buildPiModelsConfig(input: PiModelsConfigInput): Record<string, unknown>;
+/** Build the owner-only Pi file used by headless and interactive processes. */
+export declare function buildPiModelsConfigFile(input: PiModelsConfigInput): PiModelsConfigFile;

package/dist/pi-models-config.js

@@ -0,0 +1,46 @@
+export const PI_MODELS_CONFIG_PATH = ".pi/agent/models.json";
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+export function buildPiModelsConfig(input) {
+    for (const [field, value] of [
+        ["providerName", input.providerName],
+        ["modelId", input.modelId],
+        ["baseUrl", input.baseUrl],
+        ["apiKey", input.apiKey],
+    ]) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new Error(`pi models.json requires a non-empty "${field}"; ` +
+                "the caller must supply provider, model, baseUrl, and apiKey");
+        }
+    }
+    return {
+        providers: {
+            [input.providerName]: {
+                name: input.providerName,
+                baseUrl: input.baseUrl,
+                api: input.api ?? "openai-completions",
+                apiKey: input.apiKey,
+                models: [
+                    {
+                        id: input.modelId,
+                        name: input.modelId,
+                        reasoning: input.reasoning ?? false,
+                        input: ["text", "image"],
+                        contextWindow: input.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+                        ...(input.maxTokens !== undefined
+                            ? { maxTokens: input.maxTokens }
+                            : {}),
+                        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                    },
+                ],
+            },
+        },
+    };
+}
+/** Build the owner-only Pi file used by headless and interactive processes. */
+export function buildPiModelsConfigFile(input) {
+    return {
+        path: PI_MODELS_CONFIG_PATH,
+        content: `${JSON.stringify(buildPiModelsConfig(input), null, 2)}\n`,
+        mode: 0o600,
+    };
+}

package/dist/plan-application.d.ts

@@ -0,0 +1,10 @@
+export declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string, options?: ApplyWorkspacePlanOptions): WorkspacePlanReceipt;
+/**
+ * Resolve opaque profile references through an executor-owned provider, then
+ * apply the resulting private native files and launch inputs. Resolution
+ * completes before any workspace write, and resolved values never enter the
+ * public plan, digest, receipt, logs, or error messages.
+ */
+export declare function applyWorkspacePlanWithSecretProvider(plan: WorkspacePlan, workspaceDir: string, secretProvider: AgentProfileSecretProvider, options?: ApplyWorkspacePlanOptions): Promise<WorkspacePlanApplication>;
+import type { AgentProfileSecretProvider } from "@tangle-network/agent-interface";
+import type { ApplyWorkspacePlanOptions, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanReceipt } from "./plan-types.js";

package/dist/plan-application.js

@@ -0,0 +1,152 @@
+export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
+    return applyResolvedWorkspacePlan(plan, resolvePublicWorkspacePlan(plan), workspaceDir, options).receipt;
+}
+/**
+ * Resolve opaque profile references through an executor-owned provider, then
+ * apply the resulting private native files and launch inputs. Resolution
+ * completes before any workspace write, and resolved values never enter the
+ * public plan, digest, receipt, logs, or error messages.
+ */
+export async function applyWorkspacePlanWithSecretProvider(plan, workspaceDir, secretProvider, options = {}) {
+    const planDigest = hashWorkspacePlan(plan);
+    const resolved = await resolvePrivateWorkspacePlan(plan, secretProvider);
+    return applyResolvedWorkspacePlan(plan, resolved, workspaceDir, options, planDigest);
+}
+function secretRefLabel(ref) {
+    return JSON.stringify(ref.key);
+}
+function requireResolvedSecretValue(ref, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`AgentProfile secret provider returned no value for ${secretRefLabel(ref)}`);
+    }
+    return value;
+}
+function setValueAtJsonPath(root, path, value) {
+    let current = root;
+    for (const segment of path.slice(0, -1)) {
+        if (current === null ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, segment)) {
+            throw new Error("Generated profile JSON secret path no longer exists");
+        }
+        current = current[segment];
+    }
+    const finalSegment = path.at(-1);
+    if (finalSegment === undefined ||
+        current === null ||
+        typeof current !== "object" ||
+        !Object.hasOwn(current, finalSegment)) {
+        throw new Error("Generated profile JSON secret path no longer exists");
+    }
+    Object.defineProperty(current, finalSegment, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+}
+function resolvePublicWorkspacePlan(plan) {
+    const files = normalizePlanFiles(plan.files);
+    for (const file of files) {
+        const ref = file.secretSlots[0]?.ref;
+        if (ref) {
+            throw new Error(`Workspace plan requires an AgentProfileSecretProvider for ${secretRefLabel(ref)}`);
+        }
+    }
+    const env = Object.fromEntries(Object.entries(plan.env).map(([name, value]) => {
+        if (typeof value !== "string") {
+            throw new Error(`Workspace plan requires an AgentProfileSecretProvider for ${secretRefLabel(value)}`);
+        }
+        return [name, value];
+    }));
+    const flags = plan.flags.map((argument) => {
+        const normalized = normalizeWorkspacePlanArgument(argument);
+        if (typeof normalized !== "string") {
+            const segment = normalized.segments.find((value) => typeof value !== "string");
+            if (!segment) {
+                throw new Error("Workspace plan argument template is malformed");
+            }
+            throw new Error(`Workspace plan requires an AgentProfileSecretProvider for ${secretRefLabel(segment.ref)}`);
+        }
+        return normalized;
+    });
+    return {
+        files,
+        env,
+        flags,
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
+    };
+}
+async function resolvePrivateWorkspacePlan(plan, secretProvider) {
+    if (!secretProvider || typeof secretProvider.get !== "function") {
+        throw new Error("AgentProfileSecretProvider.get is required");
+    }
+    const pending = new Map();
+    const resolveRef = async (input) => {
+        const ref = agentProfileSecretRefSchema.parse(input);
+        let raw = pending.get(ref.key);
+        if (!raw) {
+            raw = (async () => {
+                let value;
+                try {
+                    value = await secretProvider.get(ref.key);
+                }
+                catch {
+                    throw new Error(`AgentProfile secret provider failed for ${secretRefLabel(ref)}`);
+                }
+                return requireResolvedSecretValue(ref, value);
+            })();
+            pending.set(ref.key, raw);
+        }
+        const value = await raw;
+        return ref.format === "bearer" ? `Bearer ${value}` : value;
+    };
+    const files = await Promise.all(normalizePlanFiles(plan.files).map(async (file) => {
+        if (file.secretSlots.length === 0)
+            return file;
+        const parsed = JSON.parse(file.content);
+        const values = await Promise.all(file.secretSlots.map(async (slot) => ({
+            path: slot.path,
+            value: await resolveRef(slot.ref),
+        })));
+        for (const resolved of values) {
+            setValueAtJsonPath(parsed, resolved.path, resolved.value);
+        }
+        return {
+            ...file,
+            content: JSON.stringify(parsed, null, 2),
+            secretSlots: [],
+        };
+    }));
+    const env = Object.fromEntries(await Promise.all(Object.entries(plan.env).map(async ([name, value]) => [
+        name,
+        typeof value === "string" ? value : await resolveRef(value),
+    ])));
+    const flags = await Promise.all(plan.flags.map(async (argument) => {
+        const normalized = normalizeWorkspacePlanArgument(argument);
+        if (typeof normalized === "string")
+            return normalized;
+        const segments = await Promise.all(normalized.segments.map(async (segment) => {
+            if (typeof segment === "string")
+                return segment;
+            const value = await resolveRef(segment.ref);
+            return segment.encoding === "json-string"
+                ? JSON.stringify(value)
+                : value;
+        }));
+        return segments.join("");
+    }));
+    return {
+        files,
+        env,
+        flags,
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
+    };
+}
+import { agentProfileSecretRefSchema } from "@tangle-network/agent-interface";
+import { hashWorkspacePlan } from "./plan-digest.js";
+import { normalizePlanFiles, normalizeWorkspacePlanArgument, } from "./plan-normalize.js";
+import { promptIntentFields, samePromptIntentValue, systemPromptBindingField, } from "./plan-prompt.js";
+import { applyResolvedWorkspacePlan, } from "./workspace-apply.js";

package/dist/plan-digest.d.ts

@@ -0,0 +1,18 @@
+export declare const sha256: (value: string) => string;
+export declare function hashWorkspacePlan(plan: WorkspacePlan): string;
+/** Build the exact digest-free identity document required by agent-interface. */
+export declare function agentCandidateProfilePlanMaterial(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanMaterial;
+/**
+ * Return the RFC 8785 UTF-8 bytes and SHA-256 identity of a candidate profile
+ * plan. The returned bytes are the exact bytes embedded in receipt evidence.
+ */
+export declare function canonicalizeAgentCandidateProfilePlan(plan: AgentCandidateWorkspacePlan): {
+    material: AgentCandidateProfilePlanMaterial;
+    bytes: Uint8Array;
+    digest: Sha256Digest;
+};
+/** Capture portable evidence of the exact canonical profile-plan bytes. */
+export declare function captureAgentCandidateProfilePlan(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanEvidence;
+import type { AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, Sha256Digest } from "@tangle-network/agent-interface";
+import type { AgentCandidateWorkspacePlan } from "./candidate-types.js";
+import type { WorkspacePlan } from "./plan-types.js";

package/dist/plan-digest.js

@@ -0,0 +1,90 @@
+export const sha256 = (value) => createHash("sha256").update(value, "utf8").digest("hex");
+export function hashWorkspacePlan(plan) {
+    const files = normalizePlanFiles(plan.files).map((file) => ({
+        relPath: file.relPath,
+        mode: file.mode,
+        contentSha256: sha256(file.content),
+        // Ownership decides whether re-application may replace the file, so two
+        // plans identical in bytes but different here behave differently in the
+        // same workspace — the digest a receipt proves must say which one ran.
+        ownership: file.ownership,
+        ...(file.secretSlots.length === 0
+            ? {}
+            : {
+                secretSlots: [...file.secretSlots].sort((left, right) => compareStrings(JSON.stringify(left.path), JSON.stringify(right.path))),
+            }),
+    }));
+    const env = Object.fromEntries(Object.entries(plan.env)
+        .sort(([a], [b]) => compareStrings(a, b))
+        .map(([name, value]) => [
+        name,
+        typeof value === "string"
+            ? value
+            : agentProfileSecretRefSchema.parse(value),
+    ]));
+    const unsupported = [...plan.unsupported].sort((a, b) => compareStrings(`${a.dimension}\0${a.reason}`, `${b.dimension}\0${b.reason}`));
+    // A plan that needs an extension is not the same plan as one that does not, even when every
+    // byte it writes is identical — the digest is what a receipt proves, so it must say so.
+    const requires = [...(plan.requires ?? [])].sort((a, b) => compareStrings(`${a.kind}\0${a.id}`, `${b.kind}\0${b.id}`));
+    const canonical = JSON.stringify({
+        harness: plan.harness,
+        files,
+        env,
+        flags: plan.flags.map(normalizeWorkspacePlanArgument),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        // A plan that owes a launcher a replacement is not the same plan as one
+        // that owes nothing, even when every byte it writes is identical.
+        ...systemPromptBindingField(plan),
+        unsupported,
+        ...(requires.length === 0 ? {} : { requires }),
+    });
+    return `sha256:${sha256(canonical)}`;
+}
+/** Build the exact digest-free identity document required by agent-interface. */
+export function agentCandidateProfilePlanMaterial(plan) {
+    const material = {
+        sourceProfileDigest: plan.sourceProfileDigest,
+        harness: plan.harness,
+        files: normalizePlanFiles(plan.files).map((file) => ({
+            relPath: file.relPath,
+            mode: file.mode,
+            contentSha256: `sha256:${sha256(file.content)}`,
+        })),
+        env: Object.fromEntries(Object.entries(plan.env).sort(([left], [right]) => compareStrings(left, right))),
+        flags: [...plan.flags],
+        ...promptIntentFields(plan, samePromptIntentValue),
+        unsupported: [...plan.unsupported].sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`)),
+    };
+    return agentCandidateProfilePlanMaterialSchema.parse(material);
+}
+/**
+ * Return the RFC 8785 UTF-8 bytes and SHA-256 identity of a candidate profile
+ * plan. The returned bytes are the exact bytes embedded in receipt evidence.
+ */
+export function canonicalizeAgentCandidateProfilePlan(plan) {
+    const material = agentCandidateProfilePlanMaterial(plan);
+    const bytes = canonicalCandidateBytes(material);
+    const digest = canonicalCandidateDigest(material);
+    return { material, bytes, digest };
+}
+/** Capture portable evidence of the exact canonical profile-plan bytes. */
+export function captureAgentCandidateProfilePlan(plan) {
+    const canonical = canonicalizeAgentCandidateProfilePlan(plan);
+    const artifact = {
+        encoding: "base64",
+        content: Buffer.from(canonical.bytes).toString("base64"),
+        sha256: canonical.digest,
+        byteLength: canonical.bytes.byteLength,
+    };
+    return agentCandidateProfilePlanEvidenceSchema.parse({
+        kind: "agent-profile-workspace-plan",
+        digest: canonical.digest,
+        material: canonical.material,
+        artifact,
+    });
+}
+import { createHash } from "node:crypto";
+import { agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentProfileSecretRefSchema, canonicalCandidateBytes, canonicalCandidateDigest, } from "@tangle-network/agent-interface";
+import { normalizePlanFiles, normalizeWorkspacePlanArgument, } from "./plan-normalize.js";
+import { promptIntentFields, samePromptIntentValue, systemPromptBindingField, } from "./plan-prompt.js";
+import { compareStrings } from "./workspace-files.js";

package/dist/plan-json.d.ts

@@ -0,0 +1,18 @@
+export declare const tomlStr: (s: string) => string;
+export interface SerializedPlanFileContent {
+    content: string;
+    secretSlots?: PlanFileSecretSlot[];
+}
+export type AddPlanFile = (path: string, content: string | SerializedPlanFileContent, mode?: number) => void;
+export declare function isProfilePublicConfigValue(value: unknown): value is Extract<AgentProfileConfigValue, {
+    kind: "public";
+}>;
+export declare function isProfileSecretRef(value: unknown): value is AgentProfileSecretRef;
+export declare function workspacePlanConfigValue(value: AgentProfileConfigValue): WorkspacePlanConfigValue;
+export declare function serializeWorkspacePlanJson(value: unknown): SerializedPlanFileContent;
+export declare function workspacePlanArgumentSegments(value: WorkspacePlanArgument): Array<string | WorkspacePlanSecretSegment>;
+export declare function concatWorkspacePlanArguments(...values: WorkspacePlanArgument[]): WorkspacePlanArgument;
+export declare function joinWorkspacePlanArguments(values: WorkspacePlanArgument[], separator: string): WorkspacePlanArgument;
+export declare function tomlProfileConfigValue(value: AgentProfileConfigValue): WorkspacePlanArgument;
+import type { AgentProfileConfigValue, AgentProfileSecretRef } from "@tangle-network/agent-interface";
+import type { PlanFileSecretSlot, WorkspacePlanArgument, WorkspacePlanConfigValue, WorkspacePlanSecretSegment } from "./plan-types.js";