@feniix/bridgekit 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -4,7 +4,67 @@ All notable changes to `@feniix/bridgekit` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.8.0] - Unreleased
+## [0.8.2] - Unreleased
+
+### Fixed
+
+- Discriminated unions now surface the active branch's
+  `required`/`additionalProperties` hints. When an `anyOf` fires at a path
+  and exactly one branch's discriminator (`Literal`/`const`/`enum`/`Union of
+  Literals`) is satisfied by the input, BridgeKit keeps that branch's
+  sibling errors and suppresses the others. For non-discriminated unions
+  and ambiguous cases, the conservative "suppress all" behavior from 0.8.1
+  is preserved. Resolves
+  [#38](https://github.com/feniix/bridgekit/issues/38).
+
+  Behavior notes for consumers upgrading from 0.8.1:
+
+  - `validationErrors.length` for a discriminated-union failure now reflects
+    the active branch's missing/extra props (typically 1 per missing field),
+    rather than the single `{ field: "(root)", message: ".*anyOf.*" }` entry
+    that 0.8.1 produced. Consumers asserting `validationErrors.length === 1`
+    or checking for `field === "(root)"` on these payloads will need to
+    update; assertions on `field` / `message` for the actual missing prop
+    are the new contract.
+  - The `anyOf`/`oneOf` summary at the union path is **suppressed** when an
+    active branch is resolved. Consumers using `field: "(root)"` as a
+    "union failed" sentinel will not see it for discriminated cases — read
+    the active-branch's specific entry instead. The summary is still
+    emitted in the fallback case (no active branch).
+  - Discriminators expressed as `Type.Union([Type.Literal("a"),
+    Type.Literal("b")])` (the anyOf-of-const idiom) are now recognized as
+    discriminators. 0.8.1 silently treated them as non-discriminators and
+    fell back to suppress-all.
+  - Discriminated unions inside `Type.Array(...)` are now resolved per
+    array element (the path walker descends into `items`). 0.8.1 bailed out
+    on array index segments.
+  - `const` / `enum` error messages now surface the allowed value(s)
+    (`must equal "create"` / `must equal one of "create", "update"`)
+    instead of the opaque `must be equal to constant`. Helps agents pick a
+    valid discriminator value on retry.
+  - Discriminator key lookup uses `Object.hasOwn`, so a schema discriminator
+    whose name happens to be `toString` / `constructor` / etc. won't be
+    matched via the prototype chain.
+
+  Note on nested unions: `field` is the leaf segment of the JSON pointer
+  (`"name"` for `/event/name`), not the full path. For schemas with the
+  same prop name at multiple depths this can be ambiguous; consumers
+  needing full path context should track which tool input branch was
+  active out-of-band.
+
+## [0.8.1] - 2026-05-26
+
+### Fixed
+
+- Union-of-objects validation no longer surfaces phantom missing-required-
+  property entries for every branch. When TypeBox emits an `anyOf`/`oneOf`
+  error at a path, sibling `required`/`additionalProperties` entries at the
+  same path are now suppressed so consumers see only the union summary.
+  `const`/`enum` discriminator errors at deeper paths are kept (they're
+  signal about which branch was intended).
+  Resolves [#35](https://github.com/feniix/bridgekit/issues/35).
+
+## [0.8.0] - 2026-05-26
 
 ### Breaking
 

package/README.md

@@ -127,6 +127,12 @@ if (result.isError) {
 
 For array-element validation, `field` is the leaf segment, which can be a numeric index (e.g. `field: "0"`) and loses path context. For root-level schema failures with empty `instancePath` (e.g. `null` passed to a `Type.Object` schema), `field` is the sentinel `"(root)"`.
 
+For **discriminated unions** (`Type.Union([Type.Object({tag: Literal("a"), …}), Type.Object({tag: Literal("b"), …})])`), when exactly one branch's discriminator matches the input, BridgeKit surfaces only that branch's missing-required hints (as of 0.8.2). Recognized discriminator shapes: `Literal` (`const`), `enum`, and `Union of Literals` (`anyOf` of consts). Resolution works inside `Type.Array(...)` per-element. When no branch matches (invalid discriminator), the `anyOf` summary and `const`/`enum` errors survive so consumers can identify the failed discriminator and pick a valid value.
+
+`const`/`enum` error messages carry the allowed value(s) directly (`must equal "create"` / `must equal one of "create", "update"`) so an agent can pick a valid discriminator on retry.
+
+For nested discriminated unions, `field` is the leaf segment of the JSON pointer (`"name"` for `/event/name`), not the full path. Consumers needing full path context for ambiguous prop names should track the active union branch out-of-band.
+
 The two modes expose the failure discriminator on different fields. In the
 new default `"return"` mode, prefer the result guards over inspecting a
 `kind` field directly — handler-emitted failures do not carry a synthesized

package/dist/src/core/execute-tool.js

@@ -1,5 +1,258 @@
-import { Check, Errors } from "typebox/value";
+import { Check, Errors, Pointer } from "typebox/value";
 const ROOT_FIELD = "(root)";
+function fieldFromPath(instancePath) {
+    return instancePath.split("/").filter(Boolean).at(-1) ?? ROOT_FIELD;
+}
+function readDiscriminatorValues(propSchema) {
+    // Extract the allowed values from a discriminator-eligible prop schema.
+    // Recognizes three shapes:
+    //   - `Type.Literal("x")` → `{ const: "x" }`
+    //   - `Type.String({ enum: ["x", "y"] })` → `{ enum: ["x", "y"] }`
+    //   - `Type.Union([Type.Literal("x"), Type.Literal("y")])` →
+    //     `{ anyOf: [{ const: "x" }, { const: "y" }] }`
+    // The anyOf-of-const case is idiomatic TypeBox and was missed before:
+    // without it, a branch declaring its tag as a Union-of-Literals was
+    // treated as having no discriminator, silently bailing out of branch
+    // matching.
+    if (!propSchema || typeof propSchema !== "object")
+        return [];
+    if ("const" in propSchema)
+        return [propSchema.const];
+    if (Array.isArray(propSchema.enum))
+        return propSchema.enum;
+    if (Array.isArray(propSchema.anyOf) && propSchema.anyOf.length > 0) {
+        const consts = [];
+        for (const entry of propSchema.anyOf) {
+            if (entry && typeof entry === "object" && "const" in entry) {
+                consts.push(entry.const);
+            }
+            else {
+                return [];
+            }
+        }
+        return consts;
+    }
+    return [];
+}
+function resolveSchemaAtPath(schema, instancePath) {
+    // Walk a JSON-pointer-style instancePath (e.g. "/event", "/events/0")
+    // down to the sub-schema at that data path. Follows both `properties`
+    // for object schemas and `items` for array schemas (numeric segments
+    // descend into the items schema). Other JSON Schema composites bail
+    // out; the caller then falls back to the conservative suppress-all rule.
+    if (instancePath === "")
+        return schema;
+    const segments = instancePath.split("/").filter(Boolean);
+    let current = schema;
+    for (const segment of segments) {
+        if (!current || typeof current !== "object")
+            return undefined;
+        const obj = current;
+        if (obj.properties && typeof obj.properties === "object" && segment in obj.properties) {
+            current = obj.properties[segment];
+            if (current === undefined)
+                return undefined;
+            continue;
+        }
+        if (obj.items !== undefined && /^\d+$/.test(segment)) {
+            if (Array.isArray(obj.items)) {
+                const idx = Number(segment);
+                if (idx >= obj.items.length)
+                    return undefined;
+                current = obj.items[idx];
+            }
+            else {
+                current = obj.items;
+            }
+            continue;
+        }
+        return undefined;
+    }
+    return current;
+}
+function readUnionBranches(node) {
+    // Accept both `anyOf` and `oneOf`. Each branch must be a plain object
+    // schema for this helper to apply — primitive unions (e.g. `Union([
+    // Literal("a"), Literal("b")])` rendered as anyOf-of-consts) have no
+    // discriminator-prop concept and the caller falls back.
+    if (!node || typeof node !== "object")
+        return undefined;
+    const shape = node;
+    const branches = shape.anyOf ?? shape.oneOf;
+    if (!Array.isArray(branches) || branches.length === 0)
+        return undefined;
+    if (!branches.every((b) => b && typeof b === "object" && b.type === "object" && b.properties)) {
+        return undefined;
+    }
+    return branches;
+}
+function branchDiscriminatorMatches(branch, value) {
+    // A branch matches its discriminator when every prop with a discriminator-
+    // eligible schema (Literal / enum / anyOf-of-Literal) is present on the
+    // input with a value the schema allows. `Object.hasOwn` avoids matching
+    // prototype-chain props like `toString`.
+    if (!value || typeof value !== "object")
+        return false;
+    const input = value;
+    let hasDiscriminator = false;
+    for (const [key, propSchema] of Object.entries(branch.properties ?? {})) {
+        const allowed = readDiscriminatorValues(propSchema);
+        if (allowed.length === 0)
+            continue;
+        hasDiscriminator = true;
+        if (!Object.hasOwn(input, key) || !allowed.includes(input[key]))
+            return false;
+    }
+    return hasDiscriminator;
+}
+function isSubsetOf(props, set) {
+    for (const p of props)
+        if (!set.has(p))
+            return false;
+    return true;
+}
+function suppressSiblingErrorsUnderUnion(schema, value, errors) {
+    // For unions of objects, TypeBox emits per-branch `required` /
+    // `additionalProperties` errors at the union's path. The user only needs
+    // to satisfy ONE branch, so those entries are phantoms; the `anyOf` /
+    // `oneOf` summary at the same path is the real signal.
+    //
+    // `const` / `enum` errors at the same path survive — they carry real
+    // discriminator info about which branch was intended.
+    //
+    // Discriminated-union refinement (#38): when an `anyOf`/`oneOf` fires at
+    // path P and exactly one branch's discriminator props (`const` / `enum`)
+    // are satisfied by the input, that branch is "active". Required and
+    // additionalProperties errors attributable to the active branch are
+    // preserved (so the user sees "you picked op=create, missing name");
+    // contributions from losing branches at P and its descendants are
+    // suppressed. Schema-walking on the public JSON-Schema shape avoids
+    // depending on TypeBox internals.
+    //
+    // Fallback: zero or multiple branches match — there is no actionable
+    // owner for the phantom errors, so the conservative 0.8.1 rule applies
+    // (drop all sibling `required` / `additionalProperties` at P, keep
+    // const / enum). This covers non-discriminated unions and ambiguous
+    // inputs.
+    const unionPaths = new Set();
+    for (const error of errors) {
+        if (error.keyword === "anyOf" || error.keyword === "oneOf") {
+            unionPaths.add(error.instancePath);
+        }
+    }
+    if (unionPaths.size === 0)
+        return errors;
+    const resolutions = new Map();
+    for (const path of unionPaths) {
+        const unionSchema = resolveSchemaAtPath(schema, path);
+        const branches = readUnionBranches(unionSchema);
+        if (!branches) {
+            resolutions.set(path, { kind: "no-active" });
+            continue;
+        }
+        const branchValue = Pointer.Get(value, path);
+        const matchedIndices = [];
+        for (let i = 0; i < branches.length; i++) {
+            if (branchDiscriminatorMatches(branches[i], branchValue))
+                matchedIndices.push(i);
+        }
+        if (matchedIndices.length !== 1) {
+            resolutions.set(path, { kind: "no-active" });
+            continue;
+        }
+        const activeIndex = matchedIndices[0];
+        const active = branches[activeIndex];
+        const branchRequired = new Set(active.required ?? []);
+        const branchProps = new Set(Object.keys(active.properties ?? {}));
+        // Map of property-name -> set of disallowed values held by losing
+        // branches' discriminators. Used to drop "must equal X" errors at the
+        // union's descendant paths when X belongs to a branch the user didn't
+        // pick. Covers `const`, `enum`, and `Union([Literal, Literal])` (the
+        // anyOf-of-const shape) via `readDiscriminatorValues`.
+        const losingDiscriminators = new Map();
+        for (let i = 0; i < branches.length; i++) {
+            if (i === activeIndex)
+                continue;
+            for (const [key, propSchema] of Object.entries(branches[i].properties ?? {})) {
+                const values = readDiscriminatorValues(propSchema);
+                if (values.length === 0)
+                    continue;
+                let existing = losingDiscriminators.get(key);
+                if (!existing) {
+                    existing = new Set();
+                    losingDiscriminators.set(key, existing);
+                }
+                for (const v of values)
+                    existing.add(v);
+            }
+        }
+        resolutions.set(path, { kind: "active", branchRequired, branchProps, losingDiscriminators });
+    }
+    return errors.filter((error) => {
+        // Errors at a union path: handle by keyword + active-branch attribution.
+        const resolution = resolutions.get(error.instancePath);
+        if (resolution) {
+            if (resolution.kind === "no-active") {
+                // 0.8.1 fallback: drop required/additionalProperties at P; keep
+                // const / enum / anyOf (they carry discriminator info the user
+                // needs to fix the input).
+                return error.keyword !== "required" && error.keyword !== "additionalProperties";
+            }
+            // Active branch resolved: suppress the anyOf/oneOf summary at P too.
+            // The active branch's specific errors (preserved below) are strictly
+            // more actionable than "must match a schema in anyOf".
+            if (error.keyword === "anyOf" || error.keyword === "oneOf")
+                return false;
+            if (error.keyword === "required") {
+                // Attribute by structured params: the active branch demanded a
+                // superset of these props iff the missing props are all in its
+                // `required` array. Other branches' `required` entries get dropped.
+                const props = error.params.requiredProperties ?? [];
+                return props.length > 0 && isSubsetOf(props, resolution.branchRequired);
+            }
+            if (error.keyword === "additionalProperties") {
+                // The active-branch's additionalProperties error lists ONLY keys
+                // genuinely missing from its `properties` map. A losing branch may
+                // include the active branch's legitimate props in its list (because
+                // it has its own, narrower property set), so we keep only errors
+                // where EVERY offending key is also additional for the active
+                // branch. Losing-branch entries that drag in active-branch props
+                // get dropped — they would expand into phantom "name is additional"
+                // entries otherwise.
+                const props = error.params.additionalProperties ?? [];
+                return props.length > 0 && props.every((p) => !resolution.branchProps.has(p));
+            }
+            return true;
+        }
+        // Errors at descendant paths of a union path: when an active branch is
+        // resolved at the parent, drop `const`/`enum` errors whose allowedValue
+        // belongs to a losing branch's discriminator at this prop. This keeps
+        // the active-branch error story coherent ("you picked create, forgot
+        // name") instead of mixing in "could also have been delete" noise.
+        if (error.keyword !== "const" && error.keyword !== "enum")
+            return true;
+        for (const [unionPath, resolution] of resolutions) {
+            if (resolution.kind !== "active")
+                continue;
+            const prefix = unionPath === "" ? "/" : `${unionPath}/`;
+            if (!error.instancePath.startsWith(prefix))
+                continue;
+            const remainder = error.instancePath.slice(prefix.length);
+            if (remainder.includes("/"))
+                continue; // only direct discriminator props
+            const losingValues = resolution.losingDiscriminators.get(remainder);
+            if (!losingValues)
+                continue;
+            if (error.keyword === "const" && losingValues.has(error.params.allowedValue))
+                return false;
+            if (error.keyword === "enum" && Array.isArray(error.params.allowedValues)) {
+                if (error.params.allowedValues.every((v) => losingValues.has(v)))
+                    return false;
+            }
+        }
+        return true;
+    });
+}
 function expandTypeBoxError(error) {
     // Read offending property names from TypeBox's structured `params` rather
     // than parsing the message string. Two payoffs: locale independence (the
@@ -24,19 +277,45 @@ function expandTypeBoxError(error) {
             }));
         }
     }
