@the-open-engine/zeroshot 6.26.0 → 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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.26.0",
+  "version": "6.27.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -40,21 +40,22 @@
     "test:coverage:report": "c8 --reporter=html npm run test:unit && echo 'Coverage report generated at coverage/index.html'",
     "postinstall": "node scripts/fix-node-pty-permissions.js && node scripts/check-path.js",
     "start": "node cli/index.js",
-    "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target",
+    "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target && npm run typecheck:hosted-session",
     "typecheck:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.json",
     "typecheck:hosted-target": "tsc --project tsconfig.hosted-target.json",
+    "typecheck:hosted-session": "tsc --project tsconfig.hosted-session.json",
     "test:hosted-target": "node --test tests/hosted-target/*.test.ts",
     "typecheck:cluster": "tsc --project tsconfig.cluster.json",
     "lint:agent-cli-provider": "eslint \"src/agent-cli-provider/**/*.ts\" \"tests/agent-cli-provider/**/*.ts\"",
     "build:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.build.json",
-    "build:cluster": "npm run protocol:generate && tsc --project tsconfig.cluster.cjs.json && tsc --project tsconfig.cluster.esm.json && node scripts/build-cluster.js",
+    "build:cluster": "npm run protocol:generate && tsc --project tsconfig.cluster.cjs.json && tsc --project tsconfig.cluster.esm.json && tsc --project tsconfig.hosted-session.cjs.json && tsc --project tsconfig.hosted-session.esm.json && node scripts/build-cluster.js",
     "test:agent-cli-provider": "node --test tests/agent-cli-provider/*.test.js",
     "test:omp": "npm run build:agent-cli-provider && node --test tests/agent-cli-provider/omp-*.test.js && node tests/run-tests.js tests/omp-rpc-watcher.test.js tests/omp-isolation-capability.test.js tests/omp-docker-auth.test.js tests/omp-docker-fresh-only.test.js",
     "test:providers:live": "npm run build:agent-cli-provider && node scripts/live-provider-smoke.js",
     "check:agent-cli-provider": "npm run check:agent-cli-provider:ci",
     "check:agent-cli-provider:ci": "npm run typecheck:agent-cli-provider && npm run lint:agent-cli-provider && npm run build:agent-cli-provider && npm run test:agent-cli-provider",
-    "test:cluster-client": "npm run build:cluster && node --test tests/cluster/client.test.js tests/cluster/parity.test.js tests/cluster/architecture.test.js tests/cluster/verifier-regressions.test.js tests/cluster/request-validation.test.js",
-    "test:cluster-package": "npm run build:cluster && node --test tests/cluster/package.test.js",
+    "test:cluster-client": "npm run build:cluster && node --test tests/cluster/client.test.js tests/cluster/parity.test.js tests/cluster/architecture.test.js tests/cluster/verifier-regressions.test.js tests/cluster/request-validation.test.js tests/hosted-session/coordinator.test.js",
+    "test:cluster-package": "npm run build:agent-cli-provider && npm run build:cluster && node --test tests/cluster/package.test.js",
     "dev:link": "npm link",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -132,6 +133,12 @@
       "require": "./lib/cluster/index.cjs",
       "default": "./lib/cluster/index.cjs"
     },
+    "./hosted-session": {
+      "types": "./lib/hosted-session/index.d.ts",
+      "import": "./lib/hosted-session/index.mjs",
+      "require": "./lib/hosted-session/index.cjs",
+      "default": "./lib/hosted-session/index.cjs"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },

package/scripts/build-cluster.js

@@ -4,8 +4,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const root = path.resolve(__dirname, '..');
-const buildRoot = path.join(root, '.cluster-build');
-const outputRoot = path.join(root, 'lib/cluster');
+const clusterBuildRoot = path.join(root, '.cluster-build');
+const hostedSessionBuildRoot = path.join(root, '.hosted-session-build');
+const clusterOutputRoot = path.join(root, 'lib/cluster');
+const hostedSessionOutputRoot = path.join(root, 'lib/hosted-session');
 
 function filesBelow(directory) {
   const entries = fs.readdirSync(directory, { withFileTypes: true });
@@ -15,7 +17,7 @@ function filesBelow(directory) {
   });
 }
 
