@the-open-engine/zeroshot 6.28.0 → 6.29.1

package/lib/cluster/index.cjs

@@ -14,7 +14,7 @@ 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.connectInitialized = exports.connect = exports.ClusterClient = exports.WatchSubscriptionStream = exports.LogsSubscriptionStream = exports.AgentAttachSubscriptionStream = exports.Connection = exports.PROTOCOL_DIAGNOSTIC_CAPACITY = exports.CONNECTION_TRANSITIONS = exports.CLOSE_REASON_MAX_BYTES = exports.assertGraphSpec = exports.assertGraphProfileSupported = exports.assertGraphProfile = exports.ClusterTransportError = exports.ClusterTimeoutError = exports.ClusterStateError = exports.ClusterRpcError = exports.ClusterRequestError = exports.ClusterProtocolError = exports.ClusterInternalError = exports.ClusterError = exports.ClusterConfigError = exports.SUBSCRIPTION_QUEUE_MAX_BYTES = void 0;
+exports.connectInitialized = exports.connect = exports.ClusterClient = exports.WatchSubscriptionStream = exports.LogsSubscriptionStream = exports.AgentAttachSubscriptionStream = exports.Connection = exports.PROTOCOL_DIAGNOSTIC_CAPACITY = exports.CONNECTION_TRANSITIONS = exports.assertGraphSpec = exports.assertGraphProfileSupported = exports.assertGraphProfile = exports.ClusterUpgradeError = exports.ClusterTransportError = exports.ClusterTimeoutError = exports.ClusterStateError = exports.ClusterRpcError = exports.ClusterRequestError = 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; } });
@@ -28,6 +28,7 @@ Object.defineProperty(exports, "ClusterRpcError", { enumerable: true, get: funct
 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; } });
+Object.defineProperty(exports, "ClusterUpgradeError", { enumerable: true, get: function () { return errors_js_1.ClusterUpgradeError; } });
 var validators_js_1 = require("./validators.cjs");
 Object.defineProperty(exports, "assertGraphProfile", { enumerable: true, get: function () { return validators_js_1.assertGraphProfile; } });
 Object.defineProperty(exports, "assertGraphProfileSupported", { enumerable: true, get: function () { return validators_js_1.assertGraphProfileSupported; } });
@@ -35,7 +36,6 @@ Object.defineProperty(exports, "assertGraphSpec", { enumerable: true, get: funct
 __exportStar(require("./payload-value.cjs"), exports);
 __exportStar(require("./json-source.cjs"), exports);
 var connection_js_1 = require("./connection.cjs");
-Object.defineProperty(exports, "CLOSE_REASON_MAX_BYTES", { enumerable: true, get: function () { return connection_js_1.CLOSE_REASON_MAX_BYTES; } });
 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; } });

package/lib/cluster/index.d.cts

@@ -0,0 +1,13 @@
+export * from './generated/protocol.js';
+export { SUBSCRIPTION_QUEUE_MAX_BYTES } from './queue.js';
+export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRequestError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, ClusterUpgradeError, } from './errors.js';
+export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.js';
+export * from './payload-value.js';
+export * from './json-source.js';
+export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
+export type { CallOptions, ConnectionState, ConnectionCloseSnapshot, } 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, connectInitialized } from './client.js';
+export type { AgentAttachSubscription, CoherentWatchSubscription, ConnectInitializedResult, ConnectOptions, LogsSubscription, WatchSubscription, WebSocketFactoryOptions, } from './client.js';

package/lib/cluster/index.d.mts

@@ -0,0 +1,13 @@
+export * from './generated/protocol.js';
+export { SUBSCRIPTION_QUEUE_MAX_BYTES } from './queue.js';
+export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRequestError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, ClusterUpgradeError, } from './errors.js';
+export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.js';
+export * from './payload-value.js';
+export * from './json-source.js';
+export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
+export type { CallOptions, ConnectionState, ConnectionCloseSnapshot, } 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, connectInitialized } from './client.js';
+export type { AgentAttachSubscription, CoherentWatchSubscription, ConnectInitializedResult, ConnectOptions, LogsSubscription, WatchSubscription, WebSocketFactoryOptions, } from './client.js';

