@manyoars/oars 0.2.0 → 0.4.0

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;

package/dist/telemetry/health.js

@@ -0,0 +1,108 @@
+// What the nightly run tells telemetry about the health of an install: a snapshot of the session store (counts, sizes, verify results, the versions it
+// holds) and what the run cost. Counts, bytes, and closed words only; the schema checks them again before anything reaches the spool.
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CAPTURE_VERSION, OLDEST_READABLE_CAPTURE } from '../sessions/schema.js';
+import { readSteps } from '../sessions/steps.js';
+import { frozenSessions, loadStore, paths, readSkeletons } from '../sessions/store.js';
+import { LITERAL, publicModel, publicVersion } from '../sessions/public-vocabulary.js';
+import { verifyAll, verifyCaptured } from '../sessions/verify.js';
+import { emitEvent, recordsEvents } from './emit.js';
+import { spoolEvents } from './read-events.js';
+const MAX_LIST = 32;
+const OTHER = 'other';
+const WEEK_MS = 7 * 86_400_000;
+/**
+ * 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 const closedList = (values, kind) => {
+    const visible = kind === 'version' ? publicVersion : publicModel;
+    const kept = new Set();
+    let other = false;
+    for (const value of values) {
+        const shown = visible(value);
+        if (shown === null || shown === LITERAL || shown !== value)
+            other = true;
+        else
+            kept.add(value);
+    }
+    const sorted = [...kept].sort();
+    const room = MAX_LIST - 1;
+    if (sorted.length > room)
+        return [...sorted.slice(0, room), OTHER];
+    return other ? [...sorted, OTHER] : sorted;
+};
+/** 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 const versionsHeld = (stamps) => [...new Set(stamps.map(Number).filter((stamp) => Number.isSafeInteger(stamp) && stamp >= 0))].sort((a, b) => a - b).slice(-MAX_LIST);
+/** Every byte under a folder; a folder that is not there holds none. */
+const bytesUnder = async (dir) => {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return 0;
+        throw error;
+    }
+    let total = 0;
+    for (const entry of entries)
+        total += entry.isDirectory() ? await bytesUnder(join(dir, entry.name)) : (await stat(join(dir, entry.name))).size;
+    return total;
+};
+/** The bytes the last seven days of sends put on the wire, read from telemetry's own `wire-send` events: nothing is asked of the pool. */
+const egressBytes = (dir, now) => spoolEvents(dir, 'wire-send').reduce((total, { at, data }) => (data.sent === 1 && typeof data.bytes === 'number' && Date.parse(at) >= now - WEEK_MS ? total + data.bytes : total), 0);
+/** The extractor version each pipeline step last ran at: the log is append-only, so older rows name versions the store no longer holds. A tie on `at` goes to the later row. */
+const lastExtractorVersions = (steps) => {
+    const latest = new Map();
+    for (const step of steps) {
+        const held = latest.get(step.step);
+        if (held === undefined || Date.parse(step.at) >= Date.parse(held.at))
+            latest.set(step.step, step);
+    }
+    return [...latest.values()].map((step) => step.ev);
+};
+const storeFields = async (runtime) => {
+    const { storeDir } = runtime;
+    const { skeletons, unreadable } = await readSkeletons(storeDir, undefined, true);
+    const store = await loadStore(storeDir);
+    const steps = await readSteps(storeDir);
+    const captured = [...store.sessions, ...store.subagents];
+    const frozen = await frozenSessions(runtime, captured.filter((session) => Number(session.cv) >= OLDEST_READABLE_CAPTURE && Number(session.cv) < Number(CAPTURE_VERSION)));
+    const results = [...verifyAll(skeletons, skeletons), ...verifyCaptured(captured, store.tools, frozen)];
+    return {
+        sessions: store.sessions.length,
+        subagents: store.subagents.length,
+        skeletons: skeletons.length,
+        unparseable: unreadable + captured.reduce((sum, session) => sum + session.badLines, 0),
+        rawBytes: await bytesUnder(paths(storeDir).raw),
+        verifyChecked: results.length,
+        verifyFailed: results.filter((result) => result.violations > 0).length,
+        // What the store holds: the `cv` of each captured session and the `ev` each pipeline step last ran at. A store with a session behind this build lists two.
+        captureVersions: versionsHeld(captured.map((session) => session.cv)),
+        extractorVersions: versionsHeld(lastExtractorVersions(steps)),
+        harnessVersions: closedList(captured.flatMap((session) => session.versions), 'version'),
+        models: closedList(captured.flatMap((session) => Object.keys(session.models)), 'model'),
+    };
+};
+/** 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 const recordStoreHealth = async (telemetry, runtime) => {
+    // The pass reads every skeleton and stats every raw file, so an install with telemetry off must not start it.
+    if (!recordsEvents(telemetry))
+        return;
+    try {
+        const fields = await storeFields(runtime);
+        // The outbox is an extra: a folder that cannot be read leaves the two figures out and the snapshot stands.
+        const extras = await bytesUnder(join(runtime.storeDir, 'pool-outbox')).then((outboxBytes) => ({ outboxBytes, egressBytes: egressBytes(telemetry.telemetry?.dir ?? '', telemetry.now()) }), () => ({}));
+        emitEvent(telemetry, 'store-health', { ...fields, ...extras });
+    }
+    catch {
+        emitEvent(telemetry, 'store-health', { readFailed: 1 });
+    }
+};
+/** What a nightly run cost: the whole run, the deposit's parse, the process's peak memory, and whether it failed. */
+export const recordRunCost = (telemetry, cost) => {
+    const peak = telemetry.peakRssMb ?? (() => Math.round(process.resourceUsage().maxRSS / 1024));
+    emitEvent(telemetry, 'run-cost', { totalMs: Math.max(0, cost.totalMs), parseMs: Math.max(0, cost.parseMs), peakRssMb: peak(), failed: cost.failed ? 1 : 0 });
+};

