@intelligo-dev/chat 1.0.0-beta.13

package/src/config.ts

@@ -0,0 +1,376 @@
+/**
+ * What an application tells the chat transport. Two things are required,
+ * the execution boundary and a way to run the model; everything else has a
+ * default that gives a clean install a working chat with no API keys.
+ * Optional seams close over the caller's tenancy, so the model is never told
+ * which workspace it is in. `streamTurn` replaces the model call and nothing
+ * else: auth, rate limit, gate, admission, persistence and settlement stay
+ * the transport's.
+ */
+
+import type {
+  LanguageModel,
+  StopCondition,
+  ToolSet,
+  UIMessage,
+  UIMessageChunk,
+  UIMessageStreamWriter,
+} from "ai";
+import type { streamText } from "ai";
+
+/** The provider-specific options `streamText` accepts (`ai` does not export the type). */
+export type ProviderOptions = NonNullable<
+  Parameters<typeof streamText>[0]["providerOptions"]
+>;
+
+import type { Conversation } from "@intelligo-dev/core/conversations";
+import type { Executions } from "@intelligo-dev/executions";
+
+import type { ChatAttachmentPolicy } from "./body";
+import type { ChatErrorCode, ChatModelOption } from "./client";
+import type { ChatMessages } from "./errors";
+import type { ChatGenerationOptions } from "./generation";
+import type { ChatDataChunk, ChatUIMessage } from "./parts";
+import type { TokenUsage } from "./usage";
+import type { ConversationWindowOptions } from "./windowing";
+
+export type { ChatAttachmentPolicy } from "./body";
+export type { ChatMessages, ChatMessageKey, ChatMessageParams } from "./errors";
+export type { ChatGenerationOptions } from "./generation";
+
+/** The resolved caller. Every read and write is scoped to this pair. */
+export interface ChatActor {
+  workspaceId: string;
+  userId: string;
+}
+
+/** What is known about a turn before the agent is resolved. */
+export interface ChatTurnContext extends ChatActor {
+  request: Request;
+  conversationId: string;
+  /**
+   * Fields the client transport sent beyond the AI SDK's own — an
+   * `agentId`, a `modelId`. Opaque to the transport; `resolveAgent`
+   * reads them. `modelId` is also read by the default resolution when
+   * `models` is configured.
+   */
+  body: Record<string, unknown>;
+  /** The existing row, or null on a conversation's first turn. */
+  conversation: Conversation | null;
+  trigger: "submit-message" | "regenerate-message" | undefined;
+  /**
+   * Write a part to the client mid-turn — a status line, a task plan,
+   * a document streaming into the canvas (`createArtifactWriter`). A
+   * no-op before the stream opens and after it closes, so a tool bound
+   * through `agent.tools` may hold on to it.
+   */
+  write: (chunk: ChatDataChunk) => void;
+  /**
+   * Merge a patch into the conversation's `metadata` — a runtime's
+   * session id, a summary of pruned history. Shallow: top-level keys
+   * are replaced, other keys kept. Rejects before the row exists.
+   */
+  updateMetadata: (patch: Record<string, unknown>) => Promise<void>;
+  /**
+   * Add the tokens a tool spent on its own model call — a search that
+   * asks a model, a sub-agent — to what this turn settles. They are
+   * priced as the turn's model, so a call on another model is its own
+   * execution rather than usage added here. Usage added after the run
+   * settles is not charged.
+   */
+  addUsage: (usage: TokenUsage) => void;
+}
+
+/** The agent this turn runs as. */
+export interface ResolvedAgent {
+  /** Stored on the conversation row when the transport creates it. */
+  id: string;
+  systemPrompt: string;
+  tools?: ToolSet;
+  /** Names the model may call this turn; every tool when omitted. */
+  activeTools?: string[];
+  /**
+   * Added after `stepCountIs(maxSteps)`, e.g. `hasToolCall("askUser")`.
+   *
+   * Consulted only on a turn that has tools: the SDK stops a run on
+   * this condition "when there are tool results in the last step", and
+   * a turn with no tools never has any, so it is a single step either
+   * way. The step cap itself is not removable — an uncapped step count
+   * is an uncapped bill.
+   */
+  stopWhen?: StopCondition<ToolSet> | StopCondition<ToolSet>[];
+  /** Overrides the request's and the config's model. Must be a registered model id. */
+  modelId?: string;
+  maxSteps?: number;
+  /** Overrides the config's; `null` disables the gate for this agent. */
+  featureKey?: string | null;
+  capability?: string;
+  /**
+   * Passed to `streamText` as-is — the provider's own knobs, e.g. a
+   * thinking budget (`{ google: { thinkingConfig: { includeThoughts: true } } }`,
+   * `{ anthropic: { thinking: { type: "enabled", budgetTokens: 2048 } } }`).
+   * With `reasoning: true` this is what makes a model's thoughts reach
+   * the transcript at all; the transport never names a provider.
+   */
+  providerOptions?: ProviderOptions;
+  /**
+   * How the model samples this turn — temperature, a token ceiling, a
+   * tool choice, a seed. An allowlist of the `streamText` options that
+   * do not touch settlement; see `ChatGenerationOptions` for what the
+   * transport keeps and why.
+   */
+  generation?: ChatGenerationOptions;
+}
+
+/**
+ * The one-agent shorthand, derived from `ResolvedAgent` so the two
+ * cannot drift: everything a `resolveAgent` function can return is
+ * settable here too, and the three fields below are the only ones that
+ * differ — an id and a prompt because the transport has defaults for
+ * them, and tools because the shorthand may close over the turn.
+ */
+export interface ChatAgentConfig extends Omit<
+  ResolvedAgent,
+  "id" | "systemPrompt" | "tools"
+> {
+  /** Default `"assistant"`. */
+  id?: string;
+  systemPrompt?: string;
+  tools?: ToolSet | ((turn: ChatTurnContext) => ToolSet | Promise<ToolSet>);
+}
+
+/** A turn with its agent resolved — what the hooks below receive. */
+export interface ChatTurn extends ChatTurnContext {
+  agent: ResolvedAgent;
+  /** The persisted history, read lazily: not every `prepareMessages` needs it. */
+  history: () => Promise<UIMessage[]>;
+}
+
+/** What the model is shown. */
+export interface PreparedTurn {
+  messages: UIMessage[];
+  /** Replaces the agent's system prompt when set — a summary prefix, injected context. */
+  system?: string;
+}
+
+/**
+ * A turn produced by something other than `streamText`.
+ *
+ * `stream` carries the AI SDK's UI message chunks. The transport writes
+ * `start` and `finish` itself and drops any the stream emits, so a
+ * runtime whose adapter already frames the message needs no stripping.
+ * `usage` settles the execution: it resolves once the run is over,
+ * with the whole run's tokens. On a client abort the transport settles
+ * with whatever `usage` resolves to; reject it and the turn is failed.
+ */
+export interface TurnStream {
+  stream: ReadableStream<UIMessageChunk>;
+  usage: Promise<
+    TokenUsage & {
+      modelId?: string;
+      finishReason?: string;
+    }
+  >;
+}
+
+export type StreamTurn = (
+  turn: ChatTurn,
+  prepared: PreparedTurn,
+  context: {
+    modelId: string;
+    abortSignal: AbortSignal;
+    writer: UIMessageStreamWriter<ChatUIMessage>;
+  }
+) => TurnStream | Promise<TurnStream>;
+
+export interface RateLimitDecision {
+  allowed: boolean;
+  retryAfterSeconds?: number;
+  limit?: number;
+  remaining?: number;
+  resetAt?: Date;
+}
+
+export interface ChatTurnEvents {
+  /** The execution is open and the model is about to run. */
+  start?: (event: {
+    turn: ChatTurn;
+    executionId: string;
+    requestId: string;
+    modelId: string;
+  }) => void | Promise<void>;
+  /** The run settled — after a normal finish, or after the client aborted. */
+  complete?: (event: {
+    turn: ChatTurn;
+    executionId: string;
+    modelId: string;
+    usage: TokenUsage;
+    aborted: boolean;
+    finishReason?: string;
+    rawFinishReason?: string;
+    providerMetadata?: unknown;
+    warnings?: unknown[];
+  }) => void | Promise<void>;
+  /** Something threw. `phase` says where; the turn may or may not have an agent yet. */
+  fail?: (event: {
+    turn: ChatTurnContext;
+    error: unknown;
+    phase: "stream" | "settlement" | "persistence" | "title" | "unhandled";
+  }) => void | Promise<void>;
+  /** The transport answered with a refusal rather than a stream. */
+  refuse?: (event: {
+    actor: ChatActor | null;
+    conversationId: string | null;
+    code: ChatErrorCode;
+    status: number;
+    reasonCode?: string;
+  }) => void | Promise<void>;
+  /**
+   * The user answered a tool's approval request. Fired once per
+   * response, from the continuation turn that carries it — the audit
+   * trail a product needs for a gated action.
+   */
+  approval?: (event: {
+    turn: ChatTurnContext;
+    toolName: string;
+    toolCallId: string;
+    approvalId: string;
+    approved: boolean;
+    reason?: string;
+  }) => void | Promise<void>;
+  /** The reader voted on a reply, or cleared a vote. */
+  feedback?: (event: {
+    actor: ChatActor;
+    conversationId: string;
+    messageId: string;
+    vote: "up" | "down" | null;
+  }) => void | Promise<void>;
+}
+
+export interface ChatModelsConfig {
+  /**
+   * Models the request may ask for by `modelId`. A list, or a function
+   * of the caller for a list that depends on the plan. A request naming
+   * a model outside it, or one whose `featureKey` the workspace lacks,
+   * is refused as `FEATURE_GATED` with reason `model_not_allowed`.
+   */
+  options:
+    | ChatModelOption[]
+    | ((actor: ChatActor) => ChatModelOption[] | Promise<ChatModelOption[]>);
+}
+
+export interface ChatServerConfig {
+  /** The execution boundary, with its ports bound by the composition root. */
+  executions: Executions;
+  model: {
+    /** Must be registered in `@intelligo-dev/executions/pricing`. */
+    defaultId: string;
+    /**
+     * Turns a model id into a model for `streamText`. Required unless
+     * `streamTurn` is set, and unused when it is.
+     */
+    resolve?: (
+      modelId: string,
+      turn: ChatTurnContext
+    ) => LanguageModel | Promise<LanguageModel>;
+  };
+  /**
+   * Runs the turn instead of `streamText` — a Mastra agent, an eve
+   * session, a workflow. Everything around the model call stays the
+   * transport's. See `TurnStream`.
+   */
+  streamTurn?: StreamTurn;
+
+  /** Runs first on every request — the place to call `composeIntelligo()`. */
+  onRequest?: () => void | Promise<void>;
+  /** Plan feature key gating the surface. `null` disables the gate. Default `"chat"`. */
+  featureKey?: string | null;
+  /** Capability recorded on each execution. Default `"chat.message"`. */
+  capability?: string;
+  /** Longest user message accepted, in characters. Default 8000. */
+  maxMessageLength?: number;
+  /** Model steps one turn may take (a tool call and the reply using it are two). Default 5. */
+  maxSteps?: number;
+
+  /**
+   * The one-agent shorthand. Ignored when `resolveAgent` is set.
+   * `tools` may close over the turn's tenancy.
+   */
+  agent?: ChatAgentConfig;
+  /**
+   * Which agent runs this turn — from the body, the row, a table. The
+   * default resolves `agent`, keeping the id the conversation was
+   * created with.
+   */
+  resolveAgent?: (
+    turn: ChatTurnContext
+  ) => ResolvedAgent | Promise<ResolvedAgent>;
+  /** The models a request may pick from. Unset: every request runs the default. */
+  models?: ChatModelsConfig;
+  /**
+   * What the model is shown. The default windows the incoming
+   * transcript by `windowing`. An application that prunes, summarises
+   * or injects context binds its own; `turn.history()` reads the
+   * persisted messages when the client's copy is not to be trusted.
+   */
+  prepareMessages?: (
+    turn: ChatTurn,
+    incoming: UIMessage[]
+  ) => PreparedTurn | Promise<PreparedTurn>;
+  /** Default `{ maxMessages: 40 }`; `false` shows the model everything. */
+  windowing?: ConversationWindowOptions | false;
+  /** File parts the transport accepts. Default `false`: any file part is a 400. */
+  attachments?: ChatAttachmentPolicy | false;
+  /** Stream the model's reasoning parts to the client. Default false. */
+  reasoning?: boolean;
+  /** Stream the model's source parts (citations) to the client. Default false. */
+  sources?: boolean;
+  /**
+   * Attach `{ modelId, usage, finishedAt }` to the assistant message as
+   * its metadata when the turn finishes. Default true.
+   */
+  messageMetadata?: boolean;
+  /**
+   * Answer cross-origin requests from these origins — an embedded
+   * widget on another site. Unset: no CORS headers, same-origin only.
+   */
+  cors?: { origins: readonly string[] };
+
+  /**
+   * Titles a conversation from its first user message when the row is
+   * created. Sync: stored on create. Async: the row is created untitled,
+   * renamed when the promise resolves, and the client is sent a
+   * transient `data-chat-title` part. Default: first line, truncated.
+   */
+  deriveTitle?: (
+    firstUserText: string,
+    turn: ChatTurnContext
+  ) => string | null | Promise<string | null>;
+  /**
+   * Where the turn's messages go. Default: the user message that
+   * opened the turn and the assistant reply, upserted through core.
+   * `false` persists nothing.
+   */
+  persist?:
+    | false
+    | ((
+        turn: ChatTurn,
+        result: {
+          userMessage: UIMessage | null;
+          responseMessage: UIMessage;
+          isContinuation: boolean;
+        }
+      ) => Promise<void>);
+  /** Adjusts what settlement records — a floor for providers that report nothing. */
+  normalizeUsage?: (usage: TokenUsage) => TokenUsage;
+  /** Merged into the execution's metadata on begin and complete. */
+  metadata?: (turn: ChatTurn) => Record<string, unknown>;
+  onTurn?: ChatTurnEvents;
+
+  /** Localised refusal copy. Default: English. */
+  messages?: (request: Request) => ChatMessages | Promise<ChatMessages>;
+  /** Default: `requireWorkspace()`. Throw to answer 401. */
+  authenticate?: (request: Request) => Promise<ChatActor>;
+  /** Default: the workspace plan's per-minute limit. `false` disables. */
+  rateLimit?: false | ((actor: ChatActor) => Promise<RateLimitDecision>);
+}

