mcpose 2.1.1 → 3.1.0

package/dist/index.d.ts

@@ -1,14 +1,23 @@
 export type { Middleware } from './middleware.js';
-export { compose } from './middleware.js';
+export { compose, markPassThroughObserver } from './middleware.js';
 export type { BackendConfig, BackendClient } from './backendClient.js';
 export { createBackendClient } from './backendClient.js';
 export type { Identity } from './identity.js';
-export type { ProxyContext } from './proxyContext.js';
-export { createProxyContext } from './proxyContext.js';
-export type { TelemetryEvent } from './telemetry.js';
+export type { ProxyContext, ProxyIdentity, PolicyDecision, } from './proxyContext.js';
+export { createProxyContext, outboundDelegationChain } from './proxyContext.js';
+export type { TelemetryEvent, ToolCallTelemetryEvent, BackendDegradedTelemetryEvent, } from './telemetry.js';
+export type { Backends } from './mesh.js';
 export type { PersistentEventStore } from './eventStore.js';
 export { createInMemoryEventStore } from './eventStore.js';
+export type { SessionRecord, SessionRegistry } from './sessionRegistry.js';
+export type { DelegationWireEntry, DelegationWirePayload, } from './delegation.js';
+export { DELEGATION_META_KEY, serializeDelegationChain } from './delegation.js';
 export type { RejectionReason } from './rejection.js';
-export type { ProxyOptions, HttpProxyOptions, ToolMiddleware, ResourceMiddleware, ListToolsMiddleware, } from './core.js';
-export { hasToolContent, createProxyServer, startProxy, startHttpProxy } from './core.js';
+export { rejectionMcpError } from './rejection.js';
+export type { HiddenToolPredicate, DispatcherAwareBlockOptions, } from './hiddenTools.js';
+export { dispatcherAwareBlock } from './hiddenTools.js';
+export type { SanitizeToolDescriptionsOptions } from './sanitizeCatalog.js';
+export { sanitizeToolDescriptions } from './sanitizeCatalog.js';
+export type { ProxyOptions, HttpProxyOptions, LocalTool, ToolMiddleware, ResourceMiddleware, PromptMiddleware, ListToolsMiddleware, ToolResultHandlers, } from './core.js';
+export { hasToolContent, mapToolResult, createProxyServer, startProxy, startHttpProxy, } from './core.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEnE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,YAAY,EACV,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEhF,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE3E,YAAY,EACV,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhF,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EACV,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,YAAY,EAAE,+BAA+B,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,cAAc,GACf,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,6 +1,10 @@
-export { compose } from './middleware.js';
+export { compose, markPassThroughObserver } from './middleware.js';
 export { createBackendClient } from './backendClient.js';
-export { createProxyContext } from './proxyContext.js';
+export { createProxyContext, outboundDelegationChain } from './proxyContext.js';
 export { createInMemoryEventStore } from './eventStore.js';
-export { hasToolContent, createProxyServer, startProxy, startHttpProxy } from './core.js';
+export { DELEGATION_META_KEY, serializeDelegationChain } from './delegation.js';
+export { rejectionMcpError } from './rejection.js';
+export { dispatcherAwareBlock } from './hiddenTools.js';
+export { sanitizeToolDescriptions } from './sanitizeCatalog.js';
+export { hasToolContent, mapToolResult, createProxyServer, startProxy, startHttpProxy, } from './core.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAKzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAKvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAW3D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AASzD,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAWhF,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAQ3D,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAGhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAMnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAYhE,OAAO,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,cAAc,GACf,MAAM,WAAW,CAAC"}

