@agentprojectcontext/apx 1.33.1 → 1.35.0

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

@@ -0,0 +1,117 @@
+---
+name: apx-voice
+scope: optional
+description: APX TTS — Piper (local), ElevenLabs/OpenAI/Gemini (cloud), unified /voice/turn channel, `apx voice` CLI. Load when the user wants to speak with APX, configure a voice engine, or troubleshoot silent output.
+---
+
+# apx-voice
+
+TTS facade in `core/voice/` with five engines. STT lives separately in `host/daemon/transcription.js` (Whisper). The "voice channel" combines both for mic→agent→speaker.
+
+## Engines
+
+| id | Local? | Needs key? | Notes |
+|---|---|---|---|
+| `piper`      | yes | no  | Local, offline. Requires `piper` CLI + `.onnx` model. es_AR-daniela-high recommended. |
+| `elevenlabs` | no  | yes | Excellent. Free tier 10k chars/mo. `eleven_multilingual_v2`. |
+| `openai`     | no  | yes | Reuses `engines.openai.api_key`. `tts-1`. |
+| `gemini`     | no  | yes | Returns raw L16 PCM — APX wraps in WAV automatically. |
+| `mock`       | yes | no  | Silent WAV; placeholder for tests. |
+
+`auto` probes: piper → elevenlabs → openai → gemini → mock.
+
+## Concrete CLI calls
+
+```bash
+apx voice providers                              # what's configured + available
+apx voice say "Hello from APX" --provider piper
+apx voice say "Hello from APX" --provider gemini --voice Aoede
+apx voice say "..." --no-play                    # generate WAV, don't play
+
+apx voice listen                                 # mic → STT, records until silence (sox) or Ctrl+C
+apx voice listen --seconds 5                     # fixed-duration capture
+apx voice listen --provider <id>                 # override STT provider
+```
+
+Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`). If none found, you get the file path and no playback.
+
+## Configuration
+
+`~/.apx/config.json → voice.tts.<engine>`:
+
+```json
+{
+  "voice": {
+    "tts": {
+      "provider": "gemini",
+      "piper":      { "bin": "piper", "model": "/Users/.../es_AR-daniela-high.onnx" },
+      "elevenlabs": { "api_key": "...", "model": "eleven_multilingual_v2", "voice_id": "..." },
+      "openai":     { "api_key": "...", "model": "tts-1", "voice": "alloy", "format": "mp3" },
+      "gemini":     { "api_key": "...", "model": "gemini-2.5-flash-preview-tts", "voice": "Aoede" }
+    }
+  }
+}
+```
+
+`apx config set voice.tts.provider <name>` to switch.
+
+## Quick setup: Piper local (recommended, no internet)
+
+```bash
+# 1. Install binary (macOS arm64)
+curl -L https://github.com/rhasspy/piper/releases/latest/download/piper_macos_aarch64.tar.gz \
+  -o /tmp/piper.tar.gz
+sudo tar xzf /tmp/piper.tar.gz -C /usr/local/bin --strip-components=1
+
+# 2. Voice model (es_AR, "daniela")
+mkdir -p ~/.apx/voices && cd ~/.apx/voices
+curl -LO https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_AR/daniela/high/es_AR-daniela-high.onnx
+curl -LO https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_AR/daniela/high/es_AR-daniela-high.onnx.json
+
+# 3. Configure + test
+apx config set voice.tts.provider piper
+apx config set voice.tts.piper.model "$HOME/.apx/voices/es_AR-daniela-high.onnx"
+apx voice say "hola, soy APX" --provider piper
+```
+
+## Quick setup: Gemini cloud
+
+```bash
+apx config set voice.tts.provider gemini
+apx config set voice.tts.gemini.api_key '<GEMINI_KEY>'
+apx config set engines.gemini.api_key   '<GEMINI_KEY>'    # reuse for LLM router
+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.
+
+```bash
+curl -X POST http://127.0.0.1:7430/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.
+
+## Anti-examples
+
+- DON'T trust `apx voice providers` saying "mock available" as green light — mock is silence. Configure a real provider.
+- DON'T set `voice.tts.provider` to a provider with no key. It falls through `auto` to the next, but that's not what you asked.
+- DON'T expect Gemini TTS to return MP3 — it returns raw L16 PCM; APX wraps in WAV. Files are `.wav`, mime `audio/wav`. Convert with ffmpeg if you need MP3.
+
+## Troubleshooting silent output
+
+1. `apx voice providers` — what's actually available?
+2. `apx voice say "test" --provider <engine> --no-play` — file exists?
+3. `file <path>` — valid container? Gemini output should be `RIFF WAVE Microsoft PCM`.
+4. `afplay <path>` — does the OS player open it?
+5. If 3 fails for Gemini, you may be on APX before the PCM-wrap fix (commit `ba5c416`+).
+
+## Don't
+
+- 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.

package/src/core/runtime-skills/{claude-code.md → claude-code/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: claude-code
 description: "Activate ONLY when the user explicitly mentions Claude Code, Claude CLI, claude command, Anthropic Claude Code, installing Claude Code, using Claude Code, or APX runtime claude-code. Do not activate for generic Claude model discussion."
 homepage: https://docs.anthropic.com/en/docs/claude-code

package/src/core/runtime-skills/{codex-cli.md → codex-cli/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: codex-cli
 description: "Activate ONLY when the user explicitly mentions Codex CLI, OpenAI Codex, @openai/codex, codex command, codex exec, installing Codex, using Codex, ~/.codex, or APX runtime codex."
 homepage: https://developers.openai.com/codex

package/src/core/runtime-skills/{opencode-cli.md → opencode-cli/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: opencode-cli
 description: "Activate ONLY when the user explicitly mentions OpenCode, opencode command, installing OpenCode, using OpenCode, OpenCode provider setup, or APX runtime opencode."
 homepage: https://opencode.ai/docs

package/src/core/runtime-skills/{openrouter.md → openrouter/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: openrouter
 description: "Activate ONLY when the user explicitly mentions OpenRouter, OPENROUTER_API_KEY, OpenRouter models, installing OpenRouter provider config, or using OpenRouter with APX, OpenCode, LiteLLM, or an OpenAI-compatible client."
 homepage: https://openrouter.ai/docs

package/src/{host/daemon/env-detect.js → core/runtimes/detect.js}

@@ -1,7 +1,7 @@
 // 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 "./runtimes/_spawn.js";
+import { runProcess } from "#host/daemon/runtimes/_spawn.js";
 
 const PROBES = [
   // Coding-agent CLIs (runtimes/)

package/src/core/stores/code-sessions.js

@@ -13,6 +13,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { nowIso } from "../util/time.js";
 import { shortId as makeShortId } from "../util/ids.js";
+import { CODE_MODES, DEFAULT_CODE_MODE } from "../constants/code-modes.js";
 
 function sessionsDir(storagePath) {
   return path.join(storagePath, "code-sessions");
@@ -91,7 +92,7 @@ export function createCodeSession(storagePath, fields = {}) {
     createdAt: ts,
     updatedAt: ts,
     model: fields.model || null,
-    mode: fields.mode === "plan" ? "plan" : "build",
+    mode: fields.mode === CODE_MODES.PLAN ? CODE_MODES.PLAN : DEFAULT_CODE_MODE,
     agentSlug: fields.agentSlug || null,
     git: fields.git && typeof fields.git === "object" ? fields.git : null,
     messages: [],
@@ -109,7 +110,7 @@ export function updateCodeSession(storagePath, id, patch = {}) {
   if (!session) return null;
   if (patch.title != null) session.title = String(patch.title).trim() || session.title;
   if (patch.model !== undefined) session.model = patch.model || null;
-  if (patch.mode === "plan" || patch.mode === "build") session.mode = patch.mode;
+  if (patch.mode === CODE_MODES.PLAN || patch.mode === CODE_MODES.BUILD) session.mode = patch.mode;
   if (patch.agentSlug !== undefined) session.agentSlug = patch.agentSlug || null;
   if (patch.git !== undefined) session.git = patch.git;
   session.updatedAt = nowIso();
@@ -147,3 +148,50 @@ export function appendTurn(storagePath, id, turn) {
   writeJson(sessionFile(storagePath, id), session);
   return session;
 }
+
+// ---------------------------------------------------------------------------
+// Transcript → engine history
+// ---------------------------------------------------------------------------
+
+// One-line summary of an ask_questions tool call. Without it the next turn's
+// history shows only "user answered X" with no record that the model had
+// asked something — which makes the model ask again forever.
+function summarizeAskQuestionsPart(part) {
+  const raw = part?.args?.questions;
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const lines = raw
+    .map((q) => {
+      if (typeof q === "string") return `- ${q}`;
+      if (!q || typeof q !== "object" || typeof q.question !== "string") return null;
+      const opts = Array.isArray(q.options) ? q.options : [];
+      const optStr = opts
+        .map((o) => (typeof o === "string" ? o : (o && typeof o.label === "string" ? o.label : "")))
+        .filter(Boolean)
+        .join(", ");
+      return optStr ? `- ${q.question} (opciones: ${optStr})` : `- ${q.question}`;
+    })
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  return `[ask_questions]\n${lines.join("\n")}`;
+}
+
+/**
+ * Flatten a stored rich transcript into the [{role, content}] history the
+ * super-agent loop expects. Text parts are concatenated; tool parts are
+ * normally internal, except ask_questions which is surfaced as a one-line
+ * summary so the model doesn't lose track of what it already asked.
+ */
+export function codeSessionHistory(session) {
+  return (session?.messages || []).map((m) => {
+    const chunks = [];
+    for (const p of m.parts || []) {
+      if (!p) continue;
+      if (p.kind === "text" && p.text) chunks.push(p.text);
+      else if (p.kind === "tool" && p.tool === "ask_questions") {
+        const summary = summarizeAskQuestionsPart(p);
+        if (summary) chunks.push(summary);
+      }
+    }
+    return { role: m.role, content: chunks.join("\n\n").trim() };
+  });
+}

package/src/core/stores/routine-memory.js

@@ -2,7 +2,7 @@
 //
 // Path: <projectStoragePath>/routines/<routineId>/memory.md
 //
-// The routine handler (host/daemon/routines.js) creates the file on first read
+// The routine handler (core/routines/runner.js) creates the file on first read
 // and injects a bounded slice into the super-agent prompt via
 // channelMeta.routineMemory. The routine can write back with future tooling;
 // today we only read.

package/src/core/stores/sessions-search.js

@@ -0,0 +1,121 @@
+// Cross-agent, cross-conversation session search + locator.
+// Walks the on-disk session and conversation files for each project and
+// returns matches with a small excerpt window. Used by the HTTP adapter and
+// (planned) CLI session find.
+import fs from "node:fs";
+import path from "node:path";
+import { apcAgentsDir } from "../apc/paths.js";
+
+const EXCERPT_CHARS = 300;
+const EXCERPT_LINES_BEFORE = 1;
+const EXCERPT_LINES_AFTER = 3;
+
+function scanFile(filePath, needle) {
+  try {
+    const text = fs.readFileSync(filePath, "utf8");
+    if (!text.toLowerCase().includes(needle)) return null;
+    const lines = text.split("\n");
+    const matchLine = lines.findIndex((l) => l.toLowerCase().includes(needle));
+    const excerpt = lines
+      .slice(Math.max(0, matchLine - EXCERPT_LINES_BEFORE), matchLine + EXCERPT_LINES_AFTER)
+      .join("\n");
+    return excerpt.slice(0, EXCERPT_CHARS);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Search for `needle` across one project's session + conversation files.
+ *
+ * @param project   { id, path, storagePath } record from ProjectManager
+ * @param needle    lowercase query string
+ * @param remaining max matches to add (search short-circuits when reached)
+ * @returns matches array (may be empty)
+ */
+export function searchProjectSessions(project, needle, remaining) {
+  const matches = [];
+  if (!project || remaining <= 0) return matches;
+
+  // 1) Legacy session files in the repo (.apc/agents/<slug>/sessions/)
+  const sessionAgentsDir = apcAgentsDir(project.path);
+  if (fs.existsSync(sessionAgentsDir)) {
+    for (const slug of fs.readdirSync(sessionAgentsDir)) {
+      const sessionsDir = path.join(sessionAgentsDir, slug, "sessions");
+      if (!fs.existsSync(sessionsDir)) continue;
+      for (const f of fs.readdirSync(sessionsDir).filter((x) => x.endsWith(".md"))) {
+        const filePath = path.join(sessionsDir, f);
+        const excerpt = scanFile(filePath, needle);
+        if (excerpt != null) {
+          matches.push({
+            type: "session",
+            project: project.id,
+            agent: slug,
+            filename: f,
+            path: filePath,
+            excerpt,
+          });
+          if (matches.length >= remaining) return matches;
+        }
+      }
+    }
+  }
+
+  // 2) Conversation files in daemon storage (~/.apx/projects/<id>/agents/<slug>/conversations/)
+  const convAgentsDir = path.join(project.storagePath, "agents");
+  if (fs.existsSync(convAgentsDir)) {
+    for (const slug of fs.readdirSync(convAgentsDir)) {
+      const convDir = path.join(convAgentsDir, slug, "conversations");
+      if (!fs.existsSync(convDir)) continue;
+      for (const f of fs.readdirSync(convDir).filter((x) => x.endsWith(".md"))) {
+        const filePath = path.join(convDir, f);
+        const excerpt = scanFile(filePath, needle);
+        if (excerpt != null) {
+          matches.push({
+            type: "conversation",
+            project: project.id,
+            agent: slug,
+            filename: f,
+            path: filePath,
+            excerpt,
+          });
+          if (matches.length >= remaining) return matches;
+        }
+      }
+    }
+  }
+
+  return matches;
+}
+
+/** Run searchProjectSessions across an array of projects, capping at `limit`. */
+export function searchSessions(projectList, query, limit) {
+  const needle = String(query || "").toLowerCase();
+  const matches = [];
+  for (const p of projectList) {
+    if (!p) continue;
+    const remaining = limit - matches.length;
+    if (remaining <= 0) break;
+    matches.push(...searchProjectSessions(p, needle, remaining));
+  }
+  return matches.slice(0, limit);
+}
+
+/**
+ * Find the conversation file (under daemon storage) for a given session id,
+ * scanning a list of candidate projects. Returns { project, agentSlug, filename }
+ * or null. `id` is taken as bare or with .md suffix.
+ */
+export function findSessionFile(projectList, id) {
+  const filename = id.endsWith(".md") ? id : `${id}.md`;
+  for (const p of projectList) {
+    if (!p) continue;
+    const agentsDir = path.join(p.storagePath, "agents");
+    if (!fs.existsSync(agentsDir)) continue;
+    for (const slug of fs.readdirSync(agentsDir)) {
+      const f = path.join(agentsDir, slug, "conversations", filename);
+      if (fs.existsSync(f)) return { project: p, agentSlug: slug, filename };
+    }
+  }
+  return null;
+}

package/src/core/stores/sessions.js

@@ -4,6 +4,11 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { nowIso } from "../util/time.js";
+
+export function agentSessionsDir(storageRoot, agentSlug) {
+  return path.join(storageRoot, "agents", agentSlug, "sessions");
+}
 
 export function generateSessionId(storageRoot, agentSlug) {
   const today = new Date().toISOString().slice(0, 10);
@@ -34,3 +39,36 @@ export function readSessionFrontmatter(filePath) {
   }
   return { fm, body: text.slice(end + 4).replace(/^\n+/, "") };
 }
+
+function slugifyTitle(title) {
+  return (
+    String(title || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "") || "session"
+  );
+}
+
+/**
+ * Create a new dated session file under
+ * `<storageRoot>/agents/<agentSlug>/sessions/YYYY-MM-DD-<titleSlug>.md`,
+ * with collision suffix (`-2`, `-3`, …) and standard frontmatter.
+ * Returns { filename, path, started }.
+ */
+export function createAgentSessionFile(storageRoot, agentSlug, { title, body = "" }) {
+  if (!title) throw new Error("createAgentSessionFile: title required");
+  const dir = agentSessionsDir(storageRoot, agentSlug);
+  fs.mkdirSync(dir, { recursive: true });
+  const titleSlug = slugifyTitle(title);
+  const today = new Date().toISOString().slice(0, 10);
+  let candidate = path.join(dir, `${today}-${titleSlug}.md`);
+  let n = 2;
+  while (fs.existsSync(candidate)) {
+    candidate = path.join(dir, `${today}-${titleSlug}-${n}.md`);
+    n++;
+  }
+  const started = nowIso();
+  const content = `---\ntitle: ${title}\nstarted: ${started}\n---\n\n# ${title}\n\n${body}\n`;
+  fs.writeFileSync(candidate, content);
+  return { filename: path.basename(candidate), path: candidate, started };
+}

