@effect-uai/core 0.1.0 → 0.3.0

package/src/tool/Resolvers.test.ts

@@ -1,7 +1,7 @@
 /**
- * Tests for the resolver-based executor + resolvers + history-reconciliation
- * primitives. Exercises the full HITL + streaming-tool stack end-to-end via
- * `executeAllWithResolver`, with the four wire-shaped scenarios:
+ * Tests for approval planners + history-reconciliation primitives. Exercises
+ * the full HITL + streaming-tool stack end-to-end by composing approval plans
+ * with `executeAll`, with the four wire-shaped scenarios:
  *
  *   1. Approval        : gated calls approved → tools execute, structured Values
  *   2. Denial          : gated calls denied   → Failure(denied) results
@@ -14,27 +14,16 @@ 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,
-  isValue,
-  toFunctionCallOutput,
-} from "./Outcome.js"
+import { type ToolResult, isFailure, isValue, toFunctionCallOutput } from "./Outcome.js"
 import {
   type ApprovalMapEntry,
+  type ToolCallDecision,
   fromApprovalMap,
   fromVerdictQueue,
-  withFallback,
-  withPermissions,
 } from "./Resolvers.js"
 import { fromEffectSchema, make as makeTool, streaming } from "./Tool.js"
-import { executeAll, executeAllWithResolver } from "./Toolkit.js"
-import {
-  type ToolEvent,
-  isApprovalRequested,
-  isIntermediate,
-  isOutput,
-} from "./ToolEvent.js"
+import { executeAll, outputEvent, outputEvents } from "./Toolkit.js"
+import { type ToolEvent, isApprovalRequested, isIntermediate, isOutput } from "./ToolEvent.js"
 
 // ---------------------------------------------------------------------------
 // Three demo tools covering the matrix:
@@ -97,28 +86,32 @@ const calls = [
   fc("c3", "delete_database", { name: "prod" }),
 ]
 
-const resultsFrom = (
-  collected: ReadonlyArray<ToolEvent>,
-): ReadonlyArray<ToolResult> => collected.filter(isOutput).map((e) => e.result)
+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 byCallId = (results: ReadonlyArray<ToolResult>) =>
-  new Map(results.map((r) => [r.call_id, r]))
+const eventsFromApprovalMap = (approvals: ReadonlyMap<string, ApprovalMapEntry>) => {
+  const plan = fromApprovalMap(isSensitive, approvals)(calls)
+  return Stream.merge(executeAll(allTools, plan.approved), outputEvents(plan.rejected))
+}
+
+const eventsFromDecision = (decision: ToolCallDecision): Stream.Stream<ToolEvent> =>
+  decision._tag === "Approved"
+    ? executeAll(allTools, [decision.call])
+    : Stream.succeed(outputEvent(decision.result))
 
 // ---------------------------------------------------------------------------
 // fromApprovalMap: HTTP-style scenarios
 // ---------------------------------------------------------------------------
 
-describe("executeAllWithResolver + fromApprovalMap", () => {
+describe("fromApprovalMap + executeAll", () => {
   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(
-        executeAllWithResolver(allTools, calls, fromApprovalMap(isSensitive, approvals)),
-      ),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c1")).toMatchObject({ _tag: "Value", value: { count: 3 } })
     expect(by.get("c2")).toMatchObject({
@@ -139,16 +132,10 @@ describe("executeAllWithResolver + fromApprovalMap", () => {
       ["c2", { decision: "deny", reason: "spam concern" }],
       ["c3", { decision: "deny", reason: "prod is sacred" }],
     ])
-    const collected = await Effect.runPromise(
-      Stream.runCollect(
-        executeAllWithResolver(allTools, calls, fromApprovalMap(isSensitive, approvals)),
-      ),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
 
     // bulk_email never ran.
-    expect(
-      collected.filter(isIntermediate).filter((e) => e.tool === "bulk_email"),
-    ).toHaveLength(0)
+    expect(collected.filter(isIntermediate).filter((e) => e.tool === "bulk_email")).toHaveLength(0)
 
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c2")).toMatchObject({
@@ -164,15 +151,7 @@ describe("executeAllWithResolver + fromApprovalMap", () => {
   })
 
   it("cancellation: missing verdicts → Failure(cancelled)", async () => {
-    const collected = await Effect.runPromise(
-      Stream.runCollect(
-        executeAllWithResolver(
-          allTools,
-          calls,
-          fromApprovalMap(isSensitive, new Map()),
-        ),
-      ),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(new Map())))
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c1")).toMatchObject({ _tag: "Value", value: { count: 3 } })
     expect(by.get("c2")).toMatchObject({ _tag: "Failure", kind: "cancelled" })
@@ -184,11 +163,7 @@ describe("executeAllWithResolver + fromApprovalMap", () => {
       ["c2", { decision: "approve" }],
       // c3 omitted → cancelled
     ])
-    const collected = await Effect.runPromise(
-      Stream.runCollect(
-        executeAllWithResolver(allTools, calls, fromApprovalMap(isSensitive, approvals)),
-      ),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c1")).toMatchObject({ _tag: "Value", value: { count: 3 } })
     expect(by.get("c2")).toMatchObject({ _tag: "Value", value: { status: "sent" } })
@@ -200,7 +175,7 @@ describe("executeAllWithResolver + fromApprovalMap", () => {
 // Graceful degradation: hallucinated tool name doesn't kill the turn.
 // ---------------------------------------------------------------------------
 
-describe("executeAllWithResolver: graceful degradation", () => {
+describe("executeAll: graceful degradation", () => {
   it("unknown tool name → Failure(unknown_tool); other calls still execute", async () => {
     const callsWithBogus = [
       fc("c1", "web_search", { query: "x" }),
@@ -209,11 +184,13 @@ describe("executeAllWithResolver: graceful degradation", () => {
     ]
     const collected = await Effect.runPromise(
       Stream.runCollect(
-        executeAllWithResolver(
-          allTools,
-          callsWithBogus,
-          fromApprovalMap(isSensitive, new Map([["c3", { decision: "approve" }]])),
-        ),
+        (() => {
+          const plan = fromApprovalMap(
+            isSensitive,
+            new Map([["c3", { decision: "approve" }]]),
+          )(callsWithBogus)
+          return Stream.merge(executeAll(allTools, plan.approved), outputEvents(plan.rejected))
+        })(),
       ),
     )
     const by = byCallId(resultsFrom(collected))
@@ -227,7 +204,7 @@ describe("executeAllWithResolver: graceful degradation", () => {
 // fromVerdictQueue: WebSocket-style scenarios
 // ---------------------------------------------------------------------------
 
-describe("executeAllWithResolver + fromVerdictQueue", () => {
+describe("fromVerdictQueue + executeAll", () => {
   it("queue-driven: approve + deny resolve correctly with ApprovalRequested events", async () => {
     const collected = await Effect.runPromise(
       Effect.gen(function* () {
@@ -246,11 +223,17 @@ describe("executeAllWithResolver + fromVerdictQueue", () => {
         // Stream.unwrap supplies the Scope for fromVerdictQueue's router.
         const events = Stream.unwrap(
           Effect.gen(function* () {
-            const { resolve, announce } = yield* fromVerdictQueue(
+            const { approved, decisions, announce } = yield* fromVerdictQueue(
               isSensitive,
               verdicts,
             )(calls)
-            return Stream.merge(announce, executeAllWithResolver(allTools, calls, resolve))
+            return Stream.merge(
+              announce,
+              Stream.merge(
+                executeAll(allTools, approved),
+                decisions.pipe(Stream.flatMap(eventsFromDecision)),
+              ),
+            )
           }),
         )
         return yield* Stream.runCollect(events)
@@ -269,58 +252,6 @@ describe("executeAllWithResolver + fromVerdictQueue", () => {
   })
 })
 
-// ---------------------------------------------------------------------------
-// Combinators
-// ---------------------------------------------------------------------------
-
-describe("withPermissions / withFallback", () => {
-  it("withPermissions short-circuits with permission_denied when canApprove returns false", async () => {
-    const canApprove = (call: Items.FunctionCall) =>
-      Effect.succeed(call.name !== "delete_database")
-    const inner = fromApprovalMap(
-      isSensitive,
-      new Map<string, ApprovalMapEntry>([
-        ["c2", { decision: "approve" }],
-        ["c3", { decision: "approve" }],
-      ]),
-    )
-    const collected = await Effect.runPromise(
-      Stream.runCollect(
-        executeAllWithResolver(allTools, calls, withPermissions(inner, canApprove)),
-      ),
-    )
-    const by = byCallId(resultsFrom(collected))
-    // c2 allowed → executed; c3 forbidden → permission_denied (no exec)
-    expect(by.get("c2")).toMatchObject({ _tag: "Value", value: { status: "sent" } })
-    expect(by.get("c3")).toMatchObject({
-      _tag: "Failure",
-      kind: "permission_denied",
-    })
-  })
-
-  it("withFallback recovers a Reject by running an alternate decision", async () => {
-    const inner = fromApprovalMap(
-      isSensitive,
-      new Map<string, ApprovalMapEntry>([
-        ["c2", { decision: "deny", reason: "no" }],
-        ["c3", { decision: "approve" }],
-      ]),
-    )
-    // Recover only `denied` rejections; turn them into Execute (re-run anyway).
-    const recoverable = (r: ToolResult) => isFailure(r) && r.kind === "denied"
-    const fallbackResolver = withFallback(inner, recoverable, () =>
-      Effect.succeed({ _tag: "Execute" } as const),
-    )
-    const collected = await Effect.runPromise(
-      Stream.runCollect(executeAllWithResolver(allTools, calls, fallbackResolver)),
-    )
-    const by = byCallId(resultsFrom(collected))
-    // c2 was denied but fallback re-ran the tool.
-    expect(by.get("c2")).toMatchObject({ _tag: "Value", value: { status: "sent" } })
-    expect(by.get("c3")).toMatchObject({ _tag: "Value", value: { status: "dropped" } })
-  })
-})
-
 // ---------------------------------------------------------------------------
 // History reconciliation
 // ---------------------------------------------------------------------------
@@ -412,14 +343,12 @@ describe("toFunctionCallOutput", () => {
 })
 
 // ---------------------------------------------------------------------------
-// executeAll (no-resolver shortcut)
+// executeAll
 // ---------------------------------------------------------------------------
 
 describe("executeAll", () => {
-  it("equivalent to executeAllWithResolver with allow-all resolver", async () => {
-    const collected = await Effect.runPromise(
-      Stream.runCollect(executeAll(allTools, calls)),
-    )
+  it("runs all calls passed to it", async () => {
+    const collected = await Effect.runPromise(Stream.runCollect(executeAll(allTools, calls)))
     expect(collected.filter(isOutput)).toHaveLength(3)
     expect(collected.filter(isOutput).every((e) => isValue(e.result))).toBe(true)
   })

package/src/tool/Resolvers.ts

@@ -1,55 +1,73 @@
 /**
- * Ready-made `Resolver`s for the two transport flavors plus combinators
- * for layering policy on top.
+ * Approval helpers for the two transport flavors.
  *
- *   - `fromVerdictQueue` : long-lived channel (WebSocket / SSE).
- *   - `fromApprovalMap`  : request-shaped (HTTP chat).
- *   - `withPermissions`  : authz wrapper.
- *   - `withFallback`     : recovery wrapper.
- *
- * None of these know about the executor's stream shape; they just produce
- * `Effect<ToolDecision>`s a `Resolver` can return.
+ * 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.executeAll`.
  */
 import { Deferred, Effect, Queue, Scope, Stream } from "effect"
 import type { FunctionCall } from "../domain/Items.js"
