imagen/AGENTS.md

AGENTS.md

Bun + Hono server that proxies an OpenAI-compatible image endpoint and serves a small vanilla TS playground. SSE end-to-end: streams gpt-image partial previews through, with keepalive comments that survive 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).

Config

Required env vars (validated at startup via requireEnv; the process exits if any is missing):

Var	Example	Purpose
BASE_URL	https://api.openai.com/v1	OpenAI-compatible base URL
API_KEY	sk-…	Bearer token sent to upstream
MODEL	gpt-image-2	Model name forwarded to upstream

.env.example is the source of truth for variable names. The real .env is gitignored. Restart the server after changing env vars — they are read once at module load.

These secrets stay server-side. The browser only sends prompt, size, and referenceImages. Combined with the 0.0.0.0 bind, this means anyone reachable on the network can spend your upstream quota — bind to 127.0.0.1 or put auth in front if that matters.

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), so it is reachable from other hosts on the network — be mindful when entering API keys.

Bun's dev server auto-serves /.well-known/appspecific/com.chrome.devtools.json advertising the project root to Chrome DevTools' "Automatic Workspace Folders". Sandboxed browsers (Flatpak/Snap) reject the path with Unable to add filesystem: <illegal path>. Disabled via development.chromeDevToolsAutomaticWorkspaceFolders: false.

Architecture

Three files do everything:

• index.ts — Hono app mounted under Bun.serve (fetch: app.fetch).
  • routes: { "/": index } serves index.html via Bun's HTML bundler; everything else falls through to Hono.
  • idleTimeout: 255 (max) — Bun.serve's 10s default kills SSE connections before the first keepalive can fire. The symptom is an empty EventStream in DevTools and request timed out after 10 seconds in the log.
  • POST /api/generate uses streamSSE from hono/streaming. Accepts { prompt, size, referenceImages? } — BASE_URL, API_KEY, and MODEL come from env, not the request. Emits:
    • event: partial — { image: dataUrl, index } for each image_generation.partial_image / image_edit.partial_image.
    • event: final — { image: dataUrl } for *.completed.
    • event: done — empty payload, sent before stream ends.
    • event: error — { message } for any failure.
    • First write is : connected\n\n so the browser/EventStream tab becomes responsive immediately; then a : keepalive\n\n raw comment every 15s.
  • Upstream dispatch:
    • referenceImages present → POST {baseURL}/images/edits as multipart/form-data (blobs decoded from data URLs via decodeDataUrl → Uint8Array<ArrayBuffer>). Single reference uses field name image; two or more references use image[] to match OpenAI's documented array syntax — strict gateways reject repeated image parts with a duplicate_parameter 400.
    • Otherwise → POST {baseURL}/images/generations as JSON.
    • Always sends stream: true, partial_images: 2 first. On a 400 that mentions stream or partial_images (see isStreamingUnsupportedError), retries once with stream: false and replays the JSON response as a single final event via forwardUpstreamJSON. Any other 4xx/5xx becomes an error event.
  • AbortController wired to stream.onAbort() and threaded as signal into every upstream fetch. The catch branch is suppressed when signal.aborted so closed tabs don't spam the log.
  • Targets the gpt-image series only (gpt-image-2 default). Do not reintroduce DALL·E-only fields like response_format — gpt-image always returns b64_json.
  • gpt-image-2 size constraints (per the OpenAI cookbook): both edges multiple of 16, max edge < 3840, long/short ≤ 3:1, total pixels in 655,360–8,294,400, auto not supported. Exact 16:9 requires 16k × 9k with k a multiple of 16 (so 1280×720, 1536×864, 2048×1152, 2560×1440, …). Sizes above 2560×1440 are experimental — the popular 4K target 3840×2160 violates the < 3840 rule, round down to 3824×2144 if you need it. Common misses: 1920×1080 is not valid (1080 % 16 ≠ 0).
• client.ts — browser entry, loaded via <script type="module" src="./client.ts"> in index.html. Bun's bundler resolves the import, inlines @microsoft/fetch-event-source, and serves the bundle from /_bun/client/index-*.js. Inline <script type="module"> blocks are not bundled by Bun — any client JS that imports from node_modules must live in a separate file.
  • Uses fetchEventSource instead of hand-rolled fetch + ReadableStream SSE parsing. It supports POST + body, custom headers, signal, and the onopen / onmessage / onerror callbacks.
  • On done, the client calls abort.abort() to terminate the fetchEventSource loop cleanly — otherwise it would retry forever.
  • Text fields (size, prompt) persist in localStorage under the aip:<field> prefix. Reference images stay in-memory only.
• index.html — markup + inline CSS only. No JS lives here.

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.
• lib: ["ESNext", "DOM", "DOM.Iterable"] — DOM globals are in scope for client.ts. The server file uses Bun globals from @types/bun; the overlap (fetch, Response, Blob, FormData) resolves to Web standards, which is what we want.
• TS 5.7+ split Uint8Array into Uint8Array<ArrayBuffer> vs Uint8Array<SharedArrayBuffer>. DOM's Blob/BufferSource requires the former. Allocate via new Uint8Array(new ArrayBuffer(n)) (see decodeDataUrl) rather than new Uint8Array(n) — the latter widens to ArrayBufferLike and fails to satisfy BlobPart.

When extending the API

• Routes live on the Hono app. For long-running upstream calls, mirror the existing pattern:
  • return streamSSE(c, async (stream) => { … })
  • stream.onAbort(() => abortController.abort()) at the top
  • await stream.write(": connected\n\n") to flush headers immediately
  • setInterval(() => stream.write(": keepalive\n\n").catch(() => {}), 15_000) and clearInterval in finally
  • stream.writeSSE({ event, data: JSON.stringify(payload) }) for application events
  • Catch errors and check signal.aborted before emitting error — otherwise every closed tab logs noise.
• Send the optimistic request to upstream first; detect the specific 400 via isStreamingUnsupportedError and retry with a degraded body rather than feature-detecting up front.
• Decode incoming data URLs with decodeDataUrl and pass the typed Uint8Array<ArrayBuffer> directly as a Blob part in FormData.