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

package/src/agents/runtime/pendingToolCalls.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+import { AgentUiRunState } from '../../components/agents/agentTypes.js'
+import { derivePendingToolCalls } from './pendingToolCalls.js'
+import { toolRequiresApproval } from './toolRequiresApproval.js'
+
+describe('derivePendingToolCalls', () => {
+  it('returns unresolved tool calls when state is pending_tools', () => {
+    const pending = derivePendingToolCalls(
+      [
+        {
+          role: 'assistant',
+          content: '',
+          toolCalls: [
+            {
+              id: 'tc-1',
+              name: 'book:read',
+              arguments: {},
+            },
+          ],
+        },
+      ],
+      AgentUiRunState.PendingTools,
+    )
+    expect(pending.map(call => call.id)).toEqual(['tc-1'])
+  })
+
+  it('returns empty when state is not pending_tools', () => {
+    expect(
+      derivePendingToolCalls(
+        [
+          {
+            role: 'assistant',
+            content: '',
+            toolCalls: [
+              { id: 'tc-1', name: 'book:read', arguments: {} },
+            ],
+          },
+        ],
+        AgentUiRunState.AwaitingUser,
+      ),
+    ).toEqual([])
+  })
+})
+
+describe('toolRequiresApproval', () => {
+  it('honors approval overrides over defaults', () => {
+    expect(
+      toolRequiresApproval('book:read', {
+        allowedTargetApps: ['book'],
+        approvalOverrides: { 'book:read': false },
+      }),
+    ).toBe(false)
+    expect(
+      toolRequiresApproval('book:write', {
+        allowedTargetApps: ['book'],
+        approvalOverrides: { 'book:read': false },
+        defaultRequiresApproval: true,
+      }),
+    ).toBe(true)
+  })
+
+  it('never requires approval for harness context read tools when policy is merged', () => {
+    expect(
+      toolRequiresApproval('harness.grep_context', {
+        allowedTargetApps: ['book'],
+        defaultRequiresApproval: true,
+        approvalOverrides: {
+          'harness.grep_context': false,
+          'harness.invoke_agent': true,
+          'harness.read_context_chunk': false,
+        },
+      }),
+    ).toBe(false)
+    expect(
+      toolRequiresApproval('harness.invoke_agent', {
+        allowedTargetApps: ['book'],
+        defaultRequiresApproval: true,
+        approvalOverrides: {
+          'harness.grep_context': false,
+          'harness.invoke_agent': true,
+        },
+      }),
+    ).toBe(true)
+  })
+})

package/src/agents/runtime/pendingToolCalls.ts

@@ -0,0 +1,14 @@
+import type { PlatformAgentMessage } from '../../bridge/agentTypes.js'
+import { AgentUiRunState } from '../../components/agents/agentTypes.js'
+import type { AgentUiToolCall } from '../../components/agents/agentTypes.js'
+import { unresolvedToolCalls } from './unresolvedToolCalls.js'
+
+export function derivePendingToolCalls(
+  messages: readonly PlatformAgentMessage[],
+  state: string,
+): AgentUiToolCall[] {
+  if (state !== AgentUiRunState.PendingTools) {
+    return []
+  }
+  return unresolvedToolCalls(messages)
+}

package/src/agents/runtime/toolRequiresApproval.ts

@@ -0,0 +1,20 @@
+import type { PlatformAgentSessionToolPolicy } from '../../bridge/agentTypes.js'
+
+/** Resolve whether a qualified tool name needs user approval before routing. */
+export function toolRequiresApproval(
+  qualifiedName: string,
+  policy: PlatformAgentSessionToolPolicy,
+): boolean {
+  if (
+    policy.approvalOverrides &&
+    Object.hasOwn(policy.approvalOverrides, qualifiedName)
+  ) {
+    return policy.approvalOverrides[qualifiedName]!
+  }
+
+  if (policy.defaultRequiresApproval !== undefined) {
+    return policy.defaultRequiresApproval
+  }
+
+  return true
+}

