@effect-uai/responses 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@effect-uai/responses",
+  "version": "0.1.0",
+  "description": "OpenAI Responses API provider for @effect-uai/core.",
+  "keywords": [
+    "ai",
+    "effect",
+    "llm",
+    "openai",
+    "responses-api"
+  ],
+  "homepage": "https://github.com/betalyra/effect-uai/tree/main/packages/providers/responses",
+  "bugs": {
+    "url": "https://github.com/betalyra/effect-uai/issues"
+  },
+  "license": "MIT",
+  "author": "Betalyra",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/betalyra/effect-uai",
+    "directory": "packages/providers/responses"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-beta.57",
+    "@effect-uai/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "effect": "4.0.0-beta.57",
+    "typescript": "^6.0.3",
+    "@effect-uai/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/Responses.ts

@@ -0,0 +1,316 @@
+import { Context, Effect, Layer, Match, Option, Redacted, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import { matchType } from "@effect-uai/core/Match"
+import * as StructuredFormat from "@effect-uai/core/StructuredFormat"
+import {
+  type CommonRequest,
+  LanguageModel,
+  type LanguageModelService,
+} from "@effect-uai/core/LanguageModel"
+import * as SSE from "@effect-uai/core/SSE"
+import type { TurnEvent } from "@effect-uai/core/Turn"
+import { itemsToInput } from "./codec.js"
+import type { OpenAIModel } from "./models.js"
+import {
+  KnownProviderEvent,
+  ProviderEvent,
+  eventToDeltas,
+  makeCallIdLookup,
+} from "./streamEvents.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ResponsesRequest extends Omit<CommonRequest, "model"> {
+  /**
+   * Narrows `CommonRequest.model` (`string`) to the typed `OpenAIModel`
+   * literal union for autocomplete.
+   */
+  readonly model: OpenAIModel
+  readonly reasoning?: { readonly effort: "low" | "medium" | "high" }
+  readonly store?: boolean
+  readonly previousResponseId?: string
+  readonly instructions?: string
+  readonly parallelToolCalls?: boolean
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly user?: string
+  readonly safetyIdentifier?: string
+  readonly promptCacheKey?: string
+  readonly truncation?: "auto" | "disabled"
+  /**
+   * Free-form JSON output: model emits valid JSON without schema
+   * constraints. Mutually exclusive with `structured` (schema wins if
+   * both are set).
+   */
+  readonly responseFormat?: { readonly type: "json_object" }
+  /**
+   * Answer length / level-of-detail hint. GPT-5+ models honour it;
+   * earlier models ignore.
+   */
+  readonly verbosity?: "low" | "medium" | "high"
+}
+
+export interface ResponsesService {
+  /**
+   * Stream the provider's native event vocabulary (post-SSE-decode).
+   * Use this when you need full vendor fidelity. For provider-portable
+   * code, use `streamTurn` instead.
+   */
+  readonly streamNative: (
+    request: ResponsesRequest,
+  ) => Stream.Stream<ProviderEvent, AiError.AiError>
+  /**
+   * Stream canonical `TurnEvent`s. Implemented as
+   * `streamNative |> toCanonical`.
+   */
+  readonly streamTurn: (request: ResponsesRequest) => Stream.Stream<TurnEvent, AiError.AiError>
+  /**
+   * Project a stream of native `ProviderEvent`s into canonical `TurnEvent`s.
+   * Exposed for cases where consumers want to compose with `streamNative`
+   * directly (e.g. tap into natives + still get canonical downstream).
+   */
+  readonly toCanonical: <E, R>(
+    s: Stream.Stream<ProviderEvent, E, R>,
+  ) => Stream.Stream<TurnEvent, E, R>
+}
+
+/**
+ * Provider-typed service tag. Yield this when you want Responses-specific
+ * options (`reasoning.effort`, `store`, `previousResponseId`) at the call
+ * site. Yield the generic `LanguageModel` tag for provider-portable code -
+ * both are registered by `layer`.
+ */
+export class Responses extends Context.Service<Responses, ResponsesService>()(
+  "@betalyra/effect-uai/providers/responses/Responses",
+) {}
+
+export interface Config {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+}
+
+// ---------------------------------------------------------------------------
+// Request body
+// ---------------------------------------------------------------------------
+
+const jsonSchemaFormat = (
+  format: StructuredFormat.StructuredFormat<unknown>,
+): Record<string, unknown> => ({
+  type: "json_schema",
+  name: format.name,
+  schema: format.schema["~standard"].jsonSchema.input({ target: "draft-2020-12" }),
+  ...(format.description !== undefined && { description: format.description }),
+  ...(format.strict !== undefined && { strict: format.strict }),
+})
+
+const buildText = (request: ResponsesRequest): Record<string, unknown> | undefined => {
+  const format =
+    request.structured !== undefined ? jsonSchemaFormat(request.structured) : request.responseFormat
+  const text: Record<string, unknown> = {}
+  if (format !== undefined) text.format = format
+  if (request.verbosity !== undefined) text.verbosity = request.verbosity
+  return Object.keys(text).length === 0 ? undefined : text
+}
+
+const buildBody = (request: ResponsesRequest): Record<string, unknown> => {
+  const text = buildText(request)
+  return {
+    model: request.model,
+    input: itemsToInput(request.history),
+    stream: true,
+    ...(request.tools !== undefined &&
+      request.tools.length > 0 && {
+        tools: request.tools.map((t) => ({
+          type: "function",
+          name: t.name,
+          description: t.description,
+          parameters: t.inputSchema,
+          ...(t.strict !== undefined && { strict: t.strict }),
+        })),
+      }),
+    ...(request.toolChoice !== undefined && { tool_choice: request.toolChoice }),
+    ...(request.temperature !== undefined && { temperature: request.temperature }),
+    ...(request.maxOutputTokens !== undefined && {
+      max_output_tokens: request.maxOutputTokens,
+    }),
+    ...(request.reasoning !== undefined && { reasoning: request.reasoning }),
+    ...(request.store !== undefined && { store: request.store }),
+    ...(request.previousResponseId !== undefined && {
+      previous_response_id: request.previousResponseId,
+    }),
+    ...(request.instructions !== undefined && { instructions: request.instructions }),
+    ...(request.topP !== undefined && { top_p: request.topP }),
+    ...(request.parallelToolCalls !== undefined && {
+      parallel_tool_calls: request.parallelToolCalls,
+    }),
+    ...(request.metadata !== undefined && { metadata: request.metadata }),
+    ...(request.user !== undefined && { user: request.user }),
+    ...(request.safetyIdentifier !== undefined && {
+      safety_identifier: request.safetyIdentifier,
+    }),
+    ...(request.promptCacheKey !== undefined && {
+      prompt_cache_key: request.promptCacheKey,
+    }),
+    ...(request.truncation !== undefined && { truncation: request.truncation }),
+    ...(text !== undefined && { text }),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SSE event → provider event
+// ---------------------------------------------------------------------------
+
+const decodeKnown = Schema.decodeUnknownEffect(KnownProviderEvent)
+
+const makeUnknown = (raw: unknown): ProviderEvent => ({ type: "_unknown", raw })
+
+/**
+ * Lift events that carry a terminal failure signal (`error`,
+ * `response.failed`) to a typed `AiError`. Other events are not failures
+ * and produce `Option.none`.
+ */
+const eventToError = Match.type<ProviderEvent>().pipe(
+  matchType(
+    "error",
+    (e): AiError.AiError => new AiError.Unavailable({ provider: "responses", raw: e }),
+  ),
+  matchType("response.failed", (e): AiError.AiError => {
+    const code = e.response.error?.code
+    const message = e.response.error?.message
+    return new AiError.GenerationFailed({
+      provider: "responses",
+      ...(code !== undefined && code !== null && { code }),
+      ...(message !== undefined && message !== null && { message }),
+      raw: e,
+    })
+  }),
+  Match.option,
+)
+
+const sseEventToProviderEvent = (ev: SSE.Event): Effect.Effect<ProviderEvent> =>
+  Effect.try({
+    try: () => JSON.parse(ev.data) as unknown,
+    catch: () => ev.data,
+  }).pipe(
+    Effect.flatMap((parsed) =>
+      decodeKnown(parsed).pipe(Effect.orElseSucceed(() => makeUnknown(parsed))),
+    ),
+    Effect.orElseSucceed(() => makeUnknown(ev.data)),
+  )
+
+// ---------------------------------------------------------------------------
+// Service implementation
+// ---------------------------------------------------------------------------
+
+const httpStatusError = (status: number, body: string): AiError.AiError => {
+  const provider = "responses"
+  const raw = body
+  if (status === 429) return new AiError.RateLimited({ provider, raw })
+  if (status === 408 || status === 504) return new AiError.Timeout({ provider, raw })
+  if (status === 401) return new AiError.AuthFailed({ provider, subtype: "auth", raw })
+  if (status === 403) return new AiError.AuthFailed({ provider, subtype: "permission", raw })
+  if (status === 402) return new AiError.AuthFailed({ provider, subtype: "billing", raw })
+  if (status === 413) return new AiError.ContextLengthExceeded({ provider, raw })
+  if (status >= 500) return new AiError.Unavailable({ provider, status, raw })
+  return new AiError.InvalidRequest({ provider, raw })
+}
+
+const buildNativeStream = (cfg: Config) => {
+  const url = `${cfg.baseUrl ?? "https://api.openai.com/v1"}/responses`
+  return (
+    request: ResponsesRequest,
+  ): Stream.Stream<ProviderEvent, AiError.AiError, HttpClient.HttpClient> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient
+        const httpRequest = HttpClientRequest.post(url).pipe(
+          HttpClientRequest.bearerToken(cfg.apiKey),
+          HttpClientRequest.bodyJsonUnsafe(buildBody(request)),
+          HttpClientRequest.accept("text/event-stream"),
+        )
+        const response = yield* client
+          .execute(httpRequest)
+          .pipe(
+            Effect.mapError(
+              (cause) => new AiError.Unavailable({ provider: "responses", raw: cause }),
+            ),
+          )
+        if (response.status >= 400) {
+          const body = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+          return Stream.fail(httpStatusError(response.status, body))
+        }
+
+        return response.stream.pipe(
+          Stream.mapError(
+            (cause) => new AiError.Unavailable({ provider: "responses", raw: cause }),
+          ),
+          SSE.fromBytes,
+          Stream.mapEffect(sseEventToProviderEvent),
+          Stream.flatMap((event) =>
+            Option.match(eventToError(event), {
+              onNone: () => Stream.succeed(event),
+              onSome: Stream.fail,
+            }),
+          ),
+        )
+      }),
+    )
+}
+
+/**
+ * Project a stream of native `ProviderEvent`s into canonical `TurnEvent`s.
+ * Threads a fresh `CallIdLookup` per stream so `function_call_arguments.delta`
+ * can be tagged with the right `call_id`.
+ */
+export const toCanonical = <E, R>(
+  s: Stream.Stream<ProviderEvent, E, R>,
+): Stream.Stream<TurnEvent, E, R> =>
+  Stream.unwrap(
+    Effect.sync(() => {
+      const lookup = makeCallIdLookup()
+      return s.pipe(Stream.flatMap((event) => Stream.fromIterable(eventToDeltas(event, lookup))))
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `ResponsesService` value. For Layer-based setup, prefer `layer`.
+ */
+export const make = (cfg: Config): Effect.Effect<ResponsesService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => {
+    const streamNative: ResponsesService["streamNative"] = (request) =>
+      buildNativeStream(cfg)(request).pipe(Stream.provideService(HttpClient.HttpClient, client))
+    return {
+      streamNative,
+      streamTurn: (request) => toCanonical(streamNative(request)),
+      toCanonical,
+    }
+  })
+
+/**
+ * Layer that registers both the provider-specific `Responses` tag and the
+ * generic `LanguageModel` tag, sharing one underlying implementation.
+ *
+ * The generic tag accepts `CommonRequest`; the typed tag accepts the full
+ * `ResponsesRequest` surface.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<Responses | LanguageModel, never, HttpClient.HttpClient> => {
+  const typed = Layer.effect(Responses, make(cfg))
+  const generic = Layer.effect(
+    LanguageModel,
+    Effect.map(
+      make(cfg),
+      (s): LanguageModelService => ({
+        streamTurn: (request) => s.streamTurn(request as ResponsesRequest),
+      }),
+    ),
+  )
+  return Layer.merge(typed, generic)
+}

package/src/codec.ts

@@ -0,0 +1,298 @@
+import { Match, Option, Schema } from "effect"
+import type { ContentBlock, Item } from "@effect-uai/core/Items"
+import { matchType } from "@effect-uai/core/Match"
+import type { Turn } from "@effect-uai/core/Turn"
+
+// ---------------------------------------------------------------------------
+// Wire schemas - minimal subset of the Responses API output we consume.
+// Reference: https://www.openresponses.org/specification
+// ---------------------------------------------------------------------------
+
+const WireUrlCitation = Schema.Struct({
+  type: Schema.Literal("url_citation"),
+  url: Schema.String,
+  start_index: Schema.Number,
+  end_index: Schema.Number,
+  title: Schema.String,
+})
+
+const WireFileCitation = Schema.Struct({
+  type: Schema.Literal("file_citation"),
+  file_id: Schema.String,
+  index: Schema.Number,
+})
+
+const WireContainerFileCitation = Schema.Struct({
+  type: Schema.Literal("container_file_citation"),
+  container_id: Schema.String,
+  file_id: Schema.String,
+  start_index: Schema.Number,
+  end_index: Schema.Number,
+})
+
+const WireFilePath = Schema.Struct({
+  type: Schema.Literal("file_path"),
+  file_id: Schema.String,
+  index: Schema.Number,
+})
+
+const WireAnnotation = Schema.Union([
+  WireUrlCitation,
+  WireFileCitation,
+  WireContainerFileCitation,
+  WireFilePath,
+])
+
+const WireOutputTextContent = Schema.Struct({
+  type: Schema.Literal("output_text"),
+  text: Schema.String,
+  annotations: Schema.optional(Schema.NullOr(Schema.Array(WireAnnotation))),
+})
+
+const WireRefusalContent = Schema.Struct({
+  type: Schema.Literal("refusal"),
+  refusal: Schema.String,
+})
+
+const WireMessageContent = Schema.Union([WireOutputTextContent, WireRefusalContent])
+
+const WireSummaryText = Schema.Struct({
+  type: Schema.Literal("summary_text"),
+  text: Schema.String,
+})
+
+const WireMessage = Schema.Struct({
+  type: Schema.Literal("message"),
+  id: Schema.optional(Schema.String),
+  role: Schema.Literal("assistant"),
+  content: Schema.Array(WireMessageContent),
+})
+
+const WireFunctionCall = Schema.Struct({
+  type: Schema.Literal("function_call"),
+  id: Schema.optional(Schema.String),
+  call_id: Schema.String,
+  name: Schema.String,
+  arguments: Schema.String,
+})
+
+const WireReasoning = Schema.Struct({
+  type: Schema.Literal("reasoning"),
+  id: Schema.optional(Schema.String),
+  summary: Schema.optional(Schema.Array(WireSummaryText)),
+  encrypted_content: Schema.optional(Schema.String),
+})
+
+export const WireOutputItem = Schema.Union([WireMessage, WireFunctionCall, WireReasoning])
+export type WireOutputItem = typeof WireOutputItem.Type
+
+const WireInputTokensDetails = Schema.Struct({
+  cached_tokens: Schema.optional(Schema.NullOr(Schema.Number)),
+})
+
+const WireOutputTokensDetails = Schema.Struct({
+  reasoning_tokens: Schema.optional(Schema.NullOr(Schema.Number)),
+})
+
+const WireUsage = Schema.Struct({
+  input_tokens: Schema.optional(Schema.Number),
+  output_tokens: Schema.optional(Schema.Number),
+  total_tokens: Schema.optional(Schema.Number),
+  input_tokens_details: Schema.optional(Schema.NullOr(WireInputTokensDetails)),
+  output_tokens_details: Schema.optional(Schema.NullOr(WireOutputTokensDetails)),
+})
+
+const WireResponseError = Schema.Struct({
+  code: Schema.optional(Schema.NullOr(Schema.String)),
+  message: Schema.optional(Schema.NullOr(Schema.String)),
+})
+
+// Many Responses-API fields are emitted as explicit `null` rather than
+// missing - `Schema.optional` alone (T | undefined) doesn't cover that, so
+// we lift each through `NullOr` first. Used by `response.completed`,
+// `response.incomplete`, and `response.failed` events; not every field is
+// populated on every event (e.g. `error` only on failed, `incomplete_details`
+// only on incomplete).
+export const WireResponseCompleted = Schema.Struct({
+  id: Schema.optional(Schema.NullOr(Schema.String)),
+  status: Schema.optional(Schema.NullOr(Schema.String)),
+  output: Schema.optional(Schema.NullOr(Schema.Array(WireOutputItem))),
+  usage: Schema.optional(Schema.NullOr(WireUsage)),
+  incomplete_details: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        reason: Schema.optional(Schema.NullOr(Schema.String)),
+      }),
+    ),
+  ),
+  error: Schema.optional(Schema.NullOr(WireResponseError)),
+})
+export type WireResponseCompleted = typeof WireResponseCompleted.Type
+
+// ---------------------------------------------------------------------------
+// History → request body input
+// ---------------------------------------------------------------------------
+
+/**
+ * If an item carries `providerData` from a prior OpenAI turn, re-emit it
+ * verbatim - preserves `encrypted_content`, item ids, and any field this
+ * codec doesn't model.
+ */
+const passthrough = (item: Item): Record<string, unknown> | undefined =>
+  item.providerData !== undefined &&
+  typeof item.providerData === "object" &&
+  item.providerData !== null
+    ? (item.providerData as Record<string, unknown>)
+    : undefined
+
+const contentBlockToInput = Match.type<ContentBlock>().pipe(
+  matchType("input_text", (b) => ({ type: "input_text", text: b.text })),
+  matchType("input_image", (b) => ({
+    type: "input_image",
+    image_url:
+      b.source._tag === "url"
+        ? b.source.url
+        : `data:${b.source.media_type};base64,${b.source.data}`,
+  })),
+  matchType("output_text", (b) => ({ type: "output_text", text: b.text })),
+  matchType("refusal", (b) => ({ type: "refusal", refusal: b.text })),
+  Match.exhaustive,
+)
+
+const itemToInput = (item: Item): Record<string, unknown> =>
+  passthrough(item) ??
+  Match.value(item).pipe(
+    matchType("message", (m) => ({
+      type: "message",
+      role: m.role,
+      content: m.content.map(contentBlockToInput),
+    })),
+    matchType("function_call", (f) => ({
+      type: "function_call",
+      call_id: f.call_id,
+      name: f.name,
+      arguments: f.arguments,
+    })),
+    matchType("function_call_output", (o) => ({
+      type: "function_call_output",
+      call_id: o.call_id,
+      output: o.output,
+    })),
+    matchType("reasoning", (r) => ({
+      type: "reasoning",
+      ...(r.id !== undefined && { id: r.id }),
+      ...(r.summary !== undefined && {
+        summary: [{ type: "summary_text", text: r.summary }],
+      }),
+      ...(r.signature !== undefined && { encrypted_content: r.signature }),
+    })),
+    Match.exhaustive,
+  )
+
+/** Convert our `Item[]` history into the Responses API `input` array. */
+export const itemsToInput = (items: ReadonlyArray<Item>): ReadonlyArray<Record<string, unknown>> =>
+  items.map(itemToInput)
+
+// ---------------------------------------------------------------------------
+// Wire output items → our Items
+// ---------------------------------------------------------------------------
+
+const wireMessageContentToBlock = Match.type<typeof WireMessageContent.Type>().pipe(
+  matchType(
+    "output_text",
+    (c): ContentBlock => ({
+      type: "output_text",
+      text: c.text,
+      ...(c.annotations !== undefined && c.annotations !== null && { annotations: c.annotations }),
+    }),
+  ),
+  matchType("refusal", (c): ContentBlock => ({ type: "refusal", text: c.refusal })),
+  Match.exhaustive,
+)
+
+export const wireItemToItem = (wire: WireOutputItem): Item =>
+  Match.value(wire).pipe(
+    matchType("message", (m) => ({
+      type: "message" as const,
+      role: m.role,
+      content: m.content.map(wireMessageContentToBlock),
+      providerData: m,
+    })),
+    matchType("function_call", (f) => ({
+      type: "function_call" as const,
+      call_id: f.call_id,
+      name: f.name,
+      arguments: f.arguments,
+      providerData: f,
+    })),
+    matchType("reasoning", (r) => ({
+      type: "reasoning" as const,
+      ...(r.id !== undefined && { id: r.id }),
+      ...(r.summary !== undefined && {
+        summary: r.summary.map((s) => s.text).join("\n"),
+      }),
+      ...(r.encrypted_content !== undefined && { signature: r.encrypted_content }),
+      providerData: r,
+    })),
+    Match.exhaustive,
+  )
+
+// ---------------------------------------------------------------------------
+// response.completed → Turn
+// ---------------------------------------------------------------------------
+
+const reasonToStop = Match.type<string>().pipe(
+  Match.when("max_output_tokens", () => "max_tokens" as const),
+  Match.when("refusal", () => "refusal" as const),
+  Match.when("content_filter", () => "content_filter" as const),
+  Match.when("max_tool_calls", () => "max_tool_calls" as const),
+  Match.option,
+)
+
+const hasRefusalContent = (payload: WireResponseCompleted): boolean =>
+  (payload.output ?? []).some(
+    (i) => i.type === "message" && i.content.some((c) => c.type === "refusal"),
+  )
+
+const stopReasonFromCompleted = (payload: WireResponseCompleted): Turn["stop_reason"] =>
+  Option.match(reasonToStop(payload.incomplete_details?.reason ?? ""), {
+    onSome: (s) => s,
+    onNone: () =>
+      hasRefusalContent(payload)
+        ? ("refusal" as const)
+        : (payload.output ?? []).some((i) => i.type === "function_call")
+          ? ("tool_calls" as const)
+          : ("stop" as const),
+  })
+
+const cachedTokens = (payload: WireResponseCompleted): number | undefined =>
+  payload.usage?.input_tokens_details?.cached_tokens ?? undefined
+
+const reasoningTokens = (payload: WireResponseCompleted): number | undefined =>
+  payload.usage?.output_tokens_details?.reasoning_tokens ?? undefined
+
+export const turnFromCompleted = (payload: WireResponseCompleted): Turn => {
+  const cached = cachedTokens(payload)
+  const reasoning = reasoningTokens(payload)
+  return {
+    items: (payload.output ?? []).map(wireItemToItem),
+    usage: {
+      ...(payload.usage?.input_tokens !== undefined && {
+        input_tokens: payload.usage.input_tokens,
+      }),
+      ...(payload.usage?.output_tokens !== undefined && {
+        output_tokens: payload.usage.output_tokens,
+      }),
+      ...(payload.usage?.total_tokens !== undefined && {
+        total_tokens: payload.usage.total_tokens,
+      }),
+      ...(cached !== undefined && {
+        input_tokens_details: { cached_tokens: cached },
+      }),
+      ...(reasoning !== undefined && {
+        output_tokens_details: { reasoning_tokens: reasoning },
+      }),
+    },
+    stop_reason: stopReasonFromCompleted(payload),
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./Responses.js"
+export * from "./models.js"
+export * as codec from "./codec.js"
+export * as streamEvents from "./streamEvents.js"

package/src/models.ts

@@ -0,0 +1,24 @@
+/**
+ * Known OpenAI model identifiers usable via the Responses API (as of
+ * April 2026). The `(string & {})` tail keeps autocomplete on the literals
+ * while still accepting any string, so newly-released models work without
+ * an SDK update.
+ *
+ * Reference: https://developers.openai.com/api/docs/models/all
+ */
+export type OpenAIModel =
+  | "gpt-5.5"
+  | "gpt-5.5-pro"
+  | "gpt-5.4"
+  | "gpt-5.4-pro"
+  | "gpt-5.4-mini"
+  | "gpt-5.4-nano"
+  | "gpt-5"
+  | "gpt-5-mini"
+  | "gpt-5-nano"
+  | "gpt-5.3-codex"
+  | "gpt-4.1"
+  | "gpt-4.1-mini"
+  | "gpt-4o-mini"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})