@retinue/agentkit 0.2.0 → 0.3.0

package/dist/toolkit/ssrf.js

@@ -0,0 +1,349 @@
+/**
+ * SSRF, closed at the point of connection — REQ-055 (#237), task #238, AC-3.
+ *
+ * This is the substance of the package. An agent that fetches URLs a model chose is a server-side request
+ * forgery primitive unless something stops it, and the naive implementation — check the hostname, then call
+ * `fetch` — is defeated three separate ways:
+ *
+ * 1. **A private or link-local literal.** `http://169.254.169.254/latest/meta-data/iam/security-credentials/`
+ *    returns cloud credentials in plain text on EC2. `[::ffff:169.254.169.254]` is the same address wearing a
+ *    different hat, and so is `0177.0.0.1`.
+ * 2. **A public name that resolves to a private address.** `metadata.attacker.example` with an `A` record of
+ *    `169.254.169.254` passes every hostname check ever written, because the hostname is genuinely public.
+ * 3. **A redirect.** The check ran on the URL that was requested, and the response says to go somewhere else.
+ *
+ * Each needs its own defence, and each has its own test.
+ *
+ * ## Why this resolves DNS itself rather than trusting a check-then-fetch
+ *
+ * Vector 2's obvious fix — resolve the name, look at the addresses, then call `fetch` — leaves a window: the
+ * fetch resolves the name a *second* time, and a DNS record with a one-second TTL can answer differently. That
+ * is DNS rebinding, it is not theoretical, and a check that a determined caller can lose a race against is a
+ * check that reports safety it does not provide.
+ *
+ * So the resolution and the connection are the same event. `node:https` accepts a `lookup` function, called at
+ * connect time with the hostname; this module supplies one that returns **only** an address it has just
+ * validated. There is no second resolution to poison. TLS still verifies the certificate against the hostname
+ * from the URL, so pinning the address costs nothing in transport security.
+ *
+ * This is why the package uses `node:https` rather than the shared `createHttpClient`: `fetch` has no way to
+ * say "connect to this address". The trade is written down in `check:transport`'s exemption list.
+ *
+ * ## What is deliberately *not* claimed
+ *
+ * This closes access to private network space. It does not make fetching arbitrary URLs safe in general — the
+ * content that comes back is still untrusted, which is a separate problem handled by the untrusted-content
+ * fence rather than here.
+ */
+import { lookup as dnsLookup } from "node:dns";
+import { request as httpsRequest } from "node:https";
+import { request as httpRequest } from "node:http";
+/**
+ * How this identifies itself, honestly.
+ *
+ * A real name and a URL that explains what it is, because the alternative — impersonating a browser — is the
+ * bot-detection evasion this package declines to do, and because a site that wants to refuse a crawler should
+ * be able to. Several sites answer a *missing* User-Agent with a 429 that is not a rate limit, so sending
+ * nothing is not an option either.
+ */
+export const DEFAULT_USER_AGENT = "RetinueBot/1.0 (+https://retinue.dev/integrations/scrape)";
+const v4Parts = (host) => {
+    const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (match === null)
+        return null;
+    const parts = match.slice(1, 5).map(Number);
+    return parts.every((part) => part >= 0 && part <= 255) ? parts : null;
+};
+/**
+ * Whether an IPv4 address is somewhere a fetch must not go.
+ *
+ * Broader than "the RFC 1918 ranges", because the ranges that matter are the ones that reach something. In
+ * particular `100.64/10` (carrier-grade NAT) is where several hosting providers put internal services, and
+ * `0.0.0.0/8` is a well-known way of writing "this host" that a naive `127.` check misses entirely.
+ */
+export const isPrivateV4 = (host) => {
+    const parts = v4Parts(host);
+    if (parts === null)
+        return false;
+    const [a = 0, b = 0] = parts;
+    if (a === 0)
+        return true; // "this network" — 0.0.0.0 reaches localhost on Linux
+    if (a === 10 || a === 127)
+        return true; // private, loopback
+    if (a === 169 && b === 254)
+        return true; // link-local, including cloud metadata
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 192 && b === 0)
+        return true; // IETF protocol assignments, incl. 192.0.0.192
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // carrier-grade NAT
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // benchmarking
+    if (a >= 224)
+        return true; // multicast and reserved — 224/4 and 240/4
+    return false;
+};
+/**
+ * Whether an IPv6 address is somewhere a fetch must not go.
+ *
+ * The mapped and embedded forms are the interesting part: `::ffff:169.254.169.254` and `::169.254.169.254` are
+ * both the metadata address, and `2002:a9fe:a9fe::` is it again inside a 6to4 prefix. A v6 check that does not
+ * look inside those is a v4 check with extra steps.
+ */
+export const isPrivateV6 = (host) => {
+    const address = host.toLowerCase().replace(/^\[|\]$/g, "").split("%")[0] ?? "";
+    if (address === "" || address === "::" || address === "::1")
+        return true;
+    // An embedded IPv4 address — `::ffff:1.2.3.4`, `::1.2.3.4` — is judged as the IPv4 address it contains.
+    const embedded = /:((?:\d{1,3}\.){3}\d{1,3})$/.exec(address);
+    if (embedded?.[1] !== undefined)
+        return isPrivateV4(embedded[1]);
+    // The same thing written in hex: `::ffff:a9fe:a9fe`.
+    const hexMapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(address);
+    if (hexMapped !== null) {
+        const high = Number.parseInt(hexMapped[1] ?? "0", 16);
+        const low = Number.parseInt(hexMapped[2] ?? "0", 16);
+        return isPrivateV4(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
+    }
+    // 6to4: `2002:<v4 in hex>::/48` routes to the embedded IPv4 address.
+    const sixToFour = /^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4}):/.exec(address);
+    if (sixToFour !== null) {
+        const high = Number.parseInt(sixToFour[1] ?? "0", 16);
+        const low = Number.parseInt(sixToFour[2] ?? "0", 16);
+        if (isPrivateV4(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`))
+            return true;
+    }
+    const head = address.split(":")[0] ?? "";
+    const leading = Number.parseInt(head === "" ? "0" : head, 16);
+    if ((leading & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique local
+    if ((leading & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    if ((leading & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
+    return false;
+};
+export const isPrivateAddress = (address) => address.includes(":") ? isPrivateV6(address) : isPrivateV4(address);
+/** Hostnames that name something internal by convention rather than by address. */
+const INTERNAL_NAMES = new Set([
+    "localhost",
+    "ip6-localhost",
+    "ip6-loopback",
+    // The metadata service on GCP, Azure and Alibaba respectively. Each resolves to a link-local address, so the
+    // address check catches them too — named here so a refusal says *what* was refused.
+    "metadata.google.internal",
+    "metadata.azure.com",
+    "metadata",
+]);
+/**
+ * Refuses a URL on its face, before any resolution.
+ *
+ * Scheme and shape only. A hostname that merely *looks* fine still has to survive resolution, which is the
+ * next function — this one exists so an obviously bad URL costs no DNS query and gives a specific message.
+ */
+export const refuseUrl = (url) => {
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        return `${url.protocol}// is not a scheme this can fetch. Only http and https are supported — a file:, ftp: or data: URL is refused.`;
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.+$/, "");
+    if (host === "")
+        return "That URL has no host.";
+    if (INTERNAL_NAMES.has(host) || host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".localhost")) {
+        return `${host} names something on the internal network, which this tool does not fetch.`;
+    }
+    /**
+     * An address literal is judged immediately, and a *hostname* is not judged here at all.
+     *
+     * A hostname cannot be classified without resolving it — that is vector 2 — so the temptation is to apply a
+     * heuristic. There isn't a sound one, and a heuristic here would be the check that makes the real check feel
+     * redundant.
+     */
+    if (/^[\d.]+$/.test(host) || host.includes(":")) {
+        if (isPrivateAddress(host)) {
+            return `${host} is a private, loopback or link-local address, which this tool does not fetch.`;
+        }
+        // A dotted-quad that is not four valid octets is either malformed or an obfuscated form like `0177.0.0.1`
+        // or `2130706433`, both of which resolve to loopback in some stacks. Neither is a URL anyone means.
+        if (!host.includes(":") && v4Parts(host) === null) {
+            return `${host} is not a valid IPv4 address. Octal, hexadecimal and integer forms of an address are refused.`;
+        }
+    }
+    return null;
+};
+export const systemResolve = (hostname) => new Promise((resolve, reject) => {
+    dnsLookup(hostname, { all: true, verbatim: true }, (error, addresses) => {
+        if (error)
+            reject(error);
+        else
+            resolve(addresses.map((entry) => entry.address));
+    });
+});
+export class BlockedError extends Error {
+}
+/**
+ * Resolves a host and refuses it if **any** address is private — then returns the addresses to connect to.
+ *
+ * *Any*, not *all*. A name with two `A` records, one public and one link-local, is a rebinding attack with the
+ * work done up front: connecting to whichever the resolver happened to order first is a coin flip, and a check
+ * that passes on a coin flip has not checked anything.
+ */
+export const resolvePublicly = async (hostname, resolve) => {
+    let addresses;
+    try {
+        addresses = await resolve(hostname);
+    }
+    catch {
+        throw new BlockedError(`${hostname} could not be resolved.`);
+    }
+    if (addresses.length === 0)
+        throw new BlockedError(`${hostname} resolved to no addresses.`);
+    const blocked = addresses.filter((address) => isPrivateAddress(address));
+    if (blocked.length > 0) {
+        throw new BlockedError(`${hostname} resolves to ${blocked.join(", ")}, which is a private, loopback or link-local address. ` +
+            "A public hostname pointing at internal network space is how a fetch tool is turned into a way to read " +
+            "cloud metadata, so this is refused rather than followed.");
+    }
+    return addresses;
+};
+const DEFAULT_MAX_BYTES = 2_000_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_REDIRECTS = 5;
+/**
+ * The real transport: connects to a validated address with `lookup` pinned.
+ *
+ * The `lookup` callback is what makes this sound. Node calls it at connect time instead of resolving the name,
+ * so the address that was checked is the address that is used — there is no second resolution between the
+ * check and the socket. The hostname still goes out in SNI and in the `Host` header, so the certificate is
+ * verified against the name the caller asked for, not against the IP.
+ */
+export const nodeTransport = ({ url, addresses, headers, timeoutMs, maxBytes }) => new Promise((resolve, reject) => {
+    const pinned = addresses[0];
+    const family = pinned.includes(":") ? 6 : 4;
+    const options = {
+        method: "GET",
+        headers,
+        // Pinned. Called instead of a DNS lookup, with the address already validated above.
+        lookup: (_hostname, _options, callback) => {
+            callback(null, pinned, family);
+        },
+    };
+    const send = url.protocol === "https:" ? httpsRequest : httpRequest;
+    const request = send(url, options, (response) => {
+        const chunks = [];
+        let size = 0;
+        let truncated = false;
+        response.on("data", (chunk) => {
+            if (truncated)
+                return;
+            size += chunk.length;
+            if (size > maxBytes) {
+                // Bounded *while streaming*, not after: a byte cap enforced on a body already in memory is not a cap.
+                chunks.push(chunk.subarray(0, chunk.length - (size - maxBytes)));
+                truncated = true;
+                response.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        const finish = () => {
+            const headerRecord = {};
+            for (const [name, value] of Object.entries(response.headers)) {
+                if (typeof value === "string")
+                    headerRecord[name.toLowerCase()] = value;
+                else if (Array.isArray(value))
+                    headerRecord[name.toLowerCase()] = value.join(", ");
+            }
+            resolve({
+                status: response.statusCode ?? 0,
+                headers: headerRecord,
+                body: Buffer.concat(chunks).toString("utf8"),
+                truncated,
+            });
+        };
+        response.on("end", finish);
+        response.on("close", () => {
+            if (truncated)
+                finish();
+        });
+        response.on("error", reject);
+    });
+    request.setTimeout(timeoutMs, () => {
+        request.destroy(new Error(`No response within ${timeoutMs}ms.`));
+    });
+    request.on("error", reject);
+    request.end();
+});
+/**
+ * Fetches a URL with every vector closed, following redirects **by re-running the whole check on each hop**.
+ *
+ * The shared `createHttpClient` refuses redirects outright, which is the right answer for a vendor API and the
+ * wrong one here: a great many real pages are one redirect away from their canonical URL, and a scraper that
+ * cannot follow `http → https` or `example.com → www.example.com` is a scraper that fails on ordinary input.
+ *
+ * So redirects are followed, and the price is that each hop is a fresh, untrusted URL. It gets `refuseUrl` and
+ * `resolvePublicly` exactly as the first one did. A chain that starts public and ends at `169.254.169.254` is
+ * refused at the hop that turns private, which is the only place it can be caught.
+ */
+export const safeFetch = async (target, options = {}) => {
+    const resolve = options.resolve ?? systemResolve;
+    const transport = options.transport ?? nodeTransport;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const chain = [];
+    let current;
+    try {
+        current = new URL(target);
+    }
+    catch {
+        throw new BlockedError(`"${target}" is not a URL.`);
+    }
+    for (let hop = 0; hop <= maxRedirects; hop += 1) {
+        const refusal = refuseUrl(current);
+        if (refusal !== null)
+            throw new BlockedError(refusal);
+        const addresses = await resolvePublicly(current.hostname, resolve);
+        chain.push(current.toString());
+        const response = await transport({
+            url: current,
+            addresses,
+            headers: {
+                // A real, honest identifier. Several sites answer a missing User-Agent with a 429 that is not a rate
+                // limit, and misrepresenting the client is the bot-detection evasion this package declines to do.
+                "user-agent": options.headers?.["user-agent"] ?? DEFAULT_USER_AGENT,
+                accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8",
+                ...options.headers,
+            },
+            timeoutMs,
+            maxBytes,
+        });
+        const location = response.headers.location;
+        if (response.status >= 300 && response.status < 400 && location !== undefined && location !== "") {
+            if (hop === maxRedirects) {
+                throw new BlockedError(`That URL redirected more than ${maxRedirects} times, so the chain was abandoned.`);
+            }
+            let next;
+            try {
+                next = new URL(location, current);
+            }
+            catch {
+                throw new BlockedError(`That URL redirected to "${location}", which is not a URL.`);
+            }
+            current = next;
+            continue;
+        }
+        return {
+            url: current.toString(),
+            status: response.status,
+            headers: response.headers,
+            body: response.body,
+            truncated: response.truncated,
+            chain,
+        };
+    }
+    throw new BlockedError(`That URL redirected more than ${maxRedirects} times, so the chain was abandoned.`);
+};
+//# sourceMappingURL=ssrf.js.map

package/dist/toolkit/vendor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The transport every sibling toolkit needs, once — REQ-052 (#224), task #225.
+ *
+ * `tools-github` grew one of these in #223 and it turned out to be four-fifths vendor-neutral: resolve the
+ * credential *per call*, pin the auth header to one validated host, parse JSON with an empty body tolerated,
+ * and map a failure onto the platform's closed error union. Only the last part is really vendor-specific, and
+ * only in its wording.
+ *
+ * Writing it twice more for Jira and Confluence — with nineteen toolkits after them — would mean copying four
+ * bugs along with it. #223 found two of them the hard way:
+ *
+ * - `JSON.parse("")` on a `204`. Two endpoints returned empty bodies on success and both tools failed outright
+ *   while reporting a parse error about a correct response.
+ * - A plain-text body handled by catching the parse failure, which discarded the text and returned a
+ *   placeholder. The tool typechecked and was entirely non-functional.
+ *
+ * Both are fixed here, so a toolkit gets them right by not writing them.
+ *
+ * **What stays with the vendor**: the failure vocabulary (`classify`), the base URL, and the fixed headers.
+ * A vendor that answers `200` with an error envelope — Slack's `ok: false`, GraphQL's `errors` — reads that
+ * envelope in its own module, because only it knows the shape.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import { type PlatformError } from "../core/errors.js";
+import type { CredentialRef, CredentialResolver } from "../tools/credentials.js";
+import { type HttpOutcome } from "./http.js";
+/** What a vendor's classifier is handed: the failed outcome, already narrowed. */
+export type VendorFailure = Extract<HttpOutcome, {
+    ok: false;
+}>;
+/**
+ * How this vendor names its failures.
+ *
+ * Returning `undefined` accepts the default, which is deliberately conservative: a transport failure is
+ * `provider_unavailable` and retryable, `401`/`403` is `unauthorized` and not, and everything else is
+ * `provider_error` and not. A vendor overrides where its own signalling differs — GitHub reports a rate limit
+ * as `403` with a header, which no default could guess.
+ */
+/**
+ * `PlatformError["code"]`, not a hand-picked subset.
+ *
+ * The first version listed four codes — the ones the default classification uses — and Jira needed a fifth the
+ * same afternoon: `409`/`412` is a `conflict`, which is a real platform code and was not on the list. Naming a
+ * subset means guessing which codes vendors will need, and the platform union is already the right constraint.
+ */
+/**
+ * `retryAfterMs` is part of the return type, and its absence was a live bug.
+ *
+ * The default 429 arm below has always *set* it — inside an object typed as `Pick<…, "code"|"message"|"retryable">`,
+ * where a spread makes an excess property legal and unreadable. So the field was written, typechecked, and could
+ * not be read by the one line that needed it. See the propagation note in `request`.
+ */
+export type VendorClassifier = (failure: VendorFailure) => Pick<PlatformError, "code" | "message" | "retryable" | "retryAfterMs"> | undefined;
+export type VendorTransportConfig = {
+    /** Resolved per call, by the host. A toolkit must never read the environment. */
+    readonly credentialRef: CredentialRef;
+    readonly resolver: CredentialResolver;
+    /** No trailing slash needed; one is stripped. */
+    readonly baseUrl: string;
+    /** Sent on every request, alongside the resolved credential header. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** The vendor's own name for what went wrong. */
+    readonly classify?: VendorClassifier;
+    /** Injected so tests need no network. */
+    readonly fetchImpl?: typeof fetch;
+    /** Named in every error message, so a failure says which integration produced it. */
+    readonly vendor: string;
+};
+export type VendorTransport = {
+    /** Parsed JSON, or `undefined` when the vendor answered with no body — a `204` is a success. */
+    readonly json: (context: ExecutionContext, path: string, init?: {
+        readonly method?: string;
+        readonly body?: unknown;
+    }) => Promise<unknown>;
+    /** The body verbatim, for the endpoints that do not answer in JSON. */
+    readonly text: (context: ExecutionContext, path: string, init?: {
+        readonly method?: string;
+        readonly body?: unknown;
+        /**
+         * Sent **as-is**, with `contentType`, instead of being JSON-encoded.
+         *
+         * For a media endpoint: Drive's `uploadType=media` wants the file's bytes, and `JSON.stringify` on a
+         * string produces a quoted string — a file whose contents are a JSON literal, uploaded successfully.
+         * Nothing errors, which is why this is a parameter rather than a caller's `JSON.parse` dance.
+         */
+        readonly rawBody?: string;
+        readonly contentType?: string;
+    }) => Promise<string>;
+};
+export declare const createVendorTransport: (config: VendorTransportConfig) => VendorTransport;
+//# sourceMappingURL=vendor.d.ts.map

package/dist/toolkit/vendor.js

@@ -0,0 +1,153 @@
+/**
+ * The transport every sibling toolkit needs, once — REQ-052 (#224), task #225.
+ *
+ * `tools-github` grew one of these in #223 and it turned out to be four-fifths vendor-neutral: resolve the
+ * credential *per call*, pin the auth header to one validated host, parse JSON with an empty body tolerated,
+ * and map a failure onto the platform's closed error union. Only the last part is really vendor-specific, and
+ * only in its wording.
+ *
+ * Writing it twice more for Jira and Confluence — with nineteen toolkits after them — would mean copying four
+ * bugs along with it. #223 found two of them the hard way:
+ *
+ * - `JSON.parse("")` on a `204`. Two endpoints returned empty bodies on success and both tools failed outright
+ *   while reporting a parse error about a correct response.
+ * - A plain-text body handled by catching the parse failure, which discarded the text and returned a
+ *   placeholder. The tool typechecked and was entirely non-functional.
+ *
+ * Both are fixed here, so a toolkit gets them right by not writing them.
+ *
+ * **What stays with the vendor**: the failure vocabulary (`classify`), the base URL, and the fixed headers.
+ * A vendor that answers `200` with an error envelope — Slack's `ok: false`, GraphQL's `errors` — reads that
+ * envelope in its own module, because only it knows the shape.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { credentialHeader } from "../tools/credentials.js";
+import { createHttpClient } from "./http.js";
+/**
+ * The default classification, and why each arm is what it is.
+ *
+ * A model reads these to decide whether trying again is sensible, so the distinction that matters is
+ * *retryable*, not how precisely the words describe the HTTP status. `unauthorized` on a `403` is the important
+ * one: told "forbidden", a model retries with different arguments, which is never the fix for a missing scope.
+ */
+const defaultClassification = (failure, vendor) => {
+    const transport = failure.kind === "timeout" || failure.kind === "unreachable";
+    if (transport) {
+        return {
+            code: "provider_unavailable",
+            message: `${vendor} request failed (${failure.kind}): ${failure.reason}`,
+            retryable: true,
+        };
+    }
+    if (failure.status === 429) {
+        /**
+         * `Retry-After` is honoured when the vendor sent one — the default backoff is a guess, and a vendor that
+         * told you the number has removed the need to guess. Meta, X and Reddit all send it.
+         */
+        return {
+            code: "rate_limited",
+            message: `${vendor} rate limit reached: ${failure.reason}` +
+                (failure.retryAfterMs === undefined ? "" : ` Retry after ${Math.ceil(failure.retryAfterMs / 1000)}s.`),
+            retryable: true,
+            ...(failure.retryAfterMs === undefined ? {} : { retryAfterMs: failure.retryAfterMs }),
+        };
+    }
+    if (failure.status === 401 || failure.status === 403) {
+        return {
+            code: "unauthorized",
+            message: `${vendor} refused the credential (${failure.status}): ${failure.reason}. The credential may lack the permission this tool needs.`,
+            retryable: false,
+        };
+    }
+    return { code: "provider_error", message: `${vendor} request failed (${failure.kind}): ${failure.reason}`, retryable: false };
+};
+export const createVendorTransport = (config) => {
+    const base = config.baseUrl.replace(/\/$/, "");
+    const host = new URL(base).host;
+    /**
+     * One request, with the credential resolved now rather than at construction.
+     *
+     * Per call so a rotated token takes effect without a restart — a credential read once at startup is one that
+     * survives its own rotation, and the failure looks like the vendor rejecting a token that "has not changed".
+     *
+     * The header goes in through `headersFor`, which the runtime calls with the **validated** hostname only: a
+     * credential issued for one host cannot be sent to another by asking for a URL that merely mentions it.
+     */
+    const request = async (context, path, init = {}) => {
+        const credential = await config.resolver.resolve({ ref: config.credentialRef, context });
+        // One helper, so twenty toolkits do not each write their own base64 and get the padding wrong — #260.
+        const [headerName, headerValue] = credentialHeader(credential);
+        const client = createHttpClient({
+            ...(config.fetchImpl === undefined ? {} : { fetchImpl: config.fetchImpl }),
+            headersFor: (requested) => requested === host
+                ? {
+                    [headerName.toLowerCase()]: headerValue,
+                    ...(config.headers ?? {}),
+                    // Overrides the vendor's default, which is JSON for every other call this transport makes.
+                    ...(init.contentType === undefined ? {} : { "content-type": init.contentType }),
+                }
+                : undefined,
+        });
+        const outcome = await client.request({
+            url: `${base}${path}`,
+            ...(init.method === undefined ? {} : { method: init.method }),
+            ...(init.rawBody !== undefined
+                ? { body: init.rawBody }
+                : init.body === undefined
+                    ? {}
+                    : { body: JSON.stringify(init.body) }),
+            // Parsed here and never shown to the model verbatim, so the untrusted-content envelope would only corrupt
+            // the JSON. Anything rendered as prose keeps the default fence.
+            fence: false,
+        });
+        if (outcome.ok)
+            return outcome.body;
+        const failure = outcome;
+        const described = config.classify?.(failure) ?? defaultClassification(failure, config.vendor);
+        /**
+         * `Retry-After`, carried through — and it was being dropped.
+         *
+         * `HttpFailure` parses the header and `PlatformError` has a field for it, and this transport joined them by
+         * building an error that mentioned neither. Every toolkit on it therefore ignored a vendor that had said
+         * *exactly* how long to wait, and fell back to a generic backoff — which is both slower than necessary and,
+         * against a service that counts requests during the window, a way to stay throttled.
+         *
+         * A classifier may override it; otherwise the server's own number wins over any default, because the server
+         * is the only party that knows.
+         */
+        const retryAfterMs = described.retryAfterMs ?? failure.retryAfterMs;
+        /**
+         * `AgentPlatformError`, not a decorated `Error`.
+         *
+         * `toPlatformError` maps anything else to `{ code: "internal", retryable: false }` — so a rate limit thrown
+         * as `Object.assign(new Error(…), { retryable: true })` arrives at the model as permanently broken. The
+         * extra properties simply vanish and nothing warns you.
+         */
+        throw new AgentPlatformError(retryAfterMs === undefined ? described : { ...described, retryAfterMs });
+    };
+    return {
+        async json(context, path, init) {
+            const body = await request(context, path, init);
+            // **An empty body is a success.** A `204` from a delete, or a `201` from a fire-and-forget POST, has
+            // nothing to parse — and `JSON.parse("")` throws, which reported two correct responses as parse failures.
+            if (body.trim() === "")
+                return undefined;
+            try {
+                return JSON.parse(body);
+            }
+            catch {
+                throw new AgentPlatformError({
+                    code: "provider_error",
+                    message: `${config.vendor} returned a body that is not JSON`,
+                    retryable: false,
+                });
+            }
+        },
+        text(context, path, init) {
+            // Not `json` with the parse failure caught: that discards the body, which is how a log-reading tool
+            // shipped returning a placeholder on every success.
+            return request(context, path, init ?? {});
+        },
+    };
+};
+//# sourceMappingURL=vendor.js.map