@caeliq/llms 1.0.65 → 1.0.67

package/dist/utils/paced-sse.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Hermetic paced SSE upstream for latency / cadence benchmarks.
+ * Emits fixed-cadence Chat Completions SSE events with configurable delays.
+ */
+export type PacedSSEOptions = {
+    /** Delay before response headers resolve (ms). */
+    headerDelayMs?: number;
+    /** Delay before first SSE body byte after headers (ms). */
+    firstByteDelayMs?: number;
+    /** Gap between successive events (ms). */
+    eventIntervalMs?: number;
+    /** Number of content delta events. */
+    eventCount?: number;
+    /** Split each event across this many TCP-ish chunks (default 1). */
+    fragmentChunks?: number;
+    /** Abort tracking. */
+    signal?: AbortSignal;
+    /** Optional terminal Zen-style network_error finish_reason. */
+    terminalNetworkError?: boolean;
+    /** Fail with this HTTP status instead of streaming. */
+    httpErrorStatus?: number;
+    httpErrorBody?: string;
+};
+export type PacedSSEEventStamp = {
+    index: number;
+    enqueuedAt: number;
+};
+/**
+ * Build a Response whose body emits Chat Completions SSE at a fixed cadence.
+ * `stamps` is filled as each logical event is enqueued (before fragmentation).
+ */
+export declare function createPacedSSEResponse(options?: PacedSSEOptions, stamps?: PacedSSEEventStamp[]): Promise<Response>;
+/** Read a stream and record when each complete SSE event (blank-line delimited) arrives. */
+export declare function collectSSEEventTimings(body: ReadableStream<Uint8Array>, t0?: number): Promise<{
+    events: string[];
+    arrivalsMs: number[];
+}>;
+export declare function interArrivalGaps(arrivalsMs: number[]): number[];

package/dist/utils/request-latency.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Request-stage latency timings. Allocation-light monotonic stamps; one
+ * terminal structured record per request. No per-event logging, no tee.
+ */
+export type LatencyStage = "received" | "bodyParsed" | "normalized" | "projectLookup" | "tokenizeStart" | "tokenizeEnd" | "routeSelected" | "destinationPolicy" | "requestTransformers" | "upstreamFetchStart" | "upstreamHeaders" | "upstreamFirstByte" | "responseTransformers" | "downstreamFirstByte" | "complete";
+export type RequestLatency = {
+    t0: number;
+    stages: Partial<Record<LatencyStage, number>>;
+    meta: {
+        protocol?: string;
+        provider?: string;
+        model?: string;
+        method?: string;
+        url?: string;
+        scenario?: string;
+        bypass?: boolean;
+        wireKeep?: boolean;
+        tokenCount?: number;
+        tokenCountSource?: "exact" | "estimate" | "skipped";
+        inputBytes?: number;
+        upstreamAttempts?: number;
+        cancelled?: boolean;
+        error?: string;
+    };
+    emitted?: boolean;
+};
+export declare function createRequestLatency(): RequestLatency;
+export declare function markLatency(latency: RequestLatency | undefined | null, stage: LatencyStage): void;
+export declare function tapResponseFirstByte(response: Response, onFirstByte: () => void): Response;
+export declare function attachLatencyMeta(latency: RequestLatency | undefined | null, meta: Partial<RequestLatency["meta"]>): void;
+/** Emit one structured terminal latency record. Safe to call multiple times. */
+export declare function emitLatencyRecord(logger: {
+    info?: (obj: unknown, msg?: string) => void;
+} | undefined | null, latency: RequestLatency | undefined | null): void;
+export declare function ensureRequestLatency(req: {
+    _latency?: RequestLatency;
+}): RequestLatency;

package/dist/utils/request.d.ts

@@ -1,4 +1,11 @@
+import { ProxyAgent } from "undici";
 import { UnifiedChatRequest } from "../types/llm";
+/** One Undici ProxyAgent per normalized proxy URL so connections can be reused. */
+export declare function getProxyDispatcher(httpsProxy: string): ProxyAgent;
+/** Close every cached ProxyAgent (call on server shutdown). */
+export declare function closeProxyDispatchers(): void;
+/** Test-only: inspect the module-level dispatcher cache. */
+export declare function __getProxyDispatcherCacheForTests(): Map<string, ProxyAgent>;
 /** Loopback and NO_PROXY/no_proxy hosts should not go through HTTPS_PROXY. */
 export declare function shouldBypassProxy(target: URL | string): boolean;
