agents-city 0.3.0-beta.21

package/plugin/channel/client.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { committeeCli } from './committee-cli.js';
+import { activityCli } from './activity-cli.js';
+import { loadCityContext } from './city-config.js';
+import { ensureHub } from './hub-client.js';
+import { roadBusCli } from './road-cli.js';
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const domain = args.shift() || 'help';
+  let value: unknown;
+  if (domain === 'committee') value = await committeeCli(args);
+  else if (domain === 'activity') value = await activityCli(args);
+  else if (domain === 'bus') value = await roadBusCli(args);
+  else if (domain === 'ensure') {
+    const endpoint = await ensureHub(loadCityContext());
+    value = {
+      protocol: endpoint.protocol,
+      city: endpoint.cityAddress,
+      url: endpoint.url,
+      pid: endpoint.pid,
+    };
+  } else if (domain === 'runtime-dir') {
+    value = loadCityContext().runtimeDir;
+  } else {
+    value = {
+      usage: 'client.js <ensure | runtime-dir | bus | committee | activity>',
+      note: 'This is the vendor-neutral WebSocket client behind the agents-city commands.',
+    };
+  }
+  if (typeof value === 'string') console.log(value);
+  else console.log(JSON.stringify(value, null, 2));
+}
+
+main().catch((error) => {
+  console.error(`agents-city: ${(error as Error).message}`);
+  process.exit(1);
+});

package/plugin/channel/committee/activity.ts

