dreamlayer 0.2.0 → 0.4.0-beta.1

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 balance                              # spends nothing
 dreamlayer capabilities                         # spends nothing
 ```
 
@@ -52,7 +53,7 @@ open "$(dreamlayer generate 'a fox logo')"
 | 1 | Usage error |
 | 2 | Auth or account problem |
 | 3 | Out of credits |
-| 4 | Request rejected, will fail identically until you change it |
+| 4 | Non-retryable request or execution failure |
 | 5 | Temporary, worth retrying |
 | 6 | It asked a question instead of producing an image |
 
@@ -60,9 +61,19 @@ open "$(dreamlayer generate 'a fox logo')"
 for f in shots/*.png; do dreamlayer cutout "$f" --out "cut/$(basename "$f")" || break; done
 ```
 
-**`--json`** gives machine-readable output on stdout, carrying job state, execution ids,
-and the written path. It deliberately excludes your prompt, your images, and your key,
-so it is safe to paste into a bug report.
+**`--json`** gives machine-readable success output on stdout, carrying job state,
+execution ids, and the written path. Errors use the same stable `code`, `reason`,
+`message`, `retryable`, and `request_id` fields as REST and are written to stderr, so
+stdout stays result-only. Error envelopes deliberately exclude your prompt, images,
+local filenames, and key. Successful image JSON includes the destination path you chose;
+remove it before sharing if the local name is private.
+
+Check the authenticated key's own balance without starting image work:
+
+```bash
+dreamlayer balance
+dreamlayer balance --json
+```
 
 ## Retries are safe if you reuse the key
 
@@ -96,3 +107,20 @@ Node.js 22.12 or later.
 ## License
 
 MIT. See LICENSE and NOTICE.