-export declare function sendUnifiedRequest(url: URL | string, request: UnifiedChatRequest, config: any, _context: any, _logger?: any): Promise<Response>;
+export declare function sendUnifiedRequest(url: URL | string, request: UnifiedChatRequest, config: any, context: any, _logger?: any): Promise<Response>;

package/dist/utils/responses.encrypted-content-cache.d.ts

@@ -0,0 +1,42 @@
+import { LLMProvider, UnifiedChatRequest, UnifiedMessage } from "../types/llm";
+import { TransformerContext } from "../types/transformer";
+type MessageLike = Pick<UnifiedMessage, "role" | "content" | "thinking" | "tool_calls" | "tool_call_id" | "reasoning_content"> & {
+    name?: string;
+};
+export type EncryptedReasoningPayload = {
+    encrypted_content: string;
+    content?: string;
+    id?: string;
+};
+export type EncryptedReasoningStreamRecorder = {
+    observe(event: any): void;
+    completedOutput(): any[] | undefined;
+    discard(): void;
+};
+/**
+ * Accumulate only the opaque reasoning/tool state needed for replay. Some
+ * Responses-compatible hosts omit full output from response.completed, so the
+ * cache cannot depend on that one event. Bounds make malformed streams fail
+ * closed (no cache write) without affecting client-visible stream conversion.
+ */
+export declare function createEncryptedReasoningStreamRecorder(): EncryptedReasoningStreamRecorder;
+export declare function isCrossProtocolResponsesClient(context?: TransformerContext): boolean;
+export declare function buildEncryptedReasoningCacheNamespace(request: Pick<UnifiedChatRequest, "model" | "thinking" | "reasoning">, provider?: Pick<LLMProvider, "name" | "baseUrl">, context?: TransformerContext): string;
+/**
+ * Anthropic/Chat clients cannot round-trip Responses `encrypted_content`.
+ * For those inbound protocols, request ciphertext from the destination and
+ * restore it onto assistant tool turns from a local cache keyed like DeepSeek's
+ * reasoning replay cache.
+ */
+export declare function prepareEncryptedReasoningReplay(request: UnifiedChatRequest, provider: Pick<LLMProvider, "name" | "baseUrl"> | undefined, context?: TransformerContext): {
+    restoredFromCache: number;
+    includeRequested: boolean;
+};
+export declare function hasEncryptedReasoningContext(context?: TransformerContext): boolean;
+export declare function recordEncryptedReasoningResponseMessage(message: MessageLike | null | undefined, context?: TransformerContext): number;
+/**
+ * Build a cacheable assistant message from a Responses `output` array.
+ * Ciphertext often arrives only on the terminal reasoning item.
+ */
+export declare function assistantMessageFromResponsesOutput(output: any[] | undefined): MessageLike | null;
+export {};

package/dist/utils/sse/incremental-parser.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Incremental SSE event parser that preserves each event's raw bytes/text so
+ * unchanged events can be forwarded without re-serialization.
+ */
+export type ParsedSSEEvent = {
+    event?: string;
+    id?: string;
+    retry?: number;
+    /** Parsed JSON, `{ type: "done" }` for [DONE], or `{ raw, error }`. */
+    data?: unknown;
+    /** Original data field string (without the `data:` prefix), if any. */
+    dataRaw?: string;
+    /**
+     * Exact event block as received, including the blank-line delimiter.
+     * Forward this unchanged for byte-preserving passthrough.
+     */
+    raw: string;
+};
+/**
+ * Feed decoded SSE text and emit complete events. Tolerates `\n` and `\r\n`.
+ */
+export declare class IncrementalSSEParser {
+    private buffer;
+    push(chunk: string): ParsedSSEEvent[];
+    flush(): ParsedSSEEvent[];
+    private takeComplete;
+}
+/** Serialize a (possibly modified) event. Prefer `event.raw` when unchanged. */
+export declare function serializeSSEEvent(event: {
+    event?: string;
+    id?: string;
+    retry?: number;
+    data?: unknown;
+    dataRaw?: string;
+}): string;

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

