@anhlp/alp-client 0.0.0-beta.1

package/src/setup.js

@@ -0,0 +1,150 @@
+import { copyFile, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { initProject } from '@anhlp/alp-core/init';
+import { MODELS } from '@anhlp/alp-core/models';
+import { fitEffort, modelEfforts } from '@anhlp/alp-core/profiles';
+import { resolveTeam } from '@anhlp/alp-core/teams';
+import { validateSettings } from '@anhlp/alp-core/validation';
+import { Cancelled, select, text } from './prompt.js';
+
+const PROVIDERS = ['claude', 'codex'];
+const PROVIDER_LABEL = { claude: 'Claude', codex: 'Codex' };
+/** Each seat's model and effort per provider. Main runs on the preferred provider's only; peers may run on any model of an enabled provider. */
+const DEFAULTS = {
+  main: { claude: ['claude-opus-5-5', 'high'], codex: ['gpt-6.1-sol', 'high'] },
+  worker: { claude: ['claude-opus-5-5', 'high'], codex: ['gpt-6.1-sol', 'high'] },
+  supervisor: { claude: ['claude-sonnet-5', 'medium'], codex: ['gpt-6-luna', 'medium'] },
+  oracle: { claude: ['claude-fable-5-1', 'high'], codex: ['gpt-6-astra', 'high'] },
+};
+const FLAGS = { main: 'model', worker: 'model', supervisor: 'supervisor', oracle: 'oracle' };
+const SEAT_LABEL = { main: 'main', worker: 'lead, reviewer', supervisor: 'supervisor', oracle: 'oracle' };
+const ANY_EFFORT = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+/** Write Phở and Cafe's agent profiles into a project's .alp/settings.json, without installing software or calling models. */
+export async function setup(args, home) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: Object.fromEntries(
+    ['runtime', 'prefer', ...PROVIDERS.flatMap(provider => Object.values(FLAGS).map(flag => `${provider}-${flag}`))].map(name => [name, { type: 'string' }]),
+  ) });
+  if (positionals.length > 1) throw new Error('setup takes at most one directory');
+  const root = path.resolve(positionals[0] ?? process.cwd());
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  try {
+    const runtime = values.runtime ?? (interactive ? await select({ message: 'Runtime', initial: 'mix', choices: [
+      { label: 'Mix', value: 'mix', hint: 'Claude and Codex: main runs on one, the others can run on either' },
+      { label: 'Codex only', value: 'codex' },
+      { label: 'Claude only', value: 'claude' },
+    ] }) : undefined);
+    if (runtime === undefined) throw new Error('Pass --runtime codex, claude or mix when setup is not running in a terminal');
+    if (!['codex', 'claude', 'mix'].includes(runtime)) throw new Error('--runtime must be codex, claude or mix');
+    const prefer = values.prefer ?? (runtime !== 'mix' ? runtime : interactive ? await select({ message: 'Main runs on', initial: 'claude', choices: [
+      { label: 'Claude', value: 'claude', hint: 'Claude first for the others too' },
+      { label: 'Codex', value: 'codex', hint: 'Codex first for the others too' },
+    ] }) : 'claude');
+    if (!PROVIDERS.includes(prefer) || (runtime !== 'mix' && prefer !== runtime)) throw new Error('--prefer must be an enabled runtime');
+    // The preferred provider comes first: it is each agent's default, the other one a choice.
+    const enabled = runtime === 'mix' ? [prefer, ...PROVIDERS.filter(provider => provider !== prefer)] : [runtime];
+    for (const provider of PROVIDERS) {
+      for (const flag of Object.values(FLAGS)) {
+        if (!enabled.includes(provider) && values[`${provider}-${flag}`]) throw new Error(`--${provider}-${flag} is unavailable in ${runtime}-only mode`);
+      }
+    }
+    /** @type {Record<string, Array<{ provider: string, model: string, effort?: string }>>} */
+    const seats = {};
+    for (const [seat, flag] of Object.entries(FLAGS)) {
+      seats[seat] = (seat === 'main' ? [prefer] : enabled).map(provider => {
+        const option = `${provider}-${flag}`;
+        const [fallback, effort] = DEFAULTS[seat][provider];
+        const model = nativeModel(values[option] ?? fallback, provider, `--${option}`);
+        return { provider, model, effort: fitEffort(`${provider}:${model}`, effort) };
+      });
+    }
+    const peers = enabled.map(provider => `${provider}:*`);
+
+    const file = path.join(root, '.alp/settings.json');
+    const settings = await readFile(file, 'utf8').then(content => {
+      try { return JSON.parse(content); } catch (error) { throw new Error(`${file} is not valid JSON: ${error.message}`); }
+    }, error => {
+      if (error.code === 'ENOENT') return undefined;
+      throw new Error(`${file}: ${error.message}`);
+    });
+    const show = () => {
+      for (const [seat, choices] of Object.entries(seats)) console.log(`  ${SEAT_LABEL[seat]}: ${choices.map(describe).join(', ')}`);
+      console.log(`  peer: ${peers.join(', ')} (any model: whoever assigns a peer picks its model and effort for the task)`);
+    };
+    console.log(`Profiles for Phở and Cafe in ${file}:`);
+    show();
+    const replaced = ['pho', 'cafe'].filter(id => (settings?.team ?? settings?.profile)?.[id]);
+    if (replaced.length) console.log(`These replace the ${replaced.join(' and ')} profiles already in the file; a backup is kept in ${file}.bak.`);
+    if (interactive) {
+      for (;;) {
+        const next = await select({ message: 'Save these profiles?', initial: 'save', choices: [
+          { label: 'Save', value: 'save' },
+          { label: 'Change a model', value: 'change' },
+          { label: 'Cancel', value: 'cancel' },
+        ] });
+        if (next === 'cancel') throw new Cancelled();
+        if (next === 'save') break;
+        await change(seats);
+        show();
+      }
+    }
+    const profile = await profiles(root, home, seats, peers, settings);
+    validateSettings({ ...(settings ?? {}), team: { ...(settings?.profile ?? {}), ...(settings?.team ?? {}), ...profile } }, file);
+    if (!settings) await initProject(root, { library: home });
+    else if (replaced.length) await copyFile(file, `${file}.bak`);
+    const written = settings ?? JSON.parse(await readFile(file, 'utf8'));
+    const next = { ...written, team: { ...(written.profile ?? {}), ...(written.team ?? {}), ...profile } };
+    delete next.profile;
+    await writeFile(file, JSON.stringify(next, null, 2) + '\n');
+    console.log('Setup saved. New sessions in this project use these profiles; edit the file to change one agent. Run alp doctor to check that each CLI is installed and logged in.');
+  } catch (error) {
+    if (!(error instanceof Cancelled)) throw error;
+    console.log(error.message);
+  }
+}
+
+const describe = choice => `${choice.provider}:${choice.model}${choice.effort ? `:${choice.effort}` : ''}`;
+
+/** Pick one seat and provider, then its model and effort. */
+async function change(seats) {
+  const [seat, at] = await select({ message: 'Which model?', choices: Object.entries(seats).flatMap(([seat, choices]) =>
+    choices.map((choice, at) => ({ label: `${SEAT_LABEL[seat]} · ${PROVIDER_LABEL[choice.provider]}`, value: [seat, at], hint: describe(choice) }))) });
+  const current = seats[seat][at];
+  const offered = MODELS.filter(model => model.runtime === current.provider);
+  const picked = await select({ message: `${SEAT_LABEL[seat]} on ${PROVIDER_LABEL[current.provider]}`, initial: current.model, choices: [
+    ...offered.map(model => ({ label: model.label, value: model.id, hint: `${model.id} · ${model.description}` })),
+    { label: 'Other…', value: undefined, hint: 'type a model ID' },
+  ] });
+  const model = picked ?? nativeModel(await text(`${PROVIDER_LABEL[current.provider]} model ID:`), current.provider, 'The model ID');
+  const efforts = modelEfforts(`${current.provider}:${model}`) ?? ANY_EFFORT;
+  const effort = efforts.length > 1 ? await select({ message: 'Effort', initial: efforts.includes(current.effort) ? current.effort : DEFAULTS[seat][current.provider][1],
+    choices: efforts.map(effort => ({ label: effort, value: effort })) }) : efforts[0];
+  seats[seat][at] = { provider: current.provider, model, ...(effort ? { effort } : {}) };
+}
+
+/** Every Phở and Cafe agent's profiles, keeping each agent's own compaction setting. */
+async function profiles(root, home, seats, peers, settings) {
+  const profile = {};
+  for (const id of ['pho', 'cafe']) {
+    const team = await resolveTeam(root, id, { library: home });
+    const agents = {};
+    const seat = (name, choices) => {
+      agents[name] = { profiles: choices.map(choice => typeof choice === 'string' ? choice : describe(choice)), autocompact: (settings?.team ?? settings?.profile)?.[id]?.[name]?.autocompact ?? 'auto' };
+    };
+    for (const [name, member] of Object.entries(team.members)) {
+      if (name !== 'oracle') seat(name, name === team.main ? seats.main : member.role === 'peer' ? peers : seats.worker);
+    }
+    if (team.supervisor) seat(team.supervisor.agent, seats.supervisor);
+    if (team.members.oracle) seat('oracle', seats.oracle);
+    profile[id] = agents;
+  }
+  return profile;
+}
+
+/** A model for one provider: a native ID, or one prefixed with that provider. */
+function nativeModel(id, provider, where) {
+  const model = id.startsWith(`${provider}:`) ? id.slice(provider.length + 1) : id;
+  if (!model || /\s/.test(model) || /^(codex|claude):/.test(model) || (model.includes(':') && !id.startsWith(`${provider}:`))) throw new Error(`${where} expects a ${provider} model, got '${id}'`);
+  return model;
+}

