@genesislcap/foundation-ai 14.494.0 → 14.496.0

package/dist/esm/ai-provider.js

@@ -1,5 +1,4 @@
 import { __awaiter } from "tslib";
-import { DI, Registration } from '@microsoft/fast-foundation';
 import { AnthropicProvider } from './providers/anthropic-provider';
 import { ChromeProvider } from './providers/chrome-provider';
 import { DefaultAIProvider } from './providers/default-provider';
@@ -300,85 +299,3 @@ export class MutableAIProviderRegistry {
             listener();
     }
 }
-/**
- * The DI token for the {@link (AIProviderRegistry:interface)}. When no host
- * registers a concrete registry, the container resolves the built-in empty
- * registry (a single no-op provider) so consumers degrade to inert rather
- * than throwing.
- *
- * Prefer the {@link registerAIProviders} helper over registering this token
- * directly.
- *
- * @beta
- */
-export const AIProviderRegistry = DI.createInterface((x) => x.singleton(EmptyAIProviderRegistry));
-/**
- * Registers one or more named AI providers as an {@link (AIProviderRegistry:interface)}
- * on the given DI container.
- *
- * @remarks
- * - With a single provider, the default is inferred — `options.default` may be omitted.
- * - With multiple providers, `options.default` is required to avoid implicit ordering.
- * - Throws when `providers` is empty, when the named default isn't present, or
- *   when multiple providers are passed without an explicit default.
- *
- * @example
- * ```ts
- * // Single provider — default inferred
- * registerAIProviders(container, { openai: createAIProvider(openAiConfig) });
- *
- * // Multiple providers — explicit default
- * registerAIProviders(
- *   container,
- *   { fast: chromeProvider, deep: anthropicProvider },
- *   { default: 'deep' },
- * );
- * ```
- *
- * @returns the constructed {@link MutableAIProviderRegistry}, so a host that
- *   wants to switch providers at runtime can keep the handle and call
- *   {@link MutableAIProviderRegistry.set | set} /
- *   {@link MutableAIProviderRegistry.setDefault | setDefault} /
- *   {@link MutableAIProviderRegistry.update | update} on it later. Callers that
- *   register once and never switch can ignore the return value.
- *
- * @beta
- */
-export function registerAIProviders(container, providers, options = {}) {
-    const entries = Object.entries(providers);
-    if (entries.length === 0) {
-        throw new Error('registerAIProviders: at least one provider is required.');
-    }
-    let defaultName;
-    if (options.default !== undefined) {
-        if (!Object.prototype.hasOwnProperty.call(providers, options.default)) {
-            throw new Error(`registerAIProviders: default "${options.default}" is not one of the registered providers (${entries.map(([k]) => k).join(', ')}).`);
-        }
-        defaultName = options.default;
-    }
-    else if (entries.length === 1) {
-        defaultName = entries[0][0];
-    }
-    else {
-        throw new Error(`registerAIProviders: multiple providers registered (${entries.map(([k]) => k).join(', ')}) — must specify { default } to disambiguate.`);
-    }
-    const registry = new MutableAIProviderRegistry(new Map(entries), defaultName);
-    registerAIProviderRegistry(container, registry);
-    return registry;
-}
-/**
- * Registers a host-supplied {@link (AIProviderRegistry:interface)} instance on
- * the DI container under the {@link (AIProviderRegistry:variable)} token.
- *
- * @remarks
- * A thin wrapper over FAST's `Registration.instance` so a host can register its
- * own pre-built registry — typically a {@link MutableAIProviderRegistry} it
- * owns and mutates for runtime provider switching — **without importing FAST
- * primitives** itself. {@link registerAIProviders} delegates to this; reach for
- * it directly when you construct the registry yourself.
- *
- * @beta
- */
-export function registerAIProviderRegistry(container, registry) {
-    container.register(Registration.instance(AIProviderRegistry, registry));
-}

package/dist/esm/index.js

@@ -1,4 +1,9 @@
-export { AIProviderRegistry, createAIProvider, isObservableAIProviderRegistry, MutableAIProviderRegistry, registerAIProviderRegistry, registerAIProviders, resolveAIConfig, } from './ai-provider';
+export { createAIProvider, isObservableAIProviderRegistry, MutableAIProviderRegistry, resolveAIConfig, } from './ai-provider';
+// FAST DI wiring lives in its own module so `@microsoft/fast-foundation` (→ `fast-element`, which
+// touches `document` at eval) is only pulled when a host actually uses the container. Keeps the
+// registry/driver path loadable in bare Node. `AIProviderRegistry` carries both the interface
+// (type) and the DI token (value) — both merged in `ai-provider-di.ts`. See `ai-provider-di.ts`.
+export { AIProviderRegistry, registerAIProviderRegistry, registerAIProviders, } from './ai-provider-di';
 export { AnthropicProvider } from './providers/anthropic-provider';
 export { GeminiProvider } from './providers/gemini-provider';
 export { AnthropicTransport, ResponseTruncatedError } from './transports/anthropic-transport';

