@qvac/sdk 0.10.0 → 0.10.2

package/dist/server/utils/completion-normalizer.js

@@ -1,14 +1,14 @@
 import { parseToolCalls } from "./tools/index.js";
 const DIALECT_SPECS = {
     hermes: {
-        frames: [{ open: "<tool_call>", close: "</tool_call>" }],
+        toolFrames: [{ open: "<tool_call>", close: "</tool_call>" }],
     },
     // No streaming framing — tool calls are only recovered at finalization.
     json: {
-        frames: [],
+        toolFrames: [],
     },
     pythonic: {
-        frames: [
+        toolFrames: [
             { open: "<|tool_call_start|>", close: "<|tool_call_end|>" },
             {
                 open: "<|start_header_id|>tool_call<|end_header_id|>",
@@ -16,36 +16,90 @@ const DIALECT_SPECS = {
             },
         ],
     },
+    harmony: {
+        toolFrames: [
+            { open: "<|channel|>commentary to=functions.", close: "<|call|>" },
+        ],
+        thinkingFrames: [
+            { open: "<|channel|>analysis<|message|>", close: "<|end|>" },
+        ],
+        contentFrames: [
+            { open: "<|channel|>final<|message|>", close: "<|return|>" },
+        ],
+        // Role headers between channel frames + stray `<|return|>` closes.
+        dropTokens: [
+            "<|start|>assistant",
+            "<|start|>system",
+            "<|start|>user",
+            "<|return|>",
+        ],
+    },
 };
-const THINK_OPEN = "<think>";
-const THINK_CLOSE = "</think>";
+// Capture-gated reasoning marker — the generic `<think>...</think>`
+// convention used by reasoning-tuned models. When the gate is off the
+// markers pass through into `contentDelta` unchanged (preserves the
+// pre-dialect behavior).
+const BUILTIN_THINKING = { open: "<think>", close: "</think>" };
 export function createCompletionNormalizer(config) {
     let seq = 0;
     let state = "content";
     let rawText = "";
     const contentParts = [];
     const thinkingParts = [];
-    // Frame buffer keeps the open + close markers in place so parseToolCalls
-    // can match its own dialect markers.
+    // Tool frame: buffer keeps the open + close markers in place so
+    // `parseToolCalls` can match its own dialect markers.
     let toolCallBuffer = "";
-    let activeFrame = null;
+    let activeToolFrame = null;
+    // Thinking frame: tracks which frame's close marker we're scanning for
+    // (could be the built-in `<think>` or a dialect-specific frame like
+    // Harmony's `<|channel|>analysis<|message|>...<|end|>`).
+    let activeThinkingFrame = null;
+    // Content frame: inner streamed as it arrives; partial close tail buffered.
+    let activeContentFrame = null;
     // Trailing chars that could be a prefix of a watched marker, so markers
     // split across token pushes aren't missed by indexOf.
     let contentTail = "";
-    let toolTail = "";
-    let thinkingTail = "";
+    let toolFramingTail = "";
+    let thinkingFramingTail = "";
+    let contentFramingTail = "";
     const streamedToolCallKeys = new Set();
     const toolsEnabled = config.tools.length > 0 && config.capabilities.toolCalling !== "none";
-    const useFramedParsing = toolsEnabled && config.capabilities.toolCalling === "textParse";
-    const useThinkingParsing = config.captureThinking && config.capabilities.thinkingFraming === "thinkTags";
+    const useToolFraming = toolsEnabled && config.capabilities.toolCalling === "textParse";
+    // Register `<think>` only when both capability + capture opt in.
+    // Dialect protocol markers always register; capture only gates emission.
+    const useBuiltinThinkTags = config.captureThinking &&
+        config.capabilities.thinkingFraming === "thinkTags";
     const dialect = config.toolDialect ?? "hermes";
     const dialectSpec = DIALECT_SPECS[dialect];
-    const frameSpecs = useFramedParsing ? dialectSpec.frames : [];
+    const toolFrames = useToolFraming
+        ? dialectSpec.toolFrames
+        : [];
+    const thinkingFrames = [
+        ...(useBuiltinThinkTags ? [BUILTIN_THINKING] : []),
+        ...(dialectSpec.thinkingFrames ?? []),
+    ];
+    const contentFrames = dialectSpec.contentFrames ?? [];
+    const dropTokens = dialectSpec.dropTokens ?? [];
+    const markerToEntry = new Map();
+    const dropTokenSet = new Set();
     const contentMarkers = [];
-    if (useThinkingParsing)
-        contentMarkers.push(THINK_OPEN);
-    for (const f of frameSpecs)
-        contentMarkers.push(f.open);
+    function registerFrames(frames, kind) {
+        for (const f of frames) {
+            if (markerToEntry.has(f.open))
+                continue;
+            markerToEntry.set(f.open, { kind, spec: f });
+            contentMarkers.push(f.open);
+        }
+    }
+    registerFrames(toolFrames, "tool");
+    registerFrames(thinkingFrames, "thinking");
+    registerFrames(contentFrames, "content");
+    for (const t of dropTokens) {
+        if (markerToEntry.has(t) || dropTokenSet.has(t))
+            continue;
+        dropTokenSet.add(t);
+        contentMarkers.push(t);
+    }
     function nextSeq() {
         return seq++;
     }
@@ -55,11 +109,14 @@ export function createCompletionNormalizer(config) {
         contentParts.push(text);
         events.push({ type: "contentDelta", seq: nextSeq(), text });
     }
+    // Capture-gated: thinking frames may register even when `captureThinking`
+    // is false (e.g. harmony's analysis channel, to strip markers from
+    // `contentDelta`) — drop the inner here instead of buffering it.
     function emitThinking(events, text) {
         if (!text)
             return;
-        thinkingParts.push(text);
         if (config.captureThinking) {
+            thinkingParts.push(text);
             events.push({ type: "thinkingDelta", seq: nextSeq(), text });
         }
     }
@@ -102,10 +159,10 @@ export function createCompletionNormalizer(config) {
     }
     function flushToolBuffer(events, closed) {
         const raw = toolCallBuffer;
-        const frame = activeFrame;
+        const frame = activeToolFrame;
         toolCallBuffer = "";
-        activeFrame = null;
-        toolTail = "";
+        activeToolFrame = null;
+        toolFramingTail = "";
         if (!frame)
             return;
         // Empty-payload guard. Strip frame markers and check the inner is
@@ -150,64 +207,110 @@ export function createCompletionNormalizer(config) {
             emitContent(events, raw);
         }
     }
+    function getStateTail() {
+        switch (state) {
+            case "content":
+                return contentTail;
+            case "thinkingFraming":
+                return thinkingFramingTail;
+            case "toolFraming":
+                return toolFramingTail;
+            case "contentFraming":
+                return contentFramingTail;
+        }
+    }
     function processSegment(events, text) {
-        let buf = (state === "content"
-            ? contentTail
-            : state === "thinking"
-                ? thinkingTail
-                : toolTail) + text;
+        let buf = getStateTail() + text;
         contentTail = "";
-        thinkingTail = "";
-        toolTail = "";
+        thinkingFramingTail = "";
+        toolFramingTail = "";
+        contentFramingTail = "";
         while (buf.length > 0) {
-            if (state === "toolBuffering") {
-                if (!activeFrame) {
+            if (state === "toolFraming") {
+                if (!activeToolFrame) {
                     state = "content";
                     continue;
                 }
-                const hit = buf.indexOf(activeFrame.close);
+                const hit = buf.indexOf(activeToolFrame.close);
                 if (hit >= 0) {
-                    toolCallBuffer += buf.slice(0, hit + activeFrame.close.length);
-                    buf = buf.slice(hit + activeFrame.close.length);
+                    toolCallBuffer += buf.slice(0, hit + activeToolFrame.close.length);
+                    buf = buf.slice(hit + activeToolFrame.close.length);
                     state = "content";
                     flushToolBuffer(events, true);
                     continue;
                 }
-                const tailLen = trailingPartialMarkerLen(buf, [activeFrame.close]);
+                const tailLen = trailingPartialMarkerLen(buf, [activeToolFrame.close]);
                 const safeLen = buf.length - tailLen;
                 toolCallBuffer += buf.slice(0, safeLen);
-                toolTail = buf.slice(safeLen);
+                toolFramingTail = buf.slice(safeLen);
                 buf = "";
                 continue;
             }
-            if (state === "thinking") {
-                const closeIdx = buf.indexOf(THINK_CLOSE);
+            if (state === "thinkingFraming") {
+                if (!activeThinkingFrame) {
+                    state = "content";
+                    continue;
+                }
+                const closeMarker = activeThinkingFrame.close;
+                const closeIdx = buf.indexOf(closeMarker);
                 if (closeIdx >= 0) {
                     emitThinking(events, buf.slice(0, closeIdx));
-                    buf = buf.slice(closeIdx + THINK_CLOSE.length);
+                    buf = buf.slice(closeIdx + closeMarker.length);
+                    activeThinkingFrame = null;
                     state = "content";
                     continue;
                 }
-                const tailLen = trailingPartialMarkerLen(buf, [THINK_CLOSE]);
+                const tailLen = trailingPartialMarkerLen(buf, [closeMarker]);
                 const safeLen = buf.length - tailLen;
                 emitThinking(events, buf.slice(0, safeLen));
-                thinkingTail = buf.slice(safeLen);
+                thinkingFramingTail = buf.slice(safeLen);
+                buf = "";
+                continue;
+            }
+            if (state === "contentFraming") {
+                if (!activeContentFrame) {
+                    state = "content";
+                    continue;
+                }
+                const closeMarker = activeContentFrame.close;
+                const closeIdx = buf.indexOf(closeMarker);
+                if (closeIdx >= 0) {
+                    emitContent(events, buf.slice(0, closeIdx));
+                    activeContentFrame = null;
+                    contentFramingTail = "";
+                    buf = buf.slice(closeIdx + closeMarker.length);
+                    state = "content";
+                    continue;
+                }
+                const tailLen = trailingPartialMarkerLen(buf, [closeMarker]);
+                const safeLen = buf.length - tailLen;
+                emitContent(events, buf.slice(0, safeLen));
+                contentFramingTail = buf.slice(safeLen);
                 buf = "";
                 continue;
             }
             const hit = findEarliestMarker(buf, contentMarkers);
             if (hit) {
                 emitContent(events, buf.slice(0, hit.idx));
-                if (hit.marker === THINK_OPEN) {
-                    buf = buf.slice(hit.idx + hit.marker.length);
-                    state = "thinking";
+                buf = buf.slice(hit.idx + hit.marker.length);
+                if (dropTokenSet.has(hit.marker)) {
+                    // Glue token between frames — strip and stay in content state.
                     continue;
                 }
-                const spec = frameSpecs.find((f) => f.open === hit.marker);
-                toolCallBuffer = hit.marker;
-                activeFrame = spec;
-                buf = buf.slice(hit.idx + hit.marker.length);
-                state = "toolBuffering";
+                const entry = markerToEntry.get(hit.marker);
+                if (entry.kind === "tool") {
+                    toolCallBuffer = hit.marker;
+                    activeToolFrame = entry.spec;
+                    state = "toolFraming";
+                }
+                else if (entry.kind === "thinking") {
+                    activeThinkingFrame = entry.spec;
+                    state = "thinkingFraming";
+                }
+                else {
+                    activeContentFrame = entry.spec;
+                    state = "contentFraming";
+                }
                 continue;
             }
             const tailLen = trailingPartialMarkerLen(buf, contentMarkers);
@@ -234,24 +337,33 @@ export function createCompletionNormalizer(config) {
             emitContent(events, contentTail);
             contentTail = "";
         }
-        else if (state === "thinking" && thinkingTail) {
-            emitThinking(events, thinkingTail);
-            thinkingTail = "";
+        else if (state === "thinkingFraming" && thinkingFramingTail) {
+            emitThinking(events, thinkingFramingTail);
+            thinkingFramingTail = "";
         }
-        else if (state === "toolBuffering" && toolTail) {
-            toolCallBuffer += toolTail;
-            toolTail = "";
+        else if (state === "toolFraming" && toolFramingTail) {
+            toolCallBuffer += toolFramingTail;
+            toolFramingTail = "";
         }
-        if (state === "toolBuffering" && activeFrame) {
+        else if (state === "contentFraming" && contentFramingTail) {
+            // Cutoff inside a partial close marker — emit tail as content.
+            emitContent(events, contentFramingTail);
+            contentFramingTail = "";
+        }
+        if (state === "toolFraming" && activeToolFrame) {
             if (opts?.error) {
                 emitContent(events, toolCallBuffer);
                 toolCallBuffer = "";
-                activeFrame = null;
+                activeToolFrame = null;
             }
             else {
                 flushToolBuffer(events, false);
             }
         }
+        else if (state === "contentFraming") {
+            activeContentFrame = null;
+        }
+        activeThinkingFrame = null;
         state = "content";
         if (!opts?.error) {
             if (opts?.toolCalls) {

package/dist/server/utils/tools/dialect.js

@@ -6,6 +6,8 @@
 export function detectToolDialectFromName(name, path) {
     const basename = path.toLowerCase().split(/[/\\]/).pop() ?? "";
     const tag = `${(name ?? "").toLowerCase()}|${basename}`;
+    if (/gpt[_-]?oss/.test(tag))
+        return "harmony";
     if (/lfm[_-]?\d/.test(tag))
         return "pythonic";
     return "hermes";

package/dist/server/utils/tools/parser.js

@@ -2,6 +2,7 @@ import { stripThinkingBlocks, } from "./shared.js";
 import { parseGemmaFormat, parseGenericFormat, parseLlamacppFormat, } from "./parsers/json.js";
 import { parseHermesFormat } from "./parsers/hermes.js";
 import { parsePythonicFormat } from "./parsers/pythonic.js";
+import { parseHarmonyFormat } from "./parsers/harmony.js";
 function pickFormatParsers(dialect) {
     switch (dialect) {
         case "pythonic":
@@ -12,10 +13,15 @@ function pickFormatParsers(dialect) {
             return [parseHermesFormat, parseGemmaFormat, parseLlamacppFormat];
         case "json":
             return [parseGemmaFormat, parseLlamacppFormat];
+        case "harmony":
+            return [parseHarmonyFormat];
         default:
+            // Harmony first: `to=functions.` is uniquely Harmony and can't
+            // false-match other dialects.
             // Pythonic last: its bare `[name(...)]` form can match payloads that
             // look like other dialects.
             return [
+                parseHarmonyFormat,
                 parseHermesFormat,
                 parseGemmaFormat,
                 parseLlamacppFormat,

package/dist/server/utils/tools/parsers/harmony.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from "../../../../schemas/index";
+import { type ParserResult } from "../shared";
+export declare function parseHarmonyFormat(text: string, tools: Tool[]): ParserResult;
+//# sourceMappingURL=harmony.d.ts.map

package/dist/server/utils/tools/parsers/harmony.js

@@ -0,0 +1,59 @@
+import { generateStableToolCallId, validateToolArguments, } from "../shared.js";
+const HARMONY_FRAME_RE = /to=functions\.([\w-]+)\s+<\|constrain\|>json<\|message\|>([\s\S]*?)(?=<\|call\|>|$)/g;
+export function parseHarmonyFormat(text, tools) {
+    const toolCalls = [];
+    const errors = [];
+    if (!text.includes("to=functions.")) {
+        return { matched: false, toolCalls, errors };
+    }
+    HARMONY_FRAME_RE.lastIndex = 0;
+    let m;
+    while ((m = HARMONY_FRAME_RE.exec(text)) !== null) {
+        const name = m[1];
+        const payload = m[2]?.trim();
+        const raw = m[0];
+        if (!name || payload === undefined)
+            continue;
+        let parsedArgs;
+        try {
+            parsedArgs = JSON.parse(payload);
+        }
+        catch (error) {
+            errors.push({
+                code: "PARSE_ERROR",
+                message: `Failed to parse Harmony tool call JSON for ${name}: ${error instanceof Error ? error.message : String(error)}`,
+                raw,
+            });
+            continue;
+        }
+        if (typeof parsedArgs !== "object" ||
+            parsedArgs === null ||
+            Array.isArray(parsedArgs)) {
+            errors.push({
+                code: "PARSE_ERROR",
+                message: `Harmony tool call payload for ${name} is not a JSON object`,
+                raw,
+            });
+            continue;
+        }
+        const args = parsedArgs;
+        const validation = validateToolArguments(name, args, tools);
+        if (!validation.isValid && validation.error) {
+            errors.push({ ...validation.error, raw });
+            continue;
+        }
+        toolCalls.push({
+            id: generateStableToolCallId(name, args),
+            name,
+            arguments: args,
+            raw,
+        });
+    }
+    // Defer `matched` to extraction so partial Harmony shapes fall through
+    // to the next parser instead of short-circuiting the chain.
+    return {
+        matched: toolCalls.length > 0 || errors.length > 0,
+        toolCalls,
+        errors,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/sdk",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",