package/src/supervise.d.ts

@@ -0,0 +1,12 @@
+export function holdDaemon(home: string, by?: string): Promise<void>;
+export function releaseHold(home: string): Promise<void>;
+export function daemonHeld(home: string): Promise<boolean>;
+export function startDaemon(options: { home: string; entry?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<string>;
+export function superviseDaemon(options: {
+  home: string;
+  entry?: string | (() => string | undefined);
+  env?: NodeJS.ProcessEnv;
+  intervalMs?: number;
+  misses?: number;
+  log?: (message: string) => void;
+}): (() => Promise<void>) & { started: Promise<void> };

package/src/supervise.js

@@ -0,0 +1,85 @@
+import { mkdir, unlink, writeFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDaemon, lockAlive, readLock } from './index.js';
+import { installedProgram, serviceFor, startService } from './service.js';
+
+/**
+ * Keeping alpd up (ALPD §40). Whoever starts alpd goes through its login service when
+ * one is installed, so the service keeps managing it; otherwise alpd starts detached.
+ * A deliberate `alp daemon stop` leaves a hold, which watchers respect: they start
+ * alpd again only when someone asks for it.
+ */
+
+const holdFile = home => path.join(home, 'state', 'alpd.held');
+
+/** Records that the user stopped alpd on purpose. */
+export async function holdDaemon(home, by = 'alp daemon stop') {
+  await mkdir(path.dirname(holdFile(home)), { recursive: true, mode: 0o700 });
+  await writeFile(holdFile(home), JSON.stringify({ by, at: new Date().toISOString() }) + '\n', { mode: 0o600 });
+}
+
+export async function releaseHold(home) {
+  await unlink(holdFile(home)).catch(() => {});
+}
+
+export async function daemonHeld(home) {
+  return stat(holdFile(home)).then(() => true, () => false);
+}
+
+/** Polls until an alpd for `home` is ready; returns its socket. */
+async function whenReady(home, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const lock = await readLock(home);
+    if (lockAlive(lock) && lock.ready) return lock.socket;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`alpd did not become ready within ${timeoutMs / 1000} s; see ${path.join(home, 'logs')}`);
+}
+
+/**
+ * Starts alpd for `home` unless it runs, and lifts a hold: someone asked for it.
+ * Returns its socket.
+ */
+export async function startDaemon({ home, entry, env = process.env, timeoutMs = 15_000 }) {
+  await releaseHold(home);
+  const lock = await readLock(home);
+  if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
+  const service = serviceFor({ home, env });
+  if (service && await installedProgram(service)) {
+    await startService(service);
+    return whenReady(home, timeoutMs);
+  }
+  return ensureDaemon({ home, entry, env, timeoutMs });
+}
+
+/**
+ * Starts alpd now and starts it again whenever it is found down on `misses` checks in a
+ * row, `intervalMs` apart, unless the user holds it. Two misses let `alp daemon restart`
+ * and `install` finish their own stop and start first. Returns a function that stops
+ * watching, and resolves once a start it began has settled; alpd keeps running.
+ */
+export function superviseDaemon({ home, entry, env = process.env, intervalMs = 5_000, misses = 2, log = () => {} }) {
+  let stopped = false;
+  let missed = 0;
+  let starting;
+  const start = reason => {
+    starting ??= startDaemon({ home, entry: typeof entry === 'function' ? entry() : entry, env })
+      .then(() => log(`alpd ${reason}`), error => log(`could not start alpd: ${error?.message ?? error}`))
+      .finally(() => { starting = undefined; missed = 0; });
+    return starting;
+  };
+  const check = async () => {
+    if (stopped || starting) return;
+    if (lockAlive(await readLock(home))) { missed = 0; return; }
+    if (await daemonHeld(home)) { missed = 0; return; }
+    // Stopped while this check looked: start nothing.
+    if (++missed >= misses && !stopped) await start('was down; started it again');
+  };
+  const initial = start('started with Paseo');
+  const timer = setInterval(() => { void check(); }, intervalMs);
+  timer.unref?.();
+  const stop = () => { stopped = true; clearInterval(timer); return starting ?? Promise.resolve(); };
+  stop.started = initial;
+  return stop;
+}

package/src/websocket.js

@@ -0,0 +1,259 @@
+import { MAX_FRAME } from '@anhlp/alp-protocol';
+import { AlpClientError } from './rpc/errors.js';
+import { utf8Length } from './rpc/framing.js';
+import { timerDelay } from './rpc/timers.js';
+
+/**
+ * A WebSocket transport for the portable ALP client: the browser's WebSocket, React Native's, or
+ * any implementation the caller injects (`ws` in Node, a test double). One JSON-RPC message per
+ * text message; a message holding several newline-separated messages is accepted too. Binary
+ * messages are refused: the socket is closed with 4003, a message over `maxFrame` with 4009
+ * (application codes, since browsers refuse to send 1003 and 1009 themselves).
+ *
+ * How the connection is authenticated is the caller's business and is not designed here (Task 08):
+ * `url` and `protocols` are passed through untouched, and `createSocket` builds the socket however
+ * the deployment needs (for example Node `ws` with headers). Browsers cannot set arbitrary request
+ * headers on a WebSocket, so nothing here relies on them.
+ */
+
+/**
+ * @typedef {import('./rpc/client.js').AlpTransport} AlpTransport
+ * @typedef {import('./rpc/client.js').TransportClose} TransportClose
+ * @typedef {import('./rpc/client.js').AbortSignalLike} AbortSignalLike
+ * @typedef {{
+ *   readonly readyState: number,
+ *   readonly bufferedAmount?: number,
+ *   binaryType?: string,
+ *   send(data: string): void,
+ *   close(code?: number, reason?: string): void,
+ *   addEventListener?(type: string, listener: (event: any) => void): void,
+ *   removeEventListener?(type: string, listener: (event: any) => void): void,
+ *   onopen?: ((event: any) => void) | null,
+ *   onmessage?: ((event: any) => void) | null,
+ *   onerror?: ((event: any) => void) | null,
+ *   onclose?: ((event: any) => void) | null,
+ * }} WebSocketLike
+ * @typedef {new (url: string, protocols?: string | string[]) => WebSocketLike} WebSocketConstructor
+ * @typedef {{ maxFrame?: number, maxBufferedBytes?: number }} WebSocketTransportOptions
+ * @typedef {WebSocketTransportOptions & {
+ *   WebSocket?: WebSocketConstructor,
+ *   protocols?: string | string[],
+ *   createSocket?: (url: string, protocols?: string | string[]) => WebSocketLike,
+ *   signal?: AbortSignalLike,
+ *   timeoutMs?: number,
+ * }} ConnectWebSocketOptions
+ */
+
+const CONNECTING = 0;
+const OPEN = 1;
+
+/** Close codes this transport sends when the peer breaks the protocol. */
+export const CLOSE_CODE = Object.freeze({ unsupportedData: 4003, tooLarge: 4009 });
+/** How long an error waits for the close event that carries its code before ending the transport. */
+const CLOSE_AFTER_ERROR_MS = 250;
+/** A close reason may hold 123 UTF-8 bytes. */
+const MAX_CLOSE_REASON = 123;
+
+/** A URL fit for an error message: no credentials, query or fragment, which may carry a token. @param {string} url */
+export function redactUrl(url) {
+  // The userinfo runs to the last '@' before the path, so a password holding '@' goes with it.
+  const match = /^([a-z][a-z0-9+.-]*:\/\/)(?:[^/?#\\]*@)?([^/?#\\@]*)([^?#]*)/i.exec(String(url));
+  return match ? `${match[1]}${match[2]}${match[3]}` : '<websocket>';
+}
+
+/**
+ * An error safe to show or log: the original's name and message with every URL redacted, and none
+ * of its other properties (an implementation may keep the URL in `input`, `target` or `cause`).
+ * @param {unknown} error @param {string} url
+ */
+function scrubbed(error, url) {
+  const text = error instanceof Error ? error.message : String(error ?? '');
+  const message = (text.split(String(url)).join(redactUrl(url)) || 'WebSocket error')
+    .replace(/[a-z][a-z0-9+.-]*:\/\/[^\s'"<>]+/gi, found => redactUrl(found));
+  const clean = new Error(message);
+  if (error instanceof Error && error.name) clean.name = error.name;
+  return clean;
+}
+
+/** `reason` cut to what a close frame may carry. @param {string} reason */
+function closeReason(reason) {
+  let cut = reason;
+  while (utf8Length(cut) > MAX_CLOSE_REASON) cut = cut.slice(0, -1);
+  return cut;
+}
+
+/**
+ * Closes a socket that is not closed yet, with `code` where the implementation accepts it and
+ * plainly where it does not, so the socket is always released.
+ * @param {WebSocketLike} socket @param {number} [code] @param {string} [reason]
+ */
+function release(socket, code, reason) {
+  if (socket.readyState !== CONNECTING && socket.readyState !== OPEN) return;
+  try { if (code === undefined) socket.close(); else socket.close(code, closeReason(reason ?? '')); return; } catch {}
+  try { socket.close(); } catch {}
+}
+
+/**
+ * Keeps an 'error' listener on the socket for good: Node's `ws` throws an 'error' event that
+ * nobody listens to as an uncaught exception, and one can follow a close or an abandoned connect.
+ * @param {WebSocketLike} socket
+ */
+function absorbErrors(socket) {
+  if (typeof socket.addEventListener === 'function') socket.addEventListener('error', () => {});
+}
+
+/** Subscribes with addEventListener where the socket has it, else through its on<type> property. @param {WebSocketLike} socket @param {string} type @param {(event: any) => void} listener */
+function listen(socket, type, listener) {
+  if (typeof socket.addEventListener === 'function') {
+    socket.addEventListener(type, listener);
+    return () => socket.removeEventListener?.(type, listener);
+  }
+  const key = /** @type {'onopen' | 'onmessage' | 'onerror' | 'onclose'} */ (`on${type}`);
+  const previous = socket[key];
+  socket[key] = event => { previous?.(event); listener(event); };
+  return () => { socket[key] = previous ?? null; };
+}
+
+/** The error an error event carries, never with an empty message. @param {any} event */
+const errorOf = event => {
+  const message = (event?.error instanceof Error && event.error.message) || (typeof event?.message === 'string' && event.message) || 'WebSocket error';
+  return event?.error instanceof Error && event.error.message ? event.error : new Error(message);
+};
+
+/**
+ * Wraps an open WebSocket in an ALP transport. The transport owns the socket from then on.
+ * @param {WebSocketLike} socket
+ * @param {WebSocketTransportOptions} [options]
+ * @returns {AlpTransport}
+ */
+export function createWebSocketTransport(socket, { maxFrame = MAX_FRAME, maxBufferedBytes = 4 * MAX_FRAME } = {}) {
+  if (socket.readyState !== OPEN) throw new AlpClientError('WebSocket is not open', { reason: 'disconnected' });
+  absorbErrors(socket);
+  try { socket.binaryType = 'arraybuffer'; } catch {}
+  /** @type {Set<(frame: string) => void>} */
+  const messages = new Set();
+  /** @type {Set<(close: TransportClose) => void>} */
+  const closes = new Set();
+  /** @type {TransportClose | undefined} */
+  let ended;
+  /** @type {Array<() => void>} */
+  const detach = [];
+  /** An error event waiting for the close event that follows it. @type {Error | undefined} */
+  let failed;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let failTimer;
+  /** @param {TransportClose} close */
+  const end = close => {
+    if (ended) return;
+    ended = close;
+    if (failTimer !== undefined) clearTimeout(failTimer);
+    for (const remove of detach.splice(0)) remove();
+    messages.clear();
+    const listeners = [...closes];
+    closes.clear();
+    for (const listener of listeners) listener(close);
+  };
+  /** @param {string} message @param {number} code */
+  const violate = (message, code) => {
+    const error = new AlpClientError(message, { reason: 'protocol' });
+    release(socket, code, message);
+    end({ error });
+  };
+  detach.push(listen(socket, 'message', event => {
+    if (ended) return;
+    const data = event?.data;
+    if (typeof data !== 'string') return violate('Binary WebSocket messages are not ALP frames', CLOSE_CODE.unsupportedData);
+    if (utf8Length(data) > maxFrame) return violate(`ALP frame exceeds ${maxFrame} bytes`, CLOSE_CODE.tooLarge);
+    for (const line of data.includes('\n') ? data.split('\n') : [data]) {
+      if (ended) return;
+      if (line.trim()) for (const listener of [...messages]) listener(line);
+    }
+  }));
+  detach.push(listen(socket, 'close', event => end({ error: failed, code: typeof event?.code === 'number' ? event.code : undefined, reason: typeof event?.reason === 'string' && event.reason ? event.reason : undefined })));
+  // An error comes before its close event, which carries the code (1006 for a dropped
+  // connection); the transport ends with both. Not every implementation sends the close, so it
+  // ends without it shortly after.
+  detach.push(listen(socket, 'error', event => {
+    if (failed) return;
+    failed = errorOf(event);
+    failTimer = setTimeout(() => end({ error: failed }), CLOSE_AFTER_ERROR_MS);
+    release(socket);
+  }));
+  return {
+    get state() { return ended || socket.readyState !== OPEN ? 'closed' : 'open'; },
+    send(frame) {
+      if (ended || socket.readyState !== OPEN) throw new AlpClientError('WebSocket is not open', { reason: 'send_failed' });
+      if ((socket.bufferedAmount ?? 0) + utf8Length(frame) > maxBufferedBytes) throw new AlpClientError(`WebSocket send buffer is over ${maxBufferedBytes} bytes`, { reason: 'send_failed' });
+      socket.send(frame);
+    },
+    onMessage(listener) {
+      if (ended) return () => false;
+      messages.add(listener);
+      return () => messages.delete(listener);
+    },
+    onClose(listener) {
+      if (ended) return () => false;
+      closes.add(listener);
+      return () => closes.delete(listener);
+    },
+    close() {
+      release(socket, 1000, 'client closed');
+      end({ code: 1000, reason: 'client closed' });
+    },
+  };
+}
+
+/**
+ * Opens a WebSocket to `url` and resolves with its transport once it is open. The socket comes
+ * from `createSocket`, else `new WebSocket(url, protocols)` with the injected or global WebSocket.
+ * Errors name the URL without its credentials, query or fragment.
+ * @param {string} url
+ * @param {ConnectWebSocketOptions} [options]
+ * @returns {Promise<AlpTransport>}
+ */
+export function connectWebSocket(url, { WebSocket: Implementation, protocols, createSocket, signal, timeoutMs = 15_000, ...options } = {}) {
+  const where = redactUrl(url);
+  /** @type {number | undefined} */
+  let delay;
+  try { delay = timerDelay(timeoutMs); } catch (error) { return Promise.reject(error); }
+  if (signal?.aborted) return Promise.reject(new AlpClientError(`Connecting to ${where} was aborted`, { reason: 'aborted', cause: signal.reason }));
+  const Constructor = Implementation ?? /** @type {any} */ (globalThis).WebSocket;
+  if (!createSocket && typeof Constructor !== 'function') return Promise.reject(new TypeError('No WebSocket implementation: pass options.WebSocket or options.createSocket'));
+  /** @type {WebSocketLike} */
+  let socket;
+  try {
+    socket = createSocket ? createSocket(url, protocols) : protocols === undefined ? new Constructor(url) : new Constructor(url, protocols);
+  } catch (error) {
+    // The raw error may hold the whole URL (a TypeError's `input`, for one); only a scrubbed copy goes on.
+    return Promise.reject(new AlpClientError(`Could not connect to ${where}`, { reason: 'disconnected', cause: scrubbed(error, url) }));
+  }
+  absorbErrors(socket);
+  return new Promise((resolve, reject) => {
+    /** @type {Array<() => void>} */
+    const detach = [];
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timer;
+    const settle = () => {
+      for (const remove of detach.splice(0)) remove();
+      if (timer !== undefined) clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    };
+    /** @param {AlpClientError} error */
+    const fail = error => {
+      settle();
+      release(socket);
+      reject(error);
+    };
+    const onAbort = () => fail(new AlpClientError(`Connecting to ${where} was aborted`, { reason: 'aborted', cause: signal?.reason }));
+    const open = () => {
+      settle();
+      try { resolve(createWebSocketTransport(socket, options)); } catch (error) { reject(error); }
+    };
+    if (socket.readyState === OPEN) return open();
+    detach.push(listen(socket, 'open', open));
+    detach.push(listen(socket, 'error', event => fail(new AlpClientError(`Could not connect to ${where}`, { reason: 'disconnected', cause: scrubbed(errorOf(event), url) }))));
+    detach.push(listen(socket, 'close', event => fail(new AlpClientError(`Could not connect to ${where}`, { reason: 'disconnected', data: { code: event?.code, reason: event?.reason || undefined } }))));
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (delay !== undefined) timer = setTimeout(() => fail(new AlpClientError(`Connecting to ${where} timed out after ${timeoutMs} ms`, { reason: 'timeout' })), delay);
+  });
+}