effect 4.0.6 → 4.0.7

package/src/ai/McpServer.ts

@@ -770,11 +770,19 @@ const runWithRuntime = Effect.fnUntraced(function*(
     clientStates.delete(clientId)
     runtime.disconnect(clientId)
   }
-  const sendRequestError = (clientId: number, requestId: string | number, error: unknown) =>
+  // The exit is sent already encoded, so it must carry only the JSON-RPC error members.
+  const sendRequestError = (
+    clientId: number,
+    requestId: string | number,
+    { code, data, message }: { readonly code: number; readonly message: string; readonly data?: unknown }
+  ) =>
     protocol.send(clientId, {
       _tag: "Exit",
       requestId,
-      exit: { _tag: "Failure", cause: [{ _tag: "Fail", error }] }
+      exit: {
+        _tag: "Failure",
+        cause: [{ _tag: "Fail", error: data === undefined ? { code, message } : { code, message, data } }]
+      }
     })
   const removeReverseRequestClient = (requestId: string, key: McpClientKey) => {
     const waiting = reverseRequestClients.get(requestId)
@@ -1000,16 +1008,9 @@ const runWithRuntime = Effect.fnUntraced(function*(
           response.exit._tag === "Failure" &&
           !response.exit.cause.some((failure) => failure._tag === "Fail")
         ) {
-          return protocol.send(clientId, {
-            _tag: "Exit",
-            requestId: response.requestId,
-            exit: {
-              _tag: "Failure",
-              cause: [{
-                _tag: "Fail",
-                error: new InternalError({ message: "Internal error" })
-              }]
-            }
+          return sendRequestError(clientId, response.requestId, {
+            code: McpSchema.INTERNAL_ERROR_CODE,
+            message: "Internal error"
           })
         }
       }
@@ -1900,7 +1901,7 @@ const normalizeMcpJsonRpcResponse = (response: unknown): unknown => {
 function mcpJsonRpcSerialization(options?: {
   readonly contentType?: string | undefined
 }): RpcSerialization.RpcSerialization["Service"] {
-  const serialization = RpcSerialization.jsonRpc(options)
+  const serialization = RpcSerialization.jsonRpc({ ...options, controlMessages: false })
   return RpcSerialization.RpcSerialization.of({
     ...serialization,
     makeUnsafe: () => {

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)

package/src/ai/Tool.ts

@@ -290,6 +290,12 @@ export interface Tool<
    */
   readonly needsApproval?: boolean | NeedsApprovalFunction<any> | undefined
 
+  /**
+   * Maps a successful tool result to the content sent to the model in place
+   * of the encoded result. `setSuccess` removes the mapping.
+   */
+  readonly toModelOutput?: ((result: any) => ReadonlyArray<Prompt.ToolModelOutputPart>) | undefined
+
   /**
    * Set whether user approval is required before executing this tool.
    */
@@ -955,6 +961,20 @@ export type ResultDecodingServices<T> = T extends Tool<
 > ? _Config["success"]["DecodingServices"] | _Config["failure"]["DecodingServices"]
   : never
 
+/**
+ * Extracts the services required to decode tool parameters.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 4.0.0
+ */
+export type ParametersDecodingServices<T> = T extends Tool<
+  infer _Name,
+  infer _Config,
+  infer _Requirements
+> ? _Config["parameters"]["DecodingServices"]
+  : never
+
 /**
  * Extracts the services required to encode tool parameters.
  *
@@ -1016,6 +1036,10 @@ export interface HandlerResult<Tool extends Any> {
    * into subsequent requests to the large language model.
    */
   readonly encodedResult: unknown
+  /**
+   * The output of the tool's `toModelOutput` mapping for a successful result.
+   */
+  readonly modelOutput?: ReadonlyArray<Prompt.ToolModelOutputPart> | undefined
   /**
    * Whether the result of executing the tool call handler was an error or not.
    */
@@ -1117,7 +1141,7 @@ const Proto = {
     return clone(this, { parametersSchema, jsonSchema: undefined })
   },
   setSuccess(this: Any, successSchema: Schema.Constraint) {
-    return clone(this, { successSchema })
+    return clone(this, { successSchema, toModelOutput: undefined })
   },
   setFailure(this: Any, failureSchema: Schema.Constraint) {
     return clone(this, { failureSchema })
@@ -1158,6 +1182,7 @@ const userDefinedProto = <
   readonly annotations: Context.Context<never>
   readonly failureMode: Mode
   readonly needsApproval?: NeedsApproval<Parameters> | undefined
+  readonly toModelOutput?: ((result: any) => ReadonlyArray<Prompt.ToolModelOutputPart>) | undefined
 }): Tool<
   Name,
   {
@@ -1220,6 +1245,7 @@ const dynamicProto = <
   readonly annotations: Context.Context<never>
   readonly failureMode: Mode
   readonly needsApproval?: NeedsApproval<any> | undefined
+  readonly toModelOutput?: ((result: any) => ReadonlyArray<Prompt.ToolModelOutputPart>) | undefined
   readonly jsonSchema: JsonSchema.JsonSchema | undefined
 }): Dynamic<
   Name,
@@ -1319,6 +1345,12 @@ export const make = <
    *   dynamically determine if approval is needed.
    */
   readonly needsApproval?: NeedsApproval<Parameters> | undefined
+  /**
+   * Maps a successful tool result to the content sent to the model in place
+   * of the encoded result, such as images or files. The application still
+   * receives the typed result.
+   */
+  readonly toModelOutput?: ((result: Success["Type"]) => ReadonlyArray<Prompt.ToolModelOutputPart>) | undefined
 }): Tool<
   Name,
   {
@@ -1339,7 +1371,8 @@ export const make = <
     failureSchema,
     failureMode: options?.failureMode ?? "error",
     annotations: Context.empty(),
-    needsApproval: options?.needsApproval as any
+    needsApproval: options?.needsApproval as any,
+    toModelOutput: options?.toModelOutput
   }) as any
 }
 
@@ -1447,6 +1480,7 @@ export const dynamic: {
       readonly failure?: Schema.Constraint | undefined
       readonly failureMode?: FailureMode | undefined
       readonly needsApproval?: NeedsApproval<any> | undefined
+      readonly toModelOutput?: ((result: any) => ReadonlyArray<Prompt.ToolModelOutputPart>) | undefined
     }
   >(name: Name, options?: Options): Dynamic<
     Name,
@@ -1471,6 +1505,7 @@ export const dynamic: {
     readonly failure?: Schema.Constraint | undefined
     readonly failureMode?: FailureMode | undefined
     readonly needsApproval?: NeedsApproval<any> | undefined
+    readonly toModelOutput?: ((result: any) => ReadonlyArray<Prompt.ToolModelOutputPart>) | undefined
   }
 >(name: Name, options?: Options): any => {
   const successSchema = options?.success ?? Schema.Unknown
@@ -1488,6 +1523,7 @@ export const dynamic: {
     failureMode: options?.failureMode ?? "error",
     annotations: Context.empty(),
     needsApproval: options?.needsApproval,
+    toModelOutput: options?.toModelOutput,
     jsonSchema
   })
 }

package/src/ai/Toolkit.ts

@@ -525,7 +525,10 @@ const Proto = {
             ),
           Stream.mapEffect(Effect.fnUntraced(function*(output) {
             const encodedResult = yield* encodeResult(output.result, output.isFailure)
-            return { ...output, encodedResult }
+            if (output.isFailure || output.preliminary || tool.toModelOutput === undefined) {
+              return { ...output, encodedResult }
+            }
+            return { ...output, encodedResult, modelOutput: tool.toModelOutput(output.result) }
           })),
           Stream.ensuring(Fiber.interrupt(fiber))
         ) satisfies Stream.Stream<Tool.HandlerResult<any>, any>

