The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import {
type ConnectionState,
type GatewayEvent,
isGatewayReauthRequired,
isStableOpen,
reconnectBackoffDelayMs,
registryBackendScopeKey,
resolveGatewayWsUrl,
type ServerRequest
} from '@hermes/shared'
import { atom } from 'nanostores'
import { canonicalOwnerProfile } from '@/api/canonical-protocol'
import type { HermesConnection } from '@/global'
import { HermesGateway, setApiRequestConnection } from '@/hermes'
import { translateNow } from '@/i18n'
import { UnservedProfileError } from '@/lib/browser-served-profiles'
import {
decideLivenessForceClose,
LIVENESS_REPROBE_DELAY_MS,
probeGatewayLiveness
} from '@/lib/gateway-liveness-policy'
import { isMissingRpcMethod } from '@/lib/gateway-rpc'
import { traceIdentityChange } from '@/lib/identity-trace'
import { isPermanentLocalGatewayEnsureError } from '@/lib/local-gateway-ensure-failure'
import { initialGatewayProfile } from '@/lib/platform'
import {
isTimeoutError,
RECONNECT_ATTEMPT_TIMEOUT_MS,
SOURCE_SWITCH_DIAL_TIMEOUT_MS,
withTimeout
} from '@/lib/with-timeout'
import { $gatewayActivationEpoch } from '@/store/gateway-activation-epoch'
import { isMissingConnectionError, isMissingProfileError } from '@/store/gateway-dial-failures'
import { isKeptRoute, keptRouteOpened } from '@/store/gateway-kept-routes'
import { $primaryGatewayRoute } from '@/store/gateway-primary-route'
import {
isPrimaryRider,
notePrimaryRider,
type PrimaryIdentity,
sharedPrimaryRoute
} from '@/store/gateway-shared-route'
import { notifyError, RECOVERY_ACTIONS } from '@/store/notifications'
import { markNativeNotifyBaseline } from '@/store/notify-baseline'
import { setConnection, setGatewayState } from '@/store/session'
import { stampSecondaryProfileOwner } from '@/store/session-event-provenance'
export { useGatewayActivationEpoch } from '@/store/gateway-activation-epoch'
// ── Multi-profile gateway routing ──────────────────────────────────────────
// Concurrent sessions across profiles need concurrent sockets: the renderer's
// event handler is already session-keyed, so the only thing stopping two
// profiles streaming at once was the single swapping socket. We keep that one
// socket as the PRIMARY (window) backend — owned by use-gateway-boot, with all
// its boot-progress / sleep-wake machinery — and add one persistent SECONDARY
// socket per *other* profile that has live work. Every socket feeds the same
// handleGatewayEvent, so background sessions keep painting. Single-profile users
// only ever have the primary, so their path is byte-for-byte unchanged.
const normKey = (profile: string | null | undefined): string => (profile ?? '').trim() || 'default'
// Dial intent callers attach to a user-initiated open. The canonical
// `hermes gateway ensure` path has no local slot pool, so the hint changes
// nothing about the dial itself; it survives as the option shape the SDK,
// Settings scopes and session creation pass so an explicit user gesture stays
// distinguishable from ambient hydration at the call site.
export type SpawnPriority = 'foreground' | 'background'
// Read connection state through a call so TS control-flow analysis doesn't
// narrow the getter to a constant across guards (it genuinely changes).
const isOpen = (gateway: HermesGateway | null): boolean => gateway?.connectionState === 'open'
interface RegistryConfig {
/** Electron's published descriptor is authoritative for a primary gateway's
* registry identity. Kept as a getter so gateway.ts does not own or duplicate
* the connection store. */
activeConnectionId?: () => null | string
onEvent: (event: GatewayEvent) => void
/** Server→client request (clarify, approval, …) from ANY socket the registry owns; the
* request's `respond` already routes to the socket it came from. `profile` /
* `connectionId` tag the source the same way events are tagged. */
onServerRequest?: (request: ScopedServerRequest) => void
onActiveConnectionInvalidated?: (fallbackProfile: string, activationEpoch: number) => void
onActiveConnectionChanged?: (connection: HermesConnection) => void
/**
* Fires whenever applyActive() moves the active route to a (possibly
* different) profile — including registry-internal eviction fallbacks
* (connection removal, profile delete) that no renderer call
* initiated. Consumers mirror this into $activeGatewayProfile so the
* published profile can never diverge from the socket actually selected
* (#89206: the stale-profile split-brain that stranded bot wake-ups).
*/
onActiveRouteChanged?: (profile: string) => void
/** Drop transient profile-pool runtime routes when local profile teardown
* permanently retires their owning secondary. Exact registry routes are
* deliberately outside this callback: a remote source may share the name. */
onLocalProfileRetired?: (profile: string) => void
/**
* Scopes a FOREGROUND surface is bound to right now — every mounted
* session tile's owner and the primary thread's (foregroundSessionScopes in
* store/session-states; a config hook because that store imports this
* one). Consulted by EVERY dispose path — the live-work pruner and the
* dispose-at-refcount-0 request/relay leases alike (#93892): a tile's
* resume mints its runtime on its owner's socket, and any path that closes
* that socket makes the backend orphan-reap the runtime, whose
* `session.reclaimed` unbinds the tile and re-arms its resume — a spinner
* loop with no terminal state. Read at decision time, never cached: it
* follows the tile set, so closing the tile releases the socket.
*/
foregroundScopes?: () => ReadonlySet<string>
/**
* Scopes with a running or needs-input session runtime, in the same key
* language as `foregroundScopes` (composite registry keys, bare profiles
* for local/legacy entries). The wake-path liveness probe counts these as
* in-flight work: prompt.submit returns before the turn ends, so
* `activeRequests` is 0 during most of a turn.
*/
liveScopes?: () => ReadonlySet<string>
}
// ── Secondary (pool) backends ──────────────────────────────────────────────
interface Secondary {
/** Scope key from registryBackendScopeKey(connectionId, profile). */
scope: string
profile: string
/** Registry connection serving this socket; null = the local/legacy path. */
connectionId: null | string
connection: HermesConnection | null
gateway: HermesGateway
/**
* Date.now() of the most recent socket 'open'. The live-work pruner's
* min-lifetime grace reads this: an idle prune can race an on-demand dial
* (prune → redial → prune) and close freshly opened sockets before their
* consumer registers in the keep-set, re-triggering the orphan-reap /
* remount loop (#94769). 0 = never opened.
*/
lastOpenedAt: number
/** Date.now() of the CURRENT socket's 'open'; null while not open. Stability
* clock for the backoff reset (#83134) — `lastOpenedAt` persists across
* closes and would make every failed redial look like a stable session. */
openedAt: null | number
activeRequests: number
connectPromise: Promise<void> | null
offEvent: () => void
offRequest: () => void
offState: () => void
reconnectTimer: ReturnType<typeof setTimeout> | null
reconnectAttempt: number
/**
* Consecutive unanswered wake-probe pings on this entry's current socket;
* drives the same streak tolerance the primary's probe applies
* (decideLivenessForceClose). Reset on every answered probe and on every
* fresh socket open.
*/
livenessProbeFailures: number
/** Pending deferred liveness re-probe after an in-flight-work deferral. */
livenessReprobeTimer: ReturnType<typeof setTimeout> | null
/** Consecutive automatic dials that stalled (slot wait / dial timeout)
* rather than failing fast; see SECONDARY_STALLED_DIAL_BUDGET. */
stalledDials: number
reconnecting: boolean
/** A material connection edit is waiting for live owners to drain. */
pendingConnectionRedial: boolean
/**
* True when a foreground/prewarmed consumer owns this entry beyond one RPC.
* Guards ONLY the dispose-at-refcount-0 paths (request/relay leases), never
* the live-work pruner: it is a one-way latch that every hover pre-warm and
* profile switch sets and nothing ever clears, so honoring it in
* pruneSecondaryGateways would pin every socket ever warmed. A foreground
* surface that must keep its owner socket (a mounted session tile, the
* primary thread) is represented in the pruner's keep-set instead — see
* foregroundSessionScopes in store/session-states (#93892).
*/
retained: boolean
/**
* Bot-relay retainers pinning this socket open across drain ticks (#93594).
* The relay's drain loop RPCs every registered connection on an interval;
* without retention each tick dialed and tore down a fresh WebSocket per
* connection (refcount hit 0 → dispose). Counted, not boolean, so relay
* retention can never clobber (or be clobbered by) the foreground
* `retained` flag. Only non-local registry routes are ever counted here —
* see retainGatewayForRelay.
*/
relayRetainCount: number
// While true the entry auto-reconnects on drop; pruning flips it off so a
// deliberate close doesn't trigger the backoff loop.
wantOpen: boolean
/**
* Epoch-ms deadline while an activation (prepare/ensure) is mid-dial. The
* live-work pruner must not dispose an entry the user is switching to: a
* switch target is not yet the active key, has no live sessions and holds
* no request lease, so during a cold pool spawn (~3s) every prune recompute
* saw it as idle garbage and disposed it mid-dial — the root of the dead
* profile clicks in #89622. Cleared when the activation settles; bounded so
* an orphaned lease self-heals.
*/
activationLeaseUntil: number
}
// How long a mid-dial activation holds its prune lease: it must outlast every
// dial the renderer still treats as in flight, or the pruner reaps the switch
// target mid-dial and the click resolves on a socket that is already closed
// (#89622's mechanism, one budget change later). The activation dials now carry
// SOURCE_SWITCH_DIAL_TIMEOUT_MS — the whole remote bring-up chain (ssh connect,
// the platform/locate/version probes, the remote spawn's ready sentinel, the
// forward) — so this is DERIVED from it rather than picked independently: at
// the old 30 s literal, raising the dial budget to 135 s left the switch target
// prunable for the last ~105 s of a *healthy* dial. The margin covers the
// settle that releases the lease (the renderer's switch commit). Bounded on
// purpose: a leaked lease still expires on its own and the reaper reclaims the
// entry.
const ACTIVATION_LEASE_MS = SOURCE_SWITCH_DIAL_TIMEOUT_MS + 15_000
// ── HMR-stable module state ─────────────────────────────────────────────────
// All mutable singletons (live sockets, active-profile routing, the event
// registry) live in ONE container parked on globalThis, NOT in module-level
// `let`/`const` bindings. Reason: this module is imported widely without an HMR
// boundary that accepts it, so editing it (or anything that fans out to it)
// makes Vite issue a FULL PAGE RELOAD — which would kill every live socket and
// drop the agent session on an unrelated edit. Persisting the state on
// globalThis + self-accepting HMR (bottom of file) turns that full reload into
// an in-place hot update that preserves the sockets. Production strips
// import.meta.hot, and a fresh page realm starts with an empty container, so the
// runtime behavior is identical to plain module state.
interface GatewayRegistryState {
config: RegistryConfig | null
primaryGateway: HermesGateway | null
primaryProfile: string
activeKey: string
secondaries: Map<string, Secondary>
// Auth rejection outlives the disposable socket, including background request leases.
reauthFailures: Map<string, { connectionId: string | null; error: Error }>
// Dial failures outlive the disposable socket too: a background request lease disposes its
// entry on failure, so history kept on the entry reset on every poll (#121865).
dialFailures: Map<string, { at: number; streak: number; connectionId: string | null }>
/** Scopes that opened in this renderer generation, even if later pruned. */
openedSecondaryScopes?: Set<string>
/** Scopes whose re-activation after a connection redial has not landed yet. */
reactivatingScopes?: Set<string>
/** Routed prompt sockets held until their terminal turn event arrives. */
turnLeases: Map<string, () => void>
/** Debounced releases so an immediate chained turn can reuse its lease. */
turnLeaseReleaseTimers: Map<string, ReturnType<typeof setTimeout>>
$gateway: ReturnType<typeof atom<HermesGateway | null>>
$activeProfile: ReturnType<typeof atom<string>>
}
const STATE_KEY = Symbol.for('hermes.desktop.gatewayRegistryState')
function createRegistryState(): GatewayRegistryState {
return {
config: null,
primaryGateway: null,
primaryProfile: initialGatewayProfile(),
activeKey: initialGatewayProfile(),
secondaries: new Map<string, Secondary>(),
reauthFailures: new Map(),
dialFailures: new Map(),
openedSecondaryScopes: new Set<string>(),
reactivatingScopes: new Set<string>(),
turnLeases: new Map<string, () => void>(),
turnLeaseReleaseTimers: new Map<string, ReturnType<typeof setTimeout>>(),
// The active gateway instance, exposed for inline message-stream
// components (inline ClarifyTool, model overlays) that call gateway
// methods without the instance threaded down through props.
$gateway: atom<HermesGateway | null>(null),
// The PROFILE the active gateway is routed to (bare profile name, never a
// composite registry scope). Owned exclusively by applyActive() so the
// published profile can never diverge from the socket actually selected —
// the split-brain where an eviction re-pointed activeKey at the primary
// while the profile atom kept naming the evicted bot routed every
// "loki" session.resume to the default backend (#89206 wake failures).
$activeProfile: atom<string>(initialGatewayProfile())
}
}
// Dev only: park the singletons on globalThis so an HMR re-eval of this module
// (self-accepted at the bottom) hands back the SAME live sockets/atoms instead
// of resetting them — that's what keeps the agent session alive across UI edits.
// `import.meta.hot` is undefined in production, so Vite dead-code-eliminates the
// entire globalThis branch and prod uses a plain module-local singleton — no
// globalThis, no Symbol.for. Both realms load the module once, so the container's
// shape and lifetime are identical either way.
function gatewayState(): GatewayRegistryState {
if (import.meta.hot) {
const store = globalThis as unknown as { [STATE_KEY]?: GatewayRegistryState }
store[STATE_KEY] ??= createRegistryState()
// Existing dev-HMR containers predate whole-turn leases.
store[STATE_KEY].reauthFailures ??= new Map()
store[STATE_KEY].dialFailures ??= new Map()
store[STATE_KEY].turnLeases ??= new Map()
store[STATE_KEY].turnLeaseReleaseTimers ??= new Map()
return store[STATE_KEY]
}
return createRegistryState()
}
const g = gatewayState()
// Dev HMR can hand a newer module an older state-container shape. Keep the
// generation ledger lazy so an already-open socket still survives the update.
const openedSecondaryScopes = (): Set<string> => (g.openedSecondaryScopes ??= new Set<string>())
// Dev-HMR states predate this field, so read it through the same lazy accessor pattern.
const reactivatingScopes = (): Set<string> => (g.reactivatingScopes ??= new Set<string>())
// Re-exported as a stable binding: the atom instance lives in `g`, so every hot
// reload of this module hands back the SAME atom subscribers are already wired
// to. (A fresh `atom()` per reload would orphan existing subscriptions.)
export const $gateway = g.$gateway
// The profile the ACTIVE gateway is actually routed to. Registry-owned: the
// only writer is applyActive(), which sets it in the same synchronous step
// that selects the socket — so a consumer that reads this and then calls
// activeGateway() always gets a matching (profile, socket) pair. Renderer
// surfaces (store/profile.ts's $activeGatewayProfile) mirror this atom
// instead of writing their own copy.
export const $activeGatewayRoute = g.$activeProfile
/** Bare profile name the active gateway serves (never a composite scope). */
export function activeGatewayProfileKey(): string {
return g.$activeProfile.get()
}
/** Never dials or asks main: the socket a request for (connectionId, profile)
* would ride (`primary:<profile>` for the window primary and profiles known to
* share its backend, else the pooled scope) and whether it is open right now. */
export function gatewayRouteState(connectionId: null | string, profile: string): { key: string; open: boolean } {
const key = normKey(profile)
const scope = registryBackendScopeKey(connectionId, key)
const onPrimary = key === g.primaryProfile && (scope === key || isPrimaryRegistryRoute(connectionId, key))
if (onPrimary || isPrimaryRider(scope, primaryIdentity())) {
return { key: `primary:${key}`, open: isOpen(g.primaryGateway) }
}
return { key: scope, open: isOpen(g.secondaries.get(scope)?.gateway ?? null) }
}
export function configureGatewayRegistry(cfg: RegistryConfig): void {
g.config = cfg
}
/**
* Feed a synthetic event through the exact same fan-out a real socket frame
* takes (`config.onEvent` → the desktop's `handleGatewayEvent`). Used by
* dev-only tooling to exercise the real event branches (e.g. the credit-notice
* demo) without a backend that can produce the event on demand. No-op until a
* registry is configured.
*/
export function emitLocalGatewayEvent(event: GatewayEvent): void {
g.config?.onEvent(event)
}
/** A server→client request tagged with the registry source it arrived from (like `GatewayEvent.profile`). */
export interface ScopedServerRequest extends ServerRequest {
connectionId?: string
profile: string
}
/**
* Route a server→client request into the registry handler with its source tags.
* Fail fast, never swallow: the backend blocks on this answer (clarify waits
* its full 3600s deadline). Without a registry there is nobody to answer —
* returning `false` lets the channel answer -32601 immediately instead of
* stalling the turn (it also fires the client's `onUnhandledRequest` sink).
*/
function dispatchServerRequest(request: ServerRequest, profile: string, connectionId: null | string): boolean {
if (!g.config?.onServerRequest) {
return false
}
g.config.onServerRequest({ ...request, ...(connectionId ? { connectionId } : {}), profile: canonicalOwnerProfile(request) ?? profile })
return true
}
/** Fan a primary-socket server request into the registry handler with the active source tags. */
export function dispatchPrimaryServerRequest(request: ServerRequest, profile: string): boolean {
return dispatchServerRequest(request, profile, g.config?.activeConnectionId?.() ?? null)
}
/** Registry source currently served by the window primary socket, when known. */
function primaryConnectionId(): null | string {
return $primaryGatewayRoute.get().connectionId
}
// Taken BEFORE a route await, so a hint learned across a re-home stays bound
// to the primary the route was resolved against.
const primaryIdentity = (): PrimaryIdentity => ({ connectionId: primaryConnectionId(), gateway: g.primaryGateway })
export function setPrimaryGateway(gateway: HermesGateway | null, profile = 'default'): void {
const next = normKey(profile)
if (g.primaryGateway !== gateway) {
$primaryGatewayRoute.set({ connectionId: null, mode: null })
}
// Route identity is exact-scope, never bare-name (#93892 follow-up): when
// the active route IS the primary and the primary re-homes to another
// profile, the active key must follow it. Leaving the old bare profile name
// behind lets a later same-named LOCAL secondary inherit the active-route
// spare in pruneSecondaryGateways — a remote tile keep-set of composite
// scopes then appears to "pin" that unrelated local socket forever.
if (g.activeKey === g.primaryProfile) {
g.activeKey = next
}
g.primaryGateway = gateway
g.primaryProfile = next
if (g.activeKey === g.primaryProfile) {
setApiRequestConnection(primaryConnectionId())
}
}
export function setPrimaryGatewayConnectionId(
connectionId: null | string | undefined,
mode: 'local' | 'remote' | null | undefined = undefined
): void {
// Every caller publishes the window's OWN primary socket (boot, reconnect,
// connection apply, HMR survivor), so record it even while a secondary is
// foregrounded. Refusing it there left the primary route naming the
// machine the primary socket had just left, and owner routing then sent
// that machine's requests to the other one. What belongs to the active
// scope is the AMBIENT request connection (#95628), which moves only while
// the primary is in front.
const id = (connectionId ?? '').trim() || null
const primaryMode = mode === 'local' || mode === 'remote' ? mode : null
$primaryGatewayRoute.set({ connectionId: id, mode: primaryMode })
if (g.activeKey === g.primaryProfile) {
setApiRequestConnection(id)
}
}
/**
* Mode of the socket this window already dialed for `(connectionId, profile)`,
* following gatewayForProfile's precedence: the primary socket when it serves
* that profile, else a secondary's own descriptor. Null until one is dialed.
*/
export function dialedGatewayModeFor(connectionId: null | string, profile: string): 'local' | 'remote' | null {
const id = String(connectionId ?? '').trim() || null
const key = normKey(profile)
const primary = $primaryGatewayRoute.get()
if (key === g.primaryProfile && (!id || id === primary.connectionId) && primary.mode) {
return primary.mode
}
const mode = g.secondaries.get(registryBackendScopeKey(id, key))?.connection?.mode
return mode === 'local' || mode === 'remote' ? mode : null
}
/** Publish the registry source owned by the window primary socket. */
export function setPrimaryGatewayConnection(connection: Pick<HermesConnection, 'connectionId' | 'mode'> | null): void {
setPrimaryGatewayConnectionId(connection?.connectionId, connection?.mode)
}
function traceAgentRoute(scope: string, via: string): void {
traceIdentityChange('gateway-route', scope, `via=${via} primary=${primaryConnectionId() ?? '-'}/${g.primaryProfile}`)
}
function isPrimaryRegistryRoute(connectionId: null | string, profile: string): boolean {
const id = String(connectionId ?? '').trim()
return normKey(profile) === g.primaryProfile && Boolean(id) && id === primaryConnectionId()
}
/** True when `connectionId` is the window's already-attached source AND main
* says `profile` rides the backend that source's primary socket is already
* connected to — a one-host-many-profiles remote (`sharedRemote`, #96493) or
* the one local host backend that serves every local profile under
* multiplex-only (`sharedPrimary`, #118246). Either way a registry secondary
* would be a SECOND WebSocket to the SAME process: on a remote it accept/closes
* in ~30ms and never runs `session.create`; on the local host backend it joins
* the chat's transport fan-out and the renderer receives every event twice
* (garbled streaming text + a duplicate interim bubble, #120005). Isolated
* SSH/pooled backends (neither flag) still get their own secondary. */
async function ridesPrimaryBackend(connectionId: null | string, profile: string): Promise<boolean> {
const id = String(connectionId ?? '').trim()
const key = normKey(profile)
if (!id || id !== primaryConnectionId()) {
return false
}
if (isPrimaryRegistryRoute(id, key)) {
return false
}
const desktop = window.hermesDesktop
if (!desktop?.getConnectionFor) {
return false
}
// Resolved per call, never cached: main answers the route per request
// (`resolveProfileBackendRoute` case 6 keeps a pooled backend for
// `HERMES_DESKTOP_ISOLATED_BACKEND=1`), and for a pooled profile this is the
// same dial `openSecondary` makes next, coalesced by main's claim key.
try {
const conn = await withTimeout(
desktop.getConnectionFor({ connectionId: id, profile: key }),
RECONNECT_ATTEMPT_TIMEOUT_MS,
`Timed out resolving the backend route for "${key}"`
)
const flags =
conn && typeof conn === 'object' ? (conn as { sharedPrimary?: boolean; sharedRemote?: boolean }) : null
return flags?.sharedRemote === true || flags?.sharedPrimary === true
} catch {
// Probe failed on a remote (or not-yet-classified) primary: a secondary at
// this already-attached source is the #96493 ghost WebSocket (accept/close,
// messages=1), so prefer the primary until a later probe can prove
// isolation (`sharedRemote: false`). A LOCAL primary must NOT get that
// fallback: when main routes the profile to a pooled child (isolated
// backend), the primary would still ACCEPT a `profile`-tagged
// session.create (profile_home multiplexing) and mint the session under
// its own pid, but the exact-owner route names the pool backend — after a
// renderer reload or a pool respawn the resume dials that backend and is
// refused SESSION_NOT_OWNED by a pid of the same Desktop (#101416).
return $primaryGatewayRoute.get().mode !== 'local'
}
}
async function requestOnPrimaryGateway<T>(
method: string,
params: Record<string, unknown>,
timeoutMs?: number,
signal?: AbortSignal
): Promise<T> {
const gateway = g.primaryGateway
if (!gateway || !isOpen(gateway)) {
throw new Error('Hermes gateway unavailable')
}
return timeoutMs === undefined && signal === undefined
? gateway.request<T>(method, params)
: gateway.request<T>(method, params, timeoutMs, signal)
}
export function isActivePrimary(): boolean {
return g.activeKey === g.primaryProfile
}
/** Changes on every active route selection, including same-profile source swaps. */
export function gatewayActivationEpoch(): number {
return Number.isFinite($gatewayActivationEpoch.get()) ? $gatewayActivationEpoch.get() : 0
}
export function activeGateway(): HermesGateway | null {
if (g.activeKey === g.primaryProfile) {
return g.primaryGateway
}
// A named scope resolves to ITS socket or nothing. Falling back to the
// primary here would silently route calls (sends, session ops, roster
// requests) to the WRONG backend whenever the scope's entry is gone —
// teardown sites keep the invariant "activeKey always resolves" by
// re-pointing the active key at the primary when they evict it.
return g.secondaries.get(g.activeKey)?.gateway ?? null
}
/** Passive ordering barrier for a runtime's transcript reads. Inspect only
* existing sockets: waiting must never dial, activate, or retain a backend.
* Each client names its own replaying runtime IDs; no ambient route is used
* to decide which session's events are safe to paint over. A pruned
* secondary keeps its closed socket's watermarks but will never reopen to
* replay them, so it must not veto reads forever. */
export function pendingSessionReplay(runtimeId: string): Promise<boolean> | undefined {
const reconnectable = [...g.secondaries.values()].filter(entry => entry.wantOpen)
const clients = new Set([g.primaryGateway, ...reconnectable.map(entry => entry.gateway)])
// A closed socket's false means only that IT cannot replay yet. When another
// open socket already serves this runtime, that socket orders the read.
const servedOpen = [...clients].some(client => isOpen(client) && client?.getSeqWatermarks?.()[runtimeId] != null)
const pending = [...clients].flatMap(client => {
if (servedOpen && !isOpen(client)) {
return []
}
// A dev-HMR survivor can predate the barrier method.
const barrier = client?.sessionReplayBarrier?.(runtimeId)
return barrier ? [barrier] : []
})
return pending.length ? Promise.all(pending).then(results => results.every(Boolean)) : undefined
}
/**
* The registry connection serving the gateway the user is currently looking
* at. A registry-backed primary takes its identity from the published primary
* connection, falling back to Electron's active descriptor until that is set;
* a true legacy primary (no resolved connectionId) and profile-keyed local
* secondaries remain null. Event consumers pair this with the event's own
* `connectionId` tag so "from the active profile" really means "from the active SOURCE":
* two connected gateways can both expose a 'default' profile, and a bare
* profile comparison attributed gateway B's 'default' activity to gateway A.
*/
export function activeGatewayConnectionId(): null | string {
if (g.activeKey === g.primaryProfile) {
return primaryConnectionId() ?? (g.config?.activeConnectionId?.()?.trim() || null)
}
return g.secondaries.get(g.activeKey)?.connectionId ?? null
}
/**
* Registry connections currently served by a live (open-socket) secondary.
* Used by the reconnect path when the restarted primary's own registry
* identity is unknown: Bot runtimes owned by these connections are provably
* NOT the restarted backend and keep their bindings; everything else re-resumes.
*/
export function liveSecondaryConnectionIds(): Set<string> {
const live = new Set<string>()
for (const entry of g.secondaries.values()) {
if (entry.connectionId && isOpen(entry.gateway)) {
live.add(entry.connectionId)
}
}
return live
}
// Mirror a backend's connection state into the global composer state, but only
// when that backend is the one the user is currently looking at. Lets the
// composer reflect the active profile's socket without a background reconnect
// flipping the foreground enabled/disabled state.
function reportGatewayState(profile: string, state: ConnectionState): void {
// Any socket opening replays parked prompts; hold OS notifications so a
// launch/reconnect doesn't alert about state that already existed.
if (state === 'open') {
markNativeNotifyBaseline()
}
if (normKey(profile) === g.activeKey) {
setGatewayState(state)
}
}
export function reportPrimaryGatewayState(state: ConnectionState): void {
reportGatewayState(g.primaryProfile, state)
}
function setActive(profile: string): void {
const activationEpoch = beginGatewayActivation()
applyActive(profile, activationEpoch)
}
function beginGatewayActivation(): number {
$gatewayActivationEpoch.set(gatewayActivationEpoch() + 1)
return $gatewayActivationEpoch.get()
}
function applyActive(profile: string, activationEpoch: number): boolean {
if (gatewayActivationEpoch() !== activationEpoch) {
return false
}
g.activeKey = normKey(profile)
const gateway = activeGateway()
g.$gateway.set(gateway)
setGatewayState(gateway?.connectionState ?? 'closed')
// Push the active scope's registry connection into the hermes module (null
// for the local pool) so connection-building WS calls (pluginSocket) resolve
// through the same source of truth every activation path maintains here —
// registry-agent activations included, not just profile switches.
setApiRequestConnection(activeGatewayConnectionId())
// Publish the BARE profile this route serves, in the same synchronous step
// as the socket selection. activeKey may be a composite registry scope
// (connectionId::profile); consumers route RPCs by profile, so resolve it
// through the secondary's own record. This atom is the single source of
// truth for "which profile is the active gateway on" — every eviction /
// fallback path funnels through applyActive, so the published profile can
// never linger on a backend that is no longer selected (#89206).
const routeProfile =
g.activeKey === g.primaryProfile ? g.primaryProfile : (g.secondaries.get(g.activeKey)?.profile ?? g.primaryProfile)
g.$activeProfile.set(routeProfile)
g.config?.onActiveRouteChanged?.(routeProfile)
traceIdentityChange(
'gateway-route',
'active',
`key=${g.activeKey} via=${g.activeKey === g.primaryProfile ? 'primary' : 'secondary'} conn=${activeGatewayConnectionId() ?? '-'} profile=${routeProfile}`
)
return true
}
function publishActiveConnection(connection: HermesConnection): void {
if (g.config?.onActiveConnectionChanged) {
g.config.onActiveConnectionChanged(connection)
} else {
setConnection(connection)
}
}
function clearTimer(entry: Secondary): void {
if (entry.reconnectTimer !== null) {
clearTimeout(entry.reconnectTimer)
entry.reconnectTimer = null
}
}
async function openSecondary(entry: Secondary): Promise<void> {
const desktop = window.hermesDesktop
const reauthError = g.reauthFailures.get(entry.scope)?.error
if (reauthError) {
throw reauthError
}
if (!desktop) {
return
}
if (entry.connectPromise) {
await entry.connectPromise
return
}
const pending = (async () => {
// A secondary can be reopened directly by the next routed user action,
// without passing through reconnectSecondary(). Its previous backend may
// have been respawned, so every stored→runtime binding for this exact scope
// is process-local stale state. Invalidate BEFORE connect publishes `open`:
// otherwise an eager route effect / submit can send the old runtime id in
// the narrow window between the new socket opening and post-connect cleanup.
//
// Dynamic import keeps the existing session-states → gateway module cycle
// open. Awaiting it is intentional: correctness at the generation boundary
// outranks the single local-module microtask this adds to a reconnect.
const openedScopes = openedSecondaryScopes()
const reopening = entry.lastOpenedAt > 0 || entry.connection !== null || openedScopes.has(entry.scope)
let reconcileBusyAfterOpen: null | (() => void) = null
if (reopening) {
try {
const { reconcileBusyStatesOnReconnect, resetRouteOwnedTileRuntimeBindings, resetTileRuntimeBindings } =
await import('@/store/session-states')
const scope = { connectionId: entry.connectionId || 'local', profile: entry.profile }
// Only the window's ambient gateway carries un-owned tiles and the main
// thread. A background route (e.g. a relay request lease that disposed
// its socket after the last tick) can only have minted runtimes for
// tiles that name it as their owner route.
if (g.activeKey === entry.scope) {
resetTileRuntimeBindings(scope)
} else {
resetRouteOwnedTileRuntimeBindings(scope)
}
reconcileBusyAfterOpen = () => reconcileBusyStatesOnReconnect(entry.scope)
} catch {
// Best effort for partial test/HMR graphs. Production always loads the
// real store; a failed import must not make the transport unrecoverable.
}
}
// Registry-scoped entries dial through getConnectionFor when the bridge has
// it. Local/legacy entries retain the existing getConnection path. Both are
// IPC round-trips into the main process with no timeout of their own
// (#93454) — a wedged main-process round-trip otherwise hangs this await
// forever, latching entry.connectPromise so every routed action against
// this secondary (SSH terminal, messaging DELETE, session send, …) never
// settles either. Bound the same way use-gateway-boot.ts bounds the
// primary's equivalent awaits.
//
// Two bring-ups with different legitimate worst cases: a registry route is a
// backend coming up on ANOTHER machine (ssh connect + probes + remote spawn +
// ready sentinel), which is the SOURCE_SWITCH_DIAL budget, while a local
// profile's pooled child spawns on this machine (measured ~9 s; the
// reconnect-class budget is not the binding constraint there).
const conn =
entry.connectionId && desktop.getConnectionFor
? await withTimeout(
desktop.getConnectionFor({ connectionId: entry.connectionId, profile: entry.profile }),
SOURCE_SWITCH_DIAL_TIMEOUT_MS,
`Timed out connecting to profile "${entry.profile}"`
)
: await withTimeout(
desktop.getConnection(entry.profile),
RECONNECT_ATTEMPT_TIMEOUT_MS,
`Timed out connecting to profile "${entry.profile}"`
)
entry.connection = conn
const wsDeps =
entry.connectionId && desktop.getGatewayWsUrlFor
? {
getGatewayWsUrl: () =>
desktop.getGatewayWsUrlFor!({ connectionId: entry.connectionId, profile: entry.profile })
}
: entry.connectionId
? {}
: desktop
const wsUrl = await withTimeout(
resolveGatewayWsUrl(wsDeps, conn),
RECONNECT_ATTEMPT_TIMEOUT_MS,
`Timed out re-minting the gateway WebSocket URL for profile "${entry.profile}"`
)
try {
await entry.gateway.connect(wsUrl)
} catch (error) {
// Log the dial target for support, but RETHROW THE ORIGINAL ERROR —
// reconnectSecondary classifies failures by message ("No connection
// with id", "no longer exists") to fail-stop permanent conditions, and
// wrapping here would break that. Callers decide surfacing (#81094).
console.error(`[gateway] dial failed for scope="${entry.scope}" profile="${entry.profile}":`, error)
throw error
}
entry.lastOpenedAt = Date.now()
// A fresh socket owes nothing to a previous socket's missed pings.
entry.livenessProbeFailures = 0
clearSecondaryLivenessReprobe(entry)
openedScopes.add(entry.scope)
keptRouteOpened(entry.connectionId, entry.profile)
try {
reconcileBusyAfterOpen?.()
} catch {
// The socket is already open. A best-effort UI-state reconcile must not
// turn that successful transport recovery into a reported dial failure.
}
if (!entry.wantOpen) {
entry.gateway.close()
return
}
if (g.activeKey === entry.scope) {
publishActiveConnection(conn)
}
})()
entry.connectPromise = pending
try {
await pending
} catch (error) {
if (isGatewayReauthRequired(error) && g.secondaries.get(entry.scope) === entry) {
g.reauthFailures.set(entry.scope, { connectionId: entry.connectionId, error })
entry.wantOpen = false
clearTimer(entry)
}
// Parked here, where every dial lands, so not even the first scheduled redial runs.
if (error instanceof UnservedProfileError) {
entry.wantOpen = false
clearTimer(entry)
}
throw error
} finally {
if (entry.connectPromise === pending) {
entry.connectPromise = null
}
}
}
// Consecutive STALLED automatic dials (a pool-slot wait or the 20s dial
// timeout, never a fast transport error) before a secondary parks. A
// tile-pinned scope stays wantOpen for the tile's lifetime, so an owner
// backend that keeps losing its slot wait otherwise re-queues a background
// spawn on every backoff tick forever — the queue/timeout treadmill in
// #103375. Fast failures (a gateway restarting, ECONNREFUSED) keep the
// ordinary unbounded backoff: they cost nothing and the socket must come back
// on its own. Parking keeps the entry; any explicit open of the scope
// (requestGatewayForAgent, openGatewayForAgent, ensureGatewayForAgent,
// ensureActiveGatewayOpen) re-arms it with a fresh budget.
const SECONDARY_STALLED_DIAL_BUDGET = 3
function isStalledDialError(error: unknown): boolean {
if (isTimeoutError(error)) {
return true
}
const message = error instanceof Error ? error.message : String(error ?? '')
return message.includes('timed out while waiting for a free slot')
}
function rearmSecondary(entry: Secondary, priority: SpawnPriority = 'foreground'): void {
const reauthError = g.reauthFailures.get(entry.scope)?.error
if (reauthError && priority !== 'foreground') {
throw reauthError
}
g.reauthFailures.delete(entry.scope)
// Only an explicit (foreground) re-arm resets dial history: every background request rearms
// its scope before dialing, so clearing it here would lift the throttle on each poll.
if (priority === 'foreground') {
g.dialFailures.delete(entry.scope)
}
entry.wantOpen = true
entry.stalledDials = 0
}
function recordDialFailure(entry: Secondary, error?: unknown): void {
// Auth rejection has its own ledger (reauthFailures) that already fails background callers fast.
if (error !== undefined && isGatewayReauthRequired(error)) {
return
}
const previous = g.dialFailures.get(entry.scope)
g.dialFailures.set(entry.scope, {
at: Date.now(),
streak: (previous?.streak ?? 0) + 1,
connectionId: entry.connectionId ?? null
})
}
/** True while a background caller must leave redialing to the ladder: the scope's last dial
* failed (or its socket died before RECONNECT_STABLE_OPEN_MS) inside a window that widens with
* the failure streak, on the same ceilings as the reconnect ladder. History clears on proof of
* health (a served RPC, or a socket that lived) and on a fresh start (foreground re-arm, connection
* removal, full teardown) — never on a bare open, so an accept-then-close backend keeps escalating. */
function backgroundDialCoolingDown(scope: string, now = Date.now()): boolean {
const failure = g.dialFailures.get(scope)
return failure !== undefined && now - failure.at < reconnectBackoffDelayMs(failure.streak - 1, { jitter: false })
}
/** Dial a request's secondary if it is down. Both request paths (a plain profile via
* gatewayForProfile, a registry route via requestGatewayForAgent) used to dial straight past
* the reconnect ladder, and openSecondary only coalesces CONCURRENT dials, so a poller against
* a scope whose socket accepts and then dies redialed once per tick (session.control.read on a
* cross-profile session, #121865). After a failure, background callers fail fast and leave
* redialing to scheduleReconnect; a user action (foreground) still dials at once. */
async function openSecondaryForRequest(entry: Secondary, spawnPriority: SpawnPriority): Promise<void> {
if (isOpen(entry.gateway)) {
return
}
if (spawnPriority !== 'foreground' && backgroundDialCoolingDown(entry.scope)) {
scheduleReconnect(entry)
throw new Error(`Backend for "${entry.profile}" is reconnecting; retry after it settles.`)
}
try {
await openSecondary(entry)
} catch (error) {
recordDialFailure(entry, error)
throw error
}
}
function scheduleReconnect(entry: Secondary): void {
if (entry.reconnecting || entry.reconnectTimer !== null || !entry.wantOpen) {
return
}
// Full-jitter exponential backoff — same shape (and same reason: avoid a
// reconnect storm against a restarting gateway) as the primary's.
const delay = reconnectBackoffDelayMs(entry.reconnectAttempt)
entry.reconnectAttempt += 1
entry.reconnectTimer = setTimeout(() => {
entry.reconnectTimer = null
void reconnectSecondary(entry)
}, delay)
}
async function reconnectSecondary(entry: Secondary): Promise<void> {
if (entry.reconnecting || !entry.wantOpen || isOpen(entry.gateway)) {
return
}
entry.reconnecting = true
try {
await openSecondary(entry)
} catch (error) {
// Restart the background-request cooldown from the ladder's own failure too, or a poll
// could slip a dial in between two ladder attempts on an older, expired window.
recordDialFailure(entry, error)
if (isGatewayReauthRequired(error)) {
notifyError(error, translateNow('boot.errors.gatewaySignInRequired'), { action: RECOVERY_ACTIONS.openGateways() })
return
}
// The registry no longer knows this connection (removed while we were
// backing off), or Electron's deletion guard reports the profile itself
// gone/mid-delete. Both are permanent for this scoped socket — retrying
// forever can never succeed and hammers the spawn guard every backoff
// tick (#88769). Fail-stop: dispose the entry and evict it instead of an
// infinite 15s-cap retry loop.
if ((entry.connectionId && isMissingConnectionError(error)) || isMissingProfileError(error)) {
entry.reconnecting = false
disposeSecondary(entry)
if (g.secondaries.get(entry.scope) === entry) {
g.secondaries.delete(entry.scope)
}
restoreActiveToPrimaryIfEvicted()
return
}
// An ensure refusal no redial can fix (incompatible runtime, no ensure protocol, an invalid
// endpoint, an unsafe control path): each automatic redial would spawn another
// `hermes gateway ensure` against the same install forever. Park at once, keeping the entry:
// an explicit open, focus/wake nudge or Reconnect re-arms it after the user's repair.
if (isPermanentLocalGatewayEnsureError(error)) {
console.warn(`[gateway] parking scope="${entry.scope}": local gateway ensure refused permanently`, error)
entry.wantOpen = false
entry.stalledDials = 0
} else if (isStalledDialError(error)) {
// Only a successful open resets the stall budget (the 'open' state
// listener): a treadmill that alternates slot-wait timeouts with a
// spawned-but-unresponsive socket must still run out of budget.
entry.stalledDials += 1
if (entry.stalledDials >= SECONDARY_STALLED_DIAL_BUDGET) {
console.warn(
`[gateway] parking scope="${entry.scope}" after ${entry.stalledDials} stalled dials; the next open or wake nudge redials it`
)
entry.wantOpen = false
entry.stalledDials = 0
}
}
// Still wantOpen → fall through to the backoff below.
} finally {
entry.reconnecting = false
if (entry.wantOpen && !isOpen(entry.gateway)) {
scheduleReconnect(entry)
}
}
}
function createSecondary(profile: string, connectionId: null | string = null): Secondary {
const gateway = new HermesGateway()
const scope = registryBackendScopeKey(connectionId, profile)
const entry: Secondary = {
scope,
profile,
connectionId,
connection: null,
gateway,
lastOpenedAt: 0,
openedAt: null,
activeRequests: 0,
connectPromise: null,
offEvent: () => {},
offRequest: () => {},
offState: () => {},
reconnectTimer: null,
reconnectAttempt: 0,
livenessProbeFailures: 0,
livenessReprobeTimer: null,
stalledDials: 0,
reconnecting: false,
pendingConnectionRedial: false,
retained: false,
relayRetainCount: 0,
wantOpen: true,
activationLeaseUntil: 0
}
// Canonical adapters prove the owner from their attachment; legacy pooled
// sockets prove it through this closure. Stamp before registry fan-in,
// never promote an arbitrary wire `profile` field into ownership.
entry.offEvent = gateway.onEvent(event => {
const scopedEvent = stampSecondaryProfileOwner({ ...event, ...(connectionId ? { connectionId } : {}) }, canonicalOwnerProfile(event) ?? profile)
g.config?.onEvent(scopedEvent)
releaseTerminalTurnLease(entry.scope, event)
})
entry.offRequest = gateway.onRequest?.(request => dispatchServerRequest(request, profile, connectionId)) ?? (() => {})
entry.offState = gateway.onState(state => {
reportGatewayState(scope, state)
if (state === 'open') {
entry.stalledDials = 0
entry.openedAt = Date.now()
clearTimer(entry)
} else if (state === 'closed' || state === 'error') {
// Same stable-open rule as the primary (#83134): an accept-then-close socket
// is a failed attempt, so the ladder resets only after a socket that lived.
if (isStableOpen(entry.openedAt)) {
entry.reconnectAttempt = 0
g.dialFailures.delete(scope)
} else if (entry.openedAt !== null) {
recordDialFailure(entry)
}
entry.openedAt = null
// A transport drop does not settle a running turn. Its lease must keep
// the route alive so reconnect can replay missed events and receive the
// terminal event. Actual disposal releases orphaned leases below.
if (entry.wantOpen) {
scheduleReconnect(entry)
}
}
})
g.secondaries.set(scope, entry)
return entry
}
// Resolve and open `profile`'s socket WITHOUT changing the active gateway.
// Shared global-remote profiles intentionally return the primary socket plus a
// request-scope flag; dedicated local/remote profiles use their pooled socket.
async function gatewayForProfile(
profile: string,
leaseRequest = false,
spawnPriority: SpawnPriority = 'background'
): Promise<{ gateway: HermesGateway | null; key: string; release: () => void; scopeProfile: boolean }> {
const key = normKey(profile)
const noRelease = () => undefined
if (key === g.primaryProfile) {
return { gateway: g.primaryGateway, key, release: noRelease, scopeProfile: false }
}
// sharedPrimaryRoute is itself a dial into main (it can start the profile's spawn), so a
// cooling-down scope has to be held back before it, not just before openSecondary.
const existing = g.secondaries.get(key)
if (spawnPriority !== 'foreground' && !(existing && isOpen(existing.gateway)) && backgroundDialCoolingDown(key)) {
throw new Error(`Backend for "${key}" is reconnecting; retry after it settles.`)
}
if (notePrimaryRider(primaryIdentity(), key, await sharedPrimaryRoute(key))) {
return { gateway: g.primaryGateway, key, release: noRelease, scopeProfile: true }
}
const entry = g.secondaries.get(key) ?? createSecondary(key)
// Existing dev-HMR entries predate the request lease/ownership fields.
if (!Number.isFinite(entry.activeRequests)) {
entry.activeRequests = 0
}
if (typeof entry.retained !== 'boolean') {
entry.retained = true
}
if (!leaseRequest) {
entry.retained = true
}
rearmSecondary(entry, spawnPriority)
if (leaseRequest) {
entry.activeRequests += 1
}
let released = false
const release = () => {
if (!released && leaseRequest) {
released = true
entry.activeRequests = Math.max(0, entry.activeRequests - 1)
if (
entry.activeRequests === 0 &&
!entry.retained &&
!relayRetained(entry) &&
!foregroundPinned(entry) &&
g.activeKey !== entry.scope
) {
disposeSecondary(entry)
if (g.secondaries.get(entry.scope) === entry) {
g.secondaries.delete(entry.scope)
}
}
}
}
try {
await openSecondaryForRequest(entry, spawnPriority)
} catch (error) {
release()
throw error
}
return { gateway: entry.gateway, key, release, scopeProfile: false }
}
/**
* Send a gateway RPC through a named Desktop profile without foregrounding it.
* Global-remote routes share the primary socket and need an explicit profile
* param; dedicated pooled backends are already scoped by their descriptor.
*/
export async function requestGatewayForProfile<T>(
profile: string,
method: string,
params: Record<string, unknown> = {},
timeoutMs?: number,
signal?: AbortSignal,
{ spawnPriority = 'background' }: { spawnPriority?: SpawnPriority } = {}
): Promise<T> {
const route = await gatewayForProfile(profile, true, spawnPriority)
try {
if (!route.gateway) {
throw new Error(`Hermes gateway unavailable for profile "${route.key}"`)
}
const routedParams = route.scopeProfile ? { ...params, profile: route.key } : params
// Same arity contract as the ambient path in session-request-router: only
// pass the deadline args through when the caller set them, so a plain
// profile-routed RPC keeps its two-argument call shape.
const result = await (timeoutMs === undefined && signal === undefined
? route.gateway.request<T>(method, routedParams)
: route.gateway.request<T>(method, routedParams, timeoutMs, signal))
// A served RPC proves the backend answers, not just accepts, so it clears the dial history.
// Lease requests dispose their entry right after, before a close could prove the socket stable.
g.dialFailures.delete(route.key)
return result
} finally {
route.release()
}
}
/**
* Send a gateway RPC through one registry source without activating it. The
* composite (connectionId, profile) pool key prevents same-named agents on two
* sources from sharing a socket. Only null/empty ids retain the v1 profile
* resolver; explicit `local` is a registry source and must use getConnectionFor.
*
* `spawnPriority` marks a user gesture that reaches this RPC path (first send on
* a fresh chat, "New session", an explicit Bot Chat open) as 'foreground'
* (#102281 primitive; #105104 symptom). The canonical ensure dial has no slot
* to reserve, so the tag is carried, not acted on.
*/
export async function requestGatewayForAgent<T>(
connectionId: null | string,
profile: string,
method: string,
params: Record<string, unknown> = {},
timeoutMs?: number,
signal?: AbortSignal,
{ spawnPriority = 'background' }: { spawnPriority?: SpawnPriority } = {}
): Promise<T> {
const key = normKey(profile)
const scope = registryBackendScopeKey(connectionId, key)
if (scope === key) {
return requestGatewayForProfile<T>(key, method, params, timeoutMs, signal, { spawnPriority })
}
// A primary remote selected from the connection registry carries its source
// id in the active connection descriptor. Requests for that exact
// (connection, profile) already have an owning socket: the window primary.
// Dialing a registry secondary here can resolve the same public endpoint to a
// different backend/profile route, so durable session.resume reports
// "session not found" while REST history from the primary remains visible.
// Require both owner identities to agree before collapsing the route; a
// different source or profile must retain its isolated secondary.
if (isPrimaryRegistryRoute(connectionId, key)) {
traceAgentRoute(scope, 'primary')
return requestGatewayForProfile<T>(key, method, params, timeoutMs, signal, { spawnPriority })
}
if (notePrimaryRider(primaryIdentity(), scope, await ridesPrimaryBackend(connectionId, key))) {
traceAgentRoute(scope, 'primary-shared')
return requestOnPrimaryGateway<T>(method, { ...params, profile: key }, timeoutMs, signal)
}
traceAgentRoute(scope, 'secondary')
if (!window.hermesDesktop?.getConnectionFor) {
throw new Error('This Desktop build cannot dial registry connections. Update Hermes Desktop.')
}
const entry = g.secondaries.get(scope) ?? createSecondary(key, connectionId)
// Existing dev-HMR entries predate request leases/ownership.
if (!Number.isFinite(entry.activeRequests)) {
entry.activeRequests = 0
}
if (typeof entry.retained !== 'boolean') {
entry.retained = true
}
rearmSecondary(entry, spawnPriority)
entry.activeRequests += 1
try {
await openSecondaryForRequest(entry, spawnPriority)
const result = await (timeoutMs === undefined && signal === undefined
? entry.gateway.request<T>(method, params)
: entry.gateway.request<T>(method, params, timeoutMs, signal))
g.dialFailures.delete(entry.scope)
return result
} finally {
entry.activeRequests = Math.max(0, entry.activeRequests - 1)
if (
!drainPendingConnectionRedial(entry) &&
entry.activeRequests === 0 &&
!entry.retained &&
!relayRetained(entry) &&
!foregroundPinned(entry) &&
g.activeKey !== entry.scope
) {
disposeSecondary(entry)
if (g.secondaries.get(entry.scope) === entry) {
g.secondaries.delete(entry.scope)
}
}
}
}
// ── Bot-relay socket retention (#93594) ─────────────────────────────────────
// The desktop bot relay RPCs EVERY registered connection on its drain loop.
// Each of those calls runs through requestGatewayForAgent's per-request lease,
// so a connection with no other consumer dialed a fresh WebSocket and tore it
// down again on every tick — a connect/disconnect pair per connection per tick
// flooding the gateway logs. While the relay is active, its routes hold a
// counted retention that keeps the pooled socket (and its existing
// scheduleReconnect/backoff machinery) alive across ticks; stopBotRelay (and
// plugin dispose) releases it, restoring the dispose-at-refcount-0 behavior.
/**
* True when a foreground surface (mounted tile / primary thread) is bound to
* this entry's scope (#93892). Registry-scoped entries match on their
* composite key only; local/legacy entries also match on the bare profile —
* the same key language pruneSecondaryGateways' keep-set speaks.
*/
function foregroundPinned(entry: Secondary): boolean {
const scopes = g.config?.foregroundScopes?.()
if (!scopes) {
return false
}
return scopes.has(entry.scope) || (!entry.connectionId && scopes.has(entry.profile))
}
/** Pinned open: the bot relay holds it, or it is kept connected (gateway-kept-routes). */
function relayRetained(entry: Secondary): boolean {
return entry.relayRetainCount > 0 || isKeptRoute(entry.connectionId, entry.profile)
}
/**
* Finish a material-edit redial once no request, relay lease or foreground surface owns the old socket (a keep
* pin never defers it). Removal bypasses this drain: a deleted source must fail-stop immediately.
*/
function drainPendingConnectionRedial(entry: Secondary): boolean {
if (
entry.pendingConnectionRedial !== true ||
entry.activeRequests > 0 ||
entry.relayRetainCount > 0 ||
foregroundPinned(entry) ||
g.secondaries.get(entry.scope) !== entry
) {
return false
}
entry.pendingConnectionRedial = false
const wasActive = g.activeKey === entry.scope
disposeSecondary(entry)
g.secondaries.delete(entry.scope)
reopenAfterRedial(entry, wasActive)
return true
}
// Re-open a redialed scope after its entry left the map. An active scope's
// re-activation is asynchronous, and until it lands
// restoreActiveToPrimaryIfEvicted sees an active scope with no entry, calls
// setActive(primary) and bumps the activation epoch — which turns this redial's
// own applyActive(epoch) into a no-op. The window would then sit on the primary
// backend with the redial silently discarded, after nothing more than an edit
// to the connection being viewed. Mark the scope for the pruner while the
// re-activation is in flight; the finally clears it on both outcomes so a
// redial that never lands still falls back.
function reopenAfterRedial(entry: Secondary, wasActive: boolean): void {
if (!wasActive) {
void openGatewayForAgent(entry.connectionId, entry.profile).catch(() => undefined)
return
}
reactivatingScopes().add(entry.scope)
void ensureGatewayForAgent(entry.connectionId, entry.profile)
.catch(() => undefined)
.finally(() => {
reactivatingScopes().delete(entry.scope)
})
}
/**
* Pin the pooled socket for one relay route open across drain ticks. Returns
* a once-only release. Local routes (null/empty or explicit `local` source)
* are deliberately EXEMPT and get a no-op release: a relay pin would keep a
* local socket open past the point where retireLocalProfileGateways means to
* drop it (see that note). Local relay traffic is
* either the primary socket (no churn) or a short-lived local dial — never
* the remote reconnect flood this retention exists to stop.
*/
export function retainGatewayForRelay(connectionId: null | string, profile: string): () => void {
const key = normKey(profile)
const connection = String(connectionId ?? '').trim()
if (!connection || connection === 'local') {
return () => undefined
}
const scope = registryBackendScopeKey(connection, key)
const entry = g.secondaries.get(scope) ?? createSecondary(key, connection)
if (!Number.isFinite(entry.relayRetainCount)) {
entry.relayRetainCount = 0
}
entry.relayRetainCount += 1
if (!g.reauthFailures.has(entry.scope)) {
rearmSecondary(entry)
}
let released = false
return () => {
if (released) {
return
}
released = true
entry.relayRetainCount = Math.max(0, (entry.relayRetainCount || 0) - 1)
if (
!drainPendingConnectionRedial(entry) &&
!relayRetained(entry) &&
entry.activeRequests === 0 &&
!entry.retained &&
!foregroundPinned(entry) &&
g.activeKey !== entry.scope &&
g.secondaries.get(entry.scope) === entry
) {
disposeSecondary(entry)
g.secondaries.delete(entry.scope)
}
}
}
/**
* Hold `profile`'s socket open across a multi-RPC sequence without activating
* it (#93602). Every requestGatewayForProfile/requestGatewayForAgent call is a
* per-request lease: at refcount 0 a non-retained secondary is disposed, so a
* session-scoped sequence (session.create → attach → prompt.submit) minted a
* runtime id on a socket that closed between calls — the gateway detached the
* session on WS disconnect and the next RPC hit 4001 "not in memory". Callers
* acquire this lease before the first session-scoped RPC and release it in a
* `finally`; the refcount keeps the socket (and the session it minted) alive
* for the whole sequence. Primary/shared-primary routes return a no-op release.
*
* `spawnPriority` follows requestGatewayForAgent: the retain is the FIRST dial
* of a session-create gesture, so a user click passes 'foreground' here.
*/
export async function retainGatewayForAgent(
connectionId: null | string,
profile: string,
{ spawnPriority = 'background' }: { spawnPriority?: SpawnPriority } = {}
): Promise<() => void> {
const key = normKey(profile)
const scope = registryBackendScopeKey(connectionId, key)
if (scope === key) {
// Plain-profile route: gatewayForProfile's request lease IS the retain —
// hold it until the caller releases.
const route = await gatewayForProfile(key, true, spawnPriority)
return route.release
}
if (isPrimaryRegistryRoute(connectionId, key) || (await ridesPrimaryBackend(connectionId, key))) {
// Primary socket stays open for the window lifetime — no secondary to hold.
return () => undefined
}
if (!window.hermesDesktop?.getConnectionFor) {
// No registry dialing in this build — nothing to hold; the request path
// will throw its own actionable error.
return () => undefined
}
const entry = g.secondaries.get(scope) ?? createSecondary(key, connectionId)
// Existing dev-HMR entries predate request leases/ownership.
if (!Number.isFinite(entry.activeRequests)) {
entry.activeRequests = 0
}
if (typeof entry.retained !== 'boolean') {
entry.retained = true
}
rearmSecondary(entry, spawnPriority)
entry.activeRequests += 1
let released = false
const release = () => {
if (released) {
return
}
released = true
entry.activeRequests = Math.max(0, entry.activeRequests - 1)
if (drainPendingConnectionRedial(entry)) {
return
}
if (
entry.activeRequests === 0 &&
!entry.retained &&
!relayRetained(entry) &&
!foregroundPinned(entry) &&
g.activeKey !== entry.scope
) {
disposeSecondary(entry)
if (g.secondaries.get(entry.scope) === entry) {
g.secondaries.delete(entry.scope)
}
}
}
try {
if (!isOpen(entry.gateway)) {
await openSecondary(entry)
}
} catch (error) {
release()
throw error
}
return release
}
import { acceptExecutionEvent } from '@/lib/execution-authority'
const turnLeaseKey = (scope: string, sessionId: string): string => `${scope}\u0000${sessionId}`
const TURN_LEASE_SETTLE_DELAY_MS = 500
const turnExecutionAuthorities = new Map()
function cancelTurnLeaseRelease(key: string): void {
const timer = g.turnLeaseReleaseTimers.get(key)
if (timer !== undefined) {
clearTimeout(timer)
g.turnLeaseReleaseTimers.delete(key)
}
}
function releaseTurnLeasesForScope(scope: string): void {
const prefix = `${scope}\u0000`
for (const [key, timer] of [...g.turnLeaseReleaseTimers]) {
if (key.startsWith(prefix)) {
clearTimeout(timer)
g.turnLeaseReleaseTimers.delete(key)
}
}
for (const [key, release] of [...g.turnLeases]) {
if (key.startsWith(prefix)) {
release()
}
}
}
/**
* Keep a routed Desktop prompt's socket alive after prompt.submit ACKs.
*
* Routed requests normally own a per-request lease. prompt.submit ACKs as soon
* as the background turn starts, so releasing that lease at RPC completion
* detaches the runtime session while the model is still working; the gateway's
* 20-second orphan guard then interrupts it as `client_gone`. Hold one lease per
* (route, runtime session) until message.complete/session.info settles the turn.
*/
export async function retainGatewayForSessionTurn(
connectionId: null | string,
profile: string,
sessionId: string
): Promise<() => void> {
// Primary events do not flow through a Secondary's terminal-event listener.
// Registering a no-op lease here would leave a phantom key that can suppress
// the real hold if this route is later re-homed as a secondary.
if (isPrimaryRegistryRoute(connectionId, normKey(profile))) {
return () => undefined
}
const scope = registryBackendScopeKey(connectionId, normKey(profile))
const key = turnLeaseKey(scope, sessionId)
cancelTurnLeaseRelease(key)
// A busy-session redirect/queue can submit again while the original turn is
// still retained. The existing lease owns that turn; the extra submit must
// not replace or release it. The no-op means "another caller owns the
// shared lease", not "this caller acquired a separately releasable lease".
if (g.turnLeases.has(key)) {
return () => undefined
}
const releaseRoute = await retainGatewayForAgent(connectionId, profile)
// Only a Secondary's own terminal-event listener releases this lease, so a route with no
// Secondary can never release one: retainGatewayForAgent and gatewayForProfile both hand back a
// no-op exactly when the route rides the primary socket (shared-remote collapse, shared-primary
// route, or a build without registry dialing), and none of those creates an entry. Storing the
// key there leaves the same phantom the primary-profile guard above avoids, and it would suppress
// the real hold once that route IS dialed as a secondary — which the shared-remote probe
// explicitly expects ("prefer the primary until a later probe can prove isolation"). Decide by
// outcome rather than re-probing every no-op case.
if (!g.secondaries.has(scope)) {
releaseRoute()
return () => undefined
}
// Re-check after the await: the guard above the retain ran before it, so a second submit for the
// same (route, session) can arrive while this one suspends and both pass it. Only the release
// stored in the map is ever invoked — releaseTerminalTurnLease does `g.turnLeases.get(key)?.()` —
// so the loser's hold would never be released and the socket could never be reclaimed.
if (g.turnLeases.has(key)) {
releaseRoute()
return () => undefined
}
let released = false
const release = () => {
if (released) {
return
}
released = true
if (g.turnLeases.get(key) === release) {
g.turnLeases.delete(key)
}
cancelTurnLeaseRelease(key)
releaseRoute()
}
g.turnLeases.set(key, release)
return release
}
function releaseTerminalTurnLease(scope: string, event: GatewayEvent): void {
const sessionId = String(event.session_id || '').trim()
if (!sessionId) {
return
}
const key = turnLeaseKey(scope, sessionId)
if (!acceptExecutionEvent(turnExecutionAuthorities, key, event.type, event)) {
return
}
if (
event.type === 'message.start' ||
(event.type === 'session.info' && (event.payload as Record<string, unknown>)?.running === true)
) {
// The gateway emits settled session.info before immediately chaining a
// queued/goal follow-up. Keep the same route alive for that next turn.
cancelTurnLeaseRelease(key)
return
}
if (event.type === 'session.reclaimed') {
g.turnLeases.get(key)?.()
return
}
const payload = event.payload as Record<string, unknown> | undefined
if (event.type === 'session.info' && payload?.running === false && !g.turnLeaseReleaseTimers.has(key)) {
// session.info(false) is the authoritative settled edge, but auto-followup
// emits message.start immediately after it. A short debounce lets that
// frame cancel release while still reclaiming ordinary completed turns.
g.turnLeaseReleaseTimers.set(
key,
setTimeout(() => {
g.turnLeaseReleaseTimers.delete(key)
g.turnLeases.get(key)?.()
}, TURN_LEASE_SETTLE_DELAY_MS)
)
}
}
// Open `profile`'s socket WITHOUT making it active — the hover-intent pre-warm
// (store/profile). Runs the same spawn + connect chain as a real switch, so by
// click time ensureGatewayForProfile finds an open socket and just activates
// it. No scheduleReconnect on failure: a hover is speculative, so a dead
// backend must not start a background retry loop — the real switch owns retry
// and error UX. An already-open (or primary) profile is a no-op.
export async function openGatewayForProfile(
profile: string,
{ spawnPriority = 'background' }: { spawnPriority?: SpawnPriority } = {}
): Promise<void> {
await gatewayForProfile(profile, false, spawnPriority)
}
// ── Connection-scoped agents (multi-source roster) ─────────────────────────
// The (connectionId, profile) analogues of the profile functions above. A
// null connectionId falls straight through to the profile path. An explicit
// `local` id remains registry-scoped so it cannot inherit legacy remote v1
// routing. Feature-detected: without the Electron getConnectionFor door these
// throw, and roster surfaces disable non-local rows instead.
// `activationLease`: hold the same prune lease ensureGatewayForAgent holds for
// the whole dial. Phase one of the two-phase source switch (store/connections
// selectConnection) opens the target here and activates it right after; without
// the lease a live-work recompute during the cold spawn would dispose the entry
// mid-dial and the click would die (#89622). Plain pre-warms stay prunable —
// a hovered-but-never-activated socket must not be pinned off another source's
// live work.
export async function openGatewayForAgent(
connectionId: null | string,
profile: string,
{
activationLease = false,
spawnPriority = 'background'
}: { activationLease?: boolean; spawnPriority?: SpawnPriority } = {}
): Promise<void> {
const scope = registryBackendScopeKey(connectionId, profile)
if (scope === normKey(profile) || isPrimaryRegistryRoute(connectionId, profile)) {
return openGatewayForProfile(profile, { spawnPriority })
}
if (await ridesPrimaryBackend(connectionId, profile)) {
if (!isOpen(g.primaryGateway)) {
throw new Error('Hermes gateway unavailable')
}
return
}
if (!window.hermesDesktop?.getConnectionFor) {
throw new Error('This Desktop build cannot dial registry connections. Update Hermes Desktop.')
}
const entry = g.secondaries.get(scope) ?? createSecondary(profile, connectionId)
entry.retained = true
rearmSecondary(entry, spawnPriority)
if (activationLease) {
// Stays held after a successful open: the activation that follows releases
// it (applyActive path), and one that never comes lets it expire.
entry.activationLeaseUntil = Date.now() + ACTIVATION_LEASE_MS
}
if (isOpen(entry.gateway)) {
return
}
try {
await openSecondary(entry)
} catch (error) {
if (activationLease) {
entry.activationLeaseUntil = 0
}
throw error
}
}
export async function ensureGatewayForAgent(
connectionId: null | string,
profile: string,
{ signal }: { signal?: AbortSignal } = {}
): Promise<boolean> {
const scope = registryBackendScopeKey(connectionId, profile)
if (scope === normKey(profile) || isPrimaryRegistryRoute(connectionId, profile)) {
if (signal?.aborted) {
return false
}
await ensureGatewayForProfile(profile)
return !signal?.aborted
}
const activationEpoch = beginGatewayActivation()
if (await ridesPrimaryBackend(connectionId, profile)) {
// A retained primary can be open while the foreground still points at a
// different source. Reusing its socket must also move the active route.
return Boolean(isOpen(g.primaryGateway) && !signal?.aborted && applyActive(g.primaryProfile, activationEpoch))
}
if (!window.hermesDesktop?.getConnectionFor) {
throw new Error('This Desktop build cannot dial registry connections. Update Hermes Desktop.')
}
let entry = g.secondaries.get(scope)
if (!entry) {
entry = createSecondary(profile, connectionId)
}
entry.retained = true
rearmSecondary(entry)
// Lease the entry against the live-work pruner for the whole dial: the
// switch target is not yet active and has no live sessions, so a prune
// recompute firing mid-spawn would otherwise dispose it and this
// activation would fail (#89622).
entry.activationLeaseUntil = Date.now() + ACTIVATION_LEASE_MS
if (!isOpen(entry.gateway)) {
clearTimer(entry)
entry.reconnectAttempt = 0
try {
await openSecondary(entry)
} catch {
scheduleReconnect(entry)
}
}
// The activation is settling either way — release the prune lease.
entry.activationLeaseUntil = 0
// A timed-out owner may leave the dial running, but it no longer has the
// right to move the foreground route when that work eventually settles.
if (signal?.aborted) {
return false
}
// A source edit/remove may dispose this entry while its dial is still in
// flight. Only the still-registered, still-owned activation may publish --
// and only when the WebSocket actually reached open: entry.connection is
// set BEFORE the dial completes in openSecondary, so a transient first-dial
// failure (caught above, left for scheduleReconnect) must not count as a
// successful activation just because a connection descriptor exists
// (issue #92265).
const activated =
entry.wantOpen &&
g.secondaries.get(scope) === entry &&
Boolean(entry.connection) &&
isOpen(entry.gateway) &&
applyActive(scope, activationEpoch)
if (activated && entry.connection) {
publishActiveConnection(entry.connection)
}
return activated
}
// Make `profile` the active gateway, lazily opening its socket if needed. The
// primary is a no-op fast path. Background sockets are never closed here.
export async function ensureGatewayForProfile(profile: string): Promise<void> {
const key = normKey(profile)
const activationEpoch = beginGatewayActivation()
if (key === g.primaryProfile) {
applyActive(key, activationEpoch)
return
}
// Global-remote share (routing case 3): one remote host serves every
// profile through the PRIMARY socket, scoped per request. Activate the
// primary instead of dialing a doomed duplicate socket at the same
// descriptor — $activeGatewayProfile still moves to `key`, so request
// scoping and profile-aware surfaces behave identically.
if (await sharedPrimaryRoute(key)) {
applyActive(g.primaryProfile, activationEpoch)
return
}
let entry = g.secondaries.get(key)
if (!entry) {
entry = createSecondary(key)
}
entry.retained = true
rearmSecondary(entry)
// Lease the entry against the live-work pruner for the whole dial — the
// profile-door twin of the agent path's lease above (#89622).
entry.activationLeaseUntil = Date.now() + ACTIVATION_LEASE_MS
try {
if (!isOpen(entry.gateway)) {
clearTimer(entry)
entry.reconnectAttempt = 0
try {
await openSecondary(entry)
} catch (error) {
// #81094: a failed secondary dial must NOT fall through to setActive()
// with a closed socket — that silently routes the user's messages to the
// primary backend (cross-profile session writes). Keep the reconnect
// schedule (transient failures still self-heal via the backoff below)
// but RE-THROW so the profile-door caller surfaces the failure and skips
// the activation. The agent-door twin (ensureGatewayForAgent) keeps its
// boolean contract and is guarded by the activeGateway() null invariant.
scheduleReconnect(entry)
throw error
}
}
} finally {
// The activation is settling either way — release the prune lease.
entry.activationLeaseUntil = 0
}
// Only publish when the WebSocket actually reached open -- entry.connection
// is set before the dial completes, so a transient first-dial failure must
// not count as a successful activation (issue #92265).
if (
entry.wantOpen &&
g.secondaries.get(key) === entry &&
isOpen(entry.gateway) &&
applyActive(key, activationEpoch) &&
entry.connection
) {
publishActiveConnection(entry.connection)
}
}
// Reconnect the active gateway after a transient request failure. Primary
// reconnects are owned by use-gateway-boot, so we only drive secondaries here.
// A scope parked on a rejected session stays parked for automatic request
// retries; only a user gesture (`explicit`: the Reconnect action) may redial it.
export async function ensureActiveGatewayOpen({
explicit = false
}: { explicit?: boolean } = {}): Promise<HermesGateway | null> {
if (g.activeKey === g.primaryProfile) {
return g.primaryGateway
}
const entry = g.secondaries.get(g.activeKey)
if (!entry || (!explicit && g.reauthFailures.has(entry.scope))) {
return null
}
if (!isOpen(entry.gateway)) {
// The viewed scope is a recovery target: a stall-parked entry must dial
// again here, not stay parked. A reauth-parked one only reaches this line
// via `explicit`; the foreground rearm clears its rejection.
rearmSecondary(entry)
await reconnectSecondary(entry)
}
if (!isOpen(entry.gateway)) {
// A remote/registry secondary can still be ACTIVATING (backend waking,
// socket dialing). Failing instantly turned a routine cold start into
// "Hermes gateway is not connected" on the Sessions `+` action (#88880).
// Wait a bounded beat for the in-flight activation instead of erroring;
// a genuinely dead gateway still returns null when the window closes.
const deadline = Date.now() + ACTIVE_GATEWAY_OPEN_WAIT_MS
while (Date.now() < deadline && entry.wantOpen && g.secondaries.get(g.activeKey) === entry) {
if (isOpen(entry.gateway)) {
break
}
await new Promise(resolve => setTimeout(resolve, 250))
}
}
return isOpen(entry.gateway) ? entry.gateway : null
}
// How long ensureActiveGatewayOpen waits out an in-flight secondary
// activation before reporting the gateway as unavailable.
const ACTIVE_GATEWAY_OPEN_WAIT_MS = 8_000
// Grace period before the live-work pruner may dispose a freshly opened
// secondary socket; see the min-lifetime guard in pruneSecondaryGateways
// (#94769 prune ↔ redial race). Exported for the tests that age a socket past it.
export const SECONDARY_MIN_LIFETIME_MS = 30_000
// A deferred liveness re-probe for one entry: cleared when the probe is
// answered, the socket is redialed (fresh streak), or the entry is disposed.
function clearSecondaryLivenessReprobe(entry: Secondary): void {
if (entry.livenessReprobeTimer !== null) {
clearTimeout(entry.livenessReprobeTimer)
entry.livenessReprobeTimer = null
}
}
// Probe a live-in-use secondary instead of blind-closing it on a forced wake,
// and close it only when the probe proves it not alive. A half-open TCP
// connection (sleep/wake, silent network drop) reports connectionState
// 'open' forever and fires no close event, so without this close an in-flight
// request rides a dead transport until its per-call timeout — prompt.submit's
// is 30 minutes. Closing arms the entry's ordinary reconnect backoff via its
// onState('closed') handler; a healthy-but-busy backend answers the ping and
// keeps its socket (#94769 review).
function probeSecondaryLiveness(entry: Secondary): void {
void probeGatewayLiveness(entry.gateway).then(
() => {
entry.livenessProbeFailures = 0
clearSecondaryLivenessReprobe(entry)
},
(error: unknown) => {
// -32601 (method not found) = a version-skewed but HEALTHY backend that
// predates the ping method — the same compatibility carve-out the
// primary's probe makes in use-gateway-boot.
if (isMissingRpcMethod(error)) {
entry.livenessProbeFailures = 0
clearSecondaryLivenessReprobe(entry)
return
}
// The entry may have been pruned or redialed while the probe was
// pending; only the very same socket may be torn down.
if (g.secondaries.get(entry.scope) !== entry || !isOpen(entry.gateway)) {
return
}
// ONE missed ping is not proof of death: a live backend mid tool call
// can starve its event loop past the probe budget, and force-closing it
// feeds the backend's ws_orphan_reap, interrupting the valid turn
// (#94769 review). Apply the SAME streak policy as the primary's probe
// (decideLivenessForceClose): defer the first failure while work is
// in flight behind a bounded re-probe, close only when the streak is
// exhausted — or immediately when nothing is in flight to protect.
entry.livenessProbeFailures += 1
// Counted RPCs alone under-report in-flight work: prompt.submit returns
// before the turn ends, so a foreground turn mid tool call shows
// activeRequests 0. The registry's live-scope hook supplies the turn.
const liveScopes = g.config?.liveScopes?.()
const turnInFlight =
liveScopes && (liveScopes.has(entry.scope) || (!entry.connectionId && liveScopes.has(entry.profile))) ? 1 : 0
const decision = decideLivenessForceClose({
workingSessionCount: entry.activeRequests + turnInFlight,
consecutiveFailures: entry.livenessProbeFailures
})
if (!decision.close) {
if (entry.livenessReprobeTimer === null) {
entry.livenessReprobeTimer = setTimeout(() => {
entry.livenessReprobeTimer = null
// The entry may have been pruned or redialed while the re-probe
// waited; only the same open socket may be probed again.
if (g.secondaries.get(entry.scope) !== entry || !isOpen(entry.gateway)) {
return
}
probeSecondaryLiveness(entry)
}, LIVENESS_REPROBE_DELAY_MS)
}
return
}
entry.livenessProbeFailures = 0
clearSecondaryLivenessReprobe(entry)
entry.gateway.close()
}
)
}
// Recovery signal: nudge every live secondary back open. Power-resume/network
// signals can force sockets that still report open to retire before redialing.
export function reconnectSecondaryGateways({ forceOpenSockets = false }: { forceOpenSockets?: boolean } = {}): void {
for (const entry of g.secondaries.values()) {
// A backend main retired for a foreground open stays parked: redialing it
// from a focus/wake nudge would queue a background spawn for the slot the
// retirement just freed. Its tile still shows; the next click re-arms it.
if (g.reauthFailures.has(entry.scope)) {
continue
}
// A parked entry (stall budget spent) is still pinned by its surface, or
// the pruner would have removed it. This nudge is an explicit recovery
// signal (online / focus / wake), so it re-arms with a fresh budget.
rearmSecondary(entry)
if (isOpen(entry.gateway)) {
if (!forceOpenSockets) {
continue
}
// A forced wake (power resume / network online) used to close EVERY open
// secondary socket before redialing. Closing one that is mid-use detaches
// its runtime → the backend orphan-reaps it → `session.reclaimed` → the
// surface re-resumes on a fresh socket the same signal may close again:
// the #94769 flicker loop. But a live socket also cannot simply be
// SKIPPED: a half-open socket never fires a close event, so an in-flight
// request would hang until its per-call timeout. Probe liveness instead —
// a healthy-but-busy backend answers and keeps its socket; a dead
// transport is closed and healed by the ordinary reconnect backoff.
if (entry.activeRequests > 0 || relayRetained(entry) || foregroundPinned(entry)) {
probeSecondaryLiveness(entry)
continue
}
entry.gateway.close()
}
entry.reconnectAttempt = 0
clearTimer(entry)
void reconnectSecondary(entry)
}
}
// How many non-primary backends currently hold an open socket. Hover-intent
// prewarming consults this before spawning: a speculative spawn that pushes
// the pool past its cap causes the Electron main to LRU-evict a warm backend
// — often one the user is about to click — turning the prewarm into churn
// (the #91545 evict/respawn cascade). The active gateway's backend is
// primary-routed and never counts toward the pool cap.
export function openSecondaryCount(): number {
let count = 0
for (const entry of g.secondaries.values()) {
if (isOpen(entry.gateway)) {
count += 1
}
}
return count
}
// Tear a secondary down: stop its reconnect loop, detach listeners, close the
// socket. Caller handles removal from the map.
function disposeSecondary(entry: Secondary): void {
if (!entry.wantOpen) {
return
}
entry.wantOpen = false
entry.pendingConnectionRedial = false
clearTimer(entry)
clearSecondaryLivenessReprobe(entry)
entry.offEvent()
entry.offRequest()
entry.offState()
entry.gateway.close()
// Release can re-enter disposal at refcount zero. wantOpen is already false,
// and listeners are detached, so explicit teardown never rearms reconnect.
releaseTurnLeasesForScope(entry.scope)
}
// Invariant restore for every eviction path: if the active key names a
// secondary that no longer exists, fall back to the primary EXPLICITLY (atoms
// and composer state follow) instead of leaving a dangling key that
// activeGateway() can no longer resolve. Without this, a soft gateway switch
// (closeSecondaryGateways in use-gateway-boot) left activeKey pointing at an
// evicted registry scope and every call silently hit the primary backend.
function restoreActiveToPrimaryIfEvicted(): void {
if (
g.activeKey !== g.primaryProfile &&
!g.secondaries.has(g.activeKey) &&
// A redial evicts the entry and re-activates the same scope moments later; taking the
// activation in between cancels it through the epoch. The redial's own finally always clears
// this, so a failed redial still falls back to the primary.
!reactivatingScopes().has(g.activeKey)
) {
setActive(g.primaryProfile)
}
}
// Close + evict secondaries whose scope is neither active nor in `keep`
// (scopes with a running / needs-input session). Bounds cost to live work.
// `keep` carries PROFILE names for local/legacy entries and composite
// registryBackendScopeKey(connectionId, profile) scopes for registry-sourced live
// work. A registry-scoped entry matches ONLY on its composite key: every
// source exposes a 'default' profile, so matching a non-local entry on the
// bare profile name kept gateway B's 'default' socket alive off gateway A's
// 'default' activity (and vice versa) — cross-connection attribution.
//
// Live work is not the only thing worth a socket: an idle tile still holds a
// resumed runtime on its owner's socket, and closing that socket makes the
// backend detach and orphan-reap the runtime, whose `session.reclaimed`
// unbinds the tile and re-resumes it on a fresh socket that the next
// recompute closes again — a spinner loop with no terminal state (#93892).
// Foreground-bound scopes come from the registry's `foregroundScopes` hook
// (foregroundPinned), not from `keep`, so every dispose path sees the same
// pin. `entry.retained` is deliberately NOT consulted here (see the field's
// doc).
export function pruneSecondaryGateways(keep: Set<string>): void {
const now = Date.now()
for (const [key, entry] of [...g.secondaries]) {
if (drainPendingConnectionRedial(entry)) {
continue
}
if (
key === g.activeKey ||
keep.has(key) ||
(!entry.connectionId && keep.has(entry.profile)) ||
// Bot-relay retention (#93594): the relay pins its remote routes for
// its whole active lifetime; the live-work pruner must not undo that
// pin between drain ticks or the socket churn returns.
relayRetained(entry) ||
// A mounted tile / the primary thread is bound to a runtime on this
// socket (#93892) — pinned for as long as that surface is mounted.
foregroundPinned(entry) ||
// Mid-dial activation target: the profile being switched TO is not yet
// active and has no live work, so without this lease any recompute
// during its cold spawn disposed the entry and the click died silently
// (#89622). Number guard: dev-HMR entries predate the field. Bounded:
// an orphaned lease expires on its own.
(Number.isFinite(entry.activationLeaseUntil) && entry.activationLeaseUntil > now)
) {
continue
}
// Min-lifetime grace: an idle prune can race an on-demand dial (prune →
// redial → prune) and dispose a socket that opened moments ago, before
// its consumer registered in the keep-set — closing it detaches the
// runtime, the backend orphan-reaps it, and the reclaimed surface
// re-resumes on a fresh socket the next recompute closes again: the
// #94769 flicker loop. A young socket rides one prune tick; the keepalive
// tick recomputes the keep-set so an idle one is still reaped within a minute.
if (now - entry.lastOpenedAt < SECONDARY_MIN_LIFETIME_MS) {
continue
}
// The route is no longer live work. Release turn leases first so their
// counted request holds cannot outlive a disposed route or leave a stale
// release closure attached to a later same-key socket.
releaseTurnLeasesForScope(key)
if (g.secondaries.get(key) !== entry) {
continue
}
if (entry.activeRequests > 0) {
continue
}
disposeSecondary(entry)
g.secondaries.delete(key)
}
restoreActiveToPrimaryIfEvicted()
}
function closeSecondariesWhere(shouldClose: (entry: Secondary) => boolean): void {
for (const [scope, entry] of [...g.secondaries]) {
if (!shouldClose(entry)) {
continue
}
disposeSecondary(entry)
g.secondaries.delete(scope)
}
restoreActiveToPrimaryIfEvicted()
}
function isLegacySecondary(entry: Secondary): boolean {
// Every v2 registry route is created with an explicit connection id,
// including the registry's `local` source. A missing id is reserved for the
// old profile-only pool; the loose null check also retires HMR entries from
// builds that predate the field instead of leaving an old legacy socket
// behind during a mode apply.
return entry.connectionId == null
}
/**
* Close only profile sockets that follow the legacy v1 connection config.
*
* A global mode apply re-homes the primary backend, but registered connection
* sockets are independent sources in the v2 registry. Closing every secondary
* here would detach their sessions and arm `ws_orphan_reap` even though those
* sources remain valid and reusable. Legacy profile sockets still need to be
* retired because their endpoint is derived from the v1 config being changed.
*/
export function closeLegacySecondaryGateways(): void {
for (const [scope, failure] of g.reauthFailures) {
if (failure.connectionId === null) {
g.reauthFailures.delete(scope)
}
}
for (const [scope, failure] of g.dialFailures) {
if (failure.connectionId === null) {
g.dialFailures.delete(scope)
}
}
closeSecondariesWhere(isLegacySecondary)
}
export function closeSecondaryGateways(): void {
// Full teardown releases every routed-turn lease (class-2 #94284) and the
// renderer-generation ledger; the predicate close leaves live sources'
// leases alone (their sockets stay open).
for (const timer of g.turnLeaseReleaseTimers.values()) {
clearTimeout(timer)
}
g.turnLeaseReleaseTimers.clear()
for (const release of [...g.turnLeases.values()]) {
release()
}
g.turnLeases.clear()
g.dialFailures.clear()
closeSecondariesWhere(() => true)
openedSecondaryScopes().clear()
g.reauthFailures.clear()
}
// A local profile can have two renderer-owned sockets: the legacy bare
// profile scope and the explicit `local` registry scope. Profile deletion
// stops their Electron backend processes, but a retained Secondary otherwise
// sees that shutdown as a transient disconnect and starts its reconnect loop,
// resurrecting the backend that was just deleted. Retire both local scopes
// before the DELETE request while preserving same-named agents on remote,
// cloud, or SSH connections.
export function retireLocalProfileGateways(profile: string): void {
const name = String(profile || '').trim()
if (!name) {
return
}
const key = normKey(name)
const scopes = new Set([key, registryBackendScopeKey('local', key)])
let activeInvalidated = false
// A profile-only owner is a claim about the legacy local pool, not durable
// session identity. Clear it with that pool before a delayed session action
// can recreate the deleted/old-name backend. Exact remote owners are
// descriptors and remain routable even when they share this profile name.
g.config?.onLocalProfileRetired?.(key)
for (const scope of scopes) {
const entry = g.secondaries.get(scope)
if (!entry) {
continue
}
activeInvalidated ||= scope === g.activeKey
disposeSecondary(entry)
g.secondaries.delete(scope)
}
restoreActiveToPrimaryIfEvicted()
if (activeInvalidated) {
g.config?.onActiveConnectionInvalidated?.(g.primaryProfile, gatewayActivationEpoch())
}
}
// Registry lifecycle: a connection was removed or materially edited. Removal
// disposes every scoped secondary immediately (a removed remote/cloud source
// has no local process to die, so otherwise its WebSocket streams ghost
// events). A material edit redials each profile through the normal open path so
// fresh sockets target the NEW endpoint, but request/relay leases and mounted
// foreground runtimes keep their old socket until they drain; the active scope
// re-activates when its replacement is safe to publish.
export function disposeSecondariesForConnection(connectionId: string, opts: { redial?: boolean } = {}): void {
const id = String(connectionId || '').trim()
let activeInvalidated = false
if (!id) {
return
}
for (const [scope, failure] of g.reauthFailures) {
if (failure.connectionId === id) {
g.reauthFailures.delete(scope)
}
}
// Replacing a connection is a fresh start: its old failures must not hold back the new dial.
for (const [scope, failure] of g.dialFailures) {
if (failure.connectionId === id) {
g.dialFailures.delete(scope)
}
}
for (const [key, entry] of [...g.secondaries]) {
if (entry.connectionId !== id) {
continue
}
const wasActive = key === g.activeKey
activeInvalidated ||= wasActive
if (opts.redial && (entry.activeRequests > 0 || entry.relayRetainCount > 0 || foregroundPinned(entry))) {
entry.pendingConnectionRedial = true
continue
}
disposeSecondary(entry)
g.secondaries.delete(key)
if (opts.redial) {
reopenAfterRedial(entry, wasActive)
}
}
if (activeInvalidated && !opts.redial) {
setActive(g.primaryProfile)
g.config?.onActiveConnectionInvalidated?.(g.primaryProfile, gatewayActivationEpoch())
}
}
// Self-accept so editing this module (or a fan-out that lands here) is an
// in-place hot update instead of a full page reload — the live sockets in `g`
// survive the swap. Dev-only: production strips import.meta.hot.
if (import.meta.hot) {
import.meta.hot.accept()
}