-import {
-  type ToolDecision,
-  type ToolResult,
-  cancelled,
-  denied,
-  execute,
-  reject,
-  rejected,
-} from "./Outcome.js"
-import type { Resolver } from "./Toolkit.js"
+import { type ToolResult, cancelled, denied } from "./Outcome.js"
 import type { ToolEvent } from "./ToolEvent.js"
 
+export type ToolCallPlan = {
+  readonly approved: ReadonlyArray<FunctionCall>
+  readonly rejected: ReadonlyArray<ToolResult>
+}
+
+export type ToolCallDecision =
+  | { readonly _tag: "Approved"; readonly call: FunctionCall }
+  | { readonly _tag: "Rejected"; readonly result: ToolResult }
+
+export const approve = (call: FunctionCall): ToolCallDecision => ({
+  _tag: "Approved",
+  call,
+})
+
+export const reject = (result: ToolResult): ToolCallDecision => ({
+  _tag: "Rejected",
+  result,
+})
+
+export const splitToolCallDecisions = (decisions: ReadonlyArray<ToolCallDecision>): 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: FunctionCall): ToolEvent => ({
+  _tag: "ApprovalRequested",
+  call_id: call.call_id,
+  tool: call.name,
+  arguments: call.arguments,
+})
+
 // ---------------------------------------------------------------------------
 // Verdict queue (WebSocket-style transport).
 // ---------------------------------------------------------------------------
 
