@mingozhou/dsh-replay 0.3.3

package/lib/index.js

@@ -0,0 +1,111 @@
+// src/index.ts
+import { readFile } from "node:fs/promises";
+var name = "dsh-replay";
+var inject = ["webServer", "sessionQuery"];
+function json(res, status, body) {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store"
+  });
+  res.end(JSON.stringify(body));
+}
+function get(obj, key) {
+  return typeof obj === "object" && obj !== null ? obj[key] : void 0;
+}
+function headerOf(record) {
+  for (const candidate of [get(record, "header"), get(record, "meta"), record]) {
+    if (typeof get(candidate, "id") === "string" && typeof get(candidate, "createdAt") === "number") {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function titleOf(record, depth = 3) {
+  if (typeof record !== "object" || record === null || depth < 0) return void 0;
+  const direct = record["title"];
+  if (typeof direct === "string" && direct.length > 0) return direct;
+  for (const value of Object.values(record)) {
+    if (typeof value === "object" && value !== null) {
+      const found = titleOf(value, depth - 1);
+      if (found !== void 0) return found;
+    }
+  }
+  return void 0;
+}
+function apply(ctx, config = {}) {
+  const prefix = config.routePrefix ?? "/replay/api";
+  const webServer = ctx.webServer;
+  const sessionQuery = ctx.sessionQuery;
+  const handler = async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const rest = url.pathname.slice(prefix.length).replace(/^\//u, "");
+    try {
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        json(res, 405, { error: "method not allowed" });
+        return;
+      }
+      if (rest === "sessions") {
+        const records = await sessionQuery.listSessions();
+        const headers = records.map(headerOf).filter((h) => h !== void 0);
+        const titles = /* @__PURE__ */ new Map();
+        if (sessionQuery.readTitleSnapshots !== void 0) {
+          try {
+            const snapshots = await sessionQuery.readTitleSnapshots(headers.map((h) => String(h["id"])));
+            snapshots.forEach((snapshot, i) => {
+              const title = titleOf(snapshot);
+              const id = headers[i]?.["id"];
+              if (title !== void 0 && typeof id === "string") titles.set(id, title);
+            });
+          } catch {
+          }
+        }
+        const readTitle = sessionQuery.readTitle;
+        if (readTitle !== void 0) {
+          await Promise.all(
+            headers.filter((h) => !titles.has(String(h["id"]))).map(async (h) => {
+              try {
+                const title = titleOf(await readTitle.call(sessionQuery, String(h["id"])));
+                if (title !== void 0) titles.set(String(h["id"]), title);
+              } catch {
+              }
+            })
+          );
+        }
+        json(res, 200, {
+          sessions: headers.map((h) => ({ header: h, title: titles.get(String(h["id"])) }))
+        });
+        return;
+      }
+      if (rest === "viewer.js") {
+        const source = await readFile(new URL("./viewer.js", import.meta.url), "utf8");
+        res.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
+        res.end(source);
+        return;
+      }
+      if (rest.startsWith("session/")) {
+        const id = decodeURIComponent(rest.slice("session/".length));
+        const snapshot = await sessionQuery.readSession(id);
+        const header = headerOf(snapshot) ?? headerOf(get(snapshot, "session"));
+        const events = get(snapshot, "events") ?? get(get(snapshot, "session"), "events") ?? [];
+        if (header === void 0) {
+          json(res, 404, { error: "session not found" });
+          return;
+        }
+        json(res, 200, { header, events });
+        return;
+      }
+      json(res, 404, { error: "unknown replay endpoint" });
+    } catch (error) {
+      json(res, 500, { error: String(error) });
+    }
+  };
+  ctx.effect(
+    () => webServer.register({ kind: "prefix", path: prefix, handler }),
+    "dsh-replay: http api"
+  );
+}
+export {
+  apply,
+  inject,
+  name
+};

package/lib/types/demo/main.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/demo/samples.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Realistic sample session logs in the harness wire format (format version 0),
+ * used by the demo page and the test suite. Three sessions:
+ *  A — root session with tool calls, approvals, a failing test run, packed
+ *      chunk rows, and a couple of audit-worthy commands;
+ *  B — a fork of A at the end of turn 1 (parentSession + seedLength +
+ *      session/end-seed marker), continuing differently;
+ *  C — a subagent session doing web research.
+ */
+export declare const SESSION_A_ID = "a7f3c2d1-4b5e-4a6f-8c9d-0e1f2a3b4c5d";
+export declare const SESSION_B_ID = "b8e4d3c2-5c6f-4b7a-9d0e-1f2a3b4c5d6e";
+export declare const SESSION_C_ID = "c9f5e4d3-6d7a-4c8b-a0e1-2f3a4b5c6d7e";
+export declare const SESSION_D_ID = "d0a6f5e4-7e8b-4d9c-b1f2-3a4b5c6d7e8f";
+export declare function sessionA(): string;
+export declare function sessionB(): string;
+export declare function sessionC(): string;
+export declare function sessionD(): string;
+export declare const SAMPLE_LOGS: {
+    jsonl: string;
+    title: string;
+}[];

package/lib/types/src/client/api.d.ts

@@ -0,0 +1,43 @@
+import type { ParsedSession, SessionHeader } 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 declare class HttpReplayApi implements ReplayApi {
+    private readonly base;
+    constructor(base?: string);
+    private fetchJson;
+    listSessions(): Promise<SessionEntry[]>;
+    getSession(id: string): Promise<ParsedSession>;
+    getViewerSource(): Promise<string>;
+}
+/** Demo/testing implementation over raw JSONL texts keyed by session id. */
+export declare class StaticReplayApi implements ReplayApi {
+    private readonly sessions;
+    private readonly titles;
+    /** Optional URL of the viewer bundle for HTML export (demo mode). */
+    viewerUrl?: string;
+    constructor(logs: {
+        jsonl: string;
+        title?: string;
+    }[]);
+    /** Build directly from already-decoded sessions (exported HTML, tooling). */
+    static fromParsed(list: {
+        header: ParsedSession['header'];
+        events: ParsedSession['events'];
+        title?: string;
+    }[]): StaticReplayApi;
+    getViewerSource(): Promise<string>;
+    listSessions(): Promise<SessionEntry[]>;
+    getSession(id: string): Promise<ParsedSession>;
+}
+export declare function formatDuration(ms: number): string;
+export declare function formatTokens(n: number): string;
+export declare function formatClock(time: number, startTime: number): string;
+export declare function shortId(id: string): string;

package/lib/types/src/client/components/AuditView.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { AuditReport } from '../../core/audit.js';
+import type { TimelineModel } from '../../core/timeline.js';
+export declare function AuditView({ report, model, onJump, }: {
+    report: AuditReport;
+    model: TimelineModel;
+    onJump: (seq: number) => void;
+}): React.ReactElement;

package/lib/types/src/client/components/CompareView.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { ParsedSession } from '../../core/types.js';
+import { type ReplayApi, type SessionEntry } from '../api.js';
+export declare function CompareView({ api, session, entries, title, }: {
+    api: ReplayApi;
+    session: ParsedSession;
+    entries: SessionEntry[];
+    title?: string;
+}): React.ReactElement;

package/lib/types/src/client/components/ForkTreeView.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { SessionEntry } from '../api.js';
+export declare function ForkTreeView({ entries, currentId, onSelect, }: {
+    entries: SessionEntry[];
+    currentId?: string;
+    onSelect: (id: string) => void;
+}): React.ReactElement;

package/lib/types/src/client/components/ItemDetail.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import type { TimelineItem, TimelineModel } from '../../core/timeline.js';
+export declare function ItemDetail({ item, model, }: {
+    item: TimelineItem;
+    model: TimelineModel;
+}): React.ReactElement;

package/lib/types/src/client/components/OverviewView.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { AuditReport } from '../../core/audit.js';
+import type { TimelineModel } from '../../core/timeline.js';
+export declare function OverviewView({ model, report, onOpenAudit, }: {
+    model: TimelineModel;
+    report: AuditReport;
+    onOpenAudit: () => void;
+}): React.ReactElement;

package/lib/types/src/client/components/ReplayApp.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { type ReplayApi } from '../api.js';
+import { type Lang } from '../i18n.js';
+export declare function ReplayApp({ api, sessionId, initialLang, onSwitchSession, }: {
+    api: ReplayApi;
+    /** Omit to start on the session picker (modal / standalone modes). */
+    sessionId?: string;
+    /** Override the detected language ('en' | 'zh'). */
+    initialLang?: Lang;
+    /** Optional host-provided navigation; falls back to internal state. */
+    onSwitchSession?: (id: string) => void;
+}): React.ReactElement;

package/lib/types/src/client/components/ReplayModal.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { ReplayApi } from '../api.js';
+/** Full-screen modal hosting the replay app, opened from the sidebar button. */
+export declare function ReplayModal({ api, onClose, closeLabel, }: {
+    api: ReplayApi;
+    onClose: () => void;
+    closeLabel: string;
+}): React.ReactElement;

package/lib/types/src/client/components/SessionPicker.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { type ReplayApi } from '../api.js';
+export declare function SessionPicker({ api, onPick, }: {
+    api: ReplayApi;
+    onPick: (id: string) => void;
+}): React.ReactElement;

package/lib/types/src/client/components/TimelineView.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import type { TimelineModel } from '../../core/timeline.js';
+export declare function TimelineView({ model, jumpToSeq, }: {
+    model: TimelineModel;
+    jumpToSeq?: number;
+}): React.ReactElement;

package/lib/types/src/client/export.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Export a session as a single self-contained HTML file: the viewer bundle
+ * (react inlined) + the session data, playable offline and shareable in an
+ * issue, a blog post, or a chat.
+ */
+import type { ParsedSession } from '../core/types.js';
+export interface ExportSession {
+    header: ParsedSession['header'];
+    events: ParsedSession['events'];
+    title?: string;
+}
+export declare function buildReplayHtml(viewerSource: string, sessions: ExportSession[]): string;
+export declare function downloadReplayHtml(html: string, filename: string): void;

package/lib/types/src/client/i18n.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lightweight EN/中文 i18n for the replay UI. The dictionary is plain data;
+ * `useI18n()` provides `t(key, params)` plus the current language and setter.
+ * Language resolution: explicit choice (persisted) > browser language > en.
+ */
+import React from 'react';
+export type Lang = 'en' | 'zh';
+export type T = (key: string, params?: Record<string, string | number>) => string;
+export declare function makeT(lang: Lang): T;
+export declare function detectLang(): Lang;
+export declare function persistLang(lang: Lang): void;
+export interface I18n {
+    lang: Lang;
+    t: T;
+    setLang: (lang: Lang) => void;
+}
+export declare const I18nContext: React.Context<I18n>;
+export declare function useI18n(): I18n;
+import type { AuditFinding } from '../core/audit.js';
+import type { TimelineItem } from '../core/timeline.js';
+/** Localized finding message; falls back to the stable English title. */
+export declare function localizeFinding(t: T, finding: AuditFinding): string;
+/** Localized rail label for meta items; other kinds keep their content labels. */
+export declare function localizeItemLabel(t: T, item: TimelineItem): string;

package/lib/types/src/client/index.d.ts

@@ -0,0 +1,12 @@
+export declare const name = "dsh-replay";
+export declare const inject: string[];
+interface SlotRegistryLike {
+    inject: (key: string, callback: () => unknown) => void;
+    register: (options: Record<string, unknown>, component: unknown) => () => void;
+}
+interface ClientContextLike {
+    slots: SlotRegistryLike;
+    effect: (callback: () => () => void, label?: string) => void;
+}
+export declare function apply(ctx: ClientContextLike): void;
+export {};

package/lib/types/src/client/mascot-image.d.ts

@@ -0,0 +1 @@
+export declare const mascotImage: string | undefined;

package/lib/types/src/client/mascot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 鲸小深 (Jing Xiaoshen) — dsh-replay's mascot, an original whale-catgirl
+ * character. When `assets/jingxiaoshen.png` exists at build time it is
+ * embedded and used everywhere; otherwise a built-in SVG chibi stands in.
+ * Hide globally with:  .dshr-mascot { display: none }
+ */
+import React from 'react';
+export type MascotMood = 'idle' | 'happy' | 'alert';
+export declare function Mascot({ mood, size, }: {
+    mood?: MascotMood;
+    size?: number;
+}): React.ReactElement;
+export declare function MascotState({ mood, text, size, }: {
+    mood: MascotMood;
+    text: string;
+    size?: number;
+}): React.ReactElement;

package/lib/types/src/client/viewer-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/src/core/audit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Security-audit pass over a decoded session: classify events into findings
+ * with a severity, grouped for the audit view. Rules are data, not code —
+ * extend `DEFAULT_RULES` or pass your own list.
+ *
+ * Severity vocabulary mirrors a standard status palette:
+ * 'critical' | 'serious' | 'warning' | 'info'.
+ */
+import type { ParsedSession, SessionEvent } from './types.js';
+export type Severity = 'critical' | 'serious' | 'warning' | 'info';
+export interface AuditFinding {
+    ruleId: string;
+    severity: Severity;
+    seq: number;
+    time: number;
+    /** English title (stable fallback). */
+    title: string;
+    detail?: string;
+    /** Structured message id + params, so UIs can localize findings. */
+    messageKey?: string;
+    params?: Record<string, string>;
+}
+export interface AuditRule {
+    id: string;
+    severity: Severity | ((event: SessionEvent) => Severity);
+    /** Return a finding title when the event matches, undefined otherwise. */
+    match: (event: SessionEvent) => {
+        title: string;
+        detail?: string;
+        messageKey?: string;
+        params?: Record<string, string>;
+    } | undefined;
+}
+export interface AuditReport {
+    findings: AuditFinding[];
+    counts: Record<Severity, number>;
+}
+export declare const DEFAULT_RULES: AuditRule[];
+export declare function auditSession(session: ParsedSession, rules?: AuditRule[]): AuditReport;

package/lib/types/src/core/compare.d.ts

@@ -0,0 +1,31 @@
+import type { ParsedSession } from './types.js';
+export interface CompareStats {
+    id: string;
+    title?: string;
+    turns: number;
+    steps: number;
+    events: number;
+    toolCallCount: number;
+    toolErrors: number;
+    inputTokens: number;
+    billedInputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    durationMs: number;
+    models: string[];
+    toolMix: Record<string, number>;
+}
+export interface CompareResult {
+    a: CompareStats;
+    b: CompareStats;
+    /** All tool names across both, for a stable table order. */
+    toolNames: string[];
+    /** First seq at which the two logs differ (comparing type+data), if computable. */
+    divergenceSeq?: number;
+    /** True when one session is an ancestor/fork relative of the other. */
+    related: boolean;
+}
+export declare function compareSessions(a: ParsedSession, b: ParsedSession, titles?: {
+    a?: string;
+    b?: string;
+}): CompareResult;

package/lib/types/src/core/cost.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cost estimation from token totals. Prices are USD per 1M tokens and are
+ * ESTIMATES — provider list prices change; override the table if you need
+ * exact numbers. Cache-write falls back to the input rate when a provider
+ * doesn't price it separately.
+ */
+import type { TokenTotals } from './timeline.js';
+export interface PricingRate {
+    /** USD per 1M uncached input tokens. */
+    input: number;
+    /** USD per 1M cache-read tokens. */
+    cacheRead: number;
+    /** USD per 1M cache-write tokens (defaults to `input`). */
+    cacheWrite?: number;
+    /** USD per 1M output tokens. */
+    output: number;
+}
+export interface PricingEntry {
+    match: RegExp;
+    rate: PricingRate;
+    label: string;
+}
+/** Editable defaults — first match wins, most specific first. */
+export declare const DEFAULT_PRICING: PricingEntry[];
+export interface CostEstimate {
+    usd: number;
+    label: string;
+}
+export declare function estimateCost(totals: TokenTotals, models: string[], pricing?: PricingEntry[]): CostEstimate | undefined;
+export declare function formatUsd(usd: number): string;

package/lib/types/src/core/decode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decode a DeepSeek Harness session log (JSONL text or pre-parsed records)
+ * into a `ParsedSession`: header + flat, seq-ordered `SessionEvent[]`.
+ *
+ * Handles the two wire realities documented in the harness:
+ *  - the header line (`type: 'session'`) is not an event;
+ *  - runs of streaming chunks may be packed into `*-chunks` rows
+ *    (`seq0`/`time0`/`dt[]`) that expand back into `assistant/chunk` events.
+ *
+ * A torn final line (crash tail without newline) is tolerated and reported
+ * in `malformed`, mirroring the harness's own committed-bytes semantics.
+ */
+import type { ChunkRowBase, ParsedSession, SessionEvent, SessionHeader, StorageRecord } from './types.js';
+export declare function isChunkRow(record: StorageRecord): record is ChunkRowBase;
+/** Expand one packed chunk row into its constituent `assistant/chunk` events. */
+export declare function expandChunkRow(row: ChunkRowBase): SessionEvent[];
+/** Decode one storage record (already JSON.parsed) into 0..n events. */
+export declare function decodeStorageRecord(record: StorageRecord): SessionEvent[];
+/**
+ * Parse raw JSONL text (uncompressed). The first line must be the session
+ * header; every further line is a `StorageRecord`.
+ */
+export declare function parseSessionJsonl(text: string): ParsedSession;
+/** Build a ParsedSession from an already-materialized header + events (e.g. an API response). */
+export declare function fromInspection(header: SessionHeader, records: StorageRecord[]): ParsedSession;

package/lib/types/src/core/forktree.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Build the session lineage forest from headers (`parentSession` +
+ * `seedLength`), the durable fork/resume metadata the harness keeps
+ * out-of-log. Produces a forest plus a deterministic tidy layout
+ * (depth = x, DFS row = y) the SVG view renders directly.
+ */
+import type { SessionHeader } from './types.js';
+export interface ForkNode {
+    id: string;
+    header: SessionHeader;
+    title?: string;
+    children: ForkNode[];
+    /** Inclusive source event count inherited from the parent (undefined for roots). */
+    seedLength?: number;
+    depth: number;
+    /** Row index assigned by DFS layout. */
+    row: number;
+    /** True when parentSession points at a header we never saw. */
+    orphan?: boolean;
+}
+export interface ForkForest {
+    roots: ForkNode[];
+    nodes: Map<string, ForkNode>;
+    rowCount: number;
+    maxDepth: number;
+}
+export interface SessionListEntry {
+    header: SessionHeader;
+    title?: string;
+}
+export declare function buildForkForest(entries: SessionListEntry[]): ForkForest;
+/** Path from root to the given session (inclusive), for breadcrumbs. */
+export declare function lineageOf(forest: ForkForest, id: string): ForkNode[];

package/lib/types/src/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './decode.js';
+export * from './timeline.js';
+export * from './audit.js';
+export * from './forktree.js';
+export * from './compare.js';
+export * from './cost.js';

package/lib/types/src/core/timeline.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Fold a decoded session into the timeline model the UI renders:
+ * turns → steps → items (user / assistant / tool / meta), with durations,
+ * per-step token usage (last sample wins per turn/step, per the harness's
+ * `usageOf` replace-not-accumulate rule), and cumulative token totals.
+ */
+import type { ParsedSession, SessionEvent, TokenUsage } from './types.js';
+export type ItemKind = 'user' | 'assistant' | 'tool' | 'meta';
+export interface ToolCallInfo {
+    callId: string;
+    name: string;
+    /** Raw argument JSON string exactly as the model produced it. */
+    argumentsRaw: string;
+    argumentsPretty?: string;
+    resultText?: string;
+    error?: {
+        name: string;
+        code: string;
+    };
+    callSeq: number;
+    resultSeq?: number;
+    callTime: number;
+    resultTime?: number;
+    durationMs?: number;
+}
+export interface TimelineItem {
+    kind: ItemKind;
+    seq: number;
+    time: number;
+    turn?: number;
+    step?: number;
+    type: string;
+    /** Short one-line label for the timeline rail. */
+    label: string;
+    /** Full text body when the item carries prose (user/assistant messages). */
+    text?: string;
+    reasoningText?: string;
+    toolCall?: ToolCallInfo;
+    usage?: TokenUsage;
+    event: SessionEvent;
+    /** True when this surface node was later shadowed by compaction. */
+    shadowed?: boolean;
+}
+export interface StepModel {
+    turn: number;
+    step: number;
+    startSeq: number;
+    endSeq?: number;
+    startTime: number;
+    endTime?: number;
+    usage?: TokenUsage;
+    items: TimelineItem[];
+}
+export interface TurnModel {
+    turn: number;
+    startSeq: number;
+    endSeq?: number;
+    startTime: number;
+    endTime?: number;
+    endReason?: string;
+    steps: StepModel[];
+    items: TimelineItem[];
+}
+export interface TokenTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    reasoning: number;
+    /** billed input = input + cacheRead + cacheWrite (disjoint counts). */
+    billedInput: number;
+}
+export interface TimelineModel {
+    turns: TurnModel[];
+    /** Flat, seq-ordered list of everything renderable. */
+    items: TimelineItem[];
+    totals: TokenTotals;
+    /** Per assistant-step usage samples in order, for the token strip. */
+    usageSamples: {
+        seq: number;
+        turn: number;
+        step: number;
+        usage: TokenUsage;
+    }[];
+    toolCalls: ToolCallInfo[];
+    durationMs: number;
+    startTime: number;
+    endTime: number;
+    eventCount: number;
+    /** seq of the last `session/end-seed` marker (fork/resume boundary), if any. */
+    seedBoundarySeq?: number;
+    models: string[];
+    /** Latest `session/title` event payload, when the log carries one. */
+    title?: string;
+}
+export declare function buildTimeline(session: ParsedSession): TimelineModel;