@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.9

package/src/agents/mcpServerPresets.ts

@@ -0,0 +1,380 @@
+/**
+ * Curated MCP servers preloaded with PureDesktop — one click to add from the
+ * assistant Tools library (nothing is enabled until the user confirms).
+ * Selection favors keyless servers; entries that need a key say so and the
+ * UI asks for the bearer token after the first failing test.
+ *
+ * `stdio` presets run locally and need their runner on PATH (`npx` → Node,
+ * `uvx` → uv); remote presets need nothing. The Test button verifies either
+ * way, so a missing runner or a renamed package fails loudly, not silently.
+ */
+
+export type McpServerPresetTransport = 'http' | 'sse' | 'stdio'
+
+export type McpServerPresetCategory =
+  | 'academic'
+  | 'knowledge'
+  | 'documentation'
+  | 'developer'
+
+export type McpServerPresetAuth = 'none' | 'bearer' | 'apiKey'
+
+export interface McpServerPreset {
+  /** Registry id — `[a-z0-9-]+`, stable across releases. */
+  id: string
+  label: string
+  description: string
+  category: McpServerPresetCategory
+  transport: McpServerPresetTransport
+  url?: string
+  command?: string
+  args?: string[]
+  /**
+   * How the server authenticates: `bearer` (Authorization header on a remote
+   * server) or `apiKey` (an env var, named by `apiKeyEnvVar`, on a local stdio
+   * server). Omitted → no auth.
+   */
+  auth?: McpServerPresetAuth
+  /** Env var the key is passed as, for `auth: 'apiKey'` servers. */
+  apiKeyEnvVar?: string
+  /** Preset needs a secret (bearer token or API key) before it will connect. */
+  requiresToken?: boolean
+  /** Short caveat shown with the entry (runner needed, rate limits, …). */
+  note?: string
+  /**
+   * Site to pull a favicon from for the row logo. Auto-derived from `url` for
+   * remote presets; set explicitly for local (stdio) presets that still have a
+   * recognizable home page (arXiv, PubMed, …) so they don't fall back to plain
+   * initials.
+   */
+  iconDomain?: string
+}
+
+export const MCP_SERVER_PRESETS: readonly McpServerPreset[] = [
+  // ---- Academic research ----------------------------------------------------
+  {
+    id: 'arxiv',
+    label: 'arXiv',
+    description:
+      'Search arXiv preprints, fetch abstracts, and download papers for analysis.',
+    category: 'academic',
+    transport: 'stdio',
+    command: 'uvx',
+    args: ['arxiv-mcp-server'],
+    note: 'Python server — needs uv (one-time install).',
+    iconDomain: 'arxiv.org',
+  },
+  {
+    id: 'pubmed',
+    label: 'PubMed',
+    description:
+      'Search PubMed biomedical literature and fetch article metadata and abstracts.',
+    category: 'academic',
+    transport: 'stdio',
+    command: 'uvx',
+    args: ['pubmedmcp'],
+    note: 'Python server — needs uv (one-time install).',
+    iconDomain: 'pubmed.ncbi.nlm.nih.gov',
+  },
+  {
+    id: 'wikipedia',
+    label: 'Wikipedia',
+    description:
+      'Look up and summarize Wikipedia articles with full-text search.',
+    category: 'academic',
+    transport: 'stdio',
+    command: 'uvx',
+    args: ['wikipedia-mcp'],
+    note: 'Python server — needs uv (one-time install).',
+    iconDomain: 'wikipedia.org',
+  },
+  {
+    id: 'huggingface',
+    label: 'Hugging Face',
+    description:
+      'Search models, datasets, Spaces, and daily papers on the Hugging Face Hub.',
+    category: 'academic',
+    transport: 'http',
+    url: 'https://huggingface.co/mcp',
+    note: 'Remote server; anonymous access is rate-limited.',
+  },
+  {
+    id: 'exa',
+    label: 'Exa research',
+    description:
+      'Neural web + research-paper search with full-text retrieval — strong for academic literature.',
+    category: 'academic',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', 'exa-mcp-server'],
+    auth: 'apiKey',
+    apiKeyEnvVar: 'EXA_API_KEY',
+    requiresToken: true,
+    note: 'Runs via npx (Node). Needs a free Exa API key (asked for after adding).',
+    iconDomain: 'exa.ai',
+  },
+
+  // ---- General knowledge work ----------------------------------------------
+  {
+    id: 'fetch',
+    label: 'Web fetch',
+    description:
+      'Fetch a web page and convert it to markdown for reading and citation.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'uvx',
+    args: ['mcp-server-fetch'],
+    note: 'Python reference server — needs uv (one-time install).',
+    iconDomain: 'developer.mozilla.org',
+  },
+  {
+    id: 'duckduckgo',
+    label: 'DuckDuckGo search',
+    description: 'Key-free web search with content extraction.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'uvx',
+    args: ['duckduckgo-mcp-server'],
+    note: 'Python server — needs uv (one-time install).',
+    iconDomain: 'duckduckgo.com',
+  },
+  {
+    id: 'memory',
+    label: 'Memory (knowledge graph)',
+    description:
+      'Persistent knowledge-graph memory agents can read and extend across sessions.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-memory'],
+    note: 'Reference server; runs locally via npx.',
+    iconDomain: 'modelcontextprotocol.io',
+  },
+  {
+    id: 'sequential-thinking',
+    label: 'Sequential thinking',
+    description:
+      'Structured step-by-step reasoning scratchpad for complex problems.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+    note: 'Reference server; runs locally via npx.',
+    iconDomain: 'modelcontextprotocol.io',
+  },
+  {
+    id: 'time',
+    label: 'Time & timezones',
+    description: 'Current time and timezone conversion.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'uvx',
+    args: ['mcp-server-time'],
+    note: 'Python reference server — needs uv (one-time install).',
+    iconDomain: 'modelcontextprotocol.io',
+  },
+  {
+    id: 'tavily',
+    label: 'Tavily search',
+    description:
+      'Web search, extract, and crawl tuned for LLM answers with citations.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', 'tavily-mcp'],
+    auth: 'apiKey',
+    apiKeyEnvVar: 'TAVILY_API_KEY',
+    requiresToken: true,
+    note: 'Runs via npx (Node). Needs a Tavily API key (asked for after adding).',
+    iconDomain: 'tavily.com',
+  },
+  {
+    id: 'brave-search',
+    label: 'Brave Search',
+    description: 'Independent web and local search index.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-brave-search'],
+    auth: 'apiKey',
+    apiKeyEnvVar: 'BRAVE_API_KEY',
+    requiresToken: true,
+    note: 'Runs via npx (Node). Needs a Brave Search API key (asked for after adding).',
+    iconDomain: 'search.brave.com',
+  },
+  {
+    id: 'firecrawl',
+    label: 'Firecrawl',
+    description:
+      'Scrape, crawl, and structure whole websites into clean markdown or JSON.',
+    category: 'knowledge',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', 'firecrawl-mcp'],
+    auth: 'apiKey',
+    apiKeyEnvVar: 'FIRECRAWL_API_KEY',
+    requiresToken: true,
+    note: 'Runs via npx (Node). Needs a Firecrawl API key (asked for after adding).',
+    iconDomain: 'firecrawl.dev',
+  },
+
+  // ---- Documentation --------------------------------------------------------
+  {
+    id: 'context7',
+    label: 'Context7 docs',
+    description:
+      'Version-accurate library and framework documentation for grounded answers.',
+    category: 'documentation',
+    transport: 'http',
+    url: 'https://mcp.context7.com/mcp',
+    note: 'Remote server; anonymous tier is rate-limited.',
+  },
+  {
+    id: 'deepwiki',
+    label: 'DeepWiki',
+    description:
+      'Ask questions about public GitHub repositories via generated wikis.',
+    category: 'documentation',
+    transport: 'http',
+    url: 'https://mcp.deepwiki.com/mcp',
+    note: 'Remote server, key-free.',
+  },
+  {
+    id: 'microsoft-learn',
+    label: 'Microsoft Learn',
+    description:
+      'Search and read Microsoft/Azure documentation grounded to current pages.',
+    category: 'documentation',
+    transport: 'http',
+    url: 'https://learn.microsoft.com/api/mcp',
+    note: 'Remote server, key-free.',
+  },
+  {
+    id: 'cloudflare-docs',
+    label: 'Cloudflare Docs',
+    description:
+      'Search and read Cloudflare developer documentation, grounded to current pages.',
+    category: 'documentation',
+    transport: 'sse',
+    url: 'https://docs.mcp.cloudflare.com/sse',
+    note: 'Remote server, key-free.',
+    iconDomain: 'cloudflare.com',
+  },
+
+  // ---- Developer ------------------------------------------------------------
+  {
+    id: 'git',
+    label: 'Git (local repos)',
+    description:
+      'Inspect and search local git repositories: log, diff, blame, status.',
+    category: 'developer',
+    transport: 'stdio',
+    command: 'uvx',
+    args: ['mcp-server-git'],
+    note: 'Python reference server — needs uv (one-time install).',
+    iconDomain: 'git-scm.com',
+  },
+  {
+    id: 'github',
+    label: 'GitHub',
+    description:
+      'Repositories, issues, and pull requests through the official GitHub MCP.',
+    category: 'developer',
+    transport: 'http',
+    url: 'https://api.githubcopilot.com/mcp/',
+    auth: 'bearer',
+    requiresToken: true,
+    note: 'Needs a GitHub personal access token (asked for after adding).',
+    iconDomain: 'github.com',
+  },
+  {
+    id: 'playwright',
+    label: 'Playwright browser',
+    description:
+      'Drive a real browser: navigate, click, fill, and read pages for the agent.',
+    category: 'developer',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@playwright/mcp@latest'],
+    note: 'Runs via npx (Node); downloads a browser on first use.',
+    iconDomain: 'playwright.dev',
+  },
+  {
+    id: 'everything',
+    label: 'Everything (demo)',
+    description:
+      'Reference server exercising every MCP feature — handy for trying tools out.',
+    category: 'developer',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-everything'],
+    note: 'Reference server; runs locally via npx.',
+    iconDomain: 'modelcontextprotocol.io',
+  },
+  {
+    id: 'chart',
+    label: 'Charts (AntV)',
+    description:
+      'Generate 25+ chart types (line, bar, pie, maps, …) as images from data.',
+    category: 'developer',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@antv/mcp-server-chart'],
+    note: 'Runs via npx (Node).',
+    iconDomain: 'antv.antgroup.com',
+  },
+  {
+    id: 'stripe',
+    label: 'Stripe',
+    description:
+      'Query and manage Stripe: customers, payments, invoices, and products.',
+    category: 'developer',
+    transport: 'http',
+    url: 'https://mcp.stripe.com',
+    auth: 'bearer',
+    requiresToken: true,
+    note: 'Needs a Stripe restricted API key as the bearer token (asked for after adding).',
+    iconDomain: 'stripe.com',
+  },
+]
+
+export const MCP_SERVER_PRESET_CATEGORY_LABELS: Record<
+  McpServerPresetCategory,
+  string
+> = {
+  academic: 'Academic research',
+  knowledge: 'Knowledge work',
+  documentation: 'Documentation',
+  developer: 'Developer',
+}
+
+export function findMcpServerPreset(id: string): McpServerPreset | undefined {
+  return MCP_SERVER_PRESETS.find(preset => preset.id === id)
+}
+
+/**
+ * What a preset needs on the user's machine to run:
+ * - `remote`  — nothing (an HTTP/SSE endpoint the shell just calls);
+ * - `node`    — a system `npx` (Node.js), usually already present;
+ * - `python`  — `uvx` (uv), the least commonly installed.
+ *
+ * The Tools UI privileges lower-friction runtimes and clearly flags the ones
+ * that need an extra install, rather than requiring uv across the board.
+ */
+export type McpPresetRuntime = 'remote' | 'node' | 'python'
+
+const NODE_RUNNERS = new Set(['npx', 'node', 'bunx'])
+
+export function mcpPresetRuntime(
+  preset: Pick<McpServerPreset, 'transport' | 'command'>,
+): McpPresetRuntime {
+  if (preset.transport !== 'stdio') return 'remote'
+  return preset.command && NODE_RUNNERS.has(preset.command) ? 'node' : 'python'
+}
+
+/** Sort rank so no-install servers come first, then Node, then Python. */
+export const MCP_PRESET_RUNTIME_RANK: Record<McpPresetRuntime, number> = {
+  remote: 0,
+  node: 1,
+  python: 2,
+}