-export interface Verdict {
+export type Verdict = {
   readonly call_id: string
   readonly decision: "approve" | "deny"
   readonly reason?: string
 }
 
 /**
- * Queue-backed resolver. The router fiber drains verdicts and resolves
- * pre-registered Deferreds keyed by `call_id`. Returns the resolver and
- * a stream of `ApprovalRequested` events for the gated calls; the recipe
- * merges the announce stream into its consumer view.
+ * Queue-backed approval planner. Safe calls are returned immediately in
+ * `approved`; gated calls emit `ApprovalRequested` events and later produce
+ * one `ToolCallDecision` when their matching verdict arrives.
  */
 export const fromVerdictQueue =
-  (
-    predicate: (call: FunctionCall) => boolean,
-    verdicts: Queue.Dequeue<Verdict>,
-  ) =>
+  (predicate: (call: FunctionCall) => boolean, verdicts: Queue.Dequeue<Verdict>) =>
   (
     calls: ReadonlyArray<FunctionCall>,
   ): Effect.Effect<
     {
-      readonly resolve: Resolver
+      readonly approved: ReadonlyArray<FunctionCall>
+      readonly decisions: Stream.Stream<ToolCallDecision>
       readonly announce: Stream.Stream<ToolEvent>
     },
     never,
@@ -57,6 +75,7 @@ export const fromVerdictQueue =
   > =>
     Effect.gen(function* () {
       const gated = calls.filter(predicate)
+      const approved = calls.filter((call) => !predicate(call))
 
       const entries = yield* Effect.forEach(gated, (call) =>
         Deferred.make<Verdict>().pipe(Effect.map((d) => [call.call_id, d] as const)),
@@ -76,26 +95,25 @@ export const fromVerdictQueue =
         ),
       )
 
-      const resolve: Resolver = (call) => {
-        if (!predicate(call)) return Effect.succeed(execute)
-        const d = deferreds.get(call.call_id)!
-        return Deferred.await(d).pipe(
-          Effect.map((v) =>
-            v.decision === "approve" ? execute : reject(denied(call, v.reason)),
-          ),
-        )
-      }
-
-      const announce = Stream.fromIterable<ToolEvent>(
-        gated.map((call) => ({
-          _tag: "ApprovalRequested",
-          call_id: call.call_id,
-          tool: call.name,
-          arguments: call.arguments,
-        })),
+      const decisions = Stream.fromIterable(gated).pipe(
+        Stream.flatMap(
+          (call) => {
+            const d = deferreds.get(call.call_id)!
+            return Stream.fromEffect(
+              Deferred.await(d).pipe(
+                Effect.map((v) =>
+                  v.decision === "approve" ? approve(call) : reject(denied(call, v.reason)),
+                ),
+              ),
+            )
+          },
+          { concurrency: "unbounded" },
+        ),
       )
 
-      return { resolve, announce }
+      const announce = Stream.fromIterable<ToolEvent>(gated.map(approvalRequested))
+
+      return { approved, decisions, announce }
     })
 
 // ---------------------------------------------------------------------------
@@ -108,59 +126,13 @@ export type ApprovalMapEntry =
   | { readonly decision: "deny"; readonly reason?: string }
 
 export const fromApprovalMap =
-  (
-    predicate: (call: FunctionCall) => boolean,
-    approvals: ReadonlyMap<string, ApprovalMapEntry>,
-  ): Resolver =>
-  (call) => {
-    if (!predicate(call)) return Effect.succeed(execute)
-    const v = approvals.get(call.call_id)
-    if (v === undefined) return Effect.succeed(reject(cancelled(call)))
-    return Effect.succeed(
-      v.decision === "approve" ? execute : reject(denied(call, v.reason)),
-    )
-  }
-
-// ---------------------------------------------------------------------------
-// Combinators - compose policy onto an inner resolver.
-// ---------------------------------------------------------------------------
-
-/**
- * Authz gate. `canApprove` runs BEFORE the inner resolver; failures
- * short-circuit to a `permission_denied` rejection. Override `onForbidden`
- * if your audit format wants a different kind or reason.
- */
-export const withPermissions =
-  (
-    inner: Resolver,
-    canApprove: (call: FunctionCall) => Effect.Effect<boolean>,
-    onForbidden: (call: FunctionCall) => ToolResult = (call) =>
-      rejected(call, "permission_denied", "missing permissions"),
-  ): Resolver =>
-  (call) =>
-    canApprove(call).pipe(
-      Effect.flatMap((allowed) =>
-        allowed ? inner(call) : Effect.succeed(reject(onForbidden(call))),
-      ),
+  (predicate: (call: FunctionCall) => boolean, approvals: ReadonlyMap<string, ApprovalMapEntry>) =>
+  (calls: ReadonlyArray<FunctionCall>): ToolCallPlan =>
+    splitToolCallDecisions(
+      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))
+      }),
     )
