docs(ai): fix stale README and type-check examples (#59179)

Author: rekram1-node

packages/ai/README.md

@@ -1,6 +1,6 @@
 # @opencode/ai
 
-Schema-first APIs for text, images, video, speech, and transcription, built with Effect.
+Schema-first APIs for text, images, video, speech, transcription, and decisions, built with Effect.
 
 `@opencode/ai` is the Promise API: one managed runtime behind the LLM and media methods, plus asset helpers. `ai.file`
 and `ai.write` load `node:fs/promises` on first use, so no Effect `FileSystem` is needed:
@@ -62,13 +62,11 @@ live under `providerMetadata.vertex`. The default is still full-history replay w
 
 ```ts
 const model = Google.configure({ apiKey }).interactions("gemini-3.8-flash")
-const response =
-  yield *
-  LLM.generate({
-    model,
-    prompt: "Say hello.",
-    providerOptions: { thinkingLevel: "low", thinkingSummaries: "auto", store: true },
-  })
+const response = yield* LLM.generate({
+  model,
+  prompt: "Say hello.",
+  providerOptions: { thinkingLevel: "low", thinkingSummaries: "auto", store: true },
+})
 ```
 
 Interactions supports text output, streamed function calls, native tool results, thought signatures, and multimodal
@@ -93,7 +91,8 @@ const image = Effect.gen(function* () {
   const response = yield* Image.generate({
     model: openai.image("gpt-image-2"),
     prompt: "A robot tending a rooftop garden",
-    size: "1024x1024",
+    aspect: "1:1",
+    resolution: "1K",
     providerOptions: { quality: "high" }, // typed per image model
   })
   yield* Media.write(response.image, "./garden.png")
@@ -329,10 +328,11 @@ is unit-tested for all six regions.
 ### Images
 
 `alibaba.image(...)` uses the native multimodal generation API (`/api/v1/services/aigc/multimodal-generation/generation`)
-for Qwen-Image (`qwen-image-2.0`, `qwen-image-2.0-pro`) and Wan (`wan2.7-image`, `wan2.7-image-pro`). `size` lowers to
-`W*H`, and `images` are sent as URLs or data URLs for editing. Native `parameters` include `negativePrompt`,
-`promptExtend`, `watermark`, `thinkingMode`, and `enableSequential`; raw keys such as `bbox_list` or `size: "2K"`
-pass through. Results are URLs that Model Studio keeps for 24 hours. A complete `baseURL` for images includes `/api/v1`.
+for Qwen-Image (`qwen-image-2.0`, `qwen-image-2.0-pro`) and Wan (`wan2.7-image`, `wan2.7-image-pro`). `aspect` and
+`resolution` lower to a `W*H` size, `providerOptions.size` sets it exactly, and `images` are sent as URLs or data URLs
+for editing. Native `parameters` include `size`, `seed`, `negativePrompt`, `promptExtend`, `watermark`, `thinkingMode`,
+and `enableSequential`; raw keys such as `bbox_list` pass through. Results are URLs that Model Studio keeps for 24
+hours. A complete `baseURL` for images includes `/api/v1`.
 
 ## Z.AI
 
@@ -1102,8 +1102,10 @@ Everything below is exported from `@opencode/ai/effect` unless noted.
 - **`Video.request` / `generate` / `stream` / `start` / `resume`** — queued video generation through a provider-neutral request; `VideoClient` is its Effect service and layer.
 - **`Speech.request` / `Speech.generate` / `Speech.stream`** — text-to-speech through a provider-neutral request; `SpeechClient` is its Effect service and layer.
 - **`Transcription.request` / `generate` / `stream` / `start` / `resume`** — speech-to-text over inline, streaming, and queued routes; `TranscriptionClient` is its Effect service and layer.
+- **`Decision.request` / `Decision.generate`** — typed predicate, choice, and score questions over text, JSON, and media input; `DecisionClient` is its Effect service and layer.
 - **`AIClient.layer` / `AIClient.layerWith(executor)`** — every modality client plus the request executor in one layer.
-- **`@opencode/ai`** (Promise root) — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, and `transcription` as Promise / `AsyncIterable` APIs, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets.
+- **`@opencode/ai`** (Promise root) — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, `transcription`, and `decision` as Promise / `AsyncIterable` APIs, `run(effect)` for any package Effect, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets.
+- **`@opencode/ai/experimental`** — APIs that may still change: `Extraction` (typed values read out of text) and `Realtime` (`Realtime.connect` starts an OpenAI, xAI, or Gemini voice session and returns a WebRTC answer SDP or a short-lived WebSocket URL and token).
 
 ## Testing
 
@@ -1381,12 +1383,12 @@ import { OpenAI, CloudflareAIGateway } from "@opencode/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,
+  accountId,
   gatewayApiKey: process.env.CLOUDFLARE_API_TOKEN,
 }).model("workers-ai/@cf/meta/llama-3.1-8b-instruct")
 ```
 
-Included LLM providers: OpenAI, Anthropic, Google (Gemini), Google Vertex, Amazon Bedrock, Azure OpenAI, Baseten, Cerebras, Cohere, Cloudflare AI Gateway, Cloudflare Workers AI, DeepInfra, DeepSeek, Fireworks, Groq, Mistral, OpenRouter, TogetherAI, Vercel AI Gateway, and xAI. Z.ai currently exposes image generation. Generic Chat Completions, Responses, and Anthropic Messages-compatible entrypoints support custom endpoints.
+Included LLM providers: OpenAI, Anthropic, Google (Gemini), Google Vertex, Amazon Bedrock (Converse and Mantle), Azure OpenAI, Alibaba, Baseten, Cerebras, Cohere, Cloudflare AI Gateway, Cloudflare Workers AI, DeepInfra, DeepSeek, DigitalOcean, Fireworks, Groq, Meta, MiniMax, Mistral, Moonshot, OpenRouter, TogetherAI, Venice, Vercel AI Gateway, xAI, Z.ai, and Z.ai Coding Plan. TypeSafe AI and OpenCode expose decision models only. Generic Chat Completions, Responses, and Anthropic Messages-compatible entrypoints support custom endpoints.
 
 Each named provider owns its module, endpoint, authentication, and route setup. Providers with the same wire format compose the shared protocol directly:
 
@@ -1496,5 +1498,5 @@ This package is built on Effect. Public methods in `@opencode/ai/effect` return
 ## See also
 
 - `AGENTS.md` — architecture, route construction, contributor guide
-- `example/tutorial.ts` — runnable end-to-end walkthrough
+- `example/tutorial.ts` — runnable end-to-end walkthrough (`bun example/tutorial.ts <example>`)
 - `test/provider/*.test.ts` — fixture-first protocol tests; `*.recorded.test.ts` files cover live cassettes

packages/ai/example/tutorial.ts

@@ -1,15 +1,19 @@
 import { Config, Effect, Formatter, Schema, Stream } from "effect"
+import { HttpClientResponse } from "effect/http"
 import { NodeFileSystem } from "@effect/platform-node"
 import { AIClient, Image, LLM, LLMRequest, Media, Message, ProviderID, Tool, ToolRuntime } from "@opencode/ai/effect"
-import { Route, Auth, Endpoint, Framing, Protocol } from "@opencode/ai/route"
+import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor } from "@opencode/ai/route"
 import { OpenAI } from "@opencode/ai/providers"
 
 /**
  * A runnable walkthrough of the LLM package use-site API.
  *
  * Run from `packages/ai` with an OpenAI key in the environment:
  *
- *   OPENAI_API_KEY=... bun example/tutorial.ts
+ *   OPENAI_API_KEY=... bun example/tutorial.ts [example]
+ *
+ * where `example` is one of the keys of `examples` at the bottom (default
+ * `tools`). The `fake` example runs offline and needs no key.
  *
  * The file is intentionally written as a normal TypeScript program. You can
  * hover imports and local values to see how the public API is typed.
@@ -188,7 +192,7 @@ const FakeProtocol = Protocol.make<FakeBody, string, string, void>({
     event: Schema.String,
     initial: () => undefined,
     step: (_, frame) => Effect.succeed([undefined, [{ type: "text-delta", id: "text-0", text: frame }]] as const),
-    onHalt: () => [{ type: "finish", reason: { normalized: "stop" } }],
+    onHalt: () => Effect.succeed([{ type: "finish", reason: { normalized: "stop" } }]),
   },
 })
 
@@ -213,16 +217,34 @@ const FakeEcho = {
   }),
 }
 
+// 7. Run the fake provider offline. `RequestExecutor.middleware` sees every HTTP
+// request before it is sent; here it answers with two SSE frames instead of
+// calling the network.
+const fakeExecutor = RequestExecutor.middleware((request) =>
+  Effect.succeed(
+    HttpClientResponse.fromWeb(
+      request,
+      new Response("data: hello\n\ndata: from fake-echo\n\n", { headers: { "content-type": "text/event-stream" } }),
+    ),
+  ),
+)
+
+const generateFake = Effect.gen(function* () {
+  const response = yield* LLM.generate({ model: FakeEcho.configure().model("echo-1"), prompt: "Say hello." })
+  console.log("\n== fake provider ==")
+  console.log("generated text:", response.text)
+})
+
 // 8. Image generation uses the same facade and the same request/generate shape.
 // `response.image` is a `Media.Asset`: bytes decode lazily and are cached, and
 // `Media.write` persists them through the Effect `FileSystem`.
 const generateImage = Effect.gen(function* () {
   const response = yield* Image.generate({
     model: openai.image("gpt-image-1-mini"),
     prompt: "A flat black circle centered on a plain white background.",
-    size: "1024x1024",
-    format: "jpeg",
-    providerOptions: { quality: "low" },
+    aspect: "1:1",
+    // Exact pixel sizes and output formats are provider options.
+    providerOptions: { quality: "low", outputFormat: "jpeg" },
   })
 
   console.log("\n== image ==")
@@ -233,17 +255,25 @@ const generateImage = Effect.gen(function* () {
 })
 
 // Provide every modality client and the HTTP request executor once with
-// `AIClient.layer` (`AIClient.layerWith(executor)` swaps the executor). Keep one
-// path enabled at a time so the tutorial can demonstrate generate, stream, or
-// tool-loop behavior without spending tokens on every example.
-
-const program = Effect.gen(function* () {
-  // yield* generateOnce
-  // yield* streamText
-  // yield* generateStructuredObject
-  // yield* generateDynamicObject.pipe(Effect.andThen((response) => Effect.sync(() => console.log(response.object))))
-  // yield* generateImage
-  yield* streamWithTools
-}).pipe(Effect.provide(AIClient.layer))
-
-Effect.runPromise(program)
+// `AIClient.layer`; `AIClient.layerWith(executor)` swaps the executor, as the
+// fake example does. One example runs at a time so the tutorial does not spend
+// tokens on every path.
+const examples: Record<string, Effect.Effect<void, unknown, AIClient.Services>> = {
+  generate: generateOnce,
+  stream: streamText,
+  tools: streamWithTools,
+  object: generateStructuredObject,
+  "dynamic-object": generateDynamicObject.pipe(
+    Effect.andThen((response) => Effect.sync(() => console.log(response.object))),
+  ),
+  image: generateImage,
+  fake: generateFake,
+}
+
+const name = process.argv[2] ?? "tools"
+if (!Object.hasOwn(examples, name))
+  throw new Error(`Unknown example ${name}; pick one of ${Object.keys(examples).join(", ")}`)
+
+Effect.runPromise(
+  examples[name].pipe(Effect.provide(name === "fake" ? AIClient.layerWith(fakeExecutor) : AIClient.layer)),
+)

packages/ai/tsconfig.types.json

@@ -5,5 +5,5 @@
     "noEmit": true,
     "rootDir": "."
   },
-  "include": ["test/**/*.types.ts", "test/testing.test.ts", "test/provider/checkpoint.test.ts"]
+  "include": ["example/**/*.ts", "test/**/*.types.ts", "test/testing.test.ts", "test/provider/checkpoint.test.ts"]
 }