-    const segments = error.instancePath.split("/").filter(Boolean);
-    return [{ field: segments.at(-1) ?? ROOT_FIELD, message: error.message }];
+    // const / enum errors carry the allowed values in `params`. Surfacing them
+    // in the message lets an agent recovering from an invalid-discriminator
+    // failure see exactly what tag(s) are accepted, rather than the opaque
+    // `must be equal to constant`.
+    if (error.keyword === "const") {
+        return [
+            {
+                field: fieldFromPath(error.instancePath),
+                message: `must equal ${JSON.stringify(error.params.allowedValue)}`,
+            },
+        ];
+    }
+    if (error.keyword === "enum") {
+        const allowed = error.params.allowedValues ?? [];
+        return [
+            {
+                field: fieldFromPath(error.instancePath),
+                message: allowed.length > 0 ? `must equal one of ${allowed.map((v) => JSON.stringify(v)).join(", ")}` : error.message,
+            },
+        ];
+    }
+    return [{ field: fieldFromPath(error.instancePath), message: error.message }];
 }
 export function validatePortableToolArgs(tool, args) {
     if (Check(tool.parameters, args)) {
         return { ok: true };
     }
     // TypeBox can emit multiple errors per offending field (e.g. union/anyOf
-    // mismatches fire one error per failed branch). Dedupe by (field, message)
-    // using JSON.stringify so the key can't collide regardless of what
-    // characters field or message contain.
+    // mismatches fire one error per failed branch). First, when an anyOf/oneOf
+    // error fires at a path, drop sibling `required`/`additionalProperties`
+    // errors at the same path — they're phantoms (the consumer only needs to
+    // satisfy ONE branch, not all of them). Then dedupe the survivors by
+    // (field, message) using JSON.stringify so the key can't collide regardless
+    // of what characters field or message contain.
+    const rawErrors = suppressSiblingErrorsUnderUnion(tool.parameters, args, [
+        ...Errors(tool.parameters, args),
+    ]);
     const seen = new Set();
-    const errors = [...Errors(tool.parameters, args)]
+    const errors = rawErrors
         .flatMap((error) => expandTypeBoxError(error))
         .filter(({ field, message }) => {
         const key = JSON.stringify([field, message]);

package/llms.txt

@@ -73,7 +73,7 @@ export function createTools() {
 - pi invalid arguments and portable `isError: true` results return `{ content, details, isError: true }` by default (as of 0.7). Unexpected handler exceptions are also caught in return mode and surfaced as `{ content, details: {}, isError: true }`. Branch on `result.isError` and narrow with `isValidationFailure` / `isDomainFailure` from `@feniix/bridgekit`.
 - MCP invalid arguments and portable `isError: true` results return `CallToolResult` with `isError: true`. Same guards narrow the result.
 - MCP preserves `structuredContent`; pi maps `structuredContent` into the pi `details` field. Both adapters fall back to `details` for legacy/debug payloads when `structuredContent` is absent.
-- Validation errors and domain errors share the `{ field, message }` shape *inside* `validationErrors[]`. The array itself only appears on `kind: "validation"` — narrow with `isValidationFailure` (or check the discriminator) before iterating. `field` is derived from TypeBox's structured error data: required-property errors read `params.requiredProperties` (one entry per missing prop), additional-property errors read `params.additionalProperties` (one entry per offending key), other errors take the last meaningful segment of the offending JSON pointer (`text`, not `/text`). Locale-independent and prop-names-with-commas-safe. Duplicate `(field, message)` pairs from union mismatches are deduplicated. As of 0.8.0; `path` no longer exists. Caveats: array-element fields can be numeric indices (`field: "0"`, path context lost); root-level schema failures use the sentinel `field: "(root)"` rather than empty string.
+- Validation errors and domain errors share the `{ field, message }` shape *inside* `validationErrors[]`. The array itself only appears on `kind: "validation"` — narrow with `isValidationFailure` (or check the discriminator) before iterating. `field` is derived from TypeBox's structured error data: required-property errors read `params.requiredProperties` (one entry per missing prop), additional-property errors read `params.additionalProperties` (one entry per offending key), `const`/`enum` errors carry the allowed value(s) in the message (`must equal "create"` / `must equal one of "create", "update"`), other errors take the last meaningful segment of the offending JSON pointer (`text`, not `/text`). Locale-independent and prop-names-with-commas-safe. Duplicate `(field, message)` pairs from union mismatches are deduplicated. As of 0.8.0; `path` no longer exists. As of 0.8.2: **discriminated unions** (`Type.Union([Type.Object({tag:Literal("a"),…}),Type.Object({tag:Literal("b"),…})])`) surface the *active branch's* missing-required hints when exactly one branch's discriminator is satisfied — instead of the bare `anyOf` summary. Recognized discriminator shapes: `Literal` (`const`), `enum`, and `Union of Literals` (`anyOf` of consts). Works inside `Type.Array(...)` per-element. When no branch matches (invalid discriminator), falls back to the 0.8.1 behavior (drop sibling `required`, keep `const`/`enum`/`anyOf` summary). Caveats: array-element fields can be numeric indices (`field: "0"`, path context lost); root-level schema failures use the sentinel `field: "(root)"` rather than empty string; for nested discriminated unions `field` is the leaf segment, not the full path.
 - The result guards take a `PortableToolResult` — the value `executePortableTool` returns at the seam between BridgeKit and a host. They are not designed to be called on the pi adapter's wire object (`{ content, details, isError }`), which exposes `details` instead of `structuredContent`.
 - `registerPiTools(pi, tools, { errorHandling: "throw" })` opts into the pre-0.7 behavior where `isError` results throw `PortableToolExecutionError`. Selecting this value emits a `DeprecationWarning` (code `BRIDGEKIT_PI_THROW_DEPRECATED`) once per process; only the `"throw"` value is deprecated, not the option itself. Scheduled for removal in 1.0; do not adopt it for new code.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",