agents-city 0.3.0-beta.21

package/bus/scripts/setup-dev.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Configure the optional remote-road transport on this development machine.
+# City identity is deliberately NOT written here: every running seat derives its
+# own owner/city address from the selected city.
+
+set -euo pipefail
+
+BUS_URL="${CITY_BUS_URL:-https://bus.<your-subdomain>.workers.dev}"
+CONF_DIR="$HOME/.claude/channels/city-bus"
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CHANNEL_DIR="$(cd "$REPO_DIR/../plugin/channel" && pwd)"
+
+echo "── Configure remote city roads ─────────────────────────────────"
+echo
+
+if command -v bun >/dev/null 2>&1; then
+  RUNNER=bun
+elif command -v node >/dev/null 2>&1; then
+  RUNNER=node
+else
+  echo "I need node or bun on PATH." >&2
+  exit 1
+fi
+
+echo "→ installing the channel's development dependencies..."
+(cd "$CHANNEL_DIR" && { command -v bun >/dev/null 2>&1 && bun install --silent || npm install --silent; })
+
+read -rp "Owner prefix on the relay (for example alice): " OWNER
+if ! [[ "$OWNER" =~ ^[a-z0-9][a-z0-9_-]{0,31}$ ]]; then
+  echo "Invalid owner: use lowercase letters, digits, dashes or underscores." >&2
+  exit 1
+fi
+
+read -rsp "Paste the token (starts with rb_; it will not be shown): " TOKEN; echo
+if ! [[ "$TOKEN" =~ ^rb_[a-f0-9]{48}$ ]]; then
+  echo "That token does not look right (rb_ followed by 48 hex characters)." >&2
+  exit 1
+fi
+
+mkdir -p "$CONF_DIR"
+umask 077
+cat > "$CONF_DIR/.env" <<EOF
+CITY_BUS_URL=$BUS_URL
+CITY_BUS_TOKEN=$TOKEN
+EOF
+chmod 600 "$CONF_DIR/.env"
+echo "✓ transport settings written without a global city address"
+
+echo "→ checking authentication with the temporary address $OWNER/setup-check..."
+RESULT="$(cd "$CHANNEL_DIR" && CITY_BUS_URL="$BUS_URL" CITY_BUS_TOKEN="$TOKEN" \
+  CITY_BUS_AGENT="$OWNER/setup-check" timeout 20 "$RUNNER" --eval '
+const u = new URL("/ws", process.env.CITY_BUS_URL)
+u.searchParams.set("agent", process.env.CITY_BUS_AGENT)
+u.protocol = u.protocol.replace(/^http/, "ws")
+const WS = globalThis.WebSocket || (await import("ws")).default
+const ws = new WS(u.toString(), { headers: { Authorization: "Bearer " + process.env.CITY_BUS_TOKEN } })
+ws.addEventListener("message", e => { const m = JSON.parse(String(e.data))
+  if (m.type === "welcome") { console.log("OK"); process.exit(0) } })
+ws.addEventListener("close", e => { console.log("FAIL " + e.code + " " + e.reason); process.exit(1) })
+setTimeout(() => { console.log("FAIL timeout"); process.exit(1) }, 15000)
+' 2>&1 | tail -1)"
+
+if [ "$RESULT" = "OK" ]; then
+  echo "✓ the relay accepts this owner prefix"
+else
+  echo "✗ I could not authenticate: $RESULT" >&2
+  exit 1
+fi
+
+cat <<'EOF'
+
+Done. Open a road by exchanging invitations, then start each city seat:
+
+  agents-city road invite <city>
+  agents-city road connect <city> <other.invitation.json>
+  agents-city seat --city <city>
+
+The seat derives owner/city itself. Do not add CITY_BUS_AGENT to the shared .env.
+EOF

package/bus/scripts/test-channel.ts

@@ -0,0 +1,8 @@
+/** Compatibility entrypoint for the canonical local-channel integration test. */
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const test = fileURLToPath(new URL('../../bin/test-channel.py', import.meta.url));
+const result = spawnSync(test, { stdio: 'inherit' });
+
+process.exit(result.status ?? 1);

package/bus/scripts/test-hub.ts

