effect 4.0.0-beta.11 → 4.0.0-beta.13

package/src/unstable/ai/LanguageModel.ts

@@ -949,9 +949,8 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
       return content as Array<Response.Part<Tools>>
     }
 
-    // Pre-resolve tool approvals before calling the LLM
+    // Pre-resolve pending tool approvals before calling the LLM
     if (hasPendingApprovals) {
-      // Validate all approved tools exist in the toolkit
       for (const approval of approved) {
         if (approval.toolCall && !toolkit.tools[approval.toolCall.name]) {
           return yield* AiError.make({
@@ -965,7 +964,6 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
         }
       }
 
-      // Execute approved tools and create denial results
       const approvedResults = yield* executeApprovedToolCalls(
         approved,
         toolkit,
@@ -974,23 +972,27 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
       const deniedResults = createDenialResults(denied)
       const preResolvedResults = [...approvedResults, ...deniedResults]
 
-      // Add pre-resolved results to the prompt
       if (preResolvedResults.length > 0) {
-        const toolMessage = Prompt.makeMessage("tool", {
-          content: preResolvedResults
-        })
         providerOptions.prompt = Prompt.fromMessages([
           ...providerOptions.prompt.content,
-          toolMessage
+          Prompt.makeMessage("tool", { content: preResolvedResults })
         ])
       }
+    }
 
-      // Strip consumed approval artifacts so they don't reach the provider
-      providerOptions.prompt = stripResolvedApprovals(
-        providerOptions.prompt,
-        approved,
-        denied
+    // Strip all resolved approval artifacts (both current and from previous
+    // rounds) in a single pass before sending to the provider.
+    {
+      const { approved: allResolved, denied: allDenied } = collectToolApprovals(
+        providerOptions.prompt.content
       )
+      if (allResolved.length > 0 || allDenied.length > 0) {
+        providerOptions.prompt = stripResolvedApprovals(
+          providerOptions.prompt,
+          allResolved,
+          allDenied
+        )
+      }
     }
 
     const tools = typeof toolChoice === "object" && "oneOf" in toolChoice
@@ -1137,9 +1139,10 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
         >
     }
 
-    // Pre-resolve tool approvals before calling the LLM
+    // Pre-resolve pending tool approvals before calling the LLM
+    let preResolvedStreamParts: Array<Response.StreamPart<Tools>> = []
+
     if (hasPendingApprovals) {
-      // Validate all approved tools exist in the toolkit
       for (const approval of pendingApproved) {
         if (approval.toolCall && !toolkit.tools[approval.toolCall.name]) {
           return yield* AiError.make({
@@ -1153,7 +1156,6 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
         }
       }
 
-      // Execute approved tools and create denial results
       const approvedResults = yield* executeApprovedToolCalls(
         pendingApproved,
         toolkit,
@@ -1162,22 +1164,43 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
       const deniedResults = createDenialResults(pendingDenied)
       const preResolvedResults = [...approvedResults, ...deniedResults]
 
-      // Add pre-resolved results to the prompt
       if (preResolvedResults.length > 0) {
-        const toolMessage = Prompt.makeMessage("tool", {
-          content: preResolvedResults
-        })
         providerOptions.prompt = Prompt.fromMessages([
           ...providerOptions.prompt.content,
-          toolMessage
+          Prompt.makeMessage("tool", { content: preResolvedResults })
         ])
       }
 
-      // Strip consumed approval artifacts so they don't reach the provider
+      // Emit pre-resolved tool-results as stream parts so Chat.streamText
+      // persists them to history. This lets collectToolApprovals find them
+      // on subsequent rounds and skip the now-resolved approvals.
+      // Note: r.result is already encoded (from executeApprovedToolCalls /
+      // createDenialResults), so it goes into both result and encodedResult.
+      for (const r of preResolvedResults) {
+        preResolvedStreamParts.push(
+          Response.makePart("tool-result", {
+            id: r.id,
+            name: r.name,
+            providerExecuted: false,
+            preliminary: false,
+            result: r.result,
+            encodedResult: r.result,
+            isFailure: r.isFailure
+          }) as Response.StreamPart<Tools>
+        )
+      }
+    }
+
+    // Strip all resolved approval artifacts (both current and from previous
+    // rounds) in a single pass before sending to the provider.
+    const { approved: allResolved, denied: allDenied } = collectToolApprovals(
+      providerOptions.prompt.content
+    )
+    if (allResolved.length > 0 || allDenied.length > 0) {
       providerOptions.prompt = stripResolvedApprovals(
         providerOptions.prompt,
-        pendingApproved,
-        pendingDenied
+        allResolved,
+        allDenied
       )
     }
 
@@ -1215,6 +1238,13 @@ export const make: (params: ConstructorParams) => Effect.Effect<Service> = Effec
       | Schema.SchemaError
     >()
 
+    // Emit pre-resolved tool results so Chat.streamText persists them to
+    // history. This ensures collectToolApprovals({ excludeResolved }) can
+    // find the corresponding tool-results on future rounds.
+    if (preResolvedStreamParts.length > 0) {
+      yield* Queue.offerAll(queue, preResolvedStreamParts)
+    }
+
     // FiberSet to track concurrent tool call handlers
     const toolCallFibers = yield* FiberSet.make<void, AiError.AiError>()
 

package/src/unstable/ai/McpSchema.ts

@@ -120,7 +120,7 @@ export class ResultMeta extends Schema.Opaque<ResultMeta>()(Schema.Struct({
    * This result property is reserved by the protocol to allow clients and
    * servers to attach additional metadata to their responses.
    */
-  _meta: optional(Schema.Record(Schema.String, Schema.Any))
+  _meta: optional(Schema.Record(Schema.String, Schema.Json))
 })) {}
 
 /**
@@ -132,7 +132,7 @@ export class NotificationMeta extends Schema.Opaque<NotificationMeta>()(Schema.S
    * This parameter name is reserved by MCP to allow clients and servers to
    * attach additional metadata to their notifications.
    */
-  _meta: optional(Schema.Record(Schema.String, Schema.Any))
+  _meta: optional(Schema.Record(Schema.String, Schema.Json))
 })) {}
 
 /**
@@ -240,6 +240,11 @@ export class ClientCapabilities extends Schema.Class<ClientCapabilities>(
    * Experimental, non-standard capabilities that the client supports.
    */
   experimental: optional(Schema.Record(Schema.String, Schema.Struct({}))),
+  /**
+   * Optional extensions capabilities advertised by the client.
+   * Keys are extension identifiers following <vendor-prefix>/<extension-name> (e.g. "io.modelcontextprotocol/ui").
+   */
+  extensions: optional(Schema.Record(Schema.TemplateLiteral([Schema.String, "/", Schema.String]), Schema.Json)),
   /**
    * Present if the client supports listing roots.
    */
@@ -272,6 +277,11 @@ export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Sche
    * Experimental, non-standard capabilities that the server supports.
    */
   experimental: optional(Schema.Record(Schema.String, Schema.Struct({}))),
+  /**
+   * Optional extensions capabilities advertised by the server.
+   * Keys are extension identifiers following <vendor-prefix>/<extension-name> (e.g. "io.modelcontextprotocol/ui").
+   */
+  extensions: optional(Schema.Record(Schema.TemplateLiteral([Schema.String, "/", Schema.String]), Schema.Json)),
   /**
    * Present if the server supports sending log messages to the client.
    */
@@ -321,8 +331,8 @@ export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Sche
  * @since 4.0.0
  * @category errors
  */
-export class McpError extends Schema.Class<McpError>(
-  "@effect/ai/McpSchema/McpError"
+export class McpErrorBase extends Schema.Class<McpErrorBase>(
+  "@effect/ai/McpSchema/McpErrorBase"
 )({
   /**
    * The error type that occurred.
@@ -371,7 +381,7 @@ export const PARSE_ERROR_CODE = -32700 as const
  * @category errors
  */
 export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSchema/ParseError")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("ParseError"),
   code: Schema.tag(PARSE_ERROR_CODE)
 }) {}
@@ -381,7 +391,7 @@ export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSche
  * @category errors
  */
 export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai/McpSchema/InvalidRequest")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidRequest"),
   code: Schema.tag(INVALID_REQUEST_ERROR_CODE)
 }) {}
@@ -391,7 +401,7 @@ export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai
  * @category errors
  */
 export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai/McpSchema/MethodNotFound")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("MethodNotFound"),
   code: Schema.tag(METHOD_NOT_FOUND_ERROR_CODE)
 }) {}
