jeopi-ai 16.4.4 → 16.4.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.4.5] - 2026-08-03
+
+### Added
+
+- Added `salvageLeakedToolCalls` (`jeopi-ai/dialect`), which re-materializes a native-tool-calling turn whose tool call was emitted as visible `<invoke …>` text into real `toolCall` content blocks. It only fires on unambiguous leaks: the turn must have stopped normally, carry no native tool call, keep every `<invoke` outside fenced code blocks, and name only tools available that turn — so quoted documentation is never executed.
+
 ## [16.4.4] - 2026-08-03
 
 ### Fixed

package/dist/types/dialect/index.d.ts

@@ -7,5 +7,6 @@ export * from "./history";
 export * from "./inventory";
 export * from "./owned-stream";
 export { renderDelimitedThinking } from "./rendering";
+export * from "./salvage";
 export * from "./thinking";
 export * from "./types";

package/dist/types/dialect/salvage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Recovery for tool calls a native-tool-calling model emitted as plain text.
+ *
+ * Symptom: the provider returns a normal `end_turn` whose visible text carries
+ * a fully-formed Anthropic-style `<invoke name="…">…</invoke>` block instead of
+ * native `tool_use` content. The turn then holds zero runnable tool calls, so
+ * the agent loop stops with the markup rendered verbatim to the user and the
+ * announced work never runs.
+ *
+ * This module re-materializes such a turn into real `toolCall` blocks using the
+ * same in-band scanner the owned-dialect path uses, so the loop dispatches them
+ * unchanged. It is deliberately conservative: a turn is salvaged ONLY when the
+ * markup is unambiguously a call the model meant to make (see
+ * {@link salvageLeakedToolCalls}), never when it is quoted documentation.
+ */
+import type { AssistantMessage, ToolCall } from "../types";
+import type { InbandTool } from "./types";
+export interface SalvagedToolCalls {
+    /** The rewritten turn: markup removed from text, real `toolCall` blocks appended. */
+    readonly message: AssistantMessage;
+    /** The calls recovered from the leaked markup, in emission order. */
+    readonly calls: readonly ToolCall[];
+}
+/**
+ * Recover tool calls a model wrote as visible text instead of native tool_use.
+ *
+ * Returns `undefined` unless EVERY guard holds — each one exists to keep a turn
+ * that merely *talks about* tool syntax from being executed:
+ *
+ * - The turn ended normally (`stop`). `length` may have truncated the markup
+ *   mid-argument, and `error`/`aborted` turns are already handled upstream.
+ * - The turn carries no native `toolCall` block. A model that called tools
+ *   natively AND quoted markup is documenting, not leaking.
+ * - At least one `<invoke` appears outside a fenced code block, and none appear
+ *   inside one. Fenced markup is quoted by construction; mixing the two is
+ *   ambiguous, so the whole turn is left alone.
+ * - The scanner recovers at least one call, and every recovered call names a
+ *   tool that is actually available this turn (matching `name` or
+ *   `customWireName`, mirroring the loop's own dispatch lookup).
+ *
+ * The caller decides what to do with the result; this function has no side
+ * effects and never mutates `message`.
+ */
+export declare function salvageLeakedToolCalls(message: AssistantMessage, tools: readonly InbandTool[] | undefined): SalvagedToolCalls | undefined;

package/dist/types/utils/fences.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fenced-code-block range computation shared by text scanners that must not
+ * trip on markup quoted inside ``` / ~~~ blocks (harmony-leak detection,
+ * leaked tool-call salvage).
+ */
+/** A `[start, end)` byte span covered by a fenced code block. */
+export type FenceRange = readonly [number, number];
+/**
+ * Precompute fenced-code-block ranges once per text. Each range is a
+ * [start, end) span of bytes inside any ```/~~~ fence. O(n) once instead of
+ * O(n) per detected match.
+ */
+export declare function computeFenceRanges(text: string): FenceRange[];
+export declare function isInsideFence(ranges: readonly FenceRange[], position: number): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "jeopi-ai",
-	"version": "16.4.4",
+	"version": "16.4.5",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://github.com/akillness/jeopi",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"jeopi-catalog": "16.4.4",
-		"jeopi-utils": "16.4.4",
-		"jeopi-wire": "16.4.4",
+		"jeopi-catalog": "16.4.5",
+		"jeopi-utils": "16.4.5",
+		"jeopi-wire": "16.4.5",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/dialect/index.ts

@@ -11,5 +11,6 @@ export * from "./owned-stream";
 // consumer needs (the legacy markdown `/dump` reuses its `<thinking>` envelope
 // unwrap), so re-export only that symbol rather than `export *`-ing the rest.
 export { renderDelimitedThinking } from "./rendering";
