dsh-lcx-codex 0.4.2 → 0.4.3-pre.2

package/lib/types/index.d.ts

@@ -0,0 +1,83 @@
+import z from "@deepseek-ai/schemastery";
+import type { Context } from "@deepseek-ai/cordis";
+import "@deepseek-ai/dsh-agent";
+import "@deepseek-ai/dsh-tools";
+import "@deepseek-ai/dsh-web";
+export declare const name = "lcx-codex";
+export declare const inject: string[];
+type ConfigInput = {
+    supportsLongCacheRetention?: unknown;
+    supportsExplicitPromptCacheMode?: unknown;
+    alphaCapabilityPath?: unknown;
+    alphaRefPath?: unknown;
+    alphaProfile?: unknown;
+    alphaGroup?: unknown;
+    alphaMaxOutputTokens?: unknown;
+    webSearchProvider?: unknown;
+    webMaxResults?: unknown;
+    timeoutMs?: unknown;
+    maxResponseBytes?: unknown;
+    maxAttempts?: unknown;
+    maxRequestImageBytes?: unknown;
+    requestImagePixelBudget?: unknown;
+    requestImageMaxBytes?: unknown;
+    portableReplayMaxChars?: unknown;
+    nativeRetentionTokenBudget?: unknown;
+    assistantRetentionTokenReserve?: unknown;
+    assistantRetentionPerMessageTokenCap?: unknown;
+};
+type HostContext = Context;
+export declare const Config: z<Schemastery.ObjectS<{
+    supportsLongCacheRetention: z<boolean, boolean>;
+    supportsExplicitPromptCacheMode: z<boolean, boolean>;
+    alphaCapabilityPath: z<string, string>;
+    alphaRefPath: z<string, string>;
+    alphaProfile: z<string, string>;
+    alphaGroup: z<string, string>;
+    alphaMaxOutputTokens: z<number, number>;
+    webSearchProvider: z<string, string>;
+    webMaxResults: z<number, number>;
+    timeoutMs: z<number, number>;
+    maxResponseBytes: z<number, number>;
+    maxAttempts: z<number, number>;
+    maxRequestImageBytes: z<number, number>;
+    requestImagePixelBudget: z<number, number>;
+    requestImageMaxBytes: z<number, number>;
+    portableReplayMaxChars: z<number, number>;
+    nativeRetentionTokenBudget: z<number, number>;
+    assistantRetentionTokenReserve: z<number, number>;
+    assistantRetentionPerMessageTokenCap: z<number, number>;
+}>, Schemastery.ObjectT<{
+    supportsLongCacheRetention: z<boolean, boolean>;
+    supportsExplicitPromptCacheMode: z<boolean, boolean>;
+    alphaCapabilityPath: z<string, string>;
+    alphaRefPath: z<string, string>;
+    alphaProfile: z<string, string>;
+    alphaGroup: z<string, string>;
+    alphaMaxOutputTokens: z<number, number>;
+    webSearchProvider: z<string, string>;
+    webMaxResults: z<number, number>;
+    timeoutMs: z<number, number>;
+    maxResponseBytes: z<number, number>;
+    maxAttempts: z<number, number>;
+    maxRequestImageBytes: z<number, number>;
+    requestImagePixelBudget: z<number, number>;
+    requestImageMaxBytes: z<number, number>;
+    portableReplayMaxChars: z<number, number>;
+    nativeRetentionTokenBudget: z<number, number>;
+    assistantRetentionTokenReserve: z<number, number>;
+    assistantRetentionPerMessageTokenCap: z<number, number>;
+}>>;
+export declare function compactionPressureBand(totalTokens: number, contextWindow: number, policy: {
+    auto: number;
+    emergency: number;
+}): {
+    ratioPercent: number;
+    band: string;
+};
+export declare function apply(ctx: HostContext, configInput?: ConfigInput): void;
+export declare namespace apply {
+    export { inject };
+    export { Config };
+}
+export default apply;

package/lib/types/json-store.d.ts

@@ -0,0 +1,10 @@
+export declare class JsonStore<T> {
+    readonly file: string;
+    readonly empty: () => T;
+    readonly validate: (data: unknown) => data is T;
+    readonly corruptCode: string;
+    data: T;
+    constructor(file: string, empty: () => T, validate: (data: unknown) => data is T, corruptCode?: string);
+    refresh(): void;
+    update(mutator: (current: T) => T): void;
+}

