@qvac/sdk 0.9.1 → 0.10.0

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

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

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

@@ -0,0 +1,100 @@
+import { generateStableToolCallId, isValidToolCall, validateToolArguments, } from "../shared.js";
+// Hermes-style: JSON payload wrapped in `<tool_call>...</tool_call>` tags
+export function parseHermesFormat(text, tools) {
+    const toolCalls = [];
+    const errors = [];
+    if (!text.includes("<tool_call>")) {
+        return { matched: false, toolCalls, errors };
+    }
+    // Incomplete frame: open marker without close (cutoff/abort). Recover
+    // the inner buffer here — fallthrough to JSON parsers can't strip the
+    // `<tool_call>` prefix on its own.
+    if (!text.includes("</tool_call>")) {
+        return recoverIncompleteHermesFrame(text, tools);
+    }
+    const toolCallRegex = /<tool_call>\s*({[\s\S]*?})\s*<\/tool_call>/g;
+    const matches = Array.from(text.matchAll(toolCallRegex));
+    for (const match of matches) {
+        const callJson = match[1];
+        if (!callJson)
+            continue;
+        const trimmedJson = callJson.trim();
+        let callItem;
+        try {
+            callItem = JSON.parse(trimmedJson);
+        }
+        catch (error) {
+            errors.push({
+                code: "PARSE_ERROR",
+                message: `Failed to parse Hermes tool call: ${error instanceof Error ? error.message : String(error)}`,
+                raw: trimmedJson,
+            });
+            continue;
+        }
+        if (!isValidToolCall(callItem)) {
+            errors.push({
+                code: "PARSE_ERROR",
+                message: "Hermes tool call is missing name/arguments",
+                raw: trimmedJson,
+            });
+            continue;
+        }
+        const call = callItem;
+        const validation = validateToolArguments(call.name, call.arguments, tools);
+        if (!validation.isValid && validation.error) {
+            errors.push({
+                ...validation.error,
+                raw: trimmedJson,
+            });
+            continue;
+        }
+        toolCalls.push({
+            id: call.id || generateStableToolCallId(call.name, call.arguments),
+            name: call.name,
+            arguments: call.arguments,
+            raw: trimmedJson,
+        });
+    }
+    return { matched: true, toolCalls, errors };
+}
+// Strips a possible truncated close-tag tail (`</tool`, `</tool_c`)
+// before parsing. Bounded to buffers that actually contain the open marker.
+function recoverIncompleteHermesFrame(text, tools) {
+    const openIdx = text.indexOf("<tool_call>");
+    const inner = text.slice(openIdx + "<tool_call>".length).trim();
+    const partialCloseIdx = inner.search(/<\/tool/);
+    const candidate = partialCloseIdx === -1 ? inner : inner.slice(0, partialCloseIdx).trim();
+    if (candidate.length === 0) {
+        return { matched: false, toolCalls: [], errors: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(candidate);
+    }
+    catch {
+        return { matched: false, toolCalls: [], errors: [] };
+    }
+    if (!isValidToolCall(parsed)) {
+        return { matched: false, toolCalls: [], errors: [] };
+    }
+    const validation = validateToolArguments(parsed.name, parsed.arguments, tools);
+    if (!validation.isValid && validation.error) {
+        return {
+            matched: true,
+            toolCalls: [],
+            errors: [{ ...validation.error, raw: candidate }],
+        };
+    }
+    return {
+        matched: true,
+        toolCalls: [
+            {
+                id: parsed.id || generateStableToolCallId(parsed.name, parsed.arguments),
+                name: parsed.name,
+                arguments: parsed.arguments,
+                raw: candidate,
+            },
+        ],
+        errors: [],
+    };
+}

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

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

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

@@ -0,0 +1,115 @@
+import { generateStableToolCallId, isValidToolCall, validateToolArguments, } from "../shared.js";
+export function parseGemmaFormat(text, tools) {
+    const toolCalls = [];
+    const errors = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { matched: false, toolCalls, errors };
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        !("tool_calls" in parsed) ||
+        !Array.isArray(parsed.tool_calls)) {
+        return { matched: false, toolCalls, errors };
+    }
+    for (const callItem of parsed.tool_calls) {
+        if (!isValidToolCall(callItem)) {
+            errors.push({
+                code: "PARSE_ERROR",
+                message: "Gemma tool_calls entry is missing name/arguments",
+                raw: JSON.stringify(callItem),
+            });
+            continue;
+        }
+        const call = callItem;
+        const validation = validateToolArguments(call.name, call.arguments, tools);
+        if (!validation.isValid && validation.error) {
+            errors.push({
+                ...validation.error,
+                raw: JSON.stringify(call),
+            });
+            continue;
+        }
+        toolCalls.push({
+            id: call.id || generateStableToolCallId(call.name, call.arguments),
+            name: call.name,
+            arguments: call.arguments,
+            raw: JSON.stringify(call),
+        });
+    }
+    return { matched: true, toolCalls, errors };
+}
+export function parseLlamacppFormat(text, tools) {
+    const toolCalls = [];
+    const errors = [];
+    let parsedItem;
+    try {
+        parsedItem = JSON.parse(text);
+    }
+    catch {
+        return { matched: false, toolCalls, errors };
+    }
+    if (!isValidToolCall(parsedItem)) {
+        return { matched: false, toolCalls, errors };
+    }
+    const parsed = parsedItem;
+    const validation = validateToolArguments(parsed.name, parsed.arguments, tools);
+    if (!validation.isValid && validation.error) {
+        errors.push({
+            ...validation.error,
+            raw: text,
+        });
+    }
+    else {
+        toolCalls.push({
+            id: parsed.id || generateStableToolCallId(parsed.name, parsed.arguments),
+            name: parsed.name,
+            arguments: parsed.arguments,
+            raw: text,
+        });
+    }
+    return { matched: true, toolCalls, errors };
+}
+// Last-resort fallback: loose JSON `{"name":..., "arguments":...}` objects
+// anywhere in the text. Runs after dialect-specific parsers all miss.
+export function parseGenericFormat(text, tools) {
+    const toolCalls = [];
+    const errors = [];
+    const jsonObjectRegex = /\{[\s\S]*?"name"[\s\S]*?"arguments"[\s\S]*?\}/g;
+    let match;
+    let matched = false;
+    while ((match = jsonObjectRegex.exec(text)) !== null) {
+        matched = true;
+        try {
+            const objItem = JSON.parse(match[0]);
+            if (isValidToolCall(objItem)) {
+                const obj = objItem;
+                const validation = validateToolArguments(obj.name, obj.arguments, tools);
+                if (!validation.isValid && validation.error) {
+                    errors.push({
+                        ...validation.error,
+                        raw: match[0],
+                    });
+                    continue;
+                }
+                toolCalls.push({
+                    id: obj.id || generateStableToolCallId(obj.name, obj.arguments),
+                    name: obj.name,
+                    arguments: obj.arguments,
+                    raw: match[0],
+                });
+            }
+        }
+        catch (error) {
+            errors.push({
+                code: "PARSE_ERROR",
+                message: `Failed to parse generic tool call: ${error instanceof Error ? error.message : String(error)}`,
+                raw: match[0],
+            });
+        }
+    }
+    return { matched, toolCalls, errors };
+}

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

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

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

