agents-city 0.4.0 → 0.5.2

package/plugin/channel/managed-connect/local-cities.ts

@@ -0,0 +1,94 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type LocalCity = {
+  current: boolean;
+  slug: string;
+  id: string;
+  dataDir: string;
+  name: string;
+};
+
+const locatedCitiesScript = [
+  new URL('../scripts/cities.py', import.meta.url),
+  new URL('../../scripts/cities.py', import.meta.url),
+]
+  .map((url) => fileURLToPath(url))
+  .find(existsSync);
+
+if (!locatedCitiesScript) throw new Error('Agents City city catalogue script is missing');
+const citiesScript: string = locatedCitiesScript;
+
+function scalar(input: string, key: string): string {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = input.match(new RegExp(`^${escaped}:[ \\t]*(.+)$`, 'm'));
+  return match?.[1]?.trim().replace(/^['"]|['"]$/g, '') || '';
+}
+
+export function discoverLocalCities(): LocalCity[] {
+  const result = spawnSync('python3', [citiesScript, 'list'], {
+    encoding: 'utf8',
+    env: process.env,
+    maxBuffer: 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || 'could not list local cities');
+  }
+  const cities = result.stdout
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      const [marker, slug, id, rawPath] = line.split('\t');
+      if (!slug || !id || !rawPath) throw new Error('invalid local city catalogue');
+      const dataDir = realpathSync(rawPath);
+      const identity = readFileSync(join(dataDir, 'city.yml'), 'utf8');
+      return {
+        current: marker === '*',
+        slug,
+        id,
+        dataDir,
+        name: scalar(identity, 'name') || basename(dataDir),
+      };
+    });
+  if (new Set(cities.map((city) => city.id)).size !== cities.length) {
+    throw new Error('duplicate local city identity');
+  }
+  return cities;
+}
+
+export function selectLocalCities(
+  cities: LocalCity[],
+  selectors: string[],
+  all: boolean,
+): LocalCity[] {
+  if (all && selectors.length) throw new Error('use either --all or --city, not both');
+  if (all) return cities;
+  if (!selectors.length) {
+    const current = cities.find((city) => city.current) ?? cities[0];
+    if (!current) throw new Error('there is no local city to connect');
+    return [current];
+  }
+  const selected: LocalCity[] = [];
+  for (const raw of selectors) {
+    let real = '';
+    try {
+      real = realpathSync(raw);
+    } catch {}
+    const query = raw.toLowerCase();
+    const matches = cities.filter(
+      (city) =>
+        city.slug.toLowerCase() === query ||
+        city.id.toLowerCase() === query ||
+        city.name.toLowerCase() === query ||
+        basename(city.dataDir).toLowerCase() === query ||
+        (real && city.dataDir === real),
+    );
+    if (matches.length !== 1) {
+      throw new Error(matches.length ? `ambiguous city: ${raw}` : `no local city called ${raw}`);
+    }
+    if (!selected.some((city) => city.id === matches[0].id)) selected.push(matches[0]);
+  }
+  return selected;
+}

package/plugin/channel/managed-connect/person-message.ts

