@retinue/agentkit 0.1.0 → 0.2.0

package/dist/toolkit/files.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Reading and writing files, path-scoped — REQ-047 (#206), task #215.
+ *
+ * In `toolkit/` rather than `tools/` because it performs I/O and boundary rule **R7** forbids that in the tools
+ * layer, the same arrangement `http.ts` has with the web tools. The tools in `tools/library/fs.ts` are envelopes
+ * over these functions, and every security property lives here — not in the envelope, and not in the schema.
+ *
+ * ## The one property that matters
+ *
+ * **A path a model produced must not be able to name a file outside the configured root**, and there are three
+ * ways it tries:
+ *
+ * - `../../etc/passwd` — normalised away by resolving against the root first.
+ * - `/etc/passwd` — an absolute path is **refused outright** rather than silently re-rooted. Re-rooting would
+ *   answer a different question than the one asked, and the model would not know.
+ * - A **symlink** inside the root pointing out of it. This is the one that gets missed, because the path is
+ *   inside the root right up until the filesystem resolves it. So the check is against the *real* path, after
+ *   symlink resolution, on every call — not against the string.
+ *
+ * The root itself is resolved once at construction, also through `realpath`: a root that is itself a symlink
+ * would otherwise make every real path look like an escape.
+ *
+ * ## Bytes are bounded while reading
+ *
+ * A cap applied after `readFile` has already buffered a two-gigabyte file protects nothing. These read into a
+ * fixed buffer and report `truncated`, which is the same decision `http.ts` made for the same reason. Truncation
+ * rather than refusal, because "the first 200 KB of the log" is usually the answer, and a refusal leaves the
+ * model with nothing.
+ */
+/** Bytes returned from one read. Matches the HTTP client's ceiling, for the same reason. */
+export declare const MAX_FILE_BYTES = 200000;
+/** Entries returned from one listing. A directory of ten thousand files is not an answer. */
+export declare const MAX_ENTRIES = 200;
+/** Files examined by one search. Bounded work, so a search cannot become a filesystem crawl. */
+export declare const MAX_SEARCHED_FILES = 2000;
+/** Matches returned from one search. */
+export declare const MAX_MATCHES = 100;
+export type FileScope = {
+    /** Everything readable, and the only thing readable. Resolved through `realpath` at construction. */
+    readonly root: string;
+    /**
+     * Where writes may land, when writes are wanted at all.
+     *
+     * Separate from `root`, and absent by default. A deployment that pointed both at the same directory would let
+     * a model edit the material it also reads — which is how a corpus a model cites becomes a corpus a model wrote.
+     */
+    readonly writableRoot?: string;
+    readonly maxBytes?: number;
+    readonly maxEntries?: number;
+    readonly maxMatches?: number;
+    readonly maxSearchedFiles?: number;
+};
+/**
+ * Why a file operation did not happen.
+ *
+ * A *reason*, not an exception, for the reason `HttpFailure` gives: a refused path is information the model can
+ * act on, and a thrown error reads as "something broke", which invites an identical retry.
+ */
+export type FileFailure = {
+    readonly ok: false;
+    readonly path: string;
+    readonly kind: "forbidden" | "not-found" | "not-a-file" | "not-a-directory" | "unreadable" | "too-many";
+    readonly reason: string;
+};
+export type FileRead = {
+    readonly ok: true;
+    readonly path: string;
+    readonly bytes: number;
+    readonly truncated: boolean;
+    readonly content: string;
+};
+export type FileEntry = {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: "file" | "directory" | "other";
+    readonly bytes?: number;
+};
+export type FileList = {
+    readonly ok: true;
+    readonly path: string;
+    readonly entries: readonly FileEntry[];
+    readonly truncated: boolean;
+};
+export type FileMatch = {
+    readonly path: string;
+    readonly line: number;
+    /** The matching line, trimmed and capped. Untrusted content, like everything else read from disk. */
+    readonly text: string;
+};
+export type FileSearch = {
+    readonly ok: true;
+    readonly query: string;
+    readonly matches: readonly FileMatch[];
+    readonly filesSearched: number;
+    /** True when the file or match ceiling stopped the search early. */
+    readonly truncated: boolean;
+};
+export type FileWrite = {
+    readonly ok: true;
+    readonly path: string;
+    readonly bytes: number;
+    readonly created: boolean;
+};
+/**
+ * Is `candidate` inside `root`, both already real paths?
+ *
+ * `relative` rather than `startsWith`: `/srv/data-secrets` starts with `/srv/data`, and a prefix comparison would
+ * accept it. A relative path that begins with `..` or is absolute is outside.
+ */
+export declare const contains: (root: string, candidate: string) => boolean;
+export type FileReader = {
+    read(path: string): FileRead | FileFailure;
+    list(path?: string): FileList | FileFailure;
+    search(input: {
+        readonly query: string;
+        readonly path?: string;
+        readonly namePattern?: string;
+    }): FileSearch | FileFailure;
+    write(input: {
+        readonly path: string;
+        readonly content: string;
+    }): FileWrite | FileFailure;
+};
+export declare const createFileReader: (scope: FileScope) => FileReader;
+//# sourceMappingURL=files.d.ts.map

package/dist/toolkit/files.js

@@ -0,0 +1,320 @@
+/**
+ * Reading and writing files, path-scoped — REQ-047 (#206), task #215.
+ *
+ * In `toolkit/` rather than `tools/` because it performs I/O and boundary rule **R7** forbids that in the tools
+ * layer, the same arrangement `http.ts` has with the web tools. The tools in `tools/library/fs.ts` are envelopes
+ * over these functions, and every security property lives here — not in the envelope, and not in the schema.
+ *
+ * ## The one property that matters
+ *
+ * **A path a model produced must not be able to name a file outside the configured root**, and there are three
+ * ways it tries:
+ *
+ * - `../../etc/passwd` — normalised away by resolving against the root first.
+ * - `/etc/passwd` — an absolute path is **refused outright** rather than silently re-rooted. Re-rooting would
+ *   answer a different question than the one asked, and the model would not know.
+ * - A **symlink** inside the root pointing out of it. This is the one that gets missed, because the path is
+ *   inside the root right up until the filesystem resolves it. So the check is against the *real* path, after
+ *   symlink resolution, on every call — not against the string.
+ *
+ * The root itself is resolved once at construction, also through `realpath`: a root that is itself a symlink
+ * would otherwise make every real path look like an escape.
+ *
+ * ## Bytes are bounded while reading
+ *
+ * A cap applied after `readFile` has already buffered a two-gigabyte file protects nothing. These read into a
+ * fixed buffer and report `truncated`, which is the same decision `http.ts` made for the same reason. Truncation
+ * rather than refusal, because "the first 200 KB of the log" is usually the answer, and a refusal leaves the
+ * model with nothing.
+ */
+import { closeSync, existsSync, openSync, readSync, readdirSync, realpathSync, statSync, writeFileSync, mkdirSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+/** Bytes returned from one read. Matches the HTTP client's ceiling, for the same reason. */
+export const MAX_FILE_BYTES = 200_000;
+/** Entries returned from one listing. A directory of ten thousand files is not an answer. */
+export const MAX_ENTRIES = 200;
+/** Files examined by one search. Bounded work, so a search cannot become a filesystem crawl. */
+export const MAX_SEARCHED_FILES = 2_000;
+/** Matches returned from one search. */
+export const MAX_MATCHES = 100;
+const forbidden = (path, reason) => ({ ok: false, path, kind: "forbidden", reason });
+/**
+ * Is `candidate` inside `root`, both already real paths?
+ *
+ * `relative` rather than `startsWith`: `/srv/data-secrets` starts with `/srv/data`, and a prefix comparison would
+ * accept it. A relative path that begins with `..` or is absolute is outside.
+ */
+export const contains = (root, candidate) => {
+    if (candidate === root)
+        return true;
+    const rel = relative(root, candidate);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+};
+export const createFileReader = (scope) => {
+    const maxBytes = scope.maxBytes ?? MAX_FILE_BYTES;
+    const maxEntries = scope.maxEntries ?? MAX_ENTRIES;
+    const maxMatches = scope.maxMatches ?? MAX_MATCHES;
+    const maxSearched = scope.maxSearchedFiles ?? MAX_SEARCHED_FILES;
+    /**
+     * The root, resolved once through `realpath`.
+     *
+     * A root that is itself a symlink — `/tmp` on macOS is `/private/tmp` — would otherwise make every resolved
+     * path look like an escape, and the tool would refuse everything while appearing to be configured correctly.
+     */
+    const realRoot = realpathSync(scope.root);
+    const realWritable = scope.writableRoot === undefined ? undefined : realpathSync(scope.writableRoot);
+    /** Resolve a model-supplied path inside a root, or say why not. */
+    const within = (root, requested, mustExist) => {
+        if (isAbsolute(requested))
+            return forbidden(requested, "Give a path relative to the configured root. An absolute path is refused rather than re-rooted, so a " +
+                "refusal is never mistaken for a different file.");
+        const joined = resolve(root, requested);
+        /**
+         * Lexical containment first, before the filesystem is consulted at all.
+         *
+         * `../../etc/passwd` used to come back as `not-found`, because `realpath` threw on a path that does not exist
+         * and the containment check never ran. Technically safe and a poor answer: the model learns that a path it
+         * may not read merely happens to be absent, which is a different fact and an invitation to try another. It
+         * also means the refusal depended on the target's existence, which is not a property anybody wants a security
+         * boundary to have.
+         */
+        if (!contains(root, joined))
+            return forbidden(requested, "That path is outside the configured root.");
+        if (mustExist) {
+            let real;
+            try {
+                real = realpathSync(joined);
+            }
+            catch {
+                return { ok: false, path: requested, kind: "not-found", reason: `No such path: ${requested}` };
+            }
+            if (!contains(root, real))
+                return forbidden(requested, "That path resolves outside the configured root. Symlinks are followed and then checked.");
+            return { ok: true, path: real };
+        }
+        /**
+         * For a write, the target may not exist yet — nor may its directory.
+         *
+         * So walk up to the nearest ancestor that *does* exist, resolve **that** through `realpath`, and rebuild the
+         * target beneath it. The first version resolved `dirname` only, which refused every write into a directory it
+         * was about to create — a correct-looking check that made the tool useless. Resolving the existing prefix is
+         * what keeps the symlink guarantee: a link anywhere along the real part of the path is followed and checked.
+         */
+        const missing = [];
+        let probe = joined;
+        while (!existsSync(probe)) {
+            const parent = dirname(probe);
+            if (parent === probe)
+                break;
+            missing.unshift(basename(probe));
+            probe = parent;
+        }
+        let realPrefix;
+        try {
+            realPrefix = realpathSync(probe);
+        }
+        catch {
+            return { ok: false, path: requested, kind: "not-found", reason: `No such path: ${requested}` };
+        }
+        const candidate = missing.length === 0 ? realPrefix : join(realPrefix, ...missing);
+        if (!contains(root, candidate))
+            return forbidden(requested, "That path resolves outside the configured root. Symlinks are followed and then checked.");
+        return { ok: true, path: candidate };
+    };
+    const readBounded = (path) => {
+        let handle;
+        try {
+            handle = openSync(path, "r");
+        }
+        catch (error) {
+            return { ok: false, path, kind: "unreadable", reason: error.message };
+        }
+        try {
+            const buffer = Buffer.alloc(maxBytes + 1);
+            const read = readSync(handle, buffer, 0, maxBytes + 1, 0);
+            const truncated = read > maxBytes;
+            return {
+                ok: true,
+                path,
+                bytes: truncated ? maxBytes : read,
+                truncated,
+                content: buffer.subarray(0, truncated ? maxBytes : read).toString("utf8"),
+            };
+        }
+        catch (error) {
+            return { ok: false, path, kind: "unreadable", reason: error.message };
+        }
+        finally {
+            closeSync(handle);
+        }
+    };
+    /** A deliberately small pattern language: `*.md`, `report*`, `*draft*`. Not a glob engine. */
+    const matchesName = (name, pattern) => {
+        if (pattern === undefined || pattern === "")
+            return true;
+        const parts = pattern.toLowerCase().split("*");
+        const lower = name.toLowerCase();
+        if (parts.length === 1)
+            return lower === (parts[0] ?? "");
+        let index = 0;
+        for (const [position, part] of parts.entries()) {
+            if (part === "")
+                continue;
+            const at = lower.indexOf(part, index);
+            if (at === -1)
+                return false;
+            if (position === 0 && at !== 0)
+                return false;
+            index = at + part.length;
+        }
+        const last = parts[parts.length - 1] ?? "";
+        return last === "" || lower.endsWith(last);
+    };
+    return {
+        read(requested) {
+            const scoped = within(realRoot, requested, true);
+            if (!scoped.ok)
+                return scoped;
+            let stats;
+            try {
+                stats = statSync(scoped.path);
+            }
+            catch (error) {
+                return { ok: false, path: requested, kind: "not-found", reason: error.message };
+            }
+            if (stats.isDirectory())
+                return { ok: false, path: requested, kind: "not-a-file", reason: `${requested} is a directory — use fs_list.` };
+            const outcome = readBounded(scoped.path);
+            return outcome.ok ? { ...outcome, path: relative(realRoot, scoped.path) || "." } : { ...outcome, path: requested };
+        },
+        list(requested = ".") {
+            const scoped = within(realRoot, requested, true);
+            if (!scoped.ok)
+                return scoped;
+            let names;
+            try {
+                names = readdirSync(scoped.path).sort();
+            }
+            catch (error) {
+                const message = error.code === "ENOTDIR" ? `${requested} is a file — use fs_read.` : error.message;
+                return {
+                    ok: false,
+                    path: requested,
+                    kind: error.code === "ENOTDIR" ? "not-a-directory" : "unreadable",
+                    reason: message,
+                };
+            }
+            const entries = [];
+            for (const name of names.slice(0, maxEntries)) {
+                const full = join(scoped.path, name);
+                let stats;
+                try {
+                    stats = statSync(full);
+                }
+                catch {
+                    // A broken symlink or a file removed mid-listing. Reported as `other` rather than omitted: a name that
+                    // exists and cannot be described is more useful than a silently shorter list.
+                    entries.push({ name, path: relative(realRoot, full), kind: "other" });
+                    continue;
+                }
+                entries.push({
+                    name,
+                    path: relative(realRoot, full),
+                    kind: stats.isDirectory() ? "directory" : stats.isFile() ? "file" : "other",
+                    ...(stats.isFile() ? { bytes: stats.size } : {}),
+                });
+            }
+            return { ok: true, path: relative(realRoot, scoped.path) || ".", entries, truncated: names.length > maxEntries };
+        },
+        search({ query, path = ".", namePattern }) {
+            if (query.trim() === "")
+                return { ok: false, path, kind: "unreadable", reason: "Give something to search for." };
+            const scoped = within(realRoot, path, true);
+            if (!scoped.ok)
+                return scoped;
+            const needle = query.toLowerCase();
+            const matches = [];
+            let searched = 0;
+            let truncated = false;
+            const walk = (dir) => {
+                if (truncated)
+                    return;
+                let names;
+                try {
+                    names = readdirSync(dir).sort();
+                }
+                catch {
+                    return;
+                }
+                for (const name of names) {
+                    if (truncated)
+                        return;
+                    const full = join(dir, name);
+                    let stats;
+                    try {
+                        stats = statSync(full);
+                    }
+                    catch {
+                        continue;
+                    }
+                    // The real path is checked here too: a symlinked directory inside the root would otherwise let a
+                    // search walk out of it, which is the same escape as a symlinked file and easier to miss.
+                    if (!contains(realRoot, realpathSync(full)))
+                        continue;
+                    if (stats.isDirectory()) {
+                        walk(full);
+                        continue;
+                    }
+                    if (!stats.isFile() || !matchesName(name, namePattern))
+                        continue;
+                    searched += 1;
+                    if (searched > maxSearched) {
+                        truncated = true;
+                        return;
+                    }
+                    const read = readBounded(full);
+                    if (!read.ok)
+                        continue;
+                    read.content.split("\n").forEach((line, index) => {
+                        if (truncated || !line.toLowerCase().includes(needle))
+                            return;
+                        if (matches.length >= maxMatches) {
+                            truncated = true;
+                            return;
+                        }
+                        matches.push({ path: relative(realRoot, full), line: index + 1, text: line.trim().slice(0, 400) });
+                    });
+                }
+            };
+            walk(scoped.path);
+            return { ok: true, query, matches, filesSearched: searched, truncated };
+        },
+        write({ path, content }) {
+            if (realWritable === undefined)
+                return forbidden(path, "No writable root is configured, so nothing can be written. This is a wiring decision, not a " +
+                    "permission one — see FileScope.writableRoot.");
+            const scoped = within(realWritable, path, false);
+            if (!scoped.ok)
+                return scoped;
+            const bytes = Buffer.byteLength(content, "utf8");
+            if (bytes > maxBytes)
+                return { ok: false, path, kind: "too-many", reason: `That is ${bytes} bytes; the ceiling is ${maxBytes}.` };
+            let created = true;
+            try {
+                created = !statSync(scoped.path).isFile();
+            }
+            catch {
+                created = true;
+            }
+            try {
+                mkdirSync(dirname(scoped.path), { recursive: true });
+                writeFileSync(scoped.path, content, "utf8");
+            }
+            catch (error) {
+                return { ok: false, path, kind: "unreadable", reason: error.message };
+            }
+            return { ok: true, path: relative(realWritable, scoped.path), bytes, created };
+        },
+    };
+};
+//# sourceMappingURL=files.js.map

package/dist/toolkit/index.d.ts

@@ -18,4 +18,8 @@ export { MAX_CELL_CHARS, MAX_CSV_ROWS, MAX_SQL_ROWS, createSqlQuery, createSqlSc
 export type { CsvResult, JsonQueryResult, ReadOnlyQuery, SchemaResult, SqlResult } from "./data.js";
 export { MAX_EXPRESSION_CHARS, calculate, currentTime } from "./compute.js";
 export type { CalculationResult, TimeResult } from "./compute.js";
+export { MAX_ENTRIES, MAX_FILE_BYTES, MAX_MATCHES, MAX_SEARCHED_FILES, contains, createFileReader, } from "./files.js";
+export type { FileEntry, FileFailure, FileList, FileMatch, FileRead, FileReader, FileScope, FileSearch, FileWrite } from "./files.js";
+export { DEFAULT_MEMORY_MB, DEFAULT_TIMEOUT_MS, MAX_OUTPUT_BYTES, createDockerSandbox, createLocalSandbox, dockerArgs, } from "./sandbox.js";
+export type { DockerSandboxConfig, LocalSandboxConfig, Sandbox, SandboxRequest, SandboxResult } from "./sandbox.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/toolkit/index.js

@@ -14,4 +14,6 @@ export { DEFAULT_EGRESS_POLICY, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS, createHt
 export { DEFAULT_SEARCH_LIMIT, MAX_SNIPPET_CHARS, createFetchJson, createFetchPage, createWebSearch, htmlToText, } from "./web.js";
 export { MAX_CELL_CHARS, MAX_CSV_ROWS, MAX_SQL_ROWS, createSqlQuery, createSqlSchema, parseCsv, queryJson, } from "./data.js";
 export { MAX_EXPRESSION_CHARS, calculate, currentTime } from "./compute.js";
+export { MAX_ENTRIES, MAX_FILE_BYTES, MAX_MATCHES, MAX_SEARCHED_FILES, contains, createFileReader, } from "./files.js";
+export { DEFAULT_MEMORY_MB, DEFAULT_TIMEOUT_MS, MAX_OUTPUT_BYTES, createDockerSandbox, createLocalSandbox, dockerArgs, } from "./sandbox.js";
 //# sourceMappingURL=index.js.map

package/dist/toolkit/sandbox.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Running a command somewhere it cannot hurt you — REQ-047 (#206), task #215.
+ *
+ * `shell_exec` is the only tool in this package whose blast radius is not described by its schema. Every other
+ * tool can do one thing to one kind of object; this one can do anything the process can do. And its trigger is
+ * natural language — including language the model merely *read*, in a document, in an issue body, in a Slack
+ * message. Without isolation, a shell tool is a remote code execution endpoint reachable by anyone who can get
+ * text in front of the agent.
+ *
+ * So the sandbox is not a hardening step applied afterwards. It is the thing that makes the tool defensible, and
+ * the tool does not exist without one wired.
+ *
+ * ## What the contract guarantees
+ *
+ * | Guarantee | Why it is not optional |
+ * |---|---|
+ * | No network | A command that can reach the network can exfiltrate anything it can read, and the egress policy does not apply inside a container |
+ * | Read-only root, one writable scratch mount | A command that can write to the image can install a persistent foothold |
+ * | Memory cap | An unbounded allocation takes the host down with it, and that is a denial of service anybody can trigger by asking |
+ * | Wall-clock timeout | `sleep 999` must end as a *timeout*, not as an empty success |
+ * | No TTY | An interactive prompt would hang forever waiting for a person who is not there |
+ * | Output cap, with the truncation reported | Silent truncation makes a model believe it saw the whole answer |
+ * | The exit code in the envelope | Inferring success from output text is guessing; a non-zero exit is a fact |
+ *
+ * ## Gating is by effect, never by reading the command
+ *
+ * `shell_exec` is classified `destructive` and routed through the approval gate. It is tempting to inspect the
+ * command instead — refuse `rm -rf`, allow `ls` — and that is a losing game: `find . -delete`, `>file`, `dd`,
+ * `python -c`, a base64 pipeline. Any list of dangerous shapes is a list somebody gets around, and worse, it
+ * *feels* like protection. A classification cannot be evaded by rephrasing.
+ */
+/** Bytes of stdout and of stderr returned. Beyond this the output is truncated and says so. */
+export declare const MAX_OUTPUT_BYTES = 64000;
+/** Wall clock. A model waiting on a hung command is a run holding a worker slot. */
+export declare const DEFAULT_TIMEOUT_MS = 20000;
+export declare const DEFAULT_MEMORY_MB = 256;
+export type SandboxRequest = {
+    /** The command, run by a shell inside the sandbox. Never interpreted or inspected here. */
+    readonly command: string;
+    readonly timeoutMs?: number;
+    readonly memoryMb?: number;
+    /** Files to place in the scratch mount before running, by relative path. */
+    readonly files?: Readonly<Record<string, string>>;
+};
+export type SandboxResult = {
+    /** Whether the command *ran to completion*. A non-zero exit is `ok: true` with a non-zero code. */
+    readonly ok: boolean;
+    /**
+     * The process's exit code, or null when it never produced one.
+     *
+     * Null is the honest answer for a killed process, and it is why `reason` exists: "exit code 137" and "we killed
+     * it after 20 seconds" are the same event described at two levels, and the model needs the second one.
+     */
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
+    /** Set when the sandbox ended the command itself. */
+    readonly reason?: "timeout" | "memory" | "spawn-failed";
+    readonly durationMs: number;
+};
+/**
+ * A place to run a command. A port, because where that place is — a container here, a microVM, E2B, Daytona — is
+ * a deployment's decision and not this package's.
+ */
+export interface Sandbox {
+    readonly id: string;
+    run(request: SandboxRequest): Promise<SandboxResult>;
+}
+export type DockerSandboxConfig = {
+    /** The image. A deployment's choice, and it should be one with a shell and nothing else. */
+    readonly image: string;
+    readonly docker?: string;
+    readonly timeoutMs?: number;
+    readonly memoryMb?: number;
+    /** Extra flags, appended after the enforced ones so they cannot remove them. */
+    readonly extraArgs?: readonly string[];
+    readonly shell?: string;
+};
+/**
+ * The argv, built separately so it can be asserted on.
+ *
+ * Every security property of this adapter *is* this array. A test that ran a command and checked its output would
+ * pass just as well with `--network=none` missing, so the argv is what the tests read — and the flags come before
+ * `extraArgs`, so a deployment adding options cannot quietly drop one.
+ */
+export declare const dockerArgs: (config: DockerSandboxConfig, request: SandboxRequest) => readonly string[];
+/**
+ * The real adapter: one container per command, destroyed after.
+ *
+ * Not a pool. A reused container is a container a previous command could have left something in, and the whole
+ * proposition here is that a command cannot affect anything outside itself.
+ */
+export declare const createDockerSandbox: (config: DockerSandboxConfig) => Sandbox;
+export type LocalSandboxConfig = {
+    /**
+     * Required, and named to be uncomfortable to type.
+     *
+     * There is no safe default here. A shell on the runtime's own host has no isolation at all: the command runs as
+     * the runtime user, with its filesystem, its network and its credentials. That is a remote code execution
+     * endpoint reachable through content the model merely read.
+     */
+    readonly allowUnsafeLocalExecution: true;
+    readonly timeoutMs?: number;
+    readonly shell?: string;
+};
+/**
+ * The development adapter, which **refuses to exist** unless a deployment says so in words.
+ *
+ * The refusal is at construction rather than at the call, so a misconfiguration is a boot failure rather than a
+ * surprise the first time somebody asks the agent to run something. And the message says what to do instead,
+ * because "not allowed" without a next step is how a flag gets set to make an error go away.
+ *
+ * It provides the timeout and the output cap. It provides **none** of the isolation: no network isolation, no
+ * memory cap, no read-only filesystem, no dropped capabilities. The contract's table describes what a sandbox
+ * guarantees; this adapter meets one row of it, and saying so is the point.
+ */
+export declare const createLocalSandbox: (config: LocalSandboxConfig) => Sandbox;
+//# sourceMappingURL=sandbox.d.ts.map