Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { contextBridge, ipcRenderer, webUtils } from 'electron'
import type { DesktopCommandId, DesktopCommandSource } from './desktopCommands.js'
import type { PluginConsentRequest } from './pluginSdkProtocol.js'
import type {
DesktopRuntimeConfigHandoffSelection,
EntityChangeStreamEvent,
HostMessageRequest,
ProfileSettingsOpenOptions,
SandboxUiDeepLinkEnvelope,
SandboxUiReleasedEvent,
} from './types.js'
// Sandboxed Electron preloads cannot load relative runtime modules. Keep this
// allowlist self-contained and pin it to the authoritative registry in
// desktopCommands.test.ts, matching the existing sandbox embed-preload pattern.
const DESKTOP_COMMAND_IDS = new Set<DesktopCommandId>([
'chat.newTab',
'chat.switcher',
'chat.closeTab',
'tabs.select1',
'tabs.select2',
'tabs.select3',
'tabs.select4',
'tabs.select5',
'tabs.select6',
'tabs.select7',
'tabs.select8',
'tabs.selectLast',
'tabs.next',
'tabs.previous',
'search.open',
'search.current',
'composer.focus',
'commands.open',
'settings.shortcuts',
'settings.open',
'auth.logout',
'navigate.chat',
'navigate.apps',
'navigate.agents',
'notifications.open',
'navigate.plugins',
'navigate.connectors',
'navigate.files',
'sidebar.toggle',
'app.refresh',
'app.backToApps',
])
/**
* Producer-side cancellation wiring (folder-zip Stop, R1-M1): a cancellable
* invoke carries a requestId; if the caller's signal aborts, main aborts the
* in-flight request. An already-aborted signal never starts producer work —
* no invoke, no gfs:abort event (R2-L3). Kept INLINE: the sandboxed preload
* must stay free of relative value imports (self-containment contract).
*/
function cancellableGfsInvoke<T>(
channel: string,
payload: Record<string, unknown>,
signal?: AbortSignal
): Promise<T> {
if (!signal) return ipcRenderer.invoke(channel, payload) as Promise<T>
if (signal.aborted) {
return Promise.reject(new DOMException('Request was stopped before it started.', 'AbortError'))
}
const requestId = crypto.randomUUID()
const onAbort = () => ipcRenderer.send('gfs:abort', { requestId })
signal.addEventListener('abort', onAbort, { once: true })
return ipcRenderer
.invoke(channel, { ...payload, requestId })
.finally(() => signal.removeEventListener('abort', onAbort)) as Promise<T>
}
function isDesktopCommandId(value: unknown): value is DesktopCommandId {
return typeof value === 'string' && DESKTOP_COMMAND_IDS.has(value as DesktopCommandId)
}
const clerum = Object.freeze({
shortcuts: {
onCommand: (callback: (commandId: DesktopCommandId, source: DesktopCommandSource) => void) => {
const listener = (
_event: Electron.IpcRendererEvent,
payload: { commandId?: unknown; source?: unknown }
) => {
if (
isDesktopCommandId(payload?.commandId) &&
(payload?.source === 'host' || payload?.source === 'sandbox')
) {
callback(payload.commandId, payload.source)
}
}
ipcRenderer.on('shortcuts:command', listener)
return () => ipcRenderer.off('shortcuts:command', listener)
},
},
auth: {
getSessionState: () => ipcRenderer.invoke('auth:getSessionState'),
getSessionGeneration: () => ipcRenderer.invoke('auth:getSessionGeneration'),
getDependenciesHealth: () => ipcRenderer.invoke('auth:getDependenciesHealth'),
getRuntimeConfigState: () => ipcRenderer.invoke('auth:getRuntimeConfigState'),
selectRuntimeConfig: (optionId: string) =>
ipcRenderer.invoke('auth:selectRuntimeConfig', { optionId }),
selectRuntimeConfigForHandoff: (optionId: string, expectedSessionGeneration: number) =>
ipcRenderer.invoke('auth:selectRuntimeConfigForHandoff', {
optionId,
expectedSessionGeneration,
}) as Promise<DesktopRuntimeConfigHandoffSelection>,
clearRuntimeConfigSelection: () => ipcRenderer.invoke('auth:clearRuntimeConfigSelection'),
saveRuntimeConfig: (
config: {
externalRestApiBaseUrl: string
rpcProxyBaseUrl?: string
appName?: string
},
expectedSessionGeneration?: number
) =>
ipcRenderer.invoke(
'auth:saveRuntimeConfig',
expectedSessionGeneration === undefined ? config : { ...config, expectedSessionGeneration }
),
deleteRuntimeConfig: (optionId: string) =>
ipcRenderer.invoke('auth:deleteRuntimeConfig', { optionId }),
googleLogin: (idToken: string) => ipcRenderer.invoke('auth:googleLogin', { idToken }),
passwordLogin: (email: string, password: string) =>
ipcRenderer.invoke('auth:passwordLogin', { email, password }),
diagnoseLoginBackend: () => ipcRenderer.invoke('auth:diagnoseLoginBackend'),
probeLocalhostReachable: () => ipcRenderer.invoke('auth:probeLocalhostReachable'),
openDeploymentDocs: () => ipcRenderer.invoke('auth:openDeploymentDocs'),
openHostedSignup: () => ipcRenderer.invoke('auth:openHostedSignup'),
startDesktopSetup: (email: string) => ipcRenderer.invoke('auth:startDesktopSetup', { email }),
openForgotPassword: (email?: string) =>
ipcRenderer.invoke('auth:openForgotPassword', { email }),
openProfileSettings: (email?: string, options?: ProfileSettingsOpenOptions) =>
ipcRenderer.invoke('auth:openProfileSettings', { email, ...options }),
completeDesktopSetup: (email: string, authorizationToken: string) =>
ipcRenderer.invoke('auth:completeDesktopSetup', { email, authorizationToken }),
onDesktopSetupToken: (
callback: (payload: { email: string; authorizationToken: string }) => void
) => {
const listener = (
_event: Electron.IpcRendererEvent,
payload: { email: string; authorizationToken: string }
) => callback(payload)
ipcRenderer.on('auth:desktopSetupToken', listener)
return () => ipcRenderer.off('auth:desktopSetupToken', listener)
},
onDesktopEnvironmentSetup: (
callback: (payload: { externalRestApiBaseUrl: string; appName?: string }) => void
) => {
const listener = (
_event: Electron.IpcRendererEvent,
payload: {
externalRestApiBaseUrl: string
appName?: string
}
) => callback(payload)
ipcRenderer.on('auth:desktopEnvironmentSetup', listener)
return () => ipcRenderer.off('auth:desktopEnvironmentSetup', listener)
},
getDesktopReleaseStatus: () => ipcRenderer.invoke('auth:getDesktopReleaseStatus'),
getDesktopAppInfo: () => ipcRenderer.invoke('auth:getDesktopAppInfo'),
openDesktopRelease: (releaseUrl: string) =>
ipcRenderer.invoke('auth:openDesktopRelease', { releaseUrl }),
onExternalLogout: (callback: () => void) => {
const listener = () => callback()
ipcRenderer.on('auth:externalLogout', listener)
return () => ipcRenderer.off('auth:externalLogout', listener)
},
logout: () => ipcRenderer.invoke('auth:logout'),
},
team: {
list: () => ipcRenderer.invoke('team:list'),
members: () => ipcRenderer.invoke('team:members'),
directory: () => ipcRenderer.invoke('team:directory'),
initialDirectory: () => ipcRenderer.invoke('team:initialDirectory'),
switch: (teamId: string) => ipcRenderer.invoke('team:switch', { teamId }),
},
gfs: {
resolve: (uri: string) => ipcRenderer.invoke('gfs:resolve', { uri }),
download: (uri: string, options?: { maxBytes?: number; signal?: AbortSignal }) =>
cancellableGfsInvoke('gfs:download', { uri, maxBytes: options?.maxBytes }, options?.signal),
downloadPreview: (uri: string, maxBytes: number) =>
ipcRenderer.invoke('gfs:downloadPreview', { uri, maxBytes }),
listAccessible: (drive?: string, cursor?: string) =>
ipcRenderer.invoke('gfs:listAccessible', { drive, cursor }),
listChildren: (
resourceId: string,
drive?: string,
cursor?: string,
options?: { signal?: AbortSignal }
) => cancellableGfsInvoke('gfs:listChildren', { resourceId, drive, cursor }, options?.signal),
affordances: (resourceId: string, drive?: string) =>
ipcRenderer.invoke('gfs:affordances', { resourceId, drive }),
zipStream: {
start: () => ipcRenderer.invoke('gfs:zipStream:start'),
append: (jobId: string, name: string, bytes: ArrayBuffer) =>
ipcRenderer.invoke('gfs:zipStream:append', { jobId, name, bytes }),
// The folder-zip transfer (R1-H2): the MAIN process fetches the
// resource and writes it into the archive chunk by chunk, so the payload
// never crosses this boundary. The walk's stop signal rides along as a
// requestId, exactly like the other cancellable GFS calls.
appendFromUri: (
jobId: string,
name: string,
uri: string,
options?: { maxBytes?: number; signal?: AbortSignal }
) =>
cancellableGfsInvoke(
'gfs:zipStream:appendFromUri',
{ jobId, name, uri, maxBytes: options?.maxBytes },
options?.signal
),
finish: (jobId: string, suggestedName: string) =>
ipcRenderer.invoke('gfs:zipStream:finish', { jobId, suggestedName }),
abort: (jobId: string) => ipcRenderer.invoke('gfs:zipStream:abort', { jobId }),
},
createFolder: (parentResourceId: string, name: string, drive?: string) =>
ipcRenderer.invoke('gfs:createFolder', { parentResourceId, name, drive }),
createFile: (parentResourceId: string, name: string, encodedData: string, drive?: string) =>
ipcRenderer.invoke('gfs:createFile', { parentResourceId, name, encodedData, drive }),
createFileFromPath: (
parentResourceId: string,
name: string,
filePath: string,
drive?: string
) => ipcRenderer.invoke('gfs:createFileFromPath', { parentResourceId, name, filePath, drive }),
startFileUpload: (
parentResourceId: string,
name: string,
filePath: string,
drive?: string,
resumeUploadId?: string
) =>
ipcRenderer.invoke('gfs:startFileUpload', {
parentResourceId,
name,
filePath,
drive,
resumeUploadId,
}),
startFileReplace: (
resourceId: string,
filePath: string,
drive?: string,
ifMatch?: number,
resumeUploadId?: string
) =>
ipcRenderer.invoke('gfs:startFileReplace', {
resourceId,
filePath,
drive,
ifMatch,
resumeUploadId,
}),
getUploadSnapshot: (uploadId: string, drive = 'main') =>
ipcRenderer.invoke('gfs:getUploadSnapshot', { uploadId, drive }),
listUploadSessions: (drive = 'main') => ipcRenderer.invoke('gfs:listUploadSessions', { drive }),
pauseUpload: (uploadId: string, drive = 'main') =>
ipcRenderer.invoke('gfs:pauseUpload', { uploadId, drive }),
resumeUpload: (uploadId: string, drive = 'main') =>
ipcRenderer.invoke('gfs:resumeUpload', { uploadId, drive }),
cancelUpload: (uploadId: string, drive = 'main') =>
ipcRenderer.invoke('gfs:cancelUpload', { uploadId, drive }),
replaceFile: (resourceId: string, encodedData: string, drive?: string, ifMatch?: number) =>
ipcRenderer.invoke('gfs:replaceFile', { resourceId, encodedData, drive, ifMatch }),
replaceFileFromPath: (resourceId: string, filePath: string, drive?: string, ifMatch?: number) =>
ipcRenderer.invoke('gfs:replaceFileFromPath', { resourceId, filePath, drive, ifMatch }),
getPathForFile: (file: File) => webUtils.getPathForFile(file),
renameResource: (resourceId: string, newName: string, drive?: string, ifMatch?: number) =>
ipcRenderer.invoke('gfs:renameResource', { resourceId, newName, drive, ifMatch }),
moveResource: (
resourceId: string,
destinationId: string,
drive?: string,
ifMatch?: number,
newName?: string
) =>
ipcRenderer.invoke('gfs:moveResource', {
resourceId,
destinationId,
drive,
ifMatch,
newName,
}),
deleteResource: (resourceId: string, drive?: string, ifMatch?: number) =>
ipcRenderer.invoke('gfs:deleteResource', { resourceId, drive, ifMatch }),
grant: (
resourceId: string,
subjectKeys: string[],
bits: string[],
drive?: string,
inherit?: boolean
) => ipcRenderer.invoke('gfs:grant', { resourceId, subjectKeys, bits, drive, inherit }),
listGrants: (resourceId: string, drive?: string) =>
ipcRenderer.invoke('gfs:listGrants', { resourceId, drive }),
revokeGrant: (grantId: string) => ipcRenderer.invoke('gfs:revokeGrant', { grantId }),
listShares: (resourceId: string, drive?: string) =>
ipcRenderer.invoke('gfs:listShares', { resourceId, drive }),
revokeShare: (shareId: string) => ipcRenderer.invoke('gfs:revokeShare', { shareId }),
// A desktop share grants READ access only (the minimal shared capability) —
// unlike `grant`, it takes no permission bits by design. The server still
// enforces the caller holds read + share (no-escalation).
createShare: (resourceId: string, subjectKeys: string[], drive?: string) =>
ipcRenderer.invoke('gfs:createShare', { resourceId, subjectKeys, drive }),
},
agents: {
listMine: () => ipcRenderer.invoke('agents:listMine'),
},
approvals: {
listPending: (limit?: number) => ipcRenderer.invoke('approvals:listPending', { limit }),
decide: (
approvalId: string,
decision: 'approve' | 'deny',
note?: string,
options?: { teamId?: string | null }
) => ipcRenderer.invoke('approvals:decide', { approvalId, decision, note, ...options }),
},
notifications: {
isSupported: () => ipcRenderer.invoke('notifications:isSupported'),
show: (payload: {
id: string
title: string
body: string
tag?: string
silent?: boolean
actions?: Array<{ action: string; title: string }>
}) => ipcRenderer.invoke('notifications:show', payload),
onClick: (callback: (payload: { id: string }) => void) => {
const listener = (_event: Electron.IpcRendererEvent, payload: { id: string }) =>
callback(payload)
ipcRenderer.on('notifications:click', listener)
return () => ipcRenderer.off('notifications:click', listener)
},
onAction: (callback: (payload: { id: string; action: string }) => void) => {
const listener = (
_event: Electron.IpcRendererEvent,
payload: { id: string; action: string }
) => callback(payload)
ipcRenderer.on('notifications:action', listener)
return () => ipcRenderer.off('notifications:action', listener)
},
onFailed: (callback: (payload: { id: string; error: string }) => void) => {
const listener = (
_event: Electron.IpcRendererEvent,
payload: { id: string; error: string }
) => callback(payload)
ipcRenderer.on('notifications:failed', listener)
return () => ipcRenderer.off('notifications:failed', listener)
},
subscribe: async (onEvent: (event: unknown) => void) => {
const started = (await ipcRenderer.invoke('notifications:streamStart')) as {
streamId: string
}
const streamId = String(started?.streamId || '').trim()
if (!streamId) throw new Error('Failed to start notification stream')
const listener = (_event: unknown, payload: unknown) => {
const parsed = payload as { streamId?: string; event?: unknown }
if (parsed?.streamId !== streamId) return
onEvent(parsed.event)
}
ipcRenderer.on('notifications:streamEvent', listener)
return async () => {
ipcRenderer.removeListener('notifications:streamEvent', listener)
await ipcRenderer.invoke('notifications:streamStop', { streamId })
}
},
status: () => ipcRenderer.invoke('notifications:streamStatus'),
ack: (notificationId: string) =>
ipcRenderer.invoke('notifications:ack', { notificationId }) as Promise<{
ok: boolean
status: string
}>,
},
entityChanges: {
subscribe: async (onEvent: (event: EntityChangeStreamEvent) => void) => {
let streamId = ''
const pending: unknown[] = []
const listener = (_event: unknown, payload: unknown) => {
const parsed = payload as { streamId?: string; event?: EntityChangeStreamEvent }
if (!streamId) {
if (pending.length < 100) pending.push(payload)
return
}
if (parsed?.streamId === streamId && parsed.event) onEvent(parsed.event)
}
ipcRenderer.on('entityChanges:streamEvent', listener)
try {
const started = (await ipcRenderer.invoke('entityChanges:streamStart')) as {
streamId: string
}
streamId = String(started?.streamId || '').trim()
if (!streamId) throw new Error('Failed to start entity-change stream')
for (const item of pending) {
const parsed = item as { streamId?: string; event?: EntityChangeStreamEvent }
if (parsed?.streamId === streamId && parsed.event) onEvent(parsed.event)
}
pending.length = 0
} catch (error) {
ipcRenderer.removeListener('entityChanges:streamEvent', listener)
throw error
}
return async () => {
ipcRenderer.removeListener('entityChanges:streamEvent', listener)
await ipcRenderer.invoke('entityChanges:streamStop', { streamId })
}
},
},
notificationPreferences: {
get: () => ipcRenderer.invoke('notificationPreferences:get'),
update: (payload: {
preferredMedium: 'telegram' | 'slack' | null
channelFallbackEnabled: boolean
}) => ipcRenderer.invoke('notificationPreferences:update', payload),
},
socialChannels: {
getSummary: () => ipcRenderer.invoke('socialChannels:getSummary'),
},
access: {
getCatalog: () => ipcRenderer.invoke('access:getCatalog'),
refreshCatalog: () => ipcRenderer.invoke('access:refreshCatalog'),
},
sharedFiles: {
listAttached: (contextId: string) =>
ipcRenderer.invoke('sharedFiles:listAttached', { contextId }),
listDirectory: (contextId: string, sfsName: string, path: string) =>
ipcRenderer.invoke('sharedFiles:listDirectory', { contextId, sfsName, path }),
download: (contextId: string, sfsName: string, path: string) =>
ipcRenderer.invoke('sharedFiles:download', { contextId, sfsName, path }),
},
rpc: {
listServers: (hostRefs?: string[]) => ipcRenderer.invoke('rpc:listServers', { hostRefs }),
invokeHostMessage: (
hostRef: string,
payload: HostMessageRequest,
hostRefs?: string[],
options?: { async?: boolean }
) => ipcRenderer.invoke('rpc:invokeHostMessage', { hostRef, payload, hostRefs, options }),
getTaskResult: (hostRef: string, taskId: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:getTaskResult', { hostRef, taskId, hostRefs }),
getHostStatus: (hostRef: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:getHostStatus', { hostRef, hostRefs }),
prewarmHost: (hostRef: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:prewarmHost', { hostRef, hostRefs }),
getHostActivity: (
hostRef: string,
limit?: number,
sinceEventId?: string,
hostRefs?: string[]
) => ipcRenderer.invoke('rpc:getHostActivity', { hostRef, limit, sinceEventId, hostRefs }),
subscribeHostStatus: async (
hostRef: string,
hostRefs: string[] | undefined,
onEvent: (event: unknown) => void
) => {
const started = (await ipcRenderer.invoke('rpc:hostStatusStreamStart', {
hostRef,
hostRefs,
})) as { streamId: string }
const streamId = String(started?.streamId || '').trim()
if (!streamId) throw new Error('Failed to start host status stream')
const listener = (_event: unknown, payload: unknown) => {
const parsed = payload as { streamId?: string; event?: unknown }
if (parsed?.streamId !== streamId) return
onEvent(parsed.event)
}
ipcRenderer.on('rpc:hostStatusStreamEvent', listener)
return async () => {
ipcRenderer.removeListener('rpc:hostStatusStreamEvent', listener)
await ipcRenderer.invoke('rpc:hostStatusStreamStop', { streamId })
}
},
subscribeHostActivity: async (
hostRef: string,
hostRefs: string[] | undefined,
onEvent: (event: unknown) => void
) => {
const started = (await ipcRenderer.invoke('rpc:hostActivityStreamStart', {
hostRef,
hostRefs,
})) as { streamId: string }
const streamId = String(started?.streamId || '').trim()
if (!streamId) throw new Error('Failed to start host activity stream')
const listener = (_event: unknown, payload: unknown) => {
const parsed = payload as { streamId?: string; event?: unknown }
if (parsed?.streamId !== streamId) return
onEvent(parsed.event)
}
ipcRenderer.on('rpc:hostActivityStreamEvent', listener)
return async () => {
ipcRenderer.removeListener('rpc:hostActivityStreamEvent', listener)
await ipcRenderer.invoke('rpc:hostActivityStreamStop', { streamId })
}
},
subscribeTaskProgress: async (
hostRef: string,
taskId: string,
onEvent: (event: unknown) => void
) => {
const started = (await ipcRenderer.invoke('rpc:taskProgressStreamStart', {
hostRef,
taskId,
})) as { streamId: string }
const streamId = String(started?.streamId || '').trim()
if (!streamId) throw new Error('Failed to start task progress stream')
const listener = (_event: unknown, payload: unknown) => {
const parsed = payload as { streamId?: string; event?: unknown }
if (parsed?.streamId !== streamId) return
onEvent(parsed.event)
}
ipcRenderer.on('rpc:taskProgressStreamEvent', listener)
return async () => {
ipcRenderer.removeListener('rpc:taskProgressStreamEvent', listener)
await ipcRenderer.invoke('rpc:taskProgressStreamStop', { streamId })
}
},
cancelTask: (hostRef: string, taskId: string): Promise<void> =>
ipcRenderer.invoke('rpc:cancelTask', { hostRef, taskId }),
approveToolCall: (
hostRef: string,
taskId: string,
toolCallId: string,
hostRefs?: string[],
options?: { teamId?: string | null }
) =>
ipcRenderer.invoke('rpc:approveToolCall', {
hostRef,
taskId,
toolCallId,
hostRefs,
...options,
}),
denyToolCall: (
hostRef: string,
taskId: string,
toolCallId: string,
reason: string,
hostRefs?: string[],
options?: { teamId?: string | null }
) =>
ipcRenderer.invoke('rpc:denyToolCall', {
hostRef,
taskId,
toolCallId,
reason,
hostRefs,
...options,
}),
listArtifacts: (hostRef: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:listArtifacts', { hostRef, hostRefs }),
downloadArtifact: (hostRef: string, filename: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:downloadArtifact', { hostRef, filename, hostRefs }),
listSessions: (
hostRef: string,
hostRefs?: string[],
query?: import('./types.js').SessionsListQuery
) => ipcRenderer.invoke('rpc:listSessions', { hostRef, hostRefs, query }),
loadSessionMessages: (
hostRef: string,
agent: string,
chatId: string,
hostRefs?: string[],
query?: import('./types.js').SessionMessagesQuery
) => ipcRenderer.invoke('rpc:loadSessionMessages', { hostRef, agent, chatId, hostRefs, query }),
getContextBreakdown: (hostRef: string, agent: string, chatId: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:getContextBreakdown', { hostRef, agent, chatId, hostRefs }),
getHostModels: (hostRef: string, chatId: string, hostRefs?: string[]) =>
ipcRenderer.invoke('rpc:getHostModels', { hostRef, chatId, hostRefs }),
setHostModel: (
hostRef: string,
chatId: string,
model: string,
hostRefs?: string[],
expectedRevision?: number
) =>
ipcRenderer.invoke('rpc:setHostModel', {
hostRef,
chatId,
model,
hostRefs,
expectedRevision,
}),
// Spec 15 Fase B — explicit user rename. No `hostRefs` fleet arg: the main
// process scopes the write token to this single host.
renameSession: (hostRef: string, agent: string, chatId: string, title: string) =>
ipcRenderer.invoke('rpc:renameSession', { hostRef, agent, chatId, title }),
getTokenMetadata: () => ipcRenderer.invoke('rpc:getTokenMetadata'),
// U5 (mcp-oauth reactive consent): "Connect <server>" — open the provider
// authorize-URL for a task that suspended with `connect_required`. Host-bound
// to the suspended conversation's hostRef (RPC tokens require a hostRef).
connectMcpServer: (
mcpServerName: string,
hostRef: string,
contextId?: string,
options?: { confirmShared?: boolean }
) => ipcRenderer.invoke('rpc:connectMcpServer', { mcpServerName, hostRef, contextId, options }),
// Proactive connectors panel (spec 11 U2): the classified per-agent fleet.
listConnectors: () => ipcRenderer.invoke('rpc:listConnectors'),
// Proactive disconnect (spec 11 U4): revoke an mcp-server's OAuth grant.
// `options.shared` only drives the native confirm-dialog copy.
disconnectMcpServer: (
mcpServerName: string,
hostRef: string,
contextId?: string,
options?: { shared?: boolean }
) =>
ipcRenderer.invoke('rpc:disconnectMcpServer', { mcpServerName, hostRef, contextId, options }),
// Fired when the OAuth deep-link returns with `source=mcp`. The renderer
// correlates `mcpServerName` to its suspended entries and resumes the task.
onMcpOauthCompleted: (
callback: (args: { mcpServerName: string; provider: string }) => void
) => {
const listener = (
_event: Electron.IpcRendererEvent,
args: { mcpServerName: string; provider: string }
) => callback(args)
ipcRenderer.on('rpc:mcpOauthCompleted', listener)
return () => ipcRenderer.off('rpc:mcpOauthCompleted', listener)
},
},
workflows: {
list: () => ipcRenderer.invoke('workflows:list'),
read: (ns: string, name: string) => ipcRenderer.invoke('workflows:read', { ns, name }),
health: (ns: string, name: string) => ipcRenderer.invoke('workflows:health', { ns, name }),
trigger: (
ns: string,
name: string,
inputs?: Record<string, unknown>,
idempotencyKey?: string
) => ipcRenderer.invoke('workflows:trigger', { ns, name, inputs, idempotencyKey }),
runs: (ns: string, name: string, limit?: number) =>
ipcRenderer.invoke('workflows:runs', { ns, name, limit }),
listRunArtifacts: (ns: string, name: string, runId: string) =>
ipcRenderer.invoke('workflows:runArtifacts', { ns, name, runId }),
downloadRunArtifact: (ns: string, name: string, runId: string, artifactName: string) =>
ipcRenderer.invoke('workflows:downloadRunArtifact', { ns, name, runId, artifactName }),
},
app: {
openUrl: (url: string) => ipcRenderer.invoke('app:openUrl', { url }),
rendererReady: () => ipcRenderer.invoke('app:rendererReady'),
},
window: {
getVisibility: () => ipcRenderer.invoke('window:getVisibility'),
getControlsState: () => ipcRenderer.invoke('window:getControlsState'),
minimize: () => ipcRenderer.invoke('window:minimize'),
toggleMaximize: () => ipcRenderer.invoke('window:toggleMaximize'),
close: () => ipcRenderer.invoke('window:close'),
onVisibilityChange: (callback: (state: { visible: boolean; focused: boolean }) => void) => {
const listener = (
_event: Electron.IpcRendererEvent,
state: { visible: boolean; focused: boolean }
) => callback(state)
ipcRenderer.on('window:visibility', listener)
return () => ipcRenderer.off('window:visibility', listener)
},
onControlsStateChange: (
callback: (state: { fullscreen: boolean; maximized: boolean }) => void
) => {
const listener = (
_event: Electron.IpcRendererEvent,
state: { fullscreen: boolean; maximized: boolean }
) => callback(state)
ipcRenderer.on('window:controlsState', listener)
return () => ipcRenderer.off('window:controlsState', listener)
},
},
system: {
// GAP-D1 (§4.5-4): fired after OS sleep/resume or screen unlock so the renderer
// reconciles chats with in-flight tasks and re-attaches dead streams.
onResume: (callback: () => void) => {
const listener = () => callback()
ipcRenderer.on('system:resume', listener)
return () => ipcRenderer.off('system:resume', listener)
},
},
desktop: {
openWindow: (args: { hostRef: string }) => ipcRenderer.invoke('desktop:openWindow', args),
closeWindow: (args: { hostRef: string }) => ipcRenderer.invoke('desktop:closeWindow', args),
getStatus: (args: { hostRef: string }) => ipcRenderer.invoke('desktop:getStatus', args),
onWindowClosed: (callback: (args: { hostRef: string }) => void) => {
const listener = (_event: Electron.IpcRendererEvent, args: { hostRef: string }) =>
callback(args)
ipcRenderer.on('desktop:windowClosed', listener)
return () => ipcRenderer.off('desktop:windowClosed', listener)
},
},
chat: {
list: (agentRef: string) => ipcRenderer.invoke('chat:list', { agentRef }),
create: (agentRef: string, chatId: string) =>
ipcRenderer.invoke('chat:create', { agentRef, chatId }),
rename: (agentRef: string, chatId: string, title: string, bindingGeneration: number) =>
ipcRenderer.invoke('chat:rename', { agentRef, chatId, title, bindingGeneration }),
getBindingGeneration: () => ipcRenderer.invoke('chat:bindingGeneration'),
captureDeleteFence: (expectedAuthorityScope: import('./types.js').ChatAuthorityScope) =>
ipcRenderer.invoke('chat:captureDeleteFence', { expectedAuthorityScope }),
delete: (agentRef: string, chatId: string, fence: import('./types.js').ChatDeleteFence) =>
ipcRenderer.invoke('chat:delete', { version: 3, agentRef, chatId, fence }),
loadMessages: (agentRef: string, chatId: string, limit?: number, offset?: number) =>
ipcRenderer.invoke('chat:loadMessages', { agentRef, chatId, limit, offset }),
appendMessages: (agentRef: string, chatId: string, messages: unknown[]) =>
ipcRenderer.invoke('chat:appendMessages', { agentRef, chatId, messages }),
upsertMessages: (agentRef: string, chatId: string, messages: unknown[]) =>
ipcRenderer.invoke('chat:upsertMessages', { agentRef, chatId, messages }),
replaceMessages: (
agentRef: string,
chatId: string,
messages: unknown[],
options?: import('./types.js').ReplaceChatMessagesOptions
) => ipcRenderer.invoke('chat:replaceMessages', { agentRef, chatId, messages, options }),
backfillCounters: (agentRef: string, chatId: string, messages: unknown[]) =>
ipcRenderer.invoke('chat:backfillCounters', { agentRef, chatId, messages }),
markUnreadTerminal: (agentRef: string, chatId: string) =>
ipcRenderer.invoke('chat:markUnreadTerminal', { agentRef, chatId }),
clearUnreadTerminal: (agentRef: string, chatId: string) =>
ipcRenderer.invoke('chat:clearUnreadTerminal', { agentRef, chatId }),
getLastActive: (agentRef: string) => ipcRenderer.invoke('chat:getLastActive', { agentRef }),
setLastActive: (agentRef: string, chatId: string) =>
ipcRenderer.invoke('chat:setLastActive', { agentRef, chatId }),
getIndex: (agentRef: string) => ipcRenderer.invoke('chat:getIndex', { agentRef }),
reconcileServerSessions: (
agentRef: string,
sessions: Array<{ chatId: string; lastActivityAt?: string; title?: string }>
) => ipcRenderer.invoke('chat:reconcileSessions', { agentRef, sessions }),
dismissOnboarding: (agentRef: string) =>
ipcRenderer.invoke('chat:dismissOnboarding', { agentRef }),
},
sandboxUi: {
listApps: () => ipcRenderer.invoke('sandboxUi:listApps'),
mintSession: (recipeNs: string, recipeName: string) =>
ipcRenderer.invoke('sandboxUi:mintSession', { recipeNs, recipeName }),
open: (args: {
recipeNs: string
recipeName: string
title?: string
defaultPath?: string
routePath?: string
bounds: { x: number; y: number; width: number; height: number; dpr?: number }
launchId: string
}) => ipcRenderer.invoke('sandboxUi:open', args),
// Closes that launch's view only if it is still the live one.
close: (args: { launchId: string }) => ipcRenderer.invoke('sandboxUi:close', args),
// Reloads that launch's view in place only if it is still the live one.
reload: (args: { launchId: string }) => ipcRenderer.invoke('sandboxUi:reload', args),
copyDeepLink: (teamId?: string) => ipcRenderer.invoke('sandboxUi:copyDeepLink', { teamId }),
listPendingDeepLinks: () => ipcRenderer.invoke('sandboxUi:listPendingDeepLinks'),
clearPendingDeepLinks: () => ipcRenderer.invoke('sandboxUi:clearPendingDeepLinks'),
acknowledgeDeepLink: (id: number) =>
ipcRenderer.invoke('sandboxUi:acknowledgeDeepLink', { id }),
setBounds: (bounds: { x: number; y: number; width: number; height: number; dpr?: number }) =>
ipcRenderer.invoke('sandboxUi:setBounds', { bounds }),
setVisible: (visible: boolean) => ipcRenderer.invoke('sandboxUi:setVisible', { visible }),
capturePreview: () => ipcRenderer.invoke('sandboxUi:capturePreview'),
findInPage: (
query: string,
options: { operation: 'start' | 'next' | 'previous'; clientRequestId: number }
) =>
ipcRenderer.invoke('sandboxUi:findInPage', { query, ...options }) as Promise<
| { status: 'started'; requestId: number }
| { status: 'unavailable'; reason: 'no-active-view' | 'document-loading' | 'no-session' }
>,
stopFindInPage: () => ipcRenderer.invoke('sandboxUi:stopFindInPage') as Promise<void>,
focusActive: () => ipcRenderer.invoke('sandboxUi:focusActive') as Promise<boolean>,
onFindResult: (
callback: (result: {
requestId: number
clientRequestId: number
activeMatchOrdinal: number
matches: number
finalUpdate: boolean
}) => void
) => {
const listener = (_event: unknown, result: unknown) => {
const value = result as Record<string, unknown>
if (
Number.isInteger(value?.requestId) &&
Number.isSafeInteger(value?.clientRequestId) &&
Number(value.clientRequestId) > 0 &&
Number.isInteger(value?.activeMatchOrdinal) &&
Number.isInteger(value?.matches) &&
typeof value?.finalUpdate === 'boolean'
) {
callback({
requestId: Number(value.requestId),
clientRequestId: Number(value.clientRequestId),
activeMatchOrdinal: Number(value.activeMatchOrdinal),
matches: Number(value.matches),
finalUpdate: value.finalUpdate,
})
}
}
ipcRenderer.on('sandboxUi:findResult', listener)
return () => ipcRenderer.off('sandboxUi:findResult', listener)
},
onDeepLink: (callback: (args: SandboxUiDeepLinkEnvelope) => void) => {
const listener = (_event: unknown, args: SandboxUiDeepLinkEnvelope) => callback(args)
ipcRenderer.on('sandboxUi:deepLink', listener)
return () => ipcRenderer.off('sandboxUi:deepLink', listener)
},
onReleased: (callback: (args: SandboxUiReleasedEvent) => void) => {
const listener = (_event: unknown, args: SandboxUiReleasedEvent) => callback(args)
ipcRenderer.on('sandboxUi:released', listener)
return () => ipcRenderer.off('sandboxUi:released', listener)
},
onRefreshError: (
callback: (args: { appRef: string; launchId: string; message: string }) => void
) => {
const listener = (
_event: unknown,
args: { appRef: string; launchId: string; message: string }
) => callback(args)
ipcRenderer.on('sandboxUi:refreshError', listener)
return () => ipcRenderer.off('sandboxUi:refreshError', listener)
},
onRefreshRecovered: (callback: (args: { appRef: string; launchId: string }) => void) => {
const listener = (_event: unknown, args: { appRef: string; launchId: string }) =>
callback(args)
ipcRenderer.on('sandboxUi:refreshRecovered', listener)
return () => ipcRenderer.off('sandboxUi:refreshRecovered', listener)
},
onTitleChanged: (
callback: (args: { appRef: string; launchId: string; title: string }) => void
) => {
const listener = (
_event: unknown,
args: { appRef: string; launchId: string; title: string }
) => callback(args)
ipcRenderer.on('sandboxUi:titleChanged', listener)
return () => ipcRenderer.off('sandboxUi:titleChanged', listener)
},
},
/**
* Plugin permissions, trusted-renderer half: the consent modal and the
* Settings revocation surface. The plugin-facing half lives in a different
* preload (`sandboxUiEmbedPreload.ts`) behind a different trust model.
*/
pluginSdk: {
onConsentRequested: (callback: (request: PluginConsentRequest) => void) => {
const listener = (_event: unknown, request: PluginConsentRequest) => callback(request)
ipcRenderer.on('pluginSdk:consentRequested', listener)
return () => ipcRenderer.off('pluginSdk:consentRequested', listener)
},
onConsentCancelled: (callback: (args: { promptId: string }) => void) => {
const listener = (_event: unknown, args: { promptId: string }) => callback(args)
ipcRenderer.on('pluginSdk:consentCancelled', listener)
return () => ipcRenderer.off('pluginSdk:consentCancelled', listener)
},
onOpenGfsResource: (
callback: (args: {
gfsUri: string
name: string
kind: string
bytes: number | null
version?: number
}) => void
) => {
const listener = (
_event: unknown,
args: {
gfsUri: string
name: string
kind: string
bytes: number | null
version?: number
}
) => callback(args)
ipcRenderer.on('pluginSdk:openGfsResource', listener)
return () => ipcRenderer.off('pluginSdk:openGfsResource', listener)
},
onNotificationClicked: (callback: (args: { pluginId: string; ref: string | null }) => void) => {
const listener = (_event: unknown, args: { pluginId: string; ref: string | null }) =>
callback(args)
ipcRenderer.on('pluginSdk:notificationClicked', listener)
return () => ipcRenderer.off('pluginSdk:notificationClicked', listener)
},
resolveConsent: (promptId: string, allowed: string[]) =>
ipcRenderer.invoke('pluginSdk:resolveConsent', { promptId, allowed }),
listGrants: () => ipcRenderer.invoke('pluginSdk:listGrants'),
revoke: (pluginId: string, capability?: string) =>
ipcRenderer.invoke('pluginSdk:revoke', { pluginId, capability }),
activity: (limit?: number, includeAmbient?: boolean) =>
ipcRenderer.invoke('pluginSdk:activity', { limit, includeAmbient }),
clearActivity: () => ipcRenderer.invoke('pluginSdk:clearActivity'),
setTheme: (theme: string) => ipcRenderer.invoke('pluginSdk:setTheme', { theme }),
},
})
contextBridge.exposeInMainWorld('clerum', clerum)