@agentprojectcontext/apx 1.60.1 → 1.62.0

package/package.json

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

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

@@ -60,6 +60,12 @@ export async function runSuperAgent({
   // Null disables human-in-the-loop (tools that need confirmation fail
   // immediately instead of waiting for user input).
   requestConfirmation = null,
+  // A2A callback sink: when a background tool (call_runtime) finishes out of
+  // band, it feeds the result back into the super-agent via this function so
+  // the agent — not a raw dump — relays it to the user. Channel-specific
+  // (telegram wires it to a follow-up streamed turn). Null → tools fall back to
+  // a direct channel send. See call-runtime.js.
+  backgroundResultSink = null,
   // When true, suppress the static "Available skills" slug-dump hint block
   // because a per-turn skill inspector already injected the right context.
   // Set by the daemon's super-agent endpoint when config.skills.inspector is on.
@@ -131,7 +137,7 @@ export async function runSuperAgent({
     overrideModel,
     toolSchemas,
     makeToolHandlers,
-    toolHandlerCtx: { projects, plugins, registries, globalConfig, channel, toolSession, requestConfirmation },
+    toolHandlerCtx: { projects, plugins, registries, globalConfig, channel, channelMeta, toolSession, requestConfirmation, backgroundResultSink },
     onEvent,
     signal,
     onToken,

package/src/core/agent/tools/handlers/_github.js

@@ -0,0 +1,22 @@
+// Shared helper for the GitHub agent tools (github-*.js). Underscore file — no
+// tool `name:` of its own. Resolves the project's effective GitHub integration
+// (its own record wins over the default project's) and hands back the token.
+import { resolveProject } from "../helpers.js";
+import { resolveIntegration } from "#core/integrations/index.js";
+
+export function resolveGithub(projects, project) {
+  const p = resolveProject(projects, project);
+  const resolved = resolveIntegration({ projectStorage: p.storagePath, slug: "github" });
+  if (!resolved) {
+    throw new Error(
+      "GitHub is not connected for this project. Ask the user to connect it in the web panel → Integrations → Plugins → GitHub.",
+    );
+  }
+  const token = resolved.record.config?.token;
+  if (!token) throw new Error("GitHub integration has no token configured");
+  return { token, scope: resolved.scope };
+}
+
+export const PROJECT_ARG = {
+  project: { type: "string", description: "APX project id/name (optional; defaults to current)" },
+};

package/src/core/agent/tools/handlers/call-runtime.js

@@ -8,6 +8,7 @@ import {
   createRuntimeSession,
   extractRuntimeResult as extractApfResult,
 } from "#core/stores/runtime-sessions.js";
+import { writePendingCallback, deletePendingCallback } from "#core/stores/runtime-callbacks.js";
 import { buildRuntimeBridgeHint as buildApfHint } from "#core/agent/runtime-bridge.js";
 import { detectAll } from "#core/runtimes/detect.js";
 import {
@@ -167,15 +168,38 @@ export default {
             type: "string",
             description: "Optional prior session id (claude/codex/apx) — APX prepends that session's title + last prompt to the prompt so the runtime has context.",
           },
-          timeout_s: { type: "integer", description: "seconds before SIGTERM; default 300" },
+          timeout_s: { type: "integer", description: "seconds before SIGTERM. Foreground default 300; background runs default to 3600 (1h)." },
+          background: {
+            type: "boolean",
+            description: "Run detached instead of blocking this turn. On Telegram this is the DEFAULT (runtimes like claude-code can take many minutes to an hour; blocking would freeze the super-agent). Returns immediately with status:\"launched\"; when the runtime finishes, its result is delivered to this same chat as an automatic message. Set false ONLY when you genuinely need the runtime's output within THIS turn for an immediate follow-up (short tasks).",
+          },
         },
         required: ["runtime", "prompt"],
       },
     },
   },
-  makeHandler: ({ projects, requirePermission }) => async ({ project, agent: slug, runtime, prompt, resume_session_id = null, timeout_s = 300, confirmed = false }) => {
+  makeHandler: ({ projects, requirePermission, plugins, channel, channelMeta, backgroundResultSink = null }) => async ({ project, agent: slug, runtime, prompt, resume_session_id = null, timeout_s = null, background = null, confirmed = false }) => {
     await requirePermission("call_runtime", { dangerous: true, confirmed, args: { runtime } });
 
+    // Async delivery sink: on Telegram we can push the runtime's result back to
+    // the originating chat when it finishes, so the call doesn't have to block
+    // the turn. channelMeta.chatId + the telegram plugin are what make that
+    // possible; without them there's nowhere to deliver a late result, so we
+    // stay synchronous (web/desktop/exec keep their current behavior).
+    const chatId = channelMeta?.chatId ?? null;
+    const tgChannelName = channelMeta?.channelName ?? null;
+    const telegramPlugin = channel === "telegram" && chatId != null ? plugins?.get?.("telegram") : null;
+    // We can report a late result either by re-entering the super-agent (A2A,
+    // preferred — the agent relays in its own voice) or by a direct channel
+    // send (fallback). Either makes background mode viable.
+    const canCallback = !!backgroundResultSink || !!telegramPlugin;
+    // Background by default when we can call back; the model opts out with
+    // background:false when it needs the output inside this same turn.
+    const runInBackground = canCallback && background !== false;
+    // Long runtimes (claude-code sessions) can run for an hour; a detached run
+    // must not be SIGTERM'd at the 5-min foreground default.
+    const effectiveTimeoutS = Number(timeout_s) || (runInBackground ? 3600 : 300);
+
     const p = slug ? resolveProjectForAgent(projects, project, slug) : resolveProject(projects, project);
     const agent = slug ? readAgents(p.path).find((a) => a.slug === slug) : null;
     if (slug && !agent) {
@@ -226,106 +250,191 @@ export default {
       project: p.path,
       resume_session_id: resume_session_id || null,
       resume_resolved: resume.meta ? `${resume.meta.engine}:${resume.meta.id}` : null,
-      timeout_s,
+      timeout_s: effectiveTimeoutS,
+      background: runInBackground,
     });
 
-    try {
-      const r = await rt.run({
-        system: buildRuntimeSystem(p, agent, runtime, session.id, "super_agent_tool"),
-        prompt: effectivePrompt,
-        cwd: p.path,
-        timeoutMs: timeout_s * 1000,
-      });
+    // Run the runtime to completion and finalize (close the session record, log
+    // the transcript, shape the result object). NEVER throws — a thrown spawn is
+    // caught and returned as an error object, so the background path can deliver
+    // it as a callback instead of crashing an un-awaited promise.
+    const runToCompletion = async () => {
+      try {
+        const r = await rt.run({
+          system: buildRuntimeSystem(p, agent, runtime, session.id, "super_agent_tool"),
+          prompt: effectivePrompt,
+          cwd: p.path,
+          timeoutMs: effectiveTimeoutS * 1000,
+        });
 
-      const failure = runtimeLooksLikeFailure(r);
-      const result = extractApfResult(r.output) || (r.output || "").slice(0, 200);
-      closeRuntimeSession({
-        filePath: session.path,
-        externalSessionPath: r.externalSessionPath || null,
-        exitCode: failure.failed && r.exitCode === 0 ? -1 : r.exitCode,
-        result: failure.failed ? `failed: ${failure.reason}` : result,
-      });
+        const failure = runtimeLooksLikeFailure(r);
+        const result = extractApfResult(r.output) || (r.output || "").slice(0, 200);
+        closeRuntimeSession({
+          filePath: session.path,
+          externalSessionPath: r.externalSessionPath || null,
+          exitCode: failure.failed && r.exitCode === 0 ? -1 : r.exitCode,
+          result: failure.failed ? `failed: ${failure.reason}` : result,
+        });
 
-      p.logMessage({
-        agent_slug: actor,
-        channel: "runtime",
-        direction: "in",
-        author: "user",
-        body: effectivePrompt,
-        meta: { runtime, invoked_by: "super_agent_tool", apc_session: session.id, resume_session_id: resume_session_id || null },
-      });
-      p.logMessage({
-        agent_slug: actor,
-        channel: "runtime",
-        direction: "out",
-        type: "agent",
-        actor_id: agent?.slug || runtime,
-        actor_kind: agent?.slug ? "agent" : "engine",
-        author: agent?.slug || runtime,
-        body: r.output || "",
-        meta: {
-          runtime,
-          exit_code: r.exitCode,
-          external_session_path: r.externalSessionPath || null,
-          session_id: r.sessionId || null,
-          apc_session: session.id,
-          invoked_by: "super_agent_tool",
-          failed: failure.failed || false,
-          failure_reason: failure.failed ? failure.reason : null,
-        },
-      });
+        p.logMessage({
+          agent_slug: actor,
+          channel: "runtime",
+          direction: "in",
+          author: "user",
+          body: effectivePrompt,
+          meta: { runtime, invoked_by: "super_agent_tool", apc_session: session.id, resume_session_id: resume_session_id || null },
+        });
+        p.logMessage({
+          agent_slug: actor,
+          channel: "runtime",
+          direction: "out",
+          type: "agent",
+          actor_id: agent?.slug || runtime,
+          actor_kind: agent?.slug ? "agent" : "engine",
+          author: agent?.slug || runtime,
+          body: r.output || "",
+          meta: {
+            runtime,
+            exit_code: r.exitCode,
+            external_session_path: r.externalSessionPath || null,
+            session_id: r.sessionId || null,
+            apc_session: session.id,
+            invoked_by: "super_agent_tool",
+            failed: failure.failed || false,
+            failure_reason: failure.failed ? failure.reason : null,
+          },
+        });
+
+        if (failure.failed) {
+          log.error(`${runtime} run failed: ${failure.reason}`, {
+            apc_session: session.id,
+            exit_code: r.exitCode,
+            stderr: String(r.stderr || "").slice(0, 500),
+            external_session_path: r.externalSessionPath || null,
+          });
+          return {
+            error: `runtime "${runtime}" did not complete successfully: ${failure.reason}`,
+            runtime,
+            agent: agent?.slug || null,
+            apc_session: session.id,
+            exit_code: r.exitCode,
+            stderr: (r.stderr || "").slice(0, 2000),
+            output: (r.output || "").slice(0, 2000),
+            external_session_path: r.externalSessionPath || null,
+            session_id: r.sessionId || null,
+          };
+        }
 
-      if (failure.failed) {
-        log.error(`${runtime} run failed: ${failure.reason}`, {
+        log.info(`${runtime} run ok`, {
           apc_session: session.id,
           exit_code: r.exitCode,
-          stderr: String(r.stderr || "").slice(0, 500),
           external_session_path: r.externalSessionPath || null,
+          session_id: r.sessionId || null,
+          output_bytes: (r.output || "").length,
         });
+
         return {
-          error: `runtime "${runtime}" did not complete successfully: ${failure.reason}`,
           runtime,
           agent: agent?.slug || null,
           apc_session: session.id,
           exit_code: r.exitCode,
+          result,
+          output: (r.output || "").slice(0, 4000),
           stderr: (r.stderr || "").slice(0, 2000),
-          output: (r.output || "").slice(0, 2000),
+          truncated: (r.output || "").length > 4000,
           external_session_path: r.externalSessionPath || null,
           session_id: r.sessionId || null,
         };
+      } catch (e) {
+        log.error(`${runtime} run threw: ${e.message}`, { apc_session: session.id });
+        try {
+          closeRuntimeSession({
+            filePath: session.path,
+            exitCode: -1,
+            result: `error: ${e.message.slice(0, 200)}`,
+          });
+        } catch {}
+        return { error: `runtime "${runtime}" threw: ${e.message}`, runtime, agent: agent?.slug || null, apc_session: session.id };
       }
+    };
 
-      log.info(`${runtime} run ok`, {
-        apc_session: session.id,
-        exit_code: r.exitCode,
-        external_session_path: r.externalSessionPath || null,
-        session_id: r.sessionId || null,
-        output_bytes: (r.output || "").length,
-      });
+    // Deliver a finished background run. Preferred path (A2A): feed the result
+    // back into the super-agent so it relays in its own voice / chains the next
+    // step — an internal agent-to-agent hand-off. Fallback: a direct channel
+    // send of the raw result. Best-effort: never throws (nothing awaits it).
+    const who = `${runtime}${agent ? ` (agente ${agent.slug})` : ""}`;
+    const deliverCallback = async (res) => {
+      // Take ownership of delivery: drop the durable IOU so the reconciler in
+      // another/next daemon can't also deliver this one. Fallbacks below still
+      // run in-process, so a delete here doesn't risk losing the callback.
+      deletePendingCallback(session.id);
+      const body = res.error ? "" : String(res.result || res.output || "").trim();
+
+      if (backgroundResultSink) {
+        // A2A report phrased for Roby (not the end user). Roby decides how to
+        // relay it and whether a next step is needed.
+        const report = res.error
+          ? `[callback A2A] La tarea que delegaste a ${who} (sesión ${session.id}) FALLÓ: ${res.error}. ` +
+            `Avisale al usuario en tu voz y proponé cómo seguir.`
+          : `[callback A2A] Terminó la tarea que delegaste a ${who} (sesión ${session.id}). ` +
+            `Resultado del agente:\n${body.slice(0, 6000)}\n\n` +
+            `Contale al usuario el resultado en tu voz, breve y claro. No vuelvas a delegar salvo que falte un paso siguiente.`;
+        try {
+          await backgroundResultSink(report);
+          log.info(`${runtime} callback relayed via A2A sink`, { apc_session: session.id });
+          return;
+        } catch (e) {
+          log.error(`${runtime} A2A sink failed, falling back to direct send: ${e.message}`, { apc_session: session.id });
+        }
+      }
+
+      if (!telegramPlugin) return;
+      const head = res.error
+        ? `⚠️ La sesión de ${who} terminó con error (sesión \`${session.id}\`): ${res.error}`
+        : `✅ Terminó la sesión de ${who} (\`${session.id}\`).`;
+      const text = body ? `${head}\n\n${body.slice(0, 3500)}` : head;
+      try {
+        await telegramPlugin.send({ channel: tgChannelName, chat_id: chatId, text });
+        log.info(`${runtime} callback delivered (direct)`, { apc_session: session.id, chat_id: chatId });
+      } catch (e) {
+        log.error(`${runtime} callback send failed: ${e.message}`, { apc_session: session.id });
+      }
+    };
 
+    if (runInBackground) {
+      // Durable IOU: if this daemon dies before the run finishes (crash, pull,
+      // or a task that restarts the daemon), the reconciler on the next daemon
+      // delivers the result from the session record. The in-process path below
+      // deletes it the moment it takes over. Only telegram delivery is wired.
+      if (chatId != null) {
+        writePendingCallback({
+          session_id: session.id,
+          session_path: session.path,
+          channel: "telegram",
+          chat_id: chatId,
+          tg_channel: tgChannelName,
+          runtime,
+          agent: agent?.slug || null,
+          who,
+        });
+      }
+      // Fire-and-forget: don't await into the turn. runToCompletion never
+      // rejects, so this promise is safe un-awaited; the result is pushed to the
+      // chat when the runtime exits.
+      runToCompletion().then(deliverCallback);
       return {
         runtime,
         agent: agent?.slug || null,
         apc_session: session.id,
-        exit_code: r.exitCode,
-        output: (r.output || "").slice(0, 4000),
-        stderr: (r.stderr || "").slice(0, 2000),
-        truncated: (r.output || "").length > 4000,
-        external_session_path: r.externalSessionPath || null,
-        session_id: r.sessionId || null,
+        status: "launched",
+        background: true,
+        note:
+          `La sesión de ${runtime} arrancó en segundo plano y puede tardar varios minutos u horas. ` +
+          `NO esperes ni vuelvas a llamar a call_runtime para esto: el resultado llegará AUTOMÁTICAMENTE a este chat cuando termine. ` +
+          `Respondé al usuario ahora, en una línea, avisándole que la lanzaste y que le vas a avisar acá cuando esté lista.`,
       };
-    } catch (e) {
-      log.error(`${runtime} run threw: ${e.message}`, {
-        apc_session: session.id,
-      });
-      try {
-        closeRuntimeSession({
-          filePath: session.path,
-          exitCode: -1,
-          result: `error: ${e.message.slice(0, 200)}`,
-        });
-      } catch {}
-      throw e;
     }
+
+    return await runToCompletion();
   },
 };

package/src/core/agent/tools/handlers/github-create-issue.js

@@ -0,0 +1,30 @@
+import * as github from "#core/integrations/plugins/github.js";
+import { resolveGithub, PROJECT_ARG } from "./_github.js";
+
+export default {
+  name: "github_create_issue",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "github_create_issue",
+      description: "Open an issue in a GitHub repository.",
+      parameters: {
+        type: "object",
+        properties: {
+          owner: { type: "string", description: "Repo owner (user or org)" },
+          repo: { type: "string", description: "Repo name" },
+          title: { type: "string", description: "Issue title" },
+          body: { type: "string", description: "Issue body (markdown)" },
+          ...PROJECT_ARG,
+        },
+        required: ["owner", "repo", "title"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project, owner, repo, title, body } = {}) => {
+    const { token } = resolveGithub(projects, project);
+    const issue = await github.createIssue(token, { owner, repo, title, body });
+    return { issue: { number: issue.number, url: issue.html_url, title: issue.title } };
+  },
+};

package/src/core/agent/tools/handlers/github-list-repos.js

@@ -0,0 +1,20 @@
+import * as github from "#core/integrations/plugins/github.js";
+import { resolveGithub, PROJECT_ARG } from "./_github.js";
+
+export default {
+  name: "github_list_repos",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "github_list_repos",
+      description: "List GitHub repositories accessible to the connected token.",
+      parameters: { type: "object", properties: { ...PROJECT_ARG } },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project } = {}) => {
+    const { token } = resolveGithub(projects, project);
+    const repos = await github.listRepos(token);
+    return { repos: repos.map((r) => ({ full_name: r.full_name, private: r.private, url: r.html_url, description: r.description })) };
+  },
+};

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

@@ -56,6 +56,10 @@ export const TOOLS = Object.freeze({
   ASANA_CREATE_TASK:   "asana_create_task",
   ASANA_UPDATE_TASK:   "asana_update_task",
 
+  // Integrations — GitHub plugin (see core/integrations/plugins/github.js)
+  GITHUB_LIST_REPOS:   "github_list_repos",
+  GITHUB_CREATE_ISSUE: "github_create_issue",
+
   // Side-effects
   SEND_TELEGRAM:       "send_telegram",
   SET_IDENTITY:        "set_identity",
@@ -104,6 +108,8 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.ASANA_LIST_TASKS,
   TOOLS.ASANA_CREATE_TASK,
   TOOLS.ASANA_UPDATE_TASK,
+  TOOLS.GITHUB_LIST_REPOS,
+  TOOLS.GITHUB_CREATE_ISSUE,
   TOOLS.SEND_TELEGRAM,
   TOOLS.SET_IDENTITY,
   TOOLS.SET_PERMISSION_MODE,

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

@@ -37,6 +37,8 @@ import asanaListProjects from "./handlers/asana-list-projects.js";
 import asanaListTasks from "./handlers/asana-list-tasks.js";
 import asanaCreateTask from "./handlers/asana-create-task.js";
 import asanaUpdateTask from "./handlers/asana-update-task.js";
+import githubListRepos from "./handlers/github-list-repos.js";
+import githubCreateIssue from "./handlers/github-create-issue.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 import { TOOLS, CODE_CHANNEL_TOOLS } from "./names.js";
@@ -85,6 +87,8 @@ const NATIVE_TOOLS = [
   asanaListTasks,
   asanaCreateTask,
   asanaUpdateTask,
+  githubListRepos,
+  githubCreateIssue,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env

package/src/core/channels/telegram/dispatch.js

@@ -26,7 +26,7 @@ import * as askFlow from "./ask.js";
 import { telegramAuthorLabel } from "./helpers.js";
 import { handleIncomingPhoto } from "./inbound/photo.js";
 import { handleIncomingAudio } from "./inbound/audio.js";
-import { buildStreamHandler, runTelegramSuperAgent, telegramErrorText, sendFinalReply } from "./reply.js";
+import { buildStreamHandler, runTelegramSuperAgent, telegramErrorText, sendFinalReply, runFollowupTurn } from "./reply.js";
 import { t, resolveLang } from "#core/i18n/index.js";
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -285,6 +285,28 @@ export async function handleUpdate(self, u) {
       // strip the prefix from the user prompt before sending to the loop.
       const slashed = tryResolveSkillCommand(text, { projectPath: target?.path });
 
+      // A2A callback sink: when a background call_runtime finishes out of band,
+      // it invokes this to feed the sub-agent/runtime result back into a fresh
+      // super-agent turn — so Roby relays it in its own voice instead of dumping
+      // raw output. Self-referential so a relay turn that delegates again keeps
+      // the loop. Only wired when we have a chat to stream back to.
+      let backgroundResultSink = null;
+      if (chat_id) {
+        backgroundResultSink = async (reportText) =>
+          runFollowupTurn(self, {
+            chat_id,
+            reportText,
+            target,
+            author,
+            authorId: msg.from?.id,
+            relationshipBlock,
+            allowedTools,
+            agentDisplay,
+            update_id: u.update_id,
+            backgroundResultSink,
+          });
+      }
+
       try {
         const sa = await runTelegramSuperAgent(self, {
           chat_id,
@@ -298,6 +320,7 @@ export async function handleUpdate(self, u) {
           contextNote: slashed.handled ? slashed.contextNote : "",
           signal: abortCtrl.signal,
           onEvent,
+          backgroundResultSink,
         });
         replyText = sa.text;
         replyAuthor = sa.name || agentDisplay;

package/src/core/channels/telegram/reply.js

@@ -8,7 +8,7 @@
 import { runSuperAgent } from "#core/agent/super-agent.js";
 import { TELEGRAM_TOOL_ITERS } from "#core/agent/constants.js";
 import { stripThinking } from "#core/util/thinking.js";
-import { appendGlobalMessage } from "#core/stores/messages.js";
+import { appendGlobalMessage, getRecentTelegramTurnsFromFs } from "#core/stores/messages.js";
 import { CHANNELS } from "#core/constants/channels.js";
 import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
 import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
@@ -100,7 +100,7 @@ export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
  */
 export function runTelegramSuperAgent(self, {
   chat_id, prompt, previousMessages, target, author, authorId, relationshipBlock,
-  allowedTools, contextNote, signal, onEvent,
+  allowedTools, contextNote, signal, onEvent, backgroundResultSink = null,
 }) {
   const confirmAdapter = createTelegramConfirmAdapter({
     token: resolveBotToken(self.channel),
@@ -130,6 +130,7 @@ export function runTelegramSuperAgent(self, {
     signal,
     onEvent,
     requestConfirmation: confirmAdapter.requestConfirmation,
+    backgroundResultSink,
     // Autonomy budget: Telegram is the "do the whole task for me" surface, so it
     // gets a real multi-step budget instead of the conversational default (which
     // cut tasks off after ~9 actions to ask "continue?"). Tunable via
@@ -138,6 +139,82 @@ export function runTelegramSuperAgent(self, {
   });
 }
 
+/**
+ * Run a follow-up super-agent turn triggered internally (not by an inbound
+ * message) — the A2A callback path. A background tool (call_runtime) finished
+ * out of band; `reportText` is the sub-agent/runtime result phrased as an
+ * internal report. We log it as a synthetic inbound so it lands in history,
+ * then run a normal streamed turn so Roby relays it to the user in its own
+ * voice (and can chain the next step). The same `backgroundResultSink` is
+ * forwarded so a relay turn that delegates again keeps the A2A loop intact.
+ * Best-effort: never throws (nothing awaits it).
+ */
+export async function runFollowupTurn(self, {
+  chat_id, reportText, target, author, authorId, relationshipBlock,
+  allowedTools, agentDisplay, update_id, backgroundResultSink = null,
+}) {
+  if (!chat_id || !reportText) return;
+  try {
+    // Synthetic inbound so the report is part of the rolling history. Tagged
+    // a2a_callback + a distinct author so it reads as an internal hand-off, not
+    // a user turn.
+    appendGlobalMessage({
+      channel: CHANNELS.TELEGRAM,
+      direction: "in",
+      type: "user",
+      actor_id: "a2a",
+      external_id: `a2a-${update_id}-${chat_id}`,
+      author: "a2a",
+      body: reportText,
+      meta: { chat_id, tg_channel: self.channel.name, a2a_callback: true },
+    });
+
+    const previousMessages = getRecentTelegramTurnsFromFs({ chat_id, keepRecent: 40, max_age_hours: 24 });
+    const { onEvent, state } = buildStreamHandler(self, { chat_id, update_id, agentDisplay });
+    const stopTyping = self._startTyping(chat_id);
+    let replyText;
+    let replyAuthor;
+    let saUsage = null;
+    try {
+      const sa = await runTelegramSuperAgent(self, {
+        chat_id,
+        prompt: reportText,
+        previousMessages,
+        target,
+        author,
+        authorId,
+        relationshipBlock,
+        allowedTools,
+        onEvent,
+        backgroundResultSink,
+      });
+      replyText = sa.text;
+      replyAuthor = sa.name || agentDisplay;
+      saUsage = sa.usage;
+    } catch (e) {
+      self.log(`telegram[${self.channel.name}] a2a followup failed: ${e.message}`);
+      replyText = telegramErrorText(self, e);
+      replyAuthor = agentDisplay;
+    }
+    stopTyping();
+    await sendFinalReply(self, {
+      chat_id,
+      update_id,
+      replyText,
+      replyAuthor,
+      replyActorId: SUPERAGENT_ACTOR_ID,
+      replyKind: "superagent",
+      saUsage,
+      streamedCount: state.streamedCount,
+      lastStreamedText: state.lastStreamedText,
+      agentDisplay,
+      extraMeta: { a2a_relay: true },
+    });
+  } catch (e) {
+    self.log(`telegram[${self.channel.name}] a2a followup crashed: ${e.message}`);
+  }
+}
+
 /** Localized "couldn't reply" text for a failed super-agent turn (model itself
  * failed, so it can't author this — templated, but follows the user's language). */
 export function telegramErrorText(self, e) {