@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

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

@@ -0,0 +1,156 @@
+import { randomUUID } from 'node:crypto';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { TrainEvent } from '@metro-labs/core/trains/protocol';
+import { agentIdForLine, allowlistForLine, lineReceives, mayApprove, senderPermitted } from '../agents/map.js';
+import { Call, trainCall, type CallStart } from './call.js';
+import { readVoice, voiceReady, type VoiceConfig } from './store.js';
+
+const RING_MS = 40_000;
+const CALL_TYPES = new Set(['callInvite', 'callSignal']);
+const SHUTDOWN_LEAVE_MS = 2_000;
+const SWEEP_FIRST_MS = 5_000;
+const SWEEP_EVERY_MS = 10_000;
+const SWEEP_TRIES = 12;
+
+type CallHandle = Pick<Call, 'start' | 'begin' | 'hangUp' | 'leave' | 'signalled'>;
+type MakeCall = (start: CallStart, cfg: VoiceConfig, onOver: () => void) => CallHandle;
+
+let current: CallHandle | null = null;
+const invites = new Set<string>();
+const INVITES_MAX = 256;
+const makeCall: MakeCall = (start, cfg, onOver) => new Call(start, cfg, onOver);
+
+const record = (value: unknown): Record<string, unknown> => (isRecord(value) ? value : {});
+const str = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+const contentTypeOf = (env: TrainEvent): string => str(record(env.payload).contentType);
+const sourceIdOf = (env: TrainEvent): string => str(env.message_id) || str(env.id) || randomUUID();
+const callerNameOf = (env: TrainEvent): string => str(env.from_display_name) || str(env.from_name) || 'the caller';
+
+export const isCallEvent = (env: TrainEvent): boolean => CALL_TYPES.has(contentTypeOf(env));
+
+const sameCaller = (call: CallHandle, line: string, from: string): boolean => call.start.line === line && call.start.from === from;
+
+function refusal(line: string, from: string): string | null {
+  if (current !== null && !sameCaller(current, line, from)) return 'already in a call';
+  if (!voiceReady(readVoice())) return 'voice is off or has no API key on the Voice page';
+  if (!lineReceives(line) || !mayApprove(line, from) || !senderPermitted(allowlistForLine(line), from)) return 'the caller is not someone who can approve for this channel';
+  if (agentIdForLine(line) === undefined) return 'the channel does not belong to this agent';
+  return null;
+}
+
+function decline(line: string, callId: string): void {
+  trainCall('callSignal', { line, signal: { kind: 'decline', callId } }).catch((err: unknown) => {
+    log.warn({ line, err: errMsg(err) }, 'voice: could not decline a call');
+  });
+}
+
+function ringing(env: TrainEvent): boolean {
+  const sent = Date.parse(str(env.ts));
+  const age = Date.now() - sent;
+  return Number.isFinite(age) && age >= -5_000 && age < RING_MS;
+}
+
+function invite(env: TrainEvent, body: Record<string, unknown>, create: MakeCall): void {
+  const line = str(env.line);
+  const from = str(env.from);
+  const callId = str(body.callId);
+  const callerPeer = str(body.from);
+  const key = JSON.stringify([line, from, callId]);
+  if (callId === '' || callerPeer === '' || invites.has(key)) return;
+  if (!ringing(env)) {
+    log.info({ line }, 'voice: an invite came in after the caller stopped ringing, not answered');
+    return;
+  }
+  const refused = refusal(line, from);
+  if (refused !== null) {
+    log.info({ line, reason: refused }, 'voice: a call came in and is declined');
+    decline(line, callId);
+    return;
+  }
+  const agentId = agentIdForLine(line);
+  if (agentId === undefined) return;
+  invites.add(key);
+  if (invites.size > INVITES_MAX) invites.delete(invites.values().next().value ?? '');
+  current?.hangUp('the caller started a new call');
+  const callerName = callerNameOf(env);
+  const sourceId = sourceIdOf(env);
+  const start = { agentId, sourceId, line, lineName: str(env.line_name), direct: env.is_private === true, from, callerName, callId, callerPeer };
+  const call = create(start, readVoice(), () => {
+    if (current === call) current = null;
+  });
+  current = call;
+  call.begin().catch((err: unknown) => {
+    call.hangUp(`starting failed: ${errMsg(err)}`);
+  });
+}
+
+function authenticated(env: TrainEvent): boolean {
+  if (env.sender_verified === false || (env.station !== undefined && env.station !== 'xmtp')) return false;
+  const line = str(env.line);
+  const match = /^metro:\/\/xmtp\/([^/]+)\/[^/]+$/.exec(line);
+  return match !== null && str(env.from).startsWith(`metro://xmtp/${String(match[1])}/user/`) && str(env.from).split('/').length === 6;
+}
+
+export function onCallEvent(env: TrainEvent, train = 'xmtp', create: MakeCall = makeCall): void {
+  if (train !== 'xmtp' || !authenticated(env)) return;
+  const body = record(record(env.payload).call);
+  if (contentTypeOf(env) === 'callInvite') invite(env, body, create);
+  else if (contentTypeOf(env) === 'callSignal' && current !== null && sameCaller(current, str(env.line), str(env.from)))
+    current.signalled(body);
+}
+
+export function leaveCallsForShutdown(): Promise<void> {
+  if (current === null) return Promise.resolve();
+  const leaving = current.leave('Metro stopped or restarted');
+  const capped = new Promise<void>((resolve) => {
+    setTimeout(resolve, SHUTDOWN_LEAVE_MS).unref();
+  });
+  return Promise.race([leaving, capped]);
+}
+
+interface Leftover {
+  line: string;
+  callId: string;
+  peer: string;
+}
+
+function leftoversOf(result: unknown): Leftover[] {
+  const rows = isRecord(result) && Array.isArray(result.calls) ? result.calls : [];
+  return rows
+    .map((row) => record(row))
+    .map((row) => ({ line: str(row.line), callId: str(row.callId), peer: str(row.peer) }))
+    .filter((row) => row.line !== '' && row.callId !== '' && row.peer !== '');
+}
+
+export async function leaveLeftoverCalls(): Promise<number> {
+  const leftovers = leftoversOf(await trainCall('callLeftovers', {}));
+  let left = 0;
+  for (const { line, callId, peer } of leftovers) {
+    if (current?.start.callId === callId) continue;
+    try {
+      await trainCall('callSignal', { line, signal: { kind: 'leave', callId, from: peer } });
+      log.info({ line, callId }, 'voice: left a call this box was still in');
+      left += 1;
+    } catch (err) {
+      log.warn({ line, err: errMsg(err) }, 'voice: could not leave a call this box was still in');
+    }
+  }
+  return left;
+}
+
+function sweep(tries: number, delayMs: number): void {
+  setTimeout(() => {
+    leaveLeftoverCalls().catch((err: unknown) => {
+      const reason = errMsg(err);
+      if (reason.startsWith('no train named')) return;
+      if (tries > 1) sweep(tries - 1, SWEEP_EVERY_MS);
+      else log.warn({ err: reason }, 'voice: could not check for calls left open');
+    });
+  }, delayMs).unref();
+}
+
+export function sweepLeftoverCalls(): void {
+  sweep(SWEEP_TRIES, SWEEP_FIRST_MS);
+}

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

