effect 4.0.0-beta.4 → 4.0.0-beta.41

package/src/unstable/ai/Tool.ts

@@ -257,7 +257,7 @@ export interface Tool<
    * instead of being provided when creating the tool call handler layer.
    */
   addDependency<Identifier, Service>(
-    tag: ServiceMap.Service<Identifier, Service>
+    tag: ServiceMap.Key<Identifier, Service>
   ): Tool<Name, Config, Identifier | Requirements>
 
   /**
@@ -311,7 +311,7 @@ export interface Tool<
   /**
    * Add an annotation to the tool.
    */
-  annotate<I, S>(tag: ServiceMap.Service<I, S>, value: S): Tool<Name, Config, Requirements>
+  annotate<I, S>(tag: ServiceMap.Key<I, S>, value: S): Tool<Name, Config, Requirements>
 
   /**
    * Add many annotations to the tool.
@@ -952,7 +952,7 @@ export type HandlerError<T> = T extends Tool<
   infer _Name,
   infer _Config,
   infer _Requirements
-> ? _Config["failureMode"] extends "error" ? _Config["failure"]["Type"] | AiError.AiError | AiError.AiErrorReason
+> ? _Config["failureMode"] extends "error" ? _Config["failure"]["Type"] | AiError.AiError
   : never
   : never
 
@@ -1006,7 +1006,7 @@ const Proto = {
   setFailure(this: Any, failureSchema: Schema.Top) {
     return userDefinedProto({ ...this, failureSchema })
   },
-  annotate<I, S>(this: Any, tag: ServiceMap.Service<I, S>, value: S) {
+  annotate<I, S>(this: Any, tag: ServiceMap.Key<I, S>, value: S) {
     return userDefinedProto({
       ...this,
       annotations: ServiceMap.add(this.annotations, tag, value)
@@ -1129,6 +1129,9 @@ const dynamicProto = <
  * can call. The tool definition includes parameter validation, success/failure
  * schemas, and optional service dependencies.
  *
+ * If a tool accepts no parameters but still needs an explicit empty object
+ * schema, use {@link EmptyParams}.
+ *
  * @example
  * ```ts
  * import { Schema } from "effect"
@@ -1146,11 +1149,11 @@ const dynamicProto = <
  */
 export const make = <
   const Name extends string,
-  Parameters extends Schema.Top = typeof Schema.Void,
+  Parameters extends Schema.Top = typeof EmptyParams,
   Success extends Schema.Top = typeof Schema.Void,
   Failure extends Schema.Top = typeof Schema.Never,
   Mode extends FailureMode | undefined = undefined,
