@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/runtime-skills/apx-voice/SKILL.md

@@ -35,9 +35,9 @@ When `base_url` is set, APX additionally forwards the non-OpenAI fields the serv
 Some backends (QVox/Qwen3-TTS, Gemini) accept inline `[tag]` markers and switch speaking emotion per segment while keeping the base voice. This is a **generic per-engine toggle**, not hardcoded to any adapter:
 
 ```bash
-apx config set voice.tts.custom.qvox.emotions.enabled true
+apx config set --global voice.tts.custom.qvox.emotions.enabled true
 # optional: restrict the tag set (defaults to the canonical QVox set)
-apx config set voice.tts.custom.qvox.emotions.tags '["happy","sad","excited","calm","whisper","laugh","neutral"]'
+apx config set --global voice.tts.custom.qvox.emotions.tags '["happy","sad","excited","calm","whisper","laugh","neutral"]'
 ```
 
 Default tags: `happy, sad, excited, angry, calm, whisper, shout, laugh, cry, narrator, neutral`. The voice-mode prompt learns the tag syntax **only when the engine that will actually speak has emotions enabled**. On any engine without tag support, stray `[tags]` are stripped from the displayed text and never read aloud (kept only for the speaking engine's audio).
@@ -57,6 +57,23 @@ apx voice listen --provider <id>                 # override STT provider
 
 Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`). If none found, you get the file path and no playback.
 
+## Spoken replies while driving
+
+When the daemon knows a trip is in progress (Android reports it — see
+`rules/android.md`), every automatic Telegram reply goes out twice: a voice note
+first, then the same words as text under a transcript header. The turn itself
+runs in voice mode, so the reply is one or two spoken sentences rather than a
+paragraph read aloud.
+
+The audio is OGG/Opus — the only container Telegram renders as a voice note —
+converted from whatever the engine returned via `ffmpeg`. A failing engine or a
+missing `ffmpeg` costs the audio, never the message: it falls back to plain
+text. The `mock` engine is silence, not speech, and is refused.
+
+```bash
+apx config set --global voice.mobility_replies false   # keep replies text-only in the car
+```
+
 ## Configuration
 
 `~/.apx/config.json → voice.tts.<engine>`:
@@ -85,7 +102,7 @@ Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`). I
 }
 ```
 
-`apx config set voice.tts.provider <name>` to switch.
+`apx config set --global voice.tts.provider <name>` to switch. Voice config is read from the global config, so `--global` is required — without it the value lands in a project's `.apc/config.json` and the voice stack never sees it.
 
 ## Quick setup: Piper local (recommended, no internet)
 
@@ -101,17 +118,17 @@ curl -LO https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_AR/danie
 curl -LO https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_AR/daniela/high/es_AR-daniela-high.onnx.json
 
 # 3. Configure + test
-apx config set voice.tts.provider piper
-apx config set voice.tts.piper.model "$HOME/.apx/voices/es_AR-daniela-high.onnx"
+apx config set --global voice.tts.provider piper
+apx config set --global voice.tts.piper.model "$HOME/.apx/voices/es_AR-daniela-high.onnx"
 apx voice say "hola, soy APX" --provider piper
 ```
 
 ## Quick setup: Gemini cloud
 
 ```bash
-apx config set voice.tts.provider gemini
-apx config set voice.tts.gemini.api_key '<GEMINI_KEY>'
-apx config set engines.gemini.api_key   '<GEMINI_KEY>'    # reuse for LLM router
+apx config set --global voice.tts.provider gemini
+apx config set --global voice.tts.gemini.api_key '<GEMINI_KEY>'
+apx config set --global engines.gemini.api_key   '<GEMINI_KEY>'    # reuse for LLM router
 apx voice say "Hello from APX" --provider gemini
 ```
 
