@sapiom/harness 0.0.0 → 0.1.0

package/dist/core/collector/batcher.js

@@ -0,0 +1,143 @@
+/**
+ * In-memory queue -> batched POST to the remote collector, at
+ * `${SAPIOM_COLLECTOR_URL}/v1/harness/events`.
+ *
+ * Gated by telemetry opt-in: when off (or when no collector URL is
+ * configured at all), `enqueue` is a no-op — events still land in the local
+ * ndjson store via a separate path, this is only the remote fan-out.
+ *
+ * Response contract: any 2xx = accepted, drop the batch from the queue.
+ * 4xx = permanent failure, drop without retry (a malformed batch will never
+ * succeed by resending it). 5xx or a network error = transient, retry with
+ * exponential backoff, then drop.
+ */
+import * as crypto from "node:crypto";
+import { ANALYTICS_SCHEMA_VERSION, ENV, } from "../../shared/types.js";
+const EVENTS_PATH = "/v1/harness/events";
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+const DEFAULT_MAX_BATCH_SIZE = 50;
+const RETRY_BACKOFF_MS = [500, 1000, 2000];
+/** Hard ceiling so a long collector outage can't grow memory unbounded. */
+const MAX_QUEUE_SIZE = 1000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class CollectorBatcher {
+    constructor(options) {
+        this.queue = [];
+        this.flushing = false;
+        this.warnedNoCollectorUrl = false;
+        this.machineId = options.machineId;
+        this.context = options.context;
+        this.telemetryOptIn = options.telemetryOptIn;
+        this.apiKey = options.apiKey ?? null;
+        const collectorUrl = options.collectorUrl ?? process.env[ENV.collectorUrl];
+        this.eventsUrl = collectorUrl ? `${collectorUrl.replace(/\/$/, "")}${EVENTS_PATH}` : undefined;
+        this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.onDebug = options.onDebug ?? (() => { });
+        const flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+        if (this.eventsUrl) {
+            this.timer = setInterval(() => {
+                void this.flush();
+            }, flushIntervalMs);
+            this.timer.unref?.();
+        }
+        else {
+            this.timer = null;
+        }
+    }
+    setTelemetryOptIn(optIn) {
+        this.telemetryOptIn = optIn;
+        if (!optIn)
+            this.queue = [];
+    }
+    /** Update the auth key used on subsequent flushes (e.g. after login/logout). */
+    setApiKey(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /** Queue an event for the next batch. No-op unless opted in and configured. */
+    enqueue(event) {
+        if (!this.telemetryOptIn)
+            return;
+        if (!this.eventsUrl) {
+            if (!this.warnedNoCollectorUrl) {
+                this.warnedNoCollectorUrl = true;
+                this.onDebug(`${ENV.collectorUrl} not set — remote analytics batching disabled`);
+            }
+            return;
+        }
+        this.queue.push(event);
+        if (this.queue.length > MAX_QUEUE_SIZE) {
+            const dropped = this.queue.length - MAX_QUEUE_SIZE;
+            this.queue = this.queue.slice(dropped);
+            this.onDebug(`dropped ${dropped} queued analytics events (queue over capacity)`);
+        }
+        if (this.queue.length >= this.maxBatchSize) {
+            void this.flush();
+        }
+    }
+    /** Send whatever is queued now, with retry/backoff, dropping on final failure. */
+    async flush() {
+        if (this.flushing || !this.eventsUrl || this.queue.length === 0)
+            return;
+        this.flushing = true;
+        try {
+            const events = this.queue.splice(0, this.maxBatchSize);
+            const batch = {
+                batchId: crypto.randomUUID(),
+                schemaVersion: ANALYTICS_SCHEMA_VERSION,
+                machineId: this.machineId,
+                sentAt: new Date().toISOString(),
+                context: this.context,
+                events,
+            };
+            await this.sendWithRetry(this.eventsUrl, batch);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    async sendWithRetry(url, batch) {
+        const body = JSON.stringify(batch);
+        const headers = { "content-type": "application/json" };
+        // Anonymous traffic is valid (identity then rests on machineId); the
+        // header is only sent once a Sapiom user is actually logged in.
+        if (this.apiKey)
+            headers.authorization = `Bearer ${this.apiKey}`;
+        for (let attempt = 0; attempt <= RETRY_BACKOFF_MS.length; attempt++) {
+            try {
+                const res = await this.fetchImpl(url, {
+                    method: "POST",
+                    headers,
+                    body,
+                });
+                if (res.ok)
+                    return; // any 2xx = accepted
+                if (res.status >= 400 && res.status < 500) {
+                    // Permanent failure — resending an unprocessable batch never helps.
+                    this.onDebug(`dropping batch of ${batch.events.length} events: collector rejected with ${res.status}`);
+                    return;
+                }
+                throw new Error(`collector responded ${res.status}`);
+            }
+            catch (err) {
+                const isLastAttempt = attempt === RETRY_BACKOFF_MS.length;
+                if (isLastAttempt) {
+                    this.onDebug(`dropping batch of ${batch.events.length} events after ${attempt + 1} attempts: ${String(err)}`);
+                    return;
+                }
+                await sleep(RETRY_BACKOFF_MS[attempt]);
+            }
+        }
+    }
+    /** Flush everything queued, then stop the periodic timer. */
+    async close() {
+        if (this.timer)
+            clearInterval(this.timer);
+        while (this.queue.length > 0) {
+            await this.flush();
+        }
+    }
+}
+//# sourceMappingURL=batcher.js.map

package/dist/core/collector/batcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.js","sourceRoot":"","sources":["../../../src/core/collector/batcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,OAAO,EACL,wBAAwB,EACxB,GAAG,GAIJ,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,GAAG,oBAAoB,CAAC;AACzC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AACvC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAClC,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAC3C,2EAA2E;AAC3E,MAAM,cAAc,GAAG,IAAI,CAAC;AAoB5B,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,OAAO,gBAAgB;IAc3B,YAAY,OAAgC;QANpC,UAAK,GAAqB,EAAE,CAAC;QAG7B,aAAQ,GAAG,KAAK,CAAC;QACjB,yBAAoB,GAAG,KAAK,CAAC;QAGnC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;QACrC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC3E,IAAI,CAAC,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/F,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAC;QACnE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAK,KAAmB,CAAC;QAC3D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAE7C,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,yBAAyB,CAAC;QAC7E,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;gBAC5B,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,CAAC,EAAE,eAAe,CAAC,CAAC;YACpB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,iBAAiB,CAAC,KAAc;QAC9B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC5B,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED,gFAAgF;IAChF,SAAS,CAAC,MAAqB;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,+EAA+E;IAC/E,OAAO,CAAC,KAAqB;QAC3B,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO;QACjC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC;gBAC/B,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;gBACjC,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,YAAY,+CAA+C,CAAC,CAAC;YACnF,CAAC;YACD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;YACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,cAAc,CAAC;YACnD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACvC,IAAI,CAAC,OAAO,CAAC,WAAW,OAAO,gDAAgD,CAAC,CAAC;QACnF,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC3C,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACxE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YACvD,MAAM,KAAK,GAAmB;gBAC5B,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE;gBAC5B,aAAa,EAAE,wBAAwB;gBACvC,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBAChC,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM;aACP,CAAC;YACF,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAClD,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,GAAW,EAAE,KAAqB;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;QAC/E,qEAAqE;QACrE,gEAAgE;QAChE,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,aAAa,GAAG,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC;QAEjE,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;YACpE,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;oBACpC,MAAM,EAAE,MAAM;oBACd,OAAO;oBACP,IAAI;iBACL,CAAC,CAAC;gBAEH,IAAI,GAAG,CAAC,EAAE;oBAAE,OAAO,CAAC,qBAAqB;gBAEzC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;oBAC1C,oEAAoE;oBACpE,IAAI,CAAC,OAAO,CACV,qBAAqB,KAAK,CAAC,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,MAAM,EAAE,CACzF,CAAC;oBACF,OAAO;gBACT,CAAC;gBAED,MAAM,IAAI,KAAK,CAAC,uBAAuB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACvD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,aAAa,GAAG,OAAO,KAAK,gBAAgB,CAAC,MAAM,CAAC;gBAC1D,IAAI,aAAa,EAAE,CAAC;oBAClB,IAAI,CAAC,OAAO,CACV,qBAAqB,KAAK,CAAC,MAAM,CAAC,MAAM,iBAAiB,OAAO,GAAG,CAAC,cAAc,MAAM,CAAC,GAAG,CAAC,EAAE,CAChG,CAAC;oBACF,OAAO;gBACT,CAAC;gBACD,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,KAAK;YAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}

package/dist/core/collector/codex-tailer.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Codex transcript tailer — Codex has no hook system, so this file *is* its
+ * entire analytics eventSource (see HarnessAdapter.eventSource ===
+ * "transcript-tail" on CodexAdapter). It incrementally reads a rollout JSONL
+ * file as Codex appends to it and translates each entry into the same
+ * `{hookEvent, payload}` shape Claude Code's hooks would have produced for
+ * equivalent activity — so the existing ingest pipeline
+ * (core/collector/normalizer.ts's `normalizeHookEvent`) can consume both
+ * harnesses unchanged, with zero Codex-specific branching in the normalizer.
+ *
+ * Self-contained by design: no imports from server/, session-manager.ts, or
+ * the rest of core/collector/ (only types, imported for shape-compatibility
+ * with the normalizer this feeds). Not wired into the server — see the
+ * "Wiring this in" section of the PR description for the integration
+ * contract (what to call, and when).
+ */
+import type { ClaudeHookEvent, RawHookPayload } from "./normalizer.js";
+export type CodexEventListener = (hookEvent: ClaudeHookEvent, payload: RawHookPayload) => void;
+export interface CodexTailerOptions {
+    /** Path to the rollout JSONL file. It's fine if this doesn't exist yet —
+     * the tailer polls until Codex creates it (there's an unavoidable race
+     * between spawning `codex` and it creating its rollout file). */
+    rolloutPath: string;
+    onEvent: CodexEventListener;
+    onError?: (err: unknown) => void;
+    pollIntervalMs?: number;
+    /**
+     * Tail from byte 0 regardless of the file's current size — for a fresh
+     * launch, where the caller discovered this rollout file *because* it
+     * already contains the session_meta line the caller cares about (a
+     * find-then-tail race: by the time a poll-based discovery step returns a
+     * path, Codex has necessarily already written to it). Without this, the
+     * default "start from current size" baseline (correct for a genuine
+     * resume, where prior content really is history to skip) would silently
+     * swallow that already-written SessionStart. Defaults to false (resume
+     * semantics: skip whatever's already there, only emit new activity).
+     */
+    startFromBeginning?: boolean;
+}
+export interface CodexTailerHandle {
+    /** Stop polling without emitting anything further. */
+    stop(): void;
+    /**
+     * Synthesize a SessionEnd hook-shaped event and stop polling. Codex's
+     * rollout format has no "session ended" line of its own — call this when
+     * the harness detects the underlying pty has exited.
+     */
+    emitSessionEnd(reason?: string): void;
+}
+/**
+ * Incrementally tail a Codex rollout file, translating each new line into a
+ * Claude-hook-shaped `(hookEvent, payload)` pair via `onEvent`. Only emits
+ * for content appended *after* the tailer starts (matching hook semantics —
+ * hooks only fire for new activity, never backfill); use
+ * `CodexAdapter.listPastSessions` for history.
+ */
+export declare function tailCodexRollout(options: CodexTailerOptions): CodexTailerHandle;
+export interface FindRolloutFileOptions {
+    /** Match a rollout file whose session_meta.cwd equals this exactly. */
+    cwd: string;
+    /** Only consider sessions created at/after this time (ms epoch) —
+     * disambiguates a freshly-launched session from older ones sharing a cwd.
+     * Ignored when `agentSessionId` is given (an exact id match is a strictly
+     * stronger signal than a time-window heuristic). */
+    sinceMs?: number;
+    /**
+     * Match a rollout file by its exact session_meta.id (the rollout/agent
+     * session id) instead of by recency — needed when resuming a session,
+     * where `sinceMs` can't disambiguate it from other sessions sharing the
+     * same cwd that happen to have been touched more recently.
+     */
+    agentSessionId?: string;
+    /** Overridable for tests. */
+    homeDir?: string;
+}
+/**
+ * Finds a rollout file matching `cwd`. With `agentSessionId`, matches that
+ * exact session (for resume — cwd alone is ambiguous when multiple sessions
+ * share a directory). Otherwise returns the most-recently-modified match,
+ * optionally bounded by `sinceMs`. Intended to be polled by the integrator
+ * right after spawning a fresh `codex` process — there's no way to know the
+ * exact rollout path in advance (it's a timestamp+UUID Codex generates itself).
+ */
+export declare function findRolloutFile(options: FindRolloutFileOptions): Promise<string | null>;
+//# sourceMappingURL=codex-tailer.d.ts.map

package/dist/core/collector/codex-tailer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-tailer.d.ts","sourceRoot":"","sources":["../../../src/core/collector/codex-tailer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AASvE,MAAM,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;AAE/F,MAAM,WAAW,kBAAkB;IACjC;;qEAEiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,IAAI,IAAI,IAAI,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAYD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CA0I/E;AAMD,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ;;;wDAGoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgC7F"}

package/dist/core/collector/codex-tailer.js

@@ -0,0 +1,270 @@
+/**
+ * Codex transcript tailer — Codex has no hook system, so this file *is* its
+ * entire analytics eventSource (see HarnessAdapter.eventSource ===
+ * "transcript-tail" on CodexAdapter). It incrementally reads a rollout JSONL
+ * file as Codex appends to it and translates each entry into the same
+ * `{hookEvent, payload}` shape Claude Code's hooks would have produced for
+ * equivalent activity — so the existing ingest pipeline
+ * (core/collector/normalizer.ts's `normalizeHookEvent`) can consume both
+ * harnesses unchanged, with zero Codex-specific branching in the normalizer.
+ *
+ * Self-contained by design: no imports from server/, session-manager.ts, or
+ * the rest of core/collector/ (only types, imported for shape-compatibility
+ * with the normalizer this feeds). Not wired into the server — see the
+ * "Wiring this in" section of the PR description for the integration
+ * contract (what to call, and when).
+ */
+import { open, readdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const DEFAULT_POLL_INTERVAL_MS = 300;
+const MAX_SCAN_DEPTH = 4; // ~/.codex/sessions/YYYY/MM/DD/*.jsonl
+/**
+ * Incrementally tail a Codex rollout file, translating each new line into a
+ * Claude-hook-shaped `(hookEvent, payload)` pair via `onEvent`. Only emits
+ * for content appended *after* the tailer starts (matching hook semantics —
+ * hooks only fire for new activity, never backfill); use
+ * `CodexAdapter.listPastSessions` for history.
+ */
+export function tailCodexRollout(options) {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    let offset = 0;
+    let carry = "";
+    let sessionStartEmitted = false;
+    let stopped = false;
+    let polling = false;
+    const pendingCalls = new Map();
+    // Resolve the resume-vs-fresh baseline exactly once, immediately, before
+    // any poll reads content. `startFromBeginning` (see CodexTailerOptions)
+    // always wins when set. Otherwise: if the file already exists right now,
+    // its current size becomes the "don't backfill past this" offset (resume
+    // — only new activity should be emitted, matching hook semantics); if it
+    // doesn't exist yet, the offset stays 0, so once Codex creates the file
+    // the very first bytes it writes are read as new.
+    let baselineResolved = false;
+    if (options.startFromBeginning) {
+        baselineResolved = true;
+    }
+    else {
+        void stat(options.rolloutPath).then((s) => {
+            offset = s.size;
+            baselineResolved = true;
+        }, () => {
+            baselineResolved = true;
+        });
+    }
+    const timer = setInterval(() => {
+        void poll();
+    }, pollIntervalMs);
+    timer.unref?.();
+    async function poll() {
+        if (stopped || polling || !baselineResolved)
+            return;
+        polling = true;
+        try {
+            const fileStat = await stat(options.rolloutPath);
+            if (fileStat.size <= offset)
+                return;
+            const handle = await open(options.rolloutPath, "r");
+            try {
+                const length = fileStat.size - offset;
+                const buffer = Buffer.allocUnsafe(length);
+                await handle.read(buffer, 0, length, offset);
+                offset = fileStat.size;
+                const chunk = carry + buffer.toString("utf8");
+                const lines = chunk.split("\n");
+                carry = lines.pop() ?? "";
+                for (const line of lines)
+                    processLine(line);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (err) {
+            // ENOENT is the expected steady-state before Codex has created the
+            // file yet — anything else is a real read/parse failure worth surfacing.
+            if (err?.code !== "ENOENT") {
+                options.onError?.(err);
+            }
+        }
+        finally {
+            polling = false;
+        }
+    }
+    function processLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch (err) {
+            options.onError?.(err);
+            return;
+        }
+        translate(entry);
+    }
+    function translate(entry) {
+        const payload = entry.payload;
+        if (entry.type === "session_meta") {
+            if (sessionStartEmitted)
+                return;
+            sessionStartEmitted = true;
+            options.onEvent("SessionStart", {
+                source: "codex",
+                cwd: typeof payload?.cwd === "string" ? payload.cwd : null,
+                // Claude's normalizer resolves agentSessionId from a `session_id`
+                // field on the hook payload — matching that field name here is what
+                // lets normalizeHookEvent() pick up the rollout id unchanged.
+                session_id: typeof payload?.id === "string" ? payload.id : undefined,
+            });
+            return;
+        }
+        if (entry.type === "event_msg") {
+            if (payload?.type === "user_message" && typeof payload.message === "string") {
+                options.onEvent("UserPromptSubmit", { prompt: payload.message });
+            }
+            else if (payload?.type === "task_complete") {
+                options.onEvent("Stop", { stop_hook_active: false });
+            }
+            return;
+        }
+        if (entry.type === "response_item") {
+            if (payload?.type === "function_call" && typeof payload.call_id === "string") {
+                pendingCalls.set(payload.call_id, {
+                    name: typeof payload.name === "string" ? payload.name : "unknown",
+                    argumentsRaw: typeof payload.arguments === "string" ? payload.arguments : "",
+                });
+            }
+            else if (payload?.type === "function_call_output" && typeof payload.call_id === "string") {
+                const call = pendingCalls.get(payload.call_id);
+                pendingCalls.delete(payload.call_id);
+                options.onEvent("PostToolUse", {
+                    tool_name: call?.name ?? "unknown",
+                    tool_input: call?.argumentsRaw ?? "",
+                    tool_response: payload.output ?? "",
+                });
+            }
+            return;
+        }
+    }
+    return {
+        stop() {
+            stopped = true;
+            clearInterval(timer);
+        },
+        emitSessionEnd(reason) {
+            if (stopped)
+                return;
+            options.onEvent("SessionEnd", { reason: reason ?? null });
+            stopped = true;
+            clearInterval(timer);
+        },
+    };
+}
+async function readSessionMetaHead(filePath, maxBytes = 65536) {
+    let content;
+    try {
+        const handle = await open(filePath, "r");
+        try {
+            const { size } = await handle.stat();
+            const length = Math.min(size, maxBytes);
+            const buffer = Buffer.allocUnsafe(length);
+            await handle.read(buffer, 0, length, 0);
+            content = buffer.toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return null;
+    }
+    for (const line of content.split("\n").slice(0, 20)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type !== "session_meta")
+            continue;
+        const cwd = typeof parsed.payload?.cwd === "string" ? parsed.payload.cwd : undefined;
+        if (!cwd)
+            return null;
+        const id = typeof parsed.payload?.id === "string" ? parsed.payload.id : null;
+        const timestamp = typeof parsed.payload?.timestamp === "string" ? Date.parse(parsed.payload.timestamp) : NaN;
+        return { id, cwd, timestampMs: Number.isNaN(timestamp) ? null : timestamp };
+    }
+    return null;
+}
+async function collectRolloutFiles(dir, depth = 0) {
+    if (depth > MAX_SCAN_DEPTH)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await collectRolloutFiles(fullPath, depth + 1)));
+        }
+        else if (entry.name.endsWith(".jsonl")) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Finds a rollout file matching `cwd`. With `agentSessionId`, matches that
+ * exact session (for resume — cwd alone is ambiguous when multiple sessions
+ * share a directory). Otherwise returns the most-recently-modified match,
+ * optionally bounded by `sinceMs`. Intended to be polled by the integrator
+ * right after spawning a fresh `codex` process — there's no way to know the
+ * exact rollout path in advance (it's a timestamp+UUID Codex generates itself).
+ */
+export async function findRolloutFile(options) {
+    const homeDir = options.homeDir ?? homedir();
+    const root = join(homeDir, ".codex", "sessions");
+    const files = await collectRolloutFiles(root);
+    // Codex records session_meta.cwd as the OS-canonicalized path (symlinks
+    // resolved) — on macOS in particular, `/tmp` and `/var` are themselves
+    // symlinks into `/private`, so a cwd like `/var/folders/.../T/foo` (what
+    // `os.tmpdir()` and most callers hand us) never string-equals what Codex
+    // wrote (`/private/var/folders/.../T/foo`), even though it's the same
+    // directory. Resolve our side the same way before comparing. Falls back
+    // to the raw value if the directory is gone (a session that already
+    // exited, or a test double that never touches the real filesystem).
+    const resolvedCwd = await realpath(options.cwd).catch(() => options.cwd);
+    let best = null;
+    for (const filePath of files) {
+        const meta = await readSessionMetaHead(filePath);
+        if (!meta || meta.cwd !== resolvedCwd)
+            continue;
+        if (options.agentSessionId !== undefined) {
+            if (meta.id !== options.agentSessionId)
+                continue;
+            return filePath;
+        }
+        if (options.sinceMs !== undefined && meta.timestampMs !== null && meta.timestampMs < options.sinceMs)
+            continue;
+        const fileStat = await stat(filePath).catch(() => null);
+        if (!fileStat)
+            continue;
+        if (!best || fileStat.mtimeMs > best.mtimeMs)
+            best = { path: filePath, mtimeMs: fileStat.mtimeMs };
+    }
+    return best?.path ?? null;
+}
+//# sourceMappingURL=codex-tailer.js.map

package/dist/core/collector/codex-tailer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-tailer.js","sourceRoot":"","sources":["../../../src/core/collector/codex-tailer.ts"],"names":[],"mappings":"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"}

package/dist/core/collector/normalizer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Raw Claude Code hook payload -> normalized AnalyticsEvent.
+ *
+ * `userId` / `machineId` / `harness` are never present on the hook payload
+ * itself (Claude Code has no idea it's running inside the harness) — they're
+ * injected from server-side context resolved by the caller (the session
+ * registry, auth state, machine-id file).
+ */
+import type { AnalyticsEvent, HarnessKind } from "../../shared/types.js";
+/** The six hook names Claude Code invokes; see claude-settings.ts. */
+export type ClaudeHookEvent = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "Stop" | "SessionEnd";
+/** Loose on purpose — hook payloads vary by event and Claude Code version. */
+export type RawHookPayload = Record<string, unknown>;
+export interface NormalizeContext {
+    userId: string | null;
+    tenantId: string | null;
+    machineId: string;
+    harnessSessionId: string;
+    harness: HarnessKind;
+    /** Already-known agent session id, if the registry has resolved one yet. */
+    agentSessionId: string | null;
+    /** Per-harnessSessionId monotonic counter, assigned by the caller (see core/collector/seq.ts). */
+    seq: number;
+}
+/** Stringify + truncate a value so a giant tool payload can't blow up storage. */
+export declare function truncateForPayload(value: unknown, maxLength?: number): string;
+/**
+ * Normalize one Claude Code hook invocation into an AnalyticsEvent, or
+ * `null` when the hook doesn't map to an analytics event (PreToolUse, or an
+ * unrecognized hook name).
+ */
+export declare function normalizeHookEvent(hookEvent: string, hookPayload: RawHookPayload, context: NormalizeContext): AnalyticsEvent | null;
+//# sourceMappingURL=normalizer.d.ts.map

package/dist/core/collector/normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../../src/core/collector/normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAsB,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE7F,sEAAsE;AACtE,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,kBAAkB,GAClB,YAAY,GACZ,aAAa,GACb,MAAM,GACN,YAAY,CAAC;AAEjB,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kGAAkG;IAClG,GAAG,EAAE,MAAM,CAAC;CACb;AAiBD,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,SAAmB,GAAG,MAAM,CAIvF;AA+CD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,cAAc,EAC3B,OAAO,EAAE,gBAAgB,GACxB,cAAc,GAAG,IAAI,CAmBvB"}

package/dist/core/collector/normalizer.js

@@ -0,0 +1,94 @@
+/**
+ * Raw Claude Code hook payload -> normalized AnalyticsEvent.
+ *
+ * `userId` / `machineId` / `harness` are never present on the hook payload
+ * itself (Claude Code has no idea it's running inside the harness) — they're
+ * injected from server-side context resolved by the caller (the session
+ * registry, auth state, machine-id file).
+ */
+import * as crypto from "node:crypto";
+const HOOK_TO_TYPE = {
+    SessionStart: "session.start",
+    UserPromptSubmit: "prompt.submitted",
+    PostToolUse: "tool.call",
+    Stop: "turn.completed",
+    SessionEnd: "session.end",
+    // PreToolUse has no dedicated analytics event today; it's still registered
+    // as a hook (see claude-settings.ts) so a future correctness check can
+    // compare pre/post firing without a settings-file change.
+};
+const MAX_FIELD_LENGTH = 4000;
+/** Tool output can be much larger than other fields; cap it separately. */
+const MAX_TOOL_RESPONSE_LENGTH = 16 * 1024;
+/** Stringify + truncate a value so a giant tool payload can't blow up storage. */
+export function truncateForPayload(value, maxLength = MAX_FIELD_LENGTH) {
+    const str = typeof value === "string" ? value : JSON.stringify(value ?? null);
+    if (str.length <= maxLength)
+        return str;
+    return `${str.slice(0, maxLength)}…[truncated ${str.length - maxLength} chars]`;
+}
+function stringField(payload, key) {
+    const value = payload[key];
+    return typeof value === "string" ? value : undefined;
+}
+function buildEventPayload(hookEvent, hookPayload) {
+    switch (hookEvent) {
+        case "SessionStart":
+            return {
+                source: stringField(hookPayload, "source") ?? null,
+                cwd: stringField(hookPayload, "cwd") ?? null,
+            };
+        case "UserPromptSubmit":
+            return {
+                prompt: stringField(hookPayload, "prompt") ?? "",
+            };
+        case "PostToolUse":
+            return {
+                toolName: stringField(hookPayload, "tool_name") ?? null,
+                toolInput: truncateForPayload(hookPayload.tool_input),
+                toolResponseSummary: truncateForPayload(hookPayload.tool_response, MAX_TOOL_RESPONSE_LENGTH),
+            };
+        case "Stop":
+            // Claude Code's own Stop payload already carries the final assistant
+            // message — no need to wait on the transcript file for this field (it
+            // may not exist on disk yet, or at all, when Stop fires; see
+            // enrichTurnCompleted for the model/usage backfill that DOES need it).
+            return {
+                stopHookActive: hookPayload.stop_hook_active === true,
+                assistantText: stringField(hookPayload, "last_assistant_message") ?? null,
+            };
+        case "SessionEnd":
+            return {
+                reason: stringField(hookPayload, "reason") ?? null,
+            };
+        case "PreToolUse":
+            return {};
+        default:
+            return {};
+    }
+}
+/**
+ * Normalize one Claude Code hook invocation into an AnalyticsEvent, or
+ * `null` when the hook doesn't map to an analytics event (PreToolUse, or an
+ * unrecognized hook name).
+ */
+export function normalizeHookEvent(hookEvent, hookPayload, context) {
+    const type = HOOK_TO_TYPE[hookEvent];
+    if (!type)
+        return null;
+    const agentSessionId = stringField(hookPayload, "session_id") ?? context.agentSessionId;
+    return {
+        eventId: crypto.randomUUID(),
+        seq: context.seq,
+        ts: new Date().toISOString(),
+        userId: context.userId,
+        tenantId: context.tenantId,
+        machineId: context.machineId,
+        harnessSessionId: context.harnessSessionId,
+        agentSessionId,
+        harness: context.harness,
+        type,
+        payload: buildEventPayload(hookEvent, hookPayload),
+    };
+}
+//# sourceMappingURL=normalizer.js.map