@the-open-engine/zeroshot 6.10.2 → 6.12.0

package/lib/cluster/generated/protocol.mjs

@@ -0,0 +1,19 @@
+// Generated by scripts/generate-cluster-types.js from the checked-in Cluster Protocol v1 artifacts.
+// Do not edit this file by hand. Run npm run protocol:generate.
+export const JSON_RPC_VERSION = "2.0";
+export const PROTOCOL_VERSION = "openengine.cluster/v1";
+export const SUBSCRIPTION_QUEUE_CAPACITY = 1024;
+export const MAX_FRAME_BYTES = 1048576;
+export const CLUSTER_METHODS = ["initialize", "plan", "apply", "update", "stop", "retry", "resubmit", "delete", "get", "watch", "logs", "agent/attach"];
+export const UNARY_METHODS = ["initialize", "plan", "apply", "update", "stop", "retry", "resubmit", "delete", "get"];
+export const SUBSCRIPTION_METHODS = ["watch", "logs", "agent/attach"];
+export const METHOD_RESULT_DEFINITIONS = { "initialize": "InitializeResult", "plan": "PlanResult", "apply": "ApplyResult", "update": "UpdateResult", "stop": "StopResult", "retry": "RetryResult", "resubmit": "ResubmitResult", "delete": "DeleteResult", "get": "GetResult", "watch": "WatchResult", "logs": "LogsResult", "agent/attach": "AgentAttachResult" };
+export const JSON_RPC_ERROR_CODES = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    APPLICATION_ERROR: -32000,
+};
+export const DOMAIN_ERROR_CODES = ["NOT_FOUND", "GONE", "SLOW_CONSUMER", "UNSUPPORTED_PROTOCOL_VERSION", "INTERNAL_ERROR"];

package/lib/cluster/index.cjs

@@ -0,0 +1,40 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connect = exports.ClusterClient = exports.WatchSubscriptionStream = exports.LogsSubscriptionStream = exports.AgentAttachSubscriptionStream = exports.Connection = exports.PROTOCOL_DIAGNOSTIC_CAPACITY = exports.CONNECTION_TRANSITIONS = exports.ClusterTransportError = exports.ClusterTimeoutError = exports.ClusterStateError = exports.ClusterRpcError = exports.ClusterProtocolError = exports.ClusterInternalError = exports.ClusterError = exports.ClusterConfigError = exports.SUBSCRIPTION_QUEUE_MAX_BYTES = void 0;
+__exportStar(require("./generated/protocol.cjs"), exports);
+var queue_js_1 = require("./queue.cjs");
+Object.defineProperty(exports, "SUBSCRIPTION_QUEUE_MAX_BYTES", { enumerable: true, get: function () { return queue_js_1.SUBSCRIPTION_QUEUE_MAX_BYTES; } });
+var errors_js_1 = require("./errors.cjs");
+Object.defineProperty(exports, "ClusterConfigError", { enumerable: true, get: function () { return errors_js_1.ClusterConfigError; } });
+Object.defineProperty(exports, "ClusterError", { enumerable: true, get: function () { return errors_js_1.ClusterError; } });
+Object.defineProperty(exports, "ClusterInternalError", { enumerable: true, get: function () { return errors_js_1.ClusterInternalError; } });
+Object.defineProperty(exports, "ClusterProtocolError", { enumerable: true, get: function () { return errors_js_1.ClusterProtocolError; } });
+Object.defineProperty(exports, "ClusterRpcError", { enumerable: true, get: function () { return errors_js_1.ClusterRpcError; } });
+Object.defineProperty(exports, "ClusterStateError", { enumerable: true, get: function () { return errors_js_1.ClusterStateError; } });
+Object.defineProperty(exports, "ClusterTimeoutError", { enumerable: true, get: function () { return errors_js_1.ClusterTimeoutError; } });
+Object.defineProperty(exports, "ClusterTransportError", { enumerable: true, get: function () { return errors_js_1.ClusterTransportError; } });
+var connection_js_1 = require("./connection.cjs");
+Object.defineProperty(exports, "CONNECTION_TRANSITIONS", { enumerable: true, get: function () { return connection_js_1.CONNECTION_TRANSITIONS; } });
+Object.defineProperty(exports, "PROTOCOL_DIAGNOSTIC_CAPACITY", { enumerable: true, get: function () { return connection_js_1.PROTOCOL_DIAGNOSTIC_CAPACITY; } });
+Object.defineProperty(exports, "Connection", { enumerable: true, get: function () { return connection_js_1.Connection; } });
+var subscriptions_js_1 = require("./subscriptions.cjs");
+Object.defineProperty(exports, "AgentAttachSubscriptionStream", { enumerable: true, get: function () { return subscriptions_js_1.AgentAttachSubscriptionStream; } });
+Object.defineProperty(exports, "LogsSubscriptionStream", { enumerable: true, get: function () { return subscriptions_js_1.LogsSubscriptionStream; } });
+Object.defineProperty(exports, "WatchSubscriptionStream", { enumerable: true, get: function () { return subscriptions_js_1.WatchSubscriptionStream; } });
+var client_js_1 = require("./client.cjs");
+Object.defineProperty(exports, "ClusterClient", { enumerable: true, get: function () { return client_js_1.ClusterClient; } });
+Object.defineProperty(exports, "connect", { enumerable: true, get: function () { return client_js_1.connect; } });

