@nanobpm/urban-agent-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `@nanobpm/urban-agent-client` — the worker-side client for the Nano agentic
+ * channel (ADR 0056, slice S9).
+ *
+ * A worker uses it on a connection SEPARATE from the C8 job protocol to:
+ *  - `REGISTER` a capability and receive its resolved `SERVE` tokens,
+ *  - `heartbeat` / `deregister` for presence & liveness,
+ *  - produce `relay` bytes (live terminal / command-stream output), and
+ *  - keep producing across a hub outage — everything is buffered in a bounded,
+ *    QoS-aware {@link OutboundRing} and drained, control-before-bulk, on
+ *    reconnect (hub-down tolerance, invariant #6).
+ *
+ * The wire contract itself is owned by `@nanobpm/agentic/protocol` (S0); this
+ * package imports and is held to it (including its shared conformance corpus),
+ * never redefining it.
+ *
+ * @example
+ * ```ts
+ * import { connectAgenticChannel } from "@nanobpm/urban-agent-client";
+ *
+ * const agent = connectAgenticChannel({ url: process.env.AGENTIC_CHANNEL_URL! });
+ * const { serve } = await agent.register({
+ *   capability: { cognition: "high", weight: 3, family: "opus", host: "cli" },
+ * });
+ * agent.heartbeat();
+ * agent.relay("stdout", "hello\n");
+ * // …later…
+ * agent.deregister("done");
+ * ```
+ */
+export { AgenticClient, connectAgenticChannel, isMessageFamily, } from "./client.ts";
+export type { AgenticClientOptions, AgenticClientState, ReconnectOptions, RegisterResult, } from "./client.ts";
+export { OutboundRing, compareFrameOrder } from "./ring.ts";
+export type { EnqueueResult, OutboundRingOptions } from "./ring.ts";
+export { websocketTransport, normaliseIncoming } from "./transport.ts";
+export type { Transport, TransportCloseInfo, TransportFactory, TransportHooks, } from "./transport.ts";
+export { MESSAGE_FAMILIES, QOS_LANES, encodeFrame, decodeFrame, parseToken, isValidToken, validatePayload, } from "./protocol.ts";
+export type { Capability, Frame, MessageFamily, QosLane, RegisterPayload, HeartbeatPayload, DeregisterPayload, ServePayload, RelayPayload, } from "./protocol.ts";

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * `@nanobpm/urban-agent-client` — the worker-side client for the Nano agentic
+ * channel (ADR 0056, slice S9).
+ *
+ * A worker uses it on a connection SEPARATE from the C8 job protocol to:
+ *  - `REGISTER` a capability and receive its resolved `SERVE` tokens,
+ *  - `heartbeat` / `deregister` for presence & liveness,
+ *  - produce `relay` bytes (live terminal / command-stream output), and
+ *  - keep producing across a hub outage — everything is buffered in a bounded,
+ *    QoS-aware {@link OutboundRing} and drained, control-before-bulk, on
+ *    reconnect (hub-down tolerance, invariant #6).
+ *
+ * The wire contract itself is owned by `@nanobpm/agentic/protocol` (S0); this
+ * package imports and is held to it (including its shared conformance corpus),
+ * never redefining it.
+ *
+ * @example
+ * ```ts
+ * import { connectAgenticChannel } from "@nanobpm/urban-agent-client";
+ *
+ * const agent = connectAgenticChannel({ url: process.env.AGENTIC_CHANNEL_URL! });
+ * const { serve } = await agent.register({
+ *   capability: { cognition: "high", weight: 3, family: "opus", host: "cli" },
+ * });
+ * agent.heartbeat();
+ * agent.relay("stdout", "hello\n");
+ * // …later…
+ * agent.deregister("done");
+ * ```
+ */
+export { AgenticClient, connectAgenticChannel, isMessageFamily, } from "./client.js";
+export { OutboundRing, compareFrameOrder } from "./ring.js";
+export { websocketTransport, normaliseIncoming } from "./transport.js";
+// Re-export the S0 contract surface a worker needs so consumers can build and
+// inspect frames without a second dependency line. Sourced from
+// @nanobpm/agentic/protocol (the single source of truth).
+export { MESSAGE_FAMILIES, QOS_LANES, encodeFrame, decodeFrame, parseToken, isValidToken, validatePayload, } from "./protocol.js";

package/dist/protocol.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Single import point for the S0 wire contract.
+ *
+ * We import from the package's `./source` export (raw `.ts`) rather than the
+ * bare entry (`dist`) on purpose: the CI `conformance` job runs
+ * `npm run test:conformance` with **no build step**, so every module this client
+ * touches must be runnable straight from source under
+ * `node --experimental-strip-types`. The Urban stack ships source `.ts` and runs
+ * under strip-types (ADR 0052/0053), so a published consumer resolves the same
+ * source. Keeping the import in one module gives a single swap point.
+ *
+ * The contract itself is owned by `@nanobpm/agentic/protocol` (S0, #126) — this
+ * client imports it, it never redefines it.
+ */
+export { MESSAGE_FAMILIES, isMessageFamily, QOS_LANES, isQosLane, compareFrameOrder, encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, MAX_SEQ, parseToken, isValidToken, validatePayload, bytesToHex, hexToBytes, } from "@nanobpm/agentic/source/protocol";
+export type { MessageFamily, QosLane, Frame, FrameDecodeErrorCode, Capability, RegisterPayload, HeartbeatPayload, DeregisterPayload, ServePayload, RelayPayload, BlackboardPayload, DemandPayload, } from "@nanobpm/agentic/source/protocol";

package/dist/protocol.js

@@ -0,0 +1,15 @@
+/**
+ * Single import point for the S0 wire contract.
+ *
+ * We import from the package's `./source` export (raw `.ts`) rather than the
+ * bare entry (`dist`) on purpose: the CI `conformance` job runs
+ * `npm run test:conformance` with **no build step**, so every module this client
+ * touches must be runnable straight from source under
+ * `node --experimental-strip-types`. The Urban stack ships source `.ts` and runs
+ * under strip-types (ADR 0052/0053), so a published consumer resolves the same
+ * source. Keeping the import in one module gives a single swap point.
+ *
+ * The contract itself is owned by `@nanobpm/agentic/protocol` (S0, #126) — this
+ * client imports it, it never redefines it.
+ */
+export { MESSAGE_FAMILIES, isMessageFamily, QOS_LANES, isQosLane, compareFrameOrder, encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, MAX_SEQ, parseToken, isValidToken, validatePayload, bytesToHex, hexToBytes, } from "@nanobpm/agentic/source/protocol";

package/dist/ring.d.ts

@@ -0,0 +1,103 @@
+import { compareFrameOrder } from "./protocol.ts";
+import type { Frame } from "./protocol.ts";
+/**
+ * The worker-side outbound buffer: a bounded, QoS-aware ring that holds frames
+ * the worker has produced but not yet handed to the transport. It is the local
+ * buffer / flush-on-reconnect store that gives the client its hub-down
+ * tolerance (invariant #6) — the worker keeps producing while the hub is gone,
+ * and drains in order when the channel comes back.
+ *
+ * Two properties are load-bearing:
+ *
+ *  1. **QoS drain order (invariant #5).** Frames drain in strict lane priority —
+ *     `control` before `interactive` before `bulk` — and FIFO within a lane.
+ *     A bulk-output storm can never head-of-line-block a queued heartbeat or
+ *     blackboard write: the heartbeat rides the control lane and drains first.
+ *     The ordering is DERIVED from S0's canonical {@link compareFrameOrder}, not
+ *     re-specified here (see {@link toArray}'s invariant test).
+ *
+ *  2. **Overflow sheds the single least important frame.** When the ring is
+ *     full, the next enqueue drops the lowest-priority frame among the buffer
+ *     AND the incoming frame: the oldest frame from the lowest-priority
+ *     non-empty lane is evicted (bulk before interactive before control) —
+ *     UNLESS the incoming frame is itself strictly lower priority than
+ *     everything buffered, in which case the incoming frame is dropped and the
+ *     buffer is left untouched. A higher-priority buffered frame (e.g. control)
+ *     is therefore never evicted to admit a lower-priority one (e.g. bulk):
+ *     bulk/interactive traffic can never displace buffered control frames. This
+ *     bounds memory during a long outage without ever losing liveness/
+ *     coordination traffic to a relay storm.
+ */
+export interface OutboundRingOptions {
+    /** Maximum number of buffered frames. Must be a positive integer. */
+    readonly capacity: number;
+}
+export interface EnqueueResult {
+    /**
+     * The frame shed by this enqueue, or `null` if the ring had spare capacity.
+     * Usually the oldest frame from the lowest-priority non-empty lane, evicted to
+     * make room; but when the ring is full of strictly higher-priority frames the
+     * INCOMING frame is itself the least important — it is dropped rather than
+     * displace higher-priority traffic, and is returned here with the buffer left
+     * unchanged.
+     */
+    readonly evicted: Frame | null;
+}
+export declare class OutboundRing {
+    readonly capacity: number;
+    private readonly buckets;
+    private count;
+    constructor(options: OutboundRingOptions);
+    /** Number of frames currently buffered. */
+    get size(): number;
+    /** True when no frames are buffered. */
+    get isEmpty(): boolean;
+    /**
+     * Buffer a frame. When the ring is already at capacity, the least important
+     * frame among the buffer and this one is shed (see {@link EnqueueResult.evicted}
+     * and the class-level overflow contract).
+     */
+    enqueue(frame: Frame): EnqueueResult;
+    /**
+     * Buffer a frame at the FRONT of its lane (drains before frames already
+     * queued in that lane). Used to make a reconnect's re-`register` precede any
+     * backlog buffered during the outage. Overflow follows the same QoS-correct
+     * policy as {@link enqueue}: the incoming frame is dropped rather than
+     * displace strictly higher-priority buffered traffic.
+     */
+    enqueueFront(frame: Frame): EnqueueResult;
+    /**
+     * Shared admission path for {@link enqueue} / {@link enqueueFront}.
+     *
+     * Overflow is QoS-correct: when the ring is full we shed the single
+     * least-important frame among the buffer ∪ the incoming frame. If the incoming
+     * frame is strictly lower priority than every buffered frame, IT is the least
+     * important, so it is dropped (and returned as `evicted`) and the buffer is
+     * untouched — a bulk/interactive frame never evicts buffered control traffic.
+     * Otherwise the oldest frame from the lowest-priority non-empty lane is
+     * evicted to make room.
+     */
+    private admit;
+    /** The next frame to drain (highest priority, oldest within its lane) without removing it. */
+    peek(): Frame | undefined;
+    /** Remove and return the next frame to drain, or `undefined` when empty. */
+    dequeue(): Frame | undefined;
+    /** Non-destructive snapshot in drain order (priority lane, then FIFO). */
+    toArray(): Frame[];
+    /**
+     * Remove every buffered frame matching `predicate`, returning the removed
+     * frames. Used to coalesce superseded control frames (e.g. an in-flight
+     * REGISTER replaced by a newer one) so the drain never emits a stale duplicate.
+     */
+    remove(predicate: (frame: Frame) => boolean): Frame[];
+    /** Discard all buffered frames. */
+    clear(): void;
+    private lowestNonEmptyLane;
+}
+/**
+ * The canonical drain comparator, re-exported from S0 so callers that need to
+ * reason about ordering derive it from one source rather than re-implementing
+ * lane priority. {@link OutboundRing.toArray} is asserted equal to sorting by
+ * this comparator in the ring's tests.
+ */
+export { compareFrameOrder };

package/dist/ring.js

@@ -0,0 +1,166 @@
+import { QOS_LANES, compareFrameOrder } from "./protocol.js";
+// Lanes in strict priority order (highest first). Kept as a local const so the
+// bucket walk is O(number-of-lanes) and independent of insertion.
+const LANES_BY_PRIORITY = [...QOS_LANES];
+const LANES_BY_EVICTION = [...QOS_LANES].reverse();
+// Priority rank per lane (0 = highest), derived from the canonical QOS_LANES
+// order so lane comparison has a single source of truth. A LARGER rank means
+// lower priority (evicted sooner).
+const LANE_RANK = new Map(LANES_BY_PRIORITY.map((lane, index) => [lane, index]));
+function laneRank(lane) {
+    return LANE_RANK.get(lane) ?? Number.POSITIVE_INFINITY;
+}
+export class OutboundRing {
+    capacity;
+    buckets;
+    count = 0;
+    constructor(options) {
+        if (!Number.isInteger(options.capacity) || options.capacity < 1) {
+            throw new RangeError(`OutboundRing capacity must be a positive integer, got ${options.capacity}`);
+        }
+        this.capacity = options.capacity;
+        this.buckets = new Map(LANES_BY_PRIORITY.map((lane) => [lane, []]));
+    }
+    /** Number of frames currently buffered. */
+    get size() {
+        return this.count;
+    }
+    /** True when no frames are buffered. */
+    get isEmpty() {
+        return this.count === 0;
+    }
+    /**
+     * Buffer a frame. When the ring is already at capacity, the least important
+     * frame among the buffer and this one is shed (see {@link EnqueueResult.evicted}
+     * and the class-level overflow contract).
+     */
+    enqueue(frame) {
+        return this.admit(frame, false);
+    }
+    /**
+     * Buffer a frame at the FRONT of its lane (drains before frames already
+     * queued in that lane). Used to make a reconnect's re-`register` precede any
+     * backlog buffered during the outage. Overflow follows the same QoS-correct
+     * policy as {@link enqueue}: the incoming frame is dropped rather than
+     * displace strictly higher-priority buffered traffic.
+     */
+    enqueueFront(frame) {
+        return this.admit(frame, true);
+    }
+    /**
+     * Shared admission path for {@link enqueue} / {@link enqueueFront}.
+     *
+     * Overflow is QoS-correct: when the ring is full we shed the single
+     * least-important frame among the buffer ∪ the incoming frame. If the incoming
+     * frame is strictly lower priority than every buffered frame, IT is the least
+     * important, so it is dropped (and returned as `evicted`) and the buffer is
+     * untouched — a bulk/interactive frame never evicts buffered control traffic.
+     * Otherwise the oldest frame from the lowest-priority non-empty lane is
+     * evicted to make room.
+     */
+    admit(frame, toFront) {
+        const bucket = this.buckets.get(frame.lane);
+        if (bucket === undefined) {
+            throw new RangeError(`unknown QoS lane: ${String(frame.lane)}`);
+        }
+        let evicted = null;
+        if (this.count >= this.capacity) {
+            const victimLane = this.lowestNonEmptyLane();
+            if (victimLane === undefined || laneRank(frame.lane) > laneRank(victimLane)) {
+                // The incoming frame is the least important thing in play — drop it
+                // rather than evict a higher-priority buffered frame.
+                return { evicted: frame };
+            }
+            evicted = this.buckets.get(victimLane)?.shift() ?? null;
+            if (evicted !== null) {
+                this.count -= 1;
+            }
+        }
+        if (toFront) {
+            bucket.unshift(frame);
+        }
+        else {
+            bucket.push(frame);
+        }
+        this.count += 1;
+        return { evicted };
+    }
+    /** The next frame to drain (highest priority, oldest within its lane) without removing it. */
+    peek() {
+        for (const lane of LANES_BY_PRIORITY) {
+            const bucket = this.buckets.get(lane);
+            if (bucket !== undefined && bucket.length > 0) {
+                return bucket[0];
+            }
+        }
+        return undefined;
+    }
+    /** Remove and return the next frame to drain, or `undefined` when empty. */
+    dequeue() {
+        for (const lane of LANES_BY_PRIORITY) {
+            const bucket = this.buckets.get(lane);
+            if (bucket !== undefined && bucket.length > 0) {
+                this.count -= 1;
+                return bucket.shift();
+            }
+        }
+        return undefined;
+    }
+    /** Non-destructive snapshot in drain order (priority lane, then FIFO). */
+    toArray() {
+        const out = [];
+        for (const lane of LANES_BY_PRIORITY) {
+            const bucket = this.buckets.get(lane);
+            if (bucket !== undefined) {
+                out.push(...bucket);
+            }
+        }
+        return out;
+    }
+    /**
+     * Remove every buffered frame matching `predicate`, returning the removed
+     * frames. Used to coalesce superseded control frames (e.g. an in-flight
+     * REGISTER replaced by a newer one) so the drain never emits a stale duplicate.
+     */
+    remove(predicate) {
+        const removed = [];
+        for (const lane of LANES_BY_PRIORITY) {
+            const bucket = this.buckets.get(lane);
+            if (bucket === undefined) {
+                continue;
+            }
+            for (let i = bucket.length - 1; i >= 0; i--) {
+                const frame = bucket[i];
+                if (frame !== undefined && predicate(frame)) {
+                    removed.push(frame);
+                    bucket.splice(i, 1);
+                    this.count -= 1;
+                }
+            }
+        }
+        return removed;
+    }
+    /** Discard all buffered frames. */
+    clear() {
+        for (const bucket of this.buckets.values()) {
+            bucket.length = 0;
+        }
+        this.count = 0;
+    }
+    lowestNonEmptyLane() {
+        for (const lane of LANES_BY_EVICTION) {
+            const bucket = this.buckets.get(lane);
+            if (bucket !== undefined && bucket.length > 0) {
+                return lane;
+            }
+        }
+        return undefined;
+    }
+}
+/**
+ * The canonical drain comparator, re-exported from S0 so callers that need to
+ * reason about ordering derive it from one source rather than re-implementing
+ * lane priority. {@link OutboundRing.toArray} is asserted equal to sorting by
+ * this comparator in the ring's tests.
+ */
+export { compareFrameOrder };

package/dist/testkit.d.ts

@@ -0,0 +1,53 @@
+import type { Frame } from "./protocol.ts";
+import type { Transport, TransportFactory, TransportHooks } from "./transport.ts";
+/**
+ * An in-memory transport double for exercising the client with no live hub. It
+ * records every frame the client sends, lets a test drive the connection
+ * lifecycle deterministically (open / deliver / drop / reopen), and can be
+ * pointed at by a {@link TransportFactory} so reconnects rebuild it.
+ */
+export declare class FakeTransport implements Transport {
+    readonly sent: Uint8Array[];
+    open: boolean;
+    /**
+     * When true, {@link send} throws synchronously WITHOUT firing `onClose` — the
+     * minimum a transport is required to do per its contract. Models a channel
+     * that signals disconnect solely by throwing, which must still drive the
+     * client's reconnect path.
+     */
+    throwOnSend: boolean;
+    /**
+     * When true, {@link close} does NOT fire `onClose` — models a transport whose
+     * close is asynchronous (a real WebSocket fires its close event on a later
+     * tick) or one that never surfaces its own close. The client must still notify
+     * its own `onClose` subscribers on a caller-initiated shutdown.
+     */
+    silentClose: boolean;
+    private closedLocal;
+    private readonly hooks;
+    constructor(hooks: TransportHooks);
+    /** Frames decoded from what the client sent, in send order. */
+    get sentFrames(): Frame[];
+    send(bytes: Uint8Array): void;
+    close(): void;
+    /** Simulate the channel coming up. */
+    fireOpen(): void;
+    /** Simulate a remote drop (hub outage / network loss). */
+    drop(info?: {
+        code?: number;
+        reason?: string;
+    }): void;
+    /** Deliver a raw inbound frame to the client. */
+    deliver(bytes: Uint8Array): void;
+    wasClosedLocally(): boolean;
+}
+/**
+ * A {@link TransportFactory} that hands out {@link FakeTransport}s and records
+ * each one it builds, so a test can drive reconnects (the client calls the
+ * factory again on every reconnect attempt).
+ */
+export declare function fakeTransportFactory(): {
+    factory: TransportFactory;
+    transports: FakeTransport[];
+    last(): FakeTransport;
+};

package/dist/testkit.js

@@ -0,0 +1,95 @@
+import { decodeFrame } from "./protocol.js";
+/**
+ * An in-memory transport double for exercising the client with no live hub. It
+ * records every frame the client sends, lets a test drive the connection
+ * lifecycle deterministically (open / deliver / drop / reopen), and can be
+ * pointed at by a {@link TransportFactory} so reconnects rebuild it.
+ */
+export class FakeTransport {
+    sent = [];
+    open = false;
+    /**
+     * When true, {@link send} throws synchronously WITHOUT firing `onClose` — the
+     * minimum a transport is required to do per its contract. Models a channel
+     * that signals disconnect solely by throwing, which must still drive the
+     * client's reconnect path.
+     */
+    throwOnSend = false;
+    /**
+     * When true, {@link close} does NOT fire `onClose` — models a transport whose
+     * close is asynchronous (a real WebSocket fires its close event on a later
+     * tick) or one that never surfaces its own close. The client must still notify
+     * its own `onClose` subscribers on a caller-initiated shutdown.
+     */
+    silentClose = false;
+    closedLocal = false;
+    hooks;
+    constructor(hooks) {
+        this.hooks = hooks;
+    }
+    /** Frames decoded from what the client sent, in send order. */
+    get sentFrames() {
+        return this.sent.map((bytes) => decodeFrame(bytes));
+    }
+    send(bytes) {
+        if (this.throwOnSend) {
+            throw new Error("fake transport send failure (no onClose)");
+        }
+        if (!this.open) {
+            throw new Error("fake transport not open");
+        }
+        this.sent.push(bytes);
+    }
+    close() {
+        this.closedLocal = true;
+        if (this.open) {
+            this.open = false;
+            if (!this.silentClose) {
+                this.hooks.onClose({ local: true });
+            }
+        }
+    }
+    /** Simulate the channel coming up. */
+    fireOpen() {
+        this.open = true;
+        this.hooks.onOpen();
+    }
+    /** Simulate a remote drop (hub outage / network loss). */
+    drop(info = {}) {
+        if (this.open) {
+            this.open = false;
+            this.hooks.onClose({ ...info, local: false });
+        }
+    }
+    /** Deliver a raw inbound frame to the client. */
+    deliver(bytes) {
+        this.hooks.onFrame(bytes);
+    }
+    wasClosedLocally() {
+        return this.closedLocal;
+    }
+}
+/**
+ * A {@link TransportFactory} that hands out {@link FakeTransport}s and records
+ * each one it builds, so a test can drive reconnects (the client calls the
+ * factory again on every reconnect attempt).
+ */
+export function fakeTransportFactory() {
+    const transports = [];
+    const factory = (_url, hooks) => {
+        const transport = new FakeTransport(hooks);
+        transports.push(transport);
+        return transport;
+    };
+    return {
+        factory,
+        transports,
+        last: () => {
+            const transport = transports[transports.length - 1];
+            if (transport === undefined) {
+                throw new Error("fakeTransportFactory().last() called before any transport was created");
+            }
+            return transport;
+        },
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The transport seam. The client is written against a minimal, injectable
+ * transport so it can be exercised without a live hub (hub-down tolerance is a
+ * first-class, unit-tested property) and so a host can supply any framing
+ * (a real WebSocket, an in-process pipe, a test double).
+ *
+ * A transport carries WHOLE encoded frames as binary messages — one
+ * {@link Uint8Array} in, one {@link Uint8Array} out. It never interprets the
+ * bytes; the client owns encode/decode via the S0 codec.
+ */
+export interface TransportHooks {
+    /** The channel is open and ready to send. */
+    onOpen(): void;
+    /** One binary frame arrived from the hub. */
+    onFrame(bytes: Uint8Array): void;
+    /** The channel closed (cleanly or otherwise). */
+    onClose(info: TransportCloseInfo): void;
+    /** A transport-level error occurred. Non-fatal on its own; a close follows. */
+    onError(error: Error): void;
+}
+export interface TransportCloseInfo {
+    readonly code?: number;
+    readonly reason?: string;
+    /** True when the close was requested by the client (a deregister / shutdown). */
+    readonly local?: boolean;
+}
+export interface Transport {
+    /**
+     * Send one encoded frame. Implementations MUST throw synchronously if the
+     * channel is not open, so the client can re-buffer the frame and stop
+     * draining until the next reconnect.
+     */
+    send(bytes: Uint8Array): void;
+    /** Close the channel. Idempotent. */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Builds a transport for a URL, wiring the hub's events into `hooks`. Called
+ * once per connection attempt (a reconnect calls it again).
+ */
+export type TransportFactory = (url: string, hooks: TransportHooks) => Transport;
+/**
+ * The default transport: a binary WebSocket over the app's bound port. Each
+ * agentic frame is one WebSocket binary message. Incoming messages are
+ * normalised to {@link Uint8Array} regardless of whether the runtime delivers
+ * an `ArrayBuffer`, a typed array, or a Node `Buffer`.
+ *
+ * Uses the global `WebSocket` (Node >= 22 provides one). A host on an older
+ * runtime, or one that wants a different framing, passes its own
+ * {@link TransportFactory} to `connectAgenticChannel`.
+ */
+export declare const websocketTransport: TransportFactory;
+/**
+ * Route one inbound transport message: a binary frame goes to `onFrame`; a
+ * non-binary message (a protocol violation under the "one binary frame per
+ * message" contract) is surfaced via `onError` rather than silently dropped, so
+ * the client never hangs seeing no frames yet no error. This is the single
+ * source of truth for the transport's message-dispatch branch.
+ */
+export declare function deliverIncoming(data: unknown, hooks: Pick<TransportHooks, "onFrame" | "onError">): void;
+/** Normalise a WebSocket message payload to bytes, or `undefined` if it is text. */
+export declare function normaliseIncoming(data: unknown): Uint8Array | undefined;

package/dist/transport.js

@@ -0,0 +1,80 @@
+/**
+ * The transport seam. The client is written against a minimal, injectable
+ * transport so it can be exercised without a live hub (hub-down tolerance is a
+ * first-class, unit-tested property) and so a host can supply any framing
+ * (a real WebSocket, an in-process pipe, a test double).
+ *
+ * A transport carries WHOLE encoded frames as binary messages — one
+ * {@link Uint8Array} in, one {@link Uint8Array} out. It never interprets the
+ * bytes; the client owns encode/decode via the S0 codec.
+ */
+/**
+ * The default transport: a binary WebSocket over the app's bound port. Each
+ * agentic frame is one WebSocket binary message. Incoming messages are
+ * normalised to {@link Uint8Array} regardless of whether the runtime delivers
+ * an `ArrayBuffer`, a typed array, or a Node `Buffer`.
+ *
+ * Uses the global `WebSocket` (Node >= 22 provides one). A host on an older
+ * runtime, or one that wants a different framing, passes its own
+ * {@link TransportFactory} to `connectAgenticChannel`.
+ */
+export const websocketTransport = (url, hooks) => {
+    if (typeof WebSocket !== "function") {
+        throw new Error("No global WebSocket is available. Run on Node >= 22.6 (which provides a global WebSocket) " +
+            "or pass a custom `transport` factory to connectAgenticChannel().");
+    }
+    const socket = new WebSocket(url);
+    socket.binaryType = "arraybuffer";
+    let localClose = false;
+    socket.addEventListener("open", () => hooks.onOpen());
+    socket.addEventListener("message", (event) => deliverIncoming(event.data, hooks));
+    socket.addEventListener("error", (event) => {
+        // Preserve the underlying error event as the cause so callers (tests,
+        // operational logs) can inspect the transport-level failure rather than
+        // only seeing a generic message.
+        hooks.onError(new Error("agentic channel transport error", { cause: event }));
+    });
+    socket.addEventListener("close", (event) => {
+        hooks.onClose({ code: event.code, reason: event.reason, local: localClose });
+    });
+    return {
+        send(bytes) {
+            if (socket.readyState !== WebSocket.OPEN) {
+                throw new Error("agentic channel is not open");
+            }
+            socket.send(bytes);
+        },
+        close(code, reason) {
+            localClose = true;
+            socket.close(code, reason);
+        },
+    };
+};
+/**
+ * Route one inbound transport message: a binary frame goes to `onFrame`; a
+ * non-binary message (a protocol violation under the "one binary frame per
+ * message" contract) is surfaced via `onError` rather than silently dropped, so
+ * the client never hangs seeing no frames yet no error. This is the single
+ * source of truth for the transport's message-dispatch branch.
+ */
+export function deliverIncoming(data, hooks) {
+    const bytes = normaliseIncoming(data);
+    if (bytes !== undefined) {
+        hooks.onFrame(bytes);
+        return;
+    }
+    hooks.onError(new Error("agentic channel received a non-binary message; expected one binary frame per message"));
+}
+/** Normalise a WebSocket message payload to bytes, or `undefined` if it is text. */
+export function normaliseIncoming(data) {
+    if (data instanceof Uint8Array) {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
+    }
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    return undefined;
+}