@ci-kit/roundtable 0.0.1 → 0.3.1

package/dist/chunks/example.mjs

@@ -0,0 +1,194 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+
+const TABLE = `---
+title: \u6BCF\u65E5\u4F8B\u4F1A
+schedule: daily
+budget:
+  total: 12
+  perSeat: 4
+
+phases:
+  - id: propose
+    seats: [editor]
+  - id: discuss
+    seats: [writer, guard]
+  - id: produce
+    seats: [writer]
+  - id: review
+    seats: [guard]
+    vetoable: true
+  - id: converge
+    seats: [host]
+
+onVeto: re-propose
+maxAttempts: 3
+# Optional: how long one seat's model call may take. Seat work is slower than a
+# short request, so a reviewing table usually wants more than the transport
+# default. Omit to keep that default.
+# timeoutMs: 180000
+---
+
+\u8FD9\u662F\u4E00\u4E2A\u793A\u4F8B\u5706\u684C\u3002\u6539\u5B8C frontmatter \u5C31\u80FD\u7528\uFF0C\u6B63\u6587\u53EF\u4EE5\u7559\u7A7A\u3002
+
+## propose
+
+\u4ECE\u7ED9\u5B9A\u6750\u6599\u91CC\u63D0\u51FA\u4E00\u4E2A\u5177\u4F53\u3001\u53EF\u6267\u884C\u3001\u503C\u5F97\u73B0\u5728\u505A\u7684\u8BAE\u9898\u3002
+
+## converge
+
+\u6C47\u603B\u672C\u8F6E\u7684\u7ED3\u8BBA\u3001\u9057\u7559\u5206\u6B67\u548C\u4E0B\u4E00\u6B65\u52A8\u4F5C\u3002
+`;
+const SEATS = [
+  {
+    name: "editor.md",
+    content: `---
+id: editor
+role: \u9009\u9898\u7F16\u8F91
+
+identity:
+  name: \u6797\u5C0F\u6EE1
+  avatar: \u270D\uFE0F
+  title: \u8DD1\u4E86\u516D\u5E74\u4E00\u7EBF\u7684\u8001\u7F16\u8F91
+  background: \u89C1\u8FC7\u592A\u591A\u7EB8\u4E0A\u65B9\u6848\uFF0C\u4E60\u60EF\u5148\u95EE\u95E8\u5E97\u771F\u80FD\u8FD9\u4E48\u505A\u5417
+
+persona:
+  stance: \u5B81\u53EF\u9009\u5C0F\uFF0C\u53EF\u9009\u5177\u4F53
+  personality: [\u8F83\u771F, \u5BF9\u6A21\u7CCA\u8BF4\u8F9E\u654F\u611F]
+  style: \u76F4\u63A5\u3001\u77ED\u53E5
+  speech: \u5148\u7ED9\u7ED3\u8BBA\u518D\u7ED9\u7406\u7531\uFF0C\u4E00\u6B21\u53EA\u95EE\u4E00\u4E2A\u95EE\u9898
+  values: \u4E00\u4E2A\u5199\u4E0D\u51FA\u52A8\u4F5C\u7684\u9009\u9898\uFF0C\u4E0D\u662F\u9009\u9898
+  quirks: \u63D0\u5230\u6570\u636E\u5FC5\u8FFD\u95EE\u53E3\u5F84
+  avoid: \u4E0D\u8BC4\u4EF7\u6587\u98CE
+
+seat:
+  phase: [propose]
+  canPropose: true
+  budget: 2
+---
+
+\u4F60\u8D1F\u8D23\u4ECE\u6750\u6599\u91CC\u6311\u51FA\u4E00\u4E2A\u503C\u5F97\u505A\u7684\u5177\u4F53\u8BAE\u9898\u3002
+
+## \u804C\u8D23
+- \u7ED9\u51FA\u4E00\u4E2A\u8BAE\u9898\u548C\u9009\u62E9\u5B83\u7684\u7406\u7531
+- \u8BF4\u660E\u4E3A\u4EC0\u4E48\u662F\u73B0\u5728
+- \u4E0D\u5199\u6B63\u6587\uFF0C\u53EA\u5B9A\u65B9\u5411
+`
+  },
+  {
+    name: "writer.md",
+    content: `---
+id: writer
+role: \u4F5C\u8005
+
+identity:
+  name: \u9648\u9ED8
+  avatar: \u270F\uFE0F
+  title: \u5199\u4E1C\u897F\u7684\u4EBA
+
+persona:
+  stance: \u5148\u505A\u51FA\u6765\u518D\u8BA8\u8BBA
+  style: \u5177\u4F53\u3001\u4E0D\u7ED5\u5F2F
+
+seat:
+  phase: [discuss, produce]
+  budget: 4
+---
+
+\u4F60\u8D1F\u8D23\u628A\u65B9\u5411\u843D\u6210\u5B9E\u9645\u7ED3\u679C\u3002
+
+## \u804C\u8D23
+- \u8BA8\u8BBA\u9636\u6BB5\uFF1A\u5BF9\u8BAE\u9898\u7ED9\u51FA\u53EF\u884C\u6027\u4E0E\u98CE\u9669\u5224\u65AD
+- \u4EA7\u51FA\u9636\u6BB5\uFF1A\u6309\u5DF2\u8FBE\u6210\u7684\u65B9\u5411\u5199\u51FA\u5B8C\u6574\u7ED3\u679C
+`
+  },
+  {
+    name: "guard.md",
+    content: `---
+id: guard
+role: \u4E8B\u5B9E\u5BA1\u6838
+
+identity:
+  name: \u5468\u614E
+  avatar: \u{1F6E1}\uFE0F
+  title: \u505A\u4E86\u5341\u5E74\u4E8B\u5B9E\u6838\u67E5\u7684\u8001\u5BA1\u6838
+
+persona:
+  stance: \u5B81\u53EF\u9519\u6740\uFF0C\u4E0D\u53EF\u653E\u8FC7
+  personality: [\u8F83\u771F, \u4E0D\u7559\u60C5\u9762]
+  style: \u51B7\u9759\u3001\u9010\u6761
+
+seat:
+  phase: [discuss, review]
+  sees: none
+  canVeto: true
+  weight: 2
+  budget: 3
+  output: json
+---
+
+\u4F60\u8D1F\u8D23\u6838\u5BF9\u4EA7\u51FA\u662F\u5426\u6709\u4F9D\u636E\u3002
+
+## \u8F93\u51FA
+\u53EA\u8FD4\u56DE JSON\uFF1A{"verdict":"pass \u6216 reject","score":0,"issues":[],"reason":"\u5426\u51B3\u7406\u7531\uFF0C\u901A\u8FC7\u65F6\u7559\u7A7A"}
+`
+  },
+  {
+    name: "host.md",
+    content: `---
+id: host
+role: \u4E3B\u6301
+
+identity:
+  name: \u4F55\u4E00
+  avatar: \u{1F3AF}
+  title: \u8D1F\u8D23\u6536\u53E3\u7684\u4EBA
+
+persona:
+  stance: \u8BA9\u5171\u8BC6\u53EF\u6267\u884C
+
+seat:
+  phase: [converge]
+  lead: true
+  budget: 2
+---
+
+\u4F60\u8D1F\u8D23\u6536\u53E3\u3002
+
+## \u804C\u8D23
+- \u7ED9\u51FA\u7ED3\u8BBA
+- \u5217\u51FA\u4ECD\u672A\u89E3\u51B3\u7684\u5206\u6B67
+- \u7ED9\u51FA\u4E0B\u4E00\u6B65\u52A8\u4F5C
+`
+  }
+];
+async function writeExample(dir, force = false) {
+  const target = resolve(dir);
+  const files = [
+    {
+      path: join(target, "table.md"),
+      content: TABLE
+    },
+    ...SEATS.map((seat) => ({
+      path: join(target, "seats", seat.name),
+      content: seat.content
+    }))
+  ];
+  if (!force) {
+    for (const file of files) {
+      const exists = await access(file.path).then(() => true).catch(() => false);
+      if (exists) {
+        throw new Error(`${file.path} already exists; pass --force to overwrite`);
+      }
+    }
+  }
+  const written = [];
+  for (const file of files) {
+    await mkdir(join(file.path, ".."), { recursive: true });
+    await writeFile(file.path, file.content, "utf8");
+    written.push(file.path);
+  }
+  return written;
+}
+
+export { writeExample };

