@puredesktop/puredesktop-ui-bridge 2.1.8 → 2.1.9

package/src/bridge/googleAuth.ts

@@ -1,9 +1,10 @@
-export interface GoogleOauthTokens {
-  accessToken: string
-  refreshToken?: string
-  expiresAt: number
-  scope: string
-}
+/**
+ * Google OAuth scope sets apps request through the shell-owned credential
+ * flow (`credentials.connectOAuth`). The OAuth client machinery itself —
+ * PKCE, authorize URL, token exchange, refresh — lives in the Electron main
+ * process (`packages/shell/src/modules/credentials/googleOAuth.ts`); no
+ * renderer ever handles credential material.
+ */
 
 export const GMAIL_SCOPES = [
   'https://www.googleapis.com/auth/gmail.modify',
@@ -13,149 +14,3 @@ export const GMAIL_SCOPES = [
 export const CALENDAR_SCOPES = [
   'https://www.googleapis.com/auth/calendar.events',
 ]
-
-export const GOOGLE_AUTHORIZATION_ENDPOINT =
-  'https://accounts.google.com/o/oauth2/v2/auth'
-export const GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token'
-
-const EXPIRY_SLACK_MS = 60_000
-
-export interface PkcePair {
-  verifier: string
-  challenge: string
-}
-
-function base64UrlEncode(bytes: Uint8Array): string {
-  let binary = ''
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte)
-  }
-  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
-}
-
-export function randomUrlSafeString(byteLength = 32): string {
-  const bytes = new Uint8Array(byteLength)
-  crypto.getRandomValues(bytes)
-  return base64UrlEncode(bytes)
-}
-
-export async function createPkcePair(): Promise<PkcePair> {
-  const verifier = randomUrlSafeString(48)
-  const digest = await crypto.subtle.digest(
-    'SHA-256',
-    new TextEncoder().encode(verifier),
-  )
-  return { verifier, challenge: base64UrlEncode(new Uint8Array(digest)) }
-}
-
-export interface GoogleAuthUrlInput {
-  clientId: string
-  challenge: string
-  state: string
-  scopes?: string[]
-}
-
-export function buildGoogleAuthorizationUrl(input: GoogleAuthUrlInput): string {
-  const url = new URL(GOOGLE_AUTHORIZATION_ENDPOINT)
-  url.searchParams.set('client_id', input.clientId)
-  url.searchParams.set('response_type', 'code')
-  url.searchParams.set('scope', (input.scopes ?? CALENDAR_SCOPES).join(' '))
-  url.searchParams.set('code_challenge', input.challenge)
-  url.searchParams.set('code_challenge_method', 'S256')
-  url.searchParams.set('state', input.state)
-  url.searchParams.set('access_type', 'offline')
-  url.searchParams.set('prompt', 'consent')
-  return url.toString()
-}
-
-interface GoogleTokenResponse {
-  access_token: string
-  refresh_token?: string
-  expires_in: number
-  scope: string
-}
-
-export function tokensFromTokenResponse(
-  payload: GoogleTokenResponse,
-  previousRefreshToken?: string,
-  now = Date.now(),
-): GoogleOauthTokens {
-  const refreshToken = payload.refresh_token ?? previousRefreshToken
-  return {
-    accessToken: payload.access_token,
-    ...(refreshToken === undefined ? {} : { refreshToken }),
-    expiresAt: now + payload.expires_in * 1000,
-    scope: payload.scope,
-  }
-}
-
-export function accessTokenIsFresh(
-  tokens: GoogleOauthTokens,
-  now = Date.now(),
-): boolean {
-  return tokens.expiresAt - EXPIRY_SLACK_MS > now
-}
-
-export interface TokenExchangeInput {
-  clientId: string
-  clientSecret?: string
-  code: string
-  verifier: string
-  redirectUri: string
-}
-
-type FormPost = (
-  url: string,
-  body: string,
-) => Promise<{ ok: boolean; status: number; body: string }>
-
-export async function exchangeCodeForTokens(
-  post: FormPost,
-  input: TokenExchangeInput,
-): Promise<GoogleOauthTokens> {
-  const body = new URLSearchParams({
-    client_id: input.clientId,
-    grant_type: 'authorization_code',
-    code: input.code,
-    code_verifier: input.verifier,
-    redirect_uri: input.redirectUri,
-  })
-  if (input.clientSecret) body.set('client_secret', input.clientSecret)
-  const response = await post(GOOGLE_TOKEN_ENDPOINT, body.toString())
-  if (!response.ok) {
-    throw new Error(
-      `Google token exchange failed (${response.status}): ${response.body}`,
-    )
-  }
-  return tokensFromTokenResponse(
-    JSON.parse(response.body) as GoogleTokenResponse,
-  )
-}
-
-export interface TokenRefreshInput {
-  clientId: string
-  clientSecret?: string
-  refreshToken: string
-}
-
-export async function refreshAccessToken(
-  post: FormPost,
-  input: TokenRefreshInput,
-): Promise<GoogleOauthTokens> {
-  const body = new URLSearchParams({
-    client_id: input.clientId,
-    grant_type: 'refresh_token',
-    refresh_token: input.refreshToken,
-  })
-  if (input.clientSecret) body.set('client_secret', input.clientSecret)
-  const response = await post(GOOGLE_TOKEN_ENDPOINT, body.toString())
-  if (!response.ok) {
-    throw new Error(
-      `Google token refresh failed (${response.status}): ${response.body}`,
-    )
-  }
-  return tokensFromTokenResponse(
-    JSON.parse(response.body) as GoogleTokenResponse,
-    input.refreshToken,
-  )
-}