@@ -0,0 +1,267 @@
+import { generateStableToolCallId, validateToolArguments, } from "../shared.js";
+// Pythonic `[name(k=v), ...]` arrays. LFM 2.x is auto-routed; Llama-style
+// tokens are kept for callers that opt in via `completion({ toolDialect:
+// "pythonic" })` for a model known to emit Pythonic. Pure string parsing —
+// no eval/vm/Function (untrusted model output).
+const PYTHONIC_LFM_OPEN = "<|tool_call_start|>";
+const PYTHONIC_LFM_CLOSE = "<|tool_call_end|>";
+const PYTHONIC_LLAMA_OPEN = "<|start_header_id|>tool_call<|end_header_id|>";
+const PYTHONIC_LLAMA_CLOSE = "<|eot_id|>";
+function locatePythonicCallList(text) {
+    const lfmStart = text.indexOf(PYTHONIC_LFM_OPEN);
+    if (lfmStart !== -1) {
+        const after = text.slice(lfmStart + PYTHONIC_LFM_OPEN.length);
+        const end = after.indexOf(PYTHONIC_LFM_CLOSE);
+        return end === -1 ? after : after.slice(0, end);
+    }
+    const llamaStart = text.indexOf(PYTHONIC_LLAMA_OPEN);
+    if (llamaStart !== -1) {
+        const after = text.slice(llamaStart + PYTHONIC_LLAMA_OPEN.length);
+        const end = after.indexOf(PYTHONIC_LLAMA_CLOSE);
+        return end === -1 ? after : after.slice(0, end);
+    }
+    // Identifier+`(` requirement rejects JSON arrays and plain bracketed lists.
+    const bareMatch = /\[\s*[A-Za-z_]\w*\s*\(/.exec(text);
+    if (bareMatch)
+        return text.slice(bareMatch.index);
+    return null;
+}
+function pyPeek(s, offset = 0) {
+    return s.text[s.pos + offset] ?? "";
+}
+function pyConsume(s) {
+    const c = s.text[s.pos] ?? "";
+    s.pos++;
+    return c;
+}
+function pySkipWs(s) {
+    while (/\s/.test(pyPeek(s)))
+        s.pos++;
+}
+function pyParseString(s) {
+    const quote = pyConsume(s);
+    let out = "";
+    while (s.pos < s.text.length && pyPeek(s) !== quote) {
+        if (pyPeek(s) === "\\") {
+            s.pos++;
+            const esc = pyConsume(s);
+            switch (esc) {
+                case "n":
+                    out += "\n";
+                    break;
+                case "t":
+                    out += "\t";
+                    break;
+                case "r":
+                    out += "\r";
+                    break;
+                case "\\":
+                    out += "\\";
+                    break;
+                case "'":
+                    out += "'";
+                    break;
+                case '"':
+                    out += '"';
+                    break;
+                case "0":
+                    out += "\0";
+                    break;
+                default:
+                    out += esc;
+                    break;
+            }
+        }
+        else {
+            out += pyConsume(s);
+        }
+    }
+    if (s.pos >= s.text.length) {
+        throw new Error("Unterminated string literal");
+    }
+    pyConsume(s);
+    return out;
+}
+function pyParseNumber(s) {
+    const start = s.pos;
+    if (pyPeek(s) === "-" || pyPeek(s) === "+")
+        s.pos++;
+    while (/\d/.test(pyPeek(s)))
+        s.pos++;
+    if (pyPeek(s) === ".") {
+        s.pos++;
+        while (/\d/.test(pyPeek(s)))
+            s.pos++;
+    }
+    if (pyPeek(s) === "e" || pyPeek(s) === "E") {
+        s.pos++;
+        if (pyPeek(s) === "-" || pyPeek(s) === "+")
+            s.pos++;
+        while (/\d/.test(pyPeek(s)))
+            s.pos++;
+    }
+    const literal = s.text.slice(start, s.pos);
+    const n = Number(literal);
+    if (Number.isNaN(n) || literal.length === 0) {
+        throw new Error(`Invalid number literal: ${JSON.stringify(literal)}`);
+    }
+    return n;
+}
+function pyParseIdentifier(s) {
+    if (!/[A-Za-z_]/.test(pyPeek(s))) {
+        throw new Error(`Expected identifier, got ${JSON.stringify(pyPeek(s))}`);
+    }
+    const start = s.pos;
+    while (/[\w]/.test(pyPeek(s)))
+        s.pos++;
+    return s.text.slice(start, s.pos);
+}
+// Identifier-as-string fallback: any bare word that isn't `True`/`False`/`None`
+// is returned as a string, so `[get_weather(city=Paris)]` still produces
+// `{ city: "Paris" }`. Side-effect: lowercase `null` / `true` / `false` from
+// JS-trained models also coerce to strings — validate against your tool schema.
+function pyParseValue(s) {
+    pySkipWs(s);
+    const c = pyPeek(s);
+    if (c === '"' || c === "'")
+        return pyParseString(s);
+    if (c === "[")
+        return pyParseList(s);
+    if (c === "{")
+        return pyParseDict(s);
+    if (c === "-" || c === "+" || /\d/.test(c))
+        return pyParseNumber(s);
+    if (/[A-Za-z_]/.test(c)) {
+        const id = pyParseIdentifier(s);
+        if (id === "True")
+            return true;
+        if (id === "False")
+            return false;
+        if (id === "None")
+            return null;
+        return id;
+    }
+    throw new Error(`Unexpected character: ${JSON.stringify(c)}`);
+}
+// Drives `parseItem, sep, parseItem, sep, ..., close` loops with trailing-
+// comma tolerance. Assumes the open delimiter was already consumed.
+function pyParseDelimited(s, close, context, parseItem) {
+    pySkipWs(s);
+    if (pyPeek(s) === close) {
+        pyConsume(s);
+        return;
+    }
+    for (;;) {
+        pySkipWs(s);
+        parseItem();
+        pySkipWs(s);
+        const sep = pyPeek(s);
+        if (sep === ",") {
+            pyConsume(s);
+            pySkipWs(s);
+            if (pyPeek(s) === close) {
+                pyConsume(s);
+                return;
+            }
+        }
+        else if (sep === close) {
+            pyConsume(s);
+            return;
+        }
+        else {
+            throw new Error(`Expected , or ${close} in ${context}, got ${JSON.stringify(sep)}`);
+        }
+    }
+}
+function pyParseList(s) {
+    pyConsume(s);
+    const items = [];
+    pyParseDelimited(s, "]", "list", () => {
+        items.push(pyParseValue(s));
+    });
+    return items;
+}
+function pyParseDict(s) {
+    pyConsume(s);
+    const obj = {};
+    pyParseDelimited(s, "}", "dict", () => {
+        const c = pyPeek(s);
+        let key;
+        if (c === '"' || c === "'")
+            key = pyParseString(s);
+        else if (/[A-Za-z_]/.test(c))
+            key = pyParseIdentifier(s);
+        else
+            throw new Error(`Expected dict key, got ${JSON.stringify(c)}`);
+        pySkipWs(s);
+        if (pyConsume(s) !== ":") {
+            throw new Error(`Expected : after dict key "${key}"`);
+        }
+        obj[key] = pyParseValue(s);
+    });
+    return obj;
+}
+function pyParseArgList(s) {
+    const args = {};
+    pyParseDelimited(s, ")", "args", () => {
+        const key = pyParseIdentifier(s);
+        pySkipWs(s);
+        if (pyConsume(s) !== "=") {
+            throw new Error(`Expected = after arg name "${key}"`);
+        }
+        args[key] = pyParseValue(s);
+    });
+    return args;
+}
+function pyParseCallList(text) {
+    const s = { text, pos: 0 };
+    pySkipWs(s);
+    if (pyConsume(s) !== "[") {
+        throw new Error("Expected [ at start of call list");
+    }
+    const calls = [];
+    pyParseDelimited(s, "]", "call list", () => {
+        const name = pyParseIdentifier(s);
+        pySkipWs(s);
+        if (pyConsume(s) !== "(") {
+            throw new Error(`Expected ( after call name "${name}"`);
+        }
+        calls.push({ name, arguments: pyParseArgList(s) });
+    });
+    return calls;
+}
+export function parsePythonicFormat(text, tools) {
+    const toolCalls = [];
+    const errors = [];
+    const slice = locatePythonicCallList(text);
+    if (slice === null) {
+        return { matched: false, toolCalls, errors };
+    }
+    let calls;
+    try {
+        calls = pyParseCallList(slice);
+    }
+    catch (error) {
+        errors.push({
+            code: "PARSE_ERROR",
+            message: `Failed to parse Pythonic tool call list: ${error instanceof Error ? error.message : String(error)}`,
+            raw: slice,
+        });
+        return { matched: true, toolCalls, errors };
+    }
+    for (const call of calls) {
+        const raw = `${call.name}(${JSON.stringify(call.arguments)})`;
+        const validation = validateToolArguments(call.name, call.arguments, tools);
+        if (!validation.isValid && validation.error) {
+            errors.push({ ...validation.error, raw });
+            continue;
+        }
+        toolCalls.push({
+            id: generateStableToolCallId(call.name, call.arguments),
+            name: call.name,
+            arguments: call.arguments,
+            raw,
+        });
+    }
+    return { matched: true, toolCalls, errors };
+}

package/dist/server/utils/tools/shared.d.ts

@@ -0,0 +1,18 @@
+import type { Tool, ToolCall, ToolCallError } from "../../../schemas/index";
+export type ParserResult = {
+    matched: boolean;
+    toolCalls: ToolCall[];
+    errors: ToolCallError[];
+};
+export declare function stripThinkingBlocks(text: string): string;
+export declare function generateStableToolCallId(name: string, args: Record<string, unknown>): string;
+export declare function isValidToolCall(obj: unknown): obj is {
+    name: string;
+    arguments: Record<string, unknown>;
+    id?: string;
+};
+export declare function validateToolArguments(toolName: string, args: Record<string, unknown>, tools: Tool[]): {
+    isValid: boolean;
+    error?: ToolCallError;
+};
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1,54 @@
+export function stripThinkingBlocks(text) {
+    return text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+}
+let toolCallSequence = 0;
+export function generateStableToolCallId(name, args) {
+    const content = `${name}:${JSON.stringify(args)}`;
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const char = content.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash;
+    }
+    const sequence = toolCallSequence++;
+    return `call_${Math.abs(hash).toString(36)}_${sequence}`;
+}
+export function isValidToolCall(obj) {
+    if (!obj || typeof obj !== "object") {
+        return false;
+    }
+    if (!("name" in obj) || typeof obj.name !== "string") {
+        return false;
+    }
+    if (!("arguments" in obj) ||
+        typeof obj.arguments !== "object" ||
+        obj.arguments === null) {
+        return false;
+    }
+    return true;
+}
+export function validateToolArguments(toolName, args, tools) {
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+        return {
+            isValid: false,
+            error: {
+                code: "UNKNOWN_TOOL",
+                message: `Tool "${toolName}" not found in available tools`,
+            },
+        };
+    }
+    const required = tool.parameters.required || [];
+    for (const requiredParam of required) {
+        if (!(requiredParam in args)) {
+            return {
+                isValid: false,
+                error: {
+                    code: "VALIDATION_ERROR",
+                    message: `Missing required parameter "${requiredParam}" for tool "${toolName}"`,
+                },
+            };
+        }
+    }
+    return { isValid: true };
+}

