effect 4.0.1 → 4.0.3

package/src/ai/Telemetry.ts

@@ -27,50 +27,35 @@ import type * as Response from "./Response.ts"
  *
  * These attributes follow the OpenTelemetry generative AI semantic
  * conventions:
- * https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
+ * https://github.com/open-telemetry/semantic-conventions-genai
  *
  * @stability unstable
  * @category models
  * @since 4.0.0
  */
 export type GenAITelemetryAttributes = Struct.Simplify<
-  & AttributesWithPrefix<BaseAttributes, "gen_ai">
+  & AttributesWithPrefix<ProviderAttributes, "gen_ai.provider">
   & AttributesWithPrefix<OperationAttributes, "gen_ai.operation">
-  & AttributesWithPrefix<TokenAttributes, "gen_ai.token">
+  & AttributesWithPrefix<OutputAttributes, "gen_ai.output">
   & AttributesWithPrefix<UsageAttributes, "gen_ai.usage">
   & AttributesWithPrefix<RequestAttributes, "gen_ai.request">
   & AttributesWithPrefix<ResponseAttributes, "gen_ai.response">
 >
 
-/**
- * All telemetry attributes which are part of the GenAI specification.
- *
- * @stability unstable
- * @category models
- * @since 4.0.0
- */
-export type AllAttributes =
-  & BaseAttributes
-  & OperationAttributes
-  & TokenAttributes
-  & UsageAttributes
-  & RequestAttributes
-  & ResponseAttributes
-
 /**
  * Telemetry attributes which are part of the GenAI specification and are
- * namespaced by `gen_ai`.
+ * namespaced by `gen_ai.provider`.
  *
  * @stability unstable
  * @category models
- * @since 4.0.0
+ * @since 4.0.2
  */
