@puredesktop/puredesktop-ui-bridge 2.1.8 → 2.1.9

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

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest'
+import type { PlatformAgentMessage } from '../../bridge/agentTypes.js'
+import {
+  derivePendingAsks,
+  sessionPendingAskCalls,
+  type PendingAskSession,
+} from './pendingAsks.js'
+
+function pendingMessages(
+  calls: Array<{ id: string; name: string }>,
+): PlatformAgentMessage[] {
+  return [
+    { role: 'user', content: 'do the thing' },
+    {
+      role: 'assistant',
+      content: '',
+      toolCalls: calls.map(call => ({ ...call, arguments: {} })),
+    },
+  ]
+}
+
+function session(
+  overrides: Partial<PendingAskSession> = {},
+): PendingAskSession {
+  return {
+    scope: 'global',
+    sessionId: 'parent-1',
+    state: 'pending_tools',
+    messages: pendingMessages([{ id: 'call-1', name: 'harness.invoke_agent' }]),
+    ...overrides,
+  }
+}
+
+describe('sessionPendingAskCalls', () => {
+  it('lists unresolved pending calls', () => {
+    expect(sessionPendingAskCalls(session())).toEqual([
+      { id: 'call-1', name: 'harness.invoke_agent', arguments: {} },
+    ])
+  })
+
+  it('an accepted call is in flight, not an ask', () => {
+    expect(
+      sessionPendingAskCalls(
+        session({ acceptedPendingToolCallIds: ['call-1'] }),
+      ),
+    ).toEqual([])
+  })
+
+  it('a settled session has no asks', () => {
+    expect(
+      sessionPendingAskCalls(session({ state: 'awaiting_user' })),
+    ).toEqual([])
+  })
+
+  it('policy-approved calls are not asks when a policy is supplied', () => {
+    expect(
+      sessionPendingAskCalls(
+        session({
+          toolPolicy: {
+            allowedTargetApps: [],
+            routeReadinessMs: 1_000,
+            handlerResponseMs: 1_000,
+            approvalOverrides: { 'harness.invoke_agent': false },
+          },
+        }),
+      ),
+    ).toEqual([])
+  })
+})
+
+describe('derivePendingAsks', () => {
+  it('an active child delegation ask outranks the parent ask', () => {
+    const asks = derivePendingAsks(session(), [
+      {
+        status: 'running',
+        childAppSlug: 'writer',
+        child: session({
+          scope: 'app',
+          sessionId: 'child-1',
+          appSlug: 'writer',
+          messages: pendingMessages([
+            { id: 'call-2', name: 'writer.createDocument' },
+          ]),
+        }),
+      },
+    ])
+
+    expect(asks).toHaveLength(2)
+    expect(asks[0]).toEqual({
+      session: { scope: 'app', sessionId: 'child-1', appSlug: 'writer' },
+      origin: 'child',
+      childAppSlug: 'writer',
+      calls: [{ id: 'call-2', name: 'writer.createDocument', arguments: {} }],
+    })
+    expect(asks[1]).toEqual(
+      expect.objectContaining({ origin: 'parent' }),
+    )
+  })
+
+  it('settled delegations and unreadable children are ignored', () => {
+    const asks = derivePendingAsks(session(), [
+      {
+        status: 'completed',
+        childAppSlug: 'writer',
+        child: session({ sessionId: 'child-done' }),
+      },
+      { status: 'running', childAppSlug: 'book', child: null },
+    ])
+    expect(asks).toEqual([expect.objectContaining({ origin: 'parent' })])
+  })
+
+  it('no asks anywhere yields an empty list', () => {
+    expect(
+      derivePendingAsks(session({ state: 'awaiting_user' })),
+    ).toEqual([])
+  })
+})

package/src/agents/runtime/pendingAsks.ts

