@skillpie/dsh-remote 0.0.0-stage → 1.1.0

package/lib/engine.js

@@ -0,0 +1,367 @@
+/**
+ * dsh-remote — host-side visitor command engine.
+ *
+ * One engine per host process. It speaks the control-channel frames over one
+ * OR MORE transports at a time (relay WebSocket and the local direct pipe
+ * are both common), and drives the in-process sessionController exactly
+ * where the web GUI does: list, state, create, prompt (queued), cancel, plus
+ * per-session durable event and state streams shared across observing
+ * visitors.
+ *
+ * Routing rule: a reply or addressed push always rides the transport the
+ * visitor came in on; session-wide fan-out rides every transport with an
+ * observer. The engine never reaches the model or the filesystem directly;
+ * every capability is a sessionController call, so a visitor can do remotely
+ * what the owner could do in the GUI — and nothing else.
+ */
+import { generateId, VISITOR_COMMANDS, INTERNAL_COMMANDS, PROTOCOL_VERSION } from './protocol.js'
+
+const HEARTBEAT_MS = 15_000
+const MAX_TEXT = 32 * 1024
+const LOG_CAP = 200
+const HISTORY_MAX_MESSAGES = 40
+/** sessionController's remote signatures require a signal; cap one-shot reads. */
+const READ_TIMEOUT_MS = 20_000
+
+/** A fresh bounded signal for one-shot sessionController reads. */
+const readSignal = () => AbortSignal.timeout(READ_TIMEOUT_MS)
+
+export class HostEngine {
+  /**
+   * @param services lazy service access: { sessionController(): object | undefined }
+   * @param host static host facts: { name, dsh, code } (plain values)
+   */
+  constructor({ services, host, log = () => {} }) {
+    this.services = services
+    this.host = host
+    this.log = log
+    /** channel records: { channel, heartbeat } */
+    this.channels = new Map()
+    /** visitorId → { connectedAt, sessions:Set, channel } */
+    this.visitors = new Map()
+    /** sessionId → { refs, controller, cleanups[] } */
+    this.streams = new Map()
+    this.allowControl = true
+    this.startedAt = Date.now()
+    this.broadcastTimer = undefined
+    this.closed = false
+  }
+
+  /** Wire the engine to a transport. The transport speaks hello itself. */
+  attach(channel) {
+    const record = { channel, heartbeat: undefined }
+    this.channels.set(channel, record)
+    record.offMessage = channel.onMessage((text) => this.onFrame(text, channel))
+    record.offClose = channel.onClose(() => this.detach(channel))
+    record.heartbeat = setInterval(() => {
+      if (this.channels.has(channel)) channel.send({ t: 'hb' })
+    }, HEARTBEAT_MS)
+    this.log('engine', 'channel attached')
+  }
+
+  /** Remove one transport; its visitors go with it. */
+  detach(channel) {
+    const record = this.channels.get(channel)
+    if (!record) return
+    this.channels.delete(channel)
+    record.offMessage?.()
+    record.offClose?.()
+    if (record.heartbeat) clearInterval(record.heartbeat)
+    for (const [visitorId, visitor] of [...this.visitors]) {
+      if (visitor.channel === channel) {
+        for (const sessionId of visitor.sessions) this.unobserve(visitorId, sessionId)
+        this.visitors.delete(visitorId)
+      }
+    }
+  }
+
+  /** Full teardown for plugin unload. */
+  close() {
+    if (this.closed) return
+    this.closed = true
+    for (const channel of [...this.channels.keys()]) this.detach(channel)
+    if (this.broadcastTimer) clearTimeout(this.broadcastTimer)
+    this.broadcastTimer = undefined
+    for (const stream of this.streams.values()) stream.controller.abort()
+    this.streams.clear()
+  }
+
+  onFrame(text, channel) {
+    if (this.closed) return
+    const frame = (() => {
+      try { return JSON.parse(text) } catch { return null }
+    })()
+    if (!frame || typeof frame !== 'object') return
+    if (frame.t === 'hb') return
+    if (frame.t !== 'cmd') return
+    const { id, from, cmd } = frame
+    if (typeof id !== 'string' || typeof from !== 'string' || typeof cmd !== 'string') return
+    const known = VISITOR_COMMANDS.has(cmd) || INTERNAL_COMMANDS.has(cmd)
+    if (!known) return this.reply(id, false, undefined, `unknown command: ${cmd}`, channel)
+    Promise.resolve()
+      .then(() => this.dispatch(cmd, frame.p, from, channel))
+      .then((data) => this.reply(id, true, data, undefined, channel))
+      .catch((error) => {
+        this.log('cmd-error', `${cmd}: ${error?.message ?? String(error)}`)
+        this.reply(id, false, undefined, error?.message ?? String(error), channel)
+      })
+  }
+
+  reply(id, ok, data, error, channel) {
+    channel.send({ t: 'res', id, ok, ...(ok ? { data } : { error }) })
+  }
+
+  controller() {
+    return this.services.sessionController?.()
+  }
+
+  requireControl() {
+    if (!this.allowControl) throw new Error('远程控制已关闭（只读模式）')
+  }
+
+  async dispatch(cmd, p = {}, from, channel) {
+    const controller = this.controller()
+    if (!controller) throw new Error('sessionController 服务不可用')
+    switch (cmd) {
+      case 'visitor.hello': {
+        const previous = this.visitors.get(from)
+        if (previous) {
+          for (const sessionId of previous.sessions) this.unobserve(from, sessionId)
+        }
+        this.visitors.set(from, { id: from, connectedAt: Date.now(), sessions: new Set(), channel })
+        this.log('visitor', `访客接入 ${shortId(from)}`)
+        return {
+          host: {
+            name: this.host.name,
+            dsh: this.host.dsh,
+            code: this.host.code,
+            allowControl: this.allowControl,
+          },
+          sessions: await this.listSessions(),
+        }
+      }
+      case 'visitor.gone': {
+        const record = this.visitors.get(from)
+        if (record) {
+          for (const sessionId of record.sessions) this.unobserve(from, sessionId)
+          this.visitors.delete(from)
+        }
+        this.log('visitor', `访客断开 ${shortId(from)}`)
+        return { ok: true }
+      }
+      case 'host.info': {
+        return { name: this.host.name, dsh: this.host.dsh, allowControl: this.allowControl }
+      }
+      case 'sessions.list': {
+        return { sessions: await this.listSessions() }
+      }
+      case 'sessions.state': {
+        const state = await controller.state({ sessionId: p.sessionId }, readSignal())
+        return { state: projectState(state) }
+      }
+      case 'sessions.create': {
+        this.requireControl()
+        const created = await controller.create({})
+        this.log('cmd', `访客新建会话 ${shortId(created.sessionId)}`)
+        this.scheduleSessionsBroadcast()
+        return { sessionId: created.sessionId, agentPreset: created.agentPreset }
+      }
+      case 'sessions.send': {
+        this.requireControl()
+        const text = typeof p.text === 'string' ? p.text.trim() : ''
+        if (!text) throw new Error('消息内容为空')
+        if (text.length > MAX_TEXT) throw new Error('消息过长')
+        const sessionId = p.sessionId
+        await controller.prompt({
+          requestId: generateId(),
+          sessionId,
+          mode: 'queue',
+          content: [{ type: 'text', text }],
+          clientTimeZone: 'Asia/Shanghai',
+        }, readSignal())
+        this.log('cmd', `访客向会话 ${shortId(sessionId)} 发送指令 (${text.length} 字)`)
+        return { accepted: true }
+      }
+      case 'sessions.cancel': {
+        this.requireControl()
+        await controller.cancel({ sessionId: p.sessionId })
+        this.log('cmd', `访客中断会话 ${shortId(p.sessionId)}`)
+        return { accepted: true }
+      }
+      case 'sessions.observe': {
+        const sessionId = p.sessionId
+        const visitor = this.visitors.get(from)
+        if (!visitor) throw new Error('访客会话不存在（请重连）')
+        for (const previous of visitor.sessions) {
+          if (previous !== sessionId) this.unobserve(from, previous)
+        }
+        visitor.sessions.add(sessionId)
+        const stream = this.streamFor(sessionId)
+        const [state, history] = await Promise.all([
+          controller.state({ sessionId }, readSignal()),
+          controller.events({
+            address: { kind: 'session', sessionId },
+            maxMessages: HISTORY_MAX_MESSAGES,
+            turnWindow: { minMessages: 10, minTurns: 2 },
+          }, readSignal()),
+        ])
+        this.pushTo(from, {
+          t: 'session-history',
+          sessionId,
+          records: history.records,
+          hasMore: history.hasMore,
+          state: projectState(state),
+        })
+        this.log('cmd', `访客查看会话 ${shortId(sessionId)}`)
+        return { cursor: state.cursor, state: projectState(state) }
+      }
+      case 'sessions.unobserve': {
+        this.unobserve(from, p.sessionId)
+        return { ok: true }
+      }
+      default:
+        throw new Error(`unknown command: ${cmd}`)
+    }
+  }
+
+  async listSessions() {
+    const controller = this.controller()
+    if (!controller) return []
+    const { items } = await controller.list({}, readSignal())
+    return items
+      .filter((item) => !item.blank && !item.origin)
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .slice(0, 50)
+      .map((item) => projectSummary(item))
+  }
+
+  streamFor(sessionId) {
+    let stream = this.streams.get(sessionId)
+    if (stream) {
+      stream.refs += 1
+      return stream
+    }
+    const controller = this.controller()
+    if (!controller) throw new Error('sessionController 服务不可用')
+    const ctl = new AbortController()
+    const cleanups = []
+    stream = { refs: 1, controller: ctl, cleanups }
+    this.streams.set(sessionId, stream)
+    // Durable event feed: 'ready' then one entry per committed event.
+    void this.pump(
+      ctl,
+      controller.observeEvent({ address: { kind: 'session', sessionId } }, ctl.signal),
+      (event) => this.pushSession(sessionId, { t: 'session-event', sessionId, event }),
+    )
+    // Passive state feed: running flag, queue, pending approvals.
+    void this.pump(
+      ctl,
+      controller.observeState({ sessionId }, ctl.signal),
+      (state) => this.pushSession(sessionId, { t: 'session-state', sessionId, state: projectState(state) }),
+    )
+    cleanups.push(() => this.streams.delete(sessionId))
+    return stream
+  }
+
+  async pump(ctl, iterator, onFrame) {
+    try {
+      for await (const frame of iterator) {
+        if (ctl.signal.aborted) return
+        if (frame && frame.type !== 'ready') onFrame(frame)
+      }
+    } catch (error) {
+      if (!ctl.signal.aborted) this.log('stream', `stream error: ${error?.message ?? String(error)}`)
+    }
+  }
+
+  unobserve(visitorId, sessionId) {
+    const visitor = this.visitors.get(visitorId)
+    visitor?.sessions.delete(sessionId)
+    const stream = this.streams.get(sessionId)
+    if (!stream) return
+    stream.refs -= 1
+    if (stream.refs <= 0) {
+      stream.controller.abort()
+      for (const cleanup of stream.cleanups) cleanup()
+    }
+  }
+
+  pushSession(sessionId, frame) {
+    for (const visitor of this.visitors.values()) {
+      if (visitor.sessions.has(sessionId)) visitor.channel.send({ t: 'push', to: visitor.id, f: frame })
+    }
+  }
+
+  pushTo(visitorId, frame) {
+    const visitor = this.visitors.get(visitorId)
+    visitor?.channel.send({ t: 'push', to: visitorId, f: frame })
+  }
+
+  /** Fan a refreshed session list to every visitor, throttled. */
+  scheduleSessionsBroadcast() {
+    if (this.broadcastTimer) return
+    this.broadcastTimer = setTimeout(async () => {
+      this.broadcastTimer = undefined
+      if (this.visitors.size === 0) return
+      try {
+        const sessions = await this.listSessions()
+        for (const visitor of this.visitors.values()) {
+          visitor.channel.send({ t: 'push', to: visitor.id, f: { t: 'sessions-updated', sessions } })
+        }
+      } catch {
+        // listing raced a disposal; the next trigger retries
+      }
+    }, 400)
+  }
+
+  /** Wire session lifecycle events, best-effort; degrades to action-triggered refresh. */
+  observeSessionEvents(on) {
+    const names = ['api-session/added', 'api-session/removed', 'api-session/status', 'api-session/activity']
+    const offs = []
+    for (const name of names) {
+      try {
+        offs.push(on(name, () => this.scheduleSessionsBroadcast()))
+      } catch {
+        // event bus not offered in this assembly
+      }
+    }
+    return () => { for (const off of offs) off() }
+  }
+
+  status() {
+    return {
+      protocol: PROTOCOL_VERSION,
+      startedAt: this.startedAt,
+      visitors: [...this.visitors.entries()].map(([id, visitor]) => ({
+        id,
+        connectedAt: visitor.connectedAt,
+        sessions: [...visitor.sessions],
+      })),
+    }
+  }
+}
+
+function projectSummary(item) {
+  return {
+    id: item.sessionId,
+    title: typeof item.projections?.values?.title === 'string' ? item.projections.values.title : null,
+    updatedAt: item.updatedAt,
+    running: item.running === true,
+    agentAvailable: item.agentAvailable === true,
+    cwd: typeof item.cwd === 'string' ? item.cwd : undefined,
+  }
+}
+
+function projectState(state) {
+  return {
+    cursor: state?.cursor ?? 0,
+    active: state?.active === true,
+    running: state?.running === true,
+    queued: Array.isArray(state?.queue) ? state.queue.length : 0,
+    pendingInput: Array.isArray(state?.pendingInput) ? state.pendingInput : [],
+  }
+}
+
+function shortId(id) {
+  return typeof id === 'string' && id.length > 10 ? `${id.slice(0, 8)}…` : String(id)
+}