package/lib/cluster/index.d.ts

@@ -0,0 +1,10 @@
+export * from './generated/protocol.js';
+export { SUBSCRIPTION_QUEUE_MAX_BYTES } from './queue.js';
+export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, } from './errors.js';
+export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
+export type { CallOptions, ConnectionState, } from './connection.js';
+export type { WebSocketLike } from './socket.js';
+export { AgentAttachSubscriptionStream, LogsSubscriptionStream, WatchSubscriptionStream, } from './subscriptions.js';
+export type { Subscription, SubscriptionClosedItem, SubscriptionItem, WatchSubscriptionItem, WatchSubscriptionClosedItem, } from './subscriptions.js';
+export { ClusterClient, connect } from './client.js';
+export type { AgentAttachSubscription, CoherentWatchSubscription, ConnectOptions, LogsSubscription, WatchSubscription, } from './client.js';

package/lib/cluster/index.mjs

@@ -0,0 +1,6 @@
+export * from './generated/protocol.mjs';
+export { SUBSCRIPTION_QUEUE_MAX_BYTES } from './queue.mjs';
+export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, } from './errors.mjs';
+export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.mjs';
+export { AgentAttachSubscriptionStream, LogsSubscriptionStream, WatchSubscriptionStream, } from './subscriptions.mjs';
+export { ClusterClient, connect } from './client.mjs';

