@agentprojectcontext/apx 1.42.0 → 1.42.2

package/package.json

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

package/src/core/agent/constants.js

@@ -5,6 +5,16 @@
 // Coding surfaces (web Code / terminal Build) raise this via maxIters and use
 // the finish-tool completionContract instead.
 export const MAX_TOOL_ITERS = 10;
+// Telegram is the "do real work for me" conversational surface (the super-agent
+// Roby): it needs to chain explore→edit→verify→close autonomously, not stop
+// after ~9 actions and ask "want me to continue?". A budget of 10 left only one
+// usable action step before the reserved wrap-up, so multi-step tasks routinely
+// cut off mid-job. We give it a real autonomy budget (mirroring the TUI Code
+// surface's maxIters:40) while keeping it below the coding surfaces. The
+// reserved final-step wrap-up still applies, but now only fires when a task
+// genuinely exhausts this budget — a rare safety floor, not the default close.
+// Overridable per-deployment via config.super_agent.telegram_max_iters.
+export const TELEGRAM_TOOL_ITERS = 24;
 export const ACK_ONLY_TOOLS = new Set(["send_telegram"]);
 export const MAX_CONSECUTIVE_ACKS = 2;
 // Tools whose semantics REQUIRE handing control back to the user. After the

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

@@ -84,20 +84,32 @@ export const FINISH_TOOL_SCHEMA = {
   },
 };
 