package/src/agents/runtime/index.ts

@@ -8,6 +8,13 @@ export {
 export { createIdleLiveTurn, reduceAgentLiveTurn } from './agentLiveReducer.js'
 export { unresolvedToolCalls } from './unresolvedToolCalls.js'
 export { derivePendingToolCalls } from './pendingToolCalls.js'
+export {
+  derivePendingAsks,
+  sessionPendingAskCalls,
+  type PendingAsk,
+  type PendingAskDelegation,
+  type PendingAskSession,
+} from './pendingAsks.js'
 export { toolRequiresApproval } from './toolRequiresApproval.js'
 export { mergeUsageTurn } from './mergeUsageTurn.js'
 export {

package/src/agents/runtime/mapAgentSnapshot.ts

@@ -8,7 +8,7 @@ import {
   type AgentUiToolCall,
 } from '../../components/agents/agentTypes.js'
 import { derivePendingToolCalls } from './pendingToolCalls.js'
-import { toolRequiresApproval } from './toolRequiresApproval.js'
+import { sessionPendingAskCalls } from './pendingAsks.js'
 
 const VISIBLE_ROLES = new Set(['user', 'assistant', 'tool'])
 
@@ -76,19 +76,22 @@ export function mapPendingToolCalls(
   )
 }
 
-/** Pending tools that still need explicit user approval. */
+/**
+ * Pending tools that still need explicit user approval — the shared
+ * pending-asks selector's per-session slice (docs/09 §Card states).
+ */
 export function mapApprovalPendingToolCalls(
   snapshot: PlatformAgentRunSnapshot | null,
   policy: PlatformAgentSessionToolPolicy | undefined,
   acceptedPendingToolCallIds: readonly string[] = [],
 ): AgentUiToolCall[] {
   if (!snapshot || !policy) return []
-  const accepted = new Set(acceptedPendingToolCallIds)
-  return derivePendingToolCalls(snapshot.messages, snapshot.state)
-    .filter(
-      call => !accepted.has(call.id) && toolRequiresApproval(call.name, policy),
-    )
-    .map(mapToolCall)
+  return sessionPendingAskCalls({
+    state: snapshot.state,
+    messages: snapshot.messages,
+    acceptedPendingToolCallIds,
+    toolPolicy: policy,
+  })
 }
 
 function mapToolCall(call: AgentUiToolCall): AgentUiToolCall {

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
+}