@volter/supercode-interchange 0.0.0-stage → 0.1.0

package/native-json.mjs

@@ -0,0 +1,160 @@
+// Catalog JSON follows the shipped CLI's serde_json 1.0.150 representation:
+// insertion-ordered objects, i64/u64 integers, and separately typed floats.
+// Facts about ordering/number tokens stay private; callers receive ordinary
+// JS values and never serialize this metadata into a session descriptor.
+const facts = new WeakMap();
+const uintMax = (1n << 64n) - 1n, intMin = -(1n << 63n), intMax = (1n << 63n) - 1n;
+const invalid = () => { throw new SyntaxError('not native catalog JSON'); };
+
+function validString(text) {
+  for (let at = 0; at < text.length; at++) {
+    const code = text.charCodeAt(at);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = text.charCodeAt(++at);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) invalid();
+    } else if (code >= 0xdc00 && code <= 0xdfff) invalid();
+  }
+  return text;
+}
+
+/** serde_json's default float parser keeps a u64 significand, discards
+ * overflowing decimal digits and scales with its literal powers of ten.
+ * It does not use the optional float_roundtrip feature. */
+function decimalValue(token) {
+  const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(token);
+  const negative = match[1] === '-';
+  let significand = 0n, exponent = 0, overflow = false;
+  for (const digit of match[2]) {
+    const next = significand * 10n + BigInt(digit);
+    if (overflow || next > uintMax) { overflow = true; exponent++; }
+    else significand = next;
+  }
+  overflow = false;
+  for (const digit of match[3] ?? '') {
+    const next = significand * 10n + BigInt(digit);
+    if (overflow || next > uintMax) overflow = true;
+    else { significand = next; exponent--; }
+  }
+  if (match[4]) {
+    const supplied = Number(match[4]);
+    if (!Number.isFinite(supplied) || Math.abs(supplied) > 2_147_483_647) {
+      if (supplied > 0 && significand !== 0n) invalid();
+      return negative ? -0 : 0;
+    }
+    exponent = Math.max(-2_147_483_648, Math.min(2_147_483_647, exponent + supplied));
+  }
+  let number = Number(significand);
+  while (Math.abs(exponent) > 308) {
+    if (number === 0) break;
+    if (exponent > 0) invalid();
+    number /= 1e308; exponent += 308;
+  }
+  if (number !== 0 || Math.abs(exponent) <= 308) {
+    const power = Number(`1e${Math.abs(exponent)}`);
+    number = exponent < 0 ? number / power : number * power;
+  }
+  if (!Number.isFinite(number)) invalid();
+  return negative ? -number : number;
+}
+
+function numberFact(token) {
+  if (!/[.eE]/.test(token)) {
+    const whole = BigInt(token);
+    if (token !== '-0' && whole >= intMin && whole <= uintMax) return { value: Number(whole), kind: 'integer', integer: whole };
+  }
+  return { value: decimalValue(token), kind: 'float' };
+}
+
+export function parseNativeJson(text) {
+  let at = 0;
+  const white = () => { while (/[\x20\t\r\n]/.test(text[at] ?? '') && at < text.length) at++; };
+  const takeString = () => {
+    const from = at++;
+    while (at < text.length) {
+      const char = text[at++];
+      if (char === '"') return validString(JSON.parse(text.slice(from, at)));
+      if (char === '\\') at++;
+    }
+    invalid();
+  };
+  const value = (depth) => {
+    white();
+    const char = text[at];
+    if (char === '"') return { value: takeString() };
+    if (char === '[' || char === '{') {
+      if (depth >= 127) invalid();
+      const array = char === '[', result = array ? [] : Object.create(null);
+      const meta = { keys: [], numbers: new Map() };
+      facts.set(result, meta);
+      const end = array ? ']' : '}';
+      at++; white();
+      if (text[at] === end) { at++; return { value: result }; }
+      for (;;) {
+        let key;
+        if (array) key = String(result.length);
+        else {
+          if (text[at] !== '"') invalid();
+          key = takeString(); white();
+          if (text[at++] !== ':') invalid();
+        }
+        const child = value(depth + 1);
+        if (!Object.hasOwn(result, key)) meta.keys.push(key);
+        result[key] = child.value;
+        if (child.kind) meta.numbers.set(key, child); else meta.numbers.delete(key);
+        white();
+        if (text[at] === end) { at++; break; }
+        if (text[at++] !== ',') invalid();
+        white();
+      }
+      return { value: result };
+    }
+    for (const [literal, result] of [['true', true], ['false', false], ['null', null]]) {
+      if (text.startsWith(literal, at)) { at += literal.length; return { value: result }; }
+    }
+    const number = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
+    number.lastIndex = at;
+    const token = number.exec(text)?.[0];
+    if (token == null) invalid();
+    at += token.length;
+    return numberFact(token);
+  };
+  const result = value(0);
+  white(); if (at !== text.length) invalid();
+  return result.value;
+}
+
+export function nativeObjectKeys(value) { return facts.get(value)?.keys ?? Object.keys(value); }
+
+export function nativeInteger(value, key, { signed = false } = {}) {
+  if (value == null || typeof value !== 'object') return null;
+  const fact = facts.get(value)?.numbers.get(key);
+  if (fact?.kind !== 'integer') return null;
+  const whole = fact.integer;
+  return whole >= (signed ? intMin : 0n) && whole <= (signed ? intMax : uintMax) ? whole : null;
+}
+
+function formatFloat(number) {
+  if (number === 0) return Object.is(number, -0) ? '-0.0' : '0.0';
+  // V8 supplies the shortest correctly rounded decimal significand. Apply
+  // pinned zmij 1.0.21's f64 fixed/exponent spelling, including signed exponent.
+  const sign = number < 0 ? '-' : '';
+  const [coefficient, scale] = Math.abs(number).toExponential().split('e');
+  const digits = coefficient.replace('.', ''), exponent = Number(scale);
+  if (exponent >= -5 && exponent <= 15) {
+    if (exponent >= digits.length - 1) return `${sign}${digits}${'0'.repeat(exponent + 1 - digits.length)}.0`;
+    if (exponent >= 0) return `${sign}${digits.slice(0, exponent + 1)}.${digits.slice(exponent + 1)}`;
+    return `${sign}0.${'0'.repeat(-exponent - 1)}${digits}`;
+  }
+  return `${sign}${coefficient}e${exponent >= 0 ? '+' : ''}${exponent}`;
+}
+
+export function stringifyNativeJson(value) {
+  if (value == null || typeof value !== 'object') return JSON.stringify(value);
+  const meta = facts.get(value);
+  const child = (key) => {
+    const fact = meta?.numbers.get(key);
+    return fact ? fact.kind === 'integer' ? String(fact.integer) : formatFloat(fact.value) : stringifyNativeJson(value[key]);
+  };
+  if (Array.isArray(value)) return `[${value.map((_, at) => child(String(at))).join(',')}]`;
+  return `{${nativeObjectKeys(value).map((key) => `${JSON.stringify(key)}:${child(key)}`).join(',')}}`;
+}

