@unpolarize/code-sessions 0.1.0

package/src/ipc.ts

@@ -0,0 +1,70 @@
+import { connect } from 'node:net';
+
+/** Hook event delivered over the daemon's unix socket (newline-delimited JSON). */
+export interface HookEvent {
+  event: string;
+  session_id: string;
+  transcript_path?: string;
+  cwd?: string;
+}
+
+export interface HookAck {
+  ok: boolean;
+  newTurns?: number;
+  flushed?: boolean;
+  error?: string;
+}
+
+const LIFECYCLE_END = new Set(['Stop', 'SubagentStop', 'SessionEnd']);
+
+export function isSessionEndEvent(event: string): boolean {
+  return LIFECYCLE_END.has(event);
+}
+
+/** Normalize a raw payload (from a socket line or a Claude hook stdin doc) into a HookEvent. */
+export function parseHookEvent(raw: unknown): HookEvent | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const r = raw as Record<string, unknown>;
+  const event = (r.event ?? r.hook_event_name ?? r.hookEventName) as string | undefined;
+  const session_id = (r.session_id ?? r.sessionId) as string | undefined;
+  if (!event || !session_id) return null;
+  const out: HookEvent = { event, session_id };
+  const tp = (r.transcript_path ?? r.transcriptPath) as string | undefined;
+  if (typeof tp === 'string') out.transcript_path = tp;
+  if (typeof r.cwd === 'string') out.cwd = r.cwd;
+  return out;
+}
+
+/** Connect to the daemon socket, send one event, resolve with its ack. */
+export function sendEvent(
+  socketPath: string,
+  event: HookEvent,
+  timeoutMs = 4000,
+): Promise<HookAck> {
+  return new Promise((resolve) => {
+    const sock = connect(socketPath);
+    let buf = '';
+    let settled = false;
+    const done = (ack: HookAck) => {
+      if (settled) return;
+      settled = true;
+      sock.destroy();
+      resolve(ack);
+    };
+    sock.setTimeout(timeoutMs);
+    sock.on('connect', () => sock.write(`${JSON.stringify(event)}\n`));
+    sock.on('data', (d) => {
+      buf += d.toString('utf8');
+      const nl = buf.indexOf('\n');
+      if (nl >= 0) {
+        try {
+          done(JSON.parse(buf.slice(0, nl)) as HookAck);
+        } catch {
+          done({ ok: false, error: 'bad ack' });
+        }
+      }
+    });
+    sock.on('timeout', () => done({ ok: false, error: 'timeout' }));
+    sock.on('error', (e) => done({ ok: false, error: e.message }));
+  });
+}

package/src/pricing.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { estimateCostUsd, priceFor } from './pricing';
+
+describe('pricing', () => {
+  it('selects a price table by fuzzy model match', () => {
+    expect(priceFor('claude-opus-4-8').output).toBe(75);
+    expect(priceFor('claude-haiku-4-5-20251001').output).toBe(5);
+    expect(priceFor('something-sonnet-ish').output).toBe(15);
+    expect(priceFor(undefined).output).toBe(15); // default = sonnet
+  });
+
+  it('computes cost as sum(tokens * $/M) / 1e6', () => {
+    const cost = estimateCostUsd(
+      { input_tokens: 1_000_000, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 },
+      'claude-opus-4-8',
+    );
+    expect(cost).toBe(15);
+  });
+
+  it('returns 0 for empty usage', () => {
+    expect(
+      estimateCostUsd(
+        { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 },
+        'claude-opus-4-8',
+      ),
+    ).toBe(0);
+  });
+});

package/src/pricing.ts

