@mku1tra/que-pasa 0.2.0 → 0.2.2

package/dist/sandbox/backend.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A backend: the place where a run's files are and its commands run, behind one interface. Two abilities, as in
+ * LangChain Deep Agents' backend protocol: files (`FileBackend`), and commands on top of files (`SandboxBackend`).
+ * Every path is the backend's own: relative to its root, or absolute under it. Every path a result gives is relative to
+ * the root. A backend gives its errors back in the result, and throws only when it cannot run at all.
+ */
+/** Why an operation did nothing. Deep Agents' file errors, and the two of an edit. */
+export type FileError = "file_not_found" | "is_directory" | "invalid_path" | "permission_denied" | "string_not_found" | "string_not_unique";
+/** What every result can say: that the operation did nothing, and why. `message` says more, for the model. */
+export type Failed = {
+    error?: FileError;
+    message?: string;
+};
+export type FileInfo = {
+    path: string;
+    isDir: boolean;
+};
+export type LsResult = Failed & {
+    files?: FileInfo[];
+};
+export type ReadResult = Failed & {
+    /** The lines asked for, each with its newline. */
+    content?: string;
+    /** How many lines the file has. */
+    totalLines?: number;
+};
+export type WriteResult = Failed & {
+    path?: string;
+};
+export type EditResult = Failed & {
+    path?: string;
+    occurrences?: number;
+};
+export type GlobResult = Failed & {
+    files?: string[];
+    truncated?: boolean;
+};
+export type GrepMatch = {
+    path: string;
+    line: number;
+    text: string;
+};
+export type GrepResult = Failed & {
+    matches?: GrepMatch[];
+    truncated?: boolean;
+};
+export type ExecuteResult = {
+    /** stdout and stderr, as they came. */
+    output: string;
+    /** null when the command was killed by a signal. */
+    exitCode: number | null;
+    /** The output kept only its tail. */
+    truncated: boolean;
+};
+/** Files: read, write and search them. */
+export interface FileBackend {
+    /** The folder every path is under. */
+    readonly root: string;
+    /** What a folder holds, or the file itself. */
+    ls(path: string): Promise<LsResult>;
+    /** `limit` lines of a file, after the first `offset`. */
+    read(path: string, offset: number, limit: number): Promise<ReadResult>;
+    /** A file, whole, made with its folder if it has none. It replaces what was there. */
+    write(path: string, content: string): Promise<WriteResult>;
+    /** Replace `old` with `next` in a file: it must occur once, unless `all`. */
+    edit(path: string, old: string, next: string, all: boolean): Promise<EditResult>;
+    /** The files under a folder whose path from that folder matches a glob. */
+    glob(pattern: string, path: string): Promise<GlobResult>;
+    /** The lines of the files under a path that hold a text, as is (not a pattern), in files matching `glob` if given: by path, then line. */
+    grep(pattern: string, path: string, glob?: string): Promise<GrepResult>;
+}
+/** Files, and commands: a backend that can run a shell command. */
+export interface SandboxBackend extends FileBackend {
+    /** Names this sandbox, such as its container. */
+    readonly id: string;
+    /** Run a shell command in the root. The signal kills it. */
+    execute(command: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ExecuteResult>;
+}
+/** Whether a backend can run commands. */
+export declare function canExecute(backend: FileBackend): backend is SandboxBackend;

package/dist/sandbox/backend.js

@@ -0,0 +1,10 @@
+/**
+ * A backend: the place where a run's files are and its commands run, behind one interface. Two abilities, as in
+ * LangChain Deep Agents' backend protocol: files (`FileBackend`), and commands on top of files (`SandboxBackend`).
+ * Every path is the backend's own: relative to its root, or absolute under it. Every path a result gives is relative to
+ * the root. A backend gives its errors back in the result, and throws only when it cannot run at all.
+ */
+/** Whether a backend can run commands. */
+export function canExecute(backend) {
+    return typeof backend.execute === "function";
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,7 @@
+export { canExecute, type EditResult, type ExecuteResult, type FileBackend, type FileError, type FileInfo, type GlobResult, type GrepMatch, type GrepResult, type LsResult, type ReadResult, type SandboxBackend, type WriteResult, } from "./backend.ts";
+export { local } from "./local.ts";
+export { podman, type Mount, type Podman, type PodmanOptions, } from "./podman.ts";
+export { shellBackend, type Exec } from "./shell.ts";
+export type { Ran, Script } from "./process.ts";
+export { Sandbox, commandAnswer, edit_file, execute, fileTools, glob, grep, ls, maxAnswer, read_file, readTools, write_file, } from "./tools.ts";
+export { view, type ViewPaths } from "./view.ts";

package/dist/sandbox/index.js

@@ -0,0 +1,6 @@
+export { canExecute, } from "./backend.js";
+export { local } from "./local.js";
+export { podman, } from "./podman.js";
+export { shellBackend } from "./shell.js";
+export { Sandbox, commandAnswer, edit_file, execute, fileTools, glob, grep, ls, maxAnswer, read_file, readTools, write_file, } from "./tools.js";
+export { view } from "./view.js";

package/dist/sandbox/local.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxBackend } from "./backend.ts";
+/**
+ * A folder on the host as a backend: files and commands run as the host's own user. No wall: a path is checked
+ * against the root, but a symlink, or any command, reaches the whole host. For the host's own trusted work, and tests.
+ */
+export declare function local({ root }: {
+    root: string;
+}): SandboxBackend;

package/dist/sandbox/local.js

@@ -0,0 +1,20 @@
+import { isAbsolute } from "node:path";
+import { run } from "./process.js";
+import { shellBackend } from "./shell.js";
+/**
+ * A folder on the host as a backend: files and commands run as the host's own user. No wall: a path is checked
+ * against the root, but a symlink, or any command, reaches the whole host. For the host's own trusted work, and tests.
+ */
+export function local({ root }) {
+    if (!isAbsolute(root))
+        throw new Error(`local: the root must be absolute, not "${root}"`);
+    return shellBackend({
+        id: `local:${root}`,
+        root,
+        exec: ({ script, args = [], stdin, signal }) => run("sh", ["-c", script, "sh", ...args], {
+            cwd: root,
+            ...(stdin === undefined ? {} : { stdin }),
+            ...(signal === undefined ? {} : { signal }),
+        }),
+    });
+}

package/dist/sandbox/paths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A path as a tool gives it, as a path from the root: "" for the root itself. undefined for a path the backend refuses:
+ * one that leaves the root (by `..`, or absolute and not under it), starts with `~`, or holds a control character,
+ * which a line-based listing cannot carry.
+ */
+export declare function fromRoot(root: string, path: string): string | undefined;
+/** A path from the root as a shell argument: "." for the root. */
+export declare const asArg: (p: string) => string;
+/** Whether `path` is `folder` or under it; every path is under the root (""). */
+export declare const isUnder: (path: string, folder: string) => boolean;

package/dist/sandbox/paths.js

@@ -0,0 +1,31 @@
+import { posix } from "node:path";
+/**
+ * A path as a tool gives it, as a path from the root: "" for the root itself. undefined for a path the backend refuses:
+ * one that leaves the root (by `..`, or absolute and not under it), starts with `~`, or holds a control character,
+ * which a line-based listing cannot carry.
+ */
+export function fromRoot(root, path) {
+    const given = path.trim();
+    // A control character, such as a newline: no file of a backend is named with one.
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(given) || given.startsWith("~"))
+        return undefined;
+    let p = given === "" ? "." : given;
+    if (posix.isAbsolute(p)) {
+        const top = posix.normalize(root).replace(/\/+$/, "");
+        const at = posix.normalize(p).replace(/\/+$/, "");
+        if (at === top)
+            return "";
+        if (!at.startsWith(`${top}/`))
+            return undefined;
+        p = at.slice(top.length + 1);
+    }
+    const n = posix.normalize(p).replace(/\/+$/, "");
+    if (n === ".." || n.startsWith("../"))
+        return undefined;
+    return n === "." ? "" : n;
+}
+/** A path from the root as a shell argument: "." for the root. */
+export const asArg = (p) => p || ".";
+/** Whether `path` is `folder` or under it; every path is under the root (""). */
+export const isUnder = (path, folder) => folder === "" || path === folder || path.startsWith(`${folder}/`);

