@jackchen_me/open-multi-agent 1.0.0 → 1.0.1

package/src/tool/framework.ts

@@ -1,557 +0,0 @@
-/**
- * Tool definition framework for open-multi-agent.
- *
- * Provides the core primitives for declaring, registering, and converting
- * tools to the JSON Schema format that LLM APIs expect.
- *
- * Types shared with the rest of the framework (`ToolDefinition`, `ToolResult`,
- * `ToolUseContext`) are imported from `../types` to ensure a single source of
- * truth.  This file re-exports them for the convenience of downstream callers
- * who only need to import from `tool/framework`.
- */
-
-import { type ZodSchema } from 'zod'
-import type {
-  ToolDefinition,
-  ToolResult,
-  ToolUseContext,
-  LLMToolDef,
-} from '../types.js'
-
-// Re-export so consumers can `import { ToolDefinition } from './framework.js'`
-export type { ToolDefinition, ToolResult, ToolUseContext }
-
-// ---------------------------------------------------------------------------
-// LLM-facing JSON Schema types
-// ---------------------------------------------------------------------------
-
-/** Minimal JSON Schema for a single property. */
-export type JSONSchemaProperty =
-  | { type: 'string'; description?: string; enum?: string[] }
-  | { type: 'number'; description?: string }
-  | { type: 'integer'; description?: string }
-  | { type: 'boolean'; description?: string }
-  | { type: 'null'; description?: string }
-  | { type: 'array'; items: JSONSchemaProperty; description?: string }
-  | {
-      type: 'object'
-      properties: Record<string, JSONSchemaProperty>
-      required?: string[]
-      description?: string
-    }
-  | { anyOf: JSONSchemaProperty[]; description?: string }
-  | { const: unknown; description?: string }
-  // Fallback for types we don't explicitly model
-  | Record<string, unknown>
-
-// ---------------------------------------------------------------------------
-// defineTool
-// ---------------------------------------------------------------------------
-
-/**
- * Define a typed tool.  This is the single entry-point for creating tools
- * that can be registered with a {@link ToolRegistry}.
- *
- * The returned object satisfies the {@link ToolDefinition} interface imported
- * from `../types`.
- *
- * @example
- * ```ts
- * const echoTool = defineTool({
- *   name: 'echo',
- *   description: 'Echo the input message back to the caller.',
- *   inputSchema: z.object({ message: z.string() }),
- *   execute: async ({ message }) => ({
- *     data: message,
- *     isError: false,
- *   }),
- * })
- * ```
- */
-export function defineTool<TInput>(config: {
-  name: string
-  description: string
-  inputSchema: ZodSchema<TInput>
-  execute: (input: TInput, context: ToolUseContext) => Promise<ToolResult>
-}): ToolDefinition<TInput> {
-  return {
-    name: config.name,
-    description: config.description,
-    inputSchema: config.inputSchema,
-    execute: config.execute,
-  }
-}
-
-// ---------------------------------------------------------------------------
-// ToolRegistry
-// ---------------------------------------------------------------------------
-
-/**
- * Registry that holds a set of named tools and can produce the JSON Schema
- * representation expected by LLM APIs (Anthropic, OpenAI, etc.).
- */
-export class ToolRegistry {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private readonly tools = new Map<string, ToolDefinition<any>>()
-
-  /**
-   * Add a tool to the registry.  Throws if a tool with the same name has
-   * already been registered — prevents silent overwrites.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  register(tool: ToolDefinition<any>): void {
-    if (this.tools.has(tool.name)) {
-      throw new Error(
-        `ToolRegistry: a tool named "${tool.name}" is already registered. ` +
-          'Use a unique name or deregister the existing one first.',
-      )
-    }
-    this.tools.set(tool.name, tool)
-  }
-
-  /** Return a tool by name, or `undefined` if not found. */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  get(name: string): ToolDefinition<any> | undefined {
-    return this.tools.get(name)
-  }
-
-  /**
-   * Return all registered tool definitions as an array.
-   *
-   * Callers that only need names can do `registry.list().map(t => t.name)`.
-   * This matches the agent's `getTools()` pattern.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  list(): ToolDefinition<any>[] {
-    return Array.from(this.tools.values())
-  }
-
-  /**
-   * Return all registered tool definitions as an array.
-   * Alias for {@link list} — available for callers that prefer explicit naming.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  getAll(): ToolDefinition<any>[] {
-    return Array.from(this.tools.values())
-  }
-
-  /** Return true when a tool with the given name is registered. */
-  has(name: string): boolean {
-    return this.tools.has(name)
-  }
-
-  /**
-   * Remove a tool by name.
-   * No-op if the tool was not registered — matches the agent's expected
-   * behaviour where `removeTool` is a graceful operation.
-   */
-  unregister(name: string): void {
-    this.tools.delete(name)
-  }
-
-  /** Alias for {@link unregister} — available for symmetry with `register`. */
-  deregister(name: string): void {
-    this.tools.delete(name)
-  }
-
-  /**
-   * Convert all registered tools to the {@link LLMToolDef} format used by LLM
-   * adapters.  This is the primary method called by the agent runner before
-   * each LLM API call.
-   */
-  toToolDefs(): LLMToolDef[] {
-    return Array.from(this.tools.values()).map((tool) => {
-      const schema = zodToJsonSchema(tool.inputSchema)
-      return {
-        name: tool.name,
-        description: tool.description,
-        inputSchema: schema,
-      } satisfies LLMToolDef
-    })
-  }
-
-  /**
-   * Convert all registered tools to the Anthropic-style `input_schema`
-   * format.  Prefer {@link toToolDefs} for normal use; this method is exposed
-   * for callers that construct their own API payloads.
-   */
-  toLLMTools(): Array<{
-    name: string
-    description: string
-    input_schema: {
-      type: 'object'
-      properties: Record<string, JSONSchemaProperty>
-      required?: string[]
-    }
-  }> {
-    return Array.from(this.tools.values()).map((tool) => {
-      const schema = zodToJsonSchema(tool.inputSchema)
-      return {
-        name: tool.name,
-        description: tool.description,
-        input_schema: {
-          type: 'object' as const,
-          properties:
-            (schema.properties as Record<string, JSONSchemaProperty>) ?? {},
-          ...(schema.required !== undefined
-            ? { required: schema.required as string[] }
-            : {}),
-        },
-      }
-    })
-  }
-}
-
-// ---------------------------------------------------------------------------
-// zodToJsonSchema
-// ---------------------------------------------------------------------------
-
-/**
- * Convert a Zod schema to a plain JSON Schema object suitable for inclusion
- * in LLM API calls.
- *
- * Supported Zod types:
- *   z.string(), z.number(), z.boolean(), z.enum(), z.array(), z.object(),
- *   z.optional(), z.union(), z.literal(), z.describe(), z.nullable(),
- *   z.default(), z.intersection(), z.discriminatedUnion(), z.record(),
- *   z.tuple(), z.any(), z.unknown(), z.never(), z.effects() (transforms)
- *
- * Unsupported types fall back to `{}` (any) which is still valid JSON Schema.
- */
-export function zodToJsonSchema(schema: ZodSchema): Record<string, unknown> {
-  return convertZodType(schema)
-}
-
-// Internal recursive converter.  We access Zod's internal `_def` structure
-// because Zod v3 does not ship a first-class JSON Schema exporter.
-function convertZodType(schema: ZodSchema): Record<string, unknown> {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const def = (schema as any)._def as ZodTypeDef
-
-  const description: string | undefined = def.description
-
-  const withDesc = (result: Record<string, unknown>): Record<string, unknown> =>
-    description !== undefined ? { ...result, description } : result
-
-  switch (def.typeName) {
-    // -----------------------------------------------------------------------
-    // Primitives
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodString:
-      return withDesc({ type: 'string' })
-
-    case ZodTypeName.ZodNumber:
-      return withDesc({ type: 'number' })
-
-    case ZodTypeName.ZodBigInt:
-      return withDesc({ type: 'integer' })
-
-    case ZodTypeName.ZodBoolean:
-      return withDesc({ type: 'boolean' })
-
-    case ZodTypeName.ZodNull:
-      return withDesc({ type: 'null' })
-
-    case ZodTypeName.ZodUndefined:
-      return withDesc({ type: 'null' })
-
-    case ZodTypeName.ZodDate:
-      return withDesc({ type: 'string', format: 'date-time' })
-
-    // -----------------------------------------------------------------------
-    // Literals
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodLiteral: {
-      const literalDef = def as ZodLiteralDef
-      return withDesc({ const: literalDef.value })
-    }
-
-    // -----------------------------------------------------------------------
-    // Enums
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodEnum: {
-      const enumDef = def as ZodEnumDef
-      return withDesc({ type: 'string', enum: enumDef.values })
-    }
-
-    case ZodTypeName.ZodNativeEnum: {
-      const nativeEnumDef = def as ZodNativeEnumDef
-      const values = Object.values(nativeEnumDef.values as object).filter(
-        (v) => typeof v === 'string' || typeof v === 'number',
-      )
-      return withDesc({ enum: values })
-    }
-
-    // -----------------------------------------------------------------------
-    // Arrays
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodArray: {
-      const arrayDef = def as ZodArrayDef
-      return withDesc({
-        type: 'array',
-        items: convertZodType(arrayDef.type),
-      })
-    }
-
-    case ZodTypeName.ZodTuple: {
-      const tupleDef = def as ZodTupleDef
-      return withDesc({
-        type: 'array',
-        prefixItems: tupleDef.items.map(convertZodType),
-      })
-    }
-
-    // -----------------------------------------------------------------------
-    // Objects
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodObject: {
-      const objectDef = def as ZodObjectDef
-      const properties: Record<string, unknown> = {}
-      const required: string[] = []
-
-      for (const [key, value] of Object.entries(objectDef.shape())) {
-        properties[key] = convertZodType(value as ZodSchema)
-
-        const innerDef = ((value as ZodSchema) as unknown as { _def: ZodTypeDef })._def
-        const isOptional =
-          innerDef.typeName === ZodTypeName.ZodOptional ||
-          innerDef.typeName === ZodTypeName.ZodDefault ||
-          innerDef.typeName === ZodTypeName.ZodNullable
-        if (!isOptional) {
-          required.push(key)
-        }
-      }
-
-      const result: Record<string, unknown> = { type: 'object', properties }
-      if (required.length > 0) result.required = required
-      return withDesc(result)
-    }
-
-    case ZodTypeName.ZodRecord: {
-      const recordDef = def as ZodRecordDef
-      return withDesc({
-        type: 'object',
-        additionalProperties: convertZodType(recordDef.valueType),
-      })
-    }
-
-    // -----------------------------------------------------------------------
-    // Optional / Nullable / Default
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodOptional: {
-      const optionalDef = def as ZodOptionalDef
-      const inner = convertZodType(optionalDef.innerType)
-      return description !== undefined ? { ...inner, description } : inner
-    }
-
-    case ZodTypeName.ZodNullable: {
-      const nullableDef = def as ZodNullableDef
-      const inner = convertZodType(nullableDef.innerType)
-      const type = inner.type
-      if (typeof type === 'string') {
-        return withDesc({ ...inner, type: [type, 'null'] })
-      }
-      return withDesc({ anyOf: [inner, { type: 'null' }] })
-    }
-
-    case ZodTypeName.ZodDefault: {
-      const defaultDef = def as ZodDefaultDef
-      const inner = convertZodType(defaultDef.innerType)
-      return withDesc({ ...inner, default: defaultDef.defaultValue() })
-    }
-
-    // -----------------------------------------------------------------------
-    // Union / Intersection / Discriminated Union
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodUnion: {
-      const unionDef = def as ZodUnionDef
-      const options = (unionDef.options as ZodSchema[]).map(convertZodType)
-      return withDesc({ anyOf: options })
-    }
-
-    case ZodTypeName.ZodDiscriminatedUnion: {
-      const duDef = def as ZodDiscriminatedUnionDef
-      const options = (duDef.options as ZodSchema[]).map(convertZodType)
-      return withDesc({ anyOf: options })
-    }
-
-    case ZodTypeName.ZodIntersection: {
-      const intDef = def as ZodIntersectionDef
-      return withDesc({
-        allOf: [convertZodType(intDef.left), convertZodType(intDef.right)],
-      })
-    }
-
-    // -----------------------------------------------------------------------
-    // Wrappers that forward to their inner type
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodEffects: {
-      const effectsDef = def as ZodEffectsDef
-      const inner = convertZodType(effectsDef.schema)
-      return description !== undefined ? { ...inner, description } : inner
-    }
-
-    case ZodTypeName.ZodBranded: {
-      const brandedDef = def as ZodBrandedDef
-      return withDesc(convertZodType(brandedDef.type))
-    }
-
-    case ZodTypeName.ZodReadonly: {
-      const readonlyDef = def as ZodReadonlyDef
-      return withDesc(convertZodType(readonlyDef.innerType))
-    }
-
-    case ZodTypeName.ZodCatch: {
-      const catchDef = def as ZodCatchDef
-      return withDesc(convertZodType(catchDef.innerType))
-    }
-
-    case ZodTypeName.ZodPipeline: {
-      const pipelineDef = def as ZodPipelineDef
-      return withDesc(convertZodType(pipelineDef.in))
-    }
-
-    // -----------------------------------------------------------------------
-    // Any / Unknown – JSON Schema wildcard
-    // -----------------------------------------------------------------------
-    case ZodTypeName.ZodAny:
-    case ZodTypeName.ZodUnknown:
-      return withDesc({})
-
-    case ZodTypeName.ZodNever:
-      return withDesc({ not: {} })
-
-    case ZodTypeName.ZodVoid:
-      return withDesc({ type: 'null' })
-
-    // -----------------------------------------------------------------------
-    // Fallback
-    // -----------------------------------------------------------------------
-    default:
-      return withDesc({})
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Internal Zod type-name enum (mirrors Zod's internal ZodFirstPartyTypeKind)
-// ---------------------------------------------------------------------------
-
-const enum ZodTypeName {
-  ZodString = 'ZodString',
-  ZodNumber = 'ZodNumber',
-  ZodBigInt = 'ZodBigInt',
-  ZodBoolean = 'ZodBoolean',
-  ZodDate = 'ZodDate',
-  ZodUndefined = 'ZodUndefined',
-  ZodNull = 'ZodNull',
-  ZodAny = 'ZodAny',
-  ZodUnknown = 'ZodUnknown',
-  ZodNever = 'ZodNever',
-  ZodVoid = 'ZodVoid',
-  ZodArray = 'ZodArray',
-  ZodObject = 'ZodObject',
-  ZodUnion = 'ZodUnion',
-  ZodDiscriminatedUnion = 'ZodDiscriminatedUnion',
-  ZodIntersection = 'ZodIntersection',
-  ZodTuple = 'ZodTuple',
-  ZodRecord = 'ZodRecord',
-  ZodMap = 'ZodMap',
-  ZodSet = 'ZodSet',
-  ZodFunction = 'ZodFunction',
-  ZodLazy = 'ZodLazy',
-  ZodLiteral = 'ZodLiteral',
-  ZodEnum = 'ZodEnum',
-  ZodEffects = 'ZodEffects',
-  ZodNativeEnum = 'ZodNativeEnum',
-  ZodOptional = 'ZodOptional',
-  ZodNullable = 'ZodNullable',
-  ZodDefault = 'ZodDefault',
-  ZodCatch = 'ZodCatch',
-  ZodPromise = 'ZodPromise',
-  ZodBranded = 'ZodBranded',
-  ZodPipeline = 'ZodPipeline',
-  ZodReadonly = 'ZodReadonly',
-}
-
-// ---------------------------------------------------------------------------
-// Internal Zod _def structure typings (narrow only what we access)
-// ---------------------------------------------------------------------------
-
-interface ZodTypeDef {
-  typeName: string
-  description?: string
-}
-
-interface ZodLiteralDef extends ZodTypeDef {
-  value: unknown
-}
-
-interface ZodEnumDef extends ZodTypeDef {
-  values: string[]
-}
-
-interface ZodNativeEnumDef extends ZodTypeDef {
-  values: object
-}
-
-interface ZodArrayDef extends ZodTypeDef {
-  type: ZodSchema
-}
-
-interface ZodTupleDef extends ZodTypeDef {
-  items: ZodSchema[]
-}
-
-interface ZodObjectDef extends ZodTypeDef {
-  shape: () => Record<string, ZodSchema>
-}
-
-interface ZodRecordDef extends ZodTypeDef {
-  valueType: ZodSchema
-}
-
-interface ZodUnionDef extends ZodTypeDef {
-  options: unknown
-}
-
-interface ZodDiscriminatedUnionDef extends ZodTypeDef {
-  options: unknown
-}
-
-interface ZodIntersectionDef extends ZodTypeDef {
-  left: ZodSchema
-  right: ZodSchema
-}
-
-interface ZodOptionalDef extends ZodTypeDef {
-  innerType: ZodSchema
-}
-
-interface ZodNullableDef extends ZodTypeDef {
-  innerType: ZodSchema
-}
-
-interface ZodDefaultDef extends ZodTypeDef {
-  innerType: ZodSchema
-  defaultValue: () => unknown
-}
-
-interface ZodEffectsDef extends ZodTypeDef {
-  schema: ZodSchema
-}
-
-interface ZodBrandedDef extends ZodTypeDef {
-  type: ZodSchema
-}
-
-interface ZodReadonlyDef extends ZodTypeDef {
-  innerType: ZodSchema
-}
-
-interface ZodCatchDef extends ZodTypeDef {
-  innerType: ZodSchema
-}
-
-interface ZodPipelineDef extends ZodTypeDef {
-  in: ZodSchema
-}