@cortexkit/subc-client 0.3.0 → 0.3.2

package/dist/auth.d.ts

@@ -0,0 +1,19 @@
+import type { ConnectionInfo } from "./connection-file.js";
+import { SubcSocket } from "./socket.js";
+export declare const NONCE_LEN = 32;
+export declare const PROOF_LEN = 32;
+export declare const MAX_AUTH_MESSAGE_LEN = 4096;
+export declare const SERVER_PROOF_DOMAIN = "subc-server-v1";
+export declare const CLIENT_AUTH_DOMAIN = "subc-client-v1";
+export declare const DEFAULT_CLIENT_ROLE = "client";
+export declare class AuthError extends Error {
+}
+/** HMAC-SHA256 over domain ‖ client_nonce ‖ server_nonce ‖ daemon_id. */
+export declare function computeProof(key: Uint8Array, domain: string, clientNonce: Uint8Array, serverNonce: Uint8Array, daemonId: Uint8Array): Uint8Array;
+/**
+ * Run the client handshake over an already-connected socket. Resolves on
+ * success; throws AuthError on any proof/identity mismatch or framing fault.
+ * The whole exchange is bounded by `deadlineMs` (epoch ms).
+ */
+export declare function authenticateClient(sock: SubcSocket, conn: ConnectionInfo, deadlineMs: number): Promise<void>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C,qBAAa,SAAU,SAAQ,KAAK;CAAG;AAEvC,yEAAyE;AACzE,wBAAgB,YAAY,CAC1B,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,UAAU,EACvB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,UAAU,GACnB,UAAU,CAOZ;AA2CD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/auth.js

