@retinue/agentkit 0.1.0 → 0.3.0

package/dist/toolkit/mime.js

@@ -0,0 +1,233 @@
+/**
+ * RFC 5322 messages, built once for every toolkit that sends mail — REQ-056 (#240), task #241.
+ *
+ * This started in `tools-google` for Gmail (#234) and moved here when `tools-email` needed the same thing. The
+ * reason is the one that moved `ssrf.ts`: the parts that are silent when wrong must have exactly one
+ * implementation, because a second copy is the one that ends up not encoding a header.
+ *
+ * Three things here are wrong *silently*, which is why they are here rather than per package:
+ *
+ * **A non-ASCII subject.** Headers are ASCII by the spec. Putting an umlaut in one raw does not throw — it
+ * arrives as mojibake and nobody tells you.
+ *
+ * **A header carrying a line break.** A subject of `Update` + CRLF + `Bcc: attacker@example.com` is two
+ * headers, and the second silently copies the message to somebody. Reachable from untrusted content: an agent
+ * composing a subject from a page it scraped or a mail it read is exactly the path.
+ *
+ * **Part ordering in `multipart/alternative`.** The spec orders parts least-faithful first, so `text/plain`
+ * precedes `text/html`. Reversed, a client showing the *last* part it understands displays the plain-text
+ * fallback and the HTML is never seen — mail that looks broken to the recipient and fine to the sender.
+ *
+ * ## Determinism, and why there is no `Date` or `Message-ID`
+ *
+ * `email_compose_preview` has to produce **byte-identical** output to what a send transmits, or the rehearsal
+ * is of a different message. A `Date` stamped at compose time makes that impossible by construction, and a
+ * `Message-ID` generated per call makes it impossible too. Both are added by the sending MTA or the provider's
+ * API, which is where they belong — they describe the act of sending, not the message the caller wrote. The
+ * multipart boundary is derived from a hash of the content for the same reason: a random boundary would make
+ * two composes of the same message differ.
+ */
+import { createHash } from "node:crypto";
+/** A header value, RFC 2047 encoded when it needs to be — and left alone when it does not. */
+export const encodeHeader = (value) => {
+    // Only when needed: an ASCII subject must stay readable in the raw message, because half of debugging mail
+    // is reading it with your eyes. An encoded-word on everything would be correct and unreadable.
+    if (!/[^ -~]/.test(value))
+        return value;
+    // 75 is the RFC limit for an encoded-word *including* its wrapper, so the payload budget is smaller; base64
+    // expands by 4/3, hence a multiple of 3.
+    const budget = 45;
+    const bytes = Buffer.from(value, "utf8");
+    const words = [];
+    for (let offset = 0; offset < bytes.length;) {
+        // Never split a multi-byte character across two encoded-words: each word must decode on its own.
+        let take = Math.min(budget, bytes.length - offset);
+        while (take > 0 && offset + take < bytes.length && (bytes[offset + take] & 0xc0) === 0x80)
+            take -= 1;
+        if (take === 0)
+            take = Math.min(budget, bytes.length - offset);
+        words.push(`=?UTF-8?B?${bytes.subarray(offset, offset + take).toString("base64")}?=`);
+        offset += take;
+    }
+    // Folded with a space between words, which is how a decoder is told they are one value.
+    return words.join(" ");
+};
+export class HeaderInjectionError extends Error {
+}
+/**
+ * Refuses a header value that would inject another header.
+ *
+ * Refusing rather than stripping: no legitimate subject or address contains a newline, so nothing correct is
+ * lost, and silently removing it would hide an attempt somebody should see.
+ */
+export const assertHeaderSafe = (field, value) => {
+    if (/[\r\n]/.test(value)) {
+        throw new HeaderInjectionError(`The ${field} contains a line break, which would inject a new mail header. Refused rather than sent — ` +
+            "this is how a Bcc gets added to a message nobody meant to copy.");
+    }
+};
+const CRLF = "\r\n";
+/** Base64, folded at 76 characters — an unfolded base64 body is non-conformant and some servers reject it. */
+const foldedBase64 = (value) => {
+    const encoded = Buffer.from(value, "utf8").toString("base64");
+    return encoded.match(/.{1,76}/g)?.join(CRLF) ?? "";
+};
+/**
+ * A boundary that depends only on the message.
+ *
+ * Deterministic so `email_compose_preview` and `email_send` produce the same bytes, and content-derived so two
+ * different messages do not share one. The loop rules out the remaining case where the chosen boundary appears
+ * inside a part — astronomically unlikely with a hash, and cheaper to exclude than to reason about.
+ */
+export const boundaryFor = (parts) => {
+    const digest = createHash("sha256").update(parts.join(" "), "utf8").digest("hex");
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        const candidate = `=_retinue_${digest.slice(attempt * 4, attempt * 4 + 32)}`;
+        if (!parts.some((part) => part.includes(candidate)))
+            return candidate;
+    }
+    return `=_retinue_${digest}`;
+};
+const renderPart = (headers, content) => `${headers.join(CRLF)}${CRLF}${CRLF}${content}`;
+const textPart = (text) => renderPart(['Content-Type: text/plain; charset="UTF-8"', "Content-Transfer-Encoding: base64"], foldedBase64(text));
+const htmlPart = (html) => renderPart(['Content-Type: text/html; charset="UTF-8"', "Content-Transfer-Encoding: base64"], foldedBase64(html));
+const attachmentPart = (attachment) => {
+    assertHeaderSafe("attachment filename", attachment.filename);
+    assertHeaderSafe("attachment content type", attachment.contentType);
+    return renderPart([
+        `Content-Type: ${attachment.contentType}; name="${encodeHeader(attachment.filename)}"`,
+        "Content-Transfer-Encoding: base64",
+        `Content-Disposition: attachment; filename="${encodeHeader(attachment.filename)}"`,
+    ], attachment.contentBase64.replace(/\s+/g, "").match(/.{1,76}/g)?.join(CRLF) ?? "");
+};
+const multipart = (subtype, parts) => {
+    const boundary = boundaryFor(parts);
+    return {
+        contentType: `multipart/${subtype}; boundary="${boundary}"`,
+        body: [
+            // A preamble, for clients that show nothing when they cannot parse the structure. Never displayed by one
+            // that can.
+            "This is a message in MIME format.",
+            ...parts.map((body) => `--${boundary}${CRLF}${body}`),
+            `--${boundary}--`,
+            "",
+        ].join(CRLF),
+    };
+};
+/** Splits a rendered part into its header lines and its content. */
+const splitPart = (rendered) => {
+    const separator = rendered.indexOf(`${CRLF}${CRLF}`);
+    if (separator === -1)
+        return [[], rendered];
+    return [rendered.slice(0, separator).split(CRLF), rendered.slice(separator + 4)];
+};
+/**
+ * An RFC 5322 message.
+ *
+ * CRLF line endings, not bare newlines: the spec says CRLF and some servers are strict. Getting it wrong
+ * produces a message that works with most providers and is rejected by one, which is the worst kind of bug to
+ * find in production.
+ */
+export const buildMessage = (message) => {
+    const text = message.text ?? message.body;
+    const hasText = text !== undefined && text !== "";
+    const hasHtml = message.html !== undefined && message.html !== "";
+    if (!hasText && !hasHtml) {
+        throw new Error("A message needs a text body, an HTML body, or both.");
+    }
+    // Every header value, before any of them is written.
+    for (const [field, value] of [
+        ["subject", message.subject],
+        ["from", message.from ?? ""],
+        ["reply-to", message.replyTo ?? ""],
+        ...message.to.map((address) => ["recipient", address]),
+        ...(message.cc ?? []).map((address) => ["cc recipient", address]),
+        ...(message.bcc ?? []).map((address) => ["bcc recipient", address]),
+        ...Object.entries(message.headers ?? {}).map(([name, value]) => [`${name} header`, value]),
+    ]) {
+        assertHeaderSafe(field, value);
+    }
+    const headers = [];
+    if (message.from !== undefined)
+        headers.push(`From: ${message.from}`);
+    headers.push(`To: ${message.to.join(", ")}`);
+    if (message.cc !== undefined && message.cc.length > 0)
+        headers.push(`Cc: ${message.cc.join(", ")}`);
+    /**
+     * `Bcc` **is** written into the message this function returns.
+     *
+     * Correct for an API that takes a composed message and reads the recipients out of it, and wrong for SMTP,
+     * where the envelope carries the recipients and a `Bcc` header would show every blind recipient to all of
+     * them. The SMTP transport strips it — see `stripBcc` — rather than this function guessing which kind of
+     * caller it has. A preview shows it, because somebody inspecting a rehearsal should see who is on it.
+     */
+    if (message.bcc !== undefined && message.bcc.length > 0)
+        headers.push(`Bcc: ${message.bcc.join(", ")}`);
+    if (message.replyTo !== undefined)
+        headers.push(`Reply-To: ${message.replyTo}`);
+    headers.push(`Subject: ${encodeHeader(message.subject)}`);
+    /**
+     * Both threading headers, from the original's `Message-ID`.
+     *
+     * `In-Reply-To` is what most clients thread on and `References` is what the rest use, so sending one without
+     * the other threads correctly in some inboxes and starts a new conversation in others.
+     */
+    if (message.inReplyTo !== undefined) {
+        headers.push(`In-Reply-To: ${message.inReplyTo}`);
+        const chain = message.references === undefined || message.references.trim() === ""
+            ? message.inReplyTo
+            : `${message.references.trim()} ${message.inReplyTo}`;
+        headers.push(`References: ${chain}`);
+    }
+    for (const [name, value] of Object.entries(message.headers ?? {}))
+        headers.push(`${name}: ${encodeHeader(value)}`);
+    headers.push("MIME-Version: 1.0");
+    const bodyParts = [];
+    if (hasText)
+        bodyParts.push(textPart(text));
+    // Plain text first. The spec orders parts least-faithful first, and a client showing the last part it
+    // understands would otherwise display the fallback and never the HTML.
+    if (hasHtml)
+        bodyParts.push(htmlPart(message.html));
+    const attachments = message.attachments ?? [];
+    if (bodyParts.length === 1 && attachments.length === 0) {
+        // The single-body case, byte-identical to what this produced before multipart existed.
+        const [partHeaders, content] = splitPart(bodyParts[0]);
+        return `${[...headers, ...partHeaders].join(CRLF)}${CRLF}${CRLF}${content}`;
+    }
+    const alternative = bodyParts.length > 1 ? multipart("alternative", bodyParts) : undefined;
+    const bodySection = alternative === undefined
+        ? bodyParts[0]
+        : renderPart([`Content-Type: ${alternative.contentType}`], alternative.body);
+    if (attachments.length === 0) {
+        const only = alternative;
+        return `${headers.join(CRLF)}${CRLF}Content-Type: ${only.contentType}${CRLF}${CRLF}${only.body}`;
+    }
+    const mixed = multipart("mixed", [bodySection, ...attachments.map(attachmentPart)]);
+    return `${headers.join(CRLF)}${CRLF}Content-Type: ${mixed.contentType}${CRLF}${CRLF}${mixed.body}`;
+};
+/**
+ * Removes the `Bcc` header from a composed message.
+ *
+ * For SMTP the envelope carries every recipient and the header must not, or each blind recipient can read the
+ * whole blind list — the single most embarrassing mail bug there is. The header is kept in the composed form
+ * so a preview can show it, and stripped at the transport that would otherwise leak it.
+ */
+export const stripBcc = (raw) => {
+    const separator = raw.indexOf(`${CRLF}${CRLF}`);
+    if (separator === -1)
+        return raw;
+    const kept = raw
+        .slice(0, separator)
+        .split(CRLF)
+        .filter((line) => !/^bcc:/i.test(line));
+    return `${kept.join(CRLF)}${raw.slice(separator)}`;
+};
+/** The value of a header in a composed message, for tests and for reading a provider's echo. */
+export const headerOf = (raw, name) => {
+    const separator = raw.indexOf(`${CRLF}${CRLF}`);
+    const head = separator === -1 ? raw : raw.slice(0, separator);
+    const match = new RegExp(`^${name}:\\s*(.*)$`, "im").exec(head);
+    return match?.[1]?.trim();
+};
+//# sourceMappingURL=mime.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

