@agentprojectcontext/apx 1.80.2 → 1.89.1

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

@@ -1,48 +1,400 @@
-// 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";
+// Agent-to-agent (A2A) reply: given a sender and a recipient PEER, produce the
+// recipient's answer. The recipient is an AGENTS.md agent (its model), the
+// daemon super-agent (its full identity/memory/tool loop), or an external
+// coding runtime — opencode, codex, claude-code — answered by spawning that
+// CLI and reading stdout. The same shape comes back in every case.
+//
+// Pure orchestration over core/agent + core/engines + core/runtimes: no HTTP,
+// no message-log writes (the caller decides whether and where to persist).
+import { callEngineWithFallback } from "../engine-call.js";
+import { readAgentMemory } from "../memory.js";
+import { resolveAgentModel } from "../agent-model.js";
+import { resolveAgentName } from "../../identity/self.js";
+import { readProfileState } from "../../profiles/store.js";
+import { getRuntime } from "../../runtimes/index.js";
+import { runtimeLooksLikeFailure } from "../../runtimes/outcome.js";
+import { runSuperAgent } from "../super-agent.js";
+import { runAgentTurn } from "../run-turn.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { a2aSessionKey, peerAddress as canonicalPeerAddress } from "./peers.js";
+
+// The super-agent's stable slug plus accepted technical aliases. The configured
+// display name is checked separately, so no persona name is hardcoded here.
+const ORCHESTRATOR_SLUGS = new Set(["default", "superagent", "super_agent", "super-agent", "apx"]);
+
+// A shell word only needs quoting when it isn't one. A `:thread` address is
+// safe unquoted in every shell we target, but the quotes cost nothing and cover
+// whatever an agent slug turns out to allow.
+const shellArg = (s) => (/^[A-Za-z0-9_-]+$/.test(String(s)) ? String(s) : `"${s}"`);
 
 /**
- * Build the recipient's system prompt for an A2A reply.
+ * The return address, written as the exact command that reaches it.
+ *
+ * This is what makes an a2a message answerable rather than a broadcast: a peer
+ * that can open a terminal — every coding CLI, and any agent with run_shell —
+ * learns who asked and how to reach them back, without the sender having to
+ * explain the addressing scheme in prose every time.
+ */
+export function a2aReplyCommand({ selfAddress, peerAddress }) {
+  return `apx send ${shellArg(selfAddress)} ${shellArg(peerAddress)} "<your message>" --deliver`;
+}
+
+/** a2a etiquette every recipient must follow, agent or runtime alike. An a2a
+ *  message is another AGENT talking, never the human owner — so a reply must
+ *  not "answer the owner", and must not ping the owner directly. What reaches
+ *  the owner, and when, is the orchestrator's (Roby's) call, through its own
+ *  channel and quiet-hours. */
+function a2aEtiquette({ selfAddress, peerAddress, config }) {
+  const selfName = String(selfAddress || "").toLowerCase().split("#")[0].split(":")[0];
+  const configuredName = (resolveAgentName(config) || "").toLowerCase();
+  const isOrchestrator = ORCHESTRATOR_SLUGS.has(selfName) || (configuredName && selfName === configuredName);
+  const secretaryActive = readProfileState(config).active === "secretary";
+  const superName = resolveAgentName(config) || "the orchestrator";
+  const lines = [
+    "## This is an agent-to-agent (a2a) message",
+    "It comes from another AGENT, not from the human owner.",
+  ];
+  if (isOrchestrator) {
+    lines.push(
+      "You are the orchestrator: YOU decide whether, how and when the owner hears about this — using your own channel and tools, respecting quiet-hours. Don't relay noise; relay what the owner actually needs.",
+    );
+  } else {
+    lines.push(
+      "Do NOT notify the owner directly from this turn (no `apx telegram send`, no direct owner ping).",
+      `You are NOT the orchestrator: if this needs the owner's attention or a decision, relay it to ${superName} (\`apx send <you> default "…" --deliver\` or \`apx send <you> ${superName.toLowerCase()} "…" --deliver\`) and let ${superName} decide how and when to tell them. Tag urgency: \`--severity blocker\` for a critical alert (${superName} pings the owner in the act, crossing quiet-hours), \`--severity status\`/\`fyi\` for a normal notice that rides the digest. Otherwise just do your part and reply here.`,
+    );
+  }
+  if (secretaryActive) {
+    lines.push(
+      "A secretary profile is active: anything promised to, owed to, or that the owner must act on has to be CAPTURED (a commitment via `record_commitment` / `apx commitment`, with a due date) so it resurfaces at the right time — a single a2a message is not a reminder and quiet-hours can swallow it.",
+    );
+  }
+  // The anti-double-post rule. Both kinds of peer answer by PRODUCING their
+  // reply — a model returns text, a CLI writes stdout — and APX files that as
+  // the reply. A peer that also shells out `apx send` with the same answer
+  // files the exchange twice and starts a second, overlapping thread.
+  lines.push(
+    [
+      "## How to answer",
+      `Your output IS the reply: APX logs it and hands it straight back to ${peerAddress}. Just answer here.`,
+      "Do NOT also run `apx send` to deliver this same answer — that files it twice.",
+      "",
+      "Use `apx send` only to open a NEW exchange: a later follow-up once this turn is over, or a message to somebody else. This thread's address is:",
+      "",
+      `    ${a2aReplyCommand({ selfAddress, peerAddress })}`,
+    ].join("\n"),
+  );
+  return lines.join("\n\n");
+}
+
+/**
+ * Build the recipient AGENT'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.
+ * the a2a etiquette (routing, return address, secretary capture), and the
+ * recipient's memory.
  */
