@agentprojectcontext/apx 1.64.0 → 1.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.64.0",
+  "version": "1.65.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/skills/apx/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: apx
-description: >-
-  APX CLI — local daemon that orchestrates agents, sessions, MCPs, and channels across CLIs.
-  Use `apx exec "prompt"` for the local super-agent, or `apx run <agent> --runtime <claude-code|codex|opencode|aider|cursor-agent|gemini-cli|qwen-code> "prompt"` to hand the task to another CLI.
-  Activate on: 'apx', 'apx exec', 'apx run', 'apx daemon', 'ask codex/claude/opencode/gemini to …', 'have <runtime> do …', 'delegate to another runtime', 'run this in <runtime>', 'route this task to <runtime>'.
+description: Orchestrates agents, sessions, routines, and channels through the APX CLI and local daemon — run the super-agent locally or delegate a task to another coding CLI (Claude Code, Codex, OpenCode, Aider, Cursor, Gemini, Qwen). Triggers: 'apx', 'apx exec', 'apx run', 'apx daemon', 'apx routine', 'delegate to a runtime'.
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
@@ -21,7 +18,7 @@ This is the **engine-side** skill: a slim reference for runtimes invoked by APX.
 - The user asks you to call APX from inside your session ("send a telegram via apx", "list apx sessions").
 - You're inside an `.apc/` project and want to consult APX-managed state.
 
