effect 4.0.6 → 4.1.0

package/src/ai/McpTest.ts

@@ -0,0 +1,380 @@
+/**
+ * In-memory test client for `McpServer` registrations.
+ *
+ * `McpTest.makeClient` runs the MCP server over an in-memory
+ * `RpcServer.Protocol`, performs the handshake for the selected protocol
+ * version, and returns a typed client. Requests travel through the same
+ * JSON-RPC encoding, routing, middleware, and response encoding as the stdio
+ * and HTTP transports, so tests reach protocol encoding, list methods,
+ * sessions, and notifications without opening a transport.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import type * as Arr from "../Array.ts"
+import * as Cause from "../Cause.ts"
+import * as Context from "../Context.ts"
+import * as Effect from "../Effect.ts"
+import { identity } from "../Function.ts"
+import * as Layer from "../Layer.ts"
+import * as Predicate from "../Predicate.ts"
+import * as Queue from "../Queue.ts"
+import * as RpcClient from "../rpc/RpcClient.ts"
+import type * as RpcClientError from "../rpc/RpcClientError.ts"
+import * as RpcMessage from "../rpc/RpcMessage.ts"
+import * as RpcSerialization from "../rpc/RpcSerialization.ts"
+import * as RpcServer from "../rpc/RpcServer.ts"
+import * as Schema from "../Schema.ts"
+import type * as Scope from "../Scope.ts"
+import type * as McpProtocol from "./McpProtocol.ts"
+import * as McpSchema from "./McpSchema.ts"
+import * as McpServer from "./McpServer.ts"
+
+/**
+ * A typed in-memory MCP client connected to a running `McpServer`.
+ *
+ * **Details**
+ *
+ * Each request method mirrors one entry of `McpSchema.ClientRequestRpcs`,
+ * except `initialize`, which `makeClient` sends during the handshake. Requests
+ * are encoded with the client schemas and decoded with the server's selected
+ * protocol adapter, so results and errors match what a wire client observes.
+ *
+ * Server-to-client notifications are queued on `notifications` in their wire
+ * encoding, in delivery order. Server-to-client requests (elicitation, sampling, roots) are
+ * rejected with a method-not-found error.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Client {
+  /**
+   * The protocol version negotiated during the handshake.
+   */
+  readonly protocolVersion: McpProtocol.ProtocolVersion
+  /**
+   * The `McpServer` service the client is connected to, for registering
+   * capabilities or emitting notifications from a test.
+   */
+  readonly server: McpServer.McpServer["Service"]
+  /**
+   * Notifications the server sent to this client, in delivery order.
+   */
+  readonly notifications: Queue.Dequeue<McpSchema.ServerNotificationEncoded>
+  readonly ping: Effect.Effect<void, McpSchema.McpError>
+  readonly listTools: (
+    request?: typeof McpSchema.ListTools.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.ListToolsResult, McpSchema.McpError>
+  readonly callTool: (
+    request: typeof McpSchema.CallTool.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.CallToolResult, McpSchema.McpError>
+  readonly listResources: (
+    request?: typeof McpSchema.ListResources.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.ListResourcesResult, McpSchema.McpError>
+  readonly listResourceTemplates: (
+    request?: typeof McpSchema.ListResourceTemplates.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.ListResourceTemplatesResult, McpSchema.McpError>
+  readonly readResource: (
+    request: typeof McpSchema.ReadResource.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.ReadResourceResult, McpSchema.McpError>
+  readonly subscribe: (
+    request: typeof McpSchema.Subscribe.payloadSchema.Type
+  ) => Effect.Effect<void, McpSchema.McpError>
+  readonly unsubscribe: (
+    request: typeof McpSchema.Unsubscribe.payloadSchema.Type
+  ) => Effect.Effect<void, McpSchema.McpError>
+  readonly listPrompts: (
+    request?: typeof McpSchema.ListPrompts.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.ListPromptsResult, McpSchema.McpError>
+  readonly getPrompt: (
+    request: typeof McpSchema.GetPrompt.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.GetPromptResult, McpSchema.McpError>
+  readonly complete: (
+    request: typeof McpSchema.Complete.payloadSchema.Type
+  ) => Effect.Effect<McpSchema.CompleteResult, McpSchema.McpError>
+  readonly setLevel: (
+    request: typeof McpSchema.SetLevel.payloadSchema.Type
+  ) => Effect.Effect<void, McpSchema.McpError>
+}
+
+/**
+ * Creates an in-memory MCP client for a registration layer.
+ *
+ * **Details**
+ *
+ * The server is built from `McpServer.layer` with the supplied `protocols`
+ * and `registrations`, over an in-memory `RpcServer.Protocol`. The client
+ * speaks `options.protocolVersion`, by default the first adapter's version:
+ * stateful versions `initialize` and send `notifications/initialized` before
+ * `makeClient` returns; the stateless version attaches request metadata to
+ * every request instead.
+ *
+ * Because requests reach handlers through the server runner, the transport
+ * built-ins are discharged the same way as on stdio: `McpRequestContext` on
+ * every request, and `McpServerClient` only when every adapter in `protocols`
+ * is stateful (see `McpServer.ProvidedServices`). Any other `McpRequest`
+ * marker in `registrations` stays in the requirements and must be met by MCP
+ * middleware; providing the service directly does not discharge it.
+ *
+ * The client and server live in the surrounding `Scope`.
+ *
+ * **Example** (Reading a resource in a test)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { McpProtocol, McpServer, McpTest } from "effect/ai"
+ *
+ * const registrations = McpServer.resource({
+ *   uri: "test://greeting",
+ *   name: "greeting",
+ *   content: Effect.succeed("hello")
+ * })
+ *
+ * const program = Effect.gen(function*() {
+ *   const client = yield* McpTest.makeClient(registrations, {
+ *     protocols: [McpProtocol.v2025_11_25]
+ *   })
+ *   const result = yield* client.readResource({ uri: "test://greeting" })
+ *   return result.contents.map((content) => content.uri)
+ * }).pipe(Effect.scoped)
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => ["test://greeting"]
+ * ```
+ *
+ * @see {@link Client} for the request methods and notifications
+ * @see {@link McpServer.middleware} for discharging request-level dependencies
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const makeClient: <
+  const Protocols extends Arr.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter>,
+  RA = never,
+  RE = never,
+  RR = never
+>(
+  registrations: Layer.Layer<RA, RE, RR>,
+  options: {
+    readonly protocols: Protocols
+    readonly protocolVersion?: Protocols[number]["protocolVersion"] | undefined
+    readonly name?: string | undefined
+    readonly version?: string | undefined
+    readonly instructions?: string | undefined
+    readonly extensions?: NonNullable<McpSchema.ServerCapabilities["extensions"]> | undefined
+    readonly clientInfo?: McpSchema.Implementation | undefined
+    readonly clientCapabilities?: McpSchema.ClientCapabilities | undefined
+  }
+) => Effect.Effect<
+  Client,
+  Cause.IllegalArgumentError | RE,
+  | Scope.Scope
+  | Exclude<McpServer.McpRequest.Without<RR>, McpServer.McpServer>
+  | McpServer.McpRequest.From<
+    "Requires",
+    Exclude<McpServer.McpRequest.Only<"Requires", RR>, McpServer.ProvidedServices<Protocols>>
+  >
+> = Effect.fnUntraced(function*(
+  registrations: Layer.Layer<any, any, any>,
+  options: {
+    readonly protocols: Arr.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter>
+    readonly protocolVersion?: string | undefined
+    readonly name?: string | undefined
+    readonly version?: string | undefined
+    readonly instructions?: string | undefined
+    readonly extensions?: NonNullable<McpSchema.ServerCapabilities["extensions"]> | undefined
+    readonly clientInfo?: McpSchema.Implementation | undefined
+    readonly clientCapabilities?: McpSchema.ClientCapabilities | undefined
+  }
+) {
+  const selected = options.protocolVersion === undefined
+    ? options.protocols[0]
+    : options.protocols.find((protocol) => protocol.protocolVersion === options.protocolVersion)
+  if (selected === undefined) {
+    return yield* new Cause.IllegalArgumentError(
+      `MCP protocol ${options.protocolVersion} is not in the configured protocols`
+    )
+  }
+  const clientInfo = options.clientInfo ?? defaultClientInfo
+  const clientCapabilities = options.clientCapabilities ?? new McpSchema.ClientCapabilities({})
+
+  // Each direction carries one serialized JSON-RPC message per element, so
+  // requests and responses round-trip through the same JSON-RPC encoding as
+  // the stdio and HTTP transports.
+  const toServer = yield* Queue.unbounded<string>()
+  const toClient = yield* Queue.unbounded<string>()
+  const notifications = yield* Queue.unbounded<McpSchema.ServerNotificationEncoded>()
+  const serverProtocol = RpcServer.Protocol.make(Effect.fnUntraced(function*(writeRequest) {
+    const parser = serialization.makeUnsafe()
+    yield* Queue.take(toServer).pipe(
+      Effect.flatMap((frame) =>
+        Effect.forEach(
+          parser.decode(frame) as ReadonlyArray<RpcMessage.FromClientEncoded>,
+          (message) => writeRequest(0, message),
+          { discard: true }
+        )
+      ),
+      Effect.forever,
+      Effect.forkScoped
+    )
+    return {
+      disconnects: yield* Queue.make<number>(),
+      send(_clientId, response) {
+        const encoded = parser.encode(response)
+        return typeof encoded === "string" ? Effect.asVoid(Queue.offer(toClient, encoded)) : Effect.void
+      },
+      end: () => Effect.void,
+      clientIds: Effect.succeed(new Set([0])),
+      initialMessage: Effect.succeedNone,
+      supportsAck: false,
+      supportsTransferables: false,
+      supportsSpanPropagation: false,
+      supportsNotifications: true,
+      codecFor: serialization.codecFor
+    }
+  }))
+  const context = yield* Layer.build(
+    McpServer.layer({
+      name: options.name ?? "McpTest",
+      version: options.version ?? "1.0.0",
+      instructions: options.instructions,
+      extensions: options.extensions,
+      protocols: options.protocols,
+      registrations
+    }).pipe(Layer.provide(Layer.effect(RpcServer.Protocol, serverProtocol)))
+  )
+  const server = Context.get(context as Context.Context<McpServer.McpServer>, McpServer.McpServer)
+
+  const write = (message: object) => Effect.asVoid(Queue.offer(toServer, JSON.stringify(message)))
+
+  // Stateless revisions carry the client profile on every request instead of
+  // negotiating it with `initialize`.
+  const requestMetadata = selected.runtime._tag === "Stateless"
+    ? {
+      "io.modelcontextprotocol/protocolVersion": selected.protocolVersion,
+      "io.modelcontextprotocol/clientCapabilities": encodeClientCapabilities(clientCapabilities),
+      "io.modelcontextprotocol/clientInfo": encodeImplementation(clientInfo)
+    }
+    : undefined
+  const params = (payload: unknown) => {
+    if (requestMetadata === undefined) {
+      return payload === undefined || payload === null ? {} : { params: payload }
+    }
+    const fields = Predicate.isReadonlyObject(payload) ? payload : {}
+    return {
+      params: {
+        ...fields,
+        _meta: { ...requestMetadata, ...(Predicate.isReadonlyObject(fields._meta) ? fields._meta : {}) }
+      }
+    }
+  }
+
+  const protocol = yield* RpcClient.Protocol.make(Effect.fnUntraced(function*(writeResponse) {
+    const parser = serialization.makeUnsafe()
+    let clientId = 0
+    const route = (message: RpcMessage.FromServerEncoded | RpcMessage.FromClientEncoded): Effect.Effect<void> => {
+      if (message._tag !== "Request") {
+        return writeResponse(clientId, message as RpcMessage.FromServerEncoded)
+      }
+      if (message.isNotification === true) {
+        return Effect.asVoid(Queue.offer(notifications, {
+          _tag: "Notification",
+          method: message.tag,
+          payload: message.payload ?? undefined
+        } as McpSchema.ServerNotificationEncoded))
+      }
+      // Server-to-client requests are not supported, so reject them instead
+      // of leaving the handler waiting for a reply.
+      return write({
+        jsonrpc: "2.0",
+        id: message.id,
+        error: { code: McpSchema.METHOD_NOT_FOUND_ERROR_CODE, message: `Method not found: ${message.tag}` }
+      })
+    }
+    yield* Queue.take(toClient).pipe(
+      Effect.flatMap((frame) =>
+        Effect.forEach(
+          parser.decode(frame) as ReadonlyArray<RpcMessage.FromServerEncoded | RpcMessage.FromClientEncoded>,
+          route,
+          { discard: true }
+        )
+      ),
+      Effect.forever,
+      Effect.forkScoped
+    )
+    return {
+      send(id, request) {
+        clientId = id
+        switch (request._tag) {
+          case "Request":
+            return write({ jsonrpc: "2.0", id: request.id, method: request.tag, ...params(request.payload) })
+          case "Interrupt":
+            return write({
+              jsonrpc: "2.0",
+              method: "notifications/cancelled",
+              ...params({ requestId: request.requestId })
+            })
+          default:
+            // Effect RPC control messages are not part of the MCP protocol.
+            return Effect.void
+        }
+      },
+      supportsAck: false,
+      supportsTransferables: false,
+      codecFor: serialization.codecFor
+    }
+  }))
+  let nextRequestId = 1
+  const rpc = yield* RpcClient.make(McpSchema.ClientRequestRpcs, {
+    spanPrefix: "McpTest",
+    generateRequestId: () => RpcMessage.RequestId(nextRequestId++)
+  }).pipe(Effect.provideService(RpcClient.Protocol, protocol))
+
+  let protocolVersion = selected.protocolVersion
+  if (selected.runtime._tag === "Stateful") {
+    const result = yield* rpc.initialize({
+      protocolVersion: selected.protocolVersion,
+      capabilities: clientCapabilities,
+      clientInfo
+    }).pipe(Effect.orDie)
+    protocolVersion = result.protocolVersion as McpProtocol.ProtocolVersion
+    yield* write({ jsonrpc: "2.0", method: "notifications/initialized" })
+  }
+
+  return identity<Client>({
+    protocolVersion,
+    server,
+    notifications,
+    ping: Effect.asVoid(orDieClientError(rpc.ping(undefined))),
+    listTools: (request) => orDieClientError(rpc["tools/list"](request)),
+    callTool: (request) => orDieClientError(rpc["tools/call"](request)),
+    listResources: (request) => orDieClientError(rpc["resources/list"](request)),
+    listResourceTemplates: (request) => orDieClientError(rpc["resources/templates/list"](request)),
+    readResource: (request) => orDieClientError(rpc["resources/read"](request)),
+    subscribe: (request) => Effect.asVoid(orDieClientError(rpc["resources/subscribe"](request))),
+    unsubscribe: (request) => Effect.asVoid(orDieClientError(rpc["resources/unsubscribe"](request))),
+    listPrompts: (request) => orDieClientError(rpc["prompts/list"](request)),
+    getPrompt: (request) => orDieClientError(rpc["prompts/get"](request)),
+    complete: (request) => orDieClientError(rpc["completion/complete"](request)),
+    setLevel: (request) => Effect.asVoid(orDieClientError(rpc["logging/setLevel"](request)))
+  })
+}) as any
+
+const serialization = RpcSerialization.jsonRpc()
+
+const defaultClientInfo: McpSchema.Implementation = { name: "McpTest", version: "1.0.0" }
+
+const encodeClientCapabilities = Schema.encodeSync(Schema.toCodecJson(McpSchema.ClientCapabilities))
+const encodeImplementation = Schema.encodeSync(Schema.toCodecJson(McpSchema.Implementation))
+
+// The in-memory transport never fails to send, so a client error is a defect.
+const orDieClientError = <A, E>(
+  effect: Effect.Effect<A, E | RpcClientError.RpcClientError>
+): Effect.Effect<A, Exclude<E, RpcClientError.RpcClientError>> =>
+  Effect.catchIf(
+    effect,
+    (error): error is RpcClientError.RpcClientError => Predicate.isTagged(error, "RpcClientError"),
+    Effect.die
+  ) as any

package/src/ai/Prompt.ts

@@ -689,6 +689,60 @@ export const toolCallPart = (params: PartConstructorParams<ToolCallPart>): ToolC
 // Tool Result Part
 // =============================================================================
 
+/**
+ * A part returned by a tool's `toModelOutput` mapping and sent to the model in
+ * place of the serialized tool result.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type ToolModelOutputPart = TextPart | FilePart
+
+/**
+ * Schema for validation and encoding of tool model output parts.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const ToolModelOutputPart: Schema.Union<readonly [typeof TextPart, typeof FilePart]> = Schema.Union([
+  TextPart,
+  FilePart
+])
+
+/**
+ * Converts tool model output to text for providers that only accept text tool
+ * results.
+ *
+ * **Details**
+ *
+ * Joins text parts with newlines and replaces each file part with a placeholder
+ * naming its media type and file name.
+ *
+ * **Example** (Converting tool model output to text)
+ *
+ * ```ts import.meta.vitest
+ * import { Prompt } from "effect/ai"
+ *
+ * const text = Prompt.toolModelOutputToText([
+ *   Prompt.textPart({ text: "Screenshot" }),
+ *   Prompt.filePart({ mediaType: "image/png", fileName: "screenshot.png", data: "iVBORw0KGgo=" })
+ * ])
+ * text // => "Screenshot\n[image/png screenshot.png omitted]"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.0.0
+ */
+export const toolModelOutputToText = (parts: ReadonlyArray<ToolModelOutputPart>): string =>
+  parts.map((part) =>
+    part.type === "text"
+      ? part.text
+      : `[${part.mediaType}${part.fileName === undefined ? "" : ` ${part.fileName}`} omitted]`
+  ).join("\n")
+
 /**
  * Content part representing the result of a tool call.
  *
@@ -732,6 +786,10 @@ export interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOp
    * The result returned by the tool execution.
    */
   readonly result: unknown
+  /**
+   * Content sent to the model in place of the serialized `result`.
+   */
+  readonly modelOutput?: ReadonlyArray<ToolModelOutputPart> | undefined
   /**
    * Whether the tool was executed by the provider (true) or framework (false).
    */
@@ -762,6 +820,10 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
    * The result returned by the tool execution.
    */
   readonly result: unknown
+  /**
+   * Content sent to the model in place of the serialized `result`.
+   */
+  readonly modelOutput?: ReadonlyArray<TextPartEncoded | FilePartEncoded> | undefined
   /**
    * Whether the tool was executed by the provider (true) or framework (false).
    */
@@ -791,6 +853,7 @@ export const ToolResultPart: Schema.Struct<{
   readonly name: Schema.String
   readonly isFailure: Schema.Boolean
   readonly result: Schema.Unknown
+  readonly modelOutput: Schema.optional<Schema.$Array<typeof ToolModelOutputPart>>
   readonly providerExecuted: Schema.withDecodingDefault<Schema.Boolean>
   readonly "~effect/ai/Prompt/Part": Schema.withDecodingDefaultKey<Schema.Literal<"~effect/ai/Prompt/Part">>
   readonly options: Schema.withDecodingDefault<
@@ -806,6 +869,7 @@ export const ToolResultPart: Schema.Struct<{
   name: Schema.String,
   isFailure: Schema.Boolean,
   result: Schema.Unknown,
+  modelOutput: Schema.optional(Schema.Array(ToolModelOutputPart)),
   providerExecuted: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false)))
 }).annotate({ identifier: "ToolResultPart" })
 
@@ -2272,6 +2336,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
             name: part.name,
             isFailure: part.isFailure,
             result: part.encodedResult,
+            ...(part.modelOutput !== undefined ? { modelOutput: part.modelOutput } : undefined),
             providerExecuted: part.providerExecuted ?? false,
             options: part.metadata
           }))