+export * from "./salvage";
 export * from "./thinking";
 export * from "./types";

package/src/dialect/salvage.ts

@@ -0,0 +1,90 @@
+/**
+ * Recovery for tool calls a native-tool-calling model emitted as plain text.
+ *
+ * Symptom: the provider returns a normal `end_turn` whose visible text carries
+ * a fully-formed Anthropic-style `<invoke name="…">…</invoke>` block instead of
+ * native `tool_use` content. The turn then holds zero runnable tool calls, so
+ * the agent loop stops with the markup rendered verbatim to the user and the
+ * announced work never runs.
+ *
+ * This module re-materializes such a turn into real `toolCall` blocks using the
+ * same in-band scanner the owned-dialect path uses, so the loop dispatches them
+ * unchanged. It is deliberately conservative: a turn is salvaged ONLY when the
+ * markup is unambiguously a call the model meant to make (see
+ * {@link salvageLeakedToolCalls}), never when it is quoted documentation.
+ */
+import type { AssistantMessage, ToolCall } from "../types";
+import { computeFenceRanges, isInsideFence } from "../utils/fences";
+import { parseInbandToolMessage } from "./owned-stream";
+import type { InbandTool } from "./types";
+
+/** Matches an opening invoke tag, with or without a dialect prefix (`x:invoke`). */
+const INVOKE_OPEN_RE = /<\s*(?:[A-Za-z_][\w.-]*:)?invoke\b/g;
+
+export interface SalvagedToolCalls {
+	/** The rewritten turn: markup removed from text, real `toolCall` blocks appended. */
+	readonly message: AssistantMessage;
+	/** The calls recovered from the leaked markup, in emission order. */
+	readonly calls: readonly ToolCall[];
+}
+
+/**
+ * Recover tool calls a model wrote as visible text instead of native tool_use.
+ *
+ * Returns `undefined` unless EVERY guard holds — each one exists to keep a turn
+ * that merely *talks about* tool syntax from being executed:
+ *
+ * - The turn ended normally (`stop`). `length` may have truncated the markup
+ *   mid-argument, and `error`/`aborted` turns are already handled upstream.
+ * - The turn carries no native `toolCall` block. A model that called tools
+ *   natively AND quoted markup is documenting, not leaking.
+ * - At least one `<invoke` appears outside a fenced code block, and none appear
+ *   inside one. Fenced markup is quoted by construction; mixing the two is
+ *   ambiguous, so the whole turn is left alone.
+ * - The scanner recovers at least one call, and every recovered call names a
+ *   tool that is actually available this turn (matching `name` or
+ *   `customWireName`, mirroring the loop's own dispatch lookup).
+ *
+ * The caller decides what to do with the result; this function has no side
+ * effects and never mutates `message`.
+ */
+export function salvageLeakedToolCalls(
+	message: AssistantMessage,
+	tools: readonly InbandTool[] | undefined,
+): SalvagedToolCalls | undefined {
+	if (message.stopReason !== "stop") return undefined;
+	if (!tools || tools.length === 0) return undefined;
+	if (message.content.some(block => block.type === "toolCall")) return undefined;
+
+	let text = "";
+	for (const block of message.content) {
+		if (block.type === "text") text += block.text;
+	}
+	if (text.length === 0) return undefined;
+
+	const fences = computeFenceRanges(text);
+	let bare = 0;
+	INVOKE_OPEN_RE.lastIndex = 0;
+	for (const match of text.matchAll(INVOKE_OPEN_RE)) {
+		if (isInsideFence(fences, match.index ?? 0)) return undefined;
+		bare++;
+	}
+	if (bare === 0) return undefined;
+
+	const parsed = parseInbandToolMessage(message, "anthropic", tools);
+	const calls = parsed.content.filter((block): block is ToolCall => block.type === "toolCall");
+	if (calls.length === 0) return undefined;
+
+	const available = new Set<string>();
+	for (const tool of tools) {
+		available.add(tool.name);
+		if (tool.customWireName !== undefined) available.add(tool.customWireName);
+	}
+	if (!calls.every(call => available.has(call.name))) return undefined;
+
+	// `stopReason` is restated rather than inherited: the projector happens to
+	// derive `toolUse` today, but this function's contract is "the loop must see
+	// a runnable tool turn, not a finished answer" — that must not silently
+	// depend on an internal of the owned-stream projector.
+	return { message: { ...parsed, stopReason: "toolUse" }, calls };
+}