package/lib/cluster/index.d.ts

@@ -1,11 +1,11 @@
 export * from './generated/protocol.js';
 export { SUBSCRIPTION_QUEUE_MAX_BYTES } from './queue.js';
-export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRequestError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, } from './errors.js';
+export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRequestError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, ClusterUpgradeError, } from './errors.js';
 export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.js';
 export * from './payload-value.js';
 export * from './json-source.js';
-export { CLOSE_REASON_MAX_BYTES, CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
-export type { CallOptions, ConnectionState, } from './connection.js';
+export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
+export type { CallOptions, ConnectionState, ConnectionCloseSnapshot, } 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';

package/lib/cluster/index.mjs

@@ -1,9 +1,9 @@
 export * from './generated/protocol.mjs';
 export { SUBSCRIPTION_QUEUE_MAX_BYTES } from './queue.mjs';
-export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRequestError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, } from './errors.mjs';
+export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocolError, ClusterRequestError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, ClusterUpgradeError, } from './errors.mjs';
 export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.mjs';
 export * from './payload-value.mjs';
 export * from './json-source.mjs';
-export { CLOSE_REASON_MAX_BYTES, CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.mjs';
+export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.mjs';
 export { AgentAttachSubscriptionStream, LogsSubscriptionStream, WatchSubscriptionStream, } from './subscriptions.mjs';
 export { ClusterClient, connect, connectInitialized } from './client.mjs';

package/lib/cluster/json-source.cjs

@@ -7,6 +7,7 @@ exports.assertDistinctRequestSources = assertDistinctRequestSources;
 const errors_js_1 = require("./errors.cjs");
 const protocol_js_1 = require("./generated/protocol.cjs");
 exports.MAX_REQUEST_BYTES = protocol_js_1.MAX_FRAME_BYTES;
+/** Decode one already-bounded request body with strict UTF-8 and JSON handling. */
 function decodeBoundedJson(bytes) {
     if (bytes.length > exports.MAX_REQUEST_BYTES) {
         throw new errors_js_1.ClusterRequestError(`request payload of ${bytes.length} bytes exceeds the ${exports.MAX_REQUEST_BYTES} byte limit`, 'OVERSIZED_JSON');

package/lib/cluster/json-source.d.cts

@@ -0,0 +1,5 @@
+export declare const MAX_REQUEST_BYTES: 1048576;
+/** Decode one already-bounded request body with strict UTF-8 and JSON handling. */
+export declare function decodeBoundedJson(bytes: Uint8Array): unknown;
+export declare function readBoundedSource(source: AsyncIterable<Uint8Array | string>): Promise<Uint8Array>;
+export declare function assertDistinctRequestSources(graph: string, input: string | undefined): asserts input is string;

package/lib/cluster/json-source.d.mts

@@ -0,0 +1,5 @@
+export declare const MAX_REQUEST_BYTES: 1048576;
+/** Decode one already-bounded request body with strict UTF-8 and JSON handling. */
+export declare function decodeBoundedJson(bytes: Uint8Array): unknown;
+export declare function readBoundedSource(source: AsyncIterable<Uint8Array | string>): Promise<Uint8Array>;
+export declare function assertDistinctRequestSources(graph: string, input: string | undefined): asserts input is string;

package/lib/cluster/json-source.d.ts

@@ -1,4 +1,5 @@
 export declare const MAX_REQUEST_BYTES: 1048576;
+/** Decode one already-bounded request body with strict UTF-8 and JSON handling. */
 export declare function decodeBoundedJson(bytes: Uint8Array): unknown;
 export declare function readBoundedSource(source: AsyncIterable<Uint8Array | string>): Promise<Uint8Array>;
 export declare function assertDistinctRequestSources(graph: string, input: string | undefined): asserts input is string;

package/lib/cluster/json-source.mjs

@@ -1,6 +1,7 @@
 import { ClusterRequestError } from './errors.mjs';
 import { MAX_FRAME_BYTES } from './generated/protocol.mjs';
 export const MAX_REQUEST_BYTES = MAX_FRAME_BYTES;
+/** Decode one already-bounded request body with strict UTF-8 and JSON handling. */
 export function decodeBoundedJson(bytes) {
     if (bytes.length > MAX_REQUEST_BYTES) {
         throw new ClusterRequestError(`request payload of ${bytes.length} bytes exceeds the ${MAX_REQUEST_BYTES} byte limit`, 'OVERSIZED_JSON');

package/lib/cluster/payload-value.cjs

@@ -64,6 +64,7 @@ function evaluate(type, value, path) {
         }
     }
 }
+/** Return the first deterministic schema issue without retaining the input value. */
 function firstInputValidationIssue(type, value, path = '') {
     const issue = evaluate(type, value, path);
     return issue ? { path: issue.path, code: issue.code } : null;

package/lib/cluster/payload-value.d.cts

@@ -0,0 +1,8 @@
+import type { PayloadType } from './generated/protocol.js';
+export type InputValidationIssue = {
+    readonly path: string;
+    readonly code: 'TYPE_MISMATCH' | 'MISSING_REQUIRED_FIELD' | 'UNKNOWN_FIELD' | 'UNKNOWN_ENUM_LABEL';
+};
+/** Return the first deterministic schema issue without retaining the input value. */
+export declare function firstInputValidationIssue(type: PayloadType, value: unknown, path?: string): InputValidationIssue | null;
+export declare function assertInputValue(type: PayloadType, value: unknown): void;

package/lib/cluster/payload-value.d.mts

@@ -0,0 +1,8 @@
+import type { PayloadType } from './generated/protocol.js';
+export type InputValidationIssue = {
+    readonly path: string;
+    readonly code: 'TYPE_MISMATCH' | 'MISSING_REQUIRED_FIELD' | 'UNKNOWN_FIELD' | 'UNKNOWN_ENUM_LABEL';
+};
+/** Return the first deterministic schema issue without retaining the input value. */
+export declare function firstInputValidationIssue(type: PayloadType, value: unknown, path?: string): InputValidationIssue | null;
+export declare function assertInputValue(type: PayloadType, value: unknown): void;

package/lib/cluster/payload-value.d.ts

@@ -3,5 +3,6 @@ export type InputValidationIssue = {
     readonly path: string;
     readonly code: 'TYPE_MISMATCH' | 'MISSING_REQUIRED_FIELD' | 'UNKNOWN_FIELD' | 'UNKNOWN_ENUM_LABEL';
 };
+/** Return the first deterministic schema issue without retaining the input value. */
 export declare function firstInputValidationIssue(type: PayloadType, value: unknown, path?: string): InputValidationIssue | null;
 export declare function assertInputValue(type: PayloadType, value: unknown): void;

package/lib/cluster/payload-value.mjs

@@ -60,6 +60,7 @@ function evaluate(type, value, path) {
         }
     }
 }
+/** Return the first deterministic schema issue without retaining the input value. */
 export function firstInputValidationIssue(type, value, path = '') {
     const issue = evaluate(type, value, path);
     return issue ? { path: issue.path, code: issue.code } : null;

package/lib/cluster/queue.d.cts

@@ -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.d.mts

@@ -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/socket.cjs

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

package/lib/cluster/socket.d.cts

@@ -0,0 +1,13 @@
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string, callback?: (error?: Error) => void): void | Promise<void>;
+    close(code?: number, reason?: string): void | Promise<void>;
+    terminate?(): 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;
+export declare function addSocketEmitterListener(socket: WebSocketLike, type: string, listener: (...args: unknown[]) => void): () => void;

package/lib/cluster/socket.d.mts

@@ -0,0 +1,13 @@
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string, callback?: (error?: Error) => void): void | Promise<void>;
+    close(code?: number, reason?: string): void | Promise<void>;
+    terminate?(): 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;
+export declare function addSocketEmitterListener(socket: WebSocketLike, type: string, listener: (...args: unknown[]) => void): () => void;

package/lib/cluster/socket.d.ts

@@ -2,6 +2,7 @@ export interface WebSocketLike {
     readonly readyState: number;
     send(data: string, callback?: (error?: Error) => void): void | Promise<void>;
     close(code?: number, reason?: string): void | Promise<void>;
+    terminate?(): 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;
@@ -9,3 +10,4 @@ export interface WebSocketLike {
     removeListener?(type: string, listener: (...args: unknown[]) => void): void;
 }
 export declare function addSocketListener(socket: WebSocketLike, type: string, listener: (...args: unknown[]) => void): () => void;
+export declare function addSocketEmitterListener(socket: WebSocketLike, type: string, listener: (...args: unknown[]) => void): () => void;

package/lib/cluster/socket.mjs

@@ -10,3 +10,10 @@ export function addSocketListener(socket, type, listener) {
     }
     throw new ClusterConfigError('WebSocket implementation must support event listeners', 'INVALID_WEBSOCKET');
 }
+export function addSocketEmitterListener(socket, type, listener) {
+    if (socket.on) {
+        socket.on(type, listener);
+        return () => (socket.off ?? socket.removeListener)?.call(socket, type, listener);
+    }
+    return addSocketListener(socket, type, listener);
+}

package/lib/cluster/subscriptions.d.cts

@@ -0,0 +1,73 @@
+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>;
+}
+export interface WatchSubscription {
+    readonly result: WatchResult;
+    readonly stream: WatchSubscriptionStream;
+}
+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<WatchSubscription>;
+}
+export {};

