agents-city 0.3.0-beta.21

package/plugin/channel/hub/diagnostics.ts

@@ -0,0 +1,67 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { CityContext } from '../city-config.js';
+import { isoNow, randomId } from '../protocol.js';
+
+export interface DiagnosticFields {
+  actor?: string;
+  mode?: string;
+  thread?: string;
+  command?: string;
+  outcome?: string;
+  message?: string;
+  [key: string]: unknown;
+}
+
+/** Append-only, secret-scrubbed diagnostics shared by hub and gateways. */
+export function diagnosticLog(context: CityContext, component: string) {
+  const path = join(context.runtimeDir, 'diagnostics.jsonl');
+  return (event: string, fields: DiagnosticFields = {}): void => {
+    try {
+      mkdirSync(context.runtimeDir, { recursive: true, mode: 0o700 });
+      appendFileSync(
+        path,
+        JSON.stringify({
+          protocol: 'agents-city-diagnostic/1',
+          id: randomId('diagnostic'),
+          at: isoNow(),
+          pid: process.pid,
+          city: context.city.address,
+          component: clean(component, 80),
+          event: clean(event, 120),
+          ...scrub(fields),
+        }) + '\n',
+        { mode: 0o600 },
+      );
+    } catch {
+      // Diagnostics must never take the city down.
+    }
+  };
+}
+
+function scrub(fields: DiagnosticFields): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (/token|secret|authorization|credential/i.test(key)) {
+      out[key] = '[redacted]';
+    } else if (typeof value === 'string') {
+      out[key] = clean(
+        value
+          .replace(/([?&](?:token|secret|key)=)[^&\s]+/gi, '$1[redacted]')
+          .replace(/Bearer\s+\S+/gi, 'Bearer [redacted]')
+          .replace(/(Authorization:\s*)\S+(?:\s+\S+)?/gi, '$1[redacted]')
+          .replace(/(--(?:token|password|secret|api-key)(?:=|\s+))\S+/gi, '$1[redacted]'),
+        2_000,
+      );
+    } else if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function clean(value: unknown, max: number): string {
+  return String(value ?? '')
+    .trim()
+    .slice(0, max);
+}

package/plugin/channel/hub/envelope-validity.ts

