imagen/AGENTS.md

AGENTS.md

Bun + TypeScript single-file server that proxies an OpenAI-compatible image endpoint and serves a small vanilla HTML/JS playground. The whole pipeline is SSE end-to-end so it survives Cloudflare's 120s proxy-read timeout.

Runtime

• Bun, not Node. See CLAUDE.md for the full Bun-vs-Node cheatsheet (prefer Bun.serve, Bun.file, bun:test, Bun.sql, etc.). Do not add dotenv — Bun loads .env automatically.
• Bun version baseline: 1.3.13 (per README.md).

Commands

• Install: bun install
• Dev (HMR): bun run dev → bun --hot ./index.ts
• Start: bun run start → bun ./index.ts
• Typecheck: no script defined. Use bunx tsc --noEmit (tsconfig already sets noEmit: true, so plain bunx tsc works too).
• Tests / lint / formatter: none configured. If adding tests, use bun test.

The server binds 0.0.0.0 (see index.ts:175), so it is reachable from other hosts on the network when running locally — be mindful when entering API keys.

Architecture

• index.ts — the entire backend. One Bun.serve instance with:
  • / serves index.html via Bun's HTML import (import index from "./index.html").
  • POST /api/generate accepts { baseURL, apiKey, model, prompt, size, referenceImages? } and always responds with text/event-stream. Emitted events:
    • event: partial — { image: dataUrl, index } for each partial_image
    • event: final — { image: dataUrl } for the completed image
    • event: done — empty payload, sent right before close
    • event: error — { message } for any failure
    • SSE comments : keepalive every 20s while waiting for upstream, so Cloudflare's 120s proxy-read timeout never fires.
  • Upstream dispatch:
    • referenceImages present → POST {baseURL}/images/edits as multipart/form-data (image blobs decoded from data URLs).
    • Otherwise → POST {baseURL}/images/generations as JSON.
    • Both calls send stream: true, partial_images: 2 first. If upstream returns a 400 mentioning stream or partial_images, isStreamingUnsupportedError triggers a single retry with stream: false and the response is replayed as one final event via forwardUpstreamJSON. Any other 4xx/5xx propagates as error.
  • Targets the gpt-image series only (gpt-image-2 is the default). Do not reintroduce DALL·E-only fields like response_format — gpt-image always returns b64_json.
• index.html — self-contained UI: inline CSS, plain DOM JS, no build step. Reads the SSE response via fetch + ReadableStream (not EventSource, because the API is POST). Partials overwrite a single <img> so the preview animates in place. Text fields (baseURL, apiKey, model, size, prompt) persist in localStorage under the aip:<field> prefix. Reference images are kept in an in-memory refImages array as base64 data URLs and are not persisted. There is no React code despite react / react-dom / @types/react* being in package.json — treat those deps as latent. Do not invent a React frontend unless asked.
• No router, no DB, no auth, no AI SDK. API key is supplied per-request by the browser and never stored server-side.

TypeScript conventions

tsconfig.json is strict with bundler-mode resolution:

• strict, noUncheckedIndexedAccess, noImplicitOverride, noFallthroughCasesInSwitch are on — array/object index access is T | undefined and must be narrowed.
• verbatimModuleSyntax + moduleDetection: "force" — use import type for type-only imports; every file is a module.
• allowImportingTsExtensions is on; .ts extensions in imports are fine.
• jsx: "react-jsx" is set but unused (see frontend note above).

When extending the API

• Add routes inside the routes object in index.ts; keep the { POST: async (req) => … } shape used by /api/generate.
• For any long-running upstream call, mirror the SSE-with-keepalive pattern: build a ReadableStream<Uint8Array>, start a 20s : keepalive comment timer in start(), do work inside try, always clearInterval and controller.close() in finally. Helpers sseEvent / sseComment already exist.
• Stay defensive about upstream capabilities: many OpenAI-compatible providers reject unknown params. Send the optimistic request first, then detect the specific 400 (see isStreamingUnsupportedError) and retry with a degraded body rather than feature-detecting up front.
• Decode incoming data URLs with decodeDataUrl (returns Buffer + mime) and pass them as Blob parts to FormData — same pattern as the edits path.