@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/model-pricing.js

@@ -0,0 +1,244 @@
+import { GENERATED_MODEL_DATA } from "./model-data.generated.js";
+// Official USD prices checked 2026-09-10:
+// https://api-docs.deepseek.com/quick_start/pricing
+// Exact transition times: https://api-docs.deepseek.com/news/news260910
+const DEEPSEEK_PEAK_WINDOWS_UTC = [
+    { startMinute: 60, endMinute: 240 },
+    { startMinute: 360, endMinute: 600 },
+];
+const DEEPSEEK_PEAK_WEEKDAYS_UTC = [1, 2, 3, 4, 5];
+const DEEPSEEK_V41_FLASH_TARIFF = {
+    inputCacheHitPerMillion: 0.006,
+    inputCacheMissPerMillion: 0.3,
+    outputPerMillion: 1.2,
+    peakWindowsUtc: DEEPSEEK_PEAK_WINDOWS_UTC,
+    peakWeekdaysUtc: DEEPSEEK_PEAK_WEEKDAYS_UTC,
+    offPeak: {
+        inputCacheHitPerMillion: 0.003,
+        inputCacheMissPerMillion: 0.15,
+        outputPerMillion: 0.6,
+    },
+};
+/**
+ * Hand-maintained corrections layered over the generated models.dev snapshot.
+ * An entry here shadows the generated entry with the same (providerId, modelId).
+ * Only exceptions belong here — facts the upstream catalog cannot carry
+ * (promo expiry dates, non-USD billing) or gets wrong. Everything else comes
+ * from src/model-data.generated.ts via `npm run refresh-models`.
+ */
+export const MODEL_PRICING_OVERRIDES = [
+    ...[
+        "muse-spark-1.3-contributor-free",
+        "muse-spark-1.2-contributor-free",
+        "space-bunny-free",
+    ].map((modelId) => ({
+        providerId: "opencode-zen",
+        modelId,
+        currency: "USD",
+        inputCacheHitPerMillion: 0,
+        inputCacheMissPerMillion: 0,
+        outputPerMillion: 0,
+    })),
+    {
+        providerId: "opencode-zen",
+        modelId: "muse-spark-1.2",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.15,
+        inputCacheMissPerMillion: 1.25,
+        outputPerMillion: 4.25,
+    },
+    // Gemini 3.7/3.8 Flash launch pricing. Google's standard paid-tier prices
+    // double on 2027-01-01; keep both rates so historical and future /stats are
+    // priced against the tariff that was actually active.
+    ...["gemini-3.7-flash", "gemini-3.8-flash"].map((modelId) => ({
+        providerId: "google",
+        modelId,
+        currency: "USD",
+        inputCacheHitPerMillion: 0.075,
+        inputCacheMissPerMillion: 0.75,
+        outputPerMillion: 3.75,
+        effectiveUntil: "2027-01-01T00:00:00Z",
+        original: {
+            inputCacheHitPerMillion: 0.15,
+            inputCacheMissPerMillion: 1.5,
+            outputPerMillion: 7.5,
+        },
+    })),
+    // Gemini 4 Argon introductory pricing through 2026-11-30; standard rates from
+    // 2026-12-01. Implicit caching only (95% off input), so no cache-write rate.
+    // https://ai.google.dev/gemini-api/docs/pricing
+    {
+        providerId: "google",
+        modelId: "gemini-4-argon",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.1,
+        inputCacheMissPerMillion: 2,
+        outputPerMillion: 10,
+        effectiveUntil: "2026-12-01T00:00:00Z",
+        original: {
+            inputCacheHitPerMillion: 0.2,
+            inputCacheMissPerMillion: 4,
+            outputPerMillion: 20,
+        },
+    },
+    {
+        providerId: "deepseek",
+        modelId: "deepseek-flash",
+        currency: "USD",
+        ...DEEPSEEK_V41_FLASH_TARIFF,
+        effectiveFrom: "2026-09-10T04:00:00Z",
+    },
+    // Preserve older tariffs for historical /stats. Both legacy Flash IDs now
+    // serve V4.1 Flash; Pro switches on 2026-09-14 at 04:00 UTC. A transition
+    // must select the whole tariff, including its peak/off-peak schedule.
+    ...[
+        { modelId: "deepseek-v4-flash", kind: "flash" },
+        { modelId: "deepseek-v4-flash-vision-exp", kind: "flash" },
+        { modelId: "deepseek-v4-pro", kind: "pro" },
+    ].map(({ modelId, kind }) => {
+        const peak = kind === "pro"
+            ? { inputCacheHitPerMillion: 0.044, inputCacheMissPerMillion: 1.32, outputPerMillion: 3.96 }
+            : { inputCacheHitPerMillion: 0.014, inputCacheMissPerMillion: 0.44, outputPerMillion: 1.32 };
+        const offPeak = kind === "pro"
+            ? { inputCacheHitPerMillion: 0.022, inputCacheMissPerMillion: 0.66, outputPerMillion: 1.98 }
+            : { inputCacheHitPerMillion: 0.007, inputCacheMissPerMillion: 0.22, outputPerMillion: 0.66 };
+        const prior = kind === "pro"
+            ? { inputCacheHitPerMillion: 0.003625, inputCacheMissPerMillion: 0.435, outputPerMillion: 0.87 }
+            : { inputCacheHitPerMillion: 0.0028, inputCacheMissPerMillion: 0.14, outputPerMillion: 0.28 };
+        // The 2026-08-16 schedule was already Monday-Friday only; the earlier
+        // every-day model here was an omission, so applying the weekday rule to
+        // this tariff corrects August weekend history rather than repricing it.
+        const previous = {
+            ...peak,
+            peakWindowsUtc: DEEPSEEK_PEAK_WINDOWS_UTC,
+            peakWeekdaysUtc: DEEPSEEK_PEAK_WEEKDAYS_UTC,
+            offPeak,
+            effectiveFrom: "2026-08-16T16:00:00Z",
+            // The vision model launched after the tariff change; it has no valid
+            // pre-change usage. Stable Flash/Pro retain their former rates so /stats
+            // does not reprice old sessions using today's schedule.
+            ...(modelId === "deepseek-v4-flash-vision-exp" ? {} : { prior }),
+        };
+        return {
+            providerId: "deepseek",
+            modelId,
+            currency: "USD",
+            ...(kind === "flash" ? {
+                ...DEEPSEEK_V41_FLASH_TARIFF,
+                effectiveFrom: "2026-09-10T04:00:00Z",
+                prior: previous,
+            } : {
+                ...previous,
+                effectiveUntil: "2026-09-14T04:00:00Z",
+                original: DEEPSEEK_V41_FLASH_TARIFF,
+            }),
+        };
+    }),
+    // Official current prices, verified 2026-09-23:
+    // https://platform.claude.com/docs/en/about-claude/pricing
+    // Cache reads are 2.5% (Fable 5.1) / 5% (Opus 5.5), not the older 10%.
+    {
+        providerId: "anthropic",
+        modelId: "claude-fable-5-1",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.25,
+        inputCacheMissPerMillion: 10,
+        inputCacheWritePerMillion: 12.5,
+        outputPerMillion: 50,
+    },
+    {
+        providerId: "anthropic",
+        modelId: "claude-opus-5-5",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.2,
+        inputCacheMissPerMillion: 4,
+        inputCacheWritePerMillion: 5,
+        outputPerMillion: 20,
+    },
+    // The current official Sonnet 5 price is $2/$10 without an expiry.
+    {
+        providerId: "anthropic",
+        modelId: "claude-sonnet-5",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.2,
+        inputCacheMissPerMillion: 2,
+        inputCacheWritePerMillion: 2.5,
+        outputPerMillion: 10,
+    },
+    // The StepFun step plan bills in CNY; models.dev normalizes prices to USD.
+    {
+        providerId: "stepfun",
+        modelId: "step-3.7-flash",
+        currency: "CNY",
+        inputCacheHitPerMillion: 0.27,
+        inputCacheMissPerMillion: 1.35,
+        outputPerMillion: 8.1,
+    },
+];
+function pricingFromGenerated(entry) {
+    return {
+        providerId: entry.providerId,
+        modelId: entry.modelId,
+        currency: "USD",
+        // Without a cache discount upstream, cached input bills at the plain rate.
+        inputCacheHitPerMillion: entry.cacheReadPerMillion ?? entry.inputPerMillion,
+        inputCacheMissPerMillion: entry.inputPerMillion,
+        ...(entry.cacheWritePerMillion !== undefined
+            ? { inputCacheWritePerMillion: entry.cacheWritePerMillion }
+            : {}),
+        outputPerMillion: entry.outputPerMillion,
+    };
+}
+const overriddenKeys = new Set(MODEL_PRICING_OVERRIDES.map((item) => `${item.providerId}\0${item.modelId}`));
+export const MODEL_PRICING = [
+    ...GENERATED_MODEL_DATA
+        .filter((entry) => !overriddenKeys.has(`${entry.providerId}\0${entry.modelId}`))
+        .map(pricingFromGenerated),
+    ...MODEL_PRICING_OVERRIDES,
+];
+export function getModelPricing(providerId, modelId) {
+    return MODEL_PRICING.find((item) => item.providerId === providerId && item.modelId === modelId);
+}
+function pricingRateAt(pricing, at) {
+    if (pricing.prior && pricing.effectiveFrom && at.getTime() < Date.parse(pricing.effectiveFrom)) {
+        return pricingRateAt(pricing.prior, at);
+    }
+    if (pricing.original && pricing.effectiveUntil && at.getTime() >= Date.parse(pricing.effectiveUntil)) {
+        return pricingRateAt(pricing.original, at);
+    }
+    if (!pricing.offPeak || !pricing.peakWindowsUtc?.length)
+        return pricing;
+    const minute = at.getUTCHours() * 60 + at.getUTCMinutes();
+    const isPeakDay = !pricing.peakWeekdaysUtc || pricing.peakWeekdaysUtc.includes(at.getUTCDay());
+    const isPeak = isPeakDay && pricing.peakWindowsUtc.some((window) => minute >= window.startMinute && minute < window.endMinute);
+    return isPeak ? pricing : pricing.offPeak;
+}
+export function calculateUsageCost(providerId, modelId, usage, at = new Date()) {
+    const pricing = getModelPricing(providerId, modelId);
+    if (!pricing)
+        return undefined;
+    const rate = pricingRateAt(pricing, at);
+    const hasCacheBreakdown = typeof usage.promptCacheHitTokens === "number"
+        || typeof usage.promptCacheMissTokens === "number"
+        || typeof usage.cacheCreationTokens === "number";
+    const hit = usage.promptCacheHitTokens ?? 0;
+    const miss = hasCacheBreakdown
+        ? usage.promptCacheMissTokens ?? Math.max(0, usage.promptTokens - hit)
+        : usage.promptTokens;
+    // `miss` already contains the cache-write tokens (see mergeAnthropicUsage),
+    // so writes must be netted out before being re-priced — adding a write term
+    // on top of the untouched miss term would bill them at miss + write.
+    const write = rate.inputCacheWritePerMillion !== undefined
+        ? Math.min(usage.cacheCreationTokens ?? 0, miss)
+        : 0;
+    const missOnly = miss - write;
+    const cost = (hit / 1_000_000) * rate.inputCacheHitPerMillion
+        + (write / 1_000_000) * (rate.inputCacheWritePerMillion ?? rate.inputCacheMissPerMillion)
+        + (missOnly / 1_000_000) * rate.inputCacheMissPerMillion
+        + (usage.completionTokens / 1_000_000) * rate.outputPerMillion;
+    return {
+        currency: pricing.currency,
+        cost,
+        estimated: !hasCacheBreakdown,
+    };
+}

