@agentprojectcontext/apx 1.33.0 → 1.34.0

package/package.json

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

package/skills/apc-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apc-context
-description: "Activate whenever the project has a .apc/ directory or AGENTS.md — read .apc/ before assuming anything about agents, memory, or structure. If .apc/migrate.md exists, open with a migration offer first; if the user declines, delete it. Triggers: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents'."
+description: "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again."
 homepage: https://github.com/agentprojectcontext/agentprojectcontext
 ---
 
@@ -66,13 +66,11 @@ After migration:
 ```text
 AGENTS.md                        ← root project contract
 .apc/
-  project.json                   ← project metadata (may carry an `apx` field)
-  config.json                    ← project-only config overrides (e.g. super_agent.model)
+  project.json                   ← project metadata
   .gitignore                     ← safety guard
   agents/<name>.md               ← agent definition
   agents/<name>/memory.md        ← optional curated project memory
   skills/<name>.md               ← reusable project instructions
-  commands/                      ← custom slash-commands (optional)
   mcps.json                      ← MCP hints without secrets
 ```
 
@@ -83,7 +81,6 @@ Do not store:
 .apc/sessions/
 .apc/conversations/
 .apc/messages/
-.apc/project.db
 .apc/cache/
 .apc/tmp/
 .apc/private/

package/skills/apx/SKILL.md

@@ -1,95 +1,83 @@
 ---
 name: apx
-description: "APX CLI umbrella — which sub-skill handles each operation (sessions, MCPs, routines, tasks, telegram, projects, agents, runtimes). Activate when the user mentions `apx`, the APX daemon, or wants to coordinate/run/delegate agents. Not for `.apc/` alone (use apc-context). Triggers: 'apx', 'apx run', 'apx daemon', 'coordinate agents', 'apx help'."
+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', 'pedile a codex/claude/opencode/gemini', 'que codex haga …', 'delegar a otro engine', 'ejecutar en codex/claude', 'run this in <runtime>'.
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
-# APX — Agent Project Context Runtime
+# APX — Agent Project Context Runtime (engine view)
 
-APX is a daemon (`127.0.0.1:7430`, auto-starts on first call) that turns external coding CLIs (Claude Code, Codex, OpenCode, Aider, …) and configurable agents into a unified orchestration surface.
+APX is a local daemon (`127.0.0.1:7430`, auto-starts on first call) that turns external coding CLIs (Claude Code, Codex, OpenCode, …) and configurable agents into a unified orchestration surface.
 
-It reads APC project context from `.apc/` (committed) but keeps runtime state outside the repo under `~/.apx/projects/<project-id>/`. The super-agent has a default workspace at `~/.apx/projects/default` for system-level work.
+This is the **engine-side** skill: a slim reference for runtimes invoked by APX. The full umbrella skill (with all sub-skills) lives in APX itself.
 
 ---
 
-## When to use APX (vs. spawning a subagent natively)
+## When you (as an engine) interact with APX
 
-If you can spawn a subagent natively in the IDE you're in (Claude Code, Cursor, …) — **do that**. No APX needed.
+- You were spawned by `apx run` — your CWD is a project and 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").
+- You're inside an `.apc/` project and want to consult APX-managed state.
 
-Use APX when:
-- The user explicitly asks for a specific external runtime ("run this in Codex", "delegate to OpenCode").
-- You need to run an agent in a runtime different from the one you're in.
-- You're orchestrating from outside any IDE (a script, Telegram bot, CI, routine).
+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.
 
 ---
 
-## Sub-skill index — open the one that matches the task
+## Verify before recommending
 
