@nelsonlongxiang/dsh-open-a2a-net 0.5.14 → 0.6.24

package/lib/joined-store.js

@@ -67,6 +67,17 @@ export class JoinedSessions {
         this.ids = this.ids.filter(entry => entry !== id);
         this.persist();
     }
+    /**
+     * F7 (wake-intent self-heal): re-read the persisted snapshot into memory.
+     * A boot-time transient (e.g. the workspace registry briefly reporting a
+     * session archived) can prune the in-memory intent while the file still
+     * holds it — the file is the durable source of the user's gesture, so the
+     * reload restores memory to match it. Callers use this as a one-shot
+     * fallback when a wake finds no in-memory match.
+     */
+    reload() {
+        this.restore();
+    }
     /** Load a persisted snapshot on construction, if present. */
     restore() {
         if (this.path === '' || !existsSync(this.path))

package/lib/layout-store.js

@@ -0,0 +1,155 @@
+/**
+ * Persisted spatial layout for the infinite-canvas page ('a2a/canvas-layout.json').
+ * Pure presentation state: node coordinates, team-frame rectangles, and the
+ * viewport transform. Membership truth stays in canvas.json - this store may
+ * be reset freely without touching who sits in which team.
+ *
+ * Unit semantics (contract note 6, 2026-08-28 ruling): {x,y} are 2D
+ * planning-canvas card centers in pixels. Other consumers (the 3D
+ * observation lens) must reproject into their own envelope, never consume
+ * the values as absolute scene coordinates.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/layout-store
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** World-coordinate magnitude bound: values beyond are clamped, never trusted. */
+export const COORD_LIMIT = 1_000_000;
+/** Zoom bounds, matching the page's wheel clamps. */
+export const SCALE_MIN = 0.25;
+export const SCALE_MAX = 3;
+/** Document shape caps: a layout taxonomy, not a database. */
+export const LAYOUT_NODE_CAP = 256;
+export const LAYOUT_FRAME_CAP = 96;
+function clampCoord(v) {
+    const n = typeof v === 'number' ? v : Number.NaN;
+    if (!Number.isFinite(n))
+        return undefined;
+    return Math.max(-COORD_LIMIT, Math.min(COORD_LIMIT, Math.round(n)));
+}
+function clampPoint(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const rec = raw;
+    const x = clampCoord(rec.x);
+    const y = clampCoord(rec.y);
+    return x === undefined || y === undefined ? undefined : { x, y };
+}
+function clampRect(raw) {
+    const point = clampPoint(raw);
+    if (point === undefined)
+        return undefined;
+    const rec = raw;
+    const w = clampCoord(rec.w);
+    const h = clampCoord(rec.h);
+    if (w === undefined || h === undefined || w <= 0 || h <= 0)
+        return undefined;
+    return { ...point, w: Math.min(w, COORD_LIMIT), h: Math.min(h, COORD_LIMIT) };
+}
+function clampDoc(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const rec = raw;
+    if (rec.version !== 1)
+        return undefined;
+    // The viewport is a point+scale, not a rect - validate its own shape.
+    const vpRaw = rec.viewport;
+    if (vpRaw === null || typeof vpRaw !== 'object')
+        return undefined;
+    const vp = vpRaw;
+    const vx = clampCoord(vp.x);
+    const vy = clampCoord(vp.y);
+    const vsRaw = vp.scale;
+    const vsNum = typeof vsRaw === 'number' ? vsRaw : Number.NaN;
+    if (vx === undefined || vy === undefined || !Number.isFinite(vsNum))
+        return undefined;
+    const viewport = { x: vx, y: vy };
+    const scale = Math.max(SCALE_MIN, Math.min(SCALE_MAX, vsNum));
+    const nodes = {};
+    if (rec.nodes !== null && typeof rec.nodes === 'object') {
+        for (const [id, point] of Object.entries(rec.nodes)) {
+            if (typeof id !== 'string' || id === '' || id.length > 128)
+                continue;
+            const p = clampPoint(point);
+            if (p !== undefined)
+                nodes[id] = p;
+            if (Object.keys(nodes).length >= LAYOUT_NODE_CAP)
+                break;
+        }
+    }
+    const frames = {};
+    if (rec.frames !== null && typeof rec.frames === 'object') {
+        for (const [name, rect] of Object.entries(rec.frames)) {
+            // Frame keys mirror canvas team names: same discipline (no '/', cap 40).
+            if (typeof name !== 'string' || name === '' || name.includes('/') || name.length > 40)
+                continue;
+            const r = clampRect(rect);
+            if (r !== undefined)
+                frames[name] = r;
+            if (Object.keys(frames).length >= LAYOUT_FRAME_CAP)
+                break;
+        }
+    }
+    return { version: 1, viewport: { x: viewport.x, y: viewport.y, scale }, nodes, frames };
+}
+/**
+ * Whole-document layout store with last-write-wins persistence. Accepts
+ * anything the client sends and answers with the normalized truth: clients
+ * round-trip GET after save when they need canonical numbers.
+ */
+export class LayoutStore {
+    doc;
+    path;
+    /** @param path - the snapshot file; an empty path keeps memory-only. */
+    constructor(path) {
+        this.path = path;
+        this.restore();
+    }
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            this.doc = clampDoc(JSON.parse(readFileSync(this.path, 'utf8')));
+        }
+        catch {
+            this.doc = undefined; // corrupt layout is presentation loss only
+        }
+    }
+    persist() {
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            writeFileSync(this.path, JSON.stringify(this.doc), { mode: 0o600 });
+        }
+        catch {
+            // An unwritable home degrades to memory-only presentation state.
+        }
+    }
+    /** The current snapshot, or null before the first save. */
+    get() {
+        return this.doc ?? null;
+    }
+    /**
+     * Replace the document wholesale after normalization.
+     * @returns false when the payload is not a version-1 layout document.
+     */
+    save(raw) {
+        const doc = clampDoc(raw);
+        if (doc === undefined)
+            return false;
+        this.doc = doc;
+        this.persist();
+        return true;
+    }
+    /** Drop all persisted presentation state. */
+    reset() {
+        this.doc = undefined;
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            writeFileSync(this.path, '', { mode: 0o600 });
+        }
+        catch { /* degrade to memory-only */ }
+    }
+}