package/lib/cluster/subscriptions.d.mts

@@ -0,0 +1,73 @@
+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>;
+}
+export interface WatchSubscription {
+    readonly result: WatchResult;
+    readonly stream: WatchSubscriptionStream;
+}
+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<WatchSubscription>;
+}
+export {};

package/lib/cluster/subscriptions.d.ts

@@ -24,6 +24,10 @@ export interface Subscription<T> extends AsyncIterator<SubscriptionItem<T>>, Asy
     readonly retainedCount: number;
     cancel(): Promise<void>;
 }
+export interface WatchSubscription {
+    readonly result: WatchResult;
+    readonly stream: WatchSubscriptionStream;
+}
 type FrameParser<T> = (frame: FrameRecord) => SubscriptionItem<T>;
 declare class SubscriptionStream<T> implements Subscription<T> {
     #private;
@@ -64,6 +68,6 @@ export declare class WatchSubscriptionStream implements AsyncIterator<WatchSubsc
     return(): Promise<IteratorResult<WatchSubscriptionItem>>;
     throw(error?: unknown): Promise<IteratorResult<WatchSubscriptionItem>>;
     cancel(): Promise<void>;
-    reconnect(freshConnection: Connection): Promise<import('./client.js').WatchSubscription>;
+    reconnect(freshConnection: Connection): Promise<WatchSubscription>;
 }
 export {};

