ai-foreman 1.6.2 → 1.7.0

package/dist/qaReview.js

@@ -0,0 +1,103 @@
+import { buildQaFixInstruction, buildQaInstruction, parseStepStatus } from "./foreman.js";
+import { createDisposableQaSnapshot } from "./qaSnapshot.js";
+export async function runIsolatedQa(opts) {
+    const history = [];
+    for (let cycle = 1; cycle <= opts.maxCycles; cycle++) {
+        const review = await oneReview(opts, cycle);
+        if (review.outcome === "retry-modification") {
+            cycle -= 1;
+            continue;
+        }
+        if (review.outcome === "passed")
+            return review;
+        if (review.outcome !== "failed")
+            return review;
+        history.push({ cycle, outcome: "qa_fail", detail: review.detail });
+        if (cycle === opts.maxCycles)
+            break;
+        const fix = await opts.fix(review.detail ?? "QA reported unspecified issues");
+        if (!fix.ok)
+            return { outcome: "blocked", detail: fix.detail ?? "Builder QA fix failed" };
+    }
+    const detail = `QA could not converge after ${opts.maxCycles} automatic cycle(s); choose retry, pause, waive, or Planner remediation`;
+    if (!opts.onNonconvergence)
+        return { outcome: "nonconverged", detail };
+    const decision = await opts.onNonconvergence({ ticket: opts.ticket, history, builderWorktree: opts.builderWorktree });
+    if (decision.action === "pause")
+        return { outcome: "nonconverged", detail };
+    if (decision.action === "waive")
+        return { outcome: "waived", detail: history.at(-1)?.detail ?? detail, summary: "QA explicitly waived by user" };
+    const issues = decision.action === "remediate" ? decision.remediation : history.at(-1)?.detail;
+    if (!issues)
+        return { outcome: "nonconverged", detail: "Planner remediation did not produce approved fix instructions" };
+    const fix = await opts.fix(issues);
+    if (!fix.ok)
+        return { outcome: "blocked", detail: fix.detail ?? "Builder QA fix failed" };
+    return runIsolatedQa(opts);
+}
+async function oneReview(opts, cycle) {
+    const snapshot = createDisposableQaSnapshot(opts.builderWorktree);
+    let qa;
+    try {
+        const resume = opts.qaStrategy === "compact" && opts.state.modificationViolations === 0 ? opts.state.sessionId : undefined;
+        qa = await opts.createQa(snapshot.path, resume);
+        if (opts.qaStrategy === "compact" && opts.state.reviews > 0 && resume) {
+            const compacted = await compactWithRetry(qa);
+            if (!compacted.ok) {
+                await qa.close();
+                qa = await opts.createQa(snapshot.path);
+                opts.state.sessionId = undefined;
+            }
+        }
+        const handoff = [
+            buildQaInstruction(), "", "QA handoff:", `Ticket: ${opts.ticket.id} — ${opts.ticket.title}`,
+            `Acceptance: ${opts.ticket.acceptance.join("; ")}`, `Builder summary: ${opts.builderSummary}`,
+            `Changed files/diff digest: ${snapshot.manifest.diffDigest}`, `Required tests: ${opts.ticket.required_tests.join("; ")}`,
+            "Do not change source, configuration, documentation, tickets, or control files. Only ignored cache, coverage, and build output is allowed.",
+        ].join("\n");
+        const turn = await qa.sendTurn(handoff);
+        const status = parseStepStatus(turn.text);
+        opts.state.reviews += 1;
+        opts.state.sessionId = qa.sessionId();
+        const changes = snapshot.qaChanges();
+        if (changes.length) {
+            opts.state.modificationViolations += 1;
+            opts.evidence?.({ cycle, outcome: "qa_file_modification", detail: "QA modified the disposable review copy", qaDiff: changes });
+            if (opts.state.modificationViolations === 1)
+                return { outcome: "retry-modification" };
+            return { outcome: "needs-human", detail: `QA modified files twice: ${changes.join(", ")}` };
+        }
+        opts.state.modificationViolations = 0;
+        if (turn.isError)
+            return { outcome: "blocked", detail: turn.text.slice(0, 500) };
+        if (status.kind === "qa_pass") {
+            opts.evidence?.({ cycle, outcome: "passed", detail: status.summary ?? "qa_pass" });
+            return { outcome: "passed", summary: status.summary };
+        }
+        if (status.kind === "qa_fail") {
+            const detail = status.issues ?? "QA reported no issue text";
+            opts.evidence?.({ cycle, outcome: "failed", detail });
+            return { outcome: "failed", detail };
+        }
+        return { outcome: "needs-human", detail: status.error ?? `QA returned ${status.kind}` };
+    }
+    finally {
+        await qa?.close().catch(() => { });
+        snapshot.remove();
+    }
+}
+export async function compactWithRetry(adapter) {
+    if (!adapter.compact)
+        return { ok: false, error: "native compaction unavailable" };
+    let error = "";
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const result = await adapter.compact();
+        if (result.ok)
+            return { ok: true };
+        error = result.error ?? "compaction failed";
+    }
+    return { ok: false, error };
+}
+export function buildDurableQaFixHandoff(ticket, issues, worktree, priorResult, diffDigest) {
+    return [buildQaFixInstruction(issues), "", `Ticket: ${ticket.id} — ${ticket.title}`, `Acceptance: ${ticket.acceptance.join("; ")}`, `Worktree: ${worktree}`, `Current diff: ${diffDigest}`, `Prior result: ${priorResult}`, `All QA issues: ${issues}`].join("\n");
+}

