@unpolarize/code-sessions 0.1.0

package/src/daemon.ts

@@ -0,0 +1,216 @@
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { createServer, type Server, type Socket } from 'node:net';
+import { join } from 'node:path';
+import { CaptureEngine } from './capture';
+import type { CodeSessionsConfig } from './config';
+import { isSessionEndEvent, parseHookEvent, type HookAck, type HookEvent } from './ipc';
+import { StateStore } from './state';
+import { GitStore } from './store/git';
+import { readEntries } from './store/scan';
+
+export type SessionEndHook = (sessionId: string, sessionDir: string) => void | Promise<void>;
+
+export interface DaemonDeps {
+  capture?: CaptureEngine;
+  state?: StateStore;
+  git?: GitStore;
+  /** invoked on Stop/SubagentStop — the insights labeler hooks in here */
+  onSessionEnd?: SessionEndHook;
+}
+
+export interface DaemonStatus {
+  running: boolean;
+  socketPath: string;
+  storeDir: string;
+  events: number;
+  turns: number;
+  commits: number;
+  sessions: string[];
+}
+
+/** Find a Claude transcript file by session id under the projects dir (bounded scan). */
+export function findTranscript(projectsDir: string, sessionId: string, maxDepth = 3): string | undefined {
+  const target = `${sessionId}.jsonl`;
+  const walk = (dir: string, depth: number): string | undefined => {
+    if (depth > maxDepth || !existsSync(dir)) return undefined;
+    const entries = readEntries(dir);
+    for (const e of entries) {
+      if (e.isFile() && String(e.name) === target) return join(dir, String(e.name));
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        const found = walk(join(dir, String(e.name)), depth + 1);
+        if (found) return found;
+      }
+    }
+    return undefined;
+  };
+  return walk(projectsDir, 0);
+}
+
+/**
+ * The headless capture daemon. Listens on a unix socket for hook events,
+ * captures appended turns immediately, and batches git commits (flush on
+ * session-end, on a turn threshold, or after an interval).
+ */
+export class Daemon {
+  private server?: Server;
+  private readonly capture: CaptureEngine;
+  private readonly state: StateStore;
+  private readonly git?: GitStore;
+  private readonly onSessionEnd?: SessionEndHook;
+
+  private dirty = false;
+  private pendingTurns = 0;
+  private commitTimer?: ReturnType<typeof setTimeout>;
+  private running = false;
+  private readonly stats = { events: 0, turns: 0, commits: 0 };
+  private readonly sessions = new Set<string>();
+
+  constructor(
+    private readonly cfg: CodeSessionsConfig,
+    deps: DaemonDeps = {},
+  ) {
+    this.state = deps.state ?? new StateStore(cfg.statePath);
+    this.capture = deps.capture ?? new CaptureEngine(cfg, this.state);
+    if (cfg.git.autoCommit) {
+      this.git =
+        deps.git ??
+        new GitStore(cfg.storeDir, {
+          ...(cfg.git.remote ? { remote: cfg.git.remote } : {}),
+          autoPush: cfg.git.autoPush,
+        });
+    }
+    if (deps.onSessionEnd) this.onSessionEnd = deps.onSessionEnd;
+  }
+
+  async start(): Promise<void> {
+    mkdirSync(this.cfg.storeDir, { recursive: true });
+    mkdirSync(this.cfg.runtimeDir, { recursive: true });
+    this.git?.init();
+    if (existsSync(this.cfg.socketPath)) rmSync(this.cfg.socketPath);
+    await new Promise<void>((resolve, reject) => {
+      const server = createServer((sock) => this.onConnection(sock));
+      server.on('error', reject);
+      server.listen(this.cfg.socketPath, () => {
+        this.running = true;
+        resolve();
+      });
+      this.server = server;
+    });
+  }
+
+  private onConnection(sock: Socket): void {
+    let buf = '';
+    sock.on('data', async (chunk) => {
+      buf += chunk.toString('utf8');
+      let nl: number;
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!line.trim()) continue;
+        let ack: HookAck;
+        try {
+          const evt = parseHookEvent(JSON.parse(line));
+          ack = evt ? await this.handleEvent(evt) : { ok: false, error: 'invalid event' };
+        } catch {
+          ack = { ok: false, error: 'parse error' };
+        }
+        if (!sock.destroyed) sock.write(`${JSON.stringify(ack)}\n`);
+      }
+    });
+    sock.on('error', () => {
+      /* client hangup — ignore */
+    });
+  }
+
+  /** Process a single hook event: capture, then decide whether to flush a commit. */
+  async handleEvent(evt: HookEvent): Promise<HookAck> {
+    this.stats.events++;
+    const transcript =
+      evt.transcript_path && existsSync(evt.transcript_path)
+        ? evt.transcript_path
+        : findTranscript(this.cfg.claudeProjectsDir, evt.session_id);
+    if (!transcript) return { ok: false, error: 'transcript not found' };
+
+    const res = this.capture.captureSession(evt.session_id, transcript);
+    this.sessions.add(evt.session_id);
+    if (res.newTurns > 0 || res.writtenPaths.length > 0) {
+      this.dirty = true;
+      this.pendingTurns += res.newTurns;
+      this.stats.turns += res.newTurns;
+    }
+
+    const end = isSessionEndEvent(evt.event);
+    let flushed = false;
+    if (end && this.onSessionEnd) {
+      await this.onSessionEnd(evt.session_id, res.sessionDir);
+      this.dirty = true; // insights wrote derived artifacts
+    }
+    if (end || this.pendingTurns >= this.cfg.batch.maxTurns) {
+      flushed = this.flush(`capture ${evt.session_id}`);
+    } else {
+      this.scheduleFlush();
+    }
+    return { ok: true, newTurns: res.newTurns, flushed };
+  }
+
+  private scheduleFlush(): void {
+    if (this.commitTimer) return;
+    this.commitTimer = setTimeout(() => {
+      this.commitTimer = undefined;
+      this.flush('batch interval');
+    }, this.cfg.batch.maxIntervalMs);
+    this.commitTimer.unref?.();
+  }
+
+  /** Commit (and push when configured) all buffered store changes. Returns whether a commit landed. */
+  flush(message: string): boolean {
+    if (this.commitTimer) {
+      clearTimeout(this.commitTimer);
+      this.commitTimer = undefined;
+    }
+    if (!this.dirty || !this.git) {
+      this.dirty = false;
+      this.pendingTurns = 0;
+      return false;
+    }
+    const r = this.git.sync(message);
+    this.dirty = false;
+    this.pendingTurns = 0;
+    if (r.commit.committed) this.stats.commits++;
+    return r.commit.committed;
+  }
+
+  status(): DaemonStatus {
+    return {
+      running: this.running,
+      socketPath: this.cfg.socketPath,
+      storeDir: this.cfg.storeDir,
+      events: this.stats.events,
+      turns: this.stats.turns,
+      commits: this.stats.commits,
+      sessions: [...this.sessions],
+    };
+  }
+
+  async stop(): Promise<void> {
+    if (this.commitTimer) {
+      clearTimeout(this.commitTimer);
+      this.commitTimer = undefined;
+    }
+    this.flush('daemon shutdown');
+    if (this.server) {
+      await new Promise<void>((resolve) => this.server!.close(() => resolve()));
+      this.server = undefined;
+    }
+    if (existsSync(this.cfg.socketPath)) {
+      try {
+        rmSync(this.cfg.socketPath);
+      } catch {
+        /* ignore */
+      }
+    }
+    this.running = false;
+  }
+}

