A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.
// Client channel: the team view the browser renders, and the POST /api/bot endpoints.
import { randomUUID } from 'node:crypto'
import { createUserMessage } from '@deepseek-ai/dsh-llm'
import { install as installBtw } from './btw.js'
import { install as installSide } from './side.js'
import { handoffReply, questionReply, viewReply } from './parts.js'
import { validateViewAnswer } from 'deep-view/core'
import { COLORS, EXTRA_COLORS, ROUTE } from './constants.js'
const LANGUAGES = { zh: 'Chinese (简体中文)', en: 'English' }
const RUN_STATS = ['sessionStats', 'tokenUsage', 'contextPressure']
const invalid = message => Object.assign(new Error(message), { code: 'bot/invalid' })
// Programming and file system errors are DS Bot's own faults, logged with their stack;
// any other error is a refusal whose message is meant for the user.
const isInternal = error => error instanceof TypeError || error instanceof ReferenceError || error instanceof RangeError
|| error instanceof SyntaxError || (typeof error?.code === 'string' && /^E[A-Z_]+$/.test(error.code))
export function errorCode(error) {
if (typeof error?.code === 'string' && error.code.startsWith('bot/')) return error.code
return isInternal(error) ? 'bot/internal' : 'bot/refused'
}
export function install(rt) {
installBtw(rt)
installSide(rt)
const { ctx, state } = rt
// The DSH interface language of the last browser that asked for the team.
let uiLocale
rt.uiLanguage = () => (uiLocale === undefined ? undefined : LANGUAGES[uiLocale.split('-')[0].toLowerCase()] ?? uiLocale)
const ok = value => ({ ok: true, value })
const fail = (message, code = 'bot/error') => ({ ok: false, error: { code, message, details: {} } })
// Models come from DSH, not state.json, so a provider added in Harness settings
// changes the view without a new revision.
const modelsKey = () => `${rt.cachedCatalog().map(entry => `${entry.ref}${entry.needsKey ? '!' : ''}${entry.reasoning ? `:${JSON.stringify(entry.reasoning)}` : ''}`).join(',')}|${rt.cachedDefault() ?? ''}`
const view = () => ({
revision: state.revision,
workspaceId: state.workspaceId ?? null,
// `mainBotId` is the first Main Bot, which the sidebar shows as its tile.
mainBotId: state.mainBotIds[0] ?? null,
mainBotIds: state.mainBotIds,
// `sessionId` is the Bot's current own-chat part; `parts` its earlier ones.
// `waiting`: the Bot holds its greeting until the user picks its model or fixes
// what failed it. `blocked`: the facts of a failure only the user can fix (turns.js).
bots: Object.values(state.bots).map(({ segments, kickoff, ...bot }) => ({
...bot, sessionId: rt.chatOf(bot.id), parts: (segments ?? []).map(segment => segment.sessionId), ...(kickoff ? { waiting: true } : {}),
// `engine` is the Bot's local-agent route, present only on abots.
...(rt.localAgentBadge?.(bot.appliedModel ?? bot.model) !== undefined ? { engine: rt.localAgentBadge(bot.appliedModel ?? bot.model) } : {}),
})),
// `sessionId` is the group's own Session's current part, `ownParts` its earlier
// ones; `parts` the members' hidden group Sessions and their earlier segments,
// for usage.
rooms: Object.values(state.rooms).map(({ log, seen, paused, sessions, segments, parts: ownParts, ...room }) => {
const parts = [...Object.values(sessions ?? {}), ...Object.values(segments ?? {}).flat().map(segment => segment.sessionId), ...(ownParts ?? []).map(segment => segment.sessionId)]
const last = (log ?? []).filter(line => line.kind === undefined).at(-1)
return { ...room, sessionId: rt.sessionOfRoom(room), ownParts: (ownParts ?? []).map(segment => segment.sessionId), parts, ...(last ? { preview: last.who === 'User' ? last.text : `${last.who}:${last.text}` } : {}) }
}),
// Deleted private Bots whose folder, memory and chats stay closed to the others.
privateArchives: rt.archivesView(),
exchangeTurns: state.exchangeTurns,
questions: state.questions,
views: state.views ?? {},
closedCards: state.closedCards ?? {},
// Aside answers of each Bot's current part, newest first. Not part of the
// model-visible history; earlier parts send their cards on their own pages.
btwCards: rt.btwView?.() ?? {},
// Each Bot's side chats, in creation order. The answers never join the
// model-visible history; the side panel reads them here.
sideChats: rt.sideView?.() ?? {},
// The team's DSH Agent (at most one): plain dsh Sessions, not Bots.
agents: Object.values(state.agents),
// Key names and who may use them; values never leave the host.
secrets: rt.secretsView(),
capabilities: rt.capabilityLibraryView(),
secretRequests: state.secretRequests ?? {},
connectorRequests: state.connectorRequests ?? {},
mailRequests: state.mailRequests ?? {},
colors: [...COLORS, ...EXTRA_COLORS],
models: rt.cachedCatalog(),
defaultModel: rt.cachedDefault() ?? null,
permissions: rt.permissionCatalog?.() ?? null,
modelsKey: modelsKey(),
prefs: state.prefs,
// Whether a Desktop window should serve Bot browser reads (see browser.js).
browser: rt.browserEnabled,
// False when config.memory turns memory off: no Memory row or panel.
memory: rt.memoryEnabled !== false,
// Set while another dsh host holds the team (store.js): why this one cannot change it.
readOnly: rt.readOnly() ?? null,
// IM connections (settings → IM): one per chat-app bot the user added.
im: rt.imView?.() ?? { connections: [], platforms: [] },
// The computer-use switch, the provider it mounts, and each Bot's level and app grants.
computer: rt.computerView?.() ?? { enabled: false },
})
// What changes without a new revision, sent with every state answer. `learning`:
// each Bot's pending skill proposals; `learningSettled`: the answered ones of its
// current chat part. `memoryNews`:
// per Bot or group chat, its latest memory change; `memoryReviews`: memory reviews waiting or
// running; `work`: per Bot, the turn it runs and its tool; per group, the members whose
// turn there runs; the approvals waiting; per Bot, who it waits for to hand back work;
// and per Session, when its running turn began.
const live = () => ({
activity: rt.activityView(),
work: { bots: rt.workView(), rooms: rt.roomWorkView(), approvals: rt.approvalsView(), waiting: rt.waitingView?.() ?? {}, turns: rt.turnsView?.() ?? {}, steered: rt.steeredView?.() ?? {} },
memoryNews: rt.memoryNews(),
memoryReviews: rt.memoryReviews(),
learning: rt.learningView(),
learningSettled: rt.learningSettledView(),
connectors: rt.connectorsView(),
capabilityStatuses: rt.capabilityStatusesView(),
imStatus: rt.imStatusView?.() ?? {},
imVia: rt.imViaView?.() ?? {},
// Computer use live state: per-Bot control, leases, pending app cards and holds.
// Named apart from the state view's `computer`: the live answer merges into the
// same object and would wipe its `enabled` and `provider` fields.
computerLive: rt.computerLive?.() ?? {},
})
// The live fields' sources are spread across the host with no single change
// counter, so the serialized answer itself is the detector: a poll whose `live`
// still names it gets only the key back, not the fields again. The key carries
// a per-run prefix: a window can outlive the host, and a counter that restarts
// at 1 would let its stale key name a different answer.
const liveRun = randomUUID()
let liveSeq = 0
let liveCache = null
const liveAnswer = () => {
const value = live()
const json = JSON.stringify(value)
if (liveCache?.json === json) return liveCache
return liveCache = { key: `${liveRun}:${++liveSeq}`, value, json }
}
// What a host that only reads the team may still answer.
// Updates change the dsh profile, not the team, so a reading host may run them too.
const READS = new Set(['state', 'models', 'efforts', 'providers', 'provider-models', 'earlier', 'chat', 'run-stats', 'room-progress', 'exchange', 'exchange-text', 'file-text', 'usage', 'schedules', 'memory-view', 'browser-wait', 'browser-result', 'diagnostics', 'diagnostics-log', 'diagnostics-clear', 'update-check', 'update-install', 'dsh-update-install', 'repo-stars', 'approval-answer', 'thinking', 'avatar-library', 'computer-system-status', 'computer-shot', 'local-agents'])
async function setPrefs(body) {
if (body.theme !== undefined) {
if (typeof body.theme !== 'string' || !/^[a-z][\w-]{0,31}$/.test(body.theme)) throw invalid('Unknown theme')
state.prefs.theme = body.theme
}
if (body.accent !== undefined) {
if (body.accent === null || body.accent === '') delete state.prefs.accent
else if (/^#[0-9a-f]{6}$/i.test(body.accent)) state.prefs.accent = body.accent
else throw invalid('Accent must be a #rrggbb color')
}
if (body.motion !== undefined) {
if (body.motion === null || body.motion === 'normal') delete state.prefs.motion
else if (body.motion === 'quiet' || body.motion === 'lively') state.prefs.motion = body.motion
else throw invalid('Motion must be quiet, normal or lively')
}
if (body.layout !== undefined) {
if (body.layout === null || body.layout === 'bubble') delete state.prefs.layout
else if (body.layout === 'flat') state.prefs.layout = body.layout
else throw invalid('Layout must be bubble or flat')
}
if (body.width !== undefined) {
if (body.width === null || body.width === 80) delete state.prefs.width
else if (Number.isInteger(body.width) && body.width >= 50 && body.width <= 100) state.prefs.width = body.width
else throw invalid('Width must be a whole percent from 50 to 100')
}
if (body.flatWidth !== undefined) {
if (body.flatWidth === null || body.flatWidth === 100) delete state.prefs.flatWidth
else if (Number.isInteger(body.flatWidth) && body.flatWidth >= 50 && body.flatWidth <= 100) state.prefs.flatWidth = body.flatWidth
else throw invalid('Flat text width must be a whole percent from 50 to 100')
}
if (body.defaultBotModel !== undefined) {
// The model new Bots start on when a create names none. It resolves now, so the
// saved ref is one the catalog served at save time; a create still re-checks it.
if (body.defaultBotModel === null || body.defaultBotModel === '') delete state.prefs.defaultBotModel
else state.prefs.defaultBotModel = await rt.resolveModel(body.defaultBotModel)
}
if (body.thinking !== undefined) {
// A value this version does not know is ignored, not refused: the toggle
// may grow more states later.
if (body.thinking === true) state.prefs.thinking = true
else if (body.thinking === false || body.thinking === null) delete state.prefs.thinking
}
if (body.enterToSend !== undefined) {
if (body.enterToSend === false) state.prefs.enterToSend = false
else if (body.enterToSend === true || body.enterToSend === null) delete state.prefs.enterToSend
}
return rt.save()
}
const handle = async (endpoint, payload, signal) => {
try {
const body = payload ?? {}
await rt.refresh()
const readOnly = rt.readOnly()
if (readOnly !== undefined && !READS.has(endpoint)) return fail(readOnly, 'bot/read-only')
switch (endpoint) {
case 'state': {
if (typeof body.locale === 'string' && /^[a-z]{2,3}(-[\w-]+)?$/i.test(body.locale)) uiLocale = body.locale
if (readOnly === undefined) await rt.bootstrap()
await rt.catalog()
await rt.loadSecrets()
const answer = liveAnswer()
if (body.since === state.revision && (body.models === undefined || body.models === modelsKey())) {
if (body.live === answer.key) return ok({ revision: state.revision, unchanged: true, liveKey: answer.key })
return ok({ revision: state.revision, unchanged: true, liveKey: answer.key, ...answer.value })
}
return ok({ ...view(), liveKey: answer.key, ...answer.value })
}
case 'models':
await rt.catalog({ fresh: true })
return ok({ modelsKey: modelsKey() })
case 'efforts':
return ok(await rt.reasoningOf(String(body.ref ?? '')) ?? { efforts: [] })
// A Turn's exact thinking time, from the timed stream in its events; `ms`
// omitted when the stream carries no reasoning records.
case 'thinking': {
const sessionId = String(body.sessionId ?? '')
const turn = Number(body.turn)
if (!Number.isFinite(turn) || rt.selfOf(sessionId) === undefined) return ok(null)
await rt.load()
const ms = await rt.thinkingOf(sessionId, turn)
return ok(ms === undefined ? {} : { ms })
}
// Model providers and their keys, for a window without DSH's own Models page.
case 'providers':
return ok(await rt.providersView())
case 'provider-key':
if (body.value === null) await rt.clearProviderKey(String(body.provider ?? ''))
else await rt.setProviderKey(String(body.provider ?? ''), body.value)
return ok(await rt.providersView())
case 'provider-add':
return ok(await rt.addProvider(body))
case 'provider-models':
return ok(await rt.discoverModels(body))
case 'provider-remove':
return ok(await rt.removeProvider(String(body.provider ?? '')))
case 'duplicate-bot':
await rt.load()
return ok(await rt.duplicateBot(body.id))
case 'set-prefs':
await rt.load()
await setPrefs(body)
return ok(state.prefs)
case 'exchange': {
await rt.load()
const pair = new Set([body.a, body.b])
return ok(state.exchanges.filter(entry => pair.has(entry.from) && pair.has(entry.to)))
}
case 'exchange-text': {
await rt.load()
const entry = state.exchanges.find(item => item.id === body.id)
if (entry === undefined) return fail('This message is no longer kept', 'bot/stale')
return ok(await rt.exchangeText(entry))
}
// A long Bot post's file (attachLong), for the group chat's "Show all".
case 'file-text': {
if (typeof body.file?.attachmentId !== 'string') return fail('No file named', 'bot/invalid')
const read = await rt.fileText(body.file)
return read === undefined ? fail('This file cannot be read here', 'bot/unavailable') : ok(read)
}
case 'earlier':
await rt.load()
return ok(await rt.earlierPage(String(body.sessionId ?? ''), body.cursor ?? undefined))
case 'chat':
await rt.load()
return ok(await rt.chatPage(String(body.botId ?? ''), body.cursor ?? undefined))
// DSH's own whole-log figures for the current part of a Bot's chat, the ones its
// status bar shows; a window without that bar shows them in the Bot's details.
case 'run-stats': {
await rt.load()
const bot = rt.botOf(String(body.botId ?? ''))
if (bot === undefined) return fail('Unknown Bot', 'bot/not-found')
const projections = ctx.get?.('sessionProjections')
if (projections === undefined) return ok(null)
const agent = await rt.resolveAgent(rt.chatOf(bot.id))
return ok(projections.snapshot(agent.session, RUN_STATS).values)
}
case 'usage':
await rt.load()
return ok(await rt.usageView({ timeZone: typeof body.timeZone === 'string' ? body.timeZone.slice(0, 64) : undefined }))
case 'room-progress': {
// Any part id of the group's own Session means the group itself.
const room = rt.roomOf(body.roomId) ?? rt.roomOf(rt.pastOwners.get(body.roomId)?.roomId)
return ok([...rt.roomProgress.entries()].filter(([, entry]) => entry.roomId === (room?.id ?? body.roomId)).map(([callId, entry]) => ({ callId, replies: entry.replies, speaking: entry.slots.filter(slot => slot.status === 'speaking').map(slot => slot.id) })))
}
case 'create-bot': {
await rt.bootstrap()
const bot = await rt.createBot({ name: body.name, role: body.role, color: body.color, instructions: body.instructions, brief: body.brief, avatar: body.avatar, model: body.model, effort: body.effort, workDir: body.workDir })
return ok(bot)
}
case 'update-bot':
await rt.load()
return ok(await rt.updateBot(body.id, body))
// The repair card's Retry, once the user fixed what failed the Bot's turn.
case 'resume': {
await rt.load()
const bot = rt.botOf(String(body.botId ?? ''))
if (bot === undefined) return fail('Unknown Bot', 'bot/not-found')
await rt.resumeBot(bot)
return ok(true)
}
// The avatar library: photos the user imported once, kept beside the team.
case 'avatar-library':
await rt.load()
return ok(await rt.avatarLibraryView({ offset: body.offset, limit: body.limit }))
case 'avatar-import':
await rt.load()
return ok(await rt.avatarLibraryImport(Array.isArray(body.items) ? body.items : []))
case 'avatar-delete':
await rt.load()
return ok(await rt.avatarLibraryDelete(String(body.id ?? '')))
case 'delete-bot':
await rt.load()
await rt.deleteBot(body.id)
return ok(view())
case 'private-release':
await rt.load()
await rt.releaseArchive(String(body.id ?? ''))
return ok(view())
case 'set-main':
await rt.load()
await rt.setMain(body.id, body.main !== false, {
primary: body.primary === true,
replace: typeof body.replace === 'string' ? body.replace : undefined,
})
return ok(view())
case 'create-room': {
await rt.load()
const room = await rt.createRoom({ members: Array.isArray(body.members) ? body.members : [], name: body.name, ...(typeof body.admin === 'string' ? { admin: body.admin } : {}) })
if (body.greet === true) await rt.greetRoom(room.id).catch(error => rt.warn('ds-bot: greeting in %s failed: %s', room.name, error))
return ok(room)
}
case 'update-room': {
await rt.load()
const { room, changes } = await rt.updateRoom(body.id, {
name: body.name,
notice: body.notice,
mode: body.mode,
admin: body.admin,
members: Array.isArray(body.members) ? body.members : undefined,
add: Array.isArray(body.add) ? body.add : undefined,
remove: Array.isArray(body.remove) ? body.remove : undefined,
workDir: body.workDir,
permission: body.permission,
})
return ok({ room: view().rooms.find(entry => entry.id === room.id), changes })
}
case 'folders':
case 'folder-pick':
case 'folder-list':
await rt.load()
return ok(await rt.folderEndpoint(endpoint, body, signal))
case 'team-workspace':
await rt.load()
return ok({ team: await rt.setTeamWorkspace(String(body.path ?? '')) })
case 'add-agent':
await rt.load()
return ok(await rt.addAgent())
case 'agent-session':
await rt.load()
return ok({ sessionId: await rt.createAgentSession(body.agentId, body.workspaceId) })
case 'agent-adopt':
await rt.load()
return ok({ sessionId: await rt.adoptAgentSession(body.agentId, body.sessionId) })
case 'agent-archive':
await rt.load()
await rt.archiveAgentSession(body.agentId, body.sessionId)
return ok(true)
case 'agent-rename':
await rt.load()
await rt.renameAgentSession(body.agentId, body.sessionId, body.title)
return ok(true)
case 'remove-agent':
await rt.load()
await rt.removeAgent(body.agentId)
return ok(view())
case 'set-flags':
await rt.load()
return ok(await rt.setFlags(body.id, body))
case 'delete-room':
await rt.load()
await rt.deleteRoom(body.id)
return ok(view())
case 'approval-answer':
rt.answerApproval(body.id, body.choice)
return ok(true)
// A stop that fails partway still parks the goal, or it wakes the admin again.
case 'stop-member-work':
try {
return ok(await rt.stopMemberWork(String(body.roomId ?? ''), String(body.botId ?? '')))
} finally {
rt.goalUserStopped?.(String(body.roomId ?? ''))
}
case 'stop-room-work':
try {
return ok(await rt.stopRoomWork(String(body.roomId ?? '')))
} finally {
rt.goalUserStopped?.(String(body.roomId ?? ''))
}
case 'goal-draft': {
await rt.load()
const result = await rt.goalDraft(String(body.roomId ?? ''), body.text)
return result.error !== undefined ? fail(result.error, result.code ?? 'bot/refused') : ok(view())
}
case 'goal-control': {
await rt.load()
const result = await rt.goalControl(String(body.roomId ?? ''), body)
return result.error !== undefined ? fail(result.error, result.code ?? 'bot/refused') : ok(view())
}
case 'dismiss-question':
await rt.load()
if (rt.own(state.questions, body.sessionId) !== undefined) {
rt.closeCard(body.sessionId, state.questions[body.sessionId], 'dismissed')
delete state.questions[body.sessionId]
await rt.save()
}
return ok(true)
case 'dismiss-view':
await rt.load()
if (rt.own(state.views, body.sessionId) !== undefined) {
rt.closeCard(body.sessionId, state.views[body.sessionId], 'dismissed')
delete state.views[body.sessionId]
await rt.save()
}
return ok(true)
case 'secret-set':
case 'secret-allow':
case 'secret-cancel':
case 'secret-update':
case 'secret-delete':
await rt.load()
return ok(await rt.secretEndpoint(endpoint, body))
case 'connector-connect':
case 'connector-disconnect':
case 'connector-retry':
case 'connector-sign-in-code':
case 'connector-cancel':
case 'connector-client':
case 'connector-set':
case 'connector-add':
case 'connector-remove':
case 'connector-import-scan':
case 'connector-import':
case 'connector-request-cancel':
case 'mail-account-add':
case 'mail-account-remove':
case 'mail-rule-set':
case 'mail-send-answer':
case 'mail-sign-in-code':
await rt.load()
return ok(await rt.connectorEndpoint(endpoint, body))
case 'capability-save':
case 'capability-delete':
case 'capability-approve':
case 'bot-capability':
await rt.load()
return ok(await rt.capabilityEndpoint(endpoint, body))
case 'schedules':
case 'schedule-create':
case 'schedule-delete':
await rt.load()
return ok(await rt.scheduleEndpoint(endpoint, body))
case 'memory-view':
case 'memory-ask':
case 'memory-forget':
case 'memory-history':
case 'memory-restore':
await rt.load()
return ok(await rt.memoryEndpoint(endpoint, body))
case 'learning-answer':
await rt.load()
return ok(await rt.learningEndpoint(endpoint, body))
case 'answer-question': {
if (typeof body.sessionId !== 'string') return fail('Nothing to send', 'bot/invalid')
await rt.load()
return ok(await rt.answerQuestion(body.sessionId, body.questionId, body.answer))
}
case 'view-reply': {
if (typeof body.sessionId !== 'string') return fail('Nothing to send', 'bot/invalid')
await rt.load()
const past = rt.pastOwners.get(body.sessionId)
const sessionId = rt.botOf(body.sessionId) ? rt.chatOf(body.sessionId) : past && past.roomId === undefined ? rt.chatOf(past.botId) : body.sessionId
const pending = rt.own(state.views, sessionId)
if (pending === undefined || pending.id !== body.viewId) return fail('This view is no longer open', 'bot/stale')
const checked = validateViewAnswer(pending.view, body.action, body.values)
if (checked.error !== undefined) return fail(checked.error, 'bot/invalid')
const reply = viewReply(pending, body.action, body.values)
if (reply === undefined) return fail('Nothing to send', 'bot/invalid')
// Claim the view before queueing so a second answer is refused.
delete state.views[sessionId]
try {
await rt.ensureCapabilities(sessionId)
const agent = await rt.resolveAgent(sessionId)
agent.followup(createUserMessage({ content: [{ type: 'text', text: reply.text }], source: reply.source }))
await ctx.sessions.flush(agent.session)
} catch (error) {
state.views[sessionId] ??= pending
throw error
}
await rt.save()
return ok(true)
}
case 'send': {
const text = String(body.text ?? '').trim()
if (text === '' || typeof body.sessionId !== 'string') return fail('Nothing to send', 'bot/invalid')
await rt.load()
await rt.sendUser({ sessionId: body.sessionId, content: [{ type: 'text', text }] })
return ok(true)
}
case 'btw-delete': {
if (typeof body.sessionId !== 'string' || body.sessionId === '' || typeof body.cardId !== 'string' || body.cardId === '') return fail('Nothing to delete', 'bot/invalid')
await rt.load()
return ok(await rt.btwDelete({ sessionId: body.sessionId, cardId: body.cardId }))
}
// Side chats in the Bot's panel: each question is an aside on a fresh
// snapshot of this Bot's private chat; the earlier finished pairs of
// that chat ride along. Nothing is written into the Session.
case 'side-new': {
if (typeof body.sessionId !== 'string' || body.sessionId === '') return fail('Nothing to open', 'bot/invalid')
await rt.load()
return ok(await rt.sideNew({ sessionId: body.sessionId }))
}
case 'side-ask': {
if (typeof body.sessionId !== 'string' || body.sessionId === '') return fail('Nothing to ask', 'bot/invalid')
if (body.chatId !== undefined && typeof body.chatId !== 'string') return fail('Nothing to ask', 'bot/invalid')
if (String(body.text ?? '').trim() === '') return fail('Write a question.', 'bot/invalid')
await rt.load()
return ok(await rt.sideAsk({ sessionId: body.sessionId, chatId: body.chatId, recent: body.recent === true, text: String(body.text) }))
}
case 'side-cancel': {
if (typeof body.chatId !== 'string' || body.chatId === '' || typeof body.entryId !== 'string' || body.entryId === '') return fail('Nothing to cancel', 'bot/invalid')
await rt.load()
return ok(await rt.sideCancel({ chatId: body.chatId, entryId: body.entryId }))
}
case 'side-close': {
if (typeof body.chatId !== 'string' || body.chatId === '') return fail('Nothing to close', 'bot/invalid')
await rt.load()
return ok(await rt.sideClose({ chatId: body.chatId }))
}
case 'update-check': {
const fresh = body.fresh === true
return ok({ ...(await rt.updateCheck({ fresh })), dsh: (await rt.dshUpdateCheck?.({ fresh })) ?? null })
}
case 'update-install':
return ok(rt.updateStart())
case 'dsh-update-install':
return ok(rt.dshUpdateStart?.())
case 'repo-stars':
return ok(await rt.repoStars())
// The Desktop window's long poll for read_browser, and its answers.
case 'browser-wait': {
if (rt.browserChannel === undefined) return fail('Bot browsers are off on this host', 'bot/browser-off')
const clientId = typeof body.clientId === 'string' ? body.clientId.slice(0, 100) : ''
if (clientId === '') return fail('A browser poll needs a clientId', 'bot/invalid')
await rt.load()
const requests = await rt.browserChannel.wait(clientId, rt.browserOpen(body.open))
return ok({ requests, holds: rt.browserChannel.holdSnapshot() })
}
case 'browser-result':
if (rt.browserChannel === undefined) return fail('Bot browsers are off on this host', 'bot/browser-off')
return ok(rt.browserChannel.result(body))
case 'browser-takeover': {
if (rt.browserChannel === undefined) return fail('Bot browsers are off on this host', 'bot/browser-off')
await rt.load()
const botId = String(body.botId ?? '')
if (!rt.botOf(botId)) return fail('Unknown Bot', 'bot/not-found')
// Taking over a handoff keeps its reason, note, and call, so its card stays up.
const asked = rt.browserChannel.holdOf(botId)
rt.browserChannel.setHold(botId, asked?.callId !== undefined
? { by: 'user', reason: asked.reason, note: asked.note, callId: asked.callId }
: { by: 'user', reason: 'takeover', note: 'The user is controlling this browser.' })
return ok(true)
}
// A card's 'done' or 'skip' says how the handoff went. The panel's Give back
// sends no outcome, so its reply only says that control returned to the Bot.
case 'browser-give-back': {
if (rt.browserChannel === undefined) return fail('Bot browsers are off on this host', 'bot/browser-off')
await rt.load()
const botId = String(body.botId ?? '')
if (!rt.botOf(botId)) return fail('Unknown Bot', 'bot/not-found')
if (body.outcome !== undefined && !['done', 'skip', 'returned'].includes(body.outcome)) return fail('Nothing to send', 'bot/invalid')
const hold = rt.browserChannel.holdOf(botId)
if (hold === null) return fail('This browser is not held', 'bot/forbidden')
if (body.callId !== undefined && body.callId !== hold.callId) return fail('This handoff is no longer open', 'bot/stale')
// Claim the hold before queueing so a second answer is refused.
rt.browserChannel.setHold(botId, null)
if (hold.callId === undefined) return ok(true)
try {
const sessionId = rt.chatOf(botId)
const reply = handoffReply(hold, body.outcome)
await rt.ensureCapabilities(sessionId)
const agent = await rt.resolveAgent(sessionId)
agent.followup(createUserMessage({ content: [{ type: 'text', text: reply.text }], source: reply.source }))
await ctx.sessions.flush(agent.session)
} catch (error) {
if (rt.browserChannel.holdOf(botId) === null) rt.browserChannel.setHold(botId, hold)
throw error
}
return ok(true)
}
case 'browser-stop': {
await rt.load()
const botId = String(body.botId ?? '')
if (!rt.botOf(botId)) return fail('Unknown Bot', 'bot/not-found')
const sessionId = rt.chatOf(botId)
if (sessionId && rt.live.get(sessionId)?.turn !== undefined) {
const agent = await rt.resolveAgent(sessionId)
agent.cancel({ kind: 'user' })
}
for (const room of Object.values(rt.state.rooms ?? {})) {
if (room.members?.includes(botId)) await rt.stopMemberWork?.(room.id, botId)
}
rt.browserChannel?.setHold(botId, { by: 'user', reason: 'stopped', note: 'The user is controlling this browser.' })
return ok(true)
}
case 'im-add':
case 'im-update':
case 'im-remove':
case 'im-pair':
case 'im-unpair':
case 'im-chat':
case 'im-retry':
case 'im-login-start':
case 'im-login-wait':
await rt.load()
return ok(await rt.imEndpoint(endpoint, body))
case 'local-agents':
case 'local-agent-refresh':
case 'local-agent-add':
case 'local-agent-update':
case 'local-agent-remove':
await rt.load()
return ok(await rt.localAgentsEndpoint(endpoint, body))
// "New session" and "open an earlier session" on an abot's chat: ordinary
// parts moves (parts.js), the same mechanism every Bot's chat uses.
case 'bot-new-part': {
await rt.load()
const bot = rt.botOf(String(body.botId ?? ''))
if (bot === undefined) return fail('Unknown Bot', 'bot/not-found')
return ok(await rt.newPart(rt.chatOf(bot.id)))
}
case 'bot-open-part': {
await rt.load()
const bot = rt.botOf(String(body.botId ?? ''))
if (bot === undefined) return fail('Unknown Bot', 'bot/not-found')
return ok(await rt.switchPart(bot.id, String(body.sessionId ?? '')))
}
case 'diagnostics':
await rt.load()
return ok(await rt.diagnostics.report(body))
case 'diagnostics-log':
return ok(await rt.diagnostics.logText())
case 'diagnostics-clear':
await rt.diagnostics.clear()
return ok(true)
default:
if (endpoint.startsWith('computer-')) {
await rt.load()
return ok(await rt.computerEndpoint(endpoint.slice('computer-'.length), body))
}
return fail(`Unknown endpoint ${endpoint}`, 'bot/not-found')
}
} catch (error) {
const code = errorCode(error)
const message = error?.message ?? String(error)
if (code === 'bot/internal') rt.noteFailure({ source: 'api', text: `${endpoint}: ${message}`, code: error?.code ?? error?.name, stack: error?.stack })
return fail(message, code)
}
}
// How a user message reaches a Session: a Bot id, a group chat's id, or an earlier
// part of either resolves to its current part. `content` is the prompt blocks DSH
// takes (text, image, file receipts); `requestId` lands on the message's source.
async function sendUser({ sessionId: ref, content, requestId = randomUUID() }) {
const past = rt.pastOwners.get(ref)
const room = rt.roomOf(ref)
const sessionId = rt.botOf(ref) ? rt.chatOf(ref)
: room !== undefined ? rt.sessionOfRoom(room)
: past?.roomId === undefined && past !== undefined ? rt.chatOf(past.botId)
: past !== undefined ? rt.sessionOfRoom(rt.roomOf(past.roomId)) : ref
await rt.ensureCapabilities(sessionId)
await ctx.sessionController.prompt({
requestId,
sessionId,
mode: 'queue',
content,
}, AbortSignal.timeout(30_000))
}
// The user's answer to an ask_user card, from the web or an IM chat. A Bot id or an
// earlier part of its own chat means the current one.
async function answerQuestion(sessionRef, questionId, answer) {
const past = rt.pastOwners.get(sessionRef)
const sessionId = rt.botOf(sessionRef) ? rt.chatOf(sessionRef) : past && past.roomId === undefined ? rt.chatOf(past.botId) : sessionRef
const question = rt.own(state.questions, sessionId)
if (question === undefined || question.id !== questionId) throw Object.assign(new Error('This question is no longer open'), { code: 'bot/stale' })
const reply = questionReply(question, answer)
if (reply === undefined) throw Object.assign(new Error('Nothing to send'), { code: 'bot/invalid' })
// Claim the question before queueing so a second answer is refused.
delete state.questions[sessionId]
try {
await rt.ensureCapabilities(sessionId)
const agent = await rt.resolveAgent(sessionId)
agent.followup(createUserMessage({ content: [{ type: 'text', text: reply.text }], source: reply.source }))
await ctx.sessions.flush(agent.session)
} catch (error) {
state.questions[sessionId] ??= question
throw error
}
await rt.save()
return true
}
Object.assign(rt, { sendUser, answerQuestion })
// An exact Fetch route on the shared /api channel; the browser authenticates with its session cookie.
ctx.effect(() => ctx.connection.fetch.register({
path: ROUTE,
methods: ['POST'],
requestBody: 'buffered',
fetch: async (request) => {
let body
try { body = await request.json() } catch { body = {} }
const result = await handle(String(body?.endpoint ?? ''), body?.payload, request.signal)
return new Response(JSON.stringify(result), { status: 200, headers: { 'content-type': 'application/json' } })
},
}), 'ds-bot: api route')
ctx.effect(() => {
void rt.load()
// Registered last, so this disposer runs before the state lock is released.
// In-flight side questions abort here; their entries stay answering for the
// next owner.
return () => Promise.all([rt.btwDispose?.(), rt.sideDispose?.()])
}, 'ds-bot: load state')
}