package/lib/types/native-checkpoint.d.ts

@@ -0,0 +1,213 @@
+import type { ResponseInputItem } from "openai/resources/responses/responses.js";
+import { Session, type SessionEvent } from "@deepseek-ai/dsh-session";
+import { requestImageHandleText, type Message, type StreamChunk, type TokenUsage } from "@deepseek-ai/dsh-llm";
+type CompactionItem = {
+    type: "compaction";
+    encrypted_content: string;
+};
+export type NativeOutputItem = ResponseInputItem;
+type RouteIdentity = {
+    provider: string;
+    model: string;
+    baseURL: string;
+    sessionId: string;
+};
+type CompactionSummaryEvent = SessionEvent<"compaction/summary">;
+type RetentionOptions = {
+    tokenBudget?: number;
+    assistantTokenReserve?: number;
+    assistantPerMessageTokenCap?: number;
+};
+type RetentionPlan = {
+    items: unknown[];
+    clientCount: number;
+    assistantCount: number;
+    estimatedTokens: number;
+    clientEstimatedTokens: number;
+    assistantEstimatedTokens: number;
+};
+type NativeCheckpointBase = {
+    compactionId: string;
+    provider: string;
+    model: string;
+    baseURLFingerprint: string;
+    sourceSessionId: string;
+    nativeOutput: NativeOutputItem[];
+    nativeCompaction?: CompactionItem;
+    retainedInputCount?: number;
+    retainedClientCount?: number;
+    retainedAssistantCount?: number;
+    retainedEstimatedTokens?: number;
+    createdAt?: number;
+};
+export type NativeCheckpointV5 = NativeCheckpointBase & {
+    type: "lcx-native-compaction-v5";
+    version: 5;
+    retentionPolicy?: "conversation-fidelity-v1";
+};
+export type NativeCheckpointBlock = NativeCheckpointV5;
+declare module "@deepseek-ai/dsh-llm" {
+    interface ContentBlockMap {
+        "lcx-native-compaction-v5": NativeCheckpointV5;
+    }
+}
+type NativeCompactionResult = {
+    compaction: CompactionItem;
+};
+type ImageAttachmentRef = Parameters<typeof requestImageHandleText>[0];
+type CheckpointRouteRecord = {
+    version: number;
+    provider: unknown;
+    model: unknown;
+    baseURLFingerprint: unknown;
+    sourceSessionId: unknown;
+};
+type CreateCheckpointOptions = {
+    session: Session;
+    route: RouteIdentity;
+    result: NativeCompactionResult;
+    input?: unknown[];
+    ephemeralPreludeItemCount?: number;
+    imageMap?: ReadonlyMap<string, ImageAttachmentRef>;
+    retentionOptions?: RetentionOptions;
+};
+/**
+ * @typedef {object} NativeCheckpointBase
+ * @property {string} compactionId
+ * @property {string} provider
+ * @property {string} model
+ * @property {string} baseURLFingerprint
+ * @property {string} sourceSessionId
+ * @property {NativeOutputItem[]} nativeOutput
+ * @property {CompactionItem} [nativeCompaction]
+ * @property {number} [retainedInputCount]
+ * @property {number} [retainedClientCount]
+ * @property {number} [retainedAssistantCount]
+ * @property {number} [retainedEstimatedTokens]
+ * @property {number} [createdAt]
+ */
+/** @typedef {NativeCheckpointBase & { type: 'lcx-native-compaction-v5', version: 5, retentionPolicy?: 'conversation-fidelity-v1' }} NativeCheckpointV5 */
+/** @typedef {NativeCheckpointV5} NativeCheckpointBlock */
+/**
+ * Minimal validated candidate shape. DSH rawOutput is unknown until the existing
+ * version, field, count, and compaction validation below has completed.
+ * @typedef {object} NativeCheckpointCandidate
+ * @property {typeof NATIVE_BLOCK_TYPE} type
+ * @property {typeof NATIVE_BLOCK_VERSION} version
+ * @property {unknown} [compactionId]
+ * @property {unknown} [nativeOutput]
+ * @property {unknown} [provider]
+ * @property {unknown} [model]
+ * @property {unknown} [baseURLFingerprint]
+ * @property {unknown} [sourceSessionId]
+ * @property {unknown} [retainedInputCount]
+ * @property {unknown} [retainedClientCount]
+ * @property {unknown} [retainedAssistantCount]
+ */
+/** @typedef {{ compaction: CompactionItem }} NativeCompactionResult */
+/** @typedef {{ session: Session, route: RouteIdentity, result: NativeCompactionResult, input?: unknown[], ephemeralPreludeItemCount?: number, imageMap?: unknown, retentionOptions?: RetentionOptions }} CreateCheckpointOptions */
+/** @typedef {Error & { code?: string }} LcxError */
+export declare const NATIVE_BLOCK_TYPE = "lcx-native-compaction-v5";
+export declare const NATIVE_BLOCK_VERSION = 5;
+export declare const RETAINED_MESSAGE_TOKEN_BUDGET = 64000;
+export declare const ASSISTANT_RETENTION_TOKEN_RESERVE = 24000;
+export declare const ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP = 3000;
+/**
+ * @param {unknown[] | null | undefined} input
+ * @param {RetentionOptions} [options]
+ * @returns {unknown[]}
+ */
+export declare function retainedCompactionInput(input: readonly unknown[] | null | undefined, options?: RetentionOptions): unknown[];
+/**
+ * @param {unknown[] | null | undefined} input
+ * @param {RetentionOptions} [options]
+ * @returns {RetentionPlan}
+ */
+export declare function retainedConversationPlan(input: readonly unknown[] | null | undefined, options?: RetentionOptions): RetentionPlan;
+/**
+ * @param {unknown[] | null | undefined} input
+ * @param {RetentionOptions} [options]
+ */
+export declare function retainedConversationInput<T>(input: readonly T[] | null | undefined, options?: RetentionOptions): T[];
+/** @param {unknown[] | null | undefined} items */
+export declare function hasRetainedCompactionInput(items: readonly unknown[] | null | undefined): boolean;
+export declare function compactCheckpointId(message: Message | null | undefined): string | undefined;
+/** Reject reserved checkpoint markers without interpreting unsupported formats or opening sidecars. */
+export declare function assertSupportedCheckpointMessage(message: Message): void;
+/** @param {Session | null | undefined} session */
+export declare function activeCompactionId(session: Session | null | undefined): string | undefined;
+/**
+ * @param {CreateCheckpointOptions} options
+ * @returns {NativeCheckpointV5}
+ */
+export declare function createNativeCheckpointBlock({ session, route, result, input, ephemeralPreludeItemCount, imageMap, retentionOptions, }: CreateCheckpointOptions): NativeCheckpointV5;
+/**
+ * @param {NativeCheckpointBlock} block
+ * @param {unknown} usage
+ * @returns {UnknownRecord[]}
+ */
+export declare function nativeCheckpointChunks(block: NativeCheckpointBlock, usage: TokenUsage | undefined): StreamChunk[];
+/**
+ * @param {Session | null | undefined} session
+ * @param {string | null | undefined} compactionId
+ * @returns {CompactionSummaryEvent | undefined}
+ */
+export declare function compactionSummaryEvent(session: Session | null | undefined, compactionId: string | null | undefined): CompactionSummaryEvent | undefined;
+/**
+ * @param {CompactionSummaryEvent | null | undefined} event
+ * @returns {NativeCheckpointBlock | undefined}
+ */
+export declare function stateFromSummaryEvent(event: CompactionSummaryEvent | null | undefined): {
+    compactionId: string;
+    provider: string;
+    model: string;
+    baseURLFingerprint: string;
+    sourceSessionId: string;
+    nativeOutput: NativeOutputItem[];
+    nativeCompaction: CompactionItem;
+    retainedInputCount?: number | undefined;
+    retainedClientCount?: number | undefined;
+    retainedAssistantCount?: number | undefined;
+    type: string;
+    version: number;
+} | undefined;
+/**
+ * @param {Session} session
+ * @param {Message} message
+ */
+export declare function checkpointStateForMessage(session: Session, message: Message): {
+    compactionId: string;
+    provider: string;
+    model: string;
+    baseURLFingerprint: string;
+    sourceSessionId: string;
+    nativeOutput: NativeOutputItem[];
+    nativeCompaction: CompactionItem;
+    retainedInputCount?: number | undefined;
+    retainedClientCount?: number | undefined;
+    retainedAssistantCount?: number | undefined;
+    type: string;
+    version: number;
+} | undefined;
+/**
+ * @param {NativeCheckpointBlock} state
+ * @param {RouteIdentity} route
+ * @param {unknown} ctx
+ */
+export declare function stateRouteCompatible(state: CheckpointRouteRecord | null | undefined, route: RouteIdentity, ctx: unknown): boolean;
+/**
+ * @param {Session} session
+ * @param {string} compactionId
+ * @returns {Message[]}
+ */
+export declare function shadowedMessagesForCheckpoint(session: Session, compactionId: string): Message[];
+/**
+ * @param {Session} session
+ * @param {string} compactionId
+ * @param {{ maxChars?: number }} [options]
+ * @returns {Message[]}
+ */
+export declare function portableMessagesForCheckpoint(session: Session, compactionId: string, options?: {
+    maxChars?: number;
+}): Message[];
+export {};