package/src/ai/Response.ts

@@ -18,6 +18,7 @@ import * as Predicate from "../Predicate.ts"
 import * as Schema from "../Schema.ts"
 import * as SchemaTransformation from "../SchemaTransformation.ts"
 import * as AiError from "./AiError.ts"
+import * as Prompt from "./Prompt.ts"
 import * as Tool from "./Tool.ts"
 import type * as Toolkit from "./Toolkit.ts"
 
@@ -172,6 +173,18 @@ const toolPartSchemas = (tool: Tool.Any) => {
 
 type AnyToolParts = ToolCallPart<string, unknown> | ToolResultPart<string, unknown, unknown>
 
+type ToolkitTools<T> = T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>
+
+type ToolkitTool<T> = ToolkitTools<T>[keyof ToolkitTools<T>]
+
+type ToolkitDecodingServices<T> =
+  | Tool.ParametersDecodingServices<ToolkitTool<T>>
+  | Tool.ResultDecodingServices<ToolkitTool<T>>
+
+type ToolkitEncodingServices<T> =
+  | Tool.ParametersEncodingServices<ToolkitTool<T>>
+  | Tool.ResultEncodingServices<ToolkitTool<T>>
+
 const toolPartSchemasFor = (
   toolkit: Toolkit.Any | Toolkit.WithHandler<any> | undefined
 ): ReadonlyArray<Schema.Top> => {
@@ -257,10 +270,10 @@ export const AllParts: {
    * @since 4.0.0
    */
   <T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T): Schema.Codec<
-    AllParts<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
+    AllParts<ToolkitTools<T>>,
     AllPartsEncoded,
-    Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
-    Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
+    ToolkitDecodingServices<T>,
+    ToolkitEncodingServices<T>
   >
   /**
    * Creates a Schema for all response parts based on a toolkit.
@@ -395,10 +408,10 @@ export const Part: {
    * @since 4.0.0
    */
   <T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T): Schema.Codec<
-    Part<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
+    Part<ToolkitTools<T>>,
     PartEncoded,
-    Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
-    Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
+    ToolkitDecodingServices<T>,
+    ToolkitEncodingServices<T>
   >
   /**
    * Creates a Schema for non-streaming response parts based on a toolkit.
@@ -513,10 +526,10 @@ export const StreamPart: {
    * @since 4.0.0
    */
   <T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T): Schema.Codec<
