@agentprojectcontext/apx 1.33.1 → 1.34.0

package/src/core/apc/scaffold.js

@@ -11,14 +11,22 @@ import {
 } from "./parser.js";
 import { readApcContextSkill } from "./skill-sync.js";
 import { nowIso } from "../util/time.js";
+import {
+  apcDir,
+  apcProjectFile,
+  apcAgentsDir,
+  apcAgentFile,
+  agentsMdFile,
+} from "./paths.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Now under src/core/apc/ — one more "../" to escape than before.
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..");
+// <packageRoot>/skills/<slug>/SKILL.md — the SLIM engine-side set: every skill
+// here is replicated verbatim into project IDE rule files (`apx skills add`) and
+// into ~/.<host>/skills/ (`apx skills sync`). The rich super-agent catalog lives
+// at src/core/runtime-skills/ and is intentionally NOT copied out.
 const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
-// runtime-skills lives at src/core/runtime-skills/, one level up from this
-// file's new home in src/core/apc/ (was a sibling before the Phase 3 move).
-const RUNTIME_SKILLS_DIR = path.join(__dirname, "..", "runtime-skills");
 
 export const SPEC_VERSION = "0.1.0";
 
@@ -28,12 +36,12 @@ export const SPEC_VERSION = "0.1.0";
 // install/update from the canonical APC repo (see src/interfaces/cli/postinstall.js).
 // ---------------------------------------------------------------------------
 
