@feniix/bridgekit 0.9.5 → 0.11.0

package/CHANGELOG.md

@@ -4,7 +4,74 @@ 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.9.5] - Unreleased
+## [0.11.0] - 2026-05-27
+
+### Added
+
+- New subpath export `@feniix/bridgekit/bin-wrapper` shipping
+  `runBinWrapper({ metaUrl, mcpEntry, buildScript, ... })`. Eliminates
+  the ~25-line "resolve dist path → spawn build if missing → import
+  and run" boilerplate that mixed source-loaded pi + compiled MCP
+  packages have been copy-pasting. Three downstream consumers
+  (pi-sequential-thinking, pi-exa, pi-code-reasoning) carry hand-rolled
+  versions today and can migrate in one-line replacements. Tested
+  against four canonical scenarios (entry present; entry built on
+  demand; build fails non-zero; build exits 0 with file still missing)
+  plus a negative for entry modules missing the required `runServer`
+  export. Resolves
+  [#6](https://github.com/feniix/bridgekit/issues/6).
+
+### Changed
+
+- `signalFromExtra` (internal helper at `src/adapters/mcp-signal.ts`) removed.
+  The MCP SDK exposes `RequestHandlerExtra<ServerRequest, ServerNotification>`
+  with a guaranteed non-optional `signal: AbortSignal` field; the duck-typing
+  helper existed only because the contract was undocumented. `createMcpServer`'s
+  `tools/call` handler now reads `extra.signal` directly with a typed `extra`
+  parameter. No behavior change; cancellation propagation is unchanged. An
+  adversarial type-level pin in `src/adapters/mcp.typecheck.ts` fails closed
+  if the SDK ever changes `signal`'s type. Resolves
+  [#3](https://github.com/feniix/bridgekit/issues/3).
+
+## [0.10.0] - 2026-05-27
+
+### 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
 

package/README.md

@@ -63,7 +63,7 @@ This package is ESM-only and supports Node.js 22.19.0 or newer. Published module
 
 ## Why
 
-- Define a tool once; ship it to pi and MCP (and custom hosts) without per-host forks.
+- 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.
@@ -80,17 +80,18 @@ import {
   type PortableTool,
   type PortableToolBuiltInHost,
   type PortableToolContext,
-  type PortableToolHost,
   type PortableToolResult,
   type PortableValidationError,
 } from "@feniix/bridgekit";
 import { registerPiTools } from "@feniix/bridgekit/pi";
 import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
 ```
 
 - Root entrypoint: host-neutral tool definitions, validation, and execution helpers.
 - `/pi`: pi adapter only.
 - `/mcp`: MCP server adapter only.
+- `/bin-wrapper`: optional helper for npm `bin` scripts that need to build a local compiled MCP entry on first invocation.
 
 Do not deep-import from `dist/` or `src/` in consuming packages.
 
@@ -232,41 +233,6 @@ 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";
-
-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}` };
-  },
-});
-
-const hostValue: PortableToolHost<CustomHost> = "custom-runtime";
-void hostValue;
-```
-
-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.
-
 ## Best practices
 
 Tool definition best practices:
@@ -306,5 +272,5 @@ 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 custom hosts.
+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/adapters/mcp.js

@@ -2,7 +2,6 @@ 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 { executePortableTool } from "../core/execute-tool.js";
-import { signalFromExtra } from "./mcp-signal.js";
 function toMcpResult(result) {
     return {
         content: [{ type: "text", text: result.text }],
@@ -197,7 +196,7 @@ export function createMcpServer(options) {
         try {
             const result = await executePortableTool(tool, request.params.arguments ?? {}, {
                 host: "mcp",
-                signal: signalFromExtra(extra),
+                signal: extra.signal,
             });
             return toMcpResult(result);
         }

package/dist/src/bin-wrapper-internal.d.ts

@@ -0,0 +1,39 @@
+import { type SpawnSyncOptions, type SpawnSyncReturns } from "node:child_process";
+export type BinWrapperSpawnSync = (command: string, args: readonly string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer>;
+export interface BinWrapperOptions {
+    /**
+     * `import.meta.url` of the bin script. Used to locate the package root
+     * (the bin's parent directory). Passing the helper's own `import.meta.url`
+     * would resolve the wrong package, which is why the caller must supply this.
+     */
+    metaUrl: string;
+    /**
+     * Path to the compiled MCP entry, relative to the package root.
+     *
+     * Must be a literal in the caller's source. The helper does not contain
+     * arbitrary paths — sourcing this from CLI args or env vars exposes the
+     * dynamic `import()` to attacker-controlled file paths.
+     *
+     * @example "dist/extensions/mcp-server.js"
+     */
+    mcpEntry: string;
+    /**
+     * npm script to invoke when the entry is missing.
+     *
+     * Must be a literal in the caller's source. On Windows the helper sets
+     * `shell: true` for `spawnSync`, which makes `&`, `|`, and `^` shell
+     * metacharacters; sourcing this from CLI args or env vars opens a
+     * command-injection vector on Windows.
+     *
+     * @example "build:mcp"
+     */
+    buildScript: string;
+    buildTimeoutMs?: number;
+    logPrefix?: string;
+}
+export interface BinWrapperDeps {
+    spawnSync: BinWrapperSpawnSync;
+    exit: (code: number) => never;
+}
+export declare const defaultBinWrapperDeps: BinWrapperDeps;
+export declare function runBinWrapperWithDeps(options: BinWrapperOptions, deps: BinWrapperDeps): Promise<void>;

package/dist/src/bin-wrapper-internal.js

@@ -0,0 +1,55 @@
+// Internal implementation of bin-wrapper. Ships in the published tarball
+// (the public `bin-wrapper.js` imports from it at runtime) but is not
+// reachable via package.json#exports — deep-importing this module by name
+// fails with ERR_PACKAGE_PATH_NOT_EXPORTED (pinned by scripts/smoke-package.mjs
+// under inv-deep-imports-fail).
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const DEFAULT_BUILD_TIMEOUT_MS = 60_000;
+const DEFAULT_LOG_PREFIX = "bridgekit-bin";
+export const defaultBinWrapperDeps = {
+    spawnSync,
+    exit: process.exit,
+};
+export async function runBinWrapperWithDeps(options, deps) {
+    const packageRoot = resolve(dirname(fileURLToPath(options.metaUrl)), "..");
+    const entryPath = join(packageRoot, options.mcpEntry);
+    if (!existsSync(entryPath)) {
+        const timeoutMs = options.buildTimeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS;
+        const build = deps.spawnSync("npm", ["run", options.buildScript, "--silent"], {
+            cwd: packageRoot,
+            stdio: "inherit",
+            shell: process.platform === "win32",
+            timeout: timeoutMs,
+        });
+        // File presence is the load-bearing signal: a build that exits non-zero
+        // *after* emitting the entry (e.g. tsc with a post-emit diagnostic, or a
+        // build pipeline whose final step is non-fatal lint/test) is still
+        // recoverable. Only bail if the artifact we need is actually missing.
+        if (!existsSync(entryPath)) {
+            const prefix = options.logPrefix ?? DEFAULT_LOG_PREFIX;
+            // A child killed by the timeout returns status: null + signal set.
+            // Distinguish that from a build error so the operator sees the actual
+            // cause and knows about buildTimeoutMs.
+            if (build.signal !== null) {
+                console.error(`[${prefix}] Build timed out after ${timeoutMs}ms (signal ${build.signal}). ` +
+                    `Raise buildTimeoutMs or run \`npm run ${options.buildScript}\` manually.`);
+                deps.exit(1);
+            }
+            else {
+                console.error(`[${prefix}] Failed to build the local MCP server. Run \`npm run ${options.buildScript}\` and try again.`);
+                // Propagate the build's non-zero status if present; fall back to 1
+                // when status===0 with missing entry or status===null without signal.
+                deps.exit(build.status !== null && build.status !== 0 ? build.status : 1);
+            }
+        }
+    }
+    const mod = (await import(pathToFileURL(entryPath).href));
+    if (typeof mod.runServer !== "function") {
+        throw new Error(`[bridgekit/bin-wrapper] entry "${options.mcpEntry}" does not export a runServer() function. ` +
+            `Make sure your MCP server module exports \`export async function runServer()\` at the top level.`);
+    }
+    await mod.runServer();
+}