package/dist/sandbox/podman.d.ts

@@ -0,0 +1,38 @@
+import type { SandboxBackend } from "./backend.ts";
+/** A folder of the host in the container. */
+export type Mount = {
+    source: string;
+    target: string;
+    readOnly?: boolean;
+};
+/** One container, as the host sets it: what it runs, what it sees, and what bounds it. */
+export type PodmanOptions = {
+    /** The container's name: one per sandbox, so a process that starts again finds it. */
+    name: string;
+    image: string;
+    /** The host folders it sees. Nothing else of the host is in it. */
+    mounts: readonly Mount[];
+    /** Its root: every path is under it. */
+    workdir?: string;
+    /** "none" by default: no network. */
+    network?: string;
+    /** The user commands run as, such as "1000:1000". */
+    user?: string;
+    /** Such as "4g". */
+    memory?: string;
+    /** Such as 3. */
+    cpus?: number;
+    /** Any other `podman run` options, such as `--userns=keep-id`. */
+    runArgs?: readonly string[];
+};
+/** A Podman container that outlives the process, as a backend. */
+export type Podman = SandboxBackend & {
+    /** Remove the container. The next call makes it again. */
+    close(): Promise<void>;
+};
+/**
+ * A Podman container as a backend: every operation execs into it, so its mounts, its network and its limits are the
+ * wall. It is made on its first call and kept: started again if it stopped, made again if it is gone, so a run that
+ * resumes after a restart works with no host step. One made with other options is refused, never used.
+ */
+export declare function podman(options: PodmanOptions): Podman;