@@ -0,0 +1,45 @@
+import type { Usage } from '@unpolarize/code-sessions-schema';
+
+/** Per-million-token list prices (USD). Approximate; override per real tier. */
+export interface ModelPrice {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+const PRICES: Record<string, ModelPrice> = {
+  'claude-opus-4-8': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+  'claude-opus': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+  'claude-sonnet-4-6': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  'claude-sonnet': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  'claude-haiku-4-5': { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+  'claude-haiku': { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+};
+
+const DEFAULT_PRICE: ModelPrice = PRICES['claude-sonnet']!;
+
+export function priceFor(model: string | undefined): ModelPrice {
+  if (!model) return DEFAULT_PRICE;
+  const lower = model.toLowerCase();
+  for (const key of Object.keys(PRICES)) {
+    if (lower.includes(key)) return PRICES[key]!;
+  }
+  if (lower.includes('opus')) return PRICES['claude-opus']!;
+  if (lower.includes('sonnet')) return PRICES['claude-sonnet']!;
+  if (lower.includes('haiku')) return PRICES['claude-haiku']!;
+  return DEFAULT_PRICE;
+}
+
+/** Estimate USD cost of one turn's usage. cost = sum(tokens * $/M) / 1e6. */
+export function estimateCostUsd(usage: Usage, model?: string): number {
+  const p = priceFor(model);
+  const dollars =
+    (usage.input_tokens * p.input +
+      usage.output_tokens * p.output +
+      usage.cache_read_tokens * p.cacheRead +
+      usage.cache_write_tokens * p.cacheWrite) /
+    1_000_000;
+  // round to 6 dp to avoid float noise
+  return Math.round(dollars * 1e6) / 1e6;
+}

package/src/state.test.ts

@@ -0,0 +1,46 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { StateStore } from './state';
+import { withTempDir } from './test/tmp';
+
+describe('StateStore', () => {
+  it('initializes and persists a session', () => {
+    withTempDir((dir) => {
+      const path = join(dir, 'state.json');
+      const store = new StateStore(path);
+      const s = store.ensure('sess-1', '/tmp/sess-1.jsonl');
+      expect(s.offset).toBe(0);
+      expect(s.nextTurnIndex).toBe(0);
+      expect(existsSync(path)).toBe(true);
+    });
+  });
+
+  it('survives reload (restart-safe)', () => {
+    withTempDir((dir) => {
+      const path = join(dir, 'state.json');
+      const a = new StateStore(path);
+      a.ensure('sess-1', '/tmp/sess-1.jsonl');
+      a.update('sess-1', { offset: 128, nextTurnIndex: 4, month: '2026-06' });
+
+      const b = new StateStore(path);
+      const s = b.get('sess-1');
+      expect(s).toBeDefined();
+      expect(s!.offset).toBe(128);
+      expect(s!.nextTurnIndex).toBe(4);
+      expect(s!.month).toBe('2026-06');
+    });
+  });
+
+  it('recovers from a corrupt state file', () => {
+    withTempDir((dir) => {
+      const path = join(dir, 'state.json');
+      writeFileSync(path, 'not json at all');
+      const store = new StateStore(path);
+      expect(store.all()).toEqual({});
+      // still usable
+      store.ensure('x', '/tmp/x.jsonl');
+      expect(store.get('x')).toBeDefined();
+    });
+  });
+});

package/src/state.ts

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Daemon bookkeeping — NOT the store. Tracks, per native session, how far we
+ * have consumed its JSONL and the next canonical turn index. Rebuildable by
+ * re-scanning if lost.
+ */
+
+export interface SessionState {
+  /** native transcript path being tailed */
+  transcriptPath: string;
+  /** bytes of the transcript already consumed */
+  offset: number;
+  /** next canonical turn_index to assign */
+  nextTurnIndex: number;
+  /** YYYY-MM shard the session was filed under (from its first turn) */
+  month?: string;
+  startedAt?: string;
+  lastTs?: string;
+  endedAt?: string;
+}
+
+interface StateFile {
+  version: 1;
+  sessions: Record<string, SessionState>;
+}
+
+export class StateStore {
+  private data: StateFile;
+
+  constructor(private readonly path: string) {
+    this.data = this.read();
+  }
+
+  private read(): StateFile {
+    if (existsSync(this.path)) {
+      try {
+        const parsed = JSON.parse(readFileSync(this.path, 'utf8')) as StateFile;
+        if (parsed && parsed.version === 1 && parsed.sessions) return parsed;
+      } catch {
+        // fall through to fresh state
+      }
+    }
+    return { version: 1, sessions: {} };
+  }
+
+  /** Atomic write: tmp file + rename. */
+  private flush(): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(this.data, null, 2));
+    renameSync(tmp, this.path);
+  }
+
+  get(sessionId: string): SessionState | undefined {
+    return this.data.sessions[sessionId];
+  }
+
+  /** Get existing state or initialize a fresh one for this transcript. */
+  ensure(sessionId: string, transcriptPath: string): SessionState {
+    let s = this.data.sessions[sessionId];
+    if (!s) {
+      s = { transcriptPath, offset: 0, nextTurnIndex: 0 };
+      this.data.sessions[sessionId] = s;
+      this.flush();
+    } else if (transcriptPath && s.transcriptPath !== transcriptPath) {
+      s.transcriptPath = transcriptPath;
+      this.flush();
+    }
+    return s;
+  }
+
+  update(sessionId: string, patch: Partial<SessionState>): SessionState {
+    const s = this.data.sessions[sessionId] ?? {
+      transcriptPath: '',
+      offset: 0,
+      nextTurnIndex: 0,
+    };
+    const next = { ...s, ...patch };
+    this.data.sessions[sessionId] = next;
+    this.flush();
+    return next;
+  }
+
+  all(): Record<string, SessionState> {
+    return this.data.sessions;
+  }
+}

package/src/store/git.test.ts

@@ -0,0 +1,99 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { withTempDir } from '../test/tmp';
+import { GitStore } from './git';
+
+function git(cwd: string, ...args: string[]): string {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr}`);
+  return (r.stdout ?? '').trim();
+}
+
+function writeFile(root: string, rel: string, content: string): void {
+  const p = join(root, rel);
+  mkdirSync(join(p, '..'), { recursive: true });
+  writeFileSync(p, content);
+}
+
+describe('GitStore basics', () => {
+  it('initializes a repo with scaffolding (idempotent)', () => {
+    withTempDir((dir) => {
+      const store = new GitStore(dir);
+      store.init();
+      expect(store.isRepo()).toBe(true);
+      expect(existsSync(join(dir, '.gitignore'))).toBe(true);
+      expect(existsSync(join(dir, '.gitattributes'))).toBe(true);
+      expect(() => store.init()).not.toThrow(); // idempotent
+    });
+  });
+
+  it('commits content and reports clean trees', () => {
+    withTempDir((dir) => {
+      const store = new GitStore(dir);
+      store.init();
+      expect(store.commit('init').committed).toBe(true); // .gitignore/.gitattributes
+      expect(store.commit('noop').committed).toBe(false); // clean now
+
+      writeFile(dir, 'hosts/A/2026-06/s1/turns/000000.json', '{"a":1}');
+      const c = store.commit('add turn');
+      expect(c.committed).toBe(true);
+      expect(c.sha).toMatch(/^[0-9a-f]{7,40}$/);
+    });
+  });
+
+  it('ignores runtime (.daemon) and raw/ blobs', () => {
+    withTempDir((dir) => {
+      const store = new GitStore(dir);
+      store.init();
+      store.commit('init');
+      writeFile(dir, '.daemon/state.json', '{}');
+      writeFile(dir, 'hosts/A/2026-06/s1/raw/deadbeef', 'huge');
+      expect(store.hasChanges()).toBe(false); // both ignored
+    });
+  });
+});
+
+describe('GitStore two-host conflict-free sync', () => {
+  it('merges host-keyed writes from two machines with no conflict', () => {
+    withTempDir((root) => {
+      const remote = join(root, 'remote.git');
+      mkdirSync(remote, { recursive: true });
+      git(remote, 'init', '--bare', '-b', 'main');
+
+      // Host A: init, write, push
+      const dirA = join(root, 'hostA');
+      mkdirSync(dirA, { recursive: true });
+      const a = new GitStore(dirA, { remote, autoPush: true });
+      a.init();
+      writeFile(dirA, 'hosts/A/2026-06/sa/turns/000000.json', '{"host":"A"}');
+      const ra = a.sync('A: turn 0');
+      expect(ra.commit.committed).toBe(true);
+      expect(ra.pushed).toBe(true);
+
+      // Host B: clone, write a DIFFERENT host path, sync (pull --rebase + push)
+      const dirB = join(root, 'hostB');
+      git(root, 'clone', remote, dirB);
+      const b = new GitStore(dirB, { remote, autoPush: true });
+      b.init();
+      writeFile(dirB, 'hosts/B/2026-06/sb/turns/000000.json', '{"host":"B"}');
+      const rb = b.sync('B: turn 0');
+      expect(rb.commit.committed).toBe(true);
+      expect(rb.pushed).toBe(true);
+
+      // Host A: new write, must pull B's commit (rebase) then push — still clean
+      writeFile(dirA, 'hosts/A/2026-06/sa/turns/000001.json', '{"host":"A2"}');
+      const ra2 = a.sync('A: turn 1');
+      expect(ra2.commit.committed).toBe(true);
+      expect(ra2.pushed).toBe(true);
+
+      // Fresh clone sees ALL three files — nothing was lost or conflicted
+      const verify = join(root, 'verify');
+      git(root, 'clone', remote, verify);
+      expect(existsSync(join(verify, 'hosts/A/2026-06/sa/turns/000000.json'))).toBe(true);
+      expect(existsSync(join(verify, 'hosts/A/2026-06/sa/turns/000001.json'))).toBe(true);
+      expect(existsSync(join(verify, 'hosts/B/2026-06/sb/turns/000000.json'))).toBe(true);
+    });
+  });
+});

package/src/store/git.ts

@@ -0,0 +1,138 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Git-backed store operations. Append-only + host-keyed paths mean writers never
+ * target the same file, so commits/merges are conflict-free by construction.
+ * `.gitattributes` adds merge=union for the few append-only manifests.
+ */
+
+export interface GitResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+export interface CommitResult {
+  committed: boolean;
+  sha?: string;
+  reason?: string;
+}
+
+const FALLBACK_IDENTITY = ['-c', 'user.name=code-sessions', '-c', 'user.email=agent@code-sessions'];
+
+const GITIGNORE = `# code-sessions store — runtime + local-only artifacts
+.daemon/
+*.tmp
+# large externalized blobs stay local in MVP-1 (LFS/object-store in MVP-2)
+raw/
+`;
+
+const GITATTRIBUTES = `# append-only manifests merge by union so concurrent appends both survive
+*.jsonl merge=union
+telemetry/*.jsonl merge=union
+`;
+
+export class GitStore {
+  constructor(
+    private readonly dir: string,
+    private readonly opts: { remote?: string; autoPush?: boolean } = {},
+  ) {}
+
+  private run(args: string[], extraEnv?: Record<string, string>): GitResult {
+    const res = spawnSync('git', ['-C', this.dir, ...args], {
+      encoding: 'utf8',
+      env: { ...process.env, ...extraEnv },
+    });
+    return {
+      ok: res.status === 0,
+      stdout: (res.stdout ?? '').trim(),
+      stderr: (res.stderr ?? '').trim(),
+      code: res.status ?? -1,
+    };
+  }
+
+  isRepo(): boolean {
+    return existsSync(join(this.dir, '.git'));
+  }
+
+  /** Initialize the store repo (idempotent): git init, scaffolding files, remote. */
+  init(): void {
+    if (!this.isRepo()) {
+      const r = spawnSync('git', ['init', '-b', 'main', this.dir], { encoding: 'utf8' });
+      if (r.status !== 0) throw new Error(`git init failed: ${r.stderr}`);
+    }
+    const giPath = join(this.dir, '.gitignore');
+    if (!existsSync(giPath)) writeFileSync(giPath, GITIGNORE);
+    const gaPath = join(this.dir, '.gitattributes');
+    if (!existsSync(gaPath)) writeFileSync(gaPath, GITATTRIBUTES);
+    if (this.opts.remote) this.ensureRemote(this.opts.remote);
+  }
+
+  ensureRemote(remote: string): void {
+    const existing = this.run(['remote', 'get-url', 'origin']);
+    if (existing.ok) {
+      if (existing.stdout !== remote) this.run(['remote', 'set-url', 'origin', remote]);
+    } else {
+      this.run(['remote', 'add', 'origin', remote]);
+    }
+  }
+
+  hasChanges(): boolean {
+    const r = this.run(['status', '--porcelain']);
+    return r.stdout.length > 0;
+  }
+
+  /** Stage everything and commit. Returns committed:false when the tree is clean. */
+  commit(message: string): CommitResult {
+    this.run(['add', '-A']);
+    if (!this.hasChanges() && !this.hasStaged()) {
+      return { committed: false, reason: 'nothing to commit' };
+    }
+    let r = this.run(['commit', '-m', message]);
+    if (!r.ok && /Please tell me who you are|user\.email|empty ident/i.test(r.stderr)) {
+      r = this.run([...FALLBACK_IDENTITY, 'commit', '-m', message]);
+    }
+    if (!r.ok) {
+      // "nothing to commit" race
+      if (/nothing to commit/i.test(r.stdout + r.stderr)) {
+        return { committed: false, reason: 'nothing to commit' };
+      }
+      return { committed: false, reason: r.stderr || r.stdout };
+    }
+    const sha = this.run(['rev-parse', 'HEAD']).stdout;
+    return { committed: true, sha };
+  }
+
+  private hasStaged(): boolean {
+    // diff --cached exits 1 when there are staged changes
+    const r = this.run(['diff', '--cached', '--quiet']);
+    return r.code === 1;
+  }
+
+  currentBranch(): string {
+    return this.run(['rev-parse', '--abbrev-ref', 'HEAD']).stdout || 'main';
+  }
+
+  /** Rebase local commits on top of the remote (clean by construction for host-keyed paths). */
+  pull(): GitResult {
+    return this.run(['pull', '--rebase', '--autostash', 'origin', this.currentBranch()]);
+  }
+
+  push(): GitResult {
+    return this.run(['push', '-u', 'origin', this.currentBranch()]);
+  }
+
+  /** Convenience: commit, and when a remote+autoPush are configured, pull --rebase then push. */
+  sync(message: string): { commit: CommitResult; pushed: boolean; pushError?: string } {
+    const commit = this.commit(message);
+    if (!commit.committed) return { commit, pushed: false };
+    if (!this.opts.remote || !this.opts.autoPush) return { commit, pushed: false };
+    // best-effort: integrate remote first, then push
+    this.pull();
+    const p = this.push();
+    return { commit, pushed: p.ok, ...(p.ok ? {} : { pushError: p.stderr }) };
+  }
+}

