@falai/agent 2.5.0 → 2.6.1

package/dist/utils/streamingMessage.js

@@ -0,0 +1,205 @@
+/**
+ * Incremental extraction of the `message` field from a streamed structured
+ * JSON response.
+ *
+ * Providers that enforce a JSON schema stream the raw wrapper object
+ * (`{"message":"Hel` → `{"message":"Hello"}`), not the message text. Without
+ * this, every streaming consumer has to re-implement partial-JSON unwrapping to
+ * recover the user-facing tokens. These helpers do it once, at the framework
+ * boundary, so `delta`/`accumulated` carry clean message text and the parsed
+ * object is surfaced only when complete.
+ *
+ * The extractor targets the top-level `message` string field specifically
+ * (tracking object depth and string context, so a nested decoy `"message"` key
+ * or a `"message"` substring inside another value is never mistaken for it),
+ * and is tolerant of truncation at any byte — a dangling escape sequence is
+ * held back rather than emitted half-decoded. Input that is not a JSON object
+ * (e.g. a provider streaming plain text) is passed through verbatim.
+ */
+const WHITESPACE = " \t\n\r";
+const ESCAPE_CHARS = {
+    '"': '"',
+    "\\": "\\",
+    "/": "/",
+    b: "\b",
+    f: "\f",
+    n: "\n",
+    r: "\r",
+    t: "\t",
+};
+/**
+ * Read a JSON string token whose opening quote is at `s[start]`. Decodes
+ * escapes. When the closing quote has not arrived, returns the decoded prefix
+ * with any trailing incomplete escape (`\` or a partial `\uXXXX`) held back, so
+ * a half-decoded character is never produced.
+ */
+function readJsonString(s, start) {
+    let out = "";
+    const n = s.length;
+    let i = start + 1; // skip opening quote
+    while (i < n) {
+        const ch = s[i];
+        if (ch === '"') {
+            return { value: out, end: i + 1, complete: true };
+        }
+        if (ch === "\\") {
+            const esc = s[i + 1];
+            if (esc === undefined) {
+                // Dangling backslash — wait for the rest of the escape.
+                return { value: out, end: n, complete: false };
+            }
+            if (esc === "u") {
+                if (i + 6 > n) {
+                    // Incomplete \uXXXX — hold it back.
+                    return { value: out, end: n, complete: false };
+                }
+                const code = parseInt(s.slice(i + 2, i + 6), 16);
+                if (Number.isNaN(code)) {
+                    return { value: out, end: n, complete: false };
+                }
+                out += String.fromCharCode(code);
+                i += 6;
+            }
+            else if (esc in ESCAPE_CHARS) {
+                out += ESCAPE_CHARS[esc];
+                i += 2;
+            }
+            else {
+                // Not a valid JSON escape; pass the character through leniently.
+                out += esc;
+                i += 2;
+            }
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return { value: out, end: n, complete: false };
+}
+/**
+ * Skip one JSON value (string, object, array, or primitive) starting at `s[i]`.
+ * Tolerant of truncation: an unfinished value reports `complete: false`.
+ */
+function skipJsonValue(s, i) {
+    const n = s.length;
+    if (i >= n)
+        return { end: n, complete: false };
+    const ch = s[i];
+    if (ch === '"') {
+        const r = readJsonString(s, i);
+        return { end: r.end, complete: r.complete };
+    }
+    if (ch === "{" || ch === "[") {
+        let depth = 0;
+        let j = i;
+        while (j < n) {
+            const c = s[j];
+            if (c === '"') {
+                const r = readJsonString(s, j);
+                if (!r.complete)
+                    return { end: n, complete: false };
+                j = r.end;
+                continue;
+            }
+            if (c === "{" || c === "[")
+                depth++;
+            else if (c === "}" || c === "]") {
+                depth--;
+                if (depth === 0)
+                    return { end: j + 1, complete: true };
+            }
+            j++;
+        }
+        return { end: n, complete: false };
+    }
+    // Primitive (number, true, false, null): runs until a structural delimiter.
+    // Hitting end-of-input first means it may still be streaming.
+    let j = i;
+    while (j < n && !`,}]${WHITESPACE}`.includes(s[j]))
+        j++;
+    return j < n ? { end: j, complete: true } : { end: n, complete: false };
+}
+/**
+ * Extract the decoded value of the top-level `message` string field from a
+ * (possibly partial) JSON object string, returning the text available so far.
+ *
+ * Returns `""` while the `message` value has not begun streaming, and passes
+ * `accumulated` through unchanged when it is not a JSON object.
+ */
+export function extractMessageSoFar(accumulated) {
+    const s = accumulated;
+    const n = s.length;
+    let i = 0;
+    while (i < n && WHITESPACE.includes(s[i]))
+        i++;
+    // Not a JSON object — a plain-text stream; emit verbatim.
+    if (i >= n || s[i] !== "{")
+        return accumulated;
+    i++; // skip '{'
+    while (i < n) {
+        while (i < n && (WHITESPACE.includes(s[i]) || s[i] === ","))
+            i++;
+        if (i >= n)
+            return "";
+        if (s[i] === "}")
+            return ""; // object closed without a message
+        if (s[i] !== '"')
+            return ""; // key not (fully) arrived
+        const key = readJsonString(s, i);
+        if (!key.complete)
+            return ""; // key still streaming
+        i = key.end;
+        while (i < n && WHITESPACE.includes(s[i]))
+            i++;
+        if (i >= n || s[i] !== ":")
+            return ""; // colon not arrived
+        i++;
+        while (i < n && WHITESPACE.includes(s[i]))
+            i++;
+        if (i >= n)
+            return "";
+        if (key.value === "message") {
+            // Found it. Only a string value yields text; null/other → no message yet.
+            if (s[i] !== '"')
+                return "";
+            return readJsonString(s, i).value;
+        }
+        // A field before `message`: skip its value. If it is still streaming we
+        // cannot have reached `message` yet.
+        const skipped = skipJsonValue(s, i);
+        if (!skipped.complete)
+            return "";
+        i = skipped.end;
+    }
+    return "";
+}
+/**
+ * Stateful wrapper over {@link extractMessageSoFar} for a single stream: feed
+ * each chunk's accumulated JSON and get back the clean message-so-far plus the
+ * newly revealed delta.
+ *
+ * Each push re-scans the full accumulated buffer (O(n) per chunk, O(n²) over a
+ * stream) — deliberately kept simple and stateless: at LLM response sizes (KBs)
+ * the cost is negligible, and it avoids carrying cross-chunk parser/escape state.
+ */
+export class StreamingMessageDecoder {
+    constructor() {
+        this.previous = "";
+    }
+    /**
+     * @param accumulated The provider chunk's full accumulated output so far.
+     * @returns `message` (clean text so far) and `delta` (the new text since the
+     *          previous push).
+     */
+    push(accumulated) {
+        const message = extractMessageSoFar(accumulated);
+        // Decoding is monotonic (each push extends the prefix); the guard is a
+        // belt-and-braces reset for any non-prefix anomaly.
+        const delta = message.startsWith(this.previous)
+            ? message.slice(this.previous.length)
+            : message;
+        this.previous = message;
+        return { message, delta };
+    }
+}
+//# sourceMappingURL=streamingMessage.js.map

package/dist/utils/streamingMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamingMessage.js","sourceRoot":"","sources":["../../src/utils/streamingMessage.ts"],"names":[],"mappings":"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"}

package/docs/reference/create-agent.md

@@ -44,6 +44,7 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
   flowSwitchMargin?: number;
   maxAutoStepsPerTurn?: number;
   maxDirectiveChain?: number;
+  maxToolLoops?: number;
   compaction?: AgentCompactionConfig;
   promptCache?: PromptCacheConfig;
   routerMode?: 'ai';
@@ -76,6 +77,7 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
 | `flowSwitchMargin` | `number` | no | `15` | Margin (0–100) the best alternative flow must exceed the current flow's score by before switching. Higher values make the agent stickier. |
 | `maxAutoStepsPerTurn` | `number` | no | `10` | Cap on consecutive `auto: true` steps per turn. Throws `FlowConfigurationError` when exceeded. |
 | `maxDirectiveChain` | `number` | no | `10` | Cap on chained directives per turn (e.g., `goTo` → `onEnter` emits `goTo` → …). Throws `FlowConfigurationError` when exceeded. |
+| `maxToolLoops` | `number` | no | `5` | Cap on tool-call follow-up rounds per turn, after the initial tool batch. Stops executing further tool calls when reached. Applies to both `respond()` and streaming. An explicit `0` disables tool loops. |
 | `compaction` | `AgentCompactionConfig` | no | — | History compaction config: `maxTokens`, `compactionThreshold`, `preserveRecentCount`, `maxToolResultChars`. |
 | `promptCache` | `PromptCacheConfig` | no | `{ enabled: true }` | Controls prompt-section memoization across turns. |
 | `debug` | `boolean` | no | `false` | Enables `loglevel` debug output. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/Agent.ts

@@ -255,7 +255,9 @@ export class Agent<TContext = unknown, TData = unknown> implements ResponseModal
     this.tool = new ToolManager<TContext, TData>(this);
 
     // Initialize ResponseModal for handling all response generation
-    this._responseModal = new ResponseModal<TContext, TData>(this);
+    this._responseModal = new ResponseModal<TContext, TData>(this, {
+      maxToolLoops: options.maxToolLoops,
+    });
 
     // Initialize persistence if configured
     if (options.persistence) {

package/src/core/FlowRouter.ts

@@ -366,20 +366,6 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
       }
     }
 
-    // No candidates means flow has no valid next steps (edge case)
-    if (candidates.length === 0) {
-      logger.debug(
-        `[FlowRouter] Single-flow: No valid candidate steps found`
-      );
-      return {
-        selectedFlow,
-        selectedStep: undefined,
-        session: updatedSession,
-        isFlowComplete: false,
-        completedFlows,
-      };
-    }
-
     // Multiple candidates - use AI to select best step
     const lastUserMessage = getLastMessageFromHistory(history);