gnosys 5.11.4 → 5.12.0

package/dist/lib/dreamCommand.js

@@ -0,0 +1,195 @@
+import { GnosysResolver } from "./resolver.js";
+import { GnosysDB } from "./db.js";
+import { loadConfig } from "./config.js";
+import { acquireDreamLock, appendDreamRun, countChangedMemoriesSince, createSkipRunRecord, getSystemIdleMinutes, isInsideNightWindow, readDreamState, } from "./dreamRunLog.js";
+export async function runDreamCommand(opts) {
+    const resolver = new GnosysResolver();
+    await resolver.resolve();
+    const stores = resolver.getStores();
+    if (stores.length === 0) {
+        console.error("No Gnosys stores found. Run 'gnosys init' first.");
+        process.exit(1);
+    }
+    const { GnosysDB: DbClass } = await import("./db.js");
+    const { GnosysDreamEngine, formatDreamReport } = await import("./dream.js");
+    const { getMachineId } = await import("./remote.js");
+    const storePath = stores[0].path;
+    const cfg = await loadConfig(storePath);
+    const db = new DbClass(storePath);
+    if (!db.isAvailable() || !db.isMigrated()) {
+        console.error("Dream Mode requires gnosys.db (v2.0). Run 'gnosys migrate' first.");
+        process.exit(1);
+    }
+    const trigger = opts.scheduled ? "scheduled" : "manual";
+    const gates = [];
+    // Machine-level lock — only one dream may run per machine at a time.
+    const lock = acquireDreamLock();
+    if (!lock.acquired) {
+        appendDreamRun(createSkipRunRecord({
+            trigger,
+            startedAt: new Date().toISOString(),
+            provider: cfg.dream?.provider || "ollama",
+            model: cfg.dream?.model,
+            gates: [{ name: "lock", passed: false, reason: lock.reason }],
+            reason: lock.reason,
+        }));
+        if (!opts.scheduled)
+            console.error(lock.reason);
+        db.close();
+        if (!opts.scheduled)
+            process.exit(1);
+        return;
+    }
+    try {
+        // Designation gate — warn (and exit unless --force) if this isn't the
+        // designated dream machine. Manual runs from non-designated machines are
+        // useful for testing but shouldn't happen by accident on shared brains.
+        const centralDb = GnosysDB.openCentral();
+        let localId;
+        if (centralDb.isAvailable()) {
+            const designated = centralDb.getDreamMachineId();
+            localId = getMachineId(centralDb);
+            if (designated) {
+                if (designated !== localId && !opts.force) {
+                    const reason = `Dream is designated to machine ${designated}, but this is ${localId}.`;
+                    gates.push({ name: "designation", passed: false, reason, details: { designated, localId } });
+                    appendDreamRun(createSkipRunRecord({
+                        trigger,
+                        startedAt: new Date().toISOString(),
+                        provider: cfg.dream?.provider || "ollama",
+                        model: cfg.dream?.model,
+                        gates,
+                        reason,
+                        machineId: localId,
+                    }));
+                    if (!opts.scheduled) {
+                        console.error(`${reason}\nPass --force to run anyway, or run 'gnosys setup dream' to redesignate.`);
+                    }
+                    centralDb.close();
+                    db.close();
+                    if (!opts.scheduled)
+                        process.exit(1);
+                    return;
+                }
+                gates.push({ name: "designation", passed: true, details: { designated, localId } });
+            }
+            else if (opts.scheduled) {
+                const reason = "No designated dream machine.";
+                gates.push({ name: "designation", passed: false, reason });
+                appendDreamRun(createSkipRunRecord({
+                    trigger,
+                    startedAt: new Date().toISOString(),
+                    provider: cfg.dream?.provider || "ollama",
+                    model: cfg.dream?.model,
+                    gates,
+                    reason,
+                    machineId: localId,
+                }));
+                centralDb.close();
+                db.close();
+                return;
+            }
+            centralDb.close();
+        }
+        // Scheduled runs apply the cheap night/idle/dreamworthiness gates before
+        // touching the LLM. Manual runs skip these (explicit user intent).
+        if (opts.scheduled) {
+            const now = new Date();
+            if (!isInsideNightWindow(now, cfg.dream.schedule)) {
+                const reason = `Outside dream schedule (${cfg.dream.schedule.startHour}:00-${cfg.dream.schedule.endHour}:00).`;
+                gates.push({ name: "night-window", passed: false, reason, details: { hour: now.getHours() } });
+                appendDreamRun(createSkipRunRecord({ trigger, startedAt: now.toISOString(), provider: cfg.dream.provider, model: cfg.dream.model, gates, reason, machineId: localId }));
+                db.close();
+                return;
+            }
+            gates.push({ name: "night-window", passed: true, details: { hour: now.getHours() } });
+            const idleMinutes = getSystemIdleMinutes();
+            if (idleMinutes != null && idleMinutes < cfg.dream.systemIdleMinutes) {
+                const reason = `Machine idle ${idleMinutes.toFixed(1)}min < required ${cfg.dream.systemIdleMinutes}min.`;
+                gates.push({ name: "system-idle", passed: false, reason, details: { idleMinutes } });
+                appendDreamRun(createSkipRunRecord({ trigger, startedAt: now.toISOString(), provider: cfg.dream.provider, model: cfg.dream.model, gates, reason, machineId: localId }));
+                db.close();
+                return;
+            }
+            gates.push({ name: "system-idle", passed: true, details: { idleMinutes } });
+            const state = readDreamState();
+            const memories = db.getActiveMemories();
+            const changed = countChangedMemoriesSince(memories, state.lastMemoryMaxModified);
+            const lastRunMs = state.lastSuccessfulRunAt ? Date.parse(state.lastSuccessfulRunAt) : 0;
+            const hoursSince = lastRunMs ? (Date.now() - lastRunMs) / 3_600_000 : Infinity;
+            const enoughMemories = changed >= cfg.dream.minNewMemoriesToDream;
+            const enoughTime = hoursSince >= cfg.dream.minHoursBetweenRuns;
+            if (!enoughMemories || !enoughTime) {
+                const reason = `Not dreamworthy yet (${changed} changed memories, ${hoursSince === Infinity ? "never" : hoursSince.toFixed(1)}h since last run).`;
+                gates.push({
+                    name: "dreamworthiness",
+                    passed: false,
+                    reason,
+                    details: { changed, minChanged: cfg.dream.minNewMemoriesToDream, hoursSince, minHours: cfg.dream.minHoursBetweenRuns },
+                });
+                appendDreamRun(createSkipRunRecord({ trigger, startedAt: now.toISOString(), provider: cfg.dream.provider, model: cfg.dream.model, gates, reason, machineId: localId }));
+                db.close();
+                return;
+            }
+            gates.push({ name: "dreamworthiness", passed: true, details: { changed, hoursSince } });
+        }
+        const dreamConfig = {
+            enabled: true,
+            idleMinutes: 0,
+            maxRuntimeMinutes: opts.maxRuntime ? parseInt(opts.maxRuntime, 10) : 30,
+            selfCritique: opts.critique !== false,
+            generateSummaries: opts.summaries !== false,
+            discoverRelationships: opts.relationships !== false,
+            minMemories: 1,
+            provider: cfg.dream?.provider || "ollama",
+            model: cfg.dream?.model,
+            schedule: cfg.dream?.schedule,
+            systemIdleMinutes: cfg.dream?.systemIdleMinutes,
+            minNewMemoriesToDream: cfg.dream?.minNewMemoriesToDream,
+            minHoursBetweenRuns: cfg.dream?.minHoursBetweenRuns,
+            maxLLMCallsPerRun: cfg.dream?.maxLLMCallsPerRun,
+        };
+        console.error("Starting Dream Mode cycle...");
+        const engine = new GnosysDreamEngine(db, cfg, dreamConfig, { trigger, machineId: localId });
+        const report = await engine.dream((phase, detail) => {
+            console.error(`  [${phase}] ${detail}`);
+        });
+        appendDreamRun({
+            ...report,
+            id: report.id || `dream-${Date.now()}`,
+            trigger,
+            status: report.aborted ? "aborted" : report.errors.length > 0 ? "failed" : "completed",
+            machine: report.machine || { hostname: "unknown", machineId: localId },
+            provider: report.provider || dreamConfig.provider,
+            phases: report.phases || [],
+            llmCalls: report.llmCalls || [],
+            totals: report.totals || {
+                llmCallsMade: 0,
+                llmCallsSkipped: 0,
+                estimatedInputTokens: 0,
+                estimatedOutputTokens: 0,
+                estimatedCostUsd: 0,
+            },
+            effectiveness: report.effectiveness || {
+                usefulOutputScore: 0,
+                costPerUsefulOutput: null,
+                decaysApplied: report.decayUpdated,
+                summariesGenerated: report.summariesGenerated,
+                summariesUpdated: report.summariesUpdated,
+                reviewSuggestions: report.reviewSuggestions.length,
+                relationshipsDiscovered: report.relationshipsDiscovered,
+            },
+            gates,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatDreamReport(report));
+        }
+        db.close();
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/lib/dreamLaunchd.d.ts

@@ -0,0 +1,2 @@
+export declare function installDreamLaunchAgent(): string | null;
+export declare function uninstallDreamLaunchAgent(): string | null;

package/dist/lib/dreamLaunchd.js

@@ -0,0 +1,72 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+const LABEL = "com.gnosys.dream";
+function plistPath() {
+    return path.join(os.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export function installDreamLaunchAgent() {
+    if (process.platform !== "darwin")
+        return null;
+    const file = plistPath();
+    const nodePath = process.execPath;
+    const cliPath = process.argv[1] || "gnosys";
+    const logPath = path.join(os.tmpdir(), "gnosys-dream.log");
+    const pathEnv = `${path.dirname(nodePath)}:/usr/local/bin:/usr/bin:/bin`;
+    const body = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(nodePath)}</string>
+    <string>${xmlEscape(cliPath)}</string>
+    <string>dream</string>
+    <string>run</string>
+    <string>--scheduled</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <array>
+    <dict><key>Hour</key><integer>2</integer><key>Minute</key><integer>0</integer></dict>
+    <dict><key>Hour</key><integer>3</integer><key>Minute</key><integer>0</integer></dict>
+    <dict><key>Hour</key><integer>4</integer><key>Minute</key><integer>0</integer></dict>
+  </array>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${xmlEscape(os.homedir())}</string>
+    <key>PATH</key>
+    <string>${xmlEscape(pathEnv)}</string>
+  </dict>
+</dict>
+</plist>
+`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, body, "utf8");
+    return file;
+}
+export function uninstallDreamLaunchAgent() {
+    if (process.platform !== "darwin")
+        return null;
+    const file = plistPath();
+    try {
+        fs.unlinkSync(file);
+    }
+    catch {
+        // Missing is already uninstalled.
+    }
+    return file;
+}

package/dist/lib/dreamLogCommand.d.ts

@@ -0,0 +1,10 @@
+export type DreamLogOptions = {
+    last: string;
+    since?: string;
+    failuresOnly?: boolean;
+    json?: boolean;
+};
+export type DreamLogContext = {
+    parentJson?: boolean;
+};
+export declare function runDreamLogCommand(opts: DreamLogOptions, context?: DreamLogContext): Promise<void>;

package/dist/lib/dreamLogCommand.js

@@ -0,0 +1,58 @@
+import { GnosysDB } from "./db.js";
+export async function runDreamLogCommand(opts, context = {}) {
+    let centralDb = null;
+    try {
+        centralDb = GnosysDB.openCentral();
+        if (!centralDb.isAvailable()) {
+            console.error("Central DB not available.");
+            process.exitCode = 1;
+            return;
+        }
+        const limit = Math.max(1, parseInt(opts.last) || 20);
+        const sinceIso = opts.since ? `${opts.since}T00:00:00Z` : undefined;
+        const runs = centralDb.getRecentDreamRuns(limit, {
+            failuresOnly: !!opts.failuresOnly,
+            sinceIso,
+        });
+        const wantJson = !!opts.json || !!context.parentJson;
+        // JSON path always emits a structured response — including empty runs.
+        if (wantJson) {
+            console.log(JSON.stringify({ count: runs.length, runs }, null, 2));
+            return;
+        }
+        if (runs.length === 0) {
+            console.log("No dream runs recorded.");
+            return;
+        }
+        const DIM = "\x1b[2m";
+        const RESET = "\x1b[0m";
+        const RED = "\x1b[31m";
+        const GREEN = "\x1b[32m";
+        console.log(`${runs.length} dream run(s):\n`);
+        for (const r of runs) {
+            const d = r.details;
+            const dur = r.durationMs != null ? `${(r.durationMs / 1000).toFixed(1)}s` : "—";
+            const summaries = Number(d.summariesGenerated || 0);
+            const decays = Number(d.decayUpdated || 0);
+            const reviews = Number(d.reviewSuggestions || 0);
+            const rels = Number(d.relationshipsDiscovered || 0);
+            const errors = Number(d.errors || 0);
+            const unreachable = Boolean(d.providerUnreachable);
+            const status = unreachable
+                ? `${RED}provider unreachable${RESET}`
+                : errors > 0
+                    ? `${RED}${errors} error(s)${RESET}`
+                    : summaries + decays + rels > 0
+                        ? `${GREEN}did work${RESET}`
+                        : `${DIM}no LLM work${RESET}`;
+            console.log(`  ${r.completed} ${DIM}(${dur})${RESET} ${status}`);
+            console.log(`    decays=${decays} summaries=${summaries} reviews=${reviews} relations=${rels}`);
+            if (d.provider) {
+                console.log(`    ${DIM}provider=${d.provider}${d.model ? "/" + d.model : ""}${RESET}`);
+            }
+        }
+    }
+    finally {
+        centralDb?.close();
+    }
+}

package/dist/lib/dreamReport.d.ts

@@ -0,0 +1,7 @@
+import { type DreamRunRecord } from "./dreamRunLog.js";
+export interface DreamReportOptions {
+    output?: string;
+    last?: string;
+}
+export declare function generateDreamDashboardHtml(runs: DreamRunRecord[]): string;
+export declare function runDreamReportCommand(opts: DreamReportOptions): Promise<void>;

package/dist/lib/dreamReport.js

@@ -0,0 +1,114 @@
+import fs from "fs";
+import path from "path";
+import { readDreamRuns } from "./dreamRunLog.js";
+function escapeHtml(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function fmtMoney(value) {
+    return `$${value.toFixed(value < 0.01 ? 4 : 2)}`;
+}
+function sum(runs, fn) {
+    return runs.reduce((total, run) => total + fn(run), 0);
+}
+function bar(value, max) {
+    const width = max <= 0 ? 0 : Math.max(2, Math.round((value / max) * 100));
+    return `<div class="bar"><span style="width:${width}%"></span></div>`;
+}
+export function generateDreamDashboardHtml(runs) {
+    const sorted = [...runs].sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+    const completed = sorted.filter((r) => r.status === "completed");
+    const totalCost = sum(sorted, (r) => r.totals.estimatedCostUsd);
+    const totalCalls = sum(sorted, (r) => r.totals.llmCallsMade);
+    const totalSkippedCalls = sum(sorted, (r) => r.totals.llmCallsSkipped);
+    const totalUseful = sum(sorted, (r) => r.effectiveness.usefulOutputScore);
+    const maxUseful = Math.max(1, ...sorted.map((r) => r.effectiveness.usefulOutputScore));
+    const maxCost = Math.max(0.000001, ...sorted.map((r) => r.totals.estimatedCostUsd));
+    const rows = sorted.map((run) => {
+        const phaseSummary = run.phases
+            .map((p) => `${p.name}: ${p.status}, ${p.memoryIdsTouched.length} memories, ${p.llmCallsMade}/${p.llmCallsSkipped} calls`)
+            .join("; ");
+        const gateSummary = run.gates
+            .map((g) => `${g.name}: ${g.passed ? "pass" : "skip"}${g.reason ? ` (${g.reason})` : ""}`)
+            .join("; ");
+        return `<tr>
+      <td>${escapeHtml(run.startedAt)}</td>
+      <td><span class="pill ${escapeHtml(run.status)}">${escapeHtml(run.status)}</span></td>
+      <td>${escapeHtml(run.trigger)}</td>
+      <td>${escapeHtml(run.provider)}${run.model ? `/${escapeHtml(run.model)}` : ""}</td>
+      <td>${(run.durationMs / 1000).toFixed(1)}s</td>
+      <td>${run.totals.llmCallsMade}</td>
+      <td>${run.totals.llmCallsSkipped}</td>
+      <td>${fmtMoney(run.totals.estimatedCostUsd)}</td>
+      <td>${run.effectiveness.usefulOutputScore}</td>
+      <td title="${escapeHtml(gateSummary)}">${escapeHtml(run.skipReason || phaseSummary || gateSummary || "—")}</td>
+    </tr>`;
+    }).join("\n");
+    const chartRows = sorted.slice(0, 30).map((run) => `<div class="runChart">
+    <div class="date">${escapeHtml(run.startedAt.slice(0, 16).replace("T", " "))}</div>
+    <div>${bar(run.effectiveness.usefulOutputScore, maxUseful)}</div>
+    <div>${bar(run.totals.estimatedCostUsd, maxCost)}</div>
+  </div>`).join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Gnosys Dream Dashboard</title>
+  <style>
+    :root { color-scheme: light dark; --border: #8b949e55; --muted: #8b949e; --bg2: #8b949e18; }
+    body { font: 14px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 32px; }
+    h1, h2 { margin: 0 0 12px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; margin: 20px 0; }
+    .card { border: 1px solid var(--border); border-radius: 12px; padding: 16px; background: var(--bg2); }
+    .metric { font-size: 28px; font-weight: 700; }
+    .label { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: .06em; }
+    table { width: 100%; border-collapse: collapse; margin-top: 16px; }
+    th, td { border-bottom: 1px solid var(--border); padding: 8px; text-align: left; vertical-align: top; }
+    th { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: .04em; }
+    .pill { border: 1px solid var(--border); border-radius: 999px; padding: 2px 8px; }
+    .completed { color: #2da44e; }
+    .skipped { color: #bf8700; }
+    .failed, .aborted { color: #cf222e; }
+    .runChart { display: grid; grid-template-columns: 160px 1fr 1fr; gap: 10px; align-items: center; margin: 7px 0; }
+    .date { color: var(--muted); font-size: 12px; }
+    .bar { height: 10px; border-radius: 999px; background: var(--bg2); overflow: hidden; }
+    .bar span { display: block; height: 100%; background: currentColor; opacity: .65; }
+    .hint { color: var(--muted); }
+  </style>
+</head>
+<body>
+  <h1>Gnosys Dream Dashboard</h1>
+  <p class="hint">Generated from <code>~/.gnosys/dream-runs.jsonl</code>. Useful output is a weighted score: decay=1, summary generated=5, summary updated=3, relationship=2.</p>
+  <section class="grid">
+    <div class="card"><div class="label">Runs</div><div class="metric">${sorted.length}</div></div>
+    <div class="card"><div class="label">Completed</div><div class="metric">${completed.length}</div></div>
+    <div class="card"><div class="label">LLM Calls</div><div class="metric">${totalCalls}</div><div class="hint">${totalSkippedCalls} skipped</div></div>
+    <div class="card"><div class="label">Estimated Cost</div><div class="metric">${fmtMoney(totalCost)}</div></div>
+    <div class="card"><div class="label">Useful Output</div><div class="metric">${totalUseful}</div></div>
+  </section>
+
+  <h2>Recent Runs</h2>
+  <div class="runChart"><div></div><div class="label">Useful output</div><div class="label">Cost</div></div>
+  ${chartRows || "<p>No dream runs logged yet.</p>"}
+
+  <h2>Run Details</h2>
+  <table>
+    <thead>
+      <tr><th>Started</th><th>Status</th><th>Trigger</th><th>Model</th><th>Duration</th><th>Calls</th><th>Skipped</th><th>Cost</th><th>Useful</th><th>Notes</th></tr>
+    </thead>
+    <tbody>${rows}</tbody>
+  </table>
+</body>
+</html>`;
+}
+export async function runDreamReportCommand(opts) {
+    const limit = opts.last ? Math.max(1, parseInt(opts.last, 10) || 100) : undefined;
+    const runs = readDreamRuns({ limit });
+    const output = path.resolve(opts.output || "dream-dashboard.html");
+    fs.writeFileSync(output, generateDreamDashboardHtml(runs), "utf8");
+    console.log(`Wrote ${output}`);
+}

package/dist/lib/dreamRunLog.d.ts

@@ -0,0 +1,121 @@
+import type { DbMemory } from "./db.js";
+import type { DreamConfig } from "./config.js";
+export type DreamTrigger = "manual" | "scheduled";
+export type DreamRunStatus = "completed" | "skipped" | "aborted" | "failed";
+export interface DreamRunGateResult {
+    name: "designation" | "night-window" | "system-idle" | "dreamworthiness" | "lock";
+    passed: boolean;
+    reason?: string;
+    details?: Record<string, unknown>;
+}
+export interface DreamRunPhaseRecord {
+    name: "decay" | "critique" | "summaries" | "relationships";
+    status: "ran" | "skipped";
+    reason?: string;
+    durationMs: number;
+    memoryIdsTouched: string[];
+    llmCallsMade: number;
+    llmCallsSkipped: number;
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    estimatedCostUsd: number;
+}
+export interface DreamLLMCallRecord {
+    phase: DreamRunPhaseRecord["name"];
+    label: string;
+    status: "made" | "skipped" | "failed";
+    reason?: string;
+    model: string;
+    provider: string;
+    memoryIds: string[];
+    fingerprint?: string;
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    estimatedCostUsd: number;
+}
+export interface DreamEffectivenessRecord {
+    usefulOutputScore: number;
+    costPerUsefulOutput: number | null;
+    decaysApplied: number;
+    summariesGenerated: number;
+    summariesUpdated: number;
+    reviewSuggestions: number;
+    relationshipsDiscovered: number;
+}
+export interface DreamRunRecord {
+    id: string;
+    trigger: DreamTrigger;
+    status: DreamRunStatus;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    machine: {
+        hostname: string;
+        machineId?: string;
+    };
+    provider: string;
+    model?: string;
+    gates: DreamRunGateResult[];
+    phases: DreamRunPhaseRecord[];
+    llmCalls: DreamLLMCallRecord[];
+    totals: {
+        llmCallsMade: number;
+        llmCallsSkipped: number;
+        estimatedInputTokens: number;
+        estimatedOutputTokens: number;
+        estimatedCostUsd: number;
+    };
+    effectiveness: DreamEffectivenessRecord;
+    errors: string[];
+    skipReason?: string;
+}
+export interface DreamState {
+    lastRunAt?: string;
+    lastSuccessfulRunAt?: string;
+    lastMemoryMaxModified?: string;
+    lastMemoryCount?: number;
+    analyzedFingerprints: Record<string, {
+        kind: "summary" | "critique" | "relationship";
+        lastAnalyzedAt: string;
+        memoryIds: string[];
+    }>;
+}
+export interface DreamReadOptions {
+    limit?: number;
+    sinceIso?: string;
+    status?: DreamRunStatus;
+}
+export declare function getDreamRunsPath(): string;
+export declare function getDreamStatePath(): string;
+export declare function getDreamLockPath(): string;
+export declare function acquireDreamLock(): {
+    acquired: true;
+    release: () => void;
+} | {
+    acquired: false;
+    reason: string;
+};
+export declare function estimateTokens(text: string): number;
+export declare function estimateCost(model: string | undefined, inputTokens: number, outputTokens: number): number;
+export declare function readDreamState(): DreamState;
+export declare function writeDreamState(state: DreamState): void;
+export declare function appendDreamRun(record: DreamRunRecord): void;
+export declare function readDreamRuns(opts?: DreamReadOptions): DreamRunRecord[];
+export declare function fingerprintMemories(kind: "summary" | "critique" | "relationship", memories: DbMemory[]): string;
+export declare function memoryWatermark(memories: DbMemory[]): {
+    count: number;
+    maxModified: string | undefined;
+};
+export declare function countChangedMemoriesSince(memories: DbMemory[], sinceIso?: string): number;
+export declare function isInsideNightWindow(now: Date, schedule: DreamConfig["schedule"]): boolean;
+export declare function getSystemIdleMinutes(): number | null;
+export declare function createSkipRunRecord(input: {
+    trigger: DreamTrigger;
+    startedAt: string;
+    finishedAt?: string;
+    provider: string;
+    model?: string;
+    gates: DreamRunGateResult[];
+    reason: string;
+    machineId?: string;
+}): DreamRunRecord;