package/dist/toolkit/sandbox.js

@@ -0,0 +1,239 @@
+/**
+ * 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.
+ */
+import { spawn } from "node:child_process";
+import { AgentPlatformError } from "../core/errors.js";
+/** Bytes of stdout and of stderr returned. Beyond this the output is truncated and says so. */
+export const MAX_OUTPUT_BYTES = 64_000;
+/** Wall clock. A model waiting on a hung command is a run holding a worker slot. */
+export const DEFAULT_TIMEOUT_MS = 20_000;
+export const DEFAULT_MEMORY_MB = 256;
+const cap = (text, limit) => Buffer.byteLength(text, "utf8") <= limit
+    ? { text, truncated: false }
+    : { text: Buffer.from(text, "utf8").subarray(0, limit).toString("utf8"), truncated: true };
+/**
+ * Spawn a process and bound it, shared by both adapters.
+ *
+ * The output cap is applied **while reading**, not afterwards: a command that prints a gigabyte would otherwise
+ * be buffered in full before any limit could run, which is the same mistake `readBounded` exists to avoid in the
+ * HTTP client.
+ *
+ * ## Two decisions the first version got wrong, and CI found
+ *
+ * **The whole process group is killed, not the child.** `sh -c "sleep 999"` may exec or may fork, and when it
+ * forks the grandchild survives a `SIGKILL` aimed at its parent — so a timed-out command left a process running
+ * on the host. `detached: true` makes the child a group leader; `process.kill(-pid)` takes the group with it.
+ *
+ * **Resolution is on `exit`, not `close`.** `close` waits for every stdio stream to end, and an orphaned
+ * grandchild *holds the pipe open* — so `sh -c "sleep 5 | cat"` never resolved at all. The timeout fired, the
+ * process was killed, and the promise hung until the test runner gave up thirty seconds later. Reproduced
+ * locally in one line once CI had pointed at it.
+ */
+const boundedSpawn = async (file, args, input) => {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        // A group leader, so a fork inside the shell can be killed with its parent.
+        const child = spawn(file, [...args], { stdio: ["ignore", "pipe", "pipe"], detached: true });
+        let out = "";
+        let err = "";
+        let truncated = false;
+        let reason;
+        const collect = (stream, append) => {
+            stream.on("data", (chunk) => {
+                const capped = cap(chunk.toString("utf8"), MAX_OUTPUT_BYTES);
+                if (capped.truncated)
+                    truncated = true;
+                append(capped.text);
+            });
+        };
+        collect(child.stdout, (chunk) => {
+            const capped = cap(out + chunk, MAX_OUTPUT_BYTES);
+            out = capped.text;
+            if (capped.truncated)
+                truncated = true;
+        });
+        collect(child.stderr, (chunk) => {
+            const capped = cap(err + chunk, MAX_OUTPUT_BYTES);
+            err = capped.text;
+            if (capped.truncated)
+                truncated = true;
+        });
+        /**
+         * The group, not the process.
+         *
+         * `-pid` addresses the group `detached` created. It throws if the group is already gone — a command that
+         * finished between the timer firing and this line — so the fallback is the plain kill, and neither is
+         * allowed to reject the promise.
+         */
+        const killGroup = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        };
+        const timer = setTimeout(() => {
+            reason = "timeout";
+            input.onKill?.();
+            killGroup();
+        }, input.timeoutMs);
+        // `exit` and `close` can both fire, and after a group kill only one of them may. Whichever arrives first
+        // answers, and the guard is what makes listening to both safe rather than a double resolution.
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        child.on("error", (error) => {
+            settle({
+                ok: false,
+                exitCode: null,
+                stdout: out,
+                stderr: `${err}${error.message}`,
+                truncated,
+                reason: "spawn-failed",
+                durationMs: Date.now() - startedAt,
+            });
+        });
+        const finish = (code) => settle({
+            // A timeout is not a completed command, whatever it printed before it died.
+            ok: reason === undefined,
+            exitCode: code,
+            stdout: out,
+            stderr: err,
+            truncated,
+            ...(reason === undefined ? {} : { reason }),
+            durationMs: Date.now() - startedAt,
+        });
+        /**
+         * `exit` fires when the process dies; `close` waits for its stdio to end.
+         *
+         * Preferring `exit` is the fix: a grandchild holding the pipe open means `close` may never come, and the
+         * output collected so far is still the output. `close` stays wired for the ordinary case, where it arrives
+         * a moment later with the last of the buffer flushed.
+         */
+        child.on("exit", (code) => finish(code));
+        child.on("close", (code) => finish(code));
+    });
+};
+/**
+ * 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 const dockerArgs = (config, request) => [
+    "run",
+    "--rm",
+    // No network at all. Not a restricted network: a command that can resolve a name can exfiltrate through it.
+    "--network=none",
+    // The image is immutable; only the scratch mount is writable, and it is a tmpfs that dies with the container.
+    "--read-only",
+    "--tmpfs=/scratch:rw,size=16m,mode=1777",
+    `--memory=${config.memoryMb ?? DEFAULT_MEMORY_MB}m`,
+    // Without this a memory-capped container can still be pushed into swap and take the host's disk with it.
+    `--memory-swap=${config.memoryMb ?? DEFAULT_MEMORY_MB}m`,
+    "--pids-limit=128",
+    "--cap-drop=ALL",
+    "--security-opt=no-new-privileges",
+    // Not root inside the container either. `--read-only` makes most of that moot; this makes the rest of it moot.
+    "--user=65534:65534",
+    "--workdir=/scratch",
+    // No TTY, and stdin closed: an interactive prompt has nobody to answer it and would hold the slot until the
+    // timeout, reported as a timeout, which is a confusing way to learn that a command asked a question.
+    ...(config.extraArgs ?? []),
+    config.image,
+    config.shell ?? "sh",
+    "-c",
+    request.command,
+];
+/**
+ * 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 const createDockerSandbox = (config) => ({
+    id: `docker:${config.image}`,
+    async run(request) {
+        const timeoutMs = request.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const args = dockerArgs({ ...config, ...(request.memoryMb === undefined ? {} : { memoryMb: request.memoryMb }) }, request);
+        const result = await boundedSpawn(config.docker ?? "docker", args, { timeoutMs });
+        /**
+         * 137 is SIGKILL, and inside a memory-capped container that is almost always the OOM killer.
+         *
+         * Reported as `memory` rather than left as a bare exit code, because "exit 137" is a number a reader has to
+         * look up and "the command ran out of memory" is the finding. Not claimed when we did the killing ourselves:
+         * a timeout is also a SIGKILL, and it is already named.
+         */
+        return result.exitCode === 137 && result.reason === undefined
+            ? { ...result, ok: false, reason: "memory" }
+            : result;
+    },
+});
+/**
+ * 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 const createLocalSandbox = (config) => {
+    if (config.allowUnsafeLocalExecution !== true) {
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: "The local sandbox runs commands on this host with no isolation: no network isolation, no memory cap, " +
+                "no read-only filesystem. It is for development only, and it requires " +
+                "`allowUnsafeLocalExecution: true` in so many words. For anything else, use createDockerSandbox — or " +
+                "leave shell_exec unwired, which is the default and is a legitimate answer.",
+            retryable: false,
+        });
+    }
+    return {
+        id: "local:unsafe",
+        async run(request) {
+            return boundedSpawn(config.shell ?? "sh", ["-c", request.command], {
+                timeoutMs: request.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            });
+        },
+    };
+};
+//# sourceMappingURL=sandbox.js.map