@agentprojectcontext/apx 1.15.6 → 1.16.0

package/src/cli-ts/index.ts

@@ -0,0 +1,73 @@
+// APX CLI v2 — TypeScript entry point, yargs-based.
+// This replaces the manual arg-parsing in src/cli/index.js for commands
+// that have been migrated here. Unmigrated commands delegate to the legacy handler.
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { sessionCmd } from "./commands/session.js";
+import { agentCmd } from "./commands/agent.js";
+import { mcpCmd } from "./commands/mcp.js";
+import { daemonCmd } from "./commands/daemon.js";
+import { statusCmd } from "./commands/status.js";
+import { execCmd } from "./commands/exec.js";
+import { chatCmd } from "./commands/chat.js";
+
+process.on("unhandledRejection", (err) => {
+  process.stderr.write(
+    "\x1b[91m✖ Unhandled error:\x1b[0m " + String(err) + "\n",
+  );
+  process.exit(1);
+});
+
+yargs(hideBin(process.argv))
+  .scriptName("apx")
+  .usage("$0 <command> [options]")
+  .version(false) // we handle --version ourselves below
+  .option("project", {
+    alias: "p",
+    type: "string",
+    describe: "Project name, ID, or path",
+    global: true,
+  })
+  .option("json", {
+    type: "boolean",
+    describe: "Output as JSON",
+    global: false,
+  })
+  .command(sessionCmd)
+  .command(agentCmd)
+  .command(mcpCmd)
+  .command(daemonCmd)
+  .command(statusCmd)
+  .command(execCmd)
+  .command(chatCmd)
+  .command({
+    command: "version",
+    aliases: ["--version", "-v"],
+    describe: "Print APX version",
+    handler: async () => {
+      const { createRequire } = await import("node:module");
+      const req = createRequire(import.meta.url);
+      try {
+        const pkg = req("../../package.json") as { version: string };
+        process.stdout.write(pkg.version + "\n");
+      } catch {
+        process.stdout.write("unknown\n");
+      }
+    },
+  })
+  .demandCommand(1, "Specify a command. Use --help for available commands.")
+  .strict()
+  .wrap(Math.min(100, yargs().terminalWidth()))
+  .help()
+  .alias("help", "h")
+  .fail((msg, err) => {
+    if (err) throw err;
+    process.stderr.write("\x1b[91m✖ " + msg + "\x1b[0m\n\n");
+    process.exit(1);
+  })
+  .parseAsync()
+  .catch((err: Error) => {
+    process.stderr.write("\x1b[91m✖ " + err.message + "\x1b[0m\n");
+    process.exit(1);
+  });

package/src/cli-ts/ui.ts

