The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import type {
AppHandoffStatus,
ConfigSchemaResponse,
CustomEndpointsResponse,
CustomEndpointUpdate,
CustomEndpointValidationResponse,
EnvVarInfo,
HermesConfig,
HermesConfigRecord,
LogsResponse,
OAuthPollResponse,
OAuthProvidersResponse,
OAuthStartResponse,
OAuthSubmitResponse,
StatusResponse
} from '@/types/hermes'
import { capabilityScoped, hermesApi, type ProfileScope, profileScoped, STARTUP_REQUEST_TIMEOUT_MS } from './client'
type ConfigReadOrigin = { connectionId?: string; priority?: 'foreground'; profile?: string }
const configReadOrigins = new WeakMap<object, ConfigReadOrigin>()
// Every origin object ever bound, so resolveConfigWriteScope can tell a
// captured read origin handed back as `writeScope` apart from a fresh
// `{ connectionId, profile }` pin from the scope selector.
const knownConfigReadOrigins = new WeakSet<object>()
/** Snapshot the `(connectionId, profile)` that served a config GET. */
export function bindConfigReadOrigin(record: object, origin: ConfigReadOrigin): void {
configReadOrigins.set(record, origin)
knownConfigReadOrigins.add(origin)
}
export function peekConfigReadOrigin(record: object | undefined | null): ConfigReadOrigin | undefined {
return record ? configReadOrigins.get(record) : undefined
}
/** Carry `source`'s read origin onto a record derived from it, so the next write still routes to the gateway that served the GET. */
export function retainConfigReadOrigin<T extends object>(next: T, source: object | null | undefined): T {
const origin = peekConfigReadOrigin(source)
if (origin) {
bindConfigReadOrigin(next, origin)
}
return next
}
/**
* Route a config write to the identity that served the matching read.
* An explicit `{ connectionId, profile }` pin wins. A GET-derived record
* keeps its captured origin even after the registry primary changes.
* Unbound writes (no captured origin, no object pin) keep the live ambient
* capability scope — e.g. reset-to-defaults on the current connection.
*/
export function resolveConfigWriteScope(
record: object | undefined,
requestScope?: ProfileScope
): { connectionId?: string; priority?: 'foreground'; profile?: string } {
if (requestScope && typeof requestScope === 'object') {
// A captured read origin (the hook's `writeScope`) is already a
// capabilityScoped() result. Spread it exactly like the WeakMap branch
// below instead of re-running capabilityScoped, which would stamp
// `priority: 'foreground'` onto an AMBIENT origin that never carried it —
// the two branches must yield the same tag for the same read.
return knownConfigReadOrigins.has(requestScope)
? { ...(requestScope as ConfigReadOrigin) }
: capabilityScoped(requestScope)
}
const captured = peekConfigReadOrigin(record)
if (captured) {
const profile = typeof requestScope === 'string' ? requestScope.trim() : ''
// Spread, don't rebuild: the captured origin is a capabilityScoped()
// result and may carry `priority: 'foreground'`; an explicit profile
// string gets the same foreground priority profileScoped(string) grants.
return {
...captured,
...(profile ? { profile, priority: 'foreground' as const } : {})
}
}
return capabilityScoped(requestScope)
}
export function getStatus(): Promise<StatusResponse> {
return hermesApi<StatusResponse>({
...profileScoped(),
path: '/api/status'
})
}
export function getLogs(params: {
component?: string
file?: string
level?: string
lines?: number
search?: string
}): Promise<LogsResponse> {
const query = new URLSearchParams()
if (params.file) {
query.set('file', params.file)
}
if (typeof params.lines === 'number') {
query.set('lines', String(params.lines))
}
if (params.level && params.level !== 'ALL') {
query.set('level', params.level)
}
if (params.component && params.component !== 'all') {
query.set('component', params.component)
}
if (params.search) {
query.set('search', params.search)
}
const suffix = query.toString()
return hermesApi<LogsResponse>({
...profileScoped(),
path: suffix ? `/api/logs?${suffix}` : '/api/logs'
})
}
export function getHermesConfig(profile?: string): Promise<HermesConfig> {
return hermesApi<HermesConfig>({
...profileScoped(profile),
path: '/api/config',
timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
})
}
/** GET a config record on the capability scope and bind the serving
* `(connectionId, profile)` to it so the matching write routes back there. */
async function fetchBoundConfigRecord(
profile: ProfileScope,
request: { path: string; timeoutMs?: number }
): Promise<HermesConfigRecord> {
const origin = capabilityScoped(profile ?? undefined)
const record = await window.hermesDesktop.api<HermesConfigRecord>({ ...origin, ...request })
if (record && typeof record === 'object') {
bindConfigReadOrigin(record, origin)
}
return record
}
export function getHermesConfigRecord(
profile?: ProfileScope,
{ includeDefaults = true }: { includeDefaults?: boolean } = {}
): Promise<HermesConfigRecord> {
return fetchBoundConfigRecord(profile, {
path: includeDefaults ? '/api/config' : '/api/config?include_defaults=false'
})
}
export function getHermesConfigDefaults(): Promise<HermesConfigRecord> {
return fetchBoundConfigRecord(undefined, {
path: '/api/config/defaults',
timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
})
}
export function getHermesConfigSchema(profile?: null | string): Promise<ConfigSchemaResponse> {
return hermesApi<ConfigSchemaResponse>({
...profileScoped(profile),
path: '/api/config/schema'
})
}
export function saveHermesConfig(
config: HermesConfigRecord,
profile?: ProfileScope,
{ preserveLanguage = false }: { preserveLanguage?: boolean } = {}
): Promise<{ ok: boolean }> {
return window.hermesDesktop.api<{ ok: boolean }>({
...resolveConfigWriteScope(config, profile),
path: preserveLanguage ? '/api/config?preserve_language=true' : '/api/config',
method: 'PUT',
body: { config }
})
}
/** Capability-scoped counterpart of saveHermesConfig — writes the config of
* the profile/connection the Capabilities scope selector points at (possibly
* on another registered gateway), mirroring getHermesConfigRecord. */
export function saveHermesConfigRecord(config: HermesConfigRecord, profile?: ProfileScope): Promise<{ ok: boolean }> {
return window.hermesDesktop.api<{ ok: boolean }>({
...resolveConfigWriteScope(config, profile),
path: '/api/config',
method: 'PUT',
body: { config }
})
}
export function getEnvVars(profile?: null | string): Promise<Record<string, EnvVarInfo>> {
return hermesApi<Record<string, EnvVarInfo>>({
...profileScoped(profile),
path: '/api/env'
})
}
// `providerSetup`: the caller is connecting a model provider, so shared metrics count the save as a
// provider setup even when a tool panel uses the same key (Gemini, xAI...).
export function setEnvVar(
key: string,
value: string,
profile?: ProfileScope,
{ providerSetup = false }: { providerSetup?: boolean } = {}
): Promise<{ ok: boolean }> {
return window.hermesDesktop.api<{ ok: boolean }>({
...capabilityScoped(profile),
path: '/api/env',
method: 'PUT',
body: providerSetup ? { key, provider_setup: true, value } : { key, value }
})
}
export function deleteEnvVar(key: string, profile?: ProfileScope): Promise<{ ok: boolean }> {
return window.hermesDesktop.api<{ ok: boolean }>({
...capabilityScoped(profile),
path: '/api/env',
method: 'DELETE',
body: { key }
})
}
export function revealEnvVar(key: string, profile?: ProfileScope): Promise<{ key: string; value: string }> {
return window.hermesDesktop.api<{ key: string; value: string }>({
...capabilityScoped(profile),
path: '/api/env/reveal',
method: 'POST',
body: { key }
})
}
export function validateProviderCredential(
key: string,
value: string,
apiKey?: string,
profile?: ProfileScope
): Promise<{ ok: boolean; reachable: boolean; message: string; models?: string[]; resolved_base_url?: string }> {
return window.hermesDesktop.api<{
ok: boolean
reachable: boolean
message: string
models?: string[]
resolved_base_url?: string
}>({
...capabilityScoped(profile),
path: '/api/providers/validate',
method: 'POST',
body: { key, value, api_key: apiKey ?? '' }
})
}
export function getCustomEndpoints(profile?: null | string): Promise<CustomEndpointsResponse> {
return hermesApi<CustomEndpointsResponse>({
...profileScoped(profile),
path: '/api/providers/custom-endpoints'
})
}
export function saveCustomEndpoint(
endpoint: CustomEndpointUpdate,
profile?: null | string
): Promise<CustomEndpointsResponse> {
return hermesApi<CustomEndpointsResponse>({
...profileScoped(profile),
path: '/api/providers/custom-endpoints',
method: 'POST',
body: endpoint
})
}
export function validateCustomEndpoint(
endpoint: CustomEndpointUpdate,
profile?: null | string
): Promise<CustomEndpointValidationResponse> {
return hermesApi<CustomEndpointValidationResponse>({
...profileScoped(profile),
path: '/api/providers/custom-endpoints/validate',
method: 'POST',
body: endpoint
})
}
export function activateCustomEndpoint(
id: string,
profile?: null | string
): Promise<{ ok: boolean; provider: string; model: string }> {
return hermesApi<{ ok: boolean; provider: string; model: string }>({
...profileScoped(profile),
path: `/api/providers/custom-endpoints/${encodeURIComponent(id)}/activate`,
method: 'POST'
})
}
export function deleteCustomEndpoint(id: string, profile?: null | string): Promise<CustomEndpointsResponse> {
return hermesApi<CustomEndpointsResponse>({
...profileScoped(profile),
path: `/api/providers/custom-endpoints/${encodeURIComponent(id)}`,
method: 'DELETE'
})
}
export function listOAuthProviders(profile?: ProfileScope): Promise<OAuthProvidersResponse> {
return window.hermesDesktop.api<OAuthProvidersResponse>({
...capabilityScoped(profile),
path: '/api/providers/oauth'
})
}
export function disconnectOAuthProvider(
providerId: string,
profile?: null | string
): Promise<{ ok: boolean; provider: string }> {
return hermesApi<{ ok: boolean; provider: string }>({
...profileScoped(profile),
path: `/api/providers/oauth/${encodeURIComponent(providerId)}`,
method: 'DELETE'
})
}
export function startOAuthLogin(providerId: string, profile?: ProfileScope): Promise<OAuthStartResponse> {
return window.hermesDesktop.api<OAuthStartResponse>({
...capabilityScoped(profile),
path: `/api/providers/oauth/${encodeURIComponent(providerId)}/start`,
method: 'POST',
body: {}
})
}
export function submitOAuthCode(
providerId: string,
sessionId: string,
code: string,
profile?: ProfileScope
): Promise<OAuthSubmitResponse> {
return window.hermesDesktop.api<OAuthSubmitResponse>({
...capabilityScoped(profile),
path: `/api/providers/oauth/${encodeURIComponent(providerId)}/submit`,
method: 'POST',
body: { session_id: sessionId, code }
})
}
// A long-poll waits this long at most for a change (the backend caps it at 25 s); the request's own
// timeout leaves room for the hold plus a slow answer.
export const OAUTH_LONG_POLL_SECONDS = 25
const OAUTH_LONG_POLL_TIMEOUT_MS = 45_000
/** One sign-in poll. With `waitSeconds` it is a long-poll: the backend answers
* once the session leaves `pending`, or after the wait with `pending`. */
export function pollOAuthSession(
providerId: string,
sessionId: string,
profile?: ProfileScope,
waitSeconds = 0
): Promise<OAuthPollResponse> {
const query = waitSeconds > 0 ? `?wait=${waitSeconds}` : ''
return window.hermesDesktop.api<OAuthPollResponse>({
...capabilityScoped(profile),
path: `/api/providers/oauth/${encodeURIComponent(providerId)}/poll/${encodeURIComponent(sessionId)}${query}`,
...(waitSeconds > 0 ? { timeoutMs: OAUTH_LONG_POLL_TIMEOUT_MS } : {})
})
}
/** The free tier's handoff after a Nous sign-in. A long-poll: given `since`
* (the `updated_at` on screen) the backend answers once the record changes. */
export function getNousHandoffStatus(since: null | string, profile?: ProfileScope): Promise<AppHandoffStatus> {
const query = new URLSearchParams({ wait: String(OAUTH_LONG_POLL_SECONDS), ...(since ? { since } : {}) })
return window.hermesDesktop.api<AppHandoffStatus>({
...capabilityScoped(profile),
path: `/api/providers/oauth/nous/handoff?${query}`,
timeoutMs: OAUTH_LONG_POLL_TIMEOUT_MS
})
}
export function cancelOAuthSession(sessionId: string, profile?: ProfileScope): Promise<{ ok: boolean }> {
return window.hermesDesktop.api<{ ok: boolean }>({
...capabilityScoped(profile),
path: `/api/providers/oauth/sessions/${encodeURIComponent(sessionId)}`,
method: 'DELETE'
})
}