@effect-uai/core 0.8.0 → 0.10.0

package/src/tool/Tool.ts

@@ -1,7 +1,8 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-import { Effect, Schema, Stream } from "effect"
+import { Effect, Match, Schema } from "effect"
 import type { ToolCall, ToolCallOutput } from "../domain/Items.js"
 import { toolCallOutput } from "../domain/Items.js"
+import { serializeValue } from "./ToolResult.js"
 
 export class ToolError extends Schema.TaggedErrorClass<ToolError>("@betalyra/effect-uai/ToolError")(
   "ToolError",
@@ -13,6 +14,59 @@ export class ToolError extends Schema.TaggedErrorClass<ToolError>("@betalyra/eff
   },
 ) {}
 
+/**
+ * One Standard Schema validation issue, carried on `ToolValidationError`.
+ * Mirrors `StandardSchemaV1.Issue`; `path` is left as `unknown` elements
+ * because Standard Schema path segments may be symbols or `{ key }` objects.
+ */
+const ToolValidationIssue = Schema.Struct({
+  message: Schema.String,
+  path: Schema.optional(Schema.Array(Schema.Unknown)),
+})
+
+/**
+ * The model's `arguments` for a call failed the tool's `inputSchema`. Distinct
+ * from `ToolError` (malformed JSON, runtime crash) so callers can tell a
+ * contract violation apart from a parse or execution failure, and so the
+ * structured `issues` survive instead of being flattened into a message string.
+ */
+export class ToolValidationError extends Schema.TaggedErrorClass<ToolValidationError>(
+  "@betalyra/effect-uai/ToolValidationError",
+)("ToolValidationError", {
+  call_id: Schema.String,
+  tool: Schema.String,
+  issues: Schema.Array(ToolValidationIssue),
+}) {}
+
+/**
+ * The deliberate "speak to the model" failure sentinel. A tool's `run` that
+ * fails with a `ToolFailed` (or a bare `string`, its sugar) is absorbed by
+ * `Toolkit.run` into a `ToolResult.Failure` the model reads and adapts to,
+ * instead of ending the run. Every other error type propagates typed on the
+ * executor's stream. `kind` overrides the synthesized `Failure.kind`
+ * (default `"tool_failed"`) so a tool can hand the model a distinguishable
+ * category (`"not_found"`, `"rate_limited"`) without a new result variant.
+ */
+export class ToolFailed extends Schema.TaggedErrorClass<ToolFailed>(
+  "@betalyra/effect-uai/ToolFailed",
+)("ToolFailed", {
+  message: Schema.String,
+  kind: Schema.optional(Schema.String),
+}) {}
+
+/**
+ * Fail a tool's `run` with a model-visible message (optionally a `kind`).
+ * `yield* Tool.fail("page not found", { kind: "not_found" })` inside a
+ * `run`'s `Effect.gen`; the executor absorbs it as `ToolResult.Failure`.
+ */
+export const fail = (
+  message: string,
+  options?: { readonly kind?: string },
+): Effect.Effect<never, ToolFailed> =>
+  Effect.fail(
+    new ToolFailed({ message, ...(options?.kind !== undefined ? { kind: options.kind } : {}) }),
+  )
+
 /**
  * Schemas accepted on `Tool.inputSchema`. Must implement both Standard
  * Schema validation and JSON Schema conversion (for rendering tool
@@ -33,8 +87,7 @@ export type ToolInputSchema<Input = unknown> = StandardSchemaV1<unknown, Input>
 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"]>
+  Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema))
 
 /**
  * Use any schema library that implements both Standard Schema (validation)
@@ -56,11 +109,56 @@ export const fromStandardSchema = <S extends StandardSchemaV1 & StandardJSONSche
 ): S & ToolInputSchema<StandardSchemaV1.InferOutput<S>> =>
   schema as S & ToolInputSchema<StandardSchemaV1.InferOutput<S>>
 
-export type Tool<Name extends string, Input, Output, R = never> = {
+/**
+ * Input schema for a tool that takes no arguments. Renders a clean
+ * `{ type: "object", properties: {} }`; validation accepts anything and
+ * yields `{}`. Use it instead of `fromEffectSchema(Schema.Struct({}))`,
+ * which renders a degenerate `anyOf` (object-or-array) that strict
+ * providers like Gemini reject.
+ */
+export const noInput: ToolInputSchema<Record<string, never>> = {
+  "~standard": {
+    version: 1,
+    vendor: "effect-uai",
+    validate: () => ({ value: {} }),
+    jsonSchema: {
+      input: () => ({ type: "object", properties: {} }),
+      output: () => ({ type: "object", properties: {} }),
+    },
+  },
+}
+
+/**
+ * Emit one intermediate `Event` from inside a tool's `run`. Backed by the
+ * executor's per-call queue, so it returns an `Effect` (backpressure) and
+ * composes with `Stream.runForEach(emit)`.
+ */
+export type Emit<Event> = (event: Event) => Effect.Effect<void>
+
+/**
+ * A model-visible tool with a local `Effect` executor. `run` computes the
+ * model-facing `Output`; emitting progress is a side channel via `emit`. A
+ * plain tool never calls `emit` (its `Event` is irrelevant); a streaming tool
+ * emits intermediate `Event`s that flow to the consumer as
+ * `ToolEvent.Progress` in real time.
+ *
+ * This is one of four tool *kinds*, discriminated by `_tag`. The other three
+ * (`ProviderTool`, `SignalTool`, `InteractionTool`) are model-visible but have
+ * no local executor — see their constructors below. `Tool` keeps its name (and
+ * the `Tool.make` constructor) because the local kind is by far the common one.
+ */
+export type Tool<Name extends string, Input, Event, Output, E = unknown, R = never> = {
+  readonly _tag: "LocalTool"
   readonly name: Name
   readonly description: string
   readonly inputSchema: ToolInputSchema<Input>
-  readonly run: (input: Input) => Effect.Effect<Output, unknown, R>
+  readonly run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output, E, R>
+  /**
+   * Bound on this tool's emit queue. Unbounded when omitted. Per-tool because
+   * backpressure depends on how a given tool emits, unlike `concurrency`
+   * (cross-tool, on `Toolkit.run`'s options).
+   */
+  readonly emitBufferSize?: number
   /**
    * Whether the provider should render this tool with its strict-mode
    * flag (OpenAI's `strict: true`, etc). Default: true. The framework
@@ -70,6 +168,70 @@ export type Tool<Name extends string, Input, Output, R = never> = {
   readonly strict?: boolean
 }
 
+/**
+ * A provider-hosted tool: visible to the model and executed by the *provider*
+ * (native web search, code execution, RAG grounding), never by this process.
+ * It has no local `run`; `provider`/`config` tell the provider adapter how to
+ * render it. Passing it to `Toolkit.run` yields a `non_local_tool` result.
+ */
+export type ProviderTool<Name extends string, Input, Provider extends string, Config> = {
+  readonly _tag: "ProviderTool"
+  readonly name: Name
+  readonly description: string
+  readonly inputSchema: ToolInputSchema<Input>
+  readonly provider: Provider
+  readonly config: Config
+  readonly strict?: boolean
+}
+
+/**
+ * A typed request for the agent loop to change control flow (escalate, pause,
+ * schedule, hand off). Model-visible and decodable (`decodeArgs`) but never
+ * locally executed — the loop intercepts the call in `onTurnComplete` and acts
+ * on it, so there is no fake `run`. `Toolkit.run` reports it as `non_local_tool`.
+ */
+export type SignalTool<Name extends string, Input> = {
+  readonly _tag: "SignalTool"
+  readonly name: Name
+  readonly description: string
+  readonly inputSchema: ToolInputSchema<Input>
+}
+
+/**
+ * A typed request for an external actor (user, channel, frontend) to respond
+ * before the loop resumes. Like `SignalTool` it is decode-only, but its
+ * lifecycle differs: the loop usually stops/pauses and resumes later by
+ * appending a `function_call_output` once the actor replies.
+ */
+export type InteractionTool<Name extends string, Input> = {
+  readonly _tag: "InteractionTool"
+  readonly name: Name
+  readonly description: string
+  readonly inputSchema: ToolInputSchema<Input>
+}
+
+/** A local (executable) tool of any shape. Readability alias. */
+export type AnyLocalTool<E = any, R = any> = Tool<string, any, any, any, E, R>
+
+/** Any of the four model-visible tool kinds. */
+export type AnyTool<E = any, R = any> =
+  | Tool<string, any, any, any, E, R>
+  | ProviderTool<string, any, string, any>
+  | SignalTool<string, any>
+  | InteractionTool<string, any>
+
+/** A model-visible tool that carries a decodable input schema (every kind). */
+export type DecodableTool<Input> = {
+  readonly name: string
+  readonly inputSchema: ToolInputSchema<Input>
+}
+
+/** Extract the `R` of a local tool; non-local kinds contribute `never`. */
+export type ToolR<T> = T extends Tool<string, any, any, any, any, infer R> ? R : never
+
+/** Extract the `E` of a local tool; non-local kinds contribute `never`. */
+export type ToolE<T> = T extends Tool<string, any, any, any, infer E, any> ? E : never
+
 /**
  * Provider-agnostic tool descriptor. Each provider maps `inputSchema`
  * to its own wire field (OpenAI → `parameters`, Anthropic →
@@ -82,87 +244,190 @@ export type ToolDescriptor = {
   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.Progress`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 type 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
-}
+/** A model-visible tool with a local `Effect` executor. */
+export const make = <Name extends string, Input, Event, Output, E = never, R = never>(
+  spec: Omit<Tool<Name, Input, Event, Output, E, R>, "_tag">,
+): Tool<Name, Input, Event, Output, E, R> => ({ _tag: "LocalTool", ...spec })
 
-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 })
+/**
+ * A provider-hosted tool (native web search, code execution, RAG grounding).
+ * No local executor — `provider`/`config` drive the provider adapter's
+ * rendering. The model sees it; `Toolkit.run` reports it as `non_local_tool`.
+ */
+export const provider = <Name extends string, Input, Provider extends string, Config>(
+  spec: Omit<ProviderTool<Name, Input, Provider, Config>, "_tag">,
+): ProviderTool<Name, Input, Provider, Config> => ({ _tag: "ProviderTool", ...spec })
 
