effect 4.0.0-beta.102 → 4.0.0-beta.104

package/src/unstable/ai/McpSchema.ts

@@ -23,6 +23,7 @@ import type * as RpcClient from "../rpc/RpcClient.ts"
 import type { RpcClientError } from "../rpc/RpcClientError.ts"
 import * as RpcGroup from "../rpc/RpcGroup.ts"
 import * as RpcMiddleware from "../rpc/RpcMiddleware.ts"
+import type * as McpProtocol from "./McpProtocol.ts"
 
 /**
  * Schema type returned by `optionalWithDefault`.
@@ -539,7 +540,7 @@ export const PARSE_ERROR_CODE = -32700 as const
  * @category errors
  * @since 4.0.0
  */
-export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSchema/ParseError")({
+export class ParseError extends Schema.Error<ParseError>("effect/ai/McpSchema/ParseError")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("ParseError"),
   code: Schema.tag(PARSE_ERROR_CODE)
@@ -560,7 +561,7 @@ export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSche
  * @category errors
  * @since 4.0.0
  */
-export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai/McpSchema/InvalidRequest")({
+export class InvalidRequest extends Schema.Error<InvalidRequest>("effect/ai/McpSchema/InvalidRequest")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidRequest"),
   code: Schema.tag(INVALID_REQUEST_ERROR_CODE)
@@ -580,7 +581,7 @@ export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai
  * @category errors
  * @since 4.0.0
  */
-export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai/McpSchema/MethodNotFound")({
+export class MethodNotFound extends Schema.Error<MethodNotFound>("effect/ai/McpSchema/MethodNotFound")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("MethodNotFound"),
   code: Schema.tag(METHOD_NOT_FOUND_ERROR_CODE)
@@ -601,7 +602,7 @@ export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai
  * @category errors
  * @since 4.0.0
  */
-export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/McpSchema/InvalidParams")({
+export class InvalidParams extends Schema.Error<InvalidParams>("effect/ai/McpSchema/InvalidParams")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidParams"),
   code: Schema.tag(INVALID_PARAMS_ERROR_CODE)
@@ -623,7 +624,7 @@ export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/M
  * @category errors
  * @since 4.0.0
  */