-export interface BaseAttributes {
+export interface ProviderAttributes {
   /**
-   * The Generative AI product as identified by the client or server
-   * instrumentation.
+   * The Generative AI provider as identified by the client or server
+   * instrumentation, written as `gen_ai.provider.name`.
    */
-  readonly system?: (string & {}) | WellKnownSystem | null | undefined
+  readonly name?: (string & {}) | WellKnownProviderName | null | undefined
 }
 
 /**
@@ -87,14 +72,17 @@ export interface OperationAttributes {
 
 /**
  * Telemetry attributes which are part of the GenAI specification and are
- * namespaced by `gen_ai.token`.
+ * namespaced by `gen_ai.output`.
  *
  * @stability unstable
  * @category models
- * @since 4.0.0
+ * @since 4.0.2
  */
-export interface TokenAttributes {
-  readonly type?: string | null | undefined
+export interface OutputAttributes {
+  /**
+   * The output modality requested by the client.
+   */
+  readonly type?: (string & {}) | WellKnownOutputType | null | undefined
 }
 
 /**
@@ -128,15 +116,15 @@ export interface RequestAttributes {
    */
   readonly temperature?: number | null | undefined
   /**
-   * The temperature setting for the GenAI request.
+   * The top_k sampling setting for the GenAI request.
    */
   readonly topK?: number | null | undefined
   /**
-   * The top_k sampling setting for the GenAI request.
+   * The top_p sampling setting for the GenAI request.
    */
   readonly topP?: number | null | undefined
   /**
-   * The top_p sampling setting for the GenAI request.
+   * The maximum number of tokens the model may generate.
    */
   readonly maxTokens?: number | null | undefined
   /**
@@ -203,7 +191,18 @@ export interface ResponseAttributes {
 export type WellKnownOperationName = "chat" | "embeddings" | "text_completion"
 
 /**
- * The `gen_ai.system` attribute has the following list of well-known values.
+ * The `gen_ai.output.type` attribute has the following list of well-known
+ * values.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.2
+ */
+export type WellKnownOutputType = "text" | "json" | "image" | "speech"
+
+/**
+ * The `gen_ai.provider.name` attribute has the following list of well-known
+ * values.
  *
  * **Details**
  *
@@ -212,23 +211,25 @@ export type WellKnownOperationName = "chat" | "embeddings" | "text_completion"
  *
  * @stability unstable
  * @category models
- * @since 4.0.0
+ * @since 4.0.2
  */
-export type WellKnownSystem =
+export type WellKnownProviderName =
   | "anthropic"
   | "aws.bedrock"
-  | "az.ai.inference"
-  | "az.ai.openai"
+  | "azure.ai.inference"
+  | "azure.ai.openai"
   | "cohere"
   | "deepseek"
-  | "gemini"
+  | "gcp.gemini"
+  | "gcp.gen_ai"
+  | "gcp.vertex_ai"
   | "groq"
   | "ibm.watsonx.ai"
   | "mistral_ai"
+  | "moonshot_ai"
   | "openai"
   | "perplexity"
-  | "vertex_ai"
-  | "xai"
+  | "x_ai"
 
 /**
  * Utility type for prefixing attribute names with a namespace.
@@ -375,11 +376,11 @@ export const addSpanAttributes = (
   }
 }
 
-const addSpanBaseAttributes = addSpanAttributes("gen_ai", String.camelToSnake)<BaseAttributes>
+const addSpanProviderAttributes = addSpanAttributes("gen_ai.provider", String.camelToSnake)<ProviderAttributes>
 const addSpanOperationAttributes = addSpanAttributes("gen_ai.operation", String.camelToSnake)<OperationAttributes>
+const addSpanOutputAttributes = addSpanAttributes("gen_ai.output", String.camelToSnake)<OutputAttributes>
 const addSpanRequestAttributes = addSpanAttributes("gen_ai.request", String.camelToSnake)<RequestAttributes>
 const addSpanResponseAttributes = addSpanAttributes("gen_ai.response", String.camelToSnake)<ResponseAttributes>
-const addSpanTokenAttributes = addSpanAttributes("gen_ai.token", String.camelToSnake)<TokenAttributes>
 const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToSnake)<UsageAttributes>
 
 /**
@@ -387,8 +388,7 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  *
  * **Details**
  *
- * Combines base attributes with optional grouped attributes for comprehensive
- * telemetry coverage of AI operations.
+ * Groups attributes by their `gen_ai.*` namespace.
  *
  * **Example** (Configuring GenAI telemetry attributes)
  *
@@ -396,7 +396,7 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  * import type { Telemetry } from "effect/ai"
  *
  * const telemetryOptions: Telemetry.GenAITelemetryAttributeOptions = {
- *   system: "openai",
+ *   provider: { name: "openai" },
  *   operation: {
  *     name: "chat"
  *   },
@@ -416,18 +416,26 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  *   }
  * }
  *
- * const result = [telemetryOptions.system, telemetryOptions.usage?.inputTokens] // => ["openai", 50]
+ * const result = [telemetryOptions.provider?.name, telemetryOptions.usage?.inputTokens] // => ["openai", 50]
  * ```
  *
  * @stability unstable
  * @category options
  * @since 4.0.0
  */
-export type GenAITelemetryAttributeOptions = BaseAttributes & {
+export type GenAITelemetryAttributeOptions = {
+  /**
+   * Provider attributes (e.g., provider name).
+   */
+  readonly provider?: ProviderAttributes | undefined
   /**
    * Operation-specific attributes (e.g., operation name).
    */
   readonly operation?: OperationAttributes | undefined
+  /**
+   * Output attributes (e.g., requested output type).
+   */
+  readonly output?: OutputAttributes | undefined
   /**
    * Request-specific attributes (e.g., model parameters).
    */
@@ -436,10 +444,6 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
    * Response-specific attributes (e.g., response metadata).
    */
   readonly response?: ResponseAttributes | undefined
-  /**
-   * Token-specific attributes.
-   */
-  readonly token?: TokenAttributes | undefined
   /**
    * Usage statistics attributes (e.g., token counts).
    */
@@ -451,7 +455,7 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  *
  * **When to use**
  *
- * Use when you need to write GenAI request, response, token, or usage
+ * Use when you need to write GenAI request, response, or usage
  * attributes onto an existing OpenTelemetry span.
  *
  * **Details**
@@ -473,7 +477,7 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  *   const span = yield* Effect.currentSpan
  *
  *   Telemetry.addGenAIAnnotations(span, {
- *     system: "openai",
+ *     provider: { name: "openai" },
  *     request: { model: "gpt-4", temperature: 0.7 },
  *     usage: { inputTokens: 100, outputTokens: 50 }
  *   })
@@ -493,7 +497,7 @@ export const addGenAIAnnotations: {
    *
    * **When to use**
    *
-   * Use when you need to write GenAI request, response, token, or usage
+   * Use when you need to write GenAI request, response, or usage
    * attributes onto an existing OpenTelemetry span.
    *
    * **Details**
@@ -515,7 +519,7 @@ export const addGenAIAnnotations: {
    *   const span = yield* Effect.currentSpan
    *
    *   Telemetry.addGenAIAnnotations(span, {
-   *     system: "openai",
+   *     provider: { name: "openai" },
    *     request: { model: "gpt-4", temperature: 0.7 },
    *     usage: { inputTokens: 100, outputTokens: 50 }
    *   })
@@ -535,7 +539,7 @@ export const addGenAIAnnotations: {
    *
    * **When to use**
    *
-   * Use when you need to write GenAI request, response, token, or usage
+   * Use when you need to write GenAI request, response, or usage
    * attributes onto an existing OpenTelemetry span.
    *
    * **Details**
@@ -557,7 +561,7 @@ export const addGenAIAnnotations: {
    *   const span = yield* Effect.currentSpan
    *
    *   Telemetry.addGenAIAnnotations(span, {
-   *     system: "openai",
+   *     provider: { name: "openai" },
    *     request: { model: "gpt-4", temperature: 0.7 },
    *     usage: { inputTokens: 100, outputTokens: 50 }
    *   })
@@ -573,11 +577,11 @@ export const addGenAIAnnotations: {
    */
   (span: Span, options: GenAITelemetryAttributeOptions): void
 } = dual(2, (span: Span, options: GenAITelemetryAttributeOptions) => {
-  addSpanBaseAttributes(span, { system: options.system })
+  if (Predicate.isNotNullish(options.provider)) addSpanProviderAttributes(span, options.provider)
   if (Predicate.isNotNullish(options.operation)) addSpanOperationAttributes(span, options.operation)
+  if (Predicate.isNotNullish(options.output)) addSpanOutputAttributes(span, options.output)
   if (Predicate.isNotNullish(options.request)) addSpanRequestAttributes(span, options.request)
   if (Predicate.isNotNullish(options.response)) addSpanResponseAttributes(span, options.response)
-  if (Predicate.isNotNullish(options.token)) addSpanTokenAttributes(span, options.token)
   if (Predicate.isNotNullish(options.usage)) addSpanUsageAttributes(span, options.usage)
 })
 

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

@@ -386,6 +386,8 @@ export const makeHandlers = (
       }
       const presence = yield* context.registrationPresence
       const eventsScope = yield* Scope.fork(yield* Effect.scope)
+      // Ignore changes emitted before this subscription, even if delivery was deferred.
+      const listChangeRevision = context.getListChangeRevision?.() ?? 0
       const events = yield* Scope.provide(context.subscribeServerNotifications, eventsScope)
       const honored = {
         ...(presence.tools && request.notifications.toolsListChanged === true
@@ -410,6 +412,9 @@ export const makeHandlers = (
       yield* Effect.gen(function*() {
         while (true) {
           const event = yield* PubSub.take(events)
+          if (event.listChangeRevision !== undefined && event.listChangeRevision <= listChangeRevision) {
+            continue
+          }
           if (event.targetClientId !== undefined && event.targetClientId !== client.id) {
             continue
           }

package/src/ai/internal/mcpProtocol.ts

@@ -382,6 +382,8 @@ export interface HandlerInstallationContext {
     never,
     Scope.Scope
   >
+  /** Current list-change revision; subscriptions ignore changes emitted at or before it. */
+  readonly getListChangeRevision?: (() => number) | undefined
   readonly sendNotification?: (
     protocolVersion: string,
     clientId: number,
@@ -419,6 +421,7 @@ export interface HandlerInstallationContext {
  */
 export interface CanonicalServerNotification {
   readonly notification: SubscriptionServerNotification
+  readonly listChangeRevision?: number | undefined
   readonly targetClientId?: number | undefined
 }
 

package/src/ai/internal/mcpRuntime.ts

@@ -17,6 +17,7 @@ import * as Predicate from "../../Predicate.ts"
 import * as Result from "../../Result.ts"
 import * as RpcGroup from "../../rpc/RpcGroup.ts"
 import type * as RpcMessage from "../../rpc/RpcMessage.ts"
+import type * as Scope from "../../Scope.ts"
 import type * as PublicMcpProtocol from "../McpProtocol.ts"
 import * as PublicMcpSchema from "../McpSchema.ts"
 import type * as McpCore from "./mcpCore.ts"
@@ -122,6 +123,7 @@ export type HttpAdmission =
  */
 export interface HandlerInstallationOptions {
   readonly core: McpCore.McpCore
+  readonly getListChangeRevision?: () => number
   readonly subscribeServerNotifications: McpProtocol.HandlerInstallationContext["subscribeServerNotifications"]
   readonly sendNotification?: NonNullable<McpProtocol.HandlerInstallationContext["sendNotification"]>
   readonly markSubscriptionCancelled?: NonNullable<
@@ -175,6 +177,10 @@ export interface ServerRuntimeShape {
     fallback: LogLevel.LogLevel
   ) => LogLevel.LogLevel
   readonly disconnect: (clientId: number) => void
+  readonly terminateHttpSession: (headers: Headers.Headers) => Effect.Effect<HttpServerResponse.HttpServerResponse>
+  readonly onSessionTerminated: (
+    listener: (binding: RequestBinding) => Effect.Effect<void>
+  ) => Effect.Effect<void, never, Scope.Scope>
   readonly deliveryClientIds: () => Iterable<number>
   readonly canDeliver: (
     clientId: number,
@@ -228,9 +234,36 @@ export const make = Effect.fnUntraced(function*(
     statelessProtocol = protocol
   }
   const registry = yield* McpProtocolRegistry.make(protocols)
-  const selectHttpProtocol = (headers: Headers.Headers, input: unknown): HttpProtocolSelection => {
+  const sessionTerminationListeners = new Set<(binding: RequestBinding) => Effect.Effect<void>>()
+  const unsupportedProtocolVersion = (requested: string) => ({
+    code: UNSUPPORTED_PROTOCOL_VERSION_ERROR_CODE,
+    message: `Unsupported protocol version '${requested}'`,
+    data: { supported: protocolVersions, requested }
+  })
+  const selectHttpSession = (headers: Headers.Headers, isInitialize: boolean): HttpProtocolSelection => {
     const protocolVersion = headers[MCP_PROTOCOL_VERSION_HEADER]
     const sessionId = headers[MCP_SESSION_ID_HEADER]
+    const binding = sessionId === undefined ? undefined : stateful?.resolveSessionId(sessionId)
+    if (sessionId !== undefined && binding === undefined) {
+      return { _tag: "Rejected", status: 404 }
+    }
+    if (!isInitialize && protocolVersion !== undefined) {
+      if (!protocolVersions.includes(protocolVersion)) {
+        return { _tag: "Rejected", status: 400, error: unsupportedProtocolVersion(protocolVersion) }
+      }
+      if (
+        binding?.protocol.runtime.transport.http.requiresVersionHeader === true &&
+        protocolVersion !== binding.protocol.protocolVersion
+      ) {
+        return headerMismatch(
+          `MCP-Protocol-Version header '${protocolVersion}' does not match negotiated protocol version '${binding.protocol.protocolVersion}'`
+        )
+      }
+    }
+    return { _tag: "Accepted", binding, protocol: binding?.protocol }
+  }
+  const selectHttpProtocol = (headers: Headers.Headers, input: unknown): HttpProtocolSelection => {
+    const protocolVersion = headers[MCP_PROTOCOL_VERSION_HEADER]
     const inputRecord = asRecord(input)
     const metadata = asRecord(asRecord(inputRecord?.params)?._meta)
     const claim = protocolVersionClaim(metadata)
@@ -272,18 +305,7 @@ export const make = Effect.fnUntraced(function*(
         }
       }
       if (statelessProtocol === undefined || protocolVersion !== statelessProtocol.protocolVersion) {
-        return {
-          _tag: "Rejected",
-          status: 400,
-          error: {
-            code: UNSUPPORTED_PROTOCOL_VERSION_ERROR_CODE,
-            message: `Unsupported protocol version '${protocolVersion}'`,
-            data: {
-              supported: protocolVersions,
-              requested: protocolVersion
-            }
-          }
-        }
+        return { _tag: "Rejected", status: 400, error: unsupportedProtocolVersion(protocolVersion) }
       }
       const method = inputRecord?.method
       if (typeof method !== "string" || headers[MCP_METHOD_HEADER] !== method) {
@@ -299,25 +321,7 @@ export const make = Effect.fnUntraced(function*(
       }
       return { _tag: "Accepted", binding: undefined, protocol: statelessProtocol }
     }
-    const binding = sessionId === undefined ? undefined : stateful?.resolveSessionId(sessionId)
-    if (sessionId !== undefined && binding === undefined) {
-      return { _tag: "Rejected", status: 404 }
-    }
-    if (
-      !isInitialize &&
-      protocolVersion !== undefined &&
-      !registry.protocols.some((protocol) => protocol.protocolVersion === protocolVersion)
-    ) {
-      return { _tag: "Rejected", status: 400 }
-    }
-    if (
-      !isInitialize &&
-      binding?.protocol.runtime.transport.http.requiresVersionHeader === true &&
-      protocolVersion !== binding.protocol.protocolVersion
-    ) {
-      return { _tag: "Rejected", status: 400 }
-    }
-    return { _tag: "Accepted", binding, protocol: binding?.protocol }
+    return selectHttpSession(headers, isInitialize)
   }
   return ServerRuntime.of({
     protocols: registry.protocols,
@@ -362,11 +366,7 @@ export const make = Effect.fnUntraced(function*(
         return yield* Effect.die("MCP stateless runtime invariant failed")
       }
       if (requestedVersion !== undefined && requestedVersion !== protocol.protocolVersion) {
-        return yield* new McpProtocol.ProtocolError({
-          code: UNSUPPORTED_PROTOCOL_VERSION_ERROR_CODE,
-          message: `Unsupported protocol version '${requestedVersion}'`,
-          data: { supported: protocolVersions, requested: requestedVersion }
-        })
+        return yield* new McpProtocol.ProtocolError(unsupportedProtocolVersion(requestedVersion))
       }
       const decodedProfile = yield* statelessDescriptor.profileFromRequestMetadata(metadata)
       const profile: McpCore.NegotiatedProtocolProfile<string> = {
@@ -394,12 +394,14 @@ export const make = Effect.fnUntraced(function*(
       })
       if (Result.isFailure(parsed)) {
         const version = headers[MCP_PROTOCOL_VERSION_HEADER]
-        if (version !== undefined && !registry.protocols.some((protocol) => protocol.protocolVersion === version)) {
-          return reject(400)
+        if (version !== undefined && !protocolVersions.includes(version)) {
+          return reject(400, unsupportedProtocolVersion(version))
         }
         const admission = selectHttpProtocol(headers, undefined)
-        return admission._tag === "Rejected" && admission.error === undefined
-          ? reject(admission.status)
+        // Session and protocol-header errors take precedence over parse errors.
+        return admission._tag === "Rejected" &&
+            (admission.error === undefined || admission.error.code === PublicMcpSchema.HEADER_MISMATCH_ERROR_CODE)
+          ? reject(admission.status, admission.error)
           : reject(200, new PublicMcpSchema.ParseError({ message: "Parse error" }))
       }
       const input = parsed.success
@@ -444,8 +446,21 @@ export const make = Effect.fnUntraced(function*(
       }
       const isInitialize = Predicate.hasProperty(input, "method") && input.method === "initialize"
       const hasSession = headers[MCP_SESSION_ID_HEADER] !== undefined
-      if (isInitialize ? hasSession : !hasSession && admission.protocol?.runtime._tag !== "Stateless") {
-        return reject(400)
+      if (isInitialize && hasSession) {
+        return reject(
+          400,
+          new PublicMcpSchema.InvalidRequest({ message: "initialize must not include an MCP-Session-Id header" }),
+          id
+        )
+      }
+      if (!isInitialize && !hasSession && admission.protocol?.runtime._tag !== "Stateless") {
+        return reject(
+          400,
+          stateful === undefined ? undefined : new PublicMcpSchema.InvalidRequest({
+            message: "MCP-Session-Id header is required; send initialize to start a session"
+          }),
+          id
+        )
       }
       if (
         isRequest && admission.protocol?.runtime._tag === "Stateless" &&
@@ -464,6 +479,33 @@ export const make = Effect.fnUntraced(function*(
     },
     effectLogLevel: (clientId, headers, fallback) => stateful?.effectLogLevel(clientId, headers, fallback) ?? fallback,
     disconnect: (clientId) => stateful?.disconnect(clientId),
+    terminateHttpSession: (headers) =>
+      Effect.suspend(() => {
+        const sessionId = headers[MCP_SESSION_ID_HEADER]
+        if (sessionId === undefined) {
+          return Effect.succeed(HttpServerResponse.empty({ status: 400 }))
+        }
+        const selection = selectHttpSession(headers, false)
+        if (selection._tag === "Rejected") {
+          return Effect.succeed(HttpServerResponse.empty({ status: selection.status }))
+        }
+        const binding = selection.binding!
+        stateful!.terminateSession(sessionId)
+        return Effect.as(
+          Effect.forEach(sessionTerminationListeners, (listener) => listener(binding), { discard: true }),
+          HttpServerResponse.empty({ status: 204 })
+        )
+      }),
+    onSessionTerminated: (listener) =>
+      Effect.acquireRelease(
+        Effect.sync(() => {
+          sessionTerminationListeners.add(listener)
+        }),
+        () =>
+          Effect.sync(() => {
+            sessionTerminationListeners.delete(listener)
+          })
+      ),
     deliveryClientIds: () => stateful?.initializedClientIds() ?? [],
     canDeliver: (clientId, headers, notification, fallback) =>
       stateful?.canDeliver(clientId, headers, notification, fallback) ?? true,
@@ -471,6 +513,7 @@ export const make = Effect.fnUntraced(function*(
       const contextMap = new Map<string, unknown>()
       const installationContext: McpProtocol.HandlerInstallationContext = {
         subscribeServerNotifications: options.subscribeServerNotifications,
+        getListChangeRevision: options.getListChangeRevision,
         ...(options.sendNotification === undefined ? {} : { sendNotification: options.sendNotification }),
         ...(options.markSubscriptionCancelled === undefined
           ? {}

package/src/ai/internal/mcpStatefulRuntime.ts

@@ -47,6 +47,7 @@ export interface StatefulRuntime {
   readonly registerConnection: (clientId: number, registration: Registration) => Binding
   readonly resolve: (clientId: number, headers: Headers.Headers) => Binding | undefined
   readonly resolveSessionId: (sessionId: string) => Binding | undefined
+  readonly terminateSession: (sessionId: string) => boolean
   readonly setLogLevel: (
     level: PublicMcpSchema.LoggingLevel,
     clientId: number,
@@ -123,6 +124,7 @@ export const make = (): StatefulRuntime => {
     },
     resolve: resolveSession,
     resolveSessionId: (sessionId) => bySessionId.get(sessionId),
+    terminateSession: (sessionId) => bySessionId.delete(sessionId),
     setLogLevel: (level, clientId, headers) =>
       Effect.sync(() => {
         const session = resolveSession(clientId, headers)

package/src/cli/CliOutput.ts

@@ -16,6 +16,7 @@ import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
 import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
+import * as Ansi from "./internal/ansi.ts"
 
 /**
  * Defines the service interface for formatting CLI output including help, errors, and version info.
@@ -306,17 +307,7 @@ const escapeControlCharacters = (text: string): string =>
  * @since 4.0.0
  */
 export const defaultFormatter = (options?: { colors?: boolean }): Formatter => {
-  const globalProcess = (globalThis as any).process
-  const hasProcess = typeof globalProcess === "object" && globalProcess !== null
-
-  const useColor = options?.colors !== undefined
-    ? options.colors
-    // Auto-detect based on environment
-    : (hasProcess &&
-      typeof globalProcess.stdout === "object" &&
-      globalProcess.stdout !== null &&
-      globalProcess.stdout.isTTY === true &&
-      !globalProcess.env?.NO_COLOR)
+  const useColor = options?.colors ?? Ansi.detectColors()
 
   // Color palette using ANSI escape codes
   const colors = useColor
@@ -390,7 +381,7 @@ const stripAnsi = (text: string): string => {
 }
 
 /**
- * Gets the terminal display width of a string (excluding ANSI codes).
+ * Segments text into grapheme clusters.
  * @internal
  */
 const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" })
@@ -424,7 +415,33 @@ const graphemeWidth = (grapheme: string): number => {
   return isFullWidthCodePoint(visible.codePointAt(0)!) ? 2 : 1
 }
 
-const visualLength = (text: string): number => {
+/**
+ * Measures the number of terminal cells a string occupies.
+ *
+ * **Details**
+ *
+ * Uses the same measurement as built-in help and table rendering. ANSI styling
+ * is stripped before measuring graphemes: zero-width graphemes count as `0`,
+ * emoji presentation sequences and fullwidth characters as `2`, and other
+ * graphemes as `1`.
+ *
+ * **Example** (Measuring terminal-cell widths)
+ *
+ * ```ts import.meta.vitest
+ * import { CliOutput } from "effect/cli"
+ *
+ * CliOutput.displayWidth("file") // => 4
+ * CliOutput.displayWidth("ファイル") // => 8
+ * CliOutput.displayWidth("é") // => 1
+ * CliOutput.displayWidth("1️⃣") // => 2
+ * CliOutput.displayWidth("\u001B[1mbold\u001B[0m") // => 4
+ * ```
+ *
+ * @stability unstable
+ * @category measuring
+ * @since 4.0.3
+ */
+export const displayWidth = (text: string): number => {
   let length = 0
   for (const { segment } of graphemeSegmenter.segment(stripAnsi(text))) {
     length += graphemeWidth(segment)
@@ -437,7 +454,7 @@ const visualLength = (text: string): number => {
  * @internal
  */
 const pad = (s: string, width: number) => {
-  const actualLength = visualLength(s)
+  const actualLength = displayWidth(s)
   const padding = Math.max(0, width - actualLength)
   return s + " ".repeat(padding)
 }
@@ -456,9 +473,9 @@ interface Row {
  * @internal
  */
 const renderTable = (rows: ReadonlyArray<Row>, widthCap?: number) => {
-  const maxColumn = Math.max(...rows.map((r) => visualLength(r.left))) + 4
+  const maxColumn = Math.max(...rows.map((r) => displayWidth(r.left))) + 4
   const col = widthCap === undefined ? maxColumn : Math.min(maxColumn, widthCap)
-  return rows.map(({ left, right }) => `  ${pad(left, Math.max(col, visualLength(left) + 1))}${right}`).join("\n")
+  return rows.map(({ left, right }) => `  ${pad(left, Math.max(col, displayWidth(left) + 1))}${right}`).join("\n")
 }
 
 const formatSubcommandName = (name: string, alias: string | undefined): string => alias ? `${name}, ${alias}` : name

package/src/cli/Command.ts

@@ -3104,14 +3104,15 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
         if (!hasEntry) continue
         const [, value] = yield* flag.flag.parse(emptyArgs)
         if (flag === GlobalFlag.Wizard) {
+          const { colors } = yield* Prompt.Theme
           return yield* Effect.gen(function*() {
-            yield* Console.log(Wizard.renderIntroduction(command.name, config.version, command.description))
+            yield* Console.log(Wizard.renderIntroduction(command.name, config.version, command.description, colors))
             const prefix = [
               command.name,
               ...args.filter((arg) => arg !== "--wizard" && !arg.startsWith("--wizard="))
             ]
             const wizardResult = yield* Wizard.run(command, { commandPath, prefix })
-            yield* Console.log(Wizard.renderCompletion(wizardResult.displayArgs))
+            yield* Console.log(Wizard.renderCompletion(wizardResult.displayArgs, colors))
             const shouldRun = yield* Prompt.run(Prompt.Toggle({
               message: "Run this command?",
               initial: true,
@@ -3123,7 +3124,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
               yield* runWith(command, { ...config, renderErrors: false })(wizardResult.args.slice(1))
             }
           }).pipe(
-            Effect.catchTag("QuitError", () => Console.log(Wizard.renderQuit()))
+            Effect.catchTag("QuitError", () => Console.log(Wizard.renderQuit(colors)))
           )
         }
         yield* flag.run(value, handlerCtx)