Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
5.4 KB
Raw Blame
import { contextBridge, ipcRenderer } from 'electron'
// TYPE-ONLY import: erased at compile time, so it never becomes a `require`.
import type { PluginSdkEvent, PluginSdkResponse } from './pluginSdkProtocol.js'

/**
 * Channel names are duplicated here on purpose.
 *
 * This preload runs with `sandbox: true`, where Electron's `require` is a
 * polyfill limited to `electron` and a couple of Node builtins — a relative
 * `require('./pluginSdkProtocol.js')` throws at runtime. Until the preload gets
 * its own bundling step, the values are inlined and
 * `__tests__/sandboxUiEmbedPreload.contract.test.ts` asserts they still match
 * `pluginSdkProtocol.ts` so the two cannot drift apart silently.
 */
const PLUGIN_SDK_VERSION = '1.0.0'
const PLUGIN_SDK_PROTOCOL = 1
const PLUGIN_SDK_REQUEST_CHANNEL = 'clerum:plugin-sdk:request'
const PLUGIN_SDK_PERMISSIONS_CHANNEL = 'clerum:plugin-sdk:request-permissions'
const PLUGIN_SDK_PERMISSION_STATE_CHANNEL = 'clerum:plugin-sdk:permissions'
const PLUGIN_SDK_CAPABILITIES_CHANNEL = 'clerum:plugin-sdk:capabilities'
const PLUGIN_SDK_EVENT_CHANNEL = 'clerum:plugin-sdk:event'

/**
 * Preload script attached to every sandbox-ui `WebContentsView`. Exposes the
 * plugin-facing surface to recipe JS:
 *
 *   Legacy (unchanged, and deliberately so — every shipped recipe uses these):
 *     `clerum.requestSessionRefresh()` — recover from a stale session cookie
 *        when an SSE/fetch hits 401 between scheduled refreshes.
 *     `clerum.onOauthCompleted(cb)` — OAuth completion envelope, on its own
 *        legacy channel.
 *
 *   Plugin UI SDK:
 *     `clerum.sdk.*`           — version, capability list, batched consent,
 *                                grant state, events.
 *     `clerum.identity/org/agents/contexts/mcp/gfs/theme/notifications`
 *                              — one thin wrapper per capability.
 *
 * Everything here is a dumb pipe. No validation, no caching, no policy: this
 * code runs in a world the plugin's own JS can reach, so anything enforced on
 * this side is advisory. The real gating (caller pinning, consent, rate limits,
 * response minimization) is entirely main-side in `pluginSdkBroker.ts`.
 */
type SandboxUiOauthCompletedPayload = {
  oauthClientId: string
  provider: string
}

function invoke<T>(channel: string, payload?: unknown): Promise<PluginSdkResponse<T>> {
  return ipcRenderer.invoke(channel, payload) as Promise<PluginSdkResponse<T>>
}

function capability<T>(id: string, params?: unknown): Promise<PluginSdkResponse<T>> {
  return invoke<T>(PLUGIN_SDK_REQUEST_CHANNEL, {
    v: PLUGIN_SDK_PROTOCOL,
    capability: id,
    ...(params === undefined ? {} : { params }),
  })
}

contextBridge.exposeInMainWorld(
  'clerum',
  Object.freeze({
    requestSessionRefresh: (): Promise<void> =>
      ipcRenderer.invoke('clerum:sandbox-ui:request-refresh'),
    onOauthCompleted: (
      callback: (payload: SandboxUiOauthCompletedPayload) => void
    ): (() => void) => {
      const listener = (
        _event: Electron.IpcRendererEvent,
        payload: SandboxUiOauthCompletedPayload
      ): void => {
        callback(payload)
      }
      ipcRenderer.on('clerum:sandbox-ui:oauth-completed', listener)
      return () => {
        ipcRenderer.off('clerum:sandbox-ui:oauth-completed', listener)
      }
    },

    sdk: Object.freeze({
      version: PLUGIN_SDK_VERSION,
      protocol: PLUGIN_SDK_PROTOCOL,
      /** Capability ids this host build implements — lets a plugin degrade
       *  gracefully on an older Desktop instead of hard-failing. */
      capabilities: () => invoke(PLUGIN_SDK_CAPABILITIES_CHANNEL),
      /** Ask for several capabilities in ONE modal. The intended entry point. */
      requestPermissions: (capabilities: string[]) =>
        invoke(PLUGIN_SDK_PERMISSIONS_CHANNEL, { v: PLUGIN_SDK_PROTOCOL, capabilities }),
      /** Grant state without prompting, so a returning user sees no modal. */
      permissions: (capabilities?: string[]) =>
        invoke(PLUGIN_SDK_PERMISSION_STATE_CHANNEL, capabilities ?? null),
      on: (callback: (event: PluginSdkEvent) => void): (() => void) => {
        const listener = (_event: Electron.IpcRendererEvent, payload: PluginSdkEvent): void => {
          callback(payload)
        }
        ipcRenderer.on(PLUGIN_SDK_EVENT_CHANNEL, listener)
        return () => {
          ipcRenderer.off(PLUGIN_SDK_EVENT_CHANNEL, listener)
        }
      },
    }),

    identity: Object.freeze({ get: () => capability('identity.read') }),
    org: Object.freeze({ get: () => capability('org.read') }),
    agents: Object.freeze({ list: () => capability('agents.read') }),
    contexts: Object.freeze({ list: () => capability('contexts.read') }),
    mcp: Object.freeze({ list: () => capability('mcp.read') }),
    gfs: Object.freeze({
      list: (params?: { drive?: string; resourceId?: string; cursor?: string }) =>
        capability('gfs.list', params ?? {}),
      read: (params: { uri: string; as: 'text' | 'dataUrl' }) => capability('gfs.read', params),
      /** Show a shared file in the Desktop's own viewer. Same effect as the
       *  user clicking an `<a href="gfs://…">` the plugin rendered. */
      open: (uri: string) => capability('gfs.open', { uri }),
    }),
    theme: Object.freeze({ get: () => capability('theme.read') }),
    notifications: Object.freeze({
      notify: (params: { title: string; body?: string; ref?: string }) =>
        capability('notifications.notify', params),
    }),
  })
)