@feniix/bridgekit 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -6,6 +6,54 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-10-06
+
+### Added
+
+- The MCP adapter forwards `ctx.progress?.(update)` as `notifications/progress` when the
+  `tools/call` request carries `_meta.progressToken`. `progress` is a per-call counter
+  starting at 1, `message` is `update.text`, `total` is omitted. Notifications are flushed
+  before the result and skipped once the request is cancelled; a failed send never fails
+  the call. Without a token `ctx.progress` stays `undefined`, matching previous behaviour.
+- `outputSchema` accepts any JSON Schema root except a top-level `$ref`: arrays, primitives,
+  `null` and unions join objects and object intersections. The MCP SDK projects non-object
+  values for legacy-era clients (`{ result: value }` on both `tools/list` and `tools/call`)
+  while modern `2026-07-28` clients receive the natural value. Pi forwards the raw value on
+  `structuredContent` and wraps non-object values as `details.result`. `definePortableTool`
+  checks array and primitive roots at compile time without the open-record intersection.
+
+### Changed
+
+- `PortableToolResult<TStructured>` drops the `Record<string, unknown>` constraint on its
+  generic (the default is unchanged), and bare `PortableTool` now defaults its result generic
+  to `PortableToolResult<unknown>` so adapter tool lists accept non-object outputs. A tool
+  annotated as bare `PortableTool` / `PortableTool<TSchema>` therefore yields
+  `structuredContent: unknown` from `executePortableTool` where it was `Record<string, unknown>`;
+  keep the inferred type from `definePortableTool` or annotate the result generic explicitly.
+  `PortableToolContext.progress`, the result guards and `PortableToolExecutionError` accept
+  `PortableToolResult<unknown>`. Custom adapters that declared `progress` with the narrower
+  object-only parameter need to widen it. Both adapters now test `structuredContent !== undefined`
+  instead of `??`, so a `null` structured value no longer falls back to `details`.
+- `BRIDGEKIT_MCP_NON_OBJECT_OUTPUT_SCHEMA` is gone; only `BRIDGEKIT_MCP_REF_OUTPUT_SCHEMA`
+  (and `BRIDGEKIT_REF_OUTPUT_SCHEMA` at the portable seam) remain.
+
+- Development, CI, and release installs use pnpm instead of npm. `package.json#packageManager`
+  pins `pnpm@12.9.1`, `pnpm-lock.yaml` replaces `package-lock.json`, and CI installs with
+  `pnpm install --frozen-lockfile`. The production audit gate is now
+  `pnpm audit --prod --audit-level high`. Publishing still uses
+  `npm publish --access public --provenance` for OIDC trusted publishing.
+  The lockfile resolves `typebox` to 1.3.35 rather than 1.3.36, because pnpm's default
+  `minimumReleaseAge` skips same-day releases; both satisfy `^1.1.31`.
+- The package smoke test packs with `pnpm pack` and installs the tarball into a strict pnpm
+  consumer, which now declares `@modelcontextprotocol/server` explicitly for the `Server` type.
+  A new invariant fails when `packageManager` is unpinned or an npm/yarn lockfile reappears.
+- CI and all release jobs run on Node 22 only, matching pi's workflows: the `22.19`/`24`
+  CI matrix is gone and the release no longer uses Node 24. The publish job upgrades to
+  `npm@11.16.0` (as pi does) because Node 22's bundled npm 10.x cannot do trusted publishing.
+  The `engines.node` floor stays `>=22.19.0`.
+- No runtime change: `runBinWrapper` still builds missing output with `npm run <buildScript>`,
+  since downstream consumers own their package manager.
+
 ## [0.17.0] - 2026-10-06
 
 ### Changed

package/README.md

@@ -111,8 +111,8 @@ Do not deep-import from `dist/` or `src/` in consuming packages.
 
 #### Declared structured output
 
-Add an optional object-shaped `outputSchema` to a portable tool to describe its
-successful `structuredContent` for both Pi and MCP:
+Add an optional `outputSchema` to a portable tool to describe its successful
+`structuredContent` for both Pi and MCP:
 
 ```ts
 const echoTool = definePortableTool({
@@ -125,9 +125,13 @@ const echoTool = definePortableTool({
 });
 ```
 