package/lib/types/responses-request.d.ts

@@ -0,0 +1,58 @@
+/** @typedef {'none' | 'short' | 'long'} CacheRetention */
+type UnknownRecord = Record<string, unknown>;
+type CacheRetention = "none" | "short" | "long";
+type ResponsesCompat = {
+    supportsLongCacheRetention?: boolean;
+    supportsExplicitPromptCacheMode?: boolean;
+    supportsMaxOutputTokens?: boolean;
+};
+type PiResponsesModel = {
+    id: string;
+    provider: string;
+    reasoning?: boolean;
+    thinkingLevelMap?: Record<string, string | null>;
+    compat?: ResponsesCompat;
+};
+type GenerationControls = {
+    reasoningEffort?: unknown;
+    temperature?: unknown;
+    maxTokens?: unknown;
+};
+type BuildResponsesBodyOptions = GenerationControls & {
+    model: PiResponsesModel | string;
+    input: unknown[];
+    tools?: unknown;
+    sessionId?: string;
+    promptCacheKey?: string;
+    promptCacheRetention?: string;
+    cacheRetention?: CacheRetention;
+    samplingParams?: UnknownRecord;
+};
+type ResponsesWireBody = UnknownRecord & {
+    model: string;
+    input: unknown[];
+    stream: boolean;
+    store: boolean;
+    tool_choice?: string;
+    parallel_tool_calls?: boolean;
+};
+/**
+ * Pi-parity generation controls for OpenAI Responses.
+ * @param {GenerationControls & { model?: PiResponsesModel | string, includeDefaultReasoning?: boolean }} [controls]
+ */
+export declare function responsesGenerationEnvelope({ model, reasoningEffort, temperature, maxTokens, includeDefaultReasoning, }?: GenerationControls & {
+    model?: PiResponsesModel | string;
+    includeDefaultReasoning?: boolean;
+}): UnknownRecord;
+/**
+ * Build the shared LCX-owned request envelope while retaining Pi 0.85.1 Responses semantics.
+ * Production LCX ordinary/compact/replay construction places the DSH system prompt in canonical input.
+ * @param {BuildResponsesBodyOptions} options
+ */
+export declare function buildResponsesBody({ model, input, tools, sessionId, promptCacheKey, promptCacheRetention, cacheRetention, reasoningEffort, temperature, maxTokens, samplingParams, }: BuildResponsesBodyOptions): ResponsesWireBody;
+/**
+ * Compact is the standard request plus the one opaque-history transition patch.
+ * @param {BuildResponsesBodyOptions} options
+ */
+export declare function buildCompactionResponsesBody(options: BuildResponsesBodyOptions): ResponsesWireBody;
+export {};

