ai-hist 0.3.7 → 0.6.0

package/README.md

@@ -49,7 +49,7 @@ npm run build
 node dist/mcp-server.js
 ```
 
-The MCP server exposes tools for search, recent history, session lookup, temporal context, evidence packing, stats, trajectory search, and task WHY lookup over stdio. It runs on the user's machine and uses the same data-opening behavior as the SDK: SQLite first, then local fallback scanning.
+The MCP server exposes tools for search, recent history, the session catalog, session lookup, temporal context, evidence packing, stats, trajectory search, and task WHY lookup over stdio. It runs on the user's machine and uses the same data-opening behavior as the SDK: SQLite first, then local fallback scanning.
 
 To expose only one project through MCP, pass a project scope when launching the server. Exact project matches and child paths are included.
 
@@ -67,6 +67,57 @@ Contract tools:
 - `stats()`
 - `search_trajectories(query, limit?)`
 - `why_for_task(query)`
+- `list_sessions(sources?, limit?, before_ms?, after?)`
+
+## Session catalog
+
+`sessions` is a materialized catalog of every coding-agent session ai-hist knows about — one row per `(source, session_id)`, with cwd, git branch, first/last activity, the first prompt, observed models, originator, agent version, and repo identity. It is populated by shallow discovery (cheap, metadata only) and upgraded in place by a full `ai-hist sync`. `discoveryState` says which you are looking at: `'shallow'` for a catalog row whose transcript has not been ingested, `'full'` once it has (rows written before the catalog existed store `NULL` and read as `'full'`).
+
+Reading it is one indexed query over a single table — no provider transcript is opened and no prompt history is scanned — so it is the fast path for "which sessions exist?" on first paint:
+
+```ts
+import { openAiHist, discoverSessions, SESSION_CATALOG_CONTRACT_VERSION } from 'ai-hist';
+
+const hist = await openAiHist();
+for (const s of hist.listSessionCatalog({ limit: 20 })) {
+  console.log(s.lastActivityMs, s.source, s.sessionId, s.cwd, s.firstPrompt);
+}
+```
+
+The catalog's total order is `(lastActivityMs DESC, source ASC, sessionId ASC)`, with rows of unknown recency last. Recency alone is not a key: one discovery pass can stamp many sessions with the same mtime-derived millisecond, so paginate with `listSessionCatalogPage` and follow its cursor, which carries all three columns:
+
+```ts
+let after;
+for (;;) {
+  const page = hist.listSessionCatalogPage({ limit: 20, after });
+  render(page.sessions);
+  if (!page.nextCursor) break;   // null once the catalog is exhausted
+  after = page.nextCursor;       // { lastActivityMs, source, sessionId }
+}
+```
+
+`nextCursor` is non-null only when the page filled its limit, so the loop terminates on an empty catalog and on a null-timestamp tail alike — both cases where a `beforeMs`-only walk either spins forever or silently drops the rows tied with a page boundary. `beforeMs` survives as a *coarse* cutoff ("anything before last Tuesday") and is ignored when `after` is set. The same contract is available from the CLI as the `next_cursor` field of `sessions list --json`, fed back as `--after-source` + `--after-session-id` (both required together, and `--after-ms` alone is refused — a timestamp is not a cursor). Omit `--after-ms` to continue through the undated tail.
+
+`trajectory` rows are excluded — trajectories are derived records, not sessions. A configured `projectScope` constrains rows by `cwd`, so sources with no working directory (relay) drop out of a scoped listing. A negative `limit` throws (SQLite would read it as "unlimited"). In JSONL fallback mode (no SQLite database) the catalog is empty and the methods return no rows; only the native discovery engine writes it.
+
+To populate or refresh the catalog, run shallow discovery. It scans the known provider locations with bounded reads, orders candidates globally by recency before applying the limit, and skips sources whose bytes have not changed since the last run:
+
+```ts
+const { sessions, diagnostics, summary } = await discoverSessions({
+  sources: ['claude', 'codex'],   // omit for every discoverable source
+  limit: 50,                      // global across providers, by recency
+  onSession: (s) => render(s),    // streams as rows arrive
+});
+
+console.log(summary.discovered, summary.skippedUnchanged, summary.counters.bytesRead);
+for (const d of diagnostics) console.warn(`[${d.source}] ${d.locator ?? ''}: ${d.error}`);
+```
+
+`discoverSessions` is a top-level function, not an `AiHist` method: it drives `ai-hist sessions discover --json` (binary discovery is `$AI_HIST_RUST_BIN` → the install.sh location → `ai-hist` on `PATH`, the same as `pushToCloud`), and that writes the on-disk database. An `AiHist` instance is an in-memory snapshot taken at open time, so re-open it before listing to see freshly discovered rows.
+
+Failure behavior matches the CLI's: one provider blowing up yields a diagnostic and the run still resolves. The promise rejects with a `DiscoveryError` when the binary cannot be run at all (the message names `AI_HIST_RUST_BIN`), when the run exits non-zero because every selected provider failed, or when the closing summary is missing or announces a contract version this SDK does not implement — the version is checked for you against `SESSION_CATALOG_CONTRACT_VERSION` rather than left as a field to remember. The native command writes its diagnostics and summary trailer even on an all-provider failure, so a `DiscoveryError` carries `diagnostics`, `summary`, `stderr`, and `exitCode`. Unparseable or unrecognized JSONL lines are skipped rather than failing the run.
+
+An exception thrown by `onSession` or `onDiagnostic` aborts the run: the child process is killed and the promise rejects with your error, instead of escaping the stream handler as an uncaught exception in the host.
 
 ## API
 
@@ -83,8 +134,12 @@ hist.sourceKind: 'sqlite' | 'jsonl'
 hist.projectScope: string | undefined
 
 hist.recent(opts?): HistoryEntry[]            // newest prompts first
-hist.listSessions(opts?): SessionSummary[]    // grouped by session_id, last activity DESC
+hist.listSessions(opts?): SessionSummary[]    // grouped from history by session_id, last activity DESC
+hist.listSessionCatalog(opts?): CatalogSession[]      // the sessions catalog: cache-only, one indexed query
+hist.listSessionCatalogPage(opts?): SessionCatalogPage // the same page plus its nextCursor
 hist.getSession(sessionId): HistoryEntry[]    // all prompts in a session, oldest first
+hist.getSessionEvents(sessionId): SessionEvent[] // full transcript: text, thinking, tool calls/results, token usage
+hist.getToolCalls(sessionId): SessionToolCall[]  // the session's tool invocations
 hist.getEntry(id): HistoryEntry | null
 hist.getInTimeWindow(timestampMs, windowMs): HistoryEntry[]
 hist.search(query, opts?): HistoryEntry[]     // literal substring search, recent matches first
@@ -95,9 +150,14 @@ hist.stats(): Stats                           // counts + date range
 
 All list-style methods accept `{ source?, project?, limit?, beforeMs? }`. `beforeMs` is the cursor for paginating older results.
 
+The catalog methods take `{ sources?, limit?, beforeMs?, after? }` instead — they filter on the catalog's own `source` column, not on project, and `after` is the cursor for paging.
+
 ```ts
 resumeCommand(entry): string | null           // shell command per source; null for relay
 defaultDbPath(): string                       // resolve env / OS default
