@deepseek-harness-tui/dsh-tui 0.6.1 → 0.7.0

package/lib/types/dsh-adapter/trajectory/inspect.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Inspector detail — full content, resolved on demand.
+ *
+ * The projection stores no message bodies: a node keeps `seq` (and `endSeq`)
+ * and nothing else about content, so a ten-thousand-row session costs a few
+ * hundred kilobytes of index rather than a second copy of the transcript. The
+ * price is that opening a row has to go back to the log — which is free,
+ * because the log is the same in-memory immutable array the fold read.
+ *
+ * That is also why this module lives in the adapter: it is the only place that
+ * reads raw event payloads for display, and the boundary gate keeps it here.
+ * The scene renders the returned sections without knowing what an event is.
+ */
+import type { TrajNode } from './types.js';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** One titled block of full content. */
+export interface InspectSection {
+    readonly title: string;
+    /** Raw body; the view truncates to its own box. */
+    readonly body: string;
+    /** Render hint: `error` for failures, `dim` for supporting material. */
+    readonly tone?: 'error' | 'dim';
+}
+/** Everything the inspector shows for one row. */
+export interface InspectDetail {
+    readonly title: string;
+    /** Short `key value` facts rendered on the header line. */
+    readonly facts: readonly string[];
+    readonly sections: readonly InspectSection[];
+}
+/**
+ * Resolve the full detail for one ledger row.
+ *
+ * @param node - The focused row.
+ * @param events - The session's current event snapshot.
+ * @returns Display-ready sections. Always succeeds: a row whose owning event
+ *   has been compacted away still yields its header facts.
+ */
+export declare function inspectNode(node: TrajNode, events: readonly SessionEvent[]): InspectDetail;
+//# sourceMappingURL=inspect.d.ts.map

package/lib/types/dsh-adapter/trajectory/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/trajectory/inspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;CAChC;AAED,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;CAC7C;AAwCD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,aAAa,CA2F1F"}

package/lib/types/dsh-adapter/trajectory/inspect.js

