@psiclawops/hypermem 0.6.2 → 0.8.0

package/dist/reranker.js

@@ -0,0 +1,308 @@
+/**
+ * hypermem Reranker
+ *
+ * Pluggable reranking interface with circuit-breaker protection and graceful
+ * degradation. Callers that receive null fall back to the original document
+ * order without disruption.
+ *
+ * Providers:
+ *   - ZeroEntropyReranker — https://api.zeroentropy.dev/v1/rerank (zerank-2)
+ *   - OpenRouterReranker  — https://openrouter.ai/api/v1/rerank (cohere/rerank-4-pro)
+ *   - OllamaReranker      — http://localhost:11434/api/chat (yes/no classification)
+ *
+ * API key resolution order (per provider):
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ */
+// ── Circuit Breaker ───────────────────────────────────────────────────────────
+/** Number of consecutive failures before the circuit opens. */
+const CIRCUIT_FAILURE_THRESHOLD = 3;
+/** How long the circuit stays open after tripping (ms). */
+const CIRCUIT_DISABLE_DURATION_MS = 60_000;
+/**
+ * CircuitBreaker protects a provider from repeated calls during sustained
+ * failures.
+ *
+ * State machine:
+ *   CLOSED  — normal operation; failures increment the counter.
+ *   OPEN    — provider disabled; isOpen() returns true for DISABLE_DURATION.
+ *   HALF-OPEN — one probe allowed after the disable window expires;
+ *               success resets the counter, failure re-opens the circuit.
+ *
+ * Transition: CLOSED → OPEN when consecutiveFailures >= FAILURE_THRESHOLD.
+ * Transition: OPEN → HALF-OPEN when Date.now() >= disabledUntil.
+ * Transition: HALF-OPEN → CLOSED on recordSuccess().
+ * Transition: HALF-OPEN → OPEN on recordFailure() (reset window starts fresh).
+ */
+class CircuitBreaker {
+    /** Consecutive failures since last success. Reset to 0 on any success. */
+    consecutiveFailures = 0;
+    /**
+     * Epoch ms after which the circuit allows a probe.
+     * 0 means the circuit is CLOSED (not disabled).
+     */
+    disabledUntil = 0;
+    /** Returns true when the provider should be skipped. */
+    isOpen() {
+        if (this.disabledUntil === 0)
+            return false; // CLOSED
+        if (Date.now() >= this.disabledUntil) {
+            // Disable window expired — transition to HALF-OPEN: allow one probe.
+            // We clear disabledUntil here so the next call goes through.
+            // If it fails, recordFailure() re-opens the circuit with a fresh window.
+            this.disabledUntil = 0;
+            return false;
+        }
+        return true; // OPEN
+    }
+    /** Call on a successful provider response. Resets all failure state. */
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.disabledUntil = 0;
+    }
+    /**
+     * Call on any provider failure (non-2xx, timeout, parse error, etc.).
+     * After CIRCUIT_FAILURE_THRESHOLD consecutive failures, opens the circuit
+     * for CIRCUIT_DISABLE_DURATION_MS milliseconds.
+     */
+    recordFailure() {
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= CIRCUIT_FAILURE_THRESHOLD) {
+            // Trip the circuit — disable for the configured window.
+            // Reset consecutiveFailures so the probe after the window isn't
+            // pre-tripped by the old count.
+            this.disabledUntil = Date.now() + CIRCUIT_DISABLE_DURATION_MS;
+            this.consecutiveFailures = 0;
+        }
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Returns an AbortController that fires after `ms` and a cleanup handle. */
+function withTimeout(ms) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), ms);
+    return { controller, clear: () => clearTimeout(id) };
+}
+// ── ZeroEntropyReranker ───────────────────────────────────────────────────────
+export class ZeroEntropyReranker {
+    name = 'zeroentropy';
+    circuit = new CircuitBreaker();
+    apiKey;
+    model;
+    timeoutMs;
+    constructor(apiKey, model = 'zerank-2', timeoutMs = 2000) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.timeoutMs = timeoutMs;
+    }
+    async rerank(query, documents, topK = 10) {
+        if (this.circuit.isOpen())
+            return null;
+        const { controller, clear } = withTimeout(this.timeoutMs);
+        try {
+            const response = await fetch('https://api.zeroentropy.dev/v1/rerank', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ query, documents, model: this.model, top_n: topK }),
+                signal: controller.signal,
+            });
+            clear();
+            if (!response.ok) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            const data = (await response.json());
+            if (!Array.isArray(data.results)) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            this.circuit.recordSuccess();
+            return data.results.map((r) => {
+                const score = r.score ?? r.relevance_score ?? 0;
+                const content = resolveDocumentText(r.content, r.document, documents[r.index]);
+                return { index: r.index, score, content };
+            });
+        }
+        catch {
+            clear();
+            this.circuit.recordFailure();
+            return null;
+        }
+    }
+}
+// ── OpenRouterReranker ────────────────────────────────────────────────────────
+export class OpenRouterReranker {
+    name = 'openrouter';
+    circuit = new CircuitBreaker();
+    apiKey;
+    model;
+    timeoutMs;
+    constructor(apiKey, model = 'cohere/rerank-4-pro', timeoutMs = 2000) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.timeoutMs = timeoutMs;
+    }
+    async rerank(query, documents, topK = 10) {
+        if (this.circuit.isOpen())
+            return null;
+        const { controller, clear } = withTimeout(this.timeoutMs);
+        try {
+            const response = await fetch('https://openrouter.ai/api/v1/rerank', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ query, documents, model: this.model, top_n: topK }),
+                signal: controller.signal,
+            });
+            clear();
+            if (!response.ok) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            const data = (await response.json());
+            if (!Array.isArray(data.results)) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            this.circuit.recordSuccess();
+            return data.results.map((r) => {
+                const score = r.relevance_score ?? r.score ?? 0;
+                const content = resolveDocumentText(undefined, r.document, documents[r.index]);
+                return { index: r.index, score, content };
+            });
+        }
+        catch {
+            clear();
+            this.circuit.recordFailure();
+            return null;
+        }
+    }
+}
+// ── OllamaReranker ────────────────────────────────────────────────────────────
+const OLLAMA_SYSTEM_PROMPT = 'Judge whether the Document meets the requirements based on the Query and the Instruct provided. ' +
+    'Note that the answer can only be "yes" or "no".';
+export class OllamaReranker {
+    name = 'ollama';
+    circuit = new CircuitBreaker();
+    baseUrl;
+    model;
+    timeoutMs;
+    constructor(baseUrl = 'http://localhost:11434', model = 'dengcao/Qwen3-Reranker-0.6B:Q5_K_M', timeoutMs = 10_000) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.model = model;
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * Scores documents sequentially — one chat call per document.
+     * The Qwen3-Reranker-0.6B model responds with "yes" (relevant) or "no".
+     * Score: yes → 1.0, anything else → 0.0.
+     *
+     * Sequential iteration is required because Ollama's /api/chat is stateless
+     * per-request and running calls in parallel would overload a local GPU.
+     * Returns null on the first failure to preserve circuit breaker semantics.
+     */
+    async rerank(query, documents, topK = 10) {
+        if (this.circuit.isOpen())
+            return null;
+        const scored = [];
+        for (let i = 0; i < documents.length; i++) {
+            const doc = documents[i];
+            const userContent = `Instruct: Given a query, retrieve relevant passages that answer the query\n\n` +
+                `Query: ${query}\n\nDocument: ${doc}`;
+            const { controller, clear } = withTimeout(this.timeoutMs);
+            try {
+                const response = await fetch(`${this.baseUrl}/api/chat`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        model: this.model,
+                        messages: [
+                            { role: 'system', content: OLLAMA_SYSTEM_PROMPT },
+                            { role: 'user', content: userContent },
+                        ],
+                        stream: false,
+                    }),
+                    signal: controller.signal,
+                });
+                clear();
+                if (!response.ok) {
+                    this.circuit.recordFailure();
+                    return null;
+                }
+                const data = (await response.json());
+                const answer = (data.message?.content ?? '').trim().toLowerCase();
+                // "yes" prefix → relevant; anything else (including "no") → not relevant
+                const score = answer.startsWith('yes') ? 1.0 : 0.0;
+                scored.push({ index: i, score, content: doc });
+            }
+            catch {
+                clear();
+                this.circuit.recordFailure();
+                return null;
+            }
+        }
+        this.circuit.recordSuccess();
+        // Sort by score descending and return top-K
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, topK);
+    }
+}
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Creates a RerankerProvider from the supplied config.
+ *
+ * API key resolution order:
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ *
+ * Returns null when:
+ *   - provider is 'none'
+ *   - provider is 'zeroentropy' and no key found in config or env
+ *   - provider is 'openrouter' and no key found in config or env
+ *
+ * 'local' (Ollama) never returns null from the factory — it has no required
+ * API key. The provider itself returns null on runtime failure.
+ */
+export function createReranker(config) {
+    switch (config.provider) {
+        case 'none':
+            return null;
+        case 'zeroentropy': {
+            const apiKey = config.zeroEntropyApiKey ?? process.env['ZEROENTROPY_API_KEY'];
+            if (!apiKey)
+                return null;
+            return new ZeroEntropyReranker(apiKey, config.zeroEntropyModel ?? 'zerank-2', config.timeoutMs);
+        }
+        case 'openrouter': {
+            const apiKey = config.openrouterApiKey ?? process.env['OPENROUTER_API_KEY'];
+            if (!apiKey)
+                return null;
+            return new OpenRouterReranker(apiKey, config.openrouterModel ?? 'cohere/rerank-4-pro', config.timeoutMs);
+        }
+        case 'local': {
+            return new OllamaReranker(config.ollamaUrl ?? 'http://localhost:11434', config.ollamaModel ?? 'dengcao/Qwen3-Reranker-0.6B:Q5_K_M', config.timeoutMs);
+        }
+    }
+}
+// ── Private Helpers ───────────────────────────────────────────────────────────
+/**
+ * Resolves the document text from a reranking API response.
+ * Preference order: explicit `content` string → `document` string →
+ * `document.text` string → original document from the input array.
+ */
+function resolveDocumentText(content, document, fallback) {
+    if (typeof content === 'string')
+        return content;
+    if (typeof document === 'string')
+        return document;
+    if (document !== null && typeof document === 'object' && typeof document.text === 'string') {
+        return document.text;
+    }
+    return fallback ?? '';
+}
+//# sourceMappingURL=reranker.js.map

