@agentprojectcontext/apx 1.33.0 → 1.34.0

package/src/core/agent/tools/handlers/add-project.js

@@ -2,12 +2,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { readConfig, addProject as addProjectInConfig } from "#core/config/index.js";
 import { initApf } from "#core/apc/scaffold.js";
+import { agentsMdFile, apcProjectFile } from "#core/apc/paths.js";
 import { projectMeta } from "../helpers.js";
 
+// Stricter than core/apc/paths.js::isApcProject — `add_project` also requires
+// AGENTS.md at the root, matching the gate that config.addProject() enforces.
 function isApcProject(absPath) {
   return (
-    fs.existsSync(path.join(absPath, "AGENTS.md")) &&
-    fs.existsSync(path.join(absPath, ".apc", "project.json"))
+    fs.existsSync(agentsMdFile(absPath)) &&
+    fs.existsSync(apcProjectFile(absPath))
   );
 }
 

package/src/core/agent/tools/handlers/call-runtime.js

@@ -2,13 +2,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { loggerFor } from "#core/logging.js";
 import { readAgents } from "#core/apc/parser.js";
+import { apcProjectFile } from "#core/apc/paths.js";
 import {
   closeRuntimeSession,
   createRuntimeSession,
   extractRuntimeResult as extractApfResult,
 } from "#core/stores/runtime-sessions.js";
 import { buildRuntimeBridgeHint as buildApfHint } from "#core/agent/runtime-bridge.js";
