@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/channels/telegram/voice-note.js

@@ -0,0 +1,150 @@
+// Telegram replies as VOICE while the owner is driving.
+//
+// The rule: when a trip is active, every automatic Telegram reply goes out
+// twice — first the spoken note, then the written reply under a transcript
+// header. Two sends, deliberately. The audio is what you can consume with your
+// eyes on the road; the text is what you can scroll back to at the next red
+// light, and what search, the web panel and the ledger can read. Neither one
+// alone covers both.
+//
+// They are not always the same words. The written half is the whole reply; the
+// spoken half is its FIRST PARAGRAPH (see spokenPart). That is what lets an
+// answer carry something unspeakable — a command, a prompt to paste, a diff —
+// without it being read out at the wheel: the model is told to put such things
+// below a blank line and to say where they went, and this module honours the
+// break it drew.
+//
+// Length is otherwise still the prompt's job, not this module's: the turn runs
+// in voice MODE (channelMeta.voice → prompts/modes/voice.md, two short
+// sentences) plus mobility mode, the same switch the desktop capsule uses.
+// Shortening a paragraph the model already wrote would only truncate it
+// mid-sentence, which is why nothing here does that — cutting at a boundary
+// the model was asked to draw is a different thing from cutting mid-thought.
+//
+// Core stays core: the Telegram I/O arrives as `io` ({ send, sendVoice }), so
+// nothing here imports the host plugin.
+import fs from "node:fs";
+import { t, resolveLang } from "#core/i18n/index.js";
+import { synthesize } from "#core/voice/tts.js";
+import { toVoiceNote } from "#core/voice/opus.js";
+import { stripEmoji } from "#core/voice/pronounceable.js";
+import { archiveOutboundMedia, outboundMediaMeta } from "#core/stores/media-archive.js";
+import { mobilityContext } from "#core/mobility/state.js";
+
+/**
+ * The half of a reply that gets SPOKEN: everything up to the first blank line
+ * or the first code fence, whichever comes first.
+ *
+ * This is not shortening the model's answer after the fact — that only ever
+ * truncates mid-sentence, which is why it was refused. It is honouring a
+ * boundary the model drew itself, on instruction: prompts/modes/mobility.md
+ * tells it the first paragraph is what gets spoken and that anything a person
+ * cannot hear — a command, a prompt to paste, a diff — goes below a blank line
+ * instead. Both halves are still delivered; only the audio stops at the break.
+ *
+ * Without it, "your answer is also a voice note" meant a driver being read a
+ * shell command character by character, because the model had nowhere else to
+ * put it and no reason to think it should.
+ *
+ * A reply with no break is spoken whole — the common case is one short
+ * paragraph, and nothing about it changes. A reply that opens straight into a
+ * code block has no sayable half at all; that comes back empty, and the caller
+ * sends it as plain text rather than voicing punctuation.
+ */
+export function spokenPart(text) {
+  const clean = String(text || "").trim();
+  if (!clean || clean.startsWith("```")) return "";
+  const breaks = [clean.indexOf("\n```"), clean.indexOf("\n\n")].filter((at) => at > 0);
+  return breaks.length ? clean.slice(0, Math.min(...breaks)).trim() : clean;
+}
+
+/**
+ * Is the owner in a car right now, and does this install want spoken replies
+ * for that? Trip state is the trigger; `config.voice.mobility_replies` is the
+ * kill switch (default on — the feature is pointless if you have to arm it
+ * before every drive, and the whole point is that you cannot safely touch the
+ * phone once you have started).
+ */
+export function mobilityVoiceActive(globalConfig, state = mobilityContext()) {
+  if (globalConfig?.voice?.mobility_replies === false) return false;
+  return Boolean(state?.trip?.active);
+}
+
+/**
+ * Send `text` as a voice note plus its transcript. Returns what actually
+ * happened, so the caller can log the right thing:
+ *
+ *   { voice: true,  transcript, provider, media, sent }  — both went out
+ *   { voice: false, reason }                             — TTS or ffmpeg
+ *                                          failed; the caller still owes the text
+ *
+ * `sent` is the TEXT message's Telegram result, not the audio's: it is the one
+ * carrying the inline keyboard, so it is the one a later edit has to address.
+ *
+ * The transcript send is the caller's business ONLY in the failure case: on
+ * success this function has already sent both halves, keyboard included. That
+ * asymmetry is on purpose — the keyboard must ride on the text message (a
+ * voice note with chips under it reads as if the chips belong to the audio
+ * player), and only this function knows whether the audio made it.
+ *
+ * `synthesizeFn` / `toVoiceNoteFn` are seams, not options: the same shape as
+ * `ctx.mobilityFetch` elsewhere in this feature. Speech and ffmpeg are the two
+ * things a test cannot have (the always-available mock engine returns silence,
+ * which this function is required to refuse), and without them the two-send
+ * contract would be untestable.
+ */
+export async function deliverVoiceReply({
+  io, chat_id, text, reply_markup, globalConfig, log = () => {},
+  synthesizeFn = synthesize, toVoiceNoteFn = toVoiceNote,
+}) {
+  const lang = resolveLang(globalConfig);
+  const clean = String(text || "").trim();
+  if (!clean) return { voice: false, reason: "empty" };
+  // The audio is the FIRST paragraph; the transcript below is the whole reply.
+  // See spokenPart() — the split is the model's, made on instruction.
+  const head = spokenPart(clean);
+  if (!head) return { voice: false, reason: "nothing-sayable" };
+
+  let audio = null;
+  let converted = null;
+  try {
+    // Spoken text loses its emoji; the transcript below keeps them. A TTS model
+    // has to produce something for every token, and 📍 comes out as a couple of
+    // seconds of humming in the middle of the sentence.
+    const sayable = stripEmoji(head);
+    const spoken = await synthesizeFn({ text: sayable || head, globalConfig });
+    // "mock" is the selector's way of saying nothing spoke — the audio is
+    // silence. Sending it would look like a delivered reply the owner simply
+    // could not hear, which is worse than plain text.
+    if (!spoken?.audio_path || spoken.provider === "mock") {
+      return { voice: false, reason: `tts:${spoken?.provider || "none"}` };
+    }
+    audio = spoken.audio_path;
+    converted = await toVoiceNoteFn(audio);
+    if (!converted) return { voice: false, reason: "ffmpeg" };
+
+    const duration = Math.round(spoken.duration_s || 0) || undefined;
+    await io.sendVoice({ chat_id, audio: converted, duration });
+    const transcript = `${t("mobility.transcript", { lang })}\n${clean}`;
+    const sent = await io.send({ chat_id, text: transcript, reply_markup });
+    // The tmp file is about to be deleted, so the ledger row cannot point at
+    // it — archive the bytes first and hand the caller the meta that makes the
+    // web thread show a real player instead of "[voice]".
+    const media = outboundMediaMeta(
+      "audio",
+      archiveOutboundMedia(converted, { mime: "audio/ogg" }),
+      { duration }
+    );
+    return { voice: true, transcript, provider: spoken.provider, media, sent };
+  } catch (error) {
+    log(`telegram voice reply failed: ${error?.message || error}`);
+    return { voice: false, reason: error?.message || "send-failed" };
+  } finally {
+    // Both files live under ~/.apx/tmp/tts and neither is referenced again:
+    // the ledger keeps its own archived copy (media-archive.js) once sendVoice
+    // has logged the row.
+    for (const file of new Set([audio, converted].filter(Boolean))) {
+      try { fs.unlinkSync(file); } catch { /* already gone */ }
+    }
+  }
+}

