@genesislcap/foundation-ai 15.33.1 → 15.34.0

package/dist/foundation-ai.d.ts

@@ -64,6 +64,26 @@ export declare interface AggregateUsage {
 /** Feature flag name for AI functionality (beta). Enable via ?feature.ai in URL or GENX_ENABLE_AI env var. */
 export declare const AI_FEATURE_FLAG = "ai";
 
+/**
+ * Every tier id, in ascending capability order.
+ *
+ * This array is the source of truth and {@link AITierId} is derived from it, so the two cannot
+ * drift: a tier exists exactly when it is listed here. That matters because the provider
+ * builders and the table's tests all loop over this array — a tier missing from it would get
+ * no provider and no test, with nothing to say so.
+ *
+ * @beta
+ */
+export declare const AI_TIER_IDS: readonly ["low", "high", "reasoning"];
+
+/**
+ * Every vendor in the table — the two the platform's proxy meters. The source of truth for
+ * {@link AITierVendor}, for the same reason as {@link AI_TIER_IDS}.
+ *
+ * @beta
+ */
+export declare const AI_TIER_VENDORS: readonly ["anthropic", "gemini"];
+
 /**
  * Union type for provider-specific configs.
  * Extend when adding new providers.
@@ -229,6 +249,47 @@ export declare interface AIStatus {
     contextLimit?: number;
 }
 
+/**
+ * The tier a caller asks for, rather than a model id.
+ *
+ * Tier-shaped names are what let an app swap vendor (or re-bench a tier onto a
+ * newer model) without touching a single agent config — agents resolve `'high'`,
+ * not `claude-sonnet-5`. Derived from {@link AI_TIER_IDS}.
+ *
+ * @beta
+ */
+export declare type AITierId = (typeof AI_TIER_IDS)[number];
+
+/**
+ * Per-tier overrides, shallow-merged field by field over the defaults.
+ *
+ * @beta
+ */
+export declare interface AITierOverrides {
+    anthropic?: Partial<Record<AITierId, Partial<AnthropicTierConfig>>>;
+    gemini?: Partial<Record<AITierId, Partial<GeminiTierConfig>>>;
+}
+
+/**
+ * The whole table: every tier, for every vendor.
+ *
+ * Total records, not partials — a tier a vendor cannot serve is not a tier, it is a
+ * gap that only shows up when an agent resolves it at runtime.
+ *
+ * @beta
+ */
+export declare interface AITiers {
+    anthropic: Record<AITierId, AnthropicTierConfig>;
+    gemini: Record<AITierId, GeminiTierConfig>;
+}
+
+/**
+ * The cloud vendors the tier table covers. Derived from {@link AI_TIER_VENDORS}.
+ *
+ * @beta
+ */
+export declare type AITierVendor = (typeof AI_TIER_VENDORS)[number];
+
 /**
  * Transport interface for AI providers.
  * Each provider (OpenAI, Chrome, Anthropic) implements this to handle API-specific details.
@@ -325,6 +386,27 @@ declare interface AnthropicProviderConfig {
  */
 export declare function anthropicRatesFor(model: AnthropicModelId): TokenRates;
 
+/**
+ * What one tier is worth on Anthropic: the model, its output ceiling, and the two clocks.
+ *
+ * @beta
+ */
+export declare interface AnthropicTierConfig {
+    model: AnthropicModelId;
+    /**
+     * `max_tokens` for every request on this tier. Part of the tier, not an optional
+     * extra: Anthropic requires the field and the transport defaults it to 4096, which
+     * truncates a large single-call file write mid-stream (`stop_reason: max_tokens`)
+     * and leaves the tool input unparseable. Values sit inside each model's documented
+     * output ceiling.
+     */
+    maxTokens: number;
+    /** Inactivity window on a stream that has started. */
+    stallTimeoutMs: number;
+    /** Ceiling on the wait for the FIRST byte — a different clock from the stall one. */
+    timeoutMs: number;
+}
+
 /**
  * Cost one Anthropic request.
  *
@@ -687,6 +769,48 @@ export declare class BudgetExhaustedError extends Error {
     });
 }
 
+/**
+ * Builds one {@link AIProvider} per tier for a vendor, ready to register under the tier
+ * names agents resolve (`low` / `high` / `reasoning`).
+ *
+ * @remarks
+ * Each provider carries its tier's model, output ceiling (Anthropic) and both clocks, so no
+ * tier can silently fall back to the transport defaults — which is how a large tool write
+ * ends up truncated at 4096 tokens.
+ *
+ * @example
+ * ```ts
+ * registerAIProviders(
+ *   container,
+ *   buildTierProviders({ vendor: 'gemini', serverEndpoint: (v) => `/gwf/ai-service/${v}/chat` }),
+ *   { default: 'high' },
+ * );
+ * ```
+ *
+ * @beta
+ */
+export declare function buildTierProviders(options: BuildTierProvidersOptions): Record<AITierId, AIProvider>;
+
+/**
+ * Options for {@link buildTierProviders}.
+ *
+ * @beta
+ */
+export declare interface BuildTierProvidersOptions {
+    /** Which vendor's models to build. */
+    vendor: AITierVendor;
+    /**
+     * The proxy endpoint every tier posts to — a string, or a function of the vendor for a
+     * caller that builds more than one vendor from one rule (see the example below).
+     *
+     * Always a server endpoint, never an API key: these providers are meant for an app whose
+     * keys stay on its server. An empty endpoint throws here rather than at the first turn.
+     */
+    serverEndpoint: string | ((vendor: AITierVendor) => string);
+    /** The table to build from. Defaults to {@link DEFAULT_AI_TIERS}. */
+    tiers?: AITiers;
+}
+
 /**
  * Prompt-cache policy for a chat request, resolved per turn. **Provider-neutral intent,
  * provider-specific effect** — read this carefully, the two providers differ sharply:
@@ -2419,6 +2543,30 @@ export declare interface CriteriaInterpretContext {
     fields?: FieldLike[];
 }
 
+/**
+ * The platform's default tier table.
+ *
+ * @remarks
+ * Frozen, because it is shared by every app in the process: {@link resolveAITiers} returns
+ * a fresh object for callers that override, and hands this back untouched for callers that
+ * do not.
+ *
+ * The models are the ones Genesis Create has been running these tiers on in production — except
+ * Anthropic's `reasoning`, moved to `claude-opus-4-8` (see its entry) — and they are a
+ * **benchmark result, not a preference**: re-bench before moving one. Two of the Gemini
+ * defaults carry a caveat recorded beside them, a preview model and an introductory rate. Two dates
+ * are already on the calendar for that: `gemini-3.8-flash` sits on an introductory rate that
+ * doubles on 2027-01-01 (at which point it is dearer on input than the model it replaced),
+ * and `token-cost.test.ts` fails the build that day; `ai-tiers.test.ts` fails alongside it
+ * saying the High tier is the thing to re-bench.
+ *
+ * Every model here must be in `SUPPORTED_*_MODEL_IDS` with a context limit and a price —
+ * pinned by tests, because an unpriced model silently bills at nothing.
+ *
+ * @beta
+ */
+export declare const DEFAULT_AI_TIERS: AITiers;
+
 /**
  * The single copy shown to a user whose AI budget is gone — the transcript bubble
  * the chat driver appends, and the default text of the assistant's blocked banner.
@@ -2573,6 +2721,22 @@ declare interface GeminiProviderConfig {
  */
 export declare function geminiRatesFor(model: GeminiModelId, promptTokens: number): TokenRates;
 
+/**
+ * What one tier is worth on Gemini.
+ *
+ * No `maxTokens`: `GeminiAIConfig` has no such field and the provider's own (much
+ * larger) default applies, so Gemini writes never hit the Anthropic wall above.
+ *
+ * @beta
+ */
+export declare interface GeminiTierConfig {
+    model: GeminiModelId;
+    /** Inactivity window on a stream that has started. */
+    stallTimeoutMs: number;
+    /** Ceiling on the wait for the FIRST byte — a different clock from the stall one. */
+    timeoutMs: number;
+}
+
 /**
  * Cost one Gemini request.
  *
@@ -3234,6 +3398,33 @@ export declare interface ResolveAIConfigOptions {
     preferChrome?: boolean;
 }
 
+/**
+ * The table an app should actually use: {@link DEFAULT_AI_TIERS} with `overrides` applied
+ * per field, so an app that wants one model moved says only that and keeps the platform's
+ * clocks and ceilings.
+ *
+ * @remarks
+ * An override field set to `undefined` is skipped, exactly as if it had been left out. The
+ * common caller passes an optional config value straight through
+ * (`{ high: { model: appConfig.model } }`), and copying `undefined` over the default would
+ * hand the transport no model at all — it then quietly falls back to its own default, with
+ * nothing logged.
+ *
+ * The result is frozen whether or not anything was overridden, so whether mutating it throws
+ * does not depend on what the caller passed. The default itself is returned untouched when
+ * there is nothing to override, and is never mutated, which matters because it is shared
+ * across every app in the process.
+ *
+ * @example
+ * ```ts
+ * // Keep everything, but run the reasoning tier on Fable.
+ * const tiers = resolveAITiers({ anthropic: { reasoning: { model: 'claude-fable-5' } } });
+ * ```
+ *
+ * @beta
+ */
+export declare function resolveAITiers(overrides?: AITierOverrides): AITiers;
+
 /**
  * Thrown when a response was cut off at the output-token limit (Anthropic
  * `stop_reason: 'max_tokens'`, Gemini `finishReason: 'MAX_TOKENS'`) in a way

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-ai",
   "description": "Genesis Foundation AI - Provider-agnostic AI configuration and shared utilities",
-  "version": "15.33.1",
+  "version": "15.34.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -52,17 +52,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.33.1",
-    "@genesislcap/genx": "15.33.1",
-    "@genesislcap/rollup-builder": "15.33.1",
-    "@genesislcap/ts-builder": "15.33.1",
-    "@genesislcap/uvu-playwright-builder": "15.33.1",
-    "@genesislcap/vite-builder": "15.33.1",
-    "@genesislcap/webpack-builder": "15.33.1"
+    "@genesislcap/foundation-testing": "15.34.0",
+    "@genesislcap/genx": "15.34.0",
+    "@genesislcap/rollup-builder": "15.34.0",
+    "@genesislcap/ts-builder": "15.34.0",
+    "@genesislcap/uvu-playwright-builder": "15.34.0",
+    "@genesislcap/vite-builder": "15.34.0",
+    "@genesislcap/webpack-builder": "15.34.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "15.33.1",
-    "@genesislcap/foundation-utils": "15.33.1",
+    "@genesislcap/foundation-logger": "15.34.0",
+    "@genesislcap/foundation-utils": "15.34.0",
     "@microsoft/fast-foundation": "2.50.0"
   },
   "repository": {