dreamlayer 0.4.0-beta.1 → 0.4.0-beta.2

package/README.md

@@ -21,6 +21,7 @@ dreamlayer cutout <image> [--out file.png]      # background removal
 dreamlayer upscale <image> [--out file.png]     # 2x
 dreamlayer answer <conversation-id> <text> [--image file.png]
 dreamlayer status <execution-id>
+dreamlayer download <execution-id> --out file.png
 dreamlayer balance                              # spends nothing
 dreamlayer capabilities                         # spends nothing
 ```
@@ -77,28 +78,28 @@ dreamlayer balance --json
 
 ## Retries are safe if you reuse the key
 
-An idempotency key is generated per run. After an uncertain response, pass the same one
-back and the original result replays instead of paying twice:
+Save a key before starting text generation. After an uncertain response, reuse that key
+and the identical prompt/options, or check the existing execution first:
 
 ```bash
 dreamlayer generate "a fox logo" --idempotency-key fox-001
 ```
 
-## A question is not a failure
+## Continue a question from another client
 
-An edit-shaped prompt with no image exits 6 and asks for one:
+The CLI's `generate`, `edit`, `cutout`, `upscale`, and `sprite` commands select their
+operation explicitly. `generate "remove the background"` therefore remains a
+text-to-image request; use `cutout image.png` to remove a background.
+
+A conversational request made through the API or MCP can instead ask for missing
+input. Continue that conversation from the CLI using its saved conversation ID:
 
 ```bash
-dreamlayer generate "remove the background"
-# Which image should I use? Upload or attach one, then respond.
-#   dreamlayer answer <id> "your answer" --image <file>
+dreamlayer answer <conversation-id> "Use this image" --image reference.png
 ```
 
-Answer it with the image attached. Words alone are refused, because the question is
-asking for a picture, not a clarification.
-
-Naming an operation avoids the round trip entirely, which is why `cutout`, `upscale`,
-`edit`, and `generate` all do.
+An answer that needs an image must attach one. Exit code 6 means the returned
+conversation needs input; it does not mean a generation failed.
 
 ## Requirements
 
@@ -124,3 +125,45 @@ dreamlayer status EXECUTION_ID
 Set `--max-credits` to the amount you approve after checking the current price. The CLI reconnects to existing work if an event stream closes.
 
 For affordability, compare the complete rounded quote in **credits** with `available`. One tenth of a credit is $0.017. Promotional and purchased amounts are displayed rounded down separately, so their displayed sum can be 0.1 credit below `available`; stored fractions are preserved. Compare against the combined total, not that sum. The order charge rounds only once, never per frame or per tier.
+
+## Automating recovery
+
+Commands never prompt. `--json` sends results to stdout and structured errors to stderr,
+including usage and transport errors. Exit 0 from `status` means the read succeeded;
+inspect its `status` field to learn whether the execution completed.
+
+After a lost download, recover the existing execution without generation:
+
+```sh
+dreamlayer status EXECUTION_ID --json
+dreamlayer download EXECUTION_ID --out recovered.png --json
+```
+
+All output commands refuse to overwrite existing files, directories, or symlinks.
+Paid commands check `--out` before uploads or `/v1/execute`: an existing destination
+returns `output_exists` (exit 1) without submitting or charging a new job. A missing or
+unwritable parent returns `output_unavailable` (exit 1). Re-running a batch with the
+same output paths therefore stops on completed files before paid work. Choose a new
+path only for intentionally new work. The final write is still exclusive: if another
+process creates the destination during generation, use the saved execution ID to
+recover the completed output with `download`.
+
+`download` also refuses to overwrite a file. Use `.zip` for sprite results. Generation errors
+in JSON include the available execution ID and idempotency key for recovery. Treat them
+as private identifiers. For file-based commands, rerunning uploads a new asset: the same
+local file is not an identical API request. Prefer `status` and `download`, or the
+[execution recovery guide](https://docs.dreamlayer.io/agent-api/jobs-and-events).
+
+[API overview](https://docs.dreamlayer.io/agent-api) ·
+[CLI guide](https://docs.dreamlayer.io/cli) ·
+[MCP setup](https://docs.dreamlayer.io/mcp/index)
+
+Local client failures are separate from API generation failures. `local_output_failed`
+(exit 1) means the completed output could not be written; fix the destination and run
+`download` with the saved execution ID. `download_failed` or `output_not_ready` (exit 5)
+also require recovery of existing work, not a new generation. `retryable: true` means
+retry the indicated recovery action, never blindly repeat a paid command.
+`local_input_failed` (exit 1) means no readable input was supplied; missing credentials
+use `authentication_failed` (exit 2). A cancelled run uses `execution_cancelled`, exit 4,
+and a JSON error on stderr. Unknown client failures use `client_error`; they do not
+prove that the server-side generation failed.

package/dist/cli.js

@@ -1,25 +1,10 @@
 #!/usr/bin/env node
 import { spriteCreditPrice } from "./client.js";
-/**
- * DreamLayer CLI.
- *
- * Generate and edit images from a terminal, over local files. The API is the same one
- * the MCP server and the web app use, and it spends from the same credit balance.
- *
- * Exit codes are meaningful, so this composes in a script:
- *   0  success
- *   1  usage error
- *   2  authentication or account problem (401, 403)
- *   3  out of credits (402)
- *   4  the request was rejected (409, 422)
- *   5  temporary, worth retrying (429, 5xx)
- *   6  the run ended asking a question instead of producing an image
- */
 import { randomUUID } from "node:crypto";
-import { openAsBlob, readFileSync } from "node:fs";
-import { stat, writeFile } from "node:fs/promises";
+import { constants, openAsBlob, readFileSync } from "node:fs";
+import { access, lstat, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { ApiError, KNOWN_OPERATIONS, ManagedClient, StreamIdleError, UploadTimeoutError, terminalExecutionError, } from "./client.js";
+import { ApiError, InputValidationError, RecoveryRequiredError, KNOWN_OPERATIONS, ManagedClient, StreamIdleError, UploadTimeoutError, terminalExecutionError, } from "./client.js";
 import { Progress, consume } from "./render.js";
 const PACKAGE_VERSION = String(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
 const USAGE = `dreamlayer - generate and edit images from your terminal