package/dist/model-selection.d.ts

@@ -0,0 +1,7 @@
+export interface ResolveConfiguredModelInput {
+    cliModel?: string;
+    sessionModel?: string;
+    defaultModel?: string;
+    fallbackProviderId?: string;
+}
+export declare function resolveConfiguredModel(input: ResolveConfiguredModelInput): string;

package/dist/model-selection.js

@@ -0,0 +1,18 @@
+import { decodeModel, encodeModel } from "./provider-registry.js";
+import { assertProviderModelAllowed } from "./provider-model-policy.js";
+export function resolveConfiguredModel(input) {
+    const selected = input.cliModel ?? input.sessionModel ?? input.defaultModel;
+    if (!selected)
+        return "";
+    const normalized = selected.includes(":")
+        ? selected
+        : input.fallbackProviderId
+            ? encodeModel(input.fallbackProviderId, selected)
+            : "";
+    if (!normalized)
+        return "";
+    const { providerId, modelId } = decodeModel(normalized);
+    if (providerId)
+        assertProviderModelAllowed(providerId, modelId);
+    return normalized;
+}

package/dist/network/chatgpt-transport.d.ts

@@ -0,0 +1,16 @@
+import { type Dispatcher } from "undici";
+export type ChatGptFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface ChatGptFetchOptions {
+    fetch?: ChatGptFetch;
+    env?: NodeJS.ProcessEnv;
+}
+type RequestInitWithDispatcher = RequestInit & {
+    dispatcher?: Dispatcher;
+};
+export declare function chatGptFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function getChatGptFetch(env?: NodeJS.ProcessEnv): ChatGptFetch;
+export declare function createChatGptFetch(options?: ChatGptFetchOptions): ChatGptFetch;
+export declare function createChatGptDispatcher(env?: NodeJS.ProcessEnv, input?: RequestInfo | URL): Dispatcher | undefined;
+export declare function withChatGptNetworkOptions(input: RequestInfo | URL, init: RequestInit | undefined, env?: NodeJS.ProcessEnv, dispatcher?: Dispatcher | undefined): RequestInitWithDispatcher;
+export declare function normalizeChatGptNetworkError(error: unknown, env?: NodeJS.ProcessEnv): Error;
+export {};

