@agentprojectcontext/apx 1.15.0 → 1.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -24,10 +24,11 @@
     "start": "node src/daemon/index.js",
     "smoke": "node src/daemon/smoke.js",
     "test": "node --test --test-reporter=spec tests/*.test.js",
-    "upgrade": "npm install && npm install -g .",
+    "upgrade": "pnpm install && pnpm add -g .",
     "prepack": "node scripts/sync-apc-skill.js",
     "postinstall": "node src/cli/postinstall.js"
   },
+  "packageManager": "pnpm@10.25.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.6.2",
@@ -55,6 +56,12 @@
     "claude",
     "ai"
   ],
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "puppeteer"
+    ]
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/agentprojectcontext/apx.git"

package/src/cli/commands/daemon.js

@@ -124,25 +124,57 @@ export async function cmdDaemonStop(args = {}) {
   }
 }
 
-export function cmdDaemonLogs(args) {
+export async function cmdDaemonLogs(args) {
   const debug = args.flags?.debug;
+  const follow = args.flags?.follow || args.flags?.f;
+
   if (!fs.existsSync(LOG_PATH)) {
     console.log(fmt.gray(`  (no log file at ${LOG_PATH})`));
     return;
   }
-  const tail  = args.flags?.tail ? parseInt(args.flags.tail, 10) : 50;
-  const lines = fs.readFileSync(LOG_PATH, "utf8").split("\n");
+
+  const tail = args.flags?.tail ? parseInt(args.flags.tail, 10) : 50;
+  const content = fs.readFileSync(LOG_PATH, "utf8");
+  const lines = content.split("\n");
   const slice = lines.slice(-tail - 1).filter(Boolean);
 
   if (debug) console.log(fmt.gray(`  log: ${LOG_PATH}  (last ${tail} lines)\n`));
 
-  for (const line of slice) {
-    // dim timestamps, highlight ERROR/WARN
+  const printLine = (line) => {
     const colored = line
       .replace(/^(\d{4}-\d\d-\d\dT[\d:.Z]+)/, (m) => fmt.gray(m))
       .replace(/\bERROR\b/g, fmt.red("ERROR"))
-      .replace(/\bWARN\b/g,  fmt.yellow("WARN"))
-      .replace(/\bINFO\b/g,  fmt.cyan("INFO"));
+      .replace(/\bWARN\b/g, fmt.yellow("WARN"))
+      .replace(/\bINFO\b/g, fmt.cyan("INFO"));
     console.log(colored);
+  };
+
+  for (const line of slice) {
+    printLine(line);
+  }
+
+  if (follow) {
+    let currentSize = fs.statSync(LOG_PATH).size;
+    fs.watch(LOG_PATH, (event) => {
+      if (event === "change") {
+        const newSize = fs.statSync(LOG_PATH).size;
+        if (newSize > currentSize) {
+          const stream = fs.createReadStream(LOG_PATH, {
+            start: currentSize,
+            end: newSize - 1,
+          });
+          stream.on("data", (chunk) => {
+            const lines = chunk.toString().split("\n").filter(Boolean);
+            for (const l of lines) printLine(l);
+          });
+          currentSize = newSize;
+        } else if (newSize < currentSize) {
+          // File truncated or rotated
+          currentSize = newSize;
+        }
+      }
+    });
+    // Keep process alive
+    return new Promise(() => {});
   }
 }

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/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