@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/schema.js

@@ -0,0 +1,148 @@
+// The session store's schema, in one file.
+//
+// Everything here is deterministic and local: no model call, no network. `oars sessions deposit` reads the operator's own Claude Code
+// logs (`~/.claude/projects/<path-slug>/*.jsonl` and each session's `subagents/` transcripts, one JSON event per line) and appends
+// captured records to `<config>/oars/sessions/observations.jsonl`. The log is appended to, and a whole-store deposit drops superseded revs (`compactLog` in `store.ts`): a session whose file changed is deposited
+// again under a higher `rev`, and a reader keeps only the highest `rev` of each session.
+//
+// EXTRACTOR 11 (pool vocabulary spec Section 2) changes no stored value. It moves raw `agentType`, `keys`, and `frameId` with the joined `frame` from class P to
+// class A, so a store written at 10 re-derives on its next deposit and only the pooled projection (computed at deposit, never written) changes.
+// Version 12 (CAPTURE 12) adds the optional `setup`, `funnel`, and `trust` to the session record, read from the transcript only (`session-shape.ts`;
+// `docs/sessions-store.md`). It changed no derivation, so it leaves EXTRACTOR at 10.
+// Version 13 (CAPTURE 13) changes three stored values: the email mask keeps a plain dotted version after `npm:` or `jsr:` (a pinned alias keeps its pick),
+// a block word in another case or a wrapper in another case or by path is skipped to reach the real program, and a `segments` `run` whose program basename holds
+// whitespace stores `<literal>`. It also settles the two stored forms of a `copilot` step at version 12. EXTRACTOR stays 11.
+// Version 14 (CAPTURE 14) adds the optional `errorCode`, `packages`, and `manifest` to a tool call and the optional `stack` strata to the file record and the prompt
+// record, all read from the transcript except `repoFiles`, which keeps its existing source. It changes no value captured before, so EXTRACTOR stays 11.
+// Version 15 (CAPTURE 15) changes three stored values of version 14: a Cargo table header that ends in a comment (`[package] # x`) is seen as a header, so the next
+// `version =` is no longer stored as `crates:version`; and `packageVersion` keeps only a version of three or four dotted numbers, so a bare `@1` or `==2.31` stores null; and, since calls with a null `packageVersion` share one `first`, a later short pin of the same package now marks `false`. EXTRACTOR stays 11.
+// Version 16 (CAPTURE 16) stores a call the user refused as Claude Code does, `status` `error` and `errorCode` `user-rejected`: a Cursor call whose `toolFormerData.userDecision` is `rejected`; a Codex shell
+// call, patch, or command item that is `declined` with the user's refusal text (each `none` before; any other `declined` stays `none`); and a Gemini call the user cancelled or denied (`errorCode` `other` before). A call that was `none` or `ok` gains an `error-line` record whose `line` is
+// the refusal text and loses its `manifest`, and where a result line is new (every Codex refusal, a Cursor one whose status is neither `error` nor `completed`, or one whose terminal result ended aborted) its session's `lines` and skeleton move. Any other
+// decision value, or none, changes nothing and is never stored; a Grok plan-mode refusal and a Codex `write_stdin rejected:` stay as they were. EXTRACTOR stays 11.
+//
+// Version 17 (CAPTURE 17) frames a Gemini CLI shell call as the shell that ran it. A session whose own `<session_context>` turn says `My operating system is: win32` (or,
+// with no such turn, whose working directory is written the Windows way) stores its shell calls as `PowerShell` where it stored `Bash`: the tool record's `tool`, an
+// error line's `tool`, the session's `tools` and the skeleton's tool names, each step's `native` (`run_shell_command` before), and the frame's `shell` (`bash` before), so every `frameId` of that
+// session moves. Upstream picks PowerShell on every Windows machine (`tools/shell-utils` `getShellConfiguration`). A Linux or macOS session is unchanged. It also gives a
+// session in a project folder named for a hash of its path (from before the slug registry) the cwd that hash matches when the path is known, which moves its `project`
+// (`gemini` before) and every value read from the cwd; a folder whose path is not known keeps none. Sessions under `~/.cache/.gemini` (`SANDBOX=sandbox-exec`) are new
+// reads, not moved ones. A Copilot CLI session with rotated `events.N.jsonl` archives is now read as one session, so its `prompts`, `tools`, `lines`, and skeleton move; one
+// with no archives is unchanged. EXTRACTOR stays 11. A version-16 store's next deposit captures every transcript again from the harness or `raw/`.
+//
+// EXTRACTOR 12 gives a derived prompt the strata of its user-prompt record, so its own `explore` count reaches the pool's wire as a bucket. No transcript is read: a store at
+// 11 re-derives from its log alone.
+//
+// Version 10 (CAPTURE 10) gives a turn opened by a slash command or a skill a `user-prompt` record, adds `opened` to that record, and moves `skills`
+// from class P to class A, since a skill's name can be private. It changed no derivation, so it leaves EXTRACTOR at 9.
+//
+// Version 11 (CAPTURE 11) redacts the part of an MCP tool name after `mcp__` (Cursor: `mcp_`) wherever it is stored (`tool`, the session's `tools`, an error line's `tool`, the skeleton's tool names),
+// reads package-manager and shell forms more exactly (so `pulls`, `segments`, `commits`, and each tool's `steps` change), and opens a typed prompt from a line that only starts with an injected tag's name without closing it.
+// EXTRACTOR 10 reads more command forms as a run or a verify (package runners, `unittest`, installs that are not runs, a leading word before a name); no capture record changes.
+//
+// EXTRACTOR 9 adds motifs, cells, and reads, computed from the capture records and written beside them (`docs/sessions-store.md`), and carries a prompt's
+// frame onto its derived record. No capture record changes.
+//
+// Version 9 (CAPTURE 9) adds `frame` and `frameId` to the session and prompt records and `steps` to the tool record, and moves `tool`, `tools`, and a
+// shell-form `target` from class P to class A. It changed no derivation, so it left EXTRACTOR at 8.
+//
+// Version 8 (CAPTURE 8 and EXTRACTOR 8) writes one `tool` record per tool call. The harness writes
+// `api-request-blob` lines, copies of the request body with no cwd, uuid, or timestamp, and capture used to read their blocks as conversation: a second
+// record with status `none` (and, with no cwd, another path hash) for 99.8% of calls, plus a second error line, thinking count, and TLDR. Those lines are
+// no longer read, and a call a resumed transcript replays under one tool-use id is written once. The skeleton still lists every line. The reader folds
+// records already on disk the same way until each transcript is captured again (`fold.ts`).
+//
+// Store version 5 (CAPTURE 5) keeps version 4's shape and changes one stored value: each `models` entry of the skeleton's cost state names
+// the usage keys it reported, which `verify` uses to class a side call. A version-4 skeleton reads with no keys until it is captured again.
+//
+// Store version 4 (CAPTURE 4) keeps version 3's shape and adds to it: `sid` on every capture record, `repo`, `fileHashes`, and `env` on
+// the session, `targetBase` on the tool record, `promptFingerprint` in place of `contextFingerprint`, and a 1,000-character cap on an
+// error-line's `line`. A version-3 store is read through the compatibility reader (`upgradeSession` and its siblings in store.ts) until each transcript is captured again.
+//
+// Store version 3 (register A28) splits capture from derivation. Capture writes four record kinds, each stamped `cv` with
+// CAPTURE_VERSION: `session` (one per transcript), `user-prompt` (one per prompt), `tool` (one per tool call), and `error-line` (one per
+// failed tool result, keyed by `toolUseId`). Derivation (`derive.ts`: signatures, prompt classes, tool-name sequences, recovery pairs,
+// and recovery episodes) runs over those records alone, never over raw, and stamps its output `v` with EXTRACTOR_VERSION, so a change to
+// a derivation rule re-derives the store without reading a transcript. Version-2 `prompt` and `error` lines (already derived) are still
+// read for a session that has no version-3 rev.
+//
+// Field classes (spec Section 1.1): `L` local-only, never leaves the machine at any tier; `A` account store, the account's own store only;
+// `P` pooled index, names, versions, counts, and day-resolution dates. The session, prompt, tool, error, and error-line records name
+// each field's class in a doc comment; the skeleton and the two call logs carry theirs on the type, and docs/sessions-store.md lists
+// them all. The log is the local derived-records tier: redacted text, never raw content, and nothing uploads.
+//
+// The text kept, each redacted first and then cut: the first 300 characters of a prompt, the first informative line of a tool error (cut
+// to 1,000 characters in the `error-line` record, 160 characters in a derived example), TLDR lines (400), Confidence lines (120), and,
+// with no length limit, WebSearch queries, fetched URLs, file paths, and git branch names. Also kept as written, not redacted: the
+// project folder slug (it holds the username and directory names; the log stays local), skill names, effort values, model names,
+// harness versions, and tool names (an MCP name's part after its prefix is redacted). `redact` masks secrets by pattern and entropy, emails, and the
+// organization domains the operator names. The skeleton holds hashes only.
+/** Stamped `cv` on every captured record. Bump it when the captured field list changes or a stored value of an existing captured record or skeleton changes: a bump re-reads every transcript. */
+export const CAPTURE_VERSION = '17';
+/** Capture versions the reader derives from. A version-3 record is upgraded on read; a newer one is read for the fields this code knows. */
+export const OLDEST_READABLE_CAPTURE = 3;
+/** Stamped `v` on every derived record. A bump re-derives from the log; no transcript is read. */
+export const EXTRACTOR_VERSION = '12';
+export const PROMPT_HEAD_CHARS = 300;
+export const ERROR_EXAMPLE_CHARS = 160;
+/** The reference scripts cut a normalized signature at 110 characters. */
+export const SIGNATURE_CHARS = 110;
+/** An error-line's `line` is redacted, then cut to this many characters (spec Section 1.2; version 3 stored it uncut). */
+export const ERROR_LINE_CHARS = 1000;
+/** Per-session cap on `files` and `fileHashes` (L3): the hand run on the copy store had p99 61 and max 209 files per session; 100 is the round number above p99. */
+export const FILES_PER_SESSION_MAX = 100;
+export const PROMPT_CLASSES = ['no-tools', 'orchestration', 'research', 'edit-verify', 'edit-only', 'explore-only', 'shell-only', 'mixed'];
+/** The statuses agents recover from differently (pool vocabulary spec Section 7); any other status is `other`. */
+export const HTTP_STATUSES = ['400', '401', '403', '404', '408', '409', '413', '429', '500', '502', '503', '504', '529'];
+/** A shell exit status by what the agent does next: success flagged as failure, the two common failures, not executable, not found, a signal (129 to 192), and the rest. */
+export const EXIT_CLASSES = ['0', '1', '2', '126', '127', 'signal'];
+/** What a harness says when a call fails before or without a shell: it names the harness's own refusal, never the tool's input or output. */
+export const HARNESS_ERROR_CLASSES = ['user-rejected', 'interrupted', 'permission-denied', 'input-validation', 'tool-use-error', 'timeout'];
+/** The `errorCode` of a failed call (class P): a member of this set, never text from the result. `other` covers an exit status or HTTP status outside the lists, and a failure that names no class. */
+export const ERROR_CODES = new Set([...EXIT_CLASSES, ...HTTP_STATUSES, ...HARNESS_ERROR_CLASSES, 'other']);
+/** The harness a session record came from; a record that does not name one is Claude Code's. */
+export const harnessOf = (session) => session.harness ?? 'claude-code';
+/** A language's share of the files a transcript touched (pool vocabulary spec Section 7): none, incidental, secondary, primary. The lower edge is inclusive, so 10 percent is secondary and 50 is primary. */
+export const LANGUAGE_SHARES = ['0', 'under-10', '10-50', 'over-50'];
+/** A repository's tracked-file count by order of magnitude (Section 7). The lower edge is inclusive, so exactly 100 is `100-1k` and exactly 100000 is `over-100k`, as `repoSizeOf` buckets them. */
+export const REPO_FILE_BUCKETS = ['under-100', '100-1k', '1k-10k', '10k-100k', 'over-100k'];
+/** The pipeline steps the log names (runtime-commons pipeline spec 3.1); `label` is the local labeler step (A5) that no command runs yet; `index` is the hook-index write the nightly and manual runs log. */
+export const STEPS = ['deposit', 'verify', 'derive', 'label', 'index', 'recall', 'read'];
+/** The trigger names of spec 4.1 (the ones nothing local starts are in the schema only: `weekly` (A21) and the hosted `sync`, `cron`, `release`, `run-end`, and `run-start`). The SessionEnd hook is `stop`, never `session-end`. */
+export const TRIGGERS = ['session-start', 'pre-tool', 'post-tool', 'stop', 'nightly', 'manual', 'weekly', 'sync', 'cron', 'release', 'run-end', 'run-start'];
+/** `deferred`: a Stop deposit that found the store locked and recorded its session in the pending list. It is neither a success nor a failed run. */
+export const STEP_STATUSES = ['ok', 'error', 'skipped', 'deferred'];
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const countsOf = (value) => {
+    if (!isObject(value))
+        return undefined;
+    const entries = Object.entries(value);
+    return entries.every(([, count]) => typeof count === 'number' && Number.isFinite(count)) ? Object.fromEntries(entries.map(([kind, count]) => [kind, Number(count)])) : undefined;
+};
+const oneOf = (list, value) => list.find((entry) => entry === value);
+/** Reads one line of `pipeline-runs.jsonl`; undefined when any key is missing or mistyped, so a torn or foreign line is never counted. */
+export const parseStepRow = (value) => {
+    if (!isObject(value))
+        return undefined;
+    const trigger = oneOf(TRIGGERS, value.trigger);
+    const step = oneOf(STEPS, value.step);
+    const status = oneOf(STEP_STATUSES, value.status);
+    const input = countsOf(value.in);
+    const output = countsOf(value.out);
+    if (trigger === undefined || step === undefined || status === undefined || input === undefined || output === undefined)
+        return undefined;
+    const { at, run, ms, cv, ev, lv, key, error } = value;
+    if (typeof at !== 'string' || typeof run !== 'string' || typeof ms !== 'number' || typeof cv !== 'string' || typeof ev !== 'string')
+        return undefined;
+    if (!(key === null || typeof key === 'string') || !(error === null || typeof error === 'string'))
+        return undefined;
+    // `lv` is the labeler stamp: spec 3.1 puts it on `label` rows only.
+    if (lv !== undefined && (typeof lv !== 'string' || step !== 'label'))
+        return undefined;
+    if (step === 'label' && lv === undefined)
+        return undefined;
+    // Spec 3.1: `error` is null when the step is `ok`.
+    if (status === 'ok' && error !== null)
+        return undefined;
+    return { at, run, trigger, step, status, ms, in: input, out: output, cv, ev, ...(lv === undefined ? {} : { lv }), key, error };
+};

