@agentprojectcontext/apx 1.80.2 → 1.89.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.80.2",
+  "version": "1.89.1",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -13,10 +13,10 @@
     "#interfaces/*": "./src/interfaces/*"
   },
   "bin": {
-    "apx": "./src/interfaces/cli/index.js",
-    "apx-daemon": "./src/host/daemon/index.js",
-    "apx-mcp": "./src/interfaces/mcp-server/index.js",
-    "apx-acp": "./src/interfaces/acp/index.js"
+    "apx": "src/interfaces/cli/index.js",
+    "apx-daemon": "src/host/daemon/index.js",
+    "apx-mcp": "src/interfaces/mcp-server/index.js",
+    "apx-acp": "src/interfaces/acp/index.js"
   },
   "files": [
     "src/",
@@ -34,13 +34,14 @@
   "scripts": {
     "start": "node src/host/daemon/index.js",
     "smoke": "node src/host/daemon/smoke.js",
-    "test": "node --test --test-reporter=spec tests/*.test.js",
+    "test": "node scripts/test.js",
     "test:ci": "node scripts/test-ci.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "lint:web": "node scripts/lint-web.js",
     "typecheck:tui": "node scripts/typecheck-tui.js",
     "build:web": "node scripts/build-web.js",
-    "preflight": "npm run lint && npm run test:ci && node scripts/build-web.js && (cd src/interfaces/web && npx --no-install tsc --noEmit) && npm run typecheck:tui",
+    "preflight": "npm run lint && npm run lint:web && npm run test:ci && node scripts/build-web.js && (cd src/interfaces/web && npx --no-install tsc --noEmit) && npm run typecheck:tui",
     "upgrade": "pnpm install && pnpm add -g .",
     "prepare": "node scripts/install-githooks.js && node scripts/sync-apc-skill.js",
     "prepack": "node scripts/sync-apc-skill.js && node scripts/build-web.js",
@@ -104,7 +105,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/agentprojectcontext/apx.git"
+    "url": "git+https://github.com/agentprojectcontext/apx.git"
   },
   "homepage": "https://github.com/agentprojectcontext/apx"
 }

package/skills/apc-context/SKILL.md

@@ -45,7 +45,7 @@ Classify content:
 | Agent definitions: name, model, description | Put in `.apc/agents/<name>.md` and/or `AGENTS.md` |
 | Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
 | Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
-| Durable safe facts useful to all contributors | Add to `.apc/agents/<name>/memory.md` only after curation |
+| Durable safe facts useful to all contributors | Add to `.apc/memory.md` only after curation |
 | MCP expectations without secrets | Add to `.apc/mcps.json` |
 | Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
 | Secrets, tokens, credentials, private headers | Do not store in repository |
@@ -69,7 +69,7 @@ AGENTS.md                        ← root project contract
   project.json                   ← project metadata
   .gitignore                     ← safety guard
   agents/<name>.md               ← agent definition
-  agents/<name>/memory.md        ← optional curated project memory
+  memory.md                      ← optional curated project memory (committed)
   skills/<name>.md               ← reusable project instructions
   mcps.json                      ← MCP hints without secrets
 ```
@@ -77,6 +77,7 @@ AGENTS.md                        ← root project contract
 Do not store:
 
 ```text
+.apc/agents/<name>/memory.md     ← agent memory is runtime state; see below
 .apc/agents/<name>/sessions/
 .apc/sessions/
 .apc/conversations/
@@ -92,7 +93,8 @@ Do not store:
 | Data | Visibility | Commit? |
 |---|---|---|
 | Agent definitions, skills, project rules | `stable` / `project` | Yes |
-| Curated safe `memory.md` | `project` | Yes, if team-safe |
+| Curated safe `.apc/memory.md` | `project` | Yes, if team-safe |
+| A single agent's `memory.md` | `local` | No; runtime-owned (`~/.apx/projects/<apx_id>/agents/<slug>/`) |
 | MCP hints without secrets | `project` | Yes |
 | Sessions, conversations, messages | `local` | No; runtime-owned |
 | Secrets, tokens, `*.secret.json`, `*.env` | `private` | Never |
@@ -102,7 +104,7 @@ Do not store:
 
 1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
 2. Read agent definitions from `.apc/agents/<name>.md` when present.
