@feniix/bridgekit 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -4,6 +4,76 @@ 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.1] - 2026-10-06
+
+### Fixed
+
+- Validation errors report correct field names under TypeBox 1.3+, which the
+  `typebox ^1.1.31` range already resolves to on fresh installs. TypeBox 1.3
+  escapes JSON Pointer paths per RFC 6901, so a property named `a/b` surfaced as
+  `a~1b` (and `a~b` as `a~0b`); fields are now decoded back to the literal key.
+- `additionalProperties` violations are reported once per key again. TypeBox 1.3
+  adds a per-key sub-schema error beside the summary, which duplicated fields and
+  let a losing union branch's closed-object errors slip past phantom suppression.
+  Both TypeBox 1.1 and 1.3 now produce identical validation errors.
+
+## [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
@@ -107,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";
@@ -254,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

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

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.
@@ -116,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

@@ -153,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.
@@ -170,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,17 +1,30 @@
 import { Check, Errors, Pointer } from "typebox/value";
+import { assertPortableOutputSchema } from "./output-schema.js";
 const ROOT_FIELD = "(root)";
+/**
+ * Decode one RFC 6901 JSON Pointer segment (`~1` → `/`, `~0` → `~`).
+ *
+ * TypeBox 1.3+ escapes property names in `instancePath` and `schemaPath`
+ * (`"a/b"` → `/a~1b`); TypeBox 1.1 did not. The package range spans both, so
+ * every lookup tries the raw segment first and the decoded form second.
+ */
+function decodePointerSegment(segment) {
+    return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
 function fieldFromPath(instancePath) {
-    return instancePath.split("/").filter(Boolean).at(-1) ?? ROOT_FIELD;
+    const last = instancePath.split("/").filter(Boolean).at(-1);
+    return last === undefined ? ROOT_FIELD : decodePointerSegment(last);
 }
 /**
  * Resolve the leaf property name from a TypeBox error by walking
  * `error.schemaPath` rather than `error.instancePath`.
  *
- * `instancePath` does not escape `/` inside property names (TypeBox does not
- * follow JSON Pointer RFC 6901's `~1` encoding), so a schema with BOTH a
- * slash-named property `"a/b"` AND a nested path `a.b` produces the same
+ * Before 1.3, TypeBox's `instancePath` did not escape `/` inside property
+ * names (no JSON Pointer RFC 6901 `~1` encoding), so a schema with BOTH a
+ * slash-named property `"a/b"` AND a nested path `a.b` produced the same
  * `instancePath: "/a/b"` for either failure — the two cases are
- * indistinguishable from the data path alone. `schemaPath` carries explicit
+ * indistinguishable from the data path alone. TypeBox 1.3+ escapes both paths
+ * (`/a~1b`, `#/properties/a~1b`); the walker accepts either form. `schemaPath` carries explicit
  * `/properties/` markers per nesting level, so the two cases become
  * structurally distinct:
  *
@@ -86,13 +99,17 @@ function walkSegments(node, segments, i, lastField) {
         return walkSegments(obj.items, segments, i + 1, lastField);
     }
     // `properties` command: subsequent segments form the property name (joined
-    // by `/` to recover slash-named keys). Consume by greedy longest-prefix
-    // match against the parent's actual `properties` keys, then descend.
+    // by `/` to recover unescaped slash-named keys from TypeBox < 1.3). Consume
+    // by greedy longest-prefix match against the parent's actual `properties`
+    // keys, then descend. The raw candidate wins; the RFC 6901-decoded form
+    // covers TypeBox 1.3+, which emits `a~1b` as a single segment.
     if (head === "properties" && obj.properties && typeof obj.properties === "object") {
         const props = obj.properties;
         for (let j = segments.length; j > i + 1; j--) {
-            const candidate = segments.slice(i + 1, j).join("/");
-            if (Object.hasOwn(props, candidate)) {
+            const raw = segments.slice(i + 1, j).join("/");
+            for (const candidate of new Set([raw, decodePointerSegment(raw)])) {
+                if (!Object.hasOwn(props, candidate))
+                    continue;
                 const child = walkSegments(props[candidate], segments, j, candidate);
                 if (child !== undefined)
                     return child;
@@ -150,12 +167,15 @@ function resolveSchemaAtPath(schema, instancePath) {
         if (!current || typeof current !== "object")
             return undefined;
         const obj = current;
-        if (obj.properties && typeof obj.properties === "object" && segment in obj.properties) {
-            const next = obj.properties[segment];
-            if (next === undefined)
-                return undefined;
-            current = next;
-            continue;
+        if (obj.properties && typeof obj.properties === "object") {
+            const key = segment in obj.properties ? segment : decodePointerSegment(segment);
+            if (key in obj.properties) {
+                const next = obj.properties[key];
+                if (next === undefined)
+                    return undefined;
+                current = next;
+                continue;
+            }
         }
         if (obj.items !== undefined && /^\d+$/.test(segment)) {
             if (Array.isArray(obj.items)) {
@@ -356,7 +376,8 @@ function suppressSiblingErrorsUnderUnion(schema, value, errors) {
             const remainder = error.instancePath.slice(prefix.length);
             if (remainder.includes("/"))
                 continue; // only direct discriminator props
-            const losingValues = resolution.losingDiscriminators.get(remainder);
+            const losingValues = resolution.losingDiscriminators.get(remainder) ??
+                resolution.losingDiscriminators.get(decodePointerSegment(remainder));
             if (!losingValues)
                 continue;
             if (error.keyword === "const" && losingValues.has(error.params.allowedValue))
@@ -369,6 +390,21 @@ function suppressSiblingErrorsUnderUnion(schema, value, errors) {
         return true;
     });
 }
+/**
+ * TypeBox 1.3+ reports each additional property twice: once as the
+ * `additionalProperties` summary at the object (which `expandTypeBoxError`
+ * expands per key) and once per key as the failure of the `additionalProperties`
+ * sub-schema itself (`keyword: "boolean"` for `false`, or e.g. `"type"` for a
+ * schema value), with `schemaPath` ending at that keyword. TypeBox 1.1 emitted
+ * only the summary. Dropping the per-key duplicates keeps one error per key and
+ * lets union phantom suppression, which reasons about the summary, stay
+ * authoritative. A trailing segment after a `properties` command is a property
+ * literally named `additionalProperties`, not the keyword.
+ */
+function isAdditionalPropertiesSubschemaError(error) {
+    const segments = error.schemaPath.split("/");
+    return segments.at(-1) === "additionalProperties" && segments.at(-2) !== "properties";
+}
 function expandTypeBoxError(schema, error) {
     // Read offending property names from TypeBox's structured `params` rather
     // than parsing the message string. Two payoffs: locale independence (the
@@ -427,9 +463,7 @@ export function validatePortableToolArgs(tool, args) {
     // satisfy ONE branch, not all of them). Then dedupe the survivors by
     // (field, message) using JSON.stringify so the key can't collide regardless
     // of what characters field or message contain.
-    const rawErrors = suppressSiblingErrorsUnderUnion(tool.parameters, args, [
-        ...Errors(tool.parameters, args),
-    ]);
+    const rawErrors = suppressSiblingErrorsUnderUnion(tool.parameters, args, [...Errors(tool.parameters, args)].filter((error) => !isAdditionalPropertiesSubschemaError(error)));
     const seen = new Set();
     const errors = rawErrors
         .flatMap((error) => expandTypeBoxError(tool.parameters, error))
@@ -443,6 +477,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 +492,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/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,6 +270,10 @@ 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.
 
 ---

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,9 +87,19 @@ 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 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "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.15",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/node": "^25.9.1",
     "typescript": "^6.0.3"