-| Topic | Sub-skill | When |
-|-------|-----------|------|
-| Delegate to an external coding CLI | **apx-runtime** | `apx run <agent> --runtime claude-code\|codex\|...` |
-| List / read / resume / summarise / continue sessions across engines | **apx-sessions** | `apx session resume`, `apx sessions list`, "import a codex session" |
-| Use a registered MCP tool | **apx-mcp** | `apx mcp run`, "call MCP filesystem", "the MCP is failing" |
-| Add / configure / use a project agent | **apx-agent** | "add an agent", "import from vault", per-agent model, agent memory |
-| Register / list / configure a project | **apx-project** | "register this project", `apx project list`, per-project config |
-| Per-project TODO list | **apx-task** | "add a task", "remind me to…", "what's pending" |
-| Scheduled / recurring agents | **apx-routine** | `apx routine add`, every-5m, cron-like jobs |
-| Telegram I/O | **apx-telegram** | configure bot, channels, send a message |
-| Voice channel (TTS, speech) — *optional* | **apx-voice** | only if voice is being set up |
-| Build a new MCP server — *internal/dev* | **apx-mcp-builder** | when developing a brand-new MCP from scratch |
-| Author a new APX skill — *internal/dev* | **apx-skill-builder** | when adding to APX itself |
+Do not invent subcommands. Confirm exact form with:
 
-> Sub-skills marked *internal/dev* are not pushed to IDE skill dirs by default. They live in the APX repo and are loaded by APX itself; install one to your IDE with `apx skills add <slug> --global` if you want it there.
-
----
-
-## Generic patterns (apply to every sub-skill)
-
-### Verify commands before recommending them
-
-Do not invent APX subcommands. Confirm exact CLI form with `apx --help` or `apx <command> --help` before telling another runtime to invoke APX. Avoid guessed aliases (e.g. `apx send-telegram` is *not* a thing — see apx-telegram).
-
-### `APC_RESULT` contract — structured return values
-
-When you want APX to capture a structured value from an agent (any runtime), instruct the agent to print on its last meaningful line:
-
-```
-APC_RESULT: <one-line value>
+```bash
+apx --help
+apx <command> --help
 ```
 
-APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, and CI.
+---
 
-### Tool permissions
+## Core commands you'll actually use
 
 ```bash
-apx permission show
-apx permission set automatico   # total | automatico | permiso
+# Project + daemon
+apx status                      # daemon health
+apx project list                # registered projects
+apx project current             # which project resolves from CWD
+
+# Sessions (cross-engine)
+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>"
+
+# Observe activity
+apx messages tail
+apx messages chat --channel <name> -n 20
 ```
 
-`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP, runtime, outbound, config, or filesystem mutation actions.
+---
 
-### Memory
+## APC_RESULT contract
 
-Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
+When APX captures a structured value from your run, end with:
 
-```bash
-apx memory <slug>                       # read agent's memory.md
-apx memory <slug> --append "<fact>"     # append a durable note
-apx memory <slug> --replace < file.md  # replace entire memory from stdin
 ```
-
-### Observe activity
-
-```bash
-apx messages tail                               # last 50 messages, all channels
-apx messages chat --channel telegram -n 20      # readable chat view
-apx messages tail --channel runtime --agent <slug> -n 20
+APC_RESULT: <one-line value>
 ```
 
+`extractApfResult()` parses that and stores it as the session's `result`. Use it for routines, CI, automation.
+
 ---
 
 ## Anti-patterns
 
-- Don't activate APX-sessions inside a request that's purely about `apx run` orchestration — use apx-runtime.
-- Don't activate apx-mcp-builder unless the user is actually authoring a new MCP server (it's a deep developer guide, not a usage guide).
-- Don't push state to `.apc/` that belongs in `~/.apx/projects/<id>/` (sessions, conversations, runtime logs).
+- Don't write raw transcripts, sessions, or secrets into `.apc/` — they belong in `~/.apx/projects/<id>/`.
+- Don't guess subcommands. If `apx --help` doesn't show it, it doesn't exist.
+- Don't activate this skill for pure `.apc/` reading — that's [[apc-context]].
+- For MCP details (scopes, secrets, add/remove), open [[apx-mcp]] instead of guessing flags here.

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