package/src/agents/runtime/unresolvedToolCalls.ts

@@ -0,0 +1,42 @@
+import type { PlatformAgentMessage } from '../../bridge/agentTypes.js'
+import type { AgentUiToolCall } from '../../components/agents/agentTypes.js'
+
+function lastAssistantToolRequest(
+  messages: readonly PlatformAgentMessage[],
+): PlatformAgentMessage | undefined {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (message.role === 'assistant' && message.toolCalls?.length) {
+      return message
+    }
+  }
+  return undefined
+}
+
+/** Tool calls on the latest assistant tool-request turn that lack a matching tool result. */
+export function unresolvedToolCalls(
+  messages: readonly PlatformAgentMessage[],
+): AgentUiToolCall[] {
+  const assistantTurn = lastAssistantToolRequest(messages)
+  if (!assistantTurn?.toolCalls?.length) {
+    return []
+  }
+
+  const resolvedIds = new Set(
+    messages
+      .filter(
+        message =>
+          message.role === 'tool' &&
+          typeof message.toolCallId === 'string',
+      )
+      .map(message => message.toolCallId as string),
+  )
+
+  return assistantTurn.toolCalls
+    .filter(call => !resolvedIds.has(call.id))
+    .map(call => ({
+      id: call.id,
+      name: call.name,
+      arguments: { ...call.arguments },
+    }))
+}

package/src/bridge/agentModelTiers.ts

@@ -0,0 +1,50 @@
+/** Default high-tier model id (matches shell catalog). */
+export const DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID = 'deepseek:deepseek-v4-pro'
+
+/** Default low-tier model id (matches shell catalog). */
+export const DEFAULT_AGENT_LOW_LEVEL_MODEL_ID = 'deepseek:deepseek-v4-flash'
+
+/** Session model sentinel — resolved per user message in the shell agent host. */
+export const AGENT_AUTO_MODEL_ID = 'auto'
+export const AGENT_AUTO_MODEL_LABEL = 'Auto'
+
+export function isAgentAutoModelId(modelId: string | undefined | null): boolean {
+  return modelId === AGENT_AUTO_MODEL_ID
+}
+
+export interface PlatformAgentModelTiers {
+  lowLevelModelId: string
+  highLevelModelId: string
+}
+
+export interface PlatformAgentSessionConfigPatch {
+  modelId?: string
+  sessionPrompt?: string
+  toolPolicy?: {
+    allowedTargetApps?: string[]
+    routeReadinessMs?: number
+    handlerResponseMs?: number
+    defaultRequiresApproval?: boolean
+    approvalOverrides?: Record<string, boolean>
+  }
+}
+
+export interface PlatformAgentSessionScopeDefaults {
+  global?: PlatformAgentSessionConfigPatch
+  apps?: Record<string, PlatformAgentSessionConfigPatch>
+}
+
+/** Resolve tier ids from shell preferences with catalog fallbacks. */
+export function resolveAgentModelTiersFromPrefs(
+  prefs: {
+    agentModelTiers?: Partial<PlatformAgentModelTiers>
+  } | null | undefined,
+): PlatformAgentModelTiers {
+  const stored = prefs?.agentModelTiers
+  return {
+    lowLevelModelId:
+      stored?.lowLevelModelId?.trim() || DEFAULT_AGENT_LOW_LEVEL_MODEL_ID,
+    highLevelModelId:
+      stored?.highLevelModelId?.trim() || DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID,
+  }
+}

package/src/bridge/agentToolHandlers.ts

