@revealyst/agent 0.2.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Revealyst. All rights reserved.
+
+This software is provided for use with the Revealyst service. Use of the
+Revealyst service is governed by the Revealyst Terms of Service:
+https://revealyst.com/legal/terms
+
+Redistribution or modification of this software outside the above is not
+permitted without prior written permission.

package/README.md

@@ -0,0 +1,59 @@
+# revealyst-agent
+
+The Revealyst Agent — the sanctioned local-ingest path for Claude Code
+(product spec §10). Reads your local Claude Code session logs, summarizes
+them **on your machine** into daily metric records, and pushes only those
+records to Revealyst with a device token.
+
+## What leaves your machine — and what never does
+
+Transmitted (the full list — enforced by the privacy test suite):
+- daily counts: sessions, prompts, active days
+- daily token totals (input / output / cache read / cache write)
+- per-model request/token counts (model *ids* only)
+- estimated spend (public list prices; marked as an estimate)
+- a 24-slot hourly activity histogram + peak session concurrency per day
+- your Claude account email — **only** if you opt in with
+  `--consent-identity`; otherwise a one-way device hash
+
+Never transmitted: prompt or completion text, tool inputs/outputs, file
+contents or paths, session titles, working directories, git branches,
+session ids. The parser structurally cannot carry these fields
+(`src/parse.ts`), and `tests/privacy.test.ts` proves no content survives
+into an outgoing payload using sentinel-seeded fixtures.
+
+## Usage
+
+```
+revealyst-agent login --token rva1.…  [--api <url>] [--consent-identity]
+revealyst-agent sync  [--days 30] [--dry-run]
+revealyst-agent status
+```
+
+Create the device token in Revealyst → Connections → Revealyst Agent (it is
+shown once; re-issuing rotates it). `sync --dry-run` shows exactly what
+would be pushed without pushing. Schedule `sync` daily with Task Scheduler
+(Windows) or cron if you want hands-off updates.
+
+For CI/headless one-shot runs, `sync` also honors `REVEALYST_TOKEN` (and
+optionally `REVEALYST_API`) without persisting anything — interactive users
+should prefer `login`, which keeps the token out of shell history. An
+env-supplied token is always device-scoped: identity consent applies only
+to the `login` that granted it, never to env runs.
+
+`sync` pins the pushed window to the earliest day your local logs still
+cover, so a wide `--days` lookback can never erase previously-synced days
+whose logs have since been pruned. If no activity falls inside the window,
+nothing is pushed (and nothing is deleted).
+
+Log locations scanned: `%USERPROFILE%\.claude\projects\` (or
+`~/.claude/projects/`), honoring `CLAUDE_CONFIG_DIR` (multi-path). Local
+logs retain ~30 days by default, so backfill depth is bounded by that.
+
+## Development
+
+Lives in the Revealyst monorepo; tests run from the repo root (`npm test`)
+against recorded-shape fixtures in `fixtures/vendor-payloads/claude-code-local/`.
+Dev invocation without a build: `npm run agent -- sync --dry-run`.
+Build the distributable CLI: `npm run build` in this directory (emits
+`dist/`, CommonJS, `revealyst-agent` bin).

package/dist/cli.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+"use strict";
+// Revealyst Agent CLI — the sanctioned local-ingest path (spec §10).
+//
+//   revealyst-agent login --token rva1.… [--api <url>] [--consent-identity]
+//   revealyst-agent sync  [--days 30] [--dry-run]
+//   revealyst-agent status
+//
+// Everything printed here is structural (counts, days, masked token) —
+// never log content, never file paths of individual sessions.
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_os_1 = require("node:os");
+const node_util_1 = require("node:util");
+const config_1 = require("./config");
+const discover_1 = require("./discover");
+const push_1 = require("./push");
+const stream_1 = require("./stream");
+const sync_run_1 = require("./sync-run");
+const AGENT_VERSION = "0.2.0";
+const DEFAULT_API = "https://app.revealyst.com";
+const DEFAULT_DAYS = 30;
+function fail(message) {
+    console.error(`revealyst-agent: ${message}`);
+    process.exit(1);
+}
+function deviceSeed() {
+    let user = "unknown";
+    try {
+        user = (0, node_os_1.userInfo)().username;
+    }
+    catch {
+        // Some environments (restricted containers) cannot resolve the user.
+    }
+    return `${(0, node_os_1.hostname)()}:${user}`;
+}
+async function login(args) {
+    const { values } = (0, node_util_1.parseArgs)({
+        args,
+        options: {
+            token: { type: "string" },
+            api: { type: "string", default: DEFAULT_API },
+            "consent-identity": { type: "boolean", default: false },
+        },
+    });
+    const token = values.token;
+    if (!token || !(0, config_1.isValidTokenShape)(token)) {
+        fail("a device token is required: revealyst-agent login --token rva1.… " +
+            "(create one in Revealyst → Connections → Revealyst Agent)");
+    }
+    (0, config_1.saveConfig)((0, node_os_1.homedir)(), {
+        token,
+        apiBaseUrl: values.api ?? DEFAULT_API,
+        consentIdentity: values["consent-identity"] === true,
+    });
+    console.log(`Logged in (${(0, config_1.maskToken)(token)} → ${values.api}).`);
+    console.log(values["consent-identity"]
+        ? "Identity: your Claude account email will be attached (person-level metrics)."
+        : "Identity: device-scoped only. Re-run login with --consent-identity for person-level metrics.");
+}
+async function sync(args) {
+    const { values } = (0, node_util_1.parseArgs)({
+        args,
+        options: {
+            days: { type: "string", default: String(DEFAULT_DAYS) },
+            "dry-run": { type: "boolean", default: false },
+        },
+    });
+    const days = Number(values.days);
+    if (!Number.isInteger(days) || days < 1 || days > 90) {
+        fail("--days must be an integer between 1 and 90");
+    }
+    const dryRun = values["dry-run"] === true;
+    const outcome = await (0, sync_run_1.runSync)({ days, dryRun }, {
+        homeDir: (0, node_os_1.homedir)(),
+        env: process.env,
+        defaultApi: DEFAULT_API,
+        agentVersion: AGENT_VERSION,
+        deviceSeed: deviceSeed(),
+        now: () => new Date(),
+        listFiles: () => (0, discover_1.listSessionFiles)((0, discover_1.claudeConfigDirs)(process.env, (0, node_os_1.homedir)())),
+        parseFiles: stream_1.parseSessionFilesStreaming,
+        push: push_1.pushBatch,
+        log: (message) => console.log(message),
+        warn: (message) => console.error(`revealyst-agent: ${message}`),
+    });
+    if (outcome.kind === "fail") {
+        fail(outcome.message);
+    }
+}
+function status() {
+    const resolved = (0, config_1.resolveConfig)(process.env, (0, node_os_1.homedir)(), DEFAULT_API);
+    const dirs = (0, discover_1.claudeConfigDirs)(process.env, (0, node_os_1.homedir)());
+    const files = (0, discover_1.listSessionFiles)(dirs);
+    console.log(`revealyst-agent ${AGENT_VERSION}`);
+    if (resolved.source === "invalid-env") {
+        console.log("Login: REVEALYST_TOKEN is set but malformed");
+    }
+    else if (resolved.source === "none") {
+        console.log("Login: not configured");
+    }
+    else {
+        const { config } = resolved;
+        const suffix = resolved.source === "env" ? " [from REVEALYST_TOKEN env]" : "";
+        console.log(`Login: ${(0, config_1.maskToken)(config.token)} → ${config.apiBaseUrl} ` +
+            `(identity consent: ${config.consentIdentity ? "yes" : "no"})${suffix}`);
+    }
+    console.log(`Log dirs: ${dirs.length} (${files.length} session files)`);
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case "login":
+            return login(rest);
+        case "sync":
+            return sync(rest);
+        case "status":
+            return status();
+        default:
+            console.log("usage: revealyst-agent <login|sync|status>\n" +
+                "  login  --token rva1.… [--api <url>] [--consent-identity]\n" +
+                "  sync   [--days 30] [--dry-run]\n" +
+                "  status");
+            process.exit(command ? 1 : 0);
+    }
+}
+void main();

package/dist/config.js

@@ -0,0 +1,85 @@
+"use strict";
+// Local agent config: <home>/.revealyst/agent.json — the device token, the
+// API base URL, and the identity-consent flag captured at `login`. The
+// token is a bearer secret: the file is written 0o600 (owner-only on
+// POSIX; on Windows the user-profile ACL covers it).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configPath = configPath;
+exports.isValidTokenShape = isValidTokenShape;
+exports.maskToken = maskToken;
+exports.loadConfig = loadConfig;
+exports.resolveConfig = resolveConfig;
+exports.saveConfig = saveConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function configPath(homeDir) {
+    return (0, node_path_1.join)(homeDir, ".revealyst", "agent.json");
+}
+/** Structural token check (mirrors the server's parseAgentToken; the
+ * server remains the authority). */
+function isValidTokenShape(token) {
+    const parts = token.split(".");
+    return (parts.length === 4 &&
+        parts[0] === "rva1" &&
+        parts.slice(1).every((p) => p.length > 0));
+}
+function maskToken(token) {
+    return token.length > 8 ? `rva1.…${token.slice(-4)}` : "…";
+}
+function loadConfig(homeDir) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(configPath(homeDir), "utf8"));
+        if (typeof parsed.token !== "string" ||
+            typeof parsed.apiBaseUrl !== "string") {
+            return null;
+        }
+        return {
+            token: parsed.token,
+            apiBaseUrl: parsed.apiBaseUrl,
+            consentIdentity: parsed.consentIdentity === true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Runtime config resolution: `REVEALYST_TOKEN` (with optional
+ * `REVEALYST_API`) takes precedence over the login-written file, is never
+ * persisted, and is intended for CI/headless one-shot runs — interactive
+ * users should prefer `login`, which keeps the token out of shell history
+ * and process listings. A malformed env token fails loudly rather than
+ * silently falling back to the file (the caller's token intent was
+ * explicit).
+ *
+ * An env credential is FULLY env-defined — it never inherits anything
+ * from a leftover agent.json belonging to some other login: not the api
+ * base (a prod token must not be replayed at a stale staging host) and
+ * not identity consent (consent was given for THAT login's token, not
+ * this one — env runs are always device-scoped). */
+function resolveConfig(env, homeDir, defaultApiBaseUrl) {
+    const envToken = env.REVEALYST_TOKEN;
+    if (typeof envToken === "string" && envToken.length > 0) {
+        if (!isValidTokenShape(envToken)) {
+            return { source: "invalid-env" };
+        }
+        return {
+            source: "env",
+            config: {
+                token: envToken,
+                apiBaseUrl: env.REVEALYST_API ?? defaultApiBaseUrl,
+                consentIdentity: false,
+            },
+        };
+    }
+    const fileConfig = loadConfig(homeDir);
+    return fileConfig
+        ? { source: "file", config: fileConfig }
+        : { source: "none" };
+}
+function saveConfig(homeDir, config) {
+    const path = configPath(homeDir);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(config, null, 2)}\n`, {
+        mode: 0o600,
+    });
+}

