dsh-sansheng-liubu/ds-bot/src/host/capabilities.js

546 lines
23 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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__<id>__* 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,
})
}