@@ -0,0 +1,256 @@
+import { ActorRole } from '../protocol.js';
+import type { ActivityDraft } from '../hub/activity-feed.js';
+import { DeliberationState, FloorRequest } from './types.js';
+
+/** Convert a successful state transition into a small, human-readable live event. */
+export function committeeActivities(
+  command: string,
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): ActivityDraft[] {
+  const base = {
+    thread: state.id,
+    actor,
+    role,
+    phase: state.status,
+  } as const;
+
+  if (command === 'committee.open') {
+    return [
+      {
+        ...base,
+        kind: 'committee.opened',
+        tone: 'question',
+        title: 'The chair opened a committee',
+        summary: state.brief.question,
+        details: [
+          `Desired outcome: ${state.brief.desiredOutcome}`,
+          `Definition of done: ${state.brief.definitionOfDone.join(' · ')}`,
+          `Invited: ${state.brief.participants.join(', ')}`,
+        ],
+      },
+    ];
+  }
+
+  if (command === 'committee.respond') {
+    const received = Object.keys(state.positions).length;
+    const total = state.brief.participants.length;
+    const events: ActivityDraft[] = [
+      {
+        ...base,
+        kind: 'committee.position.submitted',
+        tone: 'work',
+        title: `${actor} submitted an independent position`,
+        summary:
+          state.status === 'collecting'
+            ? 'Its content stays sealed until every selected specialist has answered.'
+            : 'The collection barrier is complete; all positions can now be revealed together.',
+        details: [`${received}/${total} positions received`],
+        target: 'seat',
+      },
+    ];
+    if (state.status === 'review') {
+      events.push({
+        ...base,
+        actor: 'seat',
+        role: 'chair',
+        kind: 'committee.positions.revealed',
+        tone: 'evidence',
+        title: 'All independent positions were revealed together',
+        summary: `${total} specialists completed the blind first round.`,
+        details: [
+          'The chair can now compare evidence, conflicts and unknowns without anchoring bias.',
+        ],
+      });
+      for (const member of state.brief.participants) {
+        const position = state.positions[member];
+        if (!position) continue;
+        events.push({
+          ...base,
+          actor: member,
+          role: 'member',
+          kind: 'committee.position.revealed',
+          tone: 'evidence',
+          title: `${member} proposes`,
+          summary: position.recommendation,
+          details: [
+            `Stance: ${position.stance}`,
+            ...position.evidence.map((item) => `Evidence: ${item}`),
+            ...(position.expectedImpact ? [`Expected impact: ${position.expectedImpact}`] : []),
+            ...(position.visibleWhen ? [`Visible when: ${position.visibleWhen}`] : []),
+            ...(position.risks || []).map((item) => `Risk: ${item}`),
+            ...(position.unknowns || []).map((item) => `Unknown: ${item}`),
+          ],
+          target: 'committee',
+        });
+      }
+    }
+    return events;
+  }
+
+  if (command === 'committee.synthesize') {
+    return [
+      {
+        ...base,
+        kind: 'committee.synthesis.published',
+        tone: 'evidence',
+        title: 'The chair published the synthesis',
+        summary: state.synthesis?.summary || '',
+        details: [
+          ...(state.synthesis?.agreements || []).map((item) => `Agreement: ${item}`),
+          ...(state.synthesis?.conflicts || []).map((item) => `Conflict: ${item}`),
+          ...(state.synthesis?.unknowns || []).map((item) => `Unknown: ${item}`),
+        ],
+      },
+    ];
+  }
+
+  if (command === 'committee.floor.request') {
+    const request = state.floor.requests.at(-1);
+    return request
+      ? [floorEvent(base, request, 'committee.floor.requested', `${actor} requested the floor`)]
+      : [];
+  }
+
+  if (command === 'committee.floor.grant' || command === 'committee.floor.deny') {
+    const request = findRequest(state, payload);
+    if (!request) return [];
+    const granted = command.endsWith('grant');
+    return [
+      {
+        ...base,
+        kind: granted ? 'committee.floor.granted' : 'committee.floor.denied',
+        tone: 'floor',
+        title: granted
+          ? `The chair gave ${request.actor} the floor`
+          : `The chair denied ${request.actor} the floor`,
+        summary: granted
+          ? `One scoped reply was granted for ${request.basis.replace('_', ' ')}.`
+          : request.decisionReason || 'The request was declined.',
+        details: [
+          `Request: ${request.reason}`,
+          ...request.evidence.map((item) => `Evidence: ${item}`),
+        ],
+        target: request.actor,
+      },
+    ];
+  }
+
+  if (command === 'committee.reply') {
+    const reply = state.floor.replies.at(-1);
+    return reply
+      ? [
+          {
+            ...base,
+            kind: 'committee.floor.spoke',
+            tone: 'floor',
+            title: `${actor} spoke on the granted floor`,
+            summary: reply.claim,
+            details: [
+              ...reply.evidence.map((item) => `Evidence: ${item}`),
+              `Consequence: ${reply.consequence}`,
+              'Every committee member heard this intervention and may request a bounded reply.',
+            ],
+            target: 'committee',
+          },
+        ]
+      : [];
+  }
+
+  if (command === 'committee.decide') {
+    const decision = state.decisions.at(-1);
+    return decision
+      ? [
+          {
+            ...base,
+            kind: 'committee.decision.recorded',
+            tone: 'decision',
+            title: 'The chair recorded a decision',
+            summary: decision.outcome,
+            details: [
+              `Rationale: ${decision.rationale}`,
+              `Decisive contributors: ${decision.decisiveContributors.join(', ')}`,
+              ...decision.dissent.map((item) => `Dissent: ${item}`),
+              `Independent verifier: ${decision.verifier}`,
+            ],
+            target: decision.verifier,
+          },
+        ]
+      : [];
+  }
+
+  if (command === 'committee.verify') {
+    const verification = state.decisions.at(-1)?.verification;
+    return verification
+      ? [
+          {
+            ...base,
+            kind: `committee.verification.${verification.result}`,
+            tone: 'verification',
+            title: `${actor} reported verification ${verification.result.toUpperCase()}`,
+            summary: verification.checks.join(' · '),
+            details: [
+              ...verification.evidence.map((item) => `Evidence: ${item}`),
+              ...verification.residualRisks.map((item) => `Residual risk: ${item}`),
+            ],
+            target: 'seat',
+          },
+        ]
+      : [];
+  }
+
+  const simple: Record<
+    string,
+    { kind: string; tone: ActivityDraft['tone']; title: string; summary: string }
+  > = {
+    'committee.replan': {
+      kind: 'committee.replanned',
+      tone: 'decision',
+      title: 'The chair reopened the plan',
+      summary: String(payload.reason || ''),
+    },
+    'committee.close': {
+      kind: 'committee.closed',
+      tone: 'decision',
+      title: 'The chair closed the committee',
+      summary: state.closure?.summary || String(payload.summary || ''),
+    },
+    'committee.cancel': {
+      kind: 'committee.cancelled',
+      tone: 'error',
+      title: 'The chair cancelled the committee',
+      summary: String(payload.reason || ''),
+    },
+  };
+  const item = simple[command];
+  return item ? [{ ...base, ...item }] : [];
+}
+
+function findRequest(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+): FloorRequest | undefined {
+  return state.floor.requests.find((request) => request.id === String(payload.requestId || ''));
+}
+
+function floorEvent(
+  base: Pick<ActivityDraft, 'thread' | 'actor' | 'role' | 'phase'>,
+  request: FloorRequest,
+  kind: string,
+  title: string,
+): ActivityDraft {
+  return {
+    ...base,
+    kind,
+    tone: 'floor',
+    title,
+    summary: request.reason,
+    details: [
+      `Basis: ${request.basis.replace('_', ' ')}`,
+      ...request.evidence.map((item) => `Evidence: ${item}`),
+    ],
+    target: 'seat',
+  };
+}

