Skip to content

The agent that grows with you

37.4 KB
Raw Blame
import {
  type GatewayEvent,
  type GatewayEventName,
  JsonRpcGatewayClient,
  type ServerRequest,
  type ServerRequestHandler
} from '@hermes/shared'
import { map, type MapStore } from 'nanostores'

import type { HermesApiRequest } from '@/global'

import { CanonicalDesktopProtocol, canonicalProfile, canonicalPromptParams, canonicalSessionKey, openGatewaySocket, recordCanonicalOwner, splitRewindSubmit } from './canonical-protocol'

// Desktop startup fires a burst of read-only data calls (config, profiles,
// model info/options, cron) the moment the backend passes readiness. On a
// profile-heavy or remote install these can each take tens of seconds — e.g.
// /api/profiles runs list_profiles(), which does a recursive skill-tree walk
// per profile — so the 15s default (DEFAULT_FETCH_TIMEOUT_MS in hardening.ts)
// times out a backend that is alive-but-busy, surfacing as a spurious
// "Timed out connecting to Hermes backend" that hangs the UI (#48504).
//
// Give the boot burst a generous per-call timeout instead of raising the
// global default: interactive/runtime calls and the liveness poll (/api/status)
// keep the short default so a genuinely-dead backend is still detected fast.
export const STARTUP_REQUEST_TIMEOUT_MS = 60_000
const DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS = 30_000
// prompt.submit is effectively fire-and-forget: turn completion is signaled by
// stream / message.complete events, NOT by the RPC return. A long turn (MoA
// presets running references + aggregator in series, deep reasoning, large tool
// chains) can legitimately take minutes to ACK, so bounding the ack by the
// generic 30s default surfaces a false "request timed out" toast while the turn
// is still running and will succeed (issue #55024). Match the backend's
// agent-turn ceiling (agent.gateway_timeout = 1800s) so the ack timeout only
// ever fires when the turn itself would have been abandoned server-side.
export const PROMPT_SUBMIT_REQUEST_TIMEOUT_MS = 1_800_000

export const GATEWAY_NOT_CONNECTED_MESSAGE = 'Hermes gateway is not connected'

// Canonical shared prompts (`gateway/session_pending_controls.py`) travel as
// `approval.request` / `clarify.request` EVENTS keyed by `prompt_id` and are
// answered through `approval.respond` / `clarify.respond`. The renderer only
// knows server→client REQUESTS (#110521), so each prompt event is delivered to
// the same `onRequest` registry as a request whose `respond` issues the RPC.
const CANONICAL_PROMPT_EVENTS: Record<string, 'approval' | 'clarify'> = { 'approval.request': 'approval', 'clarify.request': 'clarify' }

const ATTACH_REQUIRED = new Set([
  'prompt.submit',
  'approval.respond',
  'clarify.respond',
  'session.interrupt',
  'prompt.cancel',
  'session.rewind',
  'prompt.steer_queued',
  'prompt.replace_queued'
])

// A branch is a CAS mutation on the PARENT: an un-attached parent (right-click on a sidebar row
// that was never opened) has no cached revision, so attach it first to learn one. Move to project
// (`session_key`) is the same CAS mutation on a sidebar row.
const PARENT_ATTACH_REQUIRED = new Set(['session.branch_stored', 'session.branch_whole', 'session.workspace.move'])

// Canonical-only identity keys. The legacy `hermes serve` contract refuses an unknown key as
// version skew (4000), so they are stripped on a non-canonical dial. `prompt.submit` keeps its
// `submission_id` on purpose: the submit path retries identityless on that exact refusal and
// records the send as legacy-attempted, which a silent strip here would hide. A message-level
// `session.branch` keeps its legacy `count` prefix; only the canonical row boundary is dropped.
const LEGACY_STRIP: Record<string, string[]> = {
  'session.create': ['request_id'],
  'session.branch_stored': ['request_id'],
  'session.branch': ['through_message_id']
}

function legacyParams(method: string, params: Record<string, unknown>): Record<string, unknown> {
  const strip = LEGACY_STRIP[method]

  if (!strip || !strip.some(key => key in params)) { return params }

  return Object.fromEntries(Object.entries(params).filter(([key]) => !strip.includes(key)))
}

// A caller timeout of 0 (or less) means no deadline, as in the shared channel, which arms no timer
// for it. Callers that wait on a way-out offer instead (onboarding.state / onboarding.start) pass 0.
function requestDeadline(timeoutMs: number | undefined): number {
  const budget = timeoutMs ?? DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS

  return budget > 0 ? Date.now() + budget : Number.POSITIVE_INFINITY
}