package/lib/types/responses-stream.d.ts

@@ -0,0 +1,51 @@
+import { type Model as PiModel } from "@earendil-works/pi-ai";
+import type { StreamChunk } from "@deepseek-ai/dsh-llm";
+type UnknownRecord = Record<string, unknown>;
+type PiResponsesModel = PiModel<"openai-responses">;
+type ManagedFailure = {
+    message: string;
+    code: string;
+    status?: number;
+    requestId?: string;
+    providerRetryAfterMs?: number;
+};
+type AbortLike = Pick<AbortSignal, "aborted" | "reason">;
+type StreamRequestOptions = {
+    baseURL: string;
+    provider: string;
+    model: string;
+    piModel: PiResponsesModel;
+    body: UnknownRecord;
+    grammarToolInputProperties?: ReadonlyMap<string, string>;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxAttempts?: number;
+    maxResponseBytes?: number;
+};
+/**
+ * Provider bodies/messages are deliberately not surfaced. Only a stable class and safe facts leave the wire boundary.
+ * @param {unknown} error
+ * @param {AbortSignal} [signal]
+ */
+export declare function managedFailure(error: unknown, signal: AbortLike | undefined): ManagedFailure;
+/** @param {unknown} error @param {AbortSignal} [signal] */
+export declare function managedFailureChunk(error: unknown, signal?: AbortLike): StreamChunk;
+/**
+ * Send one LCX-owned OpenAI Responses request. Ordinary and replay use one provider attempt;
+ * the DSH agent recovery layer remains the visible retry owner.
+ * @param {object} options
+ * @param {string} options.baseURL
+ * @param {string} options.provider
+ * @param {string} options.model
+ * @param {UnknownRecord} options.piModel
+ * @param {UnknownRecord} options.body
+ * @param {Map<string, string>} [options.grammarToolInputProperties]
+ * @param {Record<string, string>} [options.headers]
+ * @param {AbortSignal} [options.signal]
+ * @param {number} [options.timeoutMs]
+ * @param {number} [options.maxAttempts]
+ * @param {number} [options.maxResponseBytes]
+ */
+export declare function streamResponsesRequest({ baseURL, provider, model, piModel, body, grammarToolInputProperties, headers, signal, timeoutMs, maxAttempts, maxResponseBytes, }: StreamRequestOptions): AsyncGenerator<StreamChunk, void, any>;
+export {};

