dreamlayer 0.1.0 → 0.3.0

package/README.md

@@ -12,10 +12,6 @@ dreamlayer generate "A glass greenhouse at dusk" --out greenhouse.png
 Get a key at [platform.dreamlayer.io](https://platform.dreamlayer.io). A new account
 starts at zero credits, and each finished image costs one.
 
-> **Not yet publishable.** This package sends an `operation` field that requires
-> the gateway build adding it to `ExecuteRequest`. Against the currently deployed
-> API every call returns `422 extra_forbidden`. Deploy that build first.
-
 ## Commands
 
 ```bash
@@ -25,12 +21,17 @@ 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
 ```
 
 `cutout` and `upscale` name their operation rather than hoping a sentence is read the
 way you meant, so they run a dedicated chain and never stop to ask a question.
 
+Image inputs may be PNG, JPEG, WebP, or supported camera RAW files up to 200 MB.
+DreamLayer develops RAW previews, applies camera orientation, and resizes oversized
+sources on the server before any operation runs.
+
 `upscale` doubles each side and finished images are capped at 4096 per side, so the
 longest side of your input must be 2048 or less. Anything larger is refused before it
 costs you a credit.
@@ -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
 

package/dist/cli.js

@@ -15,10 +15,12 @@
  *   6  the run ended asking a question instead of producing an image
  */
 import { randomUUID } from "node:crypto";
-import { readFile, writeFile } from "node:fs/promises";
+import { openAsBlob, readFileSync } from "node:fs";
+import { stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { ApiError, ManagedClient, StreamIdleError, } 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
 
 USAGE
@@ -28,6 +30,7 @@ USAGE
   dreamlayer upscale <image> [--out <file>]
   dreamlayer answer <conversation-id> <text> [--image <file>] [--out <file>]
   dreamlayer status <execution-id>
+  dreamlayer balance
   dreamlayer capabilities
 
 OPTIONS
@@ -104,24 +107,21 @@ function client() {
     }
     return new ManagedClient(key, (process.env.DREAMLAYER_API_URL ?? "https://api.dreamlayer.io").trim());
 }
-/** Upload a local file and return its asset id, with size and type checked here first. */
+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);
-    const extension = path.extname(resolved).toLowerCase();
-    if (![".png", ".jpg", ".jpeg", ".webp"].includes(extension)) {
-        throw new UsageError(`${file} is not a PNG, JPEG, or WEBP`);
-    }
-    let bytes;
+    let fileStat;
     try {
-        bytes = await readFile(resolved);
+        fileStat = await stat(resolved);
     }
     catch {
         throw new UsageError(`cannot read ${file}`);
     }
-    if (bytes.byteLength > 20 * 1024 * 1024) {
-        throw new UsageError(`${file} is ${Math.round(bytes.byteLength / 1024 / 1024)} MB; the limit is 20 MB`);
+    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(new Blob([new Uint8Array(bytes)]), path.basename(resolved));
+    const asset = await api.uploadInput(await openAsBlob(resolved), path.basename(resolved));
     return asset.input_asset_id;
 }
 function defaultOut() {
@@ -147,7 +147,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
@@ -187,14 +192,51 @@ 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"))
+        return;
+    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));
+    if (serverOnly.length === 0 && clientOnly.length === 0)
+        return;
+    process.stderr.write("\nThis CLI and the server disagree about the operation list.\n");
+    if (serverOnly.length > 0) {
+        process.stderr.write(`  The server offers, this version cannot use: ${serverOnly.join(", ")}\n` +
+            "  Upgrade with: npm i -g dreamlayer\n");
+    }
+    if (clientOnly.length > 0) {
+        process.stderr.write(`  This version names, the server will not run: ${clientOnly.join(", ")}\n` +
+            "  Those commands will fail validation until the server catches up.\n");
+    }
+}
 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;
@@ -203,7 +245,7 @@ async function main(argv) {
         return command ? 0 : 1;
     }
     if (command === "--version" || command === "-v") {
-        process.stdout.write("0.1.0\n");
+        process.stdout.write(`${PACKAGE_VERSION}\n`);
         return 0;
     }
     const { positional, options } = parseOptions(rest);
