@0xmaxma/claude-gateway 1.6.9 → 1.7.0

package/dist/agent/dreaming/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Types for nightly memory "dreaming" (issue #325, Part C).
+ *
+ * P2 slice = `propose` (dry-run) only: a print-only reviewer proposes memory
+ * consolidation ops which are written to a DREAMS.md diary + JSONL audit — the
+ * gateway mutates NO memory file. `auto` mode (applying ops) is a P3 follow-up.
+ */
+export type DreamMode = 'propose' | 'auto';
+export type DreamOpKind = 'add' | 'replace' | 'remove';
+export type DreamFile = 'MEMORY.md' | 'USER.md';
+/**
+ * Which memory tier an op writes to (planning-65).
+ *   - `durable`  → an evergreen file (`MEMORY.md`/`USER.md`), injected every session.
+ *   - `episodic` → a `memory/<topic>.md` note, searched on demand (task-log).
+ * Absent ⇒ `durable` (back-compat with pre-routing proposals).
+ */
+export type DreamTier = 'durable' | 'episodic';
+/** Raw archive-staleness-GC config under `gateway.dreaming.staleness` (planning-66). */
+export interface StalenessConfig {
+    enabled?: boolean;
+    staleTtlDays?: number;
+    keepImportance?: number;
+    minRetrievalKeep?: number;
+    supersession?: boolean;
+    recordRetrievals?: boolean;
+}
+/** Fully-resolved staleness config (defaults applied, values sanitized). */
+export interface ResolvedStalenessCfg {
+    enabled: boolean;
+    staleTtlDays: number;
+    keepImportance: number;
+    minRetrievalKeep: number;
+    supersession: boolean;
+    recordRetrievals: boolean;
+}
+/** Partial config as it appears under `gateway.dreaming` / a per-agent override. */
+export interface DreamingConfig {
+    enabled?: boolean;
+    mode?: DreamMode;
+    dreamHour?: number;
+    /** Minute-of-hour (0–59, default 0) the dream fires at, paired with `dreamHour`. */
+    dreamMinute?: number;
+    dreamTimezone?: string;
+    quietMinutes?: number;
+    lookbackDays?: number;
+    maxChangesPerRun?: number;
+    reviewModel?: string;
+    promotionThreshold?: number;
+    minRecallCount?: number;
+    /**
+     * planning-67: when true (default), the nightly dream (auto mode) drains an
+     * over-budget MEMORY.md by routing episodic task-log to `memory/<topic>.md`
+     * automatically (archive-safe), instead of relying on manual `dreaming:migrate`.
+     * A clean kill-switch: false ⇒ prior behavior (manual CLI only).
+     */
+    autoRouteOut?: boolean;
+    /**
+     * planning-68: spread agents' nightly runs across a window instead of all
+     * firing at `dreamHour:00`. A deterministic per-agent jitter in
+     * `[0, staggerWindowMinutes*60s)` is added to the scheduled delay. Default 30;
+     * clamped to `[0,55]` so the offset never crosses the next hour. 0 = disabled.
+     */
+    staggerWindowMinutes?: number;
+    staleness?: StalenessConfig;
+}
+/** Fully-resolved config (defaults applied, timezone normalized). */
+export interface ResolvedDreamingCfg {
+    enabled: boolean;
+    mode: DreamMode;
+    dreamHour: number;
+    dreamMinute: number;
+    dreamTimezone: string;
+    quietMinutes: number;
+    lookbackDays: number;
+    maxChangesPerRun: number;
+    reviewModel: string;
+    promotionThreshold: number;
+    minRecallCount: number;
+    autoRouteOut: boolean;
+    staggerWindowMinutes: number;
+    staleness: ResolvedStalenessCfg;
+}
+/** One proposed memory-consolidation op (never applied in propose mode). */
+export interface DreamProposal {
+    op: DreamOpKind;
+    /**
+     * Target evergreen file for a `durable` op. Omitted for `episodic` ops, which
+     * route by `topic` into `memory/<topic>.md` instead.
+     */
+    file?: DreamFile;
+    /** Tier this op writes to; absent ⇒ 'durable' (back-compat). */
+    tier?: DreamTier;
+    /** For `episodic` ops: the `memory/<topic>.md` slug (`^[a-z0-9-]{1,64}$`). */
+    topic?: string;
+    /** Substring anchor for `replace`/`remove`. */
+    target?: string;
+    /** New text for `add`/`replace`. */
+    content?: string;
+    reason: string;
+    score: number;
+    recallCount: number;
+}
+export interface DreamReviewResult {
+    summary: string;
+    proposals: DreamProposal[];
+    /** Tokens the reviewer spent (input+output), for the net-token ledger. 0 if unknown. */
+    tokensSpent: number;
+    timedOut?: boolean;
+    /**
+     * Diagnostics (#353) for a failed run: WHY the reviewer produced no usable
+     * output (e.g. 'timeout', 'spawn-error: …', 'nonzero-exit:1', 'spawn-throw: …')
+     * and a bounded tail of the child's stderr (an API error such as
+     * overloaded_error). Absent on success. Logged by dreamOnce so an
+     * `outcome=error` run is debuggable instead of opaque.
+     */
+    failureReason?: string;
+    stderrTail?: string;
+}
+export type DreamOutcome = 'proposed' | 'no-changes' | 'skipped-disabled' | 'skipped-quiet' | 'skipped-empty' | 'error';
+export interface DreamRunResult {
+    outcome: DreamOutcome;
+    proposalCount: number;
+    tokensSpent: number;
+    mode: DreamMode;
+    /** Ops actually applied to memory (auto mode only; 0 in propose mode). */
+    appliedCount?: number;
+    /** Terminal-state entries the deterministic compactor archived (auto mode; #337). */
+    compactedCount?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/dreaming/types.d.ts.map

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

package/dist/agent/dreaming/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Types for nightly memory "dreaming" (issue #325, Part C).
+ *
+ * P2 slice = `propose` (dry-run) only: a print-only reviewer proposes memory
+ * consolidation ops which are written to a DREAMS.md diary + JSONL audit — the
+ * gateway mutates NO memory file. `auto` mode (applying ops) is a P3 follow-up.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/agent/dreaming/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agent/dreaming/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/agent/knowledge/archive-db.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Per-agent knowledge archive — SQLite/FTS5 substrate (planning-64 K0).
+ *
+ * One `kb.sqlite` per agent, alongside `history.db`. Backed by `node:sqlite`
+ * `DatabaseSync` (zero new dependency — the same substrate `src/history/db.ts`
+ * uses, which already runs FTS5). Schema adapted from openclaw memory-core,
+ * trimmed for v1 (FTS5-only; no vector table yet).
+ *
+ * IMPORTANT: `DatabaseSync` is synchronous. Every method here blocks. Callers
+ * MUST run indexing/queries OFF the gateway event loop (the nightly dreaming
+ * spawn or an out-of-process tool) — never on the HTTP read path (#277 lesson).
+ * K0 ships this as dormant infrastructure; no gateway runtime path calls it yet.
+ */
+import type { ArchiveChunkRow, ArchiveProvenanceRow, ArchiveRecallRow, ArchiveSourceRow } from './types';
+/** A chunk plus its recall + provenance metadata, ready to persist. */
+export interface ChunkWithMeta {
+    chunk: ArchiveChunkRow;
+    recall: ArchiveRecallRow;
+    provenance: ArchiveProvenanceRow;
+    /**
+     * Stable, reindex-surviving identity of the archive ENTRY (markdown block) this
+     * chunk belongs to (planning-66). `null` for content outside any entry block
+     * (evergreen prose, section headers). Keyed to `kb_entry_lifecycle`.
+     */
+    entryHash?: string | null;
+}
+/** One archive-entry lifecycle row (planning-66), joined with its max importance. */
+export interface LifecycleRow {
+    entryHash: string;
+    path: string;
+    firstSeen: number;
+    lastRetrieved: number | null;
+    retrievalCount: number;
+    supersededBy: string | null;
+    invalidAt: number | null;
+    /** MAX importance across the chunks carrying this entry_hash (null = none set). */
+    importance: number | null;
+}
+export declare class ArchiveDB {
+    private readonly db;
+    private readonly dbPath;
+    private readonly tokenizer;
+    private readonly stmts;
+    private constructor();
+    static forPath(dbPath: string, tokenizer?: string): ArchiveDB;
+    static evict(dbPath: string): void;
+    private _initSchema;
+    /** Look up an indexed source by its workspace-relative path. */
+    getSource(relPath: string): ArchiveSourceRow | undefined;
+    /**
+     * Replace a file's index atomically: delete its old chunks, upsert the source
+     * row, insert the fresh chunks (+ recall + provenance), then upsert the entry
+     * lifecycle rows for ALL of the file's blocks. Runs in a transaction so a
+     * failure never leaves a half-indexed file.
+     *
+     * `entryBlocks` (planning-66) is the FULL set of archive-entry blocks in the file
+     * — one lifecycle row each — NOT derived from chunks: a single FTS chunk can span
+     * several blocks, so per-chunk upsert would miss the inner ones. Empty for
+     * non-archive-tier files (evergreen/pinned/shared get no lifecycle).
+     */
+    replaceSource(source: Omit<ArchiveSourceRow, 'id'>, chunks: ChunkWithMeta[], entryBlocks?: Array<{
+        entryHash: string;
+        firstSeen: number;
+    }>): void;
+    /** Remove a source and all its chunks (file disappeared). */
+    deleteSource(relPath: string): void;
+    private _deleteChunksForPath;
+    /** All indexed source paths. */
+    listSourcePaths(): string[];
+    /** Current index revision (bumped on every mutation). */
+    getRevision(): number;
+    /** Total chunk count (test/introspection helper). */
+    chunkCount(): number;
+    /** Provenance row for a chunk (test/introspection helper). */
+    getProvenance(chunkId: string): ArchiveProvenanceRow | undefined;
+    /** Append a retrieval event (Node-side seed for tests + aggregation symmetry). */
+    logRetrieval(entryHash: string, retrievedAt: number): void;
+    /**
+     * Fold the append-only retrieval log into per-entry lifecycle: bump each entry's
+     * `last_retrieved` to the newest hit and add the hit count, then delete the
+     * folded rows (bounded by the max rowid read, so a concurrent append after this
+     * read survives to the next GC). Returns how many log rows were folded. A hit for
+     * an entry_hash no longer in lifecycle (its text changed → new hash) updates 0
+     * rows and is harmlessly dropped.
+     */
+    aggregateRetrievalLog(): number;
+    /** All lifecycle rows, joined with the MAX importance across their chunks. */
+    listLifecycle(): LifecycleRow[];
+    /** Read one lifecycle row (test/introspection helper). */
+    getLifecycle(entryHash: string): LifecycleRow | undefined;
+    /** Mark `entryHash` superseded by `bySpec` (or clear when null). */
+    setSuperseded(entryHash: string, bySpec: string | null): void;
+    /**
+     * Populate the (previously inert) provenance `supersedes_key` for every chunk of
+     * a superseded entry — so the search-side provenance reflects supersession too,
+     * not just the lifecycle table. Best-effort mirror of {@link setSuperseded}.
+     */
+    setSupersedesKeyForEntry(entryHash: string, key: string): void;
+    /** Stamp (soft-invalidate) or clear an entry's invalidation. */
+    stampInvalid(entryHash: string, invalidAt: number | null): void;
+    /**
+     * Keyword search over chunk text (FTS5 BM25). K0 helper for tests/introspection;
+     * the ranked, agent-facing `memory_search` tool is K1. Returns best matches
+     * first. Query tokens are quoted so punctuation can't inject FTS syntax.
+     */
+    search(query: string, limit?: number): ArchiveChunkRow[];
+    /**
+     * Close the handle AND drop it from the singleton cache, so a later
+     * `forPath(samePath)` opens a fresh handle instead of returning this closed one
+     * (whose statements would throw). Mirrors `evict()`.
+     */
+    close(): void;
+}
+//# sourceMappingURL=archive-db.d.ts.map

package/dist/agent/knowledge/archive-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-db.d.ts","sourceRoot":"","sources":["../../../src/agent/knowledge/archive-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAKjB,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,oBAAoB,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mFAAmF;IACnF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAQpB;IAEF,OAAO;IAuCP,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAc,GAAG,SAAS;IAMlE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlC,OAAO,CAAC,WAAW;IAiInB,gEAAgE;IAChE,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAaxD;;;;;;;;;;OAUG;IACH,aAAa,CACX,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,EACpC,MAAM,EAAE,aAAa,EAAE,EACvB,WAAW,GAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAM,GAChE,IAAI;IA8CP,6DAA6D;IAC7D,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAmBnC,OAAO,CAAC,oBAAoB;IAK5B,gCAAgC;IAChC,eAAe,IAAI,MAAM,EAAE;IAK3B,yDAAyD;IACzD,WAAW,IAAI,MAAM;IAOrB,qDAAqD;IACrD,UAAU,IAAI,MAAM;IAKpB,8DAA8D;IAC9D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAehE,kFAAkF;IAClF,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAM1D;;;;;;;OAOG;IACH,qBAAqB,IAAI,MAAM;IAsC/B,8EAA8E;IAC9E,aAAa,IAAI,YAAY,EAAE;IAsB/B,0DAA0D;IAC1D,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIzD,oEAAoE;IACpE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAM7D;;;;OAIG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAS9D,gEAAgE;IAChE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAO/D;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,eAAe,EAAE;IAwBpD;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAId"}