context-mode 0.9.21 → 1.0.0

package/build/session/db.d.ts

@@ -0,0 +1,110 @@
+/**
+ * SessionDB — Persistent per-project SQLite database for session events.
+ *
+ * Stores raw events captured by hooks during a Claude Code session,
+ * session metadata, and resume snapshots. Extends SQLiteBase from
+ * the shared package.
+ */
+import { SQLiteBase } from "../db-base.js";
+import type { SessionEvent } from "../types.js";
+/** A stored event row from the session_events table. */
+export interface StoredEvent {
+    id: number;
+    session_id: string;
+    type: string;
+    category: string;
+    priority: number;
+    data: string;
+    source_hook: string;
+    created_at: string;
+    data_hash: string;
+}
+/** Session metadata row from the session_meta table. */
+export interface SessionMeta {
+    session_id: string;
+    project_dir: string;
+    started_at: string;
+    last_event_at: string | null;
+    event_count: number;
+    compact_count: number;
+}
+/** Resume snapshot row from the session_resume table. */
+export interface ResumeRow {
+    snapshot: string;
+    event_count: number;
+    consumed: number;
+}
+export declare class SessionDB extends SQLiteBase {
+    /**
+     * Cached prepared statements. Stored in a Map to avoid the JS private-field
+     * inheritance issue where `#field` declarations in a subclass are not
+     * accessible during base-class constructor calls.
+     *
+     * `declare` ensures TypeScript does NOT emit a field initializer at runtime.
+     * Without `declare`, even `stmts!: Map<...>` emits `this.stmts = undefined`
+     * after super() returns, wiping what prepareStatements() stored. The Map
+     * is created inside prepareStatements() instead.
+     */
+    private stmts;
+    constructor(opts?: {
+        dbPath?: string;
+    });
+    /** Shorthand to retrieve a cached statement. */
+    private stmt;
+    protected initSchema(): void;
+    protected prepareStatements(): void;
+    /**
+     * Insert a session event with deduplication and FIFO eviction.
+     *
+     * Deduplication: skips if the same type + data_hash appears in the
+     * last DEDUP_WINDOW events for this session.
+     *
+     * Eviction: if session exceeds MAX_EVENTS_PER_SESSION, evicts the
+     * lowest-priority (then oldest) event.
+     */
+    insertEvent(sessionId: string, event: SessionEvent, sourceHook?: string): void;
+    /**
+     * Retrieve events for a session with optional filtering.
+     */
+    getEvents(sessionId: string, opts?: {
+        type?: string;
+        minPriority?: number;
+        limit?: number;
+    }): StoredEvent[];
+    /**
+     * Get the total event count for a session.
+     */
+    getEventCount(sessionId: string): number;
+    /**
+     * Ensure a session metadata entry exists. Idempotent (INSERT OR IGNORE).
+     */
+    ensureSession(sessionId: string, projectDir: string): void;
+    /**
+     * Get session statistics/metadata.
+     */
+    getSessionStats(sessionId: string): SessionMeta | null;
+    /**
+     * Increment the compact_count for a session (tracks snapshot rebuilds).
+     */
+    incrementCompactCount(sessionId: string): void;
+    /**
+     * Upsert a resume snapshot for a session. Resets consumed flag on update.
+     */
+    upsertResume(sessionId: string, snapshot: string, eventCount?: number): void;
+    /**
+     * Retrieve the resume snapshot for a session.
+     */
+    getResume(sessionId: string): ResumeRow | null;
+    /**
+     * Mark the resume snapshot as consumed (already injected into conversation).
+     */
+    markResumeConsumed(sessionId: string): void;
+    /**
+     * Delete all data for a session (events, meta, resume).
+     */
+    deleteSession(sessionId: string): void;
+    /**
+     * Remove sessions older than maxAgeDays. Returns the count of deleted sessions.
+     */
+    cleanupOldSessions(maxAgeDays?: number): number;
+}

package/build/session/db.js