package/src/core/vars/index.js

@@ -0,0 +1,14 @@
+export {
+  globalVarsPath,
+  projectVarsPath,
+  readGlobalVars,
+  writeGlobalVars,
+  readProjectVars,
+  writeProjectVars,
+  loadAllVars,
+  setVar,
+  deleteVar,
+  maskValue,
+} from "./sources.js";
+
+export { interpolate, findRefs, MissingVarError } from "./interpolate.js";

package/src/core/vars/interpolate.js

@@ -0,0 +1,86 @@
+// ${var.NAME} interpolation engine.
+//
+// Used at MCP boot (and any other site that opts in) so files committed to
+// the repo can hold references like
+//   "Authorization": "Bearer ${var.ASANA_TOKEN}"
+// while the real value lives in ~/.apx/vars.json or
+// <storagePath>/vars.json (see ./sources.js).
+//
+// Semantics:
+//   - Only top-level strings inside the input object/array are walked
+//     recursively. Numbers/booleans/null pass through.
+//   - A `${var.NAME}` token where NAME is missing throws a MissingVarError
+//     listing every missing name (so the UI can show a single useful message
+//     instead of "first failure wins").
+//   - Names match [A-Z0-9_] / [a-z0-9_] / dot — we don't enforce a charset
+//     beyond "no whitespace and no closing brace". Stay liberal here, strict
+//     at the UI.
+
+const VAR_RE = /\$\{var\.([^}\s]+)\}/g;
+
+export class MissingVarError extends Error {
+  constructor(missing) {
+    super(
+      `Undefined variable${missing.length > 1 ? "s" : ""}: ${missing
+        .map((n) => `\${var.${n}}`)
+        .join(", ")}`
+    );
+    this.name = "MissingVarError";
+    this.missing = missing;
+  }
+}
+
+// Collect every `${var.NAME}` reference found in `value` (deep walk).
+// Returns an array of unique names in encounter order.
+export function findRefs(value) {
+  const seen = new Set();
+  const walk = (v) => {
+    if (typeof v === "string") {
+      let m;
+      VAR_RE.lastIndex = 0;
+      while ((m = VAR_RE.exec(v)) !== null) seen.add(m[1]);
+      return;
+    }
+    if (Array.isArray(v)) {
+      for (const x of v) walk(x);
+      return;
+    }
+    if (v && typeof v === "object") {
+      for (const x of Object.values(v)) walk(x);
+    }
+  };
+  walk(value);
+  return Array.from(seen);
+}
+
+// Replace every `${var.NAME}` inside `value` using the `vars` lookup. Missing
+// names accumulate and surface as a single MissingVarError at the end so
+// callers can show "missing: TOKEN_A, TOKEN_B" in one shot.
+export function interpolate(value, vars) {
+  const missing = new Set();
+
+  const replaceString = (s) => {
+    return s.replace(VAR_RE, (_, name) => {
+      if (Object.prototype.hasOwnProperty.call(vars, name)) {
+        return String(vars[name]);
+      }
+      missing.add(name);
+      return _;
+    });
+  };
+
+  const walk = (v) => {
+    if (typeof v === "string") return replaceString(v);
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === "object") {
+      const out = {};
+      for (const [k, x] of Object.entries(v)) out[k] = walk(x);
+      return out;
+    }
+    return v;
+  };
+
+  const result = walk(value);
+  if (missing.size) throw new MissingVarError(Array.from(missing));
+  return result;
+}

