Skip to content

A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.

41.2 KB
Raw Blame
// Connectors: outside services every Bot can use. One engine mounts each
// connected service's MCP server on the plugin context through the local
// gateway (gateway.js), so every Bot gets mcp__<id>__* tools while credentials
// stay DS Bot secrets that never reach the mcp-client config. OAuth sign-in is
// in oauth.js, the service list in catalog.js, mail in mail/.
import { randomBytes, randomUUID } from 'node:crypto'
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
import { homedir, platform } from 'node:os'
import { join } from 'node:path'
import { defineTool } from '@deepseek-ai/dsh-tools'
import { CATALOG, entryOf, customId, tokenSecretOf, refreshSecretOf, clientSecretOf, keySecretOf, envSecretOf } from './catalog.js'
import * as oauth from './oauth.js'
import { createGateway } from './gateway.js'
import { install as installMail } from './mail/index.js'
import { CONNECTOR_IDS } from '../capabilities.js'
import { output } from '../tools.js'

export const GITHUB = 'github'
export const GITHUB_SECRET = 'GITHUB_TOKEN'
const MCP_CLIENT = '@deepseek-ai/dsh-mcp-client'
const CHECK_TIMEOUT_MS = 15_000
const SIGN_IN_TIMEOUT_MS = 10 * 60_000
const SECRET_REF = /\$DSH_SECRET_([A-Z][A-Z0-9_]*)/g
const MAX_REQUESTS = 20

// Asks GitHub who the token belongs to. Any token GitHub accepts passes.
export async function signIn(token, { api = 'https://api.github.com', fetch: request = fetch } = {}) {
  let response
  try {
    response = await request(`${api.replace(/\/$/, '')}/user`, {
      headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'User-Agent': 'ds-bot', 'X-GitHub-Api-Version': '2022-11-28' },
      signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
    })
  } catch {
    throw new Error('Could not reach GitHub')
  }
  if (response.status === 401) throw new Error('GitHub did not accept this token')
  if (!response.ok) throw new Error(`GitHub answered ${response.status}`)
  const user = await response.json().catch(() => ({}))
  if (typeof user?.login !== 'string') throw new Error('GitHub did not say who this token belongs to')
  return { login: user.login }
}