@@ -0,0 +1,48 @@
+// Agent-to-agent (A2A) one-shot reply: given a sender + recipient agent and a
+// message body, build the recipient's system prompt and call the engine. Pure
+// orchestration over core/agent + core/engines — no HTTP, no message log
+// writes (the caller decides whether/where to persist).
+import fs from "node:fs";
+import { callEngine } from "../../engines/index.js";
+import { apcAgentMemoryFile } from "../../apc/paths.js";
+
+/**
+ * Build the recipient's system prompt for an A2A reply.
+ * Includes Description, Role, Language, a persona line naming the sender,
+ * and the recipient's memory.md if present.
+ */
+export function buildA2AReplySystem({ projectPath, toAgent, fromAgent }) {
+  const tf = toAgent?.fields || {};
+  const parts = [];
+  if (tf.Description) parts.push(tf.Description);
+  if (tf.Role) parts.push(`Role: ${tf.Role}`);
+  if (tf.Language) parts.push(`Default language: ${tf.Language}`);
+  parts.push(
+    `You are ${toAgent.slug}. You just received a message from ${fromAgent.slug}. Reply concisely.`
+  );
+  if (projectPath && toAgent.slug) {
+    const memPath = apcAgentMemoryFile(projectPath, toAgent.slug);
+    if (fs.existsSync(memPath)) {
+      parts.push("## Memory\n" + fs.readFileSync(memPath, "utf8"));
+    }
+  }
+  return parts.join("\n\n");
+}
+
+/**
+ * Run one A2A turn: build system, call engine, return { text, usage }.
+ * Throws on engine failure — caller decides how to surface.
+ */
+export async function replyAsAgent({ projectPath, toAgent, fromAgent, body, config }) {
+  if (!toAgent?.fields?.Model) {
+    throw new Error(`agent ${toAgent?.slug || "?"} has no model`);
+  }
+  const system = buildA2AReplySystem({ projectPath, toAgent, fromAgent });
+  const result = await callEngine({
+    modelId: toAgent.fields.Model,
+    system,
+    messages: [{ role: "user", content: `From ${fromAgent.slug}:\n\n${body}` }],
+    config,
+  });
+  return { text: result.text, usage: result.usage };
+}

package/src/core/agent/build-agent-system.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readAgentMemory } from "./memory.js";
+import { apcProjectFile, apcSkillFile } from "../apc/paths.js";
 
 // Anti-ghost-response rules injected into every agent system prompt. The text
 // lives next to the agent prompts (src/core/agent/prompts/action-discipline.md)
