@feniix/bridgekit 0.5.0 → 0.6.0

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;
@@ -23,7 +23,7 @@ export type PiToolRegistration = {
     registerTool(tool: PiToolDefinition): unknown;
 };
 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;

package/dist/src/adapters/pi.js

@@ -2,12 +2,23 @@ import { executePortableTool } from "../core/execute-tool.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;
+    }
+    const { kind: _ignored, ...rest } = source;
+    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) {

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,10 @@
 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 type { PortableValidationError };
 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/index.d.ts

@@ -1,2 +1,2 @@
-export { definePortableTool, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolHost, type PortableToolResult, } from "./core/define-tool.js";
+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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.5.0",
+  "version": "0.6.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",