@@ -0,0 +1,85 @@
+import { RTCPeerConnection, RtpHeader, RtpPacket, type RTCDataChannel, type RTCRtpSender } from 'werift';
+import { errMsg, log } from '@metro-labs/core/log';
+
+const ICE_SERVERS = [{ urls: 'stun:stun.cloudflare.com:3478' }, { urls: 'stun:stun.l.google.com:19302' }];
+const UDP_PORTS: [number, number] = [40_000, 40_100];
+const GATHER_MS = 2_500;
+const OPUS_PT = 111;
+const MEDIA = JSON.stringify({ audio: true, video: false, screen: false });
+
+export interface PeerEvents {
+  audio(opus: Buffer): void;
+  state(state: string): void;
+}
+
+function gathered(pc: RTCPeerConnection): Promise<void> {
+  if (pc.iceGatheringState === 'complete') return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, GATHER_MS);
+    pc.iceGatheringStateChange.subscribe((state) => {
+      if (state !== 'complete') return;
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+export class Peer {
+  private readonly pc = new RTCPeerConnection({
+    iceServers: ICE_SERVERS,
+    bundlePolicy: 'max-bundle',
+    icePortRange: UDP_PORTS,
+    iceUseIpv6: false,
+  });
+  private readonly channel: RTCDataChannel;
+  private sender: RTCRtpSender | null = null;
+  private sequence = Math.floor(Math.random() * 0xffff);
+  private closed = false;
+
+  constructor(private readonly events: PeerEvents) {
+    this.channel = this.pc.createDataChannel('media', { negotiated: true, id: 0 });
+    this.channel.stateChanged.subscribe((state) => {
+      if (state === 'open') this.channel.send(MEDIA);
+    });
+    this.pc.onTrack.subscribe((track) => {
+      if (track.kind === 'audio')
+        track.onReceiveRtp.subscribe((rtp) => {
+          if (!this.closed) this.events.audio(rtp.payload);
+        });
+    });
+    this.pc.connectionStateChange.subscribe((state) => {
+      if (!this.closed) this.events.state(state);
+    });
+  }
+
+  async answer(offer: string): Promise<string> {
+    await this.pc.setRemoteDescription({ type: 'offer', sdp: offer });
+    for (const transceiver of this.pc.getTransceivers()) {
+      if (transceiver.kind === 'audio') {
+        transceiver.setDirection('sendrecv');
+        this.sender = transceiver.sender;
+      } else transceiver.setDirection('inactive');
+    }
+    await this.pc.setLocalDescription(await this.pc.createAnswer());
+    await gathered(this.pc);
+    const sdp = this.pc.localDescription?.sdp;
+    if (sdp === undefined) throw new Error('no local description after the answer');
+    return sdp;
+  }
+
+  sendOpus(payload: Buffer, timestamp: number, marker: boolean): Promise<void> {
+    const sender = this.sender;
+    if (this.closed || sender === null) return Promise.reject(new Error('call audio transport is closed'));
+    this.sequence = (this.sequence + 1) & 0xffff;
+    const header = new RtpHeader({ payloadType: OPUS_PT, sequenceNumber: this.sequence, timestamp, marker });
+    return sender.sendRtp(new RtpPacket(header, payload));
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.pc.close().catch((err: unknown) => {
+      log.debug({ err: errMsg(err) }, 'voice: closing the call connection failed');
+    });
+  }
+}

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

@@ -0,0 +1,115 @@
+import WebSocket from 'ws';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { bytesOf } from './audio.js';
+
+export const elevenLabs = (): string => process.env.METRO_ELEVENLABS_URL ?? 'wss://api.elevenlabs.io';
+const STT_RATE = 16_000;
+const CHUNK_SAMPLES = STT_RATE / 10;
+const HELD_SAMPLES = STT_RATE * 2;
+export const VAD_SILENCE_SECS = 0.5;
+
+export interface Heard {
+  partial(text: string): void;
+  committed(text: string): void;
+  failed(reason: string): void;
+}
+
+const FATAL = new Set([
+  'auth_error',
+  'quota_exceeded',
+  'unaccepted_terms',
+  'rate_limited',
+  'resource_exhausted',
+  'session_time_limit_exceeded',
+  'error',
+]);
+
+export function wsText(data: WebSocket.RawData): string {
+  if (Array.isArray(data)) return Buffer.concat(data).toString('utf8');
+  return (Buffer.isBuffer(data) ? data : Buffer.from(data)).toString('utf8');
+}
+
+export function parsed(raw: string): Record<string, unknown> {
+  try {
+    const msg: unknown = JSON.parse(raw);
+    return isRecord(msg) ? msg : {};
+  } catch {
+    return {};
+  }
+}
+
+export function sttUrl(language: string | null): string {
+  const query = new URLSearchParams({
+    model_id: 'scribe_v2_realtime',
+    audio_format: 'pcm_16000',
+    commit_strategy: 'vad',
+    vad_silence_threshold_secs: String(VAD_SILENCE_SECS),
+  });
+  if (language !== null) query.set('language_code', language);
+  return `${elevenLabs()}/v1/speech-to-text/realtime?${query.toString()}`;
+}
+
+export class Scribe {
+  private readonly ws: WebSocket;
+  private buffer: Int16Array[] = [];
+  private buffered = 0;
+  private closed = false;
+
+  constructor(apiKey: string, language: string | null, private readonly heard: Heard) {
+    this.ws = new WebSocket(sttUrl(language), { headers: { 'xi-api-key': apiKey } });
+    this.ws.on('message', (data) => {
+      this.onMessage(wsText(data));
+    });
+    this.ws.on('error', (err) => {
+      if (this.closed) return;
+      log.warn({ err: errMsg(err) }, 'voice: speech to text connection error');
+    });
+    this.ws.on('close', (code) => {
+      if (this.closed) return;
+      this.closed = true;
+      this.buffer = [];
+      this.buffered = 0;
+      this.heard.failed(`speech to text closed (${String(code)})`);
+    });
+  }
+
+  send(pcm16k: Int16Array): void {
+    if (this.closed) return;
+    this.buffer.push(pcm16k);
+    this.buffered += pcm16k.length;
+    while (this.buffered > HELD_SAMPLES) this.buffered -= this.buffer.shift()?.length ?? this.buffered;
+    if (this.buffered < CHUNK_SAMPLES || this.ws.readyState !== WebSocket.OPEN) return;
+    const chunk = new Int16Array(this.buffered);
+    let at = 0;
+    for (const part of this.buffer) {
+      chunk.set(part, at);
+      at += part.length;
+    }
+    this.buffer = [];
+    this.buffered = 0;
+    this.ws.send(
+      JSON.stringify({ message_type: 'input_audio_chunk', audio_base_64: bytesOf(chunk).toString('base64'), commit: false, sample_rate: STT_RATE }),
+    );
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.buffer = [];
+    this.buffered = 0;
+    this.ws.terminate();
+  }
+
+  private onMessage(raw: string): void {
+    if (this.closed) return;
+    const msg = parsed(raw);
+    const type = typeof msg.message_type === 'string' ? msg.message_type : '';
+    const text = typeof msg.text === 'string' ? msg.text.trim() : '';
+    if (type === 'partial_transcript') this.heard.partial(text);
+    else if (type === 'committed_transcript') {
+      if (text !== '') this.heard.committed(text);
+    } else if (FATAL.has(type)) this.heard.failed(`speech to text: ${typeof msg.error === 'string' ? msg.error : type}`);
+    else log.debug({ type }, 'voice: speech to text said');
+  }
+}

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

@@ -0,0 +1,85 @@
+import { randomUUID } from 'node:crypto';
+import { downsample3, OpusIn, type Playback } from './audio.js';
+import { Scribe, type Heard } from './scribe.js';
+import type { SharedCallTransport, SharedSpeechAction } from './shared.js';
+import { SpeechQueue } from './speech-queue.js';
+import { languageOf, type VoiceConfig } from './store.js';
+
+const BARGE_MIN_WORDS = 2;
+const wordsIn = (text: string): number => text.split(/\s+/).filter((word) => /\p{L}/u.test(word)).length;
+
+type MakeScribe = (heard: Heard) => Pick<Scribe, 'send' | 'close'>;
+
+export class SharedTalk implements SharedCallTransport {
+  private readonly opus = new OpusIn();
+  private readonly scribe: Pick<Scribe, 'send' | 'close'>;
+  private readonly speech: SpeechQueue;
+  private closed = false;
+
+  constructor(
+    cfg: VoiceConfig,
+    send: Playback['send'],
+    private readonly ended: (reason: string) => void,
+    heard: (text: string, sourceId: string) => void,
+    makeScribe: MakeScribe = (events) => new Scribe(cfg.apiKey, languageOf(cfg), events),
+    speech = new SpeechQueue(cfg, send),
+  ) {
+    this.speech = speech;
+    this.speech.whenFailed(() => {
+      this.stop('speech is unavailable');
+    });
+    this.scribe = makeScribe({
+      partial: (text) => {
+        this.barge(text);
+      },
+      committed: (text) => {
+        if (this.closed || text.trim() === '') return;
+        this.barge(text);
+        heard(text, randomUUID());
+      },
+      failed: (reason) => {
+        if (!this.closed) ended(reason);
+      },
+    });
+  }
+
+  enqueue(action: SharedSpeechAction): boolean {
+    return !this.closed && this.speech.enqueue(action);
+  }
+
+  cancel(): void {
+    this.speech.cancel();
+  }
+
+  terminate(): void {
+    this.stop('the shared conversation ended');
+  }
+
+  connect(): void {
+    if (!this.closed) this.speech.connect();
+  }
+
+  hear(packet: Buffer): void {
+    if (this.closed) return;
+    const pcm = this.opus.decode(packet);
+    if (pcm !== null) this.scribe.send(downsample3(pcm));
+  }
+
+  finish(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.speech.close();
+    this.scribe.close();
+    this.opus.close();
+  }
+
+  private stop(reason: string): void {
+    if (this.closed) return;
+    this.finish();
+    this.ended(reason);
+  }
+
+  private barge(text: string): void {
+    if (!this.closed && this.speech.busy && wordsIn(text) >= BARGE_MIN_WORDS) this.speech.cancel();
+  }
+}

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

@@ -0,0 +1,200 @@
+import { randomUUID } from 'node:crypto';
+import { sameCall, type CallNotice, type CallRoute, type CallSource, type SpeechStatus, type SpeechTarget } from '@metro-labs/core/call';
+import { str } from '@metro-labs/core/str';
+import { log } from '@metro-labs/core/log';
+import { agentIdForLine, allowlistForLine, lineReceives, mayApprove, senderPermitted, accountFromLine } from '../agents/map.js';
+import { eventInScope } from '../agents/scope.js';
+import { harnessRunner } from '../claude/runner.js';
+import { policyFor, type Access } from '../policy/policy.js';
+
+export interface SharedSpeechAction {
+  actionId: string;
+  text: string;
+  isValid(): boolean;
+  status(status: SpeechStatus): void;
+}
+
+export interface SharedCallTransport {
+  enqueue(action: SharedSpeechAction): boolean;
+  terminate(): void;
+}
+
+export interface SpeechReceipt {
+  actionId: string;
+  sourceId: string;
+  status: SpeechStatus;
+  duplicate: boolean;
+}
+
+interface Action extends SpeechReceipt {
+  text: string;
+}
+
+interface Active {
+  route: CallRoute;
+  at: number;
+  transport: SharedCallTransport;
+  sources: Set<string>;
+  actions: Map<string, Action>;
+}
+
+export interface SharedCallBridge {
+  available(route: CallRoute): boolean;
+  notify(notice: CallNotice): boolean;
+  revoked(route: CallRoute): void;
+}
+
+const SOURCES_MAX = 1024;
+const TEXT_MAX = 32_000;
+const sourceValid = (sourceId: string): boolean => sourceId.length > 0 && sourceId.length <= 2048;
+
+const authorized = (route: CallRoute): boolean =>
+  agentIdForLine(route.line) === route.agentId && eventInScope(new Set([route.agentId]), route.line) && lineReceives(route.line) &&
+  mayApprove(route.line, route.from) && senderPermitted(allowlistForLine(route.line), route.from);
+
+function access(route: CallRoute): Access {
+  const account = accountFromLine(route.line);
+  return account === undefined ? 'deny' : policyFor({ kind: 'channel', station: account.station, account: account.accountId }, { name: 'send', group: 'write' });
+}
+
+export class SharedCalls {
+  private active: Active | null = null;
+  private bridge: SharedCallBridge | null = null;
+
+  constructor(private readonly permitted = authorized, private readonly policy = access) {}
+
+  connect(bridge: SharedCallBridge): void {
+    this.disconnect();
+    this.bridge = bridge;
+  }
+
+  disconnect(): void {
+    this.revoke();
+    this.bridge = null;
+  }
+
+  revoke(): void {
+    const active = this.active;
+    if (active !== null) this.end(active.route);
+  }
+
+  open(route: CallRoute, sourceId: string, transport: SharedCallTransport): boolean {
+    if (!this.permitted(route) || this.bridge?.available(route) !== true || !sourceValid(sourceId)) return false;
+    if (this.active !== null && sameCall(this.active.route, route)) return this.active.transport === transport && this.active.sources.has(sourceId);
+    if (this.active !== null) this.end(this.active.route);
+    this.active = { route, at: Date.now(), transport, sources: new Set([sourceId]), actions: new Map() };
+    if (this.bridge.notify({ type: 'started', route, sourceId })) return true;
+    this.end(route);
+    return false;
+  }
+
+  snapshot(): CallRoute | null {
+    const route = this.active?.route;
+    return route !== undefined && this.current(route) !== null ? route : null;
+  }
+
+  valid(source: CallSource): boolean {
+    return this.current(source.route)?.sources.has(source.sourceId) === true;
+  }
+
+  private current(route: CallRoute): Active | null {
+    const active = this.active;
+    return active !== null && sameCall(active.route, route) && this.permitted(route) && this.bridge?.available(route) === true ? active : null;
+  }
+
+  heard(route: CallRoute, text: string, sourceId: string): void {
+    if (text.trim() === '' || text.length > TEXT_MAX || !this.addSource(route, sourceId)) return;
+    if (this.bridge?.notify({ type: 'heard', route, text, sourceId }) !== true) this.end(route);
+  }
+
+  chat(event: Record<string, unknown>, scope: Set<string>): Record<string, string> {
+    const active = this.active;
+    if (active === null || event.senderVerified === false || !scope.has(active.route.agentId)) return {};
+    const { route } = active;
+    if (event.line !== route.line || event.from !== route.from || Date.parse(str(event.ts)) < active.at || !Number.isFinite(Date.parse(str(event.ts)))) return {};
+    const sourceId = str(event.messageId);
+    if (!this.addSource(route, sourceId, true)) return {};
+    return { call_id: route.callId, call_generation: route.generation, call_source_id: sourceId };
+  }
+
+  bindChat(event: Record<string, unknown>, scope: Set<string>): () => Record<string, string> {
+    const meta = this.chat(event, scope);
+    const route = this.active?.route;
+    const sourceId = meta.call_source_id;
+    return () => route !== undefined && sourceId !== undefined && this.valid({ route, sourceId }) ? meta : {};
+  }
+
+  source(line: string, target: SpeechTarget, scope: Set<string>): CallSource | null {
+    const route = this.active?.route;
+    if (route === undefined || route.line !== line || route.callId !== target.callId || route.generation !== target.generation || !scope.has(route.agentId)) return null;
+    const source = { route, sourceId: target.sourceId };
+    return this.valid(source) ? source : null;
+  }
+
+  speak(line: string, target: SpeechTarget, text: string, scope: Set<string>): SpeechReceipt {
+    const source = this.source(line, target, scope);
+    const active = this.active;
+    if (source === null || active === null) throw new Error('The call or its authorized source has ended or changed. Nothing was spoken.');
+    if (text.trim() === '' || text.length > TEXT_MAX) throw new Error('Call speech needs 1 to 32000 characters of text.');
+    const previous = active.actions.get(source.sourceId);
+    if (previous !== undefined) {
+      if (previous.text !== text) throw new Error('This source already has a different speech action. Nothing was repeated.');
+      return { actionId: previous.actionId, sourceId: previous.sourceId, status: previous.status, duplicate: true };
+    }
+    const accessAtAcceptance = this.policy(source.route);
+    if (accessAtAcceptance === 'deny') throw new Error('The owner blocked sending on this channel.');
+    const action: Action = { actionId: randomUUID(), sourceId: source.sourceId, text, status: 'accepted', duplicate: false };
+    active.actions.set(source.sourceId, action);
+    this.status(source.route, action, 'accepted');
+    const queued = active.transport.enqueue({
+      actionId: action.actionId,
+      text,
+      isValid: () => this.valid(source) && this.policy(source.route) === accessAtAcceptance,
+      status: (status) => { this.status(source.route, action, status); },
+    });
+    if (!queued) this.status(source.route, action, 'failed');
+    else if (action.status === 'accepted') this.status(source.route, action, 'queued');
+    return { actionId: action.actionId, sourceId: action.sourceId, status: action.status, duplicate: false };
+  }
+
+  end(route: CallRoute): void {
+    const active = this.active;
+    if (active === null || !sameCall(active.route, route)) return;
+    this.active = null;
+    this.bridge?.revoked(route);
+    active.transport.terminate();
+    for (const action of active.actions.values())
+      if (!this.terminal(action.status)) this.status(route, action, 'interrupted');
+    this.bridge?.notify({ type: 'ended', route });
+  }
+
+  private addSource(route: CallRoute, sourceId: string, duplicate = false): boolean {
+    const active = this.current(route);
+    if (active === null || !sourceValid(sourceId)) return false;
+    if (active.sources.has(sourceId)) return duplicate;
+    if (active.sources.size >= SOURCES_MAX) {
+      log.warn('sdk-call: the call source limit was reached; ending the call');
+      this.end(route);
+      return false;
+    }
+    active.sources.add(sourceId);
+    return true;
+  }
+
+  private terminal(status: SpeechStatus): boolean {
+    return status === 'completed' || status === 'interrupted' || status === 'failed';
+  }
+
+  private status(route: CallRoute, action: Action, status: SpeechStatus): void {
+    if (this.terminal(action.status) || (status === 'started' && action.status === 'started')) return;
+    action.status = status;
+    log.info({ actionId: action.actionId, status, at: Date.now() }, 'sdk-call: speech action');
+    this.bridge?.notify({ type: 'speech', route, sourceId: action.sourceId, actionId: action.actionId, status });
+  }
+}
+
+export const sharedCalls = new SharedCalls();
+export const sharedCallsSelected = (): boolean => harnessRunner() === 'sdk';
+export const openSharedCall = (route: CallRoute, sourceId: string, transport: SharedCallTransport): boolean => sharedCalls.open(route, sourceId, transport);
+export const hearSharedCall = (route: CallRoute, text: string, sourceId: string): void => { sharedCalls.heard(route, text, sourceId); };
+export const endSharedCall = (route: CallRoute): void => { sharedCalls.end(route); };