effect 4.0.6 → 4.1.0

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.
    */
@@ -912,17 +918,36 @@ export type ResultEncoded<T> = SuccessEncoded<T> | FailureResultEncoded<T>
  * @category utility types
  * @since 4.0.0
  */
-export type HandlerServices<T> = T extends Tool<
+export type HandlerServices<T> = SchemaServices<T> | Requirements<T>
+
+/**
+ * A utility type to extract the request-level dependencies a `Tool` declares
+ * with `dependencies` or `Tool.addDependency`.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 4.0.0
+ */
+export type Requirements<T> = T extends Tool<
+  infer _Name,
+  infer _Config,
+  infer _Requirements
+> ? _Requirements
+  : never
+
+/**
+ * A utility type to extract the services needed to decode the parameters of a
+ * `Tool` call and encode its result, whether success or failure.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 4.0.0
+ */
+export type SchemaServices<T> = T extends Tool<
   infer _Name,
   infer _Config,
   infer _Requirements
-> ? // Parameters must be decoded when received from a model
-    | _Config["parameters"]["DecodingServices"]
-    // A tool call `result`, whether success or failure, is encoded and returned
-    // as the `encodedResult` along with the `result`
-    | ResultEncodingServices<T>
-    // Per-request requirements
-    | _Requirements
+> ? _Config["parameters"]["DecodingServices"] | ResultEncodingServices<T>
   : never
 
 /**
@@ -955,6 +980,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 +1055,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 +1160,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 +1201,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 +1264,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 +1364,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 +1390,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 +1499,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 +1524,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 +1542,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/ai/index.ts

@@ -83,6 +83,12 @@ export * as McpSchema from "./McpSchema.ts"
  */
 export * as McpServer from "./McpServer.ts"
 
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as McpTest from "./McpTest.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0

package/src/ai/internal/mcpCore.ts

@@ -149,6 +149,20 @@ export class UnsupportedByProtocol extends Data.TaggedError("UnsupportedByProtoc
   readonly feature: string
 }> {}
 
+/**
+ * A request rejected outside the handler, for example by MCP middleware.
+ * Adapters send it as a JSON-RPC error with its code, message and data, never
+ * as a tool result. `error` keeps the original failure for in-process callers.
+ *
+ * @internal
+ */
+export class RequestRejected extends Data.TaggedError("RequestRejected")<{
+  readonly code: number
+  readonly message: string
+  readonly data?: unknown
+  readonly error: McpSchema.McpErrorBase
+}> {}
+
 /**
  * @internal
  */
@@ -157,6 +171,7 @@ export type ToolError =
   | InvalidToolInput
   | InvalidToolContinuation
   | ToolExecutionError