-// Behavioral nudge appended to the system prompt for the ONE tool-free wrap-up
-// step at the end of a turn (see the loop's `isFinalWrapUp`). This shapes
-// BEHAVIOR only — it never dictates wording or supplies a canned/templated
-// sentence. The reply the user sees is 100% model-authored and varies with
-// what the model actually did this turn. We do NOT mention any "tool limit":
-// the model just speaks from where it is. Critically it must not claim work it
-// didn't do (weak models otherwise fabricate "all done").
-const WRAPUP_NUDGE =
-  "\n\n[Internal note — last step of this turn. No more tools will run now. " +
-  "Reply in plain prose, in the user's language, from your own context: briefly " +
-  "say what you actually accomplished so far (check the tool results above — do " +
-  "NOT claim anything you didn't do), and if work is still pending, name what's " +
-  "left and ask the user whether you should continue. Do not mention limits, " +
-  "steps, or iterations — just talk naturally.]";
+// In-band signal injected as a CONVERSATION turn (not a system suffix) for the
+// ONE tool-free wrap-up step at the end of a turn (see the loop's
+// `isFinalWrapUp`). Delivering it through the message channel — the way a tool
+// result arrives — makes weak models reliably author a reply instead of
+// returning empty, because they always answer the latest turn. It shapes
+// BEHAVIOR only: it never dictates wording or supplies a canned sentence. The
+// reply the user sees is 100% model-authored and varies with what the model
+// actually did this turn. Critically it must not claim work it didn't do (weak
+// models otherwise fabricate "all done").
+//
+// Unlike a hard "iteration limit" message, it asks the model to surface the
+// situation NATURALLY ("this is taking more steps than I expected") plus a
+// concrete recap of what it found and did NOT find — so the closing reads like
+// a human status update, never robotic system jargon.
+const WRAPUP_SIGNAL =
+  "[Internal turn note — this is NOT from the user. You've taken several tool " +
+  "steps this turn and the task isn't finished; no more tools will run now. " +
+  "Write the user ONE short, natural closing message, in their language, " +
+  "entirely in your own words:\n" +
+  "- Concretely recap what you actually did and what you found so far — and be " +
+  "honest about what you did NOT find or couldn't resolve yet. Read the tool " +
+  "results above; do not claim anything you didn't do.\n" +
+  "- Mention plainly that this is taking more steps than expected and isn't done.\n" +
+  "- Ask whether they want you to keep going.\n" +
+  "Talk like a person giving a quick status update. Do NOT emit a tool call, " +
+  "JSON, or system jargon like \"iteration\" or \"limit\".]";
 
 /**
  * Shared tool-calling agent loop used by super-agent and future surfaces.
@@ -301,8 +313,8 @@ export async function runAgent({
     // Rather than cut off silently mid-tool-call, we run ONE tool-free step so
     // the model writes a natural closing in its OWN words — what it did, what's
     // left, and (if anything remains) whether to continue. We change only the
-    // STRUCTURE (no tools this step) + a behavioral nudge; the wording is
-    // entirely the model's. Coding surfaces keep their finish-tool flow, so
+    // STRUCTURE (no tools this step) + an in-band directive turn (WRAPUP_SIGNAL);
+    // the wording is entirely the model's. Coding surfaces keep their finish-tool flow, so
     // this never applies under completionContract.
     const isFinalWrapUp =
       !useContract && effectiveSchemas.length > 0 && iter === maxIters - 1;
@@ -322,8 +334,14 @@ export async function runAgent({
     let result;
     try {
       result = await tryCallEngine({
-        system: isFinalWrapUp ? baseSystem + WRAPUP_NUDGE : baseSystem,
-        messages: conversation,
+        system: baseSystem,
+        // Wrap-up: deliver the "you're out of steps, summarize + ask" directive
+        // as the latest CONVERSATION turn so the model treats it like any other
+        // turn it must answer — far more reliable than a system suffix on weak
+        // models. Ephemeral: built fresh here, never persisted to history.
+        messages: isFinalWrapUp
+          ? [...conversation, { role: "user", content: WRAPUP_SIGNAL }]
+          : conversation,
         config: globalConfig,
         // On the wrap-up step we withhold tools entirely so the model must
         // answer in prose — same as a real engine called with tools omitted.

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

@@ -0,0 +1,62 @@
+// Low-level Telegram Bot API client — the single place the raw JSON endpoints
+// are called. Higher layers (the poller's send/typing/keyboard methods, the
+// confirmation adapter, the ask flow) compose these instead of hand-rolling
+// fetch boilerplate, so each endpoint's quirks live in exactly one spot. These
+// used to be duplicated across the poller AND the confirm adapter.
+//
+// Every call is token-explicit (no channel/config coupling) so it's reusable
+// from any surface — poller, adapter, routines, tests. Media uploads (multipart
+// FormData) stay in ./media.js; this module owns the JSON endpoints.
+import { API_BASE } from "./media.js";
+
+/**
+ * POST a JSON body to a Bot API method. Returns the parsed `result` on success;
+ * throws on transport failure or a non-ok Telegram response. Best-effort callers
+ * (typing, keyboard edits, callback acks) wrap this in their own try/catch.
+ */
+async function apiCall(token, method, body) {
+  const res = await fetch(`${API_BASE}/bot${token}/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!json.ok) throw new Error(json.description || `${method} failed (${res.status})`);
+  return json.result;
+}
+
+/** sendMessage: the plain text reply (optionally with an inline keyboard). */
+export function sendMessage(token, chatId, { text, reply_markup, parse_mode } = {}) {
+  const body = { chat_id: chatId, text };
+  if (reply_markup) body.reply_markup = reply_markup;
+  if (parse_mode) body.parse_mode = parse_mode;
+  return apiCall(token, "sendMessage", body);
+}
+
+/** sendChatAction: the "typing…" indicator (auto-clears after ~5s). */
+export function sendChatAction(token, chatId, action = "typing") {
+  return apiCall(token, "sendChatAction", { chat_id: chatId, action });
+}
+
+/** editMessageReplyMarkup: swap/clear the inline keyboard on a sent message. */
+export function editMessageReplyMarkup(token, chatId, messageId, reply_markup) {
+  const body = { chat_id: chatId, message_id: messageId };
+  if (reply_markup) body.reply_markup = reply_markup;
+  return apiCall(token, "editMessageReplyMarkup", body);
+}
+
+/** answerCallbackQuery: clear the spinner on a tapped inline button (+ toast). */
+export function answerCallbackQuery(token, callbackQueryId, text) {
+  const body = { callback_query_id: callbackQueryId };
+  if (text) body.text = text;
+  return apiCall(token, "answerCallbackQuery", body);
+}
+
+/** getUpdates: long-poll for inbound updates from a given offset. */
+export async function getUpdates(token, { offset = 0, timeout = 25 } = {}) {
+  const res = await fetch(`${API_BASE}/bot${token}/getUpdates?timeout=${timeout}&offset=${offset}`);
+  if (!res.ok) throw new Error(`getUpdates ${res.status}`);
+  const json = await res.json();
+  if (!json.ok) throw new Error(json.description || "telegram error");
+  return json.result || [];
+}

package/src/core/channels/telegram/ask-callbacks.js

@@ -0,0 +1,238 @@
+// ask_questions flow orchestration for Telegram, extracted from the host poller
+// so that file stays focused on process lifecycle. Like dispatch.js, every
+// function takes the poller instance (`self`) and reaches its I/O surface
+// (self._send / _editKeyboard / _answerCallback / _startTyping) and config
+// through it. The flow's own state machine lives in ./ask.js; this is the glue
+// that turns its decisions into Telegram messages and re-enters the reply path.
+import * as askFlow from "./ask.js";
+import { resolveBotToken } from "./helpers.js";
+import { buildStreamHandler, runTelegramSuperAgent, telegramErrorText, sendFinalReply } from "./reply.js";
+import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
+import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
+import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
+
+/**
+ * Route an inbound callback_query. ask_questions button presses are handled
+ * here; everything else falls through to the confirmation adapter. Both use
+ * `apx:<verb>:...` namespacing but the ask flow owns its own state.
+ */
+export async function handleCallbackQuery(self, callbackQuery) {
+  const data = callbackQuery.data || "";
+  if (data.startsWith("apx:ask:")) {
+    await handleAskCallback(self, callbackQuery);
+    return;
+  }
+  const adapter = createTelegramConfirmAdapter({
+    token: resolveBotToken(self.channel),
+    chatId: callbackQuery.message?.chat?.id,
+    pendingStore: getConfirmStore(),
+  });
+  const handled = await adapter.handleCallbackQuery(callbackQuery);
+  if (!handled) {
+    self.log(`telegram[${self.channel.name}] unhandled callback_query: ${callbackQuery.data}`);
+  }
+}
+
+/**
+ * Draw the current question as a fresh message with its inline keyboard, wiping
+ * the previous question's keyboard so the chat reads as a clean history.
+ */
+export async function renderQuestion(self, state) {
+  const text = askFlow.formatQuestionText(state);
+  const reply_markup = askFlow.buildKeyboard(state);
+  if (state.messageId) {
+    try {
+      await self._editKeyboard({
+        chat_id: state.chatId,
+        message_id: state.messageId,
+        reply_markup: { inline_keyboard: [] },
+      });
+    } catch { /* best-effort */ }
+  }
+  const sent = await self._send({ chat_id: state.chatId, text, reply_markup, parse_mode: "Markdown" });
+  state.messageId = sent?.message_id || null;
+  askFlow.saveState(state.chatId, state);
+}
+
+/**
+ * Kick off a brand-new ask flow after the super-agent called ask_questions. The
+ * flow's `resume` callback captures the per-turn context so when the compiled
+ * answer arrives we run another super-agent turn without retyping the inputs.
+ */
+export async function startAskFlow(self, ctx) {
+  const state = askFlow.startFlow({
+    chatId: ctx.chat_id,
+    projectId: ctx.projectId,
+    authorId: ctx.authorId,
+    questions: ctx.questions,
+    resume: async (compiled) => {
+      await runResumedTurn(self, { ...ctx, compiled });
+    },
+  });
+  await renderQuestion(self, state);
+}
+
+/** Apply an inline-keyboard press, then react: redraw, advance, cancel or finish. */
+export async function handleAskCallback(self, callbackQuery) {
+  const chatId = callbackQuery.message?.chat?.id;
+  if (!chatId) return;
+  const result = askFlow.applyCallback(chatId, callbackQuery.data || "");
+  // Ack the press regardless — keeps the spinner from hanging client-side.
+  await self._answerCallback({ callback_query_id: callbackQuery.id });
+  if (!result) return; // stale or unknown — adapter already ack'd.
+
+  if (result.action === "redraw") {
+    // Multi-select toggle: refresh the keyboard on the SAME message.
+    try {
+      await self._editKeyboard({
+        chat_id: chatId,
+        message_id: callbackQuery.message?.message_id,
+        reply_markup: askFlow.buildKeyboard(result.state),
+      });
+    } catch (e) {
+      self.log(`telegram[${self.channel.name}] redraw failed: ${e.message}`);
+    }
+    return;
+  }
+  if (result.action === "advance") {
+    await renderQuestion(self, result.state);
+    return;
+  }
+  if (result.action === "cancel") {
+    try {
+      await self._editKeyboard({
+        chat_id: chatId,
+        message_id: callbackQuery.message?.message_id,
+        reply_markup: { inline_keyboard: [] },
+      });
+      await self._send({ chat_id: chatId, text: "Pregunta cancelada." });
+    } catch { /* best-effort */ }
+    return;
+  }
+  if (result.action === "done") {
+    try {
+      await self._editKeyboard({
+        chat_id: chatId,
+        message_id: callbackQuery.message?.message_id,
+        reply_markup: { inline_keyboard: [] },
+      });
+    } catch { /* best-effort */ }
+    // Feed the compiled answer back as a synthetic user turn.
+    if (typeof result.state.resume === "function") {
+      await result.state.resume(result.compiled);
+    }
+  }
+}
+
+/**
+ * Apply a free-text user reply when there's a pending free-text question.
+ * Returns true iff the message was consumed by the ask flow (so the normal
+ * super-agent path should be skipped for this update).
+ */
+export async function maybeConsumeAskTextAnswer(self, { chat_id, text }) {
+  if (!chat_id || !text) return false;
+  if (!askFlow.hasPendingFreeText(chat_id)) return false;
+  const state = askFlow.applyTextAnswer(chat_id, text);
+  if (!state) return false;
+  // Advance: emit a synthetic "next" to move past this question.
+  const next = askFlow.applyCallback(chat_id, `apx:ask:${state.correlationId}:next`);
+  if (!next) return true;
+  if (next.action === "advance") {
+    await renderQuestion(self, next.state);
+    return true;
+  }
+  if (next.action === "done") {
+    if (typeof next.state.resume === "function") {
+      await next.state.resume(next.compiled);
+    }
+    return true;
+  }
+  return true;
+}
+
+/**
+ * Run a follow-up super-agent turn with the compiled answers as the user prompt.
+ * Shares the exact reply path as a normal inbound turn (./reply.js) — only the
+ * photo/audio/reset preamble is skipped. Re-enters the ask flow if the model
+ * decides to ask again.
+ */
+export async function runResumedTurn(self, ctx) {
+  const { chat_id, compiled, target, relationshipBlock, allowedTools, author, agentDisplay, update_id, sender, authorId } = ctx;
+  if (!chat_id) return;
+  // Log the synthetic user message so getRecentTelegramTurnsFromFs picks it up
+  // on the NEXT inbound. Mirrors how a normal text reply would be recorded.
+  appendGlobalMessage({
+    channel: CHANNELS.TELEGRAM,
+    direction: "in",
+    type: "user",
+    actor_id: authorId ? String(authorId) : (author || "ask_flow"),
+    external_id: `ask-${Date.now()}`,
+    author: author || "user",
+    body: compiled,
+    meta: { chat_id, user_id: authorId || null, tg_channel: self.channel.name, ask_flow: 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: compiled,
+      previousMessages,
+      target,
+      author,
+      relationshipBlock,
+      allowedTools,
+      onEvent,
+    });
+
+    // Did the model ask again? Restart the flow instead of replying.
+    const followupAsk = askFlow.extractAskQuestionsFromTrace(sa.trace);
+    if (followupAsk) {
+      stopTyping();
+      await startAskFlow(self, {
+        chat_id,
+        projectId: target?.id,
+        authorId,
+        questions: followupAsk,
+        author,
+        agentDisplay,
+        relationshipBlock,
+        allowedTools,
+        target,
+        sender,
+        update_id,
+      });
+      return;
+    }
+    replyText = sa.text;
+    replyAuthor = sa.name || agentDisplay;
+    saUsage = sa.usage;
+  } catch (e) {
+    self.log(`telegram[${self.channel.name}] ask resume 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: { ask_resume: true },
+  });
+}