smoltalk 0.8.4 → 0.9.0

package/README.md

@@ -8,15 +8,6 @@ Smoltalk exposes a common API to different LLM providers, with built-in cost tra
 pnpm install smoltalk
 ```
 
-> **Upgrading to 0.6.x?** The flat API-key/host fields on `SmolConfig` have
-> been removed in favor of nested `apiKey` and `baseUrl` maps. Migration:
-> ```diff
-> -{ openAiApiKey: "sk-...",   googleApiKey: "...", ollamaHost: "http://..." }
-> +{ apiKey: { openAi: "sk-...", google: "..." }, baseUrl: { ollama: "http://..." } }
-> ```
-> Env-var fallbacks are unchanged (`OPENAI_API_KEY`, `GEMINI_API_KEY`,
-> `ANTHROPIC_API_KEY`, `OLLAMA_HOST`).
-
 ## Hello world example
 
 ```typescript
@@ -346,7 +337,7 @@ tracking starts working.
 **One model — `registerTextModel` (recommended).** Register once at startup:
 
 ```ts
-import { registerTextModel, textSync } from "smoltalk";
+import { registerTextModel, textSync, userMessage } from "smoltalk";
 
 registerTextModel({
   modelName: "my-model",
@@ -359,6 +350,7 @@ registerTextModel({
   maxOutputTokens: 8192,
 });
 
+const messages = [userMessage("hello")];
 const res = await textSync({
   model: "my-model",
   provider: "openai-compat",
@@ -373,7 +365,7 @@ per-tenant rates), pass a minimal blob for a single call. It layers over the
 baseline exactly like a refresh blob:
 
 ```ts
-import { textSync, type ModelDataBlob } from "smoltalk";
+import { textSync, userMessage, type ModelDataBlob } from "smoltalk";
 
 const modelData: ModelDataBlob = {
   schemaVersion: 1,
@@ -392,6 +384,7 @@ const modelData: ModelDataBlob = {
   ],
 };
 
