dsh-live-trace 0.1.0

package/lib/transport.js

@@ -0,0 +1,231 @@
+/**
+ * The Host-side Unix domain socket server: the transport the observer plugin
+ * publishes on and the standalone viewer subscribes to.
+ *
+ * A Unix socket rather than a TCP port is deliberate. It cannot be reached from
+ * another machine, it cannot collide with the Harness web server's port, it
+ * needs no authentication story, and its permissions are the access control.
+ * Each Harness process owns one socket file under
+ * `<runtimeDir>/sockets/<pid>.sock`, so two `dsh` processes never fight over
+ * one path.
+ *
+ * @module dsh-live-trace/transport
+ */
+
+import { chmodSync, mkdirSync, rmSync } from 'node:fs'
+import { createServer } from 'node:net'
+
+import { socketsDir } from './paths.js'
+import { CLIENT_KIND, createLineDecoder, encodeRecord, MAX_REPLAY_ENTRIES, PROTOCOL_VERSION, SERVER_KIND } from './protocol.js'
+
+/** How often an idle connection receives a heartbeat, in milliseconds. */
+export const HEARTBEAT_MS = 5000
+
+/** Entries replayed to a viewer that does not ask for a specific count. */
+export const DEFAULT_REPLAY_LIMIT = 500
+
+/**
+ * @param {string} runtimeDir
+ * @param {number} pid
+ * @returns {string} the socket path this process should own
+ */
+export function defaultSocketPath(runtimeDir, pid = process.pid) {
+  return `${socketsDir(runtimeDir)}/${pid}.sock`
+}
+
+/**
+ * Start the observer's socket server.
+ *
+ * @param {object} options
+ * @param {string} options.socketPath       absolute path to bind
+ * @param {import('./tracker.js').TraceHub} options.hub
+ * @param {() => object} [options.serverInfo] server identity for the `hello` record
+ * @param {number} [options.heartbeatMs]
+ * @param {(error: Error) => void} [options.onError]
+ * @returns {{ socketPath: string, close: () => Promise<void>, clientCount: () => number, broadcast: (record: object) => void, ready: Promise<void> }}
+ */
+export function createTraceServer(options) {
+  const { socketPath, hub, serverInfo = () => ({}), heartbeatMs = HEARTBEAT_MS, onError } = options
+
+  mkdirSync(socketsDir(options.runtimeDir ?? dirnameOf(socketPath)), { recursive: true, mode: 0o700 })
+  // A leftover file from a crashed process would make bind() fail with EADDRINUSE.
+  rmSync(socketPath, { force: true })
+
+  const clients = new Set()
+  let closed = false
+
+  const server = createServer((socket) => {
+    /** @type {{ socket: import('node:net').Socket, decoder: ReturnType<typeof createLineDecoder>, sessionId: string | null, send: (record: object) => void }} */
+    const client = { socket, decoder: createLineDecoder(), sessionId: null, send: () => {} }
+    clients.add(client)
+    socket.setNoDelay(true)
+    socket.setEncoding('utf8')
+
+    const send = (record) => {
+      if (socket.destroyed) return
+      try {
+        socket.write(encodeRecord({ v: PROTOCOL_VERSION, ...record }))
+      } catch {
+        /* the socket already died; close handling below cleans up */
+      }
+    }
+
+    client.send = send
+    client.sessionId = null
+
+    // The session list is enough to start: the viewer answers with an explicit
+    // SELECT, which is what makes per-viewer session routing unambiguous.
+    send({
+      kind: SERVER_KIND.HELLO,
+      protocol: PROTOCOL_VERSION,
+      server: serverInfo(),
+      sessions: hub.sessionsInfo(),
+      activeSessionId: hub.activeSessionId,
+      replayLimit: DEFAULT_REPLAY_LIMIT
+    })
+
+    socket.on('data', (chunk) => {
+      let records
+      try {
+        records = client.decoder.push(chunk)
+      } catch (error) {
+        onError?.(/** @type {Error} */ (error))
+        socket.destroy()
+        return
+      }
+      for (const record of records) handleClientRecord(client, record, hub, send)
+    })
+    socket.on('error', () => {
+      /* handled by close */
+    })
+    socket.on('close', () => {
+      clients.delete(client)
+    })
+  })
+
+  server.on('error', (error) => onError?.(error))
+
+  const ready = new Promise((resolvePromise, rejectPromise) => {
+    server.once('error', rejectPromise)
+    server.listen(socketPath, () => {
+      try {
+        chmodSync(socketPath, 0o600)
+      } catch {
+        /* the platform may not support chmod on sockets; the directory mode still applies */
+      }
+      resolvePromise(undefined)
+    })
+  })
+
+  const heartbeat = setInterval(() => {
+    const record = { kind: SERVER_KIND.HEARTBEAT, at: Date.now(), clients: clients.size }
+    for (const client of clients) client.send(record)
+  }, heartbeatMs)
+  heartbeat.unref?.()
+
+  /**
+   * Route one hub record: session-scoped records only reach viewers bound to
+   * that session; the session list reaches everyone.
+   * @param {object} record
+   */
+  function broadcast(record) {
+    if (closed) return
+    if (record.kind === SERVER_KIND.SESSIONS) {
+      // `boundSessionId` is per-viewer state, so the shared list record is
+      // personalized on the way out rather than broadcast verbatim.
+      for (const client of clients) client.send({ ...record, boundSessionId: client.sessionId })
+      return
+    }
+    const sessionId = record.sessionId
+    for (const client of clients) {
+      if (client.sessionId !== null && client.sessionId === sessionId) client.send(record)
+    }
+  }
+
+  const unsubscribe = hub.subscribe(broadcast)
+
+  return {
+    socketPath,
+    ready,
+    clientCount: () => clients.size,
+    broadcast,
+    async close() {
+      if (closed) return
+      closed = true
+      clearInterval(heartbeat)
+      unsubscribe()
+      for (const client of clients) client.socket.destroy()
+      clients.clear()
+      await new Promise((resolvePromise) => server.close(() => resolvePromise(undefined)))
+      rmSync(socketPath, { force: true })
+    }
+  }
+}
+
+function dirnameOf(path) {
+  const index = path.lastIndexOf('/')
+  return index === -1 ? '.' : path.slice(0, index)
+}
+
+/**
+ * Apply one client request.
+ * @param {{ sessionId: string | null }} client
+ * @param {any} record
+ * @param {import('./tracker.js').TraceHub} hub
+ * @param {(record: object) => void} send
+ */
+function handleClientRecord(client, record, hub, send) {
+  if (record === null || typeof record !== 'object') return
+  switch (record.kind) {
+    case CLIENT_KIND.SELECT: {
+      const explicit = record.sessionId !== undefined && record.sessionId !== null
+      const requested = explicit ? String(record.sessionId) : hub.activeSessionId
+      if (requested === null || !hub.stateOf(requested)) {
+        if (explicit) {
+          send({
+            kind: SERVER_KIND.ERROR,
+            message: `unknown session ${String(record.sessionId)}`,
+            sessions: hub.sessionsInfo(),
+            boundSessionId: client.sessionId
+          })
+        } else {
+          // No explicit request and nothing to bind to yet: an empty Harness is
+          // not an error, so answer with the (empty) session list and wait.
+          send({
+            kind: SERVER_KIND.SESSIONS,
+            sessions: hub.sessionsInfo(),
+            activeSessionId: hub.activeSessionId,
+            boundSessionId: client.sessionId
+          })
+        }
+        return
+      }
+      client.sessionId = requested
+      const limit = clampLimit(record.limit)
+      send({
+        kind: SERVER_KIND.SESSIONS,
+        sessions: hub.sessionsInfo(),
+        activeSessionId: hub.activeSessionId,
+        boundSessionId: client.sessionId
+      })
+      for (const replay of hub.snapshot(requested, limit)) send(replay)
+      break
+    }
+    case CLIENT_KIND.REPLAY: {
+      if (client.sessionId === null) return
+      for (const replay of hub.snapshot(client.sessionId, clampLimit(record.limit))) send(replay)
+      break
+    }
+    case CLIENT_KIND.PING:
+      send({ kind: SERVER_KIND.HEARTBEAT, at: Date.now(), pong: true })
+      break
+    default:
+      // Forward compatibility: an unknown client request is ignored, never fatal.
+      break
+  }
+}
+
+function clampLimit(limit) {
+  if (typeof limit !== 'number' || !Number.isFinite(limit)) return DEFAULT_REPLAY_LIMIT
+  return Math.max(1, Math.min(MAX_REPLAY_ENTRIES, Math.floor(limit)))
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Live Trace",
+    "description": "Publishes normalized Harness session events on a local socket so the standalone `dsh-live-trace` terminal dashboard can show live Turn/Step progress, tool calls, streaming text, elapsed time, and token usage."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "实时轨迹看板",
+    "description": "把 Harness 会话事件归一化后发布到本地 socket，供独立的 `dsh-live-trace` 终端看板实时展示 Turn/Step 进度、工具调用、流式文本、耗时与 Token 消耗。"
+  }
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "dsh-live-trace",
+  "version": "0.1.0",
+  "description": "Read-only live terminal dashboard for DeepSeek Harness sessions: a Host plugin that normalizes session events onto a local socket, plus a standalone full-screen `dsh-live-trace` viewer.",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "observability",
+    "terminal",
+    "dashboard",
+    "trace"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.11"
+  },
+  "bin": {
+    "dsh-live-trace": "bin/dsh-live-trace.js",
+    "dsh-live-working": "bin/dsh-live-working.js",
+    "dsh-glyph-probe": "bin/dsh-glyph-probe.js"
+  },
+  "main": "./index.js",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": "./index.js",
+    "./normalize": "./lib/normalize.js",
+    "./protocol": "./lib/protocol.js",
+    "./registry": "./lib/registry.js",
+    "./width": "./src/cli/width.js",
+    "./renderer": "./src/cli/renderer.js",
+    "./view-state": "./src/cli/view-state.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "lib",
+    "src",
+    "bin",
+    "locale",
+    "icon.svg",
+    "README.md",
+    "scripts",
+    "assets",
+    "picture"
+  ],
+  "scripts": {
+    "test": "node --test 'test/*.test.js'",
+    "test:watch": "node --test --watch 'test/*.test.js'",
+    "demo": "node scripts/demo.mjs",
+    "install:profile": "node scripts/install-profile.mjs",
+    "mock-provider": "node scripts/mock-provider.mjs",
+    "bench": "node scripts/bench-render.mjs",
+    "demo:working": "node scripts/demo-working.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "catalog": {
+      "category": "observability",
+      "summary": {
+        "en": "Read-only live terminal dashboard for Harness sessions: streams Turn/Step progress, tool calls and results, coalesced streaming text, elapsed time and token usage to a standalone `dsh-live-trace` viewer.",
+        "zh": "会话实时终端看板（只读）：把 Turn/Step 进度、工具调用与结果、合并后的流式思考文本、耗时与 Token 消耗推送到独立的 `dsh-live-trace` 终端窗口。"
+      },
+      "capabilities": [
+        "host-observability",
+        "cli"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "author": "Ausntar",
+  "homepage": "https://github.com/Ausntar/dsh-live-trace#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ausntar/dsh-live-trace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ausntar/dsh-live-trace/issues"
+  }
+}