package/src/utils/fences.ts

@@ -0,0 +1,48 @@
+/**
+ * Fenced-code-block range computation shared by text scanners that must not
+ * trip on markup quoted inside ``` / ~~~ blocks (harmony-leak detection,
+ * leaked tool-call salvage).
+ */
+
+const FENCE_RE = /^\s*(?:```+|~~~+)/;
+
+/** A `[start, end)` byte span covered by a fenced code block. */
+export type FenceRange = readonly [number, number];
+
+/**
+ * Precompute fenced-code-block ranges once per text. Each range is a
+ * [start, end) span of bytes inside any ```/~~~ fence. O(n) once instead of
+ * O(n) per detected match.
+ */
+export function computeFenceRanges(text: string): FenceRange[] {
+	const ranges: FenceRange[] = [];
+	let inFence = false;
+	let fenceStart = 0;
+	let lineStart = 0;
+	while (lineStart <= text.length) {
+		const newline = text.indexOf("\n", lineStart);
+		const lineEnd = newline === -1 ? text.length : newline;
+		const line = text.slice(lineStart, lineEnd);
+		if (FENCE_RE.test(line)) {
+			if (inFence) {
+				ranges.push([fenceStart, lineEnd]);
+				inFence = false;
+			} else {
+				fenceStart = lineStart;
+				inFence = true;
+			}
+		}
+		if (newline === -1) break;
+		lineStart = newline + 1;
+	}
+	if (inFence) ranges.push([fenceStart, text.length]);
+	return ranges;
+}
+
+export function isInsideFence(ranges: readonly FenceRange[], position: number): boolean {
+	for (const [start, end] of ranges) {
+		if (position >= start && position < end) return true;
+		if (start > position) break;
+	}
+	return false;
+}

package/src/utils/harmony-leak.ts

@@ -8,6 +8,7 @@
  * abort-and-retry handled by the agent loop.
  */
 import type { AssistantMessage, Model, ToolCall } from "../types";
+import { computeFenceRanges, isInsideFence } from "./fences";
 
 // Single source of truth for the marker pattern. `M` in the errata.
 // Use a fresh non-global instance for `.test()` to avoid lastIndex pitfalls.
@@ -29,8 +30,6 @@ const BODY_CASCADE_RE = /to=functions\.\w+\s+code\b[\s\S]{0,200}?to=functions\./
 // Fake-result framing (`R`): marker followed within 80 chars by Cell N: framing.
 const FAKE_RESULT_RE = /to=functions\.\w+[\s\S]{0,80}?code_output\s*\nCell\s+\d+:/;
 
-const FENCE_RE = /^\s*(?:```+|~~~+)/;
-
 // Non-Latin scripts seen in the corpus: CJK + ext, Cyrillic, Thai, Georgian,
 // Armenian, Kannada, Telugu, Devanagari, Arabic, Malayalam.
 const SCRIPT_CLASS =
@@ -342,44 +341,6 @@ function makeSignal(classes: HarmonySignalClass[], start: number, end: number, t
 	return { classes: sorted, start, end, text };
 }
 
-/**
- * Precompute fenced-code-block ranges once per text. Each range is a
- * [start, end) span of bytes inside any ```/~~~ fence. O(n) once instead of
- * O(n) per detected match.
- */
-function computeFenceRanges(text: string): Array<[number, number]> {
-	const ranges: Array<[number, number]> = [];
-	let inFence = false;
-	let fenceStart = 0;
-	let lineStart = 0;
-	while (lineStart <= text.length) {
-		const newline = text.indexOf("\n", lineStart);
-		const lineEnd = newline === -1 ? text.length : newline;
-		const line = text.slice(lineStart, lineEnd);
-		if (FENCE_RE.test(line)) {
-			if (inFence) {
-				ranges.push([fenceStart, lineEnd]);
-				inFence = false;
-			} else {
-				fenceStart = lineStart;
-				inFence = true;
-			}
-		}
-		if (newline === -1) break;
-		lineStart = newline + 1;
-	}
-	if (inFence) ranges.push([fenceStart, text.length]);
-	return ranges;
-}
-
-function isInsideFence(ranges: Array<[number, number]>, position: number): boolean {
-	for (const [start, end] of ranges) {
-		if (position >= start && position < end) return true;
-		if (start > position) break;
-	}
-	return false;
-}
-
 function hasScriptMismatchNear(text: string, start: number, end: number): boolean {
 	const near = text.slice(Math.max(0, start - 32), Math.min(text.length, end + 32));
 	if (!SCRIPT_RUN_RE.test(near)) return false;