effect 4.0.0-beta.98 → 4.0.0-rc.108

package/src/unstable/ai/Tool.ts

@@ -171,7 +171,7 @@ export type NeedsApproval<Params extends Schema.Constraint> =
  *
  * **Example** (Defining a weather lookup tool)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -188,6 +188,7 @@ export type NeedsApproval<Params extends Schema.Constraint> =
  *     humidity: Schema.Number
  *   })
  * })
+ * const result = [GetWeather.name, GetWeather.failureMode] // => ["GetWeather", "error"]
  * ```
  *
  * @category models
@@ -273,6 +274,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.
@@ -358,7 +366,7 @@ export interface Tool<
  *
  * **Example** (Defining a provider-defined web search tool)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -377,7 +385,8 @@ export interface Tool<
  *       snippet: Schema.String
  *     }))
  *   })
- * })
+ * })({ query: "Effect" })
+ * const result = [WebSearch.name, WebSearch.providerName] // => ["OpenAiWebSearch", "web_search"]
  * ```
  *
  * @category models
@@ -450,7 +459,7 @@ export interface ProviderDefined<
  *
  * **Example** (Defining dynamic tools)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -473,6 +482,8 @@ export interface ProviderDefined<
  *     required: ["query"]
  *   }
  * })
+ *
+ * const result = [Calculator.name, McpTool.name] // => ["Calculator", "McpTool"]
  * ```
  *
  * @category models
@@ -517,7 +528,7 @@ export interface Dynamic<
  *
  * **Example** (Checking for user-defined tools)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -547,8 +558,7 @@ export interface Dynamic<
  *   })
  * })
  *
- * console.log(Tool.isUserDefined(UserDefinedTool)) // true
- * console.log(Tool.isUserDefined(ProviderDefinedTool)) // false
+ * const result = [Tool.isUserDefined(UserDefinedTool), Tool.isUserDefined(ProviderDefinedTool)] // => [true, false]
  * ```
  *
  * @category guards
@@ -562,7 +572,7 @@ export const isUserDefined = (u: unknown): u is Tool<string, any, any> =>
  *
  * **Example** (Checking for provider-defined tools)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -592,8 +602,7 @@ export const isUserDefined = (u: unknown): u is Tool<string, any, any> =>
  *   })
  * })
  *
- * console.log(Tool.isProviderDefined(UserDefinedTool)) // false
- * console.log(Tool.isProviderDefined(ProviderDefinedTool)) // true
+ * const result = [Tool.isProviderDefined(UserDefinedTool), Tool.isProviderDefined(ProviderDefinedTool)] // => [false, false]
  * ```
  *
  * @category guards
@@ -608,7 +617,7 @@ export const isProviderDefined = (
  *
  * **Example** (Checking for dynamic tools)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -621,8 +630,7 @@ export const isProviderDefined = (
  *   success: Schema.Number
  * })
  *
- * console.log(Tool.isDynamic(DynamicTool)) // true
- * console.log(Tool.isDynamic(UserDefinedTool)) // false
+ * const result = [Tool.isDynamic(DynamicTool), Tool.isDynamic(UserDefinedTool)] // => [true, false]
  * ```
  *
  * @category guards
@@ -1028,37 +1036,37 @@ export type RequiresHandler<Tool extends Any> = Tool extends ProviderDefined<
 // Constructors
 // =============================================================================
 
