import { createHash } from 'node:crypto' import { encodeUrlComponent } from './secrets.js' import { own } from './store.js' const MCP_CLIENT = '@deepseek-ai/dsh-mcp-client' const NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/ const SECRET_REFERENCE = /\$DSH_SECRET_([A-Z][A-Z0-9_]*)/g const ENSURE_TIMEOUT_MS = 15_000 // Connector ids are reserved: a capability named like one would collide with // its mcp____* tool prefix. The connectors module registers its ids here. export const CONNECTOR_IDS = new Set(['github', 'mail']) export function validateCapabilityName(value, reserved = CONNECTOR_IDS) { const name = String(value ?? '').trim() if (name.length > 32 || !NAME.test(name) || name === 'github' || reserved.has(name)) { throw new Error('Use a capability name with lowercase letters, digits, and single hyphens; connector names are reserved.') } return name } export function expandCapabilityNames(capabilities, library) { const expanded = new Set() for (const name of capabilities ?? []) { const item = own(library, name) if (!item) throw new Error(`No capability named ${name}.`) if (item.kind === 'pack') { for (const childName of item.items ?? []) { const child = own(library, childName) if (!child || !['mcp', 'skill'].includes(child.kind)) throw new Error(`Pack ${name} refers to an unavailable capability ${childName}.`) expanded.add(childName) } } else if (item.kind === 'mcp' || item.kind === 'skill') { expanded.add(name) } else { throw new Error(`Capability ${name} has an unknown kind.`) } } return expanded } const same = (a, b) => JSON.stringify(a) === JSON.stringify(b) const strings = value => { if (value === undefined) return [] if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) throw new Error('Arguments must be a list of text values.') return [...value] } const stringMap = (value, label) => { if (value === undefined) return {} if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.values(value).some(item => typeof item !== 'string')) throw new Error(`${label} must contain text values.`) return Object.fromEntries(Object.entries(value)) } export function install(rt) { const { ctx, state } = rt const agents = new Map() // Mounted fibers live in each Agent's own context, so they outlive this plugin unless // its cleanup disposes them; a strong map keeps them reachable for that. const mounts = new Map() // One reconcile chain per Agent: a slow MCP server holds up only its own Agent. const chains = new WeakMap() const queued = new WeakSet() const sessionStatuses = new Map() let pluginPromise let scheduled = null let loadingSecrets = 0 let stopped = false const library = () => state.capabilities.items const ensureLibrary = () => { state.capabilities ??= { items: {} } state.capabilities.items ??= {} return library() } const writeCheck = () => { const readOnly = rt.readOnly() if (readOnly !== undefined) throw new Error(readOnly) } const allowedToEdit = (item, botId) => rt.isMain(botId) || item.createdBy === botId const usedByOthers = (name, botId) => Object.values(state.bots).some(bot => bot.id !== botId && (bot.capabilities ?? []).some((attached) => { const item = own(library(), attached) return attached === name || (item?.kind === 'pack' && (item.items ?? []).includes(name)) })) // A creator that is not a Main Bot could otherwise rewrite what a Main Bot runs. const editCheck = (item, botId, verb) => { if (!allowedToEdit(item, botId)) throw new Error(`Only ${item.createdBy ? 'its creator or a Main Bot' : 'a Main Bot'} can ${verb} ${item.name}.`) if (!rt.isMain(botId) && usedByOthers(item.name, botId)) throw new Error(`Another Bot uses ${item.name}, so only a Main Bot can ${verb} it.`) } const itemInput = (body, { botId, ui }) => { const name = validateCapabilityName(body.name) const kind = body.kind if (!['mcp', 'skill', 'pack'].includes(kind)) throw new Error('Choose an MCP server, skill, or pack.') const items = ensureLibrary() const previous = own(items, name) if (previous && !ui) editCheck(previous, botId, 'change') if (previous && previous.kind !== kind) throw new Error('A capability cannot change its kind. Delete it and save a new one.') const now = Date.now() const item = { name, kind, description: String(body.description ?? '').trim().slice(0, 2000), createdBy: previous?.createdBy ?? (ui ? null : botId), createdAt: previous?.createdAt ?? now, updatedAt: now, } if (kind === 'mcp') { const transport = body.transport === 'streamable-http' ? 'streamable-http' : 'stdio' if (transport === 'stdio') { const command = String(body.command ?? '').trim() if (command === '') throw new Error('Enter a command for the MCP server.') const args = strings(body.args) const env = stringMap(body.env, 'Environment variables') const changed = !previous || previous.kind !== 'mcp' || previous.transport !== 'stdio' || previous.command !== command || !same(previous.args ?? [], args) || !same(previous.env ?? {}, env) Object.assign(item, { transport, command, args, env, approved: ui ? true : changed ? false : previous.approved === true }) } else { const url = String(body.url ?? '').trim() try { const parsed = new URL(url) if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') throw new Error() } catch { throw new Error('Enter a valid HTTP or HTTPS URL.') } Object.assign(item, { transport, url, headers: stringMap(body.headers, 'Headers'), approved: true }) } } else if (kind === 'skill') { item.content = String(body.content ?? '').trim() } else { const names = [...new Set(strings(body.items))] for (const childName of names) { const child = own(items, childName) if (!child || !['mcp', 'skill'].includes(child.kind)) throw new Error(`Packs can include only saved MCP servers and skills. ${childName} is not one.`) } item.items = names } items[name] = item return item } const capabilitySave = async (body, options = {}) => { await rt.load() writeCheck() const item = itemInput(body ?? {}, options) await rt.save() return item } const capabilityDelete = async (name, { botId, ui } = {}) => { await rt.load() writeCheck() const items = ensureLibrary() const item = own(items, String(name ?? '')) if (!item) throw new Error(`No capability named ${name}.`) if (!ui) editCheck(item, botId, 'delete') delete items[item.name] for (const pack of Object.values(items)) if (pack.kind === 'pack') pack.items = (pack.items ?? []).filter(child => child !== item.name) for (const bot of Object.values(state.bots)) bot.capabilities = (bot.capabilities ?? []).filter(attached => attached !== item.name) await rt.save() return true } // Called with the Bot being deleted, after it left the team. The shared list belongs to // the user, so only a local MCP this Bot added, nobody approved and no other Bot or pack // uses goes: no one is left to ask for it, and approving it would start a server for no one. // Anything a pack lists stays. const dropOrphanCapabilities = (bot) => { const items = library() const packed = name => Object.values(items).some(item => item.kind === 'pack' && (item.items ?? []).includes(name)) for (const name of bot.capabilities ?? []) { const item = own(items, name) if (item === undefined || item.kind !== 'mcp' || item.transport !== 'stdio' || item.approved === true) continue if (item.createdBy !== bot.id || usedByOthers(name, bot.id) || packed(name)) continue delete items[item.name] } } const changeAttachment = async (endpoint, { name, bot: targetRef }, callerId) => { await rt.load() writeCheck() const caller = rt.botOf(callerId) if (!caller) throw new Error('Only Bots on the team can change capabilities.') const target = targetRef ? rt.findBot(targetRef) : caller if (!target) throw new Error(`No Bot named ${targetRef}.`) if (target.id !== caller.id && !rt.isMain(callerId)) throw new Error('Only a Main Bot can change another Bot’s capabilities.') const item = own(ensureLibrary(), String(name ?? '')) if (!item) throw new Error(`No capability named ${name}.`) await setAttached(target, item.name, endpoint === 'attach') return { bot: target.name, attached: endpoint === 'attach' } } // Changes one name against the saved list, so two quick changes both land. const setAttached = async (bot, name, attached) => { bot.capabilities ??= [] const wasEmpty = bot.capabilities.length === 0 if (attached && !bot.capabilities.includes(name)) bot.capabilities.push(name) if (!attached) bot.capabilities = bot.capabilities.filter(entry => entry !== name) await rt.save() if (wasEmpty && bot.capabilities.length > 0) { await trackBotAgents(bot) void scheduleReconcile() } return bot.capabilities } const statusSet = (botId, itemName, sessionId, status) => { let byItem = sessionStatuses.get(botId) if (!byItem) sessionStatuses.set(botId, byItem = new Map()) let bySession = byItem.get(itemName) if (!bySession) byItem.set(itemName, bySession = new Map()) bySession.set(sessionId, status) } const clearStatus = (botId, itemName, sessionId) => { const byItem = sessionStatuses.get(botId) const bySession = byItem?.get(itemName) bySession?.delete(sessionId) if (bySession?.size === 0) byItem.delete(itemName) if (byItem?.size === 0) sessionStatuses.delete(botId) } const clearSession = sessionId => { for (const [botId, byItem] of sessionStatuses) { for (const [name, bySession] of byItem) { bySession.delete(sessionId) if (bySession.size === 0) byItem.delete(name) } if (byItem.size === 0) sessionStatuses.delete(botId) } } const statusFor = (botId, name) => { const values = [...(sessionStatuses.get(botId)?.get(name)?.values() ?? [])] if (values.some(status => status.state === 'error')) return values.find(status => status.state === 'error') if (values.some(status => status.state === 'needs-approval')) return { state: 'needs-approval' } if (values.some(status => status.state === 'connecting')) return { state: 'connecting' } return values.length > 0 ? { state: 'ready' } : undefined } const capabilityStatusesView = () => { const result = {} for (const bot of Object.values(state.bots)) { const statuses = {} for (const name of bot.capabilities ?? []) { const item = own(library(), name) if (!item) continue if (item.kind !== 'pack') { const status = statusFor(bot.id, name) if (status) statuses[name] = status continue } const children = (item.items ?? []).map(child => statusFor(bot.id, child)).filter(Boolean) const status = children.find(status => status.state === 'error') ?? children.find(status => status.state === 'needs-approval') ?? children.find(status => status.state === 'connecting') ?? children[0] if (status) statuses[name] = status } result[bot.id] = statuses } return result } const libraryView = () => Object.values(library()).map(item => ({ ...item, ...(item.env ? { env: { ...item.env } } : {}), ...(item.headers ? { headers: { ...item.headers } } : {}), ...(item.items ? { items: [...item.items] } : {}), })) async function loadMcpPlugin() { if (!pluginPromise) { pluginPromise = (async () => { const loader = ctx.get?.('loader') if (typeof loader?.import !== 'function') throw new Error('This DSH cannot load MCP servers.') const exports = await loader.import(MCP_CLIENT) return loader.unwrapExports?.(exports) ?? exports?.default ?? exports })() } return pluginPromise } function secretFor(name, botId) { const value = rt.canUseSecret(name, botId) ? rt.secretValue(name) : undefined if (value === undefined) throw new Error(`Secret ${name} is missing or unavailable for this Bot.`) return value } function resolveValues(values, botId) { const resolved = {} for (const [key, raw] of Object.entries(values ?? {})) { resolved[key] = String(raw).replace(SECRET_REFERENCE, (_match, name) => secretFor(name, botId)) } return resolved } const resolveUrl = (url, botId) => String(url).replace(SECRET_REFERENCE, (_match, name) => encodeUrlComponent(secretFor(name, botId))) const resolveList = (list, botId) => (list ?? []).map(raw => String(raw).replace(SECRET_REFERENCE, (_match, name) => secretFor(name, botId))) const configFor = (item, botId) => { if (item.kind === 'skill') return { name: item.name, description: item.description, content: item.content } if (item.transport === 'stdio') return { transport: 'stdio', serverName: item.name, command: item.command, args: resolveList(item.args, botId), env: resolveValues(item.env, botId), failOnStartupError: true } return { transport: 'streamable-http', serverName: item.name, url: resolveUrl(item.url, botId), headers: resolveValues(item.headers, botId), failOnStartupError: true } } const disposeMount = async mount => { if (mount?.fiber) await Promise.resolve().then(() => mount.fiber.dispose()).catch(() => {}) } const mountOne = async (agent, bot, agentMounts, name) => { const sessionId = agent.session.id const item = own(library(), name) const drop = async () => { await disposeMount(agentMounts.get(name)) agentMounts.delete(name) } if (item.kind === 'mcp' && item.transport === 'stdio' && item.approved !== true) { await drop() statusSet(bot.id, name, sessionId, { state: 'needs-approval' }) return } let config try { config = configFor(item, bot.id) } catch (error) { await drop() statusSet(bot.id, name, sessionId, { state: 'error', error: rt.redactSecrets(error.message).slice(0, 300) }) return } const key = `${name}:${createHash('sha256').update(JSON.stringify(config)).digest('hex')}` if (agentMounts.get(name)?.key === key) return await drop() statusSet(bot.id, name, sessionId, { state: 'connecting' }) try { const plugin = item.kind === 'skill' ? { name: `ds-bot-capability-skill-${name}`, inject: ['skills'], apply(c) { c.effect(() => c.skills.register({ name: config.name, description: config.description, source: 'runtime', content: config.content })) }, } : await loadMcpPlugin() if (stopped) return const fiber = item.kind === 'skill' ? agent.ctx.plugin(plugin) : agent.ctx.plugin(plugin, config) agentMounts.set(name, { key, fiber }) await fiber.await() if (stopped || agents.get(sessionId)?.deref() !== agent) return statusSet(bot.id, name, sessionId, { state: 'ready' }) } catch (error) { await drop() const message = rt.redactSecrets([error, error?.cause].filter(Boolean).map(part => String(part?.message ?? part)).join(': ') || 'Connection failed').slice(0, 300) statusSet(bot.id, name, sessionId, { state: 'error', error: message }) } } const reconcileAgent = async (agent, bot) => { const sessionId = agent.session.id const desired = bot ? expandCapabilityNames(bot.capabilities, library()) : new Set() const agentMounts = mounts.get(agent) ?? new Map() if (desired.size > 0) mounts.set(agent, agentMounts) if (bot) { for (const name of sessionStatuses.get(bot.id)?.keys() ?? []) { if (!desired.has(name)) clearStatus(bot.id, name, sessionId) } } else { clearSession(sessionId) } for (const [name, mount] of agentMounts) { if (desired.has(name)) continue await disposeMount(mount) agentMounts.delete(name) } await Promise.all([...desired].map(name => mountOne(agent, bot, agentMounts, name))) if (agentMounts.size === 0 && mounts.get(agent) === agentMounts) mounts.delete(agent) } const botOfSession = sessionId => (rt.isBotSession(sessionId) ? rt.botOf(rt.selfOf(sessionId)) : undefined) // At most one run waits behind the running one; it reads the latest state when it starts. const reconcileOne = agent => { if (queued.has(agent)) return chains.get(agent) queued.add(agent) const run = (chains.get(agent) ?? Promise.resolve()).then(async () => { queued.delete(agent) const sessionId = agent.session.id if (stopped || agents.get(sessionId)?.deref() !== agent) return await reconcileAgent(agent, botOfSession(sessionId)) }).catch(error => rt.warn('ds-bot: capability reconcile for %s failed: %s', agent.session?.id, error)) chains.set(agent, run) return run } const loadInputs = async () => { await rt.load() loadingSecrets += 1 try { await rt.loadSecrets() } finally { loadingSecrets -= 1 } } async function reconcile() { if (stopped) return await loadInputs() const runs = [] for (const [sessionId, reference] of agents) { const agent = reference.deref() if (agent) { runs.push(reconcileOne(agent)) continue } agents.delete(sessionId) clearSession(sessionId) } await Promise.all(runs) } const scheduleReconcile = () => { if (!scheduled) { scheduled = new Promise(resolve => queueMicrotask(() => { scheduled = null resolve(reconcile().catch(error => rt.warn('ds-bot: capability reconcile failed: %s', error))) })) } return scheduled } // A run that outlasts the limit goes on in the background, and later requests for the // same Agent do not wait for it again. const stalled = new WeakSet() const prepare = async (agent, sessionId) => { const run = loadInputs().then(() => reconcileOne(agent)).then(() => true, error => { rt.warn('ds-bot: capability mount for %s failed: %s', sessionId, error) return true }) if (stalled.has(agent)) return const timeoutMs = rt.capabilityEnsureTimeoutMs ?? ENSURE_TIMEOUT_MS let timer const completed = await Promise.race([run, new Promise(resolve => { timer = setTimeout(resolve, timeoutMs, false) })]) clearTimeout(timer) if (completed) return stalled.add(agent) void run.then(() => stalled.delete(agent)) rt.warn('ds-bot: capability mount for %s did not finish within %dms; continuing', sessionId, timeoutMs) } async function ensureCapabilities(sessionId) { await rt.load() const bot = botOfSession(sessionId) if (!bot) return if ((bot.capabilities ?? []).length === 0 && !mounts.get(agents.get(sessionId)?.deref())?.size) return let agent try { agent = await rt.resolveAgent(sessionId) } catch (error) { rt.warn('ds-bot: capability Agent for %s could not be resolved: %s', sessionId, rt.redactSecrets(String(error))) return } trackAgent(agent) await prepare(agent, sessionId) } const trackAgent = agent => { const sessionId = agent?.session?.id if (typeof sessionId !== 'string' || !agent.ctx) return if (agents.get(sessionId)?.deref() === agent) return agents.set(sessionId, new WeakRef(agent)) agent.ctx.effect(() => () => { if (agents.get(sessionId)?.deref() === agent) agents.delete(sessionId) clearSession(sessionId) for (const mount of mounts.get(agent)?.values() ?? []) void disposeMount(mount) mounts.delete(agent) }, `ds-bot: capabilities ${sessionId}`) } const trackBotAgents = async bot => { const sessionIds = new Set() try { const sessionId = rt.chatOf(bot.id) if (typeof sessionId === 'string') sessionIds.add(sessionId) } catch (error) { rt.warn('ds-bot: capability chat session for %s could not be read: %s', bot.id, error) } try { for (const sessionId of rt.groupSessionsOf(bot.id) ?? []) { if (typeof sessionId === 'string') sessionIds.add(sessionId) } } catch (error) { rt.warn('ds-bot: capability group sessions for %s could not be read: %s', bot.id, error) } for (const sessionId of sessionIds) { try { trackAgent(await rt.resolveAgent(sessionId)) } catch (error) { rt.warn('ds-bot: capability Agent for %s could not be resolved: %s', sessionId, error) } } } async function capabilityEndpoint(endpoint, body = {}) { if (endpoint === 'capability-save') return capabilitySave(body, { ui: true }) if (endpoint === 'capability-delete') return capabilityDelete(body.name, { ui: true }) if (endpoint === 'capability-approve') { await rt.load() writeCheck() const item = own(library(), String(body.name ?? '')) if (!item || item.kind !== 'mcp' || item.transport !== 'stdio') throw new Error(`No unapproved stdio MCP named ${body.name}.`) item.approved = true item.updatedAt = Date.now() await rt.save() return item } if (endpoint === 'bot-capability') { await rt.load() writeCheck() const bot = rt.botOf(String(body.botId ?? '')) if (!bot) throw new Error('Unknown Bot') const name = String(body.name ?? '') if (!own(library(), name)) throw new Error(`No capability named ${name}.`) return setAttached(bot, name, body.attached === true) } throw new Error('Unknown capability operation.') } const secretsChanged = rt.secretsChanged rt.secretsChanged = () => { secretsChanged?.() if (loadingSecrets === 0) void scheduleReconcile() } rt.capabilitiesStateSaved = () => { void scheduleReconcile() } // Creation waits for these listeners, so a new Agent's first request already has its // tools and skill catalog. agent/pre-step is too late: a step assembles its tools first. ctx.on('agent/created', async function prepareCapabilities({ agent }) { trackAgent(agent) try { await rt.load() const bot = botOfSession(agent.session.id) if ((bot?.capabilities ?? []).length > 0) await prepare(agent, agent.session.id) } catch (error) { rt.warn('ds-bot: capability load failed: %s', error) } }) ctx.effect(() => { void rt.load().then(async () => { for (const bot of Object.values(state.bots)) { if ((bot.capabilities ?? []).length > 0) await trackBotAgents(bot) } await scheduleReconcile() }).catch(error => rt.warn('ds-bot: capability startup failed: %s', error)) return async () => { stopped = true const live = [...mounts.values()] mounts.clear() agents.clear() sessionStatuses.clear() await Promise.all(live.flatMap(agentMounts => [...agentMounts.values()].map(disposeMount))) } }, 'ds-bot: capabilities') Object.assign(rt, { capabilitySave, capabilityDelete, dropOrphanCapabilities, capabilityEndpoint, capabilityLibraryView: libraryView, capabilityStatusesView, reconcileCapabilities: reconcile, scheduleCapabilitiesReconcile: scheduleReconcile, ensureCapabilities, expandCapabilities: names => expandCapabilityNames(names, library()), changeCapabilityAttachment: changeAttachment, }) }