@tangle-network/agent-profile-materialize 0.22.3 → 0.23.0

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export type { PrimeProfileErrorKind, PrimeThinkingLevel, } from "./prime-fork.js
 export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_FORK_INSTALL, PRIME_FORK_PIN, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PrimeHarnessStateError, PrimeProfileError, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
 export type { PrimeProfileControls, PrimeProfileSkill, PrimeProfileSubagent, } from "./prime-profile.js";
 export { assertPrimeModelAgreement, hasPrimeProfileMaterial, primeProfileNeedsAgentDir, primeSubagentEntryId, readPrimeProfileControls, } from "./prime-profile.js";
+export * from "./profile-bundle-cache.js";
 export { executionControlConflict, materializeProfile, UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER, } from "./profile-materializer.js";
 export type { ResolveAgentProfileResourcesOptions } from "./resource-resolution.js";
 export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";

package/dist/index.js

@@ -14,6 +14,7 @@ export { BINDABLE_LAUNCH_CONTROLS, EXECUTOR_SYSTEM_PROMPT_BINDINGS, isExecutorSy
 export { materializePrimeProfileControls, prunePrimeProfileMaterial, seedPrimeProfileSubagents, writePrimeAgentFile, } from "./prime-agent-dir.js";
 export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_FORK_INSTALL, PRIME_FORK_PIN, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PrimeHarnessStateError, PrimeProfileError, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
 export { assertPrimeModelAgreement, hasPrimeProfileMaterial, primeProfileNeedsAgentDir, primeSubagentEntryId, readPrimeProfileControls, } from "./prime-profile.js";
+export * from "./profile-bundle-cache.js";
 export { executionControlConflict, materializeProfile, UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER, } from "./profile-materializer.js";
 export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";
 export { prepareSecretConcurrentProfileRevision } from "./secret-concurrent-revision.js";

package/dist/mcp.d.ts

@@ -3,7 +3,7 @@ export declare function materializeMcp(h: HarnessId, mcp: Record<string, ActiveA
  * The header a harness sends to a remote MCP server whose tool-call timeout it
  * raised, carrying the timeout it applied in milliseconds. A server may hold a
  * call for nearly that long. A server that does not see the header must assume
- * the harness default, 60 s for Claude Code and Codex.
+ * the harness default, 60 s for Claude Code, Codex and OpenCode.
  */
 export declare const MCP_TOOL_TIMEOUT_HEADER = "X-Mcp-Tool-Timeout-Ms";
 /** OpenCode-native MCP configuration used by workspace and startup paths. */
@@ -12,14 +12,24 @@ export type OpenCodeMcpConfig = Record<string, {
     url: string;
     enabled: boolean;
     headers?: Record<string, AgentProfileConfigValue>;
+    /** Milliseconds; OpenCode bounds this server's connect, tool listing and tool calls by it. */
+    timeout?: number;
+    /** `false` turns off OpenCode's OAuth discovery for this server. */
+    oauth?: false;
 } | {
     type: "local";
     command: Array<string | AgentProfileConfigValue>;
     enabled: boolean;
     environment?: Record<string, AgentProfileConfigValue>;
+    timeout?: number;
 }>;
-/** Lower canonical MCP definitions to OpenCode's native startup configuration. */
-export declare function openCodeMcpConfig(mcp: Record<string, AgentProfileMcpServer>): OpenCodeMcpConfig;
+/**
+ * Lower canonical MCP definitions to OpenCode's native startup configuration.
+ * `toolTimeouts` holds the validated `metadata.toolTimeoutMs` of each server
+ * that declared one; without it OpenCode applies the MCP SDK's 60 s default to
+ * every tool call.
+ */
+export declare function openCodeMcpConfig(mcp: Record<string, AgentProfileMcpServer>, toolTimeouts?: ReadonlyMap<string, number>): OpenCodeMcpConfig;
 import type { AgentProfileConfigValue, AgentProfileMcpServer } from "@tangle-network/agent-interface";
 import type { AddPlanFile } from "./plan-json.js";
 import type { HarnessId, Unsupported, WorkspacePlan } from "./plan-types.js";

package/dist/mcp.js

@@ -58,7 +58,7 @@ export function materializeMcp(h, mcp, plan, add, unsupported) {
             // opencode.json "mcp" block (local|remote).
             add(OPENCODE_CONFIG_FILE, serializeWorkspacePlanJson({
                 $schema: OPENCODE_CONFIG_SCHEMA,
-                mcp: openCodeMcpConfig(mcp),
+                mcp: openCodeMcpConfig(mcp, mcpToolTimeouts(mcp, h, unsupported)),
             }));
             break;
         case "gemini": {
@@ -156,7 +156,7 @@ function tomlInlineStringTable(values) {
  * The header a harness sends to a remote MCP server whose tool-call timeout it
  * raised, carrying the timeout it applied in milliseconds. A server may hold a
  * call for nearly that long. A server that does not see the header must assume
- * the harness default, 60 s for Claude Code and Codex.
+ * the harness default, 60 s for Claude Code, Codex and OpenCode.
  */
 export const MCP_TOOL_TIMEOUT_HEADER = "X-Mcp-Tool-Timeout-Ms";
 const MIN_MCP_TOOL_TIMEOUT_MS = 1_000;
@@ -270,21 +270,38 @@ function kimiMcpServer(server) {
         ...(server.cwd ? { cwd: server.cwd } : {}),
     };
 }
-/** Lower canonical MCP definitions to OpenCode's native startup configuration. */
-export function openCodeMcpConfig(mcp) {
+const carriesAuthorization = (headers) => Object.keys(headers ?? {}).some((header) => header.toLowerCase() === "authorization");
+/**
+ * Lower canonical MCP definitions to OpenCode's native startup configuration.
+ * `toolTimeouts` holds the validated `metadata.toolTimeoutMs` of each server
+ * that declared one; without it OpenCode applies the MCP SDK's 60 s default to
+ * every tool call.
+ */
+export function openCodeMcpConfig(mcp, toolTimeouts = new Map()) {
     const out = {};
     for (const [name, s] of Object.entries(mcp)) {
         if (s.enabled === false)
             continue;
+        // OpenCode also bounds connect and tool listing by this value, so a server
+        // that hangs on connect holds startup that long; a refused connection still
+        // fails at once.
+        const timeout = toolTimeouts.get(name);
         if (s.url) {
             if (s.transport === "sse") {
                 throw new Error(`OpenCode MCP server "${name}" uses unsupported SSE transport`);
             }
+            const headers = withAppliedToolTimeout(s.headers, timeout);
             out[name] = {
                 type: "remote",
                 url: s.url,
                 enabled: true,
-                ...(s.headers ? { headers: s.headers } : {}),
+                ...(headers ? { headers } : {}),
+                ...(timeout !== undefined ? { timeout } : {}),
+                // A server that takes its credential from these headers has no OAuth
+                // flow. With OAuth on, OpenCode answers its 401 with OAuth discovery at
+                // the server's origin, and the agent sees that discovery's failure
+                // instead of the server's refusal.
+                ...(carriesAuthorization(s.headers) ? { oauth: false } : {}),
             };
             continue;
         }
@@ -299,6 +316,7 @@ export function openCodeMcpConfig(mcp) {
             command: [s.command, ...(s.args ?? [])],
             enabled: true,
             ...(s.env ? { environment: s.env } : {}),
+            ...(timeout !== undefined ? { timeout } : {}),
         };
     }
     return out;

package/dist/profile-bundle-cache.d.ts

@@ -0,0 +1,37 @@
+import { type ProfileBundleCache, type ProfileBundleClaim, type ProfileBundleClaimResult, type ProfileBundleManifest } from "./profile-bundle-key.js";
+export * from "./profile-bundle-key.js";
+export { evictProfileBundles, profileBundleManifestPath, sweepProfileBundleCache, } from "./profile-bundle-lru.js";
+/**
+ * Admit a just-delivered bundle to the host cache, all-or-nothing. Every
+ * object's bytes are verified against its content hash BEFORE anything is
+ * renamed into place; a mismatch throws with nothing published. Objects
+ * already present are re-verified against the incoming bytes, then the temp
+ * copy is dropped — the existing object was verified when it was admitted.
+ * The manifest is written LAST as the commit point, followed by lru update
+ * and eviction down to the default cap.
+ */
+export declare function admitProfileBundle(root: string, manifest: ProfileBundleManifest, readObject: (sha256: string) => Promise<Uint8Array> | Uint8Array): Promise<void>;
+/**
+ * Claim a bundle from a (possibly read-only mounted) cache. Verify-on-read:
+ * every object's bytes are re-hashed and compared to BOTH the manifest entry
+ * and the claim's expected sha256 before `linkFile` is called — a read-only
+ * mount must never serve unverified bytes. `linkFile` returning false sends
+ * the file to `missing` (the caller delivers it normally). Status is "hit"
+ * only when nothing is missing; a partial bundle is NEVER a hit. The only
+ * write is a best-effort lru touch, wrapped so EROFS on a read-only mount is
+ * harmless.
+ */
+export declare function claimProfileBundle(root: string, claim: ProfileBundleClaim, linkFile: (objectPath: string, entry: {
+    mountPath: string;
+    target: string;
+    sha256: string;
+    mode: number;
+}) => Promise<boolean>): Promise<ProfileBundleClaimResult>;
+/**
+ * Open a host-side cache handle over `root`, creating the layout and sweeping
+ * stale `incoming/` residue synchronously so the cache is deterministic to
+ * use immediately afterwards.
+ */
+export declare function openProfileBundleCache(root: string, options?: {
+    maxBytes?: number;
+}): ProfileBundleCache;

package/dist/profile-bundle-cache.js

@@ -0,0 +1,318 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, rmSync } from "node:fs";
+import { mkdir, open, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { PROFILE_BUNDLE_DEFAULT_MAX_BYTES, PROFILE_BUNDLE_MAX_BYTES, PROFILE_BUNDLE_MAX_FILE_BYTES, PROFILE_BUNDLE_MAX_FILES, PROFILE_BUNDLE_SCHEMA, } from "./profile-bundle-key.js";
+import { evictProfileBundles, evictUnlocked, fsyncDir, loadLru, pathExists, profileBundleManifestPath, readManifestFile, saveLru, sweepProfileBundleCache, withRootLock, } from "./profile-bundle-lru.js";
+import { hasControlCharacter, normalizeWorkspaceRelativePath, validateFileMode, } from "./workspace-files.js";
+export * from "./profile-bundle-key.js";
+export { evictProfileBundles, profileBundleManifestPath, sweepProfileBundleCache, } from "./profile-bundle-lru.js";
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const nowIso = () => new Date().toISOString();
+/**
+ * Content-addressed, per-host cache of delivered profile-file bundles.
+ *
+ * A production cold sandbox start spends seconds re-delivering the same inline
+ * profile file mounts through the box file API on every fresh box. The host
+ * owns a cache directory (mounted read-only into boxes) of immutable,
+ * content-addressed file objects plus per-bundle manifests. A box "claims" a
+ * bundle by verifying every object against its content hash and hardlinking it
+ * into the workspace, skipping network delivery; after a normal miss-delivery
+ * the box-side publisher "admits" the just-delivered bytes to the host.
+ *
+ * Durability invariants:
+ * - `objects/<sha256>` bytes are immutable and self-certifying: the filename
+ *   IS the SHA-256 of the bytes. Objects are written to a unique `incoming/`
+ *   dir and renamed into place only after every byte is verified, so a crash
+ *   mid-admit leaves no half-published object behind.
+ * - `bundles/<key>.json` is the commit point: readers treat a bundle as
+ *   present only if its manifest exists, and verify every object anyway
+ *   (verify-on-read), so a read-only or partially corrupt cache mount can
+ *   never serve unverified bytes.
+ * - `lru.json` is advisory accounting only; corruption never breaks admit or
+ *   claim (see profile-bundle-lru.ts).
+ */
+function validateManifestShape(manifest) {
+    if (manifest.schema !== PROFILE_BUNDLE_SCHEMA) {
+        throw new Error(`Profile bundle manifest schema mismatch: ${String(manifest.schema)}`);
+    }
+    if (typeof manifest.bundle !== "string" || manifest.bundle.length === 0) {
+        throw new Error("Profile bundle manifest requires a non-empty bundle key");
+    }
+    if (typeof manifest.createdAt !== "string") {
+        throw new Error("Profile bundle manifest requires an ISO createdAt");
+    }
+    if (!Number.isInteger(manifest.sizeBytes) ||
+        manifest.sizeBytes < 0 ||
+        manifest.sizeBytes > PROFILE_BUNDLE_MAX_BYTES) {
+        throw new Error(`Profile bundle sizeBytes exceeds ${PROFILE_BUNDLE_MAX_BYTES}: ${manifest.sizeBytes}`);
+    }
+    if (!Array.isArray(manifest.files)) {
+        throw new Error("Profile bundle manifest requires a files array");
+    }
+}
+/**
+ * Reject anything that could link outside the cache or the workspace:
+ * mount paths must already be canonical workspace-relative paths, and targets
+ * must not contain traversal segments (targets MAY be absolute — the staged
+ * manifest's `path` can be a file-API absolute prefix — but never `..`).
+ */
+function validateTarget(target) {
+    if (typeof target !== "string" || target.length === 0) {
+        throw new Error("Profile bundle file requires a non-empty target");
+    }
+    if (hasControlCharacter(target)) {
+        throw new Error(`Profile bundle target has control characters: ${target}`);
+    }
+    const segments = target.replace(/\\/g, "/").split("/");
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error(`Profile bundle target must not traverse: ${target}`);
+    }
+    return target;
+}
+function validateManifestFiles(manifest) {
+    if (manifest.files.length > PROFILE_BUNDLE_MAX_FILES) {
+        throw new Error(`Profile bundle has ${manifest.files.length} files; limit is ${PROFILE_BUNDLE_MAX_FILES}`);
+    }
+    const mountPaths = new Set();
+    const targets = new Set();
+    const entries = [];
+    for (const file of manifest.files) {
+        if (normalizeWorkspaceRelativePath(file.mountPath) !== file.mountPath) {
+            throw new Error(`Profile bundle mount path must be canonical: ${file.mountPath}`);
+        }
+        const target = validateTarget(file.target);
+        if (!SHA256_HEX_RE.test(file.sha256)) {
+            throw new Error(`Profile bundle sha256 must be lowercase hex without prefix: ${file.sha256}`);
+        }
+        const mode = validateFileMode(file.mode);
+        if (mountPaths.has(file.mountPath)) {
+            throw new Error(`Profile bundle has duplicate mount path: ${file.mountPath}`);
+        }
+        if (targets.has(target)) {
+            throw new Error(`Profile bundle has duplicate target: ${target}`);
+        }
+        mountPaths.add(file.mountPath);
+        targets.add(target);
+        entries.push({
+            mountPath: file.mountPath,
+            sha256: file.sha256,
+            mode,
+            target,
+        });
+    }
+    return entries;
+}
+/**
+ * Admit a just-delivered bundle to the host cache, all-or-nothing. Every
+ * object's bytes are verified against its content hash BEFORE anything is
+ * renamed into place; a mismatch throws with nothing published. Objects
+ * already present are re-verified against the incoming bytes, then the temp
+ * copy is dropped — the existing object was verified when it was admitted.
+ * The manifest is written LAST as the commit point, followed by lru update
+ * and eviction down to the default cap.
+ */
+export async function admitProfileBundle(root, manifest, readObject) {
+    validateManifestShape(manifest);
+    const entries = validateManifestFiles(manifest);
+    await sweepProfileBundleCache(root);
+    await mkdir(join(root, "objects"), { recursive: true });
+    await mkdir(join(root, "bundles"), { recursive: true });
+    await mkdir(join(root, "incoming"), { recursive: true });
+    await withRootLock(root, async () => {
+        const manifestPath = profileBundleManifestPath(root, manifest.bundle);
+        const existing = await readManifestFile(manifestPath);
+        if (existing && existing.bundle !== manifest.bundle) {
+            throw new Error(`Profile bundle key collides with an admitted bundle: ${manifest.bundle}`);
+        }
+        const incoming = join(root, "incoming", randomUUID());
+        await mkdir(incoming, { recursive: true });
+        try {
+            const staged = [];
+            let totalBytes = 0;
+            for (const entry of entries) {
+                const bytes = await readObject(entry.sha256);
+                const buffer = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+                if (buffer.byteLength > PROFILE_BUNDLE_MAX_FILE_BYTES) {
+                    throw new Error(`Profile bundle file ${entry.mountPath} exceeds ${PROFILE_BUNDLE_MAX_FILE_BYTES} bytes`);
+                }
+                if (sha256Hex(buffer) !== entry.sha256) {
+                    throw new Error(`Profile bundle object hash mismatch for ${entry.mountPath}`);
+                }
+                totalBytes += buffer.byteLength;
+                const object = join(root, "objects", entry.sha256);
+                if (await pathExists(object)) {
+                    // Already admitted; the bytes above were re-verified, so drop the temp.
+                    continue;
+                }
+                const temporary = join(incoming, entry.sha256);
+                const handle = await open(temporary, "w", (entry.mode & 0o100) !== 0 ? 0o755 : 0o644);
+                try {
+                    await handle.write(buffer);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                staged.push({ temporary, object });
+            }
+            if (totalBytes > PROFILE_BUNDLE_MAX_BYTES) {
+                throw new Error(`Profile bundle exceeds ${PROFILE_BUNDLE_MAX_BYTES} bytes: ${totalBytes}`);
+            }
+            for (const { temporary, object } of staged) {
+                await rename(temporary, object);
+            }
+            await fsyncDir(join(root, "objects"));
+            const stagedManifest = join(incoming, "manifest.json");
+            await writeFile(stagedManifest, JSON.stringify(manifest));
+            const manifestHandle = await open(stagedManifest, "r");
+            try {
+                await manifestHandle.sync();
+            }
+            finally {
+                await manifestHandle.close();
+            }
+            await rename(stagedManifest, manifestPath);
+            await fsyncDir(join(root, "bundles"));
+            const lru = await loadLru(root);
+            const used = nowIso();
+            for (const entry of entries) {
+                lru.objects[entry.sha256] = {
+                    bytes: (await stat(join(root, "objects", entry.sha256))).size,
+                    lastUsed: used,
+                };
+            }
+            lru.bundles[manifest.bundle] = {
+                bytes: totalBytes,
+                lastUsed: used,
+                createdAt: manifest.createdAt,
+            };
+            await saveLru(root, lru);
+        }
+        finally {
+            await rm(incoming, { recursive: true, force: true });
+        }
+        await evictUnlocked(root, PROFILE_BUNDLE_DEFAULT_MAX_BYTES);
+    });
+}
+/**
+ * Claim a bundle from a (possibly read-only mounted) cache. Verify-on-read:
+ * every object's bytes are re-hashed and compared to BOTH the manifest entry
+ * and the claim's expected sha256 before `linkFile` is called — a read-only
+ * mount must never serve unverified bytes. `linkFile` returning false sends
+ * the file to `missing` (the caller delivers it normally). Status is "hit"
+ * only when nothing is missing; a partial bundle is NEVER a hit. The only
+ * write is a best-effort lru touch, wrapped so EROFS on a read-only mount is
+ * harmless.
+ */
+export async function claimProfileBundle(root, claim, linkFile) {
+    const missAll = () => ({
+        status: "miss",
+        missing: claim.files.map((file) => file.mountPath),
+    });
+    const manifest = await readManifestFile(profileBundleManifestPath(root, claim.bundle));
+    if (!manifest ||
+        manifest.schema !== PROFILE_BUNDLE_SCHEMA ||
+        manifest.bundle !== claim.bundle ||
+        !Array.isArray(manifest.files)) {
+        return missAll();
+    }
+    let entries;
+    try {
+        entries = validateManifestFiles(manifest);
+    }
+    catch {
+        return missAll();
+    }
+    const expected = new Map();
+    for (const file of claim.files) {
+        // Fail closed: a claim with a non-canonical path is rejected outright so a
+        // tampered claim can never link outside the workspace.
+        if (normalizeWorkspaceRelativePath(file.mountPath) !== file.mountPath) {
+            throw new Error(`Profile bundle claim path is not canonical: ${file.mountPath}`);
+        }
+        if (!SHA256_HEX_RE.test(file.sha256)) {
+            throw new Error(`Profile bundle claim sha256 is not hex: ${file.sha256}`);
+        }
+        if (expected.has(file.mountPath)) {
+            throw new Error(`Profile bundle claim has duplicate mount path: ${file.mountPath}`);
+        }
+        expected.set(file.mountPath, file.sha256);
+    }
+    const tableMatches = entries.length === expected.size &&
+        entries.every((entry) => expected.get(entry.mountPath) === entry.sha256);
+    if (!tableMatches) {
+        return missAll();
+    }
+    const linked = [];
+    const missing = [];
+    for (const entry of entries) {
+        const objectPath = join(root, "objects", entry.sha256);
+        let bytes;
+        try {
+            bytes = await readFile(objectPath);
+        }
+        catch {
+            missing.push(entry.mountPath);
+            continue;
+        }
+        if (sha256Hex(bytes) !== entry.sha256 ||
+            entry.sha256 !== expected.get(entry.mountPath)) {
+            missing.push(entry.mountPath);
+            continue;
+        }
+        if (await linkFile(objectPath, entry)) {
+            linked.push(entry.mountPath);
+        }
+        else {
+            missing.push(entry.mountPath);
+        }
+    }
+    if (missing.length > 0)
+        return { status: "miss", missing };
+    try {
+        await withRootLock(root, async () => {
+            const lru = await loadLru(root);
+            const used = nowIso();
+            for (const entry of entries) {
+                const object = lru.objects[entry.sha256];
+                if (object)
+                    object.lastUsed = used;
+            }
+            const bundleEntry = lru.bundles[claim.bundle];
+            if (bundleEntry)
+                bundleEntry.lastUsed = used;
+            await saveLru(root, lru);
+        });
+    }
+    catch {
+        // Best-effort accounting on a possibly read-only mount.
+    }
+    return { status: "hit", linked };
+}
+/**
+ * Open a host-side cache handle over `root`, creating the layout and sweeping
+ * stale `incoming/` residue synchronously so the cache is deterministic to
+ * use immediately afterwards.
+ */
+export function openProfileBundleCache(root, options) {
+    const maxBytes = options?.maxBytes ?? PROFILE_BUNDLE_DEFAULT_MAX_BYTES;
+    if (!Number.isFinite(maxBytes) || maxBytes < 0) {
+        throw new Error(`Profile bundle cache maxBytes must be >= 0: ${maxBytes}`);
+    }
+    mkdirSync(join(root, "objects"), { recursive: true });
+    mkdirSync(join(root, "bundles"), { recursive: true });
+    const incoming = join(root, "incoming");
+    mkdirSync(incoming, { recursive: true });
+    for (const entry of readdirSync(incoming)) {
+        rmSync(join(incoming, entry), { recursive: true, force: true });
+    }
+    return {
+        root,
+        maxBytes,
+        admit: (manifest, readObject) => admitProfileBundle(root, manifest, readObject),
+        evict: () => evictProfileBundles(root, maxBytes),
+        sweep: () => sweepProfileBundleCache(root),
+    };
+}

package/dist/profile-bundle-key.d.ts

@@ -0,0 +1,69 @@
+import type { AgentProfileFileMount } from "@tangle-network/agent-interface";
+export declare const PROFILE_BUNDLE_SCHEMA = "agent-profile-bundle/v1";
+export declare const PROFILE_BUNDLE_MAX_FILES = 512;
+export declare const PROFILE_BUNDLE_MAX_BYTES: number;
+export declare const PROFILE_BUNDLE_MAX_FILE_BYTES: number;
+export declare const PROFILE_BUNDLE_DEFAULT_MAX_BYTES: number;
+export interface ProfileBundleFileEntry {
+    /** Logical workspace-relative mount path, exactly as declared on the profile. */
+    mountPath: string;
+    /** SHA-256 of the content bytes as lowercase hex, WITHOUT the `sha256:` prefix. */
+    sha256: string;
+    /** Full file mode (0o644 default, 0o755 for executable mounts). */
+    mode: number;
+}
+export interface ProfileBundleManifest {
+    schema: string;
+    /** Raw bundle key (e.g. `sha256:<hex>`); also recoverable from the filename. */
+    bundle: string;
+    createdAt: string;
+    sizeBytes: number;
+    files: Array<ProfileBundleFileEntry & {
+        target: string;
+    }>;
+}
+export interface ProfileBundleClaim {
+    bundle: string;
+    files: Array<{
+        mountPath: string;
+        sha256: string;
+    }>;
+}
+export type ProfileBundleClaimResult = {
+    status: "hit";
+    linked: string[];
+} | {
+    status: "miss";
+    missing: string[];
+};
+export interface ProfileBundleCache {
+    root: string;
+    maxBytes: number;
+    admit(manifest: ProfileBundleManifest, readObject: (sha256: string) => Promise<Uint8Array> | Uint8Array): Promise<void>;
+    evict(): Promise<void>;
+    sweep(): Promise<void>;
+}
+/**
+ * Derive the canonical bundle file entry for one inline mount. The sha256 is
+ * computed over the exact inline content bytes and the mode mirrors the SDK's
+ * `profileFileMode`/`isExecutableProfileFile`: `mount.executable` wins when
+ * present, otherwise a path under a `bin/` or `sbin/` directory is executable.
+ * A mount whose resource is not inline is a caller bug and throws, matching
+ * the fail-closed discipline of {@link resolveInlineRef}.
+ */
+export declare function profileBundleFileEntry(mount: AgentProfileFileMount): ProfileBundleFileEntry;
+/**
+ * The canonical file table: one entry per mount, sorted by (mountPath, sha256)
+ * so any array order of the same mounts produces the same table.
+ */
+export declare function profileBundleFileTable(mounts: readonly AgentProfileFileMount[]): ProfileBundleFileEntry[];
+/**
+ * The content-addressed bundle key. The digest covers EXACTLY the schema
+ * version and, per file, the logical mount path, the sha256 of the content
+ * bytes, and the full file mode — the same image-content-hash discipline as
+ * scripts/ci/image-content-hash.mjs: hash exactly the inputs that determine
+ * the cached bytes (and their placement semantics), nothing more. Any profile
+ * change — content, path, or mode — produces a new key; anything else
+ * (mount order, transport-only target paths, timestamps) does not.
+ */
+export declare function profileFileBundleKey(mounts: readonly AgentProfileFileMount[]): string;

package/dist/profile-bundle-key.js

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { canonicalCandidateDigest } from "@tangle-network/agent-interface";
+import { resolveInlineRef } from "./resource-resolution.js";
+import { compareStrings } from "./workspace-files.js";
+// The bundle key, wire shapes and limits shared by the SDK, sidecar and
+// host-agent. The cache itself (admit, claim, open) is profile-bundle-cache.ts.
+export const PROFILE_BUNDLE_SCHEMA = "agent-profile-bundle/v1";
+export const PROFILE_BUNDLE_MAX_FILES = 512;
+export const PROFILE_BUNDLE_MAX_BYTES = 256 * 1024 * 1024;
+export const PROFILE_BUNDLE_MAX_FILE_BYTES = 32 * 1024 * 1024;
+export const PROFILE_BUNDLE_DEFAULT_MAX_BYTES = 1024 * 1024 * 1024;
+// Mirrors PROFILE_BIN_DIR_RE in products/sandbox/sdk/src/profile-file-mounts.ts,
+// the canonical definition for staged profile delivery. The SDK consumes this
+// package, so the regex source is mirrored (not imported); tests assert parity
+// with the SDK's profileFileMode semantics for representative paths.
+const PROFILE_BIN_DIR_RE = /(^|\/)(s?bin)\//;
+/**
+ * Derive the canonical bundle file entry for one inline mount. The sha256 is
+ * computed over the exact inline content bytes and the mode mirrors the SDK's
+ * `profileFileMode`/`isExecutableProfileFile`: `mount.executable` wins when
+ * present, otherwise a path under a `bin/` or `sbin/` directory is executable.
+ * A mount whose resource is not inline is a caller bug and throws, matching
+ * the fail-closed discipline of {@link resolveInlineRef}.
+ */
+export function profileBundleFileEntry(mount) {
+    const resolved = resolveInlineRef(mount.resource);
+    if (resolved === null) {
+        throw new Error(`profileBundleFileEntry: ${mount.path} requires an inline resource`);
+    }
+    const executable = mount.executable ?? PROFILE_BIN_DIR_RE.test(mount.path);
+    return {
+        mountPath: mount.path,
+        sha256: createHash("sha256").update(resolved.content, "utf8").digest("hex"),
+        mode: executable ? 0o755 : 0o644,
+    };
+}
+/**
+ * The canonical file table: one entry per mount, sorted by (mountPath, sha256)
+ * so any array order of the same mounts produces the same table.
+ */
+export function profileBundleFileTable(mounts) {
+    return mounts
+        .map(profileBundleFileEntry)
+        .sort((left, right) => left.mountPath !== right.mountPath
+        ? compareStrings(left.mountPath, right.mountPath)
+        : compareStrings(left.sha256, right.sha256));
+}
+/**
+ * The content-addressed bundle key. The digest covers EXACTLY the schema
+ * version and, per file, the logical mount path, the sha256 of the content
+ * bytes, and the full file mode — the same image-content-hash discipline as
+ * scripts/ci/image-content-hash.mjs: hash exactly the inputs that determine
+ * the cached bytes (and their placement semantics), nothing more. Any profile
+ * change — content, path, or mode — produces a new key; anything else
+ * (mount order, transport-only target paths, timestamps) does not.
+ */
+export function profileFileBundleKey(mounts) {
+    return canonicalCandidateDigest({
+        schema: PROFILE_BUNDLE_SCHEMA,
+        files: profileBundleFileTable(mounts),
+    });
+}

package/dist/profile-bundle-lru.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Advisory lru accounting for the profile bundle cache (see
+ * profile-bundle-cache.ts for the cache layout and durability invariants).
+ * `lru.json` is never load-bearing: it is rebuilt from a disk scan whenever it
+ * is absent or corrupt, and every write to it is best-effort so a full or
+ * read-only cache can never break admit, claim, or eviction.
+ */
+export interface ProfileBundleLru {
+    v: 1;
+    objects: Record<string, {
+        bytes: number;
+        lastUsed: string;
+    }>;
+    bundles: Record<string, {
+        bytes: number;
+        lastUsed: string;
+        createdAt: string;
+    }>;
+}
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function fsyncDir(dir: string): Promise<void>;
+export declare function withRootLock<T>(root: string, run: () => Promise<T>): Promise<T>;
+export declare function readManifestFile(path: string): Promise<{
+    schema?: unknown;
+    bundle?: unknown;
+    createdAt?: unknown;
+    files?: unknown;
+} | null>;
+/**
+ * Bundle keys come from `canonicalCandidateDigest` as `sha256:<hex>`; the `:`
+ * is encoded so the key is a safe single path segment on any host filesystem.
+ * The raw key is always recoverable from the manifest's `bundle` field.
+ */
+export declare function profileBundleManifestPath(root: string, bundle: string): string;
+/** Rebuild advisory lru accounting from a disk scan (objects are immutable). */
+/**
+ * Remove stale `incoming/` admission directories. An admit only ever renames
+ * OUT of `incoming/`, so anything found here is residue from an interrupted
+ * admission and is safe to delete; objects and manifests are untouched.
+ */
+export declare function sweepProfileBundleCache(root: string): Promise<void>;
+export declare function loadLru(root: string): Promise<ProfileBundleLru>;
+/** Best-effort by contract: lru corruption or a full cache must never break admit/claim. */
+export declare function saveLru(root: string, lru: ProfileBundleLru): Promise<void>;
+/** Eviction body; callers must already hold the per-root lock. */
+export declare function evictUnlocked(root: string, maxBytes: number): Promise<void>;
+/**
+ * Evict least-recently-used objects until total object bytes are within
+ * `maxBytes`. Unreferenced objects go first (they reclaim space with no
+ * bundle impact); if the cap still does not hold, referenced objects are
+ * evicted oldest-first, which makes their bundles partial — claims then miss
+ * and re-deliver, so eviction can never serve wrong bytes. Bundle manifests
+ * referencing no existing objects are removed. Mid-admit `incoming/` dirs are
+ * never touched.
+ */
+export declare function evictProfileBundles(root: string, maxBytes: number): Promise<void>;

package/dist/profile-bundle-lru.js

@@ -0,0 +1,211 @@
+import { randomUUID } from "node:crypto";
+import { open, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { compareStrings } from "./workspace-files.js";
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function fsyncDir(dir) {
+    try {
+        const handle = await open(dir, "r");
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        // Best-effort durability: a cache without directory fsync still verifies.
+    }
+}
+/** Serialize admits/evictions per cache root so lru read-modify-write stays deterministic. */
+const rootQueues = new Map();
+export function withRootLock(root, run) {
+    const previous = rootQueues.get(root) ?? Promise.resolve();
+    const next = previous.then(run, run);
+    rootQueues.set(root, next.catch(() => undefined));
+    return next;
+}
+export async function readManifestFile(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bundle keys come from `canonicalCandidateDigest` as `sha256:<hex>`; the `:`
+ * is encoded so the key is a safe single path segment on any host filesystem.
+ * The raw key is always recoverable from the manifest's `bundle` field.
+ */
+export function profileBundleManifestPath(root, bundle) {
+    const filename = bundle.replace(/[^A-Za-z0-9._-]/g, (char) => `_${char.codePointAt(0)?.toString(16) ?? "3f"}_`);
+    return join(root, "bundles", `${filename}.json`);
+}
+/** Rebuild advisory lru accounting from a disk scan (objects are immutable). */
+/**
+ * Remove stale `incoming/` admission directories. An admit only ever renames
+ * OUT of `incoming/`, so anything found here is residue from an interrupted
+ * admission and is safe to delete; objects and manifests are untouched.
+ */
+export async function sweepProfileBundleCache(root) {
+    const incoming = join(root, "incoming");
+    let entries;
+    try {
+        entries = await readdir(incoming);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        await rm(join(incoming, entry), { recursive: true, force: true });
+    }
+    await fsyncDir(incoming);
+}
+async function rebuildLru(root) {
+    const lru = { v: 1, objects: {}, bundles: {} };
+    try {
+        for (const name of await readdir(join(root, "objects"))) {
+            const info = await stat(join(root, "objects", name));
+            if (info.isFile()) {
+                lru.objects[name] = {
+                    bytes: info.size,
+                    lastUsed: info.mtime.toISOString(),
+                };
+            }
+        }
+    }
+    catch {
+        // Missing objects dir: fresh cache.
+    }
+    try {
+        for (const name of await readdir(join(root, "bundles"))) {
+            const manifest = await readManifestFile(join(root, "bundles", name));
+            if (!manifest || typeof manifest.bundle !== "string")
+                continue;
+            const info = await stat(join(root, "bundles", name));
+            const files = Array.isArray(manifest.files) ? manifest.files : [];
+            const referenced = files.map((file) => file.sha256);
+            const bytes = referenced.reduce((sum, sha) => sum + (lru.objects[sha ?? ""]?.bytes ?? 0), 0);
+            lru.bundles[manifest.bundle] = {
+                bytes,
+                lastUsed: info.mtime.toISOString(),
+                createdAt: typeof manifest.createdAt === "string"
+                    ? manifest.createdAt
+                    : info.mtime.toISOString(),
+            };
+        }
+    }
+    catch {
+        // Missing bundles dir: fresh cache.
+    }
+    return lru;
+}
+export async function loadLru(root) {
+    try {
+        const parsed = JSON.parse(await readFile(join(root, "lru.json"), "utf8"));
+        if (parsed &&
+            parsed.v === 1 &&
+            typeof parsed.objects === "object" &&
+            typeof parsed.bundles === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        // Corrupt or missing: rebuild below.
+    }
+    return rebuildLru(root);
+}
+/** Best-effort by contract: lru corruption or a full cache must never break admit/claim. */
+export async function saveLru(root, lru) {
+    try {
+        const path = join(root, "lru.json");
+        const temporary = `${path}.tmp-${randomUUID()}`;
+        await writeFile(temporary, JSON.stringify(lru));
+        await rename(temporary, path);
+    }
+    catch {
+        // Read-only or full cache: eviction still held on disk.
+    }
+}
+/** Eviction body; callers must already hold the per-root lock. */
+export async function evictUnlocked(root, maxBytes) {
+    const lru = await loadLru(root);
+    const objectsDir = join(root, "objects");
+    for (const sha of Object.keys(lru.objects)) {
+        if (!(await pathExists(join(objectsDir, sha)))) {
+            delete lru.objects[sha];
+        }
+    }
+    const manifests = new Map();
+    const bundlesDir = join(root, "bundles");
+    for (const name of await readdir(bundlesDir)) {
+        const manifest = await readManifestFile(join(bundlesDir, name));
+        if (manifest && typeof manifest.bundle === "string") {
+            manifests.set(manifest.bundle, manifest);
+        }
+        else {
+            await rm(join(bundlesDir, name), { force: true });
+        }
+    }
+    const referenced = new Set();
+    for (const manifest of manifests.values()) {
+        const files = Array.isArray(manifest.files) ? manifest.files : [];
+        for (const file of files) {
+            const sha = file.sha256;
+            if (typeof sha === "string")
+                referenced.add(sha);
+        }
+    }
+    let total = Object.values(lru.objects).reduce((sum, o) => sum + o.bytes, 0);
+    const byLastUsed = (sha) => lru.objects[sha]?.lastUsed ?? "";
+    const live = Object.keys(lru.objects);
+    const unreferenced = live
+        .filter((sha) => !referenced.has(sha))
+        .sort((a, b) => compareStrings(byLastUsed(a), byLastUsed(b)));
+    const referencedLive = live
+        .filter((sha) => referenced.has(sha))
+        .sort((a, b) => compareStrings(byLastUsed(a), byLastUsed(b)));
+    for (const sha of [...unreferenced, ...referencedLive]) {
+        if (total <= maxBytes)
+            break;
+        await rm(join(objectsDir, sha), { force: true });
+        total -= lru.objects[sha]?.bytes ?? 0;
+        delete lru.objects[sha];
+    }
+    // Bundles whose every object is gone can never be claimed; drop their manifests.
+    for (const [bundle, manifest] of manifests) {
+        const files = Array.isArray(manifest.files) ? manifest.files : [];
+        const alive = files.some((file) => Boolean(lru.objects[file.sha256 ?? ""]));
+        if (!alive) {
+            await rm(profileBundleManifestPath(root, bundle), { force: true });
+            delete lru.bundles[bundle];
+        }
+    }
+    await fsyncDir(objectsDir);
+    await fsyncDir(bundlesDir);
+    await saveLru(root, lru);
+}
+/**
+ * Evict least-recently-used objects until total object bytes are within
+ * `maxBytes`. Unreferenced objects go first (they reclaim space with no
+ * bundle impact); if the cap still does not hold, referenced objects are
+ * evicted oldest-first, which makes their bundles partial — claims then miss
+ * and re-deliver, so eviction can never serve wrong bytes. Bundle manifests
+ * referencing no existing objects are removed. Mid-admit `incoming/` dirs are
+ * never touched.
+ */
+export async function evictProfileBundles(root, maxBytes) {
+    if (!Number.isFinite(maxBytes) || maxBytes < 0) {
+        throw new Error(`Profile bundle cache maxBytes must be >= 0: ${maxBytes}`);
+    }
+    await withRootLock(root, () => evictUnlocked(root, maxBytes));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.22.3",
+  "version": "0.23.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",
   "repository": {