package/dist/src/bin-wrapper.d.ts

@@ -0,0 +1,25 @@
+import { type BinWrapperOptions } from "./bin-wrapper-internal.js";
+export type { BinWrapperOptions } from "./bin-wrapper-internal.js";
+/**
+ * Helper for an npm `bin` script that needs to load a compiled MCP entrypoint
+ * and build it on first invocation (workspace/local execution) when the
+ * compiled output is missing.
+ *
+ * Replaces the ~25-line "resolve dist path -> spawn build if missing ->
+ * import and run" boilerplate shipped in `examples/README.md` since 0.4.x.
+ *
+ * The MCP entry module must export `runServer(): Promise<void>`. Consumers
+ * with a different name can re-export under that alias.
+ *
+ * @example
+ * ```ts
+ * #!/usr/bin/env node
+ * import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
+ * await runBinWrapper({
+ *   metaUrl: import.meta.url,
+ *   mcpEntry: "dist/extensions/mcp-server.js",
+ *   buildScript: "build:mcp",
+ * });
+ * ```
+ */
+export declare function runBinWrapper(options: BinWrapperOptions): Promise<void>;

package/dist/src/bin-wrapper.js

@@ -0,0 +1,26 @@
+import { defaultBinWrapperDeps, runBinWrapperWithDeps } from "./bin-wrapper-internal.js";
+/**
+ * Helper for an npm `bin` script that needs to load a compiled MCP entrypoint
+ * and build it on first invocation (workspace/local execution) when the
+ * compiled output is missing.
+ *
+ * Replaces the ~25-line "resolve dist path -> spawn build if missing ->
+ * import and run" boilerplate shipped in `examples/README.md` since 0.4.x.
+ *
+ * The MCP entry module must export `runServer(): Promise<void>`. Consumers
+ * with a different name can re-export under that alias.
+ *
+ * @example
+ * ```ts
+ * #!/usr/bin/env node
+ * import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
+ * await runBinWrapper({
+ *   metaUrl: import.meta.url,
+ *   mcpEntry: "dist/extensions/mcp-server.js",
+ *   buildScript: "build:mcp",
+ * });
+ * ```
+ */
+export async function runBinWrapper(options) {
+    return runBinWrapperWithDeps(options, defaultBinWrapperDeps);
+}

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