package/src/core/vars/sources.js

@@ -0,0 +1,151 @@
+// Variable storage for APX. Two scopes:
+//   global  — ~/.apx/vars.json                              (chmod 0600)
+//   project — <storagePath>/vars.json                       (chmod 0600)
+//             i.e. ~/.apx/projects/<apxId>/vars.json
+//
+// Both files live outside the project repo so values never get committed.
+// The .apc/ files committed to the repo only reference vars by name
+// (e.g. `${var.ASANA_TOKEN}`) — actual values live here.
+//
+// Each file is a flat object: { "NAME": "value", ... }. Names are
+// uppercase letters / digits / underscore by convention (we don't enforce it
+// — anything safe to interpolate works).
+//
+// project wins over global when the same name exists in both.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const APX_HOME = path.join(os.homedir(), ".apx");
+const GLOBAL_VARS_FILE = path.join(APX_HOME, "vars.json");
+const PROJECT_VARS_FILENAME = "vars.json";
+
+export function globalVarsPath() {
+  return GLOBAL_VARS_FILE;
+}
+
+export function projectVarsPath(storagePath) {
+  if (!storagePath) return null;
+  return path.join(storagePath, PROJECT_VARS_FILENAME);
+}
+
+function readJsonSafe(absPath) {
+  if (!absPath || !fs.existsSync(absPath)) return {};
+  try {
+    const json = JSON.parse(fs.readFileSync(absPath, "utf8"));
+    return json && typeof json === "object" && !Array.isArray(json) ? json : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeJsonSecure(absPath, obj) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(obj, null, 2) + "\n");
+  try {
+    fs.chmodSync(absPath, 0o600);
+  } catch {
+    // Best effort on non-POSIX filesystems.
+  }
+}
+
+export function readGlobalVars() {
+  return readJsonSafe(GLOBAL_VARS_FILE);
+}
+
+export function writeGlobalVars(obj) {
+  writeJsonSecure(GLOBAL_VARS_FILE, obj);
+}
+
+export function readProjectVars(storagePath) {
+  return readJsonSafe(projectVarsPath(storagePath));
+}
+
+export function writeProjectVars(storagePath, obj) {
+  if (!storagePath) throw new Error("writeProjectVars: storagePath required");
+  writeJsonSecure(projectVarsPath(storagePath), obj);
+}
+
+function sanitizeMap(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    out[k] = String(v)
+      .replace(/[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/g, "")
+      .replace(/\u00A0/g, " ")
+      .trim();
+  }
+  return out;
+}
+
+// Aggregate project + global with project winning.
+// Returns { project, global, effective, sources } where sources[name] is
+// "project" or "global" so callers know where each effective value came from.
+// Values are sanitized at read time so legacy entries written before the
+// save-time trim land also come out clean.
+export function loadAllVars({ storagePath } = {}) {
+  const project = sanitizeMap(storagePath ? readProjectVars(storagePath) : {});
+  const global = sanitizeMap(readGlobalVars());
+  const effective = { ...global, ...project };
+  const sources = {};
+  for (const name of Object.keys(global)) sources[name] = "global";
+  for (const name of Object.keys(project)) sources[name] = "project";
+  return { project, global, effective, sources };
+}
+
+// Strip leading/trailing whitespace + invisible chars (ZWSP, BOM, …). The #1
+// reason a pasted token "doesn't work" is a stray newline picked up from the
+// copy buffer; defaulting to trim removes that whole class of bugs while
+// leaving real values untouched.
+function sanitizeVarValue(raw) {
+  return String(raw)
+    .replace(/[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/g, "")
+    .replace(/\u00A0/g, " ")
+    .trim();
+}
+
+// Convenience: set/unset on either scope. Returns the new full object.
+export function setVar({ storagePath, scope, name, value }) {
+  const v = sanitizeVarValue(value);
+  if (scope === "project") {
+    if (!storagePath) throw new Error("project scope requires storagePath");
+    const obj = readProjectVars(storagePath);
+    obj[name] = v;
+    writeProjectVars(storagePath, obj);
+    return obj;
+  }
+  if (scope === "global") {
+    const obj = readGlobalVars();
+    obj[name] = v;
+    writeGlobalVars(obj);
+    return obj;
+  }
+  throw new Error(`unknown scope "${scope}"`);
+}
+
+export function deleteVar({ storagePath, scope, name }) {
+  if (scope === "project") {
+    if (!storagePath) throw new Error("project scope requires storagePath");
+    const obj = readProjectVars(storagePath);
+    if (!(name in obj)) return false;
+    delete obj[name];
+    writeProjectVars(storagePath, obj);
+    return true;
+  }
+  if (scope === "global") {
+    const obj = readGlobalVars();
+    if (!(name in obj)) return false;
+    delete obj[name];
+    writeGlobalVars(obj);
+    return true;
+  }
+  throw new Error(`unknown scope "${scope}"`);
+}
+
+// Mask helper for read paths — never send the raw value to the UI by default.
+export function maskValue(value) {
+  if (value == null) return "";
+  const s = String(value);
+  if (s.length <= 4) return "•".repeat(s.length);
+  return "•".repeat(Math.min(s.length - 4, 8)) + s.slice(-4);
+}