@better-than-coca/dsh-session-handoff 0.0.0-stage → 0.5.3

package/cordis.patch.yml

@@ -0,0 +1,31 @@
+# The handoff needs a fact-dense summarizer reachable from the ROOT context.
+# Compaction backends live inside each agent preset's isolated group, where
+# root-level code cannot reach them, so this bundle mounts its own instance.
+#
+# This entry is a summarizer host, not a compactor: `auto: false` means it never
+# joins automatic pressure handling, and the handoff path calls the engine's
+# summarize() directly WITHOUT committing anything back into the session. The
+# outgoing session is therefore never mutated.
+#
+# It is ADDED, never a replacement: no host entry is disabled, so a failure here
+# degrades the handoff feature only.
+- insert:
+    - id: handoff-compaction-root
+      name: '@better-than-coca/dsh-session-handoff/summary-engine'
+      config:
+        auto: false
+        thresholdRatio: 0.8
+        retainRatio: 0.16
+        maxTokens: 8192
+
+    - id: session-handoff
+      name: '@better-than-coca/dsh-session-handoff'
+      disabled: true
+      config:
+        mode: ask
+        dryRun: true
+        askRatio: 0.55
+        autoRatio: 0.75
+        minRatio: 0.3
+        maxHandoffsPerSession: 1
+        includeHistoryTool: true

package/lib/archive.js

