The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* Reconcile the sidebar's pins with the backend "keep" flag, both directions.
*
* Pins drive the sidebar UI out of `$pinnedSessionIds` (localStorage), but the
* durable record is `sessions.pinned` in each profile's state.db. Two things
* depend on the backend copy: the `sessions.auto_archive` sweep runs
* server-side and would otherwise hide a pinned chat, and a second Desktop app
* pointed at the same gateway has its own, separate localStorage.
*
* Push: PATCH `pinned` whenever the local set changes, and re-assert the whole
* set at boot — which transparently migrates pre-existing pins with no user
* action.
*
* Pull: session rows now carry `pinned`, and the list endpoints back-fill
* pinned conversations past their LIMIT, so a row's absence from a page no
* longer says anything about its pin state. That makes the server row
* authoritative: adopt pins this app hasn't seen, and drop local pins the
* server says are gone. Only rows actually present in the payload are
* consulted, so a backend predating the flag (`pinned === undefined`) leaves
* the local set untouched — and a page that predates one of our own writes is
* fenced out until a later page confirms the value we wrote.
*/
import { atom } from 'nanostores'
import { setSessionPinnedRemote } from '@/hermes'
import { onConnectionScopeChange } from '@/lib/connection-scoped'
import { $pinnedSessionIds, pinSession, unpinSession } from '@/store/layout'
import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
import {
$cronSessions,
$messagingSessions,
$sessions,
sessionMatchesStoredId,
sessionPinId,
setCronSessions,
setMessagingSessions,
setSessions
} from '@/store/session'
import { isSessionRemovalPending } from '@/store/session-removal'
import type { SessionInfo } from '@/types/hermes'
// pin ids we've successfully PATCHed pinned=true this session.
const mirrored = new Set<string>()
// pin ids awaiting their row so we can resolve the owning profile before PATCH.
const pending = new Set<string>()
// Writes we've issued, id -> the value we wrote and when. A list page already
// in flight when we PATCH still carries the OLD value, and it can land after
// our ack — so the ack is not proof the page we're reading is newer than the
// write. Hold the guard until a page actually CONFIRMS the written value,
// with a cooldown so a row that never comes back can't fence itself forever.
const unconfirmed = new Map<string, { at: number; value: boolean }>()
// Marker stamped on rows this module repainted to match a local toggle. They
// carry OUR intent, not the server's, so they may never confirm (release) a
// write guard — only a row a real list page delivered can do that. It is an
// enumerable symbol so a value copy (`{ ...row }`) carries it too: rows are
// re-spread on ordinary user paths (touchSessionActivity on send,
// applySessionTitle on rename), and identity-keyed tracking would drop
// exactly those copies, letting our own painted value read as a remote
// confirmation and release the guard mid-flight.
const optimisticPin = Symbol('optimisticPin')
type OptimisticSessionRow = SessionInfo & { [optimisticPin]?: true }
function isOptimisticRow(row: SessionInfo): boolean {
return (row as OptimisticSessionRow)[optimisticPin] === true
}
/**
* The ids `unconfirmed` currently fences, for readers outside this module.
*
* The sidebar's Pinned section falls back to the server `pinned` flag for rows
* the local set doesn't know about, and that fallback needs the same fence the
* pull pass uses: a row whose flag our own in-flight write contradicts is not
* news, it's the past. Without it an unpin re-lists the session under Pinned
* until the next page lands.
*
* Re-published only when the key set actually changes, so a sidebar memo keyed
* on it survives an ordinary session refresh.
*/
export const $unconfirmedPinWrites = atom<ReadonlySet<string>>(new Set())
// How long an unconfirmed write outranks a page that contradicts it. Long
// enough to cover a list request issued just before the PATCH (those are the
// slow ones), short enough that a genuine server-side change still wins.
const WRITE_GUARD_MS = 10_000
function publishUnconfirmed(): void {
const published = $unconfirmedPinWrites.get()
if (published.size === unconfirmed.size && [...unconfirmed.keys()].every(id => published.has(id))) {
return
}
$unconfirmedPinWrites.set(new Set(unconfirmed.keys()))
}
function profileFor(pinId: string): null | string | undefined {
return loadedRowFor(pinId)?.profile
}
function loadedSessionRows(): SessionInfo[] {
return [...$sessions.get(), ...$cronSessions.get(), ...$messagingSessions.get()]
}
/**
* The row a stored pin id resolves to, across every slice. Same tie-break as
* `rowsByPinId`: when two profiles share the id, the write must target the
* row the pull adopted — the active gateway's — or an unpin PATCHes the other
* profile and the next page re-adopts the pin.
*/
function loadedRowFor(pinId: string): SessionInfo | undefined {
const rows = loadedSessionRows().filter(row => sessionMatchesStoredId(row, pinId))
const gateway = normalizeProfileKey($activeGatewayProfile.get())
return rows.find(row => normalizeProfileKey(row.profile) === gateway) ?? rows[0]
}
/**
* One authoritative row per durable pin id. Session ids are only unique inside
* a profile, so the cross-profile list can legitimately hold two rows with the
* same `sessionPinId` but different `pinned` flags (copied/imported profile
* databases). Iterating both would pin then unpin the same id in one pass and
* re-fire `reconcile` forever — the runaway that overflows nanostores'
* listenerQueue. Collapse to a single row per id, preferring the active
* gateway's profile (the same tie-break `resolveLoadedRow` uses), so the pull
* is deterministic and never oscillates.
*/
function rowsByPinId(rows: readonly SessionInfo[]): Map<string, SessionInfo> {
const byId = new Map<string, SessionInfo>()
const gateway = normalizeProfileKey($activeGatewayProfile.get())
for (const row of rows) {
const pinId = sessionPinId(row)
const existing = byId.get(pinId)
if (!existing) {
byId.set(pinId, row)
continue
}
// Prefer the active gateway's profile; otherwise keep the first seen.
if (normalizeProfileKey(row.profile) === gateway && normalizeProfileKey(existing.profile) !== gateway) {
byId.set(pinId, row)
}
}
return byId
}
/**
* Paint the local intent onto every loaded row for `pinId`, in every slice.
*
* Without this the cached row keeps the pre-toggle flag until a page replaces
* it — and a row kept alive as a survivor (open tile, selection, recently
* settled, or simply no refresh yet) never is. Once the write guard's cooldown
* lapsed, the next unrelated slice change read that frozen `pinned: true` as a
* remote pin and re-listed the chat the user had just unpinned (and the mirror
* image for a fresh pin). Rows without the flag (backend predating it) are left
* alone so the pull still has no opinion on them.
*/
function applyRowPinned(pinId: string, pinned: boolean, profile?: null | string): void {
// Session ids are only unique per profile; when the write names its owner,
// leave a same-id twin in another profile carrying its own server flag.
const owner = profile == null ? null : normalizeProfileKey(profile)
const patchRows = (rows: SessionInfo[]): SessionInfo[] => {
let changed = false
const next = rows.map(row => {
if (
typeof row.pinned !== 'boolean' ||
row.pinned === pinned ||
!sessionMatchesStoredId(row, pinId) ||
(owner != null && normalizeProfileKey(row.profile) !== owner)
) {
return row
}
changed = true
const updated: OptimisticSessionRow = { ...row, pinned, [optimisticPin]: true }
return updated
})
return changed ? next : rows
}
setSessions(patchRows)
setCronSessions(patchRows)
setMessagingSessions(patchRows)
}
/** PATCH the flag, guarding reads against pages that predate the write. */
function writePin(id: string, pinned: boolean, profile?: null | string): Promise<void> {
unconfirmed.set(id, { at: Date.now(), value: pinned })
applyRowPinned(id, pinned, profile)
return setSessionPinnedRemote(id, pinned, profile).then(
() => {
// Deliberately NOT cleared here: a list request issued before this PATCH
// can still land after the ack carrying the pre-write value. The guard
// is released by pullRemotePins when a page confirms the written value,
// or by the cooldown if none ever does.
},
(err: unknown) => {
// A failed write leaves the server on the old value, so the guard would
// be fencing out the truth. Drop it and let the page win.
// The painted rows are left as-is (pin or unpin alike): a failed pin is
// retried by the caller (repainting here would fire a reconcile before
// that retry is booked and drop the pin), a failed unpin keeps the local
// value until the next real page, and the next page replaces them anyway.
unconfirmed.delete(id)
publishUnconfirmed()
throw err
}
)
}
/**
* Adopt the server's pin state for every row in the current page.
*
* Runs after the push pass so local intent is already fenced (`pending` /
* `unconfirmed`) by the time the page is read — a fresh local toggle whose
* PATCH hasn't landed yet must win over the stale row, not be reverted by it
* (#74570). Remote pins adopted here are marked mirrored before the local set
* changes, so the re-entrant reconcile doesn't echo them back as a PATCH.
*/
function pullRemotePins(): void {
const local = new Set($pinnedSessionIds.get())
for (const row of rowsByPinId(loadedSessionRows()).values()) {
// A backend without the flag has no opinion; never act on `undefined`.
if (typeof row.pinned !== 'boolean') {
continue
}
// Pins are keyed on the durable lineage root so they survive compression
// tip rotation; the row may surface under either identity.
const pinId = sessionPinId(row)
const heldLocally = local.has(pinId) || local.has(row.id)
// A write of ours this page may predate. Confirmed (page agrees) → release
// the guard, the server has caught up. Contradicted but still inside the
// cooldown → the page was almost certainly issued before our PATCH, so our
// write is newer: skip the row. Contradicted past the cooldown → no page
// ever confirmed us, so stop fencing and let the server win.
const guardKey = unconfirmed.has(pinId) ? pinId : unconfirmed.has(row.id) ? row.id : null
const guard = guardKey ? unconfirmed.get(guardKey) : undefined
if (guard && guardKey) {
if (isOptimisticRow(row)) {
// Our own painted row agrees by construction (as does any value copy
// of it — the marker is enumerable and spreads with the row), so it is
// not a confirmation. Let the cooldown retire the guard as usual; the
// row then matches the local set and the checks below are a no-op.
if (Date.now() - guard.at >= WRITE_GUARD_MS) {
unconfirmed.delete(guardKey)
}
} else if (guard.value === row.pinned) {
unconfirmed.delete(guardKey)
} else if (Date.now() - guard.at < WRITE_GUARD_MS) {
continue
} else {
unconfirmed.delete(guardKey)
}
}
// Local intent still waiting on its PATCH (row unresolved when the push
// pass ran) is also newer than the page — never revert it.
if (pending.has(pinId) || pending.has(row.id)) {
continue
}
if (row.pinned && !heldLocally) {
// Mark mirrored first: pinSession fires the pin listener synchronously,
// and the nested reconcile must not see this as a new pin to PATCH.
mirrored.add(pinId)
pinSession(pinId)
} else if (!row.pinned && heldLocally) {
// Same discipline on the way down: forget the mirror before the nested
// reconcile runs, or it re-PATCHes pinned=false the server already has.
mirrored.delete(pinId)
mirrored.delete(row.id)
unpinSession(local.has(pinId) ? pinId : row.id)
}
}
}
// Re-entrancy guard: reconcile() is subscribed to every loaded-session slice
// and $pinnedSessionIds, and pullRemotePins() mutates $pinnedSessionIds (via
// pinSession/unpinSession), which fires reconcile() again synchronously.
// Without this guard, a session whose pin state oscillates — two rows with the
// same durable id but conflicting `pinned` flags, possible when profile
// databases share session ids — drives an unbounded re-entrant loop that
// overflows nanostores' shared listenerQueue and crashes the renderer with
// `RangeError: Invalid array length`.
let reconciling = false
function reconcile(): void {
if (reconciling) {
return
}
reconciling = true
try {
reconcileInner()
} finally {
reconciling = false
// One publish per top-level pass: writePin adds guards and pullRemotePins
// retires them, and re-entrant calls above returned without touching either.
publishUnconfirmed()
}
}
function reconcileInner(): void {
// Config/session REST is only reachable through the Electron bridge.
if (!window.hermesDesktop) {
return
}
// Push before pull. The pin listener fires synchronously on a local toggle,
// so this reconcile runs before the PATCH for that toggle exists anywhere.
// The push pass below records the intent (`pending`, then `unconfirmed` via
// writePin) — only then may the pull read the page, where those fences stop
// the still-stale row from silently reverting the user's action (#74570).
const current = new Set($pinnedSessionIds.get())
// Unpinned: anything we were tracking that's no longer in the set.
for (const id of [...mirrored, ...pending]) {
if (!current.has(id)) {
mirrored.delete(id)
pending.delete(id)
// Removal owns the durable write; a separate unpin would race its
// revision snapshot. Archive clears the pin in the same PATCH.
if (!isSessionRemovalPending(id)) {
void writePin(id, false, profileFor(id)).catch(() => {})
}
}
}
// Newly pinned: hold until we can resolve the row (for its profile).
for (const id of current) {
if (!mirrored.has(id)) {
pending.add(id)
}
}
// Flush whatever we can resolve now; unresolved ids (row not loaded yet)
// retry on the next loaded-session slice change.
for (const id of [...pending]) {
const row = loadedRowFor(id)
if (!row) {
continue
}
pending.delete(id)
mirrored.add(id)
void writePin(id, true, row.profile).catch(() => {
// Let a later reconcile retry the mirror.
mirrored.delete(id)
pending.add(id)
})
}
pullRemotePins()
}
// Sync once, then re-sync on pin-set and session-list changes. Call once per app.
export function watchSessionPins(): void {
// A connection rescope repaints $pinnedSessionIds from the new backend's
// storage scope; the mirrored/pending/unconfirmed bookkeeping describes
// the PREVIOUS backend and must reset before that reload reconciles.
onConnectionScopeChange(resetSessionPinMirror)
reconcile()
$pinnedSessionIds.listen(reconcile)
$sessions.listen(reconcile)
$cronSessions.listen(reconcile)
$messagingSessions.listen(reconcile)
}
/**
* Forget what we've mirrored, because the backend we mirrored it TO is gone.
*
* `mirrored` / `pending` / `unconfirmed` all mean "relative to the gateway we
* are talking to". After a soft switch the next backend has its own state.db
* and has never seen these pins, but `mirrored` would report them as already
* pushed and suppress the PATCHes — so the user's pins silently fail to reach
* the new gateway (and its auto-archive sweep is free to hide them). Dropping
* the bookkeeping makes the next reconcile re-assert the whole set, which is
* the same path that migrates pre-existing pins at boot.
*/
export function resetSessionPinMirror(): void {
mirrored.clear()
pending.clear()
unconfirmed.clear()
publishUnconfirmed()
}
/**
* Forget one id's sync bookkeeping. The dead-session prune calls this before
* unpinning a pin whose session is gone, so the reconcile listener (fired
* synchronously by `unpinSession`) doesn't re-PATCH the dead id — which would
* produce exactly the 404 the prune exists to remove.
*/
export function forgetPinSyncState(id: string): void {
mirrored.delete(id)
pending.delete(id)
unconfirmed.delete(id)
}