function remainingRequestBudget(deadline: number, signal?: AbortSignal): number {
  signal?.throwIfAborted()

  if (deadline === Number.POSITIVE_INFINITY) { return 0 }
  const remaining = deadline - Date.now()

  if (remaining <= 0) { throw new Error('Hermes gateway request timed out') }

  return remaining
}

export class HermesGateway extends JsonRpcGatewayClient {
  private canonical = false
  private readonly protocol = new CanonicalDesktopProtocol()
  private readonly promptHandlers = new Set<ServerRequestHandler>()
  // A stored ID can exist in several profile islands (for example after import).
  private readonly deliveredPrompts = new Map<string, { sessionId: string; profile: string }>()
  private readonly sessionProfiles = new Map<string, Set<string>>()
  private readonly profileAliases = new Map<string, string>()
  private readonly replayProfiles = new Map<string, { sessionId: string; profile: string }>()
  private readonly displayProfiles = new Map<string, string>()
  private readonly eventRoutes = new WeakMap<GatewayEvent, string>()
  private readonly reconciledEpochs = new Set<string>()
  // Frames of an ambiguous (session, epoch) parked until its owner probes settle.
  private readonly parkedFrames = new Map<string, Array<() => void>>()
  private connectionGeneration = 0

  override onRequest(handler: ServerRequestHandler): () => void {
    this.promptHandlers.add(handler)
    const off = super.onRequest(handler)

    return () => {
      this.promptHandlers.delete(handler)
      off()
    }
  }

  private deliverCanonicalPrompt(event: { type: string; session_id?: string; profile?: string; payload?: unknown }, replayed: boolean) {
    const kind = CANONICAL_PROMPT_EVENTS[event.type]
    const p = event.payload as Record<string, unknown> | undefined
    const sid = event.session_id

    if (!kind || !p || !sid || typeof p.prompt_id !== 'string') { return }
    const id = p.prompt_id
    const profile = canonicalProfile(event.profile)
    const generation = this.connectionGeneration

    if (this.deliveredPrompts.has(id)) { return }
    this.deliveredPrompts.set(id, { sessionId: sid, profile })
    const params = canonicalPromptParams(kind, sid, p)

    let settled = false

    const request: ServerRequest = {
      id,
      method: kind,
      params,
      replayed,
      respond: result => {
        if (settled || generation !== this.connectionGeneration) { return }
        settled = true

        // A clarify reply without an answer (skip, Stop, cancel) is the empty answer the
        // authority records as skipped; `clarify.respond` refuses a missing field.
        const answer = kind === 'clarify'
          ? { answer: typeof result.answer === 'string' ? result.answer : '' }
          : { choice: result.choice }

        void this.request(`${kind}.respond`, { session_id: sid, profile, request_id: id, ...answer })
          .catch(() => this.recoverCanonicalPrompt(id, sid, profile, generation))
      },
      // A card this window declined (a stopped session) is not delivered: the next authoritative
      // snapshot that still lists the prompt shows it again. Only answered prompts stay deduplicated.
      fail: () => {
        if (settled) { return }
        settled = true

        if (generation === this.connectionGeneration) { this.deliveredPrompts.delete(id) }
      }
    }

    recordCanonicalOwner(request, this.displayProfiles.get(canonicalSessionKey(sid, profile)) ?? profile)

    for (const handler of this.promptHandlers) {
      if (handler(request) !== false) { return }
    }
  }

  private async recoverCanonicalPrompt(id: string, sessionId: string, profile: string, generation: number): Promise<void> {
    if (generation !== this.connectionGeneration || !this.deliveredPrompts.has(id)) { return }
    this.deliveredPrompts.delete(id)

    // A lost reply may have committed. Reopen a card only if the authority's
    // snapshot still lists it; never resend an approval from a cached event.
    try { await this.request('session.resume', { session_id: sessionId, profile }) } catch {
      // A disconnected socket will reconcile its pending prompts on reattach.
    }
  }

  override close(): void {
    this.connectionGeneration++
    this.deliveredPrompts.clear()
    this.sessionProfiles.clear()
    this.profileAliases.clear()
    this.retainReplayOwners()
    this.displayProfiles.clear()
    this.reconciledEpochs.clear()
    this.parkedFrames.clear()
    this.attached.clear()
    super.close()
  }