-
-/**
- * Fallback gate. If `inner` returns a Reject whose result matches the
- * `recoverable` predicate, run `fallback(call)` instead and use that
- * decision. Otherwise pass the original Reject through.
- */
-export const withFallback =
-  (
-    inner: Resolver,
-    recoverable: (result: ToolResult) => boolean,
-    fallback: (call: FunctionCall) => Effect.Effect<ToolDecision>,
-  ): Resolver =>
-  (call) =>
-    inner(call).pipe(
-      Effect.flatMap((decision) =>
-        decision._tag === "Reject" && recoverable(decision.result)
-          ? fallback(call)
-          : Effect.succeed(decision),
-      ),
-    )
-

package/src/tool/Tool.ts

@@ -36,7 +36,7 @@ export const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(
   Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema)) as unknown as S &
     ToolInputSchema<S["Type"]>
 
-export interface Tool<Name extends string, Input, Output, R = never> {
+export type Tool<Name extends string, Input, Output, R = never> = {
   readonly name: Name
   readonly description: string
   readonly inputSchema: ToolInputSchema<Input>
@@ -55,7 +55,7 @@ export interface Tool<Name extends string, Input, Output, R = never> {
  * to its own wire field (OpenAI → `parameters`, Anthropic →
  * `input_schema`). Built from a `Tool` by `Toolkit.toDescriptors`.
  */
-export interface ToolDescriptor {
+export type ToolDescriptor = {
   readonly name: string
   readonly description: string
   readonly inputSchema: Record<string, unknown>
@@ -75,7 +75,7 @@ export const make = <Name extends string, Input, Output, R = never>(
 // `Output`. Sub-agents, slow downloads with progress, recipe streamers.
 // ---------------------------------------------------------------------------
 
-export interface StreamingTool<Name extends string, Input, Event, Output, R = never> {
+export type StreamingTool<Name extends string, Input, Event, Output, R = never> = {
   readonly _kind: "streaming"
   readonly name: Name
   readonly description: string
@@ -89,11 +89,11 @@ 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 type AnyStreamingTool<R = any> = StreamingTool<string, any, any, any, R>
+export type AnyPlainTool<R = any> = Tool<string, any, any, R>
+export type AnyKindTool<R = any> = AnyStreamingTool<R> | AnyPlainTool<R>
 
-export const isStreamingTool = (t: AnyKindTool): t is AnyStreamingTool =>
+export const isStreamingTool = <R>(t: AnyKindTool<R>): t is AnyStreamingTool<R> =>
   "_kind" in t && t._kind === "streaming"
 
 /**
@@ -101,8 +101,8 @@ export const isStreamingTool = (t: AnyKindTool): t is AnyStreamingTool =>
  * descriptors. Mirrors `Toolkit.toDescriptors` but accepts the union type
  * so a single list can carry both kinds.
  */
-export const toDescriptors = (
-  tools: ReadonlyArray<AnyKindTool>,
+export const toDescriptors = <R>(
+  tools: ReadonlyArray<AnyKindTool<R>>,
 ): ReadonlyArray<ToolDescriptor> =>
   tools.map((tool) => {
     const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({

package/src/tool/ToolEvent.ts

@@ -1,37 +1,41 @@
 /**
- * The event type emitted by `Toolkit.executeAllWithResolver`.
+ * The event type emitted while handling tool calls.
  *
- *   - ApprovalRequested : gated calls before resolver returns
+ *   - ApprovalRequested : gated calls waiting for approval
  *   - 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
+ * Recipes thread `ToolEvent.Output.result` through `continueWith` and apply
  * `toFunctionCallOutput` when appending to history.
  */
+import { Data } from "effect"
 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 type ToolEvent = Data.TaggedEnum<{
+  ApprovalRequested: {
+    readonly call_id: string
+    readonly tool: string
+    readonly arguments: string
+  }
+  Intermediate: {
+    readonly call_id: string
+    readonly tool: string
+    readonly data: unknown
+  }
+  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"
+/**
+ * Namespace of constructors, type guards, and matchers for `ToolEvent`,
+ * provided by `Data.taggedEnum`. Use `ToolEvent.Output({ result })` to build
+ * an event, `ToolEvent.$is("Output")` for type narrowing,
+ * `ToolEvent.$match({ ApprovalRequested, Intermediate, Output })` for
+ * exhaustive pattern matching.
+ */
+export const ToolEvent = Data.taggedEnum<ToolEvent>()
 
-export const isOutput = (e: ToolEvent): e is Extract<ToolEvent, { _tag: "Output" }> =>
-  e._tag === "Output"
+export const isApprovalRequested = ToolEvent.$is("ApprovalRequested")
+export const isIntermediate = ToolEvent.$is("Intermediate")
+export const isOutput = ToolEvent.$is("Output")