@@ -31,12 +16,14 @@ USAGE
   dreamlayer upscale <image> [--out <file>]
   dreamlayer sprite <image> --action <walk|run|idle> [--frames <7–100>] --max-credits <n> [--out <zip>]
   dreamlayer answer <conversation-id> <text> [--image <file>] [--out <file>]
+  dreamlayer download <execution-id> --out <file>
   dreamlayer status <execution-id>
   dreamlayer balance
   dreamlayer capabilities
 
 OPTIONS
-  --out <file>      Where to write the image. Default: dreamlayer-<n>.png
+  --out <file>      New output file; never overwrites. Default: dreamlayer-<n>.png
+                    Existing destinations are refused before paid submission.
   --image <file>    Attach an image when answering a question that asks for one
   --aspect <ratio>  1:1, 16:9, 9:16, 4:3, 3:4. Default 1:1
   --action <name>  Sprite preset: walk, run, idle (walk if no custom prompt)
@@ -45,10 +32,19 @@ OPTIONS
   --frame-size <px> Square export: 32, 64, 128, 256, 512 (default), 720, 1080
   --frames <n>      Frame count: integer 7–100, default 12
   --max-credits <n> Maximum approved charge for the sprite job
-  --json            Machine-readable output on stdout
+  --json            JSON results on stdout; JSON errors on stderr
   --quiet           No progress on stderr
   --idempotency-key <key>  Reuse to retry safely after an uncertain response
 
+EXIT CODES
+  0 success, 1 usage/local error, 2 authentication/access, 3 credits/quota,
+  4 permanent API failure, 5 temporary failure, 6 input required
+
+AUTOMATION
+  Commands never prompt. Save a unique --idempotency-key before paid work.
+  After uncertainty, use status then download; do not start a replacement job.
+  CLI guide: https://docs.dreamlayer.io/cli
+
 ENVIRONMENT
   DREAMLAYER_API_KEY   Required. Get one at https://platform.dreamlayer.io
   DREAMLAYER_API_URL   Override the endpoint. Default https://api.dreamlayer.io
