@agentprojectcontext/apx 1.34.0 → 1.36.0

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

@@ -1,9 +1,18 @@
-// Prompt builder for the APX default agent — known internally as the
-// "super-agent". That name is a MODE descriptor (the daemon-level tool-using
-// loop that runs when no project agent is named), not a persona the user
-// should ever see. The model is told its real display name comes from
-// ~/.apx/identity.json; "super-agent" only appears in code, file paths, CLI
-// flags, and channel meta.
+// Unified prompt builder for ANY agent (super-agent OR project agent).
+//
+// The system prompt is assembled from layered fragments:
+//
+//   1. core/agent-base.md      common: tool usage, memory, hard rules — applies to every agent
+//   2. core/super-agent.md     OR  core/project-agent.md  — the role delta
+//   3. # Agent profile         identity (name, personality, owner, language)
+//   4. # Project / context     project pin, registered projects index, AGENTS.md
+//   5. # Memory                self-memory or relevant memory block, active threads
+//   6. # Channel               channel-specific formatting rules
+//   7. # Discipline            action.md + (two-segment OR single-segment) + voice mode
+//   8. # Suffix                channel-specific format directives (suggestions JSON, etc.)
+//
+// Sections are dropped when empty (no project context for super-agent on a
+// generic CLI call, no self-memory for project agents, etc.).
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,68 +20,66 @@ import { readIdentity } from "../identity/index.js";
 import { agentsMdFile } from "../apc/paths.js";
 import { readSelfMemoryForPrompt } from "./self-memory.js";
 import { buildSkillsHintBlock } from "./skills/catalog.js";
+import { CHANNELS } from "#core/constants/channels.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PROMPTS_DIR = path.join(__dirname, "prompts");
-const BASE_PROMPT_PATH = path.join(PROMPTS_DIR, "super-agent-base.md");
 
-// Action discipline + chit-chat rules — same file used by project agents
-// (buildAgentSystem in agent-system.js), loaded once here for the super-agent.
-const ACTION_DISCIPLINE = fs
-  .readFileSync(path.join(PROMPTS_DIR, "action-discipline.md"), "utf8")
-  .trimEnd();
-
-const promptCache = new Map();
-
-/** @deprecated use super-agent-base.md */
-const LEGACY_PROMPT_PATH = path.join(PROMPTS_DIR, "super-agent-default.md");
-
-// Channels are SURFACES (where the user is). Voice is NOT a channel — it's a
-// MODE that layers on top of a surface (see buildVoiceModeBlock); a spoken deck
-// turn is channel "deck" + voice mode, not its own channel.
+// Channels are SURFACES. Voice is NOT a channel — it's a MODE that layers on
+// top of a surface (see buildVoiceModeBlock); a spoken deck turn is channel
+// "deck" + voice mode, not its own channel.
 const CHANNEL_PROMPT_FILES = {
-  telegram: "channels/telegram.md",
-  cli: "channels/cli.md",
-  routine: "channels/routine.md",
-  api: "channels/api.md",
-  web: "channels/web.md",                 // web big chat (long-form, full tools)
-  web_sidebar: "channels/web_sidebar.md", // web quick chat (short, lightweight)
-  web_code: "channels/web_code.md",       // web Code module (rich coding session)
-  deck: "channels/deck.md",               // cockpit dashboard
-  desktop: "channels/desktop.md",         // PC floating module (was "overlay")
-  code: "channels/code.md",               // `apx code` — terminal coding session
+  [CHANNELS.TELEGRAM]: "channels/telegram.md",
+  [CHANNELS.CLI]: "channels/cli.md",
+  [CHANNELS.ROUTINE]: "channels/routine.md",
+  [CHANNELS.API]: "channels/api.md",
+  [CHANNELS.WEB]: "channels/web.md",
+  [CHANNELS.WEB_SIDEBAR]: "channels/web_sidebar.md",
+  [CHANNELS.WEB_CODE]: "channels/web_code.md",
+  [CHANNELS.DECK]: "channels/deck.md",
+  [CHANNELS.DESKTOP]: "channels/desktop.md",
+  [CHANNELS.CODE]: "channels/code.md",
 };
 
