@manyoars/oars 0.2.0 → 0.4.0

package/dist/telemetry/send.js

@@ -0,0 +1,172 @@
+// The sender: the only code that sends telemetry. It runs from the nightly task, and at most once a day from an interactive command as a detached process; never on a hook path, and
+// nothing waits for it. Before any byte leaves it calls `telemetrySendAllowed` (telemetry on, notice shown) and sends to the pool server in `OARS_POOL_URL`, else the Many Oars pool, the same default `oars pool`
+// reads and with the same rules (https, or http to this machine).
+//
+// A batch is up to 250 events. Only a 2xx clears what was sent; anything else (an error status, a redirect, a timeout, a refused connection) keeps the spool for the next try. That makes
+// delivery at least once: a batch the server kept whose answer was lost is sent again.
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultConfigDir } from '../credentials.js';
+import { telemetrySendAllowed } from './consent.js';
+import { installId, readSpool, spoolPaths } from './spool.js';
+/** The pool route takes at most this many events (Analytics Engine's per-request write limit). */
+export const BATCH_EVENTS = 250;
+/** One request's whole life, connect to last byte; a server that is slower than this is treated as down. */
+export const SEND_TIMEOUT_MS = 10_000;
+const DAY_MS = 86_400_000;
+const MARK = 'last-send';
+/** The pool server, validated the way `oars pool` does it, or undefined. The pool command's code is loaded only after sending is allowed, so a run with telemetry off or the notice unshown does not pay for it. */
+const serverOf = async (env) => {
+    try {
+        const { poolServer } = await import('../sessions/pool-command.js');
+        return poolServer(env, 'telemetry');
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The route answers 400 to an event whose `type` is not a string of 1 to 64 characters, and a failed batch blocks every later send, so such an object is junk here (the pool's `telemetry.ts` holds the rule). */
+const eventOf = (line) => {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const type = Reflect.get(parsed, 'type');
+        return typeof type === 'string' && type.length >= 1 && type.length <= 64 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** True only for a 2xx. A redirect is not followed: a pool never redirects a POST, and a 3xx from anything else is not the pool. */
+const post = async (url, install, events, deps) => {
+    try {
+        const response = await (deps.fetch ?? fetch)(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ install, events }),
+            redirect: 'manual',
+            signal: AbortSignal.timeout(deps.timeoutMs ?? SEND_TIMEOUT_MS),
+        });
+        await response.body?.cancel();
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
+/** Takes the sent lines out of the spool, by content and oldest first, so an event written after the read stays and a rotation in between does not matter. A file that cannot be rewritten keeps its lines, and they are sent again. */
+const dropLines = (dir, gone) => {
+    const counts = new Map();
+    for (const line of gone)
+        counts.set(line, (counts.get(line) ?? 0) + 1);
+    const { previous, current } = spoolPaths(dir);
+    for (const path of [previous, current]) {
+        try {
+            const lines = readFileSync(path, 'utf8')
+                .split('\n')
+                .filter((line) => line !== '');
+            const kept = lines.filter((line) => {
+                const left = counts.get(line) ?? 0;
+                if (left === 0)
+                    return true;
+                counts.set(line, left - 1);
+                return false;
+            });
+            if (kept.length === lines.length)
+                continue;
+            const scratch = `${path}.tmp`;
+            writeFileSync(scratch, kept.map((line) => `${line}\n`).join(''));
+            renameSync(scratch, path);
+        }
+        catch {
+            // No such file, or one another process holds: its lines stay, and a later send takes them.
+        }
+    }
+};
+export const writeMark = (dir, now) => {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, MARK), String(now));
+};
+/** Whether a day has passed since the last send was started. A missing, unreadable, or future mark counts as due. */
+export const dueForSend = (dir, now) => {
+    let last;
+    try {
+        last = Number(readFileSync(join(dir, MARK), 'utf8').trim());
+    }
+    catch {
+        return true;
+    }
+    return !Number.isFinite(last) || last > now || now - last >= DAY_MS;
+};
+/** Sends what the spool holds. Never throws. */
+export const sendSpool = async (deps) => {
+    const tally = { sent: 0, requests: 0 };
+    const finish = (outcome) => ({ outcome, ...tally });
+    if (!telemetrySendAllowed(deps.env, deps.dir))
+        return finish('not-allowed');
+    const server = await serverOf(deps.env);
+    if (server === undefined)
+        return finish('no-server');
+    try {
+        const events = [];
+        const junk = [];
+        for (const line of readSpool(deps.dir)) {
+            const event = eventOf(line);
+            if (event === undefined)
+                junk.push(line);
+            else
+                events.push({ line, event });
+        }
+        if (events.length === 0)
+            return finish('empty');
+        const install = installId(deps.dir);
+        writeMark(deps.dir, deps.now());
+        const sent = [];
+        let failed = false;
+        for (let at = 0; at < events.length && !failed; at += BATCH_EVENTS) {
+            const batch = events.slice(at, at + BATCH_EVENTS);
+            tally.requests += 1;
+            if (await post(`${server}/v1/telemetry`, install, batch.map(({ event }) => event), deps)) {
+                tally.sent += batch.length;
+                sent.push(...batch.map(({ line }) => line));
+            }
+            else
+                failed = true;
+        }
+        // A line that is not an event can never be sent, so it goes with the first batch the server takes.
+        if (sent.length > 0)
+            dropLines(deps.dir, [...sent, ...junk]);
+        return finish(failed ? 'failed' : 'sent');
+    }
+    catch {
+        return finish('failed');
+    }
+};
+/** The nightly task's send, in the telemetry folder under the config folder. */
+export const sendNightly = (env, platform, home, now) => sendSpool({ env, dir: join(defaultConfigDir(env, platform, home), 'oars', 'telemetry'), now });
+/**
+ * Called after an interactive command: starts one detached send, at most once a day, when sending is allowed. The mark is written first, so two commands at
+ * once start one. Nothing here throws or waits, and the run has no way to start a send unless `main.ts` gave it one.
+ */
+export const startDailySend = (runtime, env, now) => {
+    try {
+        if (runtime.spawnSend === undefined)
+            return;
+        if (!telemetrySendAllowed(env, runtime.dir) || !dueForSend(runtime.dir, now))
+            return;
+        writeMark(runtime.dir, now);
+        runtime.spawnSend(runtime.dir);
+    }
+    catch {
+        // Telemetry is never allowed to change what a command does.
+    }
+};
+/** Starts `send-main.js` detached with no stdio and never waits for it, as the gate's helper is started. */
+export const spawnDetachedSend = (dir, start = spawn) => {
+    const child = start(process.execPath, [fileURLToPath(new URL('./send-main.js', import.meta.url)), dir], { detached: true, stdio: 'ignore', windowsHide: true });
+    child.on('error', () => undefined);
+    child.unref();
+};

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.2.0",
-  "description": "The oars CLI: log in to Many Oars, list the starter templates, and deploy an agent",
+  "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",
@@ -17,7 +17,7 @@
   },
   "files": [
     "dist",
-    "parity/deploy-plans"
+    "vocab"
   ],
   "publishConfig": {
     "access": "public"
@@ -37,7 +37,6 @@
   "devDependencies": {
     "@playwright/test": "^1.64.1",
     "msw": "^3.0.3",
-    "typescript": "~5.9.3",
-    "yaml": "^2.9.1"
+    "typescript": "~5.9.3"
   }
 }