smoltalk 0.8.2 → 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.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";
@@ -269,7 +271,7 @@ export class SmolAnthropic extends BaseClient {
         // + retry recover a prompt-shaped reply.
         const format = config.responseFormat &&
             anthropicSupportsStructuredOutput(this.getModel())
-            ? { type: "json_schema", schema: config.responseFormat.toJSONSchema() }
+            ? { type: "json_schema", schema: responseFormatToJsonSchema(config.responseFormat) }
             : undefined;
         // Merge effort + format into one output_config (both optional, independent).
         const outputConfig = effortConfig || format
@@ -389,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;
         }
@@ -459,6 +466,7 @@ export class SmolAnthropic extends BaseClient {
         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;
@@ -569,6 +577,9 @@ export class SmolAnthropic extends BaseClient {
                 }
             }
             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
@@ -630,17 +641,19 @@ export class SmolAnthropic extends BaseClient {
             hostedToolResults = applied.results;
             cost = applied.cost;
         }
-        yield {
-            type: "done",
-            result: {
-                output: content || null,
-                toolCalls,
-                ...(thinkingBlocks.length > 0 && { thinkingBlocks }),
-                usage,
-                cost,
-                model: this.getModel(),
-                ...(hostedToolResults.length > 0 && { hostedToolResults }),
-            },
+        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;
@@ -297,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.js

@@ -4,6 +4,8 @@ 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 { 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";
@@ -178,7 +180,7 @@ 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`,
@@ -292,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: [],
@@ -300,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));
@@ -360,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,
@@ -367,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;
         }
@@ -404,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) {
@@ -413,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
@@ -482,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 };
     }
 }

package/dist/clients/ollama.js

@@ -4,6 +4,8 @@ import { getLogger } from "../util/logger.js";
 import { redactAttachments } from "../util/redact.js";
 import { success, } from "../types.js";
 import { zodToGoogleTool } from "../util/tool.js";
+import { responseFormatToJsonSchema } from "../util/jsonSchema.js";
+import { normalizeOllamaStopReason } from "../util/stopReason.js";
 import { sanitizeAttributes } from "../util/util.js";
 import { resolveBaseUrl } from "../util/provider.js";
 import { BaseClient } from "./baseClient.js";
@@ -81,7 +83,7 @@ export class SmolOllama extends BaseClient {
             request.tools = tools.map((t) => ({ type: "function", function: t }));
         }
         if (config.responseFormat) {
-            request.format = config.responseFormat.toJSONSchema();
+            request.format = responseFormatToJsonSchema(config.responseFormat);
         }
         Object.assign(request, sanitizeAttributes(config.rawAttributes));
         this.logger.debug("Sending request to Ollama:", JSON.stringify(redactAttachments(request), null, 2));
@@ -116,8 +118,20 @@ export class SmolOllama extends BaseClient {
         }
         // Extract usage and calculate cost
         const { usage, cost } = this.calculateUsageAndCost(result);
+        const rawStopReason = result.done_reason ?? undefined;
         // Return the response, updating the chat history
-        return success({ output, toolCalls, usage, cost, model: this.getModel() });
+        const promptResult = {
+            output,
+            toolCalls,
+            usage,
+            cost,
+            model: this.getModel(),
+            stopReason: normalizeOllamaStopReason(rawStopReason),
+        };
+        if (rawStopReason) {
+            promptResult.rawStopReason = rawStopReason;
+        }
+        return success(promptResult);
     }
     async *_textStream(config) {
         const messages = config.messages.map((msg) => msg.toOllamaMessage());
@@ -135,7 +149,7 @@ export class SmolOllama extends BaseClient {
             request.tools = tools.map((t) => ({ type: "function", function: t }));
         }
         if (config.responseFormat) {
-            request.format = config.responseFormat.toJSONSchema();
+            request.format = responseFormatToJsonSchema(config.responseFormat);
         }
         Object.assign(request, sanitizeAttributes(config.rawAttributes));
         this.logger.debug("Sending streaming request to Ollama:", JSON.stringify(redactAttachments(request), null, 2));
@@ -201,16 +215,19 @@ export class SmolOllama extends BaseClient {
                 toolCalls.push(toolCall);
                 yield { type: "tool_call", toolCall };
             }
-            yield {
-                type: "done",
-                result: {
-                    output: content || null,
-                    toolCalls,
-                    usage,
-                    cost,
-                    model: this.getModel(),
-                },
+            const rawStopReason = lastChunk?.done_reason ?? undefined;
+            const result = {
+                output: content || null,
+                toolCalls,
+                usage,
+                cost,
+                model: this.getModel(),
+                stopReason: normalizeOllamaStopReason(rawStopReason),
             };
+            if (rawStopReason) {
+                result.rawStopReason = rawStopReason;
+            }
+            yield { type: "done", result };
         }
         catch (error) {
             this.rethrowAsSmolError(error);

package/dist/clients/openai.js

@@ -8,6 +8,8 @@ import { BaseClient } from "./baseClient.js";
 import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
 import { extractHttpErrorFields } from "../util/httpError.js";
 import { zodToOpenAITool } from "../util/tool.js";
+import { responseFormatToJsonSchema } from "../util/jsonSchema.js";
+import { normalizeOpenAIStopReason } from "../util/stopReason.js";
 import { Model } from "../model.js";
 export class SmolOpenAi extends BaseClient {
     client;
@@ -120,7 +122,7 @@ export class SmolOpenAi extends BaseClient {
                 type: "json_schema",
                 json_schema: {
                     name: config.responseFormatOptions?.name || "response",
-                    schema: config.responseFormat.toJSONSchema(),
+                    schema: responseFormatToJsonSchema(config.responseFormat),
                 },
             };
         }
@@ -185,14 +187,22 @@ export class SmolOpenAi extends BaseClient {
         // response headers (e.g. LiteLLM's x-litellm-response-cost).
         const { usage, cost } = this.calculateUsageAndCost(completion.usage, rawResponse);
         const hostedToolResults = this.parseHostedToolResults(completion, config);
-        return success({
+        const rawStopReason = completion.choices[0]?.finish_reason ?? undefined;
+        const result = {
             output,
             toolCalls,
             usage,
             cost,
             model: this.getModel(),
-            ...(hostedToolResults.length > 0 ? { hostedToolResults } : {}),
-        });
+            stopReason: normalizeOpenAIStopReason(rawStopReason),
+        };
+        if (rawStopReason) {
+            result.rawStopReason = rawStopReason;
+        }
+        if (hostedToolResults.length > 0) {
+            result.hostedToolResults = hostedToolResults;
+        }
+        return success(result);
     }
     async *_textStream(config) {
         const request = this.buildRequest(config);
@@ -214,7 +224,11 @@ export class SmolOpenAi extends BaseClient {
         const toolCallsMap = new Map();
         let usage;
         let cost;
+        let rawStopReason;
         for await (const chunk of completion) {
+            const chunkFinish = chunk.choices?.[0]?.finish_reason;
+            if (chunkFinish)
+                rawStopReason = chunkFinish;
             // Extract usage from the final chunk
             if (chunk.usage) {
                 // Header-based cost (LiteLLM) is unsupported while streaming.
@@ -266,15 +280,17 @@ export class SmolOpenAi extends BaseClient {
             toolCalls.push(toolCall);
             yield { type: "tool_call", toolCall };
         }
-        yield {
-            type: "done",
-            result: {
-                output: content || null,
-                toolCalls,
-                usage,
-                cost,
-                model: this.getModel(),
-            },
+        const result = {
+            output: content || null,
+            toolCalls,
+            usage,
+            cost,
+            model: this.getModel(),
+            stopReason: normalizeOpenAIStopReason(rawStopReason),
         };
+        if (rawStopReason) {
+            result.rawStopReason = rawStopReason;
+        }
+        yield { type: "done", result };
     }
 }

package/dist/clients/openaiResponses.js

@@ -5,6 +5,8 @@ import { getLogger } from "../util/logger.js";
 import { redactAttachments } from "../util/redact.js";
 import { BaseClient } from "./baseClient.js";
 import { zodToOpenAIResponsesTool } from "../util/tool.js";
+import { responseFormatToJsonSchema } from "../util/jsonSchema.js";
+import { normalizeOpenAIResponsesStopReason } from "../util/stopReason.js";
 import { sanitizeAttributes } from "../util/util.js";
 import { WEB_SEARCH, webSearchResult, applyHostedToolCost } from "../util/hostedTools.js";
 import { Model } from "../model.js";
@@ -122,7 +124,7 @@ export class SmolOpenAiResponses extends BaseClient {
                 format: {
                     type: "json_schema",
                     name: config.responseFormatOptions?.name || "response",
-                    schema: config.responseFormat.toJSONSchema(),
+                    schema: responseFormatToJsonSchema(config.responseFormat),
                 },
             };
         }
@@ -192,13 +194,19 @@ export class SmolOpenAiResponses extends BaseClient {
         const { usage, cost } = this.calculateUsageAndCost(response.usage);
         const parsed = parseOpenAIResponsesHostedTools(response, "openai-responses");
         const { results: hostedToolResults, cost: finalCost } = applyHostedToolCost(parsed, cost, this.getModel(), this.config.modelData);
+        const incompleteReason = response.incomplete_details?.reason;
+        const rawStopReason = incompleteReason ?? response.status ?? undefined;
         const result = {
             output,
             toolCalls,
             usage,
             cost: finalCost,
             model: this.getModel(),
+            stopReason: normalizeOpenAIResponsesStopReason(response.status, incompleteReason, toolCalls.length > 0),
         };
+        if (rawStopReason) {
+            result.rawStopReason = rawStopReason;
+        }
         if (hostedToolResults.length > 0) {
             result.hostedToolResults = hostedToolResults;
         }
@@ -222,7 +230,12 @@ export class SmolOpenAiResponses extends BaseClient {
         const functionCalls = new Map();
         let usage;
         let cost;
+        let finalResponse;
         for await (const event of stream) {
+            if (event.type === "response.completed" ||
+                event.type === "response.incomplete") {
+                finalResponse = event.response;
+            }
             switch (event.type) {
                 case "response.output_text.delta": {
                     content += event.delta;
@@ -291,15 +304,19 @@ export class SmolOpenAiResponses extends BaseClient {
             toolCalls.push(toolCall);
             yield { type: "tool_call", toolCall };
         }
-        yield {
-            type: "done",
-            result: {
-                output: content || null,
-                toolCalls,
-                usage,
-                cost,
-                model: this.getModel(),
-            },
+        const incompleteReason = finalResponse?.incomplete_details?.reason;
+        const rawStopReason = incompleteReason ?? finalResponse?.status ?? undefined;
+        const result = {
+            output: content || null,
+            toolCalls,
+            usage,
+            cost,
+            model: this.getModel(),
+            stopReason: normalizeOpenAIResponsesStopReason(finalResponse?.status, incompleteReason, toolCalls.length > 0),
         };
+        if (rawStopReason) {
+            result.rawStopReason = rawStopReason;
+        }
+        yield { type: "done", result };
     }
 }

package/dist/types/stopReason.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Normalized reason a generation turn ended, unified across providers. The
+ * untouched provider value is available separately as `PromptResult.rawStopReason`.
+ */
+export type StopReason = 
+/** Natural completion (OpenAI `stop`, Anthropic `end_turn`, Google `STOP`, Ollama `stop`). */
+"stop"
+/** Hit the max-tokens limit (`length` / `max_tokens` / `MAX_TOKENS`). */
+ | "length"
+/** Model wants to call a tool (`tool_calls` / `tool_use`). */
+ | "tool_use"
+/** Blocked by a safety/policy filter or refusal (`content_filter` / `refusal` / `SAFETY`). */
+ | "content_filter"
+/** Hit a caller-supplied stop sequence (Anthropic `stop_sequence`). */
+ | "stop_sequence"
+/** Provider paused a long-running turn (Anthropic `pause_turn`). */
+ | "pause"
+/** Anything unmapped or unknown. */
+ | "other";

package/dist/types/stopReason.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -10,8 +10,10 @@ import type { ModelDataBlob } from "./modelData.js";
 import { Result } from "./types/result.js";
 import { TokenUsage } from "./types/tokenUsage.js";
 import { CostEstimate } from "./types/costEstimate.js";
+import { StopReason } from "./types/stopReason.js";
 export * from "./types/costEstimate.js";
 export * from "./types/tokenUsage.js";
+export * from "./types/stopReason.js";
 export type SmolConfig = {
     /** The model to use. */
     model: ModelName;
@@ -150,8 +152,12 @@ export type PromptResult = {
     cost?: CostEstimate;
     model?: ModelName;
     hostedToolResults?: HostedToolResult[];
+    /** Normalized reason the turn ended, unified across providers. */
+    stopReason?: StopReason;
+    /** The untouched provider finish/stop-reason value (e.g. `end_turn`, `MAX_TOKENS`). */
+    rawStopReason?: string;
 };
-export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, }: Partial<PromptResult>): PromptResult;
+export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, }: Partial<PromptResult>): PromptResult;
 export type StreamChunk = {
     type: "text";
     text: string;

package/dist/types.js

@@ -3,7 +3,8 @@ export * from "./classes/message/contentParts.js";
 import z from "zod";
 export * from "./types/costEstimate.js";
 export * from "./types/tokenUsage.js";
-export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, }) {
+export * from "./types/stopReason.js";
+export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, }) {
     return {
         output: output || null,
         toolCalls: toolCalls || [],
@@ -12,6 +13,8 @@ export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, m
         cost,
         model,
         hostedToolResults,
+        stopReason,
+        rawStopReason,
     };
 }
 export const ThinkingBlockSchema = z.object({

package/dist/util/jsonSchema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * JSON Schema sanitization for structured output.
+ *
+ * Zod converts `z.any()` / `z.unknown()` to an unconstrained schema — a bare
+ * `{}` (nested), `{"$schema":…}` (top-level), or the boolean `true`. That is
+ * valid JSON Schema ("accept any value"), but every provider rejects an
+ * unconstrained node inside a structured-output or strict-tool schema, since the
+ * whole point of structured output is that it is structured. These helpers map
+ * such nodes to `{"type":"string"}` (the safe universal container) and let
+ * callers detect the whole-schema-is-`any` case so they can drop structured
+ * output entirely and return free text.
+ */
+/**
+ * True if `node` accepts any value: the boolean `true`, or a plain object whose
+ * every own key is a pure annotation (`{}`, `{$schema:…}`,
+ * `{$schema:…, description:…}`). `false` and any object with a structural or
+ * validation keyword are constrained.
+ */
+export declare function isUnconstrainedSchema(node: unknown): boolean;
+/**
+ * Convert a Zod `responseFormat` schema to a sanitized JSON Schema for a
+ * provider's structured-output request: any nested unconstrained node becomes
+ * `{"type":"string"}`. (The whole-schema-is-`any` case is handled upstream in
+ * `BaseClient.normalizeResponseFormat`, which drops structured output entirely.)
+ */
+export declare function responseFormatToJsonSchema(schema: {
+    toJSONSchema: () => unknown;
+}): object;
+/**
+ * Returns a new JSON Schema with every unconstrained node replaced by
+ * `{"type":"string"}` (annotations preserved), recursing through all subschema
+ * positions. Idempotent — a node that already has `type` is left untouched.
+ *
+ * `additionalProperties` and `items` may be a boolean (`true`/`false`), which is
+ * a legitimate provider-accepted flag, not an any-typed value slot; booleans
+ * there are left as-is and only an object subschema is sanitized.
+ */
+export declare function sanitizeJsonSchema(node: unknown): unknown;

package/dist/util/jsonSchema.js

@@ -0,0 +1,133 @@
+/**
+ * JSON Schema sanitization for structured output.
+ *
+ * Zod converts `z.any()` / `z.unknown()` to an unconstrained schema — a bare
+ * `{}` (nested), `{"$schema":…}` (top-level), or the boolean `true`. That is
+ * valid JSON Schema ("accept any value"), but every provider rejects an
+ * unconstrained node inside a structured-output or strict-tool schema, since the
+ * whole point of structured output is that it is structured. These helpers map
+ * such nodes to `{"type":"string"}` (the safe universal container) and let
+ * callers detect the whole-schema-is-`any` case so they can drop structured
+ * output entirely and return free text.
+ */
+/**
+ * Pure-annotation keywords. A node carrying *only* these constrains nothing, so
+ * it is treated as unconstrained. Everything else — `type`, `properties`,
+ * `enum`, `$ref`, any validation keyword — counts as constraining. This is an
+ * allowlist, not a denylist of structural keywords, so unknown/future keywords
+ * are constraining by default (the safe direction: never rewrite a schema that
+ * means something).
+ */
+const ANNOTATION_KEYS = new Set([
+    "$schema",
+    "$id",
+    "$anchor",
+    "$comment",
+    "description",
+    "title",
+    "default",
+    "examples",
+    "readOnly",
+    "deprecated",
+]);
+/**
+ * True if `node` accepts any value: the boolean `true`, or a plain object whose
+ * every own key is a pure annotation (`{}`, `{$schema:…}`,
+ * `{$schema:…, description:…}`). `false` and any object with a structural or
+ * validation keyword are constrained.
+ */
+export function isUnconstrainedSchema(node) {
+    if (node === true)
+        return true;
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+        return false;
+    }
+    return Object.keys(node).every((key) => ANNOTATION_KEYS.has(key));
+}
+/**
+ * Convert a Zod `responseFormat` schema to a sanitized JSON Schema for a
+ * provider's structured-output request: any nested unconstrained node becomes
+ * `{"type":"string"}`. (The whole-schema-is-`any` case is handled upstream in
+ * `BaseClient.normalizeResponseFormat`, which drops structured output entirely.)
+ */
+export function responseFormatToJsonSchema(schema) {
+    // Zod's top-level toJSONSchema() is always an object, and the whole-schema-is-
+    // `any` case is stripped upstream, so sanitize always yields an object here.
+    return sanitizeJsonSchema(schema.toJSONSchema());
+}
+/**
+ * Subschema positions holding a single nested value schema (recursed into).
+ *
+ * `not` and `contains` are deliberately excluded: they are *assertions*, not
+ * value slots, so an unconstrained schema there is meaningful and must not be
+ * rewritten — `not: {}` means "reject everything" and would silently become
+ * "reject only strings" if mapped to `{type:"string"}`. Zod never emits either,
+ * so leaving them untouched is both correct and zero-impact in practice.
+ */
+const SCHEMA_KEYS = ["items", "propertyNames"];
+/** Subschema positions holding an object map of schemas. */
+const SCHEMA_MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions"];
+/** Subschema positions holding an array of schemas. */
+const SCHEMA_ARRAY_KEYS = ["anyOf", "oneOf", "allOf", "prefixItems"];
+/**
+ * Returns a new JSON Schema with every unconstrained node replaced by
+ * `{"type":"string"}` (annotations preserved), recursing through all subschema
+ * positions. Idempotent — a node that already has `type` is left untouched.
+ *
+ * `additionalProperties` and `items` may be a boolean (`true`/`false`), which is
+ * a legitimate provider-accepted flag, not an any-typed value slot; booleans
+ * there are left as-is and only an object subschema is sanitized.
+ */
+export function sanitizeJsonSchema(node) {
+    if (node === true)
+        return { type: "string" };
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+        return node;
+    }
+    if (isUnconstrainedSchema(node)) {
+        return { ...node, type: "string" };
+    }
+    const src = node;
+    const out = { ...src };
+    for (const key of SCHEMA_KEYS) {
+        if (key in out) {
+            out[key] = sanitizeSubschema(out[key]);
+        }
+    }
+    for (const key of SCHEMA_MAP_KEYS) {
+        const map = out[key];
+        if (map && typeof map === "object" && !Array.isArray(map)) {
+            // Object.create(null): a property literally named "__proto__" (a legal Zod
+            // key) would otherwise reassign the prototype instead of setting an own key.
+            const sanitized = Object.create(null);
+            for (const [name, sub] of Object.entries(map)) {
+                sanitized[name] = sanitizeJsonSchema(sub);
+            }
+            out[key] = sanitized;
+        }
+    }
+    for (const key of SCHEMA_ARRAY_KEYS) {
+        const arr = out[key];
+        if (Array.isArray(arr)) {
+            out[key] = arr.map((sub) => sanitizeJsonSchema(sub));
+        }
+    }
+    // additionalProperties: leave booleans as-is, sanitize an object subschema.
+    if ("additionalProperties" in out) {
+        out.additionalProperties = sanitizeSubschema(out.additionalProperties);
+    }
+    return out;
+}
+/**
+ * Sanitize a value at a single-schema position (`items`, `propertyNames`,
+ * `additionalProperties`). These positions may legitimately hold a boolean:
+ * `additionalProperties: false`/`true` and `items: false` are provider-accepted
+ * flags, not any-typed value slots, so booleans pass through untouched and only
+ * an object subschema is recursively sanitized. (Zod does not emit a boolean at
+ * these positions, so `items: true` etc. are theoretical.)
+ */
+function sanitizeSubschema(value) {
+    if (typeof value === "boolean")
+        return value;
+    return sanitizeJsonSchema(value);
+}

package/dist/util/stopReason.d.ts

@@ -0,0 +1,11 @@
+import type { StopReason } from "../types/stopReason.js";
+export declare function normalizeOpenAIStopReason(raw: string | null | undefined): StopReason;
+export declare function normalizeAnthropicStopReason(raw: string | null | undefined): StopReason;
+export declare function normalizeGoogleStopReason(raw: string | null | undefined, hasToolCalls: boolean): StopReason;
+export declare function normalizeOllamaStopReason(raw: string | null | undefined): StopReason;
+/**
+ * The Responses API has no single finish-reason field: a `completed` response
+ * is a normal stop (or tool use, if it carries tool calls), while an
+ * `incomplete` one carries the reason in `incomplete_details.reason`.
+ */
+export declare function normalizeOpenAIResponsesStopReason(status: string | null | undefined, incompleteReason: string | null | undefined, hasToolCalls: boolean): StopReason;

package/dist/util/stopReason.js

@@ -0,0 +1,80 @@
+/**
+ * Pure mappers from each provider's raw finish/stop-reason vocabulary to the
+ * unified {@link StopReason}. Clients set `PromptResult.stopReason` from these
+ * and keep the untouched provider value in `PromptResult.rawStopReason`.
+ */
+const OPENAI_MAP = {
+    stop: "stop",
+    length: "length",
+    tool_calls: "tool_use",
+    function_call: "tool_use",
+    content_filter: "content_filter",
+};
+export function normalizeOpenAIStopReason(raw) {
+    return (raw && OPENAI_MAP[raw]) || "other";
+}
+const ANTHROPIC_MAP = {
+    end_turn: "stop",
+    max_tokens: "length",
+    // Ran out of context window — a length-class stop, same bucket as max_tokens.
+    model_context_window_exceeded: "length",
+    tool_use: "tool_use",
+    stop_sequence: "stop_sequence",
+    refusal: "content_filter",
+    pause_turn: "pause",
+};
+export function normalizeAnthropicStopReason(raw) {
+    return (raw && ANTHROPIC_MAP[raw]) || "other";
+}
+const GOOGLE_MAP = {
+    STOP: "stop",
+    MAX_TOKENS: "length",
+    SAFETY: "content_filter",
+    PROHIBITED_CONTENT: "content_filter",
+    RECITATION: "content_filter",
+    BLOCKLIST: "content_filter",
+    SPII: "content_filter",
+    IMAGE_SAFETY: "content_filter",
+    LANGUAGE: "content_filter",
+};
+export function normalizeGoogleStopReason(raw, hasToolCalls) {
+    // Gemini reports `STOP` even for tool-call turns, so infer `tool_use` when
+    // tool calls are present — otherwise the unified field couldn't detect tool
+    // use on Google the way it does on OpenAI/Anthropic.
+    if (raw === "STOP" && hasToolCalls) {
+        return "tool_use";
+    }
+    return (raw && GOOGLE_MAP[raw]) || "other";
+}
+const OLLAMA_MAP = {
+    stop: "stop",
+    length: "length",
+};
+export function normalizeOllamaStopReason(raw) {
+    return (raw && OLLAMA_MAP[raw]) || "other";
+}
+const RESPONSES_INCOMPLETE_MAP = {
+    max_output_tokens: "length",
+    content_filter: "content_filter",
+};
+/**
+ * The Responses API has no single finish-reason field: a `completed` response
+ * is a normal stop (or tool use, if it carries tool calls), while an
+ * `incomplete` one carries the reason in `incomplete_details.reason`.
+ */
+export function normalizeOpenAIResponsesStopReason(status, incompleteReason, hasToolCalls) {
+    if (incompleteReason) {
+        return RESPONSES_INCOMPLETE_MAP[incompleteReason] || "other";
+    }
+    // Tool-call turns report a generic terminal status, so infer tool_use from the
+    // presence of tool calls. Also treat a missing status (e.g. a stream that ended
+    // without a completed/incomplete event) as "unknown but has tools" rather than
+    // letting a tool-call turn silently degrade to "other".
+    if (hasToolCalls && (status === "completed" || status == null)) {
+        return "tool_use";
+    }
+    if (status === "completed") {
+        return "stop";
+    }
+    return "other";
+}

package/dist/util/tool.js

@@ -1,8 +1,9 @@
 import { validateToolName } from "./util.js";
+import { sanitizeJsonSchema } from "./jsonSchema.js";
 export function zodToOpenAITool(name, schema, options = {}) {
     validateToolName(name);
     // Convert Zod schema to JSON Schema
-    const jsonSchema = schema.toJSONSchema();
+    const jsonSchema = sanitizeJsonSchema(schema.toJSONSchema());
     let description = "";
     if (options?.description) {
         description = options.description;
@@ -37,7 +38,7 @@ export function zodToOpenAITool(name, schema, options = {}) {
 }
 export function zodToOpenAIResponsesTool(name, schema, options = {}) {
     validateToolName(name);
-    const jsonSchema = schema.toJSONSchema();
+    const jsonSchema = sanitizeJsonSchema(schema.toJSONSchema());
     const strict = options?.strict ?? false;
     const parameters = {
         type: "object",
@@ -67,7 +68,7 @@ export function zodToOpenAIResponsesTool(name, schema, options = {}) {
 }
 export function zodToAnthropicTool(name, schema, options = {}) {
     validateToolName(name);
-    const jsonSchema = schema.toJSONSchema();
+    const jsonSchema = sanitizeJsonSchema(schema.toJSONSchema());
     let description;
     if (options?.description) {
         description = options.description;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [