dsh-mesh-node 0.0.0-stage → 0.0.2

package/src/core/ds-web.js

@@ -0,0 +1,394 @@
+import { randomUUID } from 'node:crypto'
+import WebSocket from 'ws'
+
+/**
+ * Client for the DSH web host's local Remote API (route A of the channel design).
+ *
+ * Two facts from the harness source that shape this file:
+ *  - The only way in is the one-time launch URL printed by `dsh web`
+ *    (`http://127.0.0.1:<port>/?token=<43 chars>`): GET it with `redirect: 'manual'`
+ *    and you get `303 + Set-Cookie`. There is no static token on disk.
+ *    (apps/web/tests/smoke-real.e2e.ts:50-66, apps/cli/tests/web-auth.e2e.ts:173-183)
+ *  - Every unary call is `POST /api/<method>` with
+ *    `{type:'client-request', rpcId, method, payload:{args}}` and answers
+ *    `{result:{ok:true,value}}` — HTTP can be 200 while `result.ok` is false, so
+ *    never trust the status code alone. (smoke-real.e2e.ts:91-109)
+ */
+
+export class DshError extends Error {
+  constructor(code, message, extra = {}) {
+    super(`${code}: ${message}`)
+    this.name = 'DshError'
+    this.code = code
+    this.extra = extra
+  }
+}
+
+/** Strip a trailing slash and any path so we always talk to the origin. */
+function originOf(url) {
+  return new URL(url).origin
+}
+
+export class DshWebClient {
+  constructor({ baseUrl, cookie, log = console } = {}) {
+    this.baseUrl = baseUrl ? originOf(baseUrl) : null
+    this.cookie = cookie || null
+    this.log = log
+  }
+
+  get authenticated() {
+    return Boolean(this.cookie)
+  }
+
+  /**
+   * Exchange a launch URL for the session cookie. The launch token is single-use;
+   * the resulting cookie survives `dsh web` restarts (it is signed by the key that
+   * lives in the DSH home), so it is worth persisting.
+   */
+  async login(launchUrl, { timeoutMs = 15000 } = {}) {
+    if (!launchUrl) throw new DshError('E_INVALID_ARG', 'launchUrl is required')
+    const started = Date.now()
+    const response = await fetch(launchUrl, { redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) })
+    const setCookie = response.headers.get('set-cookie')
+    if (response.status !== 303 || !setCookie) {
+      throw new DshError('E_DSH_AUTH', `launch URL rejected (HTTP ${response.status}, set-cookie=${setCookie ? 'yes' : 'no'})`, {
+        status: response.status
+      })
+    }
+    this.cookie = setCookie.split(';', 1)[0]
+    this.baseUrl = originOf(launchUrl)
+    this.log?.debug?.(`[dsh-mesh] channel login ok in ${Date.now() - started}ms`)
+    return { baseUrl: this.baseUrl, cookie: this.cookie }
+  }
+
+  async rpc(endpoint, args = {}, { timeoutMs = 60000, rpcId } = {}) {
+    if (!this.baseUrl) throw new DshError('E_DSH_NO_TARGET', 'no baseUrl: log in first')
+    if (!this.cookie) throw new DshError('E_DSH_NO_COOKIE', 'no session cookie: log in first')
+    const body = {
+      type: 'client-request',
+      rpcId: rpcId || `mesh-${endpoint.replace(/\//g, '-')}-${randomUUID()}`,
+      method: endpoint,
+      payload: { args }
+    }
+    let response
+    try {
+      response = await fetch(`${this.baseUrl}/api/${endpoint}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', cookie: this.cookie },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
+      })
+    } catch (error) {
+      if (error?.name === 'TimeoutError') throw new DshError('E_TIMEOUT', `${endpoint} timed out after ${timeoutMs}ms`)
+      throw new DshError('E_DSH_UNREACHABLE', `${endpoint} failed: ${error?.message || error}`)
+    }
+    const text = await response.text()
+    if (!response.ok) {
+      throw new DshError('E_DSH_HTTP', `${endpoint} HTTP ${response.status}: ${text.slice(0, 400)}`, {
+        status: response.status
+      })
+    }
+    let parsed
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      throw new DshError('E_DSH_BAD_BODY', `${endpoint} returned non-JSON: ${text.slice(0, 200)}`)
+    }
+    const result = parsed?.result
+    if (!result || result.ok !== true) {
+      const error = result?.error || {}
+      throw new DshError(error.code || 'E_DSH_RPC', `${endpoint}: ${error.message || 'unknown RPC failure'}`, {
+        endpoint
+      })
+    }
+    return result.value
+  }
+
+  /** `{ items: [{ sessionId, ... }] }` — see smoke-real.e2e.ts:759-771. */
+  async listSessions({ timeoutMs = 30000 } = {}) {
+    return this.rpc('session/list', { _request: {} }, { timeoutMs })
+  }
+
+  /** `{ sessionId }` — smoke-real.e2e.ts:456. */
+  async createSession({ request = {}, timeoutMs = 30000 } = {}) {
+    const value = await this.rpc('session/create', { request }, { timeoutMs })
+    const sessionId = value?.sessionId || value?.request?.sessionId
+    if (!sessionId) throw new DshError('E_DSH_BAD_BODY', 'session/create returned no sessionId')
+    return sessionId
+  }
+
+  /** `{ accepted: true }` — smoke-real.e2e.ts:457-462. */
+  async prompt({ sessionId, text, mode = 'queue', timeoutMs = 60000 } = {}) {
+    if (!sessionId) throw new DshError('E_INVALID_ARG', 'sessionId is required')
+    if (typeof text !== 'string' || text.trim() === '') throw new DshError('E_INVALID_ARG', 'text is required')
+    const requestId = randomUUID()
+    const value = await this.rpc(
+      'session/prompt',
+      { request: { requestId, sessionId, mode, content: [{ type: 'text', text }] } },
+      { timeoutMs }
+    )
+    return { requestId, accepted: value?.accepted !== false, value }
+  }
+
+  /**
+   * Read the latest history window over one short-lived follow stream.
+   *
+   * `session/page` requires a `throughSeq` cut that only a follow opening frame
+   * provides (`packages/api/session-controller/src/types.ts:471-476`), and the
+   * `throughSeq:-1` sentinel paginates to an empty window
+   * (`packages/api/session-controller/src/history.ts:392-426`). So: open, keep the
+   * snapshot, close.
+   */
+  async page({ sessionId, maxMessages = 40, timeoutMs = 30000 } = {}) {
+    const follow = await this.openFollow({ sessionId, maxMessages, timeoutMs })
+    try {
+      return {
+        records: follow.snapshot.records,
+        hasMore: follow.snapshot.hasMore,
+        cursor: follow.snapshot.cursor
+      }
+    } finally {
+      follow.close()
+    }
+  }
+
+  /**
+   * Open `session/follow` on the host's WebSocket mux
+   * (`/api/remote.mux`, `packages/api/gateway/src/stream-protocol.ts:7`) and resolve
+   * once the opening snapshot arrives. Live durable events after that are delivered
+   * to `follow.onEvent`.
+   */
+  openFollow({ sessionId, maxMessages = 40, timeoutMs = 15000 } = {}) {
+    if (!this.baseUrl) throw new DshError('E_DSH_NO_TARGET', 'no baseUrl: log in first')
+    if (!this.cookie) throw new DshError('E_DSH_NO_COOKIE', 'no session cookie: log in first')
+    if (!sessionId) throw new DshError('E_INVALID_ARG', 'sessionId is required')
+    const streamId = `mesh-follow-${randomUUID()}`
+    const url = `${this.baseUrl.replace(/^http/u, 'ws')}/api/remote.mux`
+    const socket = new WebSocket(url, { headers: { cookie: this.cookie } })
+    const follow = {
+      socket,
+      streamId,
+      snapshot: null,
+      /** @type {((event: any) => void) | null} */
+      onEvent: null,
+      /** @type {((error: Error) => void) | null} */
+      onError: null,
+      closed: false,
+      close() {
+        if (follow.closed) return
+        follow.closed = true
+        try {
+          socket.close()
+        } catch {
+          /* already gone */
+        }
+      }
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false
+      const finish = (error) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        if (error) {
+          follow.close()
+          reject(error)
+        } else {
+          resolve(follow)
+        }
+      }
+      const timer = setTimeout(
+        () => finish(new DshError('E_TIMEOUT', `session/follow did not open within ${timeoutMs}ms`)),
+        timeoutMs
+      )
+      socket.on('open', () => {
+        socket.send(
+          JSON.stringify({
+            type: 'open',
+            streamId,
+            endpoint: 'session/follow',
+            payload: {
+              args: { request: { address: { kind: 'session', sessionId }, maxMessages } }
+            }
+          })
+        )
+      })
+      socket.on('message', (data) => {
+        let frame
+        try {
+          frame = JSON.parse(typeof data === 'string' ? data : data.toString('utf8'))
+        } catch {
+          return
+        }
+        if (!frame || frame.streamId !== streamId) return
+        if (frame.type === 'error') {
+          const error = new DshError(
+            frame.error?.code || 'E_DSH_STREAM',
+            `session/follow failed: ${frame.error?.message || 'unknown error'}`
+          )
+          if (!settled) finish(error)
+          else follow.onError?.(error)
+          return
+        }
+        if (frame.type === 'end') {
+          follow.close()
+          if (!settled) finish(new DshError('E_DSH_STREAM', 'session/follow ended before its opening snapshot'))
+          return
+        }
+        if (frame.type !== 'item') return
+        const value = frame.value
+        if (!value) return
+        if (value.type === 'snapshot') {
+          follow.snapshot = {
+            cursor: value.cursor,
+            records: Array.isArray(value.records) ? value.records : [],
+            hasMore: value.hasMore === true
+          }
+          finish()
+          return
+        }
+        if (value.type === 'event' && value.event) follow.onEvent?.(value.event)
+      })
+      socket.on('error', (error) => {
+        const wrapped = new DshError('E_DSH_UNREACHABLE', `session/follow carrier failed: ${error?.message || error}`)
+        if (!settled) finish(wrapped)
+        else follow.onError?.(wrapped)
+      })
+      socket.on('close', () => {
+        follow.closed = true
+        if (!settled) finish(new DshError('E_DSH_STREAM', 'session/follow carrier closed before its opening snapshot'))
+      })
+    })
+  }
+
+  async cancel({ sessionId, timeoutMs = 30000 } = {}) {
+    if (!sessionId) throw new DshError('E_INVALID_ARG', 'sessionId is required')
+    return this.rpc('session/cancel', { request: { sessionId } }, { timeoutMs })
+  }
+
+  /**
+   * Send a prompt and wait for the turn that carries it to end.
+   *
+   * The follow stream is opened *before* the prompt, so no event can be missed; the
+   * snapshot gives us the baseline turn counter. A `queue` prompt can land after a
+   * turn that was already running, so we only accept a `turn/end` that follows a
+   * `turn/start` we saw live (or, for `steer`, the very next `turn/end`).
+   */
+  async sendAndWait({ sessionId, text, mode = 'queue', waitMs = 180000 } = {}) {
+    const started = Date.now()
+    const follow = await this.openFollow({ sessionId, maxMessages: 40 })
+    const baselineTurn = lastTurnOf(follow.snapshot.records)
+    const fresh = []
+    let sawTurnStart = false
+    const outcome = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => resolve({ timedOut: true }), waitMs)
+      follow.onEvent = (event) => {
+        fresh.push({ type: 'event', event })
+        if (event?.type === 'turn/start') sawTurnStart = true
+        if (event?.type !== 'turn/end') return
+        const turn = event?.data?.turn
+        const accepted =
+          mode === 'steer' || sawTurnStart || (Number.isFinite(turn) && turn > baselineTurn)
+        if (!accepted) return
+        clearTimeout(timer)
+        resolve({ timedOut: false, turnEnd: normalizeTurnEnd(event) })
+      }
+      follow.onError = (error) => {
+        clearTimeout(timer)
+        reject(error)
+      }
+    })
+    try {
+      const { requestId } = await this.prompt({ sessionId, text, mode })
+      const result = await outcome
+      if (result.timedOut) {
+        throw new DshError('E_TIMEOUT', `turn did not finish within ${waitMs}ms`, {
+          sessionId,
+          requestId,
+          mode,
+          reply: assistantText(fresh).slice(-4000)
+        })
+      }
+      return {
+        sessionId,
+        requestId,
+        reply: assistantText(fresh).slice(-4000),
+        turnEnd: result.turnEnd,
+        events: fresh.length,
+        ms: Date.now() - started
+      }
+    } finally {
+      follow.close()
+    }
+  }
+}
+
+/** Event records are `{ type:'event', event:{ seq, type, data } }`. */
+function seqOf(record) {
+  const seq = record?.event?.seq ?? record?.seq
+  return Number.isFinite(seq) ? seq : null
+}
+
+function lastSeqOf(records) {
+  let last = -1
+  for (const record of records || []) {
+    const seq = seqOf(record)
+    if (seq !== null && seq > last) last = seq
+  }
+  return last
+}
+
+/** Highest turn counter present in a history window (0 when there is no turn yet). */
+function lastTurnOf(records) {
+  let last = 0
+  let seen = 0
+  for (const record of records || []) {
+    const event = record?.event
+    if (event?.type !== 'turn/start') continue
+    seen += 1
+    const turn = event?.data?.turn ?? event?.data?.turnId
+    if (Number.isFinite(turn)) last = Math.max(last, turn)
+    else last = Math.max(last, seen)
+  }
+  return last
+}
+
+/** Concatenate every assistant text block in order. */
+export function assistantText(records) {
+  const parts = []
+  for (const record of records || []) {
+    const event = record?.event
+    if (event?.type !== 'assistant/message') continue
+    const content = event?.data?.message?.content
+    if (!Array.isArray(content)) continue
+    for (const block of content) {
+      if (block?.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+    }
+  }
+  return parts.join('\n').trim()
+}
+
+function normalizeTurnEnd(event) {
+  const reason = event?.data?.reason || {}
+  return { kind: reason.kind || 'unknown', message: reason.message, seq: event?.seq }
+}
+
+/** Compact a history record for MCP output (never dump the whole event stream). */
+export function summarizeRecord(record) {
+  const event = record?.event
+  if (!event) return { type: record?.type || 'unknown' }
+  const summary = { seq: event.seq, type: event.type }
+  if (event.type === 'user/message') {
+    const content = event?.data?.message?.content
+    summary.text = Array.isArray(content)
+      ? content.filter((b) => b?.type === 'text').map((b) => b.text).join('\n').slice(0, 500)
+      : undefined
+  } else if (event.type === 'assistant/message') {
+    summary.text = assistantText([record]).slice(0, 4000)
+  } else if (event.type === 'turn/end') {
+    summary.reason = normalizeTurnEnd(event)
+  } else if (event.type === 'turn/start') {
+    summary.turn = event?.data?.turn ?? event?.data?.turnId
+  }
+  return summary
+}

package/src/core/host-agent.js

@@ -0,0 +1,263 @@
+/**
+ * Client for the `dsh-mesh-host` bridge plugin (route B).
+ *
+ * The plugin runs *inside* a DSH instance and listens on loopback only; this
+ * module is the mesh server's side of that link. Authentication is a shared
+ * random token file (`<home>/host-token`, 0600) written by the plugin on first
+ * load and readable by the mesh CLI.
+ *
+ * Every call is short-lived and has its own timeout: the bridge is a local
+ * daemon, so "slow" means "that DSH instance is busy", not "the network is bad".
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export class HostError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message)
+    this.name = 'HostError'
+    this.code = code
+    Object.assign(this, extra)
+  }
+}
+
+/** Configured host bridges (one per local DSH instance). */
+export function hostInstances(config) {
+  const list = Array.isArray(config?.hosts) ? config.hosts : []
+  return list.filter((entry) => entry && typeof entry.id === 'string' && entry.id.length > 0)
+}
+
+/**
+ * Resolve one host instance by id; with no id, the first enabled instance wins.
+ * Unknown ids fail loud so a caller cannot silently hit the wrong DSH.
+ */
+export function resolveHostInstance(config, id) {
+  const list = hostInstances(config)
+  if (list.length === 0) {
+    throw new HostError('E_HOST_NO_INSTANCE', 'no host bridge configured (config.hosts is empty)')
+  }
+  if (id === undefined || id === null || id === '') {
+    return list.find((entry) => entry.enabled !== false) || list[0]
+  }
+  const found = list.find((entry) => entry.id === id)
+  if (!found) {
+    throw new HostError(
+      'E_HOST_UNKNOWN',
+      `unknown host instance "${id}" — configured: ${list.map((entry) => entry.id).join(', ')}`,
+      { instances: list.map((entry) => entry.id) }
+    )
+  }
+  return found
+}
+
+/** Resolve the shared loopback token path for one host instance. */
+export function hostTokenPath(config, home, id) {
+  const entry = resolveHostInstance(config, id)
+  if (entry.tokenFile) return entry.tokenFile
+  // dsh0 keeps the historical name so existing installs keep working.
+  return entry.id === 'dsh0' ? join(home, 'host-token') : join(home, `host-token-${entry.id}`)
+}
+
+/** Read the shared token; throws E_HOST_NO_TOKEN with a fix hint when absent. */
+export function readHostToken(config, home, id) {
+  const path = hostTokenPath(config, home, id)
+  try {
+    const token = readFileSync(path, 'utf8').trim()
+    if (token) return token
+  } catch {
+    /* fall through to the descriptive error */
+  }
+  throw new HostError(
+    'E_HOST_NO_TOKEN',
+    `host bridge token not found at ${path} — start a DSH instance with the dsh-mesh-host plugin installed (it creates the token on first load)`
+  )
+}
+
+function requestJson({ url, token, method = 'GET', path, body, timeoutMs = 120000 }) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(path, url)
+    const payload = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8')
+    const headers = { authorization: `Bearer ${token}`, accept: 'application/json' }
+    if (payload) {
+      headers['content-type'] = 'application/json'
+      headers['content-length'] = String(payload.length)
+    }
+
+    let settled = false
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      fn(value)
+    }
+
+    const req = (target.protocol === 'https:' ? import('node:https') : import('node:http'))
+    const timer = setTimeout(() => {
+      req?.then?.(() => {})
+      try {
+        request?.destroy?.(new Error('timeout'))
+      } catch {
+        /* ignore */
+      }
+      finish(reject, new HostError('E_HOST_TIMEOUT', `host bridge did not answer within ${timeoutMs} ms`))
+    }, timeoutMs)
+
+    let request
+    Promise.resolve(req).then(({ default: mod }) => {
+      request = mod.request(
+        target,
+        { method, headers },
+        res => {
+          const chunks = []
+          res.on('data', chunk => chunks.push(chunk))
+          res.on('end', () => {
+            const text = Buffer.concat(chunks).toString('utf8')
+            let parsed
+            try {
+              parsed = text ? JSON.parse(text) : {}
+            } catch {
+              return finish(
+                reject,
+                new HostError('E_HOST_BAD_RESPONSE', `host bridge returned non-JSON (${res.statusCode})`)
+              )
+            }
+            finish(resolve, { status: res.statusCode, body: parsed })
+          })
+        }
+      )
+      request.on('error', error => {
+        finish(
+          reject,
+          new HostError(
+            'E_HOST_OFFLINE',
+            `host bridge unreachable at ${url} (${error?.code || error?.message || error}) — is a DSH instance running with the dsh-mesh-host plugin?`
+          )
+        )
+      })
+      if (payload) request.write(payload)
+      request.end()
+    })
+  })
+}
+
+/**
+ * Build a host-bridge client bound to one config/home pair and one instance.
+ * @param {{config: object, home: string, log?: object, instance?: string}} options
+ */
+export function createHostClient({ config, home, log = console, instance }) {
+  const entry = resolveHostInstance(config, instance)
+  const base = {
+    id: entry.id,
+    label: entry.label || entry.id,
+    url: String(entry.url || 'http://127.0.0.1:9100'),
+    timeoutMs: Number(entry.timeoutMs) || 120000
+  }
+  const tokenOf = () => readHostToken(config, home, entry.id)
+
+  async function call(path, { method = 'GET', body, timeoutMs } = {}) {
+    const { status, body: payload } = await requestJson({
+      url: base.url,
+      token: tokenOf(),
+      method,
+      path,
+      body,
+      timeoutMs: timeoutMs ?? base.timeoutMs
+    })
+    if (status === 401) throw new HostError('E_HOST_AUTH', 'host bridge rejected the shared token')
+    if (payload && payload.ok === false) {
+      throw new HostError(payload.code || 'E_HOST_ERROR', payload.message || 'host bridge call failed')
+    }
+    if (status >= 400) {
+      throw new HostError('E_HOST_ERROR', `host bridge returned HTTP ${status}`)
+    }
+    return payload
+  }
+
+  return {
+    id: base.id,
+    label: base.label,
+    url: base.url,
+    /** True when the bridge answers /host/ping. */
+    async ping() {
+      try {
+        const { body } = await requestJson({
+          url: base.url,
+          token: tokenOf(),
+          method: 'GET',
+          path: '/host/ping',
+          timeoutMs: 4000
+        })
+        return body?.ok === true
+      } catch (error) {
+        log?.debug?.(`[dsh-mesh] host ping failed: ${error?.code || error?.message}`)
+        return false
+      }
+    },
+    async self() {
+      return call('/host/self')
+    },
+    async tools() {
+      return call('/host/tools')
+    },
+    async agents() {
+      return call('/host/agents')
+    },
+    async sessions({ limit = 50, includeEnded = true, workspace = '' } = {}) {
+      const params = new URLSearchParams({ limit: String(limit), includeEnded: String(includeEnded) })
+      if (workspace) params.set('workspace', workspace)
+      return call(`/host/sessions?${params.toString()}`)
+    },
+    async callTool({ tool, args, sessionId, timeoutMs }) {
+      return call('/host/tools/call', {
+        method: 'POST',
+        body: { tool, arguments: args ?? {}, sessionId, timeoutMs },
+        timeoutMs: timeoutMs ?? base.timeoutMs
+      })
+    },
+    async wake({ sessionId, text, target }) {
+      return call('/host/wake', {
+        method: 'POST',
+        body: { sessionId, text, target },
+        timeoutMs: 30000
+      })
+    },
+    /**
+     * Create a fresh Session in that DSH instance (the web UI's own
+     * sessionController path). Requires dsh-mesh-host >= 0.2.0; an older
+     * plugin answers 404 unknown endpoint.
+     */
+    async createSession({ cwd, sessionId, agentPreset, workspaceId } = {}) {
+      return call('/host/sessions/create', {
+        method: 'POST',
+        body: { cwd, sessionId, agentPreset, workspaceId },
+        timeoutMs: 60000
+      })
+    },
+    /** Deliver one user prompt into a Session without a web cookie. */
+    async prompt({ sessionId, text, mode, requestId, clientTimeZone } = {}) {
+      return call('/host/prompt', {
+        method: 'POST',
+        body: { sessionId, text, mode, requestId, clientTimeZone },
+        timeoutMs: 60000
+      })
+    },
+    /**
+     * Tail one allow-listed log file on the peer machine (mesh home root or
+     * `<mesh home>/logs`, `*.log` only; secrets are redacted by the bridge).
+     * Requires dsh-mesh-host >= 0.4.0; older plugins answer 404 unknown endpoint.
+     */
+    async logs({ name, lines = 100 } = {}) {
+      const params = new URLSearchParams({ name: String(name || ''), lines: String(lines) })
+      return call(`/host/logs?${params.toString()}`, { timeoutMs: 15000 })
+    },
+    /** Archive a Session (DSH's restorable "remove from list"; no hard delete exists). */
+    async archiveSession({ sessionId, stopActivity } = {}) {
+      return call('/host/sessions/archive', {
+        method: 'POST',
+        body: { sessionId, stopActivity },
+        timeoutMs: 60000
+      })
+    }
+  }
+}