-import { detectAll } from "#host/daemon/env-detect.js";
+import { detectAll } from "#core/runtimes/detect.js";
 import {
   findEngineSessionById,
   readEngineSessionContext,
@@ -88,7 +89,7 @@ function resolveProjectForAgent(projects, project, slug) {
 
 function projectName(project) {
   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"));
     if (meta.name) return meta.name;
   } catch {}
   return path.basename(project.path);

package/src/core/agent/tools/handlers/transcribe-audio.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
-import { transcribe } from "#host/daemon/transcription.js";
+import { transcribe } from "#core/voice/transcription.js";
 
 export default {
   name: "transcribe_audio",

package/src/core/agent/tools/helpers.js

@@ -1,12 +1,12 @@
 // Pure / config-only helpers used by tool handlers. Anything that needs the
 // running daemon's projects registry (projectMeta, resolveProject) lives in
-// host/daemon/projects-helpers.js and is re-exported here for back-compat.
+// core/apc/projects-helpers.js and is re-exported here for back-compat.
 import path from "node:path";
 import { agentSkills, buildAgentSystem as buildCoreAgentSystem } from "#core/agent/build-agent-system.js";
 import { buildConfirmDescription } from "#core/confirmation/index.js";
 import { PERMISSION_MODES, DEFAULT_PERMISSION_MODE } from "#core/constants/permissions.js";
 
-export { projectMeta, resolveProject } from "#host/daemon/projects-helpers.js";
+export { projectMeta, resolveProject } from "#core/apc/projects-helpers.js";
 
 export function safePathJoin(root, sub = ".") {
   const target = path.resolve(root, sub || ".");

package/src/core/agent/tools/names.js

@@ -0,0 +1,138 @@
+// Canonical tool names. Every place that mentions a tool by name — handler
+// dispatch, allow-lists, prompt rules, the registry bridge skip-set — imports
+// the constant from here. Refactor-safe: rename once, the rest follows.
+//
+// Keep the keys SCREAMING_SNAKE_CASE and the values snake_case (the on-wire
+// tool name the LLM sees). The two halves stay aligned so a typo on either
+// side is obvious.
+
+export const TOOLS = Object.freeze({
+  // Discovery / projects / agents
+  LIST_PROJECTS:       "list_projects",
+  ADD_PROJECT:         "add_project",
+  LIST_AGENTS:         "list_agents",
+  LIST_VAULT_AGENTS:   "list_vault_agents",
+  IMPORT_AGENT:        "import_agent",
+  LIST_MCPS:           "list_mcps",
+
+  // Memory
+  READ_AGENT_MEMORY:   "read_agent_memory",
+  READ_SELF_MEMORY:    "read_self_memory",
+  REMEMBER:            "remember",
+
+  // Filesystem / shell
+  LIST_FILES:          "list_files",
+  READ_FILE:           "read_file",
+  WRITE_FILE:          "write_file",
+  EDIT_FILE:           "edit_file",
+  SEARCH_FILES:        "search_files",
+  RUN_SHELL:           "run_shell",
+
+  // History / messages / sessions
+  TAIL_MESSAGES:       "tail_messages",
+  SEARCH_MESSAGES:     "search_messages",
+  SEARCH_SESSIONS:     "search_sessions",
+
+  // Skills + dynamic tool surface
+  LIST_SKILLS:         "list_skills",
+  LOAD_SKILL:          "load_skill",
+  DISCOVER_TOOLS:      "discover_tools",
+
+  // Tasks
+  LIST_TASKS:          "list_tasks",
+  CREATE_TASK:         "create_task",
+
+  // Interaction
+  ASK_QUESTIONS:       "ask_questions",
+
+  // Delegation / external
+  CALL_AGENT:          "call_agent",
+  CALL_MCP:            "call_mcp",
+  CALL_RUNTIME:        "call_runtime",
+
+  // Side-effects
+  SEND_TELEGRAM:       "send_telegram",
+  SET_IDENTITY:        "set_identity",
+  SET_PERMISSION_MODE: "set_permission_mode",
+  TRANSCRIBE_AUDIO:    "transcribe_audio",
+
+  // HTTP-bridged registry tools (not native handlers; served via
+  // core/tools/registry.js so the regular generic tools work the same way).
+  GREP:                "grep",
+  GLOB:                "glob",
+  FETCH:               "fetch",
+  SEARCH:              "search",
+});
+
+/**
+ * Native handlers in src/core/agent/tools/handlers/ that own these names.
+ * The registry bridge MUST skip these — otherwise the HTTP roundtrip would
+ * shadow the in-process handler with possibly different semantics.
+ */
+export const NATIVE_TOOL_NAMES = new Set([
+  TOOLS.LIST_PROJECTS,
+  TOOLS.LIST_AGENTS,
+  TOOLS.LIST_VAULT_AGENTS,
+  TOOLS.IMPORT_AGENT,
+  TOOLS.ADD_PROJECT,
+  TOOLS.LIST_MCPS,
+  TOOLS.READ_AGENT_MEMORY,
+  TOOLS.LIST_FILES,
+  TOOLS.READ_FILE,
+  TOOLS.WRITE_FILE,
+  TOOLS.EDIT_FILE,
+  TOOLS.SEARCH_FILES,
+  TOOLS.RUN_SHELL,
+  TOOLS.TAIL_MESSAGES,
+  TOOLS.SEARCH_MESSAGES,
+  TOOLS.CALL_AGENT,
+  TOOLS.CALL_MCP,
+  TOOLS.CALL_RUNTIME,
+  TOOLS.SEND_TELEGRAM,
+  TOOLS.SET_IDENTITY,
+  TOOLS.SET_PERMISSION_MODE,
+  TOOLS.READ_SELF_MEMORY,
+  TOOLS.REMEMBER,
+  TOOLS.LIST_SKILLS,
+  TOOLS.LOAD_SKILL,
+  TOOLS.LIST_TASKS,
+  TOOLS.CREATE_TASK,
+  TOOLS.ASK_QUESTIONS,
+  TOOLS.SEARCH_SESSIONS,
+  TOOLS.TRANSCRIBE_AUDIO,
+  TOOLS.DISCOVER_TOOLS,
+]);
+
+/**
+ * Read-only allow-list for the Code module's PLAN mode: the agent explores
+ * the repo and proposes changes without mutating anything. Build mode uses
+ * the full registry — see CODE_BUILD_TOOLS below.
+ */
+export const CODE_PLAN_TOOLS = Object.freeze([
+  TOOLS.READ_FILE,
+  TOOLS.LIST_FILES,
+  TOOLS.SEARCH_FILES,
+  TOOLS.GREP,
+  TOOLS.GLOB,
+  TOOLS.LIST_PROJECTS,
+  TOOLS.LIST_AGENTS,
+  TOOLS.LIST_MCPS,
+  TOOLS.READ_AGENT_MEMORY,
+  TOOLS.READ_SELF_MEMORY,
+  TOOLS.SEARCH_SESSIONS,
+  TOOLS.SEARCH_MESSAGES,
+  TOOLS.TAIL_MESSAGES,
+  TOOLS.LIST_SKILLS,
+  TOOLS.LOAD_SKILL,
+  TOOLS.LIST_TASKS,
+  TOOLS.ASK_QUESTIONS,
+  TOOLS.FETCH,
+  TOOLS.SEARCH,
+]);
+
+/**
+ * BUILD mode = unrestricted. Kept as a sentinel value so callers compare
+ * against the constant instead of the magic "*" string. The registry treats
+ * "*" as "expose every tool the channel is otherwise allowed to see".
+ */
+export const CODE_BUILD_TOOLS = "*";

package/src/core/agent/tools/registry-bridge.js

@@ -1,10 +1,9 @@
-// daemon/super-agent-tools/registry-bridge.js
 //
 // Generic bridge that exposes registry-backed HTTP tools (browser, fetch,
 // search, glob, grep, etc.) to the super-agent — no per-tool import boilerplate.
 //
 // How it works:
-//   1. Read TOOL_DEFINITIONS from daemon/tools/registry.js
+//   1. Read TOOL_DEFINITIONS from core/http-tools/registry.js
 //   2. Drop entries whose names collide with native super-agent tools (those
 //      win — they touch in-process state directly).
 //   3. For each remaining entry, produce { name, schema, makeHandler } in the
@@ -19,8 +18,9 @@
 // super-agent-tools/tools/, no import in index.js.
 
 import fs from "node:fs";
-import { TOOL_DEFINITIONS } from "#core/tools/registry.js";
+import { TOOL_DEFINITIONS } from "#core/http-tools/registry.js";
 import { TOKEN_PATH } from "#core/config/index.js";
+import { NATIVE_TOOL_NAMES } from "./names.js";
 
 // The bridge POSTs to the daemon's OWN HTTP server, which is behind the bearer
 // auth middleware (see api/shared.js). Without a token every bridged tool call
@@ -42,17 +42,9 @@ function daemonToken() {
   return cachedToken;
 }
 
-// Native handlers in super-agent-tools/tools/ that own these names. The bridge
-// MUST skip them or the registry version (HTTP roundtrip) would shadow the
-// native one with possibly different semantics.
-const NATIVE_NAMES = new Set([
-  "list_projects", "list_agents", "list_vault_agents", "import_agent",
-  "add_project", "list_mcps", "read_agent_memory",
-  "list_files", "read_file", "write_file", "edit_file", "search_files",
-  "run_shell", "tail_messages", "search_messages",
-  "call_agent", "call_mcp", "call_runtime",
-  "send_telegram", "set_identity", "set_permission_mode",
-]);
+// Native handler list lives in ./names.js so the bridge skip-set and the
+// allow-lists in api/code.js share one source of truth.
+const NATIVE_NAMES = NATIVE_TOOL_NAMES;
 
 // Default allow-list of categories the bridge will expose. The NATIVE_NAMES
 // filter handles duplicates inside these categories (e.g. "file" contains

package/src/core/agent/tools/registry.js

@@ -31,6 +31,8 @@ import listTasks from "./handlers/list-tasks.js";
 import discoverTools from "./handlers/discover-tools.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
+import { TOOLS } from "./names.js";
+import { CHANNELS } from "#core/constants/channels.js";
 
 const NATIVE_TOOLS = [
   listProjects,
@@ -76,9 +78,9 @@ function resolveBridgeCategories() {
 }
 
 const BRIDGED_TOOLS = buildBridgedTools({ categories: resolveBridgeCategories() });
-const TOOLS = [...NATIVE_TOOLS, ...BRIDGED_TOOLS];
+const ALL_TOOLS = [...NATIVE_TOOLS, ...BRIDGED_TOOLS];
 
-export const TOOL_SCHEMAS = TOOLS.map((tool) => tool.schema);
+export const TOOL_SCHEMAS = ALL_TOOLS.map((tool) => tool.schema);
 
 // ---------------------------------------------------------------------------
 // Lazy tools: base set (always loaded) + on-demand set (revealed via
@@ -93,78 +95,83 @@ export const TOOL_SCHEMAS = TOOLS.map((tool) => tool.schema);
 // sessions, projects/inventory, basic shell, tasks, skills, and discovery.
 export const BASE_TOOL_NAMES = new Set([
   // Discovery — the entry point to everything not loaded here.
-  "discover_tools",
+  TOOLS.DISCOVER_TOOLS,
   // Inventory — the model needs these to know what exists.
-  "list_projects",
-  "list_agents",
-  "list_mcps",
-  "list_skills",
-  "load_skill",
+  TOOLS.LIST_PROJECTS,
+  TOOLS.LIST_AGENTS,
+  TOOLS.LIST_MCPS,
+  TOOLS.LIST_SKILLS,
+  TOOLS.LOAD_SKILL,
   // Memory + identity.
-  "read_agent_memory",
-  "read_self_memory",
-  "remember",
-  "set_identity",
+  TOOLS.READ_AGENT_MEMORY,
+  TOOLS.READ_SELF_MEMORY,
+  TOOLS.REMEMBER,
+  TOOLS.SET_IDENTITY,
   // Sessions + messages (self-recall + channel history).
-  "search_sessions",
-  "search_messages",
-  "tail_messages",
+  TOOLS.SEARCH_SESSIONS,
+  TOOLS.SEARCH_MESSAGES,
+  TOOLS.TAIL_MESSAGES,
   // Channels + conversation control + lightweight delegation.
-  "send_telegram",
-  "ask_questions",
-  "call_agent",
+  TOOLS.SEND_TELEGRAM,
+  TOOLS.ASK_QUESTIONS,
+  TOOLS.CALL_AGENT,
   // Tasks (very common ask via chat).
-  "create_task",
-  "list_tasks",
+  TOOLS.CREATE_TASK,
+  TOOLS.LIST_TASKS,
   // Files + basic shell — frequent enough on chat to keep hot.
-  "read_file",
-  "write_file",
-  "edit_file",
-  "list_files",
-  "search_files",
-  "run_shell",
+  TOOLS.READ_FILE,
+  TOOLS.WRITE_FILE,
+  TOOLS.EDIT_FILE,
+  TOOLS.LIST_FILES,
+  TOOLS.SEARCH_FILES,
+  TOOLS.RUN_SHELL,
 ]);
 
 // Channels that get the FULL registry up front (deliberate, user-picked model,
 // no cheap-tier TPM cap). Everything else is a "lightweight" channel and starts
 // on BASE_TOOL_NAMES with discover_tools to expand.
-const FULL_CHANNELS = new Set(["routine", "api", "web", "code", "terminal"]);
+const FULL_CHANNELS = new Set([
+  CHANNELS.ROUTINE,
+  CHANNELS.API,
+  CHANNELS.WEB,
+  CHANNELS.CODE,
+]);
 
 // Category labels for grouping the discover_tools catalog. Native tools have no
 // registry category, so we assign one here; bridged tools carry their own
 // (browser/fetch/search/file) from registry-bridge.js.
 const NATIVE_CATEGORY = {
-  discover_tools: "system",
-  set_permission_mode: "system",
-  list_projects: "inventory",
-  list_agents: "inventory",
-  list_vault_agents: "inventory",
-  list_mcps: "inventory",
-  list_skills: "inventory",
-  load_skill: "skills",
-  import_agent: "agents",
-  add_project: "projects",
-  call_agent: "agents",
-  call_runtime: "runtime",
-  call_mcp: "mcp",
-  read_agent_memory: "memory",
-  read_self_memory: "memory",
-  remember: "memory",
-  set_identity: "identity",
-  search_sessions: "sessions",
-  search_messages: "messages",
-  tail_messages: "messages",
-  send_telegram: "messages",
-  ask_questions: "conversation",
-  create_task: "tasks",
-  list_tasks: "tasks",
-  transcribe_audio: "voice",
-  read_file: "files",
-  write_file: "files",
-  edit_file: "files",
-  list_files: "files",
-  search_files: "files",
-  run_shell: "shell",
+  [TOOLS.DISCOVER_TOOLS]:      "system",
+  [TOOLS.SET_PERMISSION_MODE]: "system",
+  [TOOLS.LIST_PROJECTS]:       "inventory",
+  [TOOLS.LIST_AGENTS]:         "inventory",
+  [TOOLS.LIST_VAULT_AGENTS]:   "inventory",
+  [TOOLS.LIST_MCPS]:           "inventory",
+  [TOOLS.LIST_SKILLS]:         "inventory",
+  [TOOLS.LOAD_SKILL]:          "skills",
+  [TOOLS.IMPORT_AGENT]:        "agents",
+  [TOOLS.ADD_PROJECT]:         "projects",
+  [TOOLS.CALL_AGENT]:          "agents",
+  [TOOLS.CALL_RUNTIME]:        "runtime",
+  [TOOLS.CALL_MCP]:            "mcp",
+  [TOOLS.READ_AGENT_MEMORY]:   "memory",
+  [TOOLS.READ_SELF_MEMORY]:    "memory",
+  [TOOLS.REMEMBER]:            "memory",
+  [TOOLS.SET_IDENTITY]:        "identity",
+  [TOOLS.SEARCH_SESSIONS]:     "sessions",
+  [TOOLS.SEARCH_MESSAGES]:     "messages",
+  [TOOLS.TAIL_MESSAGES]:       "messages",
+  [TOOLS.SEND_TELEGRAM]:       "messages",
+  [TOOLS.ASK_QUESTIONS]:       "conversation",
+  [TOOLS.CREATE_TASK]:         "tasks",
+  [TOOLS.LIST_TASKS]:          "tasks",
+  [TOOLS.TRANSCRIBE_AUDIO]:    "voice",
+  [TOOLS.READ_FILE]:           "files",
+  [TOOLS.WRITE_FILE]:          "files",
+  [TOOLS.EDIT_FILE]:           "files",
+  [TOOLS.LIST_FILES]:          "files",
+  [TOOLS.SEARCH_FILES]:        "files",
+  [TOOLS.RUN_SHELL]:           "shell",
 };
 
 function categoryOf(tool) {
@@ -179,7 +186,7 @@ function oneLine(desc = "") {
 
 // Static metadata index for every tool — name, schema, category, short blurb.
 // Used by the per-turn tool session for the catalog and activation lookups.
-const TOOL_META = TOOLS.map((t) => ({
+const TOOL_META = ALL_TOOLS.map((t) => ({
   name: t.name,
   schema: t.schema,
   category: categoryOf(t),
@@ -187,14 +194,10 @@ const TOOL_META = TOOLS.map((t) => ({
 }));
 const META_BY_NAME = new Map(TOOL_META.map((m) => [m.name, m]));
 
-export const BASE_TOOL_SCHEMAS = TOOLS
+export const BASE_TOOL_SCHEMAS = ALL_TOOLS
   .filter((t) => BASE_TOOL_NAMES.has(t.name))
   .map((t) => t.schema);
 
-// Back-compat alias: a few callers/tests historically referenced the "core"
-// subset. The base set supersedes it.
-export const CORE_TOOL_SCHEMAS = BASE_TOOL_SCHEMAS;
-
 const schemaName = (s) => s?.function?.name || s?.name;
 
 /**
@@ -337,7 +340,7 @@ export function makeToolHandlers(ctx) {
       requestConfirmation: ctx.requestConfirmation || null,
     }),
   };
-  return Object.fromEntries(TOOLS.map((tool) => [tool.name, tool.makeHandler(toolCtx)]));
+  return Object.fromEntries(ALL_TOOLS.map((tool) => [tool.name, tool.makeHandler(toolCtx)]));
 }
 
 // Diagnostic helper — useful for `apx daemon status` or debug logging.

package/src/core/apc/context-copy.js

@@ -0,0 +1,27 @@
+// Snapshot a project's read-aloud context — AGENTS.md + .apc/memory.md —
+// into a single labelled markdown string. Used by /deck/context/copy and
+// (potentially) any other "give me the context" surface.
+import fs from "node:fs/promises";
+import { AGENTS_MD, apcMemoryFile } from "./paths.js";
+import path from "node:path";
+
+const CONTEXT_FILES = [
+  { rel: AGENTS_MD,              label: AGENTS_MD },
+  { rel: `.apc/${"memory.md"}`,  label: ".apc/memory.md", abs: (root) => apcMemoryFile(root) },
+];
+
+export async function readProjectContext(projectPath) {
+  const chunks = [];
+  for (const entry of CONTEXT_FILES) {
+    const abs = entry.abs ? entry.abs(projectPath) : path.join(projectPath, entry.rel);
+    try {
+      const content = await fs.readFile(abs, "utf8");
+      if (content.trim()) {
+        chunks.push(`# ${entry.label}\n\n${content.trim()}\n`);
+      }
+    } catch {
+      // missing file is fine; we just skip it.
+    }
+  }
+  return chunks.join("\n---\n\n");
+}

package/src/core/apc/notes.js

@@ -0,0 +1,19 @@
+// Append-only project notes under .apc/notes/YYYY-MM-DD.md. Each note is a
+// timestamped markdown block; the file is append-only so no UID management
+// is required.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { apcNotesDir } from "./paths.js";
+
+export async function appendProjectNote(projectPath, { title, body }) {
+  const notesDir = apcNotesDir(projectPath);
+  await fs.mkdir(notesDir, { recursive: true });
+  const today = new Date().toISOString().slice(0, 10);
+  const file = path.join(notesDir, `${today}.md`);
+  const ts = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  const block = title
+    ? `\n## ${title}\n_${ts}_\n\n${body}\n`
+    : `\n### ${ts}\n\n${body}\n`;
+  await fs.appendFile(file, block, "utf8");
+  return file;
+}

package/src/core/apc/parser.js

@@ -1,6 +1,13 @@
 // Core parsers for APC — pure ESM, no deps.
 import fs from "node:fs";
 import path from "node:path";
+import {
+  apcAgentsDir,
+  apcAgentFile,
+  apcProjectFile,
+  agentsMdFile,
+  isApcProject,
+} from "./paths.js";
 
 export const SLUG_RE = /^[a-z][a-z0-9_-]*$/;
 const H1_RE = /^#\s+Agents\s*$/i;
@@ -91,7 +98,7 @@ export function parseAgentFile(slug, text) {
 
 // Read all .apc/agents/<slug>.md files. Returns [] if none exist.
 export function readAgentsFromDir(root) {
-  const dir = path.join(root, ".apc", "agents");
+  const dir = apcAgentsDir(root);
   if (!fs.existsSync(dir)) return [];
   return fs
     .readdirSync(dir)
@@ -123,7 +130,7 @@ 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 BUNDLED_VAULT_DIR = path.resolve(__parserDir, "../../../assets/agent-vault-defaults");
 export const VAULT_TOMBSTONE_PATH = path.join(VAULT_DIR, ".removed.json");
 
 function readVaultDirRaw(dir) {
@@ -189,7 +196,7 @@ function readVaultAgent(slug, { includeRemoved = false } = {}) {
 
 // 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`);
+  const localPath = apcAgentFile(root, slug);
   if (fs.existsSync(localPath)) {
     const agent = parseAgentFile(slug, fs.readFileSync(localPath, "utf8"));
     return { ...agent, source: "local" };
@@ -203,7 +210,7 @@ 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");
+  const p = apcProjectFile(root);
   if (!fs.existsSync(p)) return [];
   try {
     const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
@@ -235,7 +242,7 @@ export function readAgents(root) {
   const all = [...fromFiles, ...vaultAgents];
   const allSlugs = new Set(all.map((a) => a.slug));
 
-  const agentsMdPath = path.join(root, "AGENTS.md");
+  const agentsMdPath = agentsMdFile(root);
   if (!fs.existsSync(agentsMdPath)) return all;
 
   const mdText = fs.readFileSync(agentsMdPath, "utf8");
@@ -255,7 +262,7 @@ export function readAgents(root) {
 export function findApfRoot(start = process.cwd()) {
   let cur = path.resolve(start);
   while (true) {
-    if (fs.existsSync(path.join(cur, ".apc", "project.json"))) return cur;
+    if (isApcProject(cur)) return cur;
     const parent = path.dirname(cur);
     if (parent === cur) return null;
     cur = parent;

package/src/core/apc/paths.js

@@ -0,0 +1,87 @@
+// Filesystem layout of an APC project. The `.apc/` folder is APX's footprint
+// inside someone else's repo — everything that the daemon writes to a
+// user-checked-out project lives here, plus the top-level AGENTS.md spec.
+//
+// Use the helpers below instead of joining the literal names yourself. A typo
+// in `".apc"` or `"project.json"` will silently create an orphan tree instead
+// of failing loud, which is exactly the bug class these constants prevent.
+import fs from "node:fs";
+import path from "node:path";
+
+// Raw names — exported for the rare caller that needs to glob/match by name.
+export const APC_DIR = ".apc";
+export const APC_PROJECT_FILE = "project.json";
+export const APC_PROJECT_CONFIG_FILE = "config.json";
+export const APC_PROJECT_MEMORY_FILE = "memory.md";
+export const APC_AGENTS_DIR = "agents";
+export const APC_SKILLS_DIR = "skills";
+export const APC_COMMANDS_DIR = "commands";
+export const APC_NOTES_DIR = "notes";
+export const APC_MCPS_FILE = "mcps.json";
+export const APC_REMOVED_FILE = ".removed.json";
+export const AGENTS_MD = "AGENTS.md";
+
+// Path builders. `root` is the project root (the directory that contains
+// `.apc/` and `AGENTS.md`).
+export function apcDir(root) {
+  return path.join(root, APC_DIR);
+}
+
+export function apcProjectFile(root) {
+  return path.join(root, APC_DIR, APC_PROJECT_FILE);
+}
+
+export function apcProjectConfigFile(root) {
+  return path.join(root, APC_DIR, APC_PROJECT_CONFIG_FILE);
+}
+
+export function apcAgentsDir(root) {
+  return path.join(root, APC_DIR, APC_AGENTS_DIR);
+}
+
+export function apcAgentFile(root, slug) {
+  return path.join(root, APC_DIR, APC_AGENTS_DIR, `${slug}.md`);
+}
+
+export function apcAgentMemoryFile(root, slug) {
+  return path.join(root, APC_DIR, APC_AGENTS_DIR, slug, "memory.md");
+}
+
+export function apcRemovedFile(root) {
+  return path.join(root, APC_DIR, APC_AGENTS_DIR, APC_REMOVED_FILE);
+}
+
+export function apcSkillsDir(root) {
+  return path.join(root, APC_DIR, APC_SKILLS_DIR);
+}
+
+export function apcSkillFile(root, slug) {
+  return path.join(root, APC_DIR, APC_SKILLS_DIR, `${slug}.md`);
+}
+
+export function apcCommandsDir(root) {
+  return path.join(root, APC_DIR, APC_COMMANDS_DIR);
+}
+
+export function apcNotesDir(root) {
+  return path.join(root, APC_DIR, APC_NOTES_DIR);
+}
+
+// Project-level memory (super-agent / project-wide), distinct from the
+// per-agent memory.md that lives under .apc/agents/<slug>/.
+export function apcMemoryFile(root) {
+  return path.join(root, APC_DIR, APC_PROJECT_MEMORY_FILE);
+}
+
+export function apcMcpsFile(root) {
+  return path.join(root, APC_DIR, APC_MCPS_FILE);
+}
+
+export function agentsMdFile(root) {
+  return path.join(root, AGENTS_MD);
+}
+
+// True when `root` looks like an initialized APC project (has the marker file).
+export function isApcProject(root) {
+  return fs.existsSync(apcProjectFile(root));
+}