@cortexkit/subc-client 0.12.0 → 0.13.0

package/dist/index.js

@@ -1,7 +1,7 @@
 export { SubcClient, SubcError, SubcCallError, DEFAULT_RECONNECT_BACKOFF, SUBC_MODULE_ID_ENV, SUBC_LAUNCH_NONCE_ENV, isConsumerReconnectTransient, parseRouteCloseReason, classifyRouteCloseReason, routeCloseReason, isValidCapabilityIdentifier, connectionFileExists, } from "./client.js";
-export { RouteHandle, StaleRouteHandleError } from "./route-handle.js";
+export { ReverseRequestRegistry, ReverseRequestRegistrationError, RouteHandle, StaleRouteHandleError, } from "./route-handle.js";
 export { readConnectionFile, ConnectionFileError, } from "./connection-file.js";
-export { FrameType, Priority, AdmissionClass, DAEMON_ORIGIN_FLAG, PROTOCOL_VERSION, HEADER_LEN, buildFrame, buildFrameWithVersion, buildFlags, encodeFrame, decodeHeader, hasBinary, hasDaemonOrigin, encodeHeader, DecodeError, } from "./envelope.js";
+export { FrameType, Priority, AdmissionClass, DAEMON_ORIGIN_FLAG, SUBSCRIPTION_FLAG, PROTOCOL_VERSION, HEADER_LEN, buildFrame, buildFrameWithVersion, buildFlags, encodeFrame, decodeHeader, hasBinary, hasDaemonOrigin, encodeHeader, DecodeError, } from "./envelope.js";
 export { authenticateClient, computeProof, AuthError, NONCE_LEN, PROOF_LEN, SERVER_PROOF_DOMAIN, CLIENT_AUTH_DOMAIN, } from "./auth.js";
 export { SubcSocket, SocketClosedError, SocketTimeoutError } from "./socket.js";
 export { SubcProvider, SubcProviderError, HELLO_CORR, managementSurfaceManifest, jsonProviderHandler, } from "./provider.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACT,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,qBAAqB,EACrB,4BAA4B,EAC5B,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,2BAA2B,EAC3B,oBAAoB,GAwBrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,SAAS,EACT,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,UAAU,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACT,eAAe,EACf,YAAY,EACZ,WAAW,GAIZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,yBAAyB,EACzB,mBAAmB,GAmCpB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACT,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,qBAAqB,EACrB,4BAA4B,EAC5B,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,2BAA2B,EAC3B,oBAAoB,GAwBrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAC/B,WAAW,EACX,qBAAqB,GAGtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,SAAS,EACT,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,UAAU,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACT,eAAe,EACf,YAAY,EACZ,WAAW,GAIZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,yBAAyB,EACzB,mBAAmB,GAmCpB,MAAM,eAAe,CAAC"}

package/dist/route-handle.d.ts

@@ -1,3 +1,30 @@
+export interface ReverseRequestContext {
+    readonly corr: bigint;
+    readonly method: string;
+}
+export type ReverseRequestHandler = (body: Uint8Array, ctx: ReverseRequestContext) => Promise<Uint8Array> | Uint8Array;
+/** A reverse-request registration cannot add a capability after route.open declared its set. */
+export declare class ReverseRequestRegistrationError extends Error {
+    readonly methodFamily: string;
+    readonly code = "reverse_request_capability_not_declared";
+    constructor(methodFamily: string);
+}
+/**
+ * Mutable handler registry prepared before route.open. The client derives
+ * consumer_capabilities from its method families and seals that set when the
+ * route opens; handlers for declared families may still be replaced afterward.
+ */
+export declare class ReverseRequestRegistry {
+    private readonly handlers;
+    private declaredFamilies;
+    onRequest(methodFamily: string, handler: ReverseRequestHandler): void;
+    /** @internal */
+    capabilities(): string[];
+    /** @internal */
+    handler(methodFamily: string): ReverseRequestHandler | undefined;
+    /** @internal */
+    seal(): void;
+}
 /**
  * Immutable identity for one route binding on one live socket. Only channel and
  * epoch cross the wire; the connection token remains private to this SDK.
@@ -6,10 +33,14 @@ export declare class RouteHandle {
     readonly channel: number;
     readonly epoch: number;
     private constructor();
+    /** Replace the handler for a capability declared when this route opened. */
+    onRequest(methodFamily: string, handler: ReverseRequestHandler): void;
     private static create;
 }
 /** @internal SDK factory; not re-exported from the package surface. */
