@ci-kit/roundtable 0.0.1 → 0.3.1

package/dist/index.d.ts

@@ -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 };