@effect-uai/responses 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/responses",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "OpenAI Responses API provider for @effect-uai/core.",
   "keywords": [
     "ai",
@@ -38,6 +38,10 @@
       "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"
@@ -51,13 +55,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "effect": "4.0.0-beta.94",
-    "typescript": "^6.0.3",
-    "@effect-uai/core": "0.11.0"
+    "effect": "4.0.0-rc.111",
+    "typescript": "^7.0.2",
+    "@effect-uai/core": "0.12.1"
   },
   "peerDependencies": {
     "@effect-uai/core": ">=0.2.0 <1",
-    "effect": ">=4.0.0-beta.94 <5.0.0"
+    "effect": ">=4.0.0-rc.111 <5.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/OpenAIDeepResearch.ts

@@ -87,20 +87,15 @@ 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.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" })),
   )
 

package/src/OpenAIEmbedding.ts

@@ -241,12 +241,10 @@ const embedManyImpl =
   ): Effect.Effect<EmbedManyResponse, AiError.AiError, HttpClient.HttpClient> =>
     buildBatchBody(request).pipe(
       Effect.flatMap((body) => postEmbed(cfg, body)),
-      Effect.map(
-        (decoded): EmbedManyResponse => ({
-          embeddings: orderedEmbeddings(decoded.data),
-          usage: usageOf(decoded.usage),
-        }),
-      ),
+      Effect.map((decoded): EmbedManyResponse => ({
+        embeddings: orderedEmbeddings(decoded.data),
+        usage: usageOf(decoded.usage),
+      })),
     )
 
 // ---------------------------------------------------------------------------
@@ -279,29 +277,26 @@ export const layer = (
   const typed = Layer.effect(OpenAIEmbedding, make(cfg))
   const generic = Layer.effect(
     EmbeddingModel,
-    Effect.map(
-      make(cfg),
-      (s): EmbeddingModelService => ({
-        // OpenAI emits float32 only and has no task parameter. Reject a
-        // non-float32 `encoding` (bucket 1, else a float32 vector comes back
-        // mislabeled as the requested type) and warn on a dropped `task`
-        // (bucket 2).
-        embed: <E extends EmbedEncoding | undefined = undefined>(
-          req: Omit<CommonEmbedRequest, "encoding"> & { readonly encoding?: E },
-        ) =>
-          assertEncoding(req.encoding, ["float32"], "openai").pipe(
-            Effect.andThen(warnTaskDropped(req.task)),
-            Effect.andThen(s.embed(req as OpenAIEmbedRequest)),
-          ) as Effect.Effect<EmbedResponse<E>, AiError.AiError>,
-        embedMany: <E extends EmbedEncoding | undefined = undefined>(
-          req: Omit<CommonEmbedManyRequest, "encoding"> & { readonly encoding?: E },
-        ) =>
-          assertEncoding(req.encoding, ["float32"], "openai").pipe(
-            Effect.andThen(warnTaskDropped(req.task)),
-            Effect.andThen(s.embedMany(req as OpenAIEmbedManyRequest)),
-          ) as Effect.Effect<EmbedManyResponse<E>, AiError.AiError>,
-      }),
-    ),
+    Effect.map(make(cfg), (s): EmbeddingModelService => ({
+      // OpenAI emits float32 only and has no task parameter. Reject a
+      // non-float32 `encoding` (bucket 1, else a float32 vector comes back
+      // mislabeled as the requested type) and warn on a dropped `task`
+      // (bucket 2).
+      embed: <E extends EmbedEncoding | undefined = undefined>(
+        req: Omit<CommonEmbedRequest, "encoding"> & { readonly encoding?: E },
+      ) =>
+        assertEncoding(req.encoding, ["float32"], "openai").pipe(
+          Effect.andThen(warnTaskDropped(req.task)),
+          Effect.andThen(s.embed(req as OpenAIEmbedRequest)),
+        ) as Effect.Effect<EmbedResponse<E>, AiError.AiError>,
+      embedMany: <E extends EmbedEncoding | undefined = undefined>(
+        req: Omit<CommonEmbedManyRequest, "encoding"> & { readonly encoding?: E },
+      ) =>
+        assertEncoding(req.encoding, ["float32"], "openai").pipe(
+          Effect.andThen(warnTaskDropped(req.task)),
+          Effect.andThen(s.embedMany(req as OpenAIEmbedManyRequest)),
+        ) as Effect.Effect<EmbedManyResponse<E>, AiError.AiError>,
+    })),
   )
   return Layer.merge(typed, generic)
 }

