@feniix/bridgekit 0.8.3 → 0.9.1

package/CHANGELOG.md

@@ -4,7 +4,85 @@ 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.8.3] - Unreleased
+## [0.9.1] - 2026-05-26
+
+### Fixed
+
+- pi adapter now spreads `hostExtras.pi.promptGuidelines` into a fresh
+  `string[]` before handing it to `pi.registerTool`. Bridgekit's declared type
+  stays `readonly string[]` (signals immutability of consumer-owned metadata),
+  but the boundary copy satisfies pi-coding-agent's mutable `string[]`
+  contract. Resolves contravariance friction observed in three downstream
+  consumers that previously needed `pi as unknown as PiToolRegistration`
+  casts. Resolves [#47](https://github.com/feniix/bridgekit/issues/47).
+
+## [0.9.0] - 2026-05-26
+
+### Changed
+
+- Widened `createMcpServer` / `runMcpStdioServer` `tools` parameter from
+  `PortableTool<TObject>[]` to `PortableTool<TSchema>[]`. `Type.Intersect([
+  Type.Object(...), Type.Object(...)])` is now accepted alongside
+  `Type.Object(...)`. Schemas that don't resolve to a JSON-Schema object at the
+  top level throw at server construction with a named-tool error message
+  pointing to the actionable wrapping recipe. On the wire, `tools/list`
+  synthesises `type: "object"` on schemas whose top-level lowering is `allOf`
+  so MCP SDK clients that Zod-validate `inputSchema.type` continue to accept
+  them; existing `Type.Object` consumers see no change in payload shape.
+  Resolves [#29](https://github.com/feniix/bridgekit/issues/29).
+- `createMcpServer` construction error now appends Union-specific guidance
+  when the offending tool's parameters lower to `anyOf`/`oneOf`, including
+  when the Union is nested inside an `allOf` branch (the `Type.Intersect`
+  recipe is wrong for that shape). The bare allOf-with-mixed-branches case
+  now names the first non-object branch by index in the `type="..."` label
+  instead of the misdirecting `type="allOf"`.
+- `tools/list` payload is now pre-computed at `createMcpServer` construction
+  rather than per-request. The outer `tools` array is snapshotted at that
+  point: pushing or removing entries from the caller's array post-construction
+  does not affect listing or dispatch. Schemas inside each tool remain held
+  by reference; treat `tool.parameters` as immutable once the server is
+  constructed.
+- `createMcpServer` construction errors now carry a stable `error.code` so
+  consumers have a non-string anchor for branching: `"BRIDGEKIT_MCP_NON_OBJECT_PARAMETERS"`
+  for the top-level-object guard, `"BRIDGEKIT_MCP_DUPLICATE_TOOL_NAME"` for
+  the new duplicate-name guard. Message text remains recipe-shaped for
+  human reading but is not a public contract; branch on `.code`.
+
+### Added
+
+- `PortableTool.hostExtras` — optional per-host metadata namespace for
+  host-specific fields without polluting the host-neutral tool definition.
+  `hostExtras.pi` carries `pendingMessage` (fires a pre-execute `onUpdate`
+  so pi-side tools can surface a "Processing..." signal without bypassing
+  `registerPiTools`), `promptSnippet`, and `promptGuidelines` (passed
+  through to the pi host's `registerTool` call). `hostExtras.mcp.annotations`
+  (`title` / `readOnlyHint` / `destructiveHint` / `idempotentHint` /
+  `openWorldHint`) is consumed in this release: annotations are attached to
+  `tools/list` entries, closing the RFC §4 30-day rollback gate in the same
+  release that declares the namespace rather than deferring to 0.9.x. Tools
+  that don't set `hostExtras` see zero behavior change: the pi registration
+  payload's key set is byte-identical to 0.8.x and the MCP `Tool` entry omits
+  the `annotations` field entirely. The shape is module-augmentable: a
+  custom-host adapter can extend `PortableToolHostExtras` via
+  `declare module "@feniix/bridgekit"` to claim its own namespace. Resolves
+  [#28](https://github.com/feniix/bridgekit/issues/28).
+- `createMcpServer` now rejects duplicate tool names at construction with
+  a tool-attributed error (code `BRIDGEKIT_MCP_DUPLICATE_TOOL_NAME`). The
+  previous behavior silently overwrote earlier registrations in the dispatch
+  map while still listing both on `tools/list`, leaving the earlier tool
+  unreachable on `tools/call`.
+- RFC: `docs/rfc-host-extras.md` (design doc for [#28](https://github.com/feniix/bridgekit/issues/28); no code change).
+
+### Fixed
+
+- `PortableValidationError.field` preservation for slash-named properties
+  (the 0.8.3 fix) now descends into `Type.Intersect` (`allOf`) branches.
+  Previously a property named `a/b` inside an Intersect branch resolved as
+  `b` because the schema walker stopped at the root's missing `properties`
+  field; the walker now probes each `allOf` branch with the full remaining
+  path.
+
+## [0.8.3] - 2026-05-26
 
 ### Fixed
 

package/README.md

@@ -141,6 +141,39 @@ 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`
+
+`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.
+
+```ts
+import { Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
+
+export const generateSummaryTool = definePortableTool({
+  name: "generate_summary",
+  title: "Generate Summary",
+  description: "Summarise a block of text.",
+  parameters: Type.Object({ text: Type.String() }),
+  execute(args) {
+    return { text: args.text.slice(0, 80) };
+  },
+  hostExtras: {
+    pi: {
+      // Fires once before TypeBox validation runs. Lets the pi host show a
+      // "Processing..." signal without a custom registration wrapper.
+      pendingMessage: "Summarising...",
+      promptSnippet: "Use this tool when the user asks for a short summary.",
+      promptGuidelines: ["Prefer < 80 chars.", "Strip markdown."],
+    },
+    mcp: {
+      annotations: { readOnlyHint: true },
+    },
+  },
+});
+```
+
+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
 
 ```ts
@@ -178,6 +211,8 @@ if (process.argv[1] && realpathIfPossible(resolve(process.argv[1])) === realpath
 
 The MCP adapter uses low-level `tools/list` and `tools/call` handlers so TypeBox schemas are exposed as JSON Schema directly. It intentionally does not expose a high-level `registerMcpTools` helper.
 
+Tool `parameters` must resolve to a JSON-Schema object at the top level. `Type.Object(...)` is the common case; `Type.Intersect([Type.Object(...), Type.Object(...)])` of object schemas is also accepted (its `allOf` lowering is recognised, and `type: "object"` is synthesised onto the `tools/list` response so MCP clients that validate the inputSchema shape stay happy). Non-object top-level schemas (`Type.String()`, `Type.Union([Type.Object(...), Type.Object(...)])`, etc.) throw at server construction with a named-tool error so the failure surfaces at adapter setup, not at first `tools/call`.
+
 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, and the same result-guard helpers (`isValidationFailure`, `isDomainFailure`) narrow them on either side.

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

@@ -1,10 +1,23 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import type { TObject } from "typebox";
+import type { TSchema } from "typebox";
 import type { PortableTool } from "../core/define-tool.js";
 export interface CreateMcpServerOptions {
     name: string;
     version: string;
-    tools: readonly PortableTool<TObject>[];
+    /**
+     * Portable tools to expose. Each tool's `parameters` must resolve to a
+     * JSON-Schema object at the top level — `Type.Object(...)` or
+     * `Type.Intersect([Type.Object(...), Type.Object(...)])`. Other top-level
+     * shapes (`Type.String()`, `Type.Union([Type.Object(...), Type.Object(...)])`,
+     * etc.) throw at `createMcpServer` construction with a tool-attributed error.
+     *
+     * 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
+     * `createMcpServer` returns.
+     */
+    tools: readonly PortableTool<TSchema>[];
     instructions?: string;
 }
 export declare function createMcpServer(options: CreateMcpServerOptions): Server;

package/dist/src/adapters/mcp.js

@@ -10,20 +10,154 @@ function toMcpResult(result) {
         isError: result.isError ?? false,
     };
 }
+/**
+ * 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;
+    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.
+ */
+function schemaTypeLabel(schema) {
+    if (typeof schema !== "object" || schema === null)
+        return "unknown";
+    const candidate = schema;
+    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
+ * `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"]`.
+ */
+function toInputSchema(parameters) {
+    const candidate = parameters;
+    if (candidate.type === "object") {
+        return parameters;
+    }
+    return { type: "object", ...parameters };
+}
+/**
+ * Stable `error.code` values attached to `createMcpServer` construction
+ * failures so consumers have a non-string anchor (the message text is
+ * recipe-shaped and may evolve; the code is part of the public contract).
+ */
+const ERROR_CODE_NON_OBJECT_PARAMETERS = "BRIDGEKIT_MCP_NON_OBJECT_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)) {
+            const typeLabel = schemaTypeLabel(tool.parameters);
+            let message = `createMcpServer: tool "${tool.name}" has a non-object parameters schema (type="${typeLabel}"). ` +
+                "MCP requires Type.Object(...) at the top level; use Type.Object({ value: Type.String() }) " +
+                "to wrap a single-field schema, or Type.Intersect([Type.Object(...), Type.Object(...)]) for " +
+                "merged object schemas.";
+            if (typeLabel.includes("anyOf") || typeLabel.includes("oneOf")) {
+                // Union lowers to `anyOf`/`oneOf` (OR) — at the top level or nested
+                // inside an `allOf` branch. The generic `Type.Intersect` (AND) advice
+                // above is the wrong recipe for that case, so append union-specific
+                // guidance.
+                message +=
+                    " Top-level Type.Union([Type.Object(...), ...]) is not supported by the MCP wire layer; " +
+                        "flatten branches into a single Type.Object(...) with optional discriminator fields, " +
+                        "or expose each branch as a separate tool.";
+            }
+            throwWithCode(message, ERROR_CODE_NON_OBJECT_PARAMETERS);
+        }
+    }
+}
+function assertUniqueToolNames(tools) {
+    const seen = new Set();
+    for (const tool of tools) {
+        if (seen.has(tool.name)) {
+            throwWithCode(`createMcpServer: tool "${tool.name}" is registered more than once. ` +
+                "MCP tool names must be unique within a server — silently overwriting would make the " +
+                "earlier registration unreachable on `tools/call`.", ERROR_CODE_DUPLICATE_TOOL_NAME);
+        }
+        seen.add(tool.name);
+    }
+}
 export function createMcpServer(options) {
+    assertObjectShapedParameters(options.tools);
+    assertUniqueToolNames(options.tools);
+    // 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 annotations = tool.hostExtras?.mcp?.annotations;
+        // MCP advisory hints from `hostExtras.mcp.annotations`. Two gates:
+        //   1. `annotations !== undefined` — a tool without hostExtras builds a
+        //      Tool entry whose own-property keys are byte-identical to 0.8.x.
+        //   2. `Object.keys(annotations).length > 0` — an explicitly empty
+        //      annotations object is semantically identical to no annotations
+        //      and is omitted from the wire payload (not emitted as `{}`).
+        //
+        // The non-empty branch shallow-clones the annotations object so that
+        // post-construction mutation of the caller's `tool.hostExtras.mcp.annotations`
+        // cannot leak into subsequent `tools/list` responses. The clone is
+        // safe-by-construction because annotation fields are primitive scalars
+        // (the MCP spec defines only `title: string` and four `…Hint: boolean`
+        // fields); no nested mutation surface exists.
+        const hasAnnotations = annotations !== undefined && Object.keys(annotations).length > 0;
+        return {
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: toInputSchema(tool.parameters),
+            ...(hasAnnotations ? { annotations: { ...annotations } } : {}),
+        };
+    });
     const server = new Server({ name: options.name, version: options.version }, {
         capabilities: { tools: { listChanged: false } },
         instructions: options.instructions,
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: options.tools.map((tool) => ({
-            name: tool.name,
-            title: tool.title,
-            description: tool.description,
-            inputSchema: tool.parameters,
-        })),
-    }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: mcpTools }));
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const tool = byName.get(request.params.name);
         if (!tool) {

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

@@ -19,6 +19,8 @@ type PiToolDefinition = {
     description: string;
     parameters: TSchema;
     execute(toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: (update: PiToolUpdate) => void, ctx?: unknown): Promise<PiToolResult>;
+    promptSnippet?: string;
+    promptGuidelines?: readonly string[];
 };
 export type PiToolRegistration = {
     registerTool(tool: PiToolDefinition): unknown;

package/dist/src/adapters/pi.js

@@ -50,14 +50,41 @@ export function registerPiTools(pi, tools, options = {}) {
         });
     }
     for (const tool of tools) {
+        const piExtras = tool.hostExtras?.pi;
         pi.registerTool({
             name: tool.name,
             label: tool.title,
             description: tool.description,
             parameters: tool.parameters,
+            // 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.
+            ...(piExtras?.promptSnippet !== undefined && { promptSnippet: piExtras.promptSnippet }),
+            // Spread into a fresh array at the boundary: bridgekit declares promptGuidelines
+            // as `readonly string[]` (signal: "we don't mutate consumer metadata"), but
+            // pi-coding-agent's registerTool input is `string[]` (mutable). The boundary
+            // copy satisfies both sides without weakening either declared type.
+            ...(piExtras?.promptGuidelines !== undefined && { promptGuidelines: [...piExtras.promptGuidelines] }),
             async execute(_toolCallId, params, signal, onUpdate, _ctx) {
                 let result;
                 try {
+                    // Pre-execute lifecycle hook. Fires exactly once per call, before
+                    // TypeBox validation runs, when the tool declares a non-empty
+                    // `hostExtras.pi.pendingMessage`. Silently no-ops when the pi host
+                    // does not supply `onUpdate`. See RFC §3 (Gap B).
+                    //
+                    // Wrapped inside the same try/catch that guards the handler so a
+                    // throwing host `onUpdate` is routed through `errorHandling` (and
+                    // does not skip past the catch as an uncaught exception). The
+                    // handler is NOT invoked when the pre-execute emit throws —
+                    // erroring before validation is a host-channel failure, not an
+                    // argument failure.
+                    if (piExtras?.pendingMessage !== undefined && piExtras.pendingMessage !== "") {
+                        onUpdate?.({
+                            content: [{ type: "text", text: piExtras.pendingMessage }],
+                            details: { status: "pending" },
+                        });
+                    }
                     result = await executePortableTool(tool, params, {
                         host: "pi",
                         signal,

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

@@ -43,11 +43,117 @@ export interface PortableToolContext<THost extends string = PortableToolBuiltInH
     signal?: AbortSignal;
     progress?: (update: PortableToolResult) => void;
 }
+/**
+ * Pi-specific entries on `PortableTool.hostExtras`. Read only by the pi
+ * adapter; the MCP adapter ignores this namespace.
+ *
+ * **Snapshot semantics.** Pi-side fields are read at registration time:
+ * `pendingMessage` is re-read at each tool invocation (so a mutation between
+ * two calls would be observed), while `promptSnippet` / `promptGuidelines`
+ * are captured once during `registerPiTools` and never re-read. Treat all
+ * pi-side fields as immutable once `registerPiTools` returns.
+ *
+ * @see PortableToolHostExtras
+ */
+export interface PiHostExtras {
+    /**
+     * One-shot text the pi adapter emits as `onUpdate(...)` exactly once,
+     * **before** TypeBox validation runs. When unset (or absent on the tool),
+     * no pre-execute update is emitted. An empty string is treated as unset
+     * and produces no update. When the registered pi host does not supply an
+     * `onUpdate` callback at call time, the adapter silently no-ops.
+     *
+     * Held by reference at registration time; treat `pendingMessage` as
+     * immutable once attached to a tool definition.
+     *
+     * @example
+     * hostExtras: { pi: { pendingMessage: "Processing..." } }
+     */
+    pendingMessage?: string;
+    /**
+     * Short string blended into pi's system prompt to summarise when this tool
+     * should be called. Passed through verbatim to pi's `registerTool` call.
+     *
+     * Whether the installed pi SDK reads this field is the pi host's concern;
+     * bridgekit's contract is to pass it through unmodified when set.
+     */
+    promptSnippet?: string;
+    /**
+     * Longer-form guidance bullet points passed through to pi's `registerTool`
+     * call. Each entry is one bullet. Held by reference — treat as immutable
+     * once attached to a tool definition.
+     */
+    promptGuidelines?: readonly string[];
+}
+/**
+ * MCP-specific entries on `PortableTool.hostExtras`. Read only by the MCP
+ * adapter; the pi adapter ignores this namespace.
+ *
+ * @see PortableToolHostExtras
+ */
+export interface McpHostExtras {
+    /**
+     * MCP tool annotations attached to `tools/list` entries. Hints clients may
+     * surface to users; do not affect validation or execution.
+     *
+     * The annotations object is shallow-cloned at `createMcpServer`
+     * construction; post-construction mutation of the original object does
+     * not affect subsequent `tools/list` responses. Consumers do not need to
+     * defensively clone before passing.
+     *
+     * An empty annotations object (`{}`) is treated as semantically identical
+     * to omitting the field — the resulting `Tool` entry has no `annotations`
+     * key on the wire.
+     *
+     * @see https://modelcontextprotocol.io/specification (Tool annotations)
+     */
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+/**
+ * Opaque per-host metadata attached to a portable tool definition. Adapters
+ * read the keys they recognise and ignore the rest. Tools that omit
+ * `hostExtras` see no behavior change and pay no runtime cost — every adapter
+ * short-circuits on `tool.hostExtras?.<host>` being `undefined`.
+ *
+ * The shape is **module-augmentable** for custom hosts:
+ *
+ * ```ts
+ * declare module "@feniix/bridgekit" {
+ *   interface PortableToolHostExtras {
+ *     "custom-runtime"?: { something: string };
+ *   }
+ * }
+ * ```
+ *
+ * The augmentation must be in scope wherever a tool sets
+ * `hostExtras["custom-runtime"]`. bridgekit guarantees the type slot; the
+ * consumer is responsible for adapter dispatch.
+ */
+export interface PortableToolHostExtras {
+    pi?: PiHostExtras;
+    mcp?: McpHostExtras;
+}
 export interface PortableTool<TParams extends TSchema = TSchema, THost extends string = PortableToolBuiltInHost> {
     name: string;
     title: string;
     description: string;
     parameters: TParams;
     execute: (args: Static<TParams>, ctx: PortableToolContext<THost>) => PortableToolResult | Promise<PortableToolResult>;
+    /**
+     * Optional per-host metadata. Adapters consume the keys they recognise;
+     * unknown host namespaces are ignored. Absent → no behavior change.
+     *
+     * @see PortableToolHostExtras
+     * @see docs/rfc-host-extras.md for design rationale (admission criteria,
+     * why a top-level field beats a sidecar map, closure rules for future
+     * additions).
+     */
+    hostExtras?: PortableToolHostExtras;
 }
 export declare function definePortableTool<TParams extends TSchema, THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TParams, THost>): PortableTool<TParams, THost>;

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

@@ -15,6 +15,11 @@ function fieldFromPath(instancePath) {
  * property key, descending into the matched sub-schema — and returns the
  * actual leaf key. Array nodes consume a single numeric segment via `items`.
  *
+ * `allOf` nodes (TypeBox's `Intersect` lowering) probe each branch in turn
+ * with the same remaining path and return the first successful match. This
+ * is what lets `Type.Intersect([Object({"a/b": String()}), Object({c: ...})])`
+ * resolve a `/a/b` instancePath to the `"a/b"` key in the first branch.
+ *
  * Returns `undefined` if the walk gets stuck (the schema does not model the
  * data path — e.g. `additionalProperties` content). The caller then falls
  * back to the string-split `fieldFromPath`, preserving prior behavior.
@@ -29,52 +34,60 @@ function fieldFromSchemaWalk(schema, instancePath) {
     const segments = instancePath.split("/").filter(Boolean);
     if (segments.length === 0)
         return undefined;
-    let current = schema;
-    let lastKey;
-    let i = 0;
-    while (i < segments.length) {
-        if (!current || typeof current !== "object")
-            return undefined;
-        const node = current;
-        // Array descent: numeric segment against an `items` schema. Tuple-form
-        // `items` (array) indexes positionally; schema-form descends uniformly.
-        if (node.items !== undefined && /^\d+$/.test(segments[i])) {
-            const idx = Number(segments[i]);
-            if (Array.isArray(node.items)) {
-                if (idx >= node.items.length)
-                    return undefined;
-                current = node.items[idx];
-            }
-            else {
-                current = node.items;
-            }
-            lastKey = segments[i];
-            i++;
-            continue;
+    return walkSegments(schema, segments, 0);
+}
+function walkSegments(node, segments, i) {
+    if (i >= segments.length)
+        return undefined;
+    if (!node || typeof node !== "object")
+        return undefined;
+    const obj = node;
+    // Array descent: numeric segment against an `items` schema. Tuple-form
+    // `items` (array) indexes positionally; schema-form descends uniformly.
+    if (obj.items !== undefined && /^\d+$/.test(segments[i])) {
+        const idx = Number(segments[i]);
+        let next;
+        if (Array.isArray(obj.items)) {
+            if (idx >= obj.items.length)
+                return undefined;
+            next = obj.items[idx];
         }
-        // Object descent: greedy longest-prefix match against `properties` keys.
-        // This is what lets `a/b` resolve to a single key when the schema
-        // declares it, even though the instancePath segments it as ["a", "b"].
-        if (node.properties && typeof node.properties === "object") {
-            const props = node.properties;
-            let matched = -1;
-            for (let j = segments.length; j > i; j--) {
-                const candidate = segments.slice(i, j).join("/");
-                if (Object.hasOwn(props, candidate)) {
-                    matched = j;
-                    lastKey = candidate;
-                    current = props[candidate];
-                    break;
-                }
+        else {
+            next = obj.items;
+        }
+        if (i + 1 === segments.length)
+            return segments[i];
+        return walkSegments(next, segments, i + 1);
+    }
+    // Object descent: greedy longest-prefix match against `properties` keys.
+    // This is what lets `a/b` resolve to a single key when the schema
+    // declares it, even though the instancePath segments it as ["a", "b"].
+    if (obj.properties && typeof obj.properties === "object") {
+        const props = obj.properties;
+        for (let j = segments.length; j > i; j--) {
+            const candidate = segments.slice(i, j).join("/");
+            if (Object.hasOwn(props, candidate)) {
+                if (j === segments.length)
+                    return candidate;
+                const child = walkSegments(props[candidate], segments, j);
+                if (child !== undefined)
+                    return child;
             }
-            if (matched === -1)
-                return undefined;
-            i = matched;
-            continue;
         }
         return undefined;
     }
-    return lastKey;
+    // allOf descent: TypeBox's Intersect lowering. Each branch sees the full
+    // remaining path; return the first branch that resolves. This is the
+    // schema-side mirror of how Intersect merges property contributions.
+    if (Array.isArray(obj.allOf)) {
+        for (const branch of obj.allOf) {
+            const matched = walkSegments(branch, segments, i);
+            if (matched !== undefined)
+                return matched;
+        }
+        return undefined;
+    }
+    return undefined;
 }
 function fieldFromError(schema, error) {
     return fieldFromSchemaWalk(schema, error.instancePath) ?? fieldFromPath(error.instancePath);

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
-export { definePortableTool, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolErrorDetails, type PortableToolHost, type PortableToolResult, type PortableValidationError, } from "./core/define-tool.js";
+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 { executePortableTool, validatePortableToolArgs } from "./core/execute-tool.js";
 export { isDomainFailure, isValidationFailure, type PortableDomainFailure, type PortableValidationFailure, } from "./core/result-guards.js";

package/examples/README.md

@@ -81,6 +81,42 @@ Best practices shown here:
 - The `createTools()` factory gives stateful tools a fresh runtime per host instance; stateless packages may still return the same definitions.
 - The file has no import-time registration or server startup.
 
+### Composing object schemas with `Type.Intersect`
+
+When two object schemas describe different facets of the same input — common
+properties plus a feature-specific extension — compose them with
+`Type.Intersect`. Both branches must be `Type.Object(...)`; the MCP adapter
+synthesises `type: "object"` on the wire so existing MCP SDK clients accept
+the composed schema unchanged. Other top-level shapes (`Type.Union(...)`,
+`Type.String()`) throw at `createMcpServer` construction.
+
+```ts
+import { type Static, Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
+
+const idParams = Type.Object({ id: Type.String({ description: "Record id." }) });
+const updateParams = Type.Object({
+  name: Type.Optional(Type.String({ description: "New display name." })),
+  archived: Type.Optional(Type.Boolean({ description: "Archive flag." })),
+});
+
+const params = Type.Intersect([idParams, updateParams]);
+type Params = Static<typeof params>; // { id: string; name?: string; archived?: boolean }
+
+export const updateRecordTool = definePortableTool({
+  name: "update_record",
+  title: "Update Record",
+  description: "Update a record by id.",
+  parameters: params,
+  execute(args: Params) {
+    return {
+      text: `Updated ${args.id}`,
+      structuredContent: { id: args.id, name: args.name, archived: args.archived },
+    };
+  },
+});
+```
+
 ---
 
 ## 2. Register tools in a pi extension
@@ -293,7 +329,124 @@ Use `PortableToolHost<CustomHost>` for values that can be either a built-in host
 
 ---
 
-## 5. Package checklist
+## 5. 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.
+
+```ts
+import { Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
+
+export const summariseTool = definePortableTool({
+  name: "summarise",
+  title: "Summarise",
+  description: "Generate a short summary of a block of text.",
+  parameters: Type.Object({ text: Type.String() }),
+  execute(args) {
+    return { text: args.text.slice(0, 80) };
+  },
+  hostExtras: {
+    pi: {
+      // Fires once before TypeBox validation runs — surfaces a "Processing..."
+      // signal to the pi host without a custom registration wrapper.
+      pendingMessage: "Summarising...",
+      promptSnippet: "Use this tool when the user asks for a short summary.",
+      promptGuidelines: ["Prefer < 80 chars.", "Strip markdown."],
+    },
+    mcp: {
+      // Advisory hints clients may surface. Do not affect validation or
+      // execution; round-trip verbatim on `tools/list` entries.
+      annotations: { readOnlyHint: true },
+    },
+  },
+});
+```
+
+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.
+
+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).
+
+### Migrating from a custom registration loop
+
+Before `hostExtras`, packages that needed pi-specific per-tool metadata
+typically kept a sidecar map plus a custom `toPiTool` wrapper that bypassed
+`registerPiTools`. The before-shape drifts out of sync the first time a tool
+is added without its sidecar entry; the after-shape co-locates the metadata
+with the tool, removes the wrapper, and uses the canonical adapter directly.
+
+**Before** — sidecar `PENDING_MESSAGES` plus a custom registration loop:
+
+```ts
+// extensions/index.ts (before)
+import { executePortableTool } from "@feniix/bridgekit";
+import { createTools } from "./tools.js";
+
+const PENDING_MESSAGES: Record<string, string> = {
+  generate_summary: "Generating summary...",
+  rewrite_paragraph: "Rewriting...",
+};
+
+export default function extension(pi: { registerTool: (tool: unknown) => void }) {
+  for (const tool of createTools()) {
+    pi.registerTool({
+      name: tool.name,
+      label: tool.title,
+      description: tool.description,
+      parameters: tool.parameters,
+      async execute(_id: string, params: unknown, signal: AbortSignal, onUpdate?: (u: unknown) => void) {
+        onUpdate?.({
+          content: [{ type: "text", text: PENDING_MESSAGES[tool.name] ?? "" }],
+          details: { status: "pending" },
+        });
+        const result = await executePortableTool(tool, params, { host: "pi", signal });
+        return { content: [{ type: "text", text: result.text }], details: result.structuredContent ?? {} };
+      },
+    });
+  }
+}
+```
+
+**After** — `pendingMessage` carried on each tool, `registerPiTools` used directly:
+
+```ts
+// extensions/tools.ts (after — each tool declares its own pending message)
+import { Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
+
+export const generateSummaryTool = definePortableTool({
+  name: "generate_summary",
+  title: "Generate Summary",
+  description: "Summarise a block of text.",
+  parameters: Type.Object({ text: Type.String() }),
+  execute(args) {
+    return { text: args.text.slice(0, 80) };
+  },
+  hostExtras: {
+    pi: { pendingMessage: "Generating summary..." },
+  },
+});
+
+// extensions/index.ts (after — sidecar map deleted, custom loop deleted)
+import { registerPiTools } from "@feniix/bridgekit/pi";
+import { createTools } from "./tools.js";
+
+export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
+  registerPiTools(pi, createTools());
+}
+```
+
+The sidecar map deletes entirely, the per-tool wrapper deletes, and the
+remaining wiring is the same three-line shape every other consumer uses.
+See `docs/rfc-host-extras.md` §5 for the canonical motivation and the
+per-consumer migration deltas.
+
+---
+
+## 6. Package checklist
 
 For publishable tool packages:
 

package/llms.txt

@@ -55,7 +55,7 @@ export function createTools() {
 ## Best practices
 
 - Keep portable tools host-neutral. Do not import pi or MCP SDKs from files that define tool behavior.
-- Use TypeBox `Type.Object(...)` schemas for MCP-compatible tools.
+- 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.
 - 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.
@@ -76,6 +76,7 @@ export function createTools() {
 - 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`.
 - `registerPiTools(pi, tools, { errorHandling: "throw" })` opts into the pre-0.7 behavior where `isError` results throw `PortableToolExecutionError`. Selecting this value emits a `DeprecationWarning` (code `BRIDGEKIT_PI_THROW_DEPRECATED`) once per process; only the `"throw"` value is deprecated, not the option itself. Scheduled for removal in 1.0; do not adopt it for new code.
+- `PortableTool.hostExtras` (0.9+) carries optional per-host metadata in namespaced sub-objects (`pi`, `mcp`, plus module-augmentable custom hosts). Each field is optional and zero-cost when absent — a tool without `hostExtras` produces byte-identical pi registration and MCP `tools/list` payloads to 0.8.x. `hostExtras.pi.pendingMessage` fires `onUpdate({ content, details: { status: "pending" } })` exactly once before TypeBox validation; `hostExtras.pi.promptSnippet` / `promptGuidelines` pass through verbatim to pi's `registerTool` call; `hostExtras.mcp.annotations` (`title` / `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`) attaches MCP advisory hints. Tool definitions stay host-neutral — host-specific metadata lives in its namespace, not on the tool's top-level fields.
 
 ### Result-guard usage
 

package/package.json

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