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

package/src/tool/ToolDecision.test.ts

@@ -0,0 +1,301 @@
+import { describe, expect, expectTypeOf, it } from "@effect/vitest"
+import { Effect, Match, Result, Schema } from "effect"
+import * as Items from "../domain/Items.js"
+import * as ToolDecision from "./ToolDecision.js"
+import * as HistoryCheck from "./HistoryCheck.js"
+import * as Tool from "./Tool.js"
+import * as Toolkit from "./Toolkit.js"
+import * as ToolOutput from "./ToolOutput.js"
+
+const call = (id: string): Items.ToolCall => ({
+  type: "function_call",
+  call_id: id,
+  name: "send_email",
+  arguments: "{}",
+})
+
+const Decisions = ToolDecision.make({
+  Approve: { always: Schema.optionalKey(Schema.Boolean) },
+  Deny: { reason: Schema.optionalKey(Schema.String) },
+  Respond: { output: Schema.Json },
+})
+
+describe("ToolDecision.make", () => {
+  it("groups waiting calls by answer, ignores answers to other calls, keeps the rest unanswered", () => {
+    const waiting = [call("a"), call("b"), call("c"), call("d"), call("e")]
+    const resolved = Decisions.resolve(waiting, [
+      { callId: "a", decision: Decisions.Approve({ always: true }) },
+      { callId: "b", decision: Decisions.Deny({ reason: "spam" }) },
+      { callId: "c", decision: Decisions.Respond({ output: { booked: true } }) },
+      { callId: "e", decision: { _tag: "Edit", subject: "hi" } },
+      { callId: "closed-long-ago", decision: Decisions.Approve() },
+    ])
+    const approve = {
+      _tag: "Approve",
+      call: call("a"),
+      decision: { _tag: "Approve", always: true },
+    }
+    const deny = { _tag: "Deny", call: call("b"), decision: { _tag: "Deny", reason: "spam" } }
+    const respond = {
+      _tag: "Respond",
+      call: call("c"),
+      decision: { _tag: "Respond", output: { booked: true } },
+    }
+    expect(resolved).toEqual({
+      Approve: [approve],
+      Deny: [deny],
+      Respond: [respond],
+      answered: [approve, deny, respond],
+      unanswered: [call("d")],
+      // An answer this definition doesn't accept is reported, not dropped.
+      invalid: [{ call: call("e"), decision: { _tag: "Edit", subject: "hi" } }],
+    })
+    expectTypeOf(resolved.Deny[0]!.decision).toEqualTypeOf<{
+      readonly _tag: "Deny"
+      readonly reason?: string
+    }>()
+  })
+
+  it.effect("decodes answers from the wire and rejects unknown tags", () =>
+    Effect.gen(function* () {
+      const decode = Schema.decodeUnknownEffect(Decisions.schema)
+      expect(yield* decode({ _tag: "Deny", reason: "no" })).toEqual(
+        Decisions.Deny({ reason: "no" }),
+      )
+      const error = yield* Effect.flip(decode({ _tag: "Maybe" }))
+      expect(error._tag).toBe("SchemaError")
+    }),
+  )
+
+  it("type: constructors need their required fields", () => {
+    Decisions.Approve()
+    // @ts-expect-error Respond requires `output`
+    Decisions.Respond()
+  })
+
+  it("a closing decision comes with the error it names, built from its fields", () => {
+    const { Deny } = ToolDecision.Default.resolve(
+      [call("a"), call("b")],
+      [
+        { callId: "a", decision: ToolDecision.Default.Deny({ reason: "not today" }) },
+        { callId: "b", decision: ToolDecision.Default.Deny() },
+      ],
+    )
+    expect(Deny.map((d) => d.error)).toEqual([
+      new ToolDecision.Denied({ message: "not today" }),
+      new ToolDecision.Denied({ message: "The user declined." }),
+    ])
+    expectTypeOf(Deny[0]!.error).toEqualTypeOf<ToolDecision.Denied>()
+  })
+
+  it("answered lists every answered call, tagged by its decision, for an exhaustive Match", () => {
+    const { answered } = ToolDecision.Default.resolve(
+      [call("a"), call("b")],
+      [
+        { callId: "a", decision: ToolDecision.Default.Approve() },
+        { callId: "b", decision: ToolDecision.Default.Deny({ reason: "no" }) },
+      ],
+    )
+    const handled = answered.map(
+      Match.type<(typeof answered)[number]>().pipe(
+        Match.tagsExhaustive({
+          Approve: ({ call }) => `run ${call.call_id}`,
+          Deny: ({ call, error }) => `close ${call.call_id}: ${error.message}`,
+        }),
+      ),
+    )
+    expect(handled).toEqual(["run a", "close b: no"])
+  })
+
+  it("type: Match over answered must handle every decision", () => {
+    const { answered } = ToolDecision.Default.resolve([], [])
+    answered.map(
+      Match.type<(typeof answered)[number]>().pipe(
+        // @ts-expect-error Deny is not handled
+        Match.tagsExhaustive({ Approve: () => "run" }),
+      ),
+    )
+  })
+
+  it("a call answered twice: the same answer counts once, two different ones are invalid", () => {
+    const resolved = ToolDecision.Default.resolve(
+      [call("a"), call("b")],
+      [
+        { callId: "a", decision: ToolDecision.Default.Approve() },
+        { callId: "a", decision: ToolDecision.Default.Approve() },
+        { callId: "b", decision: ToolDecision.Default.Approve() },
+        { callId: "b", decision: ToolDecision.Default.Deny() },
+      ],
+    )
+    expect(resolved.answered.map((e) => e.call.call_id)).toEqual(["a"])
+    expect(resolved.invalid).toEqual([
+      { call: call("b"), decision: [{ _tag: "Approve" }, { _tag: "Deny" }] },
+    ])
+  })
+})
+
+describe("ToolDecision.byTool", () => {
+  class Escalated extends Schema.TaggedError<Escalated>()("Escalated", {
+    team: Schema.Literals(["finance", "legal"]),
+  }) {}
+
+  const Refund = ToolDecision.make({
+    Approve: {},
+    Reduce: { amount: Schema.Number },
+    Escalate: ToolDecision.closesWith(
+      { team: Schema.Literals(["finance", "legal"]) },
+      ({ team }) => new Escalated({ team }),
+    ),
+  })
+  const Email = ToolDecision.make({
+    Approve: {},
+    Edit: { subject: Schema.String },
+    // A closing decision is reusable across sets.
+    Deny: ToolDecision.Default.variants.Deny,
+  })
+  const Decisions = ToolDecision.byTool(
+    { issue_refund: Refund, send_email: Email },
+    { fallback: ToolDecision.Default },
+  )
+
+  const named = (name: string, id: string): Items.ToolCall => ({
+    type: "function_call",
+    call_id: id,
+    name,
+    arguments: "{}",
+  })
+
+  it("resolves each call with its own tool's decisions, the rest with the fallback", () => {
+    const waiting = [
+      named("issue_refund", "r1"),
+      named("issue_refund", "r2"),
+      named("send_email", "e1"),
+      named("helpdesk__write_ticket", "h1"),
+      named("send_email", "e2"),
+    ]
+    const resolved = Decisions.resolve(waiting, [
+      { callId: "r1", decision: Refund.Reduce({ amount: 40 }) },
+      { callId: "r2", decision: Email.Edit({ subject: "a refund edited like an email" }) },
+      { callId: "e1", decision: Email.Edit({ subject: "Your refund" }) },
+      { callId: "h1", decision: ToolDecision.Default.Deny({ reason: "read only today" }) },
+    ])
+    expect(resolved.issue_refund.Reduce.map((r) => r.decision.amount)).toEqual([40])
+    expect(resolved.send_email.Edit.map((r) => r.call.call_id)).toEqual(["e1"])
+    expect(resolved.fallback.Deny.map((r) => r.error)).toEqual([
+      new ToolDecision.Denied({ message: "read only today" }),
+    ])
+    expect(resolved.invalid.map((i) => i.call.call_id)).toEqual(["r2"])
+    expect(resolved.unanswered.map((c) => c.call_id)).toEqual(["e2"])
+  })
+
+  it("without a fallback, a call nobody takes decisions for can't be answered", () => {
+    const only = ToolDecision.byTool({ issue_refund: Refund })
+    const resolved = only.resolve(
+      [named("delete_ticket", "d1"), named("delete_ticket", "d2")],
+      [{ callId: "d1", decision: ToolDecision.Default.Approve() }],
+    )
+    expect(resolved.invalid.map((i) => i.call.call_id)).toEqual(["d1"])
+    expect(resolved.unanswered.map((c) => c.call_id)).toEqual(["d2"])
+  })
+
+  it.effect("decodes any set's answer from the wire", () =>
+    Effect.gen(function* () {
+      const decode = Schema.decodeUnknownEffect(Decisions.schema)
+      expect(yield* decode({ _tag: "Reduce", amount: 5 })).toEqual(Refund.Reduce({ amount: 5 }))
+      expect(yield* decode({ _tag: "Edit", subject: "s" })).toEqual(Email.Edit({ subject: "s" }))
+    }),
+  )
+
+  it("type: two sets may share a tag only with the same fields", () => {
+    const Always = ToolDecision.make({ Approve: { always: Schema.Boolean } })
+    // @ts-expect-error "Approve" has different fields in issue_refund and send_email
+    ToolDecision.byTool({ issue_refund: Refund, send_email: Always })
+    // An optional extra field is a conflict too: the union would drop it.
+    const Maybe = ToolDecision.make({ Approve: { always: Schema.optionalKey(Schema.Boolean) } })
+    // @ts-expect-error "Approve" has different fields
+    ToolDecision.byTool({ issue_refund: Refund }, { fallback: Maybe })
+    // Same fields (or a reused variant) are fine.
+    ToolDecision.byTool(
+      { issue_refund: Refund, send_email: Email },
+      { fallback: ToolDecision.Default },
+    )
+  })
+
+  it("type: an answer takes its tool's decisions; groups and errors are typed per tool", () => {
+    const refund = { callId: "r1", name: "issue_refund" } as const
+    Decisions.answer(refund, Refund.Reduce({ amount: 1 }))
+    // @ts-expect-error an email decision for a refund call
+    Decisions.answer(refund, Email.Edit({ subject: "s" }))
+    Decisions.answer(
+      { callId: "h1", name: "helpdesk__write_ticket" },
+      ToolDecision.Default.Approve(),
+    )
+
+    type Resolved = ToolDecision.ResolvedByTool<typeof Decisions.tools, typeof ToolDecision.Default>
+    expectTypeOf<Resolved["issue_refund"]["Escalate"][number]["error"]>().toEqualTypeOf<Escalated>()
+    expectTypeOf<
+      Resolved["send_email"]["Edit"][number]["decision"]["subject"]
+    >().toEqualTypeOf<string>()
+    expectTypeOf<
+      Resolved["send_email"]["Deny"][number]["error"]
+    >().toEqualTypeOf<ToolDecision.Denied>()
+  })
+})
+
+describe("closing waiting calls", () => {
+  const Sent = Schema.Struct({ id: Schema.String })
+  const sendEmail = Tool.make({
+    name: "send_email",
+    description: "",
+    inputSchema: Tool.noInput,
+    outputSchema: Sent,
+    run: () => Effect.succeed({ id: "m1" }),
+  })
+  const kit = Toolkit.make(sendEmail)
+
+  it.effect("a user-supplied result reads back like the tool's own output", () =>
+    Effect.gen(function* () {
+      const answered = yield* ToolOutput.success(call("b"), Sent, { id: "u1" })
+      expect(yield* Toolkit.decode(kit, "send_email", answered)).toEqual(
+        Result.succeed({ id: "u1" }),
+      )
+    }),
+  )
+
+  it.effect("a denied call carries the tagged error the model sees", () =>
+    Effect.gen(function* () {
+      const denied = new ToolDecision.Denied({ message: "spam" })
+      expect(yield* ToolOutput.failure(call("a"), ToolDecision.Denied, denied)).toEqual({
+        type: "function_call_output",
+        call_id: "a",
+        output: [{ type: "input_json", value: { _tag: "Denied", message: "spam" } }],
+        isError: true,
+      })
+    }),
+  )
+})
+
+describe("HistoryCheck", () => {
+  it.effect("closes every unanswered call with Cancelled, so history is submittable", () =>
+    Effect.gen(function* () {
+      const history: ReadonlyArray<Items.HistoryItem> = [
+        Items.userText("send both"),
+        call("a"),
+        call("b"),
+        Items.toolCallOutput("a", "sent"),
+      ]
+      expect(HistoryCheck.findUnansweredCalls(history)).toEqual([call("b")])
+
+      const closing = yield* HistoryCheck.cancelAllPending(history, "user moved on")
+      expect(closing).toEqual([
+        {
+          type: "function_call_output",
+          call_id: "b",
+          output: [{ type: "input_json", value: { _tag: "Cancelled", message: "user moved on" } }],
+          isError: true,
+        },
+      ])
+      expect(HistoryCheck.isReconciled([...history, ...closing])).toBe(true)
+    }),
+  )
+})

