@anhlp/alp-client 0.0.0-stage → 0.0.1-beta.4

package/dist/prompt.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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<T>({ message, choices, initial }: {
+    message: string;
+    choices: Array<{
+        label: string;
+        value: T;
+        hint?: string;
+    }>;
+    initial?: T;
+}, { input, output }?: {
+    input?: NodeJS.ReadStream;
+    output?: NodeJS.WriteStream;
+}): Promise<T>;
+/**
+ * A line of text, for a value the list does not offer.
+ * @param {string} message
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream }} [io]
+ */
+export function text(message: string, { input, output }?: {
+    input?: NodeJS.ReadStream;
+    output?: NodeJS.WriteStream;
+}): Promise<string>;
+export class Cancelled extends Error {
+    constructor();
+}

package/dist/prompt.js

@@ -0,0 +1,59 @@
+// packages/client/src/prompt.js
+import { emitKeypressEvents } from "node:readline";
+var dim = (text2) => `\x1B[2m${text2}\x1B[22m`;
+var cyan = (text2) => `\x1B[36m${text2}\x1B[39m`;
+var Cancelled = class extends Error {
+  constructor() {
+    super("Setup cancelled.");
+  }
+};
+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("(\u2191/\u2193, Enter)")}`, ...choices.map((choice, at) => at === index ? cyan(`\u276F ${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("\u2714")} ${message} ${cyan(choices[index].label)}
+`);
+      settle(value);
+    };
+    const onKey = (text2, 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();
+  });
+}
+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();
+  }
+}
+export {
+  Cancelled,
+  select,
+  text
+};

package/dist/render.d.ts

@@ -0,0 +1,6 @@
+/** `alp ps`: sessions as a tree, one line each. */
+export function renderPs(sessions: any): any[];
+/** `alp log`: one line per run-log entry, with its time. */
+export function renderLog(rootId: any, entries: any): string[];
+export function ago(since: any, now?: number): string;
+export function duration(ms: any): string;

package/dist/render.js

@@ -0,0 +1,120 @@
+// packages/client/src/render.js
+var 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)" };
+var ago = (since, now = Date.now()) => {
+  const seconds = Math.max(0, Math.round((now - Date.parse(since)) / 1e3));
+  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`;
+};
+var duration = (ms) => ago((/* @__PURE__ */ new Date(0)).toISOString(), ms);
+var tokens = (count) => typeof count !== "number" ? "?" : count >= 1e6 && count % 1e6 < 5e4 ? `${Math.round(count / 1e6)}M` : `${Math.round(count / 1e3)}k`;
+function renderPs(sessions) {
+  const lines = [];
+  const children = /* @__PURE__ */ 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;
+}
+function renderLog(rootId, entries) {
+  const lines = [];
+  const agents = /* @__PURE__ */ 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} \u2192 ${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":
+        if (entry.kind === "board") continue;
+        text = `\u2709 ${entry.kind} ${entry.from} \u2192 ${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" ? "\u2691" : entry.kind === "decision" ? "\u25C6" : "\u2022"} ${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 = `\u2610 ${entry.agent} ${TASK_PAST[entry.action] ?? entry.action} ${entry.id} "${entry.title}" \u2192 ${entry.status}${entry.detail ? `: ${entry.detail.split("\n")[0].slice(0, 120)}` : ""}`;
+        break;
+      case "board.unpin":
+        text = `\u2690 ${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 ? "\u2013" : entry.passed ? "\u2713" : "\u2717"} 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 = `\u25C6 ${entry.agent} closed ${entry.id} "${entry.title}": ${entry.tasks} tasks, ${entry.reworked} reworked`;
+        break;
+      case "notice":
+        text = `${entry.level === "error" ? "\u203C" : entry.level === "warning" ? "!" : "\u2139"} ${entry.text}`;
+        break;
+      case "assignment.parked":
+        text = `\u23F8 ${entry.agent} ${entry.assignmentId} parked: ${entry.reason}`;
+        break;
+      case "assignment.resumed":
+        text = `\u25B6 ${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":
+        text = entry.level === "soon" ? `\u25D4 ${entry.agent} context ${tokens(entry.tokens)}, compacts at ${tokens(entry.compactAt)}: told it is near` : `\u25D4 ${entry.agent} context ${entry.percent}% full: ${entry.level === "now" ? "told to hand off now" : "told to plan a handoff"}`;
+        break;
+      case "skill":
+        text = Array.isArray(entry.roles) ? `\u2726 ${entry.agent} saved skill ${entry.name} for ${entry.roles.join(", ")}` : `\u2726 ${entry.agent} uses skill ${entry.skill}${entry.via === "skill" ? " (Skill tool)" : ""}`;
+        break;
+      case "compacted":
+        text = entry.failed ? `\u2717 ${entry.agent}'s context could not be compacted${entry.error ? `: ${entry.error}` : ""}` : `\u25D1 ${entry.agent}'s context compacted${entry.preTokens !== void 0 ? ` from ${tokens(entry.preTokens)}` : ""}${entry.postTokens !== void 0 ? ` to ${tokens(entry.postTokens)}` : ""}${entry.trigger === "manual" ? " on request" : ""}`;
+        break;
+      case "assignment.interrupted":
+        text = `\u23F9 ${entry.agent} ${entry.assignmentId} interrupted: ${entry.reason}; the next alpd continues it`;
+        break;
+      case "assignment.recovered":
+        text = `\u21BB ${entry.agent} ${entry.assignmentId} reopened after alpd restarted`;
+        break;
+      case "session.restarted":
+        text = `\u21BB ${entry.agent}'s native process stopped (${entry.error}); restart ${entry.restarts}`;
+        break;
+      case "session.revived":
+        text = `\u25B6 ${entry.agent} running again`;
+        break;
+      case "session.revive_failed":
+        text = `\u2717 ${entry.agent} could not be restarted: ${entry.error}`;
+        break;
+      case "human.answer":
+        text = `\u21B3 ${entry.questionId} ${entry.outcome}${entry.answer !== void 0 ? `: ${entry.answer.split("\n")[0].slice(0, 120)}` : ""}`;
+        break;
+      case "hook":
+        text = entry.skipped ? `\u21AA ${entry.agent}'s ${entry.on} hook ${entry.hook} skipped: the workspace's hooks are not trusted` : `${entry.blocked ? "\u26D4" : entry.error || entry.exitCode !== 0 || entry.timedOut ? "\u2717" : "\u21AA"} ${entry.agent}'s ${entry.on} hook ${entry.hook} ${entry.error ? `could not run: ${entry.error}` : entry.timedOut ? "timed out" : `exit ${entry.exitCode}`}${entry.durationMs !== void 0 ? ` 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 ? "\u2713 the user trusts" : "\u2717 the user did not trust"} the hooks of ${entry.project}${entry.outcome ? ` (${entry.outcome})` : ""}`;
+        break;
+      case "runtime.slip":
+        text = `\u26A0 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;
+}
+export {
+  ago,
+  duration,
+  renderLog,
+  renderPs
+};