package/dist/server/utils/worker-lock.d.ts

@@ -0,0 +1,3 @@
+export declare function acquireWorkerLock(): void;
+export declare function releaseWorkerLock(): void;
+//# sourceMappingURL=worker-lock.d.ts.map

package/dist/server/utils/worker-lock.js

@@ -0,0 +1,67 @@
+import fs from "bare-fs";
+import path from "bare-path";
+import process from "bare-process";
+import { getServerLogger } from "../../logging/index.js";
+import { getQvacPath } from "./qvac-paths.js";
+const logger = getServerLogger();
+const LOCK_FILENAME = ".worker.lock";
+function getLockFilePath() {
+    return getQvacPath(LOCK_FILENAME);
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLockFile(lockPath) {
+    try {
+        if (!fs.existsSync(lockPath))
+            return null;
+        const raw = fs.readFileSync(lockPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function acquireWorkerLock() {
+    const lockPath = getLockFilePath();
+    const existing = readLockFile(lockPath);
+    if (existing) {
+        if (isProcessAlive(existing.pid)) {
+            logger.warn(`Another worker (PID ${existing.pid}) is still running — lock file exists at ${lockPath}`);
+        }
+        else {
+            logger.warn(`Stale lock file detected (PID ${existing.pid} is dead, started ${existing.startedAt}). Removing.`);
+        }
+    }
+    const content = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+        fs.writeFileSync(lockPath, JSON.stringify(content));
+        logger.debug(`Worker lock acquired (PID ${process.pid})`);
+    }
+    catch (error) {
+        logger.error("Failed to write worker lock file:", error instanceof Error ? error.message : String(error));
+    }
+}
+export function releaseWorkerLock() {
+    const lockPath = getLockFilePath();
+    try {
+        const existing = readLockFile(lockPath);
+        if (existing && existing.pid === process.pid) {
+            fs.unlinkSync(lockPath);
+            logger.debug("Worker lock released");
+        }
+    }
+    catch {
+        // Best-effort — may already be gone
+    }
+}

package/dist/server/worker-core.d.ts

@@ -3,6 +3,21 @@ export declare function initializeWorkerCore(): {
 };
 export declare function ensureRPCSetup(): void;
 export declare function isCoreInitialized(): boolean;
-export type BareDirectShutdownReason = "signal" | "rpc-close";
+export type BareDirectShutdownReason = "signal" | "rpc-close" | "uncaught-exception" | "unhandled-rejection" | "ipc-disconnect";
+/**
+ * Pre-terminate cleanup, callable while the worker is still alive.
+ *
+ * On platforms where the worker lives in the same OS process as the JS host
+ * (i.e. mobile via react-native-bare-kit Worklet), `process.exit()` would
+ * kill the entire app. This path runs the same registry/model cleanup as
+ * `shutdownBareDirectWorker` but skips the lock release + exit, leaving the
+ * caller (typically the SDK client about to call `worklet.terminate()`)
+ * responsible for tearing the worker down.
+ *
+ * Critical for clean termination: addons hold static state with js_ref_t
+ * handles into the current V8 isolate; without this cleanup, those refs
+ * survive into the next worklet's isolate and crash on first access.
+ */
+export declare function cleanupForTerminate(): Promise<void>;
 export declare function shutdownBareDirectWorker(reason: BareDirectShutdownReason): Promise<void>;
 //# sourceMappingURL=worker-core.d.ts.map