package/src/bridge/mcpClient.d.mts

@@ -0,0 +1,74 @@
+export type McpClientTransportType = 'http' | 'sse' | 'stdio'
+export type McpClientAuthType = 'none' | 'bearer' | 'apiKey'
+
+/** A configured external MCP server (no secret material — that stays shell-side). */
+export interface McpClientServerConfig {
+  /** Stable slug — `[a-z0-9-]+`. */
+  id: string
+  label: string
+  transport: McpClientTransportType
+  /** Remote endpoint for `http` / `sse` transports. */
+  url?: string
+  /** Executable for the `stdio` transport. */
+  command?: string
+  args?: string[]
+  enabled: boolean
+  authType: McpClientAuthType
+  /** Env var the stored secret is injected as, when `authType` is `apiKey`. */
+  apiKeyEnvVar?: string
+  /** Short tool names opted into auto-run; everything else asks first. */
+  autoApproveTools?: string[]
+}
+
+export interface McpClientServerView extends McpClientServerConfig {
+  hasSecret: boolean
+}
+
+export interface McpClientSettingsView {
+  enabled: boolean
+  servers: McpClientServerView[]
+}
+
+export interface McpClientTestResult {
+  ok: boolean
+  serverId: string
+  toolNames: string[]
+  error?: string
+}
+
+export interface McpToolInfo {
+  name: string
+  description?: string
+  inputSchema: Record<string, unknown>
+}
+
+export interface McpToolRunResult {
+  content: string
+  isError: boolean
+}
+
+export function listMcpClientSettings(): Promise<McpClientSettingsView>
+export function setMcpClientEnabled(
+  enabled: boolean,
+): Promise<McpClientSettingsView>
+export function upsertMcpClientServer(
+  config: McpClientServerConfig,
+): Promise<McpClientSettingsView>
+export function removeMcpClientServer(
+  serverId: string,
+): Promise<McpClientSettingsView>
+export function setMcpClientServerSecret(
+  serverId: string,
+  value: string | null,
+): Promise<McpClientSettingsView>
+export function testMcpClientServer(
+  config: McpClientServerConfig,
+): Promise<McpClientTestResult>
+export function listMcpClientServerTools(
+  serverId: string,
+): Promise<McpToolInfo[]>
+export function callMcpClientServerTool(
+  serverId: string,
+  toolName: string,
+  args: Record<string, unknown>,
+): Promise<McpToolRunResult>

package/src/bridge/mcpClient.mjs

