@xingular/harness 0.0.0-stage → 0.1.0

package/src/mcp/service.ts

@@ -0,0 +1,567 @@
+// Connected apps as sessions use them: which connections a session may reach, the two broker
+// tools every such session gets, approval of anything that is not a read, and a redacted record
+// of what each call returned.
+import { createHash, randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+
+import type { SecretStore } from '../accounts/secrets'
+import type { Bus } from '../core/bus'
+import type { HarnessEnv } from '../core/env'
+import { HarnessError, invalid, notFound } from '../core/errors'
+import { newId, now, readJson, writeJson } from '../core/fs'
+import { charCount, takeChars } from '../core/text'
+import type { CapabilitySet } from '../capabilities/types'
+import type { CallerContext } from '../memory/caller'
+import type { ToolPolicy } from '../sessions/policy'
+import type { ActiveRun, RunRegistry } from '../sessions/registry'
+import { findRun, runDir } from '../sessions/runStore'
+import type { SessionBroker } from '../sessions/sessions'
+import type { ToolSession, ToolSpec } from '../tools/types'
+import { allowed, Connections, setScope, webUrl } from './connections'
+import { isSignInRequired, McpManager, signInRequired } from './manager'
+import { signIn, type OAuthHost } from './oauth'
+import type { Connection, HttpConfig, LaunchConfig, McpSource, McpTrace } from './types'
+
+/** A session's access to the broker. A terminal session presents `token`; an SDK session holds the object. */
+export interface BrokerSession {
+  token: string
+  sessionId: string
+  runId: string | null
+  caller: CallerContext
+  /** Only reads are permitted. */
+  readOnly: boolean
+  depth: number
+  /** The run's immutable tool and connector set. */
+  capabilities?: CapabilitySet
+}
+
+export interface BrokerTool {
+  name: string
+  description?: string
+  inputSchema?: unknown
+}
+
+/** Tools the embedding application offers through the broker, beside connected apps. */
+export interface BrokeredTools {
+  list(session: BrokerSession): Promise<BrokerTool[]>
+  has(name: string): boolean
+  /** The tool's result as the application returns it: text, `{ text, image? }`, or structured data. */
+  call(session: BrokerSession, name: string, args: Record<string, unknown>): Promise<unknown>
+  /** Changes whenever the offered tools may have changed. */
+  revision?(session: BrokerSession): Promise<unknown>
+  /** A sentence added to the discovery tool's description, e.g. where the application lists the rest of its tools. */
+  discoveryNote?: string
+}
+
+interface ListedTool extends BrokerTool {
+  connectionId: string
+  tool: string
+  origin?: 'app'
+}
+
+const TOOL_SUMMARY_CHARS = 160
+
+/**
+ * A tool listing a model can scan: a name and one line each. Input schemas are the bulk of a
+ * discovery reply, so they come back for one named tool at a time.
+ */
+export function compactTools<T extends BrokerTool>(tools: readonly T[], tool?: string): Array<Omit<T, 'inputSchema'> | T> {
+  if (tool) return tools.filter((entry) => entry.name === tool)
+  return tools.map(({ inputSchema: _schema, ...entry }) => ({
+    ...entry,
+    ...(entry.description && entry.description.length > TOOL_SUMMARY_CHARS ? { description: `${entry.description.slice(0, TOOL_SUMMARY_CHARS).trimEnd()}…` } : {})
+  })) as Array<Omit<T, 'inputSchema'>>
+}
+
+/** Most tools one listing returns. A server with hundreds of tools would otherwise make every discovery call a very large input. */
+export const TOOL_PAGE = 40
+
+/**
+ * One page of a tool listing: names and summaries only, optionally filtered by a
+ * case-insensitive `query` over name and description. `more` and `nextOffset` appear when
+ * entries remain.
+ */
+export function pageTools<T extends BrokerTool>(tools: readonly T[], options: { query?: string; offset?: number; limit?: number } = {}) {
+  const query = options.query?.trim().toLowerCase()
+  const matching = query ? tools.filter((tool) => tool.name.toLowerCase().includes(query) || (tool.description ?? '').toLowerCase().includes(query)) : tools
+  const offset = Math.max(0, Math.floor(options.offset ?? 0))
+  const limit = Math.max(1, Math.min(Math.floor(options.limit ?? TOOL_PAGE), 100))
+  const page = compactTools(matching.slice(offset, offset + limit))
+  const next = offset + page.length
+  return { tools: page, total: matching.length, ...(next < matching.length ? { more: matching.length - next, nextOffset: next } : {}) }
+}
+
+const WORKSPACE_READS = new Set([
+  'x_workspace_status', 'x_workspace_context', 'x_workspace_search', 'x_workspace_note_list', 'x_workspace_note_read', 'x_workspace_project_list', 'x_workspace_project_get',
+  'x_workspace_task_list', 'x_workspace_task_get', 'x_workspace_milestone_list', 'x_workspace_milestone_get', 'x_workspace_update_list', 'x_workspace_update_get',
+  'x_workspace_meeting_list', 'x_workspace_meeting_get', 'x_workspace_resource_list', 'x_workspace_resource_get', 'x_workspace_resource_preview'
+])
+
+interface Proposal {
+  runId: string
+  sessionId: string
+  connectionId: string
+  data: unknown
+  expiresAt: string
+}
+
+interface AuthorizedCall {
+  session: BrokerSession
+  connection: Connection
+  runId: string
+}
+
+export interface ConnectedAppsOptions {
+  env: HarnessEnv
+  stateDir: string
+  secrets: SecretStore
+  bus: Bus
+  runs: RunRegistry
+  policy: ToolPolicy
+}
+
+/** The scope a plugin hook's connections are opened under: they belong to no session. */
+const UNATTENDED_SCOPE = 'plugin-hooks'
+
+export class ConnectedApps implements SessionBroker {
+  readonly toolNames = ['mcp_list_tools', 'mcp_call_tool'] as const
+  readonly connections: Connections
+  private readonly manager: McpManager
+  private readonly oauth: OAuthHost
+  private readonly grants = new Map<string, BrokerSession>()
+  private readonly proposals = new Map<string, Proposal>()
+  private readonly calls = new Map<string, AuthorizedCall>()
+  private brokered: BrokeredTools | null = null
+
+  constructor(private readonly options: ConnectedAppsOptions) {
+    this.connections = new Connections(options.stateDir, options.secrets, options.bus)
+    this.oauth = {
+      clientName: options.env.productName,
+      load: (id) => this.connections.oauthLoad(id),
+      save: (id, state) => this.connections.oauthSave(id, state),
+      openUrl: (url) => {
+        if (!webUrl(url)) throw invalid('The sign-in page must be an https:// address.')
+        // The application shows the page; the harness never opens a browser by itself.
+        options.bus.emit({ type: 'connections.openUrl', url })
+      }
+    }
+    this.manager = new McpManager(this.oauth)
+  }
+
+  /** Loads what is needed to redact results. Call once before sessions start. */
+  start(): Promise<void> {
+    return this.connections.refreshSecrets()
+  }
+
+  /** Lets the application offer its own tools through `mcp_list_tools` and `mcp_call_tool`. */
+  expose(tools: BrokeredTools): void {
+    this.brokered = tools
+  }
+
+  // ---- Grants -----------------------------------------------------------------------------
+
+  /** Gives a session access to the broker. The token is what a process outside the harness presents. */
+  grant(input: Omit<BrokerSession, 'token'>): BrokerSession {
+    const session: BrokerSession = { ...input, token: `${newId()}${newId()}` }
+    this.grants.set(session.token, session)
+    return session
+  }
+
+  session(token: string): BrokerSession {
+    const session = this.grants.get(token)
+    if (!session) throw new HarnessError('mcp_unauthorized', 'This MCP session is no longer authorized.')
+    return session
+  }
+
+  revokeSession(sessionId: string): void {
+    for (const [token, session] of this.grants) if (session.sessionId === sessionId) this.grants.delete(token)
+    for (const [key, proposal] of this.proposals) if (proposal.sessionId === sessionId) this.proposals.delete(key)
+  }
+
+  /** A run ended: its grants, previews, and open client sessions go with it. */
+  revokeRun(runId: string, sessionId: string): void {
+    for (const [token, session] of this.grants) if (session.runId === runId) this.grants.delete(token)
+    for (const [key, proposal] of this.proposals) if (proposal.runId === runId) this.proposals.delete(key)
+    void this.manager.close(undefined, sessionId)
+  }
+
+  private activeRun(session: BrokerSession): ActiveRun {
+    const run = (session.runId ? this.options.runs.active(session.runId) : null) ?? this.options.runs.activeForSession(session.sessionId)
+    if (!run) throw new HarnessError('run_not_active', 'The requesting run has ended.')
+    return run
+  }
+
+  private valid(session: BrokerSession): void {
+    if (this.grants.get(session.token) !== session) throw new HarnessError('mcp_unauthorized', 'This MCP session is no longer authorized.')
+  }
+
+  // ---- What a session may reach ---------------------------------------------------------------
+
+  private async reachable(session: BrokerSession): Promise<Connection[]> {
+    const scoped = this.connections.forScope({ agentId: session.caller.agentId, projectId: session.caller.projectId })
+    const frozen = session.capabilities ? scoped.filter((connection) => session.capabilities!.connectors.includes(connection.id)) : scoped
+    const policy = this.options.policy.connections
+    // Nothing to narrow: the application is not asked.
+    if (!policy || !frozen.length) return frozen
+    const ids = await policy({ sessionId: session.sessionId, runId: session.runId, caller: session.caller, connectionIds: frozen.map((connection) => connection.id) })
+    return frozen.filter((connection) => ids.includes(connection.id))
+  }
+
+  /** The application's tools and every reachable connection's tools, with the connections that could not be read. */
+  async list(session: BrokerSession): Promise<{ tools: ListedTool[]; errors: { connection: string; message: string }[] }> {
+    const own = (await this.brokered?.list(session)) ?? []
+    const discovered = await Promise.all(
+      (await this.reachable(session)).map(async (connection) => {
+        const tools: ListedTool[] = []
+        let config: LaunchConfig | null = null
+        try {
+          config = await this.connections.launch(connection)
+          const client = await this.manager.client(session.sessionId, config)
+          for (const tool of (await client.listTools({}, { timeout: 15000 })).tools) {
+            const alias = `mcp_${createHash('sha256').update(`${connection.id}:${tool.name}`).digest('hex').slice(0, 12)}_${tool.name.replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 40)}`
+            tools.push({ name: alias, description: `${connection.name}: ${tool.description ?? tool.name}`, inputSchema: tool.inputSchema, connectionId: connection.id, tool: tool.name })
+          }
+          if (client.getServerCapabilities()?.resources) {
+            for (const operation of ['list', 'read'] as const) {
+              tools.push({
+                name: `mcp_${connection.id.replace(/-/g, '').slice(0, 12)}_resources_${operation}`,
+                description: `${connection.name}: ${operation} MCP resources`,
+                inputSchema: { type: 'object', properties: operation === 'read' ? { uri: { type: 'string' } } : {}, ...(operation === 'read' ? { required: ['uri'] } : {}) },
+                connectionId: connection.id,
+                tool: `resources/${operation}`
+              })
+            }
+          }
+          return { tools, errors: [] }
+        } catch (error) {
+          const unauthorized = isSignInRequired(error)
+          const message = unauthorized ? signInRequired(connection).message : `${connection.name} could not load its tools. Check the connection in Settings → Connections.`
+          if (unauthorized) await this.manager.close(connection.id, session.sessionId)
+          this.connectionFailed(connection.id, unauthorized)
+          return { tools: [], errors: [{ connection: connection.name, message }] }
+        }
+      })
+    )
+    return {
+      tools: [...own.map((tool): ListedTool => ({ ...tool, origin: 'app', connectionId: '__app__', tool: tool.name })), ...discovered.flatMap((entry) => entry.tools)],
+      errors: discovered.flatMap((entry) => entry.errors)
+    }
+  }
+
+  private connectionFailed(connectionId: string, unauthorized: boolean): void {
+    try {
+      this.connections.update(connectionId, (item) => {
+        if (item.auth === 'oauth' && unauthorized) {
+          item.authState = 'expired'
+          item.error = `${item.name} needs you to sign in again.`
+        } else if (item.kind === 'remote') {
+          item.error = `${item.name} could not load its tools. Check its address and sign-in, then test or reconnect.`
+        } else {
+          item.error = `${item.name} could not load its tools. Check its executable and arguments, then test or reconnect.`
+        }
+      })
+      this.connections.changed()
+    } catch {
+      // The connection was removed while it was being read.
+    }
+  }
+
+  // ---- Calling ------------------------------------------------------------------------------
+
+  /** Runs one tool by the name `list` gave it. */
+  async invoke(session: BrokerSession, alias: string, args: Record<string, unknown>): Promise<unknown> {
+    if (this.brokered?.has(alias)) {
+      const result = await this.brokered.call(session, alias, args)
+      const output = result as { text?: string; image?: { data: string; mimeType: string } } | null
+      return {
+        content: [{ type: 'text', text: output?.text ?? (typeof result === 'string' ? result : JSON.stringify(result)) }, ...(output?.image ? [{ type: 'image', ...output.image }] : [])],
+        ...(!output?.image && result && typeof result === 'object' ? { structuredContent: Array.isArray(result) ? { result } : result } : {})
+      }
+    }
+    const tool = (await this.list(session)).tools.find((candidate) => candidate.name === alias)
+    if (!tool) throw new HarnessError('mcp_tool_unavailable', 'This MCP tool is unavailable or its connection was disabled.')
+    const toolCallId = randomUUID()
+    const config = await this.authorize(session, tool.connectionId, tool.tool, args, toolCallId)
+    try {
+      const client = await this.manager.client(session.sessionId, config)
+      const result = tool.tool === 'resources/list' ? await client.listResources() : tool.tool === 'resources/read' ? await client.readResource({ uri: String(args.uri) }) : await client.callTool({ name: tool.tool, arguments: args }, { timeout: 60000 })
+      this.completed(toolCallId, tool.tool, { result })
+      return result
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'MCP call failed'
+      this.completed(toolCallId, tool.tool, { error: tool.tool === 'x_workspace_mutation_apply' ? 'Workspace apply did not return a confirmed result. Do not retry automatically; read the affected record to verify its state.' : message })
+      throw error
+    }
+  }
+
+  /** Checks scope, asks for approval when the call is not a read, and returns how to reach the connection. */
+  private async authorize(session: BrokerSession, connectionId: string, tool: string, args: Record<string, unknown>, toolCallId: string): Promise<LaunchConfig> {
+    const run = this.activeRun(session)
+    const record = findRun(this.options.env.root, run.runId)
+    if (record) {
+      const scope = await this.options.policy.scope?.({ run: record, caller: session.caller, tool: 'connected_app', args })
+      if (scope && scope.automatic && !scope.allowed) throw new HarnessError('outside_work_scope', scope.reason ?? 'Outside the approved work scope.')
+    }
+    const denied = (): HarnessError => new HarnessError('mcp_access_denied', 'This connection is disabled or unavailable to this agent.')
+    const connection = (await this.reachable(session)).find((item) => item.id === connectionId)
+    if (!connection) throw denied()
+    const workspace = connection.kind === 'workspace'
+    const preview = workspace && tool === 'x_workspace_mutation_preview'
+    const apply = workspace && tool === 'x_workspace_mutation_apply'
+    const isRead = (workspace && WORKSPACE_READS.has(tool)) || (!apply && !preview && connection.readTools.includes(tool))
+    if (session.readOnly && !isRead) throw new HarnessError('mcp_read_only', 'This session only permits reads from connected apps.')
+    let proposal: unknown
+    if (apply) {
+      const approvalToken = typeof args.approvalToken === 'string' ? args.approvalToken : ''
+      const saved = this.proposals.get(approvalToken)
+      this.proposals.delete(approvalToken)
+      if (!saved) throw new HarnessError('mcp_preview_required', 'Create a fresh preview in this run before applying.')
+      if (saved.sessionId !== session.sessionId || saved.runId !== run.runId || saved.connectionId !== connectionId || saved.expiresAt <= now()) throw new HarnessError('mcp_preview_required', 'This preview belongs to another run or has expired.')
+      proposal = saved.data
+    }
+    run.emit('tool.started', { toolCallId, name: tool, summary: connection.name })
+    if (!isRead && !preview) {
+      const action = JSON.stringify(proposal ?? this.connections.scrub(args, connection.id), null, 2)
+      const decision = await run.requestApproval({ requestId: `mcp-${newId()}`, target: connection.name, action: `${tool}\n${action}`, standing: 'switch', timeoutMs: 300_000 })
+      if (decision !== 'approved') {
+        run.emit('tool.completed', { toolCallId, name: tool, ok: false })
+        throw new HarnessError('mcp_denied', 'The user denied the MCP operation or its approval expired.')
+      }
+    }
+    // Access may have been revoked, or the run ended, while the request was waiting.
+    const current = (await this.reachable(session)).find((item) => item.id === connectionId)
+    if (!current) throw new HarnessError('mcp_access_denied', 'Connection access was revoked while waiting.')
+    this.valid(session)
+    this.activeRun(session)
+    this.calls.set(toolCallId, { session, connection: current, runId: run.runId })
+    return this.connections.launch(current)
+  }
+
+  /** Records what an authorized call returned: a redacted trace with its sources, and the tool's outcome. */
+  private completed(toolCallId: string, tool: string, outcome: { result?: unknown; error?: string }): void {
+    const call = this.calls.get(toolCallId)
+    if (!call) return
+    this.calls.delete(toolCallId)
+    const { connection, session, runId } = call
+    const result = (outcome.result ?? null) as { structuredContent?: { data?: { approvalToken?: unknown; expiresAt?: unknown }; truncated?: unknown }; isError?: unknown } | null
+    const structured = result?.structuredContent
+    const live = this.grants.get(session.token) === session && this.options.runs.active(runId) !== null
+    if (tool === 'x_workspace_mutation_preview' && live && typeof structured?.data?.approvalToken === 'string') {
+      this.proposals.set(structured.data.approvalToken, { runId, sessionId: session.sessionId, connectionId: connection.id, data: this.connections.scrub(structured.data, connection.id), expiresAt: typeof structured.data.expiresAt === 'string' ? structured.data.expiresAt : '' })
+    }
+    const ok = outcome.error === undefined && result?.isError !== true
+    const cleaned = this.connections.scrub(result, connection.id) as { structuredContent?: { sources?: unknown } } | null
+    const raw = outcome.error === undefined ? JSON.stringify(cleaned) : String(this.connections.scrub(outcome.error, connection.id))
+    const found = cleaned?.structuredContent?.sources
+    const sources: McpSource[] = (Array.isArray(found) ? found : [])
+      .flatMap((source: Record<string, unknown> | null) => {
+        if (!source || typeof source.id !== 'string' || typeof source.title !== 'string' || typeof source.uri !== 'string') return []
+        const value: McpSource = { id: source.id, title: source.title, uri: source.uri, path: typeof source.path === 'string' ? source.path : null }
+        for (const field of ['revision', 'excerpt', 'projectId'] as const) if (typeof source[field] === 'string') value[field] = takeChars(source[field] as string, 2000)
+        return [value]
+      })
+      .slice(0, 100)
+    const trace: McpTrace = { id: toolCallId, connectionId: connection.id, connectionName: connection.name, tool, at: now(), ok, summary: tool, result: takeChars(raw, 24000), sources, truncated: charCount(raw) > 24000 || structured?.truncated === true }
+    try {
+      const file = join(runDir(this.options.env.root, runId), 'mcp-context.json')
+      writeJson(file, [...(readJson<McpTrace[]>(file) ?? []), trace])
+    } catch {
+      // The call happened; a trace that cannot be written does not undo it.
+    }
+    this.options.runs.active(runId)?.emit('tool.completed', { toolCallId, name: tool, ok })
+  }
+
+  /** What a run retrieved from connected apps, in order. */
+  runContext(runId: string): McpTrace[] {
+    return readJson<McpTrace[]>(join(runDir(this.options.env.root, runId), 'mcp-context.json')) ?? []
+  }
+
+  /** Changes whenever what a session can discover may have changed. */
+  async revision(session: BrokerSession): Promise<unknown> {
+    return { connections: this.connections.revision(), tools: (await this.brokered?.revision?.(session)) ?? null }
+  }
+
+  // ---- The two tools a session gets -------------------------------------------------------------
+
+  tools(session: ToolSession, options: { readOnly: boolean }): ToolSpec[] {
+    const granted = this.grant({ sessionId: session.run.sessionId, runId: session.run.runId, caller: session.caller, readOnly: options.readOnly, depth: session.depth, capabilities: session.capabilities })
+    return this.brokerTools(granted)
+  }
+
+  /** `mcp_list_tools` and `mcp_call_tool` bound to a granted session. */
+  brokerTools(session: BrokerSession): ToolSpec[] {
+    return [
+      {
+        name: 'mcp_list_tools',
+        label: 'App and connected tools',
+        description: `Discover enabled ${this.options.env.productName} app operations and connected-app tools by name. Pass tool to get one tool with its input schema.${this.brokered?.discoveryNote ? ` ${this.brokered.discoveryNote}` : ''}`,
+        parameters: (Type) =>
+          Type.Object({
+            tool: Type.Optional(Type.String({ description: 'One tool name, to get its input schema.' })),
+            query: Type.Optional(Type.String({ description: 'Only tools whose name or description contains this text.' })),
+            offset: Type.Optional(Type.Integer({ minimum: 0, description: 'Where to continue a long list (nextOffset from the previous page).' }))
+          }),
+        execute: async (input) => {
+          const listed = await this.list(session)
+          const wanted = typeof input.tool === 'string' && input.tool ? input.tool : undefined
+          if (wanted) return JSON.stringify({ ...listed, tools: compactTools(listed.tools, wanted) })
+          const page = pageTools(listed.tools, { query: typeof input.query === 'string' ? input.query : undefined, offset: typeof input.offset === 'number' ? input.offset : undefined })
+          return JSON.stringify({ ...listed, ...page, note: `Names and summaries only. Call mcp_list_tools with tool for the input schema before the first call to that tool.${page.more ? ' More tools match: pass offset, and query to narrow the list.' : ''}` })
+        }
+      },
+      {
+        name: 'mcp_call_tool',
+        label: 'Use connected app',
+        description: 'Invoke an enabled app or connected-app tool returned by mcp_list_tools. Current settings are checked on every call. Changes require approval.',
+        parameters: (Type) => Type.Object({ name: Type.String(), arguments: Type.Record(Type.String(), Type.Unknown()) }),
+        execute: async (input) => JSON.stringify(await this.invoke(session, String(input.name), (input.arguments ?? {}) as Record<string, unknown>))
+      }
+    ]
+  }
+
+  // ---- What a person does on the Connections screen ---------------------------------------------
+
+  async save(input: Parameters<Connections['save']>[0]): Promise<Connection> {
+    const connection = await this.connections.save(input)
+    this.cancelConnection(connection.id)
+    return connection
+  }
+
+  async remove(connectionId: string): Promise<void> {
+    await this.connections.remove(connectionId)
+    this.cancelConnection(connectionId)
+  }
+
+  private cancelConnection(connectionId: string): void {
+    for (const [key, proposal] of this.proposals) if (proposal.connectionId === connectionId) this.proposals.delete(key)
+    void this.manager.close(connectionId)
+  }
+
+  /** Connects once and records what the server offers, or why it could not be reached. */
+  async test(connectionId: string): Promise<Connection> {
+    const connection = this.connections.find(connectionId)
+    let probed: Awaited<ReturnType<McpManager['probe']>> | null = null
+    let failure: unknown = null
+    try {
+      probed = await this.manager.probe(await this.connections.launch(connection))
+    } catch (error) {
+      failure = error
+    }
+    if (JSON.stringify(this.connections.find(connectionId)) !== JSON.stringify(connection)) throw new HarnessError('mcp_config_changed', 'Connection changed during its test. Test the saved connection again.')
+    const updated = this.connections.update(connectionId, (item) => {
+      item.checkedAt = now()
+      if (probed) {
+        item.serverName = probed.serverName
+        item.tools = probed.tools
+        item.error = null
+        if (item.kind === 'workspace' && !item.expectedVaultId) item.expectedVaultId = probed.vaultId
+      } else {
+        if (isSignInRequired(failure) && item.auth === 'oauth' && item.authState === 'signed_in') item.authState = 'expired'
+        item.error = failure instanceof Error ? failure.message : String(failure)
+        item.tools = []
+      }
+    })
+    this.connections.changed()
+    return updated
+  }
+
+  /** Signs in with the provider in a browser. Only a person starts this; a session that finds an expired sign-in reports it. */
+  async signIn(connectionId: string): Promise<Connection> {
+    const connection = this.connections.find(connectionId)
+    if (connection.kind !== 'remote' || connection.auth !== 'oauth') throw invalid('This connection does not use browser sign-in.')
+    if (connection.oauthClient === 'user' && !(await this.connections.hasOauthClient(connection.id))) throw invalid('Add your OAuth client ID before signing in.')
+    await signIn(this.oauth, (await this.connections.launch(connection)) as HttpConfig)
+    const updated = this.connections.update(connectionId, (item) => Object.assign(item, { authState: 'signed_in', error: null }))
+    await this.manager.close(connectionId)
+    this.connections.changed()
+    return updated
+  }
+
+  async signOut(connectionId: string): Promise<Connection> {
+    const updated = await this.connections.signOut(connectionId)
+    this.cancelConnection(connectionId)
+    return updated
+  }
+
+  /** Reads one retrieved source again from the Xingular Workspace connection it came from. */
+  async refreshSource(runId: string, traceId: string, sourceUri: string): Promise<unknown> {
+    const trace = this.runContext(runId).find((entry) => entry.id === traceId)
+    if (!trace) throw notFound('Retrieved context')
+    const source = trace.sources.find((entry) => entry.uri === sourceUri)
+    if (!source) throw notFound('Source')
+    const connection = this.connections.list().find((item) => item.enabled && item.kind === 'workspace' && item.id === trace.connectionId)
+    if (!connection) throw new HarnessError('mcp_access_denied', 'Enable the original Xingular Workspace connection to refresh this source.')
+    const kind = sourceUri.split('/')[3] ?? ''
+    const [tool, args]: [string, Record<string, unknown>] = kind.startsWith('note')
+      ? ['x_workspace_note_read', { path: source.path ?? source.id }]
+      : kind.startsWith('task')
+        ? ['x_workspace_task_get', { id: source.id }]
+        : kind.startsWith('project')
+          ? ['x_workspace_project_get', { id: source.id }]
+          : kind.startsWith('resource')
+            ? ['x_workspace_resource_get', { id: source.id }]
+            : ['x_workspace_context', { query: source.title || source.id }]
+    return this.connections.scrub(await this.manager.readSource(await this.connections.launch(connection), tool, args), connection.id)
+  }
+
+  /** Gives one agent exactly these connections, if its creator may reach each of them. */
+  setAgentScope(creator: { agentId?: string | null; projectId?: string | null }, agentId: string, ids: readonly string[]): Connection[] {
+    this.connections.updateAll((all) => {
+      for (const id of ids) {
+        const connection = all.find((item) => item.id === id)
+        if (!connection) throw notFound('Connection')
+        if (!allowed(connection, creator)) throw new HarnessError('required_connections_unavailable', `${connection.name} is disabled or outside your connection scope.`)
+      }
+      for (const connection of all) {
+        connection.agentIds = connection.agentIds.filter((id) => id !== agentId)
+        connection.excludedAgentIds = connection.excludedAgentIds.filter((id) => id !== agentId)
+        if (ids.includes(connection.id)) {
+          if (!connection.global) connection.agentIds.push(agentId)
+        } else if (connection.global) {
+          connection.excludedAgentIds.push(agentId)
+        }
+      }
+    })
+    return this.connections.forScope({ agentId })
+  }
+
+  /**
+   * A call with no session and nobody to ask, made by a plugin's hook. It reaches a connection
+   * only when it is on for everyone, and a tool only when a person marked it to run without asking.
+   */
+  async callUnattended(reference: string, tool: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    const connection = this.connections.list().find((item) => item.id === reference || item.name === reference)
+    if (!connection || !allowed(connection, {})) throw new HarnessError('mcp_access_denied', `There is no connected app called "${reference}" that is on for everyone.`)
+    // A change to the first-party workspace is previewed and approved by a person, never run from a hook.
+    if (!connection.readTools.includes(tool) || tool.startsWith('x_workspace_mutation')) {
+      throw new HarnessError('mcp_denied', `${connection.name} asks before running "${tool}". Mark it to run without asking in the connection's settings to let a plugin use it.`)
+    }
+    const client = await this.manager.client(UNATTENDED_SCOPE, await this.connections.launch(connection))
+    return client.callTool({ name: tool, arguments: args }, { timeout: 60000 })
+  }
+
+  /** Switches one saved connection on or off for everyone, one agent, or one project. */
+  attach(connectionId: string, scope: { agentId?: string | null; projectId?: string | null }, on: boolean): void {
+    this.connections.updateAll((all) => {
+      const connection = all.find((item) => item.id === connectionId)
+      if (!connection) throw notFound('Connection')
+      if (!connection.enabled) throw invalid(`${connection.name} is switched off. Switch it on in its own settings first.`)
+      setScope(connection, scope, on)
+    })
+  }
+
+  /** Forgets an agent that no longer exists. */
+  removeAgentScope(agentId: string): void {
+    this.connections.updateAll((all) => {
+      for (const connection of all) {
+        connection.agentIds = connection.agentIds.filter((id) => id !== agentId)
+        connection.excludedAgentIds = connection.excludedAgentIds.filter((id) => id !== agentId)
+      }
+    })
+  }
+
+  async close(): Promise<void> {
+    await this.manager.close(undefined, UNATTENDED_SCOPE).catch(() => undefined)
+    await this.manager.close()
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,105 @@
+// Connected apps: MCP servers the user added. A connection is device-local; its secrets
+// (environment values, request headers, OAuth tokens and client) are in the secret store,
+// never in `connections.json`.
+import { z } from 'zod'
+
+/** Loopback address every OAuth sign-in returns to. Pre-registered clients must list it exactly. */
+export const MCP_OAUTH_PORT = 47823
+export const MCP_OAUTH_REDIRECT_URL = `http://127.0.0.1:${MCP_OAUTH_PORT}/oauth/callback`
+
+export const connectionSchema = z.object({
+  id: z.string().default(''),
+  name: z.string().default(''),
+  /** `workspace` (the first-party Xingular Workspace server), `local` (a command), or `remote` (Streamable HTTP). */
+  kind: z.string().default(''),
+  command: z.string().default(''),
+  args: z.array(z.string()).default([]),
+  cwd: z.string().nullable().default(null),
+  envKeys: z.array(z.string()).default([]),
+  enabled: z.boolean().default(false),
+  /** Available to every agent and project, except those excluded. */
+  global: z.boolean().default(false),
+  agentIds: z.array(z.string()).default([]),
+  projectIds: z.array(z.string()).default([]),
+  excludedAgentIds: z.array(z.string()).default([]),
+  excludedProjectIds: z.array(z.string()).default([]),
+  /** Tools that run without asking. */
+  readTools: z.array(z.string()).default([]),
+  expectedVaultId: z.string().nullable().default(null),
+  checkedAt: z.string().nullable().default(null),
+  serverName: z.string().nullable().default(null),
+  tools: z.array(z.unknown()).default([]),
+  error: z.string().nullable().default(null),
+  url: z.string().nullable().default(null),
+  /** `none`, `headers`, or `oauth`. */
+  auth: z.string().default(''),
+  headerKeys: z.array(z.string()).default([]),
+  oauthClient: z.string().nullable().default(null),
+  oauthScopes: z.array(z.string()).default([]),
+  authState: z.string().nullable().default(null),
+  catalogId: z.string().nullable().default(null)
+})
+export type Connection = z.infer<typeof connectionSchema>
+
+export const connectionInputSchema = connectionSchema.extend({
+  env: z.record(z.string(), z.string()).nullish(),
+  removeEnv: z.array(z.string()).nullish(),
+  headers: z.record(z.string(), z.string()).nullish(),
+  removeHeaders: z.array(z.string()).nullish(),
+  /** A client registered by the user with the provider; replaces any saved sign-in. */
+  oauthCredentials: z.object({ clientId: z.string(), clientSecret: z.string() }).nullish()
+})
+export type ConnectionInput = z.input<typeof connectionInputSchema>
+
+export interface StdioConfig {
+  id: string
+  name: string
+  transport: 'stdio'
+  command: string
+  args: string[]
+  cwd: string | null
+  env: Record<string, string>
+}
+
+export interface HttpConfig {
+  id: string
+  name: string
+  transport: 'http'
+  url: string
+  headers: Record<string, string>
+  auth: 'none' | 'headers' | 'oauth'
+  scopes: string[]
+}
+
+/** What it takes to reach a server: a process to start, or an address and its credentials. */
+export type LaunchConfig = StdioConfig | HttpConfig
+
+/** Who a session is, for deciding which connections it may reach. */
+export interface Scope {
+  agentId?: string | null
+  projectId?: string | null
+}
+
+export interface McpSource {
+  id: string
+  title: string
+  uri: string
+  path?: string | null
+  revision?: string
+  excerpt?: string
+  projectId?: string
+}
+
+/** One connected-app call a run made, kept in `runs/<id>/mcp-context.json`. */
+export interface McpTrace {
+  id: string
+  connectionId: string
+  connectionName: string
+  tool: string
+  at: string
+  ok: boolean
+  summary: string
+  result: string
+  sources: McpSource[]
+  truncated: boolean
+}