package/dist/sessions/session-shape.d.ts

@@ -0,0 +1,73 @@
+import type { Harness } from './schema.js';
+type Obj = {
+    [key: string]: unknown;
+};
+/** The harness's tool-rejection results, both worded for the operator declining: a classifier or hook denial is policy, and the model carries on. */
+export declare const REJECTED_RE: RegExp;
+/** The harness writes this as a user line when the operator cut a turn short; a rejection is followed by it too, so it is not a second interrupt. */
+export declare const INTERRUPT_MARKER = "[Request interrupted by user";
+/** An adapter's neutral line naming tools: `offered` and `loaded` are arrays of tool names. */
+export declare const SHAPE_TOOLS_LINE = "oars-tools";
+/** An adapter's neutral line for a turn the operator cut short, for a harness whose record is not a Claude marker line. */
+export declare const SHAPE_INTERRUPT_LINE = "oars-interrupt";
+export type TrustEventKind = 'interrupt' | 'rejection' | 'denial';
+/** One stop, with the tool in flight (null when none is known) and the prompt it fell in (null before the first). */
+export interface TrustEvent {
+    event: TrustEventKind;
+    tool: string | null;
+    prompt: number | null;
+}
+/** The setup the session ran with. A field the transcript does not hold is absent. */
+export interface SessionSetup {
+    /** The mode most of the session ran in: the harness's documented value, else `other`. */
+    permissionMode?: string;
+    /** Plugins evidenced by a tool named after them, sorted. */
+    plugins?: string[];
+    /** Distinct hooks seen to fire, by the name the harness gives each, a floor; never the command. */
+    hookCount?: number;
+    /** Bytes of instruction files the harness loaded mid-session, a floor: the opening instruction files are in a blob capture skips. */
+    instructionBytes?: number;
+}
+/** The tool names at each stage a transcript shows, sorted. `called` and `worked` are the session's tool calls and their status, already captured. */
+export interface SessionFunnel {
+    /** Offered and not since removed. */
+    offered?: string[];
+    /** Pulled into the context by a tool search. */
+    loaded?: string[];
+    /** Offered and then removed, and not offered again. */
+    removed?: string[];
+}
+/** How far the session was trusted to run alone. The exact value is kept; the buckets belong to the projection. */
+export interface SessionTrust {
+    interrupts?: number;
+    /** The human declined a tool call. */
+    rejections?: number;
+    /** Policy refused it: permission rules, the classifier, or a hook. */
+    denials?: number;
+    trustEvent?: TrustEvent[];
+    /** Minutes the agent ran alone after each human turn: from the turn to the agent's last line before the next human turn, two decimals. */
+    unattendedRun?: number[];
+}
+export interface SessionShape {
+    setup?: SessionSetup;
+    funnel?: SessionFunnel;
+    trust?: SessionTrust;
+}
+/** Where a line sits, for the parts of the shape that depend on it. */
+export interface LineContext {
+    /** A sidechain line in a main transcript: a subagent's own, not read here. */
+    side: boolean;
+    /** The prompt the line falls in. */
+    prompt: number | null;
+}
+export interface ShapeCollector {
+    read(line: Obj, at: LineContext): void;
+    /** A turn: `human` opens a run of the agent alone and closes the last; `agent` is the agent (or an automated turn) working; `none` is neither. */
+    turn(kind: 'human' | 'agent' | 'none', seconds: number | undefined, uuid?: string): void;
+    finish(): SessionShape;
+}
+/** `stored` is the stored form of a tool name (`storedToolName`): every name this keeps is a tool name, an MCP server's part redacted. */
+export declare const createShape: (harness: Harness, stored: (tool: string) => string, options: {
+    timing: boolean;
+}) => ShapeCollector;
+export {};