-export type AnyStreamingTool<R = any> = StreamingTool<string, any, any, any, R>
-export type AnyPlainTool<R = any> = Tool<string, any, any, R>
-export type AnyTool<R = any> = AnyStreamingTool<R> | AnyPlainTool<R>
+/**
+ * A typed control-flow signal to the agent loop (escalate, pause, schedule,
+ * hand off). Decode-only: the loop interprets the call rather than executing a
+ * handler, so there is no `run`.
+ */
+export const signal = <Name extends string, Input>(
+  spec: Omit<SignalTool<Name, Input>, "_tag">,
+): SignalTool<Name, Input> => ({ _tag: "SignalTool", ...spec })
 
-export const isStreamingTool = <R>(t: AnyTool<R>): t is AnyStreamingTool<R> =>
-  "_kind" in t && t._kind === "streaming"
+/**
+ * A typed request for an external actor to respond before the loop resumes
+ * (frontend, Telegram, CLI prompt). Decode-only; the loop stops/pauses and
+ * resumes by appending the actor's `function_call_output`.
+ */
+export const interaction = <Name extends string, Input>(
+  spec: Omit<InteractionTool<Name, Input>, "_tag">,
+): InteractionTool<Name, Input> => ({ _tag: "InteractionTool", ...spec })
 
 /**
- * Render any-kind tools (mixed plain and streaming) to provider-agnostic
- * descriptors. Accepts the union type so a single list can carry both
- * plain and streaming tools.
+ * Return a copy of a tool under a new `name`. Useful for resolving a name
+ * clash before combining tools into one `Toolkit`. Literal-preserving, so the
+ * renamed tool keys the toolkit record under the new name statically.
  */
