@effect-uai/responses 0.10.0 → 0.12.0

package/src/ResponsesTools.ts

@@ -0,0 +1,158 @@
+import { Match, Result, Schema } from "effect"
+import * as Tool from "@effect-uai/core/Tool"
+
+// ---------------------------------------------------------------------------
+// OpenAI Responses provider-hosted tools. Each is a `Tool.provider` whose
+// `config` carries the wire `type` string plus its options; the renderer maps
+// it to a native entry appended to the `tools` array alongside function tools.
+// The `inputSchema` is never sent (provider tools are partitioned out of the
+// function declarations), so `Tool.noInput` suffices.
+// Reference: https://developers.openai.com/api/docs/guides/tools
+// ---------------------------------------------------------------------------
+
+const UserLocation = Schema.Struct({
+  city: Schema.optional(Schema.String),
+  region: Schema.optional(Schema.String),
+  country: Schema.optional(Schema.String),
+  timezone: Schema.optional(Schema.String),
+})
+export type UserLocation = typeof UserLocation.Type
+
+const WebSearchFilters = Schema.Struct({
+  allowedDomains: Schema.optional(Schema.Array(Schema.String)),
+  blockedDomains: Schema.optional(Schema.Array(Schema.String)),
+})
+export type WebSearchFilters = typeof WebSearchFilters.Type
+
+const WebSearchConfig = Schema.Struct({
+  kind: Schema.Literal("web_search"),
+  filters: Schema.optional(WebSearchFilters),
+  userLocation: Schema.optional(UserLocation),
+  searchContextSize: Schema.optional(Schema.Literals(["low", "medium", "high"])),
+})
+
+const CodeInterpreterConfig = Schema.Struct({
+  kind: Schema.Literal("code_interpreter"),
+  fileIds: Schema.optional(Schema.Array(Schema.String)),
+})
+
+const FileSearchConfig = Schema.Struct({
+  kind: Schema.Literal("file_search"),
+  vectorStoreIds: Schema.Array(Schema.String),
+})
+
+/** Discriminated config for a Responses hosted tool. */
+export const ResponsesToolConfig = Schema.Union([
+  WebSearchConfig,
+  CodeInterpreterConfig,
+  FileSearchConfig,
+])
+export type ResponsesToolConfig = typeof ResponsesToolConfig.Type
+
+export type WebSearchOptions = {
+  readonly filters?: WebSearchFilters
+  readonly userLocation?: UserLocation
+  readonly searchContextSize?: "low" | "medium" | "high"
+}
+
+/** OpenAI-hosted web search. */
+export const webSearchTool = (opts: WebSearchOptions = {}) =>
+  Tool.provider({
+    name: "web_search",
+    description: "Search the web, executed by OpenAI.",
+    inputSchema: Tool.noInput,
+    provider: "openai",
+    config: { kind: "web_search", ...opts } as const,
+  })
+
+/** OpenAI-hosted code interpreter (Python sandbox). */
+export const codeInterpreterTool = (opts: { readonly fileIds?: ReadonlyArray<string> } = {}) =>
+  Tool.provider({
+    name: "code_interpreter",
+    description: "Run Python in a sandbox, executed by OpenAI.",
+    inputSchema: Tool.noInput,
+    provider: "openai",
+    config: { kind: "code_interpreter", ...opts } as const,
+  })
+
+/** OpenAI-hosted file search over the given vector stores. */
+export const fileSearchTool = (opts: { readonly vectorStoreIds: ReadonlyArray<string> }) =>
+  Tool.provider({
+    name: "file_search",
+    description: "Retrieve from uploaded files, executed by OpenAI.",
+    inputSchema: Tool.noInput,
+    provider: "openai",
+    config: { kind: "file_search", vectorStoreIds: opts.vectorStoreIds } as const,
+  })
+
+/**
+ * A provider tool this adapter cannot render — a foreign `provider` or an
+ * unrecognized `config`. Carried as data so `Responses.ts` can lift it into a
+ * typed `AiError.Unsupported`.
+ */
+export type ToolRenderError = {
+  readonly capability: string
+  readonly reason: string
+}
+
+const filtersWire = (f: WebSearchFilters): Record<string, unknown> => ({
+  ...(f.allowedDomains !== undefined && { allowed_domains: f.allowedDomains }),
+  ...(f.blockedDomains !== undefined && { blocked_domains: f.blockedDomains }),
+})
+
+const userLocationWire = (loc: UserLocation): Record<string, unknown> => ({
+  type: "approximate",
+  ...(loc.city !== undefined && { city: loc.city }),
+  ...(loc.region !== undefined && { region: loc.region }),
+  ...(loc.country !== undefined && { country: loc.country }),
+  ...(loc.timezone !== undefined && { timezone: loc.timezone }),
+})
+
+const configToWire = Match.type<ResponsesToolConfig>().pipe(
+  Match.discriminatorsExhaustive("kind")({
+    web_search: (c): Record<string, unknown> => ({
+      type: "web_search",
+      ...(c.filters !== undefined && { filters: filtersWire(c.filters) }),
+      ...(c.userLocation !== undefined && { user_location: userLocationWire(c.userLocation) }),
+      ...(c.searchContextSize !== undefined && { search_context_size: c.searchContextSize }),
+    }),
+    code_interpreter: (c): Record<string, unknown> => ({
+      type: "code_interpreter",
+      container: c.fileIds !== undefined ? { type: "auto", file_ids: c.fileIds } : { type: "auto" },
+    }),
+    file_search: (c): Record<string, unknown> => ({
+      type: "file_search",
+      vector_store_ids: c.vectorStoreIds,
+    }),
+  }),
+)
+
+const decodeConfig = Schema.decodeUnknownResult(ResponsesToolConfig)
+
+const renderOne = (
+  tool: Tool.ProviderTool<string, any, string, any>,
+): Result.Result<Record<string, unknown>, ToolRenderError> =>
+  tool.provider !== "openai"
+    ? Result.fail({
+        capability: `providerTool:${tool.provider}`,
+        reason: `tool "${tool.name}" is hosted by "${tool.provider}", not openai`,
+      })
+    : decodeConfig(tool.config).pipe(
+        Result.map(configToWire),
+        Result.mapError(
+          (): ToolRenderError => ({
+            capability: "providerTool",
+            reason: `unrecognized Responses provider tool config on "${tool.name}"`,
+          }),
+        ),
+      )
+
+/**
+ * Render a toolkit's Responses provider tools to native `tools` entries. Fails
+ * with a `ToolRenderError` on the first foreign or unrecognized tool rather
+ * than dropping it.
+ */
+export const renderProviderTools = (
+  tools: ReadonlyArray<Tool.ProviderTool<string, any, string, any>>,
+): Result.Result<ReadonlyArray<Record<string, unknown>>, ToolRenderError> =>
+  Result.all(tools.map(renderOne))