package/dist/sessions/session-shape.js

@@ -0,0 +1,342 @@
+// What a transcript shows of a session's setup, its tool funnel, and its trust shape (the capture half of the pool vocabulary). Read from the
+// transcript only: never today's config or instruction files, because a file read now is not that session's setup. A field the transcript does not
+// hold is absent, never guessed. Counts, names, and sizes only: no instruction text, hook command, or tool description is kept. Class A, local; nothing
+// here is projected or uploaded.
+//
+// One collector per transcript, fed line by line by `captureSession`. It reads the Claude Code line shapes (a census of 2.1.312 to 2.1.318) and
+// two neutral lines an adapter may write for a harness whose records are not Claude-shaped (`oars-tools`, `oars-interrupt`).
+const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const str = (value) => (typeof value === 'string' ? value : undefined);
+const names = (value) => (Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item !== '') : []);
+/** The harness's tool-rejection results, both worded for the operator declining: a classifier or hook denial is policy, and the model carries on. */
+export const REJECTED_RE = /^The user doesn't want to (?:proceed with this tool use|take this action)/;
+/** The harness writes this as a user line when the operator cut a turn short; a rejection is followed by it too, so it is not a second interrupt. */
+export const INTERRUPT_MARKER = '[Request interrupted by user';
+/** A policy refusal: the permission rules or the auto-mode classifier (`Permission ... has been denied`), or a hook (`PreToolUse:Bash hook error`). Not the human's. */
+const DENIED_RE = /^(?:Permission (?:to use .{1,200}?|for this action) has been denied|[A-Za-z]+:[^\s]+ hook error|Hook [A-Za-z]+:[^\s]+ denied)/;
+/** A plugin's MCP server names its tools `mcp__plugin_<plugin>_<server>__<tool>`; that is the only evidence of an installed plugin read here.
+ * The name stops at its first `_`, since the tool name cannot say where the plugin ends and the server begins: `mcp__plugin_my_plugin_srv__t` reads as `my`. */
+const PLUGIN_TOOL_RE = /^mcp__plugin_([A-Za-z0-9-]+)_/;
+/** A hook of the `Stop` event, named `Stop` or `Stop:<matcher>`. */
+const STOP_HOOK_RE = /^Stop(?::|$)/;
+/** An adapter's neutral line naming tools: `offered` and `loaded` are arrays of tool names. */
+export const SHAPE_TOOLS_LINE = 'oars-tools';
+/** An adapter's neutral line for a turn the operator cut short, for a harness whose record is not a Claude marker line. */
+export const SHAPE_INTERRUPT_LINE = 'oars-interrupt';
+/** The permission modes each harness documents; any other value is stored as `other` (spec row `permissionMode`). Keyed by harness so a new one must add its entry. */
+const PERMISSION_MODES = {
+    'claude-code': new Set(['default', 'acceptEdits', 'plan', 'auto', 'dontAsk', 'bypassPermissions']),
+    codex: new Set(['untrusted', 'on-failure', 'on-request', 'never', 'granular']),
+    // Cursor's, Copilot's, and Gemini CLI's readers record no permission mode, so no value is documented to keep.
+    copilot: new Set(),
+    // VS Code Copilot Chat's reader records no permission mode either.
+    'vscode-copilot': new Set(),
+    gemini: new Set(),
+    cursor: new Set(),
+    // Grok Build's reader reads no mode (its `current_mode_update` carries one, but this reader does not read it), so no value is documented to keep.
+    grok: new Set(),
+};
+/**
+ * Which trust counts a harness's transcript records completely. A zero is stored only where the harness would have shown the event; where it would not,
+ * the count is absent, because zero would claim a human never stopped it. Keyed by harness so a new one must decide.
+ */
+const COMPLETE = {
+    'claude-code': { interrupts: true, rejections: true, denials: true, timing: true },
+    codex: { interrupts: true, rejections: false, denials: false, timing: true },
+    // Copilot's reader writes the prompts and the agent's lines with their times (so the runs are real), and reads no `abort`, tool outcome refusal, or hook denial.
+    copilot: { interrupts: false, rejections: false, denials: false, timing: true },
+    // VS Code Copilot Chat's reader writes the prompts and the responses with their times (so the runs are real) and reads a refusal as a tool error, not as a counted one; it reads no interrupt or hook denial count.
+    'vscode-copilot': { interrupts: false, rejections: false, denials: false, timing: true },
+    // Gemini CLI's reader writes each message with its own time (so the runs are real), and reads no interrupt, refusal, or denial: the chat file holds a cancelled call as an error and no more.
+    gemini: { interrupts: false, rejections: false, denials: false, timing: true },
+    cursor: { interrupts: false, rejections: false, denials: false, timing: false },
+    // Grok Build's reader writes the prompts and replies with their line times (seconds), and reads no cancel, tool refusal, or hook denial.
+    grok: { interrupts: false, rejections: false, denials: false, timing: true },
+};
+const firstText = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    for (const block of content)
+        if (isObj(block) && block.type === 'text')
+            return str(block.text) ?? '';
+    return '';
+};
+const firstLine = (content) => firstText(content).trimStart().split('\n', 1)[0] ?? '';
+const pluginOf = (tool) => PLUGIN_TOOL_RE.exec(tool)?.[1];
+/** `stored` is the stored form of a tool name (`storedToolName`): every name this keeps is a tool name, an MCP server's part redacted. */
+export const createShape = (harness, stored, options) => {
+    const complete = COMPLETE[harness];
+    const modes = new Map();
+    /** Hooks seen to fire, by the name the harness gives them (`PreToolUse:Bash`, `Stop`). */
+    const hooks = new Set();
+    /** The commands a `stop_hook_summary` lists: counted only when no line of a `Stop` hook was seen, since that line and the summary are the same hooks. */
+    const stopCommands = new Set();
+    let stopSeen = false;
+    const memory = new Map();
+    const plugins = new Set();
+    /** Every name offered or removed, in order: the last event on a name decides which side it ends on. */
+    const standing = new Map();
+    const loaded = new Set();
+    const events = [];
+    const open = new Map();
+    /** Every tool call id that has had its result, so a replayed call or result is neither re-opened nor counted twice. */
+    const finished = new Set();
+    /** Human turns already taken, by uuid: a resume replays them. */
+    const humans = new Set();
+    const markers = new Set();
+    let rejectedLast = false;
+    // The human refused a call: the run ended at the agent's last line before it, and what the agent does after the refusal waits for the next human turn.
+    let declined = false;
+    const counts = { interrupts: 0, rejections: 0, denials: 0 };
+    const runs = [];
+    let start;
+    let end;
+    const timing = options.timing && complete.timing;
+    const mode = (raw) => {
+        const value = str(raw);
+        if (value === undefined || value === '')
+            return;
+        const kept = PERMISSION_MODES[harness].has(value) ? value : 'other';
+        modes.set(kept, (modes.get(kept) ?? 0) + 1);
+    };
+    const noted = (tool) => {
+        // The `mcp__plugin_<plugin>_` naming is Claude Code's; another harness's tool of that shape is not evidence of a plugin.
+        // Read from the stored form, so a plugin named with a token reads as none rather than as the token.
+        const plugin = harness === 'claude-code' && tool.startsWith('mcp__plugin_') ? pluginOf(stored(tool)) : undefined;
+        if (plugin !== undefined)
+            plugins.add(plugin);
+    };
+    const offer = (list) => {
+        for (const name of list) {
+            standing.set(name, 'offered');
+            noted(name);
+        }
+    };
+    const remove = (list) => {
+        for (const name of list) {
+            standing.set(name, 'removed');
+            noted(name);
+        }
+    };
+    const load = (list) => {
+        for (const name of list) {
+            loaded.add(name);
+            noted(name);
+        }
+    };
+    const event = (kind, tool, prompt) => {
+        if (kind === 'interrupt')
+            counts.interrupts += 1;
+        else if (kind === 'rejection')
+            counts.rejections += 1;
+        else
+            counts.denials += 1;
+        events.push({ event: kind, tool, prompt });
+    };
+    const interrupt = (tool, prompt) => {
+        // The turn ended, so no call is still in flight: a later marker must not name this one.
+        open.clear();
+        if (rejectedLast) {
+            rejectedLast = false;
+            return;
+        }
+        event('interrupt', tool, prompt);
+    };
+    /** The tool the harness was still waiting on: the last call with no result. */
+    const inFlight = () => [...open.values()].at(-1) ?? null;
+    const result = (block, at) => {
+        const id = str(block.tool_use_id);
+        // A tool_reference block is the tool search's answer: those tools are now loaded.
+        if (Array.isArray(block.content)) {
+            for (const inner of block.content)
+                if (isObj(inner) && inner.type === 'tool_reference')
+                    load(names([inner.tool_name]));
+        }
+        if (id === undefined || finished.has(id))
+            return;
+        finished.add(id);
+        const tool = open.get(id) ?? null;
+        open.delete(id);
+        if (block.is_error !== true)
+            return;
+        const line = firstLine(block.content);
+        if (REJECTED_RE.test(line)) {
+            if (complete.rejections) {
+                rejectedLast = true;
+                declined = true;
+            }
+            event('rejection', tool, at.prompt);
+        }
+        else if (DENIED_RE.test(line))
+            event('denial', tool, at.prompt);
+    };
+    const attachment = (a) => {
+        const kind = str(a.type);
+        if (kind === 'deferred_tools_delta') {
+            offer(names(a.addedNames));
+            remove(names(a.removedNames));
+        }
+        else if (kind === 'hook_success' || kind === 'hook_additional_context' || kind === 'hook_blocking_error') {
+            const name = str(a.hookName);
+            if (name !== undefined && name !== '') {
+                hooks.add(name);
+                if (STOP_HOOK_RE.test(name))
+                    stopSeen = true;
+            }
+        }
+        else if (kind === 'nested_memory' && isObj(a.content) && typeof a.content.content === 'string') {
+            // The same file comes again when the harness reloads it, so one path counts once.
+            const key = str(a.path) ?? str(a.content.path) ?? `#${String(memory.size)}`;
+            if (!memory.has(key))
+                memory.set(key, Buffer.byteLength(a.content.content));
+        }
+    };
+    const close = () => {
+        if (start !== undefined)
+            runs.push(Math.round((((end ?? start) - start) / 60) * 100) / 100);
+        start = undefined;
+        end = undefined;
+    };
+    return {
+        read(line, at) {
+            // A sidechain line is a subagent's own, not the main session's setup.
+            if (at.side)
+                return;
+            const type = str(line.type);
+            if (type === 'permission-mode')
+                mode(line.permissionMode);
+            else if (type === 'api-request-shape') {
+                // The eager tool list the request sent: names only. `shape.system` holds the system prompt and a tool's description its text, so neither is touched.
+                const shape = isObj(line.shape) ? line.shape : undefined;
+                if (Array.isArray(shape?.tools))
+                    offer(names(shape.tools.map((tool) => (isObj(tool) ? tool.name : undefined))));
+            }
+            else if (type === SHAPE_TOOLS_LINE) {
+                offer(names(line.offered));
+                load(names(line.loaded));
+            }
+            else if (type === SHAPE_INTERRUPT_LINE)
+                interrupt(inFlight(), at.prompt);
+            else if (type === 'attachment') {
+                if (isObj(line.attachment))
+                    attachment(line.attachment);
+            }
+            else if (type === 'system' && line.subtype === 'stop_hook_summary') {
+                if (Array.isArray(line.hookInfos))
+                    for (const info of line.hookInfos)
+                        if (isObj(info) && str(info.command) !== undefined)
+                            stopCommands.add(str(info.command) ?? '');
+            }
+            else if ((type === 'user' || type === 'assistant') && isObj(line.message)) {
+                if (type === 'user')
+                    mode(line.permissionMode);
+                const content = line.message.content;
+                if (type === 'user' && firstText(content).startsWith(INTERRUPT_MARKER)) {
+                    const uuid = str(line.uuid);
+                    if (uuid === undefined || !markers.has(uuid))
+                        interrupt(inFlight(), at.prompt);
+                    if (uuid !== undefined)
+                        markers.add(uuid);
+                }
+                if (type === 'assistant')
+                    rejectedLast = false;
+                if (!Array.isArray(content))
+                    return;
+                for (const block of content) {
+                    if (!isObj(block))
+                        continue;
+                    if (block.type === 'tool_use') {
+                        const id = str(block.id);
+                        const name = str(block.name);
+                        if (name !== undefined)
+                            noted(name);
+                        if (id !== undefined && name !== undefined && !open.has(id) && !finished.has(id))
+                            open.set(id, name);
+                    }
+                    else if (block.type === 'tool_result')
+                        result(block, at);
+                }
+            }
+        },
+        turn(kind, seconds, uuid) {
+            if (kind === 'human') {
+                // A resume replays earlier lines: a human turn already taken is not a new one.
+                if (uuid !== undefined) {
+                    if (humans.has(uuid))
+                        return;
+                    humans.add(uuid);
+                }
+                // The operator spoke again: nothing is still in flight, and a rejection before this is not what a later marker follows.
+                open.clear();
+                rejectedLast = false;
+            }
+            // The line after a rejection ends the run; a human turn does that anyway, so it falls through to start the next one.
+            const afterRejection = declined && kind !== 'human';
+            declined = false;
+            if (!timing)
+                return;
+            if (afterRejection) {
+                close();
+                return;
+            }
+            // A human turn with no usable time still ends the run before it: the agent lines after it are not that run's.
+            if (kind === 'human') {
+                close();
+                start = seconds;
+            }
+            else if (kind === 'agent' && seconds !== undefined && start !== undefined && seconds >= start && (end === undefined || seconds > end))
+                end = seconds;
+        },
+        finish() {
+            close();
+            const out = {};
+            const setup = {};
+            let best = 0;
+            for (const [value, count] of modes) {
+                if (count > best) {
+                    best = count;
+                    setup.permissionMode = value;
+                }
+            }
+            if (plugins.size > 0)
+                setup.plugins = [...plugins].sort();
+            const hookTotal = hooks.size + (stopSeen ? 0 : stopCommands.size);
+            if (hookTotal > 0)
+                setup.hookCount = hookTotal;
+            if (memory.size > 0)
+                setup.instructionBytes = [...memory.values()].reduce((sum, bytes) => sum + bytes, 0);
+            if (Object.keys(setup).length > 0)
+                out.setup = setup;
+            const funnel = {};
+            // Two names that redact to one form are one tool, as `tools` keys it.
+            const sideOf = (which) => [...new Set([...standing].filter(([, side]) => side === which).map(([name]) => stored(name)))].sort();
+            const offered = sideOf('offered');
+            const removed = sideOf('removed');
+            if (offered.length > 0)
+                funnel.offered = offered;
+            if (loaded.size > 0)
+                funnel.loaded = [...new Set([...loaded].map(stored))].sort();
+            if (removed.length > 0)
+                funnel.removed = removed;
+            if (Object.keys(funnel).length > 0)
+                out.funnel = funnel;
+            const trust = {};
+            if (complete.interrupts)
+                trust.interrupts = counts.interrupts;
+            if (complete.rejections)
+                trust.rejections = counts.rejections;
+            if (complete.denials)
+                trust.denials = counts.denials;
+            const kept = events.filter((item) => (item.event === 'interrupt' ? complete.interrupts : item.event === 'rejection' ? complete.rejections : complete.denials));
+            if (kept.length > 0)
+                trust.trustEvent = kept.map((item) => ({ ...item, tool: item.tool === null ? null : stored(item.tool) }));
+            if (runs.length > 0)
+                trust.unattendedRun = runs;
+            if (Object.keys(trust).length > 0)
+                out.trust = trust;
+            return out;
+        },
+    };
+};

