Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { randomUUID } from 'node:crypto'
import fs from 'node:fs'
import path from 'node:path'
import { AuthClient } from './authClient.js'
import { bindChatStoreForUser, unbindChatStore } from './chatStoreBinding.js'
import {
clearDesktopRuntimeConfigSelection,
config,
deleteDesktopRuntimeConfigOption,
getActiveEnvKey,
getActiveLegacyEnvKeys,
getActiveRuntimeConfigOptionId,
getDesktopRuntimeConfigState,
hydrateDesktopRuntimeConfig,
isDesktopRuntimeConfigured,
resolveEnvKey,
saveDesktopRuntimeConfig,
selectDesktopRuntimeConfigOption,
validateRpcProxyBaseUrl,
} from './config.js'
import {
canonicalizeDesktopRestEndpoint,
sameDesktopRestEndpoint,
} from './desktopEnvironmentUrl.js'
import { fetchBoundedBytes, streamBoundedBytes } from './gfs/boundedDownload.js'
import { type DelegationAffordances, delegationAffordances } from './gfs/delegation.js'
import {
DesktopGfsUploadJob,
DesktopUploadCapabilityError,
type DesktopUploadInput,
type DesktopUploadSession,
type DesktopUploadTransport,
formatGfsUploadLimit,
} from './gfs/upload.js'
import { GfsClient, type GfsResourceView, parseSubjectKey } from './gfs/uriHandler.js'
import { ApiError, requestJson, withTimeout } from './httpClient.js'
import { MemberRegistrationServiceClient } from './memberRegistrationServiceClient.js'
import { tryGetPluginSdkRuntime } from './pluginSdkRuntime.js'
import { RpcProxyClient } from './rpcProxyClient.js'
import { RpcTokenManager } from './rpcTokenManager.js'
import {
ContextSharedFilesystemSummary,
SharedFileListResult,
SharedFilesClient,
} from './sharedFilesClient.js'
import { TokenStore } from './tokenStore.js'
import {
AccessCatalog,
AgentWithMcpServers,
ApprovalDecisionResult,
ChatAuthorityScope,
ContextBreakdownResult,
DependencyHealth,
DesktopAppInfo,
DesktopReleaseStatus,
DesktopRuntimeConfig,
DesktopRuntimeConfigHandoffSelection,
EntityChangeStreamEvent,
ExternalChannelsSummary,
HostActivitySnapshot,
HostActivityStreamEvent,
HostMessageRequest,
HostMessageResponse,
HostModelsResult,
HostRuntimeStatus,
HostStatusStreamEvent,
LoginBackendHint,
PasswordLoginResult,
PendingWorkflowApproval,
PrewarmHostResult,
ProfileSettingsOpenOptions,
RpcAllowedServersResult,
RpcConnectorsResult,
RpcScope,
SessionMe,
SessionMessagesQuery,
SessionMessagesResult,
SessionState,
SessionsListQuery,
SessionsListResult,
SetHostModelResult,
TaskProgressStreamEvent,
TeamDirectoryResult,
TeamMember,
TeamSummary,
TokenMetadata,
UserNotificationPreferences,
WorkflowApprovalDecisionResult,
WorkflowNotificationStreamEvent,
WorkflowRecipeListResult,
WorkflowRunArtifactsResult,
} from './types.js'
// The single wake scope. A finite (non-streaming) Host operation carries this
// IN ADDITION to its functional scope so a suspended stateless Host wakes
// bounded-and-once for that operation (issue #791). control-api intersects the
// requested scopes against the caller's grants before issuance, so requesting
// the wake scope never widens a caller who was not granted it.
// Upper bound for a single backend-reachability probe used by
// `diagnoseLoginBackend`. Kept short so a post-login-failure diagnosis never
// makes the failure feel slower than it already did.
const BACKEND_PROBE_TIMEOUT_MS = 1500
const ENTITY_CHANGE_RETRY_AFTER_CAP_MS = 5 * 60 * 1000
// Two maximum server heartbeat intervals plus its maximum poll delay. This
// matches the operator-stream liveness watchdog and bounds half-open sockets.
const ENTITY_CHANGE_STREAM_IDLE_TIMEOUT_MS = 2 * (60_000 + 5_000)
const HOST_WAKE_SCOPE: RpcScope = 'host:wake:write'
const PROFILE_UI_BASE_URL_ORIGIN_ERROR =
'PROFILE_UI_BASE_URL must be an origin URL with a root pathname and no search parameters'
type RuntimeConfigDiscovery = {
profileId: string | null
externalRestApiBaseUrl: string
rpcProxyBaseUrl: string
appName: string
}
function parseEntityChangeRetryAfterMs(
value: string | undefined,
nowMs = Date.now()
): number | undefined {
const retryAfter = value?.trim()
if (!retryAfter) return undefined
const seconds = Number(retryAfter)
const retryAtMs =
Number.isFinite(seconds) && seconds >= 0 ? nowMs + seconds * 1_000 : Date.parse(retryAfter)
if (!Number.isFinite(retryAtMs)) return undefined
return Math.min(ENTITY_CHANGE_RETRY_AFTER_CAP_MS, Math.max(0, retryAtMs - nowMs))
}
function normalizeExplicitProfileUiBaseUrl(rawValue: string): string | null {
const value = rawValue.trim()
if (!value) return null
let url: URL
try {
url = new URL(value)
} catch {
return null
}
if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
return null
}
if (url.pathname !== '/' || url.search) return null
url.hash = ''
return url.toString().replace(/\/$/, '')
}
function requireProfileUiBaseUrlForBrowserAction(): string {
if (!config.desktopProfileUiBaseUrlExplicit) {
return config.desktopProfileUiBaseUrl
}
const explicitBaseUrl = normalizeExplicitProfileUiBaseUrl(config.desktopProfileUiBaseUrl)
if (!explicitBaseUrl) {
throw new Error(PROFILE_UI_BASE_URL_ORIGIN_ERROR)
}
return explicitBaseUrl
}
/**
* Guarded wrapper around `shell.openExternal` for URLs that originate in data
* (server responses, config, deep-links) rather than fixed constants. Electron
* hands a non-web scheme (`file:`, `javascript:`, `data:`, a custom protocol
* such as `clerum://`) straight to the OS protocol handler, so every
* data-derived URL is scheme-checked before it can reach the browser.
*
* `requireHttps` pins OAuth authorize URLs to `https:` — real providers never
* issue a plaintext authorize endpoint. The default also permits `http:` for
* profile-ui links, which legitimately run on `http://localhost` in local dev
* (see `normalizeExplicitProfileUiBaseUrl`, which accepts both schemes).
*
* On rejection only the offending scheme is surfaced — never the full URL,
* whose query string may carry tokens or other secrets.
*/
async function openExternalDataUrl(
rawUrl: string,
options: { requireHttps?: boolean } = {}
): Promise<void> {
const value = String(rawUrl ?? '')
let parsed: URL
try {
parsed = new URL(value)
} catch {
throw new Error('Refusing to open a malformed external URL')
}
const allowedProtocols = options.requireHttps ? ['https:'] : ['https:', 'http:']
if (!allowedProtocols.includes(parsed.protocol)) {
throw new Error(`Refusing to open external URL with unsupported scheme "${parsed.protocol}"`)
}
const { shell } = await import('electron')
await shell.openExternal(value)
}
/**
* Finite-operation scope matrix — the single source of truth for the exact
* scope array each finite (single request/response) Host RPC operation requests,
* keyed by operation family (plan §11.4). EVERY entry carries HOST_WAKE_SCOPE:
* these are the on-demand, user-driven operations that may legitimately wake a
* suspended stateless Host. rpc-proxy still enforces each route's own functional
* `requireScope`; the wake scope here only lets that same operation pull a
* suspended Host back up.
*
* Streams and observability reads are DELIBERATELY absent (see
* HOST_OBSERVABILITY_SCOPES): they keep narrow read scopes with NO wake scope so
* background polling and SSE streams can never defeat scale-to-zero. Adding a
* family here is the ONLY place the wake grant is requested — never append
* HOST_WAKE_SCOPE at a call site.
* - `model`: writing the per-session selection (POST /model) is gated by the
* dedicated write scope (the swap's blast radius is the caller's own
* session); wake is added so selecting a model on a suspended Host brings it
* up. Reading the model list (GET /models) rides the `session` family.
* - `approval`: the tool-call surface only (approveToolCall/denyToolCall).
* `decideWorkflowApproval` (`host:workflow-approval:decide`) is a separate
* surface and is intentionally NOT in this matrix.
*/
const HOST_FINITE_OPERATION_SCOPES: Record<
'message' | 'session' | 'model' | 'artifact' | 'approval',
RpcScope[]
> = {
message: ['host:message:invoke', 'host:task:read', HOST_WAKE_SCOPE],
session: ['host:session:read', HOST_WAKE_SCOPE],
model: ['host:model:write', HOST_WAKE_SCOPE],
artifact: ['host:activity:read', 'host:task:read', HOST_WAKE_SCOPE],
approval: ['host:approval:write', HOST_WAKE_SCOPE],
}
/**
* Observability scope matrix — status/activity reads plus every SSE stream.
* DELIBERATELY never contains HOST_WAKE_SCOPE: a suspended stateless Host must
* stay suspended under polling/streaming, or observability would defeat
* scale-to-zero. The negative scope tests assert no entry here carries wake.
*/
const HOST_OBSERVABILITY_SCOPES: Record<'status' | 'activity', RpcScope[]> = {
status: ['host:status:read'],
activity: ['host:activity:read'],
}
// Named views onto the matrices so existing call sites stay byte-identical.
const HOST_WAKEABLE_OPERATION_SCOPES: RpcScope[] = HOST_FINITE_OPERATION_SCOPES.message
const HOST_STATUS_SCOPES: RpcScope[] = HOST_OBSERVABILITY_SCOPES.status
const HOST_ACTIVITY_SCOPES: RpcScope[] = HOST_OBSERVABILITY_SCOPES.activity
const HOST_SESSION_SCOPES: RpcScope[] = HOST_FINITE_OPERATION_SCOPES.session
const HOST_MODEL_SCOPES: RpcScope[] = HOST_FINITE_OPERATION_SCOPES.model
// Spec 15 Fase B — explicit user rename. A dedicated WRITE scope, distinct from
// `host:session:read` (so a read/navigation token can never rename), and
// DELIBERATELY NOT wake-eligible: it carries no HOST_WAKE_SCOPE. Rename is
// optimistic local-first and reconciles on the next listSessions poll, and
// rpc-proxy's PATCH route is non-wake too — granting wake here would turn a
// rename into a cheap "wake my pod" primitive. Kept OUT of
// HOST_FINITE_OPERATION_SCOPES (whose every entry carries wake, asserted by
// appService.wakeScopeMatrix.issue791.test.ts) for exactly that reason.
const HOST_SESSION_TITLE_SCOPES: RpcScope[] = ['host:session:write']
const HOST_ARTIFACT_SCOPES: RpcScope[] = HOST_FINITE_OPERATION_SCOPES.artifact
const HOST_APPROVAL_SCOPES: RpcScope[] = HOST_FINITE_OPERATION_SCOPES.approval
const MCP_SERVERS_LIST_SCOPES: RpcScope[] = ['mcp:servers:list']
// U5 (mcp-oauth reactive consent): "Connect <server>" reuses the SAME capability
// the desktop already holds to invoke mcp tools — connecting is a precondition of
// invoking, so rpc-proxy gates the authorize-url route on this scope (no new
// scope is minted). The token is host-bound to the suspended conversation's
// hostRef, which the user demonstrably has access to.
const MCP_SERVER_INVOKE_SCOPES: RpcScope[] = ['mcp:server:invoke']
const DESKTOP_VIEW_SCOPES: RpcScope[] = ['desktop:view']
const SANDBOX_UI_VIEW_SCOPES: RpcScope[] = ['sandbox:ui:view']
// hostRefs is required by control-api's RPC token issuance (see
// `issueRpcAccessToken` — it returns null for empty hostRefs). The
// `sandbox:ui:view` scope is recipe-bound, not host-bound, so we pass a
// sentinel that doesn't collide with any real host. rpc-proxy's view/*
// path doesn't read hostRefs; the cookie + path pair is the per-recipe gate.
const SANDBOX_UI_HOST_REF_SENTINEL = 'sandbox-ui'
// Pre-warm cooldown: client-side hygiene so catalog refreshes or rapid app
// reloads don't spam the wake route (control-api rate-limits anyway). Attempts —
// including failed ones — are recorded up front so a failing wake is never
// silently retried by the next catalog refresh inside the window.
const PREWARM_COOLDOWN_MS = 60_000
// Bounded map: evict the oldest attempt entry past this many distinct hosts.
const PREWARM_COOLDOWN_MAX_HOSTS = 256
// Bounded wake re-emission: HCC's raw watch is known to lose events, and a
// single projected wake annotation then goes unseen until the ~300s resync.
// The reactive message path compensates by re-triggering every 15s while
// holding (rpc-proxy wakeAndHold); prewarm mirrors that backstop with a
// BOUNDED loop tied to one catalog-driven invocation: while the wake route
// answers 202 wake-requested (HCC has not acted — the CR is still suspended),
// re-POST up to this many more times at this interval. The interval exceeds
// control-api's 2s coalesce window, so each re-POST bumps the Postgres
// generation and re-projects a fresh watch event. 200 active is the
// acknowledgment that HCC acted — stop immediately, as on any other status
// or error. Never a persistent loop, never coupled to the status stream.
const PREWARM_REEMIT_MAX_ATTEMPTS = 2
const PREWARM_REEMIT_INTERVAL_MS = 10_000
function compareSemverLike(left: string, right: string): number {
const parse = (value: string) =>
value
.split(/[.-]/)
.slice(0, 3)
.map(part => Number.parseInt(part.replace(/\D.*/, ''), 10))
.map(part => (Number.isFinite(part) ? part : 0))
const a = parse(left)
const b = parse(right)
for (let index = 0; index < 3; index += 1) {
const delta = (a[index] ?? 0) - (b[index] ?? 0)
if (delta !== 0) return delta > 0 ? 1 : -1
}
return 0
}
function normalizeVersion(value: unknown): string | null {
const version = String(value || '').trim()
return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version) ? version : null
}
function readDesktopPackageVersion(): string | null {
const envVersion = normalizeVersion(process.env.npm_package_version)
if (envVersion) return envVersion
const candidates = [
path.join(__dirname, '..', 'package.json'),
path.join(process.cwd(), 'package.json'),
]
for (const candidate of candidates) {
try {
const packageJson = JSON.parse(fs.readFileSync(candidate, 'utf8')) as { version?: unknown }
const packageVersion = normalizeVersion(packageJson.version)
if (packageVersion) return packageVersion
} catch {
// Keep the release check best-effort in dev mode.
}
}
return null
}
function resolveDesktopAppVersion(desktopApp: { isPackaged: boolean; getVersion: () => string }) {
return desktopApp.isPackaged
? desktopApp.getVersion()
: readDesktopPackageVersion() || desktopApp.getVersion()
}
/** Known progress event types forwarded from host SSE to desktop consumers. */
const KNOWN_PROGRESS_EVENTS = new Set([
'tool_start',
'tool_complete',
'tool_progress',
'llm_in_progress',
'suspended',
// Keepalive surfaced by the SSE parser — forwarded so the renderer's task
// watchdog resets on it (the tracker bumps lastEventAt on every event).
'heartbeat',
])
// stream-recovery (A): bounded reconnect of a dropped progress stream before
// surfacing an error. Total worst-case (~3 attempts + backoff + per-attempt
// timeout) stays under the renderer's 30s watchdog so B backstops either way.
const MAX_RECONNECT_ATTEMPTS = 3
const RECONNECT_BASE_DELAY_MS = 500
const RECONNECT_MAX_DELAY_MS = 2000
// F3: the 8s bound guards CONNECTION ESTABLISHMENT only — the window between
// opening the HTTP request and receiving the first server bytes. mcp-host emits
// `waiting` immediately on flushing the SSE headers (`routes.ts` handleProgress
// StreamRoute), so a `waiting` proves the connection is established and clears
// this timer.
const RECONNECT_ATTEMPT_TIMEOUT_MS = 8000
// F3: after `waiting`, mcp-host blocks in `progressReporterRegistry.waitFor(taskId,
// 180_000)` (main.ts) before it can send `open` — and sends NO keepalive until
// after `open` (routes.ts:1043). So the legitimate pre-`open` wait can be up to
// 180s; the 8s establishment bound must NOT police it (that synthesized a false
// stream-loss terminal while the task was alive → false reconcile → P1/P2). This
// longer bound matches the server's reporter-wait budget plus margin: the server
// itself ends the stream with `task_not_found_or_expired` at 180s if no reporter
// appears, so this is a backstop for a connection that received `waiting` but
// then went silent without the server's own error. A genuinely dead/hung
// post-`waiting` connection is still caught here (and by the renderer's 30s
// watchdog).
const RECONNECT_WAITING_FOR_OPEN_TIMEOUT_MS = 195_000
const SAVED_SESSION_RESTORE_RETRY_DELAY_MS = 5_000
const gfsUploadTransport: DesktopUploadTransport = {
requestJson,
requestPart: async (url, token, headers, body, timeoutMs, signal) => {
const response = await fetch(url, {
method: 'PUT',
headers: { authorization: `Bearer ${token}`, ...headers },
body: body as unknown as BodyInit,
// Node's fetch requires this opt-in for a streaming request body.
duplex: 'half',
signal: withTimeout(signal, timeoutMs),
} as RequestInit & { duplex: 'half' })
const text = await response.text()
return {
status: response.status,
text,
retryAfter: response.headers.get('retry-after') ?? undefined,
}
},
}
const LEGACY_GFS_MAX_FILE_BYTES = 16 * 1024 * 1024
const LEGACY_GFS_READ_BUFFER_BYTES = 1024 * 1024
async function readBoundedLegacyFile(handle: fs.promises.FileHandle): Promise<Buffer> {
const chunks: Buffer[] = []
let totalBytes = 0
for (;;) {
const remaining = LEGACY_GFS_MAX_FILE_BYTES + 1 - totalBytes
const chunk = Buffer.allocUnsafe(Math.min(LEGACY_GFS_READ_BUFFER_BYTES, remaining))
const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, null)
if (bytesRead === 0) break
totalBytes += bytesRead
if (totalBytes > LEGACY_GFS_MAX_FILE_BYTES) {
throw new Error(
`This writer does not advertise resumable uploads; legacy GFS is limited to ${formatGfsUploadLimit(LEGACY_GFS_MAX_FILE_BYTES)}.`
)
}
chunks.push(chunk.subarray(0, bytesRead))
}
return Buffer.concat(chunks, totalBytes)
}
export async function legacyEncodedFile(filePath: string): Promise<string> {
const noFollow = typeof fs.constants.O_NOFOLLOW === 'number' ? fs.constants.O_NOFOLLOW : 0
let handle: fs.promises.FileHandle
try {
handle = await fs.promises.open(filePath, fs.constants.O_RDONLY | noFollow)
} catch (error) {
if ((error as NodeJS.ErrnoException)?.code === 'ELOOP') {
throw new Error('selected upload path must not be a symbolic link')
}
throw error
}
try {
const info = await handle.stat()
if (!info.isFile()) throw new Error('selected upload path is not a regular file')
if (info.size > LEGACY_GFS_MAX_FILE_BYTES) {
throw new Error(
`This writer does not advertise resumable uploads; legacy GFS is limited to ${formatGfsUploadLimit(LEGACY_GFS_MAX_FILE_BYTES)}.`
)
}
// O_NOFOLLOW is not available on every Electron target. The post-open
// lstat/object-identity check is the portable equivalent: a symlink is
// rejected and a pathname swap cannot make the already-open descriptor
// point at different bytes.
const pathInfo = await fs.promises.lstat(filePath)
if (pathInfo.isSymbolicLink())
throw new Error('selected upload path must not be a symbolic link')
if (
typeof info.dev === 'number' &&
typeof info.ino === 'number' &&
typeof pathInfo.dev === 'number' &&
typeof pathInfo.ino === 'number' &&
(info.dev !== pathInfo.dev || info.ino !== pathInfo.ino)
) {
throw new Error('selected upload path changed while it was being opened')
}
const bytes = await readBoundedLegacyFile(handle)
const finalInfo = await handle.stat()
if (
finalInfo.size !== info.size ||
finalInfo.mtimeMs !== info.mtimeMs ||
finalInfo.ctimeMs !== info.ctimeMs ||
bytes.byteLength !== info.size
) {
throw new Error('selected upload file changed while it was being read')
}
return bytes.toString('base64')
} finally {
await handle.close()
}
}
function legacyReceipt(
resource: GfsResourceView,
operation: 'create' | 'replace'
): DesktopUploadSession {
return {
uploadId: resource.resourceId,
drive: resource.drive,
operation,
expectedBytes: resource.bytes,
partBytes: resource.bytes || 1,
partCount: resource.bytes === 0 ? 0 : 1,
state: 'completed',
contiguousBytes: resource.bytes,
committedBytes: resource.bytes,
committedPartCount: resource.bytes === 0 ? 0 : 1,
activePartCount: 0,
expiresAt: new Date(Date.now()).toISOString(),
resultResourceId: resource.resourceId,
resultVersion: resource.version,
}
}
const DESKTOP_GFS_UPLOAD_STATE_VERSION = 2 as const
type DesktopGfsUploadPersistenceStatus = 'active' | 'paused' | 'failed' | 'suspended_auth'
interface DesktopGfsUploadScope {
ownerId: string
teamId: string | null
environmentKey: string
baseUrl: string
drive: string
authEpoch: number
}
type DesktopGfsUploadIdentity = Omit<DesktopGfsUploadScope, 'drive' | 'authEpoch'>
interface PersistedDesktopGfsUpload {
version: typeof DESKTOP_GFS_UPLOAD_STATE_VERSION
uploadId: string
filePath: string
fileName: string
fileSize: number
target: {
operation: 'create' | 'replace'
parentRid?: string
resourceRid?: string
ifMatch?: number
}
name: string
session: DesktopUploadSession
scope: DesktopGfsUploadScope
status: DesktopGfsUploadPersistenceStatus
updatedAt: string
}
interface LegacyPersistedDesktopGfsUpload {
uploadId: string
filePath: string
fileName: string
fileSize: number
target: PersistedDesktopGfsUpload['target']
name: string
session: DesktopUploadSession
}
interface QuarantinedDesktopGfsUpload {
uploadId: string
reason: 'legacy_unscoped' | 'invalid_scope' | 'unsupported_version'
quarantinedAt: string
}
interface DesktopGfsUploadStateFile {
version: typeof DESKTOP_GFS_UPLOAD_STATE_VERSION
records: PersistedDesktopGfsUpload[]
quarantined: QuarantinedDesktopGfsUpload[]
}
interface DesktopGfsUploadSummary {
uploadId: string
fileName: string
fileSize: number
target: PersistedDesktopGfsUpload['target']
name: string
drive: string
status: DesktopGfsUploadPersistenceStatus
}
const DESKTOP_GFS_UPLOAD_STATE_FILE = 'gfs-upload-sessions.json'
function normalizeDesktopUploadBaseUrl(value: string): string {
const url = new URL(String(value || '').trim())
if (url.protocol !== 'http:' && url.protocol !== 'https:') {
throw new Error('GFS upload base URL must use http(s)')
}
url.hash = ''
return url.toString().replace(/\/+$/, '')
}
function desktopGfsUploadIdentity(me: SessionMe): DesktopGfsUploadIdentity {
return {
ownerId: me.id,
teamId: me.teamId ? String(me.teamId).trim() : null,
environmentKey: getActiveEnvKey(),
baseUrl: normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl),
}
}
function normalizeDesktopUploadDrive(value: string | undefined): string {
const drive = String(value ?? 'main').trim()
if (!drive) throw new Error('drive_required: GFS uploads require a canonical drive')
return drive
}
function isNonNegativeSafeInteger(value: unknown): value is number {
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
}
function isDesktopGfsUploadTarget(value: unknown): value is PersistedDesktopGfsUpload['target'] {
if (!value || typeof value !== 'object') return false
const target = value as Partial<PersistedDesktopGfsUpload['target']>
if (target.operation !== 'create' && target.operation !== 'replace') return false
if (
target.parentRid !== undefined &&
(typeof target.parentRid !== 'string' || !target.parentRid.trim())
)
return false
if (
target.resourceRid !== undefined &&
(typeof target.resourceRid !== 'string' || !target.resourceRid.trim())
)
return false
if (target.ifMatch !== undefined && !isNonNegativeSafeInteger(target.ifMatch)) return false
return target.operation === 'create' ? Boolean(target.parentRid) : Boolean(target.resourceRid)
}
function isDesktopUploadSession(value: unknown): value is DesktopUploadSession {
if (!value || typeof value !== 'object') return false
const session = value as Partial<DesktopUploadSession>
return (
typeof session.uploadId === 'string' &&
Boolean(session.uploadId.trim()) &&
typeof session.drive === 'string' &&
session.drive === session.drive.trim() &&
Boolean(session.drive) &&
(session.operation === 'create' || session.operation === 'replace') &&
isNonNegativeSafeInteger(session.expectedBytes) &&
isNonNegativeSafeInteger(session.partBytes) &&
session.partBytes > 0 &&
isNonNegativeSafeInteger(session.partCount) &&
typeof session.state === 'string' &&
Boolean(session.state) &&
isNonNegativeSafeInteger(session.contiguousBytes) &&
isNonNegativeSafeInteger(session.committedBytes) &&
isNonNegativeSafeInteger(session.committedPartCount) &&
isNonNegativeSafeInteger(session.activePartCount) &&
typeof session.expiresAt === 'string' &&
Boolean(session.expiresAt) &&
(session.resultResourceId === undefined || typeof session.resultResourceId === 'string') &&
(session.resultVersion === undefined || isNonNegativeSafeInteger(session.resultVersion)) &&
(session.resultSha256 === undefined || typeof session.resultSha256 === 'string')
)
}
function canonicalDesktopUploadSession(session: DesktopUploadSession): DesktopUploadSession {
return {
uploadId: session.uploadId,
drive: session.drive,
operation: session.operation,
expectedBytes: session.expectedBytes,
partBytes: session.partBytes,
partCount: session.partCount,
state: session.state,
contiguousBytes: session.contiguousBytes,
committedBytes: session.committedBytes,
committedPartCount: session.committedPartCount,
activePartCount: session.activePartCount,
expiresAt: session.expiresAt,
...(session.resultResourceId === undefined
? {}
: { resultResourceId: session.resultResourceId }),
...(session.resultVersion === undefined ? {} : { resultVersion: session.resultVersion }),
...(session.resultSha256 === undefined ? {} : { resultSha256: session.resultSha256 }),
}
}
function isLegacyPersistedDesktopGfsUpload(
value: unknown
): value is LegacyPersistedDesktopGfsUpload {
if (!value || typeof value !== 'object') return false
const item = value as Partial<LegacyPersistedDesktopGfsUpload>
return (
typeof item.uploadId === 'string' &&
typeof item.filePath === 'string' &&
typeof item.fileName === 'string' &&
isNonNegativeSafeInteger(item.fileSize) &&
typeof item.name === 'string' &&
isDesktopGfsUploadTarget(item.target) &&
isDesktopUploadSession(item.session)
)
}
function isDesktopGfsUploadScope(value: unknown): value is DesktopGfsUploadScope {
if (!value || typeof value !== 'object') return false
const scope = value as Partial<DesktopGfsUploadScope>
if (
typeof scope.ownerId !== 'string' ||
scope.ownerId !== scope.ownerId.trim() ||
!scope.ownerId ||
(scope.teamId !== null &&
(typeof scope.teamId !== 'string' ||
scope.teamId !== scope.teamId.trim() ||
!scope.teamId)) ||
typeof scope.environmentKey !== 'string' ||
scope.environmentKey !== scope.environmentKey.trim() ||
!scope.environmentKey ||
typeof scope.baseUrl !== 'string' ||
typeof scope.drive !== 'string' ||
scope.drive !== scope.drive.trim() ||
!scope.drive ||
!Number.isSafeInteger(scope.authEpoch) ||
Number(scope.authEpoch) < 0
) {
return false
}
try {
return normalizeDesktopUploadBaseUrl(scope.baseUrl) === scope.baseUrl
} catch {
return false
}
}
function isPersistedDesktopGfsUpload(value: unknown): value is PersistedDesktopGfsUpload {
if (!isLegacyPersistedDesktopGfsUpload(value)) return false
const item = value as Partial<PersistedDesktopGfsUpload>
return (
item.version === DESKTOP_GFS_UPLOAD_STATE_VERSION &&
isDesktopGfsUploadScope(item.scope) &&
item.uploadId === item.session?.uploadId &&
item.fileSize === item.session?.expectedBytes &&
item.target?.operation === item.session?.operation &&
item.session?.drive === item.scope.drive &&
['active', 'paused', 'failed', 'suspended_auth'].includes(String(item.status)) &&
typeof item.updatedAt === 'string'
)
}
function canonicalPersistedDesktopGfsUpload(
record: PersistedDesktopGfsUpload
): PersistedDesktopGfsUpload {
return {
version: DESKTOP_GFS_UPLOAD_STATE_VERSION,
uploadId: record.uploadId,
filePath: record.filePath,
fileName: record.fileName,
fileSize: record.fileSize,
target: {
operation: record.target.operation,
...(record.target.parentRid === undefined ? {} : { parentRid: record.target.parentRid }),
...(record.target.resourceRid === undefined
? {}
: { resourceRid: record.target.resourceRid }),
...(record.target.ifMatch === undefined ? {} : { ifMatch: record.target.ifMatch }),
},
name: record.name,
session: canonicalDesktopUploadSession(record.session),
scope: {
ownerId: record.scope.ownerId,
teamId: record.scope.teamId,
environmentKey: record.scope.environmentKey,
baseUrl: record.scope.baseUrl,
drive: record.scope.drive,
authEpoch: record.scope.authEpoch,
},
status: record.status,
updatedAt: record.updatedAt,
}
}
function canonicalQuarantinedDesktopGfsUpload(value: unknown): QuarantinedDesktopGfsUpload | null {
if (!value || typeof value !== 'object') return null
const record = value as Partial<QuarantinedDesktopGfsUpload>
if (
typeof record.uploadId !== 'string' ||
!record.uploadId ||
!['legacy_unscoped', 'invalid_scope', 'unsupported_version'].includes(String(record.reason)) ||
typeof record.quarantinedAt !== 'string' ||
!record.quarantinedAt
)
return null
return {
uploadId: record.uploadId,
reason: record.reason as QuarantinedDesktopGfsUpload['reason'],
quarantinedAt: record.quarantinedAt,
}
}
function serializedStateValueChanged(raw: unknown, canonical: unknown): boolean {
try {
return JSON.stringify(raw) !== JSON.stringify(canonical)
} catch {
return true
}
}
function sameDesktopGfsUploadScope(
left: DesktopGfsUploadScope,
right: DesktopGfsUploadScope,
options: { includeAuthEpoch?: boolean } = {}
): boolean {
return (
left.ownerId === right.ownerId &&
left.teamId === right.teamId &&
left.environmentKey === right.environmentKey &&
left.baseUrl === right.baseUrl &&
left.drive === right.drive &&
(options.includeAuthEpoch === false || left.authEpoch === right.authEpoch)
)
}
export function migrateDesktopGfsUploadState(value: unknown): {
state: DesktopGfsUploadStateFile
migrated: boolean
} {
const now = new Date().toISOString()
if (Array.isArray(value)) {
const quarantined = value
.filter(isLegacyPersistedDesktopGfsUpload)
.slice(-100)
.map(record => ({
uploadId: record.uploadId,
reason: 'legacy_unscoped' as const,
quarantinedAt: now,
}))
return {
state: { version: DESKTOP_GFS_UPLOAD_STATE_VERSION, records: [], quarantined },
migrated: true,
}
}
if (!value || typeof value !== 'object') {
return {
state: { version: DESKTOP_GFS_UPLOAD_STATE_VERSION, records: [], quarantined: [] },
migrated: value !== undefined && value !== null,
}
}
const candidate = value as {
version?: unknown
records?: unknown
quarantined?: unknown
}
if (candidate.version !== DESKTOP_GFS_UPLOAD_STATE_VERSION) {
return {
state: {
version: DESKTOP_GFS_UPLOAD_STATE_VERSION,
records: [],
quarantined: [
{
uploadId: 'unknown',
reason: 'unsupported_version',
quarantinedAt: now,
},
],
},
migrated: true,
}
}
const rawRecords = Array.isArray(candidate.records) ? candidate.records : []
const records = rawRecords
.filter(isPersistedDesktopGfsUpload)
.map(canonicalPersistedDesktopGfsUpload)
.slice(-100)
const invalid = rawRecords
.filter(record => !isPersistedDesktopGfsUpload(record))
.slice(-100)
.map(record => ({
uploadId:
record &&
typeof record === 'object' &&
typeof (record as { uploadId?: unknown }).uploadId === 'string'
? String((record as { uploadId: string }).uploadId)
: 'unknown',
reason: 'invalid_scope' as const,
quarantinedAt: now,
}))
const rawQuarantined = Array.isArray(candidate.quarantined) ? candidate.quarantined : []
const quarantined = rawQuarantined
.map(canonicalQuarantinedDesktopGfsUpload)
.filter((record): record is QuarantinedDesktopGfsUpload => record !== null)
.slice(-100)
const recordsChanged =
records.length !== rawRecords.length ||
records.some((record, index) => serializedStateValueChanged(rawRecords[index], record))
const quarantineChanged =
!Array.isArray(candidate.quarantined) ||
quarantined.length !== rawQuarantined.length ||
quarantined.some((record, index) => serializedStateValueChanged(rawQuarantined[index], record))
return {
state: {
version: DESKTOP_GFS_UPLOAD_STATE_VERSION,
records,
quarantined: [...quarantined, ...invalid].slice(-100),
},
migrated: recordsChanged || quarantineChanged,
}
}
export interface AppServiceOptions {
tokenStore?: TokenStore
}
export class AppService {
private readonly authClient = new AuthClient()
private readonly memberRegistrationServiceClient = new MemberRegistrationServiceClient()
private readonly rpcClient = new RpcProxyClient(() => this.getEffectiveRpcProxyBaseUrl())
private readonly sharedFilesClient = new SharedFilesClient()
private readonly gfsClient = new GfsClient({
get baseUrl() {
return config.externalRestApiBaseUrl
},
requestJson,
fetchBytes: (url, token, opts) => fetchBoundedBytes(url, token, opts),
fetchByteStream: (url, token, opts, onChunk) => streamBoundedBytes(url, token, opts, onChunk),
})
private readonly tokenStore: TokenStore
private readonly rpcTokenManager = new RpcTokenManager(this.authClient)
private sessionToken: string | null = null
private me: SessionMe | null = null
private profileUiBaseUrlCache: { key: string; value: string } | null = null
private accessCatalog: AccessCatalog | null = null
private teamDirectoryCache: TeamDirectoryResult | null = null
private teamContextQueue: Promise<void> = Promise.resolve()
private restoreSavedSessionInFlight: Promise<SessionState> | null = null
private restoreSavedSessionReservationStarted = false
private runtimeConfigResolutionInFlight = new Map<string, { promise: Promise<void> }>()
private effectiveRuntimeRpcEndpoint: RuntimeConfigDiscovery | null = null
private pendingRuntimeConfigDiscovery: RuntimeConfigDiscovery | null = null
private savedSessionRestoreAttemptedEnvKey: string | null = null
private savedSessionRestoreAttemptedAtMs = 0
private interactiveLoginAttempts = 0
private nativeAuthEnvironmentCommitQueue: Promise<void> = Promise.resolve()
private gfsAuthEpoch = 0
private gfsDispatchBlocked = true
// A transient runWithTeamContext hop temporarily installs another team's
// token in sessionToken. Existing GFS jobs keep their captured token and
// scope, but new GFS operations must not capture that temporary token.
private gfsTransientTeamHopDepth = 0
// While a `runWithTeamContext` hop that will restore the original team is in
// flight, `me.teamId` holds the borrowed team. The chat store (and the delete
// fence derived from it) stays on the original team: rebinding it for the hop
// and back would expose the deliberate team's chats to the borrowed scope for
// the length of an RPC.
private chatStoreHomeTeamId: string | null = null
// A finite RPC may temporarily borrow another team session. Keep the
// deliberate user-owned GFS scope stable across that hop so in-flight jobs
// are not invalidated by the transient `me` value.
private gfsScopeIdentity: DesktopGfsUploadIdentity | null = null
private gfsUploadStateQueue: Promise<void> = Promise.resolve()
private readonly gfsUploadJobs = new Map<
string,
{
job: DesktopGfsUploadJob
promise: Promise<DesktopUploadSession>
scope: DesktopGfsUploadScope
}
>()
private readonly gfsPendingUploadJobs = new Set<{
job: DesktopGfsUploadJob
promise: Promise<DesktopUploadSession>
scope: DesktopGfsUploadScope
}>()
private readonly gfsPendingLegacyUploads = new Set<{
controller: AbortController
promise: Promise<unknown>
}>()
private sessionGeneration = 0
private sandboxUiLifecycleQueue: Promise<void> = Promise.resolve()
private workflowApprovalTeamById = new Map<string, string>()
private workflowTeamByKey = new Map<string, string>()
private readonly prewarmAttemptAtByHostRef = new Map<string, number>()
private readonly prewarmReemitLoopHostRefs = new Set<string>()
private readonly prewarmReemitAbortControllers = new Map<string, AbortController>()
private prewarmAuthEpoch = 0
private prewarmAuthTransitionCount = 0
private hostStatusStreams = new Map<
string,
{
ownerId: number
stop: (opts?: { silent?: boolean }) => void
}
>()
private hostActivityStreams = new Map<
string,
{
ownerId: number
stop: (opts?: { silent?: boolean }) => void
}
>()
private notificationStreams = new Map<
string,
{
ownerId: number
state: 'connecting' | 'open' | 'error'
approvalRequested: number
snapshot: number
updated: number
completed: number
stop: (opts?: { silent?: boolean }) => void
}
>()
private readonly entityChangeSubscribers = new Map<
string,
{ ownerId: number; onEvent: (event: EntityChangeStreamEvent) => void }
>()
private entityChangeConnectionStop: ((opts?: { silent?: boolean }) => void) | null = null
private entityChangeSessionToken: string | null = null
private entityChangeSessionGeneration = 0
private entityChangeEnvironmentSwitching = false
private entityChangeSessionExpiryDeferred = false
private entityChangeCursor: string | null = null
private progressStreams = new Map<
string,
{ ownerId: number; stop: (opts?: { silent?: boolean }) => void }
>()
constructor(options: AppServiceOptions = {}) {
this.tokenStore = options.tokenStore ?? new TokenStore()
}
private static dedupe(values: string[]): string[] {
return Array.from(new Set(values.map(value => String(value || '').trim()).filter(Boolean)))
}
private static shouldRefreshRpcToken(error: unknown): boolean {
if (!(error instanceof ApiError)) return false
if (error.status === 401) return true
if (error.status !== 403) return false
const body = String(error.bodyText || '').toLowerCase()
const message = String(error.message || '').toLowerCase()
return body.includes('missing scope') || message.includes('missing scope')
}
private static isForbiddenSharedFilesListError(error: unknown): boolean {
if (!(error instanceof ApiError)) return false
if (error.status === 403) return true
if (error.status !== 500) return false
const details = `${error.message || ''} ${error.bodyText || ''}`.toLowerCase()
return (
details.includes('shared-filesystems') &&
details.includes('(403)') &&
details.includes('forbidden')
)
}
private static isRejectedStoredSessionError(error: unknown): boolean {
return (
error instanceof ApiError &&
(error.status === 401 || error.status === 403 || error.status === 410)
)
}
/**
* Maps rpc-proxy's structured host-availability 503s ({code:'host_waking'}
* from the wake-and-hold subsystem, {code:'host_draining'} from the mcp-host
* DRAINING fence) to a stable Error. Electron IPC serializes errors down to
* their message string, so the renderer keys its "waking" presentation off
* the code token carried in this message.
*/
private static toHostAvailabilityError(hostRef: string, error: unknown): Error | null {
if (!(error instanceof ApiError) || error.status !== 503) return null
const body = String(error.bodyText || '')
if (body.includes('"host_waking"')) {
return new Error(`host_waking: agent host "${hostRef}" is waking up — retry shortly`)
}
if (body.includes('"host_draining"')) {
return new Error(`host_draining: agent host "${hostRef}" is draining — retry shortly`)
}
return null
}
private rememberWorkflowApprovalTeam(approval: PendingWorkflowApproval): void {
const teamId = String(approval.target?.teamId || '').trim()
if (!approval.id || !teamId) return
this.workflowApprovalTeamById.set(approval.id, teamId)
}
private rememberWorkflowApprovalTeams(approvals: PendingWorkflowApproval[]): void {
for (const approval of approvals) {
this.rememberWorkflowApprovalTeam(approval)
}
}
private workflowKey(ns: string, name: string): string {
return `${String(ns || '').trim()}/${String(name || '').trim()}`
}
private updateCachedCurrentTeam(teamId: string | null | undefined): void {
if (!this.teamDirectoryCache) return
this.teamDirectoryCache = {
...this.teamDirectoryCache,
currentTeamId: String(teamId || ''),
}
}
/** The team the chat store and the delete fence are scoped to (see chatStoreHomeTeamId). */
private chatStoreTeamId(): string | null {
if (this.chatStoreHomeTeamId !== null) return this.chatStoreHomeTeamId
return this.me?.teamId ?? null
}
private async bindCurrentChatStore(userId: string): Promise<void> {
await bindChatStoreForUser(userId, getActiveEnvKey(), {
legacyEnvKeys: getActiveLegacyEnvKeys(),
teamId: this.me?.id === userId ? this.chatStoreTeamId() : null,
})
}
/**
* Serialize native operations that publish runtime configuration, session,
* token-store, or GFS authorization state. The queue recovers after either
* success or failure so one rejected transition cannot strand later work.
*/
private withNativeAuthEnvironmentCommit<T>(operation: () => Promise<T>): Promise<T> {
const result = this.nativeAuthEnvironmentCommitQueue.then(operation, operation)
this.nativeAuthEnvironmentCommitQueue = result.then(
() => undefined,
() => undefined
)
return result
}
private captureAuthEnvironmentBinding(): {
environmentKey: string
profileId: string | null
restBaseUrl: string
} {
return {
environmentKey: getActiveEnvKey(),
profileId: getActiveRuntimeConfigOptionId(),
restBaseUrl: canonicalizeDesktopRestEndpoint(config.externalRestApiBaseUrl),
}
}
private assertAuthEnvironmentBinding(binding: {
environmentKey: string
profileId: string | null
restBaseUrl: string
}): void {
const current = this.captureAuthEnvironmentBinding()
if (
current.profileId !== binding.profileId ||
!sameDesktopRestEndpoint(current.restBaseUrl, binding.restBaseUrl)
) {
throw new Error('stale_runtime_environment')
}
}
private runtimeConfigDiscoveryMatchesCurrentBinding(discovery: RuntimeConfigDiscovery): boolean {
const currentBinding = this.captureAuthEnvironmentBinding()
return (
currentBinding.profileId === discovery.profileId &&
sameDesktopRestEndpoint(currentBinding.restBaseUrl, discovery.externalRestApiBaseUrl)
)
}
private getEffectiveRpcProxyBaseUrl(): string {
const effectiveEndpoint = this.effectiveRuntimeRpcEndpoint
if (effectiveEndpoint && this.runtimeConfigDiscoveryMatchesCurrentBinding(effectiveEndpoint)) {
return effectiveEndpoint.rpcProxyBaseUrl
}
return config.rpcProxyBaseUrl
}
/** Caller must hold the native auth/environment commit owner. */
private setEffectiveRuntimeRpcEndpoint(discovery: RuntimeConfigDiscovery): void {
const previousEndpoint = this.getEffectiveRpcProxyBaseUrl()
this.effectiveRuntimeRpcEndpoint = discovery
if (previousEndpoint !== discovery.rpcProxyBaseUrl) this.rpcTokenManager.clear()
}
/** Caller must hold the native auth/environment commit owner. */
private clearEffectiveRuntimeRpcEndpoint(): void {
const effectiveEndpoint = this.effectiveRuntimeRpcEndpoint
if (!effectiveEndpoint) return
this.effectiveRuntimeRpcEndpoint = null
if (effectiveEndpoint.rpcProxyBaseUrl !== config.rpcProxyBaseUrl) this.rpcTokenManager.clear()
}
/** Caller must hold the native auth/environment commit owner. */
private discardRuntimeConfigDiscoveryOutsideCurrentBinding(): void {
if (
this.pendingRuntimeConfigDiscovery &&
!this.runtimeConfigDiscoveryMatchesCurrentBinding(this.pendingRuntimeConfigDiscovery)
) {
this.pendingRuntimeConfigDiscovery = null
}
if (
this.effectiveRuntimeRpcEndpoint &&
!this.runtimeConfigDiscoveryMatchesCurrentBinding(this.effectiveRuntimeRpcEndpoint)
) {
this.clearEffectiveRuntimeRpcEndpoint()
}
if (config.rpcProxyBaseUrl?.trim()) {
this.pendingRuntimeConfigDiscovery = null
this.clearEffectiveRuntimeRpcEndpoint()
}
}
getChatDeletionFenceAuthority(): {
authorityScope: ChatAuthorityScope
sessionGeneration: number
} {
this.requireSessionToken()
if (!this.me) throw new Error('Not authenticated')
return {
authorityScope: {
environmentKey: getActiveEnvKey(),
userId: this.me.id,
teamId: String(this.chatStoreTeamId() || '').trim() || null,
},
sessionGeneration: this.sessionGeneration,
}
}
private async commitSessionToken(
token: string,
options: { advanceSessionGeneration?: boolean; refreshMe?: boolean } = {}
): Promise<void> {
const tokenChanged = token !== this.sessionToken
if (tokenChanged && options.advanceSessionGeneration !== false) {
this.sessionGeneration += 1
}
this.sessionToken = token
if (tokenChanged) {
this.rpcTokenManager.clear()
this.profileUiBaseUrlCache = null
this.accessCatalog = null
await this.tokenStore.setSessionToken(token, getActiveEnvKey())
if (this.gfsTransientTeamHopDepth === 0) {
this.updateEntityChangeSessionToken(token)
this.restartEntityChangeStreamForSessionReplacement()
}
}
if (options.refreshMe) {
try {
this.me = await this.authClient.getMe(token)
} catch (error) {
unbindChatStore()
throw error
}
await this.bindCurrentChatStore(this.me.id)
this.updateCachedCurrentTeam(this.me.teamId)
}
}
/** Caller must hold the native auth/environment commit owner. */
private async switchSessionToTeam(
teamId: string,
token: string,
options: { advanceSessionGeneration?: boolean } = {}
) {
const releaseTransientHop = this.enterGfsTransientTeamHop()
const targetTeamId = String(teamId || '').trim()
try {
if (!targetTeamId) throw new Error('teamId is required')
const switchGeneration = this.sessionGeneration
if (this.sessionToken !== token || !this.me) {
throw new Error('stale_auth_epoch: authenticated team scope changed before switch dispatch')
}
const previousIdentity =
this.gfsScopeIdentity ?? (this.me ? desktopGfsUploadIdentity(this.me) : undefined)
let switchedToken: string | null = null
try {
const switched = await this.authClient.switchTeam(token, targetTeamId)
switchedToken = switched.token
if (this.sessionGeneration !== switchGeneration || this.sessionToken !== token) {
throw new Error('stale_auth_epoch: authenticated team scope changed during switch')
}
await this.commitSessionToken(switched.token, {
advanceSessionGeneration: options.advanceSessionGeneration,
refreshMe: true,
})
if (!this.me) throw new Error('Team switch ended without an authenticated session')
return switched.token
} catch (error) {
if (!switchedToken && this.sessionToken === token && this.me) {
// A failed transient hop leaves the deliberate GFS scope untouched.
} else {
// Once the auth service has issued a replacement token, the previous
// authenticated scope is no longer safe to continue. Fence and
// persist its uploads before clearing the partially switched session;
// otherwise a failed refresh/restore could leave a job running with a
// token whose team ownership is unknown. The fence is best effort:
// clearing the in-memory scope and revoking the persisted token must
// still happen when its state write is unavailable.
try {
await this.suspendDesktopGfsUploadsForAuthBoundary(previousIdentity)
} catch (fenceError) {
console.warn(
'[AppService] Failed to persist the GFS authentication fence during team switch:',
fenceError
)
}
this.clearAuthenticatedSessionState()
try {
await this.tokenStore.clearSessionToken(getActiveEnvKey(), {
legacyEnvKeys: getActiveLegacyEnvKeys(),
})
} catch (clearError) {
console.warn(
'[AppService] Failed to clear a partially switched team session:',
clearError
)
}
}
throw error
}
} finally {
releaseTransientHop()
}
}
private enterGfsTransientTeamHop(): () => void {
this.gfsTransientTeamHopDepth += 1
let released = false
return () => {
if (released) return
released = true
this.gfsTransientTeamHopDepth = Math.max(0, this.gfsTransientTeamHopDepth - 1)
if (this.gfsTransientTeamHopDepth === 0 && this.entityChangeSessionExpiryDeferred) {
this.entityChangeSessionExpiryDeferred = false
this.emitEntityChangeSessionExpired()
}
}
}
private assertGfsDispatchAllowed(): void {
if (this.gfsTransientTeamHopDepth > 0) {
throw new Error('GFS upload dispatch is unavailable during a transient team hop')
}
}
private runWithTeamContext<T>(
teamId: string | null | undefined,
operation: (sessionToken: string) => Promise<T>,
options: { mutation?: boolean } = {}
): Promise<T> {
const targetTeamId = String(teamId || '').trim()
const run = () => this.runWithTeamContextInTeamQueue(targetTeamId, operation, options)
return run()
}
private async runWithTeamContextInTeamQueue<T>(
targetTeamId: string,
operation: (sessionToken: string) => Promise<T>,
options: { mutation?: boolean } = {}
): Promise<T> {
if (!targetTeamId) {
await this.teamContextQueue.catch(() => undefined)
if (options.mutation) {
return this.withNativeAuthEnvironmentCommit(() => operation(this.requireSessionToken()))
}
return operation(this.requireSessionToken())
}
const previousQueue = this.teamContextQueue
let releaseQueue!: () => void
this.teamContextQueue = previousQueue
.catch(() => undefined)
.then(
() =>
new Promise<void>(resolve => {
releaseQueue = resolve
})
)
await previousQueue.catch(() => undefined)
try {
const session = await this.withNativeAuthEnvironmentCommit(async () => {
const sessionToken = this.requireSessionToken()
return {
sessionToken,
teamId: String(this.me?.teamId || '').trim(),
sessionGeneration: this.sessionGeneration,
environmentBinding: this.captureAuthEnvironmentBinding(),
}
})
let context = session
if (!context.teamId) {
const me = await this.authClient.getMe(session.sessionToken)
context = await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(session.sessionGeneration)
if (this.sessionToken !== session.sessionToken) {
throw new Error('stale_auth_epoch: authenticated team scope changed during discovery')
}
this.assertAuthEnvironmentBinding(session.environmentBinding)
this.me = me
await this.bindCurrentChatStore(me.id)
this.updateCachedCurrentTeam(me.teamId)
return { ...session, teamId: String(me.teamId || '').trim() }
})
}
const assertContextIsCurrent = () => {
this.assertSessionGeneration(context.sessionGeneration)
const currentTeamId = String(this.me?.teamId || '').trim()
if (this.sessionToken !== context.sessionToken || currentTeamId !== context.teamId) {
throw new Error('stale_auth_epoch: authenticated team scope changed during operation')
}
this.assertAuthEnvironmentBinding(context.environmentBinding)
}
if (context.teamId === targetTeamId) {
if (options.mutation) {
return this.withNativeAuthEnvironmentCommit(async () => {
assertContextIsCurrent()
const result = await operation(context.sessionToken)
return result
})
}
const { request } = await this.withNativeAuthEnvironmentCommit(async () => {
assertContextIsCurrent()
return { request: operation(context.sessionToken) }
})
const result = await request
return this.withNativeAuthEnvironmentCommit(async () => {
assertContextIsCurrent()
return result
})
}
return await this.withNativeAuthEnvironmentCommit(async () => {
assertContextIsCurrent()
const originalToken = context.sessionToken
const originalTeamId = context.teamId
const shouldRestore = Boolean(originalTeamId)
let restoredOriginalTeam = false
let operationFailed = false
let restoreFailed = false
let restoreFailure: unknown
let hopSessionToken: string | null = null
const releaseTransientHop = this.enterGfsTransientTeamHop()
if (shouldRestore) this.chatStoreHomeTeamId = originalTeamId
try {
const activeToken = await this.switchSessionToTeam(targetTeamId, originalToken, {
advanceSessionGeneration: false,
})
hopSessionToken = activeToken
try {
return await operation(activeToken)
} catch (error) {
operationFailed = true
throw error
} finally {
if (shouldRestore) {
try {
await this.switchSessionToTeam(originalTeamId, this.requireSessionToken(), {
advanceSessionGeneration: false,
})
restoredOriginalTeam = true
} catch (restoreError) {
restoreFailed = true
restoreFailure = restoreError
if (operationFailed) {
console.warn(
'[AppService] Failed to restore team context after operation:',
restoreError
)
}
}
}
if (restoredOriginalTeam && this.sessionToken) {
this.updateEntityChangeSessionToken(this.sessionToken)
this.restartEntityChangeStreamForSessionReplacement()
} else if (
shouldRestore &&
hopSessionToken &&
this.sessionToken === hopSessionToken &&
this.me &&
String(this.me.teamId || '').trim() !== originalTeamId
) {
// A failed restore leaves the hop team as the actual committed
// session. Publish it as a new session before releasing the owner,
// then rebind session-scoped consumers to the token that remains.
this.sessionGeneration += 1
this.updateEntityChangeSessionToken(this.sessionToken)
this.restartEntityChangeStreamForSessionReplacement()
}
if (restoreFailed && !operationFailed) throw restoreFailure
}
} finally {
if (shouldRestore) {
this.chatStoreHomeTeamId = null
// A failed switch back leaves the session on the hop team while the
// store is still bound to the pinned home team. Rebind so the store
// scope and delete-fence authority agree again. A rebind failure is
// logged and never replaces the operation or restore error.
const sessionUserId = this.me?.id
if (sessionUserId && this.me?.teamId !== originalTeamId) {
try {
await this.bindCurrentChatStore(sessionUserId)
} catch (rebindError) {
console.error(
'[AppService] Failed to rebind the chat store after a failed team restore:',
rebindError
)
}
}
}
releaseTransientHop()
}
})
} finally {
releaseQueue()
}
}
private async resolveTeamForHostRefs(hostRefs: string[]): Promise<string | null> {
const refs = AppService.dedupe(hostRefs)
if (!refs.length) return null
const currentSessionTeamId = String(this.me?.teamId || '').trim()
const cachedCatalogTeamId = String(this.accessCatalog?.teamId || '').trim()
const directory = this.teamDirectoryCache
const currentTeamId = directory?.currentTeamId || currentSessionTeamId || cachedCatalogTeamId
if (
this.accessCatalog?.userAgentNames.length &&
refs.every(ref => this.accessCatalog?.userAgentNames.includes(ref))
) {
if (currentSessionTeamId || cachedCatalogTeamId) return null
if (currentTeamId) return currentTeamId
}
if (!directory) return this.accessCatalog?.teamId ?? null
const teamHasRefs = (entry: TeamDirectoryResult['items'][number]) =>
refs.every(ref => entry.agentNames.includes(ref))
if (currentTeamId) {
const currentEntry = directory.items.find(entry => entry.team.id === currentTeamId)
if (currentEntry && teamHasRefs(currentEntry)) return currentTeamId
}
const matchingEntry = directory.items.find(teamHasRefs)
return matchingEntry?.team.id ?? this.accessCatalog?.teamId ?? null
}
/**
* Monotonic per sandbox-ui mount. Carried into the SDK surface pin so a
* request from a superseded embed can be told apart from the live one
*, mirroring the driver's own `mountGeneration` guard.
*/
private sandboxUiGeneration = 0
/**
* Advanced only when the signed-in user goes away: the session is cleared, or
* a login replaces it without a logout. Sandbox-ui work
* that awaits the network (open mint, OAuth authorize-url fetch) captures it
* first and drops its effects if it moved. `sessionGeneration` cannot serve:
* every token commit bumps it, including the two of each transient team hop
* that unrelated concurrent work performs while a mint is in flight.
*/
private sandboxUiSessionEpoch = 0
private assertSandboxUiSessionEpoch(epoch: number): void {
if (this.sandboxUiSessionEpoch !== epoch) {
throw new Error('The session changed while this app request was in flight')
}
}
private enqueueSandboxUiLifecycle<T>(operation: () => Promise<T>): Promise<T> {
const result = this.sandboxUiLifecycleQueue.then(operation)
this.sandboxUiLifecycleQueue = result.then(
() => undefined,
() => undefined
)
return result
}
private async issueRpcTokenForHostRefs(
scopes: RpcScope[],
hostRefs: string[],
options: { teamId?: string | null } = {}
) {
const targetTeamId =
String(options.teamId || '').trim() || (await this.resolveTeamForHostRefs(hostRefs))
return this.runWithTeamContext(targetTeamId, token =>
this.rpcTokenManager.getOrIssue(token, scopes, hostRefs)
)
}
private clearAuthenticatedSessionState(): void {
this.sessionGeneration += 1
this.updateEntityChangeSessionToken(null)
this.gfsAuthEpoch += 1
this.gfsDispatchBlocked = true
this.gfsScopeIdentity = null
this.cancelPrewarmReemissions()
this.stopAllStreams()
this.sessionToken = null
this.me = null
this.clearEffectiveRuntimeRpcEndpoint()
this.profileUiBaseUrlCache = null
this.accessCatalog = null
this.teamDirectoryCache = null
this.workflowApprovalTeamById.clear()
this.workflowTeamByKey.clear()
this.rpcTokenManager.clear()
unbindChatStore()
this.invalidateSandboxUiSession()
}
/** Retires the sandbox-ui work of a session that is being cleared or replaced. */
private invalidateSandboxUiSession(): void {
this.sandboxUiSessionEpoch += 1
// The embed and its refresh loop run on the outgoing session. Queued rather
// than awaited: callers must not wait on a pending open's mint; the serial
// queue still tears down whatever that open mounts.
void this.closeSandboxUi({ reason: 'session' }).catch(error => {
console.error('[SandboxUI] Could not close the embed on session change:', error)
})
}
private activateGfsAuthScope(identityOverride?: DesktopGfsUploadIdentity): void {
this.gfsAuthEpoch += 1
this.gfsDispatchBlocked = false
this.gfsScopeIdentity = identityOverride ?? (this.me ? desktopGfsUploadIdentity(this.me) : null)
}
private cancelPrewarmReemissions(): void {
this.prewarmAuthEpoch += 1
this.prewarmAttemptAtByHostRef.clear()
this.prewarmReemitLoopHostRefs.clear()
for (const controller of this.prewarmReemitAbortControllers.values()) controller.abort()
this.prewarmReemitAbortControllers.clear()
}
private beginPrewarmAuthTransition(): () => void {
this.prewarmAuthTransitionCount += 1
this.cancelPrewarmReemissions()
let released = false
return () => {
if (released) return
released = true
this.cancelPrewarmReemissions()
this.prewarmAuthTransitionCount -= 1
}
}
private currentDesktopGfsUploadScope(
driveValue: string | undefined,
options: { allowTransientTeamHop?: boolean } = {}
): DesktopGfsUploadScope {
if (this.gfsDispatchBlocked || !this.sessionToken || !this.me) {
throw new Error('GFS upload dispatch is unavailable without an active authenticated scope')
}
if (!options.allowTransientTeamHop) this.assertGfsDispatchAllowed()
const identity = this.gfsScopeIdentity
if (!identity) {
throw new Error('GFS upload dispatch is unavailable before scope activation')
}
return {
...identity,
drive: normalizeDesktopUploadDrive(driveValue),
authEpoch: this.gfsAuthEpoch,
}
}
private assertCurrentDesktopGfsUploadScope(scope: DesktopGfsUploadScope): void {
// Existing jobs retain their original token and scope while a finite RPC
// borrows another team session. Only new user-facing dispatches are gated.
const current = this.currentDesktopGfsUploadScope(scope.drive, { allowTransientTeamHop: true })
if (!sameDesktopGfsUploadScope(scope, current)) {
throw new Error('stale_auth_epoch: GFS upload no longer belongs to the active scope')
}
}
private async suspendDesktopGfsUploadsForAuthBoundary(identityOverride?: {
ownerId: string
teamId: string | null
environmentKey: string
baseUrl: string
}): Promise<void> {
const oldIdentity =
identityOverride ??
(this.me
? {
ownerId: this.me.id,
teamId: this.me.teamId ? String(this.me.teamId).trim() : null,
environmentKey: getActiveEnvKey(),
baseUrl: normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl),
}
: null)
this.gfsDispatchBlocked = true
this.gfsAuthEpoch += 1
const jobs = new Set([
...[...this.gfsUploadJobs.values()].map(entry => entry.job),
...[...this.gfsPendingUploadJobs].map(entry => entry.job),
])
const jobSuspensions = [...jobs].map(job => job.suspendForAuth())
const legacyUploads = [...this.gfsPendingLegacyUploads]
for (const upload of legacyUploads) {
upload.controller.abort(new Error('GFS legacy upload suspended by authentication fence'))
}
await Promise.all([
...jobSuspensions,
...legacyUploads.map(upload => upload.promise.catch(() => undefined)),
])
this.gfsUploadJobs.clear()
this.gfsPendingUploadJobs.clear()
this.gfsPendingLegacyUploads.clear()
if (!oldIdentity) return
await this.updateDesktopGfsUploadState(state => {
const updatedAt = new Date().toISOString()
return {
...state,
records: state.records.map(record =>
record.scope.ownerId === oldIdentity.ownerId &&
record.scope.teamId === oldIdentity.teamId &&
record.scope.environmentKey === oldIdentity.environmentKey &&
record.scope.baseUrl === oldIdentity.baseUrl
? { ...record, status: 'suspended_auth' as const, updatedAt }
: record
),
}
})
}
private async restoreSavedSession(options: { runLaunchMaintenance?: boolean } = {}) {
if (this.restoreSavedSessionInFlight) {
return await this.restoreSavedSessionInFlight
}
const restore = (async () => {
this.restoreSavedSessionReservationStarted = false
await this.resolveRuntimeConfigIfNeeded().catch(() => undefined)
return this.restoreSavedSessionOnce(options)
})()
this.restoreSavedSessionInFlight = restore
try {
return await restore
} finally {
// No newer restore can start while this promise is installed, so the
// single-flight slot can be cleared unconditionally after it settles.
this.restoreSavedSessionInFlight = null
this.restoreSavedSessionReservationStarted = false
if (this.interactiveLoginAttempts === 0) {
await this.withNativeAuthEnvironmentCommit(async () => {
await this.commitPendingRuntimeConfigDiscoveryIfSafe().catch(() => undefined)
})
}
}
}
private async restoreSavedSessionOnce(options: { runLaunchMaintenance?: boolean } = {}) {
const reservation = await this.withNativeAuthEnvironmentCommit(async () => {
this.restoreSavedSessionReservationStarted = true
if (this.interactiveLoginAttempts > 0) return null
hydrateDesktopRuntimeConfig()
const environment = this.captureAuthEnvironmentBinding()
const legacyEnvKeys = getActiveLegacyEnvKeys()
this.savedSessionRestoreAttemptedEnvKey = environment.environmentKey
this.savedSessionRestoreAttemptedAtMs = Date.now()
let token: string | null = null
let tokenReadFailed = false
try {
// getSessionToken can migrate a legacy token into a new durable slot,
// so keep the native owner until its read/migration has settled.
token = await this.tokenStore.getSessionToken(environment.environmentKey, {
legacyEnvKeys,
})
} catch {
tokenReadFailed = true
}
return {
sessionGeneration: this.sessionGeneration,
environment,
legacyEnvKeys,
token,
tokenReadFailed,
}
})
if (!reservation) {
return this.withNativeAuthEnvironmentCommit(async () => ({
authenticated: Boolean(this.sessionToken && this.me),
me: this.me,
}))
}
const ownsRestore = () =>
this.sessionGeneration === reservation.sessionGeneration &&
this.interactiveLoginAttempts === 0 &&
(() => {
try {
this.assertAuthEnvironmentBinding(reservation.environment)
return true
} catch {
return false
}
})()
const currentSession = () => ({
authenticated: Boolean(this.sessionToken && this.me),
me: this.me,
})
if (reservation.tokenReadFailed) {
return this.withNativeAuthEnvironmentCommit(async () => {
if (!ownsRestore()) return currentSession()
if (this.sessionToken !== null || this.me !== null) this.clearAuthenticatedSessionState()
return { authenticated: false, me: null }
})
}
const token = reservation.token
if (!token) {
return this.withNativeAuthEnvironmentCommit(async () => {
if (!ownsRestore()) return currentSession()
if (this.sessionToken !== null || this.me !== null) this.clearAuthenticatedSessionState()
return { authenticated: false, me: null }
})
}
let getMeRequest: ReturnType<AuthClient['getMe']> | undefined
const requestStarted = await this.withNativeAuthEnvironmentCommit(async () => {
if (!ownsRestore()) return false
getMeRequest = this.authClient.getMe(token)
return true
})
if (!requestStarted || !getMeRequest) {
return this.withNativeAuthEnvironmentCommit(async () => currentSession())
}
try {
const restoredMe = await getMeRequest
const session = await this.withNativeAuthEnvironmentCommit(async () => {
if (!ownsRestore()) return currentSession()
this.sessionToken = token
const environmentKey = reservation.environment.environmentKey
await bindChatStoreForUser(restoredMe.id, environmentKey, {
legacyEnvKeys: reservation.legacyEnvKeys,
teamId: restoredMe.teamId,
})
this.me = restoredMe
this.savedSessionRestoreAttemptedEnvKey = environmentKey
this.updateEntityChangeSessionToken(token)
this.restartEntityChangeStreamForSessionReplacement()
this.accessCatalog = null
this.teamDirectoryCache = null
this.workflowApprovalTeamById.clear()
this.workflowTeamByKey.clear()
// Persisted uploads are never auto-resumed. The active owner/team/env can
// list only its own scoped records and must explicitly resume one, at
// which point the record is rebound to this newly activated auth epoch.
const restoredGfsIdentity: DesktopGfsUploadIdentity = {
ownerId: restoredMe.id,
teamId: restoredMe.teamId ? String(restoredMe.teamId).trim() : null,
environmentKey,
baseUrl: normalizeDesktopUploadBaseUrl(reservation.environment.restBaseUrl),
}
this.activateGfsAuthScope(restoredGfsIdentity)
await this.migrateLegacyDesktopGfsUploadScopes(
restoredGfsIdentity,
reservation.legacyEnvKeys
).catch(() => undefined)
// A successful restore publishes a new auth owner. Invalidate pending
// setup and other work prepared against the signed-out generation only
// after the restored session and its GFS scope are coherent.
this.sessionGeneration += 1
return { authenticated: true, me: restoredMe }
})
if (session.authenticated && options.runLaunchMaintenance) {
// Launch-time sandbox-ui partition GC is best-effort and must not delay
// publishing the saved session.
void this.runSandboxUiPartitionGcSafely()
}
return session
} catch (error) {
return this.withNativeAuthEnvironmentCommit(async () => {
if (!ownsRestore()) return currentSession()
if (this.sessionToken !== null || this.me !== null) this.clearAuthenticatedSessionState()
if (AppService.isRejectedStoredSessionError(error)) {
await this.tokenStore.clearSessionToken(getActiveEnvKey(), {
legacyEnvKeys: getActiveLegacyEnvKeys(),
})
}
return { authenticated: false, me: null }
})
}
}
async initialize(): Promise<SessionState> {
return this.restoreSavedSession({ runLaunchMaintenance: true })
}
private async runSandboxUiPartitionGcSafely(): Promise<void> {
try {
const { app } = await import('electron')
const { runSandboxUiPartitionGc } = await import('./sandboxUiPartitionGc.js')
const result = await runSandboxUiPartitionGc({
userDataDir: app.getPath('userData'),
envKey: getActiveEnvKey(),
listAccessibleApps: () => this.listSandboxUiApps(),
})
if (result.wiped.length || result.evicted.length) {
console.info(
`[SandboxUI] partition GC complete: wiped=${result.wiped.length}, ` +
`evicted=${result.evicted.length}`
)
}
} catch (err) {
console.warn('[SandboxUI] partition GC failed:', err)
}
}
private async installAuthenticatedLogin(
result: { token: string; me: SessionMe },
expectedSessionGeneration: number
): Promise<SessionState> {
this.assertSessionGeneration(expectedSessionGeneration)
const releasePrewarm = this.beginPrewarmAuthTransition()
try {
const previousToken = this.sessionToken
const previousMe = this.me
const previousGeneration = this.sessionGeneration
const hadAuthenticatedScope = Boolean(previousToken && previousMe)
if (hadAuthenticatedScope) {
try {
await this.suspendDesktopGfsUploadsForAuthBoundary()
} catch (error) {
if (
this.sessionGeneration === previousGeneration &&
this.sessionToken === previousToken &&
this.me === previousMe
) {
this.activateGfsAuthScope()
}
throw error
}
this.assertSessionGeneration(expectedSessionGeneration)
if (
this.sessionGeneration !== previousGeneration ||
this.sessionToken !== previousToken ||
this.me !== previousMe
) {
throw new Error('stale_auth_epoch: authenticated scope changed during login replacement')
}
}
this.sessionGeneration += 1
// A login over a live session replaces it without a logout, so nothing
// else retires the outgoing user's embed, refresh loop or in-flight open.
if (hadAuthenticatedScope) this.invalidateSandboxUiSession()
this.sessionToken = result.token
this.me = result.me
this.updateEntityChangeSessionToken(result.token)
this.restartEntityChangeStreamForSessionReplacement()
await this.bindCurrentChatStore(result.me.id)
this.accessCatalog = null
this.teamDirectoryCache = null
this.workflowApprovalTeamById.clear()
this.workflowTeamByKey.clear()
this.rpcTokenManager.clear()
await this.tokenStore.setSessionToken(result.token, getActiveEnvKey())
this.activateGfsAuthScope()
if (this.gfsScopeIdentity) {
await this.migrateLegacyDesktopGfsUploadScopes(
this.gfsScopeIdentity,
getActiveLegacyEnvKeys()
).catch(() => undefined)
}
return { authenticated: true, me: result.me }
} finally {
releasePrewarm()
}
}
private async completePasswordLogin(
email: string,
password: string,
expectedSessionGeneration: number
): Promise<SessionState> {
let loginRequest: ReturnType<AuthClient['passwordLogin']> | undefined
const binding = await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(expectedSessionGeneration)
const currentBinding = this.captureAuthEnvironmentBinding()
loginRequest = this.authClient.passwordLogin(email, password)
return currentBinding
})
if (!loginRequest) throw new Error('password login request was not dispatched')
const result = await loginRequest
return this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(expectedSessionGeneration)
this.assertAuthEnvironmentBinding(binding)
return this.installAuthenticatedLogin(result, expectedSessionGeneration)
})
}
async getDependenciesHealth(): Promise<DependencyHealth> {
await this.resolveRuntimeConfigIfNeeded().catch(() => undefined)
const [externalHealth, rpcHealth] = await Promise.allSettled([
this.authClient.health(),
this.rpcClient.health(),
])
return {
externalRestApi:
externalHealth.status === 'fulfilled'
? { ok: externalHealth.value.status === 'ok' }
: {
ok: false,
detail:
externalHealth.reason instanceof Error
? externalHealth.reason.message
: String(externalHealth.reason),
},
rpcProxy:
rpcHealth.status === 'fulfilled'
? { ok: rpcHealth.value.status === 'ok' }
: {
ok: false,
detail:
rpcHealth.reason instanceof Error
? rpcHealth.reason.message
: String(rpcHealth.reason),
},
}
}
getRuntimeConfigState() {
return getDesktopRuntimeConfigState()
}
getSessionGeneration(): number {
return this.sessionGeneration
}
private assertSessionGeneration(expectedSessionGeneration: number): void {
if (this.sessionGeneration !== expectedSessionGeneration) {
throw new Error('stale_session_generation')
}
}
private assertProfileHandoffSessionIsSignedOut(): void {
if (this.interactiveLoginAttempts > 0) {
throw new Error('auth_transition_in_progress')
}
if (this.sessionToken || this.me) {
throw new Error('desktop_setup_requires_signout')
}
}
private async applyRuntimeEnvironmentChange(
operation: () => Promise<void>,
expectedSessionGeneration?: number
): Promise<number> {
if (expectedSessionGeneration !== undefined) {
this.assertSessionGeneration(expectedSessionGeneration)
}
const oldEnvKey = getActiveEnvKey()
const oldBaseUrl = normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl)
const oldLegacyEnvKeys = getActiveLegacyEnvKeys()
const oldSessionToken = this.sessionToken
const oldMe = this.me
const releasePrewarm = this.beginPrewarmAuthTransition()
try {
const hadAuthenticatedScope = Boolean(this.sessionToken && this.me)
this.entityChangeEnvironmentSwitching = true
this.entityChangeConnectionStop?.({ silent: true })
// Invalidate a restore that may still be awaiting keychain/getMe before it
// can bind an old-environment token to the newly selected runtime.
this.sessionGeneration += 1
const transitionGeneration = this.sessionGeneration
if (hadAuthenticatedScope) await this.suspendDesktopGfsUploadsForAuthBoundary()
this.assertSessionGeneration(transitionGeneration)
try {
await operation()
this.assertSessionGeneration(transitionGeneration)
this.discardRuntimeConfigDiscoveryOutsideCurrentBinding()
} catch (error) {
const environmentUnchanged =
getActiveEnvKey() === oldEnvKey &&
normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl) === oldBaseUrl
if (!environmentUnchanged) {
this.discardRuntimeConfigDiscoveryOutsideCurrentBinding()
this.clearAuthenticatedSessionState()
await this.tokenStore
.clearSessionToken(oldEnvKey, { legacyEnvKeys: oldLegacyEnvKeys })
.catch(() => undefined)
} else if (
hadAuthenticatedScope &&
this.sessionToken === oldSessionToken &&
this.me === oldMe &&
this.sessionToken &&
this.me
) {
this.activateGfsAuthScope()
}
throw error
}
const boundaryChanged =
getActiveEnvKey() !== oldEnvKey ||
normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl) !== oldBaseUrl
if (boundaryChanged) {
this.clearAuthenticatedSessionState()
await this.tokenStore.clearSessionToken(oldEnvKey, { legacyEnvKeys: oldLegacyEnvKeys })
} else if (hadAuthenticatedScope && this.sessionToken && this.me) {
this.activateGfsAuthScope()
this.sessionGeneration += 1
} else {
this.sessionGeneration += 1
}
return this.sessionGeneration
} finally {
this.entityChangeEnvironmentSwitching = false
if (
getActiveEnvKey() === oldEnvKey &&
normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl) === oldBaseUrl
) {
this.ensureEntityChangeConnection()
}
releasePrewarm()
}
}
async selectRuntimeConfig(optionId: string) {
return (await this.selectRuntimeConfigWithGeneration(optionId)).runtimeConfigState
}
async selectRuntimeConfigForHandoff(
optionId: string,
expectedSessionGeneration: number
): Promise<DesktopRuntimeConfigHandoffSelection> {
if (!Number.isSafeInteger(expectedSessionGeneration) || expectedSessionGeneration < 0) {
throw new Error('invalid_session_generation')
}
return this.selectRuntimeConfigWithGeneration(optionId, expectedSessionGeneration)
}
private async selectRuntimeConfigWithGeneration(
optionId: string,
expectedSessionGeneration?: number
): Promise<DesktopRuntimeConfigHandoffSelection> {
return this.withNativeAuthEnvironmentCommit(async () => {
if (expectedSessionGeneration !== undefined) {
this.assertSessionGeneration(expectedSessionGeneration)
this.assertProfileHandoffSessionIsSignedOut()
}
const state = getDesktopRuntimeConfigState()
const selected = state.options.find(option => option.id === String(optionId || '').trim())
const nextEnvKey = selected
? resolveEnvKey(selected.externalRestApiBaseUrl, selected.rpcProxyBaseUrl)
: null
const sameUploadBoundary =
nextEnvKey === state.envKey &&
selected !== undefined &&
normalizeDesktopUploadBaseUrl(selected.externalRestApiBaseUrl) ===
normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl)
if (sameUploadBoundary) {
this.sessionGeneration += 1
const transitionGeneration = this.sessionGeneration
await selectDesktopRuntimeConfigOption(optionId)
this.assertSessionGeneration(transitionGeneration)
this.discardRuntimeConfigDiscoveryOutsideCurrentBinding()
this.sessionGeneration += 1
} else {
await this.applyRuntimeEnvironmentChange(
() => selectDesktopRuntimeConfigOption(optionId),
expectedSessionGeneration
)
}
return {
runtimeConfigState: getDesktopRuntimeConfigState(),
sessionGeneration: this.sessionGeneration,
}
})
}
async clearRuntimeConfigSelection() {
return this.withNativeAuthEnvironmentCommit(async () => {
await this.applyRuntimeEnvironmentChange(clearDesktopRuntimeConfigSelection)
return getDesktopRuntimeConfigState()
})
}
async saveRuntimeConfig(next: DesktopRuntimeConfig, expectedSessionGeneration?: number) {
await this.withNativeAuthEnvironmentCommit(async () => {
if (expectedSessionGeneration !== undefined) {
if (!Number.isSafeInteger(expectedSessionGeneration) || expectedSessionGeneration < 0) {
throw new Error('invalid_session_generation')
}
this.assertSessionGeneration(expectedSessionGeneration)
this.assertProfileHandoffSessionIsSignedOut()
}
const nextEnvKey = resolveEnvKey(next.externalRestApiBaseUrl, next.rpcProxyBaseUrl || '')
const sameUploadBoundary =
nextEnvKey === getActiveEnvKey() &&
normalizeDesktopUploadBaseUrl(next.externalRestApiBaseUrl) ===
normalizeDesktopUploadBaseUrl(config.externalRestApiBaseUrl)
if (sameUploadBoundary) {
await saveDesktopRuntimeConfig(next)
this.discardRuntimeConfigDiscoveryOutsideCurrentBinding()
} else await this.applyRuntimeEnvironmentChange(() => saveDesktopRuntimeConfig(next))
})
await this.resolveRuntimeConfigIfNeeded().catch(() => undefined)
return getDesktopRuntimeConfigState()
}
async deleteRuntimeConfig(optionId: string) {
return this.withNativeAuthEnvironmentCommit(async () => {
const state = getDesktopRuntimeConfigState()
if (state.activeOptionId === String(optionId || '').trim())
await this.applyRuntimeEnvironmentChange(() => deleteDesktopRuntimeConfigOption(optionId))
else await deleteDesktopRuntimeConfigOption(optionId)
return getDesktopRuntimeConfigState()
})
}
async googleLogin(idToken: string): Promise<SessionState> {
let loginRequest: ReturnType<AuthClient['googleLogin']> | undefined
let registered = false
try {
const sessionGeneration = await this.withNativeAuthEnvironmentCommit(async () => {
const sessionGeneration = ++this.sessionGeneration
this.interactiveLoginAttempts += 1
registered = true
return sessionGeneration
})
await this.resolveRuntimeConfigIfNeeded().catch(() => undefined)
const binding = await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(sessionGeneration)
return this.captureAuthEnvironmentBinding()
})
const dispatch = await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(sessionGeneration)
this.assertAuthEnvironmentBinding(binding)
return { request: this.authClient.googleLogin(idToken) }
})
loginRequest = dispatch.request
if (!loginRequest) throw new Error('Google login request was not dispatched')
const result = await loginRequest
return await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(sessionGeneration)
this.assertAuthEnvironmentBinding(binding)
return this.installAuthenticatedLogin(result, sessionGeneration)
})
} finally {
if (registered) {
await this.withNativeAuthEnvironmentCommit(async () => {
this.interactiveLoginAttempts = Math.max(0, this.interactiveLoginAttempts - 1)
if (this.interactiveLoginAttempts === 0 && !this.sessionToken && !this.me) {
await this.commitPendingRuntimeConfigDiscoveryIfSafe().catch(() => undefined)
}
})
}
}
}
private async openProfileDesktopSetup(email: string): Promise<{
profileUiUrl: string
appName: string
}> {
try {
const activation = await this.memberRegistrationServiceClient.getInvitationProfile(email)
if (activation.email.trim().toLowerCase() !== email.trim().toLowerCase()) {
throw new Error('invitation configuration mismatch')
}
const profileUiUrl = new URL(
'/desktop-setup',
`${activation.profileUiBaseUrl.replace(/\/+$/, '')}/`
)
profileUiUrl.searchParams.set('email', activation.email)
await openExternalDataUrl(profileUiUrl.toString())
return {
profileUiUrl: profileUiUrl.toString(),
appName: activation.appName,
}
} catch (error) {
if (error instanceof ApiError) {
if (error.status === 404) {
throw new Error('invitation_config_not_found')
}
}
throw error
}
}
async startDesktopSetup(email: string): Promise<{
profileUiUrl: string
appName: string
}> {
const normalizedEmail = email.trim().toLowerCase()
if (!normalizedEmail) throw new Error('email is required')
return this.openProfileDesktopSetup(normalizedEmail)
}
async openForgotPassword(email: string): Promise<{ profileUiUrl: string }> {
const normalizedEmail = email.trim().toLowerCase()
const profileUiBaseUrl = requireProfileUiBaseUrlForBrowserAction()
const profileUiUrl = new URL('/forgot-password', `${profileUiBaseUrl.replace(/\/+$/, '')}/`)
if (normalizedEmail) profileUiUrl.searchParams.set('email', normalizedEmail)
await openExternalDataUrl(profileUiUrl.toString())
return { profileUiUrl: profileUiUrl.toString() }
}
async openProfileSettings(
email: string,
options: ProfileSettingsOpenOptions = {}
): Promise<{ profileUiUrl: string }> {
const normalizedEmail = email.trim().toLowerCase()
const profileUiBaseUrl = await this.resolveProfileUiBaseUrl(normalizedEmail)
const network = String(options.network || '')
.trim()
.toLowerCase()
const socialPath =
options.section === 'social' && /^[a-z0-9-]+$/.test(network)
? `/settings/social/${network}`
: '/settings/profile'
const profileUiUrl = new URL(socialPath, `${profileUiBaseUrl.replace(/\/+$/, '')}/`)
if (options.action === 'password') profileUiUrl.searchParams.set('action', 'password')
await openExternalDataUrl(profileUiUrl.toString())
return { profileUiUrl: profileUiUrl.toString() }
}
private async resolveProfileUiBaseUrl(
email?: string,
options: { fallbackOnLookupError?: boolean } = {}
): Promise<string> {
const { fallbackOnLookupError = true } = options
if (config.desktopProfileUiBaseUrlExplicit) {
const explicitBaseUrl = normalizeExplicitProfileUiBaseUrl(config.desktopProfileUiBaseUrl)
if (!explicitBaseUrl) {
throw new Error(PROFILE_UI_BASE_URL_ORIGIN_ERROR)
}
return explicitBaseUrl
}
const normalizedEmail = String(email || this.me?.email || '')
.trim()
.toLowerCase()
if (!normalizedEmail) {
if (fallbackOnLookupError) return config.desktopProfileUiBaseUrl
throw new Error('Cannot resolve the Profile UI for this desktop session')
}
const cacheKey = `${getActiveEnvKey()}:${this.me?.id || ''}:${normalizedEmail}`
if (this.profileUiBaseUrlCache?.key === cacheKey) {
return this.profileUiBaseUrlCache.value
}
try {
const activation =
await this.memberRegistrationServiceClient.getInvitationProfile(normalizedEmail)
const profileUiBaseUrl = String(activation.profileUiBaseUrl || '').trim()
if (!profileUiBaseUrl) {
if (!fallbackOnLookupError) {
throw new Error('the invitation profile did not provide a Profile UI URL')
}
return config.desktopProfileUiBaseUrl
}
this.profileUiBaseUrlCache = { key: cacheKey, value: profileUiBaseUrl }
return profileUiBaseUrl
} catch (error) {
if (fallbackOnLookupError) return config.desktopProfileUiBaseUrl
const message = error instanceof Error ? error.message : String(error)
throw new Error(`Cannot resolve a shareable Profile UI link: ${message}`)
}
}
async completeDesktopSetup(email: string, authorizationToken: string) {
const normalizedEmail = email.trim().toLowerCase()
if (!normalizedEmail || !authorizationToken.trim()) {
throw new Error('email and authorization token are required')
}
const setupGeneration = await this.withNativeAuthEnvironmentCommit(async () => {
this.assertProfileHandoffSessionIsSignedOut()
return ++this.sessionGeneration
})
let setupRequest:
| ReturnType<MemberRegistrationServiceClient['completeDesktopSetup']>
| undefined
await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(setupGeneration)
setupRequest = this.memberRegistrationServiceClient.completeDesktopSetup(
normalizedEmail,
authorizationToken
)
})
if (!setupRequest) throw new Error('desktop setup request was not dispatched')
try {
const activation = await setupRequest
if (activation.email.trim().toLowerCase() !== normalizedEmail) {
throw new Error('desktop setup configuration mismatch')
}
const committedGeneration = await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(setupGeneration)
await saveDesktopRuntimeConfig({
externalRestApiBaseUrl: activation.externalRestApiBaseUrl,
rpcProxyBaseUrl: '',
appName: activation.appName,
})
this.discardRuntimeConfigDiscoveryOutsideCurrentBinding()
this.assertSessionGeneration(setupGeneration)
this.sessionGeneration += 1
return this.sessionGeneration
})
const shouldResolve = await this.withNativeAuthEnvironmentCommit(
async () => this.sessionGeneration === committedGeneration
)
if (shouldResolve) await this.resolveRuntimeConfigIfNeeded().catch(() => undefined)
return getDesktopRuntimeConfigState()
} catch (error) {
if (error instanceof ApiError && error.status === 404) {
throw new Error('desktop_setup_not_found')
}
throw error
}
}
async passwordLogin(email: string, password: string): Promise<PasswordLoginResult> {
let registered = false
try {
const loginGeneration = await this.withNativeAuthEnvironmentCommit(async () => {
const generation = ++this.sessionGeneration
hydrateDesktopRuntimeConfig()
if (!isDesktopRuntimeConfigured()) {
throw new Error('desktop_setup_required')
}
this.interactiveLoginAttempts += 1
registered = true
return generation
})
await this.withNativeAuthEnvironmentCommit(async () => {
this.assertSessionGeneration(loginGeneration)
})
await this.resolveRuntimeConfigIfNeeded().catch(() => undefined)
this.assertSessionGeneration(loginGeneration)
const normalizedEmail = email.trim().toLowerCase()
return await this.completePasswordLogin(normalizedEmail, password, loginGeneration)
} finally {
if (registered) {
await this.withNativeAuthEnvironmentCommit(async () => {
this.interactiveLoginAttempts = Math.max(0, this.interactiveLoginAttempts - 1)
if (this.interactiveLoginAttempts === 0 && !this.sessionToken && !this.me) {
await this.commitPendingRuntimeConfigDiscoveryIfSafe().catch(() => undefined)
}
})
}
}
}
/**
* After a login failure, decide whether to offer a one-click "switch to
* Localhost and retry". Returns a hint ONLY when all hold:
* - the active runtime profile is NOT already localhost,
* - a local Evenfire external-rest-api answers `/health`, and
* - the active backend does NOT answer `/health` (i.e. the failure looks
* like "pointed at the wrong/dead backend", not a bad password against a
* healthy one).
* Self-contained (reads current runtime state + probes reachability), so it
* never second-guesses a reachable backend and needs no detail from the
* thrown login error. Best-effort and time-bounded — a slow network yields
* `null`, never a slower login.
*/
async diagnoseLoginBackend(): Promise<LoginBackendHint | null> {
hydrateDesktopRuntimeConfig()
const state = getDesktopRuntimeConfigState()
if (state.isLocalhost) return null
const localhostOption = state.options.find(option => option.source === 'localhost')
if (!localhostOption?.externalRestApiBaseUrl) return null
const activeOption = state.options.find(option => option.id === state.activeOptionId) ?? null
const activeBaseUrl = activeOption?.externalRestApiBaseUrl || config.externalRestApiBaseUrl
// Nothing to switch to if we're already pointed at the localhost origin.
if (activeBaseUrl === localhostOption.externalRestApiBaseUrl) return null
const [localhostReachable, activeReachable] = await Promise.all([
this.probeBackendHealthy(localhostOption.externalRestApiBaseUrl),
this.probeBackendHealthy(activeBaseUrl),
])
if (!localhostReachable || activeReachable) return null
return {
targetOptionId: localhostOption.id,
targetLabel: localhostOption.label,
activeLabel: activeOption?.label || config.appName || activeBaseUrl,
}
}
/**
* Onboarding's local-cluster hint: is a local Evenfire answering?
*
* Takes **no argument** on purpose. The renderer cannot name a URL for the
* main process to fetch — it can only ask about the built-in Localhost
* option, whose address is a constant in config. Best-effort and
* time-bounded, like every other use of `probeBackendHealthy`; a negative
* result means "show no hint", never an error.
*/
async probeLocalhostReachable(): Promise<boolean> {
hydrateDesktopRuntimeConfig()
const state = getDesktopRuntimeConfigState()
const localhostOption = state.options.find(option => option.source === 'localhost')
if (!localhostOption?.externalRestApiBaseUrl) return false
return this.probeBackendHealthy(localhostOption.externalRestApiBaseUrl)
}
/**
* Open the deployment documentation for onboarding's self-hosted answer
*. The URL is a build-time constant, not a renderer argument.
*/
async openDeploymentDocs(): Promise<{ opened: true }> {
const { shell } = await import('electron')
await shell.openExternal(config.deploymentDocsUrl)
return { opened: true }
}
/**
* Open the hosted Evenfire site for onboarding's hosted answer.
* Also a build-time constant. No credentials, no tenant name and no nonce
* cross this boundary — the app only opens a page.
*/
async openHostedSignup(): Promise<{ opened: true }> {
const { shell } = await import('electron')
await shell.openExternal(config.hostedSignupUrl)
return { opened: true }
}
/** True iff `<baseUrl>/health` returns `{ status: 'ok' }` within the probe bound. */
private async probeBackendHealthy(baseUrl: string): Promise<boolean> {
if (!baseUrl?.trim()) return false
try {
const result = await this.authClient.healthAt(
baseUrl,
AbortSignal.timeout(BACKEND_PROBE_TIMEOUT_MS)
)
return result?.status === 'ok'
} catch {
return false
}
}
private async resolveRuntimeConfigIfNeeded(): Promise<void> {
const request = await this.withNativeAuthEnvironmentCommit(async () => {
hydrateDesktopRuntimeConfig()
if (!isDesktopRuntimeConfigured() || config.rpcProxyBaseUrl?.trim()) return null
if (
this.pendingRuntimeConfigDiscovery &&
this.interactiveLoginAttempts > 0 &&
!this.sessionToken &&
!this.me
) {
await this.applyRuntimeConfigDiscovery(this.pendingRuntimeConfigDiscovery)
}
if (config.rpcProxyBaseUrl?.trim()) return null
if (
this.effectiveRuntimeRpcEndpoint &&
this.runtimeConfigDiscoveryMatchesCurrentBinding(this.effectiveRuntimeRpcEndpoint)
) {
return null
}
return {
externalRestApiBaseUrl: canonicalizeDesktopRestEndpoint(config.externalRestApiBaseUrl),
appName: config.appName,
environmentBinding: this.captureAuthEnvironmentBinding(),
}
})
if (!request) return
const resolutionKey = JSON.stringify([
request.environmentBinding.profileId,
request.externalRestApiBaseUrl,
])
const inFlight = this.runtimeConfigResolutionInFlight.get(resolutionKey)
if (inFlight) {
await inFlight.promise
return
}
const resolution = { promise: this.resolveRuntimeConfigRequest(request) }
this.runtimeConfigResolutionInFlight.set(resolutionKey, resolution)
try {
await resolution.promise
} finally {
if (this.runtimeConfigResolutionInFlight.get(resolutionKey) === resolution) {
this.runtimeConfigResolutionInFlight.delete(resolutionKey)
}
}
}
private async resolveRuntimeConfigRequest(request: {
externalRestApiBaseUrl: string
appName: string
environmentBinding: {
environmentKey: string
profileId: string | null
restBaseUrl: string
}
}): Promise<void> {
const discovered = await this.authClient.getDesktopEnvironment()
const rpcProxyBaseUrl = validateRpcProxyBaseUrl(discovered.rpcProxyBaseUrl)
if (
!sameDesktopRestEndpoint(discovered.externalRestApiBaseUrl, request.externalRestApiBaseUrl)
) {
throw new Error('Desktop environment discovery returned a different REST endpoint')
}
await this.withNativeAuthEnvironmentCommit(async () => {
this.assertAuthEnvironmentBinding(request.environmentBinding)
await this.applyRuntimeConfigDiscovery({
profileId: request.environmentBinding.profileId,
externalRestApiBaseUrl: request.externalRestApiBaseUrl,
rpcProxyBaseUrl,
appName: discovered.appName || request.appName,
})
})
}
/** Caller must hold the native auth/environment commit owner. */
private async applyRuntimeConfigDiscovery(discovery: RuntimeConfigDiscovery): Promise<void> {
this.pendingRuntimeConfigDiscovery = discovery
hydrateDesktopRuntimeConfig()
if (!this.runtimeConfigDiscoveryMatchesCurrentBinding(discovery)) {
if (this.pendingRuntimeConfigDiscovery === discovery) {
this.pendingRuntimeConfigDiscovery = null
}
return
}
if (!isDesktopRuntimeConfigured() || config.rpcProxyBaseUrl?.trim()) {
if (this.pendingRuntimeConfigDiscovery === discovery) {
this.pendingRuntimeConfigDiscovery = null
}
this.clearEffectiveRuntimeRpcEndpoint()
return
}
const restoreHasReservedEnvironment =
this.restoreSavedSessionInFlight !== null && this.restoreSavedSessionReservationStarted
if (this.sessionToken || this.me) {
this.setEffectiveRuntimeRpcEndpoint(discovery)
return
}
if (restoreHasReservedEnvironment && this.interactiveLoginAttempts === 0) {
return
}
const previousEnvKey = getActiveEnvKey()
await saveDesktopRuntimeConfig({
// Discovery only enriches the selected profile. Commit it while signed
// out so the next auth boundary owns token and chat migration.
externalRestApiBaseUrl: discovery.externalRestApiBaseUrl,
rpcProxyBaseUrl: discovery.rpcProxyBaseUrl,
appName: discovery.appName,
})
if (getActiveEnvKey() !== previousEnvKey) this.rpcTokenManager.clear()
if (this.pendingRuntimeConfigDiscovery === discovery) {
this.pendingRuntimeConfigDiscovery = null
}
this.clearEffectiveRuntimeRpcEndpoint()
}
/** Caller must hold the native auth/environment commit owner. */
private async commitPendingRuntimeConfigDiscoveryIfSafe(): Promise<void> {
const pending = this.pendingRuntimeConfigDiscovery
if (pending) await this.applyRuntimeConfigDiscovery(pending)
}
async getDesktopReleaseStatus(): Promise<DesktopReleaseStatus> {
const { app } = await import('electron')
const currentVersion = resolveDesktopAppVersion(app)
const token = this.requireSessionToken()
const policy = await this.authClient.getDesktopReleasePolicy(token)
const updateRequired = compareSemverLike(currentVersion, policy.minimumDesktopVersion) < 0
return {
checked: true,
currentVersion,
latestVersion: policy.desktopVersion,
minimumVersion: policy.minimumDesktopVersion,
updateRequired,
releaseUrl: policy.releaseUrl,
releaseId: policy.releaseId,
releaseTag: policy.releaseTag,
externalRestApiVersion: policy.externalRestApiVersion,
rpcProxyVersion: policy.rpcProxyVersion,
}
}
async getDesktopAppInfo(): Promise<DesktopAppInfo> {
const { app } = await import('electron')
return {
appName: config.appName || 'Evenfire',
version: resolveDesktopAppVersion(app),
isPackaged: Boolean(app.isPackaged),
}
}
async openDesktopRelease(releaseUrl: string): Promise<{ opened: true }> {
const target = String(releaseUrl || '').trim()
if (!/^https?:\/\//i.test(target)) throw new Error('releaseUrl must be http(s)')
const { shell } = await import('electron')
await shell.openExternal(target)
return { opened: true }
}
async logout(): Promise<number> {
return this.withNativeAuthEnvironmentCommit(async () => {
this.sessionGeneration += 1
const logoutGeneration = this.sessionGeneration
const logoutToken = this.sessionToken
const logoutMe = this.me
const releasePrewarm = this.beginPrewarmAuthTransition()
try {
const envKey = getActiveEnvKey()
const legacyEnvKeys = getActiveLegacyEnvKeys()
await this.suspendDesktopGfsUploadsForAuthBoundary()
this.assertSessionGeneration(logoutGeneration)
try {
await this.tokenStore.clearSessionToken(envKey, { legacyEnvKeys })
this.assertSessionGeneration(logoutGeneration)
} catch (error) {
if (logoutToken && logoutMe) this.activateGfsAuthScope()
throw error
}
this.clearAuthenticatedSessionState()
await this.commitPendingRuntimeConfigDiscoveryIfSafe().catch(() => undefined)
// Grants survive logout (they are keyed by userId), but every cached SDK
// result must not: the next user of this machine gets nothing of this one's.
tryGetPluginSdkRuntime()?.notifySessionChanged(false)
return this.sessionGeneration
} finally {
releasePrewarm()
}
})
}
/** Resolve a gfs:// URI to its current resource via the API (no local mirror). */
async resolveGfsUri(uri: string) {
return this.gfsClient.resolveUri(uri, this.requireSessionToken())
}
/**
* Resolve then download a gfs:// resource's bytes through the brokered proxy.
* `maxBytes` bounds the download for the preview path (rejected before an
* oversized payload materializes); omitting it (save-to-disk, plugin SDK)
* reads the full body.
*/
async downloadGfsUri(uri: string, maxBytes?: number, signal?: AbortSignal) {
return this.gfsClient.download(
uri,
this.requireSessionToken(),
maxBytes !== undefined || signal !== undefined ? { maxBytes, signal } : undefined
)
}
/**
* Resolve then STREAM a gfs:// resource's bytes into `onChunk` (R1-H2).
*
* The folder-zip walk uses this instead of `downloadGfsUri`: the payload is
* written straight into the ZIP temp file chunk by chunk, so neither the
* main process nor the renderer ever holds a whole file in memory. The
* ceiling is enforced producer-side, mid-stream.
*/
async downloadGfsUriInto(
uri: string,
maxBytes: number,
signal: AbortSignal | undefined,
onChunk: (chunk: Uint8Array) => Promise<void>
) {
return this.gfsClient.downloadInto(
uri,
this.requireSessionToken(),
signal ? { maxBytes, signal } : { maxBytes },
onChunk
)
}
/** List a gfs directory's children (deny-by-default: only what the user is granted). */
async listGfsChildren(resourceId: string, drive?: string, cursor?: string, signal?: AbortSignal) {
return this.gfsClient.listChildren(resourceId, this.requireSessionToken(), {
drive,
cursor,
signal,
})
}
/** List explicit gfs resources the current user can read through grants or shares. */
async listAccessibleGfsResources(drive?: string, cursor?: string) {
return this.gfsClient.listAccessible(this.requireSessionToken(), { drive, cursor })
}
/**
* Compute the delegation affordances the renderer should SHOW on a resource.
* The held bits come from the server (the authority); `delegationAffordances`
* (the existing pure lib) maps them to {canDelegate, grantableBits,
* canCreateShare}. Enforcement is always server-side — this only hides controls.
*/
async gfsAffordances(resourceId: string, drive?: string): Promise<DelegationAffordances> {
const { held, isOperator } = await this.gfsClient.affordances(
resourceId,
this.requireSessionToken(),
drive
)
return delegationAffordances(new Set(held), isOperator)
}
/**
* Delegate a grant to one or more subjects (each subjectKey → structured
* subject) in a single atomic bulk PUT. No-escalation is server-side.
* `inherit` is renderer-driven; omitting it defaults the wire body to
* `true` so a folder grant always covers the folder's contents (the
* historical `false` default is what produced unreadable children).
*/
async grantGfs(
resourceId: string,
subjectKeys: string[],
bits: string[],
drive?: string,
inherit?: boolean
) {
// One atomic bulk PUT for every selected subject (server caps at 100). Each
// key is parsed to its structured subject up front, so a single malformed
// key fails the whole call before any round-trip — never a partial write.
await this.gfsClient.grant(
{ resourceId, drive, subjects: subjectKeys.map(parseSubjectKey), permissions: bits, inherit },
this.requireSessionToken()
)
}
/**
* List a resource's ACL rows for the Manage modal. The row `id` is the revoke
* handle (the grant PUT response carries no ids). View-ACL = manage-ACL is
* enforced server-side; a caller without manage_acl gets the API's 403.
*/
async listGfsGrants(resourceId: string, drive?: string) {
return this.gfsClient.listGrants({ resourceId, drive }, this.requireSessionToken())
}
/** Revoke an ACL row by id (id learned from listGfsGrants). */
async revokeGfsGrant(grantId: string) {
await this.gfsClient.revokeGrant(grantId, this.requireSessionToken())
}
/** List direct URI shares on a resource for the combined access-management view. */
async listGfsShares(resourceId: string, drive?: string) {
return this.gfsClient.listShares({ resourceId, drive }, this.requireSessionToken())
}
/** Revoke a direct URI share by its server-issued row id. */
async revokeGfsShare(shareId: string) {
await this.gfsClient.revokeShare(shareId, this.requireSessionToken())
}
/**
* The caller's own agents with their canonical GFS host subjects — the grant
* targets for per-agent delegation. Served fresh from external-rest-api
* GET /me/agents on every call, NOT from the cached name-based AccessCatalog
* (which has no gfsSubject and would go stale across reconciliations).
*/
async listMyAgents(): Promise<AgentWithMcpServers[]> {
const result = await this.authClient.getMyAgents(this.requireSessionToken())
return Array.isArray(result.agents) ? result.agents : []
}
/**
* Create a read share for a subject. A "share" grants read access (the minimal
* shared capability); the no-escalation engine still requires the caller hold
* read + share. includeDescendants so a folder share covers its subtree.
*/
async createGfsShare(resourceId: string, subjectKeys: string[], drive?: string) {
await this.gfsClient.createShare(
{
resourceId,
drive,
subjects: subjectKeys.map(parseSubjectKey),
permissions: ['read'],
includeDescendants: true,
},
this.requireSessionToken()
)
}
async createGfsFolder(parentResourceId: string, name: string, drive?: string) {
return this.gfsClient.createResource(
{ parentResourceId, drive, name, kind: 'directory' },
this.requireSessionToken()
)
}
async createGfsFile(parentResourceId: string, name: string, encodedData: string, drive?: string) {
return this.gfsClient.createResource(
{ parentResourceId, drive, name, kind: 'file', encodedData },
this.requireSessionToken()
)
}
private async desktopGfsUploadStatePath(): Promise<string> {
const { app } = await import('electron')
return path.join(app.getPath('userData'), DESKTOP_GFS_UPLOAD_STATE_FILE)
}
private enqueueDesktopGfsUploadState<T>(operation: () => Promise<T>): Promise<T> {
const result = this.gfsUploadStateQueue.then(operation, operation)
this.gfsUploadStateQueue = result.then(
() => undefined,
() => undefined
)
return result
}
private async loadDesktopGfsUploadState(): Promise<{
state: DesktopGfsUploadStateFile
migrated: boolean
}> {
try {
const raw = await fs.promises.readFile(await this.desktopGfsUploadStatePath(), 'utf8')
const parsed = JSON.parse(raw) as unknown
return migrateDesktopGfsUploadState(parsed)
} catch (error) {
if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
return {
state: { version: DESKTOP_GFS_UPLOAD_STATE_VERSION, records: [], quarantined: [] },
migrated: false,
}
}
console.warn('[AppService] Could not read GFS upload state:', error)
return {
state: { version: DESKTOP_GFS_UPLOAD_STATE_VERSION, records: [], quarantined: [] },
migrated: false,
}
}
}
private async writeDesktopGfsUploadState(state: DesktopGfsUploadStateFile): Promise<void> {
const filePath = await this.desktopGfsUploadStatePath()
await fs.promises.mkdir(path.dirname(filePath), { recursive: true })
const temporaryPath = `${filePath}.${randomUUID()}.tmp`
const records = state.records
.filter(isPersistedDesktopGfsUpload)
.map(canonicalPersistedDesktopGfsUpload)
.slice(-100)
const quarantined = state.quarantined
.map(canonicalQuarantinedDesktopGfsUpload)
.filter((record): record is QuarantinedDesktopGfsUpload => record !== null)
.slice(-100)
await fs.promises.writeFile(
temporaryPath,
JSON.stringify({
version: DESKTOP_GFS_UPLOAD_STATE_VERSION,
records,
quarantined,
}),
{ mode: 0o600 }
)
await fs.promises.rename(temporaryPath, filePath)
}
private hasLiveDesktopGfsUpload(record: PersistedDesktopGfsUpload): boolean {
const active = this.gfsUploadJobs.get(record.uploadId)
if (active && sameDesktopGfsUploadScope(active.scope, record.scope)) return true
return [...this.gfsPendingUploadJobs].some(entry => {
const pendingSession = entry.job.snapshot().session
return (
pendingSession?.uploadId === record.uploadId &&
sameDesktopGfsUploadScope(entry.scope, record.scope)
)
})
}
private async readDesktopGfsUploadState(): Promise<DesktopGfsUploadStateFile> {
return this.enqueueDesktopGfsUploadState(async () => {
const loaded = await this.loadDesktopGfsUploadState()
let suspendedOrphanedActive = false
const updatedAt = new Date().toISOString()
const state = {
...loaded.state,
records: loaded.state.records.map(record => {
if (record.status !== 'active' || this.hasLiveDesktopGfsUpload(record)) return record
suspendedOrphanedActive = true
return { ...record, status: 'suspended_auth' as const, updatedAt }
}),
}
if (loaded.migrated || suspendedOrphanedActive) {
await this.writeDesktopGfsUploadState(state)
}
return state
})
}
private async updateDesktopGfsUploadState(
update: (state: DesktopGfsUploadStateFile) => DesktopGfsUploadStateFile
): Promise<void> {
await this.enqueueDesktopGfsUploadState(async () => {
const loaded = await this.loadDesktopGfsUploadState()
await this.writeDesktopGfsUploadState(update(loaded.state))
})
}
private async migrateLegacyDesktopGfsUploadScopes(
identity: DesktopGfsUploadIdentity,
legacyEnvKeys: readonly string[]
): Promise<void> {
const sourceEnvKeys = new Set(
legacyEnvKeys
.map(key => String(key || '').trim())
.filter(key => key && key !== identity.environmentKey)
)
if (!sourceEnvKeys.size) return
await this.enqueueDesktopGfsUploadState(async () => {
const loaded = await this.loadDesktopGfsUploadState()
const updatedAt = new Date().toISOString()
let changed = false
const records = loaded.state.records.map(record => {
if (
!sourceEnvKeys.has(record.scope.environmentKey) ||
record.scope.ownerId !== identity.ownerId ||
record.scope.teamId !== identity.teamId ||
record.scope.baseUrl !== identity.baseUrl ||
this.hasLiveDesktopGfsUpload(record)
) {
return record
}
changed = true
return {
...record,
scope: {
...record.scope,
environmentKey: identity.environmentKey,
authEpoch: this.gfsAuthEpoch,
},
status: record.status === 'active' ? ('suspended_auth' as const) : record.status,
updatedAt,
}
})
if (changed || loaded.migrated) {
await this.writeDesktopGfsUploadState({ ...loaded.state, records })
}
})
}
private async persistDesktopGfsUpload(record: PersistedDesktopGfsUpload): Promise<void> {
if (!isPersistedDesktopGfsUpload(record)) {
throw new Error('Refusing to persist an invalid GFS upload record')
}
const canonicalRecord = canonicalPersistedDesktopGfsUpload(record)
await this.updateDesktopGfsUploadState(state => ({
...state,
records: [
...state.records.filter(item => item.uploadId !== canonicalRecord.uploadId),
canonicalRecord,
].slice(-100),
}))
}
private async clearDesktopGfsUpload(uploadId: string): Promise<void> {
await this.updateDesktopGfsUploadState(state => ({
...state,
records: state.records.filter(item => item.uploadId !== uploadId),
}))
}
private async runScopedLegacyGfsUpload<T>(
scope: DesktopGfsUploadScope,
operation: (token: string, signal: AbortSignal) => Promise<T>
): Promise<T> {
const controller = new AbortController()
const pending = { controller, promise: Promise.resolve() as Promise<unknown> }
this.gfsPendingLegacyUploads.add(pending)
const promise = (async () => {
this.assertCurrentDesktopGfsUploadScope(scope)
const result = await operation(this.requireSessionToken(), controller.signal)
this.assertCurrentDesktopGfsUploadScope(scope)
return result
})()
pending.promise = promise
try {
return await promise
} finally {
this.gfsPendingLegacyUploads.delete(pending)
}
}
private async startDesktopGfsUpload(
input: Omit<
DesktopUploadInput,
'transport' | 'token' | 'baseUrl' | 'onPersist' | 'onClearPersisted' | 'assertAuthEpoch'
> & { resumeUploadId?: string }
): Promise<DesktopUploadSession> {
const scope = this.currentDesktopGfsUploadScope(input.drive)
const token = this.requireSessionToken()
let scopedInput = { ...input, drive: scope.drive }
if (input.resumeUploadId) {
const state = await this.readDesktopGfsUploadState()
const record = state.records.find(item => item.uploadId === input.resumeUploadId)
if (!record || !sameDesktopGfsUploadScope(record.scope, scope, { includeAuthEpoch: false })) {
throw new Error('GFS upload session is not available in the active security scope')
}
if (
record.filePath !== input.filePath ||
record.name !== input.name ||
record.target.operation !== input.operation ||
record.target.parentRid !== input.parentRid ||
record.target.resourceRid !== input.resourceRid ||
record.target.ifMatch !== input.ifMatch ||
record.session.drive !== scope.drive
) {
throw new Error('GFS upload resume metadata does not match the persisted scoped record')
}
scopedInput = {
...scopedInput,
filePath: record.filePath,
name: record.name,
operation: record.target.operation,
parentRid: record.target.parentRid,
resourceRid: record.target.resourceRid,
ifMatch: record.target.ifMatch,
}
}
const job = new DesktopGfsUploadJob({
...scopedInput,
baseUrl: scope.baseUrl,
token,
transport: gfsUploadTransport,
assertAuthEpoch: () => this.assertCurrentDesktopGfsUploadScope(scope),
onPersist: record =>
this.persistDesktopGfsUpload({
...record,
version: DESKTOP_GFS_UPLOAD_STATE_VERSION,
scope,
status: record.session.state === 'paused' ? 'paused' : 'active',
updatedAt: new Date().toISOString(),
}),
onClearPersisted: uploadId => this.clearDesktopGfsUpload(uploadId),
})
const promise = job.start()
// Capability/auth failures can reject before a resumable session exists.
// Observe that early rejection immediately; once a session exists, the
// lifecycle observer below records the durable failed state as usual.
void promise.catch(() => undefined)
const pending = { job, promise, scope }
this.gfsPendingUploadJobs.add(pending)
let session: DesktopUploadSession
try {
session = await job.waitForSession()
} finally {
this.gfsPendingUploadJobs.delete(pending)
}
this.assertCurrentDesktopGfsUploadScope(scope)
if (session.drive !== scope.drive)
throw new Error('upload_drive_mismatch: session does not match the active drive')
this.gfsUploadJobs.set(session.uploadId, { job, promise, scope })
void promise
.then(
() => undefined,
async error => {
const message = String(error instanceof Error ? error.message : error)
if (!message.startsWith('stale_auth_epoch:')) {
await this.updateDesktopGfsUploadState(state => ({
...state,
records: state.records.map(record =>
record.uploadId === session.uploadId &&
sameDesktopGfsUploadScope(record.scope, scope)
? { ...record, status: 'failed' as const, updatedAt: new Date().toISOString() }
: record
),
}))
console.warn('[AppService] GFS upload job failed:', error)
}
if (this.gfsUploadJobs.get(session.uploadId)?.job === job) {
this.gfsUploadJobs.delete(session.uploadId)
}
}
)
.catch(error => console.warn('[AppService] Could not persist GFS upload failure:', error))
return session
}
async startGfsFileUpload(
parentResourceId: string,
name: string,
filePath: string,
drive?: string,
resumeUploadId?: string
): Promise<DesktopUploadSession> {
const canonicalDrive = normalizeDesktopUploadDrive(drive)
const scope = this.currentDesktopGfsUploadScope(canonicalDrive)
try {
return await this.startDesktopGfsUpload({
filePath,
name,
drive: canonicalDrive,
operation: 'create',
parentRid: parentResourceId,
resumeUploadId,
})
} catch (error) {
// A legacy fallback is valid only for a fresh upload. An explicit resume
// must remain a v2 operation so a missing capability cannot silently turn
// a persisted session into a second non-resumable resource.
if (
!(error instanceof DesktopUploadCapabilityError) ||
!error.allowLegacyFallback ||
resumeUploadId
)
throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
return this.gfsClient.createResource(
{ parentResourceId, drive: canonicalDrive, name, kind: 'file', encodedData },
token,
signal
)
})
return legacyReceipt(resource, 'create')
}
}
async startGfsFileReplace(
resourceId: string,
filePath: string,
drive?: string,
ifMatch?: number,
resumeUploadId?: string
): Promise<DesktopUploadSession> {
const canonicalDrive = normalizeDesktopUploadDrive(drive)
const scope = this.currentDesktopGfsUploadScope(canonicalDrive)
try {
return await this.startDesktopGfsUpload({
filePath,
name: resourceId,
drive: canonicalDrive,
operation: 'replace',
resourceRid: resourceId,
ifMatch,
resumeUploadId,
})
} catch (error) {
if (
!(error instanceof DesktopUploadCapabilityError) ||
!error.allowLegacyFallback ||
resumeUploadId
)
throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
return this.gfsClient.replaceFile(
{ resourceId, drive: canonicalDrive, ifMatch, encodedData },
token,
signal
)
})
return legacyReceipt(resource, 'replace')
}
}
async getGfsUploadSnapshot(uploadId: string, drive?: string) {
const entry = this.gfsUploadJobs.get(uploadId)
// Snapshot is read-only and an existing job already owns its captured
// token/scope. It must remain observable during a finite internal team hop;
// only a brand-new user-facing dispatch is fenced by that hop.
const scope = this.currentDesktopGfsUploadScope(drive, { allowTransientTeamHop: true })
if (entry && sameDesktopGfsUploadScope(entry.scope, scope)) return entry.job.snapshot()
const state = await this.readDesktopGfsUploadState()
const record = state.records.find(
item =>
item.uploadId === uploadId &&
sameDesktopGfsUploadScope(item.scope, scope, { includeAuthEpoch: false })
)
if (!record) return null
return {
// `active` is the persistence marker for a process-owned upload. The
// renderer contract describes the same resumable state as `uploading`;
// never leak the storage-only marker across the IPC boundary after a
// restart.
state: record.status === 'active' ? 'uploading' : record.status,
session: record.session,
uploadedBytes: record.session.committedBytes,
totalBytes: record.fileSize,
}
}
async pauseGfsUpload(uploadId: string, drive?: string): Promise<DesktopUploadSession> {
const entry = this.gfsUploadJobs.get(uploadId)
const scope = this.currentDesktopGfsUploadScope(drive, {
allowTransientTeamHop: Boolean(entry),
})
if (!entry || !sameDesktopGfsUploadScope(entry.scope, scope))
throw new Error('GFS upload is not active in the current security scope')
const session = await entry.job.pause()
await this.updateDesktopGfsUploadState(state => ({
...state,
records: state.records.map(record =>
record.uploadId === uploadId && sameDesktopGfsUploadScope(record.scope, scope)
? { ...record, session, status: 'paused' as const, updatedAt: new Date().toISOString() }
: record
),
}))
return session
}
async resumeGfsUpload(uploadId: string, drive?: string): Promise<DesktopUploadSession> {
const entry = this.gfsUploadJobs.get(uploadId)
const scope = this.currentDesktopGfsUploadScope(drive, {
allowTransientTeamHop: Boolean(entry),
})
if (entry) {
if (!sameDesktopGfsUploadScope(entry.scope, scope))
throw new Error('GFS upload is not active in the current security scope')
return entry.job.resume()
}
const state = await this.readDesktopGfsUploadState()
const record = state.records.find(
item =>
item.uploadId === uploadId &&
sameDesktopGfsUploadScope(item.scope, scope, { includeAuthEpoch: false })
)
if (!record) throw new Error('GFS upload session is not available in the active security scope')
if (!['suspended_auth', 'paused', 'failed'].includes(record.status)) {
throw new Error(`GFS upload cannot be explicitly resumed from ${record.status}`)
}
return this.startDesktopGfsUpload({
filePath: record.filePath,
name: record.name,
drive: record.scope.drive,
operation: record.target.operation,
parentRid: record.target.parentRid,
resourceRid: record.target.resourceRid,
ifMatch: record.target.ifMatch,
resumeUploadId: record.uploadId,
})
}
async cancelGfsUpload(uploadId: string, drive?: string): Promise<void> {
const entry = this.gfsUploadJobs.get(uploadId)
const scope = this.currentDesktopGfsUploadScope(drive, {
allowTransientTeamHop: Boolean(entry),
})
if (entry) {
if (!sameDesktopGfsUploadScope(entry.scope, scope))
throw new Error('GFS upload is not active in the current security scope')
await entry.job.cancel()
this.gfsUploadJobs.delete(uploadId)
return
}
const state = await this.readDesktopGfsUploadState()
const record = state.records.find(
item =>
item.uploadId === uploadId &&
sameDesktopGfsUploadScope(item.scope, scope, { includeAuthEpoch: false })
)
if (!record) throw new Error('GFS upload session is not available in the active security scope')
const url = new URL(
`/api/v1/me/gfs/uploads/${encodeURIComponent(uploadId)}`,
`${scope.baseUrl}/`
)
url.searchParams.set('drive', scope.drive)
await gfsUploadTransport.requestJson('DELETE', url.toString(), {
token: this.requireSessionToken(),
timeoutMs: 10 * 60 * 1000,
})
this.assertCurrentDesktopGfsUploadScope(scope)
await this.clearDesktopGfsUpload(uploadId)
}
async listGfsUploadSessions(drive?: string): Promise<DesktopGfsUploadSummary[]> {
// Listing persisted state is read-only and must remain available while a
// finite internal team hop temporarily borrows another team's token.
const scope = this.currentDesktopGfsUploadScope(drive, { allowTransientTeamHop: true })
const state = await this.readDesktopGfsUploadState()
return state.records
.filter(record => sameDesktopGfsUploadScope(record.scope, scope, { includeAuthEpoch: false }))
.map(record => ({
uploadId: record.uploadId,
fileName: record.fileName,
fileSize: record.fileSize,
target: record.target,
name: record.name,
drive: record.scope.drive,
status: record.status,
}))
}
async createGfsFileFromPath(
parentResourceId: string,
name: string,
filePath: string,
drive?: string
): Promise<DesktopUploadSession> {
const canonicalDrive = normalizeDesktopUploadDrive(drive)
const scope = this.currentDesktopGfsUploadScope(canonicalDrive)
try {
const session = await this.startDesktopGfsUpload({
filePath,
name,
drive: canonicalDrive,
operation: 'create',
parentRid: parentResourceId,
})
this.assertCurrentDesktopGfsUploadScope(scope)
const entry = this.gfsUploadJobs.get(session.uploadId)
if (!entry || !sameDesktopGfsUploadScope(entry.scope, scope)) {
throw new Error('stale_auth_epoch: GFS upload left the active security scope')
}
return await entry.promise
} catch (error) {
if (!(error instanceof DesktopUploadCapabilityError) || !error.allowLegacyFallback)
throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
return this.gfsClient.createResource(
{ parentResourceId, drive: canonicalDrive, name, kind: 'file', encodedData },
token,
signal
)
})
return legacyReceipt(resource, 'create')
}
}
async replaceGfsFile(resourceId: string, encodedData: string, drive?: string, ifMatch?: number) {
return this.gfsClient.replaceFile(
{ resourceId, drive, encodedData, ifMatch },
this.requireSessionToken()
)
}
async replaceGfsFileFromPath(
resourceId: string,
filePath: string,
drive?: string,
ifMatch?: number
): Promise<DesktopUploadSession> {
const canonicalDrive = normalizeDesktopUploadDrive(drive)
const scope = this.currentDesktopGfsUploadScope(canonicalDrive)
try {
const session = await this.startDesktopGfsUpload({
filePath,
name: resourceId,
drive: canonicalDrive,
operation: 'replace',
resourceRid: resourceId,
ifMatch,
})
this.assertCurrentDesktopGfsUploadScope(scope)
const entry = this.gfsUploadJobs.get(session.uploadId)
if (!entry || !sameDesktopGfsUploadScope(entry.scope, scope)) {
throw new Error('stale_auth_epoch: GFS upload left the active security scope')
}
return await entry.promise
} catch (error) {
if (!(error instanceof DesktopUploadCapabilityError) || !error.allowLegacyFallback)
throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
return this.gfsClient.replaceFile(
{ resourceId, drive: canonicalDrive, ifMatch, encodedData },
token,
signal
)
})
return legacyReceipt(resource, 'replace')
}
}
async renameGfsResource(resourceId: string, newName: string, drive?: string, ifMatch?: number) {
return this.gfsClient.renameResource(
{ resourceId, drive, newName, ifMatch },
this.requireSessionToken()
)
}
/**
* Move a resource into a destination folder (PATCH newParentId). Move
* authority is parent-relative (write+delete on the old parent, write on the
* destination) and is enforced server-side; ifMatch pins the resource version.
* An optional newName performs a combined rename+move in the same PATCH.
*/
async moveGfsResource(
resourceId: string,
destinationId: string,
drive?: string,
ifMatch?: number,
newName?: string
) {
return this.gfsClient.moveResource(
{ resourceId, drive, destinationId, ifMatch, ...(newName !== undefined ? { newName } : {}) },
this.requireSessionToken()
)
}
async deleteGfsResource(resourceId: string, drive?: string, ifMatch?: number) {
return this.gfsClient.deleteResource({ resourceId, drive, ifMatch }, this.requireSessionToken())
}
private requireSessionToken(): string {
if (!this.sessionToken) {
throw new Error('Not authenticated')
}
return this.sessionToken
}
async getSessionState(): Promise<SessionState> {
if (!this.sessionToken || !this.me) {
if (this.restoreSavedSessionInFlight) return this.restoreSavedSession()
// createWindow() already performs the saved-token restore before showing
// the renderer. Do not immediately repeat a failed 60-second network
// attempt from the renderer bootstrap; a new app launch or environment
// selection gets a fresh attempt because its service/env key is new.
if (
this.savedSessionRestoreAttemptedEnvKey === getActiveEnvKey() &&
Date.now() - this.savedSessionRestoreAttemptedAtMs < SAVED_SESSION_RESTORE_RETRY_DELAY_MS
) {
return { authenticated: false, me: null }
}
return this.restoreSavedSession()
}
return { authenticated: true, me: this.me }
}
/**
* Synchronous read of the cached session user id. The plugin SDK broker needs
* the current user to key grants and audit lines on every request, and it
* cannot await mid-decision without opening a window where a logout races the
* consent check. Returns null whenever there is no live session.
*/
getCachedUserId(): string | null {
if (!this.sessionToken || !this.me) return null
return this.me.id
}
async listTeams(): Promise<{ currentTeamId: string; items: TeamSummary[] }> {
const token = this.requireSessionToken()
return this.authClient.listTeams(token)
}
async listTeamMembers(): Promise<TeamMember[]> {
const token = this.requireSessionToken()
const result = await this.authClient.getTeamMembers(token)
return Array.isArray(result.items) ? result.items : []
}
async listPendingWorkflowApprovals(limit = 20): Promise<PendingWorkflowApproval[]> {
const token = this.requireSessionToken()
try {
const listed = await this.authClient.listTeams(token)
const teams = Array.isArray(listed.items) ? listed.items : []
if (!teams.length) {
const result = await this.authClient.listPendingWorkflowApprovals(token, limit)
const items = Array.isArray(result.items) ? result.items : []
this.rememberWorkflowApprovalTeams(items)
return items
}
const allApprovals: PendingWorkflowApproval[] = []
const seen = new Set<string>()
for (const team of teams) {
const teamId = String(team.id || '').trim()
if (!teamId) continue
try {
const result = await this.runWithTeamContext(teamId, teamToken =>
this.authClient.listPendingWorkflowApprovals(teamToken, limit)
)
const items = Array.isArray(result.items) ? result.items : []
for (const approval of items) {
if (seen.has(approval.id)) continue
seen.add(approval.id)
allApprovals.push(approval)
}
} catch (error) {
console.warn(`[AppService] Failed loading approvals for team ${teamId}:`, error)
}
}
allApprovals.sort(
(left, right) =>
new Date(right.requestedAt).getTime() - new Date(left.requestedAt).getTime()
)
const items = allApprovals.slice(0, limit)
this.rememberWorkflowApprovalTeams(items)
return items
} catch {
const result = await this.authClient.listPendingWorkflowApprovals(token, limit)
const items = Array.isArray(result.items) ? result.items : []
this.rememberWorkflowApprovalTeams(items)
return items
}
}
async acknowledgeNotificationDelivery(
notificationId: string
): Promise<{ ok: boolean; status: string }> {
const token = this.requireSessionToken()
return this.authClient.acknowledgeNotificationDelivery(token, notificationId)
}
async getNotificationPreferences(): Promise<UserNotificationPreferences> {
const token = this.requireSessionToken()
return this.authClient.getNotificationPreferences(token)
}
async getExternalChannelsSummary(): Promise<ExternalChannelsSummary> {
const token = this.requireSessionToken()
const [targetsResponse, accountsResponse] = await Promise.all([
this.authClient.listExternalChannelTargets(token),
this.authClient.listExternalChannelAccounts(token),
])
return {
targets: Array.isArray(targetsResponse.items) ? targetsResponse.items : [],
accounts: Array.isArray(accountsResponse.items) ? accountsResponse.items : [],
}
}
async updateNotificationPreferences(body: {
preferredMedium: 'telegram' | 'slack' | null
channelFallbackEnabled: boolean
}): Promise<UserNotificationPreferences> {
const token = this.requireSessionToken()
return this.authClient.updateNotificationPreferences(token, body)
}
async decideWorkflowApproval(
approvalId: string,
decision: 'approve' | 'deny',
note?: string,
options: { teamId?: string | null } = {}
): Promise<WorkflowApprovalDecisionResult> {
const targetTeamId =
String(options.teamId || '').trim() || this.workflowApprovalTeamById.get(approvalId) || null
const result = await this.runWithTeamContext(
targetTeamId,
token => this.authClient.decideWorkflowApproval(token, approvalId, decision, note),
{ mutation: true }
)
this.workflowApprovalTeamById.delete(approvalId)
return result
}
startEntityChangeStream(
streamId: string,
ownerId: number,
onEvent: (event: EntityChangeStreamEvent) => void
): void {
this.entityChangeSubscribers.set(streamId, { ownerId, onEvent })
this.ensureEntityChangeConnection()
}
private emitEntityChangeEvent(event: EntityChangeStreamEvent): void {
if ('cursor' in event) this.entityChangeCursor = event.cursor
for (const subscriber of Array.from(this.entityChangeSubscribers.values())) {
try {
subscriber.onEvent(event)
} catch {
// A destroyed renderer must not interrupt delivery to other windows.
}
}
}
private updateEntityChangeSessionToken(token: string | null): void {
if (this.entityChangeSessionToken === token) return
this.entityChangeSessionToken = token
this.entityChangeSessionGeneration += 1
}
private handleEntityChangeSessionExpiry(connectionGeneration: number): void {
const hasNewerCommittedSession =
this.entityChangeSessionGeneration > connectionGeneration &&
Boolean(this.entityChangeSessionToken)
if (hasNewerCommittedSession) {
this.restartEntityChangeStreamForSessionReplacement()
return
}
this.entityChangeConnectionStop?.({ silent: true })
if (this.gfsTransientTeamHopDepth > 0) {
this.entityChangeSessionExpiryDeferred = true
return
}
this.emitEntityChangeSessionExpired()
}
private emitEntityChangeSessionExpired(): void {
this.emitEntityChangeEvent({
type: 'stream.closing',
schemaVersion: 1,
cursor: this.entityChangeCursor ?? '00000000-0000-0000-0000-000000000000',
reason: 'session_expired',
})
// Keep renderer-owned subscriptions dormant so a newly committed session
// can rebind the stream without requiring a renderer remount. The expired
// connection itself is already stopped; logout and renderer teardown remove
// these owners through stopAllStreams/stopEntityChangeStreamsForOwner.
}
private ensureEntityChangeConnection(): void {
if (this.entityChangeEnvironmentSwitching) return
if (this.entityChangeConnectionStop || this.entityChangeSubscribers.size === 0) return
if (
!this.entityChangeSessionToken &&
this.sessionToken &&
this.gfsTransientTeamHopDepth === 0
) {
this.updateEntityChangeSessionToken(this.sessionToken)
}
if (!this.entityChangeSessionToken) return
let closed = false
let abortController: AbortController | null = null
let retryTimer: NodeJS.Timeout | null = null
let idleTimer: NodeJS.Timeout | null = null
let backoffMs = 1000
let serverRetryAfterMs: number | undefined
const clearRetry = () => {
if (retryTimer) clearTimeout(retryTimer)
retryTimer = null
}
const clearIdleTimer = () => {
if (idleTimer) clearTimeout(idleTimer)
idleTimer = null
}
const armIdleTimer = (attemptController: AbortController) => {
clearIdleTimer()
idleTimer = setTimeout(() => {
idleTimer = null
if (!closed && abortController === attemptController) attemptController.abort()
}, ENTITY_CHANGE_STREAM_IDLE_TIMEOUT_MS)
}
const stop = (opts?: { silent?: boolean }) => {
if (closed) return
closed = true
clearRetry()
clearIdleTimer()
abortController?.abort()
if (this.entityChangeConnectionStop === stop) this.entityChangeConnectionStop = null
if (!opts?.silent) this.emitEntityChangeEvent({ type: 'closed' })
}
this.entityChangeConnectionStop = stop
const connect = async () => {
if (closed) return
const connectionToken = this.entityChangeSessionToken
const connectionGeneration = this.entityChangeSessionGeneration
if (!connectionToken) return
const attemptController = new AbortController()
abortController = attemptController
armIdleTimer(attemptController)
try {
await this.authClient.openEntityChangeStream(
connectionToken,
this.entityChangeCursor,
event => {
if (closed) return
if (
event.type === 'heartbeat' ||
event.type === 'scope.invalidated' ||
event.type === 'resync_required' ||
event.type === 'stream.closing'
) {
armIdleTimer(attemptController)
// Transport-open is synthetic: it proves only that fetch
// returned headers. Reset retry pressure only after the server
// produces a validated schema-v1 frame.
backoffMs = 1000
}
if (event.type === 'stream.closing' && event.reason === 'session_expired') {
this.handleEntityChangeSessionExpiry(connectionGeneration)
return
}
this.emitEntityChangeEvent(event)
},
attemptController.signal
)
} catch (error) {
if (!closed) {
if (error instanceof ApiError && error.status === 401) {
this.handleEntityChangeSessionExpiry(connectionGeneration)
} else {
serverRetryAfterMs =
error instanceof ApiError
? parseEntityChangeRetryAfterMs(error.retryAfter)
: undefined
this.emitEntityChangeEvent({
type: 'error',
message: 'Live updates disconnected; reconnecting.',
})
}
}
} finally {
if (closed) return
clearIdleTimer()
clearRetry()
const localBackoffMs = backoffMs + Math.floor(Math.random() * Math.max(1, backoffMs * 0.2))
const delay = Math.max(localBackoffMs, serverRetryAfterMs ?? 0)
serverRetryAfterMs = undefined
backoffMs = Math.min(backoffMs * 2, 15_000)
retryTimer = setTimeout(() => void connect(), delay)
}
}
void connect()
}
private restartEntityChangeStreamForSessionReplacement(): void {
this.entityChangeSessionExpiryDeferred = false
this.entityChangeCursor = null
this.entityChangeConnectionStop?.({ silent: true })
this.ensureEntityChangeConnection()
}
stopEntityChangeStream(streamId: string, requesterOwnerId?: number): boolean {
const subscriber = this.entityChangeSubscribers.get(streamId)
if (!subscriber) return true
if (requesterOwnerId !== undefined && subscriber.ownerId !== requesterOwnerId) return false
this.entityChangeSubscribers.delete(streamId)
if (this.entityChangeSubscribers.size === 0) this.entityChangeConnectionStop?.({ silent: true })
return true
}
stopEntityChangeStreamsForOwner(ownerId: number): void {
for (const [streamId, subscriber] of this.entityChangeSubscribers) {
if (subscriber.ownerId === ownerId) this.entityChangeSubscribers.delete(streamId)
}
if (this.entityChangeSubscribers.size === 0) this.entityChangeConnectionStop?.({ silent: true })
}
startWorkflowNotificationStream(
streamId: string,
ownerId: number,
onEvent: (event: WorkflowNotificationStreamEvent) => void
): void {
const token = this.requireSessionToken()
let closed = false
let abortController: AbortController | null = null
let retryTimer: NodeJS.Timeout | null = null
let backoffMs = 1000
const clearRetry = () => {
if (retryTimer) {
clearTimeout(retryTimer)
retryTimer = null
}
}
const stop = (opts?: { silent?: boolean }) => {
if (closed) return
closed = true
clearRetry()
if (abortController) abortController.abort()
this.notificationStreams.delete(streamId)
// `silent` (bulk teardown on logout/team-switch) aborts without emitting the
// final `closed`: the renderer's own `releaseAll()`/reset tears its trackers
// down, so a fabricated `closed` here would only fire a spurious stream-loss
// terminal against a still-live tracker (R-F13). See `stopAllStreams`.
if (!opts?.silent) onEvent({ type: 'closed' })
}
this.notificationStreams.set(streamId, {
ownerId,
state: 'connecting',
approvalRequested: 0,
snapshot: 0,
updated: 0,
completed: 0,
stop,
})
const connect = async () => {
if (closed) return
let gracefulStreamClosing = false
abortController = new AbortController()
const entry = this.notificationStreams.get(streamId)
if (entry) entry.state = 'connecting'
try {
await this.authClient.openWorkflowNotificationStream(
token,
event => {
if (closed) return
if (event.type === 'open') {
backoffMs = 1000
const current = this.notificationStreams.get(streamId)
if (current) current.state = 'open'
}
if (event.type === 'stream.closing') {
gracefulStreamClosing = true
const current = this.notificationStreams.get(streamId)
if (current) current.state = 'connecting'
}
if (event.type === 'approval.requested') {
this.rememberWorkflowApprovalTeam(event.approval)
}
if (event.type === 'notification.snapshot') {
this.rememberWorkflowApprovalTeams(event.items)
}
const current = this.notificationStreams.get(streamId)
if (current && event.type === 'approval.requested') current.approvalRequested += 1
if (current && event.type === 'notification.snapshot') current.snapshot += 1
const eventType = (event as { type?: string }).type
if (current && event.type === 'approval.updated') current.updated += 1
if (current && eventType === 'workflow.run.completed') current.completed += 1
onEvent(event)
},
abortController.signal
)
if (!closed) {
const current = this.notificationStreams.get(streamId)
if (gracefulStreamClosing) {
if (current) current.state = 'connecting'
} else {
if (current) current.state = 'error'
onEvent({ type: 'error', message: 'Notification stream disconnected; reconnecting' })
}
}
} catch (error) {
if (closed) return
const current = this.notificationStreams.get(streamId)
if (current) current.state = 'error'
onEvent({
type: 'error',
message: error instanceof Error ? error.message : String(error),
})
} finally {
if (closed) return
clearRetry()
retryTimer = setTimeout(() => {
backoffMs = Math.min(backoffMs * 2, 15000)
void connect()
}, backoffMs)
}
}
void connect()
}
stopWorkflowNotificationStream(streamId: string, requesterOwnerId?: number): boolean {
const entry = this.notificationStreams.get(streamId)
if (!entry) return true
if (requesterOwnerId !== undefined && entry.ownerId !== requesterOwnerId) {
return false
}
entry.stop()
return true
}
stopWorkflowNotificationStreamsForOwner(ownerId: number): void {
const toStop: string[] = []
for (const [streamId, entry] of this.notificationStreams.entries()) {
if (entry.ownerId === ownerId) toStop.push(streamId)
}
for (const streamId of toStop) {
this.stopWorkflowNotificationStream(streamId)
}
}
/**
* Close EVERY live upstream SSE the app owns — progress (per task), activity
* (per agent), host status, and workflow notification streams — regardless of
* owner. Called on `logout()` and on a deliberate `switchTeam()` (spec-v2
* §4.5-3, R-F13 / GAP-N4 main half): the session/team those streams belong to
* is going away, so no late terminal/activity event may fire against a torn-down
* auth or team context, and no reconnect may re-mint a token for the old team.
* Uses the SILENT stop: each entry aborts its socket and deletes its map entry
* but does NOT emit the final `closed`. The renderer half (`releaseAll()` /
* `fsm.reset()` / `resetChat`) tears its own trackers down; a fabricated `closed`
* here would instead fire a spurious `source:'stream'` terminal against a
* still-live tracker (its release runs AFTER the `team.switch` IPC resolves),
* running post-teardown side effects — exactly the R-F13 bug this closes.
*/
private stopAllStreams(): void {
for (const entry of Array.from(this.progressStreams.values())) entry.stop({ silent: true })
for (const entry of Array.from(this.hostActivityStreams.values())) entry.stop({ silent: true })
for (const entry of Array.from(this.hostStatusStreams.values())) entry.stop({ silent: true })
for (const entry of Array.from(this.notificationStreams.values())) entry.stop({ silent: true })
this.entityChangeSubscribers.clear()
this.entityChangeSessionExpiryDeferred = false
this.entityChangeConnectionStop?.({ silent: true })
this.entityChangeCursor = null
}
getWorkflowNotificationStreamStatus(): {
active: number
open: number
connecting: number
error: number
approvalRequested: number
snapshot: number
updated: number
completed: number
} {
let open = 0
let connecting = 0
let error = 0
let approvalRequested = 0
let snapshot = 0
let updated = 0
let completed = 0
for (const stream of this.notificationStreams.values()) {
if (stream.state === 'open') open += 1
else if (stream.state === 'connecting') connecting += 1
else error += 1
approvalRequested += stream.approvalRequested
snapshot += stream.snapshot
updated += stream.updated
completed += stream.completed
}
return {
active: this.notificationStreams.size,
open,
connecting,
error,
approvalRequested,
snapshot,
updated,
completed,
}
}
async listWorkflows(): Promise<WorkflowRecipeListResult> {
const token = this.requireSessionToken()
try {
const listed = await this.authClient.listTeams(token)
const teams = Array.isArray(listed.items) ? listed.items : []
if (!teams.length) {
this.workflowTeamByKey.clear()
return this.authClient.listWorkflows(token)
}
const orderedTeams = [
...teams.filter(team => team.id === listed.currentTeamId),
...teams.filter(team => team.id !== listed.currentTeamId),
]
const items: WorkflowRecipeListResult['items'] = []
const seen = new Set<string>()
const nextWorkflowTeamByKey = new Map<string, string>()
for (const team of orderedTeams) {
const teamId = String(team.id || '').trim()
if (!teamId) continue
try {
const result = await this.runWithTeamContext(teamId, teamToken =>
this.authClient.listWorkflows(teamToken)
)
const teamItems = Array.isArray(result.items) ? result.items : []
for (const item of teamItems) {
const namespace = String(item.metadata?.namespace || '').trim()
const name = String(item.metadata?.name || '').trim()
if (!namespace || !name) continue
const key = this.workflowKey(namespace, name)
if (seen.has(key)) continue
seen.add(key)
nextWorkflowTeamByKey.set(key, teamId)
items.push(item)
}
} catch (error) {
console.warn(`[AppService] Failed loading workflows for team ${teamId}:`, error)
}
}
this.workflowTeamByKey.clear()
for (const [key, teamId] of nextWorkflowTeamByKey) {
this.workflowTeamByKey.set(key, teamId)
}
return { items, count: items.length }
} catch {
this.workflowTeamByKey.clear()
return this.authClient.listWorkflows(token)
}
}
async readWorkflow(ns: string, name: string): Promise<unknown> {
const teamId = this.workflowTeamByKey.get(this.workflowKey(ns, name)) || null
return this.runWithTeamContext(teamId, token => this.authClient.readWorkflow(token, ns, name))
}
async getWorkflowHealth(ns: string, name: string): Promise<unknown> {
const teamId = this.workflowTeamByKey.get(this.workflowKey(ns, name)) || null
return this.runWithTeamContext(teamId, token =>
this.authClient.getWorkflowHealth(token, ns, name)
)
}
async triggerWorkflow(
ns: string,
name: string,
inputs?: Record<string, unknown>,
idempotencyKey?: string
): Promise<unknown> {
const body: Record<string, unknown> = {}
if (inputs) body.inputs = inputs
const teamId = this.workflowTeamByKey.get(this.workflowKey(ns, name)) || null
return this.runWithTeamContext(
teamId,
token => this.authClient.triggerWorkflow(token, ns, name, body, idempotencyKey),
{ mutation: true }
)
}
async listWorkflowRuns(ns: string, name: string, limit?: number): Promise<unknown> {
const teamId = this.workflowTeamByKey.get(this.workflowKey(ns, name)) || null
return this.runWithTeamContext(teamId, token =>
this.authClient.listWorkflowRuns(token, ns, name, limit)
)
}
async getInitialTeamsDirectory(): Promise<TeamDirectoryResult> {
const sessionToken = this.requireSessionToken()
const result = await this.authClient.getInitialTeamDirectory(sessionToken)
this.teamDirectoryCache = result
return result
}
async listWorkflowRunArtifacts(
ns: string,
name: string,
runId: string
): Promise<WorkflowRunArtifactsResult> {
const teamId = this.workflowTeamByKey.get(this.workflowKey(ns, name)) || null
return this.runWithTeamContext(teamId, token =>
this.authClient.listWorkflowRunArtifacts(token, ns, name, runId)
)
}
async downloadWorkflowRunArtifact(
ns: string,
name: string,
runId: string,
artifactName: string
): Promise<Buffer> {
const teamId = this.workflowTeamByKey.get(this.workflowKey(ns, name)) || null
return this.runWithTeamContext(teamId, token =>
this.authClient.downloadWorkflowRunArtifact(token, ns, name, runId, artifactName)
)
}
async getTeamsDirectory(): Promise<TeamDirectoryResult> {
return this.getInitialTeamsDirectory()
}
async switchTeam(teamId: string): Promise<SessionState> {
const targetTeamId = String(teamId || '').trim()
if (!targetTeamId) throw new Error('teamId is required')
// Explicit team changes fence opportunistic wake immediately. A failed
// switch can safely leave prewarm canceled; the message path remains live.
const releasePrewarm = this.beginPrewarmAuthTransition()
// Keep the new team token fenced until the old GFS jobs have been
// suspended. The native owner spans the entire deliberate transition so
// another team-context operation cannot commit between token installation
// and GFS activation.
const releaseTransientHop = this.enterGfsTransientTeamHop()
try {
return await this.withNativeAuthEnvironmentCommit(async () => {
const previousIdentity =
this.gfsScopeIdentity ?? (this.me ? desktopGfsUploadIdentity(this.me) : undefined)
// §4.5-3 (GAP-N4 main half): a deliberate team switch tears down every
// live stream — the old team's progress/activity/status/notification
// sockets must not survive it. The transition owns the commit slot until
// GFS activation and stream/cache publication complete. Transient
// runWithTeamContext hops continue to reuse their existing owner and do
// not suspend uploads or stop streams.
const switchedToken = await this.switchSessionToTeam(
targetTeamId,
this.requireSessionToken()
)
const switchedMe = this.me
if (this.sessionToken !== switchedToken || !switchedMe) {
throw new Error('stale_auth_epoch: authenticated team scope changed before activation')
}
// A deliberate user switch is the only team-context boundary that fences
// in-flight uploads. Transient runWithTeamContext hops intentionally use
// switchSessionToTeam directly and must leave those jobs untouched.
try {
await this.suspendDesktopGfsUploadsForAuthBoundary(previousIdentity)
} catch (error) {
// The replacement session is already installed at this point. If the
// auth-boundary state write fails, do not leave that token/me paired
// with a blocked or stale GFS scope. Cleanup remains inside the outer
// transient-hop gate, and the original persistence error is preserved.
this.clearAuthenticatedSessionState()
try {
await this.tokenStore.clearSessionToken(getActiveEnvKey(), {
legacyEnvKeys: getActiveLegacyEnvKeys(),
})
} catch {
// Preserve the original team-transition error when cleanup also fails.
}
throw error
}
this.activateGfsAuthScope()
this.updateEntityChangeSessionToken(this.sessionToken)
this.stopAllStreams()
// Grants are keyed by userId, not by team, so they carry over — but every
// cached org/agents/contexts answer is now about the wrong team. Drop the
// cache and tell mounted plugins to refetch.
tryGetPluginSdkRuntime()?.notifySessionChanged(true)
return { authenticated: true, me: this.me }
})
} finally {
releasePrewarm()
releaseTransientHop()
}
}
async refreshAccessCatalog(): Promise<AccessCatalog> {
this.rpcTokenManager.clear()
const token = this.requireSessionToken()
const me = this.me ?? (await this.authClient.getMe(token))
this.me = me
await this.bindCurrentChatStore(me.id)
const currentTeamId = String(me.teamId || '').trim()
const [userContexts, userAgents, teamContexts, teamAgents] = await Promise.all([
this.authClient.getMyContexts(token),
this.authClient.getMyAgents(token),
currentTeamId
? this.authClient.getTeamContexts(token)
: Promise.resolve({ teamId: '', contextIds: [] }),
currentTeamId
? this.authClient.getTeamAgents(token)
: Promise.resolve({ teamId: '', agentNames: [], agents: [] }),
])
const userContextIds = AppService.dedupe(userContexts.contextIds)
const teamContextIds = AppService.dedupe(teamContexts.contextIds)
const contextIds = AppService.dedupe([...userContextIds, ...teamContextIds])
const rawUserAgentNames = AppService.dedupe(userAgents.agentNames)
const rawTeamAgentNames = AppService.dedupe(teamAgents.agentNames)
const agentNames = AppService.dedupe([...rawUserAgentNames, ...rawTeamAgentNames])
const activeAgentNameSet = new Set(agentNames)
const userAgentNames = rawUserAgentNames.filter(agentName => activeAgentNameSet.has(agentName))
const teamAgentNames = rawTeamAgentNames.filter(agentName => activeAgentNameSet.has(agentName))
// Merge the optional per-agent MCP server lists from user + team responses.
// The agent→servers map is intentionally a narrow interface (names only) —
// no URLs or credentials are exposed on the session path.
const mcpServersByAgent: Record<string, string[]> = {}
const agentMcpServers: Record<string, Array<{ name: string }>> = {}
const contextMcpServers: Record<string, Array<{ name: string }>> = {}
const agentContextByName: Record<string, string | null> = {}
const agentProviderByName: Record<string, string | null> = {}
// Visible agent name (Agent CRD `spec.host`, arriving as the wire
// `displayName`) keyed by `metadata.name`. This is the single producer
// boundary for the desktop catalog: the `|| name` guard lives here only
// (mirroring control-api's accessReconciliation `configuredDisplayName ||
// name`), so renderer consumers read `agentDisplayByName[name]` directly
// without sprinkling `|| name`. Filled total over
// `agentNames` below so a lookup is never undefined.
const agentDisplayByName: Record<string, string> = {}
const upsertScopedServers = (
target: Record<string, Array<{ name: string }>>,
key: string,
names: string[]
) => {
const existing = target[key] ?? []
const mergedNames = AppService.dedupe([
...existing.map(entry => String(entry?.name || '').trim()),
...names,
])
target[key] = mergedNames.map(name => ({ name }))
}
const collectAgents = (
agents?: Array<{
name: string
displayName?: string | null
contextRef?: string | null
provider?: string | null
model?: { provider?: string | null } | null
mcpServers?: Array<{ name: string }>
}>
) => {
if (!Array.isArray(agents)) return
for (const a of agents) {
const agentName = String(a?.name || '').trim()
if (!agentName) continue
const displayNameCandidate = typeof a?.displayName === 'string' ? a.displayName.trim() : ''
if (
displayNameCandidate &&
!Object.prototype.hasOwnProperty.call(agentDisplayByName, agentName)
) {
agentDisplayByName[agentName] = displayNameCandidate
}
const contextRef =
typeof a?.contextRef === 'string' && a.contextRef.trim().length > 0
? a.contextRef.trim()
: null
if (
!Object.prototype.hasOwnProperty.call(agentContextByName, agentName) ||
agentContextByName[agentName] == null
) {
agentContextByName[agentName] = contextRef
}
const providerCandidate =
typeof a?.provider === 'string'
? a.provider.trim()
: typeof a?.model?.provider === 'string'
? a.model.provider.trim()
: ''
if (
providerCandidate &&
(!Object.prototype.hasOwnProperty.call(agentProviderByName, agentName) ||
agentProviderByName[agentName] == null)
) {
agentProviderByName[agentName] = providerCandidate
}
const existing = mcpServersByAgent[agentName] ?? []
const incoming = Array.isArray(a.mcpServers)
? a.mcpServers.map(s => String(s?.name || '').trim()).filter(Boolean)
: []
const merged = AppService.dedupe([...existing, ...incoming])
mcpServersByAgent[agentName] = merged
if (!merged.length) continue
upsertScopedServers(agentMcpServers, agentName, merged)
if (contextRef) {
upsertScopedServers(contextMcpServers, contextRef, merged)
}
}
}
const filterAgentDetails = (
agents?: Array<{
name: string
displayName?: string | null
contextRef?: string | null
provider?: string | null
model?: { provider?: string | null } | null
mcpServers?: Array<{ name: string }>
}>
) =>
Array.isArray(agents)
? agents.filter(agent => activeAgentNameSet.has(String(agent?.name || '').trim()))
: []
collectAgents(filterAgentDetails(userAgents.agents))
collectAgents(filterAgentDetails(teamAgents.agents))
for (const agentName of agentNames) {
if (!Object.prototype.hasOwnProperty.call(agentContextByName, agentName)) {
agentContextByName[agentName] = null
}
if (!Object.prototype.hasOwnProperty.call(agentProviderByName, agentName)) {
agentProviderByName[agentName] = null
}
// Producer-side `|| name` guard (the only one — see Decision #6): an agent
// whose wire entry carried no `displayName` (pre-display API build) falls
// back to its identifier here so consumers never render an empty label.
if (!Object.prototype.hasOwnProperty.call(agentDisplayByName, agentName)) {
agentDisplayByName[agentName] = agentName
}
}
const hasAgentScopedMcp = Object.keys(agentMcpServers).length > 0
const hasContextScopedMcp = Object.keys(contextMcpServers).length > 0
this.accessCatalog = {
userId: me.id,
teamId: currentTeamId || null,
userContextIds,
userAgentNames,
teamContextIds,
teamAgentNames,
contextIds,
agentNames,
mcpServersByAgent,
...(hasAgentScopedMcp ? { agentMcpServers } : {}),
...(hasContextScopedMcp ? { contextMcpServers } : {}),
agentContextByName,
agentProviderByName,
agentDisplayByName,
}
return this.accessCatalog
}
async listAccessibleMcpServers(hostRefs?: string[]): Promise<RpcAllowedServersResult> {
const token = this.requireSessionToken()
const effectiveHostRefs = AppService.dedupe(Array.isArray(hostRefs) ? hostRefs : [])
if (!effectiveHostRefs.length) {
const me = this.me ?? (await this.authClient.getMe(token))
this.me = me
return { userId: me.id, contextIds: [], servers: [] }
}
const rpc = await this.issueRpcTokenForHostRefs(MCP_SERVERS_LIST_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.listServers(rpc.token)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(
MCP_SERVERS_LIST_SCOPES,
effectiveHostRefs
)
return this.rpcClient.listServers(retried.token)
}
throw error
}
}
async getAccessCatalog(): Promise<AccessCatalog> {
// Access grants are mutable from Control UI. Always read the current
// external catalog so the desktop never serves removed agents/contexts from
// the main-process cache.
return this.refreshAccessCatalog()
}
async invokeHostMessage(
hostRef: string,
request: HostMessageRequest,
hostRefs?: string[],
options?: { async?: boolean }
): Promise<HostMessageResponse> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
// A malformed request is rejected before any token is issued for it.
if (request.attachments != null && !Array.isArray(request.attachments)) {
throw new Error('Attachments must be a list.')
}
if (request.fileReferences !== undefined && !Array.isArray(request.fileReferences)) {
throw new Error('File references must be a list.')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(
HOST_WAKEABLE_OPERATION_SCOPES,
effectiveHostRefs
)
const outgoingAttachmentCount = Array.isArray(request.attachments)
? request.attachments.length
: 0
if (outgoingAttachmentCount > 0) {
console.info(
`[AppService] invokeHostMessage host=${targetHostRef} attachments=${outgoingAttachmentCount}`
)
}
const contextualRequest: HostMessageRequest = {
content: request.content,
channelType: 'rpc',
channelId: targetHostRef,
hostRef: targetHostRef,
sender: this.me?.id,
metadata: this.me?.teamId ? { teamId: this.me.teamId } : {},
threadId: typeof request.threadId === 'string' ? request.threadId : undefined,
attachments: Array.isArray(request.attachments) ? request.attachments : undefined,
// Forward the optional piggybacked per-session model (R2 "Option A"). This
// build is a field allow-list, so an unlisted field would be dropped —
// thread `model` through explicitly. NOTE: rpc-proxy ALSO rebuilds the body
// as its own allow-list (routes/rpc.ts `forwardedBody`), so `model` must be
// forwarded there too — it does not pass the body through unchanged.
...(typeof request.model === 'string' && request.model ? { model: request.model } : {}),
...(request.modelSelectionRevision === undefined
? {}
: { modelSelectionRevision: request.modelSelectionRevision }),
// Structured references (#666): parsed at the IPC boundary; rpc-proxy
// forwards them and mcp-host resolves each one.
...(request.fileReferences === undefined ? {} : { fileReferences: request.fileReferences }),
}
try {
return await this.rpcClient.invokeHostMessage(
rpc.token,
targetHostRef,
contextualRequest,
options
)
} catch (error) {
const availabilityError = AppService.toHostAvailabilityError(targetHostRef, error)
if (availabilityError) throw availabilityError
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(
HOST_WAKEABLE_OPERATION_SCOPES,
effectiveHostRefs
)
try {
return await this.rpcClient.invokeHostMessage(
retried.token,
targetHostRef,
contextualRequest,
options
)
} catch (retryError) {
const retryAvailabilityError = AppService.toHostAvailabilityError(
targetHostRef,
retryError
)
if (retryAvailabilityError) throw retryAvailabilityError
throw retryError
}
}
throw error
}
}
async getTaskResult(
hostRef: string,
taskId: string,
hostRefs?: string[]
): Promise<HostMessageResponse> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
const targetTaskId = String(taskId || '').trim()
if (!targetTaskId) {
throw new Error('taskId is required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(
HOST_WAKEABLE_OPERATION_SCOPES,
effectiveHostRefs
)
try {
return await this.rpcClient.getTaskResult(rpc.token, targetHostRef, targetTaskId)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(
HOST_WAKEABLE_OPERATION_SCOPES,
effectiveHostRefs
)
return this.rpcClient.getTaskResult(retried.token, targetHostRef, targetTaskId)
}
throw error
}
}
async getHostStatus(hostRef: string, hostRefs?: string[]): Promise<HostRuntimeStatus> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_STATUS_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.getHostStatus(rpc.token, targetHostRef)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(HOST_STATUS_SCOPES, effectiveHostRefs)
return this.rpcClient.getHostStatus(retried.token, targetHostRef)
}
throw error
}
}
/**
* Fire-and-forget pre-warm of a (possibly suspended) stateless host.
*
* POSTs the rpc-proxy wake route with the same RPC token the app already
* uses for messages so the pod is Ready by the time the user types. Every
* response on the wake contract is terminal (200 active / 202
* wake-requested / 409 not-stateless) — no polling. A 202 means HCC has NOT
* acted yet and its raw watch can lose the single projected event, so a
* bounded background re-emission ({@link runPrewarmReemissionLoop}) re-POSTs
* while 202 persists — up to PREWARM_REEMIT_MAX_ATTEMPTS times, then gives
* up to the reactive message path. Failures are
* warn-logged here (hostRef + reason, never the token) and returned as a
* structured result instead of thrown, so the renderer's login/catalog path
* can never be blocked or broken by prewarm.
*
* MUST only be invoked from authenticated access-catalog paths — never from
* the host status stream lifecycle, whose ~300s token-TTL reconnects would
* resurrect a suspended host forever.
*/
async prewarmHost(hostRef: string, hostRefs?: string[]): Promise<PrewarmHostResult> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
if (this.prewarmAuthTransitionCount > 0) {
return { requested: false, skipped: 'auth-changed' }
}
const authEpoch = this.prewarmAuthEpoch
const now = Date.now()
const lastAttemptAt = this.prewarmAttemptAtByHostRef.get(targetHostRef)
if (lastAttemptAt !== undefined && now - lastAttemptAt < PREWARM_COOLDOWN_MS) {
return { requested: false, skipped: 'cooldown' }
}
if (this.prewarmReemitLoopHostRefs.has(targetHostRef)) {
// Structural backstop behind the cooldown gate: even if this host's
// cooldown entry was evicted from the bounded map, never run two
// re-emission loops for the same host at once.
return { requested: false, skipped: 'in-flight' }
}
this.prewarmAttemptAtByHostRef.delete(targetHostRef)
if (this.prewarmAttemptAtByHostRef.size >= PREWARM_COOLDOWN_MAX_HOSTS) {
const oldestHostRef = this.prewarmAttemptAtByHostRef.keys().next().value
if (oldestHostRef !== undefined) {
this.prewarmAttemptAtByHostRef.delete(oldestHostRef)
}
}
this.prewarmAttemptAtByHostRef.set(targetHostRef, now)
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
try {
const rpc = await this.issueRpcTokenForHostRefs(
HOST_WAKEABLE_OPERATION_SCOPES,
effectiveHostRefs
)
if (this.prewarmAuthEpoch !== authEpoch || this.prewarmAuthTransitionCount > 0) {
return { requested: false, skipped: 'auth-changed' }
}
const result = await this.rpcClient.prewarmHost(rpc.token, targetHostRef)
if (
result.status === 'wake-requested' &&
this.prewarmAuthEpoch === authEpoch &&
this.prewarmAuthTransitionCount === 0
) {
// HCC has not acted yet and its watch may have lost the event. Run
// the bounded background re-emission tied to THIS catalog-driven
// invocation — the renderer never awaits it, and the cooldown gate
// (checked above, not refreshed by re-emits) keeps it single-flight.
this.prewarmReemitLoopHostRefs.add(targetHostRef)
const controller = new AbortController()
this.prewarmReemitAbortControllers.set(targetHostRef, controller)
void this.runPrewarmReemissionLoop(targetHostRef, rpc.token, authEpoch, controller.signal)
}
return { requested: true, status: result.status }
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
console.warn(`[AppService] prewarmHost failed host=${targetHostRef}: ${message}`)
return { requested: false, error: message }
}
}
/** Injectable so tests stay deterministic; fake timers advance it. */
private prewarmReemitDelay = (ms: number, signal?: AbortSignal): Promise<void> =>
new Promise(resolve => {
if (signal?.aborted) {
resolve()
return
}
const timer = setTimeout(() => {
signal?.removeEventListener('abort', abort)
resolve()
}, ms)
const abort = () => {
clearTimeout(timer)
signal?.removeEventListener('abort', abort)
resolve()
}
signal?.addEventListener('abort', abort, { once: true })
})
/**
* Bounded background wake re-emission (see PREWARM_REEMIT_* constants).
* Re-POSTs the wake while the route keeps answering 202 wake-requested;
* stops immediately on 200 active (HCC acted), on any other status, on any
* error, or after the bounded attempts — then the reactive message path is
* the backstop. Runs at most once per hostRef (prewarmReemitLoopHostRefs)
* and never touches the cooldown map, so re-emits cannot extend or refresh
* the cooldown window. Deliberately NOT reachable from the host status
* stream lifecycle — the anti-flap invariant is unchanged.
*/
private async runPrewarmReemissionLoop(
hostRef: string,
rpcToken: string,
authEpoch: number,
signal: AbortSignal
): Promise<void> {
try {
for (let attempt = 1; attempt <= PREWARM_REEMIT_MAX_ATTEMPTS; attempt++) {
await this.prewarmReemitDelay(PREWARM_REEMIT_INTERVAL_MS, signal)
if (signal.aborted || this.prewarmAuthEpoch !== authEpoch) return
const result = await this.rpcClient.prewarmHost(rpcToken, hostRef)
console.info(
`[AppService] prewarmHost re-emit host=${hostRef} attempt=${attempt} status=${result.status}`
)
if (result.status !== 'wake-requested') {
return
}
}
console.warn(
`[AppService] prewarmHost re-emission gave up host=${hostRef} after ${PREWARM_REEMIT_MAX_ATTEMPTS} re-emits: wake still unacknowledged; the reactive message path will cover the user's message`
)
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
console.warn(`[AppService] prewarmHost re-emit failed host=${hostRef}: ${message}`)
} finally {
if (this.prewarmReemitAbortControllers.get(hostRef)?.signal === signal) {
this.prewarmReemitLoopHostRefs.delete(hostRef)
this.prewarmReemitAbortControllers.delete(hostRef)
}
}
}
async getHostActivity(
hostRef: string,
options?: { limit?: number; sinceEventId?: string; hostRefs?: string[] }
): Promise<HostActivitySnapshot> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
const effectiveHostRefs =
options?.hostRefs && options.hostRefs.length > 0 ? options.hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_ACTIVITY_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.getHostActivity(rpc.token, targetHostRef, {
limit: options?.limit,
sinceEventId: options?.sinceEventId,
})
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(HOST_ACTIVITY_SCOPES, effectiveHostRefs)
return this.rpcClient.getHostActivity(retried.token, targetHostRef, {
limit: options?.limit,
sinceEventId: options?.sinceEventId,
})
}
throw error
}
}
startHostStatusStream(
streamId: string,
ownerId: number,
hostRef: string,
hostRefs: string[] | undefined,
onEvent: (event: HostStatusStreamEvent) => void
): void {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
this.requireSessionToken()
let closed = false
let abortController: AbortController | null = null
let retryTimer: NodeJS.Timeout | null = null
let backoffMs = 1000
const clearRetry = () => {
if (retryTimer) {
clearTimeout(retryTimer)
retryTimer = null
}
}
const stop = (opts?: { silent?: boolean }) => {
if (closed) return
closed = true
clearRetry()
if (abortController) {
abortController.abort()
}
this.hostStatusStreams.delete(streamId)
// `silent`: bulk teardown skips the final `closed` (see `stopAllStreams`).
if (!opts?.silent) onEvent({ type: 'closed' })
}
const connect = async () => {
if (closed) return
abortController = new AbortController()
try {
const rpc = await this.issueRpcTokenForHostRefs(HOST_STATUS_SCOPES, effectiveHostRefs)
await this.rpcClient.openHostStatusStream(
rpc.token,
targetHostRef,
({ event, data }) => {
if (closed) return
if (event === 'open') {
backoffMs = 1000
const payload = data as { hostRef?: string; observedAt?: string }
onEvent({
type: 'open',
hostRef: String(payload?.hostRef || targetHostRef),
observedAt: String(payload?.observedAt || new Date().toISOString()),
})
return
}
if (event === 'status') {
backoffMs = 1000
const payload = data as HostRuntimeStatus
onEvent({ type: 'status', status: payload })
return
}
if (event === 'auth-expired') {
// Upstream rejected the captured RPC token (TTL is 300s; this
// is normal on long-lived sessions). Drop the cached token so
// the upcoming retry calls authClient.issueRpcToken with the
// long-lived session and gets a fresh one — no relogin needed.
this.rpcTokenManager.clear()
const payload = data as { message?: string }
onEvent({
type: 'error',
message: String(payload?.message || 'RPC token expired; reconnecting'),
})
return
}
const payload = data as { message?: string }
onEvent({
type: 'error',
message: String(payload?.message || 'Status stream event error'),
})
},
abortController.signal
)
if (!closed) {
onEvent({ type: 'error', message: 'Status stream disconnected' })
}
} catch (error) {
if (closed) return
if (error instanceof ApiError && error.status === 401) {
this.rpcTokenManager.clear()
}
onEvent({ type: 'error', message: error instanceof Error ? error.message : String(error) })
} finally {
if (closed) return
clearRetry()
retryTimer = setTimeout(() => {
backoffMs = Math.min(backoffMs * 2, 15000)
void connect()
}, backoffMs)
}
}
this.hostStatusStreams.set(streamId, { ownerId, stop })
void connect()
}
stopHostStatusStream(streamId: string, requesterOwnerId?: number): boolean {
const entry = this.hostStatusStreams.get(streamId)
if (!entry) return true
if (requesterOwnerId !== undefined && entry.ownerId !== requesterOwnerId) {
return false
}
entry.stop()
return true
}
stopHostStatusStreamsForOwner(ownerId: number): void {
const toStop: string[] = []
for (const [streamId, entry] of this.hostStatusStreams.entries()) {
if (entry.ownerId === ownerId) toStop.push(streamId)
}
for (const streamId of toStop) {
this.stopHostStatusStream(streamId)
}
}
startHostActivityStream(
streamId: string,
ownerId: number,
hostRef: string,
hostRefs: string[] | undefined,
onEvent: (event: HostActivityStreamEvent) => void
): void {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
this.requireSessionToken()
let closed = false
let abortController: AbortController | null = null
let retryTimer: NodeJS.Timeout | null = null
let backoffMs = 1000
const clearRetry = () => {
if (retryTimer) {
clearTimeout(retryTimer)
retryTimer = null
}
}
const stop = (opts?: { silent?: boolean }) => {
if (closed) return
closed = true
clearRetry()
if (abortController) abortController.abort()
this.hostActivityStreams.delete(streamId)
// `silent`: bulk teardown skips the final `closed` (see `stopAllStreams`).
if (!opts?.silent) onEvent({ type: 'closed' })
}
const connect = async () => {
if (closed) return
abortController = new AbortController()
try {
const rpc = await this.issueRpcTokenForHostRefs(HOST_ACTIVITY_SCOPES, effectiveHostRefs)
await this.rpcClient.openHostActivityStream(
rpc.token,
targetHostRef,
({ event, data }) => {
if (closed) return
if (event === 'open') {
backoffMs = 1000
const payload = data as { hostRef?: string; observedAt?: string }
onEvent({
type: 'open',
hostRef: String(payload?.hostRef || targetHostRef),
observedAt: String(payload?.observedAt || new Date().toISOString()),
})
return
}
if (event === 'activity') {
backoffMs = 1000
onEvent({ type: 'activity', activity: data as HostActivitySnapshot['items'][number] })
return
}
if (event === 'auth-expired') {
// §4.5-5 / GAP-D2: parity with the status stream (:1374). Upstream
// rejected the captured RPC token (TTL 300s) as an SSE event rather
// than a transport 401 — clear the cached token so the retry re-mints
// a fresh one, then surface an error to drive the reconnect. Without
// this the retry re-used the still-"valid" (client-side) dead token.
// The token is never forwarded to the renderer.
this.rpcTokenManager.clear()
const payload = data as { message?: string }
onEvent({
type: 'error',
message: String(payload?.message || 'RPC token expired; reconnecting'),
})
return
}
const payload = data as { message?: string }
onEvent({
type: 'error',
message: String(payload?.message || 'Activity stream event error'),
})
},
abortController.signal
)
if (!closed) onEvent({ type: 'error', message: 'Activity stream disconnected' })
} catch (error) {
if (closed) return
if (error instanceof ApiError && error.status === 401) {
this.rpcTokenManager.clear()
}
onEvent({ type: 'error', message: error instanceof Error ? error.message : String(error) })
} finally {
if (closed) return
clearRetry()
retryTimer = setTimeout(() => {
backoffMs = Math.min(backoffMs * 2, 15000)
void connect()
}, backoffMs)
}
}
this.hostActivityStreams.set(streamId, { ownerId, stop })
void connect()
}
stopHostActivityStream(streamId: string, requesterOwnerId?: number): boolean {
const entry = this.hostActivityStreams.get(streamId)
if (!entry) return true
if (requesterOwnerId !== undefined && entry.ownerId !== requesterOwnerId) {
return false
}
entry.stop()
return true
}
stopHostActivityStreamsForOwner(ownerId: number): void {
const toStop: string[] = []
for (const [streamId, entry] of this.hostActivityStreams.entries()) {
if (entry.ownerId === ownerId) toStop.push(streamId)
}
for (const streamId of toStop) {
this.stopHostActivityStream(streamId)
}
}
startTaskProgressStream(
streamId: string,
ownerId: number,
hostRef: string,
taskId: string,
hostRefs: string[] | undefined,
onEvent: (event: TaskProgressStreamEvent) => void
): void {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
const targetTaskId = String(taskId || '').trim()
if (!targetTaskId) {
throw new Error('taskId is required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
this.requireSessionToken()
let closed = false
// Reassigned per reconnect attempt; `stop()` aborts whichever attempt is live.
let abortController = new AbortController()
let streamOpened = false
// De-collapse (§4.5-1): `waiting` and `open` are now distinct renderer events.
// Each is emitted at most once per subscription (dedup across bridge-internal
// reconnects — the tracker is already following this streamId).
let waitingEmitted = false
const stop = (opts?: { silent?: boolean }) => {
if (closed) return
closed = true
abortController.abort()
this.progressStreams.delete(streamId)
// `silent`: bulk teardown on logout/team-switch aborts the socket WITHOUT a
// fabricated `closed`, which would otherwise fire a spurious stream-loss
// terminal against a live tracker before the renderer's own release runs
// (R-F13). The abort alone stops any reconnect/token re-mint. See
// `stopAllStreams`.
if (!opts?.silent) onEvent({ type: 'closed' })
}
this.progressStreams.set(streamId, { ownerId, stop })
void (async () => {
// stream-recovery (A): a dropped transport is not a task failure — the task
// is durable server-side. Reconnect a bounded number of times before
// surfacing an error; mcp-host replays the buffered terminal to a late
// subscriber, so a blip recovers transparently. Only after exhausting the
// attempts do we emit `error` (→ the renderer reconciles, B).
let attempt = 0
let giveUp = false // non-retryable: task_not_found_or_expired, 401, or a
let forwardedError = false // structured task error already sent to the renderer.
// §4.5-2: the reason surfaced to the renderer as a structured `gone` event
// when the bridge gives up without a clean terminal.
let goneReason = 'reconnect_exhausted'
let attemptTimer: ReturnType<typeof setTimeout> | null = null
let waitingForOpenTimer: ReturnType<typeof setTimeout> | null = null
const clearAttemptTimeout = () => {
if (attemptTimer) {
clearTimeout(attemptTimer)
attemptTimer = null
}
}
const clearWaitingForOpenTimeout = () => {
if (waitingForOpenTimer) {
clearTimeout(waitingForOpenTimer)
waitingForOpenTimer = null
}
}
const clearTimers = () => {
clearAttemptTimeout()
clearWaitingForOpenTimeout()
}
const handleEvent = ({ event, data }: { event: string; data: unknown }) => {
if (closed) return
// F3: `waiting` proves the HTTP connection is ESTABLISHED — we received
// bytes from the server. It does NOT prove the task is streaming: mcp-host
// sends `waiting`, then blocks in waitFor(reporter, 180s) before `open`,
// with no keepalive in between. So on `waiting` we clear the 8s
// establishment bound and arm a longer "waiting-for-open" bound matching the
// server's reporter-wait budget (+ margin); a >8s pre-`open` stall no longer
// aborts a live task. §4.5-1: forward `waiting` as its OWN renderer event
// (no longer collapsed to `open`) so the renderer distinguishes a queued
// task from a live reporter and does NOT reset its re-rejoin budget on it.
// `waiting` deliberately does NOT reset the bridge's reconnect budget either.
if (event === 'waiting') {
clearAttemptTimeout()
if (!waitingForOpenTimer) {
waitingForOpenTimer = setTimeout(
() => abortController.abort(),
RECONNECT_WAITING_FOR_OPEN_TIMEOUT_MS
)
}
if (!waitingEmitted) {
waitingEmitted = true
const payload = data as { taskId?: string; hostRef?: string } | undefined
onEvent({
type: 'waiting',
taskId: String(payload?.taskId || targetTaskId),
hostRef: String(payload?.hostRef || targetHostRef),
})
}
return
}
// Any non-`waiting` event: the connection is producing genuine traffic —
// clear BOTH timers.
clearTimers()
// §4.5-5 / GAP-D2: upstream rejected the captured RPC token mid-stream (TTL
// is 300s — normal on long-lived sessions). Drop the cached token so the
// next reconnect attempt re-mints a fresh one, then let the current attempt
// end and reconnect. Parity with the status stream (:1374); without this the
// reconnect re-used the still-"valid" (client-side) dead token and looped
// until the budget exhausted. The token never crosses to the renderer.
if (event === 'auth-expired') {
this.rpcTokenManager.clear()
return
}
// §4.5-1: a real reporter-live `open` (the mcp-host waiting→open handshake
// completed). Emitted distinctly from `waiting`; `streamOpened` dedups it
// across bridge-internal reconnects. Does NOT reset the reconnect budget (a
// flapping open must still exhaust MAX_RECONNECT_ATTEMPTS).
if (event === 'open') {
if (streamOpened) return
streamOpened = true
const payload = data as { taskId?: string; hostRef?: string } | undefined
onEvent({
type: 'open',
taskId: String(payload?.taskId || targetTaskId),
hostRef: String(payload?.hostRef || targetHostRef),
})
return
}
// F4: genuine POST-open traffic (a heartbeat or task progress) proves this
// connection is alive and streaming, so reset the reconnect budget. A
// long-lived stream that already absorbed a couple of transient drops then
// gets a full retry allowance for a later blip; `attempt` is otherwise only
// ever incremented.
attempt = 0
if (event === 'done') {
const payload = data as { taskId?: string } | undefined
onEvent({
type: 'terminal',
data: { taskId: String(payload?.taskId || targetTaskId), status: 'completed' },
})
this.stopTaskProgressStream(streamId)
return
}
if (event === 'terminal') {
// Phase D unified terminal event — forward and close the stream
// (BUG-14: was silently dropped by KNOWN_PROGRESS_EVENTS allowlist)
onEvent({ type: 'terminal', data } as TaskProgressStreamEvent)
this.stopTaskProgressStream(streamId)
return
}
if (event === 'error' || event === 'closed') {
const payload = data as
| {
taskId?: string
code?: string
message?: string
retryable?: boolean
provider?: string
}
| undefined
// Structured task error (has `code`) — a real failure, not a transport
// blip. Forward it as-is and stop retrying.
if (
event === 'error' &&
payload &&
typeof payload.code === 'string' &&
typeof payload.message === 'string'
) {
onEvent({
type: 'error',
message: payload.message,
data: {
taskId: String(payload.taskId || targetTaskId),
code: payload.code,
message: payload.message,
retryable: Boolean(payload.retryable),
provider: String(payload.provider || 'unknown'),
},
})
forwardedError = true
giveUp = true
return
}
// task_not_found_or_expired → the reporter+result are gone; reconnect
// can't help. Give up so the renderer reconciles against /messages (B).
if (String(payload?.message || '').includes('task_not_found_or_expired')) {
giveUp = true
goneReason = 'task_not_found_or_expired'
return
}
// Other transport-level error/closed: do NOT forward mid-retry — let the
// attempt end so the loop reconnects.
return
}
// Forward only known progress event types (incl. heartbeat keepalives)
if (KNOWN_PROGRESS_EVENTS.has(event)) {
onEvent({ type: event, data } as TaskProgressStreamEvent)
}
// Silently ignore unrecognized event types
}
try {
while (!closed && !giveUp) {
abortController = new AbortController()
// F3: this 8s bound guards CONNECTION ESTABLISHMENT only (open request →
// first server bytes). It's cleared on `waiting` (connection established),
// which then arms the longer waiting-for-open bound. A server that never
// sends `waiting` within 8s still aborts and retries as before.
attemptTimer = setTimeout(() => abortController.abort(), RECONNECT_ATTEMPT_TIMEOUT_MS)
try {
const rpc = await this.issueRpcTokenForHostRefs(HOST_ACTIVITY_SCOPES, effectiveHostRefs)
await this.rpcClient.openTaskProgressStream(
rpc.token,
targetHostRef,
targetTaskId,
handleEvent,
abortController.signal
)
} catch (error) {
// F4: a 401 on token re-issue (the 300s RPC token expired mid-stream)
// clears the cache so the NEXT attempt re-mints a fresh token, then
// falls through to retry. A single transient 401 must NOT collapse a
// live stream — only a persistent 401 (genuinely revoked session) still
// terminates, bounded by MAX_RECONNECT_ATTEMPTS below. The structured
// task-error path above keeps its own `giveUp` for truly non-retryable
// failures.
if (error instanceof ApiError && error.status === 401) {
this.rpcTokenManager.clear()
}
// Otherwise transient (network/abort) — fall through to retry.
} finally {
clearTimers()
}
if (closed || giveUp) break
attempt += 1
if (attempt >= MAX_RECONNECT_ATTEMPTS) break
const delayMs = Math.min(
RECONNECT_BASE_DELAY_MS * 2 ** (attempt - 1),
RECONNECT_MAX_DELAY_MS
)
await new Promise(resolve => setTimeout(resolve, delayMs))
}
// Exhausted/gave up without a clean terminal → surface the loss as a
// structured `gone` (§4.5-2), NOT the generic `error`. The renderer's
// tracker turns this into a definitive stream-loss terminal and reconciles
// against the server (re-attach if non-idle, else settle) rather than
// re-attaching blindly.
if (!closed && !forwardedError) {
onEvent({ type: 'gone', reason: goneReason })
}
} finally {
if (!closed) stop()
}
})()
}
stopTaskProgressStream(streamId: string, requesterOwnerId?: number): boolean {
const entry = this.progressStreams.get(streamId)
if (!entry) return true
if (requesterOwnerId !== undefined && entry.ownerId !== requesterOwnerId) {
return false
}
entry.stop()
return true
}
stopTaskProgressStreamsForOwner(ownerId: number): void {
const toStop: string[] = []
for (const [streamId, entry] of this.progressStreams.entries()) {
if (entry.ownerId === ownerId) toStop.push(streamId)
}
for (const streamId of toStop) {
this.stopTaskProgressStream(streamId)
}
}
async approveToolCall(
hostRef: string,
taskId: string,
toolCallId: string,
hostRefs?: string[],
options: { teamId?: string | null } = {}
): Promise<ApprovalDecisionResult> {
const targetHostRef = String(hostRef || '').trim()
const targetTaskId = String(taskId || '').trim()
const targetToolCallId = String(toolCallId || '').trim()
if (!targetHostRef || !targetTaskId || !targetToolCallId) {
throw new Error('hostRef, taskId, and toolCallId are required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(
HOST_APPROVAL_SCOPES,
effectiveHostRefs,
options
)
try {
return await this.rpcClient.approveToolCall(
rpc.token,
targetHostRef,
targetTaskId,
targetToolCallId
)
} catch (error) {
// §4.5-7: align with invoke/getTaskResult — a 401/expired-scope means the
// 300s RPC token lapsed; clear the cache, re-mint (same `options`/team so a
// cross-team decision still acquires the right team's token) and retry once.
// Retry-safety (verified): `shouldRefreshRpcToken` fires ONLY on 401 or
// 403-"missing scope". Every 401/403 reachable on this route is emitted
// BEFORE the approval mutation runs — by rpc-proxy's auth middleware
// (`requireRpcAuth`/`requireScope`, rpc-proxy/src/middleware/auth.ts:18-48,
// ahead of the forward at rpc-proxy/src/routes/rpc.ts:215-250) AND by
// mcp-host's pre-dispatch checks (`runtimeEdgeGuard`
// mcp-host/src/server/edgeRuntimeAuth.ts:78-97 + the guards in
// `handleApprovalRoute` mcp-host/src/server/routes.ts:401, all before
// `approvalHandler` at :443). The only POST-mutation responses are 200 or
// 500, neither of which triggers a refresh-retry — so a retried error is
// always a pre-mutation rejection and the approval is never double-applied.
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(
HOST_APPROVAL_SCOPES,
effectiveHostRefs,
options
)
return this.rpcClient.approveToolCall(
retried.token,
targetHostRef,
targetTaskId,
targetToolCallId
)
}
throw error
}
}
async cancelTask(hostRef: string, taskId: string): Promise<void> {
const targetHostRef = String(hostRef || '').trim()
const targetTaskId = String(taskId || '').trim()
if (!targetHostRef) throw new Error('hostRef is required')
if (!targetTaskId) throw new Error('taskId is required')
const rpc = await this.issueRpcTokenForHostRefs(HOST_WAKEABLE_OPERATION_SCOPES, [targetHostRef])
try {
await this.rpcClient.cancelTask(rpc.token, targetHostRef, targetTaskId)
} catch (error) {
// §4.5-7: retry once after a token refresh (previously a 401 here failed
// outright, unlike invoke/getTaskResult).
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(HOST_WAKEABLE_OPERATION_SCOPES, [
targetHostRef,
])
await this.rpcClient.cancelTask(retried.token, targetHostRef, targetTaskId)
return
}
throw error
}
}
async denyToolCall(
hostRef: string,
taskId: string,
toolCallId: string,
reason: string,
hostRefs?: string[],
options: { teamId?: string | null } = {}
): Promise<ApprovalDecisionResult> {
const targetHostRef = String(hostRef || '').trim()
const targetTaskId = String(taskId || '').trim()
const targetToolCallId = String(toolCallId || '').trim()
if (!targetHostRef || !targetTaskId || !targetToolCallId) {
throw new Error('hostRef, taskId, and toolCallId are required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(
HOST_APPROVAL_SCOPES,
effectiveHostRefs,
options
)
try {
return await this.rpcClient.denyToolCall(
rpc.token,
targetHostRef,
targetTaskId,
targetToolCallId,
reason
)
} catch (error) {
// §4.5-7: retry once after a token refresh, preserving `options`/team.
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(
HOST_APPROVAL_SCOPES,
effectiveHostRefs,
options
)
return this.rpcClient.denyToolCall(
retried.token,
targetHostRef,
targetTaskId,
targetToolCallId,
reason
)
}
throw error
}
}
async listArtifacts(
hostRef: string,
hostRefs?: string[]
): Promise<{
artifacts: Array<{ name: string; format: string; sizeBytes: number; createdAt: string }>
}> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) throw new Error('hostRef is required')
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_ARTIFACT_SCOPES, effectiveHostRefs)
return this.rpcClient.listArtifacts(rpc.token, targetHostRef)
}
async downloadArtifact(hostRef: string, filename: string, hostRefs?: string[]): Promise<Buffer> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef || !filename) throw new Error('hostRef and filename are required')
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_ARTIFACT_SCOPES, effectiveHostRefs)
return this.rpcClient.downloadArtifact(rpc.token, targetHostRef, filename)
}
async listSessions(
hostRef: string,
hostRefs?: string[],
query: SessionsListQuery = {}
): Promise<SessionsListResult> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) throw new Error('hostRef is required')
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_SESSION_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.listSessions(rpc.token, targetHostRef, query)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(HOST_SESSION_SCOPES, effectiveHostRefs)
return this.rpcClient.listSessions(retried.token, targetHostRef, query)
}
throw error
}
}
async loadSessionMessages(
hostRef: string,
agent: string,
chatId: string,
hostRefs?: string[],
query: SessionMessagesQuery = {}
): Promise<SessionMessagesResult> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef || !agent || !chatId) {
throw new Error('hostRef, agent, and chatId are required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_SESSION_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.loadSessionMessages(
rpc.token,
targetHostRef,
agent,
chatId,
query
)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(HOST_SESSION_SCOPES, effectiveHostRefs)
return this.rpcClient.loadSessionMessages(
retried.token,
targetHostRef,
agent,
chatId,
query
)
}
throw error
}
}
/**
* On-demand context-window breakdown for the active conversation. Mirrors
* `loadSessionMessages` (same `host:session:read` scope, same token issuance
* by hostRefs). Returns `{ breakdown: null }` when there is no snapshot — the
* UI hides the chip in that case rather than treating it as an error.
*/
async getContextBreakdown(
hostRef: string,
agent: string,
chatId: string,
hostRefs?: string[]
): Promise<ContextBreakdownResult> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef || !agent || !chatId) {
throw new Error('hostRef, agent, and chatId are required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_SESSION_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.getContextBreakdown(rpc.token, targetHostRef, agent, chatId)
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
if (message.includes('401') && message.toLowerCase().includes('missing token')) {
console.warn(
'[AppService] Context breakdown unavailable because the runtime rejected the session token.'
)
return { breakdown: null }
}
throw error
}
}
/**
* Lists the models selectable for a host's active provider plus the current
* per-session selection (R2). Uses the same `host:session:read` scope and
* token issuance as {@link getContextBreakdown}. Returns `null` when the host
* predates the endpoint (404/501) so the UI hides the selector (R2.6 compat).
*/
async getHostModels(
hostRef: string,
chatId: string,
hostRefs?: string[]
): Promise<HostModelsResult | null> {
const targetHostRef = String(hostRef || '').trim()
// `chatId` is OPTIONAL here: the model list is host-level (allowlist), and a
// brand-new chat has no id yet. When absent, the server returns the list with
// `sessionModel: null` (R2 new-chat composer selector). Only the host is
// required to resolve the token/route.
const targetChatId = String(chatId || '').trim()
if (!targetHostRef) {
throw new Error('hostRef is required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_SESSION_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.getHostModels(rpc.token, targetHostRef, targetChatId)
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
if (message.includes('401') && message.toLowerCase().includes('missing token')) {
console.warn(
'[AppService] Host models unavailable because the runtime rejected the session token.'
)
return null
}
throw error
}
}
/**
* Sets the per-session model for a host (R2.3). Applies to the next task only.
* Issues a token carrying the dedicated `host:model:write` scope. A model
* outside the allowlist throws with the `model_not_allowed` token in the
* message, which the renderer detects to show a targeted error.
*/
async setHostModel(
hostRef: string,
chatId: string,
model: string,
hostRefs?: string[],
expectedRevision?: number
): Promise<SetHostModelResult> {
const targetHostRef = String(hostRef || '').trim()
const targetModel = String(model || '').trim()
if (!targetHostRef || !chatId || !targetModel) {
throw new Error('hostRef, chatId, and model are required')
}
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_MODEL_SCOPES, effectiveHostRefs)
return this.rpcClient.setHostModel(
rpc.token,
targetHostRef,
chatId,
targetModel,
expectedRevision
)
}
/**
* Spec 15 Fase B — propagates an explicit user rename to the server. Mints a
* token carrying the dedicated, NON-wake `host:session:write` scope (see
* {@link HOST_SESSION_TITLE_SCOPES}). The raw title is never logged. Errors
* (404 missing/foreign/channel, 400 invalid, 403 access) throw so the renderer
* can drive the pending-rename queue (§2.5); a bounded refresh-retry mirrors
* {@link getDesktopStatus} for the 401/403-missing-scope token-lapse case.
*/
async renameSession(
hostRef: string,
agent: string,
chatId: string,
title: string
): Promise<{ title: string }> {
const targetHostRef = String(hostRef || '').trim()
const targetAgent = String(agent || '').trim()
const targetChatId = String(chatId || '').trim()
if (!targetHostRef || !targetAgent || !targetChatId) {
throw new Error('hostRef, agent, and chatId are required')
}
// A rename always targets exactly one host, so the write-scope token is minted
// for that single hostRef only — never a caller-supplied fleet list, which would
// widen an intentionally narrow token. (Unlike setHostModel, which is multi-host.)
const effectiveHostRefs = [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(HOST_SESSION_TITLE_SCOPES, effectiveHostRefs)
try {
return await this.rpcClient.renameSession(
rpc.token,
targetHostRef,
targetAgent,
targetChatId,
title
)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(
HOST_SESSION_TITLE_SCOPES,
effectiveHostRefs
)
return this.rpcClient.renameSession(
retried.token,
targetHostRef,
targetAgent,
targetChatId,
title
)
}
throw error
}
}
getTokenMetadata(): TokenMetadata {
const meta = this.rpcTokenManager.getMetadata()
return {
hasSession: Boolean(this.sessionToken),
rpcTokenExpiresAtMs: meta.expiresAtMs,
rpcScopes: meta.scopes,
rpcHostRefs: meta.hostRefs,
}
}
async getDesktopStatus(
hostRef: string
): Promise<{ hostRef: string; status: string; message?: string }> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) throw new Error('hostRef is required')
const rpc = await this.issueRpcTokenForHostRefs(DESKTOP_VIEW_SCOPES, [targetHostRef])
try {
return await this.rpcClient.getDesktopStatus(rpc.token, targetHostRef)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(DESKTOP_VIEW_SCOPES, [targetHostRef])
return this.rpcClient.getDesktopStatus(retried.token, targetHostRef)
}
throw error
}
}
async openDesktop(
hostRef: string,
onWindowClosed?: (closedHostRef: string) => void
): Promise<void> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) throw new Error('hostRef is required')
const rpc = await this.issueRpcTokenForHostRefs(DESKTOP_VIEW_SCOPES, [targetHostRef])
const { openDesktopWindow } = await import('./desktopWindow.js')
await openDesktopWindow({
hostRef: targetHostRef,
jwt: rpc.token,
rpcProxyUrl: this.getEffectiveRpcProxyBaseUrl(),
onClose: onWindowClosed,
})
}
async closeDesktop(hostRef: string): Promise<void> {
const targetHostRef = String(hostRef || '').trim()
if (!targetHostRef) throw new Error('hostRef is required')
const { closeDesktopWindow } = await import('./desktopWindow.js')
closeDesktopWindow(targetHostRef)
}
// ─── Sandbox UI ───────────────────────────────────────────────────
/** Picker payload for the renderer's sandbox-ui app list. */
async listSandboxUiApps(): Promise<{ apps: import('./rpcProxyClient.js').SandboxUiApp[] }> {
const token = this.requireSessionToken()
const rpc = await this.rpcTokenManager.getOrIssue(token, SANDBOX_UI_VIEW_SCOPES, [
SANDBOX_UI_HOST_REF_SENTINEL,
])
try {
return await this.rpcClient.listSandboxUiApps(rpc.token)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.rpcTokenManager.getOrIssue(token, SANDBOX_UI_VIEW_SCOPES, [
SANDBOX_UI_HOST_REF_SENTINEL,
])
return this.rpcClient.listSandboxUiApps(retried.token)
}
throw error
}
}
/**
* Mint a per-recipe UI session cookie. Returns the raw Set-Cookie value
* so the WebContentsView driver can install it into the per-recipe
* Electron partition.
*/
async mintSandboxUiSession(recipeNs: string, recipeName: string): Promise<{ setCookie: string }> {
const ns = String(recipeNs || '').trim()
const name = String(recipeName || '').trim()
if (!ns || !name) throw new Error('recipeNs and recipeName are required')
const token = this.requireSessionToken()
const rpc = await this.rpcTokenManager.getOrIssue(token, SANDBOX_UI_VIEW_SCOPES, [
SANDBOX_UI_HOST_REF_SENTINEL,
])
try {
return await this.rpcClient.mintSandboxUiSession(rpc.token, ns, name)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.rpcTokenManager.getOrIssue(token, SANDBOX_UI_VIEW_SCOPES, [
SANDBOX_UI_HOST_REF_SENTINEL,
])
return this.rpcClient.mintSandboxUiSession(retried.token, ns, name)
}
throw error
}
}
/**
* Embed clicked `clerum://oauth?clientId=…`. Fetch the provider authorize
* URL via rpc-proxy and `shell.openExternal` it. The rest of the flow
* runs in the OS browser; control-api's callback stores the grant and
* bounces back to `clerum://oauth-completed`, which `main.ts` routes to
* the active embed via `dispatchSandboxUiOauthCompleted`.
*
* When `background` is true (deep-link had `background=1`), a host-rendered
* Electron confirm dialog is shown before opening the browser. If the user
* cancels, the authorize flow is aborted.
*/
async requestSandboxUiOauthAuthorize(
recipeNs: string,
recipeName: string,
oauthClientId: string,
background = false
): Promise<void> {
const ns = String(recipeNs || '').trim()
const name = String(recipeName || '').trim()
const clientId = String(oauthClientId || '').trim()
if (!ns || !name) throw new Error('recipeNs and recipeName are required')
if (!clientId) throw new Error('oauthClientId is required')
const sessionEpoch = this.sandboxUiSessionEpoch
const token = this.requireSessionToken()
const issueRpc = () =>
this.rpcTokenManager.getOrIssue(token, SANDBOX_UI_VIEW_SCOPES, [SANDBOX_UI_HOST_REF_SENTINEL])
let rpc = await issueRpc()
let result: { authorizeUrl: string }
try {
result = await this.rpcClient.requestSandboxUiOauthAuthorizeUrl(
rpc.token,
ns,
name,
clientId,
background
)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
rpc = await issueRpc()
result = await this.rpcClient.requestSandboxUiOauthAuthorizeUrl(
rpc.token,
ns,
name,
clientId,
background
)
} else {
throw error
}
}
// The authorize URL binds the grant to the session that fetched it; never
// hand it to the browser once that session is gone.
this.assertSandboxUiSessionEpoch(sessionEpoch)
if (background) {
const { dialog, BrowserWindow } = await import('electron')
const win = BrowserWindow.getFocusedWindow() ?? undefined
const opts = {
type: 'question' as const,
buttons: ['Cancel', 'Allow background access'],
defaultId: 1,
cancelId: 0,
message: `Allow "${name}" to use your account in the background?`,
detail:
'The plugin will be able to act on your behalf even when you are not using it, until you disconnect it from Connected accounts.',
}
const result = win
? await dialog.showMessageBox(win, opts)
: await dialog.showMessageBox(opts)
if (result.response !== 1) return
this.assertSandboxUiSessionEpoch(sessionEpoch)
}
await openExternalDataUrl(result.authorizeUrl, { requireHttps: true })
}
/**
* U5 (mcp-oauth reactive consent) — the renderer's "Connect <server>" button.
* A tool-call against an OAuth mcp-server suspended the task with
* `connect_required`; this fetches a fresh provider authorize URL via rpc-proxy
* and `shell.openExternal`s it. The rest of the flow runs in the OS browser;
* control-api's callback stores the grant and bounces back to
* `clerum://oauth-completed?…&source=mcp`, which `main.ts` routes to the
* renderer to resume the suspended task (NOT the sandbox-ui embed).
*
* Analogous to `requestSandboxUiOauthAuthorize`, but keyed by `mcpServerName`
* (never a recipe) and host-bound to the suspended conversation's `hostRef`
* (RPC tokens require ≥1 hostRef; the user has access to the host they are
* chatting in). `userId` is derived by rpc-proxy from `auth.sub`, never sent.
*/
async requestMcpOauthAuthorize(
mcpServerName: string,
hostRef: string,
contextId?: string,
// Proactive panel (spec 11 U3/D-4): when the connector is `oauth-context`
// ("shared by the team"), authorizing affects the WHOLE Context, so the
// panel asks main to show an explicit confirm dialog first. The reactive
// U5 path never sets this, so its behavior is byte-identical.
options?: { confirmShared?: boolean }
): Promise<void> {
const server = String(mcpServerName || '').trim()
const targetHostRef = String(hostRef || '').trim()
if (!server) throw new Error('mcpServerName is required')
if (!targetHostRef) throw new Error('hostRef is required')
const ctx = contextId ? String(contextId).trim() || undefined : undefined
if (options?.confirmShared) {
const confirmed = await this.confirmSharedConnectorAction('connect', server)
if (!confirmed) return
}
let rpc = await this.issueRpcTokenForHostRefs(MCP_SERVER_INVOKE_SCOPES, [targetHostRef])
let result: { authorizeUrl: string }
try {
result = await this.rpcClient.requestMcpOauthAuthorizeUrl(rpc.token, server, ctx)
} catch (error) {
// §4.5-7: a 401/expired-scope means the 300s RPC token lapsed; clear the
// cache, re-mint (same hostRef) and retry once. Every 401/403-missing-scope
// on this route is emitted by rpc-proxy's auth middleware BEFORE any grant
// mutation, so a retried error is always a pre-effect rejection — the
// authorize-url mint is idempotent regardless.
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
rpc = await this.issueRpcTokenForHostRefs(MCP_SERVER_INVOKE_SCOPES, [targetHostRef])
result = await this.rpcClient.requestMcpOauthAuthorizeUrl(rpc.token, server, ctx)
} else {
throw error
}
}
await openExternalDataUrl(result.authorizeUrl, { requireHttps: true })
}
/**
* Proactive connectors read-model (spec 11 U2). Returns the user's agent fleet
* with each connector classified tri-state (`authorized`/`requires_setup`/
* `no_oauth`). Host refs come from the access catalog purely to mint the
* `mcp:servers:list` RPC token (rpc-proxy derives the userId from `auth.sub`
* and enumerates agents server-side). Retry-after-refresh mirrors
* {@link listAccessibleMcpServers}.
*/
async getConnectors(): Promise<RpcConnectorsResult> {
const token = this.requireSessionToken()
const catalog = await this.getAccessCatalog()
const hostRefs = AppService.dedupe(
(catalog.agentNames || []).map(name => String(name || '').trim()).filter(Boolean)
)
if (!hostRefs.length) {
const me = this.me ?? (await this.authClient.getMe(token))
this.me = me
return { userId: me.id, agents: [] }
}
const rpc = await this.issueRpcTokenForHostRefs(MCP_SERVERS_LIST_SCOPES, hostRefs)
try {
return await this.rpcClient.getConnectors(rpc.token)
} catch (error) {
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
const retried = await this.issueRpcTokenForHostRefs(MCP_SERVERS_LIST_SCOPES, hostRefs)
return this.rpcClient.getConnectors(retried.token)
}
throw error
}
}
/**
* Disconnect (revoke) an mcp-server's OAuth grant from the proactive panel
* (spec 11 U4). Host-bound to the agent whose row triggered it (RPC tokens
* require ≥1 hostRef; `mcp:server:invoke`, same as connect). Disconnect is
* destructive, so it ALWAYS asks for explicit confirmation via a native
* dialog (D-4); for an `oauth-context` connector the copy names the team-wide
* blast radius. `userId` is derived by rpc-proxy from `auth.sub`, never sent.
* Resolves `{ confirmed:false }` when the user cancels (nothing was revoked).
*/
async disconnectMcpServer(
mcpServerName: string,
hostRef: string,
contextId?: string,
options?: { shared?: boolean }
): Promise<{ confirmed: boolean }> {
const server = String(mcpServerName || '').trim()
const targetHostRef = String(hostRef || '').trim()
if (!server) throw new Error('mcpServerName is required')
if (!targetHostRef) throw new Error('hostRef is required')
const ctx = contextId ? String(contextId).trim() || undefined : undefined
const confirmed = await this.confirmSharedConnectorAction(
'disconnect',
server,
Boolean(options?.shared)
)
if (!confirmed) return { confirmed: false }
let rpc = await this.issueRpcTokenForHostRefs(MCP_SERVER_INVOKE_SCOPES, [targetHostRef])
try {
await this.rpcClient.deleteMcpOauthGrant(rpc.token, server, ctx)
} catch (error) {
// The DELETE is idempotent and rpc-proxy emits every 401/403-missing-scope
// from its auth middleware BEFORE the upstream call, so a retried error is
// always a pre-effect rejection — safe to re-mint (same hostRef) and retry.
if (AppService.shouldRefreshRpcToken(error)) {
this.rpcTokenManager.clear()
rpc = await this.issueRpcTokenForHostRefs(MCP_SERVER_INVOKE_SCOPES, [targetHostRef])
await this.rpcClient.deleteMcpOauthGrant(rpc.token, server, ctx)
} else {
throw error
}
}
return { confirmed: true }
}
/**
* Native confirmation dialog for a connector action whose effect is either
* destructive (any disconnect) or team-wide (`oauth-context`). Mirrors the
* background-consent dialog of {@link requestSandboxUiOauthAuthorize}. The
* `shared` copy names the Context blast radius; every disconnect carries the
* revocation-latency note (D-5 — no immediate push; eviction is by idle
* timeout). Returns true iff the user confirmed.
*/
private async confirmSharedConnectorAction(
action: 'connect' | 'disconnect',
server: string,
shared = true
): Promise<boolean> {
const { dialog, BrowserWindow } = await import('electron')
const win = BrowserWindow.getFocusedWindow() ?? undefined
const verb = action === 'connect' ? 'Connect' : 'Disconnect'
// Revocation is NOT immediate and — critically — has no fixed upper bound for
// the shared (oauth-context) flavor: SHARED partitions are exempt from the
// 15-min idle eviction (mcp-host), so a live session ends only on the next
// grant-revocation sweep, which is fail-open. Don't promise "a few minutes".
const latencyNote =
action === 'disconnect'
? ' It is not immediate — active sessions end on the next revocation sweep.'
: ''
const message = shared ? `${verb} "${server}" for the whole team?` : `${verb} "${server}"?`
const detail = shared
? action === 'connect'
? `This connector is shared by the team. Authorizing it connects every agent in this context on your behalf.${latencyNote}`
: `This connector is shared by the team. Disconnecting removes access for every agent in this context.${latencyNote}`
: `This removes your authorization for this connector.${latencyNote}`
const opts = {
type: (action === 'disconnect' ? 'warning' : 'question') as 'warning' | 'question',
buttons: ['Cancel', verb],
// Disconnect is destructive: default to Cancel (0) so a stray Enter does
// NOT revoke. Connect is additive, so its default stays on the action (1).
defaultId: action === 'disconnect' ? 0 : 1,
cancelId: 0,
message,
detail,
}
const result = win ? await dialog.showMessageBox(win, opts) : await dialog.showMessageBox(opts)
return result.response === 1
}
/**
* Open the sandbox-ui WebContentsView. Mints a session cookie, installs it
* into the per-recipe Electron partition, and mounts a single embedded
* view at the bounds the renderer reserved.
*
* Only one sandbox-ui view exists at a time across the desktop app —
* re-opening recipe B while A is up tears down A first, before B's session
* is minted, so a failed open leaves no view at all. This keeps memory + GPU
* usage bounded and avoids accidental cross-recipe focus / cookie-jar
* mixups.
*/
openSandboxUi(args: {
/** Names the view this open mounts in every event about it. */
launchId: string
recipeNs: string
recipeName: string
title?: string
defaultPath?: string
routePath?: string
bounds: import('./sandboxUiDriver.js').SandboxUiBounds
parentWindow: import('electron').BrowserWindow
/** Exactly once per view this open mounts, even if the open then rejects. */
onReleased?: (event: import('./sandboxUiDriver.js').SandboxUiReleasedEvent) => void
onRefreshError?: (message: string) => void
/** A refresh succeeded after `onRefreshError` reported that it had given up. */
onRefreshRecovered?: () => void
onOauthError?: (message: string) => void
onTitleChanged?: (title: string) => void
}): Promise<void> {
// Captured at request time, not when the queue reaches it: an open asked for
// under one session must not run under the next one. Enqueued synchronously:
// a close for this launch sent right after it must find it ahead in the queue.
const sessionEpoch = this.sandboxUiSessionEpoch
return this.enqueueSandboxUiLifecycle(() => this.openSandboxUiNow(args, sessionEpoch))
}
private async openSandboxUiNow(
args: Parameters<AppService['openSandboxUi']>[0],
sessionEpoch: number
): Promise<void> {
const recipeNs = String(args.recipeNs || '').trim()
const recipeName = String(args.recipeName || '').trim()
if (!recipeNs || !recipeName) throw new Error('recipeNs and recipeName are required')
this.sandboxUiGeneration += 1
// An open replaces the current view whatever its outcome, so the outgoing
// view goes BEFORE the network mint: a failed mint must not leave it
// painted (with its refresh loop still minting) after the renderer has been
// told the open failed. Failure is reported only by the rejection.
await this.teardownSandboxUiView('replaced')
try {
await this.mintAndMountSandboxUiView(args, recipeNs, recipeName, sessionEpoch)
} catch (error) {
// Only this open's own view, never one another launch owns; its release
// goes out before the rejection. `open_failed` tells the renderer that
// rejection is on its way, so it reports the failure instead of an
// abandoned launch; a session that ended meanwhile is the real cause.
const reason = this.sandboxUiSessionEpoch === sessionEpoch ? 'open_failed' : 'session'
await this.teardownSandboxUiView(reason, args.launchId)
throw error
}
}
private async mintAndMountSandboxUiView(
args: Parameters<AppService['openSandboxUi']>[0],
recipeNs: string,
recipeName: string,
sessionEpoch: number
): Promise<void> {
// The close queued by a session clear only runs after this open settles, so
// the open itself must refuse to install the cleared session's cookie or
// attach a view for it.
this.assertSandboxUiSessionEpoch(sessionEpoch)
const mintedAt = Date.now()
const { setCookie } = await this.mintSandboxUiSession(recipeNs, recipeName)
this.assertSandboxUiSessionEpoch(sessionEpoch)
const driver = await import('./sandboxUiDriver.js')
const refreshModule = await import('./sandboxUiSessionRefresh.js')
this.assertSandboxUiSessionEpoch(sessionEpoch)
await driver.mountSandboxUiView({
recipeNs,
recipeName,
setCookie,
rpcProxyUrl: this.getEffectiveRpcProxyBaseUrl(),
defaultPath: args.defaultPath,
routePath: args.routePath,
parentWindow: args.parentWindow,
bounds: args.bounds,
launchId: args.launchId,
onReleased: args.onReleased,
// A teardown main did not ask for (crash, parent window closed) skips
// `teardownSandboxUiView`, so its cleanup runs here.
onClosed: () => {
// Cancel refresh first so the timer doesn't keep firing against a
// partition we're about to evict on the next mount.
refreshModule.cancelSandboxUiRefresh()
// Unpin before anything else can observe a dead surface as pinned:
// per-mount SDK state (session denials, prompt budget, rate budget)
// dies with the mount.
tryGetPluginSdkRuntime()?.unpinAllSandboxUiSurfaces()
},
onGfsOpen: uri => {
const active = tryGetPluginSdkRuntime()
const surface = driver.getActiveSandboxUi()
if (!active || !surface) return
void active.openGfsResourceFromNavigation(surface.webContentsId, uri)
},
onTitleChanged: args.onTitleChanged,
onUnauthorizedNavigation: webContentsId => {
refreshModule.handleSandboxUiUnauthorizedNavigation(webContentsId)
},
onOauthAuthorize: (oauthClientId, background) => {
void this.requestSandboxUiOauthAuthorize(
recipeNs,
recipeName,
oauthClientId,
background
).catch(err => {
const message = err instanceof Error ? err.message : String(err)
console.warn('[SandboxUI] oauth authorize-url fetch failed:', message)
args.onOauthError?.(message)
})
},
isCurrent: () => this.sandboxUiSessionEpoch === sessionEpoch,
})
this.assertSandboxUiSessionEpoch(sessionEpoch)
const activeView = driver.getActiveSandboxUi()
if (!activeView || activeView.launchId !== args.launchId) {
// The view died before the open finished (its renderer crashed, its
// window closed). An open resolves only when it leaves its view mounted,
// and its refresh loop must not attach to whatever is active now.
throw new Error('The app view closed before it finished opening')
}
// Pin the surface so the SDK broker can derive this plugin's identity from
// `webContents.id` — the plugin never asserts who it is.
tryGetPluginSdkRuntime()?.pinSandboxUiSurface({
pluginId: activeView.appRef,
pluginTitle: String(args.title || '').trim() || recipeName,
webContentsId: activeView.webContentsId,
generation: this.sandboxUiGeneration,
})
refreshModule.startSandboxUiRefresh({
recipeNs,
recipeName,
webContentsId: activeView.webContentsId,
parentWindow: args.parentWindow,
mintedAt,
// A refresh minted before a session clear can land before the queued
// close cancels this loop. Rejecting fails the attempt without writing
// the cleared session's cookie, and any retry before the close runs is
// refused before it reaches rpc-proxy, so the next session's token never
// mints for this view. The user has nothing to act on, so it is not
// reported.
refresh: async (ns, name) => {
this.assertSandboxUiSessionEpoch(sessionEpoch)
return this.mintSandboxUiSession(ns, name)
},
installCookie: async setCookieValue => {
this.assertSandboxUiSessionEpoch(sessionEpoch)
await driver.installSandboxUiCookie(setCookieValue)
},
reload: () => {
if (driver.getActiveSandboxUi()?.webContentsId !== activeView.webContentsId) return
driver.reloadActiveSandboxUiView()
},
onError: err => {
if (this.sandboxUiSessionEpoch !== sessionEpoch) return
args.onRefreshError?.(err instanceof Error ? err.message : String(err))
},
onRecovered: () => {
if (this.sandboxUiSessionEpoch !== sessionEpoch) return
args.onRefreshRecovered?.()
},
})
}
/**
* With a `launchId`, closes the view only if that launch still owns it: a
* close that arrives after its view was replaced must not take down the
* replacement. Without one, closes whatever is live; only main's own callers
* (session change, renderer replaced) do that, the renderer must always name
* its launch. Enqueued synchronously, like `openSandboxUi`.
*/
closeSandboxUi(
options: {
launchId?: string
reason?: import('./sandboxUiDriver.js').SandboxUiReleaseReason
} = {}
): Promise<void> {
return this.enqueueSandboxUiLifecycle(() =>
this.teardownSandboxUiView(options.reason ?? 'closed', options.launchId)
)
}
/**
* Reloads the document of the view `launchId` owns, in place: same view, same
* session cookie, same refresh loop, so nothing is minted. Enqueued
* synchronously like `openSandboxUi`, so it acts on the view the queue holds
* when it gets there; a launch that no longer owns the view reloads nothing.
*/
reloadSandboxUi(options: { launchId: string }): Promise<void> {
return this.enqueueSandboxUiLifecycle(async () => {
const driver = await import('./sandboxUiDriver.js')
if (driver.getActiveSandboxUi()?.launchId !== options.launchId) return
driver.reloadActiveSandboxUiView()
})
}
private async teardownSandboxUiView(
reason: import('./sandboxUiDriver.js').SandboxUiReleaseReason,
onlyLaunchId?: string
): Promise<void> {
const driver = await import('./sandboxUiDriver.js')
const refreshModule = await import('./sandboxUiSessionRefresh.js')
if (onlyLaunchId !== undefined && driver.getActiveSandboxUi()?.launchId !== onlyLaunchId) {
return
}
// Neither must keep the view from being unmounted and released.
try {
refreshModule.cancelSandboxUiRefresh()
} catch (error) {
console.error('[SandboxUI] Could not cancel the session refresh of a closing view:', error)
}
try {
tryGetPluginSdkRuntime()?.unpinAllSandboxUiSurfaces()
} catch (error) {
console.error('[SandboxUI] Could not unpin the surfaces of a closing view:', error)
}
await driver.unmountSandboxUiView(reason)
}
async createSandboxUiDeepLink(teamId?: string): Promise<{ url: string }> {
const driver = await import('./sandboxUiDriver.js')
const { buildSandboxUiWebLink } = await import('./sandboxUiDeepLinks.js')
const location = driver.getActiveSandboxUiLocation()
if (!location) throw new Error('No app is currently open')
const profileUiBaseUrl = await this.resolveProfileUiBaseUrl(undefined, {
fallbackOnLookupError: false,
})
return {
url: buildSandboxUiWebLink(profileUiBaseUrl, {
...location,
teamId: String(teamId || '').trim() || undefined,
}),
}
}
async setSandboxUiBounds(bounds: import('./sandboxUiDriver.js').SandboxUiBounds): Promise<void> {
const { setSandboxUiBounds } = await import('./sandboxUiDriver.js')
setSandboxUiBounds(bounds)
}
async setSandboxUiVisible(visible: boolean): Promise<void> {
const { setSandboxUiVisible } = await import('./sandboxUiDriver.js')
setSandboxUiVisible(visible)
}
async captureSandboxUiPreview(): Promise<string | null> {
const { captureSandboxUiPreview } = await import('./sandboxUiDriver.js')
return captureSandboxUiPreview()
}
async findInActiveSandboxUi(
query: string,
operation: import('./sandboxUiDriver.js').SandboxUiFindOperation,
clientRequestId: number,
onResult: (result: import('./sandboxUiDriver.js').SandboxUiFindResult) => void
): Promise<import('./sandboxUiDriver.js').SandboxUiFindStartResult> {
const { findInActiveSandboxUi } = await import('./sandboxUiDriver.js')
return findInActiveSandboxUi(query, operation, clientRequestId, onResult)
}
async stopActiveSandboxUiFind(): Promise<void> {
const { stopActiveSandboxUiFind } = await import('./sandboxUiDriver.js')
stopActiveSandboxUiFind()
}
async focusActiveSandboxUi(): Promise<boolean> {
const { focusActiveSandboxUi } = await import('./sandboxUiDriver.js')
return focusActiveSandboxUi()
}
/**
* Embed-side refresh request. The IPC layer hands us the sender's
* `webContents.id`; we delegate to the refresh module which gates the
* call by the pinning map and per-view rate-limit.
*/
async requestSandboxUiRefresh(senderId: number): Promise<void> {
const refreshModule = await import('./sandboxUiSessionRefresh.js')
await refreshModule.handleEmbedRefreshRequest(senderId)
}
async listContextSharedFilesystems(
contextId: string
): Promise<{ items: ContextSharedFilesystemSummary[] }> {
const token = this.requireSessionToken()
if (!contextId.trim()) throw new Error('contextId is required')
try {
return await this.sharedFilesClient.listAttached(token, contextId.trim())
} catch (error) {
if (AppService.isForbiddenSharedFilesListError(error)) {
return { items: [] }
}
throw error
}
}
async listSharedFilesystemDirectory(
contextId: string,
sfsName: string,
relPath: string
): Promise<SharedFileListResult> {
const token = this.requireSessionToken()
if (!contextId.trim()) throw new Error('contextId is required')
if (!sfsName.trim()) throw new Error('sfsName is required')
return this.sharedFilesClient.listDirectory(token, contextId.trim(), sfsName.trim(), relPath)
}
async downloadSharedFile(
contextId: string,
sfsName: string,
relPath: string
): Promise<{ bytes: Buffer; filename: string; contentType: string | null }> {
const token = this.requireSessionToken()
if (!contextId.trim()) throw new Error('contextId is required')
if (!sfsName.trim()) throw new Error('sfsName is required')
if (!relPath.trim()) throw new Error('relPath is required')
return this.sharedFilesClient.downloadFile(token, contextId.trim(), sfsName.trim(), relPath)
}
}