+const messages = [userMessage("hello")];
 await textSync({ model: "my-model", provider: "openai-compat", messages, modelData });
 ```
 

package/dist/classes/ToolCall.js

@@ -79,17 +79,25 @@ export class ToolCall {
         };
     }
     toGoogle() {
-        return {
-            functionCall: {
-                name: this.name,
-                args: this.arguments,
-            },
-            // Gemini 3 requires the original thought signature echoed back on the
-            // function-call part; omitting it fails validation during tool use.
-            ...(this._thoughtSignature !== undefined && {
-                thoughtSignature: this._thoughtSignature,
-            }),
+        const functionCall = {
+            name: this.name,
+            args: this.arguments,
         };
+        // Echo the id when we have one: the Gemini API pairs a functionResponse
+        // back to its functionCall by id when present. Omit it when empty — current
+        // Gemini 3 preview models issue no ids, and an empty id is not a valid key.
+        if (this._id !== "") {
+            functionCall.id = this._id;
+        }
+        const result = {
+            functionCall,
+        };
+        // Gemini 3 requires the original thought signature echoed back on the
+        // function-call part; omitting it fails validation during tool use.
+        if (this._thoughtSignature !== undefined) {
+            result.thoughtSignature = this._thoughtSignature;
+        }
+        return result;
     }
     toOpenAIResponseInputItem() {
         return {

package/dist/classes/message/ToolMessage.js

@@ -91,18 +91,21 @@ export class ToolMessage extends BaseMessage {
         };
     }
     toGoogleMessage() {
+        const functionResponse = {
+            name: this.name,
+            response: {
+                result: this.content,
+            },
+        };
+        // Echo the id so Gemini can pair this response to its call by id — the
+        // documented matching mechanism. Only when non-empty: current Gemini 3
+        // preview models issue no ids, and an empty id is not a valid key.
+        if (this.tool_call_id !== "") {
+            functionResponse.id = this.tool_call_id;
+        }
         return {
             role: "user",
-            parts: [
-                {
-                    functionResponse: {
-                        name: this.name,
-                        response: {
-                            result: this.content,
-                        },
-                    },
-                },
-            ],
+            parts: [{ functionResponse }],
         };
     }
     toOllamaMessage() {

package/dist/clients/google.d.ts

@@ -3,6 +3,7 @@ import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk } from "../ty
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";
 import { HostedToolResult } from "../types.js";
+import type { Message } from "../classes/message/index.js";
 export type SmolGoogleConfig = SmolConfig;
 export declare function googleWebSearchEntries(hostedTools?: string[]): any[];
 /**
@@ -20,6 +21,7 @@ export declare function googleWebSearchEntries(hostedTools?: string[]): any[];
  * See egonSchiele/agency-lang#495.
  */
 export declare function geminiSupportsToolCirculation(model: string): boolean;
+export declare function reorderToolResultsForGemini(messages: Message[]): Message[];
 export declare function parseGoogleHostedTools(result: any, provider: string, model: string): HostedToolResult[];
 type GeneratedRequest = {
     contents: Content[];

package/dist/clients/google.js

@@ -39,6 +39,118 @@ export function geminiSupportsToolCirculation(model) {
         return true;
     return parseInt(m[1], 10) >= 3;
 }
+// Reorder each round's tool results to match the order of the calls that
+// produced them. Two documented Gemini behaviors make this necessary:
+//   - A function call carries an optional `id`, and a response is paired back to
+//     its call by echoing that id.
+//     https://ai.google.dev/gemini-api/docs/function-calling
+//   - Parts must be returned in the order received (responses in call order:
+//     FC1,FC2 -> FR1,FR2), and the thought signature rides ONLY the first
+//     function call of a parallel batch; omitting it 400s on Gemini 3. So part
+//     order is load-bearing independent of ids.
+//     https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures
+// Current Gemini 3 preview models are observed to emit no function-call ids, so
+// on them pairing is purely positional. A caller whose results arrive in
+// completion order (rather than call order) would otherwise feed tool A's answer
+// to tool B and break thought-signature validation.
+//
+// For every assistant message that carries toolCalls, the run of ToolMessages
+// immediately following it is reordered. The run ends at the first non-tool
+// message: any results the caller interleaved AFTER a non-tool message are left
+// where they are — moving messages across an interloper is repair, not reorder.
+//   1. By id, when both the call and a response have non-empty ids (order-free,
+//      takes global priority so an id match is never stolen by a name match).
+//   2. By name + occurrence otherwise: the k-th response named X answers the
+//      k-th call named X.
+// NEVER drop a message: a response matching no call (or any surplus) is kept at
+// the end of the run in its original relative order. A reorder that lost a
+// message would turn a mispairing bug into a missing-result bug, which is worse.
+export function reorderToolResultsForGemini(messages) {
+    const out = [];
+    let i = 0;
+    while (i < messages.length) {
+        const msg = messages[i];
+        out.push(msg);
+        const toolCalls = msg.role === "assistant" ? msg.toolCalls : undefined;
+        if (!toolCalls || toolCalls.length === 0) {
+            i += 1;
+            continue;
+        }
+        // Collect the contiguous run of tool results that answers this round.
+        let j = i + 1;
+        const run = [];
+        while (j < messages.length && messages[j].role === "tool") {
+            run.push(messages[j]);
+            j += 1;
+        }
+        if (run.length === 0) {
+            i += 1;
+            continue;
+        }
+        out.push(...orderRunToMatchCalls(toolCalls, run));
+        i = j;
+    }
+    return out;
+}
+function orderRunToMatchCalls(toolCalls, run) {
+    const used = new Array(run.length).fill(false);
+    // assignment[callIndex] = index into `run`, or -1 if that call has no result.
+    const assignment = new Array(toolCalls.length).fill(-1);
+    function runId(k) {
+        const m = run[k];
+        if (m.role === "tool") {
+            return m.tool_call_id;
+        }
+        return "";
+    }
+    function runName(k) {
+        const m = run[k];
+        if (m.role === "tool") {
+            return m.name;
+        }
+        return "";
+    }
+    // Pass 1: id pairing (both sides non-empty), global priority.
+    toolCalls.forEach((call, ci) => {
+        if (call.id === "")
+            return;
+        const ri = run.findIndex((_r, k) => !used[k] && runId(k) !== "" && runId(k) === call.id);
+        if (ri !== -1) {
+            assignment[ci] = ri;
+            used[ri] = true;
+        }
+    });
+    // Pass 2: name + occurrence, for calls still unmatched. findIndex takes the
+    // first unused same-name response, so the k-th call named X pairs with the
+    // k-th response named X.
+    //
+    // Garbage-in caveat: if a call and its only same-name response carry DIFFERENT
+    // non-empty ids (one side lost or mangled its id), pass 1 misses and pass 2
+    // pairs them by name — emitting functionCall.id != functionResponse.id in that
+    // slot, which an id-pairing model would see as a contradiction. The input was
+    // already inconsistent; we pair positionally rather than drop the result. Not
+    // a reorder bug.
+    toolCalls.forEach((call, ci) => {
+        if (assignment[ci] !== -1)
+            return;
+        const ri = run.findIndex((_r, k) => !used[k] && runName(k) === call.name);
+        if (ri !== -1) {
+            assignment[ci] = ri;
+            used[ri] = true;
+        }
+    });
+    const ordered = [];
+    for (const ri of assignment) {
+        if (ri !== -1)
+            ordered.push(run[ri]);
+    }
+    // Never drop: append any unmatched/surplus responses in original order.
+    for (let k = 0; k < run.length; k++) {
+        if (!used[k])
+            ordered.push(run[k]);
+    }
+    return ordered;
+}
 export function parseGoogleHostedTools(result, provider, model) {
     const queries = [];
     const sources = [];
@@ -136,7 +248,12 @@ export class SmolGoogle extends BaseClient {
             }
             return true;
         });
-        const messages = contentMessages.map((msg) => msg.toGoogleMessage());
+        // Normalize tool-result ordering before conversion: Gemini pairs each
+        // functionResponse to its functionCall (by id on 3.5+, strictly by position
+        // on the Gemini 3 family), so results must leave in call order regardless of
+        // the order the caller supplied them. See reorderToolResultsForGemini.
+        const orderedMessages = reorderToolResultsForGemini(contentMessages);
+        const messages = orderedMessages.map((msg) => msg.toGoogleMessage());
         const tools = (config.tools || []).map((tool) => {
             return zodToGoogleTool(tool.name, tool.schema, {
                 description: tool.description,
@@ -341,7 +458,12 @@ export class SmolGoogle extends BaseClient {
                         const functionCall = part.functionCall;
                         // Gemini 3 rides the thought signature on the same part as the
                         // function call; capture it so it can be echoed back during tool use.
-                        toolCalls.push(new ToolCall("", functionCall.name, functionCall.args, {
+                        toolCalls.push(
+                        // Keep functionCall.id so id-based pairing can round-trip. Do NOT
+                        // fall back to the name (as the streaming path does for its Map
+                        // key): two parallel calls to the same tool would share a fake id
+                        // and re-create the pairing bug at the id layer.
+                        new ToolCall(functionCall.id || "", functionCall.name, functionCall.args, {
                             thoughtSignature: part.thoughtSignature,
                         }));
                     }

package/package.json

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