@manyoars/oars 0.4.1 → 0.5.2

package/dist/telemetry/observe.js

@@ -1,6 +1,7 @@
-import { consentOf, markNoticeShown, NOTICE } from './consent.js';
+import { consentOf, everShownNotice, markNoticeShown, NOTICE } from './consent.js';
 import { recordEvent } from './record.js';
 import { startDailySend } from './send.js';
+import { ciWord, installFolder, surfaceWord } from './fields.js';
 import { errorClassOf } from './schema.js';
 const pathOf = (command) => {
     const names = [];
@@ -18,12 +19,29 @@ export const observeCommand = (observed, action) => {
     const given = action.optsWithGlobals();
     observed.flags = Object.keys(given).filter((key) => action.getOptionValueSourceWithGlobals(key) === 'cli');
 };
-const isHook = (argv, observed) => {
+export 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) => {
+/**
+ * The `first-run` event, from the one place that shows the notice. `installPath` is where this copy runs from; only a test names it, and it is read here because it is needed on a first run only.
+ * Never throws: `oars telemetry on`, which shows the notice itself, calls it outside `finishTelemetry`'s guard.
+ */
+export const recordFirstRun = (deps, runtime, installPath) => {
+    try {
+        recordEvent({ ...runtime, version: deps.version, now: deps.now }, 'first-run', { ci: ciWord(deps.env), surface: surfaceWord(installPath ?? installFolder(), deps.env.npm_config_user_agent) });
+    }
+    catch {
+        // Telemetry is never allowed to change what a command does.
+    }
+};
+/** `--version` and `--help` end the parse before any action runs (so the path is empty); they stay a plain answer and leave the notice for the next command. */
+const isInfoOnly = (argv, observed) => observed.path.length === 0 && argv.some((word) => ['--version', '-V', '--help', '-h'].includes(word));
+/**
+ * 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. `installPath` is where this copy runs from; only a test names it,
+ * and it is read inside the guard because it is needed on a first run only.
+ */
+export const finishTelemetry = (deps, argv, observed, startedAt, exit, installPath) => {
     try {
         const runtime = deps.telemetry;
         if (runtime === undefined)
@@ -31,17 +49,26 @@ export const finishTelemetry = (deps, argv, observed, startedAt, exit) => {
         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`);
+        if (!consent.noticeShown && !isHook(argv, observed) && !isInfoOnly(argv, observed)) {
+            const seenBefore = everShownNotice(runtime.dir);
+            if (markNoticeShown(runtime.dir, deps.now)) {
+                deps.io.stderr(`${NOTICE}\n`);
+                // Once per install: an install that saw an older notice sees this one but records no second first-run; nothing is recorded or sent from a folder that could not claim it.
+                if (!seenBefore)
+                    recordFirstRun(deps, runtime, installPath);
+            }
+        }
         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,
+            ci: ciWord(deps.env),
+            ...(observed.cardLine === undefined ? {} : { cardLine: observed.cardLine }),
             ...(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.
+        // Never from a hook: a hook has a time budget, and the send is for the detached sender and the commands a person runs.
         if (!isHook(argv, observed))
             startDailySend(runtime, deps.env, deps.now());
     }

package/dist/telemetry/region.d.ts

@@ -0,0 +1,6 @@
+/** IANA zones of the EU, the EEA (Iceland, Liechtenstein, Norway), and the UK, with the outermost regions that sit outside `Europe/*` and `Europe/Mariehamn` (Åland). */
+export declare const CLOSED_ZONES: ReadonlySet<string>;
+/** True when the zone is on the closed list or cannot be read (absent or blank). */
+export declare const isClosedZone: (zone: string | undefined) => boolean;
+/** The machine's resolved IANA zone, or `undefined` when the runtime cannot say. */
+export declare const machineZone: () => string | undefined;

package/dist/telemetry/region.js

@@ -0,0 +1,28 @@
+// Where telemetry is off: a machine whose time zone is in the EU, the EEA, or the UK records and sends nothing, with no prompt (P97). The zone is the machine's own fact, so no network call
+// is made. An unresolvable zone counts as closed: the rule fails toward sending nothing.
+/** IANA zones of the EU, the EEA (Iceland, Liechtenstein, Norway), and the UK, with the outermost regions that sit outside `Europe/*` and `Europe/Mariehamn` (Åland). */
+export const CLOSED_ZONES = new Set([
+    // EU member states
+    'Europe/Vienna', 'Europe/Brussels', 'Europe/Sofia', 'Europe/Zagreb', 'Asia/Nicosia', 'Asia/Famagusta', 'Europe/Nicosia', 'Europe/Prague', 'Europe/Copenhagen',
+    'Europe/Tallinn', 'Europe/Helsinki', 'Europe/Mariehamn', 'Europe/Paris', 'Europe/Berlin', 'Europe/Busingen', 'Europe/Athens', 'Europe/Budapest', 'Europe/Dublin',
+    'Europe/Rome', 'Europe/Riga', 'Europe/Vilnius', 'Europe/Luxembourg', 'Europe/Malta', 'Europe/Amsterdam', 'Europe/Warsaw', 'Europe/Lisbon', 'Europe/Bucharest',
+    'Europe/Bratislava', 'Europe/Ljubljana', 'Europe/Madrid', 'Europe/Stockholm',
+    // EEA outside the EU, and the UK (with its legacy aliases). Europe/Jersey, Europe/Guernsey, and Europe/Isle_of_Man (Crown dependencies) and
+    // America/St_Barthelemy (outside the EU since 2012) are kept on purpose, to fail closed.
+    'Atlantic/Reykjavik', 'Iceland', 'Europe/Vaduz', 'Europe/Oslo', 'Arctic/Longyearbyen', 'Atlantic/Jan_Mayen', 'WET', 'CET', 'MET', 'EET', 'Europe/London', 'Europe/Belfast', 'Europe/Jersey', 'Europe/Guernsey', 'Europe/Isle_of_Man',
+    'GB', 'GB-Eire', 'Eire', 'Portugal', 'Poland',
+    // Outermost regions and island zones of member states
+    'Atlantic/Canary', 'Atlantic/Madeira', 'Atlantic/Azores', 'Africa/Ceuta', 'America/Martinique', 'America/Guadeloupe', 'America/Cayenne', 'Indian/Reunion', 'Indian/Mayotte',
+    'America/St_Barthelemy', 'America/Marigot',
+]);
+/** True when the zone is on the closed list or cannot be read (absent or blank). */
+export const isClosedZone = (zone) => zone === undefined || zone.trim() === '' || zone.trim() === 'Etc/Unknown' || CLOSED_ZONES.has(zone.trim());
+/** The machine's resolved IANA zone, or `undefined` when the runtime cannot say. */
+export const machineZone = () => {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/telemetry/report.js

@@ -167,7 +167,7 @@ export const textOf = (report, dir) => {
     const floor = fleet.status === 'answered' ? fleet.floor : 0;
     const out = [`Your telemetry, from the spool in ${dir}.`];
     if (report.windows.every((window) => window.cells.length === 0) && report.store === undefined)
-        out.push('Nothing is measured in the spool yet: the hooks and nightly task record as they run.');
+        out.push('Nothing is measured in the spool yet: the hooks and the detached sender record as they run.');
     for (const window of report.windows) {
         if (window.cells.length === 0)
             continue;

package/dist/telemetry/schema.d.ts

@@ -18,6 +18,9 @@ export declare const HOOK_OUTCOMES: readonly ["hit", "miss", "held", "error"];
 export declare const RECALL_FORMS: readonly ["pattern", "entity", "question", "text", "legacy"];
 export declare const RECALL_MODES: readonly ["pull", "push"];
 export declare const RECALL_ARMS: readonly ["shown", "held"];
+/** What the weekly card line did on a command: printed, held back by the holdback, or not due. */
+export declare const CARD_LINE_ARMS: readonly ["shown", "held", "not_due"];
+export type CardLineArm = (typeof CARD_LINE_ARMS)[number];
 /** The read families a recall can serve, as the program names them. */
 export declare const RECALL_FAMILY_NAMES: readonly ["recovery", "fit", "cost", "change", "live", "adoption", "method", "next-step", "tool-day", "version-boundary", "substitution", "interaction", "day-move", "entity"];
 export declare const FETCH_HARNESSES: readonly ["claude-code", "cursor", "codex", "copilot", "gemini", "grok", "opencode", "pi", "vscode-copilot", "otel", "other"];

package/dist/telemetry/schema.js

@@ -6,6 +6,7 @@ import { ExitCode } from '../errors.js';
 import { FIELD_ROWS } from '../sessions/pool-outbox.js';
 import { OTHER, HARNESSES } from '../sessions/pool-wire.js';
 import { LITERAL, publicModel, publicVersion } from '../sessions/public-vocabulary.js';
+import { CI_WORDS, SURFACE_WORDS } from './words.js';
 /** Bumped when an event type or field changes meaning; every spooled event carries it. */
 export const SCHEMA_VERSION = 1;
 /** A command or option name as the program defines it: letters, digits, and hyphens. No space, slash, dot, colon, or quote. */
@@ -36,6 +37,9 @@ const hex = (digits) => (value) => typeof value === 'string' && new RegExp(`^[0-
 /** A problem code as a server names it: lowercase words joined with underscores. No space, slash, dot, colon, or quote, so no path, URL, or sentence fits. */
 const CODE = /^[a-z][a-z0-9_]{0,39}$/;
 const code = (value) => (typeof value === 'string' && CODE.test(value) ? value : undefined);
+/** A covenant version as the pool names it: a short word of letters, digits, dots, underscores, and hyphens. A text off that shape (the pool is any server the operator names) is dropped, not trimmed. */
+const COVENANT_VERSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+const covenantVersion = (value) => (typeof value === 'string' && COVENANT_VERSION.test(value) ? value : undefined);
 const rules = (fields) => new Map(Object.entries(fields));
 const DAY_MS = 86_400_000;
 /** What went wrong, as a closed word chosen from the exit code; the error's own text never comes here. */
@@ -48,6 +52,8 @@ export const HOOK_OUTCOMES = ['hit', 'miss', 'held', 'error'];
 export const RECALL_FORMS = ['pattern', 'entity', 'question', 'text', 'legacy'];
 export const RECALL_MODES = ['pull', 'push'];
 export const RECALL_ARMS = ['shown', 'held'];
+/** What the weekly card line did on a command: printed, held back by the holdback, or not due. */
+export const CARD_LINE_ARMS = ['shown', 'held', 'not_due'];
 /** The read families a recall can serve, as the program names them. */
 export const RECALL_FAMILY_NAMES = ['recovery', 'fit', 'cost', 'change', 'live', 'adoption', 'method', 'next-step', 'tool-day', 'version-boundary', 'substitution', 'interaction', 'day-move', 'entity'];
 export const FETCH_HARNESSES = ['claude-code', 'cursor', 'codex', 'copilot', 'gemini', 'grok', 'opencode', 'pi', 'vscode-copilot', 'otel', 'other'];
@@ -63,7 +69,7 @@ const WIRE_HARNESSES = [...HARNESSES, OTHER];
 const WIRE_LENGTH = WIRE_NAMES.size;
 /** One line per event type. */
 const EVENTS = new Map([
-    ['command', rules({ path: tokens(4), flags: tokens(40), durationMs: whole(DAY_MS), exitCode: whole(255), errorClass: oneOf(ERROR_CLASSES) })],
+    ['command', rules({ path: tokens(4), flags: tokens(40), durationMs: whole(DAY_MS), exitCode: whole(255), errorClass: oneOf(ERROR_CLASSES), ci: oneOf(CI_WORDS), cardLine: oneOf(CARD_LINE_ARMS) })],
     ['hook', rules({ name: oneOf(HOOK_NAMES), latencyMs: whole(DAY_MS), outcome: oneOf(HOOK_OUTCOMES), bytes: whole(BYTES), harness: oneOf(WIRE_HARNESSES), harnessVersion: MODEL_OR_VERSION(versionWord), model: MODEL_OR_VERSION(modelWord) })],
     [
         'recall',
@@ -128,6 +134,10 @@ const EVENTS = new Map([
     ],
     // One send of one batch: whether the pool took it, the HTTP status, and the code of its refusal.
     ['wire-send', rules({ sent: whole(1), status: whole(599), code, bytes: whole(HUGE) })],
+    // The install's first run, sent once where the first-run notice is shown (docs/telemetry.md).
+    ['first-run', rules({ ci: oneOf(CI_WORDS), surface: oneOf(SURFACE_WORDS) })],
+    // The CLI told the operator which covenant to read and accept: the version and nothing else.
+    ['covenant-shown', rules({ version: covenantVersion })],
 ]);
 export const EVENT_TYPES = [...EVENTS.keys()];
 /** The field names a type admits, so a test can feed every one. */

package/dist/telemetry/send.d.ts

@@ -14,7 +14,7 @@ export interface SendDeps {
     timeoutMs?: number;
 }
 export interface SendResult {
-    outcome: 'sent' | 'failed' | 'empty' | 'not-allowed' | 'no-server';
+    outcome: 'sent' | 'failed' | 'empty' | 'not-allowed' | 'no-server' | 'not-due';
     /** Events the server took (and that were cleared from the spool). */
     sent: number;
     /** Requests made, including one that failed. */
@@ -25,7 +25,10 @@ export declare const writeMark: (dir: string, now: number) => void;
 export declare const dueForSend: (dir: string, now: number) => boolean;
 /** Sends what the spool holds. Never throws. */
 export declare const sendSpool: (deps: SendDeps) => Promise<SendResult>;
-/** The nightly task's send, in the telemetry folder under the config folder. */
+/**
+ * The detached sender's telemetry send, in the telemetry folder under the config folder. The sender runs up to about hourly, but telemetry goes at most once a
+ * day, on the same mark a command's daily send uses; events recorded by the runs in between wait in the spool for the next day's batch.
+ */
 export declare const sendNightly: (env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string, now: () => number) => Promise<SendResult>;
 /**
  * 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

package/dist/telemetry/send.js

@@ -1,4 +1,4 @@
-// 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
+// The sender: the only code that sends telemetry. It runs from the detached sender (hook-bin.js nightly), 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).
 //
@@ -9,7 +9,7 @@ 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 { shownNoticeVersion, 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;
@@ -41,12 +41,12 @@ const eventOf = (line) => {
     }
 };
 /** 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) => {
+const post = async (url, install, notice, events, deps) => {
     try {
         const response = await (deps.fetch ?? fetch)(url, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ install, events }),
+            body: JSON.stringify({ install, notice, events }),
             redirect: 'manual',
             signal: AbortSignal.timeout(deps.timeoutMs ?? SEND_TIMEOUT_MS),
         });
@@ -129,7 +129,7 @@ export const sendSpool = async (deps) => {
         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)) {
+            if (await post(`${server}/v1/telemetry`, install, shownNoticeVersion(deps.dir), batch.map(({ event }) => event), deps)) {
                 tally.sent += batch.length;
                 sent.push(...batch.map(({ line }) => line));
             }
@@ -145,8 +145,16 @@ export const sendSpool = async (deps) => {
         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 });
+/**
+ * The detached sender's telemetry send, in the telemetry folder under the config folder. The sender runs up to about hourly, but telemetry goes at most once a
+ * day, on the same mark a command's daily send uses; events recorded by the runs in between wait in the spool for the next day's batch.
+ */
+export const sendNightly = async (env, platform, home, now) => {
+    const dir = join(defaultConfigDir(env, platform, home), 'oars', 'telemetry');
+    if (!dueForSend(dir, now()))
+        return { outcome: 'not-due', sent: 0, requests: 0 };
+    return sendSpool({ env, dir, 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.

package/dist/telemetry/words.d.ts

@@ -0,0 +1,6 @@
+/** Whether a run was in CI and by which provider: the word is chosen from the provider's own variable (`ciWord` in `fields.ts`), so the variable's value never reaches the spool. `other` is a bare `CI`. */
+export declare const CI_WORDS: readonly ["none", "github-actions", "gitlab-ci", "circleci", "travis-ci", "jenkins", "buildkite", "azure-pipelines", "bitbucket", "teamcity", "appveyor", "codebuild", "other"];
+export type CiWord = (typeof CI_WORDS)[number];
+/** How this copy of oars arrived, from the folder it runs in and the package manager that started it (`surfaceWord` in `fields.ts`); the path itself never reaches the spool. A folder it cannot place is `unknown`. */
+export declare const SURFACE_WORDS: readonly ["npm-global", "npx", "claude-plugin", "codex-plugin", "gemini-extension", "unknown"];
+export type SurfaceWord = (typeof SURFACE_WORDS)[number];

package/dist/telemetry/words.js

@@ -0,0 +1,6 @@
+// The two closed word lists the pool's rollup reads (`measures.ts`) beside the schema that checks them (`schema.ts`). A leaf on purpose: it imports nothing, so a Worker that imports it takes no
+// file-system module along (`schema.ts` reaches `node:fs/promises` through the session outbox).
+/** Whether a run was in CI and by which provider: the word is chosen from the provider's own variable (`ciWord` in `fields.ts`), so the variable's value never reaches the spool. `other` is a bare `CI`. */
+export const CI_WORDS = ['none', 'github-actions', 'gitlab-ci', 'circleci', 'travis-ci', 'jenkins', 'buildkite', 'azure-pipelines', 'bitbucket', 'teamcity', 'appveyor', 'codebuild', 'other'];
+/** How this copy of oars arrived, from the folder it runs in and the package manager that started it (`surfaceWord` in `fields.ts`); the path itself never reaches the spool. A folder it cannot place is `unknown`. */
+export const SURFACE_WORDS = ['npm-global', 'npx', 'claude-plugin', 'codex-plugin', 'gemini-extension', 'unknown'];

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@manyoars/oars",
-  "version": "0.4.1",
-  "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",
+  "version": "0.5.2",
+  "mcpName": "io.github.manyoars/oars",
+  "description": "A local, searchable record of your coding agent sessions. Reads Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI, and more, and keeps the record on your machine.",
+  "homepage": "https://manyoars.com/",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "coding-agents",
+    "agent-memory",
+    "session-history",
+    "mcp",
+    "mcp-server",
+    "claude-code-plugin",
+    "codex-plugin",
+    "gemini-cli-extension",
+    "coding-agent",
+    "cli"
+  ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -10,10 +28,11 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=22.23.4"
   },
   "bin": {
-    "oars": "./dist/bin.js"
+    "oars": "./dist/bin.js",
+    "oars-hook": "./dist/oars-hook.js"
   },
   "files": [
     "dist",
@@ -30,7 +49,7 @@
     "test:live": "vitest run --config vitest.live.config.ts"
   },
   "dependencies": {
-    "@manyoars/oars-client": "^0.1.1",
+    "@manyoars/oars-client": "^0.1.2",
     "commander": "^15.0.0",
     "openid-client": "^6.8.8"
   },