@ljwei-stak/dsh-model-route-bot 0.66.4 → 0.67.0

package/packages/orchestration/src/desktop-proxy.mjs

@@ -0,0 +1,311 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import { WebSocketServer } from 'ws'
+
+export const DESKTOP_PROXY_PATH = '/bot-product/desktop/v1/socket'
+export const DESKTOP_PROXY_LIMITS = Object.freeze({ maxConnections: 16, maxTickets: 32, authTimeoutMs: 5000,
+  maxPayload: 9 * 1024 * 1024, maxBufferedBytes: 12 * 1024 * 1024, maxQueuedFrames: 64, maxTicketMs: 300_000 })
+export const DESKTOP_PROXY_UPSTREAM_OPTIONS = Object.freeze({ autoPong: false, perMessageDeflate: false, maxPayload: DESKTOP_PROXY_LIMITS.maxPayload })
+
+const fail = code => { throw Object.assign(new Error(code), { code }) }
+const identifier = value => typeof value === 'string' && /^[-A-Za-z0-9_.]{1,128}$/u.test(value)
+const token = value => typeof value === 'string' && /^[A-Za-z0-9_-]{43}$/u.test(value)
+const digest = value => createHash('sha256').update(value).digest()
+const matches = (value, expected) => token(value) && timingSafeEqual(digest(value), expected)
+const isSignal = signal => signal && typeof signal.addEventListener === 'function' && typeof signal.removeEventListener === 'function'
+const owner = peer => peer?.principal?.kind === 'owner' && isSignal(peer.signal) && !peer.signal.aborted
+const originOf = value => {
+  if (typeof value !== 'string') fail('DESKTOP_PROXY_ORIGIN_DENIED')
+  try {
+    const url = new URL(value)
+    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== value || url.username || url.password) fail('DESKTOP_PROXY_ORIGIN_DENIED')
+    return value
+  } catch { fail('DESKTOP_PROXY_ORIGIN_DENIED') }
+}
+const synchronous = value => {
+  if (value && typeof value.then === 'function') {
+    Promise.resolve(value).catch(() => {})
+    fail('DESKTOP_PROXY_AUTHORITY_INVALID')
+  }
+  return value
+}
+const bufferOf = data => Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data)
+
+export function desktopTicketMetadata(ticket) {
+  const result = { sessionId: ticket.sessionId, expiresAt: ticket.expiresAt }
+  for (const key of ['taskId', 'attemptId', 'displayId', 'coordinateSpace']) {
+    if (typeof ticket[key] === 'string' && ticket[key].length <= 256 && !/[\u0000-\u001f]/u.test(ticket[key])) result[key] = ticket[key]
+  }
+  if (['watch', 'control'].includes(ticket.mode)) result.mode = ticket.mode
+  for (const key of ['canControl', 'controlAllowed']) if (typeof ticket[key] === 'boolean') result[key] = ticket[key]
+  for (const key of ['width', 'height', 'fps']) if (Number.isSafeInteger(ticket[key]) && ticket[key] > 0) result[key] = ticket[key]
+  if (Array.isArray(ticket.displays)) result.displays = Object.freeze(ticket.displays.slice(0, 32).map(display => {
+    const row = {}
+    for (const key of ['id', 'name']) if (typeof display?.[key] === 'string' && display[key].length <= 256 && !/[\u0000-\u001f]/u.test(display[key])) row[key] = display[key]
+    for (const key of ['width', 'height', 'x', 'y', 'dpi', 'scaleFactor']) if (Number.isFinite(display?.[key])) row[key] = display[key]
+    if (typeof display?.primary === 'boolean') row.primary = display.primary
+    return Object.freeze(row)
+  }))
+  return result
+}
+
+/**
+ * Host-only desktop carrier. validate is synchronous and closes over committed authority;
+ * connect creates a paired upstream Node ws with DESKTOP_PROXY_UPSTREAM_OPTIONS.
+ * ownerPeer must be the exact Peer admitted for the ticket's originating owner action.
+ */
+export function createDesktopProxy({ webServer, connection, now = Date.now }) {
+  if (typeof webServer?.registerUpgrade !== 'function' || !['http:', 'https:'].includes(webServer.protocol)
+    || typeof connection?.admitConnection !== 'function' || typeof connection?.admit !== 'function' || typeof now !== 'function') fail('DESKTOP_PROXY_REQUIRES_HOST')
+  const limits = DESKTOP_PROXY_LIMITS, rows = new Map(), states = new Set(), signalWatches = new Map(), releases = new Set()
+  const sockets = new WebSocketServer({ noServer: true, autoPong: false, perMessageDeflate: false,
+    maxPayload: limits.maxPayload, maxFragments: 1024, maxBufferedChunks: 1024 })
+  sockets.on('error', () => {})
+  let closing = false, closed
+
+  const watch = (signal, callback) => {
+    if (!signal || typeof signal.addEventListener !== 'function' || typeof signal.removeEventListener !== 'function') fail('DESKTOP_PROXY_AUTHORITY_INVALID')
+    let entry = signalWatches.get(signal)
+    if (!entry) {
+      entry = { callbacks: new Set(), abort: () => { for (const fn of [...entry.callbacks]) fn() } }
+      signalWatches.set(signal, entry); signal.addEventListener('abort', entry.abort, { once: true })
+    }
+    entry.callbacks.add(callback)
+    return () => {
+      entry.callbacks.delete(callback)
+      if (!entry.callbacks.size) { signal.removeEventListener('abort', entry.abort); signalWatches.delete(signal) }
+    }
+  }
+  const release = state => {
+    if (!state.admission || state.released) return
+    state.released = true
+    let result
+    try { result = state.admission.release() } catch { return }
+    const pending = Promise.resolve(result).catch(() => {})
+    releases.add(pending); void pending.finally(() => releases.delete(pending))
+  }
+  const endRow = row => {
+    if (row.ended) return
+    row.ended = true; row.secret = null; row.connect = null; row.validate = null; row.active = null
+    for (const off of row.unwatch) off()
+    row.unwatch = []
+  }
+  const rejectHttp = (state, status) => {
+    if (state.raw.destroyed) return
+    const reason = { 400: 'Bad Request', 401: 'Unauthorized', 403: 'Forbidden', 409: 'Conflict', 429: 'Too Many Requests', 503: 'Service Unavailable' }[status] ?? 'Forbidden'
+    const text = `HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`
+    const timer = setTimeout(() => state.raw.destroy(), 250); timer.unref()
+    state.raw.once('close', () => clearTimeout(timer))
+    try { state.raw.end(text, () => state.raw.destroy()) } catch { state.raw.destroy() }
+  }
+  const stop = (state, code = 'DESKTOP_PROXY_DISCONNECTED', closeCode = 1008, httpStatus) => {
+    if (state.ended) return
+    state.ended = true; states.delete(state); clearTimeout(state.timer); state.controller.abort()
+    state.unwatch?.(); state.unwatch = null
+    if (state.row) endRow(state.row)
+    for (const channel of [state.toBrowser, state.toAgent]) { channel.queue = []; channel.bytes = 0; channel.count = 0 }
+    if (state.upstream) {
+      try { state.upstream.terminate() } catch {}
+    }
+    if (state.browser) {
+      const ws = state.browser
+      if (ws.readyState === 1) {
+        try {
+          if (ws.bufferedAmount <= 2048) ws.send(JSON.stringify({ type: 'error', code }), { compress: false }, () => {})
+          ws.close(closeCode, code)
+        } catch { ws.terminate() }
+      } else if (ws.readyState !== 3) ws.terminate()
+      if (ws.readyState !== 3) { const timer = setTimeout(() => ws.terminate(), 250); timer.unref(); ws.once('close', () => clearTimeout(timer)) }
+    } else if (httpStatus) rejectHttp(state, httpStatus)
+    else state.raw.destroy()
+    release(state)
+  }
+  const checkRow = row => {
+    if (closing || row.ended || !owner(row.ownerPeer) || row.signal?.aborted || row.expiresAt <= now()) fail('DESKTOP_PROXY_REVOKED')
+    if (synchronous(row.validate({ sessionId: row.sessionId, ownerPeer: row.ownerPeer })) === false) fail('DESKTOP_PROXY_REVOKED')
+  }
+  const check = state => {
+    if (state.ended || closing || !owner(state.admission?.peer) || state.deadline !== null && state.deadline <= now()) fail('DESKTOP_PROXY_REVOKED')
+    const admission = synchronous(connection.admit(state.request))
+    if (!admission || 'rejection' in admission || admission.peer !== state.admission.peer || !owner(admission.peer)) fail('DESKTOP_PROXY_REVOKED')
+    if (state.row) checkRow(state.row)
+  }
+  const channelOf = () => ({ target: null, queue: [], bytes: 0, count: 0, sending: false })
+  const pump = (state, channel) => {
+    if (state.ended || channel.sending || channel.target?.readyState !== 1 || !channel.queue.length) return
+    try { check(state) } catch { stop(state, 'DESKTOP_PROXY_REVOKED'); return }
+    const item = channel.queue.shift(), target = channel.target
+    channel.sending = true
+    const done = error => {
+      if (state.ended) return
+      channel.sending = false; channel.bytes -= item.data.length; channel.count -= 1
+      if (error) stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011)
+      else pump(state, channel)
+    }
+    try {
+      if (item.kind === 'message') target.send(item.data, { binary: item.binary, compress: false }, done)
+      else target[item.kind](item.data, undefined, done)
+    } catch { stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011) }
+  }
+  const enqueue = (state, channel, kind, data, binary = false) => {
+    if (state.ended) return
+    try {
+      check(state)
+      const bytes = bufferOf(data), size = bytes.length, buffered = channel.target?.bufferedAmount ?? 0
+      if (size > limits.maxPayload || kind !== 'message' && size > 125 || kind === 'message' && !binary && size > 65536) {
+        stop(state, 'DESKTOP_PROXY_MESSAGE_LIMIT', 1009); return
+      }
+      if (!Number.isFinite(buffered) || Math.max(channel.bytes, buffered) + size > limits.maxBufferedBytes || channel.count >= limits.maxQueuedFrames) {
+        stop(state, 'DESKTOP_PROXY_BACKPRESSURE', 1013); return
+      }
+      channel.queue.push({ kind, data: bytes, binary }); channel.bytes += size; channel.count += 1
+      pump(state, channel)
+    } catch { stop(state, 'DESKTOP_PROXY_REVOKED') }
+  }
+  const attachUpstream = (state, upstream) => {
+    if (!upstream || typeof upstream.on !== 'function' || typeof upstream.terminate !== 'function') fail('DESKTOP_PROXY_UNAVAILABLE')
+    upstream.on('error', () => stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011))
+    if (state.ended) { upstream.terminate(); return }
+    state.upstream = upstream
+    if (![0, 1].includes(upstream.readyState) || ['send', 'ping', 'pong'].some(name => typeof upstream[name] !== 'function')) fail('DESKTOP_PROXY_UNAVAILABLE')
+    upstream.once('close', () => stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011))
+    upstream.on('message', (data, binary) => enqueue(state, state.toBrowser, 'message', data, binary))
+    // DS Desktop uses the pong after a JPEG as its receipt. Neither proxy leg may auto-pong.
+    upstream.on('ping', data => enqueue(state, state.toBrowser, 'ping', data))
+    upstream.on('pong', data => enqueue(state, state.toBrowser, 'pong', data))
+    let opened = false
+    const open = () => {
+      if (opened || state.ended) return
+      opened = true
+      try { check(state) } catch { stop(state, 'DESKTOP_PROXY_REVOKED'); return }
+      clearTimeout(state.timer); state.deadline = null; state.phase = 'forwarding'
+      state.toAgent.target = upstream; pump(state, state.toAgent)
+    }
+    upstream.once('open', open)
+    if (upstream.readyState === 1) open()
+  }
+  const authenticate = (state, data, binary) => {
+    let row
+    try {
+      if (binary || bufferOf(data).length > 2048) fail('DESKTOP_PROXY_AUTH_INVALID')
+      const value = JSON.parse(bufferOf(data).toString('utf8'))
+      if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !['type', 'sessionId', 'token'].includes(key))
+        || value.type !== 'auth' || !identifier(value.sessionId) || !token(value.token)) fail('DESKTOP_PROXY_AUTH_INVALID')
+      row = rows.get(value.sessionId)
+      if (!row || row.used || row.ended || row.ownerPeer !== state.admission.peer || row.clientOrigin !== state.origin || !matches(value.token, row.proxyDigest)) fail('DESKTOP_PROXY_AUTH_INVALID')
+      check(state); checkRow(row)
+    } catch { stop(state, 'DESKTOP_PROXY_AUTH_INVALID'); return }
+    row.used = true; row.active = state; state.row = row; state.phase = 'connecting'
+    clearTimeout(state.timer); state.deadline = now() + limits.authTimeoutMs
+    state.timer = setTimeout(() => stop(state, 'DESKTOP_PROXY_CONNECT_TIMEOUT', 1011), limits.authTimeoutMs); state.timer.unref()
+    const connect = row.connect, auth = Buffer.from(JSON.stringify({ type: 'auth', sessionId: row.sessionId, token: row.secret }))
+    row.secret = null
+    enqueue(state, state.toAgent, 'message', auth)
+    if (state.ended) return
+    try {
+      Promise.resolve(connect({ signal: state.controller.signal, sessionId: row.sessionId, webSocketOptions: DESKTOP_PROXY_UPSTREAM_OPTIONS }))
+        .then(upstream => { try { attachUpstream(state, upstream) } catch { stop(state, 'DESKTOP_PROXY_UNAVAILABLE', 1011) } }, () => stop(state, 'DESKTOP_PROXY_UNAVAILABLE', 1011))
+    } catch { stop(state, 'DESKTOP_PROXY_UNAVAILABLE', 1011) }
+  }
+  const accept = (state, browser) => {
+    if (state.ended) { browser.on('error', () => {}); browser.terminate(); return }
+    state.browser = browser; state.toBrowser.target = browser
+    browser.on('error', () => stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011))
+    browser.once('close', () => stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011))
+    browser.on('message', (data, binary) => state.phase === 'auth' ? authenticate(state, data, binary) : enqueue(state, state.toAgent, 'message', data, binary))
+    for (const kind of ['ping', 'pong']) browser.on(kind, data => {
+      if (state.phase === 'auth') stop(state, 'DESKTOP_PROXY_AUTH_INVALID')
+      else enqueue(state, state.toAgent, kind, data)
+    })
+    state.raw.resume()
+  }
+  const handleUpgrade = async (request, raw, head) => {
+    const state = { raw, browser: null, upstream: null, row: null, ended: false, released: false, admission: null,
+      phase: 'auth', controller: new AbortController(), toBrowser: channelOf(), toAgent: channelOf(), deadline: now() + limits.authTimeoutMs }
+    raw.on('error', () => stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011))
+    raw.once('close', () => stop(state, 'DESKTOP_PROXY_DISCONNECTED', 1011))
+    raw.pause()
+    state.timer = setTimeout(() => stop(state, 'DESKTOP_PROXY_AUTH_REQUIRED', 1008, 401), limits.authTimeoutMs); state.timer.unref()
+    if (closing || states.size >= limits.maxConnections) { stop(state, 'DESKTOP_PROXY_CONNECTION_LIMIT', 1013, closing ? 503 : 429); return }
+    states.add(state)
+    try {
+      if (request.url !== DESKTOP_PROXY_PATH || head.length > 8192 || request.headers['sec-websocket-protocol'] !== undefined) { stop(state, 'DESKTOP_PROXY_REQUEST_INVALID', 1008, 400); return }
+      state.origin = originOf(request.headers.origin)
+      const host = request.headers.host
+      if (typeof host !== 'string' || new URL(`${webServer.protocol}//${host}`).origin !== state.origin) { stop(state, 'DESKTOP_PROXY_ORIGIN_DENIED', 1008, 403); return }
+      state.request = { headers: Object.freeze(Object.fromEntries(Object.entries(request.headers).map(([key, value]) => [key, Array.isArray(value) ? Object.freeze([...value]) : value]))) }
+      const admission = await connection.admitConnection(state.request)
+      if (admission && !('rejection' in admission) && typeof admission.release === 'function') state.admission = admission
+      if (state.ended) { release(state); return }
+      if (!state.admission || !owner(admission.peer)) { stop(state, 'DESKTOP_PROXY_AUTH_INVALID', 1008, admission?.rejection === 401 ? 401 : admission?.rejection === 409 ? 409 : 403); return }
+      check(state)
+      state.unwatch = watch(admission.peer.signal, () => stop(state, 'DESKTOP_PROXY_REVOKED'))
+      if (admission.peer.signal.aborted || state.ended) { stop(state, 'DESKTOP_PROXY_REVOKED', 1008, 403); return }
+      sockets.handleUpgrade(request, raw, head, browser => accept(state, browser))
+    } catch { stop(state, 'DESKTOP_PROXY_AUTH_INVALID', 1008, 403) }
+  }
+  const unregister = webServer.registerUpgrade({ path: DESKTOP_PROXY_PATH, handler: handleUpgrade })
+  const sweep = setInterval(() => {
+    for (const state of [...states]) {
+      if (state.deadline !== null && state.deadline <= now()) { stop(state, state.phase === 'auth' ? 'DESKTOP_PROXY_AUTH_REQUIRED' : 'DESKTOP_PROXY_CONNECT_TIMEOUT', 1008, state.browser ? undefined : 401); continue }
+      if (state.admission) try { check(state) } catch { stop(state, 'DESKTOP_PROXY_REVOKED') }
+    }
+    for (const [key, row] of rows) {
+      if (row.expiresAt <= now()) { if (row.active) stop(row.active, 'DESKTOP_PROXY_EXPIRED'); endRow(row); rows.delete(key) }
+      else if (!row.ended) try { checkRow(row) } catch { if (row.active) stop(row.active, 'DESKTOP_PROXY_REVOKED'); endRow(row) }
+    }
+  }, 100)
+  sweep.unref()
+
+  return Object.freeze({
+    wrapTicket(ticket, { ownerPeer, clientOrigin, connect, validate, signal } = {}) {
+      if (closing) fail('DESKTOP_PROXY_CLOSED')
+      if (!ticket || !identifier(ticket.sessionId) || !token(ticket.token) || !Number.isSafeInteger(ticket.expiresAt)
+        || ticket.expiresAt <= now() || ticket.expiresAt > now() + limits.maxTicketMs
+        || typeof connect !== 'function' || typeof validate !== 'function' || !owner(ownerPeer) || signal !== undefined && (!isSignal(signal) || signal.aborted)) fail('DESKTOP_PROXY_TICKET_INVALID')
+      const origin = originOf(clientOrigin), sourceDigest = digest(ticket.token), previous = rows.get(ticket.sessionId)
+      if (previous) {
+        if (previous.ended || previous.expiresAt <= now() || previous.ownerPeer !== ownerPeer || previous.clientOrigin !== origin
+          || !timingSafeEqual(previous.sourceDigest, sourceDigest)) fail('DESKTOP_PROXY_TICKET_INVALID')
+        const candidate = { ...previous, expiresAt: ticket.expiresAt, connect, validate, signal }
+        checkRow(candidate)
+        previous.expiresAt = ticket.expiresAt; previous.connect = connect; previous.validate = validate
+        if (signal !== previous.signal) {
+          for (const off of previous.unwatch) off()
+          previous.signal = signal
+          previous.unwatch = [watch(ownerPeer.signal, () => { if (previous.active) stop(previous.active, 'DESKTOP_PROXY_REVOKED'); endRow(previous) })]
+          if (signal) previous.unwatch.push(watch(signal, () => { if (previous.active) stop(previous.active, 'DESKTOP_PROXY_REVOKED'); endRow(previous) }))
+        }
+        return Object.freeze({ ...desktopTicketMetadata(ticket), websocketPath: DESKTOP_PROXY_PATH, token: previous.proxyToken })
+      }
+      for (const [key, row] of rows) if (row.expiresAt <= now()) { if (row.active) stop(row.active, 'DESKTOP_PROXY_EXPIRED'); endRow(row); rows.delete(key) }
+      if (rows.size >= limits.maxTickets) fail('DESKTOP_PROXY_TICKET_LIMIT')
+      const proxyToken = randomBytes(32).toString('base64url')
+      const row = { sessionId: ticket.sessionId, expiresAt: ticket.expiresAt, ownerPeer, clientOrigin: origin, connect, validate, signal,
+        secret: ticket.token, sourceDigest, proxyToken, proxyDigest: digest(proxyToken), used: false, ended: false, active: null, unwatch: [] }
+      checkRow(row)
+      const revoke = () => { if (row.active) stop(row.active, 'DESKTOP_PROXY_REVOKED'); endRow(row) }
+      row.unwatch.push(watch(ownerPeer.signal, revoke))
+      if (signal) row.unwatch.push(watch(signal, revoke))
+      rows.set(row.sessionId, row)
+      if (ownerPeer.signal.aborted || signal?.aborted) { revoke(); fail('DESKTOP_PROXY_REVOKED') }
+      return Object.freeze({ ...desktopTicketMetadata(ticket), websocketPath: DESKTOP_PROXY_PATH, token: proxyToken })
+    },
+    revoke(sessionId) {
+      const row = rows.get(sessionId)
+      if (!row) return false
+      if (row.active) stop(row.active, 'DESKTOP_PROXY_REVOKED')
+      endRow(row)
+      return true
+    },
+    close() {
+      if (closed) return closed
+      closing = true; clearInterval(sweep)
+      try { unregister?.() } catch {}
+      for (const state of [...states]) stop(state, 'DESKTOP_PROXY_CLOSED', 1001)
+      for (const row of rows.values()) endRow(row)
+      rows.clear()
+      closed = Promise.allSettled([...releases, new Promise(resolve => sockets.close(() => resolve()))]).then(() => undefined)
+      return closed
+    },
+  })
+}

