@effect-uai/core 0.1.0

package/src/tool/Tool.ts

@@ -0,0 +1,150 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
+import { Effect, Schema, Stream } from "effect"
+import type { FunctionCall, FunctionCallOutput } from "../domain/Items.js"
+import { functionCallOutput } from "../domain/Items.js"
+
+export class ToolError extends Schema.TaggedErrorClass<ToolError>("@betalyra/effect-uai/ToolError")(
+  "ToolError",
+  {
+    call_id: Schema.String,
+    tool: Schema.String,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+  },
+) {}
+
+/**
+ * Schemas accepted on `Tool.inputSchema`. Must implement both Standard
+ * Schema validation and JSON Schema conversion (for rendering tool
+ * descriptors to provider request bodies).
+ *
+ * Any Standard-Schema-compliant library that exposes both interfaces
+ * works directly: Zod 4+, Valibot, ArkType, Effect Schema (after
+ * `fromEffectSchema`), etc.
+ */
+export type ToolInputSchema<Input = unknown> = StandardSchemaV1<unknown, Input> &
+  StandardJSONSchemaV1<unknown, Input>
+
+/**
+ * Convenience wrapper for Effect Schema users - adds both the
+ * `validate` and `jsonSchema` extensions to a plain Effect Schema so it
+ * can be used as a `Tool.inputSchema`.
+ */
+export const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(
+  schema: S,
+): S & ToolInputSchema<S["Type"]> =>
+  Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema)) as unknown as S &
+    ToolInputSchema<S["Type"]>
+
+export interface Tool<Name extends string, Input, Output, R = never> {
+  readonly name: Name
+  readonly description: string
+  readonly inputSchema: ToolInputSchema<Input>
+  readonly run: (input: Input) => Effect.Effect<Output, unknown, R>
+  /**
+   * Whether the provider should render this tool with its strict-mode
+   * flag (OpenAI's `strict: true`, etc). Default: true. The framework
+   * never rewrites the schema; if the rendered JSON Schema isn't
+   * compatible, the provider returns an error.
+   */
+  readonly strict?: boolean
+}
+
+/**
+ * Provider-agnostic tool descriptor. Each provider maps `inputSchema`
+ * to its own wire field (OpenAI → `parameters`, Anthropic →
+ * `input_schema`). Built from a `Tool` by `Toolkit.toDescriptors`.
+ */
+export interface ToolDescriptor {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: Record<string, unknown>
+  readonly strict?: boolean
+}
+
+export const make = <Name extends string, Input, Output, R = never>(
+  spec: Tool<Name, Input, Output, R>,
+): Tool<Name, Input, Output, R> => spec
+
+// ---------------------------------------------------------------------------
+// Streaming tools
+//
+// `run` returns a `Stream<Event>` instead of an `Effect<Output>`. Events
+// flow through to the consumer as `ToolEvent.Intermediate`s in real time;
+// at end-of-stream `finalize(events)` reduces them to the model-facing
+// `Output`. Sub-agents, slow downloads with progress, recipe streamers.
+// ---------------------------------------------------------------------------
+
+export interface StreamingTool<Name extends string, Input, Event, Output, R = never> {
+  readonly _kind: "streaming"
+  readonly name: Name
+  readonly description: string
+  readonly inputSchema: ToolInputSchema<Input>
+  readonly run: (input: Input) => Stream.Stream<Event, unknown, R>
+  readonly finalize: (events: ReadonlyArray<Event>) => Output
+  readonly strict?: boolean
+}
+
+export const streaming = <Name extends string, Input, Event, Output, R = never>(
+  spec: Omit<StreamingTool<Name, Input, Event, Output, R>, "_kind">,
+): StreamingTool<Name, Input, Event, Output, R> => ({ _kind: "streaming", ...spec })
+
+export type AnyStreamingTool = StreamingTool<string, any, any, any, never>
+export type AnyPlainTool = Tool<string, any, any, never>
+export type AnyKindTool = AnyStreamingTool | AnyPlainTool
+
+export const isStreamingTool = (t: AnyKindTool): t is AnyStreamingTool =>
+  "_kind" in t && t._kind === "streaming"
+
+/**
+ * Render any-kind tools (mixed plain and streaming) to provider-agnostic
+ * descriptors. Mirrors `Toolkit.toDescriptors` but accepts the union type
+ * so a single list can carry both kinds.
+ */
+export const toDescriptors = (
+  tools: ReadonlyArray<AnyKindTool>,
+): ReadonlyArray<ToolDescriptor> =>
+  tools.map((tool) => {
+    const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({
+      target: "draft-2020-12",
+    })
+    return tool.strict !== undefined
+      ? { name: tool.name, description: tool.description, inputSchema, strict: tool.strict }
+      : { name: tool.name, description: tool.description, inputSchema }
+  })
+
+const toToolError = (call: FunctionCall, toolName: string, message: string) => (cause: unknown) =>
+  new ToolError({ call_id: call.call_id, tool: toolName, message, cause })
+
+/**
+ * Decode and validate the JSON arguments of a function_call against the
+ * tool's input schema, run the tool, and serialize the output into a
+ * function_call_output item.
+ */
+export const execute = <Name extends string, Input, Output, R>(
+  tool: Tool<Name, Input, Output, R>,
+  call: FunctionCall,
+): Effect.Effect<FunctionCallOutput, ToolError, R> =>
+  Effect.gen(function* () {
+    const parsed = yield* Effect.try({
+      try: () => JSON.parse(call.arguments) as unknown,
+      catch: toToolError(call, tool.name, "Failed to parse JSON arguments"),
+    })
+
+    const result = yield* Effect.promise(() =>
+      Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
+    )
+    if (result.issues !== undefined) {
+      return yield* new ToolError({
+        call_id: call.call_id,
+        tool: tool.name,
+        message: "Tool input failed schema validation",
+        cause: result.issues,
+      })
+    }
+
+    const output = yield* tool
+      .run(result.value)
+      .pipe(Effect.mapError(toToolError(call, tool.name, "Tool execution failed")))
+    return functionCallOutput(call.call_id, JSON.stringify(output))
+  })