@@ -0,0 +1,109 @@
+import { CommitteeFiles } from '../committee/storage.js';
+import { DeliberationState, TERMINAL_STATUSES } from '../committee/types.js';
+import { BusEnvelope } from '../protocol.js';
+
+/**
+ * Decide whether a durable committee delivery still describes actionable
+ * state. This is intentionally used only while draining an offline actor's
+ * outbox: a transition's live notification remains useful even when that same
+ * transition has just advanced the state.
+ */
+export function staleCommitteeEnvelopeReason(files: CommitteeFiles, envelope: BusEnvelope): string {
+  if (envelope.scope !== 'internal' || !envelope.kind.startsWith('committee.')) return '';
+  if (!envelope.thread) return 'committee delivery has no deliberation id';
+
+  let state: DeliberationState;
+  try {
+    state = files.load(envelope.thread);
+  } catch {
+    return 'deliberation state is unavailable';
+  }
+
+  if (TERMINAL_STATUSES.has(state.status)) return `deliberation is ${state.status}`;
+
+  const expected = expectedStatus(envelope.kind);
+  if (expected && !expected.includes(state.status)) {
+    return `delivery belongs to ${expected.join(' or ')}, current state is ${state.status}`;
+  }
+
+  if (envelope.kind === 'committee.assignment' && state.positions[envelope.to.actor]) {
+    return 'participant already submitted a position';
+  }
+  if (envelope.kind === 'committee.position_received') {
+    const deliveredCount = Number(envelope.payload.received);
+    const currentCount = Object.keys(state.positions).length;
+    if (!Number.isInteger(deliveredCount) || deliveredCount !== currentCount) {
+      return `position count advanced from ${deliveredCount || 0} to ${currentCount}`;
+    }
+  }
+  if (envelope.kind === 'committee.positions_ready') {
+    const currentCount = Object.keys(state.positions).length;
+    if (currentCount !== state.brief.participants.length) {
+      return 'the independent-position barrier is no longer complete';
+    }
+  }
+  if (envelope.kind === 'committee.floor.requested') {
+    const request = record(envelope.payload.request);
+    const requestId = String(request.id || '');
+    if (!state.floor.requests.some((item) => item.id === requestId && item.status === 'pending')) {
+      return 'floor request is no longer pending';
+    }
+  }
+  if (envelope.kind === 'committee.floor.granted') {
+    const requestId = String(envelope.payload.requestId || '');
+    if (
+      !state.floor.active ||
+      state.floor.active.requestId !== requestId ||
+      state.floor.active.actor !== envelope.to.actor
+    ) {
+      return 'floor grant is no longer active';
+    }
+  }
+  if (envelope.kind === 'committee.floor.denied') {
+    const requestId = String(envelope.payload.requestId || '');
+    if (!state.floor.requests.some((item) => item.id === requestId && item.status === 'denied')) {
+      return 'floor denial no longer matches the deliberation';
+    }
+  }
+  if (envelope.kind === 'committee.reply.received' || envelope.kind === 'committee.reply.heard') {
+    const reply = record(envelope.payload.reply);
+    const requestId = String(reply.requestId || '');
+    const actor = String(reply.actor || envelope.from.actor || '');
+    if (!state.floor.replies.some((item) => item.requestId === requestId && item.actor === actor)) {
+      return 'floor reply no longer matches the deliberation';
+    }
+  }
+  if (envelope.kind === 'committee.verification.assigned') {
+    const current = state.decisions.at(-1);
+    if (!current || current.verifier !== envelope.to.actor) {
+      return 'verification assignment is no longer current';
+    }
+  }
+
+  return '';
+}
+
+function expectedStatus(kind: string): DeliberationState['status'][] | null {
+  if (kind === 'committee.assignment' || kind === 'committee.position_received') {
+    return ['collecting'];
+  }
+  if (kind === 'committee.positions_ready') return ['review'];
+  if (
+    kind === 'committee.synthesis' ||
+    kind.startsWith('committee.floor.') ||
+    kind === 'committee.reply.received' ||
+    kind === 'committee.reply.heard'
+  ) {
+    return ['deliberating'];
+  }
+  if (kind === 'committee.verification.assigned') return ['verifying'];
+  if (kind === 'committee.verification.passed') return ['verified'];
+  if (kind === 'committee.verification.failed') return ['verification_failed'];
+  return null;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}

package/plugin/channel/hub/envelopes.ts

@@ -0,0 +1,66 @@
+import { ActorRole, BUS_PROTOCOL, BusEnvelope, isoNow, randomId } from '../protocol.js';
+import { CityContext } from '../city-config.js';
+import { acknowledge, enqueueForActor, pendingForActor } from '../delivery-queue.js';
+import { ConnectionRegistry } from './connections.js';
+
+interface EnvelopeRouterOptions {
+  staleReason?: (envelope: BusEnvelope) => string;
+  onDrop?: (envelope: BusEnvelope, reason: string) => void;
+}
+
+export function envelopeRouter(
+  context: CityContext,
+  connections: ConnectionRegistry,
+  options: EnvelopeRouterOptions = {},
+) {
+  const internal = (
+    kind: string,
+    fromActor: string,
+    fromRole: ActorRole,
+    toActor: string,
+    thread: string | null,
+    payload: Record<string, unknown>,
+  ): BusEnvelope => {
+    const envelope: BusEnvelope = {
+      protocol: BUS_PROTOCOL,
+      id: randomId('msg'),
+      kind,
+      scope: 'internal',
+      thread,
+      from: { city: context.city.address, actor: fromActor, role: fromRole },
+      to: { city: context.city.address, actor: toActor },
+      createdAt: isoNow(),
+      payload,
+    };
+    enqueueForActor(context.runtimeDir, envelope);
+    connections.deliver(toActor, envelope);
+    return envelope;
+  };
+
+  const roadInbound = (envelope: BusEnvelope): void => {
+    enqueueForActor(context.runtimeDir, envelope);
+    connections.deliver('seat', envelope);
+  };
+
+  const drain = (actor: string): number => {
+    const pending = pendingForActor(context.runtimeDir, actor);
+    let delivered = 0;
+    for (const envelope of pending) {
+      const reason = options.staleReason?.(envelope) || '';
+      if (reason) {
+        acknowledge(context.runtimeDir, actor, envelope.id);
+        options.onDrop?.(envelope, reason);
+        continue;
+      }
+      if (connections.deliver(actor, envelope)) delivered += 1;
+    }
+    return delivered;
+  };
+
+  const ack = (actor: string, envelopeId: string): boolean =>
+    acknowledge(context.runtimeDir, actor, envelopeId);
+
+  return { internal, roadInbound, drain, ack };
+}
+
+export type EnvelopeRouter = ReturnType<typeof envelopeRouter>;

