@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.320

package/runtime/node_modules/@metro-labs/daemon/src/terminal/api.ts

@@ -0,0 +1,84 @@
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField, readJsonBody, sessionRoute } from '@metro-labs/http/api-http';
+import { log } from '@metro-labs/core/log';
+import { mintTerminalTicket } from './tickets.js';
+import { agentCommand, asAgent, claudeHome } from '../agent-user/user.js';
+import { inSessionScope } from '../claude/memory.js';
+import { tmuxServerUp } from '../claude/session.js';
+
+const PREFIX = '/api/terminal';
+const TICKETS = `${PREFIX}/tickets`;
+const SESSION_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+
+const scoped = (command: string[]): string[] => {
+  if (tmuxServerUp()) return command;
+  const [file = '', ...args] = command;
+  const [bin, argv] = inSessionScope([file, args]);
+  return [bin, ...argv];
+};
+
+export const tmuxCommand = (session: string, home = claudeHome() ?? homedir()): string[] => scoped(agentCommand([
+  'tmux',
+  'new-session',
+  '-A',
+  '-D',
+  '-s',
+  session,
+  '-c',
+  home,
+  ';',
+  'set-option',
+  '-g',
+  'mouse',
+  'on',
+  ';',
+  'set-option',
+  '-s',
+  'set-clipboard',
+  'on',
+  ';',
+  'set-option',
+  '-as',
+  'terminal-features',
+  ',xterm-256color:clipboard',
+], { TERM: 'xterm-256color', COLORTERM: 'truecolor' }));
+
+export interface TerminalApiDeps {
+  command?: (session: string) => string[];
+}
+
+function tmuxAvailable(deps: TerminalApiDeps): boolean {
+  if (deps.command !== undefined) return true;
+  const run = spawnSync(...asAgent('tmux', ['-V']), { stdio: 'ignore' });
+  return run.error === undefined && run.status === 0;
+}
+
+function tmuxSessions(): string[] {
+  const run = spawnSync(...asAgent('tmux', ['list-sessions', '-F', '#{session_name}']), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (run.error !== undefined || run.status !== 0) return [];
+  return run.stdout
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => SESSION_RE.test(l));
+}
+
+function sessionOf(raw: unknown): string {
+  if (raw === undefined || raw === null || raw === '')
+    throw new ApiError('name the tmux session to open; GET /api/terminal lists the ones that exist', 400);
+  if (typeof raw !== 'string' || !SESSION_RE.test(raw))
+    throw new ApiError('a session name is 1 to 32 letters, digits, dots, dashes or underscores', 400);
+  return raw;
+}
+
+export function handleTerminalRequest(req: IncomingMessage, res: ServerResponse, deps: TerminalApiDeps): boolean {
+  return sessionRoute(req, res, { methods: { [PREFIX]: ['GET'], [TICKETS]: ['POST'] }, admin: true, label: 'terminal-api' }, async (session, path) => {
+    if (path === PREFIX) return { available: tmuxAvailable(deps), sessions: tmuxSessions() };
+    const wanted = sessionOf(bodyField(await readJsonBody(req), 'session'));
+    const minted = mintTerminalTicket(session.subject, wanted);
+    log.info({ subject: session.subject, session: wanted }, 'terminal: ticket minted');
+    return { ...minted, session: wanted, path: `${PREFIX}/${minted.ticket}` };
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/terminal/socket.ts

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+import type { IncomingMessage, Server } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer, type RawData, type WebSocket } from 'ws';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { takeTerminalTicket, type TerminalGrant } from './tickets.js';
+import { asAgent } from '../agent-user/user.js';
+
+const TICKET_PATH = /^\/api\/terminal\/([A-Za-z0-9_-]{43})$/;
+const MAX_MESSAGE = 1024 * 1024;
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 36;
+const MAX_DIMENSION = 500;
+
+export interface TerminalSocketDeps {
+  command: (session: string) => string[];
+  takeTicket?: (ticket: string) => TerminalGrant | null;
+}
+
+const rawBytes = (data: RawData): Buffer =>
+  Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+
+export const resizeWindowArgs = (session: string, cols: number, rows: number): string[] => [
+  'resize-window',
+  '-t',
+  `${session}:`,
+  '-x',
+  String(cols),
+  '-y',
+  String(rows),
+];
+
+function sizeTmuxWindow(command: string[], session: string, cols: number, rows: number): void {
+  if (!command.includes('tmux')) return;
+  const child = spawn(...asAgent('tmux', resizeWindowArgs(session, cols, rows)), { stdio: 'ignore' });
+  child.on('error', (err) => {
+    log.warn({ err: errMsg(err) }, 'terminal: resize-window could not run');
+  });
+  child.on('exit', (code) => {
+    if (code !== 0) log.warn({ code, session, cols, rows }, 'terminal: tmux refused the window resize');
+  });
+}
+
+const dimension = (raw: unknown): number | null =>
+  typeof raw === 'number' && Number.isInteger(raw) && raw > 1 && raw <= MAX_DIMENSION ? raw : null;
+
+function sizeFrom(control: unknown): { cols: number; rows: number } | null {
+  if (!isRecord(control)) return null;
+  const cols = dimension(control.cols);
+  const rows = dimension(control.rows);
+  return cols === null || rows === null ? null : { cols, rows };
+}
+
+function runTerminal(ws: WebSocket, command: string[], subject: string, session: string): void {
+  const terminal = new Bun.Terminal({
+    cols: DEFAULT_COLS,
+    rows: DEFAULT_ROWS,
+    data: (_term, chunk) => {
+      if (ws.readyState === ws.OPEN) ws.send(chunk);
+    },
+  });
+  const proc = Bun.spawn(command, {
+    terminal,
+    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+  });
+  log.info({ subject, pid: proc.pid, command: command[0] }, 'terminal: opened');
+  ws.on('message', (data, isBinary) => {
+    const bytes = rawBytes(data);
+    if (isBinary) {
+      terminal.write(bytes);
+      return;
+    }
+    try {
+      const size = sizeFrom(JSON.parse(bytes.toString('utf8')));
+      if (size !== null) {
+        terminal.resize(size.cols, size.rows);
+        proc.kill('SIGWINCH');
+        sizeTmuxWindow(command, session, size.cols, size.rows);
+      }
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'terminal: bad control frame');
+    }
+  });
+  ws.on('close', () => {
+    proc.kill();
+    terminal.close();
+    log.info({ subject, pid: proc.pid }, 'terminal: closed by the page');
+  });
+  proc.exited
+    .then((code) => {
+      if (ws.readyState === ws.OPEN) ws.close(1000, `exit ${String(code)}`);
+      terminal.close();
+    })
+    .catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'terminal: exit watch failed');
+    });
+}
+
+function refuse(socket: Duplex, status: number, text: string): void {
+  socket.write(`HTTP/1.1 ${String(status)} ${text}\r\nConnection: close\r\n\r\n`);
+  socket.destroy();
+}
+
+export function attachTerminalSockets(server: Server, deps: TerminalSocketDeps): void {
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE });
+  const take = deps.takeTicket ?? takeTerminalTicket;
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const path = (req.url ?? '').split('?')[0] ?? '';
+    const found = TICKET_PATH.exec(path);
+    if (!found) {
+      refuse(socket, 404, 'Not Found');
+      return;
+    }
+    const grant = take(found[1] ?? '');
+    if (grant === null) {
+      refuse(socket, 401, 'Unauthorized');
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      runTerminal(ws, deps.command(grant.session), grant.subject, grant.session);
+    });
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/terminal/tickets.ts