@@ -0,0 +1,23 @@
+import type {
+  AgentToolHandler,
+  AgentToolHandlerResult,
+  AgentToolInvokeContext,
+} from './react/usePlatformAgentTools.js'
+
+export type AgentToolHandlerFn<TContext> = (
+  context: TContext,
+  invoke: AgentToolInvokeContext,
+) => Promise<AgentToolHandlerResult>
+
+/** Bind tab-scoped context to modular per-tool handler functions. */
+export function createAgentToolHandlers<TContext>(
+  definitions: Record<string, AgentToolHandlerFn<TContext>>,
+  getContext: () => TContext,
+): Record<string, AgentToolHandler> {
+  return Object.fromEntries(
+    Object.entries(definitions).map(([name, handler]) => [
+      name,
+      (invoke: AgentToolInvokeContext) => handler(getContext(), invoke),
+    ]),
+  )
+}

package/src/bridge/agentToolHelpers.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import {
+  agentToolErrorContent,
+  formatAgentToolJson,
+  readAgentToolStringArg,
+} from './agentToolHelpers.js'
+
+describe('agentToolHelpers', () => {
+  it('reads trimmed string args', () => {
+    expect(
+      readAgentToolStringArg({ bookPath: ' /tmp/book ' }, 'bookPath'),
+    ).toBe('/tmp/book')
+    expect(readAgentToolStringArg({}, 'bookPath')).toBeNull()
+    expect(readAgentToolStringArg({ bookPath: '   ' }, 'bookPath')).toBeNull()
+  })
+
+  it('formats JSON tool payloads', () => {
+    expect(formatAgentToolJson({ ok: true })).toBe('{\n  "ok": true\n}')
+  })
+
+  it('builds error results', () => {
+    expect(agentToolErrorContent('nope')).toEqual({
+      content: 'nope',
+      isError: true,
+    })
+  })
+})

package/src/bridge/agentToolHelpers.ts