package/src/tool/ToolEvent.ts

@@ -0,0 +1,37 @@
+/**
+ * The event type emitted by `Toolkit.executeAllWithResolver`.
+ *
+ *   - ApprovalRequested : gated calls before resolver returns
+ *   - Intermediate      : per-element passthrough from a streaming tool's run
+ *   - Output            : terminal result (carries a structured ToolResult)
+ *
+ * Recipes thread `ToolEvent.Output.result` through `nextStateFrom` and apply
+ * `toFunctionCallOutput` when appending to history.
+ */
+import type { ToolResult } from "./Outcome.js"
+
+export type ToolEvent =
+  | {
+      readonly _tag: "ApprovalRequested"
+      readonly call_id: string
+      readonly tool: string
+      readonly arguments: string
+    }
+  | {
+      readonly _tag: "Intermediate"
+      readonly call_id: string
+      readonly tool: string
+      readonly data: unknown
+    }
+  | { readonly _tag: "Output"; readonly result: ToolResult }
+
+export const isApprovalRequested = (
+  e: ToolEvent,
+): e is Extract<ToolEvent, { _tag: "ApprovalRequested" }> => e._tag === "ApprovalRequested"
+
+export const isIntermediate = (
+  e: ToolEvent,
+): e is Extract<ToolEvent, { _tag: "Intermediate" }> => e._tag === "Intermediate"
+
+export const isOutput = (e: ToolEvent): e is Extract<ToolEvent, { _tag: "Output" }> =>
+  e._tag === "Output"

package/src/tool/Toolkit.test.ts

@@ -0,0 +1,45 @@
+import { Effect, Schema } from "effect"
+import { describe, expect, it } from "vitest"
+import * as Tool from "./Tool.js"
+import * as Toolkit from "./Toolkit.js"
+
+describe("Toolkit.toDescriptors", () => {
+  const GetWeatherInput = Schema.Struct({ city: Schema.String })
+
+  const getWeather = Tool.make({
+    name: "get_weather",
+    description: "Look up the current temperature for a city.",
+    inputSchema: Tool.fromEffectSchema(GetWeatherInput),
+    run: ({ city }) => Effect.succeed({ city, tempC: 18 }),
+  })
+
+  it("renders the input schema as a JSON Schema document", () => {
+    const [desc] = Toolkit.toDescriptors(Toolkit.make([getWeather]))
+    expect(desc?.name).toBe("get_weather")
+    expect(desc?.description).toBe("Look up the current temperature for a city.")
+    expect(desc?.inputSchema).toMatchObject({
+      type: "object",
+      properties: { city: { type: "string" } },
+      required: ["city"],
+    })
+  })
+
+  it("includes strict flag only when set on the tool", () => {
+    const strictTool = Tool.make({
+      name: "strict_one",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(GetWeatherInput),
+      run: () => Effect.succeed({}),
+      strict: true,
+    })
+    const looseTool = Tool.make({
+      name: "loose_one",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(GetWeatherInput),
+      run: () => Effect.succeed({}),
+    })
+    const [s, l] = Toolkit.toDescriptors(Toolkit.make([strictTool, looseTool]))
+    expect(s?.strict).toBe(true)
+    expect(l).not.toHaveProperty("strict")
+  })
+})

