@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/analysis_questions.ts

@@ -0,0 +1,78 @@
+/**
+ * analysis_questions.ts — routes every question a run raises by the
+ * ownership classes of `decision_resolution` (ADR-268 § 10): technical ones to
+ * the agent or the council, spend exhaustion to pause-and-report, and only the
+ * owner-locked classes to the owner.
+ *
+ * An owner item that gates an action — a push, a destructive step, a fetch, a
+ * Hard-Floor trigger — is asked before that action, alone. Every other owner
+ * item waits for one batch at the end, each with a recommendation, while the
+ * run continues on everything it does not block.
+ */
+import { DEFAULT_RESOLUTION_MODES, OWNERSHIP_CLASSES } from './ai_council/ownership_classes.js';
+
+export const GATED_ACTIONS = ['push', 'destructive', 'fetch', 'hard-floor'] as const;
+export type GatedAction = (typeof GATED_ACTIONS)[number];
+
+export interface Question {
+    id: string;
+    text: string;
+    ownership: string;
+    gates?: GatedAction;
+    recommendation?: string;
+}
+
+export interface Routed {
+    agent: Question[];
+    council: Question[];
+    pause: Question[];
+    preAction: Record<GatedAction, Question[]>;
+    endBatch: Array<{ id: string; text: string; recommendation: string }>;
+}
+
+export class QuestionError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'QuestionError';
+    }
+}
+
+export function routeQuestions(questions: readonly Question[]): Routed {
+    const routed: Routed = {
+        agent: [],
+        council: [],
+        pause: [],
+        preAction: { push: [], destructive: [], fetch: [], 'hard-floor': [] },
+        endBatch: [],
+    };
+    for (const q of questions) {
+        if (!OWNERSHIP_CLASSES.includes(q.ownership)) {
+            throw new QuestionError(`${q.id}: unknown ownership class ${q.ownership}`);
+        }
+        if (q.ownership === 'spend-exhaustion') {
+            routed.pause.push(q);
+            continue;
+        }
+        // A gated action needs this-turn user confirmation whatever the class,
+        // so the gate is read before the class can route the item elsewhere.
+        if (q.gates !== undefined) {
+            routed.preAction[q.gates].push(q);
+            continue;
+        }
+        const mode = DEFAULT_RESOLUTION_MODES[q.ownership];
+        if (mode === 'agent') routed.agent.push(q);
+        else if (mode === 'council') routed.council.push(q);
+        else {
+            if (q.recommendation === undefined || q.recommendation.trim() === '') {
+                throw new QuestionError(`${q.id}: an owner item in the end batch needs a recommendation`);
+            }
+            routed.endBatch.push({ id: q.id, text: q.text, recommendation: q.recommendation });
+        }
+    }
+    return routed;
+}
+
+/** The one owner question due before `action`, or null when nothing gates it. */
+export function nextOwnerAsk(routed: Routed, action: GatedAction): Question | null {
+    return routed.preAction[action][0] ?? null;
+}

package/src/scripts/analysis_run.ts