+// Clones a tool while preserving its prototype (and thus its kind, e.g.
+// user-defined vs. provider-defined vs. dynamic) and its own properties such
+// as `id`. Optional `overrides` replace individual fields on the clone.
+const clone = (self: Any, overrides?: Record<string, unknown>): any =>
+  Object.assign(Object.create(Object.getPrototypeOf(self)), self, overrides)
+
 const Proto = {
   [TypeId]: { _Requirements: identity },
   pipe() {
     return pipeArguments(this, arguments)
   },
   addDependency(this: Any) {
-    return userDefinedProto({ ...this })
+    return clone(this)
   },
   setParameters(this: Any, parametersSchema: Schema.Constraint) {
-    return userDefinedProto({
-      ...this,
-      parametersSchema
-    })
+    return clone(this, { parametersSchema })
   },
   setSuccess(this: Any, successSchema: Schema.Constraint) {
-    return userDefinedProto({ ...this, successSchema })
+    return clone(this, { successSchema })
   },
   setFailure(this: Any, failureSchema: Schema.Constraint) {
-    return userDefinedProto({ ...this, failureSchema })
+    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 userDefinedProto({
-      ...this,
-      annotations: Context.add(this.annotations, tag, value)
-    })
+    return clone(this, { annotations: Context.add(this.annotations, tag, value) })
   },
   annotateMerge<I>(this: Any, context: Context.Context<I>) {
-    return userDefinedProto({
-      ...this,
-      annotations: Context.merge(this.annotations, context)
-    })
+    return clone(this, { annotations: Context.merge(this.annotations, context) })
   }
 }
 
@@ -1132,7 +1140,7 @@ const providerDefinedProto = <
     readonly failureMode: Mode
   },
   RequiresHandler
-> => Object.assign(Object.create(ProviderDefinedProto), { ...options })
+> => Object.assign(Object.create(ProviderDefinedProto), { annotations: Context.empty(), ...options })
 
 const dynamicProto = <
   const Name extends string,
@@ -1178,7 +1186,7 @@ const dynamicProto = <
  *
  * **Example** (Creating a tool without parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1187,6 +1195,7 @@ const dynamicProto = <
  *   description: "Returns the current timestamp",
  *   success: Schema.Number
  * })
+ * GetCurrentTime.name // => "GetCurrentTime"
  * ```
  *
  * @category constructors
@@ -1284,7 +1293,7 @@ export const make = <
  *
  * **Example** (Creating a dynamic tool)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1307,6 +1316,8 @@ export const make = <
  *     required: ["query"]
  *   }
  * })
+ *
+ * const result = [Calculator.name, McpTool.name] // => ["Calculator", "McpTool"]
  * ```
  *
  * @category constructors
@@ -1329,7 +1340,7 @@ export const dynamic: {
    *
    * **Example** (Creating a dynamic tool)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Schema } from "effect"
    * import { Tool } from "effect/unstable/ai"
    *
@@ -1352,6 +1363,8 @@ export const dynamic: {
    *     required: ["query"]
    *   }
    * })
+   *
+   * const result = [Calculator.name, McpTool.name] // => ["Calculator", "McpTool"]
    * ```
    *
    * @category constructors
@@ -1423,7 +1436,7 @@ export const dynamic: {
  *
  * **Example** (Creating a provider-defined tool)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1442,7 +1455,8 @@ export const dynamic: {
  *       content: Schema.String
  *     }))
  *   })
- * })
+ * })({ query: "Effect" })
+ * const result = [WebSearch.name, WebSearch.providerName] // => ["OpenAiWebSearch", "web_search"]
  * ```
  *
  * @category constructors
@@ -1620,7 +1634,7 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
  *
  * **Example** (Reading a tool description)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Tool } from "effect/unstable/ai"
  *
  * const myTool = Tool.make("example", {
@@ -1628,7 +1642,7 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
  * })
  *
  * const description = Tool.getDescription(myTool)
- * console.log(description) // "This is an example tool"
+ * description // => "This is an example tool"
  * ```
  *
  * @category getters
@@ -1659,7 +1673,7 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
  *
  * **Example** (Generating a tool JSON schema)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1671,15 +1685,10 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
  * })
  *
  * const jsonSchema = Tool.getJsonSchema(weatherTool)
- * console.log(jsonSchema)
- * // {
- * //   type: "object",
- * //   properties: {
- * //     location: { type: "string" },
- * //     units: { type: "string", enum: ["celsius", "fahrenheit"] }
- * //   },
- * //   required: ["location", "units"]
- * // }
+ * jsonSchema.type // => "object"
+ * if (typeof jsonSchema.properties === "object" && jsonSchema.properties !== null) {
+ *   Object.keys(jsonSchema.properties) // => ["location", "units"]
+ * }
  * ```
  *
  * @category getters
