dsh-device-fleet 0.0.0-stage → 0.1.0-dev.10

package/src/host/direct-call.js

@@ -0,0 +1,209 @@
+// Direct-call host/client over the fleet RPC layer (ADR-0003, ADR-0004, ADR-0014).
+//
+// Host side runs on the resource-owner device: it applies Tool Policy, may ask
+// for local approval, then executes through the Execution Slot (or a direct fs
+// read for list/fetch). Client side runs on the caller device and backs the
+// `fleet_*` model tools.
+import { DEFAULT_SHELL_TOOL } from './execution-slot.js'
+
+const DEFAULT_POLICY_TIMEOUT_MS = 60_000
+
+function toolText(result) {
+  if (!result) return ''
+  if (result.isError) return `Error: ${result.text || 'tool failed'}`
+  return result.text ?? ''
+}
+
+export class DirectCallHost {
+  /**
+   * @param {object} options
+   * @param {object} options.slot ExecutionSlot
+   * @param {import('./tool-policy.js').ToolPolicy} options.policy
+   * @param {{resolve: Function, listDir: Function, stat?: Function, readText?: Function}} [options.fs]
+   * @param {(request: object) => Promise<boolean>} [options.requestApproval]
+   * @param {string} options.deviceId
+   * @param {string} [options.name]
+   * @param {string} [options.pluginVersion]
+   * @param {string} [options.dshVersion]
+   * @param {string[]} [options.capabilities]
+   * @param {string} [options.shellTool]
+   * @param {object} [options.delegation] DelegationHost for `fleet.delegate`
+   */
+  constructor({
+    slot,
+    policy,
+    fs,
+    requestApproval,
+    deviceId,
+    name = 'device',
+    pluginVersion = '0.0.0',
+    dshVersion = 'unknown',
+    capabilities = [],
+    shellTool = DEFAULT_SHELL_TOOL,
+    approvalTimeoutMs = DEFAULT_POLICY_TIMEOUT_MS,
+    delegation = null,
+  }) {
+    this.slot = slot
+    this.policy = policy
+    this.fs = fs
+    this.requestApproval = requestApproval
+    this.deviceId = deviceId
+    this.name = name
+    this.pluginVersion = pluginVersion
+    this.dshVersion = dshVersion
+    this.capabilities = capabilities
+    this.shellTool = shellTool
+    this.approvalTimeoutMs = approvalTimeoutMs
+    this.delegation = delegation
+  }
+
+  info() {
+    return {
+      deviceId: this.deviceId,
+      name: this.name,
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+      policy: this.policy.summarize(),
+    }
+  }
+
+  async handleRequest({ deviceId, method, params }) {
+    switch (method) {
+      case 'fleet.ping':
+        return { pong: true, deviceId: this.deviceId }
+      case 'fleet.info':
+        return this.info()
+      case 'fleet.tools':
+        return { deviceId: this.deviceId, tools: await this.slot.listTools(), policy: this.policy.summarize() }
+      case 'fleet.call':
+        return this.handleCall({ fromDeviceId: deviceId, request: params ?? {} })
+      case 'fleet.delegate':
+        if (!this.delegation) {
+          throw Object.assign(new Error('delegation is unavailable on this device'), { code: 'unsupported' })
+        }
+        return this.delegation.delegate({ fromDeviceId: deviceId, request: params ?? {} })
+      default:
+        throw Object.assign(new Error(`unknown fleet method: ${String(method)}`), { code: 'unknown-method' })
+    }
+  }
+
+  async handleCall({ fromDeviceId, request }) {
+    const capability = request.capability ?? 'tool'
+    const tool = request.tool ?? null
+    const args = request.args ?? {}
+    const decision = this.policy.decide({ capability, tool, args })
+    if (decision.decision === 'deny') {
+      throw Object.assign(new Error(decision.reason), { code: 'denied', data: { capability, tool } })
+    }
+    if (decision.decision === 'ask') {
+      const outcome = await this.askApproval({ fromDeviceId, capability, tool, args, reason: decision.reason })
+      if (outcome.approved !== true) {
+        throw Object.assign(new Error(outcome.reason ?? 'local approval was not granted'), { code: 'approval_denied' })
+      }
+      this.policy.grant(decision.key, { scope: outcome.scope === 'ttl' ? 'ttl' : 'once' })
+    }
+    const startedAt = Date.now()
+    const result = await this.execute({ capability, tool, args })
+    return {
+      ...result,
+      meta: {
+        ...(result.meta ?? {}),
+        capability,
+        tool,
+        deviceId: this.deviceId,
+        durationMs: Date.now() - startedAt,
+      },
+    }
+  }
+
+  async askApproval({ fromDeviceId, capability, tool, args, reason }) {
+    if (typeof this.requestApproval !== 'function') return { approved: false, reason: 'no approval channel' }
+    try {
+      const outcome = await this.requestApproval({ fromDeviceId, capability, tool, args, reason })
+      if (outcome === true) return { approved: true, scope: 'once' }
+      if (outcome && typeof outcome === 'object') {
+        return { approved: outcome.approved === true, scope: outcome.scope ?? 'once', reason: outcome.reason }
+      }
+      return { approved: false, reason: 'approval not granted' }
+    } catch (error) {
+      return { approved: false, reason: String(error?.message ?? error) }
+    }
+  }
+
+  async execute({ capability, tool, args }) {
+    switch (capability) {
+      case 'read':
+      case 'grep':
+      case 'run':
+      case 'tool': {
+        const name = capability === 'run' ? this.shellTool : tool
+        if (typeof name !== 'string' || name === '') {
+          throw Object.assign(new Error(`capability ${capability} needs a tool name`), { code: 'bad-request' })
+        }
+        return this.slot.executeTool({ name, args })
+      }
+      case 'list':
+        return this.readDirectory(args)
+      case 'fetch':
+        return this.fetchFile(args)
+      default:
+        throw Object.assign(new Error(`unsupported capability: ${String(capability)}`), { code: 'unsupported' })
+    }
+  }
+
+  async readDirectory(args) {
+    if (!this.fs) throw Object.assign(new Error('filesystem is unavailable'), { code: 'unsupported' })
+    const path = String(args?.path ?? args?.dir ?? '')
+    if (!path) throw Object.assign(new Error('list needs path'), { code: 'bad-request' })
+    const target = await this.fs.resolve(path)
+    const entries = await this.fs.listDir(target)
+    const lines = entries.map((entry) => `${entry.type}\t${entry.name}${entry.size === undefined ? '' : `\t${entry.size}`}`)
+    return { isError: false, text: lines.join('\n') || '(empty directory)', content: [], meta: { path } }
+  }
+
+  async fetchFile(args) {
+    if (!this.fs) throw Object.assign(new Error('filesystem is unavailable'), { code: 'unsupported' })
+    const path = String(args?.path ?? '')
+    if (!path) throw Object.assign(new Error('fetch needs path'), { code: 'bad-request' })
+    const target = await this.fs.resolve(path)
+    if (typeof this.fs.readText !== 'function') {
+      throw Object.assign(new Error('fetch is unavailable on this device'), { code: 'unsupported' })
+    }
+    const text = await this.fs.readText(target)
+    return { isError: false, text, content: [], meta: { path, bytes: Buffer.byteLength(text) } }
+  }
+}
+
+export class DirectCallClient {
+  constructor({ node }) {
+    this.node = node
+  }
+
+  async info(deviceId) {
+    return this.node.request(deviceId, 'fleet.info', {})
+  }
+
+  async listTools(deviceId) {
+    return this.node.request(deviceId, 'fleet.tools', {})
+  }
+
+  async call(deviceId, { capability, tool = null, args = {} }, options = {}) {
+    return this.node.request(deviceId, 'fleet.call', { capability, tool, args }, options)
+  }
+
+  /** Ask the target device's agent to do a one-shot task and return its final text. */
+  async delegate(deviceId, request, options = {}) {
+    return this.node.request(deviceId, 'fleet.delegate', request, options)
+  }
+
+  /** Format a remote result for a model-facing text tool. */
+  render(result) {
+    if (result?.isError) return `Error: ${result.text || 'remote tool failed'}`
+    const meta = result?.meta ?? {}
+    const footer = meta.durationMs !== undefined ? `\n[${String(meta.capability ?? 'call')} on ${String(meta.deviceId ?? 'peer')} · ${String(meta.durationMs)}ms]` : ''
+    return `${result?.text ?? ''}${footer}`.trim()
+  }
+}
+
+export { toolText }

