dreamlayer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DreamLayer AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,9 @@
+DreamLayer CLI
+Copyright (c) 2026 DreamLayer AI
+
+This package is a thin client. It sends requests to the DreamLayer Agent API at
+https://api.dreamlayer.io and returns what that service replies. The service itself
+is proprietary and is not included here.
+
+Nothing in this package inspects, stores, or transmits your prompts or images anywhere
+other than the DreamLayer Agent API, using the key you supply in DREAMLAYER_API_KEY.

package/README.md

@@ -0,0 +1,98 @@
+# dreamlayer
+
+Generate and edit images from your terminal, over local files, with one API key.
+
+```bash
+npm install -g dreamlayer
+export DREAMLAYER_API_KEY="dlr_live_your_key"
+
+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
+dreamlayer generate <prompt> [--aspect 16:9] [--out file.png]
+dreamlayer edit <image> <prompt> [--out file.png]
+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 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.
+
+`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.
+
+## It composes
+
+**stdout is the result, stderr is the narration.** On success stdout is the file path
+and nothing else, so this works:
+
+```bash
+open "$(dreamlayer generate 'a fox logo')"
+```
+
+**Exit codes mean something**, so a script can branch instead of grepping:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Usage error |
+| 2 | Auth or account problem |
+| 3 | Out of credits |
+| 4 | Request rejected, will fail identically until you change it |
+| 5 | Temporary, worth retrying |
+| 6 | It asked a question instead of producing an image |
+
+```bash
+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.
+
+## 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:
+
+```bash
+dreamlayer generate "a fox logo" --idempotency-key fox-001
+```
+
+## A question is not a failure
+
+An edit-shaped prompt with no image exits 6 and asks for one:
+
+```bash
+dreamlayer generate "remove the background"
+# Which image should I use? Upload or attach one, then respond.
+#   dreamlayer answer <id> "your answer" --image <file>
+```
+
+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.
+
+## Requirements
+
+Node.js 22.12 or later.
+
+## License
+
+MIT. See LICENSE and NOTICE.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * 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 { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ApiError, ManagedClient, StreamIdleError, } from "./client.js";
+import { Progress, consume } from "./render.js";
+const USAGE = `dreamlayer - generate and edit images from your terminal
+
+USAGE
+  dreamlayer generate <prompt> [--aspect <ratio>] [--out <file>]
+  dreamlayer edit <image> <prompt> [--out <file>]
+  dreamlayer cutout <image> [--out <file>]
+  dreamlayer upscale <image> [--out <file>]
+  dreamlayer answer <conversation-id> <text> [--image <file>] [--out <file>]
+  dreamlayer status <execution-id>
+  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
+  --json            Machine-readable output on stdout
+  --quiet           No progress on stderr
+  --idempotency-key <key>  Reuse to retry safely after an uncertain response
+
+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.
+`;
+class UsageError extends Error {
+}
+function parseOptions(argv) {
+    const positional = [];
+    const options = {
+        out: null,
+        image: null,
+        aspect: "1:1",
+        json: false,
+        quiet: false,
+        idempotencyKey: null,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "--json")
+            options.json = true;
+        else if (token === "--quiet")
+            options.quiet = true;
+        else if (token === "--out" || token === "-o") {
+            const value = argv[++i];
+            if (!value)
+                throw new UsageError("--out needs a file path");
+            options.out = value;
+        }
+        else if (token === "--image") {
+            const value = argv[++i];
+            if (!value)
+                throw new UsageError("--image needs a file path");
+            options.image = value;
+        }
+        else if (token === "--aspect") {
+            const value = argv[++i];
+            if (!value)
+                throw new UsageError("--aspect needs a ratio");
+            options.aspect = value;
+        }
+        else if (token === "--idempotency-key") {
+            const value = argv[++i];
+            if (!value)
+                throw new UsageError("--idempotency-key needs a value");
+            options.idempotencyKey = value;
+        }
+        else if (token !== undefined && token.startsWith("-")) {
+            throw new UsageError(`unknown option ${token}`);
+        }
+        else if (token !== undefined) {
+            positional.push(token);
+        }
+    }
+    return { positional, options };
+}
+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");
+    }
+    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. */
+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;
+    try {
+        bytes = await readFile(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`);
+    }
+    const asset = await api.uploadInput(new Blob([new Uint8Array(bytes)]), path.basename(resolved));
+    return asset.input_asset_id;
+}
+function defaultOut() {
+    return `dreamlayer-${Date.now()}.png`;
+}
+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);
+    if (outcome.question) {
+        progress.stop();
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(outcome, 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`);
+        }
+        return 6;
+    }
+    if (outcome.status !== "completed" || !outcome.asset) {
+        progress.stop("Failed");
+        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;
+    }
+    progress.set("Downloading");
+    const bytes = await api.download(outcome.asset.download_url);
+    const target = options.out ?? defaultOut();
+    await writeFile(target, bytes);
+    progress.stop();
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ ...outcome, 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;
+}
+async function imageCommand(operation, prompt, file, options) {
+    const api = client();
+    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
+            ?.execution_id
+        : null;
+    return id ? `The job may still be running. Check it with:\n  dreamlayer status ${id}\n` : "";
+}
+function exitCodeFor(error) {
+    if (error.status === 401 || error.status === 403)
+        return 2;
+    if (error.status === 402)
+        return 3;
+    if (error.status === 409 || error.status === 422)
+        return 4;
+    return 5;
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h" || command === "help") {
+        process.stdout.write(USAGE);
+        return command ? 0 : 1;
+    }
+    if (command === "--version" || command === "-v") {
+        process.stdout.write("0.1.0\n");
+        return 0;
+    }
+    const { positional, options } = parseOptions(rest);
+    switch (command) {
+        case "generate": {
+            const prompt = positional[0];
+            if (!prompt)
+                throw new UsageError("generate needs a prompt");
+            return run(client(), { prompt, operation: "text_to_image", aspect_ratio: options.aspect }, options);
+        }
+        case "edit": {
+            const [file, prompt] = positional;
+            if (!file || !prompt)
+                throw new UsageError("edit needs an image and a prompt");
+            return imageCommand("image_to_image", prompt, file, options);
+        }
+        case "cutout": {
+            const file = positional[0];
+            if (!file)
+                throw new UsageError("cutout needs an image");
+            return imageCommand("background_remove", "remove the background", file, options);
+        }
+        case "upscale": {
+            const file = positional[0];
+            if (!file)
+                throw new UsageError("upscale needs an image");
+            return imageCommand("upscale", "upscale this image", file, options);
+        }
+        case "answer": {
+            const [conversationId, text] = positional;
+            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,
+                conversation_id: conversationId,
+                ...(input ? { input_asset_id: input } : {}),
+            }, options);
+        }
+        case "status": {
+            const executionId = positional[0];
+            if (!executionId)
+                throw new UsageError("status needs an execution id");
+            const execution = await client().getExecution(executionId);
+            process.stdout.write(`${JSON.stringify(execution, null, 2)}\n`);
+            return 0;
+        }
+        case "capabilities": {
+            const capabilities = await client().getCapabilities();
+            process.stdout.write(`${JSON.stringify(capabilities, null, 2)}\n`);
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown command ${command}`);
+    }
+}
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    if (error instanceof UsageError) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (error instanceof ApiError) {
+        const hint = error.status === 402
+            ? "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`);
+        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");
+        process.stderr.write(recoveryHint(error));
+        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

@@ -0,0 +1,121 @@
+/**
+ * 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 type ManagedOperation = "text_to_image" | "image_to_image" | "background_remove" | "upscale";
+export type ManagedExecuteInput = {
+    prompt?: string;
+    respond?: string;
+    conversation_id?: string;
+    input_asset_id?: string;
+    aspect_ratio?: string;
+    /** Requires the gateway build that added it. See ManagedOperation. */
+    operation?: ManagedOperation;
+};
+export type ManagedInputAsset = {
+    input_asset_id: string;
+    width: number;
+    height: number;
+    expires_at: string;
+};
+export type ManagedExecution = {
+    execution_id: string;
+    conversation_id: string;
+    status: string;
+    image_job: Record<string, unknown> | null;
+};
+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 requestId: string | null;
+    constructor(status: number, surface?: string, detail?: string | null, 
+    /** Server-assigned id for this failure. The only handle support can search on. */
+    requestId?: string | null);
+    /** Whether retrying with the same idempotency key is worth doing. */
+    get retryable(): boolean;
+}
+/**
+ * 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();
+}
+/**
+ * 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;
+    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>;
+    /** 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>;
+    cancel(executionId: string): Promise<ManagedExecution>;
+    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;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,458 @@
+/**
+ * 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 class ApiError extends Error {
+    status;
+    detail;
+    requestId;
+    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})`);
+        this.status = status;
+        this.detail = detail;
+        this.requestId = requestId;
+        this.name = "ApiError";
+    }
+    /** Whether retrying with the same idempotency key is worth doing. */
+    get retryable() {
+        return this.status === 429 || this.status >= 500;
+    }
+}
+/**
+ * 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() {
+        super(`the stream sent nothing for ${Math.round(STREAM_IDLE_TIMEOUT_MS / 1000)}s, so the ` +
+            "connection is treated as dead. The job may still be running on the server.");
+        this.name = "StreamIdleError";
+    }
+}
+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;
+/**
+ * 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)
+        return STREAM_IDLE_DEFAULT_MS;
+    return Math.min(Math.max(raw, 100), 15 * 60_000);
+})();
+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 apiError(response, surface = "DreamLayer Agent API") {
+    let detail = null;
+    let requestId = null;
+    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);
+            }
+        }
+    }
+    catch {
+        detail = null;
+    }
+    return new ApiError(response.status, surface, detail, requestId);
+}
+const MANAGED_EVENT_NAMES = new Set([
+    "started",
+    "thinking",
+    "progress",
+    "job",
+    "question",
+    "asset",
+    "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;
+/**
+ * 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");
+    }
+    const data = { ...value };
+    const exact = (required, optional = []) => {
+        const keys = Object.keys(data);
+        if (!required.every((key) => keys.includes(key)) ||
+            !keys.every((key) => required.includes(key) || optional.includes(key))) {
+            throw new Error("Invalid DreamLayer managed event fields");
+        }
+    };
+    const uuid = (key) => {
+        const candidate = data[key];
+        if (typeof candidate !== "string" || !UUID_PATTERN.test(candidate)) {
+            throw new Error("Invalid DreamLayer managed event identifier");
+        }
+    };
+    const text = (key, maximum) => {
+        const candidate = data[key];
+        if (typeof candidate !== "string" || candidate.length === 0 || candidate.length > maximum) {
+            throw new Error("Invalid DreamLayer managed event text");
+        }
+    };
+    switch (event) {
+        case "started":
+            exact(["execution_id", "conversation_id"]);
+            uuid("execution_id");
+            uuid("conversation_id");
+            break;
+        case "thinking":
+            exact([]);
+            break;
+        case "progress":
+            exact(["text"]);
+            text("text", 300);
+            break;
+        case "job":
+            exact(["public_job_id", "status"]);
+            uuid("public_job_id");
+            if (!["queued", "running", "completed", "failed"].includes(String(data.status))) {
+                throw new Error("Invalid DreamLayer managed job status");
+            }
+            break;
+        case "question":
+            exact(["question_id", "conversation_id", "text"]);
+            uuid("question_id");
+            uuid("conversation_id");
+            text("text", 300);
+            break;
+        case "asset":
+            exact(["asset_id", "download_url"]);
+            uuid("asset_id");
+            text("download_url", 500);
+            break;
+        case "done":
+            exact(["status"], ["conversation_id", "message"]);
+            if (!["needs_input", "completed", "failed", "cancelled"].includes(String(data.status))) {
+                throw new Error("Invalid DreamLayer managed completion status");
+            }
+            if (data.conversation_id !== undefined)
+                uuid("conversation_id");
+            if (data.message !== undefined)
+                text("message", 300);
+            break;
+    }
+    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 });
+        let boundary = buffer.indexOf("\n\n");
+        while (boundary >= 0) {
+            const block = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            const lines = block.split("\n");
+            const event = lines
+                .find((line) => line.startsWith("event:"))
+                ?.slice(6)
+                .trim();
+            const id = lines
+                .find((line) => line.startsWith("id:"))
+                ?.slice(3)
+                .trim() ?? null;
+            const data = lines
+                .filter((line) => line.startsWith("data:"))
+                .map((line) => line.slice(5).trim())
+                .join("\n");
+            if (event && data)
+                yield { event, id, data: JSON.parse(data) };
+            boundary = buffer.indexOf("\n\n");
+        }
+        if (done)
+            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]";
+}
+function managedOrigin(value) {
+    if (!value || value.endsWith("?") || value.endsWith("#")) {
+        throw new Error("Managed endpoint must be a clean HTTPS origin");
+    }
+    const parsed = new URL(value);
+    if (parsed.username ||
+        parsed.password ||
+        (parsed.pathname !== "" && parsed.pathname !== "/") ||
+        parsed.search ||
+        parsed.hash) {
+        throw new Error("Managed endpoint must be a clean HTTPS origin");
+    }
+    const loopback = isLoopback(parsed.hostname);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopback)) {
+        throw new Error("Managed endpoint must use HTTPS, except for exact loopback development");
+    }
+    const permitted = ALLOWED_HOSTS.has(parsed.hostname) ||
+        loopback ||
+        (process.env.DREAMLAYER_ALLOW_ANY_HOST ?? "").trim() === "1";
+    if (!permitted) {
+        throw new Error(`Refusing to send an API key to ${parsed.hostname}. ` +
+            `Expected api.dreamlayer.io. Set DREAMLAYER_ALLOW_ANY_HOST=1 to override.`);
+    }
+    return parsed.origin;
+}
+function requireEventStream(response) {
+    if (!response.headers.get("content-type")?.includes("text/event-stream")) {
+        throw new Error("DreamLayer managed endpoint did not return an event stream");
+    }
+}
+export class ManagedClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl = "https://api.dreamlayer.io") {
+        this.apiKey = apiKey;
+        if (!apiKey.trim())
+            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) {
+        const stream = await this.fetchStream("/v1/execute", {
+            method: "POST",
+            headers: {
+                Accept: "text/event-stream",
+                "Content-Type": "application/json",
+                "Idempotency-Key": options.idempotencyKey,
+            },
+            body: JSON.stringify(input),
+        });
+        yield* this.parse(stream);
+    }
+    /** 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)
+            headers["Last-Event-ID"] = lastEventId;
+        const stream = await this.fetchStream(`/v1/executions/${encodeURIComponent(executionId)}/events`, { headers });
+        yield* this.parse(stream);
+    }
+    async getCapabilities() {
+        const capabilities = await this.request("/v1/capabilities");
+        if (capabilities.api_version !== "1") {
+            throw new Error("Unsupported DreamLayer Agent API version");
+        }
+        return capabilities;
+    }
+    getExecution(executionId) {
+        return this.request(`/v1/executions/${encodeURIComponent(executionId)}`);
+    }
+    cancel(executionId) {
+        return this.request(`/v1/executions/${encodeURIComponent(executionId)}/cancel`, {
+            method: "POST",
+        });
+    }
+    listConversations() {
+        return this.request("/v1/conversations");
+    }
+    deleteConversation(conversationId) {
+        return this.request(`/v1/conversations/${encodeURIComponent(conversationId)}`, {
+            method: "DELETE",
+        });
+    }
+    uploadInput(file, filename = "input.png") {
+        const body = new FormData();
+        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;
+            }
+            catch {
+                return false;
+            }
+        })();
+        const response = await fetch(url, {
+            headers: sameOrigin ? { Authorization: `Bearer ${this.apiKey}` } : {},
+            redirect: "follow",
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            throw await apiError(response);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async *parse(stream) {
+        const { response, keepAlive, finish } = stream;
+        if (!response.body) {
+            finish();
+            throw new Error("DreamLayer managed endpoint returned no body");
+        }
+        try {
+            for await (const block of readEventStream(response.body, keepAlive)) {
+                yield managedEvent(block.event, block.id, block.data);
+            }
+        }
+        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();
+        }
+    }
+    async fetchStream(path, init) {
+        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 = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => controller.abort(new StreamIdleError()), STREAM_IDLE_TIMEOUT_MS);
+            timer.unref?.();
+        };
+        const finish = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+        };
+        keepAlive();
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                ...init,
+                headers,
+                redirect: "manual",
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                finish();
+                throw await apiError(response);
+            }
+            requireEventStream(response);
+            return { response, keepAlive, finish };
+        }
+        catch (error) {
+            finish();
+            throw error;
+        }
+    }
+    async request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${this.apiKey}`);
+        headers.set("DreamLayer-Version", "1");
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            ...init,
+            headers,
+            redirect: "manual",
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            throw await apiError(response);
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+}

package/dist/render.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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;
+    conversation_id: string | null;
+    status: string;
+    asset: {
+        asset_id: string;
+        download_url: string;
+    } | null;
+    question: {
+        question_id: string;
+        text: string;
+    } | null;
+    last_event_id: string | null;
+};
+export declare class Progress {
+    private readonly enabled;
+    private timer;
+    private frame;
+    private label;
+    constructor(enabled: boolean);
+    set(label: string): void;
+    stop(final?: string): void;
+}
+export declare function consume(stream: AsyncGenerator<ManagedEvent>, progress: Progress, onEvent?: (event: ManagedEvent) => void): Promise<Outcome>;

package/dist/render.js

@@ -0,0 +1,113 @@
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export class Progress {
+    enabled;
+    timer = null;
+    frame = 0;
+    label = "";
+    constructor(enabled) {
+        this.enabled = enabled;
+    }
+    set(label) {
+        this.label = label;
+        if (!this.enabled)
+            return;
+        if (this.timer === null) {
+            this.timer = setInterval(() => {
+                this.frame = (this.frame + 1) % FRAMES.length;
+                process.stderr.write(`\r${FRAMES[this.frame]} ${this.label}`);
+            }, 90);
+            this.timer.unref();
+        }
+    }
+    stop(final) {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (!this.enabled) {
+            if (final)
+                process.stderr.write(`${final}\n`);
+            return;
+        }
+        process.stderr.write(`\r`);
+        if (final)
+            process.stderr.write(`${final}\n`);
+    }
+}
+/** Human wording for each event. `thinking` carries no text by contract. */
+function describe(event) {
+    switch (event.event) {
+        case "started":
+            return "Starting";
+        case "thinking":
+            return "Working";
+        case "progress":
+            return String(event.data.text ?? "Working");
+        case "job":
+            return `Job ${String(event.data.status)}`;
+        case "question":
+            return null;
+        case "asset":
+            return "Downloading";
+        case "done":
+            return null;
+    }
+}
+export async function consume(stream, progress, onEvent) {
+    const outcome = {
+        execution_id: null,
+        conversation_id: null,
+        status: "unknown",
+        asset: null,
+        question: null,
+        last_event_id: null,
+    };
+    try {
+        for await (const event of stream) {
+            onEvent?.(event);
+            outcome.last_event_id = event.id;
+            const label = describe(event);
+            if (label)
+                progress.set(label);
+            if (event.event === "started") {
+                outcome.execution_id = String(event.data.execution_id);
+                outcome.conversation_id = String(event.data.conversation_id);
+            }
+            else if (event.event === "asset") {
+                outcome.asset = {
+                    asset_id: String(event.data.asset_id),
+                    download_url: String(event.data.download_url),
+                };
+            }
+            else if (event.event === "question") {
+                outcome.question = {
+                    question_id: String(event.data.question_id),
+                    text: String(event.data.text),
+                };
+                if (event.data.conversation_id) {
+                    outcome.conversation_id = String(event.data.conversation_id);
+                }
+            }
+            else if (event.event === "done") {
+                outcome.status = String(event.data.status);
+                if (event.data.conversation_id) {
+                    outcome.conversation_id = String(event.data.conversation_id);
+                }
+            }
+        }
+    }
+    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;
+        }
+        throw error;
+    }
+    return outcome;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "dreamlayer",
+  "version": "0.1.0",
+  "description": "Generate and edit images from your terminal, over local files, with one API key.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dreamlayer": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "pnpm test"
+  },
+  "devDependencies": {
+    "typescript": "5.9.2",
+    "@types/node": "^22.10.0"
+  },
+  "keywords": [
+    "image-generation",
+    "cli",
+    "dreamlayer",
+    "ai",
+    "image-editing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheDesignFounder/dreamlayer-cli.git"
+  },
+  "homepage": "https://docs.dreamlayer.io/cli"
+}