@lincyaw/mcp 1.0.0-rc.0 → 1.0.0-rc.2

package/src/{stdio.ts → cli.ts}

@@ -2,42 +2,42 @@ import { stat } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
-import { errorMessage } from '@lincyaw/kernel'
-import type { ApprovalKind, Member } from '@lincyaw/kernel'
-import { buildView, Compiler, findPackageDir, resolveEntry, runBlock } from '@lincyaw/compiler'
+import { APPROVAL_KINDS, errorMessage, LOCAL_AUTHOR } from '@lincyaw/kernel'
+import type { ApprovalKind } from '@lincyaw/kernel'
+import { fileVersion } from '@lincyaw/kernel/node'
+import { buildSummary, buildToDist, Compiler, findPackageDir, resolveEntry, runBlock } from '@lincyaw/compiler'
 import type { Compilation } from '@lincyaw/compiler'
 import type { McpHost } from './host.ts'
 import { serveMcpStdio } from './mcp.ts'
+import { MCP_CLI_MESSAGES, systemLocale } from './messages.ts'
 
-const AUTHOR: Member = { id: 'local', name: 'local author', roles: ['owner'] }
-const KINDS: readonly ApprovalKind[] = ['operate', 'spend', 'write', 'agent']
 const OWN_DIR = fileURLToPath(new URL('..', import.meta.url))
 const CLI_PACKAGE = '@lincyaw/cli'
 
-const USAGE = `Usage: presmium-mcp [deck] [--allow <kinds>]
-
-Serves the deck (a directory holding lecture.md, or an entry file; default: .)
-as MCP tools and resources on stdio, for the agent of an editor.
-
-  --allow <kinds>  offer and allow these operations: operate (run_code, build), spend
-  -h, --help       show this help`
+const t = MCP_CLI_MESSAGES[systemLocale()]
 
 async function stamps(files: string[]): Promise<string> {
-  const times = await Promise.all(files.map(file => stat(file).then(s => s.mtimeMs, () => -1)))
+  const times = await Promise.all(files.map(file => stat(file, { bigint: true }).then(fileVersion, () => 'missing')))
   return times.join(',')
 }
 
