@effect-uai/responses 0.9.0 → 0.11.0

package/src/codec.ts

@@ -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({
@@ -219,31 +245,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: m,
+        },
+      ],
+      function_call: (f): ReadonlyArray<HistoryItem> => [
+        {
+          type: "function_call" as const,
+          call_id: f.call_id,
+          name: f.name,
+          arguments: f.arguments,
+          providerData: 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: 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 +321,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,
+        },
+      },
+    ])
+  })
+})

package/src/streamEvents.ts

@@ -1,6 +1,11 @@
 import { Match, Schema } from "effect"
 import { TurnEvent } from "@effect-uai/core/Turn"
-import { WireOutputItem, WireResponseCompleted, turnFromCompleted } from "./codec.js"
+import {
+  WireAnnotation,
+  WireOutputItem,
+  WireResponseCompleted,
+  turnFromCompleted,
+} from "./codec.js"
 
 // ---------------------------------------------------------------------------
 // Schemas for the SSE event payloads we care about. The Responses API ships
@@ -44,6 +49,28 @@ const RefusalDone = Schema.Struct({
   refusal: Schema.optional(Schema.String),
 })
 
+// Web-search lifecycle. The three phases carry `item_id` / `output_index` /
+// `sequence_number`; we map each to a `WebSearchCall` status. `query` / `action`
+// ride on the `web_search_call` output item, not these lifecycle events.
+const WebSearchInProgress = Schema.Struct({
+  type: Schema.Literal("response.web_search_call.in_progress"),
+})
+
+const WebSearchSearching = Schema.Struct({
+  type: Schema.Literal("response.web_search_call.searching"),
+})
+
+const WebSearchCompleted = Schema.Struct({
+  type: Schema.Literal("response.web_search_call.completed"),
+})
+
+// A citation attached to the answer as it is written. `annotation` is the
+// same shape as the ones bundled on the final `output_text` block.
+const AnnotationAdded = Schema.Struct({
+  type: Schema.Literal("response.output_text.annotation.added"),
+  annotation: WireAnnotation,
+})
+
 const Completed = Schema.Struct({
   type: Schema.Literal("response.completed"),
   response: WireResponseCompleted,
@@ -61,8 +88,18 @@ const Failed = Schema.Struct({
 
 const ErrorEvent = Schema.Struct({
   type: Schema.Literal("error"),
+  // Flat form (top-level `message`/`code`) and the nested form the Responses API
+  // uses for request rejections: `error: { message, code, type, param }`.
   message: Schema.optional(Schema.String),
   code: Schema.optional(Schema.String),
+  error: Schema.optional(
+    Schema.Struct({
+      message: Schema.optional(Schema.NullOr(Schema.String)),
+      code: Schema.optional(Schema.NullOr(Schema.String)),
+      type: Schema.optional(Schema.NullOr(Schema.String)),
+      param: Schema.optional(Schema.NullOr(Schema.String)),
+    }),
+  ),
 })
 
 /**
@@ -88,6 +125,10 @@ export const KnownProviderEvent = Schema.Union([
   ReasoningSummaryDelta,
   RefusalDelta,
   RefusalDone,
+  WebSearchInProgress,
+  WebSearchSearching,
+  WebSearchCompleted,
+  AnnotationAdded,
   Completed,
   Incomplete,
   Failed,
@@ -107,6 +148,10 @@ export const ProviderEvent = Schema.Union([
   ReasoningSummaryDelta,
   RefusalDelta,
   RefusalDone,
+  WebSearchInProgress,
+  WebSearchSearching,
+  WebSearchCompleted,
+  AnnotationAdded,
   Completed,
   Incomplete,
   Failed,
@@ -165,6 +210,18 @@ export const eventToDeltas = (
       // Terminal marker for the refusal stream; the deltas already covered
       // the text, so no canonical event is emitted here.
       "response.refusal.done": () => [],
+      "response.web_search_call.in_progress": () => [
+        TurnEvent.WebSearchCall({ status: "started" }),
+      ],
+      "response.web_search_call.searching": () => [
+        TurnEvent.WebSearchCall({ status: "searching" }),
+      ],
+      "response.web_search_call.completed": () => [
+        TurnEvent.WebSearchCall({ status: "completed" }),
+      ],
+      "response.output_text.annotation.added": ({ annotation }) => [
+        TurnEvent.CitationAdded({ annotation }),
+      ],
       "response.completed": ({ response }) => [
         TurnEvent.TurnComplete({ turn: turnFromCompleted(response) }),
       ],