-export function buildA2AReplySystem({ projectPath, toAgent, fromAgent }) {
+export function buildA2AReplySystem({
+  projectPath,
+  toAgent,
+  fromAgent,
+  config,
+  selfAddress = null,
+  peerAddress = null,
+  mode = "chat",
+}) {
+  const self = selfAddress || toAgent.slug;
+  const peer = peerAddress || fromAgent.slug;
   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.`
-  );
+  parts.push(`You are ${self}. You just received a message from ${peer}. Reply concisely.`);
+  if (mode === "code") {
+    // An agent peer has no sandbox to open — it answers through its model, with
+    // whatever its own turn allows. `--code` still changes what is being ASKED
+    // of it, so the framing has to say so rather than silently reading the same.
+    parts.push(
+      "This exchange was opened as a CODING session: answer at the level of the code — concrete files, " +
+      "concrete changes, concrete commands — not a summary of the area.",
+    );
+  }
+  parts.push(a2aEtiquette({ selfAddress: self, peerAddress: peer, config }));
   if (projectPath && toAgent.slug) {
-    const memPath = apcAgentMemoryFile(projectPath, toAgent.slug);
-    if (fs.existsSync(memPath)) {
-      parts.push("## Memory\n" + fs.readFileSync(memPath, "utf8"));
-    }
+    // Same file buildAgentSystem injects — an A2A turn must not read a
+    // different memory than a normal turn, or the agent contradicts itself
+    // depending on who asked.
+    const memory = readAgentMemory(projectPath, toAgent.slug);
+    if (memory) parts.push("## Memory\n" + memory);
   }
   return parts.join("\n\n");
 }
 
+/** What the peer is here to DO. The two halves of the split the `--code` flag
+ *  names: an exchange is either people talking about the code, or a working
+ *  session on it. The prompt says which, and the adapter backs it with the
+ *  runtime's own read-only mode so the sentence is enforced, not just asked. */
+function modeBrief(mode) {
+  if (mode === "code") {
+    return [
+      "This is a CODING session. You are expected to do the work, not describe it:",
+      "read what you need, make the changes, run what verifies them — then report what you actually",
+      "changed, briefly. Your write access is on for this exchange.",
+    ].join(" ");
+  }
+  return [
+    "This is a conversation, not a task. Answer directly and concisely.",
+    "You are in READ-ONLY mode: you can look at anything, but you cannot change it.",
+    "If answering well would mean editing the codebase, say what you would change and why —",
+    "the sender can reopen the exchange as a coding session if they want it done.",
+  ].join(" ");
+}
+
+/** Build the recipient RUNTIME's system prompt. There is no persona to load —
+ *  the CLI is itself, with its own project context — so this says only who it
+ *  is being addressed as, what kind of exchange this is, and the same etiquette
+ *  every peer gets. */
+export function buildA2APeerSystem({ projectName, peer, selfAddress, peerAddress, config, mode = "chat" }) {
+  return [
+    `You are "${selfAddress}" inside APX — the ${peer.runtime} CLI, reached as an agent-to-agent peer.`,
+    projectName ? `Project: ${projectName}.` : "",
+    `A message from ${peerAddress} follows. ${modeBrief(mode)}`,
+    a2aEtiquette({ selfAddress, peerAddress, config }),
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+/** The thread so far, as text, for a peer that cannot resume its own session. */
+function flattenHistory(history) {
+  if (!history?.length) return "";
+  const lines = history.map((m) =>
+    m.role === "assistant" ? `You said:\n${m.content}` : m.content,
+  );
+  return ["## Earlier in this exchange (oldest first)", ...lines].join("\n\n");
+}
+
 /**
- * Run one A2A turn: build system, call engine, return { text, usage }.
- * Throws on engine failure — caller decides how to surface.
+ * Run one A2A turn against an AGENT: build system, call engine.
+ * Returns { text, usage, model }. Throws on engine failure.
  */
-export async function replyAsAgent({ projectPath, toAgent, fromAgent, body, config }) {
-  if (!toAgent?.fields?.Model) {
-    throw new Error(`agent ${toAgent?.slug || "?"} has no model`);
+export async function replyAsAgent({
+  project,
+  projectPath,
+  toAgent,
+  fromAgent,
+  body,
+  config,
+  history = [],
+  selfAddress = null,
+  peerAddress = null,
+  mode = "chat",
+  projects,
+  plugins,
+  registries,
+  projectId = null,
+  tools = true,
+  signal = null,
+  runAgentTurnFn = runAgentTurn,
+}) {
+  const modelId = await resolveAgentModel({ agent: toAgent, config });
+  if (!modelId) {
+    throw new Error(
+      `no model for agent ${toAgent?.slug || "?"} (no override, no router default)`
+    );
+  }
+  const peer = peerAddress || fromAgent?.slug || "peer";
+  const system = buildA2AReplySystem({
+    projectPath: projectPath || project?.path,
+    toAgent,
+    fromAgent,
+    config,
+    selfAddress,
+    peerAddress: peer,
+    mode,
+  });
+
+  const p = project || {
+    id: projectId || 0,
+    path: projectPath || "",
+    config,
+  };
+
+  // If tools are explicitly disabled, or there is no real projectPath on disk,
+  // execute single turn with fallback without tool session.
+  if (!tools || !projectPath) {
+    const result = await callEngineWithFallback({
+      modelId,
+      system,
+      messages: [...history, { role: "user", content: `From ${peer}:\n\n${body}` }],
+      config,
+      signal,
+    });
+    return { text: result.text, usage: result.usage, model: result.model || modelId };
   }
-  const system = buildA2AReplySystem({ projectPath, toAgent, fromAgent });
-  const result = await callEngine({
-    modelId: toAgent.fields.Model,
+
+  const result = await runAgentTurnFn({
+    p,
+    agent: toAgent,
+    modelId,
     system,
-    messages: [{ role: "user", content: `From ${fromAgent.slug}:\n\n${body}` }],
+    prompt: `From ${peer}:\n\n${body}`,
+    previousMessages: history,
+    channel: CHANNELS.A2A,
+    channelMeta: {
+      projectId: p.id,
+      projectPath: p.path,
+      from: peer,
+      to: selfAddress || toAgent.slug,
+      mode,
+    },
+    tools: true,
+    projects,
+    plugins,
+    registries,
     config,
+    signal,
+  });
+
+  return {
+    text: result.text,
+    usage: result.usage,
+    model: result.model || modelId,
+    trace: result.trace,
+    media: result.media,
+  };
+}
+
+/**
+ * Run one A2A turn against the daemon super-agent mode. Unlike a synthetic
+ * project agent, this keeps the configured identity, memory, project context,
+ * permission guard and tool loop — including the ability to decide whether an
+ * agent's escalation belongs on Telegram.
+ */
+export async function replyAsSuperAgent({
+  peer,
+  fromAddress,
+  body,
+  config,
+  history = [],
+  projectPath,
+  projectId = null,
+  projectName = "",
+  projects,
+  plugins,
+  registries,
+  mode = "chat",
+  runSuperAgentFn = runSuperAgent,
+}) {
+  const selfAddress = canonicalPeerAddress(peer);
+  const contextNote = [
+    a2aEtiquette({ selfAddress, peerAddress: fromAddress, config }),
+    mode === "code"
+      ? "This exchange was explicitly opened as a CODING session. Do the requested work under the normal permission policy, verify it, then reply with the result."
+      : "This exchange is agent coordination. Use tools only when the message requires action; otherwise answer directly.",
+  ].join("\n\n");
+  const result = await runSuperAgentFn({
+    globalConfig: config,
+    projects,
+    plugins,
+    registries,
+    prompt: `From ${fromAddress}:\n\n${body}`,
+    contextNote,
+    previousMessages: history,
+    channel: CHANNELS.A2A,
+    channelMeta: {
+      projectId,
+      projectName,
+      projectPath,
+      from: fromAddress,
+      to: selfAddress,
+      mode,
+    },
+    completionContract: mode === "code",
+  });
+  return { text: result.text, usage: result.usage, model: result.model || null };
+}
+
+/**
+ * Run one A2A turn against a RUNTIME: spawn the CLI and read its answer.
+ *
+ * `resumeSessionId` is the whole point. A runtime that continues its own
+ * session already lived through the earlier turns, so nothing is replayed and
+ * nothing is re-read — the exchange costs one message, not one transcript.
+ * A thread with no session on record (a runtime that can't keep one, or a first
+ * turn) gets the history carried in the prompt instead, so it is never amnesic.
+ */
+export async function replyAsRuntime({
+  peer,
+  fromAddress,
+  body,
+  config,
+  history = [],
+  cwd,
+  projectName = "",
+  resumeSessionId = null,
+  timeoutMs = 5 * 60 * 1000,
+  mode = "chat",
+}) {
+  const rt = getRuntime(peer.runtime);
+  const system = buildA2APeerSystem({
+    projectName,
+    peer,
+    selfAddress: peer.address,
+    peerAddress: fromAddress,
+    config,
+    mode,
+  });
+  const carried = resumeSessionId ? "" : flattenHistory(history);
+  const prompt = [carried, `From ${fromAddress}:\n\n${body}`].filter(Boolean).join("\n\n---\n\n");
+
+  const startedAt = Date.now();
+  const r = await rt.run({
+    system,
+    prompt,
+    cwd,
+    timeoutMs,
+    sessionKey: a2aSessionKey(fromAddress, peer.address),
+    resumeSessionId,
+    mode,
+  });
+
+  // A killed process can outlive its own SIGTERM, so "did we reach the
+  // deadline", not "how long did we wait".
+  const timedOut = Date.now() - startedAt >= timeoutMs;
+  const failure = runtimeLooksLikeFailure(r, {
+    timedOut,
+    timeoutS: Math.round(timeoutMs / 1000),
+  });
+  if (failure.failed) {
+    throw new Error(`${peer.runtime} did not answer: ${failure.reason}`);
+  }
+
+  return {
+    text: r.output,
+    // attribution-exempt: an external CLI spends its own tokens on its own
+    // model; APX made no model call here and has nothing truthful to record.
+    usage: null,
+    model: null,
+    runtime: peer.runtime,
+    mode,
+    sessionId: r.sessionId || resumeSessionId || null,
+    // Why there is no session, when there is none — a null the caller can
+    // explain beats a null it can only report.
+    sessionNote: r.sessionId || resumeSessionId ? null : r.sessionNote || null,
+  };
+}
+
+/** One turn against whichever kind of peer this is. The caller logs the result
+ *  the same way for all — that sameness is the point of the split living here
+ *  rather than in the route. */
+export async function replyToPeer({ peer, ...rest }) {
+  if (peer.kind === "runtime") return replyAsRuntime({ peer, ...rest });
+  if (peer.kind === "super_agent") return replyAsSuperAgent({ peer, ...rest });
+  return replyAsAgent({
+    ...rest,
+    toAgent: peer.agent,
+    selfAddress: peer.address,
+    peerAddress: rest.fromAddress,
   });
-  return { text: result.text, usage: result.usage };
 }

package/src/core/agent/abort.js

@@ -0,0 +1,25 @@
+// "Was this throw the abort we asked for?" — the one home for that question.
+//
+// It lives in core because both sides of a stopped turn need it: the daemon
+// routes that own the AbortController (host/daemon/api/*), and the group cascade
+// (agent/group/run-group-turn.js), which has to tell "the owner pressed Stop"
+// apart from "this speaker's model fell over" while deciding whether to persist
+// the partial and end the room's turn quietly. core/ cannot import from host/,
+// so a second copy was the alternative.
+//
+// Checked against OUR controller, not just the error: an engine that aborts its
+// own fetch on a timeout also throws AbortError, and treating that as "the user
+// stopped it" would swallow a genuine failure and show the user a turn they
+// never interrupted.
+//
+// @param {unknown} e the thrown value
+// @param {{signal?: AbortSignal}|AbortController|null} controller the turn's own controller
+export function wasAborted(e, controller) {
+  if (!controller?.signal?.aborted) return false;
+  return e?.name === "AbortError" || /abort/i.test(String(e?.message || ""));
+}
+
+/** Same question, when all you were handed is the signal itself. */
+export function wasAbortedBySignal(e, signal) {
+  return wasAborted(e, signal ? { signal } : null);
+}

package/src/core/agent/agent-model.js

@@ -0,0 +1,58 @@
+// Which model an APC agent runs on. Single home for the question "what does
+// this agent's `Model:` field mean?" — every caller (daemon routes, routines,
+// the call_agent tool, A2A, the Telegram routed agent) goes through here.
+//
+// The field has three states, not two:
+//
+//   Model: groq:llama-3.3-70b-versatile   → forced. This model, no router.
+//   Model: inherit                        → no override. APC's normalizer
+//                                           writes this marker, and it is the
+//                                           documented idiom in
+//                                           `.apc/agents/<slug>.md`.
+//   (absent / empty)                      → no override.
+//
+// `inherit` used to reach `callEngine` as a literal model id, which parses as a
+// provider-less name and fails the run. It is a marker, never a model.
+import { resolveActiveModel } from "./model-router.js";
+
+const INHERIT = "inherit";
+
+/**
+ * The model this agent forces, or `""` when it inherits.
+ * @param {{ fields?: Record<string, unknown> }} agent an entry from readAgents()
+ */
+export function agentForcedModel(agent) {
+  const raw = agent?.fields?.Model;
+  if (typeof raw !== "string") return "";
+  const model = raw.trim();
+  if (!model || model.toLowerCase() === INHERIT) return "";
+  return model;
+}
+
+/** Whether a raw `Model:` value means "inherit" (absent, empty or the marker). */
+export function isInheritedModel(model) {
+  if (typeof model !== "string") return !model;
+  const v = model.trim();
+  return !v || v.toLowerCase() === INHERIT;
+}
+
+/**
+ * The model to actually call for this agent: an explicit per-call override
+ * first, then the agent's forced model, then whatever the router resolves for
+ * the super-agent (which walks the fallback chain and skips unhealthy
+ * providers). Returns `null` when nothing is configured anywhere.
+ */
+export async function resolveAgentModel({ agent, config, override } = {}) {
+  // Per-call override (the chat picker) wins only when it is a real model
+  // id. `inherit` / empty from the picker means "use the agent's card", not
+  // "call a provider named inherit". The agent's own `Model: inherit` then
+  // falls through to the router.
+  const forced = agentForcedModel({ fields: { Model: override ?? "" } }) || agentForcedModel(agent);
+  if (forced) return forced;
+  try {
+    const routing = await resolveActiveModel(config);
+    return routing?.modelId || null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,101 @@
+// Project-agent tool allowlist.
+//
+// Super-agent = the full registry. A project agent (Magui, Scout, …) is a
+// specialist: its `.apc/agents/<slug>.md` `tools:` field is the allowlist, not
+// a hint. The picker stores HTTP-catalog names (`glob`, `memory_get`,
+// `agent_list`); the loop speaks native + bridged names (`search_files` is
+// native, `glob` is bridged, `read_self_memory` is native). This module is the
+// one map between those vocabularies.
+import { listCallableToolNames } from "#core/agent/tools/registry.js";
+import { TOOLS } from "#core/agent/tools/names.js";
+
+export const AGENT_TOOL_ALIASES = Object.freeze({
+  memory_get: TOOLS.READ_SELF_MEMORY,
+  memory_set: TOOLS.REMEMBER,
+  memory_append: TOOLS.REMEMBER,
+  memory_list: TOOLS.READ_SELF_MEMORY,
+  agent_list: TOOLS.LIST_AGENTS,
+  agent_get: TOOLS.LIST_AGENTS,
+  project_info: TOOLS.LIST_PROJECTS,
+  run_command: TOOLS.RUN_SHELL,
+  mcp_list: TOOLS.LIST_MCPS,
+  mcp_run: TOOLS.CALL_MCP,
+  session_list: TOOLS.SEARCH_SESSIONS,
+  session_search: TOOLS.SEARCH_SESSIONS,
+  session_get: TOOLS.SEARCH_SESSIONS,
+});
+
+export function declaredAgentTools(agent) {
+  const raw = agent?.fields?.Tools ?? agent?.tools ?? [];
+  if (Array.isArray(raw)) return raw.map((s) => String(s).trim()).filter(Boolean);
+  if (typeof raw === "string") return raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+// What an agent with no declared `tools:` may NOT call. Everything else it can.
+//
+// The default used to be a narrow read/search/memory set, and the result was
+// agents that could not do their job: a social producer that could not reach the
+// MCP holding its publishing tools, a routine that could not file the task it
+// had just written. Every one of those was diagnosed as a bug, one card at a
+// time, long after the run that needed it had already failed.
+//
+// So capability is the default and removal is the deliberate act: declare
+// `tools:` on the card when an agent should be narrower than the registry. What
+// stays out is only what belongs to the super-agent as the host, not work an
+// agent might reasonably need.
+//
+// This is an ALLOWLIST gate, not a prompt budget — lightweight channels still
+// send the small base set and expand through discover_tools, so a broad default
+// costs nothing on a chat turn. It only stops the runtime from refusing.
+const HOST_ONLY_TOOLS = Object.freeze([
+  // The super-agent's own persona and privilege level. An agent rewriting who
+  // APX is, or widening its own permissions, is never the task.
+  TOOLS.SET_IDENTITY,
+  TOOLS.SET_PERMISSION_MODE,
+  // Registry surgery: adding projects / importing agents reshapes the install
+  // the agent is running inside.
+  TOOLS.ADD_PROJECT,
+  TOOLS.IMPORT_AGENT,
+]);
+
+/** Everything a project agent may call by default: the registry minus the host's own. */
+export function defaultAgentToolNames() {
+  const deny = new Set(HOST_ONLY_TOOLS);
+  return listCallableToolNames().filter((n) => !deny.has(n));
+}
+
+/**
+ * Names this agent may call this turn.
+ *
+ * - `override` set (routine.allowed_tools) wins, including `[]` = no tools.
+ * - else the agent's declared `tools:` field, when it declares one.
+ * - no declaration → the broad default (see defaultAgentToolNames).
+ * Unknown names are dropped, catalog aliases are rewritten, duplicates collapse.
+ *
+ * @returns {string[]}
+ */
+export function resolveAgentAllowedTools(agent, { override } = {}) {
+  if (Array.isArray(override)) return resolveNames(override);
+  const declared = declaredAgentTools(agent);
+  if (!declared.length) return defaultAgentToolNames();
+  const resolved = resolveNames(declared);
+  // A card whose every name is stale would otherwise mean a silent no-tools
+  // turn that dumps markup as the "answer". Capability beats a broken card.
+  return resolved.length ? resolved : defaultAgentToolNames();
+}
+
+function resolveNames(names) {
+  const known = new Set(listCallableToolNames());
+  const out = [];
+  const seen = new Set();
+  for (const raw of names) {
+    const name = String(raw || "").trim();
+    if (!name) continue;
+    const candidate = known.has(name) ? name : (AGENT_TOOL_ALIASES[name] || name);
+    if (!known.has(candidate) || seen.has(candidate)) continue;
+    seen.add(candidate);
+    out.push(candidate);
+  }
+  return out;
+}