package/src/errors.ts

@@ -0,0 +1,80 @@
+/**
+ * Refusals: one status per code, one message key per situation.
+ *
+ * The transport never invents copy. It asks a translator for a key,
+ * and the application binds that translator to its own message files
+ * (`messages(request)` in the config). The English table below is the
+ * default a deployment gets when it binds nothing.
+ */
+
+import type { ChatErrorBody, ChatErrorCode } from "./client";
+
+export const CHAT_ERROR_STATUS: Readonly<Record<ChatErrorCode, number>> = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  QUOTA_EXCEEDED: 402,
+  FEATURE_GATED: 403,
+  NOT_FOUND: 404,
+  RATE_LIMITED: 429,
+  INTERNAL: 500,
+  BILLING_NOT_CONFIGURED: 503,
+  MODEL_UNAVAILABLE: 503,
+};
+
+/**
+ * Every message the transport can answer with. One key per situation,
+ * not per code: `BAD_REQUEST` has three.
+ */
+export type ChatMessageKey =
+  | "invalidBody"
+  | "messageTooLong"
+  | "attachmentRejected"
+  | "unauthorized"
+  | "rateLimited"
+  | "featureGated"
+  | "notFound"
+  | "quotaExceeded"
+  | "billingNotConfigured"
+  | "modelUnavailable"
+  | "internalError"
+  | "streamError";
+
+export type ChatMessageParams = Record<string, string | number>;
+
+/** Resolves a message key in the caller's locale. */
+export type ChatMessages = (
+  key: ChatMessageKey,
+  params?: ChatMessageParams
+) => string;
+
+const ENGLISH: Readonly<Record<ChatMessageKey, string>> = {
+  invalidBody: "Invalid request body.",
+  messageTooLong: "Message is too long (max {max} characters).",
+  attachmentRejected: "That attachment type isn't accepted.",
+  unauthorized: "Unauthorized.",
+  rateLimited: "Rate limit exceeded. Try again in {seconds}s.",
+  featureGated: "Chat isn't included in your current plan.",
+  notFound: "That conversation no longer exists.",
+  quotaExceeded: "Usage quota exceeded. Upgrade your plan or purchase credits.",
+  billingNotConfigured: "Billing is not configured for this deployment.",
+  modelUnavailable: "Chat is temporarily unavailable. Please try again later.",
+  internalError: "Something went wrong.",
+  streamError: "Something went wrong while generating a response.",
+};
+
+/** The default translator: English, with `{param}` interpolation. */
+export const DEFAULT_CHAT_MESSAGES: ChatMessages = (key, params = {}) =>
+  ENGLISH[key].replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in params ? String(params[name]) : match
+  );
+
+/** A JSON refusal with the status its code fixes. */
+export function refuse(
+  code: ChatErrorCode,
+  error: string,
+  extra: Partial<Omit<ChatErrorBody, "error" | "code">> = {},
+  headers: Record<string, string> = {}
+): Response {
+  const body: ChatErrorBody = { error, code, ...extra };
+  return Response.json(body, { status: CHAT_ERROR_STATUS[code], headers });
+}

