@gajae-code/ai 0.16.1 → 0.16.4

package/src/openai-completions-compat.ts

@@ -48,10 +48,57 @@ function parseHostname(baseUrl: string): string | undefined {
 	}
 }
 
+function isProductionXaiApiUrl(baseUrl: string): boolean {
+	if (
+		/[\u0000-\u0020\u007f]/u.test(baseUrl) ||
+		baseUrl.includes("?") ||
+		baseUrl.includes("#") ||
+		baseUrl.includes("\\")
+	) {
+		return false;
+	}
+	const authorityTail = baseUrl.slice("https://".length);
+	const authorityEnd = authorityTail.search(/[/?#]/u);
+	const authority = authorityTail.slice(0, authorityEnd === -1 ? undefined : authorityEnd);
+	if (!/^api\.x\.ai(?::443)?$/iu.test(authority)) return false;
+	try {
+		const url = new URL(baseUrl);
+		return (
+			url.protocol === "https:" &&
+			url.hostname.toLowerCase() === "api.x.ai" &&
+			url.port === "" &&
+			url.username === "" &&
+			url.password === "" &&
+			url.search === "" &&
+			url.hash === ""
+		);
+	} catch {
+		return false;
+	}
+}
+
 function hostnameMatches(hostname: string | undefined, suffix: string): boolean {
 	return hostname !== undefined && (hostname === suffix || hostname.endsWith(`.${suffix}`));
 }
 
+export type GrokGeneration = {
+	major: number;
+	minor: number;
+};
+
+function parseGrokGeneration(modelId: string): GrokGeneration | undefined {
+	const canonicalId = modelId.startsWith("x-ai/") ? modelId.slice("x-ai/".length) : modelId;
+	const match =
+		/^grok-([1-9]\d?)(?:\.(0|[1-9]\d?))?(?:-(latest|preview|\d{8}|reasoning|\d{4}-reasoning|beta-latest-reasoning|multi-agent-beta-latest))?$/.exec(
+			canonicalId,
+		);
+	if (!match) return undefined;
+	return {
+		major: Number(match[1]),
+		minor: match[2] === undefined ? 0 : Number(match[2]),
+	};
+}
+
 /** Returns whether the request endpoint is an audited reasoning-control transport. */
 export function isAuditedOpenAIReasoningTransport(
 	model: { provider: string; baseUrl?: string },
@@ -63,6 +110,32 @@ export function isAuditedOpenAIReasoningTransport(
 	return AUDITED_REASONING_EFFORT_HOST_SUFFIXES.some(suffix => hostnameMatches(hostname, suffix));
 }
 
+/**
+ * xAI's first-party API accepts `reasoning_effort` on Grok 4.5 and later.
+ * Provider labels are user-configurable, so both the provider and the official
+ * API origin must match. Unknown variants fail closed instead of inheriting a
+ * capability from a loose model-id prefix.
+ */
+export function parseDirectXaiReasoningEffortGeneration(
+	model: { provider: string; id: string; api?: string; baseUrl?: string },
+	resolvedBaseUrl?: string,
+): GrokGeneration | undefined {
+	if (model.provider !== "xai") return undefined;
+	if (model.api !== "openai-completions") return undefined;
+	if (!isProductionXaiApiUrl(resolvedBaseUrl ?? model.baseUrl ?? "")) return undefined;
+	if (model.id.includes("/")) return undefined;
+	const generation = parseGrokGeneration(model.id);
+	if (!generation) return undefined;
+	return generation.major > 4 || (generation.major === 4 && generation.minor >= 5) ? generation : undefined;
+}
+
+export function isDirectXaiReasoningEffortModel(
+	model: { provider: string; id: string; api?: string; baseUrl?: string },
+	resolvedBaseUrl?: string,
+): boolean {
+	return parseDirectXaiReasoningEffortGeneration(model, resolvedBaseUrl) !== undefined;
+}
+
 export type ResolvedOpenAICompat = Required<
 	Omit<
 		OpenAICompat,
@@ -184,8 +257,8 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 		baseUrl.includes("chutes.ai") ||
 		baseUrl.includes("fireworks.ai") ||
 		isDirectDeepseekApi;
-	const isGrok = provider === "xai" || baseUrl.includes("api.x.ai");
-	const isDirectXaiReasoningEffortModel = provider === "xai" && (model.id === "grok-4.5" || model.id === "grok-4.6");
+	const isGrok = provider === "xai" || baseUrl.includes("api.x.ai") || parseGrokGeneration(model.id) !== undefined;
+
 	const isMistral = provider === "mistral" || baseUrl.includes("mistral.ai");
 
 	// Hosts whose chat-completions endpoints are known to accept multiple
@@ -278,7 +351,8 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 		supportsResponsesSessionAffinity: false,
 		supportsMultipleSystemMessages: supportsMultipleSystemMessagesDefault,
 		supportsReasoningEffort:
-			hasAuditedReasoningEffortTransport && ((!isGrok && !isZai) || isDirectXaiReasoningEffortModel),
+			hasAuditedReasoningEffortTransport &&
+			((!isGrok && !isZai) || isOpenRouter || isDirectXaiReasoningEffortModel(model, resolvedBaseUrl)),
 		reasoningEffortMap,
 		supportsUsageInStreaming: !isCerebras,
 		disableReasoningOnForcedToolChoice: isKimiModel || isAnthropicModel || isOpenCodeGoReasoning,

package/src/providers/amazon-bedrock.d.ts

@@ -6,8 +6,9 @@
  * No `@aws-sdk/*`, no `@smithy/*`, no `proxy-agent`. Proxies are honored via
  * Bun's native `HTTPS_PROXY` support.
  */
+import { parseBedrockClaudeGeneration } from "../bedrock-claude-cache-policy";
 import type { Effort } from "../model-thinking";
-import type { StreamFunction, StreamOptions, ThinkingBudgets, Tool, ToolChoice } from "../types";
+import type { Model, StreamFunction, StreamOptions, ThinkingBudgets, Tool, ToolChoice } from "../types";
 export type BedrockThinkingDisplay = "summarized" | "omitted";
 export interface BedrockOptions extends StreamOptions {
     region?: string;
@@ -51,10 +52,24 @@ interface WireToolConfig {
     toolChoice?: WireToolChoice;
 }
 export declare const streamBedrock: StreamFunction<"bedrock-converse-stream">;
+/**
+ * Check if the model supports prompt caching.
+ * Supported: Claude 3.5 Haiku, Claude 3.7 Sonnet, and every later Claude
+ * generation:
+ * https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
+ *
+ * For base models and system-defined inference profiles the model ID / ARN
+ * contains the model name, so we can decide locally.
+ *
+ * For application inference profiles (whose ARNs don't contain the model name),
+ * set AWS_BEDROCK_FORCE_CACHE=1 to enable cache points.  Amazon Nova models
+ * have automatic caching and don't need explicit cache points.
+ */
+export declare function supportsPromptCaching(model: Model<"bedrock-converse-stream">): boolean;
+export { parseBedrockClaudeGeneration };
 export declare function stripBedrockForcedToolChoiceForRetry<T extends {
     toolConfig?: {
         toolChoice?: unknown;
     };
 }>(body: T): T;
 export declare function convertToolConfig(tools: Tool[] | undefined, toolChoice: BedrockOptions["toolChoice"]): WireToolConfig | undefined;
-export {};

package/src/providers/amazon-bedrock.ts

@@ -9,6 +9,7 @@
 
 import { $credentialEnv, $env, $flag, extractHttpStatusFromError, fetchWithRetry } from "@gajae-code/utils";
 import { assertAwsRegionLabel } from "../adapter-internals/aws-region";
+import { parseBedrockClaudeGeneration, supportsBedrockClaudePromptCaching } from "../bedrock-claude-cache-policy";
 import type { Effort } from "../model-thinking";
 import {
 	mapEffortToAnthropicAdaptiveEffort,
@@ -610,7 +611,9 @@ function handleContentBlockStop(
 
 /**
  * Check if the model supports prompt caching.
- * Supported: Anthropic model 3.5 Haiku, Anthropic model 3.7 Sonnet, Anthropic model 4.x+ models, Haiku 4.5+
+ * Supported: Claude 3.5 Haiku, Claude 3.7 Sonnet, and every later Claude
+ * generation:
+ * https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
  *
  * For base models and system-defined inference profiles the model ID / ARN
  * contains the model name, so we can decide locally.
@@ -619,21 +622,18 @@ function handleContentBlockStop(
  * set AWS_BEDROCK_FORCE_CACHE=1 to enable cache points.  Amazon Nova models
  * have automatic caching and don't need explicit cache points.
  */
-function supportsPromptCaching(model: Model<"bedrock-converse-stream">): boolean {
+export function supportsPromptCaching(model: Model<"bedrock-converse-stream">): boolean {
+	const claudeSupport = supportsBedrockClaudePromptCaching(model.id);
+	if (claudeSupport !== undefined) return claudeSupport;
 	if (model.cost.cacheRead || model.cost.cacheWrite) return true;
-	const id = model.id.toLowerCase();
-	// Anthropic model 4.x models (opus-4, sonnet-4, haiku-4)
-	if (id.includes("claude") && (id.includes("-4-") || id.includes("-4."))) return true;
-	// Anthropic model 3.5 Haiku, Anthropic model 3.7 Sonnet (legacy naming)
-	if (id.includes("claude-3-7-sonnet") || id.includes("claude-3-5-haiku")) return true;
-	// Anthropic model Haiku 4.5+ (new naming)
-	if (id.includes("claude-haiku")) return true;
 	// Application inference profiles don't contain the model name in the ARN.
 	// Allow users to force cache points via environment variable.
 	if (typeof process !== "undefined" && $flag("AWS_BEDROCK_FORCE_CACHE")) return true;
 	return false;
 }
 
+export { parseBedrockClaudeGeneration };
+
 /**
  * Check if the model supports thinking signatures in reasoningContent.
  * Only Anthropic Anthropic model models support the signature field.

package/src/providers/anthropic.d.ts

@@ -203,6 +203,7 @@ export type AnthropicClientOptionsArgs = {
     maxRetryDelayMs?: number;
     streamFirstEventTimeoutMs?: number;
     streamIdleTimeoutMs?: number;
+    providerSessionId?: string;
 };
 export type AnthropicClientOptionsResult = {
     isOAuthToken: boolean;

package/src/providers/anthropic.ts

@@ -111,6 +111,11 @@ import {
 	hasCopilotVisionInput,
 	resolveGitHubCopilotBaseUrl,
 } from "./github-copilot-headers";
+import {
+	applyOpenCodeGoSessionHeader,
+	resolveOpenCodeGoSessionId,
+	wrapFetchForOpenCodeGoSession,
+} from "./opencode-go-session";
 import { hasAdjacentPrivateThinkingBlocks, transformMessages } from "./transform-messages";
 import { NON_VISION_IMAGE_PLACEHOLDER } from "./vision-guard";
 
@@ -1126,6 +1131,7 @@ export type AnthropicClientOptionsArgs = {
 	maxRetryDelayMs?: number;
 	streamFirstEventTimeoutMs?: number;
 	streamIdleTimeoutMs?: number;
+	providerSessionId?: string;
 };
 
 export type AnthropicClientOptionsResult = {
@@ -1940,6 +1946,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					maxRetryDelayMs: options?.maxRetryDelayMs,
 					streamFirstEventTimeoutMs: options?.streamFirstEventTimeoutMs,
 					streamIdleTimeoutMs: options?.streamIdleTimeoutMs,
+					providerSessionId: options?.providerSessionId,
 				});
 				client = created.client;
 				isOAuthToken = created.isOAuthToken;
@@ -3107,7 +3114,11 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 	const tlsFetchOptions = buildClaudeCodeTlsFetchOptions(model, baseUrl);
 	const baseFetch = args.fetch ?? fetch;
 	const boundedFetch = wrapAnthropicFetchForBoundedRateLimits(baseFetch, args.maxRetryDelayMs);
-	const debugFetch = onSseEvent ? wrapFetchForSseDebug(boundedFetch, event => onSseEvent(event, model)) : boundedFetch;
+	const openCodeGoSessionId = resolveOpenCodeGoSessionId(model, baseUrl, args.providerSessionId, "anthropic");
+	const providerScopedFetch = wrapFetchForOpenCodeGoSession(boundedFetch, openCodeGoSessionId);
+	const debugFetch = onSseEvent
+		? wrapFetchForSseDebug(providerScopedFetch, event => onSseEvent(event, model))
+		: providerScopedFetch;
 	// Bound the connect/headers phase. The first-event watchdog arms only after
 	// response headers arrive, so a request whose connection dies before headers
 	// was previously governed only by the Anthropic SDK's 10-minute default per
@@ -3124,16 +3135,19 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 		if (needsFineGrainedToolStreamingBeta) {
 			betaFeatures.push(fineGrainedToolStreamingBeta);
 		}
-		const defaultHeaders = mergeHeaders(
-			{
-				Accept: stream ? "text/event-stream" : "application/json",
-				"Anthropic-Dangerous-Direct-Browser-Access": "true",
-				Authorization: `Bearer ${copilotApiKey}`,
-				...(betaFeatures.length > 0 ? { "anthropic-beta": buildBetaHeader([], betaFeatures) } : {}),
-			},
-			model.headers,
-			dynamicHeaders,
-			headers,
+		const defaultHeaders = applyOpenCodeGoSessionHeader(
+			mergeHeaders(
+				{
+					Accept: stream ? "text/event-stream" : "application/json",
+					"Anthropic-Dangerous-Direct-Browser-Access": "true",
+					Authorization: `Bearer ${copilotApiKey}`,
+					...(betaFeatures.length > 0 ? { "anthropic-beta": buildBetaHeader([], betaFeatures) } : {}),
+				},
+				model.headers,
+				dynamicHeaders,
+				headers,
+			),
+			openCodeGoSessionId,
 		);
 
 		return {
@@ -3159,16 +3173,19 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 		betaFeatures.push(interleavedThinkingBeta);
 	}
 
-	const defaultHeaders = buildAnthropicHeaders({
-		apiKey,
-		baseUrl,
-		isOAuth: oauthToken,
-		extraBetas: betaFeatures,
-		stream,
-		modelHeaders: mergeHeaders(model.headers, foundryCustomHeaders, headers, dynamicHeaders),
-		isCloudflareAiGateway: model.provider === "cloudflare-ai-gateway",
-		zcodeSourceHeaders: model.provider === "glm-zcode",
-	});
+	const defaultHeaders = applyOpenCodeGoSessionHeader(
+		buildAnthropicHeaders({
+			apiKey,
+			baseUrl,
+			isOAuth: oauthToken,
+			extraBetas: betaFeatures,
+			stream,
+			modelHeaders: mergeHeaders(model.headers, foundryCustomHeaders, headers, dynamicHeaders),
+			isCloudflareAiGateway: model.provider === "cloudflare-ai-gateway",
+			zcodeSourceHeaders: model.provider === "glm-zcode",
+		}),
+		openCodeGoSessionId,
+	);
 
 	if (model.provider === "cloudflare-ai-gateway") {
 		return {

package/src/providers/cursor.ts

@@ -689,7 +689,7 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 			conversationUsageContextCache.set(conversationId, usageContext);
 			const reusableCachedState =
 				cachedState && canReuseCursorUsageContext(previousUsageContext, usageContext) ? cachedState : undefined;
-			const { requestBytes, conversationState } = buildGrpcRequest(model, context, options, {
+			const { requestBytes, conversationState } = await buildGrpcRequest(model, context, options, {
 				conversationId,
 				blobStore,
 				conversationState: reusableCachedState,
@@ -3459,7 +3459,7 @@ function extractImages(content: (TextContent | ImageContent)[]) {
 		);
 }
 
-function buildGrpcRequest(
+async function buildGrpcRequest(
 	model: Model<"cursor-agent">,
 	context: Context,
 	options: CursorOptions | undefined,
@@ -3468,11 +3468,11 @@ function buildGrpcRequest(
 		blobStore: Map<string, Uint8Array>;
 		conversationState?: ConversationStateStructure;
 	},
-): {
+): Promise<{
 	requestBytes: Uint8Array;
 	blobStore: Map<string, Uint8Array>;
 	conversationState: ConversationStateStructure;
-} {
+}> {
 	const blobStore = state.blobStore;
 
 	const systemPromptIds = buildCursorSystemPromptJsons(context.systemPrompt, model.id).map(json =>
@@ -3558,7 +3558,7 @@ function buildGrpcRequest(
 		displayName: model.name,
 	});
 
-	const runRequest = create(AgentRunRequestSchema, {
+	let runRequest = create(AgentRunRequestSchema, {
 		conversationState,
 		action,
 		modelDetails,
@@ -3573,7 +3573,13 @@ function buildGrpcRequest(
 			: {}),
 	});
 
-	options?.onPayload?.(runRequest, model, options?.attemptScope);
+	if (options?.onPayload) {
+		const payload = toJson(AgentRunRequestSchema, runRequest);
+		const replacement = await options.onPayload(payload, model, options.attemptScope);
+		if (replacement !== undefined) {
+			runRequest = fromJson(AgentRunRequestSchema, replacement as JsonValue);
+		}
+	}
 
 	// Tools are sent later via requestContext (exec handshake)
 

package/src/providers/openai-codex/response-handler.ts

@@ -25,7 +25,7 @@ const REQUEST_BLOCKED_MESSAGE_RE = /^\s*request blocked\b/i;
 
 export async function parseCodexError(response: Response): Promise<CodexErrorInfo> {
 	const raw = await response.text();
-	let message = raw || response.statusText || "Request failed";
+	let message = raw || response.statusText || `Codex request failed (HTTP ${response.status})`;
 	let friendlyMessage: string | undefined;
 	let rateLimits: CodexRateLimits | undefined;
 	let code: string | undefined;

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

@@ -51,6 +51,10 @@ import {
 	normalizeSystemPrompts,
 	sanitizeOpenAIResponsesHistoryItemsForReplay,
 } from "../utils";
+import {
+	formatOpenAICodexChatGPTEntitlementError,
+	isOpenAICodexChatGPTEntitlementError,
+} from "../utils/codex-entitlement";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE, transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
@@ -1234,7 +1238,7 @@ function handleCodexStreamEvent(args: {
 	}
 
 	if (eventType === "error" || eventType === "response.failed") {
-		throw createCodexProviderStreamError(rawEvent);
+		throw createCodexProviderStreamError(rawEvent, model.id);
 	}
 
 	return firstTokenTime;
@@ -2853,7 +2857,11 @@ async function openCodexSseEventStream(
 	updateCodexSessionMetadataFromHeaders(state, response.headers);
 	if (!response.ok) {
 		const info = await parseCodexError(response);
-		const error = new Error(info.friendlyMessage || info.message);
+		const error = new Error(
+			isOpenAICodexChatGPTEntitlementError(info.message, info.code)
+				? formatOpenAICodexChatGPTEntitlementError(body.model)
+				: info.friendlyMessage || info.message,
+		);
 		(error as { headers?: Headers; status?: number }).headers = response.headers;
 		(error as { headers?: Headers; status?: number }).status = response.status;
 		(error as { code?: string }).code = info.code;
@@ -3235,11 +3243,12 @@ function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolea
 	return !!message && CODEX_RETRYABLE_EVENT_MESSAGE.test(message);
 }
 
-function createCodexProviderStreamError(rawEvent: Record<string, unknown>): CodexProviderStreamError {
+function createCodexProviderStreamError(rawEvent: Record<string, unknown>, modelId: string): CodexProviderStreamError {
 	const code = getCodexEventErrorCode(rawEvent);
 	const message = getCodexEventErrorMessage(rawEvent);
-	const formattedMessage =
-		typeof rawEvent.type === "string" && rawEvent.type === "error"
+	const formattedMessage = isOpenAICodexChatGPTEntitlementError(message, code)
+		? formatOpenAICodexChatGPTEntitlementError(modelId)
+		: typeof rawEvent.type === "string" && rawEvent.type === "error"
 			? formatCodexErrorEvent(rawEvent, code, message)
 			: (formatCodexFailure(rawEvent) ?? "Codex response failed");
 	return new CodexProviderStreamError(

package/src/providers/openai-completions-compat.d.ts

@@ -3,4 +3,4 @@
  * the core-safe module so model metadata can use it without loading provider
  * implementations during startup.
  */
-export { detectOpenAICompat, type ResolvedOpenAICompat, resolveOpenAICompat } from "../openai-completions-compat";
+export { detectOpenAICompat, type GrokGeneration, isDirectXaiReasoningEffortModel, parseDirectXaiReasoningEffortGeneration, type ResolvedOpenAICompat, resolveOpenAICompat, } from "../openai-completions-compat";

package/src/providers/openai-completions-compat.ts

@@ -3,4 +3,11 @@
  * the core-safe module so model metadata can use it without loading provider
  * implementations during startup.
  */
-export { detectOpenAICompat, type ResolvedOpenAICompat, resolveOpenAICompat } from "../openai-completions-compat";
+export {
+	detectOpenAICompat,
+	type GrokGeneration,
+	isDirectXaiReasoningEffortModel,
+	parseDirectXaiReasoningEffortGeneration,
+	type ResolvedOpenAICompat,
+	resolveOpenAICompat,
+} from "../openai-completions-compat";

package/src/providers/openai-completions.ts

@@ -100,6 +100,11 @@ import {
 	wrapFetchForOpenAIRequestTransform,
 } from "./openai-request-transform";
 import { createInitialResponsesAssistantMessage } from "./openai-responses-shared";
+import {
+	applyOpenCodeGoSessionHeader,
+	resolveOpenCodeGoSessionId,
+	wrapFetchForOpenCodeGoSession,
+} from "./opencode-go-session";
 import { transformMessages } from "./transform-messages";
 import { joinTextWithImagePlaceholder, NON_VISION_IMAGE_PLACEHOLDER } from "./vision-guard";
 
@@ -602,6 +607,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				options?.authCredentialType,
 				options?.requestMaxRetries,
 				options?.sessionId,
+				options?.providerSessionId,
 				options?.maxRetryDelayMs,
 				options?.attemptScope,
 			);
@@ -1259,6 +1265,7 @@ async function createClient(
 	authCredentialType?: OpenAICompletionsOptions["authCredentialType"],
 	requestMaxRetries?: number,
 	sessionId?: string,
+	providerSessionId?: string,
 	maxRetryDelayMs?: number,
 	attemptScope?: import("../types.js").AttemptScopeRef,
 ): Promise<{
@@ -1356,6 +1363,11 @@ async function createClient(
 	const endpointRequestQuery = endpointQuery;
 	const requestQuery =
 		[endpointRequestQuery, azureQuery].filter((query): query is string => query !== undefined).join("&") || undefined;
+	const openCodeGoSessionId = resolveOpenCodeGoSessionId(model, baseUrl, providerSessionId, "openai");
+	// Reserve the provider-specific header on every OpenAI-compatible route. Caller,
+	// model, and transform values are removed unless the exact OpenCode Go endpoint
+	// has an opaque identity owned by the agent's conversation lifecycle.
+	headers = applyOpenCodeGoSessionHeader(headers, openCodeGoSessionId);
 	let capturedErrorResponse: CapturedHttpErrorResponse | undefined;
 	const baseFetch = fetchOverride ?? fetch;
 	const wrappedFetch = Object.assign(
@@ -1389,8 +1401,9 @@ async function createClient(
 		baseFetch.preconnect ? { preconnect: baseFetch.preconnect } : {},
 	);
 	const boundedFetch = wrapOpenAIFetchForBoundedRateLimits(wrappedFetch, maxRetryDelayMs);
+	const providerScopedFetch = wrapFetchForOpenCodeGoSession(boundedFetch, openCodeGoSessionId);
 	const transformedFetch = wrapFetchForOpenAIRequestTransform(
-		boundedFetch,
+		providerScopedFetch,
 		model.requestTransform,
 		`Gajae-Code/${packageJson.version}`,
 	);

package/src/providers/openai-responses.ts

@@ -93,6 +93,11 @@ import {
 	processResponsesStream,
 	repairOrphanResponsesToolOutputs,
 } from "./openai-responses-shared";
+import {
+	applyOpenCodeGoSessionHeader,
+	resolveOpenCodeGoSessionId,
+	wrapFetchForOpenCodeGoSession,
+} from "./opencode-go-session";
 import { transformMessages } from "./transform-messages";
 
 /**
@@ -378,6 +383,7 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 				options?.headers,
 				options?.initiatorOverride,
 				cacheSessionId,
+				options?.providerSessionId,
 				cacheRetention,
 				options?.onSseEvent,
 				options?.fetch,
@@ -556,6 +562,7 @@ function createClient(
 	extraHeaders?: Record<string, string>,
 	initiatorOverride?: MessageAttribution,
 	sessionId?: string,
+	providerSessionId?: string,
 	cacheRetention?: CacheRetention,
 	onSseEvent?: OpenAIResponsesOptions["onSseEvent"],
 	fetchOverride?: FetchImpl,
@@ -618,6 +625,8 @@ function createClient(
 	}
 	headers = applyOpenAIRequestTransformHeaders(headers, model.requestTransform, `Gajae-Code/${packageJson.version}`);
 	const { baseUrl: clientBaseUrl, query: endpointQuery } = splitBaseUrlQuery(baseUrl);
+	const openCodeGoSessionId = resolveOpenCodeGoSessionId(model, baseUrl, providerSessionId, "openai");
+	headers = applyOpenCodeGoSessionHeader(headers, openCodeGoSessionId);
 	const baseFetch = fetchOverride ?? fetch;
 	const queryFetch = Object.assign(
 		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
@@ -626,8 +635,9 @@ function createClient(
 		baseFetch.preconnect ? { preconnect: baseFetch.preconnect } : {},
 	);
 	const boundedFetch = wrapOpenAIFetchForBoundedRateLimits(queryFetch, maxRetryDelayMs);
+	const providerScopedFetch = wrapFetchForOpenCodeGoSession(boundedFetch, openCodeGoSessionId);
 	const transformedFetch = wrapFetchForOpenAIRequestTransform(
-		boundedFetch,
+		providerScopedFetch,
 		model.requestTransform,
 		`Gajae-Code/${packageJson.version}`,
 	);

package/src/providers/opencode-go-session.d.ts

@@ -0,0 +1,5 @@
+import type { FetchImpl, Model } from "../types";
+export type OpenCodeGoApiFamily = "openai" | "anthropic";
+export declare function resolveOpenCodeGoSessionId(model: Pick<Model, "provider">, baseUrl: string | undefined, providerSessionId: string | undefined, apiFamily: OpenCodeGoApiFamily): string | undefined;
+export declare function applyOpenCodeGoSessionHeader(headers: Record<string, string>, sessionId: string | undefined): Record<string, string>;
+export declare function wrapFetchForOpenCodeGoSession(baseFetch: FetchImpl, sessionId: string | undefined): FetchImpl;

package/src/providers/opencode-go-session.ts

@@ -0,0 +1,57 @@
+import type { FetchImpl, Model } from "../types";
+
+const OPENCODE_GO_ORIGIN = "https://opencode.ai";
+const OPENCODE_GO_OPENAI_BASE_PATH = "/zen/go/v1";
+const OPENCODE_GO_ANTHROPIC_BASE_PATH = "/zen/go";
+
+export type OpenCodeGoApiFamily = "openai" | "anthropic";
+
+function expectedBasePath(apiFamily: OpenCodeGoApiFamily): string {
+	return apiFamily === "openai" ? OPENCODE_GO_OPENAI_BASE_PATH : OPENCODE_GO_ANTHROPIC_BASE_PATH;
+}
+
+export function resolveOpenCodeGoSessionId(
+	model: Pick<Model, "provider">,
+	baseUrl: string | undefined,
+	providerSessionId: string | undefined,
+	apiFamily: OpenCodeGoApiFamily,
+): string | undefined {
+	if (model.provider !== "opencode-go" || !baseUrl || !providerSessionId) return undefined;
+	try {
+		const url = new URL(baseUrl);
+		if (url.origin !== OPENCODE_GO_ORIGIN) return undefined;
+		if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") return undefined;
+		if (url.pathname.replace(/\/+$/u, "") !== expectedBasePath(apiFamily)) return undefined;
+		return providerSessionId;
+	} catch {
+		return undefined;
+	}
+}
+
+export function applyOpenCodeGoSessionHeader(
+	headers: Record<string, string>,
+	sessionId: string | undefined,
+): Record<string, string> {
+	const normalizedHeaders = new Headers(headers);
+	normalizedHeaders.delete("x-opencode-session");
+	if (sessionId) normalizedHeaders.set("x-opencode-session", sessionId);
+	return Object.fromEntries(normalizedHeaders.entries());
+}
+
+export function wrapFetchForOpenCodeGoSession(baseFetch: FetchImpl, sessionId: string | undefined): FetchImpl {
+	return Object.assign(
+		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			if (input instanceof Request) {
+				const request = new Request(input, init);
+				request.headers.delete("x-opencode-session");
+				if (sessionId) request.headers.set("x-opencode-session", sessionId);
+				return baseFetch(request);
+			}
+			const headers = new Headers(init?.headers);
+			headers.delete("x-opencode-session");
+			if (sessionId) headers.set("x-opencode-session", sessionId);
+			return baseFetch(input, { ...init, headers });
+		},
+		baseFetch.preconnect ? { preconnect: baseFetch.preconnect } : {},
+	);
+}

package/src/stream.ts

@@ -955,6 +955,7 @@ function mapOptionsForApi<TApi extends Api>(
 		streamMaxRetries: options?.fallbackManaged ? 0 : options?.streamMaxRetries,
 		metadata: options?.metadata,
 		sessionId: options?.sessionId,
+		providerSessionId: options?.providerSessionId,
 		providerSessionState: options?.providerSessionState,
 		onPayload: options?.onPayload,
 		onResponse: options?.onResponse,

package/src/types.d.ts

@@ -239,6 +239,13 @@ export interface StreamOptions {
      * session-aware features. Ignored by providers that don't support it.
      */
     sessionId?: string;
+    /**
+     * Opaque conversation identity owned by the calling agent/session lifecycle.
+     * Unlike `sessionId`, this MUST NOT be synthesized from prompts, credentials,
+     * paths, cache keys, or other request content. Providers with a dedicated
+     * conversation header may use this only when their endpoint policy permits it.
+     */
+    providerSessionId?: string;
     /**
      * Provider-scoped mutable state store for this agent session.
      * Providers can use this to persist transport/session state between turns.

package/src/types.ts

@@ -443,6 +443,13 @@ export interface StreamOptions {
 	 * session-aware features. Ignored by providers that don't support it.
 	 */
 	sessionId?: string;
+	/**
+	 * Opaque conversation identity owned by the calling agent/session lifecycle.
+	 * Unlike `sessionId`, this MUST NOT be synthesized from prompts, credentials,
+	 * paths, cache keys, or other request content. Providers with a dedicated
+	 * conversation header may use this only when their endpoint policy permits it.
+	 */
+	providerSessionId?: string;
 	/**
 	 * Provider-scoped mutable state store for this agent session.
 	 * Providers can use this to persist transport/session state between turns.