package/lib/file-route.js

@@ -0,0 +1,159 @@
+/**
+ * dsh-remote — host-side visitor file download route.
+ *
+ * Visitors of the real GUI have no way to save a generated file locally: the
+ * built-in file menu only hands paths to the Host desktop (open / reveal),
+ * which is invisible to a remote browser. This route reads a file from this
+ * host's disk and streams it back with `Content-Disposition: attachment`,
+ * so the visitor's browser opens its own save dialog.
+ *
+ * The route registers on the HOST's own web server under `/dsh-remote-file`;
+ * visitor requests reach it through the tunnel (relay prefix proxy or direct
+ * pipe) with the bridge-minted owner cookie attached. Everything else is
+ * gated by a shared-secret key derived from the host id (`?k=` or the
+ * `x-dsh-remote-key` header) so loopback strangers cannot read arbitrary
+ * files. The same derivation runs on the relay to stamp the key into the
+ * visitor shim, so no protocol change carries it.
+ */
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+
+/** Largest file one download may serve. */
+const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024
+
+const MIME_BY_EXT = new Map([
+  ['.xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+  ['.xlsm', 'application/vnd.ms-excel.sheet.macroEnabled.12'],
+  ['.xls', 'application/vnd.ms-excel'],
+  ['.csv', 'text/csv; charset=utf-8'],
+  ['.tsv', 'text/tab-separated-values; charset=utf-8'],
+  ['.docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+  ['.doc', 'application/msword'],
+  ['.pptx', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'],
+  ['.ppt', 'application/vnd.ms-powerpoint'],
+  ['.pdf', 'application/pdf'],
+  ['.json', 'application/json; charset=utf-8'],
+  ['.txt', 'text/plain; charset=utf-8'],
+  ['.md', 'text/markdown; charset=utf-8'],
+  ['.html', 'text/html; charset=utf-8'],
+  ['.htm', 'text/html; charset=utf-8'],
+  ['.xml', 'application/xml; charset=utf-8'],
+  ['.yml', 'text/yaml; charset=utf-8'],
+  ['.yaml', 'text/yaml; charset=utf-8'],
+  ['.png', 'image/png'],
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.gif', 'image/gif'],
+  ['.webp', 'image/webp'],
+  ['.svg', 'image/svg+xml'],
+  ['.zip', 'application/zip'],
+  ['.gz', 'application/gzip'],
+  ['.mp4', 'video/mp4'],
+  ['.mp3', 'audio/mpeg'],
+  ['.wav', 'audio/wav'],
+])
+
+export function mimeOf(name) {
+  const at = name.lastIndexOf('.')
+  if (at === -1) return 'application/octet-stream'
+  return MIME_BY_EXT.get(name.slice(at).toLowerCase()) ?? 'application/octet-stream'
+}
+
+/** attachment disposition with an UTF-8 form plus an ASCII fallback. */
+export function dispositionOf(name) {
+  const clean = String(name ?? '').replace(/[\r\n]/g, ' ').trim() || 'download'
+  const fallback = clean.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_')
+  return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(clean)}`
+}
+
+/**
+ * Shared secret gating the host's file route. Derived from the host id only,
+ * so it survives token regeneration and needs no protocol change: the relay
+ * derives the same value from the hello hostId to stamp the visitor shim.
+ */
+export function fileRouteKey(hostId) {
+  return createHash('sha256').update(`dsh-remote-file:v1:${hostId}`).digest('hex').slice(0, 32)
+}
+
+/** Constant-time-ish comparison for short hex strings. */
+function keyMatches(given, expected) {
+  const a = Buffer.from(String(given ?? ''))
+  const b = Buffer.from(String(expected ?? ''))
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < b.length; i++) diff |= a[i] ^ b[i]
+  return diff === 0
+}
+
+/**
+ * Register the download route on the host web server.
+ * @param services { webServer: object with register(route) → disposer }
+ * @param key string from fileRouteKey(identity.hostId)
+ * @param log fn(kind, text)
+ * @returns disposer
+ */
+export function registerFileRoute({ webServer, key, log = () => {} }) {
+  return webServer.register({
+    kind: 'prefix',
+    path: '/dsh-remote-file',
+    handler: (req, res) => {
+      try {
+        void handle(req, res)
+      } catch (error) {
+        log('file-route', `下载路由处理异常（已隔离）: ${error?.message ?? error}`)
+        try { res.writeHead(500).end() } catch { try { res.destroy() } catch { /* gone */ } }
+      }
+    },
+  })
+
+  async function handle(req, res) {
+    const url = new URL(req.url ?? '/', 'http://localhost')
+    const send = (status, text) => {
+      if (res.headersSent) { try { res.destroy() } catch { res.end() } ; return }
+      res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' })
+      res.end(`${text}\n`)
+    }
+    if (!url.pathname.startsWith('/dsh-remote-file')) return send(404, 'not found')
+    if (req.method !== 'GET' && req.method !== 'HEAD') return send(405, 'method not allowed')
+    // Loopback strangers and forged pages must not read files; only requests
+    // carrying the key survive (the visitor shim stamps it, tunnel or direct).
+    const given = url.searchParams.get('k') ?? req.headers['x-dsh-remote-key'] ?? ''
+    if (!keyMatches(given, key)) return send(403, 'bad download key')
+    const filePath = url.searchParams.get('path') ?? ''
+    if (!filePath || !filePath.startsWith('/') || filePath.includes('\0')) return send(400, 'path must be absolute')
+    let info
+    try {
+      info = await stat(filePath)
+    } catch {
+      return send(404, 'file not found')
+    }
+    if (!info.isFile()) return send(404, 'not a regular file')
+    if (info.size > MAX_DOWNLOAD_BYTES) return send(413, 'file too large')
+    const name = filePath.split('/').pop() || 'download'
+    let stream
+    try {
+      stream = createReadStream(filePath)
+    } catch (error) {
+      return send(404, `file unreadable: ${error?.message ?? error}`)
+    }
+    res.writeHead(200, {
+      'Content-Type': mimeOf(name),
+      'Content-Length': String(info.size),
+      'Content-Disposition': dispositionOf(name),
+      'Cache-Control': 'no-store',
+      'X-Content-Type-Options': 'nosniff',
+    })
+    stream.on('error', (error) => {
+      log('file-route', `下载流中断: ${error?.message ?? error}`)
+      try { res.destroy() } catch { res.end() }
+    })
+    req.on('close', () => { try { stream.destroy() } catch { /* gone */ } })
+    if (req.method === 'HEAD') {
+      stream.destroy()
+      res.end()
+      return
+    }
+    stream.pipe(res)
+  }
+}