hippo-memory 1.60.0 → 1.62.0

package/dist/{graph.js → graph/write.js}

@@ -17,75 +17,17 @@
  * enqueue-hook + E3.1 entity extraction will call. No operator surface (CLI/HTTP/SDK)
  * until E3.2 multi-hop recall.
  */
-import { openHippoDb, closeHippoDb } from './db.js';
-import { assertTenantId } from './tenant.js';
-import { log } from './log.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { assertTenantId } from '../tenant.js';
+import { log } from '../log.js';
+import { GRAPH_ENTITY_TYPES, GRAPH_RELATION_TYPES, MAX_ENTITY_NAME_LEN } from './types.js';
+import { rowToEntity, rowToRelation, rowToQueueItem, ENTITY_COLS, RELATION_COLS, QUEUE_COLS } from './rows.js';
 const SOURCE_OBJECT_TABLE = {
     decision: 'decisions',
     policy: 'policies',
     customer: 'customer_notes',
     project: 'project_briefs',
 };
-export const GRAPH_ENTITY_TYPES = new Set([
-    'person', 'project', 'customer', 'system', 'policy', 'decision',
-]);
-export const GRAPH_RELATION_TYPES = new Set([
-    'owns', 'supersedes', 'depends-on', 'blocked-by', 'references',
-]);
-export const VALID_QUEUE_STATES = new Set([
-    'pending', 'processed', 'skipped',
-]);
-export const MAX_ENTITY_NAME_LEN = 512;
-function rowToEntity(row) {
-    // SAFETY: entity_type/source_kind/source_object_type are DB CHECK-constrained
-    // (see db.ts CREATE TABLE entities) to exactly the EntityType/SourceKind/
-    // SourceObjectType enum values, so the row's column values match those types.
-    return {
-        id: row.id,
-        tenantId: row.tenant_id,
-        entityType: row.entity_type,
-        name: row.name,
-        memoryId: row.memory_id,
-        sourceKind: row.source_kind,
-        sourceObjectType: row.source_object_type === null ? undefined : row.source_object_type,
-        sourceObjectId: row.source_object_id === null ? undefined : row.source_object_id,
-        createdAt: row.created_at,
-    };
-}
-function rowToRelation(row) {
-    // SAFETY: rel_type/source_kind/source_object_type are DB CHECK-constrained
-    // (see db.ts CREATE TABLE relations) to exactly the RelationType/SourceKind/
-    // SourceObjectType enum values, so the row's column values match those types.
-    return {
-        id: row.id,
-        tenantId: row.tenant_id,
-        fromEntityId: row.from_entity_id,
-        toEntityId: row.to_entity_id,
-        relType: row.rel_type,
-        memoryId: row.memory_id,
-        sourceKind: row.source_kind,
-        sourceObjectType: row.source_object_type === null ? undefined : row.source_object_type,
-        sourceObjectId: row.source_object_id === null ? undefined : row.source_object_id,
-        createdAt: row.created_at,
-    };
-}
-function rowToQueueItem(row) {
-    // SAFETY: kind/status are DB CHECK-constrained (see db.ts CREATE TABLE
-    // graph_extraction_queue) to exactly the SourceKind/GraphQueueStatus enum
-    // values, so the row's column values match those types.
-    return {
-        id: row.id,
-        tenantId: row.tenant_id,
-        memoryId: row.memory_id,
-        kind: row.kind,
-        status: row.status,
-        enqueuedAt: row.enqueued_at,
-        processedAt: row.processed_at,
-    };
-}
-const ENTITY_COLS = `id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at`;
-const RELATION_COLS = `id, tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at`;
-const QUEUE_COLS = `id, tenant_id, memory_id, kind, status, enqueued_at, processed_at`;
 function resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, label) {
     let memKind = null;
     let effectiveMemoryId = memoryId;
@@ -227,274 +169,6 @@ export function insertRelation(hippoRoot, tenantId, opts, txDb) {
             closeHippoDb(ownDb);
     }
 }
