feat(llm): lower thinking toggle and max effort for OpenAI-compatible chat

See U · See U · commit 4afdb14f8808 · 2026-08-01T01:10:51.000+08:00
diff --git a/packages/llm/src/protocols/openai-chat.ts b/packages/llm/src/protocols/openai-chat.ts
@@ -97,6 +97,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),
+  thinking: Schema.optional(OpenAIOptions.OpenAIThinking),
   max_tokens: Schema.optional(Schema.Number),
   temperature: Schema.optional(Schema.Number),
   top_p: Schema.optional(Schema.Number),
@@ -128,6 +129,10 @@ const OpenAIChatUsage = Schema.Struct({
       reasoning_tokens: Schema.optional(Schema.Number),
     }),
   ),
+  // DeepSeek reports the cache split natively (prompt_tokens = hit + miss)
+  // at the top level; keep the raw fields for billing-level audit trails.
+  prompt_cache_hit_tokens: Schema.optional(Schema.Number),
+  prompt_cache_miss_tokens: Schema.optional(Schema.Number),
 })
 
 const OpenAIChatToolCallDeltaFunction = Schema.Struct({
@@ -333,14 +338,25 @@ const lowerMessages = Effect.fn("OpenAIChat.lowerMessages")(function* (request:
 const lowerOptions = Effect.fn("OpenAIChat.lowerOptions")(function* (request: LLMRequest) {
   const store = OpenAIOptions.store(request)
   const reasoningEffort = OpenAIOptions.reasoningEffort(request)
-  if (reasoningEffort && !OpenAIOptions.isReasoningEffort(reasoningEffort))
+  const thinking = OpenAIOptions.thinking(request)
+  // `max` is a Responses-only tier on OpenAI-managed chat surfaces (OpenAI,
+  // Azure, GitHub Copilot); DeepSeek V4 pro honors it natively on Chat
+  // Completions. The shared protocol keys the rejection off the provider id
+  // so OpenAI-family requests keep the local guard while deepseek passes.
+  if (reasoningEffort === "max" && OPENAI_MAX_EFFORT_INVALID.has(request.model.provider))
     return yield* invalid(`OpenAI Chat does not support reasoning effort ${reasoningEffort}`)
   return {
     ...(store !== undefined ? { store } : {}),
     ...(reasoningEffort ? { reasoning_effort: reasoningEffort } : {}),
+    ...(thinking ? { thinking } : {}),
   }
 })
 
+// OpenAI Chat Completions (and Azure / GitHub Copilot deployments of it)
+// reject the `max` reasoning effort tier; everything else routed through
+// this protocol is provider-enforced.
+const OPENAI_MAX_EFFORT_INVALID = new Set<string>(["openai", "azure", "github-copilot"])
+
 const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (request: LLMRequest) {
   // `fromRequest` returns the provider body only. Endpoint, auth, framing,
   // validation, and HTTP execution are composed by `Route.make`.
@@ -387,10 +403,16 @@ const mapFinishReason = (reason: string | null | undefined): FinishReason => {
 // `cached_tokens` subset, and `completion_tokens` (inclusive total) with
 // a `reasoning_tokens` subset. We pass the inclusive totals through and
 // derive the non-cached breakdown so the `LLM.Usage` contract is
-// satisfied on both sides.
+// satisfied on both sides. DeepSeek additionally reports the cache split
+// natively (`prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`);
+// prefer those when present since they survive even without the details
+// object.
 const mapUsage = (usage: OpenAIChatEvent["usage"]): Usage | undefined => {
   if (!usage) return undefined
-  const cached = usage.prompt_tokens_details?.cached_tokens
+  const cached =
+    usage.prompt_cache_hit_tokens !== undefined
+      ? usage.prompt_cache_hit_tokens
+      : usage.prompt_tokens_details?.cached_tokens
   const reasoning = usage.completion_tokens_details?.reasoning_tokens
   const nonCached = ProviderShared.subtractTokens(usage.prompt_tokens, cached)
   return new Usage({
diff --git a/packages/llm/src/protocols/openai-responses.ts b/packages/llm/src/protocols/openai-responses.ts
@@ -457,8 +457,11 @@ const lowerOptions = Effect.fn("OpenAIResponses.lowerOptions")(function* (reques
   const store = OpenAIOptions.store(request)
   const promptCacheKey = OpenAIOptions.promptCacheKey(request)
   const effort = OpenAIOptions.reasoningEffort(request)
-  if (effort && !OpenAIOptions.isReasoningEffort(effort))
-    return yield* invalid(`OpenAI Responses does not support reasoning effort ${effort}`)
+  // `reasoningEffort` already filters through the full `ReasoningEfforts`
+  // set, so the only value that can reach here is the Responses-incompatible
+  // `max` tier.
+  if (effort === "max")
+    return yield* invalid("OpenAI Responses does not support reasoning effort max")
   const summary = OpenAIOptions.reasoningSummary(request)
   const include = OpenAIOptions.include(request)
   const verbosity = OpenAIOptions.textVerbosity(request)
diff --git a/packages/llm/src/protocols/utils/openai-options.ts b/packages/llm/src/protocols/utils/openai-options.ts
@@ -2,9 +2,7 @@ import { Schema } from "effect"
 import type { LLMRequest, ReasoningEffort, TextVerbosity as TextVerbosityValue } from "../../schema"
 import { ReasoningEfforts, TextVerbosity } from "../../schema"
 
-export const OpenAIReasoningEfforts = ReasoningEfforts.filter(
-  (effort): effort is Exclude<ReasoningEffort, "max"> => effort !== "max",
-)
+export const OpenAIReasoningEfforts = [...ReasoningEfforts]
 export type OpenAIReasoningEffort = (typeof OpenAIReasoningEfforts)[number]
 
 // Mirrors OpenAI's `ResponseIncludable` union from the official SDK. Keep this
@@ -24,7 +22,6 @@ export const OpenAIServiceTiers = ["auto", "default", "flex", "priority"] as con
 export type OpenAIServiceTier = (typeof OpenAIServiceTiers)[number]
 
 const REASONING_EFFORTS = new Set<string>(ReasoningEfforts)
-const OPENAI_REASONING_EFFORTS = new Set<string>(OpenAIReasoningEfforts)
 const TEXT_VERBOSITY = new Set<string>(["low", "medium", "high"])
 const INCLUDABLES = new Set<string>(OpenAIResponseIncludables)
 const SERVICE_TIERS = new Set<string>(OpenAIServiceTiers)
@@ -37,8 +34,30 @@ export const OpenAIServiceTier = Schema.Literals(OpenAIServiceTiers)
 const isAnyReasoningEffort = (effort: unknown): effort is ReasoningEffort =>
   typeof effort === "string" && REASONING_EFFORTS.has(effort)
 
-export const isReasoningEffort = (effort: unknown): effort is OpenAIReasoningEffort =>
-  typeof effort === "string" && OPENAI_REASONING_EFFORTS.has(effort)
+// DeepSeek V4 toggles thinking with `{ type: "enabled" | "disabled" }` on the
+// official API; opencode-managed minimax mirrors also surface `"adaptive"`.
+// z.ai/zhipuai additionally accept `clear_thinking`. Validate against the
+// literal set so an unknown type never poisons the body.
+const ThinkingTypes = ["enabled", "disabled", "adaptive"] as const
+type ThinkingType = (typeof ThinkingTypes)[number]
+const THINKING_TYPES = new Set<string>(ThinkingTypes)
+
+export const OpenAIThinking = Schema.Struct({
+  type: Schema.Literals(ThinkingTypes),
+  clear_thinking: Schema.optional(Schema.Boolean),
+})
+export type OpenAIThinking = Schema.Schema.Type<typeof OpenAIThinking>
+
+const isThinkingType = (value: unknown): value is ThinkingType =>
+  typeof value === "string" && THINKING_TYPES.has(value)
+
+export const thinking = (request: LLMRequest): OpenAIThinking | undefined => {
+  const value = options(request)?.thinking
+  if (typeof value !== "object" || value === null || !("type" in value)) return undefined
+  const { type, clear_thinking } = value as { type: unknown; clear_thinking?: unknown }
+  if (!isThinkingType(type)) return undefined
+  return { type, ...(typeof clear_thinking === "boolean" ? { clear_thinking } : {}) }
+}
 
 const isTextVerbosity = (value: unknown): value is TextVerbosityValue =>
   typeof value === "string" && TEXT_VERBOSITY.has(value)
diff --git a/packages/llm/test/provider/openai-chat.test.ts b/packages/llm/test/provider/openai-chat.test.ts
@@ -107,6 +107,89 @@ describe("OpenAI Chat route", () => {
     }),
   )
 
+  it.effect("lowers OpenAI-compatible thinking toggles to the wire body", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          prompt: "think",
+          providerOptions: { openai: { thinking: { type: "disabled" } } },
+        }),
+      )
+
+      expect(prepared.body.thinking).toEqual({ type: "disabled" })
+    }),
+  )
+
+  it.effect("passes z.ai clear_thinking through the thinking toggle", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          prompt: "think",
+          providerOptions: { openai: { thinking: { type: "enabled", clear_thinking: false } } },
+        }),
+      )
+
+      expect(prepared.body.thinking).toEqual({ type: "enabled", clear_thinking: false })
+    }),
+  )
+
+  it.effect("rejects max reasoning effort on OpenAI-managed chat", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          prompt: "think",
+          providerOptions: { openai: { reasoningEffort: "max" } },
+        }),
+      ).pipe(Effect.flip)
+      expect(error.message).toContain("does not support reasoning effort max")
+    }),
+  )
+
+  it.effect("passes max reasoning effort through for OpenAI-compatible providers", () =>
+    Effect.gen(function* () {
+      const deepseek = OpenAIChat.route
+        .with({
+          provider: "opencode.deepseek",
+          endpoint: { baseURL: "https://api.example.test/v1/" },
+          auth: Auth.bearer("test"),
+        })
+        .model({ id: "deepseek-v4-pro" })
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model: deepseek,
+          prompt: "think",
+          providerOptions: { openai: { reasoningEffort: "max" } },
+        }),
+      )
+
+      expect(prepared.body.reasoning_effort).toBe("max")
+    }),
+  )
+
+  it.effect("replays reasoning_content from native openaiCompatible metadata", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.make({
+              role: "assistant",
+              content: "Hello",
+              native: { openaiCompatible: { reasoning_content: "thinking" } },
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        { role: "assistant", content: "Hello", reasoning_content: "thinking" },
+      ])
+    }),
+  )
+
   it.effect("adds native query params to the Chat Completions URL", () =>
     LLMClient.generate(
       LLM.updateRequest(request, {
@@ -526,6 +609,45 @@ describe("OpenAI Chat route", () => {
     }),
   )
 
+  it.effect("prefers DeepSeek native cache fields over the cached_tokens detail", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        deltaChunk({ role: "assistant", content: "Hi" }),
+        deltaChunk({}, "stop"),
+        usageChunk({
+          prompt_tokens: 100,
+          completion_tokens: 2,
+          total_tokens: 102,
+          prompt_tokens_details: { cached_tokens: 1 },
+          prompt_cache_hit_tokens: 88,
+          prompt_cache_miss_tokens: 12,
+        }),
+      )
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+      expect(response.events.at(-1)).toEqual({
+        type: "finish",
+        reason: "stop",
+        usage: new Usage({
+          inputTokens: 100,
+          outputTokens: 2,
+          nonCachedInputTokens: 12,
+          cacheReadInputTokens: 88,
+          totalTokens: 102,
+          providerMetadata: {
+            openai: {
+              prompt_tokens: 100,
+              completion_tokens: 2,
+              total_tokens: 102,
+              prompt_tokens_details: { cached_tokens: 1 },
+              prompt_cache_hit_tokens: 88,
+              prompt_cache_miss_tokens: 12,
+            },
+          },
+        }),
+      })
+    }),
+  )
+
   it.effect("parses OpenAI-compatible reasoning content deltas", () =>
     Effect.gen(function* () {
       const body = sseEvents(
diff --git a/packages/llm/test/provider/openai-responses.test.ts b/packages/llm/test/provider/openai-responses.test.ts
@@ -571,6 +571,19 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
+  it.effect("rejects max reasoning effort on OpenAI Responses", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          prompt: "think",
+          providerOptions: { openai: { reasoningEffort: "max" } },
+        }),
+      ).pipe(Effect.flip)
+      expect(error.message).toContain("does not support reasoning effort max")
+    }),
+  )
+
   it.effect("accepts the full ResponseIncludable union", () =>
     Effect.gen(function* () {
       const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
