@substrat-run/model-providers 0.1.0

package/dist/pricing.js

@@ -0,0 +1,100 @@
+/**
+ * List-price math over the generated rate card — QUANTITIES × LIST RATES, and
+ * nothing more. Margin is vocabulary: the builder studio charges list × 1.2
+ * for its own spend, the platform will charge list × (1 + its margin) for
+ * inference it provides (#1054), and the metering engine owns neither (D-E).
+ * Each of those is a one-line wrapper over `listCostOfSteps`; the tier and
+ * cache semantics below are the part that must not be re-derived twice.
+ *
+ * The rate card itself is GENERATED (rate-card.generated.ts) from models.dev ×
+ * LiteLLM with a failing cross-check, and reviewed as a PR diff — the billing
+ * checkpoint of docs/architecture/builder/harness.md §2.2. This file owns the math:
+ *
+ *   - Tier selection is ALL-OR-NOTHING by a request's total input tokens
+ *     (DashScope/Anthropic threshold semantics): the whole request bills at
+ *     the tier its input lands in. That makes pricing inherently PER-STEP — a
+ *     turn is dozens of requests, and summing them before selecting a tier
+ *     would land the sum in a tier no single request reached. `listCostOfSteps`
+ *     is the correct path; `listCostOf` over totals is the legacy fallback for
+ *     entries recorded before per-step usage existed.
+ *   - Cache reads/writes bill at their own rates when the card has them; a
+ *     missing cache rate bills that slice at the plain input rate — the
+ *     provider's own behavior when it publishes no cache pricing. A discount
+ *     is only ever applied when a catalog actually states one.
+ *
+ * Decimal strings end to end (K-14). Token counts convert to exact millions
+ * (an integer / 1e6 is at most 6 dp), so mulDecimal's 6 dp micro-unit scale
+ * never truncates — which is also why rates are multiplied per-MILLION, never
+ * pre-divided to a per-token rate ($0.19/1M per-token would be 1.9e-7, below
+ * the 6 dp floor).
+ */
+import { addDecimal, mulDecimal } from '@substrat-run/contracts';
+import { RATE_CARD } from './rate-card.generated.js';
+import { parseModelSpec } from './spec.js';
+/** The card entry for a `provider:model`, by longest id prefix; null = unpriced. */
+export function rateFor(model) {
+    if (model.indexOf(':') === -1)
+        return null;
+    const { provider, modelId } = parseModelSpec(model);
+    let best = null;
+    for (const rate of RATE_CARD) {
+        if (rate.provider !== provider || !modelId.startsWith(rate.idPrefix))
+            continue;
+        if (!best || rate.idPrefix.length > best.idPrefix.length)
+            best = rate;
+    }
+    return best;
+}
+/** An integer token count as an exact millions decimal (12_345 → '0.012345'). */
+function tokensInMillions(tokens) {
+    const s = String(Math.max(0, Math.round(tokens))).padStart(7, '0');
+    const frac = s.slice(-6).replace(/0+$/, '');
+    return `${s.slice(0, -6)}${frac ? `.${frac}` : ''}`;
+}
+/** All-or-nothing: first tier whose bound holds the request's total input. */
+function tierFor(rate, inputTokens) {
+    for (const tier of rate.tiers) {
+        if (tier.upToInputTokens === null || inputTokens <= tier.upToInputTokens)
+            return tier;
+    }
+    // Unreachable for a well-formed card (last tier is unbounded); the generator
+    // guarantees it, but a fallback beats a throw in the billing path.
+    return rate.tiers[rate.tiers.length - 1];
+}
+/**
+ * Price a turn from its per-request steps — the correct path (see header).
+ * USD list price as a decimal string; null when the model has no rate card
+ * entry — unpriced, never guessed.
+ */
+export function listCostOfSteps(model, steps) {
+    const rate = rateFor(model);
+    if (!rate)
+        return null;
+    let listUsd = '0';
+    for (const step of steps) {
+        const tier = tierFor(rate, step.inputTokens);
+        const cacheRead = Math.min(step.cachedInputTokens ?? 0, step.inputTokens);
+        const cacheWrite = Math.min(step.cacheWriteTokens ?? 0, step.inputTokens - cacheRead);
+        const plainInput = step.inputTokens - cacheRead - cacheWrite;
+        listUsd = addDecimal(listUsd, mulDecimal(tokensInMillions(plainInput), tier.inputPer1M));
+        listUsd = addDecimal(listUsd, mulDecimal(tokensInMillions(step.outputTokens), tier.outputPer1M));
+        if (cacheRead > 0) {
+            listUsd = addDecimal(listUsd, mulDecimal(tokensInMillions(cacheRead), tier.cacheReadPer1M ?? tier.inputPer1M));
+        }
+        if (cacheWrite > 0) {
+            listUsd = addDecimal(listUsd, mulDecimal(tokensInMillions(cacheWrite), tier.cacheWritePer1M ?? tier.inputPer1M));
+        }
+    }
+    return listUsd;
+}
+/**
+ * Legacy totals path: ledger entries recorded before per-step usage carry only
+ * turn totals, with no step split and no cache breakdown. Priced as ONE
+ * pseudo-request — for a single-tier card this equals the per-step price
+ * exactly; for a tiered card it can only over-select the tier, so a read side
+ * uses recorded costs whenever they exist and falls back here only for old rows.
+ */
+export function listCostOf(model, inputTokens, outputTokens) {
+    return listCostOfSteps(model, [{ inputTokens, outputTokens }]);
+}
+//# sourceMappingURL=pricing.js.map

