@opencode-ai/ai 0.0.0-bootstrap.0 → 0.0.0-dev-17472

package/README.md

@@ -1,3 +1,392 @@
 # @opencode-ai/ai
 
-Bootstrap release. Use a current `next` or `latest` version for the real package.
+Schema-first AI primitives for opencode. Provider quirks live in adapters, not in calling code.
+
+```ts
+import { Effect, Layer } from "effect"
+import { LLM, LLMClient } from "@opencode-ai/ai"
+import { RequestExecutor } from "@opencode-ai/ai/route"
+import { OpenAI } from "@opencode-ai/ai/providers"
+
+const model = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
+
+const request = LLM.request({
+  model,
+  system: "You are concise.",
+  prompt: "Say hello in one short sentence.",
+  generation: { maxTokens: 40 },
+})
+
+const program = Effect.gen(function* () {
+  const response = yield* LLMClient.generate(request)
+  console.log(response.text)
+})
+
+const llmLayer = LLMClient.layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
+
+await Effect.runPromise(program.pipe(Effect.provide(llmLayer)))
+```
+
+Run `LLMClient.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
+
+## Image generation
+
+Use `Image.generate` with an image model for direct asset generation:
+
+```ts
+import { Image, ImageInput } from "@opencode-ai/ai"
+import { OpenAI } from "@opencode-ai/ai/providers"
+
+const program = Effect.gen(function* () {
+  const response = yield* Image.generate({
+    model: OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).image("gpt-image-2"),
+    prompt: "A robot tending a rooftop garden",
+    options: {
+      n: 2,
+      size: "1024x1024",
+      quality: "high", // inferred from the OpenAI image model
+      outputFormat: "webp",
+      future_option: true, // unknown native options pass through unchanged
+    },
+  })
+
+  return response.images // GeneratedImage[] with owned bytes or a provider URL
+})
+```
+
+Pass ordered image inputs to the same method for editing, composition, or image-conditioned generation:
+
+```ts
+const response =
+  yield *
+  Image.generate({
+    model,
+    prompt: "Combine these product photos into one studio scene",
+    images: [
+      ImageInput.bytes(firstBytes, "image/png"),
+      ImageInput.url("https://example.com/second.webp"),
+      ImageInput.file("file_123"),
+    ],
+    options,
+    http,
+  })
+```
+
+`ImageInput.fileUri(uri, mediaType)` represents provider file URIs such as Gemini Files. Raw strings are not
+accepted as image inputs, avoiding ambiguity between base64, URLs, and provider IDs. Empty or omitted `images`
+uses text-to-image generation; a non-empty array selects the provider's edit behavior without enforcing provider
+image-count limits locally. `images` is the only common image-editing field. OpenAI uses multipart for byte/data-URL
+edits and its JSON reference body for URL or file-ID edits. Its provider-specific `options.mask` accepts an
+`ImageInput` for inpainting:
+
+```ts
+yield *
+  Image.generate({
+    model: OpenAI.configure({ apiKey }).image("gpt-image-2"),
+    prompt,
+    images: [ImageInput.bytes(sourceBytes, "image/png")],
+    options: { mask: ImageInput.bytes(maskBytes, "image/png") },
+  })
+```
+
+The OpenAI adapter extracts this helper value into the edit request's native `mask` field rather than passing the
+tagged `ImageInput` object through as an ordinary option. On multipart requests, `http.body` can override option
+fields but not structural `model`, `prompt`, `image[]`, or `mask` fields, and the transport owns the multipart
+`Content-Type` boundary. For JSON requests, `http.body` remains the final raw-native overlay. Gemini does not fetch
+public HTTP URLs, and hosted Z.ai image generation does not accept image inputs. These cases fail with
+`InvalidRequest` before network I/O.
+
+Provider-native image options belong to each request. Raw `http.body` fields have final precedence over them:
+
+```ts
+const model = OpenAI.configure({ apiKey }).image("gpt-image-2")
+
+yield *
+  Image.generate({
+    model,
+    prompt,
+    options: { quality: "medium" },
+    http,
+  })
+```
+
+xAI image models use the same request API with xAI-native controls:
+
+```ts
+yield *
+  Image.generate({
+    model: XAI.configure({ apiKey }).image("any-model-id"),
+    prompt,
+    options: {
+      n: 2,
+      aspectRatio: "16:9",
+      resolution: "1k",
+      responseFormat: "b64_json",
+      future_option: true,
+    },
+    http,
+  })
+```
+
+Google's current Gemini image models use the same direct API:
+
+```ts
+import { Google } from "@opencode-ai/ai/providers"
+
+const googleProgram = Effect.gen(function* () {
+  const response = yield* Image.generate({
+    model: Google.configure({ apiKey }).image("any-model-id"),
+    prompt: "A robot tending a rooftop garden",
+    options: {
+      aspectRatio: "16:9",
+      imageSize: "2K",
+      seed: 42,
+      thinkingLevel: "HIGH",
+      includeThoughts: true,
+      futureOption: true,
+    },
+    http,
+  })
+
+  return response.images
+})
+```
+
+Google image options are request-scoped and inferred from the selected model. Known fields autocomplete while
+future string values and arbitrary native Gemini `generationConfig` fields remain available. Native fields override
+their mapped aliases, and `http.body` is the final deep overlay. The selected model ID is sent to Gemini
+`generateContent` without a local allowlist.
+
+Z.ai image models infer open Z.ai-native options from the selected model:
+
+```ts
+yield *
+  Image.generate({
+    model: ZAI.configure({ apiKey }).image("any-model-id"),
+    prompt,
+    options: {
+      quality: "hd",
+      userID: "user-123",
+      future_option: true,
+    },
+    http,
+  })
+```
+
+Z.ai does not include trustworthy MIME metadata for output URLs, so generated images use
+`application/octet-stream`. Output URLs expire after 30 days; download and persist them promptly if they must
+remain available.
+
+Conversational image generation remains part of the LLM interaction. OpenAI Responses exposes it through its hosted image tool:
+
+```ts
+const program = Effect.gen(function* () {
+  const response = yield* LLM.generate(
+    LLM.request({
+      model: OpenAI.configure({ apiKey }).responses("gpt-5"),
+      prompt: "Design a solarpunk rooftop garden, then show me.",
+      tools: [OpenAI.imageGeneration({ quality: "high" })],
+    }),
+  )
+
+  return response.message
+})
+```
+
+The hosted result is represented as a provider-executed tool call and tool result. Its image is a `file` content item with a data URI, so retaining `response.message` preserves the generated image for continuation.
+
+## Public API
+
+- **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
+- **`LLM.generate` / `LLM.stream`** — re-exported from `LLMClient` for one-import use.
+- **`Message.user(...)` / `Message.assistant(...)` / `Message.tool(...)`** — message constructors from the canonical schema model.
+- **`LanguageModel.make(...)` / `ToolCallPart.make(...)` / `ToolResultPart.make(...)` / `ToolDefinition.make(...)`** — model and tool-related constructors from the canonical schema model.
+- **`LLMEvent.is.*`** — typed guards (`is.textDelta`, `is.toolCall`, `is.finish`, …) for filtering streams.
+- **`Image.generate({...})`** — generate images through a provider-neutral image request and response model.
+- **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.
+
+## Testing
+
+Use the deterministic test client from `@opencode-ai/ai/testing` to script provider-neutral responses and inspect
+the requests sent by code under test:
+
+```ts
+import { Effect } from "effect"
+import { TestLLM } from "@opencode-ai/ai/testing"
+
+const testLLM = TestLLM.layer({
+  fallback: TestLLM.text("Hello from the test model", "text-1"),
+})
+
+// TestLLM.clientLayer provides LLMClient.Service and consumes TestLLM.Service.
+const programWithTestClient = Effect.gen(function* () {
+  const result = yield* program
+  const test = yield* TestLLM.Service
+  console.log(test.requests)
+  return result
+}).pipe(Effect.provide(TestLLM.clientLayer), Effect.provide(testLLM))
+```
+
+`TestLLM.push(...)` scripts one-shot responses, `TestLLM.always(...)` changes the fallback, and
+`TestLLM.wait(...)` lets concurrent tests wait until a request has arrived. Every received canonical request is
+available on the yielded `TestLLM.Service`.
+
+## Caching
+
+Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "auto"` unless the caller opts out with `cache: "none"`. Each protocol translates `CacheHint`s to its wire format (`cache_control` on Anthropic, `cachePoint` on Bedrock; OpenAI and Gemini do implicit caching server-side and don't need inline markers — auto is a no-op there).
+
+### Auto placement
+
+`"auto"` places up to four breakpoints — the last tool definition, the first system part, the last system part when distinct, and the final message boundary. These expose successively larger reusable prefixes for tools, the base agent, project instructions, and the active conversation. The rolling final-message boundary is the load-bearing detail in tool loops: it advances on every request so the previous cache entry stays within Anthropic's 20-block lookback.
+
+Tools precede every system and conversation block in the provider prefix, so tool definitions must remain byte-stable and deterministically ordered for downstream breakpoints to remain reusable.
+
+The math justifies the default: Anthropic's 5-minute cache write is 1.25× base, read is 0.1×, so a single reuse within 5 minutes already wins. One-shot completions below the per-model minimum-cacheable-token threshold silently no-op on the wire, so the worst case is harmless.
+
+### Opting out
+
+```ts
+LLM.request({
+  model,
+  system,
+  prompt: "one-off question",
+  cache: "none",
+})
+```
+
+### Granular policy
+
+```ts
+cache: {
+  tools?: boolean,
+  system?: boolean,
+  messages?: "latest-user-message" | "latest-assistant" | { tail: number },
+  ttlSeconds?: number,         // ≥ 3600 → 1h on Anthropic/Bedrock; else 5m
+}
+```
+
+### Manual hints
+
+Inline `CacheHint` on any text / system / tool / tool-result part overrides automatic placement. The auto policy preserves manual hints, counts them against Anthropic and Bedrock's four-breakpoint limit, and only fills the remaining slots.
+
+```ts
+LLM.request({
+  model,
+  system: [
+    { type: "text", text: "stable system prompt", cache: { type: "ephemeral" } },
+  ],
+  ...
+})
+```
+
+### Provider behavior table
+
+| Protocol                | `cache: "auto"`                                                           |
+| ----------------------- | ------------------------------------------------------------------------- |
+| Anthropic Messages      | emits up to 4 `cache_control` markers (4-breakpoint cap enforced)         |
+| Bedrock Converse        | emits up to 4 `cachePoint` blocks (4-breakpoint cap enforced)             |
+| OpenAI Chat / Responses | no-op (implicit caching above 1024 tokens)                                |
+| Gemini                  | no-op (implicit caching on 2.5+; explicit `CachedContent` is out-of-band) |
+
+Normalized cache usage is read back into `response.usage.cacheReadInputTokens` and `cacheWriteInputTokens` across every provider.
+
+## Providers
+
+Provider facades configure endpoint/auth/deployment details first, then expose model selectors that take only a model or deployment id. The selected model carries the executable route value used at runtime.
+
+```ts
+import { OpenAI, CloudflareAIGateway } from "@opencode-ai/ai/providers"
+
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
+const gateway = CloudflareAIGateway.configure({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+  gatewayApiKey: process.env.CLOUDFLARE_API_TOKEN,
+}).model("workers-ai/@cf/meta/llama-3.1-8b-instruct")
+```
+
+Included providers: OpenAI, Anthropic, Google (Gemini), Google Vertex Gemini and Anthropic, Amazon Bedrock, Azure OpenAI, Cloudflare AI Gateway, Cloudflare Workers AI, GitHub Copilot, OpenRouter, xAI, Z.ai, plus generic OpenAI-compatible Chat and Responses entrypoints and an Anthropic Messages-compatible entrypoint.
+
+### Package-like entrypoints
+
+Native catalog integrations load provider behavior through package-like entrypoints. These are export paths from the same `@opencode-ai/ai` npm package, not independently published packages. Each entrypoint exports the same `model(modelID, settings)` contract, and `settings` contains serializable provider configuration plus common `headers`, `body`, and `limits` overlays.
+
+```ts
+import { model } from "@opencode-ai/ai/providers/openai/responses"
+
+const selected = model("gpt-5", {
+  apiKey: process.env.OPENAI_API_KEY,
+  headers: { "x-application": "opencode" },
+  limits: { context: 200_000, output: 64_000 },
+})
+```
+
+OpenAI Chat and OpenAI Responses are separate semantic entrypoints:
+
+- `@opencode-ai/ai/providers/openai/chat`
+- `@opencode-ai/ai/providers/openai/responses`
+- `@opencode-ai/ai/providers/openai-compatible/responses`
+- `@opencode-ai/ai/providers/anthropic-compatible`
+- `@opencode-ai/ai/providers/google-vertex/gemini`
+- `@opencode-ai/ai/providers/google-vertex/chat`
+- `@opencode-ai/ai/providers/google-vertex/responses`
+- `@opencode-ai/ai/providers/google-vertex/messages`
+
+OpenAI Responses has one semantic route and uses HTTP by default. Advanced callers may supply a per-call WebSocket channel executor through `StreamOptions`; transport policy does not change provider settings, model identity, or route identity. The provider-neutral Open Responses implementation owns the reusable WebSocket request and event contract, while each provider opts in with its own handshake and connection policy. Azure follows the same Chat/Responses split at `providers/azure/chat` and `providers/azure/responses`. Generic OpenAI-compatible Chat remains at `providers/openai-compatible`; the Responses adapter at `providers/openai-compatible/responses` uses the provider-neutral Open Responses protocol. OpenAI Responses extends that baseline with OpenAI tools, event variants, metadata, and defaults. Generic Anthropic Messages-compatible providers use `providers/anthropic-compatible`, which the named Anthropic provider composes. Google Gemini and Amazon Bedrock expose their single native API through their existing provider paths.
+
+Vertex Gemini, Vertex Chat, Vertex Responses, and Vertex Messages are separate API entrypoints. All accept `project`, `location`, and an optional `accessToken`; when no explicit token or auth override is supplied they lazily use Google Application Default Credentials. Vertex Gemini instead selects express mode when `apiKey` or `GOOGLE_VERTEX_API_KEY` is present. Vertex Chat targets MaaS models through the OpenAI-compatible Chat Completions endpoint, while Vertex Responses targets Grok models and defaults `store` to `false` as required by Vertex. `providers/google-vertex` remains the default alias for `providers/google-vertex/gemini`.
+
+Tuned Vertex Gemini deployments use model ids shaped like `endpoints/1234567890` and require OAuth or ADC; Vertex express-mode API keys support publisher models only.
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/gemini"
+
+model("gemini-3.5-flash", { project: "my-project", location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/chat"
+
+model("deepseek-ai/deepseek-v3.2-maas", { project: "my-project", location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/responses"
+
+model("xai/grok-4.20-reasoning", { project: "my-project", location: "global" })
+```
+
+```ts
+import { model } from "@opencode-ai/ai/providers/google-vertex/messages"
+
+model("claude-sonnet-4-6", { project: "my-project", location: "global" })
+```
+
+Provider facades such as `OpenAI.configure(...).responses(...)` remain the direct application API. Package-like entrypoints are the self-similar loading contract used when a catalog selects behavior by export path.
+
+Other provider exports listed above remain direct facades until they explicitly implement the package-like contract. Exporting a provider facade does not implicitly make it a catalog-loadable provider package.
+
+## Provider options & HTTP overlays
+
+Request options in order of stability:
+
+1. **`generation`** — portable knobs (`maxTokens`, `temperature`, `topP`, `topK`, penalties, seed, stop).
+2. **`promptCacheKey`** — stable cache affinity lowered by every protocol that supports it.
+3. **`providerOptions: { <provider>: {...} }`** — typed-at-the-facade provider-specific knobs (OpenAI `store`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
+4. **`http: { body, headers, query }`** — last-resort serializable overlays merged into the final HTTP request. Reach for this only when a stable typed path doesn't yet exist.
+
+Route/provider defaults are overridden by request-level values for each axis.
+
+## Routes
+
+Adding a new model or deployment is usually 5-15 lines using `Route.make({ protocol, endpoint, auth, framing, ... })`. The route owns endpoint/auth/framing and the protocol owns body construction plus stream parsing. Transports are reusable IO templates that receive route endpoint/auth at compile time. Capability/catalog metadata lives outside this low-level package; unsupported request shapes fail during protocol lowering. See `AGENTS.md` for the architectural detail.
+
+## Effect
+
+This package is built on Effect. Public methods return `Effect` or `Stream`; provide `LLMClient.layer` for LLM dispatch and `ImageClient.layer` for image dispatch, then import the provider/protocol modules for the routes you use. The example at `example/tutorial.ts` is a runnable walkthrough.
+
+## See also
+
+- `AGENTS.md` — architecture, route construction, contributor guide
+- `STATUS.md` — native provider parity status and AI SDK migration gaps
+- `example/tutorial.ts` — runnable end-to-end walkthrough
+- `test/provider/*.test.ts` — fixture-first protocol tests; `*.recorded.test.ts` files cover live cassettes

package/dist/cache-policy.d.ts

@@ -0,0 +1,2 @@
+import { LLMRequest } from "./schema/messages.js";
+export declare const applyCachePolicy: (request: LLMRequest) => LLMRequest;

package/dist/cache-policy.js

@@ -0,0 +1,121 @@
+// Apply an `LLMRequest.cache` policy by injecting `CacheHint`s onto the parts
+// the policy designates. Runs once at compile time, before the per-protocol
+// body builder, so the existing inline-hint lowering path handles the rest.
+//
+// The default `"auto"` shape places breakpoints at the last tool definition,
+// the first and last distinct system parts, and the conversation tail. This
+// exposes reusable tool, base-agent, project, and session prefixes while
+// advancing the tail after each tool result keeps the previous cache entry
+// within Anthropic's 20-block lookback during long agent turns.
+//
+// Manual `cache: CacheHint` placements on individual parts are preserved and
+// count against the four-breakpoint budget; auto only fills remaining slots.
+import { CacheHint } from "./schema/options.js";
+import { LLMRequest, Message, ToolDefinition } from "./schema/messages.js";
+const AUTO = {
+    tools: true,
+    system: true,
+    messages: { tail: 1 },
+};
+const NONE = {};
+const BREAKPOINT_CAP = 4;
+// Resolution rules:
+//   - undefined   → "auto" — caching is on by default. The math favors it:
+//                   Anthropic 5m-cache write is 1.25x base, read is 0.1x,
+//                   so a single reuse within 5 minutes already wins.
+//   - "auto"      → tools + first/last system + final message boundary.
+//   - "none"      → no auto placement; manual `CacheHint`s still flow.
+//   - object form → exactly what the caller asked for.
+const resolve = (policy) => {
+    if (policy === undefined || policy === "auto")
+        return AUTO;
+    if (policy === "none")
+        return NONE;
+    return policy;
+};
+// Protocols whose wire format ignores inline cache markers (OpenAI's implicit
+// prefix caching, Gemini's implicit + out-of-band CachedContent). Skip the
+// whole policy pass for these — emitting hints would be harmless but pointless.
+const RESPECTS_INLINE_HINTS = new Set(["anthropic-messages", "bedrock-converse", "openrouter"]);
+const makeHint = (ttlSeconds) => ttlSeconds !== undefined ? new CacheHint({ type: "ephemeral", ttlSeconds }) : new CacheHint({ type: "ephemeral" });
+const markLastTool = (tools, hint, budget) => {
+    if (tools.length === 0)
+        return tools;
+    const last = tools.length - 1;
+    if (tools[last].cache || budget.remaining === 0)
+        return tools;
+    budget.remaining -= 1;
+    return tools.map((tool, i) => (i === last ? new ToolDefinition({ ...tool, cache: hint }) : tool));
+};
+const markSystemBoundaries = (system, hint, budget) => {
+    if (system.length === 0)
+        return system;
+    let changed = false;
+    const next = system.map((part, index) => {
+        if ((index !== 0 && index !== system.length - 1) || part.cache || budget.remaining === 0)
+            return part;
+        budget.remaining -= 1;
+        changed = true;
+        return { ...part, cache: hint };
+    });
+    return changed ? next : system;
+};
+const lastIndexOfRole = (messages, role) => messages.findLastIndex((m) => m.role === role);
+// Mark the last text part of `messages[index]`. If no text part exists, mark
+// the last content part regardless of type — that's the breakpoint position
+// in tool-result-only messages too.
+const markMessageAt = (messages, index, hint, budget) => {
+    if (index < 0 || index >= messages.length)
+        return messages;
+    const target = messages[index];
+    if (target.content.length === 0)
+        return messages;
+    const lastTextIndex = target.content.findLastIndex((part) => part.type === "text");
+    const markAt = lastTextIndex >= 0 ? lastTextIndex : target.content.length - 1;
+    const existing = target.content[markAt];
+    if (("cache" in existing && existing.cache) || budget.remaining === 0)
+        return messages;
+    budget.remaining -= 1;
+    const nextContent = target.content.map((part, i) => (i === markAt ? { ...part, cache: hint } : part));
+    const next = new Message({ ...target, content: nextContent });
+    // Single pass over `messages`, substituting the one updated entry. Long
+    // conversations call this on every request, so avoid `.map()` here — its
+    // closure dispatch and identity copies show up in profiling.
+    const result = messages.slice();
+    result[index] = next;
+    return result;
+};
+const markMessages = (messages, strategy, hint, budget) => {
+    if (messages.length === 0)
+        return messages;
+    if (strategy === "latest-user-message")
+        return markMessageAt(messages, lastIndexOfRole(messages, "user"), hint, budget);
+    if (strategy === "latest-assistant")
+        return markMessageAt(messages, lastIndexOfRole(messages, "assistant"), hint, budget);
+    const start = Math.max(0, messages.length - strategy.tail);
+    let next = messages;
+    for (let i = start; i < messages.length; i++)
+        next = markMessageAt(next, i, hint, budget);
+    return next;
+};
+const countHints = (request) => request.tools.reduce((count, tool) => count + (tool.cache === undefined ? 0 : 1), 0) +
+    request.system.reduce((count, part) => count + (part.cache === undefined ? 0 : 1), 0) +
+    request.messages.reduce((count, message) => count +
+        message.content.reduce((contentCount, part) => contentCount + ("cache" in part && part.cache !== undefined ? 1 : 0), 0), 0);
+export const applyCachePolicy = (request) => {
+    if (!RESPECTS_INLINE_HINTS.has(request.model.route.id))
+        return request;
+    if (request.model.route.id === "openrouter" && (request.cache === undefined || request.cache === "auto"))
+        return request;
+    const policy = resolve(request.cache);
+    if (!policy.tools && !policy.system && !policy.messages)
+        return request;
+    const hint = makeHint(policy.ttlSeconds);
+    const budget = { remaining: Math.max(0, BREAKPOINT_CAP - countHints(request)) };
+    const tools = policy.tools ? markLastTool(request.tools, hint, budget) : request.tools;
+    const system = policy.system ? markSystemBoundaries(request.system, hint, budget) : request.system;
+    const messages = policy.messages ? markMessages(request.messages, policy.messages, hint, budget) : request.messages;
+    if (tools === request.tools && system === request.system && messages === request.messages)
+        return request;
+    return LLMRequest.update(request, { tools, system, messages });
+};

package/dist/image-client.d.ts

@@ -0,0 +1,19 @@
+import { Context, Effect, Layer } from "effect";
+import { RequestExecutor } from "./route/executor.js";
+import type { ImageOptions, ImageRequestFor, ImageResponse } from "./image.js";
+import type { AIError } from "./schema/index.js";
+export type Execute = RequestExecutor.Interface["execute"];
+export interface Interface {
+    readonly generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<ImageResponse, AIError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@opencode/ImageClient", Interface>;
+export declare class Service extends Service_base {
+}
+export declare const generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<ImageResponse, AIError, Service>;
+export declare const layer: Layer.Layer<Service, never, RequestExecutor.Service>;
+export declare const ImageClient: {
+    readonly Service: typeof Service;
+    readonly layer: Layer.Layer<Service, never, RequestExecutor.Service>;
+    readonly generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<ImageResponse, AIError, Service>;
+};
+export {};

package/dist/image-client.js

@@ -0,0 +1,19 @@
+import { Context, Effect, Layer } from "effect";
+import { RequestExecutor } from "./route/executor.js";
+export class Service extends Context.Service()("@opencode/ImageClient") {
+}
+export const generate = (request) => Effect.gen(function* () {
+    const client = yield* Service;
+    return yield* client.generate(request);
+});
+export const layer = Layer.effect(Service, Effect.gen(function* () {
+    const executor = yield* RequestExecutor.Service;
+    return Service.of({
+        generate: (request) => request.model.route.generate(request, executor.execute),
+    });
+}));
+export const ImageClient = {
+    Service,
+    layer,
+    generate,
+};

package/dist/image.d.ts

@@ -0,0 +1,110 @@
+import { Effect, Schema } from "effect";
+import { HttpOptions, AIError, ModelID, ProviderID, Usage } from "./schema/index.js";
+import { Service, type Execute as ImageExecute } from "./image-client.js";
+export interface ImageRoute<Options extends ImageOptions = ImageOptions> {
+    readonly id: string;
+    readonly generate: (request: ImageRequestFor<Options>, execute: ImageExecute) => Effect.Effect<ImageResponse, AIError>;
+}
+export type ImageOptions = Record<string, unknown>;
+export declare class ImageModel<Options extends ImageOptions = ImageOptions> {
+    protected readonly _Options: (options: Options) => Options;
+    readonly id: ModelID;
+    readonly provider: ProviderID;
+    readonly route: ImageRoute<Options>;
+    readonly http?: HttpOptions;
+    constructor(input: ImageModel.Input<Options>);
+    static make<Options extends ImageOptions = ImageOptions>(input: ImageModel.MakeInput<Options>): ImageModel<Options>;
+}
+export declare namespace ImageModel {
+    interface Input<Options extends ImageOptions = ImageOptions> {
+        readonly id: ModelID;
+        readonly provider: ProviderID;
+        readonly route: ImageRoute<Options>;
+        readonly http?: HttpOptions;
+    }
+    interface MakeInput<Options extends ImageOptions = ImageOptions> extends Omit<Input<Options>, "id" | "provider"> {
+        readonly id: string | ModelID;
+        readonly provider: string | ProviderID;
+    }
+}
+export declare const ImageModelSchema: Schema.declare<ImageModel<ImageOptions>, ImageModel<ImageOptions>>;
+export declare const ImageInputSchema: Schema.toTaggedUnion<"type", readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"bytes">;
+    readonly data: Schema.Uint8Array;
+    readonly mediaType: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"url">;
+    readonly url: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"file-id">;
+    readonly id: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"file-uri">;
+    readonly uri: Schema.String;
+    readonly mediaType: Schema.String;
+}>]>;
+export type ImageInput = Schema.Schema.Type<typeof ImageInputSchema>;
+export declare const ImageInput: {
+    readonly bytes: (data: Uint8Array, mediaType: string) => ImageInput;
+    readonly url: (url: string) => ImageInput;
+    readonly file: (id: string) => ImageInput;
+    readonly fileUri: (uri: string, mediaType: string) => ImageInput;
+};
+declare const ImageRequest_base: Schema.Class<ImageRequest, Schema.Struct<{
+    readonly model: Schema.declare<ImageModel<ImageOptions>, ImageModel<ImageOptions>>;
+    readonly prompt: Schema.String;
+    readonly images: Schema.optional<Schema.$Array<Schema.toTaggedUnion<"type", readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"bytes">;
+        readonly data: Schema.Uint8Array;
+        readonly mediaType: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"url">;
+        readonly url: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"file-id">;
+        readonly id: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"file-uri">;
+        readonly uri: Schema.String;
+        readonly mediaType: Schema.String;
+    }>]>>>;
+    readonly options: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+    readonly http: Schema.optional<typeof HttpOptions>;
+}>, {}>;
+export declare class ImageRequest extends ImageRequest_base {
+    protected readonly _ImageRequest: void;
+}
+export type ImageRequestFor<Options extends ImageOptions = ImageOptions> = Omit<ImageRequest, "model" | "options"> & {
+    readonly model: ImageModel<Options>;
+    readonly options?: Options;
+};
+export type ImageModelOptions<Model> = Model extends ImageModel<infer Options> ? Options : never;
+export type ImageRequestInput<Model extends object = ImageModel> = Omit<ConstructorParameters<typeof ImageRequest>[0], "model" | "options" | "http"> & {
+    readonly model: Model;
+    readonly options?: NoInfer<ImageModelOptions<Model>>;
+    readonly http?: HttpOptions.Input;
+} & (Model extends ImageModel<ImageModelOptions<Model>> ? unknown : never);
+declare const GeneratedImage_base: Schema.Class<GeneratedImage, Schema.Struct<{
+    readonly mediaType: Schema.String;
+    readonly data: Schema.Union<readonly [Schema.String, Schema.Uint8Array]>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+}>, {}>;
+export declare class GeneratedImage extends GeneratedImage_base {
+}
+declare const ImageResponse_base: Schema.Class<ImageResponse, Schema.Struct<{
+    readonly images: Schema.$Array<typeof GeneratedImage>;
+    readonly usage: Schema.optional<typeof Usage>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+}>, {}>;
+export declare class ImageResponse extends ImageResponse_base {
+    get image(): GeneratedImage;
+}
+export declare function request<const Model extends object>(input: ImageRequestInput<Model>): ImageRequestFor<ImageModelOptions<Model>>;
+export declare function request(input: ImageRequest): ImageRequest;
+export declare function generate<const Model extends object>(input: ImageRequestInput<Model>): Effect.Effect<ImageResponse, AIError, Service>;
+export declare function generate(input: ImageRequest): Effect.Effect<ImageResponse, AIError, Service>;
+export declare const Image: {
+    readonly request: typeof request;
+    readonly generate: typeof generate;
+};
+export {};