agents-city 0.3.0-beta.21

package/plugin/channel/committee-cli.ts

@@ -0,0 +1,109 @@
+import { busCommand } from './hub-client.js';
+import { parsePayload } from './cli-args.js';
+
+const COMMANDS: Record<string, string> = {
+  open: 'committee.open',
+  respond: 'committee.respond',
+  synthesize: 'committee.synthesize',
+  'floor-request': 'committee.floor.request',
+  'floor-grant': 'committee.floor.grant',
+  'floor-deny': 'committee.floor.deny',
+  reply: 'committee.reply',
+  decide: 'committee.decide',
+  verify: 'committee.verify',
+  replan: 'committee.replan',
+  close: 'committee.close',
+  cancel: 'committee.cancel',
+};
+
+export async function committeeCli(args: string[]): Promise<unknown> {
+  const verb = args.shift() || 'list';
+  if (['help', '-h', '--help'].includes(verb)) return help();
+  if (verb === 'list') return busCommand('committee.list');
+  if (verb === 'history') return busCommand('committee.history');
+  if (verb === 'schema') return schema(args[0] || 'open');
+  const { payload, positional } = parsePayload(args);
+  if (verb === 'show' || verb === 'status') {
+    const thread = positional[0];
+    if (!thread) throw new Error(`committee ${verb} needs a deliberation id`);
+    return busCommand('committee.get', {}, thread);
+  }
+  const command = COMMANDS[verb];
+  if (!command) throw new Error(`unknown committee command: ${verb}`);
+  const thread = verb === 'open' ? undefined : positional[0];
+  if (verb !== 'open' && !thread) throw new Error(`committee ${verb} needs a deliberation id`);
+  if (verb === 'open' && payload.outcome && !payload.desiredOutcome) {
+    payload.desiredOutcome = payload.outcome;
+    delete payload.outcome;
+  }
+  return busCommand(command, payload, thread);
+}
+
+function help(): Record<string, unknown> {
+  return {
+    usage: 'agents-city committee <command> [deliberation-id] [--input payload.json | flags]',
+    commands: [
+      'list',
+      'history',
+      'show',
+      'open',
+      ...Object.keys(COMMANDS).filter((name) => name !== 'open'),
+      'schema',
+    ],
+    note: 'Every mutation travels over the local WebSocket bus; repo agents cannot address one another.',
+    examples: [
+      'agents-city committee open --question "Ship it?" --outcome "A verified go/no-go" --member api --done "tests pass"',
+      'agents-city committee respond DELIB --input /tmp/position.json',
+      'agents-city committee schema respond',
+    ],
+  };
+}
+
+function schema(verb: string): Record<string, unknown> {
+  const examples: Record<string, Record<string, unknown>> = {
+    open: {
+      question: 'What exactly are we deciding?',
+      desiredOutcome: 'The concrete result expected from the committee',
+      context: 'Only facts needed to answer',
+      constraints: ['time, cost or policy boundary'],
+      definitionOfDone: ['observable acceptance condition'],
+      authority: 'recommend',
+      participants: ['api'],
+      maxRebuttals: 2,
+    },
+    respond: {
+      stance: 'conditional',
+      recommendation: 'What this specialist recommends',
+      evidence: ['file:line, command result or source'],
+      expectedImpact: 'What number or observable outcome changes',
+      visibleWhen: 'When the change can be measured',
+      withdrawIf: 'Evidence that would change this position',
+      risks: [],
+      unknowns: [],
+    },
+    synthesize: { summary: '', agreements: [], conflicts: [], unknowns: [], proceedWithout: '' },
+    'floor-request': { basis: 'new_evidence', reason: '', evidence: [''] },
+    'floor-grant': { requestId: '' },
+    'floor-deny': { requestId: '', reason: '' },
+    reply: { claim: '', evidence: [''], consequence: '' },
+    decide: {
+      outcome: '',
+      rationale: '',
+      owner: '',
+      executor: 'seat',
+      verifier: 'api',
+      verificationQuestion: '',
+      selectedEvidence: [''],
+      decisiveContributors: ['api'],
+      rejectedOptions: [],
+      dissent: [],
+      reopenIf: [''],
+    },
+    verify: { result: 'pass', evidence: [''], checks: [''], residualRisks: [] },
+    replan: { reason: '' },
+    close: { summary: '', learnings: [], followups: [] },
+    cancel: { reason: '' },
+  };
+  if (!examples[verb]) throw new Error(`no schema for committee ${verb}`);
+  return examples[verb];
+}

package/plugin/channel/delivery-metrics.ts