@@ -0,0 +1,248 @@
+/**
+ * analysis_run.ts — the persisted run core of the analysis doors: one record
+ * per round under the gitignored `agents/runtime/analysis/<round-id>/`, legal
+ * transitions only, atomic writes, resume that re-validates every pin, one
+ * idempotency key per publication and a token budget whose cap ends the run
+ * in `handed-back`.
+ *
+ * The state lives in code rather than in a prompt because a prompt cannot
+ * guarantee resume or idempotency; a door re-invoked after a kill calls the
+ * same stages again and every stage already passed is skipped.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const RUN_SCHEMA_VERSION = '1.0';
+export const RUN_STATE_FILE = 'run-state.json';
+export const RUNS_REL = 'agents/runtime/analysis';
+
+export const RUN_STATES = [
+    'initialized',
+    'pinned',
+    'seeded',
+    'deepened',
+    'exchanged',
+    'judged',
+    'awaiting-decision',
+    'emitted',
+    'validated',
+    'committed',
+    'pushed',
+    'pr-open',
+    'ci-settled',
+    'done',
+] as const;
+
+export type ForwardState = (typeof RUN_STATES)[number];
+export type RunState = ForwardState | 'handed-back';
+
+export interface Transition {
+    from: RunState;
+    to: RunState;
+    at: string;
+    reason: string | null;
+}
+
+export interface RunRecord {
+    schema_version: string;
+    run_id: string;
+    state: RunState;
+    pins: Record<string, string>;
+    budget: { cap_tokens: number; spent_tokens: number };
+    publications: string[];
+    handed_back_reason: string | null;
+    history: Transition[];
+}
+
+export interface PinMove {
+    pin: string;
+    recorded: string;
+    current: string | null;
+}
+
+export class RunError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'RunError';
+    }
+}
+
+export function isTerminal(state: RunState): boolean {
+    return state === 'done' || state === 'handed-back';
+}
+
+export function legalNext(state: RunState): RunState[] {
+    if (isTerminal(state)) return [];
+    const idx = RUN_STATES.indexOf(state as ForwardState);
+    return [RUN_STATES[idx + 1] as ForwardState, 'handed-back'];
+}
+
+export function runsDir(projectRoot: string): string {
+    return path.join(projectRoot, RUNS_REL);
+}
+
+export function newRunId(now: Date = new Date()): string {
+    const day = now.toISOString().slice(0, 10).replaceAll('-', '');
+    return `run-${day}-${randomBytes(3).toString('hex')}`;
+}
+
+function writeAtomic(file: string, body: string): void {
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    fs.writeFileSync(tmp, body);
+    fs.renameSync(tmp, file);
+}
+
+function save(runDir: string, record: RunRecord): void {
+    fs.mkdirSync(runDir, { recursive: true });
+    writeAtomic(path.join(runDir, RUN_STATE_FILE), `${JSON.stringify(record, null, 2)}\n`);
+}
+
+/** Refuses a record whose major schema version this code does not know. */
+export function assertKnownSchema(version: unknown, what: string): void {
+    const major = typeof version === 'string' ? version.split('.')[0] : undefined;
+    if (major !== RUN_SCHEMA_VERSION.split('.')[0]) {
+        throw new RunError(`${what}: unknown schema_version ${JSON.stringify(version)} (this code reads ${RUN_SCHEMA_VERSION})`);
+    }
+}
+
+export function createRun(
+    projectRoot: string,
+    options: { runId?: string; pins: Record<string, string>; tokenCap: number },
+): { runDir: string; record: RunRecord } {
+    if (!Number.isFinite(options.tokenCap) || options.tokenCap <= 0) {
+        throw new RunError('tokenCap must be a positive number');
+    }
+    const runId = options.runId ?? newRunId();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId.includes('..')) {
+        throw new RunError(`run id ${JSON.stringify(runId)} is not a single folder name`);
+    }
+    const runDir = path.join(runsDir(projectRoot), runId);
+    if (fs.existsSync(path.join(runDir, RUN_STATE_FILE))) {
+        throw new RunError(`run ${runId} already exists`);
+    }
+    const record: RunRecord = {
+        schema_version: RUN_SCHEMA_VERSION,
+        run_id: runId,
+        state: 'initialized',
+        pins: { ...options.pins },
+        budget: { cap_tokens: options.tokenCap, spent_tokens: 0 },
+        publications: [],
+        handed_back_reason: null,
+        history: [],
+    };
+    save(runDir, record);
+    return { runDir, record };
+}
+
+export function loadRun(runDir: string): RunRecord {
+    const file = path.join(runDir, RUN_STATE_FILE);
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as RunRecord;
+    assertKnownSchema(raw.schema_version, file);
+    return raw;
+}
+
+export function transition(runDir: string, record: RunRecord, to: RunState, reason: string | null = null): RunRecord {
+    if (!legalNext(record.state).includes(to)) {
+        throw new RunError(`illegal transition ${record.state} → ${to}`);
+    }
+    const next: RunRecord = {
+        ...record,
+        state: to,
+        handed_back_reason: to === 'handed-back' ? (reason ?? 'unspecified') : record.handed_back_reason,
+        history: [...record.history, { from: record.state, to, at: new Date().toISOString(), reason }],
+    };
+    save(runDir, next);
+    return next;
+}
+
+export function handBack(runDir: string, record: RunRecord, reason: string): RunRecord {
+    return transition(runDir, record, 'handed-back', reason);
+}
+
+/** True when `record` has already passed `target` on the forward path. */
+export function reached(record: RunRecord, target: ForwardState): boolean {
+    if (record.state === 'handed-back') return false;
+    return RUN_STATES.indexOf(record.state as ForwardState) >= RUN_STATES.indexOf(target);
+}
+
+/**
+ * Runs `effect` and moves to `target` — unless the record already reached it,
+ * in which case nothing runs. This is what makes a re-invocation after a kill
+ * resume instead of repeating a completed stage; a kill after `effect` and
+ * before the transition is saved repeats that one stage.
+ */
+export function runStage(
+    runDir: string,
+    record: RunRecord,
+    target: ForwardState,
+    effect: () => void,
+): { record: RunRecord; performed: boolean } {
+    if (reached(record, target)) return { record, performed: false };
+    if (!legalNext(record.state).includes(target)) {
+        throw new RunError(`illegal transition ${record.state} → ${target}`);
+    }
+    effect();
+    return { record: transition(runDir, record, target), performed: true };
+}
+
+/**
+ * Re-validates every recorded pin. A moved or missing pin is reported and the
+ * record is returned unchanged — the caller decides, the run never continues
+ * silently on a different head.
+ */
+export function resumeRun(
+    runDir: string,
+    currentPins: Record<string, string | null>,
+): { record: RunRecord; moved: PinMove[] } {
+    const record = loadRun(runDir);
+    const moved: PinMove[] = [];
+    for (const [pin, recorded] of Object.entries(record.pins)) {
+        const current = currentPins[pin] ?? null;
+        if (current !== recorded) moved.push({ pin, recorded, current });
+    }
+    return { record, moved };
+}
+
+export function publicationKey(runId: string, paths: readonly string[], baseSha: string): string {
+    const body = JSON.stringify({ runId, paths: [...paths].sort(), baseSha });
+    return createHash('sha256').update(body).digest('hex');
+}
+
+/**
+ * Performs a publication at most once per key across re-runs that complete.
+ * The key is saved AFTER the effect, so a kill between the two repeats the
+ * effect on resume: across kills this is at-least-once, and an effect that
+ * must not repeat carries its own idempotence check (as `publish()` does with
+ * `findOpenPr`).
+ */
+export function publishOnce(
+    runDir: string,
+    record: RunRecord,
+    key: string,
+    effect: () => void,
+): { record: RunRecord; performed: boolean } {
+    if (record.publications.includes(key)) return { record, performed: false };
+    effect();
+    const next: RunRecord = { ...record, publications: [...record.publications, key] };
+    save(runDir, next);
+    return { record: next, performed: true };
+}
+
+/** Adds spend; crossing the cap hands the run back rather than raising the cap. */
+export function spendTokens(runDir: string, record: RunRecord, tokens: number): RunRecord {
+    if (isTerminal(record.state)) {
+        throw new RunError(`cannot spend on a run in ${record.state}`);
+    }
+    if (!Number.isFinite(tokens) || tokens < 0) {
+        throw new RunError(`token spend must be a non-negative number, got ${String(tokens)}`);
+    }
+    const spent = record.budget.spent_tokens + tokens;
+    const next: RunRecord = { ...record, budget: { ...record.budget, spent_tokens: spent } };
+    if (spent > record.budget.cap_tokens) {
+        save(runDir, next);
+        return handBack(runDir, next, `budget: ${spent} of ${record.budget.cap_tokens} tokens`);
+    }
+    save(runDir, next);
+    return next;
+}