export function install(rt) {
  const { ctx, state } = rt
  for (const entry of CATALOG) CONNECTOR_IDS.add(entry.id)
  const options = rt.config.github === false ? null : { api: 'https://api.github.com', ...rt.config.github }
  const insecure = (url) => !/^https:\/\//i.test(String(url))
  let stopped = false
  let queue = Promise.resolve()
  const mounts = new Map()
  const statuses = new Map()
  const pendings = new Map()
  const refreshes = new Map()
  const gateways = { gw: null }
  const pluginP = { p: null }

  const entries = () => {
    const list = [...CATALOG.filter(entry => entry.id !== 'github' || options !== null)]
    for (const [id, saved] of Object.entries(state.connectors ?? {})) {
      if (saved?.custom) list.push({ id, name: saved.custom.name, category: 'custom', about: saved.custom.url ?? saved.custom.command ?? '', auth: { kind: 'custom' }, custom: saved.custom })
    }
    return list
  }
  const entryFor = (id) => {
    const catalog = entryOf(id)
    // rt.config.github keeps its url/api overrides from the old single connector.
    if (catalog !== undefined && id === 'github' && options?.url !== undefined) {
      return { ...catalog, remote: { url: options.url } }
    }
    if (catalog !== undefined) return catalog
    const custom = state.connectors?.[id]?.custom
    if (custom !== undefined) return { id, name: custom.name, category: 'custom', about: custom.url ?? custom.command ?? '', auth: { kind: 'custom' }, custom }
    return undefined
  }
  const known = (id) => {
    const entry = entryFor(String(id ?? ''))
    if (entry === undefined || entry.id === 'github' && options === null) throw new Error('No such connector')
    return entry
  }
  const reason = (error) => rt.redactSecrets([error, error?.cause].filter(Boolean).map(part => String(part?.message ?? part)).join(': ') || 'error').slice(0, 300)

  // --- credentials ------------------------------------------------------

  const credentialOf = (id) => {
    const entry = entryFor(id)
    if (entry === undefined) return undefined
    if (entry.auth.kind === 'none' || entry.auth.kind === 'custom') return {}
    if (entry.auth.kind === 'oauth') {
      const token = rt.secretValue(tokenSecretOf(id))
      return token === undefined ? undefined : { Authorization: `Bearer ${token}` }
    }
    if (entry.auth.kind === 'key') {
      const key = rt.secretValue(keySecretOf(id))
      return key === undefined ? undefined : { key }
    }
    return {}
  }
  const hasCredential = (id) => {
    const entry = entryFor(id)
    if (entry === undefined) return false
    if (entry.custom !== undefined) return true
    if (entry.auth.kind === 'none') return state.connectors?.[id] !== undefined
    return credentialOf(id) !== undefined
  }

  // What the gateway sends upstream for a connector.
  const upstreamOf = (id) => {
    const entry = entryFor(id)
    if (entry === undefined || !hasCredential(id)) return undefined
    let url = entry.custom?.url ?? entry.remote?.url
    if (url === undefined) return undefined
    const headers = { ...(entry.headers ?? {}) }
    const cred = credentialOf(id)
    if (entry.auth.kind === 'oauth' && cred !== undefined) Object.assign(headers, cred)
    if (entry.auth.kind === 'key' && cred !== undefined) {
      if (entry.auth.header) headers[entry.auth.header] = `${entry.auth.prefix ?? ''}${cred.key}`
      else if (entry.auth.query) {
        const parsed = new URL(url)
        parsed.searchParams.set(entry.auth.query, cred.key)
        url = String(parsed)
      }
    }
    if (entry.custom !== undefined) {
      for (const [name, raw] of Object.entries(entry.custom.headers ?? {})) {
        headers[name] = String(raw).replace(SECRET_REF, (_m, n) => rt.secretValue(n) ?? '')
      }
    }
    return { url, headers }
  }

  const gateway = async () => {
    gateways.gw ??= createGateway({
      credential: upstreamOf,
      readOnly: id => state.connectors?.[id]?.readOnly === true,
      onUnauthorized: id => refreshConnector(id),
      log: (...args) => rt.warn(...args),
    })
    await gateways.gw.listen()
    return gateways.gw
  }

  const loadMcpPlugin = async () => {
    pluginP.p ??= (async () => {
      const loader = ctx.get?.('loader')
      if (typeof loader?.import !== 'function') throw new Error('This DSH cannot load connectors')
      const mod = await loader.import(MCP_CLIENT)
      return loader.unwrapExports?.(mod) ?? mod?.default ?? mod
    })()
    return pluginP.p
  }

  const resolveRefs = (value) => String(value).replace(SECRET_REF, (_m, name) => rt.secretValue(name) ?? '')

  async function configFor(id) {
    const entry = entryFor(id)
    if (entry?.custom !== undefined && entry.custom.command !== undefined) {
      const env = {}
      for (const [key, raw] of Object.entries(entry.custom.env ?? {})) env[key] = resolveRefs(raw)
      return { transport: 'stdio', serverName: id, command: entry.custom.command, args: entry.custom.args ?? [], env }
    }
    const gw = await gateway()
    return { transport: 'streamable-http', serverName: id, url: gw.urlFor(id), headers: gw.headers() }
  }

  // A mount fingerprint covers the config a change must re-mount for; access and
  // refresh tokens live in the gateway, so changing one never re-mounts.
  async function fingerprint(id) {
    const config = await configFor(id)
    return JSON.stringify(config)
  }

  const unmount = async (id) => {
    const mount = mounts.get(id)
    mounts.delete(id)
    if (mount?.fiber !== undefined) await Promise.resolve().then(() => mount.fiber.dispose()).catch(() => {})
  }

  async function mountOne(id) {
    const fp = await fingerprint(id)
    if (mounts.get(id)?.fp === fp) return
    await unmount(id)
    statuses.set(id, { state: 'connecting' })
    try {
      const plugin = await loadMcpPlugin()
      if (stopped) return
      const config = { ...(await configFor(id)), failOnStartupError: true }
      const fiber = ctx.plugin(plugin, config)
      const mount = { fp, fiber }
      mounts.set(id, mount)
      await fiber.await()
      if (stopped || mounts.get(id) !== mount) return
      statuses.delete(id)
      settleRequests(id)
    } catch (error) {
      await unmount(id)
      mounts.set(id, { fp })
      statuses.set(id, { state: 'error', error: reason(error) })
      rt.warn('ds-bot: connector %s failed: %s', id, statuses.get(id).error)
    }
  }

  async function reconcile() {
    for (const id of mounts.keys()) {
      if (!hasCredential(id)) await unmount(id)
    }
    for (const entry of entries()) {
      if (entry.id === 'mail' || !hasCredential(entry.id)) continue
      await mountOne(entry.id)
    }
  }
  const sync = (force = false) => {
    queue = queue.then(async () => {
      if (force) { for (const id of mounts.keys()) await unmount(id) }
      await reconcile()
    }).catch(error => rt.warn('ds-bot: connectors: %s', reason(error)))
    return queue
  }

  // --- secrets ----------------------------------------------------------

  const keptSecret = async (name) => { await rt.loadSecrets(); return rt.secretValue(name) !== undefined }
  const writeSecret = async (name, value, purpose) => {
    const kept = await keptSecret(name)
    await rt.secretEndpoint('secret-set', { name, value, purpose, ...(kept ? {} : { scope: [] }) })
  }
  const dropSecrets = async (id) => {
    await rt.loadSecrets()
    for (const name of [tokenSecretOf(id), refreshSecretOf(id), clientSecretOf(id), keySecretOf(id)]) {
      if (id !== 'github' || name === GITHUB_SECRET || name !== tokenSecretOf(id)) {
        if (rt.secretValue(name) !== undefined) await rt.secretEndpoint('secret-delete', { name }).catch(() => {})
      }
    }
  }
  const saveState = async (id, patch) => {
    state.connectors = { ...(state.connectors ?? {}), [id]: { ...state.connectors?.[id], ...patch } }
    await rt.save()
  }

  // --- OAuth sign-in ----------------------------------------------------

  const finishTokens = async (id, entry, tokens) => {
    await writeSecret(tokenSecretOf(id), tokens.access_token, `${entry.name} connector`)
    if (typeof tokens.refresh_token === 'string' && tokens.refresh_token !== '') {
      await writeSecret(refreshSecretOf(id), tokens.refresh_token, `${entry.name} connector`).catch(() => {})
    }
    const account = await readAccount(id, entry, tokens.access_token).catch(() => undefined)
    await saveState(id, { account, connectedAt: Date.now(), tokenExpiresAt: Number.isFinite(tokens.expires_in) ? Date.now() + tokens.expires_in * 1000 : undefined })
  }

  async function readAccount(id, entry, token) {
    if (entry.whoami === undefined) return undefined
    if (id === 'github') return (await signIn(token, { api: options.api })).login
    const response = await fetch(entry.whoami.url, { headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) })
    if (!response.ok) return undefined
    const body = await response.json().catch(() => ({}))
    return typeof body?.[entry.whoami.field] === 'string' ? body[entry.whoami.field] : undefined
  }

  async function endPending(id, status) {
    const pending = pendings.get(id)
    pendings.delete(id)
    if (pending?.timer !== undefined) clearTimeout(pending.timer)
    if (pending?.listener !== undefined) await new Promise(resolve => pending.listener.close(resolve)).catch(() => {})
    if (status !== undefined) statuses.set(id, status)
    else statuses.delete(id)
  }

  // The loopback server for the browser flow: fixed port first, else a random one.
  async function loopback(ready) {
    const listener = createServer((req, res) => {
      req.on('error', () => res.destroy())
      res.on('error', () => req.destroy())
      let url
      try { url = new URL(req.url ?? '/', 'http://127.0.0.1') } catch { res.writeHead(400); res.end(); return }
      if (url.pathname !== '/callback') { res.writeHead(404); res.end(); return }
      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
      res.end('<!doctype html><title>Signed in</title><p style="font-family:sans-serif;margin:3em;text-align:center">Signed in — you can close this tab and go back to DS Bot.</p>')
      void ready({ code: url.searchParams.get('code'), state: url.searchParams.get('state'), iss: url.searchParams.get('iss'), error: url.searchParams.get('error'), errorDescription: url.searchParams.get('error_description') }).catch(error => rt.warn('ds-bot: connector sign-in callback failed: %s', reason(error)))
    })
    listener.on('error', error => {
      if (listener.listening) rt.warn('ds-bot: connector sign-in listener failed: %s', error?.code ?? 'error')
    })
    const listen = port => new Promise((resolve, reject) => {
      const onError = error => { listener.off('listening', onOk); reject(error) }
      const onOk = () => { listener.off('error', onError); resolve() }
      listener.once('error', onError)
      listener.once('listening', onOk)
      listener.listen(port, '127.0.0.1')
    })
    try {
      await listen(oauth.FIXED_CALLBACK_PORT)
      return { listener, fixed: true, redirectUri: `http://127.0.0.1:${oauth.FIXED_CALLBACK_PORT}/callback` }
    } catch {
      await listen(0)
      const port = listener.address().port
      return { listener, fixed: false, redirectUri: `http://127.0.0.1:${port}/callback` }
    }
  }

  async function startBrowserFlow(id, entry, pending) {
    const { listener, fixed, redirectUri } = await loopback(({ code, state, iss, error, errorDescription }) => completeBrowser(id, { code, state, iss, error, errorDescription }))
    const saved = state.connectors?.[id]
    const persist = async (client) => {
      const { clientSecret, ...rest } = client
      if (clientSecret !== undefined) await writeSecret(clientSecretOf(id), clientSecret, `${entry.name} connector`)
      await saveState(id, { client: rest })
    }
    const resolved = await oauth.resolveClient(entry, pending.discovery, redirectUri, fixed, saved?.client ? { ...saved.client, clientSecret: rt.secretValue(clientSecretOf(id)) } : undefined, { persist })
    if (resolved === null) {
      pendings.set(id, { ...pending, listener, redirectUri })
      statuses.set(id, { state: 'needs-client' })
      return
    }
    // Refresh needs to know which client signed in; DCR already persisted its result.
    if (resolved.via !== 'dcr') await saveState(id, { client: { via: resolved.via, clientId: resolved.clientInformation.client_id } })
    const stateParam = randomBytes(16).toString('base64url')
    const { url, codeVerifier } = await oauth.beginBrowser(pending.discovery, resolved.clientInformation, redirectUri, { state: stateParam })
    pendings.set(id, {
      ...pending, kind: 'browser', listener, redirectUri, codeVerifier, expectedState: stateParam,
      clientInformation: resolved.clientInformation,
      row: { kind: 'browser', url },
      timer: setTimeout(() => void expire(id), SIGN_IN_TIMEOUT_MS),
    })
    statuses.set(id, { state: 'connecting' })
  }

  async function expire(id) {
    await endPending(id, { state: 'off', error: 'Sign-in timed out' })
  }

  async function completeBrowser(id, result) {
    const pending = pendings.get(id)
    if (pending === undefined || pending.kind !== 'browser') return
    try {
      if (result.error !== null && result.error !== undefined) throw new Error(result.errorDescription ?? result.error)
      if (result.state !== pending.expectedState) throw new Error('The sign-in answer did not match this attempt (state mismatch). Try again.')
      const entry = entryFor(id)
      const tokens = await oauth.exchange(pending.discovery, pending.clientInformation, { code: result.code, codeVerifier: pending.codeVerifier, redirectUri: pending.redirectUri, iss: result.iss ?? undefined })
      await endPending(id)
      await finishTokens(id, entry, tokens)
      await sync(true)
    } catch (error) {
      await endPending(id, { state: 'error', error: reason(error) })
    }
  }

  async function startDeviceFlow(id, entry, pending) {
    const clientId = entry.auth.client.id
    const device = await oauth.deviceBegin(clientId, (entry.auth.scopes ?? []).join(' '), { endpoints: rt.config.github?.endpoints })
    const poll = async () => {
      const current = pendings.get(id)
      if (current === undefined || current.kind !== 'device' || stopped) return
      if (Date.now() >= current.device.expiresAt) { await expire(id); return }
      try {
        const step = await oauth.devicePoll(clientId, current.device, { endpoints: rt.config.github?.endpoints })
        if (step.state === 'done') {
          await endPending(id)
          await writeSecret(GITHUB_SECRET, step.token, 'GitHub connector')
          const account = await readAccount(id, entry, step.token).catch(() => undefined)
          await saveState(id, { account, connectedAt: Date.now() })
          await sync(true)
          return
        }
        if (step.state === 'error') { await endPending(id, { state: 'error', error: reason(step.error) }); return }
        if (step.state === 'slow_down') current.interval += 5
      } catch (error) {
        await endPending(id, { state: 'error', error: reason(error) })
        return
      }
      current.timer = setTimeout(() => void poll(), current.interval * 1000)
    }
    pendings.set(id, {
      ...pending, kind: 'device', device, interval: device.interval,
      row: { kind: 'device', userCode: device.userCode, verificationUri: device.verificationUri, expiresAt: device.expiresAt },
      timer: setTimeout(() => void poll(), device.interval * 1000),
    })
  }

  async function beginSignIn(id) {
    const entry = known(id)
    if (entry.auth.kind !== 'oauth') throw new Error('This connector does not sign in')
    if (rt.readOnly() !== undefined) throw new Error(rt.readOnly())
    await rt.loadSecrets()
    if (pendings.has(id)) await endPending(id)
    statuses.set(id, { state: 'connecting' })
    try {
      // GitHub's own flow: device code through github.com, no discovery.
      if (entry.auth.client?.deviceFlow === true) {
        await startDeviceFlow(id, entry, {})
        return
      }
      const remote = entry.remote?.url
      if (remote === undefined) throw new Error('This connector has no server address')
      if (insecure(remote)) throw new Error('Connector addresses must start with https://')
      const discovery = await oauth.discover(remote)
      if (discovery.metadata === undefined) throw new Error('This service does not publish OAuth sign-in metadata')
      state.connectors = { ...(state.connectors ?? {}), [id]: { ...state.connectors?.[id], oauth: { authorizationServerUrl: discovery.authorizationServerUrl, resource: discovery.resource, scope: discovery.scope } } }
      await rt.save()
      await startBrowserFlow(id, entry, { discovery })
    } catch (error) {
      await endPending(id)
      statuses.set(id, { state: 'error', error: reason(error) })
    }
  }

  // One refresh per connector at a time; read-only windows never write.
  function refreshConnector(id) {
    if (refreshes.has(id)) return refreshes.get(id)
    const job = (async () => {
      const saved = state.connectors?.[id]
      const readOnly = rt.readOnly()
      if (readOnly !== undefined) {
        await rt.loadSecrets()
        return false
      }
      const refresh = rt.secretValue(refreshSecretOf(id))
      let path = saved?.client?.via ?? 'inferred'
      if (refresh === undefined || saved?.oauth === undefined) {
        statuses.set(id, { state: 'needs-sign-in' })
        rt.warn('ds-bot: connector %s token refresh failed (client: %s; missing refresh token or OAuth metadata)', id, path)
        return false
      }
      try {
        const discovery = await oauth.rediscover(saved.oauth)
        // Refresh with the client that signed in: catalog → the current catalog id,
        // CIMD → the published document id, DCR/manual → the stored id (+ secret).
        // Rows signed in before clients were persisted have no `client`: fall back to
        // CIMD when the AS supports it, otherwise ask the user to sign in again.
        const via = saved.client?.via
        const clientId = via === 'catalog' ? entryFor(id)?.auth?.client?.id
          : via === 'cimd' ? oauth.CIMD_CLIENT_ID
          : saved.client?.clientId ?? (discovery.metadata?.client_id_metadata_document_supported === true ? oauth.CIMD_CLIENT_ID : undefined)
        const clientVia = via ?? (saved.client?.clientId ? 'manual' : 'cimd')
        if (via === undefined && clientId !== undefined) path = `inferred/${clientVia}`
        if (clientId === undefined) {
          statuses.set(id, { state: 'needs-sign-in' })
          rt.warn('ds-bot: connector %s token refresh failed (client: %s; no OAuth client)', id, path)
          return false
        }
        const secret = rt.secretValue(clientSecretOf(id))
        const client = { client_id: clientId, ...(secret !== undefined ? { client_secret: secret } : {}) }
        const tokens = await oauth.refreshTokens(discovery, client, refresh, { scope: saved.oauth.scope })
        const purpose = `${entryFor(id)?.name ?? id} connector`
        await writeSecret(tokenSecretOf(id), tokens.access_token, purpose)
        if (typeof tokens.refresh_token === 'string' && tokens.refresh_token !== '' && tokens.refresh_token !== refresh) {
          // Rotation: the old refresh token stays if this write fails.
          await writeSecret(refreshSecretOf(id), tokens.refresh_token, purpose).catch(() => {})
        }
        await saveState(id, {
          client: { ...saved.client, via: clientVia, clientId },
          tokenExpiresAt: Number.isFinite(tokens.expires_in) ? Date.now() + tokens.expires_in * 1000 : undefined,
        })
        statuses.delete(id)
        rt.warn('ds-bot: connector %s token refresh succeeded (client: %s)', id, path)
        return true
      } catch (error) {
        if (oauth.invalidGrant(error)) statuses.set(id, { state: 'needs-sign-in', error: 'Sign in again' })
        else statuses.set(id, { state: 'error', error: reason(error) })
        rt.warn('ds-bot: connector %s token refresh failed (client: %s; %s)', id, path, oauth.invalidGrant(error) ? 'invalid_grant' : 'refresh error')
        return false
      }
    })().finally(() => refreshes.delete(id))
    refreshes.set(id, job)
    return job
  }

  // --- request cards (request_connector) ---------------------------------

  const requestsOf = (botId) => {
    const requests = (state.connectorRequests ??= {})
    if (!Object.hasOwn(requests, botId) && rt.botOf(botId) === undefined) return []
    return (requests[botId] ??= [])
  }
  const settleRequests = async (id) => {
    const notes = []
    for (const [botId, list] of Object.entries(state.connectorRequests ?? {})) {
      for (const request of list) {
        if (request.status !== 'pending' || request.connectorId !== id) continue
        request.status = 'connected'
        request.settledAt = Date.now()
        const entry = entryFor(id)
        notes.push([botId, `The user connected ${entry?.name ?? id}. Its tools are available as mcp__${id}__* now. Carry on with what you needed it for.`])
      }
    }
    if (notes.length === 0) return
    await rt.save()
    for (const [botId, text] of notes) {
      await rt.deliver({ toId: botId, role: 'connector', text }).catch(error => rt.warn('ds-bot: connector note to %s failed: %s', botId, error))
    }
  }

  rt.teamTools.push(defineTool({
    name: 'list_connectors',
    description: 'List the connectors the team can use: name, what it offers, whether it is connected, and whether you may use it. Connect one for yourself with request_connector.',
    parameters: {},
    output,
    async execute(_args, exec) {
      await rt.load()
      const self = rt.selfOf(exec.agent?.id)
      const bot = rt.botOf(self)
      if (!bot) return 'Only Bots on the team can use list_connectors.'
      const rows = entries().filter(entry => entry.id !== 'mail' || mailHasAccounts())
      if (rows.length === 0) return 'No connectors are set up.'
      const lines = rows.map((entry) => {
        const connected = entry.id === 'mail' ? mailHasAccounts() : (statuses.get(entry.id)?.state === undefined && mounts.has(entry.id)) || hasCredential(entry.id)
        const usable = !offFor(entry.id).includes(bot.id)
        return `- ${entry.name} (${entry.id}) — ${entry.about} — ${connected ? 'connected' : 'not connected'}${usable ? '' : '; turned off for you'}`
      })
      return ['Connectors:', ...lines].join('\n')
    },
  }))

  rt.teamTools.push(defineTool({
    name: 'request_connector',
    description: 'Ask the user to connect an outside service through a card in your own chat, when you need a service that is not connected. The card shows a Connect button; your turn ends and a note arrives when the user connects or dismisses it. If the connector is already connected, this just tells you its tool prefix.',
    parameters: {
      id: { type: 'string', required: true, description: 'Connector id from list_connectors' },
      purpose: { type: 'string', required: true, description: 'One short line for the user: what you need it for' },
    },
    output,
    async execute(args, exec) {
      await rt.load()
      const id = String(args.id ?? '').trim()
      const entry = id === 'mail' ? entryOf('mail') : entryFor(id)
      if (entry === undefined) return `No connector named ${id}.`
      const agentId = exec.agent?.id
      const bot = rt.botOf(rt.selfOf(agentId))
      if (bot === undefined) return 'Only Bots on the team can use request_connector.'
      const connected = id === 'mail' ? mailHasAccounts() : hasCredential(id)
      const signIn = statuses.get(id)?.state === 'needs-sign-in'
      if (connected && !signIn && !offFor(id).includes(bot.id)) return `${entry.name} is already connected; use its tools (mcp__${id}__*).`
      if (offFor(id).includes(bot.id)) return `${entry.name} is turned off for you. The user can turn it on in your details.`
      if (rt.groupOwners.has(agentId)) return 'Connector cards only work in your own chat. Tell the group you will ask the user in your own chat, and call request_connector there.'
      if (!rt.chatOwners.has(agentId)) return 'Connector cards only work in your current own chat.'
      const readOnly = rt.readOnly()
      if (readOnly !== undefined) return `No card can be shown now. ${readOnly}`
      const list = requestsOf(bot.id)
      const now = Date.now()
      for (const request of list) if (request.status === 'pending' && request.connectorId === id) { request.status = 'canceled'; request.settledAt = now }
      list.push({
        id: randomUUID(),
        ...(exec.callId ? { callId: exec.callId } : {}),
        sessionId: agentId,
        connectorId: id,
        name: entry.name,
        purpose: String(args.purpose ?? '').trim().slice(0, 300),
        status: 'pending',
        askedAt: now,
      })
      while (list.length > MAX_REQUESTS) { const at = list.findIndex(entry => entry.status !== 'pending'); list.splice(at === -1 ? 0 : at, 1) }
      await rt.save()
      exec.concludeTurn?.()
      return `The card asking the user to connect ${entry.name} is on screen. A note arrives when the user connects or dismisses it.`
    },
  }))

  const offFor = id => state.connectors?.[id]?.offFor ?? []

  // --- import -------------------------------------------------------------

  const importFiles = () => {
    const home = homedir()
    const appData = platform() === 'win32' ? (process.env.APPDATA ?? join(home, 'AppData', 'Roaming')) : null
    const files = [
      { source: 'claude', key: 'mcpServers', path: platform() === 'darwin' ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json') : platform() === 'win32' ? join(appData, 'Claude', 'claude_desktop_config.json') : join(home, '.config', 'Claude', 'claude_desktop_config.json') },
      { source: 'cursor', key: 'mcpServers', path: join(home, '.cursor', 'mcp.json') },
      { source: 'vscode', key: 'servers', path: platform() === 'darwin' ? join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json') : platform() === 'win32' ? join(appData, 'Code', 'User', 'mcp.json') : join(home, '.config', 'Code', 'User', 'mcp.json') },
    ]
    return files
  }
  const importScan = async () => {
    const found = []
    for (const file of importFiles()) {
      let parsed
      try { parsed = JSON.parse(await readFile(file.path, 'utf8')) } catch { continue }
      const servers = parsed?.[file.key]
      if (servers === null || typeof servers !== 'object' || Array.isArray(servers)) continue
      for (const [name, spec] of Object.entries(servers)) {
        if (spec === null || typeof spec !== 'object') continue
        const url = typeof spec.url === 'string' ? spec.url : typeof spec.serverUrl === 'string' ? spec.serverUrl : undefined
        const command = typeof spec.command === 'string' ? spec.command : undefined
        if (url === undefined && command === undefined) continue
        found.push({
          source: file.source,
          name,
          ...(url !== undefined ? { url } : { command, args: Array.isArray(spec.args) ? spec.args.filter(arg => typeof arg === 'string') : [] }),
          envNames: Object.keys(spec.env ?? {}),
          headersNames: Object.keys(spec.headers ?? {}),
        })
      }
    }
    return found
  }
  const importPick = async (items) => {
    const scanned = await importScan()
    const wanted = new Set((Array.isArray(items) ? items : []).map(item => `${item?.source ?? ''}:${item?.name ?? ''}`))
    const picked = []
    for (const file of importFiles()) {
      let parsed
      try { parsed = JSON.parse(await readFile(file.path, 'utf8')) } catch { continue }
      const servers = parsed?.[file.key] ?? {}
      for (const [name, spec] of Object.entries(servers)) {
        if (!wanted.has(`${file.source}:${name}`) || spec === null || typeof spec !== 'object') continue
        if (scanned.some(entry => entry.source === file.source && entry.name === name)) picked.push({ name, spec })
      }
    }
    return picked
  }

  // --- view & endpoints ---------------------------------------------------

  const rowFor = (entry) => {
    const saved = state.connectors?.[entry.id]
    const status = statuses.get(entry.id)
    const connected = hasCredential(entry.id)
    const remote = entry.custom === undefined || entry.custom.url !== undefined
    const state_ = status?.state ?? (connected && mounts.has(entry.id) ? 'ready' : connected ? 'connecting' : 'off')
    return {
      id: entry.id,
      name: entry.name,
      category: entry.category,
      about: entry.about,
      auth: entry.auth,
      state: state_,
      ...(status?.error !== undefined ? { error: status.error } : {}),
      account: saved?.account ?? (id => id === 'github' ? saved?.login : undefined)(entry.id) ?? null,
      ...(remote && connected && entry.auth.kind !== 'none' ? { readOnly: saved?.readOnly === true } : {}),
      ...(remote && connected && (entry.auth.kind === 'oauth' || entry.auth.kind === 'key') ? { readOnly: saved?.readOnly === true } : {}),
      offFor: saved?.offFor ?? [],
      tools: gateways.gw?.toolCount?.(entry.id) ?? 0,
      ...(entry.custom !== undefined ? { custom: true } : {}),
      ...(pendings.has(entry.id) ? { pending: pendings.get(entry.id).row } : {}),
    }
  }

  const connectorsView = () => ({
    connectors: entries().filter(entry => entry.id !== 'mail').map(rowFor),
    mail: rt.mailView?.() ?? { accounts: [], google: false },
  })

  const endpoints = {
    async 'connector-connect'(body) {
      const entry = known(body.id)
      if (entry.id === 'github' && options === null) throw new Error('No such connector')
      if (entry.auth.kind === 'none') {
        await saveState(entry.id, { connectedAt: Date.now() })
        await sync()
        return connectorsView()
      }
      if (entry.auth.kind === 'key') {
        const key = typeof body.key === 'string' ? body.key.trim() : ''
        if (key === '') throw new Error('Paste a key first')
        const remote = entry.remote?.url
        if (remote !== undefined && insecure(remote)) throw new Error('Connector addresses must start with https://')
        await writeSecret(keySecretOf(entry.id), key, `${entry.name} connector`)
        await saveState(entry.id, { connectedAt: Date.now() })
        await sync()
        return connectorsView()
      }
      const token = typeof body.token === 'string' ? body.token.trim() : ''
      if (token !== '') {
        const remote = entry.remote?.url
        if (remote !== undefined && insecure(remote)) throw new Error('Connector addresses must start with https://')
        if (entry.id === 'github' && options?.api !== undefined && insecure(options.api)) throw new Error('GitHub addresses must start with https://')
        await rt.loadSecrets()
        let account
        if (entry.id === 'github') account = (await signIn(token, { api: options.api })).login
        else if (entry.whoami !== undefined) account = await readAccount(entry.id, entry, token)
        await writeSecret(tokenSecretOf(entry.id), token, `${entry.name} connector`)
        await saveState(entry.id, { account, ...(entry.id === 'github' ? { login: account } : {}), connectedAt: Date.now() })
        await sync()
        return connectorsView()
      }
      if (entry.id === 'github' && (entry.auth.client?.id ?? '') === '') throw new Error('Paste a token first')
      await beginSignIn(entry.id)
      return connectorsView()
    },
    async 'connector-disconnect'(body) {
      const entry = known(body.id)
      await endPending(entry.id)
      await dropSecrets(entry.id)
      if (state.connectors?.[entry.id] !== undefined) {
        delete state.connectors[entry.id]
        await rt.save()
      }
      gateways.gw?.forget(entry.id)
      await sync()
      return connectorsView()
    },
    async 'connector-retry'(body) {
      const entry = known(body.id)
      statuses.delete(entry.id)
      await rt.loadSecrets()
      await sync(true)
      return connectorsView()
    },
    async 'connector-cancel'(body) {
      const entry = known(body.id)
      await endPending(entry.id, { state: hasCredential(entry.id) ? 'ready' : 'off' })
      return connectorsView()
    },
    async 'connector-sign-in-code'(body) {
      const entry = known(body.id)
      const pending = pendings.get(entry.id)
      if (pending === undefined || pending.kind !== 'browser') throw new Error('No sign-in is waiting')
      const input = String(body.input ?? body.code ?? '').trim()
      if (input === '') throw new Error('Paste the address or the code')
      let code = input, stateParam, iss
      if (/^https?:\/\//i.test(input)) {
        const url = new URL(input)
        code = url.searchParams.get('code') ?? ''
        stateParam = url.searchParams.get('state')
        iss = url.searchParams.get('iss') ?? undefined
        if (stateParam !== pending.expectedState) throw new Error('This address is not from this sign-in attempt (state mismatch). Copy the whole address again.')
      }
      if (code === '') throw new Error('The address has no code')
      await completeBrowser(entry.id, { code, state: pending.expectedState, iss })
      return connectorsView()
    },
    async 'connector-client'(body) {
      const entry = known(body.id)
      const clientId = String(body.clientId ?? '').trim()
      if (clientId === '') throw new Error('Enter the client ID')
      const clientSecret = typeof body.clientSecret === 'string' && body.clientSecret.trim() !== '' ? body.clientSecret.trim() : undefined
      if (clientSecret !== undefined) await writeSecret(clientSecretOf(entry.id), clientSecret, `${entry.name} connector`)
      await saveState(entry.id, { client: { via: 'manual', clientId } })
      const pending = pendings.get(entry.id)
      if (pending !== undefined && pending.discovery !== undefined) {
        await startBrowserFlow(entry.id, entry, pending)
      }
      return connectorsView()
    },
    async 'connector-set'(body) {
      const entry = known(body.id)
      const patch = {}
      if (body.readOnly !== undefined) patch.readOnly = body.readOnly === true
      if (Array.isArray(body.offFor)) patch.offFor = [...new Set(body.offFor.filter(id => rt.botOf(id) !== undefined))]
      await saveState(entry.id, patch)
      rt.reapplyToolMasks?.()
      return connectorsView()
    },
    async 'connector-add'(body) {
      const name = String(body.name ?? '').trim()
      if (name === '') throw new Error('Name the connector')
      const url = typeof body.url === 'string' ? body.url.trim() : undefined
      const command = typeof body.command === 'string' ? body.command.trim() : undefined
      if (url !== undefined && insecure(url) && !/^http:\/\/(localhost|127\.)/i.test(url)) throw new Error('Connector addresses must start with https://')
      if (url === undefined && command === undefined) throw new Error('Enter an address or a command')
      const taken = new Set(Object.keys(state.connectors ?? {}))
      const id = customId(name, taken)
      CONNECTOR_IDS.add(id)
      const custom = url !== undefined
        ? { name, url, headers: body.headers && typeof body.headers === 'object' ? body.headers : {} }
        : { name, command, args: Array.isArray(body.args) ? body.args.map(String) : [], env: body.env && typeof body.env === 'object' ? body.env : {} }
      await saveState(id, { custom, connectedAt: Date.now() })
      await sync(true)
      return connectorsView()
    },
    async 'connector-remove'(body) {
      const entry = known(body.id)
      if (entry.custom === undefined) throw new Error('Only added connectors can be removed')
      await endpoints['connector-disconnect']({ id: entry.id })
      return connectorsView()
    },
    async 'connector-import-scan'() {
      return importScan()
    },
    async 'connector-import'(body) {
      const picked = await importPick(body.items)
      const created = []
      for (const { name, spec } of picked) {
        const taken = new Set(Object.keys(state.connectors ?? {}))
        const id = customId(name, taken)
        const custom = { name }
        if (typeof spec.url === 'string' || typeof spec.serverUrl === 'string') {
          custom.url = spec.url ?? spec.serverUrl
          custom.headers = {}
          for (const [header, raw] of Object.entries(spec.headers ?? {})) {
            const secretName = envSecretOf(id, `HEAD_${header}`)
            await writeSecret(secretName, String(raw), `${name} connector`)
            custom.headers[header] = `$DSH_SECRET_${secretName}`
          }
        } else if (typeof spec.command === 'string') {
          custom.command = spec.command
          custom.args = Array.isArray(spec.args) ? spec.args.map(String) : []
          custom.env = {}
          for (const [envName, raw] of Object.entries(spec.env ?? {})) {
            const secretName = envSecretOf(id, envName)
            await writeSecret(secretName, String(raw), `${name} connector`)
            custom.env[envName] = `$DSH_SECRET_${secretName}`
          }
        } else continue
        await saveState(id, { custom, connectedAt: Date.now() })
        created.push(id)
      }
      await sync(true)
      return { view: connectorsView(), created }
    },
    async 'connector-request-cancel'(body) {
      const found = (() => {
        for (const [botId, list] of Object.entries(state.connectorRequests ?? {})) {
          const request = list.find(entry => entry.id === String(body.requestId ?? ''))
          if (request !== undefined) return { botId, request }
        }
        return undefined
      })()
      if (found === undefined) throw new Error('This request is gone')
      if (found.request.status !== 'pending') throw new Error('This request was already answered')
      found.request.status = 'canceled'
      found.request.settledAt = Date.now()
      await rt.save()
      await rt.deliver({ toId: found.botId, role: 'connector', text: `The user dismissed your request to connect ${entryFor(found.request.connectorId)?.name ?? found.request.connectorId}. Carry on without it, or tell the user what you cannot do without it.` }).catch(() => {})
      return true
    },
  }

  const mailApi = installMail(rt, { entries: () => entries().find(e => e.id === 'mail'), offFor, secrets: { writeSecret, value: name => rt.secretValue(name) }, reason })
  const mailHasAccounts = () => mailApi.hasAccounts()
  rt.mailView = mailApi.mailView

  const connectorEndpoint = async (endpoint, body) => {
    await rt.loadSecrets()
    if (endpoint.startsWith('mail-')) return mailApi.endpoint(endpoint, body)
    return endpoints[endpoint](body ?? {})
  }

  ctx.on('tools/change', () => { rt.reapplyToolMasks?.() })

  ctx.effect(() => {
    stopped = false
    void rt.load().then(() => rt.loadSecrets()).then(() => sync())
    return () => {
      stopped = true
      for (const pending of pendings.values()) if (pending.timer !== undefined) clearTimeout(pending.timer)
      for (const pending of pendings.values()) pending.listener?.close()
      pendings.clear()
      const closing = [...mounts.values()].map(mount => Promise.resolve().then(() => mount.fiber?.dispose()).catch(() => {}))
      mounts.clear()
      const gw = gateways.gw
      gateways.gw = null
      return Promise.all([...closing, gw?.close(), mailApi.dispose()])
    }
  }, 'ds-bot: connectors')

  Object.assign(rt, {
    connectorsView,
    connectorEndpoint,
    connectorOffFor: (botId) => {
      const prefixes = []
      for (const entry of entries()) {
        if (!offFor(entry.id).includes(botId)) continue
        if (entry.id === 'mail') prefixes.push('mail_')
        else prefixes.push(`mcp__${entry.id}__`)
      }
      return prefixes
    },
    connectorSettleRequests: settleRequests,
    secretsChanged: () => { void sync() },
    connectorsInternals: { mounts, statuses, pendings, gateways, refreshConnector, upstreamOf },
  })
}