@theokit/sdk 2.15.0 → 2.15.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.15.2
+
+### Patch Changes
+
+- 6336f81: Suppress the leaked-dialect tool-call from the visible stream (R7). When `extractToolCallsFromContent` is enabled and a model leaks a `<function=NAME>` tool call as assistant text, the OpenAI-compat streaming now HOLDS that text back at the stream boundary (a small suspicion-buffer FSM that reuses the request-scoped allowlist from R5) instead of emitting it as `text_delta` events — so the raw dialect no longer flashes by in the live stream or lands in the final assistant text. `finish()` still recovers the call (unchanged). Fail-open: a never-closing marker or un-suppressable input is flushed as visible text (never held forever). Flag-off streaming is byte-for-byte unchanged. Grounded in openclaw's stream-normalizer FSM.
+
+## 2.15.1
+
+### Patch Changes
+
+- bec2077: Make the leaked-dialect recovery **request-scoped (R5)**. The opt-in `extractToolCallsFromContent` recovery previously promoted ANY `<function=NAME>` block leaked into assistant text on an enabled route, so a code assistant printing a literal `<function=example>` in a fenced code block could be wrongly turned into a tool call. Recovery now gates on an exact, case-sensitive allowlist derived automatically from the current request's declared tools (`request.tools`): the per-route flag stays the coarse enable, and the allowlist is the precise false-positive guard. A request with no tools recovers nothing; a gated-out block keeps its text visible (it is not silently deleted). No public API change — the allowlist is derived from the tools you already pass. Mirrors openclaw's `@openclaw/tool-call-repair` allowlist.
+
 ## 2.15.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -10332,11 +10332,16 @@ var init_sanitize_tool_input = __esm({
 });
 
 // src/internal/llm/hermes-tool-extract.ts
