effect 4.0.0-rc.112 → 4.0.0-rc.113

package/src/unstable/ai/Tool.ts

@@ -22,7 +22,7 @@ import * as Schema from "../../Schema.ts"
 import * as SchemaAST from "../../SchemaAST.ts"
 import type * as Struct from "../../Struct.ts"
 import type * as Types from "../../Types.ts"
-import type * as AiError from "./AiError.ts"
+import * as AiError from "./AiError.ts"
 import type { CodecTransformer } from "./LanguageModel.ts"
 import type * as Prompt from "./Prompt.ts"
 
@@ -818,9 +818,8 @@ export type FailureEncoded<T> = T extends Tool<
   : never
 
 /**
- * A utility type for the actual failure value that can appear in tool results.
- * When `failureMode` is `"return"`, this includes both user-defined failures
- * and `AiError`.
+ * A tool's failure type, plus {@link ExecutionFailure} in both failure modes
+ * and `AiError` in `"return"` mode.
  *
  * @category utility types
  * @since 4.0.0
@@ -829,8 +828,11 @@ export type FailureResult<T> = T extends Tool<
   infer _Name,
   infer _Config,
   infer _Requirements
-> ? _Config["failureMode"] extends "return" ? _Config["failure"]["Type"] | AiError.AiError
-  : _Config["failure"]["Type"]
+> ? _Config["failureMode"] extends "return" ?
+      | _Config["failure"]["Type"]
+      | typeof ExecutionFailure.Type
+      | AiError.AiError
+  : _Config["failure"]["Type"] | typeof ExecutionFailure.Type
   : never
 
 /**
@@ -843,47 +845,28 @@ export type FailureResultEncoded<T> = T extends Tool<
   infer _Name,
   infer _Config,
   infer _Requirements
-> ? _Config["failureMode"] extends "return" ? _Config["failure"]["Encoded"] | AiError.AiErrorEncoded
-  : _Config["failure"]["Encoded"]
+> ? _Config["failureMode"] extends "return" ?
+      | _Config["failure"]["Encoded"]
+      | typeof ExecutionFailure.Encoded
+      | AiError.AiErrorEncoded
+  : _Config["failure"]["Encoded"] | typeof ExecutionFailure.Encoded
   : never
 
 /**
- * A utility type to extract the type of the tool call result whether it
- * succeeds or fails.
- *
- * **Details**
- *
- * When `failureMode` is `"return"`, the result may also be an `AiError`.
+ * A tool's success or {@link FailureResult} type.
  *
  * @category utility types
  * @since 4.0.0
  */
-export type Result<T> = T extends Tool<
-  infer _Name,
-  infer _Config,
-  infer _Requirements
-> ? _Config["failureMode"] extends "return" ? Success<T> | Failure<T> | AiError.AiError
-  : Success<T> | Failure<T>
-  : never
+export type Result<T> = Success<T> | FailureResult<T>
 
 /**
- * A utility type to extract the encoded type of the tool call result whether
- * it succeeds or fails.
- *
- * **Details**
- *
- * When `failureMode` is `"return"`, the result may also be an encoded `AiError`.
+ * The encoded form of {@link Result}.
  *
  * @category utility types
  * @since 4.0.0
  */
