@feniix/bridgekit 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ 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).
 
+## [Unreleased]
+
+## [0.16.0] - 2026-10-06
+
+### Added
+
+- Optional object-shaped `PortableTool.outputSchema`. Successful calls must return
+  matching `structuredContent`; missing or invalid output throws a tool-attributed
+  `TypeError`. Argument and domain failures are exempt from success schemas.
+- Pi registrations forward `outputSchema`, and Pi results preserve
+  `structuredContent` alongside the existing renderer-facing `details`.
+- MCP listings forward object-shaped output schemas, including intersections;
+  invalid output schemas are rejected at server construction.
+- Schema-declaring `definePortableTool` calls check successful structured data at
+  compile time while preserving inferred result unions; explicit annotations can
+  retain schemas with a third `PortableTool` generic. Domain failures are exempt.
+  Explicit legacy two-generic function calls intentionally erase schema linkage
+  and retain runtime validation; inferred calls are recommended for type checking.
+- Output-schema construction failures carry stable diagnostic codes, with
+  reference/union-specific recipes and MCP constructor attribution.
+
+### Changed (breaking)
+
+- MCP runtime now uses `@modelcontextprotocol/server` SDK v2. `createMcpServer`
+  returns a v2 `Server`; consumers using its low-level API must migrate method
+  registration/context types and must not mix v1 and v2 SDK instances.
+- `runMcpStdioServer` now serves both legacy MCP clients and modern protocol
+  `2026-07-28` via `serveStdio`. Its `Promise<void>` startup signature is unchanged.
+  This change requires a pre-1.0 minor release, not a patch.
+
+### Fixed
+
+- Discarded modern stdio discovery probes no longer contaminate legacy fallback:
+  each factory invocation gets a fresh server. SDK-reported opening errors are
+  diagnosed on stderr without contaminating protocol stdout.
+- Pi validates all output schemas before registering tools, preventing partial
+  registration when a later tool has an invalid schema.
+- `definePortableTool` retains metadata composition and already-annotated
+  two-generic inputs while still checking concrete schema-bearing handlers.
+  Packed declarations pin both valid and invalid replacement handlers.
+
+## [0.15.0] - 2026-07-12
+
+### Added
+
+- `PiHostExtras` accepts `renderCall` and `renderResult`, pi's per-tool TUI
+  renderers for the call line and for the collapsed/expanded result view.
+  `registerPiTools` forwards both to `pi.registerTool` by identity; the core
+  never invokes them and does not import `pi-tui`. Contributed by
+  [@akaGelo](https://github.com/akaGelo) in
+  [#72](https://github.com/feniix/bridgekit/pull/72).
+
+### Changed
+
+- `docs/rfc-host-extras.md` records the renderers as Gap E, in scope as a
+  registration-time pass-through.
+
 ## [0.14.0] - 2026-05-28
 
 ### Added

package/README.md

@@ -2,6 +2,8 @@
 
 BridgeKit provides reusable TypeBox-backed tool definitions and adapters for exposing one tool implementation through pi, MCP, and other hosts.
 
+More about why this exists and where it is useful: [feniix-hq.net/projects/bridgekit](https://feniix-hq.net/projects/bridgekit/).
+
 ## Quickstart
 
 ```ts
@@ -83,6 +85,8 @@ import {
   executePortableTool,
   isDomainFailure,
   isValidationFailure,
+  type PiToolCallRenderer,
+  type PiToolResultRenderer,
   type PortableTool,
   type PortableToolBuiltInHost,
   type PortableToolContext,
@@ -105,6 +109,48 @@ Do not deep-import from `dist/` or `src/` in consuming packages.
 
 ### pi adapter
 
+#### Declared structured output
+
+Add an optional object-shaped `outputSchema` to a portable tool to describe its
+successful `structuredContent` for both Pi and MCP:
+
+```ts
+const echoTool = definePortableTool({
+  name: "echo",
+  title: "Echo",
+  description: "Echo text.",
+  parameters: Type.Object({ text: Type.String() }),
+  outputSchema: Type.Object({ text: Type.String() }),
+  execute: (args) => ({ text: args.text, structuredContent: { text: args.text } }),
+});
+```
+
+Inlined object schemas and intersections of objects are accepted. Success calls
+must return matching `structuredContent`; legacy `details` alone does not satisfy
+the schema. Missing/invalid output throws a tool-attributed `TypeError` at the
+portable seam and becomes an error result through the adapters. Argument/domain
+failures are exempt from success schemas. Without `outputSchema`, existing result
+behavior is unchanged.
+
+`definePortableTool` infers the output schema and checks synchronous/asynchronous
+successful data at compile time while preserving the handler's inferred result
+type. Domain failures must use the literal `isError: true` discriminator.
+Runtime validation still protects JavaScript callers and dynamically sourced data.
+For explicitly annotated tools, use the third `PortableTool<TParams, TResult, TOutput>`
+generic to retain schema checking; existing two-generic annotations deliberately
+erase schema specificity.
+Explicit legacy `definePortableTool<TParams, TResult>(...)` calls also erase the
+schema, even with a concrete `outputSchema`. Prefer inferred calls for compile-time
+schema checking; runtime output validation still applies to the explicit calls.
+Existing annotated tools and metadata-only spreads remain accepted by
+`definePortableTool`; concrete schema-bearing spreads still check replacement
+handlers. Treat `parameters` and `outputSchema` as immutable after registration:
+do not mutate their contents or replace either schema object.
+
+Pi registrations forward the schema; Pi results now preserve `structuredContent`
+directly for programmatic/codemode consumers, alongside the renderer-facing
+`details` described below. The new fields are omitted when not supplied.
+
 ```ts
 import { registerPiTools } from "@feniix/bridgekit/pi";
 import { createTools } from "./tools.js";
@@ -167,13 +213,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 +242,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 +253,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
@@ -241,7 +298,30 @@ 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. 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).
+The two adapters return `{ isError: true }` for argument/domain failures by default.
+Use result guards on portable values; both wire formats now preserve `structuredContent`,
+and Pi also exposes its renderer-facing `details`.
+The guards match error/data shape, not provenance, so Pi wire failures also match
+at runtime. Raw Pi values still lack portable `text`; do not cast them to
+`PortableToolResult` to use the typed guards.
+
+#### MCP SDK v2 and modern stdio
+
+`runMcpStdioServer(options)` serves both legacy MCP revisions and modern
+`2026-07-28` through SDK v2's `serveStdio`. Its `Promise<void>` resolves after
+startup wiring, not at shutdown. Stdin EOF closes the connection; long-running
+tools must honor `ctx.signal` and release their own resources.
+
+`createMcpServer` now returns `@modelcontextprotocol/server` SDK v2's low-level
+`Server`. This is a source-level breaking change for consumers using SDK methods
+or types, even though legacy clients work over the wire. A direct
+`server.connect(StdioServerTransport)` remains legacy-only; use the runner for
+modern serving. See [migration guidance](docs/mcp-v2-migration.md).
+
+Some SDK v1 clients validate error data against cached success output schemas
+in their convenience `callTool` method; their generic request API can preserve
+that data. SDK v2 clients correctly exempt error results. HTTP and tasks remain
+outside BridgeKit's runner support.
 
 ### bin-wrapper (since 0.11.0)
 

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

@@ -1,4 +1,4 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { Server } from "@modelcontextprotocol/server";
 import type { TSchema } from "typebox";
 import type { PortableTool } from "../core/define-tool.js";
 export interface CreateMcpServerOptions {
@@ -14,7 +14,7 @@ export interface CreateMcpServerOptions {
      * The outer array is snapshotted at construction; pushing or removing
      * entries from the caller's `tools` array post-construction does not affect
      * `tools/list` or `tools/call`. Schemas inside each tool are held by
-     * reference, not deep-cloned — treat `tool.parameters` as immutable once
+     * reference, not deep-cloned — treat `tool.parameters` and `tool.outputSchema` as immutable once
      * `createMcpServer` returns.
      */
     tools: readonly PortableTool<TSchema>[];

package/dist/src/adapters/mcp.js

@@ -1,7 +1,7 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { Server } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { executePortableTool } from "../core/execute-tool.js";
+import { assertPortableOutputSchema, isObjectSchema, schemaTypeLabel, throwWithCode } from "../core/output-schema.js";
 function toMcpResult(result) {
     return {
         content: [{ type: "text", text: result.text }],
@@ -10,85 +10,22 @@ function toMcpResult(result) {
     };
 }
 /**
- * Returns true if `schema` resolves to a JSON-Schema object at the top level —
- * either `{"type": "object", ...}` directly, or an `allOf` composition whose
- * branches are all object schemas (as produced by `Type.Intersect`).
- *
- * The check walks the canonical JSON-Schema shape rather than poking at
- * TypeBox `Kind` symbols, mirroring how `executePortableTool` traverses
- * schemas. The MCP wire contract is "top-level object," so that's the
- * predicate, regardless of which TypeBox combinator built the schema.
- */
-function isObjectSchema(schema) {
-    if (typeof schema !== "object" || schema === null)
-        return false;
-    const candidate = schema;
-    // $ref takes structural precedence: a hybrid {type: "object", $ref: "..."}
-    // is not an inlined object schema — it's a reference, and
-    // assertObjectShapedParameters owns the rejection recipe. Return false so
-    // the $ref branch runs.
-    if (typeof candidate.$ref === "string")
-        return false;
-    if (candidate.type === "object")
-        return true;
-    if (Array.isArray(candidate.allOf) && candidate.allOf.length > 0) {
-        return candidate.allOf.every((entry) => isObjectSchema(entry));
-    }
-    return false;
-}
-/**
- * Best-effort human-readable label for a non-object schema, used in error
- * messages. For `allOf` (TypeBox's `Intersect` lowering) we descend into the
- * branches and surface the first non-object branch by index — a bare `"allOf"`
- * label is misleading because the rejection is owned by one specific branch,
- * not the composition itself.
- *
- * The `$ref` check is first because `Type.Cyclic` produces
- * `{ $defs: {...}, $ref: "..." }` at the root; the `$ref` is the load-bearing
- * structural signal regardless of what else is set, and the recipe for that
- * shape (inline or split) is different from the generic `Type.Object(...)`
- * wrap recipe.
- */
-function schemaTypeLabel(schema) {
-    if (typeof schema !== "object" || schema === null)
-        return "unknown";
-    const candidate = schema;
-    if (typeof candidate.$ref === "string")
-        return "$ref";
-    if (typeof candidate.type === "string")
-        return candidate.type;
-    if (Array.isArray(candidate.anyOf))
-        return "anyOf";
-    if (Array.isArray(candidate.oneOf))
-        return "oneOf";
-    if (Array.isArray(candidate.allOf)) {
-        if (candidate.allOf.length === 0)
-            return "allOf (empty)";
-        for (let i = 0; i < candidate.allOf.length; i++) {
-            if (!isObjectSchema(candidate.allOf[i])) {
-                return `allOf[${i}] resolves to type="${schemaTypeLabel(candidate.allOf[i])}"`;
-            }
-        }
-    }
-    return "unknown";
-}
-/**
- * Render `parameters` as MCP `inputSchema`. The MCP SDK Zod-validates that the
- * top-level schema has `type: "object"` on the client side of `tools/list`, so
+ * Render a validated object schema as MCP `inputSchema` or `outputSchema`.
+ * MCP clients require the top-level schema to have `type: "object"`, so
  * `Type.Intersect` (which TypeBox renders as `{ allOf: [...] }` with no top-
  * level `type`) needs `type: "object"` synthesized before transmission. This
  * is a no-op for `Type.Object` schemas, which already carry the field.
  *
- * The casts here are sound because `assertObjectShapedParameters` runs first
- * and rejects any schema whose top-level lowering isn't `type:"object"` or
- * `allOf` of objects — both shapes round-trip as MCP `Tool["inputSchema"]`.
+ * The casts here are sound because `assertObjectShapedParameters` or
+ * `assertPortableOutputSchema` runs first and rejects schemas whose top-level
+ * lowering isn't `type:"object"` or `allOf` of objects.
  */
-function toInputSchema(parameters) {
-    const candidate = parameters;
+function toMcpObjectSchema(schema) {
+    const candidate = schema;
     if (candidate.type === "object") {
-        return parameters;
+        return schema;
     }
-    return { type: "object", ...parameters };
+    return { type: "object", ...schema };
 }
 /**
  * Stable `error.code` values attached to `createMcpServer` construction
@@ -98,11 +35,6 @@ function toInputSchema(parameters) {
 const ERROR_CODE_NON_OBJECT_PARAMETERS = "BRIDGEKIT_MCP_NON_OBJECT_PARAMETERS";
 const ERROR_CODE_REF_PARAMETERS = "BRIDGEKIT_MCP_REF_PARAMETERS";
 const ERROR_CODE_DUPLICATE_TOOL_NAME = "BRIDGEKIT_MCP_DUPLICATE_TOOL_NAME";
-function throwWithCode(message, code) {
-    const error = new Error(message);
-    error.code = code;
-    throw error;
-}
 function assertObjectShapedParameters(tools) {
     for (const tool of tools) {
         if (!isObjectSchema(tool.parameters)) {
@@ -150,6 +82,8 @@ function assertUniqueToolNames(tools) {
     }
 }
 export function createMcpServer(options) {
+    for (const tool of options.tools)
+        assertPortableOutputSchema(tool, "createMcpServer", "BRIDGEKIT_MCP");
     assertObjectShapedParameters(options.tools);
     assertUniqueToolNames(options.tools);
     // Build the dispatch map and the listing payload at construction so
@@ -176,7 +110,8 @@ export function createMcpServer(options) {
             name: tool.name,
             title: tool.title,
             description: tool.description,
-            inputSchema: toInputSchema(tool.parameters),
+            inputSchema: toMcpObjectSchema(tool.parameters),
+            ...(tool.outputSchema !== undefined && { outputSchema: toMcpObjectSchema(tool.outputSchema) }),
             ...(hasAnnotations ? { annotations: { ...annotations } } : {}),
         };
     });
@@ -184,8 +119,8 @@ export function createMcpServer(options) {
         capabilities: { tools: { listChanged: false } },
         ...(options.instructions !== undefined && { instructions: options.instructions }),
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: mcpTools }));
-    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    server.setRequestHandler("tools/list", async () => ({ tools: mcpTools }));
+    server.setRequestHandler("tools/call", async (request, ctx) => {
         const tool = byName.get(request.params.name);
         if (!tool) {
             return {
@@ -196,9 +131,9 @@ export function createMcpServer(options) {
         try {
             const result = await executePortableTool(tool, request.params.arguments ?? {}, {
                 host: "mcp",
-                signal: extra.signal,
+                signal: ctx.mcpReq.signal,
             });
-            return toMcpResult(result);
+            return server.projectCallToolResult(toMcpResult(result), tool.outputSchema !== undefined ? toMcpObjectSchema(tool.outputSchema) : undefined);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -211,6 +146,10 @@ export function createMcpServer(options) {
     return server;
 }
 export async function runMcpStdioServer(options) {
-    const server = createMcpServer(options);
-    await server.connect(new StdioServerTransport());
+    // Validate eagerly, but each discarded probe/connection must own its server:
+    // a modern probe installs era-specific handlers before it can be discarded.
+    createMcpServer(options);
+    serveStdio(() => createMcpServer(options), {
+        onerror: (error) => process.stderr.write(`[bridgekit-mcp] ${error.message}\n`),
+    });
 }

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;
@@ -11,6 +11,7 @@ type PiToolUpdate = {
 type PiToolResult = {
     content: PiContent[];
     details: Record<string, unknown>;
+    structuredContent?: Record<string, unknown>;
     isError?: boolean;
 };
 type PiToolDefinition = {
@@ -18,9 +19,12 @@ type PiToolDefinition = {
     label: string;
     description: string;
     parameters: TSchema;
+    outputSchema?: TSchema;
     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

@@ -1,4 +1,5 @@
 import { executePortableTool } from "../core/execute-tool.js";
+import { assertPortableOutputSchema } from "../core/output-schema.js";
 import { isValidationFailure } from "../core/result-guards.js";
 function toPiDetails(result) {
     return result.structuredContent ?? result.details ?? {};
@@ -40,6 +41,8 @@ let throwModeDeprecationWarned = false;
  * registerPiTools(pi, tools, { errorHandling: "throw" });
  */
 export function registerPiTools(pi, tools, options = {}) {
+    for (const tool of tools)
+        assertPortableOutputSchema(tool);
     const errorHandling = options.errorHandling ?? "return";
     if (errorHandling === "throw" && !throwModeDeprecationWarned) {
         throwModeDeprecationWarned = true;
@@ -56,6 +59,7 @@ export function registerPiTools(pi, tools, options = {}) {
             label: tool.title,
             description: tool.description,
             parameters: tool.parameters,
+            ...(tool.outputSchema !== undefined && { outputSchema: tool.outputSchema }),
             // Pass-through pi-side metadata. Each field is gated on `!== undefined`
             // so tools without `hostExtras.pi` build a registration object whose
             // own-property keys are unchanged from the pre-0.9 shape.
@@ -65,6 +69,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 {
@@ -113,6 +120,7 @@ export function registerPiTools(pi, tools, options = {}) {
                 return {
                     content: [{ type: "text", text: result.text }],
                     details: toPiDetails(result),
+                    ...(result.structuredContent !== undefined && { structuredContent: result.structuredContent }),
                     isError: result.isError === true,
                 };
             },

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,28 @@ export interface PortableToolHostExtras {
     pi?: PiHostExtras;
     mcp?: McpHostExtras;
 }
-export interface PortableTool<TParams extends TSchema = TSchema, TResult extends PortableToolResult = PortableToolResult> {
+/** Successes satisfy the output schema; literal domain failures retain arbitrary data. */
+type SchemaResult<TOutput extends TSchema> = (PortableToolResult & {
+    structuredContent: Exclude<Static<TOutput>, undefined> & Record<string, unknown>;
+    isError?: false;
+}) | (PortableToolResult & {
+    isError: true;
+});
+type CheckedResult<TResult extends PortableToolResult, TOutput extends TSchema | undefined> = [TOutput] extends [
+    TSchema
+] ? TResult & SchemaResult<NoInfer<Extract<TOutput, TSchema>>> : TResult;
+export interface PortableTool<TParams extends TSchema = TSchema, TResult extends PortableToolResult = PortableToolResult, TOutput extends TSchema | undefined = TSchema | undefined> {
     name: string;
     title: string;
     description: string;
     parameters: TParams;
-    execute: (args: Static<TParams>, ctx: PortableToolContext) => TResult | Promise<TResult>;
+    /**
+     * Object-shaped TypeBox schema for successful structuredContent.
+     * Literal isError:true results are exempt. Treat this schema and parameters
+     * as immutable after registration, including replacing either schema object.
+     */
+    outputSchema?: TOutput;
+    execute: (args: Static<TParams>, ctx: PortableToolContext) => CheckedResult<TResult, TOutput> | Promise<CheckedResult<TResult, TOutput>>;
     /**
      * Optional per-host metadata. Adapters consume the keys they recognise;
      * unknown host namespaces are ignored. Absent → no behavior change.
@@ -155,4 +186,18 @@ export interface PortableTool<TParams extends TSchema = TSchema, TResult extends
      */
     hostExtras?: PortableToolHostExtras;
 }
-export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult>(tool: PortableTool<TParams, TResult>): PortableTool<TParams, TResult>;
+export declare function definePortableTool<TParams extends TSchema, TOutput extends TSchema, TExecute extends (args: Static<TParams>, ctx: PortableToolContext) => SchemaResult<NoInfer<TOutput>> | Promise<SchemaResult<NoInfer<TOutput>>>>(tool: Omit<PortableTool<TParams, PortableToolResult, TOutput>, "execute" | "outputSchema"> & {
+    outputSchema: TOutput;
+    execute: TExecute;
+}): PortableTool<TParams, Awaited<ReturnType<TExecute>>, TOutput>;
+export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult>(tool: PortableTool<TParams, TResult> & {
+    outputSchema?: undefined;
+}): PortableTool<TParams, TResult, undefined>;
+export declare function definePortableTool<TParams extends TSchema, TOutput extends TSchema, TExecute extends (args: Static<TParams>, ctx: PortableToolContext) => SchemaResult<NoInfer<TOutput>> | Promise<SchemaResult<NoInfer<TOutput>>>>(tool: Omit<PortableTool<TParams, PortableToolResult, TOutput>, "execute" | "outputSchema"> & {
+    outputSchema?: TOutput;
+    execute: TExecute;
+}): PortableTool<TParams, Awaited<ReturnType<TExecute>>, TOutput>;
+export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult, TTool extends {
+    outputSchema?: TSchema | undefined;
+} = PortableTool<TParams, TResult>>(tool: PortableTool<TParams, TResult> & TTool & (TSchema extends NonNullable<NoInfer<TTool>["outputSchema"]> ? unknown : never)): TTool;
+export {};

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

@@ -1,4 +1,5 @@
 import { Check, Errors, Pointer } from "typebox/value";
+import { assertPortableOutputSchema } from "./output-schema.js";
 const ROOT_FIELD = "(root)";
 function fieldFromPath(instancePath) {
     return instancePath.split("/").filter(Boolean).at(-1) ?? ROOT_FIELD;
@@ -443,6 +444,7 @@ export function validatePortableToolArgs(tool, args) {
     return { ok: false, errors };
 }
 export async function executePortableTool(tool, args, ctx) {
+    assertPortableOutputSchema(tool);
     const validation = validatePortableToolArgs(tool, args);
     if (!validation.ok) {
         return {
@@ -457,5 +459,13 @@ export async function executePortableTool(tool, args, ctx) {
             isError: true,
         };
     }
-    return (await tool.execute(validation.args, ctx));
+    const result = await tool.execute(validation.args, ctx);
+    if (tool.outputSchema !== undefined &&
+        result.isError !== true &&
+        (result.structuredContent === undefined || !Check(tool.outputSchema, result.structuredContent))) {
+        // A handler violating its declared success contract is a programmer error,
+        // not an argument failure. Keep inferred success/error result types intact.
+        throw new TypeError(`Invalid structured output for ${tool.name}: structuredContent must match outputSchema.`);
+    }
+    return result;
 }

package/dist/src/core/output-schema.d.ts

@@ -0,0 +1,7 @@
+import type { PortableTool } from "./define-tool.js";
+/** Follow JSON Schema structure rather than TypeBox-specific symbols. */
+export declare function isObjectSchema(schema: unknown): boolean;
+/** Identify the first unsupported root/branch for an actionable schema diagnostic. */
+export declare function schemaTypeLabel(schema: unknown): string;
+export declare function throwWithCode(message: string, code: string, ErrorType?: ErrorConstructor): never;
+export declare function assertPortableOutputSchema(tool: PortableTool, context?: string, codePrefix?: string): void;

package/dist/src/core/output-schema.js

@@ -0,0 +1,53 @@
+/** Follow JSON Schema structure rather than TypeBox-specific symbols. */
+export function isObjectSchema(schema) {
+    if (typeof schema !== "object" || schema === null)
+        return false;
+    const candidate = schema;
+    if (typeof candidate.$ref === "string")
+        return false;
+    if (candidate.type === "object")
+        return true;
+    return Array.isArray(candidate.allOf) && candidate.allOf.length > 0 && candidate.allOf.every(isObjectSchema);
+}
+/** Identify the first unsupported root/branch for an actionable schema diagnostic. */
+export function schemaTypeLabel(schema) {
+    if (typeof schema !== "object" || schema === null)
+        return "unknown";
+    const candidate = schema;
+    if (typeof candidate.$ref === "string")
+        return "$ref";
+    if (typeof candidate.type === "string")
+        return candidate.type;
+    if (Array.isArray(candidate.anyOf))
+        return "anyOf";
+    if (Array.isArray(candidate.oneOf))
+        return "oneOf";
+    if (Array.isArray(candidate.allOf)) {
+        if (candidate.allOf.length === 0)
+            return "allOf (empty)";
+        for (let i = 0; i < candidate.allOf.length; i++) {
+            if (!isObjectSchema(candidate.allOf[i])) {
+                return `allOf[${i}] resolves to type="${schemaTypeLabel(candidate.allOf[i])}"`;
+            }
+        }
+    }
+    return "unknown";
+}
+export function throwWithCode(message, code, ErrorType = Error) {
+    const error = new ErrorType(message);
+    error.code = code;
+    throw error;
+}
+export function assertPortableOutputSchema(tool, context, codePrefix = "BRIDGEKIT") {
+    if (tool.outputSchema !== undefined && !isObjectSchema(tool.outputSchema)) {
+        const label = schemaTypeLabel(tool.outputSchema);
+        let recipe = "Use an inlined object schema or an intersection of object schemas.";
+        if (label.includes("$ref")) {
+            recipe += " Top-level $ref / Type.Cyclic is unsupported; inline the referenced shape or split recursive shapes.";
+        }
+        else if (label.includes("anyOf") || label.includes("oneOf")) {
+            recipe += " Top-level unions are unsupported; flatten branches into one object or expose separate tools.";
+        }
+        throwWithCode(`${context ? `${context}: ` : ""}Invalid outputSchema for ${tool.name} (type="${label}"): ${recipe}`, `${codePrefix}_${label.includes("$ref") ? "REF" : "NON_OBJECT"}_OUTPUT_SCHEMA`, TypeError);
+    }
+}

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

@@ -144,7 +144,8 @@ In `package.json`:
 
 pi behavior:
 
-- Valid portable results become pi tool results.
+- Valid portable results become pi tool results with `structuredContent` preserved
+  alongside renderer-facing `details`. Optional `outputSchema` is forwarded.
 - 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.
@@ -269,17 +270,27 @@ MCP behavior:
 - `tools/call` validates arguments before invoking handlers.
 - Invalid arguments and portable `isError: true` results return MCP tool results with `isError: true`.
 - Unexpected thrown errors become MCP tool errors with text content.
+- Optional object-shaped `outputSchema` is listed for successful structured results;
+  matching `structuredContent` is required and validated. Error results are exempt.
+- The stdio runner serves legacy and modern `2026-07-28` clients through SDK v2.
+  It retains `Promise<void>` startup behavior; stdin EOF shuts down the connection.
 - The module stays import-passive and testable: tests can import `createMcpServerOptions()` without starting stdio.
 
 ---
 
 ## 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 +307,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 +322,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

@@ -59,6 +59,18 @@ export function createTools() {
 - Keep portable tools host-neutral. Do not import pi or MCP SDKs from files that define tool behavior.
 - Tool `parameters` for MCP-compatible tools must resolve to a JSON-Schema object at the top level. `Type.Object(...)` is the common case; `Type.Intersect([Type.Object(...), Type.Object(...)])` is also accepted. Non-object top-level shapes throw at `createMcpServer` construction.
 - Return `{ text, structuredContent }` for successful results.
+- Optional `outputSchema` declares successful structured data for both hosts: use
+  an inlined TypeBox object or object intersection. Missing/invalid successful
+  `structuredContent` throws `TypeError`; argument/domain error results are exempt.
+  Legacy `details` alone does not satisfy a declared output schema.
+  `definePortableTool` infers/checks schema-linked success data at compile time;
+  use literal `isError: true` for exempt domain failures. A third
+  `PortableTool<TParams, TResult, TOutput>` generic preserves the schema in explicit
+  annotations; legacy two-generic annotations erase it. Runtime checks still apply.
+  Explicit legacy `definePortableTool<TParams, TResult>(...)` calls also erase
+  schema inference, even for concrete schemas; prefer inferred calls for checking.
+  Existing tool annotations and metadata spreads remain composable. Treat both
+  `parameters` and `outputSchema` as immutable after registration (no mutation or replacement).
 - Use `isError: true` for domain/tool-level failures that should reach the model as tool output.
 - Throw only for unexpected programmer, adapter, or runtime failures.
 - Respect `ctx.signal` in long-running tools.
@@ -75,11 +87,21 @@ export function createTools() {
 
 - 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.
+- Both adapters preserve `structuredContent`; Pi also maps it into renderer-facing
+  `details`. Both retain legacy `details` fallback. Output schemas are forwarded
+  to registrations/listings only when provided.
 - 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`.
+- Result guards take `PortableToolResult` values from `executePortableTool`, not
+  raw Pi wire objects (`content` instead of portable `text`).
+  Their runtime predicates are shape-based, so Pi structured failures also
+  match; that does not make a raw Pi result a valid portable typed value.
+- MCP uses SDK v2's low-level `Server` and method-string handlers. Cancellation
+  reads `ctx.mcpReq.signal`. `runMcpStdioServer` serves legacy and modern
+  `2026-07-28` stdio; direct `Server.connect` remains legacy-only. The runner's
+  `Promise<void>` resolves at startup, not EOF. Migration details:
+  `docs/mcp-v2-migration.md`.
 - `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.16.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -23,7 +23,7 @@
   "bugs": {
     "url": "https://github.com/feniix/bridgekit/issues"
   },
-  "homepage": "https://github.com/feniix/bridgekit#readme",
+  "homepage": "https://feniix-hq.net/projects/bridgekit/",
   "exports": {
     ".": {
       "types": "./dist/src/index.d.ts",
@@ -69,11 +69,13 @@
     "examples/README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "^2.3.1",
     "typebox": "^1.1.31"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.16",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@biomejs/biome": "2.5.4",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/node": "^25.9.1",
     "typescript": "^6.0.3"