@effect-uai/core 0.9.0 → 0.11.0

package/src/tool/Tool.ts

@@ -1,7 +1,8 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-import { Effect, Schema } 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",
@@ -37,6 +38,35 @@ export class ToolValidationError extends Schema.TaggedErrorClass<ToolValidationE
   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
@@ -79,6 +109,25 @@ export const fromStandardSchema = <S extends StandardSchemaV1 & StandardJSONSche
 ): S & ToolInputSchema<StandardSchemaV1.InferOutput<S>> =>
   schema as S & ToolInputSchema<StandardSchemaV1.InferOutput<S>>
 
+/**
+ * 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
@@ -98,12 +147,12 @@ export type Emit<Event> = (event: Event) => Effect.Effect<void>
  * 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, R = never> = {
+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, emit: Emit<Event>) => 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`
@@ -162,11 +211,11 @@ export type InteractionTool<Name extends string, Input> = {
 }
 
 /** A local (executable) tool of any shape. Readability alias. */
-export type AnyLocalTool<R = any> = Tool<string, any, any, any, R>
+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<R = any> =
-  | Tool<string, any, any, any, R>
+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>
@@ -178,7 +227,10 @@ export type DecodableTool<Input> = {
 }
 
 /** Extract the `R` of a local tool; non-local kinds contribute `never`. */
-export type ToolR<T> = T extends Tool<string, any, any, any, infer R> ? R : 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`
@@ -192,37 +244,114 @@ export type ToolDescriptor = {
   readonly strict?: boolean
 }
 
+const resolveInputSchema = (
+  schema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>,
+): ToolInputSchema<any> =>
+  Schema.isSchema(schema)
+    ? fromEffectSchema(schema as Schema.Codec<any, any, never, any>)
+    : (schema as ToolInputSchema<any>)
+
 /** A model-visible tool with a local `Effect` executor. */
-export const make = <Name extends string, Input, Event, Output, R = never>(
-  spec: Omit<Tool<Name, Input, Event, Output, R>, "_tag">,
-): Tool<Name, Input, Event, Output, R> => ({ _tag: "LocalTool", ...spec })
+export const make: {
+  <
+    Name extends string,
+    S extends Schema.Codec<any, any, never, any>,
+    Event,
+    Output,
+    E = never,
+    R = never,
+  >(
+    spec: Omit<Tool<Name, S["Type"], Event, Output, E, R>, "_tag" | "inputSchema"> & {
+      readonly inputSchema: S
+    },
+  ): Tool<Name, S["Type"], Event, Output, E, R>
+  <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>
+} = (
+  spec: Omit<AnyLocalTool, "_tag" | "inputSchema"> & {
+    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
+  },
+): AnyLocalTool => ({
+  _tag: "LocalTool",
+  ...spec,
+  inputSchema: resolveInputSchema(spec.inputSchema),
+})
 
 /**
  * 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 const provider: {
+  <
+    Name extends string,
+    S extends Schema.Codec<any, any, never, any>,
+    Provider extends string,
+    Config,
+  >(
+    spec: Omit<ProviderTool<Name, S["Type"], Provider, Config>, "_tag" | "inputSchema"> & {
+      readonly inputSchema: S
+    },
+  ): ProviderTool<Name, S["Type"], Provider, Config>
+  <Name extends string, Input, Provider extends string, Config>(
+    spec: Omit<ProviderTool<Name, Input, Provider, Config>, "_tag">,
+  ): ProviderTool<Name, Input, Provider, Config>
+} = (
+  spec: Omit<ProviderTool<string, any, string, any>, "_tag" | "inputSchema"> & {
+    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
+  },
+): ProviderTool<string, any, string, any> => ({
+  _tag: "ProviderTool",
+  ...spec,
+  inputSchema: resolveInputSchema(spec.inputSchema),
+})
 
 /**
  * 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 signal: {
+  <Name extends string, S extends Schema.Codec<any, any, never, any>>(
+    spec: Omit<SignalTool<Name, S["Type"]>, "_tag" | "inputSchema"> & {
+      readonly inputSchema: S
+    },
+  ): SignalTool<Name, S["Type"]>
+  <Name extends string, Input>(spec: Omit<SignalTool<Name, Input>, "_tag">): SignalTool<Name, Input>
+} = (
+  spec: Omit<SignalTool<string, any>, "_tag" | "inputSchema"> & {
+    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
+  },
+): SignalTool<string, any> => ({
+  _tag: "SignalTool",
+  ...spec,
+  inputSchema: resolveInputSchema(spec.inputSchema),
+})
 
 /**
  * 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 })
+export const interaction: {
+  <Name extends string, S extends Schema.Codec<any, any, never, any>>(
+    spec: Omit<InteractionTool<Name, S["Type"]>, "_tag" | "inputSchema"> & {
+      readonly inputSchema: S
+    },
+  ): InteractionTool<Name, S["Type"]>
+  <Name extends string, Input>(
+    spec: Omit<InteractionTool<Name, Input>, "_tag">,
+  ): InteractionTool<Name, Input>
+} = (
+  spec: Omit<InteractionTool<string, any>, "_tag" | "inputSchema"> & {
+    readonly inputSchema: ToolInputSchema<any> | Schema.Codec<any, any, never, any>
+  },
+): InteractionTool<string, any> => ({
+  _tag: "InteractionTool",
+  ...spec,
+  inputSchema: resolveInputSchema(spec.inputSchema),
+})
 
 /**
  * Return a copy of a tool under a new `name`. Useful for resolving a name
@@ -245,23 +374,54 @@ export const withName = <N extends string, T extends AnyTool>(
  * 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, R, Output2, R2 = never>(
-  tool: Tool<Name, Input, Event, Output, R>,
-  run: (input: Input, emit: Emit<Event>) => Effect.Effect<Output2, unknown, R2>,
-): Tool<Name, Input, Event, Output2, R2> => ({ ...tool, run })
+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 })
+
+/** True for provider-hosted tools — the kind a provider renders natively. */
+export const isProviderTool = (tool: AnyTool): tool is ProviderTool<string, any, string, any> =>
+  tool._tag === "ProviderTool"
 
-/** Render tools to provider-agnostic descriptors. Every kind is model-visible. */
+/**
+ * The `ProviderTool`s in a toolkit, for a provider adapter to render as its
+ * native hosted-tool entries (web search, code execution, grounding). The other
+ * kinds render as function declarations via `descriptorsOf`.
+ */
+export const providerToolsOf = (
+  toolkit?: Readonly<Record<string, AnyTool>>,
+): ReadonlyArray<ProviderTool<string, any, string, any>> =>
+  toolkit === undefined ? [] : Object.values(toolkit).filter(isProviderTool)
+
+/**
+ * Render tools to provider-agnostic descriptors. `ProviderTool`s are excluded:
+ * they are provider-hosted and must never leak into the function-declaration
+ * list — each adapter renders them natively via `providerToolsOf`. Every other
+ * kind is model-visible as a declaration.
+ */
 export const toDescriptors = (tools: ReadonlyArray<AnyTool>): ReadonlyArray<ToolDescriptor> =>
-  tools.map((tool) => {
-    const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({
-      target: "draft-2020-12",
+  tools
+    .filter((tool) => !isProviderTool(tool))
+    .map((tool) => {
+      const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({
+        target: "draft-2020-12",
+      })
+      // `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 }
     })
