agents-city 0.3.0-beta.21

package/plugin/channel/committee/floor.ts

@@ -0,0 +1,135 @@
+import { ActorRole, isoNow, oneOf, randomId, strings, text } from '../protocol.js';
+import { requireChair, requireMember } from './guards.js';
+import { DeliberationState, FLOOR_BASES, FloorRequest, TransitionResult } from './types.js';
+
+export function requestFloor(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireMember(state, actor, role);
+  if (state.status !== 'deliberating')
+    throw new Error('the floor opens only after the chair synthesis');
+  const alreadyUsed = state.floor.replies.filter((reply) => reply.actor === actor).length;
+  const alreadyPending = state.floor.requests.some(
+    (request) => request.actor === actor && ['pending', 'granted'].includes(request.status),
+  );
+  if (alreadyPending) throw new Error(`${actor} already has a pending floor request`);
+  if (alreadyUsed >= state.brief.maxRebuttals) {
+    throw new Error(`${actor} reached this deliberation's rebuttal limit`);
+  }
+  const request: FloorRequest = {
+    id: randomId('floor'),
+    actor,
+    basis: oneOf(payload.basis, FLOOR_BASES, 'basis'),
+    reason: text(payload.reason, 'reason'),
+    evidence: strings(payload.evidence, 'evidence', true),
+    status: 'pending',
+    requestedAt: isoNow(),
+  };
+  state.floor.requests.push(request);
+  return {
+    state,
+    deliveries: [{ kind: 'committee.floor.requested', to: 'seat', payload: { request } }],
+  };
+}
+
+export function grantFloor(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireChair(actor, role);
+  if (state.status !== 'deliberating') throw new Error('there is no open deliberation floor');
+  if (state.floor.active)
+    throw new Error(`the floor already belongs to ${state.floor.active.actor}`);
+  const request = pendingRequest(state, text(payload.requestId, 'requestId'));
+  request.status = 'granted';
+  request.decidedAt = isoNow();
+  state.floor.active = { requestId: request.id, actor: request.actor, grantedAt: isoNow() };
+  return {
+    state,
+    deliveries: [
+      {
+        kind: 'committee.floor.granted',
+        to: request.actor,
+        payload: { requestId: request.id, basis: request.basis, oneReply: true },
+      },
+    ],
+  };
+}
+
+export function denyFloor(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireChair(actor, role);
+  const request = pendingRequest(state, text(payload.requestId, 'requestId'));
+  request.status = 'denied';
+  request.decidedAt = isoNow();
+  request.decisionReason = text(payload.reason, 'reason');
+  return {
+    state,
+    deliveries: [
+      {
+        kind: 'committee.floor.denied',
+        to: request.actor,
+        payload: { requestId: request.id, reason: request.decisionReason },
+      },
+    ],
+  };
+}
+
+export function replyOnFloor(
+  state: DeliberationState,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+): TransitionResult {
+  requireMember(state, actor, role);
+  if (!state.floor.active || state.floor.active.actor !== actor) {
+    throw new Error('the chair has not granted this agent the floor');
+  }
+  const request = state.floor.requests.find((item) => item.id === state.floor.active?.requestId);
+  if (!request || request.status !== 'granted')
+    throw new Error('the floor grant is no longer valid');
+  const reply = {
+    requestId: request.id,
+    actor,
+    claim: text(payload.claim, 'claim'),
+    evidence: strings(payload.evidence, 'evidence', true),
+    consequence: text(payload.consequence, 'consequence'),
+    repliedAt: isoNow(),
+  };
+  state.floor.replies.push(reply);
+  request.status = 'used';
+  state.floor.active = null;
+  const heardBy = state.brief.participants.filter((participant) => participant !== actor);
+  return {
+    state,
+    deliveries: [
+      { kind: 'committee.reply.received', to: 'seat', payload: { reply } },
+      ...heardBy.map((to) => ({
+        kind: 'committee.reply.heard',
+        to,
+        payload: {
+          reply,
+          speaker: actor,
+          note: 'This was a chair-granted intervention. Request the floor only if you can add new evidence, a contradiction, a material risk or a dependency.',
+        },
+      })),
+    ],
+  };
+}
+
+function pendingRequest(state: DeliberationState, requestId: string): FloorRequest {
+  const request = state.floor.requests.find(
+    (item) => item.id === requestId && item.status === 'pending',
+  );
+  if (!request) throw new Error('that pending floor request does not exist');
+  return request;
+}

