feat(ai): add OpenAI image generation (#37714)

Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com>

packages/ai/src/image-client.ts

@@ -0,0 +1,34 @@
+import { Context, Effect, Layer } from "effect"
+import { RequestExecutor } from "./route/executor"
+import type { ImageRequest, ImageResponse } from "./image"
+import type { LLMError } from "./schema"
+
+export type Execute = RequestExecutor.Interface["execute"]
+
+export interface Interface {
+  readonly generate: (request: ImageRequest) => Effect.Effect<ImageResponse, LLMError>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/ImageClient") {}
+
+export const generate = (request: ImageRequest): Effect.Effect<ImageResponse, LLMError> =>
+  Effect.gen(function* () {
+    const client = yield* Service
+    return yield* client.generate(request)
+  }) as Effect.Effect<ImageResponse, LLMError>
+
+export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = 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,
+} as const

packages/ai/src/image.ts

@@ -0,0 +1,116 @@
+import { Effect, Schema } from "effect"
+import { HttpOptions, InvalidRequestReason, LLMError, ModelID, ProviderID, ProviderMetadata, Usage } from "./schema"
+import { ImageClient, type Execute as ImageExecute } from "./image-client"
+
+export interface ImageRoute {
+  readonly id: string
+  readonly generate: (request: ImageRequest, execute: ImageExecute) => Effect.Effect<ImageResponse, LLMError>
+}
+
+export class ImageModel {
+  readonly id: ModelID
+  readonly provider: ProviderID
+  readonly route: ImageRoute
+  readonly defaults?: ImageModelDefaults
+
+  constructor(input: ImageModel.Input) {
+    this.id = input.id
+    this.provider = input.provider
+    this.route = input.route
+    this.defaults = input.defaults
+  }
+
+  static make(input: ImageModel.MakeInput) {
+    return new ImageModel({
+      id: ModelID.make(input.id),
+      provider: ProviderID.make(input.provider),
+      route: input.route,
+      defaults: input.defaults,
+    })
+  }
+}
+
+export namespace ImageModel {
+  export interface Input {
+    readonly id: ModelID
+    readonly provider: ProviderID
+    readonly route: ImageRoute
+    readonly defaults?: ImageModelDefaults
+  }
+
+  export interface MakeInput extends Omit<Input, "id" | "provider"> {
+    readonly id: string | ModelID
+    readonly provider: string | ProviderID
+  }
+}
+
+export interface ImageModelDefaults {
+  readonly providerOptions?: Record<string, Record<string, unknown>>
+  readonly http?: HttpOptions
+}
+
+export const ImageModelSchema = Schema.declare((value): value is ImageModel => value instanceof ImageModel, {
+  expected: "Image.Model",
+})
+
+export const ImageSize = Schema.Struct({
+  width: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  height: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+}).annotate({ identifier: "Image.Size" })
+export type ImageSize = Schema.Schema.Type<typeof ImageSize>
+
+export class ImageRequest extends Schema.Class<ImageRequest>("Image.Request")({
+  model: ImageModelSchema,
+  prompt: Schema.String,
+  count: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))),
+  size: Schema.optional(ImageSize),
+  aspectRatio: Schema.optional(Schema.String),
+  seed: Schema.optional(Schema.Number),
+  providerOptions: Schema.optional(Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Unknown))),
+  http: Schema.optional(HttpOptions),
+  metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+}) {}
+
+export type ImageRequestInput = Omit<ConstructorParameters<typeof ImageRequest>[0], "http"> & {
+  readonly http?: HttpOptions.Input
+}
+
+export class GeneratedImage extends Schema.Class<GeneratedImage>("Image.Generated")({
+  mediaType: Schema.String,
+  data: Schema.Union([Schema.String, Schema.Uint8Array]),
+  providerMetadata: Schema.optional(ProviderMetadata),
+}) {}
+
+export class ImageResponse extends Schema.Class<ImageResponse>("Image.Response")({
+  images: Schema.Array(GeneratedImage),
+  usage: Schema.optional(Usage),
+  providerMetadata: Schema.optional(ProviderMetadata),
+}) {
+  get image() {
+    return this.images[0]
+  }
+}
+
+export const request = (input: ImageRequest | ImageRequestInput) => {
+  if (input instanceof ImageRequest) return input
+  return new ImageRequest({
+    ...input,
+    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+  })
+}
+
+export const generate = (input: ImageRequest | ImageRequestInput) =>
+  Effect.try({
+    try: () => request(input),
+    catch: (error) =>
+      new LLMError({
+        module: "Image",
+        method: "generate",
+        reason: new InvalidRequestReason({ message: error instanceof Error ? error.message : String(error) }),
+      }),
+  }).pipe(Effect.flatMap(ImageClient.generate))
+
+export const Image = {
+  request,
+  generate,
+} as const

