@inetafrica/open-claudia 3.0.25 → 3.0.27

package/core/agency/deliberate.js

@@ -0,0 +1,332 @@
+// Agency deliberation — advisory "what should I do next?" (Track B1).
+//
+// Consumes the read-only ledger (core/agency/ledger) and PROPOSES a single best
+// next action with a transparent reason. It acts on nothing — B1 is advisory
+// only; the act/schedule loop is B2+ (gated behind a shadow-mode review).
+//
+// Pipeline: triage (deterministic prefilter cuts the backlog to what could
+// matter now) → rank (explainable algorithmic score) → optional judge (a cheap
+// model disambiguates a close top-N and refines the action type). Default-
+// silence: if nothing clears the confidence floor, it proposes nothing.
+//
+// The judge is injectable and OFF by default, so deliberation is deterministic,
+// network-free, and safe to run repeatedly in shadow mode. When enabled it can
+// never break the proposal — any judge failure falls back to the deterministic
+// pick.
+
+const path = require("path");
+const fs = require("fs");
+const configDir = require(path.join(__dirname, "..", "..", "config-dir"));
+
+const DAY_MS = 86400000;
+const ACTIONS = ["act", "schedule", "ask", "park"];
+
+// Tunables — deliberately conservative so shadow mode stays quiet unless
+// something genuinely warrants attention.
+const CONFIDENCE_FLOOR = 25;   // below this top score → propose nothing
+const CLEAR_MARGIN = 20;       // top beats second by this → skip the judge
+const DUE_SOON_DAYS = 3;
+const CANDIDATE_STALE_DAYS = 30;
+const TOP_N = 5;
+
+// --- shadow log (mirrors core/prompt-budget storage pattern) ------------
+const LOG_FILE = path.join(configDir, "agency-deliberation.jsonl");
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+function shadowEnabled() {
+  const v = String(process.env.AGENCY_SHADOW || "on").toLowerCase();
+  return v !== "off" && v !== "0" && v !== "false";
+}
+
+function toMs(v) {
+  if (!v) return 0;
+  if (typeof v === "number") return v;
+  const t = Date.parse(v);
+  return Number.isFinite(t) ? t : 0;
+}
+
+function daysUntil(due, now) {
+  const dueMs = toMs(due);
+  if (!dueMs) return null;
+  return (dueMs - now) / DAY_MS;
+}
+
+// --- triage: cut the backlog to what could plausibly matter now ---------
+// Notifications are awareness, not work to "pick" — excluded from candidates.
+// An item survives triage if it is overdue, due soon, already in progress,
+// high priority, or a fresh owner assignment. Everything else is background
+// (parked by default) so a 300-item list collapses to a handful.
+function isCandidate(e, now) {
+  if (e.source === "notification") return false;
+  if (e.status === "done") return false;
+  if (e.overdue) return true;
+  const d = daysUntil(e.due, now);
+  if (d != null && d <= DUE_SOON_DAYS) return true;
+  if (e.status === "in_progress") return true;
+  if (e.priority === "high") return true;
+  if (e.source === "spaces" && e.staleDays != null && e.staleDays <= CANDIDATE_STALE_DAYS) return true;
+  return false;
+}
+
+// --- rank: explainable score + the signals that fired -------------------
+function scoreOf(e, now) {
+  const signals = [];
+  let score = 0;
+
+  if (e.overdue) {
+    const over = Math.min(Math.max(0, -(daysUntil(e.due, now) || 0)), 30);
+    score += 100 + over * 2;
+    signals.push({ k: "overdue", w: 100 + over * 2, label: `overdue ${Math.round(over)}d` });
+  } else {
+    const d = daysUntil(e.due, now);
+    if (d != null && d <= DUE_SOON_DAYS) {
+      const w = 60 - Math.max(0, d) * 12;
+      score += w;
+      signals.push({ k: "due-soon", w, label: d < 1 ? "due today" : `due in ${Math.round(d)}d` });
+    } else if (d != null) {
+      const w = Math.max(4, 20 - Math.min(d, 30));
+      score += w;
+      signals.push({ k: "has-due", w, label: `due in ${Math.round(d)}d` });
+    }
+  }
+
+  if (e.status === "in_progress") {
+    score += 30;
+    signals.push({ k: "in-progress", w: 30, label: "already in progress" });
+  }
+  if (e.priority === "high") {
+    score += 25;
+    signals.push({ k: "priority", w: 25, label: "high priority" });
+  } else if (e.priority === "medium") {
+    score += 8;
+    signals.push({ k: "priority", w: 8, label: "medium priority" });
+  }
+
+  // Unblocks others: a plan/task with open subtasks gates that downstream work.
+  const openSubs = (e.meta && typeof e.meta.subtasks === "number")
+    ? Math.max(0, e.meta.subtasks - (e.meta.subtasksDone || 0)) : 0;
+  if (openSubs > 0) {
+    score += 15;
+    signals.push({ k: "unblocks", w: 15, label: `unblocks ${openSubs} subtask${openSubs > 1 ? "s" : ""}` });
+  }
+
+  // Staleness: mild nudge for neglected-but-active work; mild penalty for very
+  // cold items so abandoned cruft doesn't float up on staleness alone.
+  if (e.staleDays != null) {
+    if (e.staleDays > CANDIDATE_STALE_DAYS && !e.overdue) {
+      score -= 10;
+      signals.push({ k: "cold", w: -10, label: `untouched ${Math.round(e.staleDays)}d` });
+    } else if (e.staleDays > 7 && (e.status === "in_progress" || e.overdue)) {
+      score += 6;
+      signals.push({ k: "neglected", w: 6, label: `neglected ${Math.round(e.staleDays)}d` });
+    }
+  }
+
+  if (e.meta && e.meta.space) signals.push({ k: "context", w: 0, label: e.meta.space });
+
+  signals.sort((a, b) => Math.abs(b.w) - Math.abs(a.w));
+  return { score, signals };
+}
+
+// Deterministic action-type guess (the judge can override when enabled).
+function guessAction(e, now) {
+  if (e.source === "spaces") {
+    // Assigned work: if it's overdue/soon it likely needs a nudge to the
+    // assignee/owner; otherwise it's work to do.
+    if (e.overdue || (daysUntil(e.due, now) ?? 99) <= DUE_SOON_DAYS) return "ask";
+    return "act";
+  }
+  if (e.status === "in_progress") return "act";
+  const d = daysUntil(e.due, now);
+  if (d != null && d > DUE_SOON_DAYS) return "schedule";
+  return "act";
+}
+
+// --- default judge: cheap model, injectable, never fatal ----------------
+// Uses the low tier so it maps to Haiku (or the provider's cheapest). purpose
+// "recall" is reused only because it is the established cheap per-turn judgment
+// lane; spawnUtilityAgent does not log recall metrics, so nothing is polluted.
+async function defaultJudge(top, ctx) {
+  let spawnUtilityAgent;
+  try { ({ spawnUtilityAgent } = require("../utility-agent")); }
+  catch (e) { return null; }
+
+  const lines = top.map((c, i) =>
+    `${i + 1}. [${c.id}] (${c.source}) ${c.title} — signals: ${c.signals.map((s) => s.label).join(", ") || "none"}`,
+  ).join("\n");
+  const prompt = [
+    "You are triaging the assistant owner's work queue. Pick the SINGLE item to do next.",
+    "Prefer items that are overdue, unblock others, or are already in progress. Be decisive.",
+    "",
+    "Candidates:",
+    lines,
+    "",
+    'Reply with JSON only: {"pickId": "<id>", "actionType": "act|schedule|ask|park", "why": "<one short sentence>", "confidence": "high|medium|low"}',
+  ].join("\n");
+
+  const outputSchema = {
+    type: "object",
+    required: ["pickId", "actionType", "why"],
+    properties: {
+      pickId: { type: "string" },
+      actionType: { type: "string", enum: ACTIONS },
+      why: { type: "string" },
+      confidence: { type: "string", enum: ["high", "medium", "low"] },
+    },
+    additionalProperties: true,
+  };
+
+  try {
+    const r = await spawnUtilityAgent(prompt, {
+      purpose: "recall",
+      tier: "low",
+      readOnly: true,
+      allowedTools: [],
+      outputSchema,
+      timeoutMs: 30000,
+    });
+    if (r && r.ok && r.json && r.json.pickId) return r.json;
+  } catch (e) { /* fall through to deterministic */ }
+  return null;
+}
+
+// --- deliberate: the pipeline -------------------------------------------
+async function deliberate(ledger, opts = {}) {
+  const now = opts.now || (ledger && ledger.generatedAt) || Date.now();
+  const entries = (ledger && ledger.entries) || [];
+  const counts = (ledger && ledger.counts) || null;
+
+  const ranked = entries
+    .filter((e) => isCandidate(e, now))
+    .map((e) => ({ ...e, ...scoreOf(e, now) }))
+    .sort((a, b) => b.score - a.score);
+
+  const base = {
+    generatedAt: now,
+    proposed: false,
+    pick: null,
+    actionType: null,
+    why: [],
+    confidence: "low",
+    method: "deterministic",
+    candidateCount: ranked.length,
+    candidates: ranked.slice(0, TOP_N).map((c) => ({ id: c.id, source: c.source, title: c.title, score: Math.round(c.score) })),
+    counts,
+  };
+
+  if (!ranked.length || ranked[0].score < CONFIDENCE_FLOOR) return base;
+
+  const top = ranked.slice(0, TOP_N);
+  let pick = ranked[0];
+  let actionType = guessAction(pick, now);
+  let method = "deterministic";
+  let judgeWhy = null;
+  const margin = ranked.length > 1 ? ranked[0].score - ranked[1].score : Infinity;
+  let confidence = margin >= CLEAR_MARGIN ? "high" : "medium";
+
+  const useJudge = opts.useJudge === true && ranked.length > 1 && margin < CLEAR_MARGIN;
+  if (useJudge) {
+    const judge = opts.judge || defaultJudge;
+    let verdict = null;
+    try { verdict = await judge(top, { now }); } catch (e) { verdict = null; }
+    if (verdict && verdict.pickId) {
+      const chosen = top.find((c) => c.id === verdict.pickId);
+      if (chosen) {
+        pick = chosen;
+        if (ACTIONS.includes(verdict.actionType)) actionType = verdict.actionType;
+        if (verdict.why) judgeWhy = String(verdict.why);
+        if (["high", "medium", "low"].includes(verdict.confidence)) confidence = verdict.confidence;
+        method = "judge";
+      }
+    }
+  }
+
+  const why = pick.signals.filter((s) => s.w !== 0 || s.k === "context").map((s) => s.label);
+
+  return {
+    ...base,
+    proposed: true,
+    pick: {
+      id: pick.id, source: pick.source, kind: pick.kind, title: pick.title,
+      status: pick.status, due: pick.due, priority: pick.priority,
+      score: Math.round(pick.score), meta: pick.meta,
+    },
+    actionType,
+    why,
+    judgeWhy,
+    confidence,
+    method,
+  };
+}
+
+// --- shadow record: append one line per real deliberation ---------------
+function record(proposal, meta = {}) {
+  if (!shadowEnabled() || !proposal) return;
+  try {
+    const row = {
+      at: new Date().toISOString(),
+      proposed: !!proposal.proposed,
+      pickId: proposal.pick ? proposal.pick.id : null,
+      source: proposal.pick ? proposal.pick.source : null,
+      title: proposal.pick ? proposal.pick.title : null,
+      actionType: proposal.actionType || null,
+      confidence: proposal.confidence || null,
+      method: proposal.method || null,
+      score: proposal.pick ? proposal.pick.score : null,
+      candidateCount: proposal.candidateCount || 0,
+      channel: meta.channel || null,
+    };
+    try {
+      const st = fs.statSync(LOG_FILE);
+      if (st.size > MAX_LOG_BYTES) fs.renameSync(LOG_FILE, `${LOG_FILE}.1`);
+    } catch (e) {}
+    fs.appendFileSync(LOG_FILE, JSON.stringify(row) + "\n");
+  } catch (e) { /* best effort */ }
+}
+
+// --- render: advisory text (no action taken) ----------------------------
+const ACTION_VERB = {
+  act: "Do it now",
+  schedule: "Schedule it",
+  ask: "Nudge / ask",
+  park: "Park it",
+};
+
+function render(proposal) {
+  if (!proposal || !proposal.proposed) {
+    return "Nothing pressing to pick right now — nothing overdue, due soon, or in progress that clears the bar. 🟢";
+  }
+  const p = proposal.pick;
+  const conf = proposal.confidence ? ` · ${proposal.confidence} confidence` : "";
+  const via = proposal.method === "judge" ? " · judged" : "";
+  const lines = [];
+  lines.push(`Next up (advisory${conf}${via})`);
+  lines.push("─".repeat(18));
+  lines.push(`${p.title}`);
+  lines.push(`  ${ACTION_VERB[proposal.actionType] || proposal.actionType} · ${p.source}${p.id ? ` · ${p.id}` : ""}`);
+  if (proposal.judgeWhy) lines.push(`  Why: ${proposal.judgeWhy}`);
+  else if (proposal.why && proposal.why.length) lines.push(`  Why: ${proposal.why.join(" · ")}`);
+  if (proposal.candidateCount > 1) {
+    lines.push("");
+    lines.push(`Considered ${proposal.candidateCount}; runners-up:`);
+    for (const c of proposal.candidates.slice(1, 4)) lines.push(`  · ${c.title}  (${c.score})`);
+  }
+  lines.push("");
+  lines.push("Advisory only — I won't act on this without your go-ahead.");
+  return lines.join("\n");
+}
+
+module.exports = {
+  deliberate,
+  render,
+  record,
+  scoreOf,
+  isCandidate,
+  guessAction,
+  defaultJudge,
+  shadowEnabled,
+  LOG_FILE,
+  ACTIONS,
+  CONFIDENCE_FLOOR,
+  CLEAR_MARGIN,
+};