package/lib/cluster/validators.cjs

@@ -54,6 +54,7 @@ function assertRequestDefinition(definition, value, code) {
     const details = (validate.errors ?? []).map((error) => `${error.instancePath || '/'} ${error.message ?? 'is invalid'}`).join('; ');
     throw new errors_js_1.ClusterRequestError(`${definition} validation failed: ${details}`, code);
 }
+/** Validate an execution graph against the frozen cluster protocol schema. */
 function assertGraphSpec(value) {
     assertRequestDefinition('GraphSpec', value, 'INVALID_GRAPH');
 }

package/lib/cluster/validators.d.cts

@@ -0,0 +1,7 @@
+import type { ClusterMethod, GraphProfile, GraphSpec, ServerCapabilities } from './generated/protocol.js';
+export declare function assertDefinition(definition: string, value: unknown): void;
+export declare function assertMethodResult(method: ClusterMethod, value: unknown): void;
+/** Validate an execution graph against the frozen cluster protocol schema. */
+export declare function assertGraphSpec(value: unknown): asserts value is GraphSpec;
+export declare function assertGraphProfile(value: unknown): asserts value is GraphProfile;
+export declare function assertGraphProfileSupported(profile: GraphProfile, capabilities: ServerCapabilities): void;

package/lib/cluster/validators.d.mts

