@volter/supercode-interchange 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-interchange",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "description": "Read-only harness metadata, transcript codecs and session projections for Supercode",
   "license": "MIT OR Apache-2.0",

package/session-claude-index.mjs

@@ -1,8 +1,11 @@
+import { createHash } from 'node:crypto';
+import { basename, dirname, extname, join } from 'node:path';
 import { withSessionFile } from './file-io.mjs';
 import { sessionFileLines, decodeSessionUtf8 } from './session-file.mjs';
 import { parseNativeJson, cloneNativeJson } from './native-json.mjs';
-import { createSession } from './session-model.mjs';
-import { messageHasContent } from './session-views.mjs';
+import { createSession, normalizedSessionJson } from './session-model.mjs';
+import { messageJson } from './message.mjs';
+import { messageHasContent, recordedProfileFold, recordedSessionProfile } from './session-views.mjs';
 import { nativeTrim } from './text.mjs';
 import { field, stringField, ensureToolResultsPaired } from './session-codec-utils.mjs';
 import { captureNativeResidue, claudeResidueKind } from './session-native-residue.mjs';
@@ -10,11 +13,64 @@ import { captureClaudeMeta } from './session-claude.mjs';
 import { ClaudeReplayIndex } from './session-claude-graph.mjs';
 import { captureClaudeProvenance, pushClaudeUser, pushClaudeAttachment, pushClaudeSystem, mergeClaudeAssistantChunk, flushClaudeAssistant, reorderClaudeToolResults } from './session-claude-content.mjs';
 import { sourceStat } from './store-registry.mjs';
-import { looksLikeSessionSqlite } from './session-path.mjs';
+import { isCompressedSessionPath, looksLikeSessionSqlite, sessionTextError } from './session-path.mjs';
 import { detectSessionSource } from './session-source.mjs';
 
 const REFERENCE = 'supercode.internal.read_index';
 