package/dist/rpc/client.d.ts

@@ -0,0 +1,82 @@
+/** Requests waiting for an answer at once; beyond it a request fails as `overloaded` and is not sent. */
+export const DEFAULT_MAX_PENDING: 4096;
+export class AlpRpcClient {
+    /**
+     * @param {AlpTransport} transport an open transport; the client owns it from now on
+     * @param {AlpRpcClientOptions} [options]
+     */
+    constructor(transport: AlpTransport, { maxPending, maxFrame, timeoutMs, onListenerError }?: AlpRpcClientOptions);
+    /** True once the connection is gone, for whatever reason. */
+    get closed(): boolean;
+    /** Requests sent and still waiting for an answer. */
+    get pendingCount(): number;
+    /**
+     * 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<T = any>(method: string, params?: unknown, { signal, timeoutMs }?: RequestOptions): Promise<T>;
+    /** Every `event` notification: an envelope of a session the connection attached to. Returns a remover. @param {(envelope: any) => void} listener */
+    onEvent(listener: (envelope: any) => void): () => boolean;
+    /** Every notification from the daemon, `event` included; for methods this client does not know yet. @param {(method: string, params: any) => void} listener */
+    onNotification(listener: (method: string, params: any) => void): () => boolean;
+    /**
+     * 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: (method: string, params: any) => unknown): () => boolean;
+    /** Called once when the connection ends, with the error pending requests were rejected with. @param {(error: Error) => void} listener */
+    onClose(listener: (error: Error) => void): () => boolean;
+    /** Ends the connection; waiting requests reject with reason `closed`. Idempotent. */
+    close(): void;
+    #private;
+}
+export type TransportState = "open" | "closed";
+/**
+ * Why a transport closed: `error` when it failed, `code`/`reason` when the peer said so.
+ */
+export type TransportClose = {
+    error?: Error;
+    code?: number;
+    reason?: string;
+};
+/**
+ * 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.
+ */
+export type AlpTransport = {
+    readonly state: TransportState;
+    send(frame: string): void;
+    onMessage(listener: (frame: string) => void): () => void;
+    onClose(listener: (close: TransportClose) => void): () => void;
+    close(): void;
+};
+export type AbortSignalLike = {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+};
+/**
+ * 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.
+ */
+export type RequestOptions = {
+    signal?: AbortSignalLike;
+    timeoutMs?: number;
+};
+export type AlpRpcClientOptions = {
+    maxPending?: number;
+    maxFrame?: number;
+    timeoutMs?: number;
+    onListenerError?: (error: unknown) => void;
+};