@@ -0,0 +1,7 @@
+import type { ClusterMethod, GraphProfile, GraphSpec, ServerCapabilities } from './generated/protocol.js';
+export declare function assertDefinition(definition: string, value: unknown): void;
+export declare function assertMethodResult(method: ClusterMethod, value: unknown): void;
+/** Validate an execution graph against the frozen cluster protocol schema. */
+export declare function assertGraphSpec(value: unknown): asserts value is GraphSpec;
+export declare function assertGraphProfile(value: unknown): asserts value is GraphProfile;
+export declare function assertGraphProfileSupported(profile: GraphProfile, capabilities: ServerCapabilities): void;

package/lib/cluster/validators.d.ts

@@ -1,6 +1,7 @@
 import type { ClusterMethod, GraphProfile, GraphSpec, ServerCapabilities } from './generated/protocol.js';
 export declare function assertDefinition(definition: string, value: unknown): void;
 export declare function assertMethodResult(method: ClusterMethod, value: unknown): void;
+/** Validate an execution graph against the frozen cluster protocol schema. */
 export declare function assertGraphSpec(value: unknown): asserts value is GraphSpec;
 export declare function assertGraphProfile(value: unknown): asserts value is GraphProfile;
 export declare function assertGraphProfileSupported(profile: GraphProfile, capabilities: ServerCapabilities): void;

package/lib/cluster/validators.mjs

@@ -47,6 +47,7 @@ function assertRequestDefinition(definition, value, code) {
     const details = (validate.errors ?? []).map((error) => `${error.instancePath || '/'} ${error.message ?? 'is invalid'}`).join('; ');
     throw new ClusterRequestError(`${definition} validation failed: ${details}`, code);
 }
+/** Validate an execution graph against the frozen cluster protocol schema. */
 export function assertGraphSpec(value) {
     assertRequestDefinition('GraphSpec', value, 'INVALID_GRAPH');
 }

package/lib/cluster-worker/engine-adapter.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { cloneJson } = require('./object-utils');
+const { inputFromRequest } = require('./engine-input');
 
 const TERMINAL_TOPICS = new Set(['CLUSTER_COMPLETE', 'CLUSTER_FAILED']);
 
@@ -28,17 +29,6 @@ function terminalEventFromMessage(message) {
   };
 }
 
