@llm4ts/core 0.1.0

package/src/tools/Tool.ts

@@ -0,0 +1,379 @@
+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.TaggedErrorClass<InvalidToolSchema>()(
+  "InvalidSchema",
+  {
+    message: Schema.String
+  }
+) {}
+
+export class InvalidToolParameters extends Schema.TaggedErrorClass<InvalidToolParameters>()(
+  "InvalidParameters",
+  {
+    message: Schema.String
+  }
+) {}
+
+export class DuplicateToolName extends Schema.TaggedErrorClass<DuplicateToolName>()(
+  "DuplicateToolName",
+  {
+    name: Schema.String
+  }
+) {
+  get message(): string {
+    return `Tool already registered: ${this.name}`
+  }
+}
+
+export class ToolSandboxViolation extends Schema.TaggedErrorClass<ToolSandboxViolation>()(
+  "SandboxViolation",
+  {
+    message: Schema.String
+  }
+) {}
+
+export class ToolExecutionFailed extends Schema.TaggedErrorClass<ToolExecutionFailed>()(
+  "ExecutionFailed",
+  {
+    message: Schema.String
+  }
+) {}
+
+export class ToolSchemaGenerationFailed extends Schema.TaggedErrorClass<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

@@ -0,0 +1,106 @@
+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

@@ -0,0 +1,224 @@
+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
+      }