refactor(tui): remove redundant code (#40081)

Co-authored-by: Kit Langton <kit.langton@gmail.com>

AGENTS.md

@@ -4,6 +4,13 @@
 - The default branch in this repo is `dev`.
 - Local `main` ref may not exist; use `dev` or `origin/dev` for diffs.
 
+## Live V2 TUI Testing
+
+- Run `bun run dev:live` from a development worktree to test its TUI against the currently elected `opencode2` background server and live sessions.
+- Pass a directory after the script when needed, for example `bun run dev:live /path/to/project`.
+- The script discovers the server with `opencode2 service status`, injects its private local credential from `opencode2 service get password`, and uses the `next` TUI storage channel so tabs and other client-local state match the installed client.
+- Prefer `dev:live` over plain `bun run dev` for this workflow. An implicit managed-service connection may replace the live server when the worktree client version differs; explicit `--server` warns and continues without replacing it.
+
 ## Branch Names
 
 Use a short branch name of at most three words, separated by hyphens. Do not use slashes or type prefixes such as `feat/` or `fix/`.

bun.lock

@@ -64,8 +64,10 @@
         "@opencode-ai/client": "workspace:*",
         "@opencode-ai/core": "workspace:*",
         "@opencode-ai/schema": "workspace:*",
+        "@opencode-ai/sdk": "file:vendor/opencode-ai-sdk-1.18.8-dev.tgz",
         "@opencode-ai/session-ui": "workspace:*",
         "@opencode-ai/ui": "workspace:*",
+        "@opencode-ai/util": "workspace:*",
         "@pierre/trees": "1.0.0-beta.4",
         "@sentry/solid": "catalog:",
         "@shikijs/transformers": "3.9.2",
@@ -86,7 +88,6 @@
         "@tanstack/solid-query": "5.91.4",
         "@tanstack/solid-virtual": "catalog:",
         "@thisbeyond/solid-dnd": "0.7.5",
-        "diff": "catalog:",
         "effect": "catalog:",
         "fuzzysort": "catalog:",
         "ghostty-web": "github:anomalyco/ghostty-web#83c0a07b8628b748aed073b232cb4b52a6ca11c1",
@@ -142,7 +143,10 @@
         "open": "10.1.2",
         "semver": "catalog:",
         "solid-js": "catalog:",
+        "tree-sitter-bash": "0.25.0",
+        "tree-sitter-powershell": "0.25.10",
         "uqr": "0.1.3",
+        "web-tree-sitter": "0.25.10",
         "ws": "8.21.0",
       },
       "devDependencies": {
@@ -379,7 +383,6 @@
         "@opencode-ai/ai": "workspace:*",
         "@opencode-ai/codemode": "workspace:*",
         "@opencode-ai/effect-drizzle-sqlite": "workspace:*",
-        "@opencode-ai/effect-sqlite-node": "workspace:*",
         "@opencode-ai/plugin": "workspace:*",
         "@opencode-ai/schema": "workspace:*",
         "@opencode-ai/util": "workspace:*",
@@ -400,7 +403,6 @@
         "ignore": "7.0.5",
         "immer": "11.1.4",
         "jsonc-parser": "3.3.1",
-        "semver": "^7.6.3",
         "tree-sitter-bash": "0.25.0",
         "tree-sitter-powershell": "0.25.10",
         "turndown": "7.2.0",
@@ -422,7 +424,6 @@
         "@tsconfig/bun": "catalog:",
         "@types/bun": "catalog:",
         "@types/node": "catalog:",
-        "@types/semver": "catalog:",
         "@types/turndown": "5.0.5",
         "@types/which": "3.0.4",
         "drizzle-kit": "catalog:",
@@ -516,6 +517,7 @@
         "@opencode-ai/core": "workspace:*",
         "@opencode-ai/session-ui": "workspace:*",
         "@opencode-ai/ui": "workspace:*",
+        "@opencode-ai/util": "workspace:*",
         "@pierre/diffs": "catalog:",
         "@solidjs/meta": "catalog:",
         "@solidjs/router": "catalog:",
@@ -6338,6 +6340,8 @@
 
     "@openauthjs/openauth/jose": ["jose@5.9.6", "", {}, "sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ=="],
 
+    "@opencode-ai/app/@opencode-ai/sdk": ["@opencode-ai/sdk@vendor/opencode-ai-sdk-1.18.8-dev.tgz", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-C2nfk4x0sPINwE5V6DPkFSuH3PkUmKPWHPzxpXC1j+3Ui5hslLCWJbkk8WcOG1Lyt3C0+yp4ea64v/kmtYCO4w=="],
+
     "@opencode-ai/cli/semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
 
     "@opencode-ai/console-app/@smithy/eventstream-codec": ["@smithy/eventstream-codec@4.2.7", "", { "dependencies": { "@aws-crypto/crc32": "5.2.0", "@smithy/types": "^4.11.0", "@smithy/util-hex-encoding": "^4.2.0", "tslib": "^2.6.2" } }, "sha512-DrpkEoM3j9cBBWhufqBwnbbn+3nf1N9FP6xuVJ+e220jbactKuQgaZwjwP5CP1t+O94brm2JgVMD2atMGX3xIQ=="],

package.json

@@ -8,6 +8,7 @@
   "packageManager": "bun@1.3.14",
   "scripts": {
     "dev": "bun run --cwd packages/cli --conditions=browser src/index.ts",
+    "dev:live": "OPENCODE_TUI_CHANNEL=next OPENCODE_PASSWORD=\"$(opencode2 service get password)\" bun run dev --server \"$(opencode2 service status)\"",
     "dev:desktop": "bun --cwd packages/desktop dev",
     "dev:web": "bun --cwd packages/app dev",
     "dev:console": "ulimit -n 10240 2>/dev/null; bun run --cwd packages/console/app dev",

packages/ai/AGENTS.md

@@ -12,6 +12,8 @@
 
 Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `Model.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, `LLM.updateRequest`, and `LLM.generateObject`. Two ways to construct the same thing is one too many.
 
+- Keep provider-defined string enums forward-compatible. Expose known values for autocomplete while accepting future values with `Known | (string & {})`; use `Schema.String` at runtime unless rejecting unknown values is required for correctness.
+
 ## Tests
 
 - Use `testEffect(...)` from `test/lib/effect.ts` for tests requiring Effect layers.

packages/ai/src/cache-policy.ts

@@ -38,7 +38,7 @@ const resolve = (policy: CachePolicy | undefined): CachePolicyObject => {
 // Protocols whose wire format ignores inline cache markers (OpenAI's implicit
 // prefix caching, Gemini's implicit + out-of-band CachedContent). Skip the
 // whole policy pass for these — emitting hints would be harmless but pointless.
-const RESPECTS_INLINE_HINTS = new Set(["anthropic-messages", "bedrock-converse"])
+const RESPECTS_INLINE_HINTS = new Set(["anthropic-messages", "bedrock-converse", "openrouter"])
 
 const makeHint = (ttlSeconds: number | undefined): CacheHint =>
   ttlSeconds !== undefined ? new CacheHint({ type: "ephemeral", ttlSeconds }) : new CacheHint({ type: "ephemeral" })
@@ -133,6 +133,7 @@ const countHints = (request: LLMRequest) =>
 
 export const applyCachePolicy = (request: LLMRequest): LLMRequest => {
   if (!RESPECTS_INLINE_HINTS.has(request.model.route.id)) return request
+  if (request.model.route.id === "openrouter" && (request.cache === undefined || request.cache === "auto")) return request
   const policy = resolve(request.cache)
   if (!policy.tools && !policy.system && !policy.messages) return request
 

packages/ai/src/protocols/gemini.ts

@@ -29,9 +29,30 @@ export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1bet
 
 export interface OptionsInput {
   readonly [key: string]: unknown
+  readonly cachedContent?: string
+  readonly safetySettings?: ReadonlyArray<{
+    readonly category:
+      | "HARM_CATEGORY_UNSPECIFIED"
+      | "HARM_CATEGORY_HATE_SPEECH"
+      | "HARM_CATEGORY_DANGEROUS_CONTENT"
+      | "HARM_CATEGORY_HARASSMENT"
+      | "HARM_CATEGORY_SEXUALLY_EXPLICIT"
+      | "HARM_CATEGORY_CIVIC_INTEGRITY"
+      | (string & {})
+    readonly threshold:
+      | "HARM_BLOCK_THRESHOLD_UNSPECIFIED"
+      | "BLOCK_LOW_AND_ABOVE"
+      | "BLOCK_MEDIUM_AND_ABOVE"
+      | "BLOCK_ONLY_HIGH"
+      | "BLOCK_NONE"
+      | "OFF"
+      | (string & {})
+  }>
+  readonly serviceTier?: "standard" | "flex" | "priority" | (string & {})
   readonly thinkingConfig?: {
     readonly thinkingBudget?: number
     readonly includeThoughts?: boolean
+    readonly thinkingLevel?: "minimal" | "low" | "medium" | "high" | (string & {})
   }
 }
 
@@ -111,6 +132,12 @@ const GeminiToolConfig = Schema.Struct({
 const GeminiThinkingConfig = Schema.Struct({
   thinkingBudget: Schema.optional(Schema.Number),
   includeThoughts: Schema.optional(Schema.Boolean),
+  thinkingLevel: Schema.optional(Schema.String),
+})
+
+const GeminiSafetySetting = Schema.Struct({
+  category: Schema.String,
+  threshold: Schema.String,
 })
 
 const GeminiGenerationConfig = Schema.Struct({
@@ -123,7 +150,10 @@ const GeminiGenerationConfig = Schema.Struct({
 })
 
 const GeminiBodyFields = {
+  cachedContent: Schema.optional(Schema.String),
   contents: Schema.Array(GeminiContent),
+  safetySettings: optionalArray(GeminiSafetySetting),
+  serviceTier: Schema.optional(Schema.String),
   systemInstruction: Schema.optional(GeminiSystemInstruction),
   tools: optionalArray(GeminiTool),
   toolConfig: Schema.optional(GeminiToolConfig),
@@ -316,17 +346,38 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
 })
 
 const resolveOptions = (request: LLMRequest) => {
-  const value = request.providerOptions?.gemini?.thinkingConfig
-  if (!ProviderShared.isRecord(value)) return {}
+  const input = request.providerOptions?.gemini
+  const value = input?.thinkingConfig
   const thinkingConfig = {
-    thinkingBudget: typeof value.thinkingBudget === "number" ? value.thinkingBudget : undefined,
-    includeThoughts: typeof value.includeThoughts === "boolean" ? value.includeThoughts : undefined,
+    thinkingBudget:
+      ProviderShared.isRecord(value) && typeof value.thinkingBudget === "number" ? value.thinkingBudget : undefined,
+    includeThoughts:
+      ProviderShared.isRecord(value) && typeof value.includeThoughts === "boolean"
+        ? value.includeThoughts
+        : ProviderShared.isRecord(value)
+          ? true
+          : undefined,
+    thinkingLevel:
+      ProviderShared.isRecord(value) && typeof value.thinkingLevel === "string" ? value.thinkingLevel : undefined,
   }
   return {
+    cachedContent: typeof input?.cachedContent === "string" ? input.cachedContent : undefined,
+    safetySettings: mapSafetySettings(input?.safetySettings),
+    serviceTier: typeof input?.serviceTier === "string" ? input.serviceTier : undefined,
     thinkingConfig: Object.values(thinkingConfig).some((item) => item !== undefined) ? thinkingConfig : undefined,
   }
 }
 
+function mapSafetySettings(value: unknown) {
+  if (!Array.isArray(value)) return undefined
+  const settings = value.flatMap((item) =>
+    ProviderShared.isRecord(item) && typeof item.category === "string" && typeof item.threshold === "string"
+      ? [{ category: item.category, threshold: item.threshold }]
+      : [],
+  )
+  return settings
+}
+
 const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMRequest) {
   const hasTools = request.tools.length > 0
   const generation = request.generation
@@ -342,7 +393,10 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
   }
 
   return {
+    cachedContent: options.cachedContent,
     contents: yield* lowerMessages(request),
+    safetySettings: options.safetySettings,
+    serviceTier: options.serviceTier,
     systemInstruction:
       request.system.length === 0 ? undefined : { parts: [{ text: ProviderShared.joinText(request.system) }] },
     tools: hasTools

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

@@ -11,6 +11,7 @@ import {
   Usage,
   type FinishReason,
   type FinishReasonDetails,
+  type CacheHint,
   type JsonSchema,
   type LLMRequest,
   type MediaPart,
@@ -38,6 +39,11 @@ export const PATH = "/chat/completions"
 // The body schema is the provider-native JSON body. `fromRequest` below builds
 // this shape from the common `LLMRequest`, then `Route.make` validates and
 // JSON-encodes it before transport.
+const OpenAIChatCacheControl = Schema.Struct({
+  type: Schema.Literal("ephemeral"),
+  ttl: Schema.optional(Schema.String),
+})
+
 const OpenAIChatFunction = Schema.Struct({
   name: Schema.String,
   description: Schema.String,
@@ -47,6 +53,7 @@ const OpenAIChatFunction = Schema.Struct({
 const OpenAIChatTool = Schema.Struct({
   type: Schema.tag("function"),
   function: OpenAIChatFunction,
+  cache_control: Schema.optional(OpenAIChatCacheControl),
 })
 type OpenAIChatTool = Schema.Schema.Type<typeof OpenAIChatTool>
 
@@ -61,7 +68,11 @@ const OpenAIChatAssistantToolCall = Schema.Struct({
 type OpenAIChatAssistantToolCall = Schema.Schema.Type<typeof OpenAIChatAssistantToolCall>
 
 const OpenAIChatUserContent = Schema.Union([
-  Schema.Struct({ type: Schema.Literal("text"), text: Schema.String }),
+  Schema.Struct({
+    type: Schema.Literal("text"),
+    text: Schema.String,
+    cache_control: Schema.optional(OpenAIChatCacheControl),
+  }),
   Schema.Struct({
     type: Schema.Literal("image_url"),
     image_url: Schema.Struct({ url: Schema.String }),
@@ -69,7 +80,10 @@ const OpenAIChatUserContent = Schema.Union([
 ])
 
 const OpenAIChatMessage = Schema.Union([
-  Schema.Struct({ role: Schema.Literal("system"), content: Schema.String }),
+  Schema.Struct({
+    role: Schema.Literal("system"),
+    content: Schema.Union([Schema.String, Schema.Array(OpenAIChatUserContent)]),
+  }),
   Schema.Struct({
     role: Schema.Literal("user"),
     content: Schema.Union([Schema.String, Schema.Array(OpenAIChatUserContent)]),
@@ -83,10 +97,16 @@ const OpenAIChatMessage = Schema.Union([
       reasoning: Schema.optional(Schema.String),
       reasoning_text: Schema.optional(Schema.String),
       reasoning_details: Schema.optional(Schema.Unknown),
+      cache_control: Schema.optional(OpenAIChatCacheControl),
     }),
     [Schema.Record(Schema.String, Schema.Unknown)],
   ),
-  Schema.Struct({ role: Schema.Literal("tool"), tool_call_id: Schema.String, content: Schema.String }),
+  Schema.Struct({
+    role: Schema.Literal("tool"),
+    tool_call_id: Schema.String,
+    content: Schema.String,
+    cache_control: Schema.optional(OpenAIChatCacheControl),
+  }),
 ]).pipe(Schema.toTaggedUnion("role"))
 type OpenAIChatMessage = Schema.Schema.Type<typeof OpenAIChatMessage>
 
@@ -107,6 +127,7 @@ export const bodyFields = {
   stream_options: Schema.optional(Schema.Struct({ include_usage: Schema.Boolean })),
   store: Schema.optional(Schema.Boolean),
   reasoning_effort: Schema.optional(OpenAIOptions.OpenAIReasoningEffort),
+  max_completion_tokens: Schema.optional(Schema.Number),
   max_tokens: Schema.optional(Schema.Number),
   temperature: Schema.optional(Schema.Number),
   top_p: Schema.optional(Schema.Number),
@@ -209,13 +230,20 @@ export interface ParserState {
 // Lowering is the only place that knows how common LLM messages map onto the
 // OpenAI Chat wire format. Keep provider quirks here instead of leaking native
 // fields into `LLMRequest`.
-const lowerTool = (tool: ToolDefinition, inputSchema: JsonSchema): OpenAIChatTool => ({
+interface LoweringOptions {
+  readonly cacheControl?: (
+    cache: CacheHint | undefined,
+  ) => Schema.Schema.Type<typeof OpenAIChatCacheControl> | undefined
+}
+
+const lowerTool = (tool: ToolDefinition, inputSchema: JsonSchema, options: LoweringOptions): OpenAIChatTool => ({
   type: "function",
   function: {
     name: tool.name,
     description: tool.description,
     parameters: ToolSchemaProjection.openAI(inputSchema),
   },
+  cache_control: options.cacheControl?.(tool.cache),
 })
 
 const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
@@ -257,11 +285,14 @@ const reasoningDetails = (parts: ReadonlyArray<ReasoningPart>, native: unknown)
   if (isRecord(native) && Array.isArray(native.reasoning_details)) return native.reasoning_details
 }
 
-const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (message: OpenAIChatRequestMessage) {
+const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (
+  message: OpenAIChatRequestMessage,
+  options: LoweringOptions,
+) {
   const content: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
   for (const part of message.content) {
     if (part.type === "text") {
-      content.push({ type: "text", text: part.text })
+      content.push({ type: "text", text: part.text, cache_control: options.cacheControl?.(part.cache) })
       continue
     }
     if (part.type === "media") {
@@ -270,14 +301,18 @@ const lowerUserMessage = Effect.fn("OpenAIChat.lowerUserMessage")(function* (mes
     }
     return yield* ProviderShared.unsupportedContent("OpenAI Chat", "user", ["text", "media"])
   }
-  if (content.every((part) => part.type === "text"))
-    return { role: "user" as const, content: content.map((part) => part.text).join("") }
+  if (content.every((part) => part.type === "text" && part.cache_control === undefined))
+    return {
+      role: "user" as const,
+      content: content.map((part) => (part.type === "text" ? part.text : "")).join(""),
+    }
   return { role: "user" as const, content }
 })
 
 const lowerAssistantMessage = Effect.fn("OpenAIChat.lowerAssistantMessage")(function* (
   message: OpenAIChatRequestMessage,
   configuredField?: string,
+  options: LoweringOptions = {},
 ) {
   const content: TextPart[] = []
   const reasoning: ReasoningPart[] = []
@@ -315,29 +350,44 @@ const lowerAssistantMessage = Effect.fn("OpenAIChat.lowerAssistantMessage")(func
     if (reasoning.length === 0) return nativeReasoning
     return text
   })()
+  const cached = message.content.findLast((part) => "cache" in part && part.cache !== undefined)
   const result = {
     role: "assistant" as const,
     content: content.length === 0 ? null : ProviderShared.joinText(content),
     tool_calls: toolCalls.length === 0 ? undefined : toolCalls,
     reasoning_details: details,
+    cache_control: options.cacheControl?.(cached && "cache" in cached ? cached.cache : undefined),
   }
   if (field === undefined || reasoningText === undefined) return result
   return { ...result, [field]: reasoningText }
 })
 
-const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (message: OpenAIChatRequestMessage) {
+const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (
+  message: OpenAIChatRequestMessage,
+  options: LoweringOptions,
+) {
   const messages: OpenAIChatMessage[] = []
   const images: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
   for (const part of message.content) {
     if (!ProviderShared.supportsContent(part, ["tool-result"]))
       return yield* ProviderShared.unsupportedContent("OpenAI Chat", "tool", ["tool-result"])
     if (part.result.type !== "content") {
-      messages.push({ role: "tool", tool_call_id: part.id, content: ProviderShared.toolResultText(part) })
+      messages.push({
+        role: "tool",
+        tool_call_id: part.id,
+        content: ProviderShared.toolResultText(part),
+        cache_control: options.cacheControl?.(part.cache),
+      })
       continue
     }
     const content: ReadonlyArray<Tool.Content> = part.result.value
     const text = content.filter((item) => item.type === "text").map((item) => item.text)
-    messages.push({ role: "tool", tool_call_id: part.id, content: text.join("\n") })
+    messages.push({
+      role: "tool",
+      tool_call_id: part.id,
+      content: text.join("\n"),
+      cache_control: options.cacheControl?.(part.cache),
+    })
     const files = content.filter((item) => item.type === "file")
     images.push(
       ...(yield* Effect.forEach(files, (item) =>
@@ -351,15 +401,29 @@ const lowerToolMessages = Effect.fn("OpenAIChat.lowerToolMessages")(function* (m
 const lowerMessage = Effect.fn("OpenAIChat.lowerMessage")(function* (
   message: OpenAIChatRequestMessage,
   reasoningField?: string,
+  options: LoweringOptions = {},
 ) {
-  if (message.role === "user") return [yield* lowerUserMessage(message)]
-  if (message.role === "assistant") return [yield* lowerAssistantMessage(message, reasoningField)]
-  return (yield* lowerToolMessages(message)).messages
+  if (message.role === "user") return [yield* lowerUserMessage(message, options)]
+  if (message.role === "assistant") return [yield* lowerAssistantMessage(message, reasoningField, options)]
+  return (yield* lowerToolMessages(message, options)).messages
 })
 
-const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request: LLMRequest) {
+const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request: LLMRequest, options: LoweringOptions) {
   const system: OpenAIChatMessage[] =
-    request.system.length === 0 ? [] : [{ role: "system", content: ProviderShared.joinText(request.system) }]
+    request.system.length === 0
+      ? []
+      : request.system.some((part) => part.cache !== undefined) && options.cacheControl !== undefined
+        ? [
+            {
+              role: "system",
+              content: request.system.map((part) => ({
+                type: "text",
+                text: part.text,
+                cache_control: options.cacheControl?.(part.cache),
+              })),
+            },
+          ]
+        : [{ role: "system", content: ProviderShared.joinText(request.system) }]
   const messages = [...system]
   const pendingImages: Array<Schema.Schema.Type<typeof OpenAIChatUserContent>> = []
   const flushImages = () => {
@@ -370,28 +434,53 @@ const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request:
     if (message.role === "system") {
       const part = yield* ProviderShared.wrappedSystemUpdate("OpenAI Chat", message)
       if (pendingImages.length > 0) {
-        messages.push({ role: "user", content: [...pendingImages.splice(0), { type: "text", text: part.text }] })
+        messages.push({
+          role: "user",
+          content: [
+            ...pendingImages.splice(0),
+            { type: "text", text: part.text, cache_control: options.cacheControl?.(part.cache) },
+          ],
+        })
         continue
       }
       const previous = messages.at(-1)
       if (previous?.role === "user" && typeof previous.content === "string")
-        messages[messages.length - 1] = { role: "user", content: `${previous.content}\n${part.text}` }
+        messages[messages.length - 1] = options.cacheControl?.(part.cache)
+          ? {
+              role: "user",
+              content: [
+                { type: "text", text: previous.content },
+                { type: "text", text: part.text, cache_control: options.cacheControl(part.cache) },
+              ],
+            }
+          : { role: "user", content: `${previous.content}\n${part.text}` }
       else if (previous?.role === "user" && Array.isArray(previous.content))
         messages[messages.length - 1] = {
           role: "user",
-          content: [...previous.content, { type: "text", text: part.text }],
+          content: [
+            ...previous.content,
+            { type: "text", text: part.text, cache_control: options.cacheControl?.(part.cache) },
+          ],
         }
-      else messages.push({ role: "user", content: part.text })
+      else
+        messages.push(
+          options.cacheControl?.(part.cache)
+            ? {
+                role: "user",
+                content: [{ type: "text", text: part.text, cache_control: options.cacheControl(part.cache) }],
+              }
+            : { role: "user", content: part.text },
+        )
       continue
     }
     if (message.role === "tool") {
-      const lowered = yield* lowerToolMessages(message)
+      const lowered = yield* lowerToolMessages(message, options)
       messages.push(...lowered.messages)
       pendingImages.push(...lowered.images)
       continue
     }
     flushImages()
-    messages.push(...(yield* lowerMessage(message, request.model.compatibility?.reasoningField)))
+    messages.push(...(yield* lowerMessage(message, request.model.compatibility?.reasoningField, options)))
   }
   flushImages()
   return messages
@@ -405,7 +494,10 @@ const lowerOptions = (request: LLMRequest) => {
   }
 }
 
-const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (request: LLMRequest) {
+export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
+  request: LLMRequest,
+  options: LoweringOptions = {},
+) {
   // `fromRequest` returns the provider body only. Endpoint, auth, framing,
   // validation, and HTTP execution are composed by `Route.make`.
   const reasoningField = request.model.compatibility?.reasoningField
@@ -415,19 +507,26 @@ const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (request: LLMR
     )
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
+  const maxTokensField = request.model.compatibility?.maxTokensField ?? "max_tokens"
   return {
     model: request.model.id,
-    messages: yield* lowerMessages(request),
+    messages: yield* lowerMessages(request, options),
     tools:
       request.tools.length === 0
         ? undefined
         : request.tools.map((tool) =>
-            lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
+            lowerTool(
+              tool,
+              ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),
+              options,
+            ),
           ),
     tool_choice: request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined,
     stream: true as const,
     stream_options: { include_usage: true },
-    max_tokens: generation?.maxTokens,
+    ...(maxTokensField === "max_completion_tokens"
+      ? { max_completion_tokens: generation?.maxTokens }
+      : { max_tokens: generation?.maxTokens }),
     temperature: generation?.temperature,
     top_p: generation?.topP,
     frequency_penalty: generation?.frequencyPenalty,

packages/ai/src/provider-error.ts

@@ -16,7 +16,6 @@ import {
 
 const patterns = [
   /prompt is too long/i,
-  /request_too_large/i,
   /input is too long for requested model/i,
   /exceeds the context window/i,
   /exceeds (?:the )?(?:model'?s )?maximum context length(?: of [\d,]+ tokens?|\s*\([\d,]+\))/i,
@@ -33,7 +32,6 @@ const patterns = [
   /context window exceeds limit/i,
   /exceeded model token limit/i,
   /context[_ ]length[_ ]exceeded/i,
-  /request entity too large/i,
   /context length is only \d+ tokens/i,
   /input length.*exceeds.*context length/i,
   /prompt too long; exceeded (?:max )?context length/i,
@@ -44,11 +42,15 @@ const patterns = [
   /token limit exceeded/i,
 ]
 
+const payloadPatterns = [/request_too_large/i, /request entity too large/i, /payload too large/i, /request too large/i]
+
 const exclusions = [/^(throttling error|service unavailable):/i, /rate limit/i, /too many requests/i]
 
 export const isContextOverflow = (message: string) =>
   !exclusions.some((pattern) => pattern.test(message)) &&
-  (patterns.some((pattern) => pattern.test(message)) || /^4(00|13)\s*(status code)?\s*\(no body\)/i.test(message))
+  (patterns.some((pattern) => pattern.test(message)) || /^400\s*(status code)?\s*\(no body\)/i.test(message))
+
+export const isPayloadTooLarge = (message: string) => payloadPatterns.some((pattern) => pattern.test(message))
 
 export const isContextOverflowFailure = (failure: unknown) =>
   failure instanceof LLMError
@@ -100,6 +102,8 @@ export function classifyProviderFailure(input: ProviderFailure): LLMError["reaso
       isContextOverflow(text))
   )
     return new InvalidRequestReason({ ...common, classification: "context-overflow" })
+  if (input.status === 413 || isPayloadTooLarge(text))
+    return new InvalidRequestReason({ ...common, classification: "payload-too-large" })
   if (CONTENT_POLICY_TEXT.test(text)) return new ContentPolicyReason(common)
   if (codes.some((code) => QUOTA_CODES.has(code)) || (input.status === 429 && QUOTA_TEXT.test(text)))
     return new QuotaExceededReason(common)
@@ -142,12 +146,7 @@ export function classifyProviderFailure(input: ProviderFailure): LLMError["reaso
       retryAfterMs: input.retryAfterMs,
     })
   if (codes.some((code) => INVALID_REQUEST_CODES.has(code))) return new InvalidRequestReason(common)
-  if (
-    input.status === 400 ||
-    input.status === 404 ||
-    input.status === 413 ||
-    input.status === 422
-  )
+  if (input.status === 400 || input.status === 404 || input.status === 413 || input.status === 422)
     return new InvalidRequestReason(common)
   return new UnknownProviderReason({ ...common, status: input.status })
 }

packages/ai/src/provider-package.ts

@@ -1,10 +1,12 @@
 import type { Model, ProviderOptions } from "./schema"
 
 export interface Settings extends Readonly<Record<string, unknown>> {
+  readonly baseURL?: string
   readonly headers?: Readonly<Record<string, string>>
   readonly body?: Readonly<Record<string, unknown>>
   readonly limits?: {
     readonly context: number
+    readonly input?: number
     readonly output: number
   }
 }

packages/ai/src/providers/openrouter.ts

@@ -4,21 +4,72 @@ import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
 import { Protocol } from "../route/protocol"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
+import { ProviderID, type CacheHint, type ModelID, type ProviderOptions } from "../schema"
 import type { ProviderPackage } from "../provider-package"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAIChat from "../protocols/openai-chat"
+import { newBreakpoints, ttlBucket } from "../protocols/utils/cache"
 import { isRecord } from "../protocols/shared"
 
 export const profile = OpenAICompatibleProfiles.profiles.openrouter
 export const id = ProviderID.make(profile.provider)
 const ADAPTER = "openrouter"
 
+type OpenRouterString<Known extends string> = Known | (string & {})
+
+export interface OpenRouterProviderRouting {
+  readonly [key: string]: unknown
+  readonly order?: ReadonlyArray<string>
+  readonly allow_fallbacks?: boolean
+  readonly require_parameters?: boolean
+  readonly data_collection?: OpenRouterString<"allow" | "deny">
+  readonly only?: ReadonlyArray<string>
+  readonly ignore?: ReadonlyArray<string>
+  readonly quantizations?: ReadonlyArray<string>
+  readonly sort?: OpenRouterString<"price" | "throughput" | "latency">
+  readonly max_price?: Readonly<{
+    prompt?: number | string
+    completion?: number | string
+    image?: number | string
+    audio?: number | string
+    request?: number | string
+  }>
+  readonly zdr?: boolean
+}
+
+export type OpenRouterPlugin =
+  | Readonly<{
+      id: "web"
+      max_results?: number
+      search_prompt?: string
+      engine?: OpenRouterString<"native" | "exa">
+    }>
+  | Readonly<{ id: "file-parser"; max_files?: number; pdf?: { engine?: string } }>
+  | Readonly<{ id: "moderation" }>
+  | Readonly<{ id: "response-healing" }>
+  | Readonly<{ id: "auto-router"; allowed_models?: ReadonlyArray<string> }>
+  | Readonly<{ id: string & {}; [key: string]: unknown }>
+
 export interface OpenRouterOptions {
   readonly [key: string]: unknown
-  readonly usage?: boolean | Record<string, unknown>
-  readonly reasoning?: Record<string, unknown>
+  readonly debug?: Readonly<{ echo_upstream_body?: boolean }>
+  readonly models?: ReadonlyArray<string>
+  readonly plugins?: ReadonlyArray<OpenRouterPlugin>
   readonly promptCacheKey?: string
+  readonly provider?: OpenRouterProviderRouting
+  readonly reasoning?: Readonly<{
+    enabled?: boolean
+    exclude?: boolean
+    effort?: OpenRouterString<"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">
+    max_tokens?: number
+  }>
+  readonly usage?: boolean | Readonly<{ include: boolean }>
+  readonly user?: string
+  readonly web_search_options?: Readonly<{
+    max_results?: number
+    search_prompt?: string
+    engine?: OpenRouterString<"native" | "exa">
+  }>
 }
 
 export type OpenRouterProviderOptionsInput = ProviderOptions & {
@@ -47,7 +98,7 @@ export const protocol = Protocol.make({
   body: {
     schema: OpenRouterBody,
     from: (request) =>
-      OpenAIChat.protocol.body.from(request).pipe(
+      OpenAIChat.fromRequest(request, { cacheControl: cacheControl() }).pipe(
         Effect.map((body) => {
           const sourceAssistants = request.messages.filter((message) => message.role === "assistant")
           let assistantIndex = 0
@@ -78,16 +129,39 @@ export const protocol = Protocol.make({
   stream: OpenAIChat.protocol.stream,
 })
 
+const cacheControl = () => {
+  const breakpoints = newBreakpoints(4)
+  return (cache: CacheHint | undefined) => {
+    if (cache === undefined || breakpoints.remaining === 0) return undefined
+    breakpoints.remaining -= 1
+    return {
+      type: "ephemeral" as const,
+      ...(ttlBucket(cache.ttlSeconds) === "1h" ? { ttl: "1h" } : {}),
+    }
+  }
+}
+
 const bodyOptions = (input: unknown) => {
   const openrouter = isRecord(input) ? input : {}
+  const { usage, models, provider, plugins, web_search_options, debug, user, reasoning, promptCacheKey, ...options } =
+    openrouter
   return {
-    ...(openrouter.usage === true
+    ...options,
+    ...(usage === undefined || usage === true
       ? { usage: { include: true } }
-      : isRecord(openrouter.usage)
-        ? { usage: openrouter.usage }
-        : {}),
-    ...(isRecord(openrouter.reasoning) ? { reasoning: openrouter.reasoning } : {}),
-    ...(typeof openrouter.promptCacheKey === "string" ? { prompt_cache_key: openrouter.promptCacheKey } : {}),
+      : usage === false
+        ? { usage: { include: false } }
+        : isRecord(usage)
+          ? { usage }
+          : {}),
+    ...(Array.isArray(models) ? { models } : {}),
+    ...(isRecord(provider) ? { provider } : {}),
+    ...(Array.isArray(plugins) ? { plugins } : {}),
+    ...(isRecord(web_search_options) ? { web_search_options } : {}),
+    ...(isRecord(debug) ? { debug } : {}),
+    ...(typeof user === "string" ? { user } : {}),
+    ...(isRecord(reasoning) ? { reasoning } : {}),
+    ...(typeof promptCacheKey === "string" ? { prompt_cache_key: promptCacheKey } : {}),
   }
 }
 

packages/ai/src/providers/xai.ts

@@ -1,38 +1,62 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import type { RouteDefaultsInput } from "../route/client"
-import { HttpOptions, ProviderID, type ModelID } from "../schema"
+import { Route, type RouteDefaultsInput } from "../route/client"
+import { Endpoint } from "../route/endpoint"
+import { HttpOptions, ProviderID, type ModelID, type ProviderOptions } from "../schema"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
+import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
 import { XAIImages } from "../protocols/xai-images"
-import type { OpenAIProviderOptionsInput } from "./openai-options"
+import type { OpenAIOptionsInput } from "./openai-options"
 import type { ProviderPackage } from "../provider-package"
 
 export const id = ProviderID.make("xai")
 
+export type XAIProviderOptionsInput = ProviderOptions & {
+  readonly xai?: OpenAIOptionsInput
+}
+
 export type ModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
   ProviderAuthOption<"optional"> & {
     readonly baseURL?: string
-    readonly providerOptions?: OpenAIProviderOptionsInput
+    readonly providerOptions?: XAIProviderOptionsInput
   }
 
 export interface Settings extends ProviderPackage.Settings {
   readonly apiKey?: string
   readonly baseURL?: string
-  readonly providerOptions?: OpenAIProviderOptionsInput
+  readonly providerOptions?: XAIProviderOptionsInput
 }
 
 export type { XAIImageOptions } from "../protocols/xai-images"
 
-export const routes = [OpenAIResponses.route, OpenAICompatibleChat.route]
+const responsesRoute = Route.make({
+  id: "openai-responses",
+  provider: id,
+  providerMetadataKey: "xai",
+  protocol: OpenAIResponses.protocol,
+  endpoint: Endpoint.path("/responses", { baseURL: OpenAICompatibleProfiles.profiles.xai.baseURL }),
+  transport: OpenAIResponses.httpTransport,
+  defaults: { providerOptions: { xai: { store: false } } },
+})
+
+const chatRoute = Route.make({
+  id: "openai-compatible-chat",
+  provider: id,
+  providerMetadataKey: "xai",
+  protocol: OpenAIChat.protocol,
+  endpoint: Endpoint.path("/chat/completions", { baseURL: OpenAICompatibleProfiles.profiles.xai.baseURL }),
+  transport: OpenAICompatibleChat.route.transport,
+})
+
+export const routes = [responsesRoute, chatRoute]
 
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "XAI_API_KEY")
 
 const configuredResponsesRoute = (input: ModelOptions) => {
   const { apiKey: _, auth: _auth, baseURL, ...rest } = input
-  return OpenAIResponses.route.with({
+  return responsesRoute.with({
     ...rest,
-    provider: id,
     endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
     auth: auth(input),
   })
@@ -40,9 +64,8 @@ const configuredResponsesRoute = (input: ModelOptions) => {
 
 const configuredChatRoute = (input: ModelOptions) => {
   const { apiKey: _, auth: _auth, baseURL, ...rest } = input
-  return OpenAICompatibleChat.route.with({
+  return chatRoute.with({
     ...rest,
-    provider: id,
     endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
     auth: auth(input),
   })
@@ -51,8 +74,8 @@ const configuredChatRoute = (input: ModelOptions) => {
 export const configure = (input: ModelOptions = {}) => {
   const responsesRoute = configuredResponsesRoute(input)
   const chatRoute = configuredChatRoute(input)
-  const responses = (modelID: string | ModelID) => responsesRoute.model<OpenAIProviderOptionsInput>({ id: modelID })
-  const chat = (modelID: string | ModelID) => chatRoute.model<OpenAIProviderOptionsInput>({ id: modelID })
+  const responses = (modelID: string | ModelID) => responsesRoute.model<XAIProviderOptionsInput>({ id: modelID })
+  const chat = (modelID: string | ModelID) => chatRoute.model<XAIProviderOptionsInput>({ id: modelID })
   const image = (modelID: string | ModelID) =>
     XAIImages.model({
       id: modelID,
@@ -72,7 +95,7 @@ export const configure = (input: ModelOptions = {}) => {
 }
 
 export const provider = configure()
-export const model: ProviderPackage.Definition<Settings, OpenAIProviderOptionsInput>["model"] = (modelID, settings) =>
+export const model: ProviderPackage.Definition<Settings, XAIProviderOptionsInput>["model"] = (modelID, settings) =>
   configure({
     apiKey: settings.apiKey,
     baseURL: settings.baseURL,

packages/ai/src/route/client.ts

@@ -5,7 +5,7 @@ import { Endpoint, type EndpointPatch } from "./endpoint"
 import { RequestExecutor } from "./executor"
 import { Framing } from "./framing"
 import { HttpTransport } from "./transport"
-import type { Transport, TransportRuntime } from "./transport"
+import type { HttpRequestTransform, Transport, TransportRuntime } from "./transport"
 import { WebSocketExecutor } from "./transport"
 import type { Protocol } from "./protocol"
 import { applyCachePolicy } from "../cache-policy"
@@ -46,7 +46,11 @@ export interface Route<Body, Prepared = unknown> {
   readonly body: RouteBody<Body>
   readonly with: (patch: RoutePatch<Body, Prepared>) => Route<Body, Prepared>
   readonly model: <Options extends ProviderOptions = ProviderOptions>(input: RouteMappedModelInput) => Model<Options>
-  readonly prepareTransport: (body: Body, request: LLMRequest) => Effect.Effect<Prepared, LLMError>
+  readonly prepareTransport: (
+    body: Body,
+    request: LLMRequest,
+    options?: StreamOptions,
+  ) => Effect.Effect<Prepared, LLMError>
   readonly streamPrepared: (
     prepared: Prepared,
     request: LLMRequest,
@@ -145,12 +149,16 @@ export interface Interface {
   readonly generate: GenerateMethod
 }
 
+export interface StreamOptions {
+  readonly transform?: HttpRequestTransform
+}
+
 export interface StreamMethod {
-  (request: LLMRequest): Stream.Stream<LLMEvent, LLMError>
+  (request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, LLMError>
 }
 
 export interface GenerateMethod {
-  (request: LLMRequest): Effect.Effect<LLMResponse, LLMError>
+  (request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, LLMError>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/LLMClient") {}
@@ -286,7 +294,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
       },
       model: <Options extends ProviderOptions = ProviderOptions>(input: RouteMappedModelInput) =>
         makeRouteModel<Options>(route, input),
-      prepareTransport: (body, request) =>
+      prepareTransport: (body, request, options) =>
         routeInput.transport.prepare({
           body,
           request,
@@ -294,6 +302,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
           auth: routeInput.auth ?? Auth.none,
           encodeBody,
           headers: routeInput.headers,
+          transform: options?.transform,
         }),
       streamPrepared: (prepared: Prepared, request: LLMRequest, runtime: TransportRuntime) => {
         const route = `${request.model.provider}/${request.model.route.id}`
@@ -359,14 +368,14 @@ export function make<Body, Prepared, Frame, Event, State>(
   })
 }
 
-const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest) {
+const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest, options?: StreamOptions) {
   const resolved = applyCachePolicy(resolveRequestOptions(request))
   const route = resolved.model.route
 
   const body = yield* route.body
     .from(resolved)
     .pipe(Effect.flatMap(ProviderShared.validateWith(Schema.decodeUnknownEffect(route.body.schema))))
-  const prepared = yield* route.prepareTransport(body, resolved)
+  const prepared = yield* route.prepareTransport(body, resolved, options)
 
   return {
     request: resolved,
@@ -389,17 +398,17 @@ export const compileRequest = Effect.fn("LLM.compileRequest")(function* (request
   }
 })
 
-const streamRequestWith = (runtime: TransportRuntime) => (request: LLMRequest) =>
+const streamRequestWith = (runtime: TransportRuntime) => (request: LLMRequest, options?: StreamOptions) =>
   Stream.unwrap(
     Effect.gen(function* () {
-      const compiled = yield* compile(request)
+      const compiled = yield* compile(request, options)
       return compiled.route.streamPrepared(compiled.prepared, compiled.request, runtime)
     }),
   )
 
 const generateWith = (stream: Interface["stream"]) =>
-  Effect.fn("LLM.generate")(function* (request: LLMRequest) {
-    const state = yield* stream(request).pipe(Stream.runFold(LLMResponse.empty, LLMResponse.reduce))
+  Effect.fn("LLM.generate")(function* (request: LLMRequest, options?: StreamOptions) {
+    const state = yield* stream(request, options).pipe(Stream.runFold(LLMResponse.empty, LLMResponse.reduce))
     const response = LLMResponse.complete(state)
     if (response) return response
     return yield* ProviderShared.eventError(
@@ -408,24 +417,24 @@ const generateWith = (stream: Interface["stream"]) =>
     )
   })
 
-export function stream(request: LLMRequest): Stream.Stream<LLMEvent, LLMError> {
+export function stream(request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, LLMError> {
   return Stream.unwrap(
     Effect.gen(function* () {
-      return (yield* Service).stream(request)
+      return (yield* Service).stream(request, options)
     }),
   ) as Stream.Stream<LLMEvent, LLMError>
 }
 
-export function generate(request: LLMRequest): Effect.Effect<LLMResponse, LLMError> {
+export function generate(request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, LLMError> {
   return Effect.gen(function* () {
-    return yield* (yield* Service).generate(request)
+    return yield* (yield* Service).generate(request, options)
   }) as Effect.Effect<LLMResponse, LLMError>
 }
 
-export const streamRequest = (request: LLMRequest) =>
+export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>
   Stream.unwrap(
     Effect.gen(function* () {
-      return (yield* Service).stream(request)
+      return (yield* Service).stream(request, options)
     }),
   )
 

packages/ai/src/route/index.ts

@@ -8,6 +8,7 @@ export type {
   AnyRoute,
   Interface as LLMClientShape,
   Service as LLMClientService,
+  StreamOptions,
 } from "./client"
 export * from "./executor"
 export { Auth } from "./auth"
@@ -22,4 +23,4 @@ export type { ApiKeyMode, AuthOverride, ProviderAuthOption } from "./auth-option
 export type { Definition as EndpointFn, EndpointInput } from "./endpoint"
 export type { Definition as FramingDef } from "./framing"
 export type { Protocol as ProtocolDef } from "./protocol"
-export type { Transport as TransportDef, TransportRuntime } from "./transport"
+export type { HttpRequest, HttpRequestTransform, Transport as TransportDef, TransportRuntime } from "./transport"

packages/ai/src/route/transport/http.ts

@@ -28,57 +28,9 @@ const applyQuery = (url: string, query: Record<string, string> | undefined) => {
   return next.toString()
 }
 
-const PROTOCOL_BODY_OVERLAY_DENYLIST = new Set([
-  "anthropic_version",
-  "content",
-  "contents",
-  "frequencyPenalty",
-  "frequency_penalty",
-  "generationConfig",
-  "inferenceConfig",
-  "input",
-  "maxTokens",
-  "max_tokens",
-  "messages",
-  "model",
-  "presencePenalty",
-  "presence_penalty",
-  "responseFormat",
-  "response_format",
-  "seed",
-  "stop",
-  "stopSequences",
-  "stop_sequences",
-  "stream",
-  "streamOptions",
-  "stream_options",
-  "system",
-  "systemInstruction",
-  "system_instruction",
-  "temperature",
-  "thinking",
-  "toolChoice",
-  "toolConfig",
-  "tool_choice",
-  "tool_config",
-  "tools",
-  "topK",
-  "topP",
-  "top_k",
-  "top_p",
-])
-
-const forbiddenBodyOverlayKeys = (body: Record<string, unknown>) =>
-  Object.keys(body).filter((key) => PROTOCOL_BODY_OVERLAY_DENYLIST.has(key))
-
 const bodyWithOverlay = <Body>(body: Body, request: LLMRequest, encodeBody: (body: Body) => string) =>
   Effect.gen(function* () {
     if (request.http?.body === undefined) return { jsonBody: body, bodyText: encodeBody(body) }
-    const forbiddenKeys = forbiddenBodyOverlayKeys(request.http.body)
-    if (forbiddenKeys.length > 0)
-      return yield* ProviderShared.invalidRequest(
-        `http.body cannot overlay protocol-owned field(s): ${forbiddenKeys.join(", ")}`,
-      )
     if (ProviderShared.isRecord(body)) {
       const overlaid = mergeJsonRecords(body, request.http.body) ?? {}
       return { jsonBody: overlaid, bodyText: ProviderShared.encodeJson(overlaid) }
@@ -120,14 +72,19 @@ export const httpJson = <Body, Frame>(input: HttpJsonInput<Body, Frame>): HttpJs
   id: "http-json",
   with: (patch) => httpJson({ ...input, ...patch }),
   prepare: (prepareInput) =>
-    jsonRequestParts({
-      ...prepareInput,
-    }).pipe(
-      Effect.map((parts) => ({
-        request: ProviderShared.jsonPost({ url: parts.url, body: parts.bodyText, headers: parts.headers }),
+    Effect.gen(function* () {
+      const parts = yield* jsonRequestParts({ ...prepareInput })
+      const request = { url: parts.url, method: "POST", headers: { ...parts.headers }, body: parts.bodyText }
+      yield* (prepareInput.transform?.(request) ?? Effect.void)
+      return {
+        request: ProviderShared.jsonPost({
+          url: request.url,
+          body: request.body ?? "",
+          headers: Headers.fromInput(request.headers),
+        }),
         framing: input.framing,
-      })),
-    ),
+      }
+    }),
   frames: (prepared, request, runtime) =>
     Stream.unwrap(
       runtime.http

packages/ai/src/route/transport/index.ts

@@ -10,6 +10,15 @@ export interface TransportRuntime {
   readonly webSocket?: WebSocketExecutorInterface
 }
 
+export interface HttpRequest {
+  url: string
+  readonly method: string
+  headers: Record<string, string>
+  body: string | undefined
+}
+
+export type HttpRequestTransform = (request: HttpRequest) => Effect.Effect<void>
+
 export interface Transport<Body, Prepared, Frame> {
   readonly id: string
   readonly prepare: (input: TransportPrepareInput<Body>) => Effect.Effect<Prepared, LLMError>
@@ -27,6 +36,7 @@ export interface TransportPrepareInput<Body> {
   readonly auth: Auth.Definition
   readonly encodeBody: (body: Body) => string
   readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
+  readonly transform?: HttpRequestTransform
 }
 
 export * as HttpTransport from "./http"

packages/ai/src/schema/errors.ts

@@ -2,7 +2,7 @@ import { Schema } from "effect"
 import { Tool } from "@opencode-ai/schema/tool"
 import { ModelID, ProviderID, ProviderMetadata, RouteID } from "./ids"
 
-export const ProviderFailureClassification = Schema.Literal("context-overflow")
+export const ProviderFailureClassification = Schema.Literals(["context-overflow", "payload-too-large"])
 export type ProviderFailureClassification = typeof ProviderFailureClassification.Type
 
 export class HttpRequestDetails extends Schema.Class<HttpRequestDetails>("LLM.HttpRequestDetails")({

packages/ai/src/schema/messages.ts

@@ -124,6 +124,7 @@ export const ToolCallPart = Object.assign(
     name: Schema.String,
     input: Schema.Unknown,
     providerExecuted: Schema.optional(Schema.Boolean),
+    cache: Schema.optional(CacheHint),
     metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
     providerMetadata: Schema.optional(ProviderMetadata),
   }).annotate({ identifier: "LLM.Content.ToolCall" }),
@@ -168,6 +169,7 @@ export const ReasoningPart = Schema.Struct({
   type: Schema.Literal("reasoning"),
   text: Schema.String,
   encrypted: Schema.optional(Schema.String),
+  cache: Schema.optional(CacheHint),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
   providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Content.Reasoning" })

packages/ai/src/schema/options.ts

@@ -123,6 +123,7 @@ export const mergeGenerationOptions = (...items: ReadonlyArray<GenerationOptions
 
 export class ModelLimits extends Schema.Class<ModelLimits>("LLM.ModelLimits")({
   context: Schema.optional(Schema.Number),
+  input: Schema.optional(Schema.Number),
   output: Schema.optional(Schema.Number),
 }) {}
 
@@ -166,9 +167,13 @@ export namespace ModelDefaults {
 export const ModelToolSchemaCompatibility = Schema.Literals(["gemini", "moonshot"])
 export type ModelToolSchemaCompatibility = Schema.Schema.Type<typeof ModelToolSchemaCompatibility>
 
+export const ModelMaxTokensFieldCompatibility = Schema.Literals(["max_completion_tokens", "max_tokens"])
+export type ModelMaxTokensFieldCompatibility = Schema.Schema.Type<typeof ModelMaxTokensFieldCompatibility>
+
 export class ModelCompatibility extends Schema.Class<ModelCompatibility>("LLM.ModelCompatibility")({
   toolSchema: Schema.optional(ModelToolSchemaCompatibility),
   reasoningField: Schema.optional(Schema.String),
+  maxTokensField: Schema.optional(ModelMaxTokensFieldCompatibility),
 }) {}
 
 export namespace ModelCompatibility {

packages/ai/test/compile.test.ts

@@ -137,24 +137,61 @@ describe("request option precedence", () => {
     ),
   )
 
-  it.effect("rejects raw body overlays for protocol-owned roots", () =>
-    Effect.gen(function* () {
-      const model = OpenAIChat.route
-        .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
-        .model({ id: "gpt-4o-mini" })
-      const error = yield* compileRequest(
-        LLM.request({
-          model,
-          prompt: "Say hello.",
-          http: { body: { model: "gpt-5", messages: [], tools: [] } },
-        }),
-      ).pipe(Effect.flip)
+  it.effect("transforms the final HTTP request after serialization and authentication", () =>
+    LLMClient.generate(
+      LLM.request({
+        model: OpenAIChat.route
+          .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("fresh-key") })
+          .model({ id: "gpt-4o-mini" }),
+        prompt: "Say hello.",
+      }),
+      {
+        transform: (request) =>
+          Effect.sync(() => {
+            expect(request.headers.authorization).toBe("Bearer fresh-key")
+            request.url = "https://proxy.test/v1/chat/completions"
+            request.headers["x-plugin"] = "transformed"
+            request.body = JSON.stringify({ transformed: true })
+          }),
+      },
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.url).toBe("https://proxy.test/v1/chat/completions")
+            expect(web.headers.get("x-plugin")).toBe("transformed")
+            expect(decodeJson(input.text)).toEqual({ transformed: true })
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
 
-      expect(error.reason).toMatchObject({
-        _tag: "InvalidRequest",
-        message: "http.body cannot overlay protocol-owned field(s): model, messages, tools",
-      })
-    }),
+  it.effect("applies raw body overlays after protocol lowering", () =>
+    LLMClient.generate(
+      LLM.request({
+        model: OpenAIChat.route
+          .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+          .model({ id: "gpt-4o-mini" }),
+        prompt: "Say hello.",
+        http: { body: { model: "gpt-5", messages: [], tools: [] } },
+      }),
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            expect(decodeJson(input.text)).toMatchObject({ model: "gpt-5", messages: [], tools: [] })
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
   )
 
   it.effect("uses model output limits after route limits and before call maxTokens", () =>

packages/ai/test/executor.test.ts

@@ -85,14 +85,17 @@ describe("RequestExecutor", () => {
     ),
   )
 
-  it.effect("does not classify generic HTTP 413 payload errors as context overflow", () =>
+  it.effect("classifies generic HTTP 413 payload errors", () =>
     Effect.gen(function* () {
       const executor = yield* RequestExecutor.Service
       const error = yield* executor.execute(request).pipe(Effect.flip)
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
-      expect("classification" in error.reason ? error.reason.classification : undefined).toBeUndefined()
+      expect(error.reason).toMatchObject({
+        _tag: "InvalidRequest",
+        classification: "payload-too-large",
+        http: { response: { status: 413 } },
+      })
     }).pipe(Effect.provide(responsesLayer([new Response("request too large", { status: 413 })]))),
   )
 

packages/ai/test/provider-error.test.ts

@@ -6,7 +6,6 @@ describe("provider error classification", () => {
   test("classifies provider token limit messages as context overflow", () => {
     const messages = [
       "tokens in request more than max tokens allowed",
-      '{"error":{"type":"request_too_large","message":"Request exceeds the maximum size"}}',
       "Requested token count exceeds the model's maximum context length of 131072 tokens.",
       "Input length (265330) exceeds model's maximum context length (262144).",
       "Input length 131393 exceeds the maximum allowed input length of 131040 tokens.",
@@ -19,6 +18,24 @@ describe("provider error classification", () => {
     expect(messages.every(isContextOverflow)).toBe(true)
   })
 
+  test("classifies request size failures separately from context overflow", () => {
+    const failures = [
+      classifyProviderFailure({ message: "request too large", status: 413 }),
+      classifyProviderFailure({
+        message: '{"error":{"type":"request_too_large","message":"Request exceeds the maximum size"}}',
+        status: 400,
+      }),
+      classifyProviderFailure({ message: "upstream request entity too large", status: 502 }),
+    ]
+
+    expect(failures).toEqual(
+      failures.map((failure) =>
+        expect.objectContaining({ _tag: "InvalidRequest", classification: "payload-too-large" }),
+      ),
+    )
+    expect(isContextOverflow("413 status code (no body)")).toBe(false)
+  })
+
   test("does not classify rate limits as context overflow", () => {
     const messages = [
       "Throttling error: Too many tokens, please wait before trying again.",
@@ -59,9 +76,10 @@ describe("provider error classification", () => {
   })
 
   test("classifies transient client statuses as provider internal", () => {
-    expect(
-      [408, 409].map((status) => classifyProviderFailure({ message: `HTTP ${status}`, status })._tag),
-    ).toEqual(["ProviderInternal", "ProviderInternal"])
+    expect([408, 409].map((status) => classifyProviderFailure({ message: `HTTP ${status}`, status })._tag)).toEqual([
+      "ProviderInternal",
+      "ProviderInternal",
+    ])
   })
 
   test("classifies nested provider codes when a top-level code is also present", () => {

packages/ai/test/provider-options/google.types.ts

@@ -9,9 +9,39 @@ LLM.request({
   providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1024 } } },
 })
 
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: {
+    gemini: {
+      // @ts-expect-error Gemini safety settings require a threshold for every category.
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH" }],
+    },
+  },
+})
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: {
+    gemini: {
+      cachedContent: "cachedContents/example",
+      safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
+      serviceTier: "future-tier",
+      thinkingConfig: { thinkingLevel: "high", includeThoughts: true },
+    },
+  },
+})
+
 LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error Gemini thinking budgets must be numeric.
   providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "large" } } },
 })
+
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "maximum" } } },
+})

packages/ai/test/provider-options/openrouter.types.ts

@@ -5,6 +5,28 @@ const model = OpenRouter.provider.model("anthropic/claude-sonnet-4.5")
 
 LLM.request({ model, prompt: "Hello", providerOptions: { openrouter: { usage: true } } })
 
+LLM.request({
+  model,
+  prompt: "Hello",
+  providerOptions: {
+    openrouter: {
+      models: ["google/gemini-3.1-pro"],
+      provider: {
+        order: ["anthropic"],
+        require_parameters: true,
+        data_collection: "future-policy",
+        sort: "future-sort",
+        max_price: { prompt: "0.50" },
+      },
+      reasoning: { effort: "future-effort", exclude: false },
+      plugins: [{ id: "future-plugin", enabled: true }],
+      web_search_options: { engine: "future-engine" },
+      debug: { echo_upstream_body: true },
+      user: "user_123",
+    },
+  },
+})
+
 LLM.request({
   model,
   prompt: "Hello",

packages/ai/test/provider-options/xai.types.ts

@@ -3,11 +3,11 @@ import { XAI } from "../../src/providers"
 
 const model = XAI.provider.model("grok-4")
 
-LLM.request({ model, prompt: "Hello", providerOptions: { openai: { reasoningEffort: "high" } } })
+LLM.request({ model, prompt: "Hello", providerOptions: { xai: { reasoningEffort: "high" } } })
 
 LLM.request({
   model,
   prompt: "Hello",
   // @ts-expect-error xAI's OpenAI-compatible reasoning effort must be a string.
-  providerOptions: { openai: { reasoningEffort: true } },
+  providerOptions: { xai: { reasoningEffort: true } },
 })

packages/ai/test/provider-package.test.ts

@@ -47,7 +47,7 @@ describe("provider package entrypoints", () => {
     })
     const xai = XAI.model("grok-4", {
       ...settings,
-      providerOptions: { openai: { reasoningEffort: "high" } },
+      providerOptions: { xai: { reasoningEffort: "high" } },
     })
 
     for (const selected of [openrouter, xai]) {
@@ -57,7 +57,7 @@ describe("provider package entrypoints", () => {
       expect(selected.route.defaults.limits).toEqual(settings.limits)
     }
     expect(openrouter.route.defaults.providerOptions).toEqual({ openrouter: { usage: true } })
-    expect(xai.route.defaults.providerOptions).toEqual({ openai: { reasoningEffort: "high", store: false } })
+    expect(xai.route.defaults.providerOptions).toMatchObject({ xai: { reasoningEffort: "high", store: false } })
   })
 
   test("maps package settings onto the executable model", () => {

packages/ai/test/provider/gemini.test.ts

@@ -41,7 +41,14 @@ describe("Gemini route", () => {
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
         LLMRequest.update(request, {
-          providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 0, includeThoughts: false } } },
+          providerOptions: {
+            gemini: {
+              cachedContent: "cachedContents/example",
+              safetySettings: [{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" }],
+              serviceTier: "priority",
+              thinkingConfig: { thinkingBudget: 0, includeThoughts: false, thinkingLevel: "high" },
+            },
+          },
         }),
       )
       const filtered = yield* compileRequest(
@@ -49,12 +56,33 @@ describe("Gemini route", () => {
           providerOptions: { gemini: { thinkingConfig: { thinkingBudget: "invalid", includeThoughts: false } } },
         }),
       )
+      const defaulted = yield* compileRequest(
+        LLMRequest.update(request, {
+          providerOptions: { gemini: { thinkingConfig: { thinkingLevel: "high" } } },
+        }),
+      )
+      const emptySafetySettings = yield* compileRequest(
+        LLMRequest.update(request, {
+          providerOptions: { gemini: { safetySettings: [] } },
+        }),
+      )
 
       expect(prepared.body.generationConfig?.thinkingConfig).toEqual({
         thinkingBudget: 0,
         includeThoughts: false,
+        thinkingLevel: "high",
       })
+      expect(prepared.body.cachedContent).toBe("cachedContents/example")
+      expect(prepared.body.safetySettings).toEqual([
+        { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" },
+      ])
+      expect(prepared.body.serviceTier).toBe("priority")
       expect(filtered.body.generationConfig?.thinkingConfig).toEqual({ includeThoughts: false })
+      expect(defaulted.body.generationConfig?.thinkingConfig).toEqual({
+        includeThoughts: true,
+        thinkingLevel: "high",
+      })
+      expect(emptySafetySettings.body.safetySettings).toEqual([])
     }),
   )
 

packages/ai/test/provider/google-vertex.test.ts

@@ -181,23 +181,6 @@ describe("Google Vertex providers", () => {
     }),
   )
 
-  it.effect("protects the Vertex Messages API version from body overlays", () =>
-    Effect.gen(function* () {
-      const error = yield* compileRequest(
-        LLM.request({
-          model: GoogleVertexMessages.configure({
-            accessToken: "vertex-token",
-            http: { body: { anthropic_version: "wrong" } },
-            project: "vertex-project",
-          }).model("claude-sonnet-4-6"),
-          prompt: "Say hello.",
-        }),
-      ).pipe(Effect.flip)
-
-      expect(error.message).toContain("http.body cannot overlay protocol-owned field(s): anthropic_version")
-    }),
-  )
-
   it.effect("routes tuned Gemini models through their deployed endpoint", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(

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

@@ -144,6 +144,20 @@ describe("OpenAI-compatible Chat route", () => {
     }),
   )
 
+  it.effect("configures the max tokens request field", () =>
+    Effect.gen(function* () {
+      const compatible = OpenAICompatibleChat.route
+        .with({ provider: "custom", endpoint: { baseURL: "https://api.custom.test/v1" } })
+        .model({ id: "custom-model", compatibility: { maxTokensField: "max_completion_tokens" } })
+      const prepared = yield* compileRequest(
+        LLM.request({ model: compatible, prompt: "Say hello.", generation: { maxTokens: 20 } }),
+      )
+
+      expect(prepared.body).toMatchObject({ max_completion_tokens: 20 })
+      expect(prepared.body).not.toHaveProperty("max_tokens")
+    }),
+  )
+
   it.effect("matches AI SDK compatible tool request body fixture", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(

packages/ai/test/provider/openrouter.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, Message } from "../../src"
+import { CacheHint, LLM, Message } from "../../src"
 import { LLMClient } from "../../src/route"
 import { compileRequest } from "../../src/route/client"
 import * as OpenRouter from "../../src/providers/openrouter"
@@ -27,10 +27,131 @@ describe("OpenRouter", () => {
         model: "openai/gpt-4o-mini",
         messages: [{ role: "user", content: "Say hello." }],
         stream: true,
+        usage: { include: true },
       })
     }),
   )
 
+  it.effect("lowers the native cache policy to OpenRouter cache controls", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          system: [
+            { type: "text", text: "Base agent", cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3_600 }) },
+            { type: "text", text: "Project instructions" },
+          ],
+          tools: [{ name: "lookup", description: "Lookup", inputSchema: { type: "object", properties: {} } }],
+          prompt: "Hello",
+          cache: { tools: true, system: true, messages: { tail: 1 } },
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        tools: [{ cache_control: { type: "ephemeral" } }],
+        messages: [
+          {
+            role: "system",
+            content: [
+              { text: "Base agent", cache_control: { type: "ephemeral", ttl: "1h" } },
+              { text: "Project instructions", cache_control: { type: "ephemeral" } },
+            ],
+          },
+          {
+            role: "user",
+            content: [{ text: "Hello", cache_control: { type: "ephemeral" } }],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("lowers manual assistant and tool-result cache hints", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
+          messages: [
+            Message.user("Call the tool"),
+            Message.assistant([
+              { type: "text", text: "Calling", cache: new CacheHint({ type: "ephemeral" }) },
+              { type: "tool-call", id: "call_1", name: "lookup", input: {} },
+            ]),
+            Message.tool({
+              id: "call_1",
+              name: "lookup",
+              result: "Done",
+              cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3_600 }),
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages).toMatchObject([
+        { role: "user", content: "Call the tool" },
+        { role: "assistant", content: "Calling", cache_control: { type: "ephemeral" } },
+        { role: "tool", content: '"Done"', cache_control: { type: "ephemeral", ttl: "1h" } },
+      ])
+    }),
+  )
+
+  it.effect("caps manual cache controls at four breakpoints", () =>
+    Effect.gen(function* () {
+      const cache = new CacheHint({ type: "ephemeral" })
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
+          system: [1, 2, 3, 4, 5].map((index) => ({ type: "text" as const, text: `System ${index}`, cache })),
+          prompt: "Hello",
+        }),
+      )
+
+      const system = prepared.body.messages[0]
+      expect(system?.role).toBe("system")
+      expect(
+        system && Array.isArray(system.content)
+          ? system.content.filter((part) => "cache_control" in part && part.cache_control !== undefined)
+          : [],
+      ).toHaveLength(4)
+    }),
+  )
+
+  it.effect("preserves cache policy hints on reasoning-only assistant messages", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: { messages: "latest-assistant" },
+          messages: [Message.user("Think"), Message.assistant([{ type: "reasoning", text: "Reasoning" }])],
+        }),
+      )
+
+      expect(prepared.body.messages).toMatchObject([
+        { role: "user", content: "Think" },
+        { role: "assistant", cache_control: { type: "ephemeral" } },
+      ])
+    }),
+  )
+
+  it.effect("allows usage accounting to be disabled explicitly", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({
+            apiKey: "test-key",
+            providerOptions: { openrouter: { usage: false } },
+          }).model("openai/gpt-4o-mini"),
+          cache: "none",
+          prompt: "Hello",
+        }),
+      )
+
+      expect(prepared.body.usage).toEqual({ include: false })
+    }),
+  )
+
   it.effect("applies OpenRouter payload options from the model helper", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
@@ -42,6 +163,13 @@ describe("OpenRouter", () => {
                 usage: true,
                 reasoning: { effort: "high" },
                 promptCacheKey: "session_123",
+                models: ["anthropic/claude-sonnet-4.6", "google/gemini-3.1-pro"],
+                provider: { order: ["anthropic", "google"], require_parameters: true },
+                plugins: [{ id: "response-healing" }],
+                web_search_options: { engine: "native", max_results: 3 },
+                debug: { echo_upstream_body: true },
+                user: "user_123",
+                future_option: { enabled: true },
               },
             },
           }).model("anthropic/claude-3.7-sonnet:thinking"),
@@ -53,10 +181,54 @@ describe("OpenRouter", () => {
         usage: { include: true },
         reasoning: { effort: "high" },
         prompt_cache_key: "session_123",
+        models: ["anthropic/claude-sonnet-4.6", "google/gemini-3.1-pro"],
+        provider: { order: ["anthropic", "google"], require_parameters: true },
+        plugins: [{ id: "response-healing" }],
+        web_search_options: { engine: "native", max_results: 3 },
+        debug: { echo_upstream_body: true },
+        user: "user_123",
+        future_option: { enabled: true },
       })
     }),
   )
 
+  it.effect("filters invalid known OpenRouter options while preserving extensions", () =>
+    Effect.gen(function* () {
+      const invalid: Record<string, unknown> = {
+        usage: "yes",
+        models: "anthropic/claude-sonnet-4.6",
+        provider: [],
+        plugins: {},
+        web_search_options: [],
+        debug: [],
+        user: 123,
+        reasoning: [],
+        promptCacheKey: 123,
+        future_option: { enabled: true },
+      }
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenRouter.configure({
+            apiKey: "test-key",
+            providerOptions: { openrouter: invalid },
+          }).model("openai/gpt-4o-mini"),
+          prompt: "Hello",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({ future_option: { enabled: true } })
+      expect(prepared.body).not.toHaveProperty("usage")
+      expect(prepared.body).not.toHaveProperty("models")
+      expect(prepared.body).not.toHaveProperty("provider")
+      expect(prepared.body).not.toHaveProperty("plugins")
+      expect(prepared.body).not.toHaveProperty("web_search_options")
+      expect(prepared.body).not.toHaveProperty("debug")
+      expect(prepared.body).not.toHaveProperty("user")
+      expect(prepared.body).not.toHaveProperty("reasoning")
+      expect(prepared.body).not.toHaveProperty("prompt_cache_key")
+    }),
+  )
+
   it.effect("preserves the upstream provider finish reason", () =>
     Effect.gen(function* () {
       const model = OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6")
@@ -104,6 +276,7 @@ describe("OpenRouter", () => {
       const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [
             Message.assistant([
               {
@@ -137,6 +310,7 @@ describe("OpenRouter", () => {
       const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [
             Message.assistant({
               type: "reasoning",
@@ -162,6 +336,7 @@ describe("OpenRouter", () => {
       const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [
             Message.assistant({
               type: "reasoning",
@@ -183,6 +358,7 @@ describe("OpenRouter", () => {
       const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
+          cache: "none",
           messages: [Message.assistant({ type: "reasoning", text: "Thinking" })],
         }),
       )

packages/app/V1_API_MIGRATION.md

@@ -0,0 +1,220 @@
+# V1 API Migration Checklist
+
+The app is currently hybrid. In this document, V1 refers to the legacy unprefixed server APIs used by `@opencode-ai/sdk/v2`, despite the SDK package name.
+
+## Events
+
+- [x] Replace `GET /global/event` with `GET /api/event`.
+  - `src/context/server-sdk.tsx`
+- [x] Reduce current granular session and message events into the existing app projections.
+  - `src/context/server-session-v2-reducer.ts`
+  - `src/context/server-session.ts`
+- [ ] Remove transitional session event dependencies: `session.created`, `session.updated`, `session.diff`, `session.status`, `session.idle`, and `session.error`.
+  - `src/context/global-sync/event-reducer.ts`
+  - `src/context/server-session.ts`
+  - `src/context/notification.tsx`
+  - `src/pages/session/usage-exceeded-dialogs.tsx`
+- [ ] Remove legacy message event compatibility: `message.updated`, `message.removed`, `message.part.updated`, `message.part.removed`, and `message.part.delta`.
+  - `src/context/global-sync/event-reducer.ts`
+  - `src/context/server-session.ts`
+- [x] Adapt current permission and question events to the existing request model.
+  - `src/context/global-sync/event-reducer.ts`
+  - `src/context/permission.tsx`
+- [x] Consume current file watcher events.
+  - `src/context/file.tsx`
+- [x] Consume current VCS events.
+  - `src/context/global-sync/event-reducer.ts`
+  - `src/pages/session.tsx`
+- [x] Consume current `pty.exited` events.
+  - `src/context/terminal.tsx`
+- [ ] Migrate LSP and reference events.
+  - `src/context/global-sync/event-reducer.ts`
+
+## Sessions
+
+- [x] Replace `GET /session/status` with one server-scoped `GET /api/session/active` snapshot plus V2 execution events.
+  - `src/context/server-sync.tsx`
+- [x] Migrate session listing from `GET /session`.
+  - `src/context/server-sync.tsx`
+  - `src/context/directory-sync.ts`
+  - `src/pages/layout.tsx`
+- [x] Migrate the remaining direct session read from `GET /session/:sessionID`.
+  - `src/components/titlebar.tsx`
+- [x] Migrate session updates from `PATCH /session/:sessionID`.
+  - `src/context/directory-sync.ts`
+  - `src/context/layout.tsx`
+  - `src/pages/home.tsx`
+  - `src/pages/layout.tsx`
+  - `src/pages/session/timeline/message-timeline.tsx`
+  - `src/components/titlebar-tab-nav.tsx`
+  - Renames use `POST /api/session/:sessionID/rename`; archival uses `POST /api/session/:sessionID/archive`.
+- [x] Migrate session deletion from `DELETE /session/:sessionID`.
+  - `src/pages/session/timeline/message-timeline.tsx`
+- [x] Remove session diff loading from `GET /session/:sessionID/diff`.
+  - Historical Session diffs remain unavailable until the current API defines their snapshot semantics.
+- [x] Migrate abort from `POST /session/:sessionID/abort`.
+  - `src/components/prompt-input/submit.ts`
+  - `src/pages/session/use-session-commands.tsx`
+  - `src/pages/session.tsx`
+- [x] Migrate revert and unrevert from `POST /session/:sessionID/revert` and `POST /session/:sessionID/unrevert`.
+  - `src/pages/session/use-session-commands.tsx`
+  - `src/pages/session.tsx`
+- [x] Replace `POST /session/:sessionID/summarize` with the current compact API.
+  - `src/pages/session/use-session-commands.tsx`
+- [x] Migrate slash commands from `POST /session/:sessionID/command`.
+  - `src/components/prompt-input/submit.ts`
+- [x] Migrate shell execution from `POST /session/:sessionID/shell`.
+  - `src/components/prompt-input/submit.ts`
+- [x] Migrate session fork from `POST /session/:sessionID/fork`.
+  - `src/components/dialog-fork.tsx`
+- [ ] Migrate sharing from `POST /session/:sessionID/share` and `DELETE /session/:sessionID/share`.
+  - `src/pages/session/use-session-commands.tsx`
+  - `src/pages/session/timeline/message-timeline.tsx`
+  - Blocked: the current API has no sharing contract or implementation.
+
+## Session Compatibility Fallbacks
+
+These calls are retained as fallback adapters. The current production path supplies the current session and message APIs.
+
+- [ ] Remove fallback `GET /session/:sessionID` after compatibility support is unnecessary.
+  - `src/context/server-session.ts`
+- [ ] Remove fallback `GET /session/:sessionID/message` after compatibility support is unnecessary.
+  - `src/context/server-session.ts`
+- [ ] Remove fallback `GET /session/:sessionID/message/:messageID` after compatibility support is unnecessary.
+  - `src/context/server-session.ts`
+
+## Filesystem
+
+- [ ] Migrate file listing from `GET /file`.
+  - `src/context/file.tsx`
+- [ ] Migrate file reads from `GET /file/content`.
+  - `src/context/file.tsx`
+  - `src/pages/session/review-tab.tsx`
+  - `src/pages/session/v2/review-panel-v2.tsx`
+- [x] Migrate path discovery from `GET /path` to `GET /api/path`.
+  - `src/context/global-sync/bootstrap.ts`
+  - `src/components/dialog-select-directory.tsx`
+  - `src/components/dialog-select-directory-v2.tsx`
+
+## Projects And Worktrees
+
+- [x] Migrate project listing from `GET /project` to `GET /api/project`.
+  - `src/context/global-sync/bootstrap.ts`
+- [x] Migrate the current project lookup from `GET /project/current` to `GET /api/project/current`.
+  - `src/context/global-sync/bootstrap.ts`
+- [ ] Migrate Git initialization from `POST /project/git/init`.
+  - `src/pages/session.tsx`
+- [x] Migrate project updates from `PATCH /project/:projectID` to `PATCH /api/project/:projectID`.
+  - `src/context/layout.tsx`
+  - `src/components/edit-project.ts`
+  - `src/pages/layout.tsx`
+- [ ] Migrate experimental worktree listing, creation, removal, and reset from `/experimental/worktree`.
+  - `src/pages/layout.tsx`
+  - `src/components/prompt-input/submit.ts`
+  - Listing now uses `GET /api/project/:projectID/directories`; create, removal, and reset remain.
+- [ ] Migrate instance disposal from `POST /instance/dispose`.
+  - `src/pages/layout.tsx`
+
+## VCS
+
+- [x] Migrate repository information from `GET /vcs` to `GET /api/vcs`.
+  - `src/context/global-sync/bootstrap.ts`
+- [x] Migrate diffs from `GET /vcs/diff` to `GET /api/vcs/diff`.
+  - `src/pages/session.tsx`
+- [x] Migrate status from `GET /vcs/status` to `GET /api/vcs/status`.
+  - `src/pages/layout.tsx`
+
+## Configuration And Authentication
+
+- [ ] Migrate global configuration reads from `GET /global/config`.
+  - `src/context/global-sync/bootstrap.ts`
+- [ ] Migrate directory configuration reads from `GET /config`.
+  - `src/context/global-sync/bootstrap.ts`
+- [ ] Migrate global configuration updates from `PATCH /global/config`.
+  - `src/context/server-sync.tsx`
+- [x] Migrate provider authentication method discovery from `GET /provider/auth` to `GET /api/integration/:integrationID`.
+  - `src/components/dialog-connect-provider.tsx`
+- [x] Migrate built-in provider OAuth authorization and callbacks to `/api/integration/:integrationID/connect/oauth/*`.
+  - `src/components/dialog-connect-provider.tsx`
+- [ ] Migrate remaining credentials from `PUT /auth/:providerID` and `DELETE /auth/:providerID`.
+  - Built-in provider key connections now use `POST /api/integration/:integrationID/connect/key`.
+  - `src/components/dialog-connect-provider.tsx`
+  - `src/components/dialog-custom-provider.tsx`
+  - `src/components/settings-providers.tsx`
+  - `src/components/settings-v2/providers.tsx`
+- [ ] Migrate global disposal from `POST /global/dispose`.
+  - `src/components/dialog-connect-provider.tsx`
+  - `src/components/settings-providers.tsx`
+  - `src/components/settings-v2/providers.tsx`
+
+## Permissions And Questions
+
+- [x] Migrate permission listing from `GET /permission` to `GET /api/permission/request`.
+  - `src/context/global-sync/bootstrap.ts`
+  - `src/context/permission.tsx`
+- [x] Migrate permission responses from `/session/:sessionID/permissions/:permissionID`.
+  - `src/context/permission.tsx`
+  - `src/pages/session/composer/session-composer-state.ts`
+- [x] Migrate question listing from `GET /question` to `GET /api/question/request`.
+  - `src/context/global-sync/bootstrap.ts`
+- [x] Migrate question replies and rejections from `/question/:requestID/*` to `/api/session/:sessionID/question/:requestID/*`.
+  - `src/pages/session/composer/session-question-dock.tsx`
+
+## Commands, MCP, LSP, And References
+
+- [x] Migrate command listing from `GET /command` to `GET /api/command`.
+  - `src/context/global-sync/bootstrap.ts`
+  - `src/context/server-sync.tsx`
+- [x] Migrate MCP listing, connection, and disconnection from `/mcp` to `/api/mcp`.
+  - `src/context/server-sync.tsx`
+- [ ] Replace legacy MCP authentication with the Integration OAuth workflow.
+  - `src/context/server-sync.tsx`
+- [x] Migrate experimental resource listing from `GET /experimental/resource` to `GET /api/mcp/resource`.
+  - `src/context/server-sync.tsx`
+- [ ] Migrate LSP status from `GET /lsp`.
+  - `src/context/server-sync.tsx`
+- [x] Move `GET /api/reference` off the legacy generated SDK transport.
+  - `src/context/global-sync/bootstrap.ts`
+
+## Search
+
+- [x] Migrate global session search from `GET /experimental/session` to `GET /api/session`.
+  - `src/components/command-palette.ts`
+  - `src/components/dialog-command-palette-v2.tsx`
+
+## PTY And Terminal
+
+- [x] Migrate PTY creation, reads, updates, and deletion from `/pty` to `/api/pty`.
+  - `src/context/terminal.tsx`
+  - `src/components/terminal.tsx`
+- [x] Migrate shell listing from `GET /pty/shells` to `GET /api/pty/shells`.
+  - `src/components/settings-general.tsx`
+  - `src/components/settings-v2/general.tsx`
+- [x] Migrate connection tokens from `POST /pty/:ptyID/connect-token` to `POST /api/pty/:ptyID/connect-token`.
+  - `src/components/terminal.tsx`
+- [x] Migrate the direct WebSocket connection from `/pty/:ptyID/connect` to `/api/pty/:ptyID/connect`.
+  - `src/components/terminal.tsx`
+
+## Legacy Types And Adapters
+
+These are not V1 network requests, but they keep the UI coupled to V1 data contracts.
+
+- [ ] Replace the current-session-to-legacy-session adapter.
+  - `src/utils/session.ts`
+- [ ] Replace the current-message-to-legacy-message-and-part adapter.
+  - `src/utils/session-message.ts`
+- [ ] Replace current agent, provider, and model adapters to legacy SDK structures.
+  - `src/context/global-sync/utils.ts`
+- [ ] Replace legacy `Session`, `Message`, `Part`, `PermissionRequest`, `QuestionRequest`, `Project`, `FileNode`, `FileDiffInfo`, and `Event` types throughout app state and rendering.
+- [ ] Remove the `@opencode-ai/sdk` runtime dependency after all legacy calls and types are gone.
+  - `package.json`
+
+## Test Infrastructure
+
+- [ ] Replace V1 endpoint mocks with current API mocks.
+  - `e2e/utils/mock-server.ts`
+- [x] Replace `/global/event` and `/event` interception with current event transport handling.
+  - `e2e/utils/sse-transport.ts`
+- [ ] Replace `SessionV1` and legacy SDK fixtures in timeline performance tests.
+  - `e2e/performance/timeline-stability/fixture.ts`
+- [ ] Remove remaining legacy SDK type fixtures from unit and browser tests.

packages/app/e2e/performance/timeline-stability/fixture.ts

@@ -2,8 +2,17 @@ import { base64Encode } from "@opencode-ai/core/util/encode"
 import { Event } from "@opencode-ai/schema/event"
 import { SessionStatusEvent } from "@opencode-ai/schema/session-status-event"
 import { SessionV1 } from "@opencode-ai/schema/session-v1"
-import type { SessionV1Info, SessionStatus } from "@opencode-ai/client/promise"
-import type { AssistantMessage, Message, Part, ToolPart, ToolState, UserMessage } from "../../../src/types"
+import type {
+  AssistantMessage,
+  GlobalEvent,
+  Message,
+  Part,
+  Session,
+  SessionStatus,
+  ToolPart,
+  ToolState,
+  UserMessage,
+} from "@opencode-ai/sdk/v2/client"
 import { expect, type Page } from "@playwright/test"
 import { Schema } from "effect"
 import { mockOpenCodeServer } from "../../utils/mock-server"
@@ -18,29 +27,18 @@ export const assistantID = "msg_1001_timeline_assistant"
 export const title = "Timeline visual stability"
 export const model = { providerID: "opencode", modelID: "claude-opus-4-6", variant: "max" }
 
-type Session = SessionV1Info
-type GlobalEvent = {
-  directory: string
-  project?: string
-  workspace?: string
-  payload: {
-    id: string
-    type: string
-    properties: Record<string, unknown>
+type TimelinePayload = Extract<
+  GlobalEvent["payload"],
+  {
+    type:
+      | "message.updated"
+      | "message.removed"
+      | "message.part.updated"
+      | "message.part.removed"
+      | "message.part.delta"
+      | "session.status"
   }
-}
-
-type TimelineProperties = {
-  "message.updated": { sessionID: string; info: Message }
-  "message.removed": { sessionID: string; messageID: string }
-  "message.part.updated": { sessionID: string; part: Part; time: number }
-  "message.part.removed": { sessionID: string; messageID: string; partID: string }
-  "message.part.delta": { sessionID: string; messageID: string; partID: string; field: string; delta: string }
-  "session.status": { sessionID: string; status: SessionStatus }
-}
-type TimelinePayload = {
-  [Type in keyof TimelineProperties]: { id: string; type: Type; properties: TimelineProperties[Type] }
-}[keyof TimelineProperties]
+>
 
 type DeepReadonly<Value> = Value extends readonly unknown[]
   ? { readonly [Key in keyof Value]: DeepReadonly<Value[Key]> }
@@ -99,6 +97,7 @@ export async function setupTimeline(
     locale?: string
     deviceScaleFactor?: number
     seedHistory?: boolean
+    protocol?: "v1" | "v2"
   } = {},
 ) {
   const sessions = input.sessions ?? [session()]
@@ -116,6 +115,7 @@ export async function setupTimeline(
     retry: input.eventRetry ?? 20,
   })
   await mockOpenCodeServer(page, {
+    protocol: input.protocol,
     directory,
     project: project(),
     provider: provider(),
@@ -235,7 +235,7 @@ export function event(type: TimelinePayload["type"], properties: TimelinePayload
 }
 
 export function validateTimelineEvent(input: unknown): TimelineEvent {
-  return decodeEvent(input, decodeOptions) as TimelineEvent
+  return decodeEvent(input, decodeOptions)
 }
 
 export function validateTimelineMessages(input: readonly TimelineMessage[]): TimelineMessage[] {
@@ -460,7 +460,7 @@ export function toolPart(
   input: Record<string, unknown>,
   options: ToolOptions<ToolStatus> = {},
 ): Omit<ToolPart, "sessionID" | "messageID"> {
-  const base = { id, type: "tool" as const, callID: id, tool }
+  const base = { id, type: "tool" as const, callID: `call_${id}`, tool }
   if (state === "pending") return { ...base, state: { status: state, input, raw: "" } }
   if (state === "running")
     return {

packages/app/e2e/performance/unit/mock-server.test.ts

@@ -1,121 +1,6 @@
 import { expect, test } from "bun:test"
-import type { SessionMessageInfo } from "@opencode-ai/client/promise"
 import type { Page, Route } from "@playwright/test"
-import { currentMessage, mockOpenCodeServer } from "../../utils/mock-server"
-
-test("preserves current messages", () => {
-  const message = {
-    id: "msg_current",
-    type: "user",
-    time: { created: 1 },
-    text: "current",
-    files: [{ data: "e30=", mime: "application/json", source: { type: "inline" } }],
-  } satisfies SessionMessageInfo
-
-  expect(currentMessage(message)).toBe(message)
-})
-
-test("converts rich legacy messages to current message types", () => {
-  expect(
-    currentMessage({
-      info: { id: "msg_user", role: "user", time: { created: 1 } },
-      parts: [
-        { type: "text", text: "Use @src/a.ts with @explore" },
-        {
-          type: "file",
-          mime: "application/json",
-          filename: "data.json",
-          url: "data:application/json;base64,e30=",
-        },
-        {
-          type: "file",
-          mime: "text/plain",
-          filename: "a.ts",
-          url: "src/a.ts",
-          source: { type: "file", text: { value: "@src/a.ts", start: 4, end: 13 } },
-        },
-        { type: "agent", name: "explore", source: { value: "@explore", start: 19, end: 27 } },
-      ],
-    }),
-  ).toEqual({
-    id: "msg_user",
-    type: "user",
-    time: { created: 1 },
-    text: "Use @src/a.ts with @explore",
-    files: [
-      { data: "e30=", mime: "application/json", name: "data.json", source: { type: "inline" } },
-      {
-        data: "",
-        mime: "text/plain",
-        name: "a.ts",
-        source: { type: "uri", uri: "src/a.ts" },
-        mention: { text: "@src/a.ts", start: 4, end: 13 },
-      },
-    ],
-    agents: [{ name: "explore", mention: { text: "@explore", start: 19, end: 27 } }],
-  })
-
-  expect(
-    currentMessage({
-      info: {
-        id: "msg_assistant",
-        role: "assistant",
-        time: { created: 2, completed: 5 },
-        agent: "explore",
-        modelID: "model",
-        providerID: "provider",
-        variant: "high",
-        cost: 0.5,
-        tokens: { input: 1, output: 2, reasoning: 3, cache: { read: 4, write: 5 } },
-        finish: "tool-calls",
-        error: { name: "MessageAbortedError", data: { message: "Stopped" } },
-      },
-      parts: [
-        { type: "text", text: "Answer" },
-        { type: "reasoning", text: "Thinking", time: { start: 2, end: 3 } },
-        {
-          id: "prt_tool",
-          callID: "call_tool",
-          type: "tool",
-          tool: "read",
-          state: {
-            status: "completed",
-            input: { filePath: "src/a.ts" },
-            output: "contents",
-            metadata: { title: "a.ts" },
-            time: { start: 3, end: 4 },
-          },
-        },
-      ],
-    }),
-  ).toEqual({
-    id: "msg_assistant",
-    type: "assistant",
-    time: { created: 2, completed: 5 },
-    agent: "explore",
-    model: { id: "model", providerID: "provider", variant: "high" },
-    cost: 0.5,
-    tokens: { input: 1, output: 2, reasoning: 3, cache: { read: 4, write: 5 } },
-    finish: "tool-calls",
-    error: { type: "MessageAbortedError", message: "Stopped" },
-    content: [
-      { type: "text", text: "Answer" },
-      { type: "reasoning", text: "Thinking", time: { created: 2, completed: 3 } },
-      {
-        type: "tool",
-        id: "call_tool",
-        name: "read",
-        time: { created: 3, ran: 3, completed: 4 },
-        state: {
-          status: "completed",
-          input: { filePath: "src/a.ts" },
-          content: [{ type: "text", text: "contents" }],
-          metadata: { title: "a.ts" },
-        },
-      },
-    ],
-  })
-})
+import { mockOpenCodeServer } from "../../utils/mock-server"
 
 test("applies message latency after a list response gate is released", async () => {
   const events: string[] = []
@@ -145,7 +30,7 @@ test("applies message latency after a list response gate is released", async ()
   })
 
   const response = handler!({
-    request: () => ({ url: () => "http://127.0.0.1:4096/api/session/session/message" }),
+    request: () => ({ url: () => "http://127.0.0.1:4096/session/session/message" }),
     fulfill: () => {
       events.push("fulfill")
       return Promise.resolve()

packages/app/e2e/regression/cross-server-tab-close.spec.ts

@@ -85,17 +85,21 @@ async function mockServers(page: Page, requests: string[]) {
     const current = url.origin === serverA ? sessionA : sessionB
     const directory = url.searchParams.get("directory")
     if (directory && directory !== current.directory) return json(route, { name: "InvalidDirectory" }, 500)
-    if (url.pathname === "/api/event")
+    if (url.pathname === "/global/event" || url.pathname === "/event" || url.pathname === "/api/event")
       return sse(route)
+    if (url.pathname === "/global/health") return json(route, {}, 404)
     if (url.pathname === "/api/health") return json(route, { pid: 1 })
     if (url.pathname === "/api/session") return json(route, { data: [currentSession(current)], cursor: {} })
     if (url.pathname === "/api/session/active") return json(route, { data: {} })
     if (url.pathname === `/api/session/${current.id}`) return json(route, { data: currentSession(current) })
     if (url.pathname === `/api/session/${current.id}/message`) return json(route, { data: [], cursor: {} })
+    if (url.pathname === `/session/${current.id}`) return json(route, current)
     if (/^\/session\/[^/]+$/.test(url.pathname)) return json(route, { name: "NotFoundError" }, 404)
+    if (url.pathname === `/session/${current.id}/message`) return json(route, [])
     if (/^\/session\/[^/]+\/(children|todo|diff)$/.test(url.pathname)) return json(route, [])
     if (["/skill", "/command", "/lsp", "/formatter", "/permission", "/question", "/vcs/diff"].includes(url.pathname))
       return json(route, [])
+    if (["/global/config", "/config", "/provider/auth", "/mcp"].includes(url.pathname)) return json(route, {})
     if (url.pathname === "/provider")
       return json(route, { all: [], connected: [], default: { providerID: "", modelID: "" } })
     if (url.pathname === "/agent") return json(route, [{ name: "build", mode: "primary" }])

packages/app/e2e/regression/remote-session-settings.spec.ts

@@ -3,7 +3,7 @@ import { expect, test, type Page, type Route } from "@playwright/test"
 import { installSseTransport } from "../utils/sse-transport"
 import { currentSession } from "../utils/mock-server"
 
-const serverA = `http://127.0.0.1:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
+const serverA = "http://127.0.0.1:4096"
 const serverB = "http://127.0.0.1:4097"
 const directoryA = "C:/server-a"
 const directoryB = "/home/server-b"
@@ -32,7 +32,7 @@ test("session settings use the remote server context", async ({ page }) => {
     .poll(() =>
       permissionRequests.some((request) => {
         const url = new URL(request)
-        return url.origin === serverB && url.searchParams.get("location[directory]") === directoryB
+        return url.origin === serverB && url.searchParams.get("directory") === directoryB
       }),
     )
     .toBe(true)
@@ -67,7 +67,7 @@ test("auto-accept responds for an unfocused server session", async ({ page }) =>
     .poll(() =>
       permissionRequests.some((request) => {
         const url = new URL(request)
-        return url.origin === serverA && url.searchParams.get("location[directory]") === directoryA
+        return url.origin === serverA && url.searchParams.get("directory") === directoryA
       }),
     )
     .toBe(true)
@@ -99,10 +99,10 @@ test("auto-accept responds for an unfocused server session", async ({ page }) =>
     .toEqual([
       {
         origin: serverA,
-        directory: undefined,
+        directory: directoryA,
         sessionID: sessionA.id,
         permissionID: "permission-background-a",
-        body: { reply: "once" },
+        body: { response: "once" },
       },
     ])
 
@@ -127,17 +127,17 @@ test("auto-accept responds for an unfocused server session", async ({ page }) =>
     .toEqual([
       {
         origin: serverA,
-        directory: undefined,
+        directory: directoryA,
         sessionID: sessionA.id,
         permissionID: "permission-background-a",
-        body: { reply: "once" },
+        body: { response: "once" },
       },
       {
         origin: serverA,
-        directory: undefined,
+        directory: directoryA,
         sessionID: childSessionA.id,
         permissionID: "permission-background-a-child",
-        body: { reply: "once" },
+        body: { response: "once" },
       },
     ])
 })
@@ -168,8 +168,8 @@ async function mockServers(page: Page, permissionRequests: string[], permissionR
     const remote = url.origin === serverB
     const directory = remote ? directoryB : directoryA
     const sessions = remote ? [sessionB] : [sessionA, childSessionA]
-    const requestDirectory = url.searchParams.get("location[directory]")
-    const response = url.pathname.match(/^\/api\/session\/([^/]+)\/permission\/([^/]+)\/reply$/)
+    const requestDirectory = url.searchParams.get("directory")
+    const response = url.pathname.match(/^\/session\/([^/]+)\/permissions\/([^/]+)$/)
     if (route.request().method() === "POST" && response) {
       permissionResponses.push({
         origin: url.origin,
@@ -181,21 +181,13 @@ async function mockServers(page: Page, permissionRequests: string[], permissionR
       return json(route, true)
     }
     if (requestDirectory && requestDirectory !== directory) return json(route, { name: "InvalidDirectory" }, 500)
-    if (url.pathname === "/api/event")
+    if (url.pathname === "/global/event" || url.pathname === "/event" || url.pathname === "/api/event")
       return sse(route)
-    if (url.pathname === "/api/provider")
-      return json(route, {
-        location: { directory },
-        data: [{ id: remote ? "server-b" : "server-a", name: remote ? "Server B Provider" : "Server A Provider", package: "test" }],
-      })
-    if (url.pathname === "/api/model") return json(route, { location: { directory }, data: [model(remote)] })
-    if (url.pathname === "/api/model/default") return json(route, { location: { directory }, data: model(remote) })
-    if (url.pathname === "/api/agent") return json(route, { location: { directory }, data: [] })
-    if (url.pathname === "/api/permission/request") {
-      permissionRequests.push(url.toString())
-      return json(route, { location: { directory }, data: [] })
-    }
-    if (["/api/command", "/api/reference", "/api/question/request"].includes(url.pathname))
+    if (url.pathname === "/global/health") return json(route, { healthy: true })
+    if (url.pathname === "/api/provider" || url.pathname === "/api/model" || url.pathname === "/api/agent")
+      return json(route, { data: [] })
+    if (url.pathname === "/api/model/default") return json(route, { data: null })
+    if (["/api/command", "/api/reference", "/api/permission/request", "/api/question/request"].includes(url.pathname))
       return json(route, { location: { directory }, data: [] })
     if (url.pathname === "/api/mcp") return json(route, { location: { directory }, data: [] })
     if (url.pathname === "/api/mcp/resource")
@@ -219,6 +211,8 @@ async function mockServers(page: Page, permissionRequests: string[], permissionR
     if (currentSessionInfo) return json(route, { data: currentSession(currentSessionInfo) })
     if (sessions.some((session) => url.pathname === `/api/session/${session.id}/message`))
       return json(route, { data: [], cursor: {} })
+    const current = sessions.find((session) => url.pathname === `/session/${session.id}`)
+    if (current) return json(route, current)
     if (/^\/session\/[^/]+$/.test(url.pathname)) return json(route, { name: "NotFoundError" }, 404)
     if (/^\/session\/[^/]+\/message$/.test(url.pathname)) return json(route, [])
     if (/^\/session\/[^/]+\/(children|todo|diff)$/.test(url.pathname)) return json(route, [])
@@ -228,6 +222,7 @@ async function mockServers(page: Page, permissionRequests: string[], permissionR
     }
     if (["/skill", "/command", "/lsp", "/formatter", "/question", "/vcs/diff", "/pty/shells"].includes(url.pathname))
       return json(route, [])
+    if (["/global/config", "/config", "/provider/auth", "/mcp"].includes(url.pathname)) return json(route, {})
     if (url.pathname === "/provider") return json(route, provider(remote ? "server-b" : "server-a"))
     if (url.pathname === "/agent") return json(route, [{ name: "build", mode: "primary" }])
     if (url.pathname === "/project" || url.pathname === "/project/current") {
@@ -293,25 +288,6 @@ function provider(id: string) {
   }
 }
 
-function model(remote: boolean) {
-  const id = remote ? "server-b" : "server-a"
-  const name = remote ? "Server B" : "Server A"
-  return {
-    id,
-    modelID: id,
-    providerID: id,
-    name: `${name} Model`,
-    family: id,
-    capabilities: { tools: true, input: ["text"], output: ["text"] },
-    variants: [],
-    time: { released: Date.now() },
-    cost: [{ input: 0, output: 0, cache: { read: 0, write: 0 } }],
-    status: "active",
-    enabled: true,
-    limit: { context: 200_000, output: 32_000 },
-  }
-}
-
 function json(route: Route, body: unknown, status = 200) {
   return route.fulfill({
     status,

packages/app/e2e/regression/remote-tab-busy.spec.ts

@@ -58,18 +58,22 @@ async function mockServers(page: Page) {
     const current = url.origin === serverA ? sessionA : sessionB
     const directory = url.searchParams.get("directory")
     if (directory && directory !== current.directory) return json(route, { name: "InvalidDirectory" }, 500)
-    if (url.pathname === "/api/event")
+    if (url.pathname === "/global/event" || url.pathname === "/event" || url.pathname === "/api/event")
       return sse(route, url.pathname === "/api/event")
+    if (url.pathname === "/global/health") return json(route, {}, 404)
     if (url.pathname === "/api/health") return json(route, { pid: 1 })
     if (url.pathname === "/api/session/active")
       return json(route, { data: url.origin === serverB ? { [sessionB.id]: { type: "running" } } : {} })
     if (url.pathname === "/api/session") return json(route, { data: [currentSession(current)], cursor: {} })
     if (url.pathname === `/api/session/${current.id}`) return json(route, { data: currentSession(current) })
     if (url.pathname === `/api/session/${current.id}/message`) return json(route, { data: [], cursor: {} })
+    if (url.pathname === `/session/${current.id}`) return json(route, current)
     if (/^\/session\/[^/]+$/.test(url.pathname)) return json(route, { name: "NotFoundError" }, 404)
+    if (url.pathname === `/session/${current.id}/message`) return json(route, [])
     if (/^\/session\/[^/]+\/(children|todo|diff)$/.test(url.pathname)) return json(route, [])
     if (["/skill", "/command", "/lsp", "/formatter", "/permission", "/question", "/vcs/diff"].includes(url.pathname))
       return json(route, [])
+    if (["/global/config", "/config", "/provider/auth", "/mcp"].includes(url.pathname)) return json(route, {})
     if (url.pathname === "/provider")
       return json(route, { all: [], connected: [], default: { providerID: "", modelID: "" } })
     if (url.pathname === "/agent") return json(route, [{ name: "build", mode: "primary" }])

packages/app/e2e/regression/review-open-file.spec.ts

@@ -127,7 +127,7 @@ test("opens and searches project files inline", async ({ page }) => {
   await expect(panel.getByRole("tab", { name: "nested.ts" })).toHaveAttribute("data-selected", "")
   await expect(sidebarToggle).toBeEnabled()
   await expect(panel.getByText("contents:src/nested.ts", { exact: true })).toBeVisible()
-  expect(searches).toContainEqual({ query: "nested", dirs: "file", limit: 200 })
+  expect(searches).toContainEqual({ query: "nested", dirs: "false", limit: 200 })
 
   await panel.getByRole("button", { name: "Open file" }).click()
   await expect(panel.getByRole("tab", { name: "nested.ts" })).toHaveCount(1)

packages/app/e2e/regression/review-state-persistence.spec.ts

@@ -19,25 +19,36 @@ test("restores review mode and selected file per session", async ({ page }) => {
   await expectSessionTitle(page, titleA)
   await page.getByRole("button", { name: "Toggle review" }).click()
 
-  await selectFile(page, "alpha.ts")
+  await selectMode(page, "Git changes", "Branch changes")
+  await selectFile(page, "beta.ts")
 
   await switchSession(page, titleB)
   await expect(page.getByRole("button", { name: "Git changes" })).toBeVisible()
   await selectFile(page, "gamma.ts")
 
   await switchSession(page, titleA)
+  await expect(page.getByRole("button", { name: "Branch changes" })).toBeVisible()
+  await expectSelectedFile(page, "beta.ts")
+  await selectMode(page, "Branch changes", "Git changes")
   await expectSelectedFile(page, "alpha.ts")
+  await selectMode(page, "Git changes", "Branch changes")
+  await expectSelectedFile(page, "beta.ts")
 
   await page.reload()
   await expectSessionTitle(page, titleA)
-  await expect(page.getByRole("button", { name: "Git changes" })).toBeVisible()
-  await expectSelectedFile(page, "alpha.ts")
+  await expect(page.getByRole("button", { name: "Branch changes" })).toBeVisible()
+  await expectSelectedFile(page, "beta.ts")
 
   await switchSession(page, titleB)
   await expect(page.getByRole("button", { name: "Git changes" })).toBeVisible()
   await expectSelectedFile(page, "gamma.ts")
 })
 
+async function selectMode(page: Page, current: string, next: string) {
+  await page.getByRole("button", { name: current }).click()
+  await page.getByRole("option", { name: next }).dispatchEvent("click")
+}
+
 async function selectFile(page: Page, file: string) {
   await page.getByRole("button", { name: file }).click()
   await expectSelectedFile(page, file)
@@ -54,6 +65,7 @@ async function switchSession(page: Page, title: string) {
 
 async function setup(page: Page) {
   await mockOpenCodeServer(page, {
+    protocol: "v1",
     directory,
     project: {
       id: projectID,
@@ -77,27 +89,22 @@ async function setup(page: Page) {
     sessions: [session(sessionA, titleA, 1700000000000), session(sessionB, titleB, 1700000001000)],
     pageMessages: () => ({ items: [] }),
   })
-  await page.route(/\/api\/vcs(?:\?.*)?$/, (route) =>
+  await page.route(/\/vcs(?:\?.*)?$/, (route) =>
     route.fulfill({
       status: 200,
       contentType: "application/json",
-      body: JSON.stringify({
-        location: { directory, project: { id: projectID, directory, canonical: directory } },
-        data: { branch: "feature", defaultBranch: "dev" },
-      }),
+      body: JSON.stringify({ branch: "feature", default_branch: "dev" }),
     }),
   )
-  await page.route("**/api/vcs/diff**", (route) =>
+  await page.route("**/vcs/diff**", (route) =>
     route.fulfill({
       status: 200,
       contentType: "application/json",
-      body: JSON.stringify({
-        location: { directory, project: { id: projectID, directory, canonical: directory } },
-        data:
-          new URL(route.request().url()).searchParams.get("mode") === "branch"
-            ? [diff("src/alpha.ts"), diff("src/beta.ts")]
-            : [diff("src/alpha.ts"), diff("src/gamma.ts")],
-      }),
+      body: JSON.stringify(
+        new URL(route.request().url()).searchParams.get("mode") === "branch"
+          ? [diff("src/alpha.ts"), diff("src/beta.ts")]
+          : [diff("src/alpha.ts"), diff("src/gamma.ts")],
+      ),
     }),
   )
   await page.addInitScript(

packages/app/e2e/regression/review-terminal-stacked.spec.ts

@@ -25,6 +25,7 @@ test("keeps the review tree and terminal sized when both panels are open", async
   let detailFailures = 1
   await page.setViewportSize({ width: 1400, height: 900 })
   await mockOpenCodeServer(page, {
+    protocol: "v1",
     directory,
     project: {
       id: projectID,
@@ -61,32 +62,33 @@ test("keeps the review tree and terminal sized when both panels are open", async
     events: () => events.splice(0, 1),
     eventRetry: 16,
   })
-  await page.route(/\/api\/vcs(?:\?.*)?$/, (route) =>
+  await page.route(/\/vcs(?:\?.*)?$/, (route) =>
     route.fulfill({
       status: 200,
       contentType: "application/json",
       body: JSON.stringify({
-        location: { directory, project: { id: projectID, directory, canonical: directory } },
-        data: { branch: "review-pane-performance", defaultBranch: "dev" },
+        branch: "review-pane-performance",
+        default_branch: "dev",
       }),
     }),
   )
-  await page.route("**/api/vcs/diff**", (route) => {
+  await page.route("**/vcs/diff**", (route) => {
     const url = new URL(route.request().url())
-    const scope = url.searchParams.get("location[directory]")?.replaceAll("\\", "/")
+    const scope = url.searchParams.get("directory")?.replaceAll("\\", "/")
     const detail = scope?.endsWith("/src/branch/d00027")
     if (detail && detailFailures-- > 0) return route.fulfill({ status: 500, body: "retry detail" })
     return route.fulfill({
       status: 200,
       contentType: "application/json",
-      body: JSON.stringify({
-        location: { directory, project: { id: projectID, directory, canonical: directory } },
-        data: detail
-          ? branchDiffs
-              .filter((diff) => diff.file.startsWith("src/branch/d00027/"))
-              .map((diff) => fileDiff(diff.file, diff.additions, true, detailVersion))
-          : branchDiffs,
-      }),
+      body: JSON.stringify(
+        url.searchParams.get("mode") === "branch"
+          ? detail
+            ? branchDiffs
+                .filter((diff) => diff.file.startsWith("src/branch/d00027/"))
+                .map((diff) => fileDiff(diff.file, diff.additions, true, detailVersion))
+            : branchDiffs
+          : Array.from({ length: 7 }, (_, index) => fileDiff(`src/git-${index}.ts`, 1)),
+      ),
     })
   })
   await page.route("**/pty*", (route) =>
@@ -107,7 +109,7 @@ test("keeps the review tree and terminal sized when both panels are open", async
       }),
     }),
   )
-  await page.route("**/api/pty/pty_review_terminal*", (route) =>
+  await page.route("**/pty/pty_review_terminal*", (route) =>
     route.fulfill({
       status: 200,
       contentType: "application/json",
@@ -125,7 +127,7 @@ test("keeps the review tree and terminal sized when both panels are open", async
       }),
     }),
   )
-  await page.route("**/api/pty/pty_review_terminal/connect-token*", (route) =>
+  await page.route("**/pty/pty_review_terminal/connect-token*", (route) =>
     route.fulfill({
       status: 200,
       contentType: "application/json",
@@ -135,7 +137,7 @@ test("keeps the review tree and terminal sized when both panels are open", async
       }),
     }),
   )
-  await page.routeWebSocket("**/api/pty/pty_review_terminal/connect", () => undefined)
+  await page.routeWebSocket("**/pty/pty_review_terminal/connect", () => undefined)
   await page.addInitScript(() => {
     localStorage.setItem("settings.v3", JSON.stringify({ general: { newLayoutDesigns: true } }))
     localStorage.setItem(
@@ -147,7 +149,9 @@ test("keeps the review tree and terminal sized when both panels are open", async
   await page.goto(`/${base64Encode(directory)}/session/${sessionID}`)
   await expectSessionTitle(page, title)
   await expect(page.locator("#review-panel")).toBeVisible()
-  await expectTree(page, 2_773, "action.yml")
+  await expectTree(page, 8, "git-0.ts")
+
+  await selectMode(page, "Git changes", "Branch changes")
   await expect(page.locator("#session-side-panel-review-tab")).toHaveText("Files Changed 2740")
   await page.keyboard.press("Control+Backquote")
   await expect(page.locator("#terminal-panel")).toBeVisible()
@@ -170,9 +174,9 @@ test("keeps the review tree and terminal sized when both panels are open", async
   expect(bottomGap).toBeLessThanOrEqual(16)
   const lazyDiff = page.waitForRequest((request) => {
     const url = new URL(request.url())
-      return (
-        url.pathname === "/api/vcs/diff" &&
-      url.searchParams.get("location[directory]")?.replaceAll("\\", "/").endsWith("/src/branch/d00027") === true
+    return (
+      url.pathname === "/vcs/diff" &&
+      url.searchParams.get("directory")?.replaceAll("\\", "/").endsWith("/src/branch/d00027") === true
     )
   })
   await lastFile.click()
@@ -186,46 +190,59 @@ test("keeps the review tree and terminal sized when both panels are open", async
   const refreshedDiff = page.waitForRequest((request) => {
     const url = new URL(request.url())
     return (
-      url.pathname === "/api/vcs/diff" &&
-      url.searchParams.get("location[directory]")?.replaceAll("\\", "/").endsWith("/src/branch/d00027") === true
+      url.pathname === "/vcs/diff" &&
+      url.searchParams.get("directory")?.replaceAll("\\", "/").endsWith("/src/branch/d00027") === true
     )
   })
   sessionStatus[sessionID] = { type: "idle" }
   events.push(statusEvent("idle"))
   await refreshedDiff
   await expect(preview).toContainText("after-2")
+  await selectMode(page, "Branch changes", "Git changes")
+  await expectTree(page, 8, "git-0.ts")
+  await page.getByRole("button", { name: "git-0.ts" }).click()
+  await selectMode(page, "Git changes", "Branch changes")
+  await expectTree(page, 2_773, "action.yml")
+
   const filter = page.getByRole("searchbox", { name: "Filter files" })
   await filter.fill("generated-2738")
   await expectTree(page, 1, "generated-2738.ts")
   await filter.fill("")
-  await expectTree(page, 2_773, "generated-2738.ts")
+  await expectTree(page, 2_773, "action.yml")
 
   await page.getByRole("button", { name: "Toggle file tree" }).click()
   await expect(page.locator('[data-slot="session-review-v2-sidebar"]')).toHaveCount(0)
   await expect(page.locator('#review-panel [data-component="file-tree-v2"]')).toHaveCount(0)
   await page.getByRole("button", { name: "Toggle file tree" }).click()
-  await expectTree(page, 2_773, "generated-2738.ts")
+  await expectTree(page, 2_773, "action.yml")
 
   await page.keyboard.press("Control+Backquote")
   await expect(page.locator("#terminal-panel")).toHaveCount(0)
-  await expectTree(page, 2_773, "generated-2738.ts")
+  await expectTree(page, 2_773, "action.yml")
   await page.keyboard.press("Control+Backquote")
   await expect(page.locator("#terminal-panel")).toBeVisible()
-  await expectTree(page, 2_773, "generated-2738.ts")
+  await expectTree(page, 2_773, "action.yml")
 
   await page.getByRole("button", { name: "Toggle review" }).click()
   await expect(page.locator("#review-panel")).toHaveCount(0)
   await page.getByRole("button", { name: "Toggle review" }).click()
-  await expectTree(page, 2_773, "generated-2738.ts")
+  await expectTree(page, 2_773, "action.yml")
   await page.setViewportSize({ width: 1_000, height: 700 })
-  await expectTree(page, 2_773, "generated-2738.ts")
+  await expectTree(page, 2_773, "action.yml")
   await expectStackGeometry(page)
   await page.setViewportSize({ width: 1_000, height: 120 })
   await page.setViewportSize({ width: 1_400, height: 900 })
-  await expectTree(page, 2_773, "generated-2738.ts")
+  await expectTree(page, 2_773, "action.yml")
   await expectStackGeometry(page)
 })
 
+async function selectMode(page: Page, current: string, next: string) {
+  await page.getByRole("button", { name: current }).click()
+  const option = page.getByRole("option", { name: next })
+  await expect(option).toBeVisible()
+  await option.click()
+}
+
 async function expectTree(page: Page, total: number, file: string) {
   await expectMountedTree(page, total)
   await expect(page.getByRole("button", { name: file })).toBeVisible()

packages/app/e2e/regression/session-request-docks.spec.ts

@@ -173,6 +173,7 @@ async function mockServer(
   },
 ) {
   await mockOpenCodeServer(page, {
+    protocol: "v2",
     directory,
     project: {
       id: projectID,

packages/app/e2e/regression/session-timeline-collapse-state.spec.ts

@@ -52,7 +52,7 @@ const editPart = {
   sessionID,
   messageID: assistantMessageID,
   type: "tool",
-  callID: editPartID,
+  callID: "call_edit_regression",
   tool: "edit",
   state: {
     status: "completed",

packages/app/e2e/regression/session-timeline-context-resize.spec.ts

@@ -14,8 +14,8 @@ const projectID = "proj_context_resize_regression"
 const sessionID = "ses_context_resize_regression"
 const title = "Context resize regression"
 const model = { providerID: "opencode", modelID: "claude-opus-4-6", variant: "max" }
-const contextIDs = ["ctx_0100_read", "ctx_0101_glob", "ctx_0102_grep", "ctx_0103_list"]
-const followingTextID = `${id("msg_assistant", 10)}:text:0`
+const contextIDs = ["prt_0100_read", "prt_0101_glob", "prt_0102_grep", "prt_0103_list"]
+const followingTextID = "prt_0104_text"
 
 type Message = {
   info: Record<string, unknown> & { id: string; role: "user" | "assistant" }
@@ -263,7 +263,7 @@ function turn(index: number, target: boolean, status: "running" | "completed" =
             ),
             contextTool(contextIDs[3]!, assistantID, "list", { path: "src" }, status),
             {
-              id: "prt_0104_text",
+              id: followingTextID,
               sessionID,
               messageID: assistantID,
               type: "text",
@@ -295,7 +295,7 @@ function contextTool(
     sessionID,
     messageID,
     type: "tool",
-    callID: partID,
+    callID: `call_${partID}`,
     tool,
     state: {
       status,

packages/app/e2e/regression/session-timeline-history-root.spec.ts

@@ -10,6 +10,7 @@ import {
   status,
   textPart,
   title,
+  userID,
   userMessage,
 } from "../performance/timeline-stability/fixture"
 import { mockOpenCodeServer } from "../utils/mock-server"
@@ -18,22 +19,18 @@ import { expectSessionTitle } from "../utils/waits"
 
 const initialPageSize = 20
 const historyPageSize = 200
-const messages = Array.from({ length: initialPageSize + 1 }, (_, index) => {
-  const id = `msg_${String(index + 1001).padStart(4, "0")}_history_root_user`
-  return [
-    userMessage(undefined, { id, created: 1700000000000 + index * 2_000 }),
-    assistantMessage([textPart(`prt_history_root_${index}`, `Assistant response ${index}`)], {
-      id: `msg_${String(index + 1001).padStart(4, "0")}_history_root_assistant`,
-      parentID: id,
-      created: 1700000001000 + index * 2_000,
-      completed: index < initialPageSize,
-    }),
-  ]
-}).flat()
-const assistants = messages.filter((message) => message.info.role === "assistant")
+const assistants = Array.from({ length: initialPageSize + 1 }, (_, index) =>
+  assistantMessage([textPart(`prt_history_root_${index}`, `Assistant response ${index}`)], {
+    id: `msg_${String(index + 1001).padStart(4, "0")}_history_root_assistant`,
+    parentID: userID,
+    created: 1700000001000 + index * 1_000,
+    completed: index < initialPageSize,
+  }),
+)
+const messages = [userMessage(), ...assistants]
 const lastAssistant = assistants.at(-1)!
-const lastPartID = `${assistants.at(-1)!.info.id}:text:0`
-const userPartID = `${messages.at(-2)!.info.id}:text:0`
+const lastPartID = assistants.at(-1)!.parts[0]!.id
+const userPartID = `prt_${userID}_text`
 const completed = {
   ...lastAssistant.info,
   time: { ...lastAssistant.info.time, completed: lastAssistant.info.time.created + 15_000 },
@@ -157,23 +154,15 @@ for (const scenario of scenarios) {
     await expectSessionTitle(page, title)
     await expect(page.locator(`[data-timeline-part-id="${lastPartID}"]`)).toBeVisible()
     await expect(page.locator(`[data-timeline-part-id="${userPartID}"]`)).toBeVisible()
-    const viewport = page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
-    await viewport.hover()
-    const deadline = Date.now() + 10_000
-    while (requests.filter((request) => request.phase === "start").length < 2) {
-      if (Date.now() >= deadline) throw new Error("Timed out scrolling to the history boundary")
-      await page.mouse.wheel(0, -240)
-      await page.waitForTimeout(20)
-    }
+    await expect.poll(() => requests.filter((request) => request.phase === "start").length).toBe(2)
     expect(requests.filter((request) => request.phase === "end")).toHaveLength(1)
-    expect(sequence.slice(0, 3)).toEqual([
+    expect(sequence.slice(0, 4)).toEqual([
       "messages:start:latest",
       "messages:end:latest",
+      `message:${userID}`,
       `messages:start:${messages.at(-initialPageSize)!.info.id}`,
     ])
-    await expect(page.locator('[data-timeline-part-id*="_history_root_assistant:text:0"]')).toHaveCount(
-      initialPageSize / 2,
-    )
+    await expect(page.locator('[data-timeline-part-id^="prt_history_root_"]')).toHaveCount(initialPageSize)
     await page.evaluate(() => {
       ;(
         window as Window & {
@@ -185,9 +174,7 @@ for (const scenario of scenarios) {
     expect(await visibleContentHidden(page)).toBe(false)
     const beforeHistory = await probeSamples(page)
     history.resolve()
-    await expect
-      .poll(() => page.locator('[data-timeline-part-id*="_history_root_assistant:text:0"]').count())
-      .toBeGreaterThan(initialPageSize / 2)
+    await expect(page.locator('[data-timeline-part-id^="prt_history_root_"]')).toHaveCount(assistants.length)
     await expect.poll(() => requests.filter((request) => request.phase === "end").length).toBe(2)
     await expect(page.getByRole("button", { name: "Stop" })).toBeVisible()
     await waitForProbeSamples(page, beforeHistory)
@@ -195,7 +182,7 @@ for (const scenario of scenarios) {
       { before: undefined, limit: initialPageSize },
       { before: messages.at(-initialPageSize)!.info.id, limit: historyPageSize },
     ])
-    expect(roots).toEqual([])
+    expect(roots).toEqual([{ sessionID, messageID: userID }])
 
     const message = messageUpdated(scenario.info)
     const idle = status("idle")

packages/app/e2e/regression/session-timeline-lifecycle-state.spec.ts

@@ -103,7 +103,7 @@ test("moves busy through retry and recovery to final idle content", async ({ pag
   await timeline.send(status("idle"), 350)
   await expect(page.locator('[data-timeline-row="Retry"]')).toHaveCount(0)
   await expect(page.locator('[data-timeline-row="Thinking"]')).toHaveCount(0)
-  await expect(page.locator('[data-timeline-part-id="prt_recovered"]')).toContainText("Recovered response")
+  await expect(page.locator('[data-timeline-row="DiffSummary"]')).toBeVisible()
 })
 
 function lines(count: number) {

packages/app/e2e/regression/session-timeline-projection.spec.ts

@@ -89,6 +89,7 @@ test.describe("session timeline projection", () => {
     const aborted = assistantMessage(
       [
         { id: "prt_before_abort", type: "text", text: "Before interruption" },
+        { id: "prt_compaction", type: "compaction", auto: true },
       ],
       {
         id: "msg_1001_assistant_aborted",
@@ -121,13 +122,13 @@ test.describe("session timeline projection", () => {
     await scroller.evaluate((element) => (element.scrollTop = 0))
 
     await expect(page.locator('[data-timeline-row="TurnDivider"]')).toHaveCount(1)
-    await expect(page.getByText("Before interruption", { exact: true })).toBeVisible()
+    await expect(page.getByText("Session compacted", { exact: true })).toBeVisible()
     await expect(page.getByText("Visible provider failure")).toBeVisible()
     await scroller.evaluate((element) => (element.scrollTop = element.scrollHeight))
     await expect(page.locator('[data-timeline-row="TurnGap"]')).toBeVisible()
   })
 
-  test("renders legacy synthetic comments as ordinary V2 user text", async ({ page }) => {
+  test("renders comment strips and historical diff summary overflow", async ({ page }) => {
     const user = userMessage(
       [
         userText("The user made the following comment regarding lines 4 through 8 of src/a.ts: Keep this stable", {
@@ -158,14 +159,10 @@ test.describe("session timeline projection", () => {
     const scroller = page.locator(".scroll-view__viewport", { has: page.locator("[data-timeline-row]") })
     await scroller.evaluate((element) => (element.scrollTop = 0))
 
-    await expect(
-      page.getByText(
-        "The user made the following comment regarding lines 4 through 8 of src/a.ts: Keep this stable Continue after the comment",
-        { exact: true },
-      ),
-    ).toBeVisible()
-    await expect(page.locator('[data-timeline-row="CommentStrip"]')).toHaveCount(0)
-    await expect(page.locator('[data-timeline-row="DiffSummary"]')).toHaveCount(0)
+    await expect(page.locator('[data-timeline-row="CommentStrip"]')).toBeVisible()
+    await expect(page.getByText("Keep this stable", { exact: true })).toBeVisible()
+    await expect(page.locator('[data-timeline-row="DiffSummary"]')).toBeVisible()
+    await expect(page.getByText(/show all/i)).toBeVisible()
   })
 
   test("renders interruption independently when the turn is not compacted", async ({ page }) => {

packages/app/e2e/regression/session-timeline-reasoning-projection.spec.ts

@@ -1,6 +1,5 @@
 import { expect, test } from "@playwright/test"
 import {
-  assistantID,
   assistantMessage,
   reasoningPart,
   setupTimeline,
@@ -71,7 +70,7 @@ for (const profile of profiles) {
     await timeline.send(status("busy"), 150)
 
     await expect(page.locator('[data-timeline-row="Thinking"]')).toHaveCount(profile.thinking ? 1 : 0)
-    await expect(page.locator(`[data-timeline-part-id="${assistantID}:reasoning:0"]`)).toHaveCount(profile.body ? 1 : 0)
+    await expect(page.locator(`[data-timeline-part-id="${reasoningID}"]`)).toHaveCount(profile.body ? 1 : 0)
     if (!profile.summaries && profile.reasoning.trim()) {
       await expect(page.getByText("Inspecting stability", { exact: true })).toBeVisible()
     }
@@ -90,5 +89,5 @@ test("does not infer reasoning visibility from provider identity", async ({ page
 
   await expect(page.locator('[data-timeline-row="Thinking"]')).toHaveCount(0)
   await expect(page.locator('[data-timeline-part-id*="reasoning"]')).toHaveCount(0)
-  await expect(page.locator(`[data-timeline-part-id="${assistantID}:text:0"]`)).toBeVisible()
+  await expect(page.locator('[data-timeline-part-id="prt_provider_text"]')).toBeVisible()
 })

packages/app/e2e/regression/session-timeline-reducer-projection.spec.ts

@@ -23,11 +23,10 @@ test("groups singleton and separated context operations at correct boundaries",
   ]
   await setupTimeline(page, { messages: [userMessage(), assistantMessage(parts)] })
 
-  await expect(
-    page.locator('[data-timeline-part-ids="prt_boundary_01_read,prt_boundary_03_glob,prt_boundary_04_grep"]'),
-  ).toBeVisible()
+  await expect(page.locator('[data-timeline-part-ids="prt_boundary_01_read"]')).toBeVisible()
+  await expect(page.locator('[data-timeline-part-ids="prt_boundary_03_glob,prt_boundary_04_grep"]')).toBeVisible()
   await expect(page.locator('[data-timeline-part-ids="prt_boundary_06_list"]')).toBeVisible()
-  await expect(page.locator('[data-timeline-row="AssistantPart"]')).toHaveCount(4)
+  await expect(page.locator('[data-timeline-row="AssistantPart"]')).toHaveCount(5)
 })
 
 test("reducer-hardening: converges when idle arrives before final part and message completion", async ({ page }) => {

packages/app/e2e/regression/session-timeline-shell-outline.spec.ts

@@ -145,6 +145,7 @@ test("allows paint rounding for every framed row but not fixed turn gaps", async
       }),
     ],
   })
+  await expect(page.locator('[data-timeline-row="DiffSummary"]')).toBeVisible()
   await expect(page.locator('[data-timeline-row="TurnGap"]')).toBeVisible()
 
   const rows = await page.locator("[data-timeline-key]").evaluateAll((elements) =>

packages/app/e2e/regression/session-timeline-transport.spec.ts

@@ -90,7 +90,7 @@ test("reconnects after a stream error", async ({ page }) => {
 })
 
 test("does not request replay when reconnecting the volatile V2 event stream", async ({ page }) => {
-  const timeline = await setupTimeline(page, { eventRetry: 10 })
+  const timeline = await setupTimeline(page, { eventRetry: 10, protocol: "v2" })
   const first = await timeline.transport.send(partUpdated(textPart("prt_transport_id", "event with id")), {
     id: "timeline-event-7",
   })
@@ -107,10 +107,10 @@ test("passes through non-event fetches", async ({ page }) => {
   const timeline = await setupTimeline(page)
 
   const health = await page.evaluate(async () => {
-    const response = await fetch("/api/health")
+    const response = await fetch("/global/health")
     return response.json()
   })
 
-  expect(health).toEqual({ healthy: true, version: "2.0.0", pid: 1 })
+  expect(health).toEqual({ healthy: true })
   expect(await timeline.transport.connections()).toHaveLength(1)
 })

packages/app/e2e/regression/session-todo-dock-navigation.spec.ts

@@ -23,7 +23,7 @@ type EventPayload = {
 
 test.use({ viewport: { width: 1440, height: 900 }, reducedMotion: "no-preference" })
 
-test("animates todo opening without replaying it across session tabs", async ({ page }) => {
+test("animates todo lifecycle without replaying it across session tabs", async ({ page }) => {
   test.setTimeout(90_000)
   const events: EventPayload[] = []
   const todos: Record<string, typeof activeTodos> = { [sourceID]: [], [otherID]: [] }
@@ -86,8 +86,28 @@ test("animates todo opening without replaying it across session tabs", async ({
   await switchSession(page, otherID, otherTitle)
   await expect(dock).toHaveCount(0)
 
+  const returningOpen = sampleDock(page, 700)
+  await switchSession(page, sourceID, sourceTitle)
+  const openSamples = (await returningOpen).filter((sample) => sample.present)
+  expect(openSamples.length).toBeGreaterThan(0)
+  expect(openSamples[0]!.opacity).toBeGreaterThan(0.98)
+  expect(openSamples[0]!.height).toBeGreaterThan(70)
+  await expect(dock.locator('[data-state="in_progress"]')).toHaveCount(1)
+
+  const completedTodos = activeTodos.map((todo) => ({ ...todo, status: "completed" }))
+  const closing = sampleDock(page, 1_000)
+  todos[sourceID] = completedTodos
+  events.push(todoEvent(sourceID, completedTodos))
+  await expect(dock).toHaveCount(0)
+  expect((await closing).some((sample) => sample.opacity > 0.05 && sample.opacity < 0.95)).toBe(true)
+  todos[sourceID] = []
+  events.push(todoEvent(sourceID, []))
+
+  await switchSession(page, otherID, otherTitle)
+  const returningEmpty = sampleDock(page, 700)
   await switchSession(page, sourceID, sourceTitle)
   await expect(dock).toHaveCount(0)
+  expect((await returningEmpty).every((sample) => !sample.present)).toBe(true)
 })
 
 function session(id: string, title: string, created: number) {

packages/app/e2e/regression/tab-navigate-mousedown.spec.ts

@@ -89,19 +89,23 @@ async function mockServer(page: Page) {
     if (url.origin !== server) return route.fallback()
     if ([`/api/session/${unresolvedSessionID}`, `/session/${unresolvedSessionID}`].includes(url.pathname))
       return new Promise(() => {})
-    if (url.pathname === "/api/event")
+    if (url.pathname === "/global/event" || url.pathname === "/event" || url.pathname === "/api/event")
       return sse(route)
+    if (url.pathname === "/global/health") return json(route, { healthy: true })
     if (url.pathname === "/api/session") return json(route, { data: sessions.map(currentSession), cursor: {} })
     if (url.pathname === "/api/session/active") return json(route, { data: {} })
     const currentSessionInfo = sessions.find((item) => url.pathname === `/api/session/${item.id}`)
     if (currentSessionInfo) return json(route, { data: currentSession(currentSessionInfo) })
     if (sessions.some((item) => url.pathname === `/api/session/${item.id}/message`))
       return json(route, { data: [], cursor: {} })
+    const byId = sessions.find((item) => url.pathname === `/session/${item.id}`)
+    if (byId) return json(route, byId)
     if (/^\/session\/[^/]+$/.test(url.pathname)) return json(route, { name: "NotFoundError" }, 404)
     if (/^\/session\/[^/]+\/message$/.test(url.pathname)) return json(route, [])
     if (/^\/session\/[^/]+\/(children|todo|diff)$/.test(url.pathname)) return json(route, [])
     if (["/skill", "/command", "/lsp", "/formatter", "/permission", "/question", "/vcs/diff"].includes(url.pathname))
       return json(route, [])
+    if (["/global/config", "/config", "/provider/auth", "/mcp"].includes(url.pathname)) return json(route, {})
     if (url.pathname === "/provider")
       return json(route, { all: [], connected: [], default: { providerID: "", modelID: "" } })
     if (url.pathname === "/agent") return json(route, [{ name: "build", mode: "primary" }])

packages/app/e2e/regression/terminal-hidden.spec.ts

@@ -10,6 +10,7 @@ const title = "Hidden terminal regression"
 test("unmounts the terminal panel while it is hidden", async ({ page }) => {
   await page.setViewportSize({ width: 1400, height: 900 })
   await mockOpenCodeServer(page, {
+    protocol: "v2",
     directory,
     project: {
       id: projectID,

packages/app/e2e/regression/terminal-tab-switch.spec.ts

@@ -66,6 +66,7 @@ async function readProbe(page: Page) {
 
 async function setup(page: Page) {
   await mockOpenCodeServer(page, {
+    protocol: "v2",
     directory,
     project: {
       id: projectID,

packages/app/e2e/smoke/session-timeline.fixture.ts

@@ -21,7 +21,7 @@ const words = [
   "vector",
 ]
 
-const serverKey = `http://127.0.0.1:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
+const serverKey = "http://127.0.0.1:4096"
 const sourceID = "ses_smoke_source"
 const targetID = "ses_smoke_target"
 const directory = "C:/OpenCode/SmokeProject"
@@ -134,7 +134,7 @@ function toolPart(
   return {
     id: id(`prt_tool_${tool}_${partIndex}`, index),
     type: "tool",
-    callID: id("call", index * 100 + partIndex),
+    callID: id("call", index * 10 + partIndex),
     tool,
     state: {
       status: "completed",
@@ -235,17 +235,8 @@ function renderable(part: MessagePart) {
   return part.type !== "step-start" && part.type !== "step-finish" && part.type !== "patch"
 }
 
-function currentPartIDs(message: Message) {
-  const ordinals = { text: 0, reasoning: 0 }
-  return message.parts
-    .flatMap((part) => {
-      if (!renderable(part)) return []
-      if (part.type === "text") return [`${message.info.id}:text:${ordinals.text++}`]
-      if (part.type === "reasoning") return [`${message.info.id}:reasoning:${ordinals.reasoning++}`]
-      if (part.type === "tool") return [typeof part.callID === "string" ? part.callID : part.id]
-      return []
-    })
-    .sort()
+function orderedParts(message: Message) {
+  return message.parts.slice().sort((a, b) => a.id.localeCompare(b.id))
 }
 
 export const fixture = {
@@ -299,10 +290,12 @@ export const fixture = {
     targetMessageIDs: targetMessages
       .filter((message) => message.info.role === "user")
       .map((message) => message.info.id),
-    targetPartIDs: targetMessages.flatMap(currentPartIDs),
-    expandedShellPartID: targetMessages
-      .flatMap((message) => message.parts)
-      .find((part) => part.tool === "bash")!.callID,
+    targetPartIDs: targetMessages.flatMap((message) =>
+      orderedParts(message)
+        .filter(renderable)
+        .map((part) => part.id),
+    ),
+    expandedShellPartID: targetMessages.flatMap((message) => message.parts).find((part) => part.tool === "bash")!.id,
   },
 }
 

packages/app/e2e/smoke/session-timeline.spec.ts

@@ -125,19 +125,20 @@ test.describe("smoke: session timeline", () => {
     })
     await configureSmokePage(page, fixture.directory)
     await page.addInitScript(
-      ({ server, sourceID, targetID }) => {
+      ({ dirBase64, sourceID, targetID }) => {
         localStorage.setItem(
           "opencode.window.browser.dat:tabs",
           JSON.stringify(
             [sourceID, targetID].map((sessionId) => ({
               type: "session",
-              server,
+              server: "http://127.0.0.1:4096",
+              dirBase64,
               sessionId,
             })),
           ),
         )
       },
-      { server: fixture.serverKey, sourceID: fixture.sourceID, targetID: fixture.targetID },
+      { dirBase64: base64Encode(fixture.directory), sourceID: fixture.sourceID, targetID: fixture.targetID },
     )
 
     await page.goto(`/${base64Encode(fixture.directory)}/session/${fixture.targetID}`)
@@ -250,19 +251,20 @@ test.describe("smoke: session timeline", () => {
     })
     await configureSmokePage(page, fixture.directory)
     await page.addInitScript(
-      ({ server, sourceID, targetID }) => {
+      ({ dirBase64, sourceID, targetID }) => {
         localStorage.setItem(
           "opencode.window.browser.dat:tabs",
           JSON.stringify(
             [sourceID, targetID].map((sessionId) => ({
               type: "session",
-              server,
+              server: "http://127.0.0.1:4096",
+              dirBase64,
               sessionId,
             })),
           ),
         )
       },
-      { server: fixture.serverKey, sourceID: fixture.sourceID, targetID: fixture.targetID },
+      { dirBase64: base64Encode(fixture.directory), sourceID: fixture.sourceID, targetID: fixture.targetID },
     )
     await page.goto(`/${base64Encode(fixture.directory)}/session/${fixture.sourceID}`)
     await expectSessionTitle(page, fixture.expected.sourceTitle)

packages/app/e2e/tsconfig.json

@@ -12,7 +12,6 @@
     "./performance/unit/visual-stability.test.ts",
     "./reproduction/timeline-suspense/**/*.ts",
     "./reproduction/timeline-suspense/**/*.tsx",
-    "../src/types.ts",
     "../src/pages/session/timeline/observe-element-offset.ts",
     "./regression/new-session-panel-corner.spec.ts",
     "./regression/session-timeline-context-resize.spec.ts",

packages/app/e2e/user-story/model-selection-flow.spec.ts

@@ -4,7 +4,11 @@ import { expectAppVisible } from "../utils/waits"
 
 const directory = "C:/OpenCode/NewProject"
 
-test("creates a session in a new project and selects its model", async ({ page }) => {
+test("creates a session in a new project, connects OpenCode Go, and selects its model", async ({ page }) => {
+  let connectedGo = false
+  let pendingGo = false
+  const connections: Array<{ integrationID: string; body: unknown }> = []
+
   await mockOpenCodeServer(page, {
     directory,
     project: {
@@ -42,9 +46,17 @@ test("creates a session in a new project and selects its model", async ({ page }
           },
         },
       ],
-      connected: ["opencode", "opencode-go"],
+      connected: connectedGo ? ["opencode", "opencode-go"] : ["opencode"],
       default: { providerID: "opencode", modelID: "free-model" },
     }),
+    integrationMethods: { "opencode-go": [{ type: "api", label: "API key" }] },
+    onConnectKey: (input) => {
+      connections.push(input)
+      if (input.integrationID === "opencode-go") pendingGo = true
+    },
+    onInstanceDispose: () => {
+      if (pendingGo) connectedGo = true
+    },
     sessions: [],
     pageMessages: () => ({ items: [] }),
     fileList: (path) =>
@@ -54,17 +66,6 @@ test("creates a session in a new project and selects its model", async ({ page }
   await page.addInitScript(() => {
     localStorage.setItem("settings.v3", JSON.stringify({ general: { newLayoutDesigns: true } }))
     localStorage.setItem("opencode.global.dat:server", JSON.stringify({ projects: { local: [] } }))
-    localStorage.setItem(
-      "opencode.global.dat:model",
-      JSON.stringify({
-        user: [
-          { providerID: "opencode", modelID: "free-model", visibility: "show" },
-          { providerID: "opencode-go", modelID: "go-model-1", visibility: "show" },
-        ],
-        recent: [],
-        variant: {},
-      }),
-    )
   })
 
   await page.goto("/")
@@ -78,7 +79,16 @@ test("creates a session in a new project and selects its model", async ({ page }
 
   const modelControl = page.locator('[data-action="prompt-model"]')
   await modelControl.click()
-  await expect(page.locator('[data-option-key="opencode:free-model"]')).toBeVisible()
+  await expect(page.locator('[data-section="free-models"]')).toContainText("Free models provided by OpenCode")
+
+  await page.locator('[data-provider-id="opencode-go"]').click()
+  await page.locator('[data-input="provider-api-key"]').fill("mock-go-api-key")
+  await page.locator('[data-action="provider-connect-submit"]').click()
+  await expect(page.locator('[data-component="dialog-v2"]')).toHaveCount(0)
+  expect(connections).toEqual([{ integrationID: "opencode-go", body: { type: "api", key: "mock-go-api-key" } }])
+
+  await expect(modelControl).toHaveAttribute("data-control-type", "popover")
+  await modelControl.click()
   const goModel = page.locator('[data-option-key="opencode-go:go-model-1"]')
   await expect(goModel).toBeVisible()
   await goModel.click()

packages/app/e2e/utils/mock-server.ts

@@ -1,17 +1,14 @@
 import type { Page, Route } from "@playwright/test"
-import type {
-  JsonValue,
-  PromptAgentAttachment,
-  PromptFileAttachment,
-  SessionMessageAssistant,
-  SessionMessageInfo,
-  SessionStructuredError,
-} from "@opencode-ai/client/promise"
+
+const emptyList = new Set(["/skill", "/command", "/lsp", "/formatter", "/vcs/status", "/vcs/diff"])
+const emptyObject = new Set(["/global/config", "/config", "/provider/auth", "/mcp", "/experimental/resource"])
 
 export interface MockServerConfig {
+  protocol?: "v1" | "v2"
   provider: unknown | (() => unknown)
   integrationMethods?: Record<string, unknown[]>
   onConnectKey?: (input: { integrationID: string; body: unknown }) => void
+  onInstanceDispose?: () => void
   directory: string
   project: unknown
   sessions: ({ id: string } & Record<string, unknown>)[]
@@ -36,6 +33,21 @@ export interface MockServerConfig {
 export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
   const cursors = new Map<string, string>()
   let nextCursor = 0
+  const staticRoutes: Record<string, unknown> = {
+    "/path": {
+      state: config.directory,
+      config: config.directory,
+      worktree: config.directory,
+      directory: config.directory,
+      home: "C:/OpenCode",
+    },
+    "/project": [config.project],
+    "/project/current": config.project,
+    "/agent": [{ name: "build", mode: "primary" }],
+    "/vcs": { branch: "main", default_branch: "main" },
+    "/session": config.sessions,
+  }
+
   await page.route("**/*", async (route) => {
     const url = new URL(route.request().url())
     const targetPort = process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"
@@ -45,15 +57,61 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
     if (url.port !== targetPort && url.port !== appPort) return route.fallback()
 
     const path = url.pathname
-    if (path === "/api/event") {
+    if (path === "/global/event" || path === "/event" || path === "/api/event") {
       const events = config.events?.()
       return sse(
         route,
-        [{ id: "evt_mock_connected", type: "server.connected", data: {} }, ...(events?.map(currentEvent) ?? [])],
+        path === "/api/event"
+          ? [{ id: "evt_mock_connected", type: "server.connected", data: {} }, ...(events?.map(currentEvent) ?? [])]
+          : [
+              ...(path === "/global/event"
+                ? [{ payload: { id: "evt_mock_connected", type: "server.connected", properties: {} } }]
+                : []),
+              ...(events ?? []),
+            ],
         config.eventRetry,
       )
     }
-    if (path === "/api/health") return json(route, { healthy: true, version: "2.0.0", pid: 1 })
+    if (path === "/global/health")
+      return config.protocol === "v2" ? json(route, {}, undefined, 404) : json(route, { healthy: true })
+    if (path === "/api/health" && config.protocol === "v2")
+      return json(route, { healthy: true, version: "2.0.0", pid: 1 })
+    if (path === "/experimental/capabilities") return json(route, { backgroundSubagents: true })
+    if (path === "/provider")
+      return json(route, typeof config.provider === "function" ? config.provider() : config.provider)
+    if (path === "/provider/auth") return json(route, config.integrationMethods ?? {})
+    const legacyAuth = path.match(/^\/auth\/([^/]+)$/)?.[1]
+    if (legacyAuth && route.request().method() === "PUT") {
+      config.onConnectKey?.({ integrationID: legacyAuth, body: route.request().postDataJSON() })
+      return json(route, true)
+    }
+    if (path === "/instance/dispose" && route.request().method() === "POST") {
+      config.onInstanceDispose?.()
+      return json(route, true)
+    }
+    if (path === "/permission")
+      return json(route, typeof config.permissions === "function" ? config.permissions() : (config.permissions ?? []))
+    if (path === "/question")
+      return json(route, typeof config.questions === "function" ? config.questions() : (config.questions ?? []))
+    if (path === "/session/status")
+      return json(
+        route,
+        typeof config.sessionStatus === "function" ? config.sessionStatus() : (config.sessionStatus ?? {}),
+      )
+    if (path === "/vcs/diff" && config.vcsDiff) return json(route, config.vcsDiff)
+    if (path === "/file" && config.fileList)
+      return json(route, await config.fileList(url.searchParams.get("path") ?? ""))
+    if (path === "/file/content" && config.fileContent)
+      return json(route, await config.fileContent(url.searchParams.get("path") ?? ""))
+    if (path === "/find/file" && config.findFiles)
+      return json(
+        route,
+        await config.findFiles({
+          query: url.searchParams.get("query") ?? "",
+          dirs: url.searchParams.get("dirs") ?? undefined,
+          limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
+        }),
+      )
     if (path === "/api/reference")
       return json(route, {
         location: {
@@ -76,17 +134,7 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
           },
         ],
       })
-    if (path === "/api/provider")
-      return json(route, {
-        location: location(config),
-        data: currentProviders(providerConfig(config)),
-      })
-    if (path === "/api/model") return json(route, { location: location(config), data: currentModels(providerConfig(config)) })
-    if (path === "/api/model/default")
-      return json(route, { location: location(config), data: currentDefaultModel(providerConfig(config)) })
-    if (path === "/api/integration") return json(route, { location: location(config), data: [] })
     if (path === "/api/command") return json(route, { location: location(config), data: [] })
-    if (path === "/api/plugin") return json(route, { location: location(config), data: [] })
     if (path === "/api/mcp") return json(route, { location: location(config), data: [] })
     if (path === "/api/mcp/resource")
       return json(route, { location: location(config), data: { resources: [], templates: [] } })
@@ -94,31 +142,25 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
     if (integration && route.request().method() === "GET")
       return json(route, {
         location: location(config),
-        data: {
-          id: integration,
-          name: integration,
-          methods: config.integrationMethods?.[integration] ?? [{ type: "key", label: "API key" }],
-          connections: [],
-        },
+        data: { id: integration, name: integration, methods: [{ type: "key", label: "API key" }], connections: [] },
       })
     const integrationConnect = path.match(/^\/api\/integration\/([^/]+)\/connect\/key$/)?.[1]
     if (integrationConnect && route.request().method() === "POST") {
       config.onConnectKey?.({ integrationID: integrationConnect, body: route.request().postDataJSON() })
       return route.fulfill({ status: 204, headers: { "access-control-allow-origin": "*" } })
     }
-    if (/^\/api\/credential\/[^/]+$/.test(path) && route.request().method() === "DELETE")
-      return route.fulfill({ status: 204, headers: { "access-control-allow-origin": "*" } })
     if (path === "/api/project") return json(route, [config.project])
     if (path === "/api/project/current")
       return json(route, { id: (config.project as { id?: string }).id, directory: config.directory })
-    if (path === "/api/location") return json(route, location(config))
-    const projectCopy = path.match(/^\/experimental\/project\/([^/]+)\/copy$/)?.[1]
-    if (projectCopy && route.request().method() === "POST") {
-      const input = route.request().postDataJSON() as { directory: string; name?: string }
-      return json(route, { directory: `${input.directory}/${input.name ?? "copy"}` })
-    }
-    if (projectCopy && route.request().method() === "DELETE")
-      return route.fulfill({ status: 204, headers: { "access-control-allow-origin": "*" } })
+    if (path.startsWith("/api/project/") && route.request().method() === "PATCH") return json(route, config.project)
+    if (path === "/api/path")
+      return json(route, {
+        state: config.directory,
+        config: config.directory,
+        worktree: config.directory,
+        directory: config.directory,
+        home: "C:/OpenCode",
+      })
     if (path === "/api/permission/request")
       return json(route, {
         location: location(config),
@@ -135,43 +177,11 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
       return json(route, { location: location(config), data: { branch: "main", defaultBranch: "main" } })
     if (path === "/api/vcs/status") return json(route, { location: location(config), data: [] })
     if (path === "/api/vcs/diff") return json(route, { location: location(config), data: config.vcsDiff ?? [] })
-    if (path === "/api/fs/list" && config.fileList)
-      return json(route, {
-        location: location(config),
-        data: await config.fileList(url.searchParams.get("path") ?? ""),
-      })
-    const fileRead = path.match(/^\/api\/fs\/read\/(.+)$/)?.[1]
-    if (fileRead && config.fileContent) {
-      const value = await config.fileContent(decodeURIComponent(fileRead))
-      const content = value && typeof value === "object" && "content" in value ? String(value.content) : String(value ?? "")
-      return route.fulfill({ status: 200, body: content, headers: { "content-type": "application/octet-stream" } })
-    }
-    if (path === "/api/fs/find" && config.findFiles) {
-      const entries = await config.findFiles({
-        query: url.searchParams.get("query") ?? "",
-        dirs: url.searchParams.get("type") ?? undefined,
-        limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
-      })
-      return json(route, {
-        location: location(config),
-        data: Array.isArray(entries)
-          ? entries.map((entry) =>
-              typeof entry === "string"
-                ? {
-                    name: entry.split(/[\\/]/).at(-1) ?? entry,
-                    path: entry,
-                    absolute: `${config.directory}/${entry}`,
-                    type: "directory",
-                    ignored: false,
-                  }
-                : entry,
-            )
-          : entries,
-      })
-    }
     if (path === "/api/pty/shells") return json(route, { location: location(config), data: [] })
     if (/^\/api\/pty\/[^/]+\/connect-token$/.test(path))
       return json(route, { location: location(config), data: { ticket: "e2e-ticket", expires_in: 60 } })
+    if (emptyObject.has(path)) return json(route, {})
+    if (emptyList.has(path)) return json(route, [])
     if (path === "/api/session") {
       const directory = url.searchParams.get("directory")
       const parentID = url.searchParams.get("parentID")
@@ -198,9 +208,7 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
       })
     }
     if (path === "/api/session/active") {
-      const statuses = (
-        typeof config.sessionStatus === "function" ? config.sessionStatus() : (config.sessionStatus ?? {})
-      ) as Record<string, { type?: string }>
+      const statuses = (config.sessionStatus ?? {}) as Record<string, { type?: string }>
       return json(route, {
         data: Object.fromEntries(
           Object.entries(statuses).flatMap(([id, status]) =>
@@ -218,6 +226,12 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
     if (/^\/api\/session\/[^/]+\/permission\/[^/]+\/reply$/.test(path) && route.request().method() === "POST") {
       return route.fulfill({ status: 204, headers: { "access-control-allow-origin": "*" } })
     }
+    if (/^\/question\/[^/]+\/(reply|reject)$/.test(path) && route.request().method() === "POST") {
+      return json(route, true)
+    }
+    if (/^\/session\/[^/]+\/permissions\/[^/]+$/.test(path) && route.request().method() === "POST") {
+      return json(route, true)
+    }
     if (
       /^\/api\/session\/[^/]+\/(archive|rename|interrupt|revert\/clear|revert\/commit)$/.test(path) &&
       route.request().method() === "POST"
@@ -227,6 +241,7 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
     if (/^\/api\/session\/[^/]+$/.test(path) && route.request().method() === "DELETE") {
       return route.fulfill({ status: 204, headers: { "access-control-allow-origin": "*" } })
     }
+    if (path in staticRoutes) return json(route, staticRoutes[path])
 
     const currentSessionMatch = path.match(/^\/api\/session\/([^/]+)$/)
     if (currentSessionMatch) {
@@ -237,15 +252,28 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
       })
     }
 
-    const currentMessageMatch = path.match(/^\/api\/session\/([^/]+)\/message\/([^/]+)$/)
-    if (currentMessageMatch) {
-      config.onMessage?.({ sessionID: currentMessageMatch[1]!, messageID: currentMessageMatch[2]! })
-      if (config.messageDelay !== undefined) await new Promise((resolve) => setTimeout(resolve, config.messageDelay))
-      const message = config.message?.(currentMessageMatch[1]!, currentMessageMatch[2]!)
-      if (message === undefined) return json(route, { error: "Message not found" }, undefined, 404)
-      return json(route, { data: currentMessage(message) })
+    const sessionMatch = path.match(/^\/session\/([^/]+)$/)
+    if (sessionMatch) {
+      const session = config.sessions.find((s) => s.id === sessionMatch[1])
+      return json(route, session ?? {})
     }
 
+    const projectMatch = path.match(/^\/project\/([^/]+)$/)
+    if (projectMatch) return json(route, config.project)
+
+    const messageMatch = path.match(/^\/session\/([^/]+)\/message\/([^/]+)$/)
+    if (messageMatch) {
+      config.onMessage?.({ sessionID: messageMatch[1]!, messageID: messageMatch[2]! })
+      if (config.messageDelay !== undefined) await new Promise((resolve) => setTimeout(resolve, config.messageDelay))
+      const message = config.message?.(messageMatch[1]!, messageMatch[2]!)
+      if (message === undefined) return json(route, { error: "Message not found" }, undefined, 404)
+      return json(route, message)
+    }
+
+    const todoMatch = path.match(/^\/session\/([^/]+)\/todo$/)
+    if (todoMatch) return json(route, config.todos?.(todoMatch[1]!) ?? [])
+    if (/^\/session\/[^/]+\/(children|diff)$/.test(path)) return json(route, [])
+
     const currentMessagesMatch = path.match(/^\/api\/session\/([^/]+)\/message$/)
     if (currentMessagesMatch) {
       const token = url.searchParams.get("cursor") ?? undefined
@@ -264,6 +292,23 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
       })
     }
 
+    const messagesMatch = path.match(/^\/session\/([^/]+)\/message$/)
+    if (messagesMatch) {
+      const token = url.searchParams.get("before") ?? undefined
+      const before = token ? cursors.get(token) : undefined
+      if (token && !before) return json(route, { error: "Invalid cursor" }, undefined, 400)
+      config.onMessages?.({ sessionID: messagesMatch[1], before, phase: "start" })
+      await config.beforeMessagesResponse?.({ sessionID: messagesMatch[1]!, before })
+      if (config.messageDelay !== undefined) await new Promise((resolve) => setTimeout(resolve, config.messageDelay))
+      const limit = Number(url.searchParams.get("limit") ?? 80)
+      const pageData = config.pageMessages(messagesMatch[1], limit, before)
+      config.onMessages?.({ sessionID: messagesMatch[1], before, phase: "end" })
+      if (!pageData.cursor) return json(route, pageData.items)
+      const cursor = `cursor_${++nextCursor}`
+      cursors.set(cursor, pageData.cursor)
+      return json(route, pageData.items, { "x-next-cursor": cursor })
+    }
+
     if (url.port === targetPort && targetPort !== appPort) return json(route, {})
     return route.fallback()
   })
@@ -272,75 +317,10 @@ export async function mockOpenCodeServer(page: Page, config: MockServerConfig) {
 function location(config: MockServerConfig) {
   return {
     directory: config.directory,
-    project: { id: (config.project as { id?: string }).id, directory: config.directory, canonical: config.directory },
+    project: { id: (config.project as { id?: string }).id, directory: config.directory },
   }
 }
 
-function providerConfig(config: MockServerConfig) {
-  return typeof config.provider === "function" ? config.provider() : config.provider
-}
-
-function currentProviders(value: unknown) {
-  if (!record(value) || !Array.isArray(value.all)) return Array.isArray(value) ? value : []
-  return value.all.filter(record).flatMap((provider) =>
-    typeof provider.id === "string" && typeof provider.name === "string"
-      ? [{ id: provider.id, name: provider.name, package: provider.id }]
-      : [],
-  )
-}
-
-function currentModels(value: unknown) {
-  if (!record(value) || !Array.isArray(value.all)) return []
-  return value.all.filter(record).flatMap((provider) => {
-    if (typeof provider.id !== "string" || !record(provider.models)) return []
-    return Object.values(provider.models)
-      .filter(record)
-      .flatMap((model) => {
-        if (typeof model.id !== "string" || typeof model.name !== "string") return []
-        const limit = record(model.limit) ? model.limit : {}
-        const cost = record(model.cost) ? model.cost : {}
-        return [
-          {
-            id: model.id,
-            modelID: model.id,
-            providerID: provider.id,
-            name: model.name,
-            capabilities: { tools: true, input: ["text"], output: ["text"] },
-            variants: record(model.variants)
-              ? Object.entries(model.variants).map(([id, settings]) => ({
-                  id,
-                  ...(jsonRecord(settings) ? { settings: jsonRecord(settings) } : {}),
-                }))
-              : [],
-            time: { released: Date.now() },
-            cost: [
-              {
-                input: typeof cost.input === "number" ? cost.input : 0,
-                output: typeof cost.output === "number" ? cost.output : 0,
-                cache: { read: 0, write: 0 },
-              },
-            ],
-            status: "active",
-            enabled: true,
-            limit: {
-              context: typeof limit.context === "number" ? limit.context : 200_000,
-              output: typeof limit.output === "number" ? limit.output : 32_000,
-            },
-          },
-        ]
-      })
-  })
-}
-
-function currentDefaultModel(value: unknown) {
-  if (!record(value) || !record(value.default)) return null
-  const selected = value.default
-  const models = currentModels(value)
-  return models.find(
-    (model) => model.providerID === selected.providerID && model.id === selected.modelID,
-  ) ?? null
-}
-
 function currentPermission(value: unknown) {
   const permission = value as Record<string, unknown>
   if (permission.action) return permission
@@ -384,222 +364,63 @@ export function currentSession(session: { id: string } & Record<string, unknown>
   }
 }
 
-export function currentMessage(value: unknown): SessionMessageInfo {
-  if (isCurrentMessage(value)) return value
-  if (!record(value) || !record(value.info) || !Array.isArray(value.parts)) throw new Error("Invalid message fixture")
-
-  const info = value.info
-  const parts = value.parts.filter(record)
-  if (typeof info.id !== "string" || !record(info.time) || typeof info.time.created !== "number")
-    throw new Error("Invalid legacy message fixture")
-
-  const time = {
-    created: info.time.created,
-    ...(typeof info.time.completed === "number" ? { completed: info.time.completed } : {}),
+function currentMessage(value: unknown) {
+  const item = value as {
+    info: Record<string, unknown> & { id: string; role: "user" | "assistant"; time: { created: number } }
+    parts: Array<Record<string, unknown> & { type: string }>
   }
-  if (info.role === "user") {
+  if (item.info.role === "user") {
     return {
-      id: info.id,
+      id: item.info.id,
       type: "user",
-      time: { created: time.created },
-      text: parts
+      time: item.info.time,
+      text: item.parts
         .flatMap((part) => (part.type === "text" && typeof part.text === "string" ? [part.text] : []))
         .join("\n"),
-      files: parts.flatMap((part) => (part.type === "file" ? legacyFile(part) : [])),
-      agents: parts.flatMap((part) => (part.type === "agent" ? legacyAgent(part) : [])),
     }
   }
-  if (info.role !== "assistant") throw new Error("Invalid legacy message role")
-
   return {
-    id: info.id,
+    id: item.info.id,
     type: "assistant",
-    time,
-    agent: typeof info.agent === "string" ? info.agent : typeof info.mode === "string" ? info.mode : "build",
-    model: {
-      id: typeof info.modelID === "string" ? info.modelID : "model",
-      providerID: typeof info.providerID === "string" ? info.providerID : "provider",
-      ...(typeof info.variant === "string" ? { variant: info.variant } : {}),
-    },
-    content: parts.flatMap((part) => legacyAssistantContent(part, time.created)),
-    ...(typeof info.cost === "number" ? { cost: info.cost } : {}),
-    ...(tokens(info.tokens) ? { tokens: tokens(info.tokens) } : {}),
-    ...(structuredError(info.error) ? { error: structuredError(info.error) } : {}),
-    ...(finish(info.finish) ? { finish: finish(info.finish) } : {}),
-  }
-}
-
-function isCurrentMessage(value: unknown): value is SessionMessageInfo {
-  return record(value) && typeof value.id === "string" && typeof value.type === "string" && !record(value.info)
-}
-
-function legacyFile(part: Record<string, unknown>): PromptFileAttachment[] {
-  if (typeof part.mime !== "string" || typeof part.url !== "string") return []
-  const data = part.url.match(/^data:[^,]*;base64,(.*)$/)?.[1] ?? ""
-  const source = record(part.source) ? part.source : undefined
-  const sourceText = source && record(source.text) ? source.text : undefined
-  const mention = mentionFrom(sourceText)
-  const uri = source?.type === "resource" && typeof source.uri === "string" ? source.uri : part.url
-  return [
-    {
-      data,
-      mime: part.mime,
-      source: part.url.startsWith("data:") ? { type: "inline" } : { type: "uri", uri },
-      ...(typeof part.filename === "string" ? { name: part.filename } : {}),
-      ...(mention ? { mention } : {}),
-    },
-  ]
-}
-
-function legacyAgent(part: Record<string, unknown>): PromptAgentAttachment[] {
-  if (typeof part.name !== "string") return []
-  const mention = mentionFrom(record(part.source) ? part.source : undefined)
-  return [{ name: part.name, ...(mention ? { mention } : {}) }]
-}
-
-function mentionFrom(value: Record<string, unknown> | undefined) {
-  if (
-    !value ||
-    typeof value.value !== "string" ||
-    typeof value.start !== "number" ||
-    typeof value.end !== "number"
-  )
-    return
-  return { text: value.value, start: value.start, end: value.end }
-}
-
-function legacyAssistantContent(
-  part: Record<string, unknown>,
-  created: number,
-): SessionMessageAssistant["content"] {
-  if (part.type === "text" && typeof part.text === "string")
-    return [{ type: "text", text: part.text, ...(jsonRecord(part.metadata) ? { state: jsonRecord(part.metadata) } : {}) }]
-  if (part.type === "reasoning" && typeof part.text === "string") {
-    const time = record(part.time) ? part.time : undefined
-    return [
-      {
-        type: "reasoning",
-        text: part.text,
-        ...(jsonRecord(part.metadata) ? { state: jsonRecord(part.metadata) } : {}),
-        ...(time && typeof time.start === "number"
-          ? {
-              time: {
-                created: time.start,
-                ...(typeof time.end === "number" ? { completed: time.end } : {}),
-              },
-            }
-          : {}),
-      },
-    ]
-  }
-  if (part.type !== "tool" || typeof part.id !== "string" || typeof part.tool !== "string" || !record(part.state))
-    return []
-
-  const state = part.state
-  const time = record(state.time) ? state.time : undefined
-  const toolTime = {
-    created: time && typeof time.start === "number" ? time.start : created,
-    ...(time && typeof time.start === "number" ? { ran: time.start } : {}),
-    ...(time && typeof time.end === "number" ? { completed: time.end } : {}),
-  }
-  const input = jsonRecord(state.input) ?? {}
-  const metadata = jsonRecord(state.metadata)
-  const base = {
-    type: "tool" as const,
-    id: typeof part.callID === "string" ? part.callID : part.id,
-    name: part.tool,
-    time: toolTime,
-    ...(typeof part.executed === "boolean" ? { executed: part.executed } : {}),
-    ...(jsonRecord(part.providerState) ? { providerState: jsonRecord(part.providerState) } : {}),
-    ...(jsonRecord(part.providerResultState) ? { providerResultState: jsonRecord(part.providerResultState) } : {}),
-  }
-  if (state.status === "pending")
-    return [{ ...base, state: { status: "streaming", input: typeof state.raw === "string" ? state.raw : JSON.stringify(input) } }]
-  if (state.status === "completed")
-    return [
-      {
-        ...base,
-        state: {
-          status: "completed",
-          input,
-          content: [{ type: "text", text: typeof state.output === "string" ? state.output : "" }],
-          ...(metadata ? { metadata } : {}),
+    time: item.info.time,
+    agent: item.info.agent ?? "build",
+    model: { id: item.info.modelID ?? "model", providerID: item.info.providerID ?? "provider" },
+    cost: item.info.cost,
+    tokens: item.info.tokens,
+    error: item.info.error,
+    content: item.parts.flatMap<unknown>((part) => {
+      if (part.type === "text" || part.type === "reasoning") return [{ type: part.type, text: part.text ?? "" }]
+      if (part.type !== "tool") return []
+      const state = part.state as Record<string, unknown>
+      return [
+        {
+          type: "tool",
+          id: part.id,
+          name: part.tool,
+          time: state.time ?? { created: item.info.time.created },
+          state:
+            state.status === "pending"
+              ? { status: "streaming", input: state.raw ?? JSON.stringify(state.input ?? {}) }
+              : state.status === "completed"
+                ? {
+                    status: "completed",
+                    input: state.input ?? {},
+                    structured: state.metadata ?? {},
+                    content: [{ type: "text", text: state.output ?? "" }],
+                  }
+                : state.status === "error"
+                  ? {
+                      status: "error",
+                      input: state.input ?? {},
+                      structured: state.metadata ?? {},
+                      content: [],
+                      error: { type: "ToolError", message: state.error ?? "Tool failed" },
+                    }
+                  : { status: "running", input: state.input ?? {}, structured: state.metadata ?? {}, content: [] },
         },
-      },
-    ]
-  if (state.status === "error")
-    return [
-      {
-        ...base,
-        state: {
-          status: "error",
-          input,
-          error: structuredError(state.error) ?? { type: "ToolError", message: "Tool failed" },
-          ...(metadata ? { metadata } : {}),
-        },
-      },
-    ]
-  return [{ ...base, state: { status: "running", input, metadata: metadata ?? {} } }]
-}
-
-function structuredError(value: unknown): SessionStructuredError | undefined {
-  if (typeof value === "string") return { type: "Error", message: value }
-  if (!record(value)) return
-  if (typeof value.type === "string" && typeof value.message === "string")
-    return { type: value.type, message: value.message }
-  if (typeof value.name !== "string" || !record(value.data) || typeof value.data.message !== "string") return
-  return { type: value.name, message: value.data.message }
-}
-
-function tokens(value: unknown): SessionMessageAssistant["tokens"] | undefined {
-  if (!record(value) || !record(value.cache)) return
-  if (
-    typeof value.input !== "number" ||
-    typeof value.output !== "number" ||
-    typeof value.reasoning !== "number" ||
-    typeof value.cache.read !== "number" ||
-    typeof value.cache.write !== "number"
-  )
-    return
-  return {
-    input: value.input,
-    output: value.output,
-    reasoning: value.reasoning,
-    cache: { read: value.cache.read, write: value.cache.write },
-  }
-}
-
-function finish(value: unknown): SessionMessageAssistant["finish"] | undefined {
-  if (
-    value === "stop" ||
-    value === "length" ||
-    value === "tool-calls" ||
-    value === "content-filter" ||
-    value === "error" ||
-    value === "unknown"
-  )
-    return value
-}
-
-function jsonRecord(value: unknown): Record<string, JsonValue> | undefined {
-  if (!record(value)) return
-  return Object.fromEntries(
-    Object.entries(value).flatMap(([key, item]) => {
-      const next = jsonValue(item)
-      return next === undefined ? [] : [[key, next]]
+      ]
     }),
-  )
-}
-
-function jsonValue(value: unknown): JsonValue | undefined {
-  if (value === null || typeof value === "string" || typeof value === "boolean") return value
-  if (typeof value === "number") return Number.isFinite(value) ? value : null
-  if (Array.isArray(value)) return value.map((item) => jsonValue(item) ?? null)
-  return jsonRecord(value)
-}
-
-function record(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value)
+  }
 }
 
 function json(route: Route, body: unknown, headers?: Record<string, string>, status = 200) {

packages/app/e2e/utils/sse-transport.ts

@@ -3,7 +3,7 @@ import type { Page } from "@playwright/test"
 export type SseConnectionRecord = {
   id: number
   url: string
-  path: "/api/event"
+  path: "/global/event" | "/event" | "/api/event"
   headers: Record<string, string>
   openedAt: number
   endedAt?: number
@@ -174,7 +174,10 @@ export async function installSseTransport<T>(
       const fetch = (input: RequestInfo | URL, init?: RequestInit) => {
         const request = new Request(input, init)
         const url = new URL(request.url)
-        if (url.origin !== server || url.pathname !== "/api/event")
+        if (
+          url.origin !== server ||
+          (url.pathname !== "/global/event" && url.pathname !== "/event" && url.pathname !== "/api/event")
+        )
           return originalFetch(request)
 
         const id = ++nextConnectionID
@@ -190,9 +193,18 @@ export async function installSseTransport<T>(
             record.controller = controller
             connections.push(record)
             if (retry !== undefined) controller.enqueue(encoder.encode(`retry: ${retry}\n\n`))
-            controller.enqueue(
-              encoder.encode(frame({ id: `evt_mock_connected_${id}`, type: "server.connected", data: {} })),
-            )
+            if (url.pathname === "/api/event")
+              controller.enqueue(
+                encoder.encode(frame({ id: `evt_mock_connected_${id}`, type: "server.connected", data: {} })),
+              )
+            if (url.pathname === "/global/event")
+              controller.enqueue(
+                encoder.encode(
+                  frame({
+                    payload: { id: `evt_mock_connected_${id}`, type: "server.connected", properties: {} },
+                  }),
+                ),
+              )
             request.signal.addEventListener(
               "abort",
               () => {

packages/app/package.json

@@ -56,8 +56,10 @@
     "@opencode-ai/client": "workspace:*",
     "@opencode-ai/core": "workspace:*",
     "@opencode-ai/schema": "workspace:*",
+    "@opencode-ai/sdk": "file:vendor/opencode-ai-sdk-1.18.8-dev.tgz",
     "@opencode-ai/session-ui": "workspace:*",
     "@opencode-ai/ui": "workspace:*",
+    "@opencode-ai/util": "workspace:*",
     "@pierre/trees": "1.0.0-beta.4",
     "@sentry/solid": "catalog:",
     "@shikijs/transformers": "3.9.2",

packages/app/src/app.tsx

@@ -238,6 +238,26 @@ function UiI18nBridge(props: ParentProps) {
 }
 
 function LayoutCompatibility(props: ParentProps) {
+  const global = useGlobal()
+  const navigate = useNavigate()
+  const server = useServer()
+  const settings = useSettings()
+
+  createEffect(() => {
+    if (settings.general.newLayoutDesigns()) return
+    const current = server.current
+    if (!current) return
+    const protocol = global.ensureServerCtx(current).sdk.protocolKind()
+    if (protocol !== "v2") return
+    const next = global.servers.list().find((s) => {
+      if (ServerConnection.key(s) === ServerConnection.key(current)) return false
+      return global.ensureServerCtx(s).sdk.protocolKind() !== "v2"
+    })
+    if (!next) return
+    navigate("/")
+    queueMicrotask(() => server.setActive(ServerConnection.key(next)))
+  })
+
   return <>{props.children}</>
 }
 

packages/app/src/components/command-palette.ts

@@ -1,5 +1,5 @@
 import { getFilename } from "@opencode-ai/core/util/path"
-import type { Project } from "@/types"
+import type { Project } from "@opencode-ai/sdk/v2/client"
 import type { SessionInfo } from "@opencode-ai/client/promise"
 import { useDialog } from "@opencode-ai/ui/context/dialog"
 import { createMemo, onCleanup } from "solid-js"

packages/app/src/components/dialog-custom-provider.tsx

@@ -130,9 +130,26 @@ export function CustomProviderForm(props: { autofocus?: boolean } = {}) {
   }
 
   const saveMutation = useMutation(() => ({
-    mutationFn: async (result: NonNullable<ReturnType<typeof validate>>): Promise<typeof result> => {
-      // TODO: Restore custom providers when V2 exposes config and arbitrary credential APIs.
-      throw new Error(`Custom provider ${result.providerID} is unavailable`)
+    mutationFn: async (result: NonNullable<ReturnType<typeof validate>>) => {
+      if ((await serverSDK().protocol) !== "v1") throw new Error("Custom providers are unavailable on this server")
+      const disabledProviders = serverSync().data.config.disabled_providers ?? []
+      const nextDisabled = disabledProviders.filter((id) => id !== result.providerID)
+
+      if (result.key) {
+        await serverSDK().client.auth.set({
+          providerID: result.providerID,
+          auth: {
+            type: "api",
+            key: result.key,
+          },
+        })
+      }
+
+      await serverSync().updateConfig({
+        provider: { [result.providerID]: result.config },
+        disabled_providers: nextDisabled,
+      })
+      return result
     },
     onSuccess: (result) => {
       dialog.close()

packages/app/src/components/dialog-edit-project-v2.tsx

@@ -146,7 +146,7 @@ export function DialogEditProjectV2(props: { project: LocalProject; server: Serv
           <ButtonV2 type="button" variant="neutral" disabled={model.save.isPending} onClick={model.close}>
             {language.t("common.cancel")}
           </ButtonV2>
-          <ButtonV2 type="submit" variant="contrast" disabled={!model.supported || model.save.isPending}>
+          <ButtonV2 type="submit" variant="contrast" disabled={model.save.isPending}>
             {model.save.isPending ? language.t("common.saving") : language.t("common.save")}
           </ButtonV2>
         </DialogFooter>

packages/app/src/components/dialog-edit-project.tsx

@@ -160,7 +160,7 @@ export function DialogEditProject(props: { project: LocalProject; server: Server
           <Button type="button" variant="ghost" size="large" onClick={model.close}>
             {language.t("common.cancel")}
           </Button>
-          <Button type="submit" variant="primary" size="large" disabled={!model.supported || model.save.isPending}>
+          <Button type="submit" variant="primary" size="large" disabled={model.save.isPending}>
             {model.save.isPending ? language.t("common.saving") : language.t("common.save")}
           </Button>
         </div>

packages/app/src/components/dialog-fork.tsx

@@ -8,7 +8,7 @@ import { Dialog } from "@opencode-ai/ui/dialog"
 import { List } from "@opencode-ai/ui/list"
 import { showToast } from "@/utils/toast"
 import { extractPromptFromParts } from "@/utils/prompt"
-import type { TextPart as SDKTextPart } from "@/types"
+import type { TextPart as SDKTextPart } from "@opencode-ai/sdk/v2/client"
 import { base64Encode } from "@opencode-ai/core/util/encode"
 import { useLanguage } from "@/context/language"
 

packages/app/src/components/dialog-select-directory-v2.tsx

@@ -8,7 +8,7 @@ import { createEffect, createMemo, createResource, createSignal, For, onCleanup,
 import { useGlobal } from "@/context/global"
 import { useLanguage } from "@/context/language"
 import { ServerConnection } from "@/context/server"
-import type { Path } from "@/types"
+import type { Path } from "@opencode-ai/sdk/v2/client"
 import {
   absoluteTreePath,
   activeTreeNavigation,
@@ -66,21 +66,16 @@ export function DialogSelectDirectoryV2(props: DialogSelectDirectoryV2Props) {
   let pathArea: HTMLDivElement | undefined
   let navigation = 0
 
+  const missingBase = createMemo(() => !(sync.data.path.home || sync.data.path.directory))
   const [fallbackPath] = createResource(
-    () => (!(sync.data.path.home || sync.data.path.directory) ? true : undefined),
-    () =>
-      sdk.api.location
+    () => (missingBase() ? true : undefined),
+    async (): Promise<Path | undefined> => {
+      if ((await sdk.protocol) !== "v1") return
+      return sdk.client.path
         .get()
-        .then(
-          (location): Path => ({
-            state: "",
-            config: "",
-            worktree: location.project.directory,
-            directory: location.directory,
-            home: location.home,
-          }),
-        )
-        .catch(() => undefined),
+        .then((result) => result.data)
+        .catch(() => undefined)
+    },
     { initialValue: undefined },
   )
   const home = createMemo(() => sync.data.path.home || fallbackPath()?.home || "")

packages/app/src/components/dialog-select-directory.tsx

@@ -9,7 +9,7 @@ import { useLanguage } from "@/context/language"
 import { ServerConnection } from "@/context/server"
 import { useGlobal } from "@/context/global"
 import { cleanPickerInput, createDirectorySearch, displayPickerPath } from "./directory-picker-domain"
-import type { Path } from "@/types"
+import type { Path } from "@opencode-ai/sdk/v2/client"
 
 interface DialogSelectDirectoryProps {
   title?: string
@@ -57,21 +57,16 @@ export function DialogSelectDirectory(props: DialogSelectDirectoryProps) {
   const [filter, setFilter] = createSignal("")
   let list: ListRef | undefined
 
+  const missingBase = createMemo(() => !(sync.data.path.home || sync.data.path.directory))
   const [fallbackPath] = createResource(
-    () => (!(sync.data.path.home || sync.data.path.directory) ? true : undefined),
-    () =>
-      sdk.api.location
+    () => (missingBase() ? true : undefined),
+    async (): Promise<Path | undefined> => {
+      if ((await sdk.protocol) !== "v1") return
+      return sdk.client.path
         .get()
-        .then(
-          (location): Path => ({
-            state: "",
-            config: "",
-            worktree: location.project.directory,
-            directory: location.directory,
-            home: location.home,
-          }),
-        )
-        .catch(() => undefined),
+        .then((result) => result.data)
+        .catch(() => undefined)
+    },
     { initialValue: undefined },
   )
 

packages/app/src/components/dialog-select-server.tsx

@@ -16,6 +16,7 @@ import { useGlobal } from "@/context/global"
 import { useLanguage } from "@/context/language"
 import { usePlatform } from "@/context/platform"
 import { normalizeServerUrl, ServerConnection, useServer } from "@/context/server"
+import { detectServerProtocol } from "@/utils/server-protocol"
 import { type ServerHealth, useCheckServerHealth } from "@/utils/server-health"
 import { useSettings } from "@/context/settings"
 import { useTabs } from "@/context/tabs"
@@ -263,6 +264,13 @@ export function useServerManagementController(options: { onSelect?: () => void;
         setStore("addServer", { error: language.t("dialog.server.add.error") })
         return
       }
+      if (
+        !settings.general.newLayoutDesigns() &&
+        (await detectServerProtocol(conn.http, platform.fetch ?? globalThis.fetch)) === "v2"
+      ) {
+        setStore("addServer", { error: language.t("dialog.server.add.error") })
+        return
+      }
 
       resetAdd()
       if (options.navigateOnAdd === false) {
@@ -307,6 +315,13 @@ export function useServerManagementController(options: { onSelect?: () => void;
         setStore("editServer", { error: language.t("dialog.server.add.error") })
         return
       }
+      if (
+        !settings.general.newLayoutDesigns() &&
+        (await detectServerProtocol(conn.http, platform.fetch ?? globalThis.fetch)) === "v2"
+      ) {
+        setStore("editServer", { error: language.t("dialog.server.add.error") })
+        return
+      }
       if (normalized === input.original.http.url) {
         server.add(conn)
       } else {
@@ -345,7 +360,9 @@ export function useServerManagementController(options: { onSelect?: () => void;
 
   const sortedItems = createMemo(() => {
     const raw = items()
-    const list = raw
+    const list = settings.general.newLayoutDesigns()
+      ? raw
+      : raw.filter((x) => global.ensureServerCtx(x).sdk.protocolKind() !== "v2")
     if (!list.length) return list
     const active = current()
     const order = new Map(list.map((url, index) => [url, index] as const))

packages/app/src/components/edit-project.ts

@@ -9,7 +9,6 @@ import { type LocalProject } from "@/context/layout"
 import { ServerConnection } from "@/context/server"
 
 export function createEditProjectModel(props: { project: LocalProject; server: ServerConnection.Any }) {
-  const supported = !props.project.id || props.project.id === "global"
   const dialog = useDialog()
   const global = useGlobal()
   const serverCtx = createMemo(() => global.ensureServerCtx(props.server))
@@ -72,9 +71,29 @@ export function createEditProjectModel(props: { project: LocalProject; server: S
       const start = store.startup.trim()
 
       if (props.project.id && props.project.id !== "global") {
-        // TODO: Restore project edits when the V2 client exposes a project update API.
-        // await serverCtx().sdk.api.project.update({ projectID: props.project.id, name, icon, commands })
-        throw new Error(`Project ${props.project.id} cannot be updated`)
+        if ((await serverCtx().sdk.protocol) !== "v1") return
+        const project = await serverCtx()
+          .sdk.client.project.update({
+            projectID: props.project.id,
+            directory: props.project.worktree,
+            name,
+            icon: { color: store.color || "", override: store.iconOverride || "" },
+            commands: { start },
+          })
+          .then((result) => result.data)
+        if (!project) return
+        // const project = await serverCtx().sdk.api.project.update({
+        //   projectID: props.project.id,
+        //   name,
+        //   icon: { color: store.color || "", override: store.iconOverride || "" },
+        //   commands: { start },
+        // })
+        serverCtx().sync.set("project", (items) =>
+          items.map((item) => (item.id === project.id ? normalizeProjectInfo(project) : item)),
+        )
+        serverCtx().sync.project.icon(props.project.worktree, store.iconOverride || undefined)
+        dialog.close()
+        return
       }
 
       serverCtx().sync.project.meta(props.project.worktree, {
@@ -88,7 +107,7 @@ export function createEditProjectModel(props: { project: LocalProject; server: S
 
   function submit(event: SubmitEvent) {
     event.preventDefault()
-    if (!supported || save.isPending) return
+    if (save.isPending) return
     save.mutate()
   }
 
@@ -98,7 +117,6 @@ export function createEditProjectModel(props: { project: LocalProject; server: S
     folderName,
     defaultName,
     save,
-    supported,
     submit,
     drop,
     dragOver,

packages/app/src/components/file-tree-v2-model.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { buildFileTreeV2Model, flattenFileTreeV2, flattenLiveFileTreeV2 } from "./file-tree-v2-model"
-import type { FileNode } from "@/types"
+import type { FileNode } from "@opencode-ai/sdk/v2"
 
 describe("buildFileTreeV2Model", () => {
   test("builds a sorted tree and flattens expanded directories", () => {

packages/app/src/components/file-tree-v2-model.ts

@@ -1,4 +1,4 @@
-import type { FileNode } from "@/types"
+import type { FileNode } from "@opencode-ai/sdk/v2"
 
 export type FileTreeV2Model = {
   children: ReadonlyMap<string, readonly FileTreeV2Node[]>

packages/app/src/components/file-tree-v2.tsx

@@ -12,7 +12,7 @@ import {
   type ParentProps,
 } from "solid-js"
 import { Dynamic } from "solid-js/web"
-import type { FileNode } from "@/types"
+import type { FileNode } from "@opencode-ai/sdk/v2"
 import { Icon } from "@opencode-ai/ui/v2/icon"
 import { pathToFileUrl, withFileDragImage, type Kind } from "@/components/file-tree"
 import { createVirtualizer, defaultRangeExtractor } from "@tanstack/solid-virtual"

packages/app/src/components/file-tree.tsx

@@ -17,7 +17,7 @@ import {
   type ParentProps,
 } from "solid-js"
 import { Dynamic } from "solid-js/web"
-import type { FileNode } from "@/types"
+import type { FileNode } from "@opencode-ai/sdk/v2"
 
 const MAX_DEPTH = 128
 

packages/app/src/components/prompt-input-v2.tsx

@@ -5,7 +5,7 @@ import { ButtonV2 } from "@opencode-ai/ui/v2/button-v2"
 import { Icon } from "@opencode-ai/ui/v2/icon"
 import { KeybindV2 } from "@opencode-ai/ui/v2/keybind-v2"
 import { TooltipV2 } from "@opencode-ai/ui/v2/tooltip-v2"
-import type { ReferenceInfo } from "@/types"
+import type { ReferenceInfo } from "@opencode-ai/sdk/v2/client"
 import { createEffect, createMemo, on, Show } from "solid-js"
 import { ModelSelectorPopoverV2 } from "@/components/dialog-select-model"
 import { DialogSelectModelUnpaidV2 } from "@/components/dialog-select-model-unpaid-v2"

packages/app/src/components/prompt-input.stories.tsx

@@ -1,6 +1,6 @@
 // @ts-nocheck
 import { createStore } from "solid-js/store"
-import type { Todo } from "@/types"
+import type { Todo } from "@opencode-ai/sdk/v2"
 import { createPromptState } from "@/context/prompt"
 import { SessionComposerRegion, createSessionComposerRegionController } from "@/pages/session/composer"
 import { createPromptInputHistory, PromptInput } from "./prompt-input"

packages/app/src/components/prompt-input.tsx

@@ -81,7 +81,7 @@ import { promptDesignPlaceholder, promptPlaceholder } from "./prompt-input/place
 import { createPromptInputTransientState } from "./prompt-input/transient-state"
 import { showToast } from "@/utils/toast"
 import { ImagePreview } from "@opencode-ai/ui/image-preview"
-import type { ReferenceInfo } from "@/types"
+import type { ReferenceInfo } from "@opencode-ai/sdk/v2/client"
 
 export { createPromptInputHistory }
 export type { PromptInputControls, PromptInputHistory, PromptInputProps, PromptInputState, PromptInputSubmission }

packages/app/src/components/prompt-input/build-request-parts.ts

@@ -1,5 +1,5 @@
 import { getFilename } from "@opencode-ai/core/util/path"
-import type { AgentPartInput, FilePartInput, Part, TextPartInput } from "@/types"
+import { type AgentPartInput, type FilePartInput, type Part, type TextPartInput } from "@opencode-ai/sdk/v2/client"
 import type { FileSelection } from "@/context/file"
 import { encodeFilePath } from "@/context/file/path"
 import type { AgentPart, FileAttachmentPart, ImageAttachmentPart, Prompt } from "@/context/prompt"

packages/app/src/components/prompt-input/submit.test.ts

@@ -125,6 +125,13 @@ beforeAll(async () => {
     useSearchParams: () => [search, () => undefined],
   }))
 
+  mock.module("@opencode-ai/sdk/v2/client", () => ({
+    createOpencodeClient: (input: { directory: string }) => {
+      createdClients.push(input.directory)
+      return clientFor(input.directory)
+    },
+  }))
+
   mock.module("@opencode-ai/ui/toast", () => ({
     Toast: { Region: () => null },
     showToast: () => 0,
@@ -190,8 +197,12 @@ beforeAll(async () => {
       const sdk = {
         scope: "local",
         directory: "/repo/main",
+        client: rootClient,
         api: rootClient.api,
         url: "http://localhost:4096",
+        createClient(opts: any) {
+          return clientFor(opts.directory)
+        },
       }
       return () => sdk
     },
@@ -321,7 +332,7 @@ describe("prompt submit worktree selection", () => {
     selected = "/repo/worktree-b"
     await submit.handleSubmit(event)
 
-    expect(createdClients).toEqual([])
+    expect(createdClients).toEqual(["/repo/worktree-a", "/repo/worktree-b"])
     expect(createdSessions).toEqual(["/repo/worktree-a", "/repo/worktree-b"])
     expect(sessionCreateInputs).toEqual([
       {
@@ -478,6 +489,9 @@ describe("prompt submit worktree selection", () => {
       agents: [],
     })
     expect((promptInputs[0] as { id?: string }).id).toStartWith("msg_")
+    expect((promptInputs[0] as { legacyParts?: { id: string; type: string; text?: string }[] }).legacyParts).toEqual([
+      { id: expect.stringMatching(/^prt_/), type: "text", text: "ls" },
+    ])
   })
 
   test("submits slash commands through the current session API", async () => {

packages/app/src/components/prompt-input/submit.ts

@@ -1,4 +1,4 @@
-import type { Message, Session } from "@/types"
+import type { Message, Session } from "@opencode-ai/sdk/v2/client"
 import { showToast } from "@/utils/toast"
 import { base64Encode } from "@opencode-ai/core/util/encode"
 import { Binary } from "@opencode-ai/core/util/binary"
@@ -15,7 +15,6 @@ import { useSDK, type DirectorySDK } from "@/context/sdk"
 import { useSync, type DirectorySync } from "@/context/sync"
 import { Identifier } from "@/utils/id"
 import { Worktree as WorktreeState } from "@/utils/worktree"
-import { getDirectory } from "@opencode-ai/core/util/path"
 import { buildRequestParts } from "./build-request-parts"
 import { setCursorPosition } from "./editor-dom"
 import { formatServerError } from "@/utils/server-errors"
@@ -160,6 +159,10 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
     await input.api.prompt({
       sessionID: input.draft.sessionID,
       id: messageID,
+      agent: input.draft.agent,
+      model: input.draft.model,
+      variant: input.draft.variant,
+      legacyParts: requestParts,
       text: requestParts.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n"),
       files: requestParts.flatMap((part) => {
         if (part.type !== "file") return []
@@ -345,15 +348,13 @@ export function createPromptSubmit(input: PromptSubmitInput) {
     const worktreeSelection = input.newSessionWorktree?.() || "main"
 
     let sessionDirectory = projectDirectory
+    let client = sdk().client
+
     if (isNewSession) {
       if (worktreeSelection === "create") {
-        const createdWorktree = await sdk()
-          .api.projectCopy.create({
-            projectID: sync().data.project,
-            strategy: "git_worktree",
-            directory: getDirectory(projectDirectory),
-            location: { directory: projectDirectory },
-          })
+        const createdWorktree = await client.worktree
+          .create({ directory: projectDirectory })
+          .then((x) => x.data)
           .catch((err) => {
             showToast({
               title: language.t("prompt.toast.worktreeCreateFailed.title"),
@@ -361,7 +362,14 @@ export function createPromptSubmit(input: PromptSubmitInput) {
             })
             return undefined
           })
-        if (!createdWorktree) return
+
+        if (!createdWorktree?.directory) {
+          showToast({
+            title: language.t("prompt.toast.worktreeCreateFailed.title"),
+            description: language.t("common.requestFailed"),
+          })
+          return
+        }
         WorktreeState.pending(sdk().scope, createdWorktree.directory)
         sessionDirectory = createdWorktree.directory
       }
@@ -371,6 +379,10 @@ export function createPromptSubmit(input: PromptSubmitInput) {
       }
 
       if (sessionDirectory !== projectDirectory) {
+        client = sdk().createClient({
+          directory: sessionDirectory,
+          throwOnError: true,
+        })
         serverSync().child(sessionDirectory)
       }
 
@@ -475,6 +487,8 @@ export function createPromptSubmit(input: PromptSubmitInput) {
           sessionID: session.id,
           id: eventID,
           command: text,
+          agent,
+          model,
         })
         .catch((err) => {
           showToast({

packages/app/src/components/session/session-context-breakdown.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import type { Message, Part } from "@/types"
+import type { Message, Part } from "@opencode-ai/sdk/v2/client"
 import { estimateSessionContextBreakdown } from "./session-context-breakdown"
 
 const user = (id: string) => {

packages/app/src/components/session/session-context-breakdown.ts

@@ -1,4 +1,4 @@
-import type { Message, Part } from "@/types"
+import type { Message, Part } from "@opencode-ai/sdk/v2/client"
 
 export type SessionContextBreakdownKey = "system" | "user" | "assistant" | "tool" | "other"
 

packages/app/src/components/session/session-context-metrics.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import type { Message } from "@/types"
+import type { Message } from "@opencode-ai/sdk/v2/client"
 import { getSessionContext } from "./session-context-metrics"
 
 const assistant = (

packages/app/src/components/session/session-context-metrics.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessage, Message } from "@/types"
+import type { AssistantMessage, Message } from "@opencode-ai/sdk/v2/client"
 
 type Provider = {
   id: string

packages/app/src/components/session/session-context-tab.tsx

@@ -10,7 +10,7 @@ import { StickyAccordionHeader } from "@opencode-ai/ui/sticky-accordion-header"
 import { File } from "@opencode-ai/session-ui/file"
 import { Markdown } from "@opencode-ai/session-ui/markdown"
 import { ScrollView } from "@opencode-ai/ui/scroll-view"
-import type { Message, Part, UserMessage } from "@/types"
+import type { Message, Part, UserMessage } from "@opencode-ai/sdk/v2/client"
 import { useLanguage } from "@/context/language"
 import { useProviders } from "@/hooks/use-providers"
 import { useSDK } from "@/context/sdk"

packages/app/src/components/settings-general.tsx

@@ -128,7 +128,11 @@ export const SettingsGeneral: Component = () => {
 
   const [shells] = createResource(
     async () => {
-      // TODO: Restore executable shell discovery; V2 shell.list only lists shell processes.
+      const sdk = serverSdk()
+      if ((await sdk.protocol) === "v1") {
+        return (await sdk.client.pty.shells()).data ?? []
+      }
+      // return (await sdk.api.pty.shells()).data
       return [] as ShellOption[]
     },
     { initialValue: [] as ShellOption[] },
@@ -327,7 +331,6 @@ export const SettingsGeneral: Component = () => {
         >
           <Select
             data-action="settings-shell"
-            disabled
             options={shellOptions()}
             current={shellOptions().find((o) => o.value === currentShell()) ?? autoOption}
             value={(o) => o.id}
@@ -335,8 +338,7 @@ export const SettingsGeneral: Component = () => {
             onSelect={(option) => {
               if (!option) return
               if (option.value === currentShell()) return
-              // TODO: Restore config writes when the V2 client exposes a config API.
-              // void serverSync().updateConfig({ shell: option.value })
+              serverSync().updateConfig({ shell: option.value })
             }}
             variant="secondary"
             size="small"

packages/app/src/components/settings-providers.tsx

@@ -6,7 +6,7 @@ import { showToast } from "@/utils/toast"
 import { popularProviders, useProviders } from "@/hooks/use-providers"
 import { createMemo, type Component, For, Show } from "solid-js"
 import { useLanguage } from "@/context/language"
-import { useServerSDK } from "@/context/server-sdk"
+import { useServerProtocol, useServerSDK } from "@/context/server-sdk"
 import { useServerSync } from "@/context/server-sync"
 import { DialogConnectProvider, useProviderConnectController } from "./dialog-connect-provider"
 import { DialogCustomProvider } from "./dialog-custom-provider"
@@ -39,6 +39,7 @@ const SettingsProvidersContent: Component<{ onBack?: () => void }> = (props) =>
   const dialog = useDialog()
   const language = useLanguage()
   const serverSDK = useServerSDK()
+  const protocol = useServerProtocol()
   const serverSync = useServerSync()
   const providers = useProviders(() => undefined)
   const providerConnect = useProviderConnectController({ onBack: props.onBack })
@@ -83,7 +84,8 @@ const SettingsProvidersContent: Component<{ onBack?: () => void }> = (props) =>
     return language.t("settings.providers.tag.other")
   }
 
-  const canDisconnect = (item: ProviderItem) => source(item) !== "env" && !isConfigCustom(item.id)
+  const canDisconnect = (item: ProviderItem) =>
+    source(item) !== "env" && (protocol() === "v1" || !isConfigCustom(item.id))
 
   const note = (id: string) => PROVIDER_NOTES.find((item) => item.match(id))?.key
 
@@ -96,7 +98,7 @@ const SettingsProvidersContent: Component<{ onBack?: () => void }> = (props) =>
   }
 
   const disableProvider = async (providerID: string, name: string) => {
-    return
+    if (protocol() !== "v1") return
     const before = serverSync().data.config.disabled_providers ?? []
     const next = before.includes(providerID) ? before : [...before, providerID]
     serverSync().set("config", "disabled_providers", next)
@@ -119,14 +121,17 @@ const SettingsProvidersContent: Component<{ onBack?: () => void }> = (props) =>
   }
 
   const disconnect = async (providerID: string, name: string) => {
+    if (isConfigCustom(providerID)) {
+      await serverSDK()
+        .client.auth.remove({ providerID })
+        .catch(() => undefined)
+      await disableProvider(providerID, name)
+      return
+    }
     await serverSDK()
-      .api.integration.get({ integrationID: providerID })
-      .then(async (integration) => {
-        const credentials = integration.data?.connections.filter((item) => item.type === "credential") ?? []
-        if (credentials.length === 0) throw new Error(`No removable credentials found for ${name}`)
-        await Promise.all(
-          credentials.map((credential) => serverSDK().api.credential.remove({ credentialID: credential.id })),
-        )
+      .client.auth.remove({ providerID })
+      .then(async () => {
+        await serverSDK().client.global.dispose()
         showToast({
           variant: "success",
           icon: "circle-check",
@@ -216,7 +221,7 @@ const SettingsProvidersContent: Component<{ onBack?: () => void }> = (props) =>
               )}
             </For>
 
-            <Show when={false}>
+            <Show when={protocol() === "v1"}>
               <div
                 class="flex items-center justify-between gap-4 min-h-16 border-b border-border-weak-base last:border-none flex-wrap py-3"
                 data-component="custom-provider-section"

packages/app/src/components/settings-v2/general.tsx

@@ -10,6 +10,7 @@ import { useLanguage } from "@/context/language"
 import { usePermission } from "@/context/permission"
 import { usePlatform } from "@/context/platform"
 import { useServerSync } from "@/context/server-sync"
+import { useServerSDK } from "@/context/server-sdk"
 import { useUpdaterAction } from "../updater-action"
 import {
   monoDefault,
@@ -90,6 +91,7 @@ export const SettingsGeneralV2: Component<{
   const dialog = useDialog()
   const settings = useSettings()
   const serverSync = useServerSync()
+  const serverSdk = useServerSDK()
   const mobile = createMediaQuery("(max-width: 767px)")
 
   const updater = useUpdaterAction()
@@ -121,7 +123,10 @@ export const SettingsGeneralV2: Component<{
 
   const [shells] = createResource(
     async () => {
-      // TODO: Restore executable shell discovery when the V2 client exposes it.
+      const sdk = serverSdk()
+      if ((await sdk.protocol) === "v1") {
+        return (await sdk.client.pty.shells()).data ?? []
+      }
       // return (await sdk.api.pty.shells()).data
       return [] as ShellOption[]
     },

packages/app/src/components/settings-v2/providers.tsx

@@ -6,7 +6,7 @@ import { showToast } from "@/utils/toast"
 import { popularProviders, useProviders } from "@/hooks/use-providers"
 import { createMemo, type Accessor, type Component, For, Show } from "solid-js"
 import { useLanguage } from "@/context/language"
-import { useServerSDK } from "@/context/server-sdk"
+import { useServerProtocol, useServerSDK } from "@/context/server-sdk"
 import { useServerSync } from "@/context/server-sync"
 import { DialogConnectProvider, useProviderConnectController } from "../dialog-connect-provider"
 import { DialogCustomProvider } from "../dialog-custom-provider"
@@ -36,6 +36,7 @@ export const SettingsProvidersV2: Component<{
   const dialog = useDialog()
   const language = useLanguage()
   const serverSdk = useServerSDK()
+  const protocol = useServerProtocol()
   const serverSync = useServerSync()
   const providers = useProviders(props.directory)
   const providerConnect = useProviderConnectController({ onBack: props.onBack })
@@ -80,7 +81,8 @@ export const SettingsProvidersV2: Component<{
     return language.t("settings.providers.tag.other")
   }
 
-  const canDisconnect = (item: ProviderItem) => source(item) !== "env" && !isConfigCustom(item.id)
+  const canDisconnect = (item: ProviderItem) =>
+    source(item) !== "env" && (protocol() === "v1" || !isConfigCustom(item.id))
 
   const note = (id: string) => PROVIDER_NOTES.find((item) => item.match(id))?.key
 
@@ -93,7 +95,7 @@ export const SettingsProvidersV2: Component<{
   }
 
   const disableProvider = async (providerID: string, name: string) => {
-    return
+    if (protocol() !== "v1") return
     const before = serverSync().data.config.disabled_providers ?? []
     const next = before.includes(providerID) ? before : [...before, providerID]
     serverSync().set("config", "disabled_providers", next)
@@ -116,17 +118,17 @@ export const SettingsProvidersV2: Component<{
   }
 
   const disconnect = async (providerID: string, name: string) => {
-    const location = props.directory() ? { directory: props.directory() } : undefined
+    if (isConfigCustom(providerID)) {
+      await serverSdk()
+        .client.auth.remove({ providerID })
+        .catch(() => undefined)
+      await disableProvider(providerID, name)
+      return
+    }
     await serverSdk()
-      .api.integration.get({ integrationID: providerID, location })
-      .then(async (integration) => {
-        const credentials = integration.data?.connections.filter((item) => item.type === "credential") ?? []
-        if (credentials.length === 0) throw new Error(`No removable credentials found for ${name}`)
-        await Promise.all(
-          credentials.map((credential) =>
-            serverSdk().api.credential.remove({ credentialID: credential.id, location }),
-          ),
-        )
+      .client.auth.remove({ providerID })
+      .then(async () => {
+        await serverSdk().client.global.dispose()
         showToast({
           variant: "success",
           icon: "circle-check",
@@ -222,7 +224,7 @@ export const SettingsProvidersV2: Component<{
               )}
             </For>
 
-            <Show when={false}>
+            <Show when={protocol() === "v1"}>
               <div class="settings-v2-provider-row" data-component="custom-provider-section">
                 <div class="settings-v2-provider-lead">
                   <ProviderIcon

packages/app/src/components/status-popover-body.tsx

@@ -5,7 +5,7 @@ import { Switch } from "@opencode-ai/ui/switch"
 import { Tabs } from "@opencode-ai/ui/tabs"
 import { showToast } from "@/utils/toast"
 import { useNavigate } from "@solidjs/router"
-import { type Accessor, createEffect, createMemo, createResource, For, type JSXElement, onCleanup, Show } from "solid-js"
+import { type Accessor, createEffect, createMemo, For, type JSXElement, onCleanup, Show } from "solid-js"
 import { createStore } from "solid-js/store"
 import { ServerHealthIndicator, ServerRow } from "@/components/server/server-row"
 import { useLanguage } from "@/context/language"
@@ -16,7 +16,7 @@ import { type ServerHealth } from "@/utils/server-health"
 import { useGlobal } from "@/context/global"
 import { useSettings } from "@/context/settings"
 import { useMcpToggle } from "@/context/mcp"
-import { useSDK } from "@/context/sdk"
+import { useServerProtocol } from "@/context/server-sdk"
 
 const pluginEmptyMessage = (value: string, file: string): JSXElement => {
   const parts = value.split(file)
@@ -251,7 +251,6 @@ function ServerStatusList(props: { state: ServerStatusState }) {
 
 export function StatusPopoverBody(props: { shown: Accessor<boolean> }) {
   const sync = useSync()
-  const sdk = useSDK()
   const global = useGlobal()
   const server = useServer()
   const platform = usePlatform()
@@ -259,6 +258,7 @@ export function StatusPopoverBody(props: { shown: Accessor<boolean> }) {
   const language = useLanguage()
   const navigate = useNavigate()
   const settings = useSettings()
+  const protocol = useServerProtocol()
 
   const fail = (err: unknown) => {
     showToast({
@@ -279,7 +279,9 @@ export function StatusPopoverBody(props: { shown: Accessor<boolean> }) {
     dialogRun += 1
   })
   const sortedServers = createMemo(() => {
-    const list = global.servers.list()
+    const list = settings.general.newLayoutDesigns()
+      ? global.servers.list()
+      : global.servers.list().filter((x) => global.ensureServerCtx(x).sdk.protocolKind() !== "v2")
     return listServersByHealth(list, server.key, global.servers.health)
   })
   const toggleMcp = useMcpToggle()
@@ -289,11 +291,9 @@ export function StatusPopoverBody(props: { shown: Accessor<boolean> }) {
   const mcpConnected = createMemo(() => mcpNames().filter((name) => mcpStatus(name) === "connected").length)
   const lspItems = createMemo(() => sync().data.lsp ?? [])
   const lspCount = createMemo(() => lspItems().length)
-  const [pluginList] = createResource(
-    () => (props.shown() ? sdk().directory : undefined),
-    (directory) => sdk().api.plugin.list({ location: { directory } }).then((result) => result.data),
+  const plugins = createMemo(() =>
+    (sync().data.config.plugin ?? []).map((item) => (typeof item === "string" ? item : item[0])),
   )
-  const plugins = createMemo(() => (pluginList.latest ?? []).map((item) => item.id))
   const pluginCount = createMemo(() => plugins().length)
   const pluginEmpty = createMemo(() => pluginEmptyMessage(language.t("dialog.plugins.empty"), "opencode.json"))
 
@@ -322,7 +322,7 @@ export function StatusPopoverBody(props: { shown: Accessor<boolean> }) {
             {lspCount() > 0 ? `${lspCount()} ` : ""}
             {language.t("status.popover.tab.lsp")}
           </Tabs.Trigger>
-          <Show when={true}>
+          <Show when={protocol() === "v1"}>
             <Tabs.Trigger value="plugins" data-slot="tab" class="text-12-regular">
               {pluginCount() > 0 ? `${pluginCount()} ` : ""}
               {language.t("status.popover.tab.plugins")}
@@ -487,7 +487,7 @@ export function StatusPopoverBody(props: { shown: Accessor<boolean> }) {
           </div>
         </Tabs.Content>
 
-        <Show when={true}>
+        <Show when={protocol() === "v1"}>
           <Tabs.Content value="plugins">
             <div class="flex flex-col px-2 pb-2">
               <div class="flex flex-col p-3 bg-background-base rounded-sm min-h-14">

packages/app/src/components/status-popover-indicator.ts

@@ -1,4 +1,4 @@
-import type { LspStatus } from "@/types"
+import type { LspStatus } from "@opencode-ai/sdk/v2/client"
 import type { McpServer } from "@opencode-ai/client/promise"
 
 export function hasServiceNeedingAttention(input: { mcp: Array<McpServer["status"]["status"]> }) {

packages/app/src/components/terminal.tsx

@@ -11,6 +11,7 @@ import { matchKeybind, parseKeybind } from "@/context/command"
 import { useLanguage } from "@/context/language"
 import { usePlatform } from "@/context/platform"
 import { useSDK } from "@/context/sdk"
+import { useServerSDK } from "@/context/server-sdk"
 import { terminalFontFamily, useSettings } from "@/context/settings"
 import type { LocalPTY } from "@/context/terminal"
 import { disposeIfDisposable, getHoveredLinkText, setOptionIfSupported } from "@/utils/runtime-adapters"
@@ -174,8 +175,15 @@ export const Terminal = (props: TerminalProps) => {
   const settings = useSettings()
   const theme = useTheme()
   const language = useLanguage()
+  // Terminal captures its connection for the PTY lifetime, so callers must key it per server/session.
+  const connection = useServerSDK()().server
   const directory = sdk().directory
   const url = sdk().url
+  const auth = connection.http
+  const username = auth?.username ?? "opencode"
+  const password = auth?.password ?? ""
+  const authToken = connection.type === "http" ? connection.authToken : false
+  const sameOrigin = new URL(url, location.href).origin === location.origin
   let container!: HTMLDivElement
   const [local, others] = splitProps(props, [
     "pty",
@@ -233,6 +241,16 @@ export const Terminal = (props: TerminalProps) => {
   }
 
   const pushSize = async (cols: number, rows: number) => {
+    if ((await sdk().protocol) === "v1") {
+      return sdk()
+        .client.pty.update({
+          ptyID: id,
+          size: { cols, rows },
+        })
+        .catch((err) => {
+          debugTerminal("failed to sync terminal size", err)
+        })
+    }
     return sdk()
       .api.pty.update({
         ptyID: id,
@@ -515,6 +533,15 @@ export const Terminal = (props: TerminalProps) => {
       }
 
       const gone = async () => {
+        if ((await sdk().protocol) === "v1") {
+          return sdk()
+            .client.pty.get({ ptyID: id }, { throwOnError: false })
+            .then((result) => result.response.status === 404)
+            .catch((err) => {
+              debugTerminal("failed to inspect terminal session", err)
+              return false
+            })
+        }
         return sdk()
           .api.pty.get({ ptyID: id, location: { directory } })
           .then((result) => result.data.status === "exited")
@@ -526,8 +553,33 @@ export const Terminal = (props: TerminalProps) => {
       }
 
       const connectToken = async () => {
-        // TODO: Add PTY tickets when the V2 client exposes a connect-token API.
-        return undefined
+        if ((await sdk().protocol) === "v1") {
+          const result = await sdk()
+            .client.pty.connectToken(
+              { ptyID: id, directory },
+              {
+                throwOnError: false,
+                headers: { "x-opencode-ticket": "1" },
+              },
+            )
+            .catch((err: unknown) => {
+              if (err instanceof Error && err.message.includes("Request is not supported")) return
+              throw err
+            })
+          if (!result) return
+          if (result.response.status === 200 && result.data?.ticket) return result.data.ticket
+          if (result.response.status === 404 || result.response.status === 405) return
+          if (result.response.status === 403)
+            throw new Error("PTY connect ticket rejected by origin or CSRF checks. Check the server CORS config.")
+          throw new Error(`PTY connect ticket failed with ${result.response.status}`)
+        }
+        // return sdk()
+        //   .api.pty.connectToken({
+        //     ptyID: id,
+        //     location: { directory },
+        //     "x-opencode-ticket": "1",
+        //   })
+        //   .then((result) => result.data.ticket)
       }
 
       const retry = (err: unknown) => {
@@ -557,16 +609,23 @@ export const Terminal = (props: TerminalProps) => {
           fail(err)
           return undefined
         })
+        const protocol = await sdk().protocol
+        // if (protocol === "v2" && !ticket) return
         if (once.value) return
         if (disposed) return
 
         const socket = new WebSocket(
           terminalWebSocketURL({
+            protocol,
             url,
             id,
             directory,
             cursor: seek,
             ticket,
+            sameOrigin,
+            username,
+            password,
+            authToken,
           }),
         )
         socket.binaryType = "arraybuffer"

packages/app/src/components/titlebar-tab-nav.tsx

@@ -4,11 +4,12 @@ import { createResizeObserver } from "@solid-primitives/resize-observer"
 import { createMutation } from "@tanstack/solid-query"
 import { IconButtonV2 } from "@opencode-ai/ui/v2/icon-button-v2"
 import { Icon as IconV2 } from "@opencode-ai/ui/v2/icon"
+import { displayLabel } from "@opencode-ai/util/session-title-fallback"
 import { useGlobal } from "@/context/global"
 import { ServerConnection, serverName } from "@/context/server"
 import { displayName, projectForSession } from "@/pages/layout/helpers"
 import { SessionTabAvatar } from "@/pages/layout/session-tab-avatar"
-import type { Session } from "@/types"
+import type { Session } from "@opencode-ai/sdk/v2"
 import { canOpenTabRename, forwardTabRef } from "./titlebar-tab-gesture"
 import { TabPreviewPopover } from "./titlebar-tab-popover"
 import "./titlebar-tab-nav.css"
@@ -54,7 +55,10 @@ export function TabNavItem(props: {
     if (!session) return
     return projectForSession(session, serverCtx()?.projects.list() ?? [])
   })
-  const title = createMemo(() => props.session()?.title ?? props.fallbackTitle)
+  const title = createMemo(() => {
+    const session = props.session()
+    return session ? displayLabel(session) : props.fallbackTitle
+  })
 
   const projectName = createMemo(() => {
     const session = props.session()
@@ -143,7 +147,7 @@ export function TabNavItem(props: {
     if (!canOpenTabRename(props.dragging, editing(), rename.isPending)) return
     const session = props.session()
     if (!session) return
-    titleEl.textContent = session.title
+    titleEl.textContent = session.title ?? ""
     setEditing(true)
 
     requestAnimationFrame(() => {
@@ -302,7 +306,7 @@ export function TabNavItem(props: {
       }}
       data={{
         projectName: projectName(),
-        title: props.session()?.title,
+        title: title(),
         path: previewPath(),
         serverName: serverLabel(),
       }}

packages/app/src/components/titlebar-tab-strip.tsx

@@ -19,7 +19,7 @@ import { base64Encode } from "@opencode-ai/core/util/encode"
 import { showToast } from "@/utils/toast"
 import { canStartTabDrag, isTabCloseTarget } from "./titlebar-tab-gesture"
 import { adjacentTabKey, mergeVisibleTabOrder } from "./titlebar-tab-order"
-import type { Session } from "@/types"
+import type { Session } from "@opencode-ai/sdk/v2"
 
 function SessionTabSlot(props: {
   tab: SessionTab

packages/app/src/context/directory-sync.ts

@@ -1,5 +1,5 @@
 import { Binary } from "@opencode-ai/core/util/binary"
-import type { Message, Part, Session } from "@/types"
+import type { Message, Part, Session } from "@opencode-ai/sdk/v2/client"
 import { createMemo } from "solid-js"
 import { produce, reconcile, type SetStoreFunction } from "solid-js/store"
 import type { createServerSdkContext } from "./server-sdk"
@@ -26,6 +26,7 @@ export const createDirSyncContext = (
   serverSync: ReturnType<typeof createServerSyncContextInner>,
   serverSDK: ReturnType<typeof createServerSdkContext>,
 ) => {
+  const client = serverSDK.createClient({ directory, throwOnError: true })
   const current = createMemo(() => serverSync.child(directory, { mcp: true }))
   const absolute = (path: string) => (current()[0].path.directory + "/" + path).replace("//", "/")
   const data = new Proxy({} as State, {
@@ -133,8 +134,15 @@ export const createDirSyncContext = (
       },
       more: createMemo(() => current()[0].session.length >= current()[0].limit),
       archive: async (sessionID: string) => {
-        // TODO: Restore archiving when the V2 client exposes a session archive API.
-        void sessionID
+        if ((await serverSDK.protocol) !== "v1") return
+        await serverSDK.client.session.update({ sessionID, directory, time: { archived: Date.now() } })
+        current()[1](
+          "session",
+          produce((draft) => {
+            const match = Binary.search(draft, sessionID, (session) => session.id)
+            if (match.found) draft.splice(match.index, 1)
+          }),
+        )
       },
     },
     mcp: {

packages/app/src/context/file.tsx

@@ -81,15 +81,8 @@ export const { use: useFile, provider: FileProvider } = createSimpleContext({
       normalizeDir: path.normalizeDir,
       list: (dir) =>
         sdk()
-          .api.file.list({ path: dir, location: { directory: scope() } })
-          .then((x) =>
-            x.data.map((entry) => ({
-              ...entry,
-              name: entry.path.split("/").at(-1) ?? entry.path,
-              absolute: `${scope()}/${entry.path}`,
-              ignored: false,
-            })),
-          ),
+          .client.file.list({ path: dir })
+          .then((x) => x.data ?? []),
       onError: (message) => {
         showToast({
           variant: "error",
@@ -188,10 +181,10 @@ export const { use: useFile, provider: FileProvider } = createSimpleContext({
       setLoading(file)
 
       const promise = sdk()
-        .api.file.read({ path: file, location: { directory } })
-        .then((data) => {
+        .client.file.read({ path: file })
+        .then((x) => {
           if (scope() !== directory) return
-          const content = { type: "text" as const, content: new TextDecoder().decode(data) }
+          const content = x.data
           setLoaded(file, content)
 
           if (!content) return

packages/app/src/context/file/content-cache.ts

@@ -1,4 +1,4 @@
-import type { FileContent } from "@/types"
+import type { FileContent } from "@opencode-ai/sdk/v2"
 
 const MAX_FILE_CONTENT_ENTRIES = 40
 const MAX_FILE_CONTENT_BYTES = 20 * 1024 * 1024

packages/app/src/context/file/tree-store.ts

@@ -1,5 +1,5 @@
 import { createStore, produce, reconcile } from "solid-js/store"
-import type { FileNode } from "@/types"
+import type { FileNode } from "@opencode-ai/sdk/v2"
 
 type DirectoryState = {
   expanded: boolean

packages/app/src/context/file/types.ts

@@ -1,4 +1,4 @@
-import type { FileContent } from "@/types"
+import type { FileContent } from "@opencode-ai/sdk/v2"
 
 export type FileSelection = {
   startLine: number

packages/app/src/context/file/watcher.ts

@@ -1,4 +1,4 @@
-import type { FileNode } from "@/types"
+import type { FileNode } from "@opencode-ai/sdk/v2"
 
 type WatcherEvent = {
   type: string

packages/app/src/context/global-sync/bootstrap.test.ts

@@ -1,8 +1,11 @@
 import { describe, expect, test } from "bun:test"
+import { createStore } from "solid-js/store"
 import { QueryClient } from "@tanstack/solid-query"
+import type { Config, OpencodeClient, Project } from "@opencode-ai/sdk/v2/client"
 import type { AgentApi, CatalogApi, CommandApi, ReferenceApi } from "@opencode-ai/client/promise"
 import type { NormalizedProviderListResponse } from "@opencode-ai/session-ui/context"
 import {
+  bootstrapDirectory,
   loadAgentsQuery,
   loadCommands,
   loadPathQuery,
@@ -10,19 +13,139 @@ import {
   loadProvidersQuery,
   loadReferencesQuery,
 } from "./bootstrap"
+import type { State, VcsCache } from "./types"
 import { ServerScope } from "@/utils/server-scope"
 import type { ServerApi } from "@/utils/server"
 
 type ProjectApi = ServerApi["project"]
 
+const provider = { all: new Map(), connected: [], default: {} } satisfies NormalizedProviderListResponse
+const api = {
+  agent: { list: async () => ({ location: {}, data: [] }) },
+  provider: { list: async () => ({ location: {}, data: [] }) },
+  model: {
+    list: async () => ({ location: {}, data: [] }),
+    default: async () => ({ location: {}, data: null }),
+  },
+  permission: { request: { list: async () => ({ location: {}, data: [] }) } },
+  project: {
+    list: async () => [],
+    current: async () => ({ id: "project", directory: "/project" }),
+  },
+  question: { request: { list: async () => ({ location: {}, data: [] }) } },
+  reference: { list: async () => ({ location: {}, data: [] }) },
+  vcs: { get: async () => ({ location: {}, data: {} }) },
+} as unknown as ServerApi
+
+function directoryState() {
+  return createStore<State>({
+    status: "loading",
+    agent: [],
+    command: [],
+    reference: [],
+    project: "",
+    projectMeta: undefined,
+    icon: undefined,
+    provider_ready: true,
+    provider,
+    config: {},
+    path: { state: "", config: "", worktree: "/project", directory: "/project", home: "/home" },
+    session: [],
+    sessionTotal: 0,
+    session_status: {},
+    session_working(id: string) {
+      return this.session_status[id]?.type !== "idle"
+    },
+    session_diff: {},
+    todo: {},
+    permission: {},
+    question: {},
+    mcp_ready: true,
+    mcp: {},
+    mcp_resource: {},
+    lsp_ready: true,
+    lsp: [],
+    vcs: undefined,
+    limit: 5,
+    message: {},
+    session_message: {},
+    part: {},
+    part_text_accum_delta: {},
+  })
+}
+
+describe("bootstrapDirectory", () => {
+  test("uses legacy MCP endpoints while refreshing a v1 directory", async () => {
+    const mcpReads: string[] = []
+    const [store, setStore] = directoryState()
+
+    await bootstrapDirectory({
+      directory: "/project",
+      scope: ServerScope.local,
+      mcp: true,
+      global: {
+        config: {} satisfies Config,
+        path: { state: "", config: "", worktree: "/project", directory: "/project", home: "/home" },
+        project: [{ id: "project", worktree: "/project" } as Project],
+        provider,
+      },
+      sdk: {
+        app: { agents: async () => ({ data: [{ name: "build", mode: "primary" }] }) },
+        config: { get: async () => ({ data: {} }) },
+        session: { status: async () => ({ data: {} }) },
+        vcs: { get: async () => ({ data: undefined }) },
+        command: {
+          list: async () => {
+            mcpReads.push("command")
+            return { data: [] }
+          },
+        },
+        permission: { list: async () => ({ data: [] }) },
+        question: { list: async () => ({ data: [] }) },
+        v2: { reference: { list: async () => ({ data: { data: [] } }) } },
+        mcp: {
+          status: async () => {
+            mcpReads.push("status")
+            return { data: {} }
+          },
+        },
+        experimental: {
+          resource: {
+            list: async () => {
+              mcpReads.push("resource")
+              return { data: {} }
+            },
+          },
+        },
+        provider: { list: async () => ({ data: { all: [], connected: [], default: {} } }) },
+      } as unknown as OpencodeClient,
+      api,
+      store,
+      setStore,
+      vcsCache: { setStore() {} } as unknown as VcsCache,
+      loadSessions() {},
+      translate: (key) => key,
+      queryClient: new QueryClient(),
+      protocol: Promise.resolve("v1"),
+    })
+
+    expect(store.status).toBe("partial")
+
+    await new Promise((resolve) => setTimeout(resolve, 80))
+
+    expect(store.status).toBe("complete")
+    expect(mcpReads.sort()).toEqual(["command", "resource", "status"])
+  })
+})
+
 describe("query keys", () => {
   test("partitions identical directories by server scope", () => {
+    const client = {} as Parameters<typeof loadPathQuery>[2]
     const api = {} as CatalogApi
-    const location = {} as ServerApi["location"]
     const remote = "https://debian.example" as typeof ServerScope.local
 
-    expect([...loadPathQuery(ServerScope.local, "/repo", location).queryKey]).toEqual(["local", "/repo", "path"])
-    expect([...loadPathQuery(remote, "/repo", location).queryKey]).toEqual(["https://debian.example", "/repo", "path"])
+    expect([...loadPathQuery(ServerScope.local, "/repo", client).queryKey]).toEqual(["local", "/repo", "path"])
+    expect([...loadPathQuery(remote, "/repo", client).queryKey]).toEqual(["https://debian.example", "/repo", "path"])
     expect([...loadProvidersQuery(remote, null, api).queryKey]).toEqual(["https://debian.example", null, "providers"])
   })
 
@@ -57,21 +180,6 @@ describe("query keys", () => {
     expect(result.connected).toEqual(["openai"])
   })
 
-  test("loads current location metadata", async () => {
-    const calls: unknown[] = []
-    const api = {
-      get: async (input: unknown) => {
-        calls.push(input)
-        return { directory: "/repo/subpath", project: { id: "project", directory: "/repo" } }
-      },
-    } as ServerApi["location"]
-
-    const result = await new QueryClient().fetchQuery(loadPathQuery(ServerScope.local, "/repo/subpath", api))
-
-    expect(calls).toEqual([{ location: { directory: "/repo/subpath" } }])
-    expect(result).toMatchObject({ directory: "/repo/subpath", worktree: "/repo" })
-  })
-
   test("loads agents from the current location-scoped endpoint", async () => {
     const calls: unknown[] = []
     const api = {