-    // `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 }
-  })
 
 /**
  * Render a `Toolkit` (a name-indexed record of tools) to descriptors, treating
@@ -275,8 +435,51 @@ export const descriptorsOf = (
 ): ReadonlyArray<ToolDescriptor> =>
   toolkit === undefined ? [] : toDescriptors(Object.values(toolkit))
 
-const toToolError = (call: ToolCall, toolName: string, message: string) => (cause: unknown) =>
-  new ToolError({ call_id: call.call_id, tool: toolName, message, cause })
+/**
+ * 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
@@ -291,28 +494,26 @@ export const decodeArgs = <Input>(
   tool: DecodableTool<Input>,
   call: ToolCall,
 ): Effect.Effect<Input, ToolError | ToolValidationError> =>
-  Effect.gen(function* () {
-    const parsed = yield* Effect.try({
-      // inputSchema validates through Standard Schema, not Effect Schema, so its
-      // JSON codecs don't apply; the parse is separate to keep ToolError (bad
-      // JSON) distinct from ToolValidationError (bad shape).
-      // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
-      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 ToolValidationError({
-        call_id: call.call_id,
-        tool: tool.name,
-        issues: result.issues,
-      })
-    }
-    return result.value
-  })
+  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
@@ -320,15 +521,11 @@ export const decodeArgs = <Input>(
  * 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, Event, Output, R>(
-  tool: Tool<Name, Input, Event, 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 | ToolValidationError, R> =>
+): Effect.Effect<ToolCallOutput, E | ToolError | ToolValidationError, R> =>
   decodeArgs(tool, call).pipe(
-    Effect.flatMap((input) =>
-      tool
-        .run(input, () => Effect.void)
-        .pipe(Effect.mapError(toToolError(call, tool.name, "Tool execution failed"))),
-    ),
-    Effect.map((output) => toolCallOutput(call.call_id, JSON.stringify(output))),
+    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

@@ -95,14 +95,20 @@ export const validationError = (call: ToolCall, reason?: string): ToolResult =>
 // 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)),
   })