@@ -0,0 +1,61 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { BusEnvelope } from './protocol.js';
+import { TerminalReceipt } from './terminal-delivery.js';
+
+export interface DeliveryMetric {
+  schema: 'agents-city/delivery-latency@1';
+  envelopeId: string;
+  thread: string | null;
+  kind: string;
+  actor: string;
+  runtime: string;
+  envelopeCreatedAt: string;
+  adapterReceivedAt: string;
+  terminalReadyAt: string;
+  pastedAt: string;
+  submittedAt: string;
+  transportToAdapterMs: number;
+  adapterToSubmitMs: number;
+  totalToSubmitMs: number;
+  pasteToSubmitMs: number;
+  bytes: number;
+}
+
+export function recordDelivery(
+  runtimeDir: string,
+  envelope: BusEnvelope,
+  actor: string,
+  runtime: string,
+  adapterReceivedAt: string,
+  receipt: TerminalReceipt,
+): DeliveryMetric {
+  const metric: DeliveryMetric = {
+    schema: 'agents-city/delivery-latency@1',
+    envelopeId: envelope.id,
+    thread: envelope.thread,
+    kind: envelope.kind,
+    actor,
+    runtime,
+    envelopeCreatedAt: envelope.createdAt,
+    adapterReceivedAt,
+    terminalReadyAt: receipt.readyAt,
+    pastedAt: receipt.pastedAt,
+    submittedAt: receipt.submittedAt,
+    transportToAdapterMs: elapsed(envelope.createdAt, adapterReceivedAt),
+    adapterToSubmitMs: elapsed(adapterReceivedAt, receipt.submittedAt),
+    totalToSubmitMs: elapsed(envelope.createdAt, receipt.submittedAt),
+    pasteToSubmitMs: receipt.pasteToSubmitMs,
+    bytes: receipt.bytes,
+  };
+  mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+  appendFileSync(join(runtimeDir, 'delivery-latency.jsonl'), JSON.stringify(metric) + '\n', {
+    mode: 0o600,
+  });
+  return metric;
+}
+
+function elapsed(start: string, end: string): number {
+  const value = Date.parse(end) - Date.parse(start);
+  return Number.isFinite(value) ? Math.max(0, value) : 0;
+}

package/plugin/channel/delivery-queue.ts

