Feature/union response schemas

[flsh86]

Union-type response schemas: structured intent classification

Stacked PR: targets feature/derive-agent-tools (or rebase onto master once that PR merges).

Adds discriminated-union response schemas, so a classifier agent returns one of several typed intents and the caller dispatches with an exhaustive match (unhandled intents caught by the compiler):

val classifier = OpenAIAgent
  .synchronous(openai, "gpt-4o-mini")
  .responseSchema(UnionResponseSchema.derive[Refund | Complaint | GeneralQuery]("Classify the user's intent"))
  .build

classifier.run(msg)(backend).finalAnswer.map {
  case r: Refund       => refunds.run(...)
  case c: Complaint    => support.run(...)
  case _: GeneralQuery => faq.run(...)
}

Design

Two layers, one engine:
- ResponseSchema.oneOf[U](Variant[A], Variant[B], ...) (shared, Scala 2.13 + 3, macro-free) — explicit variants for sealed traits; Variant.named customizes the model-facing label.
- UnionResponseSchema.derive[A | B | C] (Scala 3 macro) — flattens the union (dealiasing, nested unions), summons per-member Schema/Encoder/Decoder/ClassTag givens, delegates to oneOf. Non-union types, duplicate members, and missing givens are compile errors.

Wire shape (uniform across providers — OpenAI strict mode forbids anyOf at the schema root): a root object with a single required result property holding an anyOf of the variants, each carrying a required kind: {"type": "string", "enum": ["<name>"]} discriminator as the first property. Model output: {"result": {"kind": "Refund", "orderId": "o-1"}}.

The discriminator-first ordering is load-bearing, discovered in live validation: structured-output grammars (OpenAI strict, Claude) constrain generation to schema property order, and with kind last, models leading with the discriminator were grammar-locked into the empty variant.

Details

- Construction-time validation: non-object variants, reserved kind property, duplicate names/classes, conflicting $defs — all fail at the oneOf/derive call site.
- Nested case classes hoist into a root $defs (no dangling refs); decode failures surface through the existing typed-run AgentFailure channel; unknown kind lists the valid kinds.
- Additive, non-breaking; no new dependencies. Scala 2.13 path is fully tested (shared spec runs on both rows).
- 24 shared + 7 macro unit tests; docs in docs/other/json-schemas.md and docs/agents/tools.md (mdoc-compiled).
- Live-validated on Claude (haiku-4-5), OpenAI strict (gpt-4o-mini), and Gemini (3.5 flash lite): 3-intent classifier with a nested case-class variant, an Option field variant, an empty variant, and a Variant.named custom label — all classified and decoded correctly on all three providers.
- No examples/ entry yet (examples must compile against released artifacts; post-release follow-up).

[adamw]

generated-docs should not be modified in PRs, only during releases

[adamw]

why can't the same .deriveResponseSchema[Refund | Complaint | GeneralQuery] be used here, as in the first example above? Why do we need a specialised UnionResponseSchema in the first place?

[flsh86]

deriveResponseSchema[T] requires given sttp.tapir.Schema[T] and io.circe.Codec[T]. Neither tapir nor circe can derive these for union types — unions have no Mirror - so that call simply doesn't compile for a union (with an unhelpful "no given instance" error).

[adamw]

Ok ... so then maybe we could have:

.responseSchema(ResponseSchema.derive[T]) // normal case
.responseSchema(ResponseSchema.deriveUnion[T | U]) // union case

this would be more regular. Plus we need clear docs on when to use .responseSchema vs .deriveResponseSchema and how these compare

[adamw]

is ResponseSchema introduced earlier? Doesn't seem so - it might need a section on its own

[adamw]

Automated review. Core logic verified correct (oneOf assembly, $defs merge, kind-stripping decoder, runtime dispatch, SchemaSupport $defs fix). Findings:

Coverage / docs

1. docs/other/json-schemas.md:113 — docs say the union schema works on Gemini, but GeminiAgent sends it unmodified and no test covers that path. Verify live on Gemini or soften the claim.
2. ResponseSchema.scala:46 — the description in the new oneOf(...) / derive[T](description) overloads is only sent by the OpenAI backend; Claude and Gemini drop it silently. The new docs don't mention this.

Hardening
3. SchemaSupport.scala:96 — the strict-mode folder now special-cases properties and $defs/definitions, but other name-to-schema containers (patternProperties, dependentSchemas, dependencies) still hit the generic branch — the same bug class this PR fixes for $defs. A shared helper over a key set would fix all of them.
4. UnionResponseSchema.scala:64 — the macro doesn't check that members are case classes, so derive[Refund | String] compiles and fails at runtime. A compile-time check would match the macro's other errors.
5. ResponseSchema.scala:110 — the kind-must-be-first invariant survives the Json → apispec Schema → Json round trip only because apispec happens to preserve property order. A dependency upgrade could silently demote kind. Assert kind-first where the schema is rendered, or keep the assembled Json end-to-end.

Cleanup
6. ResponseSchema.scala:108 — the encode → JsonObject surgery → decode round trip could stay in typed apispec.Schema (prepend kind to properties/required, clear $defs), removing ~25 lines and the "internal error" decode branch.
7. Variant.scala:32 — compile-time collision checks use typeSymbol.name, runtime labels parse Class.getName; these diverge for operator names, backticked digit names, and generics erasing to one class. The macro's advice to use Variant.named can't work for erasure-colliding generics (fails the duplicate-classes require).
8. ResponseSchema.scala:128 — variant decode failures lose the .result path prefix (the unknown-kind branch keeps it). Fix: df.history ::: result.history.
9. AgentTool.scala:39 — fromFunctionF still inlines TapirSchemaToJsonSchema(...) instead of calling the new renderTapirSchema helper.
10. ResponseSchema.scala:89 — the $defs merge fold hides its conflict require two closures deep, and JsonObject.fromMap makes $defs order nondeterministic. groupBy + ListMap is simpler and deterministic.