package/dist/sessions/sources.d.ts

@@ -0,0 +1,50 @@
+import type { SubagentOrigin } from './extract.js';
+import type { Harness } from './schema.js';
+/** A session found in a source, before its transcript is read. */
+export interface SourceSession {
+    /** Names the skeleton (`<source>-<id>`), so it is a safe file name. */
+    id: string;
+    /** The working folder (a path); null when the source names none. */
+    folder: string | null;
+    /** With `mtimeMs`, the cursor `state.json` keeps to tell a changed session from one already deposited. */
+    size: number;
+    mtimeMs: number;
+    /** Set when the session is a spawned agent's: it is deposited as a subagent of its parent, so session counts stay main sessions. */
+    subagent?: SubagentOrigin;
+}
+export interface SourceStore {
+    sessions: SourceSession[];
+    /** The session as transcript text for `captureSession`; throws when it cannot be read. */
+    transcript: (session: SourceSession) => string | Promise<string>;
+    /** Sessions skipped because their id is not a safe file name, counted so the skip is never silent. */
+    rejected: number;
+    /** Items that could not be inspected, warned about once each and never fatal; `reason` names no path. */
+    unreadable: readonly {
+        file: string;
+        reason: string;
+    }[];
+    /** The file to blame when `transcript` throws for a session; the store's own file when a source keeps one. */
+    where: (session: SourceSession) => string;
+    close: () => void;
+}
+export interface Source {
+    /** The `--allow` name, the first segment of its `state.json` keys, and the prefix of its skeleton names. */
+    name: string;
+    harness: Harness;
+    /** How the deposit lines name it ("Cursor": `Read 3 Cursor sessions.`). */
+    label: string;
+    /** Where its store lives; the caller passes the environment so a test never reads the real one. */
+    root: (platform: NodeJS.Platform, env: {
+        [name: string]: string | undefined;
+    }, home: string) => string;
+    /** The file reported when the store as a whole cannot be opened. */
+    storeFile: (root: string) => string;
+    /** A session whose transcript cannot be read ends this source's deposit (Cursor's, as it was before the table) instead of skipping to the next. */
+    stopOnTranscriptError?: boolean;
+    /** Opens the store read-only; undefined when the machine has none, so a missing store is skipped silently. */
+    open: (root: string) => Promise<SourceStore | undefined>;
+}
+/** Every non-Claude source, in the order the deposit reads them. */
+export declare const SOURCES: readonly Source[];
+/** How a source is named in a deposit line; a name the table does not know (a test's) is its own label. */
+export declare const sourceLabel: (name: string, table?: readonly Source[]) => string;