@effect-uai/responses 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/responses",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "OpenAI Responses API provider for @effect-uai/core.",
   "keywords": [
     "ai",
@@ -38,6 +38,14 @@
       "types": "./dist/Responses.d.mts",
       "import": "./dist/Responses.mjs"
     },
+    "./ResponsesTools": {
+      "types": "./dist/ResponsesTools.d.mts",
+      "import": "./dist/ResponsesTools.mjs"
+    },
+    "./OpenAIDeepResearch": {
+      "types": "./dist/OpenAIDeepResearch.d.mts",
+      "import": "./dist/OpenAIDeepResearch.mjs"
+    },
     "./OpenAIEmbedding": {
       "types": "./dist/OpenAIEmbedding.d.mts",
       "import": "./dist/OpenAIEmbedding.mjs"
@@ -47,13 +55,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "effect": "4.0.0-beta.57",
+    "effect": "4.0.0-beta.94",
     "typescript": "^6.0.3",
-    "@effect-uai/core": "0.10.0"
+    "@effect-uai/core": "0.12.0"
   },
   "peerDependencies": {
     "@effect-uai/core": ">=0.2.0 <1",
-    "effect": "4.0.0-beta.57"
+    "effect": ">=4.0.0-beta.94 <5.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/OpenAIDeepResearch.ts

@@ -0,0 +1,266 @@
+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 {
+  DeepResearch,
+  type DeepResearchService,
+  type DeepResearchServiceShape,
+  fromJob,
+  type ResearchJobOps,
+} from "@effect-uai/core/DeepResearch"
+import * as Job from "@effect-uai/core/Job"
+import type { ResearchJobRef, ResearchRequest, ResearchState } from "@effect-uai/core/Research"
+import type { Turn, TurnEvent } from "@effect-uai/core/Turn"
+import { WireResponseCompleted, turnFromCompleted, itemsToInput } from "./codec.js"
+import type { OpenAIDeepResearchModel } from "./models.js"
+import { type OpenAiRegion, resolveHost } from "./region.js"
+import { httpStatusError, providerEventsOfResponse, toCanonical } from "./Responses.js"
+import type { ProviderEvent } from "./streamEvents.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenAI-typed research request. Narrows `model` to the deep-research ids and
+ * adds `maxSearches` (mapped to `max_tool_calls`) and a `reasoning` hint.
+ * Provider-portable code uses the generic `DeepResearch` tag instead.
+ */
+export type OpenAIResearchRequest = Omit<ResearchRequest, "model"> & {
+  readonly model?: OpenAIDeepResearchModel
+  /** Cost/latency cap on the agent's tool calls. Maps to `max_tool_calls`. */
+  readonly maxSearches?: number
+  /** Reasoning-effort hint; `summary: "auto"` streams reasoning summaries. */
+  readonly reasoning?: {
+    readonly effort?: "low" | "medium" | "high"
+    readonly summary?: "auto" | "concise" | "detailed"
+  }
+}
+
+export type OpenAIDeepResearchService = DeepResearchServiceShape<OpenAIResearchRequest>
+
+/**
+ * Provider-typed tag. Yield this for the OpenAI model / `maxSearches` knobs;
+ * yield the generic `DeepResearch` tag for provider-portable code. The
+ * background job is detachable and streams live over the resumable Responses
+ * SSE, so `streamFrom` is a real event stream (not the synthesized fallback) and
+ * a persisted ref survives a restart.
+ */
+export class OpenAIDeepResearch extends Context.Service<
+  OpenAIDeepResearch,
+  OpenAIDeepResearchService
+>()("@betalyra/effect-uai/providers/responses/OpenAIDeepResearch") {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  readonly region?: OpenAiRegion
+  /** Poll cadence / overall timeout for the derived poll loops. */
+  readonly job?: Job.JobConfig
+}
+
+// ---------------------------------------------------------------------------
+// Wire codec
+// ---------------------------------------------------------------------------
+
+const decodeResponse = Schema.decodeUnknownEffect(WireResponseCompleted)
+
+// Any early lifecycle event (`response.created` / `response.queued` / ...)
+// carries the response object; only its id matters here. These events are not
+// in the modeled `ProviderEvent` union, so they arrive as `_unknown`.
+const WireCreated = Schema.Struct({ response: Schema.Struct({ id: Schema.String }) })
+const decodeCreated = Schema.decodeUnknownEffect(WireCreated)
+
+const responseIdOf = (event: ProviderEvent): Effect.Effect<Option.Option<string>> =>
+  event.type === "_unknown"
+    ? decodeCreated(event.raw).pipe(
+        Effect.map((wire) => Option.some(wire.response.id)),
+        Effect.orElseSucceed(() => Option.none<string>()),
+      )
+    : Effect.succeedNone
+
+// Map a Responses object's `status` onto the generic `JobState`. `completed`
+// and `incomplete` both carry a usable turn (incomplete = stopped early with a
+// partial answer, same shape); `failed` / `cancelled` are terminal failures.
+// An unknown / absent status keeps the loop polling (bounded by the timeout).
+export const jobStateOf = (wire: WireResponseCompleted): ResearchState =>
+  Match.value(wire.status ?? "").pipe(
+    Match.when("queued", (): ResearchState => ({ _tag: "Pending" })),
+    Match.when("in_progress", (): ResearchState => ({ _tag: "Running" })),
+    Match.whenOr(
+      "completed",
+      "incomplete",
+      (): ResearchState => ({ _tag: "Succeeded", result: turnFromCompleted(wire) }),
+    ),
+    Match.whenOr(
+      "failed",
+      "cancelled",
+      (): ResearchState => ({
+        _tag: "Failed",
+        ...(wire.error?.message != null && { reason: wire.error.message }),
+        raw: wire,
+      }),
+    ),
+    Match.orElse((): ResearchState => ({ _tag: "Running" })),
+  )
+
+// ---------------------------------------------------------------------------
+// HTTP
+// ---------------------------------------------------------------------------
+
+const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "responses", raw: cause })
+
+// Deep research requires at least one data-source tool; default to web search.
+const submitBody = (request: OpenAIResearchRequest): Record<string, unknown> => ({
+  model: request.model ?? "o3-deep-research",
+  input: itemsToInput(request.history),
+  background: true,
+  store: true,
+  tools: [{ type: "web_search_preview" }],
+  ...(request.maxSearches !== undefined && { max_tool_calls: request.maxSearches }),
+  ...(request.reasoning !== undefined && { reasoning: request.reasoning }),
+})
+
+// The job is created with `stream: true` on top of `background: true`: OpenAI
+// only exposes a resumable event feed on responses *created* streaming, so this
+// keeps every submitted ref attachable via `streamFrom`. Only the first SSE
+// event is read (for the response id); the connection is then dropped and the
+// background job keeps running server-side.
+const submitJob = (
+  cfg: Config,
+  request: OpenAIResearchRequest,
+): Effect.Effect<ResearchJobRef, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.post(`${resolveHost(cfg)}/responses`).pipe(
+      HttpClientRequest.bearerToken(cfg.apiKey),
+      HttpClientRequest.accept("text/event-stream"),
+      HttpClientRequest.bodyJsonUnsafe({ ...submitBody(request), stream: true }),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    const id = yield* providerEventsOfResponse(response).pipe(
+      Stream.mapEffect(responseIdOf),
+      Stream.filter(Option.isSome),
+      Stream.map((some) => some.value),
+      Stream.runHead,
+    )
+    return yield* Option.match(id, {
+      onNone: () =>
+        Effect.fail(
+          new AiError.GenerationFailed({
+            provider: "responses",
+            message: "streaming create ended without a response id",
+            raw: submitBody(request),
+          }),
+        ),
+      onSome: (value) => Effect.succeed(Job.jobRef<Turn>("responses", value)),
+    })
+  })
+
+const pollJob = (
+  cfg: Config,
+  ref: ResearchJobRef,
+): Effect.Effect<ResearchState, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.get(`${resolveHost(cfg)}/responses/${ref.id}`).pipe(
+      HttpClientRequest.bearerToken(cfg.apiKey),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* httpStatusError(response.status, text)
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    const wire = yield* decodeResponse(json).pipe(Effect.mapError(transportFailure))
+    return jobStateOf(wire)
+  })
+
+const cancelJob = (
+  cfg: Config,
+  ref: ResearchJobRef,
+): Effect.Effect<void, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.post(
+      `${resolveHost(cfg)}/responses/${ref.id}/cancel`,
+    ).pipe(HttpClientRequest.bearerToken(cfg.apiKey))
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* httpStatusError(response.status, text)
+    }
+  })
+
+// Attach a live event stream to a detached job via the resumable Responses SSE,
+// reusing the shared decode pipeline and the canonical `TurnEvent` projection.
+const streamFromRef = (
+  cfg: Config,
+  ref: ResearchJobRef,
+): Stream.Stream<TurnEvent, AiError.AiError, HttpClient.HttpClient> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const httpRequest = HttpClientRequest.get(
+        `${resolveHost(cfg)}/responses/${ref.id}?stream=true`,
+      ).pipe(
+        HttpClientRequest.bearerToken(cfg.apiKey),
+        HttpClientRequest.accept("text/event-stream"),
+      )
+      const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+      return toCanonical(providerEventsOfResponse(response))
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+// The job ops. OpenAI streams live over the resumable Responses SSE, so it
+// supplies a real `streamFrom` (not the synthesized fallback). Since `submit`
+// creates the job streaming, `fromJob`'s default `researchStream`
+// (submit-then-attach) streams real events too.
+const jobOps = (
+  cfg: Config,
+  client: HttpClient.HttpClient,
+): ResearchJobOps<OpenAIResearchRequest> => {
+  const withClient = <A>(e: Effect.Effect<A, AiError.AiError, HttpClient.HttpClient>) =>
+    Effect.provideService(e, HttpClient.HttpClient, client)
+  const withClientStream = <A>(s: Stream.Stream<A, AiError.AiError, HttpClient.HttpClient>) =>
+    Stream.provideService(s, HttpClient.HttpClient, client)
+  return {
+    submit: (request) => withClient(submitJob(cfg, request)),
+    poll: (ref) => withClient(pollJob(cfg, ref)),
+    cancel: (ref) => withClient(cancelJob(cfg, ref)),
+    streamFrom: (ref) => withClientStream(streamFromRef(cfg, ref)),
+  }
+}
+
+/** Build an `OpenAIDeepResearchService`. For Layer setup, prefer {@link layer}. */
+export const make = (
+  cfg: Config,
+): Effect.Effect<OpenAIDeepResearchService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient, (client) => fromJob(jobOps(cfg, client), cfg.job))
+
+/**
+ * Layer registering the provider-typed `OpenAIDeepResearch` tag and the generic
+ * `DeepResearch` tag. No capability markers: the whole surface (detach, live
+ * stream, cancel) is universal.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<OpenAIDeepResearch | DeepResearch, never, HttpClient.HttpClient> => {
+  const typed = Layer.effect(OpenAIDeepResearch, make(cfg))
+  const generic = Layer.effect(
+    DeepResearch,
+    Effect.map(HttpClient.HttpClient, (client): DeepResearchService => {
+      const ops = jobOps(cfg, client)
+      return fromJob<ResearchRequest>(
+        { ...ops, submit: (request) => ops.submit(request as OpenAIResearchRequest) },
+        cfg.job,
+      )
+    }),
+  )
+  return Layer.merge(typed, generic)
+}

package/src/OpenAIEmbedding.ts

@@ -260,7 +260,7 @@ const embedManyImpl =
 export const make = (
   cfg: Config,
 ): Effect.Effect<OpenAIEmbeddingService, never, HttpClient.HttpClient> =>
-  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+  Effect.map(HttpClient.HttpClient, (client) => ({
     embed: (request) =>
       embedImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
     embedMany: (request) =>

package/src/Responses.ts

@@ -1,5 +1,5 @@
-import { Context, Effect, Layer, Match, Option, Redacted, Schema, Stream } from "effect"
-import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import { Context, Effect, Layer, Match, Option, Redacted, Result, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
 import * as AiError from "@effect-uai/core/AiError"
 import * as StructuredFormat from "@effect-uai/core/StructuredFormat"
 import {
@@ -9,9 +9,19 @@ import {
   turnFromStream,
 } from "@effect-uai/core/LanguageModel"
 import * as SSE from "@effect-uai/core/SSE"
-import { descriptorsOf } from "@effect-uai/core/Tool"
+import { descriptorsOf, providerToolsOf } from "@effect-uai/core/Tool"
 import type { Turn, TurnEvent } from "@effect-uai/core/Turn"
 import { itemsToInput } from "./codec.js"
+import { renderProviderTools } from "./ResponsesTools.js"
+
+export {
+  codeInterpreterTool,
+  fileSearchTool,
+  webSearchTool,
+  type WebSearchOptions,
+  type WebSearchFilters,
+  type UserLocation,
+} from "./ResponsesTools.js"
 import type { OpenAIModel } from "./models.js"
 import { type OpenAiRegion, resolveHost } from "./region.js"
 import {
@@ -41,6 +51,20 @@ export type ResponsesRequest = Omit<CommonRequest, "model"> & {
   readonly safetyIdentifier?: string
   readonly promptCacheKey?: string
   readonly truncation?: "auto" | "disabled"
+  /**
+   * Vendor-specific body fields merged into the request as-is.
+   *
+   * The Responses dialect is spoken by gateways as well as by OpenAI, and a
+   * gateway carries its own parameters — Requesty's `{ requesty: { auto_cache:
+   * true } }`, for example. Modelling each one would tie this provider to a
+   * catalogue of gateways it cannot see; passing them through keeps the typed
+   * surface OpenAI's and the untyped surface open.
+   *
+   * Merged over the built body, so a field named here wins over the one this
+   * provider would have sent. Per-request keys win over the layer's
+   * {@link Config.extraBody}.
+   */
+  readonly extraBody?: Readonly<Record<string, unknown>>
   /**
    * Free-form JSON output: model emits valid JSON without schema
    * constraints. Mutually exclusive with `structured` (schema wins if
@@ -98,6 +122,12 @@ export type Config = {
   readonly apiKey: Redacted.Redacted
   readonly baseUrl?: string
   readonly region?: OpenAiRegion
+  /**
+   * Vendor-specific body fields sent on every request from this layer — the
+   * place for a gateway's standing configuration, so call sites do not repeat
+   * it. Overridden per request by {@link ResponsesRequest.extraBody}.
+   */
+  readonly extraBody?: Readonly<Record<string, unknown>>
 }
 
 // ---------------------------------------------------------------------------