package/dist/mesh.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Multi-backend (mesh) composition: backend-key validation, namespacing,
+ * routing, and failure-isolated listing. See ADR-0013.
+ */
+import type { BackendClient } from './backendClient.js';
+/** One named upstream of a mesh. */
+export interface MeshEntry {
+    readonly key: string;
+    readonly client: BackendClient;
+}
+/**
+ * Either a single upstream (1:1 proxy, no namespacing) or a record of named
+ * backends keyed by backend key (mesh mode). See ADR-0013.
+ */
+export type Backends = BackendClient | Readonly<Record<string, BackendClient>>;
+/**
+ * Normalizes the `backends` argument to an ordered entry list. The 1:1 form
+ * yields a single entry with an empty key and `mesh: false`.
+ *
+ * @throws On an empty record, an empty backend key, or a key containing the
+ * namespace separator — each would make an exposed name ambiguous, and
+ * guessing which upstream a caller meant is the failure mesh routing exists
+ * to prevent.
+ */
+export declare function normalizeBackends(backends: Backends): {
+    mesh: boolean;
+    entries: ReadonlyArray<MeshEntry>;
+};
+/** Namespaces a listed tool or prompt as `<key>__<name>`. */
+export declare function namespaceName<Item extends {
+    name: string;
+}>(key: string, item: Item): Item;
+/**
+ * Exposes a listed resource as `mcpose://<key>/<uri>`. The upstream URI is
+ * appended untouched, so what the client holds is still one valid URI whose
+ * only meaning is "read me through this proxy", exactly as opaque as before.
+ */
+export declare function namespaceUri<Item extends {
+    uri: string;
+}>(key: string, item: Item): Item;
+/**
+ * Resolves an exposed resource URI to its backend and upstream URI.
+ *
+ * Returns `undefined` for a URI not under `mcpose://`, an unknown key, or an
+ * empty upstream URI, and the caller rejects it as `BACKEND_UNROUTABLE`:
+ * there is no "which backend listed this URI" lookup, for the same reason
+ * tool names get no single-backend fallback.
+ */
+export declare function routeResourceUri(uri: string, byKey: ReadonlyMap<string, BackendClient>): {
+    client: BackendClient;
+    uri: string;
+} | undefined;
+/**
+ * Resolves an exposed name to its backend and upstream name.
+ *
+ * Returns `undefined` for an un-namespaced name, an unknown key, or an empty
+ * upstream name. The caller turns that into a loud `BACKEND_UNROUTABLE`
+ * rejection: there is deliberately no "resolve it if only one backend has
+ * that name" fallback, because it silently re-routes once a backend is added.
+ */
+export declare function routeNamespaced(name: string, byKey: ReadonlyMap<string, BackendClient>): {
+    client: BackendClient;
+    name: string;
+} | undefined;
+/** One page of a paginated list surface. */
+export interface MeshPage<Item> {
+    items: ReadonlyArray<Item>;
+    nextCursor: string | undefined;
+}
+/**
+ * Lists one paginated surface across every backend concurrently, exposing
+ * each entry under its backend key via `expose` and isolating failures: a
+ * backend that throws (or never finishes paginating) contributes nothing and
+ * is reported through `onDegraded`, while the live backends' entries are
+ * still returned.
+ *
+ * Entries keep backend declaration order. A backend that fails part-way
+ * through pagination contributes nothing at all rather than a truncated
+ * list, so the response never looks complete when it is not.
+ */
+export declare function listAcrossMesh<Item>(entries: ReadonlyArray<MeshEntry>, listPage: (client: BackendClient, cursor: string | undefined) => Promise<MeshPage<Item>>, onDegraded: (key: string, error: unknown) => void, expose: (key: string, item: Item) => Item): Promise<Item[]>;
+//# sourceMappingURL=mesh.d.ts.map

package/dist/mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.d.ts","sourceRoot":"","sources":["../src/mesh.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA6BxD,oCAAoC;AACpC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAK/E;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACnC,CAgCA;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,IAAI,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACzD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,GACT,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EACvD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,GACT,IAAI,CAEN;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,GACxC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CASpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,GACxC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOrD;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ,CAAC,IAAI;IAC5B,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,IAAI,EACvC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,EACjC,QAAQ,EAAE,CACR,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GAAG,SAAS,KACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAC5B,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,EACjD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,GACxC,OAAO,CAAC,IAAI,EAAE,CAAC,CAsBjB"}

package/dist/mesh.js

