@retinue/agentkit 0.2.0 → 0.3.0

package/dist/testing/pglite.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A shared PGlite instance with a fresh schema per caller.
+ *
+ * **Why.** Every test used to boot its own embedded Postgres, and boot is essentially the entire cost:
+ * measured on this machine, `new PGlite()` plus a first query is **432ms warm**, while running all
+ * eleven migrations is **20ms** — and creating a second schema and migrating into it inside an
+ * already-booted instance is also **20ms**. Boot dominates by more than twenty to one.
+ *
+ * The conformance entrypoints call their store factory once per test case, so between them they were
+ * booting roughly 250 embedded databases per run. That is the largest single cost in CI, and it grew
+ * with every port added — the `build` job roughly tripled over #98–#111.
+ *
+ * **Isolation is by schema, not by instance.** Each caller gets `CREATE SCHEMA` and an executor that
+ * sets `search_path` on every query, because the connection is shared and another caller's schema may
+ * be current by the time a query runs. Two in-process round trips instead of one is nothing next to a
+ * 432ms boot.
+ *
+ * **What this does not isolate**, and the reason some test files deliberately keep their own instance:
+ * connection-level state. Roles (`CREATE ROLE app_user`), `SET ROLE`, and session GUCs are properties
+ * of the connection, not the schema — so a file that creates a role per test would collide on the
+ * second one. The row-level-security tests are exactly that shape and are left alone on purpose.
+ *
+ * Also note: `information_schema` queries must filter on `table_schema = current_schema()` here. With
+ * one schema per instance an unqualified `WHERE table_name = 'runs'` matched one row; with many schemas
+ * in one instance it matches one per schema.
+ */
+import { PGlite } from "@electric-sql/pglite";
+import type { SqlExecutor } from "../adapters/postgres/sql.js";
+/**
+ * An executor pinned to `schema`.
+ *
+ * `search_path` is set per query rather than once, because the connection is shared: between two
+ * queries from this executor, another caller's executor may have pointed the path at its own schema.
+ * Setting it once at creation would make every test's isolation depend on execution order.
+ *
+ * `public` is deliberately **absent** from the path. With it present, `CREATE TABLE IF NOT EXISTS`
+ * would see a table of the same name in `public` and skip creating it here — so a stray table in
+ * `public` would silently make every later schema share it.
+ */
+export declare const schemaExecutor: (db: PGlite, schema: string) => SqlExecutor;
+export type PgliteSchema = {
+    readonly sql: SqlExecutor;
+    readonly db: PGlite;
+    readonly schema: string;
+};
+/** A migrated, isolated schema on the shared instance. Lazily boots the instance on first use. */
+export declare const freshPgliteSchema: () => Promise<PgliteSchema>;
+/**
+ * A migrated schema, created lazily on first query so a caller can build stores synchronously.
+ *
+ * The conformance harnesses call their factory inside each test and expect a usable executor back
+ * immediately, so the work has to be deferred to the first query rather than done up front.
+ */
+export declare const lazyPgliteSchema: () => SqlExecutor;
+//# sourceMappingURL=pglite.d.ts.map

package/dist/testing/pglite.js

