@providerkit/core 0.17.2 → 0.20.0

package/src/auth/oauth.ts

@@ -0,0 +1,226 @@
+// The OAuth plumbing every signed-in provider shares: PKCE, the token POST, the
+// credential it builds, and the errors a sign-in can end in. Fetch only, no
+// Node built-ins. What differs per vendor stays in flows.ts.
+import { classifyHttp, ProviderError } from "../errors.ts";
+
+/** What the host app supplies. Opening a browser and catching a redirect are
+ *  the two things a fetch-only package can't do. */
+export interface AuthHost {
+  /** Names the app on the wire: Copilot's `Editor-Version`, xAI's `referrer`.
+   *  Use `name/version`, like `TabRunner/1.4.0`. */
+  appName: string;
+  /** Opens a page for the user. Device-code flows call it with the approval page. */
+  openUrl(url: string): void | Promise<void>;
+  /**
+   * Opens `authorizeUrl`, waits for the browser to land on `redirectUri`, and
+   * returns the `code` from that URL. Reject with a `SignInError` when the user
+   * denies (`denied`), closes the page (`cancelled`) or takes too long
+   * (`expired`). Check `state` against the one in the URL when it is set.
+   */
+  captureRedirect(request: {
+    authorizeUrl: string;
+    redirectUri: string;
+    state?: string;
+    signal: AbortSignal;
+  }): Promise<string>;
+  /** Replaces `fetch`, for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/** The stored result of a sign-in. */
+export interface Credential {
+  accessToken: string;
+  /** What renews `accessToken`. Copilot keeps the GitHub token here and Meta
+   *  its identity token. Empty for a key that never expires (OpenRouter). */
+  refreshToken: string;
+  /** Epoch ms, already moved earlier by {@link REFRESH_SKEW_MS}: refresh at or
+   *  after this, it is not the server's own expiry. */
+  expiresAt: number;
+  /** For display: the account the token belongs to. */
+  account?: string;
+  /** ChatGPT only: send it as the `ChatGPT-Account-Id` header. */
+  chatgptAccountId?: string;
+  /** Set when the vendor gives each account its own host (Copilot). */
+  baseUrl?: string;
+}
+
+export type SignInFailure = "denied" | "expired" | "cancelled";
+
+/** How a sign-in ended without a credential. The reason picks the wording. */
+export class SignInError extends Error {
+  constructor(readonly reason: SignInFailure) {
+    super(reason);
+    this.name = "SignInError";
+  }
+}
+
+/** The coded errors a sign-in or a refresh throws, as `ProviderError.code`. */
+export type AuthErrorCode =
+  | "token_refused"
+  | "token_incomplete"
+  | "device_response_invalid"
+  | "setup_required"
+  | "refresh_dead";
+
+export function authError(
+  code: AuthErrorCode,
+  message: string,
+  opts: { status?: number; body?: string } = {},
+): ProviderError {
+  const body = opts.body ?? "";
+  // `invalid_grant` and a 401 classify as `auth`, a 429 as `rate`, a 5xx as an outage.
+  const kind = opts.status === undefined ? "auth" : classifyHttp(opts.status, body);
+  return new ProviderError("auth", kind, message, { ...opts, code });
+}
+
+/** Refresh this long before the server's own expiry. */
+export const REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+export const str = (value: unknown): string | undefined =>
+  typeof value === "string" && value.length > 0 ? value : undefined;
+
+export const num = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined;
+
+export const asRecord = (value: unknown): Record<string, unknown> =>
+  typeof value === "object" && value !== null ? Object.fromEntries(Object.entries(value)) : {};
+
+/** RFC 7636 code verifier and S256 challenge. */
+export async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+  const verifier = toBase64Url(crypto.getRandomValues(new Uint8Array(64)));
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: toBase64Url(new Uint8Array(digest)) };
+}
+
+/** Opaque CSRF state: 128 bits, hex. */
+export function randomState(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function toBase64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * POST to a token endpoint and return the parsed body.
+ *
+ * A token in the body wins over the status: a vendor can return a usable
+ * credential next to a non-2xx (Anthropic answers 429 for a plan over its usage
+ * limit). Only a body without one is an error. The device-code poll sets
+ * `allowErrorBody`, because it gets a 4xx for most of the wait.
+ */
+export async function postToken(
+  host: AuthHost,
+  url: string,
+  params: Record<string, string>,
+  opts: { encode: "json" | "form"; allowErrorBody?: boolean },
+): Promise<Record<string, unknown>> {
+  const json = opts.encode === "json";
+  const res = await (host.fetchImpl ?? fetch)(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": json ? "application/json" : "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body: json ? JSON.stringify(params) : new URLSearchParams(params).toString(),
+  });
+  const text = await res.text().catch(() => "");
+  const record = asRecord(safeJson(text));
+
+  if (isTokenPair(record)) return record;
+  if (res.ok || (opts.allowErrorBody && res.status < 500)) return record;
+
+  const detail = errorDetail(record) ?? String(res.status);
+  throw authError("token_refused", `The sign-in server refused the request: ${detail}`, {
+    status: res.status,
+    body: text.slice(0, 2_000),
+  });
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function isTokenPair(body: Record<string, unknown>): boolean {
+  return (
+    str(body.access_token) !== undefined &&
+    str(body.refresh_token) !== undefined &&
+    num(body.expires_in) !== undefined
+  );
+}
+
+/** A reason out of an OAuth error body: RFC 6749's `error_description` and
+ *  `error`, or the nested `error.message` Anthropic and OpenAI use. */
+export function errorDetail(record: Record<string, unknown>): string | undefined {
+  const description = str(record.error_description);
+  if (description) return description;
+  const error = record.error;
+  if (typeof error === "string") return error;
+  const nested = asRecord(error);
+  return str(nested.message) ?? str(nested.type);
+}
+
+/** The credential a token response describes. Naming the account is the
+ *  caller's job: every vendor puts it under a different claim. */
+export function toCredential(body: Record<string, unknown>, fallbackRefresh?: string): Credential {
+  const accessToken = str(body.access_token);
+  // A refresh response may leave out the refresh token. Keep the old one then.
+  const refreshToken = str(body.refresh_token) ?? fallbackRefresh;
+  const expiresIn = num(body.expires_in);
+  if (!accessToken || !refreshToken || expiresIn === undefined) {
+    throw authError(
+      "token_incomplete",
+      "The sign-in server's reply is missing a token or its expiry.",
+    );
+  }
+  return { accessToken, refreshToken, expiresAt: Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS };
+}
+
+/** A JWT's payload, read WITHOUT checking the signature. Safe here because
+ *  nothing is authorized on it: it only names the account for display. */
+export function jwtClaims(token?: string): Record<string, unknown> | undefined {
+  const payload = token?.split(".")[1];
+  if (!payload) return undefined;
+  try {
+    return asRecord(JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/"))));
+  } catch {
+    return undefined;
+  }
+}
+
+/** The account a token names, trying the claims in order. An email wins and is
+ *  lowercased, because one mailbox written two ways is one account. */
+export function accountFromToken(
+  token: string | undefined,
+  ...claims: string[]
+): string | undefined {
+  const payload = jwtClaims(token);
+  if (!payload) return undefined;
+  for (const claim of claims) {
+    const value = str(payload[claim]);
+    if (value) return claim === "email" ? value.toLowerCase() : value;
+  }
+  return undefined;
+}
+
+/** The URL if it is http(s), else undefined. It comes off the network and ends
+ *  up in `openUrl`, so a `javascript:` or `data:` URL must not get through. */
+export function webUrl(
+  value: string | undefined,
+  protocols = ["https:", "http:"],
+): string | undefined {
+  if (!value) return undefined;
+  try {
+    const url = new URL(value);
+    return protocols.includes(url.protocol) ? url.href : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/auth/token-source.ts

@@ -0,0 +1,76 @@
+// One place that hands out a token that works: refreshes it once however many
+// callers ask, saves the new pair before anyone uses it, and recovers when a
+// second tab or process spent the refresh token first.
+import { isTransportFailure, ProviderError } from "../errors.ts";
+import { authError, type Credential } from "./oauth.ts";
+
+export interface TokenSourceOptions<C extends Credential = Credential> {
+  /** Read the stored credential. Read it on every call, never cache it: the
+   *  refresh token rotates, and a cached copy would spend one already used. */
+  load(): Promise<C | undefined>;
+  /** Persist a refreshed credential. Awaited before the new token is used. */
+  save(credential: C): Promise<void>;
+  /** Trade the credential for a fresh one: `createAuthFlow(id, host).refresh`. */
+  refresh(credential: C): Promise<C>;
+}
+
+export interface TokenSource<C extends Credential = Credential> {
+  /** A credential whose `accessToken` is good now. Throws a `ProviderError`
+   *  coded `refresh_dead` when the user must sign in again. */
+  getToken(): Promise<C>;
+}
+
+/**
+ * Refresh when the stored credential has expired, and only then.
+ *
+ * - Concurrent calls share one refresh and the result is saved before use.
+ * - When the server rejects the refresh, the stored credential is reloaded. If
+ *   another context saved a newer one meanwhile, that one is used. Otherwise
+ *   the session is dead and the error says so.
+ * - A network failure keeps the credential and rethrows, so a user on bad wifi
+ *   isn't told to sign in again.
+ *
+ * ponytail: two contexts can both lose a refresh before either one saves, and
+ * then both fail. Closing that needs a lock on the storage.
+ */
+export function tokenSource<C extends Credential>(options: TokenSourceOptions<C>): TokenSource<C> {
+  let inFlight: Promise<C> | undefined;
+
+  async function refreshStored(stale: C): Promise<C> {
+    try {
+      const fresh = await options.refresh(stale);
+      await options.save(fresh);
+      return fresh;
+    } catch (error) {
+      if (!isRejected(error)) throw error;
+      const stored = await options.load();
+      if (stored && isNewer(stored, stale) && Date.now() < stored.expiresAt) return stored;
+      throw authError("refresh_dead", "The sign-in expired and can't be renewed. Sign in again.");
+    }
+  }
+
+  return {
+    async getToken() {
+      const credential = await options.load();
+      if (!credential) {
+        throw authError("refresh_dead", "Not signed in. Sign in first.");
+      }
+      if (Date.now() < credential.expiresAt) return credential;
+      inFlight ??= refreshStored(credential).finally(() => {
+        inFlight = undefined;
+      });
+      return inFlight;
+    },
+  };
+}
+
+/** A refresh the server turned down for good, as opposed to one that never
+ *  reached it or came back unreadable. */
+function isRejected(error: unknown): error is ProviderError {
+  if (isTransportFailure(error) || !(error instanceof ProviderError)) return false;
+  return error.status === 400 || error.status === 401 || error.status === 403;
+}
+
+function isNewer(stored: Credential, stale: Credential): boolean {
+  return stored.refreshToken !== stale.refreshToken || stored.expiresAt > stale.expiresAt;
+}

package/src/context.ts

@@ -41,7 +41,22 @@ export function messageTokens(message: ChatMessage): number {
       ? (message.reasoning ?? "") +
         (message.toolCalls?.map((call) => call.name + call.arguments).join("") ?? "")
       : "";
-  return estimateTokens(textOf(message) + extra);
+  return estimateTokens(textOf(message) + extra) + reasoningItemTokens(message);
+}
+
+/**
+ * Encrypted reasoning is base64 of the real thing, so its length says little:
+ * three bytes per four characters, less ~650 bytes of envelope, then four bytes
+ * a token (cc-proxy's estimate).
+ */
+function reasoningItemTokens(message: ChatMessage): number {
+  if (message.role !== "assistant" || !message.reasoningItems) return 0;
+  let tokens = 0;
+  for (const item of message.reasoningItems.items) {
+    const blob = (item as { encrypted_content?: unknown } | null)?.encrypted_content;
+    if (typeof blob === "string") tokens += Math.max(0, ((blob.length * 3) / 4 - 650) / 4);
+  }
+  return Math.ceil(tokens);
 }
 
 export function conversationTokens(messages: readonly ChatMessage[]): number {

package/src/errors.ts

@@ -423,6 +423,9 @@ const AUTH_PATTERNS: readonly RegExp[] = [
   /account (?:disabled|suspended|deactivated|banned)/i,
   /unrecognizedclient|unauthorizedexception|accessdeniedexception/i,
   /expired[_\s]?token/i,
+  // OAuth's answer to a refresh token that was revoked, spent or expired. It
+  // arrives as a 400, which on status alone reads as `invalid`.
+  /\binvalid_grant\b/i,
   /OAuth token has been revoked/i,
   // Cloudflare's code 7003, for an account id that names no account. It
   // arrives as a 404, which on status alone reads as a missing model — but

package/src/presets.ts

@@ -7,7 +7,7 @@
  * they drift on a vendor's schedule and a wrong number in a library is a
  * wrong number in everyone's ledger), icons, colors, marketing names, and
  * sign-in flows (an `oauth` preset expects the CALLER to hand over an access
- * token; acquiring one stays app-side).
+ * token; `@providerkit/core/auth` is how to get and renew one).
  *
  * Sources: the coding-plan endpoints and auth quirks are measured
  * (tabrunner's extension + this repo's adopters, 2026-09); the model lists
@@ -31,7 +31,7 @@ export type PresetShape = "anthropic" | "openai" | "responses" | "gemini";
  *   coding-plan gateways' mode on the Anthropic wire (measured: Z.ai's coding
  *   endpoint ignores `x-api-key` and reads Bearer).
  * - `oauth`: same wire as `bearer`, but the token is a short-lived access
- *   token from a sign-in flow the caller owns. The preset may carry the beta
+ *   token from a sign-in flow (see `@providerkit/core/auth`). The preset may carry the beta
  *   headers that switch the endpoint into OAuth mode.
  */
 export type PresetAuth = "key" | "bearer" | "oauth";
@@ -76,6 +76,13 @@ export interface ProviderPreset {
   /** Responses shape: what the backend accepts as an image, for backends that
    *  fail a whole request over one image they won't take. */
   imageLimits?: ImageLimits;
+  /** Responses shape: ask for the encrypted reasoning items, and send them back
+   *  on the next turn. Only for backends that take `include`; `chatgpt` is the
+   *  one that does, and Go and Grok may refuse it. */
+  replayReasoning?: boolean;
+  /** OpenAI shape: send `X-Initiator` (`user` or `agent`) on every call. GitHub
+   *  Copilot bills a premium request per `user` turn. */
+  initiatorHeader?: boolean;
 }
 
 export const PROVIDER_PRESETS = {
@@ -445,7 +452,7 @@ export const PROVIDER_PRESETS = {
     auth: "bearer",
   },
 
-  // ── OAuth — the caller owns the sign-in flow and hands over the token ───
+  // ── OAuth — sign in with `@providerkit/core/auth`, hand over the token ──
   claude: {
     shape: "anthropic",
     baseUrl: "https://api.anthropic.com",
@@ -493,6 +500,7 @@ export const PROVIDER_PRESETS = {
       "gpt-5.6-luna",
       "gpt-5.5",
     ],
+    replayReasoning: true,
   },
   /**
    * A Grok subscription (SuperGrok, X Premium) — the backend the Grok CLI
@@ -530,12 +538,33 @@ export const PROVIDER_PRESETS = {
     auth: "oauth",
     defaultModel: "kimi-for-coding",
   },
+  /**
+   * GitHub Copilot, on an individual seat's host. Other plans have their own
+   * host, which the sign-in returns as `credential.baseUrl`: pass it as
+   * `baseUrl`. Copilot serves chat at `/chat/completions` with no `/v1`, and the
+   * default path would have added one and 404'd.
+   *
+   * The headers are the ones its gate checks on every call. Pass
+   * `copilotHeaders(appName, "user")` from `@providerkit/core/auth` in
+   * `headers` to name your app in `Editor-Version`. `X-Initiator` is set per
+   * call, because it decides what Copilot bills.
+   */
   "github-copilot": {
     shape: "openai",
-    baseUrl: "https://api.githubcopilot.com",
+    baseUrl: "https://api.individual.githubcopilot.com",
+    path: "/chat/completions",
     auth: "oauth",
     defaultModel: "gpt-5.6-sol",
     models: ["gpt-5.6-sol", "claude-opus-5", "claude-sonnet-5", "gpt-6-astra"],
+    headers: {
+      "Copilot-Integration-Id": "vscode-chat",
+      "Editor-Version": "providerkit",
+      "Editor-Plugin-Version": "providerkit",
+      "X-GitHub-Api-Version": "2026-06-01",
+      "Openai-Intent": "conversation-edits",
+      "Copilot-Vision-Request": "true",
+    },
+    initiatorHeader: true,
   },
 } as const satisfies Record<string, ProviderPreset>;
 

package/src/providers/anthropic.ts

@@ -1,5 +1,5 @@
 // Anthropic-shape adapter — SSE from POST /v1/messages.
-import { fileRefused, streamCut, streamError } from "../errors.ts";
+import { fileRefused, ProviderError, streamCut, streamError } from "../errors.ts";
 import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
@@ -371,6 +371,15 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       const effort = opts.effort ?? config.effort;
       const { system, messages: body } = toAnthropicMessages(messages, id);
 
+      // Anthropic's own `service_tier` means auto or standard_only, not this.
+      if (opts.serviceTier) {
+        throw new ProviderError(
+          id,
+          "invalid",
+          `${id}: Anthropic has no priority or flex tier (its service_tier field means something else). ` +
+            "Leave serviceTier unset for Claude models.",
+        );
+      }
       const request: Record<string, unknown> = {
         model,
         max_tokens: maxTokens,

package/src/providers/factory.ts

@@ -20,12 +20,12 @@ import {
   type ProviderPreset,
   type ProviderPresetId,
 } from "../presets.ts";
-import type { Effort, Provider } from "../types.ts";
+import type { Effort, Provider, ServiceTier } from "../types.ts";
 import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 
 export interface PresetProviderConfig extends ProviderFallbackConfig {
   /** The credential: an API key for `key`/`bearer` presets, an ACCESS TOKEN
-   *  for `oauth` ones. Acquiring the token is the caller's job. */
+   *  for `oauth` ones. `@providerkit/core/auth` signs in and renews it. */
   apiKey: string;
   /** Which model to run. Absent = the preset's `defaultModel`; a preset
    *  without either throws rather than sending a request nobody chose. */
@@ -34,6 +34,9 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
    *  take over in order when it fails (quota, rate, outage). Wins over `model`
    *  and the preset's `rotation`; `fallbacks` still run after the chain. */
   models?: readonly string[];
+  /** Replaces the preset's API root. For a vendor that gives each account its
+   *  own host (Copilot: `credential.baseUrl` from the sign-in). */
+  baseUrl?: string;
   effort?: Effort;
   /** Output ceiling. The Anthropic shape requires one; adapters default it. */
   maxTokens?: number;
@@ -57,6 +60,9 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
    *  between rounds — pinning keeps a conversation's rounds (and their cache)
    *  on one host. Empty/absent = default routing. */
   providerOrder?: string[];
+  /** Default `service_tier` for every call on the OpenAI and Responses shapes;
+   *  `StreamOptions.serviceTier` wins. Anthropic and Gemini presets refuse it. */
+  serviceTier?: ServiceTier;
   fetchImpl?: typeof fetch;
 }
 
@@ -85,7 +91,14 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
   if (!model) {
     throw new Error(`[providerkit] Preset "${id}" has no defaultModel — pass a model.`);
   }
+  if (config.serviceTier && (preset.shape === "anthropic" || preset.shape === "gemini")) {
+    throw new Error(
+      `[providerkit] Preset "${id}" speaks the ${preset.shape} shape, which has no service tier. ` +
+        "Remove serviceTier.",
+    );
+  }
   const headers = { ...preset.headers, ...config.headers };
+  const baseUrl = config.baseUrl ?? preset.baseUrl;
   const maxTokens = config.maxTokens ?? preset.maxTokens;
 
   const {
@@ -107,7 +120,7 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         model,
         effort: config.effort,
         maxTokens,
-        baseUrl: preset.baseUrl,
+        baseUrl,
         id,
         headers,
         bearer: preset.auth !== "key",
@@ -125,11 +138,12 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         model,
         effort: config.effort,
         maxTokens,
-        baseUrl: preset.baseUrl,
+        baseUrl,
         ...(preset.path ? { path: preset.path } : {}),
         headers,
         ...(config.providerOrder ? { providerOrder: config.providerOrder } : {}),
         ...(preset.sessionHeader ? { sessionHeader: preset.sessionHeader } : {}),
+        ...(preset.initiatorHeader ? { initiatorHeader: true } : {}),
         fetchImpl: config.fetchImpl,
       });
       break;
@@ -140,12 +154,13 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         model,
         effort: config.effort,
         maxTokens,
-        baseUrl: preset.baseUrl,
+        baseUrl,
         ...(preset.path ? { path: preset.path } : {}),
         id,
         headers,
         ...(preset.sessionHeader ? { sessionHeader: preset.sessionHeader } : {}),
         ...(preset.imageLimits ? { imageLimits: preset.imageLimits } : {}),
+        ...(preset.replayReasoning ? { replayReasoning: true } : {}),
         fetchImpl: config.fetchImpl,
       });
       break;
@@ -155,7 +170,7 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         apiKey: config.apiKey,
         model,
         effort: config.effort,
-        baseUrl: preset.baseUrl,
+        baseUrl,
         id,
         headers,
         fetchImpl: config.fetchImpl,

package/src/providers/gemini.ts

@@ -320,6 +320,13 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         generationConfig.responseJsonSchema = toGeminiToolSchema(opts.json.schema);
       }
 
+      if (opts.serviceTier) {
+        throw new ProviderError(
+          id,
+          "invalid",
+          `${id}: Gemini has no service tier switch. Leave serviceTier unset for Gemini models.`,
+        );
+      }
       const request: Record<string, unknown> = { contents, generationConfig };
       // A Content, not the bare string the SDK accepts — REST rejects a string.
       // The prompt-carried schema rides as a second part, after the caller's

package/src/providers/openai.ts

@@ -14,6 +14,7 @@ import type {
   JsonWithTools,
   Provider,
   ProviderChunk,
+  ServiceTier,
   StreamOptions,
   ToolDefinition,
 } from "../types.ts";
@@ -104,6 +105,12 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *  no sessionId, the provider's own per-instance id rides instead, so the
    *  gateway never sees a call without one. */
   sessionHeader?: string;
+  /** Send `X-Initiator`: `user` when the last message is the user's, else
+   *  `agent`. GitHub Copilot bills a premium request per `user` turn and lets
+   *  the agent's own follow-ups (tool results) ride free. */
+  initiatorHeader?: boolean;
+  /** Default `service_tier` for every call; `StreamOptions.serviceTier` wins. */
+  serviceTier?: ServiceTier;
 }
 
 const DEFAULT_BASE_URL = "https://api.openai.com";
@@ -487,6 +494,8 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       if (opts.temperature !== undefined) request.temperature = opts.temperature;
       if (opts.topP !== undefined) request.top_p = opts.topP;
       if (opts.stopSequences?.length) request.stop = opts.stopSequences;
+      const serviceTier = opts.serviceTier ?? config.serviceTier;
+      if (serviceTier) request.service_tier = serviceTier;
       Object.assign(request, effortParams(config.effortDialect ?? dialectFor(id), effort, model));
       if (tools.length > 0) {
         request.tools = tools.map((tool) => ({
@@ -582,6 +591,9 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
           ...(config.sessionHeader
             ? { [config.sessionHeader]: opts.sessionId ?? instanceSessionId }
             : {}),
+          ...(config.initiatorHeader
+            ? { "X-Initiator": messages.at(-1)?.role === "user" ? "user" : "agent" }
+            : {}),
           ...config.headers,
         },
         body: request,