package/dist/sandbox/podman.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { run } from "./process.js";
+import { shellBackend } from "./shell.js";
+/** The label that holds a hash of the options a container was made with. */
+const label = "que-pasa.sandbox";
+/** podman's exit code for a container that is not there. */
+const noContainer = 125;
+/**
+ * A Podman container as a backend: every operation execs into it, so its mounts, its network and its limits are the
+ * wall. It is made on its first call and kept: started again if it stopped, made again if it is gone, so a run that
+ * resumes after a restart works with no host step. One made with other options is refused, never used.
+ */
+export function podman(options) {
+    const { name, image, mounts, workdir = "/work" } = options;
+    if (!posix.isAbsolute(workdir))
+        throw new Error(`podman: the workdir must be absolute, not "${workdir}"`);
+    const config = createHash("sha256")
+        .update(JSON.stringify([
+        image,
+        mounts,
+        workdir,
+        options.network ?? "none",
+        options.user ?? null,
+        options.memory ?? null,
+        options.cpus ?? null,
+        options.runArgs ?? [],
+    ]))
+        .digest("hex")
+        .slice(0, 16);
+    const podmanOf = async (args, stdin, signal) => run("podman", args, {
+        ...(stdin === undefined ? {} : { stdin }),
+        ...(signal === undefined ? {} : { signal }),
+    });
+    const must = (what, ran) => {
+        if (ran.code !== 0)
+            throw new Error(`podman ${what} ${name}: exit ${ran.code}: ${(ran.stderr || ran.stdout).trim().slice(-400)}`);
+        return ran.stdout.trim();
+    };
+    /** The container's label and whether it runs, or undefined when there is none. */
+    async function inspect() {
+        const ran = await podmanOf([
+            "container",
+            "inspect",
+            "--format",
+            `{{index .Config.Labels "${label}"}} {{.State.Running}}`,
+            name,
+        ]);
+        if (ran.code !== 0)
+            return undefined;
+        const [made, running] = ran.stdout.trim().split(" ");
+        return { made, running: running === "true" };
+    }
+    /** Keep it, start it, or make it: and refuse one made with other options. */
+    async function ensure() {
+        let found = await inspect();
+        if (!found) {
+            const made = await podmanOf([
+                "run",
+                "--detach",
+                "--name",
+                name,
+                "--label",
+                `${label}=${config}`,
+                "--network",
+                options.network ?? "none",
+                ...(options.user ? ["--user", options.user] : []),
+                ...(options.memory ? ["--memory", options.memory] : []),
+                ...(options.cpus ? ["--cpus", String(options.cpus)] : []),
+                ...(options.runArgs ?? []),
+                ...mounts.flatMap((m) => [
+                    "--volume",
+                    `${m.source}:${m.target}${m.readOnly ? ":ro" : ""}`,
+                ]),
+                "--workdir",
+                workdir,
+                image,
+                "sleep",
+                "infinity",
+            ]);
+            if (made.code === 0)
+                return;
+            // Another process made it first: it is checked as any found one.
+            found = await inspect();
+            if (!found)
+                must("run", made);
+        }
+        if (found.made !== config) {
+            throw new Error(`podman: the container "${name}" was made with other options: remove it, or give this sandbox another name`);
+        }
+        if (!found.running)
+            must("start", await podmanOf(["start", name]));
+    }
+    let ready;
+    const ensured = () => {
+        ready ??= ensure().catch((error) => {
+            ready = undefined;
+            throw error;
+        });
+        return ready;
+    };
+    const backend = shellBackend({
+        id: name,
+        root: workdir,
+        async exec({ script, args = [], stdin, signal }) {
+            const call = async () => {
+                await ensured();
+                return podmanOf([
+                    "exec",
+                    ...(stdin === undefined ? [] : ["--interactive"]),
+                    "--workdir",
+                    workdir,
+                    name,
+                    "sh",
+                    "-c",
+                    script,
+                    "sh",
+                    ...args,
+                ], stdin, signal);
+            };
+            const ran = await call();
+            // Gone since it was made, such as by a host restart: made again, once.
+            if (ran.code === noContainer && !(await inspect())) {
+                ready = undefined;
+                return call();
+            }
+            return ran;
+        },
+    });
+    return {
+        ...backend,
+        async close() {
+            ready = undefined;
+            must("rm", await podmanOf(["rm", "--force", "--ignore", "--time", "0", name]));
+        },
+    };
+}

package/dist/sandbox/process.d.ts

@@ -0,0 +1,27 @@
+/** What a process gave back. */
+export type Ran = {
+    /** null when it was killed by a signal. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** Its output was cut to its tail. */
+    truncated: boolean;
+};
+/** One call of a script: its arguments are `$1`…, and its input goes over stdin, so neither is read by the shell. */
+export type Script = {
+    script: string;
+    args?: readonly string[];
+    stdin?: string;
+    signal?: AbortSignal;
+};
+/** The most of each stream a process keeps: its tail, where a failure is. */
+export declare const keep = 1000000;
+/**
+ * Run a command to its end. It never rejects on a non-zero exit, only when it cannot start or the signal aborts it,
+ * which kills it.
+ */
+export declare function run(command: string, args: readonly string[], { stdin, signal, cwd, }?: {
+    stdin?: string;
+    signal?: AbortSignal;
+    cwd?: string;
+}): Promise<Ran>;

package/dist/sandbox/process.js

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+/** The most of each stream a process keeps: its tail, where a failure is. */
+export const keep = 1_000_000;
+/** Keep the last `keep` characters of a stream. */
+function tail() {
+    let text = "";
+    let cut = false;
+    return {
+        add(chunk) {
+            text += chunk.toString("utf8");
+            if (text.length > keep) {
+                text = text.slice(-keep);
+                cut = true;
+            }
+        },
+        get text() {
+            return text;
+        },
+        get cut() {
+            return cut;
+        },
+    };
+}
+/**
+ * Run a command to its end. It never rejects on a non-zero exit, only when it cannot start or the signal aborts it,
+ * which kills it.
+ */
+export function run(command, args, { stdin, signal, cwd, } = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+            ...(cwd === undefined ? {} : { cwd }),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const out = tail();
+        const err = tail();
+        child.stdout?.on("data", out.add);
+        child.stderr?.on("data", err.add);
+        child.on("error", reject);
+        child.on("close", (code) => resolve({
+            code,
+            stdout: out.text,
+            stderr: err.text,
+            truncated: out.cut || err.cut,
+        }));
+        if (child.stdin) {
+            // A script that exits before it reads its input closes the pipe: that is its answer, not an error.
+            child.stdin.on("error", () => { });
+            child.stdin.end(stdin);
+        }
+    });
+}

