@llm4ts/core 2.54.0 → 3.0.0

package/src/tools/Tool.ts

@@ -1,376 +0,0 @@
-import * as Effect from "effect/Effect"
-import * as Schema from "effect/Schema"
-import { Capability as CapabilitySchema, type Capability } from "../Capability.ts"
-import { ToolDefinition, type JsonSchema, type LlmProvider } from "../Models.ts"
-import {
-  isJsonRecord,
-  jsonArray,
-  jsonField,
-  jsonStringField,
-  type JsonValue
-} from "../providers/CliSupport.ts"
-
-export class InvalidToolSchema extends Schema.TaggedError<InvalidToolSchema>()("InvalidSchema", {
-  message: Schema.String
-}) {}
-
-export class InvalidToolParameters extends Schema.TaggedError<InvalidToolParameters>()(
-  "InvalidParameters",
-  {
-    message: Schema.String
-  }
-) {}
-
-export class DuplicateToolName extends Schema.TaggedError<DuplicateToolName>()(
-  "DuplicateToolName",
-  {
-    name: Schema.String
-  }
-) {
-  get message(): string {
-    return `Tool already registered: ${this.name}`
-  }
-}
-
-export class ToolSandboxViolation extends Schema.TaggedError<ToolSandboxViolation>()(
-  "SandboxViolation",
-  {
-    message: Schema.String
-  }
-) {}
-
-export class ToolExecutionFailed extends Schema.TaggedError<ToolExecutionFailed>()(
-  "ExecutionFailed",
-  {
-    message: Schema.String
-  }
-) {}
-
-export class ToolSchemaGenerationFailed extends Schema.TaggedError<ToolSchemaGenerationFailed>()(
-  "SchemaGenerationFailed",
-  {
-    message: Schema.String
-  }
-) {}
-
-export const ToolExecutionError = Schema.Union([
-  InvalidToolSchema,
-  InvalidToolParameters,
-  DuplicateToolName,
-  ToolSandboxViolation,
-  ToolExecutionFailed,
-  ToolSchemaGenerationFailed
-])
-export type ToolExecutionError = typeof ToolExecutionError.Type
-
-export const ToolSandbox = Schema.Literals([
-  "WorkspaceReadWrite",
-  "WorkspaceReadOnly",
-  "Unrestricted"
-])
-export type ToolSandbox = typeof ToolSandbox.Type
-
-export class ToolDescriptor extends Schema.Class<ToolDescriptor>("ToolDescriptor")({
-  name: Schema.String,
-  description: Schema.String,
-  parameters: Schema.Record(Schema.String, Schema.Json),
-  tags: Schema.ReadonlySet(Schema.String).pipe(
-    Schema.withConstructorDefault(Effect.succeed(new Set<string>()))
-  ),
-  sandbox: ToolSandbox.pipe(Schema.withConstructorDefault(Effect.succeed("WorkspaceReadWrite"))),
-  requires: Schema.Array(CapabilitySchema).pipe(
-    Schema.withConstructorDefault(Effect.succeed(Object.freeze([])))
-  )
-}) {}
-
-export interface Tool {
-  readonly name: string
-  readonly description: string
-  readonly parameters: JsonSchema
-  readonly execute: (parameters: JsonValue) => Effect.Effect<JsonValue, ToolExecutionError>
-  readonly tags: ReadonlySet<string>
-  readonly sandbox: ToolSandbox
-  readonly requires: ReadonlyArray<Capability>
-}
-
-export interface ToolOptions {
-  readonly name: string
-  readonly description: string
-  readonly parameters: JsonSchema
-  readonly execute: Tool["execute"]
-  readonly tags?: Iterable<string>
-  readonly sandbox?: ToolSandbox
-  readonly requires?: ReadonlyArray<Capability>
-}
-
-export const makeTool = (options: ToolOptions): Tool => ({
-  name: options.name,
-  description: options.description,
-  parameters: options.parameters,
-  execute: options.execute,
-  tags: new Set(options.tags ?? []),
-  sandbox: options.sandbox ?? "WorkspaceReadWrite",
-  requires: options.requires ?? []
-})
-
-export const toolDefinition = (tool: Tool): ToolDefinition =>
-  ToolDefinition.make({
-    name: tool.name,
-    description: tool.description,
-    parameters: tool.parameters
-  })
-
-const splitParameters = (raw: string): ReadonlyArray<string> => {
-  const parameters: Array<string> = []
-  let start = 0
-  let depth = 0
-  for (let index = 0; index < raw.length; index += 1) {
-    const character = raw.charAt(index)
-    if (character === "[" || character === "<" || character === "(") {
-      depth += 1
-    } else if (character === "]" || character === ">" || character === ")") {
-      depth -= 1
-    } else if (character === "," && depth === 0) {
-      parameters.push(raw.slice(start, index).trim())
-      start = index + 1
-    }
-  }
-  const last = raw.slice(start).trim()
-  return last.length === 0 ? parameters : [...parameters, last]
-}
-
-interface ParsedParameter {
-  readonly name: string
-  readonly type: string
-  readonly required: boolean
-}
-
-const parseParameter = (raw: string): ParsedParameter | undefined => {
-  const match = /^(?:readonly\s+)?([A-Za-z_$][\w$]*)(\?)?\s*:\s*(.+?)(?:\s*=\s*.+)?$/.exec(raw)
-  const name = match?.[1]
-  const type = match?.[3]?.trim()
-  if (name === undefined || type === undefined) {
-    return undefined
-  }
-  const optional = match?.[2] === "?" || raw.includes("=") || /^(?:Option|Optional)[[<]/.test(type)
-  return {
-    name,
-    type,
-    required: !optional
-  }
-}
-
-const genericInner = (type: string, names: ReadonlyArray<string>): string | undefined => {
-  for (const name of names) {
-    const squarePrefix = `${name}[`
-    const anglePrefix = `${name}<`
-    if (type.startsWith(squarePrefix) && type.endsWith("]")) {
-      return type.slice(squarePrefix.length, -1).trim()
-    }
-    if (type.startsWith(anglePrefix) && type.endsWith(">")) {
-      return type.slice(anglePrefix.length, -1).trim()
-    }
-  }
-  return undefined
-}
-
-const schemaForType = (rawType: string): JsonValue => {
-  const type = rawType.trim()
-  switch (type) {
-    case "String":
-    case "string":
-      return { type: "string" }
-    case "Boolean":
-    case "boolean":
-      return { type: "boolean" }
-    case "Int":
-    case "Long":
-    case "Short":
-    case "Byte":
-    case "BigInt":
-    case "int":
-    case "integer":
-      return { type: "integer" }
-    case "Double":
-    case "Float":
-    case "BigDecimal":
-    case "number":
-      return { type: "number" }
-  }
-
-  const optional = genericInner(type, ["Option", "Optional"])
-  if (optional !== undefined) {
-    return schemaForType(optional)
-  }
-  const array = genericInner(type, ["List", "Seq", "Vector", "Set", "Array", "ReadonlyArray"])
-  if (array !== undefined) {
-    return {
-      type: "array",
-      items: schemaForType(array)
-    }
-  }
-  const map = genericInner(type, ["Map", "Record"])
-  if (map !== undefined) {
-    const parts = splitParameters(map)
-    return {
-      type: "object",
-      additionalProperties: schemaForType(parts.at(-1) ?? "object")
-    }
-  }
-  return { type: "object" }
-}
-
-export const schemaFromMethodSignature = (
-  signature: string
-): Effect.Effect<JsonSchema, ToolSchemaGenerationFailed> => {
-  const parametersText = signature.match(
-    /(?:def|function)?\s*[A-Za-z_$][\w$]*\s*\((.*)\)\s*(?::.*)?$/
-  )?.[1]
-  if (parametersText === undefined) {
-    return Effect.fail(
-      ToolSchemaGenerationFailed.make({
-        message: "Unsupported signature. Expected a method declaration or definition"
-      })
-    )
-  }
-  const parameters = splitParameters(parametersText).map(parseParameter)
-  if (parameters.some((parameter) => parameter === undefined)) {
-    return Effect.fail(
-      ToolSchemaGenerationFailed.make({
-        message: "Failed to parse one or more method parameters"
-      })
-    )
-  }
-
-  const properties: Record<string, JsonValue> = {}
-  const required: Array<string> = []
-  for (const parameter of parameters) {
-    if (parameter !== undefined) {
-      properties[parameter.name] = schemaForType(parameter.type)
-      if (parameter.required) {
-        required.push(parameter.name)
-      }
-    }
-  }
-  return Effect.succeed({
-    type: "object",
-    properties,
-    required,
-    additionalProperties: false
-  })
-}
-
-export const toolFromMethodSignature = Effect.fn("@llm4ts/core/tools/Tool.fromMethodSignature")(
-  function* (
-    options: Omit<ToolOptions, "parameters"> & {
-      readonly signature: string
-    }
-  ) {
-    const parameters = yield* schemaFromMethodSignature(options.signature)
-    return makeTool({
-      ...options,
-      parameters
-    })
-  }
-)
-
-const valueMatchesType = (value: JsonValue, expected: string): boolean => {
-  switch (expected) {
-    case "string":
-      return typeof value === "string"
-    case "boolean":
-      return typeof value === "boolean"
-    case "integer":
-      return typeof value === "number" && Number.isInteger(value)
-    case "number":
-      return typeof value === "number"
-    case "array":
-      return Array.isArray(value)
-    case "object":
-      return isJsonRecord(value)
-    default:
-      return true
-  }
-}
-
-export const validateToolParameters = Effect.fn("@llm4ts/core/tools/Tool.validateParameters")(
-  function* (
-    schema: JsonSchema,
-    parameters: JsonValue
-  ): Effect.fn.Return<void, ToolExecutionError> {
-    if (!isJsonRecord(schema)) {
-      return yield* InvalidToolParameters.make({
-        message: "Tool schema must be a JSON object"
-      })
-    }
-    if (!isJsonRecord(parameters)) {
-      return yield* InvalidToolParameters.make({
-        message: "Tool arguments must be a JSON object"
-      })
-    }
-
-    const required = jsonArray(jsonField(schema, "required")).flatMap((value) =>
-      typeof value === "string" ? [value] : []
-    )
-    const missing = required.filter((name) => parameters[name] === undefined).sort()
-    if (missing.length > 0) {
-      return yield* InvalidToolParameters.make({
-        message: `Missing required parameters: ${missing.join(", ")}`
-      })
-    }
-
-    const properties = jsonField(schema, "properties")
-    for (const [name, value] of Object.entries(parameters)) {
-      const property = jsonField(properties, name)
-      if (property !== undefined) {
-        const expected = jsonStringField(property, "type") ?? "object"
-        if (!valueMatchesType(value, expected)) {
-          return yield* InvalidToolParameters.make({
-            message: `Invalid type for '${name}'. Expected: ${expected}`
-          })
-        }
-      }
-    }
-  }
-)
-
-export const toolsToOpenAI = (tools: ReadonlyArray<Tool>): JsonValue =>
-  tools.map((tool) => ({
-    type: "function",
-    function: {
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.parameters
-    }
-  }))
-
-export const toolsToAnthropic = (tools: ReadonlyArray<Tool>): JsonValue =>
-  tools.map((tool) => ({
-    name: tool.name,
-    description: tool.description,
-    input_schema: tool.parameters
-  }))
-
-export const toolsToGemini = (tools: ReadonlyArray<Tool>): JsonValue => ({
-  functionDeclarations: tools.map((tool) => ({
-    name: tool.name,
-    description: tool.description,
-    parameters: tool.parameters
-  }))
-})
-
-export const toolsToProviderFormat = (
-  provider: LlmProvider,
-  tools: ReadonlyArray<Tool>
-): JsonValue => {
-  switch (provider) {
-    case "OpenAI":
-      return toolsToOpenAI(tools)
-    case "Anthropic":
-      return toolsToAnthropic(tools)
-    case "GeminiApi":
-      return toolsToGemini(tools)
-    default:
-      return []
-  }
-}

package/src/tools/ToolCallingExecutor.ts

@@ -1,106 +0,0 @@
-import * as Effect from "effect/Effect"
-import * as Schema from "effect/Schema"
-import { InvalidRequestError, type LlmError } from "../Errors.ts"
-import type { LlmServiceShape } from "../LlmService.ts"
-import { LlmResponse, type ToolCallResponse } from "../Models.ts"
-import { jsonText } from "../providers/CliSupport.ts"
-import { toolDefinition, type Tool } from "./Tool.ts"
-import { toolResultValue, type ToolRegistryShape, type ToolResult } from "./ToolRegistry.ts"
-
-export class ToolLoopConfig extends Schema.Class<ToolLoopConfig>("ToolLoopConfig")({
-  maxIterations: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(8))),
-  maxDenials: Schema.optionalKey(Schema.Int),
-  maxConcurrency: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(1)))
-}) {}
-
-export const buildToolFollowUpPrompt = (
-  previousPrompt: string,
-  response: ToolCallResponse,
-  results: ReadonlyArray<ToolResult>
-): string => {
-  const renderedResults = results
-    .map(
-      (result) => `tool_call_id=${result.toolCallId} result=${jsonText(toolResultValue(result))}`
-    )
-    .join("\n")
-  return (
-    `${previousPrompt}\n\n` +
-    `Assistant requested tool execution with finishReason='${response.finishReason}'.\n` +
-    `Tool results:\n${renderedResults}\n\n` +
-    "Continue the task. If no further tools are needed, respond with final user-facing content.\n"
-  )
-}
-
-export const runToolCallingLoop = Effect.fn("@llm4ts/core/tools/ToolCallingExecutor.run")(
-  function* (
-    prompt: string,
-    tools: ReadonlyArray<Tool>,
-    llmService: LlmServiceShape,
-    registry: ToolRegistryShape,
-    config: ToolLoopConfig = ToolLoopConfig.make({})
-  ): Effect.fn.Return<LlmResponse, LlmError> {
-    if (config.maxIterations < 0) {
-      return yield* InvalidRequestError.make({
-        message: `Tool loop maxIterations must be non-negative; received ${config.maxIterations}`
-      })
-    }
-    if (config.maxDenials !== undefined && config.maxDenials < 0) {
-      return yield* InvalidRequestError.make({
-        message: `Tool loop maxDenials must be non-negative; received ${config.maxDenials}`
-      })
-    }
-
-    const definitions = tools.map(toolDefinition)
-    const loop = (
-      currentPrompt: string,
-      iteration: number,
-      denials: number
-    ): Effect.Effect<LlmResponse, LlmError> => {
-      if (iteration >= config.maxIterations) {
-        return Effect.fail(
-          InvalidRequestError.make({
-            message: `Tool call loop reached max iterations (${config.maxIterations})`
-          })
-        )
-      }
-
-      return Effect.flatMap(llmService.executeWithTools(currentPrompt, definitions), (response) => {
-        if (response.toolCalls.length === 0) {
-          return Effect.succeed(
-            LlmResponse.make({
-              content: response.content ?? "",
-              metadata: {
-                finish_reason: response.finishReason,
-                tool_iterations: String(iteration)
-              }
-            })
-          )
-        }
-
-        return Effect.flatMap(
-          registry.executeAll(response.toolCalls, config.maxConcurrency),
-          (results) => {
-            const totalDenials = denials + results.filter((result) => result.denied).length
-            if (config.maxDenials !== undefined && totalDenials >= config.maxDenials) {
-              return Effect.fail(
-                InvalidRequestError.make({
-                  message:
-                    "Tool loop exceeded the capability-denial budget " + `(${config.maxDenials})`
-                })
-              )
-            }
-            return Effect.suspend(() =>
-              loop(
-                buildToolFollowUpPrompt(currentPrompt, response, results),
-                iteration + 1,
-                totalDenials
-              )
-            )
-          }
-        )
-      })
-    }
-
-    return yield* loop(prompt, 0, 0)
-  }
-)

