@tangle-network/agent-profile-materialize 0.15.1 → 0.16.0

package/dist/workspace-apply.js

@@ -0,0 +1,334 @@
+export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, options, publicPlanDigest = hashWorkspacePlan(publicPlan)) {
+    const workspaceRoot = resolve(workspaceDir);
+    const runtimeOnlyFiles = new Set((options.runtimeOnlyFiles ?? []).map(normalizeWorkspaceRelativePath));
+    const existingFiles = options.existingFiles ?? "allow-identical";
+    if (existingFiles !== "allow-identical" && existingFiles !== "reject") {
+        throw new Error(`Unsupported existing workspace file policy: ${existingFiles}`);
+    }
+    const resolvedFiles = resolvedPlan.files;
+    const privateRuntimeFiles = Object.fromEntries(resolvedFiles
+        .filter((file) => runtimeOnlyFiles.has(file.relPath))
+        .map((file) => [file.relPath, file.content]));
+    const files = resolvedFiles
+        .filter((file) => !runtimeOnlyFiles.has(file.relPath))
+        .map((file) => ({
+        ...file,
+        absPath: resolveWorkspaceFilePath(workspaceRoot, file.relPath),
+    }));
+    // A prior application of THIS EXACT plan makes the workspace the running
+    // agent's live state: a file the agent edited or removed since then is the
+    // session's own memory, not a conflict, so a byte comparison against the
+    // plan would refuse a resume the caller proved is unchanged. The digest the
+    // caller passes is its own record of what it already applied here; only the
+    // caller can know that, which is why this is an option and not an inference
+    // from disk. `reject` is not short-circuited: that policy asserts an empty
+    // target and must keep failing on any pre-existing path.
+    if (existingFiles === "allow-identical" &&
+        options.appliedPlanDigest !== undefined &&
+        options.appliedPlanDigest === publicPlanDigest) {
+        return {
+            receipt: safeWorkspacePlanReceipt(publicPlan, files.map((file) => file.relPath), publicPlanDigest),
+            spawn: {
+                env: { ...resolvedPlan.env },
+                flags: [...resolvedPlan.flags],
+                ...promptIntentFields(resolvedPlan, samePromptIntentValue),
+                ...systemPromptBindingField(resolvedPlan),
+            },
+            runtimeOnlyFiles: privateRuntimeFiles,
+        };
+    }
+    // A path this package invented can only hold this package's own earlier
+    // output, so re-applying into the same workspace replaces it rather than
+    // failing the turn. `reject` still refuses: that policy is "nothing may
+    // pre-exist here", which is a statement about the workspace, not authorship.
+    const mayReplace = (file) => existingFiles === "allow-identical" && file.ownership === "materializer";
+    // Validate the complete plan before the first write so a late traversal or
+    // existing symlink cannot leave a partially materialized workspace.
+    for (const file of files) {
+        assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+        if (workspaceFileExists(file.absPath) &&
+            !mayReplace(file) &&
+            (existingFiles === "reject" || !workspaceFileMatches(file))) {
+            throw new Error(workspaceFileConflictMessage(file, existingFiles, publicPlanDigest));
+        }
+    }
+    // Parent directories remain on failure because they may contain concurrent
+    // workspace state that this call does not own.
+    for (const file of files) {
+        mkdirSync(dirname(file.absPath), { recursive: true });
+    }
+    for (const file of files) {
+        assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+    }
+    const prepared = [];
+    // Prepared temp links stay alive through publication and rollback. Their
+    // inodes distinguish files created here from concurrent replacements.
+    try {
+        for (const file of files) {
+            if (existingFiles === "allow-identical" &&
+                workspaceFileExists(file.absPath) &&
+                workspaceFileMatches(file)) {
+                continue;
+            }
+            prepared.push(prepareWorkspaceFile(workspaceRoot, file));
+        }
+        for (const entry of prepared) {
+            assertNoSymlinkPathComponents(workspaceRoot, entry.file.absPath);
+            try {
+                linkSync(entry.temporaryPath, entry.file.absPath);
+                entry.published = true;
+            }
+            catch (error) {
+                if (isFsError(error, "EEXIST") &&
+                    existingFiles === "allow-identical" &&
+                    workspaceFileMatches(entry.file)) {
+                    continue;
+                }
+                if (isFsError(error, "EEXIST") && mayReplace(entry.file)) {
+                    // rename() replaces in one step, so no window exists in which the
+                    // path is missing and a concurrent spawn reads nothing. The staged
+                    // inode moves onto the path, which is what rollback identifies the
+                    // file by, so an abort still removes exactly what this call
+                    // published — leaving the path ABSENT rather than restored to the
+                    // superseded bytes. That is the fail-closed direction: the harness
+                    // whose flag names a missing file refuses to start, whereas silently
+                    // restored previous-turn bytes would run the wrong prompt.
+                    assertNoSymlinkPathComponents(workspaceRoot, entry.file.absPath);
+                    renameSync(entry.temporaryPath, entry.file.absPath);
+                    entry.published = true;
+                    continue;
+                }
+                if (isFsError(error, "EEXIST")) {
+                    throw new Error(workspaceFileConflictMessage(entry.file, existingFiles, publicPlanDigest), { cause: error });
+                }
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        const cleanupErrors = [];
+        for (const entry of [...prepared].reverse()) {
+            try {
+                if (entry.published &&
+                    workspacePathHasIdentity(entry.file.absPath, entry.identity)) {
+                    unlinkSync(entry.file.absPath);
+                }
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            try {
+                if (workspacePathHasIdentity(entry.temporaryPath, entry.identity)) {
+                    unlinkSync(entry.temporaryPath);
+                }
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError([error, ...cleanupErrors], "Failed to apply workspace plan and roll back published files");
+        }
+        throw error;
+    }
+    const receipt = safeWorkspacePlanReceipt(publicPlan, files.map((file) => file.relPath), publicPlanDigest);
+    const cleanupErrors = [];
+    const temporaryPaths = [];
+    for (const entry of prepared) {
+        try {
+            unlinkSync(entry.temporaryPath);
+        }
+        catch (error) {
+            if (!isFsError(error, "ENOENT")) {
+                cleanupErrors.push(error);
+                temporaryPaths.push(entry.temporaryPath);
+            }
+        }
+    }
+    if (cleanupErrors.length > 0) {
+        throw new WorkspacePlanCleanupError(cleanupErrors, receipt, temporaryPaths);
+    }
+    return {
+        receipt,
+        spawn: {
+            env: { ...resolvedPlan.env },
+            flags: [...resolvedPlan.flags],
+            ...promptIntentFields(resolvedPlan, samePromptIntentValue),
+            ...systemPromptBindingField(resolvedPlan),
+        },
+        runtimeOnlyFiles: privateRuntimeFiles,
+    };
+}
+function workspaceFileExists(pathValue) {
+    try {
+        lstatSync(pathValue);
+        return true;
+    }
+    catch (error) {
+        if (isFsError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function workspaceFileMatches(file) {
+    const stats = lstatSync(file.absPath);
+    return (stats.isFile() &&
+        (stats.mode & 0o777) === file.mode &&
+        readFileSync(file.absPath, "utf8") === file.content);
+}
+function sha256Hex(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/**
+ * The refusal names what differs — planned versus existing content digest,
+ * mode, or file kind — plus the plan digest, so the operator can tell a
+ * mid-session profile swap from an agent-edited workspace file without
+ * reproducing the workspace. Reads here are best-effort diagnosis inside an
+ * already-failing path; an unreadable existing file is reported, not thrown
+ * over.
+ */
+function workspaceFileConflictMessage(file, existingFiles, planDigest) {
+    const prefix = `Refusing to replace existing workspace file: ${file.relPath}`;
+    if (existingFiles === "reject") {
+        return `${prefix} — the reject policy forbids any pre-existing plan path (plan ${planDigest})`;
+    }
+    const planned = `planned sha256:${sha256Hex(file.content)} mode ${file.mode.toString(8)}`;
+    let existing;
+    try {
+        const stats = lstatSync(file.absPath);
+        if (!stats.isFile()) {
+            existing = stats.isSymbolicLink()
+                ? "existing path is a symlink, not a regular file"
+                : "existing path is not a regular file";
+        }
+        else {
+            const mode = (stats.mode & 0o777).toString(8);
+            existing = `existing sha256:${sha256Hex(readFileSync(file.absPath))} mode ${mode}`;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        existing = `existing file unreadable: ${message}`;
+    }
+    return `${prefix} — ${planned} != ${existing} (plan ${planDigest})`;
+}
+function prepareWorkspaceFile(workspaceRoot, file) {
+    assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+    const temporaryPath = join(dirname(file.absPath), `.agent-profile-${randomUUID()}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(temporaryPath, SAFE_WRITE_FLAGS, 0o600);
+        writeFileSync(descriptor, file.content, "utf8");
+        fchmodSync(descriptor, file.mode);
+        const stats = fstatSync(descriptor);
+        const descriptorToClose = descriptor;
+        descriptor = undefined;
+        closeSync(descriptorToClose);
+        return {
+            file,
+            temporaryPath,
+            identity: { device: stats.dev, inode: stats.ino },
+            published: false,
+        };
+    }
+    catch (error) {
+        const cleanupErrors = [];
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+        }
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch (cleanupError) {
+            if (!isFsError(cleanupError, "ENOENT"))
+                cleanupErrors.push(cleanupError);
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError([error, ...cleanupErrors], `Failed to prepare workspace file: ${file.relPath}`);
+        }
+        throw error;
+    }
+}
+function workspacePathHasIdentity(pathValue, identity) {
+    try {
+        const stats = lstatSync(pathValue);
+        return stats.dev === identity.device && stats.ino === identity.inode;
+    }
+    catch (error) {
+        if (isFsError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function resolveWorkspaceFilePath(workspaceRoot, relativePath) {
+    const targetPath = resolve(workspaceRoot, ...relativePath.split("/"));
+    const targetRelativePath = relative(workspaceRoot, targetPath);
+    if (!targetRelativePath ||
+        targetRelativePath === ".." ||
+        targetRelativePath.startsWith(`..${sep}`) ||
+        isAbsolute(targetRelativePath)) {
+        throw new Error(`Refusing to materialize profile file outside workspace: ${relativePath}`);
+    }
+    return targetPath;
+}
+function assertNoSymlinkPathComponents(workspaceRoot, targetPath) {
+    const targetRelativePath = relative(workspaceRoot, targetPath);
+    let currentPath = workspaceRoot;
+    const components = ["", ...targetRelativePath.split(sep)];
+    for (const [index, component] of components.entries()) {
+        if (component)
+            currentPath = join(currentPath, component);
+        let stats;
+        try {
+            stats = lstatSync(currentPath);
+        }
+        catch (error) {
+            if (isFsError(error, "ENOENT"))
+                return;
+            if (isFsError(error, "ELOOP")) {
+                throw new Error(`Refusing to materialize profile file through symlink path: ${targetRelativePath}`);
+            }
+            throw error;
+        }
+        if (stats.isSymbolicLink()) {
+            throw new Error(`Refusing to materialize profile file through symlink path: ${targetRelativePath}`);
+        }
+        const isTarget = index === components.length - 1;
+        if ((!isTarget && !stats.isDirectory()) || (isTarget && !stats.isFile())) {
+            throw new Error(`Refusing to materialize profile file through non-file path: ${targetRelativePath}`);
+        }
+    }
+}
+function isFsError(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+export function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorkspacePlan(plan)) {
+    return {
+        workspacePlanDigest,
+        env: Object.fromEntries(Object.entries(plan.env).map(([name, value]) => [
+            name,
+            typeof value === "string" ? value : { ...value },
+        ])),
+        flags: plan.flags.map(normalizeWorkspacePlanArgument),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
+        unsupported: plan.unsupported.map((entry) => ({ ...entry })),
+        written: [...written],
+    };
+}
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, fchmodSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { hashWorkspacePlan } from "./plan-digest.js";
+import { normalizeWorkspacePlanArgument, } from "./plan-normalize.js";
+import { promptIntentFields, samePromptIntentValue, systemPromptBindingField, } from "./plan-prompt.js";
+import { WorkspacePlanCleanupError } from "./plan-types.js";
+import { normalizeWorkspaceRelativePath, SAFE_WRITE_FLAGS, } from "./workspace-files.js";

package/dist/workspace-files.d.ts

@@ -0,0 +1,8 @@
+export declare const compareStrings: (a: string, b: string) => 0 | 1 | -1;
+export declare const DEFAULT_FILE_MODE = 420;
+export declare const PRIVATE_FILE_MODE = 384;
+export declare const EXECUTABLE_FILE_MODE = 493;
+export declare const SAFE_WRITE_FLAGS: number;
+export declare function normalizeWorkspaceRelativePath(pathValue: string): string;
+export declare function hasControlCharacter(value: string): boolean;
+export declare function validateFileMode(mode: number | undefined): number;

package/dist/workspace-files.js

@@ -0,0 +1,46 @@
+export const compareStrings = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+export const DEFAULT_FILE_MODE = 0o644;
+export const PRIVATE_FILE_MODE = 0o600;
+export const EXECUTABLE_FILE_MODE = 0o755;
+export const SAFE_WRITE_FLAGS = fsConstants.O_WRONLY |
+    fsConstants.O_CREAT |
+    fsConstants.O_EXCL |
+    (typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0);
+export function normalizeWorkspaceRelativePath(pathValue) {
+    if (typeof pathValue !== "string" ||
+        !pathValue ||
+        hasControlCharacter(pathValue)) {
+        throw new Error("Workspace file path must be non-empty and contain no control characters");
+    }
+    if (isAbsolute(pathValue) ||
+        win32.isAbsolute(pathValue) ||
+        /^[A-Za-z]:/.test(pathValue)) {
+        throw new Error(`Workspace file path must be relative: ${pathValue}`);
+    }
+    const segments = pathValue.replace(/\\/g, "/").split("/");
+    if (segments.some((segment) => !segment ||
+        segment === "." ||
+        segment === ".." ||
+        segment === ".git" ||
+        segment === ".sidecar")) {
+        throw new Error(`Workspace file path must be canonical: ${pathValue}`);
+    }
+    return segments.join("/");
+}
+export function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+export function validateFileMode(mode) {
+    const normalized = mode ?? DEFAULT_FILE_MODE;
+    if (!Number.isInteger(normalized) || normalized < 0 || normalized > 0o777) {
+        throw new Error(`Workspace file mode must be between 0o000 and 0o777: ${mode}`);
+    }
+    return normalized;
+}
+import { constants as fsConstants } from "node:fs";
+import { isAbsolute, win32 } from "node:path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.15.1",
+  "version": "0.16.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",
@@ -20,13 +20,13 @@
     "dist"
   ],
   "devDependencies": {
-    "@tangle-network/agent-interface": "0.53.0",
+    "@tangle-network/agent-interface": "1.0.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@tangle-network/agent-interface": ">=0.47.0 <0.54.0"
+    "@tangle-network/agent-interface": "^1.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",