@letta-ai/dreams 0.0.3 → 0.0.4

package/dist/cli.js

@@ -2,6 +2,8 @@
 /** @letta-ai/dreams command-line entry point. */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
+// Must be first: filters node:sqlite ExperimentalWarning before other imports load it.
+require("./suppress-sqlite-warning");
 const index_1 = require("./auth/index");
 const commands_1 = require("./auth/commands");
 const development_reset_1 = require("./development-reset");
@@ -15,6 +17,7 @@ const snapshots_1 = require("./snapshots");
 const skill_1 = require("./skill");
 const store_1 = require("./store");
 const backfill_1 = require("./local/backfill");
+const hooks_install_1 = require("./local/hooks-install");
 const sync_1 = require("./sync");
 const version_1 = require("./version");
 const USAGE = `Usage: dreams <command> [options]
@@ -28,12 +31,15 @@ Commands:
   auth logout                Revoke Dreams' refresh token and clear stored credentials
   dev reset local            Preview/reset local SQLite and blob state
   dev reset identity         Preview/reset local state, credentials, and device identity
-  source detect              Detect Claude Code and register a detected Cloud source
-  source scan                Discover Claude Code sessions and build the local upload queue
-  source approve-root <path> Approve a work root so its transcripts become eligible
-  source list                Show local sources, approved roots, and the pending queue
+  source detect              Detect a harness and register a detected Cloud source
+  source scan                Discover sessions and build the local upload queue
+  source approve-root <path> Approve a work directory so its transcripts become eligible
+  source approve-dir <path>  Alias for approve-root (preferred user-facing name)
+  source list                Show local sources, approved directories, and the pending queue
   snapshots create           Submit a skill-authored snapshot JSON file to Cloud
-  sync                       Schedule a hook-safe sync worker (live then active backfill)
+  hooks install              Install or preview harness live-sync hooks (Claude/Codex)
+  wake                       SessionStart housekeeping + kick pending sync/backfill
+  sync                       Schedule a live-turn sync worker (Stop hook; then active backfill)
   sync pause|resume|status   Pause/resume hooks or show sync diagnostics
   backfill start             Queue a bounded historical backfill window (local only)
   upload                     Upload pending queued objects to Letta Cloud
@@ -41,8 +47,9 @@ Commands:
 Options:
   --json                 Machine-readable JSON output
   --confirm              Apply a development reset preview
+  --dry-run              Preview hooks install without writing files
   --force                Bypass sync cadence (never bypasses pause/privacy)
-  --source <type>        Sync source adapter (claude-code default; codex)
+  --source <type>        Source adapter (claude-code default; codex) for sync/wake, source detect/scan, upload, backfill, hooks install
   --since <RFC3339>      Backfill window start (with backfill start)
   --type <type>          Snapshot type (with snapshots create)
   --file <path>          Snapshot JSON file (with snapshots create)
@@ -51,12 +58,13 @@ Options:
   --version              Print the CLI version
   --help                 Show this help
 `;