package/src/tool/ToolDecision.ts

@@ -0,0 +1,360 @@
+/**
+ * ToolDecision: define what an answer to a waiting tool call can be (approve,
+ * deny, edit, escalate, anything), and get the wire schema, the constructors
+ * and a resolver that groups waiting calls by answer. Which calls wait and what each
+ * answer means is app code; tools and toolkits know nothing about decisions.
+ */
+import { Array as Arr, Equal, Function, HashMap, Option, Record, Result, Schema } from "effect"
+import type { ToolCall } from "../domain/Items.js"
+
+/** A decision's fields; context-free schemas so the wire codec needs no services. */
+type Fields = Record<string, Schema.Codec<unknown, unknown, never, never>>
+
+/** A decision that ends the call with an error, built from the decision's fields. */
+export type Closing<F extends Fields, E> = {
+  readonly _tag: "Closing"
+  readonly fields: F
+  readonly error: (decision: Schema.Struct.Type<F>) => E
+}
+
+/**
+ * A decision that ends the call with an error, e.g. `Deny` with `Denied`. The
+ * resolver builds the error, so a decision can only end in the error it names.
+ */
+export const closesWith = <const F extends Fields, E>(
+  fields: F,
+  error: (decision: Schema.Struct.Type<F>) => E,
+): Closing<F, E> => ({ _tag: "Closing", fields, error })
+
+type Variants = Record<string, Fields | Closing<any, any>>
+
+type FieldsOf<X> = X extends Closing<infer F, any> ? F : X extends Fields ? X : never
+
+/** A decision of a definition: `{ _tag: "Approve", ...fields } | ...`. */
+export type DecisionOf<V extends Variants> = {
+  [K in keyof V & string]: Schema.TaggedStruct<K, FieldsOf<V[K]>>["Type"]
+}[keyof V & string]
+
+type FieldsType<V extends Variants, K extends keyof V & string> = Omit<
+  Extract<DecisionOf<V>, { readonly _tag: K }>,
+  "_tag"
+>
+
+type Constructors<V extends Variants> = {
+  readonly [K in keyof V & string]: {} extends FieldsType<V, K>
+    ? (fields?: FieldsType<V, K>) => DecisionOf<V>
+    : (fields: FieldsType<V, K>) => DecisionOf<V>
+}
+
+/** One decision for one call, as a client sends it. */
+export type Answer<D> = { readonly callId: string; readonly decision: D }
+
+/** An answer the call's decisions don't accept (wrong tag or fields, or two different answers). */
+export type Invalid = { readonly call: ToolCall; readonly decision: unknown }
+
+/**
+ * One answered call, tagged like its decision so `Match.tagsExhaustive` covers
+ * every tag; a closing decision also carries its error.
+ */
+export type Entry<V extends Variants, K extends keyof V & string = keyof V & string> = {
+  [T in K]: {
+    readonly _tag: T
+    readonly call: ToolCall
+    readonly decision: Extract<DecisionOf<V>, { readonly _tag: T }>
+  } & (V[T] extends Closing<any, infer E> ? { readonly error: E } : {})
+}[K]
+
+type Groups<V extends Variants> = {
+  readonly [K in keyof V & string]: ReadonlyArray<Entry<V, K>>
+} & {
+  /** Every answered call, in order: match on `_tag` to handle each decision. */
+  readonly answered: ReadonlyArray<Entry<V>>
+}
+
+/** Waiting calls grouped by the tag of their answer; `unanswered` got none, `invalid` a wrong one. */
+export type Resolved<V extends Variants> = Groups<V> & {
+  readonly unanswered: ReadonlyArray<ToolCall>
+  readonly invalid: ReadonlyArray<Invalid>
+}
+
+type ResolveFn<R> = {
+  (answers: ReadonlyArray<Answer<unknown>>): (calls: ReadonlyArray<ToolCall>) => R
+  (calls: ReadonlyArray<ToolCall>, answers: ReadonlyArray<Answer<unknown>>): R
+}
+
+export type Decisions<V extends Variants> = Constructors<V> & {
+  readonly variants: V
+  /** The wire form of a decision. */
+  readonly schema: Schema.Codec<DecisionOf<V>, unknown>
+  /**
+   * Group waiting calls by the answer each one got. Each answer is checked
+   * against this definition; answers for other calls are ignored.
+   */
+  readonly resolve: ResolveFn<Resolved<V>>
+}
+
+/** A call's answer: one decision, or `Conflict` when it got two different ones. */
+type Answered = Result.Result<unknown, { readonly conflict: ReadonlyArray<unknown> }>
+
+const answersById = (answers: ReadonlyArray<Answer<unknown>>): HashMap.HashMap<string, Answered> =>
+  HashMap.fromIterable(
+    Object.entries(Arr.groupBy(answers, (a) => a.callId)).map(([callId, group]) => {
+      const decisions = Arr.dedupeWith(
+        group.map((a) => a.decision),
+        Equal.equals,
+      )
+      const answered: Answered =
+        decisions.length === 1 ? Result.succeed(decisions[0]) : Result.fail({ conflict: decisions })
+      return [callId, answered] as const
+    }),
+  )
+
+/**
+ * Define the possible answers:
+ *
+ *   const RefundDecisions = ToolDecision.make({
+ *     Approve: {},
+ *     Reduce: { amount: Schema.Number },
+ *     Deny: ToolDecision.closesWith({ reason: Schema.String }, ({ reason }) => new Denied({ message: reason })),
+ *   })
+ *   const { Approve, Reduce, Deny, unanswered, invalid } = RefundDecisions.resolve(waiting, answers)
+ */
+export function make<const V extends Variants>(variants: V): Decisions<V>
+export function make(variants: Variants): object {
+  const fieldsOf = (variant: Fields | Closing<Fields, unknown>): Fields =>
+    isClosing(variant) ? variant.fields : variant
+  const tags = Object.keys(variants)
+  const schema: Schema.Codec<{ readonly _tag: string }, unknown> = Schema.Union(
+    Object.entries(variants).map(([tag, variant]) => Schema.TaggedStruct(tag, fieldsOf(variant))),
+  )
+  const accepts = Schema.is(schema)
+  const constructors = Object.fromEntries(
+    tags.map((tag) => [tag, (fields: object = {}) => ({ _tag: tag, ...fields })]),
+  )
+  // An entry is tagged like its decision; a closing one brings its error, built from the fields.
+  const entryOf = (call: ToolCall, decision: { readonly _tag: string }) =>
+    Option.match(Option.fromNullishOr(variants[decision._tag]).pipe(Option.filter(isClosing)), {
+      onNone: () => ({ _tag: decision._tag, call, decision }),
+      onSome: (closing) => ({
+        _tag: decision._tag,
+        call,
+        decision,
+        error: closing.error(decision),
+      }),
+    })
+  const resolve = Function.dual(
+    2,
+    (calls: ReadonlyArray<ToolCall>, answers: ReadonlyArray<Answer<unknown>>) => {
+      const byId = answersById(answers)
+      const [answeredCalls, unanswered] = Arr.partition(calls, (call) =>
+        Option.match(HashMap.get(byId, call.call_id), {
+          onNone: () => Result.fail(call),
+          onSome: (answer) => Result.succeed({ call, answer }),
+        }),
+      )
+      const [answered, invalid] = Arr.partition(answeredCalls, ({ call, answer }) =>
+        Result.match(answer, {
+          onSuccess: (decision) =>
+            accepts(decision)
+              ? Result.succeed(entryOf(call, decision))
+              : Result.fail({ call, decision }),
+          onFailure: ({ conflict }) => Result.fail({ call, decision: conflict }),
+        }),
+      )
+      const byTag = Arr.groupBy(answered, (entry) => entry._tag)
+      return {
+        ...Record.fromIterableWith(tags, (tag) => [tag, byTag[tag] ?? []]),
+        answered,
+        unanswered,
+        invalid,
+      }
+    },
+  )
+  return { ...constructors, variants, schema, resolve }
+}
+
+const isClosing = (
+  variant: Fields | Closing<Fields, unknown>,
+): variant is Closing<Fields, unknown> => variant["_tag"] === "Closing"
+
+/** What the model sees for a denied call. Define your own error for more fields. */
+export class Denied extends Schema.TaggedError<Denied>("@betalyra/effect-uai/Denied")("Denied", {
+  message: Schema.String,
+}) {}
+
+/** Approve, or deny with an optional reason; `Deny` ends the call with `Denied`. */
+export const Default = make({
+  Approve: {},
+  Deny: closesWith(
+    { reason: Schema.optionalKey(Schema.String) },
+    ({ reason }) => new Denied({ message: reason ?? "The user declined." }),
+  ),
+})
+
+// ---------------------------------------------------------------------------
+// Decisions per tool
+// ---------------------------------------------------------------------------
+
+// Any decision set, by structure: `Decisions<any>` is too narrow for a typed set's `resolve`.
+type AnyDecisions = {
+  readonly variants: Variants
+  readonly schema: Schema.Codec<any, unknown>
+  readonly resolve: ResolveFn<any>
+}
+type VariantsOf<D> = D extends { readonly variants: infer V extends Variants } ? V : never
+// Distributes over a union of sets, so each keeps its own tags.
+type DecisionsOf<D> = D extends { readonly variants: infer V extends Variants }
+  ? DecisionOf<V>
+  : never
+type Table = Record<string, AnyDecisions>
+
+/** The decision a call of tool `N` takes: its own set, else the fallback. */
+export type DecisionFor<M extends Table, F, N extends string> = N extends keyof M
+  ? DecisionsOf<M[N]>
+  : DecisionsOf<F>
+
+/** Each tool's groups, `fallback` for the rest, then what's left unanswered or invalid. */
+export type ResolvedByTool<M extends Table, F> = {
+  readonly [K in keyof M & string]: Groups<VariantsOf<M[K]>>
+} & (F extends AnyDecisions ? { readonly fallback: Groups<VariantsOf<F>> } : {}) & {
+    readonly unanswered: ReadonlyArray<ToolCall>
+    readonly invalid: ReadonlyArray<Invalid>
+  }
+
+export type ByTool<M extends Table, F> = {
+  readonly tools: M
+  /** The wire form of any answer: every set's decisions. */
+  readonly schema: Schema.Codec<DecisionsOf<M[keyof M]> | DecisionsOf<F>, unknown>
+  /** An answer to a waiting call, typed by its tool's decisions. */
+  readonly answer: <N extends string>(
+    interrupt: { readonly callId: string; readonly name: N },
+    decision: DecisionFor<M, F, N>,
+  ) => Answer<DecisionFor<M, F, N>>
+  /** Resolve every waiting call with its own tool's decisions. */
+  readonly resolve: ResolveFn<ResolvedByTool<M, F>>
+}
+
+// Exact type equality: `{}` and `{ always?: boolean }` differ (the union would drop `always`).
+type Equals<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false
+
+type TagDecision<V extends Variants, K extends string> = Extract<
+  DecisionOf<V>,
+  { readonly _tag: K }
+>
+
+// Tags two sets share with different fields.
+type SharedConflict<A, B> = A extends { readonly variants: infer VA extends Variants }
+  ? B extends { readonly variants: infer VB extends Variants }
+    ? {
+        [K in keyof VA & keyof VB & string]: Equals<
+          TagDecision<VA, K>,
+          TagDecision<VB, K>
+        > extends true
+          ? never
+          : K
+      }[keyof VA & keyof VB & string]
+    : never
+  : never
+
+type AllSets<M extends Table, F> = M & (F extends AnyDecisions ? { readonly fallback: F } : {})
+
+type Conflicts<S> = {
+  [A in keyof S]: { [B in keyof S]: SharedConflict<S[A], S[B]> }[keyof S]
+}[keyof S]
+
+/** A tag used by two sets with different fields: the wire can't tell them apart. */
+type NoConflicts<M extends Table, F> = [Conflicts<AllSets<M, F>>] extends [never]
+  ? unknown
+  : {
+      readonly __error: `Decision "${Conflicts<AllSets<M, F>> & string}" has different fields in two sets; rename one`
+    }
+
+/**
+ * The decisions each tool takes, in app code:
+ *
+ *   const Decisions = ToolDecision.byTool(
+ *     { issue_refund: RefundDecisions, send_email: EmailDecisions },
+ *     { fallback: ToolDecision.Default },
+ *   )
+ *
+ * Sets may share a tag only with the same fields (a compile error otherwise).
+ * A call whose tool has no set (and no fallback) can't be answered: it stays
+ * `unanswered`, or lands in `invalid` when an answer arrives for it.
+ */
+export function byTool<const M extends Table>(
+  tools: M & NoConflicts<M, undefined>,
+): ByTool<M, undefined>
+export function byTool<const M extends Table, F extends AnyDecisions>(
+  tools: M & NoConflicts<M, F>,
+  options: { readonly fallback: F },
+): ByTool<M, F>
+export function byTool(tools: Table, options?: { readonly fallback?: AnyDecisions }): object {
+  const fallback = options?.fallback
+  const sets = [...Object.values(tools), ...(fallback === undefined ? [] : [fallback])]
+  const schema = Schema.Union(sets.map((set) => set.schema))
+  const setOf = (call: ToolCall): Option.Option<AnyDecisions> =>
+    Option.orElse(
+      Option.fromNullishOr(Object.hasOwn(tools, call.name) ? tools[call.name] : undefined),
+      () => Option.fromNullishOr(fallback),
+    )
+  const groupsOf = (resolved: Record<string, unknown>) => {
+    const { unanswered: _u, invalid: _i, ...groups } = resolved
+    return groups
+  }
+  const resolve = Function.dual(
+    2,
+    (calls: ReadonlyArray<ToolCall>, answers: ReadonlyArray<Answer<unknown>>) => {
+      const [covered, uncovered] = Arr.partition(calls, (call) =>
+        Option.match(setOf(call), {
+          onNone: () => Result.fail(call),
+          onSome: () => Result.succeed(call),
+        }),
+      )
+      const named = Object.entries(tools).map(([name, set]) => {
+        const resolved = set.resolve(
+          covered.filter((call) => call.name === name),
+          answers,
+        )
+        return [name, resolved] as const
+      })
+      const rest = Option.map(Option.fromNullishOr(fallback), (set) =>
+        set.resolve(
+          covered.filter((call) => !Object.hasOwn(tools, call.name)),
+          answers,
+        ),
+      )
+      const all = [...named.map(([, r]) => r), ...Option.toArray(rest)]
+      // A call nobody takes decisions for: an answer to it is invalid.
+      const byId = answersById(answers)
+      const [orphaned, waiting] = Arr.partition(uncovered, (call) =>
+        Option.match(HashMap.get(byId, call.call_id), {
+          onNone: () => Result.fail(call),
+          onSome: (answer) =>
+            Result.succeed({
+              call,
+              decision: Result.match(answer, {
+                onSuccess: Function.identity,
+                onFailure: (c) => c.conflict,
+              }),
+            }),
+        }),
+      )
+      return {
+        ...Object.fromEntries(named.map(([name, r]) => [name, groupsOf(r)])),
+        ...Option.match(rest, { onNone: () => ({}), onSome: (r) => ({ fallback: groupsOf(r) }) }),
+        unanswered: [...all.flatMap((r) => r.unanswered), ...waiting],
+        invalid: [...all.flatMap((r) => r.invalid), ...orphaned],
+      }
+    },
+  )
+  return {
+    tools,
+    schema,
+    answer: (interrupt: { readonly callId: string }, decision: unknown) => ({
+      callId: interrupt.callId,
+      decision,
+    }),
+    resolve,
+  }
+}