@agentprojectcontext/apx 1.24.0 → 1.27.1

package/src/core/memory/store.js

@@ -0,0 +1,231 @@
+// Vector store for the cross-channel memory RAG (Pieza 2).
+//
+// Dual backend, chosen at open() time:
+//   1. SqliteVecStore — better-sqlite3 + the sqlite-vec extension, persisted to
+//      ~/.apx/memory.db. Uses vec_distance_cosine() for scoring. Preferred.
+//   2. JsonStore — a dependency-free JSONL file with brute-force cosine in JS.
+//      Used when better-sqlite3 / sqlite-vec can't load (no native binary).
+//
+// Both expose the same interface:
+//   upsert(rows)              rows: {id, source, channel, ts, tag, text, embedder, dim, vector}
+//   search(vector, {embedder, k, channel}) -> [{...row, score}]
+//   hasId(id) / count()
+//   close()
+//
+// Cosine is only meaningful within one embedder space, so search() filters to
+// rows whose `embedder` matches the query's embedder. Everything here is
+// best-effort: open() never throws — on any failure it returns a JsonStore.
+
+import fs from "node:fs";
+import path from "node:path";
+import { cosineSim } from "./embeddings.js";
+
+function vecToBlob(vec) {
+  const f = new Float32Array(vec);
+  return Buffer.from(f.buffer, f.byteOffset, f.byteLength);
+}
+
+// ---------------------------------------------------------------------------
+// JSON fallback store
+// ---------------------------------------------------------------------------
+export class JsonStore {
+  constructor(jsonPath) {
+    this.jsonPath = jsonPath;
+    this.rows = new Map(); // id -> row {id, source, channel, ts, tag, text, embedder, dim, vector}
+    this.backend = "json";
+    this._load();
+  }
+
+  _load() {
+    try {
+      const text = fs.readFileSync(this.jsonPath, "utf8");
+      for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (!t) continue;
+        try {
+          const row = JSON.parse(t);
+          if (row && row.id) this.rows.set(row.id, row);
+        } catch {
+          /* skip bad line */
+        }
+      }
+    } catch {
+      /* no file yet */
+    }
+  }
+
+  _flush() {
+    fs.mkdirSync(path.dirname(this.jsonPath), { recursive: true });
+    const lines = [];
+    for (const row of this.rows.values()) lines.push(JSON.stringify(row));
+    const tmp = `${this.jsonPath}.tmp`;
+    fs.writeFileSync(tmp, lines.join("\n") + (lines.length ? "\n" : ""));
+    fs.renameSync(tmp, this.jsonPath);
+  }
+
+  upsert(rows) {
+    let n = 0;
+    for (const r of rows) {
+      if (!r || !r.id) continue;
+      this.rows.set(r.id, r);
+      n++;
+    }
+    if (n) this._flush();
+    return n;
+  }
+
+  hasId(id) {
+    return this.rows.has(id);
+  }
+
+  count() {
+    return this.rows.size;
+  }
+
+  clear() {
+    this.rows.clear();
+    this._flush();
+  }
+
+  search(vector, { embedder, k = 5, channel } = {}) {
+    const scored = [];
+    for (const row of this.rows.values()) {
+      if (embedder && row.embedder !== embedder) continue;
+      if (channel && row.channel !== channel) continue;
+      if (!Array.isArray(row.vector) || row.vector.length !== vector.length) continue;
+      scored.push({ ...row, score: cosineSim(vector, row.vector) });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, k);
+  }
+
+  close() {
+    /* nothing to release */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sqlite-vec store
+// ---------------------------------------------------------------------------
+class SqliteVecStore {
+  constructor(db) {
+    this.db = db;
+    this.backend = "sqlite-vec";
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS chunks (
+        id TEXT PRIMARY KEY,
+        source TEXT,
+        channel TEXT,
+        ts TEXT,
+        tag TEXT,
+        text TEXT,
+        embedder TEXT,
+        dim INTEGER,
+        vec BLOB
+      );
+      CREATE INDEX IF NOT EXISTS idx_chunks_embedder ON chunks(embedder);
+    `);
+    this._insert = db.prepare(
+      `INSERT INTO chunks (id, source, channel, ts, tag, text, embedder, dim, vec)
+       VALUES (@id, @source, @channel, @ts, @tag, @text, @embedder, @dim, @vec)
+       ON CONFLICT(id) DO UPDATE SET
+         source=@source, channel=@channel, ts=@ts, tag=@tag, text=@text,
+         embedder=@embedder, dim=@dim, vec=@vec`
+    );
+    this._has = db.prepare("SELECT 1 FROM chunks WHERE id = ?");
+    this._count = db.prepare("SELECT COUNT(*) AS n FROM chunks");
+  }
+
+  upsert(rows) {
+    const tx = this.db.transaction((items) => {
+      let n = 0;
+      for (const r of items) {
+        if (!r || !r.id) continue;
+        this._insert.run({
+          id: r.id,
+          source: r.source || null,
+          channel: r.channel || null,
+          ts: r.ts || null,
+          tag: r.tag || null,
+          text: r.text || "",
+          embedder: r.embedder || null,
+          dim: r.dim || (r.vector ? r.vector.length : 0),
+          vec: vecToBlob(r.vector),
+        });
+        n++;
+      }
+      return n;
+    });
+    return tx(rows);
+  }
+
+  hasId(id) {
+    return !!this._has.get(id);
+  }
+
+  count() {
+    return this._count.get().n;
+  }
+
+  clear() {
+    this.db.prepare("DELETE FROM chunks").run();
+  }
+
+  search(vector, { embedder, k = 5, channel } = {}) {
+    const blob = vecToBlob(vector);
+    const where = ["embedder = ?", "dim = ?"];
+    const params = [embedder, vector.length];
+    if (channel) {
+      where.push("channel = ?");
+      params.push(channel);
+    }
+    const rows = this.db
+      .prepare(
+        `SELECT id, source, channel, ts, tag, text, embedder, dim,
+                vec_distance_cosine(vec, ?) AS dist
+         FROM chunks
+         WHERE ${where.join(" AND ")}
+         ORDER BY dist ASC
+         LIMIT ?`
+      )
+      .all(blob, ...params, k);
+    // cosine distance → similarity score in [0,1] (sqlite-vec returns 1 - cos).
+    return rows.map((r) => ({ ...r, score: 1 - r.dist }));
+  }
+
+  close() {
+    try {
+      this.db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+// Open the vector store. Async because the native modules are dynamically
+// imported. Tries the sqlite-vec backend first; on ANY failure (module missing,
+// extension load error, broken build) it returns a JsonStore. Never throws.
+export async function openMemoryStore({ dbPath, jsonPath, log } = {}) {
+  const note = typeof log === "function" ? log : () => {};
+  if (!process.env.APX_MEMORY_FORCE_JSON) {
+    try {
+      const [{ default: Database }, sqliteVec] = await Promise.all([
+        import("better-sqlite3"),
+        import("sqlite-vec"),
+      ]);
+      fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+      const db = new Database(dbPath);
+      sqliteVec.load(db);
+      // Smoke-test the extension so a broken build falls back cleanly.
+      db.prepare("SELECT vec_distance_cosine(?, ?) AS d").get(
+        vecToBlob([1, 0]),
+        vecToBlob([1, 0])
+      );
+      note("memory: sqlite-vec backend active (" + dbPath + ")");
+      return new SqliteVecStore(db);
+    } catch (e) {
+      note("memory: sqlite-vec unavailable (" + (e?.message || e) + ") — JSON fallback");
+    }
+  }
+  return new JsonStore(jsonPath);
+}

package/src/core/messages-store.js

@@ -32,12 +32,41 @@ function dayPathMd(projectRoot, ts) {
   return path.join(projectRoot, "messages", `${day}.md`);
 }
 
-const VALID_MESSAGE_TYPES = new Set(["user", "agent", "tool", "system"]);
+// `compact` is a progressive-compaction summary record (Pieza 3): a dense
+// recap of older turns, stored inline in the channel JSONL so the reader can
+// prepend it as a [RESUMEN COMPACTADO] system turn instead of replaying the
+// raw history it covers.
+const VALID_MESSAGE_TYPES = new Set(["user", "agent", "tool", "system", "compact"]);
+
+// Render class (`type`) stays a 4-value enum the UI branches on. `actor_kind`
+// is a finer discriminator stored in meta: who/what actually produced the turn.
+//   superagent — the APX daemon-level agent (persona from identity.json)
+//   agent      — a project agent (its own slug/persona, may run on any engine)
+//   engine     — a raw external engine reply with no project-agent persona
+//   user / tool / system — mirror the render class
+const VALID_ACTOR_KINDS = new Set(["superagent", "agent", "engine", "user", "tool", "system", "compact"]);
 
 function normalizeMessageType(type) {
   return typeof type === "string" && VALID_MESSAGE_TYPES.has(type) ? type : null;
 }
 
+function normalizeActorKind(kind) {
+  return typeof kind === "string" && VALID_ACTOR_KINDS.has(kind) ? kind : null;
+}
+
+// Best-effort classification of the actor when not given explicitly. Legacy
+// records (and most call sites) don't set actor_kind, so this keeps history
+// queryable: a `type:"agent"` turn whose actor_id is the stable super-agent id
+// is a "superagent"; any other agent turn is a project "agent".
+function inferActorKind({ actor_kind, type, actor_id, meta = {} } = {}) {
+  const explicit = normalizeActorKind(actor_kind) || normalizeActorKind(meta.actor_kind);
+  if (explicit) return explicit;
+  if (type === "compact") return "compact";
+  if (type === "user" || type === "tool" || type === "system") return type;
+  if (type === "agent") return actor_id === "super_agent" ? "superagent" : "agent";
+  return null;
+}
+
 export function inferMessageType({ type, channel, direction, author, agent_slug, meta = {} } = {}) {
   const explicit = normalizeMessageType(type) || normalizeMessageType(meta.type) || normalizeMessageType(meta.actor_type);
   if (explicit) return explicit;
@@ -57,28 +86,31 @@ function inferActorId({ type, actor_id, author, agent_slug, meta = {} } = {}) {
   if (type === "agent") return agent_slug || author || "agent";
   if (type === "tool") return meta.tool || meta.tool_name || author || "tool";
   if (type === "system") return author || "system";
+  if (type === "compact") return "compact";
   return author || null;
 }
 
-function messageMeta({ type, actor_id, agent_slug, session_id, external_id, meta = {} }) {
+function messageMeta({ type, actor_id, actor_kind, agent_slug, session_id, external_id, meta = {} }) {
   return {
     ...meta,
     type,
     ...(actor_id ? { actor_id } : {}),
+    ...(actor_kind ? { actor_kind } : {}),
     ...(agent_slug ? { agent: agent_slug } : {}),
     ...(session_id ? { session_id } : {}),
     ...(external_id ? { external_id } : {}),
   };
 }
 
-export function appendMessageToFs({ projectRoot, channel, direction, type, actor_id, author, body, meta = {}, ts, agent_slug, session_id, external_id }) {
+export function appendMessageToFs({ projectRoot, channel, direction, type, actor_id, actor_kind, author, body, meta = {}, ts, agent_slug, session_id, external_id }) {
   ts = ts || nowIso();
   const file = dayPathJsonl(projectRoot, ts);
   fs.mkdirSync(path.dirname(file), { recursive: true });
 
   const msgType = inferMessageType({ type, channel, direction, author, agent_slug, meta });
   const msgActorId = inferActorId({ type: msgType, actor_id, author, agent_slug, meta });
-  const fullMeta = messageMeta({ type: msgType, actor_id: msgActorId, agent_slug, session_id, external_id, meta });
+  const msgActorKind = inferActorKind({ actor_kind, type: msgType, actor_id: msgActorId, meta });
+  const fullMeta = messageMeta({ type: msgType, actor_id: msgActorId, actor_kind: msgActorKind, agent_slug, session_id, external_id, meta });
 
   const record = {
     ts,
@@ -104,9 +136,11 @@ export function insertMessageRow(db, m) {
   }
   const type = inferMessageType(m);
   const actor_id = inferActorId({ ...m, type });
+  const actor_kind = inferActorKind({ actor_kind: m.actor_kind, type, actor_id, meta: m.meta || {} });
   const meta = messageMeta({
     type,
     actor_id,
+    actor_kind,
     agent_slug: m.agent_slug,
     session_id: m.session_id,
     external_id: m.external_id,
@@ -131,13 +165,14 @@ export function insertMessageRow(db, m) {
 }
 
 // Single entry point used by everywhere the daemon writes a message.
-export function appendMessage({ projectRoot, db, channel, direction, type, actor_id, author, body, meta = {}, ts, agent_slug, session_id, external_id }) {
+export function appendMessage({ projectRoot, db, channel, direction, type, actor_id, actor_kind, author, body, meta = {}, ts, agent_slug, session_id, external_id }) {
   const written = appendMessageToFs({
     projectRoot,
     channel,
     direction,
     type,
     actor_id,
+    actor_kind,
     author,
     body,
     meta,
@@ -151,6 +186,7 @@ export function appendMessage({ projectRoot, db, channel, direction, type, actor
     direction,
     type,
     actor_id,
+    actor_kind,
     author,
     body,
     meta,
@@ -188,6 +224,7 @@ export function parseDayJsonl(text) {
       agent_slug,
       meta,
     });
+    const actor_kind = inferActorKind({ actor_kind: obj.actor_kind, type, actor_id, meta });
     out.push({
       ts: obj.ts,
       channel: obj.channel,
@@ -195,6 +232,7 @@ export function parseDayJsonl(text) {
       type,
       author: obj.author,
       actor_id,
+      actor_kind,
       body: obj.body || "",
       meta,
       agent_slug,
@@ -228,10 +266,12 @@ export function parseDayFile(text) {
     const agent_slug = meta.agent;
     const type = inferMessageType({ channel, direction, author, agent_slug, meta });
     const actor_id = inferActorId({ type, author, agent_slug, meta });
+    const actor_kind = inferActorKind({ type, actor_id, meta });
     out.push({
       ts, channel, direction, author, body, meta,
       type,
       actor_id,
+      actor_kind,
       agent_slug,
       session_id: meta.session_id ?? (typeof meta.apc_session_id === "number" ? meta.apc_session_id : null),
       external_id: meta.external_id,
@@ -376,20 +416,59 @@ export function searchProjectMessages(projectRoot, query, limit = 50) {
   return all.slice(0, Math.min(limit, 500));
 }
 
-// File-based Telegram turn history: reads from ~/.apx/messages/telegram/ JSONL.
+const TOOL_CONTEXT_CAP = 400; // chars of a tool result kept in model context
+
+// Truncated, prefixed rendering of a tool result for model context (Pieza 3).
+function renderToolResult(m) {
+  const name = m.meta?.tool_name || m.meta?.tool || m.actor_id || "tool";
+  const body = String(m.body || "").replace(/\s+/g, " ").trim();
+  return `[tool result: ${name}] ${body}`.slice(0, TOOL_CONTEXT_CAP);
+}
+
+// Collapse consecutive same-role entries into one message. Keeps the model
+// context clean and side-steps engines (Anthropic) that dislike consecutive
+// same-role turns once tool results land on the assistant side.
+function coalesceTurns(turns) {
+  const out = [];
+  for (const t of turns) {
+    const prev = out[out.length - 1];
+    if (prev && prev.role === t.role) {
+      prev.content = `${prev.content}\n${t.content}`.trim();
+    } else {
+      out.push({ role: t.role, content: t.content });
+    }
+  }
+  return out;
+}
+
+// File-based channel turn history (Pieza 3). Reads ~/.apx/messages/<channel>/
+// JSONL and shapes it for use as `previousMessages`:
+//   - the latest `compact` record (if any) is prepended as a role:"system"
+//     turn "[RESUMEN COMPACTADO turnos a-b]: …"; the raw turns it covers are
+//     dropped (they live in the summary now)
+//   - tool results are INCLUDED, truncated to 400 chars, prefixed
+//     "[tool result: <tool>]" (kept on the assistant side)
+//   - the most recent `keepRecent` conversational turns are kept verbatim
+//   - consecutive same-role turns are coalesced
+//
 // Pass _globalMessagesDir to override the default dir (useful in tests).
-export function getRecentTelegramTurnsFromFs({
+export function getRecentChannelTurnsFromFs({
+  channel = "telegram",
   chat_id,
-  limit = 12,
+  // Back-compat: `limit` (if given) is treated as the verbatim-turn budget.
+  limit,
+  keepRecent = 40,
   max_age_hours = 24,
+  includeTools = true,
   _globalMessagesDir,
 } = {}) {
   if (!chat_id) return [];
+  const keep = Number.isFinite(limit) ? limit : keepRecent;
   const cutoff = new Date(Date.now() - max_age_hours * 3600_000)
     .toISOString()
     .replace(/\.\d{3}Z$/, "Z");
   const base = _globalMessagesDir || GLOBAL_MESSAGES_DIR;
-  const dir = path.join(base, "telegram");
+  const dir = path.join(base, channel);
   if (!fs.existsSync(dir)) return [];
   const all = [];
   for (const f of fs.readdirSync(dir).sort()) {
@@ -401,20 +480,58 @@ export function getRecentTelegramTurnsFromFs({
     }
   }
   all.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
-  const filtered = all
-    .filter((m) => String(m.meta?.chat_id ?? "") === String(chat_id))
-    // Only conversational turns become model context. `tool` / `system`
-    // entries are kept in the store for the audit trail (and for channels
-    // that DO render tools), but replaying them as assistant messages would
-    // look like bogus answers to the model.
-    .filter((m) => m.type === "user" || m.type === "agent")
-    .slice(-limit);
-  return filtered.map((m) => {
-    const role = m.direction === "in" ? "user" : "assistant";
-    let content = m.body;
-    if (role === "assistant") content = sanitizeAssistantForContext(content);
-    return { role, content };
-  });
+  const mine = all.filter((m) => String(m.meta?.chat_id ?? "") === String(chat_id));
+
+  // Latest compact record wins; everything it covers is replaced by its summary.
+  let compact = null;
+  for (const m of mine) if (m.type === "compact") compact = m;
+  const coverUntil = compact ? compact.meta?.covers_until_ts || compact.ts : "";
+
+  const eligible = mine.filter(
+    (m) =>
+      (m.type === "user" || m.type === "agent" || (includeTools && m.type === "tool")) &&
+      (!coverUntil || m.ts > coverUntil)
+  );
+
+  // Keep the last `keep` conversational (user/agent) turns plus any tool
+  // results interleaved among them.
+  const kept = [];
+  let realCount = 0;
+  for (let i = eligible.length - 1; i >= 0; i--) {
+    const m = eligible[i];
+    kept.push(m);
+    if (m.type === "user" || m.type === "agent") realCount++;
+    if (realCount >= keep) break;
+  }
+  kept.reverse();
+
+  const turns = [];
+  if (compact && String(compact.body || "").trim()) {
+    const range = compact.meta?.range;
+    const label = Array.isArray(range)
+      ? `turnos ${range[0]}-${range[1]}`
+      : `${compact.meta?.count || ""} turnos previos`.trim();
+    turns.push({
+      role: "system",
+      content: `[RESUMEN COMPACTADO ${label}]:\n${String(compact.body).trim()}`,
+    });
+  }
+  for (const m of kept) {
+    if (m.type === "tool") {
+      turns.push({ role: "assistant", content: renderToolResult(m) });
+    } else {
+      const role = m.type === "user" ? "user" : "assistant";
+      let content = m.body;
+      if (role === "assistant") content = sanitizeAssistantForContext(content);
+      turns.push({ role, content });
+    }
+  }
+  return coalesceTurns(turns);
+}
+
+// Telegram-specific wrapper kept for back-compat with existing call sites.
+export function getRecentTelegramTurnsFromFs(opts = {}) {
+  return getRecentChannelTurnsFromFs({ ...opts, channel: "telegram" });
 }
 
 // ---------------------------------------------------------------------------
@@ -422,14 +539,15 @@ export function getRecentTelegramTurnsFromFs({
 // ---------------------------------------------------------------------------
 
 // Write a message to the global channel store.  No SQL cache — JSONL only.
-export function appendGlobalMessage({ channel, direction, type, actor_id, author, body, meta = {}, ts, agent_slug, external_id }) {
+export function appendGlobalMessage({ channel, direction, type, actor_id, actor_kind, author, body, meta = {}, ts, agent_slug, external_id }) {
   ts = ts || nowIso();
   const dir = path.join(GLOBAL_MESSAGES_DIR, channel);
   fs.mkdirSync(dir, { recursive: true });
   const file = path.join(dir, `${ts.slice(0, 10)}.jsonl`);
   const msgType = inferMessageType({ type, channel, direction, author, agent_slug, meta });
   const msgActorId = inferActorId({ type: msgType, actor_id, author, agent_slug, meta });
-  const fullMeta = messageMeta({ type: msgType, actor_id: msgActorId, agent_slug, external_id, meta });
+  const msgActorKind = inferActorKind({ actor_kind, type: msgType, actor_id: msgActorId, meta });
+  const fullMeta = messageMeta({ type: msgType, actor_id: msgActorId, actor_kind: msgActorKind, agent_slug, external_id, meta });
   const record = {
     ts,
     channel,

package/src/core/parser.js

@@ -104,41 +104,103 @@ export function readAgentsFromDir(root) {
 }
 
 // ---------------------------------------------------------------------------
-// Vault — ~/.apx/agents/<slug>.md  (global templates, no memory)
+// Vault — global, project-agnostic agent templates.
+// Two-layer model:
+//   - BUNDLED  → assets/agent-vault-defaults/<slug>.md, shipped with APX,
+//                always visible. Read-only on the user's machine.
+//   - USER     → ~/.apx/agents/<slug>.md, the user's own additions and
+//                overrides on top of the bundle. User layer wins per-slug.
+//   - REMOVED  → ~/.apx/agents/.removed.json, tombstones (slugs the user
+//                explicitly deleted). Hidden from listings until restored.
+// Reading: BUNDLED ∪ USER, dedup by slug (user wins), filter tombstones.
+// Writing: always to the USER layer (copy-on-write). Removing: tombstones
+// if it's a bundled slug, deletes the user file otherwise.
 // ---------------------------------------------------------------------------
 
 import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __parserDir = path.dirname(fileURLToPath(import.meta.url));
 
 export const VAULT_DIR = path.join(os.homedir(), ".apx", "agents");
+export const BUNDLED_VAULT_DIR = path.resolve(__parserDir, "../../assets/agent-vault-defaults");
+export const VAULT_TOMBSTONE_PATH = path.join(VAULT_DIR, ".removed.json");
 
-export function readVaultAgents() {
-  if (!fs.existsSync(VAULT_DIR)) return [];
+function readVaultDirRaw(dir) {
+  if (!fs.existsSync(dir)) return [];
   return fs
-    .readdirSync(VAULT_DIR)
+    .readdirSync(dir)
     .filter((f) => f.endsWith(".md") && SLUG_RE.test(f.slice(0, -3)))
     .sort()
-    .map((f) => {
-      const slug = f.slice(0, -3);
-      const agent = parseAgentFile(slug, fs.readFileSync(path.join(VAULT_DIR, f), "utf8"));
-      return { ...agent, source: "vault" };
-    });
+    .map((f) => ({ slug: f.slice(0, -3), file: path.join(dir, f) }));
+}
+
+export function readVaultTombstones() {
+  if (!fs.existsSync(VAULT_TOMBSTONE_PATH)) return new Set();
+  try {
+    const raw = JSON.parse(fs.readFileSync(VAULT_TOMBSTONE_PATH, "utf8"));
+    return new Set(Array.isArray(raw.slugs) ? raw.slugs : []);
+  } catch { return new Set(); }
+}
+
+export function writeVaultTombstones(slugs) {
+  fs.mkdirSync(VAULT_DIR, { recursive: true });
+  fs.writeFileSync(
+    VAULT_TOMBSTONE_PATH,
+    JSON.stringify({ slugs: [...slugs].sort() }, null, 2) + "\n",
+  );
 }
 
-// Resolve a single agent for a project: local file → vault → null
+export function readVaultAgents({ includeRemoved = false } = {}) {
+  const tombstones = readVaultTombstones();
+  // Build a map slug → { agent, source }. User layer overrides bundled.
+  const bySlug = new Map();
+  for (const { slug, file } of readVaultDirRaw(BUNDLED_VAULT_DIR)) {
+    if (!includeRemoved && tombstones.has(slug)) continue;
+    const agent = parseAgentFile(slug, fs.readFileSync(file, "utf8"));
+    bySlug.set(slug, { ...agent, source: "bundled" });
+  }
+  for (const { slug, file } of readVaultDirRaw(VAULT_DIR)) {
+    if (!includeRemoved && tombstones.has(slug)) continue;
+    const agent = parseAgentFile(slug, fs.readFileSync(file, "utf8"));
+    const overrides = bySlug.has(slug);
+    bySlug.set(slug, { ...agent, source: overrides ? "user-override" : "user" });
+  }
+  return [...bySlug.values()].sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+// Resolve a single vault agent honoring the layered model. Returns null when
+// the slug is missing or tombstoned (unless includeRemoved is true).
+function readVaultAgent(slug, { includeRemoved = false } = {}) {
+  if (!includeRemoved && readVaultTombstones().has(slug)) return null;
+  const userPath = path.join(VAULT_DIR, `${slug}.md`);
+  if (fs.existsSync(userPath)) {
+    const agent = parseAgentFile(slug, fs.readFileSync(userPath, "utf8"));
+    const overrides = fs.existsSync(path.join(BUNDLED_VAULT_DIR, `${slug}.md`));
+    return { ...agent, source: overrides ? "user-override" : "user" };
+  }
+  const bundledPath = path.join(BUNDLED_VAULT_DIR, `${slug}.md`);
+  if (fs.existsSync(bundledPath)) {
+    const agent = parseAgentFile(slug, fs.readFileSync(bundledPath, "utf8"));
+    return { ...agent, source: "bundled" };
+  }
+  return null;
+}
+
+// Resolve a single agent for a project: local file → vault (layered) → null.
 export function resolveAgent(root, slug) {
   const localPath = path.join(root, ".apc", "agents", `${slug}.md`);
   if (fs.existsSync(localPath)) {
     const agent = parseAgentFile(slug, fs.readFileSync(localPath, "utf8"));
     return { ...agent, source: "local" };
   }
-  const vaultPath = path.join(VAULT_DIR, `${slug}.md`);
-  if (fs.existsSync(vaultPath)) {
-    const agent = parseAgentFile(slug, fs.readFileSync(vaultPath, "utf8"));
-    return { ...agent, source: "vault" };
-  }
-  return null;
+  return readVaultAgent(slug);
 }
 
+// Exported for callers (CLI rm/edit, API DELETE/PATCH) that need to know
+// whether a slug is user-layer, bundled, or absent before acting.
+export { readVaultAgent };
+
 // Return slugs imported from vault in this project (from project.json)
 export function importedVaultSlugs(root) {
   const p = path.join(root, ".apc", "project.json");