@@ -241,36 +241,23 @@ For mixed source-loaded pi + compiled MCP packages, keep the pi source entrypoin
 }
 ```
 
-The wrapper should resolve the generated MCP server relative to the installed package, build it when missing in local/workspace execution, and preserve build failures:
+The wrapper should resolve the generated MCP server relative to the installed package, build it when missing in local/workspace execution, and preserve build failures. BridgeKit ships this as a built-in helper under the `/bin-wrapper` subpath:
 
 ```js
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const serverPath = join(packageRoot, "dist", "extensions", "mcp-server.js");
-
-if (!existsSync(serverPath)) {
-  const build = spawnSync("npm", ["run", "build:mcp", "--silent"], {
-    cwd: packageRoot,
-    stdio: "inherit",
-    shell: process.platform === "win32",
-    timeout: 60_000,
-  });
-
-  if (build.status !== 0 || !existsSync(serverPath)) {
-    console.error("[my-tools] Failed to build the local MCP server. Run `npm run build:mcp` and try again.");
-    process.exit(build.status && build.status !== 0 ? build.status : 1);
-  }
-}
+import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
 
-const { runServer } = await import(pathToFileURL(serverPath).href);
-await runServer();
+await runBinWrapper({
+  metaUrl: import.meta.url,
+  mcpEntry: "dist/extensions/mcp-server.js",
+  buildScript: "build:mcp",
+});
 ```
 
+`mcpEntry` and `buildScript` are the two options consumers typically vary. The MCP entry module must export `runServer(): Promise<void>` (the convention used throughout these examples). `buildTimeoutMs` (default `60_000`) and `logPrefix` (default `"bridgekit-bin"`) are available for tuning but rarely needed.
+
+Both `mcpEntry` and `buildScript` must be **literal strings** in your bin source. The helper joins `mcpEntry` onto the resolved package root and dynamically `import()`s it, and it passes `buildScript` to `spawnSync` (with `shell: true` on Windows where `&`, `|`, and `^` are shell metacharacters). Sourcing either from CLI args, environment variables, or other runtime input exposes arbitrary-file import and Windows command injection — the trusted-literal expectation is the threat model.
+
 Commit the wrapper with executable mode (`chmod +x bin/my-tools-mcp.js`) and verify `npm pack --dry-run --json` includes it with executable mode.
 
 MCP behavior:
@@ -283,53 +270,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 +307,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 +387,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
@@ -20,11 +20,13 @@ import {
 } from "@feniix/bridgekit";
 import { registerPiTools } from "@feniix/bridgekit/pi";
 import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper"; // optional: built-in bin wrapper for mixed source-loaded pi + compiled MCP packages
 ```
 
 - Root entrypoint: host-neutral tool definitions, validation, and execution helpers.
 - `/pi`: pi adapter only.
 - `/mcp`: MCP server adapter only.
