@psiclawops/hypermem 0.5.0 → 0.5.2

package/dist/desired-state-store.js

@@ -0,0 +1,222 @@
+/**
+ * hypermem Agent Desired State Store
+ *
+ * Stores intended configuration for each agent and tracks drift.
+ * Enables fleet-wide config visibility and enforcement.
+ *
+ * Config keys are dot-path strings matching openclaw.json structure:
+ *   model, thinkingDefault, provider, workspace, tools.exec.host, etc.
+ *
+ * Drift statuses:
+ *   - 'ok'       — actual matches desired
+ *   - 'drifted'  — actual differs from desired
+ *   - 'unknown'  — not yet checked
+ *   - 'error'    — check failed
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+function tryParseJson(val) {
+    try {
+        return JSON.parse(val);
+    }
+    catch {
+        // Value is a bare string (e.g. model names like "copilot-local/claude-sonnet-4.6")
+        // stored without JSON quoting — return as-is.
+        return val;
+    }
+}
+function parseEntry(row) {
+    return {
+        agentId: row.agent_id,
+        configKey: row.config_key,
+        desiredValue: row.desired_value ? tryParseJson(row.desired_value) : null,
+        actualValue: row.actual_value ? tryParseJson(row.actual_value) : null,
+        source: row.source,
+        setBy: row.set_by || null,
+        driftStatus: row.drift_status || 'unknown',
+        lastChecked: row.last_checked || null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        notes: row.notes || null,
+    };
+}
+function parseEvent(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        configKey: row.config_key,
+        eventType: row.event_type,
+        oldValue: row.old_value ? tryParseJson(row.old_value) : null,
+        newValue: row.new_value ? tryParseJson(row.new_value) : null,
+        changedBy: row.changed_by || null,
+        createdAt: row.created_at,
+    };
+}
+export class DesiredStateStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Set desired state for a config key on an agent.
+     */
+    setDesired(agentId, configKey, desiredValue, opts) {
+        const now = nowIso();
+        const valueJson = JSON.stringify(desiredValue);
+        const existing = this.getEntry(agentId, configKey);
+        if (existing) {
+            // Record change event
+            this.db.prepare(`
+        INSERT INTO agent_config_events (agent_id, config_key, event_type, old_value, new_value, changed_by, created_at)
+        VALUES (?, ?, 'desired_changed', ?, ?, ?, ?)
+      `).run(agentId, configKey, JSON.stringify(existing.desiredValue), valueJson, opts?.setBy || null, now);
+            this.db.prepare(`
+        UPDATE agent_desired_state SET
+          desired_value = ?,
+          source = COALESCE(?, source),
+          set_by = COALESCE(?, set_by),
+          drift_status = 'unknown',
+          notes = COALESCE(?, notes),
+          updated_at = ?
+        WHERE agent_id = ? AND config_key = ?
+      `).run(valueJson, opts?.source || null, opts?.setBy || null, opts?.notes || null, now, agentId, configKey);
+        }
+        else {
+            this.db.prepare(`
+        INSERT INTO agent_desired_state (agent_id, config_key, desired_value, source, set_by, drift_status, created_at, updated_at, notes)
+        VALUES (?, ?, ?, ?, ?, 'unknown', ?, ?, ?)
+      `).run(agentId, configKey, valueJson, opts?.source || 'operator', opts?.setBy || null, now, now, opts?.notes || null);
+            // Record creation event
+            this.db.prepare(`
+        INSERT INTO agent_config_events (agent_id, config_key, event_type, new_value, changed_by, created_at)
+        VALUES (?, ?, 'desired_set', ?, ?, ?)
+      `).run(agentId, configKey, valueJson, opts?.setBy || null, now);
+        }
+        return this.getEntry(agentId, configKey);
+    }
+    /**
+     * Report actual state observed at runtime.
+     * Compares against desired and updates drift status.
+     */
+    reportActual(agentId, configKey, actualValue) {
+        const now = nowIso();
+        const actualJson = JSON.stringify(actualValue);
+        const entry = this.getEntry(agentId, configKey);
+        if (!entry)
+            return 'unknown';
+        const desiredJson = JSON.stringify(entry.desiredValue);
+        const driftStatus = actualJson === desiredJson ? 'ok' : 'drifted';
+        this.db.prepare(`
+      UPDATE agent_desired_state SET
+        actual_value = ?,
+        drift_status = ?,
+        last_checked = ?,
+        updated_at = ?
+      WHERE agent_id = ? AND config_key = ?
+    `).run(actualJson, driftStatus, now, now, agentId, configKey);
+        if (driftStatus === 'drifted' && actualJson !== JSON.stringify(entry.actualValue)) {
+            this.db.prepare(`
+        INSERT INTO agent_config_events (agent_id, config_key, event_type, old_value, new_value, changed_by, created_at)
+        VALUES (?, ?, 'drift_detected', ?, ?, 'system', ?)
+      `).run(agentId, configKey, JSON.stringify(entry.actualValue), actualJson, now);
+        }
+        return driftStatus;
+    }
+    /**
+     * Bulk report actual state for an agent (e.g., on heartbeat).
+     */
+    reportActualBulk(agentId, actuals) {
+        const results = {};
+        for (const [key, value] of Object.entries(actuals)) {
+            results[key] = this.reportActual(agentId, key, value);
+        }
+        return results;
+    }
+    /**
+     * Get a specific desired state entry.
+     */
+    getEntry(agentId, configKey) {
+        const row = this.db.prepare('SELECT * FROM agent_desired_state WHERE agent_id = ? AND config_key = ?').get(agentId, configKey);
+        return row ? parseEntry(row) : null;
+    }
+    /**
+     * Get all desired state for an agent.
+     */
+    getAgentState(agentId) {
+        const rows = this.db.prepare('SELECT * FROM agent_desired_state WHERE agent_id = ? ORDER BY config_key').all(agentId);
+        return rows.map(parseEntry);
+    }
+    /**
+     * Get desired state as a flat config object (key → value).
+     */
+    getAgentConfig(agentId) {
+        const entries = this.getAgentState(agentId);
+        const config = {};
+        for (const entry of entries) {
+            config[entry.configKey] = entry.desiredValue;
+        }
+        return config;
+    }
+    /**
+     * Get all drifted entries across the fleet.
+     */
+    getDrifted() {
+        const rows = this.db.prepare("SELECT * FROM agent_desired_state WHERE drift_status = 'drifted' ORDER BY agent_id, config_key").all();
+        return rows.map(parseEntry);
+    }
+    /**
+     * Get fleet-wide view of a specific config key.
+     */
+    getFleetConfig(configKey) {
+        const rows = this.db.prepare('SELECT * FROM agent_desired_state WHERE config_key = ? ORDER BY agent_id').all(configKey);
+        return rows.map(parseEntry);
+    }
+    /**
+     * Get config change history for an agent/key.
+     */
+    getHistory(agentId, configKey, limit = 20) {
+        let sql = 'SELECT * FROM agent_config_events WHERE agent_id = ?';
+        const params = [agentId];
+        if (configKey) {
+            sql += ' AND config_key = ?';
+            params.push(configKey);
+        }
+        sql += ' ORDER BY created_at DESC LIMIT ?';
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseEvent);
+    }
+    /**
+     * Remove a desired state entry.
+     */
+    removeDesired(agentId, configKey, removedBy) {
+        const now = nowIso();
+        const existing = this.getEntry(agentId, configKey);
+        if (existing) {
+            this.db.prepare(`
+        INSERT INTO agent_config_events (agent_id, config_key, event_type, old_value, changed_by, created_at)
+        VALUES (?, ?, 'desired_removed', ?, ?, ?)
+      `).run(agentId, configKey, JSON.stringify(existing.desiredValue), removedBy || null, now);
+            this.db.prepare('DELETE FROM agent_desired_state WHERE agent_id = ? AND config_key = ?').run(agentId, configKey);
+        }
+    }
+    /**
+     * Get fleet drift summary.
+     */
+    getDriftSummary() {
+        const rows = this.db.prepare(`
+      SELECT drift_status, COUNT(*) as count FROM agent_desired_state GROUP BY drift_status
+    `).all();
+        const summary = { total: 0, ok: 0, drifted: 0, unknown: 0, error: 0 };
+        for (const row of rows) {
+            const count = row.count;
+            summary.total += count;
+            if (row.drift_status in summary) {
+                summary[row.drift_status] = count;
+            }
+        }
+        return summary;
+    }
+}
+//# sourceMappingURL=desired-state-store.js.map

