@agentprojectcontext/apx 1.33.1 → 1.35.0

package/src/host/daemon/deck-exec.js

@@ -0,0 +1,148 @@
+// /deck/exec implementation.
+//
+// All shell spawning sits behind this helper so api/deck.js stays a thin HTTP
+// adapter. The OS abstraction is intentionally tiny: pick the "opener" command
+// for the platform and pass `target` as a single arg (no shell). For
+// app-launching on macOS we use `open -a <App>`.
+//
+// Stays in host/daemon/ because it's pure process orchestration (spawn child
+// processes), not domain logic.
+import { spawn } from "node:child_process";
+
+const MAC_APPS = {
+  // Whitelisted mac app names. Adding here is the only way the deck can
+  // launch something — we never honour a free-form `app` string.
+  claude: "Claude",
+  chatgpt: "ChatGPT",
+  cursor: "Cursor",
+  vscode: "Visual Studio Code",
+  zen: "Zen Browser",
+  terminal: "Terminal",
+  iterm: "iTerm",
+  finder: "Finder",
+};
+
+function platformOpener() {
+  if (process.platform === "darwin") return "open";
+  if (process.platform === "win32") return "start";
+  return "xdg-open";
+}
+
+function spawnDetached(cmd, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    let settled = false;
+    const done = (err) => {
+      if (settled) return;
+      settled = true;
+      err ? reject(err) : resolve();
+    };
+    child.on("error", done);
+    // Give the process a tick to fail-fast (bad binary); otherwise detach.
+    setTimeout(() => {
+      try { child.unref(); } catch {}
+      done(null);
+    }, 250);
+  });
+}
+
+/** Pipe `text` into the platform clipboard (pbcopy / xclip / clip). */
+export async function copyToClipboard(text) {
+  const platform = process.platform;
+  const cmd =
+    platform === "darwin" ? "pbcopy" :
+    platform === "win32" ? "clip" :
+    "xclip";
+  const args = platform === "linux" ? ["-selection", "clipboard"] : [];
+  await new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ["pipe", "ignore", "ignore"] });
+    child.on("error", reject);
+    child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} exited ${code}`))));
+    child.stdin.end(text);
+  });
+}
+
+/**
+ * Dispatch one /deck/exec action. `ctx.projects` is the daemon's
+ * ProjectManager — used to resolve numeric project ids to absolute paths.
+ *
+ * Supported kinds:
+ *   open_app      { target: "<appKey>" }                        — mac only
+ *   open_path     { target: "<absPath>" | "<projectId>" }       — opens in Finder/default
+ *   open_path_in  { target: "<projectId>", app: "<appKey>" }    — mac only
+ *   open_url      { target: "https://..." }
+ *   copy_clipboard { text: "..." }
+ */
+export async function runDeckExec({ kind, target, appHint, text, ctx }) {
+  const platform = process.platform;
+
+  // Resolve a project id (number or "<n>") into an absolute path via
+  // the daemon's project manager. Returns null when the id is bogus.
+  const projectPath = (idOrPath) => {
+    if (!idOrPath) return null;
+    const str = String(idOrPath);
+    if (str.startsWith("/")) return str;
+    if (!/^\d+$/.test(str)) return null;
+    const p = ctx.projects?.get?.(parseInt(str, 10));
+    return p?.path || null;
+  };
+
+  if (kind === "open_app") {
+    if (platform !== "darwin") throw new Error("open_app only implemented on macOS for now");
+    const appName = MAC_APPS[String(target || "").toLowerCase()];
+    if (!appName) throw new Error(`unknown app: ${target}`);
+    // Two-step launch:
+    //   1. `open -a` ensures the app is running (no-op if already up).
+    //   2. AppleScript `activate` brings it to the foreground across
+    //      Spaces / Stage Manager, which `open` alone often skips when
+    //      the app was already running in the background.
+    await spawnDetached("open", ["-a", appName]);
+    try {
+      await new Promise((resolve) => {
+        const child = spawn("osascript", [
+          "-e",
+          `tell application "${appName}" to activate`,
+        ], { stdio: "ignore" });
+        child.on("close", () => resolve());
+        child.on("error", () => resolve());
+        setTimeout(() => { try { child.kill(); } catch {} ; resolve(); }, 600);
+      });
+    } catch {
+      // osascript missing or refused — `open -a` already ran.
+    }
+    return { app: appName };
+  }
+
+  if (kind === "open_path") {
+    const resolved = projectPath(target);
+    if (!resolved) throw new Error(`open_path: invalid target ${target}`);
+    await spawnDetached(platformOpener(), [resolved]);
+    return { path: resolved };
+  }
+
+  if (kind === "open_path_in") {
+    if (platform !== "darwin") throw new Error("open_path_in only implemented on macOS for now");
+    const resolved = projectPath(target);
+    if (!resolved) throw new Error(`open_path_in: invalid target ${target}`);
+    const appName = MAC_APPS[String(appHint || "").toLowerCase()];
+    if (!appName) throw new Error(`open_path_in: unknown app ${appHint}`);
+    await spawnDetached("open", ["-a", appName, resolved]);
+    return { app: appName, path: resolved };
+  }
+
+  if (kind === "open_url") {
+    if (!target || !/^https?:\/\//i.test(String(target))) {
+      throw new Error("open_url: target must be http(s) URL");
+    }
+    await spawnDetached(platformOpener(), [String(target)]);
+    return { url: target };
+  }
+
+  if (kind === "copy_clipboard") {
+    if (typeof text !== "string") throw new Error("copy_clipboard: text required");
+    await copyToClipboard(text);
+    return { bytes: text.length };
+  }
+
+  throw new Error(`unknown kind: ${kind}`);
+}

package/src/host/daemon/index.js

@@ -18,7 +18,7 @@ import {
 import { ProjectManager } from "./db.js";
 import { McpRegistry } from "#core/mcp/runner.js";
 import { PluginManager } from "./plugins/index.js";
-import { RoutineScheduler } from "./routines.js";
+import { RoutineScheduler } from "./routines-scheduler.js";
 import { buildApi } from "./api.js";
 import { createTokenStore } from "./token-store.js";
 import { triggerWakeup } from "./wakeup.js";
@@ -218,11 +218,28 @@ async function main() {
     // store, and start the incremental RAG indexer. Best-effort — never blocks
     // boot and never throws into the daemon.
     initMemory({ config: cfg, log }).catch((e) => log(`memory: init failed: ${e?.message || e}`));
+    // Skill Inspector: if enabled, refresh its vector index in the background so
+    // any SKILL.md added/edited while the daemon was down is picked up without a
+    // manual `apx skills index`. Best-effort; never blocks boot.
+    (async () => {
+      try {
+        const { isInspectorEnabled } = await import("#core/agent/skills/inspector.js");
+        if (!isInspectorEnabled(cfg)) return;
+        const { backgroundRefreshIfStale } = await import("#core/agent/skills/index-store.js");
+        const r = backgroundRefreshIfStale({
+          embedOpts: { globalConfig: cfg },
+          onDone: (out) => log(`skill inspector: index refreshed (${out.embedder}, +${out.changed.added.length} -${out.changed.removed.length} ~${out.changed.refreshed.length})`),
+        });
+        if (r.started) log(`skill inspector: reindexing ${r.missing} new / ${r.stale} stale / ${r.gone} gone skills…`);
+      } catch (e) {
+        log(`skill inspector: index refresh skipped (${e?.message || e})`);
+      }
+    })();
     // Fire wake-up message after a short delay so plugins (Telegram) are ready
     setTimeout(() => triggerWakeup(cfg, log), 3000);
     // Preload whisper-server in the background so first desktop transcription is fast.
     // Adopts an existing one if already on the port; otherwise spawns fresh.
-    import("./transcription.js").then(({ preloadWhisperServer }) => {
+    import("./whisper-server.js").then(({ preloadWhisperServer }) => {
       preloadWhisperServer((m) => log(m));
     }).catch(() => {});
   });
@@ -257,7 +274,7 @@ async function main() {
     stopMemory();
     registries.shutdown();
     // Best-effort shutdown of whisper-server subprocess.
-    import("./transcription.js").then(({ shutdownWhisperServer }) => {
+    import("./whisper-server.js").then(({ shutdownWhisperServer }) => {
       shutdownWhisperServer().catch(() => {});
     }).catch(() => {});
     server.close(() => {

package/src/host/daemon/plugins/telegram/index.js

@@ -32,12 +32,12 @@ import path from "node:path";
 import { TELEGRAM_STATE_PATH, APX_HOME } from "#core/config/index.js";
 import { callEngine } from "#core/engines/index.js";
 import { runSuperAgent, isSuperAgentEnabled } from "#core/agent/super-agent.js";
-import { stripThinking } from "../../thinking.js";
+import { stripThinking } from "#core/util/thinking.js";
 import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
 import { compactChannelIfNeeded } from "#core/memory/index.js";
 import { readAgents } from "#core/apc/parser.js";
 import { buildAgentSystem } from "#core/agent/build-agent-system.js";
-import { transcribe as transcribeAudioFile } from "../../transcription.js";
+import { transcribe as transcribeAudioFile } from "#core/voice/transcription.js";
 import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
 import { registerSender, resolveAllowedTools } from "#core/identity/telegram.js";
 import { buildRelationshipBlock } from "#core/agent/index.js";
@@ -45,13 +45,13 @@ import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pend
 import { CHANNELS } from "#core/constants/channels.js";
 import { tryResolveSkillCommand } from "#core/agent/skills/trigger.js";
 import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
-import * as askFlow from "./ask.js";
+import * as askFlow from "#core/channels/telegram/ask.js";
 
-// API_BASE re-imported from ./media.js below
+// API_BASE re-imported from #core/channels/telegram/media.js below
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
-// All non-class-bound helpers live in ./helpers.js so the file stays
-// focused on the poller class + dispatch wiring.
+// All non-class-bound channel logic lives in core/channels/telegram/ — this
+// file stays focused on the poller class + plugin lifecycle wiring.
 import {
   buildTelegramMeta,
   loadState,
@@ -61,11 +61,11 @@ import {
   tokenSource,
   resolveChannels,
   sleep,
-} from "./helpers.js";
-import { handleUpdate } from "./dispatch.js";
+} from "#core/channels/telegram/helpers.js";
+import { handleUpdate } from "#core/channels/telegram/dispatch.js";
 
 // ---------- media sending helpers (re-exports) ------------------------------
-import { sendPhoto, sendVoice, sendDocument, sendAudio, downloadTelegramFile, API_BASE } from "./media.js";
+import { sendPhoto, sendVoice, sendDocument, sendAudio, downloadTelegramFile, API_BASE } from "#core/channels/telegram/media.js";
 export { sendPhoto, sendVoice, sendDocument, sendAudio };
 
 // ---------- per-channel poller ----------------------------------------------

package/src/host/daemon/routines-scheduler.js

@@ -0,0 +1,64 @@
+// Polling timer that fires due routines. Process-state — needs the daemon
+// alive, has no business being in core/. Delegates the actual work to
+// core/routines/runner.js so CLI / HTTP / web / mcp-server / scripts can
+// invoke the same runner without depending on this file.
+import { getDueRoutines } from "#core/stores/routines.js";
+import { runRoutineNow } from "#core/routines/runner.js";
+import { nowIso } from "#core/util/time.js";
+
+const TICK_MS = 5_000;
+
+export class RoutineScheduler {
+  constructor({ projects, plugins, registries, globalConfig, log }) {
+    this.projects = projects;
+    this.plugins = plugins;
+    this.registries = registries;
+    this.globalConfig = globalConfig;
+    this.log = log || (() => {});
+    this._timer = null;
+    this._running = false;
+  }
+
+  start() {
+    if (this._timer) return;
+    this._timer = setInterval(
+      () => this._tick().catch((e) => this.log(`routines tick error: ${e.message}`)),
+      TICK_MS
+    );
+    this._timer.unref?.();
+  }
+
+  stop() {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+  }
+
+  async _tick() {
+    if (this._running) return;
+    this._running = true;
+    try {
+      const nowStr = nowIso();
+      for (const proj of this.projects.list().map((p) => this.projects.get(p.id))) {
+        if (!proj) continue;
+        const due = getDueRoutines(proj.storagePath, nowStr);
+        for (const r of due) {
+          this.log(`routine ${r.name} (${r.kind}) firing in project #${proj.id}`);
+          await runRoutineNow(
+            {
+              project: proj,
+              projects: this.projects,
+              plugins: this.plugins,
+              registries: this.registries,
+              globalConfig: this.globalConfig,
+            },
+            r
+          );
+        }
+      }
+    } finally {
+      this._running = false;
+    }
+  }
+}

