@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1 → 2.1.0

package/src/bridge/agents.mjs

@@ -1,233 +1,287 @@
-import { bridge } from './client.mjs'
-import { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
-import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
-
-/**
- * Agent session + run bridge SDK for plugin iframes.
- * Requires `agents` permission in plugin.json.
- *
- * Host handlers wire in shell phase S8; constants and client are stable for app authors.
- */
-
-/** @param {import('./agentTypes.js').PlatformCreateAgentSessionRequest} request */
-export async function createAgentSession(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_CREATE, [request])
-}
-
-/** @param {import('./agentTypes.js').PlatformListAgentSessionsRequest} request */
-export async function listAgentSessions(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_LIST, [request])
-}
-
-/** @param {import('./agentTypes.js').PlatformReadAgentSessionRequest} request */
-export async function readAgentSession(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_READ, [request])
-}
-
-/** @param {import('./agentTypes.js').PlatformUpdateAgentSessionRequest} request */
-export async function updateAgentSession(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_UPDATE, [request])
-}
-
-/** @param {import('./agentTypes.js').PlatformReadAgentSessionRequest} request */
-export async function deleteAgentSession(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_DELETE, [request])
-}
-
-/**
- * Send a user message on a session; shell drives the run until awaiting user,
- * manual pending tools, or terminal state.
- * @param {import('./agentTypes.js').PlatformSendAgentSessionMessageRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult>}
- */
-export async function sendAgentSessionMessage(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_SEND_MESSAGE, [
-    request,
-  ])
-}
-
-/**
- * Approve manual pending tools and continue the run.
- * @param {import('./agentTypes.js').PlatformAgentSessionDriveRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult | null>}
- */
-export async function approveAgentSessionTools(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_APPROVE_TOOLS, [
-    request,
-  ])
-}
-
-/**
- * Reject manual pending tools and continue the run.
- * @param {import('./agentTypes.js').PlatformRejectAgentSessionToolsRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult | null>}
- */
-export async function rejectAgentSessionTools(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_REJECT_TOOLS, [
-    request,
-  ])
-}
-
-/**
- * Auto-approve policy-approved pending tools (e.g. after loading a session).
- * @param {import('./agentTypes.js').PlatformAgentSessionDriveRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult | null>}
- */
-export async function advanceAgentSessionPending(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_ADVANCE_PENDING, [
-    request,
-  ])
-}
-
-/**
- * Stop the in-flight turn for a session and persist interrupted state.
- * @param {import('./agentTypes.js').PlatformInterruptAgentSessionRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult>}
- */
-export async function interruptAgentSession(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_INTERRUPT, [request])
-}
-
-/**
- * Subscribe to streaming agent run events for this plugin tab.
- * Payload shape matches shell `AgentRunEventIpcPayload` (runId, seq, type, …).
- *
- * @param {(payload: import('./agentTypes.js').PlatformAgentRunEvent) => void} listener
- * @returns {() => void}
- */
-export function onAgentRunEvent(listener) {
-  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.AGENT_RUN_EVENT, listener)
-}
-
-/**
- * Materialize a run for an existing session and send the first user message.
- * Returns the run snapshot (state 'ready'); drive it with callAgentRunModel
- * and resolveAgentRunToolCalls until 'awaiting_user'.
- *
- * @param {import('./agentTypes.js').PlatformStartAgentRunRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
- */
-export async function startAgentRun(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_START, [request])
-}
-
-/**
- * @param {import('./agentTypes.js').PlatformCallAgentModelRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
- */
-export async function callAgentRunModel(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_CALL_MODEL, [request])
-}
-
-/**
- * Route policy-approved pending tool calls to their registered app tabs and
- * resolve them. Tools still pending afterwards need user approval in the
- * agent drawer.
- *
- * @param {import('./agentTypes.js').PlatformResolveAgentToolCallsRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
- */
-export async function resolveAgentRunToolCalls(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_RESOLVE_TOOL_CALLS, [
-    request,
-  ])
-}
-
-/**
- * @param {import('./agentTypes.js').PlatformSendAgentRunMessageRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
- */
-export async function sendAgentRunMessage(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_SEND, [request])
-}
-
-/**
- * @param {import('./agentTypes.js').PlatformReadAgentRunContextRequest} request
- * @returns {Promise<import('./agentTypes.js').PlatformAgentRunContext>}
- */
-export async function readAgentRunContext(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_READ_CONTEXT, [request])
-}
-
-/**
- * Credential-filtered catalog entries for model menus (configured booleans only).
- * @param {import('./agentTypes.js').PlatformReadAgentLlmMenuOptionsRequest} [request]
- * @returns {Promise<import('./agentTypes.js').PlatformAgentLlmMenuOption[]>}
- */
-export async function readAgentLlmMenuOptions(request = {}) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_LLM_MENU_OPTIONS, [request])
-}
-
-/**
- * @returns {Promise<import('./agentTypes.js').PlatformLocalModelRuntimeStatus>}
- */
-export async function readLocalModelsStatus() {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_LOCAL_MODELS_STATUS, [])
-}
-
-/**
- * Register tool short names implemented by this tab (after bridge ready).
- * @param {{ tools: string[] }} request
- */
-export async function registerAgentTools(request) {
-  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_TOOLS_REGISTER, [request])
-}
-
-/**
- * Handle host-initiated tool invocations for this tab.
- * @param {(payload: {
- *   invokeId: string
- *   toolCallId: string
- *   name: string
- *   shortName: string
- *   arguments: Record<string, unknown>
- * }) => Promise<{ toolCallId: string, content: string, isError?: boolean }>} handler
- */
-export function onAgentToolInvoke(handler) {
-  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.AGENT_TOOL_INVOKE, payload => {
-    void (async () => {
-      if (!payload || typeof payload !== 'object') return
-      const invokeId = payload.invokeId
-      const toolCallId = payload.toolCallId
-      const name = payload.name
-      const shortName = payload.shortName
-      if (
-        typeof invokeId !== 'string' ||
-        typeof toolCallId !== 'string' ||
-        typeof name !== 'string' ||
-        typeof shortName !== 'string'
-      ) {
-        return
-      }
-      try {
-        const result = await handler({
-          invokeId,
-          toolCallId,
-          name,
-          shortName,
-          arguments:
-            payload.arguments && typeof payload.arguments === 'object'
-              ? payload.arguments
-              : {},
-        })
-        await bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_TOOLS_COMPLETE, [
-          {
-            invokeId,
-            toolCallId: result.toolCallId ?? toolCallId,
-            content: result.content,
-            isError: result.isError,
-          },
-        ])
-      } catch (error) {
-        await bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_TOOLS_COMPLETE, [
-          {
-            invokeId,
-            toolCallId,
-            content: error instanceof Error ? error.message : String(error),
-            isError: true,
-          },
-        ])
-      }
-    })()
-  })
-}
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_EVENTS } from './events.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/**
+ * Agent session + run bridge SDK for plugin iframes.
+ * Requires `agents` permission in plugin.json.
+ *
+ * Host handlers wire in shell phase S8; constants and client are stable for app authors.
+ */
+
+/** @param {import('./agentTypes.js').PlatformCreateAgentSessionRequest} request */
+export async function createAgentSession(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_CREATE, [request])
+}
+
+/** @param {import('./agentTypes.js').PlatformListAgentSessionsRequest} request */
+export async function listAgentSessions(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_LIST, [request])
+}
+
+/** @param {import('./agentTypes.js').PlatformReadAgentSessionRequest} request */
+export async function readAgentSession(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_READ, [request])
+}
+
+/** @param {import('./agentTypes.js').PlatformUpdateAgentSessionRequest} request */
+export async function updateAgentSession(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_UPDATE, [request])
+}
+
+/** @param {import('./agentTypes.js').PlatformReadAgentSessionRequest} request */
+export async function deleteAgentSession(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSIONS_DELETE, [request])
+}
+
+/**
+ * Create a durable scheduled job for an existing agent session.
+ * @param {import('./agentTypes.js').PlatformCreateAgentJobRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentJobRecord>}
+ */
+export async function createAgentJob(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_JOBS_CREATE, [request])
+}
+
+/**
+ * @param {import('./agentTypes.js').PlatformListAgentJobsRequest} [request]
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentJobRecord[]>}
+ */
+export async function listAgentJobs(request = {}) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_JOBS_LIST, [request])
+}
+
+/**
+ * @param {import('./agentTypes.js').PlatformReadAgentJobRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentJobRecord>}
+ */
+export async function readAgentJob(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_JOBS_READ, [request])
+}
+
+/**
+ * Cancel a job. If it is running, shell interrupts the backing session first so
+ * the session remains the source of run state.
+ * @param {import('./agentTypes.js').PlatformCancelAgentJobRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentJobRecord>}
+ */
+export async function cancelAgentJob(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_JOBS_CANCEL, [request])
+}
+
+/**
+ * Queue a completed, failed, cancelled, or future queued job immediately.
+ * @param {import('./agentTypes.js').PlatformReadAgentJobRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentJobRecord>}
+ */
+export async function runAgentJobNow(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_JOBS_RUN_NOW, [request])
+}
+
+/**
+ * Send a user message on a session; shell drives the run until awaiting user,
+ * manual pending tools, or terminal state.
+ * @param {import('./agentTypes.js').PlatformSendAgentSessionMessageRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult>}
+ */
+export async function sendAgentSessionMessage(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_SEND_MESSAGE, [
+    request,
+  ])
+}
+
+/**
+ * Approve manual pending tools and continue the run.
+ * @param {import('./agentTypes.js').PlatformAgentSessionDriveRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult | null>}
+ */
+export async function approveAgentSessionTools(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_APPROVE_TOOLS, [
+    request,
+  ])
+}
+
+/**
+ * Reject manual pending tools and continue the run.
+ * @param {import('./agentTypes.js').PlatformRejectAgentSessionToolsRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult | null>}
+ */
+export async function rejectAgentSessionTools(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_REJECT_TOOLS, [
+    request,
+  ])
+}
+
+/**
+ * Auto-approve policy-approved pending tools (e.g. after loading a session).
+ * @param {import('./agentTypes.js').PlatformAgentSessionDriveRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult | null>}
+ */
+export async function advanceAgentSessionPending(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_ADVANCE_PENDING, [
+    request,
+  ])
+}
+
+/**
+ * Stop the in-flight turn for a session and persist interrupted state.
+ * @param {import('./agentTypes.js').PlatformInterruptAgentSessionRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentSessionDriveResult>}
+ */
+export async function interruptAgentSession(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_SESSION_INTERRUPT, [request])
+}
+
+/**
+ * Subscribe to streaming agent run events for this plugin tab.
+ * Payload shape matches shell `AgentRunEventIpcPayload` (runId, seq, type, …).
+ *
+ * @param {(payload: import('./agentTypes.js').PlatformAgentRunEvent) => void} listener
+ * @returns {() => void}
+ */
+export function onAgentRunEvent(listener) {
+  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.AGENT_RUN_EVENT, listener)
+}
+
+/**
+ * Materialize a run for an existing session and send the first user message.
+ * Returns the run snapshot (state 'ready'); drive it with callAgentRunModel
+ * and resolveAgentRunToolCalls until 'awaiting_user'.
+ *
+ * @param {import('./agentTypes.js').PlatformStartAgentRunRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
+ */
+export async function startAgentRun(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_START, [request])
+}
+
+/**
+ * @param {import('./agentTypes.js').PlatformCallAgentModelRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
+ */
+export async function callAgentRunModel(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_CALL_MODEL, [request])
+}
+
+/**
+ * Route policy-approved pending tool calls to their registered app tabs and
+ * resolve them. Tools still pending afterwards need user approval in the
+ * agent drawer.
+ *
+ * @param {import('./agentTypes.js').PlatformResolveAgentToolCallsRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
+ */
+export async function resolveAgentRunToolCalls(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_RESOLVE_TOOL_CALLS, [
+    request,
+  ])
+}
+
+/**
+ * @param {import('./agentTypes.js').PlatformSendAgentRunMessageRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentRunSnapshot>}
+ */
+export async function sendAgentRunMessage(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_SEND, [request])
+}
+
+/**
+ * @param {import('./agentTypes.js').PlatformReadAgentRunContextRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentRunContext>}
+ */
+export async function readAgentRunContext(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_RUN_READ_CONTEXT, [request])
+}
+
+/**
+ * Ask the configured low/high tier agent model for compact JSON without
+ * creating a durable agent session.
+ * @param {import('./agentTypes.js').PlatformLowModelJsonRequest} request
+ * @returns {Promise<import('./agentTypes.js').PlatformLowModelJsonResponse>}
+ */
+export async function callLowModelJson(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_LOW_MODEL_JSON, [request])
+}
+
+/**
+ * Credential-filtered catalog entries for model menus (configured booleans only).
+ * @param {import('./agentTypes.js').PlatformReadAgentLlmMenuOptionsRequest} [request]
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentLlmMenuOption[]>}
+ */
+export async function readAgentLlmMenuOptions(request = {}) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_LLM_MENU_OPTIONS, [request])
+}
+
+/**
+ * @returns {Promise<import('./agentTypes.js').PlatformLocalModelRuntimeStatus>}
+ */
+export async function readLocalModelsStatus() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_LOCAL_MODELS_STATUS, [])
+}
+
+/**
+ * Register tool short names implemented by this tab (after bridge ready).
+ * @param {{ tools: string[] }} request
+ */
+export async function registerAgentTools(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_TOOLS_REGISTER, [request])
+}
+
+/**
+ * Handle host-initiated tool invocations for this tab.
+ * @param {(payload: {
+ *   invokeId: string
+ *   toolCallId: string
+ *   name: string
+ *   shortName: string
+ *   arguments: Record<string, unknown>
+ * }) => Promise<{ toolCallId: string, content: string, isError?: boolean }>} handler
+ */
+export function onAgentToolInvoke(handler) {
+  return bridge.onEvent(PLATFORM_BRIDGE_EVENTS.AGENT_TOOL_INVOKE, payload => {
+    void (async () => {
+      if (!payload || typeof payload !== 'object') return
+      const invokeId = payload.invokeId
+      const toolCallId = payload.toolCallId
+      const name = payload.name
+      const shortName = payload.shortName
+      if (
+        typeof invokeId !== 'string' ||
+        typeof toolCallId !== 'string' ||
+        typeof name !== 'string' ||
+        typeof shortName !== 'string'
+      ) {
+        return
+      }
+      try {
+        const result = await handler({
+          invokeId,
+          toolCallId,
+          name,
+          shortName,
+          arguments:
+            payload.arguments && typeof payload.arguments === 'object'
+              ? payload.arguments
+              : {},
+        })
+        await bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_TOOLS_COMPLETE, [
+          {
+            invokeId,
+            toolCallId: result.toolCallId ?? toolCallId,
+            content: result.content,
+            isError: result.isError,
+          },
+        ])
+      } catch (error) {
+        await bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_TOOLS_COMPLETE, [
+          {
+            invokeId,
+            toolCallId,
+            content: error instanceof Error ? error.message : String(error),
+            isError: true,
+          },
+        ])
+      }
+    })()
+  })
+}