@mingozhou/dsh-replay 0.3.3

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@mingozhou/dsh-replay",
+  "version": "0.3.3",
+  "description": "Session replay, fork-tree, audit & compare visualization for DeepSeek Harness — time machine for your agent sessions",
+  "main": "lib/index.js",
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "demo": "node demo/serve.mjs",
+    "screenshots": "node scripts/screenshot.mjs",
+    "prepare": "node scripts/build.mjs"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "dsh",
+    "agent",
+    "session-replay",
+    "observability",
+    "audit",
+    "timeline",
+    "visualization"
+  ],
+  "author": "MingoZhou",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "esbuild": "^0.28.2",
+    "playwright": "^1.62.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "types": "lib/types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/src/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/src/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./core": {
+      "types": "./lib/types/src/core/index.d.ts",
+      "default": "./lib/core.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "scripts/build.mjs",
+    "src",
+    "types.d.ts",
+    "tsconfig.json"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-host-webserver": "*",
+    "@deepseek-ai/dsh-session-query": "*",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MingoZhou/dsh-replay"
+  },
+  "homepage": "https://mingozhou.github.io/dsh-replay/",
+  "bugs": "https://github.com/MingoZhou/dsh-replay/issues",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,131 @@
+/**
+ * Build the three artifacts:
+ *   lib/index.js   — host half (ESM, externals: @deepseek-ai/*, node:*)
+ *   lib/client.js  — browser half, classic script registering a lazy CJS
+ *                    factory with window.__ModuleLoader__ (the dsh web
+ *                    loader contract); externals resolve via the injected
+ *                    require from the loader's module table.
+ *   demo/dist/demo.js — fully self-contained demo bundle (react inlined).
+ */
+import { build } from 'esbuild'
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
+
+const cssAsText = { loader: { '.css': 'text' } }
+
+await mkdir('lib', { recursive: true })
+await mkdir('demo/dist', { recursive: true })
+
+// ---- optional mascot artwork (assets/jingxiaoshen.{png,jpg,jpeg,webp}) ----
+// Drop your artwork there and it replaces the built-in SVG mascot everywhere
+// in the UI (and in exported HTML). Cap 1.5 MB; square images look best.
+{
+  const { readFile, stat } = await import('node:fs/promises')
+  const candidates = [
+    ['assets/jingxiaoshen.png', 'image/png'],
+    ['assets/jingxiaoshen.jpg', 'image/jpeg'],
+    ['assets/jingxiaoshen.jpeg', 'image/jpeg'],
+    ['assets/jingxiaoshen.webp', 'image/webp'],
+  ]
+  let source = 'export const mascotImage: string | undefined = undefined\n'
+  let found = false
+  for (const [file, mime] of candidates) {
+    try {
+      const info = await stat(file)
+      found = true
+      if (info.size > 1_500_000) {
+        console.warn(`mascot: ${file} is ${Math.round(info.size / 1024)} KB — compress it to ≤1.5 MB to embed; using built-in SVG for now`)
+      } else {
+        const b64 = (await readFile(file)).toString('base64')
+        source = `export const mascotImage: string | undefined = 'data:${mime};base64,${b64}'\n`
+        console.log(`mascot: embedded ${file} (${Math.round(info.size / 1024)} KB)`)
+      }
+      break
+    } catch {
+      /* try next candidate */
+    }
+  }
+  if (!found) console.log('mascot: no assets/jingxiaoshen.{png,jpg,webp} found — using built-in SVG fallback')
+  await writeFile('src/client/mascot-image.ts', source)
+}
+
+// ---- host half ----
+await build({
+  entryPoints: ['src/index.ts'],
+  outfile: 'lib/index.js',
+  bundle: true,
+  format: 'esm',
+  platform: 'node',
+  target: 'node22',
+  external: ['@deepseek-ai/*', 'node:*'],
+  ...{},
+})
+
+// ---- core as its own importable entry (for standalone/tooling use) ----
+await build({
+  entryPoints: ['src/core/index.ts'],
+  outfile: 'lib/core.js',
+  bundle: true,
+  format: 'esm',
+  platform: 'neutral',
+})
+
+// ---- browser half ----
+const client = await build({
+  entryPoints: ['src/client/index.ts'],
+  bundle: true,
+  format: 'cjs',
+  platform: 'browser',
+  jsx: 'automatic',
+  ...cssAsText,
+  external: ['react', 'react/jsx-runtime', 'react-dom', 'react-dom/client', '@deepseek-ai/*'],
+  write: false,
+})
+const cjs = client.outputFiles[0].text
+const wrapped = `/* dsh-replay client bundle — registers a lazy CJS factory with the dsh web loader. */
+;(function () {
+  var factory = function (require) {
+    var module = { exports: {} };
+    (function (require, module, exports) {
+${cjs}
+    })(require, module, module.exports);
+    return module.exports;
+  };
+  if (typeof window !== 'undefined' && window.__ModuleLoader__) {
+    window.__ModuleLoader__.load({ id: 'dsh-replay', factory: factory });
+  } else if (typeof module !== 'undefined' && module.exports) {
+    module.exports = factory(typeof require === 'function' ? require : function (id) {
+      throw new Error('unresolvable external: ' + id);
+    });
+  }
+})();
+`
+await writeFile('lib/client.js', wrapped)
+
+// ---- standalone viewer (react inlined; embedded into exported HTML) ----
+await build({
+  entryPoints: ['src/client/viewer-entry.tsx'],
+  outfile: 'lib/viewer.js',
+  bundle: true,
+  format: 'iife',
+  platform: 'browser',
+  jsx: 'automatic',
+  ...cssAsText,
+  define: { 'process.env.NODE_ENV': '"production"' },
+  minify: true,
+})
+await copyFile('lib/viewer.js', 'demo/dist/viewer.js')
+
+// ---- demo ----
+await build({
+  entryPoints: ['demo/main.tsx'],
+  outfile: 'demo/dist/demo.js',
+  bundle: true,
+  format: 'iife',
+  platform: 'browser',
+  jsx: 'automatic',
+  ...cssAsText,
+  define: { 'process.env.NODE_ENV': '"production"' },
+  minify: true,
+})
+
+console.log('build ok: lib/index.js, lib/core.js, lib/client.js, lib/viewer.js, demo/dist/demo.js')