package/dist/cli.mjs

@@ -1,26 +1,84 @@
 #!/usr/bin/env node
 import process from 'node:process';
 import { cac } from 'cac';
+import { loadRoundtable, defaultOutDir, runRoundtable, resumeRoundtable, RoundtableConfigError } from './index.mjs';
+import 'node:fs/promises';
+import 'node:path';
+import 'node:crypto';
+import '@ci-kit/ai';
 
-const version = "0.0.1";
+const version = "0.3.1";
 const pkg = {
 	version: version};
 
 const cli = cac("ci-kit-roundtable");
+function reportError(error) {
+  const message = error instanceof RoundtableConfigError ? `config: ${error.message}` : error instanceof Error ? error.message : String(error);
+  process.stderr.write(`ci-kit-roundtable: ${message}
+`);
+  process.exit(2);
+}
 cli.command("check", "Validate table.md and seats without calling a model").option("--config <dir>", "Roundtable directory", { default: ".ci-kit/roundtable" }).action(async (options) => {
-  const { checkRoundtable } = await import('./index.mjs');
-  await checkRoundtable({ configDir: options.config ?? ".ci-kit/roundtable" });
+  try {
+    const loaded = await loadRoundtable({ configDir: options.config ?? ".ci-kit/roundtable" });
+    const phases = loaded.phases.map((phase) => `${phase.id}(${phase.seats.join(", ")})`).join(" \u2192 ");
+    process.stdout.write(`roundtable: ok \xB7 ${loaded.seats.length} seats \xB7 ${loaded.phases.length} phases
+`);
+    process.stdout.write(`  ${phases}
+`);
+    process.stdout.write(`  title: ${loaded.table.title}
+`);
+  } catch (error) {
+    reportError(error);
+  }
 });
