@manyoars/oars 0.3.0 → 0.4.0

package/dist/sessions/survival.js

@@ -21,7 +21,7 @@ const CWD_SCAN_LINES = 200;
 const DEFAULT_REFS = ['refs/remotes/origin/main', 'refs/remotes/origin/master', 'refs/heads/main', 'refs/heads/master'];
 const STATES = ['survived', 'reverted', 'unreachable', 'unknown'];
 export const survivalFile = (storeDir) => join(storeDir, 'commit-survival.jsonl');
-const runGit = (root, args, stdin) => new Promise((resolve, reject) => {
+export const runGit = (root, args, stdin) => new Promise((resolve, reject) => {
     const child = execFile('git', ['-C', root, ...args], {
         encoding: 'utf8',
         timeout: GIT_TIMEOUT_MS,
@@ -145,7 +145,7 @@ const cwdIn = async (file, project) => {
         stream.destroy();
     }
 };
-const cwdOfProject = async (runtime, project, sessions) => {
+export const cwdOfProject = async (runtime, project, sessions) => {
     for (const session of sessions) {
         for (const root of [runtime.projectsRoot, paths(runtime.storeDir).raw]) {
             const found = await cwdIn(join(root, project, `${session}.jsonl`), project);

package/dist/sessions/transcript-tail.d.ts

@@ -0,0 +1,14 @@
+/** A file's last bytes; a first line this cuts in two fails to parse and is skipped by whoever reads it. */
+export declare const tailOf: (file: string) => Promise<string>;
+export declare const isRecord: (value: unknown) => value is {
+    [key: string]: unknown;
+};
+/** What a transcript's tail states of the asker: the harness version, the model, and the effort, each the newest line's that states it. */
+export interface Stated {
+    harnessVersion: string | null;
+    model: string | null;
+    effort: string | null;
+}
+export declare const statedOf: (tail: string) => Stated;
+/** The same from a transcript file. A file that cannot be read states nothing: telemetry must never cost a hook its answer. */
+export declare const statedAt: (file: string) => Promise<Stated>;

package/dist/sessions/transcript-tail.js

@@ -0,0 +1,64 @@
+// The last bytes of a transcript and what they state, light enough for a hook to import: the bare `oars gate hook` loads this and never the recall machinery.
+import { open } from 'node:fs/promises';
+/** How far back a hook looks in a growing file: enough for the session's latest lines, and a bound on what a hook on every call can cost. */
+const TAIL_BYTES = 64 * 1024;
+const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+const openIfThere = async (file) => {
+    try {
+        return await open(file, 'r');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+};
+/** A file's last bytes; a first line this cuts in two fails to parse and is skipped by whoever reads it. */
+export const tailOf = async (file) => {
+    const handle = await openIfThere(file);
+    if (handle === undefined)
+        return '';
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(size, TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        return buffer.toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+};
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (value) => (typeof value === 'string' && value !== '' ? value : null);
+const parsedLines = (tail) => tail.split('\n').flatMap((line) => {
+    try {
+        const parsed = JSON.parse(line);
+        return isRecord(parsed) ? [parsed] : [];
+    }
+    catch {
+        return [];
+    }
+});
+export const statedOf = (tail) => {
+    let harnessVersion = null;
+    let model = null;
+    let effort = null;
+    // Oldest first, so the newest line that states a field wins.
+    for (const line of parsedLines(tail)) {
+        harnessVersion = text(line.version) ?? harnessVersion;
+        effort = text(line.effort) ?? effort;
+        if (isRecord(line.message))
+            model = text(line.message.model) ?? model;
+    }
+    return { harnessVersion, model, effort };
+};
+/** The same from a transcript file. A file that cannot be read states nothing: telemetry must never cost a hook its answer. */
+export const statedAt = async (file) => {
+    try {
+        return statedOf(await tailOf(file));
+    }
+    catch {
+        return { harnessVersion: null, model: null, effort: null };
+    }
+};

package/dist/sessions/vscode-copilot.js

@@ -31,6 +31,7 @@
 //                    `hiddenFromTranscript` is the harness writing, not the operator, and its prompt is not read; its response still is
 //   timestamp        epoch milliseconds, `responseTimestamp` for the response. A missing or implausible one is never made up: the time carries forward
 //   modelId          the model
+//   agent            `agent.extensionVersion` (participants/chatAgents.ts:71) is the Copilot Chat extension's version, the harness version, read only when `agent.extensionId.value` is `GitHub.copilot-chat` (a third-party participant carries its own): the newest request that names one
 //   response[]       a markdown part is a bare `{value}` (a string in the old format); `kind:'thinking'` is skipped;
 //                    `kind:'toolInvocationSerialized'` is a tool call (chatService/chatService.ts:1246-1270); `kind:'textEditGroup'` or `'notebookEditGroup'` `{uri}` is a file edited
 //   usage            `completionTokens` on the request, the whole turn's output (model/chatModel.ts:1929-1934, 2086), and `modelTotals[{model, inputTokens, cachedTokens, outputTokens}]`
@@ -48,7 +49,8 @@
 // button of a confirmation is the decline button and writes `{type:5, source:'user'}` (browser/widget/chatContentParts/toolInvocationParts/abstractToolConfirmationSubPart.ts:225,
 // chatTerminalToolConfirmationSubPart.ts:380,507; browser/tools/languageModelToolsService.ts:711), so a user's refusal (`source` `user`) reads as Claude Code's refusal text and
 // stores `user-rejected`; a hook's or a risk assessment's (languageModelToolsService.ts:683,1051) reads as a permission denial. A `{type:5}` with no `source` is the skip after
-// approval (model/chatProgressTypes/chatToolInvocation.ts:516) and has no outcome. The file holds no harness version and no working-directory change.
+// approval (model/chatProgressTypes/chatToolInvocation.ts:516) and has no outcome. The file holds no working-directory change;
+// its one harness version is the Copilot Chat agent's `extensionVersion` (see `agent` above).
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
@@ -67,6 +69,8 @@ export const vscodeAppData = (platform, env, home = homedir()) => {
 /** The `nameShort` of each build read. */
 const SHELL_TOOLS = new Set(['run_in_terminal', 'run_task', 'create_and_run_task']);
 const CHANNELS = ['Code', 'Code - Insiders', 'Code - OSS'];
+// ExtensionIdentifier compares ids case-insensitively, so this is the lowercase form of `GitHub.copilot-chat`.
+const COPILOT_CHAT_EXTENSION_ID = 'github.copilot-chat';
 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);
@@ -229,6 +233,11 @@ export const chatLines = (data, fallbackId, folder) => {
     };
     for (const request of requests) {
         const when = stamp(request.timestamp);
+        // The extension's version, from the agent VS Code serialized beside the request (ISerializableChatAgentData.extensionVersion); a later request supersedes. A
+        // third-party chat participant is serialized the same way with its own extension's version, so only Copilot Chat's own agent is read (id compared case-insensitively).
+        const extensionVersion = isObj(request.agent) && isObj(request.agent.extensionId) && str(request.agent.extensionId.value)?.toLowerCase() === COPILOT_CHAT_EXTENSION_ID ? str(request.agent.extensionVersion) : undefined;
+        if (extensionVersion !== undefined)
+            base.version = extensionVersion;
         const message = request.message;
         const text = typeof message === 'string' ? str(message) : isObj(message) ? str(message.text) : undefined;
         const hidden = request.isSystemInitiated === true || request.requestHiddenFromTranscript === true || request.hiddenFromTranscript === true;
@@ -326,12 +335,20 @@ export const chatLines = (data, fallbackId, folder) => {
         const totals = Array.isArray(request.modelTotals) ? request.modelTotals.filter(isObj) : [];
         const completion = num(request.completionTokens);
         const sum = (field) => totals.reduce((total, entry) => total + (num(entry[field]) ?? 0), 0);
-        // `inputTokens` is taken whole: the source does not say whether it includes `cachedTokens`.
-        const usage = totals.length > 0
-            ? { input_tokens: sum('inputTokens'), cache_read_input_tokens: sum('cachedTokens'), output_tokens: sum('outputTokens') }
-            : completion === undefined
-                ? undefined
-                : { output_tokens: completion };
+        // `inputTokens` is taken whole: the source does not say whether it includes `cachedTokens`. A zero `inputTokens` means unknown (the extension API bridge never reports one,
+        // so the zero is a default), so it is left out rather than written as a measured zero. `cachedTokens` and `outputTokens` are values: a zero is kept when a total carried the
+        // field, since a request with no cache hit is a measured zero, and only a field no total carried is left out. When no category is left, the request has no usage.
+        // An all-zero `outputTokens` beside a positive `completionTokens` is the bridge's default beside the real count, so the completion count wins over that zero.
+        const carried = (field) => totals.some((entry) => num(entry[field]) !== undefined);
+        const fromCompletion = completion !== undefined && completion > 0 ? { output_tokens: completion } : {};
+        const fromTotals = {
+            ...(sum('inputTokens') > 0 ? { input_tokens: sum('inputTokens') } : {}),
+            ...(carried('cachedTokens') ? { cache_read_input_tokens: sum('cachedTokens') } : {}),
+            ...(carried('outputTokens') ? { output_tokens: sum('outputTokens') } : {}),
+            ...(sum('outputTokens') === 0 ? fromCompletion : {}),
+        };
+        const counted = totals.length > 0 && Object.keys(fromTotals).length > 0 ? fromTotals : fromCompletion;
+        const usage = Object.keys(counted).length > 0 ? counted : undefined;
         if (content.length > 0 || usage !== undefined) {
             const model = str(request.modelId);
             const answered = stamp(request.responseTimestamp);

package/dist/telemetry/command.d.ts

@@ -0,0 +1,8 @@
+import type { Outcome, RunDeps } from '../cli.js';
+export declare const telemetryStatus: (deps: RunDeps) => Outcome;
+export declare const telemetryOn: (deps: RunDeps) => Outcome;
+export declare const telemetryOff: (deps: RunDeps) => Outcome;
+/** The spool exactly as it is on disk, oldest first, as `pool outbox` prints a batch; the document carries the same events parsed. */
+export declare const telemetryShow: (deps: RunDeps) => Outcome;
+/** The user's own numbers from the spool, and the fleet's beside them when a pool server is configured and answers (docs/telemetry.md, "The report"). It writes nothing. */
+export declare const telemetryReport: (deps: RunDeps) => Promise<Outcome>;

package/dist/telemetry/command.js

@@ -0,0 +1,85 @@
+// `oars telemetry status|on|off|show`.
+import { statSync } from 'node:fs';
+import { CliError, ExitCode } from '../errors.js';
+import { consentOf, markNoticeShown, NOTICE, setEnabled } from './consent.js';
+import { readFleet, reportOf, textOf } from './report.js';
+import { readSpool, spoolPaths } from './spool.js';
+const STEP = 'telemetry';
+const runtimeOf = (deps) => {
+    if (deps.telemetry === undefined)
+        throw new CliError('The telemetry folder is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+    return deps.telemetry;
+};
+const REASONS = {
+    default: 'on by default',
+    setting: 'by `oars telemetry on` or `off`',
+    OARS_TELEMETRY: 'by OARS_TELEMETRY',
+    DO_NOT_TRACK: 'by DO_NOT_TRACK',
+};
+const sizeOf = (path) => {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+};
+const describe = (consent) => `Telemetry is ${consent.enabled ? 'on' : 'off'} (${REASONS[consent.reason]}).`;
+export const telemetryStatus = (deps) => {
+    const { dir } = runtimeOf(deps);
+    const consent = consentOf(deps.env, dir);
+    const events = readSpool(dir).length;
+    const bytes = sizeOf(spoolPaths(dir).current) + sizeOf(spoolPaths(dir).previous);
+    const lines = [
+        describe(consent),
+        `The notice has ${consent.noticeShown ? '' : 'not '}been shown.`,
+        `${String(events)} events (${String(bytes)} bytes) in ${dir}.`,
+        'Events are sent to the pool server in OARS_POOL_URL, else to the Many Oars pool (pool.manyoars.com, not deployed yet: until it is, a send fails and the events stay on this machine), and only while telemetry is on and the notice has been shown.',
+    ];
+    return { document: { ok: true, step: STEP, enabled: consent.enabled, reason: consent.reason, noticeShown: consent.noticeShown, events, bytes, dir }, text: lines.join('\n') };
+};
+const save = (dir, enabled) => {
+    try {
+        setEnabled(dir, enabled);
+    }
+    catch (error) {
+        throw new CliError(`Could not save the telemetry setting in ${dir}: ${error instanceof Error ? error.message : String(error)}`, ExitCode.UNEXPECTED, 'telemetry-setting');
+    }
+};
+export const telemetryOn = (deps) => {
+    const { dir } = runtimeOf(deps);
+    save(dir, true);
+    // Running `on` is the notice: it is printed here and recorded as shown.
+    markNoticeShown(dir, deps.now);
+    const consent = consentOf(deps.env, dir);
+    const override = consent.enabled ? '' : `\nIt stays off in this shell: ${consent.reason} is set.`;
+    return { document: { ok: true, step: STEP, enabled: consent.enabled, reason: consent.reason, notice: NOTICE }, text: `Telemetry is on.\n${NOTICE}${override}` };
+};
+export const telemetryOff = (deps) => {
+    const { dir } = runtimeOf(deps);
+    save(dir, false);
+    return {
+        document: { ok: true, step: STEP, enabled: false, reason: 'setting' },
+        text: `Telemetry is off: nothing more is recorded or sent. What is already in the spool stays until you delete ${dir}.`,
+    };
+};
+const parsed = (line) => {
+    try {
+        return [JSON.parse(line)];
+    }
+    catch {
+        return [];
+    }
+};
+/** The spool exactly as it is on disk, oldest first, as `pool outbox` prints a batch; the document carries the same events parsed. */
+export const telemetryShow = (deps) => {
+    const { dir } = runtimeOf(deps);
+    const lines = readSpool(dir);
+    return { document: { ok: true, step: STEP, events: lines.flatMap(parsed) }, text: lines.length === 0 ? `The spool is empty (${dir}).` : lines.join('\n') };
+};
+/** The user's own numbers from the spool, and the fleet's beside them when a pool server is configured and answers (docs/telemetry.md, "The report"). It writes nothing. */
+export const telemetryReport = async (deps) => {
+    const { dir } = runtimeOf(deps);
+    const report = reportOf(readSpool(dir), deps.now(), await readFleet(deps.env));
+    return { document: { ok: true, step: STEP, ...report }, text: textOf(report, dir) };
+};

package/dist/telemetry/consent.d.ts

@@ -0,0 +1,17 @@
+/** Printed once on stderr, on the first run that is not a hook; also what `oars telemetry on` prints. */
+export declare const NOTICE: string;
+export type Reason = 'default' | 'setting' | 'OARS_TELEMETRY' | 'DO_NOT_TRACK';
+export interface Consent {
+    enabled: boolean;
+    /** Which switch decided `enabled`. */
+    reason: Reason;
+    /** The notice was printed (or `on` was run) on this install. */
+    noticeShown: boolean;
+}
+export declare const consentOf: (env: NodeJS.ProcessEnv, dir: string) => Consent;
+/** Saves `on` or `off`. Throws when the folder cannot be written: the command that asked reports it. */
+export declare const setEnabled: (dir: string, enabled: boolean) => void;
+/** Records that the notice was shown; `false` when it could not be recorded (nothing is recorded or sent from a folder that cannot be written). */
+export declare const markNoticeShown: (dir: string, now: () => number) => boolean;
+/** Whether the sender (t875) may send: telemetry on, and the notice shown. Off, or notice not yet shown, means nothing sends. */
+export declare const telemetrySendAllowed: (env: NodeJS.ProcessEnv, dir: string) => boolean;

package/dist/telemetry/consent.js

@@ -0,0 +1,63 @@
+// Whether telemetry records and may send, and the one-time notice. The off switches are `oars telemetry off` (a saved setting), `OARS_TELEMETRY=0`, and
+// `DO_NOT_TRACK=1`; the environment wins over a saved `on`. `telemetrySendAllowed` is the check the sender must call before any byte leaves.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { spoolPaths } from './spool.js';
+/** Printed once on stderr, on the first run that is not a hook; also what `oars telemetry on` prints. */
+export const NOTICE = [
+    'oars records how it is used, on this machine: one event per command with its path, flag names (never their values), how long it took, the exit code, and the class of any error; one per hook fire, recall, deposit, and fetch, as counts and closed words (which hook, how long, hit or miss, how many bytes, how many sessions a deposit counted and how many each gate kept out, never which); each with a random install id, the oars version, the OS, and the time. Once a night it also records counts and sizes of the session store and what the run cost. A crash is recorded as the error\'s class and a hash of its stack (never its message). Each pool deposit records, per batch, which fields it held and how many bytes each took, and each send (a wire-send event) its HTTP status, the pool\'s refusal code, and its size.',
+    'It never records session content, prompts, file paths, URLs, arguments, or anything you typed. oars sends the events in batches to the pool server in OARS_POOL_URL, else to the Many Oars pool (pool.manyoars.com, not deployed yet: until it is, a send fails and the events stay on this machine), and nowhere else.',
+    'See exactly what is kept: oars telemetry show. Turn it off: oars telemetry off, or set OARS_TELEMETRY=0 or DO_NOT_TRACK=1. More: docs/telemetry.md.',
+].join('\n');
+const readSettings = (dir) => {
+    try {
+        const parsed = JSON.parse(readFileSync(spoolPaths(dir).settings, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        const enabled = Reflect.get(parsed, 'enabled');
+        const shown = Reflect.get(parsed, 'noticeShownAt');
+        return { ...(typeof enabled === 'boolean' ? { enabled } : {}), ...(typeof shown === 'string' ? { noticeShownAt: shown } : {}) };
+    }
+    catch {
+        return {};
+    }
+};
+/** Write to a sibling and rename over, so a crash leaves the old settings or the new, never half. */
+const writeSettings = (dir, settings) => {
+    const { settings: path } = spoolPaths(dir);
+    mkdirSync(dir, { recursive: true });
+    const scratch = `${path}.tmp`;
+    writeFileSync(scratch, `${JSON.stringify(settings)}\n`);
+    renameSync(scratch, path);
+};
+const OFF_WORDS = new Set(['0', 'false', 'off', 'no']);
+const DO_NOT_TRACK_WORDS = new Set(['1', 'true']);
+export const consentOf = (env, dir) => {
+    const settings = readSettings(dir);
+    const noticeShown = settings.noticeShownAt !== undefined;
+    if (OFF_WORDS.has((env.OARS_TELEMETRY ?? '').toLowerCase()))
+        return { enabled: false, reason: 'OARS_TELEMETRY', noticeShown };
+    if (DO_NOT_TRACK_WORDS.has((env.DO_NOT_TRACK ?? '').toLowerCase()))
+        return { enabled: false, reason: 'DO_NOT_TRACK', noticeShown };
+    if (settings.enabled !== undefined)
+        return { enabled: settings.enabled, reason: 'setting', noticeShown };
+    return { enabled: true, reason: 'default', noticeShown };
+};
+/** Saves `on` or `off`. Throws when the folder cannot be written: the command that asked reports it. */
+export const setEnabled = (dir, enabled) => {
+    writeSettings(dir, { ...readSettings(dir), enabled });
+};
+/** Records that the notice was shown; `false` when it could not be recorded (nothing is recorded or sent from a folder that cannot be written). */
+export const markNoticeShown = (dir, now) => {
+    try {
+        writeSettings(dir, { ...readSettings(dir), noticeShownAt: new Date(now()).toISOString() });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether the sender (t875) may send: telemetry on, and the notice shown. Off, or notice not yet shown, means nothing sends. */
+export const telemetrySendAllowed = (env, dir) => {
+    const consent = consentOf(env, dir);
+    return consent.enabled && consent.noticeShown;
+};

package/dist/telemetry/crash.d.ts

@@ -0,0 +1,8 @@
+import { type Emitter } from './emit.js';
+import { type CrashClass } from './schema.js';
+/** The class of a thrown value: a built-in error class by name, else `other`. A class a program or library defines, and a name set to text, are `other`. */
+export declare const crashClassOf: (error: unknown) => CrashClass;
+/** 16 hex characters from the frames of the stack, the message's lines left out (a message can run over many lines, and none begins with `at`). */
+export declare const stackHashOf: (error: unknown) => string;
+/** Records a crash. It reads the error for its class and its frames only; the message is never touched. */
+export declare const recordCrash: (emitter: Emitter, error: unknown) => void;

package/dist/telemetry/crash.js

@@ -0,0 +1,52 @@
+// A crash report is the error's class and a hash of its stack: never its message, which can hold a path. The stack's own text is read only to be
+// hashed, and every file path in it is reduced to its place inside a package (or hashed whole when it sits nowhere known) before that, so the same
+// code on two machines is the same crash and no home folder reaches the hash's input in clear.
+import { createHash } from 'node:crypto';
+import { emitEvent } from './emit.js';
+import { CRASH_CLASSES } from './schema.js';
+/** The class of a thrown value: a built-in error class by name, else `other`. A class a program or library defines, and a name set to text, are `other`. */
+export const crashClassOf = (error) => {
+    if (!(error instanceof Error))
+        return 'other';
+    // A subclass of a built-in is that built-in; walk up until one is named.
+    for (let proto = Object.getPrototypeOf(error); typeof proto === 'object' && proto !== null; proto = Object.getPrototypeOf(proto)) {
+        const named = Reflect.get(proto, 'constructor');
+        const name = typeof named === 'function' ? Reflect.get(named, 'name') : '';
+        const found = CRASH_CLASSES.find((known) => known === name && known !== 'other');
+        if (found !== undefined)
+            return found;
+    }
+    return 'other';
+};
+const short = (text) => createHash('sha256').update(text).digest('hex').slice(0, 8);
+/** `file:///C:/a/b.js`, `C:\a\b.js`, and `/a/b.js` as one slash-separated path, so two machines' separators agree. */
+const plain = (location) => location.replace(/^file:\/\/\/?/, '').replaceAll('\\', '/');
+/** Where a package's own files start in a path: after the last `dist/`, `src/`, or `node_modules/`. What lies before it is the machine's. */
+const WITHIN = /^.*\/(?:dist|src|node_modules)\/(.*)$/;
+const frameOf = (line) => {
+    const found = /^\s*at (?:(.*?) \()?(.*?)\)?$/.exec(line);
+    if (found === null)
+        return undefined;
+    const name = found[1] ?? '';
+    const place = /^(.*):(\d+):(\d+)$/.exec(found[2] ?? '');
+    // A frame with no line and column is an engine frame (`node:internal/...`, `<anonymous>`): nothing of the machine's.
+    if (place === null)
+        return `${name}@${found[2] ?? ''}`;
+    const path = plain(place[1] ?? '');
+    const within = WITHIN.exec(path)?.[1];
+    // Hashed either way: a package-relative path names no one, and one that is not inside a package is the machine's and is hashed whole.
+    return `${name}@${short(within ?? path)}:${place[2] ?? ''}:${place[3] ?? ''}`;
+};
+/** 16 hex characters from the frames of the stack, the message's lines left out (a message can run over many lines, and none begins with `at`). */
+export const stackHashOf = (error) => {
+    const stack = error instanceof Error && typeof error.stack === 'string' ? error.stack : '';
+    const frames = stack
+        .split('\n')
+        .filter((line) => /^\s+at /.test(line))
+        .flatMap((line) => frameOf(line) ?? []);
+    return createHash('sha256').update(frames.join('\n')).digest('hex').slice(0, 16);
+};
+/** Records a crash. It reads the error for its class and its frames only; the message is never touched. */
+export const recordCrash = (emitter, error) => {
+    emitEvent(emitter, 'crash', { errorClass: crashClassOf(error), stackHash: stackHashOf(error) });
+};

package/dist/telemetry/emit.d.ts

@@ -0,0 +1,31 @@
+import { type TelemetryRuntime } from './record.js';
+/** What recording needs from a run: where the folder is, the environment's switches, the version, and the clock. */
+export interface Emitter {
+    env: NodeJS.ProcessEnv;
+    telemetry?: TelemetryRuntime | undefined;
+    version: string;
+    now: () => number;
+}
+/** Whether this run records at all: a folder is set and consent is on. A caller that must do work to build an event asks first, so an opt-out pays nothing. */
+export declare const recordsEvents: (emitter: Emitter) => boolean;
+export declare const emitEvent: (emitter: Emitter, type: string, fields: object) => void;
+/** Records one event of a known type; a no-op when telemetry is off, has no folder, or fails. */
+export type Emit = (type: string, fields: object) => void;
+export interface EmitContext {
+    env: NodeJS.ProcessEnv;
+    /** Absent: nothing is recorded. */
+    telemetry: TelemetryRuntime | undefined;
+    /** Read only when an event is about to be written, so a run with telemetry off never reads it. */
+    version: () => string;
+    now: () => number;
+}
+export declare const emitFor: ({ env, telemetry, version, now }: EmitContext) => Emit;
+/** An emitter that records nothing, for a caller built without telemetry. */
+export declare const noEmit: Emit;
+/** The emitter for a CLI run: the run's environment, telemetry folder, version, and clock. */
+export declare const emitOf: (deps: {
+    env: NodeJS.ProcessEnv;
+    telemetry?: TelemetryRuntime | undefined;
+    version: string;
+    now: () => number;
+}) => Emit;

package/dist/telemetry/emit.js

@@ -0,0 +1,42 @@
+// The one way a part of oars records an event: it checks the switches, passes the closed schema through `recordEvent`, and never throws,
+// so no command's exit code or output can depend on it. A working path holds one `Emit`: one call, consent checked, so the line it carries is the whole cost to its caller.
+import { consentOf } from './consent.js';
+import { recordEvent } from './record.js';
+/** Whether this run records at all: a folder is set and consent is on. A caller that must do work to build an event asks first, so an opt-out pays nothing. */
+export const recordsEvents = (emitter) => {
+    try {
+        return emitter.telemetry !== undefined && consentOf(emitter.env, emitter.telemetry.dir).enabled;
+    }
+    catch {
+        return false;
+    }
+};
+export const emitEvent = (emitter, type, fields) => {
+    try {
+        const runtime = emitter.telemetry;
+        if (runtime === undefined || !consentOf(emitter.env, runtime.dir).enabled)
+            return;
+        recordEvent({ ...runtime, version: emitter.version, now: emitter.now }, type, fields);
+    }
+    catch {
+        // Telemetry is never allowed to change what a command or hook does.
+    }
+};
+export const emitFor = ({ env, telemetry, version, now }) => {
+    const emitter = {
+        env,
+        telemetry,
+        // A getter, so `emitEvent` reads the version only after consent says an event will be written.
+        get version() {
+            return version();
+        },
+        now,
+    };
+    return (type, fields) => {
+        emitEvent(emitter, type, fields);
+    };
+};
+/** An emitter that records nothing, for a caller built without telemetry. */
+export const noEmit = () => undefined;
+/** The emitter for a CLI run: the run's environment, telemetry folder, version, and clock. */
+export const emitOf = (deps) => emitFor({ env: deps.env, telemetry: deps.telemetry, version: () => deps.version, now: deps.now });

package/dist/telemetry/fields.d.ts

@@ -0,0 +1,16 @@
+import type { Recall } from '../sessions/recall-object.js';
+/** The harness every hook oars installs runs under (Claude Code); one spelling for the session hooks and the gate hook, so the two emitters cannot drift. */
+export declare const HOOK_HARNESS = "claude-code";
+/** The harness a hook ran under, as the closed list names it, else `other`. */
+export declare const harnessWord: (harness: string) => string;
+/**
+ * The harness, harness version, and model a hook saw, as the public vocabulary knows them or `other`; a version or model the hook did not see is absent. A hook fire names its harness (the
+ * recall's frame when a push made one); the nightly task runs under none, so its caller passes `undefined` and the event carries no harness (it reads as `unrecorded`).
+ */
+export declare const frameWords: (harness: string | undefined, harnessVersion: string | null | undefined, model: string | null | undefined) => {
+    harness?: string;
+    harnessVersion?: string;
+    model?: string;
+};
+/** A recall as counts: how it was asked, which families it served, how many reads and evidence rows, the size of the answer, and its arm. Never the query text, a name, or the rendered answer. */
+export declare const recallFields: (recall: Recall, families: readonly string[], legacy?: boolean) => object;

package/dist/telemetry/fields.js

@@ -0,0 +1,26 @@
+import { HARNESSES, OTHER } from '../sessions/pool-wire.js';
+import { modelWord, versionWord } from './schema.js';
+/** The harness every hook oars installs runs under (Claude Code); one spelling for the session hooks and the gate hook, so the two emitters cannot drift. */
+export const HOOK_HARNESS = 'claude-code';
+/** The harness a hook ran under, as the closed list names it, else `other`. */
+export const harnessWord = (harness) => (HARNESSES.some((known) => known === harness) ? harness : OTHER);
+/**
+ * The harness, harness version, and model a hook saw, as the public vocabulary knows them or `other`; a version or model the hook did not see is absent. A hook fire names its harness (the
+ * recall's frame when a push made one); the nightly task runs under none, so its caller passes `undefined` and the event carries no harness (it reads as `unrecorded`).
+ */
+export const frameWords = (harness, harnessVersion, model) => ({
+    ...(harness === undefined ? {} : { harness: harnessWord(harness) }),
+    ...(harnessVersion === undefined || harnessVersion === null ? {} : { harnessVersion: versionWord(harnessVersion) }),
+    ...(model === undefined || model === null ? {} : { model: modelWord(model) }),
+});
+/** A recall as counts: how it was asked, which families it served, how many reads and evidence rows, the size of the answer, and its arm. Never the query text, a name, or the rendered answer. */
+export const recallFields = (recall, families, legacy = false) => ({
+    form: legacy ? 'legacy' : recall.query.form,
+    mode: recall.mode,
+    families: [...new Set(families)],
+    kind: recall.answer.kind,
+    reads: recall.answer.reads.length,
+    evidence: recall.evidence.length,
+    tokens: recall.answer.tokens,
+    arm: recall.arm,
+});

package/dist/telemetry/health.d.ts

@@ -0,0 +1,21 @@
+import { type SessionsRuntime } from '../sessions/store.js';
+import { type Emitter } from './emit.js';
+/** What the nightly run needs to record: the emitter, and a reader for the process's peak memory (a test sets it). */
+export interface NightlyTelemetry extends Emitter {
+    peakRssMb?: () => number;
+}
+/**
+ * The distinct values seen, each kept when the pool wire's own public vocabulary admits it and written as `other` when it does not, sorted with `other`
+ * last. More than the schema's list length folds the tail into `other`.
+ */
+export declare const closedList: (values: readonly string[], kind: "version" | "model") => string[];
+/** The distinct whole-number versions among the stamps, ascending; a stamp that is not a whole number names no version and is left out. */
+export declare const versionsHeld: (stamps: readonly string[]) => number[];
+/** The store-health event of one nightly run. A store that cannot be read is recorded as that and nothing else; it never stops the run. */
+export declare const recordStoreHealth: (telemetry: NightlyTelemetry, runtime: SessionsRuntime) => Promise<void>;
+/** What a nightly run cost: the whole run, the deposit's parse, the process's peak memory, and whether it failed. */
+export declare const recordRunCost: (telemetry: NightlyTelemetry, cost: {
+    totalMs: number;
+    parseMs: number;
+    failed: boolean;
+}) => void;