@@ -0,0 +1,224 @@
+/**
+ * Parent-session archive access.
+ *
+ * A genuine-new-session handoff never copies the parent log: the child receives
+ * one injected checkpoint, and every concrete detail stays in the parent's own
+ * append-only log. That makes the parent log a first-class read dependency, so
+ * this module owns locating it, decoding it, and remembering which parent a
+ * child came from.
+ *
+ * Everything here is read-only with respect to session logs. The only writes are
+ * this plugin's own handoff records under <dsh home>/handoff.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import zlib from 'node:zlib';
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+const LOG_NAME = 'session.v4.jsonl.zstd';
+/** How many frames a decode may merge before the file is treated as unreadable. */
+const MAX_FRAMES = 200000;
+
+/** DSH home. Overridable so tests never touch the real profile. */
+function home() {
+    const override = process.env.DSH_SESSION_HANDOFF_HOME;
+    return override === undefined || override === '' ? join(homedir(), '.dsh') : override;
+}
+
+export function sessionsRoot() {
+    return join(home(), 'sessions');
+}
+
+export function handoffRoot() {
+    return join(home(), 'handoff');
+}
+
+/**
+ * Find the durable log of one session, wherever its workspace directory sits.
+ * @param sessionId - session identity.
+ * @returns absolute path, or undefined when the log is absent.
+ */
+export function locateSessionLog(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId === '') return undefined;
+    const root = sessionsRoot();
+    if (!existsSync(root)) return undefined;
+    let workspaces;
+    try {
+        workspaces = readdirSync(root, { withFileTypes: true });
+    } catch {
+        return undefined;
+    }
+    for (const entry of workspaces) {
+        if (!entry.isDirectory()) continue;
+        const candidate = join(root, entry.name, sessionId, LOG_NAME);
+        if (existsSync(candidate)) return candidate;
+    }
+    return undefined;
+}
+
+/**
+ * Decode an append-only zstd file: every append is its own frame, and a single
+ * decompress call only yields the first one.
+ * @param buffer - raw file bytes.
+ * @returns concatenated UTF-8 payload.
+ */
+export function decodeFrames(buffer) {
+    const offsets = [];
+    for (let index = 0; index + 4 <= buffer.length; index += 1) {
+        if (buffer.compare(ZSTD_MAGIC, 0, 4, index, index + 4) === 0) {
+            offsets.push(index);
+            if (offsets.length > MAX_FRAMES) break;
+        }
+    }
+    if (offsets.length === 0) return buffer.toString('utf8');
+    const parts = [];
+    for (let index = 0; index < offsets.length; index += 1) {
+        const end = index + 1 < offsets.length ? offsets[index + 1] : buffer.length;
+        try {
+            parts.push(zlib.zstdDecompressSync(buffer.subarray(offsets[index], end)).toString('utf8'));
+        } catch {
+            // A partially written trailing frame must not poison the rest.
+        }
+    }
+    return parts.join('');
+}
+
+const logCache = new Map();
+
+/**
+ * Read the durable events of one archived session.
+ * @param sessionId - session identity.
+ * @returns parsed events, or an empty array when the log is missing.
+ */
+export function readSessionEvents(sessionId) {
+    const path = locateSessionLog(sessionId);
+    if (path === undefined) return [];
+    let stats;
+    try {
+        stats = statSync(path);
+    } catch {
+        return [];
+    }
+    const cached = logCache.get(path);
+    if (cached !== undefined && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) return cached.events;
+    let buffer;
+    try {
+        buffer = readFileSync(path);
+    } catch {
+        return [];
+    }
+    if (typeof zlib.zstdDecompressSync !== 'function') return [];
+    const events = [];
+    for (const line of decodeFrames(buffer).split('\n')) {
+        if (line.trim() === '') continue;
+        try {
+            events.push(JSON.parse(line));
+        } catch {
+            // Skip a torn line rather than failing the whole archive.
+        }
+    }
+    logCache.set(path, { mtimeMs: stats.mtimeMs, size: stats.size, events });
+    return events;
+}
+
+/**
+ * The waiting checkpoint.
+ *
+ * A handoff does not create a session: the host hides sessions with no events and
+ * the plugin cannot write into one it did not create through the UI. Instead the
+ * checkpoint waits here, and the next brand-new conversation the user opens picks
+ * it up on its first prompt.
+ */
+function pendingPath() {
+    return join(handoffRoot(), 'pending.json');
+}
+
+export function writePending(record) {
+    mkdirSync(handoffRoot(), { recursive: true });
+    writeFileSync(pendingPath(), JSON.stringify(record, null, 2), 'utf8');
+    return pendingPath();
+}
+
+export function readPending() {
+    const path = pendingPath();
+    if (!existsSync(path)) return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Record which conversation took the waiting checkpoint.
+ * @param sessionId - session that received it.
+ * @returns the updated record, or undefined when nothing was pending.
+ */
+export function consumePending(sessionId) {
+    const record = readPending();
+    if (record === undefined) return undefined;
+    const next = { ...record, consumedBy: sessionId, consumedAt: Date.now() };
+    writeFileSync(pendingPath(), JSON.stringify(next, null, 2), 'utf8');
+    return next;
+}
+
+/** Drop a waiting checkpoint without using it. */
+export function clearPending() {
+    const path = pendingPath();
+    if (!existsSync(path)) return false;
+    try {
+        rmSync(path, { force: true });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function recordPath(childId) {
+    return join(handoffRoot(), childId + '.json');
+}
+
+/**
+ * Persist the handoff record that tells a child where its parent archive is.
+ * @param record - handoff identity, checkpoint text, and measurement.
+ * @returns the absolute record path.
+ */
+export function writeHandoff(record) {
+    mkdirSync(handoffRoot(), { recursive: true });
+    const path = recordPath(record.childId);
+    writeFileSync(path, JSON.stringify(record, null, 2), 'utf8');
+    return path;
+}
+
+/**
+ * Read the handoff record of one child session.
+ * @param childId - child session identity.
+ * @returns the record, or undefined when this session was not handed off to.
+ */
+export function readHandoff(childId) {
+    if (typeof childId !== 'string' || childId === '') return undefined;
+    const path = recordPath(childId);
+    if (!existsSync(path)) return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Rewrite a handoff record after its checkpoint was injected into the child.
+ * The record is kept: it is the child's only pointer back to its parent archive.
+ * @param childId - child session identity.
+ * @param patch - fields to merge.
+ */
+export function updateHandoff(childId, patch) {
+    const record = readHandoff(childId);
+    if (record === undefined) return undefined;
+    const next = { ...record, ...patch };
+    writeFileSync(recordPath(childId), JSON.stringify(next, null, 2), 'utf8');
+    return next;
+}
+

package/lib/checkpoint.js

@@ -0,0 +1,20 @@
+/**
+ * Checkpoint framing.
+ *
+ * The exact preamble and tags the host uses for its own compaction checkpoints,
+ * so a handed-off session treats the injected text as established background
+ * rather than as a request it should answer.
+ */
+
+export const SUMMARY_OPEN_TAG = '<compacted-summary>';
+export const SUMMARY_CLOSE_TAG = '</compacted-summary>';
+export const CHECKPOINT_PREAMBLE = 'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.';
+
+/**
+ * Wrap checkpoint text in the host's framing.
+ * @param summaryText - the generated checkpoint body.
+ * @returns framed text ready to inject or append.
+ */
+export function frameCheckpoint(summaryText) {
+    return [CHECKPOINT_PREAMBLE, '', SUMMARY_OPEN_TAG, summaryText, SUMMARY_CLOSE_TAG].join('\n');
+}

package/lib/config.js

@@ -0,0 +1,90 @@
+/**
+ * Configuration resolution and validation for dsh-session-handoff.
+ * Every value is validated once at plugin load; a bad value never throws into
+ * the host loader, it falls back to the documented default and is reported.
+ */
+
+export const DEFAULTS = Object.freeze({
+    /** off | ask | auto */
+    mode: 'ask',
+    /** Safety default: only report what would happen. */
+    dryRun: true,
+    /** Ratio of the model context window at which the model is asked to check in. */
+    askRatio: 0.55,
+    /** Ratio at which auto mode performs the handoff without asking. */
+    autoRatio: 0.75,
+    /** Never hand off below this ratio, even if requested. */
+    minRatio: 0.3,
+    /** Hard cap: refuse further handoffs once reached for the same session. */
+    maxHandoffsPerSession: 1,
+    /** Register the handoff_history lookup tool. */
+    includeHistoryTool: true,
+    /** Open a brand-new session and continue there once the checkpoint is parked. */
+    autoOpenSession: true,
+    /** Minimum gap between two "context is filling up" notices. */
+    noticeCooldownMs: 10 * 60 * 1000,
+    /** Timeout for the summarization request that builds the checkpoint. */
+    summarizeTimeoutMs: 180000
+});
+
+const RATIO_KEYS = ['askRatio', 'autoRatio', 'minRatio'];
+
+function isRatio(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 && value < 1;
+}
+
+/**
+ * Merge user configuration over the defaults, rejecting invalid values.
+ * @param raw - configuration object supplied by the loader.
+ * @param warn - reporter used for every rejected value.
+ * @returns a frozen resolved configuration.
+ */
+export function resolveConfig(raw, warn = () => {}) {
+    const input = raw !== null && typeof raw === 'object' ? raw : {};
+    const resolved = { ...DEFAULTS };
+
+    if (input.mode !== undefined) {
+        if (input.mode === 'off' || input.mode === 'ask' || input.mode === 'auto') resolved.mode = input.mode;
+        else warn('mode must be one of off|ask|auto; using ' + DEFAULTS.mode);
+    }
+    if (input.dryRun !== undefined) {
+        if (typeof input.dryRun === 'boolean') resolved.dryRun = input.dryRun;
+        else warn('dryRun must be a boolean; using ' + DEFAULTS.dryRun);
+    }
+    for (const key of RATIO_KEYS) {
+        if (input[key] === undefined) continue;
+        if (isRatio(input[key])) resolved[key] = input[key];
+        else warn(key + ' must be a number in (0, 1); using ' + DEFAULTS[key]);
+    }
+    if (!(resolved.askRatio < resolved.autoRatio)) {
+        warn('askRatio must be lower than autoRatio; keeping defaults');
+        resolved.askRatio = DEFAULTS.askRatio;
+        resolved.autoRatio = DEFAULTS.autoRatio;
+    }
+    if (resolved.minRatio > resolved.askRatio) resolved.minRatio = resolved.askRatio;
+
+    if (input.includeHistoryTool !== undefined) {
+        if (typeof input.includeHistoryTool === 'boolean') resolved.includeHistoryTool = input.includeHistoryTool;
+        else warn('includeHistoryTool must be a boolean; using ' + DEFAULTS.includeHistoryTool);
+    }
+    if (input.autoOpenSession !== undefined) {
+        if (typeof input.autoOpenSession === 'boolean') resolved.autoOpenSession = input.autoOpenSession;
+        else warn('autoOpenSession must be a boolean; using ' + DEFAULTS.autoOpenSession);
+    }
+    if (input.maxHandoffsPerSession !== undefined) {
+        const value = input.maxHandoffsPerSession;
+        if (Number.isSafeInteger(value) && value >= 0) resolved.maxHandoffsPerSession = value;
+        else warn('maxHandoffsPerSession must be a non-negative integer; using ' + DEFAULTS.maxHandoffsPerSession);
+    }
+    if (input.noticeCooldownMs !== undefined) {
+        const value = input.noticeCooldownMs;
+        if (Number.isFinite(value) && value >= 0) resolved.noticeCooldownMs = value;
+        else warn('noticeCooldownMs must be a non-negative number; using ' + DEFAULTS.noticeCooldownMs);
+    }
+    const timeout = input.summarizeTimeoutMs ?? input.compactTimeoutMs;
+    if (timeout !== undefined) {
+        if (Number.isSafeInteger(timeout) && timeout > 0) resolved.summarizeTimeoutMs = timeout;
+        else warn('summarizeTimeoutMs must be a positive integer; using ' + DEFAULTS.summarizeTimeoutMs);
+    }
+    return Object.freeze(resolved);
+}

package/lib/debug.js

@@ -0,0 +1,13 @@
+/**
+ * Opt-in trace log used while validating the handoff chain.
+ * Enabled only when DSH_SESSION_HANDOFF_DEBUG points at a file.
+ */
+import { appendFileSync } from 'node:fs';
+
+export function debugLog(message) {
+    const target = process.env.DSH_SESSION_HANDOFF_DEBUG;
+    if (target === undefined || target === '') return;
+    try {
+        appendFileSync(target, new Date().toISOString() + ' ' + message + '\n');
+    } catch {}
+}

package/lib/handoff.js

@@ -0,0 +1,178 @@
+/**
+ * The handoff transaction.
+ *
+ * The parent is never mutated: its surface, its context window, and its log stay
+ * exactly as they were, which is what makes it a usable archive. The checkpoint
+ * does not go into a session created by this plugin either — the host hides
+ * sessions that hold no events, and a plugin cannot write into one it did not open
+ * through the UI. So the checkpoint waits in a pending record, and the next
+ * brand-new conversation picks it up on its first prompt.
+ */
+
+import { readPressure, formatPressure } from './pressure.js';
+import { sessionEvents } from './history.js';
+import { debugLog } from './debug.js';
+import { rootSummaryEngine } from './summary-engine.js';
+import { summaryTokensOf, routeCard } from './route-card.js';
+import { frameCheckpoint } from './checkpoint.js';
+import { writePending } from './archive.js';
+
+/**
+ * Resolve a service from the agent's own composition first, then the plugin's
+ * context.
+ * @param agent - live agent whose context carries the composed services.
+ * @param ctx - the plugin's own context.
+ * @param name - service name.
+ * @returns the service instance, or undefined.
+ */
+function serviceFor(agent, ctx, name) {
+    const scoped = agent?.ctx;
+    if (scoped !== undefined && typeof scoped.get === 'function') {
+        const fromAgent = scoped.get(name);
+        if (fromAgent !== undefined) return fromAgent;
+    }
+    return ctx.get(name);
+}
+
+/**
+ * Collect the reasons a handoff must be refused right now.
+ * @param session - session proposing to hand off.
+ * @param cfg - resolved configuration.
+ * @param state - plugin runtime state.
+ * @returns an array of human-readable refusal reasons (empty means allowed).
+ */
+export function refusalReasons(session, cfg, state) {
+    const reasons = [];
+    const header = session?.header ?? {};
+    if (typeof header.delegationDepth === 'number' && header.delegationDepth > 0) reasons.push('subagent sessions cannot hand off');
+    const used = state.counts.get(session) ?? 0;
+    if (used >= cfg.maxHandoffsPerSession) reasons.push('handoff limit reached (' + used + '/' + cfg.maxHandoffsPerSession + ') for this session');
+    const events = sessionEvents(session);
+    if (events.length === 0) reasons.push('session log is empty');
+    return reasons;
+}
+
+/**
+ * Rebuild the exact message list the model currently sees, the same way the
+ * host's compactor does before summarizing. Only public session methods are
+ * used, so this stays valid if the compactor's internals move.
+ * @param session - live session.
+ * @returns `{ messages, tools? }`, or null when the surface is unreadable.
+ */
+export function summarizationInput(session) {
+    const nodes = session?.surface?.nodes;
+    if (!Array.isArray(nodes) || nodes.length === 0) return null;
+    if (typeof session.eventAt !== 'function' || typeof session.deriveEventMessage !== 'function') return null;
+    const headEvent = session.eventAt(nodes[0]);
+    const system = headEvent?.type === 'system/message' ? session.deriveEventMessage(headEvent) : null;
+    const systemHead = system === null || system === undefined ? null : system;
+    const regionSeqs = systemHead === null ? nodes : nodes.slice(1);
+    const messages = [];
+    for (const seq of regionSeqs) {
+        const event = session.eventAt(seq);
+        if (event === undefined || event === null) continue;
+        const message = session.deriveEventMessage(event);
+        if (message !== null && message !== undefined) messages.push(message);
+    }
+    if (messages.length === 0) return null;
+    const header = typeof session.requestHeader === 'function' ? session.requestHeader() : undefined;
+    return {
+        ...(header?.tools === undefined ? {} : { tools: [...header.tools] }),
+        messages: systemHead === null ? messages : [systemHead, ...messages]
+    };
+}
+
+/**
+ * Price the span the checkpoint replaces.
+ * @param ctx - host context exposing `tokenMeter`.
+ * @param session - session being measured.
+ * @returns shadowed token count, or null when the meter is unavailable.
+ */
+export function shadowedTokens(ctx, session) {
+    try {
+        const meter = ctx.get('tokenMeter');
+        if (meter === undefined || typeof meter.measure !== 'function') return null;
+        const nodes = meter.measure(session)?.nodes ?? [];
+        let total = 0;
+        for (const node of nodes) if (Number.isFinite(node.tokens)) total += node.tokens;
+        return total > 0 ? total : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Execute one handoff: summarize the parent's surface and park the checkpoint for
+ * the next new conversation.
+ * @param ctx - host context.
+ * @param cfg - resolved configuration.
+ * @param state - plugin runtime state.
+ * @param agent - the live agent whose session is handing off.
+ * @returns a result record; never throws.
+ */
+export async function performHandoff(ctx, cfg, state, agent) {
+    const session = agent?.session;
+    if (session === undefined || session === null) return { ok: false, reason: 'no live session' };
+    if (state.busy.has(session)) return { ok: false, reason: 'another handoff is already running' };
+
+    state.busy.add(session);
+    try {
+        const reading = readPressure(ctx, session);
+        if (reading === null) return { ok: false, reason: 'context pressure is unmeasurable' };
+        if (reading.ratio < cfg.minRatio) {
+            return { ok: false, reason: 'pressure ' + formatPressure(reading) + ' is below minRatio ' + cfg.minRatio };
+        }
+
+        const engine = rootSummaryEngine();
+        if (engine === undefined || typeof engine.summarize !== 'function') {
+            return { ok: false, reason: 'the handoff summarizer is not mounted; nothing was written' };
+        }
+
+        const input = summarizationInput(session);
+        if (input === null) return { ok: false, reason: 'session surface is empty or unreadable; nothing was written' };
+
+        debugLog('performHandoff: summarize start messages=' + input.messages.length);
+        const summarized = await engine.summarize(input, agent, AbortSignal.timeout(cfg.summarizeTimeoutMs));
+        debugLog('performHandoff: summarize done');
+
+        const blocks = Array.isArray(summarized?.summary) ? summarized.summary : [];
+        const summaryText = blocks
+            .map((block) => (typeof block?.text === 'string' ? block.text : ''))
+            .join('\n')
+            .trim();
+        if (summaryText === '') return { ok: false, reason: 'the summarizer produced an empty checkpoint; nothing was written' };
+
+        const summaryTokens = summaryTokensOf(summaryText, summarized?.usage);
+        const shadowed = shadowedTokens(ctx, session) ?? reading.used;
+        const stats = { shadowed, summaryTokens, ratio: shadowed / summaryTokens };
+        const checkpoint = frameCheckpoint(summaryText) + '\n\n' + routeCard(null, { ...stats, parentSession: session.id });
+        const path = writePending({
+            version: 1,
+            parentSession: session.id,
+            createdAt: Date.now(),
+            summary: summaryText,
+            checkpoint,
+            stats,
+            ...(summarized?.provider === undefined ? {} : { provider: summarized.provider }),
+            ...(summarized?.model === undefined ? {} : { model: summarized.model })
+        });
+        debugLog('performHandoff: pending written ' + path);
+
+        state.counts.set(session, (state.counts.get(session) ?? 0) + 1);
+        state.handoffs.set(session, { at: Date.now(), before: reading, stats, pending: true });
+        ctx.logger.info(
+            'session-handoff: checkpoint ready for ' + session.id +
+            ' (checkpoint ' + summaryTokens + ' tokens, ratio ' + Math.round(stats.ratio) + ':1, parent untouched, before=' + formatPressure(reading) + ')'
+        );
+        return { ok: true, pending: true, stats, before: reading };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const cause = error instanceof Error ? error.cause : undefined;
+        const causeText = cause instanceof Error ? cause.message : cause === undefined ? '' : String(cause);
+        debugLog('performHandoff threw: ' + message + (causeText === '' ? '' : ' <- cause: ' + causeText));
+        ctx.logger.warn('session-handoff: handoff aborted: ' + message);
+        return { ok: false, reason: message };
+    } finally {
+        state.busy.delete(session);
+    }
+}

package/lib/history.js

@@ -0,0 +1,103 @@
+/**
+ * Read and search the raw event log of the current session.
+ *
+ * A forked child inherits the parent's raw events verbatim, so the child can
+ * recover any earlier detail without cross-session search: the route points at
+ * seq numbers that exist in its own log. This module is the lookup half of
+ * that route and needs no SQLite full-text index.
+ */
+
+/**
+ * Snapshot the raw event log of a session across the two supported shapes.
+ * @param session - target session.
+ * @returns the durable event array, possibly empty.
+ */
+export function sessionEvents(session) {
+    if (session === undefined || session === null) return [];
+    if (typeof session.snapshotEvents === 'function') {
+        const events = session.snapshotEvents();
+        return Array.isArray(events) ? events : [];
+    }
+    if (Array.isArray(session.events)) return session.events;
+    return [];
+}
+
+/**
+ * Extract the human-readable text of one event.
+ * @param event - durable session event.
+ * @returns text blocks joined by newlines, or a JSON fallback.
+ */
+export function eventText(event) {
+    const data = event?.data;
+    if (data === undefined || data === null) return '';
+    const parts = [];
+    const message = data.message ?? data;
+    const content = message?.content;
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            if (block?.type === 'text' && typeof block.text === 'string' && block.text !== '') parts.push(block.text);
+            else if (block?.type === 'reasoning' && typeof block.text === 'string' && block.text !== '') parts.push(block.text);
+        }
+    }
+    if (parts.length > 0) return parts.join('\n');
+    if (typeof data.text === 'string') return data.text;
+    try {
+        return JSON.stringify(data);
+    } catch {
+        return '';
+    }
+}
+
+function snippet(text, query, radius) {
+    const flat = text.replace(/\s+/g, ' ');
+    if (query === '') return flat.slice(0, radius * 2);
+    const at = flat.toLowerCase().indexOf(query.toLowerCase());
+    if (at < 0) return flat.slice(0, radius * 2);
+    const start = Math.max(0, at - radius);
+    return (start > 0 ? '…' : '') + flat.slice(start, at + query.length + radius) + '…';
+}
+
+/**
+ * Literal substring search across the raw event log.
+ * @param events - event array from {@link sessionEvents}.
+ * @param query - literal text to look for (case-insensitive).
+ * @param limit - maximum number of hits.
+ * @returns matching lines, newest last.
+ */
+export function searchEvents(events, query, limit) {
+    const hits = [];
+    for (let index = events.length - 1; index >= 0 && hits.length < limit; index -= 1) {
+        const event = events[index];
+        const text = eventText(event);
+        if (text === '') continue;
+        if (text.toLowerCase().indexOf(query.toLowerCase()) < 0) continue;
+        hits.push({ seq: event.seq, type: event.type, text: snippet(text, query, 120) });
+    }
+    return hits.reverse();
+}
+
+/**
+ * Read one event in full plus optional neighbours.
+ * @param events - event array from {@link sessionEvents}.
+ * @param seq - target event sequence number.
+ * @param before - number of preceding events to include.
+ * @param after - number of following events to include.
+ * @returns rendered text, or an explanation when the seq is absent.
+ */
+export function readEventDetail(events, seq, before, after) {
+    const target = events.find((event) => event.seq === seq);
+    if (target === undefined) return 'No event at seq ' + seq + ' in this session.';
+    const first = Math.max(0, seq - before);
+    const last = Math.min(events.length - 1, seq + after);
+    const lines = [];
+    for (let index = first; index <= last; index += 1) {
+        const event = events[index];
+        if (event === undefined) continue;
+        const marker = event.seq === seq ? '>>' : '  ';
+        const body = event.seq === seq
+            ? '\n' + (eventText(event) || JSON.stringify(event.data)).slice(0, 6000)
+            : ' ' + snippet(eventText(event) || JSON.stringify(event.data), '', 90);
+        lines.push(marker + ' [' + event.seq + '] ' + event.type + body);
+    }
+    return lines.join('\n');
+}