@the-open-engine/zeroshot 6.29.0 → 6.29.1

package/src/cluster/connection-state.ts

@@ -0,0 +1,33 @@
+if (!Object.prototype.hasOwnProperty.call(Symbol, 'asyncDispose')) {
+  Object.defineProperty(Symbol, 'asyncDispose', {
+    configurable: false, enumerable: false,
+    value: Symbol.for('Symbol.asyncDispose'), writable: false,
+  });
+}
+
+export type ConnectionState = 'OPEN' | 'CLOSING' | 'CLOSED';
+export const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly ConnectionState[]>> = Object.freeze({
+  OPEN: Object.freeze(['CLOSING'] as const),
+  CLOSING: Object.freeze(['CLOSED'] as const),
+  CLOSED: Object.freeze([] as const),
+});
+export const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export interface ConnectionCloseSnapshot {
+  readonly code: number | null;
+  readonly reason: null;
+}
+
+export type Deferred<T> = {
+  readonly promise: Promise<T>;
+  readonly resolve: (value: T) => void;
+  readonly reject: (reason: unknown) => void;
+};
+export function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((onResolve, onReject) => {
+    resolve = onResolve;
+    reject = onReject;
+  });
+  return { promise, resolve, reject };
+}

package/src/cluster/connection-types.ts

@@ -0,0 +1,28 @@
+import type { FrameRecord } from './frames.js';
+import type { BoundedQueue } from './queue.js';
+import type { ClusterMethod } from './generated/protocol.js';
+
+export interface CallOptions {
+  readonly signal?: AbortSignal;
+  readonly requestTimeoutMs?: number;
+}
+export type SubscriptionKind = 'watch' | 'logs' | 'agent/attach';
+export type SubscriptionRegistration = {
+  readonly id: string;
+  readonly kind: SubscriptionKind;
+  readonly queue: BoundedQueue<FrameRecord>;
+  overflowed: boolean;
+  cancelSent: boolean;
+  abortHandler?: () => void;
+  abortSignal?: AbortSignal;
+};
+export type EstablishedSubscription<R> = {
+  readonly result: R;
+  readonly registration: SubscriptionRegistration;
+};
+export type PendingEntry = {
+  readonly id: string; readonly method: ClusterMethod; readonly expectedId: string;
+  readonly resolve: (value: unknown) => void; readonly reject: (reason: unknown) => void;
+  readonly subscriptionKind?: SubscriptionKind; settled: boolean;
+  abortHandler?: () => void; signal?: AbortSignal; timeout?: ReturnType<typeof setTimeout>;
+};

package/src/cluster/connection.ts

@@ -13,68 +13,32 @@ import { BoundedQueue } from './queue.js';
 import { addSocketListener } from './socket.js';
 import type { WebSocketLike } from './socket.js';
 import { assertDefinition, assertMethodResult } from './validators.js';
