@agentprojectcontext/apx 1.74.0 → 1.74.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.74.0",
+  "version": "1.74.1",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -67,7 +67,8 @@
     "react": "^19.2.0",
     "remeda": "^2.21.0",
     "safer-buffer": "^2.1.2",
-    "solid-js": "^1.9.13"
+    "solid-js": "^1.9.13",
+    "ws": "^8.21.3"
   },
   "optionalDependencies": {
     "better-sqlite3": "^11.3.0",

package/src/core/desktop/autostart.js

@@ -18,6 +18,7 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { augmentedPath } from "#core/util/path-env.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
@@ -55,6 +56,12 @@ function escapeXml(s) {
 export function buildPlist(runner, logFile) {
   const args = [...runner, "desktop", "start"];
   const argsXml = args.map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+  // Absolute ProgramArguments (see getApxRunner) only save the *first* hop.
+  // Everything the daemon spawns below itself — ffmpeg for whisper, npx/node
+  // for stdio MCPs — still resolves through PATH, and launchd's is
+  // /usr/bin:/bin:/usr/sbin:/sbin. Baking the installing shell's augmented
+  // PATH in makes the whole tree behave the same at login as in a terminal.
+  const pathEnv = augmentedPath();
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -64,6 +71,10 @@ export function buildPlist(runner, logFile) {
   <array>
 ${argsXml}
   </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${escapeXml(pathEnv)}</string>
+  </dict>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><false/>
   <key>ProcessType</key><string>Interactive</string>
@@ -76,12 +87,18 @@ ${argsXml}
 
 // ── public API ───────────────────────────────────────────────────────────
 
+// The three functions below take `platform` instead of reading process.platform
+// inline so the unsupported-platform branch is reachable from a test on any
+// machine — it's the only branch with no filesystem/registry side effect, and
+// hard-coding process.platform meant it could only ever be exercised on a
+// freebsd/sunos box. Callers always omit it.
+
 /** Boolean: is the autostart entry currently registered on this platform? */
-export function autostartIsOn() {
+export function autostartIsOn(platform = process.platform) {
   try {
-    if (process.platform === "darwin") return fs.existsSync(MAC_PLIST_PATH);
-    if (process.platform === "linux")  return fs.existsSync(LINUX_DESKTOP_PATH);
-    if (process.platform === "win32") {
+    if (platform === "darwin") return fs.existsSync(MAC_PLIST_PATH);
+    if (platform === "linux")  return fs.existsSync(LINUX_DESKTOP_PATH);
+    if (platform === "win32") {
       const out = execFileSync("reg", ["query", WIN_RUN_KEY, "/v", WIN_RUN_NAME], {
         stdio: ["ignore", "pipe", "ignore"],
       }).toString();
@@ -95,12 +112,12 @@ export function autostartIsOn() {
  * Enable autostart. Idempotent — running twice is safe.
  * @returns {{ ok: boolean, message?: string, error?: string, runs?: string, path?: string }}
  */
-export function autostartInstall() {
+export function autostartInstall(platform = process.platform) {
   const runner = getApxRunner();
   const sh = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
   const cmdline = [...runner, "desktop", "start"].map(sh).join(" ");
 
-  if (process.platform === "darwin") {
+  if (platform === "darwin") {
     try {
       fs.mkdirSync(path.dirname(MAC_PLIST_PATH), { recursive: true });
       fs.mkdirSync(path.dirname(AUTOSTART_LOG_PATH), { recursive: true });
@@ -110,7 +127,7 @@ export function autostartInstall() {
       return { ok: true, runs: cmdline, path: MAC_PLIST_PATH };
     } catch (e) { return { ok: false, error: e.message }; }
   }
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     try {
       execFileSync("reg", [
         "add", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/t", "REG_SZ", "/d", cmdline, "/f",
@@ -118,7 +135,7 @@ export function autostartInstall() {
       return { ok: true, runs: cmdline, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}` };
     } catch (e) { return { ok: false, error: e.message }; }
   }
-  if (process.platform === "linux") {
+  if (platform === "linux") {
     try {
       fs.mkdirSync(path.dirname(LINUX_DESKTOP_PATH), { recursive: true });
       fs.writeFileSync(LINUX_DESKTOP_PATH,
@@ -127,15 +144,15 @@ export function autostartInstall() {
       return { ok: true, runs: cmdline, path: LINUX_DESKTOP_PATH };
     } catch (e) { return { ok: false, error: e.message }; }
   }
-  return { ok: false, error: `autostart not supported on platform: ${process.platform}` };
+  return { ok: false, error: `autostart not supported on platform: ${platform}` };
 }
 
 /**
  * Disable autostart. Idempotent — no-op if not installed.
  * @returns {{ ok: boolean, removed?: boolean, path?: string, error?: string }}
  */
-export function autostartUninstall() {
-  if (process.platform === "darwin") {
+export function autostartUninstall(platform = process.platform) {
+  if (platform === "darwin") {
     if (!fs.existsSync(MAC_PLIST_PATH)) return { ok: true, removed: false };
     try {
       try { execFileSync("launchctl", ["unload", "-w", MAC_PLIST_PATH], { stdio: "ignore" }); } catch {}
@@ -143,7 +160,7 @@ export function autostartUninstall() {
       return { ok: true, removed: true, path: MAC_PLIST_PATH };
     } catch (e) { return { ok: false, error: e.message }; }
   }
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     try {
       execFileSync("reg", ["delete", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/f"], { stdio: "ignore" });
       return { ok: true, removed: true, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}` };
@@ -151,12 +168,12 @@ export function autostartUninstall() {
       return { ok: true, removed: false };
     }
   }
-  if (process.platform === "linux") {
+  if (platform === "linux") {
     if (!fs.existsSync(LINUX_DESKTOP_PATH)) return { ok: true, removed: false };
     try {
       fs.unlinkSync(LINUX_DESKTOP_PATH);
       return { ok: true, removed: true, path: LINUX_DESKTOP_PATH };
     } catch (e) { return { ok: false, error: e.message }; }
   }
-  return { ok: false, error: `autostart not supported on platform: ${process.platform}` };
+  return { ok: false, error: `autostart not supported on platform: ${platform}` };
 }

package/src/core/mcp/runner.js

@@ -9,6 +9,7 @@ import { spawn } from "node:child_process";
 import { loadAll } from "./sources.js";
 import { interpolate, MissingVarError } from "#core/vars/interpolate.js";
 import { loadAllVars } from "#core/vars/sources.js";
+import { envWithPath } from "#core/util/path-env.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const LOG_CAP = 64;            // entries per MCP we keep in memory
@@ -59,8 +60,12 @@ class McpProcess {
   start() {
     if (this.proc) return;
     this._log("info", `spawn ${this.command} ${(this.args || []).join(" ")}`);
+    // envWithPath, not a bare process.env spread: most stdio MCPs are launched
+    // via `npx`/`node`, which live in the nvm/pnpm bin dir. Booted from launchd
+    // the daemon only has /usr/bin:/bin:/usr/sbin:/sbin and every one of them
+    // fails with "spawn npx ENOENT".
     this.proc = spawn(this.command, this.args, {
-      env: { ...process.env, ...this.env },
+      env: envWithPath(this.env),
       stdio: ["pipe", "pipe", "pipe"],
     });
     this.startedAt = nowIso();

package/src/core/util/index.js

@@ -1,2 +1,3 @@
 export * from "./time.js";
 export * from "./ids.js";
+export * from "./path-env.js";

package/src/core/util/path-env.js

@@ -0,0 +1,73 @@
+// PATH repair for processes APX spawns.
+//
+// When the daemon is booted from a GUI context — the launchd agent
+// (dev.apx.desktop), a .app bundle, an IDE — it inherits launchd's minimal
+// PATH: /usr/bin:/bin:/usr/sbin:/sbin. No Homebrew, no nvm, no pnpm. Every
+// child we spawn then dies with ENOENT on binaries that work fine in a
+// terminal:
+//
+//   - whisper-server.py → "No such file or directory: 'ffmpeg'" (mlx/faster
+//     whisper shell out to ffmpeg to decode .oga/.webm)
+//   - stdio MCP servers  → "spawn npx ENOENT" / "spawn node ENOENT"
+//
+// getApxRunner() in core/desktop/autostart.js already dodges this for the
+// node binary itself by using an absolute process.execPath. This module is
+// the same idea for everything spawned *below* that process.
+//
+// Extra dirs are APPENDED, never prepended: an inherited PATH that already
+// resolves a binary keeps winning, we only fill the gaps.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Directories worth appending on this machine, in priority order. Only ones
+ * that actually exist are returned, so PATH stays free of dead entries.
+ */
+export function extraBinDirs() {
+  const home = os.homedir();
+  // dirname(process.execPath) is the bin/ of the node currently running us —
+  // under nvm/fnm/volta that's also where npm and npx live, which is exactly
+  // what stdio MCP servers need.
+  const candidates = process.platform === "win32"
+    ? [path.dirname(process.execPath)]
+    : [
+        path.dirname(process.execPath),
+        "/opt/homebrew/bin",      // Homebrew on Apple Silicon
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",         // Homebrew on Intel, most manual installs
+        "/usr/local/sbin",
+        path.join(home, ".local", "bin"),
+        path.join(home, "Library", "pnpm"),
+        path.join(home, ".bun", "bin"),
+        path.join(home, ".cargo", "bin"),
+      ];
+  return candidates.filter((dir) => {
+    try { return fs.existsSync(dir); } catch { return false; }
+  });
+}
+
+/**
+ * `basePath` with every missing entry from extraBinDirs() appended.
+ * @param {string} [basePath]  defaults to the current process PATH
+ */
+export function augmentedPath(basePath = process.env.PATH || "") {
+  const sep = path.delimiter;
+  const seen = new Set(basePath.split(sep).filter(Boolean));
+  const additions = extraBinDirs().filter((dir) => !seen.has(dir));
+  if (!additions.length) return basePath;
+  return [...basePath.split(sep).filter(Boolean), ...additions].join(sep);
+}
+
+/**
+ * An env object for child_process.spawn: process.env + `extra`, with PATH
+ * repaired. A PATH supplied in `extra` is respected as the base and augmented
+ * too, so callers can still pin their own dirs first.
+ */
+export function envWithPath(extra = {}) {
+  const merged = { ...process.env, ...extra };
+  // Windows env keys are case-insensitive and may arrive as "Path".
+  const key = Object.keys(merged).find((k) => k.toUpperCase() === "PATH") || "PATH";
+  merged[key] = augmentedPath(merged[key] || "");
+  return merged;
+}

package/src/core/voice/transcription.js

@@ -174,12 +174,37 @@ export function listSttProviders(rawConfig = {}) {
   return { configured_provider: provider, engines };
 }
 
+// Host-injected "make sure the whisper subprocess is alive" hook. Core must
+// not import from host/daemon, so host/daemon/whisper-server.js registers
+// ensureWhisperServer() here at module load instead. Stays null in contexts
+// that have no subprocess to manage (tests, CLI talking to a remote daemon),
+// where transcribeViaLocalServer just fetches as before.
+let _ensureLocalServer = null;
+
+/** @param {((opts:object)=>Promise<void>)|null} fn */
+export function setLocalServerEnsure(fn) {
+  _ensureLocalServer = typeof fn === "function" ? fn : null;
+}
+
 /**
- * Call the local whisper-server.py over HTTP. Does NOT spawn or check the
- * subprocess — that's host/daemon/whisper-server.js's job. If the server is
- * down, this throws a clear "ECONNREFUSED" the caller can surface.
+ * Call the local whisper-server.py over HTTP.
+ *
+ * The server shuts itself down after `idle_minutes` (10 by default), so on any
+ * request that isn't back-to-back with the last one the port is simply dead.
+ * We therefore ask the host to (re)spawn it first — ensureWhisperServer() is a
+ * cheap health check when the process is already up. Without this, the first
+ * voice message after an idle gap always failed with a bare "fetch failed".
  */
 export async function transcribeViaLocalServer(filePath, opts) {
+  if (_ensureLocalServer) {
+    try {
+      await _ensureLocalServer(opts);
+    } catch (e) {
+      // Not fatal: the server may still be reachable (e.g. an orphan listener
+      // this process doesn't own). Let the fetch below decide.
+      logWarn("whisper", `ensure local server failed, trying anyway: ${e.message}`);
+    }
+  }
   const language = (opts.language || DEFAULT_LOCAL.language) === "auto"
     ? null
     : (opts.language || null);

package/src/host/daemon/whisper-server.js

@@ -15,7 +15,9 @@ import {
   WHISPER_LOCAL_PORT,
   DEFAULT_LOCAL,
   getConfig,
+  setLocalServerEnsure,
 } from "#core/voice/transcription.js";
+import { envWithPath } from "#core/util/path-env.js";
 import { pythonForWhisper } from "./stt-venv.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -82,7 +84,21 @@ async function _killOrphanWhisper() {
   }
 }
 
+// Serializes concurrent ensures. Two voice messages arriving together (or a
+// desktop utterance racing a Telegram note) would otherwise each see a dead
+// port and spawn their own python, and the loser then trips
+// "address already in use".
+let _ensureInFlight = null;
+
 export async function ensureWhisperServer(opts) {
+  if (_ensureInFlight) return _ensureInFlight;
+  _ensureInFlight = _ensureWhisperServer(opts).finally(() => {
+    _ensureInFlight = null;
+  });
+  return _ensureInFlight;
+}
+
+async function _ensureWhisperServer(opts) {
   const model = opts.model || DEFAULT_LOCAL.model;
   const backend = opts.backend || "faster";
 
@@ -129,9 +145,15 @@ async function _spawnWhisper(opts, model, backend, retried) {
 
   // Prefer APX's dedicated venv interpreter (isolated mlx/faster-whisper);
   // fall back to system python3 for the legacy user-site install.
+  //
+  // envWithPath: both whisper backends shell out to `ffmpeg` to decode
+  // .oga/.webm. Booted from launchd the daemon's PATH is /usr/bin:/bin:
+  // /usr/sbin:/sbin, so a Homebrew ffmpeg is invisible and every transcription
+  // dies with "[Errno 2] No such file or directory: 'ffmpeg'".
   const proc = spawn(pythonForWhisper(), args, {
     stdio: ["ignore", "pipe", "inherit"],
     detached: false,
+    env: envWithPath(),
   });
 
   _serverProcess = proc;
@@ -236,3 +258,8 @@ export const WHISPER_PATHS = {
   whisper_server: WHISPER_SERVER,
   port: WHISPER_LOCAL_PORT,
 };
+
+// Hand core the ability to revive the subprocess on demand. Importing this
+// module (the daemon does, to preload at boot) is what wires it up — core
+// itself never reaches into host/.
+setLocalServerEnsure(ensureWhisperServer);