-cli.command("run", "Run one meeting").option("--config <dir>", "Roundtable directory", { default: ".ci-kit/roundtable" }).option("--out <dir>", "Directory for run folders", { default: "roundtable-out" }).option("--topic <text>", "Optional topic override; seats propose their own by default").action(async (options) => {
-  const { runRoundtable } = await import('./index.mjs');
-  const result = await runRoundtable({
-    configDir: options.config ?? ".ci-kit/roundtable",
-    outDir: options.out,
-    topic: options.topic
-  });
-  process.stdout.write(`roundtable: ${result.status} \xB7 ${result.recordPath}
-`);
-  process.exitCode = result.status === "passed" ? 0 : 1;
+cli.command("run", "Run one meeting").option("--config <dir>", "Roundtable directory", { default: ".ci-kit/roundtable" }).option("--out <dir>", "Directory for run folders", {
+  default: defaultOutDir()
+}).option("--topic <text>", "Optional topic override; seats propose their own by default").option("--context <text>", "Material for the seats, repeatable").option("--resume <dir>", "Continue an interrupted run directory").action(async (options) => {
+  const rawContext = options.context;
+  const context = rawContext === void 0 ? [] : Array.isArray(rawContext) ? rawContext : [rawContext];
+  try {
+    const common = {
+      configDir: String(options.config ?? ".ci-kit/roundtable"),
+      topic: options.topic === void 0 ? void 0 : String(options.topic),
+      context,
+      onProgress: (line) => process.stderr.write(`${line}
+`)
+    };
+    const result = options.resume === void 0 ? await runRoundtable({
+      ...common,
+      outDir: options.out === void 0 ? void 0 : String(options.out)
+    }) : await resumeRoundtable({
+      ...common,
+      runDir: String(options.resume)
+    });
+    const total = result.budgetTotal === void 0 ? "unlimited" : String(result.budgetTotal);
+    const summary = `roundtable: ${result.status} \xB7 ${result.record.attempts} attempt \xB7 ${result.used}/${total} calls \xB7 ${result.runDir}`;
+    if (result.status === "passed") {
+      process.stdout.write(`${summary}
+`);
+    } else {
+      process.stderr.write(`${summary}
+`);
+    }
+    process.exitCode = result.status === "passed" ? 0 : 1;
+  } catch (error) {
+    reportError(error);
+  }
+});
+cli.command("init [dir]", "Write an example roundtable you can edit").option("--force", "Overwrite existing files").action(async (dir, options) => {
+  try {
+    const { writeExample } = await import('./chunks/example.mjs');
+    const written = await writeExample(dir ?? ".ci-kit/roundtable", options.force === true);
+    process.stdout.write(`roundtable: wrote ${written.length} files
+`);
+    for (const path of written) {
+      process.stdout.write(`  ${path}
+`);
+    }
+  } catch (error) {
+    reportError(error);
+  }
 });
 cli.help();
 cli.version(pkg.version);

package/dist/index.d.mts

@@ -1,16 +1,240 @@
+import { text } from '@ci-kit/ai';
+
+type Sees = 'all' | 'none' | 'lead-only' | string[];
+type Fallback = 'skip' | 'retry' | 'abort';
+type SeatOutput = 'text' | 'json' | 'markdown';
+interface SeatIdentity {
+    name: string;
+    avatar?: string;
+    title?: string;
+    background?: string;
+}
+interface SeatPersona {
+    /** Decision tendency. Kept apart from expression so verdicts stay reproducible. */
+    stance?: string;
+    personality: string[];
+    style?: string;
+    speech?: string;
+    values?: string;
+    quirks?: string;
+    avoid?: string;
+}
+interface SeatPowers {
+    /** Phase ids this seat attends; empty means every phase. */
+    phase: string[];
+    sees: Sees;
+    canPropose: boolean;
+    canVeto: boolean;
+    lead: boolean;
+    weight: number;
+    priority: number;
+    budget?: number;
+    fallback: Fallback;
+    output: SeatOutput;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+interface Seat {
+    id: string;
+    role: string;
+    enabled: boolean;
+    identity: SeatIdentity;
+    persona: SeatPersona;
+    seat: SeatPowers;
+    /** Markdown body, used verbatim as the seat's instructions. */
+    body: string;
+    /** File the seat came from, for error messages only. */
+    source: string;
+}
+
+type PhaseMode = 'serial' | 'parallel';
+type OnVeto = 're-propose' | 'revise' | 'abort';
+interface Phase {
+    id: string;
+    /** Seats named here; empty means "derive from every seat's seat.phase". */
+    seats: string[];
+    vetoable: boolean;
+    requires: string[];
+    mode: PhaseMode;
+}
+interface Budget {
+    total?: number;
+    perSeat?: number;
+}
+interface Table {
+    title: string;
+    schedule?: string;
+    budget: Budget;
+    onVeto: OnVeto;
+    maxAttempts: number;
+    threshold: number;
+    /**
+     * How long one seat's model call may take. Undefined keeps the http
+     * package's default.
+     *
+     * A seat reads a whole article and replies with paragraphs, which routinely
+     * needs more than the transport default meant for short requests. The table
+     * owns this because "how long may a seat think" is a property of the review,
+     * not of the provider.
+     */
+    timeoutMs?: number;
+    phases: Phase[];
+    /** Phase ids given the special roles, resolved during validation. */
+    special: {
+        propose: string;
+        converge: string;
+    };
+}
+
+declare class RoundtableConfigError extends Error {
+    constructor(message: string);
+}
+interface LoadedRoundtable {
+    table: Table;
+    seats: Seat[];
+    /** Seats after `enabled` filtering, keyed by id. */
+    byId: Map<string, Seat>;
+    /** Phases with their participant lists resolved. */
+    phases: Phase[];
+    configDir: string;
+    /** Content fingerprint over table, seats and the roundtable schema. */
+    fingerprint: string;
+}
 /**
- * @ci-kit/roundtable
- *
- * Placeholder package. The design is settled in `ai-docs/design-docs/roundtable/`;
- * the implementation has not started yet, so this module exports only the
- * names and types that downstream code may already reference.
+ * Read and validate a roundtable directory without calling any model.
  *
- * Do not add behaviour here before the design document is followed end to end:
- * seat parsing, phase scheduling, programmatic adjudication and resumable runs
- * are one unit, and half of them is worse than none.
+ * Everything a meeting needs to be well defined is checked here: unknown
+ * fields, missing required fields, duplicate ids, phase references and the
+ * table/seat membership intersection. A meeting that starts is a meeting that
+ * can finish.
  */
-declare const ROUNDTABLE_SCHEMA: 1;
-type RoundtableStatus = 'passed' | 'rejected' | 'aborted' | 'failed';
+declare function loadRoundtable(options: {
+    configDir: string;
+    schema?: number;
+}): Promise<LoadedRoundtable>;
+/** Convenience for the CLI: validate and report, never call a model. */
+declare function checkRoundtable(options: {
+    configDir: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<LoadedRoundtable>;
+/** Resolved default output directory. */
+declare function defaultOutDir(cwd?: string): string;
+
+/** One seat's turn in a phase, as seen by later seats. */
+interface Statement {
+    seat: string;
+    name: string;
+    role: string;
+    phase: string;
+    status: StatementStatus;
+    content: string;
+    structured?: unknown;
+    durationMs?: number;
+    model?: string;
+    usage?: {
+        input: number;
+        output: number;
+    };
+    /** One log-safe line when the seat failed. */
+    error?: string;
+    artifacts?: ArtifactRef[];
+}
+type StatementStatus = 'completed' | 'skipped' | 'failed' | 'budget-exhausted' | 'invalid-veto';
+interface ArtifactRef {
+    path: string;
+    bytes: number;
+}
+
+interface Vote {
+    seatId: string;
+    weight: number;
+    /** `undefined` when the seat failed or was skipped, so it cannot count. */
+    vote?: 'pass' | 'reject';
+    /** Set when a veto-capable seat wrote `reject` with a reason. */
+    veto?: boolean;
+    /** Whether the seat actually wrote text for its reason. */
+    hasReason?: boolean;
+}
+interface Judgement {
+    passed: boolean;
+    /** Seats whose valid veto blocked the phase. */
+    vetoed: string[];
+    /** Seats that voted reject without a valid veto. */
+    rejected: string[];
+    /** Weighted pass ratio over seats that actually voted. */
+    score: number;
+    /** Seats whose veto had no reason and was therefore ignored. */
+    invalidVetoes: string[];
+}
+
+type RoundtableStatus = 'running' | 'passed' | 'rejected' | 'aborted' | 'failed';
+type PhaseStatus = 'completed' | 'skipped' | 'failed' | 'budget-exhausted';
+interface PhaseRecord {
+    id: string;
+    status: PhaseStatus;
+    statements: Statement[];
+    judgement?: Judgement;
+    /** True when a completed phase had no input from its dependencies. */
+    pruned?: boolean;
+}
+interface RoundRecord {
+    attempt: number;
+    phases: PhaseRecord[];
+}
+interface BudgetState {
+    total?: number;
+    used: number;
+    perSeat: Record<string, number>;
+    perSeatLimit: Record<string, number | undefined>;
+}
+/** The AI call the engine depends on; injectable so meetings can be tested offline. */
+type TextCaller = typeof text;
+
+declare const RECORD_SCHEMA = 1;
+interface RoundtableRecord {
+    schema: number;
+    title: string;
+    startedAt: string;
+    finishedAt?: string;
+    status: RoundtableStatus;
+    attempts: number;
+    verdict: {
+        passed: boolean;
+        vetoed: string[];
+        rejected: string[];
+        score: number;
+        invalidVetoes: string[];
+    };
+    rounds: RoundRecord[];
+    budget: {
+        total?: number;
+        used: number;
+        perSeat: Record<string, number>;
+    };
+    /** Files produced under artifacts/, referenced by statements. */
+    artifacts?: string[];
+    error?: string;
+}
+interface RunState {
+    schema: number;
+    runId: string;
+    /** `running` until the loop settles on a terminal status. */
+    status: RoundtableStatus | 'running';
+    attempt: number;
+    phaseIndex: number;
+    phaseId?: string;
+    budget: BudgetState;
+    fingerprint: string;
+    resumable: boolean;
+    rounds: RoundRecord[];
+    startedAt: string;
+    finishedAt?: string;
+    topic?: string;
+    context: string[];
+    error?: string;
+}
+
 interface RoundtableOptions {
     /** Directory holding `table.md` and `seats/` */
     configDir: string;
@@ -21,17 +245,45 @@ interface RoundtableOptions {
     /** Where run directories are written */
     outDir?: string;
     env?: NodeJS.ProcessEnv;
+    /** Emit one line per statement while the meeting runs. */
+    onProgress?: (line: string) => void;
+    /** Defaults to `@ci-kit/ai`'s text(); tests pass a stub. */
+    callText?: TextCaller;
 }
 interface RoundtableResult {
     status: RoundtableStatus;
     recordPath: string;
+    /** Directory holding record.json, record.md, state.json. */
+    runDir: string;
+    record: RoundtableRecord;
+    /** Total AI calls consumed. */
+    used: number;
+    budgetTotal?: number;
+}
+/**
+ * Run one meeting.
+ *
+ * Business failure is reported through `status`, never thrown: a rejected
+ * meeting is a normal result. Only configuration and usage errors throw,
+ * because those mean nothing could start.
+ */
+declare function runRoundtable(options: RoundtableOptions): Promise<RoundtableResult>;
+interface ResumeOptions extends Omit<RoundtableOptions, 'outDir'> {
+    /** Run directory produced by a previous, interrupted execution. */
+    runDir: string;
 }
-/** Validate `table.md` and `seats/*.md` without calling a model. */
-declare function loadRoundtable(_options: RoundtableOptions): Promise<never>;
-/** Alias kept for the CLI `check` command: no paid calls, config errors only. */
-declare function checkRoundtable(_options: RoundtableOptions): Promise<never>;
-/** Run one meeting and return its verdict. Business failure is reported via `status`. */
-declare function runRoundtable(_options: RoundtableOptions): Promise<RoundtableResult>;
+/**
+ * Continue an interrupted run from the phase that did not finish.
+ *
+ * Rules are fingerprinted: if a seat or the table changed, the previous
+ * progress described a different meeting and cannot be resumed. That mirrors
+ * "editing a prompt never rewrites an already-published draft".
+ *
+ * A run that already reached a terminal status is returned as-is rather than
+ * re-executed: repeating a finished meeting would spend money to reach the same
+ * answer.
+ */
+declare function resumeRoundtable(options: ResumeOptions): Promise<RoundtableResult>;
 
-export { ROUNDTABLE_SCHEMA, checkRoundtable, loadRoundtable, runRoundtable };
-export type { RoundtableOptions, RoundtableResult, RoundtableStatus };
+export { RECORD_SCHEMA as ROUNDTABLE_SCHEMA, RoundtableConfigError, checkRoundtable, defaultOutDir, loadRoundtable, resumeRoundtable, runRoundtable };
+export type { ArtifactRef, BudgetState, Judgement, LoadedRoundtable, Phase, PhaseMode, PhaseRecord, ResumeOptions, RoundRecord, RoundtableOptions, RoundtableRecord, RoundtableResult, RoundtableStatus, RunState, Seat, SeatIdentity, SeatOutput, SeatPersona, SeatPowers, Statement, StatementStatus, Table, TextCaller, Vote };