@tangle-network/agent-profile-materialize 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -60,12 +60,29 @@ export interface WorkspacePlanReceipt {
     unsupported: Unsupported[];
     written: string[];
 }
+/** The plan was applied, but one or more private staging files remain. */
+export declare class WorkspacePlanCleanupError extends AggregateError {
+    readonly receipt: WorkspacePlanReceipt;
+    readonly temporaryPaths: readonly string[];
+    constructor(errors: readonly unknown[], receipt: WorkspacePlanReceipt, temporaryPaths: readonly string[]);
+}
 export interface ApplyWorkspacePlanOptions {
     /** Plan files consumed in memory by the runtime and never persisted to cwd. */
     runtimeOnlyFiles?: readonly string[];
+    /** Existing workspace paths are either exact idempotent inputs or forbidden. */
+    existingFiles?: "allow-identical" | "reject";
 }
 /** Fail when a profile asks for controls the chosen harness cannot execute. */
 export declare function assertWorkspacePlanSupported(plan: Pick<WorkspacePlan, "unsupported">): void;
+/**
+ * Enforce plan supportability under the profile's `resources.failOnError`
+ * policy. Strict by default: `failOnError` absent or `true` throws on any
+ * unsupported dimension. An explicitly best-effort profile
+ * (`failOnError: false`) materializes the supported subset instead; the
+ * returned `"dimension: reason"` entries are what the caller must surface
+ * as a warning so the skipped dimensions stay visible to operators.
+ */
+export declare function enforceWorkspacePlanSupport(plan: Pick<WorkspacePlan, "unsupported">, failOnError: boolean | undefined): string[];
 /**
  * Candidate-safe workspace plan. Spawn values remain typed until the runtime
  * resolves them; the materializer never joins argv into a shell command.
@@ -91,6 +108,42 @@ export interface MaterializeCandidateProfileOptions {
     /** Exact text fetched from pinned resource refs, keyed by declared SHA-256. */
     resolvedResources?: ReadonlyMap<Sha256Digest, string>;
 }
+/**
+ * Whether the harness LOADS its {@link CONTEXT_FILE} from cwd on its own.
+ *
+ * True for every harness whose CLI discovers the file by name (CLAUDE.md,
+ * AGENTS.md, …). opencode is the exception: it reads only what its
+ * `opencode.json` `instructions[]` names, so a caller writing context for
+ * opencode must register the path as well as write it — see the `instructions`
+ * lowering below, and the interactive TUI's persona fold.
+ */
+export declare function harnessAutoLoadsContextFile(harness: HarnessId): boolean;
+/**
+ * The project context file this harness reads from cwd — its stable, documented
+ * ALWAYS-LOADED surface. Exported so a caller lowering additive context (e.g. a
+ * bare TUI's persona, which has no per-message system channel) targets the same
+ * file the materializer writes instructions to, instead of keeping its own copy
+ * of this per-harness map.
+ */
+export declare function harnessContextFile(harness: HarnessId): string;
+/**
+ * cwd-relative native skill dir per harness, or null if the harness has no
+ * cwd skill primitive (skills live in a user/global dir the workspace plan
+ * cannot reach). Public so consumers composing a profile can (a) render the
+ * exact path the platform will mount a skill at into their prompts instead
+ * of hardcoding `~/.claude/skills/...`, and (b) branch on skill support
+ * ahead of materialization instead of catching the materialize-time throw.
+ */
+export declare const HARNESS_SKILL_DIRS: Readonly<Record<HarnessId, string | null>>;
+/**
+ * Resolve the cwd-relative directory `resources.skills` refs materialize
+ * into on `harness` (after alias canonicalization: claude/claudish →
+ * claude-code, kimi → kimi-code). `null` means the harness cannot receive
+ * cwd skills — the same condition that surfaces as an `unsupported`
+ * "skills" entry (and an {@link assertWorkspacePlanSupported} throw) at
+ * materialize time, exposed here as branchable data.
+ */
+export declare function skillDirForHarness(harness: HarnessId): string | null;
 export interface ResolveAgentProfileResourcesOptions {
     /** Repository used when a GitHub resource omits its own `repository`. */
     repository?: string;
@@ -146,6 +199,10 @@ export declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWor
  * agent-dev-container box, and VB. Returns `unsupported` so the caller can log/fail.
  */
 export declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string, options?: ApplyWorkspacePlanOptions): WorkspacePlanReceipt;
