@agentprojectcontext/apx 1.77.2 → 1.78.0

package/README.md

@@ -11,7 +11,7 @@
 <p align="center">
   <a href="https://agentprojectcontext.github.io/apx/"><img src="https://img.shields.io/badge/Website-agentprojectcontext.github.io-3fb950?style=flat-square&logo=googlechrome&logoColor=white" alt="Website"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-3fb950?style=flat-square" alt="License: MIT"></a>
-  <img src="https://img.shields.io/badge/Node.js-20%2B-3fb950?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 20+">
+  <img src="https://img.shields.io/badge/Node.js-22%2B-3fb950?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 22+">
   <a href="https://github.com/agentprojectcontext/agentprojectcontext"><img src="https://img.shields.io/badge/Protocol-APC-3fb950?style=flat-square" alt="APC protocol"></a>
 </p>
 
@@ -49,7 +49,7 @@ APX is opinionated about storage: the filesystem is the source of truth. Project
   █    ‿    █
    ▀███████▀
 </pre>
-<sub>Meet <b>Roby</b> — your project's super-agent. He greets you across the <code>apx</code> CLI and the web admin.</sub>
+<sub>The <b>super-agent</b> — it greets you across the <code>apx</code> CLI and the web admin.</sub>
 </div>
 
 ## Quick start
@@ -77,7 +77,8 @@ apx messages tail
 ## Examples
 
 Real commands — copy one, point it at an agent like `sofia`, and APX routes it to the right
-runtime. The session and memory land in `.apc/`.
+runtime. The session transcript and its summary land in `~/.apx/`; only curated
+memory and the agent definition live in `.apc/`.
 
 | What | Command |
 |------|---------|
@@ -90,7 +91,7 @@ runtime. The session and memory land in `.apc/`.
 
 ## Use cases
 
-- **Review PRs across any runtime** — point an agent at your repo; APX routes to Claude Code and falls back to Codex or OpenCode if one isn't installed. The session and its summary land in `.apc/`.
+- **Review PRs across any runtime** — point an agent at your repo; APX routes to Claude Code and falls back to Codex or OpenCode if one isn't installed. The session and its summary land in `~/.apx/`.
 - **Operate your agents from Telegram** — talk to project agents from your phone. Identity roles gate who can do what, and every message is logged per channel for a full audit trail.
 - **Memory that lives in your repo** — curated, per-agent memory is plain markdown, committed and reviewable alongside your code. No vendor database, no hidden state, no lock-in.
 - **Run the same prompt across engines** — send one prompt through Anthropic, OpenAI, Gemini or a local Ollama model with `apx exec`, configured per project or globally.