@@ -0,0 +1,160 @@
+/**
+ * Inspector detail — full content, resolved on demand.
+ *
+ * The projection stores no message bodies: a node keeps `seq` (and `endSeq`)
+ * and nothing else about content, so a ten-thousand-row session costs a few
+ * hundred kilobytes of index rather than a second copy of the transcript. The
+ * price is that opening a row has to go back to the log — which is free,
+ * because the log is the same in-memory immutable array the fold read.
+ *
+ * That is also why this module lives in the adapter: it is the only place that
+ * reads raw event payloads for display, and the boundary gate keeps it here.
+ * The scene renders the returned sections without knowing what an event is.
+ */
+import { asRawEvents, readRetry } from './guards.js';
+/** Binary search for an event by seq; the log is seq-monotonic. */
+function findBySeq(events, seq) {
+    let low = 0;
+    let high = events.length - 1;
+    while (low <= high) {
+        const mid = (low + high) >> 1;
+        const candidate = events[mid];
+        if (candidate.seq === seq)
+            return candidate;
+        if (candidate.seq < seq)
+            low = mid + 1;
+        else
+            high = mid - 1;
+    }
+    return undefined;
+}
+/** Pretty-print a JSON string; returns the input unchanged when it is not JSON. */
+function prettyJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{') && !trimmed.startsWith('['))
+        return text;
+    try {
+        return JSON.stringify(JSON.parse(trimmed), null, 2);
+    }
+    catch {
+        return text;
+    }
+}
+/** Concatenate every text block of a message content array. */
+function allText(content) {
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const record = block;
+        if (typeof record.text === 'string')
+            parts.push(record.text);
+        else if (record.type === 'image')
+            parts.push('[image]');
+    }
+    return parts.join('\n');
+}
+/**
+ * Resolve the full detail for one ledger row.
+ *
+ * @param node - The focused row.
+ * @param events - The session's current event snapshot.
+ * @returns Display-ready sections. Always succeeds: a row whose owning event
+ *   has been compacted away still yields its header facts.
+ */
+export function inspectNode(node, events) {
+    const raw = asRawEvents(events);
+    const open = findBySeq(raw, node.seq);
+    const close = node.endSeq === undefined ? undefined : findBySeq(raw, node.endSeq);
+    const data = open?.data;
+    const facts = [];
+    if (node.turn > 0)
+        facts.push(node.step === undefined ? `turn ${node.turn}` : `turn ${node.turn} · step ${node.step}`);
+    if (node.callId !== undefined)
+        facts.push(node.callId.slice(0, 12));
+    if (node.tokens !== undefined) {
+        const { input, output, think, cacheRead } = node.tokens;
+        facts.push(`in ${input} · out ${output}${think > 0 ? ` · think ${think}` : ''}${cacheRead > 0 ? ` · cache ${cacheRead}` : ''}`);
+    }
+    const sections = [];
+    switch (node.kind) {
+        case 'tool':
+        case 'subtool': {
+            const args = node.detail;
+            if (args !== undefined && args !== '')
+                sections.push({ title: 'input', body: prettyJson(args) });
+            const message = close?.data?.message;
+            const body = typeof message === 'object' && message !== null
+                ? allText(message.content)
+                : (node.outcome ?? '');
+            if (body !== '')
+                sections.push({ title: 'output', body, tone: node.status === 'error' ? 'error' : undefined });
+            if (node.errorCode !== undefined)
+                sections.push({ title: 'error', body: node.errorCode, tone: 'error' });
+            break;
+        }
+        case 'retry': {
+            const payload = open === undefined ? undefined : readRetry(open.data);
+            if (payload !== undefined) {
+                facts.push(`${node.attempts ?? 1} attempts`);
+                if (payload.provider !== undefined)
+                    facts.push(payload.provider);
+                sections.push({
+                    title: 'cause',
+                    body: `${payload.code ?? 'unknown'} — ${payload.message ?? ''}`.trim(),
+                    tone: 'error',
+                });
+            }
+            // Every attempt of this sequence, so the backoff ladder is visible.
+            const ladder = [];
+            for (const event of raw) {
+                if (event.type !== 'llm/retry')
+                    continue;
+                const attempt = readRetry(event.data);
+                if (attempt === undefined || payload === undefined || attempt.retryId !== payload.retryId)
+                    continue;
+                ladder.push(`#${attempt.retry} → ${Math.round(attempt.delayMs)}ms`);
+            }
+            if (ladder.length > 0)
+                sections.push({ title: 'backoff', body: ladder.join('  ') });
+            break;
+        }
+        case 'approval': {
+            if (node.detail !== undefined)
+                sections.push({ title: 'reason', body: node.detail });
+            if (node.outcome !== undefined) {
+                sections.push({ title: 'outcome', body: node.outcome, tone: node.status === 'error' ? 'error' : undefined });
+            }
+            break;
+        }
+        case 'user':
+        case 'assistant':
+        case 'thinking':
+        case 'context': {
+            const content = data?.content ?? data?.message?.content;
+            const body = allText(content);
+            sections.push({ title: node.kind, body: body === '' ? (node.detail ?? '') : body });
+            break;
+        }
+        default: {
+            if (node.detail !== undefined && node.detail !== '')
+                sections.push({ title: 'detail', body: node.detail });
+            if (node.outcome !== undefined && node.outcome !== '')
+                sections.push({ title: 'outcome', body: node.outcome });
+            break;
+        }
+    }
+    if (node.burst !== undefined) {
+        sections.unshift({
+            title: `${node.burst.members.length} calls`,
+            body: node.burst.members
+                .map((member, position) => `${position + 1}. ${(member.detail ?? '').replace(/\s+/g, ' ').slice(0, 120)}`)
+                .join('\n'),
+            tone: 'dim',
+        });
+    }
+    const title = node.label === '' ? node.kind : node.label;
+    return { title, facts, sections };
+}