package/lib/types/route.d.ts

@@ -0,0 +1,132 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { type Session } from "@deepseek-ai/dsh-session";
+import "@deepseek-ai/dsh-settings";
+import { resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+type HeaderMap = Record<string, string>;
+type RetryPolicyConfig = Parameters<typeof resolveRetryPolicy>[0];
+type CacheRetention = "none" | "short" | "long";
+type ResponsesCompat = {
+    supportsDeveloperRole?: boolean;
+    sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
+    supportsStrictMode?: boolean;
+    supportsLongCacheRetention?: boolean;
+    supportsOpenAIGrammarTools?: boolean;
+    supportsAdditionalTools?: boolean;
+    supportsToolSearch?: boolean;
+    supportsExplicitPromptCacheMode?: boolean;
+    supportsMaxOutputTokens?: boolean;
+};
+type RouteIdentity = {
+    provider: string;
+    model: string;
+    baseURL: string;
+    sessionId: string;
+};
+type RouteOptions = {
+    provider?: unknown;
+    model?: unknown;
+    sessionId?: unknown;
+};
+type ProviderModelProfile = {
+    id?: unknown;
+    compat?: unknown;
+};
+type ProviderProfile = {
+    api?: string;
+    baseURL?: string;
+    apiKeyEnv?: string;
+    headers?: HeaderMap;
+    cacheRetention?: unknown;
+    timeoutMs?: unknown;
+    maxRequestImageBytes?: unknown;
+    requestImagePixelBudget?: unknown;
+    requestImageMaxBytes?: unknown;
+    retryPolicy?: RetryPolicyConfig;
+    compat?: unknown;
+    models?: ProviderModelProfile[];
+    modelOverrides?: Record<string, ProviderModelProfile>;
+};
+type LlmSettingsSection = {
+    providers?: Record<string, ProviderProfile>;
+};
+type RequestHeaderConfig = {
+    provider?: unknown;
+    model?: unknown;
+    reasoningEffort?: unknown;
+    temperature?: unknown;
+    maxTokens?: unknown;
+};
+type RequestHeader = {
+    config?: RequestHeaderConfig;
+};
+type RouteSession = Pick<Session, "requestHeader">;
+export type RouteContext = Pick<Context, "credentials" | "logger" | "sessions" | "settings">;
+type RoutePolicy = {
+    cacheRetention?: unknown;
+    supportsLongCacheRetention?: unknown;
+    supportsExplicitPromptCacheMode?: unknown;
+    responsesCompat?: unknown;
+    timeoutMs?: number;
+    maxAttempts?: number;
+    maxRequestImageBytes?: number;
+    requestImagePixelBudget?: number;
+    requestImageMaxBytes?: number;
+};
+type UnresolvedRouteConfig = RoutePolicy & {
+    provider: string;
+    model: string;
+    baseURL: string;
+    apiKeyEnv: string;
+    headers?: HeaderMap;
+};
+export type ResolvedResponsesRoute = UnresolvedRouteConfig & {
+    api: "openai-responses";
+    cacheRetention: CacheRetention;
+    supportsLongCacheRetention: boolean;
+    responsesCompat?: ResponsesCompat;
+};
+type GenerationControls = {
+    reasoningEffort?: unknown;
+    temperature?: unknown;
+    maxTokens?: unknown;
+};
+type CheckpointRouteRecord = {
+    version: number;
+    provider: unknown;
+    model: unknown;
+    baseURLFingerprint: unknown;
+    sourceSessionId: unknown;
+};
+/** @param {unknown} value */
+export declare function normalizeBaseURL(value: unknown): string;
+/** @param {unknown} baseURL */
+export declare function baseURLFingerprint(baseURL: unknown): string;
+/** @param {Partial<RouteIdentity> | null | undefined} route @param {{ includeSession?: boolean }} [options] */
+export declare function routeFingerprint(route: Partial<RouteIdentity> | null | undefined, options?: {
+    includeSession?: boolean;
+}): string;
+/** @param {Partial<RouteIdentity> | null | undefined} route @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config] @param {RouteContext | null | undefined} [ctx] */
+export declare function promptCacheSessionId(route: Partial<RouteIdentity> | null | undefined, config?: Partial<Pick<ResolvedResponsesRoute, "cacheRetention">>, ctx?: RouteContext | null | undefined): string | undefined;
+/** @param {Partial<RouteIdentity> | null | undefined} route @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config] @param {RouteContext | null | undefined} [ctx] */
+export declare function promptCacheKey(route: Partial<RouteIdentity> | null | undefined, config?: Partial<Pick<ResolvedResponsesRoute, "cacheRetention">>, ctx?: RouteContext | null | undefined): string | undefined;
+/** @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention' | 'supportsLongCacheRetention' | 'responsesCompat'>>} [config] */
+export declare function promptCacheRetention(config?: Partial<Pick<ResolvedResponsesRoute, "cacheRetention" | "supportsLongCacheRetention" | "responsesCompat">>): "24h" | undefined;
+/** @param {RouteContext | null | undefined} ctx @param {string} namespace */
+export declare function settingsValue(ctx: RouteContext | null | undefined, namespace: string): LlmSettingsSection | undefined;
+/** Resolve only the selected DSH profile; policy cannot supply route identity or credentials. */
+export declare function resolveResponsesRouteConfig(ctx: RouteContext | null | undefined, options: RouteOptions & {
+    purpose?: string;
+}, policy: RoutePolicy): ResolvedResponsesRoute | undefined;
+/** @param {RouteContext | null | undefined} ctx @param {Pick<ResolvedResponsesRoute, 'apiKeyEnv'>} config */
+export declare function resolveApiKey(ctx: RouteContext | null | undefined, config: Pick<ResolvedResponsesRoute, "apiKeyEnv">): Promise<string>;
+/** @param {RouteContext | null | undefined} ctx @param {ResolvedResponsesRoute} config @param {unknown} sessionId @param {string | null | undefined} requestId @returns {Promise<HeaderMap>} */
+export declare function authenticatedHeaders(ctx: RouteContext | null | undefined, config: ResolvedResponsesRoute, sessionId: unknown, requestId: string | null | undefined): Promise<HeaderMap>;
+/** @param {RouteOptions | null | undefined} options @param {Pick<UnresolvedRouteConfig, 'provider' | 'model' | 'baseURL'>} config @returns {RouteIdentity} */
+export declare function currentRoute(options: RouteOptions | null | undefined, config: Pick<UnresolvedRouteConfig, "provider" | "model" | "baseURL">): RouteIdentity;
+/** @param {RequestHeader | null | undefined} header @param {Partial<RouteIdentity> | null | undefined} route @returns {GenerationControls} */
+export declare function generationControlsFromHeader(header: RequestHeader | null | undefined, route: Partial<RouteIdentity> | null | undefined): GenerationControls;
+/** @param {RouteSession | null | undefined} session @param {Partial<RouteIdentity> | null | undefined} route @returns {GenerationControls} */
+export declare function generationControlsFromSession(session: RouteSession | null | undefined, route: Partial<RouteIdentity> | null | undefined): GenerationControls;
+/** @param {CheckpointRouteRecord | null | undefined} record @param {RouteIdentity} route @param {unknown} ctx */
+export declare function routeCompatible(record: CheckpointRouteRecord | null | undefined, route: RouteIdentity, ctx: unknown): boolean;
+export {};

package/lib/types/service-mutex.d.ts

@@ -0,0 +1,14 @@
+type Release = () => void;
+export declare class ServiceMutex {
+    private locked;
+    private closed;
+    private closeReason?;
+    private readonly queue;
+    private readonly idleWaiters;
+    constructor();
+    acquire(signal?: AbortSignal): Promise<Release>;
+    release(): void;
+    run<T>(signal: AbortSignal | undefined, task: () => T | Promise<T>): Promise<T>;
+    close(reason?: Error): Promise<void>;
+}
+export {};

package/lib/types/token-budget.d.ts

@@ -0,0 +1,50 @@
+export declare const PORTABLE_BUDGET_ERROR_CODE = "LCX_PORTABLE_BUDGET_EXCEEDED";
+/**
+ * A small conservative fallback, deliberately not a tokenizer. The baseline
+ * preserves legacy /4 while CJK and structural characters cost more.
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+export declare function estimateTextTokens(value: unknown): number | undefined;
+/**
+ * Project an item to model-visible fields only. Opaque provider state, raw
+ * binary, and replay/session metadata are intentionally excluded.
+ * @param {unknown} item
+ * @returns {unknown | undefined}
+ */
+export declare function modelVisibleBudgetView(item: unknown): {
+    type: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+    output?: undefined;
+    role?: undefined;
+    content?: undefined;
+} | {
+    name?: undefined;
+    arguments?: undefined;
+    type: string;
+    call_id: string;
+    output: string;
+    role?: undefined;
+    content?: undefined;
+} | {
+    name?: undefined;
+    arguments?: undefined;
+    type?: undefined;
+    call_id?: undefined;
+    output?: undefined;
+    role: string;
+    content: unknown[];
+} | undefined;
+/**
+ * @param {unknown} item
+ * @returns {number | undefined}
+ */
+export declare function estimateBudgetItem(item: unknown): number | undefined;
+/** @param {unknown} maxChars */
+export declare function portableTokenCeiling(maxChars: unknown): number | undefined;
+/** @param {string} message */
+export declare function portableBudgetError(message: string): Error & {
+    code: string;
+};

package/lib/types/transport.d.ts

@@ -0,0 +1,20 @@
+type AbortLike = Pick<AbortSignal, "aborted" | "reason" | "addEventListener">;
+type RetryOptions = {
+    maxAttempts?: number;
+    maxResponseBytes?: number;
+};
+type SseRetryOptions<T = Response> = RetryOptions & {
+    consume?: (response: Response, options: {
+        requestSignal?: AbortSignal;
+    }) => Promise<T>;
+};
+type JsonRequestBody = Record<string, unknown>;
+type SseRequestBody = Record<string, unknown>;
+export declare function abortIfNeeded(signal: AbortLike | undefined): void;
+export declare function fetchJsonWithRetry(url: string | URL | Request, body: JsonRequestBody, headers: HeadersInit | undefined, signal: AbortSignal | undefined, timeoutMs?: number | undefined, options?: RetryOptions): Promise<any>;
+export declare function fetchSseWithRetry<T = Response>(url: string | URL | Request, body: SseRequestBody, headers: HeadersInit | undefined, signal: AbortSignal | undefined, timeoutMs?: number | undefined, options?: SseRetryOptions<T>): Promise<T>;
+export declare function consumeSse(response: Response, onEvent: (event: unknown) => void, options?: {
+    signal?: AbortSignal;
+    maxResponseBytes?: number;
+}): Promise<void>;
+export {};

package/lib/types/web-run-output.d.ts

@@ -0,0 +1,29 @@
+export interface WebRunLink {
+    id: number;
+    label: string;
+    domain?: string;
+}
+export interface WebRunLine {
+    text: string;
+    heading?: number;
+    line?: number;
+    page?: number;
+    pageEnd?: number;
+}
+export interface WebRunBlock {
+    title?: string;
+    url?: string;
+    references: string[];
+    links: WebRunLink[];
+    metadata: string[];
+    lines: WebRunLine[];
+}
+export declare function parseWebRunOutput(output: string): WebRunBlock[];
+export declare function outputLineRange(blocks: WebRunBlock[]): {
+    first: number;
+    last: number;
+} | undefined;
+export declare function outputDomains(blocks: WebRunBlock[]): string[];
+export declare function outputLinks(blocks: WebRunBlock[]): WebRunLink[];
+export declare function outputPdfRefs(blocks: WebRunBlock[]): string[];
+export declare function blockPlainText(block: Pick<WebRunBlock, "lines">): string;