effect 4.0.0-beta.67 → 4.0.0-beta.69

package/src/unstable/ai/Telemetry.ts

@@ -302,8 +302,8 @@ export type FormatAttributeName<T extends string | number | symbol> = T extends
  * **Example** (Adding prefixed span attributes)
  *
  * ```ts
- * import type { Tracer } from "effect"
  * import { String } from "effect"
+ * import type { Tracer } from "effect"
  * import { Telemetry } from "effect/unstable/ai"
  *
  * const addCustomAttributes = Telemetry.addSpanAttributes(
@@ -320,7 +320,7 @@ export type FormatAttributeName<T extends string | number | symbol> = T extends
  * // Results in attributes: "custom.ai.model_name" and "custom.ai.max_tokens"
  * ```
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const addSpanAttributes = (
@@ -441,7 +441,7 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  * })
  * ```
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const addGenAIAnnotations: {
@@ -470,7 +470,7 @@ export const addGenAIAnnotations: {
    * })
    * ```
    *
-   * @category utilities
+   * @category utils
    * @since 4.0.0
    */
   (options: GenAITelemetryAttributeOptions): (span: Span) => void
@@ -499,7 +499,7 @@ export const addGenAIAnnotations: {
    * })
    * ```
    *
-   * @category utilities
+   * @category utils
    * @since 4.0.0
    */
   (span: Span, options: GenAITelemetryAttributeOptions): void

package/src/unstable/ai/Tokenizer.ts

@@ -80,8 +80,8 @@ export class Tokenizer extends Context.Service<Tokenizer, Service>()(
  *
  * ```ts
  * import { Effect } from "effect"
- * import type { Tokenizer } from "effect/unstable/ai"
  * import { Prompt } from "effect/unstable/ai"