package/src/hooks/install.test.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { withTempDir } from '../test/tmp';
+import { DEFAULT_HOOK_EVENTS, installHooks, mergeHooks } from './install';
+
+describe('mergeHooks', () => {
+  it('adds our command to each event without clobbering existing hooks', () => {
+    const existing = {
+      model: 'opus',
+      hooks: { Stop: [{ matcher: '', hooks: [{ type: 'command' as const, command: 'other-tool' }] }] },
+    };
+    const { settings, added } = mergeHooks(existing, 'code-sessions hook');
+    expect(added).toEqual([...DEFAULT_HOOK_EVENTS]);
+    // preserves unrelated settings
+    expect((settings as { model: string }).model).toBe('opus');
+    // preserves the pre-existing Stop hook AND adds ours
+    const stop = settings.hooks!.Stop!;
+    expect(stop.some((g) => g.hooks.some((h) => h.command === 'other-tool'))).toBe(true);
+    expect(stop.some((g) => g.hooks.some((h) => h.command === 'code-sessions hook'))).toBe(true);
+  });
+
+  it('is idempotent (no duplicate command on re-run)', () => {
+    const first = mergeHooks({}, 'code-sessions hook');
+    const second = mergeHooks(first.settings, 'code-sessions hook');
+    expect(second.added).toEqual([]);
+    for (const event of DEFAULT_HOOK_EVENTS) {
+      const groups = second.settings.hooks![event]!;
+      const count = groups.filter((g) =>
+        g.hooks.some((h) => h.command === 'code-sessions hook'),
+      ).length;
+      expect(count).toBe(1);
+    }
+  });
+});
+
+describe('installHooks', () => {
+  it('writes a merged settings.json file', () => {
+    withTempDir((dir) => {
+      const settingsPath = join(dir, 'settings.json');
+      const res = installHooks(settingsPath, 'code-sessions hook');
+      expect(res.added.length).toBeGreaterThan(0);
+      const written = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      expect(written.hooks.PostToolUse[0].hooks[0].command).toBe('code-sessions hook');
+    });
+  });
+});