packages/ai/src/index.ts

@@ -1,4 +1,5 @@
 export { LLMClient } from "./route/client"
+export { ImageClient } from "./image-client"
 export { Auth } from "./route/auth"
 export { Provider } from "./provider"
 export { ProviderPackage } from "./provider-package"
@@ -10,6 +11,9 @@ export type {
   Service as LLMClientService,
 } from "./route/client"
 export * from "./schema"
+export { GeneratedImage, ImageModel, ImageRequest, ImageResponse, ImageSize } from "./image"
+export type { ImageModelDefaults, ImageRequestInput, ImageRoute } from "./image"
+export { Image } from "./image"
 export { Tool, ToolFailure, toDefinitions } from "./tool"
 export { ToolRuntime } from "./tool-runtime"
 export type { DispatchResult as ToolDispatchResult, ToolSettlement } from "./tool-runtime"

packages/ai/src/protocols/index.ts

@@ -2,6 +2,7 @@ export * as AnthropicMessages from "./anthropic-messages"
 export * as BedrockConverse from "./bedrock-converse"
 export * as Gemini from "./gemini"
 export * as OpenAIChat from "./openai-chat"
+export * as OpenAIImages from "./openai-images"
 export * as OpenAICompatibleChat from "./openai-compatible-chat"
 export * as OpenAICompatibleResponses from "./openai-compatible-responses"
 export * as OpenAIResponses from "./openai-responses"

packages/ai/src/protocols/openai-images.ts