package/lib/peer-store.js

@@ -8,7 +8,8 @@
  * .agents/notes/proposed/feature/2026-08-16-gnunet-prior-art-for-a2a-topology.md.
  * @module @nelsonlongxiang/dsh-open-a2a-net/peer-store
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 /** Hard cap on tracked peers, seeds included (hostlist bound: 30). */
 export const PEER_CAP = 30;
@@ -29,15 +30,17 @@ export const EVICTION_FLOOR = 0;
 export class PeerStore {
     path;
     cap;
+    persistDebounceMs;
     peers = new Map();
     /**
      * @param seeds - the configured seed URLs; always retained (never evicted).
      * @param path - persistence file (`<dsh-home>/a2a/peers.json`); empty = no persistence.
      * @param cap - peer bound, seeds included (default {@link PEER_CAP}).
      */
-    constructor(seeds, path, cap = PEER_CAP) {
+    constructor(seeds, path, cap = PEER_CAP, persistDebounceMs = 1_000) {
         this.path = path;
         this.cap = cap;
+        this.persistDebounceMs = persistDebounceMs;
         this.restore();
         for (const seed of seeds) {
             if (seed === '')
@@ -59,6 +62,15 @@ export class PeerStore {
             .sort((a, b) => (a.seed === b.seed ? b.score - a.score : a.seed ? -1 : 1))
             .map(peer => peer.url);
     }
+    /**
+     * The operator-established subset (gh#8 N9): URLs that came from the
+     * config seed set — never the referral-learned tail. Team-name resolution
+     * rides this basis so a self-naming host nobody linked cannot capture
+     * routes; probing and visibility keep the full list.
+     */
+    listSeeded() {
+        return [...this.peers.values()].filter(peer => peer.seed).map(peer => peer.url);
+    }
     /** Whether the store has room for one more peer. */
     hasRoom() {
         return this.peers.size < this.cap;
@@ -127,6 +139,38 @@ export class PeerStore {
     score(url) {
         return this.peers.get(url)?.score;
     }
+    /**
+     * Record the signed-card session a tracked peer served. The session is the
+     * node identity (the same fact the self-referral guard judges), so learning
+     * it per URL is what lets the caller collapse alias spellings of one node
+     * (loopback vs LAN IP) into a single tracked peer.
+     * @param url - the tracked peer the card came from.
+     * @param session - the verified card's session label; empty is ignored.
+     */
+    learnSession(url, session) {
+        const peer = this.peers.get(url);
+        if (peer === undefined || session === '')
+            return;
+        // PeerRecord fields are readonly: replace the record wholesale.
+        this.peers.set(url, { ...peer, session });
+        this.persist();
+    }
+    /**
+     * The strongest tracked URL known to serve one node identity — seeds beat
+     * referrals, then the higher score wins (ties keep first-tracked order).
+     * @param session - the signed-card session to look up.
+     * @returns the winning peer URL, or undefined when none is tracked.
+     */
+    bySession(session) {
+        let best;
+        for (const peer of this.peers.values()) {
+            if (peer.session !== session)
+                continue;
+            if (best === undefined || (best.seed === peer.seed ? peer.score > best.score : peer.seed))
+                best = peer;
+        }
+        return best?.url;
+    }
     /** Load a persisted snapshot on construction, if present. */
     restore() {
         if (this.path === '' || !existsSync(this.path))
@@ -144,6 +188,7 @@ export class PeerStore {
                     url: peer.url,
                     score: typeof peer.score === 'number' && Number.isFinite(peer.score) ? peer.score : INITIAL_SCORE,
                     seed: peer.seed === true,
+                    ...(typeof peer.session === 'string' && peer.session !== '' ? { session: peer.session } : {}),
                 });
             }
         }
@@ -151,19 +196,59 @@ export class PeerStore {
             // A corrupt store is not fatal: fall back to seeds only.
         }
     }
-    /** Persist the current peer set (no-op when no path was configured). */
+    /**
+     * Persist the current peer set (no-op when no path was configured).
+     * Writes are debounced and asynchronous: a sweep that settles dozens of
+     * fetch outcomes must not fire one synchronous writeFileSync per change
+     * (each blocks the event loop for milliseconds on Windows). The dirty
+     * flag coalesces the whole window into one async write; `flush()` lets
+     * tests and teardown await the final state on disk. A crash inside the
+     * window loses at most `persistDebounceMs` of score deltas — seeds are
+     * re-seeded from config on every boot, and scores rebuild on contact.
+     */
+    dirty = false;
+    writeChain = Promise.resolve();
+    pendingTimer;
     persist() {
         if (this.path === '')
             return;
-        try {
-            mkdirSync(dirname(this.path), { recursive: true });
-            const snapshot = {
-                peers: [...this.peers.values()].map(peer => ({ ...peer })),
-            };
-            writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
-        }
-        catch {
-            // An unwritable home must not break routing; the store degrades to memory-only.
-        }
+        this.dirty = true;
+        // Classic trailing debounce: one shared timer, reset on every change, so
+        // a steady drip of outcomes still lands as one write after the last
+        // change — not one write per elapsed window. Unref'd so a timer armed at
+        // teardown never keeps the process alive for it.
+        if (this.pendingTimer !== undefined)
+            clearTimeout(this.pendingTimer);
+        const timer = setTimeout(() => {
+            this.pendingTimer = undefined;
+            if (!this.dirty)
+                return;
+            this.dirty = false;
+            this.writeChain = this.writeChain.then(async () => {
+                if (this.path === '')
+                    return;
+                try {
+                    await mkdir(dirname(this.path), { recursive: true });
+                    const snapshot = {
+                        peers: [...this.peers.values()].map(peer => ({ ...peer })),
+                    };
+                    await writeFile(this.path, JSON.stringify(snapshot), { mode: 0o600 });
+                }
+                catch {
+                    // An unwritable home must not break routing; the store degrades to memory-only.
+                }
+            });
+        }, this.persistDebounceMs);
+        timer.unref?.();
+        this.pendingTimer = timer;
+    }
+    /**
+     * Await the last scheduled write (tests and teardown). Resolves when the
+     * debounced write chain has settled with the current in-memory state.
+     */
+    async flush() {
+        if (this.dirty)
+            await new Promise(resolve => setTimeout(resolve, this.persistDebounceMs + 5));
+        await this.writeChain;
     }
 }

package/lib/receipt-ladder.js

@@ -0,0 +1,35 @@
+/**
+ * Receipt delivery three-tier hard order (work-order P2 / B1 residual):
+ * caller lane first; if it fails, escalate ONCE to the owner mailbox so the
+ * outcome still lands somewhere answerable on this host; total failure stays
+ * a breadcrumb (correlation & archive remain the authoritative truth).
+ *
+ * Extracted pure so the ladder is unit-drivable without live agents.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/receipt-ladder
+ */
+/**
+ * Attempt delivery through the ladder.
+ * @param callerTeam - tier-one target (`callbackTarget`). When it already IS
+ * the owner team, a failure terminates after tier one — escalating to
+ * yourself would just double the noise.
+ */
+export async function runReceiptLadder(deps, callerTeam) {
+    try {
+        await deps.deliver(callerTeam);
+        return;
+    }
+    catch (error) {
+        deps.log(`to ${callerTeam}`, error);
+        if (callerTeam === deps.ownerTeam)
+            throw error;
+    }
+    try {
+        await deps.deliver(deps.ownerTeam);
+        return;
+    }
+    catch (error) {
+        deps.log(`to owner ${deps.ownerTeam}`, error);
+        deps.log('both lanes', error);
+        throw error;
+    }
+}

package/lib/receipt.js

@@ -0,0 +1,102 @@
+/**
+ * Receipt text codec — single home for the correlation pattern and the v2
+ * structured envelope (receipt-envelope-v2.md). The header line
+ * `[A2A receipt] task <id> …` stays byte-identical to the network's original
+ * contract; the machine payload rides EXACTLY ONE following line that must be
+ * a complete JSON object containing at least one known key. Everything after
+ * it is human continuation and every consumer ignores unknown keys.
+ *
+ * Discriminator over a bare `{`: an object qualifies as an envelope only when
+ * one of the known keys is present, so legacy prose summaries that happen to
+ * open with a brace can never be mistaken for machine payloads.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/receipt
+ */
+/** The network's fixed, case-sensitive correlation template. */
+export const RECEIPT_PATTERN = /^\[A2A receipt\] task (\S+)\s*([\s\S]*)$/;
+/** Controlled outcome vocabulary — the ONLY branchable field of an envelope. */
+export const RECEIPT_OUTCOMES = [
+    'completed',
+    'failed',
+    'abandoned',
+    'expired',
+    'rejected',
+    'sync_completed',
+    'unknown',
+];
+const KNOWN_ENVELOPE_KEYS = ['outcome', 'idempotencyKey', 'sessionKey', 'elapsedMs', 'artifacts'];
+void KNOWN_ENVELOPE_KEYS;
+function tryEnvelopeLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        const value = JSON.parse(trimmed);
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const record = value;
+        // Discriminator: a known key must EXTRACT at least one valid field —
+        // an object carrying only garbage values stays human prose (v1).
+        const fields = {};
+        if (typeof record['outcome'] === 'string' && RECEIPT_OUTCOMES.includes(record['outcome'])) {
+            fields.outcome = record['outcome'];
+        }
+        if (typeof record['idempotencyKey'] === 'string')
+            fields.idempotencyKey = record['idempotencyKey'];
+        if (typeof record['sessionKey'] === 'string')
+            fields.sessionKey = record['sessionKey'];
+        if (typeof record['elapsedMs'] === 'number' && Number.isFinite(record['elapsedMs']))
+            fields.elapsedMs = record['elapsedMs'];
+        if (Object.keys(fields).length === 0)
+            return undefined;
+        return fields;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parse one inbound message against the receipt contract.
+ * @returns `null` when the message is not a receipt at all; otherwise the
+ * correlation key with its summary and, when present, the v2 envelope.
+ */
+export function parseReceipt(message) {
+    const match = RECEIPT_PATTERN.exec(message);
+    if (match === null)
+        return null;
+    const taskId = match[1] ?? '';
+    const rest = match[2] ?? '';
+    const newlineAt = rest.indexOf('\n');
+    const firstRestLine = newlineAt === -1 ? '' : rest.slice(0, newlineAt);
+    const envelope = newlineAt !== -1
+        ? tryEnvelopeLine(rest.slice(newlineAt + 1).split('\n', 1)[0] ?? '')
+        : undefined;
+    // Without a machine line the legacy remainder flows through untouched so
+    // multi-line human summaries keep their exact historical shape.
+    const summary = envelope !== undefined ? firstRestLine : rest;
+    return { taskId, summary, ...(envelope !== undefined ? { envelope } : {}) };
+}
+/**
+ * Compose a receipt text: the immutable header (+ human summary) followed,
+ * when any envelope field is supplied, by exactly one complete JSON line.
+ * @param taskId - correlation key echoed in the header.
+ * @param summary - human-readable outcome tail on the header line.
+ * @param fields - structured projection; omit entirely for a pure v1 receipt.
+ */
+export function formatReceipt(taskId, summary, fields) {
+    const header = `[A2A receipt] task ${taskId}${summary !== '' ? ` ${summary}` : ''}`;
+    if (fields === undefined)
+        return header;
+    const ordered = {};
+    if (fields.outcome !== undefined)
+        ordered['outcome'] = fields.outcome;
+    if (fields.idempotencyKey !== undefined)
+        ordered['idempotencyKey'] = fields.idempotencyKey;
+    if (fields.sessionKey !== undefined)
+        ordered['sessionKey'] = fields.sessionKey;
+    if (fields.elapsedMs !== undefined)
+        ordered['elapsedMs'] = fields.elapsedMs;
+    const keys = Object.keys(ordered);
+    if (keys.length === 0)
+        return header;
+    return `${header}\n${JSON.stringify(ordered)}`;
+}

package/lib/self-suppress.js

@@ -0,0 +1,62 @@
+/**
+ * Unmasked-identity suppression: decentralized gossip mirrors peer lists back
+ * and forth, so every alias of this node's own address comes home as an
+ * inbound referral within minutes of being dropped. Fetching one is the
+ * identity check that drops it (the fetched card carries our session id),
+ * but the next inbound referral re-offers the same URL seconds later, and
+ * the peer store flickers between present and dropped forever.
+ *
+ * The same flicker plagues alias spellings of OTHER tracked nodes: a peer
+ * reached as both loopback and LAN IP drops one spelling on the alias
+ * collapse, and the next mirrored referral re-offers it. This filter
+ * therefore remembers each URL whose fetch revealed a settled identity —
+ * self or an already-tracked peer — for a window far beyond any realistic
+ * offer cadence: offers inside the window are refused without a network
+ * round-trip. Shape-agnostic on purpose — alias spellings never seen before
+ * (localhost vs 127.0.0.1 vs a hostname) suppress naturally once their first
+ * fetch unmasks them.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/self-suppress
+ */
+/** How long an identity-revealing URL stays suppressed after its unmasking fetch. */
+export const SELF_REFERRAL_SUPPRESS_MS = 6 * 60 * 60_000;
+/** Bounded memory of URLs whose recent fetch proved they serve a known identity. */
+export class SelfReferralFilter {
+    remembered = new Map();
+    now;
+    /** @param now - injectable clock for deterministic tests. */
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    /**
+     * Record that fetching `url` served this node's own card. Expired entries
+     * prune first, so the map stays bounded by the live offer cadence.
+     */
+    remember(url) {
+        if (url === '')
+            return;
+        this.prune(this.now());
+        this.remembered.set(url, this.now());
+    }
+    /**
+     * Whether one inbound referral is still worth offering to the store.
+     * A URL unmasked as self inside the suppression window refuses without a
+     * fetch; every other URL passes through unchanged.
+     */
+    shouldOffer(url) {
+        const at = this.remembered.get(url);
+        if (at === undefined)
+            return true;
+        if (this.now() - at > SELF_REFERRAL_SUPPRESS_MS) {
+            this.remembered.delete(url);
+            return true;
+        }
+        return false;
+    }
+    /** Drop entries past the window (called from the mutating entry points). */
+    prune(at) {
+        for (const [url, since] of this.remembered) {
+            if (at - since > SELF_REFERRAL_SUPPRESS_MS)
+                this.remembered.delete(url);
+        }
+    }
+}

package/lib/session-transcript.js

@@ -0,0 +1,150 @@
+/**
+ * Session transcript reader (0.6.11): lets the workbench inspector show the
+ * tail of a LOCAL session's own conversation log, inline, with no navigation
+ * (owner ruling 2026-10-20: no jumps, responsive only). Remote nodes' logs
+ * live on their machines — this module deliberately only reads this host's
+ * <dshHome>/sessions tree.
+ *
+ * Log layout (dsh session-persistence-jsonl): each session dir holds one
+ * append-only JSONL artifact per FORMAT GENERATION — session.jsonl.zstd,
+ * session.v2.jsonl.zstd, session.v3.jsonl.zstd… (generation, not rotation:
+ * a migration writes the next file and new events append there). The zstd
+ * artifacts are CONCATENATED independent frames — the writer appends one
+ * self-contained checksummed frame per durable batch, and node:zlib's public
+ * decoder stops after the first frame, so a reader must split frames
+ * structurally and decode each with zstdDecompressSync.
+ *
+ * Event records (JSONL lines) this extractor cares about:
+ *   {"type":"user/message","seq","time","data":{"content":[{"type":"text","text"}]}}
+ *   {"type":"assistant/message","seq","time","data":{"message":{"role":"assistant","content":[{"type":"text"|"reasoning"|"tool-call",…}]}}}
+ * reasoning and tool-call segments are skipped; only human-visible text is a
+ * transcript entry.
+ */
+import { zstdDecompressSync } from 'node:zlib';
+/** Hard caps so a pathological log cannot balloon memory or the response. */
+export const TRANSCRIPT_MAX_FILE_BYTES = 64 * 1024 * 1024;
+export const TRANSCRIPT_MAX_DECOMPRESSED_BYTES = 160 * 1024 * 1024;
+export const TRANSCRIPT_ENTRY_TEXT_CAP = 500;
+export const TRANSCRIPT_DEFAULT_LIMIT = 20;
+export const TRANSCRIPT_MAX_LIMIT = 100;
+const ZSTD_MAGIC = 0xfd2fb528;
+/**
+ * Walk concatenated zstd frames structurally (no block decoding) and return
+ * their byte ranges. Malformed structure rejects; EOF inside a final frame is
+ * dropped from the result (a torn tail frame decodes to nothing usable).
+ */
+export function scanZstdFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while (offset + 4 <= buffer.length) {
+        if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC)
+            break;
+        const start = offset;
+        offset += 4;
+        if (offset >= buffer.length)
+            break;
+        const descriptor = buffer.readUInt8(offset);
+        offset += 1;
+        const contentSizeFlag = descriptor >>> 6;
+        const singleSegment = (descriptor & 0x20) !== 0;
+        const checksum = (descriptor & 0x04) !== 0;
+        const dictionaryFlag = descriptor & 0x03;
+        const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+        const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+        offset += (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+        let complete = false;
+        while (offset + 3 <= buffer.length) {
+            const blockHeader = buffer.readUIntLE(offset, 3);
+            offset += 3;
+            const lastBlock = (blockHeader & 1) !== 0;
+            const blockType = (blockHeader >>> 1) & 0x03;
+            const blockSize = blockHeader >>> 3;
+            if (blockType === 0x03)
+                return frames; // reserved block type: stop before it
+            const payloadBytes = blockType === 0x01 ? 1 : blockSize;
+            if (offset + payloadBytes > buffer.length)
+                break;
+            offset += payloadBytes;
+            if (lastBlock) {
+                complete = true;
+                break;
+            }
+        }
+        if (!complete)
+            break;
+        if (checksum)
+            offset += 4;
+        if (offset > buffer.length)
+            break;
+        frames.push({ start, end: offset });
+    }
+    return frames;
+}
+/**
+ * Decode a session log artifact to text. Plain .jsonl passes through; .zstd
+ * artifacts are split into frames and decoded frame by frame (node's public
+ * decoder is single-frame).
+ */
+export function decodeSessionLog(buffer) {
+    const frames = scanZstdFrames(buffer);
+    if (frames.length === 0)
+        return buffer.toString('utf8');
+    const parts = [];
+    let total = 0;
+    for (const frame of frames) {
+        const chunk = zstdDecompressSync(buffer.subarray(frame.start, frame.end));
+        total += chunk.length;
+        if (total > TRANSCRIPT_MAX_DECOMPRESSED_BYTES) {
+            throw new Error('session log exceeds the decompressed-size cap');
+        }
+        parts.push(chunk.toString('utf8'));
+    }
+    return parts.join('');
+}
+function clampEntry(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > TRANSCRIPT_ENTRY_TEXT_CAP ? flat.slice(0, TRANSCRIPT_ENTRY_TEXT_CAP) + '…' : flat;
+}
+/**
+ * Extract the last `limit` human-visible turns from a decoded session log.
+ * User lines come from user/message data.content[].text; assistant lines from
+ * assistant/message data.message.content[] segments of type "text" (reasoning
+ * and tool calls are working detail, not transcript).
+ */
+export function extractTranscript(logText, limit = TRANSCRIPT_DEFAULT_LIMIT) {
+    const entries = [];
+    for (const line of logText.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof record !== 'object' || record === null)
+            continue;
+        const event = record;
+        const time = typeof event.time === 'number' ? event.time : undefined;
+        if (event.type === 'user/message') {
+            const data = event.data;
+            const text = (data?.content ?? [])
+                .filter(seg => seg?.type === 'text' && typeof seg.text === 'string')
+                .map(seg => seg.text)
+                .join(' ');
+            if (text.trim() !== '')
+                entries.push({ role: 'user', text: clampEntry(text), time });
+        }
+        else if (event.type === 'assistant/message') {
+            const data = event.data;
+            const text = (data?.message?.content ?? [])
+                .filter(seg => seg?.type === 'text' && typeof seg.text === 'string')
+                .map(seg => seg.text)
+                .join(' ');
+            if (text.trim() !== '')
+                entries.push({ role: 'assistant', text: clampEntry(text), time });
+        }
+    }
+    return entries.slice(-limit);
+}