package/dist/schema.d.ts

@@ -6,7 +6,7 @@
  * Contains ONLY conversation data — structured knowledge lives in library.db.
  */
 import type { DatabaseSync } from 'node:sqlite';
-export declare const LATEST_SCHEMA_VERSION = 8;
+export declare const LATEST_SCHEMA_VERSION = 10;
 /**
  * Run migrations on an agent message database.
  */

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAgJvC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA0H9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAgJxC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA0K9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}

package/dist/schema.js

@@ -5,7 +5,7 @@
  * Write-heavy, temporal, rotatable.
  * Contains ONLY conversation data — structured knowledge lives in library.db.
  */
-export const LATEST_SCHEMA_VERSION = 8;
+export const LATEST_SCHEMA_VERSION = 10;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -250,6 +250,51 @@ export function migrate(db) {
         db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
             .run(8, nowIso());
     }
+    // v8 → v9: Tool Artifact Store — durable storage for full tool result payloads.
+    // Transcript stubs carry an artifactId pointer; raw payload lives here so
+    // wave-guard degradation is never lossy. See specs/TOOL_ARTIFACT_STORE.md.
+    if (currentVersion < 9) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS tool_artifacts (
+        id                 TEXT PRIMARY KEY,
+        content_hash       TEXT NOT NULL,
+        agent_id           TEXT NOT NULL,
+        session_key        TEXT NOT NULL,
+        conversation_id    INTEGER REFERENCES conversations(id),
+        message_id         INTEGER REFERENCES messages(id),
+        turn_id            TEXT,
+        tool_call_id       TEXT,
+        tool_name          TEXT NOT NULL,
+        is_error           INTEGER NOT NULL DEFAULT 0,
+        content_type       TEXT NOT NULL DEFAULT 'text/plain',
+        size_bytes         INTEGER NOT NULL,
+        token_estimate     INTEGER NOT NULL,
+        payload            TEXT NOT NULL,
+        summary            TEXT,
+        created_at         TEXT NOT NULL,
+        last_used_at       TEXT NOT NULL,
+        ref_count          INTEGER NOT NULL DEFAULT 1
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_hash ON tool_artifacts(content_hash)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_session ON tool_artifacts(agent_id, session_key, created_at DESC)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_turn ON tool_artifacts(turn_id)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_tool_call ON tool_artifacts(tool_call_id)');
+        db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(9, nowIso());
+    }
+    // v9 → v10: Retention sweep — add is_sensitive flag to tool_artifacts.
+    // Enables differential TTL: sensitive artifacts expire sooner than standard ones.
+    // See: ToolArtifactStore.sweep() and ToolArtifactRetentionPolicy.
+    if (currentVersion < 10) {
+        const taCols = db.prepare('PRAGMA table_info(tool_artifacts)').all()
+            .map(r => r.name);
+        if (!taCols.includes('is_sensitive')) {
+            db.exec('ALTER TABLE tool_artifacts ADD COLUMN is_sensitive INTEGER NOT NULL DEFAULT 0');
+        }
+        db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(10, nowIso());
+    }
 }
 export { LATEST_SCHEMA_VERSION as SCHEMA_VERSION };
 //# sourceMappingURL=schema.js.map