@@ -401,7 +411,7 @@ export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai
  * @category errors
  */
 export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/McpSchema/InvalidParams")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidParams"),
   code: Schema.tag(INVALID_PARAMS_ERROR_CODE)
 }) {}
@@ -411,13 +421,26 @@ export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/M
  * @category errors
  */
 export class InternalError extends Schema.ErrorClass<InternalError>("effect/ai/McpSchema/InternalError")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("InternalError"),
   code: Schema.tag(INTERNAL_ERROR_CODE)
 }) {
   static readonly notImplemented = new InternalError({ message: "Not implemented" })
 }
 
+/**
+ * @since 4.0.0
+ * @category errors
+ */
+export const McpError = Schema.Union([
+  ParseError,
+  InvalidRequest,
+  MethodNotFound,
+  InvalidParams,
+  InternalError,
+  McpErrorBase
+])
+
 // =============================================================================
 // Ping
 // =============================================================================
@@ -615,7 +638,14 @@ export class Resource extends Schema.Class<Resource>(
    * This can be used by Hosts to display file sizes and estimate context
    * window usage.
    */
-  size: optional(Schema.Number)
+  size: optional(Schema.Number),
+  /**
+   * Optional additional metadata for the client.
+   *
+   * This parameter name is reserved by MCP to allow clients and servers to
+   * attach additional metadata to resources.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Json))
 }) {}
 
 /**
@@ -656,7 +686,12 @@ export class ResourceTemplate extends Schema.Class<ResourceTemplate>(
   /**
    * Optional annotations for the client.
    */
-  annotations: optional(Annotations)
+  annotations: optional(Annotations),
+
+  /**
+   * Optional additional metadata for the client.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Json))
 }) {}
 
 /**
@@ -673,7 +708,11 @@ export class ResourceContents extends Schema.Opaque<ResourceContents>()(Schema.S
   /**
    * The MIME type of this resource, if known.
    */
-  mimeType: optional(Schema.String)
+  mimeType: optional(Schema.String),
+  /**
+   * Optional additional metadata for the client.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Json))
 })) {}
 
 /**
@@ -1183,7 +1222,14 @@ export class Tool extends Schema.Class<Tool>(
   /**
    * Optional additional tool information.
    */
-  annotations: optional(ToolAnnotations)
+  annotations: optional(ToolAnnotations),
+  /**
+   * Optional additional metadata for the client.
+   *
+   * This parameter name is reserved by MCP to allow clients and servers to
+   * attach additional metadata to resources.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Json))
 }) {}
 
 /**

package/src/unstable/ai/McpServer.ts

@@ -9,6 +9,7 @@ import * as Layer from "../../Layer.ts"
 import * as Option from "../../Option.ts"
 import * as Queue from "../../Queue.ts"
 import * as RcMap from "../../RcMap.ts"
+import { CurrentLogLevel } from "../../References.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
@@ -548,6 +549,7 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
   >)
   const services = yield* Effect.services<never>()
   for (const tool of Object.values(built.tools)) {
+    const toolMeta = ServiceMap.getOrUndefined(tool.annotations, Tool.Meta)
     const mcpTool = new McpTool({
       name: tool.name,
       description: Tool.getDescription(tool),
@@ -561,7 +563,8 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
         destructiveHint: ServiceMap.get(tool.annotations, Tool.Destructive),
         idempotentHint: ServiceMap.get(tool.annotations, Tool.Idempotent),
         openWorldHint: ServiceMap.get(tool.annotations, Tool.OpenWorld)
-      }
+      },
+      _meta: toolMeta
     })
     yield* registry.addTool({
       tool: mcpTool,
@@ -1075,6 +1078,7 @@ const layerHandlers = (serverInfo: {
   ClientRpcs.toLayer(
     Effect.gen(function*() {
       const server = yield* McpServer
+      let currentLogLevel = yield* CurrentLogLevel
 
       return ClientRpcs.of({
         // Requests
@@ -1105,17 +1109,51 @@ const layerHandlers = (serverInfo: {
               : LATEST_PROTOCOL_VERSION
           })
         },
-        "completion/complete": server.completion,
-        "logging/setLevel": () => InternalError.notImplemented.asEffect(),
-        "prompts/get": server.getPromptResult,
+        "completion/complete": (r) =>
+          server.completion(r).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
+        "logging/setLevel": ({ level }) =>
+          Effect.sync(() => {
+            switch (level) {
+              case "notice":
+              case "info":
+                currentLogLevel = "Info"
+                break
+              case "error":
+                currentLogLevel = "Error"
+                break
+              case "debug":
+                currentLogLevel = "Debug"
+                break
+              case "warning":
+                currentLogLevel = "Warn"
+                break
+              case "critical":
+              case "alert":
+              case "emergency":
+                currentLogLevel = "Fatal"
+                break
+            }
+          }),
+        "prompts/get": (r) =>
+          server.getPromptResult(r).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
         "prompts/list": () => Effect.sync(() => new ListPromptsResult({ prompts: server.prompts })),
         "resources/list": () => Effect.sync(() => new ListResourcesResult({ resources: server.resources })),
-        "resources/read": ({ uri }) => server.findResource(uri),
+        "resources/read": ({ uri }) =>
+          server.findResource(uri).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
         "resources/subscribe": () => InternalError.notImplemented.asEffect(),
         "resources/unsubscribe": () => InternalError.notImplemented.asEffect(),
         "resources/templates/list": () =>
           Effect.sync(() => new ListResourceTemplatesResult({ resourceTemplates: server.resourceTemplates })),
-        "tools/call": server.callTool,
+        "tools/call": (r) =>
+          server.callTool(r).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
         "tools/list": () => Effect.sync(() => new ListToolsResult({ tools: server.tools })),
 
         // Notifications

package/src/unstable/ai/Tool.ts

@@ -1661,6 +1661,21 @@ export const getJsonSchemaFromSchema = <S extends Schema.Top>(schema: S, options
  */
 export class Title extends ServiceMap.Service<Title, string>()("effect/ai/Tool/Title") {}
 
+/**
+ * Annotation for providing tool metadata for MCP.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "effect/unstable/ai"
+ *
+ * const myCalculatorUi = Tool.make("calculator_ui", {})
+ *   .annotate(Tool.Meta, { ui: { resourceUri: "ui://example/calculator-ui" } })
+ * ```
+ * @since 1.0.0
+ * @category annotations
+ */
+export class Meta extends ServiceMap.Service<Meta, Record<string, unknown>>()("effect/ai/Tool/Meta") {}
+
 /**
  * Annotation indicating whether a tool only reads data without making changes.
  *

package/src/unstable/cli/CliOutput.ts

@@ -409,6 +409,8 @@ const renderTable = (rows: ReadonlyArray<Row>, widthCap: number) => {
   return rows.map(({ left, right }) => `  ${pad(left, col)}${right}`).join("\n")
 }
 
+const formatSubcommandName = (name: string, alias: string | undefined): string => alias ? `${name}, ${alias}` : name
+
 /**
  * Color functions interface for help formatting.
  * @internal
@@ -497,6 +499,34 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
     sections.push("")
   }
 
+  // Global Flags section
+  if (doc.globalFlags && doc.globalFlags.length > 0) {
+    sections.push(colors.bold("GLOBAL FLAGS"))
+
+    const globalFlagRows: Array<Row> = doc.globalFlags.map((flag) => {
+      const names: Array<string> = []
+
+      // Add main name with -- prefix first
+      names.push(colors.green(`--${flag.name}`))
+
+      // Add aliases after (like -f) to match expected ordering
+      for (const alias of flag.aliases) {
+        names.push(colors.green(alias))
+      }
+
+      const namesPart = names.join(", ")
+      const typePart = flag.type !== "boolean" ? ` ${colors.dim(flag.type)}` : ""
+
+      return {
+        left: namesPart + typePart,
+        right: flag.description ?? ""
+      }
+    })
+
+    sections.push(renderTable(globalFlagRows, 30))
+    sections.push("")
+  }
+
   // Subcommands section
   if (doc.subcommands && doc.subcommands.length > 0) {
     const ungrouped = doc.subcommands.find((group) => group.group === undefined)
@@ -505,7 +535,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
       sections.push(colors.bold("SUBCOMMANDS"))
       sections.push(renderTable(
         ungrouped.commands.map((sub) => ({
-          left: colors.cyan(sub.name),
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
           right: sub.shortDescription ?? sub.description
         })),
         20
@@ -520,7 +550,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
       sections.push(colors.bold(`${group.group}:`))
       sections.push(renderTable(
         group.commands.map((sub) => ({
-          left: colors.cyan(sub.name),
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
           right: sub.shortDescription ?? sub.description
         })),
         20