-export declare function createRouteHandle(channel: number, epoch: number, token: object): RouteHandle;
+export declare function createRouteHandle(channel: number, epoch: number, token: object, registry?: ReverseRequestRegistry): RouteHandle;
+/** @internal */
+export declare function reverseRequestHandler(handle: RouteHandle, methodFamily: string): ReverseRequestHandler | undefined;
 /** A route handle belongs to another connection or is no longer installed. */
 export declare class StaleRouteHandleError extends Error {
     readonly handle: RouteHandle;

package/dist/route-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-handle.d.ts","sourceRoot":"","sources":["../src/route-handle.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,OAAO;IAaP,OAAO,CAAC,MAAM,CAAC,MAAM;CAGtB;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAK5F;AAED,8EAA8E;AAC9E,qBAAa,qBAAsB,SAAQ,KAAK;IAGlC,QAAQ,CAAC,MAAM,EAAE,WAAW;IAFxC,QAAQ,CAAC,IAAI,wBAAwB;gBAEhB,MAAM,EAAE,WAAW;CAIzC;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,gBAAgB;AAChB,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED,gBAAgB;AAChB,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAE9E"}
+{"version":3,"file":"route-handle.d.ts","sourceRoot":"","sources":["../src/route-handle.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,qBAAqB,GAAG,CAClC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,qBAAqB,KACvB,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;AAEtC,gGAAgG;AAChG,qBAAa,+BAAgC,SAAQ,KAAK;IAG5C,QAAQ,CAAC,YAAY,EAAE,MAAM;IAFzC,QAAQ,CAAC,IAAI,6CAA6C;gBAErC,YAAY,EAAE,MAAM;CAI1C;AAED;;;;GAIG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,gBAAgB,CAAoC;IAE5D,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAWrE,gBAAgB;IAChB,YAAY,IAAI,MAAM,EAAE;IAIxB,gBAAgB;IAChB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAIhE,gBAAgB;IAChB,IAAI,IAAI,IAAI;CAGb;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,OAAO;IAeP,4EAA4E;IAC5E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAIrE,OAAO,CAAC,MAAM,CAAC,MAAM;CAQtB;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,yBAA+B,GACtC,WAAW,CAKb;AAED,gBAAgB;AAChB,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAElH;AAMD,8EAA8E;AAC9E,qBAAa,qBAAsB,SAAQ,KAAK;IAGlC,QAAQ,CAAC,MAAM,EAAE,WAAW;IAFxC,QAAQ,CAAC,IAAI,wBAAwB;gBAEhB,MAAM,EAAE,WAAW;CAIzC;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,gBAAgB;AAChB,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED,gBAAgB;AAChB,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAE9E"}

package/dist/route-handle.js

@@ -1,4 +1,47 @@
 const connectionToken = new WeakMap();
+const reverseRequests = new WeakMap();
+/** A reverse-request registration cannot add a capability after route.open declared its set. */
+export class ReverseRequestRegistrationError extends Error {
+    methodFamily;
+    code = "reverse_request_capability_not_declared";
+    constructor(methodFamily) {
+        super(`reverse-request capability ${JSON.stringify(methodFamily)} was not registered before route.open`);
+        this.methodFamily = methodFamily;
+        this.name = "ReverseRequestRegistrationError";
+    }
+}
+/**
+ * Mutable handler registry prepared before route.open. The client derives
+ * consumer_capabilities from its method families and seals that set when the
+ * route opens; handlers for declared families may still be replaced afterward.
+ */
+export class ReverseRequestRegistry {
+    handlers = new Map();
+    declaredFamilies = null;
+    onRequest(methodFamily, handler) {
+        if (!isMethodFamily(methodFamily)) {
+            throw new TypeError(`reverse-request method family must be a capability identifier, got ${JSON.stringify(methodFamily)}`);
+        }
+        if (typeof handler !== "function")
+            throw new TypeError("reverse-request handler must be a function");
+        if (this.declaredFamilies && !this.declaredFamilies.has(methodFamily)) {
+            throw new ReverseRequestRegistrationError(methodFamily);
+        }
+        this.handlers.set(methodFamily, handler);
+    }
+    /** @internal */
+    capabilities() {
+        return [...this.handlers.keys()].sort();
+    }
+    /** @internal */
+    handler(methodFamily) {
+        return this.handlers.get(methodFamily);
+    }
+    /** @internal */
+    seal() {
+        this.declaredFamilies ??= new Set(this.handlers.keys());
+    }
+}
 /**
  * Immutable identity for one route binding on one live socket. Only channel and
  * epoch cross the wire; the connection token remains private to this SDK.
@@ -6,7 +49,7 @@ const connectionToken = new WeakMap();
 export class RouteHandle {
     channel;
     epoch;
-    constructor(channel, epoch, token) {
+    constructor(channel, epoch, token, registry) {
         if (!Number.isInteger(channel) || channel <= 0 || channel > 0xffff) {
             throw new RangeError(`route channel must be an integer in 1..65535, got ${channel}`);
         }
@@ -15,17 +58,30 @@ export class RouteHandle {
         }
         this.channel = channel;
         this.epoch = epoch;
+        registry.seal();
         connectionToken.set(this, token);
+        reverseRequests.set(this, registry);
         Object.freeze(this);
     }
-    static create(channel, epoch, token) {
-        return new RouteHandle(channel, epoch, token);
+    /** Replace the handler for a capability declared when this route opened. */
+    onRequest(methodFamily, handler) {
+        reverseRequests.get(this).onRequest(methodFamily, handler);
+    }
+    static create(channel, epoch, token, registry) {
+        return new RouteHandle(channel, epoch, token, registry);
     }
 }
 /** @internal SDK factory; not re-exported from the package surface. */
-export function createRouteHandle(channel, epoch, token) {
+export function createRouteHandle(channel, epoch, token, registry = new ReverseRequestRegistry()) {
     const factory = RouteHandle;
-    return factory.create(channel, epoch, token);
+    return factory.create(channel, epoch, token, registry);
+}
+/** @internal */
+export function reverseRequestHandler(handle, methodFamily) {
+    return reverseRequests.get(handle)?.handler(methodFamily);
+}
+function isMethodFamily(value) {
+    return /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value);
 }
 /** A route handle belongs to another connection or is no longer installed. */
 export class StaleRouteHandleError extends Error {

package/dist/route-handle.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-handle.js","sourceRoot":"","sources":["../src/route-handle.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG,IAAI,OAAO,EAAuB,CAAC;AAE3D;;;GAGG;AACH,MAAM,OAAO,WAAW;IACb,OAAO,CAAS;IAChB,KAAK,CAAS;IAEvB,YAAoB,OAAe,EAAE,KAAa,EAAE,KAAa;QAC/D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,OAAO,GAAG,MAAM,EAAE,CAAC;YACnE,MAAM,IAAI,UAAU,CAAC,qDAAqD,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,WAAW,EAAE,CAAC;YAClE,MAAM,IAAI,UAAU,CAAC,wDAAwD,KAAK,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAEO,MAAM,CAAC,MAAM,CAAC,OAAe,EAAE,KAAa,EAAE,KAAa;QACjE,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAChD,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,KAAa,EAAE,KAAa;IAC7E,MAAM,OAAO,GAAG,WAEf,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC;AAED,8EAA8E;AAC9E,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAGzB;IAFZ,IAAI,GAAG,oBAAoB,CAAC;IAErC,YAAqB,MAAmB;QACtC,KAAK,CAAC,iBAAiB,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC,KAAK,yCAAyC,CAAC,CAAC;QAD9E,WAAM,GAAN,MAAM,CAAa;QAEtC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,gBAAgB;AAChB,MAAM,UAAU,kBAAkB;IAChC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,mBAAmB,CAAC,MAAmB,EAAE,KAAa;IACpE,OAAO,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC;AAC/C,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,eAAe,CAAC,IAAiB,EAAE,KAAkB;IACnE,OAAO,IAAI,KAAK,KAAK,CAAC;AACxB,CAAC"}
+{"version":3,"file":"route-handle.js","sourceRoot":"","sources":["../src/route-handle.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/subc-client",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript client for the subc daemon. Wire-compatible (byte-for-byte) with the Rust subc-transport handshake and subc-protocol envelope.",
   "type": "module",
   "exports": {

package/src/client.ts

@@ -22,12 +22,15 @@ import {
   FrameType,
   hasBinary,
   Priority,
+  SUBSCRIPTION_FLAG,
   type Frame,
 } from "./envelope.js";
 import {
   belongsToConnection,
   createRouteHandle,
   newConnectionToken,
+  reverseRequestHandler,
+  ReverseRequestRegistry,
   RouteHandle,
   sameRouteHandle,
   StaleRouteHandleError,
@@ -109,8 +112,11 @@ export interface ConsumerIdentity {
 export interface RouteOpenOptions {
   /** Optional override for the consumer identity; by default the SUBC_MODULE_ID and SUBC_LAUNCH_NONCE environment variables are used when both are non-empty. Set null to send route.open without consumer_identity. */
   consumerIdentity?: ConsumerIdentity | null;
-  /** Optional consumer-declared reverse-request capabilities for this route.open. This is a declaration, not a verified privilege; providers must treat an omitted field as no reverse-request capability. Known MCP method-family values today are "elicitation", "sampling", and "roots". */
-  consumerCapabilities?: string[];
+  /**
+   * Handlers prepared before route.open. The client derives consumer_capabilities
+   * from this registry; callers cannot declare a capability without a handler.
+   */
+  reverseRequests?: ReverseRequestRegistry;
 }
 
 export interface CatalogCapabilityRequirement {
@@ -193,6 +199,8 @@ export interface ManagedCallOptions extends RequestOptions {
   targetKind?: ManagedRouteKind;
   /** Optional override for the consumer identity; by default the SUBC_MODULE_ID and SUBC_LAUNCH_NONCE environment variables are used when both are non-empty. Set null to send route.open without consumer_identity. */
   consumerIdentity?: ConsumerIdentity | null;
+  /** Reverse-request handlers used by the managed route and all of its reconnect reopens. */
+  reverseRequests?: ReverseRequestRegistry;
 }
 
 export interface SubscribeOptions {
@@ -221,6 +229,8 @@ export interface CloseRouteOptions {
 export interface ManagedCloseRouteOptions extends CloseRouteOptions {
   /** Consumer identity used by the cached managed route. */
   consumerIdentity?: ConsumerIdentity | null;
+  /** The registry whose derived capability set identifies the cached route. */
+  reverseRequests?: ReverseRequestRegistry;
 }
 
 /**
@@ -468,6 +478,7 @@ interface CachedRoute {
   target: Extract<RouteTarget, { kind: ManagedRouteKind }>;
   identity: BindIdentity;
   consumerIdentity?: ConsumerIdentity;
+  reverseRequests: ReverseRequestRegistry;
   handle: RouteHandle | null;
   opening: Promise<RouteHandle> | null;
   /**
@@ -566,13 +577,15 @@ export class SubcClient {
   /** Open a route and return its connection-bound immutable handle. */
   async routeOpen(target: RouteTarget, identity: BindIdentity, opts: RouteOpenOptions = {}): Promise<RouteHandle> {
     const consumerIdentity = routeOpenConsumerIdentity(opts);
-    const consumerCapabilities = opts.consumerCapabilities;
+    const reverseRequests = opts.reverseRequests ?? new ReverseRequestRegistry();
+    reverseRequests.seal();
+    const consumerCapabilities = reverseRequests.capabilities();
     const body = this.encode({
       op: "route.open",
       target,
       identity,
       ...(consumerIdentity ? { consumer_identity: consumerIdentity } : {}),
-      ...(consumerCapabilities !== undefined ? { consumer_capabilities: consumerCapabilities } : {}),
+      ...(consumerCapabilities.length > 0 ? { consumer_capabilities: consumerCapabilities } : {}),
     });
 
     let installed: RouteHandle | null = null;
@@ -582,7 +595,7 @@ export class SubcClient {
       if (typeof parsed.route_channel !== "number" || typeof parsed.route_epoch !== "number") {
         throw new SubcError(`route.open returned no route handle: ${JSON.stringify(parsed)}`);
       }
-      installed = this.installRoute(parsed.route_channel, parsed.route_epoch);
+      installed = this.installRoute(parsed.route_channel, parsed.route_epoch, reverseRequests);
       return true;
     };
     const closeLateRoute = (frame: Frame): void => {
@@ -749,7 +762,7 @@ export class SubcClient {
       this.pending.set(key, subscriptionPending);
       const frame = buildFrame(
         FrameType.Request,
-        buildFlags(false, priority, false, admission),
+        buildFlags(false, priority, false, admission) | SUBSCRIPTION_FLAG,
         handle.channel,
         handle.epoch,
         corr,
@@ -857,7 +870,12 @@ export class SubcClient {
     identity: BindIdentity,
     opts: ManagedCloseRouteOptions = {},
   ): Promise<void> {
-    const key = routeCacheKey(target, identity, routeOpenConsumerIdentity(opts));
+    const key = routeCacheKey(
+      target,
+      identity,
+      routeOpenConsumerIdentity(opts),
+      (opts.reverseRequests ?? new ReverseRequestRegistry()).capabilities(),
+    );
     const cached = this.routes.get(key);
     if (!cached) return;
     cached.closed = true;
@@ -1139,7 +1157,9 @@ export class SubcClient {
       { kind: ManagedRouteKind }
     >;
     const consumerIdentity = routeOpenConsumerIdentity(opts);
-    const key = routeCacheKey(target, identity, consumerIdentity);
+    const reverseRequests = opts.reverseRequests ?? new ReverseRequestRegistry();
+    reverseRequests.seal();
+    const key = routeCacheKey(target, identity, consumerIdentity, reverseRequests.capabilities());
     let cached = this.routes.get(key);
     if (!cached) {
       cached = {
@@ -1148,6 +1168,7 @@ export class SubcClient {
         target,
         identity,
         consumerIdentity,
+        reverseRequests,
         handle: null,
         opening: null,
       };
@@ -1178,6 +1199,7 @@ export class SubcClient {
       try {
         const handle = await this.routeOpen(cached.target, cached.identity, {
           consumerIdentity: cached.consumerIdentity ?? null,
+          reverseRequests: cached.reverseRequests,
         });
         if (cached.closed) {
           this.liveRoutes.delete(handle.channel);
@@ -1401,6 +1423,7 @@ export class SubcClient {
       try {
         const handle = await this.routeOpen(cached.target, cached.identity, {
           consumerIdentity: cached.consumerIdentity ?? null,
+          reverseRequests: cached.reverseRequests,
         });
         if (cached.closed) {
           this.liveRoutes.delete(handle.channel);
@@ -1504,6 +1527,11 @@ export class SubcClient {
       }
     }
 
+    if (frame.header.ty === FrameType.Request && handle) {
+      this.dispatchReverseRequest(frame, handle);
+      return;
+    }
+
     const key = pendingKey(handle, frame.header.corr);
     const pending = this.pending.get(key);
     if (pending) {
@@ -1607,6 +1635,109 @@ export class SubcClient {
     this.settle(key, pending, () => pending.reject(pending.classifyFailure?.(err) ?? err));
   }
 
+  private dispatchReverseRequest(frame: Frame, handle: RouteHandle): void {
+    const method = reverseRequestMethod(frame.body);
+    const methodFamily = method?.split("/", 1)[0];
+    const handler = methodFamily ? reverseRequestHandler(handle, methodFamily) : undefined;
+    const sock = this.sock;
+    const generation = this.generation;
+
+    // ONE CODE, TWO SITES, ON PURPOSE. `reverse_request_unhandled` is emitted
+    // both here (no handler registered) and below (a handler that threw), with
+    // different MESSAGES and the same CODE. That is a ruling, not an oversight:
+    // the distinction between "nobody listening" and "the listener broke" is
+    // ours to log, and every provider's decision is identical for both -- not
+    // granted, retry later. A second code would be a second thing every
+    // consumer's decoder must learn for a branch none of them takes. If one ever
+    // needs it, the message carries it. (Settled with prefrontal, the lane's
+    // first consumer, before anyone pinned on it.)
+    //
+    // What must NOT join them: a handler that RETURNS bytes declining the
+    // request answers with an ordinary Response in the provider's own
+    // vocabulary. Error means "the consumer did not answer", never "the consumer
+    // said no" -- that separation is the reason this lane exists.
+    const reply = async (): Promise<void> => {
+      if (!handler || !method) {
+        await this.sendReverseError(
+          frame,
+          handle,
+          "reverse_request_unhandled",
+          methodFamily
+            ? `no reverse-request handler is registered for ${methodFamily}`
+            : "reverse request has no valid method",
+          sock,
+          generation,
+        );
+        return;
+      }
+
+      let body: Uint8Array;
+      try {
+        body = await handler(frame.body, { corr: frame.header.corr, method });
+        if (!(body instanceof Uint8Array)) {
+          throw new TypeError("reverse-request handler must return a Uint8Array");
+        }
+      } catch (error) {
+        await this.sendReverseError(
+          frame,
+          handle,
+          "reverse_request_unhandled",
+          error instanceof Error ? error.message : String(error),
+          sock,
+          generation,
+        );
+        return;
+      }
+
+      await this.sendReverseReply(frame, handle, FrameType.Response, body, sock, generation);
+    };
+
+    void reply().catch((error) => {
+      if (this.sock === sock && this.generation === generation && !this.closeStarted) {
+        debug("failed to answer reverse request: %s", causeMessage(error));
+      }
+    });
+  }
+
+  private async sendReverseError(
+    request: Frame,
+    handle: RouteHandle,
+    code: string,
+    message: string,
+    sock: SubcSocket,
+    generation: number,
+  ): Promise<void> {
+    await this.sendReverseReply(request, handle, FrameType.Error, this.encode({ code, message }), sock, generation);
+  }
+
+  private async sendReverseReply(
+    request: Frame,
+    handle: RouteHandle,
+    type: FrameType.Response | FrameType.Error,
+    body: Uint8Array,
+    sock: SubcSocket,
+    generation: number,
+  ): Promise<void> {
+    if (
+      this.sock !== sock ||
+      this.generation !== generation ||
+      !this.isLiveHandle(handle) ||
+      this.closeStarted ||
+      this.closedErr
+    ) {
+      return;
+    }
+    const frame = buildFrame(
+      type,
+      buildFlags(false, Priority.Interactive, false),
+      handle.channel,
+      handle.epoch,
+      request.header.corr,
+      body,
+    );
+    await writeBorrowed(sock, encodeFrame(frame), Date.now() + DEFAULT_REQUEST_TIMEOUT_MS);
+  }
+
   private errorFromFrame(frame: Frame): SubcError {
     try {
       const parsed = JSON.parse(Buffer.from(frame.body).toString("utf8")) as {
@@ -1663,8 +1794,12 @@ export class SubcClient {
     return this.ingressEpochDropCount;
   }
 
-  private installRoute(channel: number, epoch: number): RouteHandle {
-    const handle = createRouteHandle(channel, epoch, this.connectionToken);
+  private installRoute(
+    channel: number,
+    epoch: number,
+    reverseRequests = new ReverseRequestRegistry(),
+  ): RouteHandle {
+    const handle = createRouteHandle(channel, epoch, this.connectionToken, reverseRequests);
     this.liveRoutes.set(channel, handle);
     return handle;
   }
@@ -1813,12 +1948,14 @@ export function isValidCapabilityIdentifier(identifier: string): boolean {
 function routeCacheKey(
   target: Extract<RouteTarget, { kind: ManagedRouteKind }>,
   identity: BindIdentity,
-  consumerIdentity?: ConsumerIdentity,
+  consumerIdentity: ConsumerIdentity | undefined,
+  consumerCapabilities: readonly string[],
 ): string {
   const consumerPart = consumerIdentity
     ? `${consumerIdentity.module_id}\0${consumerIdentity.launch_nonce}`
     : "";
-  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}\0${consumerPart}`;
+  const capabilitiesPart = [...consumerCapabilities].sort().join("\0");
+  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}\0${consumerPart}\0${capabilitiesPart}`;
 }
 
 function routeOpenConsumerIdentity(opts: RouteOpenOptions = {}): ConsumerIdentity | undefined {
@@ -1845,3 +1982,12 @@ function causeMessage(cause: unknown): string {
 function pendingKey(handle: RouteHandle | null, corr: bigint): string {
   return handle ? `${handle.channel}:${handle.epoch}:${corr}` : `0:0:${corr}`;
 }
+
+function reverseRequestMethod(body: Uint8Array): string | undefined {
+  try {
+    const parsed = JSON.parse(Buffer.from(body).toString("utf8")) as { method?: unknown };
+    return typeof parsed.method === "string" && parsed.method.length > 0 ? parsed.method : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/envelope.ts

@@ -51,7 +51,8 @@ const FLAG_LAST = 0b0000_1000;
 const FLAG_ADMISSION_MASK = 0b0011_0000;
 const FLAG_ADMISSION_SHIFT = 4;
 export const DAEMON_ORIGIN_FLAG = 0x40;
-const FLAG_RESERVED_MASK = 0b1000_0000;
+export const SUBSCRIPTION_FLAG = 0x80;
+const FLAG_RESERVED_MASK = 0;
 
 /** Build flags from typed components. Admission defaults to NORMAL. */
 export function buildFlags(

package/src/index.ts

@@ -35,7 +35,14 @@ export {
   type RoutePollKind,
   type RoutePollResult,
 } from "./client.js";
-export { RouteHandle, StaleRouteHandleError } from "./route-handle.js";
+export {
+  ReverseRequestRegistry,
+  ReverseRequestRegistrationError,
+  RouteHandle,
+  StaleRouteHandleError,
+  type ReverseRequestContext,
+  type ReverseRequestHandler,
+} from "./route-handle.js";
 export {
   readConnectionFile,
   ConnectionFileError,
@@ -47,6 +54,7 @@ export {
   Priority,
   AdmissionClass,
   DAEMON_ORIGIN_FLAG,
+  SUBSCRIPTION_FLAG,
   PROTOCOL_VERSION,
   HEADER_LEN,
   buildFrame,

package/src/route-handle.ts

@@ -1,4 +1,61 @@
 const connectionToken = new WeakMap<RouteHandle, object>();
+const reverseRequests = new WeakMap<RouteHandle, ReverseRequestRegistry>();
+
+export interface ReverseRequestContext {
+  readonly corr: bigint;
+  readonly method: string;
+}
+
+export type ReverseRequestHandler = (
+  body: Uint8Array,
+  ctx: ReverseRequestContext,
+) => Promise<Uint8Array> | Uint8Array;
+
+/** A reverse-request registration cannot add a capability after route.open declared its set. */
+export class ReverseRequestRegistrationError extends Error {
+  readonly code = "reverse_request_capability_not_declared";
+
+  constructor(readonly methodFamily: string) {
+    super(`reverse-request capability ${JSON.stringify(methodFamily)} was not registered before route.open`);
+    this.name = "ReverseRequestRegistrationError";
+  }
+}
+
+/**
+ * Mutable handler registry prepared before route.open. The client derives
+ * consumer_capabilities from its method families and seals that set when the
+ * route opens; handlers for declared families may still be replaced afterward.
+ */
+export class ReverseRequestRegistry {
+  private readonly handlers = new Map<string, ReverseRequestHandler>();
+  private declaredFamilies: ReadonlySet<string> | null = null;
+
+  onRequest(methodFamily: string, handler: ReverseRequestHandler): void {
+    if (!isMethodFamily(methodFamily)) {
+      throw new TypeError(`reverse-request method family must be a capability identifier, got ${JSON.stringify(methodFamily)}`);
+    }
+    if (typeof handler !== "function") throw new TypeError("reverse-request handler must be a function");
+    if (this.declaredFamilies && !this.declaredFamilies.has(methodFamily)) {
+      throw new ReverseRequestRegistrationError(methodFamily);
+    }
+    this.handlers.set(methodFamily, handler);
+  }
+
+  /** @internal */
+  capabilities(): string[] {
+    return [...this.handlers.keys()].sort();
+  }
+
+  /** @internal */
+  handler(methodFamily: string): ReverseRequestHandler | undefined {
+    return this.handlers.get(methodFamily);
+  }
+
+  /** @internal */
+  seal(): void {
+    this.declaredFamilies ??= new Set(this.handlers.keys());
+  }
+}
 
 /**
  * Immutable identity for one route binding on one live socket. Only channel and
@@ -8,7 +65,7 @@ export class RouteHandle {
   readonly channel: number;
   readonly epoch: number;
 
-  private constructor(channel: number, epoch: number, token: object) {
+  private constructor(channel: number, epoch: number, token: object, registry: ReverseRequestRegistry) {
     if (!Number.isInteger(channel) || channel <= 0 || channel > 0xffff) {
       throw new RangeError(`route channel must be an integer in 1..65535, got ${channel}`);
     }
@@ -17,21 +74,47 @@ export class RouteHandle {
     }
     this.channel = channel;
     this.epoch = epoch;
+    registry.seal();
     connectionToken.set(this, token);
+    reverseRequests.set(this, registry);
     Object.freeze(this);
   }
 
-  private static create(channel: number, epoch: number, token: object): RouteHandle {
-    return new RouteHandle(channel, epoch, token);
+  /** Replace the handler for a capability declared when this route opened. */
+  onRequest(methodFamily: string, handler: ReverseRequestHandler): void {
+    reverseRequests.get(this)!.onRequest(methodFamily, handler);
+  }
+
+  private static create(
+    channel: number,
+    epoch: number,
+    token: object,
+    registry: ReverseRequestRegistry,
+  ): RouteHandle {
+    return new RouteHandle(channel, epoch, token, registry);
   }
 }
 
 /** @internal SDK factory; not re-exported from the package surface. */
-export function createRouteHandle(channel: number, epoch: number, token: object): RouteHandle {
+export function createRouteHandle(
+  channel: number,
+  epoch: number,
+  token: object,
+  registry = new ReverseRequestRegistry(),
+): RouteHandle {
   const factory = RouteHandle as unknown as {
-    create(channel: number, epoch: number, token: object): RouteHandle;
+    create(channel: number, epoch: number, token: object, registry: ReverseRequestRegistry): RouteHandle;
   };
-  return factory.create(channel, epoch, token);
+  return factory.create(channel, epoch, token, registry);
+}
+
+/** @internal */
+export function reverseRequestHandler(handle: RouteHandle, methodFamily: string): ReverseRequestHandler | undefined {
+  return reverseRequests.get(handle)?.handler(methodFamily);
+}
+
+function isMethodFamily(value: string): boolean {
+  return /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value);
 }
 
 /** A route handle belongs to another connection or is no longer installed. */