@agentprojectcontext/apx 1.78.0 → 1.79.0

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/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;
+}

package/src/core/nudge/policy.js

@@ -0,0 +1,143 @@
+// How many unrequested messages APX may send, and when.
+//
+// Three layers, lowest precedence first:
+//
+//   1. CORE DEFAULTS — permissive, and `enabled: false`. Vanilla APX delivers
+//      exactly what it delivered before this module existed. Turning a budget
+//      on by default would have silently muted push paths people already rely
+//      on, which is a regression dressed as a feature.
+//   2. THE ACTIVE PROFILE — a profile that declares `nudge_budget_per_day` or
+//      `quiet_hours` is stating a criterion, and switches enforcement ON. This
+//      is the split the whole profile subsystem rests on: core owns the
+//      capability (a gate, a ledger, a feedback loop), the profile owns the
+//      judgement (three a day, quiet after ten).
+//   3. THE USER — `config.nudge` in ~/.apx/config.json, written by the panel or
+//      by hand. Always wins. Someone who sets a number should get that number
+//      whatever profile they install later.
+import { readActiveProfile, effectiveProfileConfig } from "#core/profiles/store.js";
+
+/** Permissive on purpose — see the header. */
+export const DEFAULT_POLICY = Object.freeze({
+  enabled: false,
+  daily_max: 0,               // 0 = no ceiling
+  quiet_hours: "",            // "" = never quiet
+  cooldown_minutes: 0,        // between any two nudges
+  project_cooldown_minutes: 0, // between two nudges about the SAME project
+  kind_cooldown_minutes: 0,   // between two nudges of the SAME kind
+  critical_bypasses_budget: true,
+});
+
+/**
+ * Profile config keys this module understands. Deliberately generic names: a
+ * chief-of-staff profile and a study-tutor profile both mean the same thing by
+ * "how often may you interrupt me". A profile that declares neither key leaves
+ * the gate off.
+ */
+const PROFILE_KEYS = Object.freeze({
+  nudge_budget_per_day: "daily_max",
+  quiet_hours: "quiet_hours",
+  nudge_cooldown_minutes: "cooldown_minutes",
+  nudge_project_cooldown_minutes: "project_cooldown_minutes",
+  nudge_kind_cooldown_minutes: "kind_cooldown_minutes",
+});
+
+/**
+ * Resolve the effective policy for the current config.
+ *
+ * @param {object} config  the parsed ~/.apx/config.json
+ * @returns {typeof DEFAULT_POLICY & { source: string[] }}
+ */
+export function resolveNudgePolicy(config = {}) {
+  const policy = { ...DEFAULT_POLICY };
+  const source = ["defaults"];
+
+  // ── layer 2: the active profile ──────────────────────────────────────────
+  let profileConfig = null;
+  try {
+    const active = readActiveProfile(config);
+    if (active) profileConfig = effectiveProfileConfig(active, config);
+  } catch {
+    // A broken or half-installed profile must not take the gate down with it.
+    profileConfig = null;
+  }
+
+  if (profileConfig) {
+    let touched = false;
+    for (const [profileKey, policyKey] of Object.entries(PROFILE_KEYS)) {
+      const v = profileConfig[profileKey];
+      if (v === undefined || v === null || v === "") continue;
+      policy[policyKey] = v;
+      touched = true;
+    }
+    // Declaring a budget IS opting in. A profile that says "three a day" and
+    // then gets ignored because a separate flag was off is worse than useless.
+    if (touched) {
+      policy.enabled = true;
+      source.push("profile");
+    }
+  }
+
+  // ── layer 3: the user ────────────────────────────────────────────────────
+  const user = config?.nudge;
+  if (user && typeof user === "object") {
+    let touched = false;
+    for (const key of Object.keys(DEFAULT_POLICY)) {
+      if (user[key] === undefined || user[key] === null) continue;
+      policy[key] = user[key];
+      touched = true;
+    }
+    if (touched) source.push("user");
+  }
+
+  policy.daily_max = toNonNegativeInt(policy.daily_max);
+  policy.cooldown_minutes = toNonNegativeInt(policy.cooldown_minutes);
+  policy.project_cooldown_minutes = toNonNegativeInt(policy.project_cooldown_minutes);
+  policy.kind_cooldown_minutes = toNonNegativeInt(policy.kind_cooldown_minutes);
+  policy.enabled = policy.enabled === true;
+  policy.critical_bypasses_budget = policy.critical_bypasses_budget !== false;
+  policy.quiet_hours = typeof policy.quiet_hours === "string" ? policy.quiet_hours.trim() : "";
+
+  return { ...policy, source };
+}
+
+function toNonNegativeInt(v) {
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Parse a "HH:MM-HH:MM" window into minutes-from-midnight.
+ * Returns null when the string is absent or unparseable — an unreadable window
+ * must not accidentally mean "always quiet".
+ */
+export function parseQuietHours(spec) {
+  const m = /^\s*(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})\s*$/.exec(String(spec || ""));
+  if (!m) return null;
+  const [h1, m1, h2, m2] = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (h1 > 23 || h2 > 23 || m1 > 59 || m2 > 59) return null;
+  return { start: h1 * 60 + m1, end: h2 * 60 + m2 };
+}
+
+/**
+ * Is `date` inside the quiet window? Handles windows that cross midnight,
+ * which is the normal case for sleep ("22:00-07:30").
+ */
+export function isQuietAt(spec, date = new Date()) {
+  const w = parseQuietHours(spec);
+  if (!w) return false;
+  const mins = date.getHours() * 60 + date.getMinutes();
+  if (w.start === w.end) return false;               // zero-width window
+  if (w.start < w.end) return mins >= w.start && mins < w.end;
+  return mins >= w.start || mins < w.end;            // crosses midnight
+}
+
+/** When does the current quiet window end? Null when not quiet. */
+export function quietEndsAt(spec, date = new Date()) {
+  if (!isQuietAt(spec, date)) return null;
+  const w = parseQuietHours(spec);
+  const end = new Date(date);
+  end.setSeconds(0, 0);
+  end.setHours(Math.floor(w.end / 60), w.end % 60);
+  if (end <= date) end.setDate(end.getDate() + 1);
+  return end;
+}