package/scripts/bench-render.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Frame-cost benchmark.
+ *
+ * A frame only ever shows the tail of the log, so its cost must not grow with
+ * the session. This prints the per-frame cost for growing entry counts; the
+ * numbers should stay flat and far below the repaint interval (120 ms by
+ * default). It exists because an earlier implementation rendered every entry
+ * per frame, which reached seconds on a long session and made scrolling feel
+ * laggy.
+ *
+ *   node scripts/bench-render.mjs
+ */
+
+import { renderFrame } from '../src/cli/renderer.js'
+import { createTheme } from '../src/cli/theme.js'
+import { applyRecord, createViewState } from '../src/cli/view-state.js'
+
+const THEME = createTheme({ color: true })
+const AT = Date.now()
+
+function stateWith(entries) {
+  const state = createViewState()
+  applyRecord(state, {
+    kind: 'hello',
+    server: { pid: 1 },
+    sessions: [{ id: 's', createdAt: AT, title: 'bench' }],
+    activeSessionId: 's'
+  })
+  for (let index = 0; index < entries; index += 1) {
+    applyRecord(state, {
+      kind: 'entry',
+      sessionId: 's',
+      entry: {
+        seq: index,
+        time: AT + index,
+        tag: 'assistant',
+        label: 'ASSISTANT',
+        text: `message ${index}`,
+        rawText:
+          `## Step ${index}\n\nFixed \`thing ${index}\` in **src/file${index}.ts**.\n\n` +
+          `\`\`\`ts\nexport function f${index}(x: number) { return x + ${index} }\n\`\`\`\n\n- item a\n- item b`,
+        reasoning: 'thinking about the change '.repeat(6),
+        turn: 1,
+        step: index
+      }
+    })
+  }
+  return state
+}
+
+const BUDGET_MS = 30
+let worst = 0
+
+for (const count of [50, 200, 1000, 3000, 10_000]) {
+  const state = stateWith(count)
+  renderFrame(state, { cols: 80, rows: 30, theme: THEME, now: AT, frame: 0 })
+  const runs = 5
+  const started = process.hrtime.bigint()
+  for (let index = 0; index < runs; index += 1) {
+    renderFrame(state, { cols: 80, rows: 30, theme: THEME, now: AT, frame: index })
+  }
+  const perFrame = Number(process.hrtime.bigint() - started) / 1e6 / runs
+  worst = Math.max(worst, perFrame)
+  console.log(`entries=${String(count).padStart(6)}  per-frame=${perFrame.toFixed(1).padStart(6)}ms`)
+}
+
+console.log(`\nworst ${worst.toFixed(1)}ms against a ${BUDGET_MS}ms budget — ${worst < BUDGET_MS ? 'ok' : 'TOO SLOW'}`)
+process.exitCode = worst < BUDGET_MS ? 0 : 1

