@letta-ai/dreams 0.0.1

package/README.md

@@ -0,0 +1,146 @@
+# @letta-ai/dreams
+
+CLI for **Dream** — Letta's shared organizational memory built from
+coding-agent transcripts.
+
+## Setup
+
+Start setup from a coding agent with:
+
+```sh
+npx @letta-ai/dreams@latest onboard --json
+```
+
+`onboard`:
+
+1. verifies Node >= 22.13 through the bin preflight
+2. installs the exact CLI version under `~/.dreams/cli/<version>/`
+3. creates or preserves the stable launcher at `~/.dreams/bin/dreams`
+4. creates or preserves the installation id in `~/.dreams/installation.json`
+5. installs `~/.claude/skills/dreams-setup/SKILL.md`
+6. initializes and migrates `~/.dreams/dreams.db`
+7. returns the next agent action based on authentication state
+
+It does not start login or `orient` itself. An unauthenticated response directs
+the agent to run `auth login` and then rerun `onboard`; an authenticated
+response directs the agent to run `orient`. Repeated calls are safe and return
+the same action until authentication state changes.
+
+### Commands
+
+- `dreams onboard [--json]` — install or repair local setup and return the next
+  setup action.
+- `dreams status [--json]` — installation, durable CLI, 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
+  (`at-let-…abcd`), never printed.
+- `dreams auth logout [--json]` — best-effort revoke of Dreams' refresh token,
+  then clear stored credentials.
+
+Local state lives in `~/.dreams/`. Requires Node >= 22.13, where built-in
+`node:sqlite` no longer requires the `--experimental-sqlite` flag.
+
+## Local sources (Claude Code)
+
+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 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.
+- `dreams upload [--json]` — authenticate, register the source, and upload due
+  queue entries to Letta Cloud.
+
+Local cursors track a `queued_through_offset` (advanced as segments are queued)
+separately from an `acked_offset` (advanced only after durable Cloud
+acceptance, in a later step).
+
+## Auth
+
+`dreams auth login` runs Letta's **OAuth 2.0 Device Code Flow** against
+`https://app.letta.com` (override with `LETTA_AUTH_BASE_URL`; the API host is
+`https://api.letta.com`, override with `LETTA_BASE_URL`):
+
+1. The CLI requests a device + user code and prints a verification URL.
+2. The user approves in the browser; the CLI polls the token endpoint
+   (handling `authorization_pending`, `slow_down`, `access_denied`,
+   `expired_token`) until it receives an access token (`at-let-…`, ~30 days)
+   and a refresh token (`rt-let-…`, 1 year).
+3. In `--json` mode, `auth login` emits **two JSON lines** on stdout: first
+   `{"status":"awaiting_approval",…}` (show the user the URL/code), then
+   `{"status":"authenticated",…}` after approval.
+
+**Storage.** Credentials go to the OS keychain via `@napi-rs/keyring`
+(an *optional* dependency — the CLI keeps zero hard runtime deps), service
+`letta-dreams`, accounts `refresh-token` and `access-token`. When the keychain
+is unavailable, the CLI falls back to `~/.dreams/credentials.json`, written
+atomically with mode 0600 (a one-line stderr warning notes the fallback).
+Tokens are never written to local setup state or logs, and status output always
+masks them. `DREAMS_CREDENTIALS_BACKEND=file|keychain` forces a backend
+(tests use `file`).
+
+**Precedence** when resolving an auth header (`getAuthHeader()` in
+`src/auth/index.ts`):
+
+1. `LETTA_API_KEY` env var — used verbatim, never refreshed, never stored.
+2. Stored Dreams credentials — the access token is refreshed automatically
+   when it is missing or expires within 5 minutes.
+3. Otherwise: a structured not-authenticated error (`dreams auth login`).
+
+**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
+atomically before using the new access token, singleflights concurrent
+in-process refreshes, and holds a lockfile (`~/.dreams/auth.lock`, stale
+after 30s) so two dreams processes on one machine cannot interleave
+rotate-then-persist. A refresh failing with `invalid_grant` (stale rotated
+token) clears stored credentials.
+
+**Why Dreams does not reuse letta-code's keychain entries.** Dreams shares
+letta-code's *public client id*, but deliberately keeps its own credentials
+(service `letta-dreams` vs `letta-code`) and its own `device_id` (the Dreams
+`installation_id`). Rotation is scoped per (user, client, device): if both
+CLIs shared one refresh token, each refresh by one tool would revoke the
+token out from under the other (rotation collision). Separate device ids
+guarantee the two token chains never collide, and `dreams auth logout` can
+never revoke letta-code's session.
+
+## Development
+
+```sh
+npm install
+npm run dev -- onboard --json   # run from source via tsx
+npm run typecheck
+npm run build                   # compile to dist/
+npm test                        # build + node:test suite (uses a temp HOME)
+```
+
+## Testing the npx bootstrap via tarball (no publish)
+
+```sh
+npm pack                     # produces letta-ai-dreams-0.0.1.tgz
+cd "$(mktemp -d)"
+npx -y -p /absolute/path/to/dreams/letta-ai-dreams-0.0.1.tgz dreams onboard
+```
+
+(The `-p <tarball> dreams` form is required: a bare `npx <tarball>` treats the
+path as a script to execute, not a package to install.)
+
+`onboard` writes to `~/.dreams/` and installs
+`~/.claude/skills/dreams-setup/SKILL.md`. Set `HOME` to a temporary directory
+for a sandboxed run.
+
+## Deferred
+
+- `orient` and its Cloud-backed setup actions
+- Shared-memory generation and review
+- Automated source configuration and historical backfill

