aisubs 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.6 - 2026-09-15
+
+- Preserve provider cache controls and cache usage across OpenAI-compatible,
+  Anthropic, Responses, and subscription transports.
+- Keep ChatGPT cache routing state scoped to account, session, and turn.
+- Normalize cache reads/writes and reasoning usage without losing native fields.
+
 ## 0.3.5 - 2026-09-14
 
 - Move ChatGPT Responses instructions into the developer input prefix so

package/dist/compatibility.js

@@ -29,13 +29,22 @@ function requiredModel(raw) {
         throw new CompatibilityError("A non-empty model is required");
     return model;
 }
+function cacheControl(value) {
+    if (!isRecord(value) || value.cache_control == null)
+        return {};
+    const control = record(value.cache_control, "cache_control must be an object");
+    if (control.type !== "ephemeral" ||
+        (control.ttl != null && control.ttl !== "5m" && control.ttl !== "1h"))
+        throw new CompatibilityError("Unsupported cache_control type or TTL", "unsupported_feature");
+    return { cache_control: { type: "ephemeral", ...(control.ttl ? { ttl: control.ttl } : {}) } };
+}
 function text(value) {
     if (typeof value === "string")
         return { type: "text", text: value };
     if (!isRecord(value))
         return null;
     const content = stringValue(value.text);
-    return content == null ? null : { type: "text", text: content };
+    return content == null ? null : { type: "text", text: content, ...cacheControl(value) };
 }
 function imageUrl(value) {
     if (typeof value === "string")
@@ -61,14 +70,14 @@ function openAiParts(value) {
             const url = imageUrl(part.image_url) ?? stringValue(part.image_url) ?? stringValue(part.file_id);
             if (!url)
                 throw new CompatibilityError("Image content requires image_url or file_id");
-            return { type: "image", url, detail: stringValue(part.detail) };
+            return { type: "image", url, detail: stringValue(part.detail), ...cacheControl(part) };
         }
         if (type === "input_audio") {
             const audio = record(part.input_audio, "input_audio requires audio data");
             const data = stringValue(audio.data);
             if (!data)
                 throw new CompatibilityError("input_audio requires audio data");
-            return { type: "audio", data, format: stringValue(audio.format) };
+            return { type: "audio", data, format: stringValue(audio.format), ...cacheControl(part) };
         }
         if (type === "file" || type === "input_file") {
             return {
@@ -76,6 +85,7 @@ function openAiParts(value) {
                 fileId: stringValue(part.file_id),
                 data: stringValue(part.file_data),
                 filename: stringValue(part.filename),
+                ...cacheControl(part),
             };
         }
         if (type === "refusal")
@@ -116,6 +126,7 @@ function chatTools(value) {
             description: stringValue(fn.description),
             parameters: fn.parameters,
             strict: typeof fn.strict === "boolean" ? fn.strict : undefined,
+            ...cacheControl(tool),
         };
     });
 }
