@falai/agent 3.1.1 → 3.2.1

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

package/src/utils/index.ts

@@ -69,7 +69,7 @@ export {
 } from "./condition.js";
 
 // JSON utilities
-export { parseJSONResponse, tryParseJSONResponse } from "./json.js";
+export { parseJSONResponse, tryParseJSONResponse, extractEmbeddedJSONObject } from "./json.js";
 
 // Serialization utilities
 export { serializeToolResult, isToolResultLike, extractResultDirectives } from "./serialize.js";

package/src/utils/json.ts

@@ -44,3 +44,64 @@ export function tryParseJSONResponse(text: string): unknown {
     return undefined;
   }
 }
+
+/**
+ * Find a complete JSON object embedded in surrounding text.
+ *
+ * {@link parseJSONResponse} requires the WHOLE string to be the object. A model
+ * told to answer in JSON sometimes answers twice instead — the conversational
+ * text for the user, and then the protocol envelope repeating it — and such a
+ * turn parses as nothing, so the envelope travels on as user-visible content.
+ * This scans for the first balanced `{...}` that parses as an object, ignoring
+ * braces that sit inside string literals.
+ *
+ * Returns `undefined` when no complete object is present (prose that merely
+ * contains a brace, or an envelope truncated before its closing brace).
+ */
+export function extractEmbeddedJSONObject(text: string): Record<string, unknown> | undefined {
+  if (!text) return undefined;
+
+  for (let start = text.indexOf("{"); start !== -1; start = text.indexOf("{", start + 1)) {
+    const end = findObjectEnd(text, start);
+    if (end === -1) continue;
+
+    try {
+      const parsed = JSON.parse(text.slice(start, end + 1));
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // Not an object after all — keep scanning for a later candidate.
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Index of the `}` closing the object that opens at `start`, or -1 when the
+ * text ends first. Quotes and their escapes are tracked so a brace inside a
+ * string value never opens or closes a level.
+ */
+function findObjectEnd(text: string, start: number): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}" && --depth === 0) return i;
+  }
+
+  return -1;
+}