@agentprojectcontext/apx 1.33.1 → 1.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.33.1",
+  "version": "1.35.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/skills/apx/SKILL.md

@@ -1,95 +1,83 @@
 ---
 name: apx
-description: "APX CLI umbrella — which sub-skill handles each operation (sessions, MCPs, routines, tasks, telegram, projects, agents, runtimes). Activate when the user mentions `apx`, the APX daemon, or wants to coordinate/run/delegate agents. Not for `.apc/` alone (use apc-context). Triggers: 'apx', 'apx run', 'apx daemon', 'coordinate agents', 'apx help'."
+description: >-
+  APX CLI — local daemon that orchestrates agents, sessions, MCPs, and channels across CLIs.
+  Use `apx exec "prompt"` for the local super-agent, or `apx run <agent> --runtime <claude-code|codex|opencode|aider|cursor-agent|gemini-cli|qwen-code> "prompt"` to hand the task to another CLI.
+  Activate on: 'apx', 'apx exec', 'apx run', 'apx daemon', 'ask codex/claude/opencode/gemini to …', 'have <runtime> do …', 'delegate to another runtime', 'run this in <runtime>', 'route this task to <runtime>'.
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
-# APX — Agent Project Context Runtime
+# APX — Agent Project Context Runtime (engine view)
 
-APX is a daemon (`127.0.0.1:7430`, auto-starts on first call) that turns external coding CLIs (Claude Code, Codex, OpenCode, Aider, …) and configurable agents into a unified orchestration surface.
+APX is a local daemon (`127.0.0.1:7430`, auto-starts on first call) that turns external coding CLIs (Claude Code, Codex, OpenCode, …) and configurable agents into a unified orchestration surface.
 
-It reads APC project context from `.apc/` (committed) but keeps runtime state outside the repo under `~/.apx/projects/<project-id>/`. The super-agent has a default workspace at `~/.apx/projects/default` for system-level work.
+This is the **engine-side** skill: a slim reference for runtimes invoked by APX. The full umbrella skill (with all sub-skills) lives in APX itself.
 
 ---
 
-## When to use APX (vs. spawning a subagent natively)
+## When you (as an engine) interact with APX
 
-If you can spawn a subagent natively in the IDE you're in (Claude Code, Cursor, …) — **do that**. No APX needed.
+- You were spawned by `apx run` — your CWD is a project and APX is reachable on `127.0.0.1:7430`.
+- The user asks you to call APX from inside your session ("send a telegram via apx", "list apx sessions").
+- You're inside an `.apc/` project and want to consult APX-managed state.
 
