@0xmaxma/claude-gateway 1.6.8 → 1.7.0

package/dist/agent/dreaming/episodic.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Episodic note writer (planning-65) — routes task-log OUT of the injected core
+ * (MEMORY.md) into the searchable `memory/<topic>.md` archive tier.
+ *
+ * MEMORY.md is injected into every prompt (expensive); episodic records of "what
+ * happened" belong in `memory/*.md`, which the knowledge indexer already walks
+ * (`indexer.ts` → `walkMarkdown('memory')`) so the note stays retrievable via
+ * `memory_search` — recall is preserved, the prompt stays small.
+ *
+ * Security: the transcript that drives the dreaming reviewer is untrusted
+ * (prompt-injection surface), so the topic slug is validated against a strict
+ * regex AND the resolved path is realpath-confined under `<ws>/<episodicDir>/`.
+ * A topic that fails validation or escapes the directory is rejected — never
+ * written. Append-only (a dated bullet); never rewrites existing content, so it
+ * cannot destroy prior notes.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EPISODIC_DIR = exports.EPISODIC_SLUG_RE = void 0;
+exports.isValidTopicSlug = isValidTopicSlug;
+exports.resolveEpisodicPath = resolveEpisodicPath;
+exports.appendEpisodicNote = appendEpisodicNote;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Lowercase-kebab slug, 1..64 chars. No slashes/dots ⇒ cannot escape the dir. */
+exports.EPISODIC_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_SLUG_LEN = 64;
+/** Default episodic archive directory (relative to the agent workspace). */
+exports.DEFAULT_EPISODIC_DIR = 'memory';
+function isValidTopicSlug(topic) {
+    return (typeof topic === 'string' &&
+        topic.length >= 1 &&
+        topic.length <= MAX_SLUG_LEN &&
+        exports.EPISODIC_SLUG_RE.test(topic));
+}
+/**
+ * Resolve `<ws>/<episodicDir>/<topic>.md`, confined under `<ws>/<episodicDir>`.
+ * Returns null for an invalid slug or any path that would escape the base dir
+ * (defense-in-depth on top of the slug regex).
+ */
+function resolveEpisodicPath(workspaceDir, episodicDir, topic) {
+    if (!isValidTopicSlug(topic))
+        return null;
+    const baseDir = path.resolve(workspaceDir, episodicDir);
+    const target = path.resolve(baseDir, `${topic}.md`);
+    const rel = path.relative(baseDir, target);
+    // Must be a direct child file `<topic>.md` — no separators, no `..`, not absolute.
+    if (rel !== `${topic}.md` || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    return target;
+}
+/**
+ * Append a dated bullet to `memory/<topic>.md` (creating dir + file on first
+ * write). One entry per line — internal newlines are collapsed so a note stays a
+ * single searchable bullet. Never throws; a rejected/failed write returns
+ * `ok:false` and touches nothing.
+ */
+function appendEpisodicNote(workspaceDir, episodicDir, topic, content, now) {
+    const fail = { topic: String(topic ?? ''), path: '', ok: false, bytesAppended: 0 };
+    const abs = resolveEpisodicPath(workspaceDir, episodicDir, topic);
+    if (!abs)
+        return fail;
+    const text = (content ?? '').trim();
+    if (!text)
+        return fail;
+    try {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        const date = new Date(now).toISOString().slice(0, 10);
+        const existing = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
+        const header = existing
+            ? ''
+            : `# ${topic}\n\nEpisodic task-log routed out of MEMORY.md (planning-65). Searchable via \`memory_search\`.\n\n`;
+        const bullet = `- [${date}] ${text.replace(/\s*\n\s*/g, ' ')}`;
+        const sep = existing && !existing.endsWith('\n') ? '\n' : '';
+        const payload = `${header}${sep}${bullet}\n`;
+        fs.appendFileSync(abs, payload, 'utf8');
+        return { topic, path: abs, ok: true, bytesAppended: payload.length };
+    }
+    catch {
+        return fail;
+    }
+}
+//# sourceMappingURL=episodic.js.map

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

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

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

@@ -0,0 +1,31 @@
+/**
+ * Gather the lookback transcript slice for a dream run from the agent's own
+ * HistoryDB. Read-only; bounded in size. Best-effort — DB errors degrade to an
+ * empty slice rather than throwing (the daemon must never wedge on a dream).
+ */
+import type { ResolvedDreamingCfg } from './types';
+/** The subset of HistoryDB the dreamer reads (injectable for tests). */
+export interface DreamHistoryDb {
+    listSessions(chatId?: string): Array<{
+        sessionId: string;
+        lastActivity: number;
+    }>;
+    getSessionTranscript(sessionId: string, limit?: number): Array<{
+        role: string;
+        content: string;
+        ts: number;
+    }>;
+}
+export interface GatherResult {
+    transcript: string;
+    sessionCount: number;
+    /** Most recent activity across ALL sessions (ms), 0 if none. For the quiet-window check. */
+    lastActivityMs: number;
+}
+/**
+ * Build the transcript slice for sessions active within the lookback window.
+ * Sessions are ordered oldest→newest; if the concatenation exceeds the char
+ * cap, the most-recent tail is kept.
+ */
+export declare function gatherTranscript(db: DreamHistoryDb, cfg: ResolvedDreamingCfg, now: number): GatherResult;
+//# sourceMappingURL=gather.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../../../src/agent/dreaming/gather.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/G;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAsCxG"}

package/dist/agent/dreaming/gather.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Gather the lookback transcript slice for a dream run from the agent's own
+ * HistoryDB. Read-only; bounded in size. Best-effort — DB errors degrade to an
+ * empty slice rather than throwing (the daemon must never wedge on a dream).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherTranscript = gatherTranscript;
+const PER_SESSION_LIMIT = 200;
+const MAX_TRANSCRIPT_CHARS = 40000;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Build the transcript slice for sessions active within the lookback window.
+ * Sessions are ordered oldest→newest; if the concatenation exceeds the char
+ * cap, the most-recent tail is kept.
+ */
+function gatherTranscript(db, cfg, now) {
+    const cutoff = now - cfg.lookbackDays * MS_PER_DAY;
+    let sessions;
+    try {
+        sessions = db.listSessions();
+    }
+    catch {
+        return { transcript: '', sessionCount: 0, lastActivityMs: 0 };
+    }
+    const lastActivityMs = sessions.reduce((max, s) => Math.max(max, s.lastActivity ?? 0), 0);
+    const recent = sessions
+        .filter((s) => (s.lastActivity ?? 0) >= cutoff)
+        .sort((a, b) => (a.lastActivity ?? 0) - (b.lastActivity ?? 0));
+    if (recent.length === 0) {
+        return { transcript: '', sessionCount: 0, lastActivityMs };
+    }
+    const blocks = [];
+    for (const s of recent) {
+        let rows;
+        try {
+            rows = db.getSessionTranscript(s.sessionId, PER_SESSION_LIMIT);
+        }
+        catch {
+            rows = [];
+        }
+        const text = rows
+            .map((r) => `${r.role}: ${r.content}`)
+            .join('\n')
+            .trim();
+        if (text)
+            blocks.push(`<session id="${s.sessionId}">\n${text}\n</session>`);
+    }
+    let transcript = blocks.join('\n\n');
+    if (transcript.length > MAX_TRANSCRIPT_CHARS) {
+        transcript = transcript.slice(transcript.length - MAX_TRANSCRIPT_CHARS);
+    }
+    return { transcript, sessionCount: blocks.length, lastActivityMs };
+}
+//# sourceMappingURL=gather.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gather.js","sourceRoot":"","sources":["../../../src/agent/dreaming/gather.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA0BH,4CAsCC;AA/CD,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAC9B,MAAM,oBAAoB,GAAG,KAAM,CAAC;AACpC,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvC;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,EAAkB,EAAE,GAAwB,EAAE,GAAW;IACxF,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,YAAY,GAAG,UAAU,CAAC;IACnD,IAAI,QAA4D,CAAC;IACjE,IAAI,CAAC;QACH,QAAQ,GAAG,EAAE,CAAC,YAAY,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,QAAQ;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC;SAC9C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC;IAEjE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7D,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,IAA0D,CAAC;QAC/D,IAAI,CAAC;YACH,IAAI,GAAG,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;QACjE,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,IAAI,GAAG,IAAI;aACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACrC,IAAI,CAAC,IAAI,CAAC;aACV,IAAI,EAAE,CAAC;QACV,IAAI,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,SAAS,OAAO,IAAI,cAAc,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,UAAU,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QAC7C,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,oBAAoB,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;AACrE,CAAC"}

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

@@ -0,0 +1,87 @@
+/**
+ * DreamingManager — nightly memory consolidation, propose (dry-run) slice.
+ *
+ * Orchestrates: gather lookback transcript → print-only reviewer proposes memory
+ * ops → write DREAMS.md diary + JSONL audit. In propose mode (the only mode
+ * implemented here) NO memory file is mutated. The `auto` applier is a P3
+ * follow-up; until it lands, `auto` behaves like `propose` (logs proposals only).
+ */
+import type { ClaudeSpawnFn } from '../skill-learning/reviewer';
+import { type DreamHistoryDb } from './gather';
+import type { DreamingConfig, DreamProposal, DreamRunResult, ResolvedDreamingCfg } from './types';
+export interface DreamingManagerDeps {
+    db: DreamHistoryDb;
+    agentId: string;
+    workspaceDir: string;
+    globalCfg?: DreamingConfig;
+    agentCfg?: DreamingConfig;
+    logger?: {
+        info: (msg: string, data?: Record<string, unknown>) => void;
+        warn?: (msg: string, data?: Record<string, unknown>) => void;
+    };
+    /** Injectable reviewer spawn for tests (defaults to a real print-only claude -p). */
+    spawnFn?: ClaudeSpawnFn;
+    /** Soft memory budgets for the K4 auto-applier's net-negative gate (defaults 8000/3000). */
+    memoryBudgetChars?: number;
+    userBudgetChars?: number;
+    /**
+     * planning-65 write routing. When true, the reviewer is told the two-tier
+     * contract and may emit episodic ops; `episodicArchiveDir` is where those
+     * `memory/<topic>.md` notes are written. When false/absent, durable-only
+     * (exact prior behavior).
+     */
+    writeRouting?: boolean;
+    episodicArchiveDir?: string;
+    /**
+     * planning-67: injected route-out classifier for the embedded auto-migrate
+     * stage. Given the current MEMORY.md, returns episodic-move proposals. The
+     * gateway wires it (reviewer-backed spawn) only when write routing is on;
+     * tests inject a stub. Absent ⇒ the stage is skipped (durable-only behavior).
+     */
+    routeOutFn?: (memory: string) => Promise<DreamProposal[]> | DreamProposal[];
+    /**
+     * Optional per-agent→shared promotion hook (K3↔K4). When provided (the gateway
+     * wires it only when the shared KB is enabled AND `shared.mode:auto`), each
+     * durable `add` the dream promotes is also contributed to the shared vault.
+     * Injected as a callback so the manager stays decoupled from shared-config
+     * resolution and is easy to test. Best-effort; must not throw.
+     */
+    sharedPromote?: (proposal: DreamProposal) => void;
+}
+/**
+ * Select which proposals to apply this run (#337). Under budget: the classic
+ * first-N cap. Over budget (overageFactor > 1): keep the non-shrink (add/grow)
+ * cap at `maxChanges`, but allow proportionally MORE shrink ops (remove /
+ * length-reducing replace) so an over-budget file converges instead of trickling
+ * at `maxChanges`/night. Capped at MAX_SHRINK_OPS_PER_RUN.
+ */
+export declare function selectProposals(proposals: DreamProposal[], maxChanges: number, overageFactor: number): DreamProposal[];
+/**
+ * planning-68 — deterministic per-agent jitter (ms) added to the nightly delay so
+ * agents don't all fire at `dreamHour:00` together (thundering herd → concurrent
+ * `claude -p` spawns). A stable string hash of `agentId` mapped into
+ * `[0, windowMinutes*60_000)`; NOT `Math.random`, so the offset is the same across
+ * reschedules and is unit-testable. Non-finite or `<= 0` window ⇒ 0 (feature off).
+ */
+export declare function agentJitterMs(agentId: string, windowMinutes: number): number;
+export declare class DreamingManager {
+    readonly cfg: ResolvedDreamingCfg;
+    private readonly deps;
+    private timer;
+    constructor(deps: DreamingManagerDeps);
+    private log;
+    /**
+     * Run one dream cycle. Never throws. In propose mode it writes only the diary
+     * + audit and mutates no memory file.
+     */
+    dreamOnce(now?: number): Promise<DreamRunResult>;
+    private audit;
+    /**
+     * Start the nightly dream scheduler (mirror `startCurator`): a self-rescheduling
+     * unref'd timer at `dreamHour` in `dreamTimezone`. Best-effort; never throws at
+     * boot (invalid tz already normalized to UTC in resolveDreamingConfig).
+     */
+    startDreaming(): void;
+    stop(): void;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/dreaming/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAOjE,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACb,cAAc,EACd,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,cAAc,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QAC5D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KAC9D,CAAC;IACF,qFAAqF;IACrF,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,4FAA4F;IAC5F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,GAAG,aAAa,EAAE,CAAC;IAC5E;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;CACnD;AAgBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,aAAa,EAAE,EAC1B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,aAAa,EAAE,CAiBjB;AAUD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAS5E;AAED,qBAAa,eAAe;IAC1B,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C,OAAO,CAAC,KAAK,CAA4C;gBAE7C,IAAI,EAAE,mBAAmB;IAKrC,OAAO,CAAC,GAAG;IAIX;;;OAGG;IACG,SAAS,CAAC,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IA+MlE,OAAO,CAAC,KAAK;IAuBb;;;;OAIG;IACH,aAAa,IAAI,IAAI;IAsBrB,IAAI,IAAI,IAAI;CAGb"}