@@ -0,0 +1,84 @@
+// Port of subc-transport's auth.rs client handshake. The proof construction,
+// domain strings, message framing, and verification order must match the Rust
+// byte-for-byte: a single byte of drift fails authentication outright.
+//
+// Handshake (client side):
+//   1. send ClientHello { client_nonce, role }
+//   2. receive ServerProof { daemon_id, server_nonce, daemon_ver, server_proof }
+//   3. verify server_proof == HMAC(key, "subc-server-v1" ‖ cn ‖ sn ‖ did)  (constant-time)
+//      and daemon_id == the id from the connection file
+//   4. send ClientAuth { client_auth = HMAC(key, "subc-client-v1" ‖ cn ‖ sn ‖ did) }
+//
+// Each message on the wire is a 4-byte little-endian length prefix followed by
+// the JSON body. Byte arrays (nonces, proofs, ids) serialize as JSON arrays of
+// numbers, matching serde's default for [u8; N].
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+export const NONCE_LEN = 32;
+export const PROOF_LEN = 32;
+export const MAX_AUTH_MESSAGE_LEN = 4096;
+export const SERVER_PROOF_DOMAIN = "subc-server-v1";
+export const CLIENT_AUTH_DOMAIN = "subc-client-v1";
+export const DEFAULT_CLIENT_ROLE = "client";
+export class AuthError extends Error {
+}
+/** HMAC-SHA256 over domain ‖ client_nonce ‖ server_nonce ‖ daemon_id. */
+export function computeProof(key, domain, clientNonce, serverNonce, daemonId) {
+    const mac = createHmac("sha256", Buffer.from(key));
+    mac.update(Buffer.from(domain, "utf8"));
+    mac.update(Buffer.from(clientNonce));
+    mac.update(Buffer.from(serverNonce));
+    mac.update(Buffer.from(daemonId));
+    return new Uint8Array(mac.digest());
+}
+function constantTimeEq(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+async function writeMessage(sock, value, deadlineMs) {
+    const json = Buffer.from(JSON.stringify(value), "utf8");
+    if (json.length > MAX_AUTH_MESSAGE_LEN) {
+        throw new AuthError(`auth message too large: ${json.length} > ${MAX_AUTH_MESSAGE_LEN}`);
+    }
+    const lenPrefix = new Uint8Array(4);
+    new DataView(lenPrefix.buffer).setUint32(0, json.length, true);
+    await sock.write(lenPrefix, deadlineMs);
+    await sock.write(json, deadlineMs);
+}
+async function readMessage(sock, deadlineMs) {
+    const lenBytes = await sock.readExact(4, deadlineMs);
+    const len = new DataView(lenBytes.buffer, lenBytes.byteOffset, 4).getUint32(0, true);
+    if (len > MAX_AUTH_MESSAGE_LEN) {
+        throw new AuthError(`auth message too large: ${len} > ${MAX_AUTH_MESSAGE_LEN}`);
+    }
+    const body = len === 0 ? new Uint8Array(0) : await sock.readExact(len, deadlineMs);
+    try {
+        return JSON.parse(Buffer.from(body).toString("utf8"));
+    }
+    catch (err) {
+        throw new AuthError(`auth message JSON decode failed: ${String(err)}`);
+    }
+}
+/**
+ * Run the client handshake over an already-connected socket. Resolves on
+ * success; throws AuthError on any proof/identity mismatch or framing fault.
+ * The whole exchange is bounded by `deadlineMs` (epoch ms).
+ */
+export async function authenticateClient(sock, conn, deadlineMs) {
+    const clientNonce = new Uint8Array(randomBytes(NONCE_LEN));
+    await writeMessage(sock, { client_nonce: Array.from(clientNonce), role: DEFAULT_CLIENT_ROLE }, deadlineMs);
+    const proof = await readMessage(sock, deadlineMs);
+    const serverNonce = Uint8Array.from(proof.server_nonce);
+    const daemonId = Uint8Array.from(proof.daemon_id);
+    const serverProof = Uint8Array.from(proof.server_proof);
+    const expected = computeProof(conn.key, SERVER_PROOF_DOMAIN, clientNonce, serverNonce, daemonId);
+    if (!constantTimeEq(expected, serverProof)) {
+        throw new AuthError("server proof mismatch — wrong key or impostor daemon");
+    }
+    if (!constantTimeEq(daemonId, conn.daemonId)) {
+        throw new AuthError("daemon id mismatch — connection file points at a different daemon");
+    }
+    const clientAuth = computeProof(conn.key, CLIENT_AUTH_DOMAIN, clientNonce, serverNonce, daemonId);
+    await writeMessage(sock, { client_auth: Array.from(clientAuth) }, deadlineMs);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8EAA8E;AAC9E,uEAAuE;AACvE,EAAE;AACF,2BAA2B;AAC3B,+CAA+C;AAC/C,iFAAiF;AACjF,2FAA2F;AAC3F,wDAAwD;AACxD,qFAAqF;AACrF,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,iDAAiD;AAEjD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKvE,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAC5B,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAC5B,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AACnD,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAE5C,MAAM,OAAO,SAAU,SAAQ,KAAK;CAAG;AAEvC,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAC1B,GAAe,EACf,MAAc,EACd,WAAuB,EACvB,WAAuB,EACvB,QAAoB;IAEpB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IACrC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IACrC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,cAAc,CAAC,CAAa,EAAE,CAAa;IAClD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,IAAgB,EAChB,KAAc,EACd,UAAkB;IAElB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QACvC,MAAM,IAAI,SAAS,CAAC,2BAA2B,IAAI,CAAC,MAAM,MAAM,oBAAoB,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC/D,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACxC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACrC,CAAC;AAED,KAAK,UAAU,WAAW,CAAI,IAAgB,EAAE,UAAkB;IAChE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACrF,IAAI,GAAG,GAAG,oBAAoB,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CAAC,2BAA2B,GAAG,MAAM,oBAAoB,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACnF,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAM,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CAAC,oCAAoC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AASD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAgB,EAChB,IAAoB,EACpB,UAAkB;IAElB,MAAM,WAAW,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;IAE3D,MAAM,YAAY,CAChB,IAAI,EACJ,EAAE,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,EACpE,UAAU,CACX,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAqB,IAAI,EAAE,UAAU,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAExD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IACjG,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CAAC,sDAAsD,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IAClG,MAAM,YAAY,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;AAChF,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,265 @@
+import { type ConnectionInfo } from "./connection-file.js";
+import { Priority } from "./envelope.js";
+export declare const SUBC_MODULE_ID_ENV = "SUBC_MODULE_ID";
+export declare const SUBC_LAUNCH_NONCE_ENV = "SUBC_LAUNCH_NONCE";
+export interface BindIdentity {
+    project_root: string;
+    harness: string;
+    session: string;
+}
+export type RouteTarget = {
+    kind: "tool_provider";
+    module_id: string;
+} | {
+    kind: "management_surface";
+    module_id: string;
+} | {
+    kind: "internal_service";
+    module_id: string;
+    service_id: string;
+};
+export type ManagedRouteKind = "management_surface" | "tool_provider";
+export interface ConsumerIdentity {
+    module_id: string;
+    launch_nonce: string;
+}
+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;
+}
+export interface CatalogEntry {
+    module_id: string;
+    roles: unknown[];
+    control_ops: string[];
+}
+export interface RequestOptions {
+    priority?: Priority;
+    timeoutMs?: number;
+    /** Called for each interim PUSH / StreamData frame before the terminal reply. */
+    onProgress?: (body: Uint8Array) => void;
+}
+export interface ManagedCallOptions extends RequestOptions {
+    /** Overrides the per-client identity used for route.open before this call. */
+    identity?: BindIdentity;
+    /** Defaults to management_surface, matching the store/host management APIs. */
+    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;
+}
+export interface SubscribeOptions {
+    priority?: Priority;
+}
+export interface CloseRouteOptions {
+    /**
+     * Await in-flight UNARY requests on the route to settle before tearing it down.
+     * Subscriptions are always aborted (a held-open stream cannot be drained).
+     * Defaults to false: close immediately, aborting everything in flight.
+     */
+    drain?: boolean;
+    /** Consumer identity to use when looking up the route to close; only needed for routes opened with a non-default consumer identity. */
+    consumerIdentity?: ConsumerIdentity | null;
+}
+/**
+ * Capped exponential reconnect backoff. maxAttempts includes the first immediate
+ * reconnect attempt; sleeps happen only between failed transient attempts.
+ */
+export interface ReconnectBackoff {
+    /** First retry delay. */
+    baseMs: number;
+    /** Delay ceiling (doubling is capped here). */
+    capMs: number;
+    /** Max attempts (including the first) before giving up. */
+    maxAttempts: number;
+}
+export declare const DEFAULT_RECONNECT_BACKOFF: ReconnectBackoff;
+export type SubcCallErrorKind = "not_sent" | "outcome_unknown" | "terminal";
+/**
+ * Managed call failure with send-outcome semantics.
+ *
+ * `not_sent` is intentionally narrow: the request bytes provably never left the
+ * local process (the connection was already closed, or net.Socket.write failed
+ * before queuing bytes). Managed call() may retry only this case.
+ *
+ * `outcome_unknown` is the safe default once bytes have been handed to the local
+ * socket. The daemon or module may have received the request before the response
+ * was lost, so call() never retries it automatically; the caller must decide
+ * whether the operation is idempotent or needs a check-then-act recovery.
+ *
+ * `terminal` covers protocol Error frames and non-retryable client/setup errors.
+ */
+export declare class SubcCallError extends Error {
+    readonly kind: SubcCallErrorKind;
+    readonly code?: string | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(kind: SubcCallErrorKind, message: string, code?: string | undefined, cause?: unknown | undefined);
+}
+/**
+ * A live subscription to a provider's event stream, riding a single held-open
+ * request. `onEvent` fires for each StreamData frame; `closed` resolves when the
+ * provider ends the stream (StreamEnd) and rejects on an Error terminal or a route
+ * GOODBYE. `unsubscribe` cancels the held-open request so the provider unwinds.
+ */
+export interface Subscription {
+    /** Cancel the subscription: sends Cancel on the held-open request; idempotent. */
+    unsubscribe(): void;
+    /** Resolves on StreamEnd; rejects on an Error terminal or route close. */
+    readonly closed: Promise<void>;
+}
+export declare class SubcError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export interface ConnectOptions {
+    connectionFile: string;
+    handshakeTimeoutMs?: number;
+    /** Default route identity used by managed call(); can be overridden per call. */
+    identity?: BindIdentity;
+    /** Default route target kind used by managed call(); defaults to management_surface. */
+    targetKind?: ManagedRouteKind;
+    /** Backoff for managed reconnect after a connection drop. */
+    reconnectBackoff?: ReconnectBackoff;
+    /** Injectable sleep for timer-free reconnect tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Hard cap on the timeout-arbitration grace window (see
+     * TIMEOUT_ARBITRATION_GRACE_MS). A reply whose bytes are actively arriving when
+     * the request deadline fires is given up to this long to finish dispatching
+     * before the call settles as a timeout. Bounded and never a deadline extension;
+     * exposed mainly so tests can prove the arbitration deterministically.
+     */
+    timeoutArbitrationGraceMs?: number;
+}
+export declare class SubcClient {
+    private sock;
+    private currentConn;
+    private readonly opts;
+    private nextCorr;
+    private readonly pending;
+    private readonly routes;
+    private closedErr;
+    private closeStarted;
+    private reconnecting;
+    private generation;
+    private readerActive;
+    private constructor();
+    get conn(): ConnectionInfo;
+    /** Read the connection file, connect, authenticate, and start the read loop. */
+    static connect(opts: ConnectOptions): Promise<SubcClient>;
+    /** List modules subc knows about (channel-0 catalog.list). */
+    catalogList(moduleId?: string): Promise<CatalogEntry[]>;
+    /** Open a route to a provider (channel-0 route.open); returns the route channel. */
+    routeOpen(target: RouteTarget, identity: BindIdentity, opts?: RouteOpenOptions): Promise<number>;
+    /** Send a data-plane request on a route channel and await its terminal reply. */
+    request(routeChannel: number, body: unknown, opts?: RequestOptions): Promise<unknown>;
+    /**
+     * Managed route + request convenience. Opens and caches a route for the module,
+     * reconnecting and re-opening cached routes after connection drops.
+     */
+    call<Response = unknown>(moduleId: string, method: string, params?: unknown, opts?: ManagedCallOptions): Promise<Response>;
+    /**
+     * Open a held-open event subscription on a route channel. Sends one Request the
+     * provider keeps open, delivering each interim StreamData frame to `onEvent`; the
+     * returned `closed` settles on the StreamEnd terminal (resolve) or an Error / route
+     * GOODBYE (reject). Events ride this held-open request's correlation id — they are
+     * never unsolicited, so they are not dropped. Call `unsubscribe()` to cancel.
+     */
+    subscribe(routeChannel: number, body: unknown, onEvent: (event: Uint8Array) => void, opts?: SubscribeOptions): Subscription;
+    /**
+     * Tear down ONE managed route (a route opened via `call()`), keyed by its
+     * (target, identity). Idempotent and never throws — callers over-call on
+     * session-end. The teardown:
+     *  - flips a tombstone on the cached route and removes it from the cache, so an
+     *    in-flight `openCachedRoute` for the same key will NOT install its channel
+     *    (the generation guard: close beats a racing reopen), and a later `call()`
+     *    opens a fresh route (this is NOT a permanent tombstone);
+     *  - settles in-flight requests on the channel as RouteClosed (managed requests
+     *    keep their at-most-once classification: outcome_unknown if already sent,
+     *    not_sent otherwise; subscriptions always abort);
+     *  - sends a best-effort route GOODBYE so subc releases the route and notifies
+     *    the module to free per-session resources.
+     * `opts.drain` waits for in-flight UNARY requests to settle before tearing down.
+     */
+    closeRoute(target: Extract<RouteTarget, {
+        kind: ManagedRouteKind;
+    }>, identity: BindIdentity, opts?: CloseRouteOptions): Promise<void>;
+    /**
+     * Tear down ONE route by its channel number — the primitive for callers that
+     * opened a route with `routeOpen` directly (e.g. a tool route carrying raw
+     * {name, arguments}) and hold the channel themselves. Idempotent, never throws.
+     * Settles in-flight requests on the channel as RouteClosed and sends a best-effort
+     * route GOODBYE. `opts.drain` awaits in-flight UNARY requests first; subscriptions
+     * are always aborted (a held-open stream cannot be drained).
+     */
+    closeRouteChannel(channel: number, opts?: CloseRouteOptions): Promise<void>;
+    close(): void;
+    /** Resolve once every in-flight UNARY request on the channel (snapshot at call
+     * time) has settled. Subscriptions are excluded — they are aborted, not drained. */
+    private drainUnaryOnChannel;
+    /** Send a best-effort header-only route GOODBYE for `channel`. One-way: the daemon
+     * releases the route and relays a route-gone GOODBYE to the module; no ack. */
+    private sendRouteGoodbye;
+    private static openConnection;
+    private controlRpc;
+    private send;
+    /**
+     * A request-deadline timer has fired. Before settling as a timeout, arbitrate
+     * the timer-vs-poll race: a reply may already be in the socket buffer, unread
+     * only because the loop was starved. Yield one check phase (setImmediate) so a
+     * fully-buffered reply dispatches and wins via settle()'s identity guard; then,
+     * only while the reader is actively draining THIS socket (a frame mid-arrival),
+     * grant a single hard-capped grace before finally settling. Absent replies
+     * still settle right after the check phase. The settle carries the deadline
+     * marker so the managed classifier reports deadline-not-drop.
+     */
+    private arbitrateTimeout;
+    private managedRequest;
+    private sendManaged;
+    private cachedRouteChannel;
+    private openCachedRoute;
+    private ensureConnectedForManaged;
+    private scheduleReconnectAfterDrop;
+    private reconnectAfterDrop;
+    private reconnectWithRetry;
+    private replaceConnection;
+    private reopenCachedRoutes;
+    private timeoutMessage;
+    private routeClosedDuringOpen;
+    private readLoop;
+    private dispatch;
+    /**
+     * Settle a pending exactly once. The object-identity guard (the map still
+     * holds THIS pending under `key`) is the single-winner primitive: whichever of
+     * dispatch, a timeout, fail(), failChannel(), a GOODBYE, or a deferred timeout
+     * arbitration reaches it first wins, and every later caller no-ops. This is what
+     * makes the deferred-timeout arbitration safe — it cannot double-settle, reject
+     * an already-resolved promise, or delete a pending re-created for a later corr.
+     * Returns true when this call was the settler.
+     */
+    private settle;
+    private rejectPending;
+    private errorFromFrame;
+    private failChannel;
+    private fail;
+    private notSentCallError;
+    private outcomeUnknownCallError;
+    private terminalCallError;
+    private notSentRecoveryError;
+    private encode;
+    private parseJson;
+}
+export declare function isConsumerReconnectTransient(err: unknown): boolean;
+/**
+ * The closed set of route.open rejection codes that mean "the target is
+ * momentarily unavailable but the request could succeed on retry" — the target
+ * is booting, mid-reload, transiently absent, or the bind relay timed out. A
+ * daemon-rejected route.open is provably pre-send (no data frame ever left the
+ * client), so these classify as not_sent; the managed path retries them in-place
+ * within ROUTE_OPEN_RETRY_DEADLINE_MS. Permanent rejections (bad_consumer_identity,
+ * config_divergence, unknown_target, ...) are excluded — they are pre-send but
+ * would never succeed, so retrying them would only storm the daemon. Kept
+ * byte-identical to subc-client-rs is_retryable_route_open_code for cross-client
+ * classification parity.
+ */
+export declare function isRetryableRouteOpenCode(code: string | undefined): boolean;
+export declare function connectionFileExists(path: string): Promise<boolean>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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