package/src/scripts/analysis_run_record.ts

@@ -0,0 +1,210 @@
+/**
+ * analysis_run_record.ts — `run.json`, the one record each analysis round
+ * leaves in `agents/runtime/analysis/<round-id>/` (step 6.3, ADR-288 D9).
+ *
+ * It is the denominator the falsification rule reads after ten runs and the
+ * unit the retro's `analysis-run` reader consumes. A reading that was not taken
+ * is `missing`, never 0: a zero would be counted as a measured null.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { TOP_TIERS, type Lens, type LoopRow } from './analysis_ledger.js';
+import type { AnalystMode } from './analysis_analysts.js';
+import { assertKnownSchema, type RunState } from './analysis_run.js';
+
+export const RUN_JSON = 'run.json';
+export const RUN_JSON_SCHEMA_VERSION = '1.0';
+export const DOORS = ['reference', 'and-optimize', 'pr', 'inbox'] as const;
+export type Door = (typeof DOORS)[number];
+
+export interface AnalystInput {
+    analyst_id: string;
+    mode: AnalystMode;
+    family: string;
+    ledger: readonly LoopRow[];
+    tokens: number;
+}
+
+export interface RunJsonInput {
+    run_id: string;
+    door: Door;
+    started_at: string;
+    ended_at: string;
+    final_state: RunState;
+    analysts: AnalystInput[];
+    exchange: { rounds: number; already_fixed: number; claims_checked: number } | null;
+    gain: { offered: boolean; band: 'low' | 'medium' | 'high'; reason: string };
+    seats: { used: string[]; failed: string[] };
+    roadmaps_emitted: string[];
+    recurrence_hits: number;
+    ci_rounds: number;
+    /** From `probe_turnaround` over the run's sessions; null when it was not read. */
+    turnaround: { user_requests: number; blocking_calls: number } | null;
+}
+
+export interface RunJsonRow {
+    analyst_id: string;
+    mode: AnalystMode;
+    family: string;
+    loop: number;
+    lens: Lens;
+    status: LoopRow['status'];
+    top_tier: { added: number; changed: number; killed: number };
+}
+
+export interface RunJson {
+    schema_version: string;
+    run_id: string;
+    door: Door;
+    final_state: RunState;
+    analysts: number;
+    rows: RunJsonRow[];
+    exchange:
+        | { rounds: number; already_fixed: number; claims_checked: number; already_fixed_rate: number | 'missing' }
+        | 'missing';
+    gain: RunJsonInput['gain'];
+    seats: RunJsonInput['seats'];
+    roadmaps_emitted: string[];
+    recurrence_hits: number;
+    ci_rounds: number;
+    tokens: number;
+    wall_clock_seconds: number;
+    turnaround: NonNullable<RunJsonInput['turnaround']> | 'missing';
+}
+
+function topTierCounts(row: LoopRow): RunJsonRow['top_tier'] {
+    const counts = { added: 0, changed: 0, killed: 0 };
+    if (row.status !== 'counted') return counts;
+    for (const item of row.items) {
+        if (item.change === 'retained' || !item.evidence.some((e) => TOP_TIERS.includes(e.tier))) continue;
+        counts[item.change] += 1;
+    }
+    return counts;
+}
+
+export function buildRunJson(input: RunJsonInput): RunJson {
+    const rows: RunJsonRow[] = input.analysts.flatMap((a) =>
+        a.ledger.map((row) => ({
+            analyst_id: a.analyst_id,
+            mode: a.mode,
+            family: a.family,
+            loop: row.loop,
+            lens: row.lens,
+            status: row.status,
+            top_tier: topTierCounts(row),
+        })),
+    );
+    const ex = input.exchange;
+    return {
+        schema_version: RUN_JSON_SCHEMA_VERSION,
+        run_id: input.run_id,
+        door: input.door,
+        final_state: input.final_state,
+        analysts: input.analysts.length,
+        rows,
+        exchange:
+            ex === null
+                ? 'missing'
+                : { ...ex, already_fixed_rate: ex.claims_checked > 0 ? ex.already_fixed / ex.claims_checked : 'missing' },
+        gain: { ...input.gain },
+        seats: { used: [...input.seats.used], failed: [...input.seats.failed] },
+        roadmaps_emitted: [...input.roadmaps_emitted],
+        recurrence_hits: input.recurrence_hits,
+        ci_rounds: input.ci_rounds,
+        tokens: input.analysts.reduce((sum, a) => sum + a.tokens, 0),
+        wall_clock_seconds: Math.round((Date.parse(input.ended_at) - Date.parse(input.started_at)) / 1000),
+        turnaround: input.turnaround === null ? 'missing' : { ...input.turnaround },
+    };
+}
+
+const isCount = (v: unknown): boolean => typeof v === 'number' && Number.isInteger(v) && v >= 0;
+
+/** Every reason `doc` is not a valid run.json. Empty means valid. */
+export function validateRunJson(doc: unknown): string[] {
+    if (typeof doc !== 'object' || doc === null) return ['run.json is not an object'];
+    const d = doc as Record<string, unknown>;
+    const errors: string[] = [];
+    try {
+        assertKnownSchema(d['schema_version'], 'run.json');
+    } catch (err) {
+        errors.push(err instanceof Error ? err.message : String(err));
+    }
+    if (typeof d['run_id'] !== 'string' || d['run_id'] === '') errors.push('run_id is required');
+    if (!DOORS.includes(d['door'] as Door)) errors.push(`door must be one of ${DOORS.join(', ')}`);
+    for (const key of ['analysts', 'recurrence_hits', 'ci_rounds', 'tokens', 'wall_clock_seconds']) {
+        if (!isCount(d[key])) errors.push(`${key} must be a non-negative integer`);
+    }
+    const seats = d['seats'] as { used?: unknown; failed?: unknown } | undefined;
+    if (seats === undefined || !Array.isArray(seats.used) || !Array.isArray(seats.failed)) errors.push('seats.used and seats.failed are required');
+    if (!Array.isArray(d['roadmaps_emitted'])) errors.push('roadmaps_emitted must be a list');
+    if (d['exchange'] !== 'missing' && (typeof d['exchange'] !== 'object' || d['exchange'] === null)) errors.push('exchange must be an object or "missing"');
+    if (d['turnaround'] !== 'missing' && (typeof d['turnaround'] !== 'object' || d['turnaround'] === null)) {
+        errors.push('turnaround must be an object or "missing"');
+    }
+    const rows = d['rows'];
+    if (!Array.isArray(rows)) {
+        errors.push('rows must be a list');
+        return errors;
+    }
+    const perAnalyst = new Map<string, number[]>();
+    for (const r of rows as Array<Record<string, unknown>>) {
+        const id = String(r['analyst_id']);
+        perAnalyst.set(id, [...(perAnalyst.get(id) ?? []), Number(r['loop'])]);
+    }
+    if (isCount(d['analysts']) && perAnalyst.size !== d['analysts']) {
+        errors.push(`rows name ${perAnalyst.size} analysts, the record says ${String(d['analysts'])}`);
+    }
+    for (const [id, loops] of perAnalyst) {
+        if (loops.some((l, i) => l !== i + 1)) errors.push(`rows of ${id} are not one per loop from 1: ${loops.join(',')}`);
+    }
+    return errors;
+}
+
+/** Written atomically, after validation; an invalid record is never left on disk. */
+export function writeRunJson(runDir: string, doc: RunJson): void {
+    const errors = validateRunJson(doc);
+    if (errors.length > 0) throw new Error(`run.json invalid: ${errors.join('; ')}`);
+    fs.mkdirSync(runDir, { recursive: true });
+    const tmp = path.join(runDir, `${RUN_JSON}.tmp`);
+    fs.writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`);
+    fs.renameSync(tmp, path.join(runDir, RUN_JSON));
+}
+
+export function readRunJson(runDir: string): RunJson {
+    const doc = JSON.parse(fs.readFileSync(path.join(runDir, RUN_JSON), 'utf8')) as unknown;
+    const errors = validateRunJson(doc);
+    if (errors.length > 0) throw new Error(`run.json invalid: ${errors.join('; ')}`);
+    return doc as RunJson;
+}
+
+/** `analysis_run_record --run <run-dir>`: validates the run's `run.json` and prints one summary line. */
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const i = argv.indexOf('--run');
+    const runDir = i >= 0 ? argv[i + 1] : undefined;
+    if (runDir === undefined) {
+        process.stderr.write('usage: analysis_run_record --run <run-dir>\n');
+        return 2;
+    }
+    try {
+        const doc = readRunJson(runDir);
+        process.stdout.write(`${doc.run_id} · ${doc.door} · ${doc.final_state} · ${doc.analysts} analysts · ${doc.rows.length} loop rows · ${doc.tokens} tokens\n`);
+        return 0;
+    } catch (err) {
+        process.stderr.write(`analysis_run_record: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href ||
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) process.exit(main());