package/bin/dreams.cjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Preflight Node version check. This shim must stay ES5-safe so it can run
+// (and fail gracefully) on old Node versions before any modern syntax loads.
+// Node >= 22.13 is required: that is where node:sqlite stopped needing the
+// --experimental-sqlite flag, which the local source store depends on.
+var REQUIRED_MAJOR = 22;
+var REQUIRED_MINOR = 13;
+
+var version = process.versions.node;
+var parts = version.split('.');
+var major = parseInt(parts[0], 10) || 0;
+var minor = parseInt(parts[1], 10) || 0;
+
+if (major < REQUIRED_MAJOR || (major === REQUIRED_MAJOR && minor < REQUIRED_MINOR)) {
+  console.error('Dream requires Node 22.13+ — found v' + version + '. Please upgrade.');
+  process.exit(1);
+}
+
+require('../dist/cli.js').main();

package/dist/auth/browser.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCommand = openCommand;
+exports.openBrowser = openBrowser;
+const node_child_process_1 = require("node:child_process");
+/** Platform command for opening a URL in the default browser. */
+function openCommand(platform) {
+    switch (platform) {
+        case "darwin":
+            return { cmd: "open", args: [] };
+        case "win32":
+            // `start` is a cmd builtin; empty title arg guards URLs with ampersands.
+            return { cmd: "cmd", args: ["/c", "start", '""'] };
+        case "linux":
+            return { cmd: "xdg-open", args: [] };
+        default:
+            return null;
+    }
+}
+/**
+ * Best-effort: open the verification URL in the user's default browser.
+ * Never throws, never blocks — the printed URL is always the fallback.
+ * Suppressed by DREAMS_NO_BROWSER=1 (CI, ssh sessions, tests).
+ */
+function openBrowser(url) {
+    if (process.env.DREAMS_NO_BROWSER === "1")
+        return false;
+    const command = openCommand(process.platform);
+    if (!command)
+        return false;
+    try {
+        const child = (0, node_child_process_1.spawn)(command.cmd, [...command.args, url], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/auth/commands.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Command handlers for `dreams auth login|status|logout`.
+ *
+ * JSON mode of `auth login` is JSON-lines on stdout (agents drive this):
+ * one {"status":"awaiting_approval",…} object immediately, then a second
+ * {"status":"authenticated",…} object once the user approves in the browser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandAuthLogin = commandAuthLogin;
+exports.renderAuthStatus = renderAuthStatus;
+exports.commandAuthStatus = commandAuthStatus;
+exports.commandAuthLogout = commandAuthLogout;
+const browser_1 = require("./browser");
+const store_1 = require("../store");
+const index_1 = require("./index");
+const credentials_1 = require("./credentials");
+const oauth_refresh_1 = require("./oauth-refresh");
+const oauth_1 = require("./oauth");
+/** `auth login` short-circuits when the stored token is valid for >7 days. */
+const REAUTH_MARGIN_MS = 7 * 24 * 60 * 60 * 1000;
+function printJsonLine(value) {
+    console.log(JSON.stringify(value));
+}
+async function commandAuthLogin(json) {
+    const stored = (0, credentials_1.loadCredentials)();
+    if (stored && stored.credentials.access_token && !(0, credentials_1.expiresWithin)(stored.credentials, REAUTH_MARGIN_MS)) {
+        if (json) {
+            printJsonLine({ status: "already_authenticated", expires_at: stored.credentials.expires_at });
+        }
+        else {
+            console.log(`Already authenticated (access token valid until ${stored.credentials.expires_at}).\n` +
+                `Run \`dreams auth logout\` first to connect a different account.`);
+        }
+        return 0;
+    }
+    const installation = (0, store_1.loadOrCreateInstallation)();
+    try {
+        const device = await (0, oauth_1.requestDeviceCode)();
+        const verifyUrl = device.verification_uri_complete || device.verification_uri;
+        const opened = (0, browser_1.openBrowser)(verifyUrl);
+        if (json) {
+            printJsonLine({
+                status: "awaiting_approval",
+                verification_uri: device.verification_uri,
+                verification_uri_complete: device.verification_uri_complete ?? null,
+                user_code: device.user_code,
+                expires_in: device.expires_in,
+            });
+        }
+        else {
+            console.log([
+                ``,
+                `To connect this device to Letta, open:`,
+                ``,
+                `    ${verifyUrl}`,
+                ``,
+                `and confirm the code: ${device.user_code}`,
+                ``,
+                opened ? `(opened in your browser)` : ``,
+                `Waiting for approval (expires in ${Math.round(device.expires_in / 60)} minutes)...`,
+            ].join("\n"));
+        }
+        let pendingPolls = 0;
+        const token = await (0, oauth_1.pollForToken)({
+            deviceCode: device.device_code,
+            deviceId: installation.installation_id,
+            intervalSeconds: device.interval,
+            expiresInSeconds: device.expires_in,
+            onPending: () => {
+                pendingPolls += 1;
+                if (!json && pendingPolls % 6 === 0)
+                    console.log("Still waiting for approval...");
+            },
+        });
+        const credentials = (0, oauth_refresh_1.credentialsFromToken)(token, "");
+        (0, credentials_1.saveCredentials)(credentials);
+        if (json) {
+            printJsonLine({ status: "authenticated", expires_at: credentials.expires_at });
+        }
+        else {
+            console.log(`\nAuthenticated. Access token expires ${credentials.expires_at}.`);
+            if (process.env.LETTA_API_KEY) {
+                process.stderr.write("Note: LETTA_API_KEY is set and takes precedence over stored credentials.\n");
+            }
+        }
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (json)
+            printJsonLine({ status: "error", message });
+        else
+            process.stderr.write(`Login failed: ${message}\n`);
+        return 1;
+    }
+}
+function renderAuthStatus(info) {
+    if (!info.authenticated) {
+        return [
+            `Not authenticated — run \`dreams auth login\` to connect this device.`,
+            ``,
+            `  Device id: ${info.device_id}`,
+        ].join("\n");
+    }
+    return [
+        `Authenticated via ${info.source}`,
+        ``,
+        `  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");
+}
+function commandAuthStatus(json) {
+    const info = (0, index_1.authStatusInfo)();
+    if (json) {
+        console.log(JSON.stringify(info, null, 2));
+    }
+    else {
+        console.log(renderAuthStatus(info));
+    }
+    return 0;
+}
+async function commandAuthLogout(json) {
+    const stored = (0, credentials_1.loadCredentials)();
+    if (!stored) {
+        if (json)
+            printJsonLine({ status: "not_authenticated" });
+        else
+            console.log("No stored credentials to clear.");
+        return 0;
+    }
+    // Best-effort revoke of Dreams' own refresh token (never letta-code's).
+    await (0, oauth_1.revokeToken)(stored.credentials.refresh_token);
+    (0, credentials_1.clearCredentials)();
+    if (json)
+        printJsonLine({ status: "logged_out" });
+    else
+        console.log("Logged out: refresh token revoked and local credentials cleared.");
+    return 0;
+}

package/dist/auth/credentials.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * Credential storage for the Dreams CLI.
+ *
+ * Primary backend: OS keychain via @napi-rs/keyring (an OPTIONAL dependency —
+ * loaded with a try/require guard), service "letta-dreams", accounts
+ * "refresh-token" and "access-token" (the latter stores JSON with expires_at).
+ * Fallback: ~/.dreams/credentials.json written atomically with mode 0600.
+ *
+ * Tokens must NEVER be written to local setup state or logs. This module never
+ * touches letta-code's keychain entries (its service name is "letta-code").
+ */
+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.EXPIRY_MARGIN_MS = exports.NotAuthenticatedError = void 0;
+exports.credentialsFilePath = credentialsFilePath;
+exports.loadCredentials = loadCredentials;
+exports.saveCredentials = saveCredentials;
+exports.clearCredentials = clearCredentials;
+exports.expiresWithin = expiresWithin;
+exports.maskToken = maskToken;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const store_1 = require("../store");
+class NotAuthenticatedError extends Error {
+    code = "not_authenticated";
+    constructor(message = "Not authenticated. Run `dreams auth login` to connect this device.") {
+        super(message);
+        this.name = "NotAuthenticatedError";
+    }
+}
+exports.NotAuthenticatedError = NotAuthenticatedError;
+const KEYCHAIN_SERVICE = "letta-dreams";
+const REFRESH_ACCOUNT = "refresh-token";
+const ACCESS_ACCOUNT = "access-token";
+/** Refresh when the access token is missing or expires within 5 minutes. */
+exports.EXPIRY_MARGIN_MS = 5 * 60 * 1000;
+const EPOCH_ISO = new Date(0).toISOString();
+let cachedKeyringCtor;
+function requireKeyring() {
+    if (cachedKeyringCtor === undefined) {
+        try {
+            // Optional dependency: may be missing (install skipped/failed) — fall back.
+            const mod = require("@napi-rs/keyring");
+            cachedKeyringCtor = mod.Entry ?? null;
+        }
+        catch {
+            cachedKeyringCtor = null;
+        }
+    }
+    return cachedKeyringCtor;
+}
+function backendOverride() {
+    const value = process.env.DREAMS_CREDENTIALS_BACKEND;
+    return value === "file" || value === "keychain" ? value : null;
+}
+/** null means "do not use the keychain" (forced file backend or module absent). */
+function keyringCtor() {
+    const override = backendOverride();
+    if (override === "file")
+        return null;
+    const ctor = requireKeyring();
+    if (override === "keychain" && ctor === null) {
+        throw new Error("DREAMS_CREDENTIALS_BACKEND=keychain but @napi-rs/keyring is unavailable");
+    }
+    return ctor;
+}
+function keychainRead(account) {
+    const ctor = keyringCtor();
+    if (!ctor)
+        return null;
+    try {
+        return new ctor(KEYCHAIN_SERVICE, account).getPassword() ?? null;
+    }
+    catch {
+        return null; // no entry, or keychain unusable — fall through to file
+    }
+}
+function keychainDelete(account) {
+    const ctor = keyringCtor();
+    if (!ctor)
+        return;
+    try {
+        new ctor(KEYCHAIN_SERVICE, account).deleteCredential();
+    }
+    catch {
+        // already gone or keychain unusable
+    }
+}
+// --- file backend ------------------------------------------------------------
+function credentialsFilePath() {
+    return path.join((0, store_1.dreamsDir)(), "credentials.json");
+}
+function fileRead() {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(credentialsFilePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.refresh_token !== "string" || parsed.refresh_token === "")
+        return null;
+    return {
+        access_token: typeof parsed.access_token === "string" ? parsed.access_token : "",
+        refresh_token: parsed.refresh_token,
+        expires_at: typeof parsed.expires_at === "string" ? parsed.expires_at : EPOCH_ISO,
+    };
+}
+/** Atomic write (temp + rename) with owner-only permissions. */
+function fileWrite(credentials) {
+    const file = credentialsFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(credentials, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+let warnedKeychainUnavailable = false;
+function warnKeychainUnavailable() {
+    if (warnedKeychainUnavailable)
+        return;
+    warnedKeychainUnavailable = true;
+    process.stderr.write("Warning: OS keychain unavailable — storing credentials in ~/.dreams/credentials.json (mode 0600).\n");
+}
+// --- public API ---------------------------------------------------------------
+/**
+ * Load stored credentials: keychain first, then the file fallback (covers
+ * installs where an earlier save fell back to the file).
+ */
+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;
+            }
+            catch {
+                // stale/foreign entry shape — treat access token as expired
+            }
+        }
+        return { credentials: { access_token, refresh_token: refresh, expires_at }, source: "keychain" };
+    }
+    const fromFile = fileRead();
+    return fromFile ? { credentials: fromFile, source: "file" } : null;
+}
+/** Persist credentials: keychain if usable, else the 0600 file (with a warning). */
+function saveCredentials(credentials) {
+    const ctor = keyringCtor();
+    if (ctor) {
+        try {
+            new ctor(KEYCHAIN_SERVICE, REFRESH_ACCOUNT).setPassword(credentials.refresh_token);
+            new ctor(KEYCHAIN_SERVICE, ACCESS_ACCOUNT).setPassword(JSON.stringify({ access_token: credentials.access_token, expires_at: credentials.expires_at }));
+            // Remove any stale file copy so there is a single source of truth.
+            fs.rmSync(credentialsFilePath(), { force: true });
+            return;
+        }
+        catch {
+            // keychain present but unusable (locked, headless, …) — fall back
+        }
+    }
+    if (backendOverride() !== "file")
+        warnKeychainUnavailable();
+    fileWrite(credentials);
+}
+/** Clear both backends (login/logout/invalid_grant paths). */
+function clearCredentials() {
+    keychainDelete(REFRESH_ACCOUNT);
+    keychainDelete(ACCESS_ACCOUNT);
+    fs.rmSync(credentialsFilePath(), { force: true });
+}
+function expiresWithin(credentials, marginMs = exports.EXPIRY_MARGIN_MS) {
+    const at = Date.parse(credentials.expires_at);
+    if (Number.isNaN(at))
+        return true;
+    return at - Date.now() <= marginMs;
+}
+/** Mask a token for display: `at-let-…abcd`. Never print tokens unmasked. */
+function maskToken(token) {
+    const prefixMatch = token.match(/^[a-z]{2}-let-/);
+    const prefix = prefixMatch ? prefixMatch[0] : token.slice(0, 3);
+    const suffix = token.length >= prefix.length + 8 ? token.slice(-4) : "";
+    return `${prefix}…${suffix}`;
+}

package/dist/auth/index.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Auth entry point for the Dreams CLI.
+ *
+ * Precedence for resolving an auth header:
+ *   1. LETTA_API_KEY env var — used verbatim; never refreshed, never stored.
+ *   2. Stored Dreams credentials — refreshed when missing/expiring within 5 min.
+ *   3. Otherwise: NotAuthenticatedError telling the caller to run
+ *      `dreams auth login`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotAuthenticatedError = void 0;
+exports.resolveAccessToken = resolveAccessToken;
+exports.getAuthHeader = getAuthHeader;
+exports.authStatusInfo = authStatusInfo;
+const store_1 = require("../store");
+const credentials_1 = require("./credentials");
+Object.defineProperty(exports, "NotAuthenticatedError", { enumerable: true, get: function () { return credentials_1.NotAuthenticatedError; } });
+const oauth_refresh_1 = require("./oauth-refresh");
+async function resolveAccessToken() {
+    const envKey = process.env.LETTA_API_KEY;
+    if (envKey) {
+        return { token: envKey, source: "env" };
+    }
+    const stored = (0, credentials_1.loadCredentials)();
+    if (!stored) {
+        throw new credentials_1.NotAuthenticatedError();
+    }
+    if (stored.credentials.access_token && !(0, credentials_1.expiresWithin)(stored.credentials)) {
+        return { token: stored.credentials.access_token, source: stored.source };
+    }
+    const deviceId = (0, store_1.loadOrCreateInstallation)().installation_id;
+    const refreshed = await (0, oauth_refresh_1.refreshCredentialsSingleFlight)(stored.credentials, deviceId);
+    return { token: refreshed.access_token, source: stored.source };
+}
+/** Auth header for the (future) upload client. */
+async function getAuthHeader() {
+    const { token } = await resolveAccessToken();
+    return { authorization: `Bearer ${token}` };
+}
+/** 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,
+            source: "env",
+            access_token: (0, credentials_1.maskToken)(envKey),
+            expires_at: null,
+            device_id,
+        };
+    }
+    const stored = (0, credentials_1.loadCredentials)();
+    if (!stored) {
+        return { authenticated: false, source: null, access_token: null, expires_at: null, device_id };
+    }
+    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,
+        device_id,
+    };
+}