@feniix/bridgekit 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.14.0] - 2026-05-28
+
+### Added
+
+- `PortableTool` now carries an inferred success-result generic in addition to
+  its TypeBox parameter generic. `definePortableTool` and `executePortableTool`
+  preserve handler `structuredContent` types for direct/programmatic callers,
+  while validation failures remain `isError: true` results that narrow with
+  `isValidationFailure`.
+- `runBinWrapper` now validates its string inputs before spawning or importing:
+  `mcpEntry` rejects absolute paths, `..` path segments, and NUL bytes;
+  `buildScript` rejects option-shaped or shell-shaped script names.
+- CI and release checks now run `npm audit --omit=dev --audit-level=high`, and
+  Dependabot is configured for npm and GitHub Actions updates.
+
+### Changed
+
+- TypeScript is now strict-plus: `noUncheckedIndexedAccess` and
+  `exactOptionalPropertyTypes` are enabled in addition to `strict`. The packed
+  consumer smoke test compiles installed declarations with the same flags.
+- The Release workflow is manual-only (`workflow_dispatch`) with a `main`
+  branch guard; publishing no longer happens automatically after CI on `main`.
+  Third-party GitHub Actions are pinned by full commit SHA.
+- Documentation now reflects the current pi default error-return behavior, the
+  install-time MCP SDK dependency footprint, pre-1.0 stability/support
+  expectations, and MCP stdio-safe `buildStdio` examples.
+
+### Fixed
+
+- `isValidationFailure` now verifies every `validationErrors[]` entry has a
+  string `field` and `message` before narrowing to `PortableValidationFailure`.
+- `package-lock.json` root metadata now matches `package.json#version`.
+
 ## [0.13.0] - 2026-05-27
 
 ### Added

package/README.md

@@ -61,12 +61,18 @@ npm install @feniix/bridgekit typebox
 
 This package is ESM-only and supports Node.js 22.19.0 or newer. Published modules are import-passive and marked as side-effect free; tools are registered or servers are started only when the exported adapter functions are called.
 
+## Stability and support
+
+BridgeKit is pre-1.0. Patch releases are intended to be compatible within the current minor, but `0.x.0` minor bumps may contain source-level breaking changes while the API is settling. Production consumers that need maximum stability should pin an exact version or a patch-only range and read `CHANGELOG.md` before bumping.
+
+Issue triage is best-effort, with priority on packaging regressions, install failures, and SDK-compatibility breaks.
+
 ## Why
 
 - Define a tool once; ship it to pi and MCP without per-host forks.
 - Host-neutral tool files: no pi or MCP SDK imports in the tool definition itself.
 - TypeBox schemas pass through to MCP `inputSchema` directly — no JSON Schema conversion step.
-- Import-passive, `sideEffects: false`, four-entrypoint split (`.`, `./pi`, `./mcp`, `./bin-wrapper`) so pi-only consumers do not pull the MCP SDK and vice versa.
+- Import-passive, `sideEffects: false`, four-entrypoint split (`.`, `./pi`, `./mcp`, `./bin-wrapper`) so ESM/bundler consumers that use only core or pi entrypoints do not import or bundle the MCP adapter code. The MCP SDK is still a normal package dependency today, so all npm installs include its transitive dependencies.
 - Conformance-tested public surface: a packed-install smoke test enforces the runtime export set, deep-import rejection, and type-level strictness against the installed declarations.
 
 ## API reference