-3. Read curated project memory from `.apc/agents/<name>/memory.md` when present.
+3. Read curated project memory from `.apc/memory.md` when present. An individual agent's own memory is runtime state and lives at `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` — never under `.apc/`.
 4. Write only durable, safe, curated facts to APC memory.
 5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
 6. Keep secrets out of APC and out of git.
@@ -110,17 +112,22 @@ Do not store:
 
 ## Normalization
 
-If agent formats are broken or use legacy fields (role, skills in YAML), offer to normalize:
+`role`, `model`, `language`, `description`, `skills` and `tools` in YAML frontmatter
+are the canonical shape — this is exactly what `apx agent add` writes. Do NOT strip
+them.
 
 ```yaml
 ---
 name: agent-name
+role: what this agent is for
 model: inherit
 description: Semantic activation trigger
+skills: skill-a, skill-b
 ---
 ```
 
-Identify and fix inconsistencies in `model` (use technical IDs or `inherit`) and ensure `description` is present for semantic activation.
+Only fix genuine breakage: frontmatter that does not parse, a `model` that is neither
+a technical ID nor `inherit`, or a missing `description` (semantic activation needs it).
 
 ## Sessions
 
@@ -136,7 +143,7 @@ OpenCode runtime storage
 ```
 
 At task end, provide the user a concise result. If project memory should be updated, write a short
-sanitized fact to `.apc/agents/<name>/memory.md` only when useful and safe.
+sanitized fact to `.apc/memory.md` only when useful and safe.
 
 ## APX
 

package/skills/apx/SKILL.md

@@ -14,8 +14,9 @@ This is the **engine-side** skill: a slim reference for runtimes invoked by APX.
 
 ## When you (as an engine) interact with APX
 
-- You were spawned by `apx run` — your CWD is a project and APX is reachable on `127.0.0.1:7430`.
+- You were spawned by `apx run`, or the user launched you by hand inside an APX project — either way APX is reachable on `127.0.0.1:7430`.
 - The user asks you to call APX from inside your session ("send a telegram via apx", "list apx sessions").
+- The user asks you to reach an APX agent — "hablá con Roby", "preguntale a <agente>", "que <agente> me avise cuando termines" — see **Talking to an APX agent (a2a relay)** below.
 - 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. For anything MCP-related, use the [[apx-mcp]] skill — it's the MCP entry point for agents.
@@ -38,7 +39,10 @@ apx <command> --help
 ```bash
 # One-shot super-agent call
 apx exec "prompt"               # default 'cli' channel
-apx exec --code "prompt"        # 'code' channel: coding system prompt + git/code tools
+apx exec --code "prompt"        # 'code' channel: coding prompt + git/code tools.
+                                # Runs in a persistent code session (visible at
+                                # /m/code); the session id is printed on stderr.
+apx exec --code --session <id> "…"   # continue that session instead of a new one
 apx exec --channel <name> "…"   # explicit channel (cli, code, api, …)
 
 # Project + daemon
@@ -64,6 +68,62 @@ apx acp                         # Agent Client Protocol server on stdio (Zed, Je
 
 ---
 