@@ -0,0 +1,15 @@
+import { ticketStore } from '@metro-labs/core/tickets';
+
+export interface TerminalGrant {
+  subject: string;
+  session: string;
+}
+
+const tickets = ticketStore<TerminalGrant>(30_000, 20);
+
+export const mintTerminalTicket = (subject: string, session: string, now = Date.now()): { ticket: string; expiresAt: number } =>
+  tickets.mint({ subject, session }, now);
+
+export const takeTerminalTicket = (ticket: string, now = Date.now()): TerminalGrant | null => tickets.take(ticket, now) ?? null;
+
+export const pendingTerminalTickets = (): number => tickets.size();

package/runtime/node_modules/@metro-labs/daemon/src/voice/api.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { readJsonBody, sessionRoute } from '@metro-labs/http/api-http';
+import { patchVoice, publicVoice, readVoice, writeVoice } from './store.js';
+
+const PATH = '/api/voice';
+
+async function answer(req: IncomingMessage): Promise<unknown> {
+  if (req.method === 'PUT') writeVoice(patchVoice(readVoice(), await readJsonBody(req)));
+  return publicVoice(readVoice());
+}
+
+export function handleVoiceRequest(req: IncomingMessage, res: ServerResponse): boolean {
+  return sessionRoute(req, res, { methods: { [PATH]: ['GET', 'PUT'] }, admin: ['PUT'], label: 'voice-api' }, () => answer(req));
+}

