@agentprojectcontext/apx 1.14.1 → 1.15.1

package/src/daemon/super-agent-tools/tools/ask-questions.js

@@ -0,0 +1,28 @@
+export default {
+  name: "ask_questions",
+  schema: {
+    function: {
+      name: "ask_questions",
+      description: "Ask the user one or more specific questions to clarify the task or gather requirements.",
+      parameters: {
+        type: "object",
+        properties: {
+          questions: {
+            type: "array",
+            items: { type: "string" },
+            description: "A list of questions for the user."
+          }
+        },
+        required: ["questions"]
+      }
+    }
+  },
+  makeHandler: () => async ({ questions }) => {
+    // This tool is used by the agent to explicitly signal that it is waiting for 
+    // answers to specific questions. The UI can then highlight these.
+    return { 
+      status: "Questions presented to user. Waiting for input.", 
+      count: questions.length 
+    };
+  }
+};

package/src/daemon/super-agent-tools/tools/transcribe-audio.js

@@ -11,7 +11,7 @@ export default {
     function: {
       name: "transcribe_audio",
       description:
-        "Transcribe an audio file to text. Default backend is local faster-whisper (model 'medium' on CPU with int8 quantization), with automatic fallback to OpenAI Whisper API if local fails. Pass file_path for a file on disk, or base64 for raw audio bytes (will be written to a temp file). Override provider/model/language as needed.",
+        "Transcribe an audio file to text. Default backend is local faster-whisper (model 'small' on CPU with int8 quantization, persistent server to avoid reload overhead), with automatic fallback to OpenAI Whisper API if local fails. Pass file_path for a file on disk, or base64 for raw audio bytes (will be written to a temp file). Override provider/model/language as needed.",
       parameters: {
         type: "object",
         properties: {
@@ -19,7 +19,7 @@ export default {
           base64: { type: "string", description: "alternative to file_path — raw base64 audio bytes (or 'data:audio/...;base64,...' data URI)" },
           format: { type: "string", description: "file extension hint when using base64 (default 'ogg')" },
           provider: { type: "string", description: "override the configured provider: 'auto' | 'local' | 'openai'" },
-          model: { type: "string", description: "local model size: tiny | base | small | medium | large | large-v2 | large-v3 (default medium)" },
+          model: { type: "string", description: "local model size: tiny | base | small | medium | large | large-v2 | large-v3 (default small)" },
           language: { type: "string", description: "ISO 639-1 code (e.g. 'es', 'en') or 'auto' for detection" },
           device: { type: "string", description: "local device: cpu | cuda (default cpu)" },
           compute_type: { type: "string", description: "local quantization: int8 | int8_float16 | float16 | float32 (default int8)" },

package/src/daemon/super-agent.js

@@ -68,6 +68,47 @@ HARD RULES (do not deviate):
 21. **SKILLS — ON DEMAND**: The "# Available skills" section below lists every skill available to you (slug + description, NO body). When the user asks about specific APX/APC commands, project structure, agent runtimes, or anything where exact syntax or detailed behavior matches a skill description (in ANY language — match semantically, not by keyword), call load_skill({slug}) to fetch the full markdown body. If a CWD is in the contextNote, pass it as project_path so project-scoped skills resolve. If the user explicitly asks "what skills do you have?", you can either read the catalog below directly OR call list_skills to get a fresh enumeration. Do NOT load skills for trivial / unrelated questions — that wastes tokens. Don't guess CLI syntax when a skill can tell you; load it.
 22. **NEVER PASTE BASE64 OR DATA URIs IN MESSAGE TEXT**: When you need to send an image, audio, or file via Telegram (or any channel), you MUST pass it via the dedicated parameter — NEVER embed it in the text field. Concretely: after browser_screenshot returns its base64 field, call send_telegram({text: "<short caption>", photo_base64: "<that base64>"}). Do NOT write text like 'Aquí está: ![screenshot](data:image/png;base64,...)' — Telegram (and most chat clients) do NOT render data URIs or markdown images; the user sees thousands of garbage characters. Same for files: use document_path / document_base64 / document_url, NOT the text field. The text field is exclusively for human-readable prose (and becomes the caption when media is attached). If unsure, save the image to /tmp/screenshot-<ts>.png first (browser_screenshot supports save_to_tmp=true and returns a path field) and pass that path to send_telegram via photo_path — never inline the bytes in text.`;
 
+function compactToolSchema(schema) {
+  const fn = schema?.function || {};
+  const params = fn.parameters || {};
+  const properties = params.properties || {};
+  return {
+    name: fn.name,
+    description: fn.description,
+    required: params.required || [],
+    properties: Object.fromEntries(
+      Object.entries(properties).map(([name, spec]) => [
+        name,
+        {
+          type: spec?.type || "string",
+          enum: spec?.enum,
+          description: spec?.description,
+        },
+      ])
+    ),
+  };
+}
+
+function pseudoToolSystem(system) {
+  const catalog = TOOL_SCHEMAS.map(compactToolSchema);
+  return [
+    system,
+    "# Structured tool fallback",
+    "The engine rejected native structured tools. You can still call tools by emitting plain JSON.",
+    "When you need a tool, respond ONLY with one JSON object per line:",
+    "{\"name\":\"tool_name\",\"arguments\":{\"arg\":\"value\"}}",
+    "After tool results arrive, continue the task or give the final answer normally.",
+    "Available tools:",
+    JSON.stringify(catalog),
+  ].join("\n\n");
+}
+
+function shouldRetryWithPseudoTools(modelId, error, alreadyPseudo) {
+  if (alreadyPseudo) return false;
+  const message = String(error?.message || "");
+  return /^ollama:/i.test(String(modelId || "")) && /ollama\s+500/i.test(message);
+}
+
 function isShortConfirmation(text) {
   return /^(yes|y|si|si dale|dale|ok|okay|confirm|confirmed|go|proceed|do it)\b/i
     .test(String(text || "").trim());
@@ -115,6 +156,7 @@ export async function runSuperAgent({
   previousMessages = [],
   overrideModel = null,
   onEvent = null,
+  signal,
 }) {
   if (!isSuperAgentEnabled(globalConfig)) {
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
@@ -187,6 +229,7 @@ export async function runSuperAgent({
   const trace = [];
   let totalUsage = { input_tokens: 0, output_tokens: 0 };
   let lastText = "";
+  let usePseudoTools = false;
 
   for (let iter = 0; iter < MAX_TOOL_ITERS; iter++) {
     await emitProgress(onEvent, { type: "model_start", iteration: iter + 1 });
@@ -195,15 +238,38 @@ export async function runSuperAgent({
     // acting on an action request. On later iterations (after tool results
     // have been fed back) tool_choice is "auto" so the model can produce its
     // final text summary.
-    const result = await callEngine({
-      modelId: activeModel,
-      system,
-      messages: conversation,
-      config: globalConfig,
-      tools: TOOL_SCHEMAS,
-      toolChoice: iter === 0 ? "required" : "auto",
-      maxTokens: 1024,
-    });
+    let result;
+    try {
+      result = await callEngine({
+        modelId: activeModel,
+        system: usePseudoTools ? pseudoToolSystem(system) : system,
+        messages: conversation,
+        config: globalConfig,
+        tools: usePseudoTools ? null : TOOL_SCHEMAS,
+        toolChoice: usePseudoTools ? null : (iter === 0 ? "required" : "auto"),
+        maxTokens: 1024,
+        signal,
+      });
+    } catch (e) {
+      if (usePseudoTools && /^ollama:/i.test(String(activeModel || "")) && /ollama\s+500/i.test(String(e?.message || "")) && trace.length > 0) {
+        await emitProgress(onEvent, { type: "model_retry", reason: "ollama_final_response_500", iteration: iter + 1 });
+        lastText = fallbackFinalText(trace, e);
+        break;
+      }
+      if (!shouldRetryWithPseudoTools(activeModel, e, usePseudoTools)) throw e;
+      usePseudoTools = true;
+      await emitProgress(onEvent, { type: "model_retry", reason: "ollama_structured_tools_500", iteration: iter + 1 });
+      result = await callEngine({
+        modelId: activeModel,
+        system: pseudoToolSystem(system),
+        messages: conversation,
+        config: globalConfig,
+        tools: null,
+        toolChoice: null,
+        maxTokens: 1024,
+        signal,
+      });
+    }
     totalUsage.input_tokens += result.usage?.input_tokens || 0;
     totalUsage.output_tokens += result.usage?.output_tokens || 0;
     lastText = result.text || "";
@@ -317,3 +383,25 @@ function summarizeForTrace(r) {
   if (s.length <= 400) return r;
   return s.slice(0, 380) + "…(truncated)";
 }
+
+function fallbackFinalText(trace, error) {
+  const lines = [
+    "Tool execution completed, but the model failed while composing the final answer.",
+    `Engine error: ${String(error?.message || error).slice(0, 220)}`,
+    "Trace:",
+  ];
+  for (const item of trace.slice(-8)) {
+    lines.push(`- ${item.tool}: ${previewTraceResult(item.result)}`);
+  }
+  return lines.join("\n");
+}
+
+function previewTraceResult(result) {
+  if (result === null || result === undefined) return "ok";
+  if (typeof result === "string") return result.slice(0, 180);
+  if (result.error) return `error: ${String(result.error).slice(0, 180)}`;
+  if (result.path) return String(result.path).slice(0, 180);
+  if (result.content) return String(result.content).slice(0, 180);
+  if (result.results) return JSON.stringify(result.results).slice(0, 180);
+  return JSON.stringify(result).slice(0, 180);
+}

package/src/daemon/transcription.js

@@ -1,10 +1,10 @@
 // daemon/transcription.js
 // Audio transcription dispatcher. Two backends:
 //
-//   - LOCAL (faster-whisper via Python subprocess) — ported from Panda's
-//     transcription_service.py. Same defaults: model "medium", device "cpu",
-//     compute_type "int8", beam_size 5, auto language detection. Requires
-//     `pip3 install faster-whisper` on the host.
+//   - LOCAL (faster-whisper via persistent Python server) — the server loads
+//     the model once on first use and keeps it in RAM. It auto-shuts down after
+//     idle_minutes (default 10) of inactivity, then restarts lazily on the
+//     next request. Requires `pip3 install faster-whisper` on the host.
 //
 //   - OPENAI (Whisper-1 cloud API) — needs OPENAI_API_KEY or
 //     engines.openai.api_key in config.
@@ -13,31 +13,36 @@
 //   "transcription": {
 //     "provider": "auto" | "local" | "openai",   // default "auto"
 //     "local": {
-//       "model": "medium",            // tiny | base | small | medium | large | large-v2 | large-v3
-//       "device": "cpu",              // cpu | cuda
-//       "compute_type": "int8",       // int8 | int8_float16 | float16 | float32
-//       "language": "auto",           // ISO 639-1 code or "auto"
-//       "beam_size": 5
+//       "model": "small",           // tiny | base | small | medium | large | large-v2 | large-v3
+//       "device": "cpu",            // cpu | cuda
+//       "compute_type": "int8",     // int8 | int8_float16 | float16 | float32
+//       "language": "auto",         // ISO 639-1 code (e.g. "es") or "auto"
+//       "beam_size": 5,
+//       "idle_minutes": 10          // auto-shutdown after N minutes idle
 //     }
 //   }
 //
 // "auto" tries local first; on failure falls back to openai.
+//
+// Spanish tip: set language: "es" for better accuracy with the small model.
 
 import fs from "node:fs";
 import path from "node:path";
-import { execFile } from "node:child_process";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-const __filename  = fileURLToPath(import.meta.url);
-const __dirname   = path.dirname(__filename);
-const PYTHON_HELPER = path.join(__dirname, "whisper-transcribe.py");
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const WHISPER_SERVER = path.join(__dirname, "whisper-server.py");
+const WHISPER_PORT = 18765;
 
 const DEFAULT_LOCAL = {
-  model: "medium",
+  model: "small",
   device: "cpu",
   compute_type: "int8",
   language: "auto",
   beam_size: 5,
+  idle_minutes: 10,
 };
 
 // ---------------------------------------------------------------------------
@@ -65,45 +70,145 @@ async function getConfig() {
 }
 
 // ---------------------------------------------------------------------------
-// Local backend (Python + faster-whisper)
+// Persistent server management
 // ---------------------------------------------------------------------------
 
-function transcribeLocal(filePath, opts) {
-  return new Promise((resolve, reject) => {
-    const args = [
-      PYTHON_HELPER,
-      filePath,
-      "--model",       String(opts.model || DEFAULT_LOCAL.model),
-      "--language",    String(opts.language || DEFAULT_LOCAL.language),
-      "--device",      String(opts.device || DEFAULT_LOCAL.device),
-      "--compute-type", String(opts.compute_type || DEFAULT_LOCAL.compute_type),
-      "--beam-size",   String(opts.beam_size || DEFAULT_LOCAL.beam_size),
-    ];
-    execFile("python3", args, { maxBuffer: 16 * 1024 * 1024, timeout: 5 * 60_000 }, (err, stdout, stderr) => {
-      if (err) {
-        const tail = (stderr || err.message || "").slice(-300);
-        return reject(new Error(`local transcription failed: ${tail}`));
-      }
-      let parsed;
-      try { parsed = JSON.parse(String(stdout).trim().split("\n").pop()); }
-      catch (e) {
-        return reject(new Error(`could not parse helper output: ${stdout.slice(0, 300)}`));
+let _serverProcess = null;
+let _serverModel = null;   // model the running server was started with
+
+function _sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function _isServerHealthy() {
+  try {
+    const res = await fetch(`http://127.0.0.1:${WHISPER_PORT}/health`, {
+      signal: AbortSignal.timeout(800),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function _waitForServer(maxMs = 15_000) {
+  const deadline = Date.now() + maxMs;
+  while (Date.now() < deadline) {
+    if (await _isServerHealthy()) return;
+    await _sleep(250);
+  }
+  throw new Error(`whisper-server did not start within ${maxMs}ms`);
+}
+
+async function ensureWhisperServer(opts) {
+  const model = opts.model || DEFAULT_LOCAL.model;
+
+  // Already running with the right model — health-check to confirm still alive.
+  if (_serverProcess && _serverModel === model) {
+    if (await _isServerHealthy()) return;
+    // Process died (idle shutdown). Fall through to restart.
+    _serverProcess = null;
+    _serverModel = null;
+  }
+
+  // Wrong model: kill old server and start fresh.
+  if (_serverProcess) {
+    try { _serverProcess.kill(); } catch {}
+    _serverProcess = null;
+    _serverModel = null;
+    await _sleep(300);
+  }
+
+  const args = [
+    WHISPER_SERVER,
+    "--port", String(WHISPER_PORT),
+    "--model", model,
+    "--device", String(opts.device || DEFAULT_LOCAL.device),
+    "--compute-type", String(opts.compute_type || DEFAULT_LOCAL.compute_type),
+    "--idle-minutes", String(opts.idle_minutes ?? DEFAULT_LOCAL.idle_minutes),
+  ];
+
+  const proc = spawn("python3", args, {
+    stdio: ["ignore", "pipe", "inherit"],
+    detached: false,
+  });
+
+  _serverProcess = proc;
+  _serverModel = model;
+
+  proc.on("exit", () => {
+    if (_serverProcess === proc) {
+      _serverProcess = null;
+      _serverModel = null;
+    }
+  });
+
+  // Wait for the "ready" line on stdout, then wait for HTTP to respond.
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(
+      () => reject(new Error("whisper-server startup timed out (15s)")),
+      15_000
+    );
+    let buf = "";
+    proc.stdout.on("data", (chunk) => {
+      buf += chunk.toString();
+      const nl = buf.indexOf("\n");
+      if (nl === -1) return;
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      clearTimeout(timeout);
+      try {
+        const msg = JSON.parse(line);
+        if (msg.status === "error") return reject(new Error(msg.error || "whisper-server error"));
+        resolve(); // "ready"
+      } catch {
+        resolve(); // unexpected line but server is up
       }
-      if (!parsed.ok) return reject(new Error(parsed.error || "unknown local transcription error"));
-      resolve({
-        ok: true,
-        backend: "local",
-        text: parsed.text || "",
-        language: parsed.language || null,
-        language_probability: parsed.language_probability ?? null,
-        duration: parsed.duration ?? null,
-        model: parsed.model,
-        compute_type: parsed.compute_type,
-      });
+    });
+    proc.on("exit", (code) => {
+      clearTimeout(timeout);
+      reject(new Error(`whisper-server exited (code ${code}) before becoming ready`));
     });
   });
 }
 
+// ---------------------------------------------------------------------------
+// Local backend (persistent whisper-server.py via HTTP)
+// ---------------------------------------------------------------------------
+
+async function transcribeLocal(filePath, opts) {
+  await ensureWhisperServer(opts);
+
+  const language = (opts.language || DEFAULT_LOCAL.language) === "auto"
+    ? null
+    : (opts.language || null);
+
+  const res = await fetch(`http://127.0.0.1:${WHISPER_PORT}/transcribe`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      audio_path: filePath,
+      language,
+      beam_size: opts.beam_size || DEFAULT_LOCAL.beam_size,
+    }),
+    signal: AbortSignal.timeout(5 * 60_000),
+  });
+
+  const json = await res.json();
+  if (!json.ok) throw new Error(json.error || "transcription failed");
+
+  return {
+    ok: true,
+    backend: "local",
+    text: json.text || "",
+    language: json.language || null,
+    language_probability: json.language_probability ?? null,
+    duration: json.duration ?? null,
+    model: json.model,
+    compute_type: json.compute_type,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // OpenAI backend (Whisper-1 cloud)
 // ---------------------------------------------------------------------------
@@ -154,7 +259,7 @@ async function transcribeOpenAI(filePath, apiKey) {
  * Returns { ok, backend, text, language?, language_probability?, duration?, model? }.
  *
  * @param {string} filePath   absolute path to audio file
- * @param {object} overrides  optional: { provider, model, language, ... }
+ * @param {object} overrides  optional: { provider, model, language, idle_minutes, ... }
  */
 export async function transcribe(filePath, overrides = {}) {
   if (!filePath || !fs.existsSync(filePath)) {
@@ -189,5 +294,6 @@ export async function transcribe(filePath, overrides = {}) {
 // ---------------------------------------------------------------------------
 
 export const TRANSCRIPTION_PATHS = {
-  python_helper: PYTHON_HELPER,
+  whisper_server: WHISPER_SERVER,
+  port: WHISPER_PORT,
 };

package/src/daemon/whisper-server.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+Persistent Whisper transcription server for APX.
+
+Loads the model once on the first /transcribe request and keeps it in RAM.
+Auto-shuts down after --idle-minutes of inactivity so it doesn't consume
+memory permanently when not in use.
+
+Started automatically by APX daemon via transcription.js. Do not run manually.
+
+Endpoints:
+  GET  /health      → { ok, model, loaded }
+  POST /transcribe  ← { audio_path, language?, beam_size? }
+                    → { ok, text, language, language_probability, duration, model, compute_type }
+  POST /shutdown    → graceful stop
+"""
+import argparse
+import json
+import os
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+_model = None
+_model_name = None
+_model_lock = threading.Lock()
+_last_used = time.monotonic()
+_idle_seconds = 10 * 60
+_server_ref = None
+
+
+def _touch():
+    global _last_used
+    _last_used = time.monotonic()
+
+
+def _load_model_if_needed(model_name, device, compute_type):
+    global _model, _model_name
+    if _model is not None and _model_name == model_name:
+        return _model
+    from faster_whisper import WhisperModel
+    threads = os.cpu_count() or 4
+    m = WhisperModel(model_name, device=device, compute_type=compute_type, cpu_threads=threads)
+    _model = m
+    _model_name = model_name
+    return m
+
+
+# ---------------------------------------------------------------------------
+# HTTP handler
+# ---------------------------------------------------------------------------
+
+class _Handler(BaseHTTPRequestHandler):
+    model_name = "small"
+    device = "cpu"
+    compute_type = "int8"
+
+    def log_message(self, fmt, *args):
+        pass  # suppress access log; APX daemon handles its own logging
+
+    def _send_json(self, code, body):
+        data = json.dumps(body).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def _read_body(self):
+        n = int(self.headers.get("Content-Length", 0))
+        if n <= 0:
+            return {}
+        try:
+            return json.loads(self.rfile.read(n))
+        except Exception:
+            return {}
+
+    def do_GET(self):
+        if self.path == "/health":
+            _touch()
+            self._send_json(200, {
+                "ok": True,
+                "model": _model_name or _Handler.model_name,
+                "loaded": _model is not None,
+            })
+        else:
+            self._send_json(404, {"ok": False, "error": "not found"})
+
+    def do_POST(self):
+        req = self._read_body()
+
+        if self.path == "/transcribe":
+            _touch()
+            audio_path = req.get("audio_path", "")
+            language = req.get("language") or None  # None → auto-detect
+            beam_size = int(req.get("beam_size", 5))
+
+            if not audio_path or not os.path.exists(audio_path):
+                self._send_json(400, {"ok": False, "error": f"file not found: {audio_path}"})
+                return
+
+            with _model_lock:
+                try:
+                    m = _load_model_if_needed(_Handler.model_name, _Handler.device, _Handler.compute_type)
+                except ImportError:
+                    self._send_json(500, {
+                        "ok": False,
+                        "error": "faster-whisper not installed — run: pip3 install faster-whisper",
+                    })
+                    return
+                except Exception as e:
+                    self._send_json(500, {"ok": False, "error": f"model load failed: {e}"})
+                    return
+
+                try:
+                    segments, info = m.transcribe(audio_path, beam_size=beam_size, language=language)
+                    text = " ".join(seg.text.strip() for seg in segments).strip()
+                    self._send_json(200, {
+                        "ok": True,
+                        "text": text,
+                        "language": info.language,
+                        "language_probability": round(info.language_probability, 4),
+                        "duration": round(info.duration, 2),
+                        "model": _model_name,
+                        "compute_type": _Handler.compute_type,
+                    })
+                except Exception as e:
+                    self._send_json(500, {"ok": False, "error": f"transcription failed: {e}"})
+
+        elif self.path == "/shutdown":
+            self._send_json(200, {"ok": True})
+            if _server_ref:
+                threading.Thread(target=_server_ref.shutdown, daemon=True).start()
+
+        else:
+            self._send_json(404, {"ok": False, "error": "not found"})
+
+
+# ---------------------------------------------------------------------------
+# Idle watchdog
+# ---------------------------------------------------------------------------
+
+def _watchdog(idle_seconds):
+    while True:
+        time.sleep(30)
+        idle = time.monotonic() - _last_used
+        if idle > idle_seconds:
+            print(
+                f"[whisper-server] idle {int(idle)}s > {idle_seconds}s — shutting down",
+                file=sys.stderr,
+                flush=True,
+            )
+            if _server_ref:
+                _server_ref.shutdown()
+            return
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    global _server_ref, _idle_seconds
+
+    parser = argparse.ArgumentParser(description="Persistent APX Whisper server")
+    parser.add_argument("--port", type=int, default=18765)
+    parser.add_argument("--model", default="small")
+    parser.add_argument("--device", default="cpu")
+    parser.add_argument("--compute-type", dest="compute_type", default="int8")
+    parser.add_argument("--idle-minutes", dest="idle_minutes", type=int, default=10)
+    args = parser.parse_args()
+
+    _Handler.model_name = args.model
+    _Handler.device = args.device
+    _Handler.compute_type = args.compute_type
+    _idle_seconds = args.idle_minutes * 60
+
+    try:
+        _server_ref = HTTPServer(("127.0.0.1", args.port), _Handler)
+    except OSError as e:
+        print(json.dumps({"status": "error", "error": str(e)}), flush=True)
+        sys.exit(1)
+
+    # Signal readiness to the Node.js parent before serve_forever blocks.
+    print(json.dumps({
+        "status": "ready",
+        "port": args.port,
+        "model": args.model,
+        "idle_minutes": args.idle_minutes,
+    }), flush=True)
+
+    threading.Thread(target=_watchdog, args=(_idle_seconds,), daemon=True).start()
+    _server_ref.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

package/src/daemon/whisper-transcribe.py

@@ -42,7 +42,9 @@ def main() -> int:
         return 1
 
     try:
-        model = WhisperModel(args.model, device=args.device, compute_type=args.compute_type)
+        import multiprocessing
+        threads = os.cpu_count() or 4
+        model = WhisperModel(args.model, device=args.device, compute_type=args.compute_type, cpu_threads=threads)
     except Exception as e:
         print(json.dumps({"ok": False, "error": f"failed to load model '{args.model}': {e}"}))
         return 1