-export class InternalError extends Schema.ErrorClass<InternalError>("effect/ai/McpSchema/InternalError")({
+export class InternalError extends Schema.Error<InternalError>("effect/ai/McpSchema/InternalError")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("InternalError"),
   code: Schema.tag(INTERNAL_ERROR_CODE)
@@ -662,7 +663,7 @@ export const McpError = Schema.Union([
  *
  * The receiver should respond promptly; otherwise the sender may disconnect.
  *
- * @category ping
+ * @category protocols
  * @since 4.0.0
  */
 export class Ping extends Rpc.make("ping", {
@@ -678,7 +679,7 @@ export class Ping extends Rpc.make("ping", {
 /**
  * Schema for the server's response to an initialize request from the client.
  *
- * @category initialization
+ * @category schemas
  * @since 4.0.0
  */
 export class InitializeResult extends Schema.Opaque<InitializeResult>()(Schema.Struct({
@@ -705,7 +706,7 @@ export class InitializeResult extends Schema.Opaque<InitializeResult>()(Schema.S
  * Sent from the client to the server when it first connects, asking it to begin
  * initialization.
  *
- * @category initialization
+ * @category protocols
  * @since 4.0.0
  */
 export class Initialize extends Rpc.make("initialize", {
@@ -734,7 +735,7 @@ export class Initialize extends Rpc.make("initialize", {
 /**
  * Sent from the client to the server after initialization has finished.
  *
- * @category initialization
+ * @category protocols
  * @since 4.0.0
  */
 export class InitializedNotification extends Rpc.make("notifications/initialized", {
@@ -754,7 +755,7 @@ export class InitializedNotification extends Rpc.make("notifications/initialized
  * The payload identifies the request to cancel and may include a
  * human-readable reason.
  *
- * @category cancellation
+ * @category protocols
  * @since 4.0.0
  */
 export class CancelledNotification extends Rpc.make("notifications/cancelled", {
@@ -782,7 +783,7 @@ export class CancelledNotification extends Rpc.make("notifications/cancelled", {
 /**
  * Sent from either peer to report progress for a long-running request.
  *
- * @category progress
+ * @category protocols
  * @since 4.0.0
  */
 export class ProgressNotification extends Rpc.make("notifications/progress", {
@@ -816,7 +817,7 @@ export class ProgressNotification extends Rpc.make("notifications/progress", {
 /**
  * Schema for a known resource that the server is capable of reading.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class Resource extends Schema.Class<Resource>(
@@ -868,7 +869,7 @@ export class Resource extends Schema.Class<Resource>(
 /**
  * Schema for a template description of resources available on the server.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class ResourceTemplate extends Schema.Class<ResourceTemplate>(
@@ -914,7 +915,7 @@ export class ResourceTemplate extends Schema.Class<ResourceTemplate>(
 /**
  * Schema for the contents of a specific resource or sub-resource.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class ResourceContents extends Schema.Opaque<ResourceContents>()(Schema.Struct({
@@ -935,7 +936,7 @@ export class ResourceContents extends Schema.Opaque<ResourceContents>()(Schema.S
 /**
  * Schema for text resource contents represented as a string.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class TextResourceContents extends Schema.Opaque<TextResourceContents>()(Schema.Struct({
@@ -950,7 +951,7 @@ export class TextResourceContents extends Schema.Opaque<TextResourceContents>()(
 /**
  * Schema for binary resource contents represented as a `Uint8Array`.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class BlobResourceContents extends Schema.Opaque<BlobResourceContents>()(Schema.Struct({
@@ -964,7 +965,7 @@ export class BlobResourceContents extends Schema.Opaque<BlobResourceContents>()(
 /**
  * Schema for the server's response to a resources/list request from the client.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class ListResourcesResult extends Schema.Class<ListResourcesResult>(
@@ -977,7 +978,7 @@ export class ListResourcesResult extends Schema.Class<ListResourcesResult>(
 /**
  * Sent from the client to request a list of resources the server has.
  *
- * @category resources
+ * @category protocols
  * @since 4.0.0
  */
 export class ListResources extends Rpc.make("resources/list", {
@@ -990,7 +991,7 @@ export class ListResources extends Rpc.make("resources/list", {
  * Schema for the server's response to a resources/templates/list request from
  * the client.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class ListResourceTemplatesResult extends Schema.Class<ListResourceTemplatesResult>(
@@ -1003,7 +1004,7 @@ export class ListResourceTemplatesResult extends Schema.Class<ListResourceTempla
 /**
  * Sent from the client to request a list of resource templates the server has.
  *
- * @category resources
+ * @category protocols
  * @since 4.0.0
  */
 export class ListResourceTemplates extends Rpc.make("resources/templates/list", {
@@ -1015,7 +1016,7 @@ export class ListResourceTemplates extends Rpc.make("resources/templates/list",
 /**
  * Schema for the server's response to a resources/read request from the client.
  *
- * @category resources
+ * @category schemas
  * @since 4.0.0
  */
 export class ReadResourceResult extends Schema.Opaque<ReadResourceResult>()(Schema.Struct({
@@ -1026,7 +1027,7 @@ export class ReadResourceResult extends Schema.Opaque<ReadResourceResult>()(Sche
 /**
  * Sent from the client to the server, to read a specific resource URI.
  *
- * @category resources
+ * @category protocols
  * @since 4.0.0
  */
 export class ReadResource extends Rpc.make("resources/read", {
@@ -1053,7 +1054,7 @@ export class ReadResource extends Rpc.make("resources/read", {
  *
  * Servers may send this notification without a previous client subscription.
  *
- * @category resources
+ * @category protocols
  * @since 4.0.0
  */
 export class ResourceListChangedNotification extends Rpc.make("notifications/resources/list_changed", {
@@ -1064,10 +1065,11 @@ export class ResourceListChangedNotification extends Rpc.make("notifications/res
  * Sent from the client to request resources/updated notifications from the
  * server whenever a particular resource changes.
  *
- * @category resources
+ * @category protocols
  * @since 4.0.0
  */
 export class Subscribe extends Rpc.make("resources/subscribe", {
+  success: Schema.Struct({}),
   error: McpError,
   payload: {
     ...RequestMeta.fields,
@@ -1084,10 +1086,11 @@ export class Subscribe extends Rpc.make("resources/subscribe", {
  * notifications from the server. This should follow a previous
  * resources/subscribe request.
  *
- * @category resources
+ * @category protocols
  * @since 4.0.0
  */
 export class Unsubscribe extends Rpc.make("resources/unsubscribe", {
+  success: Schema.Struct({}),
   error: McpError,
   payload: {
     ...RequestMeta.fields,
@@ -1107,7 +1110,7 @@ export class Unsubscribe extends Rpc.make("resources/unsubscribe", {
  * The URI may identify a sub-resource of the resource that the client
  * originally subscribed to.
  *
- * @category resources
+ * @category protocols
  * @since 4.0.0
  */
 export class ResourceUpdatedNotification extends Rpc.make("notifications/resources/updated", {
@@ -1403,7 +1406,7 @@ export class PromptListChangedNotification extends Rpc.make("notifications/promp
  * Clients should never make tool use decisions based on ToolAnnotations
  * received from untrusted servers.
  *
- * @category tools
+ * @category schemas
  * @since 4.0.0
  */
 export class ToolAnnotations extends Schema.Opaque<ToolAnnotations>()(Schema.Struct({
@@ -1449,7 +1452,7 @@ export class ToolAnnotations extends Schema.Opaque<ToolAnnotations>()(Schema.Str
 /**
  * Schema for the definition of a tool the client can call.
  *
- * @category tools
+ * @category schemas
  * @since 4.0.0
  */
 export class Tool extends Schema.Class<Tool>(
@@ -1470,6 +1473,10 @@ export class Tool extends Schema.Class<Tool>(
    * A JSON Schema object defining the expected parameters for the tool.
    */
   inputSchema: Schema.Any,
+  /**
+   * An optional JSON Schema object defining the expected output of the tool.
+   */
+  outputSchema: optional(Schema.Any),
   /**
    * Optional additional tool information.
    */
@@ -1486,7 +1493,7 @@ export class Tool extends Schema.Class<Tool>(
 /**
  * Schema for the server's response to a tools/list request from the client.
  *
- * @category tools
+ * @category schemas
  * @since 4.0.0
  */
 export class ListToolsResult extends Schema.Class<ListToolsResult>(
@@ -1499,7 +1506,7 @@ export class ListToolsResult extends Schema.Class<ListToolsResult>(
 /**
  * Sent from the client to request a list of tools the server has.
  *
- * @category tools
+ * @category protocols
  * @since 4.0.0
  */
 export class ListTools extends Rpc.make("tools/list", {
@@ -1520,7 +1527,7 @@ export class ListTools extends Rpc.make("tools/list", {
  * indicating that the server does not support tool calls, or any other
  * exceptional conditions, should be reported as an MCP error response.
  *
- * @category tools
+ * @category schemas
  * @since 4.0.0
  */
 export class CallToolResult extends Schema.Class<CallToolResult>("@effect/ai/McpSchema/CallToolResult")({
@@ -1546,7 +1553,7 @@ export class CallToolResult extends Schema.Class<CallToolResult>("@effect/ai/Mcp
  * @see {@link ListTools} for discovering available tools before calling one
  * @see {@link CallToolResult} for the successful tool-call result shape
  *
- * @category tools
+ * @category protocols
  * @since 4.0.0
  */
 export class CallTool extends Rpc.make("tools/call", {
@@ -1555,9 +1562,12 @@ export class CallTool extends Rpc.make("tools/call", {
   payload: {
     ...RequestMeta.fields,
     name: Schema.String,
-    arguments: Schema.Record(
-      Schema.String,
-      Schema.Any
+    arguments: optionalWithDefault(
+      Schema.Record(
+        Schema.String,
+        Schema.Any
+      ),
+      () => ({})
     )
   }
 }) {}
@@ -1573,7 +1583,7 @@ export class CallTool extends Rpc.make("tools/call", {
  *
  * Servers may send this notification without a previous client subscription.
  *
- * @category tools
+ * @category protocols
  * @since 4.0.0
  */
 export class ToolListChangedNotification extends Rpc.make("notifications/tools/list_changed", {
@@ -1638,6 +1648,7 @@ export class SetLevel extends Rpc.make("logging/setLevel", {
      */
     level: LoggingLevel
   },
+  success: Schema.Struct({}),
   error: McpError
 }) {}
 
@@ -1678,7 +1689,7 @@ export class LoggingMessageNotification extends Rpc.make("notifications/message"
 /**
  * Describes a message issued to or received from an LLM API.
  *
- * @category sampling
+ * @category schemas
  * @since 4.0.0
  */
 export class SamplingMessage extends Schema.Opaque<SamplingMessage>()(Schema.Struct({
@@ -1694,7 +1705,7 @@ export class SamplingMessage extends Schema.Opaque<SamplingMessage>()(Schema.Str
  * Keys not declared here are currently left unspecified by the spec and are up
  * to the client to interpret.
  *
- * @category sampling
+ * @category schemas
  * @since 4.0.0
  */
 export class ModelHint extends Schema.Opaque<ModelHint>()(Schema.Struct({
@@ -1731,7 +1742,7 @@ export class ModelHint extends Schema.Opaque<ModelHint>()(Schema.Struct({
  * up to the client to decide how to interpret these preferences and how to
  * balance them against other considerations.
  *
- * @category sampling
+ * @category schemas
  * @since 4.0.0
  */
 export class ModelPreferences extends Schema.Class<ModelPreferences>(
@@ -1779,12 +1790,13 @@ export class ModelPreferences extends Schema.Class<ModelPreferences>(
  * The client should let the user inspect the sampled message before returning
  * it to the server.
  *
- * @category sampling
+ * @category schemas
  * @since 4.0.0
  */
 export class CreateMessageResult extends Schema.Class<CreateMessageResult>(
   "@effect/ai/McpSchema/CreateMessageResult"
 )({
+  ...SamplingMessage.fields,
   /**
    * The name of the model that generated the message.
    */
@@ -1808,7 +1820,7 @@ export class CreateMessageResult extends Schema.Class<CreateMessageResult>(
  * The client chooses the model and should ask the user to approve the sampling
  * request before it begins.
  *
- * @category sampling
+ * @category protocols
  * @since 4.0.0
  */
 export class CreateMessage extends Rpc.make("sampling/createMessage", {
@@ -1820,7 +1832,7 @@ export class CreateMessage extends Rpc.make("sampling/createMessage", {
      * The server's preferences for which model to select. The client MAY ignore
      * these preferences.
      */
-    modelPreferences: optional(ModelPreferences),
+    modelPreferences: optional(Schema.Struct(ModelPreferences.fields)),
     /**
      * An optional system prompt the server wants to use for sampling. The
      * client MAY modify or omit this prompt.
@@ -1842,7 +1854,7 @@ export class CreateMessage extends Rpc.make("sampling/createMessage", {
      * Optional metadata to pass through to the LLM provider. The format of
      * this metadata is provider-specific.
      */
-    metadata: Schema.Any
+    metadata: optional(Schema.Record(Schema.String, Schema.Unknown))
   }
 }) {}
 
@@ -1853,7 +1865,7 @@ export class CreateMessage extends Rpc.make("sampling/createMessage", {
 /**
  * Schema for a reference to a resource or resource template definition.
  *
- * @category autocomplete
+ * @category schemas
  * @since 4.0.0
  */
 export class ResourceReference extends Schema.Opaque<ResourceReference>()(Schema.Struct({
@@ -1867,7 +1879,7 @@ export class ResourceReference extends Schema.Opaque<ResourceReference>()(Schema
 /**
  * Schema for a prompt reference used in autocomplete requests.
  *
- * @category autocomplete
+ * @category schemas
  * @since 4.0.0
  */
 export class PromptReference extends Schema.Opaque<PromptReference>()(Schema.Struct({
@@ -1882,7 +1894,7 @@ export class PromptReference extends Schema.Opaque<PromptReference>()(Schema.Str
 /**
  * Schema for the server's response to a completion/complete request.
  *
- * @category autocomplete
+ * @category schemas
  * @since 4.0.0
  */
 export class CompleteResult extends Schema.Opaque<CompleteResult>()(Schema.Struct({
@@ -1920,7 +1932,7 @@ export class CompleteResult extends Schema.Opaque<CompleteResult>()(Schema.Struc
 /**
  * Sent from the client to the server to ask for completion options.
  *
- * @category autocomplete
+ * @category protocols
  * @since 4.0.0
  */
 export class Complete extends Rpc.make("completion/complete", {
@@ -1966,7 +1978,7 @@ export class Complete extends Rpc.make("completion/complete", {
 /**
  * Represents a root directory or file that the server can operate on.
  *
- * @category roots
+ * @category schemas
  * @since 4.0.0
  */
 export class Root extends Schema.Class<Root>(
@@ -1993,7 +2005,7 @@ export class Root extends Schema.Class<Root>(
  *
  * Use to return the directories or files that an MCP server may operate on.
  *
- * @category roots
+ * @category schemas
  * @since 4.0.0
  */
 export class ListRootsResult extends Schema.Class<ListRootsResult>(
@@ -2014,7 +2026,7 @@ export class ListRootsResult extends Schema.Class<ListRootsResult>(
  * system structure or access specific locations that the client has permission
  * to read from.
  *
- * @category roots
+ * @category protocols
  * @since 4.0.0
  */
 export class ListRoots extends Rpc.make("roots/list", {
@@ -2034,7 +2046,7 @@ export class ListRoots extends Rpc.make("roots/list", {
  *
  * Send this when the client adds, removes, or modifies a root.
  *
- * @category roots
+ * @category protocols
  * @since 4.0.0
  */
 export class RootsListChangedNotification extends Rpc.make("notifications/roots/list_changed", {
@@ -2048,7 +2060,7 @@ export class RootsListChangedNotification extends Rpc.make("notifications/roots/
 /**
  * Schema for an accepted client response to an elicitation request.
  *
- * @category elicitation
+ * @category schemas
  * @since 4.0.0
  */
 export class ElicitAcceptResult extends Schema.Class<ElicitAcceptResult>(
@@ -2072,7 +2084,7 @@ export class ElicitAcceptResult extends Schema.Class<ElicitAcceptResult>(
 /**
  * Schema for a declined or canceled client response to an elicitation request.
  *
- * @category elicitation
+ * @category schemas
  * @since 4.0.0
  */
 export class ElicitDeclineResult extends Schema.Class<ElicitDeclineResult>(
@@ -2091,7 +2103,7 @@ export class ElicitDeclineResult extends Schema.Class<ElicitDeclineResult>(
 /**
  * Schema for every client response to an elicitation request.
  *
- * @category elicitation
+ * @category schemas
  * @since 4.0.0
  */
 export const ElicitResult = Schema.Union([
@@ -2108,7 +2120,7 @@ export const ElicitResult = Schema.Union([
  * The client responds with accepted content, an explicit decline, or a
  * cancellation.
  *
- * @category elicitation
+ * @category protocols
  * @since 4.0.0
  */
 export class Elicit extends Rpc.make("elicitation/create", {
@@ -2137,16 +2149,14 @@ export class Elicit extends Rpc.make("elicitation/create", {
  * The error stores the original elicitation request and, when available, the
  * underlying cause.
  *
- * @category elicitation
+ * @category schemas
  * @since 4.0.0
  */
-export class ElicitationDeclined
-  extends Schema.ErrorClass<ElicitationDeclined>("@effect/ai/McpSchema/ElicitationDeclined")({
-    _tag: Schema.tag("ElicitationDeclined"),
-    request: Elicit.payloadSchema,
-    cause: optional(Schema.Defect())
-  })
-{}
+export class ElicitationDeclined extends Schema.Error<ElicitationDeclined>("@effect/ai/McpSchema/ElicitationDeclined")({
+  _tag: Schema.tag("ElicitationDeclined"),
+  request: Elicit.payloadSchema,
+  cause: optional(Schema.Defect())
+}) {}
 
 // =============================================================================
 // McpServerClient
@@ -2160,11 +2170,12 @@ export class ElicitationDeclined
  * It exposes the current client id, the client's initialize payload, and a
  * scoped RPC client for server-initiated requests back to that client.
  *
- * @category client
+ * @category services
  * @since 4.0.0
  */
 export class McpServerClient extends Context.Service<McpServerClient, {
   readonly clientId: number
+  readonly protocolVersion: McpProtocol.ProtocolVersion
   readonly initializePayload: typeof Initialize.payloadSchema["Type"]
   readonly getClient: Effect.Effect<
     RpcClient.RpcClient<RpcGroup.Rpcs<typeof ServerRequestRpcs>, RpcClientError>,
@@ -2459,7 +2470,7 @@ const ParamSchemaTypeId = "~effect/ai/McpSchema/ParamSchema"
  * Returns `true` when a schema was created with `param` and therefore carries
  * a resource URI template parameter name.
  *
- * @category parameters
+ * @category guards
  * @since 4.0.0
  */
 export function isParam(schema: Schema.Constraint): schema is Param<string, Schema.Top> {
@@ -2519,7 +2530,7 @@ export function param<const Name extends string, S extends Schema.Constraint>(
  * Annotation to conditionally enable or disable tools based on client
  * information.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class EnabledWhen