@genesislcap/foundation-ai 14.494.0 → 14.496.0

package/dist/foundation-ai.d.ts

@@ -227,7 +227,7 @@ export declare interface AnthropicAIConfig extends AIProviderConfig {
  *
  * @beta
  */
-export declare type AnthropicModelId = 'claude-opus-4-7' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001';
+export declare type AnthropicModelId = 'claude-fable-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001';
 
 /**
  * Anthropic Claude AI provider. Uses {@link AnthropicTransport} to handle requests.
@@ -565,12 +565,32 @@ export declare interface ChatCostHistoryConfig {
  */
 export declare type ChatDriverResult = {
     reason: 'done';
+    /**
+     * Set when the turn ended in a typed failure rather than a clean completion
+     * (see {@link TurnFailureReason}). **Additive and optional**: the discriminant
+     * stays `'done'` for every exit — success and failure alike — so existing
+     * consumers matching on `reason === 'done'` behave identically. Absent on a
+     * successful turn, a user cancel, and a driver dispose (none are failures).
+     */
+    failureReason?: TurnFailureReason;
 } | {
     reason: 'agent-handoff';
     summary: string;
     remainingTask: string;
 };
 
+/**
+ * One entry in a {@link ChatRequestOptions.fallbacks} chain.
+ *
+ * @beta
+ */
+export declare interface ChatFallback {
+    /** Model id to fall back to (e.g. `'claude-opus-4-8'`). */
+    model: string;
+    /** Optional per-hop `max_tokens` cap for this fallback attempt. */
+    maxTokens?: number;
+}
+
 /**
  * Controls how the main chat input area behaves while an agent (or sub-agent)
  * is executing.
@@ -775,6 +795,29 @@ export declare interface ChatRequestOptions {
      * @beta
      */
     tailContext?: string;
+    /**
+     * 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.
+     *
+     * @beta
+     */
+    fallbacks?: ChatFallback[];
+    /**
+     * 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).
+     *
+     * @beta
+     */
+    responseSchema?: object;
 }
 
 /**
@@ -2096,4 +2139,26 @@ export declare const SUPPORTED_ANTHROPIC_MODEL_IDS: readonly AnthropicModelId[];
 /** @beta */
 export declare const SUPPORTED_GEMINI_MODEL_IDS: readonly GeminiModelId[];
 
+/**
+ * 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`.
+ *
+ * - `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.
+ *
+ * @beta
+ */
+export declare type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated';
+
 export { }

package/package.json

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