@feniix/bridgekit 0.14.0 → 0.15.0

package/README.md

@@ -83,6 +83,8 @@ import {
   executePortableTool,
   isDomainFailure,
   isValidationFailure,
+  type PiToolCallRenderer,
+  type PiToolResultRenderer,
   type PortableTool,
   type PortableToolBuiltInHost,
   type PortableToolContext,
@@ -167,13 +169,19 @@ 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",
@@ -190,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 },
@@ -198,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

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 {

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

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

@@ -275,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",
@@ -296,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
@@ -308,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.
 

package/llms.txt

@@ -79,7 +79,7 @@ export function createTools() {
 - 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
 

package/package.json

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