@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.9

package/src/bridge/agentScopeDefaults.ts

@@ -0,0 +1,65 @@
+import type {
+  PlatformAgentSessionConfigPatch,
+  PlatformAgentSessionScope,
+} from './agentTypes.js'
+import {
+  getPlatformPreferences,
+  patchPlatformPreferences,
+} from './preferences.mjs'
+
+/**
+ * Persist session-config changes as scope defaults in shell preferences
+ * (`agentSessionDefaults.global` / `.apps[slug]`) — layer 3 of the approval
+ * ladder (docs/08-agent-orchestration.md). Every NEW session in the scope
+ * inherits these, mission runs and delegated children included; this is what
+ * makes "always allow" stick beyond one conversation.
+ */
+
+interface StoredScopeDefaults {
+  global?: PlatformAgentSessionConfigPatch
+  apps?: Record<string, PlatformAgentSessionConfigPatch>
+}
+
+export function mergeScopeDefaultPatch(
+  base: PlatformAgentSessionConfigPatch | undefined,
+  patch: PlatformAgentSessionConfigPatch,
+): PlatformAgentSessionConfigPatch {
+  const toolPolicy =
+    patch.toolPolicy || base?.toolPolicy
+      ? {
+          ...base?.toolPolicy,
+          ...patch.toolPolicy,
+          approvalOverrides: {
+            ...base?.toolPolicy?.approvalOverrides,
+            ...patch.toolPolicy?.approvalOverrides,
+          },
+        }
+      : undefined
+  return { ...base, ...patch, ...(toolPolicy ? { toolPolicy } : {}) }
+}
+
+export async function patchAgentSessionScopeDefaults(
+  scope: PlatformAgentSessionScope,
+  appSlug: string | undefined,
+  patch: PlatformAgentSessionConfigPatch,
+): Promise<void> {
+  const prefs = (await getPlatformPreferences()) as {
+    agentSessionDefaults?: StoredScopeDefaults
+  }
+  const stored = prefs.agentSessionDefaults ?? {}
+  if (scope === 'global') {
+    await patchPlatformPreferences({
+      agentSessionDefaults: {
+        ...stored,
+        global: mergeScopeDefaultPatch(stored.global, patch),
+      },
+    })
+    return
+  }
+  if (!appSlug) return
+  const apps = { ...(stored.apps ?? {}) }
+  apps[appSlug] = mergeScopeDefaultPatch(apps[appSlug], patch)
+  await patchPlatformPreferences({
+    agentSessionDefaults: { ...stored, apps },
+  })
+}

package/src/bridge/agentTypes.ts

@@ -24,7 +24,27 @@ export interface PlatformAgentImageAttachment {
   name?: string
 }
 