package/dist/sandbox/shell.d.ts

@@ -0,0 +1,17 @@
+import type { SandboxBackend } from "./backend.ts";
+import type { Ran, Script } from "./process.ts";
+/** Runs one script in the backend's root: `sh -c <script> sh <args…>`, with its stdin. */
+export type Exec = (call: Script) => Promise<Ran>;
+/** The most matches grep gives back. */
+export declare const maxMatches = 1000;
+/**
+ * A whole sandbox backend in POSIX `sh`, on one primitive that runs a script in the root (Deep Agents' `BaseSandbox`).
+ * A path is always a positional argument and content always goes over stdin: nothing a model gives is part of a
+ * script. It needs no other runtime in the sandbox: `find`, `awk`, `grep`, `cat`, `mkdir` and `dirname`, which
+ * BusyBox has too.
+ */
+export declare function shellBackend({ id, root, exec, }: {
+    id: string;
+    root: string;
+    exec: Exec;
+}): SandboxBackend;

package/dist/sandbox/shell.js

@@ -0,0 +1,208 @@
+import { posix } from "node:path";
+import { asArg, fromRoot } from "./paths.js";
+/** How a script says why it did nothing. Any other failure is the backend's, and throws. */
+const missing = 3;
+const directory = 4;
+/** The most matches grep gives back. */
+export const maxMatches = 1000;
+/** How many files one grep call reads. */
+const batch = 200;
+const invalid = { error: "invalid_path" };
+/** A path as the backend gives it in a result: from the root, with no `./`. */
+const clean = (p) => posix.normalize(p).replace(/^\.\//, "");
+/** A script's failure that is none of the ones it says: the backend's own, such as a read-only file system. */
+function failed(what, ran) {
+    throw new Error(`${what}: exit ${ran.code ?? "killed"}: ${(ran.stderr || ran.stdout).trim().slice(-400)}`);
+}
+/**
+ * A whole sandbox backend in POSIX `sh`, on one primitive that runs a script in the root (Deep Agents' `BaseSandbox`).
+ * A path is always a positional argument and content always goes over stdin: nothing a model gives is part of a
+ * script. It needs no other runtime in the sandbox: `find`, `awk`, `grep`, `cat`, `mkdir` and `dirname`, which
+ * BusyBox has too.
+ */
+export function shellBackend({ id, root, exec, }) {
+    /** Every file under a path, from the root, `.git` left out. undefined when the path is not there. */
+    async function filesUnder(at) {
+        const ran = await exec({
+            script: `[ -e "$1" ] || exit ${missing}; find "$1" -name .git -prune -o -type f -print0`,
+            args: [asArg(at)],
+        });
+        if (ran.code === missing)
+            return undefined;
+        if (ran.code !== 0)
+            failed("glob", ran);
+        const names = ran.stdout.split("\0").filter(Boolean);
+        // A cut output starts mid-name: that one is dropped.
+        if (ran.truncated)
+            names.shift();
+        return names.map(clean);
+    }
+    /** The files under a path whose path from it matches a glob. */
+    async function matching(at, pattern) {
+        const files = await filesUnder(at);
+        return files?.filter((f) => {
+            const from = f === at ? posix.basename(f) : at ? f.slice(at.length + 1) : f;
+            return posix.matchesGlob(from, pattern);
+        });
+    }
+    return {
+        id,
+        root,
+        async ls(path) {
+            const at = fromRoot(root, path);
+            if (at === undefined)
+                return invalid;
+            const ran = await exec({
+                script: `if [ -d "$1" ]; then
+  find "$1" -mindepth 1 -maxdepth 1 -exec sh -c 'for f; do if [ -d "$f" ]; then printf "d%s\\0" "$f"; else printf "f%s\\0" "$f"; fi; done' sh {} +
+elif [ -e "$1" ]; then printf "f%s\\0" "$1"
+else exit ${missing}; fi`,
+                args: [asArg(at)],
+            });
+            if (ran.code === missing)
+                return { error: "file_not_found" };
+            if (ran.code !== 0)
+                failed("ls", ran);
+            const files = ran.stdout
+                .split("\0")
+                .filter(Boolean)
+                .map((entry) => ({
+                path: clean(entry.slice(1)),
+                isDir: entry[0] === "d",
+            }))
+                .sort((a, b) => a.path.localeCompare(b.path));
+            return { files };
+        },
+        async read(path, offset, limit) {
+            const at = fromRoot(root, path);
+            if (at === undefined)
+                return invalid;
+            const ran = await exec({
+                script: `[ -e "$1" ] || exit ${missing}; [ -d "$1" ] && exit ${directory}; awk -v o="$2" -v l="$3" 'NR > o && NR <= o + l { print } END { printf "%d", NR }' "$1"`,
+                args: [asArg(at), String(offset), String(limit)],
+            });
+            if (ran.code === missing)
+                return { error: "file_not_found" };
+            if (ran.code === directory)
+                return { error: "is_directory" };
+            if (ran.code !== 0)
+                failed("read", ran);
+            // The lines, then the file's line count, with no newline after it.
+            const last = ran.stdout.lastIndexOf("\n");
+            return {
+                content: ran.stdout.slice(0, last + 1),
+                totalLines: Number(ran.stdout.slice(last + 1)),
+            };
+        },
+        async write(path, content) {
+            const at = fromRoot(root, path);
+            if (at === undefined)
+                return invalid;
+            const ran = await exec({
+                script: `[ -d "$1" ] && exit ${directory}; mkdir -p -- "$(dirname -- "$1")" && cat > "$1"`,
+                args: [asArg(at)],
+                stdin: content,
+            });
+            if (ran.code === directory)
+                return { error: "is_directory" };
+            if (ran.code !== 0)
+                failed("write", ran);
+            return { path: at };
+        },
+        async edit(path, old, next, all) {
+            const at = fromRoot(root, path);
+            if (at === undefined)
+                return invalid;
+            const read = await exec({
+                script: `[ -e "$1" ] || exit ${missing}; [ -d "$1" ] && exit ${directory}; cat -- "$1"`,
+                args: [asArg(at)],
+            });
+            if (read.code === missing)
+                return { error: "file_not_found" };
+            if (read.code === directory)
+                return { error: "is_directory" };
+            if (read.code !== 0)
+                failed("edit", read);
+            const occurrences = read.stdout.split(old).length - 1;
+            if (occurrences === 0)
+                return { error: "string_not_found" };
+            if (occurrences > 1 && !all)
+                return { error: "string_not_unique", occurrences };
+            // The function form: a `$` in the new text is text, never a replacement pattern.
+            const text = all
+                ? read.stdout.split(old).join(next)
+                : read.stdout.replace(old, () => next);
+            const wrote = await exec({
+                script: `cat > "$1"`,
+                args: [asArg(at)],
+                stdin: text,
+            });
+            if (wrote.code !== 0)
+                failed("edit", wrote);
+            return { path: at, occurrences: all ? occurrences : 1 };
+        },
+        async glob(pattern, path) {
+            const at = fromRoot(root, path);
+            if (at === undefined)
+                return invalid;
+            const files = await matching(at, pattern);
+            if (!files)
+                return { error: "file_not_found" };
+            return { files: files.sort() };
+        },
+        async grep(pattern, path, glob) {
+            const at = fromRoot(root, path);
+            if (at === undefined)
+                return invalid;
+            const files = glob ? await matching(at, glob) : await filesUnder(at);
+            if (!files)
+                return { error: "file_not_found" };
+            // By path, then line, as glob lists them: the same order on any file system.
+            files.sort();
+            // No line holds a newline, so a text with one is in no file.
+            if (pattern.includes("\n"))
+                return { matches: [] };
+            const matches = [];
+            for (let i = 0; i < files.length && matches.length <= maxMatches; i += batch) {
+                const some = files.slice(i, i + batch);
+                const ran = await exec({
+                    script: `p="$1"; shift; grep -nHF -e "$p" -- "$@"`,
+                    args: [pattern, ...some],
+                });
+                // 1: no match. 2: a file it could not read, such as one gone since the listing; the others still count.
+                if (ran.code !== 0 && ran.code !== 1 && ran.code !== 2)
+                    failed("grep", ran);
+                // A line is "<file>:<n>:<text>", and a file's name can hold ":": the longest file of the batch that starts it.
+                const named = [...some].sort((a, b) => b.length - a.length);
+                for (const line of ran.stdout.split("\n")) {
+                    const file = named.find((f) => line.startsWith(`${f}:`));
+                    if (!file)
+                        continue;
+                    const rest = line.slice(file.length + 1);
+                    const colon = rest.indexOf(":");
+                    const n = Number(rest.slice(0, colon));
+                    if (colon < 1 || !Number.isInteger(n))
+                        continue;
+                    matches.push({ path: file, line: n, text: rest.slice(colon + 1) });
+                }
+            }
+            const truncated = matches.length > maxMatches;
+            return {
+                matches: matches.slice(0, maxMatches),
+                ...(truncated ? { truncated } : {}),
+            };
+        },
+        async execute(command, options = {}) {
+            const ran = await exec({
+                script: `exec 2>&1; eval "$1"`,
+                args: [command],
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            return {
+                output: ran.stdout + ran.stderr,
+                exitCode: ran.code,
+                truncated: ran.truncated,
+            };
+        },
+    };
+}

package/dist/sandbox/tools.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The file and command tools of LangChain Deep Agents, as que-pasa tools, with their names, parameters and wording:
+ * ls, read_file, write_file, edit_file, glob, grep and execute. Each asks its run for the `Sandbox` the host provides,
+ * and works through it: the tools hold no backend and no policy.
+ */
+import { z } from "zod";
+import { type Json } from "../define/index.ts";
+import { type ExecuteResult, type FileBackend } from "./backend.ts";
+/** The backend a run's file tools work in: the host provides it per run, such as a container, or a view over one. */
+export declare const Sandbox: import("../define/resource.ts").Resource<FileBackend>;
+/** The most of a tool's answer the model gets (Deep Agents: 20,000 tokens, at four characters each). */
+export declare const maxAnswer = 80000;
+export declare const ls: import("../define/tool.ts").Tool<z.ZodObject<{
+    path: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, Json | undefined>;
+export declare const read_file: import("../define/tool.ts").Tool<z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, Json | undefined>;
+export declare const write_file: import("../define/tool.ts").Tool<z.ZodObject<{
+    file_path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>, Json | undefined>;
+export declare const edit_file: import("../define/tool.ts").Tool<z.ZodObject<{
+    file_path: z.ZodString;
+    old_string: z.ZodString;
+    new_string: z.ZodString;
+    replace_all: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, Json | undefined>;
+export declare const glob: import("../define/tool.ts").Tool<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, Json | undefined>;
+export declare const grep: import("../define/tool.ts").Tool<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodDefault<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Json | undefined>;
+export declare const execute: import("../define/tool.ts").Tool<z.ZodObject<{
+    command: z.ZodString;
+}, z.core.$strip>, Json | undefined>;
+/**
+ * What the model reads for a command that ran: the tail of its output, at most `maxAnswer` characters, where a failure
+ * is, then how it ended. `execute`'s answer, for a host tool that runs a command to answer the same way.
+ */
+export declare function commandAnswer(result: ExecuteResult): string;
+/** The tools that only read. */
+export declare const readTools: readonly [import("../define/tool.ts").Tool<z.ZodObject<{
+    path: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodDefault<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Json | undefined>];
+/** The tools that read and write files. `execute` is given on its own. */
+export declare const fileTools: readonly [import("../define/tool.ts").Tool<z.ZodObject<{
+    path: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodDefault<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    file_path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>, Json | undefined>, import("../define/tool.ts").Tool<z.ZodObject<{
+    file_path: z.ZodString;
+    old_string: z.ZodString;
+    new_string: z.ZodString;
+    replace_all: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, Json | undefined>];

package/dist/sandbox/tools.js

@@ -0,0 +1,248 @@
+/**
+ * The file and command tools of LangChain Deep Agents, as que-pasa tools, with their names, parameters and wording:
+ * ls, read_file, write_file, edit_file, glob, grep and execute. Each asks its run for the `Sandbox` the host provides,
+ * and works through it: the tools hold no backend and no policy.
+ */
+import { z } from "zod";
+import { defineResource, defineTool, } from "../define/index.js";
+import { canExecute, } from "./backend.js";
+/** The backend a run's file tools work in: the host provides it per run, such as a container, or a view over one. */
+export const Sandbox = defineResource("sandbox");
+/** The most of a tool's answer the model gets (Deep Agents: 20,000 tokens, at four characters each). */
+export const maxAnswer = 80_000;
+const cutNote = "\n... [results truncated, try being more specific with your parameters]";
+/** An answer cut to the most the model gets, at a whole line. */
+function cut(text) {
+    if (text.length <= maxAnswer)
+        return text;
+    const head = text.slice(0, maxAnswer);
+    return head.slice(0, Math.max(head.lastIndexOf("\n"), 0)) + cutNote;
+}
+/** What the model reads for a result that did nothing. Deep Agents' strings. */
+function failure(result, op, path, old = "") {
+    switch (result.error) {
+        case "file_not_found":
+            return op === "read" || op === "edit"
+                ? `Error: File '${path}' not found`
+                : `Error: Path '${path}' not found`;
+        case "is_directory":
+            return `Error: '${path}' is a directory, not a file`;
+        case "invalid_path":
+            return `Error: Path traversal not allowed: ${path}`;
+        case "permission_denied":
+            return `Error: permission denied for ${op} on ${path}${result.message ? `: ${result.message}` : ""}`;
+        case "string_not_found":
+            return `Error: String not found in file: '${old}'`;
+        case "string_not_unique":
+            return `Error: String '${old}' appears ${result.occurrences ?? "several"} times in file. Use replace_all=True to replace all instances, or provide a more specific string with surrounding context.`;
+        default:
+            return undefined;
+    }
+}
+const sandbox = (runtime) => runtime.use(Sandbox);
+/** A path the model gives. */
+const path = () => z
+    .string()
+    .describe("A path in the sandbox: relative to its root, or absolute under it.");
+/** A folder the model may leave out: the root. */
+const folder = () => path().default(".");
+export const ls = defineTool({
+    name: "ls",
+    description: "Lists the files and folders in a folder of the sandbox. A folder ends in a slash.",
+    schema: z.object({ path: folder() }),
+    uses: [Sandbox],
+    replay: "safe",
+    run: async ({ path }, runtime) => {
+        const result = await (await sandbox(runtime)).ls(path);
+        const failed = failure(result, "ls", path);
+        if (failed)
+            return failed;
+        const files = result.files ?? [];
+        if (files.length === 0)
+            return `No files found in '${path}'`;
+        return cut(files.map((f) => (f.isDir ? `${f.path}/` : f.path)).join("\n"));
+    },
+});
+export const read_file = defineTool({
+    name: "read_file",
+    description: "Reads a file from the sandbox. Assume any path the user provides is valid; reading a missing file returns an error. " +
+        "By default it reads up to 100 lines from the start; use offset and limit to page through a large file. " +
+        "A status header, `@@ lines A-B of T | next offset N @@`, sits above the file content, and every line after it is " +
+        "the file's content, verbatim. Never include the header when editing. Always read a file before editing it.",
+    schema: z.object({
+        file_path: path(),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Line offset to start reading from (0-indexed)."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .default(100)
+            .describe("Maximum number of lines to read. Use for pagination of large files."),
+    }),
+    uses: [Sandbox],
+    replay: "safe",
+    run: async ({ file_path, offset, limit }, runtime) => {
+        const result = await (await sandbox(runtime)).read(file_path, offset, limit);
+        const failed = failure(result, "read", file_path);
+        if (failed)
+            return failed;
+        const total = result.totalLines ?? 0;
+        if (total === 0)
+            return "System reminder: File exists but has empty contents";
+        if (offset >= total)
+            return `Error: Line offset ${offset} exceeds file length (${total} lines)`;
+        let content = result.content ?? "";
+        let note = "";
+        if (content.length > maxAnswer) {
+            const head = content.slice(0, maxAnswer);
+            content = head.slice(0, head.lastIndexOf("\n") + 1);
+            note = " | truncated due to size";
+        }
+        const lines = content.split("\n").length - 1;
+        const end = offset + lines;
+        const next = end < total ? ` | next offset ${end}` : "";
+        return `@@ lines ${offset + 1}-${end} of ${total}${next}${note} @@\n${content}`;
+    },
+});
+export const write_file = defineTool({
+    name: "write_file",
+    description: "Writes content to a file in the sandbox. Creates the file, and its folder, if it does not exist; replaces it entirely if it does.",
+    schema: z.object({
+        file_path: path(),
+        content: z
+            .string()
+            .describe("The text content to write to the file. This parameter is required."),
+    }),
+    uses: [Sandbox],
+    // It writes the whole file, so a second run leaves the same file as one.
+    replay: "safe",
+    run: async ({ file_path, content }, runtime) => {
+        const result = await (await sandbox(runtime)).write(file_path, content);
+        return (failure(result, "write", file_path) ??
+            `Successfully wrote to '${file_path}'`);
+    },
+});
+export const edit_file = defineTool({
+    name: "edit_file",
+    description: "Performs exact string replacements in a file of the sandbox. old_string must occur exactly once, unless " +
+        "replace_all is true, which replaces each one. You must read the file before editing.",
+    schema: z.object({
+        file_path: path(),
+        old_string: z
+            .string()
+            .min(1)
+            .describe("The exact text to find and replace. Must be unique in the file unless replace_all is true."),
+        new_string: z.string().describe("The text to replace it with."),
+        replace_all: z
+            .boolean()
+            .default(false)
+            .describe("Replace every occurrence of old_string."),
+    }),
+    uses: [Sandbox],
+    // Not replay-safe: a second replace finds nothing, or replaces twice.
+    run: async ({ file_path, old_string, new_string, replace_all }, runtime) => {
+        const result = await (await sandbox(runtime)).edit(file_path, old_string, new_string, replace_all);
+        return (failure(result, "edit", file_path, old_string) ??
+            `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`);
+    },
+});
+export const glob = defineTool({
+    name: "glob",
+    description: "Finds the files of the sandbox whose path matches a glob pattern, under a folder: `*` matches within a folder, " +
+        "`**` across folders, as in `**/*.test.ts`. Paths are from the sandbox's root.",
+    schema: z.object({
+        pattern: z
+            .string()
+            .min(1)
+            .describe("The glob pattern, matched against the path from `path`."),
+        path: folder(),
+    }),
+    uses: [Sandbox],
+    replay: "safe",
+    run: async ({ pattern, path }, runtime) => {
+        const result = await (await sandbox(runtime)).glob(pattern, path);
+        const failed = failure(result, "glob", path);
+        if (failed)
+            return failed;
+        const files = result.files ?? [];
+        if (files.length === 0)
+            return `No files found matching pattern '${pattern}'`;
+        return cut(files.join("\n") + (result.truncated ? cutNote : ""));
+    },
+});
+export const grep = defineTool({
+    name: "grep",
+    description: "Search for a LITERAL text pattern across files (NOT regex), under a path, in files matching glob if given. " +
+        "Gives each matching file, then each matching line with its number.",
+    schema: z.object({
+        pattern: z.string().min(1).describe("The text to find, as is."),
+        path: folder(),
+        glob: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Only files whose path from `path` matches this glob, such as `*.ts`."),
+    }),
+    uses: [Sandbox],
+    replay: "safe",
+    run: async ({ pattern, path, glob }, runtime) => {
+        const result = await (await sandbox(runtime)).grep(pattern, path, glob);
+        const failed = failure(result, "grep", path);
+        if (failed)
+            return failed;
+        const matches = result.matches ?? [];
+        if (matches.length === 0)
+            return `No matches found for pattern '${pattern}'`;
+        const byFile = new Map();
+        for (const m of matches) {
+            const lines = byFile.get(m.path) ?? [];
+            lines.push(`  ${m.line}: ${m.text}`);
+            byFile.set(m.path, lines);
+        }
+        const text = [...byFile]
+            .map(([f, lines]) => `${f}:\n${lines.join("\n")}`)
+            .join("\n");
+        return cut(text + (result.truncated ? cutNote : ""));
+    },
+});
+export const execute = defineTool({
+    name: "execute",
+    description: "Executes a shell command in the sandbox, in its root, and returns its combined stdout and stderr with the exit " +
+        "code (the tail, if very large).",
+    schema: z.object({
+        command: z.string().min(1).describe("The shell command to run."),
+    }),
+    uses: [Sandbox],
+    // Not replay-safe: a command can do anything.
+    run: async ({ command }, runtime) => {
+        const backend = await sandbox(runtime);
+        if (!canExecute(backend)) {
+            return "Error: Execution not available. This agent's backend does not support command execution.";
+        }
+        return commandAnswer(await backend.execute(command));
+    },
+});
+/**
+ * What the model reads for a command that ran: the tail of its output, at most `maxAnswer` characters, where a failure
+ * is, then how it ended. `execute`'s answer, for a host tool that runs a command to answer the same way.
+ */
+export function commandAnswer(result) {
+    const cutTail = result.output.length > maxAnswer;
+    const output = cutTail ? result.output.slice(-maxAnswer) : result.output;
+    const status = result.exitCode === null
+        ? "[Command was killed]"
+        : `[Command ${result.exitCode === 0 ? "succeeded" : "failed"} with exit code ${result.exitCode}]`;
+    const truncated = result.truncated || cutTail
+        ? "\n[Output was truncated due to size limits]"
+        : "";
+    return `${output}${output.endsWith("\n") || output === "" ? "" : "\n"}${status}${truncated}`;
+}
+/** The tools that only read. */
+export const readTools = [ls, read_file, glob, grep];
+/** The tools that read and write files. `execute` is given on its own. */
+export const fileTools = [...readTools, write_file, edit_file];

package/dist/sandbox/view.d.ts

@@ -0,0 +1,17 @@
+import type { FileBackend } from "./backend.ts";
+/** The files a view holds: paths from the backend's root, or absolute under it. */
+export type ViewPaths = {
+    /** The files it may read. */
+    read: readonly string[];
+    /** The files it may write: it may read them too. */
+    write: readonly string[];
+};
+/**
+ * A backend over a backend, limited to some files: to its tools, a path outside the view does not exist, and a write
+ * outside its write files is refused. It has no execute, since a shell reaches any path. It checks names, so it is a
+ * wall only over a backend that is one, such as a container whose mounts hold no more than the view's folder.
+ *
+ * Deep Agents' path rules answer a path outside them as denied; a view answers it as missing, so the model keeps to its
+ * task and does not probe.
+ */
+export declare function view(backend: FileBackend, paths: ViewPaths): FileBackend;

package/dist/sandbox/view.js

@@ -0,0 +1,87 @@
+import { fromRoot, isUnder } from "./paths.js";
+/**
+ * A backend over a backend, limited to some files: to its tools, a path outside the view does not exist, and a write
+ * outside its write files is refused. It has no execute, since a shell reaches any path. It checks names, so it is a
+ * wall only over a backend that is one, such as a container whose mounts hold no more than the view's folder.
+ *
+ * Deep Agents' path rules answer a path outside them as denied; a view answers it as missing, so the model keeps to its
+ * task and does not probe.
+ */
+export function view(backend, paths) {
+    const { root } = backend;
+    const checked = (list) => list.map((p) => {
+        const at = fromRoot(root, p);
+        if (!at)
+            throw new Error(`view: "${p}" is not a file under ${root}`);
+        return at;
+    });
+    const writes = new Set(checked(paths.write));
+    const files = [...new Set([...checked(paths.read), ...writes])];
+    const mine = new Set(files);
+    /** A path of the view: one of its files, or a folder on the way to one. */
+    const sees = (at) => files.some((f) => f === at || isUnder(f, at));
+    /** A path the view resolves, or undefined when it is outside the root. */
+    const at = (path) => fromRoot(root, path);
+    const missing = { error: "file_not_found" };
+    const invalid = { error: "invalid_path" };
+    /** A path the backend gave back that is one of the view's files. */
+    const own = (path) => mine.has(path);
+    const refused = (path) => ({
+        error: "permission_denied",
+        message: `${path} is not a file this view may write: it may write ${[...writes].join(", ") || "none"}`,
+    });
+    return {
+        root,
+        async ls(path) {
+            const p = at(path);
+            if (p === undefined)
+                return invalid;
+            if (!sees(p))
+                return missing;
+            const listed = await backend.ls(path);
+            return listed.files
+                ? { files: listed.files.filter((f) => sees(f.path)) }
+                : listed;
+        },
+        async read(path, offset, limit) {
+            const p = at(path);
+            if (p === undefined)
+                return invalid;
+            return sees(p) ? backend.read(path, offset, limit) : missing;
+        },
+        async write(path, content) {
+            const p = at(path);
+            if (p === undefined)
+                return invalid;
+            return writes.has(p) ? backend.write(path, content) : refused(path);
+        },
+        async edit(path, old, next, all) {
+            const p = at(path);
+            if (p === undefined)
+                return invalid;
+            return writes.has(p) ? backend.edit(path, old, next, all) : refused(path);
+        },
+        // A search runs once on the backend, and the view keeps its own files: Deep Agents filters its path rules' results
+        // the same way. The backend's limit counts files outside the view too, so a cut result says it is cut.
+        async glob(pattern, path) {
+            const p = at(path);
+            if (p === undefined)
+                return invalid;
+            if (!sees(p))
+                return missing;
+            const found = await backend.glob(pattern, path);
+            return found.files ? { ...found, files: found.files.filter(own) } : found;
+        },
+        async grep(pattern, path, glob) {
+            const p = at(path);
+            if (p === undefined)
+                return invalid;
+            if (!sees(p))
+                return missing;
+            const found = await backend.grep(pattern, path, glob);
+            return found.matches
+                ? { ...found, matches: found.matches.filter((m) => own(m.path)) }
+                : found;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mku1tra/que-pasa",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "An agent harness on pi-durable: define agents and tools with define/, and run them durably and traced with loop/.",
   "license": "MIT",
   "repository": {