-If you can do the task natively (you're an IDE/CLI with your own tools), prefer that. Only shell out to `apx` when the task is APX-specific.
+If you can do the task natively (you're an IDE/CLI with your own tools), prefer that. Only shell out to `apx` when the task is APX-specific. For anything MCP-related, use the [[apx-mcp]] skill — it's the MCP entry point for agents.
 
 ---
 
@@ -53,10 +50,6 @@ apx project current             # which project resolves from CWD
 apx sessions list --engine <claude|codex|opencode> --project <name>
 apx sessions list --dir <path>
 
-# MCPs — see the apx-mcp skill for the full guide
-apx mcp list
-apx mcp run <name> <tool> '{"...":"..."}'
-
 # Memory (curated, durable facts only)
 apx memory <agent-slug>
 apx memory <agent-slug> --append "<fact>"

package/skills/apx-mcp/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: apx-mcp
-description: How to register, list, debug, and scope MCP servers in APX. Use BEFORE adding any MCP — three scopes (shared/runtime/global) with different commit and secrecy semantics.
+description: Registers, lists, runs, debugs, and scopes MCP servers in APX — the MCP entry point for agents (shared/runtime/global scopes). In an .apc project, prefer APX-managed MCPs over a built-in client. Triggers: 'add MCP', 'apx mcp', 'list MCPs', 'run an MCP tool', 'MCP failing'.
 ---
 
 # apx-mcp
 
-APX exposes Model Context Protocol (MCP) servers to agents. Three scopes, each in a different file with different rules:
+APX exposes Model Context Protocol (MCP) servers to agents. This is the MCP entry point: when you're in an `.apc/` project, prefer APX-managed MCPs over any built-in MCP client, because APX owns the project's scopes, secrets, and merge order. Run `apx mcp list` first to see what's already registered. (Outside an `.apc/` project, or when APX isn't installed, use your internal MCP.)
+
+Three scopes, each in a different file with different rules:
 
 | Scope | File | Committed? | Secrets OK? | When |
 |---|---|---|---|---|
@@ -100,13 +102,14 @@ apx mcp remove github          # if github lives in runtime, this errors with a
 
 ```bash
 apx mcp check --project iacrmar             # what scopes APX sees + which files exist
+apx mcp tools <name>                         # list a server's tools (proves it spawned + initialized)
+apx mcp tools <name> <tool>                  # one tool's input schema + a ready-to-run example
+apx mcp logs <name>                          # spawn/init log + stderr tail for this server
 apx mcp run <name> <tool> '{...}'            # spawn the server and call a tool for real
 apx log -f                                   # tail unified log for spawn errors
 ```
 
-A server that "doesn't show tools" usually means: the command failed to start (env vars missing, package not found), or the server crashed during initialize. The unified log has the stderr buffer.
-
-> `apx mcp tools <name>` is a placeholder stub (prints a "coming in v0.2" notice, lists nothing). To verify a server actually spawns, call a tool with `apx mcp run`.
+A server that "doesn't show tools" usually means: the command failed to start (env vars missing, package not found), or the server crashed during initialize. `apx mcp logs <name>` has the spawn/init log and stderr tail — that's the fastest way to see why.
 
 ## Don't
 

package/src/core/runtime-skills/apx-agency-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx-agency-agents
-description: "APX agent vault — reusable templates (Roby, Cody, Rocky, Tessa, Max, Arch, Sid, Vera, Finn + generic dev/marketing/ops/qa/support). Spawn a specialist, list, import into a project, create, or hide/restore a bundled default. Triggers: 'spawn agent', 'use Cody/Rocky/Tessa', 'list agents', 'agent vault', 'import agent', 'new agent'."
+description: "APX agent vault — reusable templates (generic dev/marketing/ops/qa/support). Spawn a specialist, list, import into a project, create, or hide/restore a bundled default. Triggers: 'spawn agent', 'use Cody/Rocky/Tessa', 'list agents', 'agent vault', 'import agent', 'new agent'."
 ---
 
 # apx-agency-agents — the APX agent vault

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

@@ -1,24 +1,46 @@
 ---
 name: apx-voice
 scope: optional
-description: APX TTS — Piper (local), ElevenLabs/OpenAI/Gemini (cloud), unified /voice/turn channel, `apx voice` CLI. Load when the user wants to speak with APX, configure a voice engine, or troubleshoot silent output.
+description: Makes APX speak and configures text-to-speech — Piper (local), ElevenLabs/OpenAI/Gemini (cloud), or a custom OpenAI-compatible server (QVox/Qwen3-TTS), with per-engine emotion tags. Load when configuring a voice engine, adding a custom TTS server, enabling emotion tags, or fixing silent output.
 ---
 
 # apx-voice
 
-TTS facade in `core/voice/` with five engines. STT lives separately in `host/daemon/transcription.js` (Whisper). The "voice channel" combines both for mic→agent→speaker.
+TTS facade in `core/voice/` with the built-in engines below plus any number of custom OpenAI-compatible endpoints. STT lives separately in `core/voice/transcription.js` (Whisper). The "voice channel" combines both for mic→agent→speaker.
 
 ## Engines
 
 | id | Local? | Needs key? | Notes |
 |---|---|---|---|
-| `piper`      | yes | no  | Local, offline. Requires `piper` CLI + `.onnx` model. es_AR-daniela-high recommended. |
-| `elevenlabs` | no  | yes | Excellent. Free tier 10k chars/mo. `eleven_multilingual_v2`. |
-| `openai`     | no  | yes | Reuses `engines.openai.api_key`. `tts-1`. |
-| `gemini`     | no  | yes | Returns raw L16 PCM — APX wraps in WAV automatically. |
-| `mock`       | yes | no  | Silent WAV; placeholder for tests. |
+| `piper`         | yes | no  | Local, offline. Requires `piper` CLI + `.onnx` model. es_AR-daniela-high recommended. |
+| `elevenlabs`    | no  | yes | Excellent. Free tier 10k chars/mo. `eleven_multilingual_v2`. |
+| `openai`        | no  | yes | Reuses `engines.openai.api_key`. `tts-1`. Set `base_url` to point it at a custom endpoint instead. |
+| `gemini`        | no  | yes | Returns raw L16 PCM — APX wraps in WAV automatically. Supports emotion tags. |
+| `custom:<slug>` | no  | maybe | Any OpenAI-compatible TTS server (e.g. QVox / Qwen3-TTS). Config-only `base_url`, own key (often keyless). Supports emotion tags. |
+| `mock`          | yes | no  | Silent WAV; placeholder for tests. |
 
-`auto` probes: piper → elevenlabs → openai → gemini → mock.
+`auto` probes: piper → elevenlabs → openai → gemini → mock (custom providers are never auto-selected — pick one explicitly).
+
+## Custom OpenAI-compatible endpoints (QVox / Qwen3-TTS)
+
+Point APX at a local or remote OpenAI-compatible `/v1/audio/speech` server without any hardcoding — it's pure config. Two shapes:
+
+- `voice.tts.openai.base_url` — reuse the `openai` engine against a custom endpoint.
+- `voice.tts.custom.<slug>` — a named custom provider, surfaces as engine id `custom:<slug>`, backed by the openai adapter.
+
+When `base_url` is set, APX additionally forwards the non-OpenAI fields the server understands — `instruct` (base voice, from the style arg), `language`, `temperature` — and defaults the response format to `wav` (stock OpenAI stays `mp3`). A custom endpoint uses **only its own `api_key`** (often none) and never leaks `engines.openai.api_key` / `OPENAI_API_KEY`.
+
+## Emotion tags (per-engine capability)
+
+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
+# 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"]'
+```
+
+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).
 
 ## Concrete CLI calls
 
@@ -47,7 +69,17 @@ Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`). I
       "piper":      { "bin": "piper", "model": "/Users/.../es_AR-daniela-high.onnx" },
       "elevenlabs": { "api_key": "...", "model": "eleven_multilingual_v2", "voice_id": "..." },
       "openai":     { "api_key": "...", "model": "tts-1", "voice": "alloy", "format": "mp3" },