-if (!Object.prototype.hasOwnProperty.call(Symbol, 'asyncDispose')) {
-  Object.defineProperty(Symbol, 'asyncDispose', {
-    configurable: false, enumerable: false,
-    value: Symbol.for('Symbol.asyncDispose'), writable: false,
-  });
-}
-
-export type ConnectionState = 'OPEN' | 'CLOSING' | 'CLOSED';
-export const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly ConnectionState[]>> = Object.freeze({
-  OPEN: Object.freeze(['CLOSING'] as const),
-  CLOSING: Object.freeze(['CLOSED'] as const),
-  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> = {
-  readonly promise: Promise<T>;
-  readonly resolve: (value: T) => void;
-  readonly reject: (reason: unknown) => void;
-};
-function deferred<T>(): Deferred<T> {
-  let resolve!: (value: T) => void; let reject!: (reason: unknown) => void;
-  const promise = new Promise<T>((onResolve, onReject) => {
-    resolve = onResolve; reject = onReject;
-  });
-  return { promise, resolve, reject };
-}
-export type SubscriptionKind = 'watch' | 'logs' | 'agent/attach';
-export type SubscriptionRegistration = {
-  readonly id: string;
-  readonly kind: SubscriptionKind;
-  readonly queue: BoundedQueue<FrameRecord>;
-  overflowed: boolean;
-  cancelSent: boolean;
-  abortHandler?: () => void;
-  abortSignal?: AbortSignal;
-};
-export type EstablishedSubscription<R> = {
-  readonly result: R;
-  readonly registration: SubscriptionRegistration;
-};
-type PendingEntry = {
-  readonly id: string; readonly method: ClusterMethod; readonly expectedId: string;
-  readonly resolve: (value: unknown) => void; readonly reject: (reason: unknown) => void;
-  readonly subscriptionKind?: SubscriptionKind; settled: boolean;
-  abortHandler?: () => void; signal?: AbortSignal; timeout?: ReturnType<typeof setTimeout>;
-};
+import {
+  CONNECTION_TRANSITIONS,
+  PROTOCOL_DIAGNOSTIC_CAPACITY,
+  deferred,
+  type ConnectionCloseSnapshot,
+  type ConnectionState,
+} from './connection-state.js';
+export {
+  CONNECTION_TRANSITIONS,
+  PROTOCOL_DIAGNOSTIC_CAPACITY,
+  type ConnectionCloseSnapshot,
+  type ConnectionState,
+} from './connection-state.js';
+import type {
+  CallOptions,
+  EstablishedSubscription,
+  PendingEntry,
+  SubscriptionKind,
+  SubscriptionRegistration,
+} from './connection-types.js';
+export type {
+  CallOptions,
+  EstablishedSubscription,
+  SubscriptionKind,
+  SubscriptionRegistration,
+} from './connection-types.js';
 
 export class Connection {
   #state: ConnectionState = 'OPEN'; #sequence = 1;
@@ -85,7 +49,9 @@ export class Connection {
   readonly #ownedSubscriptions = new WeakSet<SubscriptionRegistration>();
   #closePromise?: Promise<void>;
   #closeCode: number | undefined;
-  #closeReason: string | undefined;
+  readonly #closedCompletion = deferred<ConnectionCloseSnapshot>();
+  readonly closed: Promise<ConnectionCloseSnapshot> = this.#closedCompletion.promise;
+  #closeSnapshot: ConnectionCloseSnapshot | undefined;
   readonly closeDiagnostics: unknown[] = [];
   readonly protocolDiagnostics: ClusterProtocolError[] = [];
 
@@ -103,7 +69,8 @@ export class Connection {
   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; }
+  get closeReason(): undefined { return undefined; }
+  get closeSnapshot(): ConnectionCloseSnapshot | undefined { return this.#closeSnapshot; }
   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');
@@ -289,12 +256,9 @@ export class Connection {
     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 };
+      const event = first as { code?: 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> {
@@ -319,6 +283,11 @@ export class Connection {
       try { remove(); } catch (error) { this.recordDiagnostic(error); }
     }
     this.#transition('CLOSED');
+    this.#closeSnapshot = Object.freeze({
+      code: this.#closeCode ?? null,
+      reason: null,
+    });
+    this.#closedCompletion.resolve(this.#closeSnapshot);
   }
   #transition(to: ConnectionState): void {
     if (!CONNECTION_TRANSITIONS[this.#state].includes(to)) throw new ClusterInternalError(`illegal connection transition ${this.#state} -> ${to}`, 'ILLEGAL_STATE_TRANSITION');

package/src/cluster/errors.ts

@@ -15,6 +15,11 @@ export class ClusterTransportError extends ClusterError {}
 export class ClusterTimeoutError extends ClusterError {}
 export class ClusterRequestError extends ClusterError {}
 
+export class ClusterUpgradeError extends ClusterTransportError {
+  constructor(readonly status: number) {
+    super(`WebSocket upgrade rejected with HTTP ${status}`, 'UPGRADE_REJECTED');
+  }
+}
 export function requestAbortError(method: string): DOMException {
   return new DOMException(
     `${method} aborted locally; the server may still have committed this request`,

package/src/cluster/index.ts

@@ -10,14 +10,16 @@ export {
   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 { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
 export type {
   CallOptions,
   ConnectionState,
+  ConnectionCloseSnapshot,
 } from './connection.js';
 export type { WebSocketLike } from './socket.js';
 export {

package/src/cluster/json-source.ts

@@ -3,6 +3,7 @@ import { MAX_FRAME_BYTES } from './generated/protocol.js';
 
 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: Uint8Array): unknown {
   if (bytes.length > MAX_REQUEST_BYTES) {
     throw new ClusterRequestError(

package/src/cluster/payload-value.ts

@@ -65,6 +65,7 @@ function evaluate(type: PayloadType, value: unknown, path: string): InternalIssu
   }
 }
 
+/** Return the first deterministic schema issue without retaining the input value. */
 export function firstInputValidationIssue(
   type: PayloadType,
   value: unknown,

package/src/cluster/socket.ts

@@ -4,6 +4,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;
@@ -29,3 +30,15 @@ export function addSocketListener(
     'INVALID_WEBSOCKET',
   );
 }
+
+export function addSocketEmitterListener(
+  socket: WebSocketLike,
+  type: string,
+  listener: (...args: unknown[]) => void,
+): () => void {
+  if (socket.on) {
+    socket.on(type, listener);
+    return () => (socket.off ?? socket.removeListener)?.call(socket, type, listener);
+  }
+  return addSocketListener(socket, type, listener);
+}

package/src/cluster/subscriptions.ts

@@ -22,6 +22,11 @@ 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>;
 class SubscriptionStream<T> implements Subscription<T> {
@@ -198,13 +203,13 @@ export class WatchSubscriptionStream implements AsyncIterator<WatchSubscriptionI
     await this.#terminate(true); throw error;
   }
   cancel(): Promise<void> { return this.#terminate(true); }
-  reconnect(freshConnection: Connection): Promise<import('./client.js').WatchSubscription> {
+  reconnect(freshConnection: Connection): Promise<WatchSubscription> {
     if (this.#reconnectConsumed) {
       throw new ClusterStateError('watch stream reconnect is one-shot', 'RECONNECT_CONSUMED');
     }
     this.#reconnectConsumed = true; return this.#reconnectOn(freshConnection);
   }
-  async #reconnectOn(freshConnection: Connection): Promise<import('./client.js').WatchSubscription> {
+  async #reconnectOn(freshConnection: Connection): Promise<WatchSubscription> {
     await this.#terminate(true);
     try {
       const runId = this.#runId; const fromCursor = this.#lastDelivered;

package/src/cluster/validators.ts

@@ -64,6 +64,7 @@ function assertRequestDefinition(definition: string, value: unknown, code: strin
   throw new ClusterRequestError(`${definition} validation failed: ${details}`, code);
 }
 
+/** Validate an execution graph against the frozen cluster protocol schema. */
 export function assertGraphSpec(value: unknown): asserts value is GraphSpec {
   assertRequestDefinition('GraphSpec', value, 'INVALID_GRAPH');
 }

package/src/cluster/ws.d.ts

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

package/src/hosted-session/authority.ts

@@ -0,0 +1,77 @@
+import { ClusterConfigError } from '../cluster/index.js';
+import type { HostedAccess } from './types.js';
+
+const LOOPBACK_HOSTS: Readonly<Record<string, true>> = Object.freeze({
+  '127.0.0.1': true,
+  '::1': true,
+  '[::1]': true,
+});
+
+function parseCanonicalUrl(value: string, message: string, code: string): URL {
+  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 ClusterConfigError(message, code);
+  }
+}
+
+function hasOriginSuffix(url: URL): boolean {
+  return Boolean(
+    url.username ||
+    url.password ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash,
+  );
+}
+
+export function normalizedAuthority(value: string): string {
+  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 ClusterConfigError(message, 'INVALID_TARGET_AUTHORITY');
+  }
+  return url.origin;
+}
+
+function accessAuthorityMatches(endpoint: URL, target: URL): boolean {
+  const expectedProtocol = target.protocol === 'http:' ? 'ws:' : 'wss:';
+  return (
+    endpoint.protocol === expectedProtocol &&
+    endpoint.host === target.host &&
+    !endpoint.username &&
+    !endpoint.password &&
+    !endpoint.search &&
+    !endpoint.hash
+  );
+}
+
+export function validateHostedAccess(access: HostedAccess, targetAuthority: string): void {
+  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 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 ClusterConfigError(
+      'access grant does not match the hosted session contract',
+      'INVALID_ACCESS_GRANT',
+    );
+  }
+}

package/src/hosted-session/coordinator.ts

@@ -1,26 +1,48 @@
-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';
+import {
+  ClusterConfigError,
+  ClusterUpgradeError,
+  connectInitialized,
+  type ServerCapabilities,
+  type GraphProfile,
+} from '../cluster/index.js';
+import type {
+  HostedAccess,
+  HostedSessionInit,
+  HostedWatch,
+  HostedWatchOptions,
+  InitializedSession,
+} from './types.js';
+import { normalizedAuthority, validateHostedAccess } from './authority.js';
+import { HostedAuthenticationError } from './errors.js';
+import { ReconnectingHostedWatch } from './reconnecting-watch.js';
+export {
+  HostedAuthenticationError,
+  HostedAuthorizationError,
+  HostedTransportUncertainError,
+} from './errors.js';
+
 
 function combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
-  const defined = signals.filter((s): s is AbortSignal => s !== undefined);
+  const defined = signals.filter((signal): signal is AbortSignal => signal !== 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 #init: HostedSessionInit;
+  readonly #targetAuthority: string;
   readonly #clock: { now(): number };
   readonly #closeController = new AbortController();
+  readonly #sessions = new Set<InitializedSession>();
   #referenceCapabilities: ServerCapabilities | undefined;
   #closed = false;
 
   constructor(init: HostedSessionInit) {
-    this.#getAccess = init.getAccess;
-    this.#connectOptions = init.connectOptions;
+    if (init.capsuleId.length === 0)
+      throw new ClusterConfigError('capsuleId must not be empty', 'INVALID_CAPSULE_ID');
+    this.#init = init;
+    this.#targetAuthority = normalizedAuthority(init.targetAuthority);
     this.#clock = init.clock ?? Date;
   }
 
@@ -34,72 +56,107 @@ export class HostedSessionCoordinator {
   async replace(signal?: AbortSignal): Promise<InitializedSession> {
     this.#requireNotClosed();
     const session = await this.#createSession(signal);
-    this.#verifyCapabilities(session.initializeResult.capabilities, session);
-    return session;
+    try {
+      if (this.#referenceCapabilities !== undefined) {
+        this.#verifyCapabilities(
+          this.#referenceCapabilities,
+          session.initializeResult.capabilities
+        );
+      }
+      return session;
+    } catch (error) {
+      await session.connection.close();
+      throw error;
+    }
+  }
+
+  async watch(options: HostedWatchOptions): Promise<HostedWatch> {
+    const session = await this.open(options.signal);
+    try {
+      const subscription = await session.client.watch(
+        options.params,
+        options.signal === undefined ? {} : { signal: options.signal }
+      );
+      const hosted = new ReconnectingHostedWatch(
+        (replacementSignal) => this.replace(replacementSignal),
+        session,
+        subscription,
+        options.signal,
+      );
+      options.signal?.addEventListener(
+        'abort',
+        () => {
+          void hosted.cancel().catch(() => undefined);
+        },
+        { once: true }
+      );
+      if (options.signal?.aborted) {
+        await hosted.cancel();
+        throw options.signal.reason ?? new DOMException('hosted watch aborted', 'AbortError');
+      }
+      return hosted;
+    } catch (error) {
+      await session.connection.close();
+      throw error;
+    }
   }
 
-  renewalDeadline(access: AccessResponse, receivedAt: number): number {
+  renewalDeadline(access: HostedAccess, receivedAt: number): number {
     const expiresAt = Date.parse(access.expiresAt);
-    if (Number.isNaN(expiresAt)) {
-      throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+    if (!Number.isFinite(expiresAt) || expiresAt <= receivedAt) {
+      throw new ClusterConfigError(
+        'access expiry must be a future RFC 3339 timestamp',
+        'INVALID_ACCESS_EXPIRY'
+      );
     }
     const lifetime = expiresAt - receivedAt;
-    return Math.min(expiresAt - 30_000, receivedAt + 0.8 * lifetime);
+    const lead = Math.max(5_000, Math.min(60_000, Math.floor(lifetime * 0.1)));
+    return Math.max(receivedAt, expiresAt - lead);
   }
 
   async close(): Promise<void> {
+    if (this.#closed) return;
     this.#closed = true;
-    this.#closeController.abort();
+    this.#closeController.abort(new DOMException('coordinator closed', 'AbortError'));
+    const sessions = [...this.#sessions];
+    await Promise.all(sessions.map((session) => session.connection.close()));
+    this.#sessions.clear();
   }
 
   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;
+    const access = await this.#init.adapter.access(this.#init.capsuleId, combined);
+    validateHostedAccess(access, this.#targetAuthority);
+    const receivedAt = this.#clock.now();
+    this.renewalDeadline(access, receivedAt);
     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');
+      const session = await connectInitialized(access.websocketUrl, {
+        ...this.#init.connectOptions,
+        headers: { Authorization: `Bearer ${access.accessToken}` },
+        ...(combined === undefined ? {} : { signal: combined }),
+      });
+      this.#sessions.add(session);
+      void session.connection.closed.then(() => this.#sessions.delete(session));
+      return session;
+    } catch (error) {
+      if (error instanceof ClusterUpgradeError && error.status === 401)
+        throw new HostedAuthenticationError();
+      throw error;
     }
-
-    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();
+  #verifyCapabilities(reference: ServerCapabilities, incoming: ServerCapabilities): void {
+    const referenceProfiles = new Set<GraphProfile>(reference.graphProfiles ?? []);
+    const incomingProfiles = new Set<GraphProfile>(incoming.graphProfiles ?? []);
+    if (
+      (reference.logs && !incoming.logs) ||
+      (reference.agentAttach && !incoming.agentAttach) ||
+      [...referenceProfiles].some((profile) => !incomingProfiles.has(profile))
+    ) {
       throw new ClusterConfigError(
-        `replacement capabilities incompatible: ${mismatches.join(', ')}`,
-        'INCOMPATIBLE_CAPABILITIES'
+        'replacement connection removed required server capabilities',
+        'CAPABILITY_REGRESSION'
       );
     }
   }

package/src/hosted-session/errors.ts

@@ -0,0 +1,21 @@
+export class HostedAuthenticationError extends Error {
+  constructor() {
+    super('Hosted target authentication failed');
+    this.name = 'HostedAuthenticationError';
+  }
+}
+
+export class HostedAuthorizationError extends Error {
+  constructor() {
+    super('Hosted target authorization was revoked');
+    this.name = 'HostedAuthorizationError';
+  }
+}
+
+export class HostedTransportUncertainError extends Error {
+  readonly executionRetryAuthorized = false;
+  constructor() {
+    super('Hosted session transport closed with uncertain execution state');
+    this.name = 'HostedTransportUncertainError';
+  }
+}

package/src/hosted-session/index.ts

@@ -1,2 +1,14 @@
-export { HostedSessionCoordinator } from './coordinator.js';
-export type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';
+export {
+  HostedSessionCoordinator,
+  HostedAuthenticationError,
+  HostedAuthorizationError,
+  HostedTransportUncertainError,
+} from './coordinator.js';
+export type {
+  HostedAccess,
+  HostedAccessAdapter,
+  HostedSessionInit,
+  HostedWatch,
+  HostedWatchOptions,
+  InitializedSession,
+} from './types.js';