effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/ai/McpSchema.ts

@@ -46,6 +46,8 @@ import * as RpcMiddleware from "../rpc/RpcMiddleware.ts"
 /**
  * Schema type returned by `optionalWithDefault`.
  *
+ * **Details**
+ *
  * It represents an optional struct field that supplies a default value when the
  * field is absent during decoding or construction.
  *
@@ -60,6 +62,8 @@ export interface optionalWithDefault<S extends Schema.Top & Schema.WithoutConstr
  * Marks a struct field as optional and supplies `defaultValue` when the field
  * is absent.
  *
+ * **Details**
+ *
  * The default is used during decoding and as the constructor default for the
  * schema field.
  *
@@ -85,6 +89,8 @@ export const optionalWithDefault = <S extends Schema.Top & Schema.WithoutConstru
 /**
  * Creates an optional MCP struct-field schema from a required schema.
  *
+ * **Details**
+ *
  * The field may be absent, and explicit `undefined` values are omitted when
  * encoding.
  *
@@ -146,6 +152,8 @@ export type ProgressToken = typeof ProgressToken.Type
 /**
  * Schema for optional MCP request metadata.
  *
+ * **Details**
+ *
  * Request metadata may include a progress token that asks the receiver to send
  * out-of-band progress notifications for the request.
  *
@@ -168,6 +176,8 @@ export class RequestMeta extends Schema.Opaque<RequestMeta>()(Schema.Struct({
 /**
  * Schema for optional MCP result metadata.
  *
+ * **Details**
+ *
  * The `_meta` field is reserved for protocol, extension, or implementation
  * metadata attached to a result.
  *
@@ -185,6 +195,8 @@ export class ResultMeta extends Schema.Opaque<ResultMeta>()(Schema.Struct({
 /**
  * Schema for optional MCP notification metadata.
  *
+ * **Details**
+ *
  * The `_meta` field is reserved for protocol, extension, or implementation
  * metadata attached to a notification.
  *
@@ -210,6 +222,8 @@ export const Cursor: typeof Schema.String = Schema.String
 /**
  * Type represented by the MCP cursor schema.
  *
+ * **Details**
+ *
  * A cursor is an opaque string token used to continue paginated requests.
  *
  * @category common
@@ -220,6 +234,8 @@ export type Cursor = typeof Cursor.Type
 /**
  * Schema for MCP request metadata used by paginated requests.
  *
+ * **Details**
+ *
  * It includes the base request metadata fields plus an optional cursor
  * indicating where the server should continue listing results.
  *
@@ -238,6 +254,8 @@ export class PaginatedRequestMeta extends Schema.Opaque<PaginatedRequestMeta>()(
 /**
  * Schema for MCP result metadata returned by paginated operations.
  *
+ * **Details**
+ *
  * It includes the base result metadata fields plus an optional `nextCursor`,
  * which indicates that more results may be available.
  *
@@ -255,6 +273,7 @@ export class PaginatedResultMeta extends Schema.Opaque<PaginatedResultMeta>()(Sc
 
 /**
  * The sender or recipient of messages and data in a conversation.
+ *
  * @category common
  * @since 4.0.0
  */
