@tangle-network/agent-profile-materialize 0.6.0 → 0.8.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";

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
 }
@@ -424,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) => {
@@ -441,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.6.0",
+  "version": "0.8.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.31.0"
+    "@tangle-network/agent-interface": "0.33.0"
   },
   "devDependencies": {
     "@types/node": "25.6.0",