package/dist/discover.js

@@ -0,0 +1,74 @@
+"use strict";
+// Session-log discovery (docs/connector-facts.md §5):
+//   Windows  %USERPROFILE%\.claude\projects\<encoded-cwd>\<sessionId>.jsonl
+//   mac/linux ~/.claude/projects/...
+//   Also     ~/.config/claude/projects (ccusage parity)
+//   Override CLAUDE_CONFIG_DIR — COMMA-separated multi-path (ccusage), NOT
+//            the OS path delimiter (which would shred a Windows "C:\…" path
+//            on POSIX and disagrees with the documented format).
+// Subagent sidechains live at projects/<proj>/<sessionId>/subagents/*.jsonl
+// and MUST be included (they carry their own usage) — hence a recursive scan.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeConfigDirs = claudeConfigDirs;
+exports.listSessionFiles = listSessionFiles;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Config dirs to scan. §5: "Agent must scan ~/.claude/projects,
+ * ~/.config/claude/projects, and every CLAUDE_CONFIG_DIR path." The
+ * override is additive (ccusage scans defaults + override), comma-split,
+ * and the set is de-duplicated. Pure over its inputs for testability. */
+function claudeConfigDirs(env, homeDir) {
+    const dirs = [(0, node_path_1.join)(homeDir, ".claude"), (0, node_path_1.join)(homeDir, ".config", "claude")];
+    const override = env.CLAUDE_CONFIG_DIR;
+    if (override && override.trim() !== "") {
+        for (const path of override.split(",")) {
+            const trimmed = path.trim();
+            if (trimmed !== "") {
+                dirs.push(trimmed);
+            }
+        }
+    }
+    return [...new Set(dirs)];
+}
+/** Real layouts nest: sessions at projects/<proj>/*.jsonl, but subagent
+ * sidechains at projects/<proj>/<sessionId>/subagents/*.jsonl (verified on
+ * the founder's machine, where a flat scan missed 97 of 129 files — i.e.
+ * ALL sidechain usage). Bounded depth guards against symlink cycles. */
+const MAX_SCAN_DEPTH = 6;
+/** All session .jsonl files under <dir>/projects/**, recursively, for each
+ * config dir. Missing dirs are skipped silently — an empty machine is not
+ * an error. */
+function listSessionFiles(configDirs) {
+    const refs = [];
+    const walk = (dir, depth) => {
+        if (depth > MAX_SCAN_DEPTH) {
+            return;
+        }
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = (0, node_path_1.join)(dir, entry);
+            try {
+                const stat = (0, node_fs_1.statSync)(path);
+                if (stat.isDirectory()) {
+                    walk(path, depth + 1);
+                }
+                else if (entry.endsWith(".jsonl")) {
+                    refs.push({ path, sizeBytes: stat.size, mtimeMs: stat.mtimeMs });
+                }
+            }
+            catch {
+                // Deleted between readdir and stat — skip.
+            }
+        }
+    };
+    for (const dir of configDirs) {
+        walk((0, node_path_1.join)(dir, "projects"), 0);
+    }
+    return refs.sort((a, b) => a.path.localeCompare(b.path));
+}