@@ -0,0 +1,79 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Outbound MCP client registry (external MCP servers whose tools in-app
+ * agents can call). Secret material never crosses this bridge — only the
+ * redacted settings view does. The shell gates these methods to the
+ * assistant app: this is machine-level, secret-bearing configuration.
+ */
+
+/**
+ * @returns {Promise<import('./mcpClient.d.mts').McpClientSettingsView>}
+ */
+export async function listMcpClientSettings() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_LIST, [])
+}
+
+/**
+ * @param {boolean} enabled
+ * @returns {Promise<import('./mcpClient.d.mts').McpClientSettingsView>}
+ */
+export async function setMcpClientEnabled(enabled) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_SET_ENABLED, [enabled])
+}
+
+/**
+ * @param {import('./mcpClient.d.mts').McpClientServerConfig} config
+ * @returns {Promise<import('./mcpClient.d.mts').McpClientSettingsView>}
+ */
+export async function upsertMcpClientServer(config) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_UPSERT, [config])
+}
+
+/**
+ * @param {string} serverId
+ * @returns {Promise<import('./mcpClient.d.mts').McpClientSettingsView>}
+ */
+export async function removeMcpClientServer(serverId) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_REMOVE, [serverId])
+}
+
+/**
+ * @param {string} serverId
+ * @param {string | null} value
+ * @returns {Promise<import('./mcpClient.d.mts').McpClientSettingsView>}
+ */
+export async function setMcpClientServerSecret(serverId, value) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_SET_SECRET, [
+    { serverId, value },
+  ])
+}
+
+/**
+ * @param {import('./mcpClient.d.mts').McpClientServerConfig} config
+ * @returns {Promise<import('./mcpClient.d.mts').McpClientTestResult>}
+ */
+export async function testMcpClientServer(config) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_TEST, [config])
+}
+
+/**
+ * @param {string} serverId
+ * @returns {Promise<import('./mcpClient.d.mts').McpToolInfo[]>}
+ */
+export async function listMcpClientServerTools(serverId) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_LIST_TOOLS, [serverId])
+}
+
+/**
+ * @param {string} serverId
+ * @param {string} toolName
+ * @param {Record<string, unknown>} args
+ * @returns {Promise<import('./mcpClient.d.mts').McpToolRunResult>}
+ */
+export async function callMcpClientServerTool(serverId, toolName, args) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.MCPCLIENT_CALL_TOOL, [
+    { serverId, toolName, arguments: args },
+  ])
+}

package/src/bridge/methods.d.mts