-// Bundled skills — apx lives in skills/apx/. apc-context is synced from
-// the canonical APC repo (../apc or GitHub) — never edited in APX.
+// Read one slim skill from <packageRoot>/skills/<slug>/SKILL.md. `apc-context`
+// is special-cased to refresh from the canonical APC repo if available.
 function readBundledSkill(slug) {
   if (slug === "apc-context") {
     const synced = readApcContextSkill();
-    return synced?.text || null;
+    if (synced?.text) return synced.text;
   }
   const file = path.join(BUNDLED_SKILLS_DIR, slug, "SKILL.md");
   if (!fs.existsSync(file)) return null;
@@ -134,19 +142,11 @@ const GLOBAL_SKILL_DIRS = [
   path.join(os.homedir(), ".agents", "skills"),    // Antigravity/other skills.sh adopters
 ];
 
-function readRuntimeSkillFiles() {
-  if (!fs.existsSync(RUNTIME_SKILLS_DIR)) return [];
-  return fs.readdirSync(RUNTIME_SKILLS_DIR)
-    .filter((name) => name.endsWith(".md"))
-    .sort()
-    .map((name) => ({
-      slug: path.basename(name, ".md"),
-      md: fs.readFileSync(path.join(RUNTIME_SKILLS_DIR, name), "utf8").trim(),
-    }));
-}
-
 // Install APX + APC context skills into IDE rule files. Returns an array of result objects.
 // targetIds: array of target ids to install; null = all project targets.
+// Writes the slim engine-side skill from <packageRoot>/skills/. The rich
+// super-agent set in src/core/runtime-skills/ is intentionally never written
+// into project IDE files.
 export function installIdeSkills(root, targetIds = null) {
   const apxRaw = readBundledSkill("apx");
   const apcRaw = readBundledSkill("apc-context");
@@ -197,36 +197,27 @@ export function installIdeSkills(root, targetIds = null) {
 // on the user's machine after `npm install -g .` (or `npm update -g apx`)
 // without anyone having to touch this file.
 //
-// Excluded: directory names starting with "." (e.g. .DS_Store), and any
-// runtime-only CLI skill that lives under src/core/runtime-skills/ — those
-// are loaded in-process at daemon startup and are NOT for IDE consumption.
-// Public: bundled skill slugs grouped by scope.
-//   public   → pushed to every global skill dir on install / sync (default).
-//   optional → not pushed by default; user opts in with --include-optional
-//              or `apx skills add <slug> --global` for one-off install.
-//   internal → APX-developer skills (mcp-builder, skill-builder, etc.); never
-//              pushed globally, only available to APX itself via the bundled
-//              copy. Avoids cluttering other IDEs with stuff their users won't
-//              run.
+// Excluded: directory names starting with "." (e.g. .DS_Store).
+// Every slug under <packageRoot>/skills/ is part of the slim engine set and
+// gets pushed to global dirs on `apx skills sync`. No scope filtering — the
+// dir IS the contract.
 export function listBundledSkillSlugs() {
   return discoverBundledSkills().map((s) => s.slug);
 }
 
 export function listBundledSkills() {
-  return discoverBundledSkills().map(({ slug, scope }) => ({ slug, scope }));
+  return discoverBundledSkills().map(({ slug }) => ({ slug }));
+}
+
+// Backwards-compat alias — every bundled slug here IS an engine slug now.
+export function listEngineSkills() {
+  return listBundledSkills();
 }
 
-// Tiny frontmatter peek — we only need the `scope:` field. Avoids pulling in
-// a full YAML parser for one optional line.
-function parseFrontmatterScope(md) {
-  if (!md.startsWith("---\n")) return "public";
-  const end = md.indexOf("\n---", 4);
-  if (end === -1) return "public";
-  const m = md.slice(4, end).match(/^scope:\s*(\w+)/m);
-  if (!m) return "public";
-  const s = m[1].toLowerCase();
-  if (s === "internal" || s === "optional" || s === "public") return s;
-  return "public";
+// Legacy slugs APX used to ship to global dirs but no longer does — exposed so
+// the CLI can report what `installGlobalSkills` will prune.
+export function listLegacyPruneSlugs() {
+  return [...PRUNE_LEGACY_SLUGS];
 }
 
 function discoverBundledSkills() {
@@ -239,65 +230,80 @@ function discoverBundledSkills() {
     const skillFile = path.join(root, entry.name, "SKILL.md");
     if (!fs.existsSync(skillFile)) continue;
     const md = fs.readFileSync(skillFile, "utf8");
-    out.push({ slug: entry.name, md, scope: parseFrontmatterScope(md) });
+    out.push({ slug: entry.name, md });
   }
   return out.sort((a, b) => a.slug.localeCompare(b.slug));
 }
 
-// Install bundled skills to every global ~/.../skills/ dir so Claude Code,
-// Cursor, Codex, and other IDEs see them.
+// Install the slim engine skill set to every global ~/.../skills/ dir
+// (Claude Code, Cursor, Codex, Antigravity/skills.sh). External engines only
+// need to know how to talk TO apx — not the full APX sub-skill catalog. The
+// rich bundled set in skills/<slug>/ stays in-repo for the APX super-agent.
+//
+// The set lives at skills/engines/<slug>/SKILL.md and is currently:
+//   apx, apx-mcp, apc-context.
 //
-// By default only `scope: public` skills land globally. Pass
-// includeOptional / includeInternal to push the other tiers (or call
-// `apx skills add <slug> --global` for a single one).
+// `includeOptional` / `includeInternal` are kept as no-op flags for backward
+// compatibility with `apx skills sync --include-…`; the slim set has no tiers.
 //
-// Pruning: if a slug that was previously installed has since been demoted to
-// internal/optional (or marked as non-public for the current call), we remove
-// the stale global copy unless prune=false. Keeps IDE skill lists clean.
+// Pruning: removes stale APX-shipped slugs that are no longer in the engine
+// set (the catalog of slugs APX has ever published, see PRUNE_LEGACY_SLUGS).
+// Skills the user installed themselves are NOT touched.
 //
 // Returns an array of { dir, skill, file, status, scope }.
-//   status ∈ {created, updated, unchanged, pruned, skipped}
+//   status ∈ {created, updated, unchanged, pruned}
+const PRUNE_LEGACY_SLUGS = [
+  "apx-agency-agents",
+  "apx-agent",
+  "apx-mcp-builder",
+  "apx-project",
+  "apx-routine",
+  "apx-runtime",
+  "apx-sessions",
+  "apx-skill-builder",
+  "apx-task",
+  "apx-telegram",
+  "apx-voice",
+  // Runtime CLI docs that previously leaked into global dirs — these are
+  // loaded in-process by the daemon and should NOT live on disk in IDE skill
+  // dirs.
+  "claude-code",
+  "codex-cli",
+  "opencode-cli",
+  "openrouter",
+];
+
 export function installGlobalSkills({
-  includeOptional = false,
-  includeInternal = false,
   prune = true,
+  // No-ops kept for CLI backward compatibility (the slim engine set has no tiers).
+  includeOptional: _includeOptional = false,
+  includeInternal: _includeInternal = false,
 } = {}) {
-  const all = discoverBundledSkills();
-  const wanted = all.filter((s) => {
-    if (s.scope === "internal") return includeInternal;
-    if (s.scope === "optional") return includeOptional;
-    return true; // public
-  });
+  const wanted = discoverBundledSkills();
   const wantedSlugs = new Set(wanted.map((s) => s.slug));
-  const knownSlugs = new Set(all.map((s) => s.slug));
 
   const results = [];
   for (const base of GLOBAL_SKILL_DIRS) {
-    // Push the wanted set.
-    for (const { slug, md, scope } of wanted) {
+    for (const { slug, md } of wanted) {
       const dest = path.join(base, slug, "SKILL.md");
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       const existed = fs.existsSync(dest);
       const previous = existed ? fs.readFileSync(dest, "utf8") : null;
       if (previous === md) {
-        results.push({ dir: base, skill: slug, file: dest, status: "unchanged", scope });
+        results.push({ dir: base, skill: slug, file: dest, status: "unchanged", scope: "engine" });
         continue;
       }
       fs.writeFileSync(dest, md, "utf8");
-      results.push({ dir: base, skill: slug, file: dest, status: existed ? "updated" : "created", scope });
+      results.push({ dir: base, skill: slug, file: dest, status: existed ? "updated" : "created", scope: "engine" });
     }
-    // Prune anything WE shipped previously but should no longer be there
-    // (slug exists in the bundle but isn't `wanted` this run).
     if (prune) {
-      for (const { slug, scope } of all) {
+      for (const slug of PRUNE_LEGACY_SLUGS) {
         if (wantedSlugs.has(slug)) continue;
-        if (!knownSlugs.has(slug)) continue;
         const dest = path.join(base, slug, "SKILL.md");
         if (!fs.existsSync(dest)) continue;
         fs.unlinkSync(dest);
-        // Best-effort: drop the now-empty <slug>/ dir too.
         try { fs.rmdirSync(path.dirname(dest)); } catch {}
-        results.push({ dir: base, skill: slug, file: dest, status: "pruned", scope });
+        results.push({ dir: base, skill: slug, file: dest, status: "pruned", scope: "legacy" });
       }
     }
   }
@@ -423,7 +429,7 @@ function writeMigrateMd(apfDir, found) {
 // Get the stable APX storage ID for a project, generating one if it doesn't exist.
 // Called by the daemon when registering a project.
 export function getOrCreateApxId(root) {
-  const p = path.join(root, ".apc", "project.json");
+  const p = apcProjectFile(root);
   if (!fs.existsSync(p)) return null;
   let cfg;
   try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
@@ -439,7 +445,7 @@ export function initApf(directory, { name } = {}) {
   const root = path.resolve(directory);
   fs.mkdirSync(root, { recursive: true });
 
-  const apfDir = path.join(root, ".apc");
+  const apfDir = apcDir(root);
   fs.mkdirSync(path.join(apfDir, "agents"), { recursive: true });
   fs.mkdirSync(path.join(apfDir, "skills"), { recursive: true });
   fs.mkdirSync(path.join(apfDir, "commands"), { recursive: true });
@@ -469,7 +475,7 @@ export function initApf(directory, { name } = {}) {
     fs.writeFileSync(gitignore, APC_GITIGNORE);
   }
 
-  const agentsMd = path.join(root, "AGENTS.md");
+  const agentsMd = agentsMdFile(root);
   if (!fs.existsSync(agentsMd)) {
     fs.writeFileSync(agentsMd, AGENTS_MD_TEMPLATE);
   }
@@ -485,13 +491,13 @@ export function initApf(directory, { name } = {}) {
 }
 
 export function ensureAgentDir(root, slug) {
-  fs.mkdirSync(path.join(root, ".apc", "agents"), { recursive: true });
-  return path.join(root, ".apc", "agents");
+  fs.mkdirSync(apcAgentsDir(root), { recursive: true });
+  return apcAgentsDir(root);
 }
 
 // Write .apc/agents/<slug>.md — the canonical agent definition file.
 export function writeAgentFile(root, slug, fields, body = "") {
-  const dest = path.join(root, ".apc", "agents", `${slug}.md`);
+  const dest = apcAgentFile(root, slug);
   const lines = ["---"];
   const order = ["role", "model", "language", "description", "skills", "tools"];
   const written = new Set();
@@ -579,7 +585,7 @@ export function restoreVaultAgent(slug) {
 
 // Add a slug to the project's agents.imported list in project.json
 export function addImportedAgent(root, slug) {
-  const p = path.join(root, ".apc", "project.json");
+  const p = apcProjectFile(root);
   let cfg = {};
   try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
   if (!cfg.agents) cfg.agents = {};

package/src/core/apc/skill-sync.js

@@ -8,7 +8,10 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Repo root is three levels up, not two.
 export const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..");
 
+// Engine-side slim copy (replicated to ~/.<host>/skills/ by apx skills sync).
 export const APC_SKILL_REL = path.join("skills", "apc-context", "SKILL.md");
+// Runtime-internal copy (loaded by the super-agent — never published outside).
+export const APC_BUILTIN_SKILL_REL = path.join("src", "core", "runtime-skills", "apc-context", "SKILL.md");
 export const APC_SKILL_REMOTE =
   "https://raw.githubusercontent.com/agentprojectcontext/agentprojectcontext/main/skills/apc-context/SKILL.md";
 
@@ -95,5 +98,12 @@ export async function refreshApcContextSkill({ packageRoot = PACKAGE_ROOT, timeo
 
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   fs.writeFileSync(dest, text, "utf8");
+
+  // Keep the runtime-internal copy (src/core/runtime-skills/apc-context/) in
+  // sync — that's where the super-agent loads it from.
+  const builtinDest = path.join(packageRoot, APC_BUILTIN_SKILL_REL);
+  fs.mkdirSync(path.dirname(builtinDest), { recursive: true });
+  fs.writeFileSync(builtinDest, text, "utf8");
+
   return { ok: true, source, refreshed: true };
 }

package/src/{host/daemon/plugins → core/channels}/telegram/dispatch.js

@@ -1,10 +1,38 @@
 // Inbound Telegram update dispatcher.
 //
-// Extracted from the ChannelPoller class so the index.js stays under ~800
-// lines and the routing logic for text/photo/voice/document updates lives in
-// its own module. The function takes the poller instance as `self`; every
-// `this.X` in the original method becomes `self.X` here. The poller exposes
-// _handleUpdate as a thin facade that delegates to this function.
+// Extracted from the ChannelPoller class so index.js stays under ~800 lines
+// and the routing logic for text/photo/voice/document updates lives on its
+// own. Takes the poller instance as `self`; every `this.X` in the original
+// method becomes `self.X` here. The poller exposes _handleUpdate as a thin
+// facade that delegates to handleUpdate(this, u).
+//
+// IMPORTANT: this module needs the same imports the original index.js had
+// in module scope, because the extracted body references identifiers like
+// `appendGlobalMessage`, `CHANNELS`, `nowIso`, etc. Top-level imports here
+// keep that scope intact — earlier splits forgot them and the bug only
+// surfaced when a real telegram update arrived (ReferenceError at runtime).
+import path from "node:path";
+import { callEngine } from "#core/engines/index.js";
+import { runSuperAgent, isSuperAgentEnabled } from "#core/agent/super-agent.js";
+import { stripThinking } from "#core/util/thinking.js";
+import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
+import { compactChannelIfNeeded } from "#core/memory/index.js";
+import { readAgents } from "#core/apc/parser.js";
+import { buildAgentSystem } from "#core/agent/build-agent-system.js";
+import { transcribe as transcribeAudioFile } from "#core/voice/transcription.js";
+import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
+import { registerSender, resolveAllowedTools } from "#core/identity/telegram.js";
+import { buildRelationshipBlock } from "#core/agent/index.js";
+import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { tryResolveSkillCommand } from "#core/agent/skills/trigger.js";
+import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
+import * as askFlow from "./ask.js";
+import { buildTelegramMeta, resolveBotToken, sleep } from "./helpers.js";
+import { sendPhoto, sendVoice, sendDocument, sendAudio, downloadTelegramFile, API_BASE } from "./media.js";
+import { t, resolveLang } from "#core/i18n/index.js";
+
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
 export async function handleUpdate(self, u) {
     self.lastUpdateAt = nowIso();
@@ -259,7 +287,7 @@ export async function handleUpdate(self, u) {
     // honor it for future messages.
     if (isReset) {
       try {
-        const ack = "Done, context cleared. Starting fresh. What do you need?";
+        const ack = t("telegram.reset_ack", { lang: resolveLang(self.globalConfig) });
         await self._send({ chat_id, text: ack });
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,
@@ -343,15 +371,7 @@ export async function handleUpdate(self, u) {
     // short localized heads-up the moment real work starts (first tool_start),
     // but only if the agent didn't already write its own "on it" line.
     let sentHeadsUp = false;
-    const headsUpPhrase = () => {
-      const lang = (self.globalConfig?.user?.language || "es").slice(0, 2);
-      const byLang = {
-        es: "Dale, estoy con eso… 🛠️",
-        en: "On it — working on that… 🛠️",
-        pt: "Já estou nisso… 🛠️",
-      };
-      return byLang[lang] || byLang.es;
-    };
+    const headsUpPhrase = () => t("telegram.heads_up", { lang: resolveLang(self.globalConfig) });
     if (!replyText && isSuperAgentEnabled(self.globalConfig)) {
       const onEvent = async (ev) => {
         try {
@@ -523,7 +543,9 @@ export async function handleUpdate(self, u) {
     const finalClean = replyText ? stripThinking(replyText).trim() : "";
     let toSend = "";
     if (finalClean && finalClean !== lastStreamedText) toSend = finalClean;
-    else if (!finalClean && streamedCount === 0) toSend = "Listo.";
+    else if (!finalClean && streamedCount === 0) {
+      toSend = t("telegram.fallback_listo", { lang: resolveLang(self.globalConfig) });
+    }
 
     stopTyping();
     if (!toSend) return; // everything was already streamed — nothing left to send

package/src/core/config/index.js

@@ -6,6 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { APX_HOME, CONFIG_PATH } from "./paths.js";
 import { PERMISSION_MODES, DEFAULT_PERMISSION_MODE } from "../constants/permissions.js";
+import { agentsMdFile, apcProjectFile } from "../apc/paths.js";
 
 export {
   APX_HOME,
@@ -395,10 +396,10 @@ export function effectiveHost(cfg) {
 
 export function addProject(cfg, projectPath) {
   const abs = path.resolve(projectPath);
-  if (!fs.existsSync(path.join(abs, "AGENTS.md"))) {
+  if (!fs.existsSync(agentsMdFile(abs))) {
     throw new Error(`not an APC project: ${abs} (no AGENTS.md)`);
   }
-  if (!fs.existsSync(path.join(abs, ".apc", "project.json"))) {
+  if (!fs.existsSync(apcProjectFile(abs))) {
     throw new Error(`not an APC project: ${abs} (no .apc/project.json)`);
   }
   const exists = cfg.projects.find((p) => path.resolve(p.path) === abs);

package/src/core/config/redact.js

@@ -0,0 +1,95 @@
+// Secret redaction for the global config. Wraps any string secret with a
+// `*** set *** (...<suffix>)` marker so the web admin can show "value is set"
+// without leaking it, AND so PATCH callers can echo back the marker to mean
+// "don't touch this one" — see isSecretMarker / mergeRedactedChannels below.
+//
+// The dotted paths in SECRET_PATHS are the single source of truth for "which
+// keys are secrets". Anything new (a new engine api_key, a new TTS provider
+// key, etc.) goes here and every redaction path picks it up.
+
+const SECRET_MARKER_PREFIX = "*** set ***";
+
+export const SECRET_PATHS = [
+  "engines.anthropic.api_key",
+  "engines.openai.api_key",
+  "engines.groq.api_key",
+  "engines.openrouter.api_key",
+  "engines.gemini.api_key",
+  "voice.tts.elevenlabs.api_key",
+  "voice.tts.openai.api_key",
+  "voice.tts.gemini.api_key",
+  "memory.embeddings.openai.api_key",
+  "memory.embeddings.gemini.api_key",
+  // Telegram bot tokens live inside an array — handled separately in redact()
+  // because dotted paths can't address array entries.
+  "telegram.channels.*.bot_token",
+];
+
+/** 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;
+  const suffix = value.slice(-5);
+  return `${SECRET_MARKER_PREFIX} (...${suffix})`;
+}
+
+/** True when a value is the placeholder a redacted view sends back unchanged. */
+export function isSecretMarker(value) {
+  return typeof value === "string" && value.startsWith(SECRET_MARKER_PREFIX);
+}
+
+/** Deep-copy of `cfg` with every secret string replaced by its marker. */
+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;
+    const parts = dotted.split(".");
+    let cur = out;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!cur[parts[i]] || typeof cur[parts[i]] !== "object") { cur = null; break; }
+      cur = cur[parts[i]];
+    }
+    if (cur && cur[parts[parts.length - 1]]) {
+      cur[parts[parts.length - 1]] = mark(cur[parts[parts.length - 1]]);
+    }
+  }
+  const channels = out?.telegram?.channels;
+  if (Array.isArray(channels)) {
+    for (const ch of channels) {
+      if (ch && typeof ch.bot_token === "string" && ch.bot_token.length) {
+        ch.bot_token = mark(ch.bot_token);
+      }
+    }
+  }
+  return out;
+}
+
+/** Redact a single Telegram channel record. */
+export function redactChannel(channel) {
+  if (!channel?.bot_token) return channel;
+  return { ...channel, bot_token: secretMarker(channel.bot_token) };
+}
+
+/**
+ * Merge a PATCH-shape `nextChannels` against the prior on-disk list. Any
+ * incoming channel whose bot_token is missing or a marker takes the prior
+ * token verbatim — so a UI that echoes the redacted view back doesn't wipe
+ * the real secret.
+ */
+export function mergeRedactedChannels(nextChannels, priorChannels) {
+  if (!Array.isArray(nextChannels)) return nextChannels;
+  const priorByName = new Map(
+    (Array.isArray(priorChannels) ? priorChannels : [])
+      .filter((c) => c && typeof c.name === "string")
+      .map((c) => [c.name, c])
+  );
+  return nextChannels.map((channel) => {
+    if (!channel || typeof channel !== "object") return channel;
+    const prior = priorByName.get(channel.name);
+    if (prior?.bot_token && (channel.bot_token === undefined || isSecretMarker(channel.bot_token))) {
+      return { ...channel, bot_token: prior.bot_token };
+    }
+    return channel;
+  });
+}

package/src/core/constants/channels.js

@@ -16,4 +16,6 @@ export const CHANNELS = Object.freeze({
   DECK: "deck",               // Mobile cockpit dashboard
   DESKTOP: "desktop",         // Electron capsule (always voice mode)
   CODE: "code",               // `apx code` — terminal coding session
+  DIRECT: "direct",           // Planned: 1:1 channel that isn't a chat platform
+  WHATSAPP: "whatsapp",       // Planned: WhatsApp bot integration
 });

package/src/core/constants/code-modes.js

@@ -0,0 +1,10 @@
+// Code session modes. PLAN = read-only exploration (the agent proposes
+// changes but never mutates); BUILD = unrestricted execution. The value
+// lives in code-sessions.json (session.mode) and is what api/code.js,
+// stores/code-sessions.js, and agent/prompts/modes/ all branch on.
+export const CODE_MODES = Object.freeze({
+  PLAN: "plan",
+  BUILD: "build",
+});
+
+export const DEFAULT_CODE_MODE = CODE_MODES.BUILD;

package/src/core/constants/index.js

@@ -3,3 +3,4 @@ export * from "./permissions.js";
 export * from "./channels.js";
 export * from "./roles.js";
 export * from "./actors.js";
+export * from "./code-modes.js";