@letta-ai/dreams 0.0.1 → 0.0.4

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,
+        },
     };
 }

package/dist/cli.js

@@ -2,49 +2,158 @@
 /** @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");
 const commands_2 = require("./local/commands");
 const db_1 = require("./local/db");
+const state_lock_1 = require("./local/state-lock");
+const launcher_1 = require("./launcher");
 const managed_install_1 = require("./managed-install");
 const onboard_1 = require("./onboard");
+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]
 
 Commands:
-  onboard                    Install Dreams locally and return the next setup action
+  onboard                    Install Dreams locally and hand off to the setup skill
+  rollback                   Reactivate the previous installed CLI version
   status                     Show installation, skill, CLI, database, and auth state
   auth login                 Connect this device to Letta (OAuth device code flow)
   auth status                Show authentication state (never prints tokens)
   auth logout                Revoke Dreams' refresh token and clear stored credentials
-  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
+  dev reset local            Preview/reset local SQLite and blob state
+  dev reset identity         Preview/reset local state, credentials, and device identity
+  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
+  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
 
 Options:
-  --json     Machine-readable JSON output
-  --version  Print the CLI version
-  --help     Show this help
+  --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>        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)
+  --client-request-id <id>  Idempotency key (with snapshots create)
+  --workspace-id <id>    Override workspace id (defaults to local binding)
+  --version              Print the CLI version
+  --help                 Show this help
 `;
-const COMMANDS_WITH_SUBCOMMANDS = new Set(["auth", "source"]);
+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,
+        worker: false,
+        source: undefined,
+        since: undefined,
+        type: undefined,
+        file: undefined,
+        clientRequestId: undefined,
+        workspaceId: undefined,
         unknown: [],
     };
-    for (const arg of argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
         if (arg === "--json")
             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")
+            parsed.worker = true;
+        else if (arg === "--source") {
+            const value = argv[++i];
+            if (value === undefined || value.trim() === "")
+                parsed.unknown.push("--source");
+            else
+                parsed.source = value;
+        }
+        else if (arg.startsWith("--source=")) {
+            const value = arg.slice("--source=".length);
+            if (value.trim() === "")
+                parsed.unknown.push("--source=");
+            else
+                parsed.source = value;
+        }
         else if (arg === "--help" || arg === "-h")
             parsed.help = true;
         else if (arg === "--version" || arg === "-v")
             parsed.version = true;
+        else if (arg === "--since") {
+            const value = argv[++i];
+            if (value === undefined)
+                parsed.unknown.push("--since");
+            else
+                parsed.since = value;
+        }
+        else if (arg.startsWith("--since="))
+            parsed.since = arg.slice("--since=".length);
+        else if (arg === "--type") {
+            const value = argv[++i];
+            if (value === undefined)
+                parsed.unknown.push("--type");
+            else
+                parsed.type = value;
+        }
+        else if (arg.startsWith("--type="))
+            parsed.type = arg.slice("--type=".length);
+        else if (arg === "--file") {
+            const value = argv[++i];
+            if (value === undefined)
+                parsed.unknown.push("--file");
+            else
+                parsed.file = value;
+        }
+        else if (arg.startsWith("--file="))
+            parsed.file = arg.slice("--file=".length);
+        else if (arg === "--client-request-id") {
+            const value = argv[++i];
+            if (value === undefined)
+                parsed.unknown.push("--client-request-id");
+            else
+                parsed.clientRequestId = value;
+        }
+        else if (arg.startsWith("--client-request-id=")) {
+            parsed.clientRequestId = arg.slice("--client-request-id=".length);
+        }
+        else if (arg === "--workspace-id") {
+            const value = argv[++i];
+            if (value === undefined)
+                parsed.unknown.push("--workspace-id");
+            else
+                parsed.workspaceId = value;
+        }
+        else if (arg.startsWith("--workspace-id=")) {
+            parsed.workspaceId = arg.slice("--workspace-id=".length);
+        }
         else if (arg.startsWith("-"))
             parsed.unknown.push(arg);
         else
@@ -52,14 +161,17 @@ function parseArgs(argv) {
     }
     return parsed;
 }
-function commandStatus(json) {
+function commandStatusUnlocked(json) {
     const installation = (0, store_1.loadOrCreateInstallation)();
     const auth = (0, index_1.authStatusInfo)();
+    const activation = (0, launcher_1.readActivation)();
     const status = {
         installation_id: installation.installation_id,
         installation_created_at: installation.created_at,
         state: auth.authenticated ? "authenticated" : "unauthenticated",
         cli_path: (0, managed_install_1.stableCliPath)(),
+        active_cli_version: activation?.active_version ?? null,
+        previous_cli_version: activation?.previous_version ?? null,
         database_path: (0, db_1.dbFilePath)(),
         skill_version: (0, skill_1.installedSkillVersion)(),
         skill_path: (0, skill_1.skillFilePath)(),
@@ -72,7 +184,7 @@ function commandStatus(json) {
     else {
         const authLine = auth.authenticated
             ? `yes (via ${auth.source}, token ${auth.access_token ?? "pending refresh"}${auth.expires_at ? `, expires ${auth.expires_at}` : ""})`
-            : "no (run `dreams onboard`)";
+            : "no (run `dreams auth login`)";
         console.log([
             "Dreams status",
             "",
@@ -80,6 +192,8 @@ function commandStatus(json) {
             `  Created at:      ${status.installation_created_at}`,
             `  State:           ${status.state}`,
             `  Durable CLI:     ${status.cli_path}`,
+            `  Active version:  ${status.active_cli_version ?? "(not activated)"}`,
+            `  Previous version:${status.previous_cli_version ? ` ${status.previous_cli_version}` : " (none)"}`,
             `  Skill installed: ${status.skill_version ? `v${status.skill_version} at ${status.skill_path}` : "no"}`,
             `  Authenticated:   ${authLine}`,
             `  Database:        ${status.database_path}`,
@@ -88,6 +202,23 @@ function commandStatus(json) {
     }
     return 0;
 }
+async function commandStatus(json) {
+    const lock = await (0, state_lock_1.waitForLocalStateLock)();
+    if (lock === null) {
+        const message = "Another Dreams command is using local state. Try again after it finishes.";
+        if (json)
+            console.log(JSON.stringify({ status: "error", code: "local_state_busy", message }));
+        else
+            process.stderr.write(message + "\n");
+        return 1;
+    }
+    try {
+        return commandStatusUnlocked(json);
+    }
+    finally {
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+    }
+}
 function commandAuth(subcommand, json) {
     switch (subcommand) {
         case "login":
@@ -101,6 +232,17 @@ function commandAuth(subcommand, json) {
             return 1;
     }
 }
+function commandDevelopment(positionals, confirmed, json) {
+    if (positionals[1] !== "reset") {
+        process.stderr.write(`Unknown dev subcommand: ${positionals[1] ?? "(none)"} — expected reset\n\n${USAGE}`);
+        return 1;
+    }
+    if (positionals.length > 3) {
+        process.stderr.write(`Unexpected argument(s): ${positionals.slice(3).join(", ")}\n\n${USAGE}`);
+        return 1;
+    }
+    return (0, development_reset_1.commandDevelopmentReset)(positionals[2], confirmed, json);
+}
 async function runCli() {
     const args = parseArgs(process.argv.slice(2));
     const command = args.positionals[0];
@@ -113,6 +255,36 @@ async function runCli() {
         process.stdout.write(USAGE);
         return args.help ? 0 : 1;
     }
+    if (args.confirm && (command !== "dev" || subcommand !== "reset")) {
+        process.stderr.write(`--confirm is only valid with \`dreams dev reset\`\n\n${USAGE}`);
+        return 1;
+    }
+    if ((args.type || args.file || args.clientRequestId || args.workspaceId) && command !== "snapshots") {
+        process.stderr.write(`Snapshot options are only valid with \`dreams snapshots create\`\n\n${USAGE}`);
+        return 1;
+    }
+    if ((args.force || args.worker) && command !== "sync") {
+        process.stderr.write(`--force/--worker are only valid with \`dreams sync\`\n\n${USAGE}`);
+        return 1;
+    }
+    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") {
+        process.stderr.write(`--since is only valid with \`dreams backfill start\`\n\n${USAGE}`);
+        return 1;
+    }
     if (args.unknown.length > 0) {
         process.stderr.write(`Unknown argument(s): ${args.unknown.join(", ")}\n\n${USAGE}`);
         return 1;
@@ -122,23 +294,77 @@ async function runCli() {
         process.stderr.write(`Unexpected argument(s): ${args.positionals.slice(1).join(", ")}\n\n${USAGE}`);
         return 1;
     }
+    if (command === "snapshots" && args.positionals.length > 2) {
+        process.stderr.write(`Unexpected argument(s): ${args.positionals.slice(2).join(", ")}\n\n${USAGE}`);
+        return 1;
+    }
+    if (command === "sync" && args.positionals.length > 2) {
+        process.stderr.write(`Unexpected argument(s): ${args.positionals.slice(2).join(", ")}\n\n${USAGE}`);
+        return 1;
+    }
+    if (command === "backfill" && args.positionals.length > 2) {
+        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);
+        case "rollback":
+            return (0, launcher_1.commandRollback)(args.json);
         case "status":
             return commandStatus(args.json);
         case "auth":
             return commandAuth(subcommand, args.json);
+        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,
+                file: args.file,
+                clientRequestId: args.clientRequestId,
+                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,
+                force: args.force,
+                worker: args.worker,
+                sourceType: args.source,
+            });
+        case "backfill":
+            if (subcommand !== "start") {
+                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, 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;
     }
 }
 function main() {
+    (0, launcher_1.signalLauncherReady)();
     runCli().then((code) => process.exit(code), (error) => {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         process.exit(1);

package/dist/cloud/client.js

@@ -42,8 +42,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CloudError = exports.CloudAuthError = void 0;
+exports.CLOUD_UPLOAD_MAX_CONTENT_CHARS = exports.CloudError = exports.CloudAuthError = void 0;
+exports.setCloudUploadMaxContentCharsForTests = setCloudUploadMaxContentCharsForTests;
+exports.encodeUploadContent = encodeUploadContent;
 exports.registerSource = registerSource;
+exports.createSnapshot = createSnapshot;
 exports.uploadObject = uploadObject;
 const zlib = __importStar(require("node:zlib"));
 const index_1 = require("../auth/index");
@@ -71,6 +74,33 @@ exports.CloudError = CloudError;
 // Comfortably below the source lease TTL (30s) so a stalled request cannot
 // outlive the lease and let another process reclaim it mid-flight.
 const REQUEST_TIMEOUT_MS = 20_000;
+/**
+ * Cloud `createUploadBodySchema.content` max: base64 of gzip'd bytes (not the
+ * uncompressed transcript). Enforced locally so oversized payloads quarantine
+ * without a wasted round trip ([Amelia] two-limit model).
+ */
+exports.CLOUD_UPLOAD_MAX_CONTENT_CHARS = 8 * 1024 * 1024;
+let cloudUploadMaxContentCharsForTests = null;
+/** Test-only override for the encoded upload size gate. Pass null to clear. */
+function setCloudUploadMaxContentCharsForTests(value) {
+    cloudUploadMaxContentCharsForTests = value;
+}
+function cloudUploadMaxContentChars() {
+    return cloudUploadMaxContentCharsForTests ?? exports.CLOUD_UPLOAD_MAX_CONTENT_CHARS;
+}
+/** Gzip + base64 encode transcript bytes and enforce the Cloud content char cap. */
+function encodeUploadContent(bytes, maxContentChars = cloudUploadMaxContentChars()) {
+    const content = zlib.gzipSync(bytes).toString("base64");
+    if (content.length > maxContentChars) {
+        return {
+            ok: false,
+            code: "payload_too_large",
+            message: `gzip+base64 upload content is ${content.length} chars; Cloud maximum is ${maxContentChars}`,
+            encodedLength: content.length,
+        };
+    }
+    return { ok: true, content, encodedLength: content.length };
+}
 function errorDetail(error) {
     const cause = error.cause;
     return cause?.code || cause?.message || (error instanceof Error ? error.message : String(error));
@@ -144,7 +174,7 @@ function classifyAuthOrRetry(status, json, path) {
  * id, so it is also how the CLI resolves the workspace.
  */
 async function registerSource(input) {
-    const r = await request("POST", "/v1/dreams/sources", {
+    const body = {
         source_type: input.sourceType,
         source_key: input.sourceKey,
         display_name: input.displayName,
@@ -152,7 +182,16 @@ async function registerSource(input) {
         adapter_version: input.adapterVersion,
         privacy_config_hash: input.privacyConfigHash ?? null,
         backfill_policy: input.backfillPolicy ?? null,
-    });
+    };
+    if (input.status != null)
+        body.status = input.status;
+    if (input.cliVersion != null)
+        body.cli_version = input.cliVersion;
+    if (input.skillVersion != null)
+        body.skill_version = input.skillVersion;
+    if (input.platform != null)
+        body.platform = input.platform;
+    const r = await request("POST", "/v1/dreams/sources", body);
     if (r.status !== 200 && r.status !== 201)
         classifyAuthOrRetry(r.status, r.json, "sources");
     const id = r.json?.id;
@@ -164,14 +203,59 @@ async function registerSource(input) {
         workspaceId: typeof r.json?.workspace_id === "string" ? r.json.workspace_id : null,
     };
 }
+/**
+ * Narrow transport for skill-authored snapshots ([11] / LET-9833).
+ * Validation beyond JSON-object + size belongs on the server.
+ *
+ * Cloud contract: POST /v1/dreams/workspaces/{workspaceId}/snapshots
+ * with body `{ type, data, client_request_id }`.
+ */
+async function createSnapshot(input) {
+    const path = `/v1/dreams/workspaces/${encodeURIComponent(input.workspaceId)}/snapshots`;
+    const r = await request("POST", path, {
+        type: input.type,
+        client_request_id: input.clientRequestId,
+        data: input.data,
+    });
+    if (r.status !== 200 && r.status !== 201)
+        classifyAuthOrRetry(r.status, r.json, "snapshots");
+    const id = r.json?.id;
+    if (typeof id !== "string")
+        throw new CloudError("snapshot response missing id", { retryable: true });
+    return {
+        id,
+        type: typeof r.json?.type === "string" ? r.json.type : input.type,
+        workspaceId: input.workspaceId,
+        clientRequestId: typeof r.json?.client_request_id === "string" ? r.json.client_request_id : input.clientRequestId,
+        status: typeof r.json?.status === "string" ? r.json.status : "stored",
+        createdAt: typeof r.json?.created_at === "string" ? r.json.created_at : null,
+    };
+}
 async function uploadObject(input) {
-    const content = zlib.gzipSync(input.bytes).toString("base64");
+    // Prefer a preflight-encoded body; otherwise encode here (defense in depth).
+    const gated = input.encodedContent !== undefined
+        ? input.encodedContent.length > cloudUploadMaxContentChars()
+            ? {
+                ok: false,
+                code: "payload_too_large",
+                message: `gzip+base64 upload content is ${input.encodedContent.length} chars; Cloud maximum is ${cloudUploadMaxContentChars()}`,
+                encodedLength: input.encodedContent.length,
+            }
+            : {
+                ok: true,
+                content: input.encodedContent,
+                encodedLength: input.encodedContent.length,
+            }
+        : encodeUploadContent(input.bytes);
+    if (!gated.ok) {
+        return { kind: "quarantine", code: gated.code, message: gated.message };
+    }
     const r = await request("POST", "/v1/dreams/uploads", {
         source_id: input.sourceId,
         client_upload_id: input.clientUploadId,
         content_sha256: input.contentSha256,
         content_encoding: "gzip+base64",
-        content,
+        content: gated.content,
         source_schema: input.sourceSchema,
         source_metadata: input.sourceMetadata,
         priority: input.priority,