  // An epoch's owner qualifies the shared client's retained replay cursor, not this socket's
  // attachments: it lives exactly as long as that cursor, so a redial replays to the same owner.
  private retainReplayOwners(): void {
    const cursors = this.getSeqWatermarks()

    for (const [epoch, owner] of this.replayProfiles) {
      if (!(owner.sessionId in cursors)) { this.replayProfiles.delete(epoch) }
    }
  }

  override on<K extends GatewayEventName>(type: K, handler: (event: GatewayEvent<K>) => void): () => void {
    // Named listeners run before wildcard listeners in the shared client.
    // Normalize before either kind sees the prompt, including replay delivery.
    return super.on<K>(type, event => this.deliverNormalized(event, handler as (event: GatewayEvent) => void))
  }

  override onAny(handler: (event: GatewayEvent) => void): () => void {
    return super.onAny(event => this.deliverNormalized(event, handler))
  }

  private deliverNormalized(event: GatewayEvent, handler: (event: GatewayEvent) => void): void {
    const key = JSON.stringify([event.session_id, event.replay_epoch])
    // While an owner probe for this (session, epoch) runs, its frames wait and deliver in order.
    const parked = this.canonical && event.session_id ? this.parkedFrames.get(key) : undefined

    const deliver = () => {
      if (!this.canonical || this.normalizeCanonicalEvent(event)) { handler(event) }
    }

    if (parked) {
      parked.push(deliver)
    } else if (!this.canonical || this.normalizeCanonicalEvent(event)) {
      handler(event)
    } else {
      // The owner probe this frame just started may establish its route; it is the first frame parked.
      this.parkedFrames.get(key)?.push(deliver)
    }
  }


  private rememberSessionProfile(sessionId: string, profile: unknown): void {
    const profiles = this.sessionProfiles.get(sessionId) ?? new Set<string>()
    profiles.add(this.resolveSessionProfile(sessionId, profile))
    this.sessionProfiles.set(sessionId, profiles)
  }

  private resolveSessionProfile(sessionId: string, profile: unknown): string {
    return this.profileAliases.get(canonicalSessionKey(sessionId, profile)) ?? canonicalProfile(profile)
  }

  private snapshotRoute(params: Record<string, unknown>, snapshot: any): Record<string, unknown> {
    const sid = snapshot?.session_id

    if (typeof sid !== 'string') { return params }
    const previous = canonicalProfile(params.profile)
    const replayOwner = this.replayProfiles.get(snapshot.replay_epoch)
    const named = snapshot.info?.profile_name

    const profile = typeof named === 'string' && named ? named :
      replayOwner?.sessionId === sid ? replayOwner.profile : previous

    this.profileAliases.set(canonicalSessionKey(sid, previous), profile)

    if (typeof snapshot.info?.profile_id === 'string') {
      this.profileAliases.set(canonicalSessionKey(sid, snapshot.info.profile_id), profile)
    }

    const profiles = this.sessionProfiles.get(sid)
    profiles?.delete(previous)
    this.rememberSessionProfile(sid, profile)

    // The implicit route of a named launch profile and its explicit name are
    // one owner. Store retry identities under that stable name across redials.
    return profile === previous ? params : { ...params, profile }
  }

  private normalizeCanonicalEvent(event: GatewayEvent): boolean {
    if (!event.session_id) { return true }
    const owner = event.replay_epoch ? this.replayProfiles.get(event.replay_epoch) : undefined
    const profiles = this.sessionProfiles.get(event.session_id)

    let profile = owner?.sessionId === event.session_id ? owner.profile : this.eventRoutes.get(event) ??
      (profiles?.size === 1 ? profiles.values().next().value : profiles?.size ? undefined : 'default')

    if (profile === undefined) {
      this.reconcileAmbiguousEvent(event.session_id, event.replay_epoch)

      return false
    }

    profile = this.resolveSessionProfile(event.session_id, profile)
    // The renderer already understands an owner profile tag on shared-socket events.
    this.eventRoutes.set(event, profile)
    event.profile = this.displayProfiles.get(canonicalSessionKey(event.session_id, profile)) ?? profile
    recordCanonicalOwner(event, event.profile)
    this.protocol.event({ ...event, profile })

    return true
  }