package/src/codec.test.ts

@@ -0,0 +1,87 @@
+import type { HistoryItem } from "@effect-uai/core/Items"
+import { describe, expect, it } from "vitest"
+import { itemsToInput, wireItemToItem } from "./codec.js"
+
+describe("providerData round-trip", () => {
+  it("re-emits a stashed item verbatim, preserving fields our shape drops", () => {
+    // `id` and `encrypted_content` cannot be reconstructed from a Reasoning
+    // item, so the round-trip has to go through the stash.
+    const items = wireItemToItem({
+      type: "reasoning",
+      id: "rs_1",
+      encrypted_content: "opaque-state",
+    })
+    expect(itemsToInput(items)).toEqual([
+      { type: "reasoning", id: "rs_1", encrypted_content: "opaque-state" },
+    ])
+  })
+})
+
+describe("providerData is a shared slot", () => {
+  // Regression: the passthrough used to re-emit the whole `providerData`
+  // object as the wire item. An item that had been through another provider
+  // first was sent as that provider's data, losing the real content.
+  it("ignores another provider's data and encodes the item normally", () => {
+    const history: ReadonlyArray<HistoryItem> = [
+      {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: "hello world" }],
+        providerData: { gemini: { thoughtSignature: "sig-abc" } },
+      },
+    ]
+    expect(itemsToInput(history)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "hello world" }] },
+    ])
+  })
+
+  it("does not send a foreign function_call as junk", () => {
+    const history: ReadonlyArray<HistoryItem> = [
+      {
+        type: "function_call",
+        call_id: "c1",
+        name: "get_weather",
+        arguments: '{"city":"Lisbon"}',
+        providerData: { gemini: { id: "g1", thoughtSignature: "sig-abc" } },
+      },
+    ]
+    expect(itemsToInput(history)).toEqual([
+      {
+        type: "function_call",
+        call_id: "c1",
+        name: "get_weather",
+        arguments: '{"city":"Lisbon"}',
+      },
+    ])
+  })
+
+  it("re-emits only our key when an item carries several providers' data", () => {
+    const history: ReadonlyArray<HistoryItem> = [
+      {
+        type: "reasoning",
+        signature: "opaque-state",
+        providerData: {
+          responses: { type: "reasoning", id: "rs_1", encrypted_content: "opaque-state" },
+          gemini: { thoughtSignature: "sig-abc" },
+        },
+      },
+    ]
+    expect(itemsToInput(history)).toEqual([
+      { type: "reasoning", id: "rs_1", encrypted_content: "opaque-state" },
+    ])
+  })
+
+  it("falls back to a normal encode when the stashed value is not one of ours", () => {
+    const history: ReadonlyArray<HistoryItem> = [
+      {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: "hi" }],
+        providerData: { responses: { type: "not_an_item_we_model" } },
+      },
+    ]
+    expect(itemsToInput(history)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+    ])
+  })
+})