package/src/client/api.ts

@@ -0,0 +1,119 @@
+/** Data access for the UI — one HTTP implementation, one in-memory demo implementation. */
+import { fromInspection, parseSessionJsonl } from '../core/decode.js'
+import type { ParsedSession, SessionHeader, StorageRecord } from '../core/types.js'
+
+export interface SessionEntry {
+  header: SessionHeader
+  title?: string
+}
+
+export interface ReplayApi {
+  listSessions: () => Promise<SessionEntry[]>
+  getSession: (id: string) => Promise<ParsedSession>
+  /** Source of the standalone viewer bundle, for HTML export (optional). */
+  getViewerSource?: () => Promise<string>
+}
+
+export class HttpReplayApi implements ReplayApi {
+  constructor(private readonly base = '/replay/api') {}
+
+  private async fetchJson(path: string): Promise<unknown> {
+    const response = await fetch(`${this.base}${path}`)
+    if (!response.ok) throw new Error(`replay api ${path}: HTTP ${response.status}`)
+    return response.json()
+  }
+
+  async listSessions(): Promise<SessionEntry[]> {
+    const body = (await this.fetchJson('/sessions')) as { sessions: SessionEntry[] }
+    return body.sessions
+  }
+
+  async getSession(id: string): Promise<ParsedSession> {
+    const body = (await this.fetchJson(`/session/${encodeURIComponent(id)}`)) as {
+      header: SessionHeader
+      events: StorageRecord[]
+    }
+    return fromInspection(body.header, body.events)
+  }
+
+  async getViewerSource(): Promise<string> {
+    const response = await fetch(`${this.base}/viewer.js`)
+    if (!response.ok) throw new Error(`viewer bundle: HTTP ${response.status}`)
+    return response.text()
+  }
+}
+
+/** Demo/testing implementation over raw JSONL texts keyed by session id. */
+export class StaticReplayApi implements ReplayApi {
+  private readonly sessions = new Map<string, ParsedSession>()
+  private readonly titles = new Map<string, string>()
+  /** Optional URL of the viewer bundle for HTML export (demo mode). */
+  viewerUrl?: string
+
+  constructor(logs: { jsonl: string; title?: string }[]) {
+    for (const { jsonl, title } of logs) {
+      const parsed = parseSessionJsonl(jsonl)
+      this.sessions.set(parsed.header.id, parsed)
+      if (title !== undefined) this.titles.set(parsed.header.id, title)
+    }
+  }
+
+  /** Build directly from already-decoded sessions (exported HTML, tooling). */
+  static fromParsed(list: { header: ParsedSession['header']; events: ParsedSession['events']; title?: string }[]): StaticReplayApi {
+    const api = new StaticReplayApi([])
+    for (const { header, events, title } of list) {
+      api.sessions.set(header.id, { header, events, malformed: [] })
+      if (title !== undefined) api.titles.set(header.id, title)
+    }
+    return api
+  }
+
+  async getViewerSource(): Promise<string> {
+    if (this.viewerUrl === undefined) throw new Error('viewer bundle unavailable in this mode')
+    const response = await fetch(this.viewerUrl)
+    if (!response.ok) throw new Error(`viewer bundle: HTTP ${response.status}`)
+    return response.text()
+  }
+
+  async listSessions(): Promise<SessionEntry[]> {
+    return [...this.sessions.values()].map(s => ({
+      header: s.header,
+      title: this.titles.get(s.header.id),
+    }))
+  }
+
+  async getSession(id: string): Promise<ParsedSession> {
+    const session = this.sessions.get(id)
+    if (session === undefined) throw new Error(`unknown session ${id}`)
+    return session
+  }
+}
+
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return '—'
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  const s = ms / 1000
+  if (s < 60) return `${s.toFixed(s < 10 ? 1 : 0)}s`
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m ${Math.round(s % 60)}s`
+  return `${Math.floor(m / 60)}h ${m % 60}m`
+}
+
+export function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
+  if (n >= 10_000) return `${Math.round(n / 1000)}k`
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`
+  return String(n)
+}
+
+export function formatClock(time: number, startTime: number): string {
+  const ms = time - startTime
+  const s = Math.floor(ms / 1000)
+  const mm = String(Math.floor(s / 60)).padStart(2, '0')
+  const ss = String(s % 60).padStart(2, '0')
+  return `${mm}:${ss}`
+}
+
+export function shortId(id: string): string {
+  return id.length > 10 ? `${id.slice(0, 8)}…` : id
+}

