@agentprojectcontext/apx 1.77.2 → 1.78.0

package/src/core/http-tools/search.js

@@ -3,7 +3,7 @@
 //   2. Brave Search API (requires BRAVE_API_KEY env)
 //   3. Puppeteer Google fallback (requires puppeteer installed)
 //
-// Endpoint: POST /tools/search
+// Endpoint: POST /api/tools/search
 // Body: { query, mode: "auto"|"ddg"|"brave"|"browser", limit? }
 
 import { browser_navigate, browser_get_text, browser_evaluate } from "./browser.js";
@@ -302,7 +302,7 @@ export function buildSearchRouter(express) {
     }
   });
 
-  // GET convenience: /tools/search?q=...&mode=auto&limit=5
+  // GET convenience: /api/tools/search?q=...&mode=auto&limit=5
   router.get("/", async (req, res) => {
     const { q, query, mode, limit } = req.query;
     try {

package/src/core/identity/self.js

@@ -1,23 +1,22 @@
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
+import { IDENTITY_PATH } from "../config/paths.js";
+
+export { IDENTITY_PATH };
 import { SUPERAGENT_ACTOR_ID } from "../constants/actors.js";
+import { readJson } from "#core/util/json-file.js";
 
 // Re-export so callers that already imported the actor id from here keep
 // working. The single source of truth lives in core/constants/actors.js.
 export { SUPERAGENT_ACTOR_ID };
 
-export const IDENTITY_PATH = path.join(os.homedir(), ".apx", "identity.json");
+
 
 // Shown when no persona is configured yet. Brand of the app, not a persona.
 export const SUPERAGENT_DISPLAY_FALLBACK = "APX";
 
 export function readIdentity() {
-  try {
-    return JSON.parse(fs.readFileSync(IDENTITY_PATH, "utf8"));
-  } catch {
-    return null;
-  }
+  return readJson(IDENTITY_PATH, null);
 }
 
 // Resolve the super-agent's DISPLAY name (the persona shown to users). Order:

package/src/core/identity/telegram.js

@@ -37,7 +37,7 @@ export function resolveSender({ cfg, channelName, from, chatType }) {
   const isOwner =
     channel?.owner_user_id != null &&
     String(channel.owner_user_id) === String(userId);
-  const role = isOwner ? "owner" : contact?.role || "guest";
+  const role = isOwner ? SENDER_ROLES.OWNER : contact?.role || SENDER_ROLES.GUEST;
   return {
     userId,
     username,
@@ -115,11 +115,11 @@ export function registerSender({ cfg, channelName, from, chatType }) {
   if (kind === "claim") {
     upsertTelegramChannel(disk, channelName, { owner_user_id: userId });
     upsertContact(disk, userId, {
-      name, username, role: "owner", first_seen: now, last_seen: now,
+      name, username, role: SENDER_ROLES.OWNER, first_seen: now, last_seen: now,
     });
   } else if (kind === "guest") {
     upsertContact(disk, userId, {
-      name, username, role: "guest", first_seen: now, last_seen: now,
+      name, username, role: SENDER_ROLES.GUEST, first_seen: now, last_seen: now,
     });
   } else {
     upsertContact(disk, userId, { last_seen: now });

package/src/core/logging.js

@@ -1,14 +1,15 @@
 import fs from "node:fs";
-import path from "node:path";
-import { APX_HOME } from "./config/index.js";
 import { maskSecretValues } from "./config/secret-values.js";
+import { LOG_DIR, APX_LOG_PATH, ERROR_TRACE_PATH } from "./config/paths.js";
+
+// Canonical definitions live in config/paths.js; re-exported so the existing
+// `import { APX_LOG_PATH } from "#core/logging.js"` call sites keep working.
+export { LOG_DIR, APX_LOG_PATH, ERROR_TRACE_PATH };
 
-export const LOG_DIR = path.join(APX_HOME, "logs");
-export const ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
 // Unified daemon log. Every module (daemon, telegram, whisper, super-agent,
 // tools, desktop) writes here with one consistent format so the user can
 // follow the whole system from a single tail.
-export const APX_LOG_PATH = path.join(LOG_DIR, "apx.log");
+
 
 const SECRET_KEY_RE = /(token|secret|password|api[_-]?key|authorization|bot[_-]?token)/i;
 

package/src/core/mcp/sources.js

@@ -34,12 +34,14 @@
 // instead, then to true.
 
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { apxHome } from "#core/config/paths.js";
 import { apcMcpsFile } from "#core/apc/paths.js";
+import { readJson } from "#core/util/json-file.js";
 
-const APX_HOME = path.join(os.homedir(), ".apx");
-const GLOBAL_MCPS_FILE = path.join(APX_HOME, "mcps.json");
+
+// Resolved per call: the global store must follow APX_HOME if it moves.
+const globalMcpsFile = () => path.join(apxHome(), "mcps.json");
 const RUNTIME_MCPS_FILENAME = "mcps.json";
 
 // Project-relative sources (file path resolved against projectRoot).
@@ -63,15 +65,9 @@ export const SOURCES = [
   { id: "global",  file: "~/.apx/mcps.json", key: "mcpServers", scope: "global" },
 ];
 
-function readJsonSafe(absPath) {
-  if (!absPath) return null;
-  if (!fs.existsSync(absPath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(absPath, "utf8"));
-  } catch {
-    return null;
-  }
-}
+// readJsonSafe is the shared readJson(); secrets are written with SECRET_MODE.
+const readJsonSafe = (absPath) => readJson(absPath, null);
+
 
 // Resolve the runtime mcps.json path for a given project. `storagePath` is the
 // project's ~/.apx/projects/<apxId>/ directory.
@@ -81,7 +77,7 @@ export function runtimeMcpsPath(storagePath) {
 }
 
 export function globalMcpsPath() {
-  return GLOBAL_MCPS_FILE;
+  return globalMcpsFile();
 }
 
 // Aggregate all MCP sources for a project, in priority order.
@@ -119,7 +115,7 @@ export function loadAll(projectRoot, opts = {}) {
   // last. global
   pipeline.push({
     id: "global",
-    abs: GLOBAL_MCPS_FILE,
+    abs: globalMcpsFile(),
     key: "mcpServers",
   });
 
@@ -229,7 +225,7 @@ export function writeRuntimeMcps(storagePath, json) {
 // ---------------------------------------------------------------------------
 
 export function readGlobalMcps() {
-  const p = GLOBAL_MCPS_FILE;
+  const p = globalMcpsFile();
   if (!fs.existsSync(p)) return { mcpServers: {} };
   try {
     const json = JSON.parse(fs.readFileSync(p, "utf8"));
@@ -241,7 +237,7 @@ export function readGlobalMcps() {
 }
 
 export function writeGlobalMcps(json) {
-  const p = GLOBAL_MCPS_FILE;
+  const p = globalMcpsFile();
   fs.mkdirSync(path.dirname(p), { recursive: true });
   fs.writeFileSync(p, JSON.stringify(json, null, 2) + "\n");
 }

package/src/core/memory/indexer.js

@@ -23,6 +23,7 @@ import { GLOBAL_MESSAGES_DIR, APX_HOME } from "../config/index.js";
 import { SELF_MEMORY_PATH, parseSelfMemoryEntries } from "../agent/self-memory.js";
 import { apcMemoryFile } from "../apc/paths.js";
 import { embedBatch, embedOne } from "./embeddings.js";
+import { readJson } from "#core/util/json-file.js";
 
 export const CURSOR_PATH = path.join(APX_HOME, "memory-cursor.json");
 
@@ -48,11 +49,7 @@ function readIfExists(p) {
 }
 
 function readCursor(cursorPath) {
-  try {
-    return JSON.parse(fs.readFileSync(cursorPath, "utf8"));
-  } catch {
-    return { channels: {} };
-  }
+  return readJson(cursorPath, { channels: {} });
 }
 
 function writeCursor(cursorPath, cursor) {

package/src/core/profiles/lifecycle.js

@@ -23,9 +23,7 @@ import {
 } from "../stores/routines.js";
 
 import {
-  PROFILES_DIR,
   MANIFEST_FILE,
-  CONFIG_SCHEMA_FILE,
   PROFILE_ID_RE,
   userProfileDir,
 } from "./paths.js";

package/src/core/profiles/store.js

@@ -29,14 +29,9 @@ import {
   promptFileFor,
 } from "./paths.js";
 import { schemaDefaults } from "./manifest.js";
+import { readJson } from "#core/util/json-file.js";
+
 
-function readJson(file) {
-  try {
-    return JSON.parse(fs.readFileSync(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
 
 function readDirIds(dir) {
   if (!fs.existsSync(dir)) return [];

package/src/core/routines/runner.js

@@ -1,5 +1,5 @@
 // Routine execution — the domain logic any caller can invoke (daemon
-// scheduler, CLI `apx routine run`, HTTP `/projects/:pid/routines/:name/run`,
+// scheduler, CLI `apx routine run`, HTTP `/api/projects/:pid/routines/:name/run`,
 // MCP server, future scripts). The runner orchestrates a 3-phase pipeline:
 //   1. pre_commands  (shell)
 //   2. handler       (heartbeat / exec_agent / super_agent / telegram / shell)

package/src/core/runtime-skills/apx-agency-agents/SKILL.md

@@ -68,7 +68,7 @@ import_agent({ slug: "cody-developer", project: "<name-or-path>" })
 
 ## Web equivalents
 
-Agent defaults tab (`/p/0/agent-defaults`): same CRUD — "New" (POST `/agents/vault`), per-card "Edit" (PATCH `/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), "Show removed" toggle with "Restore" button.
+Agent defaults tab (`/p/0/agent-defaults`): same CRUD — "New" (POST `/api/agents/vault`), per-card "Edit" (PATCH `/api/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), "Show removed" toggle with "Restore" button.
 
 ## Which agent to use
 
@@ -107,7 +107,7 @@ is_master: false
 |---|---|
 | `role` | Shown in CLI/web; appears as "Role: …" in prompt. |
 | `model` | Default model for engine routing. |
-| `description` | Shown in `/agents/vault` and AgentDefaultsTab cards. |
+| `description` | Shown in `/api/agents/vault` and AgentDefaultsTab cards. |
 | `language` | Adds "Default language: <code>" to system prompt. |
 | `skills` | Per-agent skill names; bodies loaded by skill resolution. |
 | `tools` | Tool hints; actual callable tools depend on invocation surface. |

package/src/core/runtime-skills/apx-profile/SKILL.md

@@ -113,9 +113,9 @@ install. Check the real number with `apx profile show <id>` or
 
 ## HTTP
 
-`GET /profiles` · `GET /profiles/:id` (includes `preview`) · `GET /profiles/doctor` ·
-`POST /profiles/install` · `POST /profiles/use` · `POST /profiles/off` ·
-`PATCH /profiles/config` · `DELETE /profiles/:id`
+`GET /api/profiles` · `GET /api/profiles/:id` (includes `preview`) · `GET /api/profiles/doctor` ·
+`POST /api/profiles/install` · `POST /api/profiles/use` · `POST /api/profiles/off` ·
+`PATCH /api/profiles/config` · `DELETE /api/profiles/:id`
 
 ## Gotchas
 

package/src/core/runtime-skills/apx-project/SKILL.md

@@ -36,7 +36,7 @@ apx project config unset <project> super_agent.model               # back to glo
 apx project config edit <project>                                  # opens $EDITOR on project_only JSON
 ```
 
-Every `project config` write triggers `POST /admin/reload` so the daemon picks up changes without restart.
+Every `project config` write triggers `POST /api/admin/reload` so the daemon picks up changes without restart.
 
 ## `<project>` argument resolution
 

package/src/core/runtime-skills/apx-task/SKILL.md

@@ -79,14 +79,14 @@ apx task drop t_abc            # "no longer needed; archive without completion"
 ## Endpoint surface
 
 ```
-GET    /projects/:pid/tasks                  ?state=open|done|dropped|all&tag=X&agent=Y&due_before=ISO&limit=N
-POST   /projects/:pid/tasks                  { title, body?, tags?, due?, agent?, source?, meta? }
-GET    /projects/:pid/tasks/:id
-PATCH  /projects/:pid/tasks/:id              { patch: {...} }
-POST   /projects/:pid/tasks/:id/done         { by? }
-POST   /projects/:pid/tasks/:id/drop         { by? }
-POST   /projects/:pid/tasks/:id/reopen
-GET    /projects/:pid/tasks-summary          → { open, done, dropped, overdue, total }
+GET    /api/projects/:pid/tasks                  ?state=open|done|dropped|all&tag=X&agent=Y&due_before=ISO&limit=N
+POST   /api/projects/:pid/tasks                  { title, body?, tags?, due?, agent?, source?, meta? }
+GET    /api/projects/:pid/tasks/:id
+PATCH  /api/projects/:pid/tasks/:id              { patch: {...} }
+POST   /api/projects/:pid/tasks/:id/done         { by? }
+POST   /api/projects/:pid/tasks/:id/drop         { by? }
+POST   /api/projects/:pid/tasks/:id/reopen
+GET    /api/projects/:pid/tasks-summary          → { open, done, dropped, overdue, total }
 ```
 
 ## Don't

package/src/core/runtime-skills/apx-telegram/SKILL.md

@@ -71,17 +71,17 @@ apx telegram send "text" --chat 123456789
 apx telegram send "text" --interrupt            # bypass pending-agent queue (also: --force)
 
 # Media (daemon HTTP API — no dedicated CLI subcommand yet)
-curl -X POST http://127.0.0.1:7430/telegram/send_photo \
+curl -X POST http://127.0.0.1:7430/api/telegram/send_photo \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
   -d '{"photo":"/abs/path.png","caption":"...","channel":"clientes"}'
-curl -X POST http://127.0.0.1:7430/telegram/send_voice \
+curl -X POST http://127.0.0.1:7430/api/telegram/send_voice \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
   -d '{"audio":"/abs/path.ogg","duration":5,"channel":"default"}'
 ```
 
-Every `channel` CRUD write triggers `POST /admin/reload` so polling picks up the new wiring without restart.
+Every `channel` CRUD write triggers `POST /api/admin/reload` so polling picks up the new wiring without restart.
 
 ## What "pin to project" does
 
@@ -92,7 +92,7 @@ On a message to a channel with `project: "iacrmar"`:
 
 ## What "master agent" does
 
-With `route_to_agent: "reviewer"`, messages go through `/projects/:pid/agents/reviewer/chat` instead of `/super-agent/chat`. The agent's `AGENT.md` + memory is used. No tools (project agents are `exec_agent`-shaped — text in, text out). Single LLM call. Use this for persona channels (reviewer, sales, support) instead of the general assistant. Empty = super-agent (default).
+With `route_to_agent: "reviewer"`, messages go through `/api/projects/:pid/agents/reviewer/chat` instead of `/api/super-agent/chat`. The agent's `AGENT.md` + memory is used. No tools (project agents are `exec_agent`-shaped — text in, text out). Single LLM call. Use this for persona channels (reviewer, sales, support) instead of the general assistant. Empty = super-agent (default).
 
 ## Anti-examples
 

package/src/core/runtime-skills/apx-voice/SKILL.md

@@ -117,16 +117,16 @@ apx voice say "Hello from APX" --provider gemini
 
 ## Unified voice channel
 
-`POST /voice/turn` is one round-trip: send audio (or text), get back `{ user_text, reply_text, reply_audio_path }`. STT in, agent loop, TTS out. For overlay and future "voice room" clients.
+`POST /api/voice/turn` is one round-trip: send audio (or text), get back `{ user_text, reply_text, reply_audio_path }`. STT in, agent loop, TTS out. For overlay and future "voice room" clients.
 
 ```bash
-curl -X POST http://127.0.0.1:7430/voice/turn \
+curl -X POST http://127.0.0.1:7430/api/voice/turn \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
   -d '{"text":"Hello APX","channel":"voice"}'
 ```
 
-Telegram voice messages and overlay mascot still have their own STT pipelines — they don't go through `/voice/turn` yet.
+Telegram voice messages and overlay mascot still have their own STT pipelines — they don't go through `/api/voice/turn` yet.
 
 ## Anti-examples
 
@@ -146,4 +146,4 @@ Telegram voice messages and overlay mascot still have their own STT pipelines
 
 - Paste base64 audio into chat. Use file paths or `send_voice` / `send_audio`.
 - Switch providers mid-routine without testing — quality varies a lot across Piper voices and cloud engines.
-- Expect TTS streaming yet — `apx voice say` returns a complete file. `/tts/stream` is open work.
+- Expect TTS streaming yet — `apx voice say` returns a complete file. `/api/tts/stream` is open work.

package/src/core/runtimes/detect.js

@@ -1,8 +1,8 @@
 // Best-effort detection of installed agent CLIs and LLM runners.
 // We just probe the binary with `--version` (or equivalent) and don't fail if
 // it isn't there — caller decides what to do with absence.
-import { runProcess } from "#host/daemon/runtimes/_spawn.js";
-import { resolveAntigravityCli } from "#host/daemon/runtimes/antigravity.js";
+import { runProcess } from "./_spawn.js";
+import { resolveAntigravityCli } from "./antigravity.js";
 
 const PROBES = [
   // Coding-agent CLIs (runtimes/)