@anhlp/alp-client 0.0.0-beta.1

package/src/mcp-probe.js

@@ -0,0 +1,118 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { launchCommand } from '@anhlp/alp-core/providers';
+
+const PROTOCOL = '2025-06-18';
+const client = { name: 'alp', version: '1' };
+
+/**
+ * Starts an MCP server once and lists its tools (ALPD §43), for the Test button and
+ * `alp mcp test`. `server` is a normalized definition: { command, args, env, cwd } for
+ * stdio, or { url, headers } for HTTP. The server is stopped afterwards.
+ * @returns {Promise<{ server?: { name?: string, version?: string }, tools: Array<{ name: string, description?: string }> }>}
+ */
+export async function probeMcp(server, { cwd, timeoutMs = 15_000 } = {}) {
+  const session = server.url ? await httpSession(server, timeoutMs) : stdioSession(server, cwd, timeoutMs);
+  try {
+    const init = await session.request('initialize', { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: client });
+    await session.notify('notifications/initialized');
+    const tools = [];
+    let cursor;
+    for (let page = 0; page < 20; page++) {
+      const result = await session.request('tools/list', cursor ? { cursor } : {});
+      for (const tool of result.tools ?? []) tools.push({ name: tool.name, ...(tool.description ? { description: tool.description } : {}) });
+      cursor = result.nextCursor;
+      if (!cursor) break;
+    }
+    return { ...(init.serverInfo ? { server: { name: init.serverInfo.name, version: init.serverInfo.version } } : {}), tools };
+  } finally {
+    await session.close();
+  }
+}
+
+/** A JSON-RPC session with a process over stdio; ACP providers are probed with it too. */
+export function stdioSession(server, cwd, timeoutMs) {
+  // Its own process group, so a launcher such as npx is stopped with what it started.
+  const env = { ...process.env, ...(server.env ?? {}) };
+  const launch = launchCommand(server.command, server.args ?? [], env);
+  const child = spawn(launch.command, launch.args, { cwd: server.cwd ?? cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+  const signal = name => { try { process.kill(-child.pid, name); } catch { child.kill(name); } };
+  let stderr = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', chunk => { if (stderr.length < 4000) stderr += chunk; });
+  const pending = new Map();
+  let exited;
+  const failAll = error => { for (const { reject } of pending.values()) reject(error); pending.clear(); };
+  child.on('error', error => { exited = error; failAll(error); });
+  child.on('exit', code => {
+    exited = new Error(`${server.command} exited (${code ?? 'signal'})${stderr.trim() ? `: ${stderr.trim().split('\n').slice(-3).join(' ')}` : ''}`);
+    failAll(exited);
+  });
+  createInterface({ input: child.stdout }).on('line', line => {
+    let message;
+    try { message = JSON.parse(line); } catch { return; }
+    const waiting = pending.get(message.id);
+    if (!waiting) return;
+    pending.delete(message.id);
+    if (message.error) waiting.reject(new Error(`${message.error.message ?? 'MCP error'} (${message.error.code})`));
+    else waiting.resolve(message.result ?? {});
+  });
+  child.stdin.on('error', () => {});
+  let id = 0;
+  return {
+    request(method, params) {
+      if (exited) return Promise.reject(exited);
+      const current = ++id;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(current); reject(new Error(`${method} got no answer within ${timeoutMs / 1000} s`)); }, timeoutMs);
+        pending.set(current, { resolve: value => { clearTimeout(timer); resolve(value); }, reject: error => { clearTimeout(timer); reject(error); } });
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: current, method, params }) + '\n');
+      });
+    },
+    async notify(method) { if (!exited) child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method }) + '\n'); },
+    async close() {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      const done = new Promise(resolve => child.once('exit', resolve));
+      child.stdin.end();
+      signal('SIGTERM');
+      const timer = setTimeout(() => signal('SIGKILL'), 2000);
+      await done;
+      clearTimeout(timer);
+    },
+  };
+}
+
+async function httpSession(server, timeoutMs) {
+  let sessionId;
+  let id = 0;
+  const post = async body => {
+    const response = await fetch(server.url, {
+      method: 'POST',
+      headers: { ...(server.headers ?? {}), 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...(sessionId ? { 'mcp-session-id': sessionId } : {}), 'mcp-protocol-version': PROTOCOL },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    sessionId = response.headers.get('mcp-session-id') ?? sessionId;
+    if (!response.ok) throw new Error(`${server.url} answered ${response.status} ${response.statusText}`);
+    return response;
+  };
+  return {
+    async request(method, params) {
+      const current = ++id;
+      const response = await post({ jsonrpc: '2.0', id: current, method, params });
+      const text = await response.text();
+      // A streamable HTTP server answers with JSON or with server-sent events.
+      const messages = (response.headers.get('content-type') ?? '').includes('text/event-stream')
+        ? text.split('\n').filter(line => line.startsWith('data:')).map(line => { try { return JSON.parse(line.slice(5)); } catch { return undefined; } })
+        : [JSON.parse(text)];
+      const message = messages.find(entry => entry?.id === current);
+      if (!message) throw new Error(`${method}: no answer in the response`);
+      if (message.error) throw new Error(`${message.error.message ?? 'MCP error'} (${message.error.code})`);
+      return message.result ?? {};
+    },
+    async notify(method) { await post({ jsonrpc: '2.0', method }); },
+    async close() {
+      if (sessionId) await fetch(server.url, { method: 'DELETE', headers: { ...(server.headers ?? {}), 'mcp-session-id': sessionId }, signal: AbortSignal.timeout(timeoutMs) }).catch(() => {});
+    },
+  };
+}

package/src/portable.js

@@ -0,0 +1,27 @@
+/**
+ * The portable ALP client (docs/alp/client-sdk.md): the JSON-RPC engine, its errors, the reconnect
+ * helper and NDJSON framing. It runs in Node, browsers and React Native without polyfills: no Node
+ * built-ins, no process, no Buffer, no filesystem and no ALP core. Transports come separately:
+ * `@anhlp/alp-client/websocket` here, the Unix socket and named pipe in the Node entry.
+ */
+
+/**
+ * @typedef {import('./rpc/client.js').AlpTransport} AlpTransport
+ * @typedef {import('./rpc/client.js').TransportClose} TransportClose
+ * @typedef {import('./rpc/client.js').TransportState} TransportState
+ * @typedef {import('./rpc/client.js').AbortSignalLike} AbortSignalLike
+ * @typedef {import('./rpc/client.js').RequestOptions} RequestOptions
+ * @typedef {import('./rpc/client.js').AlpRpcClientOptions} AlpRpcClientOptions
+ * @typedef {import('./rpc/handshake.js').ClientInfo} ClientInfo
+ * @typedef {import('./rpc/reconnect.js').ReconnectOptions} ReconnectOptions
+ * @typedef {import('./rpc/reconnect.js').ReconnectingClient} ReconnectingClient
+ * @typedef {import('./rpc/reconnect.js').ReconnectState} ReconnectState
+ * @typedef {import('./rpc/reconnect.js').Backoff} Backoff
+ */
+export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, ERROR } from '@anhlp/alp-protocol';
+export { AlpRpcClient, DEFAULT_MAX_PENDING } from './rpc/client.js';
+export { AlpClientError, CLIENT_ERROR, isAlpClientError } from './rpc/errors.js';
+export { createLineDecoder, utf8Length } from './rpc/framing.js';
+export { MAX_TIMER_MS, timerDelay } from './rpc/timers.js';
+export { hello } from './rpc/handshake.js';
+export { backoffDelay, createReconnectingClient, retryable } from './rpc/reconnect.js';

package/src/prompt.js

@@ -0,0 +1,64 @@
+import { emitKeypressEvents } from 'node:readline';
+
+const dim = text => `\x1b[2m${text}\x1b[22m`;
+const cyan = text => `\x1b[36m${text}\x1b[39m`;
+
+export class Cancelled extends Error {
+  constructor() { super('Setup cancelled.'); }
+}
+
+/**
+ * A select box in the terminal: ↑/↓ (or k/j) move, Enter picks, Ctrl-C or Esc cancels.
+ * Choices are { label, value, hint? }; `initial` is the value highlighted first.
+ * @template T
+ * @param {{ message: string, choices: Array<{ label: string, value: T, hint?: string }>, initial?: T }} question
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream }} [io]
+ * @returns {Promise<T>}
+ */
+export function select({ message, choices, initial }, { input = process.stdin, output = process.stdout } = {}) {
+  let index = Math.max(0, choices.findIndex(choice => choice.value === initial));
+  let drawn = 0;
+  const draw = () => {
+    if (drawn) output.write(`\x1b[${drawn}A\x1b[0J`);
+    const lines = [`${cyan('?')} ${message} ${dim('(↑/↓, Enter)')}`, ...choices.map((choice, at) =>
+      at === index ? cyan(`❯ ${choice.label}`) + (choice.hint ? ` ${dim(choice.hint)}` : '') : `  ${choice.label}${choice.hint ? ` ${dim(choice.hint)}` : ''}`)];
+    output.write(lines.join('\n') + '\n');
+    drawn = lines.length;
+  };
+  return new Promise((resolve, reject) => {
+    emitKeypressEvents(input);
+    const raw = input.isRaw;
+    input.setRawMode?.(true);
+    input.resume();
+    output.write('\x1b[?25l');
+    const done = (settle, value) => {
+      input.off('keypress', onKey);
+      input.setRawMode?.(raw ?? false);
+      input.pause();
+      output.write(`\x1b[${drawn}A\x1b[0J\x1b[?25h`);
+      if (settle === resolve) output.write(`${cyan('✔')} ${message} ${cyan(choices[index].label)}\n`);
+      settle(value);
+    };
+    const onKey = (text, key = {}) => {
+      if ((key.ctrl && key.name === 'c') || key.name === 'escape') return done(reject, new Cancelled());
+      if (key.name === 'return' || key.name === 'enter') return done(resolve, choices[index].value);
+      if (key.name === 'up' || key.name === 'k') index = (index + choices.length - 1) % choices.length;
+      else if (key.name === 'down' || key.name === 'j') index = (index + 1) % choices.length;
+      else return;
+      draw();
+    };
+    input.on('keypress', onKey);
+    draw();
+  });
+}
+
+/**
+ * A line of text, for a value the list does not offer.
+ * @param {string} message
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream }} [io]
+ */
+export async function text(message, { input = process.stdin, output = process.stdout } = {}) {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input, output });
+  try { return (await rl.question(`${cyan('?')} ${message} `)).trim(); } finally { rl.close(); }
+}

