@the-open-engine/zeroshot 6.28.0 → 6.29.1

package/README.md

@@ -15,7 +15,7 @@
 [![npm](https://img.shields.io/npm/v/@the-open-engine/zeroshot?style=flat&labelColor=171411&color=171411)](https://www.npmjs.com/package/@the-open-engine/zeroshot)
 [![CI](https://img.shields.io/github/actions/workflow/status/the-open-engine/zeroshot/ci.yml?style=flat&labelColor=171411&label=CI)](https://github.com/the-open-engine/zeroshot/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-171411?style=flat)](LICENSE)
-[![node](https://img.shields.io/badge/node-%E2%89%A5%2018-171411?style=flat)](#install)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2022-171411?style=flat)](#install)
 [![platforms](https://img.shields.io/badge/platforms-linux%20%C2%B7%20macos-171411?style=flat)](#install)
 [![stars](https://img.shields.io/github/stars/the-open-engine/zeroshot?style=flat&labelColor=171411&color=171411)](https://github.com/the-open-engine/zeroshot)
 [![Layer 01 · The Open Engine](https://img.shields.io/badge/Layer_01-The_Open_Engine-C2240C?style=flat&labelColor=171411)](#the-open-engine)
@@ -43,7 +43,7 @@ Zeroshot is an open-source, multi-agent orchestration engine for autonomous soft
 npm install -g @the-open-engine/zeroshot
 ```
 
-Requires **Node ≥ 18** and at least one provider CLI (Claude Code, Codex, Gemini, or OpenCode). Linux and macOS today; Windows is deferred.
+Requires **Node ≥ 22** and at least one provider CLI (Claude Code, Codex, Gemini, or OpenCode). The package includes the pinned Opcore constraints CLI; repository hook activation remains explicit. Linux and macOS today; Windows is deferred.
 
 <div align="center">
   <img src="docs/assets/zeroshot-demo.gif" alt="Zeroshot resolving an issue through the executor-verifier loop" width="760">
@@ -207,7 +207,7 @@ Zeroshot is **Layer 01 · Verification** of [The Open Engine](https://theopeneng
 | 02     | Constraints: **Opcore**    | Sibling · alpha             |
 | 03-05  | Intent · Context · Runtime | In development              |
 
-Zeroshot runs the loop: an agent writes the change, and an **independent** verifier decides whether it holds: approve, or a reproducible failure. **Opcore** is the sibling layer, a deterministic, local, read-only **constraints** gate for coding agents (currently private alpha `0.1.0-alpha.0`, built in the open, not yet published). Verification asks _"does this meet the goal?"_; constraints ask _"is this within tolerance?"_
+Zeroshot runs the loop: an agent writes the change, and an **independent** verifier decides whether it holds: approve, or a reproducible failure. **Opcore** is the sibling layer, a deterministic, local, read-only **constraints** gate for coding agents. Zeroshot packages Opcore `0.2.1` and uses introduced-change validation so existing repository debt never blocks an otherwise clean change. Verification asks _"does this meet the goal?"_; constraints ask _"is this within tolerance?"_
 
 Each layer ships the same way: extracted from the platform we run, then opened. **Trust nothing. Verify everything.**
 

package/cli/index.js

@@ -2647,6 +2647,7 @@ Shell completion:
   );
 
 // Run command - CLUSTER with auto-detection
+
 program
   .command('run <input>')
   .description(
@@ -3959,6 +3960,10 @@ for (const providerName of VALID_PROVIDERS) {
 // Settings management
 const settingsCmd = program.command('settings').description('Manage zeroshot settings');
 const INTERNAL_SETTINGS_KEYS = new Set(['lastUpdateCheckClaim', '_targets']);
+// Fail closed while hosted commands are unpublished. Keeping these names out of the
+// default `run` rewrite makes them unknown commands rather than local task input.
+// Issue #920 deliberately has no CLI lifecycle or runtime execution surface.
+const UNREGISTERED_HOSTED_COMMAND_NAMES = new Set(['target', 'capsule']);
 
 function visibleSettingKeys() {
   return Object.keys(DEFAULT_SETTINGS).filter((key) => !INTERNAL_SETTINGS_KEYS.has(key));
@@ -4490,211 +4495,7 @@ settingsCmd.action(() => {
   formatSettingsList(settings, true);
 });
 
-// Target management commands
-// Target modules are compiled during install/package preparation for the Node 18+ CLI.
-const importTarget = (mod) => import(`../lib/target/${mod}.js`);
-const targetCmd = program.command('target').description('Manage named remote targets');
-
-targetCmd
-  .command('add <name>')
-  .description('Register a named remote target')
-  .requiredOption('--url <url>', 'Service URL for the target')
-  .action(async (name, options) => {
-    try {
-      const { addTarget } = await importTarget('target-registry');
-      const settingsPort = {
-        load: () => loadSettings(),
-        mutate: (fn) => mutateSettings(fn),
-      };
-      const record = addTarget(name, options.url, settingsPort);
-      console.log(chalk.green(`✓ Target "${name}" added (${record.url})`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-targetCmd
-  .command('login <name>')
-  .description('Authenticate with a remote target via device login')
-  .action(async (name) => {
-    try {
-      const { getTarget } = await importTarget('target-registry');
-      const { targetLogin } = await importTarget('target-session');
-      const { KeyringCredentialStore } = await importTarget('credential-store');
-      const { acquireTargetLock } = await importTarget('credential-lock');
-      const { discoverTargetSessionEndpoints } = await importTarget('discovery');
-
-      const settingsPort = {
-        load: () => loadSettings(),
-        mutate: (fn) => mutateSettings(fn),
-      };
-
-      const target = getTarget(name, settingsPort);
-      if (!target) {
-        console.error(chalk.red(`Target "${name}" not found.`));
-        process.exit(1);
-      }
-
-      const http = { fetch: (url, init) => fetch(url, init) };
-      const discoveryEndpoints = await discoverTargetSessionEndpoints(target.url, http);
-
-      const credentialStore = await KeyringCredentialStore.create();
-      const openPkg = await import('open');
-      const browserOpen = openPkg.default || openPkg;
-
-      const result = await targetLogin(
-        name,
-        target,
-        credentialStore,
-        () => acquireTargetLock(target.id),
-        settingsPort,
-        {
-          http,
-          clock: { now: () => Date.now() },
-          browserOpener: {
-            open: async (url) => {
-              await browserOpen(url);
-            },
-          },
-          stderr: process.stderr,
-          discoveryEndpoints,
-        }
-      );
-
-      console.log(
-        chalk.green(`✓ Logged in to "${name}" (organization: ${result.organization.name})`)
-      );
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-targetCmd
-  .command('list')
-  .description('List registered remote targets')
-  .option('--json', 'Output as JSON')
-  .action(async (options) => {
-    try {
-      const { listTargets } = await importTarget('target-registry');
-      const settingsPort = {
-        load: () => loadSettings(),
-        mutate: (fn) => mutateSettings(fn),
-      };
-
-      const targets = listTargets(settingsPort);
-
-      if (options.json) {
-        const output = targets.map(({ name, record }) => ({
-          name,
-          id: record.id,
-          url: record.url,
-          organization: record.organization ?? null,
-          loggedIn: false,
-          createdAt: record.createdAt,
-        }));
-
-        // Try to check keyring presence for each target
-        try {
-          const { KeyringCredentialStore } = await importTarget('credential-store');
-          const { targetServiceKey, TARGET_ACCOUNT } = await importTarget('credential-store');
-          const store = await KeyringCredentialStore.create();
-          for (const item of output) {
-            const matchingTarget = targets.find((t) => t.name === item.name);
-            if (matchingTarget) {
-              const cred = await store.get(
-                targetServiceKey(matchingTarget.record.id),
-                TARGET_ACCOUNT
-              );
-              item.loggedIn = cred !== null;
-            }
-          }
-        } catch {
-          // Keyring unavailable, all show as not logged in
-        }
-
-        console.log(JSON.stringify(output, null, 2));
-        return;
-      }
-
-      if (targets.length === 0) {
-        console.log(
-          chalk.dim(
-            'No targets registered. Use `zeroshot target add <name> --url <url>` to add one.'
-          )
-        );
-        return;
-      }
-
-      for (const { name, record } of targets) {
-        const org = record.organization ? ` (org: ${record.organization.name})` : '';
-        console.log(`  ${chalk.bold(name)}  ${record.url}${org}`);
-      }
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-targetCmd
-  .command('remove <name>')
-  .description('Remove a named remote target')
-  .option('--force', 'Remove even if remote revocation fails')
-  .action(async (name, options) => {
-    try {
-      const { getTarget, removeTarget } = await importTarget('target-registry');
-      const { revokeAndCleanup } = await importTarget('target-session');
-      const { acquireTargetLock } = await importTarget('credential-lock');
-      const { discoverTargetSessionEndpoints } = await importTarget('discovery');
-
-      const settingsPort = {
-        load: () => loadSettings(),
-        mutate: (fn) => mutateSettings(fn),
-      };
-
-      const target = getTarget(name, settingsPort);
-      if (!target) {
-        console.error(chalk.red(`Target "${name}" not found.`));
-        process.exit(1);
-      }
-
-      // Try to revoke and cleanup keyring
-      try {
-        const { KeyringCredentialStore } = await importTarget('credential-store');
-        const credentialStore = await KeyringCredentialStore.create();
-        const http = { fetch: (url, init) => fetch(url, init) };
-        const discoveryEndpoints = await discoverTargetSessionEndpoints(target.url, http);
-        await revokeAndCleanup(
-          target,
-          credentialStore,
-          () => acquireTargetLock(target.id),
-          {
-            http,
-            discoveryEndpoints,
-          },
-          !!options.force
-        );
-      } catch (error) {
-        if (!options.force) {
-          console.error(chalk.red(error.message));
-          process.exit(1);
-        }
-        // Force mode: continue with removal
-      }
-
-      removeTarget(name, settingsPort);
-      console.log(chalk.green(`✓ Target "${name}" removed`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-targetCmd.action(() => {
-  targetCmd.help();
-});
-
+// Hosted target commands intentionally are not registered on the stable CLI.
 // Providers management
 const providersCmd = program.command('providers').description('Manage AI providers');
 providersCmd.action(async () => {
@@ -6255,6 +6056,16 @@ function isStartupUpdateEligible(argv, options = {}) {
   });
 }
 
+function applyDefaultCommand(args) {
+  const firstArg = args[0];
+  if (!firstArg || firstArg.startsWith('-')) return;
+
+  const commandNames = program.commands.map((command) => command.name());
+  if (commandNames.includes(firstArg) || UNREGISTERED_HOSTED_COMMAND_NAMES.has(firstArg)) return;
+
+  process.argv.splice(2, 0, 'run');
+}
+
 // Main entry point
 async function main() {
   printLegacyDistroNotice();
@@ -6280,31 +6091,16 @@ async function main() {
     checkForUpdates({ argv: startupArgs, eligibilityChecked: true });
   }
 
-  let args = startupArgs;
+  const args = startupArgs;
 
   if (args.length === 0) {
     program.outputHelp();
     return;
   }
 
-  // Default command handling: if first arg doesn't match a known command, treat it as 'run'
-  // This allows `zeroshot "task"` to work the same as `zeroshot run "task"`
-  args = process.argv.slice(2);
-  if (args.length > 0) {
-    const firstArg = args[0];
-
-    // Skip if it's a flag/option (starts with -)
-    // Skip if it's --help or --version (these are handled by commander)
-    if (!firstArg.startsWith('-')) {
-      // Get all registered command names
-      const commandNames = program.commands.map((cmd) => cmd.name());
-
-      // If first arg is not a known command, prepend 'run'
-      if (!commandNames.includes(firstArg)) {
-        process.argv.splice(2, 0, 'run');
-      }
-    }
-  }
+  // Preserve the default local run shorthand without treating hosted-only command
+  // names as task input in the stable parser.
+  applyDefaultCommand(args);
 
   program.parse();
 }

package/docker/zeroshot-cluster/Dockerfile

@@ -4,12 +4,11 @@
 # Build: docker build -t vibe-cluster-base vibe/cluster/docker/vibe-cluster/
 # Usage: zeroshot run <task> --docker
 
-FROM node:20-slim
+FROM node:22-slim
 
 # Upgrade npm to fix Arborist isDescendantOf bug (npm 10.x crash on complex peer deps)
 # See: https://github.com/npm/cli/issues/7682
-# Pinned to npm@11 (the latest line that still supports the node:20-slim base); npm@latest (12.x)
-# now requires node >=22 and breaks the build with EBADENGINE.
+# Pinned to npm@11 to keep the container toolchain reproducible with the supported Node 22 line.
 RUN npm install -g npm@11
 
 # Version pinning for infrastructure tools

package/lib/cluster/client.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClusterClient = void 0;
 exports.connect = connect;
 exports.connectInitialized = connectInitialized;
+/// <reference path="./ws.d.ts" />
 const protocol_js_1 = require("./generated/protocol.cjs");
 const connection_js_1 = require("./connection.cjs");
 const socket_js_1 = require("./socket.cjs");
@@ -82,10 +83,7 @@ class ClusterClient {
 exports.ClusterClient = ClusterClient;
 async function defaultWebSocketFactory(url, protocols, options) {
     const globalWebSocket = globalThis.WebSocket;
-    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');
-        }
+    if (globalWebSocket && (!options?.headers || Object.keys(options.headers).length === 0)) {
         return new globalWebSocket(url, protocols);
     }
     try {
@@ -114,6 +112,7 @@ async function waitForOpen(socket, signal) {
     await new Promise((resolve, reject) => {
         let settled = false;
         const removers = [];
+        let upgradeFailure;
         const settle = (fn) => {
             if (settled)
                 return;
@@ -124,10 +123,34 @@ async function waitForOpen(socket, signal) {
             fn();
         };
         const onAbort = () => settle(() => reject(new DOMException('connect aborted locally; the server may still have committed this request', 'AbortError')));
-        removers.push((0, socket_js_1.addSocketListener)(socket, 'open', () => settle(resolve)), (0, socket_js_1.addSocketListener)(socket, 'error', (error) => settle(() => reject(new errors_js_1.ClusterTransportError('WebSocket failed to open', 'OPEN_FAILED', { cause: error })))), (0, socket_js_1.addSocketListener)(socket, 'close', () => settle(() => reject(new errors_js_1.ClusterTransportError('WebSocket closed before opening', 'OPEN_FAILED')))));
+        const onUnexpectedResponse = (...args) => {
+            const response = args.find((value) => value !== null && typeof value === 'object' && 'statusCode' in value);
+            const status = response?.statusCode;
+            upgradeFailure = typeof status === 'number'
+                ? new errors_js_1.ClusterUpgradeError(status)
+                : new errors_js_1.ClusterTransportError('WebSocket upgrade rejected', 'UPGRADE_REJECTED');
+            response?.resume?.();
+            if (socket.terminate) {
+                socket.terminate();
+            }
+            else {
+                settle(() => reject(upgradeFailure));
+            }
+        };
+        removers.push((0, socket_js_1.addSocketListener)(socket, 'open', () => settle(resolve)), (0, socket_js_1.addSocketListener)(socket, 'error', (error) => settle(() => reject(upgradeFailure ??
+            new errors_js_1.ClusterTransportError('WebSocket failed to open', 'OPEN_FAILED', { cause: error })))), (0, socket_js_1.addSocketListener)(socket, 'close', () => settle(() => reject(upgradeFailure ??
+            new errors_js_1.ClusterTransportError('WebSocket closed before opening', 'OPEN_FAILED')))), (0, socket_js_1.addSocketEmitterListener)(socket, 'unexpected-response', onUnexpectedResponse));
         signal?.addEventListener('abort', onAbort, { once: true });
     });
 }
+async function disposeFailedSocket(socket) {
+    if (socket.readyState === 0 && socket.terminate) {
+        socket.terminate();
+    }
+    else {
+        await socket.close();
+    }
+}
 async function connect(url, options = {}) {
     const factory = options.webSocketFactory ?? defaultWebSocketFactory;
     let socket;
@@ -141,7 +164,7 @@ async function connect(url, options = {}) {
     catch (error) {
         if (socket) {
             try {
-                await socket.close();
+                await disposeFailedSocket(socket);
             }
             catch { /* preserve the construction error */ }
         }
@@ -162,7 +185,7 @@ async function connectInitialized(url, options = {}) {
     catch (error) {
         if (socket) {
             try {
-                await socket.close();
+                await disposeFailedSocket(socket);
             }
             catch { /* preserve the construction error */ }
         }

package/lib/cluster/client.d.cts

@@ -0,0 +1,52 @@
+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 } from './generated/protocol.js';
+import { Connection } from './connection.js';
+import type { CallOptions } from './connection.js';
+import type { WebSocketLike } from './socket.js';
+import { AgentAttachSubscriptionStream, LogsSubscriptionStream } from './subscriptions.js';
+import type { WatchSubscription } from './subscriptions.js';
+export type { WatchSubscription } 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[], options?: WebSocketFactoryOptions) => WebSocketLike | Promise<WebSocketLike>;
+    readonly signal?: AbortSignal;
+    readonly initialize?: InitializeParams;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+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 declare class ClusterClient {
+    readonly connection: Connection;
+    constructor(connection: Connection);
+    initialize(params?: InitializeParams, options?: CallOptions): Promise<InitializeResult>;
+    plan(params: PlanParams, options?: CallOptions): Promise<PlanResult>;
+    apply(params: ApplyParams, options?: CallOptions): Promise<ApplyResult>;
+    update(params: UpdateParams, options?: CallOptions): Promise<UpdateResult>;
+    stop(params: StopParams, options?: CallOptions): Promise<StopResult>;
+    retry(params: RetryParams, options?: CallOptions): Promise<RetryResult>;
+    resubmit(params: ResubmitParams, options?: CallOptions): Promise<ResubmitResult>;
+    delete(params: DeleteParams, options?: CallOptions): Promise<DeleteResult>;
+    get(params?: GetParams, options?: CallOptions): Promise<GetResult>;
+    watch(params?: WatchParams, options?: CallOptions): Promise<WatchSubscription>;
+    watchColdStart(params?: Omit<WatchParams, 'fromCursor'>, options?: CallOptions): Promise<CoherentWatchSubscription>;
+    logs(params?: LogsParams, options?: CallOptions): Promise<LogsSubscription>;
+    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.d.mts

@@ -0,0 +1,52 @@
+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 } from './generated/protocol.js';
+import { Connection } from './connection.js';
+import type { CallOptions } from './connection.js';
+import type { WebSocketLike } from './socket.js';
+import { AgentAttachSubscriptionStream, LogsSubscriptionStream } from './subscriptions.js';
+import type { WatchSubscription } from './subscriptions.js';
+export type { WatchSubscription } 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[], options?: WebSocketFactoryOptions) => WebSocketLike | Promise<WebSocketLike>;
+    readonly signal?: AbortSignal;
+    readonly initialize?: InitializeParams;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+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 declare class ClusterClient {
+    readonly connection: Connection;
+    constructor(connection: Connection);
+    initialize(params?: InitializeParams, options?: CallOptions): Promise<InitializeResult>;
+    plan(params: PlanParams, options?: CallOptions): Promise<PlanResult>;
+    apply(params: ApplyParams, options?: CallOptions): Promise<ApplyResult>;
+    update(params: UpdateParams, options?: CallOptions): Promise<UpdateResult>;
+    stop(params: StopParams, options?: CallOptions): Promise<StopResult>;
+    retry(params: RetryParams, options?: CallOptions): Promise<RetryResult>;
+    resubmit(params: ResubmitParams, options?: CallOptions): Promise<ResubmitResult>;
+    delete(params: DeleteParams, options?: CallOptions): Promise<DeleteResult>;
+    get(params?: GetParams, options?: CallOptions): Promise<GetResult>;
+    watch(params?: WatchParams, options?: CallOptions): Promise<WatchSubscription>;
+    watchColdStart(params?: Omit<WatchParams, 'fromCursor'>, options?: CallOptions): Promise<CoherentWatchSubscription>;
+    logs(params?: LogsParams, options?: CallOptions): Promise<LogsSubscription>;
+    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.d.ts

@@ -1,8 +1,10 @@
-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 } 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 } from './generated/protocol.js';
 import { Connection } from './connection.js';
 import type { CallOptions } from './connection.js';
 import type { WebSocketLike } from './socket.js';
-import { AgentAttachSubscriptionStream, LogsSubscriptionStream, WatchSubscriptionStream } from './subscriptions.js';
+import { AgentAttachSubscriptionStream, LogsSubscriptionStream } from './subscriptions.js';
+import type { WatchSubscription } from './subscriptions.js';
+export type { WatchSubscription } from './subscriptions.js';
 export interface WebSocketFactoryOptions {
     readonly headers?: Readonly<Record<string, string>>;
 }
@@ -13,10 +15,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;

package/lib/cluster/client.mjs

@@ -1,7 +1,8 @@
+/// <reference path="./ws.d.ts" />
 import { PROTOCOL_VERSION } from './generated/protocol.mjs';
 import { Connection } from './connection.mjs';
-import { addSocketListener } from './socket.mjs';
-import { ClusterConfigError, ClusterProtocolError, ClusterTransportError } from './errors.mjs';
+import { addSocketEmitterListener, addSocketListener } from './socket.mjs';
+import { ClusterConfigError, ClusterProtocolError, ClusterTransportError, ClusterUpgradeError } from './errors.mjs';
 import { AgentAttachSubscriptionStream, LogsSubscriptionStream, WatchSubscriptionStream, } from './subscriptions.mjs';
 export class ClusterClient {
     connection;
@@ -76,10 +77,7 @@ export class ClusterClient {
 }
 async function defaultWebSocketFactory(url, protocols, options) {
     const globalWebSocket = globalThis.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 {
@@ -108,6 +106,7 @@ async function waitForOpen(socket, signal) {
     await new Promise((resolve, reject) => {
         let settled = false;
         const removers = [];
+        let upgradeFailure;
         const settle = (fn) => {
             if (settled)
                 return;
@@ -118,10 +117,34 @@ async function waitForOpen(socket, signal) {
             fn();
         };
         const onAbort = () => settle(() => reject(new DOMException('connect aborted locally; the server may still have committed this request', 'AbortError')));
-        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')))));
+        const onUnexpectedResponse = (...args) => {
+            const response = args.find((value) => value !== null && typeof value === 'object' && 'statusCode' in value);
+            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(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) {
+    if (socket.readyState === 0 && socket.terminate) {
+        socket.terminate();
+    }
+    else {
+        await socket.close();
+    }
+}
 export async function connect(url, options = {}) {
     const factory = options.webSocketFactory ?? defaultWebSocketFactory;
     let socket;
@@ -135,7 +158,7 @@ export async function connect(url, options = {}) {
     catch (error) {
         if (socket) {
             try {
-                await socket.close();
+                await disposeFailedSocket(socket);
             }
             catch { /* preserve the construction error */ }
         }
@@ -156,7 +179,7 @@ export async function connectInitialized(url, options = {}) {
     catch (error) {
         if (socket) {
             try {
-                await socket.close();
+                await disposeFailedSocket(socket);
             }
             catch { /* preserve the construction error */ }
         }

package/lib/cluster/connection-state.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_DIAGNOSTIC_CAPACITY = exports.CONNECTION_TRANSITIONS = void 0;
+exports.deferred = deferred;
+if (!Object.prototype.hasOwnProperty.call(Symbol, 'asyncDispose')) {
+    Object.defineProperty(Symbol, 'asyncDispose', {
+        configurable: false, enumerable: false,
+        value: Symbol.for('Symbol.asyncDispose'), writable: false,
+    });
+}
+exports.CONNECTION_TRANSITIONS = Object.freeze({
+    OPEN: Object.freeze(['CLOSING']),
+    CLOSING: Object.freeze(['CLOSED']),
+    CLOSED: Object.freeze([]),
+});
+exports.PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((onResolve, onReject) => {
+        resolve = onResolve;
+        reject = onReject;
+    });
+    return { promise, resolve, reject };
+}

package/lib/cluster/connection-state.d.cts

@@ -0,0 +1,13 @@
+export type ConnectionState = 'OPEN' | 'CLOSING' | 'CLOSED';
+export declare const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly ConnectionState[]>>;
+export declare 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 declare function deferred<T>(): Deferred<T>;