package/src/feedback.ts

@@ -0,0 +1,62 @@
+/**
+ * A reader's verdict on a reply, recorded once and reported once.
+ *
+ * The registry's `voteMessage` action is two lines over this: the
+ * write goes through core's votes table, and the `feedback` hook is
+ * the one place telemetry learns about it — the same hook whether the
+ * vote came from the page, a panel or a widget.
+ */
+
+import {
+  clearVote,
+  isConversationServiceError,
+  voteMessage,
+} from "@intelligo-dev/core/conversations";
+
+import type { ChatActor, ChatServerConfig } from "./config";
+
+export type ChatFeedback = "up" | "down" | null;
+
+export type RecordChatFeedbackResult =
+  { ok: true } | { ok: false; code: "not_found" | "database_error" };
+
+export async function recordChatFeedback(
+  config: Pick<ChatServerConfig, "onTurn">,
+  actor: ChatActor,
+  params: { conversationId: string; messageId: string; vote: ChatFeedback }
+): Promise<RecordChatFeedbackResult> {
+  try {
+    if (params.vote === null) {
+      await clearVote(actor, {
+        chatId: params.conversationId,
+        messageId: params.messageId,
+      });
+    } else {
+      await voteMessage(actor, {
+        chatId: params.conversationId,
+        messageId: params.messageId,
+        type: params.vote,
+      });
+    }
+  } catch (error) {
+    if (
+      isConversationServiceError(error) &&
+      (error.code === "not_found" || error.code === "forbidden")
+    ) {
+      return { ok: false, code: "not_found" };
+    }
+    return { ok: false, code: "database_error" };
+  }
+
+  try {
+    await config.onTurn?.feedback?.({
+      actor,
+      conversationId: params.conversationId,
+      messageId: params.messageId,
+      vote: params.vote,
+    });
+  } catch {
+    // Telemetry must never fail a vote.
+  }
+  return { ok: true };
+}

