openAgent

1import { JsonPointer, Schema } from "effect"
2import type { Definition, JsonSchema, SchemaType } from "./tool.js"
3 
4const isEffectSchema = (schema: SchemaType): schema is Schema.Decoder<unknown> & Schema.Top => Schema.isSchema(schema)
5 
6const renderLiteral = (value: unknown): string => JSON.stringify(value) ?? "unknown"
7 
8/**
9 * Bare TypeScript identifier - usable unquoted as an object key (and, in the tool runtime,
10 * with dot access as a tool-path segment). Anything else must be quoted/bracketed.
11 */
12export const identifierSegment = /^[A-Za-z_$][A-Za-z0-9_$]*$/
13 
14/** Renders a property name as a valid TS object key: bare when an identifier, quoted otherwise. */
15const renderKey = (name: string): string => (identifierSegment.test(name) ? name : JSON.stringify(name))
16 
17const effectNumberSentinel = (schema: JsonSchema) =>
18  schema.type === "string" &&
19  Array.isArray(schema.enum) &&
20  schema.enum.length === 1 &&
21  (schema.enum[0] === "NaN" || schema.enum[0] === "Infinity" || schema.enum[0] === "-Infinity")
22 
23const intersection = (members: ReadonlyArray<string>): string => {
24  const concrete = members.filter((member) => member !== "unknown")
25  if (concrete.length === 0) return "unknown"
26  if (concrete.length === 1) return concrete[0] ?? "unknown"
27  return concrete.map((member) => (member.includes(" | ") ? `(${member})` : member)).join(" & ")
28}
29 
30/**
31 * Recursion ceiling for schema rendering. Object, array, and union recursion all increment
32 * depth, so this bounds every recursion path - pathological or structurally cyclic schemas
33 * degrade to `unknown` instead of overflowing the stack (rendering must never throw).
34 */
35const MAX_RENDER_DEPTH = 8
36 
37type RenderContext = {
38  readonly definitions: Readonly<Record<string, JsonSchema>>
39  /** Indented, JSDoc-annotated multiline rendering (search results); compact single line otherwise. */
40  readonly pretty: boolean
41}
42 
43const hasUnresolvedRef = (
44  schema: JsonSchema,
45  definitions: Readonly<Record<string, JsonSchema>>,
46  seen: ReadonlySet<string> = new Set(),
47  visited: ReadonlySet<JsonSchema> = new Set(),
48): boolean => {
49  if (visited.has(schema)) return false
50  const nextVisited = new Set([...visited, schema])
51  if (schema.$ref !== undefined) {
52    const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1]
53    const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment)
54    if (name === undefined || definitions[name] === undefined || seen.has(name)) return true
55    if (hasUnresolvedRef(definitions[name], definitions, new Set([...seen, name]), nextVisited)) return true
56  }
57  return [
58    ...(schema.anyOf ?? []),
59    ...(schema.oneOf ?? []),
60    ...(schema.allOf ?? []),
61    ...Object.values(schema.properties ?? {}),
62    ...(schema.items === undefined ? [] : [schema.items]),
63    ...(typeof schema.additionalProperties === "object" ? [schema.additionalProperties] : []),
64  ].some((item) => hasUnresolvedRef(item, definitions, seen, nextVisited))
65}
66 
67/**
68 * Schema constraints a TypeScript type cannot express natively but a model benefits from,
69 * surfaced as JSDoc tags (`@deprecated`, `@default`, `@format`, `@minItems`, `@maxItems`).
70 */
71const docTags = (schema: JsonSchema): Array<string> => {
72  const tags: Array<string> = []
73  if (schema.deprecated === true) tags.push("@deprecated")
74  if (schema.default !== undefined) {
75    try {
76      const rendered = JSON.stringify(schema.default)
77      if (rendered !== undefined) tags.push(`@default ${rendered}`)
78    } catch {
79      // unserializable default: skip rather than emit a broken tag
80    }
81  }
82  if (typeof schema.format === "string") tags.push(`@format ${schema.format}`)
83  if (typeof schema.minItems === "number") tags.push(`@minItems ${schema.minItems}`)
84  if (typeof schema.maxItems === "number") tags.push(`@maxItems ${schema.maxItems}`)
85  return tags
86}
87 
88/**
89 * Format a schema `description` plus `tags` as a JSDoc comment at the given indent,
90 * preserving multi-line text (a single line stays `/** ... *\/`; multiple lines become a
91 * `*`-prefixed block). `*\/` is neutralized so nothing can close the comment early, and
92 * blank leading/trailing lines are trimmed. Returns "" (else a trailing newline) so
93 * callers can prepend it directly to the field line.
94 */
95const jsdoc = (description: string | undefined, tags: ReadonlyArray<string>, pad: string): string => {
96  const lines = [...(description === undefined ? [] : description.split("\n")), ...tags].map((line) =>
97    line.replaceAll("*/", "* /").replace(/\s+$/, ""),
98  )
99  while (lines.length > 0 && lines[0]!.trim() === "") lines.shift()
100  while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") lines.pop()
101  if (lines.length === 0) return ""
102  if (lines.length === 1) return `${pad}/** ${lines[0]} */\n`
103  const body = lines.map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`).join("\n")
104  return `${pad}/**\n${body}\n${pad} */\n`
105}
106 
107const renderSchema = (
108  schema: JsonSchema,
109  ctx: RenderContext,
110  depth = 0,
111  seen: ReadonlySet<string> = new Set(),
112): string => {
113  if (depth > MAX_RENDER_DEPTH) return "unknown"
114  const nested =
115    schema.definitions === undefined && schema.$defs === undefined
116      ? ctx
117      : { ...ctx, definitions: { ...ctx.definitions, ...(schema.definitions ?? {}), ...(schema.$defs ?? {}) } }
118  if (schema.$ref) {
119    const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1]
120    const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment)
121    if (!name || !nested.definitions[name] || seen.has(name)) return "unknown"
122    return intersection([
123      renderSchema(nested.definitions[name], nested, depth, new Set([...seen, name])),
124      renderSchema({ ...schema, $ref: undefined }, nested, depth + 1, seen),
125    ])
126  }
127  if (schema.const !== undefined) return renderLiteral(schema.const)
128  if (schema.enum) return schema.enum.map(renderLiteral).join(" | ")
129  const alternatives = schema.anyOf ?? schema.oneOf
130  if (alternatives) {
131    // Effect's number schema emits `anyOf: [{ type: "number" }, { const: "NaN" },
132    // { const: "Infinity" }, { const: "-Infinity" }]`. Collapse only that artifact;
133    // real JSON Schema unions such as `string | number` or `number | null` must keep
134    // every branch.
135    if (
136      alternatives.some((item) => item.type === "number") &&
137      alternatives.every((item) => item.type === "number" || effectNumberSentinel(item))
138    )
139      return "number"
140    // An empty Schema.Struct({}) emits `anyOf: [{ type: "object" }, { type: "array" }]`
141    // (no properties/items); render the bare shape as {} instead of `{} | Array<unknown>`.
142    if (
143      alternatives.length === 2 &&
144      alternatives[0]?.type === "object" &&
145      alternatives[0].properties === undefined &&
146      alternatives[1]?.type === "array" &&
147      alternatives[1].items === undefined
148    ) {
149      return "{}"
150    }
151    const members = alternatives.map((item) => renderSchema(item, nested, depth + 1, seen))
152    if (members.some((member) => member === "unknown")) return "unknown"
153    return intersection([
154      members.join(" | "),
155      renderSchema({ ...schema, anyOf: undefined, oneOf: undefined }, nested, depth + 1, seen),
156    ])
157  }
158  if (schema.allOf) {
159    const members = schema.allOf.map((item) => renderSchema(item, nested, depth + 1, seen))
160    if (schema.allOf.some((item) => hasUnresolvedRef(item, nested.definitions))) return "unknown"
161    return intersection([renderSchema({ ...schema, allOf: undefined }, nested, depth + 1, seen), ...members])
162  }
163  if (Array.isArray(schema.type)) {
164    return schema.type.map((item) => renderSchema({ ...schema, type: item }, nested, depth + 1, seen)).join(" | ")
165  }
166  if (schema.type === "string") return "string"
167  if (schema.type === "number" || schema.type === "integer") return "number"
168  if (schema.type === "boolean") return "boolean"
169  if (schema.type === "null") return "null"
170  if (schema.type === "array") return `Array<${renderSchema(schema.items ?? {}, nested, depth + 1, seen)}>`
171  if (schema.type === "object" || schema.properties) {
172    const required = new Set(schema.required ?? [])
173    const properties = Object.entries(schema.properties ?? {})
174    const additional = schema.additionalProperties
175    const indexType =
176      additional && typeof additional === "object" ? renderSchema(additional, nested, depth + 1, seen) : undefined
177    const field = ([name, value]: readonly [string, JsonSchema]) =>
178      `${renderKey(name)}${required.has(name) ? "" : "?"}: ${renderSchema(value, nested, depth + 1, seen)}`
179 
180    if (!ctx.pretty) {
181      const fields = properties.map(field)
182      if (indexType !== undefined) fields.push(`[key: string]: ${indexType}`)
183      return fields.length === 0 ? "{}" : `{ ${fields.join("; ")} }`
184    }
185 
186    // Pretty: an indented block, each described field preceded by its JSDoc comment.
187    if (properties.length === 0 && indexType === undefined) return "{}"
188    const pad = "  ".repeat(depth + 1)
189    const lines = properties.map(
190      (entry) => `${jsdoc(entry[1].description, docTags(entry[1]), pad)}${pad}${field(entry)},`,
191    )
192    if (indexType !== undefined) lines.push(`${pad}[key: string]: ${indexType},`)
193    return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`
194  }
195  return "unknown"
196}
197 
198export const toTypeScript = (schema: Schema.Top, decoded = false, pretty = false): string => {
199  try {
200    const visible = decoded ? Schema.toType(schema) : schema
201    const document = Schema.toJsonSchemaDocument(visible) as {
202      readonly schema: JsonSchema
203      readonly definitions?: Readonly<Record<string, JsonSchema>>
204    }
205    return renderSchema(document.schema, { definitions: document.definitions ?? {}, pretty })
206  } catch {
207    return "unknown"
208  }
209}
210 
211/** Renders a raw JSON Schema document as a TypeScript type string. */
212export const jsonSchemaToTypeScript = (schema: JsonSchema, pretty = false): string => {
213  try {
214    return renderSchema(schema, { definitions: { ...(schema.definitions ?? {}), ...(schema.$defs ?? {}) }, pretty })
215  } catch {
216    return "unknown"
217  }
218}
219 
220/** One input property of a tool, extracted best-effort from its input schema. */
221export type InputProperty = {
222  readonly name: string
223  readonly description: string | undefined
224  readonly required: boolean
225}
226 
227/**
228 * The property names, descriptions, and required flags of a tool's input schema - the raw
229 * material for search text. Best-effort: Effect Schemas go through their
230 * JSON Schema document (the same emission signature rendering uses); JSON Schemas are read
231 * directly, resolving a trivial top-level `$ref` into `$defs`/`definitions` when present.
232 * Anything unresolvable yields `[]` (search falls back to path + description).
233 */
234export const inputProperties = <R>(definition: Definition<R>): Array<InputProperty> => {
235  try {
236    const document = isEffectSchema(definition.input)
237      ? (Schema.toJsonSchemaDocument(definition.input) as {
238          readonly schema: JsonSchema
239          readonly definitions?: Readonly<Record<string, JsonSchema>>
240        })
241      : {
242          schema: definition.input,
243          definitions: { ...(definition.input.definitions ?? {}), ...(definition.input.$defs ?? {}) },
244        }
245    const definitions = document.definitions ?? {}
246    let schema = document.schema
247    if (schema.$ref !== undefined) {
248      const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1]
249      const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment)
250      const resolved = name === undefined ? undefined : definitions[name]
251      if (resolved === undefined) return []
252      schema = resolved
253    }
254    const required = new Set(schema.required ?? [])
255    return Object.entries(schema.properties ?? {}).map(([name, value]) => ({
256      name,
257      description: typeof value.description === "string" ? value.description : undefined,
258      required: required.has(name),
259    }))
260  } catch {
261    return []
262  }
263}
264 
265/**
266 * The model-visible TypeScript type of a tool's input. `pretty` renders an indented
267 * multiline block with schema descriptions and constraints as JSDoc comments on the
268 * fields; the default stays the compact single-line form.
269 */
270export const inputTypeScript = <R>(definition: Definition<R>, pretty = false): string =>
271  isEffectSchema(definition.input)
272    ? toTypeScript(definition.input, false, pretty)
273    : jsonSchemaToTypeScript(definition.input, pretty)
274 
275/**
276 * The model-visible TypeScript type of a tool's result; tools without an output schema
277 * return `unknown`. `pretty` renders the JSDoc-annotated multiline form, as for inputs.
278 */
279export const outputTypeScript = <R>(definition: Definition<R>, pretty = false): string =>
280  definition.output === undefined
281    ? "unknown"
282    : isEffectSchema(definition.output)
283      ? toTypeScript(definition.output, true, pretty)
284      : jsonSchemaToTypeScript(definition.output, pretty)
285 
286/**
287 * Decodes tool input before `run` is invoked. Effect Schemas validate (throwing on failure);
288 * JSON-Schema-described inputs pass through unvalidated (render-only).
289 */
290export const decodeInput = <R>(definition: Definition<R>, value: unknown): unknown =>
291  isEffectSchema(definition.input) ? Schema.decodeUnknownSync(definition.input)(value) : value
292 
293/**
294 * Decodes a tool result before it is exposed to the program. Effect Schemas validate and
295 * transform (throwing on failure); JSON Schema outputs and tools without an output schema pass
296 * the host value through unchanged.
297 */
298export const decodeOutput = <R>(definition: Definition<R>, value: unknown): unknown =>
299  definition.output !== undefined && isEffectSchema(definition.output)
300    ? Schema.decodeUnknownSync(definition.output)(value)
301    : value
302