@@ -1,4 +1,6 @@
-import { type CacheAffinityHeaders, type CachePrefixDiff, type CachePrefixStage } from "./cache-prefix-debug";
+import { type CacheAffinityHeaders, type CachePrefixDiff, type CachePrefixIdSource, type CachePrefixStage } from "./cache-prefix-debug";
+import { type CachePrediction, type CursorCacheLifecycle } from "./cache-outcome";
+import type { MessageDebugDirection } from "./message-debug";
 export type UpstreamSSEDebugOptions = {
     logger?: any;
     reqId?: string | number;
@@ -7,6 +9,9 @@ export type UpstreamSSEDebugOptions = {
     model?: string;
     /** Conversation / Claude session id used to pair consecutive cache snapshots. */
     conversationId?: string;
+    conversationIdSource?: CachePrefixIdSource;
+    /** When false, diff against the last baseline but do not replace it. */
+    commitCachePrefix?: boolean;
     /** Pipeline position this body was captured at. Defaults to `wire`. */
     stage?: CachePrefixStage;
     /** Codex (and similar) routing headers that pin prompt-cache affinity. */
@@ -17,14 +22,45 @@ export type UpstreamSSEDebugOptions = {
     clientStageDiff?: CachePrefixDiff | null;
     /** Outbound diff for this request, joined with the observed cache usage. */
     cacheDiff?: CachePrefixDiff | null;
+    /** Outbound body used to resolve Anthropic/Gemini family signals. */
+    outboundBody?: Record<string, any> | null;
+    /** Precomputed prediction; built from cacheDiff + family when absent. */
+    cachePrediction?: CachePrediction | null;
+    /** Cursor lifecycle plan for conversation-cache prediction. */
+    cursorLifecycle?: CursorCacheLifecycle | null;
     /** Cap for a single logged payload string (raw `data` field). */
     maxBytes?: number;
+    /**
+     * Opt-in raw per-event SSE logging. Independent of LOG_LEVEL=debug.
+     * When false (default), the debug tap still computes terminal cache outcome
+     * summaries but does not log every delta.
+     */
+    rawEvents?: boolean;
+    /**
+     * Which wire leg produced these bytes. Defaults to `provider→ccr` for the
+     * upstream tap and `ccr→client` for the client tap.
+     */
+    direction?: MessageDebugDirection;
+    /**
+     * When true, only emit raw SSE/JSON event logs (no cache outcome summary).
+     * Used for the client-bound leg where cache usage was already observed upstream.
+     */
+    eventsOnly?: boolean;
+};
+export type ClientSSEDebugOptions = {
+    logger?: any;
+    reqId?: string | number;
+    provider?: string;
+    model?: string;
+    protocol?: string;
+    maxBytes?: number;
+    rawEvents?: boolean;
 };
 /**
  * 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 /
+ * `received data` / `Original Response` logs (including Anthropic usage /
  * cache fields on message_start / message_delta).
  *
  * Important: do **not** use `ReadableStream.tee()` here. Tee couples
@@ -42,6 +78,12 @@ export type UpstreamSSEDebugOptions = {
  * the single shared place that covers every outbound provider.
  */
 export declare function tapUpstreamSSEDebug(response: Response, opts: UpstreamSSEDebugOptions): Promise<Response>;
+/**
+ * Byte-preserving tap for the SSE body CCR sends back to the client after
+ * response transformers. Same non-blocking tunnel as the upstream tap; events
+ * are tagged `direction: "ccr→client"` so greps can split the two legs.
+ */
+export declare function tapClientSSEDebug(body: ReadableStream<Uint8Array>, opts: ClientSSEDebugOptions): ReadableStream<Uint8Array>;
 export type CacheStructureSummary = {
     systemBreakpoints: number;
     messageBreakpoints: number;

package/dist/utils/stream-peek.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sniff a response body as JSON vs SSE without Response.clone().
+ *
+ * Cloudflare (Codex) often strips Content-Type from SSE. The first
+ * non-whitespace byte is `{`/`[` for a JSON object/array and anything
+ * else (typically `d` from `data:`) for SSE. JSON drains into text;
+ * SSE returns a new Response that replays the peeked chunk then
+ * continues from the same reader.
+ */
+export type PeekedResponseBody = {
+    kind: "json";
+    firstChar: string;
+    text: string;
+} | {
+    kind: "sse";
+    response: Response;
+} | {
+    kind: "empty";
+};
+export declare function peekResponseBody(response: Response): Promise<PeekedResponseBody>;

package/dist/utils/stream.d.ts

@@ -1,13 +1,36 @@
+import { type ParsedSSEEvent } from "./sse/incremental-parser";
 export interface StreamContext {
     controller: ReadableStreamDefaultController;
     encoder: TextEncoder;
 }
-export declare function createSSEStreamReader(response: Response, processLine: (line: string, context: StreamContext) => void, options?: {
+export type SSEEvent = ParsedSSEEvent;
+export type ProcessSSEEvent = (event: SSEEvent, context: StreamContext) => void;
+export type ProcessSSELine = (line: string, context: StreamContext) => void;
+/** Forward an event using its original raw bytes/string. */
+export declare function forwardSSEEvent(event: SSEEvent, context: StreamContext): void;
+/** Serialize and enqueue a modified event (only when data changed). */
+export declare function emitSSEEvent(event: {
+    event?: string;
+    id?: string;
+    retry?: number;
+    data?: unknown;
+    dataRaw?: string;
+}, context: StreamContext): void;
+type StreamReaderOptions = {
     bufferSize?: number;
     onComplete?: (context: StreamContext) => void;
-    /** Return true when the protocol adapter emitted its own terminal error. */
     onError?: (error: unknown, context: StreamContext) => boolean | void;
     logger?: any;
-}): Response;
+    processEvent?: ProcessSSEEvent;
+};
+/**
+ * Create a transformed SSE Response.
+ *
+ * Prefer `options.processEvent` for event-native handling (parse once, forward
+ * raw when unchanged). The legacy `processLine` callback is still supported via
+ * a shim that feeds reconstructed data lines.
+ */
+export declare function createSSEStreamReader(response: Response, processLineOrOptions?: ProcessSSELine | StreamReaderOptions, maybeOptions?: StreamReaderOptions): Response;
 export declare function encodeSSEData(data: string, encoder: TextEncoder): Uint8Array;
 export declare function encodeSSELine(line: string, encoder: TextEncoder): Uint8Array;
+export { serializeSSEEvent } from "./sse/incremental-parser";

package/dist/utils/token-count-worker.d.ts

@@ -0,0 +1,12 @@
+export type TokenCountWorkerRequest = {
+    messages: unknown;
+    system: unknown;
+    tools: unknown;
+};
+/** Offload when serialized payload exceeds this many characters. */
+export declare const TOKEN_COUNT_WORKER_THRESHOLD_CHARS = 200000;
+export declare function estimateTokenizePayloadChars(messages: unknown, system: unknown, tools: unknown): number;
+/** Conservative under-estimate: ~4 chars/token. Safe for "below threshold" skips. */
+export declare function estimateTokensFromChars(charCount: number): number;
+export declare function countTokensInWorker(request: TokenCountWorkerRequest): Promise<number>;
+export declare function closeTokenCountWorkers(): Promise<void>;

package/dist/utils/tool-content.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Multimodal tool-result helpers.
+ *
+ * Responses / OpenCode attach images (and files) on function_call_output as
+ * structured parts. Unified carries them as text / image_url / file parts on
+ * role:"tool". Destinations differ:
+ *   - Responses/Codex: re-emit input_image / input_file in output[]
+ *   - Anthropic: image / document blocks inside tool_result.content
+ *   - Gemini: text in functionResponse + sibling inlineData parts
+ *   - Chat Completions / Mistral: string tool content only — extract media
+ *     into a follow-up user message (OpenCode's pattern for non-supporting APIs)
+ */
+export type UnifiedToolPart = {
+    type: "text";
+    text: string;
+    cache_control?: any;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: string;
+    };
+    media_type?: string;
+    cache_control?: any;
+} | {
+    type: "file";
+    filename?: string;
+    file_data?: string;
+    file_url?: string;
+    media_type?: string;
+    cache_control?: any;
+};
+export declare function isUnifiedToolMediaPart(part: any): part is Extract<UnifiedToolPart, {
+    type: "image_url" | "file";
+}>;
+/** Normalize string | part[] tool content into a part list. */
+export declare function normalizeUnifiedToolParts(content: unknown): UnifiedToolPart[];
+export declare function unifiedToolTextOnly(content: unknown): string;
+export declare function unifiedToolHasMedia(content: unknown): boolean;
+/** Anthropic tool_result.content: string or (text|image|document)[]. */
+export declare function unifiedToolContentToAnthropic(content: unknown): string | any[];
+/**
+ * Anthropic inbound tool_result.content → Unified tool content
+ * (string or text/image_url/file parts).
+ */
+export declare function anthropicToolResultToUnified(content: unknown): string | any[];
+/** Gemini sibling inlineData / fileData parts for tool media. */
+export declare function unifiedToolMediaToGeminiParts(content: unknown): any[];
+/**
+ * Chat Completions / Mistral: string-only tool content. Pull media out of
+ * tool messages and insert a synthetic user message after each contiguous
+ * tool-result group so vision still reaches the model.
+ */
+export declare function extractToolMediaForStringToolApis(messages: any[]): any[];

package/dist/utils/transformer-plan.d.ts

@@ -0,0 +1,30 @@
+import type { Transformer } from "../types/transformer";
+export type CompiledTransformerPlan = {
+    /** Body/header middleware, then at most one transport owner. */
+    request: Transformer[];
+    /** Reverse of `request` for onion-style response transforms. */
+    response: Transformer[];
+    transportOwner?: Transformer;
+};
+/**
+ * Compile provider-level + model-level transformer chains into one plan.
+ *
+ * - Deduplicates by transformer name (first occurrence wins).
+ * - Runs every non-transport transformer before the transport owner.
+ * - Rejects configurations that leave more than one distinct transport owner.
+ */
+export declare function compileTransformerPlan(providerUse: Transformer[] | undefined, modelUse: Transformer[] | undefined, options?: {
+    skipName?: string;
+}): CompiledTransformerPlan;
+export declare function isExactProtocolResponsePlan(plan: CompiledTransformerPlan, endpointTransformer: Transformer, clientProtocolOwnerName: string | undefined): boolean;
+export declare function isExactProtocolRequestPlan(plan: CompiledTransformerPlan, endpointTransformer: Transformer, clientProtocolOwnerName: string | undefined): boolean;
+/**
+ * v1 allowlist: middleware known to be safe on a kept native wire.
+ * `OpenAI` is handled separately — it always runs. `reasoning` is
+ * Chat-shaped and only allowed with an OpenAI owner. Everything else
+ * (Anthropic/Responses owners) does not run Unified-only middleware.
+ */
+export declare function isWireSafeMiddlewareForKeep(name: string | undefined, ownerName: string | undefined): boolean;
+export declare function planContains(plan: CompiledTransformerPlan, name: string): boolean;
+/** Cancel a Response body when a newer transport result replaces it. */
+export declare function cancelReplacedProviderResponse(previous: Response | undefined | null, next: Response | undefined | null): void;

package/dist/utils/vertex-claude.util.d.ts

@@ -2,7 +2,7 @@ import { UnifiedChatRequest } from "../types/llm";
 interface ClaudeMessage {
     role: "user" | "assistant";
     content: Array<{
-        type: "text" | "image" | "tool_use" | "tool_result";
+        type: "text" | "image" | "document" | "tool_use" | "tool_result";
         text?: string;
         source?: {
             type: "base64";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caeliq/llms",
-  "version": "1.0.65",
+  "version": "1.0.67",
   "description": "A universal LLM API transformation server",
   "main": "dist/cjs/server.cjs",
   "module": "dist/esm/server.mjs",
@@ -30,8 +30,8 @@
   ],
   "dependencies": {
     "@anthropic-ai/sdk": "^0.120.0",
-    "@caeliq/ccr-shared": "^2.1.7",
-    "@cursor/sdk": "^1.0.28",
+    "@caeliq/ccr-shared": "^2.1.9",
+    "@cursor/sdk": "^1.0.30",
     "@fastify/cors": "^11.3.0",
     "@fastify/rate-limit": "^11.2.0",
     "@google/genai": "^2.18.0",
@@ -50,7 +50,7 @@
     "uuid": "^14.0.2"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "esbuild": "^0.28.2",
     "tsx": "^4.23.12",
     "typescript": "^6.0.3"