package/dist/qaSnapshot.d.ts

@@ -0,0 +1,19 @@
+export interface QaChangeManifest {
+    diffDigest: string;
+    untracked: Array<{
+        path: string;
+        kind: "file" | "symlink";
+        mode: number;
+        digest: string;
+    }>;
+}
+export interface DisposableQaSnapshot {
+    path: string;
+    manifest: QaChangeManifest;
+    verify(): void;
+    qaChanges(): string[];
+    remove(): void;
+}
+/** Reproduce the Builder's exact change set in a detached disposable worktree. */
+export declare function createDisposableQaSnapshot(builderWorktree: string): DisposableQaSnapshot;
+export declare function changeManifest(worktree: string): QaChangeManifest;

package/dist/qaSnapshot.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+/** Reproduce the Builder's exact change set in a detached disposable worktree. */
+export function createDisposableQaSnapshot(builderWorktree) {
+    const source = resolve(builderWorktree);
+    const root = execFileSync("git", ["-C", source, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+    const tempRoot = mkdtempSync(join(tmpdir(), "rafi-qa-"));
+    const review = join(tempRoot, "review");
+    const head = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+    const added = spawnSync("git", ["-C", root, "worktree", "add", "--detach", review, head], { encoding: "utf8" });
+    if (added.status !== 0) {
+        rmSync(tempRoot, { recursive: true, force: true });
+        throw new Error(`cannot create disposable QA worktree: ${added.stderr.trim()}`);
+    }
+    try {
+        const diff = execFileSync("git", ["-C", source, "diff", "--binary", "HEAD"], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
+        if (diff.length) {
+            const applied = spawnSync("git", ["-C", review, "apply", "--index", "--binary", "--whitespace=nowarn", "-"], { input: diff, encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
+            if (applied.status !== 0)
+                throw new Error(`cannot apply Builder diff to QA worktree: ${Buffer.from(applied.stderr).toString().trim()}`);
+        }
+        for (const path of untrackedPaths(source))
+            copyUntracked(source, review, path);
+        const manifest = changeManifest(source);
+        const snapshot = {
+            path: review, manifest,
+            verify: () => {
+                const actual = changeManifest(review);
+                if (JSON.stringify(actual) !== JSON.stringify(manifest))
+                    throw new Error(`disposable QA snapshot does not match Builder change manifest: expected ${JSON.stringify(manifest)}, got ${JSON.stringify(actual)}`);
+            },
+            qaChanges: () => manifestDifference(manifest, changeManifest(review)),
+            remove: () => {
+                spawnSync("git", ["-C", root, "worktree", "remove", "--force", review], { encoding: "utf8" });
+                rmSync(tempRoot, { recursive: true, force: true });
+            },
+        };
+        snapshot.verify();
+        return snapshot;
+    }
+    catch (error) {
+        spawnSync("git", ["-C", root, "worktree", "remove", "--force", review], { encoding: "utf8" });
+        rmSync(tempRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
+export function changeManifest(worktree) {
+    const diff = execFileSync("git", ["-C", worktree, "diff", "--binary", "HEAD"], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
+    const untracked = untrackedPaths(worktree).map((path) => {
+        const absolute = join(worktree, path);
+        const stat = lstatSync(absolute);
+        const kind = stat.isSymbolicLink() ? "symlink" : "file";
+        const bytes = kind === "symlink" ? Buffer.from(readlinkSync(absolute)) : readFileSync(absolute);
+        return { path, kind, mode: stat.mode & 0o7777, digest: createHash("sha256").update(bytes).digest("hex") };
+    });
+    return { diffDigest: createHash("sha256").update(diff).digest("hex"), untracked };
+}
+function untrackedPaths(worktree) {
+    const raw = execFileSync("git", ["-C", worktree, "ls-files", "--others", "--exclude-standard", "-z"], { encoding: "buffer" });
+    return raw.toString().split("\0").filter(Boolean).sort();
+}
+function copyUntracked(source, target, path) {
+    const from = join(source, path);
+    const to = join(target, path);
+    mkdirSync(dirname(to), { recursive: true });
+    const stat = lstatSync(from);
+    if (stat.isSymbolicLink()) {
+        if (existsSync(to))
+            rmSync(to, { force: true });
+        symlinkSync(readlinkSync(from), to);
+    }
+    else
+        cpSync(from, to, { preserveTimestamps: true });
+}
+function manifestDifference(before, after) {
+    const changes = [];
+    if (before.diffDigest !== after.diffDigest)
+        changes.push("tracked diff changed");
+    const left = new Map(before.untracked.map((item) => [item.path, item]));
+    const right = new Map(after.untracked.map((item) => [item.path, item]));
+    for (const path of [...new Set([...left.keys(), ...right.keys()])].sort())
+        if (JSON.stringify(left.get(path)) !== JSON.stringify(right.get(path)))
+            changes.push(path);
+    return changes;
+}

package/dist/sessionLifecycle.d.ts

@@ -0,0 +1,37 @@
+import type { ConfigurableAgentRole, ResolvedAgentSettings, WorkflowIssue } from "rafi-spec";
+import type { BuilderAdapter, ContextUsage } from "./adapters/types.js";
+export interface SessionTransition {
+    kind: "initial" | "compacted" | "fresh" | "missing" | "compaction-retry" | "compaction-fallback" | "settings-attempt" | "settings-continued" | "settings-fallback";
+    role: ConfigurableAgentRole;
+    workSession: number;
+    sessionId?: string;
+    message: string;
+}
+export interface SessionBoundary {
+    adapter: BuilderAdapter;
+    transition: SessionTransition;
+    issue?: WorkflowIssue;
+}
+export interface RoleSessionControllerOptions {
+    role: ConfigurableAgentRole;
+    settings: ResolvedAgentSettings;
+    create: (settings: ResolvedAgentSettings, resumeSessionId?: string) => Promise<BuilderAdapter>;
+    report?: (transition: SessionTransition) => void;
+    now?: () => Date;
+    initialSessionId?: string;
+}
+/** One lifecycle implementation shared by interviews, builds, QA, and recovery. */
+export declare class RoleSessionController {
+    private readonly options;
+    private adapter?;
+    private workSessions;
+    constructor(options: RoleSessionControllerOptions);
+    next(_durableHandoff: string, nextSettings?: ResolvedAgentSettings): Promise<SessionBoundary>;
+    current(): BuilderAdapter | undefined;
+    count(): number;
+    usage(): Promise<ContextUsage | undefined>;
+    close(): Promise<void>;
+    private boundary;
+    private emit;
+    private issue;
+}

package/dist/sessionLifecycle.js

@@ -0,0 +1,104 @@
+import { sanitizeDiagnostics } from "./runtimeReadiness.js";
+/** One lifecycle implementation shared by interviews, builds, QA, and recovery. */
+export class RoleSessionController {
+    options;
+    adapter;
+    workSessions = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    async next(_durableHandoff, nextSettings) {
+        this.workSessions += 1;
+        if (!this.adapter) {
+            if (nextSettings)
+                this.options.settings = nextSettings;
+            this.adapter = await this.options.create(this.options.settings, this.options.initialSessionId);
+            return this.boundary("initial", "started a workflow-scoped provider conversation");
+        }
+        if (nextSettings) {
+            const current = this.options.settings;
+            if (nextSettings.make !== current.make) {
+                await this.adapter.close();
+                this.options.settings = nextSettings;
+                this.adapter = await this.options.create(nextSettings);
+                return this.boundary("settings-fallback", `provider changed from ${current.make} to ${nextSettings.make}; started fresh from the durable handoff`);
+            }
+            const changed = nextSettings.model !== current.model || nextSettings.reasoning !== current.reasoning || nextSettings.fast !== current.fast;
+            this.options.settings = nextSettings;
+            if (changed) {
+                this.emit("settings-attempt", `attempting same-conversation settings switch to ${nextSettings.model}, reasoning=${nextSettings.reasoning}, fast=${nextSettings.fast}`);
+                const switched = this.adapter.switchSettings
+                    ? await this.adapter.switchSettings({ model: nextSettings.model === "default" ? undefined : nextSettings.model, effort: effort(nextSettings.reasoning), fast: nextSettings.fast })
+                    : { ok: false, error: "provider adapter does not support an in-conversation settings switch" };
+                if (!switched.ok) {
+                    await this.adapter.close();
+                    this.adapter = await this.options.create(nextSettings);
+                    const detail = sanitize(switched.error ?? "settings switch failed");
+                    const issue = this.issue("session_model_switch_failure", detail, "This work session continued fresh with the current project settings.");
+                    return this.boundary("settings-fallback", `settings switch failed (${detail}); started fresh and continuity was lost`, issue);
+                }
+                this.emit("settings-continued", "provider accepted the same-conversation settings switch");
+            }
+        }
+        if (this.options.settings.session_strategy === "fresh") {
+            await this.adapter.close();
+            this.adapter = await this.options.create(this.options.settings);
+            const result = this.boundary("fresh", "started a fresh conversation with a durable handoff");
+            return result;
+        }
+        if (!this.adapter.sessionId()) {
+            await this.adapter.close();
+            this.adapter = await this.options.create(this.options.settings);
+            const issue = this.issue("session_missing", "exact provider session is unavailable", "Continue fresh from the durable handoff.");
+            const result = this.boundary("missing", "continuity unavailable; started fresh from the durable handoff", issue);
+            return result;
+        }
+        let firstError = "";
+        for (let attempt = 1; attempt <= 2; attempt++) {
+            try {
+                const compacted = this.adapter.compact
+                    ? await this.adapter.compact()
+                    : { ok: false, error: "provider adapter does not expose native compaction" };
+                if (compacted.ok)
+                    return this.boundary("compacted", attempt === 1 ? "compacted and continued the exact conversation" : "compaction retry succeeded; continued the exact conversation");
+                firstError = sanitize(compacted.error ?? "provider reported compaction failure");
+            }
+            catch (error) {
+                firstError = sanitize(error);
+            }
+            if (attempt === 1)
+                this.emit("compaction-retry", `compaction failed (${firstError}); retrying once`);
+        }
+        await this.adapter.close();
+        this.adapter = await this.options.create(this.options.settings);
+        const issue = this.issue("session_compaction_failure", firstError, "Inspect provider health; this work session continued fresh.");
+        const result = this.boundary("compaction-fallback", `compaction failed twice (${firstError}); started fresh and continuity was lost`, issue);
+        return result;
+    }
+    current() { return this.adapter; }
+    count() { return this.workSessions; }
+    async usage() { return this.adapter?.contextUsage?.(); }
+    async close() { await this.adapter?.close(); this.adapter = undefined; }
+    boundary(kind, message, issue) {
+        const transition = this.emit(kind, message);
+        return { adapter: this.adapter, transition, issue };
+    }
+    emit(kind, message) {
+        const transition = { kind, role: this.options.role, workSession: this.workSessions, sessionId: this.adapter?.sessionId(), message };
+        this.options.report?.(transition);
+        return transition;
+    }
+    issue(code, detail, action) {
+        return {
+            code, role: this.options.role, phase: "session-boundary", provider: this.options.settings.make,
+            model: this.options.settings.model, detail, human_required: false, recoverable: true,
+            suggested_action: action, occurred_at: (this.options.now?.() ?? new Date()).toISOString(),
+        };
+    }
+}
+function effort(value) {
+    return ["low", "medium", "high", "xhigh"].includes(value) ? value : undefined;
+}
+function sanitize(error) {
+    return sanitizeDiagnostics(error instanceof Error ? error.message : String(error)).slice(0, 1000);
+}

package/dist/statusReporter.d.ts

@@ -0,0 +1,40 @@
+import type { BuilderAdapter } from "./adapters/types.js";
+export interface AgentStatusSnapshot {
+    role: string;
+    provider: string;
+    model: string;
+    reasoning: string;
+    fast: boolean;
+    ticket?: string;
+    stack?: string;
+    step: number;
+    total: number;
+    phase: string;
+    qaCycle?: number;
+    context?: {
+        used: number;
+        maximum?: number;
+        percentage?: number;
+    };
+    sessionTransition: string;
+    at: string;
+}
+export interface StatusClock {
+    now(): Date;
+    setInterval(callback: () => void, milliseconds: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+/** Non-blocking five-minute status with provider-truthful context occupancy. */
+export declare class AgentStatusReporter {
+    private readonly input;
+    private readonly emit;
+    private readonly clock;
+    private readonly intervalMs;
+    private handle?;
+    constructor(input: Omit<AgentStatusSnapshot, "context" | "at"> & {
+        adapter: BuilderAdapter | (() => BuilderAdapter);
+    }, emit: (line: string, snapshot: AgentStatusSnapshot) => void, clock?: StatusClock, intervalMs?: number);
+    start(): void;
+    tick(): Promise<void>;
+    stop(): void;
+}

package/dist/statusReporter.js

@@ -0,0 +1,31 @@
+const systemClock = {
+    now: () => new Date(),
+    setInterval: (callback, milliseconds) => { const handle = setInterval(callback, milliseconds); handle.unref(); return handle; },
+    clearInterval: (handle) => clearInterval(handle),
+};
+/** Non-blocking five-minute status with provider-truthful context occupancy. */
+export class AgentStatusReporter {
+    input;
+    emit;
+    clock;
+    intervalMs;
+    handle;
+    constructor(input, emit, clock = systemClock, intervalMs = 300_000) {
+        this.input = input;
+        this.emit = emit;
+        this.clock = clock;
+        this.intervalMs = intervalMs;
+    }
+    start() { if (this.handle !== undefined)
+        return; this.handle = this.clock.setInterval(() => void this.tick(), this.intervalMs); }
+    async tick() {
+        const adapter = typeof this.input.adapter === "function" ? this.input.adapter() : this.input.adapter;
+        const context = await adapter.contextUsage?.();
+        const { adapter: _adapter, ...base } = this.input;
+        const snapshot = { ...base, ...(context ? { context } : {}), at: this.clock.now().toISOString() };
+        const occupancy = context ? `context: ${context.used}/${context.maximum ?? "unknown"}${context.percentage === undefined ? "" : ` (${context.percentage.toFixed(1)}%)`}` : "context: unavailable";
+        this.emit(`[${snapshot.at}] ${snapshot.role} ${snapshot.provider}/${snapshot.model} reasoning=${snapshot.reasoning} fast=${snapshot.fast}; ${snapshot.ticket ? `ticket=${snapshot.ticket}; ` : ""}${snapshot.stack ? `stack=${snapshot.stack}; ` : ""}step=${snapshot.step}/${snapshot.total}; phase=${snapshot.phase}${snapshot.qaCycle ? `; qa_cycle=${snapshot.qaCycle}` : ""}; ${occupancy}; session=${snapshot.sessionTransition}`, snapshot);
+    }
+    stop() { if (this.handle !== undefined)
+        this.clock.clearInterval(this.handle); this.handle = undefined; }
+}

package/dist/ticketPopulation.d.ts

@@ -0,0 +1,47 @@
+import type { StructuredPlanV1 } from "rafi-spec";
+import type { TicketDef } from "./tickets/ticketSchema.js";
+import { type DeliveryConfig } from "./tickets/delivery.js";
+export interface TicketSliceProposal {
+    slice_ref: string;
+    title: string;
+    area: string;
+    priority: TicketDef["priority"];
+    size: TicketDef["size"];
+    risk: TicketDef["risk"];
+    summary: string;
+    acceptance: string[];
+    required_tests: string[];
+    likely_files: string[];
+    depends_on: string[];
+    rollback?: string | null;
+    notes?: string | null;
+}
+export interface TicketPopulationProposalV1 {
+    version: 1;
+    plan_id: string;
+    revision: number;
+    tickets: TicketSliceProposal[];
+    retirements: string[];
+}
+export declare const TICKET_POPULATION_PROPOSAL_START = "RAFI_TICKET_POPULATION_PROPOSAL_START";
+export declare const TICKET_POPULATION_PROPOSAL_END = "RAFI_TICKET_POPULATION_PROPOSAL_END";
+export interface MaterializedTicketPopulation {
+    tickets: TicketDef[];
+    delivery: DeliveryConfig;
+    retirements: string[];
+    sliceToTicket: Map<string, string>;
+}
+export declare function extractTicketPopulationProposal(output: string): TicketPopulationProposalV1;
+export declare function validateTicketPopulationProposal(proposal: TicketPopulationProposalV1, plan: StructuredPlanV1, existing: TicketDef[]): string[];
+export declare function materializeTicketPopulation(proposal: TicketPopulationProposalV1, plan: StructuredPlanV1, existing: TicketDef[]): MaterializedTicketPopulation;
+export declare function authorizeTicketRetirements(retirements: string[], input: {
+    interactiveConfirmed?: boolean;
+    authorizedIds?: string[];
+    computerRun?: boolean;
+}): void;
+export declare function applyTicketPopulation(projectDir: string, materialized: MaterializedTicketPopulation, runId?: string, now?: Date): {
+    runId: string;
+    transactionId: string;
+};
+/** Startup recovery deterministically finishes publications after tracker commit. */
+export declare function recoverTicketPublications(projectDir: string): string[];