package/native-ledgers.mjs

@@ -0,0 +1,91 @@
+import { dirname, basename, join } from 'node:path';
+import { withSessionFile, sameFingerprint, appendableFingerprint, visitAppendedLines, parseJsonLine } from './file-io.mjs';
+import { optionalFile } from './source-files.mjs';
+import { nativeTrim, displayText, truncateScalars } from './text.mjs';
+
+export function codexNamesPath(rollout) {
+  let parent = rollout;
+  for (;;) {
+    if (basename(parent) === 'sessions') return join(dirname(parent), 'session_index.jsonl');
+    const next = dirname(parent);
+    if (next === parent) return null;
+    parent = next;
+  }
+}
+
+/** Name/history ledgers are watched sources, not query-time whole-file reads.
+ * On an append, apply only its new lines and unfinished EOF; the owner commits
+ * map changes and this verified offset under one source identity. */
+async function readLedger(path, kind, previous, metrics) {
+  return optionalFile(path, async (reader) => {
+    if (sameFingerprint(previous?.fingerprint, reader.fingerprint)) return previous.result;
+    const old = previous?.result;
+    // An EOF record can change before its newline arrives. Rebuild in that
+    // unusual case rather than leaving a rename/topic from now-invalid bytes.
+    const append = old && !old.trailing && appendableFingerprint(previous?.fingerprint, reader.fingerprint);
+    const values = new Map(append ? old.values : []);
+    const apply = (line) => {
+      const record = parseJsonLine(line, { strictUtf8: true });
+      if (record == null) return;
+      if (kind === 'names') {
+        if (typeof record.id === 'string' && typeof record.thread_name === 'string') {
+          const name = nativeTrim(record.thread_name);
+          if (name) values.set(record.id, name);
+        }
+      } else if (typeof record.session_id === 'string' && !values.has(record.session_id)) {
+        const content = displayText(record.text);
+        if (content != null && nativeTrim(content)) values.set(record.session_id, { role: 'user', content: truncateScalars(content, 4096), metadata: {} });
+      }
+    };
+    const state = await visitAppendedLines(reader, append ? old : null, apply);
+    if (state.trailing) apply(Buffer.from(state.trailing, 'base64'));
+    return { ...state, values };
+  }, metrics);
+}
+
+export const readCodexNames = (path, options = {}) => readLedger(path, 'names', options.previous, options.metrics);
+export const readCodexHistory = (path, options = {}) => readLedger(path, 'history', options.previous, options.metrics);
+
+const titleKey = Buffer.from('"customTitle":');
+
+/** Native name matching searches this exact byte key anywhere in a Claude
+ * transcript, including late rename records. It does not require the enclosing
+ * record to parse. Keep the key boundary or an unfinished title between
+ * reads; names have no native length cap, so a long unfinished title is
+ * retained until its closing quote arrives rather than silently truncated. */
+export async function readClaudeTitles(path, { previous, metrics } = {}) {
+  return withSessionFile(path, async (reader) => {
+    if (sameFingerprint(previous?.fingerprint, reader.fingerprint)) return previous.result;
+    const append = previous && typeof previous.result.pending === 'string' && appendableFingerprint(previous.fingerprint, reader.fingerprint);
+    const titles = new Set(append ? previous.result.titles : []);
+    let offset = append ? previous.size : 0;
+    let pending = append ? Buffer.from(previous.result.pending, 'base64') : Buffer.alloc(0);
+    while (offset < reader.size) {
+      const chunk = await reader.read(offset, Math.min(64 * 1024, reader.size - offset), { appended: append && offset >= previous.size });
+      offset += chunk.length;
+      const bytes = pending.length ? Buffer.concat([pending, chunk]) : chunk;
+      let from = 0, at;
+      pending = Buffer.alloc(0);
+      while ((at = bytes.indexOf(titleKey, from)) >= 0) {
+        const start = at + titleKey.length;
+        let quote = start;
+        while (quote < bytes.length && [9, 10, 13, 32].includes(bytes[quote])) quote++;
+        if (quote >= bytes.length) { pending = Buffer.from(bytes.subarray(at)); break; }
+        if (bytes[quote] !== 34) { from = start; continue; }
+        let end = quote + 1, closed = false;
+        while (end < bytes.length) {
+          if (bytes[end] === 92) { end += 2; continue; }
+          if (bytes[end++] === 34) { closed = true; break; }
+        }
+        if (!closed) {
+          pending = Buffer.from(bytes.subarray(at)); break;
+        }
+        const title = parseJsonLine(bytes.subarray(quote, end));
+        if (typeof title === 'string') titles.add(title);
+        from = start;
+      }
+      if (!pending.length) pending = Buffer.from(bytes.subarray(Math.max(from, bytes.length - titleKey.length + 1)));
+    }
+    return { titles: [...titles], offset: reader.size, pending: pending.toString('base64') };
+  }, metrics);
+}