+  | RequestRejected
 
 /**
  * @internal
@@ -166,12 +181,13 @@ export interface ToolRegistration {
   // `tool.title ?? tool.annotations?.title` at the public boundary.
   readonly descriptor: McpSchema.Tool
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly handle: (
     call: typeof McpSchema.CallTool.payloadSchema.Type,
     invocation: McpInvocation
   ) => Effect.Effect<
     OperationOutcome<McpSchema.CallToolResult>,
-    InvalidToolInput | InvalidToolContinuation | ToolExecutionError,
+    ToolNotFound | InvalidToolInput | InvalidToolContinuation | ToolExecutionError | RequestRejected,
     never
   >
 }
@@ -184,8 +200,13 @@ export interface Tools {
     registration: ToolRegistration
   ) => Effect.Effect<void>
   readonly list: (
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.Tool>, RequestRejected>
+  // Skips request-level visibility checks.
+  readonly find: (
+    name: string,
     profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.Tool>>
+  ) => McpSchema.Tool | undefined
   readonly call: (
     call: typeof McpSchema.CallTool.payloadSchema.Type,
     invocation: McpInvocation
@@ -198,9 +219,10 @@ export interface Tools {
 export interface ResourceRegistration {
   readonly descriptor: McpSchema.Resource
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly read: (
     invocation: McpInvocation
-  ) => Effect.Effect<McpSchema.ReadResourceResult, McpSchema.InternalError>
+  ) => Effect.Effect<McpSchema.ReadResourceResult, ResourceNotFound | McpSchema.InternalError | RequestRejected>
 }
 
 /**
@@ -209,12 +231,16 @@ export interface ResourceRegistration {
 export interface ResourceTemplateRegistration {
   readonly descriptor: McpSchema.ResourceTemplate
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly match: (uri: string) => ReadonlyArray<string> | undefined
   readonly read: (
     uri: string,
     params: ReadonlyArray<string>,
     invocation: McpInvocation
-  ) => Effect.Effect<McpSchema.ReadResourceResult, McpSchema.InvalidParams | McpSchema.InternalError>
+  ) => Effect.Effect<
+    McpSchema.ReadResourceResult,
+    ResourceNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
+  >
 }
 
 /**
@@ -224,17 +250,17 @@ export interface Resources {
   readonly register: (registration: ResourceRegistration) => Effect.Effect<void>
   readonly registerTemplate: (registration: ResourceTemplateRegistration) => Effect.Effect<void>
   readonly list: (
-    profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.Resource>>
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.Resource>, RequestRejected>
   readonly listTemplates: (
-    profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.ResourceTemplate>>
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.ResourceTemplate>, RequestRejected>
   readonly read: (
     uri: string,
     invocation: McpInvocation
   ) => Effect.Effect<
     McpSchema.ReadResourceResult,
-    ResourceNotFound | McpSchema.InvalidParams | McpSchema.InternalError
+    ResourceNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
   >
 }
 
@@ -251,10 +277,14 @@ export class PromptNotFound extends Data.TaggedError("PromptNotFound")<{
 export interface PromptRegistration {
   readonly descriptor: McpSchema.Prompt
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly get: (
     args: Readonly<Record<string, string>>,
     invocation: McpInvocation
-  ) => Effect.Effect<OperationOutcome<McpSchema.GetPromptResult>, McpSchema.InvalidParams | McpSchema.InternalError>
+  ) => Effect.Effect<
+    OperationOutcome<McpSchema.GetPromptResult>,
+    PromptNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
+  >
 }
 
 /**
@@ -263,15 +293,15 @@ export interface PromptRegistration {
 export interface Prompts {
   readonly register: (registration: PromptRegistration) => Effect.Effect<void>
   readonly list: (
-    profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.Prompt>>
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.Prompt>, RequestRejected>
   readonly get: (
     name: string,
     args: Readonly<Record<string, string>>,
     invocation: McpInvocation
   ) => Effect.Effect<
     OperationOutcome<McpSchema.GetPromptResult>,
-    PromptNotFound | McpSchema.InvalidParams | McpSchema.InternalError
+    PromptNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
   >
 }
 
@@ -314,12 +344,12 @@ export interface Completions {
     complete: (
       request: CompletionRequest,
       invocation: McpInvocation
-    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError>
+    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected>
   ) => Effect.Effect<void>
   readonly complete: (
     request: CompletionRequest,
     invocation: McpInvocation
-  ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError>
+  ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected>
 }
 
 /**
@@ -400,6 +430,14 @@ export interface McpCore {
   }>
 }
 
+/**
+ * Runs the request-level visibility checks of a registration on a list
+ * request, after `isVisible` passed.
+ *
+ * @internal
+ */
+export type Visible = (invocation: McpInvocation) => Effect.Effect<boolean, RequestRejected>
+
 /**
  * @internal
  */