package/dist/seed.d.ts

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   const seeder = new WorkspaceSeeder(hypermem);
- *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'agent1' });
+ *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'alice' });
  *
  * Idempotent: skips files whose source hash hasn't changed since last index.
  * Atomic: each file's chunks are swapped in a single transaction.

package/dist/seed.js

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   const seeder = new WorkspaceSeeder(hypermem);
- *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'agent1' });
+ *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'alice' });
  *
  * Idempotent: skips files whose source hash hasn't changed since last index.
  * Atomic: each file's chunks are swapped in a single transaction.

package/dist/session-flusher.d.ts

@@ -1,7 +1,7 @@
 /**
  * session-flusher.ts
  *
- * Provides a clean, operator-safe way to flush a session's hot cache from Redis
+ * Provides a clean, operator-safe way to flush a session's hot cache
  * without touching long-term memory (facts, vectors, episodes, knowledge graph).
  *
  * Used to implement the /fresh slash command — lets users start a new unwarmed
@@ -12,7 +12,7 @@
  */
 import type { CacheLayer } from './cache.js';
 export interface FlushSessionOptions {
-    /** If true, also clears topic-level Redis keys for this session */
+    /** If true, also clears topic-level hot-cache entries for this session */
     includeTopics?: boolean;
 }
 export interface FlushSessionResult {
@@ -33,8 +33,8 @@ export interface FlushSessionResult {
  * from those stores naturally.
  *
  * @param cache   Connected CacheLayer instance
- * @param agentId Agent identifier (e.g. "agent1")
- * @param sessionKey  Full session key (e.g. "agent:agent1:webchat:scratchpad")
+ * @param agentId Agent identifier (e.g. "alice")
+ * @param sessionKey  Full session key (e.g. "agent:alice:webchat:scratchpad")
  * @param opts    Optional flags
  */
 export declare function flushSession(cache: CacheLayer, agentId: string, sessionKey: string, opts?: FlushSessionOptions): Promise<FlushSessionResult>;

package/dist/session-flusher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-flusher.d.ts","sourceRoot":"","sources":["../src/session-flusher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM;IAGlC;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGzF"}
+{"version":3,"file":"session-flusher.d.ts","sourceRoot":"","sources":["../src/session-flusher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM;IAGlC;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGzF"}

package/dist/session-flusher.js

@@ -1,7 +1,7 @@
 /**
  * session-flusher.ts
  *
- * Provides a clean, operator-safe way to flush a session's hot cache from Redis
+ * Provides a clean, operator-safe way to flush a session's hot cache
  * without touching long-term memory (facts, vectors, episodes, knowledge graph).
  *
  * Used to implement the /fresh slash command — lets users start a new unwarmed
@@ -18,8 +18,8 @@
  * from those stores naturally.
  *
  * @param cache   Connected CacheLayer instance
- * @param agentId Agent identifier (e.g. "agent1")
- * @param sessionKey  Full session key (e.g. "agent:agent1:webchat:scratchpad")
+ * @param agentId Agent identifier (e.g. "alice")
+ * @param sessionKey  Full session key (e.g. "agent:alice:webchat:scratchpad")
  * @param opts    Optional flags
  */
 export async function flushSession(cache, agentId, sessionKey, opts = {}) {

package/dist/spawn-context.d.ts

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   const ctx = await buildSpawnContext(messageStore, docChunkStore, agentId, {
- *     parentSessionKey: 'agent:agent1:webchat:main',
+ *     parentSessionKey: 'agent:alice:webchat:main',
  *     workingSnapshot: 10,
  *     documents: ['/path/to/spec.md'],
  *   });

package/dist/spawn-context.js

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   const ctx = await buildSpawnContext(messageStore, docChunkStore, agentId, {
- *     parentSessionKey: 'agent:agent1:webchat:main',
+ *     parentSessionKey: 'agent:alice:webchat:main',
  *     workingSnapshot: 10,
  *     documents: ['/path/to/spec.md'],
  *   });

package/dist/temporal-store.d.ts

@@ -56,6 +56,7 @@ export declare class TemporalStore {
         timeRef?: string;
         confidence?: number;
         occurredAt?: number;
+        validFrom?: string;
     }): void;
     /**
      * Time-range query. Returns facts in temporal order.

package/dist/temporal-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temporal-store.d.ts","sourceRoot":"","sources":["../src/temporal-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAeD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;OAIG;IACH,SAAS,CACP,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,IAAI;IAkBP;;;OAGG;IACH,cAAc,CAAC,IAAI,GAAE,oBAAyB,GAAG,YAAY,EAAE;IAgE/D;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,YAAY,EAAE;IAIvD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOxC;;;OAGG;IACH,QAAQ,IAAI,MAAM;CAenB"}
+{"version":3,"file":"temporal-store.d.ts","sourceRoot":"","sources":["../src/temporal-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAeD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;OAIG;IACH,SAAS,CACP,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACxF,IAAI;IAkBP;;;OAGG;IACH,cAAc,CAAC,IAAI,GAAE,oBAAyB,GAAG,YAAY,EAAE;IAgE/D;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,YAAY,EAAE;IAIvD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOxC;;;OAGG;IACH,QAAQ,IAAI,MAAM;CAenB"}

package/dist/tool-artifact-store.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Tool Artifact Store
+ *
+ * Durable, addressable storage for full tool result payloads. Schema v9.
+ *
+ * Why: the wave-guard at ingest time replaces oversized tool result payloads
+ * with a small stub for pressure relief. Before this store existed, the full
+ * payload was discarded. Now the stub in the transcript carries an
+ * `artifactId` pointing at the durable copy here, and hydration is an
+ * explicit decision, not an automatic transcript rewrite.
+ *
+ * Retention is deliberately independent of transcript eviction. Artifacts
+ * outlive the messages that referenced them, and GC is a separate concern
+ * (Phase 2).
+ *
+ * See: specs/TOOL_ARTIFACT_STORE.md
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface ToolArtifactRetentionPolicy {
+    /** TTL in ms for non-sensitive artifacts (e.g. 7 * 24 * 60 * 60 * 1000). */
+    standardTtlMs: number;
+    /** TTL in ms for sensitive artifacts. Should be <= standardTtlMs. */
+    sensitiveTtlMs: number;
+    /** Optional: max artifacts to keep per (agent_id, session_key). Excess removed oldest-first. */
+    maxPerSession?: number;
+}
+export interface ToolArtifactRecord {
+    id: string;
+    contentHash: string;
+    agentId: string;
+    sessionKey: string;
+    conversationId: number | null;
+    messageId: number | null;
+    turnId: string | null;
+    toolCallId: string | null;
+    toolName: string;
+    isError: boolean;
+    contentType: string;
+    sizeBytes: number;
+    tokenEstimate: number;
+    payload: string;
+    summary: string | null;
+    createdAt: string;
+    lastUsedAt: string;
+    refCount: number;
+    isSensitive: boolean;
+}
+export interface PutToolArtifactInput {
+    agentId: string;
+    sessionKey: string;
+    conversationId?: number;
+    messageId?: number;
+    turnId?: string;
+    toolCallId?: string;
+    toolName: string;
+    isError?: boolean;
+    contentType?: string;
+    payload: string;
+    summary?: string;
+    isSensitive?: boolean;
+}
+export declare class ToolArtifactStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Insert a new artifact, or dedupe against an existing one in the same
+     * (agentId, sessionKey) scope. Dedupe is scoped to a session so distinct
+     * sessions can't leak artifact ids across each other even when payload
+     * content is identical.
+     */
+    put(input: PutToolArtifactInput): ToolArtifactRecord;
+    /** Alias for get(id) — explicit name used by the compositor hydration pass. */
+    getById(id: string): ToolArtifactRecord | null;
+    get(id: string): ToolArtifactRecord | null;
+    getByHash(agentId: string, sessionKey: string, contentHash: string): ToolArtifactRecord | null;
+    listByTurn(sessionKey: string, turnId: string): ToolArtifactRecord[];
+    listByToolCall(toolCallId: string): ToolArtifactRecord[];
+    listRecent(agentId: string, sessionKey: string, limit?: number): ToolArtifactRecord[];
+    /** Update last_used_at — call this when hydration actually surfaces the payload. */
+    touch(id: string): void;
+    /**
+     * GC sweep: delete artifacts that exceed their TTL or per-session count cap.
+     * Returns total rows deleted.
+     *
+     * Sensitive artifacts use sensitiveTtlMs (shorter); standard artifacts use
+     * standardTtlMs. Optional maxPerSession bounds row count per (agent, session)
+     * using a ROW_NUMBER() window query — oldest last_used_at removed first.
+     */
+    sweep(policy: ToolArtifactRetentionPolicy): number;
+    /**
+     * Delete artifacts whose last_used_at is older than the ISO cutoff.
+     * Returns the number of rows deleted. Phase 1: manual invocation only.
+     */
+    deleteOlderThan(isoCutoff: string): number;
+    /** Debug / ops: row count across a session. */
+    count(agentId?: string, sessionKey?: string): number;
+}
+//# sourceMappingURL=tool-artifact-store.d.ts.map

package/dist/tool-artifact-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-artifact-store.d.ts","sourceRoot":"","sources":["../src/tool-artifact-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0BhD,MAAM,WAAW,2BAA2B;IAC1C,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA0BD,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,oBAAoB,GAAG,kBAAkB;IA+FpD,+EAA+E;IAC/E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAI9C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAO1C,SAAS,CACP,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,kBAAkB,GAAG,IAAI;IAY5B,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAWpE,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAWxD,UAAU,CACR,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAW,GACjB,kBAAkB,EAAE;IAYvB,oFAAoF;IACpF,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMvB;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,2BAA2B,GAAG,MAAM;IAsClD;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAO1C,+CAA+C;IAC/C,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAcrD"}