package/src/cli/Argument.ts

@@ -509,6 +509,11 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required argument is missing.
  *
+ * **Gotchas**
+ *
+ * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+ * the original `MissingArgument` error is returned.
+ *
  * **Example** (Showing a fallback prompt)
  *
  * ```ts import.meta.vitest
@@ -528,6 +533,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required argument is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingArgument` error is returned.
+   *
    * **Example** (Showing a fallback prompt)
    *
    * ```ts import.meta.vitest
@@ -547,6 +557,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required argument is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingArgument` error is returned.
+   *
    * **Example** (Showing a fallback prompt)
    *
    * ```ts import.meta.vitest

package/src/cli/CliError.ts

@@ -5,9 +5,10 @@
  * flags or arguments, unexpected positional arguments, invalid values, unknown
  * subcommands, rejected input combinations, user handler failures, and
  * requests to show command help. This module includes the `CliError` union,
- * the `isCliError` guard, schema-backed error classes with display messages,
- * and the `NonShowHelpErrors` union used when parse or validation errors
- * should be shown with help output.
+ * the `isCliError` guard, the `userMessage` annotation for rendering handler
+ * failures, schema-backed error classes with display messages, and the
+ * `NonShowHelpErrors` union used when parse or validation errors should be
+ * shown with help output.
  *
  * @stability unstable
  * @since 4.0.0
@@ -46,6 +47,82 @@ const TypeId = "~effect/cli/CliError"
  */
 export const isCliError = (u: unknown): u is CliError => Predicate.hasProperty(u, TypeId)
 
+/**
+ * Defines the string property key used to give an object error a user-facing
+ * message.
+ *
+ * **When to use**
+ *
+ * Use to type the property key that marks handler failures for rendering by
+ * `Command.run`.
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export type userMessage = "~effect/cli/CliError/userMessage"
+
+/**
+ * Defines the runtime property key used to give an object error a user-facing
+ * message.
+ *
+ * **When to use**
+ *
+ * Use when a handler fails with a domain error that should be shown to the
+ * user without wrapping it in {@link UserError}.
+ *
+ * **Details**
+ *
+ * When a handler failure has a string `[CliError.userMessage]`, `Command.run`
+ * renders it with the installed formatter, sets `Runtime.errorReported` to
+ * `false`, and rethrows the original error, so its tag is preserved. The
+ * global `Error` interface declares this key as an optional string.
+ *
+ * **Example** (Rendering a tagged handler failure)
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { CliError } from "effect/cli"
+ *
+ * class Occupied extends Schema.TaggedError<Occupied>()("Occupied", {
+ *   path: Schema.String
+ * }) {
+ *   override get [CliError.userMessage]() {
+ *     return `${this.path} already exists`
+ *   }
+ * }
+ *
+ * const error = new Occupied({ path: "config.yaml" })
+ * CliError.getUserMessage(error) // => "config.yaml already exists"
+ * ```
+ *
+ * @see {@link getUserMessage} for reading the message stored under this key
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export const userMessage: userMessage = "~effect/cli/CliError/userMessage"
+
+declare global {
+  interface Error {
+    readonly [userMessage]?: string
+  }
+}
+
+/**
+ * Reads the `CliError.userMessage` annotation from an error object, returning
+ * `undefined` when it is unset or not a string.
+ *
+ * @see {@link userMessage} for the annotation key this getter reads
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export const getUserMessage = (error: object): string | undefined =>
+  userMessage in error && typeof error[userMessage] === "string" ? error[userMessage] : undefined
+
 /**
  * Union type representing all possible CLI error conditions.
  *
@@ -624,6 +701,16 @@ export class UserError extends Schema.TaggedError<UserError>(
     if (this.cause instanceof Error && this.cause.message) return this.cause.message
     return "An error occurred"
   }
+
+  /**
+   * Exposes `message` as the user-facing message rendered by `Command.run`.
+   *
+   * @stability unstable
+   * @since 4.0.0
+   */
+  override get [userMessage]() {
+    return this.message
+  }
 }
 
 /**