@@ -0,0 +1,20 @@
+export function readAgentToolStringArg(
+  args: Record<string, unknown>,
+  key: string,
+): string | null {
+  const value = args[key]
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+export function formatAgentToolJson(value: unknown): string {
+  return JSON.stringify(value, null, 2)
+}
+
+export function agentToolErrorContent(message: string): {
+  content: string
+  isError: true
+} {
+  return { content: message, isError: true }
+}

package/src/bridge/agentTypes.ts

@@ -0,0 +1,294 @@
+/** Plugin-facing agent session types — mirror shell store shape without importing shell code. */
+
+export const PlatformAgentSessionScope = {
+  App: 'app',
+  Global: 'global',
+} as const
+
+export type PlatformAgentSessionScope =
+  (typeof PlatformAgentSessionScope)[keyof typeof PlatformAgentSessionScope]
+
+export type PlatformAgentUiRunState =
+  | 'ready'
+  | 'pending_tools'
+  | 'awaiting_user'
+  | 'failed'
+  | 'interrupted'
+
+export type PlatformAgentMessageRole = 'system' | 'user' | 'assistant' | 'tool'
+
+export interface PlatformAgentImageAttachment {
+  type: 'image'
+  mimeType: string
+  data: string
+  name?: string
+}
+
+export type PlatformAgentMessageAttachment = PlatformAgentImageAttachment
+
+export interface PlatformAgentUiToolCall {
+  id: string
+  name: string
+  arguments: Record<string, unknown>
+}
+
+export type PlatformAgentMessageContentPart =
+  | { type: 'text'; text: string }
+  | {
+      type: 'image_url'
+      imageUrl: string
+      mimeType?: string
+      detail?: 'auto' | 'low' | 'high'
+    }
+
+/** An image attached to a user message, delivered to vision-capable models. */
+export interface PlatformAgentImageBlock {
+  /** MIME type, e.g. 'image/png'. */
+  mediaType: string
+  /** Raw base64 payload — NO `data:` URL prefix. */
+  dataBase64: string
+}
+
+export interface PlatformAgentMessage {
+  role: PlatformAgentMessageRole
+  content: string
+  contentParts?: PlatformAgentMessageContentPart[]
+  attachments?: PlatformAgentMessageAttachment[]
+  toolCallId?: string
+  toolCalls?: PlatformAgentUiToolCall[]
+  images?: PlatformAgentImageBlock[]
+}
+
+export interface PlatformAgentSessionToolPolicy {
+  /** Empty list allows routing to any app with registered tools. */
+  allowedTargetApps: string[]
+  routeReadinessMs?: number
+  handlerResponseMs?: number
+  defaultRequiresApproval?: boolean
+  approvalOverrides?: Record<string, boolean>
+}
+
+export interface PlatformAgentSessionConfig {
+  modelId: string
+  /** Appended after the app's agents.md base prompt. */
+  sessionPrompt?: string
+  /** Full system prompt override. When set, replaces agents.md and sessionPrompt. */
+  systemPrompt?: string
+  toolPolicy?: PlatformAgentSessionToolPolicy
+}
+
+export interface PlatformAgentSessionMetadata {
+  title: string
+  createdAt: string
+  updatedAt: string
+  restoreTabId?: string
+  lastActiveAt?: string
+}
+
+export interface PlatformAgentSessionSnapshot {
+  state: PlatformAgentUiRunState
+  turn: number
+  messages: PlatformAgentMessage[]
+  error?: string
+  interruptedReason?: string
+  contextCompaction?: {
+    summary: string
+    activeFromIndex: number
+    updatedAt: string
+  }
+}
+
+export interface PlatformAgentSessionRecord {
+  version: 1
+  sessionId: string
+  scope: PlatformAgentSessionScope
+  appSlug?: string
+  config: PlatformAgentSessionConfig
+  metadata: PlatformAgentSessionMetadata
+  snapshot: PlatformAgentSessionSnapshot
+  runId?: string
+}
+
+export interface PlatformAgentSessionSummary {
+  sessionId: string
+  title: string
+  updatedAt: string
+  state: PlatformAgentUiRunState
+  restoreTabId?: string
+}
+
+export interface PlatformCreateAgentSessionRequest {
+  scope: PlatformAgentSessionScope
+  appSlug?: string
+  title?: string
+  config?: PlatformAgentSessionConfigPatch
+  restoreTabId?: string
+}
+
+export type PlatformAgentSessionConfigPatch = Omit<
+  Partial<PlatformAgentSessionConfig>,
+  'toolPolicy'
+> & {
+  toolPolicy?: Partial<PlatformAgentSessionToolPolicy>
+}
+
+export interface PlatformListAgentSessionsRequest {
+  scope: PlatformAgentSessionScope
+  appSlug?: string
+}
+
+export interface PlatformReadAgentSessionRequest {
+  scope: PlatformAgentSessionScope
+  sessionId: string
+  appSlug?: string
+}
+
+export interface PlatformUpdateAgentSessionRequest {
+  query: PlatformReadAgentSessionRequest
+  patch: {
+    config?: PlatformAgentSessionConfigPatch
+    metadata?: Partial<PlatformAgentSessionMetadata>
+    snapshot?: PlatformAgentSessionSnapshot
+    runId?: string | null
+  }
+}
+
+/** Host → plugin streaming event payload (subset; extended per event type in main). */
+export interface PlatformAgentRunEvent {
+  runId: string
+  seq: number
+  type: string
+}
+
+/** Live run snapshot returned by the agents.run.* bridge methods. */
+export interface PlatformAgentRunSnapshot {
+  runId: string
+  state: PlatformAgentUiRunState
+  turn: number
+  messages: PlatformAgentMessage[]
+  error?: string
+  interruptedReason?: string
+  effectiveModelId?: string
+  routingTier?: 'low' | 'high'
+  usage?: PlatformAgentRunUsage
+}
+
+export interface PlatformAgentRunUsage {
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
+  contextWindowTokens?: number
+  contextFillTokens?: number
+  estimated?: boolean
+}
+
+/** Snapshot + main-resolved routing policy (`readAgentRunContext`). */
+export interface PlatformAgentRunContext {
+  snapshot: PlatformAgentRunSnapshot
+  effectiveToolPolicy: PlatformAgentSessionToolPolicy
+  sessionId: string
+}
+
+/** Shared session handle for session-drive bridge methods. */
+export interface PlatformAgentSessionDriveRequest {
+  session: PlatformReadAgentSessionRequest
+  restoreTabId?: string
+}
+
+export interface PlatformSendAgentSessionMessageRequest
+  extends PlatformAgentSessionDriveRequest {
+  message: string
+  attachments?: PlatformAgentMessageAttachment[]
+}
+
+export interface PlatformRejectAgentSessionToolsRequest
+  extends PlatformAgentSessionDriveRequest {
+  rejectReason?: string
+  toolCallIds?: string[]
+}
+
+export interface PlatformApproveAgentSessionToolsRequest
+  extends PlatformAgentSessionDriveRequest {
+  toolCallIds?: string[]
+}
+
+export interface PlatformInterruptAgentSessionRequest
+  extends PlatformAgentSessionDriveRequest {
+  reason?: string
+}
+
+/** Result of shell-driven session operations (send, approve, advance pending). */
+export interface PlatformAgentSessionDriveResult {
+  session: PlatformAgentSessionRecord
+  snapshot: PlatformAgentRunSnapshot
+  /** Merged manifest + session policy when settlement paused on manual tools. */
+  effectiveToolPolicy?: PlatformAgentSessionToolPolicy
+  /** Unresolved tools that still need explicit user approval. */
+  manualPendingToolCalls: PlatformAgentUiToolCall[]
+}
+
+export interface PlatformAgentLlmMenuOption {
+  value: string
+  label: string
+  contextWindowTokens?: number
+  supportsImageInput?: boolean
+}
+
+export interface PlatformReadAgentLlmMenuOptionsRequest {
+  selectedModelId?: string
+}
+
+export interface PlatformLocalModelRuntimeStatus {
+  ok: boolean
+  runtime: 'ollama'
+  error?: string
+  loaded: ReadonlyArray<{
+    name: string
+    size: number
+    processor?: string
+    context?: number
+    until?: string
+  }>
+  installed: readonly string[]
+}
+
+/** Materialize a run for an existing session and send the first message. */
+export interface PlatformStartAgentRunRequest {
+  session: PlatformReadAgentSessionRequest
+  message: string
+  contentParts?: PlatformAgentMessageContentPart[]
+  /** Image attachments for the initial user message (vision input). */
+  images?: PlatformAgentImageBlock[]
+  attachments?: PlatformAgentMessageAttachment[]
+}
+
+export interface PlatformCallAgentModelRequest {
+  runId: string
+  sessionId: string
+}
+
+/**
+ * Route policy-approved pending tool calls to their registered app tabs and
+ * resolve them. Tools still pending afterwards require user approval.
+ */
+export interface PlatformResolveAgentToolCallsRequest {
+  runId: string
+  session: PlatformReadAgentSessionRequest
+  resolutions?: PlatformToolResolution | PlatformToolResolution[]
+  toolCallIds?: string[]
+}
+
+export type PlatformToolResolution =
+  | { action: 'approve' }
+  | { action: 'reject'; reason?: string }
+  | { action: 'edit'; content: string }
+
+export interface PlatformSendAgentRunMessageRequest {
+  runId: string
+  message: string
+  attachments?: PlatformAgentMessageAttachment[]
+}
+
+export interface PlatformReadAgentRunContextRequest {
+  runId: string
+}

package/src/bridge/agents.d.mts

@@ -0,0 +1,113 @@
+import type {
+  PlatformAgentLlmMenuOption,
+  PlatformAgentRunContext,
+  PlatformAgentRunEvent,
+  PlatformAgentRunSnapshot,
+  PlatformApproveAgentSessionToolsRequest,
+  PlatformAgentSessionDriveRequest,
+  PlatformAgentSessionDriveResult,
+  PlatformCallAgentModelRequest,
+  PlatformInterruptAgentSessionRequest,
+  PlatformLocalModelRuntimeStatus,
+  PlatformReadAgentLlmMenuOptionsRequest,
+  PlatformReadAgentRunContextRequest,
+  PlatformRejectAgentSessionToolsRequest,
+  PlatformResolveAgentToolCallsRequest,
+  PlatformSendAgentRunMessageRequest,
+  PlatformSendAgentSessionMessageRequest,
+  PlatformStartAgentRunRequest,
+  PlatformAgentSessionRecord,
+  PlatformAgentSessionSummary,
+  PlatformCreateAgentSessionRequest,
+  PlatformListAgentSessionsRequest,
+  PlatformReadAgentSessionRequest,
+  PlatformUpdateAgentSessionRequest,
+} from './agentTypes.js'
+
+export function createAgentSession(
+  request: PlatformCreateAgentSessionRequest,
+): Promise<PlatformAgentSessionRecord>
+
+export function listAgentSessions(
+  request: PlatformListAgentSessionsRequest,
+): Promise<PlatformAgentSessionSummary[]>
+
+export function readAgentSession(
+  request: PlatformReadAgentSessionRequest,
+): Promise<PlatformAgentSessionRecord>
+
+export function updateAgentSession(
+  request: PlatformUpdateAgentSessionRequest,
+): Promise<PlatformAgentSessionRecord>
+
+export function deleteAgentSession(
+  request: PlatformReadAgentSessionRequest,
+): Promise<void>
+
+export function sendAgentSessionMessage(
+  request: PlatformSendAgentSessionMessageRequest,
+): Promise<PlatformAgentSessionDriveResult>
+
+export function approveAgentSessionTools(
+  request: PlatformApproveAgentSessionToolsRequest,
+): Promise<PlatformAgentSessionDriveResult | null>
+
+export function rejectAgentSessionTools(
+  request: PlatformRejectAgentSessionToolsRequest,
+): Promise<PlatformAgentSessionDriveResult | null>
+
+export function advanceAgentSessionPending(
+  request: PlatformAgentSessionDriveRequest,
+): Promise<PlatformAgentSessionDriveResult | null>
+
+export function interruptAgentSession(
+  request: PlatformInterruptAgentSessionRequest,
+): Promise<PlatformAgentSessionDriveResult>
+
+export function onAgentRunEvent(
+  listener: (payload: PlatformAgentRunEvent) => void,
+): () => void
+
+export function startAgentRun(
+  request: PlatformStartAgentRunRequest,
+): Promise<PlatformAgentRunSnapshot>
+
+export function callAgentRunModel(
+  request: PlatformCallAgentModelRequest,
+): Promise<PlatformAgentRunSnapshot>
+
+export function resolveAgentRunToolCalls(
+  request: PlatformResolveAgentToolCallsRequest,
+): Promise<PlatformAgentRunSnapshot>
+
+export function sendAgentRunMessage(
+  request: PlatformSendAgentRunMessageRequest,
+): Promise<PlatformAgentRunSnapshot>
+
+export function readAgentRunContext(
+  request: PlatformReadAgentRunContextRequest,
+): Promise<PlatformAgentRunContext>
+
+export function readAgentLlmMenuOptions(
+  request?: PlatformReadAgentLlmMenuOptionsRequest,
+): Promise<PlatformAgentLlmMenuOption[]>
+
+export function readLocalModelsStatus(): Promise<PlatformLocalModelRuntimeStatus>
+
+export function registerAgentTools(request: {
+  tools: string[]
+}): Promise<{ ok: boolean; tools: string[] }>
+
+export function onAgentToolInvoke(
+  handler: (payload: {
+    invokeId: string
+    toolCallId: string
+    name: string
+    shortName: string
+    arguments: Record<string, unknown>
+  }) => Promise<{
+    toolCallId: string
+    content: string
+    isError?: boolean
+  }>,
+): () => void