package/plugin/channel/hub/lifecycle.ts

@@ -0,0 +1,91 @@
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import { CityContext } from '../city-config.js';
+import { HubEndpoint } from '../protocol.js';
+import { atomicJson, endpointPath } from '../runtime-files.js';
+
+export function acquireHub(context: CityContext): () => void {
+  mkdirSync(context.runtimeDir, { recursive: true, mode: 0o700 });
+  const lock = join(context.runtimeDir, 'hub.lock');
+  const owner = process.pid;
+  let acquired = false;
+  for (let attempt = 0; attempt < 2 && !acquired; attempt += 1) {
+    try {
+      const fd = openSync(lock, 'wx', 0o600);
+      try {
+        writeFileSync(fd, String(owner) + '\n');
+      } finally {
+        closeSync(fd);
+      }
+      acquired = true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      const oldPid = lockOwner(lock);
+      if (oldPid > 0) {
+        if (processAlive(oldPid)) {
+          throw new Error(`city bus is already running as pid ${oldPid}`);
+        }
+      } else if (lockIsFresh(lock)) {
+        // Another process may have created the file and not written its PID yet.
+        // Never unlink a fresh, unreadable lock: that was the race that let two
+        // detached hubs survive one concurrent first start.
+        throw new Error('city bus is already starting');
+      }
+      try {
+        unlinkSync(lock);
+      } catch (unlinkError) {
+        if ((unlinkError as NodeJS.ErrnoException).code !== 'ENOENT') throw unlinkError;
+      }
+    }
+  }
+  if (!acquired) throw new Error('could not acquire the city bus lock');
+  return () => {
+    // An old process must never erase a replacement hub's endpoint or lock.
+    if (lockOwner(lock) !== owner) return;
+    const endpoint = endpointPath(context);
+    try {
+      const published = JSON.parse(readFileSync(endpoint, 'utf8')) as HubEndpoint;
+      if (published.pid === owner) unlinkSync(endpoint);
+    } catch {}
+    try {
+      unlinkSync(lock);
+    } catch {}
+  };
+}
+
+function lockOwner(path: string): number {
+  try {
+    return Number(readFileSync(path, 'utf8').trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function lockIsFresh(path: string): boolean {
+  try {
+    return Date.now() - statSync(path).mtimeMs < 5_000;
+  } catch {
+    return false;
+  }
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function publishEndpoint(context: CityContext, endpoint: HubEndpoint): void {
+  atomicJson(endpointPath(context), endpoint);
+}

package/plugin/channel/hub/local-roads.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import WebSocket from 'ws';
+import { CityContext, runtimeDirForCity } from '../city-config.js';
+import { queueRoad } from '../delivery-queue.js';
+import { BusEnvelope, HubEndpoint, Road, randomId } from '../protocol.js';
+
+export async function sendLocalRoad(
+  context: CityContext,
+  road: Road,
+  envelope: BusEnvelope,
+): Promise<string> {
+  const destinationRuntime = runtimeDirForCity(context.appHome, road.id);
+  let endpoint: HubEndpoint;
+  try {
+    endpoint = JSON.parse(
+      readFileSync(join(destinationRuntime, 'endpoint.json'), 'utf8'),
+    ) as HubEndpoint;
+    if (endpoint.cityId !== road.id || endpoint.cityAddress !== road.address)
+      throw new Error('identity mismatch');
+  } catch {
+    queueRoad(destinationRuntime, envelope);
+    return `${road.address} is offline: queued on the local bus`;
+  }
+  try {
+    return await deliver(endpoint, context.city.address, envelope);
+  } catch {
+    queueRoad(destinationRuntime, envelope);
+    return `${road.address} became unavailable: queued on the local bus`;
+  }
+}
+
+export function localRoadOnline(context: CityContext, road: Road): boolean {
+  try {
+    const endpoint = JSON.parse(
+      readFileSync(join(runtimeDirForCity(context.appHome, road.id), 'endpoint.json'), 'utf8'),
+    ) as HubEndpoint;
+    if (endpoint.cityId !== road.id || endpoint.cityAddress !== road.address || endpoint.pid <= 0)
+      return false;
+    process.kill(endpoint.pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function deliver(endpoint: HubEndpoint, from: string, envelope: BusEnvelope): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const url = new URL(endpoint.url);
+    url.searchParams.set('mode', 'road');
+    url.searchParams.set('from', from);
+    url.searchParams.set('token', endpoint.roadToken);
+    const ws = new WebSocket(url);
+    const requestId = randomId('request');
+    const timer = setTimeout(() => finish(new Error('local road timed out')), 5_000);
+    let sent = false;
+    let settled = false;
+
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        ws.close();
+      } catch {}
+      if (error) reject(error);
+      else resolve(`delivered locally to ${endpoint.cityAddress}`);
+    };
+    ws.on('message', (raw) => {
+      let message: Record<string, unknown>;
+      try {
+        message = JSON.parse(String(raw));
+      } catch {
+        return;
+      }
+      if (message.type === 'welcome' && !sent) {
+        sent = true;
+        ws.send(JSON.stringify({ type: 'road.ingress', requestId, envelope }));
+      } else if (message.type === 'result' && message.requestId === requestId) {
+        if (message.ok) finish();
+        else finish(new Error(String(message.error || 'local road refused the message')));
+      }
+    });
+    ws.on('error', () => finish(new Error('local road connection failed')));
+    ws.on('close', () => {
+      if (!sent) finish(new Error('local road closed before delivery'));
+    });
+  });
+}

package/plugin/channel/hub/remote-roads.ts

@@ -0,0 +1,165 @@
+import WebSocket from 'ws';
+import { CityContext } from '../city-config.js';
+import { BUS_PROTOCOL, BusEnvelope, isoNow, randomId } from '../protocol.js';
+
+export function remoteRoadBridge(context: CityContext, receive: (envelope: BusEnvelope) => void) {
+  const base = process.env.CITY_BUS_URL || '';
+  const token = process.env.CITY_BUS_TOKEN || '';
+  const enabled = Boolean(base && token);
+  let ws: WebSocket | null = null;
+  let online = false;
+  let stopped = false;
+  let backoff = 1_000;
+  let roster = new Set<string>();
+  let tail: Promise<string> = Promise.resolve('');
+
+  const connect = (): void => {
+    if (!enabled || stopped) return;
+    const url = new URL('/ws', base);
+    url.protocol = url.protocol.replace(/^http/, 'ws');
+    url.searchParams.set('agent', context.city.address);
+    ws = new WebSocket(url, { headers: { Authorization: `Bearer ${token}` } });
+    ws.on('open', () => {
+      online = true;
+      backoff = 1_000;
+    });
+    ws.on('message', (raw) => handleMessage(String(raw)));
+    ws.on('close', () => {
+      online = false;
+      if (!stopped) {
+        setTimeout(connect, backoff);
+        backoff = Math.min(backoff * 2, 30_000);
+      }
+    });
+    ws.on('error', () => {});
+  };
+
+  const handleMessage = (raw: string): void => {
+    let message: Record<string, unknown>;
+    try {
+      message = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (message.type === 'welcome' || message.type === 'roster') {
+      const entries = (message.roster || message.agents || []) as Array<{ agent?: string }>;
+      roster = new Set(entries.map((entry) => entry.agent || '').filter(Boolean));
+      return;
+    }
+    if (message.type === 'presence') {
+      const address = String(message.agent || '');
+      if (message.status === 'online') roster.add(address);
+      else roster.delete(address);
+      return;
+    }
+    if (message.type !== 'msg') return;
+    const from = String(message.from || '');
+    const road = context.roads.find((candidate) => !candidate.local && candidate.address === from);
+    if (!road) return;
+    const candidate = message.envelope as BusEnvelope | undefined;
+    let envelope: BusEnvelope;
+    if (candidate !== undefined) {
+      if (
+        candidate.protocol !== BUS_PROTOCOL ||
+        candidate.scope !== 'road' ||
+        candidate.from.city !== from ||
+        candidate.from.actor !== 'seat' ||
+        candidate.to.city !== context.city.address ||
+        candidate.to.actor !== 'seat'
+      ) {
+        return;
+      }
+      envelope = candidate;
+    } else {
+      envelope = legacyEnvelope(
+        context,
+        from,
+        String(message.text || ''),
+        String(message.msg_id || randomId('remote')),
+      );
+    }
+    if (envelope.scope === 'road' && envelope.to.city === context.city.address) receive(envelope);
+  };
+
+  const sendRaw = (to: string, envelope: BusEnvelope): Promise<string> =>
+    new Promise((resolve, reject) => {
+      if (!enabled) return reject(new Error('no remote road transport is configured'));
+      if (!online || !ws || ws.readyState !== WebSocket.OPEN) {
+        return reject(new Error('the remote road is not connected'));
+      }
+      const requestId = randomId('remote_request');
+      const onMessage = (raw: WebSocket.RawData): void => {
+        let message: Record<string, unknown>;
+        try {
+          message = JSON.parse(String(raw));
+        } catch {
+          return;
+        }
+        if (!['sent', 'queued', 'error'].includes(String(message.type))) return;
+        if (message.request_id && message.request_id !== requestId) return;
+        cleanup();
+        if (message.type === 'error')
+          reject(new Error(String(message.error || 'remote road refused the message')));
+        else if (message.type === 'queued') resolve(`${to} is offline: queued remotely`);
+        else resolve(`delivered remotely to ${to}`);
+      };
+      const cleanup = (): void => {
+        clearTimeout(timer);
+        ws?.off('message', onMessage);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error('the remote road did not answer in 10s'));
+      }, 10_000);
+      ws.on('message', onMessage);
+      ws.send(
+        JSON.stringify({
+          type: 'send',
+          request_id: requestId,
+          to,
+          text: String(envelope.payload.text || ''),
+          envelope,
+        }),
+      );
+    });
+
+  const send = (to: string, envelope: BusEnvelope): Promise<string> => {
+    const turn = tail.then(
+      () => sendRaw(to, envelope),
+      () => sendRaw(to, envelope),
+    );
+    tail = turn.catch(() => '');
+    return turn;
+  };
+
+  const close = (): void => {
+    stopped = true;
+    try {
+      ws?.close();
+    } catch {}
+  };
+
+  return {
+    start: connect,
+    send,
+    close,
+    enabled: () => enabled,
+    online: (address: string) => roster.has(address),
+  };
+}
+
+function legacyEnvelope(context: CityContext, from: string, body: string, id: string): BusEnvelope {
+  return {
+    protocol: BUS_PROTOCOL,
+    id,
+    kind: 'road.message',
+    scope: 'road',
+    thread: null,
+    from: { city: from, actor: 'seat', role: 'external-seat' },
+    to: { city: context.city.address, actor: 'seat' },
+    createdAt: isoNow(),
+    payload: { text: body, legacy: true },
+  };
+}
+
+export type RemoteRoadBridge = ReturnType<typeof remoteRoadBridge>;

package/plugin/channel/hub/road-controller.ts

@@ -0,0 +1,99 @@
+import { ActorRole, BUS_PROTOCOL, BusEnvelope, isoNow, randomId, text } from '../protocol.js';
+import { CityContext } from '../city-config.js';
+import { recordRoadInbox, takeRoadInbox } from '../delivery-queue.js';
+import { requireChair } from '../committee/guards.js';
+import { wrapUntrusted } from '../untrusted.js';
+import { EnvelopeRouter } from './envelopes.js';
+import { localRoadOnline, sendLocalRoad } from './local-roads.js';
+import { remoteRoadBridge } from './remote-roads.js';
+
+export function roadController(context: CityContext, router: EnvelopeRouter) {
+  const inbound = (envelope: BusEnvelope): void => {
+    const road = context.roads.find((candidate) => candidate.address === envelope.from.city);
+    if (!road) throw new Error(`there is no road from ${envelope.from.city}`);
+    if (
+      envelope.protocol !== BUS_PROTOCOL ||
+      envelope.scope !== 'road' ||
+      envelope.from.actor !== 'seat' ||
+      envelope.to.city !== context.city.address ||
+      envelope.to.actor !== 'seat'
+    ) {
+      throw new Error('invalid road envelope');
+    }
+    // The body is untrusted text from another city: wrap it in an unforgeable
+    // boundary and defang chat-template tokens before it can reach the seat's
+    // context. Done once, here, so every inbound path (local and remote) and
+    // the durable inbox all carry the guarded form. A non-string payload text
+    // is left untouched; only the string body is wrapped.
+    const rawBody = envelope.payload?.text;
+    const guarded =
+      typeof rawBody === 'string'
+        ? {
+            ...envelope,
+            payload: {
+              ...envelope.payload,
+              text: wrapUntrusted(rawBody, envelope.from.city).text,
+              textRaw: undefined,
+            },
+          }
+        : envelope;
+    recordRoadInbox(context.runtimeDir, guarded);
+    router.roadInbound(guarded);
+  };
+  const remote = remoteRoadBridge(context, (envelope) => {
+    try {
+      inbound(envelope);
+    } catch (error) {
+      console.error(`[city-bus] dropped remote envelope: ${(error as Error).message}`);
+    }
+  });
+
+  const sendOne = async (to: string, body: string): Promise<string> => {
+    const road = context.roads.find((candidate) => candidate.address === to);
+    if (!road) throw new Error(`no road from ${context.city.address} to ${to}`);
+    const envelope: BusEnvelope = {
+      protocol: BUS_PROTOCOL,
+      id: randomId('msg'),
+      kind: 'road.message',
+      scope: 'road',
+      thread: null,
+      from: { city: context.city.address, actor: 'seat', role: 'chair' },
+      to: { city: to, actor: 'seat' },
+      createdAt: isoNow(),
+      payload: { text: body, trust: 'information-not-authority' },
+    };
+    return road.local ? sendLocalRoad(context, road, envelope) : remote.send(to, envelope);
+  };
+
+  const command = async (
+    name: string,
+    payload: Record<string, unknown>,
+    actor: string,
+    role: ActorRole,
+  ): Promise<unknown> => {
+    if (name === 'road.roster') {
+      requireChair(actor, role);
+      return context.roads.map((road) => ({
+        ...road,
+        online: road.local ? localRoadOnline(context, road) : remote.online(road.address),
+      }));
+    }
+    if (name === 'road.inbox') {
+      requireChair(actor, role);
+      return takeRoadInbox(context.runtimeDir);
+    }
+    if (name !== 'road.send') throw new Error(`unknown road command: ${name}`);
+    requireChair(actor, role);
+    const to = text(payload.to, 'to');
+    const body = text(payload.text, 'text');
+    if (to !== '*') return { results: [await sendOne(to, body)] };
+    if (!context.roads.length) throw new Error('this city has no roads');
+    const results: string[] = [];
+    for (const road of context.roads) results.push(await sendOne(road.address, body));
+    return { results };
+  };
+
+  return { command, inbound, start: remote.start, close: remote.close };
+}
+
+export type RoadController = ReturnType<typeof roadController>;