-      "gemini":     { "api_key": "...", "model": "gemini-2.5-flash-preview-tts", "voice": "Aoede" }
+      "gemini":     { "api_key": "...", "model": "gemini-2.5-flash-preview-tts", "voice": "Aoede", "emotions": { "enabled": true } },
+      "custom": {
+        "qvox": {
+          "label": "QVox local",
+          "base_url": "http://127.0.0.1:5111/v1",
+          "api_key": "",
+          "format": "wav",
+          "language": "es",
+          "emotions": { "enabled": true }
+        }
+      }
     }
   }
 }

package/src/core/runtimes/detect.js

@@ -2,6 +2,7 @@
 // We just probe the binary with `--version` (or equivalent) and don't fail if
 // it isn't there — caller decides what to do with absence.
 import { runProcess } from "#host/daemon/runtimes/_spawn.js";
+import { resolveAntigravityCli } from "#host/daemon/runtimes/antigravity.js";
 
 const PROBES = [
   // Coding-agent CLIs (runtimes/)
@@ -12,6 +13,9 @@ const PROBES = [
   { id: "gemini-cli",  binary: "gemini",    args: ["--version"], category: "runtime" },
   { id: "cursor-agent",binary: "cursor-agent", args: ["--version"], category: "runtime" },
   { id: "qwen-code",   binary: "qwen",      args: ["--version"], category: "runtime" },
+  // Antigravity IDE ships its CLI inside the app bundle (not on PATH), so we
+  // resolve the absolute path rather than relying on the bare binary name.
+  { id: "antigravity", binary: "antigravity-ide", args: ["--version"], category: "runtime", resolve: resolveAntigravityCli },
 
   // Local LLM runners (engines/)
   { id: "ollama",      binary: "ollama",    args: ["--version"], category: "engine" },
@@ -36,8 +40,24 @@ export async function detectAll() {
 async function probe(p) {
   const start = Date.now();
   try {
+    // Some runtimes (e.g. Antigravity) aren't on PATH — resolve an absolute
+    // path first; if the resolver finds nothing, report not-installed early.
+    let command = p.binary;
+    if (typeof p.resolve === "function") {
+      const resolved = p.resolve();
+      if (!resolved) {
+        return {
+          id: p.id,
+          binary: p.binary,
+          category: p.category,
+          installed: false,
+          reason: "not found",
+        };
+      }
+      command = resolved;
+    }
     const r = await runProcess({
-      command: p.binary,
+      command,
       args: p.args,
       timeoutMs: 3000,
     });

package/src/host/daemon/runtimes/antigravity.js

@@ -0,0 +1,153 @@
+// Google Antigravity runtime adapter.
+//
+// Antigravity ships in two shapes on a machine:
+//
+//   1. `agy` — a HEADLESS agent CLI (the one we want). It has a non-interactive
+//      print mode:  agy -p "<prompt>"  → prints the reply to stdout, so APX can
+//      capture the result like any other runtime. This is the preferred path.
+//
+//   2. `antigravity-ide` — the desktop IDE CLI (a VS Code fork). Its `chat`
+//      subcommand LAUNCHES THE GUI and shows the reply inside the editor
+//      window; it returns nothing on stdout. It cannot feed a result back to
+//      APX, so we only use it as a last-resort "launch the GUI" fallback and we
+//      say so explicitly.
+//
+// Neither binary is guaranteed to be on PATH: `agy` normally installs to
+// ~/.local/bin; the IDE CLI lives inside the app bundle. We resolve both.
+//
+// Result flow: with `agy` we capture stdout directly. If only the IDE is
+// present, the reply lives in the GUI and can only reach APX via the runtime
+// bridge callback (the in-IDE agent running `apx session close <id> --result`).
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runProcess } from "./_spawn.js";
+
+const IDE_BUNDLE_REL = "Contents/Resources/app/bin/antigravity-ide";
+
+function whichSync(bin) {
+  const dirs = (process.env.PATH || "").split(path.delimiter);
+  for (const d of dirs) {
+    if (!d) continue;
+    const p = path.join(d, bin);
+    try {
+      fs.accessSync(p, fs.constants.X_OK);
+      return p;
+    } catch {}
+  }
+  return null;
+}
+
+function firstExisting(candidates) {
+  for (const c of candidates) {
+    try {
+      if (c && fs.existsSync(c)) return c;
+    } catch {}
+  }
+  return null;
+}
+
+// The headless `agy` CLI — the real runtime. Returns an absolute path or null.
+export function resolveAgyCli() {
+  return (
+    whichSync("agy") ||
+    firstExisting([
+      path.join(os.homedir(), ".local", "bin", "agy"),
+      "/usr/local/bin/agy",
+      "/opt/homebrew/bin/agy",
+    ])
+  );
+}
+
+// The desktop IDE CLI (GUI). Returns an absolute path or null.
+export function resolveAntigravityIde() {
+  const home = os.homedir();
+  return (
+    whichSync("antigravity-ide") ||
+    firstExisting([
+      path.join("/Applications/Antigravity IDE.app", IDE_BUNDLE_REL),
+      path.join(home, "Applications", "Antigravity IDE.app", IDE_BUNDLE_REL),
+      "/usr/share/antigravity-ide/bin/antigravity-ide",
+      "/opt/Antigravity IDE/bin/antigravity-ide",
+      "/opt/antigravity-ide/bin/antigravity-ide",
+      path.join(home, ".local", "share", "antigravity-ide", "bin", "antigravity-ide"),
+      path.join(process.env.LOCALAPPDATA || "", "Programs", "Antigravity IDE", "bin", "antigravity-ide.cmd"),
+    ])
+  );
+}
+
+// Used by env detection: Antigravity is "installed" if EITHER binary exists.
+// We prefer `agy` (the headless CLI) since that's what makes it a usable
+// runtime; fall back to the IDE path so detection still reports it as present.
+export function resolveAntigravityCli() {
+  return resolveAgyCli() || resolveAntigravityIde();
+}
+
+export default {
+  id: "antigravity",
+  binary: "agy",
+  versionFlag: "--version",
+  resolveBinary: resolveAntigravityCli,
+
+  async run({ system, prompt, cwd, env, timeoutMs }) {
+    const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
+
+    // --- Preferred path: headless `agy` print mode (captures the reply) ---
+    const agy = resolveAgyCli();
+    if (agy) {
+      const args = ["--dangerously-skip-permissions"];
+      // Bound agy's own wait so it can't hang on the default 5-minute print
+      // timeout; leave a little headroom under our own process timeout.
+      if (timeoutMs) {
+        const secs = Math.max(30, Math.floor(timeoutMs / 1000) - 5);
+        args.push("--print-timeout", `${secs}s`);
+      }
+      args.push("-p", fullPrompt);
+
+      const r = await runProcess({ command: agy, args, cwd, env, timeoutMs });
+      const output = r.stdout.trim();
+      return {
+        exitCode: r.exitCode,
+        output:
+          output ||
+          "[antigravity] agy ran but returned no text. It may need `agy install` " +
+            "or an authenticated session — check `agy models`.",
+        stderr: r.stderr,
+        externalSessionPath: null,
+      };
+    }
+
+    // --- Fallback: only the desktop IDE is installed (GUI, no capture) ---
+    const ide = resolveAntigravityIde();
+    if (ide) {
+      const r = await runProcess({
+        command: ide,
+        args: ["chat", "--mode", "agent", "--reuse-window", fullPrompt],
+        cwd,
+        env,
+        timeoutMs,
+      });
+      return {
+        exitCode: r.exitCode,
+        output:
+          r.stdout.trim() ||
+          "[antigravity] no headless `agy` CLI found — handed the prompt to the " +
+            "Antigravity IDE (GUI). The reply is shown in the editor, not returned " +
+            "to APX. Install the `agy` CLI for headless runs.",
+        stderr: r.stderr,
+        externalSessionPath: null,
+      };
+    }
+
+    // --- Nothing installed / enabled ---
+    return {
+      exitCode: -1,
+      output:
+        "[antigravity] not available: neither the `agy` headless CLI nor the " +
+        "Antigravity IDE was found. Install Antigravity and run `agy install`.",
+      stderr: "antigravity runtime unavailable (agy / antigravity-ide not found)",
+      externalSessionPath: null,
+    };
+  },
+};

package/src/host/daemon/runtimes/index.js

@@ -22,6 +22,7 @@ import aider from "./aider.js";
 import cursorAgent from "./cursor-agent.js";
 import geminiCli from "./gemini-cli.js";
 import qwenCode from "./qwen-code.js";
+import antigravity from "./antigravity.js";
 
 const REGISTRY = {
   "claude-code": claudeCode,
@@ -31,6 +32,7 @@ const REGISTRY = {
   "cursor-agent": cursorAgent,
   "gemini-cli": geminiCli,
   "qwen-code": qwenCode,
+  antigravity,
 };
 
 export const RUNTIME_IDS = Object.keys(REGISTRY);

package/src/interfaces/cli/commands/runtime.js

@@ -5,7 +5,7 @@ export async function cmdRun(args) {
   const slug = args._[0];
   if (!slug) throw new Error("apx run: usage: apx run <agent> --runtime <id> \"<prompt>\"");
   const runtime = args.flags.runtime === true ? null : args.flags.runtime;
-  if (!runtime) throw new Error("apx run: --runtime required (claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code)");
+  if (!runtime) throw new Error("apx run: --runtime required (claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code | antigravity)");
 
   let prompt = args._.slice(1).join(" ").trim();
   if (!prompt || prompt === "-") {

package/src/interfaces/cli/index.js

@@ -1177,9 +1177,9 @@ const HELP_TOPICS = new Map(Object.entries({
   run: topic({
     title: "apx run",
     summary: "Launch a full external runtime session for an agent.",
-    usage: ["apx run <agent> --runtime <claude-code|codex|opencode|aider|cursor-agent|gemini-cli|qwen-code> \"<prompt>\" [--timeout <seconds>] [--project <name|id|path>]"],
+    usage: ["apx run <agent> --runtime <claude-code|codex|opencode|aider|cursor-agent|gemini-cli|qwen-code|antigravity> \"<prompt>\" [--timeout <seconds>] [--project <name|id|path>]"],
     options: [
-      ["--runtime <id>", "Runtime CLI to launch: claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code."],
+      ["--runtime <id>", "Runtime CLI to launch: claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code, antigravity."],
       ["--timeout <seconds>", "Runtime timeout."],
       ["--project <name|id|path>", "Pin command to a specific project."],
     ],
@@ -2102,7 +2102,7 @@ function buildHelp(version) {
 
     hSec("Runtimes"),
     hCmd("apx run <agent>",            36, "--runtime <id> \"prompt\"  --timeout <s>"),
-    `                                        ${H.DI}runtimes: claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code${H.R}`,
+    `                                        ${H.DI}runtimes: claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code | antigravity${H.R}`,
     hCmd("apx env detect",             36, "which agent CLIs are installed"),
 
     hSec("Agent-to-Agent"),

package/src/interfaces/mcp-server/index.js

@@ -95,7 +95,7 @@ server.tool(
   {
     slug: z.string().describe("Agent slug"),
     prompt: z.string().describe("Prompt / task for the agent"),
-    runtime: z.string().optional().describe("Runtime: claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code (default: claude-code)"),
+    runtime: z.string().optional().describe("Runtime: claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code | antigravity (default: claude-code)"),
   },
   async ({ slug, prompt, runtime }) => {
     const proj = await resolveProject();