+ * import type { Tokenizer } from "effect/unstable/ai"
  *
  * const customTokenizer: Tokenizer.Service = {
  *   tokenize: (input) =>

package/src/unstable/ai/Tool.ts

@@ -51,7 +51,7 @@ import type * as Prompt from "./Prompt.ts"
  * The tool type guards use this marker, together with more specific markers,
  * to distinguish user-defined, provider-defined, and dynamic tools.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/ai/Tool"
@@ -59,7 +59,7 @@ export const TypeId: TypeId = "~effect/ai/Tool"
 /**
  * Type-level representation of the Effect AI tool runtime type identifier.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/ai/Tool"
@@ -70,7 +70,7 @@ export type TypeId = "~effect/ai/Tool"
  * `isProviderDefined` uses this marker to distinguish tools that are built into
  * an AI provider from user-defined and dynamic tools.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const ProviderDefinedTypeId: ProviderDefinedTypeId = "~effect/ai/Tool/ProviderDefined"
@@ -79,7 +79,7 @@ export const ProviderDefinedTypeId: ProviderDefinedTypeId = "~effect/ai/Tool/Pro
  * Type-level representation of the provider-defined tool runtime type
  * identifier.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type ProviderDefinedTypeId = "~effect/ai/Tool/ProviderDefined"
@@ -90,7 +90,7 @@ export type ProviderDefinedTypeId = "~effect/ai/Tool/ProviderDefined"
  * `isDynamic` uses this marker to distinguish tools whose schema may be
  * provided at runtime from user-defined and provider-defined tools.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const DynamicTypeId: DynamicTypeId = "~effect/ai/Tool/Dynamic"
@@ -98,7 +98,7 @@ export const DynamicTypeId: DynamicTypeId = "~effect/ai/Tool/Dynamic"
 /**
  * Type-level representation of the dynamic tool runtime type identifier.
  *
- * @category type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type DynamicTypeId = "~effect/ai/Tool/Dynamic"
@@ -1520,7 +1520,7 @@ export const providerDefined = <
  * naming conflicts (i.e. `"web_search"`) to instead use custom names (i.e.
  * `"OpenAiWebSearch"`).
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export class NameMapper<Tools extends ReadonlyArray<Any>> {
@@ -1592,7 +1592,7 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
  * console.log(description) // "This is an example tool"
  * ```
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const getDescription = <Tool extends Any>(tool: Tool): string | undefined => {
@@ -1641,7 +1641,7 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
  * // }
  * ```
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
@@ -1661,7 +1661,7 @@ export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
  * `Schema.toJsonSchemaDocument` and any generated definitions are attached as
  * `$defs`.
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const getJsonSchemaFromSchema = <S extends Schema.Top>(schema: S, options?: {
@@ -1835,7 +1835,7 @@ export const Strict = Context.Reference<boolean | undefined>("effect/ai/Tool/Str
 /**
  * Returns the strict mode setting for a tool, or `undefined` if not set.
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const getStrictMode = <T extends Any>(tool: T): boolean | undefined => Context.get(tool.annotations, Strict)
@@ -1920,7 +1920,7 @@ function filter(obj: any) {
  * **Unsafe**: This function will throw an error if an insecure property is
  * found in the parsed JSON or if the provided JSON text is not parseable.
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const unsafeSecureJsonParse = (text: string): unknown => {
@@ -1940,6 +1940,7 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
  * It is a record schema with string keys and `never` values, so the generated
  * parameter schema accepts an empty object shape with no properties.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {}
@@ -1947,6 +1948,7 @@ export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never>
 /**
  * A schema for tools that accept no parameters.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const EmptyParams: EmptyParams = Schema.Record(Schema.String, Schema.Never)

package/src/unstable/ai/index.ts

@@ -282,11 +282,62 @@ export * as IdGenerator from "./IdGenerator.ts"
 export * as LanguageModel from "./LanguageModel.ts"
 
 /**
+ * The `McpSchema` module defines Effect Schema and RPC models for the Model
+ * Context Protocol (MCP). It provides the shared protocol vocabulary used by
+ * MCP clients and servers, including JSON-RPC request identifiers, metadata,
+ * capabilities, errors, resources, prompts, tools, logging, sampling,
+ * completions, roots, and elicitation.
+ *
+ * **Common tasks**
+ *
+ * - Describe MCP payloads with schemas such as {@link Resource}, {@link Tool},
+ *   {@link Prompt}, and {@link ContentBlock}
+ * - Build typed protocol handlers with request RPCs such as {@link Initialize},
+ *   {@link ListResources}, {@link ReadResource}, {@link ListTools}, and
+ *   {@link CallTool}
+ * - Work with protocol notifications such as
+ *   {@link ProgressNotification}, {@link ResourceUpdatedNotification}, and
+ *   {@link LoggingMessageNotification}
+ * - Use {@link ClientRpcs} and server RPC groups to derive encoded request,
+ *   notification, success, and failure message types
+ *
+ * **Gotchas**
+ *
+ * - MCP distinguishes absent fields from present fields whose value is
+ *   `undefined`; use {@link optional} and {@link optionalWithDefault} for
+ *   protocol fields so encoding omits undefined values consistently.
+ * - Capability objects are extensible. Known fields are modeled here, but
+ *   `experimental` and `extensions` allow implementations to advertise
+ *   additional protocol features.
+ *
  * @since 4.0.0
  */
 export * as McpSchema from "./McpSchema.ts"
 
 /**
+ * The `McpServer` module provides Effect services and layers for building
+ * Model Context Protocol servers. It keeps track of registered tools,
+ * resources, resource templates, prompts, completions, and server
+ * notifications, then exposes them through the MCP request handlers.
+ *
+ * **Common tasks**
+ *
+ * - Start a server over stdio with {@link layerStdio}
+ * - Register HTTP routes for an existing `HttpRouter` with {@link layerHttp}
+ * - Expose Effect AI toolkits as MCP tools with {@link registerToolkit}
+ * - Register resources, resource templates, and prompts with {@link resource}
+ *   and {@link prompt}
+ * - Ask the connected MCP client for structured input with {@link elicit}
+ *
+ * **Gotchas**
+ *
+ * - Registration helpers require an `McpServer` service, usually provided by
+ *   one of this module's layers.
+ * - HTTP clients must complete MCP initialization before other requests; the
+ *   server tracks initialized sessions with the `Mcp-Session-Id` header.
+ * - Resource template parameters are decoded with the schemas embedded in the
+ *   template literal.
+ *
  * @since 4.0.0
  */
 export * as McpServer from "./McpServer.ts"
@@ -302,8 +353,8 @@ export * as McpServer from "./McpServer.ts"
  * **Example** (Creating a provider-specific model)
  *
  * ```ts
- * import type { Layer } from "effect"
  * import { Effect } from "effect"
+ * import type { Layer } from "effect"
  * import { LanguageModel, Model } from "effect/unstable/ai"
  *
  * declare const myAnthropicLayer: Layer.Layer<LanguageModel.LanguageModel>
@@ -420,6 +471,18 @@ export * as Prompt from "./Prompt.ts"
 export * as Response from "./Response.ts"
 
 /**
+ * The `ResponseIdTracker` module provides a small service for reusing provider
+ * response IDs across incremental language model calls. It records which prompt
+ * message objects were sent for a provider response, then prepares a later
+ * prompt by returning the recognized `previousResponseId` together with only
+ * the new messages that should be sent.
+ *
+ * Use this when integrating providers that support continuing a conversation
+ * from a prior response ID instead of resending the entire prompt. The tracker
+ * is intentionally identity-based and mutable: it only recognizes the same
+ * message objects that were previously marked, and it clears its state when a
+ * prompt can no longer be matched safely.
+ *
  * @since 4.0.0
  */
 export * as ResponseIdTracker from "./ResponseIdTracker.ts"
@@ -540,10 +603,9 @@ export * as Tool from "./Tool.ts"
  * **Example** (Creating and implementing toolkits)
  *
  * ```ts
- * import { Effect, Schema } from "effect"
+ * import { Effect, Schema, Stream } from "effect"
  * import { Tool, Toolkit } from "effect/unstable/ai"
  *
- * // Create individual tools
  * const GetCurrentTime = Tool.make("GetCurrentTime", {
  *   description: "Get the current timestamp",
  *   success: Schema.Number
@@ -558,17 +620,29 @@ export * as Tool from "./Tool.ts"
  *   })
  * })
  *