package/src/render.js

@@ -0,0 +1,136 @@
+/**
+ * Text the CLI prints for sessions and run logs, kept apart from the commands so
+ * golden tests can render fixtures without an alpd (ALPD §39).
+ */
+
+const TASK_PAST = { create: 'created', update: 'updated', link: 'linked', start: 'started', close: 'closed', reopen: 'reopened', delegate: 'delegated', submit: 'submitted', release: 'released', gate: 'gated', clear: 'cleared a gate of', orphaned: 'reopened (its assignment ended with alpd)' };
+
+/** How long ago `since` was, as 42s, 3m05s or 2h10m. */
+export const ago = (since, now = Date.now()) => {
+  const seconds = Math.max(0, Math.round((now - Date.parse(since)) / 1000));
+  return seconds < 60 ? `${seconds}s` : seconds < 3600 ? `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s` : `${Math.floor(seconds / 3600)}h${String(Math.floor(seconds % 3600 / 60)).padStart(2, '0')}m`;
+};
+/** A duration in the same form. */
+export const duration = ms => ago(new Date(0).toISOString(), ms);
+/** A token count as people say it: 164k, 1M. */
+const tokens = count => typeof count !== 'number' ? '?' : count >= 1_000_000 && count % 1_000_000 < 50_000 ? `${Math.round(count / 1_000_000)}M` : `${Math.round(count / 1000)}k`;
+
+/** `alp ps`: sessions as a tree, one line each. */
+export function renderPs(sessions) {
+  const lines = [];
+  const children = new Map();
+  for (const session of sessions) {
+    const key = session.parentId ?? '';
+    children.set(key, [...(children.get(key) ?? []), session]);
+  }
+  const print = (session, depth) => {
+    const status = session.parked ? `parked (${session.parked})` : session.status === 'running' || session.status === 'idle' ? (session.activeTurnId ? 'running' : session.busy ? 'waiting' : 'idle') : session.lastError?.code ?? session.status;
+    lines.push(`${'  '.repeat(depth)}${session.id}  ${session.agent}  ${session.runtime}:${session.model}  ${session.mode}  ${status}${depth ? '' : `  ${session.projectRoot}${session.title ? `  "${session.title}"` : ''}`}`);
+    for (const child of children.get(session.id) ?? []) print(child, depth + 1);
+  };
+  for (const root of children.get('') ?? []) print(root, 0);
+  return lines;
+}
+
+/** `alp log`: one line per run-log entry, with its time. */
+export function renderLog(rootId, entries) {
+  const lines = [];
+  const agents = new Map();
+  for (const entry of entries) {
+    const time = entry.ts.slice(11, 19);
+    let text;
+    switch (entry.event) {
+      case 'assignment.started':
+        agents.set(entry.assignmentId, entry.agent);
+        text = `${entry.parentAgent} → ${entry.agent} (${entry.mode}${entry.isolation === 'worktree' ? ', worktree' : ''}, ${entry.model}${entry.wait === false ? ', async' : ''}): ${entry.task.split('\n')[0].slice(0, 120)}`;
+        break;
+      case 'assignment.finished':
+        text = `${entry.agent} ${entry.status} after ${duration(entry.durationMs ?? 0)}${entry.handoff ? `, handoff ${entry.handoff.outcome}${entry.handoff.verdict ? `, verdict ${entry.handoff.verdict.result.toUpperCase()}` : ''}: ${entry.handoff.summary.split('\n')[0].slice(0, 120)}` : ''}${entry.error ? `: ${entry.error}` : ''}${entry.reconciled ? ' (after a restart)' : ''}`;
+        break;
+      case 'mail':
+        // Board pins are logged once, as board.pin, not per reader.
+        if (entry.kind === 'board') continue;
+        text = `✉ ${entry.kind} ${entry.from} → ${entry.to === rootId ? 'main' : agents.get(entry.to) ?? entry.to}${entry.body ? `: ${entry.body.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'board.pin':
+        text = `${entry.kind === 'claim' ? '⚑' : entry.kind === 'decision' ? '◆' : '•'} ${entry.agent} pins ${entry.kind} ${entry.pinId}${entry.task ? ` for ${entry.task}` : ''}${entry.paths ? ` [${entry.paths.join(', ')}]` : ''}: ${entry.body.split('\n')[0].slice(0, 120)}`;
+        break;
+      case 'task':
+        text = `☐ ${entry.agent} ${TASK_PAST[entry.action] ?? entry.action} ${entry.id} "${entry.title}" → ${entry.status}${entry.detail ? `: ${entry.detail.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'board.unpin':
+        text = `⚐ ${entry.pinId} by ${entry.agent} ${entry.reason === 'session_ended' ? 'released when its session ended' : 'taken down'}`;
+        break;
+      case 'human.question':
+        text = `? ${entry.agent} asks the user [${entry.questionId}]: ${entry.body.split('\n')[0].slice(0, 120)}`;
+        break;
+      case 'verify':
+        text = `${entry.skipped ? '–' : entry.passed ? '✓' : '✗'} verify in the ${entry.where}${entry.taskId ? ` for ${entry.taskId}` : ''}${entry.assignmentId ? ` (${entry.assignmentId})` : ''}: ${entry.skipped ? `skipped: ${entry.skipped}` : entry.detail}`;
+        break;
+      case 'epic.landed':
+        text = `◆ ${entry.agent} closed ${entry.id} "${entry.title}": ${entry.tasks} tasks, ${entry.reworked} reworked`;
+        break;
+      case 'notice':
+        text = `${entry.level === 'error' ? '‼' : entry.level === 'warning' ? '!' : 'ℹ'} ${entry.text}`;
+        break;
+      case 'assignment.parked':
+        text = `⏸ ${entry.agent} ${entry.assignmentId} parked: ${entry.reason}`;
+        break;
+      case 'assignment.resumed':
+        text = `▶ ${entry.agent} ${entry.assignmentId} resumed`;
+        break;
+      case 'instructions':
+        text = `# ${entry.agent} instructions ${entry.sha} (ALP.md ${entry.parts?.project}, AGENT.md ${entry.parts?.agent}, ${entry.chars} chars)`;
+        break;
+      case 'context':
+        // Before 0.6 the advice came at 60% and 80% of the window (ALPD §35); since, once near compaction (§57).
+        text = entry.level === 'soon'
+          ? `◔ ${entry.agent} context ${tokens(entry.tokens)}, compacts at ${tokens(entry.compactAt)}: told it is near`
+          : `◔ ${entry.agent} context ${entry.percent}% full: ${entry.level === 'now' ? 'told to hand off now' : 'told to plan a handoff'}`;
+        break;
+      case 'skill':
+        // alp_skill saving a skill (name, roles) shares the name with an agent using one (skill, via).
+        text = Array.isArray(entry.roles)
+          ? `✦ ${entry.agent} saved skill ${entry.name} for ${entry.roles.join(', ')}`
+          : `✦ ${entry.agent} uses skill ${entry.skill}${entry.via === 'skill' ? ' (Skill tool)' : ''}`;
+        break;
+      case 'compacted':
+        text = entry.failed
+          ? `✗ ${entry.agent}'s context could not be compacted${entry.error ? `: ${entry.error}` : ''}`
+          : `◑ ${entry.agent}'s context compacted${entry.preTokens !== undefined ? ` from ${tokens(entry.preTokens)}` : ''}${entry.postTokens !== undefined ? ` to ${tokens(entry.postTokens)}` : ''}${entry.trigger === 'manual' ? ' on request' : ''}`;
+        break;
+      case 'assignment.interrupted':
+        text = `⏹ ${entry.agent} ${entry.assignmentId} interrupted: ${entry.reason}; the next alpd continues it`;
+        break;
+      case 'assignment.recovered':
+        text = `↻ ${entry.agent} ${entry.assignmentId} reopened after alpd restarted`;
+        break;
+      case 'session.restarted':
+        text = `↻ ${entry.agent}'s native process stopped (${entry.error}); restart ${entry.restarts}`;
+        break;
+      case 'session.revived':
+        text = `▶ ${entry.agent} running again`;
+        break;
+      case 'session.revive_failed':
+        text = `✗ ${entry.agent} could not be restarted: ${entry.error}`;
+        break;
+      case 'human.answer':
+        text = `↳ ${entry.questionId} ${entry.outcome}${entry.answer !== undefined ? `: ${entry.answer.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'hook':
+        text = entry.skipped ? `↪ ${entry.agent}'s ${entry.on} hook ${entry.hook} skipped: the workspace's hooks are not trusted`
+          : `${entry.blocked ? '⛔' : entry.error || entry.exitCode !== 0 || entry.timedOut ? '✗' : '↪'} ${entry.agent}'s ${entry.on} hook ${entry.hook} ${entry.error ? `could not run: ${entry.error}` : entry.timedOut ? 'timed out' : `exit ${entry.exitCode}`}${entry.durationMs !== undefined ? ` in ${duration(entry.durationMs)}` : ''}${entry.blocked ? ', refused it' : ''}${entry.output ? `: ${entry.output.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'hook.trust':
+        text = `${entry.trusted ? '✓ the user trusts' : '✗ the user did not trust'} the hooks of ${entry.project}${entry.outcome ? ` (${entry.outcome})` : ''}`;
+        break;
+      case 'runtime.slip':
+        text = `⚠ ALP could not handle ${entry.agent}'s ${entry.method}: ${entry.error}; the session went on`;
+        break;
+      default:
+        text = `${entry.event}${entry.branch ? ` ${entry.branch}` : ''}${entry.status ? ` ${entry.status}` : ''}`;
+    }
+    lines.push(`${time}  ${text}`);
+  }
+  return lines;
+}

package/src/rpc/client.js

@@ -0,0 +1,296 @@
+import { AlpRpcError, MAX_FRAME } from '@anhlp/alp-protocol';
+import { AlpClientError } from './errors.js';
+import { utf8Length } from './framing.js';
+import { timerDelay } from './timers.js';
+
+/**
+ * The transport-independent JSON-RPC 2.0 engine of an ALP client (plans/reference/ALPD.md §3):
+ * request correlation, the daemon's `event` and other notifications, requests the daemon sends
+ * the client (extension.register), local timeouts and aborts, and cleanup when the connection
+ * ends. It runs unchanged in Node, browsers and React Native; a transport moves whole frames.
+ *
+ * A transport carries one complete JSON-RPC message per frame, as text. Framing (newlines on a
+ * socket, one WebSocket message per frame), byte decoding, connection setup and authentication
+ * belong to the transport and whoever creates it, never to this engine.
+ */
+
+/**
+ * @typedef {'open' | 'closed'} TransportState
+ * @typedef {{ error?: Error, code?: number, reason?: string }} TransportClose
+ *   Why a transport closed: `error` when it failed, `code`/`reason` when the peer said so.
+ * @typedef {{
+ *   readonly state: TransportState,
+ *   send(frame: string): void,
+ *   onMessage(listener: (frame: string) => void): () => void,
+ *   onClose(listener: (close: TransportClose) => void): () => void,
+ *   close(): void,
+ * }} AlpTransport
+ *   Contract (docs/alp/client-sdk.md): `send` delivers or throws, synchronously, and a throw means
+ *   the frame did not leave; `onMessage` delivers frames in arrival order; `onClose` fires at most
+ *   once, also after `close()`; nothing is delivered after it; `close` is idempotent.
+ * @typedef {{
+ *   readonly aborted: boolean,
+ *   readonly reason?: unknown,
+ *   addEventListener(type: 'abort', listener: () => void, options?: { once?: boolean }): void,
+ *   removeEventListener(type: 'abort', listener: () => void): void,
+ * }} AbortSignalLike
+ * @typedef {{ signal?: AbortSignalLike, timeoutMs?: number }} RequestOptions
+ *   Both end only this client's wait; neither tells the daemon to stop. A timeout of Infinity, or
+ *   longer than a timer can wait (2^31-1 ms), means none.
+ * @typedef {{
+ *   maxPending?: number,
+ *   maxFrame?: number,
+ *   timeoutMs?: number,
+ *   onListenerError?: (error: unknown) => void,
+ * }} AlpRpcClientOptions
+ */
+
+const CLOSED = 'ALP daemon connection closed';
+/** Requests waiting for an answer at once; beyond it a request fails as `overloaded` and is not sent. */
+export const DEFAULT_MAX_PENDING = 4096;
+
+/** A listener's exception must not break dispatch to the others; it surfaces like an uncaught error. @param {unknown} error */
+const rethrow = error => { setTimeout(() => { throw error; }, 0); };
+
+/** @param {AlpTransport} transport */
+function assertTransport(transport) {
+  for (const name of ['send', 'onMessage', 'onClose', 'close']) {
+    if (typeof /** @type {any} */ (transport)?.[name] !== 'function') throw new TypeError(`ALP transport must implement ${name}()`);
+  }
+}
+
+/** @param {AbortSignalLike} signal */
+const abortError = signal => new AlpClientError('ALP request aborted', { reason: 'aborted', cause: signal.reason });
+
+/** @param {object} value @param {string} key */
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+
+export class AlpRpcClient {
+  /** @type {AlpTransport} */ #transport;
+  #sequence = 0;
+  /** @type {Map<number, { resolve(value: unknown): void, reject(error: unknown): void, cleanup(): void }>} */
+  #pending = new Map();
+  /** @type {Set<(envelope: any) => void>} */ #events = new Set();
+  /** @type {Set<(method: string, params: any) => void>} */ #notifications = new Set();
+  /** @type {Set<(error: Error) => void>} */ #closes = new Set();
+  /** @type {Set<(method: string, params: any) => unknown>} */ #requestHandlers = new Set();
+  /** @type {Array<() => void>} */ #detach = [];
+  /** @type {AlpClientError | undefined} */ #closeError;
+  #maxPending;
+  #maxFrame;
+  #timeoutMs;
+  #onListenerError;
+
+  /**
+   * @param {AlpTransport} transport an open transport; the client owns it from now on
+   * @param {AlpRpcClientOptions} [options]
+   */
+  constructor(transport, { maxPending = DEFAULT_MAX_PENDING, maxFrame = MAX_FRAME, timeoutMs, onListenerError = rethrow } = {}) {
+    assertTransport(transport);
+    this.#transport = transport;
+    this.#maxPending = maxPending;
+    this.#maxFrame = maxFrame;
+    timerDelay(timeoutMs);
+    this.#timeoutMs = timeoutMs;
+    this.#onListenerError = onListenerError;
+    this.#detach.push(transport.onMessage(frame => this.#receive(frame)));
+    this.#detach.push(transport.onClose(close => this.#finish(this.#disconnected(close))));
+    if (transport.state === 'closed') this.#finish(new AlpClientError(CLOSED, { reason: 'disconnected' }));
+  }
+
+  /** True once the connection is gone, for whatever reason. */
+  get closed() { return this.#closeError !== undefined; }
+  /** Requests sent and still waiting for an answer. */
+  get pendingCount() { return this.#pending.size; }
+
+  /**
+   * Sends one request and resolves with its result, or rejects with AlpRpcError (the daemon
+   * answered with an error) or AlpClientError (the client gave up: see CLIENT_ERROR). Requests are
+   * never resent, also not after a reconnect.
+   * @template [T=any]
+   * @param {string} method
+   * @param {unknown} [params]
+   * @param {RequestOptions} [options]
+   * @returns {Promise<T>}
+   */
+  request(method, params = {}, { signal, timeoutMs = this.#timeoutMs } = {}) {
+    if (this.#closeError) return Promise.reject(new AlpClientError(CLOSED, { reason: this.#closeError.reason === 'closed' ? 'closed' : 'disconnected', cause: this.#closeError }));
+    if (signal?.aborted) return Promise.reject(abortError(signal));
+    if (this.#pending.size >= this.#maxPending) return Promise.reject(new AlpClientError(`Too many ALP requests waiting for an answer (${this.#maxPending})`, { reason: 'overloaded' }));
+    /** @type {number | undefined} */
+    let delay;
+    try { delay = timerDelay(timeoutMs); } catch (error) { return Promise.reject(error); }
+    const id = ++this.#sequence;
+    let frame;
+    try { frame = JSON.stringify({ jsonrpc: '2.0', id, method, params }); } catch (error) { return Promise.reject(error); }
+    // The limit counts the newline a stream transport adds, as alpd counts it.
+    if (utf8Length(frame) >= this.#maxFrame) return Promise.reject(new AlpClientError(`ALP request ${method} exceeds the ${this.#maxFrame}-byte frame limit`, { reason: 'send_failed' }));
+    return new Promise((resolve, reject) => {
+      /** @type {ReturnType<typeof setTimeout> | undefined} */
+      let timer;
+      const onAbort = () => { if (this.#pending.delete(id)) { cleanup(); reject(abortError(/** @type {AbortSignalLike} */ (signal))); } };
+      const cleanup = () => {
+        if (timer !== undefined) clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+      };
+      this.#pending.set(id, { resolve, reject, cleanup });
+      if (delay !== undefined) {
+        timer = setTimeout(() => {
+          if (!this.#pending.delete(id)) return;
+          cleanup();
+          reject(new AlpClientError(`ALP request ${method} timed out after ${timeoutMs} ms`, { reason: 'timeout' }));
+        }, delay);
+      }
+      signal?.addEventListener('abort', onAbort, { once: true });
+      try {
+        this.#transport.send(frame);
+      } catch (error) {
+        // A transport that is already gone (a socket half-closed by alpd, a WebSocket closing) ends
+        // the connection now, so `closed` is true when this request rejects, as it was before the
+        // transport reported its close. A transport still open refused only this frame.
+        if (this.#transport.state === 'closed') this.#finish(new AlpClientError(CLOSED, { reason: 'disconnected', cause: error }));
+        else if (this.#pending.delete(id)) {
+          cleanup();
+          reject(new AlpClientError(`Could not send ALP request ${method}: ${error instanceof Error ? error.message : String(error)}`, { reason: 'send_failed', cause: error }));
+        }
+      }
+    });
+  }
+
+  /** Every `event` notification: an envelope of a session the connection attached to. Returns a remover. @param {(envelope: any) => void} listener */
+  onEvent(listener) { return this.#add(this.#events, listener); }
+
+  /** Every notification from the daemon, `event` included; for methods this client does not know yet. @param {(method: string, params: any) => void} listener */
+  onNotification(listener) { return this.#add(this.#notifications, listener); }
+
+  /**
+   * Answers requests the daemon sends this client (the extension RPC of ALPD §61). The first
+   * handler answers; its result, or its error's numeric `code`, `message` and `data`, goes back.
+   * @param {(method: string, params: any) => unknown} handler
+   */
+  onRequest(handler) { return this.#add(this.#requestHandlers, handler); }
+
+  /** Called once when the connection ends, with the error pending requests were rejected with. @param {(error: Error) => void} listener */
+  onClose(listener) { return this.#add(this.#closes, listener); }
+
+  /** Ends the connection; waiting requests reject with reason `closed`. Idempotent. */
+  close() {
+    if (this.#closeError) return;
+    this.#finish(new AlpClientError(CLOSED, { reason: 'closed' }));
+  }
+
+  /** @template F @param {Set<F>} set @param {F} listener */
+  #add(set, listener) {
+    if (typeof listener !== 'function') throw new TypeError('ALP client listener must be a function');
+    if (this.#closeError) return () => false;
+    set.add(listener);
+    return () => set.delete(listener);
+  }
+
+  /** @param {TransportClose} [close] */
+  #disconnected(close = {}) {
+    if (close.error instanceof AlpClientError) return close.error;
+    const data = close.code !== undefined || close.reason ? { code: close.code, reason: close.reason } : undefined;
+    return new AlpClientError(close.error?.message ?? CLOSED, { reason: 'disconnected', cause: close.error, data });
+  }
+
+  /** @param {string} message */
+  #violation(message) {
+    this.#finish(new AlpClientError(message, { reason: 'protocol' }));
+  }
+
+  /** @param {Function} listener @param {unknown[]} args */
+  #call(listener, ...args) {
+    try { listener(...args); } catch (error) { this.#onListenerError(error); }
+  }
+
+  /** @param {string} frame */
+  #receive(frame) {
+    if (this.#closeError) return;
+    if (typeof frame !== 'string') return this.#violation('Invalid frame from ALP daemon');
+    let message;
+    try { message = JSON.parse(frame); } catch { return this.#violation('Invalid frame from ALP daemon'); }
+    if (typeof message !== 'object' || message === null || Array.isArray(message)) return this.#violation('Invalid frame from ALP daemon');
+    const hasId = message.id !== undefined && message.id !== null;
+    if (message.method === 'event') {
+      for (const listener of [...this.#events]) this.#call(listener, message.params);
+      for (const listener of [...this.#notifications]) this.#call(listener, message.method, message.params);
+      return;
+    }
+    if (typeof message.method === 'string' && hasId && !own(message, 'result') && !own(message, 'error')) return this.#answer(message.id, message.method, message.params ?? {});
+    if (typeof message.method === 'string' && !hasId) {
+      for (const listener of [...this.#notifications]) this.#call(listener, message.method, message.params);
+      return;
+    }
+    // A response to a request this client no longer waits for (timed out, aborted) or never sent,
+    // and an error the daemon could not tie to a request (id null), have nobody to go to.
+    const waiter = this.#pending.get(message.id);
+    if (!waiter) return;
+    this.#pending.delete(message.id);
+    waiter.cleanup();
+    if (own(message, 'error') && typeof message.error === 'object' && message.error !== null) waiter.reject(new AlpRpcError(message.error));
+    else if (own(message, 'result') && !own(message, 'error')) waiter.resolve(message.result);
+    else waiter.reject(new AlpClientError('Malformed response from ALP daemon', { reason: 'protocol', data: { id: message.id } }));
+  }
+
+  /**
+   * Answers a request from alpd. Every request gets exactly one answer: a result that cannot be
+   * serialized or does not fit a frame becomes an error, and an error whose data cannot go either
+   * goes without it, so alpd's caller never waits for a reply that was silently dropped.
+   * @param {unknown} id @param {string} method @param {unknown} params
+   */
+  #answer(id, method, params) {
+    /** The frame for `body`, or undefined if it cannot be serialized or is over the limit. @param {object} body */
+    const frameOf = body => {
+      try {
+        const frame = JSON.stringify({ jsonrpc: '2.0', id, ...body });
+        return utf8Length(frame) < this.#maxFrame ? frame : undefined;
+      } catch { return undefined; }
+    };
+    /** @param {string | undefined} frame */
+    const send = frame => {
+      if (this.#closeError) return;
+      if (frame === undefined) return this.#finish(new AlpClientError('ALP reply exceeds the frame limit', { reason: 'protocol' }));
+      try { this.#transport.send(frame); } catch (cause) {
+        this.#finish(new AlpClientError('Could not send ALP reply', { reason: 'send_failed', cause }));
+      }
+    };
+    /** @param {unknown} error */
+    const failure = error => {
+      const code = (error && typeof (/** @type {any} */ (error)).code === 'number') ? /** @type {any} */ (error).code : 1000;
+      const text = error instanceof Error ? error.message : String(error);
+      const message = text.length > 2000 ? `${text.slice(0, 2000)}...` : text;
+      const data = (error && /** @type {any} */ (error).data !== undefined) ? { data: /** @type {any} */ (error).data } : {};
+      return frameOf({ error: { code, message, ...data } }) ?? frameOf({ error: { code, message } })
+        ?? frameOf({ error: { code: -32603, message: 'The reply could not be sent' } });
+    };
+    const [handler] = this.#requestHandlers;
+    if (!handler) return send(failure(Object.assign(new Error(`Unknown method '${method}'`), { code: -32601 })));
+    Promise.resolve().then(async () => {
+      try {
+        const result = await handler(method, params);
+        const frame = frameOf({ result: result === undefined ? {} : result });
+        send(frame ?? failure(new Error(`The result of ${method} cannot be serialized or exceeds the ${this.#maxFrame}-byte frame limit`)));
+      } catch (error) {
+        send(failure(error));
+      }
+    });
+  }
+
+  /** @param {AlpClientError} error */
+  #finish(error) {
+    if (this.#closeError) return;
+    this.#closeError = error;
+    for (const detach of this.#detach.splice(0)) { try { detach(); } catch {} }
+    try { this.#transport.close(); } catch {}
+    const pending = [...this.#pending.values()];
+    this.#pending.clear();
+    for (const waiter of pending) { waiter.cleanup(); waiter.reject(error); }
+    const closes = [...this.#closes];
+    this.#events.clear();
+    this.#notifications.clear();
+    this.#requestHandlers.clear();
+    this.#closes.clear();
+    for (const listener of closes) this.#call(listener, error);
+  }
+}