@the-open-engine/zeroshot 6.25.1 → 6.27.0

package/lib/cluster/client.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClusterClient = void 0;
 exports.connect = connect;
+exports.connectInitialized = connectInitialized;
 const protocol_js_1 = require("./generated/protocol.cjs");
 const connection_js_1 = require("./connection.cjs");
 const socket_js_1 = require("./socket.cjs");
@@ -79,12 +80,15 @@ class ClusterClient {
     }
 }
 exports.ClusterClient = ClusterClient;
-async function defaultWebSocketFactory(url, protocols) {
+async function defaultWebSocketFactory(url, protocols, options) {
     const globalWebSocket = globalThis.WebSocket;
-    if (globalWebSocket)
+    if (globalWebSocket) {
+        if (options?.headers && Object.keys(options.headers).length > 0) {
+            throw new errors_js_1.ClusterConfigError('WebSocket upgrade headers require the ws library; the browser WebSocket API cannot carry request headers', 'HEADERS_UNSUPPORTED');
+        }
         return new globalWebSocket(url, protocols);
+    }
     try {
-        // Dynamic loading keeps the optional Node runtime off the browser/global-WebSocket path.
         const imported = await Promise.resolve().then(() => require('ws'));
         const candidate = imported !== null && typeof imported === 'object' && 'default' in imported
             ? imported.default
@@ -93,7 +97,7 @@ async function defaultWebSocketFactory(url, protocols) {
             throw new TypeError("The installed 'ws' module does not export a WebSocket constructor");
         }
         const Constructor = candidate;
-        return new Constructor(url, protocols);
+        return options?.headers ? new Constructor(url, protocols, { headers: options.headers }) : new Constructor(url, protocols);
     }
     catch (cause) {
         throw new errors_js_1.ClusterConfigError("No WebSocket runtime is available; install 'ws' or pass webSocketFactory", 'WEBSOCKET_UNAVAILABLE', { cause });
@@ -128,7 +132,7 @@ async function connect(url, options = {}) {
     const factory = options.webSocketFactory ?? defaultWebSocketFactory;
     let socket;
     try {
-        socket = await factory(url, options.protocols);
+        socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
         await waitForOpen(socket, options.signal);
         const connection = new connection_js_1.Connection(socket);
         await new ClusterClient(connection).initialize(options.initialize, options.signal === undefined ? {} : { signal: options.signal });
@@ -144,3 +148,24 @@ async function connect(url, options = {}) {
         throw error;
     }
 }
+async function connectInitialized(url, options = {}) {
+    const factory = options.webSocketFactory ?? defaultWebSocketFactory;
+    let socket;
+    try {
+        socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
+        await waitForOpen(socket, options.signal);
+        const connection = new connection_js_1.Connection(socket);
+        const client = new ClusterClient(connection);
+        const initializeResult = await client.initialize(options.initialize, options.signal === undefined ? {} : { signal: options.signal });
+        return { connection, client, initializeResult };
+    }
+    catch (error) {
+        if (socket) {
+            try {
+                await socket.close();
+            }
+            catch { /* preserve the construction error */ }
+        }
+        throw error;
+    }
+}

package/lib/cluster/client.d.ts

@@ -3,11 +3,15 @@ import { Connection } from './connection.js';
 import type { CallOptions } from './connection.js';
 import type { WebSocketLike } from './socket.js';
 import { AgentAttachSubscriptionStream, LogsSubscriptionStream, WatchSubscriptionStream } from './subscriptions.js';
+export interface WebSocketFactoryOptions {
+    readonly headers?: Readonly<Record<string, string>>;
+}
 export interface ConnectOptions {
     readonly protocols?: string | readonly string[];
-    readonly webSocketFactory?: (url: string, protocols?: string | readonly string[]) => WebSocketLike | Promise<WebSocketLike>;
+    readonly webSocketFactory?: (url: string, protocols?: string | readonly string[], options?: WebSocketFactoryOptions) => WebSocketLike | Promise<WebSocketLike>;
     readonly signal?: AbortSignal;
     readonly initialize?: InitializeParams;
+    readonly headers?: Readonly<Record<string, string>>;
 }
 export interface WatchSubscription {
     readonly result: WatchResult;
@@ -24,6 +28,11 @@ export interface AgentAttachSubscription {
 export interface CoherentWatchSubscription extends WatchSubscription {
     readonly snapshot: GetResult;
 }
+export interface ConnectInitializedResult {
+    readonly connection: Connection;
+    readonly client: ClusterClient;
+    readonly initializeResult: InitializeResult;
+}
 export declare class ClusterClient {
     readonly connection: Connection;
     constructor(connection: Connection);
@@ -42,3 +51,4 @@ export declare class ClusterClient {
     agentAttach(params: AgentAttachParams, options?: CallOptions): Promise<AgentAttachSubscription>;
 }
 export declare function connect(url: string, options?: ConnectOptions): Promise<Connection>;
+export declare function connectInitialized(url: string, options?: ConnectOptions): Promise<ConnectInitializedResult>;

package/lib/cluster/client.mjs

@@ -74,12 +74,15 @@ export class ClusterClient {
         };
     }
 }
-async function defaultWebSocketFactory(url, protocols) {
+async function defaultWebSocketFactory(url, protocols, options) {
     const globalWebSocket = globalThis.WebSocket;
-    if (globalWebSocket)
+    if (globalWebSocket) {
+        if (options?.headers && Object.keys(options.headers).length > 0) {
+            throw new ClusterConfigError('WebSocket upgrade headers require the ws library; the browser WebSocket API cannot carry request headers', 'HEADERS_UNSUPPORTED');
+        }
         return new globalWebSocket(url, protocols);
+    }
     try {
-        // Dynamic loading keeps the optional Node runtime off the browser/global-WebSocket path.
         const imported = await import('ws');
         const candidate = imported !== null && typeof imported === 'object' && 'default' in imported
             ? imported.default
@@ -88,7 +91,7 @@ async function defaultWebSocketFactory(url, protocols) {
             throw new TypeError("The installed 'ws' module does not export a WebSocket constructor");
         }
         const Constructor = candidate;
-        return new Constructor(url, protocols);
+        return options?.headers ? new Constructor(url, protocols, { headers: options.headers }) : new Constructor(url, protocols);
     }
     catch (cause) {
         throw new ClusterConfigError("No WebSocket runtime is available; install 'ws' or pass webSocketFactory", 'WEBSOCKET_UNAVAILABLE', { cause });
@@ -123,7 +126,7 @@ export async function connect(url, options = {}) {
     const factory = options.webSocketFactory ?? defaultWebSocketFactory;
     let socket;
     try {
-        socket = await factory(url, options.protocols);
+        socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
         await waitForOpen(socket, options.signal);
         const connection = new Connection(socket);
         await new ClusterClient(connection).initialize(options.initialize, options.signal === undefined ? {} : { signal: options.signal });
@@ -139,3 +142,24 @@ export async function connect(url, options = {}) {
         throw error;
     }
 }
+export async function connectInitialized(url, options = {}) {
+    const factory = options.webSocketFactory ?? defaultWebSocketFactory;
+    let socket;
+    try {
+        socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
+        await waitForOpen(socket, options.signal);
+        const connection = new Connection(socket);
+        const client = new ClusterClient(connection);
+        const initializeResult = await client.initialize(options.initialize, options.signal === undefined ? {} : { signal: options.signal });
+        return { connection, client, initializeResult };
+    }
+    catch (error) {
+        if (socket) {
+            try {
+                await socket.close();
+            }
+            catch { /* preserve the construction error */ }
+        }
+        throw error;
+    }
+}

package/lib/cluster/connection.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Connection = exports.PROTOCOL_DIAGNOSTIC_CAPACITY = exports.CONNECTION_TRANSITIONS = void 0;
+exports.Connection = exports.CLOSE_REASON_MAX_BYTES = exports.PROTOCOL_DIAGNOSTIC_CAPACITY = exports.CONNECTION_TRANSITIONS = void 0;
 const protocol_js_1 = require("./generated/protocol.cjs");
 const errors_js_1 = require("./errors.cjs");
 const frames_js_1 = require("./frames.cjs");
@@ -19,6 +19,21 @@ exports.CONNECTION_TRANSITIONS = Object.freeze({
     CLOSED: Object.freeze([]),
 });
 exports.PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+exports.CLOSE_REASON_MAX_BYTES = 123;
+const CLOSE_REASON_ENCODER = new TextEncoder();
+function boundedCloseReason(reason) {
+    const retained = [];
+    const scratch = new Uint8Array(4);
+    let bytes = 0;
+    for (const codePoint of reason) {
+        const { written } = CLOSE_REASON_ENCODER.encodeInto(codePoint, scratch);
+        if (bytes + written > exports.CLOSE_REASON_MAX_BYTES)
+            break;
+        retained.push(codePoint);
+        bytes += written;
+    }
+    return retained.join('');
+}
 function deferred() {
     let resolve;
     let reject;
@@ -37,6 +52,8 @@ class Connection {
     #removeSocketListeners = [];
     #ownedSubscriptions = new WeakSet();
     #closePromise;
+    #closeCode;
+    #closeReason;
     closeDiagnostics = [];
     protocolDiagnostics = [];
     #socket;
@@ -44,11 +61,13 @@ class Connection {
         if (socket.readyState !== 1)
             throw new errors_js_1.ClusterStateError('Connection requires an already-open WebSocket', 'SOCKET_NOT_OPEN');
         this.#socket = socket;
-        this.#removeSocketListeners.push((0, socket_js_1.addSocketListener)(socket, 'message', (event) => this.#onMessage(event)), (0, socket_js_1.addSocketListener)(socket, 'error', () => { void this.#startClose(false); }), (0, socket_js_1.addSocketListener)(socket, 'close', () => { void this.#startClose(false); }));
+        this.#removeSocketListeners.push((0, socket_js_1.addSocketListener)(socket, 'message', (event) => this.#onMessage(event)), (0, socket_js_1.addSocketListener)(socket, 'error', () => { void this.#startClose(false); }), (0, socket_js_1.addSocketListener)(socket, 'close', (...args) => { this.#captureCloseState(args); void this.#startClose(false); }));
     }
     get state() { return this.#state; }
     get pendingSize() { return this.#pending.size; }
     get subscriptionCount() { return this.#subscriptions.size; }
+    get closeCode() { return this.#closeCode; }
+    get closeReason() { return this.#closeReason; }
     call(method, params, options = {}) {
         if (!protocol_js_1.UNARY_METHODS.includes(method)) {
             throw new errors_js_1.ClusterConfigError(`${method} is a subscription method`, 'INVALID_METHOD');
@@ -322,6 +341,23 @@ class Connection {
             this.protocolDiagnostics.shift();
         this.protocolDiagnostics.push(new errors_js_1.ClusterProtocolError(message, 'INVALID_PEER_FRAME', cause === undefined ? undefined : { cause }));
     }
+    #captureCloseState(args) {
+        if (args.length === 0)
+            return;
+        const first = args[0];
+        if (typeof first === 'number') {
+            this.#closeCode = first;
+            const raw = args.length > 1 ? String(args[1]) : undefined;
+            this.#closeReason = raw === undefined ? undefined : boundedCloseReason(raw);
+        }
+        else if (first !== null && typeof first === 'object') {
+            const event = first;
+            if (typeof event.code === 'number')
+                this.#closeCode = event.code;
+            if (typeof event.reason === 'string')
+                this.#closeReason = boundedCloseReason(event.reason);
+        }
+    }
     #startClose(sendCancels) {
         if (this.#closePromise)
             return this.#closePromise;

package/lib/cluster/connection.d.ts

@@ -6,6 +6,7 @@ import type { WebSocketLike } from './socket.js';
 export type ConnectionState = 'OPEN' | 'CLOSING' | 'CLOSED';
 export declare const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly ConnectionState[]>>;
 export declare const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export declare const CLOSE_REASON_MAX_BYTES = 123;
 export interface CallOptions {
     readonly signal?: AbortSignal;
     readonly requestTimeoutMs?: number;
@@ -32,6 +33,8 @@ export declare class Connection {
     get state(): ConnectionState;
     get pendingSize(): number;
     get subscriptionCount(): number;
+    get closeCode(): number | undefined;
+    get closeReason(): string | undefined;
     call<M extends UnaryClusterMethod>(method: M, params: ClusterMethodParams[M], options?: CallOptions): Promise<ClusterMethodResults[M]>;
     cancelSubscription(registration: SubscriptionRegistration): Promise<void>;
     openSubscription<M extends SubscriptionMethod>(method: M, params: ClusterMethodParams[M], options?: CallOptions): Promise<EstablishedSubscription<ClusterMethodResults[M]>>;

package/lib/cluster/connection.mjs

@@ -16,6 +16,21 @@ export const CONNECTION_TRANSITIONS = Object.freeze({
     CLOSED: Object.freeze([]),
 });
 export const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export const CLOSE_REASON_MAX_BYTES = 123;
+const CLOSE_REASON_ENCODER = new TextEncoder();
+function boundedCloseReason(reason) {
+    const retained = [];
+    const scratch = new Uint8Array(4);
+    let bytes = 0;
+    for (const codePoint of reason) {
+        const { written } = CLOSE_REASON_ENCODER.encodeInto(codePoint, scratch);
+        if (bytes + written > CLOSE_REASON_MAX_BYTES)
+            break;
+        retained.push(codePoint);
+        bytes += written;
+    }
+    return retained.join('');
+}
 function deferred() {
     let resolve;
     let reject;
@@ -34,6 +49,8 @@ export class Connection {
     #removeSocketListeners = [];
     #ownedSubscriptions = new WeakSet();
     #closePromise;
+    #closeCode;
+    #closeReason;
     closeDiagnostics = [];
     protocolDiagnostics = [];
     #socket;
@@ -41,11 +58,13 @@ export class Connection {
         if (socket.readyState !== 1)
             throw new ClusterStateError('Connection requires an already-open WebSocket', 'SOCKET_NOT_OPEN');
         this.#socket = socket;
-        this.#removeSocketListeners.push(addSocketListener(socket, 'message', (event) => this.#onMessage(event)), addSocketListener(socket, 'error', () => { void this.#startClose(false); }), addSocketListener(socket, 'close', () => { void this.#startClose(false); }));
+        this.#removeSocketListeners.push(addSocketListener(socket, 'message', (event) => this.#onMessage(event)), addSocketListener(socket, 'error', () => { void this.#startClose(false); }), addSocketListener(socket, 'close', (...args) => { this.#captureCloseState(args); void this.#startClose(false); }));
     }
     get state() { return this.#state; }
     get pendingSize() { return this.#pending.size; }
     get subscriptionCount() { return this.#subscriptions.size; }
+    get closeCode() { return this.#closeCode; }
+    get closeReason() { return this.#closeReason; }
     call(method, params, options = {}) {
         if (!UNARY_METHODS.includes(method)) {
             throw new ClusterConfigError(`${method} is a subscription method`, 'INVALID_METHOD');
@@ -319,6 +338,23 @@ export class Connection {
             this.protocolDiagnostics.shift();
         this.protocolDiagnostics.push(new ClusterProtocolError(message, 'INVALID_PEER_FRAME', cause === undefined ? undefined : { cause }));
     }
+    #captureCloseState(args) {
+        if (args.length === 0)
+            return;
+        const first = args[0];
+        if (typeof first === 'number') {
+            this.#closeCode = first;
+            const raw = args.length > 1 ? String(args[1]) : undefined;
+            this.#closeReason = raw === undefined ? undefined : boundedCloseReason(raw);
+        }
+        else if (first !== null && typeof first === 'object') {
+            const event = first;
+            if (typeof event.code === 'number')
+                this.#closeCode = event.code;
+            if (typeof event.reason === 'string')
+                this.#closeReason = boundedCloseReason(event.reason);
+        }
+    }
     #startClose(sendCancels) {
         if (this.#closePromise)
             return this.#closePromise;

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.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.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.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;
 __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; } });
@@ -35,6 +35,7 @@ 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; } });
@@ -45,3 +46,4 @@ Object.defineProperty(exports, "WatchSubscriptionStream", { enumerable: true, ge
 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; } });
+Object.defineProperty(exports, "connectInitialized", { enumerable: true, get: function () { return client_js_1.connectInitialized; } });

package/lib/cluster/index.d.ts

@@ -4,10 +4,10 @@ export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocol
 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 { CLOSE_REASON_MAX_BYTES, 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';
+export { ClusterClient, connect, connectInitialized } from './client.js';
+export type { AgentAttachSubscription, CoherentWatchSubscription, ConnectInitializedResult, ConnectOptions, LogsSubscription, WatchSubscription, WebSocketFactoryOptions, } from './client.js';

package/lib/cluster/index.mjs

@@ -4,6 +4,6 @@ export { ClusterConfigError, ClusterError, ClusterInternalError, ClusterProtocol
 export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.mjs';
 export * from './payload-value.mjs';
 export * from './json-source.mjs';
-export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.mjs';
+export { CLOSE_REASON_MAX_BYTES, CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.mjs';
 export { AgentAttachSubscriptionStream, LogsSubscriptionStream, WatchSubscriptionStream, } from './subscriptions.mjs';
-export { ClusterClient, connect } from './client.mjs';
+export { ClusterClient, connect, connectInitialized } from './client.mjs';

package/lib/hosted-session/coordinator.cjs

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostedSessionCoordinator = void 0;
+const index_js_1 = require("../cluster/index.cjs");
+function combineSignals(signals) {
+    const defined = signals.filter((s) => s !== undefined);
+    if (defined.length === 0)
+        return undefined;
+    if (defined.length === 1)
+        return defined[0];
+    return AbortSignal.any(defined);
+}
+class HostedSessionCoordinator {
+    #getAccess;
+    #connectOptions;
+    #clock;
+    #closeController = new AbortController();
+    #referenceCapabilities;
+    #closed = false;
+    constructor(init) {
+        this.#getAccess = init.getAccess;
+        this.#connectOptions = init.connectOptions;
+        this.#clock = init.clock ?? Date;
+    }
+    async open(signal) {
+        this.#requireNotClosed();
+        const session = await this.#createSession(signal);
+        this.#referenceCapabilities = session.initializeResult.capabilities;
+        return session;
+    }
+    async replace(signal) {
+        this.#requireNotClosed();
+        const session = await this.#createSession(signal);
+        this.#verifyCapabilities(session.initializeResult.capabilities, session);
+        return session;
+    }
+    renewalDeadline(access, receivedAt) {
+        const expiresAt = Date.parse(access.expiresAt);
+        if (Number.isNaN(expiresAt)) {
+            throw new index_js_1.ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+        }
+        const lifetime = expiresAt - receivedAt;
+        return Math.min(expiresAt - 30_000, receivedAt + 0.8 * lifetime);
+    }
+    async close() {
+        this.#closed = true;
+        this.#closeController.abort();
+    }
+    async #createSession(signal) {
+        const combined = combineSignals([signal, this.#closeController.signal]);
+        const access = await this.#getAccess(combined);
+        const expiresAt = Date.parse(access.expiresAt);
+        if (Number.isNaN(expiresAt)) {
+            throw new index_js_1.ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+        }
+        if (expiresAt <= this.#clock.now()) {
+            throw new index_js_1.ClusterConfigError('access token is already expired', 'ACCESS_EXPIRED');
+        }
+        let endpoint;
+        try {
+            endpoint = new URL(access.endpoint);
+        }
+        catch {
+            throw new index_js_1.ClusterConfigError('hosted access endpoint is invalid', 'INVALID_ENDPOINT');
+        }
+        if (endpoint.protocol !== 'wss:') {
+            throw new index_js_1.ClusterConfigError('hosted access endpoint must use wss', 'INSECURE_ENDPOINT');
+        }
+        return (0, index_js_1.connectInitialized)(endpoint.href, {
+            ...this.#connectOptions,
+            headers: { Authorization: `Bearer ${access.token}` },
+            ...(combined !== undefined ? { signal: combined } : {}),
+        });
+    }
+    #verifyCapabilities(incoming, session) {
+        if (!this.#referenceCapabilities)
+            return;
+        const ref = this.#referenceCapabilities;
+        const mismatches = [];
+        if (ref.graphProfiles) {
+            const incomingProfiles = new Set(incoming.graphProfiles ?? []);
+            for (const profile of ref.graphProfiles) {
+                if (!incomingProfiles.has(profile))
+                    mismatches.push(`missing graphProfile: ${profile}`);
+            }
+        }
+        if (ref.logs && !incoming.logs)
+            mismatches.push('missing capability: logs');
+        if (ref.agentAttach && !incoming.agentAttach)
+            mismatches.push('missing capability: agentAttach');
+        if (mismatches.length > 0) {
+            void session.connection.close();
+            throw new index_js_1.ClusterConfigError(`replacement capabilities incompatible: ${mismatches.join(', ')}`, 'INCOMPATIBLE_CAPABILITIES');
+        }
+    }
+    #requireNotClosed() {
+        if (this.#closed)
+            throw new index_js_1.ClusterConfigError('coordinator is closed', 'COORDINATOR_CLOSED');
+    }
+}
+exports.HostedSessionCoordinator = HostedSessionCoordinator;

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

@@ -0,0 +1,9 @@
+import type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';
+export declare class HostedSessionCoordinator {
+    #private;
+    constructor(init: HostedSessionInit);
+    open(signal?: AbortSignal): Promise<InitializedSession>;
+    replace(signal?: AbortSignal): Promise<InitializedSession>;
+    renewalDeadline(access: AccessResponse, receivedAt: number): number;
+    close(): Promise<void>;
+}

package/lib/hosted-session/coordinator.mjs

@@ -0,0 +1,97 @@
+import { ClusterConfigError, connectInitialized } from '../cluster/index.mjs';
+function combineSignals(signals) {
+    const defined = signals.filter((s) => s !== undefined);
+    if (defined.length === 0)
+        return undefined;
+    if (defined.length === 1)
+        return defined[0];
+    return AbortSignal.any(defined);
+}
+export class HostedSessionCoordinator {
+    #getAccess;
+    #connectOptions;
+    #clock;
+    #closeController = new AbortController();
+    #referenceCapabilities;
+    #closed = false;
+    constructor(init) {
+        this.#getAccess = init.getAccess;
+        this.#connectOptions = init.connectOptions;
+        this.#clock = init.clock ?? Date;
+    }
+    async open(signal) {
+        this.#requireNotClosed();
+        const session = await this.#createSession(signal);
+        this.#referenceCapabilities = session.initializeResult.capabilities;
+        return session;
+    }
+    async replace(signal) {
+        this.#requireNotClosed();
+        const session = await this.#createSession(signal);
+        this.#verifyCapabilities(session.initializeResult.capabilities, session);
+        return session;
+    }
+    renewalDeadline(access, receivedAt) {
+        const expiresAt = Date.parse(access.expiresAt);
+        if (Number.isNaN(expiresAt)) {
+            throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+        }
+        const lifetime = expiresAt - receivedAt;
+        return Math.min(expiresAt - 30_000, receivedAt + 0.8 * lifetime);
+    }
+    async close() {
+        this.#closed = true;
+        this.#closeController.abort();
+    }
+    async #createSession(signal) {
+        const combined = combineSignals([signal, this.#closeController.signal]);
+        const access = await this.#getAccess(combined);
+        const expiresAt = Date.parse(access.expiresAt);
+        if (Number.isNaN(expiresAt)) {
+            throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+        }
+        if (expiresAt <= this.#clock.now()) {
+            throw new ClusterConfigError('access token is already expired', 'ACCESS_EXPIRED');
+        }
+        let endpoint;
+        try {
+            endpoint = new URL(access.endpoint);
+        }
+        catch {
+            throw new ClusterConfigError('hosted access endpoint is invalid', 'INVALID_ENDPOINT');
+        }
+        if (endpoint.protocol !== 'wss:') {
+            throw new ClusterConfigError('hosted access endpoint must use wss', 'INSECURE_ENDPOINT');
+        }
+        return connectInitialized(endpoint.href, {
+            ...this.#connectOptions,
+            headers: { Authorization: `Bearer ${access.token}` },
+            ...(combined !== undefined ? { signal: combined } : {}),
+        });
+    }
+    #verifyCapabilities(incoming, session) {
+        if (!this.#referenceCapabilities)
+            return;
+        const ref = this.#referenceCapabilities;
+        const mismatches = [];
+        if (ref.graphProfiles) {
+            const incomingProfiles = new Set(incoming.graphProfiles ?? []);
+            for (const profile of ref.graphProfiles) {
+                if (!incomingProfiles.has(profile))
+                    mismatches.push(`missing graphProfile: ${profile}`);
+            }
+        }
+        if (ref.logs && !incoming.logs)
+            mismatches.push('missing capability: logs');
+        if (ref.agentAttach && !incoming.agentAttach)
+            mismatches.push('missing capability: agentAttach');
+        if (mismatches.length > 0) {
+            void session.connection.close();
+            throw new ClusterConfigError(`replacement capabilities incompatible: ${mismatches.join(', ')}`, 'INCOMPATIBLE_CAPABILITIES');
+        }
+    }
+    #requireNotClosed() {
+        if (this.#closed)
+            throw new ClusterConfigError('coordinator is closed', 'COORDINATOR_CLOSED');
+    }
+}

package/lib/hosted-session/index.cjs

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostedSessionCoordinator = void 0;
+var coordinator_js_1 = require("./coordinator.cjs");
+Object.defineProperty(exports, "HostedSessionCoordinator", { enumerable: true, get: function () { return coordinator_js_1.HostedSessionCoordinator; } });

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

@@ -0,0 +1,2 @@
+export { HostedSessionCoordinator } from './coordinator.js';
+export type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';

package/lib/hosted-session/index.mjs

@@ -0,0 +1 @@
+export { HostedSessionCoordinator } from './coordinator.mjs';

package/lib/hosted-session/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,20 @@
+import type { Connection } from '../cluster/index.js';
+import type { ClusterClient, ConnectOptions } from '../cluster/index.js';
+import type { InitializeResult } from '../cluster/index.js';
+export interface AccessResponse {
+    readonly endpoint: string;
+    readonly token: string;
+    readonly expiresAt: string;
+}
+export interface HostedSessionInit {
+    readonly getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+    readonly connectOptions?: Omit<ConnectOptions, 'headers' | 'signal'>;
+    readonly clock?: {
+        now(): number;
+    };
+}
+export interface InitializedSession {
+    readonly connection: Connection;
+    readonly client: ClusterClient;
+    readonly initializeResult: InitializeResult;
+}

package/lib/hosted-session/types.mjs

@@ -0,0 +1 @@
+export {};