@@ -77,6 +83,8 @@ import {
   executePortableTool,
   isDomainFailure,
   isValidationFailure,
+  type PiToolCallRenderer,
+  type PiToolResultRenderer,
   type PortableTool,
   type PortableToolBuiltInHost,
   type PortableToolContext,
@@ -95,6 +103,8 @@ import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
 
 Do not deep-import from `dist/` or `src/` in consuming packages.
 
+`definePortableTool` infers both the TypeBox-backed argument type and the handler's success result shape. `executePortableTool` preserves that inferred success result for direct/programmatic callers, while validation failures are returned as `isError: true` results that can be narrowed with `isValidationFailure`.
+
 ### pi adapter
 
 ```ts
@@ -106,7 +116,7 @@ export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
 }
 ```
 
-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.
+By default (`errorHandling: "return"`, as of 0.7) the pi adapter mirrors MCP's error-as-data posture: portable validation failures and portable `isError: true` results surface as `{ content, details, isError: true }` so consumers can branch on `result.isError`. The pi wire object exposes machine-readable data on `details` (sourced from `structuredContent` first, then `details`, then `{}`); use the result guards on `PortableToolResult` values at the portable seam, not directly on the pi wire object. 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. 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:
 
@@ -130,12 +140,12 @@ try {
 // After (0.7+)
 const result = await piTool.execute(...);
 if (result.isError) {
-  if (isValidationFailure(result)) {
+  if (result.details.kind === "validation" && Array.isArray(result.details.validationErrors)) {
     // validationErrors is Array<{ field: string; message: string }>.
-    for (const { field, message } of result.structuredContent.validationErrors) {
+    for (const { field, message } of result.details.validationErrors) {
       // ...
     }
-  } else if (isDomainFailure(result)) { /* handler-level error */ }
+  } else { /* handler-level error; details is whatever the handler returned */ }
 }
 ```
 
@@ -150,20 +160,28 @@ For **discriminated unions** (`Type.Union([Type.Object({tag: Literal("a"), …})
 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
-`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.
+new default `"return"` mode, validation failures surface on the pi wire
+object as `result.details.kind === "validation"`; 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.
 
 #### Per-host metadata via `hostExtras`
 
-`PortableTool.hostExtras` is an optional namespace for host-specific fields that should travel with the tool definition rather than a parallel sidecar map. The pi adapter reads `hostExtras.pi`; the MCP adapter reads `hostExtras.mcp`; each adapter ignores keys it does not recognise. Tools that omit `hostExtras` see no behavior change.
+`PortableTool.hostExtras` is an optional namespace for host-specific fields that should travel with the tool definition rather than a parallel sidecar map. The pi adapter reads `hostExtras.pi`; the MCP adapter reads `hostExtras.mcp`; each adapter ignores keys it does not recognise. Tools that omit `hostExtras` see no behavior change. Pi TUI renderers use the exported `PiToolCallRenderer` / `PiToolResultRenderer` aliases; they are opaque pass-through callbacks, so bridgekit does not import pi-tui types or validate their return values.
+
+Custom host adapters can reuse the core execution helpers, but the built-in `ctx.host` union is intentionally closed (`"pi" | "mcp" | "test"`). Custom adapters should cast at their boundary and carry custom dispatch state on adapter-owned fields; use module augmentation of `PortableToolHostExtras` for type-safe host-specific metadata.
 
 ```ts
 import { Type } from "typebox";
-import { definePortableTool } from "@feniix/bridgekit";
+import { definePortableTool, type PiToolCallRenderer, type PiToolResultRenderer } from "@feniix/bridgekit";
+
+const renderSummaryCall: PiToolCallRenderer = (args) => ({ type: "text", text: `summarise ${args.text}` });
+const renderSummaryResult: PiToolResultRenderer = (result, options) => ({
+  type: "text",
+  text: options.expanded ? result.content?.[0]?.text : "summary ready",
+});
 
 export const generateSummaryTool = definePortableTool({
   name: "generate_summary",
@@ -180,6 +198,9 @@ export const generateSummaryTool = definePortableTool({
       pendingMessage: "Summarising...",
       promptSnippet: "Use this tool when the user asks for a short summary.",
       promptGuidelines: ["Prefer < 80 chars.", "Strip markdown."],
+      // Optional pi TUI renderers, forwarded by identity to pi.registerTool.
+      renderCall: renderSummaryCall,
+      renderResult: renderSummaryResult,
     },
     mcp: {
       annotations: { readOnlyHint: true },
@@ -188,6 +209,8 @@ export const generateSummaryTool = definePortableTool({
 });
 ```
 
+`renderCall` is invoked by pi before execution to render the call line. `renderResult` is invoked by pi after execution to render the result; its `options.expanded` flag tracks the user's Ctrl+O collapsed/expanded toggle. BridgeKit forwards both functions by identity to `pi.registerTool`.
+
 See `docs/rfc-host-extras.md` for the design rationale (which fields are in scope, why a top-level field beats a sidecar map, the closure rule for future additions). `PortableToolHostExtras` is module-augmentable for custom host adapters; declare your namespace via `declare module "@feniix/bridgekit"`.
 
 ### MCP adapter
@@ -231,7 +254,7 @@ Tool `parameters` must resolve to a JSON-Schema object at the top level. `Type.O
 
 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.
+The two adapters now read in parallel: invalid args and portable `isError` results return `{ isError: true }` from both hosts by default. The result-guard helpers (`isValidationFailure`, `isDomainFailure`) narrow `PortableToolResult` values at the portable seam; adapter wire values expose the same data through host-specific fields (`structuredContent` for MCP, `details` for pi).
 
 ### bin-wrapper (since 0.11.0)
 
@@ -245,21 +268,23 @@ await runBinWrapper({
   metaUrl: import.meta.url,
   mcpEntry: "dist/extensions/mcp-server.js",
   buildScript: "build:mcp",
+  // MCP stdio bins: keep build stdout off the JSON-RPC channel.
+  buildStdio: ["ignore", "inherit", "inherit"],
 });
 ```
 
 Options:
 
 - `metaUrl` (required): `import.meta.url` of the bin script. Used to locate the package root (the bin's parent directory).
-- `mcpEntry` (required): path to the compiled MCP entry, relative to the package root (e.g. `"dist/extensions/mcp-server.js"`).
-- `buildScript` (required): npm script to invoke when the entry is missing (e.g. `"build:mcp"`).
+- `mcpEntry` (required): path to the compiled MCP entry, relative to the package root (e.g. `"dist/extensions/mcp-server.js"`). Absolute paths, `..` path segments, and NUL bytes are rejected.
+- `buildScript` (required): npm script to invoke when the entry is missing (e.g. `"build:mcp"`). Names must be literal script identifiers containing only letters, numbers, `:`, `_`, `@`, `.`, or `-`, and must not start with `-`.
 - `buildTimeoutMs` (optional, default `60_000`): timeout for the build subprocess. Distinct "Build timed out…" diagnostic fires when exceeded.
 - `logPrefix` (optional, default `"bridgekit-bin"`): prefix on the "Failed to build…" diagnostic.
 - `buildStdio` (optional, default `"inherit"`): `stdio` mode passed to `spawnSync` when the build script runs. **MCP stdio server bins should pass `["ignore", "inherit", "inherit"]`** so the build subprocess's stdout cannot contaminate the parent's JSON-RPC framing channel (`process.stdout`). stderr stays inherited so build diagnostics remain visible.
 
 The MCP entry module must export `async function runServer(): Promise<void>`. Consumers with a different export name can alias on export.
 
-**Security: `mcpEntry` and `buildScript` must be literal strings in the caller's source.** The helper joins `mcpEntry` onto the resolved package root and dynamically `import()`s it, and it passes `buildScript` to `spawnSync` (with `shell: true` on Windows where `&`, `|`, and `^` are shell metacharacters). Sourcing either from CLI args or environment variables exposes arbitrary-file import and Windows command injection.
+**Security: `mcpEntry` and `buildScript` must be literal strings in the caller's source.** The helper joins `mcpEntry` onto the resolved package root and dynamically `import()`s it, and it passes `buildScript` to `spawnSync` (with `shell: true` on Windows where `&`, `|`, and `^` are shell metacharacters). BridgeKit rejects absolute/traversing entry paths and shell-shaped script names, but sourcing either option from CLI args or environment variables is still outside the supported threat model.
 
 Behavior on missing entry:
 
@@ -297,8 +322,8 @@ Package and release checklist:
 - If an npm-launched bin depends on generated output, use `runBinWrapper` from `@feniix/bridgekit/bin-wrapper` (since 0.11.0) — it resolves the package-local generated entry, runs the package-local build when output is missing in workspace/local execution, preserves build failures, and distinguishes timeout from build error in its diagnostic. The bin script becomes a three-line invocation; no hand-rolled wrapper needed.
 - If a package keeps a source-loaded host entrypoint (for example a pi extension source file), use a package-local MCP build behind that wrapper and narrow the build to the MCP entrypoint plus shared host-neutral modules.
 - Declare a compatible Node engine (`>=22.19.0`) in downstream packages that expose BridgeKit-powered MCP bins.
-- Run `npm run check`, `npm run test`, `npm run pack:dry-run`, and `npm run package-smoke` before publishing.
-- Treat `docs/releasing.md` as the future release handoff; this repository is not configured for automated publish yet.
+- Run `npm run check`, `npm test`, `npm run pack:dry-run`, `npm run package-smoke`, and `npm audit --omit=dev --audit-level=high` before publishing.
+- Treat `docs/releasing.md` as the release handoff; publishing is manual via the Release workflow and npm trusted publishing.
 
 See `examples/README.md` for complete copyable examples.
 

package/dist/src/adapters/mcp.js

@@ -182,7 +182,7 @@ export function createMcpServer(options) {
     });
     const server = new Server({ name: options.name, version: options.version }, {
         capabilities: { tools: { listChanged: false } },
-        instructions: options.instructions,
+        ...(options.instructions !== undefined && { instructions: options.instructions }),
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: mcpTools }));
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {

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

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import type { PortableTool, PortableToolErrorDetails, PortableToolResult } from "../core/define-tool.js";
+import type { PiToolCallRenderer, PiToolResultRenderer, PortableTool, PortableToolErrorDetails, PortableToolResult } from "../core/define-tool.js";
 type PiContent = {
     type: "text";
     text: string;
@@ -21,6 +21,8 @@ type PiToolDefinition = {
     execute(toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: (update: PiToolUpdate) => void, ctx?: unknown): Promise<PiToolResult>;
     promptSnippet?: string;
     promptGuidelines?: string[];
+    renderCall?: PiToolCallRenderer;
+    renderResult?: PiToolResultRenderer;
 };
 export type PiToolRegistration = {
     registerTool(tool: PiToolDefinition): unknown;

package/dist/src/adapters/pi.js

@@ -65,6 +65,9 @@ export function registerPiTools(pi, tools, options = {}) {
             // pi-coding-agent's registerTool input is `string[]` (mutable). The boundary
             // copy satisfies both sides without weakening either declared type.
             ...(piExtras?.promptGuidelines !== undefined && { promptGuidelines: [...piExtras.promptGuidelines] }),
+            // TUI renderers forwarded verbatim from hostExtras.pi.
+            ...(piExtras?.renderCall !== undefined && { renderCall: piExtras.renderCall }),
+            ...(piExtras?.renderResult !== undefined && { renderResult: piExtras.renderResult }),
             async execute(_toolCallId, params, signal, onUpdate, _ctx) {
                 let result;
                 try {
@@ -87,7 +90,7 @@ export function registerPiTools(pi, tools, options = {}) {
                     }
                     result = await executePortableTool(tool, params, {
                         host: "pi",
-                        signal,
+                        ...(signal !== undefined && { signal }),
                         progress(update) {
                             onUpdate?.({
                                 content: [{ type: "text", text: update.text }],

package/dist/src/bin-wrapper-internal.js

@@ -5,15 +5,41 @@
 // under inv-deep-imports-fail).
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 const DEFAULT_BUILD_TIMEOUT_MS = 60_000;
 const DEFAULT_LOG_PREFIX = "bridgekit-bin";
+const SAFE_BUILD_SCRIPT_NAME = /^[A-Za-z0-9:_@.-]+$/;
+function validateMcpEntry(mcpEntry) {
+    if (mcpEntry.length === 0) {
+        throw new Error("[bridgekit/bin-wrapper] mcpEntry must be a non-empty package-relative path.");
+    }
+    if (mcpEntry.includes("\0")) {
+        throw new Error("[bridgekit/bin-wrapper] mcpEntry must not contain NUL bytes.");
+    }
+    if (isAbsolute(mcpEntry) || /^[A-Za-z]:[\\/]/.test(mcpEntry)) {
+        throw new Error("[bridgekit/bin-wrapper] mcpEntry must be relative to the package root, not absolute.");
+    }
+    if (mcpEntry.split(/[\\/]+/).some((segment) => segment === "..")) {
+        throw new Error("[bridgekit/bin-wrapper] mcpEntry must not contain '..' path segments.");
+    }
+}
+function validateBuildScript(buildScript) {
+    if (buildScript.length === 0) {
+        throw new Error("[bridgekit/bin-wrapper] buildScript must be a non-empty npm script name.");
+    }
+    if (buildScript.startsWith("-") || !SAFE_BUILD_SCRIPT_NAME.test(buildScript)) {
+        throw new Error("[bridgekit/bin-wrapper] buildScript must be a literal npm script name containing only letters, " +
+            "numbers, ':', '_', '@', '.', or '-' (and must not start with '-').");
+    }
+}
 export const defaultBinWrapperDeps = {
     spawnSync,
     exit: process.exit,
 };
 export async function runBinWrapperWithDeps(options, deps) {
+    validateMcpEntry(options.mcpEntry);
+    validateBuildScript(options.buildScript);
     const packageRoot = resolve(dirname(fileURLToPath(options.metaUrl)), "..");
     const entryPath = join(packageRoot, options.mcpEntry);
     if (!existsSync(entryPath)) {

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

@@ -42,6 +42,19 @@ export interface PortableToolContext {
     signal?: AbortSignal;
     progress?: (update: PortableToolResult) => void;
 }
+/**
+ * Optional TUI renderer for the tool call line (before execution).
+ * Receives `(args, theme, context)` and returns a pi-tui Component.
+ * BridgeKit passes this through verbatim — no validation or wrapping.
+ */
+export type PiToolCallRenderer = (args: any, theme: any, context: any) => any;
+/**
+ * Optional TUI renderer for the tool result (after execution).
+ * Receives `(result, options, theme, context)` and returns a pi-tui Component.
+ * `options.expanded` is toggled by the user via Ctrl+O in pi's TUI.
+ * BridgeKit passes this through verbatim — no validation or wrapping.
+ */
+export type PiToolResultRenderer = (result: any, options: any, theme: any, context: any) => any;
 /**
  * Pi-specific entries on `PortableTool.hostExtras`. Read only by the pi
  * adapter; the MCP adapter ignores this namespace.
@@ -83,6 +96,8 @@ export interface PiHostExtras {
      * once attached to a tool definition.
      */
     promptGuidelines?: readonly string[];
+    renderCall?: PiToolCallRenderer;
+    renderResult?: PiToolResultRenderer;
 }
 /**
  * MCP-specific entries on `PortableTool.hostExtras`. Read only by the MCP
@@ -138,12 +153,12 @@ export interface PortableToolHostExtras {
     pi?: PiHostExtras;
     mcp?: McpHostExtras;
 }
-export interface PortableTool<TParams extends TSchema = TSchema> {
+export interface PortableTool<TParams extends TSchema = TSchema, TResult extends PortableToolResult = PortableToolResult> {
     name: string;
     title: string;
     description: string;
     parameters: TParams;
-    execute: (args: Static<TParams>, ctx: PortableToolContext) => PortableToolResult | Promise<PortableToolResult>;
+    execute: (args: Static<TParams>, ctx: PortableToolContext) => TResult | Promise<TResult>;
     /**
      * Optional per-host metadata. Adapters consume the keys they recognise;
      * unknown host namespaces are ignored. Absent → no behavior change.
@@ -155,4 +170,4 @@ export interface PortableTool<TParams extends TSchema = TSchema> {
      */
     hostExtras?: PortableToolHostExtras;
 }
-export declare function definePortableTool<TParams extends TSchema>(tool: PortableTool<TParams>): PortableTool<TParams>;
+export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult>(tool: PortableTool<TParams, TResult>): PortableTool<TParams, TResult>;

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

@@ -1,9 +1,22 @@
-import type { TSchema } from "typebox";
+import type { Static, TSchema } from "typebox";
 import type { PortableTool, PortableToolContext, PortableToolResult, PortableValidationError } from "./define-tool.js";
-export declare function validatePortableToolArgs(tool: PortableTool<TSchema>, args: unknown): {
+import type { PortableValidationFailure } from "./result-guards.js";
+type PortableToolSuccess<TResult extends PortableToolResult> = TResult & {
+    details?: Record<string, unknown>;
+    isError?: boolean;
+} & (TResult extends {
+    structuredContent?: infer TStructured;
+} ? {
+    structuredContent?: TStructured;
+} : {
+    structuredContent?: Record<string, unknown>;
+});
+export declare function validatePortableToolArgs<TParams extends TSchema>(tool: PortableTool<TParams>, args: unknown): {
     ok: true;
+    args: Static<TParams>;
 } | {
     ok: false;
     errors: PortableValidationError[];
 };
-export declare function executePortableTool(tool: PortableTool<TSchema>, args: unknown, ctx: PortableToolContext): Promise<PortableToolResult>;
+export declare function executePortableTool<TParams extends TSchema, TResult extends PortableToolResult>(tool: PortableTool<TParams, TResult>, args: unknown, ctx: PortableToolContext): Promise<PortableToolSuccess<TResult> | PortableValidationFailure>;
+export {};

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

@@ -151,17 +151,19 @@ function resolveSchemaAtPath(schema, instancePath) {
             return undefined;
         const obj = current;
         if (obj.properties && typeof obj.properties === "object" && segment in obj.properties) {
-            current = obj.properties[segment];
-            if (current === undefined)
+            const next = obj.properties[segment];
+            if (next === undefined)
                 return undefined;
+            current = next;
             continue;
         }
         if (obj.items !== undefined && /^\d+$/.test(segment)) {
             if (Array.isArray(obj.items)) {
                 const idx = Number(segment);
-                if (idx >= obj.items.length)
+                const next = getArrayEntry(obj.items, idx);
+                if (next === undefined)
                     return undefined;
-                current = obj.items[idx];
+                current = next;
             }
             else {
                 current = obj.items;
@@ -207,12 +209,26 @@ function branchDiscriminatorMatches(branch, value) {
     }
     return hasDiscriminator;
 }
+function findActiveUnionBranch(branches, value) {
+    let match;
+    for (const [index, branch] of branches.entries()) {
+        if (!branchDiscriminatorMatches(branch, value))
+            continue;
+        if (match !== undefined)
+            return undefined;
+        match = { index, branch };
+    }
+    return match;
+}
 function isSubsetOf(props, set) {
     for (const p of props)
         if (!set.has(p))
             return false;
     return true;
 }
+function getArrayEntry(entries, index) {
+    return index >= 0 && index < entries.length ? entries[index] : undefined;
+}
 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
@@ -253,17 +269,12 @@ function suppressSiblingErrorsUnderUnion(schema, value, errors) {
             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) {
+        const activeMatch = findActiveUnionBranch(branches, branchValue);
+        if (!activeMatch) {
             resolutions.set(path, { kind: "no-active" });
             continue;
         }
-        const activeIndex = matchedIndices[0];
-        const active = branches[activeIndex];
+        const { branch: active, index: activeIndex } = activeMatch;
         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
@@ -275,7 +286,10 @@ function suppressSiblingErrorsUnderUnion(schema, value, errors) {
         for (let i = 0; i < branches.length; i++) {
             if (i === activeIndex)
                 continue;
-            for (const [key, propSchema] of Object.entries(branches[i].properties ?? {})) {
+            const branch = getArrayEntry(branches, i);
+            if (!branch)
+                continue;
+            for (const [key, propSchema] of Object.entries(branch.properties ?? {})) {
                 const values = readDiscriminatorValues(propSchema);
                 if (values.length === 0)
                     continue;
@@ -404,7 +418,7 @@ function expandTypeBoxError(schema, error) {
 }
 export function validatePortableToolArgs(tool, args) {
     if (Check(tool.parameters, args)) {
-        return { ok: true };
+        return { ok: true, args };
     }
     // TypeBox can emit multiple errors per offending field (e.g. union/anyOf
     // mismatches fire one error per failed branch). First, when an anyOf/oneOf
@@ -443,5 +457,5 @@ export async function executePortableTool(tool, args, ctx) {
             isError: true,
         };
     }
-    return tool.execute(args, ctx);
+    return (await tool.execute(validation.args, ctx));
 }

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

@@ -29,25 +29,6 @@ export type PortableValidationFailure = PortableToolResult & {
 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

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

@@ -17,15 +17,23 @@
  *   }
  * }
  */
+function isPortableValidationError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return typeof candidate.field === "string" && typeof candidate.message === "string";
+}
 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));
+    const candidate = structured;
+    return (candidate.kind === "validation" &&
+        typeof candidate.tool === "string" &&
+        Array.isArray(candidate.validationErrors) &&
+        candidate.validationErrors.every(isPortableValidationError));
 }
 /**
  * Type guard for handler-emitted `isError: true` results that are not

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
-export { definePortableTool, type McpHostExtras, type PiHostExtras, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolErrorDetails, type PortableToolHostExtras, type PortableToolResult, type PortableValidationError, } from "./core/define-tool.js";
+export { definePortableTool, type McpHostExtras, type PiHostExtras, type PiToolCallRenderer, type PiToolResultRenderer, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolErrorDetails, type PortableToolHostExtras, 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/examples/README.md

@@ -145,7 +145,8 @@ In `package.json`:
 pi behavior:
 
 - Valid portable results become pi tool results.
-- Portable results with `isError: true` reject with `PortableToolExecutionError`; tests should assert a rejected execution plus error `.details`.
+- Invalid arguments and portable results with `isError: true` return `{ content, details, isError: true }` by default; tests should branch on `result.isError` and inspect `details`.
+- The legacy throw mode is still available with `registerPiTools(pi, tools, { errorHandling: "throw" })`, but it is deprecated and should not be used for new code.
 - Progress updates from `ctx.progress?.(...)` map to pi updates.
 
 ---
@@ -209,7 +210,7 @@ In `package.json`:
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "@feniix/bridgekit": "^0.2.2",
+    "@feniix/bridgekit": "^0.14.0",
     "typebox": "^1.1.31"
   }
 }
@@ -235,7 +236,7 @@ For mixed source-loaded pi + compiled MCP packages, keep the pi source entrypoin
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "@feniix/bridgekit": "^0.2.2",
+    "@feniix/bridgekit": "^0.14.0",
     "typebox": "^1.1.31"
   }
 }
@@ -251,12 +252,14 @@ await runBinWrapper({
   metaUrl: import.meta.url,
   mcpEntry: "dist/extensions/mcp-server.js",
   buildScript: "build:mcp",
+  // MCP stdio bins: keep build stdout off the JSON-RPC channel.
+  buildStdio: ["ignore", "inherit", "inherit"],
 });
 ```
 
-`mcpEntry` and `buildScript` are the two options consumers typically vary. The MCP entry module must export `runServer(): Promise<void>` (the convention used throughout these examples). `buildTimeoutMs` (default `60_000`) and `logPrefix` (default `"bridgekit-bin"`) are available for tuning but rarely needed.
+`mcpEntry` and `buildScript` are the two options consumers typically vary. The MCP entry module must export `runServer(): Promise<void>` (the convention used throughout these examples). `buildStdio`, `buildTimeoutMs` (default `60_000`), and `logPrefix` (default `"bridgekit-bin"`) are available for tuning but rarely needed outside MCP-stdio stdout isolation.
 
-Both `mcpEntry` and `buildScript` must be **literal strings** in your bin source. The helper joins `mcpEntry` onto the resolved package root and dynamically `import()`s it, and it passes `buildScript` to `spawnSync` (with `shell: true` on Windows where `&`, `|`, and `^` are shell metacharacters). Sourcing either from CLI args, environment variables, or other runtime input exposes arbitrary-file import and Windows command injection — the trusted-literal expectation is the threat model.
+Both `mcpEntry` and `buildScript` must be **literal strings** in your bin source. The helper joins `mcpEntry` onto the resolved package root and dynamically `import()`s it, and it passes `buildScript` to `spawnSync` (with `shell: true` on Windows where `&`, `|`, and `^` are shell metacharacters). BridgeKit rejects absolute/traversing entry paths and shell-shaped script names, but sourcing either option from CLI args, environment variables, or other runtime input remains outside the supported threat model.
 
 Commit the wrapper with executable mode (`chmod +x bin/my-tools-mcp.js`) and verify `npm pack --dry-run --json` includes it with executable mode.
 
@@ -272,11 +275,17 @@ MCP behavior:
 
 ## 4. Per-host metadata via `hostExtras`
 
-When a tool needs host-specific metadata — pi's `pendingMessage` for a "Processing..." signal, MCP's annotations as advisory hints to clients — the canonical place is `PortableTool.hostExtras`. Each host has its own namespace; adapters read the keys they recognise and ignore the rest. Tools that omit `hostExtras` see no behavior change.
+When a tool needs host-specific metadata — pi's `pendingMessage` for a "Processing..." signal, pi TUI renderers for custom collapsed/expanded display, or MCP's annotations as advisory hints to clients — the canonical place is `PortableTool.hostExtras`. Each host has its own namespace; adapters read the keys they recognise and ignore the rest. Tools that omit `hostExtras` see no behavior change.
 
 ```ts
 import { Type } from "typebox";
-import { definePortableTool } from "@feniix/bridgekit";
+import { definePortableTool, type PiToolCallRenderer, type PiToolResultRenderer } from "@feniix/bridgekit";
+
+const renderSummariseCall: PiToolCallRenderer = (args) => ({ type: "text", text: `summarise ${args.text}` });
+const renderSummariseResult: PiToolResultRenderer = (result, options) => ({
+  type: "text",
+  text: options.expanded ? result.content?.[0]?.text : "summary ready",
+});
 
 export const summariseTool = definePortableTool({
   name: "summarise",
@@ -293,6 +302,9 @@ export const summariseTool = definePortableTool({
       pendingMessage: "Summarising...",
       promptSnippet: "Use this tool when the user asks for a short summary.",
       promptGuidelines: ["Prefer < 80 chars.", "Strip markdown."],
+      // Opaque pi TUI callbacks. BridgeKit forwards these by identity.
+      renderCall: renderSummariseCall,
+      renderResult: renderSummariseResult,
     },
     mcp: {
       // Advisory hints clients may surface. Do not affect validation or
@@ -305,7 +317,7 @@ export const summariseTool = definePortableTool({
 
 Best practices for `hostExtras`:
 
-- Keep tool *behavior* host-neutral. `hostExtras` carries *data* the adapter reads on the tool's behalf; do not embed callbacks or runtime logic.
+- Keep portable tool *behavior* host-neutral. `hostExtras` carries host presentation metadata; pi renderers should stay presentation-only and are forwarded verbatim, not invoked by BridgeKit.
 - Set only the fields the adapter recognises; unrecognised keys are silently ignored, but they add noise to the definition.
 - If you ship an adapter for a host outside `"pi" | "mcp"`, cast `ctx.host` at the adapter boundary (the host union is fixed since 0.10.0). For type-safe per-host metadata in your adapter's namespace, extend `PortableToolHostExtras` via `declare module "@feniix/bridgekit"` so consumers of your adapter get type safety on the new namespace.
 
@@ -398,8 +410,8 @@ For publishable tool packages:
 - Avoid `workspace:` or `file:` ranges in publishable package dependencies.
 - Avoid dangling `sourceMappingURL` comments: either publish maps and useful sources, or disable source maps for package builds.
 - Ensure the npm bin entrypoint starts with a shebang, is executable (`chmod +x` or equivalent), and appears in `npm pack --dry-run --json` with executable mode.
-- When a bin depends on generated output, prefer a checked-in wrapper under `bin/` over pointing directly at `dist/`; test existing output, missing output, failed builds, and successful builds that omit the expected file.
+- When a bin depends on generated output, prefer a checked-in wrapper under `bin/` over pointing directly at `dist/`; for MCP stdio bins set `buildStdio: ["ignore", "inherit", "inherit"]`; test existing output, missing output, failed builds, and successful builds that omit the expected file.
 - If only the MCP bin needs compiled output, narrow its tsconfig to the MCP entrypoint and shared host-neutral modules instead of compiling unrelated host adapters.
 - Add a packed-install smoke test that installs tarballs into a temporary project.
-- For BridgeKit itself, run `npm run check`, `npm run test`, `npm run pack:dry-run`, and `npm run package-smoke` before release.
+- For BridgeKit itself, run `npm run check`, `npm run test`, `npm run pack:dry-run`, `npm run package-smoke`, and `npm audit --omit=dev --audit-level=high` before release.
 - Keep imports side-effect free; registration and server startup should happen only in explicit entrypoints.

package/llms.txt

@@ -26,7 +26,7 @@ import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper"; // optional: buil
 - Root entrypoint: host-neutral tool definitions, validation, and execution helpers.
 - `/pi`: pi adapter only.
 - `/mcp`: MCP server adapter only.
-- `/bin-wrapper`: optional helper for npm `bin` scripts that build a local compiled MCP entry on first invocation. `mcpEntry` and `buildScript` must be literal strings in the caller's source (they're the dynamic-import target and the `spawnSync` arg; sourcing them from env or CLI is an arbitrary-file-import and Windows command-injection vector).
+- `/bin-wrapper`: optional helper for npm `bin` scripts that build a local compiled MCP entry on first invocation. `mcpEntry` and `buildScript` must be literal strings in the caller's source (they're the dynamic-import target and the `spawnSync` arg; bridgekit rejects absolute/traversing entry paths and shell-shaped script names, but sourcing them from env or CLI remains outside the supported threat model).
 
 Do not deep-import from `dist/` or `src/` in consumer code. Reading published declarations for documentation is fine; imports should use the package entrypoints above.
 
@@ -69,16 +69,17 @@ export function createTools() {
 - TypeBox validation runs before the portable handler. If you need custom guidance for missing fields or wrong primitive types, use a permissive schema plus domain validation; otherwise accept BridgeKit's structural validation result.
 - MCP stdio entrypoints should be testable: export a server-options factory and a run function, then start stdio only when executed as the package bin.
 - Keep package runtime Node >=22.19.0 and ESM-only.
+- TypeScript is strict-plus: `strict`, `noUncheckedIndexedAccess`, and `exactOptionalPropertyTypes` are enabled.
 
 ## Host behavior
 
-- 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.
+- 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`; validation failures surface as `result.details.kind === "validation"`. The result guards from `@feniix/bridgekit` operate on `PortableToolResult` values at the portable seam, not directly on the pi wire object.
+- MCP invalid arguments and portable `isError: true` results return `CallToolResult` with `isError: true`. Inspect `structuredContent` on MCP wire results, or use the guards on `PortableToolResult` values before/at the adapter seam.
 - 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), `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.
-- `PortableTool.hostExtras` (0.9+) carries optional per-host metadata in namespaced sub-objects (`pi`, `mcp`, plus module-augmentable custom hosts). Each field is optional and zero-cost when absent — a tool without `hostExtras` produces byte-identical pi registration and MCP `tools/list` payloads to 0.8.x. `hostExtras.pi.pendingMessage` fires `onUpdate({ content, details: { status: "pending" } })` exactly once before TypeBox validation; `hostExtras.pi.promptSnippet` / `promptGuidelines` pass through verbatim to pi's `registerTool` call; `hostExtras.mcp.annotations` (`title` / `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`) attaches MCP advisory hints. Tool definitions stay host-neutral — host-specific metadata lives in its namespace, not on the tool's top-level fields.
+- `PortableTool.hostExtras` (0.9+) carries optional per-host metadata in namespaced sub-objects (`pi`, `mcp`, plus module-augmentable custom hosts). Each field is optional and zero-cost when absent — a tool without `hostExtras` produces byte-identical pi registration and MCP `tools/list` payloads to 0.8.x. `hostExtras.pi.pendingMessage` fires `onUpdate({ content, details: { status: "pending" } })` exactly once before TypeBox validation; `hostExtras.pi.promptSnippet` / `promptGuidelines` pass through to pi's `registerTool`; `hostExtras.pi.renderCall` / `renderResult` are opaque TUI callbacks typed by exported `PiToolCallRenderer` / `PiToolResultRenderer` aliases and forwarded by identity; `hostExtras.mcp.annotations` (`title` / `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`) attaches MCP advisory hints. Tool definitions stay host-neutral — host-specific metadata lives in its namespace, not on the tool's top-level fields.
 
 ### Result-guard usage
 
@@ -119,7 +120,7 @@ Some hosts, such as pi in source-extension packages, may intentionally load Type
   });
   ```
 
-  `mcpEntry` and `buildScript` must be literal strings — sourcing them from CLI args or env vars opens arbitrary-file import and Windows command injection. The MCP entry module must export `async function runServer(): Promise<void>`. `buildStdio` defaults to `"inherit"`; MCP stdio server bins should override to `["ignore", "inherit", "inherit"]` (since 0.13.0) because `process.stdout` is the JSON-RPC channel and the build subprocess otherwise contaminates framing.
+  `mcpEntry` and `buildScript` must be literal strings — bridgekit rejects absolute/traversing entry paths and shell-shaped script names, but sourcing them from CLI args or env vars remains outside the supported threat model. The MCP entry module must export `async function runServer(): Promise<void>`. `buildStdio` defaults to `"inherit"`; MCP stdio server bins should override to `["ignore", "inherit", "inherit"]` (since 0.13.0) because `process.stdout` is the JSON-RPC channel and the build subprocess otherwise contaminates framing.
 - Narrow the MCP build to the MCP entrypoint and shared host-neutral modules; avoid compiling pi adapter entrypoints into the standalone MCP path.
 - Put runtime imports used by the compiled MCP bin in `dependencies`, not only peers or dev dependencies.
 - Declare BridgeKit's Node engine requirement in the downstream package (`>=22.19.0`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -73,10 +73,10 @@
     "typebox": "^1.1.31"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.10",
+    "@biomejs/biome": "2.4.16",
     "@total-typescript/shoehorn": "^0.1.2",
-    "@types/node": "^22.19.17",
-    "typescript": "^5.5.0"
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
   },
   "license": "MIT"
 }