@oh-my-pi/pi-ai 6.8.2 → 6.8.3

package/README.md

@@ -607,6 +607,28 @@ context.messages.push({ role: "user", content: "Please continue" });
 const continuation = await complete(model, context);
 ```
 
+### Common Stream Options
+
+All providers accept the base `StreamOptions` (in addition to provider-specific options):
+
+- `apiKey`: Override the provider API key
+- `headers`: Extra request headers merged on top of model-defined headers
+- `sessionId`: Provider-specific session identifier (prompt caching/routing)
+- `signal`: Abort in-flight requests
+- `onPayload`: Callback invoked with the provider request payload just before sending
+
+Example:
+
+```typescript
+const response = await complete(model, context, {
+	apiKey: "sk-live",
+	headers: { "X-Debug-Trace": "true" },
+	onPayload: (payload) => {
+		console.log("request payload", payload);
+	},
+});
+```
+
 ## APIs, Models, and Providers
 
 The library implements 4 API interfaces, each with its own streaming function and options:
@@ -987,6 +1009,15 @@ import {
 } from "@oh-my-pi/pi-ai";
 ```
 
+`loginOpenAICodex` accepts an optional `originator` value used in the OAuth flow:
+
+```typescript
+await loginOpenAICodex({
+	onAuth: ({ url }) => console.log(url),
+	originator: "my-cli",
+});
+```
+
 ### Login Flow Example
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "6.8.2",
+	"version": "6.8.3",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -17,7 +17,7 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-utils": "6.8.2",
+		"@oh-my-pi/pi-utils": "6.8.3",
 		"@anthropic-ai/sdk": "0.71.2",
 		"@aws-sdk/client-bedrock-runtime": "^3.968.0",
 		"@bufbuild/protobuf": "^2.10.2",

package/src/providers/amazon-bedrock.ts

@@ -93,14 +93,16 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				profile: options.profile,
 			});
 
-			const command = new ConverseStreamCommand({
+			const commandInput = {
 				modelId: model.id,
 				messages: convertMessages(context, model),
 				system: buildSystemPrompt(context.systemPrompt, model),
 				inferenceConfig: { maxTokens: options.maxTokens, temperature: options.temperature },
 				toolConfig: convertToolConfig(context.tools, options.toolChoice),
 				additionalModelRequestFields: buildAdditionalModelRequestFields(model, options),
-			});
+			};
+			options?.onPayload?.(commandInput);
+			const command = new ConverseStreamCommand(commandInput);
 
 			const response = await client.send(command, { abortSignal: options.signal });
 

package/src/providers/anthropic.ts

