@agentprojectcontext/apx 1.78.0 → 1.79.0

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

@@ -12,6 +12,7 @@ import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pend
 import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
 import { CHANNELS } from "#core/constants/channels.js";
 import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
+import { applyNudgeCallback } from "#core/nudge/index.js";
 
 /**
  * Route an inbound callback_query. ask_questions button presses are handled
@@ -24,6 +25,10 @@ export async function handleCallbackQuery(self, callbackQuery) {
     await handleAskCallback(self, callbackQuery);
     return;
   }
+  if (data.startsWith("apx:nudge:")) {
+    await handleNudgeCallback(self, callbackQuery);
+    return;
+  }
   const adapter = createTelegramConfirmAdapter({
     token: resolveBotToken(self.channel),
     chatId: callbackQuery.message?.chat?.id,
@@ -35,6 +40,33 @@ export async function handleCallbackQuery(self, callbackQuery) {
   }
 }
 
+/**
+ * "Was that worth interrupting you for?" — the feedback loop on proactive
+ * pushes (core/nudge). One tap, no reply, and the keyboard disappears so the
+ * chat does not accumulate stale buttons. Never re-enters the super-agent: an
+ * opinion about a message is not a new turn to answer.
+ */
+export async function handleNudgeCallback(self, callbackQuery) {
+  const chatId = callbackQuery.message?.chat?.id;
+  const result = applyNudgeCallback(callbackQuery.data || "");
+  await self._answerCallback({
+    callback_query_id: callbackQuery.id,
+    text: result?.ack || "",
+  });
+  if (!result || !chatId) return;
+  try {
+    await self._editKeyboard({
+      chat_id: chatId,
+      message_id: callbackQuery.message?.message_id,
+      reply_markup: { inline_keyboard: [] },
+    });
+  } catch { /* best-effort */ }
+  self.log(
+    `telegram[${self.channel.name}] nudge feedback: ${result.entry?.kind || "?"} → ` +
+    `${result.entry?.feedback?.useful ? "useful" : "noise"}`
+  );
+}
+
 /**
  * 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.
@@ -182,6 +214,7 @@ export async function runResumedTurn(self, ctx) {
   let replyAuthor;
   let saUsage = null;
   let saModel = null;
+  let saTrace = null;
   try {
     const sa = await runTelegramSuperAgent(self, {
       chat_id,
@@ -218,6 +251,7 @@ export async function runResumedTurn(self, ctx) {
     replyAuthor = sa.name || agentDisplay;
     saUsage = sa.usage;
     saModel = sa.model || state.model || null;
+    saTrace = sa.trace || null;
   } catch (e) {
     self.log(`telegram[${self.channel.name}] ask resume failed: ${e.message}`);
     replyText = telegramErrorText(self, e);
@@ -235,6 +269,7 @@ export async function runResumedTurn(self, ctx) {
     replyKind: "superagent",
     saUsage,
     saModel,
+    saTrace,
     streamedCount: state.streamedCount,
     lastStreamedText: state.lastStreamedText,
     agentDisplay,

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

@@ -228,6 +228,7 @@ export async function handleUpdate(self, u) {
     let replyKind = "superagent";             // actor_kind: superagent | agent
     let replyModel = null;                    // model that actually produced the reply
     let replyUsage = null;                    // token accounting for this turn
+    let replyTrace = null;                    // what the turn actually did (summarised on the message)
     const projectCfg = target.config || self.globalConfig;
     // Display name for the super-agent persona on this channel (from identity.json).
     const agentDisplay = resolveAgentName(self.globalConfig);
@@ -335,6 +336,7 @@ export async function handleUpdate(self, u) {
         replyActorId = SUPERAGENT_ACTOR_ID;
         replyKind = "superagent";
         replyUsage = sa.usage;
+        replyTrace = sa.trace || null;
         replyModel = sa.model || state.model || null;
 
         // ── ask_questions integration ────────────────────────────────────
@@ -397,6 +399,7 @@ export async function handleUpdate(self, u) {
       replyKind,
       saUsage: replyUsage,
       saModel: replyModel,
+      saTrace: replyTrace,
       streamedCount,
       lastStreamedText,
       agentDisplay,

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

@@ -7,9 +7,10 @@
 // of truth fixes that for good.
 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 { stripThinking, stripReasoning } from "#core/util/thinking.js";
 import { appendGlobalMessage, getRecentTelegramTurnsFromFs } from "#core/stores/messages.js";
 import { CHANNELS } from "#core/constants/channels.js";
+import { summarizeToolTrace } from "#core/agent/tool-summary.js";
 import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
 import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
 import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
@@ -54,7 +55,9 @@ export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
         return;
       }
       if (ev.type === "assistant_text" && ev.text) {
-        const piece = stripThinking(ev.text).trim();
+        // Untagged planning is suppressed mid-stream too, or the user
+        // watches the model think in real time.
+        const piece = stripReasoning(ev.text).answer.trim();
         if (!piece) return;
         await self._send({ chat_id, text: piece });
         state.lastStreamedText = piece;
@@ -183,6 +186,7 @@ export async function runFollowupTurn(self, {
     let replyAuthor;
     let saUsage = null;
     let saModel = null;
+    let saTrace = null;
     try {
       const sa = await runTelegramSuperAgent(self, {
         chat_id,
@@ -200,6 +204,7 @@ export async function runFollowupTurn(self, {
       replyAuthor = sa.name || agentDisplay;
       saUsage = sa.usage;
       saModel = sa.model || state.model || null;
+      saTrace = sa.trace || null;
     } catch (e) {
       self.log(`telegram[${self.channel.name}] a2a followup failed: ${e.message}`);
       replyText = telegramErrorText(self, e);
@@ -216,6 +221,7 @@ export async function runFollowupTurn(self, {
       replyKind: "superagent",
       saUsage,
       saModel,
+      saTrace,
       streamedCount: state.streamedCount,
       lastStreamedText: state.lastStreamedText,
       agentDisplay,
@@ -244,10 +250,22 @@ export function telegramErrorText(self, e) {
  */
 export async function sendFinalReply(self, {
   chat_id, update_id, replyText, replyAuthor, replyActorId, replyKind,
-  saUsage = null, saModel = null, streamedCount = 0, lastStreamedText = "", agentDisplay,
-  extraMeta = {},
+  saUsage = null, saModel = null, saTrace = null, streamedCount = 0, lastStreamedText = "",
+  agentDisplay, extraMeta = {},
 }) {
-  const finalClean = replyText ? stripThinking(replyText).trim() : "";
+  // A model that dumps raw planning must never have it forwarded. When that
+  // happens the answer comes back empty and the existing never-silent fallback
+  // below sends a short line instead — a worse reply, but not the model's notes.
+  const stripped = replyText ? stripReasoning(replyText) : { answer: "", leaked: false };
+  const finalClean = stripped.answer.trim();
+  if (stripped.leaked) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[apx] telegram: suppressed an untagged reasoning dump from ${saModel || "the model"} ` +
+      `(${replyText.length} chars). Check the model chain — a router that returns raw ` +
+      `chain-of-thought is not usable on a user-facing channel.`
+    );
+  }
   let toSend = "";
   if (finalClean && finalClean !== lastStreamedText) {
     toSend = finalClean;
@@ -265,8 +283,15 @@ export async function sendFinalReply(self, {
     await self._send({ chat_id, text: toSend });
     const meta = { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, final: true, ...extraMeta };
     if (replyText && stripThinking(replyText) !== replyText) meta.thinking_stripped = true;
+    if (stripped.leaked) meta.reasoning_leak_suppressed = true;
     if (saUsage) meta.usage = saUsage;
     if (saModel) meta.model = saModel;
+    // A COMPACT summary, not the trace: the full one carries args and results
+    // and would bloat the day-file for a detail nobody reads back. What is
+    // worth recovering later is "it read three files and sent a message", and
+    // whether any of it failed.
+    const toolSummary = summarizeToolTrace(saTrace);
+    if (toolSummary) meta.tool_summary = toolSummary;
     appendGlobalMessage({
       channel: CHANNELS.TELEGRAM,
       direction: "out",

package/src/core/config/paths.js

@@ -55,6 +55,9 @@ export const SKILLS_INDEX_PATH = path.join(SKILLS_DIR, ".index.json");
 /** Agent vault — reusable agent definitions, not tied to one project. */
 export const AGENT_VAULT_DIR = path.join(APX_HOME, "agents");
 
+/** Ledger of unrequested outbound messages and the user's feedback on them. */
+export const NUDGES_PATH = path.join(APX_HOME, "nudges.json");
+
 /** Unified log tree. Everything writes here so one tail follows the system. */
 export const LOG_DIR = path.join(APX_HOME, "logs");
 export const APX_LOG_PATH = path.join(LOG_DIR, "apx.log");

package/src/core/config/redact.js

@@ -25,6 +25,11 @@ export const SECRET_PATHS = [
   // Telegram bot tokens live inside an array — handled separately in redact()
   // because dotted paths can't address array entries.
   "telegram.channels.*.bot_token",
+  // Same problem: engines.gemini.api_keys is a LIST of spare keys (quota
+  // rotation). A dotted path cannot reach into it, so redact() handles it
+  // below. Listed here so the "which keys are secrets" question still has one
+  // answer to read.
+  "engines.gemini.api_keys.*",
 ];
 
 /** Replace a secret string with the visible marker, preserving the last 5 chars. */
@@ -64,6 +69,12 @@ export function redactConfig(cfg) {
       }
     }
   }
+  // Spare Gemini keys. Missing this would have served every one of them in
+  // clear text to anyone who opened Settings → Engines.
+  const spareKeys = out?.engines?.gemini?.api_keys;
+  if (Array.isArray(spareKeys)) {
+    out.engines.gemini.api_keys = spareKeys.map(mark);
+  }
   return out;
 }
 
@@ -108,6 +119,17 @@ export function mergeRedactedSecrets(next, prior) {
   if (Array.isArray(nextChannels)) {
     next.telegram.channels = mergeRedactedChannels(nextChannels, prior?.telegram?.channels);
   }
+  // Spare Gemini keys. Without this, opening Settings → Engines and pressing
+  // Save would write the redaction MARKERS over the real keys and silently
+  // empty the rotation pool. Matched by position, which is the only identity
+  // an entry in this list has.
+  const nextSpare = next?.engines?.gemini?.api_keys;
+  if (Array.isArray(nextSpare)) {
+    const priorSpare = Array.isArray(prior?.engines?.gemini?.api_keys)
+      ? prior.engines.gemini.api_keys : [];
+    next.engines.gemini.api_keys = nextSpare.map((v, i) =>
+      isSecretMarker(v) && typeof priorSpare[i] === "string" && priorSpare[i] ? priorSpare[i] : v);
+  }
   return next;
 }
 

package/src/core/daemon/service.js

@@ -0,0 +1,238 @@
+// Run the daemon as a real, self-healing service.
+//
+// Today the daemon starts transitively — some CLI command calls ensureDaemon()
+// and one appears. If it dies at 3am nothing brings it back, so the routines
+// that were meant to run at 8:30 do not, and nobody finds out until they
+// wonder why the morning message never arrived. A scheduler you cannot rely on
+// to be running is not a scheduler.
+//
+// Per-user, never sudo, fully reversible. Same shape as core/desktop/autostart.js,
+// which this deliberately mirrors rather than reinvents:
+//
+//   macOS  → ~/Library/LaunchAgents/dev.apx.daemon.plist   (KeepAlive true)
+//   linux  → ~/.config/systemd/user/apx-daemon.service     (Restart=always)
+//   win32  → HKCU\…\Run\APXDaemon                          (see the caveat below)
+//
+// OPT-IN, always. Installing a system service without being asked is the kind
+// of thing that makes people uninstall software, and APX works perfectly well
+// without it.
+//
+// Functions return { ok, … } and never throw or exit, so the CLI and the HTTP
+// layer can both render the result.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { LOG_DIR } from "#core/config/paths.js";
+import { augmentedPath } from "#core/util/path-env.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const SERVICE_LABEL = "dev.apx.daemon";
+export const MAC_PLIST_PATH = path.join(os.homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+export const LINUX_UNIT_PATH = path.join(os.homedir(), ".config", "systemd", "user", "apx-daemon.service");
+export const WIN_RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+export const WIN_RUN_NAME = "APXDaemon";
+
+export const SERVICE_LOG_PATH = path.join(LOG_DIR, "daemon-service.log");
+
+/**
+ * [bin, ...args] the supervisor should run.
+ *
+ * TWO things this must NOT be, both of which look right and are not:
+ *
+ * 1. The `apx` shim. npm/pnpm shims are shell scripts that `exec node`, and a
+ *    launchd/systemd environment has a minimal PATH with no nvm and often no
+ *    /usr/local/bin, so they fail at boot with "node: not found". That exact
+ *    mistake already cost a day of silent voice failures.
+ *
+ * 2. `apx daemon start`. That command SPAWNS THE DAEMON DETACHED AND EXITS
+ *    (cli/http.js autoStart). Under KeepAlive the supervisor would see its
+ *    child exit within a second, restart it, and loop forever — spawning a new
+ *    daemon each time and never noticing the one already running. A supervised
+ *    process must be the daemon itself, in the foreground.
+ */
+export function getDaemonRunner() {
+  const entry = path.resolve(__dirname, "..", "..", "host", "daemon", "index.js");
+  return [process.execPath, entry];
+}
+
+function escapeXml(s) {
+  return String(s).replace(/[<>&'"]/g, (c) =>
+    ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", "'": "&apos;", '"': "&quot;" }[c]));
+}
+
+/**
+ * launchd plist with KeepAlive TRUE — the whole point. The desktop's plist sets
+ * it false because a window the user closed should stay closed; a daemon that
+ * exits should come back.
+ */
+export function buildDaemonPlist(runner = getDaemonRunner(), logFile = SERVICE_LOG_PATH) {
+  const args = [...runner];
+  const argsXml = args.map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argsXml}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${escapeXml(augmentedPath())}</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${escapeXml(logFile)}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+/** systemd --user unit. `default.target`, not `multi-user.target`: this is a
+ *  per-user service that should start with the user's session, not at boot. */
+export function buildSystemdUnit(runner = getDaemonRunner()) {
+  const exec = [...runner]
+    .map((a) => (/\s/.test(a) ? `"${a}"` : a))
+    .join(" ");
+  return `[Unit]
+Description=APX daemon
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+Environment=PATH=${augmentedPath()}
+Restart=always
+RestartSec=10
+# Give up only if it is crash-looping, so a genuinely broken install does not
+# spin forever writing to the log.
+StartLimitBurst=5
+StartLimitIntervalSec=120
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** @returns {{installed: boolean, path?: string, platform: string, supervised: boolean, note?: string}} */
+export function serviceStatus(platform = process.platform) {
+  if (platform === "darwin") {
+    return {
+      platform, supervised: true, installed: fs.existsSync(MAC_PLIST_PATH),
+      path: MAC_PLIST_PATH,
+    };
+  }
+  if (platform === "linux") {
+    return {
+      platform, supervised: true, installed: fs.existsSync(LINUX_UNIT_PATH),
+      path: LINUX_UNIT_PATH,
+    };
+  }
+  if (platform === "win32") {
+    let installed = false;
+    try {
+      const out = execFileSync("reg", ["query", WIN_RUN_KEY, "/v", WIN_RUN_NAME], {
+        stdio: ["ignore", "pipe", "ignore"],
+      }).toString();
+      installed = new RegExp(WIN_RUN_NAME).test(out);
+    } catch { /* not present */ }
+    return {
+      platform, installed, supervised: false,
+      path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}`,
+      // Said plainly rather than implied. A Run key starts the daemon at login
+      // and does NOT restart it if it dies — which is most of what a service is
+      // for. Promising self-healing here would be a lie the user only discovers
+      // the morning nothing ran.
+      note: "starts at login, but does NOT restart the daemon if it dies — " +
+            "Windows needs a real service wrapper (nssm/sc.exe) for that, which APX does not ship yet",
+    };
+  }
+  return { platform, installed: false, supervised: false, note: `not supported on ${platform}` };
+}
+
+export function installService(platform = process.platform) {
+  const runner = getDaemonRunner();
+
+  if (platform === "darwin") {
+    try {
+      fs.mkdirSync(path.dirname(MAC_PLIST_PATH), { recursive: true });
+      fs.mkdirSync(LOG_DIR, { recursive: true });
+      fs.writeFileSync(MAC_PLIST_PATH, buildDaemonPlist(runner), "utf8");
+      try { execFileSync("launchctl", ["unload", MAC_PLIST_PATH], { stdio: "ignore" }); } catch { /* not loaded */ }
+      execFileSync("launchctl", ["load", "-w", MAC_PLIST_PATH], { stdio: "ignore" });
+      return { ok: true, path: MAC_PLIST_PATH, supervised: true, log: SERVICE_LOG_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "linux") {
+    try {
+      fs.mkdirSync(path.dirname(LINUX_UNIT_PATH), { recursive: true });
+      fs.writeFileSync(LINUX_UNIT_PATH, buildSystemdUnit(runner), "utf8");
+      execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+      execFileSync("systemctl", ["--user", "enable", "--now", "apx-daemon.service"], { stdio: "ignore" });
+      return {
+        ok: true, path: LINUX_UNIT_PATH, supervised: true,
+        // Without lingering, systemd --user stops when the last session ends,
+        // so a headless box would silently lose the daemon on logout.
+        note: "for a machine you are not logged into, run: loginctl enable-linger $USER",
+      };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "win32") {
+    const cmdline = [...runner]
+      .map((s) => `"${String(s).replace(/"/g, '\\"')}"`).join(" ");
+    try {
+      execFileSync("reg", ["add", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/t", "REG_SZ", "/d", cmdline, "/f"],
+        { stdio: "ignore" });
+      return {
+        ok: true, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}`, supervised: false,
+        note: serviceStatus("win32").note,
+      };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  return { ok: false, error: `service installation not supported on platform: ${platform}` };
+}
+
+/** Idempotent: uninstalling something that was never installed is not an error. */
+export function uninstallService(platform = process.platform) {
+  if (platform === "darwin") {
+    if (!fs.existsSync(MAC_PLIST_PATH)) return { ok: true, removed: false };
+    try {
+      try { execFileSync("launchctl", ["unload", "-w", MAC_PLIST_PATH], { stdio: "ignore" }); } catch { /* not loaded */ }
+      fs.unlinkSync(MAC_PLIST_PATH);
+      return { ok: true, removed: true, path: MAC_PLIST_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "linux") {
+    if (!fs.existsSync(LINUX_UNIT_PATH)) return { ok: true, removed: false };
+    try {
+      try {
+        execFileSync("systemctl", ["--user", "disable", "--now", "apx-daemon.service"], { stdio: "ignore" });
+      } catch { /* already stopped */ }
+      fs.unlinkSync(LINUX_UNIT_PATH);
+      try { execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" }); } catch { /* best effort */ }
+      return { ok: true, removed: true, path: LINUX_UNIT_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "win32") {
+    try {
+      execFileSync("reg", ["delete", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/f"], { stdio: "ignore" });
+      return { ok: true, removed: true, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}` };
+    } catch {
+      return { ok: true, removed: false };
+    }
+  }
+
+  return { ok: false, error: `service removal not supported on platform: ${platform}` };
+}