package/core/agency/ledger.js

@@ -0,0 +1,294 @@
+// Agency ledger — read-only work aggregator (Track B0).
+//
+// Unifies three sources into one normalized, ranked work list:
+//   • persistent per-channel tasks (core/tasks) — the agent's own plan/subtasks
+//   • Spaces tasks assigned to the owner (`spaces mine`, via the spaces tool)
+//   • connector inbox notifications (core/connected-apps) — awareness items
+//
+// Pure visibility, zero autonomy: this module only reads and normalizes. The
+// deliberation/act layer (Track B1+) consumes build()/collect() output; it never
+// writes here. Credentials never touch this module — the Spaces fetch is
+// delegated to the `spaces` tool subprocess (keyring-injected), so core holds no
+// secrets. build() is a pure function (no I/O) so it is unit-testable in full;
+// collect() is the thin impure orchestrator that gathers the three sources.
+
+const { execFile } = require("child_process");
+
+const DAY_MS = 86400000;
+const DEFAULT_STALE_DAYS = 14;
+
+function toMs(v) {
+  if (!v) return 0;
+  if (typeof v === "number") return v;
+  const t = Date.parse(v);
+  return Number.isFinite(t) ? t : 0;
+}
+
+function staleDaysOf(lastTouched, now) {
+  if (!lastTouched) return null;
+  return Math.max(0, (now - lastTouched) / DAY_MS);
+}
+
+// --- normalizers: each source → the common entry shape ------------------
+// { source, kind, id, title, status, priority, due, lastTouched, staleDays,
+//   blockedOn, overdue, meta }
+
+function normalizeTask(t, now) {
+  const lastTouched = toMs(t.updatedAt || t.createdAt);
+  const status = t.status === "in_progress" ? "in_progress"
+    : t.status === "completed" ? "done"
+    : "open";
+  return {
+    source: "task",
+    kind: t.parentId ? "subtask" : "task",
+    id: String(t.id || ""),
+    title: t.content || "(untitled)",
+    status,
+    priority: null,
+    due: null,
+    lastTouched,
+    staleDays: staleDaysOf(lastTouched, now),
+    blockedOn: null,
+    overdue: false,
+    meta: { parentId: t.parentId || null, description: t.description || null },
+  };
+}
+
+function normalizeSpacesTask(t, now) {
+  const lastTouched = toMs(t.updatedAt || t.createdAt);
+  const due = t.dueDate || null;
+  const dueMs = toMs(due);
+  const status = t.status === "in_progress" ? "in_progress"
+    : (t.status === "completed" || t.status === "done" || t.completedAt) ? "done"
+    : "open";
+  const space = t.spaceId && typeof t.spaceId === "object" ? (t.spaceId.name || "") : "";
+  return {
+    source: "spaces",
+    kind: "assignment",
+    id: String(t.id || t._id || ""),
+    title: t.title || "(untitled)",
+    status,
+    priority: t.priority || null,
+    due,
+    lastTouched,
+    staleDays: staleDaysOf(lastTouched, now),
+    blockedOn: t.parentTaskId || null,
+    overdue: !!(dueMs && dueMs < now && status !== "done"),
+    meta: {
+      space,
+      subtasks: t.subtaskCount || 0,
+      subtasksDone: t.subtaskCompletedCount || 0,
+      tags: Array.isArray(t.tags) ? t.tags : [],
+    },
+  };
+}
+
+function normalizeInbox(item, now) {
+  const lastTouched = toMs(item.createdAt);
+  const actor = item.actorName ? `${item.actorName} ` : "";
+  const verb = item.type || "notification";
+  const on = item.taskTitle ? ` on "${item.taskTitle}"` : "";
+  const title = `${actor}${verb}${on}`.trim() || item.text || "(notification)";
+  return {
+    source: "notification",
+    kind: item.type || "notification",
+    id: String(item.id || ""),
+    title,
+    status: "info",
+    priority: null,
+    due: null,
+    lastTouched,
+    staleDays: staleDaysOf(lastTouched, now),
+    blockedOn: null,
+    overdue: false,
+    meta: {
+      app: item.appName || item.appId || "",
+      actor: item.actorName || "",
+      taskId: item.taskId || "",
+      text: item.text || "",
+    },
+  };
+}
+
+// Pure-visibility ordering (NOT the Track B1 deliberation score): overdue first,
+// then anything with a due date by soonest, then in-progress, then most recently
+// touched. Stable + explainable so the ledger always reads sensibly.
+function rankKey(e) {
+  const dueMs = toMs(e.due);
+  return [
+    e.overdue ? 0 : 1,
+    dueMs || Number.MAX_SAFE_INTEGER,
+    e.status === "in_progress" ? 0 : 1,
+    -(e.lastTouched || 0),
+  ];
+}
+
+function cmpKey(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] < b[i]) return -1;
+    if (a[i] > b[i]) return 1;
+  }
+  return 0;
+}
+
+// Pure: raw source arrays → normalized, de-completed, ranked ledger + counts.
+function build({ tasks = [], spacesMine = [], inboxes = [], now = Date.now(), staleDays = DEFAULT_STALE_DAYS } = {}) {
+  const entries = [];
+  for (const t of tasks) entries.push(normalizeTask(t, now));
+  for (const t of spacesMine) entries.push(normalizeSpacesTask(t, now));
+  for (const it of inboxes) entries.push(normalizeInbox(it, now));
+
+  // The ledger is a live work list — completed items drop off.
+  const open = entries.filter((e) => e.status !== "done");
+  open.sort((a, b) => cmpKey(rankKey(a), rankKey(b)));
+
+  const byStatus = {};
+  const bySource = {};
+  let overdue = 0;
+  let stale = 0;
+  for (const e of open) {
+    byStatus[e.status] = (byStatus[e.status] || 0) + 1;
+    bySource[e.source] = (bySource[e.source] || 0) + 1;
+    if (e.overdue) overdue += 1;
+    if (e.staleDays != null && e.staleDays > staleDays) stale += 1;
+  }
+
+  return {
+    generatedAt: now,
+    counts: { total: open.length, overdue, stale, byStatus, bySource },
+    entries: open,
+  };
+}
+
+// Default Spaces fetch: shell the read-only `spaces mine` tool verb. Keyring
+// creds are injected only into that subprocess, so this module never holds the
+// central login. Best-effort — any failure yields [] and the ledger still shows
+// tasks + notifications.
+function defaultFetchSpacesMine({ timeoutMs = 15000 } = {}) {
+  return new Promise((resolve) => {
+    execFile(
+      "open-claudia",
+      ["tool", "run", "spaces", "mine", "--json"],
+      { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024 },
+      (err, stdout) => {
+        if (err || !stdout) return resolve([]);
+        try {
+          // Tool stdout can carry ExperimentalWarning/SQLite noise before the JSON.
+          const start = stdout.indexOf("[");
+          const parsed = JSON.parse(start >= 0 ? stdout.slice(start) : stdout);
+          resolve(Array.isArray(parsed) ? parsed : []);
+        } catch (e) { resolve([]); }
+      },
+    );
+  });
+}
+
+// Impure orchestrator: gather the three sources, then build(). Every source is
+// best-effort so a single failure never blanks the ledger.
+async function collect({ adapter, channelId, now = Date.now(), staleDays = DEFAULT_STALE_DAYS, includeSpaces = true, fetchSpacesMine } = {}) {
+  let tasks = [];
+  try {
+    if (adapter && channelId) tasks = require("../tasks").list(adapter, channelId);
+  } catch (e) { tasks = []; }
+
+  let spacesMine = [];
+  if (includeSpaces) {
+    try {
+      const fetch = fetchSpacesMine || defaultFetchSpacesMine;
+      const r = await fetch({});
+      spacesMine = Array.isArray(r) ? r : [];
+    } catch (e) { spacesMine = []; }
+  }
+
+  let inboxes = [];
+  try {
+    inboxes = require("../connected-apps").getAllInboxes() || [];
+  } catch (e) { inboxes = []; }
+
+  return build({ tasks, spacesMine, inboxes, now, staleDays });
+}
+
+// --- rendering ----------------------------------------------------------
+
+function ago(ms, now) {
+  if (!ms) return "";
+  const s = Math.max(0, Math.round((now - ms) / 1000));
+  if (s < 90) return "just now";
+  const m = Math.round(s / 60);
+  if (m < 90) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 36) return `${h}h ago`;
+  return `${Math.round(h / 24)}d ago`;
+}
+
+function dueLabel(due, now) {
+  const dueMs = toMs(due);
+  if (!dueMs) return "";
+  const days = Math.round((dueMs - now) / DAY_MS);
+  if (days < 0) return `overdue ${-days}d`;
+  if (days === 0) return "due today";
+  if (days === 1) return "due tomorrow";
+  return `due ${days}d`;
+}
+
+const SOURCE_LABEL = {
+  spaces: "Spaces (assigned to me)",
+  task: "Local tasks (this channel)",
+  notification: "Notifications (inbox)",
+};
+const SOURCE_ORDER = ["spaces", "task", "notification"];
+
+function mark(e) {
+  if (e.overdue) return "!";
+  if (e.status === "in_progress") return "~";
+  if (e.source === "notification") return "•";
+  return " ";
+}
+
+function renderEntry(e, now, showIds) {
+  const bits = [];
+  const d = dueLabel(e.due, now);
+  if (d) bits.push(d);
+  if (e.status === "in_progress" && !e.overdue) bits.push("in progress");
+  if (e.priority && e.priority !== "medium") bits.push(e.priority);
+  if (e.meta && e.meta.space) bits.push(e.meta.space);
+  const a = ago(e.lastTouched, now);
+  if (a && (e.source !== "spaces" || !d)) bits.push(a);
+  const tail = bits.length ? `  · ${bits.join(" · ")}` : "";
+  const id = showIds && e.id ? `  (${e.id})` : "";
+  return ` ${mark(e)} ${e.title}${tail}${id}`;
+}
+
+function render(ledger, opts = {}) {
+  const now = opts.now || ledger.generatedAt || Date.now();
+  const limit = Number.isFinite(opts.limitPerSource) ? opts.limitPerSource : 10;
+  const showIds = !!opts.showIds;
+  const c = ledger.counts || { total: 0, overdue: 0, stale: 0 };
+  const lines = ["Agenda", "──────"];
+  const summary = [`${c.total} open`];
+  if (c.overdue) summary.push(`${c.overdue} overdue`);
+  if (c.stale) summary.push(`${c.stale} stale`);
+  lines.push(summary.join(" · "));
+
+  for (const src of SOURCE_ORDER) {
+    const items = (ledger.entries || []).filter((e) => e.source === src);
+    if (!items.length) continue;
+    lines.push("");
+    lines.push(`${SOURCE_LABEL[src] || src} — ${items.length}`);
+    for (const e of items.slice(0, limit)) lines.push(renderEntry(e, now, showIds));
+    if (items.length > limit) lines.push(`   …and ${items.length - limit} more`);
+  }
+  if (!(ledger.entries || []).length) lines.push("", "Nothing on your plate. 🎉");
+  return lines.join("\n");
+}
+
+module.exports = {
+  build,
+  collect,
+  render,
+  normalizeTask,
+  normalizeSpacesTask,
+  normalizeInbox,
+  defaultFetchSpacesMine,
+  DEFAULT_STALE_DAYS,
+};

package/core/connected-apps.js

@@ -204,6 +204,20 @@ function snapshot() {
   };
 }
 
+// Public: flat, normalized list of every connector inbox item across all apps,
+// each tagged with the app it came from. Read-only; lazily loads the on-disk
+// store so it works from any process (the parent poller keeps the file fresh).
+function getAllInboxes() {
+  if (!store) store = loadStore();
+  const nameById = new Map(store.apps.map((a) => [String(a.id || a.name), a.name || String(a.id || "")]));
+  const out = [];
+  for (const [appId, state] of Object.entries(store.perApp || {})) {
+    const appName = nameById.get(appId) || appId;
+    for (const it of state.inbox || []) out.push({ appId, appName, ...it });
+  }
+  return out;
+}
+
 function initConnectedApps() {
   if (!truthy(config.OC_CONNECTED_APPS || process.env.OC_CONNECTED_APPS, false)) {
     return { started: false, reason: "OC_CONNECTED_APPS disabled" };
@@ -231,5 +245,6 @@ module.exports = {
   registerConnector,
   fetchConnectedApps,
   snapshot,
+  getAllInboxes,
   STORE_FILE,
 };