@@ -0,0 +1,285 @@
+/**
+ * SessionDB — Persistent per-project SQLite database for session events.
+ *
+ * Stores raw events captured by hooks during a Claude Code session,
+ * session metadata, and resume snapshots. Extends SQLiteBase from
+ * the shared package.
+ */
+import { SQLiteBase, defaultDBPath } from "../db-base.js";
+import { createHash } from "node:crypto";
+// ─────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────
+/** Maximum events per session before FIFO eviction kicks in. */
+const MAX_EVENTS_PER_SESSION = 1000;
+/** Number of recent events to check for deduplication. */
+const DEDUP_WINDOW = 5;
+// ─────────────────────────────────────────────────────────
+// Statement keys (typed enum to avoid string typos)
+// ─────────────────────────────────────────────────────────
+const S = {
+    insertEvent: "insertEvent",
+    getEvents: "getEvents",
+    getEventsByType: "getEventsByType",
+    getEventsByPriority: "getEventsByPriority",
+    getEventsByTypeAndPriority: "getEventsByTypeAndPriority",
+    getEventCount: "getEventCount",
+    checkDuplicate: "checkDuplicate",
+    evictLowestPriority: "evictLowestPriority",
+    updateMetaLastEvent: "updateMetaLastEvent",
+    ensureSession: "ensureSession",
+    getSessionStats: "getSessionStats",
+    incrementCompactCount: "incrementCompactCount",
+    upsertResume: "upsertResume",
+    getResume: "getResume",
+    markResumeConsumed: "markResumeConsumed",
+    deleteEvents: "deleteEvents",
+    deleteMeta: "deleteMeta",
+    deleteResume: "deleteResume",
+    getOldSessions: "getOldSessions",
+};
+// ─────────────────────────────────────────────────────────
+// SessionDB
+// ─────────────────────────────────────────────────────────
+export class SessionDB extends SQLiteBase {
+    constructor(opts) {
+        super(opts?.dbPath ?? defaultDBPath("session"));
+    }
+    /** Shorthand to retrieve a cached statement. */
+    stmt(key) {
+        return this.stmts.get(key);
+    }
+    // ── Schema ──
+    initSchema() {
+        // ── Migration: fix data_hash generated column from older schema ──
+        // Old schema had data_hash as GENERATED ALWAYS AS — new schema uses explicit INSERT.
+        // Detect and recreate table if needed (session data is ephemeral, safe to drop).
+        try {
+            const colInfo = this.db.pragma("table_xinfo(session_events)");
+            const hashCol = colInfo.find((c) => c.name === "data_hash");
+            if (hashCol && hashCol.hidden !== 0) {
+                // hidden != 0 means generated column — must recreate
+                this.db.exec("DROP TABLE session_events");
+            }
+        }
+        catch { /* table doesn't exist yet — fine */ }
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS session_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        category TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 2,
+        data TEXT NOT NULL,
+        source_hook TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        data_hash TEXT NOT NULL DEFAULT ''
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_session_events_session ON session_events(session_id);
+      CREATE INDEX IF NOT EXISTS idx_session_events_type ON session_events(session_id, type);
+      CREATE INDEX IF NOT EXISTS idx_session_events_priority ON session_events(session_id, priority);
+
+      CREATE TABLE IF NOT EXISTS session_meta (
+        session_id TEXT PRIMARY KEY,
+        project_dir TEXT NOT NULL,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_event_at TEXT,
+        event_count INTEGER NOT NULL DEFAULT 0,
+        compact_count INTEGER NOT NULL DEFAULT 0
+      );
+
+      CREATE TABLE IF NOT EXISTS session_resume (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL UNIQUE,
+        snapshot TEXT NOT NULL,
+        event_count INTEGER NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        consumed INTEGER NOT NULL DEFAULT 0
+      );
+    `);
+    }
+    prepareStatements() {
+        this.stmts = new Map();
+        const p = (key, sql) => {
+            this.stmts.set(key, this.db.prepare(sql));
+        };
+        // ── Events ──
+        p(S.insertEvent, `INSERT INTO session_events (session_id, type, category, priority, data, source_hook, data_hash)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        p(S.getEvents, `SELECT id, session_id, type, category, priority, data, source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventsByType, `SELECT id, session_id, type, category, priority, data, source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? AND type = ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventsByPriority, `SELECT id, session_id, type, category, priority, data, source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? AND priority >= ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventsByTypeAndPriority, `SELECT id, session_id, type, category, priority, data, source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? AND type = ? AND priority >= ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventCount, `SELECT COUNT(*) AS cnt FROM session_events WHERE session_id = ?`);
+        p(S.checkDuplicate, `SELECT 1 FROM (
+         SELECT type, data_hash FROM session_events
+         WHERE session_id = ? ORDER BY id DESC LIMIT ?
+       ) AS recent
+       WHERE recent.type = ? AND recent.data_hash = ?
+       LIMIT 1`);
+        p(S.evictLowestPriority, `DELETE FROM session_events WHERE id = (
+         SELECT id FROM session_events WHERE session_id = ?
+         ORDER BY priority ASC, id ASC LIMIT 1
+       )`);
+        p(S.updateMetaLastEvent, `UPDATE session_meta
+       SET last_event_at = datetime('now'), event_count = event_count + 1
+       WHERE session_id = ?`);
+        // ── Meta ──
+        p(S.ensureSession, `INSERT OR IGNORE INTO session_meta (session_id, project_dir) VALUES (?, ?)`);
+        p(S.getSessionStats, `SELECT session_id, project_dir, started_at, last_event_at, event_count, compact_count
+       FROM session_meta WHERE session_id = ?`);
+        p(S.incrementCompactCount, `UPDATE session_meta SET compact_count = compact_count + 1 WHERE session_id = ?`);
+        // ── Resume ──
+        p(S.upsertResume, `INSERT INTO session_resume (session_id, snapshot, event_count)
+       VALUES (?, ?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET
+         snapshot = excluded.snapshot,
+         event_count = excluded.event_count,
+         created_at = datetime('now'),
+         consumed = 0`);
+        p(S.getResume, `SELECT snapshot, event_count, consumed FROM session_resume WHERE session_id = ?`);
+        p(S.markResumeConsumed, `UPDATE session_resume SET consumed = 1 WHERE session_id = ?`);
+        // ── Delete ──
+        p(S.deleteEvents, `DELETE FROM session_events WHERE session_id = ?`);
+        p(S.deleteMeta, `DELETE FROM session_meta WHERE session_id = ?`);
+        p(S.deleteResume, `DELETE FROM session_resume WHERE session_id = ?`);
+        // ── Cleanup ──
+        p(S.getOldSessions, `SELECT session_id FROM session_meta WHERE started_at < datetime('now', ? || ' days')`);
+    }
+    // ═══════════════════════════════════════════
+    // Events
+    // ═══════════════════════════════════════════
+    /**
+     * Insert a session event with deduplication and FIFO eviction.
+     *
+     * Deduplication: skips if the same type + data_hash appears in the
+     * last DEDUP_WINDOW events for this session.
+     *
+     * Eviction: if session exceeds MAX_EVENTS_PER_SESSION, evicts the
+     * lowest-priority (then oldest) event.
+     */
+    insertEvent(sessionId, event, sourceHook = "PostToolUse") {
+        // SHA256-based dedup hash (first 16 hex chars = 8 bytes of entropy)
+        const dataHash = createHash("sha256")
+            .update(event.data)
+            .digest("hex")
+            .slice(0, 16)
+            .toUpperCase();
+        // Atomic: dedup check + eviction + insert in a single transaction
+        // to prevent race conditions from concurrent hook calls.
+        const transaction = this.db.transaction(() => {
+            // Deduplication check: same type + data_hash in last N events
+            const dup = this.stmt(S.checkDuplicate).get(sessionId, DEDUP_WINDOW, event.type, dataHash);
+            if (dup)
+                return;
+            // Enforce max events with FIFO eviction of lowest priority
+            const countRow = this.stmt(S.getEventCount).get(sessionId);
+            if (countRow.cnt >= MAX_EVENTS_PER_SESSION) {
+                this.stmt(S.evictLowestPriority).run(sessionId);
+            }
+            // Insert the event
+            this.stmt(S.insertEvent).run(sessionId, event.type, event.category, event.priority, event.data, sourceHook, dataHash);
+            // Update meta if session exists
+            this.stmt(S.updateMetaLastEvent).run(sessionId);
+        });
+        transaction();
+    }
+    /**
+     * Retrieve events for a session with optional filtering.
+     */
+    getEvents(sessionId, opts) {
+        const limit = opts?.limit ?? 1000;
+        const type = opts?.type;
+        const minPriority = opts?.minPriority;
+        if (type && minPriority !== undefined) {
+            return this.stmt(S.getEventsByTypeAndPriority).all(sessionId, type, minPriority, limit);
+        }
+        if (type) {
+            return this.stmt(S.getEventsByType).all(sessionId, type, limit);
+        }
+        if (minPriority !== undefined) {
+            return this.stmt(S.getEventsByPriority).all(sessionId, minPriority, limit);
+        }
+        return this.stmt(S.getEvents).all(sessionId, limit);
+    }
+    /**
+     * Get the total event count for a session.
+     */
+    getEventCount(sessionId) {
+        const row = this.stmt(S.getEventCount).get(sessionId);
+        return row.cnt;
+    }
+    // ═══════════════════════════════════════════
+    // Meta
+    // ═══════════════════════════════════════════
+    /**
+     * Ensure a session metadata entry exists. Idempotent (INSERT OR IGNORE).
+     */
+    ensureSession(sessionId, projectDir) {
+        this.stmt(S.ensureSession).run(sessionId, projectDir);
+    }
+    /**
+     * Get session statistics/metadata.
+     */
+    getSessionStats(sessionId) {
+        const row = this.stmt(S.getSessionStats).get(sessionId);
+        return row ?? null;
+    }
+    /**
+     * Increment the compact_count for a session (tracks snapshot rebuilds).
+     */
+    incrementCompactCount(sessionId) {
+        this.stmt(S.incrementCompactCount).run(sessionId);
+    }
+    // ═══════════════════════════════════════════
+    // Resume
+    // ═══════════════════════════════════════════
+    /**
+     * Upsert a resume snapshot for a session. Resets consumed flag on update.
+     */
+    upsertResume(sessionId, snapshot, eventCount) {
+        this.stmt(S.upsertResume).run(sessionId, snapshot, eventCount ?? 0);
+    }
+    /**
+     * Retrieve the resume snapshot for a session.
+     */
+    getResume(sessionId) {
+        const row = this.stmt(S.getResume).get(sessionId);
+        return row ?? null;
+    }
+    /**
+     * Mark the resume snapshot as consumed (already injected into conversation).
+     */
+    markResumeConsumed(sessionId) {
+        this.stmt(S.markResumeConsumed).run(sessionId);
+    }
+    // ═══════════════════════════════════════════
+    // Lifecycle
+    // ═══════════════════════════════════════════
+    /**
+     * Delete all data for a session (events, meta, resume).
+     */
+    deleteSession(sessionId) {
+        this.db.transaction(() => {
+            this.stmt(S.deleteEvents).run(sessionId);
+            this.stmt(S.deleteResume).run(sessionId);
+            this.stmt(S.deleteMeta).run(sessionId);
+        })();
+    }
+    /**
+     * Remove sessions older than maxAgeDays. Returns the count of deleted sessions.
+     */
+    cleanupOldSessions(maxAgeDays = 7) {
+        const negDays = `-${maxAgeDays}`;
+        const oldSessions = this.stmt(S.getOldSessions).all(negDays);
+        for (const { session_id } of oldSessions) {
+            this.deleteSession(session_id);
+        }
+        return oldSessions.length;
+    }
+}

