@letta-ai/dreams 0.0.3 → 0.0.4

package/README.md

@@ -22,9 +22,11 @@ npx @letta-ai/dreams@latest onboard --json
 7. returns a skill handoff (`status: "ready"`) with absolute `cli_path` and skill path
 
 It does **not** check authentication or choose login/orient next steps. The
-installed `dreams-setup` skill owns sequencing (authenticate → detect source →
-init snapshot → activate → test connection). Repeated `onboard` calls are safe
-and repair local setup only.
+installed `dreams-setup` skill owns sequencing (authenticate → detect sources →
+init snapshot → approve directories + install consented hooks → optional
+background history import). SessionStart hooks call `dreams wake`; Stop hooks
+call `dreams sync`. Repeated `onboard` calls are safe and repair local setup
+only.
 
 ### Commands
 
@@ -34,7 +36,7 @@ and repair local setup only.
 - `dreams status [--json]` — installation, active and previous CLI versions,
   SQLite, setup skill, and authentication state.
 - `dreams auth login [--json]` — OAuth device code sign-in (see Auth below).
-- `dreams auth status [--json]` — authentication state; tokens are masked
+- `dreams auth status [--json]` — authentication state; lists every discovered credential (`env` / `keychain` / `file`), which won and why, plus a hooks note that live sync inherits the harness process env; tokens are masked
   (`at-let-…abcd`), never printed.
 - `dreams auth logout [--json]` — best-effort revoke of Dreams' refresh token,
   then clear stored credentials.
@@ -77,42 +79,56 @@ It is a separate internal Cloud operation with different credentials and data
 cleanup semantics. `dreams dev reset test-workspace` fails without deleting
 anything.
 
-## Local sources (Claude Code)
+## Local sources (Claude Code and Codex)
 
 The CLI maintains a crash-safe local SQLite store (`~/.dreams/dreams.db`) that
-discovers Claude Code transcripts and prepares immutable upload segments before
-they are sent to Letta Cloud.
-
-- `dreams source detect [--json]` — detect Claude Code from harness filesystem
-  facts under `~/.claude` (no transcript reads) and register an installation-scoped
-  Cloud source in status `detected`. Idempotent; does not scan or upload.
-- `dreams source approve-root <path> [--json]` — approve a work root. Sources
-  are **deny-by-default**: no transcript bytes are queued until their working
-  directory is under an approved root.
-- `dreams source scan [--json]` — discover top-level Claude Code sessions
-  (`~/.claude/projects/<project>/<sessionId>.jsonl`), read only complete new
-  lines after the durable cursor, and enqueue deterministic upload segments.
-  Repeated scans are idempotent; `.dreamignore` and unapproved roots are honored
-  before anything is enqueued.
-- `dreams source list [--json]` — show the DB path, approved roots, sources, and
-  the pending upload queue.
+discovers coding-agent transcripts and prepares immutable upload segments before
+they are sent to Letta Cloud. Harness behavior is selected with
+`--source <type>` (`claude-code` default; `codex`). One invocation always
+targets a single source — it never processes all sources at once.
+
+- `dreams source detect [--source <type>] [--json]` — detect a harness from
+  filesystem facts only (`~/.claude` or `~/.codex`; no transcript reads) and
+  register an installation-scoped Cloud source in status `detected`. Idempotent;
+  does not scan or upload.
+- `dreams source approve-dir <path> [--json]` (alias: `approve-root`) — approve a
+  work directory. Sources are **deny-by-default**: no transcript bytes are queued
+  until their working directory is under an approved folder (`.dreamignore`
+  still applies).
+- `dreams source scan [--source <type>] [--json]` — discover sessions for the
+  selected source (Claude: `~/.claude/projects/...`; Codex:
+  `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`), read only complete new lines
+  after the durable cursor, and enqueue deterministic upload segments. Repeated
+  scans are idempotent.
+- `dreams source list [--json]` — show the DB path, approved directories, sources,
+  and the pending upload queue.
 - `dreams snapshots create --type <type> --file <path> --client-request-id <id> [--workspace-id <id>] [--json]`
   — submit a skill-authored JSON snapshot (256 KiB UTF-8 object cap) to
   `POST /v1/dreams/workspaces/{workspaceId}/snapshots`. Workspace defaults to the
   local binding from `source detect`.