+discoverSessions(opts?): Promise<DiscoverResult>  // drives `ai-hist sessions discover --json`
+SESSION_CATALOG_CONTRACT_VERSION: number      // native session-catalog output contract (1)
+DiscoveryError                                // thrown by discoverSessions; carries diagnostics + summary
 ```
 
 ## Trajectories
@@ -160,8 +220,46 @@ CREATE TABLE history (
 );
 
 CREATE VIRTUAL TABLE history_fts USING fts5(prompt, project, content='history', content_rowid='id');
+
+CREATE TABLE sessions (
+  session_id TEXT NOT NULL,
+  source TEXT NOT NULL,
+  cwd TEXT,
+  git_branch TEXT,
+  first_activity_ms INTEGER,
+  last_activity_ms INTEGER,
+  last_assistant_text TEXT,
+  raw_path TEXT,
+  parser_version INTEGER NOT NULL DEFAULT 1,
+  first_prompt TEXT,
+  models_json TEXT,
+  originator TEXT,
+  agent_version TEXT,
+  repo_url TEXT,
+  initial_commit TEXT,
+  workspace_roots_json TEXT,
+  source_stamp TEXT,
+  discovery_state TEXT,
+  PRIMARY KEY (session_id, source)
+);
+
+CREATE INDEX idx_sessions_recency ON sessions(last_activity_ms DESC, source, session_id);
+CREATE INDEX idx_sessions_source_recency ON sessions(source, last_activity_ms DESC, session_id);
+CREATE INDEX idx_sessions_source_last ON sessions(source, last_activity_ms DESC);
+CREATE INDEX idx_sessions_raw_path ON sessions(source, raw_path);
+
+CREATE TABLE discovery_skips (
+  source TEXT NOT NULL,
+  locator TEXT NOT NULL,
+  stamp TEXT NOT NULL,
+  reason TEXT,
+  updated_ms INTEGER,
+  PRIMARY KEY (source, locator)
+);
 ```
 
