@cleocode/core 2026.6.13 → 2026.6.15

package/dist/llm/transports/codex-responses.d.ts

@@ -1,25 +1,32 @@
 /**
- * CodexResponsesTransport — OpenAI Responses API transport.
+ * CodexResponsesTransport — OpenAI Responses API transport (raw-fetch variant).
  *
- * Implements {@link LlmTransport} for providers that expose the OpenAI
- * Responses API (`openai.responses.create`), including:
- * - OpenAI (Codex CLI models, GPT-4.1, o-series)
- * - xAI (grok-* models via Responses-compatible endpoints)
+ * Implements {@link LlmTransport} for the ChatGPT Codex backend
+ * (`https://chatgpt.com/backend-api/codex/responses`) and any provider that
+ * speaks a compatible Responses-API SSE protocol (xAI grok-via-responses).
  *
- * Key behavioral differences from ChatCompletionsTransport:
- * - Input uses the `input` array of ResponseInputItem (not `messages`).
- * - Tools use `{type: 'function', name, description, parameters}` shape.
- * - Tool results use `{type: 'function_call_output', call_id, output}` items.
- * - The system prompt goes in `instructions`, not a system message.
- * - Response text is extracted from `output_text` shortcut or by scanning
- *   `output` for `{type: 'message'}` items.
- * - Tool calls come from `output` items of `{type: 'function_call'}`.
- * - Usage is in `response.usage.input_tokens` / `output_tokens`.
+ * ## Wire shape (mirrored from @earendil-works/pi-ai 0.78.x — imports banned)
  *
- * Parity gaps vs ChatCompletions are documented inline with:
- * `// PARITY GAP: <feature> not yet supported by OpenAI Responses API`
+ * Unlike the previous OpenAI-SDK-based implementation, this transport uses
+ * **raw `fetch`** to control every request header.  The Codex backend rejects
+ * requests that carry the SDK's default `Accept: application/json` header or
+ * that omit `store: false` in the body.
+ *
+ * Mandatory request headers:
+ * - `Authorization: Bearer <token>`
+ * - `chatgpt-account-id: <jwt claim>`
+ * - `originator: codex_cli_rs` (set by buildCodexOAuthHeaders)
+ * - `OpenAI-Beta: responses=experimental`
+ * - `accept: text/event-stream`  (always — backend mandates stream:true on every request)
+ * - `content-type: application/json`
+ *
+ * Mandatory body fields:
+ * - `model`, `input`, `instructions`
+ * - `store: false`                 (codex backend rejects store:true or absent)
+ * - `stream: true`                (always — the Codex backend rejects stream:false)
  *
  * @module llm/transports/codex-responses
+ * @task T11985
  * @task T9311
  * @epic T9261 (T-LLM-CRED-CENTRALIZATION Phase 5)
  * @see ADR-072 §LlmTransport — pure wire level
@@ -31,11 +38,13 @@ import type { ModelTransport } from '@cleocode/contracts/operations/llm.js';
 /**
  * Options accepted by {@link CodexResponsesTransport}.
  *
- * `baseUrl` overrides the default OpenAI API endpoint. Required when serving
- * xAI (use `'https://api.x.ai/v1'`) or any other Responses-compatible shim.
+ * `baseUrl` overrides the default endpoint. Required when serving xAI (use
+ * `'https://api.x.ai/v1'`) or any other Responses-compatible shim.
  *
- * `defaultHeaders` carries extra HTTP headers merged into every SDK request.
- * xAI uses `x-grok-conv-id` for KV-cache affinity.
+ * `defaultHeaders` carries extra HTTP headers merged into every request.
+ * For Codex OAuth callers this should include at minimum
+ * `Authorization`, `chatgpt-account-id`, and `originator` (built by
+ * {@link buildCodexOAuthHeaders}).
  */
 export interface CodexResponsesTransportOptions {
     /**
@@ -47,31 +56,35 @@ export interface CodexResponsesTransportOptions {
     apiKey: string;
     /** Override base URL for non-OpenAI providers (no trailing slash). */
     baseUrl?: string;
-    /** Extra headers merged into every SDK request. */
+    /** Extra headers merged into every request. */
     defaultHeaders?: Record<string, string>;
 }
 /**
- * Transport for providers that expose the OpenAI Responses API.
+ * Transport for providers that expose the OpenAI Responses API via raw fetch.
  *
- * Wraps `openai.responses.create()` and normalizes requests/responses to/from
- * the provider-neutral {@link LlmTransport} interface.
+ * Uses native `fetch` (not the OpenAI SDK) so that the `Accept` header,
+ * `store: false` body field, and `OpenAI-Beta` header can all be set
+ * explicitly — the OpenAI SDK hardcodes `Accept: application/json` and omits
+ * `store`, both of which cause the Codex ChatGPT backend to return a 400.
  *
- * Input items are built by {@link _buildInputItems}, which converts
- * {@link TransportMessage} arrays into the Responses API `input` format.
- * Multi-turn tool replay is handled by injecting `function_call_output`
- * items when a prior `assistant` turn carries tool calls.
+ * SSE stream parsing mirrors the pi-ai 0.78.x reference implementation
+ * (`@earendil-works/pi-ai/dist/providers/openai-codex-responses.js`) —
+ * imports from that package are banned; the wire shape is transcribed here.
  *
  * @example
  * ```ts
  * const transport = new CodexResponsesTransport({
  *   provider: 'openai',
- *   apiKey: process.env.OPENAI_API_KEY!,
- * });
- * const response = await transport.complete({
- *   model: 'codex-mini-latest',
- *   messages: [{ role: 'user', content: 'Write a fizzbuzz.' }],
- *   maxTokens: 1024,
+ *   apiKey: process.env.CODEX_OAUTH_TOKEN!,
+ *   defaultHeaders: buildCodexOAuthHeaders(process.env.CODEX_OAUTH_TOKEN!),
  * });
+ * for await (const delta of transport.stream({
+ *   model: 'gpt-5.5',
+ *   messages: [{ role: 'user', content: 'Reply with exactly: pong' }],
+ *   maxTokens: 64,
+ * }, {})) {
+ *   process.stdout.write(delta.text);
+ * }
  * ```
  */
 export declare class CodexResponsesTransport implements LlmTransport {
@@ -86,21 +99,31 @@ export declare class CodexResponsesTransport implements LlmTransport {
      * @see ADR-072 §Type lock-in
      */
     readonly apiMode: ApiMode;
-    /** Underlying OpenAI SDK client. */
-    private readonly _client;
+    /** API key / OAuth bearer token. */
+    private readonly _apiKey;
+    /**
+     * Resolved endpoint URL (the full `/codex/responses` path).
+     * Derived once at construction so the URL normalisation runs once.
+     */
+    private readonly _endpointUrl;
+    /** Extra headers merged into every request (auth, originator, etc.). */
+    private readonly _defaultHeaders;
     /**
      * Construct a CodexResponsesTransport.
      *
-     * @param opts - Construction options including provider, API key, and
-     *   optional base URL / default headers.
+     * @param opts - Construction options: provider, API key, optional base URL
+     *   and default headers (auth + Cloudflare-bypass headers for OAuth callers).
      */
     constructor(opts: CodexResponsesTransportOptions);
     /**
-     * Execute a single completion using the OpenAI Responses API.
+     * Execute a single (non-streaming) completion using the Responses API.
      *
-     * Maps the provider-neutral {@link TransportRequest} to
-     * `openai.responses.create()` and normalizes the {@link Response} into a
-     * {@link NormalizedResponse}.
+     * The Codex ChatGPT backend mandates `stream: true` on every request and
+     * returns `400 {"detail":"Stream must be set to true"}` for `stream: false`.
+     * This method therefore always sends `stream: true` with
+     * `Accept: text/event-stream`, internally consumes the SSE stream, and
+     * aggregates text deltas + tool calls + usage into a {@link NormalizedResponse}
+     * — identical to calling `stream()` and collecting all chunks.
      *
      * @param request - Provider-neutral request parameters.
      * @param _ctx - Transport context (unused; `request.signal` handles abort).
@@ -108,11 +131,17 @@ export declare class CodexResponsesTransport implements LlmTransport {
      */
     complete(request: TransportRequest, _ctx?: TransportContext): Promise<NormalizedResponse>;
     /**
-     * Stream a completion using the OpenAI Responses API SSE stream.
+     * Stream a completion using the Responses API SSE stream.
      *
      * Yields {@link NormalizedDelta} chunks from `response.output_text.delta`
-     * events. The final delta is emitted when `response.completed` fires and
-     * carries `stopReason` and `usage`.
+     * events parsed from the raw SSE stream.  The final delta carries
+     * `stopReason` and `usage` from `response.completed`.
+     *
+     * Wire shape:
+     * - `store: false` (required — codex backend rejects absent or true)
+     * - `stream: true`
+     * - `Accept: text/event-stream`
+     * - `OpenAI-Beta: responses=experimental`
      *
      * @param request - Provider-neutral request parameters.
      * @param _ctx - Transport context (unused; `request.signal` handles abort).
@@ -120,56 +149,50 @@ export declare class CodexResponsesTransport implements LlmTransport {
      */
     stream(request: TransportRequest, _ctx: TransportContext): AsyncIterable<NormalizedDelta>;
     /**
-     * Convert provider-neutral messages to the Responses API `input` array.
-     *
-     * Mapping rules:
-     * - `user` / `assistant` string messages → `EasyInputMessage` with `type:'message'`.
-     * - `user` / `assistant` multimodal blocks → content list with `input_text` /
-     *   `input_image` items.
-     * - `tool` messages (role=`'tool'`) → `function_call_output` items using
-     *   `toolUseId` as `call_id`.
+     * Build the HTTP headers for a Codex request.
      *
-     * Multi-turn tool replay: when an assistant message's raw content is a
-     * `function_call` JSON envelope (injected by the agent loop after a tool
-     * call round-trip), the item is converted to a `function_call` input item
-     * so the Responses API can continue the conversation.
+     * Merges the auth/cloudflare headers from `_defaultHeaders` with the
+     * mandatory Codex-specific headers:
+     * - `OpenAI-Beta: responses=experimental`
+     * - `content-type: application/json`
+     * - `accept: text/event-stream` (always — both complete() and stream() use SSE)
      *
-     * @param request - Full transport request.
-     * @returns Responses API input items array.
-     */
-    private _buildInputItems;
-    /**
-     * Convert provider-neutral tool definitions to the Responses API
-     * `{type: 'function', name, description, parameters, strict}` shape.
+     * The Authorization header is injected only if not already present in
+     * `_defaultHeaders` (OAuth callers pre-set it via buildCodexOAuthHeaders).
      *
-     * @param tools - Provider-neutral tool definitions (may be undefined).
-     * @returns Responses API tool objects, or empty array.
+     * @param streaming - Whether this is a streaming (SSE) or completion call.
+     * @returns Plain string record of all request headers.
      */
-    private _buildTools;
+    private _buildHeaders;
     /**
-     * Normalize an OpenAI Responses API {@link Response} into a
-     * {@link NormalizedResponse}.
+     * Build the JSON request body for a Codex Responses API call.
      *
-     * Mapping rules:
-     * - `content` — from `response.output_text` shortcut (SDK convenience
-     *   property that aggregates all output_text parts).
-     * - `toolCalls` — from `output` items of `type: 'function_call'`.
-     * - `stopReason` — from `response.status` (completed / failed / incomplete).
-     * - `usage` — `input_tokens` → `inputTokens`, `output_tokens` → `outputTokens`.
-     * - `cachedTokens` — from `usage.input_tokens_details.cached_tokens`.
-     * - `raw` — unmodified SDK response.
+     * Mandatory fields per the Codex backend:
+     * - `store: false`   — backend rejects absent or `true`.
+     * - `instructions`   — system prompt (defaulting to empty string when absent).
+     * - `input`          — array of Responses API input items.
      *
-     * @param response - Raw Responses API response object.
-     * @param requestedModel - Model string from the originating request.
-     * @returns Normalized response envelope.
+     * @param request - Provider-neutral request.
+     * @param streaming - Whether to enable SSE streaming.
+     * @returns Serialisable request body.
      */
-    private _normalize;
-    /**
-     * Normalize OpenAI Responses API usage into {@link NormalizedUsage}.
-     *
-     * @param usage - Raw usage object (may be null when the API omits it).
-     * @returns Normalized usage with optional `cachedTokens`.
-     */
-    private _normalizeUsage;
+    private _buildBody;
 }
+/**
+ * Resolve the full Responses API endpoint URL from an optional base URL.
+ *
+ * Mirrors the `resolveCodexUrl` logic from pi-ai 0.78.x so the same base URL
+ * variants work:
+ * - `https://chatgpt.com/backend-api`           → `.../codex/responses`
+ * - `https://chatgpt.com/backend-api/codex`     → `.../codex/responses`
+ * - `https://chatgpt.com/backend-api/codex/responses` → unchanged
+ * - `undefined` (no override)                   → ChatGPT Codex default
+ *
+ * For non-ChatGPT providers (xAI, custom shims) the raw baseUrl is
+ * appended with `/responses` when it doesn't already end with `/responses`.
+ *
+ * @param baseUrl - Optional override base URL (no trailing slash).
+ * @returns The fully resolved endpoint URL.
+ */
+export declare function resolveCodexUrl(baseUrl: string | undefined): string;
 //# sourceMappingURL=codex-responses.d.ts.map

package/dist/llm/transports/codex-responses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex-responses.d.ts","sourceRoot":"","sources":["../../../src/llm/transports/codex-responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC/F,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAKlB,gBAAgB,EAGjB,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAQ5E;;;;;;;;GAQG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,uBAAwB,YAAW,YAAY;IAC1D;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAA8B;IAEvD,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;;;OAKG;gBACS,IAAI,EAAE,8BAA8B;IAShD;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyB/F;;;;;;;;;;OAUG;IACI,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAAC,eAAe,CAAC;IA8EhG;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAiBnB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,UAAU;IA2BlB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAexB"}
+{"version":3,"file":"codex-responses.d.ts","sourceRoot":"","sources":["../../../src/llm/transports/codex-responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC/F,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAKlB,gBAAgB,EAGjB,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAM5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAsBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,uBAAwB,YAAW,YAAY;IAC1D;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAA8B;IAEvD,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IAEzD;;;;;OAKG;gBACS,IAAI,EAAE,8BAA8B;IAWhD;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA8G/F;;;;;;;;;;;;;;;;OAgBG;IACI,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAAC,eAAe,CAAC;IA4EhG;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,aAAa;IAerB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,UAAU;CAgBnB;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAOnE"}