  private reconcileAmbiguousEvent(sessionId: string, epoch?: string): void {
    const key = JSON.stringify([sessionId, epoch])

    if (this.reconciledEpochs.has(key)) { return }
    this.reconciledEpochs.add(key)
    this.parkedFrames.set(key, [])
    const generation = this.connectionGeneration

    // A new/unknown replay epoch cannot choose between equal stored IDs. One
    // authoritative snapshot per known owner recovers cards and establishes routes.
    const probes = [...this.sessionProfiles.get(sessionId) ?? []].map(profile =>
      this.request('session.resume', { session_id: sessionId, profile }))

    void Promise.allSettled(probes).then(results => {
      if (generation !== this.connectionGeneration) { return }
      const parked = this.parkedFrames.get(key) ?? []
      this.parkedFrames.delete(key)

      // No owner answered: a later frame probes again instead of being dropped until reconnect.
      if (!results.some(result => result.status === 'fulfilled')) {
        this.reconciledEpochs.delete(key)

        return
      }

      for (const deliver of parked) { deliver() }
    })
  }

  protected override isDesktopLocal(): boolean {
    return this.canonical
  }

  override async connect(wsUrl: string): Promise<void> {
    this.connectionGeneration++
    this.canonical = new URL(wsUrl).searchParams.has('native_dial')
    this.attached.clear()
    this.deliveredPrompts.clear()
    this.sessionProfiles.clear()
    this.profileAliases.clear()
    this.retainReplayOwners()
    this.displayProfiles.clear()
    this.reconciledEpochs.clear()
    this.parkedFrames.clear()

    return super.connect(wsUrl)
  }

  // Sessions attached over THIS socket. An authority subscription is per
  // transport: when routing moves a session to another socket (a profile split,
  // a redial) the new socket must resume before it may submit or respond.
  private attached = new Set<string>()

  private routeCanonicalParams(method: string, params: Record<string, unknown>): Record<string, unknown> {
    if (method === 'session.events.since' && params.profile === undefined && typeof params.replay_epoch === 'string') {
      const owner = this.replayProfiles.get(params.replay_epoch)

      // The shared client's reconnect cursor predates the new socket's
      // attachments. Never route an unknown old cursor to the launch profile.
      if (!owner || owner.sessionId !== params.session_id) { throw new Error('Replay owner unavailable; reopen the session') }
      params = { ...params, profile: owner.profile }
    }

    // Prompt callbacks carry session identity, while sibling sessions share the
    // primary socket. Keep the route learned from their successful attachment.
    const sid = params.session_id ?? params.parent_session_id

    if (typeof sid === 'string' && params.profile !== undefined) {
      params = { ...params, profile: this.resolveSessionProfile(sid, params.profile) }
    }

    const profiles = this.sessionProfiles.get(String(sid ?? ''))

    if (params.profile === undefined && profiles?.size) {
      if (profiles.size !== 1) { throw new Error('Session ID belongs to several profiles; select its owner profile before continuing') }
      const profile = profiles.values().next().value!

      if (profile !== 'default') { params = { ...params, profile } }
    }

    if (typeof sid === 'string' && ['session.resume', 'session.activate'].includes(method)) {
      // Live frames may precede the attachment ACK. Register its explicit route
      // before the await; concurrent equal-ID mounts are reconciled above.
      this.rememberSessionProfile(sid, params.profile)
    }

    return params
  }