@@ -0,0 +1,78 @@
+/**
+ * A shared PGlite instance with a fresh schema per caller.
+ *
+ * **Why.** Every test used to boot its own embedded Postgres, and boot is essentially the entire cost:
+ * measured on this machine, `new PGlite()` plus a first query is **432ms warm**, while running all
+ * eleven migrations is **20ms** — and creating a second schema and migrating into it inside an
+ * already-booted instance is also **20ms**. Boot dominates by more than twenty to one.
+ *
+ * The conformance entrypoints call their store factory once per test case, so between them they were
+ * booting roughly 250 embedded databases per run. That is the largest single cost in CI, and it grew
+ * with every port added — the `build` job roughly tripled over #98–#111.
+ *
+ * **Isolation is by schema, not by instance.** Each caller gets `CREATE SCHEMA` and an executor that
+ * sets `search_path` on every query, because the connection is shared and another caller's schema may
+ * be current by the time a query runs. Two in-process round trips instead of one is nothing next to a
+ * 432ms boot.
+ *
+ * **What this does not isolate**, and the reason some test files deliberately keep their own instance:
+ * connection-level state. Roles (`CREATE ROLE app_user`), `SET ROLE`, and session GUCs are properties
+ * of the connection, not the schema — so a file that creates a role per test would collide on the
+ * second one. The row-level-security tests are exactly that shape and are left alone on purpose.
+ *
+ * Also note: `information_schema` queries must filter on `table_schema = current_schema()` here. With
+ * one schema per instance an unqualified `WHERE table_name = 'runs'` matched one row; with many schemas
+ * in one instance it matches one per schema.
+ */
+import { PGlite } from "@electric-sql/pglite";
+import { migrate } from "../adapters/postgres/migrations.js";
+/**
+ * One instance per module, which under vitest means one per test file — files run in separate workers,
+ * so this is not shared across them.
+ */
+let shared = null;
+let schemas = 0;
+const instance = () => (shared ??= new PGlite());
+/**
+ * An executor pinned to `schema`.
+ *
+ * `search_path` is set per query rather than once, because the connection is shared: between two
+ * queries from this executor, another caller's executor may have pointed the path at its own schema.
+ * Setting it once at creation would make every test's isolation depend on execution order.
+ *
+ * `public` is deliberately **absent** from the path. With it present, `CREATE TABLE IF NOT EXISTS`
+ * would see a table of the same name in `public` and skip creating it here — so a stray table in
+ * `public` would silently make every later schema share it.
+ */
+export const schemaExecutor = (db, schema) => ({
+    async query(text, params) {
+        await db.exec(`SET search_path TO ${schema}`);
+        const result = await db.query(text, params ? [...params] : undefined);
+        return result.rows;
+    },
+});
+/** A migrated, isolated schema on the shared instance. Lazily boots the instance on first use. */
+export const freshPgliteSchema = async () => {
+    const db = instance();
+    const schema = `s${(schemas += 1)}`;
+    await db.exec(`CREATE SCHEMA ${schema}`);
+    const sql = schemaExecutor(db, schema);
+    await migrate(sql);
+    return { sql, db, schema };
+};
+/**
+ * A migrated schema, created lazily on first query so a caller can build stores synchronously.
+ *
+ * The conformance harnesses call their factory inside each test and expect a usable executor back
+ * immediately, so the work has to be deferred to the first query rather than done up front.
+ */
+export const lazyPgliteSchema = () => {
+    let ready = null;
+    const init = () => (ready ??= freshPgliteSchema().then((created) => created.sql));
+    return {
+        async query(text, params) {
+            return (await init()).query(text, params);
+        },
+    };
+};
+//# sourceMappingURL=pglite.js.map

package/dist/testing/stub-model.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A scripted model, for testing an agent without calling a provider — task #253 AC-4.
+ *
+ * Testing an agent currently means writing a `streamTurn` by hand, and every consumer writes the same one badly:
+ * a single `text-delta` and a `finish`, which exercises none of the paths that actually break. The interesting
+ * behaviour of this platform — retry, approval gates, tool errors, structured output, the catalogue budget — all
+ * live in what the model does *across steps*, and a one-chunk fake cannot express any of it.
+ *
+ * ## Scripted per turn, not per call
+ *
+ * A script is a list of **turns**, and each call consumes the next one. That is what lets a test say "the model
+ * calls the tool, sees the result, then answers" — three chunks in one turn — separately from "the first turn
+ * fails and the second succeeds", which is two turns and is how a retry test is written.
+ *
+ * Running past the end of the script is an **error**, not a silent empty turn. A test whose agent took one more
+ * turn than the author expected should fail loudly, because the alternative is an assertion passing against a
+ * turn that produced nothing.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import type { ModelTurnRequest, NeutralStreamChunk, NeutralUsage } from "../models/streaming.js";
+/** What the model does on one turn. */
+export type ScriptedTurn = 
+/** Answers with text. */
+{
+    readonly say: string;
+    readonly usage?: Partial<NeutralUsage>;
+}
+/** Calls tools, then answers — the shape almost every interesting test needs. */
+ | {
+    readonly call: readonly {
+        readonly tool: string;
+        readonly input?: unknown;
+        readonly id?: string;
+    }[];
+    readonly then?: string;
+    readonly usage?: Partial<NeutralUsage>;
+}
+/**
+ * Fails, as a provider would.
+ *
+ * `retryable` defaults to **true**, because the case worth testing is the retry path — a non-retryable failure
+ * is just a thrown error and needs no scripting to produce.
+ */
+ | {
+    readonly fail: string;
+    readonly code?: AgentPlatformError["code"];
+    readonly retryable?: boolean;
+};
+export type StubModel = {
+    /** Pass as `DefaultEngineDeps.streamTurn`. */
+    readonly streamTurn: (request: ModelTurnRequest) => AsyncIterable<NeutralStreamChunk>;
+    /** Every request the engine made, in order — so a test can assert what the model was *given*. */
+    readonly requests: readonly ModelTurnRequest[];
+    /** Turns consumed so far. */
+    readonly turns: () => number;
+};
+export declare const createStubModel: (script: readonly ScriptedTurn[]) => StubModel;
+//# sourceMappingURL=stub-model.d.ts.map

package/dist/testing/stub-model.js

