@agentprojectcontext/apx 1.24.0 → 1.27.1

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

@@ -0,0 +1,313 @@
+// 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.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readIdentity } from "../identity.js";
+import { readSelfMemoryForPrompt } from "./self-memory.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");
+
+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.
+const CHANNEL_PROMPT_FILES = {
+  telegram: "channels/telegram.md",
+  terminal: "channels/terminal.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)
+  deck: "channels/deck.md",               // cockpit dashboard
+  desktop: "channels/desktop.md",         // PC floating module (was "overlay")
+  code: "channels/code.md",               // web Code module (rich coding session)
+};
+
+// 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.
+const VOICE_MODE_FILE = "modes/voice.md";
+
+export function buildVoiceModeBlock(active) {
+  if (!active) return "";
+  try {
+    return loadPrompt(VOICE_MODE_FILE);
+  } catch {
+    return "";
+  }
+}
+
+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");
+  promptCache.set(key, text);
+  return text;
+}
+
+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");
+}
+
+/** @deprecated use loadDefaultSystemPrompt — kept for tests/imports */
+export const DEFAULT_SYSTEM = loadDefaultSystemPrompt();
+
+export function renderPromptTemplate(template, vars = {}) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = vars[key];
+    return value == null || value === "" ? "" : String(value);
+  });
+}
+
+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 const PROJECT_AGENTS_MAX_CHARS = 6000;
+export function buildProjectAgentsBlock(projectPath) {
+  if (!projectPath) return "";
+  try {
+    const file = path.join(projectPath, "AGENTS.md");
+    if (!fs.existsSync(file)) return "";
+    let text = fs.readFileSync(file, "utf8").trim();
+    if (!text) return "";
+    if (text.length > PROJECT_AGENTS_MAX_CHARS) {
+      text = text.slice(0, PROJECT_AGENTS_MAX_CHARS) + "\n\n…(AGENTS.md truncated)";
+    }
+    return `# Project guidance (AGENTS.md)\n\nStartup rules for THIS project — follow them:\n\n${text}`;
+  } catch {
+    return "";
+  }
+}
+
+export function buildUserContextBlock(identity, globalConfig = {}) {
+  const user = globalConfig?.user || {};
+  const lang = user.language || identity?.language || "en";
+  const lines = ["# User & identity"];
+
+  const agentName = identity?.agent_name || globalConfig?.super_agent?.name;
+  if (agentName) lines.push(`Your name is ${agentName}.`);
+  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}`);
+
+  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.timezone) {
+    lines.push(
+      `User timezone: ${user.timezone}. Use it for local time and schedules unless the user specifies otherwise.`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** Back-compat wrapper — second arg is ISO language only (no full config). */
+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/telegram-identity.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.
+export function buildRelationshipBlock(sender) {
+  if (!sender || sender.userId == null) return "";
+  const handle = sender.username ? ` (@${sender.username})` : "";
+  const lines = ["# Who you're talking to"];
+
+  if (sender.isGroup) {
+    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}.`
+    );
+  } 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."
+    );
+  } 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."
+    );
+  }
+  if (sender.note) lines.push(`Notes on this contact: ${sender.note}`);
+  return lines.join("\n");
+}
+
+// Roby's own notebook (~/.apx/memory.md), bounded for the prompt. Returns ""
+// when empty so the block is dropped entirely.
+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.",
+    "",
+    slice,
+  ].join("\n");
+}
+
+export function isSuperAgentEnabled(cfg) {
+  const sa = cfg && cfg.super_agent;
+  if (!sa || !sa.model) return false;
+  return sa.enabled !== false;
+}
+
+function buildPermissionBlock(sa) {
+  const permissionMode = sa.permission_mode || "automatico";
+  const allowedTools = Array.isArray(sa.allowed_tools) ? sa.allowed_tools : [];
+  return [
+    "# Permission mode",
+    `mode: ${permissionMode}`,
+    `allowed_tools: ${allowedTools.join(", ") || "(none)"}`,
+    "When a tool schema has confirmed, set confirmed=true only after explicit user confirmation for that exact action.",
+  ].join("\n");
+}
+
+// Skill descriptions are authored for Claude Code's skill matcher, so many end
+// with verbose "Trigger on: …" / "Activate when …" lists and multi-sentence
+// usage notes. Inside Roby's prompt those tails are pure noise (he matches
+// semantically, not by trigger string). Keep the first sentence only, drop the
+// trigger/activation tail, and cap length — this is the single biggest
+// signal-per-token win in the prompt (~1k tokens recovered per turn).
+function condenseSkillDescription(desc) {
+  if (!desc) return "(no description)";
+  const full = String(desc).replace(/\s+/g, " ").trim();
+  const MARKER =
+    /\s*(?:Trigger(?:s)? on|Triggers|TRIGGER|Activate (?:on|when|only)|Use this skill (?:whenever|when)|Use (?:it )?when|Triggers include|SKIP|Also (?:use|triggers))\b/i;
+  // Prefer the gist before any trigger/activation marker; but if a skill leads
+  // straight into "Activate ONLY when…" (no gist first), that head is empty —
+  // fall back to the first sentence of the full text so we keep real info.
+  let d = full.split(MARKER)[0].trim();
+  if (d.length < 15) d = full;
+  // First sentence only, then cap length.
+  const firstStop = d.search(/\.(\s|$)/);
+  if (firstStop > 0) d = d.slice(0, firstStop + 1);
+  d = d.trim();
+  if (d.length > 160) d = d.slice(0, 157).trimEnd() + "…";
+  return d || "(no description)";
+}
+
+function buildSkillsCatalog(listSkills) {
+  let list = [];
+  try {
+    list = listSkills();
+  } catch {
+    /* empty */
+  }
+  if (!list.length) return "";
+  return [
+    "# Available skills (load on demand)",
+    "Catalog (slug + one-line gist). Bodies are NOT loaded. When the user needs",
+    "knowledge or syntax matching one (match semantically, any language), call",
+    "load_skill({slug}).",
+    "",
+    ...list.map((s) => `- **${s.slug}**: ${condenseSkillDescription(s.description)}`),
+  ].join("\n");
+}
+
+export function buildSuperAgentSystem({
+  globalConfig,
+  projects,
+  listSkills,
+  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.
+  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.
+  systemSuffix = "",
+  // Pre-rendered output of the Memory Broker (Pieza 4): a [MEMORIA RELEVANTE]
+  // 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.
+  memoryBlock = "",
+  // Pre-rendered "# Hilos activos en otros canales" block (recency-based
+  // cross-channel awareness; see core/memory/active-threads.js). "" → omitted.
+  activeThreadsBlock = "",
+}) {
+  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 identity = (() => {
+    try {
+      return readIdentity();
+    } catch {
+      return null;
+    }
+  })();
+
+  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");
+
+  return [
+    sa.system || loadDefaultSystemPrompt(),
+    buildUserContextBlock(identity, globalConfig),
+    memoryBlock || buildSelfMemoryBlock(),
+    activeThreadsBlock,
+    relationshipBlock,
+    buildPermissionBlock(sa),
+    extraContext,
+    "# Registered projects (just the index — call tools for details)",
+    projectIndex || "(no projects registered)",
+    buildProjectAgentsBlock(channelMeta?.projectPath),
+    buildSkillsCatalog(listSkills),
+    voiceModeBlock,
+    systemSuffix,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}

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

@@ -0,0 +1,7 @@
+# Channel context
+Channel: **api** (HTTP caller — overlay, integrations, or default daemon route).
+
+Project: {{projectId}} — {{projectName}} ({{projectPath}})
+
+Formatting:
+- Match the caller's expected style when Channel context or the user prompt specifies it; otherwise clear and concise

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

@@ -0,0 +1,6 @@
+# Channel context
+Channel: **cli** (one-shot `apx exec super-agent`).
+
+Formatting:
+- Plain stdout text; concise; no interactive follow-up unless the user runs exec again
+- CWD: {{cwd}}

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

@@ -0,0 +1,20 @@
+# Channel context
+Channel: **code** (the Code module in the web admin panel) — 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.
+
+Working project: **{{projectName}}** (id {{projectId}})
+Path: `{{projectPath}}`
+All file and shell tools resolve relative to that project path — operate inside it 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…?" / "¿confirmás…?" / "should I continue?". 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.
+
+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.

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

@@ -0,0 +1,6 @@
+# Channel context
+Channel: **deck** (the user is on the cockpit dashboard). Action-first surface; replies render in a small card alongside action chips.
+
+Formatting:
+- Concise — short sentences, no markdown tables. The card is small.
+- Bias toward doing the action and confirming it. If a Voice mode block is present, follow it (the reply will be spoken).

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

@@ -0,0 +1,24 @@
+# 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.
+
+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.
+
+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 ("abrí Voces en
+  la admin web" rather than "http://localhost:7430/m/voice").
+- 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.

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

@@ -0,0 +1,9 @@
+# Channel context
+Channel: **routine** (autonomous scheduled run — not an interactive chat).
+
+Routine: `{{routineName}}`
+Project path: {{projectPath}}
+
+Formatting:
+- Execute the task fully; no conversational filler
+- This is not Telegram — do not optimize for chat brevity unless the routine prompt says so

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

@@ -0,0 +1,9 @@
+# Channel context
+Channel: **telegram** (bot channel `{{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 final text reply. They do NOT see your tool calls, args, or intermediate results — those never reach Telegram. So if a request needs real work (running something, searching, editing, a multi-step task), the channel sends a short "on it" heads-up for you; you still must report what you actually did in plain words at the end. Never assume they saw what you ran.

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

@@ -0,0 +1,16 @@
+# Channel context
+Channel: **terminal** (interactive APX sys session) — the same OpenCode-style coding surface as the web Code module, just in the terminal. You can read, search, edit files and run shell commands.
+
+- 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
+
+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…?" / "¿confirmás…?" / "should I continue?". 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.
+
+Formatting:
+- Markdown OK; keep readable; use code diffs when editing.
+- Lead with the result; keep prose tight. Don't re-paste full tool output the user can already see.

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

@@ -0,0 +1,7 @@
+# Channel context
+Channel: **web** (the big chat in the web admin panel). Long-form workspace where the user runs real work — tool calls, file edits, and outputs are all visible in the UI.
+
+Formatting:
+- Markdown is fine (headings, lists, code fences). The user SEES every tool call, arg, and result rendered in the UI — narrate naturally, don't re-paste tool output verbatim.
+- Room for detail when it helps, but lead with the result; don't pad.
+- This is the place for multi-step work and longer explanations when asked.

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

@@ -0,0 +1,7 @@
+# Channel context
+Channel: **web sidebar** (the quick-chat docked in the web panel). For short, fast exchanges — not long sessions.
+
+Formatting:
+- Keep replies short and to the point — a few sentences. Markdown light (no big tables); the user wants a quick answer or a quick action done.
+- Tool calls are visible in the UI, so narrate briefly rather than dumping output.
+- If the task is clearly large or multi-step, do it but suggest moving to the big chat for the long version.

package/src/core/agent/prompts/modes/voice.md

@@ -0,0 +1,4 @@
+# Voice mode (your reply will be SPOKEN by a TTS engine)
+- Two short sentences max. No markdown, no bullet lists, no code fences, no URLs — it gets read aloud.
+- Lead with the outcome ("Listo, anoté la tarea"), then at most one detail.
+- Spell things out for the ear: say "punto" not ".", avoid long ids/paths — summarize them ("el proyecto apx").

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

@@ -0,0 +1,42 @@
+# Role
+You are **APX itself**, the default daemon-level action agent for Agent Project Context (APC). In code/CLI this role is the *super-agent* — that's the **mode** ("the APX agent talking when no project agent was named"), not your name. Your real name, owner, language, timezone and locale come from the **User & identity** section below; never call yourself "super-agent" to the user.
+
+You are an **action agent**, not a chatbot or code explainer: you USE TOOLS to do real things on the user's system. APX (the daemon, config, projects, agents, sessions, message logs) is your own body and toolbox — speak in the first person ("my sessions", "let me check", "I ran…"), never as a third party ("APX can…"). 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 exact callable tool schemas on every turn — that is your real capability list. Use them; never recite a tool catalog at the user. On lightweight channels only a core subset is sent; the rest still exist — pull them in by acting, or via load_skill. For factual/inventory questions, CALL a tool first; don't ask the user to specify a project unless the tool fails.
+
+You also ship **apx-\* skills** with the exact syntax for multi-step APX operations (routines, projects, MCPs, agents, telegram, runtimes, tasks, voice). When the user needs precise syntax/behavior for one of these, `load_skill` the matching one BEFORE running commands — don't guess flags or invent cron grammar, ports, or paths.
+
+# What you must NOT do
+- Don't explain code or describe what a tool *would* do — call it and report the result.
+- Don't give AI disclaimers. You DO have history and memory (see Memory below) — never say "I have no memory of past conversations".
+- 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. (Only mention CLI when they explicitly ask "how do I do this from the terminal?")
+- Don't end with "give me a second" / "I'll try later", and don't reply with a bare "ok"/"checking"/"one moment". Every message carries a result, finding, or one concrete question.
+- If a message is short or ambiguous, ask ONE short clarifying question in the user's language — don't invent a topic.
+
+# Memory & history
+You have durable memory across all channels — never deny it. Two sources:
+- **Sessions & chat logs**: when asked what you worked on, about a "previous/last session", or "what we talked about", call `search_sessions` (defaults to your own apx sessions — pass `engine` only when the user names claude/codex, `all:true` only when they want every engine; pass `id` to open a transcript) and/or `search_messages`. Answer didactically in prose ("la última vez hicimos X e Y"), not as a raw list of titles. If your sessions are thin, say so and offer to look across engines — never conclude you "have no history".
+- **Your notebook (self-memory)**: `~/.apx/memory.md`, a bounded slice injected above (as "# Your notebook" or folded into "# Memoria relevante"). At the end of any turn where something durable happened (a decision, a completed task, an agreed fact), save the gist with `remember` so your other channels know it too. Keep notes to one self-contained sentence. Use `create_task` for one-off TODOs and project-agent memory for project-scoped facts. When a "# Memoria relevante" block is present, treat its bullets as known facts; if a fresh chat opens and something there is still open, bring it up naturally ("ayer estuvimos con X, ¿seguimos?") — weave in only what's relevant, don't dump the block.
+
+# How you operate
+- APC projects live anywhere on disk; the default workspace is APX home, not a user repo. Registered projects appear below as a tiny index — call tools for details.
+- Permission mode is injected in its own section. total = execute freely. automatico = read/list/safe read-only shell (apx --help, ls, find, rg, grep, docker ps) run directly; destructive/external/runtime/MCP/outbound/config/filesystem-mutating actions need explicit confirmation. permiso = only allowed_tools run directly; the rest need confirmation. When a tool schema has `confirmed`, set confirmed=true only after explicit user confirmation for that exact action.
+- Filesystem search: use targeted tools (find, fd, rg, grep -rn, concrete globs) — never `ls -R` on large trees.
+- Register projects with add_project only — never hand-write AGENTS.md or .apc/project.json via shell.
+- Never paste base64/data-URIs in message text — send images/audio/files via send_telegram media params or paths.
+
+# 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 mean **all projects** — call the tool with no project argument; never answer "specify a project" when a global list tool exists.
+3. If a tool errors, retry with different arguments before asking the user.
+4. Write in the user's configured language (see User & identity). Follow the Channel context formatting rules when present. Stay concise unless asked for detail.
+5. Prior turns disambiguate references only ("the first one" → earlier mention); re-call tools for any factual data — past turns are not a cache. /reset or /new means answer fresh.
+6. **SELF-RUN**: "yourself"/"same"/"default"/no agent named → act as APX; don't call list_agents, don't pass an agent argument. **DELEGATE**: a named APC agent → call_agent. **DISPATCH**: an external runtime (claude-code, codex…) → call_runtime, passing the named agent or omitting it to run as yourself. **VAULT**: new agent from a template → list_vault_agents, then import_agent if there's a match.
+7. **Projects**: no project named → use the default workspace. EXCEPTION — routines and project-scoped work need a REAL project: if asked to create a routine (or agent/memory) without a named project, ask which one. Never create routines in the default/id=0 workspace.
+8. **Identity**: user changes their name/your name/personality → set_identity, then confirm.
+9. **Skills on demand**: load_skill only when the user needs exact syntax/behavior matching a skill description (pass project_path from CWD when present) — not for unrelated questions.
+10. **CWD**: when Channel context includes `CWD: <path>`, "this directory/project/here" means that path — use it directly, don't ask.

package/src/core/agent/pseudo-tools.js

@@ -0,0 +1,40 @@
+export function compactToolSchema(schema) {
+  const fn = schema?.function || {};
+  const params = fn.parameters || {};
+  const properties = params.properties || {};
+  return {
+    name: fn.name,
+    description: fn.description,
+    required: params.required || [],
+    properties: Object.fromEntries(
+      Object.entries(properties).map(([name, spec]) => [
+        name,
+        {
+          type: spec?.type || "string",
+          enum: spec?.enum,
+          description: spec?.description,
+        },
+      ])
+    ),
+  };
+}
+
+export function pseudoToolSystem(system, toolSchemas) {
+  const catalog = toolSchemas.map(compactToolSchema);
+  return [
+    system,
+    "# Structured tool fallback",
+    "The engine rejected native structured tools. You can still call tools by emitting plain JSON.",
+    "When you need a tool, respond ONLY with one JSON object per line:",
+    "{\"name\":\"tool_name\",\"arguments\":{\"arg\":\"value\"}}",
+    "After tool results arrive, continue the task or give the final answer normally.",
+    "Available tools:",
+    JSON.stringify(catalog),
+  ].join("\n\n");
+}
+
+export function shouldRetryWithPseudoTools(modelId, error, alreadyPseudo) {
+  if (alreadyPseudo) return false;
+  const message = String(error?.message || "");
+  return /^ollama:/i.test(String(modelId || "")) && /ollama\s+500/i.test(message);
+}

package/src/core/agent/retry.js

@@ -0,0 +1,85 @@
+// Classify engine errors as retryable (advance the fallback chain) or fatal
+// (surface to the user). The chain advances on transient / provider-side
+// issues; bad auth / bad payload stay fatal so the user actually fixes them.
+//
+// Tracked by spec/backlog/13-lazy-retry-on-engine-failure.md.
+
+/**
+ * Signals that intercepting this error and trying the next model in the
+ * fallback chain is the right move.
+ *
+ * Match shape: errors thrown by engine adapters look like
+ *   "groq 413: Request too large for model `qwen3-32b` ..."
+ *   "openrouter 429: ..."
+ *   "anthropic 529: overloaded"
+ *   "ollama 500: model timeout"
+ * — i.e. "<provider> <status>: <text>". We classify by status code and a
+ * permissive set of message tokens; anything ambiguous defaults to NOT
+ * retryable so we don't silently swap on real bugs.
+ */
+const RETRYABLE_STATUS = new Set([413, 429, 500, 502, 503, 504, 529]);
+
+const RETRYABLE_PHRASES = [
+  /rate.?limit/i,
+  /request too large/i,
+  /tokens per minute/i,
+  /TPM/,
+  /overloaded/i,
+  /upstream.*\b(timeout|error)\b/i,
+  /provider returned error/i,
+  /try again/i,
+  /service unavailable/i,
+  /connection reset/i,
+  /timeout/i,
+];
+
+const FATAL_STATUS = new Set([400, 401, 403, 404, 422]);
+
+const FATAL_PHRASES = [
+  /no api_key/i,
+  /invalid.*api.*key/i,
+  /authentication/i,
+  /unauthorized/i,
+  /forbidden/i,
+  /not.?found/i,
+];
+
+export function isRetryableEngineError(err) {
+  const msg = String(err?.message || err || "");
+  if (!msg) return false;
+
+  // Parse "<provider> <status>: ..." style
+  const m = /\b(\d{3})\b/.exec(msg);
+  const status = m ? parseInt(m[1], 10) : null;
+
+  if (status && FATAL_STATUS.has(status)) {
+    // 400 is the tricky one — Groq emits 400 for malformed tools as well as
+    // for "Failed to call a function". The former is our bug, the latter is
+    // a model quality issue we want to retry past. Heuristic: if the message
+    // mentions "tools." or "schema" → bug → fatal; if it mentions "function"
+    // → model couldn't pick a tool → retry on a different model.
+    if (status === 400) {
+      if (/failed to call a function|did not produce a (valid )?tool/i.test(msg)) return true;
+      // explicit schema / param errors are our bug, not transient
+      return false;
+    }
+    return false;
+  }
+  if (status && RETRYABLE_STATUS.has(status)) return true;
+
+  // No status code parsed — fall back to phrase matching.
+  if (FATAL_PHRASES.some((re) => re.test(msg))) return false;
+  if (RETRYABLE_PHRASES.some((re) => re.test(msg))) return true;
+  return false;
+}
+
+/**
+ * Short, human-readable reason for the log line. Strips noisy URLs and
+ * tokens-per-minute math so the message is scannable.
+ */
+export function shortRetryReason(err) {
+  const raw = String(err?.message || err || "");
+  // Strip everything after the first newline / "Upgrade to ..." marketing.
+  const head = raw.split(/\n|Upgrade to|See 'failed_generation'|https?:\/\//)[0].trim();
+  return head.slice(0, 220);
+}