+## Talking to an APX agent (a2a relay)
+
+When the user wants to reach an APX agent — "hablá con Roby", "preguntale a
+<agente>", "que <agente> me avise cuando termines" — you talk to the agent on the
+**agent-to-agent (a2a) channel**, not to the user. You send, the agent runs and
+returns its reply on stdout; if you identified your session, the agent (or the
+user through it) can later answer back *into this session*.
+
+Send with `apx send` on the a2a channel:
+
+```bash
+apx send <you> <agent> "<message>  engine=claude session=<your-session-id>" --deliver --project <name>
+```
+
+- `<you>` — your sender identity; for a coding CLI use the engine name (`claude`,
+  `codex`, …). It does NOT need to be a registered agent.
+- `<agent>` — recipient slug, the super-agent's configured name, or a technical
+  super-agent alias (`default`, `apx`, `super-agent`). `--project` is optional:
+  named project agents resolve by recipient; the super-agent follows the sender's
+  project context. Pass it when either side exists in several projects.
+- `--deliver` — runs the recipient now and returns its reply on stdout. The agent
+  decides whether/how to tell the user on its own channel (respecting quiet-hours).
+- **The a2a thread keeps history** — each `--deliver` sees the earlier turns of
+  this pair, so a back-and-forth is a real conversation (you don't have to restate
+  context every message). It shows in the web inbox as a "you · agent" group chat.
+- Do NOT use `apx exec` for this (it posts on the USER channel — the agent sees it
+  as if the user typed it), and do NOT `apx telegram send` the user directly (that
+  bypasses the agent and the relay never closes).
+- The super-agent is a first-class a2a target. Address it by its configured name
+  (for example `roby`) just like any other agent. APX runs the real super-agent
+  identity, memory, permission guard and tool loop; it decides whether an agent's
+  escalation should reach the owner. Use `apx exec` only for an owner-authored
+  turn, never to impersonate one from A2A.
+
+**Identify your session so the answer can return.** Put `engine=claude
+session=<id>` in the message body. Get your id from your own transcript path (most
+reliable), or `apx sessions list --engine claude --dir "$PWD"`.
+
+> ⚠️ With several Claude sessions open in the same repo, "most recent" is NOT
+> reliably you — prefer your transcript path. If you can't be sure, say so in the
+> message instead of guessing; the agent then starts fresh rather than resuming
+> the wrong (possibly stale) session.
+
+The agent answers back by resuming your session headless — **it** runs this, not
+you:
+
+```bash
+apx session resume <session-id> --continue --msg "<the reply>"
+```
+
+That injects one message into your transcript with full context and captures your
+response on stdout. (Resume-with-`--msg` is Claude-only for now.) The agent side
+of this convention lives in the **apx-runtime** skill.
+
+---
+
 ## APC_RESULT contract
 
 When APX captures a structured value from your run, end with:

package/skills/apx-mcp/SKILL.md

@@ -21,20 +21,20 @@ Resolution priority when a name appears in more than one: **runtime > shared > g
 
 ```bash
 # List (all scopes, this is the default)
-apx mcp list --project iacrmar
-apx mcp list --scope runtime --project iacrmar
-apx mcp list --scope shared  --project iacrmar
+apx mcp list --project acme
+apx mcp list --scope runtime --project acme
+apx mcp list --scope shared  --project acme
 apx mcp list --scope global
 
 # Inspect sources and conflicts
-apx mcp check --project iacrmar
+apx mcp check --project acme
 
 # Add — shared (commit to repo)
-apx mcp add filesystem --command npx --project iacrmar \
+apx mcp add filesystem --command npx --project acme \
   -- -y @modelcontextprotocol/server-filesystem .
 
 # Add — runtime (per-project, local, secrets safe)
-apx mcp add github --scope runtime --project iacrmar \
+apx mcp add github --scope runtime --project acme \
   --command npx --env GITHUB_TOKEN=ghp_xxx \
   -- -y @modelcontextprotocol/server-github
 
@@ -45,12 +45,12 @@ apx mcp add brave --scope global \
 
 # Remove (pass --scope when the MCP isn't in the default scope:
 # shared inside an APC project, else global)
-apx mcp remove filesystem --project iacrmar
-apx mcp remove github     --scope runtime --project iacrmar
+apx mcp remove filesystem --project acme
+apx mcp remove github     --scope runtime --project acme
 
 # Toggle (defaults to the scope that owns the MCP)
-apx mcp enable  filesystem --project iacrmar
-apx mcp disable filesystem --project iacrmar
+apx mcp enable  filesystem --project acme
+apx mcp disable filesystem --project acme
 
 # Call a tool through the daemon (useful for debugging)
 apx mcp run filesystem read_file '{"path":"README.md"}'
@@ -65,22 +65,49 @@ Decision tree:
 
 Default if none is obvious: `shared` when inside an APC project, `global` outside.
 
-## Common command shapes by transport
+## Command shapes by transport
+
+Two transports. `--command` = local process (stdio), `--url` = remote endpoint (http).
+There is no third option, and no flag outside this list — if a shape isn't here,
+run `apx help mcp add` instead of guessing.
 
 ```bash
-# stdio MCP (most common — npx, uvx, node, python)
+# stdio MCP — a local process (npx, uvx, node, python)
 apx mcp add <name> --command npx -- -y <package-or-flag-list>
 apx mcp add <name> --command uvx -- <python-cli-name>
 apx mcp add <name> --command python -- /abs/path/to/server.py
 