+`models_json` and `workspace_roots_json` hold JSON string arrays or `NULL` (never `[]`); the SDK parses both into arrays. The catalog columns were added after 0.5.0, so when the SDK opens an older database file it backfills the missing columns on its in-memory copy with `ALTER TABLE` — the file on disk is not touched, and the absent values read as `NULL`.
+
 Trajectory sync also creates a structured `trajectories` table and inserts each per-run compact file into `history` with `source='trajectory'`, so general history search and WHY-specific lookup both work.
 
 ## License

package/dist/cloud-client.d.ts

@@ -1,3 +1,4 @@
+export { pushToCloud, resolveAiHistBinary, type PushReport, type PushOptions } from './cloud-push.js';
 export interface RelayhistoryAuth {
     baseUrl: string;
     accessToken: string;

package/dist/cloud-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-client.d.ts","sourceRoot":"","sources":["../src/cloud-client.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAajC,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CASnF;AAED,wBAAsB,UAAU,CAC9B,gBAAgB,EAAE,MAAM,EACxB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,gBAAgB,CAAC,CAkD3B"}
+{"version":3,"file":"cloud-client.d.ts","sourceRoot":"","sources":["../src/cloud-client.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEtG,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAajC,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CASnF;AAED,wBAAsB,UAAU,CAC9B,gBAAgB,EAAE,MAAM,EACxB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,gBAAgB,CAAC,CAkD3B"}

package/dist/cloud-client.js

@@ -1,6 +1,8 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
+// Re-export the in-process cloud push so `ai-hist/cloud` exposes auth + push.
+export { pushToCloud, resolveAiHistBinary } from './cloud-push.js';
 function authPath() {
     const configDir = process.env.AI_HIST_CONFIG_DIR ?? join(homedir(), '.config', 'ai-hist');
     return join(configDir, 'auth.json');

package/dist/cloud-client.js.map

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

package/dist/cloud-push.d.ts

@@ -0,0 +1,51 @@
+/**
+ * In-process cloud push — a thin wrapper over the `ai-hist` Rust binary.
+ *
+ * Rather than re-implement the push pipeline (outbox batching, cursor, wire
+ * envelopes, dedup hashing) in TypeScript — which would have to stay byte-for-
+ * byte compatible with the Rust client forever — this spawns the real
+ * `ai-hist push --json` and parses its result. The Rust binary is the single
+ * source of truth for the push logic; this is just an ergonomic SDK surface
+ * over it, so hosts (e.g. the Agent Relay runtime) can sync without shelling
+ * out to a CLI by hand.
+ */
+import { spawn } from 'node:child_process';
+export interface PushReport {
+    sent: number;
+    accepted: number;
+    batchId: string | null;
+    cursor?: unknown;
+    /** Accepted per-source record limit after any capacity retry. */
+    batchLimit?: number;
+    /** Number of HTTP ingest attempts made by this push. */
+    attempts?: number;
+}
+export interface PushOptions {
+    /** Explicit path to the ai-hist binary (overrides discovery). */
+    binPath?: string;
+    /** Rows scanned per source (forwarded as `--limit`). */
+    limit?: number;
+    /** Session/trajectory ids to exclude (forwarded as repeated `--incognito`). */
+    incognito?: Iterable<string>;
+    /** Extra environment for the spawned binary (merged over `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable spawn for testing. */
+    spawnFn?: typeof spawn;
+}
+/**
+ * Resolve the ai-hist binary. An explicit override is **authoritative** — it is
+ * returned verbatim without falling through to discovery, so the caller always
+ * runs the binary it asked for (an unusable path surfaces later in `pushToCloud`
+ * as a no-op push, never a silent switch to a different binary). With no
+ * override: `$AI_HIST_RUST_BIN` → the install.sh location → the `ai-hist`
+ * wrapper on `PATH`. Always returns a string.
+ */
+export declare function resolveAiHistBinary(explicit?: string): string;
+/**
+ * Push new local history to relayhistory-cloud by driving `ai-hist push --json`.
+ * Resolves `null` when the binary isn't installed or the user isn't
+ * authenticated (both non-fatal for a background loop); rejects on other
+ * non-zero exits or unparseable output.
+ */
+export declare function pushToCloud(opts?: PushOptions): Promise<PushReport | null>;
+//# sourceMappingURL=cloud-push.d.ts.map

package/dist/cloud-push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-push.d.ts","sourceRoot":"","sources":["../src/cloud-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAK9D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAaD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA+D9E"}

package/dist/cloud-push.js

@@ -0,0 +1,113 @@
+/**
+ * In-process cloud push — a thin wrapper over the `ai-hist` Rust binary.
+ *
+ * Rather than re-implement the push pipeline (outbox batching, cursor, wire
+ * envelopes, dedup hashing) in TypeScript — which would have to stay byte-for-
+ * byte compatible with the Rust client forever — this spawns the real
+ * `ai-hist push --json` and parses its result. The Rust binary is the single
+ * source of truth for the push logic; this is just an ergonomic SDK surface
+ * over it, so hosts (e.g. the Agent Relay runtime) can sync without shelling
+ * out to a CLI by hand.
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const AI_HIST_RUST_BIN_ENV = 'AI_HIST_RUST_BIN';
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the ai-hist binary. An explicit override is **authoritative** — it is
+ * returned verbatim without falling through to discovery, so the caller always
+ * runs the binary it asked for (an unusable path surfaces later in `pushToCloud`
+ * as a no-op push, never a silent switch to a different binary). With no
+ * override: `$AI_HIST_RUST_BIN` → the install.sh location → the `ai-hist`
+ * wrapper on `PATH`. Always returns a string.
+ */
+export function resolveAiHistBinary(explicit) {
+    if (typeof explicit === 'string' && explicit.length > 0)
+        return explicit;
+    const known = [
+        process.env[AI_HIST_RUST_BIN_ENV],
+        join(homedir(), '.local', 'share', 'ai-hist', 'ai-hist-rust-bin'),
+    ].filter((c) => typeof c === 'string' && c.length > 0);
+    for (const candidate of known) {
+        if (isExecutable(candidate))
+            return candidate;
+    }
+    // Let PATH resolution (and ENOENT handling) take over.
+    return 'ai-hist';
+}
+/**
+ * Push new local history to relayhistory-cloud by driving `ai-hist push --json`.
+ * Resolves `null` when the binary isn't installed or the user isn't
+ * authenticated (both non-fatal for a background loop); rejects on other
+ * non-zero exits or unparseable output.
+ */
+export function pushToCloud(opts = {}) {
+    const spawnFn = opts.spawnFn ?? spawn;
+    const bin = resolveAiHistBinary(opts.binPath);
+    const args = ['push', '--json'];
+    if (opts.limit != null)
+        args.push('--limit', String(opts.limit));
+    for (const id of opts.incognito ?? [])
+        args.push('--incognito', id);
+    const spawnOpts = {
+        env: { ...process.env, ...opts.env },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    };
+    return new Promise((resolve, reject) => {
+        const child = spawnFn(bin, args, spawnOpts);
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', (err) => {
+            // Binary unavailable — missing (ENOENT), not executable (EACCES/EPERM), or
+            // a directory (ENOTDIR/EISDIR). All mean "nothing to sync", the same
+            // no-op contract a background loop relies on.
+            if (['ENOENT', 'EACCES', 'EPERM', 'ENOTDIR', 'EISDIR'].includes(err.code ?? '')) {
+                resolve(null);
+                return;
+            }
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                // Not logged in yet is expected before `reflex on` completes.
+                if (/not authenticated|no relayhistory auth|run `?ai-hist login/i.test(stderr)) {
+                    resolve(null);
+                    return;
+                }
+                reject(new Error(`ai-hist push failed (exit ${code}): ${stderr.trim().slice(0, 300)}`));
+                return;
+            }
+            try {
+                const parsed = (stdout.trim() ? JSON.parse(stdout) : {});
+                resolve({
+                    sent: typeof parsed.sent === 'number' ? parsed.sent : 0,
+                    accepted: typeof parsed.accepted === 'number' ? parsed.accepted : 0,
+                    batchId: typeof parsed.batchId === 'string' ? parsed.batchId : null,
+                    cursor: parsed.cursor,
+                    ...(typeof parsed.batchLimit === 'number' ? { batchLimit: parsed.batchLimit } : {}),
+                    ...(typeof parsed.attempts === 'number' ? { attempts: parsed.attempts } : {}),
+                });
+            }
+            catch (err) {
+                reject(new Error(`could not parse ai-hist push output: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        });
+    });
+}
+//# sourceMappingURL=cloud-push.js.map

package/dist/cloud-push.js.map

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

package/dist/cloud-push.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cloud-push.test.d.ts.map

package/dist/cloud-push.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-push.test.d.ts","sourceRoot":"","sources":["../src/cloud-push.test.ts"],"names":[],"mappings":""}

package/dist/cloud-push.test.js

@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { test } from 'node:test';
+import { pushToCloud } from './cloud-push.js';
+/** Minimal fake child process that scripts stdout/stderr/exit for one run. */
+function fakeSpawn(script) {
+    const calls = [];
+    const spawnFn = ((bin, args) => {
+        calls.push({ bin, args });
+        const child = new EventEmitter();
+        child.stdout = new EventEmitter();
+        child.stderr = new EventEmitter();
+        // Emit asynchronously so the caller has attached its listeners.
+        setImmediate(() => {
+            if (script.errorCode) {
+                const err = new Error('spawn failed');
+                err.code = script.errorCode;
+                child.emit('error', err);
+                return;
+            }
+            if (script.stdout)
+                child.stdout.emit('data', script.stdout);
+            if (script.stderr)
+                child.stderr.emit('data', script.stderr);
+            child.emit('close', script.code ?? 0);
+        });
+        return child;
+    });
+    return { spawnFn, calls };
+}
+test('pushToCloud parses ai-hist push --json output into a report', async () => {
+    const { spawnFn, calls } = fakeSpawn({
+        stdout: JSON.stringify({
+            sent: 3,
+            accepted: 3,
+            batchId: 'b_abc',
+            cursor: { history_id: 9 },
+            batchLimit: 100,
+            attempts: 2,
+        }),
+    });
+    const report = await pushToCloud({ binPath: '/bin/echo', spawnFn, limit: 200, incognito: ['s1', 's2'] });
+    assert.deepEqual(report, {
+        sent: 3,
+        accepted: 3,
+        batchId: 'b_abc',
+        cursor: { history_id: 9 },
+        batchLimit: 100,
+        attempts: 2,
+    });
+    // Forwards the flags to the binary.
+    assert.deepEqual(calls[0].args, ['push', '--json', '--limit', '200', '--incognito', 's1', '--incognito', 's2']);
+});
+test('pushToCloud returns null when the binary is not installed (ENOENT)', async () => {
+    const { spawnFn } = fakeSpawn({ errorCode: 'ENOENT' });
+    const report = await pushToCloud({ binPath: '/bin/echo', spawnFn });
+    assert.equal(report, null);
+});
+test('pushToCloud returns null when the binary is not executable (EACCES)', async () => {
+    const { spawnFn } = fakeSpawn({ errorCode: 'EACCES' });
+    const report = await pushToCloud({ binPath: '/some/dir', spawnFn });
+    assert.equal(report, null);
+});
+test('pushToCloud returns null when not authenticated', async () => {
+    const { spawnFn } = fakeSpawn({ code: 1, stderr: 'error: not authenticated — run `ai-hist login`' });
+    const report = await pushToCloud({ binPath: '/bin/echo', spawnFn });
+    assert.equal(report, null);
+});
+test('pushToCloud rejects on other non-zero exits', async () => {
+    const { spawnFn } = fakeSpawn({ code: 2, stderr: 'boom: server exploded' });
+    await assert.rejects(pushToCloud({ binPath: '/bin/echo', spawnFn }), /ai-hist push failed \(exit 2\).*boom/);
+});
+test('pushToCloud treats empty stdout as a zero-record push', async () => {
+    const { spawnFn } = fakeSpawn({ stdout: '' });
+    const report = await pushToCloud({ binPath: '/bin/echo', spawnFn });
+    assert.deepEqual(report, { sent: 0, accepted: 0, batchId: null, cursor: undefined });
+});
+test('pushToCloud rejects when the binary prints malformed JSON', async () => {
+    const { spawnFn } = fakeSpawn({ code: 0, stdout: '{ truncated' });
+    await assert.rejects(pushToCloud({ binPath: '/bin/echo', spawnFn }), /could not parse ai-hist push output/);
+});
+//# sourceMappingURL=cloud-push.test.js.map

package/dist/cloud-push.test.js.map

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

package/dist/index.d.ts

@@ -13,6 +13,8 @@
  */
 import { type Database } from 'sql.js';
 import { type TrajectoryDecision, type TrajectoryRetrospective } from './trajectory-sources.js';
+import { type CatalogSession, type ListCatalogOptions, type SessionCatalogPage } from './session-catalog.js';
+export { SESSION_CATALOG_CONTRACT_VERSION, DiscoveryError, discoverSessions, type CatalogSession, type CatalogCursor, type SessionCatalogPage, type ListCatalogOptions, type DiscoverSessionsOptions, type DiscoverResult, type DiscoverySummary, type DiscoveryDiagnostic, type DiscoveryCounters, type ProviderDiscoverySummary, type SourceExemption, } from './session-catalog.js';
 export type Source = 'claude' | 'codex' | 'cursor' | 'grok' | 'relay' | 'trajectory' | 'opencode';
 export interface HistoryEntry {
     id: number;
@@ -23,6 +25,12 @@ export interface HistoryEntry {
     timestampMs: number;
     gitBranch: string | null;
 }
+/**
+ * The pre-catalog `sessions` row shape, kept for backward compatibility.
+ * New code wants {@link CatalogSession} (via `listSessionCatalog`), which
+ * covers the whole catalog row: first prompt, models, originator, repo
+ * identity, and discovery state.
+ */
 export interface SessionMeta {
     sessionId: string;
     source: Source;
@@ -73,6 +81,44 @@ export interface SessionSummary {
     firstActivityMs: number;
     promptCount: number;
 }
+/**
+ * One normalized transcript event from the `session_events` table: user and
+ * assistant text, thinking, tool calls, and tool results, in order.
+ * `tokenUsage` is the parsed `token_json` blob — Claude's per-message
+ * `usage` shape, or a Codex per-request delta (`input_tokens` inclusive of
+ * `cached_input_tokens`). Claude repeats the same usage on every content
+ * block of a message, so sum per distinct `messageId`, not per row.
+ */
+export interface SessionEvent {
+    id: number;
+    source: Source;
+    sessionId: string;
+    project: string | null;
+    cwd: string | null;
+    gitBranch: string | null;
+    messageId: string | null;
+    parentId: string | null;
+    tsMs: number;
+    role: 'user' | 'assistant' | 'tool_result';
+    kind: 'text' | 'thinking' | 'tool_use' | 'tool_result';
+    text: string | null;
+    model: string | null;
+    tokenUsage: Record<string, unknown> | null;
+    eventUid: string;
+}
+/** One tool invocation from the `tool_calls` table. */
+export interface SessionToolCall {
+    id: number;
+    source: Source;
+    sessionId: string;
+    messageId: string | null;
+    toolUseId: string;
+    name: string;
+    target: string | null;
+    argsJson: string | null;
+    isError: boolean | null;
+    tsMs: number | null;
+}
 export interface ListOptions {
     source?: Source;
     project?: string;
@@ -144,8 +190,8 @@ export interface OpenOptions {
     /**
      * What to do when the SQLite DB is missing:
      *   - `'jsonl'` (default): scan local Claude/Codex/Cursor/Grok history files
-     *     directly into an in-memory SQLite — works without the Python
-     *     `ai-hist sync` tool installed.
+     *     directly into an in-memory SQLite — works without the native
+     *     `ai-hist` CLI installed.
      *   - `'error'`: throw with an install hint (legacy 0.1.x behavior).
      */
     fallback?: 'jsonl' | 'error';
@@ -177,7 +223,7 @@ export declare class AiHist {
      * mode: a comma-separated list of the scanned source paths.
      */
     get dbPath(): string;
-    /** Which data path was used: `'sqlite'` (Python tool) or `'jsonl'` (fallback). */
+    /** Which data path was used: `'sqlite'` (on-disk SQLite database) or `'jsonl'` (fallback). */
     get sourceKind(): 'sqlite' | 'jsonl';
     /** Server/client-wide project scope applied to every read, if configured. */
     get projectScope(): string | undefined;
@@ -206,20 +252,87 @@ export declare class AiHist {
      * Group history into sessions, ordered by last activity (newest first).
      * Sessions without a `session_id` are skipped.
      *
+     * This derives sessions from the `history` table, so it only ever sees
+     * sessions a full `ai-hist sync` has ingested, and it pays a window-function
+     * pass over history to do it. For the fast and complete path — every session
+     * the catalog knows, including ones only shallow discovery has seen, with
+     * cwd, branch, models, originator and repo identity attached — use
+     * {@link AiHist.listSessionCatalog}. This method stays as-is for callers
+     * that want prompt counts and the project-derived grouping.
+     *
      * Implementation note: this used to use a correlated scalar subquery
      * to pick `first_prompt`, which ran in O(sessions × rows) — ~19s on a
      * 35K-row DB. Switched to `ROW_NUMBER() OVER (PARTITION BY session_id
      * ORDER BY timestamp_ms)` so first-prompt picking is a single pass
      * over the table (~300ms on the same DB). Plus the index ensure step
-     * in `openAiHist` keeps it fast even when the DB was written by the
-     * older Python CLI that didn't create `idx_history_session`.
+     * in `openAiHist` keeps it fast even when the DB was written by an
+     * older CLI that didn't create `idx_history_session`.
      */
     listSessions(opts?: ListOptions): SessionSummary[];
+    /**
+     * The session catalog, newest first — one indexed query over `sessions` and
+     * nothing else.
+     *
+     * No provider transcript is opened and neither `history` nor
+     * `session_events` is touched, so this stays fast on first paint even with
+     * thousands of historical sessions. It is the read side of the native
+     * `ai-hist sessions list`; populate the catalog with `discoverSessions()`
+     * (or a full `ai-hist sync`).
+     *
+     * Details worth knowing:
+     *   - `trajectory` rows are excluded defensively — trajectories are derived
+     *     records, not sessions, and must never appear in a session list.
+     *   - The catalog's total order is
+     *     `(last_activity_ms DESC, source ASC, session_id ASC)`. SQLite sorts
+     *     NULL lowest, so rows of unknown recency land last under `DESC` without
+     *     a helper expression. Recency alone is not a key: one discovery pass can
+     *     stamp many sessions with the same mtime-derived millisecond, which is
+     *     why the identity columns are part of the order.
+     *   - To page, use {@link AiHist.listSessionCatalogPage} and follow its
+     *     `nextCursor`. `beforeMs` is only a *coarse* cutoff ("anything before
+     *     last Tuesday"): it cannot separate rows sharing a millisecond, so a
+     *     walk built on it drops every row tied with a page boundary. It is
+     *     ignored when `after` is set.
+     *   - A configured `projectScope` constrains rows by `cwd`, like
+     *     `getHandoff`. Sources with no working directory (relay) therefore drop
+     *     out of a scoped listing.
+     *   - In JSONL fallback mode (no SQLite database) the catalog is empty and
+     *     this returns `[]`: the fallback scan builds `history` rows only, and
+     *     only the native discovery engine writes the catalog.
+     */
+    listSessionCatalog(opts?: ListCatalogOptions): CatalogSession[];
+    /**
+     * {@link AiHist.listSessionCatalog} plus the cursor that continues it.
+     *
+     * Follow `nextCursor` until it comes back `null` to walk the whole catalog:
+     * no skipped and no duplicated rows, even when a whole page shares one
+     * millisecond, and the undated tail stays reachable from a dated cursor.
+     * `nextCursor` is non-null only when the page filled its limit, mirroring
+     * the native `list_session_catalog_page` and the CLI's `next_cursor`.
+     */
+    listSessionCatalogPage(opts?: ListCatalogOptions): SessionCatalogPage;
     /** All prompts in a session, ordered oldest → newest. */
     getSession(sessionId: string, opts?: Pick<ListOptions, 'source' | 'tag'>): HistoryEntry[];
+    /**
+     * All normalized events for a session, oldest first — messages, thinking,
+     * tool calls, and tool results with per-event token usage where the
+     * transcript provides it. Returns `[]` when the database predates the
+     * `session_events` table (or in JSONL fallback mode, which has no events).
+     *
+     * Size caveat: this SDK loads the whole database file into memory, so on
+     * large event-bearing databases prefer streaming from the native CLI
+     * (`ai-hist events <session-id> --json`).
+     */
+    getSessionEvents(sessionId: string, opts?: {
+        source?: Source;
+    }): SessionEvent[];
+    /** All tool calls for a session, oldest first; `[]` on pre-events databases. */
+    getToolCalls(sessionId: string, opts?: {
+        source?: Source;
+    }): SessionToolCall[];
     /**
      * Substring search across prompt + project, case-insensitive, recent
-     * matches first. The Python CLI uses FTS5; this SDK uses LIKE because
+     * matches first. The native CLI uses FTS5; this SDK uses LIKE because
      * sql.js's default WASM build doesn't ship the FTS5 module. Plenty fast
      * for the ai-hist scale (~tens of thousands of rows); revisit if a
      * future consumer needs phrase/boolean queries.