@@ -0,0 +1,110 @@
+import type {
+  PlatformAgentMessage,
+  PlatformAgentSessionScope,
+  PlatformAgentSessionToolPolicy,
+} from '../../bridge/agentTypes.js'
+import type { AgentUiToolCall } from '../../components/agents/agentTypes.js'
+import { derivePendingToolCalls } from './pendingToolCalls.js'
+import { toolRequiresApproval } from './toolRequiresApproval.js'
+
+/**
+ * The one pending-asks selector (docs/09-missions.md §Card states): both the
+ * agent drawer and the mission card derive "what is this run waiting on the
+ * human for?" from here — manual pending calls minus accepted, with active
+ * child-delegation asks taking precedence over the parent's. No surface
+ * keeps its own derivation that can disagree. Approving from either surface
+ * is the same operation against the same session.
+ */
+
+export interface PendingAskSession {
+  scope: PlatformAgentSessionScope
+  sessionId: string
+  appSlug?: string
+  state: string
+  messages: readonly PlatformAgentMessage[]
+  acceptedPendingToolCallIds?: readonly string[]
+  /** When supplied, calls the policy auto-approves are not asks. */
+  toolPolicy?: PlatformAgentSessionToolPolicy
+}
+
+export interface PendingAskDelegation {
+  status: string
+  childAppSlug: string
+  /** The delegated child's session, when the caller could read it. */
+  child?: PendingAskSession | null
+}
+
+export interface PendingAsk {
+  session: {
+    scope: PlatformAgentSessionScope
+    sessionId: string
+    appSlug?: string
+  }
+  /** Child asks come from an active delegated app agent. */
+  origin: 'child' | 'parent'
+  childAppSlug?: string
+  calls: AgentUiToolCall[]
+}
+
+/**
+ * One session's slice of the contract: unresolved manual calls, minus the
+ * accepted-but-still-settling ones (an accepted call is IN FLIGHT — a
+ * delegation or app tool holds it open — not waiting on the human).
+ */
+export function sessionPendingAskCalls(
+  session: Pick<
+    PendingAskSession,
+    'state' | 'messages' | 'acceptedPendingToolCallIds' | 'toolPolicy'
+  >,
+): AgentUiToolCall[] {
+  const accepted = new Set(session.acceptedPendingToolCallIds ?? [])
+  return derivePendingToolCalls(session.messages, session.state)
+    .filter(call => !accepted.has(call.id))
+    .filter(call =>
+      session.toolPolicy
+        ? toolRequiresApproval(call.name, session.toolPolicy)
+        : true,
+    )
+    .map(call => ({ id: call.id, name: call.name, arguments: call.arguments }))
+}
+
+function sessionRef(session: PendingAskSession): PendingAsk['session'] {
+  return {
+    scope: session.scope,
+    sessionId: session.sessionId,
+    ...(session.appSlug ? { appSlug: session.appSlug } : {}),
+  }
+}
+
+function delegationIsActive(status: string): boolean {
+  return status === 'pending' || status === 'running'
+}
+
+/**
+ * All open asks for one run, child-first: while a delegated app agent is
+ * asking, that ask IS the run's current question — a parent-level
+ * `harness.invoke_agent` ask shown instead would be stale.
+ */
+export function derivePendingAsks(
+  parent: PendingAskSession,
+  delegations: readonly PendingAskDelegation[] = [],
+): PendingAsk[] {
+  const asks: PendingAsk[] = []
+  for (const delegation of delegations) {
+    if (!delegationIsActive(delegation.status)) continue
+    if (!delegation.child) continue
+    const calls = sessionPendingAskCalls(delegation.child)
+    if (calls.length === 0) continue
+    asks.push({
+      session: sessionRef(delegation.child),
+      origin: 'child',
+      childAppSlug: delegation.childAppSlug,
+      calls,
+    })
+  }
+  const parentCalls = sessionPendingAskCalls(parent)
+  if (parentCalls.length > 0) {
+    asks.push({ session: sessionRef(parent), origin: 'parent', calls: parentCalls })
+  }
+  return asks
+}

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

@@ -89,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 {
@@ -199,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/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/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',
 }