@@ -0,0 +1,74 @@
+export const PERSON_MESSAGE_PROTOCOL = 'agents-city-person-message/1' as const;
+const MAX_PERSON_TEXT_BYTES = 11_500;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+const utf8Length = (value: string) => textEncoder.encode(value).byteLength;
+
+export type PersonMessage = {
+  kind: 'message' | 'rejection';
+  text: string;
+  inReplyTo: string | null;
+};
+
+export function encodePersonMessage(message: PersonMessage): string {
+  validateText(message.text);
+  if (!['message', 'rejection'].includes(message.kind)) {
+    throw new Error('invalid_person_message_kind');
+  }
+  if (message.inReplyTo !== null && !UUID_RE.test(message.inReplyTo)) {
+    throw new Error('invalid_person_reply_reference');
+  }
+  return textDecoder.decode(
+    textEncoder.encode(
+      JSON.stringify({
+        protocol: PERSON_MESSAGE_PROTOCOL,
+        kind: message.kind,
+        text: message.text,
+        ...(message.inReplyTo ? { inReplyTo: message.inReplyTo } : {}),
+      }),
+    ),
+  );
+}
+
+/**
+ * A legacy or deliberately malformed application frame is still harmless
+ * untrusted text. Keep it visible to the human instead of creating an
+ * unacknowledgeable poison message that the relay would retry forever.
+ */
+export function decodePersonMessage(value: string): PersonMessage {
+  validateText(value);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return { kind: 'message', text: value, inReplyTo: null };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { kind: 'message', text: value, inReplyTo: null };
+  }
+  const record = parsed as Record<string, unknown>;
+  const allowed = new Set(['protocol', 'kind', 'text', 'inReplyTo']);
+  if (
+    record.protocol !== PERSON_MESSAGE_PROTOCOL ||
+    !['message', 'rejection'].includes(String(record.kind)) ||
+    typeof record.text !== 'string' ||
+    !record.text.trim() ||
+    utf8Length(record.text) > MAX_PERSON_TEXT_BYTES ||
+    (record.inReplyTo !== undefined &&
+      (typeof record.inReplyTo !== 'string' || !UUID_RE.test(record.inReplyTo))) ||
+    Object.keys(record).some((key) => !allowed.has(key))
+  ) {
+    return { kind: 'message', text: value, inReplyTo: null };
+  }
+  return {
+    kind: record.kind as PersonMessage['kind'],
+    text: record.text,
+    inReplyTo: typeof record.inReplyTo === 'string' ? record.inReplyTo : null,
+  };
+}
+
+function validateText(value: string): void {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('person_message_required');
+  if (utf8Length(value) > MAX_PERSON_TEXT_BYTES) throw new Error('person_message_too_large');
+}

package/plugin/channel/managed-connect/reception-bridge.ts