@@ -101,7 +102,7 @@ runtime. The session and memory land in `.apc/`.
 npm install -g @agentprojectcontext/apx
 ```
 
-Requires Node.js 20+. The daemon starts automatically on first `apx` call.
+Requires Node.js 22+. The daemon starts automatically on first `apx` call.
 
 ## Web admin
 
@@ -178,12 +179,21 @@ Activity belongs to APX runtime state, not `.apc/`. Message storage is local to
 JSONL messages include `type` (`user`, `agent`, `tool`, or `system`) plus `actor_id`, so chat views
 can distinguish Telegram users from APX agents and future subagents.
 
+A **channel** is the surface a turn arrived on. The canonical list lives in
+`src/core/constants/channels.js`; `voice` is a *mode*, not a channel.
+
 | Channel | What it captures |
 |---------|-----------------|
-| `runtime` | `apx run` invocations (prompt in, response out) |
-| `a2a` | Agent-to-agent calls made from within a session |
-| `telegram` | Telegram bot messages (stored globally in `~/.apx/messages/telegram/`) |
-| `exec` | Quick `apx exec` calls |
+| `cli` | `apx exec` / `apx run` from the terminal |
+| `telegram` | Telegram bot messages |
+| `api` | Direct daemon HTTP calls |
+| `web` | The admin panel's main chat |
+| `web_sidebar` | The panel's side assistant |
+| `web_code` | The panel's coding surface |
+| `code` | `apx code` sessions |
+| `deck` | The tablet/phone dashboard |
+| `desktop` | The floating voice capsule (always voice mode) |
+| `routine` | Scheduled routine runs |
 
 ## Runtimes
 
@@ -193,6 +203,10 @@ can distinguish Telegram users from APX agents and future subagents.
 | `codex` | OpenAI Codex CLI via non-interactive `codex exec --sandbox workspace-write --skip-git-repo-check` |
 | `opencode` | OpenCode CLI |
 | `aider` | Aider CLI |
+| `cursor-agent` | Cursor's headless agent |
+| `gemini-cli` | Google Gemini CLI |
+| `qwen-code` | Qwen Code CLI |
+| `antigravity` | Antigravity CLI |
 
 Global APX skill installation also writes named helper skills for `codex-cli`, `claude-code`,
 `opencode-cli`, and `openrouter`. They are intentionally narrow and should activate only when those

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.77.2",
+  "version": "1.78.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -29,16 +29,20 @@
     "!**/*.tsbuildinfo"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
     "start": "node src/host/daemon/index.js",
     "smoke": "node src/host/daemon/smoke.js",
     "test": "node --test --test-reporter=spec tests/*.test.js",
+    "test:ci": "node scripts/test-ci.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck:tui": "node scripts/typecheck-tui.js",
     "build:web": "node scripts/build-web.js",
-    "preflight": "npm test && node scripts/build-web.js && (cd src/interfaces/web && npx --no-install tsc --noEmit)",
+    "preflight": "npm run lint && npm run test:ci && node scripts/build-web.js && (cd src/interfaces/web && npx --no-install tsc --noEmit) && npm run typecheck:tui",
     "upgrade": "pnpm install && pnpm add -g .",
-    "prepare": "node scripts/install-githooks.js",
+    "prepare": "node scripts/install-githooks.js && node scripts/sync-apc-skill.js",
     "prepack": "node scripts/sync-apc-skill.js && node scripts/build-web.js",
     "postinstall": "node src/interfaces/cli/postinstall.js",
     "smoke:seam": "node --test --test-reporter=spec tests/smoke/*.smoke.js"
@@ -50,26 +54,20 @@
     "@opentui/solid": "^0.2.16",
     "@solid-primitives/event-bus": "^1.1.3",
     "@solid-primitives/scheduled": "^1.5.2",
-    "chalk": "^5.6.2",
-    "cli-cursor": "^5.0.0",
     "cli-sound": "^1.1.3",
     "clipboardy": "^4.0.0",
     "cron-parser": "^5.5.0",
     "effect": "^3.21.2",
-    "esbuild-plugin-solid": "^0.6.0",
     "express": "^4.21.0",
     "fuzzysort": "^3.1.0",
-    "iconv-lite": "^0.6.3",
     "node-fetch": "^3.3.2",
     "open": "^10.1.2",
     "opentui-spinner": "^0.0.6",
     "qrcode-terminal": "^0.12.0",
-    "raw-body": "^3.0.0",
-    "react": "^19.2.0",
     "remeda": "^2.21.0",
-    "safer-buffer": "^2.1.2",
     "solid-js": "^1.9.13",
-    "ws": "^8.21.3"
+    "ws": "^8.21.3",
+    "zod": "^4.4.3"
   },
   "optionalDependencies": {
     "better-sqlite3": "^11.3.0",
@@ -78,12 +76,14 @@
     "sqlite-vec": "^0.1.6"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^25.7.0",
     "conventional-changelog-conventionalcommits": "^9.3.1",
     "electron": "^33.4.11",
     "esbuild": "^0.28.0",
+    "eslint": "^9.39.5",
     "typescript": "^6.0.3"
   },
   "keywords": [

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

@@ -17,6 +17,7 @@ import {
   buildUserContextBlock,
   buildSegmentDiscipline,
 } from "./prompt-builder.js";
+import { readJson } from "#core/util/json-file.js";
 
 // Cap the injected agent body so an over-long authored file can't blow the
 // token budget. Mirrors PROJECT_AGENTS_MAX_CHARS for AGENTS.md.
@@ -30,8 +31,8 @@ function listField(value) {
 function projectName(project) {
   if (project?.name) return project.name;
   try {
-    const meta = JSON.parse(fs.readFileSync(apcProjectFile(project.path), "utf8"));
-    return meta.name || project.path?.split("/").pop() || "";
+    const meta = readJson(apcProjectFile(project.path), {});
+    return meta?.name || project.path?.split("/").pop() || "";
   } catch {
     return project?.path?.split("/").pop() || "";
   }

package/src/core/agent/constants.js

@@ -15,10 +15,11 @@ export const MAX_TOOL_ITERS = 10;
 // genuinely exhausts this budget — a rare safety floor, not the default close.
 // Overridable per-deployment via config.super_agent.telegram_max_iters.
 export const TELEGRAM_TOOL_ITERS = 24;
-export const ACK_ONLY_TOOLS = new Set(["send_telegram"]);
+// Defined in tools/names.js, next to the names they reference.
+export { ACK_ONLY_TOOLS, TURN_ENDING_TOOLS } from "./tools/names.js";
 export const MAX_CONSECUTIVE_ACKS = 2;
 // Tools whose semantics REQUIRE handing control back to the user. After the
 // tool runs we break the loop — even under completionContract — because the
 // task literally cannot advance without a human reply. Without this, models
 // under forced toolChoice spam the same question across iterations.
-export const TURN_ENDING_TOOLS = new Set(["ask_questions"]);
+

package/src/core/agent/loop/greeting-guard.js

@@ -0,0 +1,55 @@
+// Collapse repeated greetings inside a single turn.
+//
+// A turn can emit several text segments (pre-tool narration, then the final
+// answer) and weaker models greet in each one, so the user sees "¡Hola Manu!"
+// twice. Keep the first greeting, strip any later one.
+//
+// Belt-and-suspenders over the action-discipline prompt rule: strong models
+// follow that rule, gemini-flash and friends often do not.
+//
+// Extracted from runAgent, where it was two loose variables and a closure among
+// twelve other concerns. As its own object it can be tested directly, which it
+// could not be before.
+// A leading greeting clause: "¡Hola Manu!", "Hola,", "Hi there!", "Buenas tardes…".
+// Intentionally narrow — only the opening salutation up to its first terminator —
+// so we never eat real content.
+// The comma matters. Without it the class ran to the first sentence
+// terminator, so "Hola de nuevo, ya está listo." matched in full and the guard
+// deleted the whole sentence — the opposite of the "never eat real content"
+// intent stated above. Stopping at a comma keeps the vocative ("¡Hola Manu!",
+// "Hola de nuevo,") and leaves the sentence that follows.
+//
+// Known limit: a greeting glued to content with no separator at all
+// ("Hey arranco.") is genuinely ambiguous and is still consumed. That is the
+// rarer shape, and erring toward stripping there matches the original intent.
+export const LEADING_GREETING_RE =
+  /^\s*[¡!]*\s*(hola+|holis?|buenas|buen[oa]s?\s+(d[ií]as|tardes|noches)|hey|hi|hello)\b[^,.!?¡\n]*[,.!?¡]*[\s]*/i;
+
+/** If `text` opens with a greeting, return it with that greeting removed; else null. */
+export function stripLeadingGreeting(text) {
+  const m = String(text).match(LEADING_GREETING_RE);
+  if (!m) return null;
+  return String(text).slice(m[0].length).replace(/^\s+/, "");
+}
+
+/**
+ * @returns {{ apply(text: string): string, greeted: boolean }} `apply` returns
+ *   the text to show the user; call it once per emitted segment, in order.
+ */
+export function createGreetingGuard() {
+  let greeted = false;
+  return {
+    apply(text) {
+      if (!text) return text;
+      if (greeted) {
+        const stripped = stripLeadingGreeting(text);
+        return stripped == null ? text : stripped;
+      }
+      if (LEADING_GREETING_RE.test(text)) greeted = true;
+      return text;
+    },
+    get greeted() {
+      return greeted;
+    },
+  };
+}

package/src/core/agent/loop/side-effects.js

@@ -0,0 +1,52 @@
+// Remembers which world-changing tool calls a turn already made.
+//
+// Weaker models (Gemini especially) re-emit the SAME tool call across
+// iterations — send_telegram three times with identical args, spamming the
+// user. For tools that mutate something we record the (name + args) signature
+// and answer a repeat with a synthetic "already done" instead of running it
+// again. Read-only tools are exempt: they are idempotent and are legitimately
+// repeated (list_tasks before and after a change).
+//
+// This is a user-facing protection, and it used to live as two loose locals
+// inside runAgent alongside eleven other concerns, keyed off an inline array of
+// tool-name literals. The names now come from tools/names.js (see
+// SIDE_EFFECT_TOOLS) and the ledger is its own object, so both halves can be
+// tested without driving a whole agent turn.
+import { SIDE_EFFECT_TOOLS } from "../tools/names.js";
+
+/**
+ * @returns {{
+ *   signature(name: string, args: unknown): string|null,
+ *   seen(sig: string|null): boolean,
+ *   previous(sig: string): unknown,
+ *   record(sig: string|null, result: unknown): void,
+ * }}
+ *   `signature` returns null for read-only tools, which callers treat as
+ *   "never dedupe this".
+ */
+export function createSideEffectLedger() {
+  const executed = new Map();
+
+  return {
+    signature(name, args) {
+      if (!SIDE_EFFECT_TOOLS.has(name)) return null;
+      try {
+        return `${name}:${JSON.stringify(args)}`;
+      } catch {
+        // Circular or otherwise unserializable args: fall back to the tool
+        // name alone. Deduping slightly too eagerly is safer than sending the
+        // same message twice.
+        return `${name}:<unserializable>`;
+      }
+    },
+    seen(sig) {
+      return sig != null && executed.has(sig);
+    },
+    previous(sig) {
+      return executed.get(sig);
+    },
+    record(sig, result) {
+      if (sig != null) executed.set(sig, result);
+    },
+  };
+}

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

@@ -125,19 +125,60 @@ function buildSegmentDiscipline({ channel, voice }) {
 // Project guidance — AGENTS.md of the pinned project, size-capped.
 // ---------------------------------------------------------------------------
 
-export const PROJECT_AGENTS_MAX_CHARS = 6000;
+// Budget guard for a FOREIGN project's AGENTS.md — a project we were merely
+// pointed at should not be able to blow the prompt budget. It is deliberately
+// generous: a real contract runs well past the old 6k cap, and a contract that
+// arrives half-read is worse than none (the agent follows the rules it can see
+// and silently violates the ones it cannot).
+//
+// Two escape hatches, because truncating a contract is never harmless:
+//   - `super_agent.project_agents_max_chars` overrides it; 0 disables the cap.
+//   - The project APX is *running inside* is never capped (see isOwnProject).
+export const PROJECT_AGENTS_MAX_CHARS = 24000;
+
+// The project that owns the running process reads its own contract in full.
+// This is the dogfood case: `apx exec` inside a repo, or the daemon started
+// from it. Capping there truncated APX's own AGENTS.md mid-rule.
+function isOwnProject(projectPath) {
+  try {
+    return path.resolve(projectPath) === path.resolve(process.cwd());
+  } catch {
+    return false;
+  }
+}
+
+function resolveAgentsCap(projectPath, globalConfig) {
+  if (isOwnProject(projectPath)) return 0;
+  const raw = globalConfig?.super_agent?.project_agents_max_chars;
+  if (raw === 0) return 0;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : PROJECT_AGENTS_MAX_CHARS;
+}
+
+// Cut on a line boundary so a rule is never severed mid-sentence, and say what
+// was dropped — a bare "…(truncated)" gives the agent no way to know it is
+// operating on a partial contract.
+function capAgentsText(text, max) {
+  if (!max || text.length <= max) return text;
+  const head = text.slice(0, max);
+  const lastBreak = head.lastIndexOf("\n");
+  const kept = lastBreak > max * 0.5 ? head.slice(0, lastBreak) : head;
+  const dropped = text.length - kept.length;
+  return (
+    `${kept.trimEnd()}\n\n…(AGENTS.md truncated: ${dropped} of ${text.length} characters omitted. ` +
+    `Read the file directly before relying on rules not shown above.)`
+  );
+}
 
-export function buildProjectAgentsBlock(projectPath) {
+export function buildProjectAgentsBlock(projectPath, globalConfig = {}) {
   if (!projectPath) return "";
   try {
     const file = agentsMdFile(projectPath);
     if (!fs.existsSync(file)) return "";
-    let text = fs.readFileSync(file, "utf8").trim();
+    const text = fs.readFileSync(file, "utf8").trim();
     if (!text) return "";
-    if (text.length > PROJECT_AGENTS_MAX_CHARS) {
-      text = text.slice(0, PROJECT_AGENTS_MAX_CHARS) + "\n\n…(AGENTS.md truncated)";
-    }
-    return `# Project guidance (AGENTS.md)\n\nStartup rules for THIS project — follow them:\n\n${text}`;
+    const capped = capAgentsText(text, resolveAgentsCap(projectPath, globalConfig));
+    return `# Project guidance (AGENTS.md)\n\nStartup rules for THIS project — follow them:\n\n${capped}`;
   } catch {
     return "";
   }
