@feniix/bridgekit 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# 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.7.0] - Unreleased
+
+### 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,42 @@ 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)) { /* result.structuredContent.validationErrors */ }
+  else if (isDomainFailure(result)) { /* handler-level error */ }
+}
+```
+
+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 +164,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/mcp-signal.d.ts

@@ -1 +1,9 @@
+/**
+ * Defensively pulls an `AbortSignal` out of MCP request `extra`. The MCP SDK
+ * does not formally type a `signal` on `extra`, so the shape is sniffed
+ * structurally.
+ *
+ * Validated against `@modelcontextprotocol/sdk` v1.x. Revalidate on any SDK
+ * major bump in case the cancellation channel moves or gains a typed surface.
+ */
 export declare function signalFromExtra(extra: unknown): AbortSignal | undefined;

package/dist/src/adapters/mcp-signal.js

@@ -1,3 +1,11 @@
+/**
+ * Defensively pulls an `AbortSignal` out of MCP request `extra`. The MCP SDK
+ * does not formally type a `signal` on `extra`, so the shape is sniffed
+ * structurally.
+ *
+ * Validated against `@modelcontextprotocol/sdk` v1.x. Revalidate on any SDK
+ * major bump in case the cancellation channel moves or gains a typed surface.
+ */
 export function signalFromExtra(extra) {
     if (!extra || typeof extra !== "object" || !("signal" in extra)) {
         return undefined;

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

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import type { PortableTool, PortableToolResult } from "../core/define-tool.js";
+import type { PortableTool, PortableToolErrorDetails, PortableToolResult } from "../core/define-tool.js";
 type PiContent = {
     type: "text";
     text: string;
@@ -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: Record<string, unknown>;
+    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,19 +1,54 @@
 import { executePortableTool } from "../core/execute-tool.js";
+import { isValidationFailure } from "../core/result-guards.js";
 function toPiDetails(result) {
     return result.structuredContent ?? result.details ?? {};
 }
+function toPortableToolErrorDetails(result) {
+    if (isValidationFailure(result)) {
+        return result.structuredContent;
+    }
+    const { kind: _ignored, ...rest } = toPiDetails(result);
+    return { kind: "domain", ...rest };
+}
 export class PortableToolExecutionError extends Error {
     details;
     constructor(result) {
         super(result.text);
         this.name = "PortableToolExecutionError";
-        this.details = toPiDetails(result);
+        this.details = toPortableToolErrorDetails(result);
     }
 }
 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,
@@ -21,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

@@ -1,14 +1,41 @@
 import type { Static, TSchema } from "typebox";
-export interface PortableToolResult {
+export interface PortableToolResult<TStructured extends Record<string, unknown> = Record<string, unknown>> {
     /** Plain text sent back to the model in every host. */
     text: string;
     /** Structured data for hosts that support it. Preferred by both pi and MCP adapters. */
-    structuredContent?: Record<string, unknown>;
-    /** Legacy/adapter debug details used only when structuredContent is absent. */
+    structuredContent?: TStructured;
+    /**
+     * Legacy/adapter debug details used only when `structuredContent` is absent.
+     *
+     * @deprecated Slated for removal in 1.0. Prefer `structuredContent` for
+     * machine-readable data. Both adapters still fall back to this field, but
+     * new tool code should not set it.
+     */
     details?: Record<string, unknown>;
     /** Tool-level error flag. Throw for unexpected adapter/runtime failures. */
     isError?: boolean;
 }
+/**
+ * Discriminated union describing the shape `executePortableTool` puts into a
+ * failure result's `structuredContent`, and that the pi adapter exposes as
+ * `PortableToolExecutionError.details`.
+ *
+ * - `kind: "validation"` — TypeBox rejected the args. Always carries the
+ *   offending tool name and the validation errors.
+ * - `kind: "domain"` — the tool's own handler returned `isError: true`. The
+ *   shape of the rest of the object is whatever the handler chose to expose.
+ */
+export type PortableToolErrorDetails = {
+    kind: "validation";
+    tool: string;
+    validationErrors: PortableValidationError[];
+} | ({
+    kind: "domain";
+} & Record<string, unknown>);
+export interface PortableValidationError {
+    path: string;
+    message: string;
+}
 export type PortableToolBuiltInHost = "pi" | "mcp" | "test";
 export type PortableToolHost<TExtension extends string = never> = PortableToolBuiltInHost | TExtension;
 export interface PortableToolContext<THost extends string = PortableToolBuiltInHost> {

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

@@ -1,15 +1,9 @@
 import type { TSchema } from "typebox";
-import type { PortableTool, PortableToolBuiltInHost, PortableToolContext, PortableToolResult } from "./define-tool.js";
-type NoInferPortable<T> = [T][T extends unknown ? 0 : never];
-export interface PortableValidationError {
-    path: string;
-    message: string;
-}
+import type { PortableTool, PortableToolBuiltInHost, PortableToolContext, PortableToolResult, PortableValidationError } from "./define-tool.js";
 export declare function validatePortableToolArgs<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown): {
     ok: true;
 } | {
     ok: false;
     errors: PortableValidationError[];
 };
-export declare function executePortableTool<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown, ctx: PortableToolContext<NoInferPortable<THost>>): Promise<PortableToolResult>;
-export {};
+export declare function executePortableTool<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown, ctx: PortableToolContext<NoInfer<THost>>): Promise<PortableToolResult>;

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

@@ -19,6 +19,7 @@ export async function executePortableTool(tool, args, ctx) {
                 .map((error) => `${error.path} ${error.message}`)
                 .join("; ")}`,
             structuredContent: {
+                kind: "validation",
                 tool: tool.name,
                 validationErrors: validation.errors,
             },

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 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,27 @@ 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.
+- 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)) {
+    // result.structuredContent.validationErrors is typed.
+    log.warn({ tool: result.structuredContent.tool }, "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.5.0",
+  "version": "0.7.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -48,10 +48,9 @@
     "build": "npm run clean && tsc -b tsconfig.json",
     "test": "npm run build && node scripts/run-built-tests.mjs",
     "test:coverage": "npm run build && node scripts/run-built-tests-coverage.mjs",
-    "verify:dist": "node scripts/verify-bridgekit-dist.mjs",
     "pack:dry-run": "npm pack --dry-run --json",
     "package-smoke": "node scripts/smoke-package.mjs",
-    "prepack": "npm run build && npm run verify:dist"
+    "prepack": "npm run build"
   },
   "files": [
     "dist/**/*.js",
@@ -61,6 +60,7 @@
     "!dist/**/*.map",
     "!dist/tsconfig.tsbuildinfo",
     "README.md",
+    "CHANGELOG.md",
     "llms.txt",
     "examples/README.md"
   ],