-export type ResultEncoded<T> = T extends Tool<
-  infer _Name,
-  infer _Config,
-  infer _Requirements
-> ? _Config["failureMode"] extends "return" ? SuccessEncoded<T> | FailureEncoded<T> | AiError.AiErrorEncoded
-  : SuccessEncoded<T> | FailureEncoded<T>
-  : never
+export type ResultEncoded<T> = SuccessEncoded<T> | FailureResultEncoded<T>
 
 /**
  * A utility type to extract the requirements of a `Tool` call handler.
@@ -932,6 +915,19 @@ export type ResultDecodingServices<T> = T extends Tool<
 > ? _Config["success"]["DecodingServices"] | _Config["failure"]["DecodingServices"]
   : never
 
+/**
+ * Extracts the services required to encode tool parameters.
+ *
+ * @category utility types
+ * @since 4.0.0
+ */
+export type ParametersEncodingServices<T> = T extends Tool<
+  infer _Name,
+  infer _Config,
+  infer _Requirements
+> ? _Config["parameters"]["EncodingServices"]
+  : never
+
 /**
  * Represents an `Tool` that has been implemented within the application.
  *
@@ -1051,7 +1047,7 @@ const Proto = {
     return clone(this)
   },
   setParameters(this: Any, parametersSchema: Schema.Constraint) {
-    return clone(this, { parametersSchema })
+    return clone(this, { parametersSchema, jsonSchema: undefined })
   },
   setSuccess(this: Any, successSchema: Schema.Constraint) {
     return clone(this, { successSchema })
@@ -2039,6 +2035,33 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
   }
 }
 
+/**
+ * Schema for denied or interrupted tool calls.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export const ExecutionFailure = Schema.Struct({
+  type: Schema.Literals(["execution-denied", "execution-interrupted"]),
+  reason: Schema.String
+}).annotate({ identifier: "ToolExecutionFailure" })
+
+/**
+ * Returns the failure schema shared by `Toolkit` and `Response`.
+ *
+ * **Details**
+ *
+ * `AiError` comes first to restore error instances. The user schema precedes
+ * {@link ExecutionFailure} to preserve user fields.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export const failureResultSchema = <T extends Any>(
+  tool: T
+): Schema.Union<readonly [typeof AiError.AiError, T["failureSchema"], typeof ExecutionFailure]> =>
+  Schema.Union([AiError.AiError, tool.failureSchema, ExecutionFailure])
+
 /**
  * Type of the `EmptyParams` schema used for tools with no parameters.
  *

package/src/unstable/ai/Toolkit.ts

@@ -19,11 +19,12 @@ import * as InternalRecord from "../../internal/record.ts"
 import * as Layer from "../../Layer.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Queue from "../../Queue.ts"
+import * as Result from "../../Result.ts"
 import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
 import * as Stream from "../../Stream.ts"
 import * as AiError from "./AiError.ts"
-import type * as Tool from "./Tool.ts"
+import * as Tool from "./Tool.ts"
 
 const TypeId = "~effect/ai/Toolkit" as const
 
@@ -242,27 +243,23 @@ const Proto = {
         readonly context: Context.Context<never>
         readonly handler: Tool.Handler<any>["handler"]
         readonly decodeParameters: (u: unknown) => Effect.Effect<unknown, Schema.SchemaError>
-        readonly decodeResult: (u: unknown) => Effect.Effect<unknown, Schema.SchemaError>
-        readonly encodeResult: (u: unknown) => Effect.Effect<unknown, Schema.SchemaError>
+        readonly encodeResult: (u: unknown, isFailure: boolean) => Effect.Effect<unknown, Schema.SchemaError>
       }>()
 
       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
           const decodeParameters = Schema.isSchema(tool.parametersSchema)
             ? Schema.decodeUnknownEffect(tool.parametersSchema) as any
             : (u: unknown) => Effect.succeed(u)
-          const decodeResult = Schema.decodeUnknownEffect(resultSchema) as any
-          const encodeResult = Schema.encodeUnknownEffect(resultSchema) as any
+          const encodeSuccess = Schema.encodeUnknownEffect(tool.successSchema) as any
+          const encodeFailure = Schema.encodeUnknownEffect(Tool.failureResultSchema(tool)) as any
+          const encodeResult = (u: unknown, isFailure: boolean) => isFailure ? encodeFailure(u) : encodeSuccess(u)
           schemas = {
             context: handler.context,
             handler: handler.handler,
             decodeParameters,
-            decodeResult,
             encodeResult
           }
           schemasCache.set(tool, schemas)
@@ -293,20 +290,44 @@ const Proto = {
         // Fetch cached schemas / handlers for the tool
         const schemas = getSchemas(tool)
 
-        // Decode the tool call parameters which will be passed to the handler
-        const decodedParams = yield* schemas.decodeParameters(params).pipe(
-          Effect.mapError((cause) =>
-            AiError.make({
-              module: "Toolkit",
-              method: `${name}.handle`,
-              reason: new AiError.ToolParameterValidationError({
-                toolName: name,
-                toolParams: params,
-                description: cause.message
+        const encodeResult = (result: any, isFailure: boolean) =>
+          schemas.encodeResult(result, isFailure).pipe(
+            Effect.mapError((cause) =>
+              AiError.make({
+                module: "Toolkit",
+                method: `${name}.handle`,
+                reason: new AiError.ToolResultEncodingError({
+                  toolName: name,
+                  toolResult: result,
+                  description: cause.message
+                })
               })
-            })
+            )
           )
-        )
+
+        const decodedParamsResult = yield* Effect.result(schemas.decodeParameters(params))
+        if (Result.isFailure(decodedParamsResult)) {
+          const error = AiError.make({
+            module: "Toolkit",
+            method: `${name}.handle`,
+            reason: new AiError.ToolParameterValidationError({
+              toolName: name,
+              description: decodedParamsResult.failure.message
+            })
+          })
+          if (tool.failureMode === "error") {
+            return yield* error
+          }
+          return Stream.fromEffect(
+            Effect.map(encodeResult(error, true), (encodedResult) => ({
+              result: error,
+              isFailure: true,
+              preliminary: false,
+              encodedResult
+            }))
+          ) satisfies Stream.Stream<Tool.HandlerResult<any>, any>
+        }
+        const decodedParams = decodedParamsResult.success
 
         // Setup the handler context
         const queue = yield* Queue.make<{
@@ -334,21 +355,6 @@ const Proto = {
           Effect.forkChild
         )
 
-        const encodeResult = (result: any) =>
-          schemas.encodeResult(result).pipe(
-            Effect.mapError((cause) =>
-              AiError.make({
-                module: "Toolkit",
-                method: `${name}.handle`,
-                reason: new AiError.ToolResultEncodingError({
-                  toolName: name,
-                  toolResult: result,
-                  description: cause.message
-                })
-              })
-            )
-          )
-
         const normalizeError = (error: unknown) => {
           // Schema errors indicate handler returned invalid data
           const normalizedError = Schema.isSchemaError(error)
@@ -380,7 +386,7 @@ const Proto = {
               : Stream.succeed({ result: normalizedError, isFailure: true, preliminary: false })
           }),
           Stream.mapEffect(Effect.fnUntraced(function*(output) {
-            const encodedResult = yield* encodeResult(output.result)
+            const encodedResult = yield* encodeResult(output.result, output.isFailure)
             return { ...output, encodedResult }
           })),
           Stream.onEnd(Fiber.interrupt(fiber))

package/src/unstable/ai/internal/structured-output.ts

@@ -64,11 +64,11 @@ function transform(root: SchemaAST.AST): SchemaAST.AST {
       case "Union": {
         const types = SchemaAST.mapOrSame(ast.types, recur)
         const checks = prepareChecks(ast.checks)
-        const mode = ast.mode === "oneOf" ? "anyOf" : ast.mode
-        if (types === ast.types && checks === ast.checks && mode === ast.mode) return ast
+        const options = ast.options?.mode === "oneOf" ? { ...ast.options, mode: "anyOf" as const } : ast.options
+        if (types === ast.types && checks === ast.checks && options === ast.options) return ast
         return new SchemaAST.Union(
           types,
-          mode,
+          options,
           ast.annotations,
           checks,
           ast.encoding,
@@ -254,7 +254,7 @@ function objectToEntries(
 function unionOrSingle(types: ReadonlyArray<SchemaAST.AST>): SchemaAST.AST {
   if (types.length === 1) return types[0]
   const unique = Array.from(new Set(types))
-  return unique.length === 1 ? unique[0] : new SchemaAST.Union(unique, "anyOf")
+  return unique.length === 1 ? unique[0] : new SchemaAST.Union(unique)
 }
 
 function combineChecks(
@@ -300,7 +300,7 @@ function compilerAnnotations(
 
 function optionalToNullable(type: SchemaAST.AST): SchemaAST.AST {
   return SchemaAST.decodeTo(
-    new SchemaAST.Union([type, SchemaAST.null], "anyOf"),
+    new SchemaAST.Union([type, SchemaAST.null]),
     SchemaAST.optionalKey(type),
     SchemaTransformation.transformOptional({
       decode: Option.filter(Predicate.isNotNull),