fix(core): preserve model request semantics

CONTEXT.md

@@ -39,6 +39,13 @@ An expected temporary inability to observe a **Context Source** value; the runti
 **Safe Provider-Turn Boundary**:
 The point immediately before a provider call, after durable input promotion and any required tool settlement, where context changes may be admitted chronologically.
 
+**Model Request Options**:
+Provider-semantic model settings selected from the Catalog and active Session variant before the LLM protocol adapter encodes them for a provider request.
+_Avoid_: Request body, wire options
+
+**Generation Controls**:
+Provider-neutral sampling and output controls, partitioned from provider semantics and compatibility wire fields when model metadata enters the Catalog.
+
 ## Relationships
 
 - A **System Context** is an opaque carrier composed from zero or more **Context Sources**.
@@ -84,6 +91,8 @@ The point immediately before a provider call, after durable input promotion and
 - A **Baseline System Context** durably preserves the exact joined text used for the active provider-cache prefix.
 - Compaction or a model/provider switch starts a new **Context Epoch** because the baseline can be replaced without preserving the prior provider cache.
 - A model/provider switch always starts a new **Context Epoch** while preserving chronological conversation history.
+- **Model Request Options** remain provider-semantic through Catalog resolution. The Session runner maps them into the LLM package's provider-option namespace; the selected protocol adapter alone owns provider wire encoding.
+- **Generation Controls**, protocol-semantic **Model Request Options**, and compatibility request body fields are separate Catalog domains. A shared ingestion adapter partitions legacy and models.dev AI-SDK-shaped options before routing.
 - A **Mid-Conversation System Message** lowers to the provider's native chronological instruction role when supported and to a wrapped chronological fallback otherwise.
 - When the effective aggregate instruction set changes, its **Mid-Conversation System Message** includes the complete current ordered set and supersedes the prior aggregate value; when no ambient instructions remain, the message states that previously loaded instructions no longer apply.
 - Ambient project instruction discovery honors `OPENCODE_DISABLE_PROJECT_CONFIG`; global instructions remain eligible.

packages/core/src/catalog.ts

@@ -3,6 +3,7 @@ export * as Catalog from "./catalog"
 import { Context, Effect, Layer, Option, Order, pipe, Schema, Array, Scope, Stream } from "effect"
 import { castDraft, enableMapSet, type Draft } from "immer"
 import { ModelV2 } from "./model"
+import { ModelRequest } from "./model-request"
 import { PluginV2 } from "./plugin"
 import { ProviderV2 } from "./provider"
 import { Location } from "./location"
