@tangle-network/agent-profile-materialize 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -21,7 +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.
  */
-import type { AgentProfile } from "@tangle-network/agent-interface";
+import type { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterialV1, AgentProfile, Sha256Digest } from "@tangle-network/agent-interface";
 export type HarnessId = "claude-code" | "claude" | "claudish" | "nanoclaw" | "codex" | "opencode" | "kimi-code" | "kimi" | "pi" | "gemini" | "hermes" | "openclaw";
 export interface PlanFile {
     relPath: string;
@@ -30,7 +30,7 @@ export interface PlanFile {
     mode?: number;
 }
 export interface Unsupported {
-    dimension: "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "permissions" | "tools";
+    dimension: "files" | "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "permissions" | "tools";
     reason: string;
 }
 /** The plan a caller writes into the run cwd, then applies to the spawn. */
@@ -45,6 +45,40 @@ export interface WorkspacePlan {
     /** Dimensions requested but with NO cwd path on this harness — fail-closed record. */
     unsupported: Unsupported[];
 }
+/**
+ * Proof of the profile workspace inputs applied before a harness is spawned.
+ * `workspacePlanDigest` covers only the {@link WorkspacePlan}; it is not an
+ * execution-plan digest and does not attest unrelated files in `workspaceDir`.
+ */
+export interface WorkspacePlanReceipt {
+    workspacePlanDigest: string;
+    env: Record<string, string>;
+    flags: string[];
+    unsupported: Unsupported[];
+    written: string[];
+}
+/**
+ * Candidate-safe workspace plan. Spawn values remain typed until the runtime
+ * resolves them; the materializer never joins argv into a shell command.
+ */
+export interface AgentCandidateWorkspacePlan {
+    harness: HarnessId;
+    files: PlanFile[];
+    env: Record<string, AgentCandidateConfigValue>;
+    flags: AgentCandidateConfigValue[];
+    unsupported: Unsupported[];
+}
+export interface AgentCandidateWorkspacePlanReceipt {
+    profilePlan: AgentCandidateProfilePlanEvidence;
+    application: AgentCandidateProfileApplication;
+    env: Record<string, AgentCandidateConfigValue>;
+    flags: AgentCandidateConfigValue[];
+    unsupported: Unsupported[];
+}
+export interface MaterializeCandidateProfileOptions {
+    /** Exact text fetched from pinned resource refs, keyed by declared SHA-256. */
+    resolvedResources?: ReadonlyMap<Sha256Digest, string>;
+}
 /** Normalize any skill markdown (VB frontmatter `skill:`/`description:`, or raw) into a
  *  harness SKILL.md with `name:`/`description:` frontmatter the harnesses require. */
 export declare function normalizeSkillMd(name: string, raw: string): string;
@@ -55,15 +89,41 @@ export declare function normalizeSkillMd(name: string, raw: string): string;
 export declare function materializeProfile(profile: AgentProfile, harness: HarnessId, opts?: {
     skip?: Unsupported["dimension"][];
 }): WorkspacePlan;
+/**
+ * Materialize a sealed candidate profile without weakening its process values.
+ * Candidate hooks deliberately fail closed because the currently supported
+ * native hook formats accept a shell command string rather than executable +
+ * argv + env as separate fields.
+ */
+export declare function materializeCandidateProfile(profile: AgentCandidateProfile, harness: HarnessId, opts?: MaterializeCandidateProfileOptions): AgentCandidateWorkspacePlan;
+/**
+ * Hash the exact files, modes, flags, environment, and unsupported dimensions
+ * represented by a plan. Array order is preserved only where it changes spawn
+ * behavior; unordered maps and file records are canonicalized first.
+ */
+export declare function hashWorkspacePlan(plan: WorkspacePlan): string;
+/** Build the exact digest-free identity document required by agent-interface. */
+export declare function agentCandidateProfilePlanMaterial(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanMaterialV1;
+/**
+ * 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: AgentCandidateProfilePlanMaterialV1;
+    bytes: Uint8Array;
+    digest: Sha256Digest;
+};
+/** Capture portable evidence of the exact canonical profile-plan bytes. */
+export declare function captureAgentCandidateProfilePlan(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanEvidence;
+/**
+ * Apply a candidate plan and return its spawn values together with captured
+ * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
+ */
+export declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWorkspacePlan, workspaceDir: string, targetWorkspace: AgentCandidateProfileApplication["targetWorkspace"]): AgentCandidateWorkspacePlanReceipt;
 /**
  * Apply a WorkspacePlan to a real workspace dir: write every file (creating parent
  * dirs), and return the env + flags the caller must hand the spawn. This is the IO
  * consumer of the pure `materializeProfile` — used by the cli-bridge host spawn, the
  * agent-dev-container box, and VB. Returns `unsupported` so the caller can log/fail.
  */
-export declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string): {
-    env: Record<string, string>;
-    flags: string[];
-    unsupported: Unsupported[];
-    written: string[];
-};
+export declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string): WorkspacePlanReceipt;