@@ -161,8 +161,9 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 		try {
 			const apiKey = options?.apiKey ?? getEnvApiKey(model.provider) ?? "";
 			const extraBetas = normalizeExtraBetas(options?.betas);
-			const { client, isOAuthToken } = createClient(model, apiKey, extraBetas, true);
+			const { client, isOAuthToken } = createClient(model, apiKey, extraBetas, true, options?.headers);
 			const params = buildParams(model, context, isOAuthToken, options);
+			options?.onPayload?.(params);
 			const anthropicStream = client.messages.stream({ ...params, stream: true }, { signal: options?.signal });
 			stream.push({ type: "start", partial: output });
 
@@ -420,6 +421,7 @@ function createClient(
 	apiKey: string,
 	extraBetas: string[],
 	stream: boolean,
+	extraHeaders?: Record<string, string>,
 ): { client: Anthropic; isOAuthToken: boolean } {
 	const oauthToken = isOAuthToken(apiKey);
 
@@ -438,7 +440,7 @@ function createClient(
 		isOAuth: oauthToken,
 		extraBetas: mergedBetas,
 		stream,
-		modelHeaders: model.headers,
+		modelHeaders: { ...(model.headers ?? {}), ...(extraHeaders ?? {}) },
 	});
 
 	const clientOptions: ConstructorParameters<typeof Anthropic>[0] = {

package/src/providers/cursor.ts

@@ -2027,6 +2027,8 @@ function buildGrpcRequest(
 		conversationId: state.conversationId,
 	});
 
+	options?.onPayload?.(runRequest);
+
 	// Tools are sent later via requestContext (exec handshake)
 
 	if (options?.customSystemPrompt) {

package/src/providers/google-gemini-cli.ts

@@ -410,6 +410,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			const endpoints = baseUrl ? [baseUrl] : isAntigravity ? ANTIGRAVITY_ENDPOINT_FALLBACKS : [DEFAULT_ENDPOINT];
 
 			const requestBody = buildRequest(model, context, projectId, options, isAntigravity);
+			options?.onPayload?.(requestBody);
 			const headers = isAntigravity ? ANTIGRAVITY_HEADERS : GEMINI_CLI_HEADERS;
 
 			const requestHeaders = {
@@ -418,6 +419,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				Accept: "text/event-stream",
 				...headers,
 				...(isClaudeThinkingModel(model.id) ? { "anthropic-beta": CLAUDE_THINKING_BETA_HEADER } : {}),
+				...(options?.headers ?? {}),
 			};
 			const requestBodyJson = JSON.stringify(requestBody);
 

package/src/providers/google-vertex.ts

@@ -85,6 +85,7 @@ export const streamGoogleVertex: StreamFunction<"google-vertex"> = (
 			const location = resolveLocation(options);
 			const client = createClient(model, project, location);
 			const params = buildParams(model, context, options);
+			options?.onPayload?.(params);
 			const googleStream = await client.models.generateContentStream(params);
 
 			stream.push({ type: "start", partial: output });

package/src/providers/google.ts

@@ -75,6 +75,7 @@ export const streamGoogle: StreamFunction<"google-generative-ai"> = (
 			const apiKey = options?.apiKey || getEnvApiKey(model.provider) || "";
 			const client = createClient(model, apiKey);
 			const params = buildParams(model, context, options);
+			options?.onPayload?.(params);
 			const googleStream = await client.models.generateContentStream(params);
 
 			stream.push({ type: "start", partial: output });

package/src/providers/openai-codex-responses.ts

@@ -55,6 +55,29 @@ const CODEX_MAX_RETRIES = 2;
 const CODEX_RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
 const CODEX_RETRY_DELAY_MS = 500;
 
+/** Fast deterministic hash to shorten long strings */
+function shortHash(str: string): string {
+	let h1 = 0xdeadbeef;
+	let h2 = 0x41c6ce57;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+	h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+	return (h2 >>> 0).toString(36) + (h1 >>> 0).toString(36);
+}
+
+function normalizeResponsesToolCallId(id: string): { callId: string; itemId: string } {
+	const [callId, itemId] = id.split("|");
+	if (callId && itemId) {
+		return { callId, itemId };
+	}
+	const hash = shortHash(id);
+	return { callId: `call_${hash}`, itemId: `item_${hash}` };
+}
+
 export const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses"> = (
 	model: Model<"openai-codex-responses">,
 	context: Context,
@@ -128,9 +151,15 @@ export const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses"
 			};
 
 			const transformedBody = await transformRequestBody(params, codexOptions, systemPrompt);
+			options?.onPayload?.(transformedBody);
 
 			const reasoningEffort = transformedBody.reasoning?.effort ?? null;
-			const headers = createCodexHeaders(model.headers, accountId, apiKey, options?.sessionId);
+			const headers = createCodexHeaders(
+				{ ...(model.headers ?? {}), ...(options?.headers ?? {}) },
+				accountId,
+				apiKey,
+				options?.sessionId,
+			);
 			logCodexDebug("codex request", {
 				url,
 				model: params.model,
@@ -508,19 +537,6 @@ function getAccountId(accessToken: string): string {
 	return accountId;
 }
 
-function shortHash(str: string): string {
-	let h1 = 0xdeadbeef;
-	let h2 = 0x41c6ce57;
-	for (let i = 0; i < str.length; i++) {
-		const ch = str.charCodeAt(i);
-		h1 = Math.imul(h1 ^ ch, 2654435761);
-		h2 = Math.imul(h2 ^ ch, 1597334677);
-	}
-	h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
-	h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
-	return (h2 >>> 0).toString(36) + (h1 >>> 0).toString(36);
-}
-
 function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput {
 	const messages: ResponseInput = [];
 
@@ -583,10 +599,11 @@ function convertMessages(model: Model<"openai-codex-responses">, context: Contex
 					} satisfies ResponseOutputMessage);
 				} else if (block.type === "toolCall" && msg.stopReason !== "error") {
 					const toolCall = block as ToolCall;
+					const normalized = normalizeResponsesToolCallId(toolCall.id);
 					output.push({
 						type: "function_call",
-						id: toolCall.id.split("|")[1],
-						call_id: toolCall.id.split("|")[0],
+						id: normalized.itemId,
+						call_id: normalized.callId,
 						name: toolCall.name,
 						arguments: JSON.stringify(toolCall.arguments),
 					});
@@ -600,11 +617,12 @@ function convertMessages(model: Model<"openai-codex-responses">, context: Contex
 				.map((c) => (c as { text: string }).text)
 				.join("\n");
 			const hasImages = msg.content.some((c) => c.type === "image");
+			const normalized = normalizeResponsesToolCallId(msg.toolCallId);
 
 			const hasText = textResult.length > 0;
 			messages.push({
 				type: "function_call_output",
-				call_id: msg.toolCallId.split("|")[0],
+				call_id: normalized.callId,
 				output: sanitizeSurrogates(hasText ? textResult : "(see attached image)"),
 			});
 

package/src/providers/openai-completions.ts

@@ -101,8 +101,9 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 
 		try {
 			const apiKey = options?.apiKey || getEnvApiKey(model.provider) || "";
-			const client = createClient(model, context, apiKey);
+			const client = createClient(model, context, apiKey, options?.headers);
 			const params = buildParams(model, context, options);
+			options?.onPayload?.(params);
 			const openaiStream = await client.chat.completions.create(params, { signal: options?.signal });
 			stream.push({ type: "start", partial: output });
 
@@ -319,7 +320,12 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 	return stream;
 };
 
-function createClient(model: Model<"openai-completions">, context: Context, apiKey?: string) {
+function createClient(
+	model: Model<"openai-completions">,
+	context: Context,
+	apiKey?: string,
+	extraHeaders?: Record<string, string>,
+) {
 	if (!apiKey) {
 		if (!process.env.OPENAI_API_KEY) {
 			throw new Error(
@@ -329,7 +335,7 @@ function createClient(model: Model<"openai-completions">, context: Context, apiK
 		apiKey = process.env.OPENAI_API_KEY;
 	}
 
-	const headers = { ...model.headers };
+	const headers = { ...(model.headers ?? {}), ...(extraHeaders ?? {}) };
 	if (model.provider === "github-copilot") {
 		// Copilot expects X-Initiator to indicate whether the request is user-initiated
 		// or agent-initiated (e.g. follow-up after assistant/tool messages). If there is

package/src/providers/openai-responses.ts

@@ -50,6 +50,11 @@ export interface OpenAIResponsesOptions extends StreamOptions {
 	reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
 	reasoningSummary?: "auto" | "detailed" | "concise" | null;
 	serviceTier?: ResponseCreateParamsStreaming["service_tier"];
+	/**
+	 * Enforce strict tool call/result pairing when building Responses API inputs.
+	 * Azure OpenAI Responses API requires tool results to have a matching tool call.
+	 */
+	strictResponsesPairing?: boolean;
 }
 
 /**
@@ -85,8 +90,9 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 		try {
 			// Create OpenAI client
 			const apiKey = options?.apiKey || getEnvApiKey(model.provider) || "";
-			const client = createClient(model, context, apiKey);
+			const client = createClient(model, context, apiKey, options?.headers);
 			const params = buildParams(model, context, options);
+			options?.onPayload?.(params);
 			const openaiStream = await client.responses.create(
 				params,
 				options?.signal ? { signal: options.signal } : undefined,
@@ -317,7 +323,12 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 	return stream;
 };
 
-function createClient(model: Model<"openai-responses">, context: Context, apiKey?: string) {
+function createClient(
+	model: Model<"openai-responses">,
+	context: Context,
+	apiKey?: string,
+	extraHeaders?: Record<string, string>,
+) {
 	if (!apiKey) {
 		if (!process.env.OPENAI_API_KEY) {
 			throw new Error(
@@ -327,7 +338,7 @@ function createClient(model: Model<"openai-responses">, context: Context, apiKey
 		apiKey = process.env.OPENAI_API_KEY;
 	}
 
-	const headers = { ...model.headers };
+	const headers = { ...(model.headers ?? {}), ...(extraHeaders ?? {}) };
 	if (model.provider === "github-copilot") {
 		// Copilot expects X-Initiator to indicate whether the request is user-initiated
 		// or agent-initiated (e.g. follow-up after assistant/tool messages). If there is
@@ -362,7 +373,8 @@ function createClient(model: Model<"openai-responses">, context: Context, apiKey
 }
 
 function buildParams(model: Model<"openai-responses">, context: Context, options?: OpenAIResponsesOptions) {
-	const messages = convertMessages(model, context);
+	const strictResponsesPairing = options?.strictResponsesPairing ?? isAzureOpenAIBaseUrl(model.baseUrl ?? "");
+	const messages = convertMessages(model, context, strictResponsesPairing);
 
 	const params: ResponseCreateParamsStreaming = {
 		model: model.id,
@@ -413,8 +425,26 @@ function buildParams(model: Model<"openai-responses">, context: Context, options
 	return params;
 }
 
-function convertMessages(model: Model<"openai-responses">, context: Context): ResponseInput {
+function normalizeResponsesToolCallId(id: string): { callId: string; itemId: string } {
+	const [callId, itemId] = id.split("|");
+	if (callId && itemId) {
+		return { callId, itemId };
+	}
+	const hash = shortHash(id);
+	return { callId: `call_${hash}`, itemId: `item_${hash}` };
+}
+
+function isAzureOpenAIBaseUrl(baseUrl: string): boolean {
+	return baseUrl.includes(".openai.azure.com") || baseUrl.includes("azure.com/openai");
+}
+
+function convertMessages(
+	model: Model<"openai-responses">,
+	context: Context,
+	strictResponsesPairing: boolean,
+): ResponseInput {
 	const messages: ResponseInput = [];
+	const knownCallIds = new Set<string>();
 
 	const transformedMessages = transformMessages(context.messages, model);
 
@@ -487,10 +517,12 @@ function convertMessages(model: Model<"openai-responses">, context: Context): Re
 					// Do not submit toolcall blocks if the completion had an error (i.e. abort)
 				} else if (block.type === "toolCall" && msg.stopReason !== "error") {
 					const toolCall = block as ToolCall;
+					const normalized = normalizeResponsesToolCallId(toolCall.id);
+					knownCallIds.add(normalized.callId);
 					output.push({
 						type: "function_call",
-						id: toolCall.id.split("|")[1],
-						call_id: toolCall.id.split("|")[0],
+						id: normalized.itemId,
+						call_id: normalized.callId,
 						name: toolCall.name,
 						arguments: JSON.stringify(toolCall.arguments),
 					});
@@ -505,12 +537,16 @@ function convertMessages(model: Model<"openai-responses">, context: Context): Re
 				.map((c) => (c as any).text)
 				.join("\n");
 			const hasImages = msg.content.some((c) => c.type === "image");
+			const normalized = normalizeResponsesToolCallId(msg.toolCallId);
+			if (strictResponsesPairing && !knownCallIds.has(normalized.callId)) {
+				continue;
+			}
 
 			// Always send function_call_output with text (or placeholder if only images)
 			const hasText = textResult.length > 0;
 			messages.push({
 				type: "function_call_output",
-				call_id: msg.toolCallId.split("|")[0],
+				call_id: normalized.callId,
 				output: sanitizeSurrogates(hasText ? textResult : "(see attached image)"),
 			});
 

package/src/providers/transform-messages.ts

@@ -9,9 +9,34 @@ function normalizeToolCallId(id: string): string {
 	return id.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 40);
 }
 
+/** Fast deterministic hash to shorten long strings */
+function shortHash(str: string): string {
+	let h1 = 0xdeadbeef;
+	let h2 = 0x41c6ce57;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+	h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+	return (h2 >>> 0).toString(36) + (h1 >>> 0).toString(36);
+}
+
+function normalizeResponsesToolCallId(id: string): string {
+	const [callId, itemId] = id.split("|");
+	if (callId && itemId) {
+		return id;
+	}
+	const hash = shortHash(id);
+	return `call_${hash}|item_${hash}`;
+}
+
 export function transformMessages<TApi extends Api>(messages: Message[], model: Model<TApi>): Message[] {
 	// Build a map of original tool call IDs to normalized IDs for github-copilot cross-API switches
 	const toolCallIdMap = new Map<string, string>();
+	const skippedToolCallIds = new Set<string>();
+	const needsResponsesToolCallIds = model.api === "openai-responses" || model.api === "openai-codex-responses";
 
 	// First pass: transform messages (thinking blocks, tool call ID normalization)
 	const transformed = messages.flatMap<Message>((msg): Message[] => {
@@ -22,20 +47,39 @@ export function transformMessages<TApi extends Api>(messages: Message[], model:
 
 		// Handle toolResult messages - normalize toolCallId if we have a mapping
 		if (msg.role === "toolResult") {
+			if (skippedToolCallIds.has(msg.toolCallId)) {
+				return [];
+			}
 			const normalizedId = toolCallIdMap.get(msg.toolCallId);
 			if (normalizedId && normalizedId !== msg.toolCallId) {
 				return [{ ...msg, toolCallId: normalizedId }];
 			}
+			if (needsResponsesToolCallIds) {
+				return [{ ...msg, toolCallId: normalizeResponsesToolCallId(msg.toolCallId) }];
+			}
 			return [msg];
 		}
 
 		// Assistant messages need transformation check
 		if (msg.role === "assistant") {
 			const assistantMsg = msg as AssistantMessage;
+			const isSameProviderApi = assistantMsg.provider === model.provider && assistantMsg.api === model.api;
+			const isErroredAssistant = assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted";
+			if (!isSameProviderApi && isErroredAssistant) {
+				for (const block of assistantMsg.content) {
+					if (block.type === "toolCall") {
+						skippedToolCallIds.add(block.id);
+					}
+				}
+				return [];
+			}
 
 			// If message is from the same provider and API, keep as is
-			if (assistantMsg.provider === model.provider && assistantMsg.api === model.api) {
-				if (assistantMsg.stopReason === "error" && assistantMsg.content.length === 0) {
+			if (isSameProviderApi) {
+				if (
+					(assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted") &&
+					assistantMsg.content.length === 0
+				) {
 					return [];
 				}
 				return [msg];
@@ -64,12 +108,20 @@ export function transformMessages<TApi extends Api>(messages: Message[], model:
 					};
 				}
 				// Normalize tool call IDs when target API requires strict format
-				if (block.type === "toolCall" && needsToolCallIdNormalization) {
+				if (block.type === "toolCall") {
 					const toolCall = block as ToolCall;
-					const normalizedId = normalizeToolCallId(toolCall.id);
-					if (normalizedId !== toolCall.id) {
-						toolCallIdMap.set(toolCall.id, normalizedId);
-						return { ...toolCall, id: normalizedId };
+					if (needsResponsesToolCallIds) {
+						const normalizedId = normalizeResponsesToolCallId(toolCall.id);
+						if (normalizedId !== toolCall.id) {
+							toolCallIdMap.set(toolCall.id, normalizedId);
+							return { ...toolCall, id: normalizedId };
+						}
+					} else if (needsToolCallIdNormalization) {
+						const normalizedId = normalizeToolCallId(toolCall.id);
+						if (normalizedId !== toolCall.id) {
+							toolCallIdMap.set(toolCall.id, normalizedId);
+							return { ...toolCall, id: normalizedId };
+						}
 					}
 				}
 				// All other blocks pass through unchanged

package/src/stream.ts

@@ -79,10 +79,17 @@ export function getEnvApiKey(provider: any): string | undefined {
 		// 1. AWS_PROFILE - named profile from ~/.aws/credentials
 		// 2. AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY - standard IAM keys
 		// 3. AWS_BEARER_TOKEN_BEDROCK - Bedrock API keys (bearer token)
+		// 4. AWS_CONTAINER_CREDENTIALS_* - ECS/Task IAM role credentials
+		// 5. AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN - IRSA (EKS) web identity
+		const hasEcsCredentials =
+			!!process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI || !!process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI;
+		const hasWebIdentity = !!process.env.AWS_WEB_IDENTITY_TOKEN_FILE && !!process.env.AWS_ROLE_ARN;
 		if (
 			process.env.AWS_PROFILE ||
 			(process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY) ||
-			process.env.AWS_BEARER_TOKEN_BEDROCK
+			process.env.AWS_BEARER_TOKEN_BEDROCK ||
+			hasEcsCredentials ||
+			hasWebIdentity
 		) {
 			return "<authenticated>";
 		}
@@ -252,7 +259,9 @@ function mapOptionsForApi<TApi extends Api>(
 		maxTokens: options?.maxTokens || Math.min(model.maxTokens, 32000),
 		signal: options?.signal,
 		apiKey: apiKey || options?.apiKey,
+		headers: options?.headers,
 		sessionId: options?.sessionId,
+		onPayload: options?.onPayload,
 		execHandlers: options?.execHandlers,
 	};
 

package/src/types.ts

@@ -96,12 +96,22 @@ export interface StreamOptions {
 	maxTokens?: number;
 	signal?: AbortSignal;
 	apiKey?: string;
+	/**
+	 * Additional headers to include in provider requests.
+	 * These are merged on top of model-defined headers.
+	 */
+	headers?: Record<string, string>;
 	/**
 	 * Optional session identifier for providers that support session-based caching.
 	 * Providers can use this to enable prompt caching, request routing, or other
 	 * session-aware features. Ignored by providers that don't support it.
 	 */
 	sessionId?: string;
+	/**
+	 * Optional hook to observe the provider request payload before it is sent.
+	 * The payload format is provider-specific.
+	 */
+	onPayload?: (payload: unknown) => void;
 	/** Cursor exec/MCP tool handlers (cursor-agent only). */
 	execHandlers?: CursorExecHandlers;
 }

package/src/utils/oauth/index.ts

@@ -30,6 +30,7 @@ export {
 export { loginAntigravity, refreshAntigravityToken } from "./google-antigravity";
 // Google Gemini CLI
 export { loginGeminiCli, refreshGoogleCloudToken } from "./google-gemini-cli";
+export type { OpenAICodexLoginOptions } from "./openai-codex";
 // OpenAI Codex (ChatGPT OAuth)
 export { loginOpenAICodex, refreshOpenAICodexToken } from "./openai-codex";
 

package/src/utils/oauth/openai-codex.ts

@@ -49,6 +49,7 @@ class OpenAICodexOAuthFlow extends OAuthCallbackFlow {
 	constructor(
 		ctrl: OAuthController,
 		private readonly pkce: PKCE,
+		private readonly originator: string,
 	) {
 		super(ctrl, CALLBACK_PORT, CALLBACK_PATH);
 	}
@@ -67,7 +68,7 @@ class OpenAICodexOAuthFlow extends OAuthCallbackFlow {
 			state,
 			id_token_add_organizations: "true",
 			codex_cli_simplified_flow: "true",
-			originator: "opencode",
+			originator: this.originator,
 		});
 
 		const url = `${AUTHORIZE_URL}?${searchParams.toString()}`;
@@ -122,9 +123,15 @@ async function exchangeCodeForToken(code: string, verifier: string, redirectUri:
 /**
  * Login with OpenAI Codex OAuth
  */
-export async function loginOpenAICodex(ctrl: OAuthController): Promise<OAuthCredentials> {
+export type OpenAICodexLoginOptions = OAuthController & {
+	/** Optional originator value for OpenAI Codex OAuth. Default: "opencode". */
+	originator?: string;
+};
+
+export async function loginOpenAICodex(options: OpenAICodexLoginOptions): Promise<OAuthCredentials> {
 	const pkce = await generatePKCE();
-	const flow = new OpenAICodexOAuthFlow(ctrl, pkce);
+	const originator = options.originator?.trim() || "opencode";
+	const flow = new OpenAICodexOAuthFlow(options, pkce, originator);
 
 	return flow.login();
 }