-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
+Any JSON Schema root is accepted except a top-level `$ref` (`Type.Ref` /
+`Type.Cyclic`): objects, intersections of objects, arrays, primitives, `null` and
+unions all work. Success calls must return matching `structuredContent`; legacy
+`details` alone does not satisfy the schema. Non-object values reach modern MCP
+clients as-is; for legacy-era clients the MCP SDK wraps both the listed schema and
+the value as `{ result: ... }`. Pi receives the raw value on `structuredContent`
+and `{ result: value }` on renderer-facing `details`. 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.
@@ -298,6 +302,8 @@ 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.
 
+When a client sends `_meta.progressToken` on `tools/call`, each `ctx.progress?.(update)` becomes a `notifications/progress` notification: `progress` is a per-call counter starting at 1 (the spec requires it to increase), `message` is `update.text`, and `total` is omitted. Without a token `ctx.progress` is `undefined`, so tools should keep calling it optionally. Notifications are flushed before the result and skipped once the request is cancelled. Caveat: the official SDK clients defer notification handlers while handling responses synchronously, so a burst of progress calls issued synchronously right before returning can be dropped by the client when it arrives in the same stdio chunk as the result. BridgeKit writes them in order regardless; tools that emit progress over time are unaffected.
+
 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`.
@@ -344,7 +350,7 @@ Options:
 
 - `metaUrl` (required): `import.meta.url` of the bin script. Used to locate the package root (the bin's parent directory).
 - `mcpEntry` (required): path to the compiled MCP entry, relative to the package root (e.g. `"dist/extensions/mcp-server.js"`). Absolute paths, `..` path segments, and NUL bytes are rejected.
-- `buildScript` (required): npm script to invoke when the entry is missing (e.g. `"build:mcp"`). Names must be literal script identifiers containing only letters, numbers, `:`, `_`, `@`, `.`, or `-`, and must not start with `-`.
+- `buildScript` (required): npm script to invoke when the entry is missing (e.g. `"build:mcp"`). The wrapper runs it with `npm run <buildScript> --silent` regardless of which package manager installed your package. Names must be literal script identifiers containing only letters, numbers, `:`, `_`, `@`, `.`, or `-`, and must not start with `-`.
 - `buildTimeoutMs` (optional, default `60_000`): timeout for the build subprocess. Distinct "Build timed out…" diagnostic fires when exceeded.
 - `logPrefix` (optional, default `"bridgekit-bin"`): prefix on the "Failed to build…" diagnostic.
 - `buildStdio` (optional, default `"inherit"`): `stdio` mode passed to `spawnSync` when the build script runs. **MCP stdio server bins should pass `["ignore", "inherit", "inherit"]`** so the build subprocess's stdout cannot contaminate the parent's JSON-RPC framing channel (`process.stdout`). stderr stays inherited so build diagnostics remain visible.
@@ -389,7 +395,7 @@ Package and release checklist:
 - If an npm-launched bin depends on generated output, use `runBinWrapper` from `@feniix/bridgekit/bin-wrapper` (since 0.11.0) — it resolves the package-local generated entry, runs the package-local build when output is missing in workspace/local execution, preserves build failures, and distinguishes timeout from build error in its diagnostic. The bin script becomes a three-line invocation; no hand-rolled wrapper needed.
 - If a package keeps a source-loaded host entrypoint (for example a pi extension source file), use a package-local MCP build behind that wrapper and narrow the build to the MCP entrypoint plus shared host-neutral modules.
 - Declare a compatible Node engine (`>=22.19.0`) in downstream packages that expose BridgeKit-powered MCP bins.
-- Run `npm run check`, `npm test`, `npm run pack:dry-run`, `npm run package-smoke`, and `npm audit --omit=dev --audit-level=high` before publishing.
+- BridgeKit itself is developed with pnpm (pinned via `packageManager`): run `pnpm run check`, `pnpm test`, `pnpm run pack:dry-run`, `pnpm run package-smoke`, and `pnpm audit --prod --audit-level high` before publishing.
 - Treat `docs/releasing.md` as the release handoff; publishing is manual via the Release workflow and npm trusted publishing.
 
 See `examples/README.md` for complete copyable examples.

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

@@ -1,6 +1,6 @@
 import { Server } from "@modelcontextprotocol/server";
 import type { TSchema } from "typebox";
-import type { PortableTool } from "../core/define-tool.js";
+import type { PortableTool, PortableToolResult } from "../core/define-tool.js";
 export interface CreateMcpServerOptions {
     name: string;
     version: string;
@@ -17,7 +17,7 @@ export interface CreateMcpServerOptions {
      * reference, not deep-cloned — treat `tool.parameters` and `tool.outputSchema` as immutable once
      * `createMcpServer` returns.
      */
-    tools: readonly PortableTool<TSchema>[];
+    tools: readonly PortableTool<TSchema, PortableToolResult<unknown>>[];
     instructions?: string;
 }
 export declare function createMcpServer(options: CreateMcpServerOptions): Server;

package/dist/src/adapters/mcp.js

@@ -3,9 +3,10 @@ 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) {
+    // `!== undefined` rather than `??`: `null` is a legal structured value.
     return {
         content: [{ type: "text", text: result.text }],
-        structuredContent: result.structuredContent ?? result.details,
+        structuredContent: result.structuredContent !== undefined ? result.structuredContent : result.details,
         isError: result.isError ?? false,
     };
 }
@@ -27,6 +28,22 @@ function toMcpObjectSchema(schema) {
     }
     return { type: "object", ...schema };
 }
+/**
+ * Render an output schema for `tools/list` and for `projectCallToolResult`.
+ * All-object `allOf` intersections still get `type: "object"` synthesized:
+ * the SDK's legacy-era `{ result: ... }` wrap keys purely on the advertised
+ * root `type`, so an unlowered intersection would silently change the wire
+ * shape existing `Type.Intersect` outputs have today. Every other root
+ * (array, primitive, union) passes through by reference and the SDK projects
+ * it per era. The same object must feed both the listing and the projection.
+ */
+function toMcpOutputSchema(schema) {
+    const candidate = schema;
+    if (candidate.type === undefined && isObjectSchema(schema)) {
+        return { type: "object", ...candidate };
+    }
+    return candidate;
+}
 /**
  * Stable `error.code` values attached to `createMcpServer` construction
  * failures so consumers have a non-string anchor (the message text is
@@ -89,8 +106,12 @@ export function createMcpServer(options) {
     // Build the dispatch map and the listing payload at construction so
     // `tools/list` returns a pre-computed array and post-construction mutations
     // to the caller's array cannot leak unvalidated schemas onto the wire.
-    const byName = new Map(options.tools.map((tool) => [tool.name, tool]));
-    const mcpTools = options.tools.map((tool) => {
+    const entries = options.tools.map((tool) => ({
+        tool,
+        outputSchema: tool.outputSchema !== undefined ? toMcpOutputSchema(tool.outputSchema) : undefined,
+    }));
+    const byName = new Map(entries.map((entry) => [entry.tool.name, entry]));
+    const mcpTools = entries.map(({ tool, outputSchema }) => {
         const annotations = tool.hostExtras?.mcp?.annotations;
         // MCP advisory hints from `hostExtras.mcp.annotations`. Two gates:
         //   1. `annotations !== undefined` — a tool without hostExtras builds a
@@ -111,7 +132,7 @@ export function createMcpServer(options) {
             title: tool.title,
             description: tool.description,
             inputSchema: toMcpObjectSchema(tool.parameters),
-            ...(tool.outputSchema !== undefined && { outputSchema: toMcpObjectSchema(tool.outputSchema) }),
+            ...(outputSchema !== undefined && { outputSchema }),
             ...(hasAnnotations ? { annotations: { ...annotations } } : {}),
         };
     });
@@ -121,21 +142,47 @@ export function createMcpServer(options) {
     });
     server.setRequestHandler("tools/list", async () => ({ tools: mcpTools }));
     server.setRequestHandler("tools/call", async (request, ctx) => {
-        const tool = byName.get(request.params.name);
-        if (!tool) {
+        const entry = byName.get(request.params.name);
+        if (!entry) {
             return {
                 content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
                 isError: true,
             };
         }
+        // `ctx.progress` is only wired when the client asked for progress by
+        // sending `_meta.progressToken`; otherwise the context is byte-identical
+        // to the pre-progress shape. `progress` is a monotonic per-call counter
+        // (the spec requires it to increase) and `message` is the update text.
+        // Sends are skipped once the request is cancelled and awaited before the
+        // result goes out, so a client never sees a notification for a token it
+        // has already released. A failed send never fails the tool call.
+        const progressToken = ctx.mcpReq._meta?.progressToken;
+        const pendingNotifications = [];
+        let progressCount = 0;
+        const progress = progressToken === undefined
+            ? undefined
+            : (update) => {
+                if (ctx.mcpReq.signal.aborted)
+                    return;
+                progressCount += 1;
+                pendingNotifications.push(ctx.mcpReq
+                    .notify({
+                    method: "notifications/progress",
+                    params: { progressToken, progress: progressCount, message: update.text },
+                })
+                    .catch(() => undefined));
+            };
         try {
-            const result = await executePortableTool(tool, request.params.arguments ?? {}, {
+            const result = await executePortableTool(entry.tool, request.params.arguments ?? {}, {
                 host: "mcp",
                 signal: ctx.mcpReq.signal,
+                ...(progress !== undefined && { progress }),
             });
-            return server.projectCallToolResult(toMcpResult(result), tool.outputSchema !== undefined ? toMcpObjectSchema(tool.outputSchema) : undefined);
+            await Promise.all(pendingNotifications);
+            return server.projectCallToolResult(toMcpResult(result), entry.outputSchema);
         }
         catch (error) {
+            await Promise.all(pendingNotifications);
             const message = error instanceof Error ? error.message : String(error);
             return {
                 content: [{ type: "text", text: message }],

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

@@ -11,7 +11,7 @@ type PiToolUpdate = {
 type PiToolResult = {
     content: PiContent[];
     details: Record<string, unknown>;
-    structuredContent?: Record<string, unknown>;
+    structuredContent?: unknown;
     isError?: boolean;
 };
 type PiToolDefinition = {
@@ -55,7 +55,7 @@ export interface RegisterPiToolsOptions {
 }
 export declare class PortableToolExecutionError extends Error {
     readonly details: PortableToolErrorDetails;
-    constructor(result: PortableToolResult);
+    constructor(result: PortableToolResult<unknown>);
 }
 export declare function isPortableToolExecutionError(error: unknown): error is PortableToolExecutionError;
 /**
@@ -75,5 +75,5 @@ export declare function isPortableToolExecutionError(error: unknown): error is P
  * // Deprecated, but available through 0.x.
  * registerPiTools(pi, tools, { errorHandling: "throw" });
  */
-export declare function registerPiTools(pi: PiToolRegistration, tools: readonly PortableTool<TSchema>[], options?: RegisterPiToolsOptions): void;
+export declare function registerPiTools(pi: PiToolRegistration, tools: readonly PortableTool<TSchema, PortableToolResult<unknown>>[], options?: RegisterPiToolsOptions): void;
 export {};

package/dist/src/adapters/pi.js

@@ -1,8 +1,19 @@
 import { executePortableTool } from "../core/execute-tool.js";
 import { assertPortableOutputSchema } from "../core/output-schema.js";
 import { isValidationFailure } from "../core/result-guards.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Renderer-facing `details` is always an object. Non-object structured
+ * content (array, primitive, `null`) is wrapped as `{ result: value }`,
+ * mirroring the MCP SDK's legacy-era projection of the same values.
+ */
 function toPiDetails(result) {
-    return result.structuredContent ?? result.details ?? {};
+    if (result.structuredContent !== undefined) {
+        return isRecord(result.structuredContent) ? result.structuredContent : { result: result.structuredContent };
+    }
+    return result.details ?? {};
 }
 function toPortableToolErrorDetails(result) {
     if (isValidationFailure(result)) {

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

@@ -1,8 +1,15 @@
 import type { Static, TSchema } from "typebox";
-export interface PortableToolResult<TStructured extends Record<string, unknown> = Record<string, unknown>> {
+export interface PortableToolResult<TStructured = Record<string, unknown>> {
     /** Plain text sent back to the model in every host. */
     text: string;
-    /** Structured data for hosts that support it. Preferred by both pi and MCP adapters. */
+    /**
+     * Structured data for hosts that support it. Preferred by both pi and MCP
+     * adapters. Any JSON value is accepted (object, array, primitive, `null`);
+     * the default type parameter keeps the common object case ergonomic.
+     * Non-object values reach MCP `structuredContent` directly on the modern
+     * era, are wrapped as `{ result: value }` by the SDK for legacy clients,
+     * and are wrapped the same way in pi's renderer-facing `details`.
+     */
     structuredContent?: TStructured;
     /**
      * Legacy/adapter debug details used only when `structuredContent` is absent.
@@ -40,7 +47,12 @@ export type PortableToolBuiltInHost = "pi" | "mcp" | "test";
 export interface PortableToolContext {
     host: PortableToolBuiltInHost;
     signal?: AbortSignal;
-    progress?: (update: PortableToolResult) => void;
+    /**
+     * Host progress channel. Pi maps each update to `onUpdate`; MCP maps it to
+     * `notifications/progress` when the request carried a `progressToken`
+     * (`progress` is a monotonic per-call counter and `message` is `update.text`).
+     */
+    progress?: (update: PortableToolResult<unknown>) => void;
 }
 /**
  * Optional TUI renderer for the tool call line (before execution).
@@ -153,23 +165,31 @@ export interface PortableToolHostExtras {
     pi?: PiHostExtras;
     mcp?: McpHostExtras;
 }
+/**
+ * Object-rooted outputs keep the open-record intersection so handlers may
+ * return extra keys beyond the schema; array and primitive roots are used as-is
+ * (neither is assignable to `Record<string, unknown>`).
+ */
+type SchemaOutput<T> = [T] extends [readonly unknown[]] ? T : [T] extends [object] ? T & Record<string, unknown> : T;
 /** 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>;
+type SchemaResult<TOutput extends TSchema> = (PortableToolResult<unknown> & {
+    structuredContent: SchemaOutput<Exclude<Static<TOutput>, undefined>>;
     isError?: false;
-}) | (PortableToolResult & {
+}) | (PortableToolResult<unknown> & {
     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> {
+type CheckedResult<TResult extends PortableToolResult<unknown>, TOutput extends TSchema | undefined> = [
+    TOutput
+] extends [TSchema] ? TResult & SchemaResult<NoInfer<Extract<TOutput, TSchema>>> : TResult;
+export interface PortableTool<TParams extends TSchema = TSchema, TResult extends PortableToolResult<unknown> = PortableToolResult<unknown>, TOutput extends TSchema | undefined = TSchema | undefined> {
     name: string;
     title: string;
     description: string;
     parameters: TParams;
     /**
-     * Object-shaped TypeBox schema for successful structuredContent.
+     * TypeBox schema for successful structuredContent. Any JSON Schema root is
+     * accepted except a top-level `$ref` (`Type.Ref` / `Type.Cyclic`); objects,
+     * object intersections, arrays, primitives and unions are all valid.
      * Literal isError:true results are exempt. Treat this schema and parameters
      * as immutable after registration, including replacing either schema object.
      */
@@ -190,14 +210,14 @@ export declare function definePortableTool<TParams extends TSchema, TOutput exte
     outputSchema: TOutput;
     execute: TExecute;
 }): PortableTool<TParams, Awaited<ReturnType<TExecute>>, TOutput>;
-export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult>(tool: PortableTool<TParams, TResult> & {
+export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult<unknown>>(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 {
+export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult<unknown>, 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.d.ts

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

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

@@ -1,7 +1,14 @@
-import type { PortableTool } from "./define-tool.js";
+import type { TSchema } from "typebox";
+import type { PortableTool, PortableToolResult } 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;
+/**
+ * Output schemas may use any JSON Schema root (object, array, primitive,
+ * union); the MCP SDK projects non-object roots for legacy clients. Only a
+ * top-level `$ref` is rejected: `tools/list` ships schemas by value and clients
+ * do not resolve references.
+ */
+export declare function assertPortableOutputSchema(tool: PortableTool<TSchema, PortableToolResult<unknown>>, context?: string, codePrefix?: string): void;

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

@@ -38,16 +38,16 @@ export function throwWithCode(message, code, ErrorType = Error) {
     error.code = code;
     throw error;
 }
+/**
+ * Output schemas may use any JSON Schema root (object, array, primitive,
+ * union); the MCP SDK projects non-object roots for legacy clients. Only a
+ * top-level `$ref` is rejected: `tools/list` ships schemas by value and clients
+ * do not resolve references.
+ */
 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);
+    const schema = tool.outputSchema;
+    if (schema !== undefined && typeof schema.$ref === "string") {
+        throwWithCode(`${context ? `${context}: ` : ""}Invalid outputSchema for ${tool.name} (type="$ref"): ` +
+            "Top-level $ref / Type.Cyclic is unsupported; inline the referenced shape or split recursive shapes.", `${codePrefix}_REF_OUTPUT_SCHEMA`, TypeError);
     }
 }

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

@@ -26,10 +26,10 @@ export type PortableValidationFailure = PortableToolResult & {
  * (The pi adapter's `PortableToolExecutionError.details` does synthesize that
  * discriminator for the deprecated `errorHandling: "throw"` path.)
  */
-export type PortableDomainFailure = PortableToolResult & {
+export type PortableDomainFailure = PortableToolResult<unknown> & {
     isError: true;
 };
-export declare function isValidationFailure(result: PortableToolResult): result is PortableValidationFailure;
+export declare function isValidationFailure(result: PortableToolResult<unknown>): result is PortableValidationFailure;
 /**
  * Type guard for handler-emitted `isError: true` results that are not
  * validation failures. Use after `result.isError` to branch between
@@ -41,4 +41,4 @@ export declare function isValidationFailure(result: PortableToolResult): result
  *   metrics.increment("tool.domain_error", { tool: tool.name });
  * }
  */
-export declare function isDomainFailure(result: PortableToolResult): result is PortableDomainFailure;
+export declare function isDomainFailure(result: PortableToolResult<unknown>): result is PortableDomainFailure;

package/examples/README.md

@@ -270,8 +270,11 @@ 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.
+- Optional `outputSchema` (any root except top-level `$ref`) is listed for successful
+  structured results; matching `structuredContent` is required and validated. Error
+  results are exempt. Non-object values are wrapped as `{ result }` for legacy clients.
+- `ctx.progress?.(...)` becomes `notifications/progress` when the client sent a
+  `progressToken`; otherwise `ctx.progress` is `undefined`.
 - 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.
@@ -418,5 +421,5 @@ For publishable tool packages:
 - When a bin depends on generated output, prefer a checked-in wrapper under `bin/` over pointing directly at `dist/`; for MCP stdio bins set `buildStdio: ["ignore", "inherit", "inherit"]`; test existing output, missing output, failed builds, and successful builds that omit the expected file.
 - If only the MCP bin needs compiled output, narrow its tsconfig to the MCP entrypoint and shared host-neutral modules instead of compiling unrelated host adapters.
 - Add a packed-install smoke test that installs tarballs into a temporary project.
-- For BridgeKit itself, run `npm run check`, `npm run test`, `npm run pack:dry-run`, `npm run package-smoke`, and `npm audit --omit=dev --audit-level=high` before release.
+- For BridgeKit itself (a pnpm project), run `pnpm run check`, `pnpm test`, `pnpm run pack:dry-run`, `pnpm run package-smoke`, and `pnpm audit --prod --audit-level high` before release.
 - Keep imports side-effect free; registration and server startup should happen only in explicit entrypoints.

package/llms.txt

@@ -59,9 +59,11 @@ 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.
+- Optional `outputSchema` declares successful structured data for both hosts: any
+  TypeBox schema except a top-level `$ref` (objects, intersections, arrays,
+  primitives, unions). Missing/invalid successful `structuredContent` throws
+  `TypeError`; argument/domain error results are exempt. Non-object values are
+  wrapped as `{ result }` for legacy MCP clients by the SDK and on pi `details`.
   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
@@ -75,6 +77,8 @@ export function createTools() {
 - Throw only for unexpected programmer, adapter, or runtime failures.
 - Respect `ctx.signal` in long-running tools.
 - Use `ctx.progress?.(...)` for incremental progress updates when the host supports them.
+  Pi maps them to `onUpdate`; MCP emits `notifications/progress` (counter + `update.text`)
+  only when the client sent `_meta.progressToken`, otherwise `ctx.progress` is `undefined`.
 - Wire hosts explicitly: pi registration and MCP server startup are separate adapter calls.
 - Keep modules import-passive. Do not register tools, start servers, read package metadata, read env vars, or touch files at import time.
 - For stateful tools, export a `createTools()` factory instead of a module-level `tools` singleton so each pi extension instance or MCP stdio process gets isolated state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -46,15 +46,15 @@
   "scripts": {
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "check": "npm run lint && npm run typecheck",
+    "check": "pnpm run lint && pnpm run typecheck",
     "clean": "node scripts/clean-package-dist.mjs",
     "typecheck": "tsc -b tsconfig.json --pretty false",
-    "build": "npm run clean && tsc -b tsconfig.json",
-    "test": "npm run build && node scripts/run-built-tests.mjs",
-    "test:coverage": "npm run build && node scripts/run-built-tests-coverage.mjs",
-    "pack:dry-run": "npm pack --dry-run --json",
+    "build": "pnpm run clean && tsc -b tsconfig.json",
+    "test": "pnpm run build && node scripts/run-built-tests.mjs",
+    "test:coverage": "pnpm run build && node scripts/run-built-tests-coverage.mjs",
+    "pack:dry-run": "pnpm pack --dry-run --json",
     "package-smoke": "node scripts/smoke-package.mjs",
-    "prepack": "npm run build"
+    "prepack": "pnpm run build"
   },
   "files": [
     "dist/**/*.js",
@@ -80,5 +80,6 @@
     "@types/node": "^22.20.5",
     "typescript": "^6.0.3"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "packageManager": "pnpm@12.9.1"
 }