@@ -0,0 +1,71 @@
+/**
+ * A scripted model, for testing an agent without calling a provider — task #253 AC-4.
+ *
+ * Testing an agent currently means writing a `streamTurn` by hand, and every consumer writes the same one badly:
+ * a single `text-delta` and a `finish`, which exercises none of the paths that actually break. The interesting
+ * behaviour of this platform — retry, approval gates, tool errors, structured output, the catalogue budget — all
+ * live in what the model does *across steps*, and a one-chunk fake cannot express any of it.
+ *
+ * ## Scripted per turn, not per call
+ *
+ * A script is a list of **turns**, and each call consumes the next one. That is what lets a test say "the model
+ * calls the tool, sees the result, then answers" — three chunks in one turn — separately from "the first turn
+ * fails and the second succeeds", which is two turns and is how a retry test is written.
+ *
+ * Running past the end of the script is an **error**, not a silent empty turn. A test whose agent took one more
+ * turn than the author expected should fail loudly, because the alternative is an assertion passing against a
+ * turn that produced nothing.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+const usageOf = (partial) => ({
+    inputTokens: 10,
+    outputTokens: 5,
+    cachedInputTokens: 0,
+    ...partial,
+});
+export const createStubModel = (script) => {
+    const requests = [];
+    let index = 0;
+    async function* run(request) {
+        requests.push(request);
+        const turn = script[index];
+        index += 1;
+        if (turn === undefined) {
+            // Loud, not empty. An agent that took one more turn than the test expected is a finding, and an empty
+            // turn would let an assertion pass against a model that said nothing.
+            throw new AgentPlatformError({
+                code: "internal",
+                message: `the stub model's script has ${script.length} turn(s) and the agent asked for turn ${index}. ` +
+                    "Either the agent is looping, or the script is short — both are worth knowing.",
+                retryable: false,
+            });
+        }
+        if ("fail" in turn) {
+            throw new AgentPlatformError({
+                code: turn.code ?? "provider_error",
+                message: turn.fail,
+                retryable: turn.retryable ?? true,
+            });
+        }
+        if ("say" in turn) {
+            yield { type: "text-delta", id: `t${index}`, text: turn.say };
+            yield { type: "finish", usage: usageOf(turn.usage) };
+            return;
+        }
+        for (const [n, call] of turn.call.entries()) {
+            const id = call.id ?? `call-${index}-${n}`;
+            yield { type: "tool-call", toolCallId: id, toolName: call.tool, input: call.input ?? {} };
+            /**
+             * No `tool-result` is emitted here, deliberately.
+             *
+             * The engine runs the tool itself and produces the result — that is the path under test. A stub that
+             * emitted its own result would test nothing but the stub, and would hide an unwired tool entirely.
+             */
+        }
+        if (turn.then !== undefined)
+            yield { type: "text-delta", id: `t${index}`, text: turn.then };
+        yield { type: "finish", usage: usageOf(turn.usage) };
+    }
+    return { streamTurn: run, requests, turns: () => index };
+};
+//# sourceMappingURL=stub-model.js.map

package/dist/testing/supabase-storage-double.d.ts

