@lincyaw/dsh 0.0.0-stage → 0.2.0-rc.0

package/src/client/theme.ts

@@ -0,0 +1,151 @@
+import { color } from '@lincyaw/design'
+import type { ColorName } from '@lincyaw/design'
+
+type Pair = { light: string, dark: string }
+const same = (value: string): Pair => ({ light: value, dark: value })
+const pm = (name: ColorName): Pair => same(color(name))
+const mix = (name: ColorName, percent: number, other = 'transparent'): Pair => same(`color-mix(in srgb, ${color(name)} ${percent}%, ${other})`)
+
+/** DeepSeek Harness's theme tokens (`--dsw-*`) mapped onto Presmium's design tokens. */
+export const DSH_THEME_TOKENS: Record<string, Pair> = {
+  '--dsw-alias-bg-base': pm('bg'),
+  '--dsw-alias-bg-document-preview': pm('surface'),
+  '--dsw-alias-bg-layer-1': pm('surface'),
+  '--dsw-alias-bg-layer-2': pm('surface'),
+  '--dsw-alias-bg-layer-3': pm('sunk'),
+  '--dsw-alias-bg-mask-1': { light: 'rgba(28, 27, 25, 0.32)', dark: 'rgba(0, 0, 0, 0.55)' },
+  '--dsw-alias-bg-mask-drop': { light: 'rgba(247, 245, 240, 0.7)', dark: 'rgba(22, 22, 20, 0.7)' },
+  '--dsw-alias-bg-module-platform': pm('sunk'),
+  '--dsw-alias-bg-overlay': pm('surface'),
+  '--dsw-alias-bg-skeleton': mix('ink', 6),
+  '--dsw-alias-border-inverted': same('transparent'),
+  '--dsw-alias-border-l1': pm('line'),
+  '--dsw-alias-border-l2': pm('line'),
+  '--dsw-alias-border-l2-darkmode-thin': pm('line'),
+  '--dsw-alias-border-l3': pm('line'),
+  '--dsw-alias-border-l4': pm('line-strong'),
+  '--dsw-alias-brand-primary': pm('ink'),
+  '--dsw-alias-brand-primary-new-colorprimary-new-color': pm('accent'),
+  '--dsw-alias-button-contrast-fill': pm('ink'),
+  '--dsw-alias-button-elevated-fill': pm('surface'),
+  '--dsw-alias-button-floating-fill': pm('surface'),
+  '--dsw-alias-button-floating-hover': pm('sunk'),
+  '--dsw-alias-button-ghost-active-border': pm('line-strong'),
+  '--dsw-alias-button-ghost-active-fill': pm('selected'),
+  '--dsw-alias-button-info-fill': { light: '#0f5f5c', dark: '#2c7a74' },
+  '--dsw-alias-button-info-hover': { light: '#0b4a47', dark: '#256963' },
+  '--dsw-alias-button-primary-fill': pm('ink'),
+  '--dsw-alias-button-primary-hover': mix('ink', 85, color('bg')),
+  '--dsw-alias-file-diff-added-bg': pm('ok-soft'),
+  '--dsw-alias-file-diff-added-gutter': pm('ok-soft'),
+  '--dsw-alias-file-diff-added-marker': pm('add'),
+  '--dsw-alias-file-diff-deleted-bg': pm('danger-soft'),
+  '--dsw-alias-file-diff-deleted-gutter': pm('danger-soft'),
+  '--dsw-alias-file-diff-deleted-marker': pm('del'),
+  '--dsw-alias-interactive-bg-active': pm('selected'),
+  '--dsw-alias-interactive-bg-hover': mix('ink', 6),
+  '--dsw-alias-interactive-bg-hover-danger': pm('danger-soft'),
+  '--dsw-alias-interactive-bg-hover-solid': pm('sunk'),
+  '--dsw-alias-label-caption': pm('muted'),
+  '--dsw-alias-label-deep-diving': pm('accent'),
+  '--dsw-alias-label-deep-diving-shimmer': pm('muted'),
+  '--dsw-alias-label-dimmed': pm('line-strong'),
+  '--dsw-alias-label-primary': pm('ink'),
+  '--dsw-alias-label-primary-bluish': pm('ink'),
+  '--dsw-alias-label-primary-dimmed': pm('ink'),
+  '--dsw-alias-label-primary-foreground': pm('bg'),
+  '--dsw-alias-label-primary-inverted': pm('bg'),
+  '--dsw-alias-label-secondary': pm('muted'),
+  '--dsw-alias-label-tertiary': pm('muted'),
+  '--dsw-alias-link': pm('accent'),
+  '--dsw-alias-markdown-citation': pm('sunk'),
+  '--dsw-alias-markdown-code-block': pm('code'),
+  '--dsw-alias-markdown-code-block-banner': pm('sunk'),
+  '--dsw-alias-menu-icon': pm('ink'),
+  '--dsw-alias-onboarding-accent': pm('accent'),
+  '--dsw-alias-onboarding-card-fill': pm('surface'),
+  '--dsw-alias-onboarding-checkbox-border': pm('line-strong'),
+  '--dsw-alias-onboarding-secondary-fill': pm('surface'),
+  '--dsw-alias-scrollbar-bg-l1': pm('line'),
+  '--dsw-alias-scrollbar-bg-l2': pm('line'),
+  '--dsw-alias-scrollbar-hover-l1': pm('line-strong'),
+  '--dsw-alias-scrollbar-hover-l2': pm('line-strong'),
+  '--dsw-alias-settings-card-fill': pm('surface'),
+  '--dsw-alias-settings-card-stroke': pm('line'),
+  '--dsw-alias-state-business-primary': pm('accent'),
+  '--dsw-alias-state-business-tertiary': pm('accent-soft'),
+  '--dsw-alias-state-error-primary': pm('danger'),
+  '--dsw-alias-state-error-secondary': pm('danger'),
+  '--dsw-alias-state-success-primary': pm('ok'),
+  '--dsw-alias-state-success-secondary': pm('ok'),
+  '--dsw-alias-state-success-tertiary': pm('ok-soft'),
+  '--dsw-alias-state-warn-label': pm('warn'),
+  '--dsw-alias-state-warn-primary': pm('warn'),
+  '--dsw-alias-state-warn-secondary': pm('warn'),
+  '--dsw-alias-state-warn-tertiary': pm('warn-soft'),
+  '--dsw-alias-tooltip-bg': { light: '#1c1b19', dark: '#3a3833' },
+  '--dsw-alias-turn-trigger-bg': pm('code'),
+  '--dsw-alias-turn-trigger-bg-hover': mix('ink', 6),
+  '--dsw-specific-sidebar-fill': pm('sunk'),
+  '--dsw-specific-sidebar-nav-item-active': pm('selected'),
+  '--dsw-specific-sidebar-nav-item-active-accent': pm('accent'),
+  '--dsw-specific-sidebar-nav-item-hover': mix('ink', 6),
+  '--dsw-specific-bubble': pm('accent-soft'),
+  '--dsw-specific-bubble-highlight': pm('selected'),
+  '--dsw-specific-input-major': pm('surface'),
+  '--dsw-specific-menu': pm('surface'),
+  '--dsw-specific-selector': pm('surface'),
+  '--dsw-focus-ring-color': pm('accent'),
+}
+
+const SANS = 'var(--pm-font-sans)'
+const MONO = 'var(--pm-font-mono)'
+const FONT_SIZES = { text: '--dsh-content-font-size', code: '--dsh-code-font-size', terminal: '--dsh-terminal-font-size' } as const
+const FONT_FAMILIES = { text: '--dsh-font-family-text', code: '--dsh-font-family-code', terminal: '--dsh-font-family-terminal' } as const
+
+export class ThemePresenter {
+  #applied: string[] = []
+  readonly #meta = document.createElement('meta')
+
+  constructor() {
+    this.#meta.name = 'theme-color'
+  }
+
+  apply(snapshot: DshThemeSnapshot): void {
+    const scheme = snapshot.active.colorScheme
+    const root = document.documentElement
+    const body = document.body
+    root.style.colorScheme = scheme
+    root.setAttribute('data-ds-theme-source', snapshot.preference === 'system' ? 'system' : scheme)
+    if (scheme === 'dark') body.setAttribute('data-ds-dark-theme', '')
+    else body.removeAttribute('data-ds-dark-theme')
+    for (const [role, name] of Object.entries(FONT_SIZES)) body.style.setProperty(name, `${snapshot.fontSizes[role as keyof typeof FONT_SIZES]}px`)
+    for (const [role, name] of Object.entries(FONT_FAMILIES)) body.style.setProperty(name, snapshot.fontFamilies[role as keyof typeof FONT_FAMILIES] || (role === 'text' ? SANS : MONO))
+    for (const name of this.#applied) body.style.removeProperty(name)
+    this.#applied = []
+    for (const [name, value] of Object.entries(snapshot.active.tokens)) {
+      body.style.setProperty(name, value)
+      this.#applied.push(name)
+    }
+    this.#meta.content = getComputedStyle(body).backgroundColor
+    if (!this.#meta.isConnected) document.head.append(this.#meta)
+  }
+
+  dispose(): void {
+    const root = document.documentElement
+    const body = document.body
+    root.style.removeProperty('color-scheme')
+    root.removeAttribute('data-ds-theme-source')
+    body.removeAttribute('data-ds-dark-theme')
+    for (const name of [...Object.values(FONT_SIZES), ...Object.values(FONT_FAMILIES), ...this.#applied]) body.style.removeProperty(name)
+    this.#applied = []
+    this.#meta.remove()
+  }
+}
+
+/** Sets the `dark` class of the page to DeepSeek Harness's colour scheme; returns whether it is dark. */
+export function syncDarkClass(snapshot: DshThemeSnapshot): boolean {
+  const dark = snapshot.active.colorScheme === 'dark'
+  document.documentElement.classList.toggle('dark', dark)
+  return dark
+}

package/src/client/workbench-keys.ts

@@ -0,0 +1,36 @@
+import type { Workbench } from '@lincyaw/workbench'
+import { CLIENT_MESSAGES } from './messages.ts'
+import type { ClientMessages } from './messages.ts'
+
+const apple = /Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent)
+const mod = apple ? '⌘' : 'Ctrl', shift = apple ? '⇧' : 'Shift'
+const key = (code: string, ...modifiers: string[]) => ({ code, modifiers })
+
+// The reference lists an extension's rows in the order of their ids, so the ids carry the order.
+const ROWS: { id: string, label: keyof ClientMessages['keys'], keys: string[], bindings: [DshShortcutBinding, ...DshShortcutBinding[]] }[] = [
+  { id: 'presmium.keys-1-save', label: 'save', keys: [mod, 'S'], bindings: [key('KeyS', 'primary')] },
+  { id: 'presmium.keys-2-undo', label: 'undo', keys: [mod, 'Z'], bindings: [key('KeyZ', 'primary')] },
+  { id: 'presmium.keys-3-redo', label: 'redo', keys: apple ? [mod, shift, 'Z'] : [mod, 'Y'], bindings: apple ? [key('KeyZ', 'primary', 'shift')] : [key('KeyY', 'primary'), key('KeyZ', 'primary', 'shift')] },
+  { id: 'presmium.keys-4-play', label: 'play', keys: ['Space'], bindings: [key('Space')] },
+  { id: 'presmium.keys-5-step', label: 'step', keys: ['←', '→'], bindings: [key('ArrowLeft'), key('ArrowRight')] },
+  { id: 'presmium.keys-6-overview', label: 'overview', keys: ['O'], bindings: [key('KeyO')] },
+  { id: 'presmium.keys-7-fullscreen', label: 'fullscreen', keys: [shift, 'F'], bindings: [key('KeyF', 'shift')] },
+]
+
+/**
+ * Lists the workbench's own keys in Harness's shortcut reference (Settings → General → Edit Shortcuts, or Mod+/). They are
+ * fixed rows: the workbench and its preview handle the keys themselves, and the rows keep them from editable commands.
+ */
+export function registerWorkbenchKeys(ctx: DshClientContext, workbench: Workbench): void {
+  ctx.effect(() => {
+    const disposers = ROWS.flatMap(({ label, ...row }) => {
+      try {
+        return [ctx.shortcuts.registerFixed({ ...row, label: () => CLIENT_MESSAGES[workbench.state.locale].keys[label], group: 'application' })]
+      } catch (error) {
+        console.warn(`[presmium] the shortcut reference did not take ${row.id}`, error)
+        return []
+      }
+    })
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'presmium: the workbench keys in the shortcut reference')
+}

package/src/client/workspace-events.ts

@@ -0,0 +1,114 @@
+import { WebSocket } from 'partysocket'
+import type { WorkspaceSubscription } from '@lincyaw/workbench'
+import type { AuthoringClientAcknowledgement, AuthoringClientEvent, AuthoringClientReport } from '@lincyaw/kernel'
+import { AUTHORING_CLIENT_REQUEST_TIMEOUT_MS } from '@lincyaw/kernel'
+import { WORKSPACE_EVENTS_PATH, workspaceEventMessage } from '../workspace-events.ts'
+import type { WorkspaceEventTopic, WorkspaceEventCommand } from '../workspace-events.ts'
+
+const TOPICS: Readonly<Record<string, WorkspaceEventTopic>> = {
+  document: 'document', diagnostics: 'diagnostics', review: 'review', revision: 'ir', job: 'jobs', 'viewer-site': 'viewer-site', 'viewer-control': 'viewer-control', approvals: 'approvals',
+}
+
+/** Each live reader owns one logical subscription; the library owns physical reconnect timing. */
+export function workspaceSubscriptions(ctx: Pick<DshClientContext, 'effect'>): WorkspaceSubscription {
+  type Subscription = { id?: string, request: Extract<WorkspaceEventCommand, { type: 'subscribe' }>, received(data: string, event?: string): void, failed?(): void, ready?(): void, pending?: Map<number, { resolve(): void, reject(error: Error): void, timer: ReturnType<typeof setTimeout> }> }
+  const readers = new Set<Subscription>()
+  const ids = new Map<string, Subscription>()
+  const url = new URL(WORKSPACE_EVENTS_PATH.slice(1), document.baseURI)
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+  const socket = new WebSocket(url.href, [], { startClosed: true, maxEnqueuedMessages: 0 })
+  let closed = false
+  let serial = 0
+  const subscribe = (reader: Subscription) => {
+    const id = String(++serial)
+    reader.id = id
+    ids.set(id, reader)
+    socket.send(JSON.stringify({ ...reader.request, id }))
+  }
+  const opened = () => {
+    if (closed) return
+    ids.clear()
+    for (const reader of readers) subscribe(reader)
+  }
+  const disconnected = () => {
+    ids.clear()
+    for (const reader of readers) { reader.id = undefined; rejectPublications(reader); reader.failed?.() }
+  }
+  const rejectPublications = (reader: Subscription) => { for (const pending of reader.pending?.values() ?? []) { clearTimeout(pending.timer); pending.reject(new Error('client-transport-disconnected')) }; reader.pending?.clear() }
+  const message = (event: MessageEvent) => {
+    let raw: unknown
+    try { raw = JSON.parse(event.data) } catch { return }
+    const parsed = workspaceEventMessage.safeParse(raw)
+    if (!parsed.success) return
+    const value = parsed.data
+    const reader = ids.get(value.id)
+    if (!reader || !readers.has(reader)) return
+    if (value.type === 'published') {
+      const pending = reader.pending?.get(value.sequence)
+      reader.pending?.delete(value.sequence)
+      if (pending) clearTimeout(pending.timer)
+      if (value.ok) pending?.resolve(); else pending?.reject(new Error('client-publication-refused'))
+    } else if (value.type === 'ready') reader.ready?.()
+    else if (value.type === 'error') { rejectPublications(reader); reader.failed?.() }
+    else {
+      const topic = reader.request.topic
+      const named = topic === 'viewer-site' ? ['ir', 'reload'] : topic === 'viewer-control' ? ['ready', 'approval', 'settled', 'go', 'session'] : topic === 'approvals' ? ['approval', 'settled'] : undefined
+      if (named && (!value.event || !named.includes(value.event))) return
+      reader.received(value.data, value.event)
+    }
+  }
+  socket.addEventListener('open', opened)
+  socket.addEventListener('close', disconnected)
+  socket.addEventListener('message', message)
+  ctx.effect(() => () => {
+    closed = true
+    for (const reader of readers) rejectPublications(reader)
+    readers.clear(); ids.clear()
+    socket.removeEventListener('open', opened)
+    socket.removeEventListener('close', disconnected)
+    socket.removeEventListener('message', message)
+    socket.close()
+  }, 'presmium: workspace subscriptions')
+  const add = (reader: Subscription) => {
+    if (!closed) {
+      readers.add(reader)
+      if (socket.readyState === WebSocket.OPEN) subscribe(reader)
+      else if (readers.size === 1) socket.reconnect()
+    }
+    return () => {
+      if (!readers.delete(reader)) return
+      rejectPublications(reader)
+      if (reader.id) {
+        ids.delete(reader.id)
+        if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ type: 'unsubscribe', id: reader.id }))
+      }
+      if (readers.size === 0) socket.close()
+    }
+  }
+  const subscription: WorkspaceSubscription = (address, name, received, failed, ready) => {
+    const topic = TOPICS[name]
+    const query = new URL(address).searchParams
+    const document = query.get('document')
+    if (!topic || topic === 'authoring-client' || document === null) throw new Error('Invalid workspace event subscription.')
+    const request: Subscription['request'] = topic === 'viewer-site'
+      ? { type: 'subscribe', id: '', topic, document, app: query.get('app') ?? '', lang: query.get('lang') ?? '', form: query.get('form') === 'slides' ? 'slides' : 'web' }
+      : topic === 'viewer-control' ? { type: 'subscribe', id: '', topic, document, window: query.get('window') ?? '' }
+        : { type: 'subscribe', id: '', topic, document }
+    const reader: Subscription = { request, received, failed, ready }
+    return add(reader)
+  }
+  subscription.openAuthoringClient = (document, open, received, failed) => {
+    const reader: Subscription = { request: { type: 'subscribe', id: '', topic: 'authoring-client', document, ...open }, pending: new Map(), failed,
+      received(raw) { let event: AuthoringClientEvent; try { event = JSON.parse(raw) } catch { return }; if (event.type === 'connected') rejectPublications(reader); received(event) } }
+    const close = add(reader)
+    const publish = (kind: 'state' | 'ack', connectionId: string, report: AuthoringClientReport | AuthoringClientAcknowledgement) => new Promise<void>((resolve, reject) => {
+      if (closed || !readers.has(reader) || !reader.id || socket.readyState !== WebSocket.OPEN || reader.pending!.has(report.sequence)) { reject(new Error('client-transport-disconnected')); return }
+      // A lost publication receipt must release the queue without authorizing a repeated action.
+      const timer = setTimeout(() => { reader.pending!.delete(report.sequence); reject(new Error('client-publication-timeout')) }, AUTHORING_CLIENT_REQUEST_TIMEOUT_MS / 2)
+      reader.pending!.set(report.sequence, { resolve, reject, timer })
+      socket.send(JSON.stringify({ type: 'authoring-client-publish', id: reader.id, connectionId, sequence: report.sequence, kind, value: report }))
+    })
+    return { close, publish: (connectionId, report) => publish('state', connectionId, report), acknowledge: (connectionId, report) => publish('ack', connectionId, report) }
+  }
+  return subscription
+}

package/src/node/bindings.ts

@@ -0,0 +1,345 @@
+import { realpathSync } from 'node:fs'
+import { relative, resolve, sep } from 'node:path'
+import { connectPresmiumMcp } from '@lincyaw/mcp/client'
+import { errorMessage, isRecord } from '@lincyaw/kernel'
+import type { DiagnosticSnapshot, DocumentSummary } from '@lincyaw/kernel'
+import type { ListedTool, PresmiumMcpClient } from '@lincyaw/mcp/client'
+import type { DshAgent, DshContext, DshLogger } from './dsh-types.ts'
+import { SERVER_ROUTES } from './server-routes.ts'
+import type { WorkspaceServerClient } from './service.ts'
+
+/** The document an agent session works on: an MCP client with a session token for it, its tools and its diagnostics. */
+export interface DocumentBinding {
+  agentSessionId: string
+  document: DocumentSummary
+  dir: string
+  client: PresmiumMcpClient
+  readonly tools: ListedTool[]
+  toolChanges: BindingTools
+  diagnostics: BindingDiagnostics
+}
+
+interface SelectionListener {
+  before(): Promise<void>
+  after(): Promise<void>
+}
+
+/** Refreshes the tool list on MCP invalidations without replacing its document-bound client. */
+export class BindingTools {
+  snapshot: ListedTool[] = []
+  error: string | undefined
+  readonly #client: PresmiumMcpClient
+  readonly #log: DshLogger
+  readonly #listeners = new Set<() => void>()
+  #signature = ''
+  #unsubscribe: (() => Promise<void>) | undefined
+  #pending: Promise<void> | undefined
+  #dirty = false
+  #closed = false
+
+  constructor(client: PresmiumMcpClient, log: DshLogger) {
+    this.#client = client
+    this.#log = log
+  }
+
+  async start(): Promise<void> {
+    this.#unsubscribe = await this.#client.subscribeTools(() => { void this.refresh() })
+    await this.refresh()
+    if (this.error) throw new Error(this.error)
+  }
+
+  watch(listener: () => void): () => void {
+    this.#listeners.add(listener)
+    return () => { this.#listeners.delete(listener) }
+  }
+
+  refresh(): Promise<void> {
+    if (this.#closed) return Promise.resolve()
+    this.#dirty = true
+    if (!this.#pending) {
+      this.#pending = this.#read().finally(() => {
+        this.#pending = undefined
+        if (this.#dirty && !this.#closed) return this.refresh()
+      })
+    }
+    return this.#pending
+  }
+
+  async #read(): Promise<void> {
+    while (this.#dirty && !this.#closed) {
+      this.#dirty = false
+      try {
+        const tools = await this.#client.tools()
+        if (this.#closed || this.#dirty) continue
+        this.error = undefined
+        const signature = JSON.stringify(tools)
+        if (signature === this.#signature) continue
+        this.#signature = signature
+        this.snapshot = tools
+        for (const listener of this.#listeners) listener()
+      } catch (error) {
+        if (!this.#closed) {
+          this.error = errorMessage(error)
+          this.#log.warn(`presmium-tools: the tool list did not refresh: ${this.error}`)
+        }
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true
+    this.#dirty = false
+    this.#listeners.clear()
+    await this.#unsubscribe?.()
+  }
+}
+
+/** One current resource snapshot, shared by notifications and the next model step. */
+export class BindingDiagnostics {
+  snapshot: DiagnosticSnapshot | undefined
+  error: string | undefined
+  readonly #client: PresmiumMcpClient
+  readonly #uri: string
+  #unsubscribe: (() => Promise<void>) | undefined
+  #pending: Promise<void> | undefined
+  #dirty = false
+  #closed = false
+
+  constructor(client: PresmiumMcpClient, document: string) {
+    this.#client = client
+    this.#uri = `presmium://diagnostics?document=${encodeURIComponent(document)}`
+  }
+
+  async start(): Promise<void> {
+    this.#unsubscribe = await this.#client.subscribe(this.#uri, () => { void this.refresh() })
+    await this.refresh()
+  }
+
+  refresh(): Promise<void> {
+    if (this.#closed) return Promise.resolve()
+    this.#dirty = true
+    if (!this.#pending) {
+      const pending = this.#read().finally(() => {
+        this.#pending = undefined
+        if (this.#dirty && !this.#closed) return this.refresh()
+      })
+      this.#pending = pending
+    }
+    return this.#pending
+  }
+
+  async #read(): Promise<void> {
+    while (this.#dirty && !this.#closed) {
+      this.#dirty = false
+      try {
+        const value = await this.#client.read(this.#uri)
+        if (!isRecord(value) || typeof value.version !== 'number' || !Array.isArray(value.diagnostics)) throw new Error('the diagnostics resource returned an invalid snapshot')
+        if (this.#closed) return
+        this.snapshot = value as unknown as DiagnosticSnapshot
+        this.error = undefined
+      } catch (error) {
+        if (!this.#closed) this.error = errorMessage(error)
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true
+    this.#dirty = false
+    await this.#unsubscribe?.()
+  }
+}
+
+async function closeBinding(binding: DocumentBinding): Promise<void> {
+  try {
+    await Promise.all([binding.diagnostics.close(), binding.toolChanges.close()])
+  } finally {
+    await binding.client.close()
+  }
+}
+
+function realPath(path: string): string {
+  try {
+    return realpathSync(path)
+  } catch {
+    return resolve(path)
+  }
+}
+
+function documentAt(root: string, dir: string, documents: DocumentSummary[]): DocumentSummary | undefined {
+  const rel = relative(realPath(root), realPath(dir)).split(sep).join('/')
+  if (rel.startsWith('..')) return undefined
+  return documents.find(doc => doc.dir === rel)
+}
+
+/**
+ * Binds each agent session to one document of the workspace: the one the workbench selected for it, or else the
+ * document its working directory is in. Selecting no document (`null`) leaves the session unbound.
+ */
+export class DocumentBindings {
+  readonly #ctx: DshContext
+  readonly #server: WorkspaceServerClient
+  readonly #log: DshLogger
+  /** Each agent session's request to bind, kept once it is bound. */
+  readonly #bindRequests = new Map<string, Promise<DocumentBinding | undefined>>()
+  readonly #bound = new Map<string, DocumentBinding>()
+  readonly #failures = new Map<string, string>()
+  readonly #syncing = new Map<string, Promise<DocumentBinding | undefined>>()
+  readonly #selectionVersions = new Map<string, number>()
+  readonly #selectionListeners = new Map<string, SelectionListener>()
+  readonly #selected = new Map<string, string | null>()
+  #closed = false
+
+  constructor(ctx: DshContext, server: WorkspaceServerClient, log: DshLogger) {
+    this.#ctx = ctx
+    this.#server = server
+    this.#log = log
+  }
+
+  workingDirectoryOf(agent: DshAgent): string {
+    const dirs = this.#ctx.get('workingDirectory') as { get(session: unknown): string } | undefined
+    try {
+      return dirs?.get(agent.session) ?? agent.session.header?.cwd ?? process.cwd()
+    } catch {
+      return agent.session.header?.cwd ?? process.cwd()
+    }
+  }
+
+  bind(agent: DshAgent): Promise<DocumentBinding | undefined> {
+    const id = agent.session.id
+    let known = this.#bindRequests.get(id)
+    if (!known) {
+      const current = () => !this.#closed && this.#bindRequests.get(id) === known
+      known = this.#bind(agent, current).catch((error: unknown) => {
+        if (!current()) return undefined
+        const message = errorMessage(error)
+        this.#log.warn(`presmium-service: the session ${id} has no Presmium tools: ${message}`)
+        this.#failures.set(id, message)
+        this.#bindRequests.delete(id)
+        return undefined
+      })
+      this.#bindRequests.set(id, known)
+    }
+    return known
+  }
+
+  async #bind(agent: DshAgent, current: () => boolean): Promise<DocumentBinding | undefined> {
+    const { root } = await this.#server.ready
+    const id = agent.session.id
+    const documents = await this.#server.readDocuments()
+    const selected = this.#selected.get(id)
+    const document = selected === undefined ? documentAt(root, this.workingDirectoryOf(agent), documents) : documents.find(doc => doc.dir === selected)
+    if (!current()) return undefined
+    if (!document) {
+      this.#failures.delete(id)
+      return undefined
+    }
+    const grant = await this.#server.requestJson<{ url: string, token: string }>(`${SERVER_ROUTES}tokens`, { body: { document: document.dir, session: id } })
+    const client = await connectPresmiumMcp(grant.url, grant.token)
+    const diagnostics = new BindingDiagnostics(client, document.dir)
+    const toolChanges = new BindingTools(client, this.#log)
+    try {
+      const binding: DocumentBinding = { agentSessionId: id, document, dir: resolve(root, document.dir), client, get tools() { return toolChanges.snapshot }, toolChanges, diagnostics }
+      await toolChanges.start()
+      await diagnostics.start()
+      if (current()) {
+        this.#failures.delete(id)
+        this.#bound.set(id, binding)
+        return binding
+      }
+    } catch (error) {
+      await Promise.all([diagnostics.close(), toolChanges.close()]).catch(() => undefined)
+      await client.close().catch(() => undefined)
+      throw error
+    }
+    await Promise.all([diagnostics.close(), toolChanges.close()]).finally(() => client.close())
+    return undefined
+  }
+
+  async selectDocument(agentSessionId: string, document: string | null): Promise<void> {
+    const version = (this.#selectionVersions.get(agentSessionId) ?? 0) + 1
+    this.#selectionVersions.set(agentSessionId, version)
+    if (document !== null) {
+      let documents = await this.#server.readDocuments()
+      if (!documents.some(doc => doc.dir === document)) {
+        this.#server.invalidateDocuments()
+        documents = await this.#server.readDocuments()
+      }
+      if (this.#selectionVersions.get(agentSessionId) !== version) return
+      if (!documents.some(doc => doc.dir === document)) throw new Error('Unknown Presmium document')
+    }
+    const listener = this.#selectionListeners.get(agentSessionId)
+    await listener?.before()
+    if (this.#selectionVersions.get(agentSessionId) !== version) return
+    this.#selected.set(agentSessionId, document)
+    await listener?.after()
+  }
+
+  watchSelection(agentSessionId: string, listener: SelectionListener): () => void {
+    this.#selectionListeners.set(agentSessionId, listener)
+    return () => { if (this.#selectionListeners.get(agentSessionId) === listener) this.#selectionListeners.delete(agentSessionId) }
+  }
+
+  /** Binds the session again when the selection changed or its diagnostics failed; concurrent calls share one. */
+  syncBinding(agent: DshAgent): Promise<DocumentBinding | undefined> {
+    const id = agent.session.id
+    let pending = this.#syncing.get(id)
+    if (!pending) {
+      pending = this.#syncBinding(agent).finally(() => this.#syncing.delete(id))
+      this.#syncing.set(id, pending)
+    }
+    return pending
+  }
+
+  async #syncBinding(agent: DshAgent): Promise<DocumentBinding | undefined> {
+    const id = agent.session.id
+    const selected = this.#selected.get(id)
+    const current = await this.bind(agent)
+    if (!current?.diagnostics.error && (selected === undefined || current?.document.dir === selected || (!current && selected === null))) return current
+    await this.unbind(id, false)
+    return this.bind(agent)
+  }
+
+  bindingOf(agent: DshAgent | undefined): DocumentBinding | undefined {
+    return agent ? this.#bound.get(agent.session.id) : undefined
+  }
+
+  /** The document the session works on now, if it is bound to one. */
+  documentOf(agentSessionId: string): string | undefined {
+    return this.#bound.get(agentSessionId)?.document.dir
+  }
+
+  failureOf(agent: DshAgent): string | undefined {
+    return this.#failures.get(agent.session.id)
+  }
+
+  /** Closes the session's binding and revokes its session token; `forget` drops its selection too. */
+  async unbind(agentSessionId: string, forget = true): Promise<void> {
+    if (forget) {
+      this.#selectionVersions.delete(agentSessionId)
+      this.#selected.delete(agentSessionId)
+      this.#selectionListeners.delete(agentSessionId)
+    }
+    const binding = this.#bound.get(agentSessionId)
+    const request = this.#bindRequests.get(agentSessionId)
+    this.#bound.delete(agentSessionId)
+    this.#bindRequests.delete(agentSessionId)
+    this.#failures.delete(agentSessionId)
+    if (binding) await closeBinding(binding).catch(error => this.#log.warn(`presmium-service: closing session ${agentSessionId}: ${errorMessage(error)}`))
+    else await request
+    if (!binding && !request) return
+    await this.#server.request(`${SERVER_ROUTES}tokens`, { method: 'DELETE', body: { session: agentSessionId } }).then(r => r.body?.cancel(), () => undefined)
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true
+    for (const binding of this.#bound.values()) await closeBinding(binding).catch(error => this.#log.warn(`presmium-service: closing session ${binding.agentSessionId}: ${errorMessage(error)}`))
+    this.#bound.clear()
+    await Promise.all(this.#bindRequests.values())
+    this.#bindRequests.clear()
+    this.#failures.clear()
+    this.#selected.clear()
+    this.#selectionVersions.clear()
+    this.#selectionListeners.clear()
+  }
+}