@@ -106,14 +107,7 @@ export const layer = Layer.effect(
               ? { ...model.api, settings: { ...provider.api.settings, ...model.api.settings } }
               : model.api
       const request = {
-        headers: {
-          ...provider.request.headers,
-          ...model.request.headers,
-        },
-        body: {
-          ...provider.request.body,
-          ...model.request.body,
-        },
+        ...ModelRequest.merge({ ...provider.request, generation: {}, options: {} }, model.request),
         variant: model.request.variant,
       }
       return new ModelV2.Info({

packages/core/src/config/plugin/provider.ts

@@ -4,6 +4,7 @@ import { Effect } from "effect"
 import { Catalog } from "../../catalog"
 import { Config } from "../../config"
 import { ModelV2 } from "../../model"
+import { ModelRequest } from "../../model-request"
 import { PluginV2 } from "../../plugin"
 import { ProviderV2 } from "../../provider"
 
@@ -31,16 +32,19 @@ export const Plugin = PluginV2.define({
             provider.enabled = { via: "custom", data: {} }
             if (item.api !== undefined) provider.api = { ...item.api }
             if (item.request !== undefined) {
-              Object.assign(provider.request.headers, item.request.headers ?? {})
-              Object.assign(provider.request.body, item.request.body ?? {})
+              Object.assign(provider.request.headers, item.request.headers)
+              Object.assign(provider.request.body, item.request.body)
             }
           })
+          const providerApi = catalog.provider.get(providerID)?.provider.api
+          const providerPackage = providerApi?.type === "aisdk" ? providerApi.package : undefined
 
           for (const [id, config] of Object.entries(item.models ?? {})) {
             catalog.model.update(providerID, ModelV2.ID.make(id), (model) => {
               if (config.family !== undefined) model.family = config.family
               if (config.name !== undefined) model.name = config.name
               if (config.api !== undefined) model.api = { ...model.api, ...config.api }
+              const packageName = model.api.type === "aisdk" ? model.api.package : providerPackage
               if (config.capabilities !== undefined) {
                 model.capabilities = {
                   tools: config.capabilities.tools,
@@ -49,8 +53,10 @@ export const Plugin = PluginV2.define({
                 }
               }
               if (config.request !== undefined) {
-                Object.assign(model.request.headers, config.request.headers ?? {})
-                Object.assign(model.request.body, config.request.body ?? {})
+                ModelRequest.assign(model.request, {
+                  headers: config.request.headers,
+                  ...ModelRequest.normalizeAiSdkOptions(packageName, config.request.body ?? {}),
+                })
                 if (config.request.variant !== undefined) model.request.variant = config.request.variant
               }
               if (config.variants !== undefined) {
@@ -61,11 +67,15 @@ export const Plugin = PluginV2.define({
                       id: variant.id,
                       headers: {},
                       body: {},
+                      generation: {},
+                      options: {},
                     }
                     model.variants.push(existing)
                   }
-                  Object.assign(existing.headers, variant.headers ?? {})
-                  Object.assign(existing.body, variant.body ?? {})
+                  ModelRequest.assign(existing, {
+                    headers: variant.headers,
+                    ...ModelRequest.normalizeAiSdkOptions(packageName, variant.body ?? {}),
+                  })
                 }
               }
               if (config.cost !== undefined) {

packages/core/src/model-request.ts

@@ -0,0 +1,124 @@
+export * as ModelRequest from "./model-request"
+
+import { Effect, Schema } from "effect"
+
+export const Generation = Schema.Struct({
+  maxTokens: Schema.Number.pipe(Schema.optional),
+  temperature: Schema.Number.pipe(Schema.optional),
+  topP: Schema.Number.pipe(Schema.optional),
+  topK: Schema.Number.pipe(Schema.optional),
+  frequencyPenalty: Schema.Number.pipe(Schema.optional),
+  presencePenalty: Schema.Number.pipe(Schema.optional),
+  seed: Schema.Number.pipe(Schema.optional),
+  stop: Schema.String.pipe(Schema.Array, Schema.mutable, Schema.optional),
+})
+export type Generation = typeof Generation.Type
+
+export const Request = Schema.Struct({
+  headers: Schema.Record(Schema.String, Schema.String),
+  body: Schema.Record(Schema.String, Schema.Any),
+  generation: Generation.pipe(
+    Schema.optionalKey,
+    Schema.withConstructorDefault(Effect.succeed({})),
+    Schema.withDecodingDefaultKey(Effect.succeed({})),
+  ),
+  options: Schema.Record(Schema.String, Schema.Any).pipe(
+    Schema.optionalKey,
+    Schema.withConstructorDefault(Effect.succeed({})),
+    Schema.withDecodingDefaultKey(Effect.succeed({})),
+  ),
+})
+export type Request = typeof Request.Type
+
+interface MutableRequest {
+  headers: Record<string, string>
+  body: Record<string, unknown>
+  generation?: Generation
+  options?: Record<string, unknown>
+}
+
+const generationKeys = new Map<string, keyof Generation>([
+  ["maxOutputTokens", "maxTokens"],
+  ["maxTokens", "maxTokens"],
+  ["temperature", "temperature"],
+  ["topP", "topP"],
+  ["topK", "topK"],
+  ["frequencyPenalty", "frequencyPenalty"],
+  ["presencePenalty", "presencePenalty"],
+  ["seed", "seed"],
+  ["stopSequences", "stop"],
+  ["stop", "stop"],
+])
+
+interface Profile {
+  readonly namespace: string
+  readonly semantics: ReadonlyMap<string, string>
+}
+
+const profiles = new Map<string, Profile>([
+  [
+    "@ai-sdk/openai",
+    {
+      namespace: "openai",
+      semantics: new Map([
+        ["store", "store"],
+        ["promptCacheKey", "promptCacheKey"],
+        ["reasoningEffort", "reasoningEffort"],
+        ["reasoningSummary", "reasoningSummary"],
+        ["include", "include"],
+        ["textVerbosity", "textVerbosity"],
+        ["serviceTier", "serviceTier"],
+        ["service_tier", "serviceTier"],
+      ]),
+    },
+  ],
+  [
+    "@ai-sdk/openai-compatible",
+    {
+      namespace: "openai",
+      semantics: new Map([
+        ["store", "store"],
+        ["promptCacheKey", "promptCacheKey"],
+        ["reasoningEffort", "reasoningEffort"],
+        ["reasoning_effort", "reasoningEffort"],
+      ]),
+    },
+  ],
+  ["@ai-sdk/anthropic", { namespace: "anthropic", semantics: new Map([["thinking", "thinking"]]) }],
+])
+
+export const namespace = (packageName: string) => profiles.get(packageName)?.namespace
+
+export const merge = (base: Request, override: Partial<Request>) => ({
+  headers: { ...base.headers, ...override.headers },
+  body: { ...base.body, ...override.body },
+  generation: { ...base.generation, ...override.generation },
+  options: { ...base.options, ...override.options },
+})
+
+export const assign = (target: MutableRequest, override: Partial<Request>) => {
+  Object.assign(target.headers, override.headers)
+  Object.assign(target.body, override.body)
+  Object.assign((target.generation ??= {}), override.generation)
+  Object.assign((target.options ??= {}), override.options)
+}
+
+/** Partitions AI-SDK-shaped request options before they enter the Catalog. */
+export function normalizeAiSdkOptions(packageName: string | undefined, input: Readonly<Record<string, unknown>>) {
+  const generation: Record<string, number | ReadonlyArray<string>> = {}
+  const options: Record<string, unknown> = {}
+  const body: Record<string, unknown> = {}
+  const semantics = profiles.get(packageName ?? "")?.semantics
+
+  for (const [key, value] of Object.entries(input)) {
+    const generationKey = generationKeys.get(key)
+    if (generationKey === "stop" && Array.isArray(value) && value.every((item) => typeof item === "string"))
+      generation[generationKey] = value
+    else if (generationKey !== undefined && generationKey !== "stop" && typeof value === "number")
+      generation[generationKey] = value
+    else if (semantics?.has(key)) options[semantics.get(key)!] = value
+    else body[key] = value
+  }
+
+  return { generation, options, body }
+}

packages/core/src/model.ts

@@ -1,6 +1,7 @@
 import { DateTime, Schema } from "effect"
 import { DateTimeUtcFromMillis } from "effect/Schema"
 import { ProviderV2 } from "./provider"
+import { ModelRequest } from "./model-request"
 
 export const ID = Schema.String.pipe(Schema.brand("ModelV2.ID"))
 export type ID = typeof ID.Type
@@ -60,12 +61,12 @@ export class Info extends Schema.Class<Info>("ModelV2.Info")({
   api: Api,
   capabilities: Capabilities,
   request: Schema.Struct({
-    ...ProviderV2.Request.fields,
+    ...ModelRequest.Request.fields,
     variant: Schema.String.pipe(Schema.optional),
   }),
   variants: Schema.Struct({
     id: VariantID,
-    ...ProviderV2.Request.fields,
+    ...ModelRequest.Request.fields,
   }).pipe(Schema.Array),
   time: Schema.Struct({
     released: DateTimeUtcFromMillis,
@@ -97,6 +98,8 @@ export class Info extends Schema.Class<Info>("ModelV2.Info")({
       request: {
         headers: {},
         body: {},
+        generation: {},
+        options: {},
       },
       variants: [],
       time: {

packages/core/src/plugin/models-dev.ts

@@ -2,6 +2,7 @@ import { DateTime, Effect, Scope, Stream } from "effect"
 import { Catalog } from "../catalog"
 import { EventV2 } from "../event"
 import { ModelV2 } from "../model"
+import { ModelRequest } from "../model-request"
 import { ModelsDev } from "../models-dev"
 import { PluginV2 } from "../plugin"
 import { ProviderV2 } from "../provider"
@@ -38,12 +39,15 @@ function cost(input: ModelsDev.Model["cost"]) {
   ]
 }
 
-function variants(model: ModelsDev.Model) {
-  return Object.entries(model.experimental?.modes ?? {}).map(([id, item]) => ({
-    id: ModelV2.VariantID.make(id),
-    headers: { ...(item.provider?.headers ?? {}) },
-    body: { ...(item.provider?.body ?? {}) },
-  }))
+function variants(model: ModelsDev.Model, packageName?: string) {
+  return Object.entries(model.experimental?.modes ?? {}).map(([id, item]) => {
+    const request = ModelRequest.normalizeAiSdkOptions(packageName, item.provider?.body ?? {})
+    return {
+      id: ModelV2.VariantID.make(id),
+      headers: { ...(item.provider?.headers ?? {}) },
+      ...request,
+    }
+  })
 }
 
 export const ModelsDevPlugin = PluginV2.define({
@@ -98,7 +102,7 @@ export const ModelsDevPlugin = PluginV2.define({
                 input: [...(model.modalities?.input ?? [])],
                 output: [...(model.modalities?.output ?? [])],
               }
-              draft.variants = variants(model)
+              draft.variants = variants(model, model.provider?.npm ?? item.npm)
               draft.time.released = released(model.release_date)
               draft.cost = cost(model.cost)
               draft.status = model.status ?? "active"

packages/core/src/session/runner/model.ts

@@ -9,6 +9,7 @@ import { Context, Effect, Layer, Option, Schema } from "effect"
 import { produce } from "immer"
 import { Catalog } from "../../catalog"
 import { ModelV2 } from "../../model"
+import { ModelRequest } from "../../model-request"
 import { PluginBoot } from "../../plugin/boot"
 import { ProviderV2 } from "../../provider"
 import { SessionSchema } from "../schema"
@@ -50,24 +51,30 @@ const apiKey = (model: ModelV2.Info, provider?: ProviderV2.Info) => {
   return provider?.enabled !== false && provider?.enabled.via === "env" ? Auth.config(provider.enabled.name) : undefined
 }
 
-const withDefaults = (model: ModelV2.Info, route: AnyRoute) =>
-  route.with({
+const withDefaults = (model: ModelV2.Info, route: AnyRoute) => {
+  const options = model.request.options ?? {}
+  const namespace = model.api.type === "aisdk" ? ModelRequest.namespace(model.api.package) : undefined
+  const body = model.request.body
+  const httpBody = Object.hasOwn(body, "apiKey")
+    ? Object.fromEntries(Object.entries(body).filter(([key]) => key !== "apiKey"))
+    : body
+  return route.with({
     provider: model.providerID,
     endpoint: model.api.url === undefined ? undefined : { baseURL: model.api.url },
     headers: model.request.headers,
-    http: {
-      body: Object.fromEntries(Object.entries(model.request.body).filter(([key]) => key !== "apiKey")),
-    },
+    generation: model.request.generation,
+    providerOptions: namespace && Object.keys(options).length > 0 ? { [namespace]: options } : undefined,
+    http: { body: httpBody },
     limits: { context: model.limit.context, output: model.limit.output },
   })
+}
 
 const withVariant = (model: ModelV2.Info, variantID: ModelV2.VariantID | undefined) => {
   const id = variantID === "default" || variantID === undefined ? model.request.variant : variantID
   const variant = model.variants.find((item) => item.id === id)
   if (!variant) return model
   return produce(model, (draft) => {
-    Object.assign(draft.request.headers, variant.headers)
-    Object.assign(draft.request.body, variant.body)
+    ModelRequest.assign(draft.request, variant)
   })
 }
 

packages/core/src/v1/config/migrate.ts

@@ -6,6 +6,7 @@ import { ConfigMCPV1 } from "./mcp"
 import { ConfigPermissionV1 } from "./permission"
 import { ConfigProviderV1 } from "./provider"
 import { ConfigProviderOptionsV1 } from "./provider-options"
+import { ModelRequest } from "../../model-request"
 
 const keys = new Set([
   "logLevel",
@@ -183,6 +184,13 @@ function migrateProvider(info: ConfigProviderV1.Info) {
 }
 
 function migrateModel(info: typeof ConfigProviderV1.Model.Type, packageName?: string) {
+  const packageID = info.provider?.npm ?? packageName
+  const lowerer = ConfigProviderOptionsV1.get(packageID)
+  const ingest = (options: Readonly<Record<string, unknown>>) => {
+    const request = ModelRequest.normalizeAiSdkOptions(packageID, options)
+    return { ...lowerer.request(request.body), ...request.generation, ...request.options }
+  }
+  const request = info.options && ingest(info.options)
   const costs = info.cost && [
     {
       input: info.cost.input,
@@ -204,7 +212,6 @@ function migrateModel(info: typeof ConfigProviderV1.Model.Type, packageName?: st
     info.tool_call !== undefined || info.modalities?.input !== undefined || info.modalities?.output !== undefined
       ? { tools: info.tool_call ?? false, input: info.modalities?.input ?? [], output: info.modalities?.output ?? [] }
       : undefined
-  const lowerer = ConfigProviderOptionsV1.get(info.provider?.npm ?? packageName)
   return {
     family: info.family,
     name: info.name,
@@ -220,12 +227,16 @@ function migrateModel(info: typeof ConfigProviderV1.Model.Type, packageName?: st
         ? undefined
         : { id: info.id },
     capabilities,
-    request: (info.headers || info.options) && {
+    request: (info.headers || request) && {
       headers: info.headers,
-      body: info.options && lowerer.request(info.options),
+      body: request,
     },
     variants:
-      info.variants && Object.entries(info.variants).map(([id, options]) => ({ id, body: lowerer.request(options) })),
+      info.variants &&
+      Object.entries(info.variants).map(([id, options]) => ({
+        id,
+        body: ingest(options),
+      })),
     cost: costs,
     disabled: info.status === "deprecated" ? true : undefined,
     limit: info.limit && {