package/plugin/channel/committee/guards.ts

@@ -0,0 +1,30 @@
+import { ActorRole } from '../protocol.js';
+import { ActorDirectory, Decision, DeliberationState, TERMINAL_STATUSES } from './types.js';
+
+export function requireChair(actor: string, role: ActorRole): void {
+  if (role !== 'chair' || actor !== 'seat') throw new Error('only the city chair can do that');
+}
+
+export function requireMember(state: DeliberationState, actor: string, role: ActorRole): void {
+  if (role !== 'member' || !state.brief.participants.includes(actor)) {
+    throw new Error(`${actor} is not a selected member of this deliberation`);
+  }
+}
+
+export function requireOpen(state: DeliberationState): void {
+  if (TERMINAL_STATUSES.has(state.status)) {
+    throw new Error(`deliberation is ${state.status} and immutable`);
+  }
+}
+
+export function currentDecision(state: DeliberationState): Decision {
+  const decision = state.decisions.at(-1);
+  if (!decision) throw new Error('this deliberation has no current decision');
+  return decision;
+}
+
+export function requireKnownVerifier(verifier: string, actors: ActorDirectory): void {
+  if (verifier !== 'seat' && actors[verifier]?.role !== 'member') {
+    throw new Error(`${verifier} is not an agent in this city`);
+  }
+}

package/plugin/channel/committee/history.ts

@@ -0,0 +1,38 @@
+import { DecisionHistory, DeliberationState } from './types.js';
+
+const HISTORY_LIMIT = 8;
+
+/** Concise chair-only memory. Frequency is surfaced, never treated as a verdict. */
+export function decisionHistory(states: DeliberationState[], current = ''): DecisionHistory {
+  const records = states
+    .filter((state) => state.id !== current)
+    .flatMap((state) =>
+      state.decisions.map((decision) => ({
+        deliberation: state.id,
+        question: state.brief.question,
+        outcome: decision.outcome,
+        decisiveContributors: decision.decisiveContributors || [],
+        verification: decision.verification?.result || 'pending',
+        decidedAt: decision.decidedAt,
+        reopenIf: decision.reopenIf,
+      })),
+    )
+    .sort((left, right) => right.decidedAt.localeCompare(left.decidedAt));
+
+  const counts = new Map<string, number>();
+  for (const record of records) {
+    for (const actor of new Set(record.decisiveContributors)) {
+      counts.set(actor, (counts.get(actor) || 0) + 1);
+    }
+  }
+  const contributorCounts = [...counts]
+    .map(([actor, decisions]) => ({ actor, decisions }))
+    .sort(
+      (left, right) => right.decisions - left.decisions || left.actor.localeCompare(right.actor),
+    );
+  return {
+    recent: records.slice(0, HISTORY_LIMIT),
+    contributorCounts,
+    note: 'Repeated influence is a review signal, not proof of capture. Re-read dissent and reopen conditions before deciding.',
+  };
+}

package/plugin/channel/committee/render.ts