package/lib/types/dsh-adapter/trajectory/projection.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Trajectory projection — folding the session event log into ledger nodes.
+ *
+ * ## What this is
+ *
+ * The DSH session log is an append-only stream of ~44 event types. This
+ * module folds it into the flat, turn-annotated node list the trajectory
+ * scene renders, pairing every bracket (`tool/call` ↔ `tool/result`,
+ * `step/start` ↔ `step/end`, `llm/retry` ↔ `llm/retry-started`,
+ * `approval/asked` ↔ `approval/decided`, `compaction/start` ↔
+ * `compaction/end`, `tool/code-dispatch-start` ↔ `tool/code-dispatch`) so a
+ * row can show its own wall-clock duration and outcome.
+ *
+ * ## Incrementality
+ *
+ * `agent.session.events` is an immutable snapshot whose element objects are
+ * frozen at append and REUSED until the next append. {@link extendTrajectory}
+ * exploits exactly that: when the incoming snapshot prefix-extends the one the
+ * previous build consumed — proven by *object identity* at the previous last
+ * index, never by `seq` arithmetic, which a fork can rewind — only the new
+ * tail is folded. Any other relationship (agent swap on `/resume`, `/rewind`,
+ * `/new`) rebuilds from scratch. A long session therefore never pays an O(n)
+ * refold per frame, and `verify-trace-projection` asserts that the incremental
+ * and from-scratch results are field-for-field identical at every split point.
+ *
+ * ## What it deliberately does not do
+ *
+ * No node holds derived text. `detail`/`outcome` are references into strings
+ * the log already owns, and the view flattens only the rows it paints (see
+ * {@link previewText}). Full content is not held at all — `seq`/`endSeq`
+ * address the owning events for the inspector to re-read on demand.
+ *
+ * Storage-level chunk packing (`text-chunks`, `reasoning-chunks`,
+ * `tool-call-chunks`) is a durable *encoding*, not an event vocabulary: the
+ * persistence reader expands those rows back into `assistant/chunk` events
+ * before they reach `Session.events`, so this fold only ever sees the
+ * expanded form.
+ */
+import { type RawTrajEvent } from './guards.js';
+import { type TrajNode } from './types.js';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Per-step streaming timestamps, the source of TTFT and decode duration. */
+export interface StepTiming {
+    /** `step/start` time. */
+    readonly startTime: number;
+    /** First `assistant/chunk` time — the model's first observable output. */
+    firstChunk?: number;
+    /** Last `assistant/chunk` time. */
+    lastChunk?: number;
+    /** `step/end` time, when the step closed. */
+    endTime?: number;
+}
+/**
+ * One assembled projection. Carries everything a continuation needs, so an
+ * append folds only its tail; treat every field as owned by this module.
+ */
+export interface TrajBuild {
+    /** The snapshot this build consumed; identity-compared on the next append. */
+    readonly source: readonly RawTrajEvent[];
+    /** The ledger, in log order, after burst folding. */
+    readonly nodes: TrajNode[];
+    /** Per-step timing keyed `${turn}:${step}`, for the hotspot aggregate. */
+    readonly timing: Map<string, StepTiming>;
+    /**
+     * Running counters, maintained O(1) per event.
+     *
+     * The status-line badge needs "how many rows, how many failed" on every
+     * chat frame; deriving that with a scan would make an idle conversation pay
+     * O(session) per repaint, which is exactly the cost the incremental fold
+     * exists to avoid.
+     */
+    readonly counts: TrajCounts;
+    /** Open brackets and fold state; internal, but reused across appends. */
+    readonly state: FoldState;
+}
+/** Cheap session counters the chat chrome reads every frame. */
+export interface TrajCounts {
+    /** Ledger rows, after burst folding. */
+    rows: number;
+    /** Rows that ended in failure, plus retry sequences. */
+    errors: number;
+    /** Retry attempts across the session. */
+    retries: number;
+}
+/** Mutable fold bookkeeping carried between incremental appends. */
+interface FoldState {
+    counts: TrajCounts;
+    tools: Map<string, TrajNode>;
+    subtools: Map<string, TrajNode>;
+    steps: Map<string, TrajNode>;
+    turns: Map<number, TrajNode>;
+    retries: Map<string, TrajNode>;
+    approvals: Map<string, TrajNode>;
+    hooks: Map<string, TrajNode>;
+    /** Compaction brackets carry no observed id — a stack pairs them by nesting. */
+    compactions: TrajNode[];
+    /** Live turn context for events that carry none. */
+    turn: number;
+    /** Live step context; cleared at `step/end`. */
+    step: number | undefined;
+    /** True until the first `session/end-seed`; marks replayed history. */
+    seeding: boolean;
+    /** `${kind}:${name}` of the run being folded, or undefined. */
+    runKey: string | undefined;
+    /** Length of the current run. */
+    runCount: number;
+    /** Index in `nodes` of the run's first row (or its burst stand-in). */
+    runStart: number;
+    /** Members of the run, kept so the burst node can adopt them. */
+    runMembers: TrajNode[];
+}
+/** An empty build, used as the identity element and for empty sessions. */
+export declare function emptyTrajectory(): TrajBuild;
+/**
+ * Extend a previous projection with the session's current event snapshot.
+ *
+ * @param previous - The prior build, or `null` to fold from scratch.
+ * @param events - The session's current immutable event snapshot.
+ * @returns A build over `events`; `previous` itself when nothing was appended.
+ */
+export declare function extendTrajectory(previous: TrajBuild | null, events: readonly SessionEvent[]): TrajBuild;
+/**
+ * Fold from scratch — the one-shot form used by tests and by consumers that
+ * hold no previous build.
+ */
+export declare function buildTrajectory(events: readonly SessionEvent[]): TrajBuild;
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/dsh-adapter/trajectory/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/trajectory/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAeL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EAA4B,KAAK,QAAQ,EAAmB,MAAM,YAAY,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAC1B;AAED,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,oEAAoE;AACpE,UAAU,SAAS;IACjB,MAAM,EAAE,UAAU,CAAA;IAClB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC/B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC5B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC5B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC9B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAChC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC5B,gFAAgF;IAChF,WAAW,EAAE,QAAQ,EAAE,CAAA;IACvB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,UAAU,EAAE,QAAQ,EAAE,CAAA;CACvB;AA6kBD,2EAA2E;AAC3E,wBAAgB,eAAe,IAAI,SAAS,CAG3C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,GAAG,IAAI,EAC1B,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,SAAS,CAwBX;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,CAE1E"}