@@ -0,0 +1,35 @@
+/**
+ * An in-process Supabase Storage, for the `FileContentStore` adapter (#129).
+ *
+ * Lives here rather than beside one test because two suites need it: `supabase-conformance.test.ts` is the
+ * single conformance entrypoint the matrix generator reads, and `supabase-storage.test.ts` holds the cases
+ * only an HTTP store has. A double copied into both would drift, and a drifting double is a suite that
+ * proves two different things while appearing to prove one.
+ *
+ * Deliberately strict about what the adapter must get right: it requires the bearer token, it refuses an
+ * upload to an existing path unless `x-upsert` says otherwise, and it 404s an unknown object rather than
+ * returning an empty body. A lenient double would let every one of those bugs through to production.
+ *
+ * It can only prove the adapter is self-consistent about the API it *believes* Supabase has. What it proves
+ * well is everything on this side of the wire — URL construction, status handling, tenant prefixing — which
+ * is where the tenant boundary lives.
+ */
+import type { FileContentStore } from "../persistence/index.js";
+export type RecordedCall = {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Record<string, string>;
+};
+export declare const STORAGE_BUCKET = "attachments";
+export declare const STORAGE_URL = "https://project.supabase.test";
+export declare const STORAGE_KEY = "service-role-key";
+/** The adapter over the double, plus the double's innards for the assertions that need them. */
+export declare const supabaseStorageDouble: () => {
+    readonly store: FileContentStore;
+    readonly objects: Map<string, {
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
+    readonly calls: RecordedCall[];
+};
+//# sourceMappingURL=supabase-storage-double.d.ts.map

package/dist/testing/supabase-storage-double.js

@@ -0,0 +1,101 @@
+/**
+ * An in-process Supabase Storage, for the `FileContentStore` adapter (#129).
+ *
+ * Lives here rather than beside one test because two suites need it: `supabase-conformance.test.ts` is the
+ * single conformance entrypoint the matrix generator reads, and `supabase-storage.test.ts` holds the cases
+ * only an HTTP store has. A double copied into both would drift, and a drifting double is a suite that
+ * proves two different things while appearing to prove one.
+ *
+ * Deliberately strict about what the adapter must get right: it requires the bearer token, it refuses an
+ * upload to an existing path unless `x-upsert` says otherwise, and it 404s an unknown object rather than
+ * returning an empty body. A lenient double would let every one of those bugs through to production.
+ *
+ * It can only prove the adapter is self-consistent about the API it *believes* Supabase has. What it proves
+ * well is everything on this side of the wire — URL construction, status handling, tenant prefixing — which
+ * is where the tenant boundary lives.
+ */
+import { createSupabaseStorageFileContentStore } from "../adapters/supabase/storage.js";
+export const STORAGE_BUCKET = "attachments";
+export const STORAGE_URL = "https://project.supabase.test";
+export const STORAGE_KEY = "service-role-key";
+const fakeStorage = () => {
+    const objects = new Map();
+    const calls = [];
+    const reply = (status, body) => ({
+        status,
+        ok: status >= 200 && status < 300,
+        async text() {
+            return typeof body === "string" ? body : new TextDecoder().decode(body);
+        },
+        async arrayBuffer() {
+            return (typeof body === "string" ? new TextEncoder().encode(body) : body)
+                .slice()
+                .buffer;
+        },
+    });
+    const fetchImpl = async (url, init) => {
+        const method = init?.method ?? "GET";
+        const headers = init?.headers ?? {};
+        calls.push({ method, url, headers });
+        if (headers["Authorization"] !== `Bearer ${STORAGE_KEY}`)
+            return reply(401, "missing bearer token");
+        const rest = url.slice(`${STORAGE_URL}/storage/v1/`.length);
+        if (rest.startsWith(`object/list/${STORAGE_BUCKET}`) && method === "POST") {
+            const body = JSON.parse(String(init?.body ?? "{}"));
+            const matched = [...objects.entries()]
+                .filter(([path]) => path.startsWith(body.prefix))
+                .map(([path, value]) => ({
+                // The API returns names relative to the searched prefix, which is what the adapter relies on.
+                name: path.slice(body.prefix.length),
+                metadata: { size: value.bytes.byteLength },
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .slice(body.offset, body.offset + body.limit);
+            return reply(200, JSON.stringify(matched));
+        }
+        if (rest.startsWith(`object/sign/${STORAGE_BUCKET}/`) && method === "POST") {
+            const path = rest.slice(`object/sign/${STORAGE_BUCKET}/`.length);
+            if (!objects.has(path))
+                return reply(404, "Object not found");
+            const { expiresIn } = JSON.parse(String(init?.body ?? "{}"));
+            return reply(200, JSON.stringify({ signedURL: `/object/sign/${STORAGE_BUCKET}/${path}?token=t&exp=${expiresIn}` }));
+        }
+        if (rest.startsWith(`object/${STORAGE_BUCKET}/`)) {
+            const path = rest.slice(`object/${STORAGE_BUCKET}/`.length);
+            if (method === "POST") {
+                if (objects.has(path) && headers["x-upsert"] !== "true")
+                    return reply(409, "The resource already exists");
+                const body = init?.body;
+                if (!(body instanceof Uint8Array))
+                    return reply(400, "expected a byte body");
+                objects.set(path, { bytes: body, mediaType: headers["Content-Type"] ?? "application/octet-stream" });
+                return reply(200, JSON.stringify({ Key: `${STORAGE_BUCKET}/${path}` }));
+            }
+            if (method === "DELETE") {
+                if (!objects.has(path))
+                    return reply(404, "Object not found");
+                objects.delete(path);
+                return reply(200, JSON.stringify({ message: "Successfully deleted" }));
+            }
+            const stored = objects.get(path);
+            return stored === undefined ? reply(404, "Object not found") : reply(200, stored.bytes);
+        }
+        return reply(404, `unrouted ${method} ${rest}`);
+    };
+    return { fetchImpl, objects, calls };
+};
+/** The adapter over the double, plus the double's innards for the assertions that need them. */
+export const supabaseStorageDouble = () => {
+    const storage = fakeStorage();
+    return {
+        store: createSupabaseStorageFileContentStore({
+            url: STORAGE_URL,
+            serviceKey: STORAGE_KEY,
+            bucket: STORAGE_BUCKET,
+            fetch: storage.fetchImpl,
+        }),
+        objects: storage.objects,
+        calls: storage.calls,
+    };
+};
+//# sourceMappingURL=supabase-storage-double.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,8 +10,34 @@
  * 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";

package/dist/toolkit/index.js

@@ -10,7 +10,30 @@
  * 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";