package/dist/doc-chunk-store.d.ts

@@ -0,0 +1,140 @@
+/**
+ * hypermem Document Chunk Store
+ *
+ * Manages doc_chunks in library.db:
+ * - Atomic re-indexing by source hash (no stale/fresh coexistence)
+ * - FTS5 keyword search fallback
+ * - Collection-scoped queries with agent/tier filtering
+ * - Source tracking (what's indexed, when, what hash)
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { DocChunk } from './doc-chunker.js';
+export interface DocChunkRow {
+    id: string;
+    collection: string;
+    sectionPath: string;
+    depth: number;
+    content: string;
+    tokenEstimate: number;
+    sourceHash: string;
+    sourcePath: string;
+    scope: string;
+    tier: string | null;
+    agentId: string | null;
+    parentPath: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface DocSourceRow {
+    sourcePath: string;
+    collection: string;
+    scope: string;
+    agentId: string | null;
+    sourceHash: string;
+    chunkCount: number;
+    indexedAt: string;
+}
+export interface IndexResult {
+    /** Number of new chunks inserted */
+    inserted: number;
+    /** Number of stale chunks deleted (from prior version) */
+    deleted: number;
+    /** Whether this was a full re-index (hash changed) or a no-op (hash unchanged) */
+    reindexed: boolean;
+    /** Whether this source was already up-to-date */
+    skipped: boolean;
+}
+export interface ChunkQuery {
+    /** Collection path to query */
+    collection: string;
+    /** Filter by scope */
+    scope?: string;
+    /** Filter by agent ID (for per-agent chunks) */
+    agentId?: string;
+    /** Filter by tier (for per-tier chunks) */
+    tier?: string;
+    /** Max number of chunks to return */
+    limit?: number;
+    /** Keyword search (FTS5) */
+    keyword?: string;
+}
+export declare class DocChunkStore {
+    private db;
+    constructor(db: DatabaseSync);
+    /**
+     * Index a set of chunks for a source file.
+     *
+     * Atomic re-indexing:
+     * 1. Check if source_hash has changed
+     * 2. If unchanged: skip (idempotent)
+     * 3. If changed: delete all chunks with old hash, insert new chunks — in one transaction
+     *
+     * This ensures no window where stale and fresh chunks coexist.
+     */
+    indexChunks(chunks: DocChunk[]): IndexResult;
+    /**
+     * Query chunks by collection with optional filters.
+     * Falls back to FTS5 keyword search when keyword is provided.
+     */
+    queryChunks(query: ChunkQuery): DocChunkRow[];
+    /**
+     * FTS5 keyword search across chunks.
+     */
+    keywordSearch(keyword: string, query: Omit<ChunkQuery, 'keyword'>): DocChunkRow[];
+    /**
+     * Get a single chunk by ID.
+     */
+    getChunk(id: string): DocChunkRow | null;
+    /**
+     * Check if a source file needs re-indexing.
+     * Returns true if the file has changed or has never been indexed.
+     */
+    needsReindex(sourcePath: string, collection: string, currentHash: string): boolean;
+    /**
+     * List all indexed sources, optionally filtered by agent or collection.
+     */
+    listSources(opts?: {
+        agentId?: string;
+        collection?: string;
+    }): DocSourceRow[];
+    /**
+     * Delete all chunks for a specific source file.
+     */
+    deleteSource(sourcePath: string, collection: string): number;
+    /**
+     * Index simple string chunks with an optional session key (for ephemeral spawn context).
+     *
+     * Unlike indexChunks() which works with DocChunk objects and hash-based dedup,
+     * this method is designed for ad-hoc session-scoped content: it always inserts fresh
+     * rows tagged with the sessionKey, without hash-based skip logic.
+     *
+     * Chunks stored with a sessionKey are ephemeral — use clearSessionChunks() to remove them.
+     */
+    indexDocChunks(agentId: string, source: string, chunks: string[], options?: {
+        sessionKey?: string;
+    }): void;
+    /**
+     * Query doc chunks by agentId+query string, with optional session key scoping.
+     * When sessionKey is provided, only chunks tagged with that session key are returned.
+     */
+    queryDocChunks(agentId: string, query: string, options?: {
+        sessionKey?: string;
+        limit?: number;
+    }): DocChunkRow[];
+    /**
+     * Delete all doc chunks associated with a specific session key.
+     * Call this when a spawn session is complete to release ephemeral storage.
+     */
+    clearSessionChunks(sessionKey: string): number;
+    /**
+     * Get chunk stats: count per collection.
+     */
+    getStats(): Array<{
+        collection: string;
+        count: number;
+        sources: number;
+        totalTokens: number;
+    }>;
+    private mapRow;
+}
+//# sourceMappingURL=doc-chunk-store.d.ts.map

package/dist/doc-chunk-store.d.ts.map

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