package/src/hooks/install.ts

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Install code-sessions hook shims into Claude Code settings.json. Each event
+ * runs `code-sessions hook`, which forwards the hook payload to the daemon
+ * socket. Existing hooks are preserved.
+ */
+
+export const DEFAULT_HOOK_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PostToolUse',
+  'Stop',
+  'SubagentStop',
+] as const;
+
+interface HookEntry {
+  type: 'command';
+  command: string;
+}
+interface HookGroup {
+  matcher?: string;
+  hooks: HookEntry[];
+}
+type SettingsHooks = Record<string, HookGroup[]>;
+interface Settings {
+  hooks?: SettingsHooks;
+  [k: string]: unknown;
+}
+
+function groupHasCommand(groups: HookGroup[], command: string): boolean {
+  return groups.some((g) => g.hooks?.some((h) => h.command === command));
+}
+
+/** Pure merge: add our command to each requested event if not already present. */
+export function mergeHooks(
+  settings: Settings,
+  command: string,
+  events: readonly string[] = DEFAULT_HOOK_EVENTS,
+): { settings: Settings; added: string[] } {
+  const next: Settings = { ...settings, hooks: { ...(settings.hooks ?? {}) } };
+  const hooks = next.hooks as SettingsHooks;
+  const added: string[] = [];
+  for (const event of events) {
+    const groups = hooks[event] ? [...hooks[event]!] : [];
+    if (groupHasCommand(groups, command)) {
+      hooks[event] = groups;
+      continue;
+    }
+    groups.push({ matcher: '', hooks: [{ type: 'command', command }] });
+    hooks[event] = groups;
+    added.push(event);
+  }
+  return { settings: next, added };
+}
+
+export interface InstallResult {
+  settingsPath: string;
+  command: string;
+  added: string[];
+}
+
+export function installHooks(
+  settingsPath: string,
+  command: string,
+  events: readonly string[] = DEFAULT_HOOK_EVENTS,
+): InstallResult {
+  let settings: Settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8')) as Settings;
+    } catch {
+      settings = {};
+    }
+  }
+  const { settings: merged, added } = mergeHooks(settings, command, events);
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
+  return { settingsPath, command, added };
+}

package/src/hooks/shim.test.ts

@@ -0,0 +1,57 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { Daemon } from '../daemon';
+import { makeConfig, withTempDirAsync } from '../test/tmp';
+import { handleHookInput } from './shim';
+
+const LINE =
+  '{"type":"user","sessionId":"sess-1","timestamp":"2026-06-20T08:00:00Z","message":{"role":"user","content":"hi"}}';
+
+describe('handleHookInput', () => {
+  it('is a silent no-op when the daemon is not running', async () => {
+    const ack = await handleHookInput('/no/such/daemon.sock', JSON.stringify({ event: 'Stop', session_id: 's' }));
+    expect(ack.ok).toBe(false);
+    expect(ack.error).toMatch(/not running/);
+  });
+
+  it('forwards a valid hook payload to a running daemon', async () => {
+    await withTempDirAsync(async (root) => {
+      const store = join(root, 'store');
+      const src = join(root, 'src');
+      mkdirSync(src, { recursive: true });
+      const transcript = join(src, 'sess-1.jsonl');
+      writeFileSync(transcript, `${LINE}\n`);
+      const socketPath = join(root, 'd.sock');
+      const d = new Daemon(makeConfig(store, { socketPath, batch: { maxTurns: 1 } }));
+      await d.start();
+      try {
+        const payload = JSON.stringify({
+          hook_event_name: 'PostToolUse',
+          session_id: 'sess-1',
+          transcript_path: transcript,
+        });
+        const ack = await handleHookInput(socketPath, payload);
+        expect(ack.ok).toBe(true);
+        expect(ack.newTurns).toBe(1);
+      } finally {
+        await d.stop();
+      }
+    });
+  });
+
+  it('rejects malformed JSON once a daemon socket exists', async () => {
+    await withTempDirAsync(async (root) => {
+      const socketPath = join(root, 'd.sock');
+      const d = new Daemon(makeConfig(join(root, 'store'), { socketPath }));
+      await d.start();
+      try {
+        const ack = await handleHookInput(socketPath, 'not json');
+        expect(ack.ok).toBe(false);
+        expect(ack.error).toMatch(/invalid hook json/);
+      } finally {
+        await d.stop();
+      }
+    });
+  });
+});

