@genesislcap/foundation-ai 14.454.2 → 14.455.1

package/dist/foundation-ai.d.ts

@@ -512,6 +512,15 @@ export declare interface ChatMessage {
      * cost without re-deriving rates.
      */
     cost?: number;
+    /**
+     * Provider diagnostic for the request that produced this message — the raw
+     * finish reason plus, where the provider reports them, the reasoning-token
+     * count and a parts breakdown. Set by transports that expose it (Gemini); the
+     * driver folds it into the debug-log meta events (e.g. an empty-response
+     * `turn.retry`/`turn.error`) so a blank or truncated turn's cause is legible.
+     * Not shown to the user.
+     */
+    responseMeta?: ChatResponseMeta;
 }
 
 /**
@@ -525,19 +534,59 @@ export declare interface ChatRequestOptions {
     attachments?: ChatAttachment[];
     signal?: AbortSignal;
     /**
-     * Whether the model MAY call a tool (`'auto'`, the default when omitted) or
-     * MUST call one (`'required'`). `'required'` maps to Anthropic
-     * `tool_choice: { type: 'any' }` and Gemini
-     * `functionCallingConfig.mode: 'ANY'`. Used by sub-agent loops so a sub-agent
-     * can only end a turn by calling a tool (e.g. its completion tool), never by
-     * emitting a free-text answer.
+     * Whether (and how) the model may call a tool this turn. Defaults to `'auto'`
+     * when omitted. Used by sub-agent loops (which force `'required'` so a turn
+     * can only end via a tool call) and configurable per agent / per agent state.
+     * See {@link ChatToolChoice}.
      *
-     * NOTE: `'required'` is incompatible with Anthropic extended/adaptive
-     * thinking — a request must not enable both.
+     * @beta
+     */
+    toolChoice?: ChatToolChoice;
+    /**
+     * Provider-agnostic sampling temperature, normalized to `0`–`1` and anchored
+     * on each provider's own default: `0` is fully deterministic, `0.5` is the
+     * provider's default, and `1` is the most random it allows. So `< 0.5` is
+     * "more focused than default" and `> 0.5` is "more random than default" on
+     * every provider, even though their native ranges differ (Anthropic
+     * `temperature` `0`–`1`, Gemini `generationConfig.temperature` `0`–`2`). Where
+     * a provider's default equals its max (Anthropic), the upper half is flat.
+     * Values outside `0`–`1` are clamped. Omit to use the provider/model default
+     * (equivalent to `0.5`). Prefer the `ChatTemperature` presets for common
+     * intents.
      *
      * @beta
      */