-export const toDescriptors = <R>(tools: ReadonlyArray<AnyTool<R>>): ReadonlyArray<ToolDescriptor> =>
+export const withName = <N extends string, T extends AnyTool>(
+  tool: T,
+  name: N,
+): Omit<T, "name"> & { readonly name: N } => ({ ...tool, name })
+
+/**
+ * Replace a local tool's `run`, keeping its model-facing definition (name,
+ * description, schema, `_tag`) identical. The new `run`'s `input` is typed from
+ * the original tool, so override/mock need no annotation:
+ *
+ *   const safe = { ...toolkit, send_email: Tool.withRun(toolkit.send_email,
+ *     ({ to }) => Effect.succeed({ status: "dry-run", to })) }
+ *
+ * Descriptors stay identical to production, so a mocked toolkit can't drift
+ * from the contract the model sees.
+ */
+export const withRun = <
+  Name extends string,
+  Input,
+  Event,
+  Output,
+  E,
+  R,
+  Output2,
+  E2 = never,
+  R2 = never,
+>(
+  tool: Tool<Name, Input, Event, Output, E, R>,
+  run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output2, E2, R2>,
+): Tool<Name, Input, Event, Output2, E2, R2> => ({ ...tool, run })
+
+/** Render tools to provider-agnostic descriptors. Every kind is model-visible. */
+export const toDescriptors = (tools: ReadonlyArray<AnyTool>): 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 }
+    // `strict` only exists on local/provider kinds; signals/interactions omit it.
+    const strict = "strict" in tool ? tool.strict : undefined
+    return strict !== undefined
+      ? { name: tool.name, description: tool.description, inputSchema, strict }
       : { name: tool.name, description: tool.description, inputSchema }
   })
 