-Use APX when:
-- The user explicitly asks for a specific external runtime ("run this in Codex", "delegate to OpenCode").
-- You need to run an agent in a runtime different from the one you're in.
-- You're orchestrating from outside any IDE (a script, Telegram bot, CI, routine).
+If you can do the task natively (you're an IDE/CLI with your own tools), prefer that. Only shell out to `apx` when the task is APX-specific.
 
 ---
 
-## Sub-skill index — open the one that matches the task
+## Verify before recommending
 
-| Topic | Sub-skill | When |
-|-------|-----------|------|
-| Delegate to an external coding CLI | **apx-runtime** | `apx run <agent> --runtime claude-code\|codex\|...` |
-| List / read / resume / summarise / continue sessions across engines | **apx-sessions** | `apx session resume`, `apx sessions list`, "import a codex session" |
-| Use a registered MCP tool | **apx-mcp** | `apx mcp run`, "call MCP filesystem", "the MCP is failing" |
-| Add / configure / use a project agent | **apx-agent** | "add an agent", "import from vault", per-agent model, agent memory |
-| Register / list / configure a project | **apx-project** | "register this project", `apx project list`, per-project config |
-| Per-project TODO list | **apx-task** | "add a task", "remind me to…", "what's pending" |
-| Scheduled / recurring agents | **apx-routine** | `apx routine add`, every-5m, cron-like jobs |
-| Telegram I/O | **apx-telegram** | configure bot, channels, send a message |
-| Voice channel (TTS, speech) — *optional* | **apx-voice** | only if voice is being set up |
-| Build a new MCP server — *internal/dev* | **apx-mcp-builder** | when developing a brand-new MCP from scratch |
-| Author a new APX skill — *internal/dev* | **apx-skill-builder** | when adding to APX itself |
+Do not invent subcommands. Confirm exact form with:
 
-> Sub-skills marked *internal/dev* are not pushed to IDE skill dirs by default. They live in the APX repo and are loaded by APX itself; install one to your IDE with `apx skills add <slug> --global` if you want it there.
-
----
-
-## Generic patterns (apply to every sub-skill)
-
-### Verify commands before recommending them
-
-Do not invent APX subcommands. Confirm exact CLI form with `apx --help` or `apx <command> --help` before telling another runtime to invoke APX. Avoid guessed aliases (e.g. `apx send-telegram` is *not* a thing — see apx-telegram).
-
-### `APC_RESULT` contract — structured return values
-
-When you want APX to capture a structured value from an agent (any runtime), instruct the agent to print on its last meaningful line:
-
-```
-APC_RESULT: <one-line value>
+```bash
+apx --help
+apx <command> --help
 ```
 
-APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, and CI.
+---
 
-### Tool permissions
+## Core commands you'll actually use
 
 ```bash
-apx permission show
-apx permission set automatico   # total | automatico | permiso
+# Project + daemon
+apx status                      # daemon health
+apx project list                # registered projects
+apx project current             # which project resolves from CWD
+
+# Sessions (cross-engine)
+apx sessions list --engine <claude|codex|opencode> --project <name>
+apx sessions list --dir <path>
+
+# MCPs — see the apx-mcp skill for the full guide
+apx mcp list
+apx mcp run <name> <tool> '{"...":"..."}'
+
+# Memory (curated, durable facts only)
+apx memory <agent-slug>
+apx memory <agent-slug> --append "<fact>"
+
+# Observe activity
+apx messages tail
+apx messages chat --channel <name> -n 20
 ```
 
-`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP, runtime, outbound, config, or filesystem mutation actions.
+---
 
-### Memory
+## APC_RESULT contract
 
-Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
+When APX captures a structured value from your run, end with:
 
-```bash
-apx memory <slug>                       # read agent's memory.md
-apx memory <slug> --append "<fact>"     # append a durable note
-apx memory <slug> --replace < file.md  # replace entire memory from stdin
 ```
-
-### Observe activity
-
-```bash
-apx messages tail                               # last 50 messages, all channels
-apx messages chat --channel telegram -n 20      # readable chat view
-apx messages tail --channel runtime --agent <slug> -n 20
+APC_RESULT: <one-line value>
 ```
 
+`extractApfResult()` parses that and stores it as the session's `result`. Use it for routines, CI, automation.
+
 ---
 
 ## Anti-patterns
 
-- Don't activate APX-sessions inside a request that's purely about `apx run` orchestration — use apx-runtime.
-- Don't activate apx-mcp-builder unless the user is actually authoring a new MCP server (it's a deep developer guide, not a usage guide).
-- Don't push state to `.apc/` that belongs in `~/.apx/projects/<id>/` (sessions, conversations, runtime logs).
+- Don't write raw transcripts, sessions, or secrets into `.apc/` — they belong in `~/.apx/projects/<id>/`.
+- Don't guess subcommands. If `apx --help` doesn't show it, it doesn't exist.
+- Don't activate this skill for pure `.apc/` reading — that's [[apc-context]].
+- For MCP details (scopes, secrets, add/remove), open [[apx-mcp]] instead of guessing flags here.

package/src/core/agent/a2a/reply.js

@@ -0,0 +1,48 @@
+// Agent-to-agent (A2A) one-shot reply: given a sender + recipient agent and a
+// message body, build the recipient's system prompt and call the engine. Pure
+// orchestration over core/agent + core/engines — no HTTP, no message log
+// writes (the caller decides whether/where to persist).
+import fs from "node:fs";
+import { callEngine } from "../../engines/index.js";
+import { apcAgentMemoryFile } from "../../apc/paths.js";
+
+/**
+ * Build the recipient's system prompt for an A2A reply.
+ * Includes Description, Role, Language, a persona line naming the sender,
+ * and the recipient's memory.md if present.
+ */
+export function buildA2AReplySystem({ projectPath, toAgent, fromAgent }) {
+  const tf = toAgent?.fields || {};
+  const parts = [];
+  if (tf.Description) parts.push(tf.Description);
+  if (tf.Role) parts.push(`Role: ${tf.Role}`);
+  if (tf.Language) parts.push(`Default language: ${tf.Language}`);
+  parts.push(
+    `You are ${toAgent.slug}. You just received a message from ${fromAgent.slug}. Reply concisely.`
+  );
+  if (projectPath && toAgent.slug) {
+    const memPath = apcAgentMemoryFile(projectPath, toAgent.slug);
+    if (fs.existsSync(memPath)) {
+      parts.push("## Memory\n" + fs.readFileSync(memPath, "utf8"));
+    }
+  }
+  return parts.join("\n\n");
+}
+
+/**
+ * Run one A2A turn: build system, call engine, return { text, usage }.
+ * Throws on engine failure — caller decides how to surface.
+ */
+export async function replyAsAgent({ projectPath, toAgent, fromAgent, body, config }) {
+  if (!toAgent?.fields?.Model) {
+    throw new Error(`agent ${toAgent?.slug || "?"} has no model`);
+  }
+  const system = buildA2AReplySystem({ projectPath, toAgent, fromAgent });
+  const result = await callEngine({
+    modelId: toAgent.fields.Model,
+    system,
+    messages: [{ role: "user", content: `From ${fromAgent.slug}:\n\n${body}` }],
+    config,
+  });
+  return { text: result.text, usage: result.usage };
+}

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