-    toolChoice?: 'auto' | 'required';
+    temperature?: number;
+}
+
+/**
+ * Provider-reported diagnostic for a single chat response, surfaced so the
+ * driver can attribute a blank/abnormal turn without re-deriving it. All fields
+ * are optional — a transport sets only what its provider reports.
+ *
+ * @beta
+ */
+export declare interface ChatResponseMeta {
+    /**
+     * Raw provider finish reason for the turn, verbatim — e.g. Gemini `'STOP'` |
+     * `'MAX_TOKENS'` | `'SAFETY'` | `'RECITATION'`. The key signal when triaging a
+     * blank or truncated turn.
+     */
+    finishReason?: string;
+    /**
+     * Reasoning ("thinking") tokens billed for this turn, when the provider
+     * reports them (Gemini 2.5). A high count alongside ~0 output tokens and a
+     * `'STOP'` finish is the "thought, then stopped without answering" signature.
+     */
+    thoughtsTokens?: number;
+    /** Count of response parts by kind — distinguishes a truly empty turn from a thinking-only one. */
+    parts?: {
+        functionCall: number;
+        thought: number;
+        text: number;
+    };
+    /** Provider block reason when the prompt/response was blocked rather than generated. */
+    blockReason?: string;
 }
 
 /**
@@ -588,6 +637,33 @@ export declare type ChatSuggestionsConfig = {
     prompt?: string;
 };
 
+/**
+ * Provider-agnostic, normalized sampling-temperature presets in `0`–`1` space —
+ * named handles for the values most callers actually want, so intent reads
+ * better than a bare magnitude. Each maps through `scaleTemperature` to the
+ * active provider's native range, so the same preset means the same intent
+ * whichever provider services the turn:
+ *
+ * - `ChatTemperature.Deterministic` (`0`) — greedy/argmax sampling.
+ * - `ChatTemperature.Focused` (`0.25`) — low but not greedy; precise tool calls
+ *   and extraction work where you still want a little slack.
+ * - `ChatTemperature.Balanced` (`0.5`) — the provider's own default.
+ * - `ChatTemperature.Creative` (`0.75`) — hotter than default, short of the ceiling.
+ * - `ChatTemperature.Maximum` (`1`) — the hottest the active provider allows.
+ *
+ * (On a provider whose default equals its max — Anthropic — `Creative` and
+ * `Maximum` coincide; see `scaleTemperature`.)
+ *
+ * @beta
+ */
+export declare const ChatTemperature: {
+    readonly Deterministic: 0;
+    readonly Focused: 0.25;
+    readonly Balanced: 0.5;
+    readonly Creative: 0.75;
+    readonly Maximum: 1;
+};
+
 /**
  * A tool call requested by the assistant.
  *
@@ -644,6 +720,37 @@ export declare type ChatToolCallUnknown = ChatToolCallBase & {
     stale?: boolean;
 };
 
+/**
+ * Controls whether (and how) the model may call a tool on a given turn. Maps to
+ * each provider's "tool choice" / "function calling mode" control:
+ *
+ * - `'auto'` (the default when omitted) — the model decides whether to call a
+ *   tool or answer with text. Anthropic leaves `tool_choice` unset; Gemini
+ *   leaves `functionCallingConfig` unset (`AUTO`).
+ * - `'required'` — the model MUST call one of the available tools. Maps to
+ *   Anthropic `tool_choice: { type: 'any' }` and Gemini
+ *   `functionCallingConfig.mode: 'ANY'`.
+ * - `'none'` — the model MUST NOT call a tool (text answer only). Maps to
+ *   Anthropic `tool_choice: { type: 'none' }` and Gemini
+ *   `functionCallingConfig.mode: 'NONE'`.
+ * - `{ tool: name }` — the model MUST call exactly the named tool. Maps to
+ *   Anthropic `tool_choice: { type: 'tool', name }` and Gemini
+ *   `functionCallingConfig.mode: 'ANY', allowedFunctionNames: [name]`. Use this
+ *   for surgical forcing at a single-tool juncture (e.g. force a classifier
+ *   tool in an intake step) while leaving `'auto'` everywhere multi-step work
+ *   happens.
+ *
+ * Forcing (`'required'` / `{ tool }`) is a no-op when no tools are advertised.
+ *
+ * NOTE: forcing is incompatible with Anthropic extended/adaptive thinking — a
+ * request must not enable both.
+ *
+ * @beta
+ */
+export declare type ChatToolChoice = 'auto' | 'required' | 'none' | {
+    tool: string;
+};
+
 /**
  * JSON Schema-based tool definition for function calling.
  *
@@ -1019,6 +1126,16 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
     private logTokenUsage;
     private toGeminiContents;
     private fromGeminiResponse;
+    /**
+     * Log the full shape of a blank or non-STOP response so its cause is legible
+     * without re-deriving it: a thinking-only STOP (substantial `thoughtsTokenCount`,
+     * ~0 `candidatesTokenCount`) vs a content block (`SAFETY` / `RECITATION`) vs a
+     * token cap (`MAX_TOKENS`) vs a prompt-level block (top-level
+     * `promptFeedback.blockReason`). On 2.5 Pro — which always thinks — a blank
+     * STOP carrying substantial thought tokens is the "thought, then stopped
+     * without answering" signature.
+     */
+    private logAbnormalResponse;
     private buildEndpoint;
     private static readonly MAX_RETRIES;
     private static readonly RATE_LIMIT_STATUS;

package/package.json

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