-# Env vars (one --env per var)
+# stdio env vars (one --env per var)
 apx mcp add <name> --command npx \
   --env GITHUB_TOKEN=ghp_xxx \
   --env GITHUB_OWNER=manuel \
   -- -y @modelcontextprotocol/server-github
+
+# http MCP — a remote streamable-HTTP endpoint. No command, no npx, no install.
+apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime
+
+# http with auth headers (repeatable; "Name: value" or Name=value both parse)
+apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime \
+  --header "Authorization: Bearer $TOKEN" \
+  --header "X-Workspace: acme"
+```
+
+Everything after `--` is forwarded verbatim as args to a stdio command. Quote carefully.
+`--env` and `--` args are stdio-only; `--header` is http-only — mixing them errors.
+
+Remote servers almost always carry a token, so they belong in `--scope runtime`
+(chmod 0600, never committed). Read the token from the environment rather than
+pasting it: `--header "Authorization: Bearer $TOKEN"`.
+
+## After adding: prove it works
+
+```bash
+apx mcp tools <name>     # spawns/connects and lists tools — this is the real check
+apx mcp logs <name>      # if the above is empty or errors: request/response log
 ```
 
-Anything after `--` is forwarded verbatim as args to the command. Quote carefully.
+`apx mcp add` only writes JSON — it never contacts the server. An MCP that "was
+added fine" but has no tools is a failed connection, not a successful install.
 
 ## Anti-examples
 
@@ -101,7 +128,7 @@ apx mcp remove github          # if github lives in runtime, this errors with a
 ## Debugging connection issues
 
 ```bash
-apx mcp check --project iacrmar             # what scopes APX sees + which files exist
+apx mcp check --project acme             # 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

package/src/core/agent/a2a/peers.js

