@linxiraos/pi-ai 1.0.0

package/dist/types/providers/openai-codex/request-transformer.d.ts

@@ -0,0 +1,109 @@
+import type { Model } from "../../types.js";
+/** Reasoning replay scope for the Codex Responses API (`reasoning.context`). */
+export type CodexReasoningContext = "auto" | "current_turn" | "all_turns";
+/** User-facing effort levels accepted by Codex request options. */
+type CodexCallerEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export interface ReasoningConfig {
+    effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    summary?: "auto" | "concise" | "detailed";
+    context?: CodexReasoningContext;
+    /** Pro reasoning serving mode (gpt-5.6+ catalog pro aliases). */
+    mode?: "pro";
+}
+export interface CodexRequestOptions {
+    /** User-facing effort; maps 1:1 onto the wire tier of the same name. */
+    reasoningEffort?: CodexCallerEffort | "none";
+    reasoningSummary?: ReasoningConfig["summary"] | null;
+    /** Explicit `reasoning.context` override. Omitted by default; Responses Lite forces `all_turns` as required by that transport. */
+    reasoningContext?: CodexReasoningContext;
+    textVerbosity?: "low" | "medium" | "high";
+    include?: string[];
+    /**
+     * Responses Lite transport override; defaults to the model's
+     * `useResponsesLite`. Lite moves instructions/tools into input items,
+     * strips image detail, and disables parallel tool calling (codex-rs
+     * `use_responses_lite`).
+     */
+    responsesLite?: boolean;
+}
+export interface InputItem {
+    id?: string | null;
+    type?: string | null;
+    role?: string;
+    content?: unknown;
+    call_id?: string | null;
+    name?: string;
+    output?: unknown;
+    arguments?: unknown;
+    action?: unknown;
+    actions?: unknown;
+    pending_safety_checks?: unknown;
+    acknowledged_safety_checks?: unknown;
+    /** `additional_tools` developer item payload (Responses Lite). */
+    tools?: unknown;
+}
+export interface RequestBody {
+    model: string;
+    store?: boolean;
+    stream?: boolean;
+    instructions?: string;
+    input?: InputItem[];
+    tools?: unknown;
+    tool_choice?: unknown;
+    /** Concurrent reasoning-summary delivery (codex-rs `StreamOptions`). */
+    stream_options?: {
+        reasoning_summary_delivery: "sequential_cutoff";
+    };
+    reasoning?: Partial<ReasoningConfig>;
+    text?: {
+        verbosity?: "low" | "medium" | "high";
+    };
+    include?: string[];
+    prompt_cache_key?: string;
+    prompt_cache_retention?: "in_memory" | "24h";
+    client_metadata?: Record<string, string>;
+    max_output_tokens?: number;
+    max_completion_tokens?: number;
+    service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;
+    [key: string]: unknown;
+}
+/**
+ * Resolve whether a Codex request uses the Responses Lite transport: an
+ * explicit option wins, then the `PI_CODEX_RESPONSES_LITE` env override
+ * (`1`/`true` forces Lite, `0`/`false` forces the full Responses body),
+ * otherwise the model's catalog flag (codex-rs `model_info.use_responses_lite`)
+ * decides.
+ */
+export declare function resolveCodexResponsesLite(model: Model<"openai-codex-responses">, requested: boolean | undefined): boolean;
+/**
+ * Structural view of a Responses-style body mutated by the Lite rewrite.
+ * Loose (`unknown`) property types let the turn transformer (`RequestBody`)
+ * and the agent's remote-compaction payloads reuse one shaper.
+ */
+export interface CodexLiteShapedBody {
+    instructions?: unknown;
+    tools?: unknown;
+    tool_choice?: unknown;
+    input?: unknown;
+    parallel_tool_calls?: unknown;
+}
+/**
+ * Applies the Responses Lite body contract in place (codex-rs
+ * `build_responses_request` with `use_responses_lite`): strips pinned image
+ * detail, forces parallel tool calling off, moves tools into a leading
+ * `additional_tools` developer item and the base instructions into a
+ * developer message, then omits top-level `instructions`/`tools`. Because the
+ * rewrite removes top-level `tools`, a forced hosted-tool choice (e.g.
+ * `{ type: "web_search" }`) would leave the backend unable to validate the
+ * choice against a tools collection and it rejects the request with HTTP 400
+ * (#5771). Native computer and named-function choices preserve exact forcing
+ * by isolating the selected declaration and using `"required"`; other hosted
+ * choices fall back to `"auto"`. Explicit string constraints such as `"none"`
+ * and `"required"` remain valid. Shared by normal turns and both remote-compaction
+ * paths — codex-rs routes `/responses/compact` through the same builder.
+ */
+export declare function applyCodexResponsesLiteShape(body: CodexLiteShapedBody): void;
+export declare function transformRequestBody(body: RequestBody, model: Model<"openai-codex-responses">, options?: CodexRequestOptions, prompt?: {
+    developerMessages: string[];
+}): Promise<RequestBody>;
+export {};