package/src/host/execution-slot.js

@@ -0,0 +1,96 @@
+// Execution Slot: a hidden DSH session/agent that gives remote direct calls a
+// legal tool-execution context (cwd, sandbox policy, approval routing) without
+// running any model turn. See ADR-0003 and ADR-0019.
+import { randomUUID } from 'node:crypto'
+
+export const DEFAULT_SHELL_TOOL = process.platform === 'win32' ? 'pwsh' : 'bash'
+
+export class ExecutionSlot {
+  /**
+   * @param {{sessionController: object, tools: object, config?: {cwd?: string, agentPreset?: string}}} options
+   */
+  constructor({ sessionController, tools, config = {} }) {
+    this.sessionController = sessionController
+    this.tools = tools
+    this.config = config
+    this.agent = null
+    this.sessionId = null
+    this.initializing = null
+  }
+
+  async ensureAgent() {
+    if (this.agent) return this.agent
+    if (this.initializing) return this.initializing
+    this.initializing = (async () => {
+      const created = await this.sessionController.create({
+        cwd: this.config.cwd,
+        agentPreset: this.config.agentPreset,
+      })
+      const sessionId = created?.sessionId
+      if (!sessionId) throw Object.assign(new Error('execution slot could not create a session'), { code: 'slot-unavailable' })
+      const resolved = await this.sessionController.resolveAgent(sessionId)
+      if (!resolved?.agent) {
+        const reason = resolved?.error?.code ?? 'session/agent-busy'
+        throw Object.assign(new Error(`execution slot agent unavailable: ${String(reason)}`), { code: 'slot-unavailable' })
+      }
+      this.sessionId = sessionId
+      this.agent = resolved.agent
+      return this.agent
+    })().finally(() => {
+      this.initializing = null
+    })
+    return this.initializing
+  }
+
+  /** Model-facing tool schemas visible to the execution slot agent. */
+  async listTools() {
+    const agent = await this.ensureAgent()
+    const schemas = this.tools.schemas?.(agent) ?? this.tools.schemas?.() ?? []
+    return schemas
+  }
+
+  /**
+   * Execute one tool inside the slot context and normalize the result.
+   * @param {{name: string, args: object, signal?: AbortSignal}} call
+   */
+  async executeTool({ name, args = {}, signal }) {
+    const agent = await this.ensureAgent()
+    // execToolBatch requires a real AbortSignal: without one the pipeline
+    // throws before dispatch, which surfaces as "Tool batch execution failed".
+    const effectiveSignal = signal ?? new AbortController().signal
+    let batch
+    try {
+      batch = await this.tools.execute({
+        calls: [{ id: randomUUID(), name, arguments: JSON.stringify(args ?? {}) }],
+        agent,
+        signal: effectiveSignal,
+      })
+    } catch (error) {
+      const cause = error?.cause
+      const detail = cause?.message ?? error?.message ?? String(error)
+      throw Object.assign(new Error(`tool ${name} failed: ${String(detail)}`), {
+        code: 'tool-failed',
+        cause,
+        data: { causeCode: cause?.code ?? null, causeMessage: cause?.message ?? null },
+      })
+    }
+    const first = batch?.results?.[0]?.result
+    if (!first) throw Object.assign(new Error(`tool ${name} returned no result`), { code: 'tool-no-result' })
+    const text = (first.content ?? [])
+      .map((block) => (block?.type === 'text' ? block.text : `[${String(block?.type ?? 'block')}]`))
+      .join('\n')
+    return {
+      isError: first.isError === true,
+      text,
+      content: first.content ?? [],
+      error: first.error ?? null,
+      meta: first.meta ?? null,
+    }
+  }
+
+  /** Tool names currently visible to the slot agent. */
+  async toolNames() {
+    const tools = await this.listTools()
+    return tools.map((tool) => tool.name).filter((name) => typeof name === 'string')
+  }
+}