@@ -0,0 +1,161 @@
+// Who an a2a message can be addressed to.
+//
+// `to` used to mean "an agent in AGENTS.md", and that alone is why a coding CLI
+// could talk INTO APX but never the other way round: `apx send claude opencode
+// "…"` died on `no agent "opencode"`. A PEER is the generalisation — a project
+// agent, the daemon super-agent, or an external runtime (opencode, codex,
+// claude-code, …). Same envelope, ledger and pair history; only reply execution
+// differs.
+//
+// Address syntax: <name>[:<thread>]
+//
+//   andy               an AGENTS.md agent (unchanged)
+//   opencode           the runtime, on its default thread with this sender
+//   opencode:review    a SECOND, independent thread with the same peer
+//
+// The `:thread` suffix stays part of the ledger slug, and the ledger keys
+// threads by the literal pair of names (see a2aPairId in stores/messages.js) —
+// so two threads with the same peer never share history. That is what lets two
+// IDE sessions talk to the same runtime without reading each other's mail, and
+// it needs no new store: the discriminator IS the address.
+//
+// The separator is `:` and not `#` because these names end up in a URL — the
+// web opens a thread at /super-agent/threads/a2a/<pairId>. A `#` is a fragment
+// delimiter: the browser cuts the address in half before the request leaves,
+// and every thread with a suffix 404s. `:` survives the trip (encoded or not),
+// which api/conversations.js already relies on for the `a2a:` slug itself.
+import { RUNTIME_IDS } from "#core/runtimes/index.js";
+import { resolveAgentName } from "#core/identity/self.js";
+import { SUPERAGENT_ACTOR_ID } from "#core/constants/actors.js";
+
+const SUPERAGENT_PEERS = new Set(["default", "superagent", "super_agent", "super-agent", "apx"]);
+
+/** Split "<name>:<thread>". A leading ":" is not a suffix — that is the name. */
+export function parsePeerAddress(address) {
+  const raw = String(address || "").trim();
+  const sep = raw.indexOf(":");
+  if (sep <= 0) return { address: raw, name: raw, thread: null };
+  return {
+    address: raw,
+    name: raw.slice(0, sep),
+    thread: raw.slice(sep + 1) || null,
+  };
+}
+
+export function isRuntimeName(name) {
+  return RUNTIME_IDS.includes(String(name || ""));
+}
+
+/** Find the real project agent claimed by an addressable name. */
+export function findAddressedAgent(name, agents = []) {
+  const raw = String(name || "");
+  if (!raw) return null;
+  const lower = raw.toLowerCase();
+  return (
+    agents.find((a) => a.slug === raw) ||
+    agents.find((a) => a.slug?.toLowerCase() === lower) ||
+    agents.find((a) => (a.name || a.fields?.Name || "").toLowerCase() === lower) ||
+    null
+  );
+}
+
+/**
+ * Whether a name addresses the daemon super-agent mode. The configured
+ * identity is an alias too; the stable ledger identity stays super_agent.
+ */
+export function isSuperAgentName(name, config = {}) {
+  const raw = String(name || "").trim().toLowerCase();
+  if (!raw) return false;
+  const configuredName = (resolveAgentName(config) || "").trim().toLowerCase();
+  return SUPERAGENT_PEERS.has(raw) || (configuredName && raw === configuredName);
+}
+
+/**
+ * Resolve an address to whoever will answer it. An agent wins over a runtime of
+ * the same name: a project that named an agent `codex` still owns that name.
+ * Returns null when nothing claims it, so the caller can 404 with the options.
+ */
+export function resolvePeer(address, agents = [], config = {}) {
+  const { address: full, name, thread } = parsePeerAddress(address);
+  if (!full) return null;
+
+  // A real project agent wins over every synthetic identity. This preserves a
+  // project that intentionally owns an agent named `apx`, `default`, or Roby.
+  const agent = findAddressedAgent(name, agents);
+
+  if (agent) return { kind: "agent", address: full, name: agent.slug, thread, agent };
+
+  if (isRuntimeName(name)) {
+    return { kind: "runtime", address: full, name, thread, runtime: name };
+  }
+
+  // Super-agent fallback: aliases and configured identity all reach the same
+  // full daemon-level mode, never a fabricated project-agent model call.
+  if (isSuperAgentName(name, config)) {
+    const displayName = resolveAgentName(config);
+    return {
+      kind: "super_agent",
+      address: full,
+      // ONE name for the super-agent on the ledger, whichever alias was typed.
+      // This used to answer to `default`, so `apx send magui default "…"` filed
+      // the exchange under a peer called "default" — a name no agent list, face
+      // resolver or reader can place, while the very same super-agent appears as
+      // `super_agent` everywhere else. Manu saw the result in his inbox: "Magui
+      // is talking to `default`, which does not exist". The aliases still all
+      // resolve; they just stop minting a second identity for the same agent.
+      name: SUPERAGENT_ACTOR_ID,
+      thread,
+      agent: {
+        slug: SUPERAGENT_ACTOR_ID,
+        name: displayName,
+        fields: {
+          Name: displayName,
+          Role: "Super-agent / Orchestrator",
+          Type: "orchestrator",
+          Description: "Always-on orchestrator and chief of staff",
+        },
+        synthetic: true,
+      },
+    };
+  }
+
+  return null;
+}
+
+/**
+ * The canonical address of a resolved peer — its real name, keeping any
+ * `:thread` suffix. What a caller should WRITE to the ledger instead of the
+ * string it was handed: `default`, `Roby`, `apx` and `roby` are one peer, and
+ * without this each spelling opened a thread of its own. The suffix stays, since
+ * it is the discriminator two threads with the same peer are keyed by.
+ */
+export function peerAddress(peer) {
+  if (!peer?.name) return "";
+  return peer.thread ? `${peer.name}:${peer.thread}` : peer.name;
+}
+
+/**
+ * The key naming the external session an a2a thread owns. Sorted, so both
+ * directions of the same exchange resolve to the SAME session — the thread is
+ * one conversation, not two. Runtimes that can only find their session again by
+ * name (opencode titles it) use this verbatim.
+ */
+export function a2aSessionKey(from, to) {
+  return `apx-a2a:${[String(from || ""), String(to || "")].sort().join("~")}`;
+}
+
+/**
+ * Runtimes that are never opened as a `--code` peer.
+ *
+ * Not a capability judgement — both can code perfectly well, and `apx run`
+ * still drives them that way. It is a wiring decision: these two are the CLIs
+ * the owner drives directly, so letting a message also start them on a working
+ * session means the same checkout has two writers and nobody can tell which one
+ * made a change. They answer as read-only peers; the work goes to opencode or
+ * to a `apx run`. A flat list beats a rule with conditions.
+ */
+export const NO_CODE_PEERS = Object.freeze(["claude-code", "codex"]);
+
+export function refusesCodeMode(peer) {
+  return peer?.kind === "runtime" && NO_CODE_PEERS.includes(peer.runtime);
+}