package/dist/types/providers/openai-codex/response-handler.d.ts

@@ -0,0 +1,26 @@
+import { ProviderHttpError } from "../../error/index.js";
+export type CodexRateLimit = {
+    used_percent?: number;
+    window_minutes?: number;
+    resets_at?: number;
+};
+export type CodexRateLimits = {
+    primary?: CodexRateLimit;
+    secondary?: CodexRateLimit;
+};
+export type CodexErrorInfo = {
+    message: string;
+    status: number;
+    /** Machine-readable error code (`error.code` or `error.type` from the response body), when present. */
+    code?: string;
+    friendlyMessage?: string;
+    rateLimits?: CodexRateLimits;
+    raw?: string;
+};
+/** Non-2xx response from the Codex backend, with the parsed body retained. */
+export declare class CodexApiError extends ProviderHttpError {
+    readonly info: CodexErrorInfo;
+    constructor(info: CodexErrorInfo, headers?: Headers);
+    static fromResponse(response: Response): Promise<CodexApiError>;
+}
+export declare function parseCodexError(response: Response): Promise<CodexErrorInfo>;

package/dist/types/providers/openai-codex-responses.d.ts

@@ -0,0 +1,238 @@
+import type { CodexCompactionContext, CodexCompactionRequestContext, Context, Model, ProviderSessionState, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoice } from "../types.js";
+import { type CodexLiteShapedBody, type CodexReasoningContext, type RequestBody } from "./openai-codex/request-transformer.js";
+import type { ResponseInput } from "./openai-responses-wire.js";
+export interface OpenAICodexResponsesOptions extends StreamOptions {
+    reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    reasoningSummary?: "auto" | "concise" | "detailed" | null;
+    /** Explicit `reasoning.context` replay scope. Omitted by default so Codex applies its native request policy. */
+    reasoningContext?: CodexReasoningContext;
+    textVerbosity?: "low" | "medium" | "high";
+    codexMode?: boolean;
+    toolChoice?: ToolChoice;
+    preferWebsockets?: boolean;
+    serviceTier?: ServiceTier;
+    /**
+     * Responses Lite transport override; defaults to the model's catalog
+     * `useResponsesLite` flag (codex-rs `use_responses_lite`). Sends
+     * `x-openai-internal-codex-responses-lite: true` on HTTP requests and on the
+     * WebSocket upgrade (the marker is connection-scoped there, so lite and
+     * non-lite turns never share a pooled socket), moves instructions/tools
+     * into input items, strips image detail, and disables parallel tool
+     * calling — mirroring codex-rs.
+     */
+    responsesLite?: boolean;
+    /**
+     * Additional fields embedded in the canonical
+     * `client_metadata["x-codex-turn-metadata"]` JSON blob. Reserved identity
+     * keys are ignored; extras are never emitted as top-level metadata fields.
+     */
+    clientMetadata?: Record<string, string>;
+    /**
+     * Turn id of the initiating (parent) Codex turn for nested requests such as
+     * subagent spawns (codex-rs `parent_turn_id`, #35835). Emitted both as the
+     * flat `client_metadata.parent_turn_id` key and inside the
+     * `x-codex-turn-metadata` JSON blob; blank values are ignored. The key is
+     * reserved: `clientMetadata` extras cannot supply it.
+     */
+    parentTurnId?: string;
+    /**
+     * Invoked when the server streams a `response.metadata` event carrying
+     * ChatGPT moderation metadata (`metadata.openai_chatgpt_moderation_metadata`)
+     * for first-party presentation parity. Diagnostic observer: failures are
+     * swallowed and must not alter the stream.
+     */
+    onModerationMetadata?: (metadata: unknown) => void;
+}
+/** Raw V2 compaction body accepted by the Codex transport selector. */
+export interface OpenAICodexCompactionBody extends CodexLiteShapedBody {
+    model: string;
+    [key: string]: unknown;
+}
+/** Transport controls for a provider-native Codex V2 compaction stream. */
+export interface OpenAICodexCompactionStreamOptions extends OpenAICodexResponsesOptions {
+    apiKey: string;
+}
+/** Inputs for synthesizing Codex request identity outside the normal stream path. */
+export interface OpenAICodexCompatibilityMetadataOptions {
+    sessionId?: string;
+    providerSessionState?: Map<string, ProviderSessionState>;
+    requestKind: OpenAICodexRequestKind;
+    compaction?: CodexCompactionRequestContext;
+    startNewTurn?: boolean;
+    turnStartedAtUnixMs?: number;
+    clientMetadata?: Readonly<Record<string, string>>;
+    /** Parent Codex turn id for nested requests; see {@link OpenAICodexResponsesOptions.parentTurnId}. */
+    parentTurnId?: string;
+    /** Add the direct installation header required by `/responses/compact`. */
+    includeInstallationHeader?: boolean;
+}
+/** Canonical Codex body metadata and compatibility headers for one request. */
+export interface OpenAICodexCompatibilityMetadata {
+    clientMetadata: Record<string, string>;
+    headers: Record<string, string>;
+}
+/** Live Codex session state to preserve after a successful history rewrite. */
+export interface OpenAICodexCompactionResetOptions {
+    providerSessionState?: Map<string, ProviderSessionState>;
+    sessionId?: string;
+    compaction: CodexCompactionContext;
+}
+/** Add the selected wire implementation to one logical compaction context. */
+export declare function createOpenAICodexCompactionRequestContext(options: {
+    context: CodexCompactionContext | undefined;
+    implementation: "responses" | "responses_compaction_v2" | "responses_compact";
+}): CodexCompactionRequestContext | undefined;
+/**
+ * Host integration boundary for just-in-time `x-oai-attestation` header
+ * values (codex-rs `AttestationProvider`). Resolves to the full header value
+ * — an `{"v":1,"s":0,"t":"v1.…"}` envelope — or `undefined` when no
+ * attestation should be sent.
+ */
+export type CodexAttestationProvider = () => Promise<string | undefined>;
+/**
+ * Install the process-wide attestation hook consulted for upstream Codex
+ * requests (codex-rs stores its provider on `ModelClient` construction). The
+ * hook is only consulted for ChatGPT-OAuth credentials and runs just-in-time
+ * per request; WebSocket handshakes resolve once per connection because the
+ * header is connection-scoped there.
+ */
+export declare function setCodexAttestationProvider(provider: CodexAttestationProvider | undefined): void;
+/**
+ * Resolve the `x-oai-attestation` header value for one upstream request.
+ * Gated on ChatGPT-OAuth credentials (a Codex JWT carries `chatgpt_account_id`;
+ * codex-rs gates on `auth.is_chatgpt_auth()`). A throwing hook degrades to no
+ * header rather than failing the request.
+ */
+export declare function getCodexAttestationHeader(accountId: string | undefined): Promise<string | undefined>;
+type CodexTransport = "sse" | "websocket";
+/** Shape of the Codex request sent on the latest provider turn. */
+export interface OpenAICodexTurnRequestDiagnostics {
+    transport: "sse" | "websocket";
+    previousResponseIdPresent: boolean;
+    inputItemCount: number;
+    inputItemTypes: string[];
+    firstInputItemType?: string;
+    inputJsonBytes: number;
+    promptCacheKey?: string;
+    toolsHash?: string;
+    optionsHash: string;
+    canAppendBeforeRequest: boolean;
+}
+/** Raw provider usage plus the normalized buckets OMP displays for the latest Codex turn. */
+export interface OpenAICodexTurnUsageDiagnostics {
+    rawInputTokens: number;
+    rawCachedTokens: number;
+    rawUncachedTokens: number;
+    rawOutputTokens: number;
+    rawTotalTokens?: number;
+    rawOrchestrationInputTokens?: number;
+    rawOrchestrationCachedTokens?: number;
+    rawOrchestrationOutputTokens?: number;
+    displayedInputTokens: number;
+    displayedOutputTokens: number;
+    displayedCacheReadTokens: number;
+    displayedCacheWriteTokens: number;
+    displayedTotalTokens: number;
+    displayedOrchestrationInputTokens: number;
+    displayedOrchestrationCacheReadTokens: number;
+    displayedOrchestrationOutputTokens: number;
+}
+/** Latest Codex turn request/usage diagnostics exposed to debug UIs and tests. */
+export interface OpenAICodexTurnDiagnostics {
+    request: OpenAICodexTurnRequestDiagnostics;
+    usage?: OpenAICodexTurnUsageDiagnostics;
+}
+/**
+ * Per-session request-shape counters and latest turn diagnostics. Despite the
+ * name, these cover both transports.
+ */
+export interface OpenAICodexWebSocketDebugStats {
+    fullContextRequests: number;
+    deltaRequests: number;
+    lastInputItems: number;
+    lastDeltaInputItems?: number;
+    lastPreviousResponseId?: string;
+    lastTurn?: OpenAICodexTurnDiagnostics;
+}
+/** Request classification encoded in Codex turn metadata. */
+export type OpenAICodexRequestKind = "turn" | "prewarm" | "compaction";
+/**
+ * Synthesize Codex request identity for raw provider routes such as remote
+ * compaction while reusing the live session's thread, window, and turn.
+ */
+export declare function createOpenAICodexCompatibilityMetadata(options: OpenAICodexCompatibilityMetadataOptions): OpenAICodexCompatibilityMetadata;
+/**
+ * Invalidate Codex history-dependent transport state after compaction while
+ * retaining the session identity and live connection.
+ */
+export declare function resetOpenAICodexHistoryAfterCompaction(options: OpenAICodexCompactionResetOptions): void;
+/** @internal Exported for tests. */
+export declare function normalizeCodexToolChoice(choice: ToolChoice | undefined, tools?: Tool[], model?: Model<"openai-codex-responses">): string | Record<string, unknown> | undefined;
+/** @internal Exported for tests. */
+export declare function buildTransformedCodexRequestBody(model: Model<"openai-codex-responses">, context: Context, options: OpenAICodexResponsesOptions | undefined, promptCacheKey?: string | undefined): Promise<RequestBody>;
+/**
+ * Open a provider-native V2 compaction stream through Codex's WebSocket-first
+ * transport, replaying WebSocket transport failures over SSE.
+ */
+export declare function openCodexCompactionEventStream(model: Model<"openai-codex-responses">, body: OpenAICodexCompactionBody, options: OpenAICodexCompactionStreamOptions): Promise<AsyncGenerator<Record<string, unknown>>>;
+export declare const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses">;
+export declare function prewarmOpenAICodexResponses(model: Model<"openai-codex-responses">, options?: Pick<OpenAICodexResponsesOptions, "apiKey" | "headers" | "sessionId" | "signal" | "preferWebsockets" | "providerSessionState" | "responsesLite">): Promise<void>;
+export interface OpenAICodexTransportDetails {
+    websocketPreferred: boolean;
+    lastTransport?: CodexTransport;
+    websocketDisabled: boolean;
+    websocketConnected: boolean;
+    fallbackCount: number;
+    canAppend: boolean;
+    prewarmed: boolean;
+    hasSessionState: boolean;
+    hasTurnState: boolean;
+    lastFallbackAt?: number;
+}
+export declare function getOpenAICodexWebSocketDebugStats(model: Model<"openai-codex-responses">, options?: {
+    sessionId?: string;
+    baseUrl?: string;
+    providerSessionState?: Map<string, ProviderSessionState>;
+}): OpenAICodexWebSocketDebugStats | undefined;
+export declare function getOpenAICodexTransportDetails(model: Model<"openai-codex-responses">, options?: {
+    sessionId?: string;
+    baseUrl?: string;
+    preferWebsockets?: boolean;
+    providerSessionState?: Map<string, ProviderSessionState>;
+}): OpenAICodexTransportDetails;
+/** Resolve a Codex Responses endpoint exactly as the chat and compaction transports do. */
+export declare function resolveCodexResponsesUrl(baseUrl: string | undefined): string;
+declare function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput;
+/** @internal Exported for tests. */
+export { convertMessages as convertCodexResponsesMessages };
+type CodexToolPayload = {
+    type: "computer";
+    name?: never;
+} | {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    strict?: boolean;
+} | {
+    type: "custom";
+    name: string;
+    description: string;
+    format: {
+        type: "grammar";
+        syntax: "lark" | "regex";
+        definition: string;
+    };
+};
+/** @internal Exported for tests. */
+export declare function convertOpenAICodexResponsesTools(tools: Tool[], model: Model<"openai-codex-responses">): CodexToolPayload[];
+export declare class CodexWebSocketTransportError extends Error {
+    constructor(detail: string);
+}
+declare class CodexProviderStreamError extends Error {
+    readonly retryable: boolean;
+    readonly code?: string;
+    constructor(message: string, retryable: boolean, code?: string);
+}
+export declare function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean;
+export declare function createCodexProviderStreamError(rawEvent: Record<string, unknown>): CodexProviderStreamError;