-function inputFromRequest(request, artifactManifest) {
-  if (request.source === 'issue') return { issue: request.issue };
-  if (request.source === 'prompt') return { text: request.prompt };
-  return {
-    text:
-      'Execute the task described by this registry-staged, byte-free artifact manifest. ' +
-      'Do not request interactive input.\n' +
-      JSON.stringify(artifactManifest),
-  };
-}
-
 function resolveOrchestrator(options) {
   if (options.orchestrator) return options.orchestrator;
   const Orchestrator = options.Orchestrator || require('../../src/orchestrator');

package/lib/cluster-worker/engine-input.js

@@ -0,0 +1,14 @@
+'use strict';
+
+function inputFromRequest(request, artifactManifest) {
+  if (request.source === 'issue') return { issue: request.issue };
+  if (request.source === 'prompt') return { text: request.prompt };
+  return {
+    text:
+      'Execute the task described by this registry-staged, byte-free artifact manifest. ' +
+      'Do not request interactive input.\n' +
+      JSON.stringify(artifactManifest),
+  };
+}
+
+module.exports = { inputFromRequest };

package/lib/hosted-session/authority.cjs

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizedAuthority = normalizedAuthority;
+exports.validateHostedAccess = validateHostedAccess;
+const index_js_1 = require("../cluster/index.cjs");
+const LOOPBACK_HOSTS = Object.freeze({
+    '127.0.0.1': true,
+    '::1': true,
+    '[::1]': true,
+});
+function parseCanonicalUrl(value, message, code) {
+    try {
+        if (/[\u0000-\u0020\u007f]/.test(value))
+            throw new TypeError('unsafe URL code point');
+        const url = new URL(value);
+        if (url.href !== value && url.origin !== value)
+            throw new TypeError('non-canonical URL');
+        return url;
+    }
+    catch {
+        throw new index_js_1.ClusterConfigError(message, code);
+    }
+}
+function hasOriginSuffix(url) {
+    return Boolean(url.username ||
+        url.password ||
+        url.pathname !== '/' ||
+        url.search ||
+        url.hash);
+}
+function normalizedAuthority(value) {
+    const message = 'targetAuthority must be an HTTPS or literal-loopback HTTP origin';
+    const url = parseCanonicalUrl(value, message, 'INVALID_TARGET_AUTHORITY');
+    const loopbackHttp = url.protocol === 'http:' && LOOPBACK_HOSTS[url.hostname] === true;
+    if ((url.protocol !== 'https:' && !loopbackHttp) || hasOriginSuffix(url) ||
+        value !== url.origin) {
+        throw new index_js_1.ClusterConfigError(message, 'INVALID_TARGET_AUTHORITY');
+    }
+    return url.origin;
+}
+function accessAuthorityMatches(endpoint, target) {
+    const expectedProtocol = target.protocol === 'http:' ? 'ws:' : 'wss:';
+    return (endpoint.protocol === expectedProtocol &&
+        endpoint.host === target.host &&
+        !endpoint.username &&
+        !endpoint.password &&
+        !endpoint.search &&
+        !endpoint.hash);
+}
+function validateHostedAccess(access, targetAuthority) {
+    const endpoint = parseCanonicalUrl(access.websocketUrl, 'access endpoint must be an absolute target WebSocket URL', 'INVALID_ACCESS_ENDPOINT');
+    if (endpoint.href !== access.websocketUrl ||
+        !accessAuthorityMatches(endpoint, new URL(targetAuthority))) {
+        throw new index_js_1.ClusterConfigError('access endpoint must remain on the exact target authority', 'INVALID_ACCESS_ENDPOINT');
+    }
+    if (access.protocol !== 'openengine.cluster/v1' ||
+        access.tokenType !== 'Bearer' ||
+        access.accessToken.length === 0) {
+        throw new index_js_1.ClusterConfigError('access grant does not match the hosted session contract', 'INVALID_ACCESS_GRANT');
+    }
+}

package/lib/hosted-session/authority.d.cts

@@ -0,0 +1,3 @@
+import type { HostedAccess } from './types.js';
+export declare function normalizedAuthority(value: string): string;
+export declare function validateHostedAccess(access: HostedAccess, targetAuthority: string): void;

package/lib/hosted-session/authority.d.mts

@@ -0,0 +1,3 @@
+import type { HostedAccess } from './types.js';
+export declare function normalizedAuthority(value: string): string;
+export declare function validateHostedAccess(access: HostedAccess, targetAuthority: string): void;

package/lib/hosted-session/authority.d.ts

@@ -0,0 +1,3 @@
+import type { HostedAccess } from './types.js';
+export declare function normalizedAuthority(value: string): string;
+export declare function validateHostedAccess(access: HostedAccess, targetAuthority: string): void;