package/packages/orchestration/src/desktop-sessions.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 
 const INPUT_TOOLS = ['desktop_click', 'desktop_key', 'desktop_type', 'desktop_scroll']
+const NODE_CARRIER=Symbol('host-only-desktop-carrier')
 const fail = code => { throw Object.assign(new Error(code), { code }) }
 const id = value => typeof value === 'string' && /^[-A-Za-z0-9_.]{1,128}$/u.test(value)
 const closed = (value, names) => {
@@ -8,7 +9,7 @@ const closed = (value, names) => {
 }
 
 /** Only owner actions mint session tickets. Pairing secrets and Agent grants never reach the viewer. */
-export function createDesktopSessionHost({ machine, binding, authority, issue, request, event, now = Date.now }) {
+export function createDesktopSessionHost({ machine, binding, authority, issue, request, cleanupRequest, event, desktopProxy, desktopHttp, connectDesktop, now = Date.now }) {
   const sessions = new Map()
   const check = (subject, row) => {
     const botId = authority.describe(subject).botId
@@ -20,6 +21,7 @@ export function createDesktopSessionHost({ machine, binding, authority, issue, r
     const tools = ['desktop_screenshot', ...INPUT_TOOLS.filter(tool => grant.scope.mode === 'workspace-write' && grant.scope.tools.includes(tool)
       && (() => { try { authority.assertTool(subject, `remote/${tool}`); return true } catch { return false } })())]
     if (row.mode === 'control' && INPUT_TOOLS.some(tool => !tools.includes(tool))) fail('MACHINE_BOT_DENIED')
+    if (row.tools?.some(tool => !tools.includes(tool))) fail('MACHINE_BOT_DENIED')
     return { record, grant, tools }
   }
   const remember = (row, value) => {
@@ -29,10 +31,27 @@ export function createDesktopSessionHost({ machine, binding, authority, issue, r
     sessions.set(value.sessionId, { ...row, sessionId: value.sessionId, expiresAt: value.expiresAt })
     const url = new URL(value.path, row.record.config.endpoint)
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
-    return { sessionId: value.sessionId, token: value.token, expiresAt: value.expiresAt, websocketUrl: url.href,
+    const ticket = { sessionId: value.sessionId, token: value.token, expiresAt: value.expiresAt, websocketUrl: url.href,
       mode: row.mode, taskId: row.identity.taskId, attemptId: row.identity.attemptId,
       canControl: INPUT_TOOLS.every(tool => row.tools.includes(tool)),
       displays: Array.isArray(value.displays) ? value.displays : [], displayId: value.displayId ?? row.displayId ?? null }
+    if (!row.record.config.transport) return ticket
+    if(row.internal)return {...ticket,websocketUrl:undefined,openWebSocket:async()=>{
+      check(row.subject,row)
+      const socket=await connectDesktop(row.record,undefined,undefined,{autoPong:true})
+      const validate=()=>{const live=sessions.get(value.sessionId);if(!live||live.expiresAt<=now())fail('DESKTOP_SESSION_EXPIRED');check(live.subject,live)}
+      try{validate()}catch(error){socket.terminate();throw error}
+      const send=socket.send.bind(socket)
+      socket.send=(...args)=>{try{validate()}catch(error){socket.terminate();throw error};return send(...args)}
+      const sweep=setInterval(()=>{try{const live=sessions.get(row.sessionId??value.sessionId);if(!live)fail('DESKTOP_SESSION_EXPIRED');check(live.subject,live);if(live.expiresAt<=now())fail('DESKTOP_SESSION_EXPIRED')}catch{socket.terminate()}},100)
+      sweep.unref();socket.once('close',()=>clearInterval(sweep))
+      return socket
+    }}
+    const carrier=row.clientOrigin==='dsh-app://app'?desktopHttp:desktopProxy
+    return carrier.wrapTicket(ticket, { ownerPeer: row.ownerPeer, botId: row.botId, clientOrigin: row.clientOrigin,
+      validate: () => { check(row.subject,row); if (ticket.expiresAt<=now()) fail('DESKTOP_SESSION_EXPIRED'); return true },
+      connect: async ({signal}) => connectDesktop(row.record,signal,row.clientOrigin),
+    })
   }
   const current = (subject, input) => {
     closed(input, ['sessionId'])
@@ -43,7 +62,9 @@ export function createDesktopSessionHost({ machine, binding, authority, issue, r
     return row
   }
   return Object.freeze({
-    async open(subject, input, { signal, clientOrigin, taskId, attemptId } = {}) {
+    openInternal(subject,input,context={}) { if(!id(context.taskId)||!id(context.attemptId))fail('INVALID_DESKTOP_IDENTITY');return this.open(subject,input,{...context,[NODE_CARRIER]:true}) },
+    async open(subject, input, context = {}) {
+      const {signal,clientOrigin,taskId,attemptId,peer}=context
       closed(input, ['machineId', 'rootId', 'mode', 'displayId', 'fps'])
       if (!id(input.machineId) || !id(input.rootId) || input.mode !== undefined && !['watch', 'control'].includes(input.mode)
         || input.fps !== undefined && (!Number.isInteger(input.fps) || input.fps < 5 || input.fps > 30)
@@ -54,6 +75,9 @@ export function createDesktopSessionHost({ machine, binding, authority, issue, r
       const row = { ...input, mode: input.mode ?? 'watch', botId: authority.describe(subject).botId,
         identity: { taskId: taskId ?? `owner-desktop-${randomUUID()}`, attemptId: attemptId ?? `attempt-${randomUUID()}` } }
       const { record, grant, tools } = check(subject, row)
+      row.internal=context[NODE_CARRIER]===true
+      if (record.config.transport && (typeof connectDesktop!=='function'||!row.internal&&(!(clientOrigin==='dsh-app://app'?desktopHttp:desktopProxy)||!peer))) fail('DESKTOP_PROXY_UNAVAILABLE')
+      row.subject=subject;row.ownerPeer=peer;row.clientOrigin=clientOrigin
       row.record = record; row.machineRevision = record.revision; row.bindingRevision = grant.revision; row.tools = tools
       row.grantToken = await issue(record, row.botId, { roots: [row.rootId], tools }, row.identity, signal)
       check(subject, row)
@@ -64,25 +88,35 @@ export function createDesktopSessionHost({ machine, binding, authority, issue, r
       event(record.id, row.botId, 'desktop-session-opened')
       return remember(row, value)
     },
-    async renew(subject, input, { signal, clientOrigin } = {}) {
+    async renew(subject, input, { signal, clientOrigin, peer, taskId, attemptId } = {}) {
       const row = current(subject, input), { record, tools } = check(subject, row)
+      if(row.internal&&(taskId!==row.identity.taskId||attemptId!==row.identity.attemptId))fail('DESKTOP_SESSION_OWNER_MISMATCH')
+      if (record.config.transport && !row.internal && (peer!==row.ownerPeer || clientOrigin!==row.clientOrigin)) fail('MACHINE_BOT_DENIED')
       const grantToken = await issue(record, row.botId, { roots: [row.rootId], tools }, row.identity, signal)
       const value = await request(record.config, '/desktop/v1/session/renew', grantToken,
         { sessionId: row.sessionId, ...(clientOrigin ? { origin: clientOrigin } : {}) }, signal)
       check(subject, row)
       return remember({ ...row, grantToken, tools }, value)
     },
-    async close(subject, input, { signal } = {}) {
-      const row = current(subject, input)
-      const value = await request(row.record.config, '/desktop/v1/session/close', row.grantToken, { sessionId: row.sessionId }, signal)
+    async close(subject, input, { signal, taskId, attemptId } = {}) {
+      closed(input,['sessionId']);if(!id(input.sessionId))fail('INVALID_DESKTOP_REQUEST')
+      const row=sessions.get(input.sessionId)
+      if(!row||authority.describe(subject).botId!==row.botId)fail('MACHINE_BOT_DENIED')
+      if(row.internal&&(taskId!==row.identity.taskId||attemptId!==row.identity.attemptId))fail('DESKTOP_SESSION_OWNER_MISMATCH')
+      desktopProxy?.revoke(row.sessionId)
+      desktopHttp?.revoke(row.sessionId)
+      const value = cleanupRequest?await cleanupRequest(row.record,{sessionId:row.sessionId,botId:row.botId,...row.identity},signal)
+        :await request(row.record.config, '/desktop/v1/session/close', row.grantToken, { sessionId: row.sessionId }, signal)
       if (value?.stopConfirmed !== true) fail('DESKTOP_STOP_UNCONFIRMED')
       sessions.delete(row.sessionId); event(row.machineId, row.botId, 'desktop-session-closed')
       return { stopConfirmed: true }
     },
     async closeAll() {
       return Promise.allSettled([...sessions.values()].map(async row => {
-        const value = await request(row.record.config, '/desktop/v1/session/close', row.grantToken,
-          { sessionId: row.sessionId }, AbortSignal.timeout(2500))
+        desktopProxy?.revoke(row.sessionId)
+        desktopHttp?.revoke(row.sessionId)
+        const value = cleanupRequest?await cleanupRequest(row.record,{sessionId:row.sessionId,botId:row.botId,...row.identity},AbortSignal.timeout(2500))
+          :await request(row.record.config, '/desktop/v1/session/close', row.grantToken,{ sessionId: row.sessionId }, AbortSignal.timeout(2500))
         if (value?.stopConfirmed !== true) fail('DESKTOP_STOP_UNCONFIRMED')
         sessions.delete(row.sessionId)
         event(row.machineId, row.botId, 'desktop-session-closed')

package/packages/orchestration/src/ds-lifecycle.mjs

@@ -5,6 +5,8 @@ import { PolicyError } from '../../capability-broker/src/authority.mjs'
 const id = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value)
 const table = value => value && typeof value === 'object' && !Array.isArray(value)
 const fail = code => { throw new PolicyError(code) }
+// The same ceiling the vendor roster enforces when it records a thread.
+export const MAX_THREADS_PER_BOT = 64
 
 function normalizeGrant(grant) {
   if (!table(grant) || !Array.isArray(grant.tools) || !Array.isArray(grant.modelRoutes)) fail('INVALID_GRANT')
@@ -19,6 +21,8 @@ function normalizeGrant(grant) {
 /** Compile only active own/group Sessions; archived parts never gain authority. */
 export function compileDsOwnership(saved, grantFor) {
   if (!table(saved) || saved.version !== 1 || !Number.isSafeInteger(saved.revision) || saved.revision < 0 || !table(saved.bots) || !table(saved.rooms)) fail('INVALID_DS_STATE')
+  const mainBotIds = saved.mainBotIds ?? []
+  if (!Array.isArray(mainBotIds)) fail('INVALID_DS_MAIN_BOT')
   const bots = new Map(), sessions = new Map(),botRecords=new Map()
   const add = (sessionId, botId) => {
     if (!id(sessionId) || sessions.has(sessionId)) fail('AMBIGUOUS_SESSION_OWNER')
@@ -26,9 +30,29 @@ export function compileDsOwnership(saved, grantFor) {
   }
   for (const [botId,bot] of Object.entries(saved.bots)) {
     if (!id(botId) || !table(bot) || bot.id !== botId) fail('INVALID_DS_BOT')
-    bots.set(botId,normalizeGrant(grantFor(structuredClone(bot))))
+    bots.set(botId,normalizeGrant(grantFor(structuredClone(bot), { main: mainBotIds.includes(botId) })))
     botRecords.set(botId,structuredClone(bot))
     add(bot.sessionId ?? botId,botId)
+    // A Bot's threads are further own chats of the same Bot, so a thread Session
+    // is authority-bearing exactly like the Bot's own chat is — same grant, same
+    // money, same tools. Only committed state can say so: nothing here reads a
+    // model argument, a request body or a client-supplied id. `add` already
+    // refuses a Session two Bots claim, and `commit` refuses one that moves
+    // between Bots, so a restored thread can only ever be its own Bot's again.
+    // An archived thread keeps its record and its readable history and gains no
+    // authority at all.
+    if (bot.threads !== undefined) {
+      if (!Array.isArray(bot.threads) || bot.threads.length > MAX_THREADS_PER_BOT) fail('INVALID_DS_BOT_THREADS')
+      const seenThreads = new Set(), seenSessions = new Set()
+      for (const thread of bot.threads) {
+        if (!table(thread) || !id(thread.threadId) || !id(thread.sessionId)) fail('INVALID_DS_BOT_THREAD')
+        if (seenThreads.has(thread.threadId) || seenSessions.has(thread.sessionId)) fail('AMBIGUOUS_THREAD_IDENTITY')
+        if (thread.archivedAt !== undefined && thread.archivedAt !== null && !Number.isSafeInteger(thread.archivedAt)) fail('INVALID_DS_BOT_THREAD')
+        seenThreads.add(thread.threadId)
+        seenSessions.add(thread.sessionId)
+        if (thread.archivedAt === undefined || thread.archivedAt === null) add(thread.sessionId,botId)
+      }
+    }
   }
   for (const room of Object.values(saved.rooms)) {
     if (!table(room) || !Array.isArray(room.members) || !table(room.sessions ?? {})) fail('INVALID_DS_ROOM')
@@ -38,8 +62,7 @@ export function compileDsOwnership(saved, grantFor) {
     }
   }
   if (bots.size > 4096 || sessions.size > 16384) fail('DS_STATE_LIMIT')
-  const mainBotIds=saved.mainBotIds??[]
-  if(!Array.isArray(mainBotIds)||mainBotIds.some(botId=>!bots.has(botId)))fail('INVALID_DS_MAIN_BOT')
+  if(mainBotIds.some(botId=>!bots.has(botId)))fail('INVALID_DS_MAIN_BOT')
   return { revision:saved.revision,bots,sessions,botRecords,mainBotIds:[...mainBotIds],sourceStamp:createHash('sha256').update(JSON.stringify(saved)).digest('hex') }
 }
 
@@ -175,9 +198,13 @@ export function attachDsLifecycle({ runtime, directory, grantFor, readSaved = ()
   return Object.freeze({
     observeAgent,
     committedBot(botId) { return healthy&&!closed&&committedBots.has(botId)?structuredClone(committedBots.get(botId)):null },
+    committedGrant(botId) { return healthy&&!closed&&records.has(botId)?structuredClone(records.get(botId).grant):null },
     committedBots() { return healthy&&!closed?[...committedBots.values()].map(bot=>structuredClone(bot)):[] },
     committedMainBotIds() { return healthy&&!closed?[...committedMainBotIds]:[] },
-    async refreshGrants() { adoptDisk(await readSaved()) },
+    async refreshGrants() {
+      try { adoptDisk(await readSaved()) }
+      catch (cause) { suspend(); throw cause }
+    },
     status:()=>({healthy,closed,revision,bots:records.size,activeSessions:ownership.size,boundAgents:bindings.size}),
     close() {
       if (closed) return

package/packages/orchestration/src/grant-refresh-queue.mjs

@@ -0,0 +1,17 @@
+/** Coalesce synchronous grant notifications and drain their reads before Host teardown. */
+export function createGrantRefreshQueue({ lifecycle, onError = () => {} }) {
+  let closed = false, dirty = false, active = null
+  const request = () => {
+    if (closed) return
+    dirty = true
+    if (active) return
+    active = Promise.resolve().then(async () => {
+      while (dirty && !closed) {
+        dirty = false
+        try { await lifecycle()?.refreshGrants() }
+        catch (cause) { try { onError(cause) } catch { /* logging cannot leak a rejection */ } }
+      }
+    }).finally(() => { active = null })
+  }
+  return Object.freeze({ request, async close() { closed = true; dirty = false; await active } })
+}

package/packages/orchestration/src/independent-chat-page.mjs

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+import { openBotSessionStore } from './bot-session-store.mjs'
+
+const fail = code => { throw Object.assign(new Error(code), { code }) }
+
+/** Read-through view of the runtime's own transcript; one get is one snapshot. */
+export function createIndependentConversationReader({ dir, maxBytes = 8 * 1024 * 1024 } = {}) {
+  if (typeof dir !== 'string' || !dir || !Number.isSafeInteger(maxBytes) || maxBytes < 256) fail('INDEPENDENT_CHAT_READER_INVALID')
+  const store = openBotSessionStore({ dir: join(dir, 'sessions') })
+  return (botId, { cursor = null, limit = 40 } = {}) => {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || cursor !== null && (typeof cursor !== 'string' || !cursor || cursor.length > 256)) fail('INDEPENDENT_CHAT_PAGE_INVALID')
+    const snapshot = store.get(botId), messages = snapshot.messages
+    const ids = messages.map(row => row.messageId)
+    if (ids.some(id => typeof id !== 'string' || !id) || new Set(ids).size !== ids.length) fail('INDEPENDENT_CHAT_MESSAGE_ID_INVALID')
+    const end = cursor === null ? messages.length : ids.indexOf(cursor)
+    if (end < 0) fail('INDEPENDENT_CHAT_CURSOR_EXPIRED')
+    const items = []
+    let bytes = 0, start = end
+    while (start > 0 && items.length < limit) {
+      const row = messages[start - 1]
+      const item = { messageId: row.messageId, role: row.role, content: row.content, at: row.at,
+        ...(row.contextId ? { contextId: row.contextId } : {}),
+        ...(row.name ? { name: row.name } : {}),
+        ...(row.modelSource ? { modelSource: row.modelSource } : {}),
+        ...(row.toolCalls ? { toolCalls: row.toolCalls } : row.toolCall ? { toolCalls: [row.toolCall] } : {}),
+        ...(row.toolCallId || row.role === 'tool' && row.toolCall?.id ? { toolCallId: row.toolCallId ?? row.toolCall.id } : {}) }
+      const size = Buffer.byteLength(JSON.stringify(item))
+      if (bytes + size > maxBytes) {
+        if (!items.length) fail('INDEPENDENT_CHAT_MESSAGE_TOO_LARGE')
+        break
+      }
+      items.unshift(item); bytes += size; start--
+    }
+    return { schemaVersion: 1, botId, items, nextCursor: start > 0 ? ids[start] : null,
+      snapshotId: createHash('sha256').update(JSON.stringify([ids, snapshot.turns, snapshot.updatedAt])).digest('hex'),
+      truncated: snapshot.truncated, turns: snapshot.turns }
+  }
+}