  override async request<T>(method: string, params: Record<string, unknown> = {}, timeoutMs?: number, signal?: AbortSignal): Promise<T> {
    if (!this.canonical) { return super.request<T>(method, legacyParams(method, params), timeoutMs, signal) }
    const generation = this.connectionGeneration
    const deadline = requestDeadline(timeoutMs)
    // A truncating submit (edit / regenerate / restore) is the owner's rewind, then the submit.
    const rewind = method === 'prompt.submit' ? splitRewindSubmit(params) : null

    if (rewind) {
      if (rewind.rewind) { await this.request('session.rewind', rewind.rewind, remainingRequestBudget(deadline, signal), signal) }

      return this.request<T>('prompt.submit', rewind.submit, remainingRequestBudget(deadline, signal), signal)
    }

    // A question's owner is immutable even when a second profile attaches an
    // equal stored session ID while the first card remains open.
    const promptOwner = method === 'clarify.lock' ? this.deliveredPrompts.get(String(params.request_id ?? '')) : undefined

    if (promptOwner) {
      const answer = typeof params.answer === 'string' ? params.answer : ''

      return this.request<T>('clarify.respond', { session_id: promptOwner.sessionId, profile: promptOwner.profile, request_id: params.request_id, answer }, timeoutMs, signal)
    }

    params = this.routeCanonicalParams(method, params)

    await this.attachForRequest(method, params, deadline, signal)
    this.requireConnectionGeneration(generation)
    // The attach may have identified the named launch profile behind an
    // implicit route. Its revision and generation are cached under that owner.
    params = this.routeCanonicalParams(method, params)

    // Answered locally only once the owner's route is known: a named launch profile's
    // retained rewind is keyed under its name, which a redial forgets until the attach.
    const local = this.protocol.localAnswer(method, params)

    if (local) { return local as T }

    // The clarify card answers a whole question set as one form: declared, the owner asks the
    // turn's multi-question clarify as ONE request; undeclared, one card per question. An older
    // owner refuses the unknown key, so it rides only where `client.capabilities` advertised it.
    if (method === 'prompt.submit' && this.backendClarifyBatch) { params = { ...params, clarify_batch: true } }

    let prepared = this.protocol.prepare(method, params)
    const wireMethod = this.protocol.wire(method, prepared)

    try {
      let result: T

      try {
        result = await super.request<T>(wireMethod, prepared, remainingRequestBudget(deadline, signal), signal)
      } catch (error) {
        if (!this.protocol.retryableFence(prepared, error)) { throw error }
        // The refusal carried the owner's current fences: one retry at them, never a loop.
        this.protocol.failure(prepared, error)
        this.requireConnectionGeneration(generation)
        prepared = this.protocol.prepare(method, params)
        result = await super.request<T>(wireMethod, prepared, remainingRequestBudget(deadline, signal), signal)
      }

      this.requireConnectionGeneration(generation)

      if (['session.resume', 'session.create', 'session.activate'].includes(method)) {
        prepared = this.snapshotRoute(prepared, result)
      }

      // A settle follow-up (compress -> resume) inherits the caller's deadline and cancellation.
      const followUp = (m: string, p: Record<string, unknown>) => {
        this.requireConnectionGeneration(generation)

        return this.request(m, p, remainingRequestBudget(deadline, signal), signal)
      }

      const settled = await this.protocol.settle(method, prepared, this.protocol.result(method, prepared, result), followUp) as T
      this.requireConnectionGeneration(generation)

      if (method === 'session.resume' || method === 'session.create' || method === 'session.activate') {
        this.adoptAttachedSnapshot(settled as { session_id?: string; prompts?: Array<Record<string, unknown>> }, prepared.profile)
      }

      return settled
    } catch (error) {
      this.protocol.failure(prepared, error)
      throw error
    }
  }

  private requireConnectionGeneration(generation: number): void {
    if (generation !== this.connectionGeneration) { throw new Error('Hermes gateway connection changed; reopen the session') }
  }

  // Resume the session (and, for branch-like methods, its parent) on THIS socket before a
  // method that needs an authority subscription here.
  private async attachForRequest(method: string, params: Record<string, unknown>, deadline: number, signal?: AbortSignal): Promise<void> {
    const sid = typeof params.session_id === 'string' ? params.session_id : null

    const resume = (sessionId: string) => this.request('session.resume', {
      session_id: sessionId, defer_history: true, omit_messages: true,
      ...(params.profile ? { profile: params.profile } : {})
    }, remainingRequestBudget(deadline, signal), signal)

    if (sid && ATTACH_REQUIRED.has(method) && !this.attached.has(canonicalSessionKey(sid, params.profile))) {
      await resume(sid)
    }

    const parent = PARENT_ATTACH_REQUIRED.has(method) ? params.parent_session_id ?? params.session_id ?? params.session_key : null

    if (typeof parent === 'string' && parent && !this.attached.has(canonicalSessionKey(parent, params.profile))) {
      await resume(parent)
    }
  }

  private adoptAttachedSnapshot(settled: { session_id?: string; replay_epoch?: string; info?: { profile_name?: string }; prompts?: Array<Record<string, unknown>> }, profile?: unknown): void {
    // Prompts still open on the authority re-deliver like `open_requests` after a reconnect.
    const sid = settled.session_id

    if (sid) {
      this.attached.add(canonicalSessionKey(sid, profile))
      this.rememberSessionProfile(sid, profile)

      if (settled.info?.profile_name) {
        this.displayProfiles.set(canonicalSessionKey(sid, profile), settled.info.profile_name)
      }

      if (typeof settled.replay_epoch === 'string') {
        this.replayProfiles.set(settled.replay_epoch, { sessionId: sid, profile: canonicalProfile(profile) })
      }
    }

    for (const prompt of (settled.prompts ?? [])) {
      this.deliverCanonicalPrompt({ type: `${prompt.kind}.request`, session_id: sid, profile: canonicalProfile(profile), payload: prompt }, true)
    }
  }