@@ -1710,10 +1719,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
   }
@@ -1729,14 +1746,16 @@ export const getJsonSchemaFromSchema = <S extends Schema.Constraint>(schema: S,
  *
  * **Example** (Annotating a tool title)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Context } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
  * const myTool = Tool.make("calculate_tip")
  *   .annotate(Tool.Title, "Tip Calculator")
+ * Context.getUnsafe(myTool.annotations, Tool.Title) // => "Tip Calculator"
  * ```
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Title extends Context.Service<Title, string>()("effect/ai/Tool/Title") {}
@@ -1746,14 +1765,16 @@ export class Title extends Context.Service<Title, string>()("effect/ai/Tool/Titl
  *
  * **Example** (Annotating MCP metadata)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Context } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
  * const myCalculatorUi = Tool.make("calculator_ui", {})
  *   .annotate(Tool.Meta, { ui: { resourceUri: "ui://example/calculator-ui" } })
+ * "ui" in Context.getUnsafe(myCalculatorUi.annotations, Tool.Meta) // => true
  * ```
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Meta extends Context.Service<Meta, Record<string, unknown>>()("effect/ai/Tool/Meta") {}
@@ -1768,14 +1789,16 @@ export class Meta extends Context.Service<Meta, Record<string, unknown>>()("effe
  *
  * **Example** (Marking a tool as read-only)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Context } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
  * const readOnlyTool = Tool.make("get_user_info")
  *   .annotate(Tool.Readonly, true)