- * // Create a toolkit with multiple tools
  * const MyToolkit = Toolkit.make(GetCurrentTime, GetWeather)
  *
  * const MyToolkitLayer = MyToolkit.toLayer({
- *   GetCurrentTime: () => Effect.succeed(Date.now()),
+ *   GetCurrentTime: () => Effect.succeed(1_704_067_200_000),
  *   GetWeather: ({ location }) =>
  *     Effect.succeed({
  *       temperature: 72,
- *       condition: "sunny"
+ *       condition: `sunny in ${location}`
  *     })
  * })
+ *
+ * const program = Effect.gen(function*() {
+ *   const toolkit = yield* MyToolkit
+ *   const stream = yield* toolkit.handle("GetWeather", {
+ *     location: "San Francisco"
+ *   })
+ *   const results = yield* Stream.runCollect(stream)
+ *
+ *   return Array.from(results, ({ result }) => result)
+ * }).pipe(Effect.provide(MyToolkitLayer))
+ *
+ * console.log(Effect.runSync(program))
+ * // [{ temperature: 72, condition: "sunny in San Francisco" }]
  * ```
  *
  * @since 4.0.0

package/src/unstable/cli/CliOutput.ts

@@ -69,8 +69,8 @@ export interface Formatter {
    *
    * ```ts
    * import { Option as O } from "effect"
-   * import type { HelpDoc } from "effect/unstable/cli"
    * import { CliOutput } from "effect/unstable/cli"