+/** What one record is to the replay, with where it stands in the file. */
+function recordFacts(line, value) {
+  return { offset: line.offset, length: line.length, assistant: stringField(value, 'type') === 'assistant',
+    error: field(value, 'isApiErrorMessage') === true, messageId: stringField(field(value, 'message'), 'id') };
+}
+
+/** The selected records as the groups that each make messages: the chunks of one assistant message together, any
+ * other record alone. An assistant record that is an API error makes none. */
+function* claudeGroups(lines, recordOf) {
+  let pending = [], pendingId = null;
+  for (const index of lines) {
+    const record = recordOf(index);
+    if (record.assistant && !record.error) {
+      if (pending.length && !(pendingId != null && pendingId === record.messageId)) { yield pending; pending = []; }
+      pendingId = record.messageId; pending.push(index);
+    } else {
+      if (pending.length) yield pending;
+      pending = []; pendingId = null;
+      if (!record.error || !record.assistant) yield [index];
+    }
+  }
+  if (pending.length) yield pending;
+}
+
+/** The messages one group's records make, each record read from where it stands (`raw`). */
+async function decodeClaudeGroup(raw, group) {
+  const messages = []; let pending = null;
+  for (const index of group) {
+    const value = parseNativeJson(await raw(index)), kind = stringField(value, 'type');
+    if (kind === 'assistant') {
+      if (pending == null) pending = value; else mergeClaudeAssistantChunk(pending, value);
+    } else {
+      const before = messages.length;
+      if (kind === 'user') pushClaudeUser(value, messages);
+      else if (kind === 'attachment') pushClaudeAttachment(value, messages);
+      else if (kind === 'system') pushClaudeSystem(value, messages);
+      captureClaudeProvenance(value, messages, before);
+    }
+  }
+  flushClaudeAssistant(pending, messages);
+  return messages;
+}
+
+/** A decoded message with what it says left out: what the passes over the whole transcript read (a tool result
+ * beside its call, a call with no result), and nothing of its size. */
+function skeletonMessage(message) {
+  if (message.content != null) message.content = nativeTrim(message.content) === '' ? '' : 'x';
+  if (message.content_parts != null) message.content_parts = message.content_parts.length ? [null] : [];
+  for (const call of message.tool_calls ?? []) call.function.arguments = '';
+  message.metadata = Object.create(null);
+  return message;
+}
+
 export async function supportsClaudeReadIndex(path, { metrics } = {}) {
   if (!(await sourceStat(path))?.isFile() || await looksLikeSessionSqlite(path, metrics)) return false;
   return (await withSessionFile(path, async (reader) => {
@@ -43,16 +99,14 @@ class ClaudeReadIndex {
     const graph = new ClaudeReplayIndex(), residueRecords = [];
     for await (const line of sessionFileLines(this.#reader)) {
       const index = this.#records.length;
-      const record = { offset: line.offset, length: line.length, assistant: false, error: false, messageId: null };
+      let record = { offset: line.offset, length: line.length, assistant: false, error: false, messageId: null };
       if (nativeTrim(line.text) !== '') {
         let value;
         try { value = parseNativeJson(line.text); } catch { this.#parseErrors++; }
         if (value !== undefined) {
           captureClaudeMeta(value, this.#meta, line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text);
           graph.observe(index, value);
-          record.assistant = stringField(value, 'type') === 'assistant';
-          record.error = field(value, 'isApiErrorMessage') === true;
-          record.messageId = stringField(field(value, 'message'), 'id');
+          record = recordFacts(line, value);
           if (claudeResidueKind(value) != null) residueRecords.push(index);
         }
       }
@@ -64,18 +118,7 @@ class ClaudeReadIndex {
       const value = parseNativeJson(raw);
       captureNativeResidue(this.#meta, 'claude_code', index, raw, value, claudeResidueKind(value));
     }
-    let pending = [], pendingId = null;
-    for (const index of selection.lines) {
-      const record = this.#records[index];
-      if (record.assistant && !record.error) {
-        if (pending.length && !(pendingId != null && pendingId === record.messageId)) { await this.#addGroup(pending); pending = []; }
-        pendingId = record.messageId; pending.push(index);
-      } else {
-        await this.#addGroup(pending); pending = []; pendingId = null;
-        if (!record.error || !record.assistant) await this.#addGroup([index]);
-      }
-    }
-    await this.#addGroup(pending);
+    for (const group of claudeGroups(selection.lines, (index) => this.#records[index])) await this.#addGroup(group);
     reorderClaudeToolResults(this.#skeleton); ensureToolResultsPaired(this.#skeleton);
   }
 
@@ -84,33 +127,13 @@ class ClaudeReadIndex {
     return decodeSessionUtf8(await this.#reader.read(record.offset, record.length));
   }
 
-  async #decodeGroup(group) {
-    const messages = []; let pending = null;
-    for (const index of group) {
-      const value = parseNativeJson(await this.#raw(index)), kind = stringField(value, 'type');
-      if (kind === 'assistant') {
-        if (pending == null) pending = value; else mergeClaudeAssistantChunk(pending, value);
-      } else {
-        const before = messages.length;
-        if (kind === 'user') pushClaudeUser(value, messages);
-        else if (kind === 'attachment') pushClaudeAttachment(value, messages);
-        else if (kind === 'system') pushClaudeSystem(value, messages);
-        captureClaudeProvenance(value, messages, before);
-      }
-    }
-    flushClaudeAssistant(pending, messages);
-    return messages;
-  }
+  #decodeGroup(group) { return decodeClaudeGroup((index) => this.#raw(index), group); }
 
   async #addGroup(group) {
-    if (!group.length) return;
     const groupId = this.#groups.length, decoded = await this.#decodeGroup(group);
     this.#groups.push(group);
     decoded.forEach((message, ordinal) => {
-      if (message.content != null) message.content = nativeTrim(message.content) === '' ? '' : 'x';
-      if (message.content_parts != null) message.content_parts = message.content_parts.length ? [null] : [];
-      for (const call of message.tool_calls ?? []) call.function.arguments = '';
-      message.metadata = Object.create(null); message.metadata[REFERENCE] = `${groupId}:${ordinal}`;
+      skeletonMessage(message).metadata[REFERENCE] = `${groupId}:${ordinal}`;
       this.#skeleton.push(message);
     });
   }
@@ -171,3 +194,158 @@ export async function withClaudeReadIndex(path, work, { fidelity = 'byte_lossles
     return work(index);
   }, metrics);
 }
+
+const REPLAYED = new Set(['user', 'assistant', 'attachment', 'system']);
+const EDGE_BYTES = 64 * 1024, VERIFY_MS = 10 * 60_000;
+const shortHash = (bytes) => createHash('sha256').update(bytes).digest('hex').slice(0, 24);
+
+/** One line taken into a scan's state: its place among the file's lines, its header facts, its node in the graph,
+ * what it changes of the recorded profile and, for a record the replay can select, where it stands and the hash of
+ * its bytes. */
+function observeClaudeLine(state, line) {
+  const index = state.lines++;
+  if (nativeTrim(line.text) === '') return;
+  let value;
+  try { value = parseNativeJson(line.text); } catch { state.parseErrors++; return; }
+  captureClaudeMeta(value, state.meta, line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text);
+  state.graph.observe(index, value);
+  state.profile.record(index, value);
+  if (typeof value?.version === 'string') state.version = value.version;
+  if (REPLAYED.has(stringField(value, 'type'))) state.records.set(index, { ...recordFacts(line, value), hash: shortHash(line.bytes) });
+}
+
+/** A transcript's complete lines as one pass over them leaves them, kept between reads of the same file: the next
+ * read takes only the lines written since (`extend`). Nothing a record says is kept, only where it is and what it is
+ * to the replay. */
+class ClaudeRecordScan {
+  records = new Map(); lines = 0; parseErrors = 0; version = null; bytes = 0;
+  graph = new ClaudeReplayIndex(); meta = createSession('claude_code').meta; profile = recordedProfileFold('claude_code');
+  skeletons = new Map(); view = null; hashed = createHash('sha256'); stamp = null; edge = null; size = 0; verified = Date.now();
+
+  constructor(reader) { this.device = reader.fingerprint.device; this.inode = reader.fingerprint.inode; }
+
+  /** Whether this is the scan of `reader`'s file: the same file, no shorter, its scanned bytes as they were. A file
+   * whose size and modification time are those last read is as it was. One that grew is an append while the last
+   * EDGE_BYTES the scan read are as they were (a bounded read), and is taken as one for at most VERIFY_MS after its
+   * bytes were last read through. Any other (written without growing, an edge that moved, or a growing file not read
+   * through for that long) is read through to where the scan stopped and compared by the hash of those bytes, no
+   * line decoded: a record rewritten in place, whatever its length, ends the scan and every mark made from it, at
+   * once when the file did not also grow, and within VERIFY_MS when it did. */
+  async holds(reader) {
+    if (reader.fingerprint.device !== this.device || reader.fingerprint.inode !== this.inode || reader.size < this.bytes) return false;
+    if (this.stamp === `${reader.fingerprint.size}:${reader.fingerprint.mtime_ns}`) return true;
+    if (reader.size > this.size && Date.now() - this.verified < VERIFY_MS) return this.edge === await this.#edge(reader);
+    const hash = createHash('sha256');
+    for (let at = 0; at < this.bytes;) { const block = await reader.read(at, Math.min(1024 * 1024, this.bytes - at)); hash.update(block); at += block.length; }
+    this.verified = Date.now();
+    return hash.digest('hex') === this.hashed.copy().digest('hex');
+  }
+
+  async #edge(reader) {
+    const from = Math.max(0, this.bytes - EDGE_BYTES);
+    return shortHash(await reader.read(from, this.bytes - from));
+  }
+
+  /** The lines completed since the last pass. A last line with no LF yet stays outside the scan: `view` reads it. */
+  async extend(reader) {
+    const from = this.bytes;
+    for await (const line of sessionFileLines(reader, this.bytes)) {
+      if (!line.terminated) break;
+      observeClaudeLine(this, line); this.hashed.update(line.bytes); this.bytes = line.offset + line.length;
+    }
+    if (this.bytes !== from || this.edge == null) this.edge = await this.#edge(reader);
+    this.size = reader.size; this.stamp = `${reader.fingerprint.size}:${reader.fingerprint.mtime_ns}`;
+  }
+
+  /** The replay of the file as `reader` holds it: its messages in order, each as its skeleton with the mark of the
+   * records that make it. A group's skeleton is decoded once and kept while the replay selects it. */
+  async project(reader, fidelity) {
+    const key = `${fidelity}:${this.bytes}:${reader.size}`;
+    if (this.view?.key === key) return this.view;
+    const state = { lines: this.lines, parseErrors: this.parseErrors, version: this.version, records: new Map(),
+      graph: this.graph.clone(), meta: cloneNativeJson(this.meta), profile: this.profile.clone() };
+    // The file's last line while it has no LF yet is read for this answer alone. Cut inside a character, it is a
+    // line still being written: counted as one that does not parse, as a cut record is.
+    if (reader.size > this.bytes) {
+      const bytes = await reader.read(this.bytes, reader.size - this.bytes); let text = null;
+      try { text = decodeSessionUtf8(bytes); } catch { state.lines++; state.parseErrors++; }
+      if (text != null) observeClaudeLine(state, { offset: this.bytes, length: bytes.length, text, bytes });
+    }
+    const recordOf = (index) => state.records.get(index) ?? this.records.get(index);
+    const raw = async (index, at) => { const record = recordOf(index); return decodeSessionUtf8(await at.read(record.offset, record.length)); };
+    const selection = state.graph.selectLines(fidelity), groups = [], sizes = [], skeleton = [], skeletons = new Map(), marks = new Map(), models = new Map();
+    for (const group of claudeGroups(selection.lines, recordOf)) {
+      const id = groups.length, records = group.map(recordOf), mark = shortHash(records.map((record) => record.hash).join(','));
+      let made = skeletons.get(mark) ?? this.skeletons.get(mark);
+      if (!made) made = (await decodeClaudeGroup((index) => raw(index, reader), group)).map((message) => ({ model: Object.hasOwn(message.metadata, 'model') ? message.metadata.model : null, message: skeletonMessage(message) }));
+      skeletons.set(mark, made); groups.push(group); sizes.push(records.reduce((sum, record) => sum + record.length, 0));
+      made.forEach(({ message, model }, ordinal) => {
+        const placed = { ...message, metadata: Object.create(null) }; placed.metadata[REFERENCE] = `${id}:${ordinal}`;
+        marks.set(placed, shortHash(`${mark}:${ordinal}`)); if (model != null) models.set(placed, model);
+        skeleton.push(placed);
+      });
+    }
+    this.skeletons = skeletons;
+    reorderClaudeToolResults(skeleton); ensureToolResultsPaired(skeleton);
+    // A result the pairing pass made up has no record: its mark is of what it says.
+    return this.view = { key, raw, groups, sizes, skeleton, marks: skeleton.map((message) => marks.get(message) ?? shortHash(JSON.stringify(messageJson(message)))),
+      model: models.get(skeleton.findLast((message) => models.has(message))) ?? null, residue: selection.residue, meta: state.meta, lines: state.lines,
+      parseErrors: state.parseErrors, version: state.version, history: state.profile.history };
+  }
+}
+
+// The scans of the files read most recently, at most this many records between them: a transcript read again is
+// read from where its scan stopped, and one read long ago is scanned again. Of the files shorter than
+// SCAN_KEPT_BYTES only the one read last is kept (a pass reads its file more than once): scanning a short file again
+// costs less than keeping the scan of every one read.
+const SCANNED_RECORDS = 400_000, SCAN_KEPT_BYTES = 8 * 1024 * 1024;
+const scans = new Map();
+
+async function scanOf(path, reader) {
+  let scan = scans.get(path); scans.delete(path);
+  if (!scan || !await scan.holds(reader)) scan = new ClaudeRecordScan(reader);
+  await scan.extend(reader);
+  if (scan.bytes < SCAN_KEPT_BYTES) for (const [other, item] of scans) if (item.bytes < SCAN_KEPT_BYTES) scans.delete(other);
+  scans.set(path, scan);
+  let held = 0; for (const item of scans.values()) held += item.lines;
+  for (const [other, item] of scans) { if (held <= SCANNED_RECORDS || item === scan) break; scans.delete(other); held -= item.lines; }
+  return scan;
+}
+
+/**
+ * A window of a Claude Code transcript's messages from the place `from`, read record by record: at most `messages` of
+ * them and `bytes` of transcript (one message at least), with each one's mark and, when `marks` is asked, the mark of
+ * every message of the session. A mark is of the bytes of the records that make a message: while it stands, so does
+ * what a reader took of that message before. Null when the locator names anything else, which is loaded as its
+ * document.
+ */
+export async function loadClaudeRecordWindow(locator, { from, bytes = null, messages = null, marks = false }, { fidelity = 'semantic', metrics } = {}) {
+  const { path, kind } = locator.storage;
+  if (kind !== 'file' || locator.harness === 'hermes' || isCompressedSessionPath(path)) return null;
+  if ((await sourceStat(join(dirname(path), `${basename(path, extname(path))}.meta.json`)))?.isFile()) return null;
+  if (!await supportsClaudeReadIndex(path, { metrics })) return null;
+  return (await withSessionFile(path, async (reader) => {
+    let view;
+    try { view = await (await scanOf(path, reader)).project(reader, fidelity); }
+    catch (error) {
+      scans.delete(path);
+      throw ['ERR_ENCODING_INVALID_ENCODED_DATA', 'ERR_STRING_TOO_LONG'].includes(error?.code) ? sessionTextError(path, error) : error;
+    }
+    const total = view.skeleton.length, offset = Math.min(from, total), session = createSession('claude_code'), counted = new Set();
+    let end = offset, used = 0, decoded = null, decodedGroup = null;
+    for (; end < total && (messages == null || end - offset < messages); end++) {
+      const message = view.skeleton[end], reference = message.metadata[REFERENCE];
+      if (reference === undefined) { session.messages.push(cloneNativeJson(message)); continue; }
+      const [group, ordinal] = reference.split(':').map(Number), cost = counted.has(group) ? 0 : view.sizes[group];
+      if (bytes != null && end > offset && used + cost > bytes) break;
+      counted.add(group); used += cost;
+      if (decodedGroup !== group) { decoded = await decodeClaudeGroup((index) => view.raw(index, reader), view.groups[group]); decodedGroup = group; }
+      session.messages.push(cloneNativeJson(decoded[ordinal]));
+    }
+    session.meta = cloneNativeJson(view.meta); session.imported_message_count = total;
+    session.parse_error_lines = view.parseErrors; session.load_residue = [...view.residue];
+    return { session: { ...normalizedSessionJson(session), raw_record_count: view.lines,
+      resolved_profile: recordedSessionProfile(session, { model: view.model, version: view.version }), resolved_profile_history: view.history.map(cloneNativeJson),
+      window: { offset, returned: end - offset, total_messages: total, marks: view.marks.slice(offset, end), ...(marks ? { all_marks: [...view.marks] } : {}) } } };
+  }, metrics)).result;
+}

package/session-codex-display.mjs

@@ -15,6 +15,9 @@ export function fromCodexDisplayStr(text, messageLimit) {
   if (!Number.isSafeInteger(messageLimit) || messageLimit < 0) throw new RangeError('invalid Codex display message limit');
   const session = createSession('codex'), { meta, messages } = session, precedingUsers = [], canonicalTexts = new Set();
   const retain = Math.min(Number.MAX_SAFE_INTEGER, Math.max(messageLimit, 1) + 64);
+  // The item ids and event texts the kept messages may hold: a record that names neither replaces nothing and looks
+  // through no message, so a read with no bound on its messages (a display anchor's) is linear in what it reads.
+  const displayItems = new Set(), eventTexts = new Set();
   let paginated = false, recordCount = 0, total = 0;
   for (const line of nonEmptyLines(text)) {
     recordCount++;
@@ -24,12 +27,13 @@ export function fromCodexDisplayStr(text, messageLimit) {
     else if (kind === 'event_msg' && paginated && type === 'item_completed') {
       const item = field(payload, 'item'), id = stringField(item, 'id');
       if (id != null) {
-        const position = messages.findIndex((message) => message.metadata.codex_display_item === id), projected = [];
+        const held = displayItems.has(id), position = held ? messages.findIndex((message) => message.metadata.codex_display_item === id) : -1, projected = [];
         pushCodexDisplayItem(item, projected);
         for (const message of projected) message.metadata.codex_display_item = id;
+        if (projected.length) displayItems.add(id);
         stampCodexMessages(projected, 0, timestamp);
         let removed = 0;
-        for (let index = messages.length - 1; index >= 0; index--) if (messages[index].metadata.codex_display_item === id) { messages.splice(index, 1); removed++; }
+        if (held) for (let index = messages.length - 1; index >= 0; index--) if (messages[index].metadata.codex_display_item === id) { messages.splice(index, 1); removed++; }
         total = Math.max(0, total - removed) + projected.length;
         const at = Math.min(position === -1 ? messages.length : position, messages.length);
         for (let index = 0; index < projected.length; index++) messages.splice(at + index, 0, projected[index]);
@@ -47,7 +51,7 @@ export function fromCodexDisplayStr(text, messageLimit) {
       const isAssistant = type === 'message' && stringField(payload, 'role') === 'assistant';
       const assistantText = isAssistant ? extractTextContent(payload, 'content') : null;
       if (assistantText != null && nativeTrim(assistantText) !== '') {
-        const duplicate = messages.findLastIndex((message) => Object.hasOwn(message.metadata, 'codex_event_message') && message.content === assistantText);
+        const duplicate = eventTexts.has(assistantText) ? messages.findLastIndex((message) => Object.hasOwn(message.metadata, 'codex_event_message') && message.content === assistantText) : -1;
         if (duplicate !== -1) { messages.splice(duplicate, 1); total = Math.max(0, total - 1); }
         canonicalTexts.add(nativeTrim(assistantText));
       }
@@ -62,7 +66,7 @@ export function fromCodexDisplayStr(text, messageLimit) {
       const text = extractTextContent(payload, 'message');
       if (nativeTrim(text) !== '' && !canonicalTexts.has(nativeTrim(text))) {
         const before = messages.length; pushCodexAssistant(messages, text); total++;
-        messages.at(-1).metadata.codex_event_message = 'true';
+        messages.at(-1).metadata.codex_event_message = 'true'; eventTexts.add(messages.at(-1).content);
         const phase = stringField(payload, 'phase'); if (phase != null) messages.at(-1).metadata.phase = phase;
         stampCodexMessages(messages, before, timestamp);
       }

package/session-file.mjs

@@ -26,23 +26,30 @@ export async function sessionFileBytes(reader, from = 0) {
 }
 export const sessionFileText = async (reader) => decodeSessionUtf8(await sessionFileBytes(reader));
 
-/** One physical line at a time, including an unterminated final line. LF and
- * CR remain in the bytes; offsets always address the verified open file. */
-export async function* sessionFileLines(reader) {
-  let pieces = [], pending = 0, start = 0;
-  for (let offset = 0; offset < reader.size;) {
+/** A line where it stands: its text is decoded when first read, so a reader that only places a line (a last one
+ * still being written) is not refused for bytes it never reads as text. */
+function fileLine(offset, bytes, terminated) {
+  let text;
+  return { offset, length: bytes.length, bytes, terminated, get text() { return text ??= decodeSessionUtf8(bytes); } };
+}
+
+/** One physical line at a time from `from` (the start of a line), including an unterminated final line. LF and
+ * CR remain in the bytes; offsets always address the verified open file. `bytes` is the line as it is stored and
+ * `terminated` says its LF was read: a last line without one may still be being written. */
+export async function* sessionFileLines(reader, from = 0) {
+  let pieces = [], pending = 0, start = from;
+  for (let offset = from; offset < reader.size;) {
     const chunk = await reader.read(offset, Math.min(64 * 1024, reader.size - offset));
     const chunkStart = offset; offset += chunk.length;
-    let from = 0, end;
-    while ((end = chunk.indexOf(10, from)) !== -1) {
-      pieces.push(chunk.subarray(from, end + 1)); pending += end + 1 - from;
-      const bytes = pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, pending);
-      yield { offset: start, length: pending, text: decodeSessionUtf8(bytes) };
-      start = chunkStart + end + 1; from = end + 1; pieces = []; pending = 0;
+    let at = 0, end;
+    while ((end = chunk.indexOf(10, at)) !== -1) {
+      pieces.push(chunk.subarray(at, end + 1)); pending += end + 1 - at;
+      yield fileLine(start, pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, pending), true);
+      start = chunkStart + end + 1; at = end + 1; pieces = []; pending = 0;
     }
-    if (from < chunk.length) { pieces.push(chunk.subarray(from)); pending += chunk.length - from; }
+    if (at < chunk.length) { pieces.push(chunk.subarray(at)); pending += chunk.length - at; }
   }
-  if (pending) yield { offset: start, length: pending, text: decodeSessionUtf8(Buffer.concat(pieces, pending)) };
+  if (pending) yield fileLine(start, Buffer.concat(pieces, pending), false);
 }
 
 export async function readSessionText(path, metrics) {

package/session-model.d.ts

@@ -108,7 +108,7 @@ export function normalizedItemCount(messages: readonly ChatMessage[]): number;
 export function projectedMessageWindow(total: number, options: SessionLoadOptions): [number, number];
 export function projectInlineMedia(message: MessageJson, options: SessionLoadOptions): MessageJson;
 export function projectedSessionSummary(session: Session, options: SessionLoadOptions): SessionSummary;
-export function recordedSessionProfile(session: Session): RecordedSessionProfile;
+export function recordedSessionProfile(session: Session, read?: { model: string | null; version: string | null } | null): RecordedSessionProfile;
 export function recordedSessionProfileHistory(session: Session): RecordedSessionProfileChange[];
 export function projectedSessionJson(session: Session, options: SessionLoadOptions): ProjectedSession;
 export function projectedSessionResult(session: Session, options: SessionLoadOptions): ProjectedSessionResult;

package/session-read.d.ts

@@ -10,8 +10,8 @@ export interface SessionReadContext { cwd?: string; env?: Record<string, string
 export function parseSessionWire(text: string): unknown;
 export function stringifySessionWire(value: unknown): string;
 export function prettySessionWire(value: unknown): string;
-export function parseSessionReadParams(params: unknown, context?: SessionReadContext): { locator: ReadLocator; fidelity: string; view: (SessionFollowOptions & { fromByte: number | null }) | null; options: import('./session-model.js').SessionLoadOptions | null };
-export function loadSessionRead(params: unknown, context?: SessionReadContext): Promise<ProjectedSessionResult | { session: NormalizedSession & { resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[] } }>;
+export function parseSessionReadParams(params: unknown, context?: SessionReadContext): { locator: ReadLocator; fidelity: string; view: (SessionFollowOptions & { fromByte: number | null; fromMessage: number | null; windowBytes: number | null; windowMessages: number | null; marks: boolean }) | null; options: import('./session-model.js').SessionLoadOptions | null };
+export function loadSessionRead(params: unknown, context?: SessionReadContext): Promise<ProjectedSessionResult | { session: NormalizedSession & { resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[]; window?: { offset: number; returned: number; total_messages: number; marks: string[]; all_marks?: string[] } } }>;
 export function openSessionReadFollower(params: unknown, context?: SessionReadContext): Promise<SessionFollower>;
 /** Recorded values only; malformed complete Claude runtime state leaves mode unknown. */
 export function loadRecordedSessionConfiguration(params: unknown, context?: SessionReadContext): Promise<{ harness: string; session_id: string | null; cwd: unknown; model: unknown; approval_policy: unknown; sandbox_policy: unknown; permission_mode: string | null }>;

package/session-read.mjs

@@ -4,7 +4,7 @@ import { resolve } from 'node:path';
 import { nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJson, stringifyNativeJsonPretty } from './native-json.mjs';
 import { loadSessionLocator } from './session-path.mjs';
 import { loadSessionDisplayLocator, loadSessionDisplayFrom } from './session-display.mjs';
-import { withClaudeReadIndex, supportsClaudeReadIndex } from './session-claude-index.mjs';
+import { withClaudeReadIndex, supportsClaudeReadIndex, loadClaudeRecordWindow } from './session-claude-index.mjs';
 import { SessionFollower } from './session-follower.mjs';
 import { normalizedSessionJson } from './session-model.mjs';
 import { boundSessionView, projectedMessageWindow, projectedSessionJson, projectedSessionResult, projectedSessionSummary, recordedSessionProfile, recordedSessionProfileHistory } from './session-views.mjs';
@@ -58,7 +58,8 @@ export function parseSessionReadParams(params, { cwd = process.cwd() } = {}) {
     const suppliedView = object(params.view, 'view');
     view = { includeSubagents: boolean(suppliedView, 'include_subagents', false), displayHistory: boolean(suppliedView, 'display_history', false),
       messageLimit: unsigned(suppliedView, 'tail_messages', 5000), maxMessageChars: unsigned(suppliedView, 'max_message_chars', 64000),
-      fromByte: unsigned(suppliedView, 'from_byte') };
+      fromByte: unsigned(suppliedView, 'from_byte'), fromMessage: unsigned(suppliedView, 'from_message'),
+      windowBytes: unsigned(suppliedView, 'window_bytes'), windowMessages: unsigned(suppliedView, 'window_messages'), marks: boolean(suppliedView, 'marks', false) };
     if (view.messageLimit != null) view.messageLimit = Math.max(1, view.messageLimit);
     if (view.maxMessageChars != null) view.maxMessageChars = Math.max(256, view.maxMessageChars);
   }
@@ -97,6 +98,11 @@ export async function loadSessionRead(params, context = {}) {
     return projectedSessionResult(await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless' }), options);
   }
   const readOptions = { ...context, fidelity, includeSubagents: view?.includeSubagents ?? true };
+  // A view from a message on is a window of the session read record by record, where its reader has one.
+  if (view?.fromMessage != null && !view.includeSubagents && !view.displayHistory) {
+    const windowed = await loadClaudeRecordWindow(locator, { from: view.fromMessage, bytes: view.windowBytes, messages: view.windowMessages, marks: view.marks }, readOptions);
+    if (windowed != null) return windowed;
+  }
   const session = view?.displayHistory
     ? view.fromByte != null ? await loadSessionDisplayFrom(locator, view.fromByte, readOptions)
       : await loadSessionDisplayLocator(locator, view.messageLimit ?? 500, readOptions)

package/session-records.mjs

@@ -17,7 +17,8 @@ import { restoreTopLevelResidue } from './session-native-residue.mjs';
 import { isCompressedSessionPath, looksLikeSessionSqlite, sessionTextError } from './session-path.mjs';
 
 async function* lines(reader) {
-  try { yield* sessionFileLines(reader); }
+  // a line's text is decoded when first read: here, so that what cannot be decoded is said as this file's
+  try { for await (const line of sessionFileLines(reader)) { void line.text; yield line; } }
   catch (error) { throw ['ERR_ENCODING_INVALID_ENCODED_DATA', 'ERR_STRING_TOO_LONG'].includes(error?.code) ? sessionTextError(reader.path, error) : error; }
 }
 

package/session-views.mjs

@@ -94,10 +94,12 @@ const payloadFor = (record) => has(record, 'payload') ? record.payload : record;
 function parsedRecord(line) { try { return parseNativeJson(line); } catch { return null; } }
 
 /** Only recorded facts. Current configuration and the reader's executable
- * never fill unknown historical fields. */
-export function recordedSessionProfile(session) {
+ * never fill unknown historical fields. `read` gives what a reader that holds
+ * neither every message nor the raw lines found in them: the last recorded
+ * model and Claude Code version. */
+export function recordedSessionProfile(session, read = null) {
   const { meta } = session;
-  let model = session.messages.findLast((message) => has(message.metadata, 'model'))?.metadata.model ?? meta.model;
+  let model = (read ? read.model : session.messages.findLast((message) => has(message.metadata, 'model'))?.metadata.model) ?? meta.model;
   let cwd = meta.cwd, version = null, approval = null, sandbox = null;
   for (const header of meta.codex_headers) {
     const payload = payloadFor(header);
@@ -108,7 +110,8 @@ export function recordedSessionProfile(session) {
     if (has(payload, 'sandbox_policy')) sandbox = cloneNativeJson(payload.sandbox_policy);
   }
   if (meta.source === 'claude_code') {
-    for (let at = session.raw.length - 1; at >= 0; at--) {
+    if (read) version = read.version;
+    else for (let at = session.raw.length - 1; at >= 0; at--) {
       const recorded = string(parsedRecord(session.raw[at])?.version);
       if (recorded != null) { version = recorded; break; }
     }
@@ -119,30 +122,37 @@ export function recordedSessionProfile(session) {
   };
 }
 
+/** The recorded profile as each record changes it, one record at a time: `history` names every record that changed it. */
+export function recordedProfileFold(source, profile = {
+  worker: { harness: source === 'codex' ? 'codex' : 'claude-code', model: null, cwd: null, binary: { version: null } },
+  permissions: { native: { approval: null, sandbox: null } }, source: 'native-session',
+}, history = []) {
+  return {
+    history,
+    clone: () => recordedProfileFold(source, cloneNativeJson(profile), [...history]),
+    record(index, record) {
+      if (record == null) return;
+      const before = cloneNativeJson(profile), payload = payloadFor(record);
+      for (const key of ['cwd', 'model']) {
+        if (typeof payload?.[key] === 'string') profile.worker[key] = payload[key];
+      }
+      const version = string(has(payload, 'cli_version') ? payload.cli_version : record?.version);
+      if (version != null) profile.worker.binary.version = version;
+      if (typeof record?.message?.model === 'string') profile.worker.model = record.message.model;
+      for (const [key, target] of [['approval_policy', 'approval'], ['sandbox_policy', 'sandbox']]) {
+        if (has(payload, key)) profile.permissions.native[target] = cloneNativeJson(payload[key]);
+      }
+      if (!isDeepStrictEqual(before, profile)) history.push({ native_key: `profile-record:${index}`, at: string(record?.timestamp), profile: cloneNativeJson(profile) });
+    },
+  };
+}
+
 export function recordedSessionProfileHistory(session) {
   if (!['codex', 'claude_code'].includes(session.meta.source)) return [];
-  const profile = {
-    worker: { harness: session.meta.source === 'codex' ? 'codex' : 'claude-code', model: null, cwd: null, binary: { version: null } },
-    permissions: { native: { approval: null, sandbox: null } }, source: 'native-session',
-  };
+  const fold = recordedProfileFold(session.meta.source);
   const records = session.meta.source === 'codex' ? session.meta.codex_headers : session.raw;
-  const history = [];
-  for (let index = 0; index < records.length; index++) {
-    const record = session.meta.source === 'codex' ? records[index] : parsedRecord(records[index]);
-    if (record == null) continue;
-    const before = cloneNativeJson(profile), payload = payloadFor(record);
-    for (const key of ['cwd', 'model']) {
-      if (typeof payload?.[key] === 'string') profile.worker[key] = payload[key];
-    }
-    const version = string(has(payload, 'cli_version') ? payload.cli_version : record?.version);
-    if (version != null) profile.worker.binary.version = version;
-    if (typeof record?.message?.model === 'string') profile.worker.model = record.message.model;
-    for (const [key, target] of [['approval_policy', 'approval'], ['sandbox_policy', 'sandbox']]) {
-      if (has(payload, key)) profile.permissions.native[target] = cloneNativeJson(payload[key]);
-    }
-    if (!isDeepStrictEqual(before, profile)) history.push({ native_key: `profile-record:${index}`, at: string(record?.timestamp), profile: cloneNativeJson(profile) });
-  }
-  return history;
+  for (let index = 0; index < records.length; index++) fold.record(index, session.meta.source === 'codex' ? records[index] : parsedRecord(records[index]));
+  return fold.history;
 }
 
 export function projectedSessionJson(session, options) {