+ * Context.get(readOnlyTool.annotations, Tool.Readonly) // => true
  * ```
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Readonly = Context.Reference<boolean>("effect/ai/Tool/Readonly", {
@@ -1792,14 +1815,16 @@ export const Readonly = Context.Reference<boolean>("effect/ai/Tool/Readonly", {
  *
  * **Example** (Marking a tool as non-destructive)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Context } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
  * const safeTool = Tool.make("search_database")
  *   .annotate(Tool.Destructive, false)
+ * Context.get(safeTool.annotations, Tool.Destructive) // => false
  * ```
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Destructive = Context.Reference<boolean>("effect/ai/Tool/Destructive", {
@@ -1817,14 +1842,16 @@ export const Destructive = Context.Reference<boolean>("effect/ai/Tool/Destructiv
  *
  * **Example** (Marking a tool as idempotent)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Context } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
  * const idempotentTool = Tool.make("get_current_time")
  *   .annotate(Tool.Idempotent, true)
+ * Context.get(idempotentTool.annotations, Tool.Idempotent) // => true
  * ```
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Idempotent = Context.Reference<boolean>("effect/ai/Tool/Idempotent", {
@@ -1842,14 +1869,16 @@ export const Idempotent = Context.Reference<boolean>("effect/ai/Tool/Idempotent"
  *
  * **Example** (Disabling open-world access)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Context } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
  * const restrictedTool = Tool.make("internal_operation")
  *   .annotate(Tool.OpenWorld, false)
+ * Context.get(restrictedTool.annotations, Tool.OpenWorld) // => false
  * ```
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const OpenWorld = Context.Reference<boolean>("effect/ai/Tool/OpenWorld", {
@@ -1871,14 +1900,15 @@ export const OpenWorld = Context.Reference<boolean>("effect/ai/Tool/OpenWorld",
  *
  * **Example** (Disabling strict JSON schema mode)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Tool } from "effect/unstable/ai"
  *
  * const flexibleTool = Tool.make("search")
  *   .annotate(Tool.Strict, false)
+ * Tool.getStrictMode(flexibleTool) // => false
  * ```
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Strict = Context.Reference<boolean | undefined>("effect/ai/Tool/Strict", {
@@ -1959,13 +1989,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"
@@ -32,8 +33,8 @@ const TypeId = "~effect/ai/Toolkit" as const
  *
  * **Example** (Defining AI toolkits)
  *
- * ```ts
- * import { Schema } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Schema } from "effect"
  * import { Tool, Toolkit } from "effect/unstable/ai"
  *
  * const SearchDocs = Tool.make("SearchDocs", {
@@ -50,8 +51,12 @@ const TypeId = "~effect/ai/Toolkit" as const
  *
  * const AiToolkit = Toolkit.make(SearchDocs, SummarizeText)
  *
- * console.log(Object.keys(AiToolkit.tools))
- * // ["SearchDocs", "SummarizeText"]
+ * const ready = AiToolkit.pipe(Effect.provide(AiToolkit.toLayer({
+ *   SearchDocs: ({ query }) => Effect.succeed([query]),
+ *   SummarizeText: ({ text }) => Effect.succeed(text)
+ * })))
+ *
+ * Object.keys((await Effect.runPromise(ready)).tools) // => ["SearchDocs", "SummarizeText"]
  * ```
  *
  * @category models
@@ -105,6 +110,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 +208,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 +270,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 +315,7 @@ const Proto = {
           readonly preliminary: boolean
         }, Cause.Done>()
         const context: HandlerContext<any> = {
+          toolCallId,
           preliminary: (result) =>
             Effect.asVoid(Queue.offer(queue, {
               result,
@@ -390,8 +404,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 +434,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
 }
@@ -447,8 +463,8 @@ export const empty: Toolkit<{}> = makeProto({})
  *
  * **Example** (Creating a toolkit)
  *
- * ```ts
- * import { Schema } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Schema } from "effect"
  * import { Tool, Toolkit } from "effect/unstable/ai"
  *
  * const GetCurrentTime = Tool.make("GetCurrentTime", {
@@ -466,6 +482,12 @@ export const empty: Toolkit<{}> = makeProto({})
  * })
  *
  * const toolkit = Toolkit.make(GetCurrentTime, GetWeather)
+ * const ready = toolkit.pipe(Effect.provide(toolkit.toLayer({
+ *   GetCurrentTime: () => Effect.succeed(0),
+ *   get_weather: () => Effect.succeed({ temperature: 20, condition: "clear" })
+ * })))
+ *
+ * Object.keys((await Effect.runPromise(ready)).tools) // => ["GetCurrentTime", "get_weather"]
  * ```
  *
  * @category constructors
@@ -518,8 +540,8 @@ export type MergedTools<Toolkits extends ReadonlyArray<Any>> = SimplifyRecord<
  *
  * **Example** (Merging toolkits)
  *
- * ```ts
- * import { Schema } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Schema } from "effect"
  * import { Tool, Toolkit } from "effect/unstable/ai"
  *
  * const mathToolkit = Toolkit.make(
@@ -533,6 +555,14 @@ export type MergedTools<Toolkits extends ReadonlyArray<Any>> = SimplifyRecord<
  * )
  *
  * const combined = Toolkit.merge(mathToolkit, utilityToolkit)
+ * const ready = combined.pipe(Effect.provide(combined.toLayer({
+ *   add: () => Effect.succeed(1),
+ *   subtract: () => Effect.succeed(0),
+ *   get_time: () => Effect.succeed(0),
+ *   get_weather: () => Effect.succeed("clear")
+ * })))
+ *
+ * Object.keys((await Effect.runPromise(ready)).tools) // => ["add", "subtract", "get_time", "get_weather"]
  * ```
  *
  * @category constructors
@@ -547,7 +577,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/index.ts

@@ -34,6 +34,11 @@ export * as IdGenerator from "./IdGenerator.ts"
  */
 export * as LanguageModel from "./LanguageModel.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as McpProtocol from "./McpProtocol.ts"
+
 /**
  * @since 4.0.0
  */

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)