-export function loadEntityById(hippoRoot, tenantId, id) {
-    assertTenantId('loadEntityById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
-        const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToEntity(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Entities with an exact `name` (read), bounded by `limit` in SQL with a
- *  deterministic order. Lets the graph-view focus query find the `--entity NAME`
- *  entity DIRECTLY (not from a globally-capped list) WITHOUT materializing every
- *  same-name row when a name maps to many entities. */
-export function loadEntitiesByName(hippoRoot, tenantId, name, opts = {}, txDb) {
-    assertTenantId('loadEntitiesByName', tenantId);
-    const limit = opts.limit ?? 100;
-    if (!Number.isInteger(limit) || limit < 0) {
-        throw new Error(`loadEntitiesByName: limit must be a non-negative integer; got ${limit}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-        const rows = db.prepare(`
-      SELECT ${ENTITY_COLS} FROM entities WHERE tenant_id = ? AND name = ?
-      ORDER BY id ASC LIMIT ?
-    `).all(tenantId, name, limit);
-        return rows.map(rowToEntity);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-export function loadEntities(hippoRoot, tenantId, opts = {}, txDb) {
-    assertTenantId('loadEntities', tenantId);
-    const limit = opts.limit ?? 100;
-    if (opts.entityType && !GRAPH_ENTITY_TYPES.has(opts.entityType)) {
-        throw new Error(`loadEntities: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.entityType) {
-            clauses.push('entity_type = ?');
-            params.push(opts.entityType);
-        }
-        params.push(limit);
-        // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-        const rows = db.prepare(`
-      SELECT ${ENTITY_COLS} FROM entities
-      WHERE ${clauses.join(' AND ')}
-      ORDER BY created_at DESC, id DESC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToEntity);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-export function loadRelations(hippoRoot, tenantId, opts = {}, txDb) {
-    assertTenantId('loadRelations', tenantId);
-    const limit = opts.limit ?? 100;
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.fromEntityId !== undefined) {
-            clauses.push('from_entity_id = ?');
-            params.push(opts.fromEntityId);
-        }
-        params.push(limit);
-        // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
-        const rows = db.prepare(`
-      SELECT ${RELATION_COLS} FROM relations
-      WHERE ${clauses.join(' AND ')}
-      ORDER BY created_at DESC, id DESC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToRelation);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-// ---------------------------------------------------------------------------
-// E3.2 multi-hop recall read helpers (SELECT-only; the check-graph-writes lint
-// permits these here and in the read-only consumer src/graph-recall.ts).
-// ---------------------------------------------------------------------------
-/** Chunk size for IN-list queries: well under SQLite's 999-bound-variable default
- *  (leaves headroom for the tenant_id param + the doubled list in neighbour lookups). */
-const IN_LIST_CHUNK = 400;
-/**
- * Map consolidated source memory ids -> their graph entities. The SEED step of E3.2
- * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
- * scoped, read-only; chunks the IN-list under the SQLite variable cap.
- */
-export function loadEntitiesByMemoryId(hippoRoot, tenantId, memoryIds) {
-    assertTenantId('loadEntitiesByMemoryId', tenantId);
-    if (memoryIds.length === 0)
-        return [];
-    const db = openHippoDb(hippoRoot);
-    try {
-        const out = [];
-        for (let i = 0; i < memoryIds.length; i += IN_LIST_CHUNK) {
-            const slice = memoryIds.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
-            // T2: no ORDER BY meant chunk-local scan order decided ties; id ASC
-            // makes it deterministic (entities.id is an autoincrement integer PK).
-            // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-            const rows = db.prepare(`
-        SELECT ${ENTITY_COLS} FROM entities
-        WHERE tenant_id = ? AND memory_id IN (${ph})
-        ORDER BY id ASC
-      `).all(tenantId, ...slice);
-            out.push(...rows.map(rowToEntity));
-        }
-        return out;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Load entities by their primary ids. Resolves the entity rows reached during the BFS
- * (whose `memory_id` maps back to a recall result). Tenant-scoped, read-only.
- */
-export function loadEntitiesByIds(hippoRoot, tenantId, ids, txDb) {
-    assertTenantId('loadEntitiesByIds', tenantId);
-    if (ids.length === 0)
-        return [];
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const out = [];
-        for (let i = 0; i < ids.length; i += IN_LIST_CHUNK) {
-            const slice = ids.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
-            // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-            const rows = db.prepare(`
-        SELECT ${ENTITY_COLS} FROM entities
-        WHERE tenant_id = ? AND id IN (${ph})
-      `).all(tenantId, ...slice);
-            out.push(...rows.map(rowToEntity));
-        }
-        return out;
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-/**
- * All relations touching ANY of `entityIds` in EITHER direction (from OR to) — the
- * per-hop neighbour query for E3.2 multi-hop traversal. ONE query for the whole frontier
- * (not one per node): this is the bidirectional read `loadRelations` (from-only) lacks,
- * and avoids an N+1 across BFS frontier nodes. `limit` caps rows for the frontier and
- * must be a non-negative integer (the raw `LIMIT ?` rejects a fractional value).
- */
-export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
-    assertTenantId('loadNeighborRelations', tenantId);
-    if (entityIds.length === 0)
-        return [];
-    const limit = opts.limit ?? 1000;
-    if (!Number.isInteger(limit) || limit < 0) {
-        throw new Error(`loadNeighborRelations: limit must be a non-negative integer; got ${limit}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        // `limit` is applied PER CHUNK; a frontier spanning >IN_LIST_CHUNK ids could return
-        // up to limit*chunks rows before the by-id dedup below. Harmless for E3.2 (the
-        // frontier is bounded by maxNeighbors <= 200 << IN_LIST_CHUNK, so a single chunk,
-        // and the BFS re-enforces the per-hop fanout cap), but note the semantics if a
-        // tighter total cap is ever needed.
-        const byId = new Map();
-        for (let i = 0; i < entityIds.length; i += IN_LIST_CHUNK) {
-            const slice = entityIds.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
-            // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
-            const rows = db.prepare(`
-        SELECT ${RELATION_COLS} FROM relations
-        WHERE tenant_id = ? AND (from_entity_id IN (${ph}) OR to_entity_id IN (${ph}))
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, ...slice, ...slice, limit);
-            for (const r of rows)
-                byId.set(r.id, rowToRelation(r));
-        }
-        return Array.from(byId.values());
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-/**
- * Relations with BOTH endpoints in `entityIds` (edges AMONG the set, not merely
- * touching it). Read. Used by the graph-view focus subgraph so the displayed
- * edges are exactly the intra-union edges: the `LIMIT` only caps genuinely-many
- * intra-union edges — no out-of-union row can evict a valid in-set edge. The
- * caller bounds `entityIds` (<= the view limit), so a single query is safe.
- */
-export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
-    assertTenantId('loadRelationsAmong', tenantId);
-    if (entityIds.length === 0)
-        return [];
-    const limit = opts.limit ?? 1000;
-    if (!Number.isInteger(limit) || limit < 0) {
-        throw new Error(`loadRelationsAmong: limit must be a non-negative integer; got ${limit}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const ph = entityIds.map(() => '?').join(',');
-        // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
-        const rows = db.prepare(`
-      SELECT ${RELATION_COLS} FROM relations
-      WHERE tenant_id = ? AND from_entity_id IN (${ph}) AND to_entity_id IN (${ph})
-      ORDER BY created_at DESC, id DESC
-      LIMIT ?
-    `).all(tenantId, ...entityIds, ...entityIds, limit);
-        return rows.map(rowToRelation);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-/**
- * Run `fn` inside ONE read transaction (a single WAL snapshot) so every graph read
- * it performs — pass the supplied `txDb` to the `load*` functions — sees a consistent
- * view, even if a `graph extract` / sleep-drain rebuild commits concurrently between
- * reads (the rebuild clears + reinserts entities, so separate reads could otherwise
- * mix old entity ids with new relation ids). Reads only; the connection is opened
- * once and closed after.
- */
-export function withGraphReadSnapshot(hippoRoot, fn) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN');
-        try {
-            const out = fn(db);
-            db.exec('COMMIT');
-            return out;
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* ignore */ }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 // ---------------------------------------------------------------------------
 // Extraction queue (the interface the deferred sleep enqueue-hook + E3.1 will use)
 // ---------------------------------------------------------------------------
@@ -526,34 +200,6 @@ export function enqueueExtraction(hippoRoot, tenantId, memoryId) {
         closeHippoDb(db);
     }
 }
-export function loadExtractionQueue(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadExtractionQueue', tenantId);
-    const limit = opts.limit ?? 100;
-    if (opts.status && !VALID_QUEUE_STATES.has(opts.status)) {
-        throw new Error(`loadExtractionQueue: status must be one of ${Array.from(VALID_QUEUE_STATES).join('|')}; got ${opts.status}`);
-    }
-    const db = openHippoDb(hippoRoot);
-    try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.status) {
-            clauses.push('status = ?');
-            params.push(opts.status);
-        }
-        params.push(limit);
-        // SAFETY: rows' shape matches the columns named in QUEUE_COLS above.
-        const rows = db.prepare(`
-      SELECT ${QUEUE_COLS} FROM graph_extraction_queue
-      WHERE ${clauses.join(' AND ')}
-      ORDER BY enqueued_at ASC, id ASC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToQueueItem);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 /**
  * Mark a queue item terminal (processed | skipped). Only `status`/`processed_at`
  * change, so the consolidated-source guard trigger (which fires on
@@ -708,30 +354,6 @@ export function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectTy
         log.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-/**
- * The dirty tenants awaiting graph re-extraction, each with the MAX pending
- * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
- * graph, then marks only items at or below the watermark processed, so items
- * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
- * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
- */
-export function loadPendingExtractionTenants(hippoRoot) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches the two aliased columns (tenant_id, max_id)
-        // named in the SELECT above.
-        const rows = db.prepare(`
-      SELECT tenant_id AS tenant_id, MAX(id) AS max_id
-      FROM graph_extraction_queue
-      WHERE status = 'pending'
-      GROUP BY tenant_id
-    `).all();
-        return rows.map((r) => ({ tenantId: r.tenant_id, maxPendingId: Number(r.max_id) }));
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 /**
  * Mark every pending queue item for a tenant with `id <= maxId` processed, in
  * one UPDATE. Status/processed_at only, so the consolidated-source guard trigger
@@ -754,4 +376,4 @@ export function markPendingProcessedUpTo(hippoRoot, tenantId, maxId) {
         closeHippoDb(db);
     }
 }
-//# sourceMappingURL=graph.js.map
+//# sourceMappingURL=write.js.map

package/dist/graph-extract.js

@@ -20,7 +20,8 @@
  * skill/incident/process entities (not in the entity_type enum - needs a migration); the
  * `hippo sleep` enqueue-hook.
  */
-import { clearGraph, insertEntity, insertRelation, runGraphRebuildTransaction, MAX_ENTITY_NAME_LEN } from './graph.js';
+import { clearGraph, insertEntity, insertRelation, runGraphRebuildTransaction } from './graph/write.js';
+import { MAX_ENTITY_NAME_LEN } from './graph/types.js';
 import { loadDecisions } from './decisions.js';
 import { loadPolicies } from './policies.js';
 import { loadCustomerNotes } from './customer-notes.js';

package/dist/graph-recall.d.ts

@@ -1,4 +1,4 @@
-import type { ResultCost, SearchResult } from './search.js';
+import type { ResultCost, SearchResult } from './search/types.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */
 export declare const MAX_HOPS = 3;

package/dist/graph-recall.js

@@ -36,10 +36,10 @@
  * No graph writes (only SELECTs via graph.ts read helpers + store reads), so the E3.3
  * check-graph-writes lint permits this module living outside graph.ts.
  */
-import { loadEntriesByIds } from './store.js';
+import { loadEntriesByIds } from './store/entry-reads.js';
 import { estimateTokens } from './token-ledger.js';
 import { compareEntryIdentity } from './compare.js';
-import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations, } from './graph.js';
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
 import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from './recall-scope.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */

package/dist/graph-stream.js

@@ -1,4 +1,4 @@
-import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations, } from './graph.js';
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
 import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
 /** Default hops expanded from each seed (MVP; hard cap MAX_HOPS=3 reused from graph-recall). */
 export const DEFAULT_GRAPH_HOPS = 2;

package/dist/graph-view.d.ts

@@ -7,7 +7,7 @@
  * stays green. Used by the CLI (`hippo graph show` / `hippo graph view`) and the
  * HTTP `GET /v1/graph` route, which all build the same `GraphModel`.
  */
-import { type EntityType, type RelationType } from './graph.js';
+import { type EntityType, type RelationType } from './graph/types.js';
 export interface GraphNode {
     id: number;
     type: EntityType;

package/dist/graph-view.js

@@ -7,7 +7,7 @@
  * stays green. Used by the CLI (`hippo graph show` / `hippo graph view`) and the
  * HTTP `GET /v1/graph` route, which all build the same `GraphModel`.
  */
-import { loadEntities, loadEntitiesByName, loadEntitiesByIds, loadRelations, loadNeighborRelations, loadRelationsAmong, withGraphReadSnapshot, } from './graph.js';
+import { loadEntities, loadEntitiesByName, loadEntitiesByIds, loadRelations, loadNeighborRelations, loadRelationsAmong, withGraphReadSnapshot, } from './graph/read.js';
 /** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
 export const DEFAULT_VIEW_LIMIT = 500;
 /**

package/dist/half-life-migration.d.ts

@@ -21,7 +21,7 @@
  * moves memories of live decisions, incidents and other objects off the flat 90 days they used to get.
  */
 import { type MemoryEntry } from './memory.js';
-import { HALF_LIFE_BASE_META_KEY } from './store.js';
+import { HALF_LIFE_BASE_META_KEY } from './store/open.js';
 /** The base every store used before the base was recorded. */
 export declare const LEGACY_HALF_LIFE_BASE = 7;
 /** The flat half-life the decision, incident and other object writers gave their memories before they took the default. */

package/dist/half-life-migration.js

@@ -21,7 +21,8 @@
  * moves memories of live decisions, incidents and other objects off the flat 90 days they used to get.
  */
 import { deriveHalfLife } from './memory.js';
-import { openStore, selectAllEntries, HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY } from './store.js';
+import { openStore, HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY } from './store/open.js';
+import { selectAllEntries } from './store/entry-reads.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
 import { appendAuditEvent } from './audit.js';
 import { loadConfig } from './config.js';

package/dist/hooks/codex-session.d.ts

@@ -0,0 +1,8 @@
+export interface CodexSessionTranscriptOptions {
+    codexHome: string;
+    historyPath: string;
+    startOffsetBytes: number;
+    startedAtMs: number;
+}
+export declare function resolveCodexSessionTranscript(options: CodexSessionTranscriptOptions): string | null;
+//# sourceMappingURL=codex-session.d.ts.map

package/dist/hooks/codex-session.js

@@ -0,0 +1,76 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { isJsonString } from './shared.js';
+function collectFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === undefined)
+            break;
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+function readCodexSessionIdsFromHistoryDelta(historyPath, startOffsetBytes) {
+    if (!fs.existsSync(historyPath))
+        return [];
+    const raw = fs.readFileSync(historyPath);
+    if (startOffsetBytes >= raw.length)
+        return [];
+    const delta = raw.subarray(startOffsetBytes).toString('utf8');
+    const seen = new Set();
+    const ordered = [];
+    for (const line of delta.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const sessionId = parsed.session_id;
+            if (isJsonString(sessionId) && sessionId && !seen.has(sessionId)) {
+                seen.add(sessionId);
+                ordered.push(sessionId);
+            }
+        }
+        catch {
+            // ignore malformed JSONL lines
+        }
+    }
+    return ordered;
+}
+function findCodexTranscriptBySessionId(sessionsDir, sessionId) {
+    const matches = collectFiles(sessionsDir).filter((filePath) => filePath.endsWith('.jsonl') && filePath.includes(sessionId));
+    if (matches.length === 0)
+        return null;
+    matches.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+    return matches[0];
+}
+function findNewestCodexTranscriptSince(sessionsDir, startedAtMs) {
+    const matches = collectFiles(sessionsDir)
+        .filter((filePath) => filePath.endsWith('.jsonl'))
+        .map((filePath) => ({ filePath, mtimeMs: fs.statSync(filePath).mtimeMs }))
+        .filter((entry) => entry.mtimeMs >= startedAtMs)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return matches[0]?.filePath ?? null;
+}
+export function resolveCodexSessionTranscript(options) {
+    const { codexHome, historyPath, startOffsetBytes, startedAtMs } = options;
+    const sessionsDir = path.join(codexHome, 'sessions');
+    for (const sessionId of readCodexSessionIdsFromHistoryDelta(historyPath, startOffsetBytes).reverse()) {
+        const transcript = findCodexTranscriptBySessionId(sessionsDir, sessionId);
+        if (transcript)
+            return transcript;
+    }
+    return findNewestCodexTranscriptSince(sessionsDir, startedAtMs);
+}
+//# sourceMappingURL=codex-session.js.map

package/dist/hooks/codex-wrapper.d.ts

@@ -0,0 +1,55 @@
+export interface CodexWrapperPaths {
+    wrapperDir: string;
+    metadataPath: string;
+    wrapperCmdPath: string;
+    wrapperPs1Path: string;
+    wrapperShPath: string;
+    logFile: string;
+    runsDir: string;
+    codexHome: string;
+    historyPath: string;
+}
+export interface CodexWrapperInstallResult {
+    installed: boolean;
+    metadataPath: string;
+    realCodexPath: string;
+    commandPath: string;
+    backupPath: string;
+    installMode: 'same-path' | 'cmd-shim';
+}
+export interface CodexWrapperMetadata {
+    originalCodexPath: string;
+    realCodexPath: string;
+    commandPath: string;
+    backupPath: string;
+    installMode: 'same-path' | 'cmd-shim';
+    logFile: string;
+    installedAt: string;
+}
+export interface EnsureCodexWrapperResult {
+    status: 'installed' | 'already-installed' | 'not-found' | 'source-checkout';
+    metadataPath?: string;
+    realCodexPath?: string;
+    commandPath?: string;
+    backupPath?: string;
+}
+export declare function resolveCodexWrapperPaths(): CodexWrapperPaths;
+export declare function detectRealCodexPath(): string | null;
+export declare function installCodexWrapper(realCodexPath?: string): CodexWrapperInstallResult;
+export declare function uninstallCodexWrapper(): boolean;
+export declare function ensureCodexWrapperInstalled(): EnsureCodexWrapperResult;
+/**
+ * True if Codex wrapper metadata exists on this machine, i.e. the user opted
+ * in to the wrapper at some point (via `hippo hook install codex`).
+ */
+export declare function isCodexWrapperInstalled(): boolean;
+/**
+ * Repair-only variant of `ensureCodexWrapperInstalled`: re-ensures the wrapper
+ * ONLY when wrapper metadata already exists — that metadata is the user's
+ * opt-in record. Never performs a first install. Replacing another vendor's
+ * binary must stay behind the explicit `hippo hook install codex` command;
+ * doing it from postinstall or routine commands is a consent violation and
+ * reads as binary hijacking to security scanners (issue #133).
+ */
+export declare function repairCodexWrapperIfInstalled(hippoCliPath?: string): EnsureCodexWrapperResult;
+//# sourceMappingURL=codex-wrapper.d.ts.map