-  Dependencies extends Array<ServiceMap.Service<any, any>> = []
+  Dependencies extends Array<ServiceMap.Key<any, any> | ServiceMap.Key<never, any>> = []
 >(name: Name, options?: {
   /**
    * An optional description explaining what the tool does.
@@ -1207,7 +1210,7 @@ export const make = <
   return userDefinedProto({
     name,
     description: options?.description,
-    parametersSchema: options?.parameters ?? Schema.Void,
+    parametersSchema: options?.parameters ?? EmptyParams,
     successSchema,
     failureSchema,
     failureMode: options?.failureMode ?? "error",
@@ -1622,15 +1625,6 @@ export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
 export const getJsonSchemaFromSchema = <S extends Schema.Top>(schema: S, options?: {
   readonly transformer?: CodecTransformer
 }): JsonSchema.JsonSchema => {
-  const props = AST.isObjects(schema.ast) ? schema.ast.propertySignatures : []
-  if (props.length === 0) {
-    return {
-      type: "object",
-      properties: {},
-      required: [],
-      additionalProperties: false
-    }
-  }
   if (Predicate.isNotUndefined(options?.transformer)) {
     return options.transformer(schema).jsonSchema
   }
@@ -1661,6 +1655,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.
  *
@@ -1860,3 +1869,20 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
     Error.stackTraceLimit = stackTraceLimit
   }
 }
+
+/**
+ * @since 4.0.0
+ */
+export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {}
+
+/**
+ * A schema for tools that accept no parameters.
+ *
+ * @since 4.0.0
+ */
+export const EmptyParams: EmptyParams = Schema.Record(Schema.String, Schema.Never)
+
+/** @internal */
+export function isEmptyParamsRecord(indexSignature: AST.IndexSignature): boolean {
+  return indexSignature.parameter === AST.string && AST.isNever(indexSignature.type)
+}

package/src/unstable/ai/Toolkit.ts

@@ -53,9 +53,7 @@ import type * as Scope from "../../Scope.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
 import * as Stream from "../../Stream.ts"
 import * as AiError from "./AiError.ts"
-import { CurrentCodecTransformer } from "./internal/codec-transformer.ts"
-import type { CodecTransformer } from "./LanguageModel.ts"
-import * as Tool from "./Tool.ts"
+import type * as Tool from "./Tool.ts"
 
 const TypeId = "~effect/ai/Toolkit" as const
 
@@ -298,24 +296,18 @@ const Proto = {
         readonly encodeResult: (u: unknown) => Effect.Effect<unknown, Schema.SchemaError>
       }>()
 
-      const getSchemas = (tool: Tool.Any, transformer: CodecTransformer) => {
+      const getSchemas = (tool: Tool.Any) => {
         let schemas = schemasCache.get(tool)
         if (Predicate.isUndefined(schemas)) {
           const handler = services.mapUnsafe.get(tool.id)! as Tool.Handler<any>
           const resultSchema = tool.failureMode === "return"
             ? Schema.Union([tool.successSchema, tool.failureSchema, AiError.AiError])
             : tool.successSchema
-          // Do not apply the codec transformation to provider defined tools,
-          // as these are defined internal to the Effect AI SDK and should
-          // already have valid schemas
-          const transformedResultSchema = Tool.isProviderDefined(tool)
-            ? resultSchema
-            : transformer(resultSchema).codec
           const decodeParameters = Schema.isSchema(tool.parametersSchema)
             ? Schema.decodeUnknownEffect(tool.parametersSchema) as any
             : (u: unknown) => Effect.succeed(u)
-          const decodeResult = Schema.decodeUnknownEffect(transformedResultSchema) as any
-          const encodeResult = Schema.encodeUnknownEffect(transformedResultSchema) as any
+          const decodeResult = Schema.decodeUnknownEffect(resultSchema) as any
+          const encodeResult = Schema.encodeUnknownEffect(resultSchema) as any
           schemas = {
             services: handler.services,
             handler: handler.handler,
@@ -349,8 +341,7 @@ const Proto = {
         }
 
         // Fetch cached schemas / handlers for the tool
-        const codecTransformer = yield* CurrentCodecTransformer
-        const schemas = getSchemas(tool, codecTransformer)
+        const schemas = getSchemas(tool)
 
         // Decode the tool call parameters which will be passed to the handler
         const decodedParams = yield* schemas.decodeParameters(params).pipe(

package/src/unstable/ai/index.ts

@@ -153,6 +153,24 @@ export * as AnthropicStructuredOutput from "./AnthropicStructuredOutput.ts"
  */
 export * as Chat from "./Chat.ts"
 
+/**
+ * The `EmbeddingModel` module provides provider-agnostic text embedding capabilities.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { EmbeddingModel } from "effect/unstable/ai"
+ *
+ * const program = Effect.gen(function*() {
+ *   const model = yield* EmbeddingModel.EmbeddingModel
+ *   return yield* model.embed("hello world")
+ * })
+ * ```
+ *
+ * @since 4.0.0
+ */
+export * as EmbeddingModel from "./EmbeddingModel.ts"
+
 /**
  * The `IdGenerator` module provides a pluggable system for generating unique identifiers
  * for tool calls and other items in the Effect AI SDKs.
@@ -280,7 +298,7 @@ export * as McpServer from "./McpServer.ts"
  *
  * declare const myAnthropicLayer: Layer.Layer<LanguageModel.LanguageModel>
  *
- * const anthropicModel = Model.make("anthropic", myAnthropicLayer)
+ * const anthropicModel = Model.make("anthropic", "claude-3-5-haiku", myAnthropicLayer)
  *
  * const program = Effect.gen(function*() {
  *   const response = yield* LanguageModel.generateText({
@@ -388,6 +406,11 @@ export * as Prompt from "./Prompt.ts"
  */
 export * as Response from "./Response.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as ResponseIdTracker from "./ResponseIdTracker.ts"
+
 /**
  * The `Telemetry` module provides OpenTelemetry integration for operations
  * performed against a large language model provider by defining telemetry

package/src/unstable/ai/internal/codec-transformer.ts

@@ -1,5 +1,4 @@
 import * as Schema from "../../../Schema.ts"
-import * as ServiceMap from "../../../ServiceMap.ts"
 import type { CodecTransformer } from "../LanguageModel.ts"
 
 /** @internal */
@@ -11,9 +10,3 @@ export const defaultCodecTransformer: CodecTransformer = (codec) => {
   }
   return { codec, jsonSchema }
 }
-
-/** @internal */
-export const CurrentCodecTransformer = ServiceMap.Reference(
-  "effect/unstable/ai/CodecTransformer",
-  { defaultValue: (): CodecTransformer => defaultCodecTransformer }
-)

package/src/unstable/cli/Argument.ts

@@ -226,9 +226,7 @@ export const fileParse = (
  *   host: Schema.String
  * })
  *
- * const JsonConfigSchema = Schema.fromJsonString(ConfigSchema)
- *
- * const config = Argument.fileSchema("config", JsonConfigSchema)
+ * const config = Argument.fileSchema("config", ConfigSchema)
  * ```
  *
  * @since 4.0.0
@@ -236,7 +234,7 @@ export const fileParse = (
  */
 export const fileSchema = <A>(
   name: string,
-  schema: Schema.Codec<A, string>,
+  schema: Schema.Decoder<A>,
   options?: Primitive.FileSchemaOptions | undefined
 ): Argument<A> => Param.fileSchema(Param.argumentKind, name, schema, options)
 

package/src/unstable/cli/CliError.ts

@@ -2,6 +2,7 @@
  * @since 4.0.0
  */
 import * as Predicate from "../../Predicate.ts"
+import * as Runtime from "../../Runtime.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
@@ -107,7 +108,7 @@ export type CliError =
  * // In CLI parsing context
  * const parseCommand = Effect.gen(function*() {
  *   // If parsing encounters unknown flag
- *   return yield* Effect.fail(unrecognizedError)
+ *   return yield* unrecognizedError
  * })
  * ```
  *
@@ -200,7 +201,7 @@ export class DuplicateOption extends Schema.ErrorClass(`${TypeId}/DuplicateOptio
  *   Effect.gen(function*() {
  *     const apiKey = options["api-key"]
  *     if (!apiKey) {
- *       return yield* Effect.fail(missingOptionError)
+ *       return yield* missingOptionError
  *     }
  *     return apiKey
  *   })
@@ -245,7 +246,7 @@ export class MissingOption extends Schema.ErrorClass(`${TypeId}/MissingOption`)(
  * const parseArguments = (args: Array<string>) =>
  *   Effect.gen(function*() {
  *     if (args.length === 0) {
- *       return yield* Effect.fail(missingArgError)
+ *       return yield* missingArgError
  *     }
  *     return args[0]
  *   })
@@ -353,7 +354,7 @@ export class InvalidValue extends Schema.ErrorClass(`${TypeId}/InvalidValue`)({
  *   Effect.gen(function*() {
  *     const validCommands = ["deploy", "destroy", "status"]
  *     if (!validCommands.includes(subcommand)) {
- *       return yield* Effect.fail(unknownSubcommandError)
+ *       return yield* unknownSubcommandError
  *     }
  *     return subcommand
  *   })
@@ -386,61 +387,6 @@ export class UnknownSubcommand extends Schema.ErrorClass(`${TypeId}/UnknownSubco
   }
 }
 
-/**
- * Control flow indicator when help is requested via --help flag.
- * This is not an error but uses the error channel for control flow.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- * import { CliError } from "effect/unstable/cli"
- *
- * const showHelpIndicator = new CliError.ShowHelp({
- *   commandPath: ["myapp", "deploy", "production"]
- * })
- *
- * console.log(showHelpIndicator.message)
- * // "Help requested"
- *
- * // In help flag handling
- * const handleHelpFlag = (hasHelpFlag: boolean) =>
- *   Effect.gen(function*() {
- *     if (hasHelpFlag) {
- *       return yield* Effect.fail(showHelpIndicator)
- *     }
- *     return "continuing with command"
- *   })
- *
- * // In error handling
- * const handleCliErrors = (error: CliError.CliError): void => {
- *   if (error._tag === "ShowHelp") {
- *     // Display help for the command path
- *     console.log(`Displaying help for: ${error.commandPath.join(" ")}`)
- *   }
- *   // Handle other errors...
- * }
- * ```
- *
- * @since 4.0.0
- * @category models
- */
-export class ShowHelp extends Schema.ErrorClass(`${TypeId}/ShowHelp`)({
-  _tag: Schema.tag("ShowHelp"),
-  commandPath: Schema.Array(Schema.String)
-}) {
-  /**
-   * @since 4.0.0
-   */
-  readonly [TypeId] = TypeId
-
-  /**
-   * @since 4.0.0
-   */
-  override get message() {
-    return "Help requested"
-  }
-}
-
 /**
  * Wrapper for user (handler) errors to unify under CLI error channel when desired.
  *
@@ -485,3 +431,45 @@ export class UserError extends Schema.ErrorClass(`${TypeId}/UserError`)({
    */
   readonly [TypeId] = TypeId
 }
+
+const NonShowHelpErrors: Schema.Union<
+  readonly [
+    typeof UnrecognizedOption,
+    typeof DuplicateOption,
+    typeof MissingOption,
+    typeof MissingArgument,
+    typeof InvalidValue,
+    typeof UnknownSubcommand,
+    typeof UserError
+  ]
+> = Schema.Union([
+  UnrecognizedOption,
+  DuplicateOption,
+  MissingOption,
+  MissingArgument,
+  InvalidValue,
+  UnknownSubcommand,
+  UserError
+])
+
+/**
+ * Control flow indicator when help is requested via --help flag.
+ * This is not an error but uses the error channel for control flow.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export class ShowHelp extends Schema.ErrorClass(`${TypeId}/ShowHelp`)({
+  _tag: Schema.tag("ShowHelp"),
+  commandPath: Schema.Array(Schema.String),
+  errors: Schema.Array(NonShowHelpErrors)
+}) {
+  readonly [TypeId] = TypeId
+
+  override readonly [Runtime.errorExitCode] = this.errors.length ? 1 : 0
+  override readonly [Runtime.errorReported] = false
+
+  override get message() {
+    return "Help requested"
+  }
+}

package/src/unstable/cli/CliOutput.ts

@@ -3,6 +3,7 @@
  */
 
 import * as Layer from "../../Layer.ts"
+import * as Option from "../../Option.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
 import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
@@ -44,6 +45,7 @@ export interface Formatter {
    *
    * @example
    * ```ts
+   * import { Option as O } from "effect"
    * import type { HelpDoc } from "effect/unstable/cli"
    * import { CliOutput } from "effect/unstable/cli"
    *
@@ -55,7 +57,7 @@ export interface Formatter {
    *       name: "verbose",
    *       aliases: ["-v"],
    *       type: "boolean",
-   *       description: "Enable verbose output",
+   *       description: O.some("Enable verbose output"),
    *       required: false
    *     }
    *   ],
@@ -63,7 +65,7 @@ export interface Formatter {
    *     {
    *       name: "file",
    *       type: "string",
-   *       description: "Input file to process",
+   *       description: O.some("Input file to process"),
    *       required: true,
    *       variadic: false
    *     }
@@ -404,11 +406,14 @@ interface Row {
  * Renders a table with aligned columns.
  * @internal
  */
-const renderTable = (rows: ReadonlyArray<Row>, widthCap: number) => {
-  const col = Math.min(Math.max(...rows.map((r) => visualLength(r.left))) + 4, widthCap)
+const renderTable = (rows: ReadonlyArray<Row>, widthCap?: number) => {
+  const maxColumn = Math.max(...rows.map((r) => visualLength(r.left))) + 4
+  const col = widthCap === undefined ? maxColumn : Math.min(maxColumn, widthCap)
   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
@@ -457,7 +462,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
       const nameType = `${coloredName} ${coloredType}`
 
       const optionalSuffix = arg.required ? "" : colors.dim(" (optional)")
-      const description = (arg.description ?? "") + optionalSuffix
+      const description = Option.getOrElse(arg.description, () => "") + optionalSuffix
 
       return {
         left: nameType,
@@ -489,24 +494,91 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
 
       return {
         left: namesPart + typePart,
-        right: flag.description ?? ""
+        right: Option.getOrElse(flag.description, () => "")
       }
     })
 
-    sections.push(renderTable(flagRows, 30))
+    sections.push(renderTable(flagRows))
+    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: Option.getOrElse(flag.description, () => "")
+      }
+    })
+
+    sections.push(renderTable(globalFlagRows))
     sections.push("")
   }
 
   // Subcommands section
   if (doc.subcommands && doc.subcommands.length > 0) {
-    sections.push(colors.bold("SUBCOMMANDS"))
+    const ungrouped = doc.subcommands.find((group) => group.group === undefined)
+
+    if (ungrouped) {
+      sections.push(colors.bold("SUBCOMMANDS"))
+      sections.push(renderTable(
+        ungrouped.commands.map((sub) => ({
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      if (doc.subcommands.length > 1) {
+        sections.push("")
+      }
+    }
 
-    const subcommandRows: Array<Row> = doc.subcommands.map((sub) => ({
-      left: colors.cyan(sub.name),
-      right: sub.description
-    }))
+    for (const group of doc.subcommands) {
+      if (group.group === undefined) continue
+      sections.push(colors.bold(`${group.group}:`))
+      sections.push(renderTable(
+        group.commands.map((sub) => ({
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      sections.push("")
+    }
+  }
 
-    sections.push(renderTable(subcommandRows, 20))
+  // Examples section
+  if (doc.examples && doc.examples.length > 0) {
+    sections.push(colors.bold("EXAMPLES"))
+
+    let first = true
+    let previousHadDescription = false
+    for (const example of doc.examples) {
+      if (example.description) {
+        if (!first) sections.push("")
+        sections.push(`  ${colors.dim(`# ${example.description}`)}`)
+      } else if (previousHadDescription) {
+        sections.push("")
+      }
+      sections.push(`  ${colors.cyan(example.command)}`)
+      first = false
+      previousHadDescription = !!example.description
+    }
     sections.push("")
   }