@@ -0,0 +1,341 @@
+import {
+  closeSync,
+  existsSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import type WebSocket from 'ws';
+import type { CityContext } from '../city-config.js';
+import { BUS_PROTOCOL, type BusEnvelope } from '../protocol.js';
+import {
+  markReceptionOutboxFailed,
+  markReceptionOutboxSent,
+  pendingReceptionOutbox,
+  recordReceptionMessage,
+  syncReceptionConnections,
+} from '../reception.js';
+import { listDeviceRoads, type DeviceIdentity, type DeviceRoad } from './device.js';
+import { decodePersonMessage, encodePersonMessage } from './person-message.js';
+import type { ManagedRelaySession, UntrustedRoadText } from './relay-session.js';
+import {
+  connectStateDirectory,
+  loadConnectIdentity,
+  readConnectState,
+  refreshStoredTransparency,
+  type ConnectedConnectState,
+} from './storage.js';
+import { openManagedRelaySession } from './transport.js';
+
+const RETRY_START_MS = 1_000;
+const RETRY_MAX_MS = 30_000;
+const DIRECTORY_REFRESH_MS = 30_000;
+const OUTBOX_INTERVAL_MS = 250;
+
+export function managedReceptionBridge(context: Pick<CityContext, 'appHome'>) {
+  let releaseLease: (() => void) | null = null;
+  let session: ManagedRelaySession | null = null;
+  let socket: WebSocket | null = null;
+  let stopped = false;
+  let connecting = false;
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  let refreshTimer: ReturnType<typeof setInterval> | null = null;
+  let outboxTimer: ReturnType<typeof setInterval> | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+  let backoff = RETRY_START_MS;
+  let draining = false;
+  let metadata = new Map<string, DeviceRoad>();
+  let identity: DeviceIdentity | null = null;
+
+  const debug = (message: string) => {
+    if (process.env.CITY_BUS_DEBUG === '1') console.error(`[reception] ${message}`);
+  };
+
+  const schedule = (delay = backoff): void => {
+    if (stopped || retryTimer) return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void connect();
+    }, delay);
+    retryTimer.unref();
+    backoff = Math.min(RETRY_MAX_MS, Math.max(RETRY_START_MS, backoff * 2));
+  };
+
+  const clearConnection = (): void => {
+    if (heartbeat) clearInterval(heartbeat);
+    heartbeat = null;
+    session = null;
+    socket = null;
+    connecting = false;
+  };
+
+  const identityFor = async (state: ConnectedConnectState) => {
+    if (identity?.deviceId === state.device.deviceId) return identity;
+    identity = await loadConnectIdentity(state, context.appHome);
+    return identity;
+  };
+
+  const refreshDirectory = async (): Promise<DeviceRoad[]> => {
+    const state = readConnectState(context.appHome);
+    if (!state || state.status !== 'connected') return [];
+    const activeIdentity = await identityFor(state);
+    const endpoint = receptionEndpoint(activeIdentity.ownerPrefix, activeIdentity.deviceId);
+    const directory = await listDeviceRoads(state.serviceUrl, activeIdentity);
+    const roads = directory.roads.filter(
+      (road) =>
+        road.kind === 'connection' && Boolean(road.connectionId) && road.localCity === endpoint,
+    );
+    metadata = new Map(roads.map((road) => [road.id, road]));
+    syncReceptionConnections(
+      context.appHome,
+      roads.map((road) => ({
+        roadId: road.id,
+        connectionId: road.connectionId!,
+        peerName: road.peerName,
+        peerEndpoint: road.peerCity,
+      })),
+    );
+    return roads;
+  };
+
+  const connect = async (): Promise<void> => {
+    if (stopped || connecting || session) return;
+    const state = readConnectState(context.appHome);
+    if (!state || state.status !== 'connected') return schedule(DIRECTORY_REFRESH_MS);
+    if (!releaseLease) {
+      releaseLease = tryAcquireReceptionLease(context.appHome);
+      if (!releaseLease) return schedule(5_000);
+    }
+    connecting = true;
+    try {
+      const refreshed = await refreshStoredTransparency(context.appHome);
+      if (refreshed.state.status !== 'connected') throw new Error('connect_state_not_connected');
+      if (refreshed.refreshWarning) {
+        debug(`${refreshed.refreshWarning}; using unexpired cached root`);
+      }
+      const activeIdentity = await identityFor(refreshed.state);
+      const roads = await refreshDirectory();
+      if (!roads.length) {
+        connecting = false;
+        backoff = RETRY_START_MS;
+        return schedule(DIRECTORY_REFRESH_MS);
+      }
+      const endpoint = receptionEndpoint(activeIdentity.ownerPrefix, activeIdentity.deviceId);
+      const opened = await openManagedRelaySession(activeIdentity, endpoint, {
+        onText: async (message) => {
+          const recorded = recordReceptionMessage(
+            {
+              appHome: context.appHome,
+              city: { id: `device_${activeIdentity.deviceId}`, address: endpoint },
+            },
+            receptionEnvelope(
+              activeIdentity.deviceId,
+              endpoint,
+              message,
+              metadata.get(message.roadId),
+            ),
+          );
+          return {
+            messageId: message.messageId,
+            status: recorded.inserted ? 'inserted' : 'duplicate',
+          };
+        },
+        keyTransparency: refreshed.runtime,
+        onSecurityError: (error) => debug(`security refusal: ${error.message}`),
+        onLocalError: (error) => debug(`local handoff failed: ${error.message}`),
+      });
+      if (stopped) {
+        opened.session.close();
+        return;
+      }
+      session = opened.session;
+      socket = opened.socket;
+      connecting = false;
+      backoff = RETRY_START_MS;
+      opened.socket.once('close', () => {
+        clearConnection();
+        schedule();
+      });
+      heartbeat = setInterval(() => {
+        try {
+          session?.ping();
+        } catch {}
+      }, 30_000);
+      heartbeat.unref();
+      void drainOutbox();
+    } catch (error) {
+      connecting = false;
+      debug(`retry: ${(error as Error).message}`);
+      schedule();
+    }
+  };
+
+  const drainOutbox = async (): Promise<void> => {
+    if (draining || !session) return;
+    draining = true;
+    try {
+      const rows = pendingReceptionOutbox(context.appHome);
+      await Promise.all(
+        rows.map(async (row) => {
+          try {
+            const active = session;
+            if (!active || !metadata.has(row.roadId)) throw new Error('connection_not_available');
+            await active.sendRoadText(
+              row.roadId,
+              encodePersonMessage({
+                kind: row.kind,
+                text: row.body,
+                inReplyTo: row.inReplyTo,
+              }),
+              {
+                messageId: row.messageId,
+                onAccepted: () => {
+                  markReceptionOutboxSent(context.appHome, row.messageId);
+                },
+              },
+            );
+          } catch (error) {
+            markReceptionOutboxFailed(context.appHome, row.messageId, row.attemptCount, error);
+          }
+        }),
+      );
+    } finally {
+      draining = false;
+    }
+  };
+
+  return {
+    start: () => {
+      void connect();
+      refreshTimer = setInterval(() => {
+        if (!releaseLease) {
+          void connect();
+          return;
+        }
+        void refreshDirectory()
+          .then((roads) => {
+            if (roads.length && !session) void connect();
+          })
+          .catch((error) => debug(`directory refresh failed: ${(error as Error).message}`));
+      }, DIRECTORY_REFRESH_MS);
+      refreshTimer.unref();
+      outboxTimer = setInterval(() => void drainOutbox(), OUTBOX_INTERVAL_MS);
+      outboxTimer.unref();
+    },
+    close: () => {
+      stopped = true;
+      if (retryTimer) clearTimeout(retryTimer);
+      if (refreshTimer) clearInterval(refreshTimer);
+      if (outboxTimer) clearInterval(outboxTimer);
+      if (heartbeat) clearInterval(heartbeat);
+      retryTimer = null;
+      refreshTimer = null;
+      outboxTimer = null;
+      heartbeat = null;
+      try {
+        session?.close();
+      } catch {}
+      try {
+        socket?.close();
+      } catch {}
+      clearConnection();
+      releaseLease?.();
+      releaseLease = null;
+    },
+  };
+}
+
+function receptionEndpoint(ownerPrefix: string, deviceId: string): string {
+  return `${ownerPrefix}/rx-${deviceId.replaceAll('-', '').slice(0, 12)}`;
+}
+
+function receptionEnvelope(
+  deviceId: string,
+  endpoint: string,
+  message: UntrustedRoadText,
+  road: DeviceRoad | undefined,
+): BusEnvelope {
+  if (!road?.connectionId || road.kind !== 'connection') {
+    throw new Error('unknown_connection_road');
+  }
+  const person = decodePersonMessage(message.text);
+  return {
+    protocol: BUS_PROTOCOL,
+    id: `managed_${message.messageId.replaceAll('-', '')}`,
+    kind: 'road.message',
+    scope: 'road',
+    thread: null,
+    from: { city: message.from, actor: 'seat', role: 'external-seat' },
+    to: { city: endpoint, actor: 'seat' },
+    createdAt: new Date().toISOString(),
+    payload: {
+      text: person.text,
+      trust: 'information-not-authority',
+      transport: 'managed-e2ee',
+      messageKind: person.kind,
+      inReplyTo: person.inReplyTo,
+      sourceName: road.peerName,
+      connectionId: road.connectionId,
+      roadId: road.id,
+      remoteMessageId: message.messageId,
+      receiverDeviceId: deviceId,
+    },
+  };
+}
+
+function tryAcquireReceptionLease(appHome: string): (() => void) | null {
+  const lock = join(connectStateDirectory(appHome), 'reception.lock');
+  const owner = process.pid;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = openSync(lock, 'wx', 0o600);
+      try {
+        writeFileSync(fd, `${owner}\n`);
+      } finally {
+        closeSync(fd);
+      }
+      return () => {
+        if (lockOwner(lock) !== owner) return;
+        try {
+          unlinkSync(lock);
+        } catch {}
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      const info = lstatSync(lock);
+      if (!info.isFile() || info.isSymbolicLink()) throw new Error('unsafe_reception_lock');
+      const old = lockOwner(lock);
+      if ((old > 0 && processAlive(old)) || (!old && Date.now() - statSync(lock).mtimeMs < 5_000)) {
+        return null;
+      }
+      try {
+        unlinkSync(lock);
+      } catch (unlinkError) {
+        if ((unlinkError as NodeJS.ErrnoException).code !== 'ENOENT') throw unlinkError;
+      }
+    }
+  }
+  return null;
+}
+
+function lockOwner(path: string): number {
+  if (!existsSync(path)) return 0;
+  try {
+    return Number(readFileSync(path, 'utf8').trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/plugin/channel/managed-connect/relay-session.ts

@@ -0,0 +1,7 @@
+export {
+  ManagedRelaySession,
+  type RelaySessionOptions,
+  type RelayTransport,
+  type RoadInboxReceipt,
+  type UntrustedRoadText,
+} from '../managed-connect-client.js';