@@ -19,7 +20,7 @@ function listField(value) {
 function projectName(project) {
   if (project?.name) return project.name;
   try {
-    const meta = JSON.parse(fs.readFileSync(path.join(project.path, ".apc", "project.json"), "utf8"));
+    const meta = JSON.parse(fs.readFileSync(apcProjectFile(project.path), "utf8"));
     return meta.name || path.basename(project.path);
   } catch {
     return path.basename(project?.path || "");
@@ -64,11 +65,11 @@ export function buildAgentSystem(project, agent, {
   const memory = readAgentMemory(project, agent.slug);
   if (memory) parts.push("## Memory\n" + memory);
 
-  const apxSkill = path.join(project.path, ".apc", "skills", "apx.md");
+  const apxSkill = apcSkillFile(project.path, "apx");
   if (fs.existsSync(apxSkill)) parts.push("## APX\n" + fs.readFileSync(apxSkill, "utf8"));
 
   for (const skill of agentSkills(agent)) {
-    const skillPath = path.join(project.path, ".apc", "skills", `${skill}.md`);
+    const skillPath = apcSkillFile(project.path, skill);
     if (fs.existsSync(skillPath)) parts.push(`## Skill: ${skill}\n` + fs.readFileSync(skillPath, "utf8"));
   }
 

package/src/core/agent/channels/voice-context.js

@@ -0,0 +1,98 @@
+// Channel-aware pre-processor for surfaces that drive the super-agent loop
+// from a voice/deck/desktop entrypoint.
+//
+// Each surface has different ergonomics: how long the reply can be, whether
+// the UI can render structured suggestion chips, what the default project
+// resolution should be. buildVoiceChannelContext() is the single place where
+// those decisions live. Callers (api/voice.js today; any future overlay or
+// device adapter tomorrow) pass the channel string + dynamic context and
+// receive the context note + system suffix to feed into the super-agent.
+//
+// Shape:
+//   contextNote   — prepended to the prompt (dynamic, per-request)
+//   systemSuffix  — concatenated onto the system prompt (per-surface rules)
+//   wantsSuggestions — whether the surface can render the trailing
+//                      `suggestions` JSON block (deck/desktop UI can; raw
+//                      Telegram cannot)
+//   channel       — resolved surface ("deck"/"desktop"/"telegram"/…)
+//   channelMeta   — surface metadata (e.g. `{ voice: true }` flags spoken mode)
+import { CHANNELS } from "../../constants/channels.js";
+
+// Balanced suggestions instruction. An earlier, more aggressive version
+// ("EJECUTA, no narres — LLAMÁ A LA TOOL") made Gemini call tools for
+// EVERYTHING, even "hola" → send_telegram("hola"). The rule below gates
+// tool use on a *clear* action request and explicitly tells the model to
+// just talk for chit-chat.
+export const SUGGESTIONS_INSTRUCTION = `
+
+# Cuándo usar tools
+SOLO llamá una tool cuando el usuario pide CLARAMENTE una acción
+concreta: "creá una tarea …", "mandá un telegram …", "listá …",
+"abrí …", "marcá como hecha …". En esos casos ejecutá la tool (no
+digas "lo voy a hacer" — hacelo) y después confirmá en una frase corta
+en castellano lo que YA hiciste.
+
+Si el mensaje es un saludo, una pregunta, o charla ("hola", "cómo
+andás", "qué podés hacer") NO llames ninguna tool: respondé en texto,
+breve, en castellano.
+
+Nunca llames la misma tool dos veces en el mismo turno.
+
+# Sugerencias (opcional)
+Al final, en su propia línea, podés agregar un bloque fenced
+\`suggestions\` con 2-3 próximos pasos. El usuario NO lo ve (la deck lo
+quita):
+\`\`\`suggestions
+[{"label":"Ver tareas","command":"deck.view:tasks"}]
+\`\`\`
+Si no hay próximos pasos útiles, omití el bloque.`;
+
+function buildLanguageDirective(language) {
+  return language === "es"
+    ? "IMPORTANT: Reply ALWAYS in Spanish (rioplatense/Argentina). The user speaks Spanish."
+    : `IMPORTANT: Reply in language "${language}".`;
+}
+
+function buildProjectHint(projectId) {
+  // Project resolution hint:
+  //   per-project mic (projectId set): use it imperatively, don't ask.
+  //   global deck mic (no projectId): default to project id=0 ("default")
+  //     for actions unless the user names a project out loud.
+  return projectId
+    ? `\nThe active project is id=${projectId}. For ANY task/note/list ` +
+      `action, pass project_id=${projectId} automatically. Do NOT ask the ` +
+      `user which project — only switch if they explicitly name another.`
+    : `\nThis is the GLOBAL mic (no project in focus). For task/note/list ` +
+      `actions, default to project_id=0 ("default") UNLESS the user names ` +
+      `a project out loud (e.g. "en evolution-registry…", "en el proyecto ` +
+      `apx…") — then resolve that project by name. Never ask "¿en qué ` +
+      `proyecto?"; pick the default and act.`;
+}
+
+export function buildVoiceChannelContext(channel, { projectId, language = "es" } = {}) {
+  const base = {
+    contextNote: "",
+    systemSuffix: "",
+    wantsSuggestions: false,
+    channel: "",
+    channelMeta: {},
+  };
+  const dynamicNote = `${buildLanguageDirective(language)}${buildProjectHint(projectId)}`;
+
+  // Channels are surfaces; "voice" is NOT a surface — it's the spoken MODE of
+  // the deck. All channel FORMATTING lives in channels/*.md + modes/voice.md
+  // (injected by buildSuperAgentSystem); contextNote here carries ONLY
+  // per-request dynamic bits (language + project).
+  switch (channel) {
+    case "voice":
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DECK, channelMeta: { voice: true } };
+    case "deck":
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DECK, channelMeta: {} };
+    case "desktop":
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DESKTOP, channelMeta: { voice: true } };
+    case "telegram":
+      return { ...base, contextNote: dynamicNote, channel: CHANNELS.TELEGRAM, channelMeta: {} };
+    default:
+      return { ...base, contextNote: dynamicNote, channel: channel || "api", channelMeta: {} };
+  }
+}

package/src/core/agent/memory.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { projectStorageRoot } from "../config/index.js";
 import { getOrCreateApxId } from "../apc/scaffold.js";
+import { apcAgentMemoryFile } from "../apc/paths.js";
 
 const EMPTY_MEMORY = (slug) =>
   `# Memory — ${slug}\n\n` +
@@ -27,7 +28,7 @@ export function agentMemoryPath(projectOrRoot, slug) {
 }
 
 export function legacyAgentMemoryPath(projectRoot, slug) {
-  return path.join(projectRoot, ".apc", "agents", slug, "memory.md");
+  return apcAgentMemoryFile(projectRoot, slug);
 }
 
 export function ensureAgentRuntimeDir(projectOrRoot, slug, { createMemory = false } = {}) {

package/src/core/agent/prompt-builder.js

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readIdentity } from "../identity/index.js";
+import { agentsMdFile } from "../apc/paths.js";
 import { readSelfMemoryForPrompt } from "./self-memory.js";
 import { buildSkillsHintBlock } from "./skills/catalog.js";
 
@@ -97,7 +98,7 @@ export const PROJECT_AGENTS_MAX_CHARS = 6000;
 export function buildProjectAgentsBlock(projectPath) {
   if (!projectPath) return "";
   try {
-    const file = path.join(projectPath, "AGENTS.md");
+    const file = agentsMdFile(projectPath);
     if (!fs.existsSync(file)) return "";
     let text = fs.readFileSync(file, "utf8").trim();
     if (!text) return "";

package/src/core/agent/prompts/modes/code-build.md

@@ -0,0 +1 @@
+MODE: build. Make the changes directly using your file and shell tools (read_file, write_file, edit_file, run_shell, …). Do not ask for confirmation and do not stop after one step — keep calling tools until the entire task is done, then briefly summarize what you changed and why. Prefer surgical edits over rewrites. When the user asks for a reusable script, snippet, or 'artifact' (something they want to keep and run later), put it under `artifacts/<name>` inside the project — it then shows up in the Artifacts tab. Don't drop reusable scripts at the project root. If a parameter you need is missing (API key, app id, target URL, …), call `ask_questions` ONCE with all your questions and stop — control returns to the user. Do not call ask_questions again in the same turn; you'll just get the same blank state back. Each question can be a string (free-text answer) OR an object {question, options:[{label, description}], multiSelect} for choices. Prefer 2–4 mutually-exclusive options when a question has a natural shortlist (yes/no, which-of-these, …); leave options empty for open-ended answers (API keys, names, free-form ideas). If the previous assistant turn already asked these same questions and the current user message is the compiled answers, DO NOT call ask_questions again — process the answers and proceed with the task.

package/src/core/agent/prompts/modes/code-plan.md

@@ -0,0 +1 @@
+MODE: plan. Investigate the codebase (read/list/search/grep) and propose an approach with the EXACT changes you would make (files + diffs/snippets). Do NOT write or edit files and do NOT run mutating shell commands — your editing tools are disabled in this mode. End with a concise, ordered plan.

package/src/core/agent/prompts/modes/index.js

@@ -0,0 +1,28 @@
+// Mode-specific system-prompt fragments for the Code module (plan / build).
+// Each mode lives in its own .md sibling and is loaded once at boot.
+//
+// Why .md files instead of inline strings: the prompts are content, not code.
+// Editing prompt copy shouldn't require touching code, and reviewing changes
+// to behavior should be a doc-shaped diff, not a JS-shaped one.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CODE_MODES } from "#core/constants/code-modes.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function load(file) {
+  return fs.readFileSync(path.join(__dirname, file), "utf8").trim();
+}
+
+const CODE_PLAN_GUIDANCE  = load("code-plan.md");
+const CODE_BUILD_GUIDANCE = load("code-build.md");
+
+/**
+ * Return the system-prompt fragment that explains how this mode behaves to
+ * the agent. Falls back to BUILD when the mode is missing or unknown — build
+ * is the safer default for the Code module (no mid-edit "do nothing" stall).
+ */
+export function codeModeGuidance(mode) {
+  return mode === CODE_MODES.PLAN ? CODE_PLAN_GUIDANCE : CODE_BUILD_GUIDANCE;
+}

package/src/core/agent/skills/loader.js

@@ -10,15 +10,19 @@
 //   1. <projectPath>/.apc/skills/<slug>.md           ← project-scoped (flat)
 //   1b.<projectPath>/.apc/skills/<slug>/SKILL.md     ← project-scoped (dir)
 //   2. ~/.apx/skills/<slug>/SKILL.md                 ← user-installed global
-//   3. <packageRoot>/skills/<slug>/SKILL.md          ← bundled core skills
-//                                                     (apx, apc-context)
-//   4. <packageRoot>/src/core/runtime-skills/<slug>.md
-//                                                     (claude-code, codex-cli,
-//                                                      opencode-cli, openrouter)
+//   3. <packageRoot>/src/core/runtime-skills/<slug>/SKILL.md
+//                                                     ← runtime-internal set
+//                                                       (rich apx-*, apc-context,
+//                                                       claude-code, codex-cli,
+//                                                       opencode-cli, openrouter)
 //
-// A slug found in a higher-priority location SHADOWS lower ones. A user can
-// override the bundled apc-context by dropping `~/.apx/skills/apc-context/SKILL.md`,
-// but the bundled copy stays in the package as a safety net.
+// A slug found in a higher-priority location SHADOWS lower ones. The user can
+// override any runtime skill by dropping `~/.apx/skills/<slug>/SKILL.md`; the
+// in-repo copy stays as a safety net.
+//
+// NOTE: <packageRoot>/skills/<slug>/SKILL.md is intentionally NOT in this chain.
+// That dir holds the engine-side slim set replicated to external CLIs/IDEs
+// (~/.claude/skills/, ~/.codex/skills/, ...) — it's not for the super-agent.
 //
 // Note: the bundled `apc-context` skill is REFRESHED from the canonical apc
 // repo on every npm install / update (see src/interfaces/cli/postinstall.js). APC is a
@@ -28,6 +32,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { apcSkillsDir } from "#core/apc/paths.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
@@ -35,8 +40,10 @@ const __dirname  = path.dirname(__filename);
 // → repo root. Used to find the bundled skills/ folder at the repo root.
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
 
-const RUNTIME_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
-const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
+// Runtime-internal skills — full apx-* catalog + CLI docs. Lives outside
+// <packageRoot>/skills/ so external tools that copy "skills/" from the repo
+// don't accidentally pull the rich set or the runtime CLI docs.
+const BUILTIN_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
 const GLOBAL_DIR         = path.join(os.homedir(), ".apx", "skills");
 
 // ---------------------------------------------------------------------------
@@ -119,7 +126,7 @@ export function listSkills({ projectPath } = {}) {
 
   // priority 1: project-scoped
   if (projectPath) {
-    const apcSkills = path.join(projectPath, ".apc", "skills");
+    const apcSkills = apcSkillsDir(projectPath);
     found.push(...scanDirStyle(apcSkills, "project"));
     found.push(...scanFlatStyle(apcSkills, "project"));
   }
@@ -127,11 +134,9 @@ export function listSkills({ projectPath } = {}) {
   // priority 2: user-installed global
   found.push(...scanDirStyle(GLOBAL_DIR, "global"));
 
-  // priority 3: bundled core skills (apx, apc-context)
-  found.push(...scanDirStyle(BUNDLED_SKILLS_DIR, "builtin"));
-
-  // priority 4: runtime docs (claude-code, codex-cli, opencode-cli, openrouter)
-  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
+  // priority 3: runtime-internal builtin set
+  // (rich apx-*, apc-context, plus claude-code, codex-cli, opencode-cli, openrouter)
+  found.push(...scanDirStyle(BUILTIN_SKILLS_DIR, "builtin"));
 
   // dedupe by slug (first-wins = higher priority shadows lower)
   const seen = new Set();
@@ -189,7 +194,6 @@ export function loadSkill(slug, { projectPath } = {}) {
 
 // Useful for diagnostics
 export const SKILL_LOCATIONS = {
-  runtime_skills: RUNTIME_SKILLS_DIR,
-  bundled: BUNDLED_SKILLS_DIR,
+  builtin: BUILTIN_SKILLS_DIR,
   global: GLOBAL_DIR,
 };

package/src/core/agent/stream/turn-accumulator.js

@@ -0,0 +1,73 @@
+// Accumulate super-agent stream events into the rich ChatPart shape so a
+// persisted assistant turn matches exactly what the UI rendered live.
+// Mirrors the front-end reducer in hooks/useChat.ts (applyStreamEvent) — keep
+// the two in sync if you add a new event type.
+//
+// Pure: no I/O, no globals. Caller drives it event-by-event and finally calls
+// build() to snapshot the resulting parts/notes/model/usage.
+export function makeTurnAccumulator() {
+  const parts = [];
+  const notes = [];
+  let model = null;
+  let usage = null;
+  const findTool = (id) => parts.find((p) => p.kind === "tool" && p.id === id);
+  return {
+    apply(ev) {
+      switch (ev?.type) {
+        case "model_start":
+          if (ev.model) model = ev.model;
+          break;
+        case "model_routed":
+          if (ev.model) model = ev.model;
+          if (ev.from_fallback) notes.push(`routing fell back → ${ev.model}`);
+          break;
+        case "engine_failed":
+          notes.push(`engine ${ev.model || "?"} failed → ${ev.retry_with || "retry"}`);
+          break;
+        case "model_retry":
+          notes.push(`retry (${ev.reason || "?"})`);
+          break;
+        case "tools_suppressed":
+          notes.push(`tools suppressed: ${(ev.tools || []).join(", ")}`);
+          break;
+        case "assistant_text":
+          if (ev.text) parts.push({ kind: "text", text: ev.text });
+          break;
+        case "tool_start":
+          if (ev.trace)
+            parts.push({
+              kind: "tool",
+              id: ev.trace.id,
+              tool: ev.trace.tool,
+              args: ev.trace.args,
+              status: "running",
+            });
+          break;
+        case "tool_deduped": {
+          const t = ev.trace && findTool(ev.trace.id);
+          if (t) t.status = "deduped";
+          break;
+        }
+        case "tool_result": {
+          const t = ev.trace && findTool(ev.trace.id);
+          if (t) {
+            t.result = ev.trace.result;
+            const errored =
+              ev.trace.result && typeof ev.trace.result === "object" && ev.trace.result.error;
+            t.status = errored ? "error" : t.status === "deduped" ? "deduped" : "done";
+          }
+          break;
+        }
+        case "final":
+          usage = ev.result?.usage ?? usage;
+          if (!model) model = ev.result?.name || null;
+          break;
+        default:
+          break;
+      }
+    },
+    build() {
+      return { parts, notes, model, usage };
+    },
+  };
+}

package/src/core/agent/suggestions.js

@@ -0,0 +1,37 @@
+// Parse the trailing ```suggestions JSON``` block out of an agent reply.
+// Surfaces like the deck/desktop render the JSON as chips; the visible reply
+// should be stripped of the fenced block so the user (and TTS) never sees it.
+//
+// Pure: just regex + JSON.parse. Malformed JSON drops suggestions silently
+// rather than failing the turn — better UX to show the reply without chips
+// than an error.
+const SUGGESTIONS_BLOCK_RE = /\n*```\s*suggestions\s*\n([\s\S]*?)\n?```\s*$/i;
+
+const MAX_SUGGESTIONS = 4;
+const MAX_LABEL_LEN = 48;
+const MAX_COMMAND_LEN = 96;
+
+export function extractSuggestions(text) {
+  if (typeof text !== "string" || !text) {
+    return { cleanText: text || "", suggestions: [] };
+  }
+  const m = SUGGESTIONS_BLOCK_RE.exec(text);
+  if (!m) return { cleanText: text, suggestions: [] };
+  const cleanText = text.slice(0, m.index).trim();
+  let suggestions = [];
+  try {
+    const parsed = JSON.parse(m[1]);
+    if (Array.isArray(parsed)) {
+      suggestions = parsed
+        .filter((s) => s && typeof s === "object" && typeof s.label === "string")
+        .slice(0, MAX_SUGGESTIONS)
+        .map((s) => ({
+          label: String(s.label).slice(0, MAX_LABEL_LEN),
+          ...(typeof s.command === "string" ? { command: s.command.slice(0, MAX_COMMAND_LEN) } : {}),
+        }));
+    }
+  } catch {
+    // Malformed JSON — drop silently.
+  }
+  return { cleanText, suggestions };
+}