@the-open-engine/zeroshot 6.29.0 → 6.30.0

package/src/cluster/client.ts

@@ -1,20 +1,23 @@
+/// <reference path="./ws.d.ts" />
 import { PROTOCOL_VERSION } from './generated/protocol.js';
 import type {
   AgentAttachParams, AgentAttachResult, ApplyParams, ApplyResult, DeleteParams, DeleteResult,
   GetParams, GetResult, InitializeParams, InitializeResult, LogsParams, LogsResult,
   PlanParams, PlanResult, ResubmitParams, ResubmitResult, RetryParams, RetryResult,
-  StopParams, StopResult, UpdateParams, UpdateResult, WatchParams, WatchResult,
+  StopParams, StopResult, UpdateParams, UpdateResult, WatchParams,
 } from './generated/protocol.js';
 import { Connection } from './connection.js';
 import type { CallOptions } from './connection.js';
-import { addSocketListener } from './socket.js';
+import { addSocketEmitterListener, addSocketListener } from './socket.js';
 import type { WebSocketLike } from './socket.js';
-import { ClusterConfigError, ClusterProtocolError, ClusterTransportError } from './errors.js';
+import { ClusterConfigError, ClusterProtocolError, ClusterTransportError, ClusterUpgradeError } from './errors.js';
 import {
   AgentAttachSubscriptionStream,
   LogsSubscriptionStream,
   WatchSubscriptionStream,
 } from './subscriptions.js';
+import type { WatchSubscription } from './subscriptions.js';
+export type { WatchSubscription } from './subscriptions.js';
 
 export interface WebSocketFactoryOptions {
   readonly headers?: Readonly<Record<string, string>>;
@@ -26,7 +29,6 @@ export interface ConnectOptions {
   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; }
@@ -131,13 +133,7 @@ async function defaultWebSocketFactory(
       protocols?: string | readonly string[],
     ) => WebSocketLike;
   }).WebSocket;
-  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',
-      );
-    }
+  if (globalWebSocket && (!options?.headers || Object.keys(options.headers).length === 0)) {
     return new globalWebSocket(url, protocols);
   }
   try {
@@ -175,6 +171,7 @@ async function waitForOpen(socket: WebSocketLike, signal?: AbortSignal): Promise
   await new Promise<void>((resolve, reject) => {
     let settled = false;
     const removers: Array<() => void> = [];
+    let upgradeFailure: ClusterUpgradeError | ClusterTransportError | undefined;
     const settle = (fn: () => void) => {
       if (settled) return;
       settled = true;
@@ -186,15 +183,45 @@ async function waitForOpen(socket: WebSocketLike, signal?: AbortSignal): Promise
       'connect aborted locally; the server may still have committed this request',
       'AbortError',
     )));
+    const onUnexpectedResponse = (...args: unknown[]) => {
+      const response = args.find(
+        (value) => value !== null && typeof value === 'object' && 'statusCode' in value,
+      ) as { statusCode?: unknown; resume?: () => void } | undefined;
+      const status = response?.statusCode;
+      upgradeFailure = typeof status === 'number'
+        ? new ClusterUpgradeError(status)
+        : new ClusterTransportError('WebSocket upgrade rejected', 'UPGRADE_REJECTED');
+      response?.resume?.();
+      if (socket.terminate) {
+        socket.terminate();
+      } else {
+        settle(() => reject(upgradeFailure));
+      }
+    };
     removers.push(
       addSocketListener(socket, 'open', () => settle(resolve)),
-      addSocketListener(socket, 'error', (error) => settle(() => reject(new ClusterTransportError('WebSocket failed to open', 'OPEN_FAILED', { cause: error })))),
-      addSocketListener(socket, 'close', () => settle(() => reject(new ClusterTransportError('WebSocket closed before opening', 'OPEN_FAILED')))),
+      addSocketListener(socket, 'error', (error) => settle(() => reject(
+        upgradeFailure ??
+          new ClusterTransportError('WebSocket failed to open', 'OPEN_FAILED', { cause: error }),
+      ))),
+      addSocketListener(socket, 'close', () => settle(() => reject(
+        upgradeFailure ??
+          new ClusterTransportError('WebSocket closed before opening', 'OPEN_FAILED'),
+      ))),
+      addSocketEmitterListener(socket, 'unexpected-response', onUnexpectedResponse),
     );
     signal?.addEventListener('abort', onAbort, { once: true });
   });
 }
 
+async function disposeFailedSocket(socket: WebSocketLike): Promise<void> {
+  if (socket.readyState === 0 && socket.terminate) {
+    socket.terminate();
+  } else {
+    await socket.close();
+  }
+}
+
 export async function connect(url: string, options: ConnectOptions = {}): Promise<Connection> {
   const factory = options.webSocketFactory ?? defaultWebSocketFactory;
   let socket: WebSocketLike | undefined;
@@ -209,7 +236,7 @@ export async function connect(url: string, options: ConnectOptions = {}): Promis
     return connection;
   } catch (error) {
     if (socket) {
-      try { await socket.close(); }
+      try { await disposeFailedSocket(socket); }
       catch { /* preserve the construction error */ }
     }
     throw error;
@@ -231,7 +258,7 @@ export async function connectInitialized(url: string, options: ConnectOptions =
     return { connection, client, initializeResult };
   } catch (error) {
     if (socket) {
-      try { await socket.close(); }
+      try { await disposeFailedSocket(socket); }
       catch { /* preserve the construction error */ }
     }
     throw error;

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',
+    );
+  }
+}