package/dist/identity.js

@@ -0,0 +1,65 @@
+"use strict";
+// Local identity resolution (docs/connector-facts.md §5): the machine's
+// user via the consented oauthAccount in <home>/.claude.json. When absent
+// (or consent withheld), fall back to a stable device-scoped ACCOUNT
+// subject — never fabricate a person (review invariant b). Attribution
+// follows the subject kind: person ⇢ "person", device ⇢ "account".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readOauthEmail = readOauthEmail;
+exports.resolveLocalIdentity = resolveLocalIdentity;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Reads oauthAccount.emailAddress from <home>/.claude.json. Never throws;
+ * any read/parse failure means "no identity available". */
+function readOauthEmail(homeDir) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(homeDir, ".claude.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        const email = parsed.oauthAccount?.emailAddress;
+        if (typeof email !== "string" || !email.includes("@")) {
+            return null;
+        }
+        const displayName = parsed.oauthAccount?.displayName;
+        return {
+            email: email.toLowerCase(),
+            displayName: typeof displayName === "string" ? displayName : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @param consentIdentity user agreed (at `login`) to attach their Claude
+ *   account email; without it the device-scoped fallback is used even when
+ *   the email is readable.
+ * @param deviceSeed stable machine-scoped seed (e.g. hostname+username);
+ *   only its hash ever leaves the machine.
+ */
+function resolveLocalIdentity(homeDir, consentIdentity, deviceSeed) {
+    if (consentIdentity) {
+        const oauth = readOauthEmail(homeDir);
+        if (oauth) {
+            return {
+                descriptor: {
+                    kind: "person",
+                    externalId: oauth.email,
+                    email: oauth.email,
+                    displayName: oauth.displayName,
+                },
+                attribution: "person",
+            };
+        }
+    }
+    const hash = (0, node_crypto_1.createHash)("sha256").update(deviceSeed).digest("hex");
+    return {
+        descriptor: {
+            kind: "account",
+            externalId: `device:${hash.slice(0, 16)}`,
+            email: null,
+            displayName: null,
+        },
+        attribution: "account",
+    };
+}

package/dist/index.js

@@ -0,0 +1,95 @@
+"use strict";
+// Composition root for the pure pipeline: session-file contents in →
+// ingest-ready AgentIngestRequest out. File I/O stays in the caller (CLI /
+// tests), so this module remains fixture-testable end-to-end.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarize = exports.SUMMARIZER_VERSION = exports.parseSessionFilesStreaming = exports.parseSessionContent = exports.createSessionParser = exports.resolveLocalIdentity = exports.readOauthEmail = exports.listSessionFiles = exports.claudeConfigDirs = void 0;
+exports.buildIngestRequest = buildIngestRequest;
+const parse_1 = require("./parse");
+const prices_1 = require("./prices");
+const summarize_1 = require("./summarize");
+var discover_1 = require("./discover");
+Object.defineProperty(exports, "claudeConfigDirs", { enumerable: true, get: function () { return discover_1.claudeConfigDirs; } });
+Object.defineProperty(exports, "listSessionFiles", { enumerable: true, get: function () { return discover_1.listSessionFiles; } });
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "readOauthEmail", { enumerable: true, get: function () { return identity_1.readOauthEmail; } });
+Object.defineProperty(exports, "resolveLocalIdentity", { enumerable: true, get: function () { return identity_1.resolveLocalIdentity; } });
+var parse_2 = require("./parse");
+Object.defineProperty(exports, "createSessionParser", { enumerable: true, get: function () { return parse_2.createSessionParser; } });
+Object.defineProperty(exports, "parseSessionContent", { enumerable: true, get: function () { return parse_2.parseSessionContent; } });
+var stream_1 = require("./stream");
+Object.defineProperty(exports, "parseSessionFilesStreaming", { enumerable: true, get: function () { return stream_1.parseSessionFilesStreaming; } });
+var prices_2 = require("./prices");
+Object.defineProperty(exports, "SUMMARIZER_VERSION", { enumerable: true, get: function () { return prices_2.SUMMARIZER_VERSION; } });
+var summarize_2 = require("./summarize");
+Object.defineProperty(exports, "summarize", { enumerable: true, get: function () { return summarize_2.summarize; } });
+/** Pin the declared window's start to the earliest surviving event day.
+ * The server treats the declared window as authoritative (delete-then-
+ * upsert), so a lookback wider than local log retention would DELETE
+ * previously-captured days whose logs are pruned and upsert nothing in
+ * their place (plan R2 / research Fix 1). Pinning is global across all
+ * config dirs (events are already flattened). With no events at all the
+ * requested window passes through — callers must not push such a batch
+ * (an empty authoritative window is pure history destruction; the CLI
+ * aborts on zero records). */
+function pinWindow(window, events) {
+    // Numeric min first — one Date/ISO conversion total, not one per event.
+    let earliestMs = Infinity;
+    for (const event of events) {
+        if (event.timestampMs < earliestMs) {
+            earliestMs = event.timestampMs;
+        }
+    }
+    if (!Number.isFinite(earliestMs)) {
+        return window;
+    }
+    const earliest = (0, summarize_1.utcDay)(earliestMs);
+    if (earliest <= window.start) {
+        return window;
+    }
+    return {
+        start: earliest > window.end ? window.end : earliest,
+        end: window.end,
+    };
+}
+function buildIngestRequest(opts) {
+    const contents = opts.sessionContents ?? [];
+    // Don't copy the (potentially multi-million-entry) streamed events array
+    // unless there are string contents to merge in.
+    const events = contents.length > 0 ? [...(opts.parsed?.events ?? [])] : (opts.parsed?.events ?? []);
+    let skippedLines = opts.parsed?.skippedLines ?? 0;
+    let unknownTypes = opts.parsed?.unknownTypes ?? 0;
+    for (const content of contents) {
+        const result = (0, parse_1.parseSessionContent)(content);
+        events.push(...result.events);
+        skippedLines += result.skippedLines;
+        unknownTypes += result.unknownTypes;
+    }
+    const window = pinWindow(opts.window, events);
+    const { records, signals, gaps } = (0, summarize_1.summarize)(events, {
+        subject: {
+            kind: opts.identity.descriptor.kind,
+            externalId: opts.identity.descriptor.externalId,
+        },
+        attribution: opts.identity.attribution,
+        window,
+    });
+    const allGaps = [...gaps];
+    if (skippedLines > 0 || unknownTypes > 0) {
+        allGaps.push({
+            kind: "other",
+            detail: `log parse drift: ${skippedLines} lines skipped, ${unknownTypes} unknown record types`,
+        });
+    }
+    return {
+        agentVersion: opts.agentVersion,
+        summarizerVersion: prices_1.SUMMARIZER_VERSION,
+        // The PINNED window — never the requested one. batch.window is the
+        // range the server deletes; it must match what summarize() covered.
+        window,
+        subjects: [opts.identity.descriptor],
+        records,
+        signals,
+        gaps: allGaps,
+    };
+}

package/dist/parse.js

@@ -0,0 +1,152 @@
+"use strict";
+// Lenient structural parser for Claude Code session JSONL
+// (docs/connector-facts.md §5). THE PRIVACY LINE LIVES HERE: a ParsedEvent
+// carries only allowlisted structural fields — type, ids, timestamps, the
+// model id, usage NUMBERS, and block-type presence. Denylisted fields
+// (content, tool output, titles, paths, branches) are never read at all.
+// The one free-text field the §5 allowlist permits, `message.model`, IS
+// transmitted (as a metric `dim`), but it's vendor free text, so
+// sanitizeModel bounds it — charset-clamped to [A-Za-z0-9._:-] and capped
+// at 64 chars — so it cannot carry spaces, punctuation, newlines, a URL,
+// JSON, or a large payload. We can't prove a string is a "real" model
+// without a brittle hardcoded list, so this is a BOUND, not a semantic
+// filter; the server dim guard is the second bound.
+//
+// Lenient by design (format drift is the #1 risk): unparseable lines and
+// unknown record types are counted and skipped, never fatal.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeModel = sanitizeModel;
+exports.createSessionParser = createSessionParser;
+exports.parseSessionContent = parseSessionContent;
+/** Record types that exist but carry nothing we may transmit (titles,
+ * prompt snapshots, mode switches) — ignored without reading payloads. */
+const IGNORED_TYPES = new Set([
+    "summary",
+    "ai-title",
+    "custom-title",
+    "last-prompt",
+    "mode",
+    "queue-operation",
+]);
+function asNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+function asString(v) {
+    return typeof v === "string" && v.length > 0 ? v : null;
+}
+/** Model ids look like "claude-fable-5" / "claude-haiku-4-5-20251001". We
+ * transmit the model (it's §5-allowlisted) but it is still vendor free
+ * text, so clamp it to a safe charset and length before it can become a
+ * metric `dim` ("model=<id>") or a gap detail — a hostile/corrupted log
+ * must not be able to smuggle content through it. Disallowed characters
+ * are dropped; an empty or overlong result collapses to a marker. */
+function sanitizeModel(raw) {
+    const s = asString(raw);
+    if (s === null) {
+        return null;
+    }
+    const cleaned = s.replace(/[^A-Za-z0-9._:-]/g, "").slice(0, 64);
+    return cleaned.length > 0 ? cleaned : "unknown";
+}
+/** True when a user record is a tool-result carrier, not a human prompt:
+ * a toolUseResult key is present, or any message.content block has type
+ * "tool_result". Only block TYPE is inspected — never block content. */
+function isToolResultCarrier(record) {
+    if ("toolUseResult" in record) {
+        return true;
+    }
+    const message = record.message;
+    const content = message?.content;
+    if (Array.isArray(content)) {
+        return content.some((block) => typeof block === "object" &&
+            block !== null &&
+            block.type === "tool_result");
+    }
+    return false;
+}
+function createSessionParser() {
+    const events = [];
+    let skippedLines = 0;
+    let unknownTypes = 0;
+    function pushLine(line) {
+        if (line.trim() === "") {
+            return;
+        }
+        let record;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed !== "object" || parsed === null) {
+                skippedLines++;
+                return;
+            }
+            record = parsed;
+        }
+        catch {
+            skippedLines++;
+            return;
+        }
+        const type = asString(record.type);
+        if (!type) {
+            skippedLines++;
+            return;
+        }
+        if (IGNORED_TYPES.has(type)) {
+            return;
+        }
+        const sessionId = asString(record.sessionId);
+        const timestampMs = Date.parse(asString(record.timestamp) ?? "");
+        if (!sessionId || Number.isNaN(timestampMs)) {
+            skippedLines++;
+            return;
+        }
+        const isSidechain = record.isSidechain === true;
+        if (type === "assistant") {
+            const message = record.message;
+            const usageRaw = message?.usage;
+            events.push({
+                kind: "assistant",
+                sessionId,
+                timestampMs,
+                isSidechain,
+                dedupKey: asString(record.requestId) ??
+                    asString(message?.id) ??
+                    asString(record.uuid) ??
+                    `${sessionId}:${timestampMs}`,
+                model: sanitizeModel(message?.model),
+                usage: usageRaw
+                    ? {
+                        input: asNumber(usageRaw.input_tokens),
+                        output: asNumber(usageRaw.output_tokens),
+                        cacheRead: asNumber(usageRaw.cache_read_input_tokens),
+                        cacheWrite: asNumber(usageRaw.cache_creation_input_tokens),
+                    }
+                    : null,
+            });
+        }
+        else if (type === "user") {
+            events.push({
+                kind: isSidechain || isToolResultCarrier(record) ? "activity" : "prompt",
+                sessionId,
+                timestampMs,
+                isSidechain,
+            });
+        }
+        else if (type === "system" || type === "attachment") {
+            events.push({ kind: "activity", sessionId, timestampMs, isSidechain });
+        }
+        else {
+            unknownTypes++;
+        }
+    }
+    return {
+        pushLine,
+        finish: () => ({ events, skippedLines, unknownTypes }),
+    };
+}
+function parseSessionContent(content) {
+    const parser = createSessionParser();
+    for (const line of content.split("\n")) {
+        parser.pushLine(line);
+    }
+    return parser.finish();
+}