@@ -57,6 +53,59 @@ Image operations cost one credit. Sprite pricing is listed in capabilities. A ne
 `;
 class UsageError extends Error {
 }
+class CommandError extends Error {
+    reason;
+    exitCode;
+    retryable;
+    guidance;
+    constructor(reason, message, exitCode, retryable = false, guidance) {
+        super(message);
+        this.reason = reason;
+        this.exitCode = exitCode;
+        this.retryable = retryable;
+        this.guidance = guidance;
+    }
+}
+async function preflightOutput(target) {
+    let exists = false;
+    try {
+        await lstat(target);
+        exists = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw new CommandError("output_unavailable", "The output destination could not be checked. No generation was submitted.", 1);
+        }
+    }
+    if (exists) {
+        throw new CommandError("output_exists", "The output destination already exists. Refusing to overwrite; no generation was submitted.", 1, false, "Use the existing output or choose a new --out path for intentionally new work.");
+    }
+    try {
+        const parent = path.dirname(path.resolve(target));
+        if (!(await stat(parent)).isDirectory())
+            throw new Error("not a directory");
+        await access(parent, constants.W_OK | constants.X_OK);
+    }
+    catch {
+        throw new CommandError("output_unavailable", "The output parent must be an existing writable directory. No generation was submitted.", 1);
+    }
+}
+async function saveOutput(target, bytes) {
+    try {
+        await writeFile(target, bytes, { flag: "wx" });
+    }
+    catch {
+        throw new CommandError("local_output_failed", "The output could not be saved locally. Generation has already completed.", 1, true, "Fix the destination or choose a new path, then use dreamlayer download with the saved execution_id. Do not generate again.");
+    }
+}
+async function downloadOutput(api, url) {
+    try {
+        return await api.download(url);
+    }
+    catch {
+        throw new CommandError("download_failed", "The completed output could not be downloaded.", 5, true, "Retry dreamlayer download with the saved execution_id. Do not generate again.");
+    }
+}
 function parseOptions(argv) {
     const positional = [];
     const options = {
@@ -147,14 +196,11 @@ function parseOptions(argv) {
 function client() {
     const key = (process.env.DREAMLAYER_API_KEY ?? "").trim();
     if (!key) {
-        throw new UsageError("DREAMLAYER_API_KEY is not set.\n" +
-            "  export DREAMLAYER_API_KEY=dlr_live_...\n" +
-            "  Get a key at https://platform.dreamlayer.io");
+        throw new CommandError("authentication_failed", "DREAMLAYER_API_KEY is not set. Get a key at https://platform.dreamlayer.io", 2);
     }
     return new ManagedClient(key, (process.env.DREAMLAYER_API_URL ?? "https://api.dreamlayer.io").trim());
 }
 const MAX_SOURCE_BYTES = 200 * 1024 * 1024;
-/** Upload a local file; the server owns RAW, EXIF, alpha, and resize normalization. */
 async function upload(api, file) {
     const resolved = path.resolve(file);
     let fileStat;
@@ -162,30 +208,38 @@ async function upload(api, file) {
         fileStat = await stat(resolved);
     }
     catch {
-        throw new UsageError(`cannot read ${file}`);
+        throw new CommandError("local_input_failed", "The local input file could not be read.", 1);
     }
     if (fileStat.size > MAX_SOURCE_BYTES) {
         throw new UsageError(`${file} is ${Math.round(fileStat.size / 1024 / 1024)} MB; the limit is 200 MB`);
     }
-    const asset = await api.uploadInput(await openAsBlob(resolved), path.basename(resolved));
+    let blob;
+    try {
+        blob = await openAsBlob(resolved);
+    }
+    catch {
+        throw new CommandError("local_input_failed", "The local input file could not be read.", 1);
+    }
+    const asset = await api.uploadInput(blob, path.basename(resolved));
     return asset.input_asset_id;
 }
 function defaultOut() {
     return `dreamlayer-${Date.now()}.png`;
 }
+let recovery = {};
 async function run(api, input, options) {
     const progress = new Progress(!options.quiet && process.stderr.isTTY === true);
     const idempotencyKey = options.idempotencyKey ?? randomUUID();
+    recovery = { idempotency_key: idempotencyKey };
     const outcome = await consume(api.follow(input, { idempotencyKey }), progress);
+    recovery.execution_id = outcome.execution_id;
     if (outcome.question) {
         progress.stop();
         if (options.json) {
-            process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
+            process.stdout.write(`${JSON.stringify({ ...outcome, idempotency_key: idempotencyKey }, null, 2)}\n`);
         }
         else {
             process.stderr.write(`\nDreamLayer needs one more thing:\n  ${outcome.question.text}\n\n`);
-            // The server's needs_input question always asks for an image, so point at the
-            // flag that can supply one rather than the bare form that will 422.
             const wantsImage = /image/i.test(outcome.question.text);
             process.stderr.write(`Answer it with:\n  dreamlayer answer ${outcome.conversation_id} "your answer"` +
                 `${wantsImage ? " --image <file>" : ""}\n`);
@@ -199,22 +253,21 @@ async function run(api, input, options) {
             if (terminal)
                 throw terminal;
         }
-        if (options.json)
-            process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
-        else
-            process.stderr.write(`Run ended as ${outcome.status}. No credit was settled.\n`);
-        return 5;
+        if (outcome.status === "cancelled")
+            throw new CommandError("execution_cancelled", "The execution was cancelled.", 4);
+        if (outcome.status === "failed")
+            throw new CommandError("generation_failed", "The execution failed. Read canonical state for details.", 4);
+        throw new RecoveryRequiredError("The execution has no completed output yet. Read its saved state.");
     }
     progress.set("Downloading");
-    const bytes = await api.download(outcome.asset.download_url);
+    const bytes = await downloadOutput(api, outcome.asset.download_url);
     const target = options.out ?? (input.operation === "sprite_sheet" ? `dreamlayer-${Date.now()}.zip` : defaultOut());
-    await writeFile(target, bytes);
+    await saveOutput(target, bytes);
     progress.stop();
     if (options.json) {
-        process.stdout.write(`${JSON.stringify({ ...outcome, file: path.resolve(target) }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ...outcome, idempotency_key: idempotencyKey, file: path.resolve(target) }, null, 2)}\n`);
     }
     else {
-        // The path on stdout and nothing else, so `$(dreamlayer generate ...)` is the file.
         process.stdout.write(`${target}\n`);
     }
     return 0;
@@ -224,13 +277,6 @@ async function imageCommand(operation, prompt, file, options) {
     const inputAssetId = await upload(api, file);
     return run(api, { prompt, operation, input_asset_id: inputAssetId }, options);
 }
-/**
- * Point a user at the job they may have paid for.
- *
- * Without this, a timed-out upscale left nothing to go on: no id, no command, and no
- * key-authenticated way to check a balance. "It might have charged you, good luck" is
- * not an acceptable end state for a paid call.
- */
 function recoveryHint(error) {
     const id = error !== null && typeof error === "object"
         ? error.partialOutcome
@@ -238,25 +284,6 @@ function recoveryHint(error) {
         : null;
     return id ? `The job may still be running. Check it with:\n  dreamlayer status ${id}\n` : "";
 }
-/**
- * Say so when this build and the server disagree about what exists.
- *
- * The MCP package solves this by asking the server at startup and shaping its tool
- * schema from the answer. The CLI cannot: `ManagedOperation` is a compile-time union and
- * `cutout` / `upscale` are compile-time commands, so deriving the list at runtime would
- * buy consistency by giving up type safety at every call site.
- *
- * So it reports instead of adapting, and it does so HERE because `capabilities` is free,
- * spends nothing, and is the command people are told to run first. Both directions are
- * worth naming:
- *
- *   - the server offers something this build cannot reach -> the user is missing a
- *     feature they are paying for and would never know
- *   - this build names something the server will not run -> the failure that shipped on
- *     2026-08-21, where a call looked like a client bug rather than a version skew
- *
- * stderr, never stdout: `dreamlayer capabilities` is piped into jq.
- */
 function warnIfOperationsDrifted(capabilities) {
     const listed = capabilities.operations;
     if (!Array.isArray(listed) || listed.some((o) => typeof o !== "string"))
@@ -290,11 +317,19 @@ async function main(argv) {
         process.stdout.write(USAGE);
         return command ? 0 : 1;
     }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
     if (command === "--version" || command === "-v") {
         process.stdout.write(`${PACKAGE_VERSION}\n`);
         return 0;
     }
     const { positional, options } = parseOptions(rest);
+    if (["generate", "edit", "cutout", "upscale", "sprite", "answer"].includes(command)) {
+        options.out ??= command === "sprite" ? `dreamlayer-${Date.now()}.zip` : defaultOut();
+        await preflightOutput(options.out);
+    }
     switch (command) {
         case "sprite": {
             if (options.action && options.animationPrompt)
@@ -342,10 +377,6 @@ async function main(argv) {
             if (!conversationId || !text)
                 throw new UsageError("answer needs a conversation id and text");
             const api = client();
-            // A question that asks for an image cannot be answered with words alone: the
-            // server refuses a reply with no asset when the pending question required one.
-            // Without --image this command reached a clean 422 and the documented path
-            // dead-ended, telling the user to attach an image and offering no way to do it.
             const input = options.image ? await upload(api, options.image) : undefined;
             return run(api, {
                 respond: text,
@@ -353,6 +384,21 @@ async function main(argv) {
                 ...(input ? { input_asset_id: input } : {}),
             }, options);
         }
+        case "download": {
+            const executionId = positional[0];
+            if (!executionId || positional.length !== 1 || !options.out)
+                throw new UsageError("download needs one execution id and --out <file>");
+            const api = client();
+            recovery = { execution_id: executionId };
+            const execution = await api.getExecution(executionId);
+            const assets = execution.image_job?.finished_assets;
+            if (execution.status !== "completed" || !Array.isArray(assets) || assets.length !== 1 || typeof assets[0]?.download_url !== "string")
+                throw new CommandError("output_not_ready", "The execution has no single finished asset. Check status before downloading.", 5, true, "Read the saved execution; do not generate again.");
+            const bytes = await downloadOutput(api, assets[0].download_url);
+            await saveOutput(options.out, bytes);
+            process.stdout.write(options.json ? `${JSON.stringify({ execution_id: executionId, file: path.resolve(options.out), bytes: bytes.length })}\n` : `${options.out}\n`);
+            return 0;
+        }
         case "status": {
             const executionId = positional[0];
             if (!executionId)
@@ -392,6 +438,39 @@ main(process.argv.slice(2))
     process.exitCode = code;
 })
     .catch((error) => {
+    const known = error instanceof CommandError ? error : error instanceof InputValidationError
+        ? new CommandError("invalid_request", error.message, 1)
+        : error instanceof RecoveryRequiredError
+            ? new CommandError("temporarily_unavailable", "Execution state is uncertain. Read saved state before retrying.", 5, true, "Use status and download for the saved execution. If no ID was received, replay identical inputs with the original idempotency key.") : null;
+    if (known) {
+        const partial = error.partialOutcome;
+        const identity = { ...recovery, ...(partial?.execution_id ? { execution_id: partial.execution_id } : {}) };
+        const envelope = { error: { code: "CLIENT_ERROR", reason: known.reason, message: known.message, retryable: known.retryable, request_id: null, guidance: known.guidance, ...identity } };
+        if (process.argv.slice(2).includes("--json"))
+            process.stderr.write(`${JSON.stringify(envelope)}\n`);
+        else {
+            process.stderr.write(`${known.message}\n${known.guidance ?? ""}\n`);
+            if (identity.execution_id)
+                process.stderr.write(`Execution: ${identity.execution_id}\n  dreamlayer status ${identity.execution_id}\n  dreamlayer download ${identity.execution_id} --out <new-file>\n`);
+            if (identity.idempotency_key)
+                process.stderr.write(`Idempotency key: ${identity.idempotency_key}\n`);
+        }
+        process.exitCode = known.exitCode;
+        return;
+    }
+    if (process.argv.slice(2).includes("--json")) {
+        const partial = error?.partialOutcome;
+        const temporary = error instanceof StreamIdleError || error instanceof UploadTimeoutError;
+        const envelope = error instanceof ApiError ? error.toPublicEnvelope() : {
+            error: { code: error instanceof UsageError ? "VALIDATION_FAILED" : temporary ? "SERVICE_UNAVAILABLE" : "INTERNAL_ERROR",
+                reason: error instanceof UsageError ? "invalid_request" : temporary ? "temporarily_unavailable" : "client_error",
+                message: error instanceof UsageError ? "Check command arguments and local input or output files; use --help." : temporary ? "The request timed out. Check the saved execution before retrying." : "The command could not complete. Check saved execution state and local output access.",
+                retryable: temporary, request_id: null },
+        };
+        process.stderr.write(`${JSON.stringify({ error: { ...envelope.error, ...recovery, ...(partial?.execution_id ? { execution_id: partial.execution_id } : {}) } })}\n`);
+        process.exitCode = error instanceof ApiError ? exitCodeFor(error) : temporary ? 5 : 1;
+        return;
+    }
     if (error instanceof UsageError) {
         process.stderr.write(`${error.message}\n`);
         process.exitCode = 1;
@@ -412,11 +491,6 @@ main(process.argv.slice(2))
         process.exitCode = exitCodeFor(error);
         return;
     }
-    // A stream that went silent is retryable, and it is the failure MOST likely to
-    // have been charged for: the server may have finished the job we stopped listening
-    // to. It reached this generic branch as a bare DOMException, so it exited 1 with no
-    // guidance, and the --idempotency-key advice that exists precisely to prevent
-    // double payment never printed on the one case that needs it.
     if (error instanceof StreamIdleError) {
         process.stderr.write(`${error.message}\n`);
         process.stderr.write("Temporary. Retry with --idempotency-key to avoid paying twice.\n");

package/dist/client.d.ts

@@ -1,49 +1,10 @@
-/**
- * Hosted client for the DreamLayer Agent API.
- *
- * Deliberately a COPY of the same file in dreamlayer-mcp rather than a shared package.
- * The alternative makes every capability three releases in strict order (client, then
- * CLI, then MCP) instead of one release per repo. For a client over eight endpoints
- * that trade is not worth the friction.
- *
- * Lifted from the DreamLayer runtime's TypeScript client, which is retired. The
- * validation, error sanitisation, and origin hardening are kept verbatim because they
- * were already correct; what changed is that the SSE reader is now wired to the hosted
- * client instead of the dead local-proxy class, and that timeouts and an explicit
- * redirect policy were added, which the original lacked.
- */
 export type ManagedEventName = "started" | "thinking" | "progress" | "job" | "question" | "asset" | "done";
 export type ManagedEvent = {
     id: string | null;
     event: ManagedEventName;
     data: Record<string, unknown>;
 };
-/**
- * Every operation the Agent API can execute.
- *
- * REQUIRES the gateway build that added `operation` to ExecuteRequest. Against an older
- * deployment this field is rejected with 422 extra_forbidden, because the request model
- * is closed. That is a sequencing constraint, not a reason to drop it: naming the
- * operation is what stops a cutout or an upscale being re-read from the prompt and
- * coming back as a clarifying question instead of an image.
- *
- * SATISFIED 2026-08-21. prodbeta176 carries the field in the gateway AND the dispatch
- * in the workflow engine, which had been split across two releases: the gateway
- * accepted `operation` from prodbeta174 while the half that acts on it was still on
- * prodbeta172, so naming an operation returned 200 and was then inferred from prose
- * anyway. Confirmed against the deployment, not the source: the live /openapi.json
- * advertises exactly these four in both ExecuteRequest and ImageJobCreate.
- */
 export declare const KNOWN_OPERATIONS: readonly ["text_to_image", "image_to_image", "background_remove", "upscale", "sprite_sheet"];
-/**
- * Derived from the array above, not written twice.
- *
- * The first version of this declared the union by hand and pinned an array to it with
- * `satisfies`. That catches a WRONG entry and not a MISSING one, because a shorter array
- * still satisfies a wider union, so the exact drift this file exists to detect could
- * slip through the check meant to prevent it. Deriving the type makes the array the
- * single definition and the question unaskable.
- */
 export type ManagedOperation = (typeof KNOWN_OPERATIONS)[number];
 export type ManagedExecuteInput = {
     prompt?: string;
@@ -51,7 +12,6 @@ export type ManagedExecuteInput = {
     conversation_id?: string;
     input_asset_id?: string;
     aspect_ratio?: string;
-    /** Requires the gateway build that added it. See ManagedOperation. */
     operation?: ManagedOperation;
     options?: {
         action?: "walk" | "run" | "idle";
@@ -62,6 +22,10 @@ export type ManagedExecuteInput = {
     };
     max_credits?: number;
 };
+export declare class InputValidationError extends Error {
+}
+export declare class RecoveryRequiredError extends Error {
+}
 export declare function spriteCreditPrice(frameCount: number): number;
 export declare function validateSpriteInput(input: ManagedExecuteInput): void;
 export type ManagedInputAsset = {
@@ -84,12 +48,8 @@ export declare class ApiError extends Error {
     readonly requestId: string | null;
     readonly code: string;
     readonly reason: PublicErrorReason;
-    constructor(status: number, surface?: string, detail?: string | null, 
-    /** Server-assigned id for this failure. The only handle support can search on. */
-    requestId?: string | null, code?: string | null, reason?: PublicErrorReason);
-    /** Whether retrying with the same idempotency key is worth doing. */
+    constructor(status: number, surface?: string, detail?: string | null, requestId?: string | null, code?: string | null, reason?: PublicErrorReason);
     get retryable(): boolean;
-    /** The same stable fields exposed by REST and MCP, with no private response text. */
     toPublicEnvelope(): Record<string, unknown>;
 }
 export type ManagedBalance = {
@@ -98,14 +58,6 @@ export type ManagedBalance = {
     available: number;
     credit_usd: "0.17";
 };
-/**
- * A stream that went silent, as distinct from a slow one.
- *
- * Thrown as a real error type because the CLI's exit codes and its retry advice are
- * driven off the error, and a bare DOMException from AbortSignal fell through to the
- * generic handler: exit 1 with no guidance, on the one failure most likely to have been
- * charged for. See ManagedApiError.retryable.
- */
 export declare class StreamIdleError extends Error {
     readonly idleMs: number;
     constructor();
@@ -115,36 +67,19 @@ export declare class UploadTimeoutError extends Error {
 }
 export declare function uploadTimeoutMs(bytes: number): number;
 export declare function managedBalance(value: unknown): ManagedBalance;
-/** Convert a terminal job failure into the same safe contract used by HTTP errors. */
 export declare function terminalExecutionError(execution: ManagedExecution): ApiError | null;
-/**
- * Validate one sanitized event against the published contract.
- *
- * Deliberately strict, including rejecting UNKNOWN fields: the point of the closed
- * schema is that a field appearing where none is documented means something changed
- * server-side that a client should not silently consume.
- */
 export declare function managedEvent(event: string, id: string | null, value: unknown): ManagedEvent;
 export declare class ManagedClient {
     private readonly apiKey;
     private readonly baseUrl;
     private capabilitiesPromise;
     constructor(apiKey: string, baseUrl?: string);
-    /**
-     * Run or continue an execution, yielding each validated event as it arrives.
-     *
-     * Streams rather than buffers. The Python server this replaces collected events into
-     * a list and threw the whole list away on overflow, taking the execution ID with it,
-     * so a caller could not even resume what it had already paid for.
-     */
     execute(input: ManagedExecuteInput, options: {
         idempotencyKey: string;
     }): AsyncGenerator<ManagedEvent>;
-    /** Follow a durable job across finite streams without submitting it twice. */
     follow(input: ManagedExecuteInput, options: {
         idempotencyKey: string;
     }): AsyncGenerator<ManagedEvent>;
-    /** Resume a stream after a drop. Pass the last event id you actually processed. */
     events(executionId: string, lastEventId?: string): AsyncGenerator<ManagedEvent>;
     getCapabilities(): Promise<Record<string, unknown>>;
     getExecution(executionId: string): Promise<ManagedExecution>;
@@ -153,11 +88,6 @@ export declare class ManagedClient {
     listConversations(): Promise<Array<Record<string, unknown>>>;
     deleteConversation(conversationId: string): Promise<void>;
     uploadInput(file: Blob, filename?: string): Promise<ManagedInputAsset>;
-    /**
-     * Fetch a finished asset. Follows redirects on purpose: large images are served
-     * straight from storage rather than proxied, so a client that refuses redirects
-     * receives the redirect instead of the image.
-     */
     download(url: string): Promise<Uint8Array>;
     private parse;
     private fetchStream;

package/dist/client.js

@@ -1,33 +1,3 @@
-/**
- * Hosted client for the DreamLayer Agent API.
- *
- * Deliberately a COPY of the same file in dreamlayer-mcp rather than a shared package.
- * The alternative makes every capability three releases in strict order (client, then
- * CLI, then MCP) instead of one release per repo. For a client over eight endpoints
- * that trade is not worth the friction.
- *
- * Lifted from the DreamLayer runtime's TypeScript client, which is retired. The
- * validation, error sanitisation, and origin hardening are kept verbatim because they
- * were already correct; what changed is that the SSE reader is now wired to the hosted
- * client instead of the dead local-proxy class, and that timeouts and an explicit
- * redirect policy were added, which the original lacked.
- */
-/**
- * Every operation the Agent API can execute.
- *
- * REQUIRES the gateway build that added `operation` to ExecuteRequest. Against an older
- * deployment this field is rejected with 422 extra_forbidden, because the request model
- * is closed. That is a sequencing constraint, not a reason to drop it: naming the
- * operation is what stops a cutout or an upscale being re-read from the prompt and
- * coming back as a clarifying question instead of an image.
- *
- * SATISFIED 2026-08-21. prodbeta176 carries the field in the gateway AND the dispatch
- * in the workflow engine, which had been split across two releases: the gateway
- * accepted `operation` from prodbeta174 while the half that acts on it was still on
- * prodbeta172, so naming an operation returned 200 and was then inferred from prose
- * anyway. Confirmed against the deployment, not the source: the live /openapi.json
- * advertises exactly these four in both ExecuteRequest and ImageJobCreate.
- */
 export const KNOWN_OPERATIONS = [
     "text_to_image",
     "image_to_image",
@@ -35,9 +5,13 @@ export const KNOWN_OPERATIONS = [
     "upscale",
     "sprite_sheet",
 ];
+export class InputValidationError extends Error {
+}
+export class RecoveryRequiredError extends Error {
+}
 export function spriteCreditPrice(frameCount) {
     if (!Number.isInteger(frameCount) || frameCount < 7 || frameCount > 100)
-        throw new Error("frame_count must be an integer from 7 to 100");
+        throw new InputValidationError("frame_count must be an integer from 7 to 100");
     const cents = 14 * Math.min(frameCount, 14) + 7 * Math.max(frameCount - 14, 0);
     return Math.ceil(cents * 10 / 17) / 10;
 }
@@ -46,18 +20,18 @@ export function validateSpriteInput(input) {
         return;
     const options = input.options;
     if (!options || (options.action === undefined) === (options.animation_prompt === undefined))
-        throw new Error("Sprite requests require exactly one of options.action or options.animation_prompt");
+        throw new InputValidationError("Sprite requests require exactly one of options.action or options.animation_prompt");
     if (options.action !== undefined && !["walk", "run", "idle"].includes(options.action))
-        throw new Error("Invalid sprite preset");
+        throw new InputValidationError("Invalid sprite preset");
     if (options.animation_prompt !== undefined && (typeof options.animation_prompt !== "string" || !options.animation_prompt.trim() || [...options.animation_prompt].length > 4000))
-        throw new Error("animation_prompt must contain 1–4000 characters");
+        throw new InputValidationError("animation_prompt must contain 1–4000 characters");
     if (options.animation_mode !== undefined && !["loop", "once"].includes(options.animation_mode))
-        throw new Error("animation_mode must be loop or once");
+        throw new InputValidationError("animation_mode must be loop or once");
     const price = spriteCreditPrice(options.frame_count ?? 12);
     if (options.frame_size !== undefined && ![32, 64, 128, 256, 512, 720, 1080].includes(options.frame_size))
-        throw new Error("frame_size must be 32, 64, 128, 256, 512, 720 or 1080");
+        throw new InputValidationError("frame_size must be 32, 64, 128, 256, 512, 720 or 1080");
     if (typeof input.max_credits !== "number" || !Number.isFinite(input.max_credits) || input.max_credits < price || input.max_credits > 100)
-        throw new Error(`This sprite request requires ${price} credits. Supply a sufficient max_credits limit.`);
+        throw new InputValidationError(`This sprite request requires ${price} credits. Supply a sufficient max_credits limit.`);
 }
 const DIRECT_INPUT_BYTES = 20 * 1024 * 1024;
 const RASTER_INPUT_SUFFIXES = new Set([".png", ".jpg", ".jpeg", ".webp"]);
@@ -182,9 +156,7 @@ export class ApiError extends Error {
     requestId;
     code;
     reason;
-    constructor(status, surface = "DreamLayer Agent API", detail = null, 
-    /** Server-assigned id for this failure. The only handle support can search on. */
-    requestId = null, code = null, reason = reasonForStatus(status)) {
+    constructor(status, surface = "DreamLayer Agent API", detail = null, requestId = null, code = null, reason = reasonForStatus(status)) {
         const safeDetail = detail ?? PUBLIC_ERROR_SPECS[reason].message;
         super(`${safeDetail || `${surface} request failed (${status})`}${requestId ? ` (request ${requestId})` : ""}`);
         this.status = status;
@@ -194,11 +166,9 @@ export class ApiError extends Error {
         this.code = code ?? defaultCode(reason);
         this.reason = reason;
     }
-    /** Whether retrying with the same idempotency key is worth doing. */
     get retryable() {
         return PUBLIC_ERROR_SPECS[this.reason].retryable;
     }
-    /** The same stable fields exposed by REST and MCP, with no private response text. */
     toPublicEnvelope() {
         return {
             error: {
@@ -211,14 +181,6 @@ export class ApiError extends Error {
         };
     }
 }
-/**
- * A stream that went silent, as distinct from a slow one.
- *
- * Thrown as a real error type because the CLI's exit codes and its retry advice are
- * driven off the error, and a bare DOMException from AbortSignal fell through to the
- * generic handler: exit 1 with no guidance, on the one failure most likely to have been
- * charged for. See ManagedApiError.retryable.
- */
 export class StreamIdleError extends Error {
     idleMs = STREAM_IDLE_TIMEOUT_MS;
     constructor() {
@@ -234,9 +196,6 @@ export class UploadTimeoutError extends Error {
     }
 }
 const ERROR_BODY_LIMIT = 16 * 1024;
-/**
- * A plain request: send, get a body back. Bounded work, so a total cap is right.
- */
 const REQUEST_TIMEOUT_MS = 130_000;
 const UPLOAD_MIN_BYTES_PER_SECOND = 256 * 1024;
 const UPLOAD_MAX_TIMEOUT_MS = 15 * 60_000;
@@ -247,29 +206,7 @@ export function uploadTimeoutMs(bytes) {
     }
     return Math.min(Math.max(REQUEST_TIMEOUT_MS, 60_000 + Math.ceil(bytes / UPLOAD_MIN_BYTES_PER_SECOND) * 1000), UPLOAD_MAX_TIMEOUT_MS);
 }
-/**
- * A STREAM is different, and conflating the two shipped a broken `upscale`.
- *
- * AbortSignal.timeout() caps TOTAL duration. An upscale of a 2048px image takes about
- * 150s server-side, so a 130s total cap aborted every single one: a command that failed
- * 100% of the time on a normal input, while the server had done the work and charged
- * for it.
- *
- * Raising the number would fix upscale and break again on the next slower operation.
- * The right question is not "how long may a job take" (unknowable, and it is the
- * server's business) but "how long may we hear NOTHING before the connection is dead".
- * The server sends `: keepalive` comments precisely so a client can tell those apart;
- * a total-duration timeout throws that information away.
- *
- * So: idle timeout, reset on every byte received.
- */
 const STREAM_IDLE_DEFAULT_MS = 90_000;
-/**
- * Overridable, within bounds. Two honest reasons rather than one: a test cannot wait
- * 90 seconds to prove a timeout fires, and a user on a genuinely bad link may need
- * longer. Clamped so a typo cannot disable the guard entirely or set it to zero, and
- * an unparseable value falls back rather than becoming NaN, which would abort instantly.
- */
 const STREAM_IDLE_TIMEOUT_MS = (() => {
     const raw = Number(process.env.DREAMLAYER_STREAM_IDLE_MS);
     if (!Number.isFinite(raw) || raw <= 0)
@@ -313,16 +250,12 @@ async function apiError(response, surface = "DreamLayer Agent API") {
         const raw = await boundedErrorBody(response);
         const parsed = raw ? JSON.parse(raw) : null;
         if (isRecord(parsed) && isRecord(parsed.error)) {
-            // Treat only the closed reason/code/id fields as data. The local message table
-            // deliberately ignores arbitrary remote detail so a private upstream response
-            // cannot leak through a client even if a server regression serializes it.
             reason = publicReason(parsed.error.reason) ?? reason;
             code = publicIdentifier(parsed.error.code);
             requestId = publicRequestId(parsed.error.request_id) ?? requestId;
         }
     }
     catch {
-        // A malformed or oversized response still becomes a closed, status-derived error.
     }
     return new ApiError(response.status, surface, null, requestId, code, reason);
 }
@@ -365,7 +298,6 @@ export function managedBalance(value) {
         credit_usd: "0.17",
     };
 }
-/** Convert a terminal job failure into the same safe contract used by HTTP errors. */
 export function terminalExecutionError(execution) {
     if (!isRecord(execution.image_job) || !isRecord(execution.image_job.sanitized_error)) {
         return execution.status === "failed" ? new ApiError(500) : null;
@@ -374,13 +306,6 @@ export function terminalExecutionError(execution) {
     const reason = publicReason(error.reason) ?? "generation_failed";
     return new ApiError(statusForReason(reason), "DreamLayer execution", null, publicRequestId(error.request_id), publicIdentifier(error.code), reason);
 }
-/**
- * Validate one sanitized event against the published contract.
- *
- * Deliberately strict, including rejecting UNKNOWN fields: the point of the closed
- * schema is that a field appearing where none is documented means something changed
- * server-side that a client should not silently consume.
- */
 export function managedEvent(event, id, value) {
     if (!MANAGED_EVENT_NAMES.has(event) || !isRecord(value)) {
         throw new Error("Invalid DreamLayer managed event");
@@ -449,15 +374,12 @@ export function managedEvent(event, id, value) {
     }
     return { id, event: event, data };
 }
-/** Parse a server-sent-event body into blocks. Handles multi-line data and comments. */
 async function* readEventStream(body, onBytes) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
     for (;;) {
         const { value, done } = await reader.read();
-        // Any byte at all, including a `: keepalive` comment that parses to no event,
-        // proves the connection is alive. That is the signal the idle timer needs.
         if (!done)
             onBytes?.();
         buffer += decoder.decode(value, { stream: !done });
@@ -486,18 +408,6 @@ async function* readEventStream(body, onBytes) {
             return;
     }
 }
-/**
- * Hosts this client will send a bearer key to.
- *
- * In August a build moved the endpoint default from api.dreamlayer.io to the bare
- * marketing apex, and every request carried Authorization there for two days. The
- * origin passed every cleanliness check below, because those check the SHAPE of a URL
- * and never which host it names. An allowlist is the only thing that catches a host
- * swap, which is why the gateway now has a pinned-origin test and why this mirrors it.
- *
- * DREAMLAYER_API_URL still works for a genuinely different deployment: set
- * DREAMLAYER_ALLOW_ANY_HOST=1 alongside it and accept that you are vouching for the host.
- */
 const ALLOWED_HOSTS = new Set(["api.dreamlayer.io"]);
 function isLoopback(hostname) {
     return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]";
@@ -542,13 +452,6 @@ export class ManagedClient {
             throw new Error("DREAMLAYER_API_KEY is required");
         this.baseUrl = managedOrigin(baseUrl);
     }
-    /**
-     * Run or continue an execution, yielding each validated event as it arrives.
-     *
-     * Streams rather than buffers. The Python server this replaces collected events into
-     * a list and threw the whole list away on overflow, taking the execution ID with it,
-     * so a caller could not even resume what it had already paid for.
-     */
     async *execute(input, options) {
         validateSpriteInput(input);
         const stream = await this.fetchStream("/v1/execute", {
@@ -562,7 +465,6 @@ export class ManagedClient {
         });
         yield* this.parse(stream);
     }
-    /** Follow a durable job across finite streams without submitting it twice. */
     async *follow(input, options) {
         let executionId;
         let cursor;
@@ -585,17 +487,21 @@ export class ManagedClient {
             catch (error) {
                 if (error instanceof StreamIdleError)
                     throw error;
-                if (!executionId || (error instanceof ApiError && ![429, 500, 502, 503, 504].includes(error.status)) || ++failures > 5)
+                if (error instanceof InputValidationError || (error instanceof ApiError && ![429, 500, 502, 503, 504].includes(error.status)))
+                    throw error;
+                if (!executionId && error instanceof ApiError)
                     throw error;
+                if (!executionId || ++failures > 5)
+                    throw new RecoveryRequiredError("Execution state is uncertain. Read saved state before retrying.");
             }
             if (!executionId)
-                throw new Error("Execution stream ended before an identifier was received; reuse your idempotency key.");
+                throw new RecoveryRequiredError("Execution stream ended before an identifier was received; reuse your idempotency key.");
             const state = await this.getExecution(executionId);
             if (["completed", "failed", "cancelled"].includes(state.status)) {
                 if (state.status === "completed") {
                     const assets = state.image_job?.finished_assets;
                     if (!Array.isArray(assets) || assets.length !== 1 || typeof assets[0]?.download_url !== "string")
-                        throw new Error(`Execution ${executionId} has no downloadable asset yet.`);
+                        throw new RecoveryRequiredError(`Execution ${executionId} has no downloadable asset yet.`);
                     yield managedEvent("asset", null, { asset_id: assets[0].asset_id, download_url: assets[0].download_url });
                 }
                 yield managedEvent("done", null, { status: state.status });
@@ -604,9 +510,8 @@ export class ManagedClient {
             await new Promise((resolve) => setTimeout(resolve, Math.min(5000, 500 * 2 ** failures)));
             stream = this.events(executionId, cursor);
         }
-        throw new Error(`Execution ${executionId ?? "unknown"} is still active. Use status to resume; the job has not been cancelled.`);
+        throw new RecoveryRequiredError(`Execution ${executionId ?? "unknown"} is still active. Use status to resume; the job has not been cancelled.`);
     }
-    /** Resume a stream after a drop. Pass the last event id you actually processed. */
     async *events(executionId, lastEventId) {
         const headers = { Accept: "text/event-stream" };
         if (lastEventId)
@@ -616,8 +521,6 @@ export class ManagedClient {
     }
     async getCapabilities() {
         this.capabilitiesPromise ??= this.request("/v1/capabilities").catch((error) => {
-            // Cache a successful contract for the process, but never pin a transient
-            // capabilities failure as a permanent result.
             this.capabilitiesPromise = null;
             throw error;
         });
@@ -701,17 +604,7 @@ export class ManagedClient {
         body.append("file", file, filename);
         return this.request("/v1/input-assets", { method: "POST", body });
     }
-    /**
-     * Fetch a finished asset. Follows redirects on purpose: large images are served
-     * straight from storage rather than proxied, so a client that refuses redirects
-     * receives the redirect instead of the image.
-     */
     async download(url) {
-        // Only attach the key when the URL is OUR origin. download_url arrives in the event
-        // stream and is validated as text, so a wrong or hostile value would otherwise walk
-        // off with a live credential on the very first request. Node strips Authorization
-        // across a cross-origin redirect, so the hop to signed storage stays safe either way,
-        // and storage URLs are pre-signed and need no header from us.
         const sameOrigin = (() => {
             try {
                 return new URL(url).origin === this.baseUrl;
@@ -741,9 +634,6 @@ export class ManagedClient {
             }
         }
         finally {
-            // Also runs when the consumer breaks out of the loop early, which the CLI does
-            // as soon as it sees a terminal event. Without this the timer keeps the process
-            // alive for another idle period.
             finish();
         }
     }
@@ -751,9 +641,6 @@ export class ManagedClient {
         const headers = new Headers(init.headers);
         headers.set("Authorization", `Bearer ${this.apiKey}`);
         headers.set("DreamLayer-Version", "1");
-        // One controller for the whole stream, armed on an IDLE clock that every received
-        // byte pushes forward. The signal has to outlive the fetch() call: aborting only
-        // the handshake would leave a stalled body hanging forever.
         const controller = new AbortController();
         let timer;
         const keepAlive = () => {

package/dist/render.d.ts

@@ -1,11 +1,3 @@
-/**
- * Terminal rendering of an execution.
- *
- * Two modes, decided by whether stdout is a TTY and whether --json was passed. A CLI
- * that only prints prose cannot be piped into anything, and one that only prints JSON
- * is miserable to watch. Progress goes to stderr so `dreamlayer generate ... | jq`
- * works without the spinner corrupting the pipe.
- */
 import type { ManagedEvent } from "./client.js";
 export type Outcome = {
     execution_id: string | null;

package/dist/render.js

@@ -34,7 +34,6 @@ export class Progress {
             process.stderr.write(`${final}\n`);
     }
 }
-/** Human wording for each event. `thinking` carries no text by contract. */
 function describe(event) {
     switch (event.event) {
         case "started":
@@ -97,13 +96,6 @@ export async function consume(stream, progress, onEvent) {
         }
     }
     catch (error) {
-        // `started` arrives within seconds and carries the execution id. When the stream
-        // later dies, that id is the only way a user can find a job they may already have
-        // paid for, and it was being discarded along with the exception.
-        //
-        // Attached to the error rather than wrapped in a new one: the top-level handler
-        // branches on `instanceof ApiError`, and a wrapper would silently defeat that
-        // while looking tidier.
         if (error !== null && typeof error === "object") {
             error.partialOutcome = outcome;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamlayer",
-  "version": "0.4.0-beta.1",
+  "version": "0.4.0-beta.2",
   "description": "Generate and edit images from your terminal, over local files, with one API key.",
   "license": "MIT",
   "type": "module",
@@ -31,11 +31,16 @@
     "cli",
     "dreamlayer",
     "ai",
-    "image-editing"
+    "image-editing",
+    "sprite-sheet",
+    "automation"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TheDesignFounder/dreamlayer-cli.git"
   },
-  "homepage": "https://docs.dreamlayer.io/cli"
+  "homepage": "https://docs.dreamlayer.io/cli",
+  "publishConfig": {
+    "tag": "beta"
+  }
 }