openAgent

1import { Effect, Schema } from "effect"
2 
3/**
4 * JSON Schema subset accepted for render-only tool schemas.
5 *
6 * A JSON-Schema-described side of a tool is used to generate the model-visible TypeScript
7 * signature only - CodeMode performs no validation against it. This is the natural shape for
8 * adapter-provided tools (e.g. MCP definitions) whose schemas arrive as JSON Schema documents.
9 */
10export type JsonSchema = {
11  readonly type?: string | ReadonlyArray<string>
12  readonly enum?: ReadonlyArray<unknown>
13  readonly const?: unknown
14  readonly anyOf?: ReadonlyArray<JsonSchema>
15  readonly oneOf?: ReadonlyArray<JsonSchema>
16  readonly allOf?: ReadonlyArray<JsonSchema>
17  readonly properties?: Readonly<Record<string, JsonSchema>>
18  readonly required?: ReadonlyArray<string>
19  readonly items?: JsonSchema
20  readonly additionalProperties?: boolean | JsonSchema
21  readonly description?: string
22  readonly default?: unknown
23  readonly format?: string
24  readonly deprecated?: boolean
25  readonly minItems?: number
26  readonly maxItems?: number
27  readonly $ref?: string
28  readonly $defs?: Readonly<Record<string, JsonSchema>>
29  readonly definitions?: Readonly<Record<string, JsonSchema>>
30}
31 
32/** Either a validating Effect Schema or a render-only JSON Schema document. */
33export type SchemaType = Schema.Decoder<unknown> | JsonSchema
34 
35/** Schema-backed tool definition consumed by a CodeMode tool tree. */
36export type Definition<R = never> = {
37  readonly _tag: "CodeModeTool"
38  readonly description: string
39  readonly input: SchemaType
40  readonly output: SchemaType | undefined
41  readonly run: (input: unknown) => Effect.Effect<unknown, unknown, R>
42}
43 
44/** The value `run` receives: the decoded type for Effect Schemas, `unknown` for JSON Schemas. */
45type InputType<S> = S extends Schema.Decoder<unknown> ? S["Type"] : unknown
46 
47/** The value `run` returns: the encoded type for Effect Schemas, `unknown` otherwise. */
48type ResultType<S> = S extends Schema.Decoder<unknown> ? S["Encoded"] : unknown
49 
50/** Options for defining one CodeMode tool. */
51export type Options<I extends SchemaType, O extends SchemaType | undefined, R = never> = {
52  readonly description: string
53  readonly input: I
54  readonly output?: O
55  readonly run: (input: InputType<I>) => Effect.Effect<ResultType<O>, unknown, R>
56}
57 
58export const isDefinition = <R = never>(value: unknown): value is Definition<R> =>
59  typeof value === "object" && value !== null && "_tag" in value && value._tag === "CodeModeTool"
60 
61/**
62 * Defines one schema-described tool available to a CodeMode program through `tools.*`.
63 *
64 * `input` and `output` each accept a validating Effect Schema or a render-only JSON Schema
65 * document. Effect Schema input is decoded before `run` is invoked, and `run` returns the
66 * encoded representation of an Effect Schema `output`, which CodeMode decodes before returning
67 * it to the program. JSON Schemas only shape the model-visible signature; values pass through
68 * unvalidated. `output` is optional - without it the signature advertises `unknown` and the
69 * host result is exposed as-is. The host tool remains responsible for authorization and
70 * durable side-effect handling.
71 *
72 * @example
73 * ```ts
74 * const lookup = Tool.make({
75 *   description: "Look up an order",
76 *   input: Schema.Struct({ id: Schema.String }),
77 *   output: Schema.Struct({ status: Schema.String }),
78 *   run: ({ id }) => Effect.succeed({ status: "open" }),
79 * })
80 *
81 * const fromJsonSchema = Tool.make({
82 *   description: "Call an adapter-described tool",
83 *   input: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
84 *   run: (input) => callHost(input),
85 * })
86 * ```
87 */
88export const make = <I extends SchemaType, const O extends SchemaType | undefined = undefined, R = never>(
89  options: Options<I, O, R>,
90): Definition<R> => ({
91  _tag: "CodeModeTool",
92  description: options.description,
93  input: options.input,
94  output: options.output,
95  run: (input) => options.run(input as InputType<I>),
96})
97