@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/core/http-tools/search.js

@@ -3,7 +3,7 @@
 //   2. Brave Search API (requires BRAVE_API_KEY env)
 //   3. Puppeteer Google fallback (requires puppeteer installed)
 //
-// Endpoint: POST /tools/search
+// Endpoint: POST /api/tools/search
 // Body: { query, mode: "auto"|"ddg"|"brave"|"browser", limit? }
 
 import { browser_navigate, browser_get_text, browser_evaluate } from "./browser.js";
@@ -302,7 +302,7 @@ export function buildSearchRouter(express) {
     }
   });
 
-  // GET convenience: /tools/search?q=...&mode=auto&limit=5
+  // GET convenience: /api/tools/search?q=...&mode=auto&limit=5
   router.get("/", async (req, res) => {
     const { q, query, mode, limit } = req.query;
     try {

package/src/core/identity/self.js

@@ -1,23 +1,22 @@
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
+import { IDENTITY_PATH } from "../config/paths.js";
+
+export { IDENTITY_PATH };
 import { SUPERAGENT_ACTOR_ID } from "../constants/actors.js";
+import { readJson } from "#core/util/json-file.js";
 
 // Re-export so callers that already imported the actor id from here keep
 // working. The single source of truth lives in core/constants/actors.js.
 export { SUPERAGENT_ACTOR_ID };
 
-export const IDENTITY_PATH = path.join(os.homedir(), ".apx", "identity.json");
+
 
 // Shown when no persona is configured yet. Brand of the app, not a persona.
 export const SUPERAGENT_DISPLAY_FALLBACK = "APX";
 
 export function readIdentity() {
-  try {
-    return JSON.parse(fs.readFileSync(IDENTITY_PATH, "utf8"));
-  } catch {
-    return null;
-  }
+  return readJson(IDENTITY_PATH, null);
 }
 
 // Resolve the super-agent's DISPLAY name (the persona shown to users). Order:

package/src/core/identity/telegram.js

@@ -37,7 +37,7 @@ export function resolveSender({ cfg, channelName, from, chatType }) {
   const isOwner =
     channel?.owner_user_id != null &&
     String(channel.owner_user_id) === String(userId);
-  const role = isOwner ? "owner" : contact?.role || "guest";
+  const role = isOwner ? SENDER_ROLES.OWNER : contact?.role || SENDER_ROLES.GUEST;
   return {
     userId,
     username,
@@ -115,11 +115,11 @@ export function registerSender({ cfg, channelName, from, chatType }) {
   if (kind === "claim") {
     upsertTelegramChannel(disk, channelName, { owner_user_id: userId });
     upsertContact(disk, userId, {
-      name, username, role: "owner", first_seen: now, last_seen: now,
+      name, username, role: SENDER_ROLES.OWNER, first_seen: now, last_seen: now,
     });
   } else if (kind === "guest") {
     upsertContact(disk, userId, {
-      name, username, role: "guest", first_seen: now, last_seen: now,
+      name, username, role: SENDER_ROLES.GUEST, first_seen: now, last_seen: now,
     });
   } else {
     upsertContact(disk, userId, { last_seen: now });

package/src/core/logging.js

@@ -1,14 +1,15 @@
 import fs from "node:fs";
-import path from "node:path";
-import { APX_HOME } from "./config/index.js";
 import { maskSecretValues } from "./config/secret-values.js";
+import { LOG_DIR, APX_LOG_PATH, ERROR_TRACE_PATH } from "./config/paths.js";
+
+// Canonical definitions live in config/paths.js; re-exported so the existing
+// `import { APX_LOG_PATH } from "#core/logging.js"` call sites keep working.
+export { LOG_DIR, APX_LOG_PATH, ERROR_TRACE_PATH };
 
-export const LOG_DIR = path.join(APX_HOME, "logs");
-export const ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
 // Unified daemon log. Every module (daemon, telegram, whisper, super-agent,
 // tools, desktop) writes here with one consistent format so the user can
 // follow the whole system from a single tail.
-export const APX_LOG_PATH = path.join(LOG_DIR, "apx.log");
+
 
 const SECRET_KEY_RE = /(token|secret|password|api[_-]?key|authorization|bot[_-]?token)/i;
 

package/src/core/mcp/sources.js

@@ -34,12 +34,14 @@
 // instead, then to true.
 
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { apxHome } from "#core/config/paths.js";
 import { apcMcpsFile } from "#core/apc/paths.js";
+import { readJson } from "#core/util/json-file.js";
 
-const APX_HOME = path.join(os.homedir(), ".apx");
-const GLOBAL_MCPS_FILE = path.join(APX_HOME, "mcps.json");
+
+// Resolved per call: the global store must follow APX_HOME if it moves.
+const globalMcpsFile = () => path.join(apxHome(), "mcps.json");
 const RUNTIME_MCPS_FILENAME = "mcps.json";
 
 // Project-relative sources (file path resolved against projectRoot).
@@ -63,15 +65,9 @@ export const SOURCES = [
   { id: "global",  file: "~/.apx/mcps.json", key: "mcpServers", scope: "global" },
 ];
 
-function readJsonSafe(absPath) {
-  if (!absPath) return null;
-  if (!fs.existsSync(absPath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(absPath, "utf8"));
-  } catch {
-    return null;
-  }
-}
+// readJsonSafe is the shared readJson(); secrets are written with SECRET_MODE.
+const readJsonSafe = (absPath) => readJson(absPath, null);
+
 
 // Resolve the runtime mcps.json path for a given project. `storagePath` is the
 // project's ~/.apx/projects/<apxId>/ directory.
@@ -81,7 +77,7 @@ export function runtimeMcpsPath(storagePath) {
 }
 
 export function globalMcpsPath() {
-  return GLOBAL_MCPS_FILE;
+  return globalMcpsFile();
 }
 
 // Aggregate all MCP sources for a project, in priority order.
@@ -119,7 +115,7 @@ export function loadAll(projectRoot, opts = {}) {
   // last. global
   pipeline.push({
     id: "global",
-    abs: GLOBAL_MCPS_FILE,
+    abs: globalMcpsFile(),
     key: "mcpServers",
   });
 
@@ -229,7 +225,7 @@ export function writeRuntimeMcps(storagePath, json) {
 // ---------------------------------------------------------------------------
 
 export function readGlobalMcps() {
-  const p = GLOBAL_MCPS_FILE;
+  const p = globalMcpsFile();
   if (!fs.existsSync(p)) return { mcpServers: {} };
   try {
     const json = JSON.parse(fs.readFileSync(p, "utf8"));
@@ -241,7 +237,7 @@ export function readGlobalMcps() {
 }
 
 export function writeGlobalMcps(json) {
-  const p = GLOBAL_MCPS_FILE;
+  const p = globalMcpsFile();
   fs.mkdirSync(path.dirname(p), { recursive: true });
   fs.writeFileSync(p, JSON.stringify(json, null, 2) + "\n");
 }

package/src/core/memory/consolidate.js

@@ -0,0 +1,225 @@
+// Post-session memory consolidation.
+//
+// THE GAP THIS CLOSES: self-memory.js has always claimed the notebook is
+// "refreshed by skimming its own recent sessions". That function did not
+// exist. Today a durable fact only reaches ~/.apx/memory.md if the model
+// happens to call `remember` in the moment. The RAG index and the compactor
+// are automatic, but those are RETRIEVAL, not learning.
+//
+// THE DANGER, which is bigger than the gap: memory.md is injected into every
+// prompt on every channel. A notebook that grows without judgement is a
+// permanent tax paid on every turn for facts nobody needed. So the whole
+// design here leans one way — when in doubt, do not save.
+//
+// Three deliberate constraints:
+//
+//   1. CANDIDATES, NOT WRITES, by default. `apx memory consolidate` proposes;
+//      writing is a separate, explicit step. A background job that silently
+//      edits the file the agent believes about itself is not something to
+//      switch on by default.
+//   2. DEDUP AGAINST WHAT IS ALREADY THERE. The same fact learned three times
+//      is one fact.
+//   3. EVERY WRITE IS TAGGED AND REVERSIBLE. Consolidated bullets carry a
+//      marker so `revert` can remove exactly what a run added and nothing the
+//      user or the model wrote by hand.
+import { readSelfMemory, appendSelfMemory, parseSelfMemoryEntries, SELF_MEMORY_PATH } from "#core/agent/self-memory.js";
+import fs from "node:fs";
+
+/** Marks a bullet as machine-distilled, so a revert can find its own writes. */
+export const CONSOLIDATED_CHANNEL = "consolidated";
+
+/** Conservative by design — see the header. */
+export const DEFAULT_LIMITS = Object.freeze({
+  /** Never propose more than this from one run. A day is not a biography. */
+  max_candidates: 5,
+  /** Below this, a line is chatter, not a fact. */
+  min_chars: 20,
+  /** Above this it is a paragraph; the notebook holds one-liners. */
+  max_chars: 240,
+  /**
+   * Jaccard overlap at which two facts are "the same fact".
+   *
+   * Set low on purpose. The two errors here are not symmetric: calling a new
+   * fact a duplicate costs one thing not saved, which the model can say again
+   * tomorrow. Calling a duplicate new costs a permanent second copy in a file
+   * that ships on every turn of every channel. So it errs toward dedup — real
+   * paraphrases ("instead of npm" / "rather than npm") land around 0.55.
+   */
+  dedup_threshold: 0.5,
+});
+
+/**
+ * Openers that mark a durable fact about how someone works or what they
+ * decided, as opposed to a transient exchange. Matching on shape rather than
+ * meaning keeps this deterministic and testable — the model does the
+ * distilling upstream; this decides what is worth keeping.
+ */
+const DURABLE_MARKERS = [
+  /\b(prefer|prefers|prefiere|prefiero)\b/i,
+  /\b(decided|decidimos|decidí|decision)\b/i,
+  /\b(always|never|siempre|nunca)\b/i,
+  /\b(uses?|usa|usamos)\b.*\b(instead of|en vez de)\b/i,
+  /\b(works? (?:on|at)|trabaja en)\b/i,
+  /\b(deadline|vence|due)\b/i,
+  /\b(rule|regla|convention|convención)\b/i,
+];
+
+/** Things that look like facts but age out within a day. */
+const TRANSIENT_MARKERS = [
+  /\b(today|hoy|right now|ahora mismo|esta mañana|this morning)\b/i,
+  /\b(will (?:check|look)|voy a (?:ver|revisar))\b/i,
+  /^\s*(ok|okay|dale|listo|thanks|gracias|perfecto)\b/i,
+];
+
+/** Words that carry meaning, lowercased, for overlap comparison. */
+function tokenise(text) {
+  return new Set(
+    String(text || "")
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N}\s]/gu, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 3),
+  );
+}
+
+/** Jaccard overlap. 1 = identical vocabulary, 0 = nothing in common. */
+export function similarity(a, b) {
+  const A = tokenise(a);
+  const B = tokenise(b);
+  if (!A.size || !B.size) return 0;
+  let shared = 0;
+  for (const w of A) if (B.has(w)) shared += 1;
+  return shared / (A.size + B.size - shared);
+}
+
+/** Is this line worth keeping past today? */
+export function looksDurable(text, limits = DEFAULT_LIMITS) {
+  const s = String(text || "").trim();
+  if (s.length < limits.min_chars || s.length > limits.max_chars) return false;
+  if (TRANSIENT_MARKERS.some((re) => re.test(s))) return false;
+  return DURABLE_MARKERS.some((re) => re.test(s));
+}
+
+/**
+ * Propose durable facts from a batch of candidate lines.
+ *
+ * The caller supplies the lines — from a model's distillation of a session, or
+ * from anywhere else. This module owns the JUDGEMENT about what survives, so
+ * the same rules apply no matter who is proposing.
+ *
+ * @param {string[]} candidates
+ * @param {object} opts  { existing?: string, limits?, now? }
+ * @returns {{ kept: string[], rejected: {text: string, reason: string}[] }}
+ */
+export function proposeConsolidation(candidates, opts = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...(opts.limits || {}) };
+  const existingText = opts.existing !== undefined ? opts.existing : readSelfMemory();
+  const known = parseSelfMemoryEntries(existingText).map((e) => e.text);
+
+  const kept = [];
+  const rejected = [];
+
+  for (const raw of candidates || []) {
+    const text = String(raw || "").replace(/\s+/g, " ").trim();
+    if (!text) continue;
+
+    if (kept.length >= limits.max_candidates) {
+      rejected.push({ text, reason: "over the per-run limit" });
+      continue;
+    }
+    if (!looksDurable(text, limits)) {
+      rejected.push({ text, reason: "not durable" });
+      continue;
+    }
+
+    // Against what is already saved AND against what this run already kept —
+    // a session that says the same thing twice must not save it twice.
+    const clash = [...known, ...kept].find((k) => similarity(k, text) >= limits.dedup_threshold);
+    if (clash) {
+      rejected.push({ text, reason: `already known: "${clash.slice(0, 60)}"` });
+      continue;
+    }
+
+    kept.push(text);
+  }
+
+  return { kept, rejected };
+}
+
+/**
+ * Write accepted facts to the notebook, tagged so they can be reverted.
+ * Separate from proposing on purpose: the decision to write is the user's.
+ */
+export function applyConsolidation(facts, opts = {}) {
+  const written = [];
+  for (const text of facts || []) {
+    appendSelfMemory(text, { channel: CONSOLIDATED_CHANNEL, ...(opts.time ? { time: opts.time } : {}) });
+    written.push(text);
+  }
+  return { written, path: SELF_MEMORY_PATH };
+}
+
+/**
+ * Undo consolidation: drop bullets this module wrote, leaving everything the
+ * user or the model wrote by hand exactly where it is.
+ *
+ * @param {object} opts  { since?: "YYYY-MM-DD" } — only that day and after.
+ * @returns {{ removed: number, path: string }}
+ */
+export function revertConsolidation(opts = {}) {
+  const text = readSelfMemory();
+  if (!text.trim()) return { removed: 0, path: SELF_MEMORY_PATH };
+
+  const since = opts.since || "";
+  const lines = text.split("\n");
+  const out = [];
+  let day = "";
+  let removed = 0;
+
+  for (const line of lines) {
+    const h = line.trim().match(/^##\s+(\d{4}-\d{2}-\d{2})/);
+    if (h) { day = h[1]; out.push(line); continue; }
+
+    // Only ever removes a bullet carrying OUR channel tag. A hand-written note
+    // that happens to sit next to one is untouched.
+    const isOurs = /^[-*]\s+(?:\[[^\]]+\]\s*)?\[consolidated\]\s/i.test(line.trim());
+    if (isOurs && (!since || day >= since)) {
+      removed += 1;
+      continue;
+    }
+    out.push(line);
+  }
+
+  if (removed) {
+    fs.writeFileSync(SELF_MEMORY_PATH, stripEmptyDays(out).join("\n"));
+  }
+  return { removed, path: SELF_MEMORY_PATH };
+}
+
+/** Drop day headings left with no bullets under them. */
+function stripEmptyDays(lines) {
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const isHeading = /^##\s+\d{4}-\d{2}-\d{2}/.test(lines[i].trim());
+    if (!isHeading) { out.push(lines[i]); continue; }
+    let hasBullet = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^##\s+/.test(lines[j].trim())) break;
+      if (/^[-*]\s+\S/.test(lines[j].trim())) { hasBullet = true; break; }
+    }
+    if (hasBullet) out.push(lines[i]);
+  }
+  return out;
+}
+
+/** How much of the prompt budget the notebook is currently costing. */
+export function notebookSize() {
+  const text = readSelfMemory();
+  const entries = parseSelfMemoryEntries(text);
+  return {
+    chars: text.length,
+    approx_tokens: Math.ceil(text.length / 4),
+    entries: entries.length,
+    consolidated: entries.filter((e) => e.channel === CONSOLIDATED_CHANNEL).length,
+  };
+}

package/src/core/memory/indexer.js

@@ -23,6 +23,7 @@ import { GLOBAL_MESSAGES_DIR, APX_HOME } from "../config/index.js";
 import { SELF_MEMORY_PATH, parseSelfMemoryEntries } from "../agent/self-memory.js";
 import { apcMemoryFile } from "../apc/paths.js";
 import { embedBatch, embedOne } from "./embeddings.js";
+import { readJson } from "#core/util/json-file.js";
 
 export const CURSOR_PATH = path.join(APX_HOME, "memory-cursor.json");
 
@@ -48,11 +49,7 @@ function readIfExists(p) {
 }
 
 function readCursor(cursorPath) {
-  try {
-    return JSON.parse(fs.readFileSync(cursorPath, "utf8"));
-  } catch {
-    return { channels: {} };
-  }
+  return readJson(cursorPath, { channels: {} });
 }
 
 function writeCursor(cursorPath, cursor) {

package/src/core/nudge/index.js

@@ -0,0 +1,192 @@
+// The interruption budget — one gate every unrequested message passes through.
+//
+// THE RULE THAT MATTERS: the gate lives at the CALL SITES that decide to speak
+// unprompted, never inside the channel's `_send`. `_send` also carries the
+// user's own replies, and a budget that can swallow an answer someone is
+// waiting for reads as a hung bot, not as restraint. Each caller states
+// `unsolicited` explicitly, so the intent is visible in the diff rather than
+// inferred from the call stack.
+//
+// The budget is a feature, not a limitation: it is what makes the message get
+// opened when the agent does speak.
+//
+// Shape of a call site:
+//
+//   const gate = canNudge({ kind: "day_open", project_id, severity }, config);
+//   if (!gate.allowed) return;                 // log gate.reason
+//   await send({ ..., reply_markup: nudgeFeedbackKeyboard(gate.nudge_id) });
+//   recordNudge(gate, { chat_id, preview: text });
+import { shortId } from "#core/util/ids.js";
+import { resolveNudgePolicy, isQuietAt, quietEndsAt } from "./policy.js";
+import {
+  readNudgeLedger, appendNudge, setNudgeFeedback, nudgesOnDay, lastNudge,
+} from "./store.js";
+
+export { resolveNudgePolicy, isQuietAt, DEFAULT_POLICY } from "./policy.js";
+export { listNudges, nudgeStats, readNudgeLedger } from "./store.js";
+
+/** Severity that may cross a closed gate, when the policy allows it. */
+const CRITICAL = "critical";
+
+/**
+ * May APX speak right now?
+ *
+ * @param {object}  req
+ * @param {string}  req.kind          what sort of interruption ("day_open", "signal", "session_result", …)
+ * @param {string?} req.project_id    which project it concerns, when it concerns one
+ * @param {string}  req.severity      "low" | "normal" | "high" | "critical"
+ * @param {boolean} req.unsolicited   false for a delivery the user asked for. Be honest here.
+ * @param {boolean} req.scheduled     true when the user themselves put this on the clock (an
+ *                                    anchor routine). Exempt from the ceiling, still recorded.
+ * @param {string}  req.channel
+ * @param {object}  config            parsed ~/.apx/config.json
+ * @param {Date}    now               injectable for tests
+ * @returns {{allowed: boolean, reason: string, retry_after_ms: number|null, nudge_id: string,
+ *            kind: string, project_id: string|null, severity: string, channel: string,
+ *            unsolicited: boolean, bypassed_budget: boolean, policy: object}}
+ */
+export function canNudge(req = {}, config = {}, now = new Date()) {
+  const kind = req.kind || "unknown";
+  const projectId = req.project_id ?? null;
+  const severity = req.severity || "normal";
+  const channel = req.channel || "telegram";
+  const unsolicited = req.unsolicited !== false;
+  const scheduled = req.scheduled === true;
+  const policy = resolveNudgePolicy(config);
+
+  const decision = (allowed, reason, retry_after_ms = null, bypassed_budget = false) => ({
+    allowed, reason, retry_after_ms,
+    nudge_id: shortId("ndg"),
+    kind, project_id: projectId, severity, channel, unsolicited, scheduled, bypassed_budget, policy,
+  });
+
+  // A reply, or a result the user launched and is waiting for. It passes
+  // through so the audit holds and so it lands in the ledger, but it never
+  // spends a budget it did not ask to spend.
+  if (!unsolicited) return decision(true, "solicited");
+
+  if (!policy.enabled) return decision(true, "budget-disabled");
+
+  // An ANCHOR — the morning and evening messages the user themselves put on
+  // the clock. The profile schema calls the daily number "the ceiling OUTSIDE
+  // the anchors", and it means it: a budget of three that two anchors spend
+  // leaves one, which is not what anybody chose. Charging someone's own
+  // schedule against their interruption allowance is the same category of
+  // wrong as gating a reply.
+  //
+  // Quiet hours are skipped too, for the same reason: an anchor scheduled
+  // inside them is a contradiction the USER wrote, and their explicit cron
+  // beats our default window.
+  if (scheduled) return decision(true, "scheduled-by-user");
+
+  const isCritical = severity === CRITICAL;
+  if (isCritical && policy.critical_bypasses_budget) {
+    // Audited, per the spec: it goes in the ledger flagged, so an integration
+    // that discovers "critical" as a way to shout cannot do it quietly.
+    return decision(true, "critical-bypass", null, true);
+  }
+
+  if (isQuietAt(policy.quiet_hours, now)) {
+    const ends = quietEndsAt(policy.quiet_hours, now);
+    return decision(false, `quiet-hours (${policy.quiet_hours})`, ends ? ends - now : null);
+  }
+
+  const ledger = readNudgeLedger();
+
+  if (policy.daily_max > 0) {
+    // Anchors and audited bypasses are recorded but do not consume the
+    // allowance — otherwise the number the user configured is not the number
+    // they get.
+    const today = nudgesOnDay(now, ledger).filter((e) => !e.bypassed_budget && !e.scheduled);
+    if (today.length >= policy.daily_max) {
+      return decision(
+        false,
+        `daily budget spent (${today.length}/${policy.daily_max})`,
+        msUntilTomorrow(now),
+      );
+    }
+  }
+
+  const cooldowns = [
+    [policy.cooldown_minutes, () => true, "global cooldown"],
+    [policy.project_cooldown_minutes, (e) => projectId != null && String(e.project_id) === String(projectId), `cooldown for this project`],
+    [policy.kind_cooldown_minutes, (e) => e.kind === kind, `cooldown for "${kind}"`],
+  ];
+
+  for (const [minutes, match, label] of cooldowns) {
+    if (!minutes) continue;
+    const last = lastNudge(match, ledger);
+    if (!last) continue;
+    const elapsed = now - new Date(last.at);
+    const window = minutes * 60_000;
+    if (Number.isFinite(elapsed) && elapsed < window) {
+      return decision(false, `${label} (${minutes}m)`, window - elapsed);
+    }
+  }
+
+  return decision(true, "within budget");
+}
+
+/**
+ * Record a nudge that was actually delivered. Takes the decision object
+ * `canNudge` returned, so the id in the feedback button and the id in the
+ * ledger are the same one.
+ */
+export function recordNudge(decision, { chat_id = null, preview = "" } = {}) {
+  if (!decision?.allowed) return null;
+  // Solicited traffic is not an interruption and must not fill the ledger the
+  // user reads to answer "how often does this thing bother me".
+  if (decision.unsolicited === false) return null;
+  return appendNudge({
+    id: decision.nudge_id,
+    kind: decision.kind,
+    project_id: decision.project_id,
+    severity: decision.severity,
+    channel: decision.channel,
+    chat_id,
+    preview,
+    bypassed_budget: decision.bypassed_budget,
+    scheduled: decision.scheduled,
+  });
+}
+
+/**
+ * "That wasn't useful." The loop is not optional: initiative that never learns
+ * gets switched off, and the switch is the user muting the bot.
+ */
+export function recordFeedback(nudgeId, useful, note = "") {
+  return setNudgeFeedback(nudgeId, { useful, note });
+}
+
+/** Telegram inline keyboard for a proactive push. Two taps, no typing. */
+export function nudgeFeedbackKeyboard(nudgeId) {
+  if (!nudgeId) return undefined;
+  return {
+    inline_keyboard: [[
+      { text: "👍 Útil", callback_data: `apx:nudge:${nudgeId}:useful` },
+      { text: "👎 No me servía", callback_data: `apx:nudge:${nudgeId}:noise` },
+    ]],
+  };
+}
+
+/**
+ * Handle a press on that keyboard. Returns the acknowledgement text, or null
+ * when the callback belongs to someone else.
+ */
+export function applyNudgeCallback(data) {
+  if (typeof data !== "string" || !data.startsWith("apx:nudge:")) return null;
+  const [nudgeId, verb] = data.slice("apx:nudge:".length).split(":");
+  if (!nudgeId || (verb !== "useful" && verb !== "noise")) return null;
+  const entry = recordFeedback(nudgeId, verb === "useful");
+  if (!entry) return { ack: "Ese mensaje ya no está en el registro.", entry: null };
+  return {
+    ack: verb === "useful" ? "Anotado: te sirvió." : "Anotado: no te servía.",
+    entry,
+  };
+}
+
+function msUntilTomorrow(now) {
+  const t = new Date(now);
+  t.setHours(24, 0, 0, 0);
+  return t - now;
+}