@@ -126,6 +143,8 @@ curl -X POST http://127.0.0.1:7430/api/voice/turn \
   -d '{"text":"Hello APX","channel":"voice"}'
 ```
 
+`channel` names the surface the turn arrives on: `voice` (the deck's spoken mode), `deck`, `desktop`, `telegram`. Anything else — including omitting it — is treated as `api`, the bounded default: the route will not adopt another surface's behaviour just because a caller names it.
+
 Telegram voice messages and overlay mascot still have their own STT pipelines — they don't go through `/api/voice/turn` yet.
 
 ## Anti-examples

package/src/core/runtime-skills/claude-code/SKILL.md

@@ -71,6 +71,14 @@ claude --continue                       # most recent session
 claude -p --resume <session-id> "..."   # specific session, always with -p (print mode)
 ```
 
+## Not here: agent-to-agent (a2a) hand-off
+
+Reaching an APX agent and being answered back (the a2a relay: `apx send … --deliver`,
+`engine=… session=…` identity, `apx session resume … --msg`) is a **harness-side**
+concern. It lives in the `apx` skill that every coding CLI loads, and on the agent
+side in **apx-runtime**. This driver covers only how APX operates the Claude
+engine — keep a2a out of it.
+
 ## APX runtime
 
 Run a project agent through Claude Code:

package/src/core/runtime-skills/openrouter/SKILL.md