package/dist/telemetry/hook-emit.d.ts

@@ -0,0 +1,4 @@
+import { type Emit } from './emit.js';
+/** The version in the package.json at `manifest`; `0.0.0` when it cannot be read (the schema writes a version it cannot read as `unknown`). */
+export declare const versionAt: (manifest: URL) => string;
+export declare const hookEmitter: (env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string, manifest: URL, now: () => number) => Emit;

package/dist/telemetry/hook-emit.js

@@ -0,0 +1,18 @@
+// The emitter a hook process builds for itself. A hook never loads the CLI (`main.ts` reads the version and the folders), so this reads the same two things for itself:
+// the config folder the CLI uses, and the version in this package's `package.json`, read only when an event is about to be written.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultConfigDir } from '../credentials.js';
+import { emitFor } from './emit.js';
+/** The version in the package.json at `manifest`; `0.0.0` when it cannot be read (the schema writes a version it cannot read as `unknown`). */
+export const versionAt = (manifest) => {
+    try {
+        const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+        const version = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'version') : undefined;
+        return typeof version === 'string' ? version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+export const hookEmitter = (env, platform, home, manifest, now) => emitFor({ env, telemetry: { dir: join(defaultConfigDir(env, platform, home), 'oars', 'telemetry'), platform }, version: () => versionAt(manifest), now });

package/dist/telemetry/measures.d.ts

@@ -0,0 +1,32 @@
+/** A latency in a cell, or a yes (1) or no (0) that a rate is made from. */
+export type Kind = 'latency' | 'rate';
+export interface Measure {
+    metric: string;
+    /** What the value groups by: the harness and harness version a hook ran under (`claude-code/2.1.5`), or the oars version for a command. */
+    dimension: 'harnessVersion' | 'cli';
+    value: string;
+    kind: Kind;
+    /** Milliseconds for a latency; 1 or 0 for a rate. */
+    x: number;
+}
+/** The windows the report shows and the pool serves, in days. */
+export declare const WINDOWS: readonly number[];
+/** The hooks that exist; any other name in a batch is not measured. */
+export declare const HOOK_NAMES: readonly string[];
+export declare const OTHER = "other";
+export declare const UNRECORDED = "unrecorded";
+/** What one event measures; an event of a type nothing measures, or that is not an object, measures nothing. */
+export declare const measuresOf: (event: unknown) => Measure[];
+/** Every cell is named by these three together. */
+export declare const cellKey: (measure: Pick<Measure, "metric" | "dimension" | "value">) => string;
+/**
+ * The bucket edges a latency histogram counts in, each 1.5 times the one before (1, 2, 3, 4, 6, 9, ...) up to a day. The pool keeps a histogram, not the latencies, so its percentile is the
+ * upper edge of the bucket that holds it: within a factor of 1.5 of the true one.
+ */
+export declare const LATENCY_EDGES: readonly number[];
+/** The index of the first edge at or above the latency. */
+export declare const bucketOf: (milliseconds: number) => number;
+/** The p-th percentile (0 to 1) of a histogram given as [bucket index, count] pairs, as that bucket's upper edge. */
+export declare const histogramPercentile: (buckets: readonly (readonly [number, number])[], p: number) => number;
+/** The nearest-rank p-th percentile (0 to 1) of numbers; 0 for none. */
+export declare const percentile: (values: readonly number[], p: number) => number;

package/dist/telemetry/measures.js

@@ -0,0 +1,128 @@
+// What telemetry measures, in one place: the CLI's own report and the pool's rollup both turn an event into the same `Measure`s, so a user's number and the fleet's are the same number.
+// A measure is one observation in a cell: a latency in milliseconds, or a yes/no that rates are made from. The cell is (metric, dimension, value): `hook.pre-tool.latency` at harness
+// `claude-code`, version `2.1.5`. The reader is tolerant on purpose: the pool reads batches kept whole from any client, so a value that does not fit is skipped, never trusted.
+import { isHarness } from '../sessions/pool-wire.js';
+/** The windows the report shows and the pool serves, in days. */
+export const WINDOWS = [7, 30];
+const DAY_MS = 86_400_000;
+/** The hooks that exist; any other name in a batch is not measured. */
+export const HOOK_NAMES = ['session-start', 'prompt', 'pre-tool', 'post-tool', 'stop', 'nightly', 'gate'];
+/** A group value as the program writes it: a version or a word, short, with no space, slash, or quote. Anything else is `other`. */
+const VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+const COMMAND = /^[a-z][A-Za-z0-9-]{0,31}$/;
+export const OTHER = 'other';
+export const UNRECORDED = 'unrecorded';
+const valueOf = (raw) => {
+    if (raw === undefined)
+        return UNRECORDED;
+    return typeof raw === 'string' && VALUE.test(raw) ? raw : OTHER;
+};
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const fieldOf = (value, key) => (isObject(value) ? Reflect.get(value, key) : undefined);
+/** A whole number of milliseconds a day long at most, or undefined. */
+const millis = (value) => (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= DAY_MS ? value : undefined);
+const latency = (metric, dimension, value, x) => ({ metric, dimension, value, kind: 'latency', x });
+const rate = (metric, dimension, value, yes) => ({ metric, dimension, value, kind: 'rate', x: yes ? 1 : 0 });
+/**
+ * The value of a hook cell: the harness and its version, `claude-code/2.1.5`, so one version number under two harnesses is two cells. A harness off the closed list is `other`; an event written
+ * before the field existed has none and reads `unrecorded`, never dropped.
+ */
+const hookCellOf = (harness, version) => {
+    const named = harness === undefined ? UNRECORDED : typeof harness === 'string' && isHarness(harness) ? harness : OTHER;
+    return `${named}/${valueOf(version)}`;
+};
+/** The measures of a `hook` event: its latency, and whether it found something. A hook that failed is neither a hit nor a miss. */
+const hookMeasures = (data) => {
+    const name = fieldOf(data, 'name');
+    if (typeof name !== 'string' || !HOOK_NAMES.includes(name))
+        return [];
+    const version = hookCellOf(fieldOf(data, 'harness'), fieldOf(data, 'harnessVersion'));
+    const found = [];
+    const took = millis(fieldOf(data, 'latencyMs'));
+    if (took !== undefined)
+        found.push(latency(`hook.${name}.latency`, 'harnessVersion', version, took));
+    const outcome = fieldOf(data, 'outcome');
+    // `held` found something and held it back for the unexposed arm, so it counts as a find.
+    if (outcome === 'hit' || outcome === 'held')
+        found.push(rate(`hook.${name}.hit`, 'harnessVersion', version, true));
+    else if (outcome === 'miss')
+        found.push(rate(`hook.${name}.hit`, 'harnessVersion', version, false));
+    return found;
+};
+/** The measures of a `command` event: how long it took, and whether it failed, under the first name of its path. */
+const commandMeasures = (event, data) => {
+    const path = fieldOf(data, 'path');
+    const first = Array.isArray(path) && typeof path[0] === 'string' && COMMAND.test(path[0]) ? path[0] : 'none';
+    const version = valueOf(fieldOf(event, 'cli'));
+    const found = [];
+    const took = millis(fieldOf(data, 'durationMs'));
+    if (took !== undefined)
+        found.push(latency(`command.${first}.latency`, 'cli', version, took));
+    const exit = fieldOf(data, 'exitCode');
+    if (typeof exit === 'number' && Number.isSafeInteger(exit) && exit >= 0 && exit <= 255)
+        found.push(rate(`command.${first}.failure`, 'cli', version, exit !== 0));
+    return found;
+};
+/** The measures of a `store-health` event: whether the nightly could read the store, and whether it found a session that does not verify. */
+const storeMeasures = (event, data) => {
+    const version = valueOf(fieldOf(event, 'cli'));
+    const unread = fieldOf(data, 'readFailed') === 1;
+    const found = [rate('store.readFailure', 'cli', version, unread)];
+    const failed = fieldOf(data, 'verifyFailed');
+    if (!unread && typeof failed === 'number' && Number.isSafeInteger(failed) && failed >= 0)
+        found.push(rate('store.verifyFailure', 'cli', version, failed > 0));
+    return found;
+};
+/** What one event measures; an event of a type nothing measures, or that is not an object, measures nothing. */
+export const measuresOf = (event) => {
+    const type = fieldOf(event, 'type');
+    const data = fieldOf(event, 'data');
+    switch (type) {
+        case 'hook':
+            return hookMeasures(data);
+        case 'command':
+            return commandMeasures(event, data);
+        case 'store-health':
+            return storeMeasures(event, data);
+        default:
+            return [];
+    }
+};
+/** Every cell is named by these three together. */
+export const cellKey = (measure) => `${measure.metric}\u0000${measure.dimension}\u0000${measure.value}`;
+/**
+ * The bucket edges a latency histogram counts in, each 1.5 times the one before (1, 2, 3, 4, 6, 9, ...) up to a day. The pool keeps a histogram, not the latencies, so its percentile is the
+ * upper edge of the bucket that holds it: within a factor of 1.5 of the true one.
+ */
+export const LATENCY_EDGES = (() => {
+    const edges = [];
+    for (let step = 0;; step += 1) {
+        const edge = Math.ceil(1.5 ** step);
+        if (edges.at(-1) !== edge)
+            edges.push(edge);
+        if (edge >= DAY_MS)
+            return edges;
+    }
+})();
+/** The index of the first edge at or above the latency. */
+export const bucketOf = (milliseconds) => LATENCY_EDGES.findIndex((edge) => milliseconds <= edge);
+/** The p-th percentile (0 to 1) of a histogram given as [bucket index, count] pairs, as that bucket's upper edge. */
+export const histogramPercentile = (buckets, p) => {
+    const sorted = [...buckets].sort((a, b) => a[0] - b[0]);
+    const total = sorted.reduce((sum, [, count]) => sum + count, 0);
+    const target = Math.max(1, Math.ceil(p * total));
+    let seen = 0;
+    for (const [index, count] of sorted) {
+        seen += count;
+        if (seen >= target)
+            return LATENCY_EDGES[index] ?? DAY_MS;
+    }
+    return 0;
+};
+/** The nearest-rank p-th percentile (0 to 1) of numbers; 0 for none. */
+export const percentile = (values, p) => {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))] ?? 0;
+};

package/dist/telemetry/observe.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+import type { RunDeps } from '../cli.js';
+import type { ExitCode } from '../errors.js';
+export interface Observed {
+    /** The command path, such as `['pool', 'fetch']`; empty when no command ran (`--help`, `--version`, a usage error). */
+    path: string[];
+    /** The long names (as commander keys them) of the options given on the command line. */
+    flags: string[];
+}
+/** Called by commander just before an action runs. */
+export declare const observeCommand: (observed: Observed, action: Command) => void;
+/** Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. */
+export declare const finishTelemetry: (deps: RunDeps, argv: string[], observed: Observed, startedAt: number, exit: ExitCode) => void;

package/dist/telemetry/observe.js

@@ -0,0 +1,51 @@
+import { consentOf, markNoticeShown, NOTICE } from './consent.js';
+import { recordEvent } from './record.js';
+import { startDailySend } from './send.js';
+import { errorClassOf } from './schema.js';
+const pathOf = (command) => {
+    const names = [];
+    let step = command;
+    // The root program has no parent and is not part of the path.
+    while (step.parent !== null) {
+        names.unshift(step.name());
+        step = step.parent;
+    }
+    return names;
+};
+/** Called by commander just before an action runs. */
+export const observeCommand = (observed, action) => {
+    observed.path = pathOf(action);
+    const given = action.optsWithGlobals();
+    observed.flags = Object.keys(given).filter((key) => action.getOptionValueSourceWithGlobals(key) === 'cli');
+};
+const isHook = (argv, observed) => {
+    const gateHook = (words) => words[0] === 'gate' && words[1] === 'hook';
+    return gateHook(observed.path) || gateHook(argv);
+};
+/** Prints the notice on the first run that is not a hook, then records the event. Never throws and never changes what the command did. */
+export const finishTelemetry = (deps, argv, observed, startedAt, exit) => {
+    try {
+        const runtime = deps.telemetry;
+        if (runtime === undefined)
+            return;
+        const consent = consentOf(deps.env, runtime.dir);
+        if (!consent.enabled)
+            return;
+        if (!consent.noticeShown && !isHook(argv, observed) && markNoticeShown(runtime.dir, deps.now))
+            deps.io.stderr(`${NOTICE}\n`);
+        const errorClass = errorClassOf(exit);
+        recordEvent({ ...runtime, version: deps.version, now: deps.now }, 'command', {
+            path: observed.path,
+            flags: observed.flags,
+            durationMs: Math.max(0, deps.now() - startedAt),
+            exitCode: exit,
+            ...(errorClass === undefined ? {} : { errorClass }),
+        });
+        // Never from a hook: a hook has a time budget, and the send is for the nightly task and the commands a person runs.
+        if (!isHook(argv, observed))
+            startDailySend(runtime, deps.env, deps.now());
+    }
+    catch {
+        // Telemetry is never allowed to change what a command does.
+    }
+};

package/dist/telemetry/read-events.d.ts

@@ -0,0 +1,9 @@
+export interface SpoolEvent {
+    type: string;
+    at: string;
+    data: {
+        [field: string]: unknown;
+    };
+}
+/** Every spooled event, oldest first, or only those of `type`. */
+export declare const spoolEvents: (dir: string, type?: string) => SpoolEvent[];