@@ -0,0 +1,141 @@
+/**
+ * Separates a backend key from the upstream name in mesh mode:
+ * `<backendKey>__<name>`. A key may not contain it, so the first occurrence
+ * always splits the two, even when the upstream name contains one itself.
+ */
+const BACKEND_NAMESPACE_SEPARATOR = '__';
+/**
+ * A backend key is an identifier: it is spliced into tool and prompt names
+ * and, for resources, into the authority of a `mcpose://<key>/<uri>` URI
+ * (ADR-0022), so it is limited to what both a name and a URI host accept.
+ */
+const BACKEND_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * The scheme a mesh exposes upstream resources under. The key is the
+ * authority and the upstream URI follows verbatim as the path, so the
+ * original is recovered by stripping a fixed prefix and never parsed.
+ */
+const RESOURCE_SCHEME = 'mcpose://';
+/**
+ * Pages drained from one backend before the proxy gives up on it. A backend
+ * that never advances its cursor would otherwise hang the whole list.
+ */
+const MAX_PAGES_PER_BACKEND = 100;
+const isBackendClient = (backends) => typeof backends.getServerCapabilities === 'function';
+/**
+ * Normalizes the `backends` argument to an ordered entry list. The 1:1 form
+ * yields a single entry with an empty key and `mesh: false`.
+ *
+ * @throws On an empty record, an empty backend key, or a key containing the
+ * namespace separator — each would make an exposed name ambiguous, and
+ * guessing which upstream a caller meant is the failure mesh routing exists
+ * to prevent.
+ */
+export function normalizeBackends(backends) {
+    if (isBackendClient(backends)) {
+        return { mesh: false, entries: [{ key: '', client: backends }] };
+    }
+    const entries = Object.entries(backends).map(([key, client]) => ({
+        key,
+        client,
+    }));
+    if (entries.length === 0) {
+        throw new Error('mcpose: backends record is empty — pass at least one named backend, or a single BackendClient for a 1:1 proxy.');
+    }
+    for (const { key } of entries) {
+        if (key === '') {
+            throw new Error('mcpose: backend key must not be empty');
+        }
+        if (key.includes(BACKEND_NAMESPACE_SEPARATOR)) {
+            throw new Error(`mcpose: backend key "${key}" must not contain "${BACKEND_NAMESPACE_SEPARATOR}" — it is the namespace separator`);
+        }
+        if (!BACKEND_KEY.test(key)) {
+            throw new Error(`mcpose: backend key "${key}" must be an identifier (letters, digits, ".", "_" and "-", starting with a letter or digit) — it names the backend inside tool names and resource URIs`);
+        }
+    }
+    return { mesh: true, entries };
+}
+/** Namespaces a listed tool or prompt as `<key>__<name>`. */
+export function namespaceName(key, item) {
+    return { ...item, name: `${key}${BACKEND_NAMESPACE_SEPARATOR}${item.name}` };
+}
+/**
+ * Exposes a listed resource as `mcpose://<key>/<uri>`. The upstream URI is
+ * appended untouched, so what the client holds is still one valid URI whose
+ * only meaning is "read me through this proxy", exactly as opaque as before.
+ */
+export function namespaceUri(key, item) {
+    return { ...item, uri: `${RESOURCE_SCHEME}${key}/${item.uri}` };
+}
+/**
+ * Resolves an exposed resource URI to its backend and upstream URI.
+ *
+ * Returns `undefined` for a URI not under `mcpose://`, an unknown key, or an
+ * empty upstream URI, and the caller rejects it as `BACKEND_UNROUTABLE`:
+ * there is no "which backend listed this URI" lookup, for the same reason
+ * tool names get no single-backend fallback.
+ */
+export function routeResourceUri(uri, byKey) {
+    if (!uri.startsWith(RESOURCE_SCHEME))
+        return undefined;
+    const rest = uri.slice(RESOURCE_SCHEME.length);
+    const slash = rest.indexOf('/');
+    if (slash <= 0)
+        return undefined;
+    const client = byKey.get(rest.slice(0, slash));
+    const upstreamUri = rest.slice(slash + 1);
+    if (client === undefined || upstreamUri === '')
+        return undefined;
+    return { client, uri: upstreamUri };
+}
+/**
+ * Resolves an exposed name to its backend and upstream name.
+ *
+ * Returns `undefined` for an un-namespaced name, an unknown key, or an empty
+ * upstream name. The caller turns that into a loud `BACKEND_UNROUTABLE`
+ * rejection: there is deliberately no "resolve it if only one backend has
+ * that name" fallback, because it silently re-routes once a backend is added.
+ */
+export function routeNamespaced(name, byKey) {
+    const at = name.indexOf(BACKEND_NAMESPACE_SEPARATOR);
+    if (at <= 0)
+        return undefined;
+    const client = byKey.get(name.slice(0, at));
+    const upstreamName = name.slice(at + BACKEND_NAMESPACE_SEPARATOR.length);
+    if (client === undefined || upstreamName === '')
+        return undefined;
+    return { client, name: upstreamName };
+}
+/**
+ * Lists one paginated surface across every backend concurrently, exposing
+ * each entry under its backend key via `expose` and isolating failures: a
+ * backend that throws (or never finishes paginating) contributes nothing and
+ * is reported through `onDegraded`, while the live backends' entries are
+ * still returned.
+ *
+ * Entries keep backend declaration order. A backend that fails part-way
+ * through pagination contributes nothing at all rather than a truncated
+ * list, so the response never looks complete when it is not.
+ */
+export async function listAcrossMesh(entries, listPage, onDegraded, expose) {
+    const settled = await Promise.allSettled(entries.map(async ({ key, client }) => {
+        const collected = [];
+        let cursor;
+        for (let page = 0; page < MAX_PAGES_PER_BACKEND; page += 1) {
+            const { items, nextCursor } = await listPage(client, cursor);
+            for (const item of items)
+                collected.push(expose(key, item));
+            if (nextCursor === undefined)
+                return collected;
+            cursor = nextCursor;
+        }
+        throw new Error(`mcpose: backend "${key}" did not finish paginating within ${MAX_PAGES_PER_BACKEND} pages`);
+    }));
+    return settled.flatMap((outcome, index) => {
+        if (outcome.status === 'fulfilled')
+            return outcome.value;
+        onDegraded(entries[index].key, outcome.reason);
+        return [];
+    });
+}
+//# sourceMappingURL=mesh.js.map