package/src/host/index.js

@@ -0,0 +1,10 @@
+// Public host-side exports for the fleet plugin.
+export * from './store.js'
+export * from './tool-policy.js'
+export * from './execution-slot.js'
+export * from './direct-call.js'
+export * from './delegation.js'
+export * from './approval-inbox.js'
+export * from './approval-web.js'
+export * from './room-service.js'
+export * from './tools.js'

package/src/host/room-service.js

@@ -0,0 +1,324 @@
+// Room logic layer (ADR-0002/0005/0006/0011/0021), with local participants for
+// simulation inside one DSH. The Host session log carries the authoritative
+// room events; participant agents are real local DSH sessions woken with an
+// addressed message, so addressing/wake/visibility and board handoff can be
+// exercised before the remote transport and the client UI exist.
+import { randomUUID } from 'node:crypto'
+
+const MAX_MESSAGE_CHARS = 20_000
+
+const DEFAULT_POLICY = Object.freeze({
+  invite: 'members',
+  join: 'auto',
+  maxMembers: 8,
+  boardWrite: 'members',
+  remove: 'members',
+})
+
+function hostMemberId(sessionId) {
+  return `host:${sessionId}`
+}
+
+function localMemberId(sessionId) {
+  return `local:${sessionId}`
+}
+
+export class RoomService {
+  /**
+   * @param {object} options
+   * @param {object} options.sessionController ctx.sessionController
+   * @param {(input: object) => object} [options.createUserMessage] dsh-llm helper
+   * @param {(now?: number) => number} [options.now]
+   */
+  constructor({ sessionController, createUserMessage = null, now = Date.now } = {}) {
+    this.sessionController = sessionController
+    this.createUserMessage = createUserMessage
+    this.now = now
+    /** @type {Map<string, any>} */
+    this.rooms = new Map()
+  }
+
+  async upgradeHost({ agent, policy = {} } = {}) {
+    if (!agent?.session?.id) throw Object.assign(new Error('room upgrade needs the calling agent session'), { code: 'bad-request' })
+    const sessionId = agent.session.id
+    const existing = this.rooms.get(sessionId)
+    if (existing) return this.summary(existing)
+    const memberId = hostMemberId(sessionId)
+    const room = {
+      roomId: sessionId,
+      createdAt: this.now(),
+      hostSessionId: sessionId,
+      policy: { ...DEFAULT_POLICY, ...policy },
+      members: new Map(),
+      messages: [],
+      tasks: new Map(),
+      closed: false,
+    }
+    room.members.set(memberId, {
+      memberId,
+      role: 'host',
+      kind: 'local',
+      sessionId,
+      name: agent.session.header?.title ?? 'host',
+      agent,
+    })
+    this.rooms.set(sessionId, room)
+    await this.append(room, 'room/created', { roomId: room.roomId, policy: room.policy, hostMemberId: memberId })
+    return this.summary(room)
+  }
+
+  async addLocalParticipant({ roomId, name = 'worker', agentPreset, cwd } = {}) {
+    const room = this.requireRoom(roomId)
+    if (room.members.size >= room.policy.maxMembers) {
+      throw Object.assign(new Error(`room member limit reached (${room.policy.maxMembers})`), { code: 'room-full' })
+    }
+    if (!this.sessionController?.create) {
+      throw Object.assign(new Error('participant sessions are unavailable'), { code: 'unsupported' })
+    }
+    const created = await this.sessionController.create({
+      ...(cwd ? { cwd } : {}),
+      ...(agentPreset ? { agentPreset } : {}),
+    })
+    const sessionId = created?.sessionId
+    if (!sessionId) throw Object.assign(new Error('could not create the participant session'), { code: 'room-participant-failed' })
+    const resolved = await this.sessionController.resolveAgent(sessionId)
+    if (!resolved?.agent) throw Object.assign(new Error('participant agent could not be resolved'), { code: 'room-participant-failed' })
+    const memberId = localMemberId(sessionId)
+    const member = { memberId, role: 'participant', kind: 'local', sessionId, name, agent: resolved.agent }
+    room.members.set(memberId, member)
+    await this.append(room, 'room/member', {
+      roomId: room.roomId,
+      action: 'added',
+      memberId,
+      role: 'participant',
+      name,
+      sessionId,
+    })
+    return this.memberSummary(member)
+  }
+
+  async removeMember({ roomId, memberId, reason = 'removed' } = {}) {
+    const room = this.requireRoom(roomId)
+    const member = room.members.get(memberId)
+    if (!member) throw Object.assign(new Error(`unknown member: ${String(memberId)}`), { code: 'unknown-member' })
+    if (member.role === 'host') throw Object.assign(new Error('the host cannot be removed; close the room instead'), { code: 'forbidden' })
+    room.members.delete(memberId)
+    await this.append(room, 'room/member', { roomId: room.roomId, action: 'removed', memberId, reason })
+    return { roomId: room.roomId, memberId }
+  }
+
+  /**
+   * Send one addressed message. The Host appends it to the canonical log and
+   * wakes only the addressed local members (never the sender).
+   */
+  async send({ roomId, from, to, text } = {}) {
+    const room = this.requireRoom(roomId)
+    const body = typeof text === 'string' ? text.trim() : ''
+    if (body === '') throw Object.assign(new Error('room message needs text'), { code: 'bad-request' })
+    if (body.length > MAX_MESSAGE_CHARS) throw Object.assign(new Error('room message is too long'), { code: 'bad-request' })
+    const recipients = Array.isArray(to) ? to.filter((id) => typeof id === 'string') : []
+    if (recipients.length === 0) throw Object.assign(new Error('room message needs at least one recipient'), { code: 'bad-request' })
+    for (const memberId of recipients) {
+      if (!room.members.has(memberId)) throw Object.assign(new Error(`unknown member: ${memberId}`), { code: 'unknown-member' })
+    }
+    const sender = this.resolveSender(room, from)
+    const message = {
+      id: randomUUID(),
+      roomId: room.roomId,
+      from: sender,
+      to: recipients,
+      text: body,
+      createdAt: this.now(),
+    }
+    room.messages.push(message)
+    await this.append(room, 'room/message', {
+      roomId: room.roomId,
+      messageId: message.id,
+      from: sender,
+      to: recipients,
+      text: body,
+    })
+    const woken = []
+    for (const memberId of recipients) {
+      if (sender.memberId === memberId) continue
+      const member = room.members.get(memberId)
+      if (await this.wake(room, member, message)) woken.push(memberId)
+    }
+    return { messageId: message.id, to: recipients, woken }
+  }
+
+  resolveSender(room, from) {
+    if (from && typeof from === 'object') {
+      if (typeof from.memberId === 'string') {
+        const member = room.members.get(from.memberId)
+        if (!member) throw Object.assign(new Error(`unknown sender member: ${from.memberId}`), { code: 'unknown-member' })
+        return { kind: 'agent', memberId: member.memberId, name: member.name ?? 'agent' }
+      }
+      if (typeof from.sessionId === 'string') {
+        for (const member of room.members.values()) {
+          if (member.sessionId === from.sessionId) {
+            return { kind: 'agent', memberId: member.memberId, name: member.name ?? 'agent' }
+          }
+        }
+        throw Object.assign(new Error(`sender session is not a room member: ${from.sessionId}`), { code: 'unknown-member' })
+      }
+      if (from.kind === 'user') return { kind: 'user', name: 'user' }
+    }
+    return { kind: 'user', name: 'user' }
+  }
+
+  /** Wake one local participant by injecting the addressed message. */
+  async wake(room, member, message) {
+    if (!member?.agent || typeof member.agent.followup !== 'function' || typeof this.createUserMessage !== 'function') return false
+    const senderLabel = message.from.kind === 'user' ? 'user' : (message.from.name ?? 'agent')
+    const text = [
+      `[Fleet Room ${room.roomId}] ${senderLabel} → you:`,
+      message.text,
+      '',
+      `Reply with room_send (roomId="${room.roomId}", to=["${message.from.memberId ?? 'host'}"]) when you have an answer.`,
+    ].join('\n')
+    const userMessage = this.createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+    try {
+      member.agent.followup(userMessage)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async append(room, type, data) {
+    const host = room.members.get(hostMemberId(room.hostSessionId))
+    const session = host?.agent?.session
+    if (session?.append) await session.append(type, data)
+  }
+
+  // --------------------------------------------------------------- room tasks
+
+  async addTask({ roomId, title, owner, dependsOn = [], description = '' } = {}) {
+    const room = this.requireRoom(roomId)
+    if (typeof title !== 'string' || title.trim() === '') throw Object.assign(new Error('task needs a title'), { code: 'bad-request' })
+    const ownerMember = room.members.get(owner)
+    if (!ownerMember) throw Object.assign(new Error(`unknown task owner: ${String(owner)}`), { code: 'unknown-member' })
+    const id = randomUUID()
+    const task = {
+      id,
+      roomId: room.roomId,
+      title: title.trim(),
+      description,
+      owner,
+      status: 'pending',
+      dependsOn: Array.isArray(dependsOn) ? dependsOn : [],
+      readyNotified: false,
+      createdAt: this.now(),
+      updatedAt: this.now(),
+    }
+    room.tasks.set(id, task)
+    await this.append(room, 'room/task', { roomId: room.roomId, action: 'added', task })
+    return task
+  }
+
+  async updateTask({ roomId, id, status, note } = {}) {
+    const room = this.requireRoom(roomId)
+    const task = room.tasks.get(id)
+    if (!task) throw Object.assign(new Error(`unknown task: ${String(id)}`), { code: 'unknown-task' })
+    const allowed = ['pending', 'running', 'done', 'blocked']
+    if (status !== undefined && !allowed.includes(status)) {
+      throw Object.assign(new Error(`invalid task status: ${String(status)}`), { code: 'bad-request' })
+    }
+    if (status !== undefined) task.status = status
+    if (typeof note === 'string' && note !== '') task.note = note
+    task.updatedAt = this.now()
+    await this.append(room, 'room/task', { roomId: room.roomId, action: 'updated', task })
+    let handedOff = []
+    if (status === 'done') handedOff = await this.handOffReady(room)
+    return { task, handedOff }
+  }
+
+  /** Wake owners of pending tasks whose dependencies all completed. */
+  async handOffReady(room) {
+    const ready = []
+    for (const task of room.tasks.values()) {
+      if (task.status !== 'pending' || task.readyNotified) continue
+      if (task.dependsOn.length === 0) continue
+      const depsDone = task.dependsOn.every((dep) => room.tasks.get(dep)?.status === 'done')
+      if (!depsDone) continue
+      task.readyNotified = true
+      task.updatedAt = this.now()
+      const owner = room.members.get(task.owner)
+      const message = {
+        id: randomUUID(),
+        roomId: room.roomId,
+        from: { kind: 'user', name: 'room' },
+        to: [task.owner],
+        text: `任务 "${task.title}" 的前置任务已完成，现在可以开始。`,
+        createdAt: this.now(),
+      }
+      room.messages.push(message)
+      await this.append(room, 'room/message', { roomId: room.roomId, messageId: message.id, from: message.from, to: message.to, text: message.text })
+      const woken = owner ? await this.wake(room, owner, message) : false
+      ready.push({ taskId: task.id, owner: task.owner, woken })
+    }
+    return ready
+  }
+
+  listTasks(roomId) {
+    const room = this.requireRoom(roomId)
+    return [...room.tasks.values()].sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  // ------------------------------------------------------------------- reads
+
+  messages({ roomId, limit = 50 } = {}) {
+    const room = this.requireRoom(roomId)
+    const items = room.messages.slice(-Math.max(1, Math.min(limit, 200)))
+    return items.map((message) => ({
+      ...message,
+      fromLabel: message.from.kind === 'user' ? 'user' : `${message.from.name ?? 'agent'} (${message.from.memberId ?? '?'})`,
+    }))
+  }
+
+  summary(room) {
+    return {
+      roomId: room.roomId,
+      createdAt: room.createdAt,
+      closed: room.closed,
+      policy: { ...room.policy },
+      members: [...room.members.values()].map((member) => this.memberSummary(member)),
+      messageCount: room.messages.length,
+      tasks: this.listTasks(room.roomId).length,
+    }
+  }
+
+  memberSummary(member) {
+    return {
+      memberId: member.memberId,
+      role: member.role,
+      kind: member.kind,
+      sessionId: member.sessionId,
+      name: member.name,
+    }
+  }
+
+  status(roomId) {
+    return this.summary(this.requireRoom(roomId))
+  }
+
+  /** All open rooms (for cleanup and diagnostics). */
+  openRooms() {
+    return [...this.rooms.keys()]
+  }
+
+  async close({ roomId, reason = 'closed by host' } = {}) {
+    const room = this.requireRoom(roomId)
+    room.closed = true
+    await this.append(room, 'room/closed', { roomId: room.roomId, reason, closedAt: this.now() })
+    this.rooms.delete(room.roomId)
+    return { roomId: room.roomId, closed: true, reason }
+  }
+
+  requireRoom(roomId) {
+    const room = this.rooms.get(roomId)
+    if (!room) throw Object.assign(new Error(`unknown or closed room: ${String(roomId)}`), { code: 'unknown-room' })
+    return room
+  }
+}