-const COMMANDS_WITH_SUBCOMMANDS = new Set(["auth", "dev", "source", "snapshots", "sync", "backfill"]);
+const COMMANDS_WITH_SUBCOMMANDS = new Set(["auth", "dev", "source", "snapshots", "sync", "backfill", "hooks"]);
 function parseArgs(argv) {
     const parsed = {
         positionals: [],
         json: false,
         confirm: false,
+        dryRun: false,
         help: false,
         version: false,
         force: false,
@@ -75,6 +83,8 @@ function parseArgs(argv) {
             parsed.json = true;
         else if (arg === "--confirm")
             parsed.confirm = true;
+        else if (arg === "--dry-run")
+            parsed.dryRun = true;
         else if (arg === "--force")
             parsed.force = true;
         else if (arg === "--worker")
@@ -257,8 +267,18 @@ async function runCli() {
         process.stderr.write(`--force/--worker are only valid with \`dreams sync\`\n\n${USAGE}`);
         return 1;
     }
-    if (args.source && command !== "sync") {
-        process.stderr.write(`--source is only valid with \`dreams sync\`\n\n${USAGE}`);
+    if (args.dryRun && command !== "hooks") {
+        process.stderr.write(`--dry-run is only valid with \`dreams hooks install\`\n\n${USAGE}`);
+        return 1;
+    }
+    if (args.source &&
+        command !== "sync" &&
+        command !== "wake" &&
+        command !== "upload" &&
+        command !== "hooks" &&
+        !(command === "source" && (subcommand === "detect" || subcommand === "scan")) &&
+        !(command === "backfill" && subcommand === "start")) {
+        process.stderr.write(`--source is only valid with \`dreams sync\`, \`dreams wake\`, \`dreams hooks install\`, \`dreams source detect\`, \`dreams source scan\`, \`dreams upload\`, or \`dreams backfill start\`\n\n${USAGE}`);
         return 1;
     }
     if (args.since && command !== "backfill") {
@@ -286,6 +306,14 @@ async function runCli() {
         process.stderr.write(`Unexpected argument(s): ${args.positionals.slice(2).join(", ")}\n\n${USAGE}`);
         return 1;
     }
+    if (command === "hooks" && args.positionals.length > 2) {
+        process.stderr.write(`Unexpected argument(s): ${args.positionals.slice(2).join(", ")}\n\n${USAGE}`);
+        return 1;
+    }
+    if (command === "wake" && args.positionals.length > 1) {
+        process.stderr.write(`Unexpected argument(s): ${args.positionals.slice(1).join(", ")}\n\n${USAGE}`);
+        return 1;
+    }
     switch (command) {
         case "onboard":
             return (0, onboard_1.commandOnboard)(args.json);
@@ -298,7 +326,7 @@ async function runCli() {
         case "dev":
             return commandDevelopment(args.positionals, args.confirm, args.json);
         case "source":
-            return (0, commands_2.commandSource)(subcommand, args.positionals[2], args.json);
+            return (0, commands_2.commandSource)(subcommand, args.positionals[2], args.json, args.source);
         case "snapshots":
             return (0, snapshots_1.commandSnapshots)(subcommand, {
                 type: args.type,
@@ -307,6 +335,14 @@ async function runCli() {
                 workspaceId: args.workspaceId,
                 json: args.json,
             });
+        case "hooks":
+            if (subcommand !== "install") {
+                process.stderr.write(`Unknown hooks subcommand: ${subcommand ?? "(none)"} — expected install\n\n${USAGE}`);
+                return 1;
+            }
+            return (0, hooks_install_1.commandHooksInstall)({ json: args.json, dryRun: args.dryRun, sourceType: args.source });
+        case "wake":
+            return (0, sync_1.commandWake)({ json: args.json, sourceType: args.source });
         case "sync":
             return (0, sync_1.commandSync)(subcommand, {
                 json: args.json,
@@ -319,9 +355,9 @@ async function runCli() {
                 process.stderr.write(`Unknown backfill subcommand: ${subcommand ?? "(none)"} — expected start\n\n${USAGE}`);
                 return 1;
             }
-            return (0, backfill_1.commandBackfillStart)({ since: args.since, json: args.json });
+            return (0, backfill_1.commandBackfillStart)({ since: args.since, json: args.json, sourceType: args.source });
         case "upload":
-            return (0, commands_2.commandUpload)(args.json);
+            return (0, commands_2.commandUpload)(args.json, args.source);
         default:
             process.stderr.write(`Unknown command: ${command}\n\n${USAGE}`);
             return 1;

package/dist/local/backfill.js

@@ -517,6 +517,21 @@ function commandBackfillStart(options) {
         process.stderr.write("dreams backfill start requires --since <RFC3339>\n");
         return 1;
     }
+    // Resolve before any installation/DB/policy mutation (unknown/empty fail closed).
+    let adapter;
+    try {
+        adapter = (0, source_adapters_1.resolveSourceAdapter)(options.sourceType);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json) {
+            console.log(JSON.stringify({ status: "error", schema_version: 1, code: "invalid_argument", message }));
+        }
+        else {
+            process.stderr.write(`${message}\n`);
+        }
+        return 1;
+    }
     const lock = (0, state_lock_1.acquireLocalStateLock)();
     if (lock === null) {
         if (options.json) {
@@ -548,7 +563,7 @@ function commandBackfillStart(options) {
                     installationId: installation.installation_id,
                     leaseOwner: owner,
                     since: options.since,
-                    adapter: (0, source_adapters_1.defaultSourceAdapter)(),
+                    adapter,
                 });
             }
             finally {
@@ -557,6 +572,8 @@ function commandBackfillStart(options) {
             const payload = {
                 schema_version: 1,
                 status: result.status,
+                source: adapter.sourceType,
+                source_id: adapter.sourceId,
                 policy: result.policy,
                 sessions_in_window: result.sessions_in_window,
                 sessions_selected: result.sessions_selected,
@@ -568,7 +585,7 @@ function commandBackfillStart(options) {
                 console.log(JSON.stringify(payload, null, 2));
             else {
                 console.log([
-                    `Backfill ${result.status} for ${result.policy.since_at} → ${result.policy.until_at}`,
+                    `Backfill ${result.status} for ${adapter.sourceType} (${result.policy.since_at} → ${result.policy.until_at})`,
                     "",
                     `  Sessions in window: ${result.sessions_in_window}`,
                     `  Sessions scanned:   ${result.sessions_selected}`,
@@ -576,7 +593,7 @@ function commandBackfillStart(options) {
                     `  Frontier complete:  ${result.frontier_complete}`,
                     `  Segments enqueued:  ${result.scan.segments_enqueued}`,
                     "",
-                    "Local queue only — wake sync to upload: dreams sync --force",
+                    `Local queue only — wake sync to upload: dreams sync --source ${adapter.sourceType} --force`,
                 ].join("\n"));
             }
             return 0;

package/dist/local/claude-hooks.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Claude Code live-sync hook helpers — merge Dreams SessionStart/Stop into
+ * ~/.claude/settings.json without clobbering unrelated handlers.
+ *
+ * SessionStart → `dreams wake` (housekeeping + pending drain)
+ * Stop → `dreams sync` (live turn, stdin session hint)
+ */
+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.CLAUDE_HOOK_MARKER = void 0;
+exports.claudeSettingsPath = claudeSettingsPath;
+exports.buildClaudeHookCommandPosix = buildClaudeHookCommandPosix;
+exports.buildClaudeHookCommandPowerShell = buildClaudeHookCommandPowerShell;
+exports.buildClaudeHookCommand = buildClaudeHookCommand;
+exports.mergeClaudeSettingsJson = mergeClaudeSettingsJson;
+exports.planClaudeHooksInstall = planClaudeHooksInstall;
+exports.installClaudeHooks = installClaudeHooks;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+exports.CLAUDE_HOOK_MARKER = "dreams-sync-hook";
+function claudeSettingsPath(home = os.homedir()) {
+    return path.join(home, ".claude", "settings.json");
+}
+/** POSIX bash command for Claude Code command hooks. */
+function buildClaudeHookCommandPosix(cliPath, mode) {
+    return `"${cliPath}" ${mode} >/dev/null 2>&1 || true # ${exports.CLAUDE_HOOK_MARKER}`;
+}
+/** PowerShell command for Claude Code command hooks on Windows. */
+function buildClaudeHookCommandPowerShell(cliPath, mode) {
+    const quoted = cliPath.replace(/'/g, "''");
+    return `& '${quoted}' ${mode} *> $null; exit 0 # ${exports.CLAUDE_HOOK_MARKER}`;
+}
+function buildClaudeHookCommand(cliPath, mode, platform = process.platform) {
+    return platform === "win32"
+        ? buildClaudeHookCommandPowerShell(cliPath, mode)
+        : buildClaudeHookCommandPosix(cliPath, mode);
+}
+function isDreamsClaudeHandler(command) {
+    if (typeof command !== "string")
+        return false;
+    // Prefer the marker; also recognize older Dreams sync-only handlers by cli+sync.
+    return (command.includes(exports.CLAUDE_HOOK_MARKER) ||
+        (/\bsync\b/.test(command) && (command.includes("dreams") || command.includes(">/dev/null") || command.includes("*> $null"))));
+}
+function upsertEventHandler(matchers, command, platform) {
+    const next = matchers.map((matcher) => ({ ...matcher, hooks: [...(matcher.hooks ?? [])] }));
+    let updated = false;
+    for (const matcher of next) {
+        const hooks = matcher.hooks ?? [];
+        for (let i = 0; i < hooks.length; i++) {
+            if (isDreamsClaudeHandler(hooks[i]?.command)) {
+                const handler = { ...hooks[i], type: "command", command };
+                if (platform === "win32")
+                    handler.shell = "powershell";
+                else
+                    delete handler.shell;
+                hooks[i] = handler;
+                updated = true;
+            }
+        }
+        matcher.hooks = hooks;
+    }
+    if (updated)
+        return next;
+    const handler = { type: "command", command };
+    if (platform === "win32")
+        handler.shell = "powershell";
+    return [...next, { hooks: [handler] }];
+}
+/**
+ * Merge Dreams Claude handlers into settings.json.
+ * SessionStart uses wake; Stop uses sync.
+ */
+function mergeClaudeSettingsJson(existingRaw, cliPath, platform = process.platform) {
+    const wakeCmd = buildClaudeHookCommand(cliPath, "wake", platform);
+    const syncCmd = buildClaudeHookCommand(cliPath, "sync", platform);
+    let doc = {};
+    if (existingRaw !== null && existingRaw.trim() !== "") {
+        const parsed = JSON.parse(existingRaw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("claude settings.json must be a JSON object");
+        }
+        doc = { ...parsed };
+    }
+    const hooksValue = doc.hooks;
+    const hooks = hooksValue && typeof hooksValue === "object" && !Array.isArray(hooksValue)
+        ? { ...hooksValue }
+        : {};
+    const sessionStart = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    const stop = Array.isArray(hooks.Stop) ? hooks.Stop : [];
+    hooks.SessionStart = upsertEventHandler(sessionStart, wakeCmd, platform);
+    hooks.Stop = upsertEventHandler(stop, syncCmd, platform);
+    doc.hooks = hooks;
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+function planClaudeHooksInstall(options) {
+    const home = options.home ?? os.homedir();
+    const platform = options.platform ?? process.platform;
+    const settingsPath = claudeSettingsPath(home);
+    let existing = null;
+    try {
+        existing = fs.readFileSync(settingsPath, "utf8");
+    }
+    catch {
+        existing = null;
+    }
+    const next = mergeClaudeSettingsJson(existing, options.cliPath, platform);
+    return {
+        settings_path: settingsPath,
+        changed: existing !== next,
+        session_start_command: buildClaudeHookCommand(options.cliPath, "wake", platform),
+        stop_command: buildClaudeHookCommand(options.cliPath, "sync", platform),
+        next_contents: next,
+    };
+}
+function installClaudeHooks(options) {
+    const plan = planClaudeHooksInstall(options);
+    if (plan.changed) {
+        fs.mkdirSync(path.dirname(plan.settings_path), { recursive: true });
+        const temporary = `${plan.settings_path}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+        try {
+            fs.writeFileSync(temporary, plan.next_contents, { encoding: "utf8" });
+            fs.renameSync(temporary, plan.settings_path);
+        }
+        finally {
+            try {
+                fs.rmSync(temporary, { force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return plan;
+}

package/dist/local/claude.js

@@ -5,9 +5,12 @@
  * Discovery rule (filesystem shape is authoritative for the pilot):
  *   - only DIRECT children of ~/.claude/projects/<encoded-project>/
  *   - filename must be a UUID-like `<sessionId>.jsonl`
- *   - the transcript's own `sessionId` must agree with the filename
+ *   - a complete head record's `sessionId` must agree with the filename
+ *   - `cwd` is taken from the first head record that carries a string `cwd`
+ *     for that session (modern Claude transcripts often open with mode /
+ *     ai-title / etc. before the first cwd-bearing record)
  *   - never recurse; the `subagents/` directory is excluded outright
- *   - `isSidechain: true` records are a secondary signal to exclude sidechains
+ *   - `isSidechain: true` on any matching head record excludes the file
  * `parentUuid` is intentionally NOT used — ordinary main-session records also
  * carry parent relationships.
  *
@@ -107,28 +110,84 @@ function detectClaudeCodeHarness(home = os.homedir()) {
     }
     return { present: true, evidence };
 }
-/** Read the file head and return the first COMPLETE JSONL record, or null. */
-function readFirstRecord(filePath) {
+/**
+ * Read up to HEAD_READ_BYTES and derive session identity + cwd from complete
+ * JSONL records in that window. Modern Claude Code transcripts often open with
+ * metadata lines (mode, ai-title, …) that omit `cwd`; the first cwd-bearing
+ * record may appear several lines later (still well within the head window).
+ *
+ * Returns null when the head has no complete line, no matching sessionId, a
+ * mismatched sessionId, or is unreadable / malformed beyond recovery.
+ */
+function readHeadSessionFacts(filePath, expectedSessionId) {
     let fd;
     try {
         fd = fs.openSync(filePath, "r");
         const buf = Buffer.alloc(HEAD_READ_BYTES);
         const read = fs.readSync(fd, buf, 0, HEAD_READ_BYTES, 0);
+        if (read === 0)
+            return null;
         const head = buf.subarray(0, read);
-        const nl = head.indexOf(0x0a);
-        if (nl === -1)
-            return null; // no complete first line yet
-        const line = head.subarray(0, nl).toString("utf8").trim();
-        if (line === "")
+        // Only complete lines — a trailing partial record in the head is ignored.
+        const text = head.toString("utf8");
+        const lines = text.split("\n");
+        // If the buffer did not end on a newline, the final split piece is partial.
+        const completeLines = head[head.length - 1] === 0x0a ? lines : lines.slice(0, -1);
+        if (completeLines.length === 0)
             return null;
-        return JSON.parse(line);
+        let sawMatchingSession = false;
+        let isSidechain = false;
+        let cwd = null;
+        for (const raw of completeLines) {
+            const line = raw.trim();
+            if (line === "")
+                continue;
+            let record;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                    continue;
+                record = parsed;
+            }
+            catch {
+                continue;
+            }
+            const sessionId = typeof record.sessionId === "string" ? record.sessionId : null;
+            if (sessionId !== null) {
+                if (sessionId !== expectedSessionId) {
+                    return null; // filename must agree with every sessionId in the head
+                }
+                sawMatchingSession = true;
+                if (record.isSidechain === true)
+                    isSidechain = true;
+            }
+            // First cwd-bearing record wins. Modern transcripts put cwd on a later
+            // user/assistant line; some preamble lines omit sessionId entirely.
+            if (cwd === null && typeof record.cwd === "string" && record.cwd.length > 0) {
+                try {
+                    cwd = (0, config_1.canonicalize)(record.cwd);
+                }
+                catch {
+                    cwd = null;
+                }
+            }
+        }
+        if (!sawMatchingSession)
+            return null;
+        return { sessionId: expectedSessionId, cwd, isSidechain };
     }
     catch {
         return null;
     }
     finally {
-        if (fd !== undefined)
-            fs.closeSync(fd);
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // ignore
+            }
+        }
     }
 }
 function statSignals(filePath) {
@@ -176,20 +235,17 @@ function discoverSessions(projectsDir = claudeProjectsDir()) {
             if (!UUID_RE.test(base))
                 continue;
             const filePath = path.join(projectDir, file.name);
-            const record = readFirstRecord(filePath);
-            if (!record)
+            const facts = readHeadSessionFacts(filePath, base);
+            if (!facts)
                 continue;
-            if (record.isSidechain === true)
+            if (facts.isSidechain)
                 continue;
-            const sessionId = typeof record.sessionId === "string" ? record.sessionId : null;
-            if (sessionId !== base)
-                continue; // filename must agree with the transcript
             const signals = statSignals(filePath);
             sessions.push({
                 path: filePath,
                 real_path: (0, config_1.canonicalize)(filePath),
-                session_id: sessionId,
-                cwd: typeof record.cwd === "string" ? (0, config_1.canonicalize)(record.cwd) : null,
+                session_id: facts.sessionId,
+                cwd: facts.cwd,
                 size: signals.size,
                 inode: signals.inode,
                 birthtime_ms: signals.birthtime_ms,