@tangle-network/agent-profile-materialize 0.23.1 → 0.25.3

package/dist/candidate.js

@@ -208,6 +208,7 @@ function candidateResourcesForClassicMaterializer(resources, resolvedResources)
         };
     };
     return {
+        ...resources,
         files: resources.files?.map((mount) => ({
             path: mount.path,
             resource: convert(mount.resource),

package/dist/harness.js

@@ -348,14 +348,15 @@ export function materializerReplacement(relPath, content, plannedContent) {
  * there.
  *
  * An `opencode.json` this package wrote holds the opencode schema id, only the
- * keys this package writes, and only instruction paths this package invented.
- * A user config that holds nothing else is indistinguishable from that output
- * and is replaced too; a config with any other key, or with an instruction path
- * of the user's own, is refused.
+ * keys this package writes, and only instruction paths this package invented;
+ * a user config holding nothing else is replaced too, any other key or own
+ * instruction path is refused.
  */
 function isMaterializerOutput(relPath, content, plannedContent) {
     if (MATERIALIZER_RESERVED_PATHS.has(relPath))
         return true;
+    if (relPath === ".pi/mcp.json" || relPath === ".kimi/mcp.json")
+        return isMaterializerMcpConfig(relPath, content);
     if (MATERIALIZER_SUBAGENT_PATH.test(relPath)) {
         const existing = content();
         if (existing === undefined)
@@ -435,3 +436,4 @@ export function skillDirForHarness(harness) {
     return HARNESS_SKILL_DIRS[harness];
 }
 import { createHash } from "node:crypto";
+import { isMaterializerMcpConfig } from "./mcp-config-ownership.js";

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from "./harness-prompt.js";
 export { type ConcurrentProfileRevision, ensurePublicConcurrentProfileRoots, type ManagedWorkspaceFileDigest, type ManagedWorkspaceManifest, preparePublicConcurrentProfileRevision, } from "./managed-workspace.js";
 export type { OpenCodeMcpConfig } from "./mcp.js";
 export { openCodeMcpConfig } from "./mcp.js";
+export { isMaterializerMcpConfig } from "./mcp-config-ownership.js";
 export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";
 export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, type PiModelsConfigFile, type PiModelsConfigInput, type PiRuntimePaths, resolvePiRuntimePaths, } from "./pi-models-config.js";
 export { applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, } from "./plan-application.js";

package/dist/index.js

@@ -4,6 +4,7 @@ export { HARNESS_SKILL_DIRS, harnessAutoLoadsAgentContextFile, harnessAutoLoadsC
 export * from "./harness-prompt.js";
 export { ensurePublicConcurrentProfileRoots, preparePublicConcurrentProfileRevision, } from "./managed-workspace.js";
 export { openCodeMcpConfig } from "./mcp.js";
+export { isMaterializerMcpConfig } from "./mcp-config-ownership.js";
 export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";
 export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, resolvePiRuntimePaths, } from "./pi-models-config.js";
 export { applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, } from "./plan-application.js";

package/dist/mcp-config-ownership.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Harness MCP config files this package generates wholesale from
+ * `profile.mcp`: exactly one `mcpServers` object whose entries carry only
+ * the fields the generators write. Recognizable by that shape alone (no
+ * schema id to key on), so an existing file holding ONLY those registrations
+ * is this package's earlier output and a new plan replaces it — a per-turn
+ * profile changes these bytes routinely (physim's MCP env carries turn
+ * state). Anything else at the path (a user's own keys, extra fields) still
+ * refuses: the name alone proves nothing, same rule as `opencode.json`.
+ */
+/** Paths owned by this rule. `.gemini/settings.json` is deliberately absent:
+ *  it is a broader user settings file the package only contributes one key
+ *  to, so its bytes cannot prove authorship. */
+export declare const MATERIALIZER_MCP_CONFIG_PATHS: Set<string>;
+/** The parsed form this rule accepts: `JSON.parse` output narrowed at the
+ *  I/O boundary by {@link parseMcpServersConfig}. */
+export interface McpServersConfig {
+    mcpServers: Record<string, Record<string, unknown>>;
+}
+/** Parse workspace bytes into the one shape this rule owns, or `null` when
+ *  the bytes are anything else (not an object, other top-level keys, or
+ *  server entries that are not objects). The I/O boundary for
+ *  {@link isGeneratedMcpConfigShape}. */
+export declare function parseMcpServersConfig(bytes: string): McpServersConfig | null;
+/** Whether a parsed MCP config carries ONLY the registrations this package
+ *  generates: no extra top-level keys, and every server entry holds only
+ *  generated fields. A user's own key anywhere makes this `false`. */
+export declare function isGeneratedMcpConfigShape(config: McpServersConfig): boolean;
+/** Whether the existing file at `relPath` is this package's own earlier MCP
+ *  config output (shape rule above). `undefined` content = no regular file. */
+export declare function isMaterializerMcpConfig(relPath: string, content: () => string | undefined): boolean;

package/dist/mcp-config-ownership.js

@@ -0,0 +1,79 @@
+/**
+ * Harness MCP config files this package generates wholesale from
+ * `profile.mcp`: exactly one `mcpServers` object whose entries carry only
+ * the fields the generators write. Recognizable by that shape alone (no
+ * schema id to key on), so an existing file holding ONLY those registrations
+ * is this package's earlier output and a new plan replaces it — a per-turn
+ * profile changes these bytes routinely (physim's MCP env carries turn
+ * state). Anything else at the path (a user's own keys, extra fields) still
+ * refuses: the name alone proves nothing, same rule as `opencode.json`.
+ */
+/** Paths owned by this rule. `.gemini/settings.json` is deliberately absent:
+ *  it is a broader user settings file the package only contributes one key
+ *  to, so its bytes cannot prove authorship. */
+export const MATERIALIZER_MCP_CONFIG_PATHS = new Set([
+    ".pi/mcp.json",
+    ".kimi/mcp.json",
+]);
+const GENERATED_MCP_SERVER_KEYS = new Set([
+    "command",
+    "args",
+    "env",
+    "cwd",
+    "url",
+    "httpUrl",
+    "headers",
+    "transport",
+    "enabled",
+    "directTools",
+]);
+/** Parse workspace bytes into the one shape this rule owns, or `null` when
+ *  the bytes are anything else (not an object, other top-level keys, or
+ *  server entries that are not objects). The I/O boundary for
+ *  {@link isGeneratedMcpConfigShape}. */
+export function parseMcpServersConfig(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const { mcpServers } = parsed;
+    if (mcpServers === null ||
+        typeof mcpServers !== "object" ||
+        Array.isArray(mcpServers)) {
+        return null;
+    }
+    for (const server of Object.values(mcpServers)) {
+        if (server === null ||
+            typeof server !== "object" ||
+            Array.isArray(server)) {
+            return null;
+        }
+    }
+    return { mcpServers: mcpServers };
+}
+/** Whether a parsed MCP config carries ONLY the registrations this package
+ *  generates: no extra top-level keys, and every server entry holds only
+ *  generated fields. A user's own key anywhere makes this `false`. */
+export function isGeneratedMcpConfigShape(config) {
+    const keys = Object.keys(config);
+    if (keys.length !== 1 || keys[0] !== "mcpServers")
+        return false;
+    return Object.values(config.mcpServers).every((server) => Object.keys(server).every((key) => GENERATED_MCP_SERVER_KEYS.has(key)));
+}
+/** Whether the existing file at `relPath` is this package's own earlier MCP
+ *  config output (shape rule above). `undefined` content = no regular file. */
+export function isMaterializerMcpConfig(relPath, content) {
+    if (!MATERIALIZER_MCP_CONFIG_PATHS.has(relPath))
+        return false;
+    const bytes = content();
+    if (bytes === undefined)
+        return false;
+    const config = parseMcpServersConfig(bytes);
+    return config !== null && isGeneratedMcpConfigShape(config);
+}

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

@@ -29,8 +29,8 @@ export declare function claimProfileBundle(root: string, claim: ProfileBundleCla
 }) => 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.
+ * stale `incoming/` residue synchronously when the root is idle. A busy root
+ * leaves cleanup to its serialized admissions and sweeps.
  */
 export declare function openProfileBundleCache(root: string, options?: {
     maxBytes?: number;

package/dist/profile-bundle-cache.js

@@ -3,7 +3,7 @@ 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 { evictProfileBundles, evictUnlocked, fsyncDir, hasPendingRootWork, loadLru, pathExists, profileBundleManifestPath, readManifestFile, saveLru, sweepProfileBundleCache, sweepUnlocked, 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";
@@ -116,11 +116,11 @@ function validateManifestFiles(manifest) {
 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 () => {
+        await sweepUnlocked(root);
         const manifestPath = profileBundleManifestPath(root, manifest.bundle);
         const existing = await readManifestFile(manifestPath);
         if (existing && existing.bundle !== manifest.bundle) {
@@ -293,8 +293,8 @@ export async function claimProfileBundle(root, claim, linkFile) {
 }
 /**
  * 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.
+ * stale `incoming/` residue synchronously when the root is idle. A busy root
+ * leaves cleanup to its serialized admissions and sweeps.
  */
 export function openProfileBundleCache(root, options) {
     const maxBytes = options?.maxBytes ?? PROFILE_BUNDLE_DEFAULT_MAX_BYTES;
@@ -305,8 +305,10 @@ export function openProfileBundleCache(root, options) {
     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 });
+    if (!hasPendingRootWork(root)) {
+        for (const entry of readdirSync(incoming)) {
+            rmSync(join(incoming, entry), { recursive: true, force: true });
+        }
     }
     return {
         root,

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

@@ -20,6 +20,8 @@ export interface ProfileBundleLru {
 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>;
+/** Synchronous open must not sweep a root with pending asynchronous work. */
+export declare function hasPendingRootWork(root: string): boolean;
 export declare function readManifestFile(path: string): Promise<{
     schema?: unknown;
     bundle?: unknown;
@@ -32,13 +34,10 @@ export declare function readManifestFile(path: string): Promise<{
  * 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.
- */
+/** Sweep only while holding the per-root lock; active admissions own incoming/. */
 export declare function sweepProfileBundleCache(root: string): Promise<void>;
+/** Remove interrupted admission residue; the caller must hold the per-root lock. */
+export declare function sweepUnlocked(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>;

package/dist/profile-bundle-lru.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { open, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { compareStrings } from "./workspace-files.js";
 export async function pathExists(path) {
     try {
@@ -25,14 +25,24 @@ export async function fsyncDir(dir) {
         // Best-effort durability: a cache without directory fsync still verifies.
     }
 }
-/** Serialize admits/evictions per cache root so lru read-modify-write stays deterministic. */
+/** Serialize admissions, sweeps, and evictions per cache root. */
 const rootQueues = new Map();
 export function withRootLock(root, run) {
-    const previous = rootQueues.get(root) ?? Promise.resolve();
+    const key = resolve(root);
+    const previous = rootQueues.get(key) ?? Promise.resolve();
     const next = previous.then(run, run);
-    rootQueues.set(root, next.catch(() => undefined));
+    const settled = next.then(() => undefined, () => undefined);
+    rootQueues.set(key, settled);
+    void settled.then(() => {
+        if (rootQueues.get(key) === settled)
+            rootQueues.delete(key);
+    });
     return next;
 }
+/** Synchronous open must not sweep a root with pending asynchronous work. */
+export function hasPendingRootWork(root) {
+    return rootQueues.has(resolve(root));
+}
 export async function readManifestFile(path) {
     try {
         return JSON.parse(await readFile(path, "utf8"));
@@ -50,13 +60,12 @@ 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.
- */
+/** Sweep only while holding the per-root lock; active admissions own incoming/. */
 export async function sweepProfileBundleCache(root) {
+    await withRootLock(root, () => sweepUnlocked(root));
+}
+/** Remove interrupted admission residue; the caller must hold the per-root lock. */
+export async function sweepUnlocked(root) {
     const incoming = join(root, "incoming");
     let entries;
     try {

package/dist/profile-materializer.js

@@ -40,6 +40,10 @@ export function executionControlConflict(profile, harness) {
 export function materializeProfile(inputProfile, harness, opts = {}) {
     assertMaterializerHarness(harness);
     const profile = agentProfileSchema.parse(inputProfile);
+    const knowledge = profile.resources && Reflect.get(profile.resources, "knowledge");
+    if (Array.isArray(knowledge) && knowledge.length > 0) {
+        throw new Error("Knowledge source generations must be owner-authorized and resolved by the execution runtime before materialization");
+    }
     const skip = new Set(assertSkippableDimensions(opts.skip));
     const binds = assertBindableLaunchControls(opts.binds);
     const instructionsRoot = opts.instructionsRoot ?? "workspace";

package/dist/workspace-files.d.ts

@@ -1,4 +1,4 @@
-export declare const compareStrings: (a: string, b: string) => 1 | -1 | 0;
+export declare const compareStrings: (a: string, b: string) => 1 | 0 | -1;
 export declare const DEFAULT_FILE_MODE = 420;
 export declare const PRIVATE_FILE_MODE = 384;
 export declare const EXECUTABLE_FILE_MODE = 493;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.23.1",
+  "version": "0.25.3",
   "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": {
@@ -25,14 +25,14 @@
     "dist"
   ],
   "devDependencies": {
-    "@tangle-network/agent-interface": "3.0.0",
-    "@tangle-network/agent-interface-current": "npm:@tangle-network/agent-interface@3.0.0",
+    "@tangle-network/agent-interface": "5.0.0",
+    "@tangle-network/agent-interface-current": "npm:@tangle-network/agent-interface@5.0.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"
   },
   "peerDependencies": {
-    "@tangle-network/agent-interface": "^3.0.0"
+    "@tangle-network/agent-interface": "^3.0.0 || ^4.0.0 || ^5.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",