@nanobpm/urban-agent-client 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @nanobpm/urban-agent-client
+
+Worker-side client for the **Nano agentic channel** (ADR 0056, epic
+[nanobpm/nano-ide#124](https://github.com/nanobpm/nano-ide/issues/124), slice
+**S9**).
+
+A worker uses it — on a connection **separate from the C8 job protocol** — to
+join the one app-tier agentic channel: declare a capability and receive its
+resolved routing tokens, heartbeat/deregister for presence, and stream live
+terminal / command-stream bytes. It speaks the
+[`@nanobpm/agentic`](https://www.npmjs.com/package/@nanobpm/agentic)
+wire contract (S0, via its `@nanobpm/agentic/protocol` subpath) and is held
+to its shared conformance corpus; it never redefines the contract.
+
+## What it does
+
+- **`REGISTER` → `SERVE`.** Declares a capability (an _enrolment attribute_ —
+  never part of a routing token, invariant #3) and resolves the leaf tokens the
+  vocab handshake (S3) hands back.
+- **Heartbeat / deregister.** Liveness so the registry ages the worker out on TTL
+  (S2); a clean deregister on shutdown.
+- **Produce relay bytes.** Streams output on the `bulk` lane with a monotonic
+  per-stream byte offset so the hub-side ring can resume-from-offset (S5).
+- **Hub-down tolerance (invariant #6).** Everything the worker produces goes
+  through a bounded, QoS-aware **outbound ring**. The worker keeps producing while
+  the hub is gone; on reconnect the buffer drains in strict lane priority
+  (`control` > `interactive` > `bulk`), so a bulk-output storm never
+  head-of-line-blocks a heartbeat (invariant #5). On overflow the ring sheds the
+  oldest **bulk** frame first and never drops a control frame to make room for a
+  relay chunk.
+
+## Usage
+
+```ts
+import { connectAgenticChannel } from "@nanobpm/urban-agent-client";
+
+const agent = connectAgenticChannel({ url: process.env.AGENTIC_CHANNEL_URL! });
+
+// REGISTER {capability} → SERVE [leaf tokens]. Capability is an enrolment
+// attribute, NOT part of any routing token.
+const { serve } = await agent.register({
+  capability: { cognition: "high", weight: 3, family: "opus", host: "cli" },
+});
+// serve === ["planning.spar#red", …] — resolved from the vocab artifact (S3)
+
+agent.heartbeat();                 // liveness; ages out on TTL if it stops (S2)
+agent.relay("stdout", "hello\n");  // stream terminal bytes on the relay/bulk lane
+// …the client buffers + drains across a hub outage automatically…
+agent.deregister("done");          // best-effort deregister, then close
+```
+
+You may `register` / `relay` **before** the channel is open — the frames buffer
+and drain once it connects.
+
+### Options
+
+| option                | default            | meaning                                                              |
+| --------------------- | ------------------ | -------------------------------------------------------------------- |
+| `url`                 | —                  | the agentic channel URL (the app's own bound port)                   |
+| `instance`            | random UUID        | stable instance id carried on every presence frame                   |
+| `capability`          | —                  | capability to (re-)register with; may also be passed to `register()` |
+| `transport`           | binary `WebSocket` | injectable `TransportFactory` (tests, custom framing)                |
+| `bufferCapacity`      | `1024`             | outbound ring size in frames                                         |
+| `heartbeatIntervalMs` | `0` (manual)       | auto-heartbeat period                                                |
+| `serveTimeoutMs`      | `30000`            | how long `register()` waits for its `SERVE`                          |
+| `reconnect`           | enabled            | backoff policy (`initialDelayMs`, `maxDelayMs`, `factor`)            |
+
+### Events
+
+`onServe`, `onFrame`, `onOpen`, `onClose`, `onError`, `onDrain` — each returns an
+unsubscribe function. Decode/validation/transport errors are surfaced via
+`onError` and are **never thrown**: a malformed inbound frame can never crash the
+worker.
+
+## Building blocks
+
+The package also exports its internals for reuse and testing:
+
+- **`OutboundRing`** — the bounded, QoS-aware buffer/flush-on-reconnect ring.
+- **`websocketTransport` / `TransportFactory`** — the transport seam; supply your
+  own to run without a global `WebSocket` or with custom framing.
+- The S0 contract surface it consumes (`encodeFrame`, `decodeFrame`,
+  `validatePayload`, `parseToken`, `MESSAGE_FAMILIES`, `QOS_LANES`, …), re-exported
+  from `@nanobpm/agentic/protocol`.
+
+## Conformance
+
+`npm run test:conformance` runs this client against the **shared** adversarial
+corpus at `@nanobpm/agentic/source/protocol/conformance` — golden frames both
+directions, malformed byte vectors, and routing-token vectors — the same corpus
+the S0 codec and the cross-repo c8ctl client are held to. It runs from source
+(no build step) so the repo's `conformance` CI job exercises the real vectors.
+
+## Runtime
+
+Node ≥ 22.6 (which provides a global `WebSocket`). Ships as source `.ts` plus a
+built `dist`; runs under `node --experimental-strip-types` like the rest of the
+Urban stack.

package/dist/client.d.ts

@@ -0,0 +1,211 @@
+import { isMessageFamily } from "./protocol.ts";
+import type { Capability, Frame, ServePayload } from "./protocol.ts";
+import type { TransportCloseInfo, TransportFactory } from "./transport.ts";
+export interface ReconnectOptions {
+    readonly enabled?: boolean;
+    readonly initialDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly factor?: number;
+}
+export interface AgenticClientOptions {
+    /**
+     * The agentic channel URL (the app's own bound port). Always passed through
+     * to the transport factory as its first argument; only the default WebSocket
+     * transport requires it, so a custom `transport` may ignore it.
+     */
+    readonly url: string;
+    /** Stable instance id, carried on every presence frame. Defaults to a random UUID. */
+    readonly instance?: string;
+    /**
+     * Capability declared at REGISTER. Stored so a reconnect re-registers
+     * automatically. May be supplied here or later via {@link AgenticClient.register}.
+     */
+    readonly capability?: Capability;
+    /** Transport factory; defaults to a binary WebSocket. Injected in tests. */
+    readonly transport?: TransportFactory;
+    /** Outbound buffer size in frames (hub-down tolerance). Default 1024. */
+    readonly bufferCapacity?: number;
+    /** Auto-heartbeat period in ms; 0/undefined disables the timer (call {@link AgenticClient.heartbeat} manually). */
+    readonly heartbeatIntervalMs?: number;
+    /** How long {@link AgenticClient.register} waits for its SERVE before rejecting. Default 30s. */
+    readonly serveTimeoutMs?: number;
+    /** Reconnect/backoff policy. Enabled by default. */
+    readonly reconnect?: ReconnectOptions;
+    /** Injectable scheduler for reconnect backoff (tests). Defaults to setTimeout. */
+    readonly schedule?: (fn: () => void, ms: number) => void;
+}
+export interface RegisterResult {
+    /** The resolved leaf routing tokens from the vocab handshake (S3). */
+    readonly serve: readonly string[];
+}
+export type AgenticClientState = "idle" | "connecting" | "open" | "closed";
+type Listener<T> = (value: T) => void;
+/** Listener for value-less events (channel open, buffer drained). */
+type VoidListener = () => void;
+/**
+ * Worker-side client for the Nano agentic channel (S9).
+ *
+ * Speaks the S0 wire contract on a connection SEPARATE from the C8 job protocol
+ * (invariants #1/#2): it registers a capability, receives its resolved `SERVE`
+ * tokens, heartbeats/deregisters, and produces relay bytes. Everything the
+ * worker produces goes through a bounded {@link OutboundRing}, so the worker
+ * keeps producing across a hub outage and drains — in strict QoS order — on
+ * reconnect (invariants #5/#6). Capability is an enrolment attribute, never a
+ * routing token (invariant #3).
+ */
+export declare class AgenticClient {
+    readonly instance: string;
+    private readonly url;
+    private readonly transportFactory;
+    private readonly ring;
+    private readonly heartbeatIntervalMs;
+    private readonly serveTimeoutMs;
+    private readonly reconnectPolicy;
+    private readonly schedule;
+    private capability;
+    private transport;
+    private state;
+    private seq;
+    private reconnectDelay;
+    private reconnecting;
+    private closedByCaller;
+    private closeHandled;
+    private heartbeatTimer;
+    private pendingServe;
+    private lastServe;
+    private readonly relayOffsets;
+    private readonly serveListeners;
+    private readonly frameListeners;
+    private readonly openListeners;
+    private readonly closeListeners;
+    private readonly errorListeners;
+    private readonly drainListeners;
+    constructor(options: AgenticClientOptions);
+    /** Current connection state. */
+    get connectionState(): AgenticClientState;
+    /** True when the transport is open and draining live. */
+    get connected(): boolean;
+    /** Number of frames currently buffered awaiting a live channel. */
+    get buffered(): number;
+    /** The most recently resolved SERVE token set (empty until the first SERVE). */
+    get serve(): readonly string[];
+    /** Open the transport. Safe to call once; reconnects are automatic. A no-op after close() (terminal). */
+    connect(): void;
+    /**
+     * Declare a capability and await the resolved SERVE tokens.
+     *
+     * The REGISTER frame is buffered like any other outbound frame, so calling
+     * `register` while the hub is down does not fail — it enqueues and resolves
+     * once the channel comes back and the hub answers with SERVE. Capability is an
+     * enrolment attribute; it never becomes part of a routing token (invariant #3).
+     */
+    register(input?: {
+        capability?: Capability;
+    }): Promise<RegisterResult>;
+    /** Produce a single liveness heartbeat (control lane). Ages out on TTL if it stops (S2). */
+    heartbeat(): void;
+    /**
+     * Produce relay bytes on the bulk lane. `chunk` is the terminal/command output
+     * for `stream`; the client tracks a monotonic per-stream byte offset so the
+     * hub-side ring can resume-from-offset after a consumer reconnect (S5). Bytes
+     * are UTF-8-encoded on the wire as the payload's `chunk` string.
+     */
+    relay(stream: string, chunk: string): void;
+    /**
+     * Deregister and close. Sends a deregister frame best-effort — only when the
+     * channel is currently open. `close()` is terminal and releases the buffer, so
+     * a deregister enqueued while disconnected could never drain; enqueuing it then
+     * would just pin an unsendable frame until close() drops it. When the channel
+     * is down we therefore skip the frame and tear down directly, without
+     * reconnecting.
+     */
+    deregister(reason?: string): void;
+    /** Tear down the client: stop the heartbeat, close the transport, stop reconnecting. */
+    close(): void;
+    /** Subscribe to resolved SERVE tokens (fires on every SERVE, including reconnects). */
+    onServe(listener: Listener<ServePayload>): () => void;
+    /** Subscribe to every validated inbound frame. */
+    onFrame(listener: Listener<Frame>): () => void;
+    /** Subscribe to channel-open events (fires on first connect and each reconnect). */
+    onOpen(listener: VoidListener): () => void;
+    /** Subscribe to channel-close events. */
+    onClose(listener: Listener<TransportCloseInfo>): () => void;
+    /** Subscribe to transport / decode / validation errors (never thrown; always non-fatal). */
+    onError(listener: Listener<Error>): () => void;
+    /** Subscribe to buffer-drained events (fires when the outbound ring empties after sending). */
+    onDrain(listener: VoidListener): () => void;
+    private openTransport;
+    private handleOpen;
+    private handleClose;
+    private scheduleReconnect;
+    private handleFrame;
+    private handleServe;
+    private enqueueRegister;
+    private enqueue;
+    /** True once close() has been called — the terminal state (see {@link close}). */
+    private get isClosed();
+    /**
+     * Categorical guard for every outbound-producing surface: once the client is
+     * closed (terminal), the transport can never reopen and the buffer has been
+     * released, so any frame produced here can never drain. Rather than silently
+     * re-grow the ring close() emptied — and mislead the caller — refuse and
+     * surface the misuse via onError. Returns true when the call was refused.
+     */
+    private refuseWhenClosed;
+    /**
+     * Validate an outbound payload against the S0 contract before it is buffered.
+     * An unsendable frame is never enqueued (so it can't silently occupy buffer
+     * space and then be dropped at encode time); the error is surfaced and, when
+     * it is the REGISTER we are awaiting a SERVE for, the register promise is
+     * failed fast instead of hanging until the serve timeout (or forever when the
+     * timeout is disabled). Returns true when the payload was rejected.
+     */
+    private rejectInvalidOutbound;
+    /** Drain the ring to the transport in strict QoS order until it empties or a send fails. */
+    private pump;
+    /**
+     * Drop every buffered frame of `family` from the ring, returning them. The
+     * single source of truth for outbound coalescing: register coalescing (a
+     * superseding `register()` and a reconnect's `handleOpen()`) and heartbeat
+     * coalescing both use it so the drain never emits a stale or duplicate frame.
+     */
+    private removeBuffered;
+    /**
+     * Tear down the current transport and route through the normal close/reconnect
+     * path when a send throws but the transport does not (or has not yet) fired its
+     * own onClose. `handleClose` is idempotent for this connection attempt, so if
+     * the transport DOES also emit onClose the second pass is a no-op.
+     */
+    private forceReconnect;
+    private nextSeq;
+    private startHeartbeatTimer;
+    private stopHeartbeatTimer;
+    private rejectPendingServe;
+    /**
+     * Fan a value out to a set of subscribers, isolating each one's failures.
+     *
+     * A subscriber that throws must never break dispatch to the remaining
+     * subscribers, and — critically — must never propagate out of internal
+     * plumbing that emits events. `emitError` in particular runs inside error
+     * handling (e.g. a malformed inbound frame), so an `onError` subscriber that
+     * throws would otherwise escape that handler and can take the worker down.
+     * Containing throws here is the single canonical dispatch contract for every
+     * `emit*` below, so no individual emitter can reintroduce that failure mode.
+     */
+    private dispatch;
+    private emitServe;
+    private emitFrame;
+    private emitOpen;
+    private emitClose;
+    private emitError;
+    private emitDrain;
+}
+/**
+ * Connect a worker to the Nano agentic channel and return the client. The
+ * transport begins connecting immediately; because everything the worker
+ * produces is buffered, callers may `register`/`relay` straight away even before
+ * the channel is open (invariant #6).
+ */
+export declare function connectAgenticChannel(options: AgenticClientOptions): AgenticClient;
+/** Re-exported so `isMessageFamily` is available to callers narrowing frames. */
+export { isMessageFamily };