@@ -134,6 +145,7 @@ function parseChat(body) {
             content: openAiParts(message.content),
             toolCallId: stringValue(message.tool_call_id),
             toolCalls: chatToolCalls(message.tool_calls),
+            ...cacheControl(message),
         };
     });
     return {
@@ -151,6 +163,7 @@ function parseChat(body) {
         metadata: raw.metadata,
         user: stringValue(raw.user),
         promptCacheKey: stringValue(raw.prompt_cache_key),
+        cacheControl: cacheControl(raw).cache_control,
     };
 }
 function responseTools(value) {
@@ -257,15 +270,16 @@ function anthropicParts(value) {
     for (const item of value) {
         const part = record(item, "Anthropic content blocks must be objects");
         if (part.type === "text")
-            content.push({ type: "text", text: stringValue(part.text) ?? "" });
+            content.push({ type: "text", text: stringValue(part.text) ?? "", ...cacheControl(part) });
         else if (part.type === "image") {
             const source = record(part.source, "Anthropic image requires source");
             if (source.type === "url")
-                content.push({ type: "image", url: stringValue(source.url) ?? "" });
+                content.push({ type: "image", url: stringValue(source.url) ?? "", ...cacheControl(part) });
             else
                 content.push({
                     type: "image",
                     url: `data:${stringValue(source.media_type) ?? "image/png"};base64,${stringValue(source.data) ?? ""}`,
+                    ...cacheControl(part),
                 });
         }
         else if (part.type === "tool_use") {
@@ -273,6 +287,7 @@ function anthropicParts(value) {
                 id: stringValue(part.id) ?? `call_${crypto.randomUUID()}`,
                 name: stringValue(part.name) ?? "function",
                 arguments: JSON.stringify(part.input ?? {}),
+                ...cacheControl(part),
             });
         }
         else if (part.type !== "thinking" && part.type !== "redacted_thinking") {
@@ -301,6 +316,7 @@ function parseAnthropic(body) {
                         role: "tool",
                         toolCallId: stringValue(part.tool_use_id),
                         content: anthropicParts(part.content).content,
+                        ...cacheControl(part),
                     });
                 }
                 else
@@ -319,7 +335,12 @@ function parseAnthropic(body) {
             const name = stringValue(tool.name);
             if (!name)
                 throw new CompatibilityError("Tool requires a name");
-            return { name, description: stringValue(tool.description), parameters: tool.input_schema };
+            return {
+                name,
+                description: stringValue(tool.description),
+                parameters: tool.input_schema,
+                ...cacheControl(tool),
+            };
         })
         : undefined;
     return {
@@ -333,6 +354,7 @@ function parseAnthropic(body) {
         topP: numberValue(raw.top_p),
         stop: raw.stop_sequences,
         metadata: raw.metadata,
+        cacheControl: cacheControl(raw).cache_control,
     };
 }
 function parseGoogle(body, model, stream = false) {
@@ -420,15 +442,16 @@ function dataUri(url) {
     return match?.[1] && match[2] ? { mediaType: match[1], data: match[2] } : null;
 }
 function chatContent(parts) {
-    if (parts.every((part) => part.type === "text"))
+    if (parts.every((part) => part.type === "text" && !part.cache_control))
         return parts.map((part) => (part.type === "text" ? part.text : "")).join("");
     return parts.map((part) => {
         if (part.type === "text")
-            return { type: "text", text: part.text };
+            return { type: "text", text: part.text, ...cacheControl(part) };
         if (part.type === "image")
             return {
                 type: "image_url",
                 image_url: { url: part.url, ...(part.detail ? { detail: part.detail } : {}) },
+                ...cacheControl(part),
             };
         if (part.type === "audio")
             return {
@@ -447,6 +470,7 @@ function toChat(request) {
     const messages = request.messages.map((message) => ({
         role: message.role,
         content: chatContent(message.content),
+        ...cacheControl(message),
         ...(message.toolCallId ? { tool_call_id: message.toolCallId } : {}),
         ...(message.toolCalls
             ? {
@@ -463,7 +487,13 @@ function toChat(request) {
         messages,
         stream: false,
         ...(request.tools
-            ? { tools: request.tools.map((tool) => ({ type: "function", function: tool })) }
+            ? {
+                tools: request.tools.map(({ cache_control, ...tool }) => ({
+                    type: "function",
+                    function: tool,
+                    ...(cache_control ? { cache_control } : {}),
+                })),
+            }
             : {}),
         ...(request.toolChoice != null ? { tool_choice: request.toolChoice } : {}),
         ...(request.maxTokens != null ? { max_completion_tokens: request.maxTokens } : {}),
@@ -550,7 +580,12 @@ function toResponses(request) {
         stream: false,
         store: false,
         ...(request.tools
-            ? { tools: request.tools.map((tool) => ({ type: "function", ...tool })) }
+            ? {
+                tools: request.tools.map(({ cache_control: _cacheControl, ...tool }) => ({
+                    type: "function",
+                    ...tool,
+                })),
+            }
             : {}),
         ...(toolChoice != null ? { tool_choice: toolChoice } : {}),
         ...(request.maxTokens != null ? { max_output_tokens: request.maxTokens } : {}),
@@ -566,12 +601,16 @@ function toResponses(request) {
 function anthropicContent(message) {
     const parts = message.content.map((part) => {
         if (part.type === "text")
-            return { type: "text", text: part.text };
+            return { type: "text", text: part.text, ...cacheControl(part) };
         if (part.type === "image") {
             const data = dataUri(part.url);
             return data
-                ? { type: "image", source: { type: "base64", media_type: data.mediaType, data: data.data } }
-                : { type: "image", source: { type: "url", url: part.url } };
+                ? {
+                    type: "image",
+                    source: { type: "base64", media_type: data.mediaType, data: data.data },
+                    ...cacheControl(part),
+                }
+                : { type: "image", source: { type: "url", url: part.url }, ...cacheControl(part) };
         }
         if (part.type === "file")
             return {
@@ -580,6 +619,7 @@ function anthropicContent(message) {
                     ? { type: "file", file_id: part.fileId }
                     : { type: "base64", media_type: "application/octet-stream", data: part.data ?? "" },
                 ...(part.filename ? { title: part.filename } : {}),
+                ...cacheControl(part),
             };
         throw new CompatibilityError("Anthropic Messages does not support OpenAI input_audio", "unsupported_feature");
     });
@@ -589,7 +629,10 @@ function anthropicContent(message) {
             id: call.id,
             name: call.name,
             input: JSON.parse(call.arguments || "{}"),
+            ...cacheControl(call),
         });
+    if (message.role !== "tool" && message.cache_control && parts.length)
+        Object.assign(parts[parts.length - 1], cacheControl(message));
     return parts;
 }
 function toAnthropic(request) {
@@ -606,6 +649,7 @@ function toAnthropic(request) {
                     type: "tool_result",
                     tool_use_id: message.toolCallId,
                     content: anthropicContent(message),
+                    ...cacheControl(message),
                 },
             ],
         }
@@ -621,12 +665,14 @@ function toAnthropic(request) {
         max_tokens: request.maxTokens ?? 4096,
         stream: false,
         ...(system.length ? { system } : {}),
+        ...(request.cacheControl ? { cache_control: request.cacheControl } : {}),
         ...(request.tools
             ? {
                 tools: request.tools.map((tool) => ({
                     name: tool.name,
                     description: tool.description,
                     input_schema: tool.parameters ?? { type: "object", properties: {} },
+                    ...cacheControl(tool),
                 })),
             }
             : {}),
@@ -740,7 +786,10 @@ function parseChatResult(raw, model) {
         finishReason: finish === "length" || finish === "tool_calls" || finish === "content_filter"
             ? finish
             : "stop",
-        usage: usage(numberValue(details?.prompt_tokens), numberValue(details?.completion_tokens), numberValue(promptDetails?.cached_tokens), numberValue(completionDetails?.reasoning_tokens), numberValue(promptDetails?.cache_write_tokens)),
+        usage: usage(numberValue(details?.prompt_tokens), numberValue(details?.completion_tokens), numberValue(details?.cached_tokens) ??
+            numberValue(details?.prompt_cache_hit_tokens) ??
+            numberValue(promptDetails?.cached_tokens), numberValue(completionDetails?.reasoning_tokens), numberValue(promptDetails?.cache_write_tokens) ??
+            numberValue(promptDetails?.cache_creation_input_tokens)),
     };
 }
 function parseResponsesResult(raw, model) {

package/dist/providers/chatgpt.js

@@ -109,25 +109,12 @@ async function normalizeChatGptRequest(request) {
     if (!isRecord(raw))
         return request;
     const body = { ...raw };
-    // The Codex endpoint places the implicit cache boundary after input
-    // messages. Move stable top-level instructions into that prefix so they
-    // participate in prompt caching for subscription requests.
-    if (typeof body.instructions === "string" && body.instructions.length > 0) {
-        const input = Array.isArray(body.input)
-            ? body.input
-            : typeof body.input === "string"
-                ? [{ type: "message", role: "user", content: body.input }]
-                : [];
-        body.input = [
-            {
-                type: "message",
-                role: "developer",
-                content: [{ type: "input_text", text: body.instructions }],
-            },
-            ...input,
-        ];
-        delete body.instructions;
-    }
+    const headers = new Headers(request.headers);
+    const sessionId = headers.get("session-id") ?? headers.get("session_id") ?? stringValue(body.prompt_cache_key);
+    if (sessionId)
+        headers.set("session-id", sessionId);
+    // Preserve instruction placement and message boundaries. The native Codex
+    // client sends top-level instructions too; moving them does not enable caching.
     delete body.prompt_cache_options;
     delete body.prompt_cache_retention;
     const stripBreakpoints = (value) => Array.isArray(value)
@@ -135,18 +122,42 @@ async function normalizeChatGptRequest(request) {
             ? Object.fromEntries(Object.entries(item).filter(([key]) => key !== "prompt_cache_breakpoint"))
             : item)
         : value;
-    body.input = stripBreakpoints(body.input);
+    const inputWithoutBreakpoints = stripBreakpoints(body.input);
+    body.input = Array.isArray(inputWithoutBreakpoints)
+        ? inputWithoutBreakpoints.map((item) => isRecord(item)
+            ? {
+                ...item,
+                ...(Array.isArray(item.content) ? { content: stripBreakpoints(item.content) } : {}),
+                ...(Array.isArray(item.output) ? { output: stripBreakpoints(item.output) } : {}),
+            }
+            : item)
+        : inputWithoutBreakpoints;
     body.tools = stripBreakpoints(body.tools);
     return new Request(request, {
         method: request.method,
         body: JSON.stringify(body),
-        headers: { ...Object.fromEntries(request.headers), "content-type": "application/json" },
+        headers: { ...Object.fromEntries(headers), "content-type": "application/json" },
     });
 }
 export function chatGptProvider(options = {}) {
     const clientId = options.clientId ?? DEFAULT_CLIENT_ID;
     const compatibilityVersion = options.compatibilityVersion ?? "0.154.0";
     const fetcher = options.fetch ?? globalThis.fetch;
+    // Routing tokens belong to one account/session/turn, never to the whole provider.
+    const turnStates = new Map();
+    const turnKey = (request, accountId) => {
+        const sessionId = request.headers.get("session-id");
+        try {
+            const metadata = JSON.parse(request.headers.get("x-codex-turn-metadata") ?? "null");
+            const turnId = isRecord(metadata) ? stringValue(metadata.turn_id) : undefined;
+            return accountId && sessionId && turnId
+                ? JSON.stringify([accountId, sessionId, turnId])
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
     async function startDeviceLogin(signal) {
         const response = await fetcher(DEVICE_CODE_URL, {
             method: "POST",
@@ -401,12 +412,32 @@ export function chatGptProvider(options = {}) {
             const accountId = credential.account?.id;
             if (!accountId)
                 throw new Error("ChatGPT account id is missing");
+            const key = turnKey(request, accountId);
+            const state = key ? turnStates.get(key) : undefined;
             return bearerRequest(request, credential, {
                 "chatgpt-account-id": accountId,
                 originator: "aisubs",
                 "user-agent": `aisubs/${compatibilityVersion}`,
+                ...(state && state.expiresAt > Date.now() && !request.headers.has("x-codex-turn-state")
+                    ? { "x-codex-turn-state": state.token }
+                    : {}),
             });
         },
+        normalizeResponse(request, response) {
+            const key = turnKey(request, request.headers.get("chatgpt-account-id") ?? undefined);
+            const token = response.headers.get("x-codex-turn-state");
+            if (response.ok && key && token) {
+                for (const [entryKey, entry] of turnStates)
+                    if (entry.expiresAt <= Date.now())
+                        turnStates.delete(entryKey);
+                if (!turnStates.has(key)) {
+                    if (turnStates.size >= 128)
+                        turnStates.delete(turnStates.keys().next().value);
+                    turnStates.set(key, { token, expiresAt: Date.now() + 30 * 60_000 });
+                }
+            }
+            return response;
+        },
         async getUsage({ fetch, signal }) {
             const response = await fetch(USAGE_URL, { headers: { accept: "application/json" }, signal });
             const raw = await responseJson(response, "ChatGPT usage");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aisubs",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Connect AI provider accounts and use those subscriptions from any local tool or as api.",
   "keywords": [
     "ai",