@retinue/agentkit 0.1.0 → 0.3.0

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/http.d.ts

@@ -57,6 +57,27 @@ export type HttpFailure = {
     readonly kind: "forbidden" | "redirected" | "timeout" | "unreachable" | "http-error" | "unreadable";
     readonly status?: number;
     readonly reason: string;
+    /**
+     * `Retry-After`, in milliseconds, when the server sent one.
+     *
+     * Parsed here because it is the one response header a *failure* still needs to carry: a vendor that answers
+     * `429` with `Retry-After: 47` has told you exactly how long to wait, and a default backoff that ignores it
+     * either hammers the vendor or waits far too long. `PlatformError.retryAfterMs` already exists and the retry
+     * path already reads it — this is the missing link between them.
+     *
+     * Both wire formats: a delay in seconds, and an HTTP date.
+     */
+    readonly retryAfterMs?: number;
+    /**
+     * The vendor's rate-limit headers, and **only** those — see `RATE_LIMIT_HEADERS`.
+     *
+     * An allowlist rather than every header, for two reasons. A failure travels into error messages and audit
+     * records, so carrying `set-cookie` or an auth echo would be a leak with no purpose. And a bounded set says
+     * what this field is *for*: `retryAfterMs` answers "how long", and these answer the question X forces —
+     * **which** limit was hit. A 15-minute burst limit and a 24-hour cap are both `429`, and treating the second
+     * as retryable makes a client sit in backoff until tomorrow.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
 };
 export type HttpSuccess = {
     readonly ok: true;
@@ -97,6 +118,12 @@ export type HttpRequest = {
 export type HttpClient = {
     request(input: HttpRequest): Promise<HttpOutcome>;
 };
+export declare const rateLimitHeadersOf: (headers: Headers) => {
+    headers?: Readonly<Record<string, string>>;
+};
+export declare const retryAfterOf: (headers: Headers) => {
+    retryAfterMs?: number;
+};
 export declare const createHttpClient: (config?: HttpClientConfig) => HttpClient;
 /**
  * Read at most `maxBytes`, stopping as they arrive, and abandon the rest.

package/dist/toolkit/http.js

@@ -56,6 +56,52 @@ export const REQUEST_TIMEOUT_MS = 10_000;
  * choose which credential to spend and where to send it. `host` forges the request target past the policy check.
  */
 const RESERVED_HEADERS = new Set(["authorization", "cookie", "proxy-authorization", "host", "content-length"]);
+/**
+ * `Retry-After` as milliseconds, in whichever of its two forms the server used.
+ *
+ * Returns a spreadable object rather than a number so an absent or unparseable header adds no key at all —
+ * `retryAfterMs: undefined` and "no retry hint" are different things to a consumer reading the field.
+ *
+ * A date in the past yields `0` rather than a negative delay, and an absurd value is capped: a vendor asking
+ * for a six-hour wait inside a request path is a vendor to give up on, not to obey.
+ */
+const MAX_RETRY_AFTER_MS = 5 * 60_000;
+/**
+ * The response headers a failure carries, by prefix.
+ *
+ * These are the shapes vendors actually use: `x-ratelimit-*` (GitHub, Reddit), `x-rate-limit-*` (X's
+ * per-15-minute window), `x-user-limit-24hour-*` / `x-app-limit-24hour-*` (X's daily caps, which are a
+ * different limit with a different remedy), and `x-ms-ratelimit-*` (Azure Resource Manager, whose
+ * `remaining-subscription-reads` counts *down* rather than reporting a ceiling — the only one of these that
+ * lets a client see a throttle approaching instead of discovering it).
+ */
+const RATE_LIMIT_HEADERS = [
+    "retry-after",
+    "x-ratelimit-",
+    "x-rate-limit-",
+    "x-user-limit-",
+    "x-app-limit-",
+    "x-ms-ratelimit-",
+];
+export const rateLimitHeadersOf = (headers) => {
+    const kept = {};
+    headers.forEach((value, name) => {
+        const lower = name.toLowerCase();
+        if (RATE_LIMIT_HEADERS.some((prefix) => lower === prefix || lower.startsWith(prefix)))
+            kept[lower] = value;
+    });
+    return Object.keys(kept).length === 0 ? {} : { headers: kept };
+};
+export const retryAfterOf = (headers) => {
+    const raw = headers.get("retry-after");
+    if (raw === null || raw.trim() === "")
+        return {};
+    const seconds = Number(raw.trim());
+    const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(raw.trim()) - Date.now();
+    if (!Number.isFinite(ms))
+        return {};
+    return { retryAfterMs: Math.min(Math.max(Math.round(ms), 0), MAX_RETRY_AFTER_MS) };
+};
 export const createHttpClient = (config = {}) => {
     const policy = config.policy ?? DEFAULT_EGRESS_POLICY;
     const doFetch = config.fetchImpl ?? fetch;
@@ -124,6 +170,8 @@ export const createHttpClient = (config = {}) => {
                         kind: "http-error",
                         status: response.status,
                         reason: `That URL returned ${response.status}${text.trim() === "" ? "" : `: ${text.slice(0, 500)}`}`,
+                        ...retryAfterOf(response.headers),
+                        ...rateLimitHeadersOf(response.headers),
                     };
                 }
                 const body = input.fence === false

package/dist/toolkit/index.d.ts

@@ -10,12 +10,42 @@
  * interesting behaviour of an outbound tool — what it refuses, where it stops reading — should be provable
  * without constructing a run.
  */
-export { DEFAULT_EGRESS_POLICY, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS, createHttpClient, readBounded, } from "./http.js";
+export { DEFAULT_EGRESS_POLICY, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS, createHttpClient, readBounded, rateLimitHeadersOf, retryAfterOf, } from "./http.js";
 export type { HttpClient, HttpClientConfig, HttpFailure, HttpOutcome, HttpRequest, HttpSuccess } from "./http.js";
+export { createVendorTransport } from "./vendor.js";
+/**
+ * RFC 5322 message building, shared — REQ-056 (#240), task #241.
+ *
+ * It began in `tools-google` and moved here when `tools-email` needed the same encoder. The header rules are
+ * the kind that fail *silently* — an unencoded non-ASCII subject arrives as mojibake, a header with a line
+ * break becomes two headers and the second copies the mail to somebody — so there is one implementation, and
+ * `tools-google` re-exports it rather than keeping a copy.
+ */
+export { assertHeaderSafe, boundaryFor, buildMessage, encodeHeader, HeaderInjectionError, headerOf, stripBcc, } from "./mime.js";
+export type { Attachment, OutgoingMessage } from "./mime.js";
+/**
+ * The SSRF-hardened fetch, shared — REQ-055 (#237), tasks #238 and #239.
+ *
+ * It was written for `tools-scrape` and lives here because `tools-browser` needs the *same* implementation
+ * rather than a second copy: a browser navigating to `169.254.169.254` is the same hole as a fetch doing it,
+ * and two copies of an address classifier is how one of them ends up missing the IPv6-mapped forms.
+ *
+ * **Not a replacement for `mcp/egress.ts`, which is deliberately stricter.** That one denies *every* IPv6
+ * literal unless explicitly allowed, which is right for an MCP endpoint an operator configures once and wrong
+ * for scraping the open web, where a great many real sites are v6-only. They differ because the questions
+ * differ, and merging them would mean picking one answer for both.
+ */
+export { BlockedError, DEFAULT_USER_AGENT, isPrivateAddress, isPrivateV4, isPrivateV6, nodeTransport, refuseUrl, resolvePublicly, safeFetch, systemResolve, } from "./ssrf.js";
+export type { Refusal, Resolve, SafeFetchOptions, SafeResponse, SafeTransport } from "./ssrf.js";
+export type { VendorClassifier, VendorFailure, VendorTransport, VendorTransportConfig } from "./vendor.js";
 export { DEFAULT_SEARCH_LIMIT, MAX_SNIPPET_CHARS, createFetchJson, createFetchPage, createWebSearch, htmlToText, } from "./web.js";
 export type { JsonResult, PageResult, SearchHit, SearchOutcome, SearchProvider } from "./web.js";
 export { MAX_CELL_CHARS, MAX_CSV_ROWS, MAX_SQL_ROWS, createSqlQuery, createSqlSchema, parseCsv, queryJson, } from "./data.js";
 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

@@ -10,8 +10,33 @@
  * interesting behaviour of an outbound tool — what it refuses, where it stops reading — should be provable
  * without constructing a run.
  */
-export { DEFAULT_EGRESS_POLICY, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS, createHttpClient, readBounded, } from "./http.js";
+export { DEFAULT_EGRESS_POLICY, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS, createHttpClient, readBounded, rateLimitHeadersOf, retryAfterOf, } from "./http.js";
+export { createVendorTransport } from "./vendor.js";
+/**
+ * RFC 5322 message building, shared — REQ-056 (#240), task #241.
+ *
+ * It began in `tools-google` and moved here when `tools-email` needed the same encoder. The header rules are
+ * the kind that fail *silently* — an unencoded non-ASCII subject arrives as mojibake, a header with a line
+ * break becomes two headers and the second copies the mail to somebody — so there is one implementation, and
+ * `tools-google` re-exports it rather than keeping a copy.
+ */
+export { assertHeaderSafe, boundaryFor, buildMessage, encodeHeader, HeaderInjectionError, headerOf, stripBcc, } from "./mime.js";
+/**
+ * The SSRF-hardened fetch, shared — REQ-055 (#237), tasks #238 and #239.
+ *
+ * It was written for `tools-scrape` and lives here because `tools-browser` needs the *same* implementation
+ * rather than a second copy: a browser navigating to `169.254.169.254` is the same hole as a fetch doing it,
+ * and two copies of an address classifier is how one of them ends up missing the IPv6-mapped forms.
+ *
+ * **Not a replacement for `mcp/egress.ts`, which is deliberately stricter.** That one denies *every* IPv6
+ * literal unless explicitly allowed, which is right for an MCP endpoint an operator configures once and wrong
+ * for scraping the open web, where a great many real sites are v6-only. They differ because the questions
+ * differ, and merging them would mean picking one answer for both.
+ */
+export { BlockedError, DEFAULT_USER_AGENT, isPrivateAddress, isPrivateV4, isPrivateV6, nodeTransport, refuseUrl, resolvePublicly, safeFetch, systemResolve, } from "./ssrf.js";
 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/mime.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ */
+/** A header value, RFC 2047 encoded when it needs to be — and left alone when it does not. */
+export declare const encodeHeader: (value: string) => string;
+export declare 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 declare const assertHeaderSafe: (field: string, value: string) => void;
+export type Attachment = {
+    readonly filename: string;
+    readonly contentType: string;
+    /** Base64. The caller encodes, because the bytes may never have been a string. */
+    readonly contentBase64: string;
+};
+export type OutgoingMessage = {
+    readonly to: readonly string[];
+    readonly subject: string;
+    readonly cc?: readonly string[];
+    readonly bcc?: readonly string[];
+    readonly from?: string;
+    readonly replyTo?: string;
+    /** Plain text. At least one of `text` and `html` is required. */
+    readonly text?: string;
+    readonly html?: string;
+    /**
+     * The single-body form, kept because `tools-google` was written against it.
+     *
+     * Equivalent to `text`. Both exist rather than one being renamed, so moving this module did not change the
+     * bytes any existing caller produces — which is the property that made the move safe to make.
+     */
+    readonly body?: string;
+    readonly attachments?: readonly Attachment[];
+    /** The `Message-ID` of the message being replied to. Both threading headers derive from it. */
+    readonly inReplyTo?: string;
+    /** The original's `References`, so a long thread keeps its whole chain rather than just the last hop. */
+    readonly references?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+};
+/**
+ * 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 declare const boundaryFor: (parts: readonly string[]) => string;
+/**
+ * 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 declare const buildMessage: (message: OutgoingMessage) => string;
+/**
+ * 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 declare const stripBcc: (raw: string) => string;
+/** The value of a header in a composed message, for tests and for reading a provider's echo. */
+export declare const headerOf: (raw: string, name: string) => string | undefined;
+//# sourceMappingURL=mime.d.ts.map