@@ -0,0 +1,118 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { atomicJson } from './runtime-files.js';
+import { BusEnvelope, MAX_PENDING, MESSAGE_TTL_MS, safeSegment } from './protocol.js';
+
+export function enqueueForActor(runtimeDir: string, envelope: BusEnvelope): void {
+  const directory = join(runtimeDir, 'outbox', safeSegment(envelope.to.actor));
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  trim(directory);
+  atomicJson(join(directory, `${fileKey(envelope.id)}.json`), envelope);
+}
+
+export function pendingForActor(runtimeDir: string, actor: string): BusEnvelope[] {
+  const directory = join(runtimeDir, 'outbox', safeSegment(actor));
+  const now = Date.now();
+  return jsonFiles(directory)
+    .map((path) => {
+      try {
+        const envelope = JSON.parse(readFileSync(path, 'utf8')) as BusEnvelope;
+        if (now - Date.parse(envelope.createdAt) > MESSAGE_TTL_MS) {
+          unlinkSync(path);
+          return null;
+        }
+        return envelope;
+      } catch {
+        try {
+          unlinkSync(path);
+        } catch {}
+        return null;
+      }
+    })
+    .filter((envelope): envelope is BusEnvelope => envelope !== null);
+}
+
+export function acknowledge(runtimeDir: string, actor: string, envelopeId: string): boolean {
+  const path = join(runtimeDir, 'outbox', safeSegment(actor), `${fileKey(envelopeId)}.json`);
+  try {
+    unlinkSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function queueRoad(runtimeDir: string, envelope: BusEnvelope): void {
+  const directory = join(runtimeDir, 'road-queue');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  trim(directory);
+  atomicJson(join(directory, `${fileKey(envelope.id)}.json`), envelope);
+}
+
+export function drainRoadQueue(runtimeDir: string): BusEnvelope[] {
+  const directory = join(runtimeDir, 'road-queue');
+  const out: BusEnvelope[] = [];
+  for (const path of jsonFiles(directory)) {
+    try {
+      const envelope = JSON.parse(readFileSync(path, 'utf8')) as BusEnvelope;
+      if (Date.now() - Date.parse(envelope.createdAt) <= MESSAGE_TTL_MS) out.push(envelope);
+    } catch {}
+    try {
+      unlinkSync(path);
+    } catch {}
+  }
+  return out;
+}
+
+export function recordRoadInbox(runtimeDir: string, envelope: BusEnvelope): void {
+  const directory = join(runtimeDir, 'road-inbox');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  trim(directory);
+  atomicJson(join(directory, `${fileKey(envelope.id)}.json`), envelope);
+  appendFileSync(join(runtimeDir, 'road-history.jsonl'), JSON.stringify(envelope) + '\n', {
+    mode: 0o600,
+  });
+}
+
+export function takeRoadInbox(runtimeDir: string): BusEnvelope[] {
+  const directory = join(runtimeDir, 'road-inbox');
+  const out: BusEnvelope[] = [];
+  for (const path of jsonFiles(directory)) {
+    try {
+      out.push(JSON.parse(readFileSync(path, 'utf8')) as BusEnvelope);
+    } catch {}
+    try {
+      unlinkSync(path);
+    } catch {}
+  }
+  return out;
+}
+
+function jsonFiles(directory: string): string[] {
+  if (!existsSync(directory)) return [];
+  try {
+    return readdirSync(directory)
+      .filter((name) => name.endsWith('.json'))
+      .sort()
+      .map((name) => join(directory, name));
+  } catch {
+    return [];
+  }
+}
+
+function fileKey(value: string): string {
+  const out = String(value)
+    .replace(/[^a-zA-Z0-9_.-]+/g, '-')
+    .slice(0, 160);
+  if (!out) throw new Error('invalid message id');
+  return out;
+}
+
+function trim(directory: string): void {
+  const files = jsonFiles(directory);
+  for (const path of files.slice(0, Math.max(0, files.length - MAX_PENDING + 1))) {
+    try {
+      unlinkSync(path);
+    } catch {}
+  }
+}

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

@@ -0,0 +1,72 @@
+import { ActivityDraft, ActivityFeed, ActivityTone } from './activity-feed.js';
+import { ActorRole } from '../protocol.js';
+import { ClientMode } from './connections.js';
+
+const TONES = new Set<ActivityTone>([
+  'question',
+  'work',
+  'floor',
+  'evidence',
+  'decision',
+  'verification',
+  'error',
+  'system',
+]);
+
+/**
+ * Authenticated semantic events from native runtimes and Claude hooks.
+ *
+ * Actor and authority always come from the socket credential. Payloads may
+ * describe visible prompts, answers and work, but cannot impersonate committee
+ * state transitions or smuggle raw provider frames into the browser.
+ */
+export function activityController(publish: ActivityFeed['publish']) {
+  const command = (
+    payload: Record<string, unknown>,
+    thread: string | undefined,
+    actor: string,
+    role: ActorRole,
+    mode: ClientMode,
+  ) => {
+    if (!['runtime', 'mcp', 'client'].includes(mode)) {
+      throw new Error('this connection cannot publish city activity');
+    }
+    const kind = clean(payload.kind, 100);
+    if (!/^(?:conversation|runtime|work)\.[a-z0-9_.-]+$/.test(kind)) {
+      throw new Error('activity kind must describe conversation, runtime or work');
+    }
+    if (/(?:^|[._-])(?:reasoning|thoughts?|chain-of-thought)(?:$|[._-])/.test(kind)) {
+      throw new Error('private model reasoning is never city activity');
+    }
+    const requestedTone = clean(payload.tone, 30) as ActivityTone;
+    const draft: ActivityDraft = {
+      sourceId: clean(payload.sourceId, 240) || undefined,
+      kind,
+      thread: clean(thread || payload.thread, 160) || null,
+      actor,
+      role,
+      phase: clean(payload.phase, 40) || 'observed',
+      tone: TONES.has(requestedTone) ? requestedTone : 'work',
+      title: clean(payload.title, 300) || `${actor} reported activity`,
+      summary: clean(payload.summary, 4_000),
+      details: Array.isArray(payload.details)
+        ? payload.details
+            .slice(0, 120)
+            .map((item) => clean(item, 2_000))
+            .filter(Boolean)
+        : [],
+      target: clean(payload.target, 80) || undefined,
+    };
+    if (!draft.summary && !draft.details?.length) {
+      throw new Error('activity needs a visible summary or details');
+    }
+    return publish(draft);
+  };
+  return { command };
+}
+
+function clean(value: unknown, max: number): string {
+  return String(value ?? '')
+    .trim()
+    .slice(0, max);
+}

package/plugin/channel/hub/activity-feed.ts

@@ -0,0 +1,169 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import WebSocket from 'ws';
+import { ActorRole, isoNow, randomId } from '../protocol.js';
+import { CityContext } from '../city-config.js';
+
+export const ACTIVITY_PROTOCOL = 'agents-city-activity/1' as const;
+
+export type ActivityTone =
+  'question' | 'work' | 'floor' | 'evidence' | 'decision' | 'verification' | 'error' | 'system';
+
+export interface ActivityDraft {
+  /** Stable provider/hook identity used to make reconnects and repeated hooks idempotent. */
+  sourceId?: string;
+  kind: string;
+  thread: string | null;
+  actor: string;
+  role: ActorRole;
+  phase: string;
+  tone: ActivityTone;
+  title: string;
+  summary: string;
+  details?: string[];
+  target?: string;
+}
+
+export interface ActivityEvent extends ActivityDraft {
+  protocol: typeof ACTIVITY_PROTOCOL;
+  id: string;
+  seq: number;
+  city: string;
+  at: string;
+  details: string[];
+}
+
+/**
+ * Read-only semantic feed for the browser.
+ *
+ * It records protocol actions, never model chain-of-thought or raw transport
+ * frames. Keeping this beside the hub means the browser sees the exact same
+ * ordering as the committee state machine, independently of the model vendor.
+ */
+export function activityFeed(context: CityContext) {
+  const path = join(context.runtimeDir, 'activity.jsonl');
+  const spectators = new Set<WebSocket>();
+  const restored = readRecent(path, 1_000);
+  let recent = restored.slice(-200);
+  let seq = recent.at(-1)?.seq || 0;
+  const sources = new Map(
+    restored.filter((event) => event.sourceId).map((event) => [event.sourceId as string, event]),
+  );
+
+  const publish = (draft: ActivityDraft): ActivityEvent => {
+    const sourceId = String(draft.sourceId || '')
+      .trim()
+      .slice(0, 240);
+    const existing = sourceId ? sources.get(sourceId) : undefined;
+    if (existing) return existing;
+    const event: ActivityEvent = {
+      protocol: ACTIVITY_PROTOCOL,
+      id: randomId('activity'),
+      seq: ++seq,
+      city: context.city.address,
+      at: isoNow(),
+      ...cleanDraft(draft),
+    };
+    mkdirSync(context.runtimeDir, { recursive: true, mode: 0o700 });
+    appendFileSync(path, JSON.stringify(event) + '\n', { mode: 0o600 });
+    recent.push(event);
+    if (event.sourceId) sources.set(event.sourceId, event);
+    if (recent.length > 200) recent = recent.slice(-200);
+    if (seq % 100 === 0 && fileIsLarge(path)) compact(path);
+    fanOut({ type: 'activity.event', event });
+    return event;
+  };
+
+  const subscribe = (ws: WebSocket): void => {
+    spectators.add(ws);
+    ws.send(
+      JSON.stringify({
+        type: 'activity.state',
+        protocol: ACTIVITY_PROTOCOL,
+        city: context.city.address,
+        events: recent,
+      }),
+    );
+  };
+
+  const remove = (ws: WebSocket): void => {
+    spectators.delete(ws);
+  };
+
+  const fanOut = (message: Record<string, unknown>): void => {
+    const encoded = JSON.stringify(message);
+    for (const ws of spectators) {
+      if (ws.readyState !== WebSocket.OPEN) continue;
+      try {
+        ws.send(encoded);
+      } catch {
+        spectators.delete(ws);
+      }
+    }
+  };
+
+  return { publish, subscribe, remove };
+}
+
+function cleanDraft(draft: ActivityDraft): ActivityDraft & { details: string[] } {
+  const short = (value: unknown, max: number): string =>
+    String(value ?? '')
+      .trim()
+      .slice(0, max);
+  return {
+    ...(draft.sourceId ? { sourceId: short(draft.sourceId, 240) } : {}),
+    kind: short(draft.kind, 100),
+    thread: draft.thread ? short(draft.thread, 100) : null,
+    actor: short(draft.actor, 80),
+    role: draft.role,
+    phase: short(draft.phase, 40),
+    tone: draft.tone,
+    title: short(draft.title, 300),
+    summary: short(draft.summary, 4_000),
+    details: (draft.details || []).slice(0, 120).map((detail) => short(detail, 2_000)),
+    ...(draft.target ? { target: short(draft.target, 80) } : {}),
+  };
+}
+
+function readRecent(path: string, limit: number): ActivityEvent[] {
+  try {
+    return readFileSync(path, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .slice(-limit)
+      .map((line) => JSON.parse(line) as ActivityEvent)
+      .filter((event) => event.protocol === ACTIVITY_PROTOCOL && Number.isInteger(event.seq));
+  } catch {
+    return [];
+  }
+}
+
+function fileIsLarge(path: string): boolean {
+  try {
+    return statSync(path).size > 2_000_000;
+  } catch {
+    return false;
+  }
+}
+
+function compact(path: string): void {
+  if (!existsSync(path)) return;
+  try {
+    const kept = readFileSync(path, 'utf8').split('\n').filter(Boolean).slice(-1_000);
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, kept.join('\n') + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch {
+    // Provider state and committee acts remain authoritative; compaction is best effort.
+  }
+}
+
+export type ActivityFeed = ReturnType<typeof activityFeed>;

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

@@ -0,0 +1,60 @@
+import { ActorRole } from '../protocol.js';
+import { committeeActivities } from '../committee/activity.js';
+import { requireChair } from '../committee/guards.js';
+import { committeeService } from '../committee/service.js';
+import type { ActivityDraft } from './activity-feed.js';
+import { EnvelopeRouter } from './envelopes.js';
+
+type CommitteeService = ReturnType<typeof committeeService>;
+
+export function committeeController(
+  service: CommitteeService,
+  router: EnvelopeRouter,
+  observe: (event: ActivityDraft) => void = () => {},
+) {
+  const command = (
+    name: string,
+    thread: string | undefined,
+    payload: Record<string, unknown>,
+    actor: string,
+    role: ActorRole,
+  ): unknown => {
+    if (name === 'committee.history') {
+      requireChair(actor, role);
+      return service.history(thread);
+    }
+    if (name === 'committee.list') {
+      return service
+        .list()
+        .filter(
+          (state) =>
+            role === 'chair' ||
+            state.brief.participants.includes(actor) ||
+            state.decisions.at(-1)?.verifier === actor,
+        )
+        .map((state) => ({
+          id: state.id,
+          status: state.status,
+          question: state.brief.question,
+          participants: state.brief.participants,
+          received: Object.keys(state.positions).length,
+          createdAt: state.createdAt,
+          updatedAt: state.updatedAt,
+        }));
+    }
+    if (name === 'committee.get') {
+      if (!thread) throw new Error('thread is required');
+      return service.view(thread, actor, role);
+    }
+    const result = service.transition(name, thread, payload, actor, role);
+    for (const delivery of result.deliveries) {
+      router.internal(delivery.kind, actor, role, delivery.to, result.state.id, delivery.payload);
+    }
+    for (const event of committeeActivities(name, result.state, payload, actor, role)) {
+      observe(event);
+    }
+    return service.view(result.state.id, actor, role);
+  };
+
+  return { command };
+}

package/plugin/channel/hub/connections.ts

@@ -0,0 +1,48 @@
+import WebSocket from 'ws';
+import { ActorRole, BusEnvelope } from '../protocol.js';
+
+export type ClientMode = 'runtime' | 'adapter' | 'client' | 'mcp';
+
+export interface ActorPeer {
+  ws: WebSocket;
+  actor: string;
+  role: ActorRole;
+  mode: ClientMode;
+}
+
+export function connectionRegistry() {
+  const peers = new Set<ActorPeer>();
+
+  const add = (peer: ActorPeer): void => {
+    peers.add(peer);
+  };
+  const remove = (ws: WebSocket): void => {
+    for (const peer of peers) if (peer.ws === ws) peers.delete(peer);
+  };
+  const deliver = (actor: string, envelope: BusEnvelope): boolean => {
+    // A native runtime gateway owns delivery. The terminal adapter is retained
+    // only as an explicit compatibility fallback, and is never used while a
+    // native gateway for the actor is online. CLI/MCP command connections cannot
+    // consume an envelope merely by opening a status command.
+    const candidates = [...peers].filter(
+      (candidate) => candidate.actor === actor && candidate.ws.readyState === WebSocket.OPEN,
+    );
+    const peer =
+      candidates.find((candidate) => candidate.mode === 'runtime') ||
+      candidates.find((candidate) => candidate.mode === 'adapter');
+    if (!peer) return false;
+    peer.ws.send(JSON.stringify({ type: 'envelope', envelope }));
+    return true;
+  };
+  const online = (actor: string): boolean =>
+    [...peers].some(
+      (peer) =>
+        peer.actor === actor &&
+        (peer.mode === 'runtime' || peer.mode === 'adapter') &&
+        peer.ws.readyState === WebSocket.OPEN,
+    );
+
+  return { add, remove, deliver, online };
+}
+
+export type ConnectionRegistry = ReturnType<typeof connectionRegistry>;