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

package/src/bridge/agentTypes.ts

@@ -1,294 +1,377 @@
-/** 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
-}
+/** 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
+  /** Tool-call IDs whose manual approval was accepted while downstream work remains pending. */
+  acceptedPendingToolCallIds?: 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 type PlatformAgentJobStatus =
+  | 'queued'
+  | 'running'
+  | 'waiting_tools'
+  | 'waiting_app_tool'
+  | 'waiting_approval'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export type PlatformAgentJobSchedule =
+  | { type: 'once' }
+  | { type: 'manual' }
+  | { type: 'interval'; intervalMs: number }
+  | { type: 'daily'; timeOfDay: string }
+  | { type: 'weekly'; dayOfWeek: number; timeOfDay: string }
+
+export interface PlatformAgentJobRecord {
+  version: 1
+  jobId: string
+  sessionId: string
+  scope: PlatformAgentSessionScope
+  appSlug?: string
+  title?: string
+  message?: string
+  schedule: PlatformAgentJobSchedule
+  status: PlatformAgentJobStatus
+  nextRunAt?: string
+  lastRunAt?: string
+  lastStartedAt?: string
+  lastFinishedAt?: string
+  leaseId?: string
+  leaseExpiresAt?: string
+  attempts: number
+  lastError?: string
+  createdAt: string
+  updatedAt: string
+}
+
+export interface PlatformCreateAgentJobRequest {
+  sessionId: string
+  scope: PlatformAgentSessionScope
+  appSlug?: string
+  title?: string
+  message: string
+  schedule?: PlatformAgentJobSchedule
+  nextRunAt?: string
+}
+
+export interface PlatformListAgentJobsRequest {
+  sessionId?: string
+  scope?: PlatformAgentSessionScope
+  appSlug?: string
+  status?: PlatformAgentJobStatus
+}
+
+export interface PlatformReadAgentJobRequest {
+  jobId: string
+}
+
+export interface PlatformCancelAgentJobRequest
+  extends PlatformReadAgentJobRequest {
+  reason?: 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[]
+  /** Unresolved harness questions that need a user answer in the composer. */
+  pendingQuestionToolCalls?: PlatformAgentUiToolCall[]
+}
+
+export interface PlatformAgentLlmMenuOption {
+  value: string
+  label: string
+  groupLabel?: string
+  meta?: string
+  contextWindowTokens?: number
+  supportsImageInput?: boolean
+}
+
+export interface PlatformReadAgentLlmMenuOptionsRequest {
+  selectedModelId?: string
+}
+
+export interface PlatformLowModelJsonRequest {
+  attachments?: PlatformAgentMessageAttachment[]
+  modelTier?: 'low' | 'high'
+  prompt: string
+  systemPrompt?: string
+}
+
+export interface PlatformLowModelJsonResponse {
+  content: string
+  modelId: 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
+}