package/dist/network/chatgpt-transport.js

@@ -0,0 +1,232 @@
+import { readFileSync } from "node:fs";
+import { delimiter } from "node:path";
+import { rootCertificates } from "node:tls";
+import { Agent, ProxyAgent } from "undici";
+import { getSystemProxyForUrl } from "./system-proxy.js";
+let cachedDefaultFetch;
+export function chatGptFetch(input, init) {
+    return getChatGptFetch()(input, init);
+}
+export function getChatGptFetch(env = process.env) {
+    const signature = networkEnvSignature(env);
+    if (!cachedDefaultFetch || cachedDefaultFetch.signature !== signature) {
+        cachedDefaultFetch = {
+            signature,
+            fetch: createChatGptFetch({ env }),
+        };
+    }
+    return cachedDefaultFetch.fetch;
+}
+export function createChatGptFetch(options = {}) {
+    const env = options.env ?? process.env;
+    const fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const dispatcher = createChatGptDispatcher(env);
+    return async (input, init) => {
+        const requestInit = withChatGptNetworkOptions(input, init, env, dispatcher);
+        try {
+            return await fetchImpl(input, requestInit);
+        }
+        catch (error) {
+            throw normalizeChatGptNetworkError(error, env);
+        }
+    };
+}
+export function createChatGptDispatcher(env = process.env, input) {
+    const ca = loadExtraCaCertificates(env);
+    const proxy = input ? nodeProxyForUrl(input, env) : defaultNodeProxy(env);
+    if (!proxy && ca.length === 0)
+        return undefined;
+    const caOptions = ca.length > 0 ? { ca: [...rootCertificates, ...ca] } : undefined;
+    if (proxy) {
+        return new ProxyAgent({
+            uri: proxy,
+            ...(caOptions ? { requestTls: caOptions, proxyTls: caOptions } : {}),
+        });
+    }
+    return caOptions ? new Agent({ connect: caOptions }) : undefined;
+}
+export function withChatGptNetworkOptions(input, init, env = process.env, dispatcher = createChatGptDispatcher(env, input)) {
+    const next = { ...(init ?? {}) };
+    if (dispatcher)
+        next.dispatcher = dispatcher;
+    return next;
+}
+export function normalizeChatGptNetworkError(error, env = process.env) {
+    // Already normalized — wrapping again would nest "Original error:" messages.
+    if (error instanceof Error && error.message.includes("connection failed before Bubble received a response")) {
+        return error;
+    }
+    const text = errorMessageChain(error).join("\n");
+    if (!isChatGptNetworkErrorText(text)) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+    const systemProxy = hasProxyEnv(env) ? undefined : getSystemProxyForUrl(new URL("https://chatgpt.com/"), env);
+    const message = [
+        "ChatGPT connection failed before Bubble received a response.",
+        isCertificateErrorText(text)
+            ? "TLS certificate verification failed. If you are on a corporate proxy, VPN, or HTTPS inspection network, start Bubble with NODE_EXTRA_CA_CERTS=/absolute/path/to/ca.pem or BUBBLE_EXTRA_CA_CERTS=/absolute/path/to/ca.pem."
+            : "This looks like a proxy or network transport failure.",
+        hasProxyEnv(env)
+            ? "Bubble is using proxy environment variables for ChatGPT requests. Make sure NO_PROXY includes localhost,127.0.0.1."
+            : systemProxy
+                ? `Bubble is routing this request through the OS system proxy at ${systemProxy} (detected automatically). Check that the proxy app is running and healthy, or set BUBBLE_SYSTEM_PROXY=0 to disable system proxy detection.`
+                : "If your network requires a proxy, set HTTPS_PROXY or HTTP_PROXY, and set NO_PROXY=localhost,127.0.0.1.",
+        "Do not disable TLS verification with NODE_TLS_REJECT_UNAUTHORIZED=0.",
+        `Original error: ${firstMeaningfulErrorMessage(error) || "unknown network error"}`,
+    ].join(" ");
+    return new Error(message, { cause: error });
+}
+function hasProxyEnv(env) {
+    return Boolean(env.BUBBLE_CHATGPT_PROXY || env.bubble_chatgpt_proxy
+        || env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy || env.ALL_PROXY || env.all_proxy);
+}
+function chatGptProxyOverride(env) {
+    return env.BUBBLE_CHATGPT_PROXY ?? env.bubble_chatgpt_proxy;
+}
+function nodeProxyForUrl(input, env) {
+    const url = urlFromInput(input);
+    if (!url || shouldBypassProxy(url, env))
+        return undefined;
+    const override = chatGptProxyOverride(env);
+    if (override)
+        return override;
+    if (url.protocol === "https:")
+        return env.HTTPS_PROXY ?? env.https_proxy ?? env.ALL_PROXY ?? env.all_proxy ?? getSystemProxyForUrl(url, env);
+    if (url.protocol === "http:")
+        return env.HTTP_PROXY ?? env.http_proxy ?? env.ALL_PROXY ?? env.all_proxy ?? getSystemProxyForUrl(url, env);
+    return defaultNodeProxy(env);
+}
+function defaultNodeProxy(env) {
+    return chatGptProxyOverride(env)
+        ?? env.HTTPS_PROXY ?? env.https_proxy ?? env.HTTP_PROXY ?? env.http_proxy ?? env.ALL_PROXY ?? env.all_proxy
+        ?? getSystemProxyForUrl(new URL("https://system-proxy-default.invalid/"), env);
+}
+function urlFromInput(input) {
+    if (input instanceof URL)
+        return input;
+    if (typeof input === "string")
+        return URL.canParse(input) ? new URL(input) : undefined;
+    const url = input.url;
+    return URL.canParse(url) ? new URL(url) : undefined;
+}
+function shouldBypassProxy(url, env) {
+    const noProxy = (env.NO_PROXY ?? env.no_proxy ?? "").trim();
+    if (!noProxy)
+        return false;
+    if (noProxy === "*")
+        return true;
+    const hostname = url.hostname.toLowerCase();
+    const port = url.port;
+    return noProxy
+        .split(/[,\s]+/)
+        .filter(Boolean)
+        .some((entry) => noProxyEntryMatches(entry.toLowerCase(), hostname, port));
+}
+function noProxyEntryMatches(entry, hostname, port) {
+    const [entryHost, entryPort] = entry.includes(":") ? entry.split(":") : [entry, ""];
+    if (entryPort && entryPort !== port)
+        return false;
+    if (entryHost === hostname)
+        return true;
+    if (entryHost.startsWith("*."))
+        return hostname.endsWith(entryHost.slice(1));
+    if (entryHost.startsWith("."))
+        return hostname.endsWith(entryHost);
+    return false;
+}
+function loadExtraCaCertificates(env) {
+    const paths = extraCaCertificatePaths(env);
+    return paths.map((path) => {
+        try {
+            return readFileSync(path, "utf-8");
+        }
+        catch (error) {
+            throw new Error(`Failed to read ChatGPT custom CA certificate at ${path}. Check NODE_EXTRA_CA_CERTS or BUBBLE_EXTRA_CA_CERTS.`, {
+                cause: error,
+            });
+        }
+    });
+}
+function extraCaCertificatePaths(env) {
+    const bubbleValue = env.BUBBLE_EXTRA_CA_CERTS?.trim();
+    if (bubbleValue) {
+        return bubbleValue.split(delimiter).map((item) => item.trim()).filter(Boolean);
+    }
+    const nodeValue = env.NODE_EXTRA_CA_CERTS?.trim();
+    return nodeValue ? [nodeValue] : [];
+}
+function networkEnvSignature(env) {
+    return [
+        env.BUBBLE_CHATGPT_PROXY,
+        env.bubble_chatgpt_proxy,
+        env.HTTP_PROXY,
+        env.http_proxy,
+        env.HTTPS_PROXY,
+        env.https_proxy,
+        env.ALL_PROXY,
+        env.all_proxy,
+        env.NO_PROXY,
+        env.no_proxy,
+        env.NODE_EXTRA_CA_CERTS,
+        env.BUBBLE_EXTRA_CA_CERTS,
+        // Invalidate the cached fetch when the user toggles the OS proxy
+        // (e.g. turning Clash system proxy on/off mid-session).
+        getSystemProxyForUrl(new URL("https://chatgpt.com/"), env),
+    ].join("\0");
+}
+function isChatGptNetworkErrorText(text) {
+    return [
+        /fetch failed/i,
+        /network.*failed/i,
+        /socket connection was closed unexpectedly/i,
+        /\bConnectionClosed\b/i,
+        /\bECONNRESET\b/i,
+        /\bECONNREFUSED\b/i,
+        /\bETIMEDOUT\b/i,
+        /\bEPIPE\b/i,
+        /\bUND_ERR_/i,
+        /socket hang up/i,
+        /Unable to connect\. Is the computer able to access the url\?/i,
+        /certificate/i,
+        /unable to verify/i,
+        /self[- ]signed/i,
+    ].some((pattern) => pattern.test(text));
+}
+function isCertificateErrorText(text) {
+    return [
+        /unknown certificate verification error/i,
+        /certificate (?:verify|verification) (?:failed|error)/i,
+        /unable to verify (?:the )?(?:first )?certificate/i,
+        /UNABLE_TO_(?:VERIFY_LEAF_SIGNATURE|GET_ISSUER_CERT_LOCALLY)/i,
+        /SELF_SIGNED_CERT_IN_CHAIN/i,
+        /DEPTH_ZERO_SELF_SIGNED_CERT/i,
+        /CERT_(?:HAS_EXPIRED|UNTRUSTED|INVALID)/i,
+        /self[- ]signed certificate/i,
+    ].some((pattern) => pattern.test(text));
+}
+function firstMeaningfulErrorMessage(error) {
+    return errorMessageChain(error).find((item) => item && item !== "Error");
+}
+function errorMessageChain(error) {
+    const messages = [];
+    let current = error;
+    for (let depth = 0; current && depth < 8; depth++) {
+        if (current instanceof Error) {
+            messages.push(current.name, current.message);
+            current = current.cause;
+            continue;
+        }
+        if (typeof current === "object") {
+            const record = current;
+            for (const key of ["name", "code", "message"]) {
+                if (typeof record[key] === "string")
+                    messages.push(record[key]);
+            }
+            current = record.cause;
+            continue;
+        }
+        messages.push(String(current));
+        break;
+    }
+    return messages;
+}