package/src/client/components/AuditView.tsx

@@ -0,0 +1,57 @@
+import React from 'react'
+import type { AuditReport, Severity } from '../../core/audit.js'
+import type { TimelineModel } from '../../core/timeline.js'
+import { formatClock } from '../api.js'
+import { localizeFinding, useI18n } from '../i18n.js'
+import { MascotState } from '../mascot.js'
+
+const SEV_META: Record<Severity, { color: string; icon: string }> = {
+  critical: { color: 'var(--dshr-critical)', icon: '⛔' },
+  serious: { color: 'var(--dshr-serious)', icon: '⚠' },
+  warning: { color: 'var(--dshr-warning)', icon: '△' },
+  info: { color: 'var(--dshr-good)', icon: 'ℹ' },
+}
+
+export function AuditView({
+  report,
+  model,
+  onJump,
+}: {
+  report: AuditReport
+  model: TimelineModel
+  onJump: (seq: number) => void
+}): React.ReactElement {
+  const { t } = useI18n()
+  return (
+    <div className="dshr-audit">
+      <div className="dshr-audit-summary">
+        {(Object.keys(SEV_META) as Severity[]).map(sev => (
+          <div key={sev} className="dshr-audit-tile">
+            <div className="dshr-count">{report.counts[sev]}</div>
+            <div className="dshr-cap">
+              <span className="dshr-sev-dot" style={{ background: SEV_META[sev].color }} />
+              {SEV_META[sev].icon} {t(`sev.${sev}`)}
+            </div>
+          </div>
+        ))}
+      </div>
+      {report.findings.length === 0 ? (
+        <MascotState mood="happy" text={t('audit.empty')} />
+      ) : (
+        report.findings.map((finding, i) => (
+          <button key={i} className="dshr-finding" onClick={() => onJump(finding.seq)}>
+            <span className="dshr-sev">
+              <span className="dshr-sev-dot" style={{ background: SEV_META[finding.severity].color }} />
+              {SEV_META[finding.severity].icon} {t(`sev.${finding.severity}`)}
+            </span>
+            <span className="dshr-finding-title">{localizeFinding(t, finding)}</span>
+            {finding.detail !== undefined && finding.detail !== '' && (
+              <span className="dshr-finding-detail">{finding.detail}</span>
+            )}
+            <span className="dshr-item-time">{formatClock(finding.time, model.startTime)}</span>
+          </button>
+        ))
+      )}
+    </div>
+  )
+}

