@opencode-ai/ai 0.0.0-next-16997 → 0.0.0-next-16998

package/README.md

@@ -368,11 +368,12 @@ Other provider exports listed above remain direct facades until they explicitly
 
 ## Provider options & HTTP overlays
 
-Three escape hatches in order of stability:
+Request options in order of stability:
 
 1. **`generation`** — portable knobs (`maxTokens`, `temperature`, `topP`, `topK`, penalties, seed, stop).
-2. **`providerOptions: { <provider>: {...} }`** — typed-at-the-facade provider-specific knobs (OpenAI `promptCacheKey`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
-3. **`http: { body, headers, query }`** — last-resort serializable overlays merged into the final HTTP request. Reach for this only when a stable typed path doesn't yet exist.
+2. **`promptCacheKey`** — stable cache affinity lowered by every protocol that supports it.
+3. **`providerOptions: { <provider>: {...} }`** — typed-at-the-facade provider-specific knobs (OpenAI `store`, Anthropic `thinking`, Gemini `thinkingConfig`, OpenRouter routing).
+4. **`http: { body, headers, query }`** — last-resort serializable overlays merged into the final HTTP request. Reach for this only when a stable typed path doesn't yet exist.
 
 Route/provider defaults are overridden by request-level values for each axis.
 

package/dist/protocols/open-responses.js

@@ -392,7 +392,7 @@ const lowerOptions = (request) => {
     return {
         ...(options.instructions ? { instructions: options.instructions } : {}),
         ...(options.store !== undefined ? { store: options.store } : {}),
-        ...(options.promptCacheKey ? { prompt_cache_key: options.promptCacheKey } : {}),
+        ...(request.promptCacheKey ? { prompt_cache_key: request.promptCacheKey } : {}),
         ...(options.include ? { include: options.include } : {}),
         ...(options.reasoningEffort || options.reasoningSummary
             ? { reasoning: { effort: options.reasoningEffort, summary: options.reasoningSummary } }

package/dist/protocols/utils/open-responses-options.d.ts

@@ -11,7 +11,6 @@ export declare const ServiceTierSchema: Schema.Literals<readonly ["auto", "defau
 export interface Resolved {
     readonly instructions?: string;
     readonly store?: boolean;
-    readonly promptCacheKey?: string;
     readonly reasoningEffort?: string;
     readonly reasoningSummary?: "auto" | "concise" | "detailed";
     readonly include?: ReadonlyArray<ResponseIncludable>;

package/dist/protocols/utils/open-responses-options.js

@@ -29,7 +29,6 @@ export const resolve = (request) => {
     return {
         instructions: typeof input?.instructions === "string" ? input.instructions : undefined,
         store: typeof input?.store === "boolean" ? input.store : undefined,
-        promptCacheKey: typeof input?.promptCacheKey === "string" ? input.promptCacheKey : undefined,
         reasoningEffort: typeof input?.reasoningEffort === "string" ? input.reasoningEffort : undefined,
         reasoningSummary: reasoningSummary === "auto" || reasoningSummary === "concise" || reasoningSummary === "detailed"
             ? reasoningSummary

package/dist/providers/open-responses-options.d.ts

@@ -4,7 +4,6 @@ export interface OpenResponsesOptionsInput {
     readonly [key: string]: unknown;
     readonly instructions?: string;
     readonly store?: boolean;
-    readonly promptCacheKey?: string;
     readonly reasoningEffort?: ReasoningEffort;
     readonly reasoningSummary?: "auto" | "concise" | "detailed";
     readonly include?: ReadonlyArray<ResponseIncludable>;

package/dist/providers/openai-options.js

@@ -3,7 +3,6 @@ const definedEntries = (input) => Object.entries(input).filter((entry) => entry[
 const openAIProviderOptions = (options) => {
     const openai = Object.fromEntries(definedEntries({
         store: options?.store,
-        promptCacheKey: options?.promptCacheKey,
         reasoningEffort: options?.reasoningEffort,
         reasoningSummary: options?.reasoningSummary,
         include: options?.include,

package/dist/providers/openrouter.d.ts

@@ -59,7 +59,6 @@ export interface OpenRouterOptions {
     }>;
     readonly models?: ReadonlyArray<string>;
     readonly plugins?: ReadonlyArray<OpenRouterPlugin>;
-    readonly promptCacheKey?: string;
     readonly provider?: OpenRouterProviderRouting;
     readonly reasoning?: Readonly<{
         enabled?: boolean;

package/dist/providers/openrouter.js

@@ -43,6 +43,7 @@ export const protocol = Protocol.make({
                 ...body,
                 messages,
                 ...bodyOptions(request.providerOptions?.openrouter),
+                ...(request.promptCacheKey ? { prompt_cache_key: request.promptCacheKey } : {}),
             };
         })),
     },
@@ -79,7 +80,6 @@ const bodyOptions = (input) => {
         ...(isRecord(debug) ? { debug } : {}),
         ...(typeof user === "string" ? { user } : {}),
         ...(isRecord(reasoning) ? { reasoning } : {}),
-        ...(typeof promptCacheKey === "string" ? { prompt_cache_key: promptCacheKey } : {}),
     };
 };
 export const route = Route.make({

package/dist/schema/messages.d.ts

@@ -368,6 +368,7 @@ declare const LLMRequest_base: Schema.Class<LLMRequest, Schema.Struct<{
         }>]>>;
         readonly ttlSeconds: Schema.optional<Schema.Number>;
     }>]>>;
+    readonly promptCacheKey: Schema.optional<Schema.String>;
     readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>, {}>;
 export declare class LLMRequest extends LLMRequest_base {

package/dist/schema/messages.js

@@ -211,6 +211,8 @@ export class LLMRequest extends Schema.Class("LLM.Request")({
     providerOptions: Schema.optional(ProviderOptions),
     http: Schema.optional(HttpOptions),
     cache: Schema.optional(CachePolicy),
+    // Stable cache affinity for protocols that support provider-managed prompt caching.
+    promptCacheKey: Schema.optional(Schema.String),
     metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
 }) {
 }
@@ -226,6 +228,7 @@ export class LLMRequest extends Schema.Class("LLM.Request")({
         providerOptions: request.providerOptions,
         http: request.http,
         cache: request.cache,
+        promptCacheKey: request.promptCacheKey,
         metadata: request.metadata,
     });
     LLMRequest.update = (request, patch) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "0.0.0-next-16997",
+  "version": "0.0.0-next-16998",
   "name": "@opencode-ai/ai",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
   "devDependencies": {
     "@clack/prompts": "1.0.0-alpha.1",
     "@effect/platform-node": "4.0.0-beta.101",
-    "@opencode-ai/http-recorder": "0.0.0-next-16997",
+    "@opencode-ai/http-recorder": "0.0.0-next-16998",
     "@tsconfig/bun": "1.0.9",
     "@types/bun": "1.3.13",
     "@typescript/native-preview": "7.0.0-dev.20251207.1",
@@ -39,7 +39,7 @@
   "dependencies": {
     "@smithy/eventstream-codec": "4.2.14",
     "@smithy/util-utf8": "4.2.2",
-    "@opencode-ai/schema": "0.0.0-next-16997",
+    "@opencode-ai/schema": "0.0.0-next-16998",
     "aws4fetch": "1.0.20",
     "effect": "4.0.0-beta.101",
     "google-auth-library": "10.5.0"