-const toToolError = (call: ToolCall, toolName: string, message: string) => (cause: unknown) =>
-  new ToolError({ call_id: call.call_id, tool: toolName, message, cause })
+/**
+ * Render a `Toolkit` (a name-indexed record of tools) to descriptors, treating
+ * an absent toolkit as no tools. The normalization point the `LanguageModel`
+ * boundary uses so a request can carry the toolkit itself instead of a
+ * pre-rendered descriptor array. Lives here (not on `Toolkit`) to keep providers
+ * free of a dependency on the toolkit module — it only needs the tool values.
+ */
+export const descriptorsOf = (
+  toolkit?: Readonly<Record<string, AnyTool>>,
+): ReadonlyArray<ToolDescriptor> =>
+  toolkit === undefined ? [] : toDescriptors(Object.values(toolkit))
+
+/**
+ * Outcome of decoding a call's `arguments` against a tool's `inputSchema`,
+ * as data so both the typed (`decodeArgs`) and result-synthesizing
+ * (`Toolkit.run`) callers can translate it their own way.
+ */
+export type DecodeResult<Input> =
+  | { readonly _tag: "ok"; readonly input: Input }
+  | { readonly _tag: "parseError" }
+  | { readonly _tag: "invalid"; readonly issues: ReadonlyArray<StandardSchemaV1.Issue> }
+
+const VALIDATION_THREW: ReadonlyArray<StandardSchemaV1.Issue> = [
+  { message: "input schema validation threw" },
+]
+
+/**
+ * Parse and validate a call's `arguments`. Empty arguments normalize to
+ * `{}` (some models emit `""` for zero-arg tools); a throwing validator is
+ * captured, not propagated. Never fails.
+ */
+export const decodeCallInput = <Input>(
+  tool: DecodableTool<Input>,
+  call: ToolCall,
+): Effect.Effect<DecodeResult<Input>> => {
+  const raw = call.arguments.trim() === "" ? "{}" : call.arguments
+  return Effect.try({
+    // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+    try: () => JSON.parse(raw) as unknown,
+    catch: (): DecodeResult<Input> => ({ _tag: "parseError" }),
+  }).pipe(
+    Effect.flatMap((parsed) =>
+      Effect.tryPromise({
+        try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
+        catch: (): DecodeResult<Input> => ({ _tag: "invalid", issues: VALIDATION_THREW }),
+      }).pipe(
+        Effect.map(
+          (result): DecodeResult<Input> =>
+            result.issues !== undefined
+              ? { _tag: "invalid", issues: result.issues }
+              : { _tag: "ok", input: result.value },
+        ),
+      ),
+    ),
+    Effect.catch((captured: DecodeResult<Input>) => Effect.succeed(captured)),
+  )
+}
+
+/**
+ * Decode and validate a function_call's JSON `arguments` against the tool's
+ * own `inputSchema`, yielding the typed input. The decode-only half of
+ * `execute` - reach for it when you intercept a call to translate it into a
+ * control-flow decision rather than running the tool's `run`.
+ *
+ * Malformed JSON fails with `ToolError`; a parsed body that violates
+ * `inputSchema` fails with `ToolValidationError` carrying the issues.
+ */
+export const decodeArgs = <Input>(
+  tool: DecodableTool<Input>,
+  call: ToolCall,
+): Effect.Effect<Input, ToolError | ToolValidationError> =>
+  decodeCallInput(tool, call).pipe(
+    Effect.flatMap(
+      Match.type<DecodeResult<Input>>().pipe(
+        Match.tag("ok", ({ input }) => Effect.succeed(input)),
+        Match.tag("parseError", () =>
+          Effect.fail(
+            new ToolError({
+              call_id: call.call_id,
+              tool: tool.name,
+              message: "Failed to parse JSON arguments",
+            }),
+          ),
+        ),
+        Match.tag("invalid", ({ issues }) =>
+          Effect.fail(new ToolValidationError({ call_id: call.call_id, tool: tool.name, issues })),
+        ),
+        Match.exhaustive,
+      ),
+    ),
+  )
 
 /**
  * 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.
+ * function_call_output item. Single-shot: intermediate events emitted by
+ * `run` are discarded (use `Toolkit.run` to stream them).
  */