-// Voice mode: spoken-reply rules layered on any surface when the turn will be
-// read aloud by TTS (deck voice overlay, desktop module, etc). Injected with
-// high recency (right before systemSuffix) so weaker models don't bury it.
+// Channels where the user CAN see two text segments per turn (chat history is
+// visible). Voice / single-surface channels get single-segment discipline.
+const TWO_SEGMENT_CHANNELS = new Set([
+  CHANNELS.TELEGRAM,
+  CHANNELS.WEB,
+  CHANNELS.WEB_SIDEBAR,
+  CHANNELS.WEB_CODE,
+  CHANNELS.CODE,
+  CHANNELS.API,
+  CHANNELS.CLI,
+]);
+
 const VOICE_MODE_FILE = "modes/voice.md";
 
-export function buildVoiceModeBlock(active) {
-  if (!active) return "";
-  try {
-    return loadPrompt(VOICE_MODE_FILE);
-  } catch {
-    return "";
-  }
-}
+// ---------------------------------------------------------------------------
+// Prompt loading
+// ---------------------------------------------------------------------------
+
+const promptCache = new Map();
 
 export function loadPrompt(relativePath) {
   const key = relativePath.replace(/\\/g, "/");
   if (promptCache.has(key)) return promptCache.get(key);
-  const full = path.join(PROMPTS_DIR, key);
-  const text = fs.readFileSync(full, "utf8");
+  const text = fs.readFileSync(path.join(PROMPTS_DIR, key), "utf8").trimEnd();
   promptCache.set(key, text);
   return text;
 }
 
+const AGENT_BASE         = loadPrompt("core/agent-base.md");
+const SUPER_AGENT_ROLE   = loadPrompt("core/super-agent.md");
+const PROJECT_AGENT_ROLE = loadPrompt("core/project-agent.md");
+const ACTION_DISCIPLINE  = loadPrompt("discipline/action.md");
+const TWO_SEGMENT        = loadPrompt("discipline/two-segment.md");
+const SINGLE_SEGMENT     = loadPrompt("discipline/single-segment.md");
+
+// Back-compat shim — a few callers/tests still want the raw default prompt.
 export function loadDefaultSystemPrompt() {
-  if (fs.existsSync(BASE_PROMPT_PATH)) return loadPrompt("super-agent-base.md");
-  if (fs.existsSync(LEGACY_PROMPT_PATH)) return loadPrompt("super-agent-default.md");
-  throw new Error("super-agent base prompt not found");
+  return [AGENT_BASE, SUPER_AGENT_ROLE].join("\n\n");
 }