package/src/host/daemon/smoke.js

@@ -9,6 +9,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { ProjectManager } from "./db.js";
 import { McpRegistry } from "#core/mcp/runner.js";
+import { agentsMdFile, apcProjectFile } from "#core/apc/paths.js";
 import { readAgents } from "#core/apc/parser.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -23,8 +24,8 @@ const EXAMPLE_CANDIDATES = [
   path.resolve(__dirname, "..", "..", "..", "..", "apc", "examples", "my-first-project"),
 ];
 const EXAMPLE = EXAMPLE_CANDIDATES.find((p) =>
-  fs.existsSync(path.join(p, "AGENTS.md")) &&
-  fs.existsSync(path.join(p, ".apc", "project.json"))
+  fs.existsSync(agentsMdFile(p)) &&
+  fs.existsSync(apcProjectFile(p))
 );
 
 function assert(cond, msg) {

package/src/host/daemon/whisper-server.js

@@ -0,0 +1,225 @@
+// Subprocess lifecycle for the persistent whisper-server.py.
+//
+// Owns:
+//   - the Python child process (spawn, health-watch, kill on shutdown)
+//   - port collision recovery (kill an orphan listener and retry)
+//   - daemon-boot preload + warmup + graceful teardown
+//
+// Does NOT do the actual transcription — that's an HTTP call to localhost
+// and lives in core/voice/transcription.js. The port number is the single
+// piece of shared state and is exported from core; this file imports it.
+import { spawn, exec } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  WHISPER_LOCAL_PORT,
+  DEFAULT_LOCAL,
+  getConfig,
+} from "#core/voice/transcription.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const WHISPER_SERVER = path.join(__dirname, "whisper-server.py");
+
+let _serverProcess = null;
+let _serverModel = null;
+
+function _sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function _isServerHealthy() {
+  try {
+    const res = await fetch(`http://127.0.0.1:${WHISPER_LOCAL_PORT}/health`, {
+      signal: AbortSignal.timeout(800),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function _serverModelName() {
+  try {
+    const res = await fetch(`http://127.0.0.1:${WHISPER_LOCAL_PORT}/health`, {
+      signal: AbortSignal.timeout(800),
+    });
+    if (!res.ok) return null;
+    const j = await res.json();
+    return j?.model || null;
+  } catch {
+    return null;
+  }
+}
+
+async function _findListenerPid() {
+  return new Promise((resolve) => {
+    exec(`lsof -ti tcp:${WHISPER_LOCAL_PORT} -sTCP:LISTEN`, (err, stdout) => {
+      if (err || !stdout) return resolve(null);
+      const candidates = stdout.trim().split("\n")
+        .map(s => parseInt(s, 10))
+        .filter(n => Number.isFinite(n) && n !== process.pid);
+      resolve(candidates[0] || null);
+    });
+  });
+}
+
+async function _killOrphanWhisper() {
+  try {
+    await fetch(`http://127.0.0.1:${WHISPER_LOCAL_PORT}/shutdown`, {
+      method: "POST", signal: AbortSignal.timeout(1000),
+    });
+    await _sleep(600);
+  } catch {}
+  const pid = await _findListenerPid();
+  if (pid && pid !== process.pid) {
+    try { process.kill(pid, "SIGTERM"); } catch {}
+    await _sleep(400);
+    try { process.kill(pid, 0); try { process.kill(pid, "SIGKILL"); } catch {} } catch {}
+    await _sleep(300);
+  }
+}
+
+export async function ensureWhisperServer(opts) {
+  const model = opts.model || DEFAULT_LOCAL.model;
+
+  if (_serverProcess && _serverModel === model) {
+    if (await _isServerHealthy()) return;
+    _serverProcess = null;
+    _serverModel = null;
+  }
+
+  if (!_serverProcess) {
+    const existing = await _serverModelName();
+    if (existing === model) {
+      _serverModel = model;
+      return;
+    }
+    if (existing) {
+      await _killOrphanWhisper();
+    }
+  }
+
+  if (_serverProcess) {
+    try { _serverProcess.kill(); } catch {}
+    _serverProcess = null;
+    _serverModel = null;
+    await _sleep(300);
+  }
+
+  await _spawnWhisper(opts, model, /* retried */ false);
+}
+
+async function _spawnWhisper(opts, model, retried) {
+  const args = [
+    WHISPER_SERVER,
+    "--port", String(WHISPER_LOCAL_PORT),
+    "--model", model,
+    "--device", String(opts.device || DEFAULT_LOCAL.device),
+    "--compute-type", String(opts.compute_type || DEFAULT_LOCAL.compute_type),
+    "--idle-minutes", String(opts.idle_minutes ?? DEFAULT_LOCAL.idle_minutes),
+  ];
+
+  const proc = spawn("python3", args, {
+    stdio: ["ignore", "pipe", "inherit"],
+    detached: false,
+  });
+
+  _serverProcess = proc;
+  _serverModel = model;
+
+  proc.on("exit", () => {
+    if (_serverProcess === proc) {
+      _serverProcess = null;
+      _serverModel = null;
+    }
+  });
+
+  try {
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error("whisper-server startup timed out (15s)")),
+        15_000
+      );
+      let buf = "";
+      proc.stdout.on("data", (chunk) => {
+        buf += chunk.toString();
+        const nl = buf.indexOf("\n");
+        if (nl === -1) return;
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        clearTimeout(timeout);
+        try {
+          const msg = JSON.parse(line);
+          if (msg.status === "error") return reject(new Error(msg.error || "whisper-server error"));
+          resolve();
+        } catch {
+          resolve();
+        }
+      });
+      proc.on("exit", (code) => {
+        clearTimeout(timeout);
+        reject(new Error(`whisper-server exited (code ${code}) before becoming ready`));
+      });
+    });
+  } catch (e) {
+    const msg = e.message || "";
+    if (!retried && /address already in use|errno 48|eaddrinuse/i.test(msg)) {
+      _serverProcess = null;
+      _serverModel = null;
+      await _killOrphanWhisper();
+      return _spawnWhisper(opts, model, /* retried */ true);
+    }
+    throw e;
+  }
+}
+
+export async function preloadWhisperServer(log = console.log) {
+  try {
+    const cfg = await getConfig();
+    if (cfg.provider === "openai") return;
+    log(`whisper: preloading model "${cfg.local.model}" on port ${WHISPER_LOCAL_PORT}…`);
+    await ensureWhisperServer(cfg.local);
+    log(`whisper: ready on port ${WHISPER_LOCAL_PORT} (model: ${_serverModel})`);
+  } catch (e) {
+    log(`whisper: preload failed — ${e.message} (will retry lazily on first request)`);
+  }
+}
+
+export async function warmupWhisper() {
+  try {
+    const cfg = await getConfig();
+    if (cfg.provider === "openai") return { ok: true, provider: "openai", loaded: false };
+    await ensureWhisperServer(cfg.local);
+    let loaded = false;
+    try {
+      const r = await fetch(`http://127.0.0.1:${WHISPER_LOCAL_PORT}/warmup`, {
+        signal: AbortSignal.timeout(40_000),
+      });
+      const j = await r.json().catch(() => ({}));
+      loaded = !!j.loaded;
+    } catch {}
+    return { ok: true, provider: "local", model: _serverModel, loaded };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+export async function shutdownWhisperServer() {
+  if (_serverProcess) {
+    try { _serverProcess.kill(); } catch {}
+    _serverProcess = null;
+    _serverModel = null;
+  } else {
+    try {
+      await fetch(`http://127.0.0.1:${WHISPER_LOCAL_PORT}/shutdown`, {
+        method: "POST", signal: AbortSignal.timeout(500),
+      });
+    } catch {}
+  }
+}
+
+export const WHISPER_PATHS = {
+  whisper_server: WHISPER_SERVER,
+  port: WHISPER_LOCAL_PORT,
+};

package/src/interfaces/cli/branding.js

@@ -0,0 +1,53 @@
+// APX CLI branding — a consistent "you're running APX vX" mark on every command.
+//
+// Two shapes:
+//   apxBanner(version, subtitle)  big ASCII wordmark for branding-heavy moments
+//                                 (onboarding, top-level entry). Loud on purpose.
+//   apxHeader(version, subtitle)  one-line "▸ APX CLI · vX · <subtitle>" for the
+//                                 everyday commands. Quiet, never in the way.
+//
+// Both write to STDERR so they never pollute piped stdout (`apx exec … | jq`,
+// `apx config show > file`). Like mascot.js, they always print (so the mark is
+// truly on every run), and self-suppress only when APX_QUIET / APX_NO_BANNER is
+// set — the escape hatch for scripts and CI.
+//
+// Color: reuses raw ANSI like mascot.js. Honors NO_COLOR.
+
+const NO_COLOR = !!process.env.NO_COLOR;
+const c = (code) => (s) => (NO_COLOR ? s : `\x1b[${code}m${s}\x1b[0m`);
+const B = c("1");
+const DI = c("2");
+const GR = c("32");
+const CY = c("36");
+const WH = c("97");
+
+function suppressed() {
+  return !!(process.env.APX_NO_BANNER || process.env.APX_QUIET);
+}
+
+// Compact, single-line header. The default for everyday subcommands.
+//   ▸ APX CLI · v1.34.0 · skills inspector
+export function apxHeader(version, subtitle = "") {
+  if (suppressed()) return;
+  const tag = `${GR("▸")} ${B(WH("APX"))} ${DI("CLI")}`;
+  const ver = DI(`v${version}`);
+  const sub = subtitle ? `  ${DI("·")}  ${CY(subtitle)}` : "";
+  process.stderr.write(`\n${tag}  ${DI("·")}  ${ver}${sub}\n\n`);
+}
+
+// Big ASCII wordmark for branding-heavy commands.
+export function apxBanner(version, subtitle = "") {
+  if (suppressed()) return;
+  const g = (s) => GR(s);
+  const lines = [
+    "",
+    `  ${g("█████╗ ██████╗ ██╗  ██╗")}`,
+    `  ${g("██╔══██╗██╔══██╗╚██╗██╔╝")}`,
+    `  ${g("███████║██████╔╝ ╚███╔╝ ")}   ${B(WH("Agent Project Context"))}`,
+    `  ${g("██╔══██║██╔═══╝  ██╔██╗ ")}   ${DI(`v${version}`)}`,
+    `  ${g("██║  ██║██║     ██╔╝ ██╗")}${subtitle ? `   ${CY(subtitle)}` : ""}`,
+    `  ${g("╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝")}`,
+    "",
+  ];
+  process.stderr.write(lines.join("\n") + "\n");
+}

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

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findApfRoot, readAgents, readVaultAgents, readVaultAgent, VAULT_DIR, SLUG_RE } from "#core/apc/parser.js";
+import { apcAgentFile } from "#core/apc/paths.js";
 import { writeAgentFile, writeVaultAgentFile, removeVaultAgent, restoreVaultAgent, addImportedAgent, ensureAgentDir } from "#core/apc/scaffold.js";
 import { ensureAgentRuntimeDir, agentMemoryPath } from "#core/agent/memory.js";
 import { http } from "../http.js";
@@ -194,7 +195,7 @@ export async function cmdAgentImport(args) {
     throw new Error(`"${slug}" not found in vault. Available: ${available}`);
   }
 
-  const alreadyLocal = fs.existsSync(path.join(root, ".apc", "agents", `${slug}.md`));
+  const alreadyLocal = fs.existsSync(apcAgentFile(root, slug));
   if (alreadyLocal && !args.flags.force) {
     console.log(dim(`  "${slug}" already has a local definition. Use --force to overwrite.`));
     return;
@@ -202,7 +203,7 @@ export async function cmdAgentImport(args) {
 
   if (args.flags.copy) {
     // Copy .md into project so user can edit locally
-    fs.copyFileSync(vaultPath, path.join(root, ".apc", "agents", `${slug}.md`));
+    fs.copyFileSync(vaultPath, apcAgentFile(root, slug));
     console.log(`\n  ${bold(slug)} copied from vault to project (now local)\n`);
   } else {
     // Just register as imported — reads from vault at runtime

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

@@ -2,12 +2,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findApfRoot } from "#core/apc/parser.js";
+import { apcCommandsDir } from "#core/apc/paths.js";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 
-function commandsDir(root) {
-  return path.join(root, ".apc", "commands");
-}
+const commandsDir = apcCommandsDir;
 
 function listCommandFiles(root) {
   const dir = commandsDir(root);

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

@@ -1,9 +1,13 @@
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
+import { CHANNELS } from "#core/constants/channels.js";
 
 // Channels that live in ~/.apx/messages/<channel>/ (global, cross-project).
 // Everything else is project-scoped.
-const GLOBAL_CHANNELS = new Set(["telegram", "direct", "whatsapp"]);
+// DIRECT and WHATSAPP are still placeholders (no plugin lives behind them
+// yet) but they're real channel ids — when those plugins land, message
+// lookup already routes them as project-less / global.
+const GLOBAL_CHANNELS = new Set([CHANNELS.TELEGRAM, CHANNELS.DIRECT, CHANNELS.WHATSAPP]);
 
 function isGlobalChannel(channel) {
   return channel && GLOBAL_CHANNELS.has(channel);
@@ -71,7 +75,7 @@ function printChatRows(rows) {
 }
 
 export async function cmdMessagesChat(args) {
-  const channel = args.flags.channel && args.flags.channel !== true ? args.flags.channel : "telegram";
+  const channel = args.flags.channel && args.flags.channel !== true ? args.flags.channel : CHANNELS.TELEGRAM;
   const n = args.flags.n || args.flags.last || "50";
   const isGlobal = args.flags.global || isGlobalChannel(channel);