package/dist/network/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Typed transport errors shared between providers and the subagent runtime.
+ *
+ * `RateLimitError` is the contract for 429 handling (design doc
+ * docs/subagent-runtime-design.md §4.5): under `rateLimitPolicy: "defer"` the
+ * transport performs no 429 backoff of its own and throws this error
+ * immediately so the subagent scheduler can be the single backoff layer.
+ */
+export declare class RateLimitError extends Error {
+    readonly isRateLimitError = true;
+    readonly status: number;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+export declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * A provider accepted the HTTP request but terminated generation with an
+ * in-band protocol error (for example OpenRouter's HTTP-200 SSE error chunk).
+ * Keeping the wire status/type structured prevents the agent from mistaking
+ * the terminal event for a successful empty response.
+ */
+export declare class ProviderResponseError extends Error {
+    readonly isProviderResponseError = true;
+    readonly status?: number;
+    readonly errorType?: string;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        errorType?: string;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+export declare function isProviderResponseError(error: unknown): error is ProviderResponseError;
+/**
+ * How a provider transport should treat HTTP 429 responses.
+ *
+ * - "handle": retry inside the transport with backoff (parent traffic default).
+ * - "defer":  do not retry 429 at all; throw RateLimitError immediately so the
+ *             caller (subagent scheduler) owns the backoff. Other retryable
+ *             statuses are unaffected.
+ */
+export type RateLimitPolicy = "handle" | "defer";

package/dist/network/errors.js

@@ -0,0 +1,48 @@
+/**
+ * Typed transport errors shared between providers and the subagent runtime.
+ *
+ * `RateLimitError` is the contract for 429 handling (design doc
+ * docs/subagent-runtime-design.md §4.5): under `rateLimitPolicy: "defer"` the
+ * transport performs no 429 backoff of its own and throws this error
+ * immediately so the subagent scheduler can be the single backoff layer.
+ */
+export class RateLimitError extends Error {
+    isRateLimitError = true;
+    status;
+    retryAfterMs;
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "RateLimitError";
+        this.status = options?.status ?? 429;
+        this.retryAfterMs = options?.retryAfterMs;
+    }
+}
+export function isRateLimitError(error) {
+    return !!error
+        && typeof error === "object"
+        && error.isRateLimitError === true;
+}
+/**
+ * A provider accepted the HTTP request but terminated generation with an
+ * in-band protocol error (for example OpenRouter's HTTP-200 SSE error chunk).
+ * Keeping the wire status/type structured prevents the agent from mistaking
+ * the terminal event for a successful empty response.
+ */
+export class ProviderResponseError extends Error {
+    isProviderResponseError = true;
+    status;
+    errorType;
+    retryAfterMs;
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "ProviderResponseError";
+        this.status = options.status;
+        this.errorType = options.errorType;
+        this.retryAfterMs = options.retryAfterMs;
+    }
+}
+export function isProviderResponseError(error) {
+    return !!error
+        && typeof error === "object"
+        && error.isProviderResponseError === true;
+}

package/dist/network/provider-transport-log.d.ts

@@ -0,0 +1,12 @@
+import { type ProviderErrorContext } from "../provider-error-record.js";
+export interface ProviderTransportFailureContext extends ProviderErrorContext {
+    sessionId: string;
+    requestId: string;
+    attempt: number;
+    responseStatus?: number;
+    receivedEvents: number;
+    elapsedMs: number;
+    lastEventAgeMs?: number;
+    decision: "retry" | "delegate_retry" | "fail" | "cancelled";
+}
+export declare function logProviderTransportFailure(error: unknown, context: ProviderTransportFailureContext): void;

package/dist/network/provider-transport-log.js

@@ -0,0 +1,32 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+import { createSanitizedProviderError } from "../provider-error-record.js";
+// Failure-only diagnostics are enabled without BUBBLE_TRACE. Keep at most two
+// 2 MiB files; never persist request/response bodies, headers, or raw errors.
+export function logProviderTransportFailure(error, context) {
+    try {
+        const dir = join(getBubbleHome(), "logs");
+        mkdirSync(dir, { recursive: true });
+        const file = join(dir, "provider-transport.jsonl");
+        if (existsSync(file) && statSync(file).size >= 2 * 1024 * 1024) {
+            renameSync(file, `${file}.1`);
+        }
+        appendFileSync(file, JSON.stringify({
+            timestamp: new Date().toISOString(),
+            phase: "provider_transport_failure",
+            sessionId: context.sessionId,
+            requestId: context.requestId,
+            attempt: context.attempt,
+            responseStatus: context.responseStatus,
+            receivedEvents: context.receivedEvents,
+            elapsedMs: context.elapsedMs,
+            lastEventAgeMs: context.lastEventAgeMs,
+            decision: context.decision,
+            error: createSanitizedProviderError(error, context),
+        }) + "\n", { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Disk errors and concurrent rotation must never affect the request.
+    }
+}