package/dist/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"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"}

package/dist/provider-errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Provider-failure explanations — WORKER-SAFE (no node imports), shared by the
+ * hosted DO and the local CLI.
+ *
+ * Exists because every provider failure this project has actually hit rendered
+ * as something misleading before it rendered as itself: a region-scoped key as
+ * "invalid", a missing endpoint as a bad token, and an exhausted weekly quota
+ * as "API key is invalid" — that last one is the incident that forced this
+ * file. The rule: name the REAL failure class first, keep the provider's own
+ * message (it often carries the useful detail, like a quota reset time), and
+ * always end with what the user can do next.
+ */
+export interface ErrorFacts {
+    readonly statusCode?: number;
+    readonly code?: string;
+    readonly url?: string;
+    readonly message: string;
+}
+/** Best-effort extraction from an AI SDK APICallError-shaped object. */
+export declare function errorFacts(err: unknown): ErrorFacts;
+/**
+ * Turn a provider error into an actionable message, or null to keep the raw
+ * one. `where` distinguishes the credential's home so the "what next" step is
+ * real: 'hosted' → worker secrets; 'local' → apps/builder/.env.
+ */
+export declare function explainProviderFailure(provider: string, err: unknown, where: 'hosted' | 'local'): string | null;
+//# sourceMappingURL=provider-errors.d.ts.map

package/dist/provider-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-errors.d.ts","sourceRoot":"","sources":["../src/provider-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,QAAQ,GAAG,OAAO,GACvB,MAAM,GAAG,IAAI,CAqDf"}

package/dist/provider-errors.js