package/dist/types/providers/openai-completions.d.ts

@@ -0,0 +1,48 @@
+import type { ResolvedOpenAICompat } from "@linxiraos/pi-catalog/types";
+import type { AssistantMessage, Context, Model, ServiceTier, StreamFunction, StreamOptions, ToolChoice } from "../types.js";
+import type { ChatCompletionMessageParam } from "./openai-chat-wire.js";
+import { type OpenAIPromptCacheOptions } from "./openai-shared.js";
+export { applyOpenRouterRoutingVariant } from "./openai-shared.js";
+/**
+ * Identify "real progress" stream chunks vs. keepalives, role-only preambles,
+ * and empty `{choices:[]}` no-ops emitted by some OpenAI-compatible endpoints.
+ * Without this filter, every keepalive resets `iterateWithIdleTimeout`'s
+ * deadline, so a provider that streams nothing but pings keeps the watchdog
+ * asleep indefinitely — observed against z.ai/GLM via OpenRouter where a
+ * subagent stalled for hours with no error surfaced.
+ *
+ * A chunk counts as progress when it carries terminal usage, a finish reason,
+ * or a model-produced delta (content / tool calls / reasoning / refusal).
+ * Role-only `delta: { role: "assistant" }` preambles do NOT count; we want the
+ * (longer) first-event timeout to keep governing until real output appears.
+ */
+export declare function isOpenAICompletionsProgressChunk(chunk: unknown): boolean;
+export interface OpenAICompletionsOptions extends StreamOptions {
+    toolChoice?: ToolChoice;
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    /** Force-disable reasoning where supported, or request the lowest effort on generic effort endpoints. */
+    disableReasoning?: boolean;
+    serviceTier?: ServiceTier;
+    /** @internal True when maxTokens came from the caller, not the model default. */
+    maxTokensExplicit?: boolean;
+    /**
+     * Routing-variant suffix appended to OpenRouter model IDs when none is
+     * already present (`anthropic/claude-haiku-latest` → `…:nitro`). Common
+     * values: `"nitro"`, `"floor"`, `"online"`, `"exacto"`. Ignored when the
+     * resolved `model.id` already contains a colon-suffix after the last
+     * provider segment (explicit `:nitro` in the selector or a catalog entry
+     * with the variant baked in).
+     */
+    openrouterVariant?: string;
+    /** Opt-in GPT-5.6+ prompt-cache policy. Unsupported explicit mode fails locally. */
+    promptCache?: OpenAIPromptCacheOptions;
+}
+/**
+ * Public entry: wrap the single-attempt streamer with bounded empty-completion
+ * retries — flaky gateways occasionally 200 with `delta: {}` + `finish_reason:
+ * "stop"` and no usage, which would otherwise stall the agent loop. Shared with
+ * the Anthropic provider via `withEmptyCompletionRetry`.
+ */
+export declare const streamOpenAICompletions: StreamFunction<"openai-completions">;
+export declare function parseChunkUsage(rawUsage: object, model: Model<"openai-completions">, premiumRequests: number | undefined): AssistantMessage["usage"];
+export declare function convertMessages(model: Model<"openai-completions">, context: Context, compat: ResolvedOpenAICompat): ChatCompletionMessageParam[];