  constructor() {
    super({
      closedErrorMessage: 'Hermes gateway connection closed',
      connectErrorMessage: 'Could not connect to Hermes gateway',
      createRequestId: nextId => nextId,
      notConnectedErrorMessage: GATEWAY_NOT_CONNECTED_MESSAGE,
      // The channel already answered -32603; surface the crash in devtools like the dial-failure sink.
      onRequestHandlerError: (error, request) =>
        console.error(`[gateway] server request handler crashed for ${request.method} (${request.id}):`, error),
      // The channel already answered -32601; note the missing registry in devtools.
      onUnhandledRequest: request =>
        console.warn(`[gateway] Hermes Desktop has no server-request registry for ${request.method} (${request.id})`),
      requestTimeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS,
      socketFactory: openGatewaySocket
    })
    this.onEvent(event => {
      if (!this.canonical) { return }

      if (event.type in CANONICAL_PROMPT_EVENTS) {
        this.deliverCanonicalPrompt({ ...event, profile: this.eventRoutes.get(event) }, false)
      } else if (event.type.endsWith('.settled')) {
        const id = (event.payload as { prompt_id?: unknown } | undefined)?.prompt_id

        if (typeof id === 'string') { this.deliveredPrompts.delete(id) }
      }
    })
  }
}

// Profile that profile-scoped REST settings (config/env/skills/tools/model/…)
// should target. Mirrors $activeGatewayProfile, pushed in from the store via
// setApiRequestProfile so this module needs no store import (avoids a cycle).
// Electron main consumes request.profile as request scope. Local calls whose
// REST handlers accept profile reuse the primary dashboard via ?profile=;
// unscoped handlers retain a profile backend. Remote overrides still route to
// their owning backend. Null → primary, so single-profile users are unaffected.
interface ApiRequestScope {
  profile: string | null
  connectionId: string | null
}

// This is the request authority, not a second copy in a presentation store.
export const $apiRequestScope: MapStore<ApiRequestScope> = map<ApiRequestScope>({ profile: null, connectionId: null })

export function setApiRequestProfile(profile: null | string): void {
  $apiRequestScope.setKey('profile', profile || null)
}

// An explicit scope (string or object, not `undefined`/`null`) is a user
// pointing a scope selector (Settings "Applies to", Capabilities, Messaging)
// at another profile — a visible action whose cold dial may take the pool's
// reserved foreground slot (#111651). The ambient path and the deliberate
// `null` → primary path stay untagged (main's background default) so
// hydration cannot consume that slot. The tag rides on the scope helper itself
// so no api/ helper can carry a scope without it.
export function profileScoped(profile?: null | string): { priority?: 'foreground'; profile?: string } {
  const selected = profile === undefined ? $apiRequestScope.get().profile : profile

  return {
    ...(selected ? { profile: selected } : {}),
    ...(profile == null ? {} : { priority: 'foreground' as const })
  }
}

/** A session's OWNER as a request scope: a profile belongs to ONE gateway, so
 *  a Bot on another connection is (its connection, its profile) — never the
 *  active connection with the Bot's profile name. Missing halves fall back to
 *  the ambient scope; an explicit connection — `'local'` included — overrides
 *  the ambient tag `hermesApi` spreads underneath (as capabilityScoped does). */
export interface OwnerScope {
  connectionId?: null | string
  profile?: null | string
}

export function ownerScoped(owner?: OwnerScope): { connectionId?: string; priority?: 'foreground'; profile?: string } {
  return {
    ...profileScoped(owner?.profile || undefined),
    ...(owner?.connectionId ? { connectionId: owner.connectionId } : {})
  }
}

/** An owner resolved ONCE for one operation (a recording, a voice conversation).
 *  `null` halves mean "untagged": the primary profile / the connection an
 *  untagged request lands on. They are never re-read from the ambient scope
 *  later, so a gateway/profile switch mid-operation cannot move its tail
 *  (release, transcription) to another backend. */
export interface ResolvedOwner {
  connectionId: null | string
  profile: null | string
}

/** Fill an owner's missing halves from the ambient scope, now. */
export function resolveOwnerNow(owner?: OwnerScope): ResolvedOwner {
  const ambient = $apiRequestScope.get()

  return {
    connectionId: owner?.connectionId || ambient.connectionId || null,
    profile: owner?.profile || ambient.profile || null
  }
}

/** `hermesApi` for a resolved owner: its tags are sent verbatim, with no
 *  ambient connection spread underneath. An untagged half stays untagged. A
 *  named profile is always explicit here, so it carries the foreground
 *  priority `profileScoped` gives explicit profiles (voice is user-driven). */