package/dist/index.js

@@ -21,8 +21,10 @@
  * `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.
  */
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, fchmodSync, constants as fsConstants, lstatSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
+import { agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, } from "@tangle-network/agent-interface";
 /** Resolve an inline resource ref to {name, content}. github refs need an async fetch
  *  (the providers' resolveProfileResource does this); the sync materializer can't, so a
  *  github ref is reported unsupported and the caller pre-resolves it. A ref with
@@ -78,6 +80,48 @@ function canonicalHarness(h) {
 // ─── Helpers ────────────────────────────────────────────────────────────────
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
 const collapse = (s) => s.replace(/\s+/g, " ").trim();
+const compareStrings = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const DEFAULT_FILE_MODE = 0o644;
+const EXECUTABLE_FILE_MODE = 0o755;
+const SAFE_WRITE_FLAGS = fsConstants.O_WRONLY |
+    fsConstants.O_CREAT |
+    fsConstants.O_EXCL |
+    (typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0);
+function normalizeWorkspaceRelativePath(pathValue) {
+    if (typeof pathValue !== "string" ||
+        !pathValue ||
+        hasControlCharacter(pathValue)) {
+        throw new Error("Workspace file path must be non-empty and contain no control characters");
+    }
+    if (isAbsolute(pathValue) ||
+        win32.isAbsolute(pathValue) ||
+        /^[A-Za-z]:/.test(pathValue)) {
+        throw new Error(`Workspace file path must be relative: ${pathValue}`);
+    }
+    const segments = pathValue.replace(/\\/g, "/").split("/");
+    if (segments.some((segment) => !segment ||
+        segment === "." ||
+        segment === ".." ||
+        segment === ".sidecar")) {
+        throw new Error(`Workspace file path must be canonical: ${pathValue}`);
+    }
+    return segments.join("/");
+}
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function validateFileMode(mode) {
+    const normalized = mode ?? DEFAULT_FILE_MODE;
+    if (!Number.isInteger(normalized) || normalized < 0 || normalized > 0o777) {
+        throw new Error(`Workspace file mode must be between 0o000 and 0o777: ${mode}`);
+    }
+    return normalized;
+}
 /** Normalize any skill markdown (VB frontmatter `skill:`/`description:`, or raw) into a
  *  harness SKILL.md with `name:`/`description:` frontmatter the harnesses require. */
 export function normalizeSkillMd(name, raw) {
@@ -126,9 +170,73 @@ export function materializeProfile(profile, harness, opts = {}) {
         flags: [],
         unsupported: [],
     };
-    const add = (relPath, content, mode) => plan.files.push({ relPath, content, ...(mode ? { mode } : {}) });
+    const add = (relPath, content, mode) => {
+        const normalizedPath = normalizeWorkspaceRelativePath(relPath);
+        plan.files.push({
+            relPath: normalizedPath,
+            content,
+            ...(mode === undefined ? {} : { mode: validateFileMode(mode) }),
+        });
+    };
     const unsupported = (dimension, reason) => plan.unsupported.push({ dimension, reason });
-    // 1) CONTEXT (instructions + systemPrompt → the harness's native context file).
+    const explicitResourcePaths = new Map();
+    const addExplicitResource = (dimension, relPath, content, mode) => {
+        const normalizedPath = normalizeWorkspaceRelativePath(relPath);
+        const previousDimension = explicitResourcePaths.get(normalizedPath);
+        if (previousDimension) {
+            throw new Error(`Duplicate profile resource path: ${normalizedPath} (${previousDimension}, ${dimension})`);
+        }
+        explicitResourcePaths.set(normalizedPath, dimension);
+        add(normalizedPath, content, mode);
+    };
+    // 1) GENERIC FILES → exact workspace-relative paths. Inline refs are
+    // deterministic; remote refs must be resolved by an async caller first.
+    const fileMountPaths = new Set();
+    for (const mount of profile.resources?.files ?? []) {
+        const relPath = normalizeWorkspaceRelativePath(mount.path);
+        if (fileMountPaths.has(relPath)) {
+            throw new Error(`Duplicate workspace file mount: ${relPath}`);
+        }
+        fileMountPaths.add(relPath);
+        if (mount.executable !== undefined &&
+            typeof mount.executable !== "boolean") {
+            throw new Error(`Workspace file executable must be a boolean: ${relPath}`);
+        }
+        const resource = resolveInlineRef(mount.resource);
+        if (!resource) {
+            unsupported("files", `file mount "${relPath}" is not inline (github refs need async pre-resolution)`);
+            continue;
+        }
+        addExplicitResource("files", relPath, resource.content, mount.executable ? EXECUTABLE_FILE_MODE : DEFAULT_FILE_MODE);
+    }
+    // 2) PROVIDER-NATIVE TOOLS → only OpenCode exposes a verified cwd path.
+    for (const ref of profile.resources?.tools ?? []) {
+        const resource = resolveInlineRef(ref);
+        if (!resource) {
+            unsupported("tools", "tool ref is not inline (github refs need async pre-resolution)");
+            continue;
+        }
+        if (h !== "opencode") {
+            unsupported("tools", `${h}: no verified cwd-native file tool path; use MCP or a native extension`);
+            continue;
+        }
+        addExplicitResource("tools", `.opencode/tools/${resource.name}`, resource.content);
+    }
+    // 3) PROVIDER-NATIVE AGENTS → raw native definitions at verified cwd paths.
+    for (const ref of profile.resources?.agents ?? []) {
+        const resource = resolveInlineRef(ref);
+        if (!resource) {
+            unsupported("subagents", "agent ref is not inline (github refs need async pre-resolution)");
+            continue;
+        }
+        const directory = agentResourceDirectory(h);
+        if (!directory) {
+            unsupported("subagents", `${h}: agent definitions have no verified cwd-native resource path`);
+            continue;
+        }
+        addExplicitResource("subagents", `${directory}/${resource.name}`, resource.content);
+    }
+    // 4) CONTEXT (instructions + systemPrompt → the harness's native context file).
     const instr = [];
     if (profile.prompt?.systemPrompt)
         instr.push(profile.prompt.systemPrompt);
@@ -143,7 +251,7 @@ export function materializeProfile(profile, harness, opts = {}) {
         add(CONTEXT_FILE[h], `${instr.join("\n\n")}\n`);
         // gemini reads AGENTS.md only via settings; we write GEMINI.md so no extra step.
     }
-    // 2) SKILLS → native skill dir, from resources.skills refs (the box's shape), or
+    // 5) SKILLS → native skill dir, from resources.skills refs (the box's shape), or
     //    fail-closed (hermes has no cwd skill dir; github refs need async pre-resolution).
     for (const ref of profile.resources?.skills ?? []) {
         const r = resolveInlineRef(ref);
@@ -156,35 +264,295 @@ export function materializeProfile(profile, harness, opts = {}) {
             unsupported("skills", `${h}: no cwd skill dir (skills live in a user/global dir); skill "${r.name}" not mounted`);
             continue;
         }
-        add(`${dir}/${r.name}/SKILL.md`, normalizeSkillMd(r.name, r.content));
+        addExplicitResource("skills", `${dir}/${r.name}/SKILL.md`, normalizeSkillMd(r.name, r.content));
     }
-    // 3) MCP → per-harness format (the divergence the matrix names). Skippable so the
+    // 6) MCP → per-harness format (the divergence the matrix names). Skippable so the
     //    additive host-wiring can leave MCP on cli-bridge's existing per-harness path.
     const mcp = profile.mcp ?? {};
     if (!skip.has("mcp") && Object.keys(mcp).length)
         materializeMcp(h, mcp, plan, add, unsupported);
-    // 4) HOOKS → per-harness format; cwd-native only for claude/codex/gemini/opencode(plugin).
+    // 7) HOOKS → per-harness format; cwd-native only for claude/codex/gemini/opencode(plugin).
     const hooks = profile.hooks ?? {};
     if (Object.keys(hooks).length)
         materializeHooks(h, hooks, add, unsupported, plan);
-    // 5) SUBAGENTS → cwd-native for claude/codex/opencode/gemini; flag/global elsewhere.
+    // 8) SUBAGENTS → cwd-native for claude/codex/opencode/gemini; flag/global elsewhere.
     const subagents = profile.subagents ?? {};
     for (const [name, sa] of Object.entries(subagents))
         materializeSubagent(h, name, sa, add, unsupported);
-    // 6) COMMANDS → cwd-native (resources.commands refs); "commands are skills" on kimi.
+    // 9) COMMANDS → cwd-native (resources.commands refs); "commands are skills" on kimi.
     for (const ref of profile.resources?.commands ?? []) {
         const r = resolveInlineRef(ref);
         if (!r) {
             unsupported("commands", "command ref is not inline (github needs pre-resolution)");
             continue;
         }
-        materializeCommand(h, r.name, r.content, add, unsupported);
+        materializeCommand(h, r.name, r.content, (path, content, mode) => addExplicitResource("commands", path, content, mode), unsupported);
+    }
+    for (const [relPath, dimension] of explicitResourcePaths) {
+        const writers = plan.files.filter((file) => file.relPath === relPath).length;
+        if (writers > 1) {
+            throw new Error(`Profile ${dimension} resource conflicts with generated harness file: ${relPath}`);
+        }
+    }
+    // Merge native multi-writer JSON files (e.g. .claude/settings.json from both
+    // mcp and hooks) so the second writer cannot clobber the first.
+    plan.files = mergeJsonFiles(plan.files).sort((a, b) => compareStrings(a.relPath, b.relPath));
+    if (profile.resources?.failOnError && plan.unsupported.length) {
+        throw new Error(formatUnsupported(plan.unsupported));
     }
-    // Merge multi-writer JSON files (e.g. .claude/settings.json from both mcp and hooks)
-    // so the second write can't clobber the first.
-    plan.files = mergeJsonFiles(plan.files);
     return plan;
 }
+/**
+ * Materialize a sealed candidate profile without weakening its process values.
+ * Candidate hooks deliberately fail closed because the currently supported
+ * native hook formats accept a shell command string rather than executable +
+ * argv + env as separate fields.
+ */
+export function materializeCandidateProfile(profile, harness, opts = {}) {
+    const candidate = agentCandidateProfileSchema.parse(profile);
+    verifyCandidateInlineResources(candidate);
+    const hookLowering = lowerCandidateHooks(candidate.hooks, harness);
+    const candidateResources = candidate.resources
+        ? candidateResourcesForClassicMaterializer(candidate.resources, opts.resolvedResources)
+        : {};
+    candidateResources.files = [
+        ...(candidateResources.files ?? []),
+        ...hookLowering.wrapperFiles,
+    ];
+    const classicProfile = {
+        ...candidate,
+        resources: candidateResources,
+        mcp: candidateMcpRecordForClassicMaterializer(candidate.mcp),
+        hooks: hookLowering.hooks,
+    };
+    const classicPlan = materializeProfile(classicProfile, harness);
+    if (canonicalHarness(harness) === "opencode" &&
+        Object.values(candidate.mcp ?? {}).some((server) => server.enabled !== false && server.cwd !== undefined)) {
+        classicPlan.unsupported.push({
+            dimension: "mcp",
+            reason: "opencode local MCP configuration does not support a cwd field",
+        });
+    }
+    if (hookLowering.unsupportedReason) {
+        classicPlan.unsupported.push({
+            dimension: "hooks",
+            reason: hookLowering.unsupportedReason,
+        });
+    }
+    classicPlan.unsupported.sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`));
+    if (classicPlan.unsupported.length > 0) {
+        throw new Error(formatUnsupported(classicPlan.unsupported));
+    }
+    return {
+        harness: classicPlan.harness,
+        files: classicPlan.files,
+        env: candidatePublicRecord(classicPlan.env),
+        flags: classicPlan.flags.map(candidatePublicValue),
+        unsupported: classicPlan.unsupported,
+    };
+}
+function lowerCandidateHooks(hooks, harness) {
+    if (!hooks || Object.keys(hooks).length === 0)
+        return { wrapperFiles: [] };
+    if (canonicalHarness(harness) !== "codex") {
+        return {
+            wrapperFiles: [],
+            unsupportedReason: `${canonicalHarness(harness)} hook configuration requires an unverified command-string mapping; ` +
+                "sealed candidate hooks preserve executable, argv, and env separately",
+        };
+    }
+    const wrapperFiles = [];
+    const lowered = {};
+    for (const [event, commands] of Object.entries(hooks)) {
+        lowered[event] = commands.map((command, index) => {
+            const wrapper = candidateHookWrapper(event, index, command);
+            wrapperFiles.push({
+                path: wrapper.path,
+                resource: {
+                    kind: "inline",
+                    name: wrapper.path,
+                    content: wrapper.content,
+                },
+            });
+            return {
+                command: `node ${wrapper.path}`,
+                timeoutMs: command.timeoutMs,
+                blocking: command.blocking,
+                matcher: command.matcher,
+            };
+        });
+    }
+    return { hooks: lowered, wrapperFiles };
+}
+function candidateHookWrapper(event, index, command) {
+    const args = (command.args ?? []).map(candidatePublicString);
+    const env = Object.fromEntries(Object.entries(command.env ?? {})
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([name, value]) => [name, candidatePublicString(value)]));
+    const identity = rfc8785Serialize({
+        event,
+        index,
+        executable: command.executable,
+        args,
+        env,
+        timeoutMs: command.timeoutMs ?? null,
+        blocking: command.blocking ?? null,
+        matcher: command.matcher ?? null,
+    });
+    const wrapperId = sha256(identity);
+    const path = `.tangle/profile-hooks/${wrapperId}.mjs`;
+    const content = [
+        'import { spawnSync } from "node:child_process"',
+        `const executable = ${JSON.stringify(command.executable)}`,
+        `const args = ${JSON.stringify(args)}`,
+        `const extraEnv = ${JSON.stringify(env)}`,
+        "const result = spawnSync(executable, args, {",
+        '  stdio: "inherit",',
+        "  env: { ...process.env, ...extraEnv },",
+        "  shell: false,",
+        "})",
+        "if (result.error) {",
+        "  console.error(result.error.message)",
+        "  process.exit(127)",
+        "}",
+        "if (result.signal) {",
+        '  console.error("hook terminated by " + result.signal)',
+        "  process.exit(1)",
+        "}",
+        "process.exit(result.status ?? 1)",
+        "",
+    ].join("\n");
+    return { path, content };
+}
+function agentResourceDirectory(harness) {
+    switch (harness) {
+        case "claude-code":
+        case "nanoclaw":
+            return ".claude/agents";
+        case "codex":
+            return ".codex/agents";
+        case "opencode":
+            return ".opencode/agents";
+        case "gemini":
+            return ".gemini/agents";
+        default:
+            return null;
+    }
+}
+function candidateMcpRecordForClassicMaterializer(servers) {
+    if (!servers)
+        return undefined;
+    return Object.fromEntries(Object.entries(servers)
+        .filter(([, server]) => server.enabled !== false)
+        .map(([name, server]) => [
+        name,
+        candidateMcpForClassicMaterializer(server),
+    ]));
+}
+function candidateMcpForClassicMaterializer(server) {
+    return {
+        transport: server.transport,
+        command: server.command,
+        args: server.args?.map(candidatePublicString),
+        env: server.env
+            ? Object.fromEntries(Object.entries(server.env).map(([name, value]) => [
+                name,
+                candidatePublicString(value),
+            ]))
+            : undefined,
+        cwd: server.cwd,
+        enabled: server.enabled,
+    };
+}
+function candidateResourcesForClassicMaterializer(resources, resolvedResources) {
+    const convert = (ref) => {
+        if (ref.kind === "inline") {
+            return { kind: "inline", name: ref.name, content: ref.content };
+        }
+        const content = resolvedResources?.get(ref.sha256);
+        if (content !== undefined) {
+            verifyCandidateResourceBytes(ref, content, ref.name ?? ref.path);
+            return {
+                kind: "inline",
+                name: ref.name ?? ref.path.split("/").at(-1) ?? "resource",
+                content,
+            };
+        }
+        return {
+            kind: "github",
+            repository: `${ref.repository.owner}/${ref.repository.repo}`,
+            path: ref.path,
+            ref: ref.commit,
+            name: ref.name,
+        };
+    };
+    return {
+        files: resources.files?.map((mount) => ({
+            path: mount.path,
+            resource: convert(mount.resource),
+            executable: mount.executable,
+        })),
+        tools: resources.tools?.map(convert),
+        skills: resources.skills?.map(convert),
+        agents: resources.agents?.map(convert),
+        commands: resources.commands?.map(convert),
+        instructions: typeof resources.instructions === "string"
+            ? resources.instructions
+            : resources.instructions
+                ? convert(resources.instructions)
+                : undefined,
+        // The candidate wrapper owns the complete unsupported check after it adds
+        // dimensions that the classic materializer cannot represent.
+        failOnError: false,
+    };
+}
+function candidatePublicString(value) {
+    if (value.kind !== "public") {
+        throw new Error("Candidate materialization accepts public config values only");
+    }
+    return value.value;
+}
+function candidatePublicValue(value) {
+    return { kind: "public", value };
+}
+function candidatePublicRecord(values) {
+    return Object.fromEntries(Object.entries(values).map(([name, value]) => [
+        name,
+        candidatePublicValue(value),
+    ]));
+}
+function verifyCandidateInlineResources(profile) {
+    const resources = profile.resources;
+    if (!resources)
+        return;
+    const refs = [
+        ...(resources.files?.map((mount) => mount.resource) ?? []),
+        ...(resources.tools ?? []),
+        ...(resources.skills ?? []),
+        ...(resources.agents ?? []),
+        ...(resources.commands ?? []),
+        ...(typeof resources.instructions === "object"
+            ? [resources.instructions]
+            : []),
+    ];
+    for (const ref of refs) {
+        if (ref.kind !== "inline")
+            continue;
+        verifyCandidateResourceBytes(ref, ref.content, ref.name);
+    }
+}
+function verifyCandidateResourceBytes(ref, content, label) {
+    const bytes = Buffer.from(content, "utf8");
+    const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    if (bytes.byteLength !== ref.byteLength || digest !== ref.sha256) {
+        throw new Error(`Candidate resource integrity mismatch: ${label}`);
+    }
+}
+function formatUnsupported(unsupported) {
+    return `Unable to materialize ${unsupported.length} profile resource(s):\n${unsupported
+        .map(({ dimension, reason }) => `- ${dimension}: ${reason}`)
+        .join("\n")}`;
+}
 /** Collapse multiple PlanFiles with the same relPath: top-level-merge JSON, last-wins
  *  for non-JSON. settings.json contributors use disjoint top-level keys, so this unions them. */
 function mergeJsonFiles(files) {
@@ -215,6 +583,149 @@ function mergeJsonFiles(files) {
     }
     return [...byPath.values()];
 }
