@tangle-network/agent-profile-materialize 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -28,6 +28,26 @@ export interface PlanFile {
     content: string;
     /** chmod mode (e.g. 0o755 for hook scripts); default 0o644. */
     mode?: number;
+    /**
+     * Provenance of this entry. `"generated"` = the materializer synthesized the
+     * content itself (native harness config, merged settings, lowered prompt/MCP/
+     * hooks/subagents). `"user"` = the exact bytes of a profile-declared resource
+     * ref (`resources.files`/`tools`/`agents`/`skills`/`commands`), passed through
+     * verbatim at the path the profile author chose.
+     *
+     * A consumer that needs to reinterpret a SPECIFIC generated file (e.g. parse
+     * `opencode.json` as the synthetic native config) MUST gate on
+     * `source === "generated"` at that relPath — matching by relPath alone cannot
+     * tell a harness-authored config apart from a user resource mount that
+     * happens to share the same conventional path, and treating arbitrary user
+     * content as trusted generated config is a fail-open bug, not a fallback.
+     *
+     * Optional: callers that hand-construct a {@link WorkspacePlan} directly for
+     * {@link applyWorkspacePlan} (tests, ad hoc writes) are not materializer
+     * output and have no provenance to report. `materializeProfile` always sets
+     * this on every file it emits.
+     */
+    source?: "user" | "generated";
 }
 export interface Unsupported {
     dimension: "files" | "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "connections" | "confidential" | "permissions" | "tools" | "modes" | "extensions";
@@ -74,6 +94,15 @@ export interface ApplyWorkspacePlanOptions {
 }
 /** 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.
@@ -99,6 +128,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;
@@ -154,6 +219,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

@@ -25,15 +25,32 @@ import { createHash, randomUUID } from "node:crypto";
 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";
+function describeUnresolvedRef(r) {
+    const name = typeof r.name === "string" ? r.name : undefined;
+    const path = typeof r.path === "string" ? r.path : undefined;
+    if (name && path)
+        return `"${name}" (${path})`;
+    if (name)
+        return `"${name}"`;
+    if (path)
+        return `"${path}"`;
+    return "resource";
+}
 /** Resolve inline bytes already present on the profile. Remote resources must
- * be resolved by {@link resolveAgentProfileResources} before materialization. */
+ * be resolved by {@link resolveAgentProfileResources} before materialization.
+ *
+ * FAIL-CLOSED: a ref that declares `kind: "inline"` is asserting its bytes are
+ * already resolved, so missing/non-string `content` is a caller bug, not an
+ * empty file — silently coercing it (`String(content ?? "")`) would produce a
+ * file that "looks provisioned, loads nothing", exactly the trap this module's
+ * docstring warns against. */
 function resolveInlineRef(ref) {
     const r = ref;
-    if (r.kind === "inline" || typeof r.content === "string") {
-        return {
-            name: String(r.name ?? r.path ?? "resource"),
-            content: String(r.content ?? ""),
-        };
+    if (typeof r.content === "string") {
+        return { name: String(r.name ?? r.path ?? "resource"), content: r.content };
+    }
+    if (r.kind === "inline") {
+        throw new Error(`Profile resource ${describeUnresolvedRef(r)} declares kind "inline" but has no string content`);
     }
     return null; // github / unresolved
 }
@@ -54,7 +71,52 @@ export function assertWorkspacePlanSupported(plan) {
         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",
@@ -70,8 +132,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",
@@ -85,6 +154,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";
@@ -360,14 +441,23 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
         flags: [],
         unsupported: [],
     };
-    const add = (relPath, content, mode) => {
+    // Every plan file is tagged by provenance at the single push site: `add`
+    // (harness-generated native config) vs `addExplicitResource` (a profile
+    // resource ref's bytes, passed through verbatim). Downstream consumers that
+    // reinterpret a specific generated file by relPath (e.g. opencode.json as
+    // the synthetic native config) must gate on `source === "generated"` —
+    // otherwise a user resource mounted at the same conventional path is
+    // silently misread as trusted harness config.
+    const pushPlanFile = (relPath, content, source, mode) => {
         const normalizedPath = normalizeWorkspaceRelativePath(relPath);
         plan.files.push({
             relPath: normalizedPath,
             content,
+            source,
             ...(mode === undefined ? {} : { mode: validateFileMode(mode) }),
         });
     };
+    const add = (relPath, content, mode) => pushPlanFile(relPath, content, "generated", mode);
     const unsupported = (dimension, reason) => plan.unsupported.push({ dimension, reason });
     const explicitResourcePaths = new Map();
     const addExplicitResource = (dimension, relPath, content, mode) => {
@@ -377,7 +467,7 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
             throw new Error(`Duplicate profile resource path: ${normalizedPath} (${previousDimension}, ${dimension})`);
         }
         explicitResourcePaths.set(normalizedPath, dimension);
-        add(normalizedPath, content, mode);
+        pushPlanFile(normalizedPath, content, "user", mode);
     };
     // 1) GENERIC FILES → exact workspace-relative paths. Inline refs are
     // deterministic; remote refs must be resolved by an async caller first.
@@ -1310,33 +1400,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);
@@ -1350,7 +1445,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.1",
+  "version": "0.7.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.32.0"
   },
   "devDependencies": {
     "@types/node": "25.6.0",