@@ -123,22 +153,25 @@ const buildText = (request: ResponsesRequest): Record<string, unknown> | undefin
   return Object.keys(text).length === 0 ? undefined : text
 }
 
-const buildBody = (request: ResponsesRequest): Record<string, unknown> => {
+const buildBody = (
+  request: ResponsesRequest,
+  providerToolWire: ReadonlyArray<Record<string, unknown>>,
+  cfg: Config,
+): Record<string, unknown> => {
   const text = buildText(request)
-  const tools = descriptorsOf(request.tools)
+  const functionTools = descriptorsOf(request.tools).map((t) => ({
+    type: "function",
+    name: t.name,
+    description: t.description,
+    parameters: t.inputSchema,
+    ...(t.strict !== undefined && { strict: t.strict }),
+  }))
+  const tools = [...functionTools, ...providerToolWire]
   return {
     model: request.model,
     input: itemsToInput(request.history),
     stream: true,
-    ...(tools.length > 0 && {
-      tools: tools.map((t) => ({
-        type: "function",
-        name: t.name,
-        description: t.description,
-        parameters: t.inputSchema,
-        ...(t.strict !== undefined && { strict: t.strict }),
-      })),
-    }),
+    ...(tools.length > 0 && { tools }),
     ...(request.toolChoice !== undefined && { tool_choice: request.toolChoice }),
     ...(request.temperature !== undefined && { temperature: request.temperature }),
     ...(request.maxOutputTokens !== undefined && {
@@ -164,6 +197,8 @@ const buildBody = (request: ResponsesRequest): Record<string, unknown> => {
     }),
     ...(request.truncation !== undefined && { truncation: request.truncation }),
     ...(text !== undefined && { text }),
+    ...cfg.extraBody,
+    ...request.extraBody,
   }
 }
 
@@ -182,7 +217,26 @@ const makeUnknown = (raw: unknown): ProviderEvent => ({ type: "_unknown", raw })
  */
 const eventToError = Match.type<ProviderEvent>().pipe(
   Match.discriminators("type")({
-    error: (e): AiError.AiError => new AiError.Unavailable({ provider: "responses", raw: e }),
+    error: (e): AiError.AiError => {
+      const detail = e.error
+      const message = detail?.message ?? e.message
+      const code = detail?.code ?? e.code
+      const param = detail?.param
+      // A top-level SSE `error` is usually a request rejection (bad model,
+      // missing access, malformed body): non-retryable, so `InvalidRequest`.
+      return detail?.type === "invalid_request_error"
+        ? new AiError.InvalidRequest({
+            provider: "responses",
+            ...(param != null && { param }),
+            raw: e,
+          })
+        : new AiError.GenerationFailed({
+            provider: "responses",
+            ...(code != null && { code }),
+            ...(message != null && { message }),
+            raw: e,
+          })
+    },
     "response.failed": (e): AiError.AiError => {
       const code = e.response.error?.code
       const message = e.response.error?.message
@@ -211,7 +265,7 @@ const sseEventToProviderEvent = (ev: SSE.Event): Effect.Effect<ProviderEvent> =>
 // Service implementation
 // ---------------------------------------------------------------------------
 
-const httpStatusError = (status: number, body: string): AiError.AiError => {
+export const httpStatusError = (status: number, body: string): AiError.AiError => {
   const provider = "responses"
   const raw = body
   if (status === 429) return new AiError.RateLimited({ provider, raw })
@@ -224,6 +278,36 @@ const httpStatusError = (status: number, body: string): AiError.AiError => {
   return new AiError.InvalidRequest({ provider, raw })
 }
 
+/**
+ * Decode an already-executed `/responses` HTTP response into the native
+ * `ProviderEvent` stream: fail on a >=400 status, else SSE-decode the body and
+ * lift terminal `error` / `response.failed` events to a typed `AiError`. Shared
+ * by the streaming turn path (POST) and the deep-research resume stream (GET
+ * `?stream=true`).
+ */
+export const providerEventsOfResponse = (
+  response: HttpClientResponse.HttpClientResponse,
+): Stream.Stream<ProviderEvent, AiError.AiError> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      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,
+          }),
+        ),
+      )
+    }),
+  )
+
 const buildNativeStream = (cfg: Config) => {
   const url = `${resolveHost(cfg)}/responses`
   return (
@@ -232,9 +316,23 @@ const buildNativeStream = (cfg: Config) => {
     Stream.unwrap(
       Effect.gen(function* () {
         const client = yield* HttpClient.HttpClient
+        const providerToolWire = yield* Result.match(
+          renderProviderTools(providerToolsOf(request.tools)),
+          {
+            onFailure: (e) =>
+              Effect.fail(
+                new AiError.Unsupported({
+                  provider: "responses",
+                  capability: e.capability,
+                  reason: e.reason,
+                }),
+              ),
+            onSuccess: (wire) => Effect.succeed(wire),
+          },
+        )
         const httpRequest = HttpClientRequest.post(url).pipe(
           HttpClientRequest.bearerToken(cfg.apiKey),
-          HttpClientRequest.bodyJsonUnsafe(buildBody(request)),
+          HttpClientRequest.bodyJsonUnsafe(buildBody(request, providerToolWire, cfg)),
           HttpClientRequest.accept("text/event-stream"),
         )
         const response = yield* client
@@ -244,24 +342,7 @@ const buildNativeStream = (cfg: Config) => {
               (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,
-            }),
-          ),
-        )
+        return providerEventsOfResponse(response)
       }),
     )
 }
@@ -289,7 +370,7 @@ export const toCanonical = <E, R>(
  * 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) => {
+  Effect.map(HttpClient.HttpClient, (client) => {
     const streamNative: ResponsesService["streamNative"] = (request) =>
       buildNativeStream(cfg)(request).pipe(Stream.provideService(HttpClient.HttpClient, client))
     const streamTurn: ResponsesService["streamTurn"] = (request) =>