package/src/tools/ToolRegistry.ts

@@ -1,224 +0,0 @@
-import * as Context from "effect/Context"
-import * as Effect from "effect/Effect"
-import * as Layer from "effect/Layer"
-import * as Ref from "effect/Ref"
-import * as Schema from "effect/Schema"
-import { allows, currentGrants, type Capability } from "../Capability.ts"
-import { InvalidRequestError, ToolError } from "../Errors.ts"
-import type { LlmError } from "../Errors.ts"
-import type { ToolCall } from "../Models.ts"
-import type { JsonValue } from "../providers/CliSupport.ts"
-import {
-  DuplicateToolName,
-  validateToolParameters,
-  type Tool,
-  type ToolExecutionError
-} from "./Tool.ts"
-
-export class ToolSucceeded extends Schema.TaggedClass<ToolSucceeded>()("Succeeded", {
-  value: Schema.Json
-}) {}
-
-export class ToolFailed extends Schema.TaggedClass<ToolFailed>()("Failed", {
-  message: Schema.String
-}) {}
-
-export const ToolResultValue = Schema.Union([ToolSucceeded, ToolFailed])
-export type ToolResultValue = typeof ToolResultValue.Type
-
-export class ToolResult extends Schema.Class<ToolResult>("ToolResult")({
-  toolCallId: Schema.String,
-  result: ToolResultValue,
-  denied: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false)))
-}) {}
-
-export interface ToolRegistryShape {
-  readonly register: (tool: Tool) => Effect.Effect<void, ToolExecutionError>
-  readonly registerAll: (tools: ReadonlyArray<Tool>) => Effect.Effect<void, ToolExecutionError>
-  readonly get: (name: string) => Effect.Effect<Tool, LlmError>
-  readonly list: Effect.Effect<ReadonlyArray<Tool>>
-  readonly select: (prompt: string, limit?: number) => Effect.Effect<ReadonlyArray<Tool>>
-  readonly validate: (
-    call: ToolCall
-  ) => Effect.Effect<readonly [tool: Tool, parameters: JsonValue], LlmError>
-  readonly execute: (call: ToolCall) => Effect.Effect<ToolResult, LlmError>
-  readonly executeAll: (
-    calls: ReadonlyArray<ToolCall>,
-    concurrency?: number
-  ) => Effect.Effect<ReadonlyArray<ToolResult>, LlmError>
-}
-
-export class ToolRegistry extends Context.Service<ToolRegistry, ToolRegistryShape>()(
-  "@llm4ts/core/tools/ToolRegistry"
-) {}
-
-const capabilityName = (capability: Capability): string =>
-  capability._tag === "Exec" ? `Exec(${capability.command})` : capability._tag
-
-const promptWords = (prompt: string): ReadonlySet<string> =>
-  new Set(
-    prompt
-      .toLowerCase()
-      .split(/[^a-z0-9_]+/)
-      .filter((word) => word.length > 0)
-  )
-
-const toolScore = (tool: Tool, words: ReadonlySet<string>): number => {
-  let score = 0
-  for (const word of words) {
-    score += tool.name.toLowerCase().includes(word) ? 5 : 0
-    score += [...tool.tags].some((tag) => tag.toLowerCase() === word) ? 4 : 0
-    score += tool.description.toLowerCase().includes(word) ? 2 : 0
-  }
-  return score
-}
-
-const parseArguments = (call: ToolCall): Effect.Effect<JsonValue, ToolError> =>
-  Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Json))(call.arguments).pipe(
-    Effect.mapError((error) =>
-      ToolError.make({
-        toolName: call.name,
-        detail: `Invalid arguments JSON: ${String(error)}`
-      })
-    )
-  )
-
-export const makeToolRegistry = Effect.fn("@llm4ts/core/tools/ToolRegistry.make")(
-  function* (): Effect.fn.Return<ToolRegistryShape> {
-    const state = yield* Ref.make<ReadonlyMap<string, Tool>>(new Map())
-
-    const register = (tool: Tool): Effect.Effect<void, ToolExecutionError> =>
-      Ref.modify(state, (current) => {
-        if (current.has(tool.name)) {
-          return [false, current] as const
-        }
-        const next = new Map(current)
-        next.set(tool.name, tool)
-        return [true, next] as const
-      }).pipe(
-        Effect.flatMap((registered) =>
-          registered ? Effect.void : Effect.fail(DuplicateToolName.make({ name: tool.name }))
-        )
-      )
-
-    const registerAll = (tools: ReadonlyArray<Tool>): Effect.Effect<void, ToolExecutionError> =>
-      Effect.forEach(tools, register, {
-        discard: true
-      })
-
-    const get = (name: string): Effect.Effect<Tool, LlmError> =>
-      Effect.flatMap(Ref.get(state), (tools) => {
-        const tool = tools.get(name)
-        return tool === undefined
-          ? Effect.fail(
-              ToolError.make({
-                toolName: name,
-                detail: `Tool not found: ${name}`
-              })
-            )
-          : Effect.succeed(tool)
-      })
-
-    const list = Ref.get(state).pipe(
-      Effect.map((tools) =>
-        [...tools.values()].sort((left, right) => left.name.localeCompare(right.name))
-      )
-    )
-
-    const select = (prompt: string, limit = 8): Effect.Effect<ReadonlyArray<Tool>> =>
-      Effect.map(list, (tools) =>
-        tools
-          .map((tool) => ({
-            tool,
-            score: toolScore(tool, promptWords(prompt))
-          }))
-          .filter(({ score }) => score > 0)
-          .sort(
-            (left, right) =>
-              right.score - left.score || left.tool.name.localeCompare(right.tool.name)
-          )
-          .slice(0, Math.max(0, limit))
-          .map(({ tool }) => tool)
-      )
-
-    const validate = Effect.fn("@llm4ts/core/tools/ToolRegistry.validate")(function* (
-      call: ToolCall
-    ): Effect.fn.Return<readonly [tool: Tool, parameters: JsonValue], LlmError> {
-      const tool = yield* get(call.name)
-      const parameters = yield* parseArguments(call)
-      yield* validateToolParameters(tool.parameters, parameters).pipe(
-        Effect.mapError((error) =>
-          ToolError.make({
-            toolName: tool.name,
-            detail: error.message
-          })
-        )
-      )
-      return [tool, parameters]
-    })
-
-    const execute = Effect.fn("@llm4ts/core/tools/ToolRegistry.execute")(function* (
-      call: ToolCall
-    ): Effect.fn.Return<ToolResult, LlmError> {
-      const [tool, parameters] = yield* validate(call)
-      const grants = yield* currentGrants
-      const missing = tool.requires
-        .filter((capability) => !allows(grants, capability))
-        .sort((left, right) => capabilityName(left).localeCompare(capabilityName(right)))
-      if (missing.length > 0) {
-        return ToolResult.make({
-          toolCallId: call.id,
-          denied: true,
-          result: ToolFailed.make({
-            message:
-              `Tool '${tool.name}' requires ungranted capabilities: ` +
-              missing.map(capabilityName).join(", ")
-          })
-        })
-      }
-
-      const result = yield* Effect.result(tool.execute(parameters))
-      return ToolResult.make({
-        toolCallId: call.id,
-        result:
-          result._tag === "Success"
-            ? ToolSucceeded.make({ value: result.success })
-            : ToolFailed.make({ message: result.failure.message })
-      })
-    })
-
-    const executeAll = (
-      calls: ReadonlyArray<ToolCall>,
-      concurrency = 1
-    ): Effect.Effect<ReadonlyArray<ToolResult>, LlmError> =>
-      !Number.isInteger(concurrency) || concurrency <= 0
-        ? Effect.fail(
-            InvalidRequestError.make({
-              message: `Tool execution concurrency must be a positive integer; received ${concurrency}`
-            })
-          )
-        : Effect.forEach(calls, execute, {
-            concurrency
-          })
-
-    return {
-      register,
-      registerAll,
-      get,
-      list,
-      select,
-      validate,
-      execute,
-      executeAll
-    }
-  }
-)
-
-export const ToolRegistryLive = Layer.effect(ToolRegistry, makeToolRegistry())
-
-export const toolResultValue = (result: ToolResult): JsonValue =>
-  result.result._tag === "Succeeded"
-    ? result.result.value
-    : {
-        error: result.result.message
-      }