package/src/hooks/shim.ts

@@ -0,0 +1,26 @@
+import { existsSync } from 'node:fs';
+import { parseHookEvent, sendEvent, type HookAck } from '../ipc';
+
+/**
+ * Hook shim: forward a Claude Code hook payload (JSON on stdin) to the daemon
+ * socket. Must NEVER block or fail the agent — a missing/unreachable daemon is
+ * a silent no-op.
+ */
+export async function handleHookInput(socketPath: string, rawInput: string): Promise<HookAck> {
+  if (!existsSync(socketPath)) return { ok: false, error: 'daemon not running' };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawInput);
+  } catch {
+    return { ok: false, error: 'invalid hook json' };
+  }
+  const evt = parseHookEvent(parsed);
+  if (!evt) return { ok: false, error: 'unrecognized hook payload' };
+  return sendEvent(socketPath, evt);
+}
+
+export async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString('utf8');
+}

package/src/hygiene.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { parseTurn } from '@unpolarize/code-sessions-schema';
+import { applyHygiene, scrubSecrets, sha256 } from './hygiene';
+
+function turn(text: string): ReturnType<typeof parseTurn> {
+  return parseTurn({
+    schema: 'session-store/turn@1',
+    session_id: 's',
+    host: 'h',
+    agent: 'claude-code',
+    turn_index: 0,
+    ts: 't',
+    role: 'assistant',
+    text,
+    raw: { original: text },
+  });
+}
+
+describe('scrubSecrets', () => {
+  it('redacts common secret shapes', () => {
+    const samples = [
+      'AKIAIOSFODNN7EXAMPLE',
+      'ghp_1234567890abcdefghijklmnopqrstuvwxyzABCD',
+      'sk-ant-api03-abcdefghij_klmnopqrstuvwxyz1234567890',
+      'AIzaSyABCDEFGHIJKLMNOPQRSTUVWXYZ0123456',
+    ];
+    for (const s of samples) {
+      const { text, matches } = scrubSecrets(`token=${s} end`);
+      expect(text).not.toContain(s);
+      expect(text).toContain('[REDACTED:');
+      expect(matches.reduce((a, m) => a + m.count, 0)).toBeGreaterThan(0);
+    }
+  });
+
+  it('leaves clean text untouched', () => {
+    const { text, matches } = scrubSecrets('just a normal sentence about foo.ts');
+    expect(text).toBe('just a normal sentence about foo.ts');
+    expect(matches).toHaveLength(0);
+  });
+});
+
+describe('applyHygiene', () => {
+  it('scrubs and drops raw when a secret is found', () => {
+    const res = applyHygiene(turn('key ghp_1234567890abcdefghijklmnopqrstuvwxyzABCD here'), {
+      maxTurnBytes: 64 * 1024,
+      scrubSecrets: true,
+    });
+    expect(res.turn.scrubbed).toBe(true);
+    expect(res.turn.text).toContain('[REDACTED:github-token]');
+    expect(res.turn.raw).toBeUndefined();
+    expect(res.redactions.length).toBeGreaterThan(0);
+  });
+
+  it('externalizes oversized text to a content-addressed blob', () => {
+    const big = 'x'.repeat(2000);
+    const res = applyHygiene(turn(big), { maxTurnBytes: 512, scrubSecrets: true });
+    expect(res.blob).toBeDefined();
+    expect(res.blob!.sha).toBe(sha256(big));
+    expect(res.turn.raw_ref).toBe(res.blob!.sha);
+    expect(res.turn.text.length).toBeLessThan(big.length);
+    expect(res.turn.text).toContain('externalized');
+    expect(res.turn.raw).toBeUndefined();
+  });
+
+  it('is a no-op for small clean turns (keeps raw)', () => {
+    const res = applyHygiene(turn('hello world'), { maxTurnBytes: 64 * 1024, scrubSecrets: true });
+    expect(res.turn.scrubbed).toBe(false);
+    expect(res.blob).toBeUndefined();
+    expect(res.turn.raw).toEqual({ original: 'hello world' });
+  });
+
+  it('does not mutate the input turn', () => {
+    const t = turn('ghp_1234567890abcdefghijklmnopqrstuvwxyzABCD');
+    applyHygiene(t, { maxTurnBytes: 64 * 1024, scrubSecrets: true });
+    expect(t.text).toContain('ghp_');
+    expect(t.scrubbed).toBe(false);
+  });
+});