@@ -0,0 +1,107 @@
+// Terminal UI utilities — ANSI colors, output helpers.
+// Adapted from opencode_ref/packages/opencode/src/cli/ui.ts
+
+import { createInterface } from "node:readline";
+
+export const Style = {
+  TEXT_HIGHLIGHT: "\x1b[96m",
+  TEXT_DIM: "\x1b[90m",
+  TEXT_NORMAL: "\x1b[0m",
+  TEXT_WARNING: "\x1b[93m",
+  TEXT_DANGER: "\x1b[91m",
+  TEXT_SUCCESS: "\x1b[92m",
+  TEXT_INFO: "\x1b[94m",
+  TEXT_BOLD: "\x1b[1m",
+  TEXT_BOLD_END: "\x1b[22m",
+} as const;
+
+let _lastEmpty = false;
+
+export function println(...parts: string[]): void {
+  _lastEmpty = false;
+  process.stderr.write(parts.join(" ") + "\n");
+}
+
+export function print(...parts: string[]): void {
+  _lastEmpty = false;
+  process.stderr.write(parts.join(" "));
+}
+
+export function empty(): void {
+  if (_lastEmpty) return;
+  _lastEmpty = true;
+  process.stderr.write("\n");
+}
+
+export function error(message: string): void {
+  println(Style.TEXT_DANGER + "✖ " + Style.TEXT_NORMAL + message);
+}
+
+export function success(message: string): void {
+  println(Style.TEXT_SUCCESS + "✔ " + Style.TEXT_NORMAL + message);
+}
+
+export function info(message: string): void {
+  println(Style.TEXT_INFO + "ℹ " + Style.TEXT_NORMAL + message);
+}
+
+export function warn(message: string): void {
+  println(Style.TEXT_WARNING + "⚠ " + Style.TEXT_NORMAL + message);
+}
+
+export function dim(message: string): string {
+  return Style.TEXT_DIM + message + Style.TEXT_NORMAL;
+}
+
+export function highlight(message: string): string {
+  return Style.TEXT_HIGHLIGHT + message + Style.TEXT_NORMAL;
+}
+
+export function bold(message: string): string {
+  return Style.TEXT_BOLD + message + Style.TEXT_BOLD_END;
+}
+
+export async function input(prompt: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise<string>((resolve) => {
+    rl.question(Style.TEXT_HIGHLIGHT + prompt + Style.TEXT_NORMAL + " ", (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export function logo(): void {
+  if (!process.stdout.isTTY) {
+    println(bold("APX"));
+    return;
+  }
+  println(
+    Style.TEXT_DIM +
+    "  ██████╗ ██████╗ ██╗  ██╗\n" +
+    Style.TEXT_INFO +
+    "  ██╔══██╗██╔══██╗╚██╗██╔╝\n" +
+    Style.TEXT_HIGHLIGHT +
+    "  ███████║██████╔╝ ╚███╔╝ \n" +
+    "  ██╔══██║██╔═══╝  ██╔██╗ \n" +
+    Style.TEXT_NORMAL +
+    "  ██║  ██║██║     ██╔╝ ██╗\n" +
+    "  ╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝" +
+    Style.TEXT_NORMAL,
+  );
+}
+
+export function table(
+  rows: Array<Record<string, string>>,
+  cols: string[],
+): void {
+  const widths = cols.map((col) =>
+    Math.max(col.length, ...rows.map((r) => (r[col] ?? "").length)),
+  );
+  const header = cols.map((col, i) => bold(col.padEnd(widths[i]!))).join("  ");
+  println(header);
+  println(dim("─".repeat(widths.reduce((a, b) => a + b + 2, -2))));
+  for (const row of rows) {
+    println(cols.map((col, i) => (row[col] ?? "").padEnd(widths[i]!)).join("  "));
+  }
+}

package/src/core/logging.js

@@ -4,6 +4,10 @@ import { APX_HOME } from "./config.js";
 
 export const LOG_DIR = path.join(APX_HOME, "logs");
 export const ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
+// Unified daemon log. Every module (daemon, telegram, whisper, super-agent,
+// tools, overlay) writes here with one consistent format so the user can
+// follow the whole system from a single tail.
+export const APX_LOG_PATH = path.join(LOG_DIR, "apx.log");
 
 const SECRET_KEY_RE = /(token|secret|password|api[_-]?key|authorization|bot[_-]?token)/i;
 
@@ -35,3 +39,80 @@ export function previewText(text, max = 500) {
   const clean = String(text || "").replace(/\s+/g, " ").trim();
   return clean.length > max ? clean.slice(0, max - 1) + "…" : clean;
 }
+
+// ---------------------------------------------------------------------------
+// Unified logger — writes to ~/.apx/logs/apx.log in the format:
+//   [2026-05-13 22:35:01.234] [LEVEL ] [module] message {meta}
+//
+// `level` is INFO | WARN | ERROR (case-insensitive). Unknown levels fall back
+// to INFO. `module` is a short tag (telegram, whisper, super-agent, daemon…).
+// `meta` is optional; if present and non-empty, it's stringified at the end.
+// Secrets in meta are redacted via the same SECRET_KEY_RE used by error traces.
+//
+// Returns the line that was written, so callers can also surface it elsewhere
+// (e.g. process.stdout for the daemon's existing stdout log).
+// ---------------------------------------------------------------------------
+
+const LEVELS = new Set(["INFO", "WARN", "ERROR"]);
+
+function fmtTs(d = new Date()) {
+  const pad = (n, w = 2) => String(n).padStart(w, "0");
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+    `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`
+  );
+}
+
+export function formatLogLine(level, module, message, meta) {
+  const lvl = LEVELS.has(String(level || "").toUpperCase())
+    ? String(level).toUpperCase()
+    : "INFO";
+  const mod = String(module || "apx").slice(0, 24);
+  const msg = String(message ?? "").replace(/\n/g, " ");
+  let suffix = "";
+  if (meta && typeof meta === "object" && Object.keys(meta).length > 0) {
+    try { suffix = " " + JSON.stringify(redact(meta)); }
+    catch { suffix = " {meta:unserializable}"; }
+  }
+  return `[${fmtTs()}] [${lvl.padEnd(5)}] [${mod}] ${msg}${suffix}`;
+}
+
+export function log(level, module, message, meta) {
+  const line = formatLogLine(level, module, message, meta);
+  try {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+    fs.appendFileSync(APX_LOG_PATH, line + "\n", "utf8");
+  } catch {
+    // never throw from the logger — losing a log line must not crash the daemon
+  }
+  return line;
+}
+
+// Convenience helpers so callers don't repeat the level string everywhere.
+export const logInfo  = (module, message, meta) => log("INFO",  module, message, meta);
+export const logWarn  = (module, message, meta) => log("WARN",  module, message, meta);
+export const logError = (module, message, meta) => log("ERROR", module, message, meta);
+
+// Build a module-bound logger so plugins can do `const log = loggerFor("telegram")`
+// and then `log.info("...")` without repeating the module tag.
+export function loggerFor(module) {
+  return {
+    info:  (message, meta) => logInfo(module, message, meta),
+    warn:  (message, meta) => logWarn(module, message, meta),
+    error: (message, meta) => logError(module, message, meta),
+    // Shorthand call form preserved for the daemon's old `log(msg)` callers:
+    //   const log = loggerFor("daemon"); log("hello") // INFO
+    // We wrap it so `log` is callable directly *and* exposes .info/.warn/.error.
+  };
+}
+
+// Make a callable+method logger: `log("msg")` works AND `log.warn("msg")` works.
+// This lets us replace the daemon's existing `log = (msg) => stdout.write(...)`
+// with one that fans out to apx.log too, without rewriting every call site.
+export function callableLogger(module) {
+  const fn = (message, meta) => logInfo(module, message, meta);
+  fn.info  = (message, meta) => logInfo(module, message, meta);
+  fn.warn  = (message, meta) => logWarn(module, message, meta);
+  fn.error = (message, meta) => logError(module, message, meta);
+  return fn;
+}

package/src/daemon/api.js

@@ -1,5 +1,6 @@
 // Express REST API for APX. See APC docs reference/apx-daemon.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
@@ -1441,6 +1442,63 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     }
   });
 
+  // ---- Transcription chunk (shared: overlay, Telegram, any channel) -
+  // POST /transcribe/chunk  ← raw audio bytes (webm, ogg, wav, mp3 …)
+  // Headers: X-Audio-Format, X-Language (ISO or "auto"), X-Provider (auto|local|openai)
+  // Returns: { ok, text, backend, language, … }
+  app.post("/transcribe/chunk", async (req, res) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", async () => {
+      const buf = Buffer.concat(chunks);
+      if (!buf.length) return res.status(400).json({ ok: false, error: "empty body" });
+      const format   = req.headers["x-audio-format"] || "webm";
+      const language = req.headers["x-language"] || "auto";
+      const provider = req.headers["x-provider"];
+      try {
+        const { transcribeBuffer } = await import("./transcription.js");
+        const result = await transcribeBuffer(buf, format, {
+          language: language === "auto" ? undefined : language,
+          beam_size: 3,
+          ...(provider ? { provider } : {}),
+        });
+        res.json(result);
+      } catch (e) {
+        res.status(500).json({ ok: false, error: e.message });
+      }
+    });
+    req.on("error", (e) => res.status(500).json({ ok: false, error: e.message }));
+  });
+
+  // ---- Overlay channel (voice/floating window) ----------------------
+  app.get("/overlay/status", (_req, res) => {
+    // Lazy import to avoid hard dep
+    import("./overlay-ws.js").then(({ overlayClients }) => {
+      res.json({ ok: true, connected_clients: overlayClients.size });
+    }).catch(() => res.json({ ok: true, connected_clients: 0 }));
+  });
+
+  // POST /overlay/message  ← text sent by the overlay after transcription
+  // Runs the super-agent and streams tokens back via WebSocket.
+  app.post("/overlay/message", async (req, res) => {
+    const { text, previousMessages = [] } = req.body || {};
+    if (!text) return res.status(400).json({ error: "text required" });
+    res.json({ ok: true }); // respond immediately; result comes via WebSocket
+
+    // Inline execution — the overlay plugin handles the heavy lift;
+    // here we just trigger it if the plugin is registered.
+    try {
+      const overlayPlugin = plugins.instances.get("overlay");
+      if (overlayPlugin?.handleMessage) {
+        await overlayPlugin.handleMessage({ text, previousMessages });
+      }
+    } catch (e) {
+      import("./overlay-ws.js").then(({ broadcastOverlay }) => {
+        broadcastOverlay({ type: "error", message: e.message });
+      }).catch(() => {});
+    }
+  });
+
   // ---- Admin --------------------------------------------------------
   app.post("/admin/shutdown", (_req, res) => {
     res.json({ ok: true });

package/src/daemon/engines/anthropic.js

@@ -11,7 +11,7 @@ function getKey(config) {
 export default {
   id: "anthropic",
 
-  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice, signal }) {
+  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice, signal, onToken }) {
     const key = getKey(config);
     if (!key) throw new Error("anthropic: no api_key (set ANTHROPIC_API_KEY or engines.anthropic.api_key)");
     if (!model) throw new Error("anthropic: model required");
@@ -39,6 +39,65 @@ export default {
       }
     }
 
+    // Streaming path — only when onToken provided AND no tool_choice=required
+    // (we can't stream tool-forced turns because tool_calls are embedded in SSE)
+    if (typeof onToken === "function" && toolChoice !== "required" && toolChoice !== "any") {
+      body.stream = true;
+      const res = await fetch(API_BASE, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": key,
+          "anthropic-version": API_VERSION,
+        },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) {
+        const err = await res.text().catch(() => "");
+        throw new Error(`anthropic ${res.status}: ${err.slice(0, 200)}`);
+      }
+
+      const decoder = new TextDecoder();
+      let text = "";
+      let inputTokens = 0;
+      let outputTokens = 0;
+      let stopReason = null;
+      let buf = "";
+
+      for await (const chunk of res.body) {
+        buf += decoder.decode(chunk, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop(); // keep incomplete last line
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const raw = line.slice(6).trim();
+          if (raw === "[DONE]") continue;
+          let evt;
+          try { evt = JSON.parse(raw); } catch { continue; }
+          if (evt.type === "content_block_delta" && evt.delta?.type === "text_delta") {
+            const t = evt.delta.text || "";
+            if (t) { text += t; onToken(t); }
+          } else if (evt.type === "message_delta") {
+            stopReason = evt.delta?.stop_reason || stopReason;
+            outputTokens = evt.usage?.output_tokens || outputTokens;
+          } else if (evt.type === "message_start") {
+            inputTokens = evt.message?.usage?.input_tokens || 0;
+            outputTokens = evt.message?.usage?.output_tokens || 0;
+          }
+        }
+      }
+
+      return {
+        text,
+        tool_uses: undefined,
+        stop_reason: stopReason,
+        usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+        raw: null,
+      };
+    }
+
+    // Non-streaming path (original)
     const res = await fetch(API_BASE, {
       method: "POST",
       headers: {

package/src/daemon/engines/index.js

@@ -46,7 +46,7 @@ export function getAdapter(provider) {
   return a;
 }
 
-export async function callEngine({ modelId, system, messages, config, temperature, maxTokens, tools, toolChoice, signal }) {
+export async function callEngine({ modelId, system, messages, config, temperature, maxTokens, tools, toolChoice, signal, onToken }) {
   const { provider, model } = resolveProvider(modelId);
   const adapter = getAdapter(provider);
   const providerCfg = (config && config.engines && config.engines[provider]) || {};
@@ -60,6 +60,7 @@ export async function callEngine({ modelId, system, messages, config, temperatur
     toolChoice,
     config: providerCfg,
     signal,
+    onToken,
   });
 }
 

package/src/daemon/engines/ollama.js

@@ -8,15 +8,32 @@ function baseUrl(config) {
 export default {
   id: "ollama",
 
-  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, config = {}, signal }) {
+  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, toolChoice, config = {}, signal, onToken }) {
     if (!model) throw new Error("ollama: model required");
 
+    // Ollama's /api/chat does not honor a tool_choice field. When the caller
+    // wants to force a tool call ("required" / "any") we inject a strong
+    // system-message hint instead so the model is much less likely to emit a
+    // text-only acknowledgement like "ok dame un minuto" without calling a tool.
+    const forceTool =
+      Array.isArray(tools) && tools.length > 0 &&
+      (toolChoice === "required" || toolChoice === "any");
+
+    let effectiveSystem = system;
+    if (forceTool) {
+      const hint =
+        "You MUST call one of the available tools to satisfy this turn. " +
+        "Do NOT reply with text-only acknowledgements (no 'ok', 'sure', 'on it', 'dame un minuto'). " +
+        "If you cannot decide which tool, pick the closest match and call it.";
+      effectiveSystem = system ? `${system}\n\n${hint}` : hint;
+    }
+
     // The caller can pass `messages` as either:
     //   [{role, content}]                       — usual shape
     //   [{role, content, tool_calls?}, {role: "tool", tool_call_id?, content}, ...]
     // We forward those fields straight through so the agent loop works.
     const fullMessages = [];
-    if (system) fullMessages.push({ role: "system", content: system });
+    if (effectiveSystem) fullMessages.push({ role: "system", content: effectiveSystem });
     for (const m of messages) {
       const out = { role: m.role };
       if (m.content !== undefined) {
@@ -30,6 +47,57 @@ export default {
       fullMessages.push(out);
     }
 
+    const url = `${baseUrl(config).replace(/\/$/, "")}/api/chat`;
+
+    // Streaming path — only when onToken provided AND no tools (Ollama streaming + tools is unreliable)
+    if (typeof onToken === "function" && (!tools || tools.length === 0)) {
+      const body = {
+        model,
+        messages: fullMessages,
+        stream: true,
+        options: { temperature, num_predict: maxTokens },
+      };
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) {
+        const t = await res.text();
+        throw new Error(`ollama ${res.status}: ${t}`);
+      }
+      const decoder = new TextDecoder();
+      let text = "";
+      let inputTokens = 0;
+      let outputTokens = 0;
+      let buf = "";
+      for await (const chunk of res.body) {
+        buf += decoder.decode(chunk, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop();
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          let evt;
+          try { evt = JSON.parse(line); } catch { continue; }
+          const t = evt.message?.content || "";
+          if (t) { text += t; onToken(t); }
+          if (evt.done) {
+            inputTokens = evt.prompt_eval_count || 0;
+            outputTokens = evt.eval_count || 0;
+          }
+        }
+      }
+      return {
+        text,
+        tool_calls: null,
+        message: { role: "assistant", content: text },
+        usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+        raw: null,
+      };
+    }
+
+    // Non-streaming path (original)
     const body = {
       model,
       messages: fullMessages,
@@ -40,7 +108,6 @@ export default {
       body.tools = tools;
     }
 
-    const url = `${baseUrl(config).replace(/\/$/, "")}/api/chat`;
     const res = await fetch(url, {
       method: "POST",
       headers: { "content-type": "application/json" },

package/src/daemon/index.js

@@ -21,6 +21,8 @@ import { PluginManager } from "./plugins/index.js";
 import { RoutineScheduler } from "./routines.js";
 import { buildApi } from "./api.js";
 import { triggerWakeup } from "./wakeup.js";
+import { registerOverlayClient } from "./overlay-ws.js";
+import { log as logToUnified } from "../core/logging.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,8 +34,41 @@ const PKG = JSON.parse(
 // to ~/.apx/daemon.log via `stdio: ["ignore", out, out]`. So a single
 // process.stdout.write reaches the file once. In foreground (npm start), it
 // still prints to the console. No double-append.
+//
+// Beyond the legacy stdout sink we also fan out every line to the unified
+// ~/.apx/logs/apx.log via core/logging.js so `apx log` and `apx log -f`
+// see everything that any plugin/module writes through the daemon's log fn.
+//
+// Heuristic for level/module inference: messages prefixed "fatal:" /
+// "uncaughtException:" / "error:" are ERROR; "warn:" / "could not" / "skipping"
+// are WARN; everything else INFO. Plugins normally pass `plugin <id> ...` or
+// `<id>[<name>] ...` — we use the first bracketed token (or first word before
+// ":") as the module tag.
+function inferLevel(msg) {
+  if (/^fatal:|^uncaughtException:|^error:|failed|crash/i.test(msg)) return "ERROR";
+  if (/^warn:|could not|skipping|orphan|broken pipe/i.test(msg)) return "WARN";
+  return "INFO";
+}
+function inferModule(msg) {
+  // "plugin telegram initialized" → telegram
+  const plug = msg.match(/^plugin\s+([a-z_-]+)/i);
+  if (plug) return plug[1];
+  // "telegram[default] ..." → telegram
+  const bracket = msg.match(/^([a-z_-]+)\[/i);
+  if (bracket) return bracket[1];
+  // "whisper: preloading ..." → whisper
+  const colon = msg.match(/^([a-z_-]+):\s/i);
+  if (colon) return colon[1];
+  // "overlay: ..." caught above; "loaded project ..." → daemon
+  return "daemon";
+}
 const log = (msg) => {
   process.stdout.write(`[${new Date().toISOString()}] ${msg}\n`);
+  try {
+    logToUnified(inferLevel(msg), inferModule(msg), msg);
+  } catch {
+    // logger is best-effort, never throw
+  }
 };
 
 function ensureHome() {
@@ -170,6 +205,25 @@ async function main() {
     scheduler.start();
     // Fire wake-up message after a short delay so plugins (Telegram) are ready
     setTimeout(() => triggerWakeup(cfg, log), 3000);
+    // Preload whisper-server in the background so first overlay transcription is fast.
+    // Adopts an existing one if already on the port; otherwise spawns fresh.
+    import("./transcription.js").then(({ preloadWhisperServer }) => {
+      preloadWhisperServer((m) => log(m));
+    }).catch(() => {});
+  });
+
+  // Attach WebSocket upgrade for overlay channel on /overlay/ws
+  server.on("upgrade", async (req, socket, head) => {
+    if (req.url !== "/overlay/ws") { socket.destroy(); return; }
+    // Lazy-import ws to avoid hard dep on startup
+    let WebSocketServer;
+    try { ({ WebSocketServer } = await import("ws")); } catch {
+      socket.destroy(); return;
+    }
+    const wss = new WebSocketServer({ noServer: true });
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      registerOverlayClient(ws);
+    });
   });
 
   server.on("error", (e) => {
@@ -185,6 +239,10 @@ async function main() {
     scheduler.stop();
     plugins.stopAll();
     registries.shutdown();
+    // Best-effort shutdown of whisper-server subprocess.
+    import("./transcription.js").then(({ shutdownWhisperServer }) => {
+      shutdownWhisperServer().catch(() => {});
+    }).catch(() => {});
     server.close(() => {
       clearPid();
       process.exit(0);

package/src/daemon/overlay-ws.js

@@ -0,0 +1,40 @@
+// Singleton WebSocket hub for the overlay channel.
+// Imported by api.js (to register connections) and by plugins/overlay.js (to broadcast).
+
+const _clients = new Set(); // Set<WebSocket>
+let _messageHandler = null; // (ws, data) => void — set by overlay plugin
+
+export const overlayClients = _clients;
+
+export function setOverlayMessageHandler(fn) {
+  _messageHandler = fn;
+}
+
+export function registerOverlayClient(ws) {
+  _clients.add(ws);
+  ws.on("close", () => _clients.delete(ws));
+  ws.on("error", () => _clients.delete(ws));
+  ws.on("message", (raw) => {
+    if (typeof _messageHandler === "function") {
+      let data;
+      try { data = JSON.parse(raw.toString()); } catch { data = { type: "raw", raw: raw.toString() }; }
+      _messageHandler(ws, data);
+    }
+  });
+}
+
+export function broadcastOverlay(msg) {
+  const payload = typeof msg === "string" ? msg : JSON.stringify(msg);
+  for (const ws of _clients) {
+    try {
+      if (ws.readyState === 1) ws.send(payload); // 1 = OPEN
+    } catch {}
+  }
+}
+
+export function sendToClient(ws, msg) {
+  const payload = typeof msg === "string" ? msg : JSON.stringify(msg);
+  try {
+    if (ws.readyState === 1) ws.send(payload);
+  } catch {}
+}

package/src/daemon/plugins/index.js

@@ -13,8 +13,9 @@
 // Plugins are discovered by static import here. Adding a new plugin = importing
 // it and pushing into PLUGINS.
 import telegramPlugin from "./telegram.js";
+import overlayPlugin from "./overlay.js";
 
-export const PLUGINS = [telegramPlugin];
+export const PLUGINS = [telegramPlugin, overlayPlugin];
 
 export class PluginManager {
   constructor({ projects, config, log, registries }) {