@@ -413,24 +451,35 @@ export const make: Effect.Effect<McpCore> = Effect.sync(() => {
     (
       request: CompletionRequest,
       invocation: McpInvocation
-    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError>
+    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected>
   >()
 
+  const filterList = <D>(
+    registrations: Iterable<{
+      readonly descriptor: D
+      readonly isVisible: ToolRegistration["isVisible"]
+      readonly visible?: Visible | undefined
+    }>,
+    invocation: McpInvocation
+  ): Effect.Effect<ReadonlyArray<D>, RequestRejected> =>
+    Effect.map(
+      Effect.filter(
+        Arr.filter(registrations, (entry) => entry.isVisible(invocation.protocol)),
+        (entry) => entry.visible === undefined ? Effect.succeed(true) : entry.visible(invocation)
+      ),
+      (entries) => entries.map((entry) => entry.descriptor)
+    )
+
   const tools: Tools = {
     register: (registration) =>
       Effect.sync(() => {
         registrations.set(registration.descriptor.name, registration)
       }),
-    list: (profile) =>
-      Effect.sync(() => {
-        const descriptors: Array<McpSchema.Tool> = []
-        for (const registration of registrations.values()) {
-          if (registration.isVisible(profile)) {
-            descriptors.push(registration.descriptor)
-          }
-        }
-        return descriptors
-      }),
+    list: (invocation) => filterList(registrations.values(), invocation),
+    find: (name, profile) => {
+      const registration = registrations.get(name)
+      return registration !== undefined && registration.isVisible(profile) ? registration.descriptor : undefined
+    },
     call: (call, invocation) =>
       Effect.suspend((): Effect.Effect<OperationOutcome<McpSchema.CallToolResult>, ToolError> => {
         const registration = registrations.get(call.name)
@@ -465,18 +514,8 @@ export const make: Effect.Effect<McpCore> = Effect.sync(() => {
           resourceTemplateRegistrations[index] = registration
         }
       }),
-    list: (profile) =>
-      Effect.sync(() =>
-        resourceRegistrations
-          .filter((entry) => entry.isVisible(profile))
-          .map((entry) => entry.descriptor)
-      ),
-    listTemplates: (profile) =>
-      Effect.sync(() =>
-        resourceTemplateRegistrations
-          .filter((entry) => entry.isVisible(profile))
-          .map((entry) => entry.descriptor)
-      ),
+    list: (invocation) => filterList(resourceRegistrations, invocation),
+    listTemplates: (invocation) => filterList(resourceTemplateRegistrations, invocation),
     read: Effect.fnUntraced(function*(uri, invocation) {
       const resource = resourceRegistrations.find((entry) => entry.descriptor.uri === uri)
       if (resource !== undefined && resource.isVisible(invocation.protocol)) {
@@ -497,12 +536,7 @@ export const make: Effect.Effect<McpCore> = Effect.sync(() => {
       Effect.sync(() => {
         promptRegistrations.set(registration.descriptor.name, registration)
       }),
-    list: (profile) =>
-      Effect.sync(() =>
-        Array.from(promptRegistrations.values())
-          .filter((entry) => entry.isVisible(profile))
-          .map((entry) => entry.descriptor)
-      ),
+    list: (invocation) => filterList(promptRegistrations.values(), invocation),
     get: Effect.fnUntraced(function*(name, args, invocation) {
       const registration = promptRegistrations.get(name)
       if (registration === undefined || !registration.isVisible(invocation.protocol)) {

package/src/ai/internal/mcpProtocol/v2024_11_05.ts

@@ -154,12 +154,10 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(Effect.map((resources) => McpSchema.ListResourcesResult.make({ resources }))),
       "resources/templates/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) => McpSchema.ListResourceTemplatesResult.make({ resourceTemplates }))
         ),
       "resources/read": Effect.fnUntraced(function*({ uri }) {
@@ -189,7 +187,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) =>
               McpSchema.ListPromptsResult.make({
@@ -249,8 +247,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        return yield* core.tools.list(McpProtocol.profileFromClient(request)).pipe(
+        return yield* McpProtocol.listForClient(core.tools.list).pipe(
           Effect.map((tools) =>
             McpSchema.ListToolsResult.make({
               tools: tools.map((tool) =>

package/src/ai/internal/mcpProtocol/v2025_03_26.ts

@@ -166,7 +166,7 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(
             Effect.map((resources) =>
               McpSchema.ListResourcesResult.make({
@@ -182,9 +182,7 @@ export const protocol = McpProtocol.make({
             )
           ),
       "resources/templates/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) =>
             McpSchema.ListResourceTemplatesResult.make({
               resourceTemplates: resourceTemplates.map((template) => ({
@@ -212,7 +210,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) =>
               McpSchema.ListPromptsResult.make({
@@ -272,8 +270,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        const tools = yield* core.tools.list(McpProtocol.profileFromClient(request))
+        const tools = yield* McpProtocol.listForClient(core.tools.list)
         return McpSchema.ListToolsResult.make({
           tools: tools.map((tool) =>
             McpSchema.Tool.make({

package/src/ai/internal/mcpProtocol/v2025_06_18.ts

@@ -182,14 +182,12 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(
             Effect.map((resources) => McpSchema.ListResourcesResult.make({ resources }))
           ),
       "resources/templates/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) => McpSchema.ListResourceTemplatesResult.make({ resourceTemplates }))
         ),
       "resources/read": Effect.fnUntraced(function*({ uri }) {
@@ -207,7 +205,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) => McpSchema.ListPromptsResult.make({ prompts }))
           ),
@@ -262,8 +260,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        const tools = yield* core.tools.list(McpProtocol.profileFromClient(request))
+        const tools = yield* McpProtocol.listForClient(core.tools.list)
         return McpSchema.ListToolsResult.make({
           tools: tools.map((tool) =>
             McpSchema.Tool.make({

package/src/ai/internal/mcpProtocol/v2025_11_25.ts

@@ -177,7 +177,7 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(
             Effect.map((resources) =>
               McpSchema.ListResourcesResult.make({
@@ -186,9 +186,7 @@ export const protocol = McpProtocol.make({
             )
           ),
       "resources/templates/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) =>
             McpSchema.ListResourceTemplatesResult.make({
               resourceTemplates: resourceTemplates.map((resourceTemplate) =>
@@ -226,7 +224,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) =>
               McpSchema.ListPromptsResult.make({
@@ -285,8 +283,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        const tools = yield* core.tools.list(McpProtocol.profileFromClient(request))
+        const tools = yield* McpProtocol.listForClient(core.tools.list)
         return McpSchema.ListToolsResult.make({
           tools: tools.map((tool) =>
             McpSchema.Tool.make({

package/src/ai/internal/mcpProtocol/v2026_07_28.ts

@@ -327,6 +327,11 @@ export const makeHandlers = (
     context.serverInfo.extensions,
     (value): value is Readonly<Record<string, unknown>> => Predicate.isReadonlyObject(value)
   )
+  // Project only the wire fields; structurally compatible hints can carry extra properties.
+  const cacheHint = (family: keyof McpProtocol.CacheHints) => {
+    const hint = context.serverInfo.cacheHints?.[family]
+    return hint === undefined ? privateStaleCache : { ttlMs: hint.ttlMs, cacheScope: hint.cacheScope }
+  }
   const getDiscovery = Effect.map(context.registrationPresence, (presence) => {
     const capabilities: Types.Mutable<typeof McpSchema.ServerCapabilities.Type> = { completions: {}, logging: {} }
     if (extensions !== undefined) capabilities.extensions = extensions
@@ -483,7 +488,7 @@ export const makeHandlers = (
     ) {
       const discovery = yield* getDiscovery
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("discover"),
         supportedVersions: Array.from(discovery.supportedVersions),
         capabilities: discovery.capabilities,
         instructions: context.serverInfo.instructions
@@ -494,9 +499,9 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListResources.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const resources = yield* core.resources.list(invocation.protocol)
+      const resources = yield* core.resources.list(invocation)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("resources"),
         resources: resources.map(projectResource)
       }, context.serverInfo)
       return yield* decodeListResourcesResult(result)
@@ -505,9 +510,9 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListResourceTemplates.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const resourceTemplates = yield* core.resources.listTemplates(invocation.protocol)
+      const resourceTemplates = yield* core.resources.listTemplates(invocation)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("resourceTemplates"),
         resourceTemplates: resourceTemplates.map(projectResourceTemplate)
       }, context.serverInfo)
       return yield* decodeListResourceTemplatesResult(result)
@@ -537,10 +542,10 @@ export const makeHandlers = (
         )
       }
       const invocation = yield* getInvocation
-      const prompts = yield* core.prompts.list(invocation.protocol)
+      const prompts = yield* core.prompts.list(invocation)
       const projectedPrompts = yield* Effect.forEach(prompts, projectPrompt)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("prompts"),
         prompts: projectedPrompts
       }, context.serverInfo)
       return yield* decodeListPromptsResult(result)
@@ -593,17 +598,17 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListTools.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const tools = yield* core.tools.list(invocation.protocol)
+      const tools = yield* core.tools.list(invocation)
       const projectedTools = yield* Effect.forEach(tools, projectTool)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("tools"),
         tools: projectedTools
       }, context.serverInfo)
       return yield* decodeListToolsResult(result)
     }, Effect.mapError(projectError)),
     "tools/call": Effect.fnUntraced(function*(request: typeof McpSchema.CallTool.payloadSchema.Type) {
       const invocation = yield* getInputInvocation(request)
-      const tool = (yield* core.tools.list(invocation.protocol)).find((tool) => tool.name === request.name)
+      const tool = core.tools.find(request.name, invocation.protocol)
       const httpRequest = yield* Effect.serviceOption(HttpServerRequest.HttpServerRequest)
 
       if (tool !== undefined && Option.isSome(httpRequest)) {