@@ -263,6 +282,8 @@ export const Role: Schema.Literals<["user", "assistant"]> = Schema.Literals(["us
 /**
  * Type represented by the MCP role schema.
  *
+ * **Details**
+ *
  * Valid roles are `"user"` and `"assistant"`.
  *
  * @category common
@@ -412,6 +433,8 @@ export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Sche
 /**
  * Base schema for MCP and JSON-RPC error objects.
  *
+ * **Details**
+ *
  * It contains the numeric error `code`, a concise `message`, and optional
  * sender-defined `data`.
  *
@@ -475,9 +498,8 @@ export const INTERNAL_ERROR_CODE = -32603 as const
 export const PARSE_ERROR_CODE = -32700 as const
 
 /**
- * MCP/JSON-RPC error for invalid JSON that could not be parsed.
- *
- * This error uses the standard parse error code `-32700`.
+ * MCP/JSON-RPC error for invalid JSON that could not be parsed. This error
+ * uses the standard parse error code `-32700`.
  *
  * @category errors
  * @since 4.0.0
@@ -489,9 +511,8 @@ export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSche
 }) {}
 
 /**
- * MCP/JSON-RPC error for a request object that is not valid.
- *
- * This error uses the standard invalid request code `-32600`.
+ * MCP/JSON-RPC error for a request object that is not valid. This error uses
+ * the standard invalid request code `-32600`.
  *
  * @category errors
  * @since 4.0.0
@@ -504,7 +525,6 @@ export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai
 
 /**
  * MCP/JSON-RPC error for a method that does not exist or is not available.
- *
  * This error uses the standard method not found code `-32601`.
  *
  * @category errors
@@ -517,9 +537,8 @@ export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai
 }) {}
 
 /**
- * MCP/JSON-RPC error for invalid method parameters.
- *
- * This error uses the standard invalid params code `-32602`.
+ * MCP/JSON-RPC error for invalid method parameters. This error uses the
+ * standard invalid params code `-32602`.
  *
  * @category errors
  * @since 4.0.0
@@ -531,9 +550,8 @@ export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/M
 }) {}
 
 /**
- * MCP/JSON-RPC error for unexpected internal server failures.
- *
- * This error uses the standard internal error code `-32603` and includes
+ * MCP/JSON-RPC error for unexpected internal server failures. This error uses
+ * the standard internal error code `-32603` and includes
  * `InternalError.notImplemented` for unimplemented handlers.
  *
  * @category errors
@@ -661,6 +679,8 @@ export class InitializedNotification extends Rpc.make("notifications/initialized
  * Notification sent by either peer to cancel a previously issued request in
  * the same direction.
  *
+ * **Details**
+ *
  * The payload identifies the request to cancel and may include a
  * human-readable reason.
  *
@@ -1006,6 +1026,8 @@ export class Unsubscribe extends Rpc.make("resources/unsubscribe", {
 /**
  * Notification sent by the server when a subscribed resource URI has changed.
  *
+ * **Details**
+ *
  * The URI may identify a sub-resource of the resource that the client
  * originally subscribed to.
  *
@@ -1139,6 +1161,8 @@ export class AudioContent extends Schema.Opaque<AudioContent>()(Schema.Struct({
 /**
  * The contents of a resource, embedded into a prompt or tool call result.
  *
+ * **Details**
+ *
  * It is up to the client how best to render embedded resources for the benefit
  * of the LLM and/or the user.
  *
@@ -1155,9 +1179,13 @@ export class EmbeddedResource extends Schema.Opaque<EmbeddedResource>()(Schema.S
 })) {}
 
 /**
- * A resource that the server is capable of reading, included in a prompt or tool call result.
+ * A resource that the server is capable of reading, included in a prompt or
+ * tool call result.
  *
- * Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.
+ * **Gotchas**
+ *
+ * Resource links returned by tools are not guaranteed to appear in the results
+ * of `resources/list` requests.
  *
  * @category prompts
  * @since 4.0.0
@@ -1185,6 +1213,8 @@ export const ContentBlock = Schema.Union([
 /**
  * Describes a message returned as part of a prompt.
  *
+ * **Details**
+ *
  * This is similar to `SamplingMessage`, but also supports the embedding of
  * resources from the MCP server.
  *
@@ -1281,10 +1311,14 @@ export class PromptListChangedNotification extends Rpc.make("notifications/promp
 /**
  * Additional properties describing a Tool to clients.
  *
+ * **Details**
+ *
  * NOTE: all properties in ToolAnnotations are **hints**. They are not
  * guaranteed to provide a faithful description of tool behavior (including
  * descriptive properties like `title`).
  *
+ * **Gotchas**
+ *
  * Clients should never make tool use decisions based on ToolAnnotations
  * received from untrusted servers.
  *
@@ -1396,14 +1430,14 @@ export class ListTools extends Rpc.make("tools/list", {
 /**
  * The server's response to a tool call.
  *
+ * **Details**
+ *
  * Any errors that originate from the tool SHOULD be reported inside the result
  * object, with `isError` set to true, _not_ as an MCP protocol-level error
  * response. Otherwise, the LLM would not be able to see that an error occurred
- * and self-correct.
- *
- * However, any errors in _finding_ the tool, an error indicating that the
- * server does not support tool calls, or any other exceptional conditions,
- * should be reported as an MCP error response.
+ * and self-correct. However, any errors in _finding_ the tool, an error
+ * indicating that the server does not support tool calls, or any other
+ * exceptional conditions, should be reported as an MCP error response.
  *
  * @category tools
  * @since 4.0.0
@@ -1456,10 +1490,9 @@ export class ToolListChangedNotification extends Rpc.make("notifications/tools/l
 // =============================================================================
 
 /**
- * The severity of a log message.
- *
- * These map to syslog message severities, as specified in RFC-5424:
- * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+ * The severity of a log message, mapped to syslog message severities as
+ * specified in RFC 5424 section 6.2.1:
+ * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1.
  *
  * @category logging
  * @since 4.0.0
@@ -1485,10 +1518,9 @@ export const LoggingLevel: Schema.Literals<[
 ])
 
 /**
- * The severity of a log message.
- *
- * These map to syslog message severities, as specified in RFC-5424:
- * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+ * Type represented by the MCP logging level schema, mapped to syslog message
+ * severities as specified in RFC 5424 section 6.2.1:
+ * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1.
  *
  * @category logging
  * @since 4.0.0
@@ -1517,6 +1549,8 @@ export class SetLevel extends Rpc.make("logging/setLevel", {
 /**
  * Server notification carrying a log message for the client.
  *
+ * **Details**
+ *
  * The notification includes the severity level, optional logger name, and
  * JSON-serializable log data.
  *
@@ -1560,6 +1594,8 @@ export class SamplingMessage extends Schema.Opaque<SamplingMessage>()(Schema.Str
 /**
  * Hints to use for model selection.
  *
+ * **Details**
+ *
  * Keys not declared here are currently left unspecified by the spec and are up
  * to the client to interpret.
  *
@@ -1583,14 +1619,19 @@ export class ModelHint extends Schema.Opaque<ModelHint>()(Schema.Struct({
 })) {}
 
 /**
- * The server's preferences for model selection, requested of the client during sampling.
+ * The server's preferences for model selection, requested of the client during
+ * sampling.
+ *
+ * **Details**
  *
  * Because LLMs can vary along multiple dimensions, choosing the "best" model is
- * rarely straightforward.  Different models excel in different areas—some are
+ * rarely straightforward. Different models excel in different areas, some are
  * faster but less capable, others are more capable but more expensive, and so
  * on. This interface allows servers to express their priorities across multiple
  * dimensions to help clients make an appropriate selection for their use case.
  *
+ * **Gotchas**
+ *
  * These preferences are always advisory. The client MAY ignore them. It is also
  * up to the client to decide how to interpret these preferences and how to
  * balance them against other considerations.
@@ -1855,8 +1896,9 @@ export class ListRootsResult extends Schema.Class<ListRootsResult>(
  * Sent from the server to request a list of root URIs from the client. Roots
  * allow servers to ask for specific directories or files to operate on. A
  * common example for roots is providing a set of repositories or directories a
- * server should operate
- * on.
+ * server should operate on.
+ *
+ * **Details**
  *
  * This request is typically used when the server needs to understand the file
  * system structure or access specific locations that the client has permission
@@ -1946,6 +1988,8 @@ export const ElicitResult = Schema.Union([
  * Request sent by the server asking the client to collect structured input
  * from the user.
  *
+ * **Details**
+ *
  * The client responds with accepted content, an explicit decline, or a
  * cancellation.
  *
@@ -1973,6 +2017,8 @@ export class Elicit extends Rpc.make("elicitation/create", {
  * Error raised when an MCP elicitation request is declined or fails before
  * accepted content is returned.
  *
+ * **Details**
+ *
  * The error stores the original elicitation request and, when available, the
  * underlying cause.
  *
@@ -1994,6 +2040,8 @@ export class ElicitationDeclined
 /**
  * Service available while handling an MCP client request.
  *
+ * **Details**
+ *
  * It exposes the current client id, the client's initialize payload, and a
  * scoped RPC client for server-initiated requests back to that client.
  *
@@ -2121,6 +2169,8 @@ export type FailureEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
 /**
  * RPC group for requests that MCP clients send to the server.
  *
+ * **Details**
+ *
  * The group includes initialization, resource, prompt, tool, logging,
  * completion, and ping requests, and installs `McpServerClientMiddleware` for
  * handlers.
@@ -2304,6 +2354,8 @@ export function isParam(schema: Schema.Top): schema is Param<string, Schema.Top>
 /**
  * Schema wrapper used for resource URI template parameters.
  *
+ * **Details**
+ *
  * A `Param` behaves like the wrapped schema while carrying the parameter name
  * used for template compilation and completion lookup.
  *

package/src/unstable/ai/McpServer.ts

@@ -98,6 +98,8 @@ import type * as Toolkit from "./Toolkit.ts"
  * Service that stores and serves an MCP server's registered tools, resources,
  * prompts, completions, and outgoing notifications.
  *
+ * **Details**
+ *
  * Handlers use this service to register capabilities and resolve incoming MCP
  * requests.
  *
@@ -358,6 +360,8 @@ const mcpProtocolVersionHeader = "mcp-protocol-version"
 /**
  * Runs an MCP server over the current `RpcServer.Protocol`.
  *
+ * **Details**
+ *
  * The server performs initialization and session handling, serves registered
  * tools, resources, and prompts, and forwards queued server notifications to
  * initialized clients.
@@ -749,6 +753,8 @@ export type ValidateCompletions<Completions, Keys extends string> =
 /**
  * Completion-handler map for a resource URI template.
  *
+ * **Details**
+ *
  * Each schema interpolation contributes a parameter key, using an explicit
  * `Param` name when present or `paramN` otherwise, and each handler returns
  * candidate values for that parameter.
@@ -1135,6 +1141,8 @@ export const prompt = <
  * Requests structured input from the current MCP client and decodes the
  * accepted response with `schema`.
  *
+ * **Details**
+ *
  * Accepted content is decoded with the supplied schema, declined requests fail
  * with `ElicitationDeclined`, and canceled requests interrupt the effect.
  *

package/src/unstable/ai/Model.ts

@@ -40,12 +40,12 @@ const TypeId = "~effect/ai/Model" as const
 /**
  * A Model represents a provider-specific AI service.
  *
- * A Model can be used directly as a Layer to provide a particular model
- * implementation to an Effect program.
+ * **When to use**
  *
- * A Model can also be used as an Effect to "lift" dependencies of the Model
- * constructor into the parent Effect. This is particularly useful when you
- * want to use a Model from within an Effect service.
+ * Use a Model directly as a Layer to provide a particular model implementation
+ * to an Effect program, or use it as an Effect to "lift" dependencies of the
+ * Model constructor into the parent Effect when you want to use a Model from
+ * within an Effect service.
  *
  * @category models
  * @since 4.0.0
@@ -73,6 +73,8 @@ export interface Model<in out Provider, in out Provides, in out Requires>
 /**
  * Service tag that provides the current large language model provider name.
  *
+ * **Details**
+ *
  * This tag is automatically provided by Model instances and can be used to
  * access the name of the provider that is currently in use within a given
  * Effect program.
@@ -87,6 +89,8 @@ export class ProviderName extends Context.Service<ProviderName, string>()(
 /**
  * Service tag that provides the current large language model name.
  *
+ * **Details**
+ *
  * This tag is automatically provided by Model instances and can be used to
  * access the name of the model that is currently in use within a given Effect
  * program.

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -14,8 +14,9 @@ import * as Transformation from "../../SchemaTransformation.ts"
 import * as Tool from "./Tool.ts"
 
 /**
- * Transforms a `Schema.Codec` into a form compatible with OpenAI's
- * structured output constraints.
+ * Transforms a `Schema.Codec` into a form compatible with OpenAI's structured output constraints.
+ *
+ * **Details**
  *
  * The transformation walks the schema AST and rewrites constructs that
  * OpenAI does not support natively:

package/src/unstable/ai/Prompt.ts

@@ -70,18 +70,13 @@ import type * as Response from "./Response.ts"
 // =============================================================================
 
 /**
- * Schema for provider-specific options which can be attached to both content
- * parts and messages, enabling provider-specific behavior.
+ * Schema for provider-specific options that can be attached to content parts
+ * and messages.
  *
- * Provider-specific options are namespaced by provider and have the structure:
+ * **Details**
  *
- * ```
- * {
- *   "<provider-specific-key>": {
- *     // Provider-specific options
- *   }
- * }
- * ```
+ * Provider-specific options are keyed by provider-specific names, and each
+ * value is JSON or `null`.
  *
  * @category models
  * @since 4.0.0
@@ -117,8 +112,11 @@ export const isPart = (u: unknown): u is Part => Predicate.hasProperty(u, PartTy
 /**
  * Union type representing all possible content parts within messages.
  *
+ * **Details**
+ *
  * Parts are the building blocks of message content, supporting text, files,
- * reasoning, tool calls, and tool results.
+ * reasoning, tool calls, tool results, tool approval responses, and tool
+ * approval requests.
  *
  * @category models
  * @since 4.0.0
@@ -150,7 +148,10 @@ export type PartEncoded =
 /**
  * Base interface for all content parts.
  *
- * Provides common structure including type and provider options.
+ * **Details**
+ *
+ * It provides the common structure shared by all content parts, including the
+ * part type and provider options.
  *
  * @category models
  * @since 4.0.0
@@ -255,7 +256,10 @@ export type PartConstructorParams<P extends Part> = Omit<P, typeof PartTypeId |
 /**
  * Content part representing plain text.
  *
- * The most basic content type used for textual information in messages.
+ * **Details**
+ *
+ * Text parts are the basic content type used for textual information in
+ * messages.
  *
  * **Example** (Creating text parts)
  *
@@ -418,10 +422,12 @@ export const reasoningPart = (params: PartConstructorParams<ReasoningPart>): Rea
 // =============================================================================
 
 /**
- * Content part representing a file attachment. Files can be provided as base64
- * strings of data, byte arrays, or URLs.
+ * Content part representing a file attachment.
+ *
+ * **Details**
  *
- * Supports various file types including images, documents, and binary data.
+ * Files can be provided as base64 data strings, byte arrays, or URLs, and can
+ * represent images, documents, or other binary data.
  *
  * **Example** (Creating file parts)
  *
@@ -760,8 +766,10 @@ export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): T
 /**
  * Content part representing a user's response to a tool approval request.
  *
- * Used in tool messages to approve or deny tool execution when tools have
- * the `needsApproval` property set.
+ * **When to use**
+ *
+ * Use this part in tool messages to approve or deny tool execution when tools
+ * have the `needsApproval` property set.
  *
  * **Example** (Creating tool approval responses)
  *
@@ -879,9 +887,11 @@ export const toolApprovalResponsePart = (
 /**
  * Content part representing a tool approval request from the framework.
  *
- * Stored in assistant messages when a tool requires user approval before
- * execution. The user responds with a `ToolApprovalResponsePart` in a tool
- * message.
+ * **Details**
+ *
+ * Tool approval request parts are stored in assistant messages when a tool
+ * requires user approval before execution. The user responds with a
+ * `ToolApprovalResponsePart` in a tool message.
  *
  * **Example** (Creating tool approval requests)
  *
@@ -990,7 +1000,10 @@ export const isMessage = (u: unknown): u is Message => Predicate.hasProperty(u,
 /**
  * Base interface for all message types.
  *
- * Provides common structure including role and provider options.
+ * **Details**
+ *
+ * It provides the common structure shared by all messages, including the role
+ * and provider options.
  *
  * @category models
  * @since 4.0.0
@@ -1832,7 +1845,9 @@ const decodeMessagesSync = Schema.decodeSync(Schema.Array(Message))
 export const empty: Prompt = makePrompt([])
 
 /**
- * Creates a Prompt from an input.
+ * Creates a `Prompt` from an input.
+ *
+ * **Details**
  *
  * This is the primary constructor for creating prompts, supporting multiple
  * input formats for convenience and flexibility.
@@ -2059,8 +2074,10 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
 /**
  * Concatenates a prompt with additional raw input by concatenating messages.
  *
- * Creates a new prompt containing all messages from both the original prompt,
- * and the provided raw input, maintaining the order of messages.
+ * **Details**
+ *
+ * The returned prompt contains all messages from the original prompt followed
+ * by the provided raw input, preserving message order.
  *
  * **Example** (Concatenating prompts)
  *
@@ -2086,8 +2103,10 @@ export const concat: {
   /**
    * Concatenates a prompt with additional raw input by concatenating messages.
    *
-   * Creates a new prompt containing all messages from both the original prompt,
-   * and the provided raw input, maintaining the order of messages.
+   * **Details**
+   *
+   * The returned prompt contains all messages from the original prompt followed
+   * by the provided raw input, preserving message order.
    *
    * **Example** (Concatenating prompts)
    *
@@ -2113,8 +2132,10 @@ export const concat: {
   /**
    * Concatenates a prompt with additional raw input by concatenating messages.
    *
-   * Creates a new prompt containing all messages from both the original prompt,
-   * and the provided raw input, maintaining the order of messages.
+   * **Details**
+   *
+   * The returned prompt contains all messages from the original prompt followed
+   * by the provided raw input, preserving message order.
    *
    * **Example** (Concatenating prompts)
    *
@@ -2152,8 +2173,10 @@ export const concat: {
  * Creates a new prompt from the specified prompt with the system message set
  * to the specified text content.
  *
- * **NOTE**: This method will remove and replace any previous system message
- * from the prompt.
+ * **Gotchas**
+ *
+ * This method removes and replaces any previous system message from the
+ * prompt.
  *
  * **Example** (Replacing system instructions)
  *
@@ -2187,8 +2210,10 @@ export const setSystem: {
    * Creates a new prompt from the specified prompt with the system message set
    * to the specified text content.
    *
-   * **NOTE**: This method will remove and replace any previous system message
-   * from the prompt.
+   * **Gotchas**
+   *
+   * This method removes and replaces any previous system message from the
+   * prompt.
    *
    * **Example** (Replacing system instructions)
    *
@@ -2222,8 +2247,10 @@ export const setSystem: {
    * Creates a new prompt from the specified prompt with the system message set
    * to the specified text content.
    *
-   * **NOTE**: This method will remove and replace any previous system message
-   * from the prompt.
+   * **Gotchas**
+   *
+   * This method removes and replaces any previous system message from the
+   * prompt.
    *
    * **Example** (Replacing system instructions)
    *