smoltalk 0.8.1 → 0.8.3

package/README.md

@@ -57,7 +57,9 @@ This is functionality that other packages allow.
       totalCost: 0.00026,
       currency: 'USD'
     },
-    model: 'gpt-5.4'
+    model: 'gpt-5.4',
+    stopReason: 'stop',
+    rawStopReason: 'stop'
   }
 }
 ```
@@ -152,6 +154,49 @@ A couple of design decisions to note:
 - The schema for tools and structured outputs is defined using Zod.
 - Parameter names are camel case, as that is the naming convention in TypeScript. They are converted to snake case for you if required by the APIs.
 
+> **`z.any()` in a structured-output schema.** Providers reject an unconstrained
+> ("any") schema, since the point of structured output is that it's structured. A
+> nested `z.any()` field is therefore coerced to a **string** (`{type:"string"}`) —
+> so `z.object({ data: z.any() })` will have the model emit a string for `data`, not
+> an arbitrary object. If the *entire* `responseFormat` is `z.any()`/`z.unknown()`,
+> structured output is dropped and the model returns free text. Use a concrete Zod
+> shape when you need a specific structure.
+
+## Stop reason
+
+Any result from a model response carries why the turn ended, normalized across
+providers:
+
+- `stopReason` — a unified value: `"stop"` (natural completion), `"length"` (hit
+  max tokens), `"tool_use"` (model wants to call a tool), `"content_filter"`
+  (safety/policy/refusal), `"stop_sequence"`, `"pause"`, or `"other"`.
+- `rawStopReason` — the untouched provider value (e.g. `end_turn`, `MAX_TOKENS`,
+  `tool_calls`), for when you need provider-specific nuance.
+
+```ts
+import { textSync, userMessage } from "smoltalk";
+
+const r = await textSync({
+  model: "claude-sonnet-4-6",
+  maxTokens: 100,
+  messages: [userMessage("Write a long essay about otters.")],
+});
+if (r.success && r.value.stopReason === "length") {
+  // response was truncated — raise maxTokens or continue the turn
+}
+```
+
+Both fields appear on the non-streaming result and on the streaming `done` chunk's
+result. They are optional: a result produced without calling a provider (e.g. a
+tool-loop halt) has neither.
+
+Two provider notes:
+- Google reports `STOP` even for tool-call turns, so `stopReason` is normalized to
+  `"tool_use"` there when tool calls are present (`rawStopReason` still shows `STOP`).
+- The OpenAI Responses API has no single finish-reason field, so its `rawStopReason`
+  is the response *status* (`"completed"`) or the incomplete reason
+  (`"max_output_tokens"`), rather than a chat-style `"stop"`.
+
 ## Configuration Options
 
 `SmolConfig` is a single config type passed to `text()`. It contains everything: API keys, model selection, request parameters, hooks, and observability options.

package/dist/clients/anthropic.d.ts

@@ -3,6 +3,16 @@ import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk, HostedToolRe
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";
 export declare function mergeConsecutiveMessages(messages: MessageParam[]): MessageParam[];
+/**
+ * Whether a model supports Anthropic's native structured-output request
+ * (`output_config.format` with a json_schema — the direct analog of the OpenAI
+ * client's `response_format`). GA on Claude 4.x+ (Opus 4.5+, Sonnet 4.5+, Haiku
+ * 4.5, and the 4.6/4.7/4.8 / Sonnet 5 / Fable families). The legacy claude-3.x /
+ * 2.x aliases do not support it; there we fall back to prompt-based output plus
+ * the base client's fence stripping. Unknown/future model names default to
+ * supported (forward-looking).
+ */
+export declare function anthropicSupportsStructuredOutput(model: string): boolean;
 export declare function anthropicWebSearchEntries(hostedTools?: string[]): any[];
 export declare function parseAnthropicHostedTools(response: any, provider: string): HostedToolResult[];
 type EphemeralCacheControl = {

package/dist/clients/anthropic.js

@@ -6,6 +6,8 @@ import { redactAttachments } from "../util/redact.js";
 import { success, } from "../types.js";
 import { WEB_SEARCH, webSearchResult, applyHostedToolCost } from "../util/hostedTools.js";
 import { zodToAnthropicTool } from "../util/tool.js";
+import { responseFormatToJsonSchema } from "../util/jsonSchema.js";
+import { normalizeAnthropicStopReason } from "../util/stopReason.js";
 import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
 import { extractHttpErrorFields } from "../util/httpError.js";
 import { BaseClient } from "./baseClient.js";
@@ -46,6 +48,18 @@ export function mergeConsecutiveMessages(messages) {
     }
     return merged;
 }
+/**
+ * Whether a model supports Anthropic's native structured-output request
+ * (`output_config.format` with a json_schema — the direct analog of the OpenAI
+ * client's `response_format`). GA on Claude 4.x+ (Opus 4.5+, Sonnet 4.5+, Haiku
+ * 4.5, and the 4.6/4.7/4.8 / Sonnet 5 / Fable families). The legacy claude-3.x /
+ * 2.x aliases do not support it; there we fall back to prompt-based output plus
+ * the base client's fence stripping. Unknown/future model names default to
+ * supported (forward-looking).
+ */
+export function anthropicSupportsStructuredOutput(model) {
+    return !/^claude-(?:3(?:[-.]|$)|2(?:[-.]|$)|instant(?:[-.]|$))/i.test(model);
+}
 export function anthropicWebSearchEntries(hostedTools) {
     if (hostedTools && hostedTools.includes(WEB_SEARCH)) {
         return [{ type: "web_search_20250305", name: "web_search" }];
@@ -247,7 +261,22 @@ export class SmolAnthropic extends BaseClient {
         // Normalize the user's provider-agnostic thinking/effort config into the
         // shape this specific model accepts. Both `thinking.enabled` and
         // `reasoningEffort` are treated as a request to think.
-        const { thinking, outputConfig } = this.resolveThinking(config);
+        const { thinking, outputConfig: effortConfig } = this.resolveThinking(config);
+        // Provider-native structured output. Anthropic constrains the response to a
+        // JSON schema via `output_config.format` (grammar-constrained decoding) —
+        // the direct analog of the OpenAI client's `response_format` json_schema,
+        // and it composes with function tools (the model may call a tool OR emit the
+        // structured JSON). GA on Claude 4.x+; on the legacy claude-3.x/2.x aliases
+        // it isn't available, so we omit it and let the base client's fence stripper
+        // + retry recover a prompt-shaped reply.
+        const format = config.responseFormat &&
+            anthropicSupportsStructuredOutput(this.getModel())
+            ? { type: "json_schema", schema: responseFormatToJsonSchema(config.responseFormat) }
+            : undefined;
+        // Merge effort + format into one output_config (both optional, independent).
+        const outputConfig = effortConfig || format
+            ? { ...effortConfig, ...(format && { format }) }
+            : undefined;
         const cachingEnabled = config.caching?.enabled !== false;
         const baseRequest = { system, messages: anthropicMessages, tools };
         const finalRequest = cachingEnabled
@@ -362,13 +391,18 @@ export class SmolAnthropic extends BaseClient {
         const { usage, cost } = this.calculateUsageAndCost(response.usage);
         const parsed = parseAnthropicHostedTools(response, "anthropic");
         const { results: hostedToolResults, cost: finalCost } = applyHostedToolCost(parsed, cost, this.getModel(), this.config.modelData);
+        const rawStopReason = response.stop_reason ?? undefined;
         const result = {
             output,
             toolCalls,
             usage,
             cost: finalCost,
             model: this.getModel(),
+            stopReason: normalizeAnthropicStopReason(rawStopReason),
         };
+        if (rawStopReason) {
+            result.rawStopReason = rawStopReason;
+        }
         if (thinkingBlocks.length > 0) {
             result.thinkingBlocks = thinkingBlocks;
         }
@@ -416,10 +450,23 @@ export class SmolAnthropic extends BaseClient {
         const toolBlocks = new Map();
         // Track thinking blocks by index: index -> { text, signature }
         const thinkingBlockMap = new Map();
+        // Track server-side web_search blocks by index -> partial input JSON. The
+        // query streams in as input_json_delta just like a client tool call; we
+        // parse it once the block stops and emit a live `web_search` chunk.
+        const webSearchBlocks = new Map();
+        // Accumulated hosted-tool signal for the final `done` result (parity with
+        // the non-streaming path's `hostedToolResults`): queries, sources,
+        // citations, billed count, and the raw provider blocks.
+        const webSearchQueries = [];
+        const webSearchSources = [];
+        const webSearchCitations = [];
+        const webSearchRaw = [];
+        let webSearchRequests;
         let inputTokens = 0;
         let cacheReadTokens = 0;
         let cacheCreationTokens = 0;
         let outputTokens = 0;
+        let rawStopReason;
         for await (const event of stream) {
             if (event.type === "message_start") {
                 const u = event.message.usage;
@@ -435,6 +482,25 @@ export class SmolAnthropic extends BaseClient {
                         arguments: "",
                     });
                 }
+                else if (event.content_block.type === "server_tool_use" &&
+                    event.content_block.name === "web_search") {
+                    // Keep the start block so we can reconstruct the raw provider block
+                    // (with its streamed `input`) at content_block_stop.
+                    webSearchBlocks.set(event.index, {
+                        arguments: "",
+                        start: event.content_block,
+                    });
+                }
+                else if (event.content_block.type === "web_search_tool_result") {
+                    // Server tool results arrive whole (no deltas). Collect sources and
+                    // keep the raw block so the final `done` result matches _textSync.
+                    webSearchRaw.push(event.content_block);
+                    for (const r of event.content_block.content || []) {
+                        if (r && typeof r.url === "string") {
+                            webSearchSources.push({ url: r.url, title: r.title });
+                        }
+                    }
+                }
                 else if (event.content_block.type === "thinking") {
                     thinkingBlockMap.set(event.index, { text: "", signature: "" });
                 }
@@ -449,6 +515,10 @@ export class SmolAnthropic extends BaseClient {
                     if (block) {
                         block.arguments += event.delta.partial_json;
                     }
+                    const searchBlock = webSearchBlocks.get(event.index);
+                    if (searchBlock) {
+                        searchBlock.arguments += event.delta.partial_json;
+                    }
                 }
                 else if (event.delta.type === "thinking_delta") {
                     const block = thinkingBlockMap.get(event.index);
@@ -462,6 +532,15 @@ export class SmolAnthropic extends BaseClient {
                         block.signature = event.delta.signature;
                     }
                 }
+                else if (event.delta.type === "citations_delta") {
+                    // Citations stream in one per delta (whereas _textSync reads them
+                    // from the assembled text block's `citations` array). Collect any
+                    // with a url so the done result's hostedToolResults match sync.
+                    const c = event.delta.citation;
+                    if (c && typeof c.url === "string") {
+                        webSearchCitations.push({ url: c.url, title: c.title });
+                    }
+                }
             }
             else if (event.type === "content_block_stop") {
                 // Emit thinking chunk once the block is fully assembled
@@ -473,8 +552,34 @@ export class SmolAnthropic extends BaseClient {
                         signature: thinkingBlock.signature,
                     };
                 }
+                // Emit the web search query the moment its block completes, so
+                // consumers see the keywords live rather than only in the final result.
+                const searchBlock = webSearchBlocks.get(event.index);
+                if (searchBlock) {
+                    // Delete first so a replayed/duplicate stop event can't emit the
+                    // same query twice.
+                    webSearchBlocks.delete(event.index);
+                    let input;
+                    try {
+                        input = JSON.parse(searchBlock.arguments || "{}");
+                    }
+                    catch {
+                        // Malformed/partial JSON — skip this block rather than throw.
+                    }
+                    // Reconstruct the raw provider block (start header + streamed input)
+                    // so hostedToolResults.raw matches the non-streaming shape.
+                    webSearchRaw.push({ ...searchBlock.start, input });
+                    const query = input?.query;
+                    if (typeof query === "string" && query.length > 0) {
+                        webSearchQueries.push(query);
+                        yield { type: "web_search", query };
+                    }
+                }
             }
             else if (event.type === "message_delta") {
+                if (event.delta?.stop_reason) {
+                    rawStopReason = event.delta.stop_reason;
+                }
                 outputTokens = event.usage.output_tokens;
                 // Defensive: in practice Anthropic only sends cache fields on
                 // message_start, but read them here too so we don't miss an
@@ -485,6 +590,10 @@ export class SmolAnthropic extends BaseClient {
                 if (event.usage.cache_creation_input_tokens != null) {
                     cacheCreationTokens = event.usage.cache_creation_input_tokens;
                 }
+                // Billable web-search count, for hosted-tool cost on the done result.
+                if (event.usage.server_tool_use?.web_search_requests != null) {
+                    webSearchRequests = event.usage.server_tool_use.web_search_requests;
+                }
             }
         }
         this.logger.debug("Streaming response completed from Anthropic");
@@ -510,17 +619,41 @@ export class SmolAnthropic extends BaseClient {
         if (cacheCreationTokens > 0) {
             usage.cacheCreationInputTokens = cacheCreationTokens;
         }
-        const cost = this.model.calculateCost(usage) ?? undefined;
-        yield {
-            type: "done",
-            result: {
-                output: content || null,
-                toolCalls,
-                ...(thinkingBlocks.length > 0 && { thinkingBlocks }),
-                usage,
-                cost,
-                model: this.getModel(),
-            },
+        let cost = this.model.calculateCost(usage) ?? undefined;
+        // Fold hosted-tool (web search) results into the done result so the
+        // streaming path reports the same `hostedToolResults` shape as _textSync.
+        // The live `web_search` chunks above already surfaced the queries; this is
+        // the durable record (queries + sources + citations + billed cost + raw).
+        let hostedToolResults = [];
+        const usedWebSearch = webSearchQueries.length > 0 ||
+            webSearchSources.length > 0 ||
+            (webSearchRequests ?? 0) > 0;
+        if (usedWebSearch) {
+            const applied = applyHostedToolCost([
+                webSearchResult("anthropic", {
+                    queries: webSearchQueries,
+                    sources: webSearchSources,
+                    citations: webSearchCitations,
+                    callCount: webSearchRequests,
+                    raw: webSearchRaw,
+                }),
+            ], cost, this.getModel(), this.config.modelData);
+            hostedToolResults = applied.results;
+            cost = applied.cost;
+        }
+        const result = {
+            output: content || null,
+            toolCalls,
+            ...(thinkingBlocks.length > 0 && { thinkingBlocks }),
+            usage,
+            cost,
+            model: this.getModel(),
+            stopReason: normalizeAnthropicStopReason(rawStopReason),
+            ...(hostedToolResults.length > 0 && { hostedToolResults }),
         };
+        if (rawStopReason) {
+            result.rawStopReason = rawStopReason;
+        }
+        yield { type: "done", result };
     }
 }

package/dist/clients/baseClient.d.ts

@@ -20,6 +20,16 @@ export declare class BaseClient implements SmolClient {
      * by textSync and textStream so the two paths can't diverge.
      */
     protected prepareAttachments(config: SmolConfig): Promise<Result<SmolConfig>>;
+    /**
+     * If the entire `responseFormat` schema is unconstrained (`z.any()` /
+     * `z.unknown()`), structured output is meaningless — every provider would
+     * reject it and there is nothing to validate against. Strip it so the call
+     * behaves exactly as if no `responseFormat` were set: no provider sends a
+     * structured-output request (each gates on `config.responseFormat`), and the
+     * strict parse/retry loop in `textWithRetry` is skipped, returning free text.
+     * A *nested* `any` is left alone here — the schema conversion sanitizes it.
+     */
+    protected normalizeResponseFormat(config: SmolConfig): SmolConfig;
     textSync(promptConfig: SmolConfig): Promise<Result<PromptResult>>;
     checkForToolLoops(promptConfig: SmolConfig): {
         continue: boolean;

package/dist/clients/baseClient.js

@@ -8,6 +8,7 @@ import { validateHostedTools } from "../util/hostedTools.js";
 import { resolveMessageAttachments, messagesHaveAttachments, DEFAULT_MAX_ATTACHMENT_BYTES } from "./resolveAttachments.js";
 import { validateModalities } from "../util/modalities.js";
 import { resolveProvider } from "../util/provider.js";
+import { isUnconstrainedSchema } from "../util/jsonSchema.js";
 import { z } from "zod";
 const DEFAULT_NUM_RETRIES = 2;
 export class BaseClient {
@@ -80,7 +81,25 @@ export class BaseClient {
         }
         return success({ ...config, messages: resolved.value });
     }
+    /**
+     * If the entire `responseFormat` schema is unconstrained (`z.any()` /
+     * `z.unknown()`), structured output is meaningless — every provider would
+     * reject it and there is nothing to validate against. Strip it so the call
+     * behaves exactly as if no `responseFormat` were set: no provider sends a
+     * structured-output request (each gates on `config.responseFormat`), and the
+     * strict parse/retry loop in `textWithRetry` is skipped, returning free text.
+     * A *nested* `any` is left alone here — the schema conversion sanitizes it.
+     */
+    normalizeResponseFormat(config) {
+        if (config.responseFormat &&
+            isUnconstrainedSchema(config.responseFormat.toJSONSchema())) {
+            const { responseFormat, ...rest } = config;
+            return rest;
+        }
+        return config;
+    }
     async textSync(promptConfig) {
+        promptConfig = this.normalizeResponseFormat(promptConfig);
         const messageLimitResult = this.checkMessageLimit(promptConfig);
         if (messageLimitResult)
             return messageLimitResult;
@@ -258,7 +277,12 @@ export class BaseClient {
                 retries > 0) {
                 const allowExtraKeys = promptConfig.responseFormatOptions?.allowExtraKeys ?? false;
                 try {
-                    const parsed = JSON.parse(output);
+                    // Strip any ```json … ``` fence before parsing. Models (notably
+                    // Anthropic on the prompt-based path) routinely wrap structured
+                    // output in a markdown fence; feeding that straight to JSON.parse
+                    // throws and burns a retry. stripCodeFence is a no-op on unfenced
+                    // JSON, so this is safe for every provider.
+                    const parsed = JSON.parse(stripCodeFence(output));
                     const parseResult = this.extractResponse(promptConfig, parsed, promptConfig.responseFormat);
                     return success({
                         ...result.value,
@@ -292,6 +316,7 @@ export class BaseClient {
         throw new Error("Method not implemented.");
     }
     async *textStream(config) {
+        config = this.normalizeResponseFormat(config);
         const messageLimitResult = this.checkMessageLimit(config);
         if (messageLimitResult) {
             yield {

package/dist/clients/google.d.ts

@@ -5,6 +5,21 @@ import { ModelName } from "../models.js";
 import { HostedToolResult } from "../types.js";
 export type SmolGoogleConfig = SmolConfig;
 export declare function googleWebSearchEntries(hostedTools?: string[]): any[];
+/**
+ * Whether a Gemini model can combine built-in tools (e.g. hosted web search)
+ * with function calling in a single request. Confirmed against the live API:
+ *   - Gemini 3+  : supported, but ONLY when `toolConfig
+ *     .includeServerSideToolInvocations` is set ("tool call context
+ *     circulation"). Without it the API 400s asking you to enable it.
+ *   - Gemini 2.5 and earlier: NOT supported by any means — the raw combination
+ *     400s with "Built-in tools and Function Calling cannot be combined", and
+ *     the flag 400s with "Tool call context circulation is not enabled for
+ *     <model>".
+ * Unknown / non-versioned model names default to supported (forward-looking):
+ * new models are expected to allow the combination.
+ * See egonSchiele/agency-lang#495.
+ */
+export declare function geminiSupportsToolCirculation(model: string): boolean;
 export declare function parseGoogleHostedTools(result: any, provider: string, model: string): HostedToolResult[];
 type GeneratedRequest = {
     contents: Content[];

package/dist/clients/google.js

@@ -4,7 +4,9 @@ import { getLogger } from "../util/logger.js";
 import { redactAttachments } from "../util/redact.js";
 import { addCosts, addTokenUsage, success, } from "../types.js";
 import { zodToGoogleTool } from "../util/tool.js";
-import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
+import { responseFormatToJsonSchema } from "../util/jsonSchema.js";
+import { normalizeGoogleStopReason } from "../util/stopReason.js";
+import { SmolError, SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
 import { extractHttpErrorFields } from "../util/httpError.js";
 import { sanitizeAttributes } from "../util/util.js";
 import { BaseClient } from "./baseClient.js";
@@ -17,6 +19,26 @@ export function googleWebSearchEntries(hostedTools) {
     }
     return [];
 }
+/**
+ * Whether a Gemini model can combine built-in tools (e.g. hosted web search)
+ * with function calling in a single request. Confirmed against the live API:
+ *   - Gemini 3+  : supported, but ONLY when `toolConfig
+ *     .includeServerSideToolInvocations` is set ("tool call context
+ *     circulation"). Without it the API 400s asking you to enable it.
+ *   - Gemini 2.5 and earlier: NOT supported by any means — the raw combination
+ *     400s with "Built-in tools and Function Calling cannot be combined", and
+ *     the flag 400s with "Tool call context circulation is not enabled for
+ *     <model>".
+ * Unknown / non-versioned model names default to supported (forward-looking):
+ * new models are expected to allow the combination.
+ * See egonSchiele/agency-lang#495.
+ */
+export function geminiSupportsToolCirculation(model) {
+    const m = /^gemini-(\d+)/.exec(model);
+    if (!m)
+        return true;
+    return parseInt(m[1], 10) >= 3;
+}
 export function parseGoogleHostedTools(result, provider, model) {
     const queries = [];
     const sources = [];
@@ -134,9 +156,22 @@ export class SmolGoogle extends BaseClient {
                 toolGroups.push(entry);
             }
             genConfig.tools = toolGroups;
-            // Gemini rejects mixing built-in (server-side) tools with function calling
-            // unless the caller opts in. Only required when both kinds coexist.
+            // Combining built-in tools (hosted web search) with function calling is a
+            // Gemini feature ("tool call context circulation") that must be opted
+            // into via includeServerSideToolInvocations AND is only supported on
+            // Gemini 3+. On older models the combination is impossible: sending the
+            // flag 400s ("circulation is not enabled for <model>") and omitting it
+            // 400s ("Built-in tools and Function Calling cannot be combined"). Fail
+            // fast with an actionable message instead of a cryptic provider 400.
+            // See egonSchiele/agency-lang#495.
             if (tools.length > 0 && hostedEntries.length > 0) {
+                if (!geminiSupportsToolCirculation(this.getModel())) {
+                    throw new SmolError(`${this.getModel()} cannot use the hosted web_search tool together ` +
+                        `with function tools in one request. Gemini only allows combining ` +
+                        `built-in tools with function calling on Gemini 3+ models. Use a ` +
+                        `Gemini 3+ model, switch to a client-side search tool instead of ` +
+                        `the hosted web_search, or drop one of the two.`, { status: 400 });
+                }
                 genConfig.toolConfig = {
                     ...genConfig.toolConfig,
                     includeServerSideToolInvocations: true,
@@ -145,9 +180,22 @@ export class SmolGoogle extends BaseClient {
         }
         if (config.responseFormat) {
             genConfig.responseMimeType = "application/json";
-            genConfig.responseJsonSchema = config.responseFormat.toJSONSchema();
+            genConfig.responseJsonSchema = responseFormatToJsonSchema(config.responseFormat);
+        }
+        if (config.thinking?.enabled) {
+            // Gemini only returns thought-summary parts (parts with `thought: true`,
+            // which populate PromptResult.thinkingBlocks) when includeThoughts is set.
+            // Without it the model still reasons, but returns only the encrypted
+            // thoughtSignature on the answer part — no visible reasoning text — so
+            // thinkingBlocks would come back empty.
+            genConfig.thinkingConfig = {
+                includeThoughts: true,
+                ...(config.thinking.budgetTokens !== undefined && {
+                    thinkingBudget: config.thinking.budgetTokens,
+                }),
+            };
         }
-        if (!config.thinking?.enabled && config.reasoningEffort) {
+        else if (config.reasoningEffort) {
             const budgetMap = { low: 2048, medium: 8192, high: 16384 };
             genConfig.thinkingConfig = {
                 thinkingBudget: budgetMap[config.reasoningEffort],
@@ -246,7 +294,7 @@ export class SmolGoogle extends BaseClient {
             ...(toolResult.value.thinkingBlocks || []),
             ...(responseResult.value.thinkingBlocks || []),
         ];
-        return success({
+        const structuredResult = {
             output: responseResult.value.output,
             // if there were tool calls, we would have returned already, so we know these are empty
             toolCalls: [],
@@ -254,7 +302,13 @@ export class SmolGoogle extends BaseClient {
             usage: addTokenUsage(toolResult.value.usage, responseResult.value.usage),
             cost: addCosts(toolResult.value.cost, responseResult.value.cost),
             model: request.model,
-        });
+            // The structured-output request is the final turn, so its stop reason wins.
+            stopReason: responseResult.value.stopReason,
+        };
+        if (responseResult.value.rawStopReason) {
+            structuredResult.rawStopReason = responseResult.value.rawStopReason;
+        }
+        return success(structuredResult);
     }
     async __textSync(request) {
         this.logger.debug("Sending request to Google Gemini:", JSON.stringify(redactAttachments(request), null, 2));
@@ -291,14 +345,19 @@ export class SmolGoogle extends BaseClient {
                             thoughtSignature: part.thoughtSignature,
                         }));
                     }
-                    else if (part.thoughtSignature) {
-                        // Capture thought parts (thought: true indicates a thinking part)
+                    else if (part.thought) {
+                        // A thinking part is identified by `thought: true` — NOT merely by
+                        // the presence of a thoughtSignature. Gemini 3 also rides a
+                        // thoughtSignature on the final answer part (no `thought` flag) for
+                        // stateless reasoning continuity; keying on the signature alone
+                        // would misfile that answer text as a thinking block and leave the
+                        // output empty. See egonSchiele/agency-lang.
                         thinkingBlocks.push({
                             text: part.text || "",
-                            signature: part.thoughtSignature,
+                            signature: part.thoughtSignature || "",
                         });
                     }
-                    else if (typeof part.text === "string" && !part.thought) {
+                    else if (typeof part.text === "string") {
                         textContent += part.text;
                     }
                 });
@@ -309,6 +368,7 @@ export class SmolGoogle extends BaseClient {
         const { usage, cost } = this.calculateUsageAndCost(result.usageMetadata);
         const parsed = parseGoogleHostedTools(result, "google", request.model);
         const { results: hostedToolResults, cost: finalCost } = applyHostedToolCost(parsed, cost, request.model, this.config.modelData);
+        const rawStopReason = result.candidates?.[0]?.finishReason ?? undefined;
         // Return the response, updating the chat history
         const promptResult = {
             output,
@@ -316,7 +376,11 @@ export class SmolGoogle extends BaseClient {
             usage,
             cost: finalCost,
             model: request.model,
+            stopReason: normalizeGoogleStopReason(rawStopReason, toolCalls.length > 0),
         };
+        if (rawStopReason) {
+            promptResult.rawStopReason = rawStopReason;
+        }
         if (thinkingBlocks.length > 0) {
             promptResult.thinkingBlocks = thinkingBlocks;
         }
@@ -353,6 +417,7 @@ export class SmolGoogle extends BaseClient {
         const thinkingBlocks = [];
         let usage;
         let cost;
+        let rawStopReason;
         for await (const chunk of stream) {
             // Extract usage metadata from chunks
             if (chunk.usageMetadata) {
@@ -362,6 +427,8 @@ export class SmolGoogle extends BaseClient {
             }
             // Iterate raw parts to capture thought signatures and regular content
             for (const candidate of chunk.candidates || []) {
+                if (candidate?.finishReason)
+                    rawStopReason = candidate.finishReason;
                 for (const part of candidate?.content?.parts || []) {
                     const p = part;
                     // Check functionCall first: Gemini 3 attaches the thought signature to
@@ -395,10 +462,16 @@ export class SmolGoogle extends BaseClient {
                             }
                         }
                     }
-                    else if (p.thoughtSignature) {
+                    else if (p.thought) {
+                        // A thinking part is identified by `thought: true` — NOT merely by
+                        // the presence of a thoughtSignature. Gemini 3 also rides a
+                        // thoughtSignature on the final answer part (no `thought` flag) for
+                        // stateless reasoning continuity; keying on the signature alone
+                        // would misfile that answer text as a thinking block and drop it
+                        // from the completion. See egonSchiele/agency-lang.
                         const block = {
                             text: p.text || "",
-                            signature: p.thoughtSignature,
+                            signature: p.thoughtSignature || "",
                         };
                         thinkingBlocks.push(block);
                         yield {
@@ -425,16 +498,18 @@ export class SmolGoogle extends BaseClient {
             toolCalls.push(toolCall);
             yield { type: "tool_call", toolCall };
         }
-        yield {
-            type: "done",
-            result: {
-                output: content || null,
-                toolCalls,
-                ...(thinkingBlocks.length > 0 && { thinkingBlocks }),
-                usage,
-                cost,
-                model: request.model,
-            },
+        const result = {
+            output: content || null,
+            toolCalls,
+            ...(thinkingBlocks.length > 0 && { thinkingBlocks }),
+            usage,
+            cost,
+            model: request.model,
+            stopReason: normalizeGoogleStopReason(rawStopReason, toolCalls.length > 0),
         };
+        if (rawStopReason) {
+            result.rawStopReason = rawStopReason;
+        }
+        yield { type: "done", result };
     }
 }