package/dist/types/providers/openai-reasoning-fallback.d.ts

@@ -0,0 +1,25 @@
+import type { CapturedHttpErrorResponse } from "../utils/http-inspector.js";
+/** @internal */
+export type OpenAIReasoningEffortFallback = string | null;
+/** @internal */
+export interface OpenAIReasoningEffortFallbackState {
+    reasoningEffortFallbacks: Map<string, OpenAIReasoningEffortFallback>;
+}
+/** @internal */
+export declare function createOpenAIReasoningEffortFallbackState(): OpenAIReasoningEffortFallbackState;
+/** @internal */
+export declare function clearOpenAIReasoningEffortFallbackState(state: OpenAIReasoningEffortFallbackState): void;
+/** @internal */
+export declare function getOpenAIReasoningEffortFallback(state: OpenAIReasoningEffortFallbackState | undefined, key: string): OpenAIReasoningEffortFallback | undefined;
+/** @internal */
+export declare function rememberOpenAIReasoningEffortFallback(state: OpenAIReasoningEffortFallbackState | undefined, key: string, fallback: OpenAIReasoningEffortFallback): void;
+/** @internal */
+export declare function createOpenAIReasoningEffortFallbackKey(endpoint: "chat-completions" | "responses" | "azure-responses", baseUrl: string | undefined, wireModelId: string | undefined): string;
+/** @internal */
+export declare function readOpenAIReasoningEffort(params: unknown): string | undefined;
+/** @internal */
+export declare function applyOpenAIReasoningEffortFallback(params: unknown, fallback: OpenAIReasoningEffortFallback): boolean;
+/** @internal */
+export declare function resolveOpenAIReasoningEffortFallback(error: unknown, captured: CapturedHttpErrorResponse | undefined, params: unknown, options?: {
+    explicitDisable?: boolean;
+}): OpenAIReasoningEffortFallback | undefined;