package/openclaw.mjs

@@ -0,0 +1,97 @@
+import { basename, sep } from 'node:path';
+import { withSessionFile, parseJsonLine, sameFingerprint, appendableFingerprint } from './file-io.mjs';
+import { finalizeNouns } from './metadata.mjs';
+import { readColdMetadataTail, advanceMetadataTail } from './jsonl.mjs';
+import { nativeTrim } from './text.mjs';
+
+const needle = Buffer.from('"type":"message"');
+
+export function openclawNouns(header, path) {
+  const components = path.split(sep), at = components.indexOf('agents');
+  let profile = at >= 0 && at + 1 < components.length ? components[at + 1] : null;
+  const candidate = Object.hasOwn(header, 'sessionKey') ? header.sessionKey : header.__openclaw?.sessionKey;
+  if (typeof candidate !== 'string') return profile == null ? {} : { profile };
+  const parts = candidate.split(':');
+  let surface = { key: candidate }, trigger = null, recurrence = null;
+  if (parts[0] === 'agent' && parts.length >= 3) {
+    if (parts[2] === 'main') {
+      profile = parts[1]; surface.kind = 'main'; trigger = 'unknown';
+    } else if (parts.length >= 5) {
+      profile = parts[1]; trigger = 'channel';
+      surface = { ...surface, platform: parts[2], kind: parts[3], chat_id: parts[4] };
+      if ((parts[5] === 'thread' || parts[5] === 'topic') && parts.length >= 7) surface.thread_id = parts[6];
+    }
+  } else if (parts[0] === 'cron' && parts.length >= 2) {
+    trigger = 'cron'; recurrence = { job_id: parts.slice(1).join(':'), kind: 'cron' };
+  } else if (parts[0] === 'hook' && parts.length >= 2) trigger = 'webhook';
+  else if (parts[0] === 'acp-bridge') { trigger = 'api'; surface.platform = 'acp'; }
+  return { ...(profile != null ? { profile } : {}), ...(trigger != null ? { surface, trigger } : {}), ...(recurrence ? { recurrence } : {}) };
+}
+
+/** Count exactly the native per-line literal, once per line, without keeping
+ * body lines in memory. Validate all newly read UTF-8 as the native full-text
+ * reader does. The partial line's hit and overlap survive an append/restart. */
+async function scanCounts(reader, previous) {
+  const count = previous ? { ...previous.count } : { complete: 0, pending_hit: false, match_tail: '' };
+  let overlap = Buffer.from(count.match_tail, 'base64');
+  let offset = previous?.offset ?? 0, header = previous?.header ?? null;
+  let headerTerminated = previous?.header_terminated ?? false;
+  let headerPieces = [], headerSize = 0;
+  const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+  const acceptHeader = (terminated) => {
+    const bytes = Buffer.concat(headerPieces, headerSize);
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    headerPieces = []; headerSize = 0;
+    if (!nativeTrim(text)) return;
+    const value = parseJsonLine(bytes, { strictUtf8: true });
+    if (value?.type !== 'session') throw new Error(`${reader.path} has no OpenClaw session header`);
+    header = value; headerTerminated = terminated;
+  };
+  while (offset < reader.size) {
+    const chunk = await reader.read(offset, Math.min(64 * 1024, reader.size - offset), { appended: previous != null });
+    offset += chunk.length;
+    utf8.decode(chunk, { stream: true });
+    let from = 0;
+    while (from < chunk.length) {
+      const end = chunk.indexOf(10, from), terminated = end >= 0;
+      const part = chunk.subarray(from, terminated ? end : chunk.length);
+      if (!count.pending_hit) {
+        const joined = overlap.length ? Buffer.concat([overlap, part]) : part;
+        count.pending_hit = joined.indexOf(needle) >= 0;
+        overlap = count.pending_hit ? Buffer.alloc(0) : Buffer.from(joined.subarray(Math.max(0, joined.length - needle.length + 1)));
+      }
+      if (header == null) {
+        headerPieces.push(part); headerSize += part.length;
+        if (terminated) acceptHeader(true);
+      }
+      if (!terminated) break;
+      if (count.pending_hit) count.complete++;
+      count.pending_hit = false; overlap = Buffer.alloc(0);
+      from = end + 1;
+    }
+  }
+  utf8.decode(); // A truncated multibyte sequence is a failed part, not none.
+  if (header == null && headerSize) acceptHeader(false);
+  if (header == null) throw new Error(`${reader.path} has no OpenClaw session header`);
+  count.match_tail = overlap.toString('base64');
+  return { count, header, header_terminated: headerTerminated };
+}
+
+export async function readOpenClaw(path, { previous, metrics } = {}) {
+  if (!path.endsWith('.jsonl') || path.endsWith('.trajectory.jsonl')) return null;
+  return withSessionFile(path, async (reader) => {
+    if (sameFingerprint(previous?.fingerprint, reader.fingerprint)) return previous.result;
+    const old = previous?.result?.state;
+    const append = old?.header_terminated && appendableFingerprint(previous?.fingerprint, reader.fingerprint);
+    const counted = await scanCounts(reader, append ? old : null);
+    const tail = append && old.appendable ? await advanceMetadataTail(reader, 'openclaw', old) : await readColdMetadataTail(reader, 'openclaw');
+    const header = counted.header;
+    return {
+      descriptor: finalizeNouns({ locator: { harness: 'openclaw', session_id: typeof header.id === 'string' ? header.id : basename(path, '.jsonl'), storage: { kind: 'file', path } },
+        cwd: typeof header.cwd === 'string' ? header.cwd : null, title: null, model: null,
+        updated_at_ms: tail.facts.last_turn_ms ?? reader.modified_ms, message_count: counted.count.complete + Number(counted.count.pending_hit),
+        ...openclawNouns(header, path) }),
+      state: { ...tail, ...counted },
+    };
+  }, metrics);
+}

