Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Cross-domain Review Queue (M42 P5) — the "inbox zero" aggregator.
*
* Where review.js manages *stored* review items (todos/alerts/briefing/cos that
* producers push in via cosEvents), this module *live-pulls* the things across
* PortOS that are currently waiting on the user and normalizes them into one
* list. It reads each producer's existing service on demand; only separate
* presentation markers are persisted, so source payloads remain live state.
*
* Each producer is gathered independently and defensively: a single producer
* throwing (or its data file being absent) degrades that one source to an
* unavailable projection rather than sinking the whole queue. Every row keeps
* the legacy fields and adds a canonical action projection:
*
* { id, source, sourceRef, actionKind, title, reason, nextAction,
* severity, priority, dueAt, revision, occurrence, operations }
*
* `drillTo` is a client route the UI deep-links to so "drill-down" works without
* the queue needing to know how to render each domain.
*
* A producer may also declare an inline `action` (a verb label) + `resolve(rawId)`
* primitive, in which case the row carries `action` and `resolveQueueItem()` can
* accept/promote it in place without leaving the Review Hub (issue #709 follow-up
* to the v1 read-only aggregator). Sources with no clean local resolve (health
* alerts are live-computed and clear when the condition does; a failed backup
* retries by re-running with settings) stay drill-down plus capability-aware
* presentation triage.
*/
import { randomUUID } from 'node:crypto';
import * as brain from './brain.js';
import * as brainStorage from './brainStorage.js';
import * as askConversations from './askConversations.js';
import * as cosTaskStore from './cosTaskStore.js';
import * as messageDrafts from './messageDrafts.js';
import { HEALTH_RESOLUTION_PREFIX } from './healthAlertResolutions.js';
import { buildHealthAlertInvestigation } from './healthAlertAgentTask.js';
import { generateNonProductAlerts } from './proactiveAlertSources.js';
import * as identity from './identity.js';
import * as reviewService from './review.js';
import * as notifications from './notifications.js';
import * as stackerNews from './stackerNews.js';
import * as x from './x.js';
import { NOTIFICATION_ACTION_POLICY } from '../lib/notificationTypes.js';
import { resolveBackupConfig } from '../lib/backupConfig.js';
import { ServerError } from '../lib/errorHandler.js';
import { safeJSONParse } from '../lib/fileUtils.js';
import { getUserTimezone } from './userTimezone.js';
import { getProductEngagement } from './portosProductMetrics.js';
import * as reviewQueueTriageStore from './reviewQueueTriageStore.js';
import { anchorLocalMidnightUtc, todayInTimezone } from '../lib/timezone.js';
import { TIMED_COOLDOWN_BLOCKED_CATEGORIES } from '../lib/taskBlockCategories.js';
import { isTerminalThreadStatus, threadNextLine } from '../lib/brainThreads.js';
// Producers are read with a bounded upper limit. The queue reports a lower
// bound, rather than pretending that a full count is known, when a producer
// fills this window. Pagination then slices the normalized snapshot, not a
// fresh set of source reads, so adjacent pages cannot reorder underneath a
// caller.
export const REVIEW_QUEUE_SOURCE_READ_LIMIT = 100;
export const REVIEW_QUEUE_MAX_PAGE_SIZE = 100;
const REVIEW_QUEUE_SOURCE_PROBE_LIMIT = REVIEW_QUEUE_SOURCE_READ_LIMIT + 1;
const REVIEW_QUEUE_SNAPSHOT_TTL_MS = 30_000;
const REVIEW_QUEUE_MAX_SNAPSHOTS = 100;
export const MAX_REVIEW_QUEUE_SNOOZE_MS = 30 * 24 * 60 * 60 * 1000;
// One process-wide deadline replaces browser polling for clock-only changes.
// It carries no source records, and is armed only after an explicit queue read.
let clockInvalidation = null;
let clockInvalidationAt = Infinity;
function scheduleQueueClockInvalidation(at) {
const delay = at - Date.now();
if (!Number.isFinite(at) || delay <= 0 || at >= clockInvalidationAt) return;
clearTimeout(clockInvalidation);
clockInvalidationAt = at;
clockInvalidation = setTimeout(() => {
clockInvalidation = null;
clockInvalidationAt = Infinity;
if (Date.now() < at) scheduleQueueClockInvalidation(at);
else reviewService.reviewEvents.emit('queue:changed');
}, Math.min(delay, 2_147_483_647));
clockInvalidation.unref?.();
}
const ACTION_KINDS = Object.freeze({
brain: 'brain.classify',
ask: 'ask.promote',
cos: 'cos.approve',
drafts: 'message.approve',
stacker: 'stacker.review',
x: 'x.review',
health: 'health.investigate',
backup: 'backup.retry',
review: 'review.triage',
notifications: 'notification.action',
threads: 'brain.thread',
todo: 'review.todo',
history: 'review.history',
feedback: 'cos.feedback',
github: 'github.notification',
product: 'product.recommendation',
});
const OPERATION_LABELS = Object.freeze({
brain: 'Done',
ask: 'Promote',
cos: 'Approve',
drafts: 'Approve',
stacker: 'Review',
x: 'Review',
health: 'Investigate',
backup: 'Retry',
review: 'Review',
notifications: 'Review',
threads: 'Complete',
todo: 'Complete',
history: 'History',
feedback: 'Rate',
github: 'Review',
});
const PRIORITY_ORDER = { HIGH: 0, MEDIUM: 1, LOW: 2 };
// generateNonProductAlerts() runs a full system-health sweep (CPU/disk/PM2/goals/usage),
// so cache it briefly — the Review Hub can be polled, and a stale-by-seconds
// alert list is fine here (the dedicated health views read it live).
const ALERTS_TTL_MS = 30_000;
let alertsCache = { data: null, timestamp: 0 };
let alertsGeneration = 0;
async function getAlertsCached() {
if (alertsCache.data && (Date.now() - alertsCache.timestamp) < ALERTS_TTL_MS) {
return alertsCache.data;
}
const generation = alertsGeneration;
const result = await generateNonProductAlerts();
if (generation === alertsGeneration) alertsCache = { data: result, timestamp: Date.now() };
return result;
}
// Test seam: drop the alerts cache so a suite can assert fresh per-case data.
export function __resetAlertsCache() {
alertsGeneration++;
alertsCache = { data: null, timestamp: 0 };
}
// Active goals are fetched once per buildQueue() (not per Ask row) so the
// inline goal picker on Ask rows has targets to offer. getGoals() lazily
// migrates the store, so we read it once and reuse the result while gathering.
// A goal-store failure degrades to "no goal targets" rather than sinking Ask.
async function getActiveGoalOptions() {
const data = await identity.getGoals().catch((err) => {
console.error(`❌ Review queue: goal options failed: ${err.message}`);
return null;
});
const goals = Array.isArray(data?.goals) ? data.goals : [];
// Guard each entry — a malformed `null`/non-object goal would otherwise throw
// on `g.status` here, and because this runs *before* the per-producer
// Promise.all catch in buildQueue, that throw would sink the whole queue
// rather than degrading goal targets to empty.
return goals
.filter((g) => g && typeof g === 'object' && g.status === 'active' && typeof g.id === 'string' && g.id)
.map((g) => ({ id: g.id, title: typeof g.title === 'string' && g.title ? g.title : '(untitled goal)' }));
}
const COMMITMENT_VIEWS = new Set(['today', 'all', 'waiting', 'someday', 'history', 'snoozed']);
const ACTIVE_THREAD_STATUSES = new Set(['open', 'waiting', 'someday']);
function isDueByLocalToday(thread, timezone, now = new Date()) {
if (!thread.dueAt) return thread.status === 'open';
const dueAt = Date.parse(thread.dueAt);
if (!Number.isFinite(dueAt)) return false;
const today = todayInTimezone(timezone, now);
const dueDay = todayInTimezone(timezone, new Date(dueAt));
return dueDay <= today;
}
function threadBelongsToView(thread, view, timezone, now = new Date()) {
if (!thread || typeof thread.id !== 'string' || !thread.id) return false;
if (!view) return ACTIVE_THREAD_STATUSES.has(thread.status);
if (!COMMITMENT_VIEWS.has(view)) return ACTIVE_THREAD_STATUSES.has(thread.status);
if (view === 'all') return ACTIVE_THREAD_STATUSES.has(thread.status);
if (view === 'history') return isTerminalThreadStatus(thread.status);
if (view === 'snoozed') return ACTIVE_THREAD_STATUSES.has(thread.status);
if (view === 'waiting' || view === 'someday') return thread.status === view;
return ACTIVE_THREAD_STATUSES.has(thread.status) && isDueByLocalToday(thread, timezone, now);
}
// These are task-owned obligations, not independent promises made by the user.
// Read live state so legacy recovery commitments clear as soon as
// automation resumes or finishes. Missing tasks stay visible; unreadable tasks
// fail the source read rather than falsely reporting an empty queue.
async function taskActionContext(taskId) {
const task = await cosTaskStore.getTaskById(taskId);
if (!task) return { needsUserAction: true, task: null };
if (task.status === 'pending' && task.approvalRequired) return { needsUserAction: true, task };
if (task.status === 'blocked') {
return { needsUserAction: !TIMED_COOLDOWN_BLOCKED_CATEGORIES.has(task.metadata?.blockedCategory), task };
}
return {
needsUserAction: !['pending', 'in_progress', 'completed', 'cancelled'].includes(task.status),
task,
};
}
const visibleInLiveViews = (producer, view) => {
if (!view) return producer.source !== 'history';
if (view === 'snoozed') return producer.source !== 'history';
if (Array.isArray(producer.views)) return producer.views.includes(view);
return view === 'today' || view === 'all';
};
const threadAction = (thread) => {
const terminal = isTerminalThreadStatus(thread.status);
return terminal
? [{ id: 'reopen', label: 'Reopen', available: true }]
: [{ id: 'complete', label: 'Complete', available: true }];
};
const threadMeta = (thread) => ({
localStatus: thread.status,
...(typeof thread.externalState === 'string' && thread.externalState.trim()
? { externalState: thread.externalState.trim() }
: {}),
...(typeof thread.source === 'string' && thread.source.trim()
? { externalSource: thread.source.trim() }
: {}),
});
const backupNeedsAttention = (state) => Boolean(state && (state.status === 'error' || state.status === 'degraded' || state.error));
/**
* Producer registry. Each entry knows how to gather its raw items and map one
* into the normalized queue shape. `gather` returns the raw list (already
* filtered to "needs attention"); `map` normalizes a single raw item.
*/
const PRODUCERS = [
{
source: 'brain',
label: 'Brain inbox',
drillTo: '/brain/inbox',
// Marking the entry done clears it from the needs-review queue.
actionLabel: 'Done',
async resolve(id) {
return brain.markInboxDone(id);
},
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
// Inbox entries the auto-classifier couldn't place — they need a human
// to pick a destination.
return brain.getInboxLog({ status: 'needs_review', limit });
},
map(entry) {
const text = (entry.capturedText || '').trim();
// Surface where the capture came from (brain_ui / voice / a managed app)
// so the user can triage by origin. Absent on legacy entries — omit the
// field entirely rather than fabricate one (absent vs empty).
const captureSource = typeof entry.source === 'string' && entry.source.trim()
? entry.source.trim()
: null;
return {
id: `brain:${entry.id}`,
title: 'Inbox item needs classification',
summary: text.slice(0, 200),
timestamp: entry.capturedAt || entry.createdAt || null,
severity: 'normal',
drillTo: '/brain/inbox',
...(captureSource ? { meta: { captureSource } } : {})
};
}
},
{
source: 'threads',
label: 'Brain commitments',
drillTo: '/brain/threads',
views: ['today', 'all', 'waiting', 'someday', 'history'],
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT, ctx = {}) {
const timezone = ctx.timezone || 'UTC';
const now = ctx.now || new Date();
const threads = await brainStorage.getThreads();
const candidates = (Array.isArray(threads) ? threads : [])
.filter((thread) => threadBelongsToView(thread, ctx.view, timezone, now));
const actionable = await Promise.all(candidates.map(async thread => {
const taskRef = thread.source === 'cos' && thread.refs?.find(ref => ref?.kind === 'cos.task' && ref.id);
if (!taskRef || ctx.view === 'history') return { needsUserAction: true, task: null };
return taskActionContext(taskRef.id);
}));
const matching = candidates.flatMap((thread, index) => actionable[index].needsUserAction
? [{ thread, task: actionable[index].task }]
: []);
const appIds = [...new Set(matching
.map(({ task }) => typeof task?.metadata?.app === 'string' ? task.metadata.app.trim() : '')
.filter(Boolean))];
const appNames = new Map();
if (appIds.length) {
const appService = await import('./apps.js').catch(() => null);
if (appService?.getAppById) {
await Promise.all(appIds.map(async appId => {
const app = await appService.getAppById(appId).catch(() => null);
if (typeof app?.name === 'string' && app.name.trim()) appNames.set(appId, app.name.trim());
}));
}
}
return {
items: matching.map(({ thread, task }) => {
const nextAction = threadNextLine(thread);
const summaryParts = [nextAction || (thread.waitingOn ? `Waiting on ${thread.waitingOn}` : 'No next action set')];
const metadata = task?.metadata && typeof task.metadata === 'object' ? task.metadata : {};
const blockedCategory = typeof metadata.blockedCategory === 'string' ? metadata.blockedCategory.trim() : '';
if (task?.status === 'blocked') {
const reason = typeof metadata.blockedReason === 'string' ? metadata.blockedReason.trim() : '';
summaryParts.push(reason
? `Still blocked: ${reason}`
: `Still blocked${blockedCategory ? ` (${blockedCategory})` : ''}.`);
}
const appId = typeof metadata.app === 'string' ? metadata.app.trim() : '';
const appLabel = appId ? (appNames.get(appId) || appId) : '';
const prUrl = typeof metadata.reviewLoopPRUrl === 'string'
? metadata.reviewLoopPRUrl.trim()
: typeof metadata.prUrl === 'string' ? metadata.prUrl.trim() : '';
const meta = {
...threadMeta(thread),
...(typeof task?.status === 'string' ? { taskStatus: task.status } : {}),
...(blockedCategory ? { blockedCategory } : {}),
...(appLabel ? { appLabel } : {}),
...(prUrl ? { reviewLoopPRUrl: prUrl } : {}),
};
return {
...thread,
queueSummary: summaryParts.join(' ').slice(0, 500),
queueMeta: meta,
};
}),
truncated: matching.length > limit,
};
},
map(thread) {
return {
id: `threads:${thread.id}`,
title: thread.title || 'Untitled commitment',
summary: thread.queueSummary || threadNextLine(thread) || (thread.waitingOn ? `Waiting on ${thread.waitingOn}` : 'No next action set'),
timestamp: thread.updatedAt || thread.createdAt || null,
severity: thread.priority === 'urgent' ? 'high' : 'normal',
required: true,
isRecommendation: false,
dueAt: thread.dueAt || null,
drillTo: `/brain/threads?thread=${encodeURIComponent(thread.id)}`,
operations: threadAction(thread),
meta: thread.queueMeta || threadMeta(thread),
};
},
},
{
source: 'ask',
label: 'Ask answers',
drillTo: '/ask',
// Ask carries no single `action`/`resolve` primitive (the row's
// `setPromoted` only *pins* the conversation against expiry, which the Ask
// UI labels "Pin", not promote-to-target). Promotion is instead offered
// inline via `promoteTargets` + `goalOptions`: brain/task in one click and
// goal via a picker (see map() below). Drilling into /ask still works for a
// per-turn promote the queue's latest-turn shortcut doesn't cover.
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
// Conversations with a promotable assistant answer that haven't been
// promoted to brain/task/goal. Gate on assistantTurnCount, NOT turnCount:
// an Ask conversation whose stream errored (or whose client disconnected)
// before the assistant turn persisted still has the user turn (turnCount
// > 0), but promoteLatestAssistantTurn would fail with NO_ASSISTANT_TURN —
// so advertising a promote action on it would be a dead-end button.
const convs = await askConversations.listConversations({ limit });
return {
items: (Array.isArray(convs) ? convs : []).filter(c => !c.promoted && (c.assistantTurnCount || 0) > 0),
truncated: Array.isArray(convs) && convs.length >= limit,
};
},
// Inline promote targets the UI can offer without a per-turn drill-down.
// The queue picks the conversation's latest assistant turn server-side, so
// brain/task need no extra choice. `goal` also promotes the latest turn but
// needs a goalId, so the row additionally carries `goalOptions` and the UI
// renders a goal picker; goal is only offered when at least one active goal
// exists (gatherContext.goalOptions, populated once per buildQueue).
promoteTargets: ['brain', 'task'],
map(conv, index, ctx) {
const turnCount = Number.isFinite(conv.turnCount) ? conv.turnCount : null;
const goalOptions = Array.isArray(ctx?.goalOptions) ? ctx.goalOptions : [];
return {
id: `ask:${conv.id}`,
title: 'Ask answer ready to promote',
summary: conv.title || '(untitled conversation)',
timestamp: conv.updatedAt || conv.createdAt || null,
severity: 'normal',
// Promotion is still available from Ask, but an optional answer is
// not a required user action in the canonical queue.
required: false,
isRecommendation: true,
drillTo: `/ask/${conv.id}`,
// Only advertise the goal target (and its picker options) when there's
// at least one active goal to promote into — an empty picker would be a
// dead-end button.
...(goalOptions.length ? { promoteTargets: ['brain', 'task', 'goal'], goalOptions } : {}),
...(turnCount != null ? { meta: { turnCount } } : {})
};
}
},
{
source: 'cos',
label: 'CoS approvals',
drillTo: '/cos/tasks',
actionLabel: 'Approve',
// approveTask resolves to an `{ error }` object (not a throw) when the task
// can't be approved; surface that as a failed resolve.
async resolve(id) {
const result = await cosTaskStore.approveTask(id);
if (result && result.error) throw new ServerError(result.error, { status: 409, code: 'CONFLICT' });
return result;
},
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
// Internal CoS tasks parked awaiting the user's approval before they run.
const { awaitingApproval } = await cosTaskStore.getCosApprovalView({ limit });
return awaitingApproval;
},
map(task) {
// Surface the task priority as a triage badge. Only HIGH/MEDIUM/LOW are
// meaningful — anything else (or absent) is omitted rather than guessed.
const priority = ['HIGH', 'MEDIUM', 'LOW'].includes(task.priority) ? task.priority : null;
return {
id: `cos:${task.id}`,
title: 'CoS task pending approval',
summary: (task.description || '').slice(0, 200),
timestamp: task.createdAt || null,
severity: task.priority === 'HIGH' ? 'high' : 'normal',
drillTo: '/cos/tasks',
...(priority ? { meta: { priority } } : {})
};
}
},
{
source: 'feedback',
label: 'CoS run feedback',
drillTo: '/cos/agents?feedback=needs-feedback',
views: ['today', 'all', 'history'],
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT, ctx = {}) {
const { getPendingAgentFeedback } = await import('./cosAgentFeedback.js');
const pending = await getPendingAgentFeedback({ includeUnavailable: ctx.view === 'history' });
const items = [
...(Array.isArray(pending?.agents) ? pending.agents : []),
...(ctx.view === 'history' && Array.isArray(pending?.unavailable) ? pending.unavailable : []),
];
return { items: items.slice(0, limit), truncated: items.length > limit };
},
map(agent) {
const unavailable = agent.availability === 'unavailable';
const description = agent.metadata?.taskDescription;
return {
id: `feedback:${agent.id || agent.agentId}`,
title: unavailable ? 'Completed CoS run unavailable for feedback' : 'Rate completed CoS run',
summary: unavailable
? 'The source run is no longer available to rate; the action is retained as history.'
: (typeof description === 'string' && description.trim()
? description.trim().slice(0, 200)
: 'Completed manual CoS run'),
timestamp: agent.completedAt || null,
severity: 'normal',
required: !unavailable,
isRecommendation: false,
sourceRef: agent.id || agent.agentId,
...(!unavailable
? { drillTo: `/cos/agents/${encodeURIComponent(agent.id || agent.agentId)}?feedback=needs-feedback` }
: {}),
availability: unavailable ? 'unavailable' : 'available',
available: !unavailable,
...(unavailable
? {
meta: { unavailableReason: agent.unavailableReason || 'unavailable' },
nextAction: 'Unavailable',
operations: [],
}
: {
operations: [{
id: 'rate',
label: 'Rate',
available: true,
input: { type: 'rating', required: true, options: ['positive', 'negative', 'neutral'] },
}],
}),
};
},
},
{
source: 'drafts',
label: 'Message drafts',
drillTo: '/messages/drafts',
// Approve (not send) — clears it from the awaiting-review queue without an
// outward side effect; the user still triggers the actual send from /messages.
actionLabel: 'Approve',
actionFor: (draft) => draft.status === 'pending_review',
async resolve(id) {
return messageDrafts.approveDraft(id);
},
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
// Drafts the user (or an AI) prepared that haven't been sent yet. Today
// messageDrafts only emits 'draft' (vs 'approved'); 'pending_review' is
// matched ahead of the producer adding it. The multi-status filter is
// pushed down to listDrafts so the whole store isn't loaded + filtered
// in memory on every Review Hub load.
const drafts = await messageDrafts.listDrafts({ status: ['draft', 'pending_review'] });
return (Array.isArray(drafts) ? drafts : []).slice(0, limit);
},
map(draft) {
// Show who/where the draft is headed so the user can triage without
// opening it: the first recipient, plus the channel it'd send through.
// Each is omitted when absent rather than rendered as an empty string.
const recipient = Array.isArray(draft.to) && typeof draft.to[0] === 'string' && draft.to[0].trim()
? draft.to[0].trim()
: null;
const channel = typeof draft.sendVia === 'string' && draft.sendVia.trim()
? draft.sendVia.trim()
: null;
const meta = {};
if (recipient) meta.recipient = recipient;
if (channel) meta.channel = channel;
return {
// Prefix matches `source` ('drafts') so resolveQueueItem's
// split-on-first-colon dispatch lands on this producer.
id: `drafts:${draft.id}`,
title: draft.status === 'pending_review' ? 'Draft awaiting review' : 'Unsent message draft',
summary: draft.subject || (draft.body || '').slice(0, 120) || '(no subject)',
timestamp: draft.updatedAt || draft.createdAt || null,
severity: 'normal',
required: draft.status === 'pending_review',
isRecommendation: draft.status !== 'pending_review',
drillTo: '/messages/drafts',
nextAction: draft.status === 'pending_review' ? 'Approve' : 'Open draft',
...(Object.keys(meta).length ? { meta } : {})
};
}
},
{
source: 'review',
label: 'Stored review obligations',
drillTo: '/review',
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
const { adaptStoredReviewItem } = await import('./reviewActionAdapters.js');
const pendingItems = await reviewService.getItems({ status: 'pending' });
const items = (Array.isArray(pendingItems) ? pendingItems : [])
.map(adaptStoredReviewItem)
.filter(Boolean);
return {
items,
truncated: items.length > limit,
};
},
map(item) {
return item;
},
},
{
source: 'todo',
label: 'Manual commitments',
drillTo: '/review?view=history',
views: ['today', 'all', 'history'],
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT, ctx = {}) {
const history = ctx.view === 'history';
const items = await reviewService.getItems({
type: 'todo',
...(history ? {} : { status: 'pending' }),
});
const matching = (Array.isArray(items) ? items : [])
.filter((item) => item.type === 'todo')
.filter((item) => history ? item.status !== 'pending' : item.status === 'pending');
return { items: matching, truncated: matching.length > limit };
},
map(item) {
const completed = item.status !== 'pending';
return {
id: `todo:${item.id}`,
title: item.title || 'Untitled commitment',
summary: item.description || item.title || '',
timestamp: item.updatedAt || item.createdAt || null,
dueAt: item.metadata?.dueAt || null,
required: !completed,
isRecommendation: false,
drillTo: `/review/${encodeURIComponent(`todo:${item.id}`)}?view=${completed ? 'history' : 'today'}`,
operations: completed
? [{ id: 'reopen', label: 'Reopen', available: true }]
: [{ id: 'complete', label: 'Complete', available: true }],
meta: { status: item.status, reviewItemId: item.id },
};
},
},
{
source: 'history',
label: 'Review history',
drillTo: '/review?view=history',
views: ['history'],
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
const items = await reviewService.getItems();
const matching = (Array.isArray(items) ? items : [])
.filter((item) => item.status !== 'pending' && item.type !== 'todo');
return {
items: matching,
truncated: matching.length > limit,
};
},
map(item) {
return {
id: `history:${item.id}`,
title: item.title || 'Review history item',
summary: item.description || item.title || '',
timestamp: item.updatedAt || item.createdAt || null,
required: false,
isRecommendation: false,
operations: [],
drillTo: item.metadata?.link || '/review?view=history',
meta: { status: item.status, type: item.type, reviewItemId: item.id },
};
},
},
{
source: 'notifications',
label: 'Actionable notifications',
drillTo: '/review',
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
const { adaptNotification } = await import('./reviewActionAdapters.js');
// Filter before applying the queue cap. A busy history stream must not
// hide a source-owned approval that happens to be older than it.
const records = await notifications.getNotifications({ includeHidden: true });
const items = (Array.isArray(records) ? records : [])
.map(adaptNotification)
.filter(Boolean);
return {
items,
truncated: items.length > limit,
};
},
map(item) {
return item;
},
},
{
source: 'github',
label: 'GitHub alerts',
drillTo: '/devtools/github/inbox',
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
const { listActionableNotifications } = await import('./githubNotifications.js');
return listActionableNotifications({ limit });
},
map(notification) {
const sourceRef = `${notification.accountId}/${notification.threadId}`;
return {
id: `github:${sourceRef}`,
sourceRef,
title: notification.title,
summary: notification.repoFullName || 'GitHub notification needs attention',
timestamp: notification.updatedAt,
severity: notification.suspect || notification.reason === 'security_alert' ? 'high' : 'normal',
drillTo: `/devtools/github/inbox/${encodeURIComponent(notification.accountId)}/${notification.threadId}`,
nextAction: 'Review GitHub notification',
// The shared card uses the source endpoints, preserving their authority checks.
operations: [],
githubNotification: notification,
};
},
},
{
source: 'stacker',
label: 'Stacker News approvals',
drillTo: '/stacker-news',
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
return stackerNews.listPendingReviewActions({ limit });
},
map(action) {
return {
id: `stacker:${action.id}`,
title: `${action.kind.replaceAll('_', ' ')} awaiting review`,
summary: action.itemTitle || action.payload?.title || action.payload?.body?.slice(0, 200) || `Account: ${action.accountLabel}`,
timestamp: action.createdAt || null,
severity: 'normal',
drillTo: `/stacker-news/${action.accountId}/review`,
meta: { account: action.accountLabel },
};
},
},
{
source: 'x',
label: 'X drafts',
drillTo: '/x',
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
return x.listPendingReviewActions({ limit });
},
map(draft) {
return {
id: `x:${draft.id}`,
title: 'X draft awaiting review',
summary: draft.payload?.body?.slice(0, 200) || '(empty draft)',
timestamp: draft.createdAt || null,
severity: 'normal',
drillTo: `/x/${draft.accountId}/drafts`,
meta: { account: draft.accountLabel || `@${draft.username}` },
};
},
},
{
source: 'product',
label: 'Product recommendations',
drillTo: '/review',
preserveTriageActionKinds: [ACTION_KINDS.product],
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
const result = await getProductEngagement();
const actions = Array.isArray(result?.actions) ? result.actions : [];
const unavailable = [result?.post, result?.creativeCommissions]
.filter((metric) => metric?.status === 'unavailable');
if (unavailable.length) {
const reasons = unavailable
.map((metric) => metric.reason)
.filter((reason) => typeof reason === 'string' && reason.trim());
throw new Error(`Product metrics unavailable${reasons.length ? `: ${reasons.join(', ')}` : ''}`);
}
if (actions.some((action) => typeof action?.id !== 'string' || !action.id.trim())) {
throw new Error('Product recommendation identity is unavailable');
}
return {
items: actions.slice(0, limit),
truncated: actions.length > limit,
};
},
map(action) {
const metadata = action.metadata && typeof action.metadata === 'object' && !Array.isArray(action.metadata)
? action.metadata
: {};
return {
id: `product:${action.id}`,
sourceRef: action.id,
actionKind: ACTION_KINDS.product,
title: action.title || 'Product recommendation',
summary: action.detail || '',
timestamp: action.timestamp || null,
severity: ['critical', 'high', 'medium', 'normal'].includes(action.severity) ? action.severity : 'normal',
drillTo: action.link || '/review',
nextAction: 'Open',
required: false,
isRecommendation: true,
occurrence: action.occurrence ?? null,
revision: action.revision ?? null,
operations: [],
...(action.featureId ? { featureId: action.featureId } : {}),
...(action.featureLabel ? { featureLabel: action.featureLabel } : {}),
...(Object.keys(metadata).length ? { meta: metadata } : {}),
};
},
},
{
source: 'health',
label: 'Health anomalies',
drillTo: '/system-resources/overview',
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
// System/health alerts; only surface the ones worth interrupting for.
const alerts = await getAlertsCached();
const byId = new Map();
for (const alert of alerts) {
if (alert.severity !== 'critical' && alert.severity !== 'high') continue;
if (typeof alert.id !== 'string' || !alert.id.trim()) {
throw new Error('Health alert identity is unavailable');
}
// Deduplicate before the per-source cap/count. If two observations of
// a condition disagree, retain its strongest severity.
const previous = byId.get(alert.id);
if (!previous || SEVERITY_ORDER[alert.severity] < SEVERITY_ORDER[previous.severity]) {
byId.set(alert.id, alert);
}
}
const selected = [...byId.values()].slice(0, limit);
if (!selected.some(alert => alert.type === 'process_error')) return selected;
const { attachProcessInvestigations } = await import('./reviewQueueInvestigations.js');
return attachProcessInvestigations(selected);
},
// The collector owns semantic identity; the queue only namespaces it.
map(alert) {
// Surface the alert category (system_resource / goal_stall / …) so the
// user can tell at a glance what kind of anomaly it is. Absent → omitted.
const alertType = typeof alert.type === 'string' && alert.type.trim()
? alert.type.trim()
: null;
const drillTo = alert.type === 'system_resource'
? '/system-resources/overview'
: alert.link || '/system-resources/overview';
return {
id: `health:${alert.id}`,
// Process-crash alerts carry an app-scoped task; every other alert gets
// the PortOS-scoped resolve-with-agent task.
...(alert.investigationUnavailable ? {} : { investigation: alert.investigation || buildHealthAlertInvestigation(alert) }),
...(alert.investigationUnavailable ? { investigationUnavailable: alert.investigationUnavailable } : {}),
operations: [{ id: 'complete', label: 'Mark resolved', available: true }],
nextAction: 'Investigate or mark resolved',
title: alert.title || `${alert.type || 'System'} alert`,
summary: (alert.detail || alert.message || '').slice(0, 200),
timestamp: alert.timestamp || null,
severity: alert.severity === 'critical' ? 'critical' : 'high',
drillTo,
drillLabel: drillTo.startsWith('/cos/learning')
? 'Open Learning'
: drillTo.startsWith('/system-resources/overview')
? 'Open system resources'
: 'View details',
...(alertType ? { meta: { alertType } } : {})
};
}
},
{
source: 'backup',
label: 'Failed backups',
drillTo: '/settings/backup',
// Acknowledging clears the recorded failure; the next failed run re-raises it.
actionLabel: 'Done',
async resolve() {
const { getState, saveState } = await import('./backup.js');
const state = await getState();
if (!backupNeedsAttention(state)) return null;
await saveState({ status: state.lastSnapshotId ? 'ok' : 'never', error: null });
return { acknowledged: true };
},
async gather(limit = REVIEW_QUEUE_SOURCE_READ_LIMIT) {
// Disabling backups makes a past failure moot.
const { getSettings } = await import('./settings.js');
if (resolveBackupConfig((await getSettings())?.backup).enabled === false) return [];
const { getState } = await import('./backup.js');
// A backup needing acknowledgement is either a full failure (status
// 'error') or a degraded run (status 'degraded' — file rsync succeeded but
// the DB dump failed; it also carries an `error` string). Both warrant a
// queue item, but they map to different severities below.
const state = await getState();
return backupNeedsAttention(state) ? [state].slice(0, limit) : [];
},
map(state) {
// Degraded = files saved, DB dump failed → a warning, not a full failure.
const degraded = state.status === 'degraded';
return {
id: 'backup:last-run',
title: degraded ? 'Backup degraded (DB dump failed)' : 'Backup failed',
summary: (state.error || 'The most recent backup did not complete.').slice(0, 200),
timestamp: state.lastRun || null,
severity: degraded ? 'normal' : 'high',
drillTo: '/settings/backup',
drillLabel: 'Open backup settings'
};
}
}
];
const SEVERITY_ORDER = { critical: 0, high: 1, normal: 2 };
/**
* Gather one producer into normalized, capped rows. Never throws — a failing
* producer degrades to `{ items: [], total: 0, error }` so the aggregate still
* returns the healthy sources.
*
* `ctx` carries cross-producer data computed once per buildQueue (e.g. the
* active-goal options the Ask producer's goal picker offers), passed through to
* `map`. A row's `map()` may also override `promoteTargets` (the Ask row adds
* `goal` only when goals exist), so the map result is spread AFTER the
* producer-level default.
*/
const canonicalPriority = (value) => {
if (typeof value !== 'string') return null;
if (Object.hasOwn(PRIORITY_ORDER, value)) return value;
const normalized = value.toLowerCase();
if (normalized === 'urgent' || normalized === 'high') return 'HIGH';
if (normalized === 'normal' || normalized === 'medium') return 'MEDIUM';
if (normalized === 'low') return 'LOW';
return null;
};
const firstText = (...values) => values.find((value) => typeof value === 'string' && value.trim())?.trim() || null;
const isCanonicalScalar = (value) => typeof value === 'string'
|| (typeof value === 'number' && Number.isFinite(value));
const firstScalar = (...values) => values.find(isCanonicalScalar) ?? null;
function semanticOperations(producer, mapped, raw) {
if (Array.isArray(mapped.operations)) return mapped.operations;
const canResolve = Boolean(
producer.resolve
&& (!producer.actionFor || producer.actionFor(raw)),
);
const operationId = producer.source === 'ask'
? 'promote'
: canResolve
? 'resolve'
: producer.source === 'health'
? 'investigate'
: producer.source === 'backup'
? 'retry'
: 'review';
const targets = Array.isArray(mapped.promoteTargets) ? mapped.promoteTargets : null;
return [{
id: operationId,
label: OPERATION_LABELS[producer.source],
available: operationId !== 'investigate' && operationId !== 'retry',
...(targets ? { targets } : {}),
}];
}
function normalizeQueueItem(producer, raw, mapped) {
const prefix = `${producer.source}:`;
const sourceRef = firstText(
mapped.sourceRef,
raw?.id == null ? null : String(raw.id),
typeof mapped.id === 'string' && mapped.id.startsWith(prefix) ? mapped.id.slice(prefix.length) : null,
);
const priority = canonicalPriority(raw?.priority ?? mapped.priority);
const required = typeof mapped.required === 'boolean'
? mapped.required
: typeof raw?.required === 'boolean'
? raw.required
: !(raw?.recommendation === true || raw?.isRecommendation === true || raw?.optional === true);
const dueAt = firstText(raw?.dueAt, raw?.due, raw?.deadline, raw?.scheduledFor, mapped.dueAt);
const revision = firstScalar(
raw?.revision,
raw?.version,
raw?.updatedAt,
raw?.updated_at,
raw?.capturedAt,
raw?.createdAt,
raw?.timestamp,
mapped.revision,
mapped.timestamp,
);
const occurrence = firstScalar(raw?.occurrence, raw?.occurrenceId, mapped.occurrence);
const operations = semanticOperations(producer, mapped, raw);
const availableOperation = operations.find((entry) => entry.available)?.label;
return {
...mapped,
sourceRef,
actionKind: mapped.actionKind || ACTION_KINDS[producer.source],
reason: firstText(raw?.reason, mapped.summary, mapped.title),
nextAction: firstText(
raw?.nextAction,
mapped.nextAction,
mapped.action,
mapped.promoteTargets?.length ? 'Promote' : null,
availableOperation,
OPERATION_LABELS[producer.source],
),
priority,
dueAt,
revision,
occurrence,
required,
isRecommendation: typeof mapped.isRecommendation === 'boolean' ? mapped.isRecommendation : !required,
operations,
availability: mapped.availability || 'available',
available: typeof mapped.available === 'boolean' ? mapped.available : true,
};
}
/**
* The queue row id is a projection identity. Triage needs the source's
* canonical action kind/reference plus occurrence and revision so a later
* occurrence of the same source record is not hidden by an older decision.
*/
export function queueActionIdentity(item) {
const actionKind = firstText(item?.actionKind, item?.source) || 'review';
const sourceRef = firstText(item?.sourceRef, item?.id) || '';
return {
actionKey: `${actionKind}:${sourceRef}`,
occurrence: item?.occurrence ?? null,
revision: item?.revision ?? null,
};
}
const emptyTriageState = Object.freeze({
snoozedUntil: null,
dismissed: false,
deliveryGeneration: 0,
});
function queueItemSupportsTriage(item) {
if (!item || item.source === 'history' || item.availability === 'unavailable' || item.available === false) {
return false;
}
if (item.source === 'threads' && isTerminalThreadStatus(item.meta?.localStatus)) return false;
if (item.source === 'todo' && item.meta?.status && item.meta.status !== 'pending') return false;
return true;
}
function triageOperationsFor(item, { snoozed = false } = {}) {
if (!queueItemSupportsTriage(item)) return [];
return [
snoozed
? { id: 'unsnooze', label: 'Unsnooze', available: true }
: { id: 'snooze', label: 'Snooze', available: true },
...(item.isRecommendation === true
? [{ id: 'dismiss', label: 'Dismiss', available: true }]
: []),
];
}
/**
* Apply durable presentation markers without changing the source-owned row.
* This is exported as a pure boundary so expiry and occurrence rollover can
* be tested with an injected clock.
*/
export function applyQueueTriage(items, entries = [], now = new Date(), { includeSnoozed = false } = {}) {
const byIdentity = new Map(
entries
.map((entry) => {
const normalized = reviewQueueTriageStore.normalizeReviewQueueTriage(entry);
return normalized ? [reviewQueueTriageStore.triageIdentityKey(normalized), normalized] : null;
})
.filter(Boolean),
);
const nowMs = now instanceof Date ? now.getTime() : Date.parse(now);
const currentTime = Number.isFinite(nowMs) ? nowMs : Date.now();
return items.flatMap((item) => {
const identity = queueActionIdentity(item);
const state = byIdentity.get(reviewQueueTriageStore.triageIdentityKey(identity)) || emptyTriageState;
const delivery = byIdentity.get(reviewQueueTriageStore.triageIdentityKey({
actionKey: `delivery:${item.id}`, occurrence: item.occurrence, revision: '',
}));
const snoozedUntilMs = state.snoozedUntil ? Date.parse(state.snoozedUntil) : NaN;
const snoozed = Number.isFinite(snoozedUntilMs) && snoozedUntilMs > currentTime;
const dismissed = state.dismissed && item.isRecommendation === true;
if (dismissed || (includeSnoozed ? !snoozed : snoozed)) return [];
return [{
...item,
triage: {
snoozedUntil: state.snoozedUntil,
dismissed: state.dismissed,
deliveryGeneration: delivery?.deliveryGeneration ?? state.deliveryGeneration,
},
triageOperations: triageOperationsFor(item, { snoozed }),
}];
});
}
/**
* Gather one producer into normalized rows. A producer may return either an
* array or `{ items, truncated }` when it filtered a bounded upstream read.
* Totals are nullable whenever the read filled its bound: the collected rows
* are a lower bound, not evidence that the source is exhausted.
*/
async function gatherProducer(producer, ctx = {}) {
const gathered = await producer.gather(REVIEW_QUEUE_SOURCE_PROBE_LIMIT, ctx);
const descriptor = Array.isArray(gathered) ? { items: gathered } : gathered;
const rawItems = Array.isArray(descriptor?.items) ? descriptor.items : [];
const truncated = descriptor?.truncated === true || rawItems.length > REVIEW_QUEUE_SOURCE_READ_LIMIT;
const list = rawItems.slice(0, REVIEW_QUEUE_SOURCE_READ_LIMIT);
const items = list.map((item, index) => {
const mapped = {
source: producer.source,
sourceLabel: producer.label,
...(Array.isArray(producer.promoteTargets) && producer.promoteTargets.length
? { promoteTargets: producer.promoteTargets }
: {}),
...producer.map(item, index, ctx),
...(producer.actionLabel && producer.resolve
&& (!producer.actionFor || producer.actionFor(item))
? { action: producer.actionLabel }
: {})
};
return normalizeQueueItem(producer, item, mapped);
});
return {
items,
total: truncated ? null : list.length,
lowerBound: list.length,
truncation: truncated,
preserveTriageActionKinds: Array.isArray(descriptor?.preserveTriageActionKinds)
? descriptor.preserveTriageActionKinds
: (producer.preserveTriageActionKinds || []),
};
}
const PRODUCERS_BY_SOURCE = Object.fromEntries(PRODUCERS.map(p => [p.source, p]));
const queueSnapshots = new Map();
const stableQueryValue = (value) => {
if (Array.isArray(value)) return value.map(stableQueryValue);
if (value && typeof value === 'object') {
return Object.fromEntries(Object.entries(value)
.sort(([a], [b]) => a.localeCompare(b))
.map(([key, child]) => [key, stableQueryValue(child)]));
}
return value;
};
const queryKeyFor = (query = {}) => JSON.stringify(stableQueryValue(query));
const invalidCursor = (message = 'Invalid review queue cursor') => {
throw new ServerError(message, { status: 400, code: 'INVALID_CURSOR' });
};
function encodeQueueCursor(snapshotId, offset) {
return Buffer.from(JSON.stringify({ v: 1, snapshotId, offset }), 'utf8').toString('base64url');
}
function decodeQueueCursor(cursor) {
const decoded = Buffer.from(String(cursor), 'base64url').toString('utf8');
const payload = safeJSONParse(decoded, null, { allowArray: false });
if (!payload || payload.v !== 1 || typeof payload.snapshotId !== 'string' || !payload.snapshotId
|| !Number.isSafeInteger(payload.offset) || payload.offset < 0) {
invalidCursor();
}
return payload;
}
function pruneQueueSnapshots(now = Date.now()) {
for (const [id, snapshot] of queueSnapshots) {
if (snapshot.expiresAt <= now) queueSnapshots.delete(id);
}
}
// Test seam: snapshots are intentionally process-local and short-lived.
export function __resetQueueSnapshots() {
queueSnapshots.clear();
clearTimeout(clockInvalidation);
clockInvalidation = null;
clockInvalidationAt = Infinity;
}
/**
* Accept/promote a single queue row in place. `queueItemId` is the row's
* normalized id (`<source>:<rawId>`); we split on the FIRST colon so raw ids
* that themselves contain colons survive. Throws a 4xx ServerError when the
* source is unknown, has no inline resolve, or the underlying primitive can't
* find the record — so the route surfaces a clean status instead of a 500.
*/
async function resolveMemoryAction(id, operation) {
const memory = await import('./memory.js');
const result = await memory[operation === 'approve' ? 'approveMemory' : 'rejectMemory'](id);
if (result?.success === false || result?.error) {
const notFound = /not found/i.test(String(result.error || ''));
if (notFound) {
// The memory is already gone, so its queue projections are stale either way.
await reviewService.dismissByReferenceId(id).catch((err) => {
console.error(`⚠️ Review queue: stale memory projection cleanup failed: ${err.message}`);
});
await notifications.removeByMetadata('memoryId', id).catch(() => {});
// Rejecting a deleted memory is the desired end state; approving one is not.
if (operation === 'reject') return { success: true, alreadyResolved: true };
}
throw new ServerError(result.error || `Memory ${operation} failed`, {
status: notFound ? 404 : 409,
code: notFound ? 'NOT_FOUND' : 'CONFLICT',
});
}
return result;
}
async function resolveCosApproval(id) {
const result = await cosTaskStore.approveTask(id);
if (result && result.error) throw new ServerError(result.error, { status: 409, code: 'CONFLICT' });
// Older installs may still have a stored CoS approval row from the former
// task:ready bridge. The owning approval succeeded, so retire that legacy
// projection by reference without allowing generic Review completion to
// mutate the obligation directly.
await reviewService.dismissByReferenceId(id).catch((err) => {
console.error(`⚠️ Review queue: legacy CoS projection cleanup failed: ${err.message}`);
});
return result;
}
async function resolveThreadAction(id, status) {
const result = await brainStorage.updateWith('threads', id, (fresh) => {
const terminal = isTerminalThreadStatus(status);
return {
status,
// Keep Brain's closedAt contract when an Actions button changes only the
// local thread state. Refs and externalState are deliberately untouched.
closedAt: terminal
? (isTerminalThreadStatus(fresh.status) && fresh.closedAt
? fresh.closedAt
: new Date().toISOString())
: null,
};
});
return result;
}
/**
* A required action item may reach the queue as either a stored Review item
* (`review.createItem`, category-based) or a notification (type-based, see
* `NOTIFICATION_ACTION_POLICY`) — both are keyed under the same `actionSource`
* vocabulary, and a queue row never records which origin produced it. Resolve
* both projections so "Mark resolved" retires the hold regardless of which
* producer raised it.
*/
async function resolveNotificationHold(actionSource, sourceRef) {
if (!sourceRef) return [];
const { notificationReference } = await import('./reviewActionAdapters.js');
const records = await notifications.getNotifications({ includeHidden: true });
const matches = (Array.isArray(records) ? records : []).filter((notification) => {
const policy = NOTIFICATION_ACTION_POLICY[notification.type];
return policy?.actionSource === actionSource && notificationReference(notification, policy) === sourceRef;
});
await Promise.all(matches.map((notification) => notifications.removeNotification(notification.id)));
return matches;
}
/**
* Owning primitive for the sourceRef-keyed required holds that have no
* domain-specific resolution of their own (goal-fidelity, plan questions,
* content reviews, paused autopilot) — a permanent acknowledge/dismiss, not a
* change to what the underlying condition means (#8007).
*/
async function resolveSourceOwnedHold(actionSource, sourceRef) {
const [reviewItems, notificationMatches] = await Promise.all([
reviewService.dismissByReferenceId(sourceRef),
resolveNotificationHold(actionSource, sourceRef),
]);
const resolvedCount = (reviewItems?.length || 0) + notificationMatches.length;
return resolvedCount > 0 ? { resolved: resolvedCount } : null;
}
const SOURCE_ACTIONS = Object.freeze({
memory: Object.freeze({
approve: (id) => resolveMemoryAction(id, 'approve'),
reject: (id) => resolveMemoryAction(id, 'reject'),
}),
cos: Object.freeze({
approve: resolveCosApproval,
}),
threads: Object.freeze({
complete: (id) => resolveThreadAction(id, 'done'),
reopen: (id) => resolveThreadAction(id, 'open'),
}),
todo: Object.freeze({
complete: (id) => reviewService.completeItem(id),
reopen: (id) => reviewService.reopenItem(id),
}),
health: Object.freeze({
complete: async (id) => {
const { resolveHealthAlert } = await import('./proactiveAlertSources.js');
const result = await resolveHealthAlert(id);
if (result) __resetAlertsCache();
return result;
},
}),
feedback: Object.freeze({
rate: async (id, input) => {
const { submitAgentFeedback } = await import('./cosAgentFeedback.js');
return submitAgentFeedback(id, input);
},
}),
'goal-fidelity': Object.freeze({
complete: (id) => resolveSourceOwnedHold('goal-fidelity', id),
}),
plan: Object.freeze({
complete: (id) => resolveSourceOwnedHold('plan', id),
}),
content: Object.freeze({
complete: (id) => resolveSourceOwnedHold('content', id),
}),
autopilot: Object.freeze({
complete: (id) => resolveSourceOwnedHold('autopilot', id),
}),
review: Object.freeze({
complete: (id) => reviewService.dismissItem(id),
}),
});
export async function resolveQueueItem(queueItemId, operation = 'resolve', input = {}) {
const sep = String(queueItemId).indexOf(':');
const source = sep === -1 ? queueItemId : queueItemId.slice(0, sep);
const rawId = sep === -1 ? '' : queueItemId.slice(sep + 1);
if (operation !== 'resolve') {
const resolver = SOURCE_ACTIONS[source]?.[operation];
if (!resolver) {
throw new ServerError(`No ${operation} action for source "${source}"`, {
status: 400,
code: 'BAD_REQUEST',
});
}
const result = await resolver(rawId, input);
if (result == null) {
throw new ServerError(`${source} item not found: ${rawId}`, { status: 404, code: 'NOT_FOUND' });
}
await clearQueueTriageMarkersForItem(queueItemId);
return { source, id: queueItemId, operation, resolved: true };
}
const producer = PRODUCERS_BY_SOURCE[source];
if (!producer || !producer.resolve) {
throw new ServerError(`No inline action for source "${source}"`, { status: 400, code: 'BAD_REQUEST' });
}
const result = await producer.resolve(rawId);
// Most resolve primitives return null when the record is already gone.
if (result == null) {
throw new ServerError(`${producer.label} item not found: ${rawId}`, { status: 404, code: 'NOT_FOUND' });
}
await clearQueueTriageMarkersForItem(queueItemId);
return { source, id: queueItemId, resolved: true };
}
const REVIEW_QUEUE_TRIAGE_OPERATIONS = new Set(['snooze', 'unsnooze', 'dismiss']);
function queueSourceAndRawId(queueItemId) {
const value = String(queueItemId || '');
const sep = value.indexOf(':');
return {
source: sep === -1 ? value : value.slice(0, sep),
rawId: sep === -1 ? '' : value.slice(sep + 1),
};
}
const TRIAGE_ACTION_KINDS_BY_SOURCE = Object.freeze({
...ACTION_KINDS,
cos: ['cos.approve', 'task.approval'],
memory: 'memory.approval',
'goal-fidelity': 'goal-fidelity.review',
plan: 'plan.question',
autopilot: 'autopilot.resume',
content: 'content.review',
});
async function clearQueueTriageMarkersForItem(queueItemId) {
const { source, rawId } = queueSourceAndRawId(queueItemId);
const configuredKinds = TRIAGE_ACTION_KINDS_BY_SOURCE[source];
if (!configuredKinds || !rawId) return;
const actionKinds = Array.isArray(configuredKinds) ? configuredKinds : [configuredKinds];
const actionKeys = new Set(actionKinds.map((actionKind) => `${actionKind}:${rawId}`));
const entries = await reviewQueueTriageStore.listReviewQueueTriage();
if (!Array.isArray(entries)) return;
for (const entry of entries) {
if (actionKeys.has(entry.actionKey)) await reviewQueueTriageStore.removeReviewQueueTriage(entry);
}
}
/**
* Apply a presentation-only queue decision after re-reading the live source.
* The mutation never accepts source identity, occurrence, or capability from
* the client; those values come from the fresh normalized queue row.
*/
export async function triageQueueItem(queueItemId, operation, input = {}, { now: injectedNow } = {}) {
if (!REVIEW_QUEUE_TRIAGE_OPERATIONS.has(operation)) {
throw new ServerError(`Unsupported review queue triage operation "${operation}"`, {
status: 400,
code: 'BAD_REQUEST',
});
}
const now = injectedNow instanceof Date && Number.isFinite(injectedNow.getTime())
? injectedNow
: new Date();
let snoozedUntil = null;
if (operation === 'snooze') {
const parsed = new Date(input?.snoozedUntil || '');
if (Number.isNaN(parsed.getTime()) || parsed.getTime() <= now.getTime()) {
throw new ServerError('snoozedUntil must be a future ISO timestamp', {
status: 400,
code: 'VALIDATION_ERROR',
});
}
if (parsed.getTime() - now.getTime() > MAX_REVIEW_QUEUE_SNOOZE_MS) {
throw new ServerError('snoozedUntil cannot be more than 30 days in the future', {
status: 400,
code: 'VALIDATION_ERROR',
});
}
snoozedUntil = parsed.toISOString();
} else if (input?.snoozedUntil !== undefined) {
throw new ServerError('snoozedUntil is only valid for the snooze operation', {
status: 400,
code: 'VALIDATION_ERROR',
});
}
const { source } = queueSourceAndRawId(queueItemId);
const queue = await gatherFullQueue({}, { applyTriageState: false, now });
const sourceDescriptor = queue.sources[source];
if (sourceDescriptor?.error) {
throw new ServerError(`Cannot triage ${source} while its source is unavailable`, {
status: 503,
code: 'SOURCE_UNAVAILABLE',
});
}
const item = queue.items.find((candidate) => candidate.id === queueItemId);
if (!item) {
throw new ServerError(`Review queue item not found: ${queueItemId}`, { status: 404, code: 'NOT_FOUND' });
}
if (operation === 'dismiss' && item.isRecommendation !== true) {
throw new ServerError('Only optional recommendations can be dismissed from the queue', {
status: 400,
code: 'CAPABILITY_UNAVAILABLE',
});
}
const identity = queueActionIdentity(item);
const existingEntries = await reviewQueueTriageStore.listReviewQueueTriage();
const identityKey = reviewQueueTriageStore.triageIdentityKey(identity);
const existing = existingEntries.find((entry) => (
reviewQueueTriageStore.triageIdentityKey(entry) === identityKey
));
const next = {
...identity,
snoozedUntil: existing?.snoozedUntil || null,
dismissed: existing?.dismissed === true,
deliveryGeneration: existing?.deliveryGeneration || 0,
};
if (operation === 'snooze') next.snoozedUntil = snoozedUntil;
if (operation === 'unsnooze') next.snoozedUntil = null;
if (operation === 'dismiss') next.dismissed = true;
if (!next.snoozedUntil && !next.dismissed && next.deliveryGeneration === 0) {
await reviewQueueTriageStore.removeReviewQueueTriage(next);
} else {
await reviewQueueTriageStore.upsertReviewQueueTriage(next);
}
__resetQueueSnapshots();
return {
id: queueItemId,
operation,
triaged: true,
triage: {
snoozedUntil: next.snoozedUntil,
dismissed: next.dismissed,
deliveryGeneration: next.deliveryGeneration,
},
};
}
// Targets the queue can promote an Ask answer into directly. brain/task pick
// the latest assistant turn with no extra input; goal additionally needs a
// goalId (the row carries `goalOptions` so the UI can supply it). Goal is in
// the allow-list even though the row only advertises it when active goals
// exist — a request with a stale goalId still validates here and 404s in the
// orchestration if the goal is gone.
const ASK_PROMOTE_TARGETS = ['brain', 'task', 'goal'];
/**
* Promote an Ask queue row's latest assistant answer into a chosen target
* (brain/task/goal). `queueItemId` is the row id (`ask:<conversationId>`);
* `target` must be one of `ASK_PROMOTE_TARGETS`. For the `goal` target,
* `goalId` is required (validated, then resolved against the goal store).
* The service picks the conversation's latest assistant turn so the client
* doesn't carry turn ids — a conversation with no assistant answer 404s.
* Reuses the same promote orchestration the per-turn Ask route uses.
*/
export async function promoteAskQueueItem(queueItemId, target, goalId) {
const sep = String(queueItemId).indexOf(':');
const source = sep === -1 ? queueItemId : queueItemId.slice(0, sep);
const conversationId = sep === -1 ? '' : queueItemId.slice(sep + 1);
if (source !== 'ask') {
throw new ServerError(`Promote is only supported for Ask rows, got "${source}"`, { status: 400, code: 'BAD_REQUEST' });
}
if (!ASK_PROMOTE_TARGETS.includes(target)) {
throw new ServerError(`Unsupported promote target "${target}" for Ask`, { status: 400, code: 'BAD_REQUEST' });
}
if (target === 'goal' && !goalId) {
throw new ServerError('goalId is required to promote into a goal', { status: 400, code: 'VALIDATION_ERROR' });
}
const { promoteLatestAssistantTurn } = await import('./askPromote.js');
const result = await promoteLatestAssistantTurn({ conversationId, target, goalId });
await clearQueueTriageMarkersForItem(queueItemId);
return { source, id: queueItemId, promoted: true, target: result.target, ref: result.ref };
}
const validDateMs = (value) => {
const parsed = Date.parse(value || '');
return Number.isFinite(parsed) ? parsed : null;
};
function compareQueueItems(a, b, now = Date.now()) {
const required = Number(Boolean(b.required)) - Number(Boolean(a.required));
if (required !== 0) return required;
const severity = (SEVERITY_ORDER[a.severity] ?? 2) - (SEVERITY_ORDER[b.severity] ?? 2);
if (severity !== 0) return severity;
const dueA = validDateMs(a.dueAt);
const dueB = validDateMs(b.dueAt);
const dueBucket = (due) => due === null ? 2 : due < now ? 0 : 1;
const dueClass = dueBucket(dueA) - dueBucket(dueB);
if (dueClass !== 0) return dueClass;
if (dueA !== null && dueB !== null && dueA !== dueB) return dueA - dueB;
const priority = (PRIORITY_ORDER[a.priority] ?? 3) - (PRIORITY_ORDER[b.priority] ?? 3);
if (priority !== 0) return priority;
return String(a.id || '').localeCompare(String(b.id || ''));
}
function deduplicateItems(items) {
const byId = new Map();
for (const item of items) {
const previous = byId.get(item.id);
if (!previous || compareQueueItems(item, previous) < 0) byId.set(item.id, item);
}
return [...byId.values()];
}
function queueCounts(items) {
const counts = { total: items.length, critical: 0, high: 0 };
for (const item of items) {
if (item.severity === 'critical') counts.critical++;
else if (item.severity === 'high') counts.high++;
}
return counts;
}
function sourceShownCounts(items) {
const shown = {};
for (const item of items) shown[item.source] = (shown[item.source] || 0) + 1;
return shown;
}
async function readQueueTriageForProjection({
now = new Date(),
currentItems = [],
pruneOrphans = false,
preserveTriageActionKinds = [],
} = {}) {
const entries = await reviewQueueTriageStore.listReviewQueueTriage();
if (!Array.isArray(entries)) return [];
const nowMs = now instanceof Date && Number.isFinite(now.getTime()) ? now.getTime() : Date.now();
for (const entry of entries) {
if (!entry.dismissed) scheduleQueueClockInvalidation(Date.parse(entry.snoozedUntil));
}
const preservedKinds = new Set(preserveTriageActionKinds);
const currentKeys = pruneOrphans
? new Set(currentItems.map((item) => reviewQueueTriageStore.triageIdentityKey(queueActionIdentity(item))))
: null;
const currentDeliveryIds = pruneOrphans
? new Set(currentItems.map((item) => String(item.id)))
: null;
const removableKeys = new Set();
for (const entry of entries) {
// Acknowledgement baselines must survive the disappearance of their alert.
if (entry.actionKey.startsWith(HEALTH_RESOLUTION_PREFIX)) continue;
const key = reviewQueueTriageStore.triageIdentityKey(entry);
const expired = entry.snoozedUntil && Date.parse(entry.snoozedUntil) <= nowMs;
const unused = expired && entry.dismissed !== true && entry.deliveryGeneration === 0;
const actionKind = typeof entry.actionKey === 'string' ? entry.actionKey.split(':')[0] : null;
const deliveryId = entry.delivery && typeof entry.actionKey === 'string'
? entry.actionKey.startsWith('delivery:') ? entry.actionKey.slice('delivery:'.length) : null
: null;
const orphaned = currentKeys && (
(entry.delivery && deliveryId && !currentDeliveryIds.has(deliveryId))
|| (!entry.delivery && !currentKeys.has(key) && !preservedKinds.has(actionKind))
);
if (unused || orphaned) removableKeys.add(key);
}
for (const entry of entries) {
if (removableKeys.has(reviewQueueTriageStore.triageIdentityKey(entry))) {
await reviewQueueTriageStore.removeReviewQueueTriage(entry);
}
}
return entries.filter((entry) => !removableKeys.has(reviewQueueTriageStore.triageIdentityKey(entry)));
}
async function gatherFullQueue(query = {}, { applyTriageState = true, now = new Date() } = {}) {
// Fetch active goals once (not per Ask row) so the goal picker on Ask rows
// has targets. A failure here degrades to no goal targets, not a sunk queue.
const goalOptions = await getActiveGoalOptions();
const view = typeof query.view === 'string' && query.view ? query.view : null;
const timezone = view === 'today'
? await getUserTimezone().catch((err) => {
console.error(`⚠️ Review queue: timezone read failed: ${err.message}`);
return 'UTC';
})
: 'UTC';
const clock = now instanceof Date && Number.isFinite(now.getTime()) ? now : new Date();
if (view === 'today') {
const tomorrow = new Date(`${todayInTimezone(timezone, clock)}T12:00:00.000Z`);
tomorrow.setUTCDate(tomorrow.getUTCDate() + 1);
scheduleQueueClockInvalidation(anchorLocalMidnightUtc(tomorrow.toISOString().slice(0, 10), timezone));
}
const ctx = { goalOptions, view, timezone, now: clock };
const visibleProducers = PRODUCERS.filter((producer) => visibleInLiveViews(producer, view));
const results = await Promise.all(visibleProducers.map(async (producer) => {
return gatherProducer(producer, ctx)
.then((result) => ({ source: producer.source, label: producer.label, ...result, error: null }))
.catch((err) => {
const message = String(err?.message || err || 'Source read failed').slice(0, 300);
console.error(`❌ Review queue: ${producer.source} source failed: ${message}`);
return {
source: producer.source,
label: producer.label,
items: [],
total: null,
lowerBound: 0,
truncation: false,
preserveTriageActionKinds: producer.preserveTriageActionKinds || [],
error: message,
};
});
}));
let items = deduplicateItems(results.flatMap((result) => result.items));
if (applyTriageState) {
const sourceReadComplete = results.every((result) => result.error === null && !result.truncation);
const preserveTriageActionKinds = results.flatMap((result) => result.preserveTriageActionKinds || []);
const triageEntries = await readQueueTriageForProjection({
now: clock,
currentItems: items,
pruneOrphans: sourceReadComplete && (view === null || view === 'all'),
preserveTriageActionKinds,
});
items = applyQueueTriage(items, triageEntries, clock, { includeSnoozed: view === 'snoozed' });
}
items.sort((a, b) => compareQueueItems(a, b, clock.getTime()));
const shownCounts = sourceShownCounts(items);
const sources = {};
const totalsBySource = {};
for (const result of results) {
const shown = shownCounts[result.source] || 0;
const knownTotal = result.error === null && !result.truncation && Number.isSafeInteger(result.total)
? shown
: null;
totalsBySource[result.source] = knownTotal;
sources[result.source] = {
label: result.label,
total: knownTotal,
shown,
error: result.error,
availability: result.error ? 'unavailable' : 'available',
available: !result.error,
truncation: Boolean(result.truncation),
lowerBound: result.error ? 0 : shown,
};
}
const partial = results.some((result) => result.error || result.truncation);
return {
items,
total: partial ? null : items.length,
totalsBySource,
sources,
nextCursor: null,
partial,
counts: queueCounts(items),
generatedAt: clock.toISOString(),
};
}
function pageSources(sources, pageItems) {
const shown = sourceShownCounts(pageItems);
return Object.fromEntries(Object.entries(sources).map(([source, descriptor]) => [source, {
...descriptor,
shown: shown[source] || 0,
}]));
}
function pageFromSnapshot(snapshot, offset) {
if (offset > snapshot.items.length) invalidCursor('Review queue cursor offset is outside the snapshot');
const items = snapshot.items.slice(offset, offset + snapshot.pageSize);
const nextOffset = offset + items.length;
return {
items,
total: snapshot.total,
totalsBySource: snapshot.totalsBySource,
sources: pageSources(snapshot.sources, items),
nextCursor: nextOffset < snapshot.items.length ? encodeQueueCursor(snapshot.id, nextOffset) : null,
partial: snapshot.partial,
counts: snapshot.counts,
generatedAt: snapshot.generatedAt,
};
}
function validatePageSize(limit) {
if (limit === undefined || limit === null) return null;
if (!Number.isSafeInteger(limit) || limit < 1 || limit > REVIEW_QUEUE_MAX_PAGE_SIZE) {
throw new ServerError(`Review queue limit must be an integer from 1 to ${REVIEW_QUEUE_MAX_PAGE_SIZE}`, {
status: 400,
code: 'VALIDATION_ERROR',
});
}
return limit;
}
function saveQueueSnapshot(queue, queryKey, pageSize) {
const now = Date.now();
pruneQueueSnapshots(now);
while (queueSnapshots.size >= REVIEW_QUEUE_MAX_SNAPSHOTS) {
queueSnapshots.delete(queueSnapshots.keys().next().value);
}
const id = randomUUID();
queueSnapshots.set(id, {
id,
...queue,
pageSize,
queryKey,
expiresAt: now + REVIEW_QUEUE_SNAPSHOT_TTL_MS,
});
return queueSnapshots.get(id);
}
/**
* Build the cross-domain review queue. A request without pagination parameters
* retains the original full-list response. Passing `limit` opts into a
* short-lived process-local snapshot with an opaque offset cursor.
*/
export async function buildQueue({ limit, cursor, query = {}, now } = {}) {
const requestedLimit = validatePageSize(limit);
const queryKey = queryKeyFor(query);
if (cursor !== undefined && cursor !== null) {
const payload = decodeQueueCursor(cursor);
pruneQueueSnapshots();
const snapshot = queueSnapshots.get(payload.snapshotId);
if (!snapshot || snapshot.expiresAt <= Date.now()) {
queueSnapshots.delete(payload.snapshotId);
throw new ServerError('Review queue snapshot expired; restart pagination', {
status: 409,
code: 'CURSOR_EXPIRED',
});
}
if (snapshot.queryKey !== queryKey) {
throw new ServerError('Review queue query changed; restart pagination', {
status: 400,
code: 'CURSOR_QUERY_MISMATCH',
});
}
if (requestedLimit !== null && requestedLimit !== snapshot.pageSize) {
throw new ServerError('Review queue page size changed; restart pagination', {
status: 400,
code: 'CURSOR_QUERY_MISMATCH',
});
}
return pageFromSnapshot(snapshot, payload.offset);
}
const queue = await gatherFullQueue(query, { now });
if (requestedLimit === null) return queue;
const snapshot = saveQueueSnapshot(queue, queryKey, requestedLimit);
return pageFromSnapshot(snapshot, 0);
}