Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import type { ReactNode } from 'react';
import { useApi } from './ApiContext';
import type { InboxSession } from './ApiContext';
import { WorkbenchInboxContext, type InboxState } from './WorkbenchInboxContext';
import { useNotificationPreferences } from './NotificationPreferencesContext';
import { useBotRoster } from './BotRosterContext';
import { badgeTotal as loudUnread, unreadByCategory as splitUnread } from '../lib/notificationPreferences';
import { sessionActivityInboxAction } from '../lib/inboxActivity';
import { syncFaviconBadge } from '../lib/faviconBadge';
import { useConsumerActivation } from '../lib/useConsumerActivation';
import { onPageReactivated } from '../lib/pageActivity';
import {
createWorkbenchSessionReadOwnership,
type WorkbenchSessionReadStamp,
} from '../lib/workbenchSessionReadOwnership';
const PAGE_SIZE = 30;
// Sort matches the backend keyset order: last activity (any author) desc, then
// session_id desc as the stable tie-break, so client upserts stay consistent
// with server-paginated pages.
const byActivityDesc = (a: InboxSession, b: InboxSession): number => {
if (a.last_activity_at !== b.last_activity_at) {
return a.last_activity_at < b.last_activity_at ? 1 : -1;
}
if (a.session_id === b.session_id) return 0;
return a.session_id < b.session_id ? 1 : -1;
};
const upsertSession = (list: InboxSession[], row: InboxSession): InboxSession[] => {
const next = list.filter((s) => s.session_id !== row.session_id);
next.push(row);
next.sort(byActivityDesc);
return next;
};
const appendPage = (prev: InboxSession[], page: InboxSession[]): InboxSession[] => {
const incoming = new Map(page.map((row) => [row.session_id, row]));
const merged = prev.map((row) => incoming.get(row.session_id) ?? row);
const seen = new Set(prev.map((row) => row.session_id));
for (const row of page) if (!seen.has(row.session_id)) merged.push(row);
merged.sort(byActivityDesc);
return merged;
};
type TargetedInboxSnapshot = {
row: InboxSession | null;
};
/** Provider that owns the Inbox state shared across WorkbenchSidebar + InboxPage.
*
* Connects to ``/api/events`` and updates the per-session feed in place:
* ``inbox.session.updated``
* upserts + re-sorts a card (the realtime "bump to top"), ``inbox.unread.changed``
* refreshes the unread map after a mark-read elsewhere. Each (re)connect also
* does a full ``refresh()`` so events missed while the socket was down (the
* broker has no replay) are recovered. The provider value is memoized per
* [[feedback_react_context_value_memoize]] so consumer ``useEffect`` hooks that
* depend on context functions don't re-fire on every parent render. */
export const WorkbenchInboxProvider = ({ children }: { children: ReactNode }) => {
const api = useApi();
// Two different appetites behind one provider: the unread map badges the
// favicon and the app icon on every route, while the paged feed is rendered
// only by the sidebar and the Inbox page. Splitting them is what lets an admin
// route keep its badge without paying for 30 rows of feed it never shows.
const { active: feedActive, isActive: isFeedActive, activate: activateFeed } =
useConsumerActivation();
const [inboxSessions, setInboxSessions] = useState<InboxSession[]>([]);
const [unreadBySession, setUnreadBySession] = useState<Record<string, number>>({});
// Becomes true the first time the server hands us an authoritative whole-account
// unread map. Until then ``totalUnread`` is only the empty-map default of 0,
// which must NOT drive the app-icon badge: the push service worker may have set
// a real badge while the app was closed, so a premature ``clearAppBadge()`` on a
// slow or failed initial load would wipe a still-accurate count. (The realtime
// session.updated/archived merges adjust a prior map, so they are not themselves
// a first authoritative load and deliberately do not flip this.)
const [unreadLoaded, setUnreadLoaded] = useState(false);
const [nextCursor, setNextCursor] = useState<string | null>(null);
const [loading, setLoading] = useState(false);
const [loadingMore, setLoadingMore] = useState(false);
// Mirror the cursor into a ref so ``loadMore`` can read the latest value
// without re-creating its identity (and the context value) on every page.
const cursorRef = useRef<string | null>(null);
cursorRef.current = nextCursor;
const applyNextCursor = useCallback((cursor: string | null) => {
// A queued feed intent may start from the completing request's finally
// block, before React renders the state update. Commit both owners together
// so that intent always reads the logically latest cursor.
cursorRef.current = cursor;
setNextCursor(cursor);
}, []);
// Mirror the loaded feed so ``reconcile`` can size its re-read to the current
// window without depending on (and re-identifying with) ``inboxSessions``.
const inboxSessionsRef = useRef<InboxSession[]>([]);
inboxSessionsRef.current = inboxSessions;
// Only the very first mount does the destructive first-page refresh; every
// later effect rerun — such as an ``api`` identity change after a locale switch
// — reconciles the loaded window instead, so a non-resume
// rerun never collapses a multi-page feed back to page one.
const initialFetched = useRef(false);
// Every Inbox read shares one ordering fence. This covers page-one refresh,
// cursor reads, resume reconcile, and the targeted foreground-restore read.
const readOwnershipRef = useRef(createWorkbenchSessionReadOwnership());
// Broad reads and cursor reads both own the feed. Serialize every feed read
// and preserve trailing intents so response completion order cannot discard a
// recovery snapshot or a page the user asked to load.
const refreshPendingRef = useRef(false);
const reconcilePendingRef = useRef(false);
const loadMorePendingRef = useRef(false);
const broadReadInFlightRef = useRef(false);
const cursorReadsInFlightRef = useRef(0);
const refreshRunnerRef = useRef<() => void>(() => {});
const reconcileRunnerRef = useRef<() => void>(() => {});
const loadMoreRunnerRef = useRef<() => void>(() => {});
const reconcileSessionRef = useRef<(sessionId: string) => void>(() => {});
const refreshLoadingGenerationRef = useRef(0);
const loadMoreLoadingGenerationRef = useRef(0);
// Targeted foreground restores own one session independently from the
// windowed feed. Keep their latest committed values so a later whole-feed
// replacement cannot erase a restored card merely because the row sorts
// outside the page; a later broad omission revalidates them by exact id.
// Counts-only reads own no feed state, so they never join the feed read
// intents above. They still serialize against themselves: a resume fires
// visibilitychange, focus and online together, and one map is enough.
const unreadReadInFlightRef = useRef(false);
const unreadReadPendingRef = useRef(false);
const unreadReadRunnerRef = useRef<() => void>(() => {});
// Every read currently in flight that would commit a WHOLE account map: the two
// broad feed reads and the counts-only read. Membership alone proves nothing —
// what makes one a payer is that it is still current for ``inbox-unread``, which
// is exactly what raising the debt takes away. Kept as stamps rather than a
// counter for that reason.
const wholeUnreadReadsInFlightRef = useRef<Set<WorkbenchSessionReadStamp>>(new Set());
// ``flushFeedReadIntent`` is the one place a scheduled payer can disappear, and it
// is defined above the settle it then has to re-run. Same runner-ref shape as the
// reads below.
const settleWholeUnreadRef = useRef<() => void>(() => {});
// "No whole-account map currently describes this account." The unread map is the
// one thing here with no demand gate at all — every route badges it — so this is
// the debt that keeps it live independently of which read was supposed to pay it:
// true until one arrives, true again whenever something voids the scope the current
// map described or moves counts it cannot describe (see ``oweWholeUnread`` for the
// edges). Every read that can deliver a whole map is allowed to fail, be
// invalidated, or be dropped by the demand gate; what must not happen is the debt
// being forgotten with it. Distinct from ``unreadLoaded``, which is one-way and
// answers a different question (may this document touch the OS badge at all).
//
// A ref and not state, because it is read where it is spent: ``settleWholeUnread``
// runs from the producers as well as from an effect, so it cannot wait a render to
// learn whether anything is still owed — and once the producers pay it themselves,
// a re-render on the same fact would be a second owner of that payment.
const wholeUnreadOwedRef = useRef(true);
const targetedSnapshotsRef = useRef<Map<string, TargetedInboxSnapshot>>(new Map());
const targetedReadInFlightRef = useRef<Set<string>>(new Set());
const targetedReadPendingRef = useRef<Set<string>>(new Set());
const committedWholeUnreadGenerationRef = useRef(0);
const flushFeedReadIntent = useCallback(() => {
if (broadReadInFlightRef.current || cursorReadsInFlightRef.current > 0) return;
// Every intent queued here reads the FEED, so the demand gate applies to it
// exactly as it applies to a first read: with no feed consumer left, a
// 30-row page would be fetched for a document that renders a badge. Dropping
// it loses nothing, because activation re-reads unconditionally (page one
// when nothing was loaded, reconcile otherwise) — the same argument that
// lets ``onConnected`` return early. It matters most right after
// ``discardAuthorizedFeed``: invalidating the read in flight is itself what
// queues a replacement refresh, which would repopulate the rows that branch
// just dropped, off-route and in parallel with the counts-only read.
//
// That argument covers the FEED half of the dropped read. The whole-account
// unread map it was also carrying is a different matter, because no route is
// exempt from badging that — the debt is ``wholeUnreadOwedRef``, and the demand
// edge that caused this drop is what makes the counts effect pay it.
if (!isFeedActive()) {
const droppedWholeMapRead = refreshPendingRef.current || reconcilePendingRef.current;
refreshPendingRef.current = false;
reconcilePendingRef.current = false;
loadMorePendingRef.current = false;
// A queued refresh/reconcile was ALSO the scheduled payment for the unread
// debt, and dropping it here is the moment that payment stops existing.
// Re-settling is what turns the drop into the counts-only read the debt is
// still owed, instead of a silently unpaid one.
if (droppedWholeMapRead) settleWholeUnreadRef.current();
return;
}
if (refreshPendingRef.current) {
refreshPendingRef.current = false;
// A replacement refresh owns the same top-of-feed recovery as a pending
// reconcile, so one authoritative read satisfies both intents.
reconcilePendingRef.current = false;
refreshRunnerRef.current();
return;
}
if (reconcilePendingRef.current) {
reconcilePendingRef.current = false;
reconcileRunnerRef.current();
return;
}
if (loadMorePendingRef.current) {
loadMorePendingRef.current = false;
loadMoreRunnerRef.current();
}
}, [isFeedActive]);
const queueRefreshIntent = useCallback(() => {
refreshPendingRef.current = true;
queueMicrotask(flushFeedReadIntent);
}, [flushFeedReadIntent]);
const queueReconcileIntent = useCallback(() => {
reconcilePendingRef.current = true;
queueMicrotask(flushFeedReadIntent);
}, [flushFeedReadIntent]);
const queueLoadMoreIntent = useCallback(() => {
loadMorePendingRef.current = true;
queueMicrotask(flushFeedReadIntent);
}, [flushFeedReadIntent]);
const acceptSessionMutation = useCallback((sessionId: string) => {
readOwnershipRef.current.acceptMutation([
'inbox-feed',
'inbox-unread',
`inbox-session:${sessionId}`,
`inbox-unread-session:${sessionId}`,
]);
}, []);
const acceptUnreadMutation = useCallback(() => {
readOwnershipRef.current.acceptMutation(['inbox-unread', 'inbox-unread-all']);
}, []);
// One owner of "pay the debt", because recording it does not schedule anything.
// Raising a debt that is already outstanding is not an edge at all, and the fence
// only re-arms a read that is still in flight — so a counts read that FAILED and
// settled leaves a debt no later signal could pay, and the badge would keep
// revoked counts until some unrelated focus or reconnect. Every producer of the
// debt calls this instead, and it declines whenever a payment is already on the
// way:
// * a feed consumer exists, so the feed read carries the whole map;
// * a counts read is in flight, and the fence its producer just applied is what
// makes that read re-read rather than commit pre-change counts.
// Deferred by a microtask, because a scope restore raises the debt once per
// restored session: paying on the first of them would have the rest fence the
// read it just started, turning one burst into a read per event. Same reason
// ``queueRefreshIntent`` and its siblings defer.
const settleWholeUnread = useCallback(() => {
queueMicrotask(() => {
if (!wholeUnreadOwedRef.current) return;
// Being in flight is not being a payer. The call that raises the debt fences
// the reads that started before it, so those will refuse their own unread map
// — declining on their mere presence is how a debt ends up with nobody left
// to pay it. Only a read still current for the map can settle this one.
for (const read of wholeUnreadReadsInFlightRef.current) {
if (readOwnershipRef.current.isMutationCurrent(read, 'inbox-unread')) return;
}
// A queued read is a payment already scheduled: it has not been issued yet, so
// it will be stamped after this debt and will commit its map.
if (refreshPendingRef.current || reconcilePendingRef.current || unreadReadPendingRef.current) return;
// With a feed consumer the whole map rides on the feed read this queues, so the
// badge is paid without a second request. If demand disappears before it
// flushes, the gate drops it and re-enters here with no consumer — the branch
// below. Without one, the counts-only read is the only thing that can pay.
if (isFeedActive()) {
queueReconcileIntent();
return;
}
unreadReadRunnerRef.current();
});
}, [isFeedActive, queueReconcileIntent]);
// The mirror of ``applyUnreadMap``: one home for "no whole map describes this
// account any more". Recording the debt alone is not enough, because a whole-map
// read that left the server BEFORE this moment cannot describe the counts it is
// about to commit — and committing it would PAY the debt without satisfying it.
// So the fence, the debt, and its payment have one owner.
const oweWholeUnread = useCallback(() => {
acceptUnreadMutation();
wholeUnreadOwedRef.current = true;
settleWholeUnread();
}, [acceptUnreadMutation, settleWholeUnread]);
// One home for "an authoritative unread map arrived": set the map and flip
// ``unreadLoaded`` together so the two can never drift apart. Every whole-account
// write (refresh / reconcile / unread.changed) goes through here; targeted
// reads and mark-read responses merge one session without claiming completeness.
// stable identity, so it never churns the memoized context value. Paying the
// ``wholeUnreadOwedRef`` debt belongs here for the same reason: this is the only
// place a whole map is adopted, so no producer has to remember to clear it.
const applyUnreadMap = useCallback((map: Record<string, number>) => {
setUnreadBySession(map);
setUnreadLoaded(true);
wholeUnreadOwedRef.current = false;
}, []);
const applyWholeUnreadRead = useCallback((
read: WorkbenchSessionReadStamp,
map: Record<string, number>,
) => {
committedWholeUnreadGenerationRef.current = Math.max(
committedWholeUnreadGenerationRef.current,
read.generation,
);
applyUnreadMap(map);
}, [applyUnreadMap]);
const applySessionUnread = useCallback((sessionId: string, count: number) => {
setUnreadBySession((prev) => {
const next = { ...prev };
if (count > 0) next[sessionId] = count;
else delete next[sessionId];
return next;
});
}, []);
const mergeTargetedSnapshots = useCallback((rows: InboxSession[]): InboxSession[] => {
let next = rows;
for (const [sessionId, snapshot] of targetedSnapshotsRef.current) {
next = snapshot.row
? upsertSession(next, snapshot.row)
: next.filter((row) => row.session_id !== sessionId);
}
return next;
}, []);
const acceptFeedRows = useCallback((
read: WorkbenchSessionReadStamp,
rows: InboxSession[],
revalidateOmissions = false,
) => {
const returnedIds = new Set(rows.map((row) => row.session_id));
for (const row of rows) {
const resource = `inbox-session:${row.session_id}`;
readOwnershipRef.current.claimRead(read, resource);
if (readOwnershipRef.current.isCurrent(read, resource)) {
targetedSnapshotsRef.current.delete(row.session_id);
targetedReadPendingRef.current.delete(row.session_id);
}
}
if (!revalidateOmissions) return [];
const omitted = new Set(
Array.from(targetedSnapshotsRef.current.entries())
.filter(([sessionId, snapshot]) => snapshot.row && !returnedIds.has(sessionId))
.map(([sessionId]) => sessionId),
);
for (const sessionId of targetedReadInFlightRef.current) {
if (!returnedIds.has(sessionId)) omitted.add(sessionId);
}
return Array.from(omitted);
}, []);
const refresh = useCallback(async function refresh() {
if (broadReadInFlightRef.current || cursorReadsInFlightRef.current > 0) {
queueRefreshIntent();
return;
}
broadReadInFlightRef.current = true;
refreshPendingRef.current = false;
reconcilePendingRef.current = false;
const read = readOwnershipRef.current.beginRead(['inbox-feed', 'inbox-unread', 'inbox-feed-refresh']);
wholeUnreadReadsInFlightRef.current.add(read);
const loadingGeneration = ++refreshLoadingGenerationRef.current;
const retryAfterInvalidation = () => {
const invalidatedByMutation = !readOwnershipRef.current.isMutationCurrent(read, 'inbox-feed');
const supersededByCursorRead =
(readOwnershipRef.current.latestGeneration('inbox-feed-cursor') ?? 0) > read.generation;
const supersededByRefresh =
(readOwnershipRef.current.latestGeneration('inbox-feed-refresh') ?? 0) > read.generation;
const supersededByReconcile =
(readOwnershipRef.current.latestGeneration('inbox-feed-reconcile') ?? 0) > read.generation;
if (
(!invalidatedByMutation && !supersededByCursorRead) ||
supersededByRefresh ||
supersededByReconcile ||
refreshPendingRef.current
) {
return false;
}
queueRefreshIntent();
return true;
};
setLoading(true);
try {
const result = await api.listInbox({ platform: 'avibe', limit: PAGE_SIZE });
const feedCurrent = readOwnershipRef.current.isCurrent(read, 'inbox-feed');
if (!feedCurrent) {
retryAfterInvalidation();
} else {
const snapshotsToRevalidate = acceptFeedRows(read, result.sessions, true);
setInboxSessions(() => mergeTargetedSnapshots(result.sessions));
applyNextCursor(result.next_cursor);
for (const sessionId of snapshotsToRevalidate) reconcileSessionRef.current(sessionId);
}
if (readOwnershipRef.current.isCurrent(read, 'inbox-unread')) {
applyWholeUnreadRead(read, result.unread_by_session ?? {});
}
} catch (err) {
if (!retryAfterInvalidation()) console.error('[inbox] refresh failed', err);
} finally {
if (refreshLoadingGenerationRef.current === loadingGeneration) setLoading(false);
wholeUnreadReadsInFlightRef.current.delete(read);
broadReadInFlightRef.current = false;
flushFeedReadIntent();
}
}, [acceptFeedRows, api, applyNextCursor, applyWholeUnreadRead, flushFeedReadIntent, mergeTargetedSnapshots, queueRefreshIntent]);
const loadMore = useCallback(async function loadMore() {
if (
broadReadInFlightRef.current ||
refreshPendingRef.current ||
reconcilePendingRef.current
) {
queueLoadMoreIntent();
return;
}
// A duplicate click while the same cursor is already loading is not a new
// page intent. Mutation invalidation queues its retry explicitly below.
if (cursorReadsInFlightRef.current > 0) return;
loadMorePendingRef.current = false;
const cursor = cursorRef.current;
if (!cursor) return;
const read = readOwnershipRef.current.beginRead(['inbox-feed', 'inbox-feed-cursor']);
cursorReadsInFlightRef.current += 1;
const loadingGeneration = ++loadMoreLoadingGenerationRef.current;
let retryAfterInvalidation = false;
setLoadingMore(true);
try {
const result = await api.listInbox({ platform: 'avibe', limit: PAGE_SIZE, before: cursor });
if (!readOwnershipRef.current.isCurrent(read, 'inbox-feed')) {
retryAfterInvalidation = readOwnershipRef.current.isLatestRead(read);
return;
}
acceptFeedRows(read, result.sessions);
setInboxSessions((prev) => mergeTargetedSnapshots(appendPage(prev, result.sessions)));
applyNextCursor(result.next_cursor);
} catch (err) {
retryAfterInvalidation =
!readOwnershipRef.current.isCurrent(read, 'inbox-feed') &&
readOwnershipRef.current.isLatestRead(read);
if (!retryAfterInvalidation) console.error('[inbox] load more failed', err);
} finally {
cursorReadsInFlightRef.current -= 1;
if (loadMoreLoadingGenerationRef.current === loadingGeneration) setLoadingMore(false);
if (retryAfterInvalidation) queueLoadMoreIntent();
else flushFeedReadIntent();
}
}, [acceptFeedRows, api, applyNextCursor, flushFeedReadIntent, mergeTargetedSnapshots, queueLoadMoreIntent]);
const markRead = useCallback(
async (sessionId: string, untilMessageId?: string) => {
// Clearing unread is best-effort, so a failure must not raise an error
// toast. Reading a permitted session and mutating its unread state are
// independent capabilities.
const operation = readOwnershipRef.current.beginRead(`inbox-mark-read:${sessionId}`);
const result = await api.markSessionRead(sessionId, untilMessageId, { handleError: false });
// With handleError off, a 4xx/5xx resolves with the error body rather
// than throwing; only the endpoint's success shape is an applied write.
const applied = typeof result?.updated === 'number' || Boolean(result?.unread_by_session);
// A later *started* write for this session (a second mark-read, or a
// read-changing event) supersedes this one. Completing an older write
// first must not fence a newer write that started after it: both share
// the same mutation epoch until one of them commits.
const laterMarkStarted = (readOwnershipRef.current.latestGeneration(`inbox-mark-read:${sessionId}`) ?? 0) > operation.generation;
if (
!applied
|| laterMarkStarted
|| !readOwnershipRef.current.isMutationCurrent(operation, [
`inbox-session:${sessionId}`,
`inbox-unread-session:${sessionId}`,
])
) {
return applied;
}
// The response carries the whole account map, but it describes the other
// sessions only as of this write. It is adopted whole only if nothing has
// changed or committed the whole map since this write began; otherwise
// only this session's count, which nothing newer has touched, is merged.
const wholeMapCurrent =
readOwnershipRef.current.isMutationCurrent(operation, 'inbox-unread')
&& committedWholeUnreadGenerationRef.current <= operation.generation;
// A successful write commits after every read that was already in flight,
// even when one of those reads started later and returns last.
readOwnershipRef.current.acceptMutation([
'inbox-unread',
`inbox-unread-session:${sessionId}`,
]);
// The unread map is authoritative for badges; the card's unread styling
// derives from it, so clearing here clears the dot without touching the
// feed order (a read doesn't change last activity).
const map = result.unread_by_session;
if (map && wholeMapCurrent) applyUnreadMap(map);
else if (map) applySessionUnread(sessionId, map[sessionId] ?? 0);
return true;
},
[api, applySessionUnread, applyUnreadMap],
);
// Resume reconcile: re-read the feed WITHOUT collapsing pagination. A
// visibility/online resume can fire after the user has loaded several pages;
// a plain first-page refresh() would drop every row past page 1 and reset the
// cursor. Re-read enough rows to cover what's loaded (capped at the API's
// 100-row max) and merge in place so existing rows update and any sessions
// that arrived during the gap surface at top. No loading flag — the user
// already has content; this is a silent catch-up.
const reconcile = useCallback(async () => {
if (
broadReadInFlightRef.current ||
cursorReadsInFlightRef.current > 0 ||
refreshPendingRef.current
) {
queueReconcileIntent();
return;
}
broadReadInFlightRef.current = true;
reconcilePendingRef.current = false;
const read = readOwnershipRef.current.beginRead(['inbox-feed', 'inbox-unread', 'inbox-feed-reconcile']);
wholeUnreadReadsInFlightRef.current.add(read);
const retryAfterInvalidation = () => {
const invalidatedByMutation = !readOwnershipRef.current.isMutationCurrent(read, 'inbox-feed');
const supersededByCursorRead =
(readOwnershipRef.current.latestGeneration('inbox-feed-cursor') ?? 0) > read.generation;
const supersededByReconcileRead =
(readOwnershipRef.current.latestGeneration('inbox-feed-reconcile') ?? 0) > read.generation;
const supersededByRefresh =
(readOwnershipRef.current.latestGeneration('inbox-feed-refresh') ?? 0) > read.generation;
if (
(!invalidatedByMutation && !supersededByCursorRead) ||
supersededByRefresh ||
supersededByReconcileRead ||
reconcilePendingRef.current
) {
return false;
}
queueReconcileIntent();
return true;
};
// Snapshot loaded ids up front: sizes the re-read window, and lets us tell
// afterward whether the read overlapped what we already had (cursor note).
const loadedIds = new Set(inboxSessionsRef.current.map((s) => s.session_id));
const limit = Math.min(Math.max(loadedIds.size, PAGE_SIZE), 100);
try {
const result = await api.listInbox({
platform: 'avibe',
limit,
cache: false,
handleError: false,
});
const feedCurrent = readOwnershipRef.current.isCurrent(read, 'inbox-feed');
const supersededByCursorRead =
(readOwnershipRef.current.latestGeneration('inbox-feed-cursor') ?? 0) > read.generation;
const supersededByReconcileRead =
(readOwnershipRef.current.latestGeneration('inbox-feed-reconcile') ?? 0) > read.generation;
if (!feedCurrent || supersededByCursorRead || supersededByReconcileRead) {
retryAfterInvalidation();
} else {
const snapshotsToRevalidate = acceptFeedRows(read, result.sessions, true);
// The read is the server's whole answer for every row that sorts above its
// last one, or for all of them when there is no further page. A loaded row
// in that range that the answer leaves out is one this reader may no longer
// see — a removed Bot's Session (docs/plans/bots.md D1), say, while the
// stream was down — so it goes, with no event needed to say so. Rows below
// that edge were not re-read and stay.
const edge = result.sessions.at(-1);
const reread = (row: InboxSession) =>
result.next_cursor === null || (edge !== undefined && byActivityDesc(row, edge) < 0);
setInboxSessions((prev) => {
const incoming = new Map(result.sessions.map((s) => [s.session_id, s]));
const merged = prev
.filter((s) => incoming.has(s.session_id) || !reread(s))
.map((s) => incoming.get(s.session_id) ?? s);
const have = new Set(prev.map((s) => s.session_id));
for (const s of result.sessions) if (!have.has(s.session_id)) merged.push(s);
merged.sort(byActivityDesc);
return mergeTargetedSnapshots(merged);
});
for (const sessionId of snapshotsToRevalidate) reconcileSessionRef.current(sessionId);
// Cursor: the loaded feed is always a contiguous run from the top, and
// this reads the newest `limit` rows. If the read shares ANY row with what
// we had (overlap), the two runs are contiguous — no gap below the read —
// so the existing cursor still marks the boundary; leave it untouched
// (this is what stops a >100-row exhausted feed from resurrecting a
// duplicate-page "Load more"). If the read is ENTIRELY new rows (no
// overlap), gap arrivals outnumbered the window and there are unseen rows
// between this read and the old feed — adopt result.next_cursor so "Load
// more" can page through them (loadMore dedupes the overlap).
const overlap = result.sessions.some((s) => loadedIds.has(s.session_id));
if (!overlap) applyNextCursor(result.next_cursor);
}
if (readOwnershipRef.current.isCurrent(read, 'inbox-unread')) {
applyWholeUnreadRead(read, result.unread_by_session ?? {});
}
} catch (err) {
if (!retryAfterInvalidation()) console.error('[inbox] reconcile failed', err);
} finally {
wholeUnreadReadsInFlightRef.current.delete(read);
broadReadInFlightRef.current = false;
flushFeedReadIntent();
}
}, [acceptFeedRows, api, applyNextCursor, applyWholeUnreadRead, flushFeedReadIntent, mergeTargetedSnapshots, queueReconcileIntent]);
// Counts-only read for routes that render no feed. Same endpoint and the same
// pagination-independent unread map as refresh()/reconcile(), with the row
// window collapsed to the smallest the API accepts — it claims only the unread
// resource, discards the row it is handed, and never touches the feed or the
// cursor, so activating the feed later still starts from a real first page.
// (The server clamps `limit` to at least 1; a true zero-row read would need an
// API change, deliberately out of scope here.)
const refreshUnread = useCallback(async function refreshUnread(backgroundPush = false) {
if (unreadReadInFlightRef.current) {
unreadReadPendingRef.current = true;
return;
}
unreadReadInFlightRef.current = true;
// A mid-flight mutation invalidates this response, and unlike the feed path
// nothing else is queued to replace it: the ``inbox.session.updated`` handler
// merges one session's count and never claims an authoritative whole map, so
// silently discarding would leave every other session's count — and the
// favicon/PWA badge — missing until some later focus or reconnect. Re-read,
// exactly as ``refresh`` does. A newer read of the same resource is a
// different case: it owns the map now and will apply its own, so stepping
// aside is correct and keeps this terminating.
const staleReadNeedsReread = (read: WorkbenchSessionReadStamp) =>
!readOwnershipRef.current.isMutationCurrent(read, 'inbox-unread') &&
(readOwnershipRef.current.latestGeneration('inbox-unread') ?? 0) <= read.generation;
try {
do {
unreadReadPendingRef.current = false;
const read = readOwnershipRef.current.beginRead(['inbox-unread']);
wholeUnreadReadsInFlightRef.current.add(read);
try {
const result = await api.listInbox({
platform: 'avibe',
limit: 1,
cache: false,
handleError: false,
backgroundPush,
});
if (readOwnershipRef.current.isCurrent(read, 'inbox-unread')) {
applyWholeUnreadRead(read, result.unread_by_session ?? {});
} else if (staleReadNeedsReread(read)) {
unreadReadPendingRef.current = true;
}
} catch (err) {
if (staleReadNeedsReread(read)) unreadReadPendingRef.current = true;
else console.error('[inbox] refreshUnread failed', err);
} finally {
wholeUnreadReadsInFlightRef.current.delete(read);
}
} while (unreadReadPendingRef.current);
} finally {
unreadReadInFlightRef.current = false;
}
}, [api, applyWholeUnreadRead]);
// Same rule as the projects tree: a reconnect is revalidation and may wait for
// a consumer, but an authorization change is invalidation and cannot. The feed's
// resumption path merges rather than replaces — ``reconcile`` deliberately keeps
// rows the response omitted — so rows loaded before the change would survive the
// trip back, and a failed reconcile would keep them indefinitely. Drop them and
// reset ``initialFetched`` so the next feed consumer takes the authoritative
// page-one path instead.
//
// The unread map is deliberately NOT dropped here: the counts read that follows
// replaces it whole, and blanking it first would clear a badge the push service
// worker may legitimately own while this document was never authoritative (the
// ``unreadLoaded`` invariant). A count is a number for a session id the user
// already had; a feed row is its title and preview.
const discardAuthorizedFeed = useCallback(() => {
const cachedSessionIds = new Set([
...inboxSessionsRef.current.map((row) => row.session_id),
...targetedSnapshotsRef.current.keys(),
...targetedReadInFlightRef.current,
]);
// Fence the reads already in flight: a response that left the server before
// the change must not repopulate what we are dropping.
readOwnershipRef.current.acceptMutation([
'inbox-feed',
...[...cachedSessionIds].map((sessionId) => `inbox-session:${sessionId}`),
]);
initialFetched.current = false;
inboxSessionsRef.current = [];
targetedSnapshotsRef.current.clear();
targetedReadPendingRef.current.clear();
setInboxSessions([]);
applyNextCursor(null);
}, [applyNextCursor]);
// Targeted reconcile for one session (contract A6 foreground restore): fetch
// that exact session by id and upsert its card, so a restored session
// reappears even when its activity sorts past the windowed reconcile()'s
// newest-N rows. The response still carries the pagination-independent
// whole-account unread map, but this read owns only this session's count.
// Never touches the cursor or replaces unrelated unread state.
const reconcileSession = useCallback(
async (sessionId: string) => {
if (targetedReadInFlightRef.current.has(sessionId)) {
targetedReadPendingRef.current.add(sessionId);
return;
}
targetedReadInFlightRef.current.add(sessionId);
try {
while (true) {
targetedReadPendingRef.current.delete(sessionId);
// The demand gate belongs HERE rather than at the events that call this:
// every trigger of a request-backed revalidation would otherwise have to
// remember it, and this provider has more triggers than guards. With no
// feed consumer the card this upserts is not rendered and the next
// activation reconciles the window anyway — the same argument that lets a
// queued feed intent be dropped. What is NOT droppable is the other half
// of this read: it owns this session's unread count, which every route
// badges. So declining hands the whole-account map the debt instead of
// dropping the obligation with the request, and a burst of foreground
// restores costs one coalesced counts read instead of one targeted read
// each.
//
// Asked per REQUEST rather than on the way in, because this is a loop:
// an entry gate answers for the pass that queued a retry, and the retry
// runs later — after the navigation that removed the card it upserts.
if (!isFeedActive()) {
oweWholeUnread();
return;
}
const sessionResource = `inbox-session:${sessionId}`;
const unreadResource = `inbox-unread-session:${sessionId}`;
const read = readOwnershipRef.current.beginRead([sessionResource, unreadResource]);
try {
const result = await api.listInbox({
platform: 'avibe',
onlySession: sessionId,
limit: 1,
cache: false,
handleError: false,
});
const supersededByPendingIntent = targetedReadPendingRef.current.has(sessionId);
const row = result.sessions.find((s) => s.session_id === sessionId);
if (
!supersededByPendingIntent &&
readOwnershipRef.current.isCurrent(read, sessionResource)
) {
targetedSnapshotsRef.current.set(sessionId, { row: row ?? null });
setInboxSessions((prev) =>
row
? upsertSession(prev, row)
: prev.filter((candidate) => candidate.session_id !== sessionId),
);
}
const newerCommittedWholeUnread =
committedWholeUnreadGenerationRef.current > read.generation;
if (
!supersededByPendingIntent &&
readOwnershipRef.current.isCurrent(read, unreadResource) &&
readOwnershipRef.current.isMutationCurrent(read, 'inbox-unread-all') &&
!newerCommittedWholeUnread
) {
applySessionUnread(sessionId, result.unread_by_session?.[sessionId] ?? 0);
}
} catch (err) {
console.error('[inbox] reconcileSession failed', err);
}
if (!targetedReadPendingRef.current.has(sessionId)) return;
}
} finally {
targetedReadInFlightRef.current.delete(sessionId);
}
},
[api, applySessionUnread, isFeedActive, oweWholeUnread],
);
settleWholeUnreadRef.current = settleWholeUnread;
unreadReadRunnerRef.current = () => void refreshUnread();
refreshRunnerRef.current = () => void refresh();
reconcileRunnerRef.current = () => void reconcile();
loadMoreRunnerRef.current = () => void loadMore();
reconcileSessionRef.current = (sessionId) => void reconcileSession(sessionId);
// The feed's first read waits for a consumer that renders it. ``feedActive`` is
// state, so it flips one render after the activation and this effect is what
// runs the read — both for a workbench document's first paint and for a later
// /admin → /chat navigation, which finds ``initialFetched`` still false and
// loads page one exactly as a direct load would.
//
// First read loads page one; every later rerun reconciles the loaded window
// instead when an ``api`` identity change rebuilds the value — so a non-resume
// rerun never collapses a multi-page feed back to page one. The broker fans
// events out live with no replay (sse_broker.py ``/api/events``), so anything
// missed while the socket was down must be re-read; plain HTTP, independent of
// whether the SSE stream itself comes back up.
//
// One owner for that choice, because activation is not its only caller: an
// authorization change re-reads for an active consumer too, and it drops the
// window first — so the answer comes from the cache as it is at that moment
// rather than from which event asked.
const readFeedForActiveConsumer = useCallback(() => {
if (!initialFetched.current) {
initialFetched.current = true;
void refresh();
return;
}
void reconcile();
}, [reconcile, refresh]);
useEffect(() => {
if (!feedActive) return;
readFeedForActiveConsumer();
}, [feedActive, readFeedForActiveConsumer]);
// The badges are shell-wide, so the unread map is loaded on every route — but on
// a route with no feed consumer, only the map. The decision itself belongs to
// ``settleWholeUnread``, which every producer of the debt also calls; this effect
// adds the two moments no producer of the debt can observe. Mount is one: it is
// the first time the map is owed. A change in DEMAND is the other, and it is not
// the same event as the debt being owed — it changes WHICH read can pay, so a
// debt whose payer failed is re-tested by the route the user moved to rather than
// by a retry. Nothing else would notice it, because the refcount function has
// stable identity by design. ``isFeedActive()`` is then read synchronously inside
// the settle rather than from ``feedActive`` here, because consumers activate in
// their own effects, which React runs before this one.
//
// The debt itself is deliberately NOT a dependency, and that is the round-8 rule
// rather than an optimization: re-running on the level would re-enter on the very
// thing a failed pass leaves behind, so it would never terminate. A demand edge is
// an event, so it re-enters a bounded number of times — once per navigation.
useEffect(() => {
settleWholeUnread();
}, [feedActive, settleWholeUnread]);
useEffect(() => {
const disconnect = api.connectWorkbenchEvents({
onAuthorizationChanged: () => {
// A permission change invalidates whatever is loaded. Demand decides only
// whether a replacement READ follows — never whether the voided cache is
// dropped, which is why the drop cannot sit in the no-consumer branch.
// With a consumer this used to merely re-read, and ``reconcile``
// deliberately KEEPS the rows a response omits, so revoked titles and
// previews survived a slow read and outlived a failed one entirely. Worse,
// the replacement is queued when a read is already in flight, and the
// demand gate in ``flushFeedReadIntent`` drops it if the last consumer
// leaves first — leaving the pre-change response free to repopulate rows
// the change had voided, with nothing left to correct them.
//
// No committed whole map describes the new scope, so owe one rather than
// naming the read that pays it: with a feed consumer the read below
// carries it, without one the counts effect runs on this very state
// change, and if that read is later dropped or fails the debt is still
// outstanding when the last consumer leaves. Owing also fences the
// pre-change counts read that may be in flight — which is the whole reason
// that fence lives with the debt and not at this call site.
oweWholeUnread();
discardAuthorizedFeed();
// Dropping the window is also what makes this the authoritative page-one
// read rather than a reconcile onto rows that are no longer there.
if (isFeedActive()) readFeedForActiveConsumer();
},
// The Bot roster decides which Sessions this reader may see: removing a Bot
// hides its Session and setting it again brings it back (bots.md D1), with
// no Inbox event of its own. The server owns that answer, so read it again
// rather than reclassify locally. Owing the whole map does exactly that: it
// fences the reads already in flight, and the read that pays it is the
// window's reconcile while the feed is shown (which drops rows the server
// no longer returns) or the counts read while it is not.
onBotsChanged: () => {
oweWholeUnread();
},
onInboxSessionUpdated: (row) => {
targetedSnapshotsRef.current.delete(row.session_id);
acceptSessionMutation(row.session_id);
setInboxSessions((prev) => upsertSession(prev, row));
setUnreadBySession((prev) => {
if ((prev[row.session_id] ?? 0) === row.unread_count) return prev;
const next = { ...prev };
if (row.unread_count > 0) next[row.session_id] = row.unread_count;
else delete next[row.session_id];
return next;
});
},
onInboxUnreadChanged: (data) => {
if (data?.unread_by_session) {
// The event IS the newest whole map: fence the reads in flight, then adopt it.
// Include the session slice when the event names one, so an in-flight
// mark-read for that session cannot merge its older count over this map.
if (data.session_id) {
readOwnershipRef.current.acceptMutation([
'inbox-unread',
'inbox-unread-all',
`inbox-unread-session:${data.session_id}`,
]);
} else {
acceptUnreadMutation();
}
applyUnreadMap(data.unread_by_session);
return;
}
// The counts changed and the event did not say how, so nothing here can
// adopt a map: owe one, which invalidates the reads that started before the
// change and would otherwise settle the debt with pre-change counts.
oweWholeUnread();
},
onSessionActivity: (data) => {
// Contract A6: react to visibility/scope changes carried on the event.
// background ⇒ drop the card (like an archive); foreground ⇒ fetch that
// exact session and upsert its card so it reappears even if it sorts past
// the reconcile window; no visibility ⇒ no-op except an explicit archive.
// See lib/inboxActivity.
const action = sessionActivityInboxAction(data);
if (action === 'reconcile') {
targetedSnapshotsRef.current.delete(data.session_id);
acceptSessionMutation(data.session_id);
void reconcileSession(data.session_id);
return;
}
if (action === 'ignore') return;
targetedSnapshotsRef.current.delete(data.session_id);
acceptSessionMutation(data.session_id);
// action === 'drop': remove the card + its unread live, instead of
// waiting for the next reconnect/refresh to filter it.
setInboxSessions((prev) => prev.filter((s) => s.session_id !== data.session_id));
setUnreadBySession((prev) => {
if (!(data.session_id in prev)) return prev;
const next = { ...prev };
delete next[data.session_id];
return next;
});
},
// A live stream is reaching us again, so anything it missed has to come
// from durable storage. This is the recovery for every gap, including the
// OS suspending us: a backgrounded mobile PWA has its page frozen and its
// SSE socket dropped, the broker never replays the gap, and iOS can leave
// EventSource in a zombie OPEN state without onerror. ApiContext recycles
// a stream that cannot prove it survived, so that case arrives here too —
// while a returning page whose stream did prove it fires nothing, having
// already delivered the events.
onConnected: () => {
if (isFeedActive()) void reconcile();
else void refreshUnread();
},
onError: (err) => {
// ApiContext owns the explicit reconnect loop. Keep this a log, not a
// crash, so the workbench stays usable during the HTTP fallback.
console.debug('[inbox] sse error', err);
},
});
return disconnect;
}, [
acceptSessionMutation,
acceptUnreadMutation,
api,
applyUnreadMap,
discardAuthorizedFeed,
isFeedActive,
oweWholeUnread,
readFeedForActiveConsumer,
reconcile,
reconcileSession,
refreshUnread,
]);
const totalUnread = useMemo(
() => Object.values(unreadBySession).reduce((sum, n) => sum + (n || 0), 0),
[unreadBySession],
);
const unreadSessions = useMemo(
() => Object.values(unreadBySession).filter((n) => (n || 0) > 0).length,
[unreadBySession],
);
// The badges outside the app count only categories whose notifications are on.
// They wait for the switches and the Bot list as they wait for the map: before
// all three are known, a badge the push worker set while the app was closed is
// the better number.
const { preferences, loaded: preferencesLoaded } = useNotificationPreferences();
const { roster } = useBotRoster();
const unreadByCategory = useMemo(
() => splitUnread(unreadBySession, roster.sessionIds),
[unreadBySession, roster.sessionIds],
);
const badgeTotal = useMemo(() => loudUnread(unreadByCategory, preferences), [unreadByCategory, preferences]);
const badgeKnown = unreadLoaded && preferencesLoaded && roster.known;
// Mirror the badge total onto the installed PWA's home-screen icon badge so
// the icon matches the in-app Inbox badge. The push service worker (push-sw.js)
// sets this while the app is closed; this keeps it live while the app is open —
// reading clears it, a new reply bumps it. Best-effort + feature-detected:
// browsers without the Badging API (and non-installed tabs) simply no-op, and a
// rejected badge promise is swallowed so it never surfaces as an app error.
//
// Gated on ``badgeKnown``: until the first authoritative unread map arrives,
// ``badgeTotal`` is just the default 0, and clearing here would wipe a badge
// the service worker set while the app was closed if that initial load is slow,
// fails, or redirects on an expired session. Once loaded, a real 0 clears it.
// A fresh authoritative map reasserts the badge even when its numeric sum
// is unchanged: a worker may have written an older sum between reads.
useEffect(() => {
const nav = navigator as Navigator & {
setAppBadge?: (contents?: number) => Promise<void>;
clearAppBadge?: () => Promise<void>;
};
if (!('setAppBadge' in nav)) return;
if (!badgeKnown) return;
const op = badgeTotal > 0 ? nav.setAppBadge?.(badgeTotal) : nav.clearAppBadge?.();
void op?.catch?.(() => {});
// Fence a background worker read that started before this authoritative
// map arrived. The worker serializes its own setter after this message, so
// a late Push response cannot be the final badge write.
try {
navigator.serviceWorker?.controller?.postMessage({
type: 'vibe.app-badge-current',
count: badgeTotal,
});
} catch {
// The direct badge write above still works without a controlling worker.
}
}, [unreadBySession, badgeTotal, badgeKnown]);
// A worker can finish a background badge write after this page's last
// unread update. Revalidate on its completion signal and whenever the page
// returns from suspension, even if the local unread total did not change.
useEffect(() => {
if (!('serviceWorker' in navigator) || !('setAppBadge' in navigator)) return;
const onWorkerMessage = (event: MessageEvent) => {
if (event.data?.type === 'vibe.push-badge-refresh') void refreshUnread(true);
};
const unsubscribeResume = onPageReactivated(() => void refreshUnread());
navigator.serviceWorker.addEventListener('message', onWorkerMessage);
return () => {
unsubscribeResume();
navigator.serviceWorker.removeEventListener('message', onWorkerMessage);
};
}, [refreshUnread]);
// Browser tabs have no Badging API. Keep their favicon useful while the
// Inbox map is authoritative, and restore the original icon after reading.
useEffect(() => {
if (!badgeKnown) return;
syncFaviconBadge(badgeTotal);
}, [badgeTotal, badgeKnown]);
const value = useMemo<InboxState>(
() => ({
inboxSessions,
unreadBySession,
unreadLoaded,
totalUnread,
unreadSessions,
unreadByCategory,
badgeTotal,
nextCursor,
loading,
loadingMore,
refresh,
loadMore,
markRead,
activateFeed,
}),
[
activateFeed,
inboxSessions,
unreadBySession,
unreadLoaded,
totalUnread,
unreadSessions,
unreadByCategory,
badgeTotal,
nextCursor,
loading,
loadingMore,
refresh,
loadMore,
markRead,
],
);
return <WorkbenchInboxContext.Provider value={value}>{children}</WorkbenchInboxContext.Provider>;
};