export function hermesApiAs<T>(owner: ResolvedOwner, request: HermesApiRequest): Promise<T> {
  return window.hermesDesktop.api<T>({
    ...(owner.connectionId ? { connectionId: owner.connectionId } : {}),
    ...(owner.profile ? { priority: 'foreground' as const, profile: owner.profile } : {}),
    ...request
  })
}

/** Profile that profile-scoped REST/WS calls should target (null → primary).
 *  Read-only twin of setApiRequestProfile for modules (e.g. voice playback)
 *  that build their own connection URLs and must stay on the same backend. */
export function getApiRequestProfile(): null | string {
  return $apiRequestScope.get().profile
}

// Registry connection serving the active gateway (null → the local pool).
// Pushed from store/gateway's setActive — the single seam BOTH
// ensureGatewayProfile and ensureGatewayAgent funnel through — so WS calls
// that dial their own backend (pluginSocket) resolve it through the SAME
// source of truth those paths maintain for $connection. That makes the plugin
// socket follow registry-agent activations too, not just profile switches.
// Same no-store-import contract as profile scope (avoids a cycle).

export function setApiRequestConnection(connectionId: null | string): void {
  $apiRequestScope.setKey('connectionId', connectionId || null)
}

// Registry connection scope for a REST request. A registered remote gateway
// owns its own state.db — cron jobs and their run sessions live THERE — so
// requests for gateway-owned data must carry the connection id for the main
// process to route them to that host (hermes:api's registry branch). Null
// resolves to no tag, keeping single-source users byte-identical; explicit
// 'local' must remain tagged when the legacy primary points elsewhere.
export function connectionScoped(): { connectionId?: string } {
  const connectionId: string | null = $apiRequestScope.get().connectionId

  return connectionId ? { connectionId } : {}
}

// Whether the window's primary connection is the local pool. Pushed from
// store/session's setConnection (same no-store-import contract as profile scope)
// so api/ helpers can name the backend an UNTAGGED request lands on without
// importing the heavy session store — which would close a module cycle
// through @/hermes.
let _apiLocalMode = false

export function setApiRequestLocalMode(local: boolean): void {
  _apiLocalMode = local
}

/** The connection an ambient (untagged) request is served by: the registry
 *  tag when one is active, else `'local'` for the local pool. Identity only —
 *  never send this as a request pin (an explicit `'local'` bypasses Electron's
 *  legacy per-profile remote overrides). */
export function ambientOwnerConnectionId(): string | undefined {
  return $apiRequestScope.get().connectionId ?? (_apiLocalMode ? 'local' : undefined)
}

/** Send a REST request to the renderer's active registry source. Request-level
 *  routing may override the active source for an explicitly-owned resource.
 *
 *  Helpers under `api/` go through here rather than calling the preload bridge
 *  directly, so the connection tag cannot be forgotten on a new one.
 *  capabilityScoped() now emits an explicit `connectionId` for EVERY object
 *  pin — `'local'` included — so a pin always overrides the ambient tag spread
 *  underneath it. (It used to omit the key for 'local', which made the pin
 *  unable to beat the ambient tag; helpers then had to bypass this wrapper.) */
export function hermesApi<T>(request: HermesApiRequest): Promise<T> {
  return window.hermesDesktop.api<T>({ ...connectionScoped(), ...request })
}

// ── Capability scope: (connection, profile) routing for the Capabilities
// surface (skills / toolsets / MCP / hub / env / toolset config) ────────────
//
// A profile is not a machine-global name — it belongs to ONE gateway. The
// Capabilities surface can be pointed at any (connection, profile) pair
// (CapabilitiesView's scope selector, Bot Mode's fixedProfile/fixedConnection), so
// its REST helpers accept either the legacy string form or an explicit scope
// object:
//
//   - `undefined` / string → the legacy profile path, PLUS the active registry
//     connection tag (connectionScoped, same contract the cron helpers adopted
//     in #87882). Without the tag, a window activated onto a registered remote
//     gateway read the LOCAL pool's skills/tools/MCP — the wrong machine.
//   - `{ connectionId, profile }` → explicit pin. A non-empty connection id —
//     `'local'` INCLUDED — is sent through so Electron's registry resolver
//     owns the routing. Dropping the `'local'` pin (the pre-#91564 behavior,
//     when an absent id always meant the local pool) silently re-routes a
//     "This device" pick to the registry PRIMARY once that primary is a
//     remote/cloud/ssh gateway: the v1 fallback route treats a remote registry
//     primary as global-remote, so the explicit pin is the ONLY way back to
//     this machine (see apiRequestRegistryConnectionId in Electron main).
export type ProfileScope = undefined | null | string | { connectionId?: null | string; profile?: null | string }

