dreamlayer 0.4.0-beta.1 → 0.4.0-beta.3

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,49 @@ 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.
+
+## Error handling updates in beta.3
+
+Transport failures include a safe connection category without exposing URLs or credentials. Cancelled executions recommend a status check; download authentication failures retain exit code 2. Help flags are parsed as options so a literal `-h` option value is preserved.

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,61 @@ 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 (error) {
+        if (error instanceof ApiError && [401, 403].includes(error.status))
+            throw error;
+        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 = {
@@ -67,11 +118,14 @@ function parseOptions(argv) {
         aspect: "1:1",
         json: false,
         quiet: false,
+        help: false,
         idempotencyKey: null,
     };
     for (let i = 0; i < argv.length; i += 1) {
         const token = argv[i];
-        if (token === "--json")
+        if (token === "--help" || token === "-h")
+            options.help = true;
+        else if (token === "--json")
             options.json = true;
         else if (token === "--quiet")
             options.quiet = true;
@@ -147,14 +201,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 +213,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 +258,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 +282,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 +289,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"))
@@ -295,6 +327,14 @@ async function main(argv) {
         return 0;
     }
     const { positional, options } = parseOptions(rest);
+    if (options.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    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 +382,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 +389,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 +443,42 @@ 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", error.message, 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 ? known.guidance + "\n" : ""}`);
+            if (identity.execution_id) {
+                process.stderr.write(`Execution: ${identity.execution_id}\n  dreamlayer status ${identity.execution_id}\n`);
+                if (["local_output_failed", "download_failed"].includes(known.reason))
+                    process.stderr.write(`  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;
@@ -403,20 +490,10 @@ main(process.argv.slice(2))
             : error.retryable
                 ? "Temporary. Retry with --idempotency-key to avoid paying twice."
                 : "";
-        if (process.argv.slice(2).includes("--json")) {
-            process.stderr.write(`${JSON.stringify(error.toPublicEnvelope())}\n`);
-        }
-        else {
-            process.stderr.write(`${error.message}\nReason: ${error.reason}${hint ? `\n${hint}` : ""}\n`);
-        }
+        process.stderr.write(`${error.message}\nReason: ${error.reason}${hint ? `\n${hint}` : ""}\n`);
         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,29 @@ 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) {
+                    const code = error?.cause?.code ?? error?.code;
+                    const causes = {
+                        ECONNREFUSED: "Connection refused", ENOTFOUND: "Host lookup failed", EAI_AGAIN: "Host lookup temporarily failed",
+                        ECONNRESET: "Connection reset", ETIMEDOUT: "Connection timed out", UND_ERR_CONNECT_TIMEOUT: "Connection timed out",
+                        UND_ERR_SOCKET: "Connection closed", CERT_HAS_EXPIRED: "TLS certificate expired", DEPTH_ZERO_SELF_SIGNED_CERT: "TLS certificate is untrusted",
+                    };
+                    const cause = code && causes[code] ? `${causes[code]} (${code}). ` : "Transport connection failed. ";
+                    throw new RecoveryRequiredError(cause + "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 +518,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 +529,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 +612,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 +642,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 +649,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.3",
   "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"
+  }
 }