+function normalizePlanFiles(files) {
+    const seen = new Set();
+    return files
+        .map((file) => {
+        const relPath = normalizeWorkspaceRelativePath(file.relPath);
+        if (seen.has(relPath)) {
+            throw new Error(`Duplicate workspace plan file: ${relPath}`);
+        }
+        seen.add(relPath);
+        if (typeof file.content !== "string") {
+            throw new Error(`Workspace file content must be a string: ${relPath}`);
+        }
+        return {
+            relPath,
+            content: file.content,
+            mode: validateFileMode(file.mode),
+        };
+    })
+        .sort((a, b) => compareStrings(a.relPath, b.relPath));
+}
+const sha256 = (value) => createHash("sha256").update(value, "utf8").digest("hex");
+/**
+ * Hash the exact files, modes, flags, environment, and unsupported dimensions
+ * represented by a plan. Array order is preserved only where it changes spawn
+ * behavior; unordered maps and file records are canonicalized first.
+ */
+export function hashWorkspacePlan(plan) {
+    const files = normalizePlanFiles(plan.files).map((file) => ({
+        relPath: file.relPath,
+        mode: file.mode,
+        contentSha256: sha256(file.content),
+    }));
+    const env = Object.fromEntries(Object.entries(plan.env).sort(([a], [b]) => compareStrings(a, b)));
+    const unsupported = [...plan.unsupported].sort((a, b) => compareStrings(`${a.dimension}\0${a.reason}`, `${b.dimension}\0${b.reason}`));
+    const canonical = JSON.stringify({
+        version: 1,
+        harness: canonicalHarness(plan.harness),
+        files,
+        env,
+        flags: [...plan.flags],
+        unsupported,
+    });
+    return `sha256:${sha256(canonical)}`;
+}
+/** Build the exact digest-free identity document required by agent-interface. */
+export function agentCandidateProfilePlanMaterial(plan) {
+    const material = {
+        version: 1,
+        harness: canonicalHarness(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],
+        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 = Uint8Array.from(Buffer.from(rfc8785Serialize(material), "utf8"));
+    const digest = `sha256:${createHash("sha256")
+        .update(bytes)
+        .digest("hex")}`;
+    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({
+        schemaVersion: 1,
+        kind: "agent-profile-workspace-plan",
+        digest: canonical.digest,
+        material: canonical.material,
+        artifact,
+    });
+}
+/**
+ * Apply a candidate plan and return its spawn values together with captured
+ * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
+ */
+export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorkspace) {
+    if (plan.unsupported.length > 0) {
+        throw new Error(formatUnsupported(plan.unsupported));
+    }
+    const profilePlan = captureAgentCandidateProfilePlan(plan);
+    const applied = applyWorkspacePlan({
+        harness: plan.harness,
+        files: plan.files,
+        env: Object.fromEntries(Object.entries(plan.env).map(([name, value]) => [
+            name,
+            candidatePublicString(value),
+        ])),
+        flags: plan.flags.map(candidatePublicString),
+        unsupported: plan.unsupported,
+    }, workspaceDir);
+    return {
+        profilePlan,
+        application: {
+            planDigest: profilePlan.digest,
+            targetWorkspace,
+            mountPaths: applied.written,
+        },
+        env: { ...plan.env },
+        flags: [...plan.flags],
+        unsupported: [...plan.unsupported],
+    };
+}
+function rfc8785Serialize(value) {
+    if (value === null || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("RFC 8785 cannot serialize a non-finite number");
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(rfc8785Serialize).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort(compareStrings)
+            .map((key) => `${JSON.stringify(key)}:${rfc8785Serialize(record[key])}`)
+            .join(",")}}`;
+    }
+    throw new Error(`RFC 8785 cannot serialize ${typeof value}`);
+}
 /**
  * Apply a WorkspacePlan to a real workspace dir: write every file (creating parent
  * dirs), and return the env + flags the caller must hand the spawn. This is the IO
@@ -222,20 +733,106 @@ function mergeJsonFiles(files) {
  * agent-dev-container box, and VB. Returns `unsupported` so the caller can log/fail.
  */
 export function applyWorkspacePlan(plan, workspaceDir) {
+    const workspaceRoot = resolve(workspaceDir);
+    const files = normalizePlanFiles(plan.files).map((file) => ({
+        ...file,
+        absPath: resolveWorkspaceFilePath(workspaceRoot, file.relPath),
+    }));
+    // Validate the complete plan before the first write so a late traversal or
+    // existing symlink cannot leave a partially materialized workspace.
+    for (const file of files) {
+        assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+    }
+    for (const file of files) {
+        mkdirSync(dirname(file.absPath), { recursive: true });
+    }
+    for (const file of files) {
+        assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+    }
     const written = [];
-    for (const f of plan.files) {
-        const abs = join(workspaceDir, f.relPath);
-        mkdirSync(dirname(abs), { recursive: true });
-        writeFileSync(abs, f.content, { mode: f.mode ?? 0o644 });
-        written.push(f.relPath);
+    for (const file of files) {
+        writeWorkspaceFile(workspaceRoot, file);
+        written.push(file.relPath);
     }
     return {
+        workspacePlanDigest: hashWorkspacePlan(plan),
         env: plan.env,
         flags: plan.flags,
         unsupported: plan.unsupported,
         written,
     };
 }
+function resolveWorkspaceFilePath(workspaceRoot, relativePath) {
+    const targetPath = resolve(workspaceRoot, ...relativePath.split("/"));
+    const targetRelativePath = relative(workspaceRoot, targetPath);
+    if (!targetRelativePath ||
+        targetRelativePath === ".." ||
+        targetRelativePath.startsWith(`..${sep}`) ||
+        isAbsolute(targetRelativePath)) {
+        throw new Error(`Refusing to materialize profile file outside workspace: ${relativePath}`);
+    }
+    return targetPath;
+}
+function assertNoSymlinkPathComponents(workspaceRoot, targetPath) {
+    const targetRelativePath = relative(workspaceRoot, targetPath);
+    let currentPath = workspaceRoot;
+    const components = ["", ...targetRelativePath.split(sep)];
+    for (const [index, component] of components.entries()) {
+        if (component)
+            currentPath = join(currentPath, component);
+        let stats;
+        try {
+            stats = lstatSync(currentPath);
+        }
+        catch (error) {
+            if (isFsError(error, "ENOENT"))
+                return;
+            if (isFsError(error, "ELOOP")) {
+                throw new Error(`Refusing to materialize profile file through symlink path: ${targetRelativePath}`);
+            }
+            throw error;
+        }
+        if (stats.isSymbolicLink()) {
+            throw new Error(`Refusing to materialize profile file through symlink path: ${targetRelativePath}`);
+        }
+        const isTarget = index === components.length - 1;
+        if ((!isTarget && !stats.isDirectory()) || (isTarget && !stats.isFile())) {
+            throw new Error(`Refusing to materialize profile file through non-file path: ${targetRelativePath}`);
+        }
+    }
+}
+function writeWorkspaceFile(workspaceRoot, file) {
+    assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+    const temporaryPath = join(dirname(file.absPath), `.agent-profile-${randomUUID()}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(temporaryPath, SAFE_WRITE_FLAGS, 0o600);
+        writeFileSync(descriptor, file.content, "utf8");
+        fchmodSync(descriptor, file.mode);
+        closeSync(descriptor);
+        descriptor = undefined;
+        assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+        renameSync(temporaryPath, file.absPath);
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch (cleanupError) {
+            if (!isFsError(cleanupError, "ENOENT"))
+                throw cleanupError;
+        }
+        throw error;
+    }
+}
+function isFsError(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
 // ─── Per-dimension routing (verified matrix) ────────────────────────────────
 function materializeMcp(h, mcp, plan, add, unsupported) {
     switch (h) {
@@ -257,6 +854,8 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
                     lines.push(`command = ${tomlStr(s.command)}`);
                 if (s.args?.length)
                     lines.push(`args = [${s.args.map(tomlStr).join(", ")}]`);
+                if (s.cwd)
+                    lines.push(`cwd = ${tomlStr(s.cwd)}`);
                 if (s.url)
                     lines.push(`url = ${tomlStr(s.url)}`);
                 if (s.env)
@@ -354,7 +953,7 @@ function materializeHooks(h, hooks, add, unsupported, plan) {
             // opencode hooks are PLUGINS (JS/TS), not a settings block — emit a plugin stub.
             for (const [event, cmds] of Object.entries(hooks)) {
                 const body = cmds.map((c) => `  // ${event}: ${c.command}`).join("\n");
-                add(`.opencode/plugin/vb-hooks-${event}.js`, `// auto-generated hook plugin for ${event}\nexport default async function () {\n${body}\n}\n`);
+                add(`.opencode/plugins/vb-hooks-${event}.js`, `// auto-generated hook plugin for ${event}\nexport default async function () {\n${body}\n}\n`);
             }
             unsupported("hooks", "opencode hooks are JS/TS plugins — generated a stub; a real handler must run the command (format differs from settings.json)");
             break;
@@ -401,7 +1000,7 @@ function materializeSubagent(h, name, sa, add, unsupported) {
             if (sa.model)
                 fm.push(`model: ${sa.model}`);
             fm.push("---", "", sa.prompt ?? "");
-            add(`.opencode/agent/${name}.md`, `${fm.join("\n")}\n`);
+            add(`.opencode/agents/${name}.md`, `${fm.join("\n")}\n`);
             break;
         }
         case "gemini":
@@ -429,7 +1028,7 @@ function materializeCommand(h, name, body, add, unsupported) {
             add(`.claude/commands/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
             break;
         case "opencode":
-            add(`.opencode/command/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
+            add(`.opencode/commands/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
             break;
         case "gemini":
             add(`.gemini/commands/${name}.toml`, `prompt = ${tomlStr(body)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.2.3",
+  "version": "0.3.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",
@@ -16,14 +16,17 @@
     "dist"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^0.18.0"
+    "@tangle-network/agent-interface": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "25.6.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }