@manyoars/oars 0.3.0 → 0.4.0

package/dist/telemetry/spool.d.ts

@@ -0,0 +1,17 @@
+/** One mebibyte per file, so the folder holds at most two. */
+export declare const SPOOL_CAP_BYTES = 1048576;
+export declare const spoolPaths: (dir: string) => {
+    current: string;
+    previous: string;
+    idFile: string;
+    settings: string;
+};
+/**
+ * This install's id: a random version 4 UUID made on first use and kept in the folder. It comes from the system's random source, never from the
+ * machine, the user, or a path, so deleting the file starts a new, unrelated id.
+ */
+export declare const installId: (dir: string) => string;
+/** Appends one line, rotating first when it would pass `capBytes`; a line larger than the cap on its own is not written. */
+export declare const appendLine: (dir: string, line: string, capBytes?: number) => void;
+/** Every spooled line, oldest first. */
+export declare const readSpool: (dir: string) => string[];

package/dist/telemetry/spool.js

@@ -0,0 +1,70 @@
+// The telemetry folder: a per-install random id, and an append-only spool of one JSON event per line. Nothing here sends anything. The spool is
+// capped: when a line would pass the cap, the current file becomes the old file (replacing the one before) and a new one starts, so the folder
+// never holds more than twice the cap.
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** One mebibyte per file, so the folder holds at most two. */
+export const SPOOL_CAP_BYTES = 1_048_576;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+export const spoolPaths = (dir) => ({
+    current: join(dir, 'events.jsonl'),
+    previous: join(dir, 'events.1.jsonl'),
+    idFile: join(dir, 'install-id'),
+    settings: join(dir, 'settings.json'),
+});
+const readIfPresent = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * This install's id: a random version 4 UUID made on first use and kept in the folder. It comes from the system's random source, never from the
+ * machine, the user, or a path, so deleting the file starts a new, unrelated id.
+ */
+export const installId = (dir) => {
+    const { idFile } = spoolPaths(dir);
+    const existing = readIfPresent(idFile);
+    const kept = existing?.trim();
+    if (kept !== undefined && UUID.test(kept))
+        return kept;
+    mkdirSync(dir, { recursive: true });
+    const fresh = randomUUID();
+    try {
+        // Exclusive when no file stood there, so two first runs at once cannot each keep their own id; a file that is not an id is replaced.
+        writeFileSync(idFile, `${fresh}\n`, { flag: existing === undefined ? 'wx' : 'w' });
+        return fresh;
+    }
+    catch (error) {
+        const winner = readIfPresent(idFile)?.trim();
+        if (winner !== undefined && UUID.test(winner))
+            return winner;
+        throw error;
+    }
+};
+/** Appends one line, rotating first when it would pass `capBytes`; a line larger than the cap on its own is not written. */
+export const appendLine = (dir, line, capBytes = SPOOL_CAP_BYTES) => {
+    const { current, previous } = spoolPaths(dir);
+    const bytes = Buffer.byteLength(line) + 1;
+    if (bytes > capBytes)
+        return;
+    mkdirSync(dir, { recursive: true });
+    let size = 0;
+    try {
+        size = statSync(current).size;
+    }
+    catch {
+        // No spool yet.
+    }
+    if (size + bytes > capBytes)
+        renameSync(current, previous);
+    appendFileSync(current, `${line}\n`);
+};
+/** Every spooled line, oldest first. */
+export const readSpool = (dir) => {
+    const { current, previous } = spoolPaths(dir);
+    return [previous, current].flatMap((path) => (readIfPresent(path) ?? '').split('\n').filter((line) => line !== ''));
+};

package/dist/telemetry/wire.d.ts

@@ -0,0 +1,25 @@
+import { type Emitter } from './emit.js';
+/** One field across the batches of a pass: in how many it appeared, and the bytes of its values (a field that holds others counts them too). */
+interface FieldTally {
+    present: number;
+    bytes: number;
+}
+interface HarnessTally {
+    batches: number;
+    bytes: number;
+    fields: Map<string, FieldTally>;
+}
+/** The tally of one deposit pass, by the harness that wrote each batch. */
+export type WireTally = Map<string, HarnessTally>;
+export declare const newTally: () => WireTally;
+/** Adds one batch (the parsed skeleton, before it is written) to the tally. It never throws: a batch it cannot read (a cycle) adds nothing, and the deposit goes on. */
+export declare const tallyBatch: (tally: WireTally, batch: unknown) => void;
+/** One `wire` event for each harness the pass built a batch for: the names, and beside them the batches that held each and the bytes it took. */
+export declare const recordWire: (emitter: Emitter, tally: WireTally) => void;
+/** One send of one batch. `code` is the pool's own word for a refusal; the schema drops anything that is not a code. */
+export declare const recordSend: (emitter: Emitter, send: {
+    status: number;
+    code?: string | undefined;
+    bytes: number;
+}) => void;
+export {};

package/dist/telemetry/wire.js

@@ -0,0 +1,76 @@
+// Wire policing: what each deposit batch carried and what a send came to, so a field that is narrow (rarely present) or costly (many bytes nobody reads)
+// shows up. Field names are only those of the register (`FIELD_ROWS`, the same list `oars pool outbox --explain` answers from); a value is never read
+// past its size, and a name the register does not hold is not counted.
+import { FIELD_ROWS } from '../sessions/pool-outbox.js';
+import { HARNESSES, OTHER } from '../sessions/pool-wire.js';
+import { emitEvent } from './emit.js';
+export const newTally = () => new Map();
+const REGISTER = new Set(Object.keys(FIELD_ROWS));
+/** JSON.stringify answers `undefined` for a value it leaves out, which its signature does not say. */
+const asText = (value) => JSON.stringify(value);
+/** The bytes of a value as JSON; a value JSON leaves out (`undefined`) is not on the wire and has none. */
+const sizeOf = (value) => {
+    const text = asText(value);
+    return text === undefined ? 0 : Buffer.byteLength(text);
+};
+const harnessOf = (batch) => {
+    const transcripts = typeof batch === 'object' && batch !== null ? Reflect.get(batch, 'transcripts') : undefined;
+    const first = Array.isArray(transcripts) ? transcripts[0] : undefined;
+    const harness = typeof first === 'object' && first !== null ? Reflect.get(first, 'harness') : undefined;
+    return typeof harness === 'string' && HARNESSES.some((known) => known === harness) ? harness : OTHER;
+};
+const walk = (value, seen) => {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            walk(entry, seen);
+    }
+    else if (typeof value === 'object' && value !== null) {
+        for (const [name, entry] of Object.entries(value)) {
+            if (REGISTER.has(name) && entry !== undefined)
+                seen.set(name, (seen.get(name) ?? 0) + sizeOf(entry));
+            walk(entry, seen);
+        }
+    }
+};
+const add = (tally, batch) => {
+    const harness = harnessOf(batch);
+    const entry = tally.get(harness) ?? { batches: 0, bytes: 0, fields: new Map() };
+    entry.batches += 1;
+    entry.bytes += sizeOf(batch);
+    const seen = new Map();
+    walk(batch, seen);
+    for (const [name, bytes] of seen) {
+        const field = entry.fields.get(name) ?? { present: 0, bytes: 0 };
+        field.present += 1;
+        field.bytes += bytes;
+        entry.fields.set(name, field);
+    }
+    tally.set(harness, entry);
+};
+/** Adds one batch (the parsed skeleton, before it is written) to the tally. It never throws: a batch it cannot read (a cycle) adds nothing, and the deposit goes on. */
+export const tallyBatch = (tally, batch) => {
+    try {
+        add(tally, batch);
+    }
+    catch {
+        // Telemetry is never allowed to change what a command does.
+    }
+};
+/** One `wire` event for each harness the pass built a batch for: the names, and beside them the batches that held each and the bytes it took. */
+export const recordWire = (emitter, tally) => {
+    for (const [harness, entry] of [...tally].sort(([a], [b]) => a.localeCompare(b))) {
+        const fields = [...entry.fields].sort(([a], [b]) => a.localeCompare(b));
+        emitEvent(emitter, 'wire', {
+            harness,
+            batches: entry.batches,
+            bytes: entry.bytes,
+            fields: fields.map(([name]) => name),
+            present: fields.map(([, field]) => field.present),
+            fieldBytes: fields.map(([, field]) => field.bytes),
+        });
+    }
+};
+/** One send of one batch. `code` is the pool's own word for a refusal; the schema drops anything that is not a code. */
+export const recordSend = (emitter, send) => {
+    emitEvent(emitter, 'wire-send', { sent: send.status === 201 ? 1 : 0, status: send.status, bytes: send.bytes, ...(send.code === undefined ? {} : { code: send.code }) });
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@manyoars/oars",
-  "version": "0.3.0",
-  "description": "The oars CLI: sign in, manage API keys, and keep a local memory of your own Claude Code sessions (on your machine; `oars sessions` uploads nothing except what `gold arms` sends through your own Claude subscription)",
+  "version": "0.4.0",
+  "description": "The oars CLI: sign in, manage API keys, and keep a local memory of your own coding-agent sessions on your machine. The session commands upload nothing except what `gold arms` sends through your own Claude subscription; telemetry (on by default) and the nightly pool send after you accept a pool covenant are described in the README",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",