@agentprojectcontext/apx 1.25.0 → 1.27.1

package/src/{cli → interfaces/cli}/commands/agent.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { findApfRoot, readAgents, readVaultAgents, VAULT_DIR, SLUG_RE } from "../../core/parser.js";
-import { writeAgentFile, writeVaultAgentFile, addImportedAgent, ensureAgentDir, regenerateAgentsMd } from "../../core/scaffold.js";
+import { findApfRoot, readAgents, readVaultAgents, readVaultAgent, VAULT_DIR, SLUG_RE } from "../../../core/parser.js";
+import { writeAgentFile, writeVaultAgentFile, removeVaultAgent, restoreVaultAgent, addImportedAgent, ensureAgentDir } from "../../../core/scaffold.js";
 import { http } from "../http.js";
 
 // ── ANSI ──────────────────────────────────────────────────────────────────────
@@ -49,7 +49,6 @@ export async function cmdAgentAdd(args) {
 
   writeAgentFile(root, slug, fields);
   ensureAgentDir(root, slug);
-  regenerateAgentsMd(root);
   await nudgeDaemon(root);
 
   console.log(`Added agent ${slug}`);
@@ -100,10 +99,11 @@ export function cmdAgentGet(args) {
 
 // ── Vault commands ────────────────────────────────────────────────────────────
 
-export function cmdAgentVaultList() {
-  const vault = readVaultAgents();
+export function cmdAgentVaultList(args = { flags: {} }) {
+  const includeRemoved = !!args.flags.all || !!args.flags["include-removed"];
+  const vault = readVaultAgents({ includeRemoved });
   if (vault.length === 0) {
-    console.log(dim(`(vault empty — add templates with \`apx agent vault add <slug>\`)`));
+    console.log(dim(`(vault empty — bundled defaults missing? add one with \`apx agent vault add <slug>\`)`));
     console.log(gray(`  vault: ${VAULT_DIR}`));
     return;
   }
@@ -111,10 +111,16 @@ export function cmdAgentVaultList() {
   for (const a of vault) {
     const role  = a.fields.Role  ? dim(a.fields.Role)  : gray("—");
     const model = a.fields.Model ? dim(a.fields.Model) : gray("—");
-    console.log(`  ${bold(a.slug)}  ${role}  ${cyan(model)}`);
+    const tag   = a.source === "bundled"        ? gray("[bundled]")
+                : a.source === "user-override" ? tag2("[override]")
+                : a.source === "user"          ? tag2("[user]")
+                : "";
+    console.log(`  ${bold(a.slug)}  ${role}  ${cyan(model)}  ${tag}`);
   }
   console.log();
 }
+// Local helper just for the list table coloring above.
+function tag2(s) { return `${c.green}${s}${c.reset}`; }
 
 export async function cmdAgentVaultAdd(args) {
   const slug = args._[0];
@@ -144,6 +150,36 @@ export async function cmdAgentVaultAdd(args) {
   console.log(`\n  ${bold(slug)} added to vault  ${gray(VAULT_DIR + "/" + slug + ".md")}\n`);
 }
 
+// Remove a vault template. If the slug exists in the bundle a tombstone is
+// written so it stays hidden until `apx agent vault restore <slug>`. User-
+// layer files are physically removed.
+export function cmdAgentVaultRm(args) {
+  const slug = args._[0];
+  if (!slug || !SLUG_RE.test(slug)) throw new Error("apx agent vault rm: missing or invalid <slug>");
+  const before = readVaultAgent(slug, { includeRemoved: true });
+  if (!before) throw new Error(`"${slug}" not found in vault (bundled or user)`);
+  const out = removeVaultAgent(slug);
+  if (out.removed === "tomb") {
+    console.log(`  ${tag("hidden")}  ${bold(slug)}  ${gray("(bundled default tombstoned — restore with `apx agent vault restore`)")}`);
+  } else if (out.removed === "user") {
+    console.log(`  ${tag("removed")}  ${bold(slug)}  ${gray("(user template deleted; no bundled default exists)")}`);
+  } else if (out.removed === "user+tomb") {
+    console.log(`  ${tag("removed")}  ${bold(slug)}  ${gray("(user override deleted + bundled tombstoned)")}`);
+  }
+}
+
+// Un-tombstone a bundled slug. No-op if it wasn't hidden.
+export function cmdAgentVaultRestore(args) {
+  const slug = args._[0];
+  if (!slug || !SLUG_RE.test(slug)) throw new Error("apx agent vault restore: missing or invalid <slug>");
+  const out = restoreVaultAgent(slug);
+  if (!out.restored) {
+    console.log(dim(`  (slug "${slug}" was not tombstoned — nothing to restore)`));
+    return;
+  }
+  console.log(`  ${cyan("restored")}  ${bold(slug)}  ${gray("(bundled default visible again)")}`);
+}
+
 export async function cmdAgentImport(args) {
   const slug = args._[0];
   if (!slug) throw new Error("apx agent import: missing <slug>");
@@ -176,6 +212,5 @@ export async function cmdAgentImport(args) {
   }
 
   ensureAgentDir(root, slug);
-  regenerateAgentsMd(root);
   await nudgeDaemon(root);
 }

package/src/{cli → interfaces/cli}/commands/command.js

@@ -1,7 +1,7 @@
 // apx command — list and show workflow commands from .apc/commands/
 import fs from "node:fs";
 import path from "node:path";
-import { findApfRoot } from "../../core/parser.js";
+import { findApfRoot } from "../../../core/parser.js";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 

package/src/{cli → interfaces/cli}/commands/config.js

@@ -1,6 +1,6 @@
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
-import { readConfig, writeConfig } from "../../core/config.js";
+import { readConfig, writeConfig } from "../../../core/config.js";
 
 function parseValue(raw) {
   // best-effort: try JSON first (covers numbers, bools, objects, arrays, null,

package/src/{cli → interfaces/cli}/commands/daemon.js

@@ -3,6 +3,16 @@ import os from "node:os";
 import path from "node:path";
 import { ensureDaemon, http } from "../http.js";
 
+// Wait until nothing answers on the daemon port (old process fully exited and
+// released it), so a fresh start can bind it. Resolves true when down.
+async function waitForPortReleased({ tries = 40, intervalMs = 150 } = {}) {
+  for (let i = 0; i < tries; i++) {
+    if (!(await http.ping(200))) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
 const PID_PATH = path.join(os.homedir(), ".apx", "daemon.pid");
 const LOG_PATH = path.join(os.homedir(), ".apx", "daemon.log");
 
@@ -97,6 +107,63 @@ export async function cmdDaemonStatus(args = {}) {
   console.log();
 }
 
+export async function cmdDaemonReload(args = {}) {
+  const debug = args.flags?.debug;
+  if (!(await http.ping())) {
+    console.log(`\n  ${fmt.yellow("○")} ${fmt.bold("apx daemon")}  ${fmt.dim("not running — start first")}\n`);
+    process.exit(1);
+  }
+  const res = await http.post("/admin/reload", undefined, { autoStart: false });
+  if (debug) debugRaw("/admin/reload", res);
+  console.log(`\n  ${fmt.green("↻")} ${fmt.bold("config reloaded")}`);
+  if (res.super_agent_model) console.log(fmt.kv("model", fmt.cyan(res.super_agent_model)));
+  if (res.fallback_order?.length) console.log(fmt.kv("fallback", fmt.cyan(res.fallback_order.join(" → "))));
+  console.log();
+}
+
+export async function cmdDaemonRestart(args = {}) {
+  const debug = args.flags?.debug;
+  const wasRunning = await http.ping();
+
+  if (wasRunning) {
+    // Ask the daemon to shut down cleanly; fall back to a PID kill if the
+    // HTTP shutdown route is unreachable (same fallback as `stop`).
+    try {
+      const res = await http.post("/admin/shutdown", undefined, { autoStart: false });
+      if (debug) debugRaw("/admin/shutdown", res);
+    } catch {
+      if (fs.existsSync(PID_PATH)) {
+        try {
+          const pid = parseInt(fs.readFileSync(PID_PATH, "utf8"), 10);
+          if (pid) process.kill(pid);
+        } catch {}
+      }
+    }
+    // The old process must release port 7430 before we start a fresh one,
+    // otherwise ensureDaemon() sees it alive and starts nothing.
+    if (!(await waitForPortReleased())) {
+      console.log(
+        `\n  ${fmt.red("○")} ${fmt.bold("apx daemon")}  ` +
+        `${fmt.dim("did not shut down in time — aborting restart")}\n`
+      );
+      process.exit(1);
+    }
+    process.stderr.write("apx: restarting daemon...\n");
+  } else {
+    process.stderr.write("apx: daemon not running — starting...\n");
+  }
+
+  await ensureDaemon({ silent: true });
+  const status = await http.get("/health", { autoStart: false });
+  if (debug) debugRaw("/health", status);
+  console.log(
+    `\n  ${fmt.green("●")} ${fmt.bold("apx daemon")} ${fmt.dim("v" + status.version)}` +
+    `  ${fmt.gray("·")}  ${fmt.green(wasRunning ? "restarted" : "started")}` +
+    `  ${fmt.gray("·")}  ${fmt.cyan("port")} ${status.port ?? (process.env.APX_PORT || 7430)}` +
+    `  ${fmt.gray("·")}  ${fmt.cyan("uptime")} ${uptime(status.uptime_s)}\n`
+  );
+}
+
 export async function cmdDaemonStop(args = {}) {
   const debug = args.flags?.debug;
 

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

@@ -0,0 +1,335 @@
+// apx desktop — launch/manage the floating voice desktop window (Electron).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { http } from "../http.js";
+import {
+  autostartIsOn as _autostartIsOn,
+  autostartInstall,
+  autostartUninstall,
+  getApxRunner as _getApxRunner,
+  buildPlist as _buildPlist,
+  MAC_PLIST_PATH,
+  LINUX_DESKTOP_PATH,
+  WIN_RUN_KEY,
+  WIN_RUN_NAME,
+} from "../../../core/desktop/autostart.js";
+
+// Re-exports — kept so existing tests (tests/desktop-autostart.test.js)
+// can still import these directly from the CLI module.
+export const getApxRunner = _getApxRunner;
+export const buildPlist   = _buildPlist;
+export const autostartIsOn = _autostartIsOn;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+const DESKTOP_MAIN  = path.resolve(__dirname, "../../desktop/main.js");
+const DESKTOP_PID   = path.join(os.homedir(), ".apx", "desktop.pid");
+
+// ── ANSI ─────────────────────────────────────────────────────────────────────
+const c = { reset:"\x1b[0m", bold:"\x1b[1m", dim:"\x1b[2m", green:"\x1b[32m",
+            red:"\x1b[31m", yellow:"\x1b[33m", cyan:"\x1b[36m", gray:"\x1b[90m" };
+const fmt = {
+  bold:(s)=>`${c.bold}${s}${c.reset}`, dim:(s)=>`${c.dim}${s}${c.reset}`,
+  green:(s)=>`${c.green}${s}${c.reset}`, red:(s)=>`${c.red}${s}${c.reset}`,
+  cyan:(s)=>`${c.cyan}${s}${c.reset}`,  gray:(s)=>`${c.gray}${s}${c.reset}`,
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function readPid() {
+  try { return parseInt(fs.readFileSync(DESKTOP_PID, "utf8").trim(), 10); } catch { return null; }
+}
+function writePid(pid) {
+  fs.mkdirSync(path.dirname(DESKTOP_PID), { recursive: true });
+  fs.writeFileSync(DESKTOP_PID, String(pid));
+}
+function clearPid() { try { fs.unlinkSync(DESKTOP_PID); } catch {} }
+function pidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+// Validate that an electron candidate actually runs (a pnpm shim can exist as a
+// file while its underlying package was never built — `--version` smokes that out).
+function electronRuns(cmd, argv) {
+  try {
+    execFileSync(cmd, argv, { stdio: "ignore", timeout: 5000 });
+    return true;
+  } catch { return false; }
+}
+
+// Returns a descriptor used by buildElectronSpawn():
+//   absolute path to a real electron binary,
+//   absolute path to electron's cli.js (".js" → run via node),
+//   "npx" as a last-resort fallback (downloads/uses electron via npx).
+// Never returns null — npx is always attempted so the user gets a real error
+// from the spawn (and a one-time download) rather than a silent no-op.
+export function findElectron() {
+  // commands/ is 4 levels under the project root: src/interfaces/cli/commands/
+  const root = path.resolve(__dirname, "..", "..", "..", "..");
+  const bin  = path.join(root, "node_modules", ".bin", "electron");
+  // The .bin shim is a shell wrapper that `exec node …`. Under launchd's
+  // minimal PATH (`/usr/bin:/bin:/usr/sbin:/sbin`) `node` isn't found, so the
+  // shim fails. We try it first (cheap, works for terminal use) and then fall
+  // back to invoking electron's cli.js directly with process.execPath, which
+  // is launchd-safe.
+  if (fs.existsSync(bin) && electronRuns(bin, ["--version"])) return bin;
+
+  const cli = path.join(root, "node_modules", "electron", "cli.js");
+  if (fs.existsSync(cli) && electronRuns(process.execPath, [cli, "--version"])) return cli;
+
+  // Global electron on PATH (works from terminal, usually not from launchd)
+  try {
+    const which = execFileSync("which", ["electron"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    if (which && electronRuns(which, ["--version"])) return which;
+  } catch {}
+
+  // Last resort: npx (pulls electron if absent). Will ENOENT under launchd if
+  // npx isn't on PATH — that's why we try cli.js BEFORE this.
+  return "npx";
+}
+
+// Turn a findElectron() descriptor + the app entry into a { cmd, argv } pair.
+export function buildElectronSpawn(descriptor, mainPath, port) {
+  if (descriptor === "npx") {
+    return { cmd: "npx", argv: ["-y", "electron", mainPath, "--port", port] };
+  }
+  if (descriptor.endsWith(".js")) {
+    return { cmd: process.execPath, argv: [descriptor, mainPath, "--port", port] };
+  }
+  return { cmd: descriptor, argv: [mainPath, "--port", port] };
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+export async function cmdDesktopStart(args = {}) {
+  const debug = !!(args.debug || args.d);
+
+  const pid = readPid();
+  if (pidAlive(pid)) {
+    if (debug) {
+      console.log(`\n  ${fmt.cyan("●")} Desktop already running ${fmt.dim("pid " + pid)} — stop it first with: apx desktop stop\n`);
+      return;
+    }
+    console.log(`\n  ${fmt.cyan("●")} Desktop already running ${fmt.dim("pid " + pid)}\n`);
+    return;
+  }
+  clearPid();
+
+  if (!fs.existsSync(DESKTOP_MAIN)) {
+    console.error(`\n  ${fmt.red("✗")} Desktop app not found at ${fmt.dim(DESKTOP_MAIN)}\n`);
+    process.exit(1);
+  }
+
+  const electronDescriptor = findElectron();
+
+  // Get daemon port from running daemon or env
+  let daemonPort = process.env.APX_PORT || "7430";
+  try {
+    const health = await http.get("/health").catch(() => null);
+    if (health?.port) daemonPort = String(health.port);
+  } catch {}
+
+  const { cmd, argv } = buildElectronSpawn(electronDescriptor, DESKTOP_MAIN, daemonPort);
+
+  const logFile = path.join(os.homedir(), ".apx", "desktop.log");
+
+  if (debug) {
+    // ── Debug mode: start desktop normally, then tail -f the log ─────────
+    // Truncate log so we only see fresh output
+    try { fs.writeFileSync(logFile, `--- APX Desktop debug started ${new Date().toISOString()} ---\n`); } catch {}
+
+    const logFd = fs.openSync(logFile, "a");
+    const child = spawn(cmd, argv, {
+      detached: false,
+      stdio: ["ignore", logFd, logFd],
+      env: { ...process.env, ELECTRON_ENABLE_LOGGING: "1" },
+    });
+    fs.closeSync(logFd);
+
+    if (child.pid) writePid(child.pid);
+
+    // Small pause so Electron writes its first lines before we tail
+    await new Promise(r => setTimeout(r, 600));
+
+    console.log(
+      `\n  ${fmt.cyan("◉")} ${fmt.bold("APX Desktop")} ${fmt.yellow("[DEBUG]")}` +
+      `  pid ${child.pid}  port ${daemonPort}` +
+      `\n  ${fmt.dim("Tailing:")} ${logFile}` +
+      `\n  ${fmt.dim("Press Ctrl+C to stop tailing (desktop keeps running).")}\n`
+    );
+
+    // Tail the log file live — read new bytes as they arrive
+    const logStream = fs.createReadStream(logFile, { encoding: "utf8", start: 0 });
+    logStream.pipe(process.stdout);
+
+    // After initial content, watch for new data
+    const watcher = fs.watch(logFile, () => {});
+    let pos = fs.statSync(logFile).size;
+    const interval = setInterval(() => {
+      const stat = fs.statSync(logFile);
+      if (stat.size > pos) {
+        const stream = fs.createReadStream(logFile, { start: pos, end: stat.size });
+        stream.on("data", (chunk) => {
+          const lines = chunk.toString();
+          // Filter Chromium noise
+          lines.split("\n").forEach(line => {
+            if (!/^\[[\d:]+\]/.test(line.trim())) process.stdout.write(line + (line ? "\n" : ""));
+          });
+        });
+        pos = stat.size;
+      }
+    }, 300);
+
+    child.on("exit", (code) => {
+      clearInterval(interval);
+      watcher.close();
+      console.log(`\n  ${code === 0 ? fmt.green("✓") : fmt.red("✗")} Desktop exited (code ${code})\n`);
+      clearPid();
+      process.exit(code || 0);
+    });
+
+    await new Promise((resolve) => {
+      process.on("SIGINT", () => {
+        clearInterval(interval);
+        watcher.close();
+        console.log(`\n  ${fmt.dim("Stopped tailing. Desktop is still running.")}\n`);
+        resolve();
+      });
+      process.on("SIGTERM", resolve);
+    });
+    return;
+  }
+
+  // ── Normal (detached) mode ────────────────────────────────────────────
+  // detached:true is REQUIRED for the autostart case — launchd kills the
+  // entire process group of a LaunchAgent when the "main" process (this
+  // wrapper) exits. detached:true gives the Electron child its own session
+  // (setsid), so it survives the wrapper's 1.5s exit. unref() below lets
+  // the wrapper's event loop end naturally.
+  const logFd = fs.openSync(logFile, "a");
+  const child = spawn(cmd, argv, {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: { ...process.env, ELECTRON_ENABLE_LOGGING: "1" },
+  });
+
+  // Give the process 1.5s to fail fast, then detach and let it run
+  await new Promise((res) => {
+    let exited = false;
+    child.on("exit", (code) => {
+      exited = true;
+      if (code !== 0) {
+        console.error(
+          `\n  ${fmt.red("✗")} Desktop exited with code ${code}\n` +
+          `  ${fmt.dim("Check log:")} ${logFile}\n` +
+          `  ${fmt.dim("Or run with:")} ${fmt.cyan("apx desktop start --debug")}\n`
+        );
+      }
+      res();
+    });
+    setTimeout(() => {
+      if (!exited) {
+        child.unref();
+        res();
+      }
+    }, 1500);
+  });
+
+  if (!child.exitCode && child.pid) writePid(child.pid);
+  else return;
+
+  // Read configured shortcut (if any) for display
+  let shortcutHint = "⌘G (macOS) / Ctrl+G (Win/Linux)";
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".apx", "config.json"), "utf8"));
+    const sc = cfg?.desktop?.shortcut || cfg?.overlay?.shortcut;
+    if (sc) shortcutHint = sc;
+  } catch {}
+
+  console.log(
+    `\n  ${fmt.green("●")} ${fmt.bold("APX Desktop")} started` +
+    `  ${fmt.dim("pid " + child.pid)}` +
+    `  ${fmt.dim("port " + daemonPort)}` +
+    `\n  ${fmt.dim("Shortcut:")} ${fmt.cyan(shortcutHint)}` +
+    `\n  ${fmt.dim("Debug:")}    ${fmt.gray("apx desktop start --debug")}` +
+    `\n  ${fmt.dim("Log:")}      ${fmt.gray(logFile)}\n`
+  );
+}
+
+export async function cmdDesktopStop(_args = {}) {
+  const pid = readPid();
+  if (!pidAlive(pid)) {
+    console.log(`\n  ${fmt.dim("Desktop is not running.")}\n`);
+    clearPid();
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    clearPid();
+    console.log(`\n  ${fmt.green("✓")} Desktop stopped ${fmt.dim("(pid " + pid + ")")}\n`);
+  } catch (e) {
+    console.error(`\n  ${fmt.red("✗")} Could not stop desktop: ${e.message}\n`);
+  }
+}
+
+export async function cmdDesktopStatus(_args = {}) {
+  const pid = readPid();
+  const alive = pidAlive(pid);
+
+  let daemonClients = 0;
+  try {
+    const s = await http.get("/desktop/status").catch(() => null);
+    daemonClients = s?.connected_clients ?? 0;
+  } catch {}
+
+  const icon  = alive ? fmt.green("●") : fmt.dim("○");
+  const state = alive ? fmt.green("running") : fmt.dim("stopped");
+  const autoIcon  = autostartIsOn() ? fmt.green("●") : fmt.dim("○");
+  const autoState = autostartIsOn() ? fmt.green("on") : fmt.dim("off");
+  console.log(
+    `\n  ${icon} ${fmt.bold("APX Desktop")}  ${state}` +
+    (pid ? `  ${fmt.dim("pid " + pid)}` : "") +
+    `\n  ${fmt.dim("daemon connections:")} ${daemonClients}` +
+    `\n  ${autoIcon} ${fmt.dim("autostart:")} ${autoState}\n`
+  );
+}
+
+// ── Autostart (opt-in: apx desktop install / uninstall) ───────────────────
+//
+// All the heavy lifting lives in core/desktop/autostart.js so the daemon's
+// /desktop/autostart endpoint and these CLI commands share a single
+// implementation. The functions below are just ANSI/UX wrappers around it.
+
+export async function cmdDesktopInstall(_args = {}) {
+  const r = autostartInstall();
+  if (!r.ok) {
+    console.error(`\n  ${fmt.red("✗")} ${r.error}\n`);
+    process.exit(1);
+  }
+  console.log(
+    `\n  ${fmt.green("✓")} ${fmt.bold("Autostart activado")}` +
+    (r.runs ? `\n  ${fmt.dim("runs:")}  ${r.runs}`  : "") +
+    (r.path ? `\n  ${fmt.dim("entry:")} ${r.path}` : "") +
+    `\n  ${fmt.dim("La ventana arrancará automáticamente en el próximo login.")}` +
+    `\n  ${fmt.dim("Para desactivar:")} ${fmt.cyan("apx desktop uninstall")}\n`
+  );
+}
+
+export async function cmdDesktopUninstall(_args = {}) {
+  const r = autostartUninstall();
+  if (!r.ok) {
+    console.error(`\n  ${fmt.red("✗")} ${r.error}\n`);
+    process.exit(1);
+  }
+  if (!r.removed) {
+    console.log(`\n  ${fmt.dim("Autostart no estaba activado.")}\n`);
+    return;
+  }
+  console.log(`\n  ${fmt.green("✓")} Autostart desactivado.\n  ${fmt.dim("Se eliminó:")} ${r.path}\n`);
+}
+

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

@@ -0,0 +1,92 @@
+import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
+
+/**
+ * Resolve exec target from CLI args.
+ * Default (no agent): super-agent daemon route.
+ * Explicit: -a / --agent <slug>
+ * Legacy: apx exec <slug> "prompt" when 2+ positionals
+ */
+export function resolveExecRequest(args) {
+  const agentFlag = args.flags?.agent ?? args.flags?.a;
+  let slug = null;
+  let promptParts;
+
+  if (agentFlag && agentFlag !== true) {
+    slug = String(agentFlag);
+    promptParts = args._;
+  } else if (args._.length >= 2) {
+    slug = args._[0];
+    promptParts = args._.slice(1);
+  } else {
+    promptParts = args._;
+  }
+
+  const useSuperAgent = !slug || slug === "super-agent";
+  return {
+    slug: useSuperAgent ? null : slug,
+    useSuperAgent,
+    promptParts,
+  };
+}
+
+async function readPromptFromStdin() {
+  const fs = await import("node:fs");
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  const buf = Buffer.alloc(65536);
+  try {
+    while (true) {
+      const n = fs.readSync(0, buf, 0, buf.length);
+      if (!n) break;
+      chunks.push(buf.slice(0, n).toString("utf8"));
+    }
+  } catch {
+    /* empty */
+  }
+  return chunks.join("").trim();
+}
+
+export async function cmdExec(args) {
+  const { slug, useSuperAgent, promptParts } = resolveExecRequest(args);
+  let prompt = promptParts.join(" ").trim();
+
+  if (!prompt || prompt === "-") {
+    prompt = await readPromptFromStdin();
+  }
+  if (!prompt) {
+    throw new Error(
+      'apx exec: prompt is empty. Usage: apx exec "prompt" | apx exec -a <agent> "prompt" | apx exec -- "prompt"'
+    );
+  }
+
+  const pid = await resolveProjectId(args?.flags?.project);
+  const body = {
+    prompt,
+    channel: "cli",
+    channelMeta: { cwd: process.cwd() },
+  };
+  if (args.flags.model && args.flags.model !== true) body.model = args.flags.model;
+  if (args.flags.temperature) body.temperature = parseFloat(args.flags.temperature);
+  if (args.flags["max-tokens"]) body.maxTokens = parseInt(args.flags["max-tokens"], 10);
+
+  if (useSuperAgent) {
+    const result = await http.post(`/projects/${pid}/super-agent/chat`, body);
+    process.stdout.write(result.text + "\n");
+    if (process.stderr.isTTY || args.flags.verbose) {
+      process.stderr.write(
+        `\n— ${result.name || "super-agent"} | model=${result.trace ? "tools" : "engine"} | in=${result.usage?.input_tokens || "?"} out=${result.usage?.output_tokens || "?"}${result.model ? ` | ${result.model}` : ""}\n`
+      );
+    }
+    return;
+  }
+
+  const result = await http.post(`/projects/${pid}/agents/${slug}/exec`, body);
+
+  process.stdout.write(result.text + "\n");
+  if (process.stderr.isTTY || args.flags.verbose) {
+    process.stderr.write(
+      `\n— ${result.engine} | in=${result.usage?.input_tokens || "?"} out=${result.usage?.output_tokens || "?"} | conv=${result.conversation.id}\n`
+    );
+  }
+}