-- `dreams upload [--json]` — authenticate, refresh source registration, and
-  upload due queue entries. Upload accepts `detected` sources; Cloud promotes to
-  `active` after durable acceptance.
-- `dreams sync [--force] [--json]` — hook-safe scheduler: records a durable sync
-  trigger and runs a detached worker that live-scans tracked sessions and uploads
-  with a per-pass budget (~3h cadence unless `--force` or retry-due).
-- `dreams sync pause|resume|status [--json]` — pause makes hook wakes no-ops;
-  resume clears pause and requests one immediate sync.
-- `dreams backfill start --since <RFC3339> [--json]` — approve a frozen
-  `[since, until=now]` historical window and run one bounded local scan/queue
-  pass (session frontier, newest unfinished sessions first; no upload).
-  Re-running the same active `--since` is idempotent; a different active policy
-  fails closed. Sync drains live first, then backfill by newest session mtime.
+- `dreams hooks install [--source <type>] [--dry-run] [--json]` — install or
+  preview Claude Code / Codex live-sync hooks. SessionStart → `wake`, Stop →
+  `sync`. Prefer `--dry-run` for consent before writing.
+- `dreams wake [--source <type>] [--json]` — SessionStart entrypoint: quiet
+  managed CLI/skill repair, then force-kick the sync worker for pending
+  live/backfill drain (no stdin session hint). Always exits 0 for hook safety.
+- `dreams sync [--source <type>] [--force] [--json]` — Stop / live-turn
+  scheduler for one source: records a durable sync trigger (optional stdin
+  `session_id`) and runs a detached worker that live-scans tracked sessions and
+  uploads with a per-pass budget (~3h cadence unless `--force` or retry-due).
+- `dreams sync pause|resume [--json]` — global pause makes hook wakes no-ops;
+  resume clears pause and requests one immediate sync (not per-source).
+- `dreams sync status [--source <type>] [--json]` — per-source diagnostics
+  (`effective_state`, cadence/retry, worker). Codex status also reports
+  discovery health (`discovery.status` / reason codes) when rollout formats
+  drift.
+- `dreams backfill start --since <RFC3339> [--source <type>] [--json]` — approve
+  a frozen `[since, until=now]` historical window for one source and run one
+  bounded local scan/queue pass (session frontier, newest unfinished sessions
+  first; no upload). Policies are source-isolated. Re-running the same active
+  `--since` is idempotent; a different active policy fails closed. After
+  `backfill start`, kick with `dreams wake --source …` so draining does not wait
+  for the next session.
 
 Local cursors track a `queued_through_offset` (advanced as segments are queued)
 separately from an `acked_offset` (advanced only after durable Cloud
@@ -150,6 +166,12 @@ masks them. `DREAMS_CREDENTIALS_BACKEND=file|keychain` forces a backend
    when it is missing or expires within 5 minutes.
 3. Otherwise: a structured not-authenticated error (`dreams auth login`).
 
+`dreams auth status --json` reports that inventory explicitly: top-level
+`source` / `access_token` remain the winner for this process; `credentials[]`
+lists each backend with `present`, `selected`, and `reason`; `active` restates
+the winner; `hooks` notes that coding-agent hooks inherit the harness
+environment (a harness-set `LETTA_API_KEY` shadows stored OAuth).
+
 **Refresh rotation.** Refreshes use `refresh_token_mode: "new"`: the server
 always returns a *new* refresh token that revokes the old one for this
 (user, client, device). The CLI persists the rotated token immediately and

package/bin/dreams-codex-hook.cjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Codex SessionStart/Stop hook launcher for Dreams.
+ *
+ * Codex Stop requires exactly one valid JSON object on stdout when exiting 0.
+ * Dreams CLI JSON must never leak into that stream. This wrapper:
+ *   1. Forwards hook stdin to `dreams <wake|sync> --source codex`
+ *   2. Suppresses all CLI stdout/stderr
+ *   3. Always prints `{}` and exits 0 (scheduling failures must not interrupt Codex)
+ *
+ * Usage:
+ *   node dreams-codex-hook.cjs <cli_path> [wake|sync]
+ * Default mode is `sync` (Stop / live turn). SessionStart should pass `wake`.
+ */
+"use strict";
+
+var spawnSync = require("node:child_process").spawnSync;
+var fs = require("node:fs");
+var path = require("node:path");
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0);
+  } catch {
+    return Buffer.alloc(0);
+  }
+}
+
+function quoteCmdArg(value) {
+  return '"' + String(value).replace(/"/g, '""') + '"';
+}
+
+function resolveMode(raw) {
+  if (raw === "wake" || raw === "sync") return raw;
+  return "sync";
+}
+
+/**
+ * Resolve how to invoke the durable Dreams CLI.
+ * On Windows the stable launcher is `dreams.cmd`, which cannot be spawnSync'd
+ * with shell:false. Prefer the sibling Node controller (`launcher.cjs`) when
+ * present (managed install layout); otherwise fall back to ComSpec with
+ * explicitly quoted paths so spaces work.
+ */
+function resolveInvocation(cliPath, mode) {
+  var args = [mode, "--source", "codex"];
+  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(cliPath)) {
+    var sibling = path.join(path.dirname(cliPath), "launcher.cjs");
+    try {
+      if (fs.statSync(sibling).isFile()) {
+        return { command: process.execPath, args: [sibling].concat(args), shell: false };
+      }
+    } catch {
+      // fall through to ComSpec
+    }
+    var cmdline = [quoteCmdArg(cliPath)].concat(args).join(" ");
+    return {
+      command: process.env.ComSpec || "cmd.exe",
+      args: ["/d", "/s", "/c", cmdline],
+      shell: false,
+    };
+  }
+  return { command: cliPath, args: args, shell: false };
+}
+
+function main() {
+  var cliPath = process.argv[2];
+  var mode = resolveMode(process.argv[3]);
+  var stdin = mode === "wake" ? Buffer.alloc(0) : readStdinSync();
+
+  if (typeof cliPath === "string" && cliPath.trim() !== "") {
+    try {
+      var invocation = resolveInvocation(cliPath, mode);
+      spawnSync(invocation.command, invocation.args, {
+        input: stdin,
+        encoding: "buffer",
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        shell: invocation.shell,
+        env: process.env,
+      });
+    } catch {
+      // Tolerate missing launcher / spawn failures — hook must not interrupt Codex.
+    }
+  }
+
+  process.stdout.write("{}\n");
+  process.exit(0);
+}
+
+main();

