effect 4.0.6 → 4.1.0

package/src/ai/internal/mcpProtocol.ts

@@ -16,6 +16,7 @@ import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
 import type * as PublicMcpProtocol from "../McpProtocol.ts"
 import * as PublicMcpSchema from "../McpSchema.ts"
+import type * as PublicMcpServer from "../McpServer.ts"
 import * as McpCore from "./mcpCore.ts"
 
 const LEGACY_RESOURCE_NOT_FOUND_ERROR_CODE = -32002
@@ -95,6 +96,18 @@ export const invocationFromClient = (
   serverClient: request
 })
 
+/**
+ * Runs a core list operation for the legacy client of the current request.
+ *
+ * @internal
+ */
+export const listForClient = <A>(
+  list: (invocation: McpCore.McpInvocation) => Effect.Effect<A, McpCore.RequestRejected>
+): Effect.Effect<A, ProtocolError, PublicMcpSchema.McpServerClient> =>
+  PublicMcpSchema.McpServerClient.use((request) =>
+    list(invocationFromClient(request)).pipe(Effect.mapError(ProtocolError.fromFeature))
+  )
+
 /**
  * @internal
  */
@@ -212,6 +225,9 @@ export class ProtocolError extends Data.TaggedError("ProtocolError")<{
   static fromTool(
     error: McpCore.ToolError | McpCore.UnsupportedByProtocol
   ): ProtocolError {
+    if (error._tag === "RequestRejected") {
+      return new ProtocolError({ code: error.code, message: error.message, data: error.data })
+    }
     const message = Match.value(error).pipe(
       Match.tag("ToolNotFound", (error) => `Tool '${error.name}' not found`),
       Match.tag(
@@ -428,6 +444,7 @@ export interface HandlerInstallationContext {
     readonly websiteUrl?: string | undefined
     readonly icons?: ReadonlyArray<PublicMcpSchema.Icon> | undefined
     readonly extensions?: PublicMcpSchema.ServerCapabilities["extensions"] | undefined
+    readonly cacheHints?: CacheHints | undefined
   }
   readonly registrationPresence: Effect.Effect<{
     readonly tools: boolean
@@ -436,6 +453,18 @@ export interface HandlerInstallationContext {
   }>
 }
 
+/**
+ * Cache hints normalized to wire values when the server is constructed.
+ *
+ * @internal
+ */
+export type CacheHints = {
+  readonly [Family in keyof PublicMcpServer.CacheHints]?: {
+    readonly ttlMs: number
+    readonly cacheScope: "private"
+  }
+}
+
 /**
  * @internal
  */

package/src/ai/internal/mcpRuntime.ts

@@ -6,6 +6,7 @@
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Cause from "../../Cause.ts"
 import * as Context from "../../Context.ts"
+import * as SecureRandom from "../../crypto/SecureRandom.ts"
 import * as Effect from "../../Effect.ts"
 import type * as Headers from "../../http/Headers.ts"
 import { appendPreResponseHandlerUnsafe } from "../../http/HttpEffect.ts"
@@ -138,6 +139,7 @@ export interface HandlerInstallationOptions {
     readonly websiteUrl?: string | undefined
     readonly icons?: ReadonlyArray<PublicMcpSchema.Icon> | undefined
     readonly extensions?: NonNullable<PublicMcpSchema.ServerCapabilities["extensions"]> | undefined
+    readonly cacheHints?: McpProtocol.CacheHints | undefined
   }
 }
 
@@ -185,7 +187,8 @@ export interface ServerRuntimeShape {
     clientId: number,
     headers: Headers.Headers,
     notification: McpCore.ServerNotification,
-    fallbackLogLevel: LogLevel.LogLevel
+    fallbackLogLevel: LogLevel.LogLevel,
+    listChangeRevision: number | undefined
   ) => boolean
   readonly installHandlers: (
     options: HandlerInstallationOptions
@@ -506,8 +509,8 @@ export const make = Effect.fnUntraced(function*(
           })
       ),
     deliveryClientIds: () => stateful?.initializedClientIds() ?? [],
-    canDeliver: (clientId, headers, notification, fallback) =>
-      stateful?.canDeliver(clientId, headers, notification, fallback) ?? true,
+    canDeliver: (clientId, headers, notification, fallback, listChangeRevision) =>
+      stateful?.canDeliver(clientId, headers, notification, fallback, listChangeRevision) ?? true,
     installHandlers: Effect.fnUntraced(function*(options) {
       const contextMap = new Map<string, unknown>()
       const installationContext: McpProtocol.HandlerInstallationContext = {
@@ -561,10 +564,11 @@ export const make = Effect.fnUntraced(function*(
                 protocol: protocol as PublicMcpProtocol.ProtocolAdapter,
                 supportsResourceSubscriptions: httpRequest === undefined &&
                   capabilities.resources?.subscribe === true,
-                logLevel: options.defaultLogLevel
+                logLevel: options.defaultLogLevel,
+                listChangeRevision: options.getListChangeRevision?.() ?? 0
               }
               if (httpRequest !== undefined) {
-                const sessionId = crypto.randomUUID()
+                const sessionId = SecureRandom.uuidV4Unsafe()
                 stateful.registerHttp(sessionId, registration)
                 appendPreResponseHandlerUnsafe(
                   fiber.context,

package/src/ai/internal/mcpStatefulRuntime.ts

@@ -28,6 +28,7 @@ export interface Binding {
 
 interface Session extends Binding {
   readonly resourceSubscriptions: Set<string> | undefined
+  readonly listChangeRevision: number
   logLevel: SessionLogLevel
 }
 
@@ -37,6 +38,11 @@ interface Session extends Binding {
 export interface Registration extends Binding {
   readonly supportsResourceSubscriptions: boolean
   readonly logLevel: LogLevel.LogLevel
+  /**
+   * The server's list-change revision when the session initialized. Changes
+   * up to this revision are already reflected in what the client lists next.
+   */
+  readonly listChangeRevision: number
 }
 
 /**
@@ -67,7 +73,8 @@ export interface StatefulRuntime {
     clientId: number,
     headers: Headers.Headers,
     notification: McpCore.ServerNotification,
-    fallbackLogLevel: LogLevel.LogLevel
+    fallbackLogLevel: LogLevel.LogLevel,
+    listChangeRevision: number | undefined
   ) => boolean
   readonly effectLogLevel: (
     clientId: number,
@@ -84,6 +91,7 @@ const makeSession = (registration: Registration): Session => ({
   negotiatedProfile: registration.negotiatedProfile,
   protocol: registration.protocol,
   resourceSubscriptions: registration.supportsResourceSubscriptions ? new Set() : undefined,
+  listChangeRevision: registration.listChangeRevision,
   logLevel: { _tag: "Effect", level: registration.logLevel }
 })
 
@@ -157,8 +165,12 @@ export const make = (): StatefulRuntime => {
       return Effect.sync(() => subscriptions.delete(uri)).pipe(Effect.asVoid)
     },
     effectLogLevel,
-    canDeliver: (clientId, headers, notification, fallbackLogLevel) => {
+    canDeliver: (clientId, headers, notification, fallbackLogLevel, listChangeRevision) => {
       const session = resolveSession(clientId, headers)
+      if (listChangeRevision !== undefined) {
+        // A client without a session on this channel has not initialized.
+        return session !== undefined && listChangeRevision > session.listChangeRevision
+      }
       if (notification._tag === "LoggingMessage") {
         const minimum = session?.logLevel
         return minimum?._tag === "Mcp"

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
@@ -733,6 +748,7 @@ export const map: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -784,6 +800,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -835,6 +852,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -894,6 +912,7 @@ export const mapEffect: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -940,6 +959,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -986,6 +1006,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void

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
+  }
 }
 
 /**