-    StreamPart<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
+    StreamPart<ToolkitTools<T>>,
     StreamPartEncoded,
-    Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
-    Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
+    ToolkitDecodingServices<T>,
+    ToolkitEncodingServices<T>
   >
   /**
    * Creates a Schema for streaming response parts based on a toolkit.
@@ -1695,6 +1708,10 @@ export interface BaseToolResult<Name extends string> extends BasePart<"tool-resu
    * The encoded result for serialization purposes.
    */
   readonly encodedResult: unknown
+  /**
+   * Content sent to the model in place of the encoded result.
+   */
+  readonly modelOutput?: ReadonlyArray<Prompt.ToolModelOutputPart> | undefined
   /**
    * Whether the tool was executed by the provider (true) or framework (false).
    */
@@ -1818,6 +1835,10 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
    * The result returned by the tool execution.
    */
   readonly result: unknown
+  /**
+   * Content sent to the model in place of the result.
+   */
+  readonly modelOutput?: ReadonlyArray<Prompt.TextPartEncoded | Prompt.FilePartEncoded> | undefined
   /**
    * Whether or not the result of executing the tool call handler was an error.
    */
@@ -1871,6 +1892,8 @@ export const ToolResultPart = <
     identifier: `ToolResultPart(${name})`
   }) as any
 