-function copyBuild(sourceRoot, mode) {
+function copyBuild(sourceRoot, outputRoot, mode) {
   for (const source of filesBelow(sourceRoot)) {
     const relative = path.relative(sourceRoot, source);
     const extension = path.extname(relative);
@@ -37,7 +39,19 @@ function copyBuild(sourceRoot, mode) {
   }
 }
 
-fs.rmSync(outputRoot, { recursive: true, force: true });
-copyBuild(path.join(buildRoot, 'cjs'), 'cjs');
-copyBuild(path.join(buildRoot, 'esm'), 'esm');
-fs.rmSync(buildRoot, { recursive: true, force: true });
+fs.rmSync(clusterOutputRoot, { recursive: true, force: true });
+fs.rmSync(hostedSessionOutputRoot, { recursive: true, force: true });
+copyBuild(path.join(clusterBuildRoot, 'cjs'), clusterOutputRoot, 'cjs');
+copyBuild(path.join(clusterBuildRoot, 'esm'), clusterOutputRoot, 'esm');
+copyBuild(
+  path.join(hostedSessionBuildRoot, 'cjs', 'hosted-session'),
+  hostedSessionOutputRoot,
+  'cjs'
+);
+copyBuild(
+  path.join(hostedSessionBuildRoot, 'esm', 'hosted-session'),
+  hostedSessionOutputRoot,
+  'esm'
+);
+fs.rmSync(clusterBuildRoot, { recursive: true, force: true });
+fs.rmSync(hostedSessionBuildRoot, { recursive: true, force: true });

package/src/cluster/client.ts

@@ -16,16 +16,25 @@ import {
   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; readonly stream: WatchSubscriptionStream; }
 export interface LogsSubscription { readonly result: LogsResult; readonly stream: LogsSubscriptionStream; }
 export interface AgentAttachSubscription { readonly result: AgentAttachResult; readonly stream: AgentAttachSubscriptionStream; }
 export interface CoherentWatchSubscription extends WatchSubscription { readonly snapshot: GetResult; }
+export interface ConnectInitializedResult {
+  readonly connection: Connection;
+  readonly client: ClusterClient;
+  readonly initializeResult: InitializeResult;
+}
 
 export class ClusterClient {
   constructor(readonly connection: Connection) {}
@@ -114,6 +123,7 @@ export class ClusterClient {
 async function defaultWebSocketFactory(
   url: string,
   protocols?: string | readonly string[],
+  options?: WebSocketFactoryOptions,
 ): Promise<WebSocketLike> {
   const globalWebSocket = (globalThis as {
     readonly WebSocket?: new (
@@ -121,9 +131,16 @@ async function defaultWebSocketFactory(
       protocols?: string | readonly string[],
     ) => WebSocketLike;
   }).WebSocket;
-  if (globalWebSocket) return new globalWebSocket(url, protocols);
+  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: unknown = await import('ws');
     const candidate = imported !== null && typeof imported === 'object' && 'default' in imported
       ? imported.default
@@ -134,8 +151,9 @@ async function defaultWebSocketFactory(
     const Constructor = candidate as new (
       url: string,
       protocols?: string | readonly string[],
+      options?: { readonly headers?: Readonly<Record<string, string>> },
     ) => WebSocketLike;
-    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",
@@ -181,7 +199,7 @@ export async function connect(url: string, options: ConnectOptions = {}): Promis
   const factory = options.webSocketFactory ?? defaultWebSocketFactory;
   let socket: WebSocketLike | undefined;
   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(
@@ -197,3 +215,25 @@ export async function connect(url: string, options: ConnectOptions = {}): Promis
     throw error;
   }
 }
+
+export async function connectInitialized(url: string, options: ConnectOptions = {}): Promise<ConnectInitializedResult> {
+  const factory = options.webSocketFactory ?? defaultWebSocketFactory;
+  let socket: WebSocketLike | undefined;
+  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/src/cluster/connection.ts

@@ -27,6 +27,20 @@ export const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly C
   CLOSED: Object.freeze([] as const),
 });
 export const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export const CLOSE_REASON_MAX_BYTES = 123;
+const CLOSE_REASON_ENCODER = new TextEncoder();
+function boundedCloseReason(reason: string): string {
+  const retained: string[] = [];
+  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('');
+}
 export interface CallOptions { readonly signal?: AbortSignal; readonly requestTimeoutMs?: number; }
 
 type Deferred<T> = {
@@ -70,6 +84,8 @@ export class Connection {
   readonly #removeSocketListeners: Array<() => void> = [];
   readonly #ownedSubscriptions = new WeakSet<SubscriptionRegistration>();
   #closePromise?: Promise<void>;
+  #closeCode: number | undefined;
+  #closeReason: string | undefined;
   readonly closeDiagnostics: unknown[] = [];
   readonly protocolDiagnostics: ClusterProtocolError[] = [];
 
@@ -80,12 +96,14 @@ export class Connection {
     this.#removeSocketListeners.push(
       addSocketListener(socket, 'message', (event) => this.#onMessage(event)),
       addSocketListener(socket, 'error', () => { void this.#startClose(false); }),
-      addSocketListener(socket, 'close', () => { void this.#startClose(false); }),
+      addSocketListener(socket, 'close', (...args: unknown[]) => { this.#captureCloseState(args); void this.#startClose(false); }),
     );
   }
   get state(): ConnectionState { return this.#state; }
   get pendingSize(): number { return this.#pending.size; }
   get subscriptionCount(): number { return this.#subscriptions.size; }
+  get closeCode(): number | undefined { return this.#closeCode; }
+  get closeReason(): string | undefined { return this.#closeReason; }
   call<M extends UnaryClusterMethod>(method: M, params: ClusterMethodParams[M], options: CallOptions = {}): Promise<ClusterMethodResults[M]> {
     if (!(UNARY_METHODS as readonly string[]).includes(method)) {
       throw new ClusterConfigError(`${method} is a subscription method`, 'INVALID_METHOD');
@@ -266,6 +284,19 @@ export class Connection {
     if (this.protocolDiagnostics.length === PROTOCOL_DIAGNOSTIC_CAPACITY) this.protocolDiagnostics.shift();
     this.protocolDiagnostics.push(new ClusterProtocolError(message, 'INVALID_PEER_FRAME', cause === undefined ? undefined : { cause }));
   }
+  #captureCloseState(args: unknown[]): void {
+    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 as { code?: unknown; reason?: unknown };
+      if (typeof event.code === 'number') this.#closeCode = event.code;
+      if (typeof event.reason === 'string') this.#closeReason = boundedCloseReason(event.reason);
+    }
+  }
   #startClose(sendCancels: boolean): Promise<void> {
     if (this.#closePromise) return this.#closePromise; if (this.#state === 'CLOSED') return Promise.resolve();
     this.#transition('CLOSING'); this.#closePromise = Promise.resolve().then(() => this.#finishClose(sendCancels)); return this.#closePromise;

package/src/cluster/index.ts

@@ -14,7 +14,7 @@ export {
 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,
@@ -32,11 +32,13 @@ export type {
   WatchSubscriptionItem,
   WatchSubscriptionClosedItem,
 } from './subscriptions.js';
-export { ClusterClient, connect } from './client.js';
+export { ClusterClient, connect, connectInitialized } from './client.js';
 export type {
   AgentAttachSubscription,
   CoherentWatchSubscription,
+  ConnectInitializedResult,
   ConnectOptions,
   LogsSubscription,
   WatchSubscription,
+  WebSocketFactoryOptions,
 } from './client.js';

package/src/cluster/ws.d.ts

@@ -2,6 +2,7 @@ declare module 'ws' {
   const WebSocket: new (
     url: string,
     protocols?: string | readonly string[],
+    options?: { readonly headers?: Readonly<Record<string, string>> },
   ) => import('./index.js').WebSocketLike;
   export default WebSocket;
 }

package/src/hosted-session/coordinator.ts

@@ -0,0 +1,110 @@
+import { ClusterConfigError, connectInitialized } from '../cluster/index.js';
+import type { ServerCapabilities, GraphProfile } from '../cluster/index.js';
+import type { ConnectOptions } from '../cluster/index.js';
+import type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';
+
+function combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+  const defined = signals.filter((s): s is AbortSignal => s !== undefined);
+  if (defined.length === 0) return undefined;
+  if (defined.length === 1) return defined[0];
+  return AbortSignal.any(defined);
+}
+
+export class HostedSessionCoordinator {
+  readonly #getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+  readonly #connectOptions: Omit<ConnectOptions, 'headers' | 'signal'> | undefined;
+  readonly #clock: { now(): number };
+  readonly #closeController = new AbortController();
+  #referenceCapabilities: ServerCapabilities | undefined;
+  #closed = false;
+
+  constructor(init: HostedSessionInit) {
+    this.#getAccess = init.getAccess;
+    this.#connectOptions = init.connectOptions;
+    this.#clock = init.clock ?? Date;
+  }
+
+  async open(signal?: AbortSignal): Promise<InitializedSession> {
+    this.#requireNotClosed();
+    const session = await this.#createSession(signal);
+    this.#referenceCapabilities = session.initializeResult.capabilities;
+    return session;
+  }
+
+  async replace(signal?: AbortSignal): Promise<InitializedSession> {
+    this.#requireNotClosed();
+    const session = await this.#createSession(signal);
+    this.#verifyCapabilities(session.initializeResult.capabilities, session);
+    return session;
+  }
+
+  renewalDeadline(access: AccessResponse, receivedAt: number): number {
+    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(): Promise<void> {
+    this.#closed = true;
+    this.#closeController.abort();
+  }
+
+  async #createSession(signal?: AbortSignal): Promise<InitializedSession> {
+    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: URL;
+    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: ServerCapabilities, session: InitializedSession): void {
+    if (!this.#referenceCapabilities) return;
+    const ref = this.#referenceCapabilities;
+    const mismatches: string[] = [];
+
+    if (ref.graphProfiles) {
+      const incomingProfiles = new Set<GraphProfile>(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(): void {
+    if (this.#closed) throw new ClusterConfigError('coordinator is closed', 'COORDINATOR_CLOSED');
+  }
+}

package/src/hosted-session/index.ts

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

package/src/hosted-session/types.ts

@@ -0,0 +1,21 @@
+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;
+}