package/src/core/config/index.js

@@ -4,7 +4,7 @@
 // can keep `import { APX_HOME, projectStorageRoot } from ".../config"` working.
 import fs from "node:fs";
 import path from "node:path";
-import { APX_HOME, CONFIG_PATH } from "./paths.js";
+import { APX_HOME, CONFIG_PATH, syncPaths } from "./paths.js";
 import { PERMISSION_MODES } from "../constants/permissions.js";
 import { agentsMdFile, apcProjectFile } from "../apc/paths.js";
 
@@ -62,6 +62,25 @@ const DEFAULT_CONFIG = {
     // snappier but more "want me to continue?" hand-backs. 0/unset → built-in
     // default (TELEGRAM_TOOL_ITERS in src/core/agent/constants.js).
     telegram_max_iters: 0,
+    // Tool-loop budget for a routine that does NOT report to Telegram (Magui
+    // filling a backlog, an agent working a repo): no human waits on it mid-run,
+    // so it runs to completion rather than to a chat budget. 0/unset → built-in
+    // ceiling (ROUTINE_UNCAPPED_TOOL_ITERS in src/core/agent/constants.js), which
+    // is a runaway backstop, not a normal stopping point. Telegram-bound routines
+    // keep telegram_max_iters so their message stays one concise turn.
+    routine_max_iters: 0,
+    // Tool-loop budget for the web chat (big chat + docked sidebar). This is the
+    // surface you watch while it works, so it runs to completion instead of
+    // stopping every few actions to ask — the "want me to keep going?" close is
+    // Telegram's guardrail, where you can't see the turn go wrong. 0/unset →
+    // built-in ceiling (WEB_TOOL_ITERS in src/core/agent/constants.js), which is
+    // a runaway backstop, not a normal stopping point.
+    web_max_iters: 0,
+    // How often optional MODEL prose may appear during a working Telegram turn.
+    // Every real tool start is already shown immediately, with typing renewed;
+    // this controls only extra model-written heartbeats. 0 disables those extra
+    // notes. See core/channels/telegram/progress-gate.js.
+    telegram_progress_every_s: 90,
     // Char cap for a FOREIGN project's AGENTS.md in the prompt. 0 = no cap.
     // The project APX runs inside is never capped regardless of this value —
     // a project must always read its own contract whole.
@@ -110,13 +129,26 @@ const DEFAULT_CONFIG = {
       enabled: true,
       rules: [],
     },
-    // Goal-completion judge (OpenHands critic pattern): after a
-    // completion-contract turn declares done, an LLM judge scores goal
-    // completion (0..1); below success_threshold the agent gets a
+    // Vision bridge: when the answering model cannot see pixels (zen free
+    // models, etc.), describe attached photos with this vision model and fold
+    // the text into the prompt. Default gemini-2.0-flash; override here or via
+    // a has_image routing rule.
+    vision_bridge_model: null,
+    // Goal-completion judge (OpenHands critic pattern): an LLM judge scores
+    // goal completion (0..1); below success_threshold the agent gets a
     // verification follow-up and continues, up to max_iterations rounds.
+    //   enabled            — verify the "done" a completion-contract (coding)
+    //                        turn declares. Opt-in: it costs a call per finish.
+    //   continue_unfinished — continue a CONVERSATIONAL turn that stopped
+    //                        mid-task (the model announced its next step and
+    //                        called no tool). On by default; that stop reads as
+    //                        a bug, and the manual fix is the user typing
+    //                        "seguí". Chat turns and turns that ended asking a
+    //                        question are never judged.
     // model "" → judge runs on super_agent.model.
     judge: {
       enabled: false,
+      continue_unfinished: true,
       success_threshold: 0.6,
       max_iterations: 2,
       model: "",
@@ -155,7 +187,8 @@ const DEFAULT_CONFIG = {
       window_hours: 6,   // only surface channels touched within this window
       max_lines: 3,      // hard cap on bullets (token guard)
     },
-    // Legacy flat keys (still honored as an ollama override for old configs).
+    // Flat Ollama embedding defaults; embed-engines/index.js folds these into
+    // an `embeddings.ollama` block when the config has no explicit one.
     embed_model: "nomic-embed-text",  // Ollama embeddings model
     embed_base_url: "",               // "" → falls back to engines.ollama.base_url
     embed_timeout_ms: 4000,
@@ -204,6 +237,12 @@ const DEFAULT_CONFIG = {
 };
 
 function ensureHome() {
+  // Re-derive the home first. It is fixed for the life of a real process, so
+  // this is a string compare that always says "no" in production — but a test
+  // that relocates APX_HOME after this module loaded needs its fixture read
+  // back, not the developer's real config. Doing it here, rather than relying
+  // on nothing having imported config yet, is what makes that deterministic.
+  syncPaths();
   fs.mkdirSync(APX_HOME, { recursive: true });
 }
 
@@ -340,36 +379,15 @@ export function writeConfig(cfg) {
   try { fs.chmodSync(CONFIG_PATH, 0o600); } catch {}
 }
 
-// Normalise `model_fallback` to the new format (`models` as an ordered array
-// of "<provider>:<model>" strings). Legacy configs that use `order + models{}`
-// are converted in place; the result is what the runtime sees, but
-// writeConfig() preserves whichever shape the user has on disk unless we
-// rewrite it explicitly elsewhere.
+// Normalise `model_fallback`: `models` is an ordered array of
+// "<provider>:<model>" strings. Anything else falls back to the defaults.
 function mergeModelFallback(raw) {
   const def = DEFAULT_CONFIG.super_agent.model_fallback;
   const src = raw && typeof raw === "object" ? raw : {};
 
-  // Resolve `models` to an array. Three input shapes:
-  //   1. array of strings → keep, filtered to "<provider>:<model>".
-  //   2. legacy object + (optional) order → walk order, collect values.
-  //   3. nothing → use defaults.
-  let models;
-  if (Array.isArray(src.models)) {
-    models = src.models
-      .filter((m) => typeof m === "string" && m.includes(":"))
-      .map(String);
-  } else if (src.models && typeof src.models === "object") {
-    const order = Array.isArray(src.order)
-      ? src.order.map(String)
-      : ["ollama", "openrouter", "groq"];
-    models = [];
-    for (const p of order) {
-      const m = src.models[p.toLowerCase()];
-      if (typeof m === "string" && m.includes(":")) models.push(m);
-    }
-  } else {
-    models = [...def.models];
-  }
+  const models = Array.isArray(src.models)
+    ? src.models.filter((m) => typeof m === "string" && m.includes(":")).map(String)
+    : [...def.models];
 
   return {
     enabled: typeof src.enabled === "boolean" ? src.enabled : def.enabled,
@@ -381,31 +399,12 @@ function mergeModelFallback(raw) {
   };
 }
 
-// Migrate legacy `telegram.bot_token` / `telegram.chat_id` (root level) into
-// `telegram.channels[]`. These root-level fields were removed once channels[]
-// became the source of truth; we keep this helper around so existing configs
-// upgrade in place without losing credentials.
+// `telegram.channels[]` is the source of truth for credentials. A bare
+// `bot_token`/`chat_id` at the root is not a supported shape and is dropped.
 function mergeTelegram(rawTelegram) {
   const src = rawTelegram || {};
-  const { bot_token: legacyBotToken, chat_id: legacyChatId, channels: rawChannels, ...rest } = src;
-  let channels = Array.isArray(rawChannels) ? rawChannels : [];
-
-  const hasLegacy =
-    (typeof legacyBotToken === "string" && legacyBotToken.length > 0) ||
-    (typeof legacyChatId === "string" && legacyChatId.length > 0);
-
-  if (hasLegacy && channels.length === 0) {
-    // Build a single "default" channel from the legacy fields and drop them.
-    channels = [
-      {
-        name: "default",
-        bot_token: legacyBotToken || "",
-        chat_id: legacyChatId || "",
-      },
-    ];
-    // eslint-disable-next-line no-console
-    console.warn("[apx] migrated legacy telegram.bot_token/chat_id into channels[0]");
-  }
+  const { bot_token: _dropBotToken, chat_id: _dropChatId, channels: rawChannels, ...rest } = src;
+  const channels = Array.isArray(rawChannels) ? rawChannels : [];
 
   return {
     ...DEFAULT_CONFIG.telegram,

package/src/core/config/paths.js

@@ -7,31 +7,49 @@ import path from "node:path";
 /**
  * Where APX keeps everything. `APX_HOME` in the environment relocates it —
  * useful for sandboxes and required by tests that need an isolated home.
- *
- * Resolve lazily when a caller can be reached after the environment changes
- * (tests stub os.homedir mid-run); the eager `APX_HOME` constant below is the
- * common case and stays for the ~30 call sites that read it at import time.
  */
-export function apxHome() {
+function computeHome() {
   return process.env.APX_HOME || path.join(os.homedir(), ".apx");
 }
 
-export const APX_HOME = apxHome();
-export const CONFIG_PATH = path.join(APX_HOME, "config.json");
-export const PID_PATH = path.join(APX_HOME, "daemon.pid");
-export const LOG_PATH = path.join(APX_HOME, "daemon.log");
-export const TELEGRAM_STATE_PATH = path.join(APX_HOME, "telegram-state.json");
-export const TOKEN_PATH = path.join(APX_HOME, "daemon.token");
+// ---------------------------------------------------------------------------
+// The paths below are `let`, not `const`, and that is the whole point.
+//
+// They used to be frozen at import: whichever module reached this file first
+// decided where ~/.apx was for the rest of the process. That made test
+// isolation a RACE — a test that relocates APX_HOME inside its body only won if
+// nothing had imported config before it, which depends on module-graph order
+// and, under a parallel runner, on which files happen to share a process. Two
+// suites flaked on exactly that (tests/admin-reload, tests/commitments-api):
+// they wrote a fixture config into a temp home and then read the developer's
+// real one.
+//
+// An ES module export is a LIVE BINDING, so reassigning here updates every
+// importer — including ones that imported before the change — with no call-site
+// changes and no accessor cost. Importers still cannot assign: the binding is
+// read-only on their side, so `let` costs nothing in safety.
+//
+// Call `syncPaths()` after changing APX_HOME (or HOME). `apxHome()` and
+// `ensureHome()` already do, which covers readConfig/writeConfig and therefore
+// nearly everything.
+// ---------------------------------------------------------------------------
+
+export let APX_HOME = computeHome();
+export let CONFIG_PATH;
+export let PID_PATH;
+export let LOG_PATH;
+export let TELEGRAM_STATE_PATH;
+export let TOKEN_PATH;
 
 // Global channel messages (telegram, direct, whatsapp, …) live here,
 // separated from any project. Structure: ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl
-export const GLOBAL_MESSAGES_DIR = path.join(APX_HOME, "messages");
+export let GLOBAL_MESSAGES_DIR;
 
 // Per-project runtime storage (conversations, sessions) — never in the repo.
 // Structure: ~/.apx/projects/<apx_id>/agents/<slug>/conversations/
-export const PROJECT_STORE_ROOT = path.join(APX_HOME, "projects");
+export let PROJECT_STORE_ROOT;
 export const DEFAULT_PROJECT_ID = "default";
-export const DEFAULT_PROJECT_STORE = path.join(PROJECT_STORE_ROOT, DEFAULT_PROJECT_ID);
+export let DEFAULT_PROJECT_STORE;
 
 // ---------------------------------------------------------------------------
 // Everything else under ~/.apx.
@@ -44,38 +62,106 @@ export const DEFAULT_PROJECT_STORE = path.join(PROJECT_STORE_ROOT, DEFAULT_PROJE
 // ---------------------------------------------------------------------------
 
 /** The super-agent's own notebook (see core/agent/self-memory.js). */
-export const SELF_MEMORY_PATH = path.join(APX_HOME, "memory.md");
+export let SELF_MEMORY_PATH;
 /** Who the super-agent is: name, personality, owner. */
-export const IDENTITY_PATH = path.join(APX_HOME, "identity.json");
+export let IDENTITY_PATH;
 
 /** User-installed skills and the RAG index built over them. */
-export const SKILLS_DIR = path.join(APX_HOME, "skills");
-export const SKILLS_INDEX_PATH = path.join(SKILLS_DIR, ".index.json");
+export let SKILLS_DIR;
+export let SKILLS_INDEX_PATH;
 
 /** Agent vault — reusable agent definitions, not tied to one project. */
-export const AGENT_VAULT_DIR = path.join(APX_HOME, "agents");
+export let AGENT_VAULT_DIR;
 
 /** Ledger of unrequested outbound messages and the user's feedback on them. */
-export const NUDGES_PATH = path.join(APX_HOME, "nudges.json");
+export let NUDGES_PATH;
+/** Mobility preferences such as "do not mention more trips today". */
+export let MOBILITY_PATH;
 
 /** Unified log tree. Everything writes here so one tail follows the system. */
-export const LOG_DIR = path.join(APX_HOME, "logs");
-export const APX_LOG_PATH = path.join(LOG_DIR, "apx.log");
-export const ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
+export let LOG_DIR;
+export let APX_LOG_PATH;
+export let ERROR_TRACE_PATH;
 
 /** Desktop capsule (Electron) runtime state. */
-export const DESKTOP_PID_PATH = path.join(APX_HOME, "desktop.pid");
-export const DESKTOP_LOG_PATH = path.join(APX_HOME, "desktop.log");
-export const DESKTOP_AUTOSTART_LOG_PATH = path.join(APX_HOME, "desktop-autostart.log");
+export let DESKTOP_PID_PATH;
+export let DESKTOP_LOG_PATH;
+export let DESKTOP_AUTOSTART_LOG_PATH;
 
 /** Scratch space. Safe to delete between runs. */
-export const TMP_DIR = path.join(APX_HOME, "tmp");
-export const TTS_TMP_DIR = path.join(TMP_DIR, "tts");
-export const RECORDINGS_TMP_DIR = path.join(TMP_DIR, "recordings");
+export let TMP_DIR;
+export let TTS_TMP_DIR;
+export let RECORDINGS_TMP_DIR;
+
+/**
+ * Generated images (see core/images/). NOT under tmp/ on purpose: a TTS clip is
+ * consumed once and thrown away, but a picture the user asked for is an
+ * artifact they will want again, so it keeps a dated gallery instead. Nothing
+ * here is ever written into a project checkout — see rule "no auto-writes into
+ * the repo": `apx image` only writes into the repo when --out says so.
+ */
+export let IMAGES_DIR;
 
 /** Managed runtimes we install on the user's behalf. */
-export const RUNTIME_DIR = path.join(APX_HOME, "runtime");
-export const WHISPER_VENV_DIR = path.join(RUNTIME_DIR, "whisper-venv");
+export let RUNTIME_DIR;
+export let WHISPER_VENV_DIR;
+
+/** Derive every path under the home. Order matters where one nests in another. */
+function rebuild(home) {
+  APX_HOME = home;
+  CONFIG_PATH = path.join(home, "config.json");
+  PID_PATH = path.join(home, "daemon.pid");
+  LOG_PATH = path.join(home, "daemon.log");
+  TELEGRAM_STATE_PATH = path.join(home, "telegram-state.json");
+  TOKEN_PATH = path.join(home, "daemon.token");
+  GLOBAL_MESSAGES_DIR = path.join(home, "messages");
+  PROJECT_STORE_ROOT = path.join(home, "projects");
+  DEFAULT_PROJECT_STORE = path.join(PROJECT_STORE_ROOT, DEFAULT_PROJECT_ID);
+  SELF_MEMORY_PATH = path.join(home, "memory.md");
+  IDENTITY_PATH = path.join(home, "identity.json");
+  SKILLS_DIR = path.join(home, "skills");
+  SKILLS_INDEX_PATH = path.join(SKILLS_DIR, ".index.json");
+  AGENT_VAULT_DIR = path.join(home, "agents");
+  NUDGES_PATH = path.join(home, "nudges.json");
+  MOBILITY_PATH = path.join(home, "mobility.json");
+  LOG_DIR = path.join(home, "logs");
+  APX_LOG_PATH = path.join(LOG_DIR, "apx.log");
+  ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
+  DESKTOP_PID_PATH = path.join(home, "desktop.pid");
+  DESKTOP_LOG_PATH = path.join(home, "desktop.log");
+  DESKTOP_AUTOSTART_LOG_PATH = path.join(home, "desktop-autostart.log");
+  TMP_DIR = path.join(home, "tmp");
+  TTS_TMP_DIR = path.join(TMP_DIR, "tts");
+  RECORDINGS_TMP_DIR = path.join(TMP_DIR, "recordings");
+  IMAGES_DIR = path.join(home, "images");
+  RUNTIME_DIR = path.join(home, "runtime");
+  WHISPER_VENV_DIR = path.join(RUNTIME_DIR, "whisper-venv");
+}
+
+rebuild(APX_HOME);
+
+/**
+ * Point every path at wherever the home is NOW.
+ *
+ * Production never needs this — the environment is fixed at boot — but a test
+ * that relocates APX_HOME (or stubs os.homedir, or moves HOME) after this
+ * module has loaded does, and calling it is deterministic where relying on
+ * import order was not.
+ *
+ * @returns {boolean} whether anything moved.
+ */
+export function syncPaths() {
+  const next = computeHome();
+  if (next === APX_HOME) return false;
+  rebuild(next);
+  return true;
+}
+
+/** The home, guaranteed current. */
+export function apxHome() {
+  syncPaths();
+  return APX_HOME;
+}
 
 export function projectStorageRoot(apxId) {
   return path.join(PROJECT_STORE_ROOT, apxId);

package/src/core/config/redact.js

@@ -18,6 +18,9 @@ export const SECRET_PATHS = [
   "voice.tts.elevenlabs.api_key",
   "voice.tts.openai.api_key",
   "voice.tts.gemini.api_key",
+  "images.a1111.api_key",
+  "images.sdcpp.api_key",
+  "images.openai.api_key",
   "transcription.openai.api_key",
   "transcription.custom.api_key",
   "memory.embeddings.openai.api_key",
@@ -30,8 +33,92 @@ export const SECRET_PATHS = [
   // below. Listed here so the "which keys are secrets" question still has one
   // answer to read.
   "engines.gemini.api_keys.*",
+  // User-added providers live in an object keyed by slug, so the segment in
+  // the middle is a wildcard. redact() walks these too — see expandWildcards.
+  "voice.tts.custom.*.api_key",
+  "images.custom.*.api_key",
 ];
 
+/**
+ * Expand a wildcard path against a real config, yielding the concrete dotted
+ * paths that exist in it. Only object maps are walked: `engines.gemini.
+ * api_keys.*` addresses a LIST, which has no key to name, and stays handled by
+ * the array cases below.
+ */
+function expandWildcards(cfg, pattern) {
+  const parts = pattern.split(".");
+  let paths = [[]];
+  let nodes = [cfg];
+  for (const part of parts) {
+    const nextPaths = [];
+    const nextNodes = [];
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i];
+      if (!node || typeof node !== "object" || Array.isArray(node)) continue;
+      const keys = part === "*" ? Object.keys(node) : [part];
+      for (const key of keys) {
+        if (!(key in node)) continue;
+        nextPaths.push([...paths[i], key]);
+        nextNodes.push(node[key]);
+      }
+    }
+    paths = nextPaths;
+    nodes = nextNodes;
+  }
+  return paths.map((p) => p.join("."));
+}
+
+/** Every concrete secret path present in `cfg`, wildcards resolved. */
+function concreteSecretPaths(cfg) {
+  const out = [];
+  for (const pattern of SECRET_PATHS) {
+    if (!pattern.includes("*")) { out.push(pattern); continue; }
+    // A trailing `*` addresses list entries, not map keys — skip those here.
+    if (pattern.endsWith(".*")) continue;
+    out.push(...expandWildcards(cfg, pattern));
+  }
+  return out;
+}
+
+// Leaf names that carry a secret even when the full path is not in
+// SECRET_PATHS yet — a provider added after this list was last touched still
+// gets caught. Deliberately narrow: `base_url`, `model` and `provider` are the
+// keys that legitimately belong in a committed project config.
+const SECRET_LEAF_RE = /(^|_)(api_?keys?|tokens?|secrets?|passwords?|credentials?)$/;
+
+/**
+ * True when a dotted config key addresses a secret — used to warn before a
+ * credential is written somewhere it should not be (a committed
+ * `.apc/config.json`). Three ways to match, in order of confidence:
+ *
+ *   1. the key IS a secret path             engines.openai.api_key
+ *   2. the key is an ANCESTOR of one        engines.openai  ← value holds api_key
+ *   3. the leaf name looks like a secret    engines.newprovider.api_key
+ *
+ * Case 2 matters because `apx config set engines.openai '{"api_key":"…"}'` puts
+ * the secret in the VALUE, where a leaf-name check would never see it.
+ * Wildcards in SECRET_PATHS (`telegram.channels.*.bot_token`) match any segment.
+ */
+export function isSecretKey(dottedKey) {
+  if (typeof dottedKey !== "string" || !dottedKey.trim()) return false;
+  const parts = dottedKey.trim().split(".");
+
+  for (const pattern of SECRET_PATHS) {
+    const pp = pattern.split(".");
+    // Compare only the segments the two have in common: a shorter key is an
+    // ancestor (case 2), a longer one reaches inside a secret (still secret).
+    const shared = Math.min(pp.length, parts.length);
+    let hit = true;
+    for (let i = 0; i < shared; i++) {
+      if (pp[i] === "*") continue;
+      if (pp[i] !== parts[i]) { hit = false; break; }
+    }
+    if (hit) return true;
+  }
+
+  return SECRET_LEAF_RE.test(parts[parts.length - 1].toLowerCase());
+}
+
 /** Replace a secret string with the visible marker, preserving the last 5 chars. */
 export function secretMarker(value) {
   if (typeof value !== "string" || !value.length) return value;
@@ -49,8 +136,7 @@ export function redactConfig(cfg) {
   const out = JSON.parse(JSON.stringify(cfg || {}));
   const mark = (val) => (typeof val === "string" && val.length ? secretMarker(val) : val);
 
-  for (const dotted of SECRET_PATHS) {
-    if (dotted.includes("*")) continue;
+  for (const dotted of concreteSecretPaths(cfg)) {
     const parts = dotted.split(".");
     let cur = out;
     for (let i = 0; i < parts.length - 1; i++) {
@@ -108,8 +194,7 @@ function setDotted(obj, dotted, value) {
  */
 export function mergeRedactedSecrets(next, prior) {
   if (!next || typeof next !== "object") return next;
-  for (const dotted of SECRET_PATHS) {
-    if (dotted.includes("*")) continue;
+  for (const dotted of concreteSecretPaths(next)) {
     if (isSecretMarker(getDotted(next, dotted))) {
       const priorVal = getDotted(prior, dotted);
       if (typeof priorVal === "string" && priorVal.length) setDotted(next, dotted, priorVal);

package/src/core/config/secret-values.js

@@ -37,9 +37,8 @@ function getDotted(obj, dotted) {
 
 /**
  * Walk a config object and return every secret VALUE it holds: all
- * SECRET_PATHS entries, every telegram channel bot_token, and the legacy
- * root telegram.bot_token (pre-migration configs). Deduped; empty and
- * too-short strings dropped.
+ * SECRET_PATHS entries and every telegram channel bot_token. Deduped; empty
+ * and too-short strings dropped.
  */
 export function collectSecretValues(cfg) {
   const out = new Set();
@@ -56,7 +55,6 @@ export function collectSecretValues(cfg) {
         if (isRegistrable(ch?.bot_token)) out.add(ch.bot_token);
       }
     }
-    if (isRegistrable(cfg?.telegram?.bot_token)) out.add(cfg.telegram.bot_token);
   } catch {
     // collection must never break the caller — return what we got so far
   }

package/src/core/constants/actors.js

@@ -6,3 +6,8 @@
 // was named). Identity (display name + personality) lives in identity.json and
 // is resolved at runtime via resolveAgentName().
 export const SUPERAGENT_ACTOR_ID = "super_agent";
+
+// The human. Not an agent and never summonable: the owner speaks by typing, so
+// naming them in a mention resolves to nothing. Used as the author of anything
+// a person wrote — a task comment, a group line — where an agent slug would go.
+export const OWNER_ACTOR_ID = "owner";