@@ -0,0 +1,74 @@
+/**
+ * Provider-failure explanations — WORKER-SAFE (no node imports), shared by the
+ * hosted DO and the local CLI.
+ *
+ * Exists because every provider failure this project has actually hit rendered
+ * as something misleading before it rendered as itself: a region-scoped key as
+ * "invalid", a missing endpoint as a bad token, and an exhausted weekly quota
+ * as "API key is invalid" — that last one is the incident that forced this
+ * file. The rule: name the REAL failure class first, keep the provider's own
+ * message (it often carries the useful detail, like a quota reset time), and
+ * always end with what the user can do next.
+ */
+/** Best-effort extraction from an AI SDK APICallError-shaped object. */
+export function errorFacts(err) {
+    const e = err;
+    const data = e?.['data']?.['error'];
+    return {
+        statusCode: typeof e?.['statusCode'] === 'number' ? e['statusCode'] : undefined,
+        code: typeof data?.['code'] === 'string' ? data['code'] : undefined,
+        url: typeof e?.['url'] === 'string' ? e['url'] : undefined,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+/**
+ * Turn a provider error into an actionable message, or null to keep the raw
+ * one. `where` distinguishes the credential's home so the "what next" step is
+ * real: 'hosted' → worker secrets; 'local' → apps/builder/.env.
+ */
+export function explainProviderFailure(provider, err, where) {
+    const f = errorFacts(err);
+    const fix = where === 'hosted'
+        ? `worker secret (secrets/platform.prod.env → BUILDER_* → secrets.mjs push --only builder)`
+        : `apps/builder/.env`;
+    // Quota exhaustion is NOT an invalid key — the misread that forced this file.
+    if (f.code === 'insufficient_quota' || /quota .*(exhaust|exceed)|insufficient_quota/i.test(f.message)) {
+        return [
+            `${provider}: quota exhausted — the key is fine, the plan's budget is spent.`,
+            `  Provider says: ${f.message}`,
+            `  Next: wait for the stated reset, top up the plan, or switch model in the picker`,
+            `  (another provider keeps working meanwhile).`,
+        ].join('\n');
+    }
+    // Rate limit ≠ quota ≠ auth: transient, retry-shaped.
+    if (f.statusCode === 429) {
+        return [
+            `${provider}: rate limited (HTTP 429) — transient, not a key problem.`,
+            `  Provider says: ${f.message}`,
+            `  Next: retry the turn in a moment.`,
+        ].join('\n');
+    }
+    if (f.statusCode === 401 || f.statusCode === 403) {
+        const lines = [
+            `${provider}: credential rejected (HTTP ${f.statusCode}).`,
+            `  Provider says: ${f.message}`,
+        ];
+        if (provider === 'qwen') {
+            lines.push(`  DashScope keys are REGION- and WORKSPACE-scoped — the key is often fine,`, `  just minted for a different endpoint than ${f.url || 'the one configured'}.`, `  Check the key and DASHSCOPE_BASE_URL agree (${fix}).`);
+        }
+        else {
+            lines.push(`  Check the key in the ${fix} — no stray quotes or whitespace.`);
+        }
+        return lines.join('\n');
+    }
+    if (/model.{0,4}not.{0,4}exist|model_not_found|does not exist/i.test(f.message)) {
+        return [
+            `${provider}: this endpoint does not serve that model id.`,
+            `  Provider says: ${f.message}`,
+            `  Next: pick a different model in the picker — workspace/regional plans`,
+            `  expose their own catalogs, so an id valid elsewhere can be absent here.`,
+        ].join('\n');
+    }
+    return null;
+}
+//# sourceMappingURL=provider-errors.js.map

package/dist/provider-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-errors.js","sourceRoot":"","sources":["../src/provider-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,wEAAwE;AACxE,MAAM,UAAU,UAAU,CAAC,GAAY;IACtC,MAAM,CAAC,GAAG,GAAqC,CAAC;IAChD,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,MAAM,CAAyC,EAAE,CAAC,OAAO,CAE/D,CAAC;IACb,OAAO;QACN,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,YAAY,CAAY,CAAC,CAAC,CAAC,SAAS;QAC3F,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,MAAM,CAAY,CAAC,CAAC,CAAC,SAAS;QAC/E,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,KAAK,CAAY,CAAC,CAAC,CAAC,SAAS;QACtE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;KACzD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACrC,QAAgB,EAChB,GAAY,EACZ,KAAyB;IAEzB,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,GAAG,GACR,KAAK,KAAK,QAAQ;QACjB,CAAC,CAAC,yFAAyF;QAC3F,CAAC,CAAC,mBAAmB,CAAC;IAExB,8EAA8E;IAC9E,IAAI,CAAC,CAAC,IAAI,KAAK,oBAAoB,IAAI,8CAA8C,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QACvG,OAAO;YACN,GAAG,QAAQ,kEAAkE;YAC7E,oBAAoB,CAAC,CAAC,OAAO,EAAE;YAC/B,mFAAmF;YACnF,+CAA+C;SAC/C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAED,sDAAsD;IACtD,IAAI,CAAC,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;QAC1B,OAAO;YACN,GAAG,QAAQ,2DAA2D;YACtE,oBAAoB,CAAC,CAAC,OAAO,EAAE;YAC/B,qCAAqC;SACrC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAED,IAAI,CAAC,CAAC,UAAU,KAAK,GAAG,IAAI,CAAC,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG;YACb,GAAG,QAAQ,+BAA+B,CAAC,CAAC,UAAU,IAAI;YAC1D,oBAAoB,CAAC,CAAC,OAAO,EAAE;SAC/B,CAAC;QACF,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CACT,4EAA4E,EAC5E,+CAA+C,CAAC,CAAC,GAAG,IAAI,oBAAoB,GAAG,EAC/E,iDAAiD,GAAG,IAAI,CACxD,CAAC;QACH,CAAC;aAAM,CAAC;YACP,KAAK,CAAC,IAAI,CAAC,0BAA0B,GAAG,mCAAmC,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,2DAA2D,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QACjF,OAAO;YACN,GAAG,QAAQ,+CAA+C;YAC1D,oBAAoB,CAAC,CAAC,OAAO,EAAE;YAC/B,yEAAyE;YACzE,2EAA2E;SAC3E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/providers.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The provider table — "any LLM" is expressed here and nowhere else (D-49, D-50,
+ * #1054).
+ *
+ * A `provider:model` string names a row; the row says how to reach the
+ * endpoint, which environment keys carry its credential, where inference runs
+ * (the D-53/D-54 subprocessor disclosure) and what to suggest in a picker.
+ * Adding a provider is one row. Nothing downstream — the builder's generator,
+ * a vertical's assistant, the pricing ledger, a settings screen — knows which
+ * row ran. If that ever stops being true, the seam has leaked.
+ *
+ * Two shapes:
+ *   - `direct`     — an AI SDK provider package with a `createX` factory. The
+ *                    package is NOT imported here: a Node host loads it
+ *                    dynamically, a Worker host imports it statically, and both
+ *                    hand the factory to `createModel`. That is what keeps this
+ *                    file loadable everywhere.
+ *   - `compatible` — an OpenAI-compatible HTTP endpoint, built with
+ *                    `createOpenAICompatible({ baseURL, apiKey })`. One package
+ *                    covers DashScope/Qwen, Cloudflare, Scaleway, Ollama, vLLM,
+ *                    LM Studio, OpenRouter and anything else speaking that
+ *                    dialect, which is why most rows land here.
+ *
+ * Cloudflare is deliberately an ordinary `compatible` row. Its gateway features
+ * (unified billing, per-request metadata, spend limits) are extras a host may
+ * layer on THAT row — never a reason for a second code path.
+ */
+export interface HostingSpec {
+    /** Who operates the inference endpoint. */
+    readonly vendor: string;
+    /**
+     * Where, as precisely as the endpoint tells us. A function decodes it from the
+     * effective host when one vendor serves several regions (DashScope).
+     */
+    readonly location: string | ((host: string) => string);
+    /**
+     * True for inference that never leaves the machine the host runs on. A hosted
+     * catalog excludes these; the disclosure sentence changes.
+     */
+    readonly local?: boolean;
+}
+interface ProviderBase {
+    readonly hosting: HostingSpec;
+    /** Env var holding the credential. Absent for local runtimes that need none. */
+    readonly envVar?: string;
+    /** Picker suggestions for a provider with no listable catalog; free text still wins. */
+    readonly suggested?: readonly string[];
+    /** One line for `--help`-style listings. */
+    readonly note?: string;
+}
+export interface DirectProvider extends ProviderBase {
+    readonly kind: 'direct';
+    /** The AI SDK package a host imports. */
+    readonly pkg: string;
+    /** Default export, used by a Node host when no base-URL override is set. */
+    readonly factory: string;
+    /** `createX` form — what `createModel` is handed. */
+    readonly createFactory: string;
+    /** Env var holding a base-URL override. Absent ⇒ endpoint is not overridable. */
+    readonly baseUrlEnv?: string;
+    /** The host requests go to when no override is set — for the disclosure. */
+    readonly defaultHost: string;
+}
+export interface CompatibleProvider extends ProviderBase {
+    readonly kind: 'compatible';
+    /** Default endpoint; empty when the endpoint is account-scoped and must be set. */
+    readonly baseUrl: string;
+    /** Env var overriding the endpoint — self-hosted, regional, or account-scoped. */
+    readonly baseUrlEnv: string;
+    /**
+     * How the endpoint lists its models. `openai` = `GET {base}/models`;
+     * `cloudflare-catalog` = the account-level `…/ai/models/search` (Workers AI's
+     * compatible surface answers 405 to `/models`).
+     */
+    readonly catalog?: 'openai' | 'cloudflare-catalog';
+    /**
+     * A fetch wrapper the row needs at the wire — DashScope's explicit
+     * context-cache markers. Named, not imported, so the table stays data.
+     */
+    readonly wire?: 'qwen-cache';
+    /**
+     * Per-request extras the row's endpoint understands — Cloudflare's AI Gateway
+     * headers (attribution metadata, payload retention off, gateway selection). Named
+     * here and dispatched in request.ts, never on the provider's name.
+     */
+    readonly request?: 'cloudflare-gateway';
+}
+export type ProviderSpec = DirectProvider | CompatibleProvider;
+declare const SENT = "sent to this provider";
+export declare const PROVIDERS: Readonly<Record<string, ProviderSpec>>;
+/**
+ * Ollama's endpoint is overridable, so "this machine" is a claim about the ENDPOINT, not
+ * about the row. Pointed at a GPU box on the LAN it is somebody else's machine, and the
+ * disclosure says so rather than repeating the default.
+ */
+export declare function ollamaLocation(host: string): string;
+/** DashScope endpoints encode region three different ways; decode them all. */
+export declare function qwenLocation(host: string): string;
+/**
+ * The row for a provider name, or `undefined` — the ONLY way to look one up.
+ *
+ * Never `PROVIDERS[name]` directly. The table is an object literal, so a name that
+ * happens to be an `Object.prototype` member — `constructor`, `toString`, `valueOf` —
+ * resolves to a truthy INHERITED value, sails past an `if (!row)` guard, and reaches
+ * `row.hosting.local` as a TypeError instead of the "unknown provider" error the caller
+ * is owed. That is reachable from config, not just from a typo: a model spec is a
+ * per-install setting (a desk's `TICKET0_MODEL`), so `constructor:x` is a value a
+ * settings field can hold.
+ */
+export declare function providerRow(name: string): ProviderSpec | undefined;
+/** One line per provider, for a CLI's "known providers" listing. */
+export declare function knownProviders(): string;
+/** The credential env var of a provider, or null when it needs none / is unknown. */
+export declare function credentialEnvVar(provider: string): string | null;
+export { SENT as DATA_SENT_PHRASE };
+//# sourceMappingURL=providers.d.ts.map

package/dist/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,MAAM,WAAW,WAAW;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,UAAU,YAAY;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAe,SAAQ,YAAY;IACnD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,oBAAoB,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACxC;AAED,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAE/D,QAAA,MAAM,IAAI,0BAA0B,CAAC;AAErC,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAyH5D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAElE;AAED,oEAAoE;AACpE,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEhE;AAED,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/providers.js

@@ -0,0 +1,193 @@
+/**
+ * The provider table — "any LLM" is expressed here and nowhere else (D-49, D-50,
+ * #1054).
+ *
+ * A `provider:model` string names a row; the row says how to reach the
+ * endpoint, which environment keys carry its credential, where inference runs
+ * (the D-53/D-54 subprocessor disclosure) and what to suggest in a picker.
+ * Adding a provider is one row. Nothing downstream — the builder's generator,
+ * a vertical's assistant, the pricing ledger, a settings screen — knows which
+ * row ran. If that ever stops being true, the seam has leaked.
+ *
+ * Two shapes:
+ *   - `direct`     — an AI SDK provider package with a `createX` factory. The
+ *                    package is NOT imported here: a Node host loads it
+ *                    dynamically, a Worker host imports it statically, and both
+ *                    hand the factory to `createModel`. That is what keeps this
+ *                    file loadable everywhere.
+ *   - `compatible` — an OpenAI-compatible HTTP endpoint, built with
+ *                    `createOpenAICompatible({ baseURL, apiKey })`. One package
+ *                    covers DashScope/Qwen, Cloudflare, Scaleway, Ollama, vLLM,
+ *                    LM Studio, OpenRouter and anything else speaking that
+ *                    dialect, which is why most rows land here.
+ *
+ * Cloudflare is deliberately an ordinary `compatible` row. Its gateway features
+ * (unified billing, per-request metadata, spend limits) are extras a host may
+ * layer on THAT row — never a reason for a second code path.
+ */
+import { isLoopbackHost } from './host.js';
+const SENT = 'sent to this provider';
+export const PROVIDERS = {
+    anthropic: {
+        kind: 'direct',
+        pkg: '@ai-sdk/anthropic',
+        factory: 'anthropic',
+        createFactory: 'createAnthropic',
+        baseUrlEnv: 'ANTHROPIC_BASE_URL',
+        envVar: 'ANTHROPIC_API_KEY',
+        defaultHost: 'api.anthropic.com',
+        hosting: { vendor: 'Anthropic', location: 'United States' },
+        suggested: ['claude-opus-5', 'claude-sonnet-5', 'claude-haiku-4-5', 'claude-fable-5'],
+        note: 'e.g. anthropic:claude-opus-5',
+    },
+    openai: {
+        kind: 'direct',
+        pkg: '@ai-sdk/openai',
+        factory: 'openai',
+        createFactory: 'createOpenAI',
+        baseUrlEnv: 'OPENAI_BASE_URL',
+        envVar: 'OPENAI_API_KEY',
+        defaultHost: 'api.openai.com',
+        hosting: { vendor: 'OpenAI', location: 'United States' },
+    },
+    google: {
+        kind: 'direct',
+        pkg: '@ai-sdk/google',
+        factory: 'google',
+        createFactory: 'createGoogleGenerativeAI',
+        envVar: 'GOOGLE_GENERATIVE_AI_API_KEY',
+        defaultHost: 'generativelanguage.googleapis.com',
+        hosting: { vendor: 'Google', location: 'United States / global' },
+    },
+    mistral: {
+        kind: 'direct',
+        pkg: '@ai-sdk/mistral',
+        factory: 'mistral',
+        createFactory: 'createMistral',
+        envVar: 'MISTRAL_API_KEY',
+        defaultHost: 'api.mistral.ai',
+        hosting: { vendor: 'Mistral', location: 'European Union (France)' },
+    },
+    /**
+     * Alibaba Model Studio (DashScope), OpenAI-compatible mode. Defaults to the
+     * international endpoint; set DASHSCOPE_BASE_URL for the China-mainland
+     * (`https://dashscope.aliyuncs.com/compatible-mode/v1`), US, or a regional
+     * workspace endpoint. Keys are region- and workspace-scoped, which is why the
+     * location is decoded from the host rather than stated.
+     */
+    qwen: {
+        kind: 'compatible',
+        baseUrl: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
+        baseUrlEnv: 'DASHSCOPE_BASE_URL',
+        envVar: 'DASHSCOPE_API_KEY',
+        catalog: 'openai',
+        wire: 'qwen-cache',
+        hosting: { vendor: 'Alibaba Cloud (Model Studio)', location: qwenLocation },
+        note: 'e.g. qwen:qwen3-coder-plus · region override via DASHSCOPE_BASE_URL',
+    },
+    /**
+     * Cloudflare Workers AI + AI Gateway, OpenAI-compatible mode. The endpoint is
+     * account-scoped (`…/accounts/<id>/ai/v1`), so there is no static default —
+     * set CLOUDFLARE_AI_BASE_URL with the account id. Model ids keep their full
+     * catalog prefix: `@cf/…` runs on Cloudflare's own network, a bare
+     * `vendor/model` slug (e.g. `openai/gpt-4.1-mini`) is partner-served under
+     * unified billing. Deliberately NOT wrangler's CLOUDFLARE_API_TOKEN, so an
+     * ambient deploy token is never silently used for inference.
+     */
+    cloudflare: {
+        kind: 'compatible',
+        baseUrl: '',
+        baseUrlEnv: 'CLOUDFLARE_AI_BASE_URL',
+        envVar: 'CLOUDFLARE_AI_API_TOKEN',
+        catalog: 'cloudflare-catalog',
+        request: 'cloudflare-gateway',
+        hosting: {
+            vendor: 'Cloudflare (Workers AI)',
+            // D-53 honesty: `@cf/…` ids run on Cloudflare's network; bare
+            // `vendor/model` ids are partner-served on that vendor's infrastructure.
+            location: 'global (Cloudflare network) · vendor/model ids partner-served',
+        },
+        suggested: ['@cf/zai-org/glm-5.2', '@cf/moonshotai/kimi-k2.7-code', 'deepseek/deepseek-v4-pro'],
+        note: 'e.g. cloudflare:@cf/zai-org/glm-5.2 · set CLOUDFLARE_AI_BASE_URL to https://api.cloudflare.com/client/v4/accounts/<id>/ai/v1',
+    },
+    /**
+     * Scaleway Generative APIs — EU-hosted (Paris) open-weight models behind the
+     * OpenAI dialect. The row that makes the data-residency answer a picker
+     * choice rather than a procurement exception.
+     */
+    scaleway: {
+        kind: 'compatible',
+        baseUrl: 'https://api.scaleway.ai/v1',
+        baseUrlEnv: 'SCALEWAY_AI_BASE_URL',
+        envVar: 'SCALEWAY_API_KEY',
+        catalog: 'openai',
+        hosting: { vendor: 'Scaleway (Generative APIs)', location: 'European Union (France, Paris)' },
+        note: 'e.g. scaleway:llama-3.3-70b-instruct · EU-resident inference',
+    },
+    /** Local models. No credential; the endpoint is Ollama's OpenAI-compatible one. */
+    ollama: {
+        kind: 'compatible',
+        baseUrl: 'http://localhost:11434/v1',
+        baseUrlEnv: 'OLLAMA_BASE_URL',
+        catalog: 'openai',
+        hosting: { vendor: 'Ollama (self-hosted)', location: ollamaLocation, local: true },
+        note: 'e.g. ollama:qwen3-coder · needs `ollama serve` and the model pulled',
+    },
+    /** Escape hatch: anything else speaking the OpenAI dialect (vLLM, LM Studio, OpenRouter…). */
+    compat: {
+        kind: 'compatible',
+        baseUrl: '',
+        baseUrlEnv: 'OPENAI_COMPATIBLE_BASE_URL',
+        envVar: 'OPENAI_COMPATIBLE_API_KEY',
+        catalog: 'openai',
+        hosting: { vendor: 'Custom endpoint', location: 'operator-defined' },
+        note: 'set OPENAI_COMPATIBLE_BASE_URL to the endpoint',
+    },
+};
+/**
+ * Ollama's endpoint is overridable, so "this machine" is a claim about the ENDPOINT, not
+ * about the row. Pointed at a GPU box on the LAN it is somebody else's machine, and the
+ * disclosure says so rather than repeating the default.
+ */
+export function ollamaLocation(host) {
+    return isLoopbackHost(host) ? 'this machine' : 'a remote host — OLLAMA_BASE_URL points off this machine';
+}
+/** DashScope endpoints encode region three different ways; decode them all. */
+export function qwenLocation(host) {
+    if (host.includes('dashscope-intl'))
+        return 'Singapore (international endpoint)';
+    if (host.includes('dashscope-us'))
+        return 'United States';
+    if (host === 'dashscope.aliyuncs.com')
+        return 'China mainland';
+    const regional = host.match(/^([^.]+)\.([a-z]{2}-[a-z]+-\d)\.maas\.aliyuncs\.com$/);
+    if (regional)
+        return `workspace "${regional[1]}" · region ${regional[2]}`;
+    return 'unknown region';
+}
+/**
+ * The row for a provider name, or `undefined` — the ONLY way to look one up.
+ *
+ * Never `PROVIDERS[name]` directly. The table is an object literal, so a name that
+ * happens to be an `Object.prototype` member — `constructor`, `toString`, `valueOf` —
+ * resolves to a truthy INHERITED value, sails past an `if (!row)` guard, and reaches
+ * `row.hosting.local` as a TypeError instead of the "unknown provider" error the caller
+ * is owed. That is reachable from config, not just from a typo: a model spec is a
+ * per-install setting (a desk's `TICKET0_MODEL`), so `constructor:x` is a value a
+ * settings field can hold.
+ */
+export function providerRow(name) {
+    return Object.hasOwn(PROVIDERS, name) ? PROVIDERS[name] : undefined;
+}
+/** One line per provider, for a CLI's "known providers" listing. */
+export function knownProviders() {
+    return Object.entries(PROVIDERS)
+        .map(([name, spec]) => `    ${name.padEnd(10)} ${spec.note ?? ''}`)
+        .join('\n');
+}
+/** The credential env var of a provider, or null when it needs none / is unknown. */
+export function credentialEnvVar(provider) {
+    return providerRow(provider)?.envVar ?? null;
+}
+export { SENT as DATA_SENT_PHRASE };
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAoE3C,MAAM,IAAI,GAAG,uBAAuB,CAAC;AAErC,MAAM,CAAC,MAAM,SAAS,GAA2C;IAChE,SAAS,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,mBAAmB;QACxB,OAAO,EAAE,WAAW;QACpB,aAAa,EAAE,iBAAiB;QAChC,UAAU,EAAE,oBAAoB;QAChC,MAAM,EAAE,mBAAmB;QAC3B,WAAW,EAAE,mBAAmB;QAChC,OAAO,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC3D,SAAS,EAAE,CAAC,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,gBAAgB,CAAC;QACrF,IAAI,EAAE,8BAA8B;KACpC;IACD,MAAM,EAAE;QACP,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,gBAAgB;QACrB,OAAO,EAAE,QAAQ;QACjB,aAAa,EAAE,cAAc;QAC7B,UAAU,EAAE,iBAAiB;QAC7B,MAAM,EAAE,gBAAgB;QACxB,WAAW,EAAE,gBAAgB;QAC7B,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE;KACxD;IACD,MAAM,EAAE;QACP,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,gBAAgB;QACrB,OAAO,EAAE,QAAQ;QACjB,aAAa,EAAE,0BAA0B;QACzC,MAAM,EAAE,8BAA8B;QACtC,WAAW,EAAE,mCAAmC;QAChD,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,wBAAwB,EAAE;KACjE;IACD,OAAO,EAAE;QACR,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,iBAAiB;QACtB,OAAO,EAAE,SAAS;QAClB,aAAa,EAAE,eAAe;QAC9B,MAAM,EAAE,iBAAiB;QACzB,WAAW,EAAE,gBAAgB;QAC7B,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,yBAAyB,EAAE;KACnE;IAED;;;;;;OAMG;IACH,IAAI,EAAE;QACL,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,wDAAwD;QACjE,UAAU,EAAE,oBAAoB;QAChC,MAAM,EAAE,mBAAmB;QAC3B,OAAO,EAAE,QAAQ;QACjB,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,EAAE,MAAM,EAAE,8BAA8B,EAAE,QAAQ,EAAE,YAAY,EAAE;QAC3E,IAAI,EAAE,qEAAqE;KAC3E;IAED;;;;;;;;OAQG;IACH,UAAU,EAAE;QACX,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,wBAAwB;QACpC,MAAM,EAAE,yBAAyB;QACjC,OAAO,EAAE,oBAAoB;QAC7B,OAAO,EAAE,oBAAoB;QAC7B,OAAO,EAAE;YACR,MAAM,EAAE,yBAAyB;YACjC,8DAA8D;YAC9D,yEAAyE;YACzE,QAAQ,EAAE,+DAA+D;SACzE;QACD,SAAS,EAAE,CAAC,qBAAqB,EAAE,+BAA+B,EAAE,0BAA0B,CAAC;QAC/F,IAAI,EAAE,8HAA8H;KACpI;IAED;;;;OAIG;IACH,QAAQ,EAAE;QACT,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,4BAA4B;QACrC,UAAU,EAAE,sBAAsB;QAClC,MAAM,EAAE,kBAAkB;QAC1B,OAAO,EAAE,QAAQ;QACjB,OAAO,EAAE,EAAE,MAAM,EAAE,4BAA4B,EAAE,QAAQ,EAAE,gCAAgC,EAAE;QAC7F,IAAI,EAAE,8DAA8D;KACpE;IAED,mFAAmF;IACnF,MAAM,EAAE;QACP,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,2BAA2B;QACpC,UAAU,EAAE,iBAAiB;QAC7B,OAAO,EAAE,QAAQ;QACjB,OAAO,EAAE,EAAE,MAAM,EAAE,sBAAsB,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE;QAClF,IAAI,EAAE,qEAAqE;KAC3E;IAED,8FAA8F;IAC9F,MAAM,EAAE;QACP,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,4BAA4B;QACxC,MAAM,EAAE,2BAA2B;QACnC,OAAO,EAAE,QAAQ;QACjB,OAAO,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,kBAAkB,EAAE;QACpE,IAAI,EAAE,gDAAgD;KACtD;CACD,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,yDAAyD,CAAC;AAC1G,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,IAAY;IACxC,IAAI,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAAE,OAAO,oCAAoC,CAAC;IACjF,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;QAAE,OAAO,eAAe,CAAC;IAC1D,IAAI,IAAI,KAAK,wBAAwB;QAAE,OAAO,gBAAgB,CAAC;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;IACpF,IAAI,QAAQ;QAAE,OAAO,cAAc,QAAQ,CAAC,CAAC,CAAC,cAAc,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,OAAO,gBAAgB,CAAC;AACzB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACvC,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc;IAC7B,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;SAClE,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAChD,OAAO,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,IAAI,CAAC;AAC9C,CAAC;AAED,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/qwen-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Explicit context-cache markers for the qwen dialect (H4 follow-up).
+ *
+ * DashScope's cache is per-model: qwen3.8-max caches implicitly, but the flash
+ * tier caches ONLY when the request carries explicit Anthropic-style
+ * `cache_control: {type:'ephemeral'}` markers on CONTENT BLOCKS — verified
+ * against the token-plan gateway 2026-08-15: block-level markers cache ~99% of
+ * the prefix (creation billed at 125%, hits at 10%, 5-minute TTL, ≥1024-token
+ * blocks, max 4 markers/request); message-level markers are silently ignored,
+ * and `@ai-sdk/openai-compatible` can only emit message-level ones. So the
+ * markers are injected here, at the wire: a fetch wrapper rewrites each
+ * chat/completions body just-in-time.
+ *
+ * Placement is the same strategy `withMovingBreakpoint` runs for Claude —
+ * system prefix + the request's last message — and because the rewrite is
+ * stateless per request, the "moving" part comes free: each step marks its own
+ * tail, and the previous step's mark simply never existed on the wire again.
+ * Explicit markers are sent to ALL qwen models (max included): explicit read
+ * price (10%) undercuts the implicit discount, and the behavior is
+ * deterministic instead of best-effort.
+ *
+ * Worker-safe on purpose: both provider hosts (providers.ts, the node CLI, and
+ * providers-worker.ts, the hosted agent) wire this into `createOpenAICompatible`.
+ */
+/**
+ * The body transform: marker on each system message (the cross-turn-stable
+ * prefix — the only part reusable between turns) and on the last markable
+ * message (the within-turn moving breakpoint — each tool-loop step re-reads
+ * everything before its own tail from cache). Non-chat bodies pass through
+ * untouched.
+ */
+export declare function withQwenCacheMarkers(body: unknown): unknown;
+type FetchLike = typeof globalThis.fetch;
+/**
+ * Fetch wrapper for the qwen provider: rewrites POST chat/completions bodies
+ * through `withQwenCacheMarkers`. Anything unexpected — non-chat URL, a
+ * Request-object body, unparseable JSON — passes through unchanged: a request
+ * without markers is merely uncached, never broken.
+ */
+export declare function qwenCacheFetch(inner?: FetchLike): FetchLike;
+export {};
+//# sourceMappingURL=qwen-cache.d.ts.map

package/dist/qwen-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qwen-cache.d.ts","sourceRoot":"","sources":["../src/qwen-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAsCH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CA+B3D;AAED,KAAK,SAAS,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAuB3D"}