@tangle-network/agent-profile-materialize 0.26.8 → 0.27.0

package/dist/index.d.ts

@@ -27,3 +27,4 @@ export type { ResolveAgentProfileResourcesOptions } from "./resource-resolution.
 export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";
 export { prepareSecretConcurrentProfileRevision } from "./secret-concurrent-revision.js";
 export * from "./secret-session-view.js";
+export * from "./tool-bin-path.js";

package/dist/index.js

@@ -21,3 +21,4 @@ export * from "./profile-start-check.js";
 export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";
 export { prepareSecretConcurrentProfileRevision } from "./secret-concurrent-revision.js";
 export * from "./secret-session-view.js";
+export * from "./tool-bin-path.js";

package/dist/managed-workspace-bind.js

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 /**
  * Paths a secret OpenCode revision serves from its own immutable tree:
  * read-only profile content under `reference/`, skills, and OpenCode's
@@ -88,9 +88,19 @@ export function bindConcurrentLaunch(plan, application, revisionWorkspaceDir, op
             break;
         }
     }
+    // A declared executable reference/ tool runs from the immutable revision:
+    // its directory, absolute in that revision, joins the launch PATH.
+    const toolBinDirs = [];
     for (const file of plan.files) {
-        if (ridesSecretRevision(plan, file, options))
+        if (ridesSecretRevision(plan, file, options)) {
+            if (file.relPath.startsWith("reference/") &&
+                ((file.mode ?? 0) & 0o111) !== 0) {
+                const dir = join(revisionWorkspaceDir, dirname(file.relPath));
+                if (!toolBinDirs.includes(dir))
+                    toolBinDirs.push(dir);
+            }
             continue;
+        }
         if (file.source !== "generated") {
             throw new Error(`Concurrent ${plan.harness} profile resource ${file.relPath} needs a shared-workspace collision-safe copy`);
         }
@@ -104,5 +114,10 @@ export function bindConcurrentLaunch(plan, application, revisionWorkspaceDir, op
             throw new Error(`Concurrent ${plan.harness} profile cannot bind runtime-only file ${name}`);
         }
     }
-    return { ...application.spawn, flags, env };
+    return {
+        ...application.spawn,
+        flags,
+        env,
+        ...(toolBinDirs.length > 0 ? { toolBinDirs } : {}),
+    };
 }

package/dist/plan-types.d.ts

@@ -284,6 +284,13 @@ export interface WorkspacePlanSpawnInputs {
     appendSystemPrompt?: string;
     /** Read it with {@link takeSystemPromptBinding}, which refuses a foreign control. */
     systemPromptBinding?: WorkspacePlanSystemPromptBinding;