-export const execute = <Name extends string, Input, Output, R>(
-  tool: Tool<Name, Input, Output, R>,
+export const execute = <Name extends string, Input, Event, Output, E, R>(
+  tool: Tool<Name, Input, Event, Output, E, R>,
   call: ToolCall,
-): Effect.Effect<ToolCallOutput, 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 toolCallOutput(call.call_id, JSON.stringify(output))
-  })
+): Effect.Effect<ToolCallOutput, E | ToolError | ToolValidationError, R> =>
+  decodeArgs(tool, call).pipe(
+    Effect.flatMap((input) => tool.run(input, () => Effect.void)),
+    Effect.map((output) => toolCallOutput(call.call_id, serializeValue(output))),
+  )

package/src/tool/ToolEvent.ts

@@ -7,6 +7,11 @@
  *
  * Recipes thread `ToolEvent.Output.result` through `continueWithResults` and
  * apply `toToolCallOutput` when appending to history.
+ *
+ * Demux note: `Progress` carries `call_id` / `tool` at the top level, while
+ * `Output` nests them inside `result` (the `ToolResult` already carries both).
+ * A consumer grouping events by call reads `e.call_id` for `Progress` and
+ * `e.result.call_id` for `Output`.
  */
 import { Data } from "effect"
 import type { ToolResult } from "./ToolResult.js"

package/src/tool/ToolResult.ts

@@ -66,22 +66,49 @@ export const denied = (call: ToolCall, reason?: string): ToolResult =>
 export const cancelled = (call: ToolCall, reason?: string): ToolResult =>
   failed(call, "cancelled", reason)
 
-/** Tool's own execution failed (parse error, schema, runtime crash). */
+/** Tool's own execution failed (JSON parse error, runtime crash). */
 export const executionError = (call: ToolCall, reason: string): ToolResult =>
   failed(call, "execution_error", reason)
 
+/**
+ * The model called a tool that is visible to it but has no local executor — a
+ * provider-hosted, signal, or interaction tool routed through `Toolkit.run`.
+ * Distinct from `unknown_tool` (no such tool at all): the loop is expected to
+ * intercept these kinds before execution, so this kind flags a missing handler.
+ */
+export const nonLocalTool = (call: ToolCall, reason?: string): ToolResult =>
+  failed(
+    call,
+    "non_local_tool",
+    reason ?? `Tool "${call.name}" is visible to the model but has no local executor`,
+  )
+
+/**
+ * The model's `arguments` failed the tool's input schema. Distinct kind from
+ * `execution_error` so recipes can tell a contract violation apart from a
+ * runtime crash.
+ */
+export const validationError = (call: ToolCall, reason?: string): ToolResult =>
+  failed(call, "input_validation_error", reason ?? "Tool input failed schema validation")
+
 // ---------------------------------------------------------------------------
 // Wire conversion - the one place structured → string happens.
 // ---------------------------------------------------------------------------
 
+/**
+ * Serialize a success value for the wire. A `string` passes through raw
+ * (models read plain text best; JSON.stringify would quote and escape it);
+ * `undefined` becomes `"null"`; anything else is JSON.
+ */
+export const serializeValue = (value: unknown): string =>
+  typeof value === "string" ? value : JSON.stringify(value ?? null)
+
+/** The one failure shape the model sees: `{"error":{"kind","message"}}`. */
+const failureBody = (kind: string, message?: string): string =>
+  JSON.stringify({ error: message !== undefined ? { kind, message } : { kind } })
+
 export const toToolCallOutput = (r: ToolResult): ToolCallOutput =>
   ToolResult.$match(r, {
-    Ok: (v) => toolCallOutput(v.call_id, JSON.stringify(v.value)),
-    Failure: (f) =>
-      toolCallOutput(
-        f.call_id,
-        JSON.stringify(
-          f.reason !== undefined ? { kind: f.kind, reason: f.reason } : { kind: f.kind },
-        ),
-      ),
+    Ok: (v) => toolCallOutput(v.call_id, serializeValue(v.value)),
+    Failure: (f) => toolCallOutput(f.call_id, failureBody(f.kind, f.reason)),
   })