@@ -20,6 +20,8 @@ export declare const PLATFORM_BRIDGE_METHODS: {
   readonly SETTINGS_APP_UPDATE: 'settings.app.update'
   readonly STORAGE_READ_JSON: 'storage.readJson'
   readonly STORAGE_WRITE_JSON: 'storage.writeJson'
+  readonly OPERATIONS_RECORD: 'operations.record'
+  readonly OPERATIONS_LIST: 'operations.list'
   readonly FS_LIST: 'fs.list'
   readonly FS_READ_PREVIEW: 'fs.readPreview'
   readonly FS_READ_BINARY: 'fs.readBinary'
@@ -63,6 +65,9 @@ export declare const PLATFORM_BRIDGE_METHODS: {
   readonly NETWORK_FETCH: 'network.fetch'
   readonly RESEARCH_QUERY: 'research.query'
   readonly VISION_GENERATE_IMAGE: 'vision.generateImage'
+  readonly NOTIFICATIONS_SCHEDULE: 'notifications.schedule'
+  readonly NOTIFICATIONS_CANCEL: 'notifications.cancel'
+  readonly NOTIFICATIONS_CANCEL_ALL: 'notifications.cancelAll'
   readonly OAUTH_LOOPBACK_AUTHORIZE: 'oauth.loopbackAuthorize'
   readonly SECRETS_GET: 'secrets.get'
   readonly SECRETS_SET: 'secrets.set'
@@ -74,6 +79,14 @@ export declare const PLATFORM_BRIDGE_METHODS: {
   readonly MYTOOLS_DELETE: 'mytools.delete'
   readonly MYTOOLS_TEST: 'mytools.test'
   readonly MYTOOLS_RESEARCH: 'mytools.research'
+  readonly MCPCLIENT_LIST: 'mcpClient.list'
+  readonly MCPCLIENT_SET_ENABLED: 'mcpClient.setEnabled'
+  readonly MCPCLIENT_UPSERT: 'mcpClient.upsertServer'
+  readonly MCPCLIENT_REMOVE: 'mcpClient.removeServer'
+  readonly MCPCLIENT_SET_SECRET: 'mcpClient.setSecret'
+  readonly MCPCLIENT_TEST: 'mcpClient.testServer'
+  readonly MCPCLIENT_LIST_TOOLS: 'mcpClient.listTools'
+  readonly MCPCLIENT_CALL_TOOL: 'mcpClient.callTool'
   readonly DEBUG_EMIT_EVENT: 'debug.emitEvent'
   readonly PLUGINS_INSTALL: 'plugins.install'
   readonly PLUGINS_EVALUATE_BUILD: 'plugins.evaluateBuild'
@@ -88,6 +101,11 @@ export declare const PLATFORM_BRIDGE_METHODS: {
   readonly CREDENTIALS_LIST: 'credentials.list'
   readonly CREDENTIALS_SET: 'credentials.set'
   readonly CREDENTIALS_DELETE: 'credentials.delete'
+  readonly CREDENTIALS_STATUS: 'credentials.status'
+  readonly CREDENTIALS_SET_OAUTH_CONFIG: 'credentials.setOAuthConfig'
+  readonly CREDENTIALS_CONNECT_OAUTH: 'credentials.connectOAuth'
+  readonly CREDENTIALS_DISCONNECT: 'credentials.disconnect'
+  readonly CREDENTIALS_OAUTH_ACCESS_TOKEN: 'credentials.oauthAccessToken'
   readonly AGENTS_SESSIONS_CREATE: 'agents.sessions.create'
   readonly AGENTS_SESSIONS_LIST: 'agents.sessions.list'
   readonly AGENTS_SESSIONS_READ: 'agents.sessions.read'
@@ -98,6 +116,7 @@ export declare const PLATFORM_BRIDGE_METHODS: {
   readonly AGENTS_JOBS_READ: 'agents.jobs.read'
   readonly AGENTS_JOBS_CANCEL: 'agents.jobs.cancel'
   readonly AGENTS_JOBS_RUN_NOW: 'agents.jobs.runNow'
+  readonly AGENTS_DELEGATIONS_LIST: 'agents.delegations.list'
   readonly AGENTS_SESSION_SEND_MESSAGE: 'agents.session.sendMessage'
   readonly AGENTS_SESSION_APPROVE_TOOLS: 'agents.session.approveTools'
   readonly AGENTS_SESSION_REJECT_TOOLS: 'agents.session.rejectTools'
@@ -141,13 +160,16 @@ export declare const PLATFORM_BRIDGE_METHOD_PREFIXES: {
   readonly NETWORK: 'network.'
   readonly RESEARCH: 'research.'
   readonly VISION: 'vision.'
+  readonly NOTIFICATIONS: 'notifications.'
   readonly OAUTH: 'oauth.'
   readonly SECRETS: 'secrets.'
   readonly MYTOOLS: 'mytools.'
+  readonly MCPCLIENT: 'mcpClient.'
   readonly AGENTS: 'agents.'
   readonly PEOPLE: 'people.'
   readonly DEBUG: 'debug.'
   readonly DOCUMENTS: 'documents.'
+  readonly OPERATIONS: 'operations.'
 }
 
 export type PlatformBridgeMethodName =

package/src/bridge/methods.mjs

@@ -27,6 +27,8 @@ export const PLATFORM_BRIDGE_METHODS = {
 
   STORAGE_READ_JSON: 'storage.readJson',
   STORAGE_WRITE_JSON: 'storage.writeJson',
+  OPERATIONS_RECORD: 'operations.record',
+  OPERATIONS_LIST: 'operations.list',
 
   FS_LIST: 'fs.list',
   FS_READ_PREVIEW: 'fs.readPreview',
@@ -78,6 +80,9 @@ export const PLATFORM_BRIDGE_METHODS = {
   NETWORK_FETCH: 'network.fetch',
   RESEARCH_QUERY: 'research.query',
   VISION_GENERATE_IMAGE: 'vision.generateImage',
+  NOTIFICATIONS_SCHEDULE: 'notifications.schedule',
+  NOTIFICATIONS_CANCEL: 'notifications.cancel',
+  NOTIFICATIONS_CANCEL_ALL: 'notifications.cancelAll',
   OAUTH_LOOPBACK_AUTHORIZE: 'oauth.loopbackAuthorize',
   SECRETS_GET: 'secrets.get',
   SECRETS_SET: 'secrets.set',
@@ -90,6 +95,15 @@ export const PLATFORM_BRIDGE_METHODS = {
   MYTOOLS_TEST: 'mytools.test',
   MYTOOLS_RESEARCH: 'mytools.research',
 
+  MCPCLIENT_LIST: 'mcpClient.list',
+  MCPCLIENT_SET_ENABLED: 'mcpClient.setEnabled',
+  MCPCLIENT_UPSERT: 'mcpClient.upsertServer',
+  MCPCLIENT_REMOVE: 'mcpClient.removeServer',
+  MCPCLIENT_SET_SECRET: 'mcpClient.setSecret',
+  MCPCLIENT_TEST: 'mcpClient.testServer',
+  MCPCLIENT_LIST_TOOLS: 'mcpClient.listTools',
+  MCPCLIENT_CALL_TOOL: 'mcpClient.callTool',
+
   DEBUG_EMIT_EVENT: 'debug.emitEvent',
 
   PLUGINS_INSTALL: 'plugins.install',
@@ -106,6 +120,11 @@ export const PLATFORM_BRIDGE_METHODS = {
   CREDENTIALS_LIST: 'credentials.list',
   CREDENTIALS_SET: 'credentials.set',
   CREDENTIALS_DELETE: 'credentials.delete',
+  CREDENTIALS_STATUS: 'credentials.status',
+  CREDENTIALS_SET_OAUTH_CONFIG: 'credentials.setOAuthConfig',
+  CREDENTIALS_CONNECT_OAUTH: 'credentials.connectOAuth',
+  CREDENTIALS_DISCONNECT: 'credentials.disconnect',
+  CREDENTIALS_OAUTH_ACCESS_TOKEN: 'credentials.oauthAccessToken',
 
   AGENTS_SESSIONS_CREATE: 'agents.sessions.create',
   AGENTS_SESSIONS_LIST: 'agents.sessions.list',
@@ -118,6 +137,7 @@ export const PLATFORM_BRIDGE_METHODS = {
   AGENTS_JOBS_READ: 'agents.jobs.read',
   AGENTS_JOBS_CANCEL: 'agents.jobs.cancel',
   AGENTS_JOBS_RUN_NOW: 'agents.jobs.runNow',
+  AGENTS_DELEGATIONS_LIST: 'agents.delegations.list',
 
   AGENTS_SESSION_SEND_MESSAGE: 'agents.session.sendMessage',
   AGENTS_SESSION_APPROVE_TOOLS: 'agents.session.approveTools',
@@ -163,11 +183,14 @@ export const PLATFORM_BRIDGE_METHOD_PREFIXES = {
   NETWORK: 'network.',
   RESEARCH: 'research.',
   VISION: 'vision.',
+  NOTIFICATIONS: 'notifications.',
   OAUTH: 'oauth.',
   SECRETS: 'secrets.',
   MYTOOLS: 'mytools.',
+  MCPCLIENT: 'mcpClient.',
   AGENTS: 'agents.',
   PEOPLE: 'people.',
   DEBUG: 'debug.',
   DOCUMENTS: 'documents.',
+  OPERATIONS: 'operations.',
 }

package/src/bridge/notifications.d.mts

@@ -0,0 +1,12 @@
+export function scheduleNotification(request: {
+  id: string
+  title: string
+  body?: string
+  fireAt: number
+}): Promise<{ ok: true }>
+
+export function cancelNotification(request: {
+  id: string
+}): Promise<{ ok: true }>
+
+export function cancelAllNotifications(): Promise<{ ok: true }>

package/src/bridge/notifications.mjs

@@ -0,0 +1,36 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * OS notification scheduling — a benign local capability (no plugin permission).
+ * Schedules are held in the shell main process and die when the app quits;
+ * reminders while the app is closed are out of scope. The app-side scheduler
+ * that decides *what* to schedule is the caller's responsibility.
+ */
+
+/**
+ * Schedule an OS notification to fire at `fireAt`. Reusing an `id` replaces any
+ * pending schedule (dedupe). `fireAt` in the past fires ~immediately.
+ * @param {{ id: string, title: string, body?: string, fireAt: number }} request
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function scheduleNotification(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.NOTIFICATIONS_SCHEDULE, [request])
+}
+
+/**
+ * Cancel a pending schedule; no-op if the id is unknown.
+ * @param {{ id: string }} request
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function cancelNotification(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.NOTIFICATIONS_CANCEL, [request])
+}
+
+/**
+ * Clear every pending schedule (used when an app reloads its reminder set).
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function cancelAllNotifications() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.NOTIFICATIONS_CANCEL_ALL, [])
+}

package/src/bridge/operations.d.mts

@@ -0,0 +1,44 @@
+export type PlatformOperationLane = 'user' | 'agent'
+
+export interface PlatformOperationInput {
+  /** Who acted: a person in the UI, or an agent doing work. */
+  lane: PlatformOperationLane
+  /** Stable machine-readable kind, dot-namespaced, e.g. `document.save`. */
+  kind: string
+  /** Originating app slug, or `shell` for platform-level operations. */
+  appSlug: string
+  /** One human-readable sentence describing the operation. */
+  summary: string
+  /** Optional free-form elaboration. */
+  detail?: string
+  /** Optional references (path, sessionId, runId, …) for drill-down. */
+  refs?: Record<string, string>
+}
+
+export interface PlatformOperation extends PlatformOperationInput {
+  id: string
+  /** ISO timestamp stamped by the shell. */
+  at: string
+}
+
+export interface PlatformOperationsListQuery {
+  lane?: PlatformOperationLane
+  /** Max entries returned, newest first. */
+  limit?: number
+}
+
+export interface PlatformOperationsListResult {
+  operations: PlatformOperation[]
+}
+
+export declare function recordPlatformOperation(
+  input: PlatformOperationInput,
+): Promise<PlatformOperation>
+
+export declare function listPlatformOperations(
+  query?: PlatformOperationsListQuery,
+): Promise<PlatformOperationsListResult>
+
+export declare function onPlatformOperationRecorded(
+  listener: (operation: PlatformOperation) => void,
+): () => void

package/src/bridge/operations.mjs

@@ -0,0 +1,40 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Platform operations ledger: one suite-wide record of what happened,
+ * split into two lanes — `user` interactions and `agent` interactions.
+ * The shell stores every entry and broadcasts each append, so UIs (the
+ * PureAssistant tab in particular) can follow activity in real time.
+ */
+
+/**
+ * Record one operation into the ledger.
+ *
+ * @param {import('./operations.d.mts').PlatformOperationInput} input
+ * @returns {Promise<import('./operations.d.mts').PlatformOperation>}
+ */
+export async function recordPlatformOperation(input) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.OPERATIONS_RECORD, [input])
+}
+
+/**
+ * List recorded operations, newest first.
+ *
+ * @param {import('./operations.d.mts').PlatformOperationsListQuery} [query]
+ * @returns {Promise<import('./operations.d.mts').PlatformOperationsListResult>}
+ */
+export async function listPlatformOperations(query) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.OPERATIONS_LIST, [query ?? {}])
+}
+
+/**
+ * Subscribe to ledger appends. The listener receives each new operation.
+ *
+ * @param {(operation: import('./operations.d.mts').PlatformOperation) => void} listener
+ * @returns {() => void} unsubscribe
+ */
+export function onPlatformOperationRecorded(listener) {
+  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.OPERATIONS_CHANGED, listener)
+}

package/src/bridge/react/usePlatformAgentSessionDrive.test.tsx

@@ -104,16 +104,35 @@ describe('usePlatformAgentSessionDrive', () => {
     ;(globalThis as ReactActGlobal).IS_REACT_ACT_ENVIRONMENT = true
   })
 
-  beforeEach(() => {
-    latestDrive = null
-    host = document.createElement('div')
-    document.body.appendChild(host)
-    root = createRoot(host)
-    agentsMock.readAgentSession.mockResolvedValue(sessionRecord)
-    agentsMock.advanceAgentSessionPending.mockResolvedValue(null)
-    agentsMock.readAgentLlmMenuOptions.mockResolvedValue([])
-    agentsMock.onAgentRunEvent.mockReturnValue(vi.fn())
-  })
+  beforeEach(() => {
+    latestDrive = null
+    host = document.createElement('div')
+    document.body.appendChild(host)
+    root = createRoot(host)
+    agentsMock.readAgentSession.mockResolvedValue(sessionRecord)
+    agentsMock.advanceAgentSessionPending.mockResolvedValue({
+      session: sessionRecord,
+      snapshot: {
+        runId: sessionRecord.runId,
+        state: sessionRecord.snapshot.state,
+        turn: sessionRecord.snapshot.turn,
+        messages: sessionRecord.snapshot.messages,
+      },
+      effectiveToolPolicy: {
+        allowedTargetApps: ['book'],
+        defaultRequiresApproval: false,
+        approvalOverrides: {
+          'book.write': true,
+          'book.review': true,
+        },
+      },
+      manualPendingToolCalls: [
+        { id: 'call-manual', name: 'book.review', arguments: {} },
+      ],
+    })
+    agentsMock.readAgentLlmMenuOptions.mockResolvedValue([])
+    agentsMock.onAgentRunEvent.mockReturnValue(vi.fn())
+  })
 
   afterEach(() => {
     act(() => root.unmount())