+    /**
+     * Absolute dirs of the profile's declared executable `reference/` tools in
+     * the immutable revision the launch runs from. The provider puts them on
+     * the launch PATH in place of the app's own tool dirs (bindLaunchToolBinDirs),
+     * so a profile names its CLI bare.
+     */
+    toolBinDirs?: string[];
 }
 /** Result of applying a public plan at the private executor boundary. */
 export interface WorkspacePlanApplication {

package/dist/secret-session-view.d.ts

@@ -13,11 +13,17 @@ export declare function secretSessionViewWorkspace(input: {
 }): string;
 /**
  * Point a session's view at one published secret revision before the
- * session's turn runs. The view's `reference/` becomes a fresh tree of hard
- * links to the revision's read-only files (the same inodes, owner, mode and
- * ACL), so the session reads this turn's files and nothing the previous
- * revision held. The view holds nothing else, so OpenCode's config search
- * finds no config there; profile config stays bound by absolute path.
+ * session's turn runs. The view's `reference/` and `.opencode/skills/` become
+ * fresh trees of hard links to the revision's read-only files (the same
+ * inodes, owner, mode and ACL), so the session reads this turn's files and
+ * skills and nothing the previous revision held. A product's skill index
+ * names `.opencode/skills/<id>/SKILL.md` cwd-relative, and OpenCode's skill
+ * tool lists the same files through the revision's config directory.
+ *
+ * The view holds nothing else: no `opencode.json`, and a `.opencode/` with
+ * only the revision's digest-attested skills, which the launch does not load
+ * as project config (it sets OPENCODE_DISABLE_PROJECT_CONFIG). Profile config
+ * stays bound by absolute path.
  *
  * The swap is not atomic for a reader that is already running: the caller
  * runs one turn of a session at a time and binds before that turn spawns.

package/dist/secret-session-view.js

@@ -1,10 +1,22 @@
 import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, linkSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { HARNESS_SKILL_DIRS } from "./harness.js";
 import { assertLaunchRoot } from "./managed-workspace.js";
 import { runSetfacl } from "./secret-concurrent-revision.js";
-/** The only cwd-relative content a secret OpenCode revision serves. */
-const VIEW_ENTRY = "reference";
+/** The profile's read-only files, which products name cwd-relative. */
+const REFERENCE_ENTRY = "reference";
+/**
+ * The profile's mounted skills, at the cwd-relative directory the platform
+ * publishes for products to name in their prompts (`.opencode/skills`).
+ */
+const SKILLS_DIR = HARNESS_SKILL_DIRS.opencode;
+const SKILLS_ENTRY = dirname(SKILLS_DIR);
+/** The only cwd-relative content a secret OpenCode session view serves. */
+const VIEW_ENTRIES = new Set([
+    REFERENCE_ENTRY,
+    SKILLS_ENTRY,
+]);
 /**
  * The stable, sealed cwd of one secret OpenCode session. OpenCode reopens a
  * native session at the directory it was created in, so a session resumed on
@@ -27,11 +39,17 @@ export function secretSessionViewWorkspace(input) {
 }
 /**
  * Point a session's view at one published secret revision before the
- * session's turn runs. The view's `reference/` becomes a fresh tree of hard
- * links to the revision's read-only files (the same inodes, owner, mode and
- * ACL), so the session reads this turn's files and nothing the previous
- * revision held. The view holds nothing else, so OpenCode's config search
- * finds no config there; profile config stays bound by absolute path.
+ * session's turn runs. The view's `reference/` and `.opencode/skills/` become
+ * fresh trees of hard links to the revision's read-only files (the same
+ * inodes, owner, mode and ACL), so the session reads this turn's files and
+ * skills and nothing the previous revision held. A product's skill index
+ * names `.opencode/skills/<id>/SKILL.md` cwd-relative, and OpenCode's skill
+ * tool lists the same files through the revision's config directory.
+ *
+ * The view holds nothing else: no `opencode.json`, and a `.opencode/` with
+ * only the revision's digest-attested skills, which the launch does not load
+ * as project config (it sets OPENCODE_DISABLE_PROJECT_CONFIG). Profile config
+ * stays bound by absolute path.
  *
  * The swap is not atomic for a reader that is already running: the caller
  * runs one turn of a session at a time and binds before that turn spawns.
@@ -61,32 +79,57 @@ export function bindSecretSessionView(input) {
             throw new Error("Secret session view is not an executor-owned directory");
         }
     }
-    if (readdirSync(viewWorkspaceDir).some((name) => name !== VIEW_ENTRY)) {
+    if (readdirSync(viewWorkspaceDir).some((name) => !VIEW_ENTRIES.has(name))) {
         throw new Error("Secret session view holds an unexpected entry");
     }
     // Only this function writes a view. An interrupted bind leaves a staged or
     // retired tree beside `workspace`, never inside it.
     clearBesideWorkspace(viewRoot);
-    const source = join(revisionWorkspaceDir, VIEW_ENTRY);
-    const sourceStat = lstatIfPresent(source);
-    let staged;
-    if (sourceStat) {
-        if (!isSealedNode(sourceStat, "directory")) {
-            throw new Error("Secret revision reference/ is not sealed");
-        }
-        staged = join(viewRoot, `.stage-${randomBytes(8).toString("hex")}`);
-        const directories = linkSealedTree(source, staged);
+    const staged = new Map();
+    const reference = sealedRevisionDirectory(revisionWorkspaceDir, REFERENCE_ENTRY);
+    if (reference) {
+        const target = besideWorkspace(viewRoot, "stage");
+        sealDirectories(linkSealedTree(reference, target), input.subprocessUid);
+        staged.set(REFERENCE_ENTRY, target);
+    }
+    const skills = sealedRevisionDirectory(revisionWorkspaceDir, SKILLS_DIR);
+    if (skills) {
+        const target = besideWorkspace(viewRoot, "stage");
+        mkdirSync(target, { mode: 0o700 });
+        const directories = [
+            target,
+            ...linkSealedTree(skills, join(target, basename(SKILLS_DIR))),
+        ];
         sealDirectories(directories, input.subprocessUid);
+        staged.set(SKILLS_ENTRY, target);
     }
-    const current = join(viewWorkspaceDir, VIEW_ENTRY);
-    if (lstatIfPresent(current)) {
-        renameSync(current, join(viewRoot, `.retired-${randomBytes(8).toString("hex")}`));
+    for (const entry of VIEW_ENTRIES) {
+        const current = join(viewWorkspaceDir, entry);
+        if (lstatIfPresent(current)) {
+            renameSync(current, besideWorkspace(viewRoot, "retired"));
+        }
+        const next = staged.get(entry);
+        if (next)
+            renameSync(next, current);
     }
-    if (staged)
-        renameSync(staged, current);
     clearBesideWorkspace(viewRoot);
     sealDirectories([viewRoot, viewWorkspaceDir], input.subprocessUid);
 }
+/** A sealed directory of the published revision, or undefined when absent. */
+function sealedRevisionDirectory(revisionWorkspaceDir, relPath) {
+    const source = join(revisionWorkspaceDir, relPath);
+    const stat = lstatIfPresent(source);
+    if (!stat)
+        return undefined;
+    if (!isSealedNode(stat, "directory")) {
+        throw new Error(`Secret revision ${relPath}/ is not sealed`);
+    }
+    return source;
+}
+/** A fresh staged or retired path beside the view's `workspace`. */
+function besideWorkspace(viewRoot, kind) {
+    return join(viewRoot, `.${kind}-${randomBytes(8).toString("hex")}`);
+}
 function isLaunchWorkspace(launchRoot, workspace, name) {
     return (basename(workspace) === "workspace" &&
         dirname(dirname(workspace)) === launchRoot &&

package/dist/tool-bin-path.d.ts

@@ -0,0 +1,23 @@
+/** The colon-separated, absolute CLI bin dirs a sandbox app mounts for its tools. */
+export declare const SANDBOX_TOOL_BIN_DIRS_ENV = "SANDBOX_TOOL_BIN_DIRS";
+/**
+ * The tool bin dirs a `SANDBOX_TOOL_BIN_DIRS` value names, or `[]` when it is
+ * unset or blank.
+ *
+ * Fail loud, never silently degrade: a malformed value (a relative segment,
+ * or an empty segment from a stray/leading/trailing colon) throws rather than
+ * silently dropping a tool dir from PATH or admitting a relative path that
+ * resolves against whatever the process cwd happens to be.
+ */
+export declare function parseSandboxToolBinDirs(value: string | undefined): string[];
+/**
+ * A launch environment whose tool bin dirs are `toolBinDirs`, at the TAIL of
+ * PATH after every Nix, npm, image and system entry, so a tool never shadows
+ * a platform-owned binary of the same name.
+ *
+ * They replace `appToolBinDirs` (by default the dirs the environment's own
+ * `SANDBOX_TOOL_BIN_DIRS` names) wherever those sit in PATH, so an app's older
+ * copy of the same tool cannot win by PATH order. Relative PATH entries are
+ * dropped too: they resolve against whatever cwd the turn moves to.
+ */
+export declare function bindLaunchToolBinDirs(env: Readonly<Record<string, string | undefined>>, toolBinDirs: readonly string[], appToolBinDirs?: readonly string[]): Record<string, string | undefined>;

package/dist/tool-bin-path.js

@@ -0,0 +1,61 @@
+import { isAbsolute } from "node:path";
+/** The colon-separated, absolute CLI bin dirs a sandbox app mounts for its tools. */
+export const SANDBOX_TOOL_BIN_DIRS_ENV = "SANDBOX_TOOL_BIN_DIRS";
+/**
+ * The tool bin dirs a `SANDBOX_TOOL_BIN_DIRS` value names, or `[]` when it is
+ * unset or blank.
+ *
+ * Fail loud, never silently degrade: a malformed value (a relative segment,
+ * or an empty segment from a stray/leading/trailing colon) throws rather than
+ * silently dropping a tool dir from PATH or admitting a relative path that
+ * resolves against whatever the process cwd happens to be.
+ */
+export function parseSandboxToolBinDirs(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return [];
+    const segments = trimmed.split(":");
+    for (const segment of segments) {
+        if (!segment || !isAbsolute(segment)) {
+            throw new Error(`SANDBOX_TOOL_BIN_DIRS must be a colon-separated list of absolute paths with no empty segments, got: ${trimmed}`);
+        }
+    }
+    return segments;
+}
+function assertToolBinDir(dir) {
+    // A ':' would split one declared dir into several PATH entries, admitting
+    // a dir no profile declared.
+    if (!dir || !isAbsolute(dir) || dir.includes(":")) {
+        throw new Error(`a tool bin dir must be an absolute path without ':', got: ${dir}`);
+    }
+}
+/**
+ * A launch environment whose tool bin dirs are `toolBinDirs`, at the TAIL of
+ * PATH after every Nix, npm, image and system entry, so a tool never shadows
+ * a platform-owned binary of the same name.
+ *
+ * They replace `appToolBinDirs` (by default the dirs the environment's own
+ * `SANDBOX_TOOL_BIN_DIRS` names) wherever those sit in PATH, so an app's older
+ * copy of the same tool cannot win by PATH order. Relative PATH entries are
+ * dropped too: they resolve against whatever cwd the turn moves to.
+ */
+export function bindLaunchToolBinDirs(env, toolBinDirs, appToolBinDirs = parseSandboxToolBinDirs(env[SANDBOX_TOOL_BIN_DIRS_ENV])) {
+    for (const dir of toolBinDirs)
+        assertToolBinDir(dir);
+    const dirs = [...new Set(toolBinDirs)];
+    // No PATH to bind: the spawner appends SANDBOX_TOOL_BIN_DIRS to its default.
+    if (env.PATH === undefined) {
+        return { ...env, [SANDBOX_TOOL_BIN_DIRS_ENV]: dirs.join(":") };
+    }
+    const replaced = new Set(appToolBinDirs);
+    const entries = env.PATH.split(":").filter((entry) => isAbsolute(entry) && !replaced.has(entry));
+    for (const dir of dirs) {
+        if (!entries.includes(dir))
+            entries.push(dir);
+    }
+    return {
+        ...env,
+        PATH: entries.join(":"),
+        [SANDBOX_TOOL_BIN_DIRS_ENV]: dirs.join(":"),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.26.8",
+  "version": "0.27.0",
   "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-container, and VB).",
   "type": "module",
   "repository": {
@@ -35,8 +35,8 @@
     "@tangle-network/agent-interface": "^3.0.0 || ^4.0.0 || ^5.0.0"
   },
   "tangleRelease": {
-    "sourceSha": "7e2d74fda45cf4ac0c3216dd88b9beef0fa96f99",
-    "mergedAt": "2026-10-19T21:48:18-06:00"
+    "sourceSha": "f4c8596359a591a5139a8180fba415239536202c",
+    "mergedAt": "2026-10-20T13:35:56-06:00"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",