package/dist/prices.js

@@ -0,0 +1,59 @@
+"use strict";
+// Public list prices used for spend_cents_estimated — an ESTIMATE, always
+// reported with an honesty gap. Cents per million tokens, matched by
+// substring on the model id (vendor ids look like "claude-opus-4-8",
+// "claude-sonnet-5", "claude-haiku-4-5-20251001", "claude-fable-5").
+//
+// Bump SUMMARIZER_VERSION whenever summarization semantics change — the
+// server stamps source_connector as `claude-code-local@<version>` so
+// restatements are traceable to summarizer behavior.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_RATES = exports.SUMMARIZER_VERSION = void 0;
+exports.ratesForModel = ratesForModel;
+exports.estimateCents = estimateCents;
+exports.SUMMARIZER_VERSION = 1;
+const OPUS = {
+    input: 1_500,
+    output: 7_500,
+    cacheWrite: 1_875,
+    cacheRead: 150,
+};
+const SONNET = {
+    input: 300,
+    output: 1_500,
+    cacheWrite: 375,
+    cacheRead: 30,
+};
+const HAIKU = {
+    input: 100,
+    output: 500,
+    cacheWrite: 125,
+    cacheRead: 10,
+};
+/** Ordered — first substring match wins. Unknown models fall back to the
+ * top (most expensive known) tier so estimates err high, with a gap noting
+ * the unknown model. */
+const RATE_TABLE = [
+    { match: "opus", rates: OPUS },
+    { match: "fable", rates: OPUS },
+    { match: "mythos", rates: OPUS },
+    { match: "sonnet", rates: SONNET },
+    { match: "haiku", rates: HAIKU },
+];
+exports.FALLBACK_RATES = OPUS;
+function ratesForModel(model) {
+    const lower = model.toLowerCase();
+    for (const { match, rates } of RATE_TABLE) {
+        if (lower.includes(match)) {
+            return { rates, known: true };
+        }
+    }
+    return { rates: exports.FALLBACK_RATES, known: false };
+}
+function estimateCents(rates, usage) {
+    return ((usage.input * rates.input +
+        usage.output * rates.output +
+        usage.cacheWrite * rates.cacheWrite +
+        usage.cacheRead * rates.cacheRead) /
+        1_000_000);
+}

