@falai/agent 3.1.1 → 3.2.0

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";