package/orchestrator-store.mjs

@@ -0,0 +1,79 @@
+import { realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readStore, statement, text, integer, unsigned, jsonColumn } from './sqlite-reader.mjs';
+import { finalizeNouns } from './metadata.mjs';
+
+const triggerWords = new Set(['human', 'channel', 'cron', 'heartbeat', 'webhook', 'parent', 'api', 'task', 'unknown']);
+const endWords = new Set(['idle', 'daily', 'reset', 'new', 'handoff', 'transfer', 'left', 'error']);
+const optionalText = (value) => value == null || typeof value === 'string';
+const object = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
+const nonempty = (value) => typeof value === 'string' && value !== '' ? value : null;
+const columns = "json_extract(g.entry_json, '$.metadata.supercode.binding') AS binding, CAST(strftime('%s', json_extract(g.entry_json, '$.metadata.supercode.binding.last_activity_at')) AS INTEGER) AS epoch";
+
+function routingScope(path) {
+  const sessions = join(dirname(path), 'sessions');
+  try { return realpathSync.native(sessions); } catch { return sessions; }
+}
+
+/** Binding's required records and native enum fields are validated before
+ * projection. A malformed routing binding is omitted, as by the native codec;
+ * its routing key/change position still belongs to the source snapshot. */
+function bindingDescriptor(path, profile, raw, epoch) {
+  const binding = jsonColumn(raw);
+  if (!object(binding) || !object(binding.key) || !object(binding.worker) || typeof binding.worker.harness !== 'string') return null;
+  if (['key', 'platform', 'kind', 'chat_type', 'chat_id', 'thread_id', 'participant_id'].some((field) => !optionalText(binding.key[field]))) return null;
+  if (['session_id', 'locator'].some((field) => !optionalText(binding.worker[field]))) return null;
+  if (['started_at', 'last_activity_at', 'ended_at', 'profile', 'conversation', 'agent'].some((field) => !optionalText(binding[field]))) return null;
+  if (Object.hasOwn(binding.key, 'kind') && Object.hasOwn(binding.key, 'chat_type')) return null;
+  if (binding.residue !== undefined && !object(binding.residue)) return null;
+  if (binding.trigger !== undefined && !triggerWords.has(binding.trigger)) return null;
+  if (binding.end_reason != null && !endWords.has(binding.end_reason)) return null;
+  if (binding.recurrence != null && (!object(binding.recurrence) || typeof binding.recurrence.job_id !== 'string'
+    || (binding.recurrence.kind !== undefined && typeof binding.recurrence.kind !== 'string'))) return null;
+  if (binding.handoff != null && (!object(binding.handoff) || typeof binding.handoff.state !== 'string'
+    || !optionalText(binding.handoff.to) || !optionalText(binding.handoff.error))) return null;
+  // The native bridge decodes its Binding, then constructs a new binding from
+  // the orchestrator row: profile and trigger follow that row's projection.
+  const platform = binding.key.platform ?? '', kind = binding.key.kind ?? binding.key.chat_type ?? '';
+  const chat = nonempty(binding.key.chat_id), thread = nonempty(binding.key.thread_id), participant = nonempty(binding.key.participant_id);
+  const parts = ['agent', profile === '' ? 'main' : profile, platform, kind, ...[chat, thread, participant].filter((part) => part != null)];
+  const surface = { key: parts.join(':'), platform, kind,
+    ...(chat != null ? { chat_id: chat } : {}), ...(thread != null ? { thread_id: thread } : {}), ...(participant != null ? { participant_id: participant } : {}) };
+  const recurrence = binding.recurrence ? { job_id: binding.recurrence.job_id, kind: 'cron' } : null;
+  const trigger = recurrence ? 'cron' : platform === 'webhook' ? 'webhook' : 'channel';
+  const id = nonempty(binding.worker.session_id), locator = nonempty(binding.worker.locator);
+  let title = `${binding.worker.harness} ${id ?? '(no worker session yet)'}`;
+  if (binding.end_reason != null && binding.ended_at != null) title += ` (ended: ${binding.end_reason})`;
+  const state = binding.handoff?.state, destination = binding.handoff?.to, error = binding.handoff?.error;
+  const at = epoch == null ? null : unsigned(integer(epoch) < 0n ? 0n : epoch);
+  if (at != null && !Number.isSafeInteger(at * 1000)) throw new Error(`${path} has an activity epoch outside the exact Node wire range`);
+  return finalizeNouns({ locator: { harness: 'orchestrator', session_id: id ?? '', storage: { kind: 'file', path: locator ?? path } },
+    cwd: null, title, updated_at_ms: at == null ? null : at * 1000, model: null, message_count: null,
+    surface, profile, trigger, ...(recurrence ? { recurrence } : {}),
+    ...(state != null ? { cross_surface: { state, ...(destination != null ? { platform: destination } : {}), ...(error != null ? { error } : {}) } } : {}) });
+}
+
+/** Routing keys are the source-row keys; several bindings may address the
+ * same worker id. Do not discard them by deduplicating native session ids. */
+export async function readOrchestratorStore(path, profile, { after, metrics = {} } = {}) {
+  return readStore(path, (db) => {
+    const hasChanges = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='supercode_routing_changes'").get() != null;
+    const sequence = hasChanges ? integer(statement(db, 'SELECT COALESCE(MAX(seq),0) AS seq FROM supercode_routing_changes').get().seq) : 0n;
+    const scope = routingScope(path);
+    let values, incremental = after != null && hasChanges;
+    if (incremental) {
+      const cursor = BigInt(after);
+      if (cursor < 0n || cursor > sequence) throw Object.assign(new Error('orchestrator routing cursor is stale; its source requires a full snapshot'), { code: 'INDEX_SOURCE_RESET' });
+      values = statement(db, `SELECT c.session_key, c.deleted, ${columns} FROM supercode_routing_changes c
+        LEFT JOIN gateway_routing g ON g.scope=c.scope AND g.session_key=c.session_key
+        WHERE c.scope=? AND c.seq>? ORDER BY c.seq`).all(scope, cursor);
+    } else {
+      values = statement(db, `SELECT g.session_key, 0 AS deleted, ${columns} FROM gateway_routing g
+        WHERE g.scope=? AND json_extract(g.entry_json, '$.metadata.supercode') IS NOT NULL`).all(scope);
+    }
+    const rows = values.map((value) => ({ key: text(value.session_key),
+      descriptor: integer(value.deleted) !== 0n ? null : bindingDescriptor(path, profile, value.binding, value.epoch) }));
+    metrics.store_sessions_read = (metrics.store_sessions_read ?? 0) + values.length;
+    return { rows, cursor: String(sequence), incremental, has_changes: hasChanges };
+  }, metrics);
+}

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@volter/supercode-interchange",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Read-only harness metadata and discovery projection for Supercode's daemon-owned session index",
+  "license": "MIT OR Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "files": ["*.mjs", "*.d.ts", "README.md", "LICENSE-MIT", "LICENSE-APACHE"],
+  "engines": { "node": ">=22.15.0" },
+  "dependencies": { "@noble/hashes": "2.4.0" }
+}