-export function compilerHost(entry: string, allow: readonly ApprovalKind[]): McpHost {
+export function compilerMcpHost(entry: string, allow: readonly ApprovalKind[]): McpHost {
   const bundled = findPackageDir(CLI_PACKAGE, dirname(entry)) ?? findPackageDir(CLI_PACKAGE, OWN_DIR) ?? OWN_DIR
   const compiler = new Compiler(entry, { bundled })
+  let inputs = [entry]
   let latest: { compilation: Compilation, files: string[], stamp: string } | undefined
   let queue = Promise.resolve()
   const current = () => {
     const next = queue.then(async () => {
       if (latest && await stamps(latest.files) === latest.stamp) return latest.compilation
+      const before = await stamps(inputs)
       const compilation = await compiler.compile()
-      const files = [...compilation.files, ...compilation.dependencies.files]
-      latest = { compilation, files, stamp: await stamps(files) }
+      const files = [...new Set([...compilation.sourceFiles, ...compilation.inputs.files])]
+      const stamp = await stamps(files)
+      const known = new Set(inputs)
+      const stable = files.length === known.size && files.every(file => known.has(file)) && await stamps(inputs) === before
+      inputs = files
+      latest = stable ? { compilation, files, stamp } : undefined
       return compilation
     })
     queue = next.then(() => undefined, () => undefined)
@@ -50,6 +50,7 @@ export function compilerHost(entry: string, allow: readonly ApprovalKind[]): Mcp
   return {
     process: { command: 'presmium-mcp' },
     async documents() {
+      if (!await stat(entry).then(info => info.isFile(), () => false)) return []
       const { doc } = await current()
       return [{ dir: '', title: doc.meta.title, lang: doc.meta.lang }]
     },
@@ -62,13 +63,13 @@ export function compilerHost(entry: string, allow: readonly ApprovalKind[]): Mcp
       return [...compilation.doc.diagnostics, ...await compilation.check()]
     },
     async build(document, options) {
-      const report = await buildView(await only(document), { to: options.to })
-      return { outputs: report.outputs.map(({ renderer, outDir }) => ({ renderer, outDir })), findings: report.findings }
+      return buildSummary(await buildToDist(await only(document), { to: options.to }))
     },
     run: async (document, target, signal) => runBlock(await only(document), target, signal),
     approve: async request => allow.includes(request.kind),
     offers: kind => allow.includes(kind),
     async tools() {
+      if (!await stat(entry).then(info => info.isFile(), () => false)) return { tools: [], service: () => undefined }
       const compilation = await current()
       return { tools: compilation.plugins.flatMap(loaded => loaded.plugin?.tools ?? []), service: compilation.service }
     },
@@ -81,21 +82,20 @@ export async function main(argv: string[]): Promise<number | undefined> {
   try {
     const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { allow: { type: 'string' }, help: { type: 'boolean', short: 'h' } } })
     if (values.help) {
-      process.stdout.write(`${USAGE}\n`)
+      process.stdout.write(`${t.usage}\n`)
       return 0
     }
-    if (positionals.length > 1) throw new Error(`unexpected argument "${positionals[1]}"`)
+    if (positionals.length > 1) throw new Error(t.unexpectedArgument(positionals[1]!))
     deck = resolveEntry(positionals[0] ?? '.')
     allow = (values.allow?.split(',').map(kind => kind.trim()).filter(Boolean) ?? []) as ApprovalKind[]
-    const unknown = allow.find(kind => !KINDS.includes(kind))
-    if (unknown) throw new Error(`--allow takes ${KINDS.join(', ')}, not "${unknown}"`)
-    await stat(deck).catch(() => {
-      throw new Error(`${deck} not found`)
-    })
+    const unknown = allow.find(kind => !APPROVAL_KINDS.includes(kind))
+    if (unknown) throw new Error(t.badAllow(APPROVAL_KINDS, unknown))
+    const exists = await stat(deck).then(info => info.isFile(), () => false)
+    if (!exists && !await stat(positionals[0] ?? '.').then(info => info.isDirectory(), () => false)) throw new Error(t.notFound(deck))
   } catch (error) {
-    process.stderr.write(`presmium-mcp: ${errorMessage(error)}\n\n${USAGE}\n`)
+    process.stderr.write(`presmium-mcp: ${errorMessage(error)}\n\n${t.usage}\n`)
     return 2
   }
-  serveMcpStdio(compilerHost(deck, allow), { member: AUTHOR, mode: 'author' })
+  serveMcpStdio(compilerMcpHost(deck, allow), { member: LOCAL_AUTHOR, mode: 'author', document: '' })
   return undefined
 }

package/src/client.ts

@@ -1,7 +1,8 @@
 import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
-import { deckLocale, isRecord } from '@lincyaw/kernel'
+import { APPROVAL_KINDS, deckLocale, errorMessage, isRecord } from '@lincyaw/kernel'
 import type { ApprovalKind } from '@lincyaw/kernel'
 import { MCP_MESSAGES } from './messages.ts'
+import { TOOL_APPROVAL_META, TOOL_KIND_META } from './tool-meta.ts'
 
 export interface ListedTool {
   name: string
@@ -18,33 +19,129 @@ export interface CalledTool {
 
 export interface PresmiumMcpClient {
   tools(): Promise<ListedTool[]>
+  subscribeTools(changed: () => void): Promise<() => Promise<void>>
   call(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<CalledTool>
   read(uri: string): Promise<unknown>
+  subscribe(uri: string, changed: () => void): Promise<() => Promise<void>>
   close(): Promise<void>
 }
 
-const KINDS = new Set(['read', 'operate', 'spend', 'write', 'agent'])
+const KINDS = new Set<string>(['read', ...APPROVAL_KINDS])
 const CALL_TIMEOUT_MS = 10 * 60_000
 
 export async function connectPresmiumMcp(url: string, token: string, name = 'presmium-dsh'): Promise<PresmiumMcpClient> {
   const client = new Client({ name, version: '0.1.0' }, { versionNegotiation: { mode: 'auto' } })
   await client.connect(new StreamableHTTPClientTransport(new URL(url), { requestInit: { headers: { Authorization: `Bearer ${token}` } } }))
+  type Subscription = Awaited<ReturnType<Client['listen']>>
+  interface SubscriptionEntry {
+    key: string | symbol
+    label: string
+    filter: Parameters<Client['listen']>[0]
+    listeners: Set<() => void>
+    controller: AbortController
+    subscription?: Subscription
+    opening?: Promise<void>
+    queued: boolean
+  }
+  const toolsKey = Symbol('tools')
+  const subscriptions = new Map<string | symbol, SubscriptionEntry>()
+  let closed = false
+  const active = (entry: SubscriptionEntry) => !closed && subscriptions.get(entry.key) === entry && entry.listeners.size > 0
+  const changed = (entry: SubscriptionEntry) => {
+    if (!active(entry) || entry.queued) return
+    entry.queued = true
+    queueMicrotask(() => {
+      entry.queued = false
+      if (active(entry)) for (const listener of entry.listeners) listener()
+    })
+  }
+  const open = (entry: SubscriptionEntry): Promise<void> => {
+    if (entry.subscription) return Promise.resolve()
+    if (entry.opening) return entry.opening
+    const opening = client.listen(entry.filter, { signal: entry.controller.signal }).then(async (subscription) => {
+      if (!active(entry)) {
+        await subscription.close()
+        return
+      }
+      entry.subscription = subscription
+      void subscription.closed.then(async (reason) => {
+        if (entry.subscription !== subscription) return
+        entry.subscription = undefined
+        if (reason === 'local' || !active(entry)) return
+        changed(entry)
+        if (reason !== 'remote') return
+        await entry.opening
+        if (!active(entry)) return
+        try {
+          await open(entry)
+          changed(entry)
+        } catch (error) {
+          if (!active(entry)) return
+          console.error(`[presmium] the subscription to ${entry.label} did not reconnect: ${errorMessage(error)}`)
+          changed(entry)
+        }
+      })
+    }).finally(() => {
+      if (entry.opening === opening) entry.opening = undefined
+    })
+    entry.opening = opening
+    return opening
+  }
+  client.setNotificationHandler('notifications/resources/updated', (notification) => {
+    const entry = subscriptions.get(notification.params.uri)
+    if (entry) changed(entry)
+  })
+  client.setNotificationHandler('notifications/tools/list_changed', () => {
+    const entry = subscriptions.get(toolsKey)
+    if (entry) changed(entry)
+  })
+  client.onclose = () => { for (const entry of subscriptions.values()) changed(entry) }
+  const subscribe = async (key: string | symbol, label: string, filter: SubscriptionEntry['filter'], onChanged: () => void) => {
+    let entry = subscriptions.get(key)
+    if (!entry) {
+      entry = { key, label, filter, listeners: new Set(), controller: new AbortController(), queued: false }
+      subscriptions.set(key, entry)
+    }
+    const own = entry
+    const listener = () => onChanged()
+    own.listeners.add(listener)
+    const stop = async () => {
+      own.listeners.delete(listener)
+      if (own.listeners.size > 0 || subscriptions.get(key) !== own) return
+      subscriptions.delete(key)
+      own.controller.abort()
+      await own.subscription?.close()
+    }
+    try {
+      await open(own)
+    } catch (error) {
+      await stop()
+      throw error
+    }
+    return stop
+  }
   return {
     async tools() {
       const listed: ListedTool[] = []
       let cursor: string | undefined
       do {
-        const page = await client.listTools(cursor ? { cursor } : undefined)
+        const page = await client.listTools(cursor ? { cursor } : undefined, { cacheMode: 'refresh' })
         for (const tool of page.tools) {
           const meta = isRecord(tool._meta) ? tool._meta : {}
-          const kind = typeof meta['presmium/kind'] === 'string' && KINDS.has(meta['presmium/kind']) ? meta['presmium/kind'] as ListedTool['kind'] : (tool.annotations?.readOnlyHint ? 'read' : 'operate')
-          const approval = meta['presmium/approval'] === 'allow' ? 'allow' : meta['presmium/approval'] === 'ask' ? 'ask' : undefined
+          const kind = typeof meta[TOOL_KIND_META] === 'string' && KINDS.has(meta[TOOL_KIND_META]) ? meta[TOOL_KIND_META] as ListedTool['kind'] : (tool.annotations?.readOnlyHint ? 'read' : 'operate')
+          const approval = meta[TOOL_APPROVAL_META] === 'allow' ? 'allow' : meta[TOOL_APPROVAL_META] === 'ask' ? 'ask' : undefined
           listed.push({ name: tool.name, description: tool.description ?? tool.name, inputSchema: tool.inputSchema as Record<string, unknown>, kind, ...approval ? { approval } : {} })
         }
         cursor = page.nextCursor
       } while (cursor)
       return listed
     },
+    async subscribeTools(onChanged) {
+      if (closed) throw new Error('the MCP client is closed')
+      if (client.getProtocolEra() !== 'modern') throw new Error('live tool subscriptions need MCP 2026-07-28 or later')
+      if (!client.getServerCapabilities()?.tools?.listChanged) throw new Error('this MCP server does not offer tool-list subscriptions')
+      return subscribe(toolsKey, 'tools', { toolsListChanged: true }, onChanged)
+    },
     async call(tool, args, signal) {
       const result = await client.callTool({ name: tool, arguments: args }, { signal, timeout: CALL_TIMEOUT_MS })
       const content = Array.isArray(result.content) ? result.content as { type: string, text?: string }[] : []
@@ -59,7 +156,23 @@ export async function connectPresmiumMcp(url: string, token: string, name = 'pre
         return text
       }
     },
-    close: () => client.close(),
+    async subscribe(uri, onChanged) {
+      if (closed) throw new Error('the MCP client is closed')
+      if (client.getProtocolEra() !== 'modern') throw new Error('live resource subscriptions need MCP 2026-07-28 or later')
+      if (!client.getServerCapabilities()?.resources?.subscribe) throw new Error('this MCP server does not offer resource subscriptions')
+      return subscribe(uri, uri, { resourceSubscriptions: [uri] }, onChanged)
+    },
+    async close() {
+      closed = true
+      const entries = [...subscriptions.values()]
+      subscriptions.clear()
+      for (const entry of entries) entry.controller.abort()
+      try {
+        await Promise.all(entries.map(entry => entry.subscription?.close()))
+      } finally {
+        await client.close()
+      }
+    },
   }
 }
 
@@ -69,7 +182,13 @@ export function describeOperation(tool: string, args: Record<string, unknown>, l
   switch (tool) {
     case 'navigate': return m.navigate(text(args.section), typeof args.step === 'number' ? args.step : 0)
     case 'run_code': return m.run(text(args.section), text(args.block))
-    case 'build': return m.build(Array.isArray(args.to) && args.to.length ? args.to.join(', ') : m.allRenderers)
+    case 'build': return m.build(m.renderers(Array.isArray(args.to) ? args.to.map(text) : []))
+    case 'apply_document_change': return m.applyDocumentChange
+    case 'apply_page_duplication': return m.duplicatePage
+    case 'apply_page_change': return m.applyPagePlan
+    case 'start_transcription': return m.startTranscription
+    case 'cancel_transcription': return m.cancelTranscription
+    case 'apply_transcription_adoption': return m.adoptTranscription
     case 'classroom_start': return m.classroomStart(text(args.name))
     case 'classroom_end': return m.classroomEnd
     default: return m.tool(tool)

package/src/deck.ts

@@ -3,13 +3,8 @@ import { blockState, blockText, blockVisible, chapters, irBlocks, narrationAt, t
 import type { CodeNode, Finding, IRBlock, IRDocument, IRSection, RecordedRun, RunOutput, RunResult, SourcePos } from '@lincyaw/kernel'
 import MiniSearch from 'minisearch'
 
-export interface Place {
-  file: string
-  line: number
-  endLine?: number
-}
-
-export function place(doc: IRDocument, pos: SourcePos): Place {
+/** The source position with its file relative to the deck directory. */
+export function relativeToDeck(doc: IRDocument, pos: SourcePos): SourcePos {
   return { file: relative(dirname(doc.meta.entry), pos.file) || pos.file, line: pos.line, ...pos.endLine ? { endLine: pos.endLine } : {} }
 }
 
@@ -32,7 +27,7 @@ export function sectionSummary(doc: IRDocument, section: IRSection) {
     title: section.title,
     depth: section.depth,
     steps: section.steps,
-    source: place(doc, section.source),
+    source: relativeToDeck(doc, section.source),
     ...section.audience ? { audience: section.audience } : {},
   }
 }
@@ -43,7 +38,7 @@ export function deckInfo(doc: IRDocument, document: string) {
     document,
     title: doc.meta.title,
     lang: doc.meta.lang,
-    entry: place(doc, { file: doc.meta.entry, line: 1 }).file,
+    entry: relativeToDeck(doc, { file: doc.meta.entry, line: 1 }).file,
     sections: doc.sections.length,
     steps: doc.sections.reduce((sum, s) => sum + s.steps + 1, 0),
     plugins: doc.config.plugins,
@@ -70,7 +65,7 @@ export function blockInfo(doc: IRDocument, block: IRBlock, step?: number) {
     ...block.span ? { span: block.span } : {},
     ...block.only ? { only: block.only } : {},
     ...block.audience ? { audience: block.audience } : {},
-    source: place(doc, block.source),
+    source: relativeToDeck(doc, block.source),
   }
   if (node.type !== 'code') return { ...base, text: blockText(block) }
   const variant = state !== undefined ? node.variants?.[state] : undefined
@@ -121,7 +116,7 @@ export function codeRef(doc: IRDocument, section: IRSection, id: string) {
     lang: node.lang,
     ...node.title ? { title: node.title } : {},
     code: node.value,
-    source: place(doc, block.source),
+    source: relativeToDeck(doc, block.source),
     origin: origin(node) ?? null,
     ...node.variants ? { variants: node.variants.map(v => ({ label: v.label, ...v.startLine ? { startLine: v.startLine, endLine: v.endLine } : {} })) } : {},
     ...node.highlight ? { highlight: node.highlight } : {},
@@ -164,7 +159,7 @@ export function diagnosticsOf(doc: IRDocument, findings: Finding[]) {
     severity: f.severity,
     check: f.checkId,
     message: f.message,
-    ...f.source ? place(doc, { file: f.source.file, line: f.source.line ?? 1 }) : {},
+    ...f.source ? relativeToDeck(doc, { file: f.source.file, line: f.source.line ?? 1 }) : {},
     ...f.hint ? { hint: f.hint } : {},
   }))
 }
@@ -173,18 +168,18 @@ export function locate(doc: IRDocument, target: { section?: string, step?: numbe
   if (target.anchor) {
     const found = doc.sections.flatMap(section => [...irBlocks(section.blocks)]
       .filter(b => b.node.type === 'code' && b.node.origin?.anchor === target.anchor)
-      .map(b => ({ section: section.id, block: b.id, source: place(doc, b.source), code: origin(b.node as CodeNode) })))
+      .map(b => ({ section: section.id, block: b.id, source: relativeToDeck(doc, b.source), code: origin(b.node as CodeNode) })))
     if (found.length === 0) throw new Error(`no code block references ${target.anchor}`)
     return { anchor: target.anchor, references: found }
   }
   if (!target.section) throw new Error('name a section, or an anchor')
   const section = findSection(doc, target.section)
-  if (target.block) return { section: section.id, block: target.block, source: place(doc, findBlock(section, target.block).source) }
+  if (target.block) return { section: section.id, block: target.block, source: relativeToDeck(doc, findBlock(section, target.block).source) }
   if (target.step !== undefined) {
     const blocks = section.blocks.filter(b => b.at === target.step)
-    return { section: section.id, step: target.step, blocks: blocks.map(b => ({ block: b.id, role: b.role, source: place(doc, b.source) })) }
+    return { section: section.id, step: target.step, blocks: blocks.map(b => ({ block: b.id, role: b.role, source: relativeToDeck(doc, b.source) })) }
   }
-  return { section: section.id, source: place(doc, section.source) }
+  return { section: section.id, source: relativeToDeck(doc, section.source) }
 }
 
 const indexes = new WeakMap<IRDocument, MiniSearch>()

package/src/diagnostics.ts

@@ -0,0 +1,101 @@
+import { join, sep } from 'node:path'
+import { diagnosticOf, fnv1a64 } from '@lincyaw/kernel'
+import { irRevision } from '@lincyaw/kernel/node'
+import type { DiagnosticSnapshot, Finding, IRDocument } from '@lincyaw/kernel'
+import type { McpHost } from './host.ts'
+import type { Call, ToolSpec } from './mcp.ts'
+import { relativeToDeck } from './deck.ts'
+
+const RESPONSE_LIMIT = 7168
+const REQUEST_LIMIT = 2048
+const snapshots = new WeakMap<McpHost, Map<string, { compilation: string, snapshot: DiagnosticSnapshot }>>()
+const fail = (status: number, message: string): never => { throw Object.assign(new Error(message), { status }) }
+const fits = (value: unknown) => JSON.stringify(value, null, 2).length <= RESPONSE_LIMIT
+const boundary = (text: string, offset: number) => !(offset > 0 && offset < text.length && /[\uD800-\uDBFF]/.test(text[offset - 1]!) && /[\uDC00-\uDFFF]/.test(text[offset]!))
+
+function remember(host: McpHost, document: string, doc: IRDocument, findings: Finding[], origin: 'compile' | 'check'): DiagnosticSnapshot {
+  let documents = snapshots.get(host)
+  if (!documents) snapshots.set(host, documents = new Map())
+  const previous = documents.get(document), compilation = irRevision(doc)
+  const diagnostics = findings.map(finding => diagnosticOf(document, origin, {
+    ...finding,
+    ...finding.source ? { source: { ...finding.source, file: join(document, relativeToDeck(doc, { ...finding.source, line: finding.source.line ?? 1 }).file).split(sep).join('/') } } : {},
+  }))
+  const same = previous?.compilation === compilation && JSON.stringify(previous.snapshot.diagnostics) === JSON.stringify(diagnostics)
+  const snapshot = same ? previous.snapshot : { version: (previous?.snapshot.version ?? 0) + 1, diagnostics }
+  documents.set(document, { compilation, snapshot })
+  return snapshot
+}
+
+/** Legacy compiler-only resources can compile; passive tools only read actual observations. */
+export async function diagnosticSnapshot(call: Call): Promise<DiagnosticSnapshot> {
+  const document = await call.document()
+  if (call.host.diagnostics) return call.host.diagnostics(document)
+  const { doc, diagnostics } = await call.compiled(), previous = snapshots.get(call.host)?.get(document)
+  if (previous?.compilation === irRevision(doc)) return previous.snapshot
+  return remember(call.host, document, doc, diagnostics, 'compile')
+}
+
+function query(call: Call) {
+  if (JSON.stringify(call.args).length > REQUEST_LIMIT) return fail(413, 'diagnostic-read-request-too-large')
+  if (Object.keys(call.args).some(key => !['document', 'version', 'digest', 'offset'].includes(key))) return fail(400, 'diagnostic-read-query-invalid')
+  const { version, digest, offset = 0 } = call.args
+  if (call.args.document !== undefined && (typeof call.args.document !== 'string' || call.args.document.length > 200)) return fail(400, 'diagnostic-read-document-invalid')
+  if (version !== undefined && (!Number.isSafeInteger(version) || Number(version) < 0)) return fail(400, 'diagnostic-read-version-invalid')
+  if (digest !== undefined && (typeof digest !== 'string' || !/^[a-f\d]{16}$/.test(digest))) return fail(400, 'diagnostic-read-digest-invalid')
+  if (!Number.isSafeInteger(offset) || Number(offset) < 0) return fail(400, 'diagnostic-read-offset-invalid')
+  if (Number(offset) > 0 && (version === undefined || digest === undefined)) return fail(400, 'diagnostic-read-continuation-required')
+  return { version, digest, offset: Number(offset) }
+}
+
+async function read(call: Call) {
+  const asked = query(call), document = await call.document()
+  const snapshot = call.host.diagnostics ? await call.host.diagnostics(document) : snapshots.get(call.host)?.get(document)?.snapshot
+  if (!snapshot) return { document, available: false, reason: 'snapshot-unavailable', verification: 'unobserved', next: 'check_document' }
+  const text = JSON.stringify(snapshot), digest = fnv1a64(text)
+  if (asked.version !== undefined && asked.version !== snapshot.version || asked.digest !== undefined && asked.digest !== digest) return fail(409, 'diagnostic-snapshot-changed')
+  if (asked.offset > text.length || !boundary(text, asked.offset)) return fail(400, 'diagnostic-read-offset-invalid')
+  const base = { document, available: true, version: snapshot.version, digest, verification: 'unobserved' as const }
+  const whole = { ...base, encoding: 'value', complete: true, value: snapshot }
+  if (asked.offset === 0 && fits(whole)) return whole
+  const fragment = (end: number) => ({ ...base, encoding: 'json-text-fragment', offsetUnit: 'utf16', offset: asked.offset,
+    ...end < text.length ? { nextOffset: end } : {}, totalChars: text.length, complete: end === text.length, text: text.slice(asked.offset, end) })
+  let low = asked.offset, high = text.length
+  while (low < high) { const mid = Math.ceil((low + high) / 2); if (fits(fragment(mid))) low = mid; else high = mid - 1 }
+  if (!boundary(text, low)) low--
+  if (low === asked.offset && low < text.length || !fits(fragment(low))) return fail(413, 'diagnostic-read-response-too-large')
+  return fragment(low)
+}
+
+async function check(call: Call) {
+  if (Object.keys(call.args).some(key => key !== 'document') || call.args.document !== undefined && (typeof call.args.document !== 'string' || call.args.document.length > 200)) return fail(400, 'diagnostic-check-query-invalid')
+  const document = await call.document()
+  // Hosts with a real diagnostic producer publish their own check contribution.
+  const compiled = call.host.diagnostics ? undefined : await call.compiled()
+  const findings = await call.host.check(document)
+  call.signal.throwIfAborted()
+  const snapshot = call.host.diagnostics ? await call.host.diagnostics(document) : remember(call.host, document, compiled!.doc, findings, 'check')
+  return { document, completed: true, findings: { total: findings.length,
+    errors: findings.filter(finding => finding.severity === 'error').length,
+    warnings: findings.filter(finding => finding.severity === 'warning').length,
+    infos: findings.filter(finding => finding.severity === 'info').length },
+    snapshot: { version: snapshot.version, digest: fnv1a64(JSON.stringify(snapshot)) },
+    verification: { currentSource: 'unverified', browser: 'unobserved' }, next: 'get_diagnostics' }
+}
+
+export const DIAGNOSTIC_TOOLS: ToolSpec[] = [
+  {
+    name: 'get_diagnostics', kind: 'read', structured: true,
+    description: 'Reads the same current diagnostic snapshot as the workbench, without compiling or running plugin checks. Entries retain their origins and reported revisions; an empty snapshot does not verify current source or browser health. Replies fit 7168 pretty-JSON UTF-16 characters. encoding:value contains the complete snapshot; json-text-fragment requires concatenating decoded text in nextOffset order then JSON.parse once. Continue with the returned version AND digest; changed snapshots return 409. Digest is fnv1a64 of JSON.stringify(snapshot). No snapshot producer or prior observation returns unavailable. Use check_document only when explicitly requesting compilation and plugin checks.',
+    inputSchema: { type: 'object', additionalProperties: false, properties: {
+      document: { type: 'string', maxLength: 200 }, version: { type: 'integer', minimum: 0 }, digest: { type: 'string', pattern: '^[a-f\\d]{16}$' }, offset: { type: 'integer', minimum: 0 },
+    } },
+    run: read,
+  },
+  {
+    name: 'check_document', kind: 'read', structured: true,
+    description: 'Explicitly runs document compilation and plugin checks. Returns bounded counts and the actual diagnostic snapshot version/digest; read full observations with get_diagnostics. It does not synthesize speech, export, play or prove a browser rendered the current source. Checks can execute project plugin code and may take time; do not use this tool merely to read current problems. Current-source verification is not established by these counts.',
+    inputSchema: { type: 'object', additionalProperties: false, properties: { document: { type: 'string', maxLength: 200 } } },
+    run: check,
+  },
+]

package/src/focus.ts

@@ -2,34 +2,38 @@ import { readFileSync } from 'node:fs'
 import { dirname, isAbsolute, join, normalize, sep } from 'node:path'
 import { docBlocks, isRecord } from '@lincyaw/kernel'
 import type { Focus, FocusReport, IRDocument, SourceRange } from '@lincyaw/kernel'
-import { findBlock, findSection, place } from './deck.ts'
+import { findBlock, findSection, relativeToDeck } from './deck.ts'
 
-export const EXCERPT_LINES = 20
+const EXCERPT_LINES = 20
 const QUOTE_CHARS = 2000
+const WORKSPACE_EXCERPT_CHARS = 8000
 const FROM = new Set<Focus['from']>(['source', 'web', 'slides'])
 
 const str = (value: unknown, max = 200) => (typeof value === 'string' && value !== '' && value.length <= max ? value : undefined)
 const line = (value: unknown) => (typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined)
 
-export function focusReport(value: unknown): FocusReport | string {
+export function toFocusReport(value: unknown): FocusReport | string {
   if (!isRecord(value)) return 'a focus is an object'
   const id = str(value.id)
   const from = value.from as Focus['from']
   if (!id) return 'a focus has an id'
   if (!FROM.has(from)) return 'a focus is from source, web or slides'
+  if (value.scope !== undefined && value.scope !== 'document' && value.scope !== 'workspace') return 'a focus scope is document or workspace'
   const source = isRecord(value.source) ? value.source : undefined
   const range = source && str(source.file, 1000) && line(source.startLine) ? { file: source.file as string, startLine: source.startLine as number, endLine: line(source.endLine) ?? source.startLine as number } : undefined
   if (source && !range) return 'a focus\'s source is { file, startLine, endLine }'
   const report: FocusReport = { id, from }
+  if (value.scope === 'workspace' || value.scope === 'document') report.scope = value.scope
   for (const key of ['section', 'block'] as const) if (str(value[key])) report[key] = value[key] as string
   if (typeof value.step === 'number' && Number.isInteger(value.step) && value.step >= 0) report.step = value.step
   if (typeof value.quote === 'string' && value.quote.trim()) report.quote = value.quote.slice(0, QUOTE_CHARS)
   if (range) report.source = range
   if (!report.section && !report.block && !report.source) return 'a focus names a section, a block or a range of the source'
+  if (report.scope === 'workspace' && (report.from !== 'source' || !report.source || report.section || report.block || report.step !== undefined)) return 'a workspace focus is a source range without a section, block or step'
   return report
 }
 
-export function excerptOf(text: string, start: number, end: number): string {
+function excerptOf(text: string, start: number, end: number): string {
   const lines = text.split(/\r?\n/).slice(start - 1, end)
   if (lines.length <= EXCERPT_LINES) return lines.join('\n')
   const half = EXCERPT_LINES / 2
@@ -39,21 +43,29 @@ export function excerptOf(text: string, start: number, end: number): string {
 function blockAt(doc: IRDocument, range: SourceRange): { section: string, block?: string } | undefined {
   let found: { section: string, block: string, span: number } | undefined
   for (const { section, block } of docBlocks(doc)) {
-    const at = place(doc, block.source)
+    const at = relativeToDeck(doc, block.source)
     const end = at.endLine ?? at.line
     if (at.file !== range.file || range.startLine < at.line || range.startLine > end) continue
     if (!found || end - at.line < found.span) found = { section: section.id, block: block.id, span: end - at.line }
   }
   if (found) return { section: found.section, block: found.block }
   const sections = doc.sections.filter((s) => {
-    const at = place(doc, s.source)
+    const at = relativeToDeck(doc, s.source)
     return at.file === range.file && at.line <= range.startLine
   })
   const section = sections.at(-1)
   return section && { section: section.id }
 }
 
-export function resolveFocus(doc: IRDocument, document: string, report: FocusReport, read: (file: string) => string = file => readFileSync(file, 'utf8')): Focus {
+export function resolveFocus(doc: IRDocument | undefined, document: string, report: FocusReport, read: (file: string) => string = file => readFileSync(file, 'utf8'), readWorkspaceFile?: (file: string) => string): Focus {
+  if (report.scope === 'workspace') {
+    if (!readWorkspaceFile || !report.source) throw new Error('this host does not read workspace source selections')
+    const range = report.source
+    const source = { ...range, endLine: Math.max(range.startLine, range.endLine) }
+    const excerpt = excerptOf(readWorkspaceFile(source.file), source.startLine, source.endLine)
+    return { id: report.id, from: report.from, document, scope: 'workspace', source, excerpt: excerpt.length > WORKSPACE_EXCERPT_CHARS ? `${excerpt.slice(0, WORKSPACE_EXCERPT_CHARS)}\n[… excerpt truncated …]` : excerpt, ...report.quote ? { quote: report.quote } : {} }
+  }
+  if (!doc) throw new Error('a document focus requires the compiled document')
   const deckDir = dirname(doc.meta.entry)
   let source: SourceRange
   let section = report.section
@@ -61,7 +73,7 @@ export function resolveFocus(doc: IRDocument, document: string, report: FocusRep
   if (report.block || (report.section && !report.source)) {
     const found = findSection(doc, report.section ?? [...docBlocks(doc)].find(b => b.block.id === report.block)?.section.id ?? '')
     section = found.id
-    const at = report.block ? place(doc, findBlock(found, report.block).source) : place(doc, found.source)
+    const at = report.block ? relativeToDeck(doc, findBlock(found, report.block).source) : relativeToDeck(doc, found.source)
     source = { file: at.file, startLine: at.line, endLine: at.endLine ?? at.line }
   } else {
     const range = report.source!

package/src/history.ts

@@ -0,0 +1,38 @@
+import { DOCUMENT_HISTORY_CHANGE_SCHEMA, DOCUMENT_HISTORY_MAX_REQUEST_CHARS, DOCUMENT_HISTORY_QUERY_SCHEMA, DOCUMENT_HISTORY_READ_SCHEMA } from '@lincyaw/kernel'
+import type { DocumentHistory, DocumentHistoryQuery } from '@lincyaw/kernel'
+import type { Call, ToolSpec } from './mcp.ts'
+import { validateDocumentHistoryRead, validateDocumentHistoryChange } from '@lincyaw/kernel/node'
+
+const documentProperty = { type: 'string', maxLength: 200, description: 'The served document directory; empty string names the root document, never the entire workspace.' }
+const service = (call: Call): DocumentHistory => {
+  if (!call.host.documentHistory) throw Object.assign(new Error('history-host-unavailable'), { status: 503 })
+  return call.host.documentHistory
+}
+const budget = (call: Call) => { if (JSON.stringify(call.args).length > DOCUMENT_HISTORY_MAX_REQUEST_CHARS) throw Object.assign(new Error('history-request-too-large'), { status: 413 }) }
+const readSchema = (schema: typeof DOCUMENT_HISTORY_QUERY_SCHEMA | typeof DOCUMENT_HISTORY_READ_SCHEMA) => ({ ...schema, properties: { document: documentProperty, ...schema.properties } })
+const readArgs = (call: Call) => { budget(call); const { document: _document, ...query } = call.args; return query }
+export const HISTORY_TOOLS: ToolSpec[] = [
+  {
+    name: 'get_document_history', kind: 'read', structured: true, inputSchema: readSchema(DOCUMENT_HISTORY_QUERY_SCHEMA),
+    description: 'Reads the served document’s actual git history and exact next undo/redo IDs, without compiling or restoring. Root document "" is scoped. At most 20 compact entries and 7168 UTF-16 response characters; summaries/file lists may be abbreviated. Continue with snapshot and nextOffset. The historyBinding contains saved raw source plus actual git HEAD; malformed current JSON is still readable. No git returns available:false. Viewing never changes files.',
+    run: async call => service(call).list(await call.document(), readArgs(call) as DocumentHistoryQuery, call.caller.member),
+  },
+  {
+    name: 'read_history_file', kind: 'read', structured: true, inputSchema: readSchema(DOCUMENT_HISTORY_READ_SCHEMA),
+    description: 'Reads a regular UTF-8 file at an exact reachable historical commit, scoped to this served document. Defaults to its lecture.json. Replies are bounded text fragments with actual SHA-256 and nextOffset; append decoded text and parse JSON only after complete. Rejects hidden, binary, symlink, cross-document and oversized files. This is a historical view, never checkout, restore, discard, compile or validation of the current document.',
+    run: async call => { const query = readArgs(call); if (!validateDocumentHistoryRead(query)) throw Object.assign(new Error('history-read-invalid'), { status: 400 }); return service(call).read(await call.document(), query, call.caller.member) },
+  },
+  ...(['undo', 'redo', 'revert'] as const).map((which): ToolSpec => ({
+    name: `${which}_document_change`, kind: 'operate', structured: true,
+    inputSchema: { type: 'object', additionalProperties: false, required: ['request'], properties: { document: documentProperty, request: DOCUMENT_HISTORY_CHANGE_SCHEMA } },
+    description: `Explicitly ${which}s ${which === 'revert' ? 'the specified reachable historical change' : 'the exact next target'} returned by get_document_history using its historyBinding and full expect commit. Requires host operate approval and existing editor/lock/review permissions. Refuses changed source/HEAD/target, mixed-document commits and uncommitted target files; never silently rebase. Use a stable intent id and retry identical input after lost ACK only while the returned result HEAD/source is current (64 process-local receipts). Uses the same Revisions transaction as Web; does not discard drafts, checkout, compile or play.`,
+    run: async call => {
+      budget(call)
+      const document = await call.document(), request = call.args.request
+      if (!validateDocumentHistoryChange(request)) throw Object.assign(new Error('history-change-invalid'), { status: 400 })
+      const lang = (await call.host.documents()).find(item => item.dir === document)?.lang ?? 'zh-CN'
+      await call.approve('operate', m => m.historyChange(which, request.expect), { lang, check: () => service(call).checkChange(document, which, request, call.caller.member, 'agent') })
+      return service(call).change(document, which, request, call.caller.member, 'agent')
+    },
+  })),
+]