@@ -256,9 +298,23 @@ 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`);
+            }
+            return 0;
+        }
         case "capabilities": {
             const capabilities = await client().getCapabilities();
             process.stdout.write(`${JSON.stringify(capabilities, null, 2)}\n`);
+            warnIfOperationsDrifted(capabilities);
             return 0;
         }
         default:
@@ -276,12 +332,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;
     }
@@ -297,6 +358,12 @@ main(process.argv.slice(2))
         process.exitCode = 5;
         return;
     }
+    if (error instanceof UploadTimeoutError) {
+        process.stderr.write(`${error.message}\n`);
+        process.stderr.write("Temporary. Retry with --idempotency-key to avoid paying twice.\n");
+        process.exitCode = 5;
+        return;
+    }
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     process.stderr.write(recoveryHint(error));
     process.exitCode = 1;

package/dist/client.d.ts

@@ -34,7 +34,17 @@ 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 type ManagedOperation = "text_to_image" | "image_to_image" | "background_remove" | "upscale";
+export declare const KNOWN_OPERATIONS: readonly ["text_to_image", "image_to_image", "background_remove", "upscale"];
+/**
+ * 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;
     respond?: string;
@@ -56,17 +66,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"];
+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.
  *
@@ -79,6 +100,13 @@ export declare class StreamIdleError extends Error {
     readonly idleMs: number;
     constructor();
 }
+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.
  *
@@ -90,6 +118,7 @@ export declare function managedEvent(event: string, id: string | null, value: un
 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.
@@ -105,6 +134,7 @@ export declare class ManagedClient {
     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

@@ -12,24 +12,174 @@
  * 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",
+    "background_remove",
+    "upscale",
+];
+const DIRECT_INPUT_BYTES = 20 * 1024 * 1024;
+const RASTER_INPUT_SUFFIXES = new Set([".png", ".jpg", ".jpeg", ".webp"]);
+const LEGACY_INPUT_SUFFIXES = new Set([
+    ...RASTER_INPUT_SUFFIXES,
+    ".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",
+];
+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,
+    },
+    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",
+    };
+    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,
+    };
+    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,
+            },
+        };
     }
 }
 /**
@@ -48,12 +198,26 @@ export class StreamIdleError extends Error {
         this.name = "StreamIdleError";
     }
 }
+export class UploadTimeoutError extends Error {
+    constructor() {
+        super("the staged upload stopped before it completed; no image job was started");
+        this.name = "UploadTimeoutError";
+    }
+}
 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.
  */
 const REQUEST_TIMEOUT_MS = 130_000;
+const UPLOAD_MIN_BYTES_PER_SECOND = 256 * 1024;
+const UPLOAD_MAX_TIMEOUT_MS = 15 * 60_000;
+export function uploadTimeoutMs(bytes) {
+    const override = Number(process.env.DREAMLAYER_UPLOAD_TIMEOUT_MS);
+    if (Number.isFinite(override) && override > 0) {
+        return Math.min(Math.max(override, 100), UPLOAD_MAX_TIMEOUT_MS);
+    }
+    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`.
  *
@@ -86,40 +250,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",
@@ -131,6 +307,41 @@ 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 (!Number.isSafeInteger(value[field]) || Number(value[field]) < 0) {
+            throw new Error("Invalid DreamLayer balance response");
+        }
+    }
+    if (value.credit_usd !== "0.17" ||
+        Number(value.available) !== Number(value.promotional) + Number(value.purchased)) {
+        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.
  *
@@ -292,6 +503,7 @@ function requireEventStream(response) {
 export class ManagedClient {
     apiKey;
     baseUrl;
+    capabilitiesPromise = null;
     constructor(apiKey, baseUrl = "https://api.dreamlayer.io") {
         this.apiKey = apiKey;
         if (!apiKey.trim())
@@ -326,7 +538,13 @@ export class ManagedClient {
         yield* this.parse(stream);
     }
     async getCapabilities() {
-        const capabilities = await this.request("/v1/capabilities");
+        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;
+        });
+        const capabilities = await this.capabilitiesPromise;
         if (capabilities.api_version !== "1") {
             throw new Error("Unsupported DreamLayer Agent API version");
         }
@@ -335,6 +553,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",
@@ -348,7 +569,57 @@ export class ManagedClient {
             method: "DELETE",
         });
     }
-    uploadInput(file, filename = "input.png") {
+    async uploadInput(file, filename = "input.png") {
+        const suffix = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+        const capabilities = await this.getCapabilities();
+        const advertised = capabilities.supported_input_extensions;
+        const supported = Array.isArray(advertised)
+            ? new Set(advertised.filter((item) => typeof item === "string"))
+            : LEGACY_INPUT_SUFFIXES;
+        if (!supported.has(suffix)) {
+            throw new Error(`${filename} is not a supported image or camera RAW file`);
+        }
+        if (file.size > DIRECT_INPUT_BYTES || !RASTER_INPUT_SUFFIXES.has(suffix)) {
+            const contentType = file.type || "application/octet-stream";
+            const upload = await this.request("/v1/input-assets/uploads", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ filename, size_bytes: file.size, content_type: contentType }),
+            });
+            const targetUrl = new URL(upload.upload_url, `${this.baseUrl}/`);
+            const headers = new Headers({ "Content-Type": upload.content_type });
+            if (upload.mode === "signed") {
+                headers.set("x-goog-content-length-range", `0,${upload.maximum_bytes}`);
+            }
+            else {
+                if (targetUrl.origin !== new URL(this.baseUrl).origin) {
+                    throw new ApiError(502, "DreamLayer input upload", "refused an off-origin upload URL");
+                }
+                headers.set("Authorization", `Bearer ${this.apiKey}`);
+                headers.set("DreamLayer-Version", "1");
+            }
+            let response;
+            try {
+                response = await fetch(targetUrl, {
+                    method: upload.http_method,
+                    headers,
+                    body: file,
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(uploadTimeoutMs(file.size)),
+                });
+            }
+            catch (error) {
+                if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+                    throw new UploadTimeoutError();
+                }
+                throw error;
+            }
+            if (!response.ok)
+                throw await apiError(response, "DreamLayer input upload");
+            return this.request(`/v1/input-assets/uploads/${encodeURIComponent(upload.upload_id)}/finalize`, {
+                method: "POST",
+            });
+        }
         const body = new FormData();
         body.append("file", file, filename);
         return this.request("/v1/input-assets", { method: "POST", body });

package/package.json

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