fix(tui): preserve POSIX folder names

Co-authored-by: Aiden Cline <63023139+rekram1-node@users.noreply.github.com>
Co-authored-by: opencode-agent[bot] <219766164+opencode-agent[bot]@users.noreply.github.com>

.github/workflows/deploy-www.yml

@@ -27,7 +27,6 @@ jobs:
         working-directory: packages/www
         run: bun run build
         env:
-          BLUME_ENV: ${{ github.ref_name == 'v2' && 'production' || 'dev' }}
           CLOUDFLARE_ENV: ${{ github.ref_name == 'v2' && 'production' || 'dev' }}
 
       - name: Deploy

.github/workflows/publish.yml

@@ -91,7 +91,7 @@ jobs:
 
       - uses: ./.github/actions/setup-bun
         with:
-          bun-version: canary # Bun 1.4 until its stable release is published
+          bun-version: 1.4.0
 
       - name: Setup git committer
         id: committer
@@ -113,7 +113,7 @@ jobs:
         id: build
         run: ./packages/cli/script/build.ts ${{ (github.ref_name == 'beta' && '--sourcemaps') || '' }}
         env:
-          BUN_COMPILE_RELEASE: canary
+          BUN_COMPILE_RELEASE: bun-v1.4.0
           OPENCODE_VERSION: ${{ needs.version.outputs.version }}
           OPENCODE_RELEASE: ${{ needs.version.outputs.release }}
           GH_REPO: ${{ needs.version.outputs.repo }}

nix/hashes.json

@@ -1,8 +1,8 @@
 {
   "nodeModules": {
-    "x86_64-linux": "sha256-V1G3RuuwtlVx166oDVCqQ9v7ELWRr5JDYitcCMitbNA=",
-    "aarch64-linux": "sha256-nm/N60X7kdkNIa2oCgqyNp9ewrBrWvr6ES0qhxzypQc=",
-    "aarch64-darwin": "sha256-7UQtp4KrtxuT6MMrz7YYcJcF9/b5ECobkSwzI+yLe0Q=",
-    "x86_64-darwin": "sha256-jrn0GOa7qDskowio97bvhl7rsideXqHVbygSi3M1cf0="
+    "x86_64-linux": "sha256-tvhHO7NdDnBWtyaOj+kVX0Tzcv3O0uISbHC4V71kA0M=",
+    "aarch64-linux": "sha256-x3F43TL7BisEuXlJw7QS/DJoSzZWuNxbgn7hFCsTdXU=",
+    "aarch64-darwin": "sha256-y2r5Qy/XNgnvuzpnGMtwV5ZmhksUN2AUPLjbb40HYIE=",
+    "x86_64-darwin": "sha256-TS68JE40IaEa7ny0ATPUnEj8EV1CKtnGTPpyvZFwO7A="
   }
 }

packages/ai/src/protocols/index.ts

@@ -8,3 +8,4 @@ export * as OpenAICompatibleResponses from "./openai-compatible-responses.js"
 export * as OpenAIResponses from "./openai-responses.js"
 export * as OpenResponses from "./open-responses.js"
 export * as OpenResponsesChannel from "./open-responses-channel.js"
+export * as XAIResponses from "./xai-responses.js"

packages/ai/src/protocols/open-responses-channel.ts

@@ -10,6 +10,7 @@ import {
 } from "../route/transport/index.js"
 import * as ProviderShared from "./shared.js"
 import { OpenResponses } from "./open-responses.js"
+import { OpenResponsesContinuation } from "./open-responses-continuation.js"
 
 const WebSocketResponseCreate = Schema.StructWithRest(Schema.Struct({ type: Schema.tag("response.create") }), [
   Schema.Record(Schema.String, Schema.Unknown),
@@ -25,11 +26,6 @@ export interface Options {
   readonly enabled?: (url: string) => boolean
   readonly url?: (url: string) => string
   readonly headers?: (headers: Headers.Headers) => Headers.Headers
-  readonly driver?: (input: {
-    readonly request: Readonly<Record<string, unknown>>
-    readonly message: string
-    readonly base: WebSocketChannelDriver
-  }) => WebSocketChannelDriver
 }
 
 export interface Prepared {
@@ -158,7 +154,13 @@ export const transport = <Body>(options: Options): Transport<Body, Prepared, str
                   url: yield* WebSocketTransport.toWebSocketUrl(options.url?.(parts.url) ?? parts.url),
                   headers,
                   rotateAfterMs: options.rotateAfterMs,
-                  driver: options.driver?.({ request: create.request, message: create.message, base }) ?? base,
+                  driver: OpenResponsesContinuation.driver({
+                    id: options.id,
+                    name: options.name,
+                    request: create.request,
+                    message: create.message,
+                    base,
+                  }),
                 }
               })
             : undefined

packages/ai/src/protocols/open-responses-continuation.ts

@@ -4,7 +4,7 @@ import { Effect, Option, Schema } from "effect"
 import * as ProviderShared from "./shared.js"
 import { OpenResponses } from "./open-responses.js"
 
-const PROTOCOL = "openai-responses.websocket.v1"
+const PROTOCOL = "open-responses.websocket.v1"
 const VERSION = 1
 const decodeEvent = Schema.decodeUnknownEffect(OpenResponses.protocol.stream.event)
 
@@ -161,4 +161,4 @@ export const driver = (input: DriverInput): WebSocketChannelDriver => {
   }
 }
 
-export const OpenAIResponsesChannel = { driver } as const
+export const OpenResponsesContinuation = { driver } as const

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

