@feniix/bridgekit 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to `@feniix/bridgekit` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - Unreleased
+
+### Removed (breaking)
+
+- `PortableToolHost<TExtension extends string>` type alias — replaced by the
+  fixed `PortableToolBuiltInHost = "pi" | "mcp" | "test"` union.
+- `<THost extends string>` generic parameter on `PortableTool`,
+  `PortableToolContext`, `definePortableTool`, `executePortableTool`, and
+  `validatePortableToolArgs`. Host is now a fixed literal union; adapters
+  outside `"pi" | "mcp"` should cast at their adapter boundary instead of
+  extending the type union.
+
+  Migration: drop the second generic argument from any of those types.
+  `PortableTool<typeof params, "custom">` becomes `PortableTool<typeof params>`.
+  `PortableToolContext<"custom">` becomes `PortableToolContext` (cast `host`
+  at the consumer if a custom literal is needed).
+
+  Cast pattern (custom literal at the adapter boundary):
+
+  ```ts
+  // PortableToolContext.host is fixed to PortableToolBuiltInHost.
+  // A direct `as "custom-runtime"` fails under strict (TS2352 — no overlap);
+  // cast through `unknown` instead.
+  const ctx: PortableToolContext = {
+    host: "custom-runtime" as unknown as PortableToolBuiltInHost,
+  };
+  ```
+
+  Caveat: the cast lies at the type-system boundary, so
+  `switch (ctx.host) { ... default: assertNever(ctx.host); }` patterns will
+  fall through on the custom literal at runtime. For custom dispatch, carry
+  the host identifier on an adapter-owned field rather than on `ctx.host`,
+  or do a runtime allowlist check before exhaustive narrowing.
+
+  No consumer in tree or in the three known downstream consumers
+  (pi-sequential-thinking, pi-exa, pi-code-reasoning) used the generic.
+  Resolves [#5](https://github.com/feniix/bridgekit/issues/5).
+
+## [0.9.5] - 2026-05-27
+
+### Documentation
+
+- README restructured to quickstart-first ordering: a copy-pasteable
+  three-file working example (`tools.ts`, `mcp-server.ts`,
+  `pi-extension.ts`) now lands above the fold; runtime requirements,
+  the import map, best practices, packaging, and the coding-agent
+  section all move below. Content preserved; no new entrypoints, no
+  API changes, no behavioral effects. Resolves
+  [#19](https://github.com/feniix/bridgekit/issues/19).
+- `docs/packaging-invariants.md` adds a cross-reference under
+  `inv-mcp-sdk-major` pointing at `toInputSchema`'s JSDoc in
+  `src/adapters/mcp.ts` as the canonical record of the SDK-v1
+  `inputSchema.type` Zod-validation quirk that the `allOf` →
+  `type: "object"` synthesis addresses. Resolves
+  [#45](https://github.com/feniix/bridgekit/issues/45).
+
 ## [0.9.4] - 2026-05-27
 
 ### Fixed

package/README.md

@@ -2,20 +2,74 @@
 
 BridgeKit provides reusable TypeBox-backed tool definitions and adapters for exposing one tool implementation through pi, MCP, and other hosts.
 
-## Runtime support
+## Quickstart
 
-This package is ESM-only and supports Node.js 22.19.0 or newer. Published modules are import-passive and marked as side-effect free; tools are registered or servers are started only when the exported adapter functions are called.
+```ts
+// src/tools.ts
+import { Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
 
-## For coding agents
+export const echoTool = definePortableTool({
+  name: "echo",
+  title: "Echo",
+  description: "Echo text back to the caller.",
+  parameters: Type.Object({ text: Type.String() }),
+  execute(args, ctx) {
+    return {
+      text: args.text,
+      structuredContent: { text: args.text, host: ctx.host },
+    };
+  },
+  hostExtras: {
+    pi: { pendingMessage: "Echoing..." },
+    mcp: { annotations: { readOnlyHint: true } },
+  },
+});
 
-Read these files in order:
+export function createTools() {
+  return [echoTool];
+}
+```
 
-1. `README.md` — public API, contracts, and best practices.
-2. `llms.txt` — compact agent-facing usage rules and anti-patterns.
-3. `examples/README.md` — copyable layouts for shared tools, pi extensions, MCP stdio servers, and custom hosts.
-4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, and `dist/src/mcp.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain the same implementation context.
+```ts
+// src/mcp-server.ts
+import { runMcpStdioServer } from "@feniix/bridgekit/mcp";
+import { createTools } from "./tools.js";
+
+await runMcpStdioServer({
+  name: "my-tools",
+  version: "0.1.0",
+  tools: createTools(),
+});
+```
+
+```ts
+// src/pi-extension.ts
+import { registerPiTools } from "@feniix/bridgekit/pi";
+import { createTools } from "./tools.js";
 
-## Entrypoints
+export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
+  registerPiTools(pi, createTools());
+}
+```
+
+## Install
+
+```bash
+npm install @feniix/bridgekit typebox
+```
+
+This package is ESM-only and supports Node.js 22.19.0 or newer. Published modules are import-passive and marked as side-effect free; tools are registered or servers are started only when the exported adapter functions are called.
+
+## Why
+
+- Define a tool once; ship it to pi and MCP without per-host forks.
+- Host-neutral tool files: no pi or MCP SDK imports in the tool definition itself.
+- TypeBox schemas pass through to MCP `inputSchema` directly — no JSON Schema conversion step.
+- Import-passive, `sideEffects: false`, three-entrypoint split (`.`, `./pi`, `./mcp`) so pi-only consumers do not pull the MCP SDK and vice versa.
+- Conformance-tested public surface: a packed-install smoke test enforces the runtime export set, deep-import rejection, and type-level strictness against the installed declarations.
+
+## API reference
 
 ```ts
 import {
@@ -26,7 +80,6 @@ import {
   type PortableTool,
   type PortableToolBuiltInHost,
   type PortableToolContext,
-  type PortableToolHost,
   type PortableToolResult,
   type PortableValidationError,
 } from "@feniix/bridgekit";
@@ -40,46 +93,7 @@ import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
 
 Do not deep-import from `dist/` or `src/` in consuming packages.
 
-## Core tools
-
-Define tools once in host-neutral files:
-
-```ts
-import { Type } from "typebox";
-import { definePortableTool } from "@feniix/bridgekit";
-
-export const echoTool = definePortableTool({
-  name: "echo",
-  title: "Echo",
-  description: "Echo text.",
-  parameters: Type.Object({ text: Type.String() }),
-  execute(args, ctx) {
-    return {
-      text: args.text,
-      structuredContent: { text: args.text, host: ctx.host },
-    };
-  },
-});
-
-export function createTools() {
-  return [echoTool];
-}
-```
-
-Tool definition best practices:
-
-- Keep tool files host-neutral: no pi imports, no MCP SDK imports.
-- Use TypeBox `Type.Object(...)` schemas so MCP can expose input schemas directly.
-- Return `text` for model-visible output and `structuredContent` for machine-readable data.
-- Use `isError: true` for expected/domain failures that should be represented as tool output.
-- Throw only for unexpected programmer, adapter, or runtime failures.
-- Respect `ctx.signal` in long-running tools.
-- Use `ctx.progress?.(...)` for incremental updates.
-- Keep modules import-passive; do not register tools or start servers at import time.
-- For stateful tools, export a `createTools()` factory instead of a module-level singleton so each host runtime gets isolated state.
-- TypeBox validation happens before `execute`; use a permissive schema plus domain validation if you need custom guidance for structurally invalid input.
-
-## pi adapter
+### pi adapter
 
 ```ts
 import { registerPiTools } from "@feniix/bridgekit/pi";
@@ -141,7 +155,7 @@ new default `"return"` mode, prefer the result guards over inspecting a
 `"domain"`). The guards operate on a `PortableToolResult`; they are not
 designed to be called on the pi adapter's wire object.
 
-### Per-host metadata via `hostExtras`
+#### 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.
 
@@ -174,7 +188,7 @@ export const generateSummaryTool = definePortableTool({
 
 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
+### MCP adapter
 
 ```ts
 import { realpathSync } from "node:fs";
@@ -217,42 +231,24 @@ Portable validation failures and portable `isError: true` results return `CallTo
 
 The two adapters now read in parallel: invalid args and portable `isError` results return `{ isError: true }` from both hosts by default, and the same result-guard helpers (`isValidationFailure`, `isDomainFailure`) narrow them on either side.
 
-## Custom host typing
-
-Default portable tools accept the built-in host union:
-
-```ts
-type BuiltIn = "pi" | "mcp" | "test";
-```
-
-Custom adapters opt in explicitly:
-
-```ts
-import { Type } from "typebox";
-import { definePortableTool, type PortableToolHost } from "@feniix/bridgekit";
-
-const params = Type.Object({ text: Type.String() });
-
-type CustomHost = "custom-runtime";
+## Best practices
 
-export const customTool = definePortableTool<typeof params, CustomHost>({
-  name: "custom_echo",
-  title: "Custom Echo",
-  description: "Echoes text in a custom runtime.",
-  parameters: params,
-  execute(args, ctx) {
-    const host: CustomHost = ctx.host;
-    return { text: `${host}: ${args.text}` };
-  },
-});
+Tool definition best practices:
 
-const hostValue: PortableToolHost<CustomHost> = "custom-runtime";
-void hostValue;
-```
+- Keep tool files host-neutral: no pi imports, no MCP SDK imports.
+- Use TypeBox `Type.Object(...)` schemas so MCP can expose input schemas directly.
+- Return `text` for model-visible output and `structuredContent` for machine-readable data.
+- Use `isError: true` for expected/domain failures that should be represented as tool output.
+- Throw only for unexpected programmer, adapter, or runtime failures.
+- Respect `ctx.signal` in long-running tools.
+- Use `ctx.progress?.(...)` for incremental updates.
+- Keep modules import-passive; do not register tools or start servers at import time.
+- For stateful tools, export a `createTools()` factory instead of a module-level singleton so each host runtime gets isolated state.
+- TypeBox validation happens before `execute`; use a permissive schema plus domain validation if you need custom guidance for structurally invalid input.
 
-Use `PortableToolHost<CustomHost>` for values that may be either a built-in host or your extension. Use the `PortableTool`/`PortableToolContext` generic when a tool or adapter is custom-host-only.
+## Packaging
 
-## Package and release checklist
+Package and release checklist:
 
 - Publish compiled JavaScript plus generated `.d.ts` declarations for runtime entrypoints.
 - Keep `exports`, `main`, and `types` aligned with built files.
@@ -267,3 +263,12 @@ Use `PortableToolHost<CustomHost>` for values that may be either a built-in host
 - Treat `docs/releasing.md` as the future release handoff; this repository is not configured for automated publish yet.
 
 See `examples/README.md` for complete copyable examples.
+
+## For coding agents
+
+Read these files in order:
+
+1. `README.md` — public API, contracts, and best practices.
+2. `llms.txt` — compact agent-facing usage rules and anti-patterns.
+3. `examples/README.md` — copyable layouts for shared tools, pi extensions, MCP stdio servers, and per-host metadata via `hostExtras`.
+4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, and `dist/src/mcp.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain the same implementation context.

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

@@ -37,9 +37,8 @@ export interface PortableValidationError {
     message: string;
 }
 export type PortableToolBuiltInHost = "pi" | "mcp" | "test";
-export type PortableToolHost<TExtension extends string = never> = PortableToolBuiltInHost | TExtension;
-export interface PortableToolContext<THost extends string = PortableToolBuiltInHost> {
-    host: THost;
+export interface PortableToolContext {
+    host: PortableToolBuiltInHost;
     signal?: AbortSignal;
     progress?: (update: PortableToolResult) => void;
 }
@@ -139,12 +138,12 @@ export interface PortableToolHostExtras {
     pi?: PiHostExtras;
     mcp?: McpHostExtras;
 }
-export interface PortableTool<TParams extends TSchema = TSchema, THost extends string = PortableToolBuiltInHost> {
+export interface PortableTool<TParams extends TSchema = TSchema> {
     name: string;
     title: string;
     description: string;
     parameters: TParams;
-    execute: (args: Static<TParams>, ctx: PortableToolContext<THost>) => PortableToolResult | Promise<PortableToolResult>;
+    execute: (args: Static<TParams>, ctx: PortableToolContext) => PortableToolResult | Promise<PortableToolResult>;
     /**
      * Optional per-host metadata. Adapters consume the keys they recognise;
      * unknown host namespaces are ignored. Absent → no behavior change.
@@ -156,4 +155,4 @@ export interface PortableTool<TParams extends TSchema = TSchema, THost extends s
      */
     hostExtras?: PortableToolHostExtras;
 }
-export declare function definePortableTool<TParams extends TSchema, THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TParams, THost>): PortableTool<TParams, THost>;
+export declare function definePortableTool<TParams extends TSchema>(tool: PortableTool<TParams>): PortableTool<TParams>;

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

@@ -1,9 +1,9 @@
 import type { TSchema } from "typebox";
-import type { PortableTool, PortableToolBuiltInHost, PortableToolContext, PortableToolResult, PortableValidationError } from "./define-tool.js";
-export declare function validatePortableToolArgs<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown): {
+import type { PortableTool, PortableToolContext, PortableToolResult, PortableValidationError } from "./define-tool.js";
+export declare function validatePortableToolArgs(tool: PortableTool<TSchema>, args: unknown): {
     ok: true;
 } | {
     ok: false;
     errors: PortableValidationError[];
 };
-export declare function executePortableTool<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown, ctx: PortableToolContext<NoInfer<THost>>): Promise<PortableToolResult>;
+export declare function executePortableTool(tool: PortableTool<TSchema>, args: unknown, ctx: PortableToolContext): Promise<PortableToolResult>;

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 PortableToolHost, type PortableToolHostExtras, type PortableToolResult, type PortableValidationError, } from "./core/define-tool.js";
+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 { executePortableTool, validatePortableToolArgs } from "./core/execute-tool.js";
 export { isDomainFailure, isValidationFailure, type PortableDomainFailure, type PortableValidationFailure, } from "./core/result-guards.js";

package/examples/README.md

@@ -283,53 +283,7 @@ MCP behavior:
 
 ---
 
-## 4. Use custom host typing for custom adapters
-
-Default portable tools accept only built-in hosts: `"pi" | "mcp" | "test"`.
-
-If you are writing a custom adapter, opt in explicitly so the handler can safely narrow `ctx.host`:
-
-```ts
-import { Type } from "typebox";
-import {
-  definePortableTool,
-  executePortableTool,
-  type PortableTool,
-  type PortableToolContext,
-  type PortableToolHost,
-} from "@feniix/bridgekit";
-
-const params = Type.Object({ text: Type.String() });
-
-type CustomHost = "custom-runtime";
-type CustomTool = PortableTool<typeof params, CustomHost>;
-
-const customTool = definePortableTool<typeof params, CustomHost>({
-  name: "custom_echo",
-  title: "Custom Echo",
-  description: "Echoes text in a custom runtime.",
-  parameters: params,
-  execute(args, ctx) {
-    const host: CustomHost = ctx.host;
-    return { text: `${host}: ${args.text}` };
-  },
-});
-
-async function runCustomTool(tool: CustomTool, text: string) {
-  const ctx: PortableToolContext<CustomHost> = { host: "custom-runtime" };
-  return executePortableTool(tool, { text }, ctx);
-}
-
-const hostValue: PortableToolHost<CustomHost> = "custom-runtime";
-void hostValue;
-void customTool;
-```
-
-Use `PortableToolHost<CustomHost>` for values that can be either a built-in host or your custom extension. Use `PortableToolContext<CustomHost>` or `PortableTool<Schema, CustomHost>` when a tool is custom-host-only.
-
----
-
-## 5. Per-host metadata via `hostExtras`
+## 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.
 
@@ -366,7 +320,7 @@ 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.
 - Set only the fields the adapter recognises; unrecognised keys are silently ignored, but they add noise to the definition.
-- For custom-host adapters, extend `PortableToolHostExtras` via `declare module "@feniix/bridgekit"` so consumers of your adapter get type safety on the new namespace.
+- 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.
 
 See `docs/rfc-host-extras.md` for the full design rationale (which fields qualify, why a top-level field beats a sidecar map, the closure rule for future additions).
 
@@ -446,7 +400,7 @@ per-consumer migration deltas.
 
 ---
 
-## 6. Package checklist
+## 5. Package checklist
 
 For publishable tool packages:
 

package/llms.txt

@@ -6,7 +6,7 @@ Use this package when you need to define a tool once and expose it through both
 
 1. `README.md` — public API, contracts, best practices, packaging notes.
 2. `llms.txt` — compact agent-facing usage rules and anti-patterns.
-3. `examples/README.md` — copyable end-to-end layouts for shared tools, pi extension wiring, MCP stdio server wiring, and custom hosts.
+3. `examples/README.md` — copyable end-to-end layouts for shared tools, pi extension wiring, MCP stdio server wiring, and per-host metadata via `hostExtras`.
 4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, and `dist/src/mcp.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain implementation context.
 
 ## Import map
@@ -96,23 +96,6 @@ if (result.isError) {
 }
 ```
 
-## Custom host typing
-
-Default tools accept only built-in hosts: `"pi" | "mcp" | "test"`.
-For a custom adapter, opt in explicitly:
-
-```ts
-const customTool = definePortableTool<typeof params, "custom-host">({
-  // ...
-  execute(args, ctx) {
-    const host: "custom-host" = ctx.host;
-    return { text: host };
-  },
-});
-```
-
-Use `PortableToolHost<"custom-host">` when a value may be either a built-in host or that extension.
-
 ## Mixed source-loaded hosts and compiled MCP bins
 
 Some hosts, such as pi in source-extension packages, may intentionally load TypeScript source while MCP clients launched from npm need compiled JavaScript. In that case:

package/package.json

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