@@ -0,0 +1,208 @@
+import { Effect, Encoding, Schema } from "effect"
+import { Headers, HttpClientRequest } from "effect/unstable/http"
+import {
+  ImageModel,
+  GeneratedImage,
+  ImageResponse,
+  type ImageRequest,
+  type ImageModelDefaults,
+  type ImageRoute,
+} from "../image"
+import { Auth, type Definition as AuthDefinition } from "../route/auth"
+import { InvalidProviderOutputReason, LLMError, Usage, mergeHttpOptions, mergeJsonRecords } from "../schema"
+import { ProviderShared } from "./shared"
+import { OpenAIImage } from "./utils/openai-image"
+
+const ADAPTER = "openai-images"
+export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
+export const PATH = "/images/generations"
+
+export interface OpenAIImageOptions {
+  readonly quality?: "auto" | "low" | "medium" | "high"
+  readonly background?: "auto" | "opaque" | "transparent"
+  readonly moderation?: "auto" | "low"
+  readonly outputFormat?: "png" | "jpeg" | "webp"
+  readonly outputCompression?: number
+}
+
+const OpenAIImageBody = Schema.Struct({
+  model: Schema.String,
+  prompt: Schema.String,
+  n: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))),
+  size: Schema.optional(Schema.String),
+  quality: Schema.optional(Schema.Literals(["auto", "low", "medium", "high"])),
+  background: Schema.optional(Schema.Literals(["auto", "opaque", "transparent"])),
+  moderation: Schema.optional(Schema.Literals(["auto", "low"])),
+  output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
+  output_compression: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 100 }))),
+})
+export type OpenAIImageBody = Schema.Schema.Type<typeof OpenAIImageBody>
+
+const OpenAIImageResponse = Schema.Struct({
+  data: Schema.Array(
+    Schema.Struct({
+      b64_json: Schema.optional(Schema.String),
+      url: Schema.optional(Schema.String),
+      revised_prompt: Schema.optional(Schema.String),
+    }),
+  ),
+  output_format: Schema.optional(Schema.String),
+  usage: Schema.optional(
+    Schema.Struct({
+      input_tokens: Schema.optional(Schema.Number),
+      output_tokens: Schema.optional(Schema.Number),
+      total_tokens: Schema.optional(Schema.Number),
+      input_tokens_details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+      output_tokens_details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+    }),
+  ),
+})
+
+export interface ModelInput {
+  readonly id: string
+  readonly auth: AuthDefinition
+  readonly baseURL?: string
+  readonly headers?: Record<string, string>
+  readonly defaults?: ImageModelDefaults
+}
+
+const providerOptions = (request: ImageRequest): OpenAIImageOptions => ({
+  ...request.model.defaults?.providerOptions?.openai,
+  ...request.providerOptions?.openai,
+})
+
+const body = (request: ImageRequest): OpenAIImageBody => {
+  const options = providerOptions(request)
+  return {
+    model: request.model.id,
+    prompt: request.prompt,
+    n: request.count,
+    size: request.size === undefined ? undefined : `${request.size.width}x${request.size.height}`,
+    quality: options.quality,
+    background: options.background,
+    moderation: options.moderation,
+    output_format: options.outputFormat,
+    output_compression: options.outputCompression,
+  }
+}
+
+const invalidOutput = (message: string) =>
+  new LLMError({
+    module: ADAPTER,
+    method: "generate",
+    reason: new InvalidProviderOutputReason({ message, route: ADAPTER }),
+  })
+
+const applyQuery = (url: string, query: Record<string, string> | undefined) => {
+  if (!query) return url
+  const next = new URL(url)
+  Object.entries(query).forEach(([key, value]) => next.searchParams.set(key, value))
+  return next.toString()
+}
+
+const PROTOCOL_BODY_FIELDS = new Set([
+  "model",
+  "prompt",
+  "n",
+  "size",
+  "quality",
+  "background",
+  "moderation",
+  "output_format",
+  "output_compression",
+])
+
+const bodyWithOverlay = Effect.fn("OpenAIImages.bodyWithOverlay")(function* (
+  imageBody: OpenAIImageBody,
+  overlay: Record<string, unknown> | undefined,
+) {
+  if (!overlay) return imageBody
+  const reserved = Object.keys(overlay).filter((key) => PROTOCOL_BODY_FIELDS.has(key))
+  if (reserved.length > 0)
+    return yield* ProviderShared.invalidRequest(
+      `http.body cannot overlay protocol-owned field(s): ${reserved.join(", ")}`,
+    )
+  return mergeJsonRecords(imageBody, overlay) ?? imageBody
+})
+
+export const model = (input: ModelInput) => {
+  const route: ImageRoute = {
+    id: ADAPTER,
+    generate: Effect.fn("OpenAIImages.generate")(function* (request: ImageRequest, execute) {
+      if (request.aspectRatio !== undefined)
+        return yield* ProviderShared.invalidRequest("OpenAI Images does not support the common aspectRatio option")
+      if (request.seed !== undefined)
+        return yield* ProviderShared.invalidRequest("OpenAI Images does not support the common seed option")
+
+      const requestBody = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenAIImageBody))(body(request))
+      const http = mergeHttpOptions(request.model.defaults?.http, request.http)
+      const overlaidBody = yield* bodyWithOverlay(requestBody, http?.body)
+      const text = ProviderShared.encodeJson(overlaidBody)
+      const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${PATH}`, http?.query)
+      const headers = yield* Auth.toEffect(input.auth)({
+        request,
+        method: "POST",
+        url,
+        body: text,
+        headers: Headers.fromInput({ ...input.headers, ...http?.headers }),
+      })
+      const response = yield* execute(
+        HttpClientRequest.post(url).pipe(
+          HttpClientRequest.setHeaders(headers),
+          HttpClientRequest.bodyText(text, "application/json"),
+        ),
+      )
+      const payload = yield* response.json.pipe(
+        Effect.mapError(() => invalidOutput("Failed to read the OpenAI Images response")),
+      )
+      const decoded = yield* Schema.decodeUnknownEffect(OpenAIImageResponse)(payload).pipe(
+        Effect.mapError(() => invalidOutput("OpenAI Images returned an invalid response")),
+      )
+      const format = decoded.output_format ?? providerOptions(request).outputFormat ?? "png"
+      const images = yield* Effect.forEach(decoded.data, (item, index) => {
+        if (item.b64_json)
+          return Effect.fromResult(Encoding.decodeBase64(item.b64_json)).pipe(
+            Effect.mapError(() => invalidOutput(`OpenAI Images result ${index} contains invalid base64 data`)),
+            Effect.map(
+              (data) =>
+                new GeneratedImage({
+                  mediaType: `image/${format}`,
+                  data,
+                  providerMetadata:
+                    item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
+                }),
+            ),
+          )
+        if (item.url)
+          return Effect.succeed(
+            new GeneratedImage({
+              mediaType: `image/${format}`,
+              data: item.url,
+              providerMetadata:
+                item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
+            }),
+          )
+        return Effect.fail(invalidOutput(`OpenAI Images result ${index} has neither image data nor a URL`))
+      })
+      if (images.length === 0) return yield* invalidOutput("OpenAI Images returned no images")
+      return new ImageResponse({
+        images,
+        usage:
+          decoded.usage === undefined
+            ? undefined
+            : new Usage({
+                inputTokens: decoded.usage.input_tokens,
+                outputTokens: decoded.usage.output_tokens,
+                totalTokens: decoded.usage.total_tokens,
+                providerMetadata: { openai: decoded.usage },
+              }),
+        providerMetadata: { openai: { outputFormat: format } },
+      })
+    }),
+  }
+  return ImageModel.make({ id: input.id, provider: "openai", route, defaults: input.defaults })
+}
+
+export const OpenAIImages = {
+  model,
+} as const

packages/ai/src/protocols/openai-responses.ts

@@ -1,4 +1,4 @@
-import { Effect, Schema } from "effect"
+import { Effect, Encoding, Schema } from "effect"
 import { Route } from "../route/client"
 import { Auth } from "../route/auth"
 import { Endpoint } from "../route/endpoint"
@@ -25,6 +25,7 @@ import { OpenAIOptions } from "./utils/openai-options"
 import { Lifecycle } from "./utils/lifecycle"
 import { ToolSchemaProjection } from "./utils/tool-schema"
 import { ToolStream } from "./utils/tool-stream"
+import { OpenAIImage } from "./utils/openai-image"
 
 const ADAPTER = "openai-responses"
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
@@ -113,11 +114,24 @@ const OpenAIResponsesTool = Schema.Struct({
   parameters: JsonObject,
   strict: Schema.optional(Schema.Boolean),
 })
-type OpenAIResponsesTool = Schema.Schema.Type<typeof OpenAIResponsesTool>
+const OpenAIResponsesImageGenerationTool = Schema.Struct({
+  type: Schema.tag("image_generation"),
+  action: Schema.optional(Schema.Literals(["auto", "generate", "edit"])),
+  background: Schema.optional(Schema.Literals(["auto", "opaque", "transparent"])),
+  input_fidelity: Schema.optional(Schema.Literals(["low", "high"])),
+  output_compression: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 100 }))),
+  output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
+  partial_images: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+  quality: Schema.optional(Schema.Literals(["auto", "low", "medium", "high"])),
+  size: Schema.optional(OpenAIImage.Size),
+})
+const OpenAIResponsesTools = Schema.Union([OpenAIResponsesTool, OpenAIResponsesImageGenerationTool])
+type OpenAIResponsesTool = Schema.Schema.Type<typeof OpenAIResponsesTools>
 
 const OpenAIResponsesToolChoice = Schema.Union([
   Schema.Literals(["auto", "none", "required"]),
   Schema.Struct({ type: Schema.tag("function"), name: Schema.String }),
+  Schema.Struct({ type: Schema.tag("image_generation") }),
 ])
 
 // Fields shared between the HTTP body and the WebSocket `response.create`
@@ -128,7 +142,7 @@ const OpenAIResponsesCoreFields = {
   model: Schema.String,
   input: Schema.Array(OpenAIResponsesInputItem),
   instructions: Schema.optional(Schema.String),
-  tools: optionalArray(OpenAIResponsesTool),
+  tools: optionalArray(OpenAIResponsesTools),
   tool_choice: Schema.optional(OpenAIResponsesToolChoice),
   store: Schema.optional(Schema.Boolean),
   service_tier: Schema.optional(OpenAIOptions.OpenAIServiceTier),
@@ -194,6 +208,8 @@ const OpenAIResponsesStreamItem = Schema.Struct({
   outputs: Schema.optional(Schema.Unknown),
   server_label: Schema.optional(Schema.String),
   output: Schema.optional(Schema.Unknown),
+  result: Schema.optional(Schema.String),
+  output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
   error: Schema.optional(Schema.Unknown),
   encrypted_content: optionalNull(Schema.String),
 })
@@ -258,21 +274,41 @@ const invalid = ProviderShared.invalidRequest
 // =============================================================================
 // Request Lowering
 // =============================================================================
-const lowerTool = (tool: ToolDefinition, inputSchema: JsonSchema): OpenAIResponsesTool => ({
-  type: "function",
-  name: tool.name,
-  description: tool.description,
-  parameters: ToolSchemaProjection.openAI(inputSchema),
-  // TODO: Read this from OpenAI-specific tool options so direct LLM callers can opt into strict schemas.
-  strict: false,
+const nativeImageToolInput = (tool: ToolDefinition) => {
+  const native = tool.native?.openai
+  return ProviderShared.isRecord(native) && native.type === "image_generation" ? native : undefined
+}
+
+const nativeImageTool = (tool: ToolDefinition) => {
+  const native = nativeImageToolInput(tool)
+  return Schema.is(OpenAIResponsesImageGenerationTool)(native) ? native : undefined
+}
+
+const lowerTool = Effect.fn("OpenAIResponses.lowerTool")(function* (tool: ToolDefinition, inputSchema: JsonSchema) {
+  const native = nativeImageToolInput(tool)
+  if (native !== undefined) {
+    if (Schema.is(OpenAIResponsesImageGenerationTool)(native)) return native
+    return yield* invalid("OpenAI Responses image generation tool options are invalid")
+  }
+  return {
+    type: "function" as const,
+    name: tool.name,
+    description: tool.description,
+    parameters: ToolSchemaProjection.openAI(inputSchema),
+    // TODO: Read this from OpenAI-specific tool options so direct LLM callers can opt into strict schemas.
+    strict: false,
+  }
 })
 
-const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
+const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tools: ReadonlyArray<ToolDefinition>) =>
   ProviderShared.matchToolChoice("OpenAI Responses", toolChoice, {
     auto: () => "auto" as const,
     none: () => "none" as const,
     required: () => "required" as const,
-    tool: (name) => ({ type: "function" as const, name }),
+    tool: (name) =>
+      tools.some((tool) => tool.name === name && nativeImageTool(tool) !== undefined)
+        ? ({ type: "image_generation" } as const)
+        : { type: "function" as const, name },
   })
 
 const lowerToolCall = (part: ToolCallPart): OpenAIResponsesInputItem => ({
@@ -420,6 +456,13 @@ const lowerMessages = Effect.fn("OpenAIResponses.lowerMessages")(function* (requ
           const itemID = hostedToolItemID(part)
           if (store !== false && itemID && !hostedToolReferences.has(itemID))
             input.push({ type: "item_reference", id: itemID })
+          if (store === false && part.name === "image_generation" && part.result.type === "content") {
+            const content: ReadonlyArray<ToolContent> = part.result.value
+            input.push({
+              role: "user",
+              content: yield* Effect.forEach(content, lowerToolResultContentItem),
+            })
+          }
           if (itemID) hostedToolReferences.add(itemID)
           continue
         }
@@ -485,10 +528,10 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
     tools:
       request.tools.length === 0
         ? undefined
-        : request.tools.map((tool) =>
+        : yield* Effect.forEach(request.tools, (tool) =>
             lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
           ),
-    tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined,
+    tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined,
     stream: true as const,
     max_output_tokens: generation?.maxTokens,
     temperature: generation?.temperature,
@@ -574,14 +617,29 @@ const isReasoningItem = (
 
 // Round-trip the full item as the structured result so consumers can extract
 // outputs / sources / status without re-decoding.
-const hostedToolResult = (item: OpenAIResponsesStreamItem) => {
+const hostedToolResult = Effect.fn("OpenAIResponses.hostedToolResult")(function* (item: OpenAIResponsesStreamItem) {
   const isError = typeof item.error !== "undefined" && item.error !== null
+  if (item.type === "image_generation_call" && item.result) {
+    yield* Effect.fromResult(Encoding.decodeBase64(item.result)).pipe(
+      Effect.mapError(() => ProviderShared.eventError(ADAPTER, "OpenAI Responses returned invalid image base64")),
+    )
+    return {
+      type: "content" as const,
+      value: [
+        {
+          type: "file" as const,
+          uri: `data:image/${item.output_format ?? "png"};base64,${item.result}`,
+          mime: `image/${item.output_format ?? "png"}`,
+        },
+      ],
+    }
+  }
   return isError ? { type: "error" as const, value: item.error } : { type: "json" as const, value: item }
-}
+})
 
-const hostedToolEvents = (
+const hostedToolEvents = Effect.fn("OpenAIResponses.hostedToolEvents")(function* (
   item: OpenAIResponsesStreamItem & { type: HostedToolType; id: string },
-): ReadonlyArray<LLMEvent> => {
+) {
   const tool = HOSTED_TOOLS[item.type]
   const providerMetadata = openaiMetadata({ itemId: item.id })
   return [
@@ -595,12 +653,12 @@ const hostedToolEvents = (
     LLMEvent.toolResult({
       id: item.id,
       name: tool.name,
-      result: hostedToolResult(item),
+      result: yield* hostedToolResult(item),
       providerExecuted: true,
       providerMetadata,
     }),
   ]
-}
+})
 
 type StepResult = readonly [ParserState, ReadonlyArray<LLMEvent>]
 
@@ -847,7 +905,7 @@ const onOutputItemDone = Effect.fn("OpenAIResponses.onOutputItemDone")(function*
   if (isHostedToolItem(item)) {
     const events: LLMEvent[] = []
     const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
-    events.push(...hostedToolEvents(item))
+    events.push(...(yield* hostedToolEvents(item)))
     return [{ ...state, lifecycle }, events] satisfies StepResult
   }
 

packages/ai/src/protocols/utils/openai-image.ts

@@ -0,0 +1,20 @@
+import { Schema } from "effect"
+
+const dimensions = (value: string) => {
+  const match = /^(\d+)x(\d+)$/.exec(value)
+  if (!match) return undefined
+  return { width: Number(match[1]), height: Number(match[2]) }
+}
+
+export const Size = Schema.String.check(
+  Schema.makeFilter((value) => {
+    if (value === "auto") return undefined
+    const parsed = dimensions(value)
+    if (!parsed) return "image size must be `auto` or `{width}x{height}`"
+    return parsed.width > 0 && parsed.height > 0 ? undefined : "image dimensions must be positive integers"
+  }),
+)
+
+export const OpenAIImage = {
+  Size,
+} as const

packages/ai/src/providers/openai.ts

@@ -1,12 +1,14 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import type { Route, RouteDefaultsInput } from "../route/client"
 import type { ProviderPackage } from "../provider-package"
-import { ProviderID, type ModelID } from "../schema"
+import { HttpOptions, ProviderID, ToolDefinition, mergeHttpOptions, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options"
+import { OpenAIImages, type OpenAIImageOptions } from "../protocols/openai-images"
 
 export type { OpenAIOptionsInput, OpenAIResponseIncludable } from "./openai-options"
+export type { OpenAIImageOptions } from "../protocols/openai-images"
 
 export const id = ProviderID.make("openai")
 
@@ -20,8 +22,44 @@ export type Config = RouteDefaultsInput &
     readonly baseURL?: string
     readonly queryParams?: Record<string, string>
     readonly providerOptions?: OpenAIProviderOptionsInput
+    readonly image?: ImageConfig
   }
 
+export interface ImageConfig {
+  readonly providerOptions?: OpenAIImageOptions
+}
+
+export interface ImageGenerationOptions {
+  readonly action?: "auto" | "generate" | "edit"
+  readonly background?: "auto" | "opaque" | "transparent"
+  readonly inputFidelity?: "low" | "high"
+  readonly outputCompression?: number
+  readonly outputFormat?: "png" | "jpeg" | "webp"
+  readonly partialImages?: number
+  readonly quality?: "auto" | "low" | "medium" | "high"
+  readonly size?: string
+}
+
+export const imageGeneration = (options: ImageGenerationOptions = {}) =>
+  ToolDefinition.make({
+    name: "image_generation",
+    description: "Generate or edit an image using OpenAI's hosted image generation tool.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    native: {
+      openai: {
+        type: "image_generation",
+        action: options.action,
+        background: options.background,
+        input_fidelity: options.inputFidelity,
+        output_compression: options.outputCompression,
+        output_format: options.outputFormat,
+        partial_images: options.partialImages,
+        quality: options.quality,
+        size: options.size,
+      },
+    },
+  })
+
 export interface Settings extends ProviderPackage.Settings {
   readonly apiKey?: string
   readonly baseURL?: string
@@ -35,7 +73,7 @@ export interface Settings extends ProviderPackage.Settings {
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "OPENAI_API_KEY")
 
 const defaults = (input: Config) => {
-  const { apiKey: _, auth: _auth, baseURL: _baseURL, queryParams: _queryParams, ...rest } = input
+  const { apiKey: _, auth: _auth, baseURL: _baseURL, queryParams: _queryParams, image: _image, ...rest } = input
   return rest
 }
 
@@ -55,6 +93,21 @@ export const configure = (input: Config = {}) => {
   const responsesWebSocket = (id: string | ModelID) =>
     responsesWebSocketRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
   const chat = (id: string | ModelID) => chatRoute.with(withOpenAIOptions(id, modelDefaults)).model({ id })
+  const image = (modelID: string | ModelID) =>
+    OpenAIImages.model({
+      id: modelID,
+      auth: auth(input),
+      baseURL: input.baseURL,
+      headers: input.headers,
+      defaults: {
+        providerOptions:
+          input.image?.providerOptions === undefined ? undefined : { openai: { ...input.image.providerOptions } },
+        http: mergeHttpOptions(
+          input.http === undefined ? undefined : HttpOptions.make(input.http),
+          input.queryParams === undefined ? undefined : new HttpOptions({ query: input.queryParams }),
+        ),
+      },
+    })
 
   return {
     id,
@@ -62,6 +115,7 @@ export const configure = (input: Config = {}) => {
     responses,
     responsesWebSocket,
     chat,
+    image,
     configure,
   }
 }
@@ -97,3 +151,4 @@ export const chatModel: ProviderPackage.Definition<Settings>["model"] = (modelID
 export const responses = provider.responses
 export const responsesWebSocket = provider.responsesWebSocket
 export const chat = provider.chat
+export const image = provider.image

packages/ai/src/route/auth.ts

@@ -1,6 +1,6 @@
 import { Config, Effect, Redacted } from "effect"
 import { Headers } from "effect/unstable/http"
-import { AuthenticationReason, InvalidRequestReason, LLMError, type LLMRequest } from "../schema"
+import { AuthenticationReason, InvalidRequestReason, LLMError, type HttpOptions } from "../schema"
 
 export class MissingCredentialError extends Error {
   readonly _tag = "MissingCredentialError"
@@ -15,7 +15,7 @@ export type AuthError = CredentialError | LLMError
 type Secret = string | Redacted.Redacted | Config.Config<string | Redacted.Redacted>
 
 export interface AuthInput {
-  readonly request: LLMRequest
+  readonly request: { readonly http?: HttpOptions }
   readonly method: "POST" | "GET"
   readonly url: string
   readonly body: string