@@ -42,8 +42,12 @@ const OpenResponsesInputImage = Schema.Struct({
 const OpenResponsesInputFile = Schema.Struct({
   type: Schema.tag("input_file"),
   filename: Schema.String,
-  file_data: Schema.String,
-  mime_type: Schema.optional(Schema.String),
+  file_data: Schema.optional(Schema.String),
+  file_url: Schema.optional(Schema.String),
+})
+const OpenResponsesInputVideo = Schema.Struct({
+  type: Schema.tag("input_video"),
+  video_url: Schema.String,
 })
 const MediaInput = Schema.Union([OpenResponsesInputImage, OpenResponsesInputFile])
 export type MediaInput = Schema.Schema.Type<typeof MediaInput>
@@ -54,7 +58,7 @@ const OpenResponsesOutputText = Schema.Struct({
   text: Schema.String,
 })
 
-export const MessagePhase = Schema.Literals(["commentary", "final_answer"])
+export const MessagePhase = Schema.NullOr(Schema.Literals(["commentary", "final_answer"]))
 type MessagePhase = Schema.Schema.Type<typeof MessagePhase>
 
 const OpenResponsesReasoningSummaryText = Schema.Struct({
@@ -81,6 +85,7 @@ const OpenResponsesFunctionCallOutputContent = Schema.Union([
   OpenResponsesInputText,
   OpenResponsesInputImage,
   OpenResponsesInputFile,
+  OpenResponsesInputVideo,
 ])
 
 const OpenResponsesFunctionCallOutput = Schema.Union([
@@ -323,7 +328,6 @@ export interface Extension {
     readonly media: ProviderShared.NormalizedMedia
     readonly request: LLMRequest
   }) => MediaInput | undefined
-  readonly messagePhase?: (value: unknown) => MessagePhase | null | undefined
 }
 
 const BASE: Extension = { id: ADAPTER, name: NAME }
@@ -422,18 +426,25 @@ const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
   part: MediaPart,
   request: LLMRequest,
   extension: Extension,
+  target: "message" | "tool-result",
 ) {
   const media = ProviderShared.normalizeMedia(part)
   const extended = extension.lowerMedia?.({ part, media, request })
   if (extended) return extended
+  const url =
+    typeof part.data === "string" && (part.data.startsWith("https://") || part.data.startsWith("http://"))
+      ? part.data
+      : undefined
   if (!media.mime.startsWith("image/")) {
+    if (target === "tool-result" && media.mime.startsWith("video/"))
+      return { type: "input_video" as const, video_url: url ?? media.dataUrl }
     return {
       type: "input_file" as const,
       filename: part.filename ?? (media.mime === "application/pdf" ? "document.pdf" : "file"),
-      file_data: media.dataUrl,
+      ...(url ? { file_url: url } : { file_data: media.base64 }),
     }
   }
-  return { type: "input_image" as const, image_url: media.dataUrl }
+  return { type: "input_image" as const, image_url: url ?? media.dataUrl }
 })
 
 const lowerUserContent = Effect.fnUntraced(function* (
@@ -442,10 +453,17 @@ const lowerUserContent = Effect.fnUntraced(function* (
   extension: Extension,
 ) {
   if (part.type === "text") return { type: "input_text" as const, text: part.text }
-  if (part.type === "media") return yield* lowerMedia(part, request, extension)
+  if (part.type === "media") return yield* lowerMessageMedia(part, request, extension)
   return yield* ProviderShared.unsupportedContent(extension.name, "user", ["text", "media"])
 })
 
+const lowerMessageMedia = Effect.fnUntraced(function* (part: MediaPart, request: LLMRequest, extension: Extension) {
+  const lowered = yield* lowerMedia(part, request, extension, "message")
+  if (lowered.type === "input_video")
+    return yield* ProviderShared.invalidRequest(`${extension.name} user messages do not support input_video`)
+  return lowered
+})
+
 // Tool results may carry structured text, images, and files. Keep media as provider-native
 // content instead of JSON-stringifying base64 into a prompt string.
 const lowerToolResultContentItem = Effect.fnUntraced(function* (
@@ -458,6 +476,20 @@ const lowerToolResultContentItem = Effect.fnUntraced(function* (
     { type: "media", mediaType: item.mime, data: item.uri, filename: item.name },
     request,
     extension,
+    "tool-result",
+  )
+})
+
+const lowerHostedToolResultContentItem = Effect.fnUntraced(function* (
+  item: Content,
+  request: LLMRequest,
+  extension: Extension,
+) {
+  if (item.type === "text") return { type: "input_text" as const, text: item.text }
+  return yield* lowerMessageMedia(
+    { type: "media", mediaType: item.mime, data: item.uri, filename: item.name },
+    request,
+    extension,
   )
 })
 
@@ -510,7 +542,7 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
         >((groups, part) => {
           const metadata = part.providerMetadata?.[providerMetadataKey]
           const id = itemID(part.providerMetadata, providerMetadataKey)
-          const phase = ProviderShared.isRecord(metadata) ? messagePhase(metadata.phase, extension) : undefined
+          const phase = ProviderShared.isRecord(metadata) ? messagePhase(metadata.phase) : undefined
           const group = groups.at(-1)
           if (group && group.id === id && group.phase === phase) group.parts.push(part)
           else groups.push({ id, phase, parts: [part] })
@@ -567,7 +599,9 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
             const content: ReadonlyArray<Content> = part.result.value
             input.push({
               role: "user",
-              content: yield* Effect.forEach(content, (item) => lowerToolResultContentItem(item, request, extension)),
+              content: yield* Effect.forEach(content, (item) =>
+                lowerHostedToolResultContentItem(item, request, extension),
+              ),
             })
           }
           if (itemID) hostedToolReferences.add(itemID)
@@ -1159,15 +1193,15 @@ export const initial = (request: LLMRequest, extension: Extension = BASE): Parse
   tools: ToolStream.empty<string>(),
   lifecycle: Lifecycle.initial(),
   messageItems: new Set<string>(),
-  messagePhase: (value) => messagePhase(value, extension),
+  messagePhase,
   messagePhases: {},
   reasoningItems: {},
   store: OpenResponsesOptions.resolve(request).store,
 })
 
-const messagePhase = (value: unknown, extension: Extension): MessagePhase | null | undefined => {
-  if (value === "commentary" || value === "final_answer") return value
-  return extension.messagePhase?.(value)
+const messagePhase = (value: unknown): MessagePhase | undefined => {
+  if (value === null || value === "commentary" || value === "final_answer") return value
+  return undefined
 }
 
 export const protocol = Protocol.make({

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

@@ -5,14 +5,13 @@ import { Auth } from "../route/auth.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
-import { LLMEvent, LLMRequest, type JsonSchema, type ToolDefinition } from "../schema/index.js"
+import { LLMRequest, type JsonSchema, type ToolDefinition } from "../schema/index.js"
 import { OpenResponses } from "./open-responses.js"
 import { optionalArray, ProviderShared } from "./shared.js"
-import { Lifecycle } from "./utils/lifecycle.js"
 import { OpenAIImage } from "./utils/openai-image.js"
+import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
-import { OpenResponsesChannel, type Options } from "./open-responses-channel.js"
-import { OpenAIResponsesChannel } from "./openai-responses-channel.js"
+import { OpenResponsesChannel } from "./open-responses-channel.js"
 
 const ADAPTER = "openai-responses"
 const NAME = "OpenAI Responses"
@@ -40,20 +39,8 @@ const OpenAIResponsesToolChoice = Schema.Union([
   Schema.Struct({ type: Schema.tag("image_generation") }),
 ])
 
-const OpenAIResponsesInputItem = Schema.Union([
-  Schema.Struct({
-    type: Schema.tag("message"),
-    id: Schema.optionalKey(Schema.String),
-    role: Schema.tag("assistant"),
-    content: Schema.Array(Schema.Struct({ type: Schema.tag("output_text"), text: Schema.String })),
-    phase: Schema.optionalKey(Schema.NullOr(OpenResponses.MessagePhase)),
-  }),
-  OpenResponses.InputItem,
-])
-
 const OpenAIResponsesCoreFields = {
   ...OpenResponses.coreFields,
-  input: Schema.Array(OpenAIResponsesInputItem),
   tools: optionalArray(OpenAIResponsesTools),
   tool_choice: Schema.optional(OpenAIResponsesToolChoice),
 }
@@ -67,16 +54,6 @@ export type OpenAIResponsesBody = Schema.Schema.Type<typeof OpenAIResponsesBody>
 const extension = {
   id: ADAPTER,
   name: NAME,
-  messagePhase: (value: unknown) => (value === null ? null : undefined),
-  lowerMedia: ({ part, media, request }) => {
-    if (request.model.provider !== "xai" || media.mime !== "application/pdf") return undefined
-    return {
-      type: "input_file",
-      filename: part.filename ?? "document.pdf",
-      file_data: media.base64,
-      mime_type: media.mime,
-    }
-  },
 } satisfies OpenResponses.Extension
 
 const nativeImageToolInput = (tool: ToolDefinition) => {
@@ -128,46 +105,7 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
   } satisfies OpenAIResponsesBody
 })
 
-type HostedToolData = OpenResponses.StreamItem & {
-  readonly id: string
-  readonly status?: string
-  readonly action?: unknown
-  readonly queries?: unknown
-  readonly results?: unknown
-  readonly code?: string
-  readonly container_id?: string
-  readonly outputs?: unknown
-  readonly server_label?: string
-  readonly output?: unknown
-  readonly result?: string
-  readonly output_format?: "png" | "jpeg" | "webp"
-  readonly error?: unknown
-}
-
-const HOSTED_TOOLS = {
-  web_search_call: { name: "web_search", input: (item) => item.action ?? {} },
-  web_search_preview_call: { name: "web_search_preview", input: (item) => item.action ?? {} },
-  file_search_call: { name: "file_search", input: (item) => ({ queries: item.queries ?? [] }) },
-  code_interpreter_call: {
-    name: "code_interpreter",
-    input: (item) => ({ code: item.code, container_id: item.container_id }),
-  },
-  computer_use_call: { name: "computer_use", input: (item) => item.action ?? {} },
-  image_generation_call: { name: "image_generation", input: () => ({}) },
-  mcp_call: {
-    name: "mcp",
-    input: (item) => ({ server_label: item.server_label, name: item.name, arguments: item.arguments }),
-  },
-  local_shell_call: { name: "local_shell", input: (item) => item.action ?? {} },
-} as const satisfies Record<string, { readonly name: string; readonly input: (item: HostedToolData) => unknown }>
-
-type HostedToolType = keyof typeof HOSTED_TOOLS
-type HostedToolItem = HostedToolData & { readonly type: HostedToolType }
-
-const isHostedToolItem = (item: OpenResponses.StreamItem): item is HostedToolItem =>
-  item.type in HOSTED_TOOLS && typeof item.id === "string" && item.id.length > 0
-
-const hostedToolResult = Effect.fn("OpenAIResponses.hostedToolResult")(function* (item: HostedToolItem) {
+const hostedToolResult = Effect.fn("OpenAIResponses.hostedToolResult")(function* (item: ResponsesHostedTools.Item) {
   const isError = item.error !== undefined && item.error !== null
   if (item.type === "image_generation_call" && item.result) {
     yield* Effect.fromResult(Encoding.decodeBase64(item.result)).pipe(
@@ -188,32 +126,22 @@ const hostedToolResult = Effect.fn("OpenAIResponses.hostedToolResult")(function*
   return isError ? { type: "error" as const, value: item.error } : { type: "json" as const, value: item }
 })
 
-const onHostedToolDone = Effect.fn("OpenAIResponses.onHostedToolDone")(function* (
-  state: OpenResponses.ParserState,
-  item: HostedToolItem,
-) {
-  const tool = HOSTED_TOOLS[item.type]
-  const providerMetadata = OpenResponses.providerMetadata(state, { itemId: item.id })
-  const events: LLMEvent[] = []
-  const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
-  events.push(
-    LLMEvent.toolCall({
-      id: item.id,
-      name: tool.name,
-      input: tool.input(item),
-      providerExecuted: true,
-      providerMetadata,
-    }),
-    LLMEvent.toolResult({
-      id: item.id,
-      name: tool.name,
-      result: yield* hostedToolResult(item),
-      providerExecuted: true,
-      providerMetadata,
-    }),
-  )
-  return [{ ...state, lifecycle }, events] satisfies OpenResponses.StepResult
-})
+const HOSTED_TOOLS = {
+  web_search_call: { name: "web_search", input: (item) => item.action ?? {} },
+  web_search_preview_call: { name: "web_search_preview", input: (item) => item.action ?? {} },
+  file_search_call: { name: "file_search", input: (item) => ({ queries: item.queries ?? [] }) },
+  code_interpreter_call: {
+    name: "code_interpreter",
+    input: (item) => ({ code: item.code, container_id: item.container_id }),
+  },
+  computer_use_call: { name: "computer_use", input: (item) => item.action ?? {} },
+  image_generation_call: { name: "image_generation", input: () => ({}), result: hostedToolResult },
+  mcp_call: {
+    name: "mcp",
+    input: (item) => ({ server_label: item.server_label, name: item.name, arguments: item.arguments }),
+  },
+  local_shell_call: { name: "local_shell", input: (item) => item.action ?? {} },
+} as const satisfies ResponsesHostedTools.Definitions
 
 const step = (state: OpenResponses.ParserState, event: OpenResponses.Event) => {
   if (event.type === "response.reasoning_text.delta" || event.type === "response.reasoning_summary.delta")
@@ -224,8 +152,8 @@ const step = (state: OpenResponses.ParserState, event: OpenResponses.Event) => {
     return event.item_id
       ? Effect.succeed(OpenResponses.onReasoningDone(state, event))
       : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`)
-  if (event.type === "response.output_item.done" && event.item && isHostedToolItem(event.item))
-    return onHostedToolDone(state, event.item)
+  if (event.type === "response.output_item.done" && event.item && ResponsesHostedTools.isItem(event.item, HOSTED_TOOLS))
+    return ResponsesHostedTools.onDone(state, event.item, HOSTED_TOOLS)
   return OpenResponses.step(state, event)
 }
 
@@ -247,11 +175,7 @@ const endpoint = Endpoint.path<OpenAIResponsesBody>(PATH, { baseURL: DEFAULT_BAS
 const auth = Auth.none
 
 export const httpTransport = HttpTransport.sseJson.with<OpenAIResponsesBody>()
-export const channelTransport = (options: Omit<Options, "driver">) =>
-  OpenResponsesChannel.transport<OpenAIResponsesBody>({
-    ...options,
-    driver: (input) => OpenAIResponsesChannel.driver({ id: options.id, name: options.name, ...input }),
-  })
+export const channelTransport = OpenResponsesChannel.transport<OpenAIResponsesBody>
 export const transport = channelTransport({
   id: ADAPTER,
   name: NAME,

packages/ai/src/protocols/utils/responses-hosted-tools.ts

@@ -0,0 +1,70 @@
+import { Effect } from "effect"
+import { LLMEvent, type AIError, type ToolResultPart } from "../../schema/index.js"
+import { OpenResponses } from "../open-responses.js"
+import { Lifecycle } from "./lifecycle.js"
+
+export type Item = OpenResponses.StreamItem & {
+  readonly id: string
+  readonly status?: string
+  readonly action?: unknown
+  readonly queries?: unknown
+  readonly results?: unknown
+  readonly code?: string
+  readonly container_id?: string
+  readonly outputs?: unknown
+  readonly server_label?: string
+  readonly output?: unknown
+  readonly result?: string
+  readonly output_format?: "png" | "jpeg" | "webp"
+  readonly error?: unknown
+}
+
+export interface Definition {
+  readonly name: string
+  readonly input: (item: Item) => unknown
+  readonly result?: (item: Item) => Effect.Effect<ToolResultPart["result"], AIError>
+}
+
+export type Definitions = Readonly<Record<string, Definition>>
+
+export const isItem = <Tools extends Definitions>(item: OpenResponses.StreamItem, tools: Tools): item is Item =>
+  item.type in tools && typeof item.id === "string" && item.id.length > 0
+
+export const onDone: (
+  state: OpenResponses.ParserState,
+  item: Item,
+  tools: Definitions,
+) => Effect.Effect<OpenResponses.StepResult, AIError> = Effect.fn("ResponsesHostedTools.onDone")(function* (
+  state,
+  item,
+  tools,
+) {
+  const tool = tools[item.type]
+  if (!tool) return [state, []] satisfies OpenResponses.StepResult
+  const providerMetadata = OpenResponses.providerMetadata(state, { itemId: item.id })
+  const events: LLMEvent[] = []
+  const lifecycle = Lifecycle.stepStart(state.lifecycle, events)
+  events.push(
+    LLMEvent.toolCall({
+      id: item.id,
+      name: tool.name,
+      input: tool.input(item),
+      providerExecuted: true,
+      providerMetadata,
+    }),
+    LLMEvent.toolResult({
+      id: item.id,
+      name: tool.name,
+      result: tool.result
+        ? yield* tool.result(item)
+        : item.error !== undefined && item.error !== null
+          ? { type: "error", value: item.error }
+          : { type: "json", value: item },
+      providerExecuted: true,
+      providerMetadata,
+    }),
+  )
+  return [{ ...state, lifecycle }, events] satisfies OpenResponses.StepResult
+})
+
+export * as ResponsesHostedTools from "./responses-hosted-tools.js"

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

@@ -0,0 +1,55 @@
+import { Effect } from "effect"
+import { Protocol } from "../route/protocol.js"
+import { OpenResponses } from "./open-responses.js"
+import { ProviderShared } from "./shared.js"
+import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
+
+const ADAPTER = "xai-responses"
+const NAME = "xAI Responses"
+
+const extension = {
+  id: ADAPTER,
+  name: NAME,
+} satisfies OpenResponses.Extension
+
+const HOSTED_TOOLS = {
+  web_search_call: { name: "web_search", input: (item) => item.action ?? {} },
+  x_search_call: { name: "x_search", input: (item) => item.action ?? {} },
+  file_search_call: { name: "file_search", input: (item) => ({ queries: item.queries ?? [] }) },
+  code_interpreter_call: {
+    name: "code_interpreter",
+    input: (item) => ({ code: item.code, container_id: item.container_id }),
+  },
+  image_generation_call: { name: "image_generation", input: () => ({}) },
+  mcp_call: {
+    name: "mcp",
+    input: (item) => ({ server_label: item.server_label, name: item.name, arguments: item.arguments }),
+  },
+} as const satisfies ResponsesHostedTools.Definitions
+
+const step = (state: OpenResponses.ParserState, event: OpenResponses.Event) => {
+  if (event.type === "response.reasoning_text.delta" || event.type === "response.reasoning_summary.delta")
+    return event.item_id
+      ? Effect.succeed(OpenResponses.onReasoningDelta(state, event, event.item_id))
+      : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`)
+  if (event.type === "response.reasoning_text.done" || event.type === "response.reasoning_summary.done")
+    return event.item_id
+      ? Effect.succeed(OpenResponses.onReasoningDone(state, event))
+      : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`)
+  if (event.type === "response.output_item.done" && event.item && ResponsesHostedTools.isItem(event.item, HOSTED_TOOLS))
+    return ResponsesHostedTools.onDone(state, event.item, HOSTED_TOOLS)
+  return OpenResponses.step(state, event)
+}
+
+export const protocol = Protocol.make({
+  id: ADAPTER,
+  body: OpenResponses.protocol.body,
+  stream: {
+    event: OpenResponses.protocol.stream.event,
+    initial: (request) => OpenResponses.initial(request, extension),
+    step,
+    terminal: OpenResponses.terminal,
+  },
+})
+
+export * as XAIResponses from "./xai-responses.js"

packages/ai/src/providers/xai.ts

@@ -5,7 +5,8 @@ import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile.js"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
-import * as OpenAIResponses from "../protocols/openai-responses.js"
+import { OpenResponsesChannel } from "../protocols/open-responses-channel.js"
+import { XAIResponses } from "../protocols/xai-responses.js"
 import { XAIImages } from "../protocols/xai-images.js"
 import type { OpenAIOptionsInput } from "./openai-options.js"
 import type { ProviderPackage } from "../provider-package.js"
@@ -34,9 +35,9 @@ const responsesRoute = Route.make({
   id: "openai-responses",
   provider: id,
   providerMetadataKey: "xai",
-  protocol: OpenAIResponses.protocol,
+  protocol: XAIResponses.protocol,
   endpoint: Endpoint.path("/responses", { baseURL: OpenAICompatibleProfiles.profiles.xai.baseURL }),
-  transport: OpenAIResponses.channelTransport({
+  transport: OpenResponsesChannel.transport({
     id: "openai-responses",
     name: "xAI Responses",
     rotateAfterMs: RESPONSES_WEBSOCKET_ROTATE_AFTER_MS,

packages/ai/test/fixtures/recordings/pdf/openai-tool-result.json

@@ -1,7 +1,14 @@
 {
   "version": 1,
   "metadata": {
-    "tags": ["prefix:pdf", "pdf", "provider:openai", "protocol:openai-responses", "tool", "tool-result"],
+    "tags": [
+      "prefix:pdf",
+      "pdf",
+      "provider:openai",
+      "protocol:openai-responses",
+      "tool",
+      "tool-result"
+    ],
     "name": "pdf/openai-tool-result",
     "recordedAt": "2026-07-22T18:15:36.438Z"
   },
@@ -14,7 +21,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"gpt-4o-mini\",\"input\":[{\"role\":\"system\",\"content\":\"Read the PDF returned by the tool and follow the user's response format exactly.\"},{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]},{\"type\":\"function_call\",\"call_id\":\"call_pdf_1\",\"name\":\"read_pdf\",\"arguments\":\"{}\"},{\"type\":\"function_call_output\",\"call_id\":\"call_pdf_1\",\"output\":[{\"type\":\"input_text\",\"text\":\"PDF read successfully\"},{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"}]}],\"tools\":[{\"type\":\"function\",\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parameters\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
+        "body": "{\"model\":\"gpt-4o-mini\",\"input\":[{\"role\":\"system\",\"content\":\"Read the PDF returned by the tool and follow the user's response format exactly.\"},{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]},{\"type\":\"function_call\",\"call_id\":\"call_pdf_1\",\"name\":\"read_pdf\",\"arguments\":\"{}\"},{\"type\":\"function_call_output\",\"call_id\":\"call_pdf_1\",\"output\":[{\"type\":\"input_text\",\"text\":\"PDF read successfully\"},{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"}]}],\"tools\":[{\"type\":\"function\",\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parameters\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
       },
       "response": {
         "status": 200,

packages/ai/test/fixtures/recordings/pdf/openai-user-input.json

@@ -1,7 +1,13 @@
 {
   "version": 1,
   "metadata": {
-    "tags": ["prefix:pdf", "pdf", "provider:openai", "protocol:openai-responses", "user-input"],
+    "tags": [
+      "prefix:pdf",
+      "pdf",
+      "provider:openai",
+      "protocol:openai-responses",
+      "user-input"
+    ],
     "name": "pdf/openai-user-input",
     "recordedAt": "2026-07-22T18:15:34.867Z"
   },
@@ -14,7 +20,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"gpt-4o-mini\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"},{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
+        "body": "{\"model\":\"gpt-4o-mini\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"},{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
       },
       "response": {
         "status": 200,

packages/ai/test/fixtures/recordings/pdf/xai-tool-result.json

@@ -1,9 +1,17 @@
 {
   "version": 1,
   "metadata": {
-    "tags": ["prefix:pdf", "pdf", "provider:xai", "protocol:openai-responses", "tool", "tool-result"],
+    "tags": [
+      "prefix:pdf",
+      "pdf",
+      "provider:xai",
+      "protocol:xai-responses",
+      "tool",
+      "tool-result"
+    ],
     "name": "pdf/xai-tool-result",
-    "recordedAt": "2026-07-22T18:15:43.608Z"
+    "recordedAt": "2026-07-22T18:15:43.608Z",
+    "protocol": "xai-responses"
   },
   "interactions": [
     {
@@ -14,7 +22,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"grok-4.5\",\"input\":[{\"role\":\"system\",\"content\":\"Read the PDF returned by the tool and follow the user's response format exactly.\"},{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]},{\"type\":\"function_call\",\"call_id\":\"call_pdf_1\",\"name\":\"read_pdf\",\"arguments\":\"{}\"},{\"type\":\"function_call_output\",\"call_id\":\"call_pdf_1\",\"output\":[{\"type\":\"input_text\",\"text\":\"PDF read successfully\"},{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\",\"mime_type\":\"application/pdf\"}]}],\"tools\":[{\"type\":\"function\",\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parameters\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
+        "body": "{\"model\":\"grok-4.5\",\"input\":[{\"role\":\"system\",\"content\":\"Read the PDF returned by the tool and follow the user's response format exactly.\"},{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]},{\"type\":\"function_call\",\"call_id\":\"call_pdf_1\",\"name\":\"read_pdf\",\"arguments\":\"{}\"},{\"type\":\"function_call_output\",\"call_id\":\"call_pdf_1\",\"output\":[{\"type\":\"input_text\",\"text\":\"PDF read successfully\"},{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"}]}],\"tools\":[{\"type\":\"function\",\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parameters\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
       },
       "response": {
         "status": 200,

packages/ai/test/fixtures/recordings/pdf/xai-user-input.json

@@ -1,9 +1,16 @@
 {
   "version": 1,
   "metadata": {
-    "tags": ["prefix:pdf", "pdf", "provider:xai", "protocol:openai-responses", "user-input"],
+    "tags": [
+      "prefix:pdf",
+      "pdf",
+      "provider:xai",
+      "protocol:xai-responses",
+      "user-input"
+    ],
     "name": "pdf/xai-user-input",
-    "recordedAt": "2026-07-22T18:15:42.429Z"
+    "recordedAt": "2026-07-22T18:15:42.429Z",
+    "protocol": "xai-responses"
   },
   "interactions": [
     {
@@ -14,7 +21,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"grok-4.5\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\",\"mime_type\":\"application/pdf\"},{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
+        "body": "{\"model\":\"grok-4.5\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_file\",\"filename\":\"verification.pdf\",\"file_data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"},{\"type\":\"input_text\",\"text\":\"Return only the verification code from the PDF.\"}]}],\"store\":false,\"max_output_tokens\":40,\"temperature\":0,\"stream\":true}"
       },
       "response": {
         "status": 200,

packages/ai/test/provider/openai-compatible-responses.test.ts

@@ -93,7 +93,7 @@ describe("Open Responses-compatible route", () => {
     }),
   )
 
-  it.effect("omits OpenAI-only nullable phases from the Open Responses baseline", () =>
+  it.effect("preserves nullable phases in the forgiving Open Responses baseline", () =>
     Effect.gen(function* () {
       const model = configure({
         apiKey: "test-key",
@@ -113,7 +113,9 @@ describe("Open Responses-compatible route", () => {
       )
 
       expect(prepared.body).toMatchObject({
-        input: [{ type: "message", role: "assistant", content: [{ type: "output_text", text: "Unclassified." }] }],
+        input: [
+          { type: "message", role: "assistant", content: [{ type: "output_text", text: "Unclassified." }], phase: null },
+        ],
       })
     }),
   )

packages/ai/test/provider/openai-responses.test.ts

@@ -28,7 +28,7 @@ import * as Azure from "../../src/providers/azure.js"
 import * as OpenAI from "../../src/providers/openai.js"
 import * as XAI from "../../src/providers/xai.js"
 import * as OpenAIResponses from "../../src/protocols/openai-responses.js"
-import { OpenAIResponsesChannel } from "../../src/protocols/openai-responses-channel.js"
+import { OpenResponsesContinuation } from "../../src/protocols/open-responses-continuation.js"
 import * as ProviderShared from "../../src/protocols/shared.js"
 import { continuationRequest, nativeOpenAIResponsesContinuation } from "../continuation-scenarios.js"
 import { it } from "../lib/effect.js"
@@ -68,7 +68,7 @@ const baseChannelDriver = (message: string): WebSocketChannelDriver => ({
 
 const continuationDriver = (request: Readonly<Record<string, unknown>>) => {
   const message = ProviderShared.encodeJson(request)
-  return OpenAIResponsesChannel.driver({
+  return OpenResponsesContinuation.driver({
     id: "openai-responses",
     name: "OpenAI Responses",
     request,
@@ -1273,7 +1273,7 @@ describe("OpenAI Responses route", () => {
         {
           type: "input_file",
           filename: "report.pdf",
-          file_data: "data:application/pdf;base64,JVBERi0xLjQ=",
+          file_data: "JVBERi0xLjQ=",
         },
       ])
     }),
@@ -1300,12 +1300,12 @@ describe("OpenAI Responses route", () => {
       )
 
       expect(expectToolOutput(prepared.body).output).toEqual([
-        { type: "input_file", filename: "report.pdf", file_data: dataUrl },
+        { type: "input_file", filename: "report.pdf", file_data: base64 },
       ])
     }),
   )
 
-  it.effect("uses xAI inline file encoding for PDF tool results", () =>
+  it.effect("uses standard inline file encoding for xAI PDF tool results", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
         LLM.request({
@@ -1334,7 +1334,6 @@ describe("OpenAI Responses route", () => {
           type: "input_file",
           filename: "report.pdf",
           file_data: "JVBERi0xLjQ=",
-          mime_type: "application/pdf",
         },
       ])
     }),
@@ -1359,7 +1358,61 @@ describe("OpenAI Responses route", () => {
       )
 
       expect(expectToolOutput(prepared.body).output).toEqual([
-        { type: "input_file", filename: "file", file_data: "data:audio/mpeg;base64,AAECAw==" },
+        { type: "input_file", filename: "file", file_data: "AAECAw==" },
+      ])
+    }),
+  )
+
+  it.effect("lowers remote tool-result media URLs without base64 wrapping", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "fetch", input: {} })]),
+            Message.tool({
+              id: "call_1",
+              name: "fetch",
+              resultType: "content",
+              result: [
+                { type: "file", uri: "https://example.com/image.png", mime: "image/png" },
+                { type: "file", uri: "https://example.com/report.pdf", mime: "application/pdf", name: "report.pdf" },
+              ],
+            }),
+          ],
+        }),
+      )
+
+      expect(expectToolOutput(prepared.body).output).toEqual([
+        { type: "input_image", image_url: "https://example.com/image.png" },
+        { type: "input_file", filename: "report.pdf", file_url: "https://example.com/report.pdf" },
+      ])
+    }),
+  )
+
+  it.effect("lowers tool-result videos as input_video", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "record", input: {} })]),
+            Message.tool({
+              id: "call_1",
+              name: "record",
+              resultType: "content",
+              result: [
+                { type: "file", uri: "data:video/mp4;base64,AAECAw==", mime: "video/mp4" },
+                { type: "file", uri: "https://example.com/demo.mp4", mime: "video/mp4" },
+              ],
+            }),
+          ],
+        }),
+      )
+
+      expect(expectToolOutput(prepared.body).output).toEqual([
+        { type: "input_video", video_url: "data:video/mp4;base64,AAECAw==" },
+        { type: "input_video", video_url: "https://example.com/demo.mp4" },
       ])
     }),
   )
@@ -2712,7 +2765,7 @@ describe("OpenAI Responses route", () => {
             {
               type: "input_file",
               filename: "report.pdf",
-              file_data: "data:application/pdf;base64,JVBERi0xLjQ=",
+              file_data: "JVBERi0xLjQ=",
             },
           ],
         },
@@ -2720,7 +2773,7 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("uses xAI inline file encoding for user PDFs", () =>
+  it.effect("uses standard inline file encoding for xAI user PDFs", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
         LLM.request({
@@ -2744,7 +2797,6 @@ describe("OpenAI Responses route", () => {
               type: "input_file",
               filename: "report.pdf",
               file_data: "JVBERi0xLjQ=",
-              mime_type: "application/pdf",
             },
           ],
         },
@@ -2769,7 +2821,7 @@ describe("OpenAI Responses route", () => {
             {
               type: "input_file",
               filename: "file",
-              file_data: "data:application/x-tar;base64,AAECAw==",
+              file_data: "AAECAw==",
             },
           ],
         },
@@ -2777,6 +2829,37 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
+  it.effect("lowers remote user media URLs without base64 wrapping", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          messages: [
+            Message.user([
+              { type: "media", mediaType: "image/png", data: "https://example.com/image.png" },
+              {
+                type: "media",
+                mediaType: "application/pdf",
+                data: "https://example.com/report.pdf",
+                filename: "report.pdf",
+              },
+            ]),
+          ],
+        }),
+      )
+
+      expect(prepared.body.input).toEqual([
+        {
+          role: "user",
+          content: [
+            { type: "input_image", image_url: "https://example.com/image.png" },
+            { type: "input_file", filename: "report.pdf", file_url: "https://example.com/report.pdf" },
+          ],
+        },
+      ])
+    }),
+  )
+
   it.effect("fails with a typed rate limit for provider error frames", () =>
     Effect.gen(function* () {
       const error = yield* LLMClient.generate(request).pipe(

packages/ai/test/provider/pdf.recorded.test.ts

@@ -64,7 +64,7 @@ const targets: ReadonlyArray<{
     id: "xai",
     name: "xAI Grok 4.5",
     provider: "xai",
-    protocol: "openai-responses",
+    protocol: "xai-responses",
     requires: "XAI_API_KEY",
     filename: "verification.pdf",
     maxTokens: 40,

packages/ai/test/provider/xai-responses.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM, LLMEvent } from "../../src/index.js"
+import { XAI } from "../../src/providers.js"
+import { OpenResponses } from "../../src/protocols/open-responses.js"
+import { OpenAIResponses } from "../../src/protocols/openai-responses.js"
+import { XAIResponses } from "../../src/protocols/xai-responses.js"
+import { LLMClient } from "../../src/route.js"
+import { compileRequest } from "../../src/route/client.js"
+import { it } from "../lib/effect.js"
+import { fixedResponse } from "../lib/http.js"
+import { sseEvents } from "../lib/sse.js"
+
+const model = XAI.configure({ apiKey: "test", baseURL: "https://api.x.ai/v1" }).responses("grok-4.6")
+
+describe("xAI Responses route", () => {
+  it.effect("extends the Open Responses baseline directly", () =>
+    Effect.gen(function* () {
+      expect(XAIResponses.protocol.body).toBe(OpenResponses.protocol.body)
+      expect(XAIResponses.protocol.body).not.toBe(OpenAIResponses.protocol.body)
+
+      const prepared = yield* compileRequest(LLM.request({ model, prompt: "Hello" }))
+      expect(prepared.protocol).toBe("xai-responses")
+    }),
+  )
+
+  it.effect("parses xAI reasoning text events", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(LLM.request({ model, prompt: "Think" })).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "response.reasoning_text.delta", item_id: "reasoning_1", delta: "Considering." },
+              { type: "response.reasoning_text.done", item_id: "reasoning_1" },
+              {
+                type: "response.output_item.done",
+                item: { type: "reasoning", id: "reasoning_1", encrypted_content: "opaque" },
+              },
+              { type: "response.completed", response: { id: "response_1" } },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.message.content.find((part) => part.type === "reasoning")).toMatchObject({
+        type: "reasoning",
+        text: "Considering.",
+        providerMetadata: { xai: { itemId: "reasoning_1", reasoningEncryptedContent: "opaque" } },
+      })
+    }),
+  )
+
+  it.effect("parses xAI hosted tool items", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(LLM.request({ model, prompt: "Search X" })).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              {
+                type: "response.output_item.done",
+                item: { type: "x_search_call", id: "x_search_1", status: "completed", action: { query: "news" } },
+              },
+              { type: "response.completed", response: { id: "response_1" } },
+            ),
+          ),
+        ),
+      )
+
+      expect(response.events.find(LLMEvent.is.toolCall)).toMatchObject({
+        id: "x_search_1",
+        name: "x_search",
+        input: { query: "news" },
+        providerExecuted: true,
+      })
+    }),
+  )
+})

packages/app/src/session/timeline/message-timeline.tsx

@@ -54,7 +54,7 @@ export function BackgroundMoveHint(props: { keybind?: string[] }) {
   return (
     <div
       data-component="session-background-hint"
-      class="flex h-6 max-w-full items-center justify-center gap-[3px] overflow-hidden text-[13px] font-[530] leading-5 tracking-[-0.04px] text-v2-text-text-muted"
+      class="flex h-6 max-w-full items-center justify-center gap-[3px] overflow-hidden text-[13px] font-[440] leading-5 tracking-[-0.04px] text-v2-text-text-muted"
       aria-label={language.t("session.background.moveInline", { keybind: keybind() })}
     >
       <span data-slot="session-background-hint-prefix" class="shrink-0">

packages/client/src/solid/data.ts

@@ -1101,6 +1101,9 @@ export function createData(config: CreateDataInput) {
       get(sessionID: string) {
         return store.session.info[sessionID]
       },
+      creating(sessionID: string) {
+        return creating.has(sessionID)
+      },
       remember(info: SessionInfo) {
         setStore("session", "info", info.id, reconcile(info))
         sync.complete(`session:${info.id}`)

packages/client/test/solid-data.test.ts

@@ -1,4 +1,4 @@
-import { test } from "bun:test"
+import { expect, test } from "bun:test"
 import { createRoot } from "solid-js"
 import { createData, type CreateDataInput } from "../src/solid"
 import { OpenCode, type OpenCodeEvent, type SessionInfo } from "../src/promise"
@@ -72,6 +72,37 @@ test("revalidates after an event overtakes an active session read", async () =>
   }
 })
 
+test("reports optimistic sessions as creating until the request settles", async () => {
+  const release = Promise.withResolvers<void>()
+  const api = OpenCode.make({
+    baseUrl: "http://opencode.local",
+    fetch: async (input, init) => {
+      const request = input instanceof Request ? input : new Request(input, init)
+      if (!request.url.endsWith("/api/session")) throw new Error(`Unexpected request: ${request.url}`)
+      await release.promise
+      return Response.json({ data: session(0) })
+    },
+  })
+  const event: CreateDataInput["event"] = {
+    on: () => () => {},
+    listen: () => () => {},
+  }
+  const setup = createRoot((dispose) => ({
+    data: createData({ api: () => api, directory: "/project", event, connection: { status: () => "connected" } }),
+    dispose,
+  }))
+
+  try {
+    const created = setup.data.session.create({ id: "ses_refresh", location: { directory: "/project" } })
+    expect(setup.data.session.creating(created.id)).toBe(true)
+    release.resolve()
+    await created.request
+    expect(setup.data.session.creating(created.id)).toBe(false)
+  } finally {
+    setup.dispose()
+  }
+})
+
 async function wait(check: () => boolean) {
   const started = Date.now()
   while (!check()) {

packages/core/src/location-activity.ts

@@ -0,0 +1,74 @@
+export * as LocationActivity from "./location-activity.js"
+
+import { Clock, Context, Duration, Effect, Layer, RcMap, Schema } from "effect"
+import { Bus } from "./bus.js"
+import { Location } from "./location.js"
+import { LocationServiceMap } from "./location-service-map.js"
+import { SessionEvent } from "./session/event.js"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+
+const isSessionEvent = Schema.is(SessionEvent.Durable)
+
+export class Service extends Context.Service<Service, {}>()("@opencode/LocationActivity") {}
+
+export function layer(options: { readonly timeToLive?: Duration.Input; readonly sweepInterval?: Duration.Input } = {}) {
+  return Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const clock = yield* Clock.Clock
+      const bus = yield* Bus.Service
+      const locations = yield* LocationServiceMap.Service
+      const timeToLive = Duration.toMillis(options.timeToLive ?? "60 minutes")
+      const entries = new Map<string, { readonly ref: Location.Ref; expiresAt: number }>()
+      const key = (ref: Location.Ref) => `${ref.directory}\0${ref.workspaceID ?? ""}`
+      const touch = (ref: Location.Ref) =>
+        Effect.sync(() => {
+          entries.set(key(ref), { ref, expiresAt: clock.currentTimeMillisUnsafe() + timeToLive })
+        })
+
+      const unsubscribe = yield* bus.listen((event) => {
+        if (!isSessionEvent(event)) return Effect.void
+        const location = event.location
+        if (!location) return Effect.void
+        return RcMap.has(locations.rcMap, location).pipe(
+          Effect.flatMap((active) => (active ? touch(location) : Effect.void)),
+        )
+      })
+      yield* Effect.addFinalizer(() => unsubscribe)
+      yield* Effect.gen(function* () {
+        yield* Effect.sleep(options.sweepInterval ?? "1 minute")
+        const refs = Array.from(yield* RcMap.keys(locations.rcMap))
+        const cached = new Set(refs.map(key))
+        yield* Effect.forEach(
+          refs,
+          (ref) => (entries.has(key(ref)) ? Effect.void : touch(ref)),
+          { discard: true },
+        )
+        for (const id of entries.keys()) {
+          if (!cached.has(id)) entries.delete(id)
+        }
+        const now = clock.currentTimeMillisUnsafe()
+        const expired = Array.from(entries.values()).filter((entry) => entry.expiresAt <= now)
+        yield* Effect.forEach(
+          expired,
+          (entry) => {
+            entries.delete(key(entry.ref))
+            return Effect.logInfo("location services evicted", {
+              directory: entry.ref.directory,
+              workspaceID: entry.ref.workspaceID,
+            }).pipe(Effect.andThen(locations.invalidate(entry.ref)))
+          },
+          { discard: true },
+        )
+      }).pipe(Effect.forever, Effect.forkScoped)
+
+      return Service.of({})
+    }),
+  )
+}
+
+export const node = makeGlobalNode({
+  service: Service,
+  layer: layer(),
+  deps: [Bus.node, LocationServiceMap.node],
+})

packages/core/src/location-services.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer, LayerMap } from "effect"
+import { Duration, Effect, Layer, LayerMap } from "effect"
 import { existsSync } from "fs"
 import path from "path"
 import { Agent } from "./agent.js"
@@ -147,7 +147,7 @@ export function buildLocationServiceMap(
             Layer.provide(LayerNode.compile(location.hoisted)),
           )
         },
-        { idleTimeToLive: (ref) => (existsSync(ref.directory) ? "60 minutes" : 0) },
+        { idleTimeToLive: (ref) => (existsSync(ref.directory) ? Duration.infinity : Duration.zero) },
       ),
       (inner) => ({
         ...inner,

packages/core/src/models-dev.ts

@@ -541,6 +541,9 @@ const decodeCatalog = (text: string) =>
   Schema.decodeUnknownEffect(CatalogJson)(text).pipe(Effect.map((catalog) => catalog as Record<string, SourceProvider>))
 const Cache = Schema.Struct({
   updatedAt: Schema.Number,
+  // Digest of the raw body, persisted so refresh() can skip republishing a
+  // byte-identical catalog. Optional for entries written before it existed.
+  digest: Schema.optional(Schema.String),
   body: CatalogJson,
 })
 const defaultSource = "https://models.opencode.ai"
@@ -568,6 +571,10 @@ function cacheKey(source: string) {
   return `models-dev:catalog:${Hash.fast(source)}`
 }
 
+export function bodyDigest(text: string) {
+  return new Bun.CryptoHasher("sha256").update(text).digest("hex")
+}
+
 export const layer = (options?: Options) =>
   Layer.effect(
     Service,
@@ -600,16 +607,11 @@ export const layer = (options?: Options) =>
           return {
             catalog: cached.value.body as Record<string, SourceProvider>,
             updatedAt: cached.value.updatedAt,
+            digest: cached.value.digest,
           }
         if (value !== undefined) yield* kv.remove(key)
       })
 
-      const fresh = Effect.fnUntraced(function* () {
-        const cached = yield* loadFromCache()
-        if (!cached) return false
-        return Date.now() - cached.updatedAt < Duration.toMillis(ttl)
-      })
-
       const fetchApi = Effect.fn("ModelsDev.fetchApi")(function* () {
         return yield* HttpClientRequest.get(`${source}/api.json`).pipe(
           HttpClientRequest.setHeader("User-Agent", userAgent),
@@ -630,19 +632,23 @@ export const layer = (options?: Options) =>
       // periodic fetch below still refreshes on top.
       const loadSnapshot = options?.snapshot === false ? Effect.undefined : bundledSnapshot
 
-      const fetchAndWrite = Effect.fn("ModelsDev.fetchAndWrite")(function* () {
-        const text = yield* fetchApi()
-        const catalog = yield* decodeCatalog(text)
-        // Best-effort: a cache-write failure must never kill catalog
-        // population. The payload has outgrown some KV backends' per-value
-        // limits (Durable Object SQLite caps values at 2 MB and api.json
-        // passed it in Aug 2026); a boot without a cache hit just refetches.
-        yield* kv.set(key, { updatedAt: Date.now(), body: text }).pipe(
+      // Best-effort: a cache-write failure must never kill catalog
+      // population. The payload has outgrown some KV backends' per-value
+      // limits (Durable Object SQLite caps values at 2 MB and api.json
+      // passed it in Aug 2026); a boot without a cache hit just refetches.
+      const writeCache = Effect.fn("ModelsDev.writeCache")(function* (text: string) {
+        yield* kv.set(key, { updatedAt: Date.now(), digest: bodyDigest(text), body: text }).pipe(
           Effect.catchCauseIf(
             (cause) => !Cause.hasInterruptsOnly(cause),
             (cause) => Effect.logWarning("Failed to cache models.dev catalog", { cause }),
           ),
         )
+      })
+
+      const fetchAndWrite = Effect.fn("ModelsDev.fetchAndWrite")(function* () {
+        const text = yield* fetchApi()
+        const catalog = yield* decodeCatalog(text)
+        yield* writeCache(text)
         return catalog
       })
 
@@ -672,8 +678,15 @@ export const layer = (options?: Options) =>
         yield* lock
           .withPermit(
             Effect.gen(function* () {
-              if (!force && (yield* fresh())) return
-              yield* fetchAndWrite()
+              const stored = yield* loadFromCache()
+              if (!force && stored && Date.now() - stored.updatedAt < Duration.toMillis(ttl)) return
+              const text = yield* fetchApi()
+              // models.dev rarely changes between polls; skip the cache write,
+              // invalidation, and Refreshed event for a byte-identical body so
+              // downstream catalog.updated listeners stay quiet.
+              if (!force && stored?.digest === bodyDigest(text)) return
+              yield* decodeCatalog(text)
+              yield* writeCache(text)
               yield* invalidate
               yield* bus.publish(ModelsDev.Event.Refreshed, {})
             }),

packages/core/src/plugin/skill/opencode.md

@@ -130,7 +130,7 @@ secret into configuration.
 For any request to migrate OpenCode configuration, agents, commands, skills,
 plugins, integrations, or other behavior from V1 to V2, read the full
 [migration guide](https://opencode.ai/v2/docs/migrate-v1) before acting. In
-the repository, its source is `packages/www/content/docs/migrate-v1.mdx`.
+the repository, its source is `packages/www/src/docs/content/migrate-v1.mdx`.
 
 V1 config files and `.opencode/` definitions are intended to remain compatible.
 The only intentional breaking changes are the server API and plugin API. Native

packages/core/test/location-layer.test.ts

@@ -3,14 +3,16 @@ import path from "path"
 import { describe, expect } from "bun:test"
 import { Config } from "@opencode-ai/schema/config"
 import { Money } from "@opencode-ai/schema/money"
-import { DateTime, Deferred, Effect, Equal, Fiber, Hash, RcMap, Schema, Stream } from "effect"
+import { DateTime, Deferred, Duration, Effect, Equal, Fiber, Hash, Layer, LayerMap, RcMap, Schema, Stream } from "effect"
+import { TestClock } from "effect/testing"
 import { Plugin as EffectPlugin } from "@opencode-ai/plugin/effect"
 import { Agent } from "@opencode-ai/core/agent"
 import { Catalog } from "@opencode-ai/core/catalog"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { Global } from "@opencode-ai/util/global"
-import { LocationServiceMap } from "@opencode-ai/core/location-services"
+import { LocationServiceMap, type LocationServices } from "@opencode-ai/core/location-services"
+import { LocationActivity } from "@opencode-ai/core/location-activity"
 import { Location } from "@opencode-ai/core/location"
 import { Plugin } from "@opencode-ai/core/plugin"
 import { SdkPlugins } from "@opencode-ai/core/plugin/sdk"
@@ -21,6 +23,7 @@ import { Project } from "@opencode-ai/core/project"
 import { Provider } from "@opencode-ai/core/provider"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 import { Session } from "@opencode-ai/core/session"
+import { SessionEvent } from "@opencode-ai/core/session/event"
 import { SessionRunnerModel } from "@opencode-ai/core/session/runner/model"
 import { tmpdir } from "./fixture/tmpdir"
 import { tempGlobalLayer } from "./fixture/global"
@@ -41,8 +44,55 @@ const itWithSdk = testEffect(
     [Global.node, tempGlobalLayer],
   ]),
 )
+const activityLocations = Layer.effect(
+  LocationServiceMap.Service,
+  LayerMap.make(
+    (ref) =>
+      // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+      Layer.succeed(
+        Location.Service,
+        Location.Service.of({
+          directory: ref.directory,
+          workspaceID: ref.workspaceID,
+          project: { id: Project.ID.global, directory: ref.directory, canonical: ref.directory },
+        }),
+      ) as unknown as Layer.Layer<LocationServices>,
+    { idleTimeToLive: Duration.infinity },
+  ),
+)
+const itWithActivity = testEffect(
+  AppNodeBuilder.build(
+    LayerNode.group([Database.node, Bus.node, LocationServiceMap.node, LocationActivity.node]),
+    [[LocationServiceMap.node, activityLocations]],
+  ),
+)
 
 describe("LocationServiceMap", () => {
+  itWithActivity.effect("refreshes lifetime from Session events only", () =>
+    Effect.gen(function* () {
+      const locations = yield* LocationServiceMap.Service
+      const bus = yield* Bus.Service
+      const ref = Location.Ref.make({ directory: AbsolutePath.make("/project") })
+      const sessionID = Session.ID.make("ses_location_activity")
+      const read = Location.Service.pipe(Effect.provide(locations.get(ref)), Effect.scoped)
+
+      yield* read
+      yield* TestClock.adjust("59 minutes")
+      yield* bus.publish(Catalog.Event.Updated, {}, { location: ref })
+      yield* TestClock.adjust("2 minutes")
+      expect(Array.from(yield* RcMap.keys(locations.rcMap))).toEqual([])
+
+      yield* read
+      yield* bus.publish(SessionEvent.Execution.Started, { sessionID }, { location: ref })
+      yield* TestClock.adjust("59 minutes")
+      yield* bus.publish(SessionEvent.Execution.Succeeded, { sessionID }, { location: ref })
+      yield* TestClock.adjust("1 minute")
+      expect(Array.from(yield* RcMap.keys(locations.rcMap))).toEqual([ref])
+      yield* TestClock.adjust("59 minutes")
+      expect(Array.from(yield* RcMap.keys(locations.rcMap))).toEqual([])
+    }),
+  )
+
   it.live("retries a location after its missing directory is recreated", () =>
     Effect.acquireRelease(
       Effect.promise(() => tmpdir()),

packages/core/test/models.test.ts

@@ -1,13 +1,14 @@
 import { describe, expect, test } from "bun:test"
 import { Money } from "@opencode-ai/schema/money"
-import { Effect, Layer, Ref } from "effect"
+import { Effect, Fiber, Layer, Ref, Scope, Stream } from "effect"
 import { HttpClient, HttpClientResponse } from "effect/unstable/http"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNodePlatform } from "@opencode-ai/util/effect/app-node-platform"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { Bus } from "@opencode-ai/core/bus"
 import { KV } from "@opencode-ai/core/kv"
 import { Model } from "@opencode-ai/core/model"
-import { ModelsDev } from "@opencode-ai/core/models-dev"
+import { bodyDigest, ModelsDev } from "@opencode-ai/core/models-dev"
 import { Provider } from "@opencode-ai/core/provider"
 import { it } from "./lib/effect"
 
@@ -180,7 +181,7 @@ const buildLayer = (state: Ref.Ref<MockState>, cache: MockCache, options: Models
   // and Effect.provide uses a process-global MemoMap by default — without fresh,
   // every test would reuse the cachedInvalidateWithTTL state from the first run.
   Layer.fresh(
-    AppNodeBuilder.build(ModelsDev.node, [
+    AppNodeBuilder.build(LayerNode.group([ModelsDev.node, Bus.node]), [
       [ModelsDev.node, ModelsDev.configured(options)],
       [LayerNodePlatform.httpClient, Layer.succeed(HttpClient.HttpClient, makeMockClient(state))],
       [KV.node, makeMockKV(cache)],
@@ -199,13 +200,16 @@ const makeFailingWriteKV = (cache: MockCache) =>
 const makeCache = (): MockCache => ({ values: new Map() })
 
 const writeCacheText = (cache: MockCache, text: string, updatedAt = Date.now()) =>
-  cache.values.set(cacheKey, { updatedAt, body: text })
+  cache.values.set(cacheKey, { updatedAt, digest: bodyDigest(text), body: text })
 
 const writeCache = (cache: MockCache, data: object, updatedAt?: number) =>
   writeCacheText(cache, JSON.stringify(data), updatedAt)
 
-const provided = <A, E>(state: Ref.Ref<MockState>, cache: MockCache, eff: Effect.Effect<A, E, ModelsDev.Service>) =>
-  eff.pipe(Effect.provide(buildLayer(state, cache)))
+const provided = <A, E>(
+  state: Ref.Ref<MockState>,
+  cache: MockCache,
+  eff: Effect.Effect<A, E, ModelsDev.Service | Bus.Service | Scope.Scope>,
+) => eff.pipe(Effect.provide(buildLayer(state, cache)))
 
 const initialState: MockState = {
   body: JSON.stringify(fixture),
@@ -391,7 +395,20 @@ describe("ModelsDev Service", () => {
         cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
-          yield* svc.refresh(false)
+          const bus = yield* Bus.Service
+          const refreshed = yield* bus.subscribe(ModelsDev.Event.Refreshed).pipe(
+            Stream.take(1),
+            Stream.runCollect,
+            Effect.forkScoped,
+            Effect.flatMap((fiber) =>
+              Effect.gen(function* () {
+                yield* Effect.yieldNow
+                yield* svc.refresh(false)
+                return yield* Fiber.join(fiber)
+              }),
+            ),
+          )
+          expect(refreshed.length).toBe(1)
           return yield* svc.get()
         }),
       )
@@ -401,6 +418,72 @@ describe("ModelsDev Service", () => {
     }),
   )
 
+  it.live("refresh(false) stays quiet when the fetched body matches the cached digest", () =>
+    Effect.gen(function* () {
+      const cache = makeCache()
+      writeCache(cache, fixture, Date.now() - 10 * 60 * 1000)
+      const seeded = structuredClone(cache.values.get(cacheKey))
+      // The server serves a byte-identical body, so the refresh still hits
+      // the network but must not rewrite the cache or publish Refreshed.
+      const state = yield* Ref.make(initialState)
+      yield* provided(
+        state,
+        cache,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          const bus = yield* Bus.Service
+          const event = yield* bus.subscribe(ModelsDev.Event.Refreshed).pipe(
+            Stream.take(1),
+            Stream.runCollect,
+            Effect.forkScoped,
+            Effect.flatMap((fiber) =>
+              Effect.gen(function* () {
+                yield* Effect.yieldNow
+                yield* svc.refresh(false)
+                return yield* Fiber.join(fiber).pipe(Effect.timeoutOption("50 millis"))
+              }),
+            ),
+          )
+          expect(event._tag).toBe("None")
+        }),
+      )
+      const final = yield* Ref.get(state)
+      expect(final.calls.length).toBe(1)
+      expect(cache.values.get(cacheKey)).toEqual(seeded)
+    }),
+  )
+
+  it.live("refresh(false) republishes once for legacy cache entries without a digest", () =>
+    Effect.gen(function* () {
+      const cache = makeCache()
+      cache.values.set(cacheKey, { updatedAt: Date.now() - 10 * 60 * 1000, body: JSON.stringify(fixture) })
+      const state = yield* Ref.make(initialState)
+      yield* provided(
+        state,
+        cache,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          const bus = yield* Bus.Service
+          const refreshed = yield* bus.subscribe(ModelsDev.Event.Refreshed).pipe(
+            Stream.take(1),
+            Stream.runCollect,
+            Effect.forkScoped,
+            Effect.flatMap((fiber) =>
+              Effect.gen(function* () {
+                yield* Effect.yieldNow
+                yield* svc.refresh(false)
+                return yield* Fiber.join(fiber)
+              }),
+            ),
+          )
+          expect(refreshed.length).toBe(1)
+        }),
+      )
+      // The rewritten entry now carries a digest, so later identical bodies stay quiet.
+      expect(cache.values.get(cacheKey)).toMatchObject({ digest: bodyDigest(JSON.stringify(fixture)) })
+    }),
+  )
+
   it.live("refresh swallows HTTP errors and leaves cache intact", () =>
     Effect.gen(function* () {
       const cache = makeCache()

packages/server/src/routes.ts

@@ -20,6 +20,7 @@ import { MCP } from "@opencode-ai/core/mcp/index"
 import { Global } from "@opencode-ai/util/global"
 import { InstructionDiscovery } from "@opencode-ai/core/instruction-discovery"
 import { LocationServiceMap } from "@opencode-ai/core/location-service-map"
+import { LocationActivity } from "@opencode-ai/core/location-activity"
 import { ModelsDev } from "@opencode-ai/core/models-dev"
 import { SessionRestart } from "@opencode-ai/core/session/execution/restart"
 import { PluginRuntime } from "@opencode-ai/core/plugin/runtime"
@@ -62,6 +63,7 @@ const applicationServiceNodes = [
   WellKnown.node,
   PtyEnvironment.node,
   LocationServiceMap.node,
+  LocationActivity.node,
   SessionRestart.node,
 ] as const
 const applicationServices = LayerNode.group(applicationServiceNodes)

packages/tui/src/app.tsx

@@ -486,6 +486,7 @@ function App(props: { pair?: DialogPairCredentials }) {
     if (route.data.type !== "session") return
     const session = data.session.get(route.data.sessionID)
     if (!session) return
+    if (data.session.creating(session.id)) return
     if (session.location.workspaceID !== undefined || terminalEnvironment.variables === undefined) return
     void client.api.session
       .environment({ sessionID: session.id, variables: terminalEnvironment.variables })

packages/tui/src/component/prompt/autocomplete.tsx

@@ -956,7 +956,7 @@ export function Autocomplete(props: {
                     fg={index === store.selected ? theme.text.action.primary.focused : theme.text.subdued}
                     wrapMode="none"
                   >
-                    {" " + option().description?.trimStart()}
+                    {" " + option().description?.replace(/\s+/g, " ").trim()}
                   </text>
                 </Show>
               </box>

packages/tui/src/context/session-tabs.tsx

@@ -29,8 +29,8 @@ import {
 
 type TabsState = {
   tabs: SessionTab[]
-  // Read only long enough to remove the former client-owned state from persisted tab files.
-  unread?: Record<string, unknown>
+  // Kept empty for rollback compatibility with clients that still read this field.
+  unread: Record<string, unknown>
 }
 
 type PersistedState = {
@@ -43,7 +43,7 @@ type ScrollAnchor = {
   screenY: number
 }
 
-const empty = (): TabsState => ({ tabs: [] })
+const empty = (): TabsState => ({ tabs: [], unread: {} })
 
 // Deliberately after connect settles: the visible session's mount syncs win the first slots.
 const TAB_PREFETCH_DELAY = 300
@@ -128,6 +128,7 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
         const sessionID = root(tab.sessionID)
         return openSessionTab(tabs, { sessionID, title: title(sessionID, tab.title) })
       }, []),
+      unread: {},
     })
     const current = () => (route.data.type === "session" ? root(route.data.sessionID) : undefined)
     const newTab = createMemo((open = false) => {
@@ -219,7 +220,7 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
       update((draft) => {
         const next = normalize(draft)
         draft.tabs = next.tabs
-        delete draft.unread
+        draft.unread = next.unread
       })
     })
 

packages/tui/src/feature-plugins/system/storybook/session-tabs.tsx

@@ -6,13 +6,24 @@ import { EMPTY_SESSION_TAB_STATUS, SessionTabs, type SessionTabsController } fro
 import { closeSessionTab, cycleSessionTab, moveSessionTab } from "../../../context/session-tabs-model"
 import { StoryFooter } from "./footer"
 import type { Story } from "./index"
+import { projectName } from "../../../util/project"
 
 type FixtureStatus = ReturnType<SessionTabsController["status"]>
 
 const FIXTURE_TABS = [
   { sessionID: "fixture-1", title: "Implement session tabs", project: "opencode" },
-  { sessionID: "fixture-2", title: "Investigate rendering", project: "opencode" },
-  { sessionID: "fixture-3", title: "A deliberately long session title for truncation", project: "opencode-slack" },
+  {
+    sessionID: "fixture-2",
+    title: "Investigate rendering",
+    canonical: "C:\\",
+    directory: "C:\\Users\\demo\\Desktop\\Prabha",
+  },
+  {
+    sessionID: "fixture-3",
+    title: "A deliberately long session title for truncation",
+    canonical: "D:\\",
+    directory: "D:\\work\\notes",
+  },
   { sessionID: "fixture-4", title: "Fix provider state", project: "opencode" },
   { sessionID: "fixture-5", title: "Review animation", project: "opencode-slack" },
   { sessionID: "fixture-6", title: "Untitled behavior", project: "opencode-drive" },
@@ -98,7 +109,10 @@ function SessionTabsStory(props: { context: Plugin.Context }) {
     current: active,
     add: addTab,
     detail(sessionID) {
-      return FIXTURE_TABS.find((tab) => tab.sessionID === sessionID)?.project
+      const tab = FIXTURE_TABS.find((tab) => tab.sessionID === sessionID)
+      if (!tab) return
+      if ("project" in tab) return tab.project
+      return projectName({ canonical: tab.canonical }, tab.directory)
     },
     status(sessionID) {
       return statuses()[sessionID] ?? EMPTY_SESSION_TAB_STATUS

packages/tui/src/util/project.ts

@@ -2,6 +2,7 @@ import path from "path"
 
 export function projectName(project?: { canonical: string; name?: string }, fallback = "") {
   const canonical = project?.canonical ?? fallback
-  if (canonical === "/") return fallback ? path.basename(fallback) : undefined
-  return project?.name || path.basename(canonical)
+  const paths = /^(?:[a-z]:[\\/]|\\\\)/i.test(canonical) ? path.win32 : path.posix
+  if (paths.parse(canonical).root === canonical) return fallback ? paths.basename(fallback) : undefined
+  return project?.name || paths.basename(canonical)
 }

packages/tui/test/context/session-tabs.test.tsx

@@ -265,10 +265,10 @@ test("stores session tabs for the current working directory by default", async (
     const file = path.join(setup.state, "test", "tui", "tabs.json")
     await wait(() => Bun.file(file).size > 0)
     const stored = await Bun.file(file).json()
-    expect(stored.global).toEqual({ tabs: [] })
+    expect(stored.global).toEqual({ tabs: [], unread: {} })
     expect(Object.keys(stored.cwd)).toEqual([directory])
     expect(stored.cwd[directory].tabs.map((tab: { sessionID: string }) => tab.sessionID)).toEqual(["first"])
-    expect(stored.cwd[directory]).not.toHaveProperty("unread")
+    expect(stored.cwd[directory].unread).toEqual({})
   } finally {
     await setup.destroy()
   }
@@ -336,14 +336,14 @@ test("acknowledges viewed sessions even when tabs are disabled", async () => {
   }
 })
 
-test("purges legacy persisted unread records", async () => {
+test("empties legacy persisted unread records for rollback compatibility", async () => {
   const setup = await renderSessionTabs("first", { persisted: ["first"] })
   try {
     const file = path.join(setup.state, "test", "tui", "tabs.json")
-    // Normalize rewrites the active scope; the legacy record must not survive it.
+    // Normalize rewrites the active scope; legacy values must not survive, but older clients require the field.
     await wait(async () => {
       const stored = await Bun.file(file).json()
-      return !("unread" in stored.cwd[directory])
+      return Object.keys(stored.cwd[directory].unread).length === 0
     })
   } finally {
     await setup.destroy()

packages/tui/test/util/project.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "bun:test"
+import { projectName } from "../../src/util/project"
+
+describe("projectName", () => {
+  test("falls back to the folder name for filesystem-root projects", () => {
+    expect(projectName({ canonical: "/" }, "/home/user/Prabha")).toBe("Prabha")
+    expect(projectName({ canonical: "C:\\" }, "C:\\Users\\user\\Desktop\\Prabha")).toBe("Prabha")
+  })
+
+  test("preserves backslashes in POSIX folder names", () => {
+    expect(projectName({ canonical: "/tmp/foo\\bar" })).toBe("foo\\bar")
+  })
+})

packages/www/.gitignore

@@ -1,4 +1,4 @@
-.blume/
+.astro/
+.wrangler/
 dist/
 node_modules/
-.blume-verify/

packages/www/AGENTS.md

@@ -1,22 +1,18 @@
-# Website and documentation guide
+# Website guide
 
 ## Structure
 
-- This package owns the `opencode.ai` website.
-- Add custom marketing routes as Astro files under `pages/`.
-- The whole project is mounted at `/v2/` by `deployment.base`, and documentation lives under `content/docs/` at `/v2/docs` through `basePath` in `blume.config.ts`.
-- Write documentation in MDX. Every page should have `title` and `description` frontmatter.
-- Use parenthesized content folders for sidebar groups that must not add a URL segment. Keep ungrouped top-level pages directly under `content/docs/`.
-- Put static files in `public/` and reference them with root-relative paths.
-- The API reference is generated from `openapi.json`; do not duplicate endpoint documentation as hand-written MDX.
-- Keep documentation aligned with the current packages.
+- This is a standard Astro website with a fully owned frontend.
+- Only `base` in `astro.config.ts` should know the deployment subpath. Use `import.meta.env.BASE_URL` everywhere else.
+- The documentation feature is self-contained under `src/docs/` and renders through the thin route in `src/pages/docs/`.
+- Do not add a documentation frontend framework; this package owns the UI directly.
+- Keep the installer route dynamic and `public/openapi.json` generated from `packages/protocol/openapi.json`.
 
 ## Local development
 
-- Run `bun dev` from this package and preview the site at `http://localhost:3000/v2/`.
-- Verify both custom marketing routes and documentation routes after changing shared navigation or layout code.
+- Run `bun dev` from this package and use the local URL printed by Astro.
 
 ## Validation
 
-- Run `bun typecheck`, `bun validate`, and `bun run build` from this package after documentation or configuration changes.
+- Run `bun typecheck`, `bun run check:generated`, and `bun run build` from this package after changes.
 - Treat validation and build errors as blockers.

packages/www/README.md

@@ -1,10 +1,13 @@
 # OpenCode website
 
-The OpenCode V2 website, powered by Blume and deployed with Wrangler at `https://opencode.ai/v2/`. Blume mounts the documentation at `/v2/docs`, and `https://v2.opencode.ai` redirects to the same deployment.
+The standard Astro website for OpenCode. The only deployment-specific path is the `base` setting in `astro.config.ts`; application code uses `import.meta.env.BASE_URL`.
 
-Wrangler deploys the site through Blume's Cloudflare server adapter. Documentation pages are prerendered, while custom dynamic routes and endpoints can run in the Worker. Production uses `opencode-www` at `opencode.ai/v2/`; dev uses `opencode-www-dev` at `dev.opencode.ai/v2/`. The `v2.opencode.ai` alias is handled by a Cloudflare Redirect Rule outside this project.
+- `src/pages/` owns website routes.
+- `src/docs/` is the self-contained documentation feature rendered under `/docs`.
+- `/install` proxies the current installer.
+- `/openapi.json` serves the generated OpenAPI specification.
 
-The `deploy-www` GitHub workflow deploys the `dev` branch to the dev Worker and the `v2` branch to the production Worker.
+The deployment currently sets `base: "/v2"`. The `v2.opencode.ai` alias is handled by a Cloudflare Redirect Rule outside this project.
 
 ## Development
 
@@ -14,12 +17,12 @@ From this directory, run:
 bun dev
 ```
 
-The site opens at `http://localhost:3000/v2/`; documentation is available at `http://localhost:3000/v2/docs`.
+The local URL includes the base configured in `astro.config.ts`.
 
 ## Verification
 
 ```bash
 bun typecheck
-bun validate
+bun run check:generated
 bun run build
 ```

packages/www/astro.config.ts

@@ -0,0 +1,56 @@
+import cloudflare from "@astrojs/cloudflare"
+import mdx from "@astrojs/mdx"
+import { unified } from "@astrojs/markdown-remark"
+import { defineConfig } from "astro/config"
+import remarkDocsLinks from "./src/docs/remark-links"
+
+const base = "/v2/"
+
+export default defineConfig({
+  site: process.env.CLOUDFLARE_ENV === "production" ? "https://opencode.ai" : "https://dev.opencode.ai",
+  base,
+  output: "server",
+  adapter: cloudflare({ imageService: "passthrough" }),
+  integrations: [mdx()],
+  markdown: {
+    processor: unified({ remarkPlugins: [[remarkDocsLinks, { base }]] }),
+    shikiConfig: {
+      themes: {
+        light: "github-light",
+        dark: "github-dark",
+      },
+      transformers: [
+        {
+          name: "code-block-title",
+          root(root) {
+            const title = this.options.meta?.__raw?.match(/title="([^"]+)"/)?.[1]
+            if (!title) return
+            const pre = root.children[0]
+            if (!pre || pre.type !== "element") return
+            root.children = [
+              {
+                type: "element",
+                tagName: "figure",
+                properties: { className: ["astro-code-figure"] },
+                children: [
+                  {
+                    type: "element",
+                    tagName: "figcaption",
+                    properties: { className: ["astro-code-title"] },
+                    children: [{ type: "text", value: title }],
+                  },
+                  pre,
+                ],
+              },
+            ]
+          },
+        },
+      ],
+    },
+  },
+  vite: {
+    server: {
+      allowedHosts: true,
+    },
+  },
+})

packages/www/blume.config.ts

@@ -1,71 +0,0 @@
-import { defineConfig } from "blume"
-
-export default defineConfig({
-  title: "OpenCode",
-  description: "The open source AI coding agent.",
-  basePath: "/docs",
-  logo: {
-    image: {
-      light: "/assets/logo-light.svg",
-      dark: "/assets/logo-dark.svg",
-      alt: "OpenCode",
-    },
-    text: "",
-    href: "/",
-  },
-  content: {
-    root: "content/docs",
-  },
-  github: {
-    owner: "anomalyco",
-    repo: "opencode",
-    branch: "v2",
-    dir: "packages/www",
-  },
-  theme: {
-    background: { dark: "#000000" },
-    fonts: {
-      body: { name: "Monaspace Neon", provider: "fontsource", weights: [400, 500, 600, 700], fallback: "mono" },
-      display: { name: "Monaspace Neon", provider: "fontsource", weights: [400, 500, 600, 700], fallback: "mono" },
-      mono: { name: "Monaspace Neon", provider: "fontsource", weights: [400, 500, 600, 700], fallback: "mono" },
-    },
-    mode: "dark",
-  },
-  navigation: {
-    tabs: [
-      { label: "Docs", path: "/" },
-      { label: "CLI", path: "/cli" },
-      { label: "Build", path: "/build" },
-      { label: "API", path: "/api" },
-    ],
-  },
-  markdown: {
-    code: {
-      icons: false,
-    },
-  },
-  openapi: {
-    enabled: true,
-    route: "/api",
-    spec: "./openapi.json",
-  },
-  seo: {
-    og: {
-      fonts: [{ name: "IBM Plex Mono", weight: [400, 600] }],
-      logo: "public/assets/logo-dark.svg",
-      palette: {
-        accent: "#b7b1b1",
-        background: "#131010",
-        border: "#343030",
-        foreground: "#f1ecec",
-        muted: "#b7b1b1",
-      },
-    },
-  },
-  deployment: {
-    adapter: "cloudflare",
-    base: "/v2/",
-    output: "server",
-    site: process.env.BLUME_ENV === "dev" ? "https://dev.opencode.ai" : "https://opencode.ai",
-  },
-})

packages/www/components.ts

@@ -1,12 +0,0 @@
-import { defineComponents } from "blume"
-import Breadcrumbs from "./components/Breadcrumbs.astro"
-import ThemeTokens from "./snippets/generated/theme-tokens.mdx"
-
-export default defineComponents({
-  layout: {
-    Breadcrumbs,
-  },
-  mdx: {
-    ThemeTokens,
-  },
-})

packages/www/components/Breadcrumbs.astro

@@ -1,2 +0,0 @@
----
----

packages/www/content/docs/(Configure)/meta.ts

@@ -1,24 +0,0 @@
-import { defineMeta } from "blume"
-
-export default defineMeta({
-  title: "Configure",
-  pages: [
-    "lsp",
-    "agents",
-    "models",
-    "skills",
-    "themes",
-    "commands",
-    "providers",
-    "snapshots",
-    "compaction",
-    "formatters",
-    "references",
-    "attachments",
-    "mcp-servers",
-    "permissions",
-    "instructions",
-    "sharing",
-    "warming",
-  ],
-})

packages/www/content/docs/build/meta.ts

@@ -1,6 +0,0 @@
-import { defineMeta } from "blume"
-
-export default defineMeta({
-  title: "Build",
-  pages: ["sdk", "index", "client", "plugins"],
-})

packages/www/content/docs/cli/(Configure)/meta.ts

@@ -1,6 +0,0 @@
-import { defineMeta } from "blume"
-
-export default defineMeta({
-  title: "Configure",
-  pages: ["theme", "plugins", "keybinds"],
-})

packages/www/content/docs/cli/meta.ts

@@ -1,6 +0,0 @@
-import { defineMeta } from "blume"
-
-export default defineMeta({
-  title: "Intro",
-  pages: ["index", "config", "configure", "providers"],
-})

packages/www/content/docs/meta.ts

@@ -1,5 +0,0 @@
-import { defineMeta } from "blume"
-
-export default defineMeta({
-  pages: ["cli", "build", "index", "config", "configure", "migrate-v1", "troubleshooting"],
-})

packages/www/package.json

@@ -4,25 +4,25 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "bun run generate && blume dev --host --port 3000",
-    "build": "bun run generate && blume build && bun script/prepare-cloudflare.ts",
+    "dev": "bun run generate && astro dev --host --port 3000",
+    "build": "bun run generate && astro build && bun script/pagefind.ts && bun run validate && bun script/prepare-cloudflare.ts",
     "deploy": "wrangler deploy --config dist/server/wrangler.json",
-    "generate": "bun script/generate-theme-tokens.ts && bun script/generate-openapi.ts",
-    "check:generated": "bun script/generate-theme-tokens.ts --check && bun script/generate-openapi.ts --check",
-    "typecheck": "blume check",
-    "validate": "blume validate",
-    "doctor": "blume doctor"
+    "generate": "bun script/generate-openapi.ts",
+    "check:generated": "bun script/generate-openapi.ts --check",
+    "validate": "bun script/validate-links.ts",
+    "typecheck": "astro check"
   },
   "dependencies": {
-    "blume": "1.5.1"
+    "@astrojs/mdx": "7.0.5",
+    "astro": "7.1.3"
   },
   "devDependencies": {
     "@astrojs/cloudflare": "14.1.4",
-    "@opencode-ai/theme": "workspace:*",
+    "@astrojs/check": "0.9.6",
+    "@astrojs/markdown-remark": "7.2.4",
     "@types/bun": "catalog:",
-    "astro": "7.1.3",
-    "effect": "catalog:",
-    "prettier": "3.6.2",
+    "pagefind": "1.5.2",
+    "typescript": "catalog:",
     "wrangler": "4.110.0"
   },
   "engines": {

packages/www/pages/index.astro

@@ -1,5 +0,0 @@
----
-export const prerender = false
-
-return Astro.redirect(`${import.meta.env.BASE_URL}docs`, 308)
----

packages/www/script/generate-theme-tokens.ts

@@ -1,136 +0,0 @@
-#!/usr/bin/env bun
-
-import { Schema, SchemaAST } from "effect"
-import { format } from "prettier"
-import { ThemeDefinition, ThemeDocument } from "@opencode-ai/theme/tui"
-
-const target = import.meta.dir + "/../snippets/generated/theme-tokens.mdx"
-const root = requireObject(ThemeDefinition.ast)
-const hue = requireObject(requireField(root, "hue").type)
-const hueNames = hue.propertySignatures.map((field) => String(field.name))
-const hueSteps = requireObject(requireField(hue, hueNames[0]).type).propertySignatures.map((field) =>
-  String(field.name),
-)
-const contexts = root.propertySignatures
-  .map((field) => String(field.name))
-  .filter((name) => name.startsWith("@context:"))
-const tokens = root.propertySignatures
-  .filter((field) => {
-    const name = String(field.name)
-    return name !== "hue" && name !== "categorical" && !name.startsWith("@context:")
-  })
-  .flatMap((field) => tokenPaths(field.type, String(field.name)))
-const groups = Map.groupBy(tokens, (token) =>
-  token
-    .split(".")
-    .slice(0, token.split(".").length > 2 ? 2 : 1)
-    .join("."),
-)
-const table = [...groups]
-  .map(([group, values]) => `| \`${group}\` | ${values.map((value) => `\`${value}\``).join("<br />")} |`)
-  .join("\n")
-const example = {
-  version: 2,
-  light: {
-    hue: {
-      accent: "$hue.purple",
-      interactive: "$hue.purple",
-    },
-    text: {
-      default: "$hue.neutral.900",
-    },
-    background: {
-      default: "#fafafa",
-    },
-  },
-  dark: {
-    mergeMode: true,
-    text: {
-      default: "$hue.neutral.100",
-    },
-    background: {
-      default: "#101014",
-    },
-  },
-} satisfies ThemeDocument
-Schema.decodeUnknownSync(ThemeDocument)(example)
-const output = await format(
-  `{/* Generated by packages/www/script/generate-theme-tokens.ts. Do not edit. */}
-
-\`\`\`json title="my-theme.json"
-${JSON.stringify(example, null, 2)}
-\`\`\`
-
-## Token reference
-
-This reference is generated from the Effect schema in
-\`@opencode-ai/theme/tui\`. Changes to the runtime schema update
-this section through \`bun run generate\`.
-
-### Hue tokens
-
-Every hue is a ${hueSteps.length}-step scale. Define a scale with all of these
-steps, or alias it to another hue with a value such as \`$hue.blue\`.
-
-| | Values |
-| --- | --- |
-| Hues | ${hueNames.map((name) => `\`${name}\``).join(", ")} |
-| Steps | ${hueSteps.map((step) => `\`${step}\``).join(", ")} |
-
-Reference a hue color as \`$hue.<name>.<step>\`, for example
-\`$hue.interactive.500\`.
-
-### Semantic tokens
-
-Semantic values can reference another token by prefixing its path with \`$\`,
-for example \`$text.default\`. Stateful tokens inherit their \`default\`
-value when a state is omitted.
-
-| Group | Tokens |
-| --- | --- |
-${table}
-
-### Contexts
-
-${contexts.map((context) => `\`${context}\``).join(" and ")} accept partial
-overrides of the semantic tokens above. Components apply these contexts to
-surfaces that need different contrast without changing the base theme.
-`,
-  { parser: "mdx", printWidth: 120, semi: false },
-)
-
-if (process.argv.includes("--check")) {
-  const current = await Bun.file(target).text()
-  if (current === output) process.exit(0)
-  console.error("Generated theme token documentation is stale. Run `bun run generate` from packages/www.")
-  process.exit(1)
-}
-
-await Bun.write(target, output)
-
-function requireObject(ast: SchemaAST.AST): SchemaAST.Objects {
-  if (SchemaAST.isObjects(ast)) return ast
-  if (SchemaAST.isUnion(ast)) {
-    const object = ast.types.map(findObject).find((value) => value !== undefined)
-    if (object) return object
-  }
-  throw new Error(`Expected an object schema, received ${ast._tag}`)
-}
-
-function findObject(ast: SchemaAST.AST): SchemaAST.Objects | undefined {
-  if (SchemaAST.isObjects(ast)) return ast
-  if (SchemaAST.isUnion(ast)) return ast.types.map(findObject).find((value) => value !== undefined)
-  if (SchemaAST.isSuspend(ast)) return findObject(ast.thunk())
-}
-
-function requireField(ast: SchemaAST.Objects, name: string) {
-  const field = ast.propertySignatures.find((field) => String(field.name) === name)
-  if (field) return field
-  throw new Error(`Theme schema field not found: ${name}`)
-}
-
-function tokenPaths(ast: SchemaAST.AST, prefix: string): string[] {
-  const object = findObject(ast)
-  if (!object || object.propertySignatures.length === 0) return [prefix]
-  return object.propertySignatures.flatMap((field) => tokenPaths(field.type, `${prefix}.${String(field.name)}`))
-}

packages/www/script/pagefind.ts

@@ -0,0 +1,5 @@
+import config from "../astro.config"
+
+const base = config.base?.replace(/\/$/, "") ?? ""
+
+await Bun.$`pagefind --site ${`dist/client${base}/docs`}`

packages/www/script/validate-links.ts

@@ -0,0 +1,39 @@
+import path from "node:path"
+
+const root = path.resolve(import.meta.dir, "../dist/client")
+const files = await Array.fromAsync(new Bun.Glob("**/*.html").scan({ cwd: root, absolute: true }))
+const failures = (
+  await Promise.all(
+    files.flatMap(async (file) => {
+      const html = await Bun.file(file).text()
+      const page = `https://opencode.local/${path.relative(root, file).replace(/index\.html$/, "")}`
+      return Promise.all(
+        Array.from(html.matchAll(/href="([^"]+)"/g), async (match) => {
+          const url = new URL(match[1], page)
+          if (url.origin !== "https://opencode.local") return
+
+          const targetPath = path.join(root, decodeURIComponent(url.pathname))
+          const target = (
+            await Promise.all(
+              [targetPath, path.join(targetPath, "index.html"), `${targetPath}.html`].map(async (candidate) =>
+                (await Bun.file(candidate).exists()) ? candidate : undefined,
+              ),
+            )
+          ).find((candidate) => candidate !== undefined)
+          if (!target) return `${path.relative(root, file)}: missing ${url.pathname}`
+          if (!url.hash || !target.endsWith(".html")) return
+
+          const id = decodeURIComponent(url.hash.slice(1))
+          if ((await Bun.file(target).text()).includes(`id="${id}"`)) return
+          return `${path.relative(root, file)}: missing ${url.pathname}${url.hash}`
+        }),
+      )
+    }),
+  )
+)
+  .flat(2)
+  .filter((failure) => failure !== undefined)
+
+if (failures.length === 0) process.exit(0)
+console.error([...new Set(failures)].sort().join("\n"))
+process.exit(1)