+   * import type { HelpDoc } from "effect/unstable/cli"
    *
    * const helpDoc: HelpDoc = {
    *   usage: "myapp [options] <file>",
@@ -111,7 +111,7 @@ export interface Formatter {
    * **Example** (Formatting CLI errors)
    *
    * ```ts
-   * import * as Data from "effect/Data"
+   * import { Data } from "effect"
    * import { CliOutput } from "effect/unstable/cli"
    *
    * class InvalidOption extends Data.TaggedError("InvalidOption")<{
@@ -134,7 +134,7 @@ export interface Formatter {
    * **Example** (Formatting error sections)
    *
    * ```ts
-   * import * as Data from "effect/Data"
+   * import { Data } from "effect"
    * import { CliOutput } from "effect/unstable/cli"
    *
    * class ValidationError extends Data.TaggedError("ValidationError")<{
@@ -217,7 +217,7 @@ export interface Formatter {
  * **Example** (Accessing the output formatter)
  *
  * ```ts
- * import * as Effect from "effect/Effect"
+ * import { Effect } from "effect"
  * import { CliOutput } from "effect/unstable/cli"
  *
  * // Access the formatter service
@@ -249,8 +249,7 @@ export const Formatter: Context.Reference<Formatter> = Context.Reference(
  * **Example** (Providing a custom formatter)
  *
  * ```ts
- * import * as Console from "effect/Console"
- * import * as Effect from "effect/Effect"
+ * import { Console, Effect } from "effect"
  * import { CliOutput } from "effect/unstable/cli"
  *
  * // Create a custom formatter without colors

package/src/unstable/cli/Command.ts

@@ -199,7 +199,7 @@ export declare namespace Command {
    *
    * ```ts
    * import { Argument, Flag } from "effect/unstable/cli"
-   * import type * as CliCommand from "effect/unstable/cli/Command"
+   * import type { Command as CliCommand } from "effect/unstable/cli"
    *
    * // Simple flat configuration
    * const simpleConfig: CliCommand.Command.Config = {
@@ -262,7 +262,7 @@ export declare namespace Command {
      *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
-     * import type * as CliCommand from "effect/unstable/cli/Command"
+     * import type { Command as CliCommand } from "effect/unstable/cli"
      *
      * const config = {
      *   name: Flag.string("name"),
@@ -431,7 +431,7 @@ export interface ParsedTokens {
 /**
  * Returns `true` if the provided value is a `Command`.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty(u, TypeId)

package/src/unstable/cli/Flag.ts

@@ -641,6 +641,30 @@ export const withMetavar: {
   <A>(self: Flag<A>, metavar: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, metavar: string) => Param.withMetavar(self, metavar))
 
+/**
+ * Hides a flag from generated help output and shell completions while keeping
+ * it fully parseable on the command line.
+ *
+ * Useful for experimental or internal flags that should be accepted but not
+ * advertised — for example, `--experimental-foo`, debug toggles, or escape
+ * hatches that are not yet committed to the public CLI surface.
+ *
+ * **Example** (Hiding a flag from help)
+ *
+ * ```ts
+ * import { Flag } from "effect/unstable/cli"
+ *
+ * // Flag still parses --experimental-foo, but it does not appear in --help.
+ * const experimental = Flag.boolean("experimental-foo").pipe(
+ *   Flag.withHidden
+ * )
+ * ```
+ *
+ * @category metadata
+ * @since 4.0.0
+ */
+export const withHidden = <A>(self: Flag<A>): Flag<A> => Param.withHidden(self)
+
 /**
  * Makes a flag optional, returning an Option type that can be None if not provided.
  *

package/src/unstable/cli/HelpDoc.ts

@@ -35,8 +35,8 @@ import type * as Option from "../../Option.ts"
  * **Example** (Defining command help documentation)
  *
  * ```ts
- * import { Option as O, Context } from "effect"
- * import type * as HelpDoc from "effect/unstable/cli/HelpDoc"
+ * import { Context, Option as O } from "effect"
+ * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const deployCommandHelp: HelpDoc.HelpDoc = {
  *   description: "Deploy your application to the cloud",
@@ -196,7 +196,7 @@ export interface FlagDoc {
  * **Example** (Documenting subcommands)
  *
  * ```ts
- * import { Option as O, Context } from "effect"
+ * import { Context, Option as O } from "effect"
  * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const deploySubcommand: HelpDoc.SubcommandDoc = {
@@ -276,7 +276,7 @@ export interface SubcommandGroupDoc {
  * **Example** (Documenting positional arguments)
  *
  * ```ts
- * import { Option as O, Context } from "effect"
+ * import { Context, Option as O } from "effect"
  * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const sourceArg: HelpDoc.ArgDoc = {