@graphorin/client 0.5.0

package/dist/graphorin-client.js

@@ -0,0 +1,594 @@
+import { ClientAbortedError, ClientNotConnectedError, GraphorinClientError, ProtocolViolationError, TransportFailedError, kindForRpcCode } from "./errors.js";
+import { computeBackoffMs, sleep } from "./reconnect.js";
+import { openSseTransport } from "./transport/sse.js";
+import { openWebSocketTransport } from "./transport/ws.js";
+import { isErrorFrame, isEventFrame, isLifecycleFrame, isPongFrame, isReplayMarkerFrame, isRpcFailure, isRpcSuccess, isSubscribedFrame, isUnsubscribedFrame } from "@graphorin/protocol";
+
+//#region src/graphorin-client.ts
+/**
+* `GraphorinClient` — ergonomic façade over the
+* {@link Transport} contract. Handles:
+*
+*   - WS handshake (`openWebSocketTransport`) with optional ticket flow.
+*   - Optional SSE fallback (`openSseTransport`) for environments
+*     that block WebSocket upgrades.
+*   - JSON-RPC request / response correlation for `subscribe` /
+*     `unsubscribe` / `cancel` / `resume` / `ping` calls.
+*   - Async-iterable subscriptions (`for await (const event of
+*     sub.events())`).
+*   - Exponential-backoff reconnect with `lastEventId` resume against
+*     the server replay buffer.
+*
+* The class is intentionally small (≈ 400 LOC) so the production
+* cross-cuts (telemetry, sticky reconnect on transient errors,
+* load-shedding) live in higher-level wrappers consumers build on
+* top of `GraphorinClient` instead of leaking into the protocol
+* adapter itself.
+*
+* @packageDocumentation
+*/
+/**
+* @stable
+*/
+var GraphorinClient = class {
+	#options;
+	#pending = /* @__PURE__ */ new Map();
+	#subscriptions = /* @__PURE__ */ new Map();
+	/** IP-3: the synthetic single subscription an SSE connection carries. */
+	#sseSubscription;
+	#transport;
+	#idCounter = 0;
+	#closed = false;
+	#connectingPromise;
+	#abortController = new AbortController();
+	constructor(options) {
+		if (typeof options.baseUrl !== "string" || options.baseUrl.length === 0) throw new TypeError("GraphorinClient: baseUrl must be a non-empty string.");
+		this.#options = options;
+	}
+	/**
+	* Open the underlying transport. Resolves once the server has
+	* accepted the handshake (`'open'`); rejects with a typed
+	* {@link GraphorinClientError} otherwise.
+	*
+	* Calling `connect()` while already connected is a no-op; calling
+	* it during another `connect()` returns the same promise.
+	*/
+	async connect() {
+		if (this.#closed) throw new ClientAbortedError("GraphorinClient was disconnected; create a new instance.");
+		if (this.#transport !== void 0) return;
+		if (this.#connectingPromise !== void 0) return this.#connectingPromise;
+		this.#connectingPromise = (async () => {
+			const preference = this.#options.transport ?? "auto";
+			try {
+				if (preference === "ws" || preference === "auto") try {
+					this.#transport = await this.#openWs();
+					await this.#initializeRpc();
+					return;
+				} catch (err) {
+					if (preference === "ws") throw err;
+				}
+				this.#transport = await this.#openSse();
+			} finally {
+				this.#connectingPromise = void 0;
+			}
+		})();
+		return this.#connectingPromise;
+	}
+	async #initializeRpc() {
+		if (this.#transport?.kind !== "ws") return;
+		await this.#sendRpc("initialize", { clientInfo: {
+			name: "graphorin-client",
+			version: "0.5.0"
+		} });
+	}
+	/** Send a `ping` RPC and resolve when the server replies with `pong`. */
+	async ping() {
+		await this.#sendRpc("ping");
+	}
+	/**
+	* Subscribe to a server-side event stream. Resolves with a
+	* {@link Subscription} once the server confirms with the matching
+	* `subscribed` frame; rejects when the server returns an
+	* `error` instead.
+	*/
+	async subscribe(target, opts) {
+		if (this.#transport === void 0) throw new ClientNotConnectedError();
+		if (this.#transport.kind === "sse") {
+			const subject$1 = subjectFor(target);
+			const boundSubject = `session:${this.#options.sessionId ?? ""}/events`;
+			if (subject$1 !== boundSubject) throw new TransportFailedError(`subscribe('${subject$1}') requires the WebSocket transport — the SSE fallback carries only the bound session stream ('${boundSubject}').`);
+			if (this.#sseSubscription === void 0) {
+				this.#sseSubscription = this.#createSubscription({
+					subscriptionId: "__sse__",
+					subject: subject$1,
+					target,
+					snapshotEventId: void 0
+				});
+				this.#subscriptions.set("__sse__", this.#sseSubscription);
+			}
+			return this.#sseSubscription;
+		}
+		const subject = subjectFor(target);
+		const lastEventId = opts?.sinceEventId ?? this.#transport.lastEventId;
+		const params = { subject };
+		if (lastEventId !== void 0) params.sinceEventId = lastEventId;
+		const result = await this.#sendRpc("subscription.subscribe", params);
+		const subscriptionId = typeof result.subscriptionId === "string" && result.subscriptionId.length > 0 ? result.subscriptionId : void 0;
+		if (subscriptionId === void 0) throw new ProtocolViolationError("Server subscribe reply missing subscriptionId.");
+		const snapshotEventId = typeof result.snapshotEventId === "string" ? result.snapshotEventId : void 0;
+		const sub = this.#createSubscription({
+			subscriptionId,
+			subject,
+			target,
+			snapshotEventId
+		});
+		this.#subscriptions.set(subscriptionId, sub);
+		return sub;
+	}
+	/**
+	* Cancel a server-side run. Sends the `run.cancel` RPC and
+	* resolves with the server's `result` payload (typically
+	* `{ cancelled: true, partialStateAvailable: true }`).
+	*/
+	async cancel(runId, opts = {}) {
+		if (typeof runId !== "string" || runId.length === 0) throw new TypeError("cancel: runId must be a non-empty string.");
+		const params = { runId };
+		if (opts.drain !== void 0) params.drain = opts.drain;
+		if (opts.reason !== void 0) params.reason = opts.reason;
+		if (opts.onPendingApprovals !== void 0) params.onPendingApprovals = opts.onPendingApprovals;
+		return this.#sendRpc("run.cancel", params);
+	}
+	/**
+	* Resume a paused (HITL) run. The WebSocket protocol intentionally
+	* does NOT carry a `resume` control message — resumes are durable
+	* + idempotent + body-carrying, which maps onto the REST endpoint
+	* `POST /v1/runs/:runId/resume`. NOTE (IP-14): the server endpoint
+	* currently answers **501** — server-side durable resume is not
+	* implemented yet. Library-mode callers resume directly:
+	* `agent.run(result.state, { directive })`.
+	*/
+	async resume(runId, directive, opts = {}) {
+		if (typeof runId !== "string" || runId.length === 0) throw new TypeError("resume: runId must be a non-empty string.");
+		const fetchImpl = this.#options.fetch ?? globalThis.fetch;
+		if (typeof fetchImpl !== "function") throw new TransportFailedError("No fetch implementation available; pass `fetch` via the client options.");
+		const url = joinUrl(this.#options.baseUrl, `/v1/runs/${encodeURIComponent(runId)}/resume`, { ws: false });
+		const headers = { "Content-Type": "application/json" };
+		if (this.#options.auth.kind === "bearer") headers.Authorization = `Bearer ${this.#options.auth.token}`;
+		if (opts.idempotencyKey !== void 0) headers["Idempotency-Key"] = opts.idempotencyKey;
+		const res = await fetchImpl(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(directive === void 0 ? {} : { directive })
+		});
+		if (!res.ok) throw new TransportFailedError(`resume(${runId}): server responded ${res.status} ${res.statusText}.`, { code: res.status });
+		try {
+			return await res.json();
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Send an MCP-compatible cancellation notification. Does not wait
+	* for a server reply (notifications have no `id`).
+	*/
+	cancelNotify(requestId) {
+		if (this.#transport === void 0) throw new ClientNotConnectedError();
+		if (typeof requestId !== "string" || requestId.length === 0) throw new TypeError("cancelNotify: requestId must be a non-empty string.");
+		const frame = {
+			v: "1",
+			jsonrpc: "2.0",
+			method: "notifications/cancelled",
+			params: { requestId }
+		};
+		this.#transport.send(frame);
+	}
+	/**
+	* Disconnect the underlying transport and abort every pending RPC
+	* + subscription. Idempotent.
+	*/
+	async disconnect() {
+		if (this.#closed) return;
+		this.#closed = true;
+		const transport = this.#transport;
+		this.#transport = void 0;
+		this.#abortController.abort(new ClientAbortedError());
+		for (const pending of this.#pending.values()) pending.reject(new ClientAbortedError("Client disconnected before reply."));
+		this.#pending.clear();
+		for (const sub of this.#subscriptions.values()) sub.__close("aborted", new ClientAbortedError("Client disconnected."));
+		this.#subscriptions.clear();
+		if (transport !== void 0) try {
+			transport.close(1e3, "client-disconnect");
+		} catch {}
+	}
+	/** Return the active transport kind (or `undefined` if not connected). */
+	get transportKind() {
+		return this.#transport?.kind;
+	}
+	async #openWs() {
+		return await openWebSocketTransport({
+			url: this.#wsUrl(),
+			auth: this.#options.auth,
+			...this.#options.WebSocket !== void 0 ? { WebSocket: this.#options.WebSocket } : {},
+			...this.#options.clientId !== void 0 ? { clientId: this.#options.clientId } : {}
+		}, this.#listeners("ws"));
+	}
+	async #openSse() {
+		if (this.#options.auth.kind !== "bearer") throw new TransportFailedError("SSE fallback requires the 'bearer' auth strategy. The WebSocket ticket flow does not extend to EventSource.");
+		return await openSseTransport({
+			url: this.#sseUrl(),
+			auth: this.#options.auth,
+			...this.#options.fetch !== void 0 ? { fetch: this.#options.fetch } : {},
+			...this.#options.clientId !== void 0 ? { clientId: this.#options.clientId } : {}
+		}, this.#listeners("sse"));
+	}
+	#wsUrl() {
+		const path = this.#options.wsPath ?? "/v1/ws";
+		return joinUrl(this.#options.baseUrl, path, { ws: true });
+	}
+	#sseUrl() {
+		const template = this.#options.sseSessionPath ?? "/v1/sessions/:sessionId/events";
+		if (template.includes(":sessionId")) {
+			const sessionId = this.#options.sessionId;
+			if (sessionId === void 0 || sessionId.length === 0) throw new TransportFailedError("The SSE fallback needs a session binding — pass `sessionId` in the client options (it fills ':sessionId' in sseSessionPath).");
+			return joinUrl(this.#options.baseUrl, template.replace(":sessionId", encodeURIComponent(sessionId)), { ws: false });
+		}
+		return joinUrl(this.#options.baseUrl, template, { ws: false });
+	}
+	#listeners(kind) {
+		return {
+			onOpen: () => {},
+			onFrame: (frame) => this.#handleFrame(frame),
+			onError: (err) => this.#handleTransportError(err, kind),
+			onClose: (reason) => this.#handleTransportClose(reason, kind)
+		};
+	}
+	#handleFrame(frame) {
+		if (isRpcSuccess(frame)) {
+			const pending = this.#pending.get(frame.id);
+			if (pending !== void 0) {
+				this.#pending.delete(frame.id);
+				pending.resolve(frame.result);
+			}
+			return;
+		}
+		if (isRpcFailure(frame)) {
+			const pending = this.#pending.get(frame.id);
+			if (pending !== void 0) {
+				this.#pending.delete(frame.id);
+				pending.reject(new GraphorinClientError(kindForRpcCode(frame.error.code), `Server returned an error for RPC '${frame.id}': ${frame.error.message} (code=${frame.error.code}).`));
+			}
+			return;
+		}
+		if (isSubscribedFrame(frame)) return;
+		if (isUnsubscribedFrame(frame)) {
+			const sub = this.#subscriptions.get(frame.subscriptionId);
+			if (sub !== void 0) {
+				sub.__close("unsubscribed");
+				this.#subscriptions.delete(frame.subscriptionId);
+			}
+			return;
+		}
+		if (isPongFrame(frame)) return;
+		if (isLifecycleFrame(frame)) {
+			const sub = this.#subscriptions.get(frame.subscriptionId) ?? this.#sseFallback();
+			if (sub !== void 0) sub.__pushLifecycle(frame);
+			return;
+		}
+		if (isReplayMarkerFrame(frame)) {
+			const sub = this.#subscriptions.get(frame.subscriptionId) ?? this.#sseFallback();
+			if (sub !== void 0) sub.__pushReplayMarker(frame);
+			return;
+		}
+		if (isEventFrame(frame)) {
+			const sub = this.#subscriptions.get(frame.subscriptionId) ?? this.#sseFallback();
+			if (sub !== void 0) sub.__push(frame);
+			return;
+		}
+		if (isErrorFrame(frame)) {
+			const target = frame.subscriptionId !== void 0 ? this.#subscriptions.get(frame.subscriptionId) : void 0;
+			const error = new GraphorinClientError("protocol-violation", `Server error frame: ${frame.message} (code=${frame.code}).`);
+			if (target !== void 0) {
+				target.__close("aborted", error);
+				if (frame.subscriptionId !== void 0) this.#subscriptions.delete(frame.subscriptionId);
+			}
+		}
+	}
+	/**
+	* IP-3: on the SSE transport every frame belongs to the single
+	* implicit session subscription regardless of the server-generated
+	* subscriptionId it carries.
+	*/
+	#sseFallback() {
+		return this.#transport?.kind === "sse" ? this.#sseSubscription : void 0;
+	}
+	#handleTransportError(err, _kind) {
+		for (const pending of this.#pending.values()) pending.reject(err);
+		this.#pending.clear();
+	}
+	async #handleTransportClose(reason, _kind) {
+		if (this.#closed) return;
+		this.#transport = void 0;
+		const closeError = new TransportFailedError(`Transport closed: ${reason.reason || reason.graphorinReason || "unknown"} (code=${reason.code}).`, { code: reason.code });
+		for (const pending of this.#pending.values()) pending.reject(closeError);
+		this.#pending.clear();
+		if (reason.graphorinReason === "auth.required" || reason.graphorinReason === "auth.invalid" || reason.graphorinReason === "auth.revoked" || reason.graphorinReason === "protocol.violation") {
+			for (const sub of this.#subscriptions.values()) sub.__close("aborted", closeError);
+			this.#subscriptions.clear();
+			return;
+		}
+		await this.#reconnect();
+	}
+	async #reconnect() {
+		if (this.#closed) return;
+		let attempt = 0;
+		while (!this.#closed) {
+			attempt += 1;
+			const delay = computeBackoffMs(attempt, this.#options.reconnect);
+			if (delay === null) {
+				const exhausted = new TransportFailedError(`Reconnect attempts exhausted after ${attempt - 1} retries.`);
+				for (const sub of this.#subscriptions.values()) sub.__close("aborted", exhausted);
+				this.#subscriptions.clear();
+				return;
+			}
+			try {
+				await sleep(delay, this.#abortController.signal);
+				await this.connect();
+				if (this.#transport === void 0) continue;
+				for (const [oldId, sub] of [...this.#subscriptions]) {
+					this.#subscriptions.delete(oldId);
+					try {
+						const cursor = sub.__lastEventId();
+						const result = await this.#sendRpc("subscription.subscribe", {
+							subject: sub.__subject(),
+							...cursor !== void 0 ? { sinceEventId: cursor } : {}
+						});
+						const newId = typeof result.subscriptionId === "string" && result.subscriptionId.length > 0 ? result.subscriptionId : void 0;
+						if (newId === void 0) throw new ProtocolViolationError("Server resubscribe reply missing subscriptionId.");
+						sub.__rebind(newId);
+						this.#subscriptions.set(newId, sub);
+					} catch (err) {
+						sub.__close("aborted", err instanceof Error ? err : new Error(String(err)));
+					}
+				}
+				return;
+			} catch (err) {
+				if (this.#closed) return;
+				if (err instanceof ClientAbortedError) return;
+			}
+		}
+	}
+	#createSubscription(args) {
+		const queue = [];
+		const lifecycle = [];
+		const replayMarkers = [];
+		const waiters = [];
+		let closed = false;
+		let closeError;
+		let lastEventId = args.snapshotEventId;
+		const push = (frame) => {
+			lastEventId = frame.eventId;
+			const waiter = waiters.shift();
+			if (waiter !== void 0) {
+				waiter.resolve({
+					value: frame,
+					done: false
+				});
+				return;
+			}
+			queue.push(frame);
+		};
+		const close = (reason, err) => {
+			if (closed) return;
+			closed = true;
+			if (err !== void 0) closeError = err;
+			else if (reason === "aborted") closeError = new ClientAbortedError();
+			while (waiters.length > 0) {
+				const waiter = waiters.shift();
+				if (waiter === void 0) continue;
+				if (closeError !== void 0) waiter.reject(closeError);
+				else waiter.resolve({
+					value: void 0,
+					done: true
+				});
+			}
+		};
+		return {
+			get subscriptionId() {
+				return args.subscriptionId;
+			},
+			subject: args.subject,
+			events: () => ({ [Symbol.asyncIterator]: () => ({
+				next: () => {
+					const buffered = queue.shift();
+					if (buffered !== void 0) return Promise.resolve({
+						value: buffered,
+						done: false
+					});
+					if (closed) {
+						if (closeError !== void 0) return Promise.reject(closeError);
+						return Promise.resolve({
+							value: void 0,
+							done: true
+						});
+					}
+					return new Promise((resolve, reject) => {
+						waiters.push({
+							resolve,
+							reject
+						});
+					});
+				},
+				return: () => {
+					close("unsubscribed");
+					return Promise.resolve({
+						value: void 0,
+						done: true
+					});
+				}
+			}) }),
+			unsubscribe: async () => {
+				if (closed) return;
+				try {
+					await this.#sendRpc("subscription.unsubscribe", { subscriptionId: args.subscriptionId });
+				} catch (err) {
+					if (!(err instanceof ClientAbortedError)) throw err;
+				}
+				close("unsubscribed");
+				this.#subscriptions.delete(args.subscriptionId);
+			},
+			metadata: () => ({
+				id: args.subscriptionId,
+				subject: args.subject,
+				target: args.target,
+				snapshotEventId: args.snapshotEventId,
+				lastEventId,
+				closed
+			}),
+			__push: push,
+			__pushLifecycle: (frame) => {
+				lifecycle.push(frame);
+				if (frame.status === "completed" || frame.status === "aborted" || frame.status === "failed") {
+					close(frame.status === "completed" ? "unsubscribed" : "aborted");
+					this.#subscriptions.delete(args.subscriptionId);
+				}
+			},
+			__pushReplayMarker: (frame) => {
+				replayMarkers.push(frame);
+			},
+			__close: close,
+			__subject: () => args.subject,
+			__target: () => args.target,
+			__snapshotEventId: () => args.snapshotEventId,
+			__lastEventId: () => lastEventId,
+			__rebind: (newSubscriptionId) => {
+				args.subscriptionId = newSubscriptionId;
+			}
+		};
+	}
+	async #sendRpc(method, params) {
+		if (this.#transport === void 0) throw new ClientNotConnectedError();
+		const id = this.#nextId();
+		const frame = buildRpcFrame(method, id, params);
+		const timeoutMs = this.#options.rpcTimeoutMs;
+		return new Promise((resolve, reject) => {
+			let timer;
+			const clear = () => {
+				if (timer !== void 0) {
+					clearTimeout(timer);
+					timer = void 0;
+				}
+			};
+			const pending = {
+				resolve: (value) => {
+					clear();
+					resolve(value);
+				},
+				reject: (reason) => {
+					clear();
+					reject(reason);
+				}
+			};
+			this.#pending.set(id, pending);
+			if (timeoutMs !== void 0 && timeoutMs > 0) timer = setTimeout(() => {
+				if (this.#pending.get(id) === pending) {
+					this.#pending.delete(id);
+					reject(new TransportFailedError(`RPC '${method}' (id=${id}) timed out after ${timeoutMs}ms with no server reply.`));
+				}
+			}, timeoutMs);
+			try {
+				this.#transport.send(frame);
+			} catch (err) {
+				clear();
+				this.#pending.delete(id);
+				reject(err);
+			}
+		});
+	}
+	#nextId() {
+		this.#idCounter += 1;
+		return `${this.#options.clientId ?? "graphorin"}-${this.#idCounter.toString(36)}`;
+	}
+};
+function subjectFor(target) {
+	switch (target.target) {
+		case "session":
+			assertNonEmpty(target.id, "session.id");
+			return `session:${target.id}/events`;
+		case "agent":
+			assertNonEmpty(target.id, "agent.id");
+			assertNonEmpty(target.runId, "agent.runId");
+			return `agent:${target.id}/runs/${target.runId}/events`;
+		case "run":
+			assertNonEmpty(target.runId, "run.runId");
+			if (target.sessionId !== void 0) {
+				assertNonEmpty(target.sessionId, "run.sessionId");
+				return `session:${target.sessionId}/runs/${target.runId}/events`;
+			}
+			return `run:${target.runId}/events`;
+		case "workflow":
+			assertNonEmpty(target.id, "workflow.id");
+			return `workflow:${target.id}/events`;
+	}
+}
+function assertNonEmpty(value, fieldName) {
+	if (typeof value !== "string" || value.length === 0) throw new TypeError(`${fieldName} must be a non-empty string.`);
+}
+function joinUrl(baseUrl, path, opts) {
+	let normalized = baseUrl;
+	if (opts.ws) {
+		if (normalized.startsWith("http://")) normalized = normalized.replace(/^http:\/\//, "ws://");
+		else if (normalized.startsWith("https://")) normalized = normalized.replace(/^https:\/\//, "wss://");
+	} else if (normalized.startsWith("ws://")) normalized = normalized.replace(/^ws:\/\//, "http://");
+	else if (normalized.startsWith("wss://")) normalized = normalized.replace(/^wss:\/\//, "https://");
+	if (normalized.endsWith("/")) normalized = normalized.slice(0, -1);
+	const tail = path.startsWith("/") ? path : `/${path}`;
+	return `${normalized}${tail}`;
+}
+function buildRpcFrame(method, id, params) {
+	switch (method) {
+		case "initialize": return {
+			v: "1",
+			jsonrpc: "2.0",
+			id,
+			method: "initialize",
+			params: params ?? { clientInfo: {
+				name: "graphorin-client",
+				version: "0.5.0"
+			} }
+		};
+		case "subscription.subscribe": return {
+			v: "1",
+			jsonrpc: "2.0",
+			id,
+			method: "subscription.subscribe",
+			params: params ?? { subject: "" }
+		};
+		case "subscription.unsubscribe": return {
+			v: "1",
+			jsonrpc: "2.0",
+			id,
+			method: "subscription.unsubscribe",
+			params: params ?? { subscriptionId: "" }
+		};
+		case "run.cancel": return {
+			v: "1",
+			jsonrpc: "2.0",
+			id,
+			method: "run.cancel",
+			params: params ?? { runId: "" }
+		};
+		case "ping": return {
+			v: "1",
+			jsonrpc: "2.0",
+			id,
+			method: "ping",
+			...params !== void 0 ? { params } : {}
+		};
+		case "notifications/cancelled": throw new TypeError("buildRpcFrame: 'notifications/cancelled' is a notification, not an RPC.");
+	}
+	throw new TypeError(`Unknown RPC method '${method}'.`);
+}
+
+//#endregion
+export { GraphorinClient };
+//# sourceMappingURL=graphorin-client.js.map