@@ -40,8 +40,14 @@ apx config --help
 apx status
 ```
 
-Then update only non-secret project-safe settings. Keep API keys in user config or environment, not
-in `.apc/` or git.
+Then update only non-secret project-safe settings. Keep API keys in the global config or the
+environment, never in `.apc/` or git — `apx config set` writes the project's committed
+`.apc/config.json` unless you pass `--global`:
+
+```bash
+apx config set --global engines.openrouter.api_key '<KEY>'   # ~/.apx/config.json
+apx config set engines.openrouter.model <model-id>           # .apc/config.json (committed)
+```
 
 ## OpenCode guidance
 

package/src/core/runtimes/_spawn.js

@@ -6,9 +6,17 @@ const DEFAULT_TIMEOUT = 5 * 60 * 1000; // 5 minutes
 
 export function runProcess({ command, args = [], stdin = "", cwd, env, timeoutMs = DEFAULT_TIMEOUT }) {
   return new Promise((resolve) => {
+    // `cwd` moves the child's working directory but NOT its inherited `PWD`,
+    // which still names wherever the daemon was started. Tools that trust `PWD`
+    // over getcwd() — opencode does — then resolve the wrong project: an a2a
+    // coding session asked to write a file wrote it into the daemon's checkout
+    // instead of the caller's. Keep the two in agreement.
+    const childEnv = { ...process.env, ...(env || {}) };
+    if (cwd) childEnv.PWD = cwd;
+
     const child = spawn(command, args, {
       cwd,
-      env: { ...process.env, ...(env || {}) },
+      env: childEnv,
       stdio: ["pipe", "pipe", "pipe"],
     });
 

package/src/core/runtimes/claude-code.js

@@ -1,5 +1,6 @@
 // Claude Code runtime adapter. Uses the headless `-p` mode:
 //   claude -p "<prompt>"  --append-system-prompt "<system>"  --output-format json
+//   claude -p "<prompt>"  --resume <session-id>              continue that session
 // Returns one JSON line with the result and session_id.
 // Reference: https://docs.claude.com/en/docs/claude-code/headless
 
@@ -33,8 +34,15 @@ export default {
   binary: "claude",
   versionFlag: "--version",
 
-  async run({ system, prompt, cwd, env, timeoutMs }) {
+  sessions: "capture",
+
+  async run({ system, prompt, cwd, env, timeoutMs, resumeSessionId = null, mode = "code" }) {
     const args = ["-p", prompt, "--output-format", "json"];
+    // `plan` is Claude Code's own read-only mode: it answers normally but will
+    // not edit. That is what a plain a2a message should get — a peer you talked
+    // to should not be able to rewrite your checkout because it was asked to.
+    if (mode === "chat") args.push("--permission-mode", "plan");
+    if (resumeSessionId) args.push("--resume", resumeSessionId);
     if (system) {
       args.push("--append-system-prompt", system);
     }
@@ -70,8 +78,9 @@ export default {
       exitCode: r.exitCode,
       output,
       stderr: r.stderr,
+      killed: r.killed,
       externalSessionPath,
-      sessionId,
+      sessionId: sessionId || resumeSessionId || null,
       raw: parsed,
     };
   },

package/src/core/runtimes/codex.js

@@ -1,29 +1,63 @@
 // OpenAI Codex CLI runtime adapter.
-//   codex exec --sandbox workspace-write --skip-git-repo-check "<prompt>"
+//   codex exec --sandbox workspace-write --skip-git-repo-check --json "<prompt>"
+//   codex exec resume <thread-id> --json "<prompt>"          continue that thread
 // System prompt is prepended to the prompt body since Codex doesn't have a
 // dedicated --system flag in `exec` mode.
 // Reference: https://github.com/openai/codex
 
 import { runProcess } from "./_spawn.js";
 
+// `--json` turns stdout into JSONL events. We ask for it because it is the only
+// place codex names the thread it opened, and that id is what lets the NEXT
+// turn resume this same conversation instead of starting a stranger. The prose
+// we would otherwise have printed is in the agent_message items.
+function parseCodexEvents(stdout) {
+  let threadId = null;
+  const messages = [];
+  for (const raw of String(stdout || "").split("\n")) {
+    const line = raw.trim();
+    if (!line.startsWith("{")) continue;
+    let event;
+    try { event = JSON.parse(line); } catch { continue; }
+    if (event.type === "thread.started" && event.thread_id) threadId = event.thread_id;
+    if (
+      event.type === "item.completed" &&
+      event.item?.type === "agent_message" &&
+      event.item.text
+    ) {
+      messages.push(String(event.item.text));
+    }
+  }
+  return { threadId, text: messages.join("\n\n").trim() };
+}
+
 export default {
   id: "codex",
   binary: "codex",
   versionFlag: "--version",
+  sessions: "capture",
 
-  async run({ system, prompt, cwd, env, timeoutMs }) {
+  async run({ system, prompt, cwd, env, timeoutMs, resumeSessionId = null, mode = "code" }) {
     const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
-    const r = await runProcess({
-      command: "codex",
-      args: ["exec", "--sandbox", "workspace-write", "--skip-git-repo-check", fullPrompt],
-      cwd,
-      env,
-      timeoutMs,
-    });
+    // `exec resume` takes no --sandbox: it inherits the sandbox the thread was
+    // opened with, and passing the flag is an error rather than a no-op. Which
+    // means the FIRST turn decides what the thread may touch for its whole life.
+    const sandbox = mode === "chat" ? "read-only" : "workspace-write";
+    const args = resumeSessionId
+      ? ["exec", "resume", resumeSessionId, "--skip-git-repo-check", "--json", fullPrompt]
+      : ["exec", "--sandbox", sandbox, "--skip-git-repo-check", "--json", fullPrompt];
+
+    const r = await runProcess({ command: "codex", args, cwd, env, timeoutMs });
+    const { threadId, text } = parseCodexEvents(r.stdout);
+
     return {
       exitCode: r.exitCode,
-      output: r.stdout.trim(),
+      // A build that emitted no parsable event still said something on stdout;
+      // falling back to the raw text keeps this adapter working as before.
+      output: text || String(r.stdout || "").trim(),
       stderr: r.stderr,
+      killed: r.killed,
+      sessionId: threadId || resumeSessionId || null,
       externalSessionPath: null,
     };
   },

package/src/core/runtimes/index.js

@@ -11,9 +11,24 @@
 //     id,
 //     binary,                         executable name to look for in PATH
 //     versionFlag,                    flag to print the version
-//     async run({ system, prompt, cwd, env, timeoutMs })
-//          → { exitCode, output, externalSessionPath?, raw? }
+//     sessions,                       "capture" when it can continue its own
+//                                     conversation; absent when every run
+//                                     starts cold
+//     async run({ system, prompt, cwd, env, timeoutMs,
+//                 sessionKey, resumeSessionId })
+//          → { exitCode, output, sessionId?, externalSessionPath?, raw? }
 //   }
+//
+// The session arguments are what turn a runtime from a one-shot into a real
+// a2a peer: `resumeSessionId` continues the conversation the peer already has,
+// and `sessionId` comes back so the caller can store it and resume again next
+// turn. `sessionKey` is a stable name for the exchange, for CLIs that can only
+// find their own session again by title (opencode); the ones that hand their id
+// straight back (claude-code, codex) ignore it.
+//
+// A runtime WITHOUT sessions is not shut out of a2a — the caller flattens the
+// thread history into the prompt instead. Sessions only make that unnecessary,
+// which is the point: a resumed peer does not re-read what it already knows.
 
 import claudeCode from "./claude-code.js";
 import codex from "./codex.js";

package/src/core/runtimes/opencode.js

@@ -1,27 +1,106 @@
 // OpenCode runtime adapter. Uses headless run:
 //   opencode run "<prompt>"
+//   opencode run --session <id> "<prompt>"   continue an earlier exchange
 // Reference: https://opencode.ai/docs/
 
+import fs from "node:fs";
+import path from "node:path";
 import { runProcess } from "./_spawn.js";
 
+// opencode prints an "agent · model" banner and ANSI colour even when its stdout
+// is a pipe. Neither is part of the answer, and an a2a reply is logged verbatim
+// — so a banner would be filed as the peer's first sentence.
+const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
+const BANNER = /^>\s+\S+\s+\S\s+\S+\s*$/;
+
+function cleanOutput(stdout) {
+  const lines = String(stdout || "").replace(ANSI, "").split("\n");
+  while (lines.length && !lines[0].trim()) lines.shift();
+  // Exactly one banner, and only when it leads: a reply that legitimately
+  // opens with a quoted line has to survive intact.
+  if (lines.length && BANNER.test(lines[0])) lines.shift();
+  return lines.join("\n").trim();
+}
+
+// opencode mints its own session ids and refuses one it did not create
+// ("Session not found"), so APX cannot dictate the id the way Claude Code
+// allows. What it CAN do is name the session on the way in (--title) and read
+// the id back out of `session list`, which speaks JSON. One extra call, only on
+// a thread's first turn — after that the id is on the ledger.
+async function findSessionByTitle({ title, cwd, env }) {
+  const r = await runProcess({
+    command: "opencode",
+    args: ["session", "list", "--format", "json", "-n", "40"],
+    cwd,
+    env,
+    timeoutMs: 20000,
+  });
+  if (r.exitCode !== 0) return null;
+  let rows;
+  try {
+    rows = JSON.parse(r.stdout);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(rows)) return null;
+  const named = rows.filter((s) => s && s.title === title);
+  // Sessions are listed across projects; prefer the one opened here.
+  const here = named.filter((s) => !cwd || !s.directory || s.directory === cwd);
+  const pick = (here.length ? here : named).sort((a, b) => (b.updated || 0) - (a.updated || 0))[0];
+  return pick?.id || null;
+}
+
+/**
+ * Why the session we just opened is not in opencode's own list.
+ *
+ * Observed: inside a git checkout `run --title X` is listed and resumable;
+ * in a plain directory the run succeeds but never appears, so there is no id to
+ * resume. Saying which case this is beats a silent null — the exchange still
+ * works (APX carries the thread in the prompt), it just costs a re-read a turn.
+ */
+function missingSessionReason(cwd) {
+  let dir = cwd || process.cwd();
+  for (;;) {
+    if (fs.existsSync(path.join(dir, ".git"))) return "opencode did not list the session it just opened";
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return "opencode keeps no resumable session outside a git repo — the thread travels in the prompt instead";
+}
+
 export default {
   id: "opencode",
   binary: "opencode",
   versionFlag: "--version",
+  sessions: "capture",
 
-  async run({ system, prompt, cwd, env, timeoutMs }) {
+  async run({ system, prompt, cwd, env, timeoutMs, sessionKey = null, resumeSessionId = null, mode = "code" }) {
     const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
-    const r = await runProcess({
-      command: "opencode",
-      args: ["run", fullPrompt],
-      cwd,
-      env,
-      timeoutMs,
-    });
+    const args = ["run"];
+    // `plan` is opencode's own read-only primary agent; `build` (its default)
+    // may write. A plain a2a message gets the one that only talks.
+    if (mode === "chat") args.push("--agent", "plan");
+    if (resumeSessionId) args.push("--session", resumeSessionId);
+    else if (sessionKey) args.push("--title", sessionKey);
+    args.push(fullPrompt);
+
+    const r = await runProcess({ command: "opencode", args, cwd, env, timeoutMs });
+
+    let sessionId = resumeSessionId || null;
+    let sessionNote = null;
+    if (!sessionId && sessionKey && r.exitCode === 0) {
+      sessionId = await findSessionByTitle({ title: sessionKey, cwd, env });
+      if (!sessionId) sessionNote = missingSessionReason(cwd);
+    }
+
     return {
       exitCode: r.exitCode,
-      output: r.stdout.trim(),
+      output: cleanOutput(r.stdout),
       stderr: r.stderr,
+      killed: r.killed,
+      sessionId,
+      sessionNote,
       externalSessionPath: null,
     };
   },

package/src/core/runtimes/outcome.js

@@ -0,0 +1,119 @@
+import { runProcess } from "./_spawn.js";
+import { detectAll } from "./detect.js";
+
+// Did the runtime actually do the work, and if not, what does the user need to
+// hear? Shared by every caller that spawns a CLI — the super-agent's
+// `call_runtime` tool and the a2a peer reply — because "exit 0 with nothing on
+// stdout" has to mean the same thing on both paths. A second copy of this
+// judgement is how one caller starts reporting a logged-out CLI as success.
+
+// A CLI that refuses to work says why in one line — "Not logged in · Please run
+// /login", "usage limit reached", "model requires a newer version". That line is
+// the whole diagnosis, and an `exit 1` that drops it leaves the model, the
+// session record and the daemon log all equally blind. Prefer stderr (where
+// CLIs put refusals), fall back to stdout (claude -p puts them in .result).
+// A machine-readable runtime answers in JSON; pasting the envelope would bury
+// the sentence inside it, so unwrap the field that carries the message.
+// Lines that carry a diagnosis rather than the machinery around it.
+const STACK_FRAME = /^(at\s|\.\.\.\s|Node\.js v)/;
+const DIAGNOSIS = /(error|failed|denied|invalid|expired|not logged|log ?in|usage limit|quota|unauthor|forbidden|not found|missing|required)/i;
+
+export function diagnosticLine(r) {
+  const pick = String(r?.stderr || "").trim() || String(r?.output || "").trim();
+  if (!pick) return "";
+  // A crashing CLI ends on `at async main (…cli.js:539307:5)`, which says
+  // nothing. Prefer the last line that reads like a cause; a stack frame is
+  // never one, and blindly taking the last line reported a 401 as a file path.
+  const lines = pick.split("\n").map((l) => l.trim()).filter(Boolean);
+  const meaningful = lines.filter((l) => !STACK_FRAME.test(l));
+  const line =
+    meaningful.filter((l) => DIAGNOSIS.test(l)).pop() ||
+    meaningful.pop() ||
+    lines.pop() ||
+    "";
+  if (line.startsWith("{")) {
+    try {
+      const o = JSON.parse(line);
+      const msg = o.result || o.error?.message || o.error || o.message;
+      if (typeof msg === "string" && msg.trim()) return msg.trim().slice(0, 160);
+    } catch { /* not JSON after all — fall through to the raw line */ }
+  }
+  return line.slice(0, 160);
+}
+
+// Decide if the runtime actually did the work the caller asked for. A spawn
+// failure (-1), a non-zero exit, or a clean exit with no captured output and
+// no transcript path all point at "process didn't really run" — exactly the
+// false-positive scenario this guard exists to catch.
+export function runtimeLooksLikeFailure(r, { timedOut = false, timeoutS = 0 } = {}) {
+  if (!r) return { failed: true, reason: "no runtime result" };
+  if (r.exitCode === -1 || r.error) {
+    return { failed: true, reason: r.error || "spawn error" };
+  }
+  // Order matters: we SIGTERM'd it ourselves, so whatever it exits with is our
+  // own signal echoed back. Reading that as the CLI's verdict would report a
+  // timeout as a crash — or, when the exit code is null, as "empty output".
+  // `r.killed` only arrives from adapters that bother to forward it; the clock
+  // is what every runtime has in common, so it decides.
+  if (timedOut || r.killed) {
+    return { failed: true, reason: `killed (timeout after ${timeoutS}s)` };
+  }
+  if (typeof r.exitCode === "number" && r.exitCode !== 0) {
+    const why = diagnosticLine(r);
+    return { failed: true, reason: why ? `exit ${r.exitCode}: ${why}` : `exit ${r.exitCode}` };
+  }
+  const out = String(r.output || "").trim();
+  const stderr = String(r.stderr || "").trim();
+  if (!out && !r.externalSessionPath && !r.sessionId) {
+    return {
+      failed: true,
+      reason: stderr ? `empty output (stderr: ${stderr.slice(0, 120)})` : "empty output",
+    };
+  }
+  return { failed: false };
+}
+
+// How long we wait for `<binary> --version` before giving up on the answer.
+// Not how long we wait for the runtime itself — that is the caller's timeout.
+export const PROBE_TIMEOUT_MS = 3000;
+
+/**
+ * Can this runtime run at all? Answered BEFORE spawning it for real, because
+ * "spawn error" is a useless thing to tell someone whose CLI is simply not
+ * installed. Shared with the super-agent's call_runtime tool so a missing
+ * binary reads the same however it was reached.
+ */
+export async function runtimeAvailability(runtime, rt, { probeTimeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  const probe = await runProcess({
+    command: rt.binary,
+    args: rt.versionFlag ? [rt.versionFlag] : ["--version"],
+    timeoutMs: probeTimeoutMs,
+  });
+  if (probe.exitCode === 0 || probe.stdout || probe.stderr) {
+    return { ok: true };
+  }
+  // A probe WE killed is not evidence of absence — it is evidence of presence.
+  // A binary that is not there fails at spawn (ENOENT, exitCode -1) and never
+  // gets far enough to be killed, so `killed` can only mean the binary exists,
+  // started, and was slower than our clock. Under load `--version` really does
+  // take longer than three seconds, and reading that as "not installed" refused
+  // to run a CLI sitting right there — then fell into detectAll() below, which
+  // spawns EVERY coding CLI on the machine to reach a verdict we already had.
+  if (probe.killed) {
+    return { ok: true };
+  }
+
+  const detected = await detectAll();
+  const current = detected.find((d) => d.id === runtime || d.binary === rt.binary);
+  if (current?.installed) {
+    return { ok: true, detected };
+  }
+  return {
+    ok: false,
+    reason: current?.reason || `${rt.binary} not found`,
+    detected,
+    installed: detected
+      .filter((d) => d.category === "runtime" && d.installed)
+      .map((d) => d.id),
+  };
+}