+const ModelOutput = Schema.Array(Prompt.ToolModelOutputPart)
+
 const makeToolResultPart = (name: Schema.Top, success: Schema.Constraint, failure: Schema.Constraint) => {
   const makeSchema = (result: Schema.Constraint, isFailure: boolean) => {
     const encodedResult = Schema.toEncoded(result)
@@ -1887,11 +1910,13 @@ const makeToolResultPart = (name: Schema.Top, success: Schema.Constraint, failur
       providerExecuted: Schema.Boolean,
       metadata: ProviderMetadata,
       encodedResult,
+      modelOutput: Schema.optional(ModelOutput),
       preliminary: Schema.Boolean
     })
     const Encoded = Schema.Struct({
       ...Common,
       result: encodedResult,
+      modelOutput: Schema.optional(Schema.toEncoded(ModelOutput)),
       providerExecuted: Schema.optional(Schema.Boolean),
       metadata: Schema.optional(ProviderMetadata),
       preliminary: Schema.optional(Schema.Boolean)
@@ -2351,15 +2376,6 @@ export const UrlSourcePart: Schema.Struct<{
 // HTTP Details
 // =============================================================================
 
-/**
- * Alias of {@link AiError.HttpRequestDetails}.
- *
- * @stability unstable
- * @category schemas
- * @since 4.0.0
- */
-export const HttpRequestDetails = AiError.HttpRequestDetails
-
 /**
  * Alias of {@link AiError.HttpResponseDetails}.
  *
@@ -2387,8 +2403,7 @@ export const HttpResponseDetails = AiError.HttpResponseDetails
  *   {
  *     id: "resp_123",
  *     modelId: "gpt-4",
- *     timestamp: DateTime.makeUnsafe("2024-01-01T00:00:00Z"),
- *     request: undefined
+ *     timestamp: DateTime.makeUnsafe("2024-01-01T00:00:00Z")
  *   }
  * )
  * const result = [metadataPart.id, metadataPart.modelId] // => ["resp_123", "gpt-4"]
@@ -2411,10 +2426,6 @@ export interface ResponseMetadataPart extends BasePart<"response-metadata", Resp
    * Optional timestamp when the response was generated.
    */
   readonly timestamp?: DateTime.Utc | undefined
-  /**
-   * Optional HTTP request details for the request made to the AI provider.
-   */
-  readonly request?: typeof HttpRequestDetails.Type | undefined
 }
 
 /**
@@ -2439,10 +2450,6 @@ export interface ResponseMetadataPartEncoded
    * Optional timestamp when the response was generated.
    */
   readonly timestamp?: string | undefined
-  /**
-   * Optional HTTP request details for the request made to the AI provider.
-   */
-  readonly request?: typeof HttpRequestDetails.Encoded | undefined
 }
 
 /**
@@ -2467,7 +2474,6 @@ export const ResponseMetadataPart: Schema.Struct<{
   readonly id: Schema.optional<Schema.String>
   readonly modelId: Schema.optional<Schema.String>
   readonly timestamp: Schema.optional<Schema.DateTimeUtcFromString>
-  readonly request: Schema.optional<typeof HttpRequestDetails>
   readonly "~effect/ai/Response/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Response/Part">>
   readonly metadata: Schema.withDecodingDefault<
     Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
@@ -2477,8 +2483,7 @@ export const ResponseMetadataPart: Schema.Struct<{
   type: Schema.tag("response-metadata"),
   id: Schema.optional(Schema.String),
   modelId: Schema.optional(Schema.String),
-  timestamp: Schema.optional(Schema.DateTimeUtcFromString),
-  request: Schema.optional(HttpRequestDetails)
+  timestamp: Schema.optional(Schema.DateTimeUtcFromString)
 }).annotate({ identifier: "ResponseMetadataPart" }) satisfies Schema.Codec<
   ResponseMetadataPart,
   ResponseMetadataPartEncoded