@agentprojectcontext/apx 1.36.0 → 1.37.0

package/README.md

@@ -1,8 +1,30 @@
 <p align="center">
-  <img src="assets/hero.png" alt="APX — Local Runtime for AI Agents" width="600">
+  <img src="assets/banner.svg" alt="APX — Agent Project eXecutable" width="820">
 </p>
 
-> The reference implementation of the [APC protocol](https://github.com/agentprojectcontext/agentprojectcontext).
+<p align="center">
+  <b>APX</b> &mdash; <b>A</b>gent <b>P</b>roject e<b>X</b>ecutable.<br>
+  A local runtime, CLI and web admin for AI agents, built on the
+  <a href="https://github.com/agentprojectcontext/agentprojectcontext">APC protocol</a>.
+</p>
+
+<p align="center">
+  <a href="https://agentprojectcontext.github.io/apx/"><img src="https://img.shields.io/badge/Website-agentprojectcontext.github.io-3fb950?style=flat-square&logo=googlechrome&logoColor=white" alt="Website"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-3fb950?style=flat-square" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/Node.js-20%2B-3fb950?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 20+">
+  <a href="https://github.com/agentprojectcontext/agentprojectcontext"><img src="https://img.shields.io/badge/Protocol-APC-3fb950?style=flat-square" alt="APC protocol"></a>
+</p>
+
+<p align="center">
+  <b><a href="https://agentprojectcontext.github.io/apx/">🌐 Visit the website</a></b> &nbsp;&middot;&nbsp;
+  <a href="#quick-start">Quick start</a> &middot;
+  <a href="#examples">Examples</a> &middot;
+  <a href="#web-admin">Web admin</a> &middot;
+  <a href="#use-cases">Use cases</a> &middot;
+  <a href="https://github.com/agentprojectcontext/agentprojectcontext">APC spec</a>
+</p>
+
+> APX is the reference implementation of the [APC protocol](https://github.com/agentprojectcontext/agentprojectcontext).
 > APX is to APC what a language SDK is to a protocol spec.
 
 ## What APX is
@@ -11,6 +33,7 @@ APX is a daemon + CLI that brings the APC convention to life:
 
 - **Daemon** — a local HTTP server that manages projects, agents, sessions, and message logs
 - **CLI** (`apx`) — commands for running agents, reading memory, tailing messages, managing sessions
+- **Web admin** — a local web UI served by the daemon to browse projects, agents, sessions, and MCPs from the browser
 - **Runtimes** — bridges to Claude Code, Codex, OpenCode, Aider
 - **Engines** — direct LLM calls via Anthropic, OpenAI, Gemini, Ollama, or a mock
 - **Plugins** — Telegram bot integration out of the box
@@ -21,9 +44,13 @@ APX is opinionated about storage: the filesystem is the source of truth. Project
 ## Quick start
 
 ```bash
+# 1 · Install
 npm install -g apx
 
-# In any directory with an AGENTS.md
+# 2 · Set up — interactive wizard (provider → model → channels → daemon)
+apx setup
+
+# In any directory with an AGENTS.md, register the project
 apx init
 
 # Spawn an agent with a full external runtime
@@ -36,6 +63,27 @@ apx exec sofia "What is my role in this project?"
 apx messages tail
 ```
 
+## Examples
+
+Real commands — copy one, point it at an agent like `sofia`, and APX routes it to the right
+runtime. The session and memory land in `.apc/`.
+
+| What | Command |
+|------|---------|
+| Register a project | `apx init` |
+| Spawn an agent (full runtime) | `apx run sofia --runtime claude-code "Review the open PRs and summarize them"` |
+| Ask a quick question (one-shot) | `apx exec sofia "What is my role in this project?"` |
+| Read an agent's memory | `apx memory sofia` |
+| Switch runtime, same context | `apx run sofia --runtime codex "Add tests for the parser"` |
+| Watch what's happening | `apx messages tail` |
+
+## Use cases
+
+- **Review PRs across any runtime** — point an agent at your repo; APX routes to Claude Code and falls back to Codex or OpenCode if one isn't installed. The session and its summary land in `.apc/`.
+- **Operate your agents from Telegram** — talk to project agents from your phone. Identity roles gate who can do what, and every message is logged per channel for a full audit trail.
+- **Memory that lives in your repo** — curated, per-agent memory is plain markdown, committed and reviewable alongside your code. No vendor database, no hidden state, no lock-in.
+- **Run the same prompt across engines** — send one prompt through Anthropic, OpenAI, Gemini or a local Ollama model with `apx exec`, configured per project or globally.
+
 ## Installation
 
 ```bash
@@ -44,6 +92,25 @@ npm install -g apx
 
 Requires Node.js 20+. The daemon starts automatically on first `apx` call.
 
+## Web admin
+
+APX ships a local **web admin** — the same runtime, in your browser. The daemon serves a
+single-page app so you can browse and manage everything the CLI does without leaving the UI:
+
+- **Projects & agents** — see registered projects, open agents, edit roles, models, and skills
+- **Sessions & messages** — read past sessions and tail live activity across every channel
+- **MCPs, engines & channels** — review MCP servers, configure engines, and manage Telegram/desktop
+
+It runs entirely on your machine. Start the daemon (any `apx` call does this) and open:
+
+```bash
+apx            # ensures the daemon is up
+open http://localhost:7430   # macOS — or just visit it in any browser
+```
+
+The web admin is served from `src/interfaces/web/dist` at the daemon port (`7430` by default,
+override with `APX_PORT`). Nothing is sent anywhere — it talks to the local daemon only.
+
 ## Project layout
 
 Project context — committed to the repository:

package/package.json

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

package/src/host/daemon/api/agents.js

@@ -245,12 +245,18 @@ export function register(app, { projects, project }) {
   app.get("/projects/:pid/agents/:slug/memory", (req, res) => {
     const p = project(req, res);
     if (!p) return;
+    // Validate the agent exists — otherwise an unknown slug returned 200 with an
+    // empty body, masking typos (QA BUG-API-1).
+    if (!readAgents(p.path).some((a) => a.slug === req.params.slug))
+      return res.status(404).json({ error: "agent not found" });
     res.json({ body: readAgentMemory(p, req.params.slug) });
   });
 
   app.put("/projects/:pid/agents/:slug/memory", (req, res) => {
     const p = project(req, res);
     if (!p) return;
+    if (!readAgents(p.path).some((a) => a.slug === req.params.slug))
+      return res.status(404).json({ error: "agent not found" });
     const { body } = req.body || {};
     if (typeof body !== "string")
       return res.status(400).json({ error: "body must be string" });

package/src/host/daemon/api/conversations.js

@@ -11,11 +11,18 @@ import { replyAsAgent } from "#core/agent/a2a/reply.js";
 import { nowIso } from "./shared.js";
 
 export function register(app, { project, config }) {
+  // The super-agent (default name "apx") is a pseudo-agent: it owns
+  // conversations per project but is NOT listed in AGENTS.md. Resolve its slug
+  // so `apx conversations list` (which defaults to the super-agent) works
+  // instead of 404-ing on the AGENTS.md check.
+  const superAgentSlug = () => config?.super_agent?.name || "apx";
+  const agentResolvable = (p, slug) =>
+    slug === superAgentSlug() || readAgents(p.path).some((a) => a.slug === slug);
+
   app.get("/projects/:pid/agents/:slug/conversations", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const agents = readAgents(p.path);
-    if (!agents.find((a) => a.slug === req.params.slug))
+    if (!agentResolvable(p, req.params.slug))
       return res.status(404).json({ error: "agent not found" });
     res.json(listConversations(p.storagePath, req.params.slug));
   });

package/src/host/daemon/api/web.js

@@ -27,13 +27,29 @@ const API_PREFIXES = [
   "/super-agent", "/identity",
 ];
 
-function isApiPath(p) {
+export function isApiPath(p) {
   for (const prefix of API_PREFIXES) {
     if (p === prefix || p.startsWith(prefix + "/")) return true;
   }
   return false;
 }
 
+// Client-side routes the SPA actually knows how to render. Must mirror the
+// <Routes> registry in src/interfaces/web/src/App.tsx. Anything else still
+// gets the SPA shell (so React Router shows the styled 404 page) but with an
+// HTTP 404 status, so curl/crawlers/health-checks see the right code instead
+// of a misleading 200.
+const SPA_ROUTES = [
+  /^\/$/,
+  /^\/settings(\/.*)?$/,
+  /^\/m\/(voice|desktop|deck|code)(\/.*)?$/,
+  /^\/p\/[^/]+(\/.*)?$/,
+];
+
+export function isKnownSpaRoute(p) {
+  return SPA_ROUTES.some((re) => re.test(p));
+}
+
 export function register(app, { express, token }) {
   // /admin/web-token: localhost-only endpoint that returns the daemon token
   // so the same-origin admin panel can authenticate every subsequent call.
@@ -118,6 +134,9 @@ export function register(app, { express, token }) {
     if (req.method !== "GET") return next();
     if (isApiPath(req.path)) return next();
     if (path.extname(req.path)) return next(); // let static handle 404 of /foo.png
+    // Always serve the shell so the SPA can render, but set 404 for routes the
+    // app doesn't recognize so the HTTP status matches what the user sees.
+    res.status(isKnownSpaRoute(req.path) ? 200 : 404);
     res.sendFile(path.join(WEB_DIST, "index.html"));
   });
 }

package/src/host/daemon/desktop-ws.js

@@ -10,6 +10,37 @@ export function setDesktopMessageHandler(fn) {
   _messageHandler = fn;
 }
 
+// --- WS upgrade auth helpers (shared by the daemon upgrade handler + tests) ---
+//
+// The desktop WS channel must authenticate the same way the HTTP /desktop/*
+// routes do: a bearer token (master or paired client) carried on the upgrade
+// request. The legitimate desktop window sends `Authorization: Bearer <token>`
+// (src/interfaces/desktop/main.js); browser clients can pass `?token=`. Without
+// this the daemon (which binds 0.0.0.0 by default) would let any LAN client open
+// the channel and drive the super-agent. See QA BUG-WS-AUTH.
+
+/** Path-gate: is this upgrade for the desktop (or legacy overlay) WS channel? */
+export function isDesktopUpgradePath(url) {
+  let pathname = url || "";
+  try { pathname = new URL(url, "http://localhost").pathname; } catch { /* keep raw */ }
+  return pathname === "/desktop/ws" || pathname === "/overlay/ws";
+}
+
+/** Extract the bearer token from the upgrade request (header first, ?token= fallback). */
+export function extractWsToken(req) {
+  const auth = (req && req.headers && req.headers["authorization"]) || "";
+  if (auth.startsWith("Bearer ")) return auth.slice(7);
+  try {
+    return new URL((req && req.url) || "", "http://localhost").searchParams.get("token") || "";
+  } catch { return ""; }
+}
+
+/** True iff the upgrade request carries a token the store recognizes. */
+export function isDesktopUpgradeAuthorized(req, tokenStore) {
+  if (!tokenStore || typeof tokenStore.has !== "function") return false;
+  return tokenStore.has(extractWsToken(req));
+}
+
 export function registerDesktopClient(ws) {
   _clients.add(ws);
   ws.on("close", () => _clients.delete(ws));

package/src/host/daemon/index.js

@@ -22,7 +22,7 @@ import { RoutineScheduler } from "./routines-scheduler.js";
 import { buildApi } from "./api.js";
 import { createTokenStore } from "./token-store.js";
 import { triggerWakeup } from "./wakeup.js";
-import { registerDesktopClient } from "./desktop-ws.js";
+import { registerDesktopClient, isDesktopUpgradePath, isDesktopUpgradeAuthorized } from "./desktop-ws.js";
 import { log as logToUnified } from "#core/logging.js";
 import { initMemory, stopMemory } from "#core/memory/index.js";
 
@@ -247,7 +247,17 @@ async function main() {
   // Attach WebSocket upgrade for the desktop channel on /desktop/ws
   // (legacy /overlay/ws still accepted for one release).
   server.on("upgrade", async (req, socket, head) => {
-    if (req.url !== "/desktop/ws" && req.url !== "/overlay/ws") { socket.destroy(); return; }
+    if (!isDesktopUpgradePath(req.url)) { socket.destroy(); return; }
+    // Auth: the WS upgrade must carry a valid token (master or paired client),
+    // matching the HTTP /desktop/* routes. Without this, any client that can
+    // reach the daemon (host binds 0.0.0.0 → the LAN) could open the desktop
+    // channel and drive the super-agent (permission_mode "total"). The
+    // legitimate desktop window already sends the bearer token. See QA BUG-WS-AUTH.
+    if (!isDesktopUpgradeAuthorized(req, tokenStore)) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      socket.destroy();
+      return;
+    }
     // Lazy-import ws to avoid hard dep on startup
     let WebSocketServer;
     try { ({ WebSocketServer } = await import("ws")); } catch {

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

@@ -5,6 +5,7 @@ import { apcAgentFile } from "#core/apc/paths.js";
 import { writeAgentFile, writeVaultAgentFile, removeVaultAgent, restoreVaultAgent, addImportedAgent, ensureAgentDir } from "#core/apc/scaffold.js";
 import { ensureAgentRuntimeDir, agentMemoryPath } from "#core/agent/memory.js";
 import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
 
 // ── ANSI ──────────────────────────────────────────────────────────────────────
 const c = { reset:"\x1b[0m", bold:"\x1b[1m", dim:"\x1b[2m", cyan:"\x1b[36m", green:"\x1b[32m", yellow:"\x1b[33m", gray:"\x1b[90m" };
@@ -100,6 +101,25 @@ export function cmdAgentGet(args) {
   console.log();
 }
 
+export async function cmdAgentRemove(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx agent remove: missing <slug> — usage: apx agent remove <slug>");
+  // Resolve locally first so we can give a clear message + suggestions instead
+  // of a bare 404 when the slug is wrong.
+  const root = findApfRoot();
+  if (root) {
+    const local = readAgents(root).find((a) => a.slug === slug);
+    if (!local) {
+      const inVault = readVaultAgents().find((v) => v.slug === slug);
+      if (inVault) throw new Error(`agent "${slug}" is in the vault but not in this project — nothing to remove here (use \`apx agent vault rm ${slug}\` to delete the template)`);
+      throw new Error(`agent "${slug}" not found in this project — run \`apx agent list\` to see the agents you can remove`);
+    }
+  }
+  const pid = await resolveProjectId(args?.flags?.project);
+  await http.delete(`/projects/${pid}/agents/${slug}`);
+  console.log(`${tag("removed")}  ${bold(slug)}  ${gray("(agent file + runtime memory deleted)")}`);
+}
+
 // ── Vault commands ────────────────────────────────────────────────────────────
 
 export function cmdAgentVaultList(args = { flags: {} }) {

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

@@ -1,6 +1,13 @@
 import readline from "node:readline";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
+import { readConfig } from "#core/config/index.js";
+
+// The super-agent (default name "apx") is the default conversational agent, so
+// `apx conversations list` (no slug) targets it — no need to spell it out.
+function superAgentSlug() {
+  try { return readConfig()?.super_agent?.name || "apx"; } catch { return "apx"; }
+}
 
 export async function cmdChat(args) {
   const slug = args._[0];
@@ -51,12 +58,12 @@ export async function cmdChat(args) {
 }
 
 export async function cmdConversationsList(args) {
-  const slug = args._[0];
-  if (!slug) throw new Error("apx conversations list: missing <agent-slug>");
+  // No slug → the super-agent (default conversational agent).
+  const slug = args._[0] || superAgentSlug();
   const pid = await resolveProjectId(args?.flags?.project);
   const rows = await http.get(`/projects/${pid}/agents/${slug}/conversations`);
   if (rows.length === 0) {
-    console.log("(no conversations)");
+    console.log(`(no conversations for ${slug})`);
     return;
   }
   console.log("ID".padEnd(16) + " ENGINE".padEnd(35) + " TURNS  STATUS");
@@ -72,9 +79,11 @@ export async function cmdConversationsList(args) {
 }
 
 export async function cmdConversationsGet(args) {
-  const slug = args._[0];
-  const id = args._[1];
-  if (!slug || !id) throw new Error("apx conversations get: usage: apx conversations get <agent> <id>");
+  // Two forms: `get <agent> <id>` or `get <id>` (→ super-agent).
+  let slug, id;
+  if (args._.length >= 2) { slug = args._[0]; id = args._[1]; }
+  else { slug = superAgentSlug(); id = args._[0]; }
+  if (!id) throw new Error("apx conversations get: usage: apx conversations get [<agent>] <id>");
   const pid = await resolveProjectId(args?.flags?.project);
   const conv = await http.get(`/projects/${pid}/agents/${slug}/conversations/${id}`);
   process.stdout.write(`# Conversation ${id} (${slug})\n`);

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

@@ -46,8 +46,27 @@ export async function cmdIdentity(args) {
     if (args.flags.personality && args.flags.personality !== true) fields.personality = args.flags.personality;
     if (args.flags.language && args.flags.language !== true) fields.language = args.flags.language;
 
+    // Positional form documented in help: `apx identity set <key> <value>`.
+    const KEY_TO_FIELD = {
+      name: "agent_name", owner: "owner_name", context: "owner_context",
+      personality: "personality", language: "language",
+      agent_name: "agent_name", owner_name: "owner_name", owner_context: "owner_context",
+    };
+    const pKey = args._[1];
+    const pVal = args._.slice(2).join(" ");
+    if (pKey && pVal) {
+      const field = KEY_TO_FIELD[pKey];
+      if (!field) {
+        console.error(`unknown identity key "${pKey}". Known: name, owner, context, personality, language`);
+        process.exitCode = 2;
+        return;
+      }
+      fields[field] = pVal;
+    }
+
     if (Object.keys(fields).length === 0) {
-      console.log("Usage: apx identity set --name <name> --owner <name> --context <text> --personality <text> --language <lang>");
+      console.log("Usage: apx identity set <key> <value>   (keys: name, owner, context, personality, language)");
+      console.log("   or: apx identity set --name <name> --owner <name> --context <text> --personality <text> --language <lang>");
       return;
     }
 

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

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { getLatestVersion } from "#core/update-check.js";
+import { apxBanner } from "../branding.js";
 
 const PACKAGE_NAME = "@agentprojectcontext/apx";
 
@@ -58,6 +59,7 @@ function daemonRunning() {
 export async function cmdUpdate(args, currentVersion) {
   const force = args.flags.force || args.flags.yes || args.flags.y;
 
+  apxBanner(currentVersion, "update");
   console.log("Checking for updates...");
   const latest = await getLatestVersion();
 

package/src/interfaces/cli/index.js

@@ -16,6 +16,7 @@ import {
   cmdAgentAdd,
   cmdAgentList,
   cmdAgentGet,
+  cmdAgentRemove,
   cmdAgentImport,
   cmdAgentVaultList,
   cmdAgentVaultAdd,
@@ -307,6 +308,7 @@ const HELP_TOPICS = new Map(Object.entries({
       ["add <slug>", "Create a project-local agent."],
       ["list | ls", "List project agents."],
       ["get | show <slug>", "Print one agent definition."],
+      ["remove | rm <slug>", "Delete a project agent (file + runtime memory)."],
       ["import <slug>", "Import an agent template from ~/.apx/agents."],
       ["vault list | ls", "List vault templates (bundled defaults + your overrides)."],
       ["vault add <slug>", "Create a new vault template in the user layer (~/.apx/agents/)."],
@@ -341,6 +343,12 @@ const HELP_TOPICS = new Map(Object.entries({
     usage: ["apx agent get <slug>", "apx agent show <slug>"],
     examples: ["apx agent get reviewer"],
   }),
+  "agent remove": topic({
+    title: "apx agent remove",
+    summary: "Delete a project agent (its .apc file + runtime memory).",
+    usage: ["apx agent remove <slug>", "apx agent rm <slug>"],
+    examples: ["apx agent remove reviewer"],
+  }),
   "agent import": topic({
     title: "apx agent import",
     summary: "Import a reusable agent template from the APX vault into the current project.",
@@ -1968,6 +1976,7 @@ function buildHelp(version) {
     hCmd("apx agent add <slug>",       36, "--role R  --model M  --skills a,b  --language es-AR  --description D"),
     hCmd("apx agent list",             36, ""),
     hCmd("apx agent get <slug>",       36, ""),
+    hCmd("apx agent remove <slug>",    36, "delete a project agent (file + runtime memory)"),
     hCmd("apx agent import",           36, ""),
     hCmd("apx agent vault list",       36, ""),
     hCmd("apx agent vault add",        36, ""),
@@ -2252,6 +2261,10 @@ if (helpRequest?.topic) {
 }
 
 if (argv[0] === "--version" || argv[0] === "-v") {
+  // Big wordmark to stderr (branding), bare version to stdout so
+  // `apx --version` stays parseable in scripts. apxBanner self-suppresses
+  // under APX_QUIET / APX_NO_BANNER.
+  apxBanner(VERSION, "version");
   console.log(VERSION);
   process.exit(0);
 }
@@ -2302,6 +2315,7 @@ async function dispatch(cmd, rest) {
         if (sub === "add") await cmdAgentAdd(a);
         else if (sub === "list" || sub === "ls") cmdAgentList();
         else if (sub === "get" || sub === "show") cmdAgentGet(a);
+        else if (sub === "remove" || sub === "rm" || sub === "delete") await cmdAgentRemove(a);
         else if (sub === "import") await cmdAgentImport(a);
         else if (sub === "vault") {
           const vsub = a._[0];