@@ -1,15 +1,26 @@
+// System prompt for project agents (Cody, Sofía, etc.). Shares the agent-base
+// + action discipline with the super-agent, layered with a project-agent role
+// delta plus the agent's own profile fields.
+//
+// When a project agent answers through a real user channel (Telegram, web,
+// desktop), pass `channel` / `channelMeta` / `sender` so the channel-context,
+// relationship and voice-mode / segmenting blocks come along — without that
+// the agent has no idea HOW the user is talking to it.
 import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { readAgentMemory } from "./memory.js";
-
-// Anti-ghost-response rules injected into every agent system prompt. The text
-// lives next to the agent prompts (src/core/agent/prompts/action-discipline.md)
-// so it can be edited without touching code. Cached at module load.
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ACTION_DISCIPLINE_RULES = fs
-  .readFileSync(path.join(__dirname, "prompts", "action-discipline.md"), "utf8")
-  .trimEnd();
+import { apcProjectFile, apcSkillFile } from "../apc/paths.js";
+import {
+  PROMPTS,
+  buildChannelContextBlock,
+  buildVoiceModeBlock,
+  buildRelationshipBlock,
+  buildUserContextBlock,
+  buildSegmentDiscipline,
+} from "./prompt-builder.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.
+const AGENT_BODY_MAX_CHARS = 6000;
 
 function listField(value) {
   if (Array.isArray(value)) return value.map(String).map((s) => s.trim()).filter(Boolean);
@@ -19,10 +30,10 @@ function listField(value) {
 function projectName(project) {
   if (project?.name) return project.name;
   try {
-    const meta = JSON.parse(fs.readFileSync(path.join(project.path, ".apc", "project.json"), "utf8"));
-    return meta.name || path.basename(project.path);
+    const meta = JSON.parse(fs.readFileSync(apcProjectFile(project.path), "utf8"));
+    return meta.name || project.path?.split("/").pop() || "";
   } catch {
-    return path.basename(project?.path || "");
+    return project?.path?.split("/").pop() || "";
   }
 }
 
@@ -30,80 +41,146 @@ export function agentSkills(agent) {
   return listField(agent?.fields?.Skills);
 }
 
+/**
+ * Build the system prompt for a project agent.
+ *
+ * @param project        { id, name, path, ... }
+ * @param agent          { slug, fields: { Description, Role, Language, Skills, Tools, ... }, body }
+ * @param opts
+ * @param opts.invocation  "engine" (direct LLM call), "telegram", "routine", etc.
+ * @param opts.runtime     external runtime name when relevant ("claude-code", …)
+ * @param opts.channel     surface the user is on (channels/<name>.md is layered in)
+ * @param opts.channelMeta meta for the channel template + `{voice: true}` flag
+ * @param opts.sender      resolved sender for the relationship block
+ * @param opts.caller      who invoked us (another agent slug, "user", "routine", …)
+ * @param opts.routine     routine name when invocation === "routine"
+ * @param opts.globalConfig used for user.language / user.locale / user.timezone
+ * @param opts.extraParts  additional blocks to append before discipline
+ */
 export function buildAgentSystem(project, agent, {
   invocation = "engine",
   runtime = null,
   channel = null,
+  channelMeta = {},
+  sender = null,
   caller = null,
   routine = null,
+  globalConfig = {},
   extraParts = [],
 } = {}) {
   const fields = agent.fields || {};
-  const parts = [
-    `You are APC agent "${agent.slug}".`,
-    `Project: ${projectName(project)} (${project.path}).`,
-  ];
+  const channelLow = String(channel || "").toLowerCase();
+  const voice = !!channelMeta?.voice || channelLow === "voice";
 
-  if (fields.Description) parts.push(String(fields.Description));
-  if (fields.Role) parts.push(`Role: ${fields.Role}`);
-  if (fields.Language) parts.push(`Default language: ${fields.Language}`);
+  // Shared base + project-agent role delta (the "I'm scoped to one project" framing).
+  const roleBlock = [PROMPTS.AGENT_BASE, PROMPTS.PROJECT_AGENT_ROLE].join("\n\n");
 
-  const declaredTools = listField(fields.Tools);
-  if (declaredTools.length) {
-    parts.push(
-      [
-        "## Declared Tool Hints",
-        declaredTools.join(", "),
-        "These are agent-level tool expectations, not a guarantee. Actual callable tools depend on invocation surface.",
-      ].join("\n")
-    );
+  // Agent profile (its display name + description + Role + Language + owner from config).
+  const profileLines = [
+    `# Agent profile`,
+    `You are **${agent.slug}**, a project agent dedicated to **${projectName(project)}** (\`${project.path}\`).`,
+  ];
+  if (fields.Description) profileLines.push(fields.Description);
+  if (fields.Role) profileLines.push(`Role: ${fields.Role}`);
+  if (fields.Language) profileLines.push(`Default language: ${fields.Language}`);
+
+  // The agent's authored body (everything after the frontmatter in its
+  // `.apc/agents/<slug>.md`) is its real instruction set — persona, domain
+  // rules, API endpoints, tone, hard limits. Without injecting it the agent
+  // runs on its fields alone and loses everything its author actually wrote.
+  let customBody = String(agent.body || "").trim();
+  if (customBody.length > AGENT_BODY_MAX_CHARS) {
+    customBody = customBody.slice(0, AGENT_BODY_MAX_CHARS) + "\n\n…(instructions truncated)";
   }
+  const customInstructions = customBody ? `# Custom instructions\n${customBody}` : "";
 
-  parts.push(buildInvocationContext({ invocation, runtime, channel, caller, routine }));
-
-  const memory = readAgentMemory(project, agent.slug);
-  if (memory) parts.push("## Memory\n" + memory);
+  // User context (owner name, language, timezone) — same block the super-agent
+  // gets, so project agents know how to address the user.
+  const userContext = buildUserContextBlock(null, globalConfig, { agentName: agent.slug });
 
-  const apxSkill = path.join(project.path, ".apc", "skills", "apx.md");
-  if (fs.existsSync(apxSkill)) parts.push("## APX\n" + fs.readFileSync(apxSkill, "utf8"));
+  // Channel context — the same channels/*.md the super-agent uses. Project
+  // agents talk through the same surfaces; they need the same formatting rules.
+  const channelBlock = buildChannelContextBlock(channel, channelMeta);
+  const voiceBlock = buildVoiceModeBlock(voice);
+  const segmentDiscipline = buildSegmentDiscipline({ channel: channelLow, voice });
 
-  for (const skill of agentSkills(agent)) {
-    const skillPath = path.join(project.path, ".apc", "skills", `${skill}.md`);
-    if (fs.existsSync(skillPath)) parts.push(`## Skill: ${skill}\n` + fs.readFileSync(skillPath, "utf8"));
-  }
+  // Relationship block — "you're talking to <owner>" / "<contact>" / "<guest>".
+  const relationship = buildRelationshipBlock(sender);
 
-  for (const ep of extraParts) {
-    if (ep) parts.push(ep);
-  }
+  // Declared tool hints (informational — actual callables come from runtime).
+  const declaredTools = listField(fields.Tools);
+  const toolHints = declaredTools.length
+    ? [
+        "## Declared tool hints (agent-level expectations)",
+        declaredTools.join(", "),
+        "Actual callable tools depend on the invocation surface — use whatever the runtime sends this turn.",
+      ].join("\n")
+    : "";
 
-  // Always append action discipline rules last so they are close to the end
-  // of the system prompt and harder for the model to "forget".
-  parts.push(ACTION_DISCIPLINE_RULES);
+  // Invocation context (who called me, through what, for what).
+  const invocationCtx = buildInvocationContext({ invocation, runtime, caller, routine });
 
-  return parts.join("\n\n");
+  // Per-agent memory (lives under <project>/.apc/agents/<slug>/memory.md).
+  const memory = readAgentMemory(project, agent.slug);
+  const memoryBlock = memory ? "# Memory\n" + memory : "";
+
+  // Project's APX skill + agent's declared skills (loaded as full bodies — they're
+  // small and specific to this agent).
+  const projectSkills = buildProjectSkills(project, agent);
+
+  return [
+    roleBlock,
+    profileLines.join("\n"),
+    customInstructions,
+    userContext,
+    memoryBlock,
+    relationship,
+    channelBlock,
+    toolHints,
+    invocationCtx,
+    projectSkills,
+    ...extraParts.filter(Boolean),
+    voiceBlock,
+    PROMPTS.ACTION_DISCIPLINE,
+    segmentDiscipline,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
 }
 
-function buildInvocationContext({ invocation, runtime, channel, caller, routine }) {
-  const lines = [
-    "## Invocation Context",
-    `invocation: ${invocation}`,
-  ];
+function buildInvocationContext({ invocation, runtime, caller, routine }) {
+  const lines = [`## Invocation`, `invocation: ${invocation}`];
   if (runtime) lines.push(`runtime: ${runtime}`);
-  if (channel) lines.push(`channel: ${channel}`);
   if (caller) lines.push(`caller: ${caller}`);
   if (routine) lines.push(`routine: ${routine}`);
 
   if (runtime) {
     lines.push(
-      "You are running inside the named external runtime. Use only tools and permissions that runtime actually exposes."
+      "You're running inside the named external runtime. Use only tools and permissions that runtime exposes."
     );
-  } else if (invocation === "engine") {
-    lines.push("You are a direct LLM call through APX. Do not claim shell, file, MCP, or Telegram tools unless APX explicitly provided them.");
-  } else if (invocation === "telegram") {
-    lines.push("You are replying through Telegram. Keep responses brief, plain text, and matched to the user's language.");
   } else if (invocation === "routine") {
-    lines.push("You were invoked by an APX routine. Complete the requested work now; do not say you will do it later.");
+    lines.push(
+      "You were invoked by an APX routine. Complete the requested work now; don't say you will do it later."
+    );
+  } else if (invocation === "engine") {
+    lines.push(
+      "You're a direct LLM call through APX. Don't claim shell, file, MCP, or Telegram tools unless the runtime explicitly sent them this turn."
+    );
   }
-
   return lines.join("\n");
 }
+
+function buildProjectSkills(project, agent) {
+  const parts = [];
+  const apxSkill = apcSkillFile(project.path, "apx");
+  if (fs.existsSync(apxSkill)) {
+    parts.push("## APX\n" + fs.readFileSync(apxSkill, "utf8").trim());
+  }
+  for (const skill of agentSkills(agent)) {
+    const skillPath = apcSkillFile(project.path, skill);
+    if (fs.existsSync(skillPath)) {
+      parts.push(`## Skill: ${skill}\n` + fs.readFileSync(skillPath, "utf8").trim());
+    }
+  }
+  return parts.join("\n\n");
+}

package/src/core/agent/channels/voice-context.js

@@ -0,0 +1,98 @@
+// Channel-aware pre-processor for surfaces that drive the super-agent loop
+// from a voice/deck/desktop entrypoint.
+//
+// Each surface has different ergonomics: how long the reply can be, whether
+// the UI can render structured suggestion chips, what the default project
+// resolution should be. buildVoiceChannelContext() is the single place where
+// those decisions live. Callers (api/voice.js today; any future overlay or
+// device adapter tomorrow) pass the channel string + dynamic context and
+// receive the context note + system suffix to feed into the super-agent.
+//
+// Shape:
+//   contextNote   — prepended to the prompt (dynamic, per-request)
+//   systemSuffix  — concatenated onto the system prompt (per-surface rules)
+//   wantsSuggestions — whether the surface can render the trailing
+//                      `suggestions` JSON block (deck/desktop UI can; raw
+//                      Telegram cannot)
+//   channel       — resolved surface ("deck"/"desktop"/"telegram"/…)
+//   channelMeta   — surface metadata (e.g. `{ voice: true }` flags spoken mode)
+import { CHANNELS } from "../../constants/channels.js";
+
+// Balanced suggestions instruction. An earlier, more aggressive version
+// ("EJECUTA, no narres — LLAMÁ A LA TOOL") made Gemini call tools for
+// EVERYTHING, even "hola" → send_telegram("hola"). The rule below gates
+// tool use on a *clear* action request and explicitly tells the model to
+// just talk for chit-chat.
+export const SUGGESTIONS_INSTRUCTION = `
+
+# Cuándo usar tools
+SOLO llamá una tool cuando el usuario pide CLARAMENTE una acción
+concreta: "creá una tarea …", "mandá un telegram …", "listá …",
+"abrí …", "marcá como hecha …". En esos casos ejecutá la tool (no
+digas "lo voy a hacer" — hacelo) y después confirmá en una frase corta
+en castellano lo que YA hiciste.
+
+Si el mensaje es un saludo, una pregunta, o charla ("hola", "cómo
+andás", "qué podés hacer") NO llames ninguna tool: respondé en texto,
+breve, en castellano.
+
+Nunca llames la misma tool dos veces en el mismo turno.
+
+# Sugerencias (opcional)
+Al final, en su propia línea, podés agregar un bloque fenced
+\`suggestions\` con 2-3 próximos pasos. El usuario NO lo ve (la deck lo
+quita):
+\`\`\`suggestions
+[{"label":"Ver tareas","command":"deck.view:tasks"}]
+\`\`\`
+Si no hay próximos pasos útiles, omití el bloque.`;
+
+function buildLanguageDirective(language) {
+  return language === "es"
+    ? "IMPORTANT: Reply ALWAYS in Spanish (rioplatense/Argentina). The user speaks Spanish."
+    : `IMPORTANT: Reply in language "${language}".`;
+}
+
+function buildProjectHint(projectId) {
+  // Project resolution hint:
+  //   per-project mic (projectId set): use it imperatively, don't ask.
+  //   global deck mic (no projectId): default to project id=0 ("default")
+  //     for actions unless the user names a project out loud.
+  return projectId
+    ? `\nThe active project is id=${projectId}. For ANY task/note/list ` +
+      `action, pass project_id=${projectId} automatically. Do NOT ask the ` +
+      `user which project — only switch if they explicitly name another.`
+    : `\nThis is the GLOBAL mic (no project in focus). For task/note/list ` +
+      `actions, default to project_id=0 ("default") UNLESS the user names ` +
+      `a project out loud (e.g. "en evolution-registry…", "en el proyecto ` +
+      `apx…") — then resolve that project by name. Never ask "¿en qué ` +
+      `proyecto?"; pick the default and act.`;
+}
+
+export function buildVoiceChannelContext(channel, { projectId, language = "es" } = {}) {
+  const base = {
+    contextNote: "",
+    systemSuffix: "",
+    wantsSuggestions: false,
+    channel: "",
+    channelMeta: {},
+  };
+  const dynamicNote = `${buildLanguageDirective(language)}${buildProjectHint(projectId)}`;
+
+  // Channels are surfaces; "voice" is NOT a surface — it's the spoken MODE of
+  // the deck. All channel FORMATTING lives in channels/*.md + modes/voice.md
+  // (injected by buildSuperAgentSystem); contextNote here carries ONLY
+  // per-request dynamic bits (language + project).
+  switch (channel) {
+    case "voice":
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DECK, channelMeta: { voice: true } };
+    case CHANNELS.DECK:
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DECK, channelMeta: {} };
+    case CHANNELS.DESKTOP:
+      return { ...base, contextNote: dynamicNote, systemSuffix: SUGGESTIONS_INSTRUCTION, wantsSuggestions: true, channel: CHANNELS.DESKTOP, channelMeta: { voice: true } };
+    case CHANNELS.TELEGRAM:
+      return { ...base, contextNote: dynamicNote, channel: CHANNELS.TELEGRAM, channelMeta: {} };
+    default:
+      return { ...base, contextNote: dynamicNote, channel: channel || CHANNELS.API, channelMeta: {} };
+  }
+}

package/src/core/agent/memory.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { projectStorageRoot } from "../config/index.js";
 import { getOrCreateApxId } from "../apc/scaffold.js";
+import { apcAgentMemoryFile } from "../apc/paths.js";
 
 const EMPTY_MEMORY = (slug) =>
   `# Memory — ${slug}\n\n` +
@@ -27,7 +28,7 @@ export function agentMemoryPath(projectOrRoot, slug) {
 }
 
 export function legacyAgentMemoryPath(projectRoot, slug) {
-  return path.join(projectRoot, ".apc", "agents", slug, "memory.md");
+  return apcAgentMemoryFile(projectRoot, slug);
 }
 
 export function ensureAgentRuntimeDir(projectOrRoot, slug, { createMemory = false } = {}) {