@letta-ai/dreams 0.0.1 → 0.0.4

package/dist/skill.js

@@ -35,6 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.skillDir = skillDir;
 exports.skillFilePath = skillFilePath;
+exports.initSnapshotTemplatePath = initSnapshotTemplatePath;
+exports.claudeHooksReferencePath = claudeHooksReferencePath;
+exports.codexHooksReferencePath = codexHooksReferencePath;
+exports.codexSyncHookScriptPath = codexSyncHookScriptPath;
 exports.installedSkillVersion = installedSkillVersion;
 exports.installSkill = installSkill;
 const crypto = __importStar(require("node:crypto"));
@@ -50,6 +54,18 @@ function skillDir() {
 function skillFilePath() {
     return path.join(skillDir(), "SKILL.md");
 }
+function initSnapshotTemplatePath() {
+    return path.join(skillDir(), "references", "init-snapshot.template.json");
+}
+function claudeHooksReferencePath() {
+    return path.join(skillDir(), "references", "hooks-claude.md");
+}
+function codexHooksReferencePath() {
+    return path.join(skillDir(), "references", "hooks-codex.md");
+}
+function codexSyncHookScriptPath() {
+    return path.join(skillDir(), "references", "codex-sync-hook.cjs");
+}
 function skillContent(version) {
     return `---
 name: dreams-setup
@@ -59,30 +75,360 @@ version: ${version}
 
 # Dreams setup
 
-Start or repair the local setup with:
+CLI owns side effects. This skill owns sequencing and user conversation. There is no durable resume pointer: in a new conversation, start at step 1 and skip work that durable facts show is already satisfied. Never blindly repeat mutations. Never print or summarize access tokens, refresh tokens, credential files, or keychain contents. Never interpolate credential env vars into shell commands, even partially.
+
+## Invariants
+
+- Quote absolute \`cli_path\` from onboard in every hook/command.
+- Never print tokens. Never invent teammate emails — derive them from git (step 3).
+- Deny-by-default: without an approved directory, nothing uploads. Do not offer “continue without approving a directory.”
+- Live hooks require consent. Do not offer “skip hooks and continue setup” — if the user declines hooks, exit setup (they can re-enter later).
+- SessionStart → \`dreams wake\`; Stop → \`dreams sync\`. Do not install \`sync\` on SessionStart.
+- Prefer \`dreams hooks install --dry-run\` before writing hook files; CLI owns the merge.
+
+## Step 0 — Local bootstrap (optional repair)
+
+If the durable CLI or this skill may be missing, run:
 
 \`\`\`bash
 npx @letta-ai/dreams@latest onboard --json
 \`\`\`
 
-\`onboard\` installs an exact CLI version at a stable local path, creates or reuses the installation identity, installs this skill, initializes local SQLite, and checks authentication. It does not log in or run \`orient\` itself.
+\`onboard\` installs or repairs the durable CLI, installation identity, this skill (including reference files), and local SQLite. It does **not** check authentication or choose the next setup step. On success it returns \`status: "ready"\` with absolute \`cli_path\` and \`skill.path\`. Use that \`cli_path\` for later Dreams commands and for harness hook commands.
+
+## Step 1 — Authenticate
+
+1. Run \`"<cli_path>" auth status --json\` (or \`dreams auth status --json\` after onboard).
+2. Read the inventory, not only the top-level winner:
+   - \`credentials[]\` lists every discovered backend (\`env\`, \`keychain\`, \`file\`) with \`present\`, \`selected\`, masked token, and \`reason\`.
+   - \`active\` is which credential won for **this process** and why.
+   - \`hooks\` explains that live sync inherits the **coding-agent harness environment**. Verify the credential hooks will use, not only an interactive CLI.
+3. If unauthenticated, run \`dreams auth login --json\`, wait for browser approval (JSON Lines: \`awaiting_approval\` then \`authenticated\`), then re-check \`auth status\`.
+4. Prefer an existing usable credential; do not force a new login when already authenticated.
+
+## Step 2 — Detect and register sources
+
+Detect each registered harness with an **explicit** adapter. Do **not** install hooks here.
+
+\`\`\`bash
+"<cli_path>" source detect --source claude-code --json
+"<cli_path>" source detect --source codex --json
+\`\`\`
+
+Record which harnesses were present (\`harness_present: true\` / exit 0). A missing harness is expected on machines that only run one coding agent — continue with whichever registered successfully.
+
+## Step 3 — Init snapshot (seed smarter memory)
+
+**Why this step exists (tell the user):** A short workspace snapshot helps Dreams start with useful structure — so early memories are more targeted and relevant to their real repos, teammates, and tools — instead of a blank slate. Prefer asking over inventing. Memories are more meaningful when they begin from a smart seed of how this person actually works.
+
+1. Read \`references/init-snapshot.template.json\` (field ranking is in \`$comment\` / \`$field_guide\`).
+2. **Approved directories (required for later sync):** identify which work directories should be eligible (usually the user’s main code tree). You will approve them in step 4 with \`source approve-dir\`. Put the intended paths in \`scope.approved_roots\` (JSON key unchanged for Cloud; user-facing language is **directories**, not “roots”).
+3. **Repositories:** prefer deeper metadata for directories with recent Claude/Codex sessions; name-only or light metadata for the long tail is fine. Deduplicate multi-clone remotes (one logical repo + optional \`local_clone_count\`).
+4. **Skills:** recursively search the repositories you listed for skill directories (\`.claude/skills\`, \`.agents/skills\`, \`**/skills\` when clearly agent-skill trees). Prefer \`{ directory, skill_count, sample_names }\` over dumping every name when large.
+5. **Teammates — do not AskUserQuestion.** Derive from recent git commits in the target repos (\`git log\` / shortlog). Include display name + email identity signals. **Exclude bots and agents** (e.g. names/emails containing \`[bot]\`, \`dependabot\`, \`github-actions\`, \`renovate\`, \`cursoragent\`, \`noreply\` automation accounts). Cap to a reasonable set of frequent human contributors.
+6. **Omit unknowns** rather than writing \`0\` or empty arrays for optional fields. Do **not** invent \`letta_agent_count\`, \`letta_memory_artifact_count\`, or \`allowlisted_file_names\`.
+7. Include every harness detected in step 2. Write concrete JSON (no teammate \`role\`; no \`scope.mode\`).
+8. Show the JSON and obtain explicit approval, then submit:
+
+\`\`\`bash
+"<cli_path>" snapshots create --type init --file /path/to/approved-init.json --client-request-id <unique-id> --json
+\`\`\`
+
+Reuse the same \`client-request-id\` only when retrying the exact same approved payload. Snapshot submit stores the fact; it does not create the shared-memory repository. If snapshot submit fails with auth/role errors, explain briefly and **continue** — directories + hooks + history still deliver value.
+
+## Step 4 — Enable live sync (directories + hooks)
+
+This step turns on ongoing sync. There is no separate “activate / sync --force” ceremony afterward.
+
+### 4a — Approve directories (required)
+
+Deny-by-default: nothing leaves the machine until at least one work directory is approved.
+
+1. Explain in plain language: Dreams will only consider transcripts whose working directory sits under an approved folder.
+2. Obtain consent for specific paths (from step 3 intent / session inventory). **Do not** offer “proceed without approving a directory.”
+3. Approve with the preferred alias:
+
+\`\`\`bash
+"<cli_path>" source approve-dir "<path>" --json
+\`\`\`
+
+(\`source approve-root\` still works as a synonym.)
+
+### 4b — Install hooks (required for live sync)
+
+**Consent:** name which harnesses from step 2 will get live sync (Claude Code and/or Codex). Explain this enables **ongoing transcript sync** on future sessions. If the user declines, **exit setup** (do not continue as if onboarding succeeded). Per-harness opt-out is OK when both were detected (wire only the consented ones).
+
+1. **Dry-run first** — show the user the exact planned commands/files:
+
+\`\`\`bash
+"<cli_path>" hooks install --dry-run --json
+# or per source:
+"<cli_path>" hooks install --source claude-code --dry-run --json
+"<cli_path>" hooks install --source codex --dry-run --json
+\`\`\`
+
+2. After approval, install (CLI owns the merge — do not hand-edit when the CLI succeeds):
+
+\`\`\`bash
+"<cli_path>" hooks install --json
+\`\`\`
+
+3. Confirm wiring from references if you need detail: \`references/hooks-claude.md\`, \`references/hooks-codex.md\`, and the Codex launcher \`references/codex-sync-hook.cjs\`.
+   - **SessionStart → \`wake\`** (CLI/skill repair + kick pending backfill/sync worker)
+   - **Stop → \`sync\`** (live turn; stdin session hint)
+4. For Codex: ask the user to run \`/hooks\`, review, and **trust** the handlers. File write ≠ trusted ≠ Cloud upload succeeded.
+
+### Hook diagnostics (reference)
+
+When live sync seems broken:
+
+1. \`"<cli_path>" status --json\`
+2. \`"<cli_path>" sync status --source claude-code --json\` / \`--source codex\`
+   - \`paused\` / \`not_due\` → expected quiet wake
+   - \`pending\` / \`running\` → work in flight
+   - \`degraded\` → inspect \`last_error_code\` (e.g. \`spawn_failed\`)
+3. Claude hooks must stay silent (exit 0). Codex launcher prints only \`{}\`.
+
+## Step 5 — Optional: import recent history
+
+Only if the user wants older transcripts. Historical import is **optional**, runs in the **background**, and is **resumable** across later \`wake\`/\`sync\` — sleep and restarts are fine. Choose the history that is useful; do not pressure for a tiny window.
+
+**Copy for the user:** calm and encouraging. Avoid harsh openers like “Optional; drains in bounded slices over time.” Prefer: “We can import recent history in the background — it’s resumable, so a wider window is a safe pick.”
+
+**Window choices to offer:** 30 days · 90 days · 180 days · all available history (still bounded by what exists on disk; CLI freezes \`until_at = now\`). When possible, give a rough sense of scale (how many sessions / projects sit under approved directories) before they choose.
+
+Live-hook consent does **not** grant historical-import consent. Ask which **detected** sources should import history.
+
+If the user opts in:
+
+1. Agree \`--since <RFC3339>\` (sessions modified since that time through now; selection is by transcript-file mtime).
+2. For each selected source, queue a slice, then **\`wake\`** so draining does not wait for the next session:
+
+\`\`\`bash
+"<cli_path>" backfill start --source claude-code --since <RFC3339> --json
+"<cli_path>" wake --source claude-code --json
+"<cli_path>" backfill start --source codex --since <RFC3339> --json
+"<cli_path>" wake --source codex --json
+\`\`\`
+
+3. Explain: live turns stay first; history continues in the background. Pause/resume without discarding progress:
+   \`"<cli_path>" sync pause\` / \`"<cli_path>" sync resume\`
+   Monitor: \`"<cli_path>" sync status --source claude-code --json\` (and codex as needed).
+
+Do **not** run unrestricted \`source scan\` or a ceremonial \`sync --force\` “smoke test” during setup. \`wake\` after backfill is the right kick; the first real Stop-hook \`sync\` under an approved directory confirms the live path.
+
+## Re-entry
+
+Inspect durable facts (\`auth status\`, \`source list\`, \`status\`, per-source \`sync status\`) and continue at the first incomplete step. Repeated \`onboard\`, \`source detect\`, approved snapshot retries, \`hooks install\`, and \`approve-dir\` are safe when they follow the rules above.
+`;
+}
+function initSnapshotTemplate() {
+    return `${JSON.stringify({
+        $comment: "Non-enforced init snapshot template. Cloud accepts any JSON object + 256 KiB cap. User-facing language: approved directories (JSON key remains scope.approved_roots). Do NOT include teammate role or scope.mode. Omit unknown optional fields rather than inventing zeros.",
+        $field_guide: {
+            high_value: "repositories (with remotes/languages for active work), harnesses, identity_signals, teammates (from git, humans only), scope.approved_roots, transcript_inventory, skills (repo-scanned counts), cli_version",
+            repository_detail: "Full metadata for repos with recent agent sessions; name/remote/language is enough for the long tail. Deduplicate clones; optional local_clone_count.",
+            instruction_files: "Agent instruction docs found in the repo (AGENTS.md, CLAUDE.md, MEMORY.md, etc.). Include name + size_bytes when present.",
+            omit_if_unknown: [
+                "letta_agent_count",
+                "letta_memory_artifact_count",
+                "allowlisted_file_names",
+                "skill_names on repositories (use top-level skills instead)",
+            ],
+        },
+        repositories: [
+            {
+                display_name: "my-repo",
+                git_remote_sanitized: "github.com/acme/my-repo",
+                primary_language: "typescript",
+                build_system: "nx",
+                instruction_files: [{ name: "AGENTS.md", size_bytes: 1024 }],
+            },
+        ],
+        harnesses: [{ name: "claude-code", version: "1.2.3" }],
+        skills: [
+            {
+                directory: "my-repo/.claude/skills",
+                skill_count: 1,
+                sample_names: ["deploy"],
+            },
+        ],
+        identity_signals: [{ type: "git_email", value: "dev@acme.com" }],
+        transcript_inventory: [{ source_key: "claude-code", session_count: 3 }],
+        teammates: [
+            {
+                display_name: "Alex",
+                identity_signals: [{ type: "git_email", value: "alex@acme.com" }],
+            },
+        ],
+        scope: { approved_roots: [] },
+        cli_version: (0, version_1.packageVersion)(),
+    }, null, 2)}\n`;
+}
+function claudeHooksReference() {
+    return `# Claude Code — Dreams live sync hooks
+
+Install **globally** in \`~/.claude/settings.json\` (user scope). Prefer \`dreams hooks install --dry-run\` / \`dreams hooks install\` so the CLI owns the merge. Manual merge is fallback only.
 
-## Follow the response
+## Goal
 
-1. Parse the single JSON document from stdout.
-2. Briefly explain \`agent_instructions\` to the user without pasting raw JSON.
-3. Run the exact command in \`next_action.command\`.
-4. Use the absolute \`cli_path\` from the response for later Dreams commands.
+- **SessionStart → \`dreams wake\`** — repair managed CLI/skill quietly; kick pending sync/backfill worker (no live-turn stdin hint).
+- **Stop → \`dreams sync\`** — after each live turn; pipe hook JSON stdin so \`session_id\` can be a live hint.
 
-When \`state\` is \`awaiting_auth\`, run the returned \`auth login --json\` command and wait for the user to approve in the browser. That login command emits JSON Lines: first \`awaiting_approval\`, then \`authenticated\`. After it succeeds, run the stable CLI's \`onboard --json\` command again.
+## Platform-specific commands
 
-When \`state\` is \`ready_for_orient\`, run the returned \`orient\` command.
+Replace \`CLI_PATH\` with the absolute \`cli_path\` from \`dreams onboard --json\`.
 
-Repeated \`onboard\` calls are safe. They repair missing local setup and return the same next action until authentication state changes.
+### macOS / Linux (bash)
 
-Never print or summarize access tokens, refresh tokens, credential files, or keychain contents.
+\`\`\`bash
+"CLI_PATH" wake >/dev/null 2>&1 || true # dreams-sync-hook
+"CLI_PATH" sync >/dev/null 2>&1 || true # dreams-sync-hook
+\`\`\`
+
+### Windows (PowerShell)
+
+\`\`\`powershell
+& 'CLI_PATH' wake *> $null; exit 0 # dreams-sync-hook
+& 'CLI_PATH' sync *> $null; exit 0 # dreams-sync-hook
+\`\`\`
+
+## Example merge fragment (macOS / Linux)
+
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\\"CLI_PATH\\" wake >/dev/null 2>&1 || true # dreams-sync-hook"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\\"CLI_PATH\\" sync >/dev/null 2>&1 || true # dreams-sync-hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
+## Example merge fragment (Windows)
+
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "powershell",
+            "command": "& 'CLI_PATH' wake *> $null; exit 0 # dreams-sync-hook"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "powershell",
+            "command": "& 'CLI_PATH' sync *> $null; exit 0 # dreams-sync-hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
+## Notes
+
+- Prefer \`dreams hooks install\` (with \`--dry-run\` for consent). Keep \`# dreams-sync-hook\` markers; update in place; never append duplicates.
+- Hooks must stay silent and exit 0. Silence is not proof of Cloud upload success.
+- \`dreams sync pause\` / \`dreams sync resume\` toggle without uninstalling.
+- Diagnostics: \`dreams sync status --json\`.
 `;
 }
+function codexHooksReference() {
+    return `# Codex — Dreams live sync hooks
+
+Install **user-level** hooks in \`~/.codex/hooks.json\`. Prefer \`dreams hooks install --dry-run\` / \`dreams hooks install\`.
+
+Also ensure:
+
+\`\`\`toml
+[features]
+hooks = true
+\`\`\`
+
+## Goal
+
+- **SessionStart → \`wake --source codex\`** via the Node launcher
+- **Stop → \`sync --source codex\`** via the Node launcher (forwards stdin; prints \`{}\`)
+
+## Why a Node launcher
+
+Codex Stop expects exactly one JSON object on stdout. Use \`references/codex-sync-hook.cjs\`:
+
+\`\`\`bash
+node "HOOK_SCRIPT" "CLI_PATH" wake # dreams-sync-hook-codex
+node "HOOK_SCRIPT" "CLI_PATH" sync # dreams-sync-hook-codex
+\`\`\`
+
+## Example merge fragment
+
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \\"HOOK_SCRIPT\\" \\"CLI_PATH\\" wake # dreams-sync-hook-codex"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \\"HOOK_SCRIPT\\" \\"CLI_PATH\\" sync # dreams-sync-hook-codex"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
+## Trust (\`/hooks\`)
+
+Ask the user to run \`/hooks\`, review, and trust. File write ≠ trusted ≠ Cloud upload succeeded.
+
+## Notes
+
+- Launcher stdout must be \`{}\\n\` with exit 0.
+- After backfill, kick with \`dreams wake --source codex --json\` (not a ceremonial sync --force smoke test).
+`;
+}
+function codexSyncHookScript() {
+    return fs.readFileSync(path.join(__dirname, "..", "bin", "dreams-codex-hook.cjs"), "utf8");
+}
 function readFile(file) {
     try {
         return fs.readFileSync(file, "utf8");
@@ -127,12 +473,23 @@ function installedSkillVersion() {
     const match = text.match(/^version:\s*(\S+)\s*$/m);
     return match ? match[1] : null;
 }
+function desiredArtifacts() {
+    return [
+        { path: skillFilePath(), contents: skillContent((0, version_1.packageVersion)()) },
+        { path: initSnapshotTemplatePath(), contents: initSnapshotTemplate() },
+        { path: claudeHooksReferencePath(), contents: claudeHooksReference() },
+        { path: codexHooksReferencePath(), contents: codexHooksReference() },
+        { path: codexSyncHookScriptPath(), contents: codexSyncHookScript() },
+    ];
+}
 function installSkill() {
     removeLegacyGeneratedSkill();
-    const desired = skillContent((0, version_1.packageVersion)());
-    const existing = readFile(skillFilePath());
-    if (existing === desired)
+    const artifacts = desiredArtifacts();
+    const existing = artifacts.map((artifact) => readFile(artifact.path));
+    const allSame = artifacts.every((artifact, index) => existing[index] === artifact.contents);
+    if (allSame)
         return "unchanged";
-    writeAtomic(skillFilePath(), desired);
-    return existing === null ? "installed" : "updated";
+    for (const artifact of artifacts)
+        writeAtomic(artifact.path, artifact.contents);
+    return existing[0] === null ? "installed" : "updated";
 }

package/dist/snapshots.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * `dreams snapshots create` — narrow CLI transport for skill-authored snapshots.
+ *
+ * Keeps credential handling, base URL selection, size checking, JSON-object
+ * validation, and idempotency keys inside the CLI. The skill authors the
+ * payload and obtains user approval before invoking this command.
+ *
+ * Workspace id is taken from the local binding written by `source detect`
+ * (or upload registration), matching the Cloud path
+ * POST /v1/dreams/workspaces/{workspaceId}/snapshots.
+ */
+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.commandSnapshotsCreate = commandSnapshotsCreate;
+exports.commandSnapshots = commandSnapshots;
+const fs = __importStar(require("node:fs"));
+const index_1 = require("./auth/index");
+const client_1 = require("./cloud/client");
+const db_1 = require("./local/db");
+const state_lock_1 = require("./local/state-lock");
+const store_1 = require("./store");
+const MAX_SNAPSHOT_BYTES = 256 * 1024;
+const MAX_TYPE_LEN = 64;
+const MAX_CLIENT_REQUEST_ID_LEN = 128;
+const TYPE_RE = /^[a-z][a-z0-9_-]*$/;
+const CLIENT_REQUEST_ID_RE = /^[A-Za-z0-9._:-]+$/;
+function emit(json, payload, human) {
+    if (json)
+        console.log(JSON.stringify(payload, null, 2));
+    else
+        console.log(human());
+}
+function validateType(type) {
+    if (!TYPE_RE.test(type) || type.length > MAX_TYPE_LEN) {
+        return `invalid --type (expected <=${MAX_TYPE_LEN} chars matching ${TYPE_RE})`;
+    }
+    return null;
+}
+function validateClientRequestId(id) {
+    if (!CLIENT_REQUEST_ID_RE.test(id) || id.length > MAX_CLIENT_REQUEST_ID_LEN) {
+        return `invalid --client-request-id (expected <=${MAX_CLIENT_REQUEST_ID_LEN} chars matching ${CLIENT_REQUEST_ID_RE})`;
+    }
+    return null;
+}
+function loadPayload(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        return { ok: false, message: `could not read --file: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const bytes = Buffer.byteLength(raw, "utf8");
+    if (bytes > MAX_SNAPSHOT_BYTES) {
+        return { ok: false, message: `snapshot exceeds ${MAX_SNAPSHOT_BYTES} byte UTF-8 cap (${bytes} bytes)` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return { ok: false, message: `snapshot is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, message: "snapshot payload must be a JSON object" };
+    }
+    return { ok: true, data: parsed, bytes };
+}
+function resolveWorkspaceId(explicit) {
+    if (explicit)
+        return explicit;
+    const installation = (0, store_1.loadOrCreateInstallation)();
+    const db = (0, db_1.openDb)({
+        installationId: installation.installation_id,
+        installationCreatedAt: installation.created_at,
+    });
+    try {
+        const row = db.prepare("SELECT workspace_id FROM workspace_bindings WHERE id = 1").get();
+        return row?.workspace_id ?? null;
+    }
+    finally {
+        (0, db_1.closeDb)();
+    }
+}
+async function commandSnapshotsCreate(args) {
+    if (!args.type || !args.file || !args.clientRequestId) {
+        process.stderr.write("Usage: dreams snapshots create --type <type> --file <path> --client-request-id <id> [--workspace-id <id>] [--json]\n");
+        return 1;
+    }
+    const typeError = validateType(args.type);
+    if (typeError) {
+        emit(args.json, { status: "error", code: "invalid_type", message: typeError }, () => typeError);
+        return 1;
+    }
+    const idError = validateClientRequestId(args.clientRequestId);
+    if (idError) {
+        emit(args.json, { status: "error", code: "invalid_client_request_id", message: idError }, () => idError);
+        return 1;
+    }
+    const loaded = loadPayload(args.file);
+    if (!loaded.ok) {
+        emit(args.json, { status: "error", code: "invalid_payload", message: loaded.message }, () => loaded.message);
+        return 1;
+    }
+    const lock = (0, state_lock_1.acquireLocalStateLock)();
+    if (lock === null) {
+        const message = "Another Dreams command is using local state. Try again after it finishes.";
+        emit(args.json, { status: "error", code: "local_state_busy", message }, () => message);
+        return 1;
+    }
+    try {
+        const workspaceId = resolveWorkspaceId(args.workspaceId);
+        if (!workspaceId) {
+            const message = "no workspace binding found; run `dreams source detect` first (or pass --workspace-id)";
+            emit(args.json, { status: "error", code: "workspace_unresolved", message }, () => message);
+            return 1;
+        }
+        try {
+            const result = await (0, client_1.createSnapshot)({
+                workspaceId,
+                type: args.type,
+                clientRequestId: args.clientRequestId,
+                data: loaded.data,
+            });
+            emit(args.json, {
+                status: "ok",
+                id: result.id,
+                type: result.type,
+                workspace_id: result.workspaceId,
+                client_request_id: result.clientRequestId,
+                snapshot_status: result.status,
+                created_at: result.createdAt,
+                bytes: loaded.bytes,
+            }, () => [
+                "Snapshot stored",
+                "",
+                `  Id:                 ${result.id}`,
+                `  Type:               ${result.type}`,
+                `  Workspace:          ${result.workspaceId}`,
+                `  Client request id:  ${result.clientRequestId}`,
+                `  Status:             ${result.status}`,
+                `  Bytes:              ${loaded.bytes}`,
+            ].join("\n"));
+            return 0;
+        }
+        catch (error) {
+            if (error instanceof index_1.NotAuthenticatedError) {
+                const message = "not authenticated: run `dreams auth login`";
+                emit(args.json, { status: "error", code: "not_authenticated", message }, () => message);
+                return 1;
+            }
+            if (error instanceof client_1.CloudAuthError) {
+                const message = `authentication failed: ${error.message}`;
+                emit(args.json, { status: "error", code: error.code ?? "auth_failed", message }, () => message);
+                return 1;
+            }
+            if (error instanceof client_1.CloudError) {
+                const message = error.message;
+                emit(args.json, { status: "error", code: error.retryable ? "retryable" : "cloud_error", message, retryable: error.retryable }, () => message);
+                return 1;
+            }
+            throw error;
+        }
+    }
+    finally {
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+    }
+}
+async function commandSnapshots(subcommand, args) {
+    switch (subcommand) {
+        case "create":
+            return commandSnapshotsCreate(args);
+        default:
+            process.stderr.write(`Unknown snapshots subcommand: ${subcommand ?? "(none)"} — expected create\n`);
+            return 1;
+    }
+}

package/dist/suppress-sqlite-warning.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * node:sqlite still emits ExperimentalWarning on load in Node 22.x even though
+ * the flag is no longer required at >= 22.13. Filter only that warning so agent
+ * transcripts and --json workflows stay clean; leave other warnings alone.
+ *
+ * Must run before the first `node:sqlite` import (see cli.ts import order and
+ * bin/dreams.cjs preflight).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suppressSqliteExperimentalWarning = suppressSqliteExperimentalWarning;
+const SQLITE_EXPERIMENTAL = /SQLite is an experimental feature|ExperimentalWarning:.*SQLite|node:sqlite/i;
+let installed = false;
+function suppressSqliteExperimentalWarning() {
+    if (installed)
+        return;
+    installed = true;
+    const originalEmit = process.emit.bind(process);
+    function filteredEmit(event, ...args) {
+        if (event === "warning" && args.length > 0) {
+            const warning = args[0];
+            if (warning &&
+                typeof warning === "object" &&
+                warning.name === "ExperimentalWarning" &&
+                typeof warning.message === "string" &&
+                SQLITE_EXPERIMENTAL.test(warning.message)) {
+                return false;
+            }
+        }
+        return Reflect.apply(originalEmit, process, [event, ...args]);
+    }
+    process.emit = filteredEmit;
+}
+suppressSqliteExperimentalWarning();