@feniix/bridgekit 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,182 @@
+# Changelog
+
+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
+
+### Breaking
+
+- **`PortableValidationError` renamed `path` → `field`.** No deprecation alias.
+  Update assertions accordingly. `field` is derived from TypeBox's structured
+  error data, not the localized message string. Resolves
+  [#33](https://github.com/feniix/bridgekit/issues/33).
+
+  ```ts
+  // Before (0.7 and earlier)
+  assert.equal(result.structuredContent.validationErrors[0].path, "/file_path");
+
+  // After (0.8+)
+  assert.equal(result.structuredContent.validationErrors[0].field, "file_path");
+  ```
+
+  Entries *inside* `validationErrors[]` share the `{ field, message }` shape
+  with handler-emitted domain-failure data so iteration code can read `.field`
+  uniformly. The `validationErrors[]` array itself only exists on the
+  `kind: "validation"` branch of `PortableToolErrorDetails` — always narrow
+  with `isValidationFailure` (or the discriminator) before iterating.
+
+- **`validationErrors[]` cardinality change.** Previously, a TypeBox error
+  with the message `must have required properties X, Y` produced a single
+  `PortableValidationError` whose message listed all missing props. Now,
+  `executePortableTool` emits **one `PortableValidationError` per missing
+  property**, with `field` set to the missing prop name and `message`
+  normalized to `must have required property <field>`. Consumers asserting
+  `validationErrors.length === 1` for a multi-prop missing case will break.
+
+  ```ts
+  // Schema: Type.Object({ file_path: Type.String(), count: Type.Number() })
+  // Args: {}
+
+  // Before (0.7)
+  // validationErrors.length === 1
+  // validationErrors[0] === { path: "/", message: "must have required properties file_path, count" }
+
+  // After (0.8+)
+  // validationErrors.length === 2
+  // validationErrors === [
+  //   { field: "file_path", message: "must have required property file_path" },
+  //   { field: "count",     message: "must have required property count"     },
+  // ]
+  ```
+
+- **Duplicate `(field, message)` pairs are deduplicated.** Union/discriminator
+  mismatches previously emitted multiple identical `(field, message)` entries
+  (one per failed union branch); they are now collapsed. Dedup only removes
+  entries — it never introduces new ones — so `validationErrors.length` can
+  only decrease relative to raw TypeBox output. Consumers locking in exact
+  counts on union failures may need to adjust.
+
+### Notes on field derivation
+
+- `field` is derived from TypeBox's structured error:
+  - `keyword === "required"` reads `params.requiredProperties` and emits one
+    entry per missing prop name.
+  - `keyword === "additionalProperties"` reads `params.additionalProperties`
+    and emits one entry per offending key name. (Previously fell back to the
+    `(root)` sentinel — the offending key is now surfaced as `field`.)
+  - Other errors take the last meaningful segment of `instancePath`
+    (e.g. `/text` → `"text"`, `/items/0/name` → `"name"`).
+- The structured-access path is locale- and message-format-independent.
+- For array-element validation, `field` is the leaf segment, which can be a
+  numeric index (e.g. `field: "0"`) and loses the path context. If positional
+  information matters, keep schemas permissive at the BridgeKit boundary and
+  validate positionally in your handler.
+- For root-level schema failures with empty `instancePath` (e.g. `null` passed
+  to a `Type.Object` schema), `field` is the sentinel `"(root)"` rather than
+  the empty string.
+
+## [0.7.0] - 2026-05-26
+
+### Changed
+
+- **`registerPiTools` now returns `isError` results by default instead of
+  throwing.** The third parameter is a new `RegisterPiToolsOptions` with
+  `errorHandling?: "throw" | "return"`; the default is `"return"`, mirroring
+  the MCP adapter. Portable validation failures and portable `isError: true`
+  results now surface as `{ content, details, isError: true }` on the pi side.
+  Unexpected exceptions thrown by tool handlers are also caught in return
+  mode and surfaced as `{ content: [{type:"text", text: message}], details: {}, isError: true }`,
+  matching MCP. This makes the documented "pi throws, MCP returns" asymmetry
+  symmetric. Resolves [#2](https://github.com/feniix/bridgekit/issues/2).
+- pi success-path results now include `isError: false` explicitly so consumers
+  can write `result.isError === false` symmetrically across pi and MCP.
+
+### Added
+
+- `isValidationFailure(result)` and `isDomainFailure(result)` type guards in
+  the root entrypoint. Use them after `result.isError` to narrow between
+  BridgeKit-emitted validation failures and tool-emitted domain failures.
+  Resolves [#30](https://github.com/feniix/bridgekit/issues/30).
+- `PortableValidationFailure` and `PortableDomainFailure` types alongside the
+  guards.
+- `RegisterPiToolsOptions` exported from `@feniix/bridgekit/pi`.
+- A `DeprecationWarning` (code `BRIDGEKIT_PI_THROW_DEPRECATED`) is emitted
+  once per process when `registerPiTools(..., { errorHandling: "throw" })`
+  is invoked, so consumers see the migration signal at runtime instead of
+  only in JSDoc.
+
+### Deprecated
+
+- `registerPiTools(..., { errorHandling: "throw" })` is retained for one
+  minor-version cycle so existing pi extensions can migrate without source
+  changes. It will be removed in 1.0. Only the `"throw"` *value* is
+  deprecated; the `errorHandling` option itself stays. Migrate by switching
+  to the default `"return"` mode and branching on `result.isError`.
+
+### Removed
+
+- The duplicate `PortableValidationError` re-export from `src/core/execute-tool.ts`.
+  The canonical export still lives in `src/core/define-tool.ts` and is surfaced
+  through `@feniix/bridgekit` unchanged.
+
+### Migration
+
+```ts
+// Before (0.6 and earlier)
+try {
+  const result = await piTool.execute(toolCallId, params, signal);
+} catch (err) {
+  if (isPortableToolExecutionError(err)) {
+    if (err.details.kind === "validation") { /* TypeBox errors */ }
+    else { /* domain failure */ }
+  }
+}
+
+// After (0.7+)
+const result = await piTool.execute(toolCallId, params, signal);
+if (result.isError) {
+  if (isValidationFailure(result)) { /* result.structuredContent.validationErrors */ }
+  else if (isDomainFailure(result)) { /* handler-level error */ }
+}
+```
+
+### Notes on the guards
+
+`isValidationFailure` narrows `structuredContent` to
+`{ kind: "validation"; tool: string; validationErrors: PortableValidationError[] }`
+because `executePortableTool` produces that exact shape on TypeBox rejection.
+The guard matches on shape, not provenance: a handler that returns the same
+shape on its own will also satisfy it. Keep handler-emitted error shapes
+distinct from the validation discriminator if that ambiguity matters.
+
+`isDomainFailure` narrows only to `result & { isError: true }`. It does **not**
+synthesize a `kind: "domain"` discriminator on `structuredContent` because the
+tool's handler chose `structuredContent` freely and BridgeKit does not rewrite
+it on the wire.
+
+#### Caveat: `kind` is not the same between modes
+
+The two `errorHandling` modes expose the failure discriminator on different
+fields and with different semantics. Branch by mode, not by reading `.kind`
+across both shapes:
+
+| Mode | Where to read | Validation failure | Handler-emitted failure |
+|------|---------------|--------------------|-------------------------|
+| `"return"` (default, 0.7+) | `result.structuredContent` | `{ kind: "validation", tool, validationErrors }` (BridgeKit-emitted) | Whatever the handler returned — no synthesized `kind` |
+| `"throw"` (deprecated) | `(err as PortableToolExecutionError).details` | `{ kind: "validation", tool, validationErrors }` | `{ kind: "domain", ...rest }` (BridgeKit synthesizes) |
+
+In return mode, prefer the type guards (`isValidationFailure`,
+`isDomainFailure`) over reading `kind` directly. In throw mode, the
+`PortableToolExecutionError.details.kind` discriminator is stable but the
+whole mode is deprecated.
+
+### Scope: where to call the guards
+
+The guards take a `PortableToolResult` — the value `executePortableTool`
+returns, or what your portable tool's own `execute` returns at the seam
+between BridgeKit and a host. They are **not** designed to operate on the pi
+adapter's wire object (`{ content, details, isError }`), which exposes
+`details` instead of `structuredContent`. Calling the guards on a pi wire
+object will always return `false`.

package/README.md

@@ -21,6 +21,8 @@ Read these files in order:
 import {
   definePortableTool,
   executePortableTool,
+  isDomainFailure,
+  isValidationFailure,
   type PortableTool,
   type PortableToolBuiltInHost,
   type PortableToolContext,
@@ -88,7 +90,50 @@ export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
 }
 ```
 
-Portable validation failures and portable results with `isError: true` reject with `PortableToolExecutionError` in pi so the host sees a native tool failure. The error message is the portable `text`, and `.details` is populated from `structuredContent` or `details`. Progress updates from `ctx.progress?.(...)` map to pi tool updates.
+By default (`errorHandling: "return"`, as of 0.7) the pi adapter mirrors the MCP adapter: portable validation failures and portable `isError: true` results surface as `{ content, details, isError: true }` so consumers can branch on `result.isError` and narrow with `isValidationFailure` / `isDomainFailure`. Unexpected handler exceptions are caught and surfaced as `{ content: [{type:"text", text: message}], details: {}, isError: true }`, matching MCP. Success-path results include `isError: false` explicitly so consumers can use the same strict-equality checks across both adapters. `details` is populated from `structuredContent` first, then from `details`, then `{}`. Progress updates from `ctx.progress?.(...)` map to pi tool updates.
+
+The pre-0.7 behavior — throw `PortableToolExecutionError` on `isError` — is still available for one deprecation cycle:
+
+```ts
+registerPiTools(pi, createTools(), { errorHandling: "throw" });
+```
+
+Selecting `errorHandling: "throw"` emits a `DeprecationWarning` (code `BRIDGEKIT_PI_THROW_DEPRECATED`) once per process. Only the `"throw"` value is deprecated; the `errorHandling` option itself remains. Migrate by switching to the default and branching on the returned result:
+
+```ts
+// Before (0.6 and earlier)
+try {
+  const result = await piTool.execute(...);
+} catch (err) {
+  if (isPortableToolExecutionError(err)) {
+    if (err.details.kind === "validation") { /* TypeBox errors */ }
+    else { /* domain failure */ }
+  }
+}
+
+// After (0.7+)
+const result = await piTool.execute(...);
+if (result.isError) {
+  if (isValidationFailure(result)) {
+    // validationErrors is Array<{ field: string; message: string }>.
+    for (const { field, message } of result.structuredContent.validationErrors) {
+      // ...
+    }
+  } else if (isDomainFailure(result)) { /* handler-level error */ }
+}
+```
+
+`PortableValidationError` exposes `{ field, message }`. `field` is derived from TypeBox's structured error data — required-property errors read `params.requiredProperties` (so a prop named `"a,b"` survives intact and the value is locale-independent); other errors take the last meaningful segment of the offending JSON pointer (`text`, not `/text`). One error is emitted per missing required property, and duplicate `(field, message)` pairs (e.g. from union mismatches) are deduplicated. Validation and domain errors share this `{ field, message }` shape, so a consumer reading `.field` does not need to branch on which kind of failure produced the entry. (`path` was the pre-0.8.0 name; it has been removed.)
+
+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)"`.
+
+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
+`kind`. In the deprecated `"throw"` mode, the discriminator lives on
+`(err as PortableToolExecutionError).details.kind` (`"validation"` or
+`"domain"`). The guards operate on a `PortableToolResult`; they are not
+designed to be called on the pi adapter's wire object.
 
 ## MCP adapter
 
@@ -127,7 +172,9 @@ if (process.argv[1] && realpathIfPossible(resolve(process.argv[1])) === realpath
 
 The MCP adapter uses low-level `tools/list` and `tools/call` handlers so TypeBox schemas are exposed as JSON Schema directly. It intentionally does not expose a high-level `registerMcpTools` helper.
 
-MCP invalid input and portable `isError: true` results return `CallToolResult` with `isError: true`. Exporting a server-options factory keeps MCP entrypoints import-passive and easy to test without starting stdio.
+Portable validation failures and portable `isError: true` results return `CallToolResult` with `isError: true`. `structuredContent` is preserved; `details` is used only as a fallback when `structuredContent` is absent. Exporting a server-options factory keeps MCP entrypoints import-passive and easy to test without starting stdio.
+
+The two adapters now read in parallel: invalid args and portable `isError` results return `{ isError: true }` from both hosts by default, and the same result-guard helpers (`isValidationFailure`, `isDomainFailure`) narrow them on either side.
 
 ## Custom host typing
 

package/dist/src/adapters/pi.d.ts

@@ -11,6 +11,7 @@ type PiToolUpdate = {
 type PiToolResult = {
     content: PiContent[];
     details: Record<string, unknown>;
+    isError?: boolean;
 };
 type PiToolDefinition = {
     name: string;
@@ -22,10 +23,51 @@ type PiToolDefinition = {
 export type PiToolRegistration = {
     registerTool(tool: PiToolDefinition): unknown;
 };
+/**
+ * How the pi adapter surfaces portable `isError: true` results (both
+ * BridgeKit-emitted validation failures and tool-emitted domain failures).
+ *
+ * - `"return"` (default as of 0.7) — return `{ content, details, isError: true }`
+ *   so the result mirrors the MCP adapter's `CallToolResult`. Consumers branch
+ *   on `result.isError` and may narrow with `isValidationFailure` /
+ *   `isDomainFailure`.
+ * - `"throw"` (deprecated, scheduled for removal in 1.0) — throw
+ *   `PortableToolExecutionError`. Available for one minor-version cycle so
+ *   existing pi extensions can migrate without source changes. Selecting
+ *   this value emits a `DeprecationWarning` (code
+ *   `BRIDGEKIT_PI_THROW_DEPRECATED`) once per process.
+ */
+export interface RegisterPiToolsOptions {
+    /**
+     * Controls how `isError: true` portable results are surfaced. Defaults to
+     * `"return"`. Passing `"throw"` is deprecated and will be removed in 1.0;
+     * only the `"throw"` value is deprecated, not the option itself.
+     *
+     * @default "return"
+     */
+    errorHandling?: "throw" | "return";
+}
 export declare class PortableToolExecutionError extends Error {
     readonly details: PortableToolErrorDetails;
     constructor(result: PortableToolResult);
 }
 export declare function isPortableToolExecutionError(error: unknown): error is PortableToolExecutionError;
-export declare function registerPiTools(pi: PiToolRegistration, tools: readonly PortableTool<TSchema>[]): void;
+/**
+ * Register a set of portable tools with a pi tool registry.
+ *
+ * Defaults to `errorHandling: "return"` so pi behaves like the MCP adapter:
+ * portable `isError: true` results and TypeBox validation failures surface as
+ * `{ content, details, isError: true }` rather than thrown exceptions. Pass
+ * `{ errorHandling: "throw" }` to opt into the pre-0.7 throwing behavior for
+ * one deprecation cycle.
+ *
+ * @example
+ * // 0.7+ default: errors as data.
+ * registerPiTools(pi, tools);
+ *
+ * @example
+ * // Deprecated, but available through 0.x.
+ * registerPiTools(pi, tools, { errorHandling: "throw" });
+ */
+export declare function registerPiTools(pi: PiToolRegistration, tools: readonly PortableTool<TSchema>[], options?: RegisterPiToolsOptions): void;
 export {};

package/dist/src/adapters/pi.js

@@ -1,16 +1,13 @@
 import { executePortableTool } from "../core/execute-tool.js";
+import { isValidationFailure } from "../core/result-guards.js";
 function toPiDetails(result) {
     return result.structuredContent ?? result.details ?? {};
 }
-function isValidationDetails(source) {
-    return source.kind === "validation" && typeof source.tool === "string" && Array.isArray(source.validationErrors);
-}
 function toPortableToolErrorDetails(result) {
-    const source = toPiDetails(result);
-    if (isValidationDetails(source)) {
-        return source;
+    if (isValidationFailure(result)) {
+        return result.structuredContent;
     }
-    const { kind: _ignored, ...rest } = source;
+    const { kind: _ignored, ...rest } = toPiDetails(result);
     return { kind: "domain", ...rest };
 }
 export class PortableToolExecutionError extends Error {
@@ -24,7 +21,34 @@ export class PortableToolExecutionError extends Error {
 export function isPortableToolExecutionError(error) {
     return error instanceof PortableToolExecutionError;
 }
-export function registerPiTools(pi, tools) {
+let throwModeDeprecationWarned = false;
+/**
+ * Register a set of portable tools with a pi tool registry.
+ *
+ * Defaults to `errorHandling: "return"` so pi behaves like the MCP adapter:
+ * portable `isError: true` results and TypeBox validation failures surface as
+ * `{ content, details, isError: true }` rather than thrown exceptions. Pass
+ * `{ errorHandling: "throw" }` to opt into the pre-0.7 throwing behavior for
+ * one deprecation cycle.
+ *
+ * @example
+ * // 0.7+ default: errors as data.
+ * registerPiTools(pi, tools);
+ *
+ * @example
+ * // Deprecated, but available through 0.x.
+ * registerPiTools(pi, tools, { errorHandling: "throw" });
+ */
+export function registerPiTools(pi, tools, options = {}) {
+    const errorHandling = options.errorHandling ?? "return";
+    if (errorHandling === "throw" && !throwModeDeprecationWarned) {
+        throwModeDeprecationWarned = true;
+        process.emitWarning('`registerPiTools(..., { errorHandling: "throw" })` is deprecated and will be removed in 1.0. ' +
+            'Migrate to the default `"return"` mode and branch on `result.isError`.', {
+            type: "DeprecationWarning",
+            code: "BRIDGEKIT_PI_THROW_DEPRECATED",
+        });
+    }
     for (const tool of tools) {
         pi.registerTool({
             name: tool.name,
@@ -32,22 +56,37 @@ export function registerPiTools(pi, tools) {
             description: tool.description,
             parameters: tool.parameters,
             async execute(_toolCallId, params, signal, onUpdate, _ctx) {
-                const result = await executePortableTool(tool, params, {
-                    host: "pi",
-                    signal,
-                    progress(update) {
-                        onUpdate?.({
-                            content: [{ type: "text", text: update.text }],
-                            details: toPiDetails(update),
-                        });
-                    },
-                });
-                if (result.isError) {
+                let result;
+                try {
+                    result = await executePortableTool(tool, params, {
+                        host: "pi",
+                        signal,
+                        progress(update) {
+                            onUpdate?.({
+                                content: [{ type: "text", text: update.text }],
+                                details: toPiDetails(update),
+                            });
+                        },
+                    });
+                }
+                catch (error) {
+                    if (errorHandling === "throw") {
+                        throw error;
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: message }],
+                        details: {},
+                        isError: true,
+                    };
+                }
+                if (result.isError && errorHandling === "throw") {
                     throw new PortableToolExecutionError(result);
                 }
                 return {
                     content: [{ type: "text", text: result.text }],
                     details: toPiDetails(result),
+                    isError: result.isError === true,
                 };
             },
         });

package/dist/src/core/define-tool.d.ts

@@ -33,7 +33,7 @@ export type PortableToolErrorDetails = {
     kind: "domain";
 } & Record<string, unknown>);
 export interface PortableValidationError {
-    path: string;
+    field: string;
     message: string;
 }
 export type PortableToolBuiltInHost = "pi" | "mcp" | "test";

package/dist/src/core/execute-tool.d.ts

@@ -1,6 +1,5 @@
 import type { TSchema } from "typebox";
 import type { PortableTool, PortableToolBuiltInHost, PortableToolContext, PortableToolResult, PortableValidationError } from "./define-tool.js";
-export type { PortableValidationError };
 export declare function validatePortableToolArgs<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown): {
     ok: true;
 } | {

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

@@ -1,22 +1,58 @@
 import { Check, Errors } from "typebox/value";
+const ROOT_FIELD = "(root)";
+function expandTypeBoxError(error) {
+    // Read offending property names from TypeBox's structured `params` rather
+    // than parsing the message string. Two payoffs: locale independence (the
+    // helper works the same after `Locale.Set("de_DE")`), and faithful
+    // preservation of property names that contain delimiters TypeBox's prose
+    // would split on (commas, etc.).
+    if (error.keyword === "required") {
+        const props = error.params.requiredProperties.filter((p) => p.length > 0);
+        if (props.length > 0) {
+            return props.map((field) => ({
+                field,
+                message: `must have required property ${field}`,
+            }));
+        }
+    }
+    if (error.keyword === "additionalProperties") {
+        const props = error.params.additionalProperties.filter((p) => p.length > 0);
+        if (props.length > 0) {
+            return props.map((field) => ({
+                field,
+                message: `must not have additional property ${field}`,
+            }));
+        }
+    }
+    const segments = error.instancePath.split("/").filter(Boolean);
+    return [{ field: segments.at(-1) ?? ROOT_FIELD, message: error.message }];
+}
 export function validatePortableToolArgs(tool, args) {
     if (Check(tool.parameters, args)) {
         return { ok: true };
     }
-    return {
-        ok: false,
-        errors: [...Errors(tool.parameters, args)].map((error) => ({
-            path: error.instancePath || "/",
-            message: error.message,
-        })),
-    };
+    // 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.
+    const seen = new Set();
+    const errors = [...Errors(tool.parameters, args)]
+        .flatMap((error) => expandTypeBoxError(error))
+        .filter(({ field, message }) => {
+        const key = JSON.stringify([field, message]);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    return { ok: false, errors };
 }
 export async function executePortableTool(tool, args, ctx) {
     const validation = validatePortableToolArgs(tool, args);
     if (!validation.ok) {
         return {
             text: `Invalid arguments for ${tool.name}: ${validation.errors
-                .map((error) => `${error.path} ${error.message}`)
+                .map((error) => `${error.field}: ${error.message}`)
                 .join("; ")}`,
             structuredContent: {
                 kind: "validation",

package/dist/src/core/result-guards.d.ts

@@ -0,0 +1,63 @@
+import type { PortableToolResult, PortableValidationError } from "./define-tool.js";
+/**
+ * Validation-failure narrowing of `PortableToolResult`.
+ *
+ * `executePortableTool` produces this shape when TypeBox rejects the args:
+ * `structuredContent` carries `kind: "validation"`, the offending tool name,
+ * and the list of validation errors. The flag is also set to `isError: true`.
+ *
+ * This is the typed form a consumer can match against in both pi (default
+ * `errorHandling: "return"`) and MCP adapters.
+ */
+export type PortableValidationFailure = PortableToolResult & {
+    isError: true;
+    structuredContent: {
+        kind: "validation";
+        tool: string;
+        validationErrors: PortableValidationError[];
+    };
+};
+/**
+ * Domain-failure narrowing of `PortableToolResult`.
+ *
+ * Any `result.isError === true` that is not a validation failure is treated
+ * as a domain failure. `structuredContent` stays whatever the handler chose;
+ * the guard does not synthesize a `kind: "domain"` discriminator on the wire.
+ * (The pi adapter's `PortableToolExecutionError.details` does synthesize that
+ * discriminator for the deprecated `errorHandling: "throw"` path.)
+ */
+export type PortableDomainFailure = PortableToolResult & {
+    isError: true;
+};
+/**
+ * Type guard for results produced by `executePortableTool` when TypeBox
+ * validation rejected the args.
+ *
+ * The guard matches on shape, not provenance: a tool handler that manually
+ * returns `{ isError: true, structuredContent: { kind: "validation", tool, validationErrors } }`
+ * will also satisfy this predicate. BridgeKit cannot authenticate the source of
+ * a result on the wire, so handler-emitted validation-shaped failures are
+ * indistinguishable from BridgeKit-emitted ones. If that ambiguity matters,
+ * keep handler-emitted error shapes distinct from the validation discriminator.
+ *
+ * @example
+ * const result = await executePortableTool(tool, args, ctx);
+ * if (result.isError) {
+ *   if (isValidationFailure(result)) {
+ *     log.warn({ errors: result.structuredContent.validationErrors }, "bad args");
+ *   }
+ * }
+ */
+export declare function isValidationFailure(result: PortableToolResult): result is PortableValidationFailure;
+/**
+ * Type guard for handler-emitted `isError: true` results that are not
+ * validation failures. Use after `result.isError` to branch between
+ * BridgeKit-emitted validation failures and tool-emitted domain failures.
+ *
+ * @example
+ * const result = await executePortableTool(tool, args, ctx);
+ * if (isDomainFailure(result)) {
+ *   metrics.increment("tool.domain_error", { tool: tool.name });
+ * }
+ */
+export declare function isDomainFailure(result: PortableToolResult): result is PortableDomainFailure;

package/dist/src/core/result-guards.js

@@ -0,0 +1,43 @@
+/**
+ * Type guard for results produced by `executePortableTool` when TypeBox
+ * validation rejected the args.
+ *
+ * The guard matches on shape, not provenance: a tool handler that manually
+ * returns `{ isError: true, structuredContent: { kind: "validation", tool, validationErrors } }`
+ * will also satisfy this predicate. BridgeKit cannot authenticate the source of
+ * a result on the wire, so handler-emitted validation-shaped failures are
+ * indistinguishable from BridgeKit-emitted ones. If that ambiguity matters,
+ * keep handler-emitted error shapes distinct from the validation discriminator.
+ *
+ * @example
+ * const result = await executePortableTool(tool, args, ctx);
+ * if (result.isError) {
+ *   if (isValidationFailure(result)) {
+ *     log.warn({ errors: result.structuredContent.validationErrors }, "bad args");
+ *   }
+ * }
+ */
+export function isValidationFailure(result) {
+    if (result.isError !== true)
+        return false;
+    const structured = result.structuredContent;
+    if (!structured || typeof structured !== "object")
+        return false;
+    return (structured.kind === "validation" &&
+        typeof structured.tool === "string" &&
+        Array.isArray(structured.validationErrors));
+}
+/**
+ * Type guard for handler-emitted `isError: true` results that are not
+ * validation failures. Use after `result.isError` to branch between
+ * BridgeKit-emitted validation failures and tool-emitted domain failures.
+ *
+ * @example
+ * const result = await executePortableTool(tool, args, ctx);
+ * if (isDomainFailure(result)) {
+ *   metrics.increment("tool.domain_error", { tool: tool.name });
+ * }
+ */
+export function isDomainFailure(result) {
+    return result.isError === true && !isValidationFailure(result);
+}

package/dist/src/index.d.ts

@@ -1,2 +1,3 @@
-export { definePortableTool, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolErrorDetails, type PortableToolHost, type PortableToolResult, } from "./core/define-tool.js";
-export { executePortableTool, type PortableValidationError, validatePortableToolArgs, } from "./core/execute-tool.js";
+export { definePortableTool, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolErrorDetails, type PortableToolHost, type PortableToolResult, type PortableValidationError, } from "./core/define-tool.js";
+export { executePortableTool, validatePortableToolArgs } from "./core/execute-tool.js";
+export { isDomainFailure, isValidationFailure, type PortableDomainFailure, type PortableValidationFailure, } from "./core/result-guards.js";

package/dist/src/index.js

@@ -1,2 +1,3 @@
 export { definePortableTool, } from "./core/define-tool.js";
-export { executePortableTool, validatePortableToolArgs, } from "./core/execute-tool.js";
+export { executePortableTool, validatePortableToolArgs } from "./core/execute-tool.js";
+export { isDomainFailure, isValidationFailure, } from "./core/result-guards.js";

package/dist/src/pi.d.ts

@@ -1 +1 @@
-export { isPortableToolExecutionError, type PiToolRegistration, PortableToolExecutionError, registerPiTools, } from "./adapters/pi.js";
+export { isPortableToolExecutionError, type PiToolRegistration, PortableToolExecutionError, type RegisterPiToolsOptions, registerPiTools, } from "./adapters/pi.js";

package/llms.txt

@@ -12,7 +12,12 @@ Use this package when you need to define a tool once and expose it through both
 ## Import map
 
 ```ts
-import { definePortableTool, executePortableTool } from "@feniix/bridgekit";
+import {
+  definePortableTool,
+  executePortableTool,
+  isDomainFailure,
+  isValidationFailure,
+} from "@feniix/bridgekit";
 import { registerPiTools } from "@feniix/bridgekit/pi";
 import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
 ```
@@ -65,9 +70,30 @@ export function createTools() {
 
 ## Host behavior
 
-- pi invalid arguments and portable `isError: true` results throw `PortableToolExecutionError`, because pi expects native tool failures. Tests should assert rejected execution plus `.details`, not a returned `{ isError: true }` object.
-- MCP invalid arguments and portable `isError: true` results return `CallToolResult` with `isError: true`.
+- 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.
+- 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.
+
+### Result-guard usage
+
+```ts
+const result = await executePortableTool(tool, args, { host: "test" });
+if (result.isError) {
+  if (isValidationFailure(result)) {
+    // validationErrors is typed: Array<{ field: string; message: string }>.
+    for (const { field, message } of result.structuredContent.validationErrors) {
+      log.warn({ tool: result.structuredContent.tool, field, message }, "bad args");
+    }
+  } else if (isDomainFailure(result)) {
+    // Handler-emitted failure; result.structuredContent is whatever the
+    // handler chose. No synthesized `kind` discriminator.
+    metrics.increment("tool.domain_error", { tool: tool.name });
+  }
+}
+```
 
 ## Custom host typing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -60,6 +60,7 @@
     "!dist/**/*.map",
     "!dist/tsconfig.tsbuildinfo",
     "README.md",
+    "CHANGELOG.md",
     "llms.txt",
     "examples/README.md"
   ],