package/src/hygiene.ts

@@ -0,0 +1,107 @@
+import { createHash } from 'node:crypto';
+import type { Turn } from '@unpolarize/code-sessions-schema';
+
+/**
+ * Hygiene at the door (the Codex 1.95 GB lesson): secret-scrub, cap per-turn
+ * size, externalize giant tool outputs. Runs before any write.
+ */
+
+export interface SecretMatch {
+  kind: string;
+  count: number;
+}
+
+interface Pattern {
+  kind: string;
+  re: RegExp;
+}
+
+// Ordered, specific-first. All global so we can count + replace every hit.
+const PATTERNS: Pattern[] = [
+  { kind: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { kind: 'github-token', re: /\bgh[posru]_[A-Za-z0-9]{36,255}\b/g },
+  { kind: 'openai-key', re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g },
+  { kind: 'anthropic-key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+  { kind: 'slack-token', re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g },
+  { kind: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { kind: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g },
+  { kind: 'bearer-token', re: /\bBearer\s+[A-Za-z0-9._-]{20,}\b/g },
+  { kind: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+];
+
+/** Redact known secret shapes in text. Returns redacted text + per-kind counts. */
+export function scrubSecrets(text: string): { text: string; matches: SecretMatch[] } {
+  let out = text;
+  const matches: SecretMatch[] = [];
+  for (const { kind, re } of PATTERNS) {
+    let count = 0;
+    out = out.replace(re, () => {
+      count++;
+      return `[REDACTED:${kind}]`;
+    });
+    if (count > 0) matches.push({ kind, count });
+  }
+  return { text: out, matches };
+}
+
+export function sha256(content: string): string {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+export interface HygieneOptions {
+  maxTurnBytes: number;
+  scrubSecrets: boolean;
+}
+
+export interface HygieneResult {
+  turn: Turn;
+  /** present when the turn's text was externalized: persist content at raw/<sha> */
+  blob?: { sha: string; content: string };
+  redactions: SecretMatch[];
+}
+
+const PREVIEW_CHARS = 280;
+
+/**
+ * Apply hygiene to a turn (pure: returns a new turn, never mutates input).
+ * - scrub secrets in text (and drop verbatim `raw` if anything was redacted, so
+ *   the unredacted secret is not preserved);
+ * - externalize oversized text to a content-addressed blob, leaving a preview.
+ */
+export function applyHygiene(turn: Turn, opts: HygieneOptions): HygieneResult {
+  let text = turn.text;
+  let scrubbed = turn.scrubbed;
+  let raw = turn.raw;
+  const redactions: SecretMatch[] = [];
+
+  if (opts.scrubSecrets) {
+    const res = scrubSecrets(text);
+    if (res.matches.length > 0) {
+      text = res.text;
+      scrubbed = true;
+      raw = undefined; // never retain the unredacted copy
+      redactions.push(...res.matches);
+    }
+  }
+
+  let blob: { sha: string; content: string } | undefined;
+  let rawRef = turn.raw_ref;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > opts.maxTurnBytes) {
+    const sha = sha256(text);
+    blob = { sha, content: text };
+    rawRef = sha;
+    raw = undefined; // the big content lives in the blob, not duplicated in raw
+    const preview = text.slice(0, PREVIEW_CHARS);
+    text = `${preview}\n…[externalized ${bytes}B → raw/${sha}]`;
+  }
+
+  const next: Turn = {
+    ...turn,
+    text,
+    scrubbed,
+    raw_ref: rawRef,
+    ...(raw === undefined ? { raw: undefined } : { raw }),
+  };
+  return { turn: next, ...(blob ? { blob } : {}), redactions };
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+// Public library API for the code-sessions agent (the CLI lives in cli.ts).
+export * from './config';
+export * from './capture';
+export * from './state';
+export * from './tail';
+export * from './hygiene';
+export * from './pricing';
+export * from './ipc';
+export * from './daemon';
+export * from './commands';
+export { parseFlags, overridesFromFlags } from './cliargs';
+export * from './store/paths';
+export * from './store/writer';
+export * from './store/git';
+export * from './store/scan';
+export * from './insights/index';
+export * from './telemetry/index';
+export * from './adapters/index';
+export * from './index_store/index';
+export * from './hooks/install';
+export * from './hooks/shim';