@voybio/ace-swarm 2.4.0 → 2.4.1

package/dist/tui/openai-compatible.js

@@ -5,7 +5,104 @@
  * - codex: defaults to OpenAI API endpoint/key env vars
  * - others: require provider-specific base URL + API key env vars
  */
+import { appendFileSync } from "node:fs";
 import { buildOpenAiCompatibleBaseUrl } from "./provider-discovery.js";
+function sanitizeTransportText(input) {
+    return input
+        .replace(/^\uFEFF/, "")
+        .replace(/\r\n?/g, "\n")
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
+}
+function sampleBytes(bytes, decoded) {
+    const buffer = Buffer.from(bytes);
+    return {
+        sample_hex: buffer.toString("hex").slice(0, 512),
+        sample_text: sanitizeTransportText(decoded).slice(0, 512),
+    };
+}
+function captureRawBytes(label, bytes) {
+    const target = process.env.ACE_RAW_RESPONSE_LOG?.trim();
+    if (!target)
+        return;
+    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+    const sample = sampleBytes(bytes, decoded);
+    try {
+        appendFileSync(target, `${JSON.stringify({
+            at: new Date().toISOString(),
+            label,
+            byte_length: bytes.byteLength,
+            ...sample,
+        })}\n`, "utf8");
+    }
+    catch {
+        // Raw capture is opt-in diagnostics; never fail the provider call because logging failed.
+    }
+}
+async function readResponseText(response, label) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    captureRawBytes(label, bytes);
+    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+    const text = sanitizeTransportText(decoded);
+    const sample = sampleBytes(bytes, decoded);
+    return {
+        text,
+        byteLength: bytes.byteLength,
+        ...sample,
+    };
+}
+function sanitizeChatMessages(messages) {
+    return (Array.isArray(messages) ? messages : [])
+        .map((msg) => {
+        const role = msg?.role === "system" || msg?.role === "assistant" || msg?.role === "user"
+            ? msg.role
+            : "user";
+        const content = typeof msg?.content === "string"
+            ? sanitizeTransportText(msg.content)
+            : sanitizeTransportText(String(msg?.content ?? ""));
+        return { role, content };
+    })
+        .filter((msg) => msg.role === "assistant" || msg.content.trim().length > 0);
+}
+function extractChoiceText(payload) {
+    if (!payload || typeof payload !== "object")
+        return "";
+    const choices = Array.isArray(payload.choices)
+        ? (payload.choices ?? [])
+        : [];
+    const firstChoice = choices[0];
+    if (!firstChoice || typeof firstChoice !== "object")
+        return "";
+    const choice = firstChoice;
+    if (typeof choice.message?.content === "string")
+        return sanitizeTransportText(choice.message.content);
+    if (typeof choice.text === "string")
+        return sanitizeTransportText(choice.text);
+    if (typeof choice.delta?.content === "string")
+        return sanitizeTransportText(choice.delta.content);
+    return "";
+}
+function extractProviderBodyText(bodyText) {
+    const trimmed = sanitizeTransportText(bodyText).trim();
+    if (!trimmed)
+        return { text: "", parsedJson: false };
+    try {
+        const payload = JSON.parse(trimmed);
+        const extracted = extractChoiceText(payload);
+        return {
+            text: extracted || trimmed,
+            parsedJson: true,
+        };
+    }
+    catch {
+        return {
+            text: trimmed,
+            parsedJson: false,
+        };
+    }
+}
+function formatErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 export class OpenAICompatibleError extends Error {
     statusCode;
     responseBody;
@@ -46,14 +143,216 @@ export class OpenAICompatibleClient {
             const resolvedModel = provider === "copilot"
                 ? normalizeCopilotModelName(request.model)
                 : request.model;
+            if (provider === "llama.cpp") {
+                const emitProviderEvent = (event) => {
+                    request.onProviderEvent?.({ provider, ...event });
+                };
+                let fallbackCount = 0;
+                const emitFallback = (stage, nextStage, reason, extra = {}) => {
+                    fallbackCount += 1;
+                    emitProviderEvent({
+                        event: "fallback",
+                        stage,
+                        next_stage: nextStage,
+                        reason,
+                        fallback_count: fallbackCount,
+                        statusCode: extra.statusCode,
+                        sample_hex: extra.sample_hex,
+                        sample_text: extra.sample_text,
+                    });
+                };
+                const messagesToSend = sanitizeChatMessages(request.messages);
+                const messagesToPrompt = messagesToSend.map((m) => `${m.role}: ${m.content}`).join("\n");
+                // Attempt 1: streaming chat (SSE)
+                try {
+                    emitProviderEvent({ event: "attempt", stage: "streaming_chat" });
+                    const streamBody = {
+                        model: resolvedModel,
+                        messages: messagesToSend,
+                        stream: true,
+                        temperature: request.temperature,
+                        top_p: request.topP,
+                    };
+                    const streamRes = await fetch(`${config.baseUrl}/chat/completions`, {
+                        method: "POST",
+                        signal: controller.signal,
+                        headers: {
+                            "Content-Type": "application/json",
+                            Accept: "text/event-stream",
+                            ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+                            ...(config.headers ?? {}),
+                        },
+                        body: JSON.stringify(streamBody),
+                    });
+                    if (streamRes.ok && streamRes.body) {
+                        let streamContentSeen = false;
+                        let streamParsedFrames = 0;
+                        let streamParseErrors = 0;
+                        for await (const data of this.streamSseData(streamRes.body)) {
+                            if (data === "[DONE]") {
+                                continue;
+                            }
+                            let parsed;
+                            try {
+                                parsed = JSON.parse(data);
+                            }
+                            catch {
+                                streamParseErrors += 1;
+                                emitProviderEvent({
+                                    event: "parse_error",
+                                    stage: "streaming_chat",
+                                    reason: "sse_data_json_parse_error",
+                                    sample_text: data.slice(0, 512),
+                                });
+                                continue;
+                            }
+                            streamParsedFrames += 1;
+                            const usage = (parsed.usage ?? {});
+                            if (typeof usage.prompt_tokens === "number")
+                                promptTokens = usage.prompt_tokens;
+                            if (typeof usage.completion_tokens === "number")
+                                completionTokens = usage.completion_tokens;
+                            const choices = Array.isArray(parsed.choices) ? parsed.choices : [];
+                            const firstChoice = (choices[0] ?? {});
+                            const delta = firstChoice.delta;
+                            const text = typeof delta?.content === "string" ? sanitizeTransportText(delta.content) : "";
+                            if (text.length > 0) {
+                                streamContentSeen = true;
+                                yield { text, done: false };
+                            }
+                        }
+                        if (streamContentSeen) {
+                            if (!doneSent) {
+                                doneSent = true;
+                                yield {
+                                    text: "",
+                                    done: true,
+                                    promptTokens,
+                                    completionTokens,
+                                };
+                            }
+                            emitProviderEvent({ event: "success", stage: "streaming_chat" });
+                            return;
+                        }
+                        emitFallback("streaming_chat", "non_streaming_chat", streamParseErrors > 0
+                            ? "stream_parse_error_no_content"
+                            : streamParsedFrames > 0
+                                ? "stream_no_text_content"
+                                : "stream_no_parseable_frames");
+                    }
+                    else {
+                        const sample = await readResponseText(streamRes, `${provider}:streaming_chat:error`);
+                        emitFallback("streaming_chat", "non_streaming_chat", "stream_http_error", {
+                            statusCode: streamRes.status,
+                            sample_hex: sample.sample_hex,
+                            sample_text: sample.sample_text,
+                        });
+                    }
+                }
+                catch (err) {
+                    if (err instanceof Error && /abort/i.test(err.name))
+                        throw err;
+                    emitFallback("streaming_chat", "non_streaming_chat", formatErrorMessage(err));
+                }
+                // Attempt 2: non-streaming chat (JSON or direct text)
+                try {
+                    emitProviderEvent({ event: "attempt", stage: "non_streaming_chat" });
+                    const chatBody = {
+                        model: resolvedModel,
+                        messages: messagesToSend,
+                        stream: false,
+                        temperature: request.temperature,
+                        top_p: request.topP,
+                    };
+                    const res = await fetch(`${config.baseUrl}/chat/completions`, {
+                        method: "POST",
+                        signal: controller.signal,
+                        headers: {
+                            "Content-Type": "application/json",
+                            Accept: "application/json, text/plain;q=0.9, */*;q=0.1",
+                            ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+                            ...(config.headers ?? {}),
+                        },
+                        body: JSON.stringify(chatBody),
+                    });
+                    const sample = await readResponseText(res, `${provider}:non_streaming_chat`);
+                    if (res.ok) {
+                        const extracted = extractProviderBodyText(sample.text);
+                        if (extracted.text.length > 0) {
+                            yield { text: extracted.text, done: false };
+                            yield {
+                                text: "",
+                                done: true,
+                                promptTokens,
+                                completionTokens,
+                            };
+                            doneSent = true;
+                            emitProviderEvent({ event: "success", stage: "non_streaming_chat" });
+                            return;
+                        }
+                        emitFallback("non_streaming_chat", "completions", "empty_non_streaming_response", {
+                            statusCode: res.status,
+                            sample_hex: sample.sample_hex,
+                            sample_text: sample.sample_text,
+                        });
+                    }
+                    else {
+                        emitFallback("non_streaming_chat", "completions", "non_streaming_http_error", {
+                            statusCode: res.status,
+                            sample_hex: sample.sample_hex,
+                            sample_text: sample.sample_text,
+                        });
+                    }
+                }
+                catch (err) {
+                    if (err instanceof Error && /abort/i.test(err.name))
+                        throw err;
+                    emitFallback("non_streaming_chat", "completions", formatErrorMessage(err));
+                }
+                // Attempt 3: completions endpoint with `prompt` (legacy shape, JSON or direct text)
+                emitProviderEvent({ event: "attempt", stage: "completions" });
+                const prompt = messagesToPrompt || "";
+                const compBody = {
+                    model: resolvedModel,
+                    prompt,
+                    temperature: request.temperature,
+                    top_p: request.topP,
+                };
+                const compRes = await fetch(`${config.baseUrl}/completions`, {
+                    method: "POST",
+                    signal: controller.signal,
+                    headers: {
+                        "Content-Type": "application/json",
+                        Accept: "application/json",
+                        ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+                        ...(config.headers ?? {}),
+                    },
+                    body: JSON.stringify(compBody),
+                });
+                const compSample = await readResponseText(compRes, `${provider}:completions`);
+                if (!compRes.ok) {
+                    throw new OpenAICompatibleError(`Provider '${provider}' API error: ${compRes.status} ${compRes.statusText}`, compRes.status, compSample.text);
+                }
+                const extracted = extractProviderBodyText(compSample.text);
+                const text = extracted.text;
+                if (text.length > 0)
+                    yield { text, done: false };
+                yield { text: "", done: true, promptTokens, completionTokens };
+                emitProviderEvent({ event: "success", stage: "completions" });
+                return;
+            }
+            // default streaming path for other providers
             const body = {
                 model: resolvedModel,
-                messages: request.messages,
+                messages: sanitizeChatMessages(request.messages),
                 stream: true,
                 temperature: request.temperature,
                 top_p: request.topP,
-                stream_options: { include_usage: true },
             };
+            // llama.cpp rejects custom stream_options; only include for non-llama providers
+            if (provider !== 'llama.cpp') {
+                body.stream_options = { include_usage: true };
+            }
             const res = await fetch(`${config.baseUrl}/chat/completions`, {
                 method: "POST",
                 signal: controller.signal,
@@ -202,7 +501,8 @@ export class OpenAICompatibleClient {
                 const { done, value } = await reader.read();
                 if (done)
                     break;
-                buffer += decoder.decode(value, { stream: true });
+                captureRawBytes("openai-compatible:sse_chunk", value);
+                buffer += sanitizeTransportText(decoder.decode(value, { stream: true }));
                 const lines = buffer.split("\n");
                 buffer = lines.pop() ?? "";
                 for (const line of lines) {
@@ -211,14 +511,14 @@ export class OpenAICompatibleClient {
                         continue;
                     if (!trimmed.startsWith("data:"))
                         continue;
-                    const data = trimmed.slice(5).trim();
+                    const data = sanitizeTransportText(trimmed.slice(5).trim());
                     if (!data)
                         continue;
                     yield data;
                 }
             }
             if (buffer.trim().startsWith("data:")) {
-                const data = buffer.trim().slice(5).trim();
+                const data = sanitizeTransportText(buffer.trim().slice(5).trim());
                 if (data)
                     yield data;
             }

package/dist/tui/provider-discovery.d.ts

@@ -57,6 +57,7 @@ export declare function buildOpenAiCompatibleBaseUrl(baseUrl: string): string;
 export declare function inferProviderFromModel(model: string | undefined): string | undefined;
 export declare function isLocalLlmProvider(providerInput: string | undefined): providerInput is LocalLlmProvider;
 export declare function defaultModelForProvider(providerInput: string | undefined): string;
+export declare function normalizeLlamaCppHfModelName(modelInput: string | undefined): string | undefined;
 export declare function providerEnvPrefix(providerInput: string | undefined): string;
 export declare function buildProviderDoctorCommands(providerInput: string | undefined, modelInput: string | undefined, baseUrlInput?: string): string[];
 export declare function parseJsoncLoose(raw: string): unknown;

package/dist/tui/provider-discovery.js

@@ -114,6 +114,22 @@ export function defaultModelForProvider(providerInput) {
         return DEFAULT_LLAMA_CPP_MODEL;
     return DEFAULT_HOSTED_MODELS[provider] ?? DEFAULT_HOSTED_MODELS.codex;
 }
+export function normalizeLlamaCppHfModelName(modelInput) {
+    const value = modelInput?.trim();
+    if (!value)
+        return undefined;
+    if (value.endsWith(".gguf"))
+        return value;
+    const normalized = value.replace(/^(?:https?:\/\/)?(?:hf\.co|huggingface\.co)\//i, "");
+    const match = normalized.match(/^([^/]+)\/([^:]+?)(?::([^:]+))?$/);
+    if (!match)
+        return value;
+    const repoName = match[2].replace(/\.gguf$/i, "").replace(/-GGUF$/i, "");
+    const quant = match[3]?.trim();
+    if (!quant)
+        return value;
+    return `${repoName}-${quant}.gguf`;
+}
 export function providerEnvPrefix(providerInput) {
     const provider = normalizeProvider(providerInput);
     if (!provider)
@@ -124,46 +140,51 @@ export function providerEnvPrefix(providerInput) {
 }
 export function buildProviderDoctorCommands(providerInput, modelInput, baseUrlInput) {
     const provider = normalizeProvider(providerInput) ?? "ollama";
-    const model = modelInput?.trim() || defaultModelForProvider(provider);
+    const model = modelInput?.trim();
     const baseUrl = normalizeLocalBaseUrl(baseUrlInput);
     if (provider === "ollama") {
+        const resolvedModel = model || defaultModelForProvider(provider);
         return [
             "ollama serve",
-            `ollama pull ${model}`,
+            `ollama pull ${resolvedModel}`,
             ...(baseUrl ? [`curl -s ${baseUrl}/api/tags`] : []),
             baseUrl
-                ? `ace doctor --llm ${provider} --model ${model} --base-url ${baseUrl}`
-                : `ace doctor --llm ${provider} --model ${model} --scan`,
+                ? `ace doctor --llm ${provider} --model ${resolvedModel} --base-url ${baseUrl}`
+                : `ace doctor --llm ${provider} --model ${resolvedModel} --scan`,
         ];
     }
     if (provider === "llama.cpp") {
+        const resolvedModel = model || "<hf-model-or-gguf>";
         return [
             "# Start llama-server separately, for example:",
-            "# llama-server -m /path/to/model.gguf --port 8080",
+            `# llama-server -hf ${resolvedModel} --port 8080`,
             ...(baseUrl ? [`curl -s ${buildOpenAiCompatibleBaseUrl(baseUrl)}/models`] : []),
             baseUrl
-                ? `ace doctor --llm ${provider} --model ${model} --base-url ${baseUrl}`
-                : `ace doctor --llm ${provider} --model ${model} --scan`,
+                ? `ace doctor --llm ${provider} --model ${resolvedModel} --base-url ${baseUrl}`
+                : `ace doctor --llm ${provider} --model ${resolvedModel} --scan`,
         ];
     }
     if (provider === "codex") {
+        const resolvedModel = model || defaultModelForProvider(provider);
         return [
             "export OPENAI_API_KEY=<token>",
             ...(baseUrl ? [`export OPENAI_BASE_URL=${baseUrl}`] : []),
-            `ace doctor --llm ${provider} --model ${model}${baseUrl ? ` --base-url ${baseUrl}` : ""}`,
+            `ace doctor --llm ${provider} --model ${resolvedModel}${baseUrl ? ` --base-url ${baseUrl}` : ""}`,
         ];
     }
     if (provider === "copilot") {
+        const resolvedModel = model || defaultModelForProvider(provider);
         return [
             "gh auth login  # or export GITHUB_TOKEN=<token>",
-            `ace doctor --llm ${provider} --model ${model}`,
+            `ace doctor --llm ${provider} --model ${resolvedModel}`,
         ];
     }
     const prefix = providerEnvPrefix(provider);
+    const resolvedModel = model || defaultModelForProvider(provider);
     return [
         `export ${prefix}_BASE_URL=${baseUrl ?? "<openai-compatible-base-url>"}`,
         `export ${prefix}_API_KEY=<token>`,
-        `ace doctor --llm ${provider} --model ${model}${baseUrl ? ` --base-url ${baseUrl}` : ""}`,
+        `ace doctor --llm ${provider} --model ${resolvedModel}${baseUrl ? ` --base-url ${baseUrl}` : ""}`,
     ];
 }
 function looksLikeModel(value) {
@@ -458,7 +479,10 @@ export function discoverProviderContext(options) {
         }
     }
     if (!model) {
-        model = defaultModelForProvider(provider);
+        model = provider === "llama.cpp" ? "" : defaultModelForProvider(provider);
+        if (provider === "llama.cpp") {
+            notes.push("runtime_default=llama.cpp (model not set; run ace connect or ace doctor --scan)");
+        }
     }
     addModel(modelsByProvider, provider, model);
     const allProviders = sortProviders([

package/dist/vericify-bridge.d.ts

@@ -5,7 +5,7 @@ export declare const VERICIFY_PROCESS_POST_LOG_SCHEMA_NAME = "vericify-process-p
 export declare const VERICIFY_BRIDGE_SNAPSHOT_REL_PATH = "agent-state/vericify/ace-bridge.json";
 export declare const VERICIFY_BRIDGE_SNAPSHOT_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json";
 export declare const VERICIFY_BRIDGE_SNAPSHOT_SCHEMA_NAME = "vericify-bridge-snapshot@1.0.0";
-type VericifyProcessPostKind = "intent" | "progress" | "blocker" | "handoff_note" | "stale_ack" | "completion";
+type VericifyProcessPostKind = "intent" | "progress" | "blocker" | "handoff_note" | "stale_ack" | "completion" | "plan_proposal" | "plan_quality_assessment";
 export interface VericifyProcessPost {
     process_post_id: string;
     run_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voybio/ace-swarm",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "ACE Framework MCP server and CLI — single-file ACEPACK state, local-model serving, agent orchestration, and host compliance enforcement.",
   "type": "module",
   "main": "dist/index.js",