package/runtime/node_modules/@metro-labs/daemon/src/voice/audio.ts

@@ -0,0 +1,193 @@
+import OpusScript from 'opusscript';
+import { errMsg, log } from '@metro-labs/core/log';
+
+const RATE = 48_000;
+const FRAME = 960;
+const FRAME_MS = 20;
+const MAX_LATE_FRAMES = 5;
+const MAX_QUEUED_FRAMES = 3_000;
+
+interface Frame {
+  pcm: Int16Array;
+  chars: number;
+}
+
+export function downsample3(pcm: Int16Array): Int16Array {
+  const out = new Int16Array(Math.floor(pcm.length / 3));
+  for (let i = 0; i < out.length; i += 1)
+    out[i] = Math.round(((pcm[i * 3] ?? 0) + (pcm[i * 3 + 1] ?? 0) + (pcm[i * 3 + 2] ?? 0)) / 3);
+  return out;
+}
+
+export function upsample2(pcm: Int16Array, carry: number): Int16Array {
+  const out = new Int16Array(pcm.length * 2);
+  let prev = carry;
+  for (let i = 0; i < pcm.length; i += 1) {
+    const cur = pcm[i] ?? 0;
+    out[i * 2] = Math.round((prev + cur) / 2);
+    out[i * 2 + 1] = cur;
+    prev = cur;
+  }
+  return out;
+}
+
+export const pcmOf = (bytes: Buffer): Int16Array => {
+  const copy = Buffer.from(bytes);
+  return new Int16Array(copy.buffer, copy.byteOffset, Math.floor(copy.length / 2));
+};
+
+export const bytesOf = (pcm: Int16Array): Buffer => Buffer.from(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+
+export class OpusIn {
+  private readonly decoder = new OpusScript(RATE, 1, OpusScript.Application.VOIP);
+
+  decode(packet: Buffer): Int16Array | null {
+    try {
+      return pcmOf(this.decoder.decode(packet));
+    } catch (err) {
+      log.debug({ err: errMsg(err) }, 'voice: an audio packet could not be decoded');
+      return null;
+    }
+  }
+
+  close(): void {
+    this.decoder.delete();
+  }
+}
+
+export interface Playback {
+  send(opus: Buffer, timestamp: number, marker: boolean): void | Promise<void>;
+  played(chars: number): void;
+}
+
+export class Player {
+  private readonly encoder = new OpusScript(RATE, 1, OpusScript.Application.VOIP);
+  private readonly queue: Frame[] = [];
+  private pending = new Int16Array(0);
+  private pendingChars = 0;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private started = 0;
+  private sent = 0;
+  private speaking = false;
+  private onIdle: (() => void) | null = null;
+  private onFirst: (() => void) | null = null;
+  private onFailed: ((reason: string) => void) | null = null;
+  private generation = 0;
+  private inFlight = 0;
+  private closed = false;
+
+  constructor(private readonly out: Playback) {}
+
+  get busy(): boolean {
+    return this.queue.length > 0 || this.pending.length > 0 || this.inFlight > 0;
+  }
+
+  whenFirstPlayed(fn: () => void): void {
+    this.onFirst = fn;
+  }
+
+  whenIdle(fn: () => void): void {
+    this.onIdle = fn;
+  }
+
+  whenFailed(fn: (reason: string) => void): void {
+    this.onFailed = fn;
+  }
+
+  push(pcm: Int16Array, chars: number): void {
+    if (this.closed) return;
+    if (this.queue.length + this.inFlight + Math.ceil((this.pending.length + pcm.length) / FRAME) > MAX_QUEUED_FRAMES) {
+      this.failed('audio queue is full');
+      return;
+    }
+    const joined = new Int16Array(this.pending.length + pcm.length);
+    joined.set(this.pending);
+    joined.set(pcm, this.pending.length);
+    let at = 0;
+    for (; at + FRAME <= joined.length; at += FRAME) this.queue.push({ pcm: joined.slice(at, at + FRAME), chars: 0 });
+    this.pending = joined.slice(at);
+    this.pendingChars += chars;
+    const last = this.queue.at(-1);
+    if (last !== undefined && this.pending.length === 0) {
+      last.chars += this.pendingChars;
+      this.pendingChars = 0;
+    }
+  }
+
+  finish(): void {
+    if (this.closed || this.pending.length === 0) return;
+    const pcm = new Int16Array(FRAME);
+    pcm.set(this.pending);
+    this.queue.push({ pcm, chars: this.pendingChars });
+    this.pending = new Int16Array(0);
+    this.pendingChars = 0;
+  }
+
+  clear(): void {
+    this.generation += 1;
+    this.inFlight = 0;
+    this.speaking = false;
+    this.queue.length = 0;
+    this.pending = new Int16Array(0);
+    this.pendingChars = 0;
+  }
+
+  start(): void {
+    if (this.closed || this.timer !== null) return;
+    this.started = performance.now();
+    this.sent = 0;
+    this.tick();
+  }
+
+  stop(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+    this.clear();
+    this.encoder.delete();
+  }
+
+  private tick(): void {
+    if (this.closed) return;
+    const due = Math.floor((performance.now() - this.started) / FRAME_MS) + 1;
+    if (due - this.sent > MAX_LATE_FRAMES) this.sent = due - 1;
+    while (!this.closed && this.sent < due) this.sendOne();
+    if (this.closed) return;
+    const next = this.started + this.sent * FRAME_MS;
+    this.timer = setTimeout(() => {
+      this.tick();
+    }, Math.max(0, next - performance.now()));
+  }
+
+  private sendOne(): void {
+    const frame = this.queue.shift();
+    const marker = frame !== undefined && !this.speaking;
+    this.speaking = frame !== undefined;
+    const pcm = frame?.pcm ?? new Int16Array(FRAME);
+    const timestamp = (this.sent * FRAME) >>> 0;
+    this.sent += 1;
+    const generation = this.generation;
+    if (frame !== undefined) this.inFlight += 1;
+    try {
+      const sent = this.out.send(this.encoder.encode(bytesOf(pcm), FRAME), timestamp, marker);
+      Promise.resolve(sent).then(() => {
+        if (this.closed || generation !== this.generation || frame === undefined) return;
+        this.inFlight -= 1;
+        if (marker) this.onFirst?.();
+        if (frame.chars > 0) this.out.played(frame.chars);
+        if (!this.busy) this.onIdle?.();
+      }).catch((err: unknown) => {
+        if (!this.closed && generation === this.generation) this.failed(errMsg(err));
+      });
+    } catch (err) {
+      if (!this.closed && generation === this.generation) this.failed(errMsg(err));
+    }
+  }
+
+  private failed(reason: string): void {
+    this.clear();
+    log.warn({ reason }, 'voice: audio playback failed');
+    this.onFailed?.(reason);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/voice/call.ts

@@ -0,0 +1,191 @@
+import { randomUUID } from 'node:crypto';
+import type { CallRoute } from '@metro-labs/core/call';
+import { errMsg, log } from '@metro-labs/core/log';
+import { forwardTrainCall } from '../stations/train-call.js';
+import type { Playback } from './audio.js';
+import { Peer, type PeerEvents } from './peer.js';
+import { SharedTalk } from './shared-talk.js';
+import { endSharedCall, hearSharedCall, openSharedCall, type SharedCallTransport } from './shared.js';
+import type { VoiceConfig } from './store.js';
+
+const OFFER_WAIT_MS = 45_000;
+const LONGEST_CALL_MS = 60 * 60_000;
+const LEAVE_RETRY_MS = 3_000;
+const SIGNAL_WAIT_MS = 2_000;
+
+export interface CallStart {
+  agentId: string;
+  sourceId: string;
+  line: string;
+  from: string;
+  callId: string;
+  callerPeer: string;
+}
+
+type CallAudio = Pick<SharedTalk, 'connect' | 'hear' | 'finish'> & SharedCallTransport;
+type CallPeer = Pick<Peer, 'answer' | 'sendOpus' | 'close'>;
+
+export interface CallDependencies {
+  train: typeof trainCall;
+  peer(events: PeerEvents): CallPeer;
+  shared(cfg: VoiceConfig, out: Playback['send'], ended: (reason: string) => void, heard: (text: string, sourceId: string) => void): CallAudio;
+  open: typeof openSharedCall;
+  heard: typeof hearSharedCall;
+  ended: typeof endSharedCall;
+  signalWaitMs: number;
+  leaveRetryMs: number;
+}
+
+export async function trainCall(action: string, args: Record<string, unknown>): Promise<unknown> {
+  const answer = await forwardTrainCall('xmtp', action, args);
+  if (answer.error !== undefined) throw new Error(answer.error);
+  return answer.result;
+}
+
+const dependencies: CallDependencies = {
+  train: trainCall,
+  peer: (events) => new Peer(events),
+  shared: (cfg, out, ended, heard) => new SharedTalk(cfg, out, ended, heard),
+  open: openSharedCall,
+  heard: hearSharedCall,
+  ended: endSharedCall,
+  signalWaitMs: SIGNAL_WAIT_MS,
+  leaveRetryMs: LEAVE_RETRY_MS,
+};
+
+export class Call {
+  readonly route: CallRoute;
+  private readonly selfPeer = randomUUID();
+  private readonly startedAt = Date.now();
+  private readonly talk: CallAudio;
+  private readonly deps: CallDependencies;
+  private peer: CallPeer | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private readonly longest: ReturnType<typeof setTimeout>;
+  private over = false;
+  private begun = false;
+  private left: Promise<void> = Promise.resolve();
+
+  constructor(
+    readonly start: CallStart,
+    cfg: VoiceConfig,
+    private readonly onOver: () => void,
+    deps: Partial<CallDependencies> = {},
+  ) {
+    this.deps = { ...dependencies, ...deps };
+    this.route = Object.freeze({ agentId: start.agentId, line: start.line, from: start.from, callId: start.callId, generation: randomUUID() });
+    const out: Playback['send'] = (opus, timestamp, marker) => {
+      if (this.over || this.peer === null) return Promise.reject(new Error('call audio is not connected'));
+      return this.peer.sendOpus(opus, timestamp, marker);
+    };
+    const ended = (reason: string): void => {
+      this.hangUp(reason);
+    };
+    this.talk = this.deps.shared(cfg, out, ended, (text, sourceId) => {
+      if (!this.over) this.deps.heard(this.route, text, sourceId);
+    });
+    this.longest = setTimeout(() => {
+      this.hangUp('the call reached one hour');
+    }, LONGEST_CALL_MS);
+  }
+
+  async begin(): Promise<void> {
+    if (this.over || this.begun) return;
+    this.begun = true;
+    log.info({ line: this.start.line, callId: this.start.callId }, 'voice: answering a call');
+    if (!this.deps.open(this.route, this.start.sourceId, this.talk)) throw new Error('the shared conversation is unavailable');
+    await this.signal({ kind: 'join', callId: this.start.callId, from: this.selfPeer });
+    if (this.over) {
+      await this.sendLeave();
+      return;
+    }
+    if (this.peer === null) this.timer = setTimeout(() => {
+      this.hangUp('no offer arrived');
+    }, OFFER_WAIT_MS);
+  }
+
+  signalled(raw: Record<string, unknown>): void {
+    if (raw.callId !== this.start.callId || this.over) return;
+    const fromCaller = raw.from === this.start.callerPeer;
+    if (raw.kind === 'offer' && fromCaller && raw.to === this.selfPeer && this.peer === null && typeof raw.sdp === 'string')
+      this.answer(this.start.callerPeer, raw.sdp).catch((err: unknown) => {
+        this.hangUp(`answering failed: ${errMsg(err)}`);
+      });
+    else if (raw.kind === 'leave' && fromCaller) this.hangUp('the caller hung up');
+  }
+
+  hangUp(reason: string): void {
+    this.end(reason);
+  }
+
+  leave(reason: string): Promise<void> {
+    this.end(reason);
+    return this.left;
+  }
+
+  private async answer(to: string, offer: string): Promise<void> {
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.peer = this.deps.peer({
+      audio: (opus) => {
+        if (!this.over) this.talk.hear(opus);
+      },
+      state: (state) => {
+        this.stateChanged(state);
+      },
+    });
+    const sdp = await this.peer.answer(offer);
+    if (this.over) return;
+    await this.signal({ kind: 'answer', callId: this.start.callId, from: this.selfPeer, to, sdp });
+  }
+
+  private stateChanged(state: string): void {
+    if (this.over) return;
+    log.info({ state, afterMs: Date.now() - this.startedAt }, 'voice: call connection');
+    if (state === 'connected') this.talk.connect();
+    else if (state === 'failed' || state === 'closed') this.hangUp(`the connection ${state}`);
+  }
+
+  private signal(signal: Record<string, unknown>): Promise<unknown> {
+    return this.deps.train('callSignal', { line: this.start.line, signal });
+  }
+
+  private end(reason: string): void {
+    if (this.over) return;
+    this.over = true;
+    if (this.timer !== null) clearTimeout(this.timer);
+    clearTimeout(this.longest);
+    log.info({ reason, seconds: Math.round((Date.now() - this.startedAt) / 1000) }, 'voice: call over');
+    this.talk.finish();
+    this.peer?.close();
+    this.deps.ended(this.route);
+    this.onOver();
+    this.left = this.sendLeave();
+  }
+
+  private async sendLeave(): Promise<void> {
+    try {
+      await this.leaveOnce();
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'voice: could not send the hang-up, trying once more');
+      await new Promise((r) => setTimeout(r, this.deps.leaveRetryMs));
+      await this.leaveOnce().catch((again: unknown) => {
+        log.warn({ err: errMsg(again) }, 'voice: could not send the hang-up; the next start sends it');
+      });
+    }
+  }
+
+  private async leaveOnce(): Promise<void> {
+    const leave = { kind: 'leave', callId: this.start.callId, from: this.selfPeer };
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const capped = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error('hang-up signal timed out'));
+      }, this.deps.signalWaitMs);
+    });
+    try {
+      await Promise.race([this.signal(leave), capped]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}