package/src/store/paths.ts

@@ -0,0 +1,45 @@
+import { join } from 'node:path';
+
+/**
+ * Store layout — sharded host/month/session so no directory holds too many
+ * entries and retention is a `rm -rf <old-month>`.
+ *
+ *   hosts/<host>/<YYYY-MM>/<session-uuid>/
+ *     session.json
+ *     turns/000007.json
+ *     telemetry/otel.jsonl
+ *     insights/labels.json
+ *     raw/<sha256>
+ */
+
+export function monthOf(ts: string | undefined): string {
+  if (ts) {
+    const m = /^(\d{4})-(\d{2})/.exec(ts);
+    if (m) return `${m[1]}-${m[2]}`;
+  }
+  return 'unknown';
+}
+
+export function sessionDir(storeDir: string, host: string, month: string, sessionId: string): string {
+  return join(storeDir, 'hosts', host, month, sessionId);
+}
+
+export function turnFile(dir: string, index: number): string {
+  return join(dir, 'turns', `${String(index).padStart(6, '0')}.json`);
+}
+
+export function envelopeFile(dir: string): string {
+  return join(dir, 'session.json');
+}
+
+export function insightsFile(dir: string): string {
+  return join(dir, 'insights', 'labels.json');
+}
+
+export function telemetryFile(dir: string): string {
+  return join(dir, 'telemetry', 'otel.jsonl');
+}
+
+export function rawBlobFile(dir: string, sha: string): string {
+  return join(dir, 'raw', sha);
+}