package/src/Responses.ts

@@ -51,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
@@ -108,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>>
 }
 
 // ---------------------------------------------------------------------------
@@ -136,6 +156,7 @@ const buildText = (request: ResponsesRequest): Record<string, unknown> | undefin
 const buildBody = (
   request: ResponsesRequest,
   providerToolWire: ReadonlyArray<Record<string, unknown>>,
+  cfg: Config,
 ): Record<string, unknown> => {
   const text = buildText(request)
   const functionTools = descriptorsOf(request.tools).map((t) => ({
@@ -176,6 +197,8 @@ const buildBody = (
     }),
     ...(request.truncation !== undefined && { truncation: request.truncation }),
     ...(text !== undefined && { text }),
+    ...cfg.extraBody,
+    ...request.extraBody,
   }
 }
 
@@ -309,7 +332,7 @@ const buildNativeStream = (cfg: Config) => {
         )
         const httpRequest = HttpClientRequest.post(url).pipe(
           HttpClientRequest.bearerToken(cfg.apiKey),
-          HttpClientRequest.bodyJsonUnsafe(buildBody(request, providerToolWire)),
+          HttpClientRequest.bodyJsonUnsafe(buildBody(request, providerToolWire, cfg)),
           HttpClientRequest.accept("text/event-stream"),
         )
         const response = yield* client
@@ -373,13 +396,10 @@ export const layer = (
   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),
-        turn: (request) => s.turn(request as ResponsesRequest),
-      }),
-    ),
+    Effect.map(make(cfg), (s): LanguageModelService => ({
+      streamTurn: (request) => s.streamTurn(request as ResponsesRequest),
+      turn: (request) => s.turn(request as ResponsesRequest),
+    })),
   )
   return Layer.merge(typed, generic)
 }

package/src/ResponsesTools.ts

@@ -139,12 +139,10 @@ const renderOne = (
       })
     : decodeConfig(tool.config).pipe(
         Result.map(configToWire),
-        Result.mapError(
-          (): ToolRenderError => ({
-            capability: "providerTool",
-            reason: `unrecognized Responses provider tool config on "${tool.name}"`,
-          }),
-        ),
+        Result.mapError((): ToolRenderError => ({
+          capability: "providerTool",
+          reason: `unrecognized Responses provider tool config on "${tool.name}"`,
+        })),
       )
 
 /**

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"
 
@@ -159,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;
@@ -253,7 +273,7 @@ export const wireItemToItem = (wire: WireOutputItem): ReadonlyArray<HistoryItem>
           type: "message" as const,
           role: m.role,
           content: m.content.map(wireMessageContentToBlock),
-          providerData: m,
+          providerData: { responses: m },
         },
       ],
       function_call: (f): ReadonlyArray<HistoryItem> => [
@@ -262,7 +282,7 @@ export const wireItemToItem = (wire: WireOutputItem): ReadonlyArray<HistoryItem>
           call_id: f.call_id,
           name: f.name,
           arguments: f.arguments,
-          providerData: f,
+          providerData: { responses: f },
         },
       ],
       reasoning: (r): ReadonlyArray<HistoryItem> => [
@@ -273,7 +293,7 @@ export const wireItemToItem = (wire: WireOutputItem): ReadonlyArray<HistoryItem>
             summary: r.summary.map((s) => s.text).join("\n"),
           }),
           ...(r.encrypted_content !== undefined && { signature: r.encrypted_content }),
-          providerData: r,
+          providerData: { responses: r },
         },
       ],
       // Hosted-tool calls are provider-executed; drop from the turn (Phase 1).