-export type PlatformAgentMessageAttachment = PlatformAgentImageAttachment
+/**
+ * An object's markdown context document attached to a user message —
+ * output of the context picker (`context.read`). Mirrors the shell's
+ * `AgentContextAttachment`.
+ */
+export interface PlatformAgentContextAttachment {
+  type: 'context'
+  /** Object kind, e.g. 'manuscript' | 'book'. */
+  kind: string
+  appSlug: string
+  objectId: string
+  title: string
+  /** Full or section markdown from the object's context document. */
+  markdown: string
+  /** Durable section id when a segmented read was attached. */
+  section?: string
+}
+
+export type PlatformAgentMessageAttachment =
+  | PlatformAgentImageAttachment
+  | PlatformAgentContextAttachment
 
 export interface PlatformAgentUiToolCall {
   id: string
@@ -69,12 +89,12 @@ export interface PlatformAgentSessionToolPolicy {
 }
 
 export interface PlatformAgentSessionConfig {
-  modelId: string
+  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
+  toolPolicy?: Partial<PlatformAgentSessionToolPolicy>
 }
 
 export interface PlatformAgentSessionMetadata {
@@ -179,6 +199,40 @@ export interface PlatformReadAgentJobRequest {
   jobId: string
 }
 
+export type PlatformAgentDelegationStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export interface PlatformAgentDelegationRecord {
+  version: 1
+  delegationId: string
+  parentJobId?: string
+  parentScope?: PlatformAgentSessionScope
+  parentAppSlug?: string
+  parentSessionId: string
+  parentRunId: string
+  parentToolCallId: string
+  childSessionId: string
+  childAppSlug: string
+  childJobId?: string
+  status: PlatformAgentDelegationStatus
+  resultJson?: unknown
+  error?: string
+  createdAt: string
+  updatedAt: string
+}
+
+export interface PlatformListAgentDelegationsRequest {
+  parentJobId?: string
+  childJobId?: string
+  parentSessionId?: string
+  childSessionId?: string
+  status?: PlatformAgentDelegationStatus
+}
+
 export interface PlatformCancelAgentJobRequest
   extends PlatformReadAgentJobRequest {
   reason?: string

package/src/bridge/agents.d.mts

@@ -23,8 +23,10 @@ import type {
   PlatformCreateAgentSessionRequest,
   PlatformCreateAgentJobRequest,
   PlatformCancelAgentJobRequest,
+  PlatformAgentDelegationRecord,
   PlatformAgentJobRecord,
   PlatformListAgentSessionsRequest,
+  PlatformListAgentDelegationsRequest,
   PlatformListAgentJobsRequest,
   PlatformReadAgentSessionRequest,
   PlatformReadAgentJobRequest,
@@ -71,6 +73,10 @@ export function runAgentJobNow(
   request: PlatformReadAgentJobRequest,
 ): Promise<PlatformAgentJobRecord>
 
+export function listAgentDelegations(
+  request?: PlatformListAgentDelegationsRequest,
+): Promise<PlatformAgentDelegationRecord[]>
+
 export function sendAgentSessionMessage(
   request: PlatformSendAgentSessionMessageRequest,
 ): Promise<PlatformAgentSessionDriveResult>

package/src/bridge/agents.mjs

@@ -78,6 +78,16 @@ export async function runAgentJobNow(request) {
   return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_JOBS_RUN_NOW, [request])
 }
 
+/**
+ * @param {import('./agentTypes.js').PlatformListAgentDelegationsRequest} [request]
+ * @returns {Promise<import('./agentTypes.js').PlatformAgentDelegationRecord[]>}
+ */
+export async function listAgentDelegations(request = {}) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.AGENTS_DELEGATIONS_LIST, [
+    request,
+  ])
+}
+
 /**
  * Send a user message on a session; shell drives the run until awaiting user,
  * manual pending tools, or terminal state.

package/src/bridge/agents.ts

@@ -8,6 +8,7 @@ export {
   createAgentSession,
   deleteAgentSession,
   interruptAgentSession,
+  listAgentDelegations,
   listAgentJobs,
   listAgentSessions,
   onAgentRunEvent,
@@ -29,6 +30,8 @@ export {
 export type {
   PlatformAgentMessage,
   PlatformAgentMessageAttachment,
+  PlatformAgentDelegationRecord,
+  PlatformAgentDelegationStatus,
   PlatformAgentJobRecord,
   PlatformAgentJobSchedule,
   PlatformAgentJobStatus,
@@ -47,6 +50,7 @@ export type {
   PlatformCreateAgentSessionRequest,
   PlatformCreateAgentJobRequest,
   PlatformListAgentSessionsRequest,
+  PlatformListAgentDelegationsRequest,
   PlatformListAgentJobsRequest,
   PlatformReadAgentJobRequest,
   PlatformReadAgentSessionRequest,

package/src/bridge/collectionImagePaste.ts

@@ -25,12 +25,29 @@ export interface CollectionImagePastePayload {
   mimeType: string
 }
 
+export interface CollectionImageInsertPayload {
+  relativePath: string
+  alt: string
+  bytes: Uint8Array
+  mimeType: string
+}
+
 export interface CollectionImagePasteHandlerOptions {
   collectionPath?: string
   subdir?: string
   onError?: (message: string) => void
   getEditor: () => Editor | null | undefined
   writeBinary: (absolutePath: string, bytes: Uint8Array) => Promise<void>
+  /**
+   * Override how the persisted image is placed into the document. Defaults to a
+   * bare image node; callers (e.g. the manuscript editor) can supply a handler
+   * that wraps it in a captioned `<figure>` so it is numbered and
+   * cross-referenceable. Returns `false` if the editor cannot accept the node.
+   */
+  insertImage?: (
+    editor: Editor | null | undefined,
+    image: CollectionImageInsertPayload,
+  ) => boolean
 }
 
 export function normalizeCollectionImageMimeType(
@@ -93,6 +110,7 @@ export function createCollectionImagePasteHandler(
     onError,
     getEditor,
     writeBinary,
+    insertImage = insertCollectionImage,
   } = options
 
   return async ({ name, bytes, mimeType }) => {
@@ -117,7 +135,7 @@ export function createCollectionImagePasteHandler(
     const stem = stemFromImageFileName(name)
     const editor = getEditor()
     if (
-      !insertCollectionImage(editor, {
+      !insertImage(editor, {
         relativePath,
         alt: stem,
         bytes,

package/src/bridge/context.mjs

@@ -10,3 +10,35 @@ import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
 export async function publishContext(request) {
   return bridge.call(PLATFORM_BRIDGE_METHODS.CONTEXT_PUBLISH, [request])
 }
+
+/**
+ * Resolve one object's context document — generates or refreshes the
+ * `<name>.<kind>.md` file when missing or stale. Requires `filesystem`.
+ *
+ * @param {{ path?: string, appSlug?: string, objectId?: string }} ref
+ * @returns {Promise<import('../context/contextAccess.js').PlatformContextResolveResult>}
+ */
+export async function resolveContextDocument(ref) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CONTEXT_RESOLVE, [ref])
+}
+
+/**
+ * Read one object's context markdown — the whole document or one section by
+ * durable section id. Requires `filesystem`.
+ *
+ * @param {{ path?: string, appSlug?: string, objectId?: string, section?: string }} request
+ * @returns {Promise<import('../context/contextAccess.js').PlatformContextReadResult>}
+ */
+export async function readContextDocument(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CONTEXT_READ, [request])
+}
+
+/**
+ * Search context-enabled objects across apps. Requires `filesystem`.
+ *
+ * @param {{ query: string, kinds?: string[], appSlug?: string, limit?: number }} request
+ * @returns {Promise<import('../context/contextAccess.js').PlatformContextSearchHit[]>}
+ */
+export async function searchContextObjects(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CONTEXT_SEARCH, [request])
+}

package/src/bridge/credentials.d.mts

@@ -0,0 +1,62 @@
+export interface CredentialStorageStatus {
+  encryptionAvailable: boolean
+  backend: string | null
+  secure: boolean
+  warning?: string
+}
+
+export interface CredentialEntryStatus {
+  id: string
+  label: string
+  description?: string
+  configured: boolean
+}
+
+/** Redacted OAuth connection state — never contains secret material. */
+export interface OAuthCredentialStatus {
+  id: string
+  kind: 'oauth'
+  provider: 'google'
+  configured: boolean
+  connected: boolean
+  email?: string
+  scopes: string[]
+  needsReconnect: boolean
+  updatedAt?: string
+}
+
+export function readCredentialStorageStatus(): Promise<CredentialStorageStatus>
+
+export function listCredentials(): Promise<CredentialEntryStatus[]>
+
+export function setCredential(request: {
+  id: string
+  value: string
+}): Promise<{ ok: true }>
+
+export function deleteCredential(request: { id: string }): Promise<{ ok: true }>
+
+export function readCredentialStatus(request: {
+  id: string
+}): Promise<OAuthCredentialStatus>
+
+export function setCredentialOAuthConfig(request: {
+  id: string
+  clientId: string
+  clientSecret: string
+  scopes?: string[]
+}): Promise<{ ok: true }>
+
+export function connectCredentialOAuth(request: {
+  id: string
+  scopes?: string[]
+}): Promise<{ email?: string }>
+
+export function disconnectCredential(request: {
+  id: string
+  forget?: boolean
+}): Promise<{ ok: true }>
+
+export function readCredentialOAuthAccessToken(request: {
+  id: string
+}): Promise<{ accessToken: string; expiresAt: number }>

package/src/bridge/credentials.mjs

@@ -20,3 +20,56 @@ export async function setCredential(request) {
 export async function deleteCredential(request) {
   return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_DELETE, [request])
 }
+
+/**
+ * Redacted OAuth connection state — the only credential state apps may read.
+ * @param {{ id: string }} request
+ * @returns {Promise<{ id: string, configured: boolean, connected: boolean, email?: string, scopes: string[], needsReconnect: boolean, updatedAt?: string }>}
+ */
+export async function readCredentialStatus(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_STATUS, [request])
+}
+
+/**
+ * Write-only OAuth client config; the secret is never echoed back.
+ * @param {{ id: string, clientId: string, clientSecret: string, scopes?: string[] }} request
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function setCredentialOAuthConfig(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_SET_OAUTH_CONFIG, [
+    request,
+  ])
+}
+
+/**
+ * Runs the full OAuth flow in the shell (browser + loopback + token
+ * exchange); no token or secret ever reaches the caller.
+ * @param {{ id: string, scopes?: string[] }} request
+ * @returns {Promise<{ email?: string }>}
+ */
+export async function connectCredentialOAuth(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_CONNECT_OAUTH, [
+    request,
+  ])
+}
+
+/**
+ * Clears tokens + identity; pass `forget: true` to also drop the client config.
+ * @param {{ id: string, forget?: boolean }} request
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function disconnectCredential(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_DISCONNECT, [request])
+}
+
+/**
+ * Short-lived access token for providers that call the API directly.
+ * Refreshed transparently in the shell; refresh tokens never cross the bridge.
+ * @param {{ id: string }} request
+ * @returns {Promise<{ accessToken: string, expiresAt: number }>}
+ */
+export async function readCredentialOAuthAccessToken(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.CREDENTIALS_OAUTH_ACCESS_TOKEN, [
+    request,
+  ])
+}

package/src/bridge/documents.d.mts

@@ -0,0 +1,76 @@
+/** One file inside a document. `name: null` addresses a single-file document
+ * itself; a string is a path relative to a package directory. */
+export interface PlatformDocumentFilePayload {
+  name: string | null
+  content: string
+}
+
+export interface PlatformDocumentCreateDraftRequest {
+  appSlug: string
+  suffix: string
+  kind: 'package' | 'file'
+  title?: string
+  files: PlatformDocumentFilePayload[]
+}
+
+export interface PlatformDocumentListEntry {
+  path: string
+  name: string
+  mtimeMs: number
+  isDraft: boolean
+  kind: 'package' | 'file'
+}
+
+export interface PlatformRecentDocumentEntry {
+  path: string
+  title: string
+  touchedAt: string
+}
+
+export function createPlatformDraft(
+  request: PlatformDocumentCreateDraftRequest,
+): Promise<{ path: string }>
+
+export function autosavePlatformDocument(request: {
+  path: string
+  files: PlatformDocumentFilePayload[]
+}): Promise<{ savedAt: string }>
+
+export function promotePlatformDocument(request: {
+  path: string
+  title: string
+  targetDir?: string
+  /** The document type's real suffix (e.g. `.chart.json`) — required for
+   * compound suffixes, which cannot be recovered from the path. */
+  suffix?: string
+  appSlug?: string
+}): Promise<{ path: string }>
+
+export function renamePlatformDocument(request: {
+  path: string
+  title: string
+  suffix?: string
+  appSlug?: string
+}): Promise<{ path: string }>
+
+export function duplicatePlatformDocument(request: {
+  path: string
+  suffix?: string
+}): Promise<{ path: string }>
+
+export function listPlatformDocumentsByType(request: {
+  suffixes: string[]
+}): Promise<PlatformDocumentListEntry[]>
+
+export function listPlatformRecentDocuments(request: {
+  appSlug: string
+  limit?: number
+}): Promise<PlatformRecentDocumentEntry[]>
+
+export function touchPlatformRecentDocument(request: {
+  appSlug: string
+  path: string
+  title: string
+}): Promise<void>
+
+export function suggestPlatformDocumentLocation(): Promise<{ dir: string }>

package/src/bridge/documents.mjs

@@ -0,0 +1,40 @@
+import { bridge } from './client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from './methods.mjs'
+
+/** Unified document lifecycle bridge: drafts, autosave, filing, recents. */
+
+export async function createPlatformDraft(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_CREATE_DRAFT, [request])
+}
+
+export async function autosavePlatformDocument(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_AUTOSAVE, [request])
+}
+
+export async function promotePlatformDocument(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_PROMOTE, [request])
+}
+
+export async function renamePlatformDocument(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_RENAME, [request])
+}
+
+export async function duplicatePlatformDocument(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_DUPLICATE, [request])
+}
+
+export async function listPlatformDocumentsByType(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_LIST_BY_TYPE, [request])
+}
+
+export async function listPlatformRecentDocuments(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_RECENTS_LIST, [request])
+}
+
+export async function touchPlatformRecentDocument(request) {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_RECENTS_TOUCH, [request])
+}
+
+export async function suggestPlatformDocumentLocation() {
+  return bridge.call(PLATFORM_BRIDGE_METHODS.DOCUMENTS_SUGGEST_LOCATION, [])
+}

package/src/bridge/events.d.mts

@@ -8,6 +8,7 @@ export declare const PLATFORM_BRIDGE_EVENTS: {
   readonly DEBUG_TEST: 'debug.test'
   readonly SCHEDULE_FIRE: 'schedule.fire'
   readonly WINDOW_CAMERA_SHORTCUT: 'window.cameraShortcut'
+  readonly OPERATIONS_CHANGED: 'operations.changed'
 }
 
 export type PlatformBridgeEventName =

package/src/bridge/events.mjs

@@ -9,4 +9,5 @@ export const PLATFORM_BRIDGE_EVENTS = {
   DEBUG_TEST: 'debug.test',
   SCHEDULE_FIRE: 'schedule.fire',
   WINDOW_CAMERA_SHORTCUT: 'window.cameraShortcut',
+  OPERATIONS_CHANGED: 'operations.changed',
 }