package/dist/esm/transports/anthropic-transport.js

@@ -30,6 +30,8 @@ function toAnthropicToolChoice(choice) {
  * Source: https://docs.claude.com/en/docs/about-claude/models/overview
  */
 const ANTHROPIC_CONTEXT_LIMITS = {
+    'claude-fable-5': 1000000,
+    'claude-opus-4-8': 1000000,
     'claude-opus-4-7': 1000000,
     'claude-sonnet-5': 1000000,
     'claude-sonnet-4-6': 1000000,
@@ -41,6 +43,8 @@ const ANTHROPIC_CONTEXT_LIMITS = {
  * and surfaces the `input` field as the structured response.
  */
 const STRUCTURED_OUTPUT_TOOL_NAME = 'emit_structured_response';
+/** Beta flag enabling the server-side `fallbacks` request parameter (refusal rescue). */
+const SERVER_SIDE_FALLBACK_BETA = 'server-side-fallback-2026-06-01';
 function assertSupportedAnthropicModel(model) {
     if (!SUPPORTED_ANTHROPIC_MODEL_IDS.includes(model)) {
         throw new Error(`AnthropicTransport: unsupported model "${model}". Use one of: ${SUPPORTED_ANTHROPIC_MODEL_IDS.join(', ')}.`);
@@ -53,36 +57,60 @@ function estimatedAnthropicRatesUsdPerMillion(model) {
     if (model === 'claude-haiku-4-5-20251001') {
         return { promptPerMillion: 1, candidatePerMillion: 5 };
     }
+    // Fable 5 — Anthropic's most capable widely-released model; priced above Opus tier.
+    if (model === 'claude-fable-5') {
+        return { promptPerMillion: 10, candidatePerMillion: 50 };
+    }
     // Sonnet 5 and Sonnet 4.6 share the standard Sonnet tier ($3 / $15 per MTok). Sonnet 5's
     // introductory rate ($2 / $10 through 2026-08-31) is deliberately NOT used here — standard rates.
     if (model === 'claude-sonnet-5' || model === 'claude-sonnet-4-6') {
         return { promptPerMillion: 3, candidatePerMillion: 15 };
     }
-    // Opus 4.7
+    // Opus 4.7 / 4.8 — same $5 / $25 per MTok.
     return { promptPerMillion: 5, candidatePerMillion: 25 };
 }
 /**
  * Models that reject non-default sampling parameters (`temperature`/`top_p`/`top_k`) with a 400 —
- * the Opus 4.7+ generation. Sonnet 4.6 and Haiku 4.5 still accept them.
+ * the Opus 4.7+ / Sonnet 5 / Fable 5 generation. Sonnet 4.6 and Haiku 4.5 still accept them.
  */
 function rejectsSamplingParams(model) {
-    return model === 'claude-opus-4-7' || model === 'claude-sonnet-5';
+    return (model === 'claude-fable-5' ||
+        model === 'claude-opus-4-8' ||
+        model === 'claude-opus-4-7' ||
+        model === 'claude-sonnet-5');
+}
+/**
+ * Whether the model enforces structured output natively via decode-time `output_config.format`
+ * (json_schema). True for Fable 5, Opus 4.8, Sonnet 5, and Haiku 4.5; false for Opus 4.7 and
+ * Sonnet 4.6, which fall back to the forced-tool approach on the one-shot path. `output_config`
+ * composes with a live `tools` array, so no tool-vs-schema gating is needed on this provider.
+ */
+function supportsNativeStructuredOutput(model) {
+    return (model === 'claude-fable-5' ||
+        model === 'claude-opus-4-8' ||
+        model === 'claude-sonnet-5' ||
+        model === 'claude-haiku-4-5-20251001');
 }
 /**
- * Extended-thinking posture for a request. Sonnet 5 always runs adaptive thinking with
+ * Extended-thinking posture for a request. Sonnet 5 and Fable 5 run adaptive thinking with
  * `display:'summarized'` — regardless of `tool_choice`. First-party has no forced-tool-vs-thinking
  * restriction (that's Bedrock-only), and "adaptive" self-regulates (the model thinks little on
  * trivial/mechanical turns on its own), so there is no reason to special-case forced tool calls.
  * `display:'summarized'` means the reasoning summary is always returned (billed regardless; the
  * host's toggle decides visibility).
  *
- * Every other model returns undefined → `thinking` is omitted → it runs WITHOUT thinking on the
- * chat path. So the older "forced tool + thinking is incompatible" restriction never applies to
- * them (you can't hit it when thinking is off). If thinking is ever enabled for a non-Sonnet-5
- * model, revisit the forced-tool interaction for that model then.
+ * Fable 5 runs thinking *unconditionally* (it cannot be disabled — an explicit
+ * `{type:'disabled'}` is a 400), so it must never be sent `disabled`; `{type:'adaptive'}`
+ * is the accepted posture and is what we return.
+ *
+ * Every other model (Opus 4.8/4.7, Sonnet 4.6, Haiku) returns undefined → `thinking` is omitted
+ * → it runs WITHOUT thinking on the chat path (Opus 4.8 adaptive thinking is opt-in). So the older
+ * "forced tool + thinking is incompatible" restriction never applies to them (you can't hit it when
+ * thinking is off). If thinking is ever enabled for one of those, revisit the forced-tool
+ * interaction for that model then.
  */
 function anthropicThinking(model) {
-    if (model !== 'claude-sonnet-5')
+    if (model !== 'claude-sonnet-5' && model !== 'claude-fable-5')
         return undefined;
     return { type: 'adaptive', display: 'summarized' };
 }
@@ -178,8 +206,11 @@ export class AnthropicTransport {
         else if (model === 'claude-sonnet-4-6') {
             logger.warn('AnthropicTransport: using claude-sonnet-4-6 — higher cost than Haiku; use for stronger reasoning or agent tasks.');
         }
-        else if (model === 'claude-opus-4-7') {
-            logger.warn('AnthropicTransport: using claude-opus-4-7 — significantly higher cost; reserve for tasks where Sonnet reliability is insufficient.');
+        else if (model === 'claude-opus-4-7' || model === 'claude-opus-4-8') {
+            logger.warn(`AnthropicTransport: using ${model} — significantly higher cost; reserve for tasks where Sonnet reliability is insufficient.`);
+        }
+        else if (model === 'claude-fable-5') {
+            logger.warn('AnthropicTransport: using claude-fable-5 — Anthropic\'s most capable model, priced above Opus tier ($10 / $50 per MTok) with thinking always on. Reserve for the hardest reasoning/long-horizon work. Requires ≥30-day data retention (unavailable under ZDR) and may return stop_reason "refusal"; pair with an Opus 4.8 fallback.');
         }
         this.timeout = (_b = config.timeout) !== null && _b !== void 0 ? _b : DEFAULT_TIMEOUT;
         this.stallTimeout = (_c = config.stallTimeout) !== null && _c !== void 0 ? _c : DEFAULT_STALL_TIMEOUT;
@@ -213,19 +244,6 @@ export class AnthropicTransport {
             var _a, _b, _c;
             const { systemPrompt, userPrompt, responseSchema } = options;
             const messages = [{ role: 'user', content: userPrompt }];
-            // Anthropic has no native JSON-schema response format. The supported pattern
-            // is to define a tool whose input_schema is the desired schema, then force
-            // the model to call it via tool_choice. The tool's `input` is the structured
-            // payload we surface back to the caller as a JSON string.
-            const tools = responseSchema
-                ? [
-                    {
-                        name: STRUCTURED_OUTPUT_TOOL_NAME,
-                        description: 'Emit the structured response that matches the required schema.',
-                        input_schema: responseSchema,
-                    },
-                ]
-                : undefined;
             const body = {
                 model: this.model,
                 max_tokens: this.maxTokens,
@@ -233,19 +251,38 @@ export class AnthropicTransport {
             };
             if (systemPrompt)
                 body.system = systemPrompt;
-            if (tools) {
-                body.tools = tools;
+            // Prefer native decode-time enforcement (`output_config.format`) where the model supports it —
+            // the answer comes back as ordinary text conforming to the schema. On models without native
+            // support (Opus 4.7, Sonnet 4.6), fall back to the legacy pattern: a tool whose `input_schema`
+            // is the schema, forced via `tool_choice`, with the structured payload read from its `tool_use`.
+            const useNative = responseSchema != null && supportsNativeStructuredOutput(this.model);
+            const useForcedTool = responseSchema != null && !useNative;
+            if (useNative) {
+                body.output_config = {
+                    format: { type: 'json_schema', schema: responseSchema },
+                };
+            }
+            else if (useForcedTool) {
+                body.tools = [
+                    {
+                        name: STRUCTURED_OUTPUT_TOOL_NAME,
+                        description: 'Emit the structured response that matches the required schema.',
+                        input_schema: responseSchema,
+                    },
+                ];
                 body.tool_choice = { type: 'tool', name: STRUCTURED_OUTPUT_TOOL_NAME };
             }
-            // Sonnet 5 runs adaptive thinking by default; disable it for structured/one-shot prompts — the
-            // reasoning would be billed but discarded (only text / the forced tool_use block is read back).
+            // Sonnet 5 runs adaptive thinking by default; disable it for one-shot prompts — the reasoning
+            // would be billed but discarded. Fable 5 runs thinking unconditionally (cannot be disabled — a
+            // 400), so it is left on; its summary is simply unused here.
             if (this.model === 'claude-sonnet-5')
                 body.thinking = { type: 'disabled' };
             const response = yield this.post(body);
-            if (responseSchema) {
+            if (useForcedTool) {
                 const toolUse = ((_a = response.content) !== null && _a !== void 0 ? _a : []).find((b) => b.type === 'tool_use' && b.name === STRUCTURED_OUTPUT_TOOL_NAME);
                 return toolUse ? JSON.stringify((_b = toolUse.input) !== null && _b !== void 0 ? _b : {}) : '';
             }
+            // Native structured output and plain prompts both return the answer as text.
             return ((_c = response.content) !== null && _c !== void 0 ? _c : [])
                 .filter((b) => b.type === 'text')
                 .map((b) => b.text)
@@ -255,7 +292,7 @@ export class AnthropicTransport {
     // ── ChatTransport (multi-turn chat) ────────────────────────────────────
     sendChatMessage(history, userMessage, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a, _b, _c;
             const messages = this.toAnthropicMessages(history, userMessage, options === null || options === void 0 ? void 0 : options.attachments);
             const body = {
                 model: this.model,
@@ -294,6 +331,22 @@ export class AnthropicTransport {
                     maxTemp: ANTHROPIC_MAX_TEMPERATURE,
                 });
             }
+            // Structured output: constrain the final text answer to the caller's JSON schema via
+            // decode-time `output_config.format`. Composes with a live `tools` array — the model still
+            // calls tools through the turn and conforms its closing answer to the schema. Applied only on
+            // models that support it natively; elsewhere the schema is dropped here (the caller keeps a
+            // prompt-instruction + validator fallback). No beta header needed.
+            if ((options === null || options === void 0 ? void 0 : options.responseSchema) && supportsNativeStructuredOutput(this.model)) {
+                body.output_config = {
+                    format: { type: 'json_schema', schema: options.responseSchema },
+                };
+            }
+            // Refusal fallback chain (e.g. Fable 5 → Opus 4.8). Sent as the server-side `fallbacks`
+            // param; `post` adds the required beta header when this is present. A refused turn is
+            // re-run on the next model in one round trip.
+            if ((_c = options === null || options === void 0 ? void 0 : options.fallbacks) === null || _c === void 0 ? void 0 : _c.length) {
+                body.fallbacks = options.fallbacks.map((f) => f.maxTokens != null ? { model: f.model, max_tokens: f.maxTokens } : { model: f.model });
+            }
             // Place prompt-cache breakpoints per the resolved policy (no-op for `'default'`/absent).
             if (options === null || options === void 0 ? void 0 : options.cachePolicy) {
                 this.applyCacheControl(body, options.cachePolicy);
@@ -553,6 +606,14 @@ export class AnthropicTransport {
         if (response.stop_reason === 'max_tokens') {
             base.responseMeta = { finishReason: 'max_tokens' };
         }
+        // A `refusal` stop means safety classifiers declined the request (Fable 5 and other
+        // recent models). Content is empty (pre-output) or partial (mid-stream) — return it
+        // rather than crash on an assumed non-empty block, and flag the reason so the driver
+        // (or a server-side `fallbacks` chain) can respond deterministically instead of
+        // retrying into the same wall. Usage/cost is already logged above.
+        if (response.stop_reason === 'refusal') {
+            base.responseMeta = { finishReason: 'refusal' };
+        }
         return base;
     }
     buildEndpoint() {
@@ -584,10 +645,17 @@ export class AnthropicTransport {
     }
     post(body, signal) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             const { url, headers, credentials } = this.buildEndpoint();
+            // The server-side `fallbacks` param is gated behind a beta flag; add it per-request only
+            // when a fallback chain is set (the param without the header is a 400, and vice-versa is fine).
+            const requestHeaders = ((_a = body.fallbacks) === null || _a === void 0 ? void 0 : _a.length)
+                ? Object.assign(Object.assign({}, headers), { 'anthropic-beta': [headers['anthropic-beta'], SERVER_SIDE_FALLBACK_BETA]
+                        .filter(Boolean)
+                        .join(',') }) : headers;
             return (yield postWithRetry({
                 url,
-                headers,
+                headers: requestHeaders,
                 body,
                 credentials,
                 vendorLabel: 'Anthropic',

package/dist/esm/transports/gemini-transport.js

@@ -258,7 +258,18 @@ export class GeminiTransport {
             // Names of the tools offered this turn — used to validate a repaired
             // malformed call against the real tool surface before accepting it.
             const offeredToolNames = new Set(((_b = options === null || options === void 0 ? void 0 : options.tools) !== null && _b !== void 0 ? _b : []).map((t) => t.name));
-            const response = yield this.post({ model: this.model, contents, tools, systemInstruction, toolConfig, generationConfig }, options === null || options === void 0 ? void 0 : options.signal);
+            // Structured output (native JSON mode). Gemini 3 can combine it with function calling;
+            // Gemini 2.x cannot, so on 2.x apply the schema only on a pure structured turn (no tools) and
+            // otherwise drop it (the caller keeps a prompt-instruction + validator fallback). Passed as a
+            // top-level `responseSchema` that `toDirectPayload` maps to `generationConfig.responseMimeType`
+            // + `responseSchema` on the direct path (the proxy forwards it).
+            const schemaCoexistsWithTools = this.model.startsWith('gemini-3');
+            const applyResponseSchema = (options === null || options === void 0 ? void 0 : options.responseSchema) != null && (!tools || schemaCoexistsWithTools);
+            const response = yield this.post(Object.assign({ model: this.model, contents,
+                tools,
+                systemInstruction,
+                toolConfig,
+                generationConfig }, (applyResponseSchema ? { responseSchema: options.responseSchema } : {})), options === null || options === void 0 ? void 0 : options.signal);
             return this.fromGeminiResponse(response, offeredToolNames);
         });
     }

package/dist/esm/types/config.types.js

@@ -9,6 +9,8 @@ export const SUPPORTED_GEMINI_MODEL_IDS = [
 ];
 /** @beta */
 export const SUPPORTED_ANTHROPIC_MODEL_IDS = [
+    'claude-fable-5',
+    'claude-opus-4-8',
     'claude-opus-4-7',
     'claude-sonnet-5',
     'claude-sonnet-4-6',

package/dist/foundation-ai.api.json

@@ -719,7 +719,7 @@
               "text": "export interface AIProviderRegistry "
             }
           ],
-          "fileUrlPath": "src/ai-provider.ts",
+          "fileUrlPath": "src/ai-provider-di.ts",
           "releaseTag": "Beta",
           "name": "AIProviderRegistry",
           "preserveMemberOrder": false,
@@ -995,7 +995,7 @@
               "text": ">"
             }
           ],
-          "fileUrlPath": "src/ai-provider.ts",
+          "fileUrlPath": "src/ai-provider-di.ts",
           "isReadonly": true,
           "releaseTag": "Beta",
           "name": "AIProviderRegistry",
@@ -1441,7 +1441,7 @@
             },
             {
               "kind": "Content",
-              "text": "'claude-opus-4-7' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001'"
+              "text": "'claude-fable-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001'"
             },
             {
               "kind": "Content",
@@ -3138,7 +3138,16 @@
             },
             {
               "kind": "Content",
-              "text": "{\n    reason: 'done';\n} | {\n    reason: 'agent-handoff';\n    summary: string;\n    remainingTask: string;\n}"
+              "text": "{\n    reason: 'done';\n    failureReason?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "TurnFailureReason",
+              "canonicalReference": "@genesislcap/foundation-ai!TurnFailureReason:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n} | {\n    reason: 'agent-handoff';\n    summary: string;\n    remainingTask: string;\n}"
             },
             {
               "kind": "Content",
@@ -3150,9 +3159,81 @@
           "name": "ChatDriverResult",
           "typeTokenRange": {
             "startIndex": 1,
-            "endIndex": 2
+            "endIndex": 4
           }
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/foundation-ai!ChatFallback:interface",
+          "docComment": "/**\n * One entry in a {@link ChatRequestOptions.fallbacks} chain.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface ChatFallback "
+            }
+          ],
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Beta",
+          "name": "ChatFallback",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatFallback#maxTokens:member",
+              "docComment": "/**\n * Optional per-hop `max_tokens` cap for this fallback attempt.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "maxTokens?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "maxTokens",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatFallback#model:member",
+              "docComment": "/**\n * Model id to fall back to (e.g. `'claude-opus-4-8'`).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "model: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "model",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!ChatInputDuringExecutionMode:type",
@@ -4014,6 +4095,65 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#fallbacks:member",
+              "docComment": "/**\n * Provider-neutral refusal-fallback chain: if the model declines the request (`stop_reason: 'refusal'`, e.g. Fable 5 safety classifiers), the provider re-runs the same request on the next listed model and returns its answer. Ordered most- to least-preferred; each entry may cap its own `maxTokens`. Providers that support it apply it server-side (Anthropic: `fallbacks` + the `server-side-fallback` beta); others ignore it. Typical use: Fable 5 with an Opus 4.8 fallback.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "fallbacks?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatFallback",
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatFallback:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "fallbacks",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#responseSchema:member",
+              "docComment": "/**\n * Structured-output schema (JSON Schema) for this turn. When set, the model's final (non-tool) answer is constrained to it instead of free text. Composes with `tools` — the model may still call tools this turn, then conform its closing answer to the schema. Providers apply it natively where the model supports it (Anthropic `output_config.format`, Gemini JSON mode) and drop it otherwise (caller keeps a prompt-instruction + validator fallback). Keep to the portable JSON-Schema subset providers share (`additionalProperties: false`, explicit `required`, enums, `anyOf` for nullables — no numeric/string constraints or recursion).\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "responseSchema?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "object"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "responseSchema",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/foundation-ai!ChatRequestOptions#signal:member",
@@ -8669,7 +8809,7 @@
               "text": ";"
             }
           ],
-          "fileUrlPath": "src/ai-provider.ts",
+          "fileUrlPath": "src/ai-provider-di.ts",
           "returnTypeTokenRange": {
             "startIndex": 5,
             "endIndex": 6
@@ -8755,7 +8895,7 @@
               "text": ";"
             }
           ],
-          "fileUrlPath": "src/ai-provider.ts",
+          "fileUrlPath": "src/ai-provider-di.ts",
           "returnTypeTokenRange": {
             "startIndex": 10,
             "endIndex": 11
@@ -8800,7 +8940,7 @@
               "text": "export interface RegisterAIProvidersOptions "
             }
           ],
-          "fileUrlPath": "src/ai-provider.ts",
+          "fileUrlPath": "src/ai-provider-di.ts",
           "releaseTag": "Beta",
           "name": "RegisterAIProvidersOptions",
           "preserveMemberOrder": false,
@@ -9597,6 +9737,32 @@
             "startIndex": 1,
             "endIndex": 4
           }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!TurnFailureReason:type",
+          "docComment": "/**\n * Why a driver turn ended in failure — the typed taxonomy the tool loop already records onto its debug-log timeline (`turn.error` / `turn.retry` details), surfaced here so callers of a turn can read the outcome structurally instead of scraping prose. Distinct from {@link SubAgentFailureReason} (underscored, its own `timeout` member) because the two enums serialise into different log surfaces and READMEs; a transport request timeout on the main turn is recorded as `exception`.\n *\n * - `exception` — an uncaught error escaped the tool loop (catch-all, includes a transport request timeout). - `malformed-function-call` — the provider returned an unparseable tool call. - `empty-response` — the model returned no content and no tool calls. - `unknown-tool-limit` — the model repeatedly called tools it couldn't dispatch, whether hallucinated or stale (real earlier, retired now). - `max-iterations` — the tool loop hit its iteration cap. - `response-truncated` — a turn stopped at the provider's output-token cap with an incomplete tool call; deterministic, so it bails without retry.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type TurnFailureReason = "
+            },
+            {
+              "kind": "Content",
+              "text": "'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated'"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/types/chat.types.ts",
+          "releaseTag": "Beta",
+          "name": "TurnFailureReason",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
         }
       ]
     }