package/build/session/extract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Session event extraction — pure functions, zero side effects.
+ * Extracts structured events from Claude Code tool calls and user messages.
+ *
+ * All 13 event categories as specified in PRD Section 3.
+ */
+export interface SessionEvent {
+    /** e.g. "file_read", "file_write", "cwd", "error_tool", "git", "task",
+     *  "decision", "rule", "env", "role", "skill", "subagent", "data", "intent" */
+    type: string;
+    /** e.g. "file", "cwd", "error", "git", "task", "decision",
+     *  "rule", "env", "role", "skill", "subagent", "data", "intent" */
+    category: string;
+    /** Extracted payload, truncated to 300 chars max */
+    data: string;
+    /** 1=critical (rules, files, tasks) … 5=low */
+    priority: number;
+}
+export interface ToolCall {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolResponse?: string;
+    isError?: boolean;
+}
+/**
+ * Hook input shape as received from Claude Code PostToolUse hook stdin.
+ * Uses snake_case to match the raw hook JSON.
+ */
+export interface HookInput {
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    tool_response?: string;
+    /** Optional structured output from the tool (may carry isError) */
+    tool_output?: {
+        isError?: boolean;
+    };
+}
+/**
+ * Extract session events from a PostToolUse hook input.
+ *
+ * Accepts the raw hook JSON shape (snake_case keys) as received from stdin.
+ * Returns an array of zero or more SessionEvents. Never throws.
+ */
+export declare function extractEvents(input: HookInput): SessionEvent[];
+/**
+ * Extract session events from a UserPromptSubmit hook input (user message text).
+ *
+ * Handles: decision, role, intent, data categories.
+ * Returns an array of zero or more SessionEvents. Never throws.
+ */
+export declare function extractUserEvents(message: string): SessionEvent[];