@caeliq/llms 1.0.59 → 1.0.61

package/dist/utils/openai.responses.util.d.ts

@@ -11,19 +11,167 @@ export declare function mapCallId(map: ResponsesCallIdMap, id: unknown, directio
  * Client Responses wire → Unified (Chat Completions shape).
  * Supports the Responses MVP subset; rejects CCR-unsupported stateful fields.
  */
-export declare function responsesRequestToUnified(body: any, callIdMap?: ResponsesCallIdMap): UnifiedChatRequest;
+export declare function responsesRequestToUnified(body: any, callIdMap?: ResponsesCallIdMap, customToolNames?: Set<string>): UnifiedChatRequest;
+export declare function isResponsesReasoningItemId(value: unknown): value is string;
+/**
+ * Ciphertext Codex/OpenAI will verify. Item ids and Anthropic/Gemini
+ * signatures are not encrypted_content — replaying them 400s with
+ * `invalid_encrypted_content`.
+ */
+export declare function responsesEncryptedContentFrom(value: unknown): string | undefined;
+export interface UnifiedAssistantThinking {
+    content: string;
+    signature?: string;
+    encrypted_content?: string;
+    id?: string;
+}
+/** Anthropic/Gemini thinking.signature — never a Responses item id. */
+export declare function anthropicThinkingSignatureFrom(thinking: {
+    signature?: string;
+} | undefined): string | undefined;
+/** Responses `reasoning` item → Unified assistant.thinking. */
+export declare function thinkingFromResponsesReasoningItem(item: any): UnifiedAssistantThinking | undefined;
+/**
+ * Record streamed reasoning summary text for one item. Late handlers
+ * (`output_item.done`, `response.completed`) consult this map so they can
+ * emit ciphertext / id without re-sending content — Unified
+ * `delta.thinking.content` is additive in every downstream consumer.
+ */
+export declare function recordReasoningSummaryDelta(deliveredContentByItemId: Map<string, string>, itemId: unknown, delta: unknown): void;
+/**
+ * Late Responses reasoning handlers exist to rescue `encrypted_content` /
+ * item id after summary deltas have already streamed the text. If this
+ * item's content was already delivered on the current stream, return
+ * replay metadata only. A terminal-only reasoning item (no summary
+ * deltas) still delivers content exactly once.
+ */
+export declare function thinkingForLateReasoningItem(item: any, deliveredContentByItemId: Map<string, string>): UnifiedAssistantThinking | undefined;
+/**
+ * Inverse of the inbound `text.format` → Chat Completions `response_format`
+ * mapping in `responsesRequestToUnified`. Shared by Codex and generic
+ * Responses outbound so the two reconstruct sites cannot drift.
+ */
+export declare function responsesTextFormatFromResponseFormat(responseFormat: any): {
+    type: string;
+    name?: string;
+    schema?: any;
+    strict?: boolean;
+} | undefined;
+/** Unified assistant.thinking → Responses `reasoning` input/output item. */
+export declare function thinkingFromUnifiedAssistant(message: any): UnifiedAssistantThinking | undefined;
+/**
+ * Fixed assistant-turn order for every protocol:
+ * thinking → text → images → tool calls.
+ * Reordering here keeps cache prefixes stable across Anthropic, Chat,
+ * Responses, Gemini, and Mistral.
+ */
+export interface CanonicalAssistantTurn {
+    thinking?: UnifiedAssistantThinking;
+    texts: Array<{
+        text: string;
+        cache_control?: any;
+    }>;
+    images: any[];
+    toolCalls: any[];
+}
+export declare function canonicalAssistantTurn(message: any): CanonicalAssistantTurn;
+export declare function assistantTurnHasText(turn: CanonicalAssistantTurn): boolean;
+export declare function responsesReasoningItemFromThinking(thinking: {
+    content?: string;
+    signature?: string;
+    encrypted_content?: string;
+    id?: string;
+} | undefined, id?: string): any | null;
+/** Synthetic argument key used to carry a `custom` tool's freeform text
+ * through the Unified/Chat Completions function-call shape. */
+export declare const CUSTOM_TOOL_INPUT_KEY = "input";
+/**
+ * Codex's apply_patch/apply_update grammar accepts only the exact markers
+ * `*** Begin Patch` and `*** End Patch` (no trailing asterisk triplet) as the
+ * first/last patch lines — anything else is rejected with "The first line of
+ * the patch must be '*** Begin Patch'". Models not trained on that grammar
+ * (e.g. Grok reaches for Claude's trailing-asterisk variant) emit
+ * `*** Begin Patch ***` / `*** End Patch ***`. Normalize those to the Codex
+ * form on the client-facing emission, scoped by the marker token itself so a
+ * rewrite can only ever hit an apply_patch-style payload regardless of the
+ * declared tool name.
+ */
+export declare function normalizeCodexPatchMarkers(text: string): string;
+/**
+ * Codex's `exec` tool runs raw JavaScript in a V8 isolate; a model that was
+ * never trained on that convention (Grok) sometimes fills the freeform input
+ * with a JSON shell-envelope instead — e.g. `{"cmd": "ls -la /tmp"}`. That is
+ * not valid JS (`{"cmd":…}` parses as a block with a string label →
+ * `SyntaxError: Unexpected token ':'`), so the shell call fails and the model
+ * wastes a turn retrying as `await tools.exec_command({cmd: …})`.
+ * Rewrite the envelope into exactly that retry shape on the client-facing
+ * emission. Scoped by the tool name and the whole-input-is-a-shell-object
+ * shape so a freeform tool that legitimately takes a JSON blob is never
+ * touched. Grok also alternates the key between `cmd` and `command`, and
+ * `exec_command` only accepts `cmd`, so normalize either to `cmd`.
+ */
+export declare function normalizeExecCommandEnvelope(name: string | undefined, text: string): string;
+/**
+ * A model that reaches for the patch tool through a shell hereditary habit
+ * wraps the patch in a heredoc instead of JS:
+ *   apply_patch << 'PATCH'\n*** Begin Patch … *** End Patch\nPATCH
+ * That is a shell command, not the raw JS `exec` runs, so it fails with a
+ * syntax error and the model wastes a turn retrying as
+ * `await tools.apply_patch(…)`. Normalize the heredoc invocation into the JS
+ * call form. Whole-value heredoc match only; anything else passes through.
+ */
+export declare function normalizeExecApplyPatchHeredoc(name: string | undefined, text: string): string;
+/**
+ * `exec` may cross the wire as a plain function tool (arguments stay the JSON
+ * wrapper `{"input":"…"}`) rather than a custom tool (whose freeform input was
+ * unwrapped already). The envelope/heredoc normalizers above operate on the
+ * unwrapped inner text, so when only the wrapper is available, descend into it
+ * and normalize its inner `input` value with the same rules.
+ */
+export declare function normalizeExecFunctionArguments(name: string | undefined, rawArguments: string, options?: CodexIsolateConventionsOptions): string;
+/** Undo the CUSTOM_TOOL_INPUT_KEY wrapping applied in normalizeResponsesTools.
+ * Falls back to the raw text so a malformed/empty call still round-trips
+ * instead of vanishing. Also strips a whole-value shell heredoc wrapper
+ * (see stripHeredocWrapper). That strip is intentional on both paths this
+ * helper serves: client emission (so the Responses client sees clean
+ * freeform text) and CodexTransformer history replay (so the backend is
+ * not re-fed a wrapper the client never kept). Replay is therefore
+ * normalized, not byte-faithful to the model's original heredoc. */
+export declare function unwrapCustomToolInput(rawArguments: string): string;
+/**
+ * Codex V8 isolate calling conventions (`await tools.exec_command` /
+ * `await tools.apply_patch`). Default on: CCR's `/v1/responses` inbound
+ * is the Codex CLI path, and Grok-via-Chat recovery depends on it.
+ * Pass `false` for a generic Responses destination whose `exec` tool
+ * legitimately accepts `{"cmd": …}` JSON.
+ */
+export interface CodexIsolateConventionsOptions {
+    codexIsolateConventions?: boolean;
+}
+/** Client-facing custom-tool input: unwrap the Unified JSON wrapper, then
+ * apply the exec/patch normalizers in one place so stream finalize, the
+ * completed skeleton, and the non-stream JSON path cannot drift. */
+export declare function normalizeClientCustomToolInput(name: string | undefined, rawArguments: string, options?: CodexIsolateConventionsOptions): string;
 /** Unified Chat JSON → Responses API non-stream response. */
 export declare function unifiedResponseToResponses(chat: any, options?: {
     originalModel?: string;
     callIdMap?: ResponsesCallIdMap;
+    customToolNames?: Set<string>;
+    codexIsolateConventions?: boolean;
 }): any;
 export interface ResponsesStreamState {
     responseId: string;
     model?: string;
     textItemId: string;
     textStarted: boolean;
+    textClosed: boolean;
     textOutputIndex?: number;
     textContent: string;
+    closedTextItems: Array<{
+        id: string;
+        outputIndex: number;
+        content: string;
+    }>;
     toolCalls: Map<number, {
         id: string;
         name: string;
@@ -31,6 +179,7 @@ export interface ResponsesStreamState {
         added: boolean;
         outputIndex: number;
         emittedArgumentsLength: number;
+        isCustom: boolean;
     }>;
     nextOutputIndex: number;
     finished: boolean;
@@ -39,10 +188,17 @@ export interface ResponsesStreamState {
     finishReasonSeen: boolean;
     usage?: any;
     callIdMap: ResponsesCallIdMap;
+    customToolNames: Set<string>;
+    thinkingContent: string;
+    thinkingEncryptedContent?: string;
+    thinkingId?: string;
+    codexIsolateConventions: boolean;
 }
 export declare function createResponsesStreamState(options?: {
     model?: string;
     callIdMap?: ResponsesCallIdMap;
+    customToolNames?: Set<string>;
+    codexIsolateConventions?: boolean;
 }): ResponsesStreamState;
 /**
  * Convert one Unified Chat Completions chunk into zero or more Responses

package/dist/utils/reasoning-effort.d.ts

@@ -0,0 +1,13 @@
+import type { ThinkLevel, UnifiedChatRequest } from "../types/llm";
+type UnifiedReasoning = UnifiedChatRequest["reasoning"];
+/** Normalize effort tokens at the protocol boundary without rejecting extensions. */
+export declare function normalizeReasoningEffort(value: unknown): ThinkLevel | undefined;
+/** `none` and an explicit enabled:false are the canonical off signals. */
+export declare function isReasoningDisabled(reasoning: UnifiedReasoning | undefined, thinking?: UnifiedChatRequest["thinking"]): boolean;
+/** Build the canonical reasoning state used by every inbound protocol. */
+export declare function canonicalReasoning(effortValue: unknown, enabledWhenEffortAbsent?: boolean): UnifiedReasoning | undefined;
+/** Serialize Unified reasoning onto the Chat Completions wire shape in place. */
+export declare function applyOpenAIChatReasoning(request: UnifiedChatRequest): UnifiedChatRequest;
+/** Anthropic accepts low..max, while CCR/OpenAI may additionally emit minimal/ultra/none. */
+export declare function toAnthropicReasoningEffort(effortValue: unknown): Exclude<ThinkLevel, "none" | "minimal" | "ultra"> | undefined;
+export {};

package/dist/utils/redact.d.ts

@@ -24,6 +24,7 @@ export declare function sanitizeBodyForLog(value: string, maxBytes?: number): st
 export declare function sanitizeErrorForLog(error: unknown): {
     message: string;
     code?: string;
+    type?: string;
     name?: string;
     statusCode?: number;
     stack?: string;

package/dist/utils/sse/client-keepalive.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Client-facing SSE keepalive.
+ *
+ * Claude Code shows "Waiting for API response · will retry in … · check your
+ * network" when no bytes arrive on the response stream for 20s (advisor: 90s),
+ * even before any retry has started — see Claude Code error docs. Anthropic's
+ * own `ping` events often arrive only every ~25–30s during long thinking /
+ * tool-argument streams, so a transparent proxy that only forwards upstream
+ * bytes trips that spinner on every slow Opus turn.
+ *
+ * Inject SSE comment frames (`: …\n\n`) after `idleMs` of silence. Comments are
+ * transport keepalives: EventSource / Anthropic SSE parsers ignore them, but
+ * they reset Claude Code's byte-idle timer. Default 10s is half the 20s warning.
+ */
+export type SSEClientKeepaliveOptions = {
+    /** Silence before emitting a comment frame. Default 10_000. */
+    idleMs?: number;
+};
+export declare function withSSEClientKeepalive(body: ReadableStream<Uint8Array>, options?: SSEClientKeepaliveOptions): ReadableStream<Uint8Array>;

package/dist/utils/sse/index.d.ts

@@ -1,3 +1,4 @@
 export { SSEParserTransform } from './SSEParser.transform';
 export { SSESerializerTransform } from './SSESerializer.transform';
 export { rewriteStream } from './rewriteStream';
+export { withSSEClientKeepalive, type SSEClientKeepaliveOptions, } from './client-keepalive';

package/dist/utils/sse-debug-tap.d.ts

@@ -0,0 +1,62 @@
+import { type CacheAffinityHeaders, type CachePrefixDiff, type CachePrefixStage } from "./cache-prefix-debug";
+export type UpstreamSSEDebugOptions = {
+    logger?: any;
+    reqId?: string | number;
+    provider?: string;
+    /** Routed model — snapshots are keyed per destination. */
+    model?: string;
+    /** Conversation / Claude session id used to pair consecutive cache snapshots. */
+    conversationId?: string;
+    /** Pipeline position this body was captured at. Defaults to `wire`. */
+    stage?: CachePrefixStage;
+    /** Codex (and similar) routing headers that pin prompt-cache affinity. */
+    cacheAffinity?: CacheAffinityHeaders;
+    /** Upstream status. Non-2xx bodies are diffed but never become the baseline. */
+    responseStatus?: number;
+    /** Client-leg diff, used to attribute a broken wire prefix to a stage. */
+    clientStageDiff?: CachePrefixDiff | null;
+    /** Outbound diff for this request, joined with the observed cache usage. */
+    cacheDiff?: CachePrefixDiff | null;
+    /** Cap for a single logged payload string (raw `data` field). */
+    maxBytes?: number;
+};
+/**
+ * Byte-preserving upstream response debug tap.
+ *
+ * For SSE: mirrors bytes to a background consumer that emits Codex-parity
+ * `recieved data` / `Original Response` logs (including Anthropic usage /
+ * cache fields on message_start / message_delta).
+ *
+ * Important: do **not** use `ReadableStream.tee()` here. Tee couples
+ * backpressure across both branches — a slow debug logger (pino file I/O on
+ * every thinking delta) stalls the client branch. Claude Code then idles long
+ * enough to surface "Waiting for API response · check your network" and retry
+ * while CCR eventually still finishes the upstream as HTTP 200.
+ *
+ * Instead, a TransformStream forwards each chunk to the client immediately and
+ * copies into a debug tunnel whose writable side has an infinite high-water
+ * mark, so debug I/O can never delay the client. The debug consumer drains the
+ * buffered copy at its own pace (memory-bound to the stream size).
+ *
+ * Exact-wire passthrough never enters transformer stream loggers; this tap is
+ * the single shared place that covers every outbound provider.
+ */
+export declare function tapUpstreamSSEDebug(response: Response, opts: UpstreamSSEDebugOptions): Promise<Response>;
+export type CacheStructureSummary = {
+    systemBreakpoints: number;
+    messageBreakpoints: number;
+    toolBreakpoints: number;
+    prompt_cache_key?: string;
+    lastAssistantBlockOrder?: string[];
+};
+/**
+ * Summarize outbound Anthropic/OpenAI cache-oriented request structure for
+ * debug verification (breakpoints / prompt_cache_key / assistant block order).
+ */
+export declare function summarizeOutboundCacheStructure(body: Record<string, any> | null | undefined): CacheStructureSummary | null;
+/**
+ * Snapshot the outbound body, diff it against the previous turn, and log both.
+ * Returns the diff so the caller can join it with the observed cache usage
+ * once upstream responds.
+ */
+export declare function logOutboundCacheStructure(body: Record<string, any> | null | undefined, opts: UpstreamSSEDebugOptions): CachePrefixDiff | null;

package/dist/utils/xai-auth.d.ts

@@ -0,0 +1,37 @@
+declare const OAUTH_CONFIG: {
+    client_id: string;
+    device_authorization_endpoint: string;
+    token_endpoint: string;
+    scope: string;
+};
+export interface XaiTokens {
+    access_token: string;
+    refresh_token?: string;
+    id_token?: string;
+    token_type: string;
+    scope?: string;
+    expires_at?: number;
+    last_refresh?: number;
+}
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in?: number;
+    interval?: number;
+}
+declare function getAuthFilePath(): string;
+export declare function loadTokens(): XaiTokens | null;
+export declare function saveTokens(tokens: XaiTokens): void;
+export declare function isTokenExpiring(tokens: XaiTokens, skewSeconds?: number): boolean;
+export declare function requestDeviceCode(): Promise<DeviceCodeResponse>;
+export declare function pollDeviceCodeToken(device: DeviceCodeResponse, options?: {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<XaiTokens>;
+export declare function refreshTokens(_refreshToken?: string): Promise<XaiTokens>;
+export declare function getValidAccessToken(options?: {
+    force?: boolean;
+}): Promise<XaiTokens>;
+export { getAuthFilePath, OAUTH_CONFIG };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caeliq/llms",
-  "version": "1.0.59",
+  "version": "1.0.61",
   "description": "A universal LLM API transformation server",
   "main": "dist/cjs/server.cjs",
   "module": "dist/esm/server.mjs",
@@ -30,29 +30,29 @@
   ],
   "dependencies": {
     "@anthropic-ai/sdk": "^0.115.0",
-    "@caeliq/ccr-shared": "^2.1.1",
-    "@cursor/sdk": "^1.0.26",
+    "@caeliq/ccr-shared": "^2.1.3",
+    "@cursor/sdk": "^1.0.28",
     "@fastify/cors": "^11.3.0",
-    "@fastify/rate-limit": "^10.3.0",
-    "@google/genai": "^2.15.0",
+    "@fastify/rate-limit": "^11.2.0",
+    "@google/genai": "^2.17.1",
     "@huggingface/tokenizers": "^0.1.3",
     "dotenv": "^17.4.2",
-    "fastify": "^5.11.2",
+    "fastify": "^5.12.0",
     "fastify-plugin": "^6.0.0",
-    "google-auth-library": "^11.0.0",
+    "google-auth-library": "^11.0.2",
     "json5": "^2.2.3",
     "jsonrepair": "^3.15.0",
     "latex-to-unicode": "^0.1.0",
     "lru-cache": "^11.5.2",
-    "openai": "^7.2.0",
+    "openai": "^7.4.0",
     "tiktoken": "^1.0.22",
-    "undici": "^8.9.0",
+    "undici": "^8.10.0",
     "uuid": "^14.0.1"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
-    "esbuild": "^0.28.1",
-    "tsx": "^4.23.1",
+    "@types/node": "^26.2.0",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3"
   },
   "engines": {