@tangle-network/agent-profile-materialize 0.26.9 → 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/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.9",
+  "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": "be89262c7e1faaedf04926a27d0ecbf17d91a318",
-    "mergedAt": "2026-10-19T23:54:34-06:00"
+    "sourceSha": "f4c8596359a591a5139a8180fba415239536202c",
+    "mergedAt": "2026-10-20T13:35:56-06:00"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",