@deepseek-harness-tui/dsh-tui 0.9.0 → 0.9.2

package/lib/types/dsh-adapter/compat/index.d.ts

@@ -11,12 +11,14 @@
  *
  * Current residents:
  *  - sessionLog: tolerant title reads plus offline rename/delete helpers for
- *    persisted sessions that are not currently owned by a live Agent, and
- *    the resume-seam registration of vouched-for legacy event types into
- *    every reachable KNOWN_SESSION_EVENT_TYPES copy — retiring the day
- *    upstream's shared catalog adopts the types or ships a real
- *    registration API (issue #153).
+ *    persisted sessions that are not currently owned by a live Agent, the
+ *    resume-seam registration of vouched-for legacy event types into every
+ *    reachable KNOWN_SESSION_EVENT_TYPES copy (retiring the day upstream's
+ *    shared catalog adopts the types or ships a real registration API —
+ *    issue #153), and the bounded read-only log reader behind the session
+ *    tree (chunked I/O, lazy zstd frame walk, event + scan budgets,
+ *    inherited-prefix skip).
  * @module @deepseek-harness-tui/dsh-tui/compat
  */
-export { appendSessionTitle, deleteSessionLog, ensureLegacySessionEventTypes, findSessionLogFile, LEGACY_SESSION_EVENT_TYPES, readSessionTitleFromLog, sessionsRoots, } from './sessionLog.js';
+export { appendSessionTitle, defaultMaxScanned, deleteSessionLog, ensureLegacySessionEventTypes, findSessionLogFile, LEGACY_SESSION_EVENT_TYPES, readSessionEventsFromFile, readSessionEventsFromLog, readSessionTitleFromLog, type SessionLogRead, sessionsRoots, } from './sessionLog.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/dsh-adapter/compat/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,6BAA6B,EAC7B,kBAAkB,EAClB,0BAA0B,EAC1B,uBAAuB,EACvB,aAAa,GACd,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,6BAA6B,EAC7B,kBAAkB,EAClB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,KAAK,cAAc,EACnB,aAAa,GACd,MAAM,iBAAiB,CAAA"}

package/lib/types/dsh-adapter/compat/index.js

@@ -11,11 +11,13 @@
  *
  * Current residents:
  *  - sessionLog: tolerant title reads plus offline rename/delete helpers for
- *    persisted sessions that are not currently owned by a live Agent, and
- *    the resume-seam registration of vouched-for legacy event types into
- *    every reachable KNOWN_SESSION_EVENT_TYPES copy — retiring the day
- *    upstream's shared catalog adopts the types or ships a real
- *    registration API (issue #153).
+ *    persisted sessions that are not currently owned by a live Agent, the
+ *    resume-seam registration of vouched-for legacy event types into every
+ *    reachable KNOWN_SESSION_EVENT_TYPES copy (retiring the day upstream's
+ *    shared catalog adopts the types or ships a real registration API —
+ *    issue #153), and the bounded read-only log reader behind the session
+ *    tree (chunked I/O, lazy zstd frame walk, event + scan budgets,
+ *    inherited-prefix skip).
  * @module @deepseek-harness-tui/dsh-tui/compat
  */
-export { appendSessionTitle, deleteSessionLog, ensureLegacySessionEventTypes, findSessionLogFile, LEGACY_SESSION_EVENT_TYPES, readSessionTitleFromLog, sessionsRoots, } from './sessionLog.js';
+export { appendSessionTitle, defaultMaxScanned, deleteSessionLog, ensureLegacySessionEventTypes, findSessionLogFile, LEGACY_SESSION_EVENT_TYPES, readSessionEventsFromFile, readSessionEventsFromLog, readSessionTitleFromLog, sessionsRoots, } from './sessionLog.js';

package/lib/types/dsh-adapter/compat/sessionLog.d.ts

@@ -1,3 +1,53 @@
+/**
+ * Session-log compatibility helpers.
+ *
+ * Title lookup tolerates event types unknown to the current harness. Offline
+ * rename and delete support the `/resume` picker when no live Agent owns the
+ * selected persisted session. The resume seam registers vouched-for legacy
+ * event types into every reachable KNOWN_SESSION_EVENT_TYPES copy so the
+ * strict read path stops rejecting whole sessions over them (issue #153).
+ *
+ * Registration background: plugins like dsh-working-activity (< the publish
+ * cut) appended `activity/status` through `session.append`, but rc.6's
+ * append exposes no `ignorable` flag and the type is absent from
+ * KNOWN_SESSION_EVENT_TYPES — so resume's seed validation rejects the WHOLE
+ * session ("unknown to this harness and not marked ignorable"). Upstream's
+ * catalog header defers a registration surface "until such a consumer
+ * exists"; the working-activity plugin became that consumer at #119 and
+ * registers its type at load. Logs written BEFORE that cut, resumed in a
+ * process where the plugin's registration never ran (plugin unmounted, or
+ * a bare cordis.yml), still hit the rejection — this module is the consumer
+ * for exactly that residue.
+ *
+ * Why registration and NOT rewriting the log to mark events `ignorable`
+ * (the #107 approach, restored then replaced after review): the store is
+ * shared with dsh web (#24) and possibly a second TUI instance (#153), and
+ * a whole-file tmp+rename swap (a) loses frames an already-open appender
+ * lands on the replaced inode, (b) drops the backend's 0600 artifact mode,
+ * (c) re-encodes frames without the writer's checksum flag, and (d) dies on
+ * torn tails the backend itself can recover. Registration touches nothing
+ * on disk and degrades to exactly the pre-patch behavior when no copy
+ * resolves.
+ *
+ * Whitelist discipline: ONLY `activity/status` — the type the plugin
+ * provably wrote as ephemeral UI frames. Anything else unknown stays
+ * unknown: upstream's fail-closed ("likely written by a newer harness") is
+ * a feature — silently skipping a REQUIRED future event would reconstruct
+ * a wrong session. Retires the day upstream's shared catalog adopts the
+ * type or ships a real registration API (the add() calls become no-ops).
+ *
+ * The second half of this module is the bounded, tolerant, read-only log
+ * reader behind the session tree (channel.buildSessionTree): 64 KiB chunked
+ * I/O, lazy per-frame zstd decode over an RFC 8878 structural frame walk (a
+ * torn final frame — crash mid-flush — is dropped as uncommitted, never
+ * fatal), packed-row expansion, an event budget plus a scanned-envelope
+ * budget so ignorable-heavy logs cannot multiply the cost of opening the
+ * panel, and an inherited-prefix skip so a fork's event budget pays only for
+ * its OWN events. It never writes; both stock encodings are read.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/compat/sessionLog
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
 /**
  * Legacy third-party session-event types the TUI vouches for as ephemeral
  * UI frames — safe for the strict read path to accept and skip. Exported
@@ -22,6 +72,106 @@ export declare function sessionsRoots(): string[];
  * @returns Absolute path of session.jsonl.zstd, or undefined when absent.
  */
 export declare function findSessionLogFile(sessionId: string): string | undefined;
+/** Outcome of reading an EXISTING log through the bounded reader. */
+export interface SessionLogRead {
+    readonly events: readonly SessionEvent[];
+    /** False when the read stopped early (event/scan budget) — a plain
+     *  truncation; the collected prefix is fully usable. */
+    readonly complete: boolean;
+    /** Envelopes inspected (collected or skipped) — the real scan cost. */
+    readonly scanned: number;
+    /** True when an EXISTING log could not be read: corruption, a torn first
+     *  frame, an over-cap frame, a decode bomb. Distinct from ABSENT (which
+     *  reports `undefined`): a failed log must degrade to a structure-only
+     *  placeholder and must NOT be retried through an unbounded strict read —
+     *  that fallback would defeat every cap this reader exists to enforce.
+     *  `events` keeps the partial prefix collected before the failure, for
+     *  diagnostics; callers building trees ignore it. */
+    readonly failed?: boolean;
+}
+/**
+ * Default scan budget derived from the event budget: 4× headroom over the
+ * collectible events (legitimate logs interleave a modest share of skipped
+ * rows — headers, repair-marked ignorable frames), plus a floor so even a
+ * tiny `maxEvents` tolerates a noisy prefix. Unbounded reads stay unbounded.
+ */
+export declare function defaultMaxScanned(maxEvents: number): number;
+/**
+ * File-level sibling of {@link readSessionEventsFromLog} for paths resolved
+ * by the backend itself (`persistence.locate`) — covers a custom-configured
+ * root that none of the stock sessionsRoots() candidates describes.
+ * @param path - Absolute artifact path (physical or logical name).
+ * @param maxEvents - Stop before collecting more than this many events.
+ * @param maxScanned - Stop after INSPECTING this many envelopes, collected
+ *   or skipped (default: {@link defaultMaxScanned} of maxEvents).
+ * @param skipBelowSeq - Inherited-prefix cutoff (session-tree dedup):
+ *   seq'd events below it are skipped without spending the event budget —
+ *   they still count against maxScanned. `session/title` events are always
+ *   collected (branch-head labels need them; they never become entries).
+ * @returns The read outcome, or undefined ONLY when nothing materialized at
+ *   the path — an existing-but-undecodable log reports `failed: true`.
+ */
+export declare function readSessionEventsFromFile(path: string, maxEvents?: number, maxScanned?: number, skipBelowSeq?: number): SessionLogRead | undefined;
+/**
+ * Read a session's events from its persisted log — tolerant, read-only, and
+ * cost-bounded. Built for the session tree (buildSessionTree), whose browse
+ * must satisfy three constraints the strict backend read cannot:
+ *
+ *  - READ-ONLY: `persistence.inspect` rejects logs carrying third-party
+ *    event types (working-activity's `activity/status`), and the resume
+ *    seam's answer (in-process type registration, issue #153) must not be
+ *    inverted here: opening a picker never rewrites a history log. This
+ *    reader never writes; unknown types are simply passed through
+ *    (extractEntries skips what it does not know).
+ *  - TOLERANT: envelope-shape or decode anomalies degrade to
+ *    `failed: true` (a structure-only tree node) instead of rejecting the
+ *    whole log — and a torn FINAL zstd frame (crash mid-flush) is dropped
+ *    as uncommitted, keeping the frames before it readable.
+ *  - BOUNDED: the file is read in 64 KiB slices and frames decode lazily,
+ *    stopping the moment `maxEvents` events have been collected — a
+ *    200k-event log costs budget × per-event work, not a whole-file read +
+ *    decompress + parse. `complete: false` marks the early stop (the caller
+ *    surfaces it as `truncated`). One honest exception: a single zstd FRAME
+ *    is the atomic unit (see logRecords) — the budget bounds work ACROSS
+ *    frames, never inside one giant flush.
+ *
+ * Packed rows are expanded with the backend's own `decodeStorageRecord`:
+ * the packChunks writer folds each run of same-block delta chunks into ONE
+ * `text-chunks`/`reasoning-chunks`/`tool-call-chunks` line (the default —
+ * the finding that motivated this reader's third revision), so a line is a
+ * storage record, not an event, and seq-less rows must not be dropped as if
+ * they were headers. The budget counts EXPANDED events, matching the tree's
+ * per-event cost. Malformed packed rows throw inside decodeStorageRecord —
+ * corrupt storage degrades to `undefined`, never to silently dropped runs.
+ *
+ * Torn-tail semantics mirror the backend's own reader: a plain log's
+ * unterminated final line (crash mid-append) is uncommitted data and
+ * ignored, while an unterminated record INSIDE a complete zstd frame is
+ * corruption and fails the read.
+ *
+ * Envelopes with `ignorable: true` are skipped (the read path's own skip
+ * signal) and the seq-less header row is metadata, not an event. Skipped
+ * envelopes still count against the SCAN budget (maxScanned): skipping is
+ * not free — the I/O, decompress and JSON.parse for them have already been
+ * paid — so an ignorable-heavy log cannot bypass the cost bound by keeping
+ * its collectible count low. Never throws; returns undefined ONLY when the
+ * log is absent — an existing-but-undecodable log returns `failed: true`
+ * so the caller degrades to a placeholder instead of escalating to an
+ * unbounded strict re-read.
+ * @param sessionId - Session whose log should be read.
+ * @param maxEvents - Stop before collecting more than this many events
+ *   (default: unbounded). 0 collects nothing and reports complete: false
+ *   whenever the log holds any collectible event.
+ * @param maxScanned - Stop after INSPECTING this many envelopes, collected
+ *   or skipped (default: 4× maxEvents + 4096; unbounded when maxEvents is).
+ * @param skipBelowSeq - Inherited-prefix cutoff (session-tree dedup):
+ *   seq'd events below it are skipped without spending the event budget —
+ *   they still count against maxScanned. `session/title` events are always
+ *   collected (branch-head labels need them; they never become entries).
+ * @returns The read outcome — events, completeness, real scan cost, and a
+ *   `failed` marker for safety-cap/corruption bailouts.
+ */
+export declare function readSessionEventsFromLog(sessionId: string, maxEvents?: number, maxScanned?: number, skipBelowSeq?: number): SessionLogRead | undefined;
 /**
  * Register every {@link LEGACY_SESSION_EVENT_TYPES} type as known in EVERY
  * reachable KNOWN_SESSION_EVENT_TYPES copy, ahead of the strict read path

package/lib/types/dsh-adapter/compat/sessionLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessionLog.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/sessionLog.ts"],"names":[],"mappings":"AAqDA;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAwB,CAAA;AAKhF;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CASxC;AAaD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAexE;AA+BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAkCpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAyBzD;AAyBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa,CAwB/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAwB7E"}
+{"version":3,"file":"sessionLog.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/sessionLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAiB5D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAwB,CAAA;AAKhF;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CASxC;AAaD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAexE;AAsXD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC;4DACwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;yDAMqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AA+DD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAiC,EAC5C,UAAU,GAAE,MAAqC,EACjD,YAAY,GAAE,MAAU,GACvB,cAAc,GAAG,SAAS,CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,MAAiC,EAC5C,UAAU,GAAE,MAAqC,EACjD,YAAY,GAAE,MAAU,GACvB,cAAc,GAAG,SAAS,CAI5B;AA+BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAkCpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAyBzD;AAyBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa,CAwB/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAwB7E"}