@parcha/pi-durable-disk 0.0.0-stage → 0.1.0-beta.13

package/dist/confine.js

@@ -0,0 +1,341 @@
+// Containment of the in-process file operations. pi's read, write and edit run in the loop's process with host
+// fs calls and no containment, so an agent can name `../store/run.sqlite`, `../run.json` or `../owner.lock` and corrupt
+// its own durable store or claim; a sandbox that confines commands (an app's own) does not cover them. Every path an operation names is
+// resolved to the file the kernel would reach (symlinks followed, a missing tail kept) and refused unless it lies in the
+// workspace, or, for reads, in a read-only root.
+//
+// The check alone is a check-then-use: a command running next to the tool can swap a component for a symlink between the
+// check and the open. So the operation never walks the path again. The resolved path is opened one component at a time
+// from a pinned directory handle of its root, each step relative to the previous handle and with O_NOFOLLOW, which is
+// openat2(RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS) done in user space. Node has no openat, so a handle's directory is named
+// `/proc/self/fd/<fd>`: the kernel jumps straight to the held inode there and never re-walks the directory's own path. A
+// swapped component fails the open (ELOOP or ENOTDIR) and the call is refused as changed; nothing is retried.
+import { constants, existsSync, realpathSync } from "node:fs";
+import { lstat, mkdir, open, readlink, realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { err, FileError, ok } from "@earendil-works/pi-durable/env";
+/**
+ * A file operation named a path that is not under the workspace (`outside_work`), or one whose components changed
+ * while it was being resolved (`changed`). pi turns it into a failed tool result that names the path. Its `code` is pi's
+ * `permission_denied`.
+ */
+export class PathOutsideWorkError extends FileError {
+    reason;
+    constructor(path, reason, message) {
+        super("permission_denied", message, path);
+        this.name = "PathOutsideWorkError";
+        this.reason = reason;
+    }
+}
+const MAX_LINKS = 40;
+const DIRECTORY = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+// Nonblocking, so opening a FIFO does not wait for a peer; a regular file is unaffected.
+const FILE = constants.O_NOFOLLOW | constants.O_NONBLOCK;
+/** Test seam: runs after a path was resolved and checked, before anything is opened. */
+export const confineHooks = {};
+function errno(error) {
+    const code = error instanceof Error ? error.code : undefined;
+    return typeof code === "string" ? code : undefined;
+}
+const isMissing = (error) => errno(error) === "ENOENT" || errno(error) === "ENOTDIR";
+const FILE_ERRORS = {
+    ABORT_ERR: "aborted",
+    ENOENT: "not_found",
+    EACCES: "permission_denied",
+    EPERM: "permission_denied",
+    ENOTDIR: "not_directory",
+    EISDIR: "is_directory",
+    EINVAL: "invalid",
+    ELOOP: "invalid",
+};
+/** pi's mapping from a Node error to its `FileError` codes (pi does not export it). */
+export function fileError(error, path) {
+    if (error instanceof FileError)
+        return error;
+    const cause = error instanceof Error ? error : new Error(String(error));
+    const code = errno(cause);
+    return new FileError((code !== undefined && FILE_ERRORS[code]) || "unknown", cause.message, path, cause);
+}
+/**
+ * The path the kernel would reach for `path` (absolute, lexically normalized): every existing component resolved,
+ * symlinks included, dangling ones followed to where they would create; a missing tail is appended as it is.
+ */
+export async function canonicalize(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    let resolved = "/";
+    let links = 0;
+    const pending = path.split("/").filter((part) => part !== "");
+    while (pending.length > 0) {
+        const name = pending.shift();
+        if (name === ".")
+            continue;
+        if (name === "..") {
+            resolved = dirname(resolved);
+            continue;
+        }
+        const next = join(resolved, name);
+        let stats;
+        try {
+            stats = await lstat(next);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return join(next, ...pending);
+            throw error;
+        }
+        if (!stats.isSymbolicLink()) {
+            resolved = next;
+            continue;
+        }
+        if (++links > MAX_LINKS)
+            throw Object.assign(new Error(`ELOOP: too many symbolic links, '${path}'`), { code: "ELOOP" });
+        const target = await readlink(next);
+        if (target.startsWith("/"))
+            resolved = "/";
+        pending.unshift(...target.split("/").filter((part) => part !== ""));
+    }
+    return resolved;
+}
+/** `canonicalize` for a directory that may not exist yet, at construction. */
+export function canonicalizeSync(path) {
+    let existing = path;
+    const tail = [];
+    while (!existsSync(existing)) {
+        const up = dirname(existing);
+        if (up === existing)
+            break;
+        tail.unshift(basename(existing));
+        existing = up;
+    }
+    return join(realpathSync(existing), ...tail);
+}
+export const inside = (path, root) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
+const FILE_INFO_KEYS = ["name", "path", "kind", "size", "mtimeMs"];
+const isFileInfo = (value) => typeof value === "object" && value !== null && FILE_INFO_KEYS.every((key) => key in value) && typeof value.path === "string";
+/**
+ * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths to hand to pi's own implementation; every
+ * path and message it returns is mapped back to the real one with `restore`. Close it when the operation is done.
+ */
+export class Pin {
+    canonical;
+    /** The last component, or "" when the target is the root itself. */
+    name;
+    /** The held directory: the target itself for a directory pin, the directory holding the target for an entry pin. */
+    dir;
+    /** The target below `dir`, for operations that do not follow a last symlink. */
+    entry;
+    #handle;
+    /** What `dir` stands for: the directory itself, or the directory holding the entry. */
+    #real;
+    #closed = false;
+    constructor(handle, canonical, name, dirMode) {
+        this.#handle = handle;
+        this.canonical = canonical;
+        this.name = name;
+        this.dir = `/proc/self/fd/${handle.fd}`;
+        this.entry = dirMode ? this.dir : name === "" ? `${this.dir}/.` : `${this.dir}/${name}`;
+        this.#real = dirMode || name === "" ? canonical : dirname(canonical);
+    }
+    /** `text` with the held paths replaced by the real ones. */
+    translate(text) {
+        return text.split(this.entry).join(this.canonical).split(this.dir).join(this.#real);
+    }
+    /** An error pi or Node raised on a held path, as a FileError that names the real one. */
+    error(error, path) {
+        if (error instanceof PathOutsideWorkError)
+            return error;
+        const mapped = fileError(error, path);
+        return new FileError(mapped.code, this.translate(mapped.message), mapped.path === undefined ? path : this.translate(mapped.path), mapped.cause instanceof Error ? mapped.cause : undefined);
+    }
+    restore(result) {
+        if (!result.ok)
+            return err(this.error(result.error, result.error.path ?? this.canonical));
+        return ok(this.#value(result.value));
+    }
+    #value(value) {
+        if (Array.isArray(value))
+            return value.map((each) => this.#value(each));
+        if (isFileInfo(value))
+            return { ...value, path: this.translate(value.path) };
+        // A page of a directory reader.
+        if (typeof value === "object" && value !== null && "entries" in value && Array.isArray(value.entries)) {
+            return { ...value, entries: this.#value(value.entries) };
+        }
+        return value;
+    }
+    /** Opens the target's last component, which is never followed, and returns its handle; the caller closes it. */
+    async openFile(flags, mode) {
+        try {
+            return await open(this.entry, flags | FILE, mode);
+        }
+        catch (error) {
+            if (errno(error) === "ELOOP")
+                throw changed(this.canonical);
+            throw error;
+        }
+    }
+    binaryReader(reader) {
+        return {
+            info: async (context) => this.restore(await reader.info(context)),
+            read: (offset, length, context) => reader.read(offset, length, context),
+            scanLines: (options, context) => reader.scanLines(options, context),
+            close: (context) => reader.close(context),
+        };
+    }
+    /** The reader keeps the pin open: pi's reader names each entry through `dir` as it pages. */
+    dirReader(reader) {
+        return {
+            next: async (maxEntries, context) => this.restore(await reader.next(maxEntries, context)),
+            close: async (context) => {
+                try {
+                    await reader.close(context);
+                }
+                finally {
+                    await this.close();
+                }
+            },
+        };
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await this.#handle.close().catch(() => undefined);
+    }
+}
+const changed = (path) => new PathOutsideWorkError(path, "changed", `${path}: a component of the path changed while it was being resolved, so the operation was refused`);
+export class Confinement {
+    work;
+    readOnly;
+    /** Directories handed out for writing after construction (the environment's temp dirs), canonical. */
+    #handed = new Set();
+    /** Canonical directories: `work` may be read and written, `readOnly` only read. */
+    constructor(work, readOnly) {
+        this.work = work;
+        this.readOnly = readOnly;
+    }
+    /**
+     * Lets file operations write inside `dir` too: a directory this process just created (`createTempDir`) directly in a
+     * read-only root, for the tool it is handed to. `dir` is that root joined with the new name, never resolved: if the
+     * directory is later swapped for a link, a path through it resolves elsewhere and is refused.
+     */
+    allowWrites(dir) {
+        if (this.readOnly.some((root) => dirname(dir) === root))
+            this.#handed.add(dir);
+    }
+    /** `dir` was removed: writes inside it, or inside any handed directory below it, are no longer allowed. */
+    forgetWrites(dir) {
+        for (const handed of this.#handed)
+            if (inside(handed, dir))
+                this.#handed.delete(handed);
+    }
+    /** Resolves `abs` and refuses it unless it lies under an allowed root; returns the root that holds it. */
+    async locate(abs, original, access, follow) {
+        const canonical = follow ? await canonicalize(abs) : join(await canonicalize(dirname(abs)), basename(abs));
+        const roots = access === "write" ? [this.work, ...this.#handed] : [this.work, ...this.#handed, ...this.readOnly];
+        const root = roots.find((candidate) => inside(canonical, candidate));
+        if (root === undefined) {
+            const where = canonical === abs ? "" : ` (it resolves to ${canonical})`;
+            throw new PathOutsideWorkError(original, "outside_work", `${original}: outside the workspace ${this.work}${where}`);
+        }
+        return { canonical, root };
+    }
+    /** Pins the directory holding the target (or the root, when it is the target). */
+    async pinEntry(abs, original, spec) {
+        const { canonical, root } = await this.locate(abs, original, spec.access, spec.follow);
+        await confineHooks.afterCheck?.(canonical);
+        const names = relative(root, canonical);
+        if (names.length === 0 && spec.strict === true) {
+            // a handed directory itself (a tool removing the temp dir it was given): pinned as an entry of the read-only root that
+            // holds it, so it can go; the workspace root never can
+            const holder = this.#handed.has(root) ? this.readOnly.find((candidate) => dirname(root) === candidate) : undefined;
+            if (holder === undefined)
+                throw new PathOutsideWorkError(original, "outside_work", `${original}: the workspace root itself cannot be removed or renamed`);
+            return new Pin(await walk(holder, [], "none", canonical), canonical, basename(root), false);
+        }
+        const name = names.pop() ?? "";
+        const handle = await walk(root, names, spec.parents === true ? "all" : "none", canonical);
+        return new Pin(handle, canonical, name, false);
+    }
+    /** Pins the target directory itself; `create` makes it and the directories above it when they are missing. */
+    async pinDir(abs, original, spec) {
+        const { canonical, root } = await this.locate(abs, original, spec.access, true);
+        await confineHooks.afterCheck?.(canonical);
+        const handle = await walk(root, relative(root, canonical), spec.create === true ? "all" : "none", canonical);
+        return new Pin(handle, canonical, basename(canonical), true);
+    }
+}
+const relative = (root, path) => (path === root ? [] : path.slice(root.length + (root.endsWith("/") ? 0 : 1)).split("/"));
+/** The error with the held path `from` in its message replaced by the real one; the errno is kept. */
+function retarget(error, from, to) {
+    if (!(error instanceof Error))
+        return error;
+    return Object.assign(new Error(error.message.split(from).join(to), { cause: error }), { code: errno(error) });
+}
+/** Whether a failed directory open found a symlink: O_DIRECTORY with O_NOFOLLOW reports it as ENOTDIR, as it does a file. */
+async function swapped(error, path) {
+    if (errno(error) === "ELOOP")
+        return true;
+    if (errno(error) !== "ENOTDIR")
+        return false;
+    return (await lstat(path).catch(() => undefined))?.isSymbolicLink() === true;
+}
+/** Opens `root`, then each name below it, every step relative to the handle before it and without following links. */
+async function walk(root, names, create, canonical) {
+    let dir;
+    try {
+        dir = await open(root, DIRECTORY);
+    }
+    catch (error) {
+        if (await swapped(error, root))
+            throw changed(canonical);
+        throw error;
+    }
+    try {
+        // The root was opened by name: it must be the directory that name denotes now, not one swapped in on the way.
+        const actual = await readlink(`/proc/self/fd/${dir.fd}`);
+        if (actual !== root)
+            throw changed(canonical);
+        let real = root;
+        for (const name of names) {
+            if (name === "" || name === "." || name === ".." || name.includes("\0"))
+                throw changed(canonical);
+            const step = `/proc/self/fd/${dir.fd}/${name}`;
+            real = join(real, name);
+            let next;
+            try {
+                next = await open(step, DIRECTORY);
+            }
+            catch (error) {
+                if (create === "all" && errno(error) === "ENOENT") {
+                    await mkdir(step).catch((made) => {
+                        if (errno(made) !== "EEXIST")
+                            throw retarget(made, step, real);
+                    });
+                    next = await open(step, DIRECTORY).catch((opened) => {
+                        throw retarget(opened, step, real);
+                    });
+                }
+                else if (await swapped(error, step)) {
+                    throw changed(canonical);
+                }
+                else {
+                    throw retarget(error, step, real);
+                }
+            }
+            await dir.close();
+            dir = next;
+        }
+        return dir;
+    }
+    catch (error) {
+        await dir.close().catch(() => undefined);
+        throw error;
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,129 @@
+import type { Context } from "@earendil-works/chord";
+import type { Extension, ToolHooks, ToolRegistration } from "@earendil-works/pi-durable";
+import { ExecutionError } from "@earendil-works/pi-durable/env";
+import { NodeExecutionEnv, type NodeWatchOptions } from "@earendil-works/pi-durable/env/node";
+import { PdaError } from "./errors.js";
+type ToolCall = Parameters<ToolHooks["afterTool"]>[0];
+/** What the environment needs of a claim; the claim satisfies it structurally. */
+export interface ArchilEnvClaim {
+    /** Absolute mount path of the run directory; the same on every host that claims the run. */
+    readonly root: string;
+    /** Absolute path of the workspace the tools write: `<root>/work`. */
+    readonly work: string;
+    /** The disk's id; part of the environment id when present. */
+    readonly disk?: string;
+    /**
+     * Where the commands this environment starts are recorded, so that the next open of the claim ends what a killed
+     * incarnation left running (`reapCommands`). Set by a claim that nothing else cleans up after: a local run's.
+     */
+    readonly commands?: string;
+}
+export interface ArchilEnvOptions {
+    /** How `watch` runs. Polling is the default because a FUSE mount does not report changes made elsewhere. */
+    readonly watch?: NodeWatchOptions;
+    readonly shellPath?: string;
+    readonly shellEnv?: NodeJS.ProcessEnv;
+    /**
+     * Run every command with no_new_privs (`setpriv --no-new-privs --`): setuid programs and file capabilities stop
+     * granting privilege, so a command cannot `sudo` even when the run user has a sudo rule (the host needs one for the
+     * archil verbs). Default true. Set false on a host that already confines commands, or where util-linux is absent.
+     */
+    readonly noNewPrivs?: boolean;
+    /** The util-linux `setpriv` that `noNewPrivs` and `runAs` run; default `/usr/bin/setpriv`. */
+    readonly setprivPath?: string;
+    /**
+     * Confine every file operation to the workspace (`PathOutsideWorkError` otherwise): read, write, edit and every other
+     * path pi's file system takes. Default true. Set false only where the paths are confined some other way, or where
+     * `/proc/self/fd` is unavailable (the confinement walks paths through it).
+     */
+    readonly confineFiles?: boolean;
+    /**
+     * Directories file operations may read but never write, besides the workspace and the claim's `tmp/` (where a bash
+     * command's spilled output lives and which the bash tool names to the model; a directory `createTempDir` returned is
+     * writable too, for the tool it was handed to). For an app's own skills or reference material.
+     */
+    readonly readRoots?: readonly string[];
+    /**
+     * Run every command as this user and group with no capabilities (`setpriv --reuid --regid --clear-groups
+     * --inh-caps=-all --bounding-set=-all`), and give it `work/` and every file and directory pi's in-process file tools
+     * create under `work/`, so a command can change what the agent wrote.
+     * For an instance that runs as root, as in a container: the run's root, store, `run.json` and owner lock stay root's
+     * (the mount enforces their modes), and the archil daemon's environment, which holds the mount token, is unreadable to
+     * the commands. Needs root (to switch users and to chown).
+     */
+    readonly runAs?: {
+        readonly uid: number;
+        readonly gid: number;
+    };
+}
+export type EnvErrorCode = "SETPRIV_UNAVAILABLE" | "PROC_UNAVAILABLE" | "INVALID_RUN_AS";
+/**
+ * What `exec` returns once the factory's `cleanup()` ran: no command was started. Its `code` is pi's `spawn_error`
+ * (the command could not start), `reason` tells it apart from a program that failed to spawn.
+ */
+export declare class EnvClosedError extends ExecutionError {
+    readonly reason = "env_closed";
+    constructor();
+}
+/** The environment cannot be built as asked. Exit 1. */
+export declare class EnvError extends PdaError {
+    constructor(code: EnvErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A `HarnessOptions.env` that builds a fresh environment per use, plus the identity and shutdown of the run's
+ * environments. The environment id is `archil:<disk>:<root>`, so file-mutation serialization keys on the run and a
+ * resumed run on another host has the same identity. Temporary files and directories (a bash command's spilled
+ * `pi-output-*.log` among them) live under `<root>/tmp/`, inside the claim and outside `work/`, so a path a result
+ * names still exists after a takeover on another host. Commands run under no_new_privs unless `noNewPrivs` is false, and
+ * every file operation is confined to the workspace (reads also to `tmp/` and `readRoots`, writes also inside a directory
+ * `createTempDir` returned) unless `confineFiles` is false.
+ */
+export interface ArchilEnvFactory {
+    /** Rooted at the claim's `work/`; an agent `cwd` is resolved against it. */
+    (target: {
+        readonly cwd?: string;
+    }): NodeExecutionEnv;
+    readonly id: string;
+    /**
+     * Closes the factory and kills every command still running in an environment it built. pi starts each command as
+     * the leader of its own process group, so killing the instance's group does not reach it: a fenced or released
+     * instance calls this before it exits. From the first moment of the call, `exec` on the factory's environments, those
+     * built before and after it, returns `EnvClosedError` without spawning, so nothing starts between the kill and the
+     * exit. A command that had passed that check but not yet spawned is killed at spawn, and ends `aborted` like the
+     * commands that were running; calling it again does nothing.
+     */
+    cleanup(context: Context): Promise<void>;
+}
+export declare function archilEnv(claim: ArchilEnvClaim, options?: ArchilEnvOptions): ArchilEnvFactory;
+/** Built-in tools that only read. A tool in this set is declared `replay: "safe"`. */
+export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
+/** Built-in tools that can change the workspace; their results follow the workspace barrier. */
+export declare const WRITING_TOOLS: ReadonlySet<string>;
+/** The tool declared `replay: "safe"`: an interrupted call reruns on recovery instead of reporting `interrupted`. */
+export declare function replaySafe<T extends ToolRegistration>(tool: T): T;
+/** `tools` with every read-only one declared replay-safe; the others, and the input array, are untouched. */
+export declare function markReadOnlySafe<T extends ToolRegistration>(tools: readonly T[], readOnly?: ReadonlySet<string>): T[];
+/**
+ * pi's `CodingTools` with `read` declared replay-safe. It keeps pi's extension name, so installing it replaces
+ * `CodingTools` in place. `write`, `edit` and `bash` stay as pi ships them (unsafe). pi 1.1.0 ships no ls, find or
+ * grep; an app that adds them declares them safe with `markReadOnlySafe`.
+ */
+export declare const ArchilCodingTools: Extension;
+export interface WorkspaceBarrierOptions {
+    /** Tools whose result follows a barrier; default `WRITING_TOOLS`. An app adds its own writing tools here. */
+    readonly tools?: Iterable<string>;
+}
+/**
+ * The hook point for the rule that the workspace changes a tool made are durable before its result is committed.
+ * Install this extension only when the result commit's own fsync does not already satisfy the rule; with it
+ * not installed nothing runs. `barrier` is the claim's (`claim.barrier()`), called after a writing tool ran and before
+ * pi appends its result entry, for the calls whose tool name is in `options.tools`.
+ *
+ * pi reports and ignores an `afterTool` hook that throws, so a failed barrier cannot hold the result back by throwing.
+ * It replaces the result with an error result carrying the diagnostic `workspace_not_durable`: a success never commits
+ * for a workspace that is not durable. The host decides separately whether a failed barrier means the claim is fenced.
+ */
+export declare function workspaceBarrier(barrier: (call: ToolCall, context: Context) => Promise<void>, options?: WorkspaceBarrierOptions): Extension;
+export {};