@falai/agent 3.1.0 → 3.2.0

package/src/providers/OpenAICompatibleProvider.ts

@@ -23,6 +23,28 @@ import { ProviderAdapter, type ProviderAdapterInit, type RequestConfig } from ".
  */
 export type StructuredOutputMode = "responses_parse" | "json_schema" | "json_object";
 
+/**
+ * How the schema rides on a call that ALSO carries tools — the one turn shape
+ * an agent makes constantly and a provider seam cannot get right by itself.
+ *
+ * `"response_format"` sends both, which every shape documents and most models
+ * honour. `"prompt"` leaves the response format off those calls and sends the
+ * schema as prompt instead.
+ *
+ * Set it to `"prompt"` when the model answers a tool-worthy turn by NARRATING
+ * the tool — "let me look that up for you" — and then stopping. That is not a
+ * model without initiative: its decoder is pinned to the schema, so the tool
+ * call has nowhere to go, and no instruction can make it emit one. Nothing is
+ * logged, because from the wire's point of view nothing failed.
+ *
+ * Measured 2026-09-07, one request, sampled: `z-ai/glm-5.3-flash` called its
+ * tool 0/10 under a response format and 8/8 without one, `deepseek-v4-flash`
+ * 0/5, `gemini-3.8-flash` 3/10. It stays a setting rather than a default
+ * because the reverse is just as real — `qwen3.8-flash` went 10/10 → 1/6 the
+ * other way. Measure the model you ship; one call answers it.
+ */
+export type JsonWithTools = "response_format" | "prompt";
+
 export interface OpenAICompatibleProviderInit
   extends Omit<ProviderAdapterInit, "provider"> {
   apiKey: string;
@@ -32,6 +54,8 @@ export interface OpenAICompatibleProviderInit
   headers?: Record<string, string>;
   config?: RequestConfig;
   structuredOutput?: StructuredOutputMode;
+  /** See {@link JsonWithTools}. Only affects calls that carry tools. */
+  jsonWithTools?: JsonWithTools;
   /** OpenRouter upstream-host pin, to keep a conversation's prompt cache warm. */
   providerOrder?: string[];
   /** Replacement `fetch`, for tests that script the wire. */
@@ -72,6 +96,7 @@ function buildProvider(init: OpenAICompatibleProviderInit, mode: StructuredOutpu
     model: init.model,
     id: init.id,
     jsonMode: mode === "json_schema" ? "schema" : "object",
+    ...(init.jsonWithTools ? { jsonWithTools: init.jsonWithTools } : {}),
     ...(init.baseUrl ? { baseUrl: init.baseUrl } : {}),
     ...(init.headers ? { headers: init.headers } : {}),
     ...(init.config?.maxTokens ? { maxTokens: init.config.maxTokens } : {}),

package/src/providers/OpenRouterProvider.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ProviderCapabilities } from "../types/ai.js";
-import { OpenAICompatibleProvider } from "./OpenAICompatibleProvider.js";
+import { OpenAICompatibleProvider, type JsonWithTools } from "./OpenAICompatibleProvider.js";
 import type { RequestConfig } from "./ProviderAdapter.js";
 
 export interface OpenRouterProviderOptions {
@@ -24,6 +24,14 @@ export interface OpenRouterProviderOptions {
    * conversation's rounds. Fallbacks stay on: this is a preference, not a lock.
    */
   providerOrder?: string[];
+  /**
+   * See {@link JsonWithTools} — and reach for it here first. One gateway serves
+   * hundreds of models and they do not agree: measured through this provider,
+   * `z-ai/glm-5.3-flash` called a tool 0/10 with the schema on the response
+   * format and 8/8 with it in the prompt, while `qwen3.8-flash` went the other
+   * way, 10/10 → 1/6. Changing `model` can change the right answer here.
+   */
+  jsonWithTools?: JsonWithTools;
   /** Request defaults sent with every call */
   config?: RequestConfig;
   /** Idle-stream deadline and retry budget */
@@ -54,6 +62,7 @@ export class OpenRouterProvider extends OpenAICompatibleProvider {
       // Chat completions rather than the Responses API: this gateway's
       // json_schema passthrough is what its models actually support.
       structuredOutput: "json_schema",
+      ...(options.jsonWithTools ? { jsonWithTools: options.jsonWithTools } : {}),
       headers: {
         ...(options.siteUrl ? { "HTTP-Referer": options.siteUrl } : {}),
         ...(options.siteName ? { "X-Title": options.siteName } : {}),

package/src/providers/ProviderAdapter.ts

@@ -22,6 +22,7 @@ import {
   ProviderError,
   classify,
   isBackupEligible,
+  probeJsonWithTools,
   requireContent,
   streamWatch,
   streamWithBackupModels,
@@ -30,6 +31,8 @@ import {
   type ChatMessage,
   type Effort,
   type JsonObjectSchema,
+  type JsonWithToolsProbe,
+  type ProbeOptions,
   type Provider,
   type ProviderChunk,
   type StreamOptions,
@@ -260,6 +263,29 @@ export abstract class ProviderAdapter implements AiProvider {
     this.retryConfig = resolveRetryConfig(init.retryConfig);
   }
 
+  /**
+   * Ask this provider's MODEL whether it can still call a tool while its output
+   * is pinned to a schema — the shape every turn here sends, because that is how
+   * `message` and the step's `collect` fields come back.
+   *
+   * Some models cannot, and they do not report it: the call has nowhere to go,
+   * so the model narrates it ("let me look that up for you") and stops. On the
+   * wire the turn succeeded. Downstream it reads as an agent that will not use
+   * its tools, and no instruction fixes it — which is why this is a measurement
+   * rather than a setting to reason about.
+   *
+   * Run it once, at boot, and pass `use` back as `jsonWithTools` (or fail the
+   * boot when it is `null` — that model cannot serve this framework's turns).
+   * Log `calls`: `0/3 and 3/3` is what makes the next model swap's regression
+   * obvious. Costs `samples × 2` short calls, and errors propagate.
+   */
+  async probeJsonWithTools(opts?: ProbeOptions): Promise<JsonWithToolsProbe> {
+    return probeJsonWithTools(this.provider, {
+      model: this.primaryModel,
+      ...(opts ?? {}),
+    });
+  }
+
   async generateMessage<TContext = unknown, TStructured = AgentStructuredResponse>(
     input: GenerateMessageInput<TContext>,
   ): Promise<GenerateMessageOutput<TStructured>> {

package/src/providers/index.ts

@@ -23,6 +23,7 @@ export type { DeepSeekProviderOptions } from "./DeepSeekProvider.js";
 
 export { OpenAICompatibleProvider } from "./OpenAICompatibleProvider.js";
 export type {
+  JsonWithTools,
   OpenAICompatibleProviderInit,
   StructuredOutputMode,
 } from "./OpenAICompatibleProvider.js";