@@ -329,7 +370,7 @@ export function buildSuperAgentSystem({
     relationshipBlock,
     extraContext,
     buildProjectIndex(projects),
-    buildProjectAgentsBlock(channelMeta?.projectPath),
+    buildProjectAgentsBlock(channelMeta?.projectPath, globalConfig),
     skipSkillsHint ? "" : buildSkillsHintBlock(listSkills),
     lazyToolsBlock,
     voiceBlock,

package/src/core/agent/run-agent.js

@@ -5,6 +5,7 @@ import {
 } from "./tools/tool-call-parser.js";
 import { resolveActiveModel, fallbackModels } from "./model-router.js";
 import { MAX_TOOL_ITERS, ACK_ONLY_TOOLS, MAX_CONSECUTIVE_ACKS, TURN_ENDING_TOOLS } from "./constants.js";
+import { TOOLS } from "./tools/names.js";
 import { pseudoToolSystem, shouldRetryWithPseudoTools } from "./tools/pseudo-tools.js";
 import { filterToolSchemas } from "./tools-overlap.js";
 import { isRetryableEngineError, shortRetryReason } from "./retry.js";
@@ -21,6 +22,8 @@ import {
   createStuckDetector,
   stuckNudgeSignal,
 } from "./stuck-detector.js";
+import { createGreetingGuard } from "./loop/greeting-guard.js";
+import { createSideEffectLedger } from "./loop/side-effects.js";
 
 async function emitProgress(onEvent, event) {
   if (typeof onEvent !== "function") return;
@@ -46,19 +49,6 @@ function fallbackFinalText(trace, error) {
   return lines.join("\n");
 }
 
-// A leading greeting clause: "¡Hola Manu!", "Hola,", "Hi there!", "Buenas tardes…".
-// Intentionally narrow — only the opening salutation up to its first terminator —
-// so we never eat real content.
-const LEADING_GREETING_RE =
-  /^\s*[¡!]*\s*(hola+|holis?|buenas|buen[oa]s?\s+(d[ií]as|tardes|noches)|hey|hi|hello)\b[^.!?¡\n]*[.!?¡]*[\s,]*/i;
-
-/** If `text` opens with a greeting, return it with that greeting removed; else null. */
-function stripLeadingGreeting(text) {
-  const m = String(text).match(LEADING_GREETING_RE);
-  if (!m) return null;
-  return String(text).slice(m[0].length).replace(/^\s+/, "");
-}
-
 function previewTraceResult(result) {
   if (result === null || result === undefined) return "ok";
   if (typeof result === "string") return result.slice(0, 180);
@@ -78,7 +68,7 @@ function previewTraceResult(result) {
 export const FINISH_TOOL_SCHEMA = {
   type: "function",
   function: {
-    name: "finish",
+    name: TOOLS.FINISH,
     description:
       "Call this ONLY when the user's request is fully complete and no step " +
       "remains. Put your final answer / summary of what you did in `summary` " +
@@ -274,7 +264,7 @@ export async function runAgent({
 
   const conversation = [...previousMessages, { role: "user", content: prompt }];
   const trace = [];
-  let totalUsage = { input_tokens: 0, output_tokens: 0 };
+  const totalUsage = { input_tokens: 0, output_tokens: 0 };
   let lastText = "";
 
   // Collapse repeated greetings within a single turn. A turn can produce several
@@ -282,16 +272,8 @@ export async function runAgent({
   // each one, so the user sees "¡Hola Manu!" twice. Keep the first greeting,
   // strip any later one. Belt-and-suspenders over the action-discipline prompt
   // rule (which strong models follow but gemini-flash et al. often ignore).
-  let greetedThisTurn = false;
-  const dedupeGreeting = (text) => {
-    if (!text) return text;
-    if (greetedThisTurn) {
-      const stripped = stripLeadingGreeting(text);
-      return stripped == null ? text : stripped;
-    }
-    if (LEADING_GREETING_RE.test(text)) greetedThisTurn = true;
-    return text;
-  };
+  const greetingGuard = createGreetingGuard();
+  const dedupeGreeting = (text) => greetingGuard.apply(text);
   let usePseudoTools = false;
   let ackOnlyStreak = 0;
   // "Never end on silence": a model call that returns no tool calls AND no
@@ -307,24 +289,7 @@ export async function runAgent({
   // short-circuit duplicates with a synthetic "already done" result
   // instead of re-running. Read-only tools are exempt (idempotent and
   // sometimes legitimately repeated, like list_tasks before/after).
-  const sideEffectExecuted = new Map();
-  const SIDE_EFFECT_TOOLS = new Set([
-    "send_telegram",
-    "create_task",
-    "write_file",
-    "edit_file",
-    "run_shell",
-    "call_runtime",
-    "add_project",
-    "set_identity",
-  ]);
-  const sideEffectSignature = (name, args) => {
-    try {
-      return `${name}:${JSON.stringify(args)}`;
-    } catch {
-      return `${name}:<unserializable>`;
-    }
-  };
+  const sideEffects = createSideEffectLedger();
 
   // Stuck detection: catches the loops the side-effect dedupe can't — a
   // read-only call repeated with identical results, or the same call erroring
@@ -498,7 +463,7 @@ export async function runAgent({
 
       // Completion contract: `finish` declares the task done. Capture its
       // summary as the final text and stop processing the rest of this turn.
-      if (name === "finish") {
+      if (name === TOOLS.FINISH) {
         finishSummary = typeof args.summary === "string" ? args.summary : "";
         break;
       }
@@ -517,13 +482,13 @@ export async function runAgent({
         iteration: iter + 1,
       });
       // Dedupe identical side-effecting calls within this turn.
-      const sig = SIDE_EFFECT_TOOLS.has(name) ? sideEffectSignature(name, args) : null;
-      if (sig && sideEffectExecuted.has(sig)) {
+      const sig = sideEffects.signature(name, args);
+      if (sideEffects.seen(sig)) {
         toolResult = {
           ok: true,
           deduped: true,
           note: `Ya ejecuté "${name}" con estos mismos argumentos en este turno; no lo repito.`,
-          previous: sideEffectExecuted.get(sig),
+          previous: sideEffects.previous(sig),
         };
         await emitProgress(onEvent, {
           type: "tool_deduped",
@@ -570,7 +535,7 @@ export async function runAgent({
             if (toolHandlerCtx) toolHandlerCtx.securityGateCleared = false;
           }
         }
-        if (sig) sideEffectExecuted.set(sig, summarizeForTrace(toolResult));
+        sideEffects.record(sig, summarizeForTrace(toolResult));
       }
 
       const traceItem = {

package/src/core/agent/security.js

@@ -17,7 +17,7 @@ const RISK_ORDER = { LOW: 1, MEDIUM: 2, HIGH: 3 };
 
 // Loop-control / interaction tools that never touch the world — grading them
 // only burns tokens and trains the model to rubber-stamp the field.
-const RISK_EXEMPT_TOOLS = new Set(["finish", "ask_questions", "discover_tools"]);
+import { RISK_EXEMPT_TOOLS } from "./tools/names.js";
 
 export function normalizeRisk(value) {
   const v = String(value || "").trim().toUpperCase();

package/src/core/agent/self-memory.js

@@ -14,11 +14,13 @@
 // The header inside the file picks up the current persona name from identity
 // (resolveAgentName) — never hardcode the agent name here.
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { SELF_MEMORY_PATH } from "../config/paths.js";
+
+export { SELF_MEMORY_PATH };
 import { resolveAgentName } from "../identity/index.js";
 
-export const SELF_MEMORY_PATH = path.join(os.homedir(), ".apx", "memory.md");
+
 
 function notebookHeader() {
   let name = "";

package/src/core/agent/skills/index-store.js

@@ -36,13 +36,13 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
+import { SKILLS_INDEX_PATH } from "#core/config/paths.js";
 
 import { embedOne } from "#core/memory/embeddings.js";
 import { listSkills } from "./loader.js";
 import { condenseSkillDescription } from "./catalog.js";
 
-const INDEX_PATH = path.join(os.homedir(), ".apx", "skills", ".index.json");
+const INDEX_PATH = SKILLS_INDEX_PATH;
 
 // ---------------------------------------------------------------------------
 // Disk I/O

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

@@ -30,9 +30,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
+import { SKILLS_DIR } from "#core/config/paths.js";
 import { fileURLToPath } from "node:url";
 import { apcSkillsDir } from "#core/apc/paths.js";
+import { parseFrontmatter } from "#core/apc/frontmatter.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
@@ -44,32 +45,12 @@ const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
 // <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");
+const GLOBAL_DIR         = SKILLS_DIR;
 
 // ---------------------------------------------------------------------------
 // Frontmatter parsing (minimal — handles the YAML we ship)
 // ---------------------------------------------------------------------------
 
-function parseFrontmatter(raw) {
-  if (!raw.startsWith("---")) return { fm: {}, body: raw };
-  const end = raw.indexOf("\n---", 3);
-  if (end < 0) return { fm: {}, body: raw };
-
-  const fmBlock = raw.slice(3, end).trim();
-  const body = raw.slice(end + 4).replace(/^\n/, "");
-
-  const fm = {};
-  for (const line of fmBlock.split("\n")) {
-    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/);
-    if (!m) continue;
-    let val = m[2].trim();
-    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-      val = val.slice(1, -1);
-    }
-    fm[m[1]] = val;
-  }
-  return { fm, body };
-}
 
 // ---------------------------------------------------------------------------
 // Directory scanners

package/src/core/agent/super-agent.js

@@ -80,8 +80,6 @@ export async function runSuperAgent({
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
   }
 
-  const sa = globalConfig.super_agent;
-
   // Memory Broker (Pieza 4): assemble the [MEMORIA RELEVANTE] block before the
   // turn. Silent + bounded (≤ broker_budget_ms); skipped for tool-free callers
   // (summarize/ask) where injected context would only confuse the transcript.

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

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 import { loggerFor } from "#core/logging.js";
 import { readAgents } from "#core/apc/parser.js";
@@ -15,9 +14,10 @@ import {
   findEngineSessionById,
   readEngineSessionContext,
 } from "#core/stores/engine-sessions.js";
-import { runProcess } from "#host/daemon/runtimes/_spawn.js";
-import { getRuntime, RUNTIME_IDS } from "#host/daemon/runtimes/index.js";
+import { runProcess } from "#core/runtimes/_spawn.js";
+import { getRuntime, RUNTIME_IDS } from "#core/runtimes/index.js";
 import { buildAgentSystem, resolveProject } from "../helpers.js";
+import { readJson } from "#core/util/json-file.js";
 
 const log = loggerFor("call_runtime");
 
@@ -90,7 +90,7 @@ function resolveProjectForAgent(projects, project, slug) {
 
 function projectName(project) {
   try {
-    const meta = JSON.parse(fs.readFileSync(apcProjectFile(project.path), "utf8"));
+    const meta = readJson(apcProjectFile(project.path), {});
     if (meta.name) return meta.name;
   } catch {}
   return path.basename(project.path);

package/src/core/agent/tools/handlers/search-sessions.js

@@ -3,7 +3,7 @@ import {
   ENGINES,
   collectAllSessions,
   findSessionAcrossEngines,
-} from "#interfaces/cli/commands/sessions.js";
+} from "#core/sessions/index.js";
 
 // Your own work sessions. This is how you remember what you did — never tell
 // the user to run `apx session ...`; call this and answer from the result.