packages/www/snippets/generated/theme-tokens.mdx

@@ -1,79 +0,0 @@
-{/* Generated by packages/www/script/generate-theme-tokens.ts. Do not edit. */}
-
-```json title="my-theme.json"
-{
-  "version": 2,
-  "light": {
-    "hue": {
-      "accent": "$hue.purple",
-      "interactive": "$hue.purple"
-    },
-    "text": {
-      "default": "$hue.neutral.900"
-    },
-    "background": {
-      "default": "#fafafa"
-    }
-  },
-  "dark": {
-    "mergeMode": true,
-    "text": {
-      "default": "$hue.neutral.100"
-    },
-    "background": {
-      "default": "#101014"
-    }
-  }
-}
-```
-
-## Token reference
-
-This reference is generated from the Effect schema in
-`@opencode-ai/theme/tui`. Changes to the runtime schema update
-this section through `bun run generate`.
-
-### Hue tokens
-
-Every hue is a 9-step scale. Define a scale with all of these
-steps, or alias it to another hue with a value such as `$hue.blue`.
-
-|       | Values                                                                                                   |
-| ----- | -------------------------------------------------------------------------------------------------------- |
-| Hues  | `gray`, `red`, `orange`, `yellow`, `green`, `cyan`, `blue`, `purple`, `accent`, `interactive`, `neutral` |
-| Steps | `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`                                            |
-
-Reference a hue color as `$hue.<name>.<step>`, for example
-`$hue.interactive.500`.
-
-### Semantic tokens
-
-Semantic values can reference another token by prefixing its path with `$`,
-for example `$text.default`. Stateful tokens inherit their `default`
-value when a state is omitted.
-
-| Group                  | Tokens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `text`                 | `text.default`<br />`text.subdued`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `text.action`          | `text.action.primary.default`<br />`text.action.primary.$hovered`<br />`text.action.primary.$focused`<br />`text.action.primary.$pressed`<br />`text.action.primary.$selected`<br />`text.action.primary.$disabled`<br />`text.action.secondary.default`<br />`text.action.secondary.$hovered`<br />`text.action.secondary.$focused`<br />`text.action.secondary.$pressed`<br />`text.action.secondary.$selected`<br />`text.action.secondary.$disabled`<br />`text.action.destructive.default`<br />`text.action.destructive.$hovered`<br />`text.action.destructive.$focused`<br />`text.action.destructive.$pressed`<br />`text.action.destructive.$selected`<br />`text.action.destructive.$disabled`                                                                                                             |
-| `text.formfield`       | `text.formfield.default`<br />`text.formfield.$hovered`<br />`text.formfield.$focused`<br />`text.formfield.$pressed`<br />`text.formfield.$selected`<br />`text.formfield.$disabled`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `text.feedback`        | `text.feedback.error.default`<br />`text.feedback.error.subdued`<br />`text.feedback.warning.default`<br />`text.feedback.warning.subdued`<br />`text.feedback.success.default`<br />`text.feedback.success.subdued`<br />`text.feedback.info.default`<br />`text.feedback.info.subdued`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `background`           | `background.default`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `background.surface`   | `background.surface.offset`<br />`background.surface.overlay`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `background.action`    | `background.action.primary.default`<br />`background.action.primary.$hovered`<br />`background.action.primary.$focused`<br />`background.action.primary.$pressed`<br />`background.action.primary.$selected`<br />`background.action.primary.$disabled`<br />`background.action.secondary.default`<br />`background.action.secondary.$hovered`<br />`background.action.secondary.$focused`<br />`background.action.secondary.$pressed`<br />`background.action.secondary.$selected`<br />`background.action.secondary.$disabled`<br />`background.action.destructive.default`<br />`background.action.destructive.$hovered`<br />`background.action.destructive.$focused`<br />`background.action.destructive.$pressed`<br />`background.action.destructive.$selected`<br />`background.action.destructive.$disabled` |
-| `background.formfield` | `background.formfield.default`<br />`background.formfield.$hovered`<br />`background.formfield.$focused`<br />`background.formfield.$pressed`<br />`background.formfield.$selected`<br />`background.formfield.$disabled`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `background.feedback`  | `background.feedback.error.default`<br />`background.feedback.warning.default`<br />`background.feedback.success.default`<br />`background.feedback.info.default`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `border`               | `border.default`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `scrollbar`            | `scrollbar.default`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `diff.text`            | `diff.text.added`<br />`diff.text.removed`<br />`diff.text.context`<br />`diff.text.hunkHeader`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `diff.background`      | `diff.background.added`<br />`diff.background.removed`<br />`diff.background.context`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `diff.highlight`       | `diff.highlight.added`<br />`diff.highlight.removed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `diff.lineNumber`      | `diff.lineNumber.text`<br />`diff.lineNumber.background.added`<br />`diff.lineNumber.background.removed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `syntax`               | `syntax.comment`<br />`syntax.keyword`<br />`syntax.function`<br />`syntax.variable`<br />`syntax.string`<br />`syntax.number`<br />`syntax.type`<br />`syntax.operator`<br />`syntax.punctuation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `markdown`             | `markdown.text`<br />`markdown.heading`<br />`markdown.link`<br />`markdown.linkText`<br />`markdown.code`<br />`markdown.blockQuote`<br />`markdown.emphasis`<br />`markdown.strong`<br />`markdown.horizontalRule`<br />`markdown.listItem`<br />`markdown.listEnumeration`<br />`markdown.image`<br />`markdown.imageText`<br />`markdown.codeBlock`                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-
-### Contexts
-
-`@context:elevated` and `@context:overlay` accept partial
-overrides of the semantic tokens above. Components apply these contexts to
-surfaces that need different contrast without changing the base theme.

packages/www/src/content.config.ts

@@ -0,0 +1,25 @@
+import { defineCollection } from "astro:content"
+import { glob } from "astro/loaders"
+import { z } from "astro/zod"
+
+export const collections = {
+  docs: defineCollection({
+    loader: glob({
+      base: "./src/docs/content",
+      pattern: "**/*.{md,mdx}",
+    }),
+    schema: z.object({
+      title: z.string(),
+      description: z.string().optional(),
+      tableOfContents: z
+        .union([
+          z.boolean(),
+          z.object({
+            minHeadingLevel: z.number().int().min(1).max(6).optional(),
+            maxHeadingLevel: z.number().int().min(1).max(6).optional(),
+          }),
+        ])
+        .optional(),
+    }),
+  }),
+}

packages/www/src/docs/AGENTS.md

@@ -0,0 +1,15 @@
+# Documentation feature guide
+
+## Structure
+
+- This folder owns the documentation data model, content, frontend, and styling.
+- Documentation content lives in `content/` and is loaded by `../content.config.ts`.
+- `lib/navigation.ts` is the source of truth for header sections and sidebar ordering.
+- The thin route entrypoints live in `../pages/docs/`; keep docs implementation details here.
+- Do not add a documentation frontend framework; this folder owns the UI directly.
+- Keep internal Markdown links docs-root-relative, for example `/config`; `remark-links.ts` applies the site and docs base paths.
+
+## Validation
+
+- Run `bun typecheck` and `bun run build` from `packages/www` after changes.
+- Check desktop and mobile layouts when changing navigation or shared styles.

packages/www/src/docs/components/Callout.astro

@@ -0,0 +1,14 @@
+---
+interface Props {
+  type?: "note" | "tip" | "warning"
+  title?: string
+}
+
+const type = Astro.props.type ?? "note"
+const title = Astro.props.title ?? (type === "tip" ? "Tip" : type === "warning" ? "Warning" : "Note")
+---
+
+<aside class={`callout callout-${type}`} aria-label={title}>
+  <strong>{title}</strong>
+  <div><slot /></div>
+</aside>

packages/www/src/docs/components/Card.astro

@@ -0,0 +1,15 @@
+---
+interface Props {
+  title: string
+  href: string
+}
+
+const href = Astro.props.href.startsWith("/")
+  ? `${import.meta.env.BASE_URL}docs${Astro.props.href}`
+  : Astro.props.href
+---
+
+<a class="docs-card" href={href}>
+  <strong>{Astro.props.title}</strong>
+  <div><slot /></div>
+</a>

packages/www/src/docs/components/CardGroup.astro

@@ -0,0 +1,9 @@
+---
+interface Props {
+  cols?: number
+}
+---
+
+<div class="docs-card-group" style={`--card-columns: ${Astro.props.cols ?? 2}`}>
+  <slot />
+</div>

packages/www/src/docs/components/CodeBlock.astro

@@ -0,0 +1,20 @@
+---
+interface Props {
+  code: string
+}
+---
+
+<div class="docs-code-block">
+  <pre><code>{Astro.props.code}</code></pre>
+  <button type="button" data-copy-code data-code={Astro.props.code}>Copy</button>
+</div>
+
+<script>
+  document.addEventListener("click", async (event) => {
+    const button = event.target
+    if (!(button instanceof HTMLButtonElement) || !button.matches("[data-copy-code]")) return
+    await navigator.clipboard.writeText(button.dataset.code ?? "")
+    button.textContent = "Copied"
+    window.setTimeout(() => (button.textContent = "Copy"), 1500)
+  })
+</script>

packages/www/src/docs/components/DocsHeader.astro

@@ -0,0 +1,118 @@
+---
+import { docsHref, docsSections } from "../lib/navigation"
+
+interface Props {
+  currentSlug: string
+}
+
+const currentSlug = Astro.props.currentSlug
+const searchEnabled = import.meta.env.PROD
+---
+
+<header class="site-header">
+  <div class="header-inner">
+    <a class="brand" href={import.meta.env.BASE_URL} aria-label="OpenCode home">
+      <img src={`${import.meta.env.BASE_URL}assets/logo-dark.svg`} alt="OpenCode" />
+    </a>
+    <nav aria-label="Documentation sections">
+      {
+        docsSections.map((section) => (
+          <a href={docsHref(section.landingSlug)} aria-current={currentSlug === section.key || currentSlug.startsWith(`${section.key}/`) || (section.key === "docs" && !currentSlug.includes("/") && currentSlug !== "api") ? "page" : undefined}>
+            {section.title}
+          </a>
+        ))
+      }
+    </nav>
+    <div class="header-spacer"></div>
+    {
+      searchEnabled && (
+        <button class="search-trigger" type="button" data-search-open aria-label="Search documentation">
+          <span>Search</span><kbd>⌘K</kbd>
+        </button>
+      )
+    }
+    <a class="github-link" href="https://github.com/anomalyco/opencode" aria-label="OpenCode on GitHub">GitHub</a>
+  </div>
+</header>
+
+{
+  searchEnabled && (
+    <dialog
+      class="search-dialog"
+      data-search-dialog
+      data-pagefind-path={`${import.meta.env.BASE_URL}docs/pagefind/pagefind.js`}
+      data-base-url={`${import.meta.env.BASE_URL}docs/`}
+      aria-label="Search documentation"
+    >
+      <form method="dialog" class="search-bar">
+        <span aria-hidden="true">&gt;</span>
+        <input data-search-input type="search" placeholder="Search docs" autocomplete="off" />
+        <button type="submit" aria-label="Close search">Esc</button>
+      </form>
+      <div class="search-results" data-search-results>
+        <p>Start typing to search the documentation.</p>
+      </div>
+    </dialog>
+  )
+}
+
+<script is:inline>
+  let pagefind
+
+  document.addEventListener("keydown", (event) => {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+      event.preventDefault()
+      const dialog = document.querySelector("[data-search-dialog]")
+      dialog?.showModal()
+      dialog?.querySelector("[data-search-input]")?.focus()
+    }
+  })
+
+  const setupSearch = () => {
+    const dialog = document.querySelector("[data-search-dialog]")
+    const input = document.querySelector("[data-search-input]")
+    const results = document.querySelector("[data-search-results]")
+    const trigger = document.querySelector("[data-search-open]")
+    if (trigger && !trigger.dataset.searchReady) {
+      trigger.dataset.searchReady = "true"
+      trigger.addEventListener("click", () => {
+        dialog?.showModal()
+        input?.focus()
+      })
+    }
+
+    if (input && results && !input.dataset.searchReady) input.addEventListener("input", async () => {
+      input.dataset.searchReady = "true"
+      const query = input.value.trim()
+      if (!query) {
+        results.innerHTML = "<p>Start typing to search the documentation.</p>"
+        return
+      }
+
+      const pagefindPath = dialog?.dataset.pagefindPath
+      if (!pagefindPath) return
+      const api = pagefind ?? (pagefind = await import(pagefindPath))
+      const search = await api.search(query)
+      const pages = await Promise.all(search.results.slice(0, 8).map((result) => result.data()))
+      results.replaceChildren(
+        ...pages.map((page) => {
+          const link = document.createElement("a")
+          const base = dialog.dataset.baseUrl ?? "/"
+          link.href = page.url.startsWith(base)
+            ? page.url
+            : `${dialog.dataset.baseUrl?.replace(/\/$/, "")}${page.url}`
+          const title = document.createElement("strong")
+          title.textContent = page.meta.title
+          const excerpt = document.createElement("span")
+          excerpt.innerHTML = page.excerpt
+          link.append(title, excerpt)
+          return link
+        }),
+      )
+      if (!pages.length) results.innerHTML = "<p>No results found.</p>"
+    })
+  }
+
+  setupSearch()
+  document.addEventListener("astro:page-load", setupSearch)
+</script>

packages/www/src/docs/components/DocsSidebar.astro

@@ -0,0 +1,27 @@
+---
+import { docsHref, type DocsNavGroup } from "../lib/navigation"
+
+interface Props {
+  groups: DocsNavGroup[]
+  currentSlug: string
+}
+---
+
+<nav class="docs-sidebar" aria-label="Documentation">
+  {
+    Astro.props.groups.map((group) => (
+      <section>
+        {group.title && <h2>{group.title}</h2>}
+        <ul>
+          {group.items.map((item) => (
+            <li>
+              <a href={docsHref(item.slug)} aria-current={item.slug === Astro.props.currentSlug ? "page" : undefined}>
+                {item.title}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </section>
+    ))
+  }
+</nav>

packages/www/src/docs/components/DocsTableOfContents.astro

@@ -0,0 +1,24 @@
+---
+import type { MarkdownHeading } from "astro"
+
+interface Props {
+  headings: MarkdownHeading[]
+}
+
+const headings = Astro.props.headings.filter((heading) => heading.depth === 2 || heading.depth === 3)
+---
+
+{
+  headings.length > 0 && (
+    <nav class="docs-toc" aria-label="On this page">
+      <h2>On this page</h2>
+      <ul>
+        {headings.map((heading) => (
+          <li class={heading.depth === 3 ? "nested" : undefined}>
+            <a href={`#${heading.slug}`}>{heading.text}</a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}