@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/sessions/digest.d.ts

@@ -0,0 +1,54 @@
+import type { PreviewEntry, SessionDigest, SessionTitle } from './types.js';
+/** Head window budget. Eight times the measured worst-case prompt offset. */
+export declare const HEAD_WINDOW_BYTES: number;
+/** Head frame ceiling — a cost bound independent of how the bytes compress. */
+export declare const HEAD_MAX_FRAMES = 128;
+/** Tail window budget. Wider than the head: trailing frames carry payloads. */
+export declare const TAIL_WINDOW_BYTES: number;
+/**
+ * Read both windows of one session log.
+ *
+ * @param path - Absolute artifact path.
+ * @param cwd - Working directory, for the last-resort title.
+ * @returns The digest. An unreadable log still yields a usable record: the
+ *   title falls back to the directory basename and says so through its source.
+ */
+export declare function digestSession(path: string, cwd: string): SessionDigest;
+export interface SessionTitleRecovery {
+    readonly title: SessionTitle | undefined;
+    /** False means a damaged/oversized frame prevented a conclusive answer. */
+    readonly complete: boolean;
+    /** Known only when a full no-title scan then reached/ruled out the prompt. */
+    readonly hasPrompt?: boolean;
+}
+export interface AppendedDigest {
+    readonly title: SessionTitle | undefined;
+    readonly model: string | undefined;
+    readonly label: string | undefined;
+    readonly hasHumanPrompt: boolean;
+    /** Only a fully decoded suffix may be folded onto cached prefix facts. */
+    readonly complete: boolean;
+}
+/** Scan all newly appended frames from the previous EOF frame boundary. */
+export declare function digestAppendedSuffix(path: string, start: number, end: number, signal?: AbortSignal): Promise<AppendedDigest>;
+/**
+ * Recover the authoritative display title for one immutable file snapshot:
+ * reverse scan for the LAST title, then (only when none exists) forward scan
+ * for the FIRST human prompt. Both directions page on verified frame boundaries.
+ */
+export declare function recoverSessionTitle(path: string, bytes: number, signal?: AbortSignal): Promise<SessionTitleRecovery>;
+/** Hash the previous EOF neighborhood; this detects replacement near the old tail. */
+export declare function sessionTitleAnchor(path: string, bytes: number, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * The last exchanges of a session, for the browser's preview pane.
+ *
+ * Bounded like everything else here: the preview shows the end of the
+ * conversation because that is what the tail window holds, and because the end
+ * is what tells you whether this is the session you meant.
+ *
+ * @param path - Absolute artifact path.
+ * @param limit - How many entries to keep, newest last.
+ * @returns Entries in log order.
+ */
+export declare function previewSession(path: string, limit: number): PreviewEntry[];
+//# sourceMappingURL=digest.d.ts.map

package/lib/types/dsh-adapter/sessions/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/sessions/digest.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3E,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,QAAY,CAAA;AAC1C,+EAA+E;AAC/E,eAAO,MAAM,eAAe,MAAM,CAAA;AAClC,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,QAAa,CAAA;AAwG3C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAyDtE;AAID,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B;AA2GD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED,2EAA2E;AAC3E,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAuCzB;AA8CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAS/B;AAED,sFAAsF;AACtF,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAyB1E"}

package/lib/types/dsh-adapter/sessions/digest.js

@@ -0,0 +1,478 @@
+/**
+ * What a bounded read can learn about a session log.
+ *
+ * Two windows, one at each end, and never anything in between:
+ *
+ * - The HEAD normally holds the session envelope, boot policy events, and the
+ *   opening prompt. Measured across a real corpus, the first user prompt lands
+ *   within 8,107 bytes of the start (524 in its `agent/inbox/spliced` form),
+ *   so a 64 KB window is the cheap path. A larger modern context prefix can
+ *   exceed it; listSummaries schedules the progressive opening scan below
+ *   after returning the immediately usable session list.
+ * - The TAIL holds whatever was appended most recently: the current title
+ *   (titles are re-emitted, and the last one wins), the model of the last
+ *   request, and the last exchanges for the preview.
+ *
+ * Titles carry their own provenance, so this module does not have to guess.
+ * A title written by a provider records `source.kind: 'provider'`; the TUI's
+ * own rename paths append `{ title }` with no source at all. That difference
+ * is the evidence behind {@link SessionTitle.source}, which is why the picker
+ * can dim a fallback and explain a name instead of merely displaying one.
+ *
+ * @module dsh-cli/sessions/digest
+ */
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { scheduler } from 'node:timers/promises';
+import { decodeFrame, decodeTail, readWindow, resyncFrames, walkFrames } from './frames.js';
+/** Head window budget. Eight times the measured worst-case prompt offset. */
+export const HEAD_WINDOW_BYTES = 64 * 1024;
+/** Head frame ceiling — a cost bound independent of how the bytes compress. */
+export const HEAD_MAX_FRAMES = 128;
+/** Tail window budget. Wider than the head: trailing frames carry payloads. */
+export const TAIL_WINDOW_BYTES = 128 * 1024;
+/** Compressed bytes read per progressive title-scan page. */
+const TITLE_SCAN_PAGE_BYTES = 128 * 1024;
+/** Largest compressed frame the fallback scanner will materialize. */
+const TITLE_SCAN_MAX_FRAME_BYTES = 16 * 1024 * 1024;
+/** Old EOF neighborhood hashed for the JSONL backend's append-only contract. */
+const TITLE_ANCHOR_BYTES = 256;
+/** Longest preview excerpt kept per message, in characters. */
+const PREVIEW_CHARS = 400;
+/** The first text block of a message `content` payload. */
+function textOfContent(content) {
+    if (typeof content === 'string')
+        return content.trim() || undefined;
+    if (!Array.isArray(content))
+        return undefined;
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const record = block;
+        if (record['type'] !== 'text')
+            continue;
+        const value = record['text'];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value.trim();
+    }
+    return undefined;
+}
+/**
+ * Whether a message's `source` marks it as typed by the person at the
+ * keyboard. Plugin injections, instruction snapshots, skill catalogues and
+ * sub-agent reports all arrive as user-role messages too, and counting them
+ * would report a conversation where none happened.
+ */
+function isHumanSource(source) {
+    if (source === undefined || source === null)
+        return true;
+    if (typeof source !== 'object')
+        return false;
+    return source['kind'] === 'user';
+}
+/** A human message is conversation evidence even when it has no title text. */
+function humanPrompt(line) {
+    const data = line['data'];
+    if (data === null || typeof data !== 'object')
+        return undefined;
+    const record = data;
+    if (line['type'] === 'user/message') {
+        return isHumanSource(record['source']) ? { text: textOfContent(record['content']) } : undefined;
+    }
+    // The inbox splice precedes the durable user/message and reaches the log
+    // several frames earlier, which is what keeps the head window small.
+    if (line['type'] === 'agent/inbox/spliced') {
+        const inserted = record['inserted'];
+        if (!Array.isArray(inserted))
+            return undefined;
+        let found = false;
+        for (const message of inserted) {
+            if (message === null || typeof message !== 'object')
+                continue;
+            const entry = message;
+            if (entry['role'] !== 'user' || !isHumanSource(entry['source']))
+                continue;
+            found = true;
+            const text = textOfContent(entry['content']);
+            if (text !== undefined)
+                return { text };
+        }
+        if (found)
+            return { text: undefined };
+    }
+    return undefined;
+}
+/** A `session/title` payload, with the provenance that classifies it. */
+function titleOf(line) {
+    if (line['type'] !== 'session/title')
+        return undefined;
+    const data = line['data'];
+    if (data === null || typeof data !== 'object')
+        return undefined;
+    const record = data;
+    const text = record['title'];
+    if (typeof text !== 'string' || text.trim().length === 0)
+        return undefined;
+    const source = record['source'];
+    const byProvider = source !== null &&
+        typeof source === 'object' &&
+        source['kind'] === 'provider';
+    return { text: text.trim(), source: byProvider ? 'auto' : 'renamed' };
+}
+/** The route recorded by a `request/context` event. */
+function modelOf(line) {
+    if (line['type'] !== 'request/context')
+        return undefined;
+    const data = line['data'];
+    if (data === null || typeof data !== 'object')
+        return undefined;
+    const model = data['model'];
+    return typeof model === 'string' && model.length > 0 ? model : undefined;
+}
+/** The label a delegated run was started under. */
+function labelOf(line) {
+    if (line['type'] !== 'subagent/descriptor')
+        return undefined;
+    const data = line['data'];
+    if (data === null || typeof data !== 'object')
+        return undefined;
+    const label = data['label'];
+    return typeof label === 'string' && label.trim().length > 0 ? label.trim() : undefined;
+}
+/** Epoch-ms of a log line, when it carries one. */
+function timeOf(line) {
+    const time = line['time'];
+    return typeof time === 'number' && Number.isFinite(time) ? time : undefined;
+}
+/**
+ * Read both windows of one session log.
+ *
+ * @param path - Absolute artifact path.
+ * @param cwd - Working directory, for the last-resort title.
+ * @returns The digest. An unreadable log still yields a usable record: the
+ *   title falls back to the directory basename and says so through its source.
+ */
+export function digestSession(path, cwd) {
+    const head = readWindow(path, HEAD_WINDOW_BYTES);
+    if (head === undefined) {
+        return { title: undefined, hasPrompt: true, model: undefined, label: undefined };
+    }
+    const headFrames = walkFrames(head.buffer, 0, HEAD_MAX_FRAMES);
+    const headLines = [];
+    let completeHead = head.whole && headFrames.at(-1)?.end === head.buffer.length;
+    for (const frame of headFrames) {
+        const lines = decodeFrame(head.buffer, frame);
+        if (lines === undefined)
+            completeHead = false;
+        else
+            headLines.push(...lines);
+    }
+    completeHead &&= headLines[0]?.['type'] === 'session';
+    let prompt;
+    let hasHumanMessage = false;
+    let headTitle;
+    let label;
+    for (const line of headLines) {
+        const human = humanPrompt(line);
+        hasHumanMessage ||= human !== undefined;
+        prompt ??= human?.text;
+        headTitle ??= titleOf(line);
+        label ??= labelOf(line);
+    }
+    // The byte window, frame limit, decoding and parsing must ALL cover the
+    // log before absence proves emptiness. Unknown is visible, never eligible
+    // for destructive cleanup; title text is not required for image-only input.
+    const hasPrompt = hasHumanMessage || !completeHead;
+    // Only a completely decoded head can stand in for the tail.
+    const tail = completeHead ? undefined : readWindow(path, TAIL_WINDOW_BYTES, true);
+    const tailLines = tail === undefined ? headLines : decodeTail(tail);
+    let tailTitle;
+    let model;
+    for (const line of tailLines) {
+        const title = titleOf(line);
+        if (title !== undefined)
+            tailTitle = title;
+        const route = modelOf(line);
+        if (route !== undefined)
+            model = route;
+    }
+    const resolved = tailTitle ??
+        headTitle ??
+        (prompt === undefined ? undefined : { text: prompt, source: 'prompt' });
+    return {
+        title: resolved ?? { text: basename(cwd), source: 'fallback' },
+        hasPrompt,
+        model,
+        label,
+        ...(!completeHead && tailTitle === undefined ? {} : { titleComplete: true }),
+    };
+}
+/** Read exactly one stable range from an already-open snapshot. */
+async function readRange(handle, start, length, signal) {
+    const buffer = Buffer.allocUnsafe(length);
+    let filled = 0;
+    while (filled < length) {
+        signal?.throwIfAborted();
+        let bytesRead;
+        try {
+            const result = await handle.read(buffer, filled, length - filled, start + filled);
+            bytesRead = result.bytesRead;
+        }
+        catch {
+            signal?.throwIfAborted();
+            return undefined;
+        }
+        if (bytesRead === 0)
+            return undefined;
+        filled += bytesRead;
+    }
+    return buffer;
+}
+/** A forward page beginning on a known frame boundary. */
+async function forwardPage(handle, start, end, signal) {
+    const remaining = end - start;
+    let length = Math.min(TITLE_SCAN_PAGE_BYTES, remaining);
+    while (length > 0) {
+        const buffer = await readRange(handle, start, length, signal);
+        if (buffer === undefined)
+            return undefined;
+        const frames = walkFrames(buffer);
+        if (frames.length > 0)
+            return { buffer, frames };
+        if (length >= remaining || length >= TITLE_SCAN_MAX_FRAME_BYTES)
+            return undefined;
+        length = Math.min(remaining, TITLE_SCAN_MAX_FRAME_BYTES, length * 2);
+    }
+    return undefined;
+}
+/** A reverse page ending on a known frame boundary. */
+async function reversePage(handle, end, signal) {
+    let length = Math.min(TITLE_SCAN_PAGE_BYTES, end);
+    while (length > 0) {
+        const start = end - length;
+        const buffer = await readRange(handle, start, length, signal);
+        if (buffer === undefined)
+            return undefined;
+        const frames = start === 0 ? walkFrames(buffer) : resyncFrames(buffer);
+        const last = frames[frames.length - 1];
+        if (last !== undefined && last.end === buffer.length)
+            return { start, buffer, frames };
+        if (length >= end || length >= TITLE_SCAN_MAX_FRAME_BYTES)
+            return undefined;
+        length = Math.min(end, TITLE_SCAN_MAX_FRAME_BYTES, length * 2);
+    }
+    return undefined;
+}
+/** Scan newest-to-oldest; the first title encountered is last-write-wins. */
+async function recoverLatestTitle(path, bytes, signal) {
+    signal?.throwIfAborted();
+    let handle;
+    try {
+        handle = await open(path, 'r');
+    }
+    catch {
+        signal?.throwIfAborted();
+        return { title: undefined, complete: false };
+    }
+    try {
+        let end = bytes;
+        while (end > 0) {
+            signal?.throwIfAborted();
+            const page = await reversePage(handle, end, signal);
+            if (page === undefined)
+                return { title: undefined, complete: false };
+            for (let frameIndex = page.frames.length - 1; frameIndex >= 0; frameIndex--) {
+                const frame = page.frames[frameIndex];
+                const lines = decodeFrame(page.buffer, frame);
+                if (lines === undefined)
+                    return { title: undefined, complete: false };
+                for (let lineIndex = lines.length - 1; lineIndex >= 0; lineIndex--) {
+                    const title = titleOf(lines[lineIndex]);
+                    if (title !== undefined)
+                        return { title, complete: true };
+                }
+            }
+            const nextEnd = page.start + page.frames[0].start;
+            if (nextEnd >= end)
+                return { title: undefined, complete: false };
+            end = nextEnd;
+            await scheduler.yield();
+        }
+        return { title: undefined, complete: true };
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+/** Scan all newly appended frames from the previous EOF frame boundary. */
+export async function digestAppendedSuffix(path, start, end, signal) {
+    signal?.throwIfAborted();
+    let handle;
+    try {
+        handle = await open(path, 'r');
+    }
+    catch {
+        signal?.throwIfAborted();
+        return { title: undefined, model: undefined, label: undefined, hasHumanPrompt: false, complete: false };
+    }
+    let title;
+    let model;
+    let label;
+    let hasHumanPrompt = false;
+    const result = (complete) => ({ title, model, label, hasHumanPrompt, complete });
+    try {
+        let position = start;
+        while (position < end) {
+            signal?.throwIfAborted();
+            const page = await forwardPage(handle, position, end, signal);
+            if (page === undefined)
+                return result(false);
+            for (const frame of page.frames) {
+                const lines = decodeFrame(page.buffer, frame);
+                if (lines === undefined)
+                    return result(false);
+                for (const line of lines) {
+                    title = titleOf(line) ?? title;
+                    model = modelOf(line) ?? model;
+                    label = labelOf(line) ?? label;
+                    hasHumanPrompt ||= humanPrompt(line) !== undefined;
+                }
+            }
+            const consumed = page.frames[page.frames.length - 1].end;
+            if (consumed <= 0)
+                return result(false);
+            position += consumed;
+            await scheduler.yield();
+        }
+        return result(true);
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+/** Find the first human prompt after a complete reverse scan proved no title. */
+async function recoverFirstPrompt(path, bytes, signal) {
+    signal?.throwIfAborted();
+    let handle;
+    try {
+        handle = await open(path, 'r');
+    }
+    catch {
+        signal?.throwIfAborted();
+        return { prompt: undefined, complete: false };
+    }
+    try {
+        let position = 0;
+        let hasPrompt = false;
+        while (position < bytes) {
+            signal?.throwIfAborted();
+            const page = await forwardPage(handle, position, bytes, signal);
+            if (page === undefined)
+                return { prompt: undefined, complete: false };
+            for (const frame of page.frames) {
+                const lines = decodeFrame(page.buffer, frame);
+                if (lines === undefined)
+                    return { prompt: undefined, complete: false };
+                if (position === 0 && frame.start === 0 && lines[0]?.['type'] !== 'session') {
+                    return { prompt: undefined, complete: false };
+                }
+                for (const line of lines) {
+                    const prompt = humanPrompt(line);
+                    hasPrompt ||= prompt !== undefined;
+                    if (prompt?.text !== undefined)
+                        return { prompt: prompt.text, complete: true, hasPrompt: true };
+                }
+            }
+            const consumed = page.frames[page.frames.length - 1].end;
+            if (consumed <= 0)
+                return { prompt: undefined, complete: false };
+            position += consumed;
+            await scheduler.yield();
+        }
+        return { prompt: undefined, complete: bytes > 0, ...(bytes > 0 ? { hasPrompt } : {}) };
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+/**
+ * Recover the authoritative display title for one immutable file snapshot:
+ * reverse scan for the LAST title, then (only when none exists) forward scan
+ * for the FIRST human prompt. Both directions page on verified frame boundaries.
+ */
+export async function recoverSessionTitle(path, bytes, signal) {
+    const latest = await recoverLatestTitle(path, bytes, signal);
+    if (latest.title !== undefined || !latest.complete)
+        return latest;
+    const opening = await recoverFirstPrompt(path, bytes, signal);
+    return {
+        title: opening.prompt === undefined ? undefined : { text: opening.prompt, source: 'prompt' },
+        complete: opening.complete,
+        ...(opening.hasPrompt === undefined ? {} : { hasPrompt: opening.hasPrompt }),
+    };
+}
+/** Hash the previous EOF neighborhood; this detects replacement near the old tail. */
+export async function sessionTitleAnchor(path, bytes, signal) {
+    signal?.throwIfAborted();
+    let handle;
+    try {
+        handle = await open(path, 'r');
+    }
+    catch {
+        signal?.throwIfAborted();
+        return undefined;
+    }
+    try {
+        const length = Math.min(TITLE_ANCHOR_BYTES, bytes);
+        const buffer = length === 0 ? Buffer.alloc(0) : await readRange(handle, bytes - length, length, signal);
+        if (buffer === undefined)
+            return undefined;
+        return createHash('sha256').update(buffer).digest('hex');
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+/**
+ * The last exchanges of a session, for the browser's preview pane.
+ *
+ * Bounded like everything else here: the preview shows the end of the
+ * conversation because that is what the tail window holds, and because the end
+ * is what tells you whether this is the session you meant.
+ *
+ * @param path - Absolute artifact path.
+ * @param limit - How many entries to keep, newest last.
+ * @returns Entries in log order.
+ */
+export function previewSession(path, limit) {
+    const window = readWindow(path, TAIL_WINDOW_BYTES, true);
+    if (window === undefined)
+        return [];
+    const lines = decodeTail(window);
+    const entries = [];
+    for (const line of lines) {
+        const data = line['data'];
+        if (data === null || typeof data !== 'object')
+            continue;
+        const record = data;
+        if (line['type'] === 'user/message') {
+            if (!isHumanSource(record['source']))
+                continue;
+            const text = textOfContent(record['content']);
+            if (text !== undefined)
+                entries.push({ role: 'user', text: text.slice(0, PREVIEW_CHARS), at: timeOf(line) });
+            continue;
+        }
+        if (line['type'] === 'assistant/message') {
+            const message = record['message'];
+            if (message === null || typeof message !== 'object')
+                continue;
+            const text = textOfContent(message['content']);
+            if (text !== undefined) {
+                entries.push({ role: 'assistant', text: text.slice(0, PREVIEW_CHARS), at: timeOf(line) });
+            }
+        }
+    }
+    return entries.slice(-limit);
+}

package/lib/types/dsh-adapter/sessions/frames.d.ts

@@ -0,0 +1,103 @@
+/** Byte range of one structurally complete frame; `end` is exclusive. */
+export interface FrameRange {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Locate the end of the frame starting at `start`, without decompressing it.
+ *
+ * The walk reads the Frame_Header (descriptor, optional window/dictionary/
+ * content-size fields) and then each Block_Header in turn — a 3-byte
+ * little-endian word carrying `last_block` (1 bit), `block_type` (2 bits) and
+ * `block_size` (21 bits) — until the block marked last. A `Reserved` block
+ * type means these bytes are not a frame at all, which is how a coincidental
+ * magic gets rejected.
+ *
+ * @param buffer - Bytes available to the reader (may end mid-frame).
+ * @param start - Offset of the candidate frame's magic.
+ * @returns The frame's exclusive end offset, or -1 when the bytes at `start`
+ *   are not a structurally complete frame within `buffer`.
+ */
+export declare function frameEnd(buffer: Buffer, start: number): number;
+/**
+ * Walk complete frames forward from `from`.
+ *
+ * @param buffer - Bytes to walk.
+ * @param from - Offset to start at (must be a frame boundary).
+ * @param maxFrames - Stop after this many frames; the reader's cost ceiling.
+ * @returns Complete frames in file order. A window that ends mid-frame simply
+ *   yields one fewer frame — the partial tail is never reported as complete.
+ */
+export declare function walkFrames(buffer: Buffer, from?: number, maxFrames?: number): FrameRange[];
+/**
+ * Re-synchronize on a frame boundary inside a window that starts mid-frame.
+ *
+ * A tail window has no boundary to start from, so the only anchor is the one
+ * structural fact we know about the whole file: its last frame ends exactly at
+ * EOF. Every magic candidate is tried in file order, and the first one whose
+ * frame chain lands precisely on the window's end is the true boundary — a
+ * coincidental magic would have to spell a valid block chain of exactly the
+ * right total length to be mistaken for one.
+ *
+ * @param buffer - A window whose last byte is the file's last byte.
+ * @returns Frames from the earliest recoverable boundary, or [] when the
+ *   window holds no complete frame.
+ */
+export declare function resyncFrames(buffer: Buffer): FrameRange[];
+/** One decoded log line, still untyped — the caller owns interpretation. */
+export type LogLine = Record<string, unknown>;
+/**
+ * Decode frames to JSON log lines, tolerantly.
+ *
+ * A frame that fails to decompress or a line that fails to parse is skipped
+ * rather than thrown: a log being appended to right now can hold a frame
+ * flushed without its final checksum, and a torn tail is the backend's own
+ * documented recovery case. A picker label is read-only UI state — degrading
+ * to a fallback title beats refusing to list the session.
+ *
+ * @param buffer - Bytes the frames index into.
+ * @param frames - Complete frame ranges within `buffer`.
+ * @returns Parsed envelopes in log order.
+ */
+export declare function decodeFrame(buffer: Buffer, frame: FrameRange): LogLine[] | undefined;
+export declare function decodeFrames(buffer: Buffer, frames: readonly FrameRange[]): LogLine[];
+/** A file's size and last-write time, read once for both. */
+export interface FileFacts {
+    readonly bytes: number;
+    readonly modifiedAt: number;
+    /** Physical file identity; replacement must not inherit append-only evidence. */
+    readonly identity: string;
+}
+/**
+ * Size and mtime of a log, or undefined when it is gone.
+ * @param path - Absolute artifact path.
+ */
+export declare function fileFacts(path: string): FileFacts | undefined;
+/**
+ * Read a window from one end of a file without loading the whole thing.
+ *
+ * @param path - Absolute artifact path.
+ * @param bytes - Window budget; the whole file is read when it is smaller.
+ * @param end - Read the last `bytes` instead of the first.
+ * @returns The window, plus whether it covers the entire file (which tells a
+ *   head reader that its last frame cannot be truncated).
+ */
+export declare function readWindow(path: string, bytes: number, end?: boolean): {
+    buffer: Buffer;
+    whole: boolean;
+} | undefined;
+/**
+ * Decode a window read from the END of a file.
+ *
+ * A tail window has no frame boundary to start from unless it happens to
+ * cover the whole file, so it re-synchronizes; a whole-file window is simply
+ * walked.
+ *
+ * @param window - A window whose last byte is the file's last byte.
+ * @returns Log lines from the trailing frames, oldest first.
+ */
+export declare function decodeTail(window: {
+    buffer: Buffer;
+    whole: boolean;
+}): LogLine[];
+//# sourceMappingURL=frames.d.ts.map

package/lib/types/dsh-adapter/sessions/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/sessions/frames.ts"],"names":[],"mappings":"AAyCA,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAsC9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,SAAI,EACR,SAAS,SAA2B,GACnC,UAAU,EAAE,CAUd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAQzD;AAED,4EAA4E;AAC5E,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,EAAE,GAAG,SAAS,CAsBpF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,EAAE,CAOrF;AAED,6DAA6D;AAC7D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAW7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,UAAQ,GACV;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAwBhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,EAAE,CAKhF"}