package/dist/push.js

@@ -0,0 +1,49 @@
+"use strict";
+// HTTP push of a locally-built batch to POST /api/agent/ingest. The only
+// network call the agent makes; the payload is the privacy-tested
+// AgentIngestRequest and nothing else.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushBatch = pushBatch;
+async function pushBatch(apiBaseUrl, token, batch, fetchImpl = fetch) {
+    const url = `${apiBaseUrl.replace(/\/+$/, "")}/api/agent/ingest`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(batch),
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: null,
+            error: `network error: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        // Non-JSON error page — fall through with the status alone.
+    }
+    if (!response.ok) {
+        const message = typeof body === "object" &&
+            body !== null &&
+            typeof body.error === "string"
+            ? body.error
+            : `server returned ${response.status}`;
+        return { ok: false, status: response.status, error: message };
+    }
+    const counts = body;
+    return {
+        ok: true,
+        subjects: counts?.subjects ?? 0,
+        records: counts?.records ?? 0,
+        signals: counts?.signals ?? 0,
+    };
+}

package/dist/stream.js

@@ -0,0 +1,60 @@
+"use strict";
+// Streaming session-file reader: feeds JSONL lines into the allowlist
+// parser without ever materializing a whole file as one string. Documented
+// multi-GB session files (claude-code#18905/#22365) exceed V8's ~0.5 GB
+// string ceiling, so `readFileSync` throws before parsing — a line stream
+// has no such ceiling. Unreadable files are counted, never fatal (the
+// lenient-by-design rule from parse.ts).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSessionFilesStreaming = parseSessionFilesStreaming;
+const promises_1 = require("node:fs/promises");
+const node_readline_1 = require("node:readline");
+const parse_1 = require("./parse");
+async function parseSessionFilesStreaming(paths) {
+    // Per-file accounting is all-or-nothing, mirroring the old readFileSync
+    // semantics: a file that errors mid-read (rotation, truncation, revoked
+    // permission) contributes NOTHING — its already-read prefix must not
+    // leak partial events into the batch while the file is simultaneously
+    // reported unreadable.
+    const merged = { events: [], skippedLines: 0, unknownTypes: 0 };
+    let unreadableFiles = 0;
+    for (const path of paths) {
+        // Open explicitly first so ENOENT/EACCES surface here, not as a late
+        // async 'error' event racing the line loop.
+        let handle;
+        try {
+            handle = await (0, promises_1.open)(path, "r");
+        }
+        catch {
+            unreadableFiles++;
+            continue;
+        }
+        const parser = (0, parse_1.createSessionParser)();
+        try {
+            const rl = (0, node_readline_1.createInterface)({
+                input: handle.createReadStream({ encoding: "utf8" }),
+                crlfDelay: Infinity,
+            });
+            // for-await propagates mid-read stream errors into the catch below.
+            for await (const line of rl) {
+                parser.pushLine(line);
+            }
+        }
+        catch {
+            unreadableFiles++;
+            continue;
+        }
+        finally {
+            // autoClose usually closed it already; double-close is a no-op error.
+            await handle.close().catch(() => { });
+        }
+        const result = parser.finish();
+        // No spread here: a multi-million-event file would overflow the stack.
+        for (const event of result.events) {
+            merged.events.push(event);
+        }
+        merged.skippedLines += result.skippedLines;
+        merged.unknownTypes += result.unknownTypes;
+    }
+    return { parsed: merged, unreadableFiles };
+}

package/dist/summarize.js

@@ -0,0 +1,180 @@
+"use strict";
+// Pure local summarizer: ParsedEvents in → metric records + sub-daily
+// signals out. No I/O, no clock (the window comes from the caller), no
+// content — deterministic over the same events, mirroring the frozen
+// Connector.normalize() purity rule.
+//
+// Two correctness rules from docs/connector-facts.md §5 are load-bearing:
+//   • Dedup usage by requestId, **last-wins** ("keep final entry") — the
+//     final streamed line restates cumulative usage; first-wins undercounts.
+//   • Sessions = distinct sessionId with isSidechain:false ("human
+//     sessions"); subagent usage is still summed, but a sidechain is not a
+//     session. Streamed duplicate lines are not extra activity either.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utcDay = utcDay;
+exports.summarize = summarize;
+const prices_1 = require("./prices");
+/** Exported so window pinning (index.ts) buckets days identically —
+ * one formatter, no silent drift between pinning and aggregation. */
+function utcDay(timestampMs) {
+    return new Date(timestampMs).toISOString().slice(0, 10);
+}
+function utcHour(timestampMs) {
+    return new Date(timestampMs).getUTCHours();
+}
+/** Peak simultaneous sessions: the max number of inclusive [min,max] event
+ * intervals overlapping at any instant (which always occurs at some
+ * interval's start). Real temporal overlap — not an hourly bucket count —
+ * so "peak concurrency" means what it says. */
+function peakConcurrency(intervals) {
+    let peak = 0;
+    for (const a of intervals) {
+        let count = 0;
+        for (const b of intervals) {
+            if (b.min <= a.min && a.min <= b.max) {
+                count++;
+            }
+        }
+        if (count > peak) {
+            peak = count;
+        }
+    }
+    return peak;
+}
+function emptyDay() {
+    return {
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        spendCents: 0,
+        prompts: 0,
+        humanSessions: new Set(),
+        sessionIntervals: new Map(),
+        modelRequests: new Map(),
+        modelTokens: new Map(),
+        hours: Array.from({ length: 24 }, () => 0),
+    };
+}
+function summarize(events, opts) {
+    // Pass 1 — collapse streamed assistant lines to ONE event per request,
+    // last-wins (the final line carries cumulative usage). Non-assistant
+    // events pass through unchanged. This dedup happens BEFORE any
+    // aggregation, so histograms and session presence never double-count a
+    // streamed turn.
+    const assistantByKey = new Map();
+    const otherEvents = [];
+    for (const event of events) {
+        if (event.kind === "assistant") {
+            assistantByKey.set(event.dedupKey, event); // last-wins
+        }
+        else {
+            otherEvents.push(event);
+        }
+    }
+    const dedupedEvents = [...otherEvents, ...assistantByKey.values()];
+    const days = new Map();
+    const unknownModels = new Set();
+    for (const event of dedupedEvents) {
+        const day = utcDay(event.timestampMs);
+        if (day < opts.window.start || day > opts.window.end) {
+            continue;
+        }
+        let agg = days.get(day);
+        if (!agg) {
+            agg = emptyDay();
+            days.set(day, agg);
+        }
+        agg.hours[utcHour(event.timestampMs)]++;
+        if (!event.isSidechain) {
+            agg.humanSessions.add(event.sessionId);
+        }
+        const interval = agg.sessionIntervals.get(event.sessionId);
+        if (interval) {
+            interval.min = Math.min(interval.min, event.timestampMs);
+            interval.max = Math.max(interval.max, event.timestampMs);
+        }
+        else {
+            agg.sessionIntervals.set(event.sessionId, {
+                min: event.timestampMs,
+                max: event.timestampMs,
+            });
+        }
+        if (event.kind === "prompt") {
+            agg.prompts++;
+        }
+        else if (event.kind === "assistant" && event.usage) {
+            agg.usage.input += event.usage.input;
+            agg.usage.output += event.usage.output;
+            agg.usage.cacheRead += event.usage.cacheRead;
+            agg.usage.cacheWrite += event.usage.cacheWrite;
+            const model = event.model ?? "unknown";
+            const { rates, known } = (0, prices_1.ratesForModel)(model);
+            if (!known) {
+                unknownModels.add(model);
+            }
+            agg.spendCents += (0, prices_1.estimateCents)(rates, event.usage);
+            agg.modelRequests.set(model, (agg.modelRequests.get(model) ?? 0) + 1);
+            agg.modelTokens.set(model, (agg.modelTokens.get(model) ?? 0) +
+                event.usage.input +
+                event.usage.output);
+        }
+    }
+    const records = [];
+    const signals = [];
+    const base = { subject: opts.subject, attribution: opts.attribution };
+    for (const day of [...days.keys()].sort()) {
+        const agg = days.get(day);
+        const flat = [
+            ["active_day", 1],
+            ["sessions", agg.humanSessions.size],
+            ["prompts", agg.prompts],
+            ["tokens_input", agg.usage.input],
+            ["tokens_output", agg.usage.output],
+            ["tokens_cache_read", agg.usage.cacheRead],
+            ["tokens_cache_write", agg.usage.cacheWrite],
+            ["spend_cents_estimated", Math.round(agg.spendCents * 100) / 100],
+        ];
+        for (const [metricKey, value] of flat) {
+            records.push({ ...base, metricKey, day, dim: "", value });
+        }
+        for (const [model, count] of [...agg.modelRequests].sort()) {
+            records.push({
+                ...base,
+                metricKey: "model_requests",
+                day,
+                dim: `model=${model}`,
+                value: count,
+            });
+        }
+        for (const [model, tokens] of [...agg.modelTokens].sort()) {
+            records.push({
+                ...base,
+                metricKey: "model_tokens",
+                day,
+                dim: `model=${model}`,
+                value: tokens,
+            });
+        }
+        signals.push({
+            subject: opts.subject,
+            day,
+            hours: agg.hours,
+            peakConcurrency: peakConcurrency([...agg.sessionIntervals.values()]),
+            sourceGranularity: "event",
+        });
+    }
+    const gaps = [
+        {
+            kind: "other",
+            detail: "spend_cents_estimated uses public list prices, not invoices",
+        },
+    ];
+    if (unknownModels.size > 0) {
+        gaps.push({
+            kind: "other",
+            detail: `unknown model rates defaulted high: ${[...unknownModels]
+                .sort()
+                .slice(0, 5)
+                .join(", ")}`,
+        });
+    }
+    return { records, signals, gaps };
+}

package/dist/sync-run.js

@@ -0,0 +1,94 @@
+"use strict";
+// The sync flow with injected I/O (file listing, streaming parse, push,
+// output), so tests can lock the R2-critical invariant directly: a push is
+// NEVER attempted for an empty batch — the server treats the declared
+// window as authoritative (delete-then-upsert), so pushing an empty
+// authoritative window would erase previously-captured days and restate
+// nothing. The CLI (cli.ts) supplies the real deps; tests supply fakes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSync = runSync;
+const config_1 = require("./config");
+const identity_1 = require("./identity");
+const index_1 = require("./index");
+const window_1 = require("./window");
+async function runSync(opts, deps) {
+    const resolved = (0, config_1.resolveConfig)(deps.env, deps.homeDir, deps.defaultApi);
+    let config = null;
+    if (resolved.source === "invalid-env") {
+        if (!opts.dryRun) {
+            return {
+                kind: "fail",
+                message: "REVEALYST_TOKEN is set but is not a valid rva1.… device token",
+            };
+        }
+        // Dry run never needs credentials — keep that invariant even for a
+        // malformed env token, but say so loudly.
+        deps.warn("warning: REVEALYST_TOKEN is set but malformed — continuing without it (dry run)");
+    }
+    else if (resolved.source !== "none") {
+        config = resolved.config;
+    }
+    if (!config && !opts.dryRun) {
+        return {
+            kind: "fail",
+            message: "not logged in — run: revealyst-agent login --token rva1.… " +
+                "(or set REVEALYST_TOKEN for one-shot/CI use)",
+        };
+    }
+    const files = deps.listFiles();
+    if (files.length === 0) {
+        deps.log("No Claude Code session logs found — nothing to sync.");
+        return { kind: "ok" };
+    }
+    // Streamed, never readFileSync: documented multi-GB session files exceed
+    // V8's string ceiling before parse (plan R4).
+    const { parsed, unreadableFiles } = await deps.parseFiles(files.map((f) => f.path));
+    // Messaging fast-path only — the records guard below is the safety
+    // mechanism (zero events always implies zero records).
+    if (parsed.events.length === 0) {
+        deps.log("No parseable Claude Code activity found in your logs — nothing to sync.");
+        return { kind: "ok" };
+    }
+    const identity = (0, identity_1.resolveLocalIdentity)(deps.homeDir, config?.consentIdentity ?? false, deps.deviceSeed);
+    const requestedWindow = (0, window_1.trailingWindow)(deps.now(), opts.days);
+    const batch = (0, index_1.buildIngestRequest)({
+        parsed,
+        window: requestedWindow,
+        identity,
+        agentVersion: deps.agentVersion,
+    });
+    // R2 safety mechanism: never push an empty authoritative window.
+    if (batch.records.length === 0) {
+        deps.log(`No Claude Code activity within the last ${opts.days} days — nothing ` +
+            "to sync (nothing was deleted or pushed).");
+        return { kind: "ok" };
+    }
+    const activeDays = new Set(batch.records.map((r) => r.day)).size;
+    deps.log(`Summarized ${files.length} session files (${unreadableFiles} unreadable) → ` +
+        `${batch.records.length} metric records, ${batch.signals.length} day signals ` +
+        `across ${activeDays} active days [window ${batch.window.start}..${batch.window.end}]`);
+    if (batch.window.start !== requestedWindow.start) {
+        deps.log(`Window pinned to ${batch.window.start} (earliest surviving local ` +
+            "log day) so older captured history is preserved.");
+    }
+    deps.log(`Identity: ${identity.descriptor.kind} (${identity.attribution}-level attribution)`);
+    if (opts.dryRun) {
+        deps.log("Dry run — nothing pushed.");
+        return { kind: "ok" };
+    }
+    if (!config) {
+        // Unreachable: guarded above. Kept as a narrow + tripwire so a future
+        // reorder of the guards cannot compile its way into a null deref here.
+        return { kind: "fail", message: "not logged in" };
+    }
+    const result = await deps.push(config.apiBaseUrl, config.token, batch);
+    if (!result.ok) {
+        return {
+            kind: "fail",
+            message: `push failed (${result.status ?? "network"}): ${result.error}`,
+        };
+    }
+    deps.log(`Pushed: ${result.records} records, ${result.signals} signals, ` +
+        `${result.subjects} subject(s) upserted.`);
+    return { kind: "ok" };
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+// Local mirrors of the frozen W0-C contract shapes (src/contracts/**) the
+// agent emits. The CLI is a separate package that runs on end-user machines
+// and must not import the monolith; drift between these mirrors and the
+// frozen zod schemas is caught by the repo-side contract test
+// (tests/agent-cli-contract.test.ts), which validates a real built batch
+// against the frozen schemas — the rule-2 seam.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/window.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trailingWindow = trailingWindow;
+/** Trailing inclusive UTC-day window ending today: the sync default.
+ * Local logs only retain ~30 days (connector-facts §5), so `days` beyond
+ * retention just yields empty days. */
+function trailingWindow(now, days) {
+    if (!Number.isInteger(days) || days < 1) {
+        throw new Error("days must be a positive integer");
+    }
+    const end = now.toISOString().slice(0, 10);
+    const startDate = new Date(now.getTime() - (days - 1) * 86_400_000);
+    return { start: startDate.toISOString().slice(0, 10), end };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@revealyst/agent",
+  "version": "0.2.0",
+  "description": "Revealyst Agent — reads Claude Code session logs, summarizes them locally to metric records (never raw prompt content), pushes via device token.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/instashop-dev/revealyst.git",
+    "directory": "packages/revealyst-agent"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "revealyst-agent": "dist/cli.js"
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  }
+}