package/scripts/demo-working.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * A self-contained run through every animation.
+ *
+ * `dsh-live-working` draws whatever a live session is doing; this plays each
+ * state in turn so you can see them all without waiting for the model to
+ * happen to read a file or call a subagent. It feeds the same record shapes the
+ * plugin publishes, so it exercises the real state machine and the real scene.
+ *
+ *   node scripts/demo-working.mjs            # cycle every state
+ *   node scripts/demo-working.mjs reading    # hold one state
+ */
+
+import { createTranslator, resolveLanguage } from '../src/cli/i18n.js'
+import { Screen } from '../src/cli/screen.js'
+import { createTheme } from '../src/cli/theme.js'
+import { renderCells, sceneFrame, sceneSizeFor } from '../src/cli/working/scene.js'
+import { createWorkState, previewOf, reduceWork, WORK_STATES, workStateOf } from '../src/cli/working/state.js'
+
+const wanted = process.argv[2]
+const states = WORK_STATES.includes(wanted) ? [wanted] : WORK_STATES
+const holdMs = Number(process.env.HOLD_MS ?? 2600)
+const theme = createTheme({ color: true })
+let translator = createTranslator(resolveLanguage('auto'))
+
+/** Records that put the machine into each state. */
+const SCRIPT = {
+  sleep: [{ kind: 'status', status: 'idle' }],
+  thinking: [{ kind: 'stream', reasoning: 'working through it' }],
+  typing: [{ kind: 'stream', text: 'writing the answer' }],
+  writing: [{ kind: 'entry', entry: { tag: 'tool', phase: 'call', callId: 'w', tool: 'write_file' } }],
+  waiting: [{ kind: 'entry', entry: { tag: 'tool', phase: 'call', callId: 'b', tool: 'bash' } }],
+  reading: [{ kind: 'entry', entry: { tag: 'tool', phase: 'call', callId: 'r', tool: 'read_file' } }],
+  searching: [{ kind: 'entry', entry: { tag: 'tool', phase: 'call', callId: 's', tool: 'web_search' } }],
+  calling: [
+    {
+      kind: 'entry',
+      entry: {
+        tag: 'tool',
+        phase: 'call',
+        callId: 't',
+        tool: 'task',
+        arguments: JSON.stringify({ description: '把 auth 模块里的校验逻辑抽出来，补上单元测试' })
+      }
+    }
+  ]
+}
+
+/** Build the machine state for one scripted state. */
+function machineFor(kind) {
+  const state = createWorkState()
+  const now = Date.now()
+  for (const record of SCRIPT[kind] ?? []) reduceWork(state, record, now)
+  return { state, at: now }
+}
+
+const screen = new Screen({ stdout: process.stdout, stdin: process.stdin, altScreen: true, mouse: false })
+let index = 0
+let frame = 0
+let machine = machineFor(states[0])
+
+const draw = () => {
+  const { cols, rows } = screen.size()
+  const now = machine.state
+  const derived = workStateOf(now, machine.at)
+  const kind = derived.kind
+  const bubble =
+    kind === 'calling'
+      ? {
+          header: translator.t('work.bubbleCalling', { n: 1 }),
+          body: 'task(description="把 auth 模块里的校验逻辑抽出来", prompt="补上单元测试，并更新文档与类型定义，确保边界情况也被覆盖")'
+        }
+      : null
+  const scene = sceneFrame({ kind, subagent: derived.subagent }, frame, {
+    palette: theme.scene,
+    bubbleHeader: bubble?.header ?? null,
+    bubbleBody: bubble?.body ?? '',
+    speechFrame: frame,
+    previewText: previewOf(now),
+    size: sceneSizeFor(cols, rows)
+  })
+  const lines = []
+  const top = Math.max(0, Math.floor((rows - scene.height - 2) / 2))
+  for (let line = 0; line < top; line += 1) lines.push('')
+  const pad = ' '.repeat(Math.max(0, Math.floor((cols - scene.width) / 2)))
+  for (const row of scene.cells) lines.push(pad + renderCells(row))
+  while (lines.length < rows - 1) lines.push('')
+  const label = `  ${translator.t(`work.state.${kind}`)}   (${index + 1}/${states.length})  q to quit`
+  lines.push(label)
+  screen.paint(lines.slice(0, rows))
+}
+
+// Without a TTY there is nothing to watch: print one frame and exit, so the
+// script is still useful from a pipe or a test harness.
+if (process.stdout.isTTY !== true && process.env.FORCE !== '1') {
+  const scene = sceneFrame({ kind: workStateOf(machine.state, machine.at).kind }, 0, { palette: theme.scene })
+  for (const row of scene.cells) process.stdout.write(`${renderCells(row)}\n`)
+  process.exit(0)
+}
+
+screen.enter()
+screen.onResize(draw)
+draw()
+
+const frames = setInterval(() => {
+  frame += 1
+  draw()
+}, 120)
+frames.unref?.()
+
+const advance = setInterval(() => {
+  index = (index + 1) % states.length
+  machine = machineFor(states[index])
+  frame = 0
+}, holdMs)
+advance.unref?.()
+
+const stop = () => {
+  clearInterval(frames)
+  clearInterval(advance)
+  screen.leave()
+  process.exit(0)
+}
+screen.onKey((key) => {
+  if (key === 'q' || key === 'quit' || key === '\u0003') stop()
+  if (key === 'l') translator = createTranslator(translator.language === 'zh' ? 'en' : 'zh')
+})
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+