package/plugin/channel/committee/collection.ts

@@ -0,0 +1,154 @@
+import { ActorRole, isoNow, oneOf, randomId, safeSegment, strings, text } from '../protocol.js';
+import { requireChair, requireMember } from './guards.js';
+import {
+  AUTHORITIES,
+  ActorDirectory,
+  CityIdentity,
+  DeliberationState,
+  FLOOR_BASES,
+  STANCES,
+  TransitionResult,
+} from './types.js';
+
+export function openDeliberation(
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+  city: CityIdentity,
+  actors: ActorDirectory,
+): TransitionResult {
+  requireChair(actor, role);
+  const requested = strings(payload.participants, 'participants', true);
+  const participants = requested.map((p) => safeSegment(p));
+  if (new Set(participants).size !== participants.length) {
+    throw new Error('participants collide after normalising their actor names');
+  }
+  for (const participant of participants) {
+    if (actors[participant]?.role !== 'member') {
+      throw new Error(`${participant} is not a repo support agent in this city`);
+    }
+  }
+  const maxRebuttals = Number(payload.maxRebuttals ?? 2);
+  if (!Number.isInteger(maxRebuttals) || maxRebuttals < 0 || maxRebuttals > 5) {
+    throw new Error('maxRebuttals must be an integer from 0 to 5');
+  }
+  const id = `delib_${new Date().toISOString().replace(/\D/g, '').slice(0, 14)}_${randomId('x').slice(-8)}`;
+  const now = isoNow();
+  const state: DeliberationState = {
+    schema: 'agents-city/deliberation@1',
+    id,
+    city,
+    parent: text(payload.parent, 'parent', false) || null,
+    status: 'collecting',
+    createdAt: now,
+    updatedAt: now,
+    brief: {
+      question: text(payload.question, 'question'),
+      desiredOutcome: text(payload.desiredOutcome, 'desiredOutcome'),
+      context: text(payload.context, 'context', false),
+      constraints: strings(payload.constraints, 'constraints'),
+      definitionOfDone: strings(payload.definitionOfDone, 'definitionOfDone', true),
+      authority: oneOf(payload.authority ?? 'recommend', AUTHORITIES, 'authority'),
+      participants,
+      maxRebuttals,
+    },
+    participantRepos: Object.fromEntries(participants.map((p) => [p, actors[p].repo || p])),
+    participantRoles: Object.fromEntries(
+      participants.map((p) => [p, actors[p].operatingRole || 'blank']),
+    ),
+    positions: {},
+    synthesis: null,
+    floor: { requests: [], active: null, replies: [] },
+    decisions: [],
+    closure: null,
+    progress: { revision: 1, failedVerifications: 0 },
+  };
+  return {
+    state,
+    deliveries: participants.map((to) => ({
+      kind: 'committee.assignment',
+      to,
+      payload: {
+        brief: state.brief,
+        participant: to,
+        operatingRole: state.participantRoles?.[to] || 'blank',
+        isolation: 'initial_positions',
+      },
+    })),
+  };
+}
+
+export function submitPosition(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireMember(state, actor, role);
+  if (state.status !== 'collecting') throw new Error('the independent-position phase is closed');
+  if (state.positions[actor]) throw new Error(`${actor} already submitted an independent position`);
+  state.positions[actor] = {
+    stance: oneOf(payload.stance, STANCES, 'stance'),
+    recommendation: text(payload.recommendation, 'recommendation'),
+    evidence: strings(payload.evidence, 'evidence', true),
+    expectedImpact: text(payload.expectedImpact, 'expectedImpact', false),
+    visibleWhen: text(payload.visibleWhen, 'visibleWhen', false),
+    withdrawIf: text(payload.withdrawIf, 'withdrawIf', false),
+    risks: strings(payload.risks, 'risks'),
+    unknowns: strings(payload.unknowns, 'unknowns'),
+    submittedAt: isoNow(),
+  };
+  const received = Object.keys(state.positions).length;
+  const total = state.brief.participants.length;
+  if (received === total) state.status = 'review';
+  return {
+    state,
+    deliveries: [
+      {
+        kind: received === total ? 'committee.positions_ready' : 'committee.position_received',
+        to: 'seat',
+        payload: { received, total, actor, contentHiddenUntilBarrier: received !== total },
+      },
+    ],
+  };
+}
+
+export function publishSynthesis(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireChair(actor, role);
+  if (!['collecting', 'review'].includes(state.status))
+    throw new Error('positions are not awaiting synthesis');
+  const missing = state.brief.participants.filter((p) => !state.positions[p]);
+  const proceedWithout = text(payload.proceedWithout, 'proceedWithout', false);
+  if (missing.length && !proceedWithout) {
+    throw new Error(
+      `positions still missing from ${missing.join(', ')}; state why proceeding without them`,
+    );
+  }
+  state.synthesis = {
+    summary: text(payload.summary, 'summary'),
+    agreements: strings(payload.agreements, 'agreements'),
+    conflicts: strings(payload.conflicts, 'conflicts'),
+    unknowns: strings(payload.unknowns, 'unknowns'),
+    missing,
+    proceedWithout,
+    publishedAt: isoNow(),
+  };
+  state.status = 'deliberating';
+  return {
+    state,
+    deliveries: state.brief.participants.map((to) => ({
+      kind: 'committee.synthesis',
+      to,
+      payload: {
+        synthesis: state.synthesis,
+        allowedFloorBases: FLOOR_BASES,
+        note: 'Request the floor only for new evidence, a contradiction, a risk or a dependency.',
+      },
+    })),
+  };
+}