-function extractHermesToolCalls(content, makeId) {
+function extractHermesToolCalls(content, makeId, allowedToolNames) {
+  const isPromoted = (name) => name.length > 0 && (allowedToolNames === void 0 || allowedToolNames.has(name));
   const toolCalls = [];
+  const droppedNames = [];
   for (const block of content.matchAll(HERMES_BLOCK)) {
     const name = (block[1] ?? "").trim();
-    if (name.length === 0) continue;
+    if (!isPromoted(name)) {
+      if (name.length > 0 && allowedToolNames !== void 0) droppedNames.push(name);
+      continue;
+    }
     toolCalls.push({
       type: "tool_use",
       id: makeId(),
@@ -10344,8 +10349,11 @@ function extractHermesToolCalls(content, makeId) {
       input: parseHermesParams(block[2] ?? "")
     });
   }
-  const residualText = toolCalls.length === 0 ? content : content.replace(HERMES_BLOCK, "").trim();
-  return { toolCalls, residualText };
+  const residualText = toolCalls.length === 0 ? content : content.replace(
+    HERMES_BLOCK,
+    (full, rawName) => isPromoted((rawName ?? "").trim()) ? "" : full
+  ).trim();
+  return { toolCalls, residualText, droppedNames };
 }
 function parseHermesParams(inner) {
   const input = {};
@@ -10357,12 +10365,83 @@ function parseHermesParams(inner) {
   }
   return sanitizeToolInput(input, { trim: true }).value;
 }
-var HERMES_BLOCK, HERMES_PARAM;
+function streamToolCallBufferState(held, allowedToolNames, cap = DEFAULT_STREAM_BUFFER_CAP) {
+  if (allowedToolNames.size === 0) return "impossible";
+  const t = held.trimStart();
+  if (t.length < STREAM_MARKER.length) {
+    return STREAM_MARKER.startsWith(t) ? "possible" : "impossible";
+  }
+  if (!t.startsWith(STREAM_MARKER)) return "impossible";
+  const parsed = parseStreamMarkerName(t);
+  if (parsed === "building") return "possible";
+  if (parsed === "invalid") return "impossible";
+  const nameOk = parsed.complete ? allowedToolNames.has(parsed.name) : someToolNameStartsWith(allowedToolNames, parsed.name);
+  if (!nameOk) return "impossible";
+  return held.length > cap ? "impossible" : "possible";
+}
+function parseStreamMarkerName(t) {
+  let cursor = STREAM_MARKER.length;
+  while (cursor < t.length && isStreamWs(t[cursor])) cursor += 1;
+  const nameStart = cursor;
+  while (cursor < t.length && t[cursor] !== ">" && !isStreamWs(t[cursor])) cursor += 1;
+  const name = t.slice(nameStart, cursor);
+  if (name.length === 0) return cursor >= t.length ? "building" : "invalid";
+  return { name, complete: cursor < t.length && t[cursor] === ">" };
+}
+function someToolNameStartsWith(allowedToolNames, prefix) {
+  for (const name of allowedToolNames) {
+    if (name.startsWith(prefix)) return true;
+  }
+  return false;
+}
+function firstPossibleMarkerStart(held, allowedToolNames) {
+  for (let i = held.indexOf("<"); i !== -1; i = held.indexOf("<", i + 1)) {
+    if (streamToolCallBufferState(held.slice(i), allowedToolNames) === "possible") return i;
+  }
+  return -1;
+}
+var HERMES_BLOCK, HERMES_PARAM, STREAM_MARKER, DEFAULT_STREAM_BUFFER_CAP, isStreamWs, StreamSuppressionBuffer;
 var init_hermes_tool_extract = __esm({
   "src/internal/llm/hermes-tool-extract.ts"() {
     init_sanitize_tool_input();
     HERMES_BLOCK = /<function=\s*([^>\s]+)\s*>([\s\S]*?)<\/tool_call>/g;
     HERMES_PARAM = /<parameter=\s*([^>\s]+)\s*>([\s\S]*?)<\/parameter>/g;
+    STREAM_MARKER = "<function=";
+    DEFAULT_STREAM_BUFFER_CAP = 8192;
+    isStreamWs = (c) => c === " " || c === "	" || c === "\n" || c === "\r";
+    StreamSuppressionBuffer = class {
+      constructor(allowedToolNames) {
+        this.allowedToolNames = allowedToolNames;
+      }
+      allowedToolNames;
+      #held = "";
+      /** Feed a content delta; returns the text to emit as a `text_delta` now, or `undefined` to hold. */
+      push(content) {
+        this.#held += content;
+        if (streamToolCallBufferState(this.#held, this.allowedToolNames) === "possible")
+          return void 0;
+        const holdStart = firstPossibleMarkerStart(this.#held, this.allowedToolNames);
+        if (holdStart > 0) {
+          const flush2 = this.#held.slice(0, holdStart);
+          this.#held = this.#held.slice(holdStart);
+          return flush2;
+        }
+        const flush = this.#held;
+        this.#held = "";
+        return flush;
+      }
+      /** Drain the held buffer at stream end. `hasNativeCalls` mirrors `finish()`'s size-guard: when
+       *  native `tool_calls` exist, `finish()` won't strip the leaked block, so stream the held text WHOLE
+       *  (keeping `accumulatedText == finish.text`); otherwise strip the recoverable blocks. Idempotent. */
+      drain(hasNativeCalls) {
+        if (this.#held.length === 0) return void 0;
+        const held = this.#held;
+        this.#held = "";
+        if (hasNativeCalls) return held;
+        const residual = extractHermesToolCalls(held, () => "held", this.allowedToolNames).residualText;
+        return residual.length > 0 ? residual : void 0;
+      }
+    };
   }
 });
 
@@ -10550,7 +10629,10 @@ var init_openai2 = __esm({
         }
         const accumulator = new OpenAIStreamAccumulator(
           this.options.extractToolCallsFromContent ?? false,
-          providerId
+          providerId,
+          // R5: request-scoped allowlist — leaked recovery only promotes a block whose name is a tool the
+          // model was actually given. Empty set (no tools) recovers nothing.
+          new Set(request.tools?.map((tool) => tool.name) ?? [])
         );
         for await (const record of parseSseStream(response.body, signal)) {
           if (record.data === "[DONE]") break;
@@ -10573,6 +10655,8 @@ var init_openai2 = __esm({
           const events = accumulator.consume(chunk);
           for (const event of events) yield event;
         }
+        const drainEvent = accumulator.finalizeHeldText();
+        if (drainEvent !== void 0) yield drainEvent;
         return accumulator.finish();
       }
     };
@@ -10580,13 +10664,19 @@ var init_openai2 = __esm({
       /**
        * @param extractFromContent opt-in leaked-dialect safe-parse (theokit#58). Default false.
        * @param providerName provider id, used only to label the recovery log line.
+       * @param allowedToolNames R5 request-scoped allowlist — built from `request.tools` at `stream()`;
+       *   leaked recovery in `finish()` only promotes a block whose name is in this set. `undefined`
+       *   (direct construction) recovers all (back-compat); an empty set recovers nothing.
        */
-      constructor(extractFromContent = false, providerName = "openai") {
+      constructor(extractFromContent = false, providerName = "openai", allowedToolNames) {
         this.extractFromContent = extractFromContent;
         this.providerName = providerName;
+        this.allowedToolNames = allowedToolNames;
+        this.suppress = extractFromContent && allowedToolNames !== void 0 && allowedToolNames.size > 0 ? new StreamSuppressionBuffer(allowedToolNames) : void 0;
       }
       extractFromContent;
       providerName;
+      allowedToolNames;
       text = "";
       stopReason = "end_turn";
       inputTokens;
@@ -10595,18 +10685,30 @@ var init_openai2 = __esm({
       cacheWriteTokens;
       reasoningTokens;
       toolCalls = /* @__PURE__ */ new Map();
+      /** R7: present only when recovery is enabled AND the request declares tools — holds suspected
+       *  leaked-dialect content back from the `text_delta` stream. `undefined` ⇒ stream immediately. */
+      suppress;
       consume(chunk) {
         const events = [];
         this.applyUsage(chunk.usage);
         for (const choice of chunk.choices ?? []) {
-          const reasoningEvent = this.applyReasoningDelta(
-            choice.delta?.reasoning ?? choice.delta?.reasoning_content
-          );
-          if (reasoningEvent !== void 0) events.push(reasoningEvent);
-          const textEvent = this.applyContentDelta(choice.delta?.content);
-          if (textEvent !== void 0) events.push(textEvent);
-          this.mergeToolCallDeltas(choice.delta?.tool_calls);
-          this.applyFinishReason(choice.finish_reason);
+          events.push(...this.applyChoice(choice));
+        }
+        return events;
+      }
+      applyChoice(choice) {
+        const events = [];
+        const reasoningEvent = this.applyReasoningDelta(
+          choice.delta?.reasoning ?? choice.delta?.reasoning_content
+        );
+        if (reasoningEvent !== void 0) events.push(reasoningEvent);
+        const textEvent = this.applyContentDelta(choice.delta?.content);
+        if (textEvent !== void 0) events.push(textEvent);
+        this.mergeToolCallDeltas(choice.delta?.tool_calls);
+        this.applyFinishReason(choice.finish_reason);
+        if (choice.finish_reason !== void 0 && choice.finish_reason !== null) {
+          const flushEvent = this.finalizeHeldText();
+          if (flushEvent !== void 0) events.push(flushEvent);
         }
         return events;
       }
@@ -10631,7 +10733,17 @@ var init_openai2 = __esm({
       applyContentDelta(content) {
         if (typeof content !== "string" || content.length === 0) return void 0;
         this.text += content;
-        return { type: "text_delta", text: content };
+        if (this.suppress === void 0) return { type: "text_delta", text: content };
+        const emit = this.suppress.push(content);
+        return emit !== void 0 ? { type: "text_delta", text: emit } : void 0;
+      }
+      /** R7 held-buffer finalizer, called at the `finish_reason` chunk (in `applyChoice`) AND after the
+       *  SSE loop in `stream()` — so a stream that omits a `finish_reason` terminal never silently drops
+       *  held text. `toolCalls.size > 0` (native calls present) makes `finish()` skip recovery, so the
+       *  buffer streams the held text whole. Idempotent once drained. */
+      finalizeHeldText() {
+        const emit = this.suppress?.drain(this.toolCalls.size > 0);
+        return emit !== void 0 ? { type: "text_delta", text: emit } : void 0;
       }
       mergeToolCallDeltas(deltas) {
         for (const call of deltas ?? []) {
@@ -10657,7 +10769,8 @@ var init_openai2 = __esm({
         if (this.extractFromContent && toolCalls.length === 0) {
           const recovered = extractHermesToolCalls(
             this.text,
-            () => `hermes-${globalThis.crypto.randomUUID()}`
+            () => `hermes-${globalThis.crypto.randomUUID()}`,
+            this.allowedToolNames
           );
           if (recovered.toolCalls.length > 0) {
             toolCalls.push(...recovered.toolCalls);
@@ -10665,6 +10778,12 @@ var init_openai2 = __esm({
             stopReason = "tool_use";
             process.stderr.write(
               `[theokit-sdk] recovered ${recovered.toolCalls.length} leaked tool call(s) from assistant content (provider="${this.providerName}", names=${recovered.toolCalls.map((c) => c.name).join(",")})
+`
+            );
+          }
+          if (recovered.droppedNames.length > 0) {
+            process.stderr.write(
+              `[theokit-sdk] dropped ${recovered.droppedNames.length} leaked block(s) whose name is not a tool in the request (provider="${this.providerName}", names=${recovered.droppedNames.join(",")})
 `
             );
           }