package/previews.mjs

@@ -0,0 +1,183 @@
+import { blake3 } from '@noble/hashes/blake3.js';
+import { withSessionFile } from './file-io.mjs';
+import { parseNativeJson, stringifyNativeJson, nativeInteger } from './native-json.mjs';
+import { readStore, statement, jsonColumn } from './sqlite-reader.mjs';
+import { nativeTrim, displayText, truncateScalars } from './text.mjs';
+
+const maxCandidates = 8, headBytes = 512 * 1024, tailBytes = 512 * 1024, expandedTailBytes = 4 * 1024 * 1024;
+const conversationRoles = new Set(['user', 'assistant']);
+const fileFormats = new Set(['claude-code', 'codex', 'pi', 'gemini', 'grok', 'supercode']);
+
+function provenance(record) {
+  const result = {};
+  for (const key of ['promptSource', 'interruptedMessageId', 'sourceToolUseID']) if (typeof record[key] === 'string') result[key] = record[key];
+  for (const key of ['isMeta', 'isCompactSummary', 'isVisibleInTranscriptOnly']) if (record[key] === true) result[key] = 'true';
+  const priority = nativeInteger(record, 'queuePriority', { signed: true });
+  if (priority != null) result.queuePriority = String(priority);
+  if (typeof record.origin?.kind === 'string') result.origin = record.origin.kind;
+  return result;
+}
+
+function nativeIdentity(record) {
+  for (const [object, key] of [[record, 'uuid'], [record, 'id'], [record.message, 'id'], [record.payload, 'id']]) {
+    if (object != null && typeof object === 'object' && Object.hasOwn(object, key)) {
+      // A present non-string wins the or_else chain; only timestamp remains
+      // eligible afterwards. Do not silently advance to a later id field.
+      return typeof object[key] === 'string' ? object[key] : typeof record.timestamp === 'string' ? record.timestamp : null;
+    }
+  }
+  return typeof record.timestamp === 'string' ? record.timestamp : null;
+}
+
+export function messageCandidateCursor(harness, record) {
+  const identity = nativeIdentity(record);
+  const input = Buffer.concat([Buffer.from('supercode.session-preview-cursor.v1\0'), Buffer.from(harness), Buffer.from([0]),
+    Buffer.from(identity ?? stringifyNativeJson(record))]);
+  return `v1:${Buffer.from(blake3(input)).toString('hex').slice(0, 24)}`;
+}
+
+function push(candidates, role, content, metadata = {}, cursor) {
+  if (candidates.length >= maxCandidates) return;
+  const text = displayText(content);
+  if (text == null || !nativeTrim(text)) return;
+  candidates.push({ ...(cursor != null ? { cursor } : {}), role, content: truncateScalars(text, 4096), metadata });
+}
+
+function genericMessage(record, harness) {
+  if (harness === 'claude-code' && conversationRoles.has(record?.type)) return { role: record.type, content: record.message?.content, metadata: record.type === 'user' ? provenance(record) : {} };
+  if (harness === 'pi' && record?.type === 'message' && conversationRoles.has(record.message?.role)) return { role: record.message.role, content: record.message.content };
+  if (harness === 'gemini' && (record?.type === 'user' || record?.type === 'gemini')) return { role: record.type === 'user' ? 'user' : 'assistant', content: record.content };
+  if (harness === 'grok' && conversationRoles.has(record?.type)) return { role: record.type, content: record.content };
+  if (harness === 'supercode' && conversationRoles.has(record?.role)) return { role: record.role, content: record.content };
+  return null;
+}
+
+function codexMessage(native) {
+  const payload = native?.payload;
+  let role, content;
+  if (native?.type === 'response_item' && payload?.type === 'message' && conversationRoles.has(payload.role)) {
+    role = payload.role; content = payload.content;
+  } else if (native?.type === 'event_msg' && payload?.type === 'user_message') { role = 'user'; content = payload.message; }
+  else if (native?.type === 'event_msg' && payload?.type === 'agent_message') { role = 'assistant'; content = payload.message; }
+  else return null;
+  const text = displayText(content);
+  return text == null || !nativeTrim(text) ? null : { native, role, text };
+}
+
+function parseLine(text) { try { return parseNativeJson(text); } catch { return null; } }
+
+function codexCandidates(lines, latest) {
+  const candidates = [];
+  let pending = null;
+  const emit = (record) => {
+    const metadata = latest && typeof record.native.timestamp === 'string' ? { timestamp: record.native.timestamp } : {};
+    push(candidates, record.role, record.text, metadata, latest ? messageCandidateCursor('codex', record.native) : null);
+  };
+  for (const line of lines) {
+    const current = codexMessage(parseLine(line));
+    if (current == null) continue;
+    if (pending == null) pending = current;
+    else if (pending.role === current.role && pending.text === current.text && pending.native.type !== current.native.type) {
+      emit(pending.native.type === 'response_item' ? pending : current); pending = null;
+    } else { emit(pending); pending = current; }
+    if (candidates.length >= maxCandidates) break;
+  }
+  if (pending != null) emit(pending);
+  return candidates;
+}
+
+function candidatesIn(bytes, harness, latest) {
+  // Validate the entire window before selecting eight records, matching the
+  // native String::from_utf8 refusal even for unused later preview bytes.
+  const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  const lines = text.split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  if (latest) lines.reverse();
+  if (harness === 'codex') return codexCandidates(lines, latest);
+  const candidates = [];
+  for (const line of lines) {
+    const record = parseLine(line), message = genericMessage(record, harness);
+    if (message == null) continue;
+    const metadata = { ...message.metadata };
+    if (latest && harness === 'claude-code' && typeof record.timestamp === 'string') metadata.timestamp = record.timestamp;
+    push(candidates, message.role, message.content, metadata, latest ? messageCandidateCursor(harness, record) : null);
+    if (candidates.length >= maxCandidates) break;
+  }
+  return candidates;
+}
+
+/** Topic reads raw native files, including packed Codex rollouts. The existing
+ * catalog does not decompress previews; its separate history source supplies
+ * archived Codex topic fallback. Only headers require the streaming decoder. */
+export async function readFileTopics(path, harness, metrics) {
+  if (harness !== 'claude-code' && harness !== 'codex') return [];
+  return (await withSessionFile(path, async (reader) => {
+    let bytes = await reader.read(0, Math.min(reader.size, headBytes));
+    if (reader.size > headBytes) {
+      const end = bytes.lastIndexOf(10);
+      if (end >= 0) bytes = bytes.subarray(0, end);
+    }
+    return candidatesIn(bytes, harness, false);
+  }, metrics)).result;
+}
+
+export async function readFileLatest(path, harness, metrics) {
+  // OpenClaw and orchestrator deliberately have no generic native projection.
+  if (!fileFormats.has(harness)) return [];
+  return (await withSessionFile(path, async (reader) => {
+    const take = async (limit) => {
+      const from = Math.max(0, reader.size - limit);
+      let bytes = await reader.read(from, reader.size - from);
+      if (from > 0) {
+        const end = bytes.indexOf(10);
+        if (end < 0) return [];
+        bytes = bytes.subarray(end + 1);
+      }
+      return candidatesIn(bytes, harness, true);
+    };
+    const initial = await take(tailBytes);
+    return initial.length ? initial : take(expandedTailBytes);
+  }, metrics)).result;
+}
+
+function sqlText(value, bytes) {
+  if (typeof value !== 'string') return null;
+  try { return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); } catch { return null; }
+}
+
+async function storeLatest(locator, metrics) {
+  const { harness, storage, session_id: id } = locator;
+  return (await readStore(storage.path, (db) => {
+    const candidates = [];
+    if (harness === 'opencode') {
+      const rows = statement(db, `SELECT m.data AS message, p.data AS part, CAST(m.data AS BLOB) AS message_bytes, CAST(p.data AS BLOB) AS part_bytes
+        FROM message m JOIN part p ON p.message_id=m.id WHERE m.session_id=?
+        ORDER BY m.time_created DESC, p.time_created DESC LIMIT 32`).all(storage.selector);
+      for (const row of rows) {
+        const message = jsonColumn(sqlText(row.message, row.message_bytes)), part = jsonColumn(sqlText(row.part, row.part_bytes));
+        if (conversationRoles.has(message?.role) && part?.type === 'text') push(candidates, message.role, part.text);
+        if (candidates.length >= maxCandidates) break;
+      }
+    } else {
+      const hermes = harness === 'hermes';
+      const sql = hermes
+        ? `SELECT role, content, CAST(role AS BLOB) AS role_bytes, CAST(content AS BLOB) AS content_bytes FROM messages
+             WHERE session_id=? AND active=1 AND role IN ('user','assistant') AND content IS NOT NULL AND content!=''
+             ORDER BY timestamp DESC,id DESC LIMIT 32`
+        : `SELECT role, content_json AS content, CAST(role AS BLOB) AS role_bytes, CAST(content_json AS BLOB) AS content_bytes FROM messages
+             WHERE session_id=? ORDER BY created_timestamp DESC,id DESC LIMIT 16`;
+      for (const row of statement(db, sql).all(hermes ? id : storage.selector)) {
+        const role = sqlText(row.role, row.role_bytes), raw = sqlText(row.content, row.content_bytes);
+        if (!conversationRoles.has(role) || raw == null) continue;
+        push(candidates, role, hermes ? raw : jsonColumn(raw));
+        if (candidates.length >= maxCandidates) break;
+      }
+    }
+    return candidates;
+  }, metrics)).result;
+}
+
+export function readLatestCandidates(locator, metrics) {
+  if (locator.harness === 'hermes' || (locator.storage.kind === 'sqlite' && ['opencode', 'goose'].includes(locator.harness))) return storeLatest(locator, metrics);
+  return locator.storage.kind === 'file' ? readFileLatest(locator.storage.path, locator.harness, metrics) : Promise.resolve([]);
+}