package/plugin/channel/committee/decision.ts

@@ -0,0 +1,175 @@
+import { ActorRole, isoNow, oneOf, randomId, safeSegment, strings, text } from '../protocol.js';
+import { currentDecision, requireChair, requireKnownVerifier } from './guards.js';
+import {
+  ActorDirectory,
+  Decision,
+  DeliberationState,
+  TransitionResult,
+  VERIFY_RESULTS,
+} from './types.js';
+
+export function decide(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+  actors: ActorDirectory,
+): TransitionResult {
+  requireChair(actor, role);
+  if (state.status !== 'deliberating' || !state.synthesis) {
+    throw new Error('the chair must publish a synthesis before deciding');
+  }
+  if (state.floor.active)
+    throw new Error(`close ${state.floor.active.actor}'s granted turn before deciding`);
+  if (state.floor.requests.some((request) => request.status === 'pending')) {
+    throw new Error('grant or deny every pending floor request before deciding');
+  }
+  const verifier = safeSegment(text(payload.verifier, 'verifier'));
+  requireKnownVerifier(verifier, actors);
+  const executor = safeSegment(text(payload.executor ?? 'seat', 'executor'));
+  const independentAvailable = state.brief.participants.some(
+    (participant) => participant !== executor,
+  );
+  if (verifier === executor && independentAvailable) {
+    throw new Error(
+      'verification must be assigned to an agent other than the executor when one is available',
+    );
+  }
+  const decisiveContributors = [
+    ...new Set(
+      strings(payload.decisiveContributors, 'decisiveContributors', true).map((value) =>
+        safeSegment(value),
+      ),
+    ),
+  ];
+  for (const contributor of decisiveContributors) {
+    if (contributor !== 'seat' && !state.brief.participants.includes(contributor)) {
+      throw new Error(`${contributor} was not a selected contributor in this deliberation`);
+    }
+  }
+  const decision: Decision = {
+    id: randomId('decision'),
+    outcome: text(payload.outcome, 'outcome'),
+    rationale: text(payload.rationale, 'rationale'),
+    owner: text(payload.owner, 'owner'),
+    executor,
+    verifier,
+    verificationQuestion: text(payload.verificationQuestion, 'verificationQuestion'),
+    selectedEvidence: strings(payload.selectedEvidence, 'selectedEvidence', true),
+    decisiveContributors,
+    rejectedOptions: strings(payload.rejectedOptions, 'rejectedOptions'),
+    dissent: strings(payload.dissent, 'dissent'),
+    reopenIf: strings(payload.reopenIf, 'reopenIf', true),
+    decidedAt: isoNow(),
+  };
+  state.decisions.push(decision);
+  state.status = 'verifying';
+  return {
+    state,
+    deliveries: [
+      {
+        kind: 'committee.verification.assigned',
+        to: verifier,
+        payload: {
+          decision: decision.outcome,
+          verificationQuestion: decision.verificationQuestion,
+          executor,
+          independent: verifier !== executor,
+        },
+      },
+    ],
+  };
+}
+
+export function verify(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+): TransitionResult {
+  const decision = currentDecision(state);
+  if (state.status !== 'verifying') throw new Error('no decision is awaiting verification');
+  if (actor !== decision.verifier) throw new Error(`verification belongs to ${decision.verifier}`);
+  const result = oneOf(payload.result, VERIFY_RESULTS, 'result');
+  decision.verification = {
+    result,
+    evidence: strings(payload.evidence, 'evidence', true),
+    checks: strings(payload.checks, 'checks', true),
+    residualRisks: strings(payload.residualRisks, 'residualRisks'),
+    verifiedBy: actor,
+    verifiedAt: isoNow(),
+  };
+  state.status = result === 'pass' ? 'verified' : 'verification_failed';
+  return {
+    state,
+    deliveries: [
+      {
+        kind: result === 'pass' ? 'committee.verification.passed' : 'committee.verification.failed',
+        to: 'seat',
+        payload: { decisionId: decision.id, verification: decision.verification },
+      },
+    ],
+  };
+}
+
+export function replan(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireChair(actor, role);
+  if (state.status !== 'verification_failed')
+    throw new Error('replanning follows a failed verification');
+  text(payload.reason, 'reason');
+  state.status = 'review';
+  state.synthesis = null;
+  state.floor = { requests: [], active: null, replies: [] };
+  state.progress.revision += 1;
+  state.progress.failedVerifications += 1;
+  return { state, deliveries: [] };
+}
+
+export function closeDeliberation(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireChair(actor, role);
+  if (state.status !== 'verified')
+    throw new Error('a deliberation closes only after verification passes');
+  state.closure = {
+    summary: text(payload.summary, 'summary'),
+    learnings: strings(payload.learnings, 'learnings'),
+    followups: strings(payload.followups, 'followups'),
+    closedAt: isoNow(),
+  };
+  state.status = 'closed';
+  return {
+    state,
+    deliveries: state.brief.participants.map((to) => ({
+      kind: 'committee.closed',
+      to,
+      payload: { decision: currentDecision(state).outcome, closure: state.closure },
+    })),
+  };
+}
+
+export function cancelDeliberation(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireChair(actor, role);
+  const reason = text(payload.reason, 'reason');
+  state.status = 'cancelled';
+  return {
+    state,
+    deliveries: state.brief.participants.map((to) => ({
+      kind: 'committee.cancelled',
+      to,
+      payload: { reason },
+    })),
+  };
+}