+
+## Sprite-sheet beta
+
+Sprite requests accept exactly one of `options.animation_prompt` (1–4000 characters) or an `options.action` preset (`walk`, `run`, `idle`). Custom prompts can describe characters, creatures, objects, effects or 360° turntables. `animation_mode` is `loop` or `once`; presets default to loop, custom prompts to once. For a turntable, request a stationary camera and rotating subject. Broad requests do not guarantee correct motion, unseen details or successful effect transparency.
+
+Request integer `frame_count` 7–100 (default 12) and `frame_size` 32, 64, 128, 256, 512, 720 or 1080 (default 512). These are square export canvases; a larger export does not guarantee additional detail. Aspect ratio and shared alignment are preserved with transparent padding. A bundle contains transparent PNG frames, sheet, atlas, preview and import instructions, including each frame's playback duration. Choose a repeating loop or a one-time action with a beginning and ending. If the requested number of distinct frames cannot be delivered, the job fails and held credits are returned. Translucent effects can lose detail or fail; small exports are not automatically pixel art.
+
+Pricing is unchanged across sizes: frames 1–14 cost $0.14 each; additional frames $0.07 each. One credit is $0.17. Round the complete order upward once to a tenth of a credit. Check `sprite_pricing` in capabilities and approve the quote with `max_credits`. Credits are held during processing, settled after complete delivery and restored on failure/timeout. There is no customer cancellation. Keep the execution ID to resume status. Custom requests need the matching broad-animation server release; older servers reject them. New live generation quality, 100-frame duration and actual cost remain unverified.
+
+```sh
+dreamlayer sprite character.png --action walk --frames 12 --max-credits 9.9 --out walk.zip
+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.

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spriteCreditPrice } from "./client.js";
 /**
  * DreamLayer CLI.
  *
@@ -18,7 +19,7 @@ import { randomUUID } from "node:crypto";
 import { openAsBlob, readFileSync } from "node:fs";
 import { stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { ApiError, KNOWN_OPERATIONS, ManagedClient, StreamIdleError, UploadTimeoutError, } from "./client.js";
+import { ApiError, 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
@@ -28,14 +29,22 @@ USAGE
   dreamlayer edit <image> <prompt> [--out <file>]
   dreamlayer cutout <image> [--out <file>]
   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 status <execution-id>
+  dreamlayer balance
   dreamlayer capabilities
 
 OPTIONS
   --out <file>      Where to write the image. Default: dreamlayer-<n>.png
   --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)
+  --animation-prompt <text>  Custom animation; cannot combine with --action
+  --animation-mode <loop|once>  Default: loop for presets, once for custom
+  --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
   --quiet           No progress on stderr
   --idempotency-key <key>  Reuse to retry safely after an uncertain response
@@ -44,13 +53,15 @@ ENVIRONMENT
   DREAMLAYER_API_KEY   Required. Get one at https://platform.dreamlayer.io
   DREAMLAYER_API_URL   Override the endpoint. Default https://api.dreamlayer.io
 
-Every finished image costs one credit. A new account starts at zero.
+Image operations cost one credit. Sprite pricing is listed in capabilities. A new account starts at zero.
 `;
 class UsageError extends Error {
 }
 function parseOptions(argv) {
     const positional = [];
     const options = {
+        maxCredits: 1,
+        frameCount: 12,
         out: null,
         image: null,
         aspect: "1:1",
@@ -70,6 +81,42 @@ function parseOptions(argv) {
                 throw new UsageError("--out needs a file path");
             options.out = value;
         }
+        else if (token === "--action") {
+            const value = argv[++i];
+            if (value !== "walk" && value !== "run" && value !== "idle")
+                throw new UsageError("--action must be walk, run, or idle");
+            options.action = value;
+        }
+        else if (token === "--animation-prompt") {
+            const value = argv[++i];
+            if (!value?.trim() || [...value].length > 4000)
+                throw new UsageError("--animation-prompt needs 1–4000 characters");
+            options.animationPrompt = value;
+        }
+        else if (token === "--animation-mode") {
+            const value = argv[++i];
+            if (value !== "loop" && value !== "once")
+                throw new UsageError("--animation-mode must be loop or once");
+            options.animationMode = value;
+        }
+        else if (token === "--frame-size") {
+            const value = Number(argv[++i]);
+            if (![32, 64, 128, 256, 512, 720, 1080].includes(value))
+                throw new UsageError("--frame-size must be 32, 64, 128, 256, 512, 720 or 1080");
+            options.frameSize = value;
+        }
+        else if (token === "--frames") {
+            const value = Number(argv[++i]);
+            if (!Number.isInteger(value) || value < 7 || value > 100)
+                throw new UsageError("--frames must be an integer from 7 to 100");
+            options.frameCount = value;
+        }
+        else if (token === "--max-credits") {
+            const value = Number(argv[++i]);
+            if (!Number.isFinite(value) || value < 0.1 || value > 100)
+                throw new UsageError("--max-credits must be 0.1 to 100");
+            options.maxCredits = value;
+        }
         else if (token === "--image") {
             const value = argv[++i];
             if (!value)
@@ -129,7 +176,7 @@ function defaultOut() {
 async function run(api, input, options) {
     const progress = new Progress(!options.quiet && process.stderr.isTTY === true);
     const idempotencyKey = options.idempotencyKey ?? randomUUID();
-    const outcome = await consume(api.execute(input, { idempotencyKey }), progress);
+    const outcome = await consume(api.follow(input, { idempotencyKey }), progress);
     if (outcome.question) {
         progress.stop();
         if (options.json) {
@@ -146,7 +193,12 @@ async function run(api, input, options) {
         return 6;
     }
     if (outcome.status !== "completed" || !outcome.asset) {
-        progress.stop("Failed");
+        progress.stop(options.json ? undefined : "Failed");
+        if (outcome.status === "failed" && outcome.execution_id) {
+            const terminal = terminalExecutionError(await api.getExecution(outcome.execution_id));
+            if (terminal)
+                throw terminal;
+        }
         if (options.json)
             process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
         else
@@ -155,7 +207,7 @@ async function run(api, input, options) {
     }
     progress.set("Downloading");
     const bytes = await api.download(outcome.asset.download_url);
-    const target = options.out ?? defaultOut();
+    const target = options.out ?? (input.operation === "sprite_sheet" ? `dreamlayer-${Date.now()}.zip` : defaultOut());
     await writeFile(target, bytes);
     progress.stop();
     if (options.json) {
@@ -212,7 +264,7 @@ function warnIfOperationsDrifted(capabilities) {
     const server = new Set(listed);
     const mine = new Set(KNOWN_OPERATIONS);
     const serverOnly = [...server].filter((o) => !mine.has(o));
-    const clientOnly = [...mine].filter((o) => !server.has(o));
+    const clientOnly = [...mine].filter((o) => !server.has(o) && o !== "sprite_sheet");
     if (serverOnly.length === 0 && clientOnly.length === 0)
         return;
     process.stderr.write("\nThis CLI and the server disagree about the operation list.\n");
@@ -226,13 +278,11 @@ function warnIfOperationsDrifted(capabilities) {
     }
 }
 function exitCodeFor(error) {
-    if (error.status === 401 || error.status === 403)
+    if (error.reason === "authentication_failed" || error.reason === "access_denied")
         return 2;
-    if (error.status === 402)
+    if (error.reason === "insufficient_credits" || error.reason === "quota_exceeded")
         return 3;
-    if (error.status === 409 || error.status === 422)
-        return 4;
-    return 5;
+    return error.retryable ? 5 : 4;
 }
 async function main(argv) {
     const [command, ...rest] = argv;
@@ -246,6 +296,23 @@ async function main(argv) {
     }
     const { positional, options } = parseOptions(rest);
     switch (command) {
+        case "sprite": {
+            if (options.action && options.animationPrompt)
+                throw new UsageError("Use either --action or --animation-prompt, not both");
+            const file = positional[0];
+            if (!file)
+                throw new UsageError("sprite needs a reference image");
+            const api = client();
+            const caps = await api.getCapabilities();
+            if (!Array.isArray(caps.operations) || !caps.operations.includes("sprite_sheet"))
+                throw new UsageError("sprite beta access is not enabled for this account");
+            if (!caps.sprite_pricing)
+                throw new UsageError("The server does not support configurable sprite pricing yet");
+            const price = spriteCreditPrice(options.frameCount);
+            if (options.maxCredits < price)
+                throw new UsageError(`Sprite jobs require ${price} credits. Set --max-credits to approve that amount.`);
+            return run(api, { operation: "sprite_sheet", input_asset_id: await upload(api, file), options: { ...(options.animationPrompt ? { animation_prompt: options.animationPrompt } : { action: options.action ?? "walk" }), ...(options.animationMode ? { animation_mode: options.animationMode } : {}), ...(options.frameSize ? { frame_size: options.frameSize } : {}), frame_count: options.frameCount }, max_credits: options.maxCredits }, options);
+        }
         case "generate": {
             const prompt = positional[0];
             if (!prompt)
@@ -294,6 +361,22 @@ async function main(argv) {
             process.stdout.write(`${JSON.stringify(execution, null, 2)}\n`);
             return 0;
         }
+        case "balance": {
+            if (positional.length > 0)
+                throw new UsageError("balance takes no arguments");
+            const balance = await client().getBalance();
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(balance, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`${balance.available} credits available ` +
+                    `(${balance.promotional} promotional, ${balance.purchased} purchased)\n`);
+            }
+            if (!options.json && Math.round(balance.available * 10) > Math.round(balance.promotional * 10) + Math.round(balance.purchased * 10)) {
+                process.stdout.write("Use the available total for affordability. Funding balances are rounded down separately; stored fractions are preserved.\n");
+            }
+            return 0;
+        }
         case "capabilities": {
             const capabilities = await client().getCapabilities();
             process.stdout.write(`${JSON.stringify(capabilities, null, 2)}\n`);
@@ -315,12 +398,17 @@ main(process.argv.slice(2))
         return;
     }
     if (error instanceof ApiError) {
-        const hint = error.status === 402
+        const hint = error.reason === "insufficient_credits"
             ? "Buy credits at https://platform.dreamlayer.io/console/billing"
             : error.retryable
                 ? "Temporary. Retry with --idempotency-key to avoid paying twice."
                 : "";
-        process.stderr.write(`${error.message}${hint ? `\n${hint}` : ""}\n`);
+        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.exitCode = exitCodeFor(error);
         return;
     }

package/dist/client.d.ts

@@ -34,7 +34,7 @@ export type ManagedEvent = {
  * 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"];
+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.
  *
@@ -53,7 +53,17 @@ export type ManagedExecuteInput = {
     aspect_ratio?: string;
     /** Requires the gateway build that added it. See ManagedOperation. */
     operation?: ManagedOperation;
+    options?: {
+        action?: "walk" | "run" | "idle";
+        animation_prompt?: string;
+        animation_mode?: "loop" | "once";
+        frame_count?: number;
+        frame_size?: 32 | 64 | 128 | 256 | 512 | 720 | 1080;
+    };
+    max_credits?: number;
 };
+export declare function spriteCreditPrice(frameCount: number): number;
+export declare function validateSpriteInput(input: ManagedExecuteInput): void;
 export type ManagedInputAsset = {
     input_asset_id: string;
     width: number;
@@ -66,17 +76,28 @@ export type ManagedExecution = {
     status: string;
     image_job: Record<string, unknown> | null;
 };
+export declare const PUBLIC_ERROR_REASONS: readonly ["invalid_request", "authentication_failed", "access_denied", "resource_not_found", "insufficient_credits", "conflict", "too_many_active_jobs", "rate_limited", "quota_exceeded", "content_refused", "temporarily_unavailable", "generation_failed", "insufficient_frames"];
+export type PublicErrorReason = (typeof PUBLIC_ERROR_REASONS)[number];
 export declare class ApiError extends Error {
     readonly status: number;
-    readonly detail: string | null;
-    /** Server-assigned id for this failure. The only handle support can search on. */
+    readonly detail: string;
     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);
+    requestId?: string | null, code?: string | null, reason?: PublicErrorReason);
     /** Whether retrying with the same idempotency key is worth doing. */
     get retryable(): boolean;
+    /** The same stable fields exposed by REST and MCP, with no private response text. */
+    toPublicEnvelope(): Record<string, unknown>;
 }
+export type ManagedBalance = {
+    promotional: number;
+    purchased: number;
+    available: number;
+    credit_usd: "0.17";
+};
 /**
  * A stream that went silent, as distinct from a slow one.
  *
@@ -93,6 +114,9 @@ export declare class UploadTimeoutError extends Error {
     constructor();
 }
 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.
  *
@@ -116,10 +140,15 @@ export declare class ManagedClient {
     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>;
+    getBalance(): Promise<ManagedBalance>;
     cancel(executionId: string): Promise<ManagedExecution>;
     listConversations(): Promise<Array<Record<string, unknown>>>;
     deleteConversation(conversationId: string): Promise<void>;

package/dist/client.js

@@ -33,7 +33,32 @@ export const KNOWN_OPERATIONS = [
     "image_to_image",
     "background_remove",
     "upscale",
+    "sprite_sheet",
 ];
+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");
+    const cents = 14 * Math.min(frameCount, 14) + 7 * Math.max(frameCount - 14, 0);
+    return Math.ceil(cents * 10 / 17) / 10;
+}
+export function validateSpriteInput(input) {
+    if (input.operation !== "sprite_sheet")
+        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");
+    if (options.action !== undefined && !["walk", "run", "idle"].includes(options.action))
+        throw new Error("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");
+    if (options.animation_mode !== undefined && !["loop", "once"].includes(options.animation_mode))
+        throw new Error("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");
+    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.`);
+}
 const DIRECT_INPUT_BYTES = 20 * 1024 * 1024;
 const RASTER_INPUT_SUFFIXES = new Set([".png", ".jpg", ".jpeg", ".webp"]);
 const LEGACY_INPUT_SUFFIXES = new Set([
@@ -41,24 +66,149 @@ const LEGACY_INPUT_SUFFIXES = new Set([
     ".arw", ".cr2", ".cr3", ".crw", ".dng", ".nef", ".nrw", ".orf", ".pef",
     ".raf", ".rw2", ".sr2", ".srw",
 ]);
+export const PUBLIC_ERROR_REASONS = [
+    "invalid_request",
+    "authentication_failed",
+    "access_denied",
+    "resource_not_found",
+    "insufficient_credits",
+    "conflict",
+    "too_many_active_jobs",
+    "rate_limited",
+    "quota_exceeded",
+    "content_refused",
+    "temporarily_unavailable",
+    "generation_failed",
+    "insufficient_frames",
+];
+const PUBLIC_ERROR_SPECS = {
+    invalid_request: { message: "The request could not be validated.", retryable: false },
+    authentication_failed: { message: "Authentication failed.", retryable: false },
+    access_denied: {
+        message: "This request is not available for this account.",
+        retryable: false,
+    },
+    resource_not_found: { message: "The requested item was not found.", retryable: false },
+    insufficient_credits: {
+        message: "The account has insufficient credits.",
+        retryable: false,
+    },
+    conflict: { message: "The request conflicts with the current state.", retryable: false },
+    too_many_active_jobs: {
+        message: "Too many image jobs are already in progress.",
+        retryable: true,
+    },
+    rate_limited: { message: "Too many requests. Please try again shortly.", retryable: true },
+    quota_exceeded: { message: "The account quota has been reached.", retryable: false },
+    content_refused: {
+        message: "The request could not be completed under the service policy.",
+        retryable: false,
+    },
+    temporarily_unavailable: {
+        message: "The service is temporarily unavailable. Please try again.",
+        retryable: true,
+    },
+    insufficient_frames: { message: "Not enough distinct animation frames. Try a lower frame count.", retryable: false },
+    generation_failed: { message: "Image generation failed.", retryable: false },
+};
+const PUBLIC_ERROR_REASON_SET = new Set(PUBLIC_ERROR_REASONS);
+function publicReason(value) {
+    return typeof value === "string" && PUBLIC_ERROR_REASON_SET.has(value)
+        ? value
+        : null;
+}
+function reasonForStatus(status) {
+    if (status === 400 || status === 405 || status === 422)
+        return "invalid_request";
+    if (status === 401)
+        return "authentication_failed";
+    if (status === 403)
+        return "access_denied";
+    if (status === 404)
+        return "resource_not_found";
+    if (status === 402)
+        return "insufficient_credits";
+    if (status === 409)
+        return "conflict";
+    if (status === 429)
+        return "rate_limited";
+    if (status === 502 || status === 503 || status === 504)
+        return "temporarily_unavailable";
+    return "generation_failed";
+}
+function defaultCode(reason) {
+    const codes = {
+        invalid_request: "VALIDATION_FAILED",
+        authentication_failed: "AUTHENTICATION_FAILED",
+        access_denied: "FORBIDDEN",
+        resource_not_found: "NOT_FOUND",
+        insufficient_credits: "BUDGET_EXCEEDED",
+        conflict: "CONFLICT",
+        too_many_active_jobs: "RATE_LIMITED",
+        rate_limited: "RATE_LIMITED",
+        quota_exceeded: "BUDGET_EXCEEDED",
+        content_refused: "CONTENT_REFUSED",
+        temporarily_unavailable: "SERVICE_UNAVAILABLE",
+        generation_failed: "INTERNAL_ERROR",
+        insufficient_frames: "INSUFFICIENT_FRAMES",
+    };
+    return codes[reason];
+}
+function statusForReason(reason) {
+    const statuses = {
+        invalid_request: 422,
+        authentication_failed: 401,
+        access_denied: 403,
+        resource_not_found: 404,
+        insufficient_credits: 402,
+        conflict: 409,
+        too_many_active_jobs: 429,
+        rate_limited: 429,
+        quota_exceeded: 402,
+        content_refused: 422,
+        temporarily_unavailable: 503,
+        generation_failed: 500,
+        insufficient_frames: 422,
+    };
+    return statuses[reason];
+}
+const ERROR_IDENTIFIER_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+function publicIdentifier(value) {
+    return typeof value === "string" && ERROR_IDENTIFIER_PATTERN.test(value) ? value : null;
+}
 export class ApiError extends Error {
     status;
     detail;
     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) {
-        super(detail
-            ? `${detail}${requestId ? ` (request ${requestId})` : ""}`
-            : `${surface} request failed (${status})`);
+    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;
-        this.detail = detail;
-        this.requestId = requestId;
         this.name = "ApiError";
+        this.detail = safeDetail;
+        this.requestId = requestId;
+        this.code = code ?? defaultCode(reason);
+        this.reason = reason;
     }
     /** Whether retrying with the same idempotency key is worth doing. */
     get retryable() {
-        return this.status === 429 || this.status >= 500;
+        return PUBLIC_ERROR_SPECS[this.reason].retryable;
+    }
+    /** The same stable fields exposed by REST and MCP, with no private response text. */
+    toPublicEnvelope() {
+        return {
+            error: {
+                code: this.code,
+                reason: this.reason,
+                message: this.detail,
+                retryable: this.retryable,
+                request_id: this.requestId,
+            },
+        };
     }
 }
 /**
@@ -84,7 +234,6 @@ export class UploadTimeoutError extends Error {
     }
 }
 const ERROR_BODY_LIMIT = 16 * 1024;
-const ERROR_DETAIL_LIMIT = 300;
 /**
  * A plain request: send, get a body back. Bounded work, so a total cap is right.
  */
@@ -130,40 +279,52 @@ const STREAM_IDLE_TIMEOUT_MS = (() => {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function sanitizedErrorDetail(value) {
-    if (typeof value !== "string")
-        return null;
-    const normalized = value
-        .replace(/[\u0000-\u001f\u007f]/g, " ")
-        .replace(/\s+/g, " ")
-        .trim();
-    return normalized ? normalized.slice(0, ERROR_DETAIL_LIMIT) : null;
+async function boundedErrorBody(response) {
+    const length = Number(response.headers.get("content-length") ?? "0");
+    if (!Number.isFinite(length) || length < 0 || length > ERROR_BODY_LIMIT || !response.body) {
+        return "";
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let total = 0;
+    let body = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                return body + decoder.decode();
+            total += value.byteLength;
+            if (total > ERROR_BODY_LIMIT) {
+                await reader.cancel();
+                return "";
+            }
+            body += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
 }
 async function apiError(response, surface = "DreamLayer Agent API") {
-    let detail = null;
-    let requestId = null;
+    let reason = reasonForStatus(response.status);
+    let code = null;
+    let requestId = publicRequestId(response.headers.get("x-request-id"));
     try {
-        const length = Number(response.headers.get("content-length") ?? "0");
-        if (!Number.isFinite(length) || length < 0 || length > ERROR_BODY_LIMIT) {
-            return new ApiError(response.status, surface);
-        }
-        const parsed = JSON.parse(await response.text());
-        if (isRecord(parsed)) {
-            // Two shapes in the wild. The gateway returns
-            // {"error":{"code","message","category","request_id"}}; older surfaces and
-            // FastAPI's own handlers return {"detail": "..."}. Reading only the latter is
-            // why every failure used to print a bare status code and nothing else.
-            detail = sanitizedErrorDetail(parsed.detail);
-            if (isRecord(parsed.error)) {
-                detail = detail ?? sanitizedErrorDetail(parsed.error.message);
-                requestId = sanitizedErrorDetail(parsed.error.request_id);
-            }
+        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 {
-        detail = null;
+        // A malformed or oversized response still becomes a closed, status-derived error.
     }
-    return new ApiError(response.status, surface, detail, requestId);
+    return new ApiError(response.status, surface, null, requestId, code, reason);
 }
 const MANAGED_EVENT_NAMES = new Set([
     "started",
@@ -175,6 +336,44 @@ const MANAGED_EVENT_NAMES = new Set([
     "done",
 ]);
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function publicRequestId(value) {
+    return typeof value === "string" && UUID_PATTERN.test(value) ? value : null;
+}
+export function managedBalance(value) {
+    if (!isRecord(value))
+        throw new Error("Invalid DreamLayer balance response");
+    const exact = ["available", "credit_usd", "promotional", "purchased"];
+    if (Object.keys(value).sort().join("\0") !== exact.join("\0")) {
+        throw new Error("Invalid DreamLayer balance response");
+    }
+    for (const field of ["promotional", "purchased", "available"]) {
+        if (typeof value[field] !== "number" || !Number.isFinite(value[field]) || Number(value[field]) < 0 || Number(value[field]) > Number.MAX_SAFE_INTEGER / 10) {
+            throw new Error("Invalid DreamLayer balance response");
+        }
+    }
+    if (value.credit_usd !== "0.17" ||
+        Math.round(Number(value.available) * 10) < Math.round(Number(value.promotional) * 10) + Math.round(Number(value.purchased) * 10) ||
+        Math.round(Number(value.available) * 10) > Math.round(Number(value.promotional) * 10) + Math.round(Number(value.purchased) * 10) + 1) {
+        throw new Error("Invalid DreamLayer balance response");
+    }
+    if ([value.promotional, value.purchased, value.available].some(v => Math.abs(Number(v) * 10 - Math.round(Number(v) * 10)) > 1e-7))
+        throw new Error("Invalid DreamLayer balance response");
+    return {
+        promotional: Number(value.promotional),
+        purchased: Number(value.purchased),
+        available: Number(value.available),
+        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;
+    }
+    const error = execution.image_job.sanitized_error;
+    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.
  *
@@ -351,6 +550,7 @@ export class ManagedClient {
      * 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", {
             method: "POST",
             headers: {
@@ -362,6 +562,50 @@ 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;
+        let stream = this.execute(input, options);
+        const deadline = Date.now() + 16 * 60_000;
+        let failures = 0;
+        while (Date.now() < deadline) {
+            try {
+                for await (const event of stream) {
+                    if (event.event === "started")
+                        executionId = String(event.data.execution_id);
+                    if (event.id)
+                        cursor = event.id;
+                    yield event;
+                    if (event.event === "done")
+                        return;
+                }
+                failures = 0;
+            }
+            catch (error) {
+                if (error instanceof StreamIdleError)
+                    throw error;
+                if (!executionId || (error instanceof ApiError && ![429, 500, 502, 503, 504].includes(error.status)) || ++failures > 5)
+                    throw error;
+            }
+            if (!executionId)
+                throw new Error("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.`);
+                    yield managedEvent("asset", null, { asset_id: assets[0].asset_id, download_url: assets[0].download_url });
+                }
+                yield managedEvent("done", null, { status: state.status });
+                return;
+            }
+            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.`);
+    }
     /** Resume a stream after a drop. Pass the last event id you actually processed. */
     async *events(executionId, lastEventId) {
         const headers = { Accept: "text/event-stream" };
@@ -386,6 +630,9 @@ export class ManagedClient {
     getExecution(executionId) {
         return this.request(`/v1/executions/${encodeURIComponent(executionId)}`);
     }
+    async getBalance() {
+        return managedBalance(await this.request("/v1/balance"));
+    }
     cancel(executionId) {
         return this.request(`/v1/executions/${encodeURIComponent(executionId)}/cancel`, {
             method: "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamlayer",
-  "version": "0.2.0",
+  "version": "0.4.0-beta.1",
   "description": "Generate and edit images from your terminal, over local files, with one API key.",
   "license": "MIT",
   "type": "module",