+/** Tool IDs reported by the OpenCode binary shipped in the Sandbox image. */
+export declare const OPENCODE_NATIVE_TOOL_IDS: readonly ["apply_patch", "bash", "codesearch", "edit", "glob", "grep", "question", "read", "skill", "task", "todowrite", "webfetch", "websearch", "write"];
+/** Resolve portable and legacy profile names to current OpenCode tool IDs. */
+export declare function openCodeNativeToolId(name: string): string | undefined;
 /** OpenCode-native MCP configuration used by workspace and startup paths. */
 export type OpenCodeMcpConfig = Record<string, {
     type: "remote";

package/dist/index.js

@@ -22,7 +22,7 @@
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, fchmodSync, constants as fsConstants, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
 import { agentCandidateProfileActivationSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, agentProfileSchema, canonicalCandidateBytes, canonicalCandidateDigest, resolveNativeWebTools, } from "@tangle-network/agent-interface";
 /** Resolve inline bytes already present on the profile. Remote resources must
@@ -37,13 +37,69 @@ function resolveInlineRef(ref) {
     }
     return null; // github / unresolved
 }
+/** The plan was applied, but one or more private staging files remain. */
+export class WorkspacePlanCleanupError extends AggregateError {
+    receipt;
+    temporaryPaths;
+    constructor(errors, receipt, temporaryPaths) {
+        super(errors, "Applied workspace plan but failed to remove temporary files");
+        this.name = "WorkspacePlanCleanupError";
+        this.receipt = receipt;
+        this.temporaryPaths = Object.freeze([...temporaryPaths]);
+    }
+}
 /** Fail when a profile asks for controls the chosen harness cannot execute. */
 export function assertWorkspacePlanSupported(plan) {
     if (plan.unsupported.length > 0) {
         throw new Error(formatUnsupported(plan.unsupported));
     }
 }
+/**
+ * Enforce plan supportability under the profile's `resources.failOnError`
+ * policy. Strict by default: `failOnError` absent or `true` throws on any
+ * unsupported dimension. An explicitly best-effort profile
+ * (`failOnError: false`) materializes the supported subset instead; the
+ * returned `"dimension: reason"` entries are what the caller must surface
+ * as a warning so the skipped dimensions stay visible to operators.
+ */
+export function enforceWorkspacePlanSupport(plan, failOnError) {
+    if (failOnError === false) {
+        return plan.unsupported.map(({ dimension, reason }) => `${dimension}: ${reason}`);
+    }
+    assertWorkspacePlanSupported(plan);
+    return [];
+}
 // ─── Verified per-harness conventions (capability matrix) ───────────────────
+/**
+ * Whether the harness LOADS its {@link CONTEXT_FILE} from cwd on its own.
+ *
+ * True for every harness whose CLI discovers the file by name (CLAUDE.md,
+ * AGENTS.md, …). opencode is the exception: it reads only what its
+ * `opencode.json` `instructions[]` names, so a caller writing context for
+ * opencode must register the path as well as write it — see the `instructions`
+ * lowering below, and the interactive TUI's persona fold.
+ */
+export function harnessAutoLoadsContextFile(harness) {
+    return canonicalHarness(harness) !== "opencode";
+}
+/**
+ * The project context file this harness reads from cwd — its stable, documented
+ * ALWAYS-LOADED surface. Exported so a caller lowering additive context (e.g. a
+ * bare TUI's persona, which has no per-message system channel) targets the same
+ * file the materializer writes instructions to, instead of keeping its own copy
+ * of this per-harness map.
+ */
+export function harnessContextFile(harness) {
+    // The map is keyed by HarnessId, but callers reach this from runtime strings
+    // (a registry spec name, a request field). A miss would otherwise return
+    // undefined behind a `string` return type and surface as an undefined write
+    // path much later.
+    const path = CONTEXT_FILE[canonicalHarness(harness)];
+    if (!path) {
+        throw new Error(`No project context file is known for harness "${harness}"`);
+    }
+    return path;
+}
 /** Project context file each harness actually reads from cwd. NEVER a constant. */
 const CONTEXT_FILE = {
     "claude-code": "CLAUDE.md",
@@ -59,8 +115,15 @@ const CONTEXT_FILE = {
     hermes: "HERMES.md", // highest-priority native name; only ONE context loads (first match)
     openclaw: "AGENTS.md",
 };
-/** cwd-relative native skill dir, or null if the harness has no cwd skill primitive. */
-const SKILL_DIR = {
+/**
+ * cwd-relative native skill dir per harness, or null if the harness has no
+ * cwd skill primitive (skills live in a user/global dir the workspace plan
+ * cannot reach). Public so consumers composing a profile can (a) render the
+ * exact path the platform will mount a skill at into their prompts instead
+ * of hardcoding `~/.claude/skills/...`, and (b) branch on skill support
+ * ahead of materialization instead of catching the materialize-time throw.
+ */
+export const HARNESS_SKILL_DIRS = {
     "claude-code": ".claude/skills",
     claude: ".claude/skills",
     claudish: ".claude/skills",
@@ -74,6 +137,18 @@ const SKILL_DIR = {
     hermes: null, // skills are ~/.hermes/skills (user) only — no cwd discovery
     openclaw: "skills", // <workspace>/skills/<name>/SKILL.md
 };
+const SKILL_DIR = HARNESS_SKILL_DIRS;
+/**
+ * Resolve the cwd-relative directory `resources.skills` refs materialize
+ * into on `harness` (after alias canonicalization: claude/claudish →
+ * claude-code, kimi → kimi-code). `null` means the harness cannot receive
+ * cwd skills — the same condition that surfaces as an `unsupported`
+ * "skills" entry (and an {@link assertWorkspacePlanSupported} throw) at
+ * materialize time, exposed here as branchable data.
+ */
+export function skillDirForHarness(harness) {
+    return HARNESS_SKILL_DIRS[canonicalHarness(harness)];
+}
 function canonicalHarness(h) {
     if (h === "claude" || h === "claudish")
         return "claude-code";
@@ -952,6 +1027,10 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
 export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
     const workspaceRoot = resolve(workspaceDir);
     const runtimeOnlyFiles = new Set((options.runtimeOnlyFiles ?? []).map(normalizeWorkspaceRelativePath));
+    const existingFiles = options.existingFiles ?? "allow-identical";
+    if (existingFiles !== "allow-identical" && existingFiles !== "reject") {
+        throw new Error(`Unsupported existing workspace file policy: ${existingFiles}`);
+    }
     const files = normalizePlanFiles(plan.files)
         .filter((file) => !runtimeOnlyFiles.has(file.relPath))
         .map((file) => ({
@@ -962,24 +1041,77 @@ export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
     // existing symlink cannot leave a partially materialized workspace.
     for (const file of files) {
         assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
-        if (workspaceFileExists(file.absPath) && !workspaceFileMatches(file)) {
+        if (workspaceFileExists(file.absPath) &&
+            (existingFiles === "reject" || !workspaceFileMatches(file))) {
             throw new Error(`Refusing to replace existing workspace file: ${file.relPath}`);
         }
     }
+    // Parent directories remain on failure because they may contain concurrent
+    // workspace state that this call does not own.
     for (const file of files) {
         mkdirSync(dirname(file.absPath), { recursive: true });
     }
     for (const file of files) {
         assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
     }
-    const written = [];
-    for (const file of files) {
-        if (!workspaceFileExists(file.absPath)) {
-            writeWorkspaceFile(workspaceRoot, file);
+    const prepared = [];
+    // Prepared temp links stay alive through publication and rollback. Their
+    // inodes distinguish files created here from concurrent replacements.
+    try {
+        for (const file of files) {
+            if (existingFiles === "allow-identical" &&
+                workspaceFileExists(file.absPath) &&
+                workspaceFileMatches(file)) {
+                continue;
+            }
+            prepared.push(prepareWorkspaceFile(workspaceRoot, file));
+        }
+        for (const entry of prepared) {
+            assertNoSymlinkPathComponents(workspaceRoot, entry.file.absPath);
+            try {
+                linkSync(entry.temporaryPath, entry.file.absPath);
+                entry.published = true;
+            }
+            catch (error) {
+                if (isFsError(error, "EEXIST") &&
+                    existingFiles === "allow-identical" &&
+                    workspaceFileMatches(entry.file)) {
+                    continue;
+                }
+                if (isFsError(error, "EEXIST")) {
+                    throw new Error(`Refusing to replace existing workspace file: ${entry.file.relPath}`, { cause: error });
+                }
+                throw error;
+            }
         }
-        written.push(file.relPath);
     }
-    return {
+    catch (error) {
+        const cleanupErrors = [];
+        for (const entry of [...prepared].reverse()) {
+            try {
+                if (entry.published &&
+                    workspacePathHasIdentity(entry.file.absPath, entry.identity)) {
+                    unlinkSync(entry.file.absPath);
+                }
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            try {
+                if (workspacePathHasIdentity(entry.temporaryPath, entry.identity)) {
+                    unlinkSync(entry.temporaryPath);
+                }
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError([error, ...cleanupErrors], "Failed to apply workspace plan and roll back published files");
+        }
+        throw error;
+    }
+    const receipt = {
         workspacePlanDigest: hashWorkspacePlan(plan),
         env: plan.env,
         flags: plan.flags,
@@ -987,8 +1119,25 @@ export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
             ? {}
             : { systemPrompt: plan.systemPrompt }),
         unsupported: plan.unsupported,
-        written,
+        written: files.map((file) => file.relPath),
     };
+    const cleanupErrors = [];
+    const temporaryPaths = [];
+    for (const entry of prepared) {
+        try {
+            unlinkSync(entry.temporaryPath);
+        }
+        catch (error) {
+            if (!isFsError(error, "ENOENT")) {
+                cleanupErrors.push(error);
+                temporaryPaths.push(entry.temporaryPath);
+            }
+        }
+    }
+    if (cleanupErrors.length > 0) {
+        throw new WorkspacePlanCleanupError(cleanupErrors, receipt, temporaryPaths);
+    }
+    return receipt;
 }
 function workspaceFileExists(pathValue) {
     try {
@@ -1007,6 +1156,59 @@ function workspaceFileMatches(file) {
         (stats.mode & 0o777) === file.mode &&
         readFileSync(file.absPath, "utf8") === file.content);
 }
+function prepareWorkspaceFile(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);
+        const stats = fstatSync(descriptor);
+        const descriptorToClose = descriptor;
+        descriptor = undefined;
+        closeSync(descriptorToClose);
+        return {
+            file,
+            temporaryPath,
+            identity: { device: stats.dev, inode: stats.ino },
+            published: false,
+        };
+    }
+    catch (error) {
+        const cleanupErrors = [];
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+        }
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch (cleanupError) {
+            if (!isFsError(cleanupError, "ENOENT"))
+                cleanupErrors.push(cleanupError);
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError([error, ...cleanupErrors], `Failed to prepare workspace file: ${file.relPath}`);
+        }
+        throw error;
+    }
+}
+function workspacePathHasIdentity(pathValue, identity) {
+    try {
+        const stats = lstatSync(pathValue);
+        return stats.dev === identity.device && stats.ino === identity.inode;
+    }
+    catch (error) {
+        if (isFsError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
 function resolveWorkspaceFilePath(workspaceRoot, relativePath) {
     const targetPath = resolve(workspaceRoot, ...relativePath.split("/"));
     const targetRelativePath = relative(workspaceRoot, targetPath);
@@ -1046,40 +1248,6 @@ function assertNoSymlinkPathComponents(workspaceRoot, targetPath) {
         }
     }
 }
-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);
-        try {
-            linkSync(temporaryPath, file.absPath);
-        }
-        catch (error) {
-            if (!isFsError(error, "EEXIST") || !workspaceFileMatches(file)) {
-                throw error;
-            }
-        }
-        unlinkSync(temporaryPath);
-    }
-    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 &&
@@ -1206,33 +1374,38 @@ function claudeToolName(name) {
         return "WebFetch";
     return CLAUDE_TOOL_NAMES[normalizedControlName(name)];
 }
-const OPENCODE_TOOL_NAMES = new Set([
+/** Tool IDs reported by the OpenCode binary shipped in the Sandbox image. */
+export const OPENCODE_NATIVE_TOOL_IDS = [
+    "apply_patch",
     "bash",
-    "batch",
     "codesearch",
     "edit",
     "glob",
     "grep",
-    "list",
-    "lsp",
-    "multiedit",
-    "patch",
+    "question",
     "read",
+    "skill",
     "task",
-    "todoread",
     "todowrite",
     "webfetch",
     "websearch",
     "write",
-]);
-function openCodeToolName(name) {
+];
+const OPENCODE_NATIVE_TOOL_ID_SET = new Set(OPENCODE_NATIVE_TOOL_IDS);
+/** Resolve portable and legacy profile names to current OpenCode tool IDs. */
+export function openCodeNativeToolId(name) {
     const web = nativeWebToolKind(name);
     if (web === "search")
         return "websearch";
     if (web === "fetch")
         return "webfetch";
     const normalized = normalizedControlName(name);
-    return OPENCODE_TOOL_NAMES.has(normalized) ? normalized : undefined;
+    if (normalized === "patch")
+        return "apply_patch";
+    return OPENCODE_NATIVE_TOOL_ID_SET.has(normalized) ? normalized : undefined;
+}
+function openCodeToolName(name) {
+    return openCodeNativeToolId(name);
 }
 function openCodePermissionName(name) {
     const normalized = normalizedControlName(name);
@@ -1246,7 +1419,7 @@ function openCodePermissionName(name) {
     if (["bash", "mcp", "doom_loop", "external_directory"].includes(normalized)) {
         return normalized;
     }
-    return normalized !== "read" && OPENCODE_TOOL_NAMES.has(normalized)
+    return normalized !== "read" && OPENCODE_NATIVE_TOOL_ID_SET.has(normalized)
         ? normalized
         : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.5.0",
+  "version": "0.6.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,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.30.0"
+    "@tangle-network/agent-interface": "0.31.0"
   },
   "devDependencies": {
     "@types/node": "25.6.0",