ai-foreman 1.7.11 → 1.7.13

package/dist/qaReview.d.ts

@@ -1,48 +1,166 @@
-import type { ProviderSessionRefV1, SessionStrategy } from "rafi-spec";
+import { type ProviderSessionRefV1, type QaFailureReportV1, type SessionStrategy } from "rafi-spec";
 import type { BuilderAdapter, CompactResult } from "./adapters/types.js";
+import type { RunObserver } from "./observability.js";
 import type { TicketDef } from "./tickets/ticketSchema.js";
+import { type QaRecoveryPacket } from "./qaRecovery.js";
 export interface QaStreamState {
     sessionId?: string;
     sessionRef?: ProviderSessionRefV1;
     reviews: number;
     modificationViolations: number;
+    remediationGeneration?: number;
+    /** Exact host-observed Builder responses; prompt-facing summaries remain separately bounded. */
+    builderResponseHistory?: Array<{
+        ticketId: string;
+        cycle: number;
+        kind: "completion" | "remediation" | "plain-fallback";
+        response: string;
+        summary: string;
+    }>;
+}
+export interface QaReportHistoryEntry {
+    cycle: number;
+    reviewAttempt?: number;
+    remediationGeneration?: number;
+    attemptId?: string;
+    outcome: string;
+    detail: string;
+    reportDigest?: string;
+    report?: QaFailureReportV1;
+    findingIds?: string[];
+    fixSummaryDigest?: string;
+    fixSummary?: string;
+    remediationDigest?: string;
+    remediation?: string;
 }
 export interface QaNonconvergenceContext {
     ticket: TicketDef;
-    history: Array<{
-        cycle: number;
-        outcome: string;
-        detail: string;
-    }>;
+    history: QaReportHistoryEntry[];
     builderWorktree: string;
 }
 export type QaNonconvergenceDecision = {
     action: "retry" | "pause" | "waive" | "remediate";
     remediation?: string;
 };
+export type QaFixRequest = {
+    kind: "validated-report";
+    report: QaFailureReportV1;
+    reportDigest: string;
+    history: QaReportHistoryEntry[];
+    latestBuilderResult: string;
+} | {
+    kind: "planner-remediation";
+    report: QaFailureReportV1;
+    reportDigest: string;
+    remediation: string;
+    history: QaReportHistoryEntry[];
+    latestBuilderResult: string;
+} | {
+    kind: "plain-issues";
+    issues: string;
+    operatorApproved: true;
+    history: QaReportHistoryEntry[];
+    latestBuilderResult: string;
+};
+export type QaFixResult = {
+    ok: true;
+    response: string;
+    summary: string;
+    detail?: string;
+} | {
+    ok: false;
+    detail?: string;
+    response?: string;
+    summary?: string;
+};
+export interface QaSessionHandle {
+    adapter: BuilderAdapter;
+    sessionIdentity?: ProviderSessionRefV1 | string;
+    effectiveRoleInstructions: string;
+    runtimeContext: unknown;
+    skills: Array<{
+        name: string;
+        digest: string | "unavailable";
+        reason?: string;
+        path?: string;
+    }>;
+    handoffReceipt?: unknown;
+}
+export interface QaSessionBoundaryRecovery {
+    packetDigest: string;
+    reviewedStateDigest: string;
+    packetPath: string;
+    resources: Array<{
+        label: string;
+        digest: string;
+        requiredForRecovery: boolean;
+        mediaType: string;
+        path: string;
+    }>;
+}
+export type QaReportRecoveryDecision = {
+    action: "fresh";
+} | {
+    action: "plain";
+} | {
+    action: "manual";
+} | {
+    action: "guidance";
+    instructions: string;
+    route?: "current" | "compact" | "fresh";
+} | {
+    action: "pause";
+};
+export type QaReportRecoveryHandler = NonNullable<IsolatedQaOptions["onReportRecovery"]>;
 export interface IsolatedQaOptions {
     ticket: TicketDef;
     builderWorktree: string;
     builderSummary: string;
     qaStrategy: SessionStrategy;
     state: QaStreamState;
-    createQa: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
+    createQa: (cwd: string, sessionId?: string) => Promise<BuilderAdapter | QaSessionHandle>;
     /** Host-owned ordinary QA boundary. Fresh strategies must return a validated successor. */
-    sessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string) => Promise<BuilderAdapter>;
+    sessionBoundary?: (adapter: BuilderAdapter, frozenAction: string, strategy: SessionStrategy, cwd: string, recovery?: QaSessionBoundaryRecovery) => Promise<BuilderAdapter>;
     /** Persist provider-native automatic compactions without imposing an ordinary QA boundary. */
     observeNativeCompactions?: (adapter: BuilderAdapter) => Promise<void>;
-    fix: (issues: string) => Promise<{
-        ok: boolean;
-        detail?: string;
-    }>;
+    fix: (request: QaFixRequest) => Promise<QaFixResult>;
     maxCycles: number;
+    /** Durable QA execution scope; review/fix budgets survive worker restarts. */
+    recovery: {
+        projectDir: string;
+        runId: string;
+    };
+    observer?: RunObserver;
     evidence?: (entry: {
         cycle: number;
+        reviewAttempt?: number;
+        remediationGeneration?: number;
+        attemptId?: string;
         outcome: string;
         detail: string;
+        durationMs?: number;
         qaDiff?: string[];
     }) => void;
     onNonconvergence?: (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
+    /** Resolve a QA blocker with the same still-open QA session before disposal. */
+    resolveBlocked?: (adapter: BuilderAdapter, reason: string) => Promise<{
+        result: import("./adapters/types.js").TurnResult;
+        status: import("./foreman.js").StepStatus;
+    }>;
+    onReportRecovery?: (context: {
+        packet: QaRecoveryPacket;
+        menu: readonly string[];
+        originalIssues?: string;
+        liveSession: boolean;
+        contextUsage?: unknown;
+    }) => Promise<QaReportRecoveryDecision>;
+    /** Accumulated authoritative QA/fix history, populated by runIsolatedQa. */
+    qaHistory?: QaReportHistoryEntry[];
+    qaRuntimeContext?: unknown;
+    /** A durable packet selected by build:resume and transferred by validated handoff. */
+    resumedRecovery?: QaRecoveryPacket;
+    /** True when a continuity wrapper validates and strips deltas before returning turn text. */
+    continuityManaged?: boolean;
 }
 export interface IsolatedQaResult {
     outcome: "passed" | "blocked" | "needs-human" | "nonconverged" | "waived";
@@ -50,6 +168,7 @@ export interface IsolatedQaResult {
     summary?: string;
 }
 export declare function runIsolatedQa(opts: IsolatedQaOptions): Promise<IsolatedQaResult>;
-export declare function buildQaReviewHandoff(ticket: TicketDef, builderSummary: string, diffDigest: string, validationChecklist: string[]): string;
+export declare function buildQaReviewHandoff(ticket: TicketDef, builderSummary: string, diffDigest: string, validationChecklist: string[], changeSummary?: unknown): string;
 export declare function compactWithRetry(adapter: BuilderAdapter): Promise<CompactResult>;
-export declare function buildDurableQaFixHandoff(ticket: TicketDef, issues: string, worktree: string, priorResult: string, diffDigest: string): string;
+export declare function buildDurableQaFixHandoff(ticket: TicketDef, request: QaFixRequest, worktree: string, priorResult: string, diffDigest: string, changeSummary?: string): string;
+export declare const QA_REPORT_RECOVERY_MENU: readonly ["Try another fresh QA.", "Use plain issues fallback.", "Manually fix saved JSON.", "Give QA specific instructions.", "Pause."];