package/src/tool/Toolkit.ts

@@ -0,0 +1,228 @@
+import { Array as Arr, Effect, Match, Ref, Stream } from "effect"
+import * as Loop from "../loop/Loop.js"
+import type { FunctionCall } from "../domain/Items.js"
+import {
+  type AnyKindTool,
+  type AnyPlainTool,
+  type AnyStreamingTool,
+  isStreamingTool,
+  type Tool,
+  type ToolDescriptor,
+} from "./Tool.js"
+import {
+  type ToolDecision,
+  type ToolResult,
+  execute as executeDecision,
+  executionError,
+  rejected,
+} from "./Outcome.js"
+import type { ToolEvent } from "./ToolEvent.js"
+import { isOutput } from "./ToolEvent.js"
+
+export type AnyTool = Tool<string, any, any, any>
+
+export type Toolkit<Tools extends ReadonlyArray<AnyTool>> = {
+  readonly tools: Tools
+}
+
+export type ToolsR<Tools extends ReadonlyArray<AnyTool>> =
+  Tools[number] extends Tool<any, any, any, infer R> ? R : never
+
+export const make = <const Tools extends ReadonlyArray<AnyTool>>(tools: Tools): Toolkit<Tools> => ({
+  tools,
+})
+
+/**
+ * Render every tool in a toolkit to a provider-agnostic descriptor.
+ * `inputSchema` is the JSON Schema document produced by the tool's
+ * Standard Schema converter (draft 2020-12).
+ */
+export const toDescriptors = <Tools extends ReadonlyArray<AnyTool>>(
+  toolkit: Toolkit<Tools>,
+): ReadonlyArray<ToolDescriptor> =>
+  toolkit.tools.map((tool) => {
+    const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({
+      target: "draft-2020-12",
+    })
+    return tool.strict !== undefined
+      ? { name: tool.name, description: tool.description, inputSchema, strict: tool.strict }
+      : { name: tool.name, description: tool.description, inputSchema }
+  })
+
+// ---------------------------------------------------------------------------
+// Resolver-based executor. Streams `ToolEvent`s in real time, dispatches
+// streaming and plain tools uniformly, and lets the caller decide what
+// happens to each call (Execute or Reject) before execution.
+//
+// `executeAllWithResolver` is the general primitive. `executeAllStream` is
+// the no-resolver shortcut.
+// ---------------------------------------------------------------------------
+
+export type Resolver = (call: FunctionCall) => Effect.Effect<ToolDecision>
+
+export interface ExecuteOptions {
+  readonly concurrency?: number | "unbounded"
+}
+
+export const executeAllWithResolver = (
+  tools: ReadonlyArray<AnyKindTool>,
+  calls: ReadonlyArray<FunctionCall>,
+  resolve: Resolver,
+  options?: ExecuteOptions,
+): Stream.Stream<ToolEvent> =>
+  Stream.fromIterable(calls).pipe(
+    Stream.flatMap(
+      (call) =>
+        Stream.unwrap(
+          resolve(call).pipe(Effect.map((decision) => dispatch(tools, call, decision))),
+        ),
+      { concurrency: options?.concurrency ?? "unbounded" },
+    ),
+  )
+
+/** No-resolver shortcut: every call gets `Execute`. */
+export const executeAll = (
+  tools: ReadonlyArray<AnyKindTool>,
+  calls: ReadonlyArray<FunctionCall>,
+  options?: ExecuteOptions,
+): Stream.Stream<ToolEvent> =>
+  executeAllWithResolver(tools, calls, () => Effect.succeed(executeDecision), options)
+
+const dispatch = (
+  tools: ReadonlyArray<AnyKindTool>,
+  call: FunctionCall,
+  decision: ToolDecision,
+): Stream.Stream<ToolEvent> =>
+  Match.value(decision).pipe(
+    Match.tag("Execute", () => runOne(tools, call)),
+    Match.tag("Reject", (d) =>
+      Stream.succeed<ToolEvent>({ _tag: "Output", result: d.result }),
+    ),
+    Match.exhaustive,
+  )
+
+const valueResult = (call: FunctionCall, tool: string, value: unknown): ToolResult => ({
+  _tag: "Value",
+  call_id: call.call_id,
+  tool,
+  value,
+})
+
+const runOne = (
+  tools: ReadonlyArray<AnyKindTool>,
+  call: FunctionCall,
+): Stream.Stream<ToolEvent> => {
+  const tool = tools.find((t) => t.name === call.name)
+  if (tool === undefined) {
+    // Graceful: emit a synthetic Failure so OTHER calls in this turn
+    // still execute. LLMs hallucinate tool names; MCP tools come and go.
+    return Stream.succeed<ToolEvent>({
+      _tag: "Output",
+      result: rejected(call, "unknown_tool", `No tool registered with name "${call.name}"`),
+    })
+  }
+  if (isStreamingTool(tool)) return runStreaming(tool, call)
+  return runPlain(tool, call)
+}
+
+const runPlain = (
+  tool: AnyPlainTool,
+  call: FunctionCall,
+): Stream.Stream<ToolEvent> =>
+  Stream.fromEffect(
+    Effect.gen(function* () {
+      const parsed = yield* Effect.try({
+        try: () => JSON.parse(call.arguments) as unknown,
+        catch: () => "json_parse_error" as const,
+      })
+      const validated = yield* Effect.tryPromise({
+        try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
+        catch: () => "validation_threw" as const,
+      })
+      if (validated.issues !== undefined) {
+        return executionError(call, "Tool input failed schema validation")
+      }
+      const output = yield* tool.run(validated.value)
+      return valueResult(call, tool.name, output)
+    }).pipe(
+      Effect.catchCause(() => Effect.succeed(executionError(call, "Tool execution failed"))),
+      Effect.map((result) => ({ _tag: "Output", result }) satisfies ToolEvent),
+    ),
+  )
+
+const runStreaming = (
+  tool: AnyStreamingTool,
+  call: FunctionCall,
+): Stream.Stream<ToolEvent> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const parsed = yield* Effect.try({
+        try: () => JSON.parse(call.arguments) as unknown,
+        catch: () => "json_parse_error" as const,
+      })
+      const validated = yield* Effect.tryPromise({
+        try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
+        catch: () => "validation_threw" as const,
+      })
+      if (validated.issues !== undefined) {
+        return Stream.succeed<ToolEvent>({
+          _tag: "Output",
+          result: executionError(call, "Tool input failed schema validation"),
+        })
+      }
+
+      // Real-time: tap each event into a Ref as it flows; emit one
+      // Intermediate per event; then concat one synthetic Output element
+      // built from the accumulated Ref via `finalize`.
+      const ref = yield* Ref.make<Array<unknown>>([])
+      const intermediates = tool.run(validated.value).pipe(
+        Stream.tap((event) => Ref.update(ref, Arr.append(event))),
+        Stream.map(
+          (data) =>
+            ({
+              _tag: "Intermediate",
+              call_id: call.call_id,
+              tool: tool.name,
+              data,
+            }) satisfies ToolEvent,
+        ),
+      )
+      const output = Stream.fromEffect(
+        Ref.get(ref).pipe(
+          Effect.map(
+            (events) =>
+              ({
+                _tag: "Output",
+                result: valueResult(call, tool.name, tool.finalize(events)),
+              }) satisfies ToolEvent,
+          ),
+        ),
+      )
+      return intermediates.pipe(Stream.concat(output))
+    }),
+  ).pipe(
+    Stream.catchCause(() =>
+      Stream.succeed<ToolEvent>({
+        _tag: "Output",
+        result: executionError(call, "Tool execution failed"),
+      }),
+    ),
+  )
+
+// ---------------------------------------------------------------------------
+// `nextStateFrom` - bridge from a `Stream<ToolEvent>` to the loop's emit
+// shape. Drains the stream to the consumer in real-time, taps every
+// `Output` into an internal Ref, and at end-of-stream emits
+// `Loop.next(build(results))`. Recipe never sees the Ref.
+// ---------------------------------------------------------------------------
+
+export const nextStateFrom = <S>(
+  stream: Stream.Stream<ToolEvent>,
+  build: (results: ReadonlyArray<ToolResult>) => S,
+): Stream.Stream<Loop.Event<ToolEvent, S>> =>
+  Loop.nextAfterFold(
+    stream,
+    [] as ReadonlyArray<ToolResult>,
+    (acc, e) => (isOutput(e) ? Arr.append(acc, e.result) : acc),
+    build,
+  )