@tea-agent/loop-agent 0.26.2 → 0.26.4

package/dist/executors/pi-writer-tool-policy.js

@@ -0,0 +1,266 @@
+import { access as fsAccess, lstat, mkdir as fsMkdir, readFile as fsReadFile, realpath, writeFile as fsWriteFile, } from "node:fs/promises";
+import path from "node:path";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+export class PiWriterPathDeniedError extends Error {
+    code;
+    targetPath;
+    constructor(code, targetPath, detail) {
+        super(detail
+            ? `pi writer path denied (${code}): ${targetPath}: ${detail}`
+            : `pi writer path denied (${code}): ${targetPath}`);
+        this.name = "PiWriterPathDeniedError";
+        this.code = code;
+        this.targetPath = targetPath;
+    }
+}
+const HARD_FORBIDDEN_PREFIXES = [
+    ".harness/tasks/",
+    ".harness/dag-runs/",
+];
+function normalizeRepoRelative(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function matchesAnyPattern(filePath, patterns) {
+    return patterns.some((pattern) => pathMatchesPattern(filePath, pattern));
+}
+function isPathInside(root, target) {
+    const normalizedRoot = path.resolve(root);
+    const normalizedTarget = path.resolve(target);
+    const rootWithSep = normalizedRoot.endsWith(path.sep)
+        ? normalizedRoot
+        : `${normalizedRoot}${path.sep}`;
+    return (normalizedTarget === normalizedRoot ||
+        normalizedTarget.startsWith(rootWithSep));
+}
+async function resolveRealIfExists(absPath) {
+    try {
+        return await realpath(absPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the effective mutation destination from the nearest existing
+ * ancestor's real path plus the unresolved suffix. This catches in-repo
+ * symlinks that redirect an authorized lexical path into a forbidden area.
+ */
+async function resolveEffectiveMutationTarget(repoRoot, absoluteTarget) {
+    const realRoot = (await resolveRealIfExists(repoRoot)) ?? path.resolve(repoRoot);
+    let current = path.resolve(absoluteTarget);
+    const suffix = [];
+    while (true) {
+        try {
+            const st = await lstat(current);
+            const real = await resolveRealIfExists(current);
+            if (!real) {
+                throw new PiWriterPathDeniedError(st.isSymbolicLink() ? "symlink-escape" : "ancestor-escape", absoluteTarget, `cannot resolve existing ancestor ${current}`);
+            }
+            const effectiveTarget = path.resolve(real, ...suffix);
+            if (!isPathInside(realRoot, effectiveTarget)) {
+                throw new PiWriterPathDeniedError(st.isSymbolicLink() ? "symlink-escape" : "ancestor-escape", absoluteTarget, `effective mutation target ${effectiveTarget} escapes repo`);
+            }
+            return { realRoot, absoluteTarget: effectiveTarget };
+        }
+        catch (error) {
+            if (error instanceof PiWriterPathDeniedError)
+                throw error;
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR") {
+                throw new PiWriterPathDeniedError("ancestor-escape", absoluteTarget, `cannot inspect ancestor ${current}`);
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new PiWriterPathDeniedError("outside-repo", absoluteTarget, "no existing repository ancestor found");
+        }
+        suffix.unshift(path.basename(current));
+        current = parent;
+    }
+}
+function isPathAtOrBelowDirectory(candidatePath, directoryPath) {
+    const candidate = normalizeRepoRelative(candidatePath);
+    const directory = normalizeRepoRelative(directoryPath);
+    return (candidate.length > 0 &&
+        (directory.length === 0 ||
+            candidate === directory ||
+            candidate.startsWith(`${directory}/`)));
+}
+function isHardForbidden(relPath) {
+    const normalized = normalizeRepoRelative(relPath);
+    if (normalized === ".harness/tasks" ||
+        normalized === ".harness/dag-runs" ||
+        normalized.startsWith(".harness/tasks/") ||
+        normalized.startsWith(".harness/dag-runs/")) {
+        return true;
+    }
+    return HARD_FORBIDDEN_PREFIXES.some((prefix) => matchesAnyPattern(normalized, [`${prefix}**`, prefix.slice(0, -1)]));
+}
+function repoRelativePath(root, absoluteTarget, raw, allowRoot) {
+    const relative = normalizeRepoRelative(path.relative(root, absoluteTarget));
+    if ((!allowRoot && !relative) ||
+        path.isAbsolute(relative) ||
+        relative.startsWith("..")) {
+        throw new PiWriterPathDeniedError("outside-repo", raw);
+    }
+    return relative;
+}
+function assertWritableRelative(relative, ctx) {
+    if (isHardForbidden(relative)) {
+        throw new PiWriterPathDeniedError("hard-forbidden", relative, "writes under .harness/tasks/** or .harness/dag-runs/** are never allowed for Pi writers");
+    }
+    const forbidden = ctx.forbiddenPaths ?? [];
+    if (forbidden.length > 0 && matchesAnyPattern(relative, forbidden)) {
+        throw new PiWriterPathDeniedError("forbidden", relative);
+    }
+    const writeSet = ctx.writeSet ?? [];
+    if ((ctx.writePolicy ?? "exclusive") === "exclusive" &&
+        (writeSet.length === 0 || !matchesAnyPattern(relative, writeSet))) {
+        throw new PiWriterPathDeniedError("not-in-write-set", relative);
+    }
+    const allowedPaths = ctx.allowedPaths ?? [];
+    if (allowedPaths.length === 0 || !matchesAnyPattern(relative, allowedPaths)) {
+        throw new PiWriterPathDeniedError("not-in-allowed-paths", relative);
+    }
+}
+function assertMkdirRelative(relative, ctx) {
+    if (relative && isHardForbidden(relative)) {
+        throw new PiWriterPathDeniedError("hard-forbidden", relative);
+    }
+    const forbidden = ctx.forbiddenPaths ?? [];
+    if (relative &&
+        forbidden.length > 0 &&
+        matchesAnyPattern(relative, forbidden)) {
+        throw new PiWriterPathDeniedError("forbidden", relative);
+    }
+    const writeSetCandidates = (ctx.writeSet ?? [])
+        .map(normalizeRepoRelative)
+        .filter((candidate) => isPathAtOrBelowDirectory(candidate, relative) ||
+        (relative.length > 0 && pathMatchesPattern(relative, candidate)));
+    if (writeSetCandidates.length === 0) {
+        throw new PiWriterPathDeniedError("not-in-write-set", relative || ".");
+    }
+    const allowedPaths = ctx.allowedPaths ?? [];
+    const allowedCandidates = writeSetCandidates.filter((candidate) => matchesAnyPattern(candidate, allowedPaths));
+    if (allowedPaths.length === 0 || allowedCandidates.length === 0) {
+        throw new PiWriterPathDeniedError("not-in-allowed-paths", relative || ".");
+    }
+    const nonHardForbiddenCandidates = allowedCandidates.filter((candidate) => !isHardForbidden(candidate));
+    if (nonHardForbiddenCandidates.length === 0) {
+        throw new PiWriterPathDeniedError("hard-forbidden", relative || ".");
+    }
+    if (forbidden.length > 0 &&
+        nonHardForbiddenCandidates.every((candidate) => matchesAnyPattern(candidate, forbidden))) {
+        throw new PiWriterPathDeniedError("forbidden", relative || ".");
+    }
+}
+/**
+ * Assert a mutation target is writable under the DAG writer policy.
+ * Returns the normalized lexical repo-relative path on success.
+ */
+export async function assertWritablePath(targetPath, ctx) {
+    const raw = String(targetPath ?? "").trim();
+    if (!raw) {
+        throw new PiWriterPathDeniedError("empty-path", targetPath ?? "");
+    }
+    const repoRoot = path.resolve(ctx.repoRoot);
+    const absoluteTarget = path.isAbsolute(raw)
+        ? path.resolve(raw)
+        : path.resolve(repoRoot, raw);
+    if (!isPathInside(repoRoot, absoluteTarget)) {
+        throw new PiWriterPathDeniedError("outside-repo", raw, "path resolves outside repository root");
+    }
+    const effective = await resolveEffectiveMutationTarget(repoRoot, absoluteTarget);
+    const lexicalRelative = repoRelativePath(repoRoot, absoluteTarget, raw, false);
+    const effectiveRelative = repoRelativePath(effective.realRoot, effective.absoluteTarget, raw, false);
+    assertWritableRelative(lexicalRelative, ctx);
+    assertWritableRelative(effectiveRelative, ctx);
+    return lexicalRelative;
+}
+/**
+ * Intermediate directory creation is authorized only when both the lexical
+ * directory and its effective real destination are ancestors of a target that
+ * satisfies the complete writer boundary.
+ */
+export async function assertMkdirPath(dirPath, ctx) {
+    const raw = String(dirPath ?? "").trim();
+    if (!raw) {
+        throw new PiWriterPathDeniedError("empty-path", dirPath ?? "");
+    }
+    const repoRoot = path.resolve(ctx.repoRoot);
+    const absoluteTarget = path.isAbsolute(raw)
+        ? path.resolve(raw)
+        : path.resolve(repoRoot, raw);
+    if (!isPathInside(repoRoot, absoluteTarget)) {
+        throw new PiWriterPathDeniedError("outside-repo", raw);
+    }
+    const effective = await resolveEffectiveMutationTarget(repoRoot, absoluteTarget);
+    const lexicalRelative = repoRelativePath(repoRoot, absoluteTarget, raw, true);
+    const effectiveRelative = repoRelativePath(effective.realRoot, effective.absoluteTarget, raw, true);
+    assertMkdirRelative(lexicalRelative, ctx);
+    assertMkdirRelative(effectiveRelative, ctx);
+    return lexicalRelative;
+}
+/** Build FS operations that enforce writer policy before mutations. */
+export function createPiWriterFsOperations(ctx) {
+    return {
+        readFile: (absolutePath) => fsReadFile(absolutePath),
+        access: async (absolutePath) => {
+            await fsAccess(absolutePath);
+        },
+        writeFile: async (absolutePath, content) => {
+            await assertWritablePath(absolutePath, ctx);
+            await fsWriteFile(absolutePath, content, "utf-8");
+        },
+        mkdir: async (dir) => {
+            await assertMkdirPath(dir, ctx);
+            await fsMkdir(dir, { recursive: true });
+        },
+    };
+}
+/**
+ * Create same-name custom edit/write tool definitions that override built-ins
+ * via Pi SDK customTools registration. Fails closed when SDK factories are missing.
+ */
+export async function createPiWriterCustomTools(ctx) {
+    const sdk = (await import("@earendil-works/pi-coding-agent"));
+    const createEditToolDefinition = sdk.createEditToolDefinition;
+    const createWriteToolDefinition = sdk.createWriteToolDefinition;
+    if (typeof createEditToolDefinition !== "function" ||
+        typeof createWriteToolDefinition !== "function") {
+        throw new Error("pi writer tool policy unavailable: createEditToolDefinition/createWriteToolDefinition missing from SDK");
+    }
+    const ops = createPiWriterFsOperations(ctx);
+    const cwd = path.resolve(ctx.repoRoot);
+    const edit = createEditToolDefinition(cwd, {
+        operations: {
+            readFile: ops.readFile,
+            writeFile: ops.writeFile,
+            access: ops.access,
+        },
+    });
+    const write = createWriteToolDefinition(cwd, {
+        operations: {
+            writeFile: ops.writeFile,
+            mkdir: ops.mkdir,
+        },
+    });
+    if (edit?.name !== "edit" || write?.name !== "write") {
+        throw new Error("pi writer tool policy unavailable: SDK tool definitions must be named edit/write");
+    }
+    return [edit, write];
+}
+/** Build a policy context from a DAG task-like write boundary. */
+export function buildPiWriterToolPolicyContext(input) {
+    const repoRoot = String(input.repoRoot ?? "").trim();
+    if (!repoRoot) {
+        throw new Error("pi writer tool policy requires non-empty repoRoot");
+    }
+    return {
+        repoRoot: path.resolve(repoRoot),
+        allowedPaths: input.allowedPaths ?? [],
+        writeSet: input.writeSet ?? [],
+        forbiddenPaths: input.forbiddenPaths ?? [],
+        writePolicy: input.writePolicy ?? "exclusive",
+    };
+}