@@ -0,0 +1,266 @@
+import { request as httpRequest } from 'node:http';
+
+const BASE = 'http://127.0.0.1:8799';
+const ALICE = 'tok-alice-test';
+const BOB = 'tok-bob-test';
+
+function open(token: string, agent: string): Promise<{ ws: WebSocket; msgs: any[] }> {
+  return new Promise((resolve, reject) => {
+    const msgs: any[] = [];
+    const ws = new WebSocket(`${BASE.replace('http', 'ws')}/ws?agent=${agent}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    } as any);
+    ws.addEventListener('message', (e) => {
+      try {
+        msgs.push(JSON.parse(String(e.data)));
+      } catch {}
+    });
+    ws.addEventListener('open', () => resolve({ ws, msgs }));
+    ws.addEventListener('error', () => reject(new Error('connection error')));
+    ws.addEventListener('close', (e) => reject(new Error(`closed ${e.code} ${e.reason}`)));
+    setTimeout(() => reject(new Error('timeout')), 5000);
+  });
+}
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+function rejected(path: string, token = ''): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, BASE);
+    const req = httpRequest(url, {
+      headers: {
+        Connection: 'Upgrade',
+        Upgrade: 'websocket',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+    });
+    req.on('response', (response) => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => {
+        body += chunk;
+      });
+      response.on('end', () => resolve({ status: response.statusCode || 0, body }));
+    });
+    req.on('upgrade', (_response, socket) => {
+      socket.destroy();
+      resolve({ status: 101, body: '' });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+const roadEnvelope = (from: string, to: string, text: string) => ({
+  protocol: 'agents-city-bus/2',
+  id: `msg_${crypto.randomUUID()}`,
+  kind: 'road.message',
+  scope: 'road',
+  thread: null,
+  from: { city: from, actor: 'seat', role: 'chair' },
+  to: { city: to, actor: 'seat' },
+  createdAt: new Date().toISOString(),
+  payload: { text, trust: 'information-not-authority' },
+});
+let pass = 0,
+  fail = 0;
+function check(name: string, ok: boolean, extra = '') {
+  console.log(`${ok ? '✅' : '❌'} ${name}${extra ? ' — ' + extra : ''}`);
+  ok ? pass++ : fail++;
+}
+
+// --- HTTP: rechazos ---
+const noTok = await rejected('/ws');
+check('no token -> 401', noTok.status === 401, `status ${noTok.status}`);
+
+const badTok = await rejected('/ws?agent=alice/lead', 'made-up');
+check('invalid token -> 403', badTok.status === 403, `status ${badTok.status}`);
+
+const badName = await rejected('/ws?agent=MAYUS', ALICE);
+check('invalid name -> 400', badName.status === 400, `status ${badName.status}`);
+
+const imperson = await rejected('/ws?agent=bob/infra', ALICE);
+check(
+  'impersonating another user -> 403',
+  imperson.status === 403,
+  `status ${imperson.status} ${imperson.body.trim()}`,
+);
+
+// --- WS: flujo real ---
+const a = await open(ALICE, 'alice/lead');
+const b = await open(BOB, 'bob/infra');
+await wait(400);
+
+check(
+  'a welcome on connecting',
+  a.msgs.some((m) => m.type === 'welcome'),
+);
+check(
+  'the second agent shows up',
+  a.msgs.some((m) => m.type === 'presence' && m.agent === 'bob/infra' && m.status === 'online'),
+);
+
+// roster
+b.ws.send(JSON.stringify({ type: 'roster' }));
+await wait(300);
+const ros = b.msgs.filter((m) => m.type === 'roster').pop();
+check(
+  'the roster sees the other one',
+  !!ros?.agents?.some((x: any) => x.agent === 'alice/lead'),
+  JSON.stringify(ros?.agents),
+);
+
+// mensaje dirigido
+a.ws.send(JSON.stringify({ type: 'send', to: 'bob/infra', text: 'hello from the seat' }));
+await wait(400);
+const got = b.msgs.find((m) => m.type === 'msg');
+check(
+  'the message is delivered',
+  got?.text === 'hello from the seat' && got?.from === 'alice/lead',
+  JSON.stringify(got),
+);
+check(
+  'the sender gets an acknowledgement',
+  a.msgs.some((m) => m.type === 'sent' && m.delivered === 1),
+);
+
+// The v2 local hub and this internet relay carry the same typed envelope.
+const typed = roadEnvelope('alice/lead', 'bob/infra', 'typed over the road');
+a.ws.send(
+  JSON.stringify({
+    type: 'send',
+    request_id: 'typed-1',
+    to: 'bob/infra',
+    text: 'typed over the road',
+    envelope: typed,
+  }),
+);
+await wait(400);
+const typedGot = b.msgs.find((m) => m.type === 'msg' && m.envelope?.id === typed.id);
+check(
+  'the relay preserves the v2 envelope',
+  typedGot?.envelope?.protocol === 'agents-city-bus/2' &&
+    typedGot?.envelope?.scope === 'road' &&
+    typedGot?.envelope?.from?.actor === 'seat' &&
+    typedGot?.envelope?.from?.role === 'external-seat',
+);
+check(
+  'typed acknowledgements correlate to their request',
+  a.msgs.some((m) => m.type === 'sent' && m.request_id === 'typed-1'),
+);
+
+const internal = { ...roadEnvelope('alice/lead', 'bob/infra', 'must fail'), scope: 'internal' };
+a.ws.send(
+  JSON.stringify({
+    type: 'send',
+    request_id: 'typed-2',
+    to: 'bob/infra',
+    text: 'must fail',
+    envelope: internal,
+  }),
+);
+await wait(300);
+check(
+  'an internal committee envelope cannot cross the internet boundary',
+  a.msgs.some((m) => m.type === 'error' && m.request_id === 'typed-2' && /scope/.test(m.error)),
+);
+
+const spoofed = roadEnvelope('alice/other', 'bob/infra', 'must fail too');
+a.ws.send(
+  JSON.stringify({
+    type: 'send',
+    request_id: 'typed-3',
+    to: 'bob/infra',
+    text: 'must fail too',
+    envelope: spoofed,
+  }),
+);
+await wait(300);
+check(
+  'the authenticated seat cannot spoof another city in an envelope',
+  a.msgs.some((m) => m.type === 'error' && m.request_id === 'typed-3' && /sender/.test(m.error)),
+);
+
+// respuesta en sentido contrario
+b.ws.send(JSON.stringify({ type: 'send', to: 'alice/lead', text: 'recibido' }));
+await wait(400);
+check(
+  'a reply travels the other way',
+  a.msgs.some((m) => m.type === 'msg' && m.text === 'recibido' && m.from === 'bob/infra'),
+);
+
+// destinatario inexistente: ahora se encola en vez de fallar
+a.ws.send(JSON.stringify({ type: 'send', to: 'nadie/x', text: 'eco' }));
+await wait(400);
+check(
+  'recipient offline -> queued',
+  a.msgs.some((m) => m.type === 'queued' && m.to === 'nadie/x'),
+);
+
+// a uno mismo
+a.ws.send(JSON.stringify({ type: 'send', to: 'alice/lead', text: 'yo' }));
+await wait(300);
+check(
+  'message to yourself -> error',
+  a.msgs.some((m) => m.type === 'error' && /that is you/.test(m.error)),
+);
+
+// broadcast
+// A second agent of the SAME person: that is the normal case — a seat window
+// and a repo window. The name here used to be left over from a find-and-replace
+// and carried a space, which the hub rightly refuses, so this test never ran.
+const c = await open(ALICE, 'alice/second');
+await wait(300);
+const bBefore = b.msgs.filter((m) => m.type === 'msg').length;
+const cBefore = c.msgs.filter((m) => m.type === 'msg').length;
+a.ws.send(JSON.stringify({ type: 'send', to: '*', text: 'to everybody' }));
+await wait(500);
+check(
+  'a broadcast reaches everybody else',
+  b.msgs.filter((m) => m.type === 'msg').length === bBefore + 1 &&
+    c.msgs.filter((m) => m.type === 'msg').length === cBefore + 1,
+);
+check(
+  'a broadcast does not come back to the sender',
+  !a.msgs.some((m) => m.type === 'msg' && m.text === 'to everybody'),
+);
+
+// size
+a.ws.send(JSON.stringify({ type: 'send', to: 'bob/infra', text: 'x'.repeat(64_001) }));
+await wait(400);
+check(
+  'an enormous message is refused',
+  a.msgs.some((m) => m.type === 'error' && /maximum/.test(m.error)),
+);
+
+// empty
+a.ws.send(JSON.stringify({ type: 'send', to: 'bob/infra', text: '   ' }));
+await wait(300);
+check(
+  'an empty message is refused',
+  a.msgs.some((m) => m.type === 'error' && /empty/.test(m.error)),
+);
+
+// the same agent reconnecting closes the previous session
+let closed = 0;
+b.ws.addEventListener('close', (e) => {
+  if (e.code === 4009) closed = 4009;
+});
+const b2 = await open(BOB, 'bob/infra');
+await wait(600);
+check('a reconnect closes the previous session', closed === 4009, `code=${closed}`);
+
+// rate limit
+const d = await open(BOB, 'bob/tmp'); // the token is bob's, so the name has to be too
+await wait(200);
+for (let i = 0; i < 35; i++)
+  d.ws.send(JSON.stringify({ type: 'send', to: 'alice/lead', text: `n${i}` }));
+await wait(900);
+check(
+  'the rate limit fires',
+  d.msgs.some((m) => m.type === 'error' && /rate limit/.test(m.error)),
+);
+
+for (const s of [a.ws, b2.ws, c.ws, d.ws])
+  try {
+    s.close();
+  } catch {}
+console.log(`\n${pass} ok, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/bus/scripts/test-local.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Exercise the internet-road Durable Object locally, including its durable queue.
+set -euo pipefail
+
+WORKER="$(cd "$(dirname "$0")/../worker" && pwd)"
+STATE="$(mktemp -d /tmp/agents-city-bus.XXXXXX)"
+LOG="$STATE/wrangler.log"
+PID=""
+cleanup() {
+  if [ -n "$PID" ]; then
+    kill "$PID" 2>/dev/null || true
+    wait "$PID" 2>/dev/null || true
+  fi
+  rm -rf "$STATE"
+}
+trap cleanup EXIT INT TERM
+
+cd "$WORKER"
+alice_hash="$(printf '%s' 'tok-alice-test' | shasum -a 256 | awk '{print $1}')"
+bob_hash="$(printf '%s' 'tok-bob-test' | shasum -a 256 | awk '{print $1}')"
+npm exec wrangler -- kv key put --local --persist-to "$STATE" --binding TOKENS "tok:$alice_hash" '{"user":"alice","can_send_to":["*"]}' >/dev/null
+npm exec wrangler -- kv key put --local --persist-to "$STATE" --binding TOKENS "tok:$bob_hash" '{"user":"bob","can_send_to":["*"]}' >/dev/null
+npm exec wrangler -- dev --local --persist-to "$STATE" --port 8799 --log-level error --show-interactive-dev-session=false >"$LOG" 2>&1 &
+PID=$!
+
+ready=0
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+  if curl -fsS http://127.0.0.1:8799/health >/dev/null 2>&1; then
+    ready=1
+    break
+  fi
+  sleep .25
+done
+if [ "$ready" -ne 1 ]; then
+  cat "$LOG" >&2
+  exit 1
+fi
+
+NODE_NO_WARNINGS=1 node --experimental-strip-types ../scripts/test-hub.ts
+NODE_NO_WARNINGS=1 node --experimental-strip-types ../scripts/test-queue.ts

package/bus/scripts/test-queue.ts

@@ -0,0 +1,132 @@
+const BASE = process.env.BUS || 'http://127.0.0.1:8799';
+const ALICE = process.env.TJ || 'tok-alice-test';
+const BOB = process.env.TA || 'tok-bob-test';
+// The prefixes have to match the owners of those tokens.
+const UA = process.env.UA || 'alice'; // owner of TA
+const UB = process.env.UB || 'bob'; // owner of TB
+function open(token: string, agent: string): Promise<{ ws: WebSocket; msgs: any[] }> {
+  return new Promise((res, rej) => {
+    const msgs: any[] = [];
+    const ws = new WebSocket(`${BASE.replace('http', 'ws')}/ws?agent=${agent}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    } as any);
+    ws.addEventListener('message', (e) => {
+      try {
+        msgs.push(JSON.parse(String(e.data)));
+      } catch {}
+    });
+    ws.addEventListener('open', () => res({ ws, msgs }));
+    ws.addEventListener('close', (e) => rej(new Error('cerrado ' + e.code)));
+    setTimeout(() => rej(new Error('timeout')), 8000);
+  });
+}
+const wait = (m: number) => new Promise((r) => setTimeout(r, m));
+let p = 0,
+  f = 0;
+const ck = (n: string, ok: boolean, x = '') => {
+  console.log((ok ? '✅' : '❌') + ' ' + n + (x ? ' — ' + x : ''));
+  ok ? p++ : f++;
+};
+
+// 1. write to somebody who is NOT connected
+const a = await open(ALICE, `${UA}/cpto`);
+await wait(400);
+a.ws.send(
+  JSON.stringify({ type: 'send', to: `${UB}/away`, text: 'revisa los CVE de las dependencias' }),
+);
+await wait(600);
+const q = a.msgs.find((m: any) => m.type === 'queued');
+ck('recipient away -> queued, not an error', !!q && q.to === `${UB}/away`, JSON.stringify(q));
+
+// 2. un segundo mensaje para el mismo
+a.ws.send(JSON.stringify({ type: 'send', to: `${UB}/away`, text: 'y el bundle size de la home' }));
+await wait(600);
+ck('a second message is queued too', a.msgs.filter((m: any) => m.type === 'queued').length === 2);
+
+const typed = {
+  protocol: 'agents-city-bus/2',
+  id: `msg_${crypto.randomUUID()}`,
+  kind: 'road.message',
+  scope: 'road',
+  thread: null,
+  from: { city: `${UA}/cpto`, actor: 'seat', role: 'chair' },
+  to: { city: `${UB}/away`, actor: 'seat' },
+  createdAt: new Date().toISOString(),
+  payload: { text: 'typed and durable' },
+};
+a.ws.send(
+  JSON.stringify({
+    type: 'send',
+    to: `${UB}/away`,
+    text: 'typed and durable',
+    envelope: typed,
+  }),
+);
+await wait(600);
+ck('a typed envelope is queued too', a.msgs.filter((m: any) => m.type === 'queued').length === 3);
+
+// 3. el destinatario aparece y recibe lo pendiente, en orden
+const b = await open(BOB, `${UB}/away`);
+await wait(1200);
+const got = b.msgs.filter((m: any) => m.type === 'msg');
+ck('on connecting it gets all queued messages', got.length === 3, `received ${got.length}`);
+ck(
+  'they arrive in order',
+  got[0]?.text === 'revisa los CVE de las dependencias' &&
+    got[1]?.text === 'y el bundle size de la home',
+);
+ck(
+  'marked as delayed',
+  typeof got[0]?.delayed_minutes === 'number',
+  `delayed_minutes=${got[0]?.delayed_minutes}`,
+);
+ck('they keep their sender', got[0]?.from === `${UA}/cpto`);
+ck(
+  'the typed envelope survives durable storage',
+  got[2]?.envelope?.id === typed.id && got[2]?.envelope?.from?.role === 'external-seat',
+);
+
+// 4. the queue drains: reconnecting does not duplicate them
+b.ws.close();
+await wait(600);
+const b2 = await open(BOB, `${UB}/away`);
+await wait(1000);
+ck(
+  'they are not delivered twice on reconnect',
+  b2.msgs.filter((m: any) => m.type === 'msg').length === 0,
+  `received ${b2.msgs.filter((m: any) => m.type === 'msg').length}`,
+);
+
+// 5. estando conectado, entrega directa (no cola)
+a.ws.send(JSON.stringify({ type: 'send', to: `${UB}/away`, text: 'directo' }));
+await wait(600);
+ck(
+  'with the peer connected it goes straight through',
+  a.msgs.some((m: any) => m.type === 'sent' && m.delivered === 1),
+);
+ck(
+  'and arrives with no delay marker',
+  b2.msgs.some(
+    (m: any) => m.type === 'msg' && m.text === 'directo' && m.delayed_minutes === undefined,
+  ),
+);
+
+// 6. a broadcast with nobody else does not queue
+try {
+  const solo = await open(ALICE, `${UA}/solo`);
+  await wait(400);
+  solo.ws.send(JSON.stringify({ type: 'send', to: '*', text: 'eco' }));
+  await wait(600);
+  ck(
+    'a broadcast reaches whoever is connected',
+    solo.msgs.some((m: any) => m.type === 'sent'),
+  );
+  solo.ws.close();
+} catch (e: any) {
+  ck('broadcast', false, e.message);
+}
+
+a.ws.close();
+b2.ws.close();
+console.log(`\n${p} ok, ${f} failed`);
+process.exit(f ? 1 : 0);