package/bin/dreams.cjs

@@ -16,4 +16,25 @@ if (major < REQUIRED_MAJOR || (major === REQUIRED_MAJOR && minor < REQUIRED_MINO
   process.exit(1);
 }
 
+// node:sqlite still emits ExperimentalWarning on load; suppress only that noise
+// before requiring the CLI (which imports node:sqlite).
+(function suppressSqliteExperimentalWarning() {
+  var originalEmit = process.emit;
+  process.emit = function (event) {
+    if (event === 'warning' && arguments.length > 1) {
+      var warning = arguments[1];
+      if (
+        warning &&
+        typeof warning === 'object' &&
+        warning.name === 'ExperimentalWarning' &&
+        typeof warning.message === 'string' &&
+        /SQLite is an experimental feature|node:sqlite/i.test(warning.message)
+      ) {
+        return false;
+      }
+    }
+    return originalEmit.apply(process, arguments);
+  };
+})();
+
 require('../dist/cli.js').main();

package/dist/auth/commands.js

@@ -97,20 +97,40 @@ async function commandAuthLoginUnlocked(json) {
     }
 }
 function renderAuthStatus(info) {
+    const candidateLines = info.credentials.map((c) => {
+        const mark = c.selected ? "*" : " ";
+        const detail = c.present
+            ? `${c.access_token ?? "(no access token)"}` + (c.expires_at ? ` exp=${c.expires_at}` : "")
+            : "(absent)";
+        return `  ${mark} ${c.source.padEnd(9)} ${detail}\n      ${c.reason}`;
+    });
     if (!info.authenticated) {
         return [
             `Not authenticated — run \`dreams auth login\` to connect this device.`,
             ``,
             `  Device id: ${info.device_id}`,
+            ``,
+            `Credentials discovered:`,
+            ...candidateLines,
+            ``,
+            `Hooks: ${info.hooks.note}`,
         ].join("\n");
     }
     return [
         `Authenticated via ${info.source}`,
+        info.active ? `  Why: ${info.active.reason}` : ``,
         ``,
         `  Access token: ${info.access_token ?? "(none — will refresh on next use)"}`,
         `  Expires at:   ${info.expires_at ?? "(n/a — LETTA_API_KEY)"}`,
         `  Device id:    ${info.device_id}`,
-    ].join("\n");
+        ``,
+        `Credentials discovered (* = selected for this process):`,
+        ...candidateLines,
+        ``,
+        `Hooks: ${info.hooks.note}`,
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
 }
 function commandAuthStatusUnlocked(json) {
     const info = (0, index_1.authStatusInfo)();

package/dist/auth/credentials.js

@@ -47,6 +47,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXPIRY_MARGIN_MS = exports.NotAuthenticatedError = void 0;
 exports.credentialsFilePath = credentialsFilePath;
 exports.loadCredentials = loadCredentials;
+exports.probeStoredCredentialBackends = probeStoredCredentialBackends;
 exports.saveCredentials = saveCredentials;
 exports.clearCredentials = clearCredentials;
 exports.expiresWithin = expiresWithin;
@@ -166,6 +167,23 @@ function warnKeychainUnavailable() {
     process.stderr.write("Warning: OS keychain unavailable — storing credentials in ~/.dreams/credentials.json (mode 0600).\n");
 }
 // --- public API ---------------------------------------------------------------
+function credentialsFromKeychainRaw(refresh, accessRaw) {
+    let access_token = "";
+    let expires_at = EPOCH_ISO;
+    if (accessRaw) {
+        try {
+            const parsed = JSON.parse(accessRaw);
+            if (typeof parsed.access_token === "string")
+                access_token = parsed.access_token;
+            if (typeof parsed.expires_at === "string")
+                expires_at = parsed.expires_at;
+        }
+        catch {
+            // stale/foreign entry shape — treat access token as expired
+        }
+    }
+    return { access_token, refresh_token: refresh, expires_at };
+}
 /**
  * Load stored credentials: keychain first, then the file fallback (covers
  * installs where an earlier save fell back to the file).
@@ -173,25 +191,66 @@ function warnKeychainUnavailable() {
 function loadCredentials() {
     const refresh = keychainRead(REFRESH_ACCOUNT);
     if (refresh) {
-        let access_token = "";
-        let expires_at = EPOCH_ISO;
-        const accessRaw = keychainRead(ACCESS_ACCOUNT);
-        if (accessRaw) {
-            try {
-                const parsed = JSON.parse(accessRaw);
-                if (typeof parsed.access_token === "string")
-                    access_token = parsed.access_token;
-                if (typeof parsed.expires_at === "string")
-                    expires_at = parsed.expires_at;
+        return {
+            credentials: credentialsFromKeychainRaw(refresh, keychainRead(ACCESS_ACCOUNT)),
+            source: "keychain",
+        };
+    }
+    const fromFile = fileRead();
+    return fromFile ? { credentials: fromFile, source: "file" } : null;
+}
+/**
+ * Inspect each stored backend independently for `auth status` inventory.
+ * Unlike `loadCredentials()`, this does not stop after keychain wins — file is
+ * still reported when both exist. Never throws (forced-keychain misconfig →
+ * unavailable).
+ */
+function probeStoredCredentialBackends() {
+    let keychain;
+    if (backendOverride() === "file") {
+        keychain = { status: "not_checked", credentials: null };
+    }
+    else {
+        try {
+            const ctor = requireKeyring();
+            if (!ctor) {
+                keychain = { status: "unavailable", credentials: null };
             }
-            catch {
-                // stale/foreign entry shape — treat access token as expired
+            else {
+                let refresh = null;
+                let accessRaw = null;
+                try {
+                    refresh = new ctor(KEYCHAIN_SERVICE, REFRESH_ACCOUNT).getPassword() ?? null;
+                }
+                catch {
+                    refresh = null;
+                }
+                try {
+                    accessRaw = new ctor(KEYCHAIN_SERVICE, ACCESS_ACCOUNT).getPassword() ?? null;
+                }
+                catch {
+                    accessRaw = null;
+                }
+                if (refresh) {
+                    keychain = {
+                        status: "present",
+                        credentials: credentialsFromKeychainRaw(refresh, accessRaw),
+                    };
+                }
+                else {
+                    keychain = { status: "absent", credentials: null };
+                }
             }
         }
-        return { credentials: { access_token, refresh_token: refresh, expires_at }, source: "keychain" };
+        catch {
+            keychain = { status: "unavailable", credentials: null };
+        }
     }
     const fromFile = fileRead();
-    return fromFile ? { credentials: fromFile, source: "file" } : null;
+    const file = fromFile
+        ? { status: "present", credentials: fromFile }
+        : { status: "absent", credentials: null };
+    return { keychain, file };
 }
 /** Persist credentials: keychain if usable, else the 0600 file (with a warning). */
 function saveCredentials(credentials) {

package/dist/auth/index.js

@@ -38,28 +38,121 @@ async function getAuthHeader() {
     const { token } = await resolveAccessToken();
     return { authorization: `Bearer ${token}` };
 }
+const HOOKS_NOTE = "Hooks invoke `dreams sync` with the coding-agent harness process environment. " +
+    "If that environment sets LETTA_API_KEY, it wins over keychain/file — verify the " +
+    "credential hooks will use (harness env), not only an interactive CLI shell.";
+function maskedStored(credentials) {
+    if (!credentials) {
+        return { access_token: null, expires_at: null, has_refresh_token: false };
+    }
+    return {
+        access_token: credentials.access_token ? (0, credentials_1.maskToken)(credentials.access_token) : null,
+        expires_at: credentials.expires_at,
+        has_refresh_token: true,
+    };
+}
+function keychainReason(status, selected) {
+    if (status === "not_checked") {
+        return "not checked because DREAMS_CREDENTIALS_BACKEND=file";
+    }
+    if (status === "unavailable") {
+        return "OS keychain unavailable (@napi-rs/keyring missing or unreadable)";
+    }
+    if (status === "absent") {
+        return "no Dreams refresh token in OS keychain";
+    }
+    if (selected) {
+        return "selected: highest-precedence stored credential (no LETTA_API_KEY)";
+    }
+    return "present but shadowed by LETTA_API_KEY";
+}
+function fileReason(present, selected, keychainPresent, envPresent) {
+    if (!present)
+        return "no credentials file at ~/.dreams/credentials.json";
+    if (selected) {
+        return "selected: file fallback (no LETTA_API_KEY; keychain empty or not used)";
+    }
+    if (envPresent)
+        return "present but shadowed by LETTA_API_KEY";
+    if (keychainPresent)
+        return "present but shadowed by keychain for stored-credential resolution";
+    return "present but not selected";
+}
 /** Snapshot of auth state for `dreams auth status` and `dreams status`. Never refreshes. */
 function authStatusInfo() {
     const device_id = (0, store_1.loadOrCreateInstallation)().installation_id;
     const envKey = process.env.LETTA_API_KEY;
-    if (envKey) {
-        return {
-            authenticated: true,
+    const envPresent = typeof envKey === "string" && envKey.length > 0;
+    const probes = (0, credentials_1.probeStoredCredentialBackends)();
+    const keychainPresent = probes.keychain.status === "present";
+    const filePresent = probes.file.status === "present";
+    let active = null;
+    if (envPresent) {
+        active = {
             source: "env",
-            access_token: (0, credentials_1.maskToken)(envKey),
-            expires_at: null,
-            device_id,
+            reason: "LETTA_API_KEY is set and takes highest precedence",
         };
     }
-    const stored = (0, credentials_1.loadCredentials)();
-    if (!stored) {
-        return { authenticated: false, source: null, access_token: null, expires_at: null, device_id };
+    else if (keychainPresent) {
+        active = {
+            source: "keychain",
+            reason: "no LETTA_API_KEY; OS keychain has a Dreams refresh token",
+        };
+    }
+    else if (filePresent) {
+        active = {
+            source: "file",
+            reason: "no LETTA_API_KEY; credentials file present (keychain empty or unavailable)",
+        };
     }
+    const keychainMasked = maskedStored(probes.keychain.credentials);
+    const fileMasked = maskedStored(probes.file.credentials);
+    const credentials = [
+        {
+            source: "env",
+            present: envPresent,
+            selected: active?.source === "env",
+            access_token: envPresent && envKey ? (0, credentials_1.maskToken)(envKey) : null,
+            expires_at: null,
+            has_refresh_token: false,
+            reason: envPresent
+                ? "highest precedence; used for CLI Cloud calls in this process and any child that inherits this environment"
+                : "LETTA_API_KEY is unset in this process",
+        },
+        {
+            source: "keychain",
+            present: keychainPresent,
+            selected: active?.source === "keychain",
+            access_token: keychainMasked.access_token,
+            expires_at: keychainMasked.expires_at,
+            has_refresh_token: keychainMasked.has_refresh_token,
+            reason: keychainReason(probes.keychain.status, active?.source === "keychain"),
+        },
+        {
+            source: "file",
+            present: filePresent,
+            selected: active?.source === "file",
+            access_token: fileMasked.access_token,
+            expires_at: fileMasked.expires_at,
+            has_refresh_token: fileMasked.has_refresh_token,
+            reason: fileReason(filePresent, active?.source === "file", keychainPresent, envPresent),
+        },
+    ];
+    const winner = active
+        ? credentials.find((c) => c.source === active.source)
+        : null;
     return {
-        authenticated: true,
-        source: stored.source,
-        access_token: stored.credentials.access_token ? (0, credentials_1.maskToken)(stored.credentials.access_token) : null,
-        expires_at: stored.credentials.expires_at,
+        authenticated: active !== null,
+        source: active?.source ?? null,
+        access_token: winner?.access_token ?? null,
+        expires_at: winner?.expires_at ?? null,
         device_id,
+        active,
+        credentials,
+        hooks: {
+            inherits_process_env: true,
+            effective_source_in_this_process: active?.source ?? null,
+            note: HOOKS_NOTE,
+        },
     };
 }