@effect-uai/core 0.18.0 → 0.19.0-dev-20261109183959

package/src/tool/Approval.test.ts

@@ -1,400 +0,0 @@
-/**
- * Tests for approval planners + history-reconciliation primitives. Exercises
- * the full HITL + streaming-tool stack end-to-end by composing approval plans
- * with `run`, with the four wire-shaped scenarios:
- *
- *   1. Approval        : gated calls approved → tools execute, structured Values
- *   2. Denial          : gated calls denied   → Failure(denied) results
- *   3. Cancellation    : missing verdicts     → Failure(cancelled) results
- *   4. Mixed + history : reconciliation via cancelAllPending
- *
- * Plus: hallucinated tool name (graceful Failure), unknown_tool kind.
- */
-import { Effect, Queue, Schema, Stream } from "effect"
-import { describe, expect, it } from "vitest"
-import * as Items from "../domain/Items.js"
-import { findUnansweredCalls, cancelAllPending, isReconciled } from "./HistoryCheck.js"
-import { type ToolResult, isFailure, isOk, toToolCallOutput } from "./ToolResult.js"
-import {
-  type ApprovalMapEntry,
-  type ApprovalDecision,
-  type Verdict,
-  fromMap,
-  fromQueue,
-} from "./Approval.js"
-import { fromEffectSchema, make as makeTool } from "./Tool.js"
-import { make as makeToolkit, run } from "./Toolkit.js"
-import { ToolEvent, isApprovalRequested, isProgress, isOutput } from "./ToolEvent.js"
-
-// ---------------------------------------------------------------------------
-// Three demo tools covering the matrix:
-//   - web_search      : streaming, no approval
-//   - bulk_email      : streaming, requires approval
-//   - delete_database : non-streaming, requires approval
-// ---------------------------------------------------------------------------
-
-const webSearch = makeTool({
-  name: "web_search",
-  description: "search",
-  inputSchema: fromEffectSchema(Schema.Struct({ query: Schema.String })),
-  run: ({ query }, emit) =>
-    Effect.gen(function* () {
-      const hits = [
-        { url: "a", title: `${query} 1` },
-        { url: "b", title: `${query} 2` },
-        { url: "c", title: `${query} 3` },
-      ]
-      yield* Stream.runForEach(Stream.fromIterable(hits), emit)
-      return { count: hits.length }
-    }),
-})
-
-const bulkEmail = makeTool({
-  name: "bulk_email",
-  description: "send",
-  inputSchema: fromEffectSchema(
-    Schema.Struct({ recipients: Schema.Array(Schema.String), subject: Schema.String }),
-  ),
-  run: ({ recipients }, emit) =>
-    Effect.gen(function* () {
-      yield* Effect.forEach(recipients, (_, i) =>
-        emit({ type: "progress" as const, sent: i + 1, total: recipients.length }),
-      )
-      return { status: "sent" as const, delivered: recipients.length }
-    }),
-})
-
-const deleteDatabase = makeTool({
-  name: "delete_database",
-  description: "drop",
-  inputSchema: fromEffectSchema(Schema.Struct({ name: Schema.String })),
-  run: ({ name }) => Effect.succeed({ status: "dropped", name }),
-})
-
-const allTools = makeToolkit(webSearch, bulkEmail, deleteDatabase)
-const SENSITIVE = new Set(["bulk_email", "delete_database"])
-const isSensitive = (call: Items.ToolCall) => SENSITIVE.has(call.name)
-
-const fc = (call_id: string, name: string, args: unknown): Items.ToolCall => ({
-  type: "function_call",
-  call_id,
-  name,
-  arguments: JSON.stringify(args),
-})
-
-const calls = [
-  fc("c1", "web_search", { query: "effect" }),
-  fc("c2", "bulk_email", { recipients: ["a@x", "b@x"], subject: "Hi" }),
-  fc("c3", "delete_database", { name: "prod" }),
-]
-
-const resultsFrom = (collected: ReadonlyArray<ToolEvent>): ReadonlyArray<ToolResult> =>
-  collected.filter(isOutput).map((e) => e.result)
-
-const byCallId = (results: ReadonlyArray<ToolResult>) => new Map(results.map((r) => [r.call_id, r]))
-
-const rejectedStream = (rejected: ReadonlyArray<ToolResult>) =>
-  Stream.fromIterable(rejected.map((result) => ToolEvent.Output({ result })))
-
-const eventsFromApprovalMap = (approvals: ReadonlyMap<string, ApprovalMapEntry>) => {
-  const plan = fromMap(isSensitive, approvals)(calls)
-  return Stream.merge(run(allTools, plan.approved), rejectedStream(plan.rejected))
-}
-
-const eventsFromDecision = (decision: ApprovalDecision): Stream.Stream<ToolEvent> =>
-  decision._tag === "Approved"
-    ? run(allTools, [decision.call])
-    : Stream.succeed(ToolEvent.Output({ result: decision.result }))
-
-// ---------------------------------------------------------------------------
-// fromMap: HTTP-style scenarios
-// ---------------------------------------------------------------------------
-
-describe("fromMap + run", () => {
-  it("approval: all gated approved → tools execute, structured Values", async () => {
-    const approvals = new Map<string, ApprovalMapEntry>([
-      ["c2", { decision: "approve" }],
-      ["c3", { decision: "approve" }],
-    ])
-    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
-    const by = byCallId(resultsFrom(collected))
-    expect(by.get("c1")).toMatchObject({ _tag: "Ok", value: { count: 3 } })
-    expect(by.get("c2")).toMatchObject({
-      _tag: "Ok",
-      value: { status: "sent", delivered: 2 },
-    })
-    expect(by.get("c3")).toMatchObject({
-      _tag: "Ok",
-      value: { status: "dropped", name: "prod" },
-    })
-
-    // No ApprovalRequested events from the pure HTTP flow.
-    expect(collected.filter(isApprovalRequested)).toHaveLength(0)
-  })
-
-  it("denial: gated denied → Failure(denied), no execution", async () => {
-    const approvals = new Map<string, ApprovalMapEntry>([
-      ["c2", { decision: "deny", reason: "spam concern" }],
-      ["c3", { decision: "deny", reason: "prod is sacred" }],
-    ])
-    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
-
-    // bulk_email never ran.
-    expect(collected.filter(isProgress).filter((e) => e.tool === "bulk_email")).toHaveLength(0)
-
-    const by = byCallId(resultsFrom(collected))
-    expect(by.get("c2")).toMatchObject({
-      _tag: "Failure",
-      kind: "denied",
-      reason: "spam concern",
-    })
-    expect(by.get("c3")).toMatchObject({
-      _tag: "Failure",
-      kind: "denied",
-      reason: "prod is sacred",
-    })
-  })
-
-  it("cancellation: missing verdicts → Failure(cancelled)", async () => {
-    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(new Map())))
-    const by = byCallId(resultsFrom(collected))
-    expect(by.get("c1")).toMatchObject({ _tag: "Ok", value: { count: 3 } })
-    expect(by.get("c2")).toMatchObject({ _tag: "Failure", kind: "cancelled" })
-    expect(by.get("c3")).toMatchObject({ _tag: "Failure", kind: "cancelled" })
-  })
-
-  it("mixed: approve + deny + omit → all three kinds", async () => {
-    const approvals = new Map<string, ApprovalMapEntry>([
-      ["c2", { decision: "approve" }],
-      // c3 omitted → cancelled
-    ])
-    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
-    const by = byCallId(resultsFrom(collected))
-    expect(by.get("c1")).toMatchObject({ _tag: "Ok", value: { count: 3 } })
-    expect(by.get("c2")).toMatchObject({ _tag: "Ok", value: { status: "sent" } })
-    expect(by.get("c3")).toMatchObject({ _tag: "Failure", kind: "cancelled" })
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Graceful degradation: hallucinated tool name doesn't kill the turn.
-// ---------------------------------------------------------------------------
-
-describe("run: graceful degradation", () => {
-  it("unknown tool name → Failure(unknown_tool); other calls still execute", async () => {
-    const callsWithBogus = [
-      fc("c1", "web_search", { query: "x" }),
-      fc("c2", "does_not_exist", {}),
-      fc("c3", "delete_database", { name: "prod" }),
-    ]
-    const collected = await Effect.runPromise(
-      Stream.runCollect(
-        (() => {
-          const plan = fromMap(
-            isSensitive,
-            new Map([["c3", { decision: "approve" }]]),
-          )(callsWithBogus)
-          return Stream.merge(run(allTools, plan.approved), rejectedStream(plan.rejected))
-        })(),
-      ),
-    )
-    const by = byCallId(resultsFrom(collected))
-    expect(by.get("c1")).toMatchObject({ _tag: "Ok" })
-    expect(by.get("c2")).toMatchObject({ _tag: "Failure", kind: "unknown_tool" })
-    expect(by.get("c3")).toMatchObject({ _tag: "Ok", value: { status: "dropped" } })
-  })
-})
-
-// ---------------------------------------------------------------------------
-// fromQueue: WebSocket-style scenarios
-// ---------------------------------------------------------------------------
-
-describe("fromQueue + run", () => {
-  it("queue-driven: approve + deny resolve correctly with ApprovalRequested events", async () => {
-    const collected = await Effect.runPromise(
-      Effect.gen(function* () {
-        const verdicts = yield* Queue.unbounded<{
-          readonly call_id: string
-          readonly decision: "approve" | "deny"
-          readonly reason?: string
-        }>()
-        yield* Queue.offer(verdicts, { call_id: "c2", decision: "approve" })
-        yield* Queue.offer(verdicts, {
-          call_id: "c3",
-          decision: "deny",
-          reason: "too risky",
-        })
-
-        // Stream.unwrap supplies the Scope for fromQueue's router.
-        const events = Stream.unwrap(
-          Effect.gen(function* () {
-            const { approved, decisions, approvalRequests } = yield* fromQueue(
-              isSensitive,
-              verdicts,
-            )(calls)
-            return Stream.merge(
-              approvalRequests,
-              Stream.merge(
-                run(allTools, approved),
-                decisions.pipe(Stream.flatMap(eventsFromDecision)),
-              ),
-            )
-          }),
-        )
-        return yield* Stream.runCollect(events)
-      }),
-    )
-
-    expect(collected.filter(isApprovalRequested)).toHaveLength(2)
-
-    const by = byCallId(resultsFrom(collected))
-    expect(by.get("c2")).toMatchObject({ _tag: "Ok", value: { status: "sent" } })
-    expect(by.get("c3")).toMatchObject({
-      _tag: "Failure",
-      kind: "denied",
-      reason: "too risky",
-    })
-  })
-
-  it("router retires per round, so sequential rounds over one queue both resolve", async () => {
-    // A verdict-per-round over one shared queue and scope. The old
-    // never-terminating router would still be alive for round 1 and steal
-    // round 2's verdict (not in its map), hanging round 2.
-    const decisions = await Effect.runPromise(
-      Effect.scoped(
-        Effect.gen(function* () {
-          const verdicts = yield* Queue.unbounded<Verdict>()
-          const round = (id: string) => [fc(id, "delete_database", { name: "prod" })]
-
-          const r1 = yield* fromQueue(isSensitive, verdicts)(round("c1"))
-          yield* Queue.offer(verdicts, { call_id: "c1", decision: "approve" })
-          const d1 = Array.from(yield* Stream.runCollect(r1.decisions))
-
-          const r2 = yield* fromQueue(isSensitive, verdicts)(round("c2"))
-          yield* Queue.offer(verdicts, { call_id: "c2", decision: "deny", reason: "no" })
-          const d2 = Array.from(yield* Stream.runCollect(r2.decisions))
-
-          return { d1, d2 }
-        }),
-      ),
-    )
-    expect(decisions.d1[0]).toMatchObject({ _tag: "Approved" })
-    expect(decisions.d2[0]).toMatchObject({ _tag: "Rejected", result: { kind: "denied" } })
-  })
-
-  it("timeout resolves an unanswered gated call as cancelled", async () => {
-    const decisions = await Effect.runPromise(
-      Effect.scoped(
-        Effect.gen(function* () {
-          const verdicts = yield* Queue.unbounded<Verdict>()
-          const { decisions } = yield* fromQueue(isSensitive, verdicts, { timeout: "10 millis" })([
-            fc("c1", "delete_database", { name: "prod" }),
-          ])
-          return Array.from(yield* Stream.runCollect(decisions))
-        }),
-      ),
-    )
-    expect(decisions[0]).toMatchObject({
-      _tag: "Rejected",
-      result: { _tag: "Failure", kind: "cancelled" },
-    })
-  })
-})
-
-// ---------------------------------------------------------------------------
-// History reconciliation
-// ---------------------------------------------------------------------------
-
-describe("findUnansweredCalls / cancelAllPending / isReconciled", () => {
-  const orphan = fc("c99", "delete_database", { name: "prod" })
-  const answered = fc("c98", "web_search", { query: "x" })
-  const answeredOutput = Items.toolCallOutput("c98", JSON.stringify({ count: 0 }))
-
-  it("findUnansweredCalls returns only orphans", () => {
-    const history = [Items.userText("hi"), answered, orphan, answeredOutput]
-    const unanswered = findUnansweredCalls(history)
-    expect(unanswered).toHaveLength(1)
-    expect(unanswered[0]!.call_id).toBe("c99")
-  })
-
-  it("isReconciled is false when orphans exist, true otherwise", () => {
-    const stale = [Items.userText("hi"), orphan]
-    expect(isReconciled(stale)).toBe(false)
-    const reconciled = [...stale, ...cancelAllPending(stale).map(toToolCallOutput)]
-    expect(isReconciled(reconciled)).toBe(true)
-  })
-
-  it("cancelAllPending synthesizes one Failure(cancelled) per orphan", () => {
-    const history = [Items.userText("hi"), answered, orphan, answeredOutput]
-    const closures = cancelAllPending(history, "user moved on")
-    expect(closures).toHaveLength(1)
-    const c = closures[0]!
-    expect(isFailure(c)).toBe(true)
-    expect(c).toMatchObject({
-      _tag: "Failure",
-      call_id: "c99",
-      kind: "cancelled",
-      reason: "user moved on",
-    })
-  })
-
-  it("follow-up: map closures to ToolCallOutput before appending new user message", () => {
-    const stale = [Items.userText("first request"), orphan]
-    const closures = cancelAllPending(stale, "user redirected")
-    const reconciled = [...stale, ...closures.map(toToolCallOutput), Items.userText("never mind")]
-    expect(findUnansweredCalls(reconciled)).toHaveLength(0)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Wire conversion
-// ---------------------------------------------------------------------------
-
-describe("toToolCallOutput", () => {
-  it("round-trips a Value result", () => {
-    const r: ToolResult = {
-      _tag: "Ok",
-      call_id: "c1",
-      tool: "web_search",
-      value: { count: 3 },
-    }
-    const out = toToolCallOutput(r)
-    expect(out.call_id).toBe("c1")
-    expect(JSON.parse(out.output)).toEqual({ count: 3 })
-  })
-
-  it("renders a Failure with reason as a nested error object", () => {
-    const r: ToolResult = {
-      _tag: "Failure",
-      call_id: "c2",
-      tool: "bulk_email",
-      kind: "denied",
-      reason: "spam concern",
-    }
-    const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ error: { kind: "denied", message: "spam concern" } })
-  })
-
-  it("renders a Failure without reason (omits message)", () => {
-    const r: ToolResult = {
-      _tag: "Failure",
-      call_id: "c3",
-      tool: "delete_database",
-      kind: "cancelled",
-    }
-    const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ error: { kind: "cancelled" } })
-  })
-})
-
-// ---------------------------------------------------------------------------
-// run
-// ---------------------------------------------------------------------------
-
-describe("run", () => {
-  it("runs all calls passed to it", async () => {
-    const collected = await Effect.runPromise(Stream.runCollect(run(allTools, calls)))
-    expect(collected.filter(isOutput)).toHaveLength(3)
-    expect(collected.filter(isOutput).every((e) => isOk(e.result))).toBe(true)
-  })
-})

package/src/tool/Approval.ts

@@ -1,181 +0,0 @@
-/**
- * Approval helpers for the two transport flavors.
- *
- * These helpers only decide which calls are approved and which synthetic
- * results must be returned to the model. Tool execution stays explicit at
- * the recipe boundary via `Toolkit.run`.
- */
-import { Data, Deferred, type Duration, Effect, Queue, Ref, Scope, Stream } from "effect"
-import type { ToolCall } from "../domain/Items.js"
-import { type ToolResult, cancelled, denied } from "./ToolResult.js"
-import { ToolEvent } from "./ToolEvent.js"
-
-export type ToolCallPlan = {
-  readonly approved: ReadonlyArray<ToolCall>
-  readonly rejected: ReadonlyArray<ToolResult>
-}
-
-export type ApprovalDecision = Data.TaggedEnum<{
-  Approved: { readonly call: ToolCall }
-  Rejected: { readonly result: ToolResult }
-}>
-
-export const ApprovalDecision = Data.taggedEnum<ApprovalDecision>()
-
-export const approve = (call: ToolCall): ApprovalDecision => ApprovalDecision.Approved({ call })
-
-export const reject = (result: ToolResult): ApprovalDecision =>
-  ApprovalDecision.Rejected({ result })
-
-export const splitApprovalDecisions = (decisions: ReadonlyArray<ApprovalDecision>): ToolCallPlan =>
-  decisions.reduce<ToolCallPlan>(
-    (acc, decision) =>
-      decision._tag === "Approved"
-        ? { ...acc, approved: [...acc.approved, decision.call] }
-        : { ...acc, rejected: [...acc.rejected, decision.result] },
-    { approved: [], rejected: [] },
-  )
-
-export const approvalRequested = (call: ToolCall): ToolEvent =>
-  ToolEvent.ApprovalRequested({
-    call_id: call.call_id,
-    tool: call.name,
-    arguments: call.arguments,
-  })
-
-// ---------------------------------------------------------------------------
-// Verdict queue (WebSocket-style transport).
-// ---------------------------------------------------------------------------
-
-export type Verdict = {
-  readonly call_id: string
-  readonly decision: "approve" | "deny"
-  readonly reason?: string
-}
-
-export type FromQueueOptions = {
-  /**
-   * Resolve any still-pending gated call as `cancelled` once this elapses,
-   * so a lost or never-sent verdict cannot hang the decisions stream
-   * forever. Omit to wait indefinitely.
-   */
-  readonly timeout?: Duration.Input
-}
-
-/**
- * Queue-backed approval planner. Safe calls are returned immediately in
- * `approved`; gated calls emit `ApprovalRequested` events and later produce
- * one `ApprovalDecision` when their matching verdict arrives.
- *
- * The verdict queue is a single-consumer transport: run one approval round
- * at a time (the router retires once every gated call of the round is
- * resolved). For overlapping rounds, use one queue per round.
- */
-export const fromQueue =
-  (
-    predicate: (call: ToolCall) => boolean,
-    verdicts: Queue.Dequeue<Verdict>,
-    options?: FromQueueOptions,
-  ) =>
-  (
-    calls: ReadonlyArray<ToolCall>,
-  ): Effect.Effect<
-    {
-      readonly approved: ReadonlyArray<ToolCall>
-      readonly decisions: Stream.Stream<ApprovalDecision>
-      readonly approvalRequests: Stream.Stream<ToolEvent>
-    },
-    never,
-    Scope.Scope
-  > =>
-    Effect.gen(function* () {
-      const gated = calls.filter(predicate)
-      const approved = calls.filter((call) => !predicate(call))
-
-      const entries = yield* Effect.forEach(gated, (call) =>
-        Deferred.make<ApprovalDecision>().pipe(Effect.map((d) => [call.call_id, d] as const)),
-      )
-      const deferreds: ReadonlyMap<string, Deferred.Deferred<ApprovalDecision>> = new Map(entries)
-      const callById: ReadonlyMap<string, ToolCall> = new Map(gated.map((c) => [c.call_id, c]))
-      const outstanding = yield* Ref.make(gated.length)
-
-      // Complete a deferred once; decrement only on the winning transition so
-      // a late verdict for an already-resolved call is a no-op.
-      const resolve = (call: ToolCall, decision: ApprovalDecision) =>
-        Deferred.succeed(deferreds.get(call.call_id)!, decision).pipe(
-          Effect.flatMap((won) => (won ? Ref.update(outstanding, (n) => n - 1) : Effect.void)),
-        )
-
-      // Router retires once every gated call is resolved (by verdict or
-      // timeout), so sequential rounds over one queue do not accumulate
-      // racing routers. Recursive + suspended: stack-safe, no imperative loop.
-      const route: Effect.Effect<void> = Effect.suspend(() =>
-        Ref.get(outstanding).pipe(
-          Effect.flatMap((n) =>
-            n <= 0
-              ? Effect.void
-              : Queue.take(verdicts).pipe(
-                  Effect.flatMap((v) => {
-                    const call = callById.get(v.call_id)
-                    return (
-                      call === undefined
-                        ? Effect.void
-                        : resolve(
-                            call,
-                            v.decision === "approve"
-                              ? approve(call)
-                              : reject(denied(call, v.reason)),
-                          )
-                    ).pipe(Effect.andThen(route))
-                  }),
-                ),
-          ),
-        ),
-      )
-
-      if (gated.length > 0) {
-        yield* Effect.forkScoped(route)
-        if (options?.timeout !== undefined) {
-          yield* Effect.forkScoped(
-            Effect.sleep(options.timeout).pipe(
-              Effect.andThen(
-                Effect.forEach(gated, (call) =>
-                  resolve(call, reject(cancelled(call, "approval timed out"))),
-                ),
-              ),
-            ),
-          )
-        }
-      }
-
-      const decisions = Stream.fromIterable(gated).pipe(
-        Stream.flatMap((call) => Stream.fromEffect(Deferred.await(deferreds.get(call.call_id)!)), {
-          concurrency: "unbounded",
-        }),
-      )
-
-      const approvalRequests = Stream.fromIterable<ToolEvent>(gated.map(approvalRequested))
-
-      return { approved, decisions, approvalRequests }
-    })
-
-// ---------------------------------------------------------------------------
-// Approval map (HTTP-style transport). Verdicts arrive synchronously
-// bundled in the request payload. Missing entries → cancelled.
-// ---------------------------------------------------------------------------
-
-export type ApprovalMapEntry =
-  | { readonly decision: "approve" }
-  | { readonly decision: "deny"; readonly reason?: string }
-
-export const fromMap =
-  (predicate: (call: ToolCall) => boolean, approvals: ReadonlyMap<string, ApprovalMapEntry>) =>
-  (calls: ReadonlyArray<ToolCall>): ToolCallPlan =>
-    splitApprovalDecisions(
-      calls.map((call) => {
-        if (!predicate(call)) return approve(call)
-        const v = approvals.get(call.call_id)
-        if (v === undefined) return reject(cancelled(call))
-        return v.decision === "approve" ? approve(call) : reject(denied(call, v.reason))
-      }),
-    )

package/src/tool/ToolResult.ts

@@ -1,114 +0,0 @@
-/**
- * Post-execution and synthetic tool results.
- *
- *   - Executed tools emit ToolResult.Ok.
- *   - Approval/cancellation policy emits synthetic ToolResult.Failure.
- *
- * Wire conversion stays at the recipe boundary via `toToolCallOutput`
- * so recipes can inspect, redact, or audit values before serialization.
- *
- * `output` and `reason` are `string`, not `unknown`: the wire wants strings,
- * and `unknown` would invite non-serializable values (Date, Map, BigInt,
- * fn). Recipes that want structured detail JSON.stringify themselves.
- */
-import { Data } from "effect"
-import type { ToolCall, ToolCallOutput } from "../domain/Items.js"
-import { toolCallOutput } from "../domain/Items.js"
-
-// ---------------------------------------------------------------------------
-// ToolResult
-// ---------------------------------------------------------------------------
-
-export type ToolResult = Data.TaggedEnum<{
-  Ok: {
-    readonly call_id: string
-    readonly tool: string
-    readonly value: unknown
-  }
-  Failure: {
-    readonly call_id: string
-    readonly tool: string
-    readonly kind: string
-    readonly reason?: string
-  }
-}>
-
-/**
- * Namespace of constructors, type guards, and matchers for `ToolResult`,
- * provided by `Data.taggedEnum`. Use `ToolResult.$is("Ok")` for type
- * narrowing and `ToolResult.$match({ Ok, Failure })` for exhaustive
- * pattern matching. Synthetic-result helpers (`denied`, `cancelled`,
- * `executionError`, `failed`) below are kinder constructors than the
- * raw `ToolResult.Failure(...)`.
- */
-export const ToolResult = Data.taggedEnum<ToolResult>()
-
-export const isOk = ToolResult.$is("Ok")
-export const isFailure = ToolResult.$is("Failure")
-
-// Synthesizers. `denied` and `cancelled` are operationally distinct;
-// anything else is just a recipe-chosen `kind` via `failed`.
-// ---------------------------------------------------------------------------
-
-export const failed = (call: ToolCall, kind: string, reason?: string): ToolResult =>
-  ToolResult.Failure({
-    call_id: call.call_id,
-    tool: call.name,
-    kind,
-    ...(reason !== undefined ? { reason } : {}),
-  })
-
-/** Explicit user/policy rejection. */
-export const denied = (call: ToolCall, reason?: string): ToolResult =>
-  failed(call, "denied", reason)
-
-/** Implicit non-answer (follow-up, inactivity, abort). */
-export const cancelled = (call: ToolCall, reason?: string): ToolResult =>
-  failed(call, "cancelled", reason)
-
-/** 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, serializeValue(v.value)),
-    Failure: (f) => toolCallOutput(f.call_id, failureBody(f.kind, f.reason)),
-  })