package/src/codec.ts

@@ -1,4 +1,4 @@
-import { Encoding, Match, Option, Schema } from "effect"
+import { Encoding, Match, Option, Result, Schema, pipe } from "effect"
 import type { ContentBlock, InputImage, HistoryItem } from "@effect-uai/core/Items"
 import type { Turn } from "@effect-uai/core/Turn"
 
@@ -35,7 +35,7 @@ const WireFilePath = Schema.Struct({
   index: Schema.Number,
 })
 
-const WireAnnotation = Schema.Union([
+export const WireAnnotation = Schema.Union([
   WireUrlCitation,
   WireFileCitation,
   WireContainerFileCitation,
@@ -82,7 +82,33 @@ const WireReasoning = Schema.Struct({
   encrypted_content: Schema.optional(Schema.String),
 })
 
-export const WireOutputItem = Schema.Union([WireMessage, WireFunctionCall, WireReasoning])
+// Provider-hosted tool call items (web search, code interpreter, file search).
+// The provider executes them, not us — we model them only so a grounded
+// `response.completed` still decodes and assembles a Turn; they are dropped
+// from the turn's items in Phase 1. Surfacing them is a follow-up.
+const WireWebSearchCall = Schema.Struct({
+  type: Schema.Literal("web_search_call"),
+  id: Schema.optional(Schema.String),
+})
+
+const WireCodeInterpreterCall = Schema.Struct({
+  type: Schema.Literal("code_interpreter_call"),
+  id: Schema.optional(Schema.String),
+})
+
+const WireFileSearchCall = Schema.Struct({
+  type: Schema.Literal("file_search_call"),
+  id: Schema.optional(Schema.String),
+})
+
+export const WireOutputItem = Schema.Union([
+  WireMessage,
+  WireFunctionCall,
+  WireReasoning,
+  WireWebSearchCall,
+  WireCodeInterpreterCall,
+  WireFileSearchCall,
+])
 export type WireOutputItem = typeof WireOutputItem.Type
 
 const WireInputTokensDetails = Schema.Struct({
@@ -133,16 +159,36 @@ export type WireResponseCompleted = typeof WireResponseCompleted.Type
 // ---------------------------------------------------------------------------
 
 /**
- * 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.
+ * The item shapes we stash for round-tripping. Narrower than
+ * `WireOutputItem`: the provider-hosted call variants are dropped from the
+ * turn, so they are never stored. Composed from the internal `Wire*` structs,
+ * which keeps the wire model out of the package's public surface.
  */
-const passthrough = (item: HistoryItem): Record<string, unknown> | undefined =>
-  item.providerData !== undefined &&
-  typeof item.providerData === "object" &&
-  item.providerData !== null
-    ? (item.providerData as Record<string, unknown>)
-    : undefined
+const StoredItem = Schema.Union([WireMessage, WireFunctionCall, WireReasoning])
+type StoredItem = typeof StoredItem.Type
+
+const ProviderDataResponses = Schema.Struct({ responses: StoredItem })
+const decodeResponsesData = Schema.decodeUnknownResult(ProviderDataResponses)
+
+/**
+ * If an item carries `providerData.responses` from a prior turn on this API,
+ * re-emit it verbatim - preserves `encrypted_content` and item ids, which a
+ * fresh encode from our `HistoryItem` shape cannot reconstruct.
+ *
+ * Namespaced because `providerData` is a shared slot: an item routed through
+ * another provider first (dynamic fallback) carries that provider's key, and
+ * re-emitting the whole object would send that provider's data as the wire
+ * item and drop the real content. Anything that fails to decode is not ours,
+ * so we fall back to encoding the item normally.
+ */
+const passthrough = (item: HistoryItem): StoredItem | undefined =>
+  pipe(
+    decodeResponsesData(item.providerData),
+    Result.match({
+      onSuccess: (data) => data.responses,
+      onFailure: (): StoredItem | undefined => undefined,
+    }),
+  )
 
 /**
  * OpenAI's `input_image` content block carries a single `image_url` field;
@@ -219,31 +265,41 @@ const wireMessageContentToBlock = Match.type<typeof WireMessageContent.Type>().p
   }),
 )
 
-export const wireItemToItem = (wire: WireOutputItem): HistoryItem =>
+export const wireItemToItem = (wire: WireOutputItem): ReadonlyArray<HistoryItem> =>
   Match.value(wire).pipe(
     Match.discriminatorsExhaustive("type")({
-      message: (m) => ({
-        type: "message" as const,
-        role: m.role,
-        content: m.content.map(wireMessageContentToBlock),
-        providerData: m,
-      }),
-      function_call: (f) => ({
-        type: "function_call" as const,
-        call_id: f.call_id,
-        name: f.name,
-        arguments: f.arguments,
-        providerData: f,
-      }),
-      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,
-      }),
+      message: (m): ReadonlyArray<HistoryItem> => [
+        {
+          type: "message" as const,
+          role: m.role,
+          content: m.content.map(wireMessageContentToBlock),
+          providerData: { responses: m },
+        },
+      ],
+      function_call: (f): ReadonlyArray<HistoryItem> => [
+        {
+          type: "function_call" as const,
+          call_id: f.call_id,
+          name: f.name,
+          arguments: f.arguments,
+          providerData: { responses: f },
+        },
+      ],
+      reasoning: (r): ReadonlyArray<HistoryItem> => [
+        {
+          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: { responses: r },
+        },
+      ],
+      // Hosted-tool calls are provider-executed; drop from the turn (Phase 1).
+      web_search_call: (): ReadonlyArray<HistoryItem> => [],
+      code_interpreter_call: (): ReadonlyArray<HistoryItem> => [],
+      file_search_call: (): ReadonlyArray<HistoryItem> => [],
     }),
   )
 
@@ -285,7 +341,7 @@ export const turnFromCompleted = (payload: WireResponseCompleted): Turn => {
   const cached = cachedTokens(payload)
   const reasoning = reasoningTokens(payload)
   return {
-    items: (payload.output ?? []).map(wireItemToItem),
+    items: (payload.output ?? []).flatMap(wireItemToItem),
     usage: {
       ...(payload.usage?.input_tokens !== undefined && {
         input_tokens: payload.usage.input_tokens,

package/src/index.ts

@@ -1,4 +1,6 @@
 export * as Responses from "./Responses.js"
+export * as ResponsesTools from "./ResponsesTools.js"
+export * as OpenAIDeepResearch from "./OpenAIDeepResearch.js"
 export * as OpenAIEmbedding from "./OpenAIEmbedding.js"
 export * as codec from "./codec.js"
 export * as streamEvents from "./streamEvents.js"

package/src/models.ts

@@ -23,6 +23,20 @@ export type OpenAIModel =
   // eslint-disable-next-line @typescript-eslint/ban-types
   | (string & {})
 
+/**
+ * OpenAI deep-research model / agent ids, usable via the Responses API with
+ * `background: true`. `o3-deep-research` is the comprehensive tier;
+ * `o4-mini-deep-research` is faster and cheaper. The `(string & {})` tail keeps
+ * autocomplete while accepting newer ids without an SDK update.
+ *
+ * Reference: https://developers.openai.com/api/docs/guides/deep-research
+ */
+export type OpenAIDeepResearchModel =
+  | "o3-deep-research"
+  | "o4-mini-deep-research"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
 /**
  * Known OpenAI embedding model identifiers. The `-3-` line is still the
  * current general-purpose lineup; `dimensions` parameter supports

package/src/responsesTools.test.ts

@@ -0,0 +1,146 @@
+import { Result, Schema } from "effect"
+import * as Tool from "@effect-uai/core/Tool"
+import { providerToolsOf } from "@effect-uai/core/Tool"
+import { describe, expect, it } from "vitest"
+import { KnownProviderEvent, eventToDeltas, makeCallIdLookup } from "./streamEvents.js"
+import {
+  codeInterpreterTool,
+  fileSearchTool,
+  renderProviderTools,
+  webSearchTool,
+} from "./ResponsesTools.js"
+
+const wireFor = (toolkit: Record<string, Tool.AnyTool>) =>
+  Result.getOrThrow(renderProviderTools(providerToolsOf(toolkit)))
+
+describe("Responses provider tool rendering", () => {
+  it("maps web_search options onto the native wire fields", () => {
+    expect(
+      wireFor({
+        web_search: webSearchTool({
+          searchContextSize: "high",
+          filters: { allowedDomains: ["example.com"], blockedDomains: ["spam.com"] },
+          userLocation: { city: "Berlin", country: "DE" },
+        }),
+      }),
+    ).toEqual([
+      {
+        type: "web_search",
+        filters: { allowed_domains: ["example.com"], blocked_domains: ["spam.com"] },
+        user_location: { type: "approximate", city: "Berlin", country: "DE" },
+        search_context_size: "high",
+      },
+    ])
+  })
+
+  it("maps code_interpreter to an auto container (with file ids when given)", () => {
+    expect(wireFor({ ci: codeInterpreterTool() })).toEqual([
+      { type: "code_interpreter", container: { type: "auto" } },
+    ])
+    expect(wireFor({ ci: codeInterpreterTool({ fileIds: ["file_1"] }) })).toEqual([
+      { type: "code_interpreter", container: { type: "auto", file_ids: ["file_1"] } },
+    ])
+  })
+
+  it("maps file_search to its vector store ids", () => {
+    expect(wireFor({ fs: fileSearchTool({ vectorStoreIds: ["vs_1", "vs_2"] }) })).toEqual([
+      { type: "file_search", vector_store_ids: ["vs_1", "vs_2"] },
+    ])
+  })
+
+  it("fails on a tool hosted by a different provider", () => {
+    const foreign = Tool.provider({
+      name: "google_search",
+      description: "Gemini grounding.",
+      inputSchema: Tool.noInput,
+      provider: "gemini",
+      config: { kind: "google_search" },
+    })
+    expect(Result.isFailure(renderProviderTools(providerToolsOf({ foreign })))).toBe(true)
+  })
+
+  it("fails on an unrecognized config", () => {
+    const bogus = Tool.provider({
+      name: "mystery",
+      description: "Unknown Responses tool.",
+      inputSchema: Tool.noInput,
+      provider: "openai",
+      config: { kind: "telepathy" },
+    })
+    expect(Result.isFailure(renderProviderTools(providerToolsOf({ bogus })))).toBe(true)
+  })
+})
+
+describe("Responses hosted-tool response tolerance", () => {
+  // The real regression: a hosted-tool output item in `response.completed` must
+  // not break the event decode, or `TurnComplete` would never fire. Decoding
+  // through the actual event schema (throws on failure) and projecting to
+  // TurnEvents proves the grounded text still assembles into a turn.
+  const decodeEvent = Schema.decodeUnknownSync(KnownProviderEvent)
+
+  it("emits TurnComplete with just the text answer for a grounded completion", () => {
+    const event = decodeEvent({
+      type: "response.completed",
+      response: {
+        status: "completed",
+        output: [
+          { type: "web_search_call", id: "ws_1", status: "completed" },
+          {
+            type: "message",
+            role: "assistant",
+            content: [{ type: "output_text", text: "Grounded answer." }],
+          },
+        ],
+      },
+    })
+    const deltas = eventToDeltas(event, makeCallIdLookup())
+    const complete = deltas.find((d) => d._tag === "TurnComplete")
+    expect(complete).toBeDefined()
+    const turn = complete?._tag === "TurnComplete" ? complete.turn : undefined
+    expect(turn?.stop_reason).toBe("stop")
+    expect(turn?.items).toEqual([
+      {
+        type: "message",
+        role: "assistant",
+        content: [{ type: "output_text", text: "Grounded answer." }],
+        providerData: expect.anything(),
+      },
+    ])
+  })
+
+  // The new streamed-citation path: a real `annotation.added` payload (with the
+  // wire's positional fields) must decode and project to a `CitationAdded`
+  // carrying a domain `Annotation`. This is what makes native-grounding
+  // citations stream instead of only landing on the final turn.
+  it("projects a streamed url_citation to CitationAdded", () => {
+    const deltas = eventToDeltas(
+      decodeEvent({
+        type: "response.output_text.annotation.added",
+        item_id: "msg_1",
+        output_index: 0,
+        content_index: 0,
+        annotation_index: 0,
+        annotation: {
+          type: "url_citation",
+          url: "https://example.com/a",
+          title: "A",
+          start_index: 10,
+          end_index: 20,
+        },
+      }),
+      makeCallIdLookup(),
+    )
+    expect(deltas).toEqual([
+      {
+        _tag: "CitationAdded",
+        annotation: {
+          type: "url_citation",
+          url: "https://example.com/a",
+          title: "A",
+          start_index: 10,
+          end_index: 20,
+        },
+      },
+    ])
+  })
+})