package/dist/rpc/client.js

@@ -0,0 +1,292 @@
+// packages/client/src/rpc/client.js
+import { AlpRpcError, MAX_FRAME } from "@anhlp/alp-protocol";
+import { AlpClientError } from "./errors.js";
+import { utf8Length } from "./framing.js";
+import { timerDelay } from "./timers.js";
+var CLOSED = "ALP daemon connection closed";
+var DEFAULT_MAX_PENDING = 4096;
+var rethrow = (error) => {
+  setTimeout(() => {
+    throw error;
+  }, 0);
+};
+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}()`);
+  }
+}
+var abortError = (signal) => new AlpClientError("ALP request aborted", { reason: "aborted", cause: signal.reason });
+var own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+var AlpRpcClient = class {
+  /** @type {AlpTransport} */
+  #transport;
+  #sequence = 0;
+  /** @type {Map<number, { resolve(value: unknown): void, reject(error: unknown): void, cleanup(): void }>} */
+  #pending = /* @__PURE__ */ new Map();
+  /** @type {Set<(envelope: any) => void>} */
+  #events = /* @__PURE__ */ new Set();
+  /** @type {Set<(method: string, params: any) => void>} */
+  #notifications = /* @__PURE__ */ new Set();
+  /** @type {Set<(error: Error) => void>} */
+  #closes = /* @__PURE__ */ new Set();
+  /** @type {Set<(method: string, params: any) => unknown>} */
+  #requestHandlers = /* @__PURE__ */ 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 !== void 0;
+  }
+  /** 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" }));
+    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);
+    }
+    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) => {
+      let timer;
+      const onAbort = () => {
+        if (this.#pending.delete(id)) {
+          cleanup();
+          reject(abortError(
+            /** @type {AbortSignalLike} */
+            signal
+          ));
+        }
+      };
+      const cleanup = () => {
+        if (timer !== void 0) clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      this.#pending.set(id, { resolve, reject, cleanup });
+      if (delay !== void 0) {
+        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) {
+        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 !== void 0 || close.reason ? { code: close.code, reason: close.reason } : void 0;
+    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 !== void 0 && 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;
+    }
+    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) {
+    const frameOf = (body) => {
+      try {
+        const frame = JSON.stringify({ jsonrpc: "2.0", id, ...body });
+        return utf8Length(frame) < this.#maxFrame ? frame : void 0;
+      } catch {
+        return void 0;
+      }
+    };
+    const send = (frame) => {
+      if (this.#closeError) return;
+      if (frame === void 0) 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 }));
+      }
+    };
+    const failure = (error) => {
+      const code = error && typeof /** @type {any} */
+      error.code === "number" ? (
+        /** @type {any} */
+        error.code
+      ) : 1e3;
+      const text = error instanceof Error ? error.message : String(error);
+      const message = text.length > 2e3 ? `${text.slice(0, 2e3)}...` : text;
+      const data = error && /** @type {any} */
+      error.data !== void 0 ? { 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 === void 0 ? {} : 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);
+  }
+};
+export {
+  AlpRpcClient,
+  DEFAULT_MAX_PENDING
+};

package/dist/rpc/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * True for an AlpClientError, also one thrown by another copy of this module (a bundle may carry
+ * two); `reason` narrows the check.
+ * @param {unknown} error
+ * @param {string} [reason]
+ * @returns {error is AlpClientError}
+ */
+export function isAlpClientError(error: unknown, reason?: string): error is AlpClientError;
+/**
+ * Why a request or a connection ended on the client side.
+ * - `closed`: this client was closed locally with close().
+ * - `disconnected`: the transport closed or failed. A request that was already sent may or may not
+ *   have run on the daemon; the client never resends it.
+ * - `protocol`: the peer sent something that is not ALP JSON-RPC, so the client closed the connection.
+ * - `send_failed`: the transport refused the frame; the request never left this client.
+ * - `timeout` / `aborted`: the caller stopped waiting. Only the local wait ends; the daemon is not told.
+ * - `overloaded`: too many requests are waiting for an answer already; nothing was sent.
+ */
+export const CLIENT_ERROR: Readonly<{
+    closed: "closed";
+    disconnected: "disconnected";
+    protocol: "protocol";
+    sendFailed: "send_failed";
+    timeout: "timeout";
+    aborted: "aborted";
+    overloaded: "overloaded";
+}>;
+export class AlpClientError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ reason: 'closed' | 'disconnected' | 'protocol' | 'send_failed' | 'timeout' | 'aborted' | 'overloaded', cause?: unknown, data?: unknown }} details
+     */
+    constructor(message: string, { reason, cause, data }: {
+        reason: "closed" | "disconnected" | "protocol" | "send_failed" | "timeout" | "aborted" | "overloaded";
+        cause?: unknown;
+        data?: unknown;
+    });
+    /** @type {'closed' | 'disconnected' | 'protocol' | 'send_failed' | 'timeout' | 'aborted' | 'overloaded'} */
+    reason: "closed" | "disconnected" | "protocol" | "send_failed" | "timeout" | "aborted" | "overloaded";
+    /** @type {unknown} */
+    data: unknown;
+}

package/dist/rpc/errors.js

@@ -0,0 +1,34 @@
+// packages/client/src/rpc/errors.js
+var BRAND = Symbol.for("@anhlp/alp-client/AlpClientError");
+var CLIENT_ERROR = Object.freeze({
+  closed: "closed",
+  disconnected: "disconnected",
+  protocol: "protocol",
+  sendFailed: "send_failed",
+  timeout: "timeout",
+  aborted: "aborted",
+  overloaded: "overloaded"
+});
+var AlpClientError = class extends Error {
+  /**
+   * @param {string} message
+   * @param {{ reason: 'closed' | 'disconnected' | 'protocol' | 'send_failed' | 'timeout' | 'aborted' | 'overloaded', cause?: unknown, data?: unknown }} details
+   */
+  constructor(message, { reason, cause, data }) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.name = "AlpClientError";
+    this.reason = reason;
+    this.data = data;
+    Object.defineProperty(this, BRAND, { value: true });
+  }
+};
+function isAlpClientError(error, reason) {
+  return typeof error === "object" && error !== null && /** @type {any} */
+  error[BRAND] === true && (reason === void 0 || /** @type {any} */
+  error.reason === reason);
+}
+export {
+  AlpClientError,
+  CLIENT_ERROR,
+  isAlpClientError
+};