effect 4.0.0-beta.101 → 4.0.0-beta.102

package/src/unstable/ai/Response.ts

@@ -2135,7 +2135,7 @@ export const HttpRequestDetails = Schema.Struct({
   method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]),
   url: Schema.String,
   urlParams: Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
-  hash: Schema.UndefinedOr(Schema.String),
+  hash: Schema.optional(Schema.String),
   headers: Schema.Record(
     Schema.String,
     Schema.Union([
@@ -2172,7 +2172,7 @@ export const HttpRequestDetails = Schema.Struct({
  * @since 4.0.0
  */
 export const HttpResponseDetails = Schema.Struct({
-  status: Schema.Number,
+  status: Schema.Int,
   headers: Schema.Record(
     Schema.String,
     Schema.Union([
@@ -2213,19 +2213,19 @@ export interface ResponseMetadataPart extends BasePart<"response-metadata", Resp
   /**
    * Optional unique identifier for this specific response.
    */
-  readonly id: string | undefined
+  readonly id?: string | undefined
   /**
    * Optional identifier of the AI model that generated the response.
    */
-  readonly modelId: string | undefined
+  readonly modelId?: string | undefined
   /**
    * Optional timestamp when the response was generated.
    */
-  readonly timestamp: DateTime.Utc | undefined
+  readonly timestamp?: DateTime.Utc | undefined
   /**
    * Optional HTTP request details for the request made to the AI provider.
    */
-  readonly request: typeof HttpRequestDetails.Type | undefined
+  readonly request?: typeof HttpRequestDetails.Type | undefined
 }
 
 /**
@@ -2272,10 +2272,10 @@ export interface ResponseMetadataPartMetadata extends ProviderMetadata {}
  */
 export const ResponseMetadataPart: Schema.Struct<{
   readonly type: Schema.tag<"response-metadata">
-  readonly id: Schema.UndefinedOr<Schema.String>
-  readonly modelId: Schema.UndefinedOr<Schema.String>
-  readonly timestamp: Schema.UndefinedOr<Schema.DateTimeUtcFromString>
-  readonly request: Schema.UndefinedOr<typeof HttpRequestDetails>
+  readonly id: Schema.optional<Schema.String>
+  readonly modelId: Schema.optional<Schema.String>
+  readonly timestamp: Schema.optional<Schema.DateTimeUtcFromString>
+  readonly request: Schema.optional<typeof HttpRequestDetails>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
     Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
@@ -2283,10 +2283,10 @@ export const ResponseMetadataPart: Schema.Struct<{
 }> = Schema.Struct({
   ...BasePart.fields,
   type: Schema.tag("response-metadata"),
-  id: Schema.UndefinedOr(Schema.String),
-  modelId: Schema.UndefinedOr(Schema.String),
-  timestamp: Schema.UndefinedOr(Schema.DateTimeUtcFromString),
-  request: Schema.UndefinedOr(HttpRequestDetails)
+  id: Schema.optional(Schema.String),
+  modelId: Schema.optional(Schema.String),
+  timestamp: Schema.optional(Schema.DateTimeUtcFromString),
+  request: Schema.optional(HttpRequestDetails)
 }).annotate({ identifier: "ResponseMetadataPart" }) satisfies Schema.Codec<
   ResponseMetadataPart,
   ResponseMetadataPartEncoded
@@ -2368,19 +2368,19 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
     /**
      * The number of non-cached input (i.e. prompt) tokens used.
      */
-    uncached: Schema.UndefinedOr(Schema.Number),
+    uncached: Schema.optional(Schema.Int),
     /**
      * The total of number of input (i.e. prompt) tokens used.
      */
-    total: Schema.UndefinedOr(Schema.Number),
+    total: Schema.optional(Schema.Int),
     /**
      * The number of cached input (i.e. prompt) tokens read.
      */
-    cacheRead: Schema.UndefinedOr(Schema.Number),
+    cacheRead: Schema.optional(Schema.Int),
     /**
      * The number of cached input (i.e. prompt) tokens written.
      */
-    cacheWrite: Schema.UndefinedOr(Schema.Number)
+    cacheWrite: Schema.optional(Schema.Int)
   }),
   /**
    * Information about the output (i.e. response) tokens used.
@@ -2389,15 +2389,15 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
     /**
      * The total of number of output (i.e. response) tokens used.
      */
-    total: Schema.UndefinedOr(Schema.Number),
+    total: Schema.optional(Schema.Int),
     /**
      * The number of text tokens used.
      */
-    text: Schema.UndefinedOr(Schema.Number),
+    text: Schema.optional(Schema.Int),
     /**
      * The number of reasoning tokens used.
      */
-    reasoning: Schema.UndefinedOr(Schema.Number)
+    reasoning: Schema.optional(Schema.Int)
   })
 }) {}
 
@@ -2443,7 +2443,7 @@ export interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
   /**
    * Optional HTTP response details from the AI provider.
    */
-  readonly response: typeof HttpResponseDetails.Type | undefined
+  readonly response?: typeof HttpResponseDetails.Type | undefined
 }
 
 /**
@@ -2500,7 +2500,7 @@ export const FinishPart: Schema.Struct<{
     "unknown"
   ]>
   readonly usage: typeof Usage
-  readonly response: Schema.UndefinedOr<typeof HttpResponseDetails>
+  readonly response: Schema.optional<typeof HttpResponseDetails>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
     Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
@@ -2510,7 +2510,7 @@ export const FinishPart: Schema.Struct<{
   type: Schema.tag("finish"),
   reason: FinishReason,
   usage: Usage,
-  response: Schema.UndefinedOr(HttpResponseDetails)
+  response: Schema.optional(HttpResponseDetails)
 }).annotate({ identifier: "FinishPart" }) satisfies Schema.Codec<FinishPart, FinishPartEncoded>
 
 // =============================================================================

package/src/unstable/ai/Tool.ts

@@ -273,6 +273,13 @@ export interface Tool<
    */
   readonly needsApproval?: boolean | NeedsApprovalFunction<any> | undefined
 
+  /**
+   * Set whether user approval is required before executing this tool.
+   */
+  setNeedsApproval(
+    needsApproval: NeedsApproval<Config["parameters"]>
+  ): Tool<Name, Config, Requirements>
+
   /**
    * Adds a _request-level_ dependency which must be provided before the tool
    * call handler can be executed.
@@ -1051,6 +1058,9 @@ const Proto = {
   setFailure(this: Any, failureSchema: Schema.Constraint) {
     return clone(this, { failureSchema })
   },
+  setNeedsApproval(this: Any, needsApproval: NeedsApproval<any>) {
+    return clone(this, { needsApproval })
+  },
   annotate<I, S>(this: Any, tag: Context.Key<I, S>, value: S) {
     return clone(this, { annotations: Context.add(this.annotations, tag, value) })
   },
@@ -1707,10 +1717,18 @@ export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
 export const getJsonSchemaFromSchema = <S extends Schema.Constraint>(schema: S, options?: {
   readonly transformer?: CodecTransformer
 }): JsonSchema.JsonSchema => {
+  return getJsonSchemaFromSchemaWith(schema, Schema.toJsonSchemaDocument, options)
+}
+
+const getJsonSchemaFromSchemaWith = <S extends Schema.Constraint>(
+  schema: S,
+  toJsonSchemaDocument: (schema: Schema.Constraint) => JsonSchema.Document<"draft-2020-12">,
+  options?: { readonly transformer?: CodecTransformer }
+): JsonSchema.JsonSchema => {
   if (Predicate.isNotUndefined(options?.transformer)) {
     return options.transformer(schema).jsonSchema
   }
-  const document = Schema.toJsonSchemaDocument(schema)
+  const document = toJsonSchemaDocument(schema)
   if (Object.keys(document.definitions).length > 0) {
     document.schema.$defs = document.definitions
   }
@@ -1956,13 +1974,13 @@ function filter(obj: any) {
     next = []
 
     for (const node of nodes) {
-      if (Object.prototype.hasOwnProperty.call(node, "__proto__")) {
+      if (Object.hasOwn(node, "__proto__")) {
         throw new SyntaxError("Object contains forbidden prototype property")
       }
 
       if (
-        Object.prototype.hasOwnProperty.call(node, "constructor") &&
-        Object.prototype.hasOwnProperty.call(node.constructor, "prototype")
+        Object.hasOwn(node, "constructor") &&
+        Object.hasOwn(node.constructor, "prototype")
       ) {
         throw new SyntaxError("Object contains forbidden prototype property")
       }

package/src/unstable/ai/Toolkit.ts

@@ -15,6 +15,7 @@ import * as Effect from "../../Effect.ts"
 import * as Effectable from "../../Effectable.ts"
 import * as Fiber from "../../Fiber.ts"
 import { identity } from "../../Function.ts"
+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"
@@ -105,6 +106,10 @@ export interface Toolkit<in out Tools extends Record<string, Tool.Any>> extends
  * @since 4.0.0
  */
 export interface HandlerContext<Tool extends Tool.Any> {
+  /**
+   * The unique identifier of the tool call, when available.
+   */
+  readonly toolCallId?: string | undefined
   /**
    * Emit a preliminary result during long-running tool calls.
    *
@@ -199,7 +204,11 @@ export interface WithHandler<in out Tools extends Record<string, Tool.Any>> {
     /**
      * Parameters to pass to the tool handler.
      */
-    params: Tool.Parameters<Tools[Name]>
+    params: Tool.Parameters<Tools[Name]>,
+    /**
+     * The unique identifier of the tool call.
+     */
+    toolCallId?: string
   ) => Effect.Effect<
     Stream.Stream<
       Tool.HandlerResult<Tools[Name]>,
@@ -257,8 +266,8 @@ const Proto = {
         return schemas
       }
 
-      const handle = Effect.fnUntraced(function*(name: string, params: unknown) {
-        const tool = tools[name]
+      const handle = Effect.fnUntraced(function*(name: string, params: unknown, toolCallId?: string) {
+        const tool = Object.hasOwn(tools, name) ? tools[name] : undefined
 
         yield* Effect.annotateCurrentSpan({
           tool: name,
@@ -302,6 +311,7 @@ const Proto = {
           readonly preliminary: boolean
         }, Cause.Done>()
         const context: HandlerContext<any> = {
+          toolCallId,
           preliminary: (result) =>
             Effect.asVoid(Queue.offer(queue, {
               result,
@@ -390,8 +400,10 @@ const Proto = {
       const handlers = Effect.isEffect(build) ? yield* build : build
       const context = new Map<string, unknown>()
       for (const [name, handler] of Object.entries(handlers)) {
-        const tool = this.tools[name]!
-        context.set(tool.id, { name, handler, context: services })
+        const tool = Object.hasOwn(this.tools, name) ? this.tools[name] : undefined
+        if (tool !== undefined) {
+          context.set(tool.id, { name, handler, context: services })
+        }
       }
       return Context.makeUnsafe(context)
     })
@@ -418,7 +430,7 @@ const resolveInput = <Tools extends ReadonlyArray<Tool.Any>>(
 ): Record<string, Tools[number]> => {
   const output = {} as Record<string, Tools[number]>
   for (const tool of tools) {
-    output[tool.name] = tool
+    InternalRecord.assignProperty(output, tool.name, tool)
   }
   return output
 }
@@ -547,7 +559,7 @@ export const merge = <const Toolkits extends ReadonlyArray<Any>>(
   const tools = {} as Record<string, any>
   for (const toolkit of toolkits) {
     for (const [name, tool] of Object.entries(toolkit.tools)) {
-      tools[name] = tool
+      InternalRecord.assignProperty(tools, name, tool)
     }
   }
   return makeProto(tools) as any

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

@@ -2,12 +2,18 @@ import * as JsonSchema from "../../../JsonSchema.ts"
 import * as Schema from "../../../Schema.ts"
 import type { CodecTransformer } from "../LanguageModel.ts"
 
-/** @internal */
-export const defaultCodecTransformer: CodecTransformer = (codec) => {
-  const document = JsonSchema.resolveTopLevel$ref(Schema.toJsonSchemaDocument(codec))
-  const jsonSchema = { ...document.schema }
-  if (Object.keys(document.definitions).length > 0) {
-    jsonSchema.$defs = document.definitions
+const makeDefaultCodecTransformer = (
+  toJsonSchemaDocument: (schema: Schema.Constraint) => JsonSchema.Document<"draft-2020-12">
+): CodecTransformer => {
+  return (codec) => {
+    const document = JsonSchema.resolveTopLevel$ref(toJsonSchemaDocument(codec))
+    const jsonSchema = { ...document.schema }
+    if (Object.keys(document.definitions).length > 0) {
+      jsonSchema.$defs = document.definitions
+    }
+    return { codec, jsonSchema }
   }
-  return { codec, jsonSchema }
 }
+
+/** @internal */
+export const defaultCodecTransformer = makeDefaultCodecTransformer(Schema.toJsonSchemaDocument)