package/src/generation.ts

@@ -0,0 +1,150 @@
+/**
+ * The `streamText` options a product may set per turn: how the model
+ * samples (temperature, a token ceiling, a tool choice, a seed), none of
+ * which changes what settlement reads back. Written out as an allowlist
+ * rather than an `Omit<>` over the SDK's type, so an option a later SDK adds
+ * is not admitted silently.
+ *
+ * What the transport keeps, and why each one is not negotiable:
+ *
+ *   `abortSignal`   without `request.signal` an abandoned run bills in
+ *                   full and `onAbort` never fires.
+ *   `timeout`       a timeout lands on the error path, which releases
+ *                   the hold without charging tokens the provider has
+ *                   already produced. The route's deadline is
+ *                   `maxDuration`.
+ *   `onFinish`,     the transport captures `totalUsage` there; replacing
+ *   `onEnd`         it means every turn ends "stream ended without
+ *                   usage".
+ *   `onAbort`       settles from `sumStepUsage(steps)`.
+ *   `onError`       the failure path is `run.fail()` plus localised copy.
+ *   `model`         admission already priced the resolved `modelId`;
+ *                   another model bills one admission never saw.
+ *   `system`,       `prepareMessages` owns what the model is shown.
+ *   `messages`,
+ *   `prompt`,
+ *   `instructions`
+ *   `tools`,        already seams on the agent, and the same object
+ *   `activeTools`   feeds `convertToModelMessages`; a second source
+ *                   desynchronises the two.
+ *   `stopWhen`      `stepCountIs(maxSteps)` must stay first and
+ *                   unremovable — an uncapped step count is an uncapped
+ *                   bill. `ResolvedAgent.stopWhen` appends to it.
+ *   `_internal`     the SDK's own test seam, not a product knob.
+ *
+ * Enforced three ways, because a cast defeats the type: the type itself,
+ * `pickGenerationOptions` copying only `GENERATION_KEYS` at runtime, and the
+ * handler spreading the result *first* so the transport's own keys win.
+ */
+
+import type {
+  LanguageModelCallOptions,
+  PrepareStepFunction,
+  RequestOptions,
+  StreamTextTransform,
+  TelemetryOptions,
+  ToolChoice,
+  ToolSet,
+} from "ai";
+import type { streamText } from "ai";
+
+/**
+ * Settlement-neutral `streamText` options, sourced from the SDK's own
+ * types by indexed access so that a signature change upstream is a
+ * compile error here rather than a silently dropped field.
+ *
+ * Nested under `generation` rather than flattened onto `ResolvedAgent`
+ * for a concrete reason: `ai` has its own `reasoning` (an effort level
+ * for the model) and `ChatServerConfig.reasoning` already means "stream
+ * reasoning parts to the client". Flattening would put two different
+ * `reasoning` in one namespace, and every future SDK option would be
+ * one name collision away from a framework field.
+ */
+export interface ChatGenerationOptions {
+  /**
+   * Ceiling on the tokens one step may produce. Unset, the transport
+   * uses the registered model's `maxOutputTokens` — the figure admission
+   * sized its hold with. A larger value here lets a step cost more than
+   * was held.
+   */
+  maxOutputTokens?: LanguageModelCallOptions["maxOutputTokens"];
+  temperature?: LanguageModelCallOptions["temperature"];
+  topP?: LanguageModelCallOptions["topP"];
+  topK?: LanguageModelCallOptions["topK"];
+  presencePenalty?: LanguageModelCallOptions["presencePenalty"];
+  frequencyPenalty?: LanguageModelCallOptions["frequencyPenalty"];
+  stopSequences?: LanguageModelCallOptions["stopSequences"];
+  seed?: LanguageModelCallOptions["seed"];
+  /**
+   * The model's reasoning effort — not `ChatServerConfig.reasoning`,
+   * which decides whether reasoning parts reach the client.
+   */
+  reasoning?: LanguageModelCallOptions["reasoning"];
+  /** Retries on a failed provider call. A retried call still reports one `totalUsage`. */
+  maxRetries?: RequestOptions["maxRetries"];
+  headers?: RequestOptions["headers"];
+  /** Picks among the tools the agent already declared; cannot introduce one. */
+  toolChoice?: ToolChoice<ToolSet>;
+  /** Per-step adjustment inside a loop the transport still caps with `maxSteps`. */
+  prepareStep?: PrepareStepFunction<ToolSet>;
+  /** Observation only. The current name; `experimental_telemetry` is the SDK's deprecated alias. */
+  telemetry?: TelemetryOptions;
+  /** Transforms the text stream. Usage is computed from steps, not from the transformed text. */
+  experimental_transform?: StreamTextTransform<ToolSet>;
+  /** Per-step observation `onTurn` has no equivalent for. */
+  onStepEnd?: Parameters<typeof streamText>[0]["onStepEnd"];
+}
+
+/**
+ * Every key of `ChatGenerationOptions`, as values.
+ *
+ * `satisfies` proves the array holds only real keys; `Exhaustive` below
+ * proves it holds all of them, so a field added to the interface
+ * without a line here is a compile error rather than an option that
+ * silently never reaches the model.
+ */
+export const GENERATION_KEYS = [
+  "maxOutputTokens",
+  "temperature",
+  "topP",
+  "topK",
+  "presencePenalty",
+  "frequencyPenalty",
+  "stopSequences",
+  "seed",
+  "reasoning",
+  "maxRetries",
+  "headers",
+  "toolChoice",
+  "prepareStep",
+  "telemetry",
+  "experimental_transform",
+  "onStepEnd",
+] as const satisfies ReadonlyArray<keyof ChatGenerationOptions>;
+
+/** Fails to compile if `GENERATION_KEYS` misses a key of the interface. */
+type Missing = Exclude<
+  keyof ChatGenerationOptions,
+  (typeof GENERATION_KEYS)[number]
+>;
+// Stryker disable next-line BooleanLiteral: equivalent — the assertion is the type annotation, which `tsc` checks and the test runner's transform strips; the value itself is never read, so `false` changes nothing a test could observe.
+const _exhaustive: Missing extends never ? true : never = true;
+void _exhaustive;
+
+/**
+ * The allowlisted options, copied by name.
+ *
+ * Absent keys produce no own property rather than an explicit
+ * `undefined`: the handler spreads the result into a call where a
+ * present-but-undefined key would override the SDK's own default.
+ */
+export function pickGenerationOptions(
+  options: ChatGenerationOptions | undefined
+): Partial<ChatGenerationOptions> {
+  if (!options) return {};
+  const picked: Record<string, unknown> = {};
+  for (const key of GENERATION_KEYS) {
+    if (options[key] !== undefined) picked[key] = options[key];
+  }
+  return picked as Partial<ChatGenerationOptions>;
+}