package/src/client/components/CompareView.tsx

@@ -0,0 +1,186 @@
+import React, { useEffect, useMemo, useState } from 'react'
+import { compareSessions, type CompareResult } from '../../core/compare.js'
+import type { ParsedSession } from '../../core/types.js'
+import { formatDuration, formatTokens, shortId, type ReplayApi, type SessionEntry } from '../api.js'
+import { useI18n } from '../i18n.js'
+
+function Row({
+  label,
+  a,
+  b,
+  format = String,
+}: {
+  label: string
+  a: number
+  b: number
+  format?: (n: number) => string
+}): React.ReactElement {
+  return (
+    <tr>
+      <td>{label}</td>
+      <td>{format(a)}</td>
+      <td>{format(b)}</td>
+      <td style={{ color: 'var(--dshr-ink-3)' }}>
+        {a === b ? '=' : a > b ? `+${format(a - b)}` : `−${format(b - a)}`}
+      </td>
+    </tr>
+  )
+}
+
+export function CompareView({
+  api,
+  session,
+  entries,
+  title,
+}: {
+  api: ReplayApi
+  session: ParsedSession
+  entries: SessionEntry[]
+  title?: string
+}): React.ReactElement {
+  const { t } = useI18n()
+  const others = useMemo(
+    () => entries.filter(e => e.header.id !== session.header.id),
+    [entries, session],
+  )
+  const defaultOther =
+    others.find(e => e.header.id === session.header.parentSession)?.header.id ??
+    others.find(e => e.header.parentSession === session.header.id)?.header.id ??
+    others[0]?.header.id
+  const [otherId, setOtherId] = useState(defaultOther)
+  const [other, setOther] = useState<ParsedSession>()
+  const [error, setError] = useState<string>()
+
+  useEffect(() => {
+    setOtherId(defaultOther)
+  }, [defaultOther])
+
+  useEffect(() => {
+    if (otherId === undefined) return
+    let cancelled = false
+    api
+      .getSession(otherId)
+      .then(s => {
+        if (!cancelled) {
+          setOther(s)
+          setError(undefined)
+        }
+      })
+      .catch(e => !cancelled && setError(String(e)))
+    return () => {
+      cancelled = true
+    }
+  }, [api, otherId])
+
+  const result: CompareResult | undefined = useMemo(() => {
+    if (other === undefined) return undefined
+    return compareSessions(session, other, {
+      a: title,
+      b: others.find(e => e.header.id === other.header.id)?.title,
+    })
+  }, [session, other, title, others])
+
+  if (others.length === 0) {
+    return <div className="dshr-center">{t('cmp.none')}</div>
+  }
+
+  return (
+    <div className="dshr-compare">
+      <div className="dshr-compare-picker">
+        <span>{t('cmp.with')}</span>
+        <select
+          className="dshr-select"
+          value={otherId}
+          onChange={e => setOtherId(e.target.value)}
+          aria-label={t('cmp.aria')}
+        >
+          {others.map(entry => (
+            <option key={entry.header.id} value={entry.header.id}>
+              {entry.title ?? shortId(entry.header.id)}
+              {entry.header.id === session.header.parentSession ? ` ${t('cmp.parent')}` : ''}
+              {entry.header.parentSession === session.header.id ? ` ${t('cmp.fork')}` : ''}
+            </option>
+          ))}
+        </select>
+      </div>
+      {error !== undefined && <div className="dshr-center">{error}</div>}
+      {result && (
+        <>
+          {result.related && result.divergenceSeq !== undefined && (
+            <div className="dshr-divergence">
+              {t('cmp.divergence', { seq: result.divergenceSeq })}
+            </div>
+          )}
+          <div className="dshr-compare-grid">
+          <table className="dshr-table">
+            <thead>
+              <tr>
+                <th>{t('cmp.metric')}</th>
+                <th>{result.a.title ?? shortId(result.a.id)}</th>
+                <th>{result.b.title ?? shortId(result.b.id)}</th>
+                <th>{t('cmp.delta')}</th>
+              </tr>
+            </thead>
+            <tbody>
+              <Row label={t('cmp.turns')} a={result.a.turns} b={result.b.turns} />
+              <Row label={t('cmp.steps')} a={result.a.steps} b={result.b.steps} />
+              <Row label={t('cmp.events')} a={result.a.events} b={result.b.events} />
+              <Row label={t('cmp.toolCalls')} a={result.a.toolCallCount} b={result.b.toolCallCount} />
+              <Row label={t('cmp.toolErrors')} a={result.a.toolErrors} b={result.b.toolErrors} />
+              <Row
+                label={t('cmp.inputTokens')}
+                a={result.a.billedInputTokens}
+                b={result.b.billedInputTokens}
+                format={formatTokens}
+              />
+              <Row
+                label={t('cmp.outputTokens')}
+                a={result.a.outputTokens}
+                b={result.b.outputTokens}
+                format={formatTokens}
+              />
+              <Row
+                label={t('cmp.cacheTokens')}
+                a={result.a.cacheReadTokens}
+                b={result.b.cacheReadTokens}
+                format={formatTokens}
+              />
+              <Row
+                label={t('cmp.duration')}
+                a={result.a.durationMs}
+                b={result.b.durationMs}
+                format={formatDuration}
+              />
+            </tbody>
+          </table>
+          {result.toolNames.length > 0 && (
+            <div>
+              <div className="dshr-section-label">{t('cmp.toolMix')}</div>
+              <table className="dshr-table">
+                <thead>
+                  <tr>
+                    <th>{t('cmp.tool')}</th>
+                    <th>{result.a.title ?? shortId(result.a.id)}</th>
+                    <th>{result.b.title ?? shortId(result.b.id)}</th>
+                    <th>{t('cmp.delta')}</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {result.toolNames.map(name => (
+                    <Row
+                      key={name}
+                      label={name}
+                      a={result.a.toolMix[name] ?? 0}
+                      b={result.b.toolMix[name] ?? 0}
+                    />
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+          </div>
+        </>
+      )}
+    </div>
+  )
+}