package/src/store/scan.ts

@@ -0,0 +1,39 @@
+import { readdirSync, type Dirent } from 'node:fs';
+import { join } from 'node:path';
+
+export interface SessionRef {
+  host: string;
+  month: string;
+  sessionId: string;
+  dir: string;
+}
+
+/** readdir(withFileTypes) that never throws and returns [] for a missing dir. */
+export function readEntries(dir: string): Dirent[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true }) as Dirent[];
+  } catch {
+    return [];
+  }
+}
+
+function subdirs(dir: string): string[] {
+  return readEntries(dir)
+    .filter((e) => e.isDirectory())
+    .map((e) => String(e.name));
+}
+
+/** Enumerate every session in the store: hosts/<host>/<month>/<sessionId>/. */
+export function listSessionDirs(storeDir: string, opts: { sinceMonth?: string } = {}): SessionRef[] {
+  const hostsRoot = join(storeDir, 'hosts');
+  const out: SessionRef[] = [];
+  for (const host of subdirs(hostsRoot)) {
+    for (const month of subdirs(join(hostsRoot, host))) {
+      if (opts.sinceMonth && month < opts.sinceMonth) continue;
+      for (const sessionId of subdirs(join(hostsRoot, host, month))) {
+        out.push({ host, month, sessionId, dir: join(hostsRoot, host, month, sessionId) });
+      }
+    }
+  }
+  return out;
+}