@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/providers/mlx/textual-tool-call-salvage.js

@@ -0,0 +1,396 @@
+import { createLogger } from '@bendyline/gezel';
+import { findBareInvokeToolCallSpans, findClaudeInvokeToolCallSpans, findGlmToolCallSpans, findHermesFunctionToolCallSpans, findHermesFunctionToolCallSpansLenient, findProseToolCallSpans, findShellToolCallSpans, findTruncatedJsonEnvelope, findUnrecognizedToolEnvelope, findXmlTagToolCallSpans, isPayloadMutationToolName, isWriteShapedToolName, parseJsonEnvelopeToolCalls, salvageWriteShapedTruncation, stripBareInvokeToolCallsFromText, stripClaudeInvokeToolCallsFromText, stripGlmToolCallsFromText, stripHermesFunctionToolCallsFromText, stripJsonEnvelopesFromText, stripProseToolCallsFromText, stripShellToolCallsFromText, stripXmlTagToolCallsFromText, } from '../local-tool-call-salvage.js';
+const log = createLogger('mlx');
+/**
+ * The salvage passes that read tool calls out of a generation's visible text,
+ * run after the structured calls and the stripped-marker repair. Each pass is
+ * gated on every earlier one having found nothing, so one intent never fires
+ * twice. Truncated calls are reported through `truncatedCallIds` and
+ * `droppedTruncatedPayloadCalls`, which the tool loop reads afterwards.
+ */
+export function salvageTextualToolCalls(input) {
+    const { knownToolNames, seq, turn, structuredCalls, repairedCalls, codeBlockRepaired, truncatedCallIds, droppedTruncatedPayloadCalls, emitWarning, } = input;
+    let turnContent = input.turnContent;
+    let unknownCall = null;
+    // Third salvage path: small models sometimes emit
+    // `name(args)` directly in their text — usually inside a
+    // markdown code block — instead of issuing a real
+    // function-call. The stripper misses it (no `<|tool_call|>`
+    // markers) and the user sees the call rendered as decoration
+    // while nothing happens. If no real or marker-repaired calls
+    // fired this turn, scan the streamed text for a prose-shaped
+    // call and promote it. Strict gating (known-tools set + JSON
+    // parse) prevents false positives.
+    const proseRepaired = [];
+    if (structuredCalls.length === 0 && repairedCalls.length === 0 && turnContent.length > 0) {
+        const parsedSpans = findProseToolCallSpans(turnContent, knownToolNames);
+        for (const [idx, parsed] of parsedSpans.entries()) {
+            proseRepaired.push({
+                id: `prose-repair-${seq}-${turn}-${idx}`,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+        }
+        if (parsedSpans.length > 0) {
+            // Strip every prose body (and any wrapping ```fence```)
+            // so the persisted assistant bubble doesn't show the
+            // calls as decoration alongside the actual tool widgets.
+            turnContent = stripProseToolCallsFromText(turnContent, parsedSpans);
+        }
+        else if (/[a-zA-Z_][a-zA-Z0-9_]*\s*\(/.test(turnContent)) {
+            // Diagnostic: the content has SHAPE that looks like a
+            // tool call (an identifier followed by `(`) but the
+            // salvage parser found nothing. Surface a debug-level
+            // preview so a regression here is visible in the daemon
+            // log without re-running the whole eval. The match
+            // could be JS / Python / prose narration — the regex
+            // alone isn't enough to promote, but it's a strong
+            // signal that the parser missed something the model
+            // intended as a call.
+            const match = turnContent.match(/([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/);
+            const wanted = match?.[1] ?? '?';
+            const headPos = Math.max(0, (match?.index ?? 0) - 40);
+            const preview = turnContent.slice(headPos, headPos + 240).replace(/\s+/g, ' ');
+            log.debug(`turn#${seq}.${turn} prose-salvage found 0 spans despite \`${wanted}(\`-shaped text — preview: ${preview}`);
+        }
+    }
+    // Fourth salvage path: Anthropic-style XML self-closing tags
+    // (`<browser_navigate url="..." />`). Wild-caught on Qwen 3.6
+    // 27B at MLX after the `<|tool_call|>` channel was closed off
+    // via prompt — the model picks the next-most-familiar tool-use
+    // shape from training data. Run before the JSON envelope
+    // salvage so a tag like `<list_projects />` isn't mis-parsed
+    // by the JSON walker.
+    const xmlTagRepaired = [];
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        turnContent.length > 0) {
+        const xmlSpans = findXmlTagToolCallSpans(turnContent, knownToolNames);
+        for (const [idx, parsed] of xmlSpans.entries()) {
+            xmlTagRepaired.push({
+                id: `xml-tag-repair-${seq}-${turn}-${idx}`,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+        }
+        if (xmlSpans.length > 0) {
+            turnContent = stripXmlTagToolCallsFromText(turnContent, xmlSpans);
+        }
+    }
+    // Anthropic-style `<function_calls><invoke name="X">...</invoke></function_calls>`
+    // markup. The literal Claude tool-use XML format that Qwen
+    // 3.6 reaches for after the simpler self-closing XML form is
+    // closed off. Parameters arrive as nested
+    // `<parameter name="K">value</parameter>` elements.
+    const claudeInvokeRepaired = [];
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        turnContent.length > 0) {
+        const invokeSpans = findClaudeInvokeToolCallSpans(turnContent, knownToolNames);
+        for (const [idx, parsed] of invokeSpans.entries()) {
+            claudeInvokeRepaired.push({
+                id: `claude-invoke-repair-${seq}-${turn}-${idx}`,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+        }
+        if (invokeSpans.length > 0) {
+            turnContent = stripClaudeInvokeToolCallsFromText(turnContent, invokeSpans);
+        }
+    }
+    // GLM-4.5/4.6 native `<tool_call>NAME<arg_key>K</arg_key><arg_value>V</arg_value></tool_call>`
+    // markup. GLM-family models (laguna-s-118b, a GLM-4.5-Air
+    // derivative) emit this verbatim as content on the MLX textual
+    // path — no `<function=`, no `="`, so none of the shapes above
+    // match it and the turn stalls with zero tool calls. Run before
+    // the Hermes/shell paths (both key on `<tool_call>` too, but on
+    // `<function=` / `name key="value"` bodies GLM never produces).
+    const glmRepaired = [];
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        claudeInvokeRepaired.length === 0 &&
+        turnContent.length > 0) {
+        const glmSpans = findGlmToolCallSpans(turnContent, knownToolNames);
+        for (const [idx, parsed] of glmSpans.entries()) {
+            if (parsed.truncated && !isWriteShapedToolName(parsed.name)) {
+                emitWarning(`The model's \`${parsed.name}\` call was cut off mid-stream and was skipped so a partial mutation could not land. Retry with a smaller payload.`);
+                if (isPayloadMutationToolName(parsed.name)) {
+                    droppedTruncatedPayloadCalls.push({ name: parsed.name, args: parsed.arguments });
+                }
+                continue;
+            }
+            const id = `glm-repair-${seq}-${turn}-${idx}`;
+            glmRepaired.push({
+                id,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+            if (parsed.truncated)
+                truncatedCallIds.add(id);
+        }
+        if (glmSpans.length > 0) {
+            turnContent = stripGlmToolCallsFromText(turnContent, glmSpans);
+        }
+    }
+    // Hermes-2-Pro / Functionary `<function=NAME><parameter=K>V</parameter></function>`
+    // markup, often wrapped in Qwen's canonical `<tool_call>`
+    // envelope (Qwen 3.6 has been trained on both corpora and at
+    // heavy quant mixes them).
+    const hermesRepaired = [];
+    // Ids of synthesized tool calls whose underlying salvage span
+    // was marked `truncated` — the bridge will execute them with
+    // whatever content arrived, then we'll append an
+    // auto-continuation hint to the tool's result so the model
+    // knows to call the tool again with the remaining bytes.
+    // Cleared and rebuilt every iteration; consumed in the
+    // tool-execution loop further down.
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        claudeInvokeRepaired.length === 0 &&
+        glmRepaired.length === 0 &&
+        turnContent.length > 0) {
+        let hermesSpans = findHermesFunctionToolCallSpans(turnContent, knownToolNames);
+        if (hermesSpans.length === 0 && /<function=/i.test(turnContent)) {
+            // Streaming-truncated case (Qwen 3.6 27B write_file bodies
+            // that exceed max_tokens): the strict regex needs
+            // `</parameter>` + `</function>` closers, the lenient
+            // parser accepts the open-only shape and extends the last
+            // parameter value to EOF. Gated on the cheap text-contains
+            // check so prose unrelated to tool calls isn't re-scanned.
+            const lenient = findHermesFunctionToolCallSpansLenient(turnContent, knownToolNames);
+            if (lenient.length > 0) {
+                log.info(`turn#${seq}.${turn} salvaged ${lenient.length} Hermes-style tool call(s) via lenient parser (truncated stream): ${lenient.map((s) => s.name).join(', ')}`);
+                hermesSpans = lenient;
+            }
+        }
+        for (const [idx, parsed] of hermesSpans.entries()) {
+            if (parsed.truncated && !isWriteShapedToolName(parsed.name)) {
+                emitWarning(`The model's \`${parsed.name}\` call was cut off mid-stream and was skipped so a partial mutation could not land. Retry with a smaller payload.`);
+                if (isPayloadMutationToolName(parsed.name)) {
+                    droppedTruncatedPayloadCalls.push({ name: parsed.name, args: parsed.arguments });
+                }
+                continue;
+            }
+            const id = `hermes-repair-${seq}-${turn}-${idx}`;
+            hermesRepaired.push({
+                id,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+            if (parsed.truncated)
+                truncatedCallIds.add(id);
+        }
+        if (hermesSpans.length > 0) {
+            turnContent = stripHermesFunctionToolCallsFromText(turnContent, hermesSpans);
+        }
+    }
+    // Shell-style `<tool_call>name key="value"` per line, no
+    // close tag, no JSON envelope. The most degraded form of
+    // Qwen's canonical `<tool_call>` template — wild-caught on
+    // Qwen 3.6 27B at heavy quant after the canonical, XML, and
+    // Claude-invoke shapes were all closed off via prompt.
+    const shellRepaired = [];
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        claudeInvokeRepaired.length === 0 &&
+        glmRepaired.length === 0 &&
+        hermesRepaired.length === 0 &&
+        turnContent.length > 0) {
+        const shellSpans = findShellToolCallSpans(turnContent, knownToolNames);
+        for (const [idx, parsed] of shellSpans.entries()) {
+            shellRepaired.push({
+                id: `shell-repair-${seq}-${turn}-${idx}`,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+        }
+        if (shellSpans.length > 0) {
+            turnContent = stripShellToolCallsFromText(turnContent, shellSpans);
+        }
+    }
+    // Fifth salvage path: JSON-envelope shape some small models
+    // (Qwen 3.5/3.6) emit verbatim — `{"tool": "X", "args": {}}`
+    // typically inside a markdown json fence — instead of a real
+    // `tool_calls` event. Promote it the same way as the prose
+    // salvage. Gated on no other salvage having fired so we don't
+    // double-issue when the model coincidentally emitted both.
+    //
+    // We extract *every* envelope in the streamed content (Qwen
+    // sometimes chains multiple back-to-back) and surface a
+    // truncation warning when the model stopped mid-envelope —
+    // both fixes for the user-visible "only the first call fires
+    // and then it stops" symptom.
+    const envelopeRepaired = [];
+    let envelopeTruncated = null;
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        claudeInvokeRepaired.length === 0 &&
+        glmRepaired.length === 0 &&
+        hermesRepaired.length === 0 &&
+        shellRepaired.length === 0 &&
+        turnContent.length > 0) {
+        const parsedCalls = parseJsonEnvelopeToolCalls(turnContent, knownToolNames);
+        envelopeTruncated = findTruncatedJsonEnvelope(turnContent);
+        for (const [idx, parsed] of parsedCalls.entries()) {
+            envelopeRepaired.push({
+                id: `json-envelope-repair-${seq}-${turn}-${idx}`,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+        }
+        if (envelopeRepaired.length > 0 || envelopeTruncated) {
+            // Strip every salvaged envelope (and any truncated tail)
+            // from visible content so the user doesn't see the call
+            // body rendered alongside the actual tool bubbles.
+            turnContent = stripJsonEnvelopesFromText(turnContent, parsedCalls, envelopeTruncated?.matchStart);
+        }
+    }
+    // Hide unrecognized-name JSON envelopes from the bubble even
+    // though we can't promote them. The downstream "Did you mean…?"
+    // branch will retry on the model's behalf; surfacing the failed
+    // first attempt as raw JSON in the user's view is just noise.
+    // Detection is done here (vs. inside the retry branch below)
+    // so the strip runs before `fullText += turnContent`.
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        claudeInvokeRepaired.length === 0 &&
+        glmRepaired.length === 0 &&
+        hermesRepaired.length === 0 &&
+        shellRepaired.length === 0 &&
+        envelopeRepaired.length === 0 &&
+        !envelopeTruncated &&
+        turnContent.length > 0) {
+        const miss = findUnrecognizedToolEnvelope(turnContent, knownToolNames);
+        unknownCall = miss;
+        if (miss) {
+            turnContent = stripJsonEnvelopesFromText(turnContent, [
+                { matchStart: miss.matchStart, matchEnd: miss.matchEnd },
+            ]);
+        }
+    }
+    // Truncation-with-partial-args salvage. When the model started
+    // a write-shaped call (`write_file`, `write_artifact`,
+    // `append_to_file`) but the stream ended mid-content, promote
+    // the partial body to a synthesized tool_call so the bytes
+    // we DID receive land on disk — and tag the call id as
+    // truncated so the tool-result auto-continuation hint below
+    // tells the model to issue `append_to_file` for the missing
+    // tail. Shared logic with Ollama + llama-cpp providers via
+    // {@link salvageWriteShapedTruncation}.
+    //
+    // Gating: only fires when NO other salvage produced a call
+    // for this iteration (otherwise we'd double-fire the same
+    // intent).
+    const truncatedSalvage = [];
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        claudeInvokeRepaired.length === 0 &&
+        glmRepaired.length === 0 &&
+        hermesRepaired.length === 0 &&
+        shellRepaired.length === 0 &&
+        envelopeRepaired.length === 0 &&
+        turnContent.length > 0) {
+        const salvage = salvageWriteShapedTruncation(turnContent, knownToolNames, `truncated-salvage-mlx-${seq}-${turn}`);
+        if (salvage.synthesizedCall) {
+            const s = salvage.synthesizedCall;
+            truncatedSalvage.push({
+                id: s.id,
+                type: 'function',
+                function: {
+                    name: s.name,
+                    arguments: JSON.stringify(s.argsObject),
+                },
+            });
+            truncatedCallIds.add(s.id);
+            log.info(`turn#${seq}.${turn} salvaged truncated ${s.name} call (path=${s.argsObject.path}, partial=${s.argsObject.content.length} bytes) — continuation hint will fire on the tool result`);
+            turnContent = salvage.strippedContent;
+            // Clear envelopeTruncated so the post-loop warning path
+            // doesn't ALSO fire — we've handled this truncation as a
+            // real salvage now.
+            envelopeTruncated = null;
+        }
+    }
+    // Bare `invoke NAME {json}` — a weak-model prose shape (wild-caught
+    // on gemma4-e2b-q4/MLX) that no earlier layer recognizes: the model
+    // never emits Gemma's `<|tool_call>` trigger so the grammar can't
+    // engage, and it narrates the call as `invoke write_file {…}` instead.
+    // Last-resort salvage, gated on nothing else having fired.
+    const bareInvokeRepaired = [];
+    if (structuredCalls.length === 0 &&
+        repairedCalls.length === 0 &&
+        proseRepaired.length === 0 &&
+        xmlTagRepaired.length === 0 &&
+        claudeInvokeRepaired.length === 0 &&
+        glmRepaired.length === 0 &&
+        hermesRepaired.length === 0 &&
+        shellRepaired.length === 0 &&
+        envelopeRepaired.length === 0 &&
+        truncatedSalvage.length === 0 &&
+        codeBlockRepaired.length === 0 &&
+        turnContent.length > 0) {
+        const bareSpans = findBareInvokeToolCallSpans(turnContent, knownToolNames);
+        for (const [idx, parsed] of bareSpans.entries()) {
+            bareInvokeRepaired.push({
+                id: `bare-invoke-repair-${seq}-${turn}-${idx}`,
+                type: 'function',
+                function: {
+                    name: parsed.name,
+                    arguments: JSON.stringify(parsed.arguments),
+                },
+            });
+        }
+        if (bareSpans.length > 0) {
+            turnContent = stripBareInvokeToolCallsFromText(turnContent, bareSpans);
+        }
+    }
+    return {
+        turnContent,
+        proseRepaired,
+        xmlTagRepaired,
+        claudeInvokeRepaired,
+        glmRepaired,
+        hermesRepaired,
+        shellRepaired,
+        envelopeRepaired,
+        envelopeTruncated,
+        unknownCall,
+        truncatedSalvage,
+        bareInvokeRepaired,
+    };
+}

package/dist/providers/mlx/tool-call-protocol.d.ts

@@ -0,0 +1,65 @@
+import type { ToolExecutor } from '../tool-executor.js';
+import type { ExternalToolSpec } from '../types.js';
+export interface ChatCompletionTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: unknown;
+    };
+}
+export interface ToolCallDelta {
+    index: number;
+    id?: string;
+    type?: 'function';
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}
+export declare const APPEND_TO_FILE_CONTINUATION_TOOL: ChatCompletionTool;
+export declare function chatCompletionToolName(tool: ChatCompletionTool): string | undefined;
+/**
+ * Names of the advertised `tools` the session may call this turn. Differs
+ * from the advertised set only under a callable restriction — see
+ * `ToolExecutor.isRestrictedFromCalling`. Caller-executed external tools
+ * never resolve to a bridge, so they always stay callable.
+ */
+export declare function callableRequestToolNames(tools: readonly ChatCompletionTool[] | undefined, bridges: ToolExecutor): string[];
+/**
+ * Narrow the engine's tool grammar to what the session may call while the
+ * request keeps advertising every tool: `body.tools` is rendered into the
+ * prompt, so narrowing it instead would rewrite the prompt and cost a full
+ * re-prefill on an untrimmable cache. No-op without a restriction or a
+ * grammar hint.
+ */
+export declare function applyCallableToolGrammar(body: Record<string, unknown>, bridges: ToolExecutor): void;
+/**
+ * Required top-level properties absent from one parsed tool call.
+ *
+ * This deliberately checks presence only. A present-but-wrongly-typed value
+ * remains the MCP validator's job; the MLX Hermes grammar promises only that
+ * every declared required key is emitted before the call can close. Seeing a
+ * missing key is therefore evidence that the live constrained-decoding path
+ * broke its own contract, not an ordinary model validation miss.
+ */
+export declare function missingTopLevelRequiredToolArgs(schema: Record<string, unknown> | undefined, args: Record<string, unknown>): string[];
+export declare function hermesRequiredArgGrammarRequested(body: Record<string, unknown>): boolean;
+export declare function validatorReportedMissingRequiredArgs(output: string): boolean;
+/** OpenAI-compatible streaming tool-call accumulator used by the MLX provider. */
+export declare class MlxToolCallAccumulator {
+    private readonly byIndex;
+    size(): number;
+    ingest(delta: ToolCallDelta): void;
+    finalize(): Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+export declare function toChatCompletionsTools(bridges: ToolExecutor): ChatCompletionTool[];
+/** Caller-executed tools (see `SessionOpts.externalTools`) in the same shape. */
+export declare function externalToolsAsChatCompletions(tools: readonly ExternalToolSpec[] | undefined): ChatCompletionTool[];

package/dist/providers/mlx/tool-call-protocol.js

@@ -0,0 +1,140 @@
+// Minimal `append_to_file` surfaced ONLY during a write-continuation. The
+// base immediate-write surface is write_file-only; on truncation we add
+// this so the model can emit the file's missing tail instead of
+// re-writing the whole thing (which would just truncate again).
+// Constructed inline so it doesn't depend on the role-filtered bridge
+// surface, which deliberately hides append_to_file from builders.
+export const APPEND_TO_FILE_CONTINUATION_TOOL = {
+    type: 'function',
+    function: {
+        name: 'append_to_file',
+        description: 'Append text to the END of an existing workspace file. Use this to write the remaining tail of a file whose previous write_file was truncated mid-content. Do not repeat content already on disk — start exactly where the file currently ends.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Workspace-relative path of the file to append to.' },
+                content: {
+                    type: 'string',
+                    description: 'Text appended verbatim at the current end of the file.',
+                },
+            },
+            required: ['path', 'content'],
+        },
+    },
+};
+export function chatCompletionToolName(tool) {
+    return tool.function.name;
+}
+/**
+ * Names of the advertised `tools` the session may call this turn. Differs
+ * from the advertised set only under a callable restriction — see
+ * `ToolExecutor.isRestrictedFromCalling`. Caller-executed external tools
+ * never resolve to a bridge, so they always stay callable.
+ */
+export function callableRequestToolNames(tools, bridges) {
+    return (tools ?? [])
+        .map((tool) => chatCompletionToolName(tool))
+        .filter((name) => !!name && !bridges.isRestrictedFromCalling(name));
+}
+/**
+ * Narrow the engine's tool grammar to what the session may call while the
+ * request keeps advertising every tool: `body.tools` is rendered into the
+ * prompt, so narrowing it instead would rewrite the prompt and cost a full
+ * re-prefill on an untrimmable cache. No-op without a restriction or a
+ * grammar hint.
+ */
+export function applyCallableToolGrammar(body, bridges) {
+    const hint = body.tool_grammar;
+    if (!bridges.hasCallableRestriction() || !hint || typeof hint !== 'object')
+        return;
+    if (!Array.isArray(body.tools))
+        return;
+    body.tool_grammar = {
+        ...hint,
+        allowed_names: callableRequestToolNames(body.tools, bridges),
+    };
+}
+/**
+ * Required top-level properties absent from one parsed tool call.
+ *
+ * This deliberately checks presence only. A present-but-wrongly-typed value
+ * remains the MCP validator's job; the MLX Hermes grammar promises only that
+ * every declared required key is emitted before the call can close. Seeing a
+ * missing key is therefore evidence that the live constrained-decoding path
+ * broke its own contract, not an ordinary model validation miss.
+ */
+export function missingTopLevelRequiredToolArgs(schema, args) {
+    const required = schema?.required;
+    if (!Array.isArray(required))
+        return [];
+    const missing = [];
+    for (const key of required) {
+        if (typeof key === 'string' &&
+            !missing.includes(key) &&
+            !Object.prototype.hasOwnProperty.call(args, key)) {
+            missing.push(key);
+        }
+    }
+    return missing;
+}
+export function hermesRequiredArgGrammarRequested(body) {
+    const hint = body.tool_grammar;
+    if (!hint || typeof hint !== 'object' || Array.isArray(hint))
+        return false;
+    const record = hint;
+    return (record.format === 'hermes' && (record.mode === undefined || record.mode === 'name-and-params'));
+}
+export function validatorReportedMissingRequiredArgs(output) {
+    return /rejected by validator[\s\S]*missing required fields?:/i.test(output);
+}
+/** OpenAI-compatible streaming tool-call accumulator used by the MLX provider. */
+export class MlxToolCallAccumulator {
+    byIndex = new Map();
+    size() {
+        return this.byIndex.size;
+    }
+    ingest(delta) {
+        const idx = delta.index;
+        let entry = this.byIndex.get(idx);
+        if (!entry) {
+            entry = { id: '', name: '', arguments: '' };
+            this.byIndex.set(idx, entry);
+        }
+        if (delta.id)
+            entry.id = delta.id;
+        if (delta.function?.name)
+            entry.name = delta.function.name;
+        if (delta.function?.arguments)
+            entry.arguments += delta.function.arguments;
+    }
+    finalize() {
+        return Array.from(this.byIndex.entries())
+            .sort((a, b) => a[0] - b[0])
+            .map(([, v]) => ({
+            id: v.id,
+            type: 'function',
+            function: { name: v.name, arguments: v.arguments },
+        }));
+    }
+}
+export function toChatCompletionsTools(bridges) {
+    return bridges.getOpenAITools().map((tool) => ({
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        },
+    }));
+}
+/** Caller-executed tools (see `SessionOpts.externalTools`) in the same shape. */
+export function externalToolsAsChatCompletions(tools) {
+    return (tools ?? []).map((tool) => ({
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description ?? '',
+            parameters: tool.parameters,
+        },
+    }));
+}

package/dist/providers/mlx/tool-call-stripper.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Streaming-safe filter for chat-template tool-call markers that leak
+ * into mlx_vlm.server's content stream.
+ *
+ * Gemma 3+ tokenizers emit tool calls with literal special-token text
+ * when the chat template doesn't fully consume them. Two open variants
+ * have been observed in the wild:
+ *
+ *   `<|tool_call|>` — canonical, what the chat template SHOULD emit
+ *   `<|tool_call>`  — short form, missing the trailing `|>`; appears on
+ *                     tighter quants of Gemma 4 E4B
+ *
+ * Close has four observed variants: `<tool_call|>`, `</tool_call|>`,
+ * `<tool_call>`, `</tool_call>`. We accept all four.
+ *
+ * mlx_vlm.server still ships a structured `tool_calls` delta when the
+ * markers parse cleanly, but ALSO leaks the raw text. The structured
+ * call is what we want; the text is noise. Stripped bodies are kept on
+ * the side so a second pass can attempt repair (`parseGemmaToolCall`)
+ * before falling back to a user-visible warning.
+ *
+ * Streaming safety: deltas can split markers across chunk boundaries,
+ * so we hold back any tail that could be a prefix of any open variant
+ * until enough additional bytes arrive to disambiguate. End-of-turn
+ * `flush()` drops anything still inside an unclosed marker (treats it
+ * as truncated noise).
+ */
+export declare class LeakyToolCallStripper {
+    private buffer;
+    private inside;
+    private currentBody;
+    private readonly bodies;
+    /**
+     * Indices into {@link bodies} that came from an EOS-flush (no
+     * `</tool_call>` close marker arrived before the stream ended).
+     * Layer 3 reads this to decide whether a successfully-parsed Gemma
+     * marker call should also be tagged as truncated — its `content`
+     * arg may be partial, in which case the auto-continuation hint
+     * should fire on the tool result.
+     */
+    private readonly eosFlushedIndices;
+    /**
+     * Push a streamed chunk and return whatever's safe to emit. Holds
+     * back any trailing fragment that could be the start of a marker
+     * until enough additional bytes arrive to disambiguate.
+     */
+    push(chunk: string): string;
+    /**
+     * Final drain at end-of-turn. If we're still mid-marker the model
+     * never finished closing it — drop the buffered content as noise
+     * rather than leak a half-marker.
+     */
+    flush(): string;
+    /**
+     * Bodies of all complete (or unclosed-at-flush) marker spans seen
+     * this stream. Surface area for `parseGemmaToolCall`.
+     */
+    getStrippedBodies(): readonly string[];
+    /**
+     * Indices into {@link getStrippedBodies}() that came from an
+     * EOS-flush — i.e. the close marker never arrived. Used by the
+     * provider's Layer 3 truncation-salvage logic to tag those parsed
+     * calls with the continuation-hint behavior even when they parsed
+     * successfully (since their string args may be partial).
+     */
+    getEosFlushedBodyIndices(): ReadonlySet<number>;
+    private drain;
+}