@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/grok.js

@@ -0,0 +1,421 @@
+// The Grok Build source: a Grok Build session log becomes the same capture records a Claude Code transcript does.
+//
+// FIXTURE-DERIVED: written from the public source of the CLI (github.com/xai-org/grok-build @ 2bdd1d6a6369de0e8c68132ea4539e9abd9e14a8, Apache-2.0, Rust,
+// under crates/codegen/) and the Agent Client Protocol schema it implements (github.com/agentclientprotocol/agent-client-protocol @ 0e486bcd, schema/v1/
+// schema.json), not from a live store. Nothing was copied; the reader is original. No vendor text promises the on-disk format (the user guide, `17-sessions.md`,
+// steers readers to `grok usage` instead of the files), so `docs/sessions-store.md` says what a live run would still have to prove.
+//
+// Where it reads from (`grokRoot`): `$GROK_HOME`, else `~/.grok` (`%USERPROFILE%\.grok` on Windows) (xai-dirs lib.rs:51-57; user guide 17-sessions.md:18). A
+// session is `sessions/<percent-encoded cwd>/<session id>/` (17-sessions.md:22-40), holding
+//   summary.json  {info: {id, cwd}, created_at, current_model_id, num_messages, session_kind?, forked_at?}: the authoritative cwd (the folder name can be a hash for a
+//                 long path), the model the session ended on, and what kind of session it is
+//   updates.jsonl "the authoritative conversation log" (17-sessions.md:42): one `{timestamp, method, params: {sessionId, update}}` per line, `timestamp` epoch
+//                 SECONDS (serde default 0), `update` an ACP SessionUpdate tagged by `sessionUpdate`:
+//     user_message_chunk   content {type: "text", text}: the operator's prompt (a block that is an image counts as the turn and is written as an image block with no data, turn.rs:960-962, storage/mod.rs:416); chunks merge into one prompt until the agent speaks or `_meta.promptIndex`
+//                          changes, including between marked and unmarked (turn.rs:890-895, storage/mod.rs:1009, :1038-1039). `_meta.hostTurn` (a slash command's turn), `_meta.hideFromScrollback` (a turn the harness started:
+//                          a finished task, subagent, workflow, notification, or goal check, turn.rs:328, :896-901) and `_meta.interjection` (a mid-turn steer whose text is a
+//                          model-facing frame) are not prompts (storage/mod.rs:966, :974); the first two end the turn, and `hostTurn` marks an agent chunk as well
+//                          (acp_session.rs:1353-1372), whose text is dropped as upstream's own rebuilders do (storage/mod.rs:429-432)
+//     agent_message_chunk  content {type: "text", text}: the response, chunks merged
+//     tool_call            {toolCallId, title, kind, rawInput}: `title` IS the tool's name (tool_calls.rs:1487), except a backend-hosted search, which is titled for display ("Web search:") and named by `rawInput.variant`
+//                          when `rawInput.backend` is true (tool_dispatch.rs:94-105). A model-issued call always has `kind` other here (tool_calls.rs:1488); its real kind
+//                          arrives only on a later tool_call_update (tool_calls.rs:2734). A shell call is therefore a name in SHELL_TOOLS, or the user's `!cmd`, the one path that
+//                          writes `kind` execute on the call itself (`bash-mode-<uuid>` titled "Execute `cmd`", tool_dispatch.rs:213, :245-246)
+//     tool_call_update     {toolCallId, status, content[], rawOutput}: the outcome. A shell call's `rawOutput` is `{type: "Bash", exit_code, output: bytes,
+//                          output_for_prompt, signal, timed_out, current_dir}` (types/output.rs:384-405); the reader takes the `output` bytes, because on the model-issued
+//                          path `output_for_prompt` is the formatted prompt (`exit: N` header or the concise tool's `Exit code: N` fence, bash/mod.rs:2246). The agent path marks a shell call `failed` only on a timeout
+//                          or a signal, so exit 2 arrives `completed` (acp_conversion.rs:241-250): the exit code decides, not the status. Any other tool's error text is its
+//                          `content[]` text, except a failed MCP call, which has none and keeps its text in `rawOutput.output.Error` (acp_conversion.rs:325-338); `list_dir`, `grep_files`,
+//                          `get_task_output`, `kill_task`, and a failed backend-hosted search carry neither (Known gaps). A `rawOutput` is otherwise a tagged wrapper that is never the error line. `current_dir` is the cwd the writer resolved BEFORE the command ran
+//                          (grok_build/bash/mod.rs:1876, stored at :2240), so a `cd` inside a command never shows; it moves only when the session's own folder moved
+//   usage.json    {turns: [{endedAt, inputTokens, outputTokens, cachedReadTokens, cacheCreationTokens, reasoningTokens, primaryModelId}]} (usage_file.rs:10-80): per-TURN
+//                 deltas (`session` is their sum, :230-300), so every turn is added once. `inputTokens` is the FULL prompt, cache reads and writes included (xai-grok-sampling-types
+//                 conversation.rs:771-773: `prompt_tokens` "is always the FULL prompt size"), and capture's fields are disjoint, so the uncached part is
+//                 input - cache reads - cache writes. A turn's totals land on the last response before its `endedAt` (turn numbers are not used: a rewind renumbers).
+// A fork copies its parent's lines with their old timestamps and its parent's usage.json (copy.rs:229, persistence.rs:2608); `summary.forked_at` is the cut, so
+// older lines and turns are not this session's. A subagent (`session_kind` subagent or subagent_fork) is its own session in the same tree: it is not listed, and the
+// parent's `task` call is the record. `events.jsonl` (telemetry), `chat_history.jsonl` (the model-facing copy), and the rest of the folder are not read.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, posix, win32 } from 'node:path';
+/** The Grok home for an environment; a test passes its own so it never reads the real one. */
+export const grokRoot = (env, home = homedir()) => {
+    const set = env.GROK_HOME;
+    return set === undefined || set === '' ? join(home, '.grok') : set;
+};
+const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const str = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+const parse = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const SAFE_ID = /^(?!\.+$)[A-Za-z0-9._-]+$/;
+const UPDATES = 'updates.jsonl';
+const SUMMARY = 'summary.json';
+const USAGE = 'usage.json';
+/** A subagent is its own session in the same tree (`session_kind`, persistence.rs:3016, subagent/mod.rs:1136). */
+const SUBAGENT_KINDS = new Set(['subagent', 'subagent_fork']);
+/** The tools that run a command; a call of `kind` execute is one whatever its name. */
+const SHELL_TOOLS = new Set(['run_terminal_cmd', 'run_terminal_command', 'bash']);
+/** The tools that change files, named so a failed edit is still an edit. Their path keys are `file_path` (`filePath` for `edit`) and, for `apply_patch`, the `*** <Add|Update|Delete> File:` headers of `patch`. */
+const EDIT_TOOLS = new Set(['search_replace', 'apply_patch', 'edit', 'write', 'hashline_edit']);
+/** The backend-hosted searches' `rawInput.variant`, by the tool name each stands for (acp_session_impl/tool_dispatch.rs:94-105). */
+const BACKEND_NAMES = new Map([['WebSearch', 'web_search'], ['XSearch', 'x_search']]);
+const PATCH_HEADER = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
+/** An error's message with `file` cut to its base name, so a reason that is logged names no folder. */
+const reasonOf = (error, file) => (error instanceof Error ? error.message : String(error)).split(file).join(basename(file));
+const missing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+/** A JSON object file; undefined when it does not exist, a throw when it is not an object. */
+const readObject = async (file) => {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+    const value = parse(text);
+    if (!isObj(value))
+        throw new Error(`${basename(file)} is not a JSON object`);
+    return value;
+};
+/** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
+export const grokBadLines = (text) => text.split('\n').filter((raw) => raw.trim() !== '' && parse(raw) === undefined);
+/** A time as ISO text, or undefined when it is not an absolute time after 2000. */
+const isoOf = (ms) => (ms >= Date.parse('2000-01-01T00:00:00Z') ? new Date(ms).toISOString() : undefined);
+const timeOf = (value) => {
+    const text = str(value);
+    const ms = text === undefined ? NaN : Date.parse(text);
+    return Number.isNaN(ms) || isoOf(ms) === undefined ? undefined : ms;
+};
+/** A failed shell call's error line: the output, but a nonzero exit says so first; a negative one is no exit status, so the output stands. */
+const failureOf = (exit, text) => (exit < 0 && text.trim() !== '' ? text : `Exit code ${String(exit)}\n${text}`);
+/** The text parts of a tool update's `content[]` (ACP ToolCallContent `content`/`text`), the error text of a tool that failed. */
+const contentText = (update) => {
+    const parts = (Array.isArray(update.content) ? update.content : []).flatMap((part) => (isObj(part) && part.type === 'content' && isObj(part.content) && str(part.content.text) !== undefined ? [String(part.content.text)] : []));
+    return parts.length === 0 ? undefined : parts.join('\n');
+};
+/** An ANSI CSI sequence (ESC [ parameters, intermediates, final byte); the output bytes are the raw terminal output. */
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, 'g');
+/**
+ * A shell call's output: the `output` bytes (always present, types/output.rs:385) with ANSI sequences stripped, else the update's text. `output_for_prompt` is not read:
+ * on the model-issued path it is the formatted prompt, `exit: N [annotations]\n<output>` (grok_build/bash/mod.rs:2246, :386-417) or the concise tool's `Exit code: N` and a
+ * fenced block (grok_build_concise/bash.rs:37-58, :187), a header the error line must not become; only the user's `!cmd` keeps it plain (tool_dispatch.rs:304).
+ */
+const shellText = (raw, update) => {
+    const bytes = Array.isArray(raw.output) ? raw.output.filter((byte) => typeof byte === 'number') : [];
+    return str(Buffer.from(bytes).toString('utf8').replace(ANSI, '')) ?? contentText(update) ?? '';
+};
+/** The files a request names: `file_path`, or `filePath` for the opencode `edit` tool (camelCase, opencode/edit/mod.rs:64, :138), or the headers of an `apply_patch` patch. */
+const requestedPaths = (input) => {
+    const path = str(input.file_path) ?? str(input.filePath);
+    if (path !== undefined)
+        return [path];
+    const patch = str(input.patch);
+    return patch === undefined ? [] : [...patch.matchAll(PATCH_HEADER)].map((match) => String(match[1]).trim());
+};
+/**
+ * A path the model named, made absolute against the session's folder. The completion's `diff` parts carry the absolute path (`absolute_path`, acp_conversion.rs:202-204),
+ * and the model's own `file_path` may be relative, so only the same form tells that two lines name one file. The folder's own style (POSIX or Windows) decides the join.
+ */
+const absolute = (path, cwd) => {
+    if (cwd === undefined || posix.isAbsolute(path) || win32.isAbsolute(path))
+        return path;
+    return (cwd.startsWith('/') ? posix : win32).join(cwd, path);
+};
+/** The files a completion reports having changed: the `diff` parts of `content[]` (ACP ToolCallContent `diff`, `path`). */
+const diffPaths = (update) => (Array.isArray(update.content) ? update.content : []).flatMap((part) => (isObj(part) && part.type === 'diff' && str(part.path) !== undefined ? [String(part.path)] : []));
+/** One session as the lines `captureSession` reads. */
+export const grokLines = (text, fallbackId, summary, usage) => {
+    const nonblank = text.split('\n').filter((raw) => raw.trim() !== '');
+    if (nonblank.length > 0 && !nonblank.some((raw) => isObj(parse(raw))))
+        throw new Error('no parseable line');
+    const info = isObj(summary.info) ? summary.info : {};
+    const model = str(summary.current_model_id);
+    const forkedAt = timeOf(summary.forked_at);
+    const lines = [];
+    const base = { sessionId: str(info.id) ?? fallbackId, ...(str(info.cwd) === undefined ? {} : { cwd: str(info.cwd) }) };
+    let at = timeOf(summary.created_at) ?? 0;
+    let sequence = 0;
+    // The prompt being read; `index` is its `_meta.promptIndex` when the chunks carry one.
+    let pending;
+    let open;
+    const responses = [];
+    const calls = new Map();
+    const resolved = new Set();
+    const stamp = (seconds) => {
+        const value = num(seconds);
+        // A missing, zero, or earlier time (the vendor's serde default is 0) says nothing about when: the latest time so far stands.
+        if (value !== undefined && value * 1000 > at)
+            at = value * 1000;
+        return at;
+    };
+    const iso = (ms) => new Date(ms).toISOString();
+    const flushPrompt = () => {
+        if (pending === undefined)
+            return;
+        sequence += 1;
+        lines.push({ ...base, type: 'user', uuid: `${fallbackId}-u${String(sequence)}`, timestamp: iso(pending.when), message: { role: 'user', content: [pending.text === '' ? { type: 'image' } : { type: 'text', text: pending.text }] } });
+        pending = undefined;
+    };
+    const response = (when) => {
+        if (open !== undefined)
+            return open;
+        sequence += 1;
+        const content = [];
+        const message = { role: 'assistant', content };
+        // Every assistant line carries a requestId (`verify --strict` needs one), and each response has its own, so its usage counts once.
+        const line = { ...base, type: 'assistant', uuid: `${fallbackId}-a${String(sequence)}`, requestId: `${fallbackId}-resp${String(sequence)}`, timestamp: iso(when), ...(model === undefined ? {} : { requestedModel: model }), message };
+        lines.push(line);
+        open = { line, message, content, at: when };
+        responses.push(open);
+        return open;
+    };
+    const result = (id, failure, when, output = '') => {
+        sequence += 1;
+        lines.push({
+            ...base,
+            type: 'user',
+            uuid: `${fallbackId}-r${String(sequence)}`,
+            timestamp: iso(when),
+            // The completion is stamped with its own time, but the call's start is not paired to it here, so no duration is claimed.
+            noDuration: true,
+            // The output follows an `Exit code 0` line, the shape a Claude Code Bash result has, so a `[branch sha]` line is still found for commit survival.
+            message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: failure !== undefined, content: failure ?? (output === '' ? '' : `Exit code 0\n${output}`) }] },
+        });
+    };
+    for (const raw of nonblank) {
+        const entry = parse(raw);
+        if (!isObj(entry) || !isObj(entry.params) || !isObj(entry.params.update))
+            continue;
+        const update = entry.params.update;
+        const kind = str(update.sessionUpdate);
+        const seconds = num(entry.timestamp);
+        // A fork's file starts with its parent's lines, each with the parent's time; the cut is the second the fork was made.
+        if (kind === undefined || (forkedAt !== undefined && seconds !== undefined && seconds > 0 && seconds < Math.floor(forkedAt / 1000)))
+            continue;
+        const when = stamp(seconds);
+        const meta = isObj(update._meta) ? update._meta : {};
+        const part = isObj(update.content) ? str(update.content.text) : undefined;
+        if (kind === 'user_message_chunk') {
+            if (meta.hostTurn === true || meta.hideFromScrollback === true) {
+                // The harness started this turn (a slash command, or a finished task, subagent, workflow, notification, or goal check): it is not the operator's prompt,
+                // and it ends the turn, so whatever the agent says next is a new response, not more of the last one.
+                flushPrompt();
+                open = undefined;
+                continue;
+            }
+            // A prompt block that is an image has no text but is still the operator's turn (storage/mod.rs:416 rebuilds it; summary.rs:51 names an "image-only message"):
+            // it takes part in the prompt boundary below, and is written as an image block with no data. Any other block type is skipped.
+            const image = isObj(update.content) && update.content.type === 'image';
+            if (meta.interjection === true || (part === undefined && !image))
+                continue;
+            // A change of `promptIndex` is a new prompt even when no reply fell between them (a prompt cancelled before its first reply, then a retry), and so is a change
+            // between marked and unmarked (the user's `!cmd` carries only a model id): upstream opens a new run on either (storage/mod.rs:1038-1039). Two unmarked chunks merge.
+            const index = num(meta.promptIndex);
+            if (pending !== undefined && index !== pending.index)
+                flushPrompt();
+            open = undefined;
+            pending = { text: (pending?.text ?? '') + (part ?? ''), when: pending?.when ?? when, index };
+        }
+        else if (kind === 'agent_message_chunk') {
+            flushPrompt();
+            if (meta.hostTurn === true) {
+                // A slash command's output is persisted as an agent chunk with the marker; upstream's own rebuilders drop it and treat it as a boundary.
+                open = undefined;
+                continue;
+            }
+            if (part === undefined)
+                continue;
+            const current = response(when);
+            const last = current.content[current.content.length - 1];
+            if (last?.type === 'text')
+                last.text = String(last.text) + part;
+            else
+                current.content.push({ type: 'text', text: part });
+        }
+        else if (kind === 'tool_call') {
+            flushPrompt();
+            const id = str(update.toolCallId);
+            const shownTitle = str(update.title);
+            if (id === undefined || shownTitle === undefined)
+                continue;
+            const current = response(when);
+            const input = isObj(update.rawInput) ? update.rawInput : {};
+            // A backend-hosted search is titled for display ("Web search:", "X search:"), with its kind in `rawInput.variant` (acp_session_impl/tool_dispatch.rs:94-105; sampling_events.rs:541-553).
+            const title = input.backend === true ? (BACKEND_NAMES.get(str(input.variant) ?? '') ?? shownTitle) : shownTitle;
+            // An MCP tool is reached two ways: titled `<server>__<tool>` itself, or through the `use_tool` wrapper, whose `rawInput.tool_name` is the qualified name
+            // (use_tool/input.rs:19-20, use_tool/mod.rs:308) and `tool_input` its arguments.
+            const target = title === 'use_tool' ? str(input.tool_name) : undefined;
+            const wrapped = target !== undefined && target.includes('__');
+            const block = {
+                type: 'tool_use',
+                id,
+                name: wrapped ? `mcp__${target}` : title.includes('__') ? `mcp__${title}` : title,
+                input: wrapped ? (isObj(input.tool_input) ? input.tool_input : {}) : input,
+            };
+            const shell = SHELL_TOOLS.has(title) || update.kind === 'execute';
+            const paths = EDIT_TOOLS.has(title) ? requestedPaths(input).map((path) => absolute(path, str(base.cwd))) : [];
+            if (shell) {
+                const command = str(input.command);
+                // The user's `!cmd` is titled "Execute `cmd`", which has no table row: it is the `bash` row's call.
+                block.native = SHELL_TOOLS.has(title) ? title : 'bash';
+                block.name = 'Bash';
+                block.input = command === undefined ? {} : { command };
+            }
+            else if (title === 'skill') {
+                // The opencode `skill` tool's input is `{name}` (opencode/skill/mod.rs:50); the table's skill.run reads `input.skill`.
+                const skill = str(input.name);
+                block.input = skill === undefined ? {} : { skill };
+            }
+            else if (EDIT_TOOLS.has(title)) {
+                const path = paths[0];
+                block.native = title;
+                block.name = 'Edit';
+                block.input = path === undefined ? {} : { file_path: path };
+            }
+            current.content.push(block);
+            calls.set(id, { block, content: current.content, shell, workdir: str(input.workdir), paths });
+        }
+        else if (kind === 'tool_call_update') {
+            const id = str(update.toolCallId);
+            const status = str(update.status);
+            const known = id === undefined ? undefined : calls.get(id);
+            // Only an outcome settles a call; a progress update leaves it `none`, and the call settles once.
+            if (id === undefined || known === undefined || resolved.has(id) || (status !== 'completed' && status !== 'failed'))
+                continue;
+            resolved.add(id);
+            open = undefined;
+            const output = isObj(update.rawOutput) ? update.rawOutput : {};
+            let failure;
+            let shown = '';
+            if (known.shell) {
+                const exit = num(output.exit_code);
+                const dir = str(output.current_dir);
+                // With a `workdir` the opencode `bash` tool reports that directory as `current_dir` (opencode/bash/mod.rs:376, :454), and the next relative `write` or `edit` still resolves against
+                // the session's own (opencode/write/mod.rs:117, opencode/edit/mod.rs:210), so only a call without one follows `current_dir`.
+                if (dir !== undefined && known.workdir === undefined)
+                    base.cwd = dir;
+                shown = shellText(output, update);
+                if (exit !== undefined && exit !== 0)
+                    failure = failureOf(exit, shown);
+                else if (status === 'failed')
+                    failure = shown === '' ? 'tool failed' : shown;
+            }
+            else if (status === 'failed') {
+                // A failed MCP call has no `content[]`: its text rides `rawOutput.output.Error` (acp_conversion.rs:325-338; types/output.rs:1112-1158).
+                const mcp = output.type === 'MCP' && isObj(output.output) ? str(output.output.Error) : undefined;
+                failure = contentText(update) ?? mcp ?? 'tool failed';
+            }
+            result(id, failure, when, shown);
+            if (EDIT_TOOLS.has(str(known.block.native) ?? '')) {
+                // The first file rides the call's own block; any other gets its own, in the same response.
+                const paths = [...new Set([...known.paths, ...diffPaths(update)])];
+                if (paths[0] !== undefined)
+                    known.block.input = { file_path: paths[0] };
+                for (const [index, path] of paths.slice(1).entries()) {
+                    const extra = `${id}:${String(index + 2)}`;
+                    known.content.push({ type: 'tool_use', id: extra, name: 'Edit', native: known.block.native, input: { file_path: path } });
+                    result(extra, failure, when);
+                }
+            }
+        }
+    }
+    flushPrompt();
+    // Each turn's totals land on the last response before the turn ended, else the first. `turns[]` are per-turn deltas (usage_file.rs:230-300), so each is added
+    // once; a fork copied its parent's turns, which end at or before `forked_at`.
+    const turns = (Array.isArray(usage?.turns) ? usage.turns : []).flatMap((turn) => {
+        const ended = isObj(turn) ? timeOf(turn.endedAt) : undefined;
+        return isObj(turn) && ended !== undefined && (forkedAt === undefined || ended > forkedAt) ? [{ turn, ended }] : [];
+    });
+    const landed = new Map();
+    for (const { turn, ended } of turns.sort((a, b) => a.ended - b.ended)) {
+        const target = responses.findLast((candidate) => candidate.at <= ended) ?? responses[0];
+        if (target === undefined)
+            continue;
+        const held = landed.get(target) ?? { input: 0, read: 0, write: 0, output: 0, thinking: 0 };
+        const read = num(turn.cachedReadTokens) ?? 0;
+        const write = num(turn.cacheCreationTokens) ?? 0;
+        // `inputTokens` includes the cache reads and writes (conversation.rs:771-773), and capture's fields are disjoint, so only the uncached part is input.
+        held.input += Math.max((num(turn.inputTokens) ?? 0) - read - write, 0);
+        held.read += read;
+        held.write += write;
+        held.output += num(turn.outputTokens) ?? 0;
+        held.thinking += num(turn.reasoningTokens) ?? 0;
+        landed.set(target, held);
+        const turnModel = str(turn.primaryModelId);
+        if (turnModel !== undefined)
+            target.line.requestedModel = turnModel;
+    }
+    for (const [target, held] of landed) {
+        target.message.usage = { input_tokens: held.input, cache_read_input_tokens: held.read, cache_creation_input_tokens: held.write, output_tokens: held.output, output_tokens_details: { thinking_tokens: held.thinking } };
+    }
+    return lines;
+};
+export const openGrokStore = async (root) => {
+    const base = join(root, 'sessions');
+    const unreadable = [];
+    let folders;
+    try {
+        folders = await readdir(base, { withFileTypes: true });
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        return { sessions: [], transcript: () => Promise.reject(new Error('no sessions')), rejected: 0, unreadable: [{ file: base, reason: reasonOf(error, base) }] };
+    }
+    const sessions = [];
+    let rejected = 0;
+    for (const folder of folders.filter((candidate) => candidate.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+        let entries;
+        try {
+            entries = await readdir(join(base, folder.name), { withFileTypes: true });
+        }
+        catch (error) {
+            unreadable.push({ file: join(base, folder.name), reason: reasonOf(error, join(base, folder.name)) });
+            continue;
+        }
+        for (const entry of entries.filter((candidate) => candidate.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!SAFE_ID.test(entry.name)) {
+                rejected += 1;
+                continue;
+            }
+            const dir = join(base, folder.name, entry.name);
+            try {
+                const summary = await readObject(join(dir, SUMMARY));
+                const updates = await stat(join(dir, UPDATES));
+                // A folder with no summary or no log (a started, never-used session) is no session; a subagent is its parent's `task` call; an unused one holds nothing.
+                if (summary === undefined || (str(summary.session_kind) !== undefined && SUBAGENT_KINDS.has(String(summary.session_kind))) || summary.num_messages === 0)
+                    continue;
+                const used = await stat(join(dir, USAGE)).catch(() => undefined);
+                const info = isObj(summary.info) ? summary.info : {};
+                sessions.push({ id: entry.name, folder: str(info.cwd) ?? null, dir, size: updates.size + (used?.size ?? 0), mtimeMs: Math.floor(Math.max(updates.mtimeMs, used?.mtimeMs ?? 0)) });
+            }
+            catch (error) {
+                if (!missing(error))
+                    unreadable.push({ file: dir, reason: reasonOf(error, dir) });
+            }
+        }
+    }
+    sessions.sort((a, b) => a.mtimeMs - b.mtimeMs || a.id.localeCompare(b.id));
+    return {
+        sessions,
+        rejected,
+        unreadable,
+        transcript: async (session) => {
+            const text = await readFile(join(session.dir, UPDATES), 'utf8');
+            const summary = await readObject(join(session.dir, SUMMARY));
+            if (summary === undefined)
+                throw new Error(`${SUMMARY} is gone`);
+            const lines = [...grokLines(text, session.id, summary, await readObject(join(session.dir, USAGE))).map((line) => JSON.stringify(line)), ...grokBadLines(text)];
+            return lines.join('\n') + (lines.length === 0 ? '' : '\n');
+        },
+    };
+};

package/dist/sessions/hook-calls.d.ts

@@ -0,0 +1,3 @@
+import type { HookCall } from './schema.js';
+export declare const appendHookCall: (storeDir: string, call: HookCall) => Promise<void>;
+export declare const readHookCalls: (storeDir: string) => Promise<HookCall[]>;

package/dist/sessions/hook-calls.js

@@ -0,0 +1,47 @@
+// The hook counters: `hook-calls.jsonl`, one line per hook invocation, appended by the hook and read by `measure`.
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { paths } from './store.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const eventOf = (value) => {
+    if (value === 'session-start' || value === 'pre-tool' || value === 'post-tool' || value === 'stop' || value === 'nightly')
+        return value;
+    return undefined;
+};
+export const appendHookCall = async (storeDir, call) => {
+    await mkdir(storeDir, { recursive: true });
+    await appendFile(paths(storeDir).hookCalls, `${JSON.stringify(call)}\n`, { mode: 0o600 });
+};
+export const readHookCalls = async (storeDir) => {
+    let text = '';
+    try {
+        text = await readFile(paths(storeDir).hookCalls, 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const calls = [];
+    for (const line of text.split('\n')) {
+        if (line === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const event = isRecord(parsed) ? eventOf(parsed.event) : undefined;
+            if (isRecord(parsed) && event !== undefined && typeof parsed.at === 'string' && typeof parsed.hit === 'boolean' && typeof parsed.ms === 'number') {
+                calls.push({
+                    at: parsed.at,
+                    event,
+                    session: typeof parsed.session === 'string' ? parsed.session : null,
+                    hit: parsed.hit,
+                    ms: parsed.ms,
+                    ...(typeof parsed.startMs === 'number' ? { startMs: parsed.startMs } : {}),
+                    error: typeof parsed.error === 'string' ? parsed.error : null,
+                });
+            }
+        }
+        catch {
+            // A torn last line is skipped.
+        }
+    }
+    return calls;
+};

package/dist/sessions/hook-index.d.ts

@@ -0,0 +1,53 @@
+import type { Read } from './read.js';
+import { type RecallRead } from './recall-reads.js';
+import { type Store } from './store.js';
+/** A signature is "recurring" once it has been seen in this many sessions. */
+export declare const RECURRING_SESSIONS = 2;
+/** SessionStart ranks by sessions within this many latest sessions of its repository: the `measure --last 300 --repo` window the G1 reading uses. */
+export declare const RECENT_SESSIONS = 300;
+export interface IndexedSignature {
+    sig: string;
+    sessions: number;
+    /** Sessions with the signature among the latest `RECENT_SESSIONS` of the session's repository. */
+    recent: number;
+    /** Tools that most often followed, most common first. */
+    followed: Array<[string, number]>;
+    harness: string[];
+}
+export interface HookIndex {
+    at: string;
+    /** Every `--redact-domain` in force, so a hook masks an error the way the log was masked. */
+    redactDomains: string[];
+    /** Recurring signatures by project folder name, most recent sessions first. */
+    projects: {
+        [project: string]: IndexedSignature[];
+    };
+    /** Every signature seen in at least two sessions. */
+    signatures: {
+        [sig: string]: {
+            sessions: number;
+            followed: Array<[string, number]>;
+        };
+    };
+    /** The call shapes over the fit floors and `PUSH_MIN_LIFT`, by read ID. An index a version before this wrote has none, and a pre-tool hook then pushes nothing. */
+    fit?: {
+        [readId: string]: RecallRead;
+    };
+}
+export declare const buildIndex: (store: Store, redactDomains: readonly string[], at: string, reads?: readonly Read[]) => HookIndex;
+export declare const indexPath: (storeDir: string) => string;
+/** The index as written, or undefined when there is none (or it is torn): a hook then says nothing. */
+export declare const readIndex: (storeDir: string) => Promise<HookIndex | undefined>;
+export interface ContextOptions {
+    /** The session's working directory; its repository root selects the project folders. */
+    cwd: string;
+    harness?: string;
+    top: number;
+    maxChars: number;
+}
+/** `<root>/.claude/worktrees/<name>` belongs to `<root>`, so a worktree session sees its repository's history. */
+export declare const repositoryRoot: (cwd: string) => string;
+/** True when a project folder slug belongs to the repository `root` sits in (a worktree path counts as its repository). */
+export declare const inRepository: (project: string, root: string) => boolean;
+/** The top recurring signatures for the repository, as a short block for injection; undefined when there is nothing to say. */
+export declare const contextBlock: (index: HookIndex, options: ContextOptions) => string | undefined;