-
-/** @deprecated use loadDefaultSystemPrompt — kept for tests/imports */
 export const DEFAULT_SYSTEM = loadDefaultSystemPrompt();
 
 export function renderPromptTemplate(template, vars = {}) {
@@ -82,19 +89,40 @@ export function renderPromptTemplate(template, vars = {}) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Channel + mode blocks
+// ---------------------------------------------------------------------------
+
 export function buildChannelContextBlock(channel, meta = {}) {
   const rel = CHANNEL_PROMPT_FILES[String(channel || "").toLowerCase()];
   if (!rel) return "";
   return renderPromptTemplate(loadPrompt(rel), meta);
 }
 
-// Project startup rules. When APX runs its OWN loop inside a project, load that
-// project's AGENTS.md into the prompt — the same convention Claude/Codex follow
-// with CLAUDE.md/AGENTS.md. `projectPath` flows in via channelMeta.projectPath
-// (set by the super-agent API, the code module, and routines). This is wired
-// ONLY into the super-agent prompt: when APX delegates to an external engine,
-// that engine reads AGENTS.md itself. Size-capped to protect the prompt budget.
+export function buildVoiceModeBlock(active) {
+  if (!active) return "";
+  try {
+    return loadPrompt(VOICE_MODE_FILE);
+  } catch {
+    return "";
+  }
+}
+
+// Pick the right segmenting discipline for the channel (and whether voice
+// mode overrides it).
+function buildSegmentDiscipline({ channel, voice }) {
+  if (voice) return SINGLE_SEGMENT;
+  if (TWO_SEGMENT_CHANNELS.has(String(channel || "").toLowerCase())) return TWO_SEGMENT;
+  // routine / deck / desktop / unknown → single-segment (single visible reply)
+  return SINGLE_SEGMENT;
+}
+
+// ---------------------------------------------------------------------------
+// Project guidance — AGENTS.md of the pinned project, size-capped.
+// ---------------------------------------------------------------------------
+
 export const PROJECT_AGENTS_MAX_CHARS = 6000;
+
 export function buildProjectAgentsBlock(projectPath) {
   if (!projectPath) return "";
   try {
@@ -111,13 +139,17 @@ export function buildProjectAgentsBlock(projectPath) {
   }
 }
 
-export function buildUserContextBlock(identity, globalConfig = {}) {
+// ---------------------------------------------------------------------------
+// Identity / user / relationship blocks (shared across agents)
+// ---------------------------------------------------------------------------
+
+export function buildUserContextBlock(identity, globalConfig = {}, { agentName } = {}) {
   const user = globalConfig?.user || {};
   const lang = user.language || identity?.language || "en";
-  const lines = ["# User & identity"];
+  const lines = ["# Agent profile"];
 
-  const agentName = identity?.agent_name || globalConfig?.super_agent?.name;
-  if (agentName) lines.push(`Your name is ${agentName}.`);
+  const name = agentName || identity?.agent_name || globalConfig?.super_agent?.name;
+  if (name) lines.push(`Your name is ${name}.`);
   if (identity?.personality) lines.push(`Your personality: ${identity.personality}.`);
   if (identity?.owner_name) lines.push(`Your owner is ${identity.owner_name}.`);
   if (identity?.owner_context) lines.push(`Owner context: ${identity.owner_context}`);
@@ -125,9 +157,7 @@ export function buildUserContextBlock(identity, globalConfig = {}) {
   lines.push(
     `Reply in the language with ISO 639-1 code "${lang}" unless the user explicitly switches language for that turn.`
   );
-  if (user.locale) {
-    lines.push(`Preferred locale or dialect: ${user.locale}.`);
-  }
+  if (user.locale) lines.push(`Preferred locale or dialect: ${user.locale}.`);
   if (user.timezone) {
     lines.push(
       `User timezone: ${user.timezone}. Use it for local time and schedules unless the user specifies otherwise.`
@@ -137,15 +167,13 @@ export function buildUserContextBlock(identity, globalConfig = {}) {
   return lines.join("\n");
 }
 
-/** Back-compat wrapper — second arg is ISO language only (no full config). */
+/** Back-compat wrapper — second arg is ISO language only. */
 export function buildIdentityBlock(identity, userLang = "en") {
   return buildUserContextBlock(identity, { user: { language: userLang } });
 }
 
-// "Who you're talking to" block. Agent-agnostic: built once from the resolved
-// sender (see core/identity/telegram.js) and injected into BOTH the super-agent
-// prompt and any routed project-agent prompt, so identification doesn't depend
-// on which agent answers. Returns "" when there's no sender info.
+// "Who you're talking to" block — agent-agnostic, built once from the resolved
+// sender (see core/identity/telegram.js). Returns "" when there's no sender.
 export function buildRelationshipBlock(sender) {
   if (!sender || sender.userId == null) return "";
   const handle = sender.username ? ` (@${sender.username})` : "";
@@ -155,41 +183,30 @@ export function buildRelationshipBlock(sender) {
     lines.push(
       "This is a Telegram GROUP chat with multiple people — do NOT assume a single owner."
     );
-    lines.push(
-      `Sender of this message: ${sender.name}${handle}, role: ${sender.role}.`
-    );
+    lines.push(`Sender of this message: ${sender.name}${handle}, role: ${sender.role}.`);
   } else if (sender.isOwner) {
     lines.push(
-      `You are talking to your owner, ${sender.name}. Treat them as the owner — ` +
-        "never ask their name or who they are; you already know them."
+      `You are talking to your owner, ${sender.name}. Treat them as the owner — never ask their name or who they are.`
     );
   } else if (sender.role && sender.role !== "guest") {
     lines.push(`You are talking to ${sender.name}${handle}, role: ${sender.role}.`);
   } else {
     lines.push(
-      `You are talking to ${sender.name}${handle}, who is NOT a recognized contact ` +
-        "(role: guest, no permissions)."
-    );
-    lines.push(
-      "Politely say you don't know them yet and ask who they are; tell them you'll " +
-        "note it down, but that you cannot grant any role or permissions yourself — " +
-        "only the owner or someone via terminal/web can assign a role. Do not perform " +
-        "privileged or destructive actions on their behalf."
+      `You are talking to ${sender.name}${handle} (role: guest, no permissions). Politely ask who they are — you'll note it down but cannot grant any role yourself.`
     );
   }
   if (sender.note) lines.push(`Notes on this contact: ${sender.note}`);
   return lines.join("\n");
 }
 
-// The super-agent's own notebook (~/.apx/memory.md), bounded for the prompt.
-// Returns "" when empty so the block is dropped entirely.
+// Super-agent notebook (~/.apx/memory.md), bounded. Returns "" when empty.
+// Project agents have their own per-agent memory.md handled in buildAgentSystem.
 export function buildSelfMemoryBlock() {
   const slice = readSelfMemoryForPrompt();
   if (!slice) return "";
   return [
-    "# Your notebook (self-memory)",
-    "Durable things you chose to remember across sessions. Treat as known facts;",
-    "update with the `remember` tool. Call read_self_memory if this looks truncated.",
+    "# Notebook",
+    "Durable facts you chose to remember. Update with the `remember` tool. Read full with `read_self_memory` if truncated.",
     "",
     slice,
   ].join("\n");
@@ -201,6 +218,26 @@ export function isSuperAgentEnabled(cfg) {
   return sa.enabled !== false;
 }
 
+// ---------------------------------------------------------------------------
+// Project index — renders the registered-project list cleanly when relevant.
+// Omits the [kind] prefix when kind="default" so we don't get `[default] "default"`.
+// ---------------------------------------------------------------------------
+
+function buildProjectIndex(projects) {
+  const list = projects?.list?.() || [];
+  if (!list.length) return "";
+  const lines = list.map((p) => {
+    if (p.id === 0) return `  ${p.id}: "${p.name}" (global workspace, ${p.path})`;
+    const kindTag = p.kind && p.kind !== "default" && p.kind !== "other" ? ` [${p.kind}]` : "";
+    return `  ${p.id}:${kindTag} "${p.name}" (${p.path})`;
+  });
+  return ["# Registered projects (index only — call tools for details)", ...lines].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Super-agent system prompt
+// ---------------------------------------------------------------------------
+
 export function buildSuperAgentSystem({
   globalConfig,
   projects,
@@ -208,67 +245,83 @@ export function buildSuperAgentSystem({
   contextNote = "",
   channel = "",
   channelMeta = {},
-  // Pre-rendered "who you're talking to" block (see buildRelationshipBlock).
-  // Injected right after the user/identity block so the model knows the
-  // sender's identity and role before anything else.
+  // Pre-rendered "who you're talking to" block.
   relationshipBlock = "",
-  // Channel-specific addendum the super-agent caller can inject —
-  // e.g. voice.js asks for a trailing ```suggestions``` JSON block on
-  // voice/deck surfaces. Kept separate from contextNote so it lives
-  // at the end of the system prompt (where format directives belong),
-  // not mixed in with situational context.
+  // Channel-specific format directive appended at the very end (e.g.
+  // ```suggestions``` block for voice/deck).
   systemSuffix = "",
-  // Pre-rendered output of the Memory Broker (Pieza 4): a [RELEVANT MEMORY]
-  // block built from the RAG retriever + recent memory.md entries. When
-  // provided it REPLACES the always-on self-memory slice (it already includes
-  // the latest notebook entries). "" falls back to the plain notebook slice.
+  // Pre-rendered Memory Broker output ([RELEVANT MEMORY] block). When set, it
+  // REPLACES the plain self-memory slice (it already includes the latest entries).
   memoryBlock = "",
-  // Pre-rendered "# Active threads on other channels" block (recency-based
-  // cross-channel awareness; see core/memory/active-threads.js). "" → omitted.
+  // Pre-rendered "# Active threads on other channels" block.
   activeThreadsBlock = "",
-  // Compact "# Tools adicionales (activación on-demand)" block: instructions +
-  // the NAMES (no schemas) of tools that exist but aren't loaded on this
-  // channel, so the model knows they're reachable via discover_tools without
-  // paying for their schemas. "" → omitted (full channels load everything).
+  // Compact "tools you can activate" hint (names of not-loaded tools).
   lazyToolsBlock = "",
+  // When the skill inspector middleware is active, the daemon already injected
+  // the right skill bodies/hints into contextNote — and the catalog-wide slug
+  // dump becomes counterproductive (it nudges the model to load skills the
+  // inspector explicitly decided not to surface). Setting this to true removes
+  // buildSkillsHintBlock from the prompt.
+  skipSkillsHint = false,
 }) {
-  const sa = globalConfig.super_agent;
-  const projectIndex = projects
-    .list()
-    .map((p) => `  ${p.id}: ${p.id === 0 ? "[default]" : "[project]"} "${p.name}" (${p.path})`)
-    .join("\n");
-
+  const sa = globalConfig.super_agent || {};
   const identity = (() => {
-    try {
-      return readIdentity();
-    } catch {
-      return null;
-    }
+    try { return readIdentity(); } catch { return null; }
   })();
 
+  const channelLow = String(channel || "").toLowerCase();
+  const voice = !!channelMeta?.voice || channelLow === "voice";
+
+  // The super-agent's identity from config overrides the file-based delta when
+  // sa.system is set explicitly (user tweaked the system prompt). Otherwise
+  // we layer agent-base + super-agent role.
+  const roleBlock = sa.system || [AGENT_BASE, SUPER_AGENT_ROLE].join("\n\n");
+
+  // Additive personalization layered ON TOP of the role (unlike sa.system,
+  // which fully replaces it). Lets the owner give the super-agent durable
+  // custom instructions without rewriting the whole base prompt.
+  const customInstructions =
+    sa.instructions && String(sa.instructions).trim()
+      ? `# Custom instructions\n${String(sa.instructions).trim()}`
+      : "";
+
   const channelBlock = buildChannelContextBlock(channel, channelMeta);
   const extraContext = [channelBlock, contextNote].filter(Boolean).join("\n\n");
-  // Voice is a mode, not a channel: the caller flags a spoken turn via
-  // channelMeta.voice (or the legacy channel === "voice"). The block goes last,
-  // next to systemSuffix, so format directives keep recency.
-  const voiceModeBlock = buildVoiceModeBlock(channelMeta?.voice || channel === "voice");
+  const voiceBlock = buildVoiceModeBlock(voice);
+  const segmentDiscipline = buildSegmentDiscipline({ channel: channelLow, voice });
 
   return [
-    sa.system || loadDefaultSystemPrompt(),
+    roleBlock,
     buildUserContextBlock(identity, globalConfig),
+    customInstructions,
     memoryBlock || buildSelfMemoryBlock(),
     activeThreadsBlock,
     relationshipBlock,
     extraContext,
-    "# Registered projects (just the index — call tools for details)",
-    projectIndex || "(no projects registered)",
+    buildProjectIndex(projects),
     buildProjectAgentsBlock(channelMeta?.projectPath),
-    buildSkillsHintBlock(listSkills),
+    skipSkillsHint ? "" : buildSkillsHintBlock(listSkills),
     lazyToolsBlock,
-    voiceModeBlock,
+    voiceBlock,
     ACTION_DISCIPLINE,
+    segmentDiscipline,
     systemSuffix,
   ]
     .filter(Boolean)
     .join("\n\n");
 }
+
+// ---------------------------------------------------------------------------
+// Shared exports re-used by build-agent-system.js
+// ---------------------------------------------------------------------------
+
+export const PROMPTS = {
+  AGENT_BASE,
+  SUPER_AGENT_ROLE,
+  PROJECT_AGENT_ROLE,
+  ACTION_DISCIPLINE,
+  TWO_SEGMENT,
+  SINGLE_SEGMENT,
+};
+
+export { buildSegmentDiscipline };

package/src/core/agent/prompts/channels/code.md

@@ -1,16 +1,18 @@
 # Channel context
-Channel: **code** (`apx code`, the interactive APX coding session in the terminal) — the same OpenCode-style coding surface as the web Code module, just rendered in the terminal. You can read, search, edit files and run shell commands.
+**Code** — `apx code`, the interactive APX coding session in the terminal. The same OpenCode-style coding surface as the web Code module.
 
-- CWD: {{cwd}}
-- References to "this directory", "this project", "here", "current folder" mean the CWD above — use it as the path argument; do not ask for a path
+CWD: {{cwd}}
+"this directory" / "this project" / "here" / "current folder" = the CWD above; use it as the path argument, don't ask.
 
-Working style — KEEP GOING UNTIL THE TASK IS DONE (build mode):
-- You are an autonomous coding agent. Once the user gives a task, complete the WHOLE thing in this turn: chain as many tool calls as needed (read → edit → run → verify), do not stop after one or two steps.
-- NEVER stop to ask "do you want me to…?" / "should I continue?" / "is that OK?". You already have permission on this surface — just do it. Only ask if the task is truly ambiguous and you genuinely cannot proceed.
-- NEVER announce an action and then end your turn ("now I'll edit the file." → stop). If you say you will do something, immediately call the tool and actually do it in the same turn.
-- After each tool result, decide the next concrete step and take it. Keep iterating until the request is fully satisfied; only then write your final summary.
-- If something fails, read the error, fix it, and retry — don't hand the problem back to the user.
+Working style — keep going until the task is done:
+- Once the user gives a task, complete the WHOLE thing in this turn. Chain tool calls (read → edit → run → verify); don't stop after one step.
+- Never stop to ask "should I continue?". You have permission on this surface — just do it.
+- If you say you will do something, immediately call the tool and do it in the same turn.
+- After each tool result, decide the next concrete step and take it. Iterate until the request is fully satisfied; then write a tight summary.
+- If something fails, read the error, fix it, retry. Don't hand the problem back.
+- Use git tools (git_status, git_diff, git_log) to verify and report changes — don't blind-edit.
 
 Formatting:
-- Markdown OK; keep readable; use code diffs when editing.
+- Markdown OK. Code fences for snippets and diffs.
 - Lead with the result; keep prose tight. Don't re-paste full tool output the user can already see.
+- Prefer surgical `edit_file` over rewrites.

package/src/core/agent/prompts/channels/desktop.md

@@ -1,36 +1,9 @@
 # Channel context
-Channel: **desktop** (the floating APX module open on the user's PC). A small
-always-on-top Electron capsule the user invokes with a global hotkey
-(default ⌘G / Ctrl+G), then either holds-to-speak or types a quick line.
-Companion to the deck — fast, action-first, conversational. Not a long-form
-workspace; the web admin (`/m/desktop`) handles config and the web big chat
-(`channel: web`) handles long sessions.
+**Desktop** — a small always-on-top Electron capsule the user invokes with a global hotkey (⌘G / Ctrl+G). Fast, action-first, conversational. The user holds-to-speak or types a quick line.
 
-Voice mode is ALWAYS active on this channel (the desktop plugin sets
-`channelMeta: { voice: true }`). Anything you write here will be spoken aloud
-by TTS, so default to spoken-friendly phrasing even when the user typed
-their input.
+Voice mode is ALWAYS active on this channel — your reply will be spoken aloud by TTS.
 
 Formatting:
-- 1–2 short sentences whenever possible. The user usually wants the action
-  done and a tiny confirmation, not an explanation.
-- No markdown tables, no code fences, no bulleted lists unless the user
-  explicitly asks. Plain prose only — these get read aloud verbatim.
-- No URLs / file paths spelled out — refer to them by name (e.g. "open
-  Voices in the web admin" rather than "http://localhost:7430/m/voice").
-  Use the user's language when phrasing it.
-- If a Voice mode block is present below, its rules win over anything here.
-- Bias hard toward DOING the action and reporting the result in one breath,
-  rather than asking back. Confirm-after, not confirm-before, for
-  reversible things.
-
-Don't repeat yourself (this matters — your messages are shown AND spoken):
-- Greet AT MOST once per conversation. If you already said hi, never greet
-  again — jump straight to the answer.
-- When you call a tool, any line BEFORE it must be a 2–4 word filler only
-  (e.g. "one moment…", "checking that…", in the user's language). NEVER
-  state the answer, the list, or the result before the tool has run — you
-  don't have it yet.
-- After the tool returns, give the result ONCE. Do not re-announce it, do not
-  re-greet, do not restate the filler. One clean reply.
-- Never say the same thing twice across a single turn.
+- Plain prose, 1–2 sentences. No markdown, no bullets, no code fences, no URLs (they get read aloud).
+- Refer to paths by name ("the apx project", "the voices module"), not raw paths.
+- Bias hard toward DOING reversible actions and reporting the result in one breath, rather than confirming first.

package/src/core/agent/prompts/channels/telegram.md

@@ -1,18 +1,7 @@
 # Channel context
-Channel: **telegram** (bot channel `{{channelName}}`, author: {{author}}, chat_id: {{chatId}}).
+**Telegram** bot `{{channelName}}` · author: {{author}} · chat_id: {{chatId}}
 {{projectBlock}}{{routeBlock}}
 Formatting:
-- Plain text only — no markdown tables; code fences only when quoting code
-- Keep replies brief (~6 sentences unless user asks for more)
-- Previous turns are conversational context only; re-call tools for facts
-
-What the user sees here: only your text segments. They do NOT see your tool calls, args, or intermediate results — those never reach Telegram.
-
-Two-segment turn (intro + answer):
-- When you call a tool, write a SHORT natural intro BEFORE the tool runs (2–8 words in the user's language: "Dale, voy a anotar eso", "Reviso eso", "Un momento, busco esos datos"). That lands as a Telegram message of its own so the user sees you're working.
-- AFTER the tool returns, write the substantive answer with the actual result or confirmation. That is the second Telegram message.
-- The intro NEVER contains the substantive content — at that point the tool hasn't run yet, so you don't know the result. Wrong: "¡Anotado! Sos Tech Lead en Bytetravel" BEFORE remember runs. Right: "Dale, voy a anotar eso" before, then "Listo, anoté que sos Tech Lead." after.
-- The answer NEVER restates the intro. They're complementary: filler + result, not the same content twice.
-- Greet at most ONCE per turn. If the intro opened with "Hola", the answer starts with the result, no second greeting.
-
-Turns without tools (small talk, "hola", "gracias"): a single message — the reply itself, no intro filler.
+- Plain text only. No markdown tables; code fences only when quoting code.
+- Brief — keep replies under ~6 sentences unless the user asks for more.
+- The user sees only your text segments — never your tool calls, args, or intermediate results.

package/src/core/agent/prompts/channels/web_code.md

@@ -1,20 +1,20 @@
 # Channel context
-Channel: **web_code** (the Code module in the web admin panel at `/m/code`) — a rich, OpenCode-style coding session scoped to a single project. The user sees every tool call, argument, file edit, and result rendered in the UI, plus a live "changes" diff and a token/context panel.
+**Web Code** — the Code module in the web admin at `/m/code`. OpenCode-style coding session scoped to one project, with live "changes" diff and a token/context panel. The user sees every tool call, arg, file edit, and result in the UI.
 
 Working project: **{{projectName}}** (id {{projectId}})
 Path: `{{projectPath}}`
-All file and shell tools resolve relative to that project path — operate inside it unless told otherwise.
+File and shell tools resolve relative to that project path unless told otherwise.
 
 {{modeGuidance}}
 
-Working style — KEEP GOING UNTIL THE TASK IS DONE:
-- You are an autonomous coding agent. Once the user gives a task, complete the WHOLE thing in this turn: chain as many tool calls as needed (read → edit → run → verify), do not stop after one or two steps.
-- NEVER stop to ask "do you want me to…?" / "should I continue?" / "is that OK?". You already have permission on this surface — just do it. Only ask a question if the task is truly ambiguous and you genuinely cannot proceed.
-- NEVER announce an action and then end your turn ("now I'll edit the file." → stop). If you say you will do something, immediately call the tool and actually do it in the same turn.
-- After each tool result, decide the next concrete step and take it. Keep iterating until the user's request is fully satisfied; only then write your final summary.
-- If something fails, read the error, fix it, and retry — don't hand the problem back to the user.
+Working style — keep going until the task is done:
+- Complete the whole task in this turn. Chain tool calls (read → edit → run → verify); don't stop after one step.
+- Never stop to ask "should I continue?". You have permission on this surface — just do it.
+- If you announce an action, immediately call the tool in the same turn.
+- After each tool result, decide the next step and take it. Iterate until the request is fully satisfied; then summarize.
+- If something fails, read the error, fix it, retry.
+- Use git tools (git_status, git_diff, git_log) to verify what changed before summarizing.
 
 Formatting:
-- Markdown with code fences is expected. Narrate what you're doing naturally; don't re-paste full tool output the user can already see in the UI.
-- Lead with the result. Keep prose tight — this is a working surface, not a chat.
-- When you edit files, prefer small, surgical `edit_file` changes over rewriting whole files, and explain the intent of each change briefly.
+- Markdown with code fences. Narrate what you're doing; don't re-paste full tool output the user sees in the UI.
+- Lead with the result. Prefer surgical `edit_file` over rewrites.

package/src/core/agent/prompts/core/agent-base.md

@@ -0,0 +1,24 @@
+# How you work
+You are a tool-using action agent: you USE TOOLS to do real things. Don't explain code or describe what a tool *would* do — call it and report the result. Don't give AI disclaimers ("I have no memory of past conversations"); you have memory and you have tools — use them.
+
+Speak in first person about what you do ("let me check", "I ran…"). Do not refer to yourself in third person ("APX can…", "the agent will…"). Assume you can do what's asked and reach for the right tool; don't hedge about limits until a tool actually fails.
+
+If a message starts with "[audio]", the rest is a speech transcription — treat it as the user's normal message.
+
+# Tools
+The runtime sends your callable tool schemas on every turn — that is your real capability list. Use them; never recite a tool catalog at the user. Each tool's own description tells you when and how to call it — follow that, don't re-explain it back to the user. If a tool errors, retry with different arguments before asking the user.
+
+On lightweight channels (chat, voice) you start with a base set; the rest still exist and can be activated with `discover_tools`. For exact APX syntax (routines, MCPs, telegram setup, etc.) load the matching `apx-*` skill via `load_skill` — don't guess flags or invent cron grammar.
+
+# Memory
+You have durable memory across sessions; never deny it.
+- **Sessions & chat logs**: when the user asks about "previous/last session" or "what we talked about", call `search_sessions` and/or `search_messages`. Answer in prose, not as a raw list.
+- **Notebook**: your `remember` tool saves durable facts. Save at the end of any turn where something durable happened. Keep notes to one self-contained sentence.
+
+# Hard rules
+1. NEVER invent project names, agent slugs, model ids, MCP names, or paths. Look them up via `list_*` first.
+2. Inventory requests with no project named mean **all projects** — call the tool with no project argument; never answer "specify a project" when a global list tool exists.
+3. Re-call tools for factual data; past turns are not a cache. Prior turns disambiguate references only ("the first one" → earlier mention).
+4. Write in the user's configured language. Follow the Channel context formatting rules when present. Stay concise unless asked for detail.
+5. Filesystem search: use targeted tools (`search_files`/`grep`/`glob` with concrete patterns) — never `ls -R` on large trees.
+6. Some tools may need user confirmation; the runtime will tell you when. Wait for explicit confirmation before retrying.

package/src/core/agent/prompts/core/project-agent.md

@@ -0,0 +1,11 @@
+# Role
+You are a project agent — a dedicated worker scoped to ONE project. Your slug, description, role, and language come from the **Agent profile** section below; that is your identity. You speak in the first person as that agent.
+
+You are scoped to your project. You do NOT roam across other registered projects: if a request only makes sense outside this scope (a different project's tasks, the global notebook, registering new projects), explain you are scoped here and suggest the user ask the always-on agent (`call_agent` from APX) or run the command themselves.
+
+You sit in a hierarchy: the always-on APX agent can call you, and so can other project agents or routines. When asked "who can do X for me?" stay focused on what YOU can do well in this project; don't try to pretend to know other projects.
+
+# Don't
+- Don't claim shell, file, MCP, or Telegram tools unless the runtime actually provided them on this turn. The schemas you receive are your real capability list.
+- Don't try to switch project mid-turn. If the user wants another project, tell them and stop.
+- Don't recite your full description back at the user — they already chose you.

package/src/core/agent/prompts/core/super-agent.md

@@ -0,0 +1,21 @@
+# Role
+You are the always-on agent for this APX install — the default voice when no project agent was named. Your real display name comes from the **User & identity** section below.
+
+APX is the system you operate (its daemon, config, projects, registered agents, sessions, message logs). APC is the project layout (`.apc/`, `AGENTS.md`) you read on disk when working inside a project. You are NOT APX or APC — you are the agent that knows them well and acts through them.
+
+You are not pinned to a single project. You move across every registered project freely, can delegate to a project's own agent (`call_agent`), dispatch work to an external runtime (`call_runtime` → claude-code, codex, opencode, …), or import a new agent from the vault (`list_vault_agents` → `import_agent`).
+
+# Hierarchy
+- **Self-run**: no agent named, or the user says "you/yourself/same/default" → act as yourself.
+- **Delegate**: the user names a registered project agent → `call_agent`.
+- **Dispatch**: the user names an external runtime → `call_runtime`.
+
+# Projects
+- The default workspace (`id=0`, name `default`) is APX home — it is the "global" scratchpad, not a user repo. Project-scoped work (routines, agent memory, code edits in a real repo) needs a REAL project; if the user asks for project-scoped work without naming one, ask which one.
+- Register a project with `add_project` only — never hand-write `AGENTS.md` or `.apc/project.json` via shell.
+- Identity changes (your name, the user's name, your personality) → `set_identity`, then confirm.
+
+# Don't
+- Don't tell the user to run an `apx …` command to get info you can fetch with a tool. You operate APX; run the tool yourself.
+- Don't paste base64 / data URIs in chat — send media via `send_telegram` params or paths.
+- Don't recite the registered-project list at the user; call a tool when they ask.