refactor(core): unify v2 tool architecture (#31168)

packages/core/src/tool/tool.ts

@@ -0,0 +1,136 @@
+export * as Tool from "./tool"
+
+import { Tool as LlmTool, ToolFailure, ToolOutput, type ToolCall } from "@opencode-ai/llm"
+import { Effect, Schema } from "effect"
+import type { AgentV2 } from "../agent"
+import type { SessionMessage } from "../session/message"
+import type { SessionSchema } from "../session/schema"
+
+export interface Context {
+  readonly sessionID: SessionSchema.ID
+  readonly agent: AgentV2.ID
+  readonly assistantMessageID: SessionMessage.ID
+  readonly toolCallID: string
+}
+
+export type SchemaType<A> = Schema.Codec<A, any, never, never>
+
+declare const TypeId: unique symbol
+
+export interface Tool<Input extends SchemaType<any>, Output extends SchemaType<any>> {
+  readonly [TypeId]: {
+    readonly _Input: Input
+    readonly _Output: Output
+  }
+}
+
+export type AnyTool = Tool<any, any>
+export const Failure = ToolFailure
+export type Failure = ToolFailure
+
+export class RegistrationError extends Schema.TaggedErrorClass<RegistrationError>()("Tool.RegistrationError", {
+  name: Schema.String,
+  message: Schema.String,
+}) {}
+
+export type Content =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "file"; readonly data: string; readonly mime: string; readonly name?: string }
+
+type Config<Input extends SchemaType<any>, Output extends SchemaType<any>> = {
+  readonly description: string
+  readonly input: Input
+  readonly output: Output
+  readonly execute: (
+    input: Schema.Schema.Type<Input>,
+    context: Context,
+  ) => Effect.Effect<Schema.Schema.Type<Output>, ToolFailure>
+  readonly toModelOutput?: (input: {
+    readonly input: Schema.Schema.Type<Input>
+    readonly output: Output["Encoded"]
+  }) => ReadonlyArray<Content>
+}
+
+type Runtime = {
+  readonly permission?: string
+  readonly definition: (name: string) => ReturnType<typeof LlmTool.toDefinitions>[number]
+  readonly settle: (call: ToolCall, context: Context) => Effect.Effect<ToolOutput, ToolFailure>
+}
+
+const runtimes = new WeakMap<AnyTool, Runtime>()
+
+export function make<Input extends SchemaType<any>, Output extends SchemaType<any>>(
+  config: Config<Input, Output>,
+): Tool<Input, Output> {
+  const tool = Object.freeze({}) as Tool<Input, Output>
+  const definitions = new Map<string, ReturnType<typeof LlmTool.toDefinitions>[number]>()
+  runtimes.set(tool, {
+    definition: (name) => {
+      const cached = definitions.get(name)
+      if (cached) return cached
+      const definition = LlmTool.toDefinitions({
+        [name]: LlmTool.make({ description: config.description, parameters: config.input, success: config.output }),
+      })[0]
+      definitions.set(name, definition)
+      return definition
+    },
+    settle: (call, context) =>
+      Schema.decodeUnknownEffect(config.input)(call.input).pipe(
+        Effect.mapError((error) => new ToolFailure({ message: `Invalid tool input: ${error.message}` })),
+        Effect.flatMap((input) =>
+          config.execute(input, context).pipe(
+            Effect.flatMap((output) =>
+              Schema.encodeEffect(config.output)(output).pipe(
+                Effect.mapError(
+                  (error) =>
+                    new ToolFailure({
+                      message: `Tool returned an invalid value for its output schema: ${error.message}`,
+                    }),
+                ),
+              ),
+            ),
+            Effect.map((output) =>
+              ToolOutput.make(
+                output,
+                config.toModelOutput?.({ input, output }).map((part) =>
+                  part.type === "text"
+                    ? { type: "text" as const, text: part.text }
+                    : {
+                        type: "file" as const,
+                        source: { type: "data" as const, data: part.data },
+                        mime: part.mime,
+                        name: part.name,
+                      },
+                ) ?? (typeof output === "string" ? [{ type: "text", text: output }] : []),
+              ),
+            ),
+          ),
+        ),
+      ),
+  })
+  return tool
+}
+
+export const validateName = (name: string) =>
+  /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name)
+    ? Effect.void
+    : Effect.fail(new RegistrationError({ name, message: `Invalid tool name: ${name}` }))
+
+export const withPermission = <Input extends SchemaType<any>, Output extends SchemaType<any>>(
+  tool: Tool<Input, Output>,
+  permission: string,
+) => {
+  const decorated = Object.freeze({}) as Tool<Input, Output>
+  runtimes.set(decorated, { ...runtimeOf(tool), permission })
+  return decorated
+}
+
+export const permission = (tool: AnyTool, name: string) => runtimeOf(tool).permission ?? name
+export const definition = (name: string, tool: AnyTool) => runtimeOf(tool).definition(name)
+export const settle = (tool: AnyTool, call: ToolCall, context: Context) => runtimeOf(tool).settle(call, context)
+
+function runtimeOf(tool: AnyTool) {
+  const runtime = runtimes.get(tool)
+  if (!runtime) throw new TypeError("Invalid Core Tool value")
+  return runtime
+}