+- `/bin-wrapper`: optional helper for npm `bin` scripts that build a local compiled MCP entry on first invocation. `mcpEntry` and `buildScript` must be literal strings in the caller's source (they're the dynamic-import target and the `spawnSync` arg; sourcing them from env or CLI is an arbitrary-file-import and Windows command-injection vector).
 
 Do not deep-import from `dist/` or `src/` in consumer code. Reading published declarations for documentation is fine; imports should use the package entrypoints above.
 
@@ -96,23 +98,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.5",
+  "version": "0.11.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -37,6 +37,10 @@
       "types": "./dist/src/mcp.d.ts",
       "import": "./dist/src/mcp.js"
     },
+    "./bin-wrapper": {
+      "types": "./dist/src/bin-wrapper.d.ts",
+      "import": "./dist/src/bin-wrapper.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {

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

@@ -1,9 +0,0 @@
-/**
- * Defensively pulls an `AbortSignal` out of MCP request `extra`. The MCP SDK
- * does not formally type a `signal` on `extra`, so the shape is sniffed
- * structurally.
- *
- * Validated against `@modelcontextprotocol/sdk` v1.x. Revalidate on any SDK
- * major bump in case the cancellation channel moves or gains a typed surface.
- */
-export declare function signalFromExtra(extra: unknown): AbortSignal | undefined;

package/dist/src/adapters/mcp-signal.js

@@ -1,15 +0,0 @@
-/**
- * Defensively pulls an `AbortSignal` out of MCP request `extra`. The MCP SDK
- * does not formally type a `signal` on `extra`, so the shape is sniffed
- * structurally.
- *
- * Validated against `@modelcontextprotocol/sdk` v1.x. Revalidate on any SDK
- * major bump in case the cancellation channel moves or gains a typed surface.
- */
-export function signalFromExtra(extra) {
-    if (!extra || typeof extra !== "object" || !("signal" in extra)) {
-        return undefined;
-    }
-    const signal = extra.signal;
-    return signal instanceof AbortSignal ? signal : undefined;
-}