export function capabilityScoped(scope?: ProfileScope): {
  connectionId?: string
  priority?: 'foreground'
  profile?: string
} {
  if (scope && typeof scope === 'object') {
    const profile = (scope.profile ?? '').trim()
    const connectionId = (scope.connectionId ?? '').trim()

    return {
      ...(profile ? { profile } : {}),
      ...(connectionId ? { connectionId } : {}),
      priority: 'foreground'
    }
  }

  return { ...profileScoped(scope), ...connectionScoped() }
}

/** Stable cache-key for a capability scope: `profile` for the ambient/legacy
 *  path, `connectionId::profile` for ANY explicit pin — `local` included. An
 *  explicit "This device" pick and the ambient path are no longer guaranteed
 *  to hit the same backend (a remote registry PRIMARY makes the ambient path
 *  remote), so sharing the bare-profile cache row between them painted one
 *  machine's config under the other's scope (AGENTS.md scope-in-key rule). */
export function profileScopeKey(scope?: ProfileScope): string {
  if (scope && typeof scope === 'object') {
    const profile = (scope.profile ?? '').trim() || 'default'
    const connectionId = (scope.connectionId ?? '').trim()

    return connectionId ? `${connectionId}::${profile}` : profile
  }

  return (scope ?? '').trim() || 'default'
}

/** Registry connection id that connection-scoped WS calls should target
 *  (null → the local pool). Read-only twin of setApiRequestConnection. */
export function getApiRequestConnection(): null | string {
  return $apiRequestScope.get().connectionId
}

// ── Session-owner pin for session-scoped REST reads (#125372) ──────────────
//
// A read of /api/sessions/{id}[/messages|/timeline|/messages/around] only
// means anything on the backend that OWNS the row. The store already resolves
// that owner (knownOwnerForSession: tile route → persisted hint → tagged row)
// and pushes the resolver here — same no-store-import seam as
// setApiRequestProfile — so read helpers stop riding the WINDOW's ambient
// connection onto a host that answers 404 "Session not found".

export interface SessionReadOwnerRoute {
  connectionId?: null | string
  profile?: null | string
  targetProfile?: null | string
}

export type SessionOwnerResolver = (sessionId: string) => SessionReadOwnerRoute | null | string | undefined

let _sessionOwnerResolver: SessionOwnerResolver | null = null

export function setSessionOwnerResolver(resolver: SessionOwnerResolver | null): void {
  _sessionOwnerResolver = resolver
}

/** The connection pin a session-scoped READ must carry for `id`, or {} when
 *  the caller already pinned a connection, no exact owner is known, or the
 *  owner is the ambient connection. Pins 'local' too (the only way back to
 *  this device when the primary is a remote registry source). When the caller
 *  named no profile, the owner's backend-facing profile rides along: the
 *  answering host resolves ?profile= against ITS OWN profiles. */
export function sessionReadOwnerPin(id: string, profile?: ProfileScope): { connectionId?: string; profile?: string } {
  if (profile && typeof profile === 'object' && String(profile.connectionId ?? '').trim()) {
    return {}
  }

  const owner = _sessionOwnerResolver?.(id)

  if (!owner || typeof owner === 'string') {
    return {}
  }

  const connectionId = String(owner.connectionId ?? '').trim()

  if (!connectionId || connectionId === (ambientOwnerConnectionId() ?? 'local')) {
    return {}
  }

  const ownerProfile = String(owner.targetProfile || owner.profile || '').trim()

  return {
    connectionId,
    ...(profile == null && ownerProfile ? { profile: ownerProfile } : {})
  }
}

/** The backend a gateway FILE request naming session `id` must go to: the owner's
 *  backend-facing profile, plus its connection when that is not the ambient one.
 *  Null when no owner profile is known. A file route looks `session_id` up in
 *  the profile the request names, so the id must never travel with another
 *  profile: a caller that gets null names no session at all. */
export function sessionFileOwnerScope(id: string): { connectionId?: string; profile: string } | null {
  const owner = _sessionOwnerResolver?.(id)

  if (!owner) {
    return null
  }

  if (typeof owner === 'string') {
    const profile = owner.trim()

    return profile ? { profile } : null
  }

  const profile = String(owner.targetProfile || owner.profile || '').trim()

  if (!profile) {
    return null
  }

  const connectionId = String(owner.connectionId ?? '').trim()

  return connectionId && connectionId !== (ambientOwnerConnectionId() ?? 'local') ? { connectionId, profile } : { profile }
}