@@ -0,0 +1,102 @@
+import { writeFileSync, renameSync } from 'fs';
+import { join } from 'path';
+import { DeliberationState } from './types.js';
+
+export function renderAct(state: DeliberationState, directory: string): void {
+  const lines = [
+    `# ${state.brief.question}`,
+    '',
+    `- **ID:** \`${state.id}\``,
+    `- **Status:** ${state.status}`,
+    `- **Chair:** ${state.city.address}#seat`,
+    `- **Authority:** ${state.brief.authority}`,
+    `- **Desired outcome:** ${state.brief.desiredOutcome}`,
+    '',
+    '## Brief',
+    '',
+    state.brief.context || '_No extra context._',
+    '',
+    '### Constraints',
+    '',
+    ...(state.brief.constraints.length
+      ? state.brief.constraints.map((x) => `- ${x}`)
+      : ['- None stated.']),
+    '',
+    '### Definition of done',
+    '',
+    ...state.brief.definitionOfDone.map((x) => `- ${x}`),
+    '',
+    '## Participants',
+    '',
+    ...state.brief.participants.map(
+      (actor) =>
+        `- \`${actor}\` (${state.participantRepos[actor]}) · role ${state.participantRoles?.[actor] || 'blank'} — ${state.positions[actor] ? 'position received' : 'pending'}`,
+    ),
+    '',
+  ];
+
+  // Keep the initial-position barrier visible in the durable human record too.
+  if (state.status !== 'collecting') appendPositions(lines, state);
+  appendDecision(lines, state);
+  appendClosure(lines, state);
+
+  const path = join(directory, 'ACT.md');
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, lines.join('\n') + '\n', { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+function appendPositions(lines: string[], state: DeliberationState): void {
+  lines.push('## Independent positions', '');
+  for (const actor of state.brief.participants) {
+    const p = state.positions[actor];
+    if (!p) continue;
+    lines.push(
+      `### ${actor} — ${p.stance}`,
+      '',
+      p.recommendation,
+      '',
+      ...p.evidence.map((e) => `- Evidence: ${e}`),
+      `- Expected impact: ${p.expectedImpact || 'not quantified'}`,
+      `- Visible: ${p.visibleWhen || 'unknown'}`,
+      `- Would withdraw if: ${p.withdrawIf || 'not stated'}`,
+      '',
+    );
+  }
+}
+
+function appendDecision(lines: string[], state: DeliberationState): void {
+  const decision = state.decisions.at(-1);
+  if (!decision) return;
+  lines.push(
+    '## Decision',
+    '',
+    decision.outcome,
+    '',
+    `- Rationale: ${decision.rationale}`,
+    `- Owner: ${decision.owner}`,
+    `- Executor: ${decision.executor}`,
+    `- Verifier: ${decision.verifier}`,
+    `- Decisive contributors: ${(decision.decisiveContributors || []).join(', ') || 'not recorded'}`,
+    ...decision.dissent.map((x) => `- Dissent preserved: ${x}`),
+    ...decision.reopenIf.map((x) => `- Reopen if: ${x}`),
+    '',
+  );
+  if (!decision.verification) return;
+  lines.push(
+    '## Verification',
+    '',
+    `**${decision.verification.result.toUpperCase()}** by ${decision.verification.verifiedBy}.`,
+    '',
+    ...decision.verification.evidence.map((x) => `- ${x}`),
+    '',
+  );
+}
+
+function appendClosure(lines: string[], state: DeliberationState): void {
+  if (!state.closure) return;
+  lines.push('## Closure', '', state.closure.summary, '');
+  for (const x of state.closure.learnings) lines.push(`- Learning: ${x}`);
+  for (const x of state.closure.followups) lines.push(`- Follow-up: ${x}`);
+  lines.push('');
+}

package/plugin/channel/committee/service.ts

@@ -0,0 +1,72 @@
+import { ActorRole, asObject } from '../protocol.js';
+import { openDeliberation, publishSynthesis, submitPosition } from './collection.js';
+import { cancelDeliberation, closeDeliberation, decide, replan, verify } from './decision.js';
+import { denyFloor, grantFloor, replyOnFloor, requestFloor } from './floor.js';
+import { requireOpen } from './guards.js';
+import { decisionHistory } from './history.js';
+import { CommitteeFiles } from './storage.js';
+import { ActorDirectory, CityIdentity, TransitionResult } from './types.js';
+import { committeeView } from './view.js';
+
+interface CommitteeServiceOptions {
+  files: CommitteeFiles;
+  city: CityIdentity;
+  actors: ActorDirectory;
+}
+
+export function committeeService({ files, city, actors }: CommitteeServiceOptions) {
+  const transition = (
+    command: string,
+    thread: string | undefined,
+    value: unknown,
+    actor: string,
+    role: ActorRole,
+  ): TransitionResult => {
+    const payload = asObject(value);
+    let result: TransitionResult;
+    if (command === 'committee.open') {
+      result = openDeliberation(payload, actor, role, city, actors);
+    } else {
+      if (!thread) throw new Error('thread is required');
+      const state = files.load(thread);
+      requireOpen(state);
+      result = runTransition(command, state, payload, actor, role, actors);
+    }
+    files.save(result.state, { type: command, actor, role, payload });
+    return result;
+  };
+
+  return {
+    transition,
+    list: () => files.list(),
+    history: (current = '') => decisionHistory(files.list(), current),
+    view: (thread: string, actor: string, role: ActorRole) => {
+      const state = files.load(thread);
+      const history = role === 'chair' ? decisionHistory(files.list(), thread) : undefined;
+      return committeeView(state, actor, role, history);
+    },
+  };
+}
+
+function runTransition(
+  command: string,
+  state: ReturnType<CommitteeFiles['load']>,
+  payload: Record<string, unknown>,
+  actor: string,
+  role: ActorRole,
+  actors: ActorDirectory,
+): TransitionResult {
+  const common = [state, payload, actor, role] as const;
+  if (command === 'committee.respond') return submitPosition(...common);
+  if (command === 'committee.synthesize') return publishSynthesis(...common);
+  if (command === 'committee.floor.request') return requestFloor(...common);
+  if (command === 'committee.floor.grant') return grantFloor(...common);
+  if (command === 'committee.floor.deny') return denyFloor(...common);
+  if (command === 'committee.reply') return replyOnFloor(...common);
+  if (command === 'committee.decide') return decide(...common, actors);
+  if (command === 'committee.verify') return verify(state, payload, actor);
+  if (command === 'committee.replan') return replan(...common);
+  if (command === 'committee.close') return closeDeliberation(...common);
+  if (command === 'committee.cancel') return cancelDeliberation(...common);
+  throw new Error(`unknown committee transition: ${command}`);
+}

package/plugin/channel/committee/storage.ts

@@ -0,0 +1,92 @@
+import {
+  appendFileSync,
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import { ActorRole, THREAD_RE, isoNow } from '../protocol.js';
+import { renderAct } from './render.js';
+import { CommitteeEvent, DeliberationState } from './types.js';
+
+export interface CommitteeFiles {
+  root: string;
+  directory(id: string): string;
+  load(id: string): DeliberationState;
+  list(): DeliberationState[];
+  save(
+    state: DeliberationState,
+    event: { type: string; actor: string; role: ActorRole; payload: Record<string, unknown> },
+  ): void;
+}
+
+export function committeeFiles(dataDir: string): CommitteeFiles {
+  const root = join(dataDir, 'deliberations');
+  let counter = 0;
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+
+  const directory = (id: string): string => {
+    if (!THREAD_RE.test(id)) throw new Error('invalid deliberation id');
+    return join(root, id);
+  };
+
+  const load = (id: string): DeliberationState => {
+    const state = JSON.parse(
+      readFileSync(join(directory(id), 'state.json'), 'utf8'),
+    ) as DeliberationState;
+    if (state.schema !== 'agents-city/deliberation@1' || state.id !== id) {
+      throw new Error(`unreadable deliberation ${id}`);
+    }
+    return state;
+  };
+
+  const list = (): DeliberationState[] => {
+    let names: string[] = [];
+    try {
+      names = readdirSync(root).filter((name) => THREAD_RE.test(name));
+    } catch {}
+    return names
+      .map((name) => {
+        try {
+          return load(name);
+        } catch {
+          return null;
+        }
+      })
+      .filter((state): state is DeliberationState => state !== null)
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  };
+
+  const save = (
+    state: DeliberationState,
+    event: { type: string; actor: string; role: ActorRole; payload: Record<string, unknown> },
+  ): void => {
+    state.updatedAt = isoNow();
+    const dir = directory(state.id);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, 'state.json');
+    const tmp = `${path}.tmp-${process.pid}-${counter++}`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+      chmodSync(path, 0o600);
+    } catch {}
+
+    const events = join(dir, 'events.jsonl');
+    let seq = 1;
+    if (existsSync(events)) {
+      try {
+        seq = readFileSync(events, 'utf8').split('\n').filter(Boolean).length + 1;
+      } catch {}
+    }
+    const record: CommitteeEvent = { seq, at: isoNow(), ...event };
+    appendFileSync(events, JSON.stringify(record) + '\n', { mode: 0o600 });
+    renderAct(state, dir);
+  };
+
+  return { root, directory, load, list, save };
+}

package/plugin/channel/committee/types.ts

@@ -0,0 +1,163 @@
+import { ActorRole } from '../protocol.js';
+
+export const STANCES = ['support', 'oppose', 'conditional', 'abstain'] as const;
+export const FLOOR_BASES = ['new_evidence', 'contradiction', 'risk', 'dependency'] as const;
+export const AUTHORITIES = ['recommend', 'decide', 'execute'] as const;
+export const VERIFY_RESULTS = ['pass', 'fail'] as const;
+export const TERMINAL_STATUSES = new Set(['closed', 'cancelled']);
+
+export type DeliberationStatus =
+  | 'collecting'
+  | 'review'
+  | 'deliberating'
+  | 'verifying'
+  | 'verified'
+  | 'verification_failed'
+  | 'closed'
+  | 'cancelled';
+
+export interface CityIdentity {
+  id: string;
+  address: string;
+  name: string;
+}
+
+export interface Position {
+  stance: (typeof STANCES)[number];
+  recommendation: string;
+  evidence: string[];
+  expectedImpact: string;
+  visibleWhen: string;
+  withdrawIf: string;
+  risks: string[];
+  unknowns: string[];
+  submittedAt: string;
+}
+
+export interface FloorRequest {
+  id: string;
+  actor: string;
+  basis: (typeof FLOOR_BASES)[number];
+  reason: string;
+  evidence: string[];
+  status: 'pending' | 'granted' | 'used' | 'denied';
+  requestedAt: string;
+  decidedAt?: string;
+  decisionReason?: string;
+}
+
+export interface Decision {
+  id: string;
+  outcome: string;
+  rationale: string;
+  owner: string;
+  executor: string;
+  verifier: string;
+  verificationQuestion: string;
+  selectedEvidence: string[];
+  decisiveContributors: string[];
+  rejectedOptions: string[];
+  dissent: string[];
+  reopenIf: string[];
+  decidedAt: string;
+  verification?: {
+    result: (typeof VERIFY_RESULTS)[number];
+    evidence: string[];
+    checks: string[];
+    residualRisks: string[];
+    verifiedBy: string;
+    verifiedAt: string;
+  };
+}
+
+export interface DeliberationState {
+  schema: 'agents-city/deliberation@1';
+  id: string;
+  city: CityIdentity;
+  parent: string | null;
+  status: DeliberationStatus;
+  createdAt: string;
+  updatedAt: string;
+  brief: {
+    question: string;
+    desiredOutcome: string;
+    context: string;
+    constraints: string[];
+    definitionOfDone: string[];
+    authority: (typeof AUTHORITIES)[number];
+    participants: string[];
+    maxRebuttals: number;
+  };
+  participantRepos: Record<string, string>;
+  /** Professional perspective, distinct from the chair/member authority role. */
+  participantRoles?: Record<string, string>;
+  positions: Record<string, Position>;
+  synthesis: null | {
+    summary: string;
+    agreements: string[];
+    conflicts: string[];
+    unknowns: string[];
+    missing: string[];
+    proceedWithout: string;
+    publishedAt: string;
+  };
+  floor: {
+    requests: FloorRequest[];
+    active: null | { requestId: string; actor: string; grantedAt: string };
+    replies: Array<{
+      requestId: string;
+      actor: string;
+      claim: string;
+      evidence: string[];
+      consequence: string;
+      repliedAt: string;
+    }>;
+  };
+  decisions: Decision[];
+  closure: null | {
+    summary: string;
+    learnings: string[];
+    followups: string[];
+    closedAt: string;
+  };
+  progress: { revision: number; failedVerifications: number };
+}
+
+export interface CommitteeEvent {
+  seq: number;
+  at: string;
+  type: string;
+  actor: string;
+  role: ActorRole;
+  payload: Record<string, unknown>;
+}
+
+export interface Delivery {
+  kind: string;
+  to: string;
+  payload: Record<string, unknown>;
+}
+
+export interface TransitionResult {
+  state: DeliberationState;
+  deliveries: Delivery[];
+}
+
+export interface DecisionHistory {
+  recent: Array<{
+    deliberation: string;
+    question: string;
+    outcome: string;
+    decisiveContributors: string[];
+    verification: string;
+    decidedAt: string;
+    reopenIf: string[];
+  }>;
+  contributorCounts: Array<{ actor: string; decisions: number }>;
+  note: string;
+}
+
+export type ActorDirectory = Record<
+  string,
+  { role: ActorRole; repo?: string; operatingRole?: string }
+>;

package/plugin/channel/committee/view.ts

@@ -0,0 +1,63 @@
+import { ActorRole } from '../protocol.js';
+import { requireChair, requireMember } from './guards.js';
+import { DecisionHistory, DeliberationState } from './types.js';
+
+export function committeeView(
+  state: DeliberationState,
+  actor: string,
+  role: ActorRole,
+  history?: DecisionHistory,
+): Record<string, unknown> {
+  const progress = {
+    status: state.status,
+    received: Object.keys(state.positions).length,
+    total: state.brief.participants.length,
+    missing: state.brief.participants.filter((participant) => !state.positions[participant]),
+    pendingFloor: state.floor.requests.filter((request) => request.status === 'pending').length,
+    activeFloor: state.floor.active?.actor || null,
+    revision: state.progress.revision,
+    failedVerifications: state.progress.failedVerifications,
+  };
+  const base: Record<string, unknown> = {
+    schema: state.schema,
+    id: state.id,
+    city: state.city,
+    brief: state.brief,
+    participantRepos: state.participantRepos,
+    participantRoles: state.participantRoles || {},
+    progress,
+  };
+  if (role === 'member') {
+    const selected = state.brief.participants.includes(actor);
+    const assignedVerifier = state.decisions.at(-1)?.verifier === actor;
+    if (!selected && !assignedVerifier) requireMember(state, actor, role);
+    return {
+      ...base,
+      myPosition: state.positions[actor] || null,
+      synthesis: state.synthesis,
+      myFloorRequests: state.floor.requests.filter((request) => request.actor === actor),
+      myReplies: state.floor.replies.filter((reply) => reply.actor === actor),
+      decision: state.decisions.at(-1) || null,
+      closure: state.closure,
+    };
+  }
+  requireChair(actor, role);
+  return {
+    ...base,
+    // The chair sees all positions at once. Early arrivals cannot anchor it.
+    positions:
+      state.status === 'collecting'
+        ? Object.fromEntries(
+            state.brief.participants.map((participant) => [
+              participant,
+              state.positions[participant] ? 'received-hidden' : 'pending',
+            ]),
+          )
+        : state.positions,
+    synthesis: state.synthesis,
+    floor: state.floor,
+    decisions: state.decisions,
+    closure: state.closure,
+    history,
+  };
+}