@mku1tra/que-pasa 0.1.0 → 0.2.1

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,206 @@
+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" };
+            // 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,80 @@
+/**
+ * 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 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>;
+/** 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>];