package/dist/mesh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.js","sourceRoot":"","sources":["../src/mesh.ts"],"names":[],"mappings":"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"}

package/dist/middleware.d.ts

@@ -32,5 +32,18 @@ export declare function compose<Req, Res>(middlewares: ReadonlyArray<Middleware<
  * Used internally by mcpose core — consumers pass arrays to `ProxyOptions`.
  */
 export declare function pipe<Req, Res>(middlewares: ReadonlyArray<Middleware<Req, Res>>): MiddlewarePipeline<Req, Res>;
+/**
+ * Marks a middleware as a pass-through observer: it still runs for tools
+ * listed in `ProxyOptions.passThroughTools`, which skip all other middleware.
+ *
+ * Use for middleware that must see every call regardless of pass-through
+ * status — audit logging, telemetry — never for middleware that transforms
+ * requests or responses (pass-through means "forward upstream as-is").
+ *
+ * Returns a new middleware; the input is not mutated.
+ */
+export declare function markPassThroughObserver<Req, Res>(mw: Middleware<Req, Res>): Middleware<Req, Res>;
+/** True when the middleware was wrapped by {@link markPassThroughObserver}. */
+export declare function isPassThroughObserver(mw: unknown): boolean;
 export {};
 //# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1E,4EAA4E;AAC5E,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,GAAG,IAAI,CACjC,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,EAChC,OAAO,EAAE,YAAY,KAClB,OAAO,CAAC,GAAG,CAAC,CAAC;AAElB,KAAK,kBAAkB,CAAC,GAAG,EAAE,GAAG,IAAI;IAClC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3D,CACE,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,EAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,GAAG,CAAC,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAC9B,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAC/C,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAkB9B;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,GAAG,EAC3B,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAC/C,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAE9B"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1E,4EAA4E;AAC5E,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,GAAG,IAAI,CACjC,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,EAChC,OAAO,EAAE,YAAY,KAClB,OAAO,CAAC,GAAG,CAAC,CAAC;AAElB,KAAK,kBAAkB,CAAC,GAAG,EAAE,GAAG,IAAI;IAClC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3D,CACE,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,EAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,GAAG,CAAC,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAC9B,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAC/C,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAoB9B;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,GAAG,EAC3B,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAC/C,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAE9B;AAID;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,GAAG,EAC9C,EAAE,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,GACvB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAQtB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAE1D"}

package/dist/middleware.js

@@ -20,18 +20,19 @@ import { createProxyContext } from './proxyContext.js';
  * const result = await pipeline(req, (r) => upstream.callTool(r.params));
  */
 export function compose(middlewares) {
-    return ((req, next, context = createProxyContext()) => {
+    return (req, next, context = createProxyContext()) => {
         let index = -1;
         const dispatch = (i, currentReq) => {
             if (i <= index) {
                 return Promise.reject(new Error('next() called multiple times'));
             }
             index = i;
-            const fn = i < middlewares.length ? middlewares[i] : (_r, n) => next(_r);
+            // Past the end of the pipeline, the terminal handler runs.
+            const fn = middlewares[i] ?? ((r) => next(r));
             return Promise.resolve(fn(currentReq, (r) => dispatch(i + 1, r), context));
         };
         return dispatch(0, req);
-    });
+    };
 }
 /**
  * Like `compose` but in response-processing order (first = innermost).
@@ -41,4 +42,27 @@ export function compose(middlewares) {
 export function pipe(middlewares) {
     return compose([...middlewares].reverse());
 }
+const PASS_THROUGH_OBSERVER = Symbol.for('mcpose.passThroughObserver');
+/**
+ * Marks a middleware as a pass-through observer: it still runs for tools
+ * listed in `ProxyOptions.passThroughTools`, which skip all other middleware.
+ *
+ * Use for middleware that must see every call regardless of pass-through
+ * status — audit logging, telemetry — never for middleware that transforms
+ * requests or responses (pass-through means "forward upstream as-is").
+ *
+ * Returns a new middleware; the input is not mutated.
+ */
+export function markPassThroughObserver(mw) {
+    const marked = (req, next, context) => mw(req, next, context);
+    Object.defineProperty(marked, PASS_THROUGH_OBSERVER, {
+        value: true,
+        enumerable: false,
+    });
+    return marked;
+}
+/** True when the middleware was wrapped by {@link markPassThroughObserver}. */
+export function isPassThroughObserver(mw) {
+    return typeof mw === 'function' && PASS_THROUGH_OBSERVER in mw;
+}
 //# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,kBAAkB,EAAqB,MAAM,mBAAmB,CAAC;AAkB1E;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CACrB,WAAgD;IAEhD,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,UAAwB,kBAAkB,EAAE,EAAE,EAAE;QAClE,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;QAEf,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,UAAe,EAAgB,EAAE;YAC5D,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;gBACf,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,CAAC;YACnE,CAAC;YACD,KAAK,GAAG,CAAC,CAAC;YAEV,MAAM,EAAE,GACN,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAEjE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7E,CAAC,CAAC;QAEF,OAAO,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAiC,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAClB,WAAgD;IAEhD,OAAO,OAAO,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,kBAAkB,EAAqB,MAAM,mBAAmB,CAAC;AAkB1E;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CACrB,WAAgD;IAEhD,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,UAAwB,kBAAkB,EAAE,EAAE,EAAE;QACjE,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;QAEf,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,UAAe,EAAgB,EAAE;YAC5D,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;gBACf,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,CAAC;YACnE,CAAC;YACD,KAAK,GAAG,CAAC,CAAC;YAEV,2DAA2D;YAC3D,MAAM,EAAE,GAAyB,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAEpE,OAAO,OAAO,CAAC,OAAO,CACpB,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CACnD,CAAC;QACJ,CAAC,CAAC;QAEF,OAAO,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAClB,WAAgD;IAEhD,OAAO,OAAO,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,EAAwB;IAExB,MAAM,MAAM,GAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAC1D,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACzB,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,qBAAqB,EAAE;QACnD,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,KAAK;KAClB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,qBAAqB,CAAC,EAAW;IAC/C,OAAO,OAAO,EAAE,KAAK,UAAU,IAAI,qBAAqB,IAAI,EAAE,CAAC;AACjE,CAAC"}

package/dist/proxyContext.d.ts

@@ -1,4 +1,27 @@
 import type { Identity } from './identity.js';
+/**
+ * The proxy instance a request passed through, as resolved from
+ * `ProxyOptions.name`/`version` (defaults included). Provenance, not a
+ * principal: it is never an entry in `delegatedFrom` and takes no part in
+ * the caller-attribution model (ADR-0011, ADR-0012).
+ */
+export interface ProxyIdentity {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * A policy decision already made, stamped on the context by the policy
+ * middleware (ADR-0017). It is a record, not a handle to query: core never
+ * evaluates policy itself, and a second evaluation path would let inner
+ * middleware ask a different question than the gate answered.
+ *
+ * `reason` carries the `RejectionReason` that accompanied a denial.
+ */
+export interface PolicyDecision {
+    readonly decision: 'allow' | 'deny';
+    readonly ruleId?: string;
+    readonly reason?: string;
+}
 /** Normalized request metadata that mcpose passes through middleware layers. */
 export interface ProxyContext {
     requestId: string;
@@ -8,11 +31,48 @@ export interface ProxyContext {
     signal?: AbortSignal;
     /** Resolved caller identity. Present when {@link HttpProxyOptions.resolveIdentity} is configured. */
     identity?: Identity;
-    /** Agent delegation chain — populated when an upstream A2A agent delegates through mcpose. */
+    /**
+     * Agent delegation chain, oldest-first. Populated from the inbound
+     * request's `_meta["mcpose/delegation"]` when a caller presents one
+     * (ADR-0016), or by a host that stamps its own, which wins.
+     *
+     * Attribution, never authorization: every entry extracted from the wire
+     * carries empty `roles` and `claims`, because a presented chain is written
+     * by the previous hop.
+     */
     delegatedFrom?: Identity[];
-    /** @stable Reserved for v3 policy engine. */
-    policy?: never;
+    /** The proxy instance handling this request. Stamped by {@link createProxyServer}. */
+    proxy?: ProxyIdentity;
+    /**
+     * The policy decision for this call. Stamped by the `@mcpose/policy`
+     * middleware before it calls `next` (allow) or throws (deny), so
+     * middleware running inside the policy layer can rely on
+     * `decision: 'allow'` (ADR-0017). Core never writes it.
+     */
+    policy?: PolicyDecision;
 }
-/** Creates a middleware context with a fresh request ID. */
-export declare function createProxyContext(overrides?: Partial<ProxyContext>): ProxyContext;
+/**
+ * Canonical oldest-first delegation chain a host attaches to outbound calls
+ * made on behalf of the inbound caller (ADR-0011). Returns a fresh array and
+ * never mutates or aliases `ctx.delegatedFrom`, because the audit middleware
+ * reads the same context object when recording the inbound call.
+ *
+ * Core attaches this chain itself to every call it forwards to a backend, at
+ * `params._meta["mcpose/delegation"]` (ADR-0016). A local tool handler makes
+ * its own outbound calls, so its host attaches the chain: for an outbound MCP
+ * call, `serializeDelegationChain(outboundDelegationChain(context))` under
+ * `DELEGATION_META_KEY` produces exactly what core sends.
+ */
+export declare function outboundDelegationChain(ctx: ProxyContext): Identity[];
+/**
+ * Creates a middleware context with a fresh request ID.
+ *
+ * Every override may be passed explicitly as `undefined` — it means "not
+ * provided" and the key is dropped from the result, which is why the
+ * parameter is not a plain `Partial<ProxyContext>` under
+ * `exactOptionalPropertyTypes`.
+ */
+export declare function createProxyContext(overrides?: {
+    [K in keyof ProxyContext]?: ProxyContext[K] | undefined;
+}): ProxyContext;
 //# sourceMappingURL=proxyContext.d.ts.map

package/dist/proxyContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxyContext.d.ts","sourceRoot":"","sources":["../src/proxyContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qGAAqG;IACrG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,8FAA8F;IAC9F,aAAa,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC3B,6CAA6C;IAC7C,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAChC,SAAS,GAAE,OAAO,CAAC,YAAY,CAAM,GACpC,YAAY,CAUd"}
+{"version":3,"file":"proxyContext.d.ts","sourceRoot":"","sources":["../src/proxyContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qGAAqG;IACrG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC3B,sFAAsF;IACtF,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,GAAG,QAAQ,EAAE,CAKrE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,GAAE;KAAG,CAAC,IAAI,MAAM,YAAY,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;CAAO,GAC1E,YAAY,CAoBd"}

package/dist/proxyContext.js

@@ -1,14 +1,49 @@
 import { randomUUID } from 'node:crypto';
-/** Creates a middleware context with a fresh request ID. */
+/**
+ * Canonical oldest-first delegation chain a host attaches to outbound calls
+ * made on behalf of the inbound caller (ADR-0011). Returns a fresh array and
+ * never mutates or aliases `ctx.delegatedFrom`, because the audit middleware
+ * reads the same context object when recording the inbound call.
+ *
+ * Core attaches this chain itself to every call it forwards to a backend, at
+ * `params._meta["mcpose/delegation"]` (ADR-0016). A local tool handler makes
+ * its own outbound calls, so its host attaches the chain: for an outbound MCP
+ * call, `serializeDelegationChain(outboundDelegationChain(context))` under
+ * `DELEGATION_META_KEY` produces exactly what core sends.
+ */
+export function outboundDelegationChain(ctx) {
+    return [
+        ...(ctx.delegatedFrom ?? []),
+        ...(ctx.identity === undefined ? [] : [ctx.identity]),
+    ];
+}
+/**
+ * Creates a middleware context with a fresh request ID.
+ *
+ * Every override may be passed explicitly as `undefined` — it means "not
+ * provided" and the key is dropped from the result, which is why the
+ * parameter is not a plain `Partial<ProxyContext>` under
+ * `exactOptionalPropertyTypes`.
+ */
 export function createProxyContext(overrides = {}) {
     return {
+        // Deliberately `||`, not `??`: an empty-string requestId is useless for
+        // correlation, so it is regenerated like a missing one.
         requestId: overrides.requestId || randomUUID(),
         transport: overrides.transport ?? 'stdio',
-        ...(overrides.sessionId === undefined ? {} : { sessionId: overrides.sessionId }),
+        ...(overrides.sessionId === undefined
+            ? {}
+            : { sessionId: overrides.sessionId }),
         ...(overrides.headers === undefined ? {} : { headers: overrides.headers }),
         ...(overrides.signal === undefined ? {} : { signal: overrides.signal }),
-        ...(overrides.identity === undefined ? {} : { identity: overrides.identity }),
-        ...(overrides.delegatedFrom === undefined ? {} : { delegatedFrom: overrides.delegatedFrom }),
+        ...(overrides.identity === undefined
+            ? {}
+            : { identity: overrides.identity }),
+        ...(overrides.delegatedFrom === undefined
+            ? {}
+            : { delegatedFrom: overrides.delegatedFrom }),
+        ...(overrides.proxy === undefined ? {} : { proxy: overrides.proxy }),
+        ...(overrides.policy === undefined ? {} : { policy: overrides.policy }),
     };
 }
 //# sourceMappingURL=proxyContext.js.map

package/dist/proxyContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"proxyContext.js","sourceRoot":"","sources":["../src/proxyContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkBzC,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB,CAChC,YAAmC,EAAE;IAErC,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,UAAU,EAAE;QAC9C,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,OAAO;QACzC,GAAG,CAAC,SAAS,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;QAChF,GAAG,CAAC,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;QAC1E,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;QACvE,GAAG,CAAC,SAAS,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC7E,GAAG,CAAC,SAAS,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,CAAC;KAC7F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"proxyContext.js","sourceRoot":"","sources":["../src/proxyContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA0DzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAiB;IACvD,OAAO;QACL,GAAG,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;QAC5B,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;KACtD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAAyE,EAAE;IAE3E,OAAO;QACL,wEAAwE;QACxE,wDAAwD;QACxD,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,UAAU,EAAE;QAC9C,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,OAAO;QACzC,GAAG,CAAC,SAAS,CAAC,SAAS,KAAK,SAAS;YACnC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;QACvC,GAAG,CAAC,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;QAC1E,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;QACvE,GAAG,CAAC,SAAS,CAAC,QAAQ,KAAK,SAAS;YAClC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC;QACrC,GAAG,CAAC,SAAS,CAAC,aAAa,KAAK,SAAS;YACvC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,CAAC;QAC/C,GAAG,CAAC,SAAS,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;QACpE,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC"}

package/dist/rejection.d.ts

@@ -9,7 +9,13 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
  *
  * @stable
  */
-export type RejectionReason = 'TOOL_HIDDEN' | 'RESOURCE_HIDDEN' | 'POLICY_DENIED' | 'IDENTITY_UNRESOLVED' | 'CONSENT_MISSING' | 'SENSITIVITY_BLOCKED' | 'DELEGATION_INVALID' | 'BUDGET_EXCEEDED' | 'SESSION_LIMIT' | 'BODY_LIMIT';
+export type RejectionReason = 'TOOL_HIDDEN' | 'RESOURCE_HIDDEN' | 'BACKEND_UNROUTABLE' | 'POLICY_DENIED' | 'IDENTITY_UNRESOLVED' | 'CONSENT_MISSING' | 'SENSITIVITY_BLOCKED' | 'DELEGATION_INVALID' | 'BUDGET_EXCEEDED' | 'SESSION_LIMIT' | 'BODY_LIMIT';
+/**
+ * Narrows an untrusted value to `RejectionReason`.
+ * `Object.hasOwn`, not `in`: the value can come from an upstream error, so a
+ * prototype key like `constructor` must not pass as a member.
+ */
+export declare function isRejectionReason(value: unknown): value is RejectionReason;
 /**
  * Creates an `McpError` with the rejection reason embedded in `error.data`.
  * The top-level `code` is unchanged so clients that only inspect the code

package/dist/rejection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rejection.d.ts","sourceRoot":"","sources":["../src/rejection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,iBAAiB,GACjB,eAAe,GACf,qBAAqB,GACrB,iBAAiB,GACjB,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,eAAe,GACf,YAAY,CAAC;AAEjB;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,GACd,QAAQ,CAEV"}
+{"version":3,"file":"rejection.d.ts","sourceRoot":"","sources":["../src/rejection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,iBAAiB,GACjB,oBAAoB,GACpB,eAAe,GACf,qBAAqB,GACrB,iBAAiB,GACjB,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,eAAe,GACf,YAAY,CAAC;AAkBjB;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,GACd,QAAQ,CAEV"}

package/dist/rejection.js

@@ -1,4 +1,27 @@
-import { McpError } from '@modelcontextprotocol/sdk/types.js';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+// The `Record` annotation keeps this table and the union from drifting apart:
+// a missing or extra key is a compile error.
+const REJECTION_REASONS = {
+    TOOL_HIDDEN: true,
+    RESOURCE_HIDDEN: true,
+    BACKEND_UNROUTABLE: true,
+    POLICY_DENIED: true,
+    IDENTITY_UNRESOLVED: true,
+    CONSENT_MISSING: true,
+    SENSITIVITY_BLOCKED: true,
+    DELEGATION_INVALID: true,
+    BUDGET_EXCEEDED: true,
+    SESSION_LIMIT: true,
+    BODY_LIMIT: true,
+};
+/**
+ * Narrows an untrusted value to `RejectionReason`.
+ * `Object.hasOwn`, not `in`: the value can come from an upstream error, so a
+ * prototype key like `constructor` must not pass as a member.
+ */
+export function isRejectionReason(value) {
+    return typeof value === 'string' && Object.hasOwn(REJECTION_REASONS, value);
+}
 /**
  * Creates an `McpError` with the rejection reason embedded in `error.data`.
  * The top-level `code` is unchanged so clients that only inspect the code

package/dist/rejection.js.map

@@ -1 +1 @@
-{"version":3,"file":"rejection.js","sourceRoot":"","sources":["../src/rejection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAa,MAAM,oCAAoC,CAAC;AAwBzE;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAuB,EACvB,IAAe,EACf,OAAe;IAEf,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"rejection.js","sourceRoot":"","sources":["../src/rejection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAyBzE,8EAA8E;AAC9E,6CAA6C;AAC7C,MAAM,iBAAiB,GAAkC;IACvD,WAAW,EAAE,IAAI;IACjB,eAAe,EAAE,IAAI;IACrB,kBAAkB,EAAE,IAAI;IACxB,aAAa,EAAE,IAAI;IACnB,mBAAmB,EAAE,IAAI;IACzB,eAAe,EAAE,IAAI;IACrB,mBAAmB,EAAE,IAAI;IACzB,kBAAkB,EAAE,IAAI;IACxB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,IAAI;IACnB,UAAU,EAAE,IAAI;CACjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAuB,EACvB,IAAe,EACf,OAAe;IAEf,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/sanitizeCatalog.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Egress sanitizer for the tool catalog: `tools/list` forwards upstream
+ * descriptions verbatim into model context, and real upstreams leak org
+ * slugs and internal hostnames there. See ADR-0010.
+ */
+import type { ListToolsMiddleware } from './core.js';
+/** Options for {@link sanitizeToolDescriptions}. */
+export interface SanitizeToolDescriptionsOptions {
+    /**
+     * Extra patterns to remove. A string replaces every literal occurrence;
+     * a RegExp is normalized to global, with any sticky flag dropped, so
+     * every match is replaced.
+     */
+    patterns?: ReadonlyArray<string | RegExp>;
+    /** Replacement text for every match. Default: `''` (plain removal). */
+    replacement?: string;
+}
+/**
+ * A {@link ListToolsMiddleware} that sanitizes tool descriptions and every
+ * `description` field nested in `inputSchema` / `outputSchema`. Names,
+ * titles, and schema structure are untouched, because clients route on
+ * them.
+ *
+ * Always strips http(s) URLs; `patterns` adds more. Place it **last** in
+ * `listToolsMiddleware` so it sanitizes the output of other list
+ * middleware and local tools.
+ *
+ * @example
+ * listToolsMiddleware: [
+ *   sanitizeToolDescriptions({
+ *     patterns: ['acme-corp', /\bi-[0-9a-f]{8,17}\b/],
+ *     replacement: '[redacted]',
+ *   }),
+ * ]
+ */
+export declare function sanitizeToolDescriptions(options?: SanitizeToolDescriptionsOptions): ListToolsMiddleware;
+//# sourceMappingURL=sanitizeCatalog.d.ts.map