package/lib/cluster/queue.cjs

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedQueue = exports.SUBSCRIPTION_QUEUE_MAX_BYTES = void 0;
+const protocol_js_1 = require("./generated/protocol.cjs");
+const errors_js_1 = require("./errors.cjs");
+exports.SUBSCRIPTION_QUEUE_MAX_BYTES = 8 * 1024 * 1024;
+function deferred() {
+    let resolve;
+    const promise = new Promise((onResolve) => { resolve = onResolve; });
+    return { promise, resolve };
+}
+class BoundedQueue {
+    #items = [];
+    #waiters = [];
+    #bytes = 0;
+    #producerClosed = false;
+    get retainedCount() { return this.#items.length; }
+    push(value, bytes) {
+        if (this.#producerClosed)
+            return 'closed';
+        const waiter = this.#waiters.shift();
+        if (waiter) {
+            waiter.resolve({ done: false, value });
+            this.#assertInvariant();
+            return 'delivered';
+        }
+        if (this.#items.length >= protocol_js_1.SUBSCRIPTION_QUEUE_CAPACITY ||
+            this.#bytes + bytes > exports.SUBSCRIPTION_QUEUE_MAX_BYTES)
+            return 'overflow';
+        this.#items.push({ value, bytes });
+        this.#bytes += bytes;
+        this.#assertInvariant();
+        return 'buffered';
+    }
+    recv() {
+        const item = this.#items.shift();
+        if (item) {
+            this.#bytes -= item.bytes;
+            this.#assertInvariant();
+            return Promise.resolve({ done: false, value: item.value });
+        }
+        if (this.#producerClosed)
+            return Promise.resolve({ done: true });
+        const waiter = deferred();
+        this.#waiters.push(waiter);
+        this.#assertInvariant();
+        return waiter.promise;
+    }
+    endRetainingBuffer() {
+        if (this.#producerClosed)
+            return;
+        this.#producerClosed = true;
+        while (this.#waiters.length > 0)
+            this.#waiters.shift().resolve({ done: true });
+        this.#assertInvariant();
+    }
+    closeAndDiscard() {
+        this.#producerClosed = true;
+        this.#items.length = 0;
+        this.#bytes = 0;
+        while (this.#waiters.length > 0)
+            this.#waiters.shift().resolve({ done: true });
+        this.#assertInvariant();
+    }
+    #assertInvariant() {
+        if (this.#items.length > 0 && this.#waiters.length > 0) {
+            throw new errors_js_1.ClusterInternalError('queue contains both buffered items and waiters', 'QUEUE_INVARIANT');
+        }
+    }
+}
+exports.BoundedQueue = BoundedQueue;

package/lib/cluster/queue.d.ts

@@ -0,0 +1,15 @@
+export declare const SUBSCRIPTION_QUEUE_MAX_BYTES: number;
+export type QueueValue<T> = {
+    readonly done: false;
+    readonly value: T;
+} | {
+    readonly done: true;
+};
+export declare class BoundedQueue<T> {
+    #private;
+    get retainedCount(): number;
+    push(value: T, bytes: number): 'buffered' | 'delivered' | 'overflow' | 'closed';
+    recv(): Promise<QueueValue<T>>;
+    endRetainingBuffer(): void;
+    closeAndDiscard(): void;
+}

package/lib/cluster/queue.mjs

@@ -0,0 +1,67 @@
+import { SUBSCRIPTION_QUEUE_CAPACITY } from './generated/protocol.mjs';
+import { ClusterInternalError } from './errors.mjs';
+export const SUBSCRIPTION_QUEUE_MAX_BYTES = 8 * 1024 * 1024;
+function deferred() {
+    let resolve;
+    const promise = new Promise((onResolve) => { resolve = onResolve; });
+    return { promise, resolve };
+}
+export class BoundedQueue {
+    #items = [];
+    #waiters = [];
+    #bytes = 0;
+    #producerClosed = false;
+    get retainedCount() { return this.#items.length; }
+    push(value, bytes) {
+        if (this.#producerClosed)
+            return 'closed';
+        const waiter = this.#waiters.shift();
+        if (waiter) {
+            waiter.resolve({ done: false, value });
+            this.#assertInvariant();
+            return 'delivered';
+        }
+        if (this.#items.length >= SUBSCRIPTION_QUEUE_CAPACITY ||
+            this.#bytes + bytes > SUBSCRIPTION_QUEUE_MAX_BYTES)
+            return 'overflow';
+        this.#items.push({ value, bytes });
+        this.#bytes += bytes;
+        this.#assertInvariant();
+        return 'buffered';
+    }
+    recv() {
+        const item = this.#items.shift();
+        if (item) {
+            this.#bytes -= item.bytes;
+            this.#assertInvariant();
+            return Promise.resolve({ done: false, value: item.value });
+        }
+        if (this.#producerClosed)
+            return Promise.resolve({ done: true });
+        const waiter = deferred();
+        this.#waiters.push(waiter);
+        this.#assertInvariant();
+        return waiter.promise;
+    }
+    endRetainingBuffer() {
+        if (this.#producerClosed)
+            return;
+        this.#producerClosed = true;
+        while (this.#waiters.length > 0)
+            this.#waiters.shift().resolve({ done: true });
+        this.#assertInvariant();
+    }
+    closeAndDiscard() {
+        this.#producerClosed = true;
+        this.#items.length = 0;
+        this.#bytes = 0;
+        while (this.#waiters.length > 0)
+            this.#waiters.shift().resolve({ done: true });
+        this.#assertInvariant();
+    }
+    #assertInvariant() {
+        if (this.#items.length > 0 && this.#waiters.length > 0) {
+            throw new ClusterInternalError('queue contains both buffered items and waiters', 'QUEUE_INVARIANT');
+        }
+    }
+}

package/lib/cluster/socket.cjs

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addSocketListener = addSocketListener;
+const errors_js_1 = require("./errors.cjs");
+function addSocketListener(socket, type, listener) {
+    if (socket.addEventListener) {
+        socket.addEventListener(type, listener);
+        return () => socket.removeEventListener?.(type, listener);
+    }
+    if (socket.on) {
+        socket.on(type, listener);
+        return () => (socket.off ?? socket.removeListener)?.call(socket, type, listener);
+    }
+    throw new errors_js_1.ClusterConfigError('WebSocket implementation must support event listeners', 'INVALID_WEBSOCKET');
+}

package/lib/cluster/socket.d.ts

@@ -0,0 +1,11 @@
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string, callback?: (error?: Error) => void): void | Promise<void>;
+    close(code?: number, reason?: string): void | Promise<void>;
+    addEventListener?(type: string, listener: (...args: unknown[]) => void): void;
+    removeEventListener?(type: string, listener: (...args: unknown[]) => void): void;
+    on?(type: string, listener: (...args: unknown[]) => void): void;
+    off?(type: string, listener: (...args: unknown[]) => void): void;
+    removeListener?(type: string, listener: (...args: unknown[]) => void): void;
+}
+export declare function addSocketListener(socket: WebSocketLike, type: string, listener: (...args: unknown[]) => void): () => void;

package/lib/cluster/socket.mjs

@@ -0,0 +1,12 @@
+import { ClusterConfigError } from './errors.mjs';
+export function addSocketListener(socket, type, listener) {
+    if (socket.addEventListener) {
+        socket.addEventListener(type, listener);
+        return () => socket.removeEventListener?.(type, listener);
+    }
+    if (socket.on) {
+        socket.on(type, listener);
+        return () => (socket.off ?? socket.removeListener)?.call(socket, type, listener);
+    }
+    throw new ClusterConfigError('WebSocket implementation must support event listeners', 'INVALID_WEBSOCKET');
+}

package/lib/cluster/subscriptions.cjs

@@ -0,0 +1,270 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WatchSubscriptionStream = exports.AgentAttachSubscriptionStream = exports.LogsSubscriptionStream = void 0;
+const errors_js_1 = require("./errors.cjs");
+const frames_js_1 = require("./frames.cjs");
+const validators_js_1 = require("./validators.cjs");
+class SubscriptionStream {
+    connection;
+    registration;
+    parse;
+    #done = false;
+    constructor(connection, registration, parse) {
+        this.connection = connection;
+        this.registration = registration;
+        this.parse = parse;
+    }
+    get subscriptionId() { return this.registration.id; }
+    get retainedCount() { return this.registration.queue.retainedCount; }
+    [Symbol.asyncIterator]() { return this; }
+    async next() {
+        if (this.#done)
+            return { done: true, value: undefined };
+        const queued = await this.registration.queue.recv();
+        if (queued.done) {
+            if (this.registration.overflowed) {
+                this.registration.overflowed = false;
+                this.#done = true;
+                return { done: false, value: { type: 'closed', reason: 'SLOW_CONSUMER' } };
+            }
+            this.#done = true;
+            return { done: true, value: undefined };
+        }
+        try {
+            const value = this.parse(queued.value);
+            if (value.type === 'closed')
+                this.#finishWithoutCancel();
+            return { done: false, value };
+        }
+        catch (cause) {
+            await this.#terminate(true);
+            throw cause;
+        }
+    }
+    async return() {
+        await this.#terminate(true);
+        return { done: true, value: undefined };
+    }
+    async throw(error) {
+        await this.#terminate(true);
+        throw error;
+    }
+    cancel() { return this.#terminate(true); }
+    async #terminate(sendCancel) {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.connection.unregisterSubscription(this.registration.id, this.registration);
+        this.registration.queue.closeAndDiscard();
+        if (sendCancel) {
+            try {
+                await this.connection.cancelSubscription(this.registration);
+            }
+            catch (error) {
+                this.connection.recordDiagnostic(error);
+            }
+        }
+    }
+    #finishWithoutCancel() {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.connection.unregisterSubscription(this.registration.id, this.registration);
+        this.registration.queue.closeAndDiscard();
+    }
+}
+function parseCursorlessClosed(params, definition) {
+    (0, validators_js_1.assertDefinition)(definition, params);
+    return { type: 'closed', reason: params.reason };
+}
+function parseWatchClosed(params) {
+    (0, validators_js_1.assertDefinition)('SubscriptionClosedNotification', params);
+    const cursor = params.lastDeliveredCursor;
+    return {
+        type: 'closed',
+        reason: params.reason,
+        ...(cursor === undefined ? {} : { lastDeliveredCursor: cursor }),
+    };
+}
+function subscriptionParser(field, eventDefinition, closedDefinition) {
+    return (frame) => {
+        if (!(0, frames_js_1.isRecord)(frame.params)) {
+            throw new errors_js_1.ClusterProtocolError('notification params are missing', 'INVALID_SUBSCRIPTION_EVENT');
+        }
+        if (frame.method === 'subscription/closed') {
+            return parseCursorlessClosed(frame.params, closedDefinition);
+        }
+        if (frame.method !== 'event') {
+            throw new errors_js_1.ClusterProtocolError('malformed subscription event', 'INVALID_SUBSCRIPTION_EVENT');
+        }
+        (0, validators_js_1.assertDefinition)(eventDefinition, frame.params);
+        return { type: 'event', event: frame.params[field] };
+    };
+}
+class LogsSubscriptionStream extends SubscriptionStream {
+    constructor(connection, registration) {
+        super(connection, registration, subscriptionParser('record', 'LogEventNotification', 'LogsClosedNotification'));
+    }
+}
+exports.LogsSubscriptionStream = LogsSubscriptionStream;
+class AgentAttachSubscriptionStream extends SubscriptionStream {
+    constructor(connection, registration) {
+        super(connection, registration, subscriptionParser('event', 'AgentAttachEventNotification', 'AgentAttachClosedNotification'));
+    }
+}
+exports.AgentAttachSubscriptionStream = AgentAttachSubscriptionStream;
+class WatchSubscriptionStream {
+    #connection;
+    #registration;
+    #lastSeenRunId;
+    #lastSeenCursor;
+    #lastDelivered;
+    #runId;
+    #done = false;
+    #reconnectConsumed = false;
+    #readBarrier = Promise.resolve();
+    constructor(init) {
+        this.#connection = init.connection;
+        this.#registration = init.registration;
+        this.#lastSeenRunId = init.lastSeenRunId;
+        this.#lastSeenCursor = init.lastSeenCursor;
+        this.#lastDelivered = init.params.fromCursor;
+        this.#runId = init.result.runId ?? init.params.runId;
+    }
+    get subscriptionId() { return this.#registration.id; }
+    get retainedCount() { return this.#registration.queue.retainedCount; }
+    get lastDeliveredCursor() { return this.#lastDelivered; }
+    [Symbol.asyncIterator]() { return this; }
+    next() {
+        const read = this.#readBarrier.then(() => this.#nextLogical());
+        this.#readBarrier = read.then(() => undefined, () => undefined);
+        return read;
+    }
+    async #nextLogical() {
+        while (!this.#done) {
+            const queued = await this.#registration.queue.recv();
+            if (queued.done)
+                return this.#finishQueue();
+            const item = await this.#decode(queued.value);
+            if (item)
+                return { done: false, value: item };
+        }
+        return { done: true, value: undefined };
+    }
+    #finishQueue() {
+        this.#done = true;
+        if (!this.#registration.overflowed)
+            return { done: true, value: undefined };
+        this.#registration.overflowed = false;
+        const cursor = this.#lastDelivered;
+        return {
+            done: false,
+            value: { type: 'closed', reason: 'SLOW_CONSUMER', ...(cursor === undefined ? {} : { lastDeliveredCursor: cursor }) },
+        };
+    }
+    async #decode(frame) {
+        if (!(0, frames_js_1.isRecord)(frame.params))
+            return this.#invalid('notification params are missing');
+        if (frame.method === 'subscription/closed') {
+            const closed = parseWatchClosed(frame.params);
+            if (closed.lastDeliveredCursor !== undefined)
+                this.#lastDelivered = closed.lastDeliveredCursor;
+            this.#finishWithoutCancel();
+            return closed;
+        }
+        if (frame.method !== 'event')
+            return this.#invalid('malformed watch event');
+        try {
+            (0, validators_js_1.assertDefinition)('EventNotification', frame.params);
+        }
+        catch {
+            return this.#invalid('malformed watch event');
+        }
+        const { runId, cursor, event } = frame.params;
+        if (this.#lastSeenRunId === runId && this.#lastSeenCursor === cursor)
+            return undefined;
+        this.#lastSeenRunId = runId;
+        this.#lastSeenCursor = cursor;
+        this.#runId = runId;
+        this.#lastDelivered = cursor;
+        return { type: 'event', runId, cursor, event };
+    }
+    async return() {
+        await this.#terminate(true);
+        return { done: true, value: undefined };
+    }
+    async throw(error) {
+        await this.#terminate(true);
+        throw error;
+    }
+    cancel() { return this.#terminate(true); }
+    reconnect(freshConnection) {
+        if (this.#reconnectConsumed) {
+            throw new errors_js_1.ClusterStateError('watch stream reconnect is one-shot', 'RECONNECT_CONSUMED');
+        }
+        this.#reconnectConsumed = true;
+        return this.#reconnectOn(freshConnection);
+    }
+    async #reconnectOn(freshConnection) {
+        await this.#terminate(true);
+        try {
+            const runId = this.#runId;
+            const fromCursor = this.#lastDelivered;
+            const params = {
+                ...(runId === undefined ? {} : { runId }),
+                ...(fromCursor === undefined ? {} : { fromCursor }),
+            };
+            const established = await freshConnection.openSubscription('watch', params);
+            return {
+                result: established.result,
+                stream: new _a({
+                    connection: freshConnection,
+                    registration: established.registration,
+                    result: established.result,
+                    params,
+                    ...(this.#lastSeenRunId === undefined ? {} : { lastSeenRunId: this.#lastSeenRunId }),
+                    ...(this.#lastSeenCursor === undefined ? {} : { lastSeenCursor: this.#lastSeenCursor }),
+                }),
+            };
+        }
+        catch (error) {
+            await freshConnection.close();
+            throw error;
+        }
+    }
+    async #terminate(sendCancel) {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.#connection.unregisterSubscription(this.#registration.id, this.#registration);
+        this.#registration.queue.closeAndDiscard();
+        if (sendCancel) {
+            try {
+                await this.#connection.cancelSubscription(this.#registration);
+            }
+            catch (error) {
+                this.#connection.recordDiagnostic(error);
+            }
+        }
+    }
+    #finishWithoutCancel() {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.#connection.unregisterSubscription(this.#registration.id, this.#registration);
+        this.#registration.queue.closeAndDiscard();
+    }
+    async #invalid(message) {
+        await this.#terminate(true);
+        throw new errors_js_1.ClusterProtocolError(message, 'INVALID_SUBSCRIPTION_EVENT');
+    }
+}
+exports.WatchSubscriptionStream = WatchSubscriptionStream;
+_a = WatchSubscriptionStream;
+Object.defineProperty(SubscriptionStream.prototype, Symbol.asyncDispose, {
+    configurable: true, value: SubscriptionStream.prototype.cancel,
+});
+Object.defineProperty(WatchSubscriptionStream.prototype, Symbol.asyncDispose, {
+    configurable: true, value: WatchSubscriptionStream.prototype.cancel,
+});

package/lib/cluster/subscriptions.d.ts

@@ -0,0 +1,69 @@
+import type { AgentAttachEvent, LogRecord, SubscriptionCloseReason, WatchEvent, WatchParams, WatchResult } from './generated/protocol.js';
+import { Connection } from './connection.js';
+import type { SubscriptionRegistration } from './connection.js';
+import type { FrameRecord } from './frames.js';
+export type SubscriptionClosedItem = {
+    readonly type: 'closed';
+    readonly reason: SubscriptionCloseReason;
+};
+export type WatchSubscriptionClosedItem = SubscriptionClosedItem & {
+    readonly lastDeliveredCursor?: string | null;
+};
+export type SubscriptionItem<T> = {
+    readonly type: 'event';
+    readonly event: T;
+} | SubscriptionClosedItem;
+export type WatchSubscriptionItem = {
+    readonly type: 'event';
+    readonly runId: string;
+    readonly cursor: string;
+    readonly event: WatchEvent;
+} | WatchSubscriptionClosedItem;
+export interface Subscription<T> extends AsyncIterator<SubscriptionItem<T>>, AsyncIterable<SubscriptionItem<T>> {
+    readonly subscriptionId: string;
+    readonly retainedCount: number;
+    cancel(): Promise<void>;
+}
+type FrameParser<T> = (frame: FrameRecord) => SubscriptionItem<T>;
+declare class SubscriptionStream<T> implements Subscription<T> {
+    #private;
+    protected readonly connection: Connection;
+    protected readonly registration: SubscriptionRegistration;
+    private readonly parse;
+    constructor(connection: Connection, registration: SubscriptionRegistration, parse: FrameParser<T>);
+    get subscriptionId(): string;
+    get retainedCount(): number;
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<SubscriptionItem<T>>>;
+    return(): Promise<IteratorResult<SubscriptionItem<T>>>;
+    throw(error?: unknown): Promise<IteratorResult<SubscriptionItem<T>>>;
+    cancel(): Promise<void>;
+}
+export declare class LogsSubscriptionStream extends SubscriptionStream<LogRecord> {
+    constructor(connection: Connection, registration: SubscriptionRegistration);
+}
+export declare class AgentAttachSubscriptionStream extends SubscriptionStream<AgentAttachEvent> {
+    constructor(connection: Connection, registration: SubscriptionRegistration);
+}
+type WatchStreamInit = {
+    readonly connection: Connection;
+    readonly registration: SubscriptionRegistration;
+    readonly result: WatchResult;
+    readonly params: WatchParams;
+    readonly lastSeenRunId?: string;
+    readonly lastSeenCursor?: string;
+};
+export declare class WatchSubscriptionStream implements AsyncIterator<WatchSubscriptionItem>, AsyncIterable<WatchSubscriptionItem> {
+    #private;
+    constructor(init: WatchStreamInit);
+    get subscriptionId(): string;
+    get retainedCount(): number;
+    get lastDeliveredCursor(): string | null | undefined;
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<WatchSubscriptionItem>>;
+    return(): Promise<IteratorResult<WatchSubscriptionItem>>;
+    throw(error?: unknown): Promise<IteratorResult<WatchSubscriptionItem>>;
+    cancel(): Promise<void>;
+    reconnect(freshConnection: Connection): Promise<import('./client.js').WatchSubscription>;
+}
+export {};