loopforge 2.11.0 → 3.2.1

package/dist/mcp/round-lifecycle.d.ts

@@ -0,0 +1,216 @@
+/** LoopForge MCP — Round lifecycle.
+ *
+ * The round state machine split out of SessionManager: crash recovery,
+ * transaction execution, disposition result building, and the advance
+ * pipeline. SessionManager owns "who may touch a session" (registry, queue,
+ * leases); this class owns "what happens to a session" (state machine,
+ * recovery, result building).
+ *
+ * Every method was moved verbatim from SessionManager. Only reference paths
+ * changed (this.sessions.* → registry.*, this.ownerId / this.leaseMs →
+ * constructor deps, this.contextProvider → getContext()).
+ */
+import { LoopForgeEngine } from "../engine.js";
+import type { LoopForgeRequest, LoopForgeResponse, SelfEvaluation, VerificationFlag, ExternalContextProvider, LoopTerminalSink } from "../protocol.js";
+import type { ProviderSnapshot } from "../evidence-provider.js";
+import type { RoundTransactionSnapshot } from "../round-transaction.js";
+import type { LoopStore, VaultEntry } from "../loop-store.js";
+import type { SessionStateStore } from "../storage.js";
+export interface McpSession {
+    sessionId: string;
+    loopId: string;
+    task: string;
+    engine: LoopForgeEngine;
+    currentRound: number;
+    maxRounds: number;
+    successTrajectory: boolean[];
+    status: "running" | "stopped" | "stalled" | "paused";
+    createdAt: number;
+    /** Previous round's validated SelfEvaluation — used by verification gate. */
+    lastSelfEval?: SelfEvaluation;
+    consecutiveRejections: number;
+    /** Which enforcement check triggered the last rejection.
+     *  Only same-check rejections accumulate toward the max. */
+    lastRejectionCheck: string;
+    /** v2.12: Consecutive rounds where the agent used drift_clarification
+     *  to waive R7 rejection. Reset to 0 when a round has no intent_drift.
+     *  Terminates the loop when exceeding policy.drift_clarification_max_streak. */
+    driftClarificationStreak: number;
+    /** v2.13: Files changed in skipped rounds during the last backtrack.
+     *  The next round's verification gate checks that the agent did not
+     *  continue working on stale files without restoring the workspace.
+     *  Cleared after the first successful post-backtrack round. */
+    backtrackSkippedFiles: string[];
+    /** v2.12: Git HEAD of the last backtrack restore point. The verification
+     *  gate checks the workspace returns to this commit before accepting.
+     *  Cleared after the first successful post-backtrack round. */
+    backtrackTargetGitHead?: string;
+    /** Evidence baseline captured immediately before the agent receives a prompt. */
+    evidenceBaseline?: ProviderSnapshot[];
+    /** Schema-versioned transaction for the prompt currently held by the agent. */
+    roundSnapshot?: RoundTransactionSnapshot;
+    /** Persisted prompt prevents resume from compiling the same round twice. */
+    currentPrompt?: string | null;
+    currentLevel?: string;
+    /** Structured warnings from the most recent compile — preferred over regex parsing. */
+    currentWarnings?: string[];
+    /** v3.0.1: The full compile response of the current round, cached so the
+     *  typed projection (getProjection) derives from it instead of recompiling
+     *  the whole vault. Freshness is checked via loop_id + round; rebuilt by
+     *  every compile path. Not persisted — cold sessions fall back to compiling. */
+    lastCompileResponse?: LoopForgeResponse | null;
+}
+export interface McpSessionSummary {
+    sessionId: string;
+    loopId: string;
+    round: number;
+    status: "running" | "stopped" | "stalled" | "paused";
+}
+export interface StartInput {
+    task: string;
+    loopId?: string;
+    maxRounds?: number;
+    domain?: string;
+    planSource?: string;
+    constraints?: string[];
+}
+export interface AdvanceResult {
+    sessionId: string;
+    round: number;
+    /** Stable logical identity; unchanged when enforcement retries the round. */
+    roundId?: string;
+    prompt: string | null;
+    stopReason?: string;
+    /** v2.0.1: Human-readable context for why the loop stopped.
+     *  Provides facts the agent can use to decide its next action,
+     *  without LoopForge prescribing a specific behavior. */
+    stopDetail?: string;
+    level?: string;
+    roundSuccess?: boolean;
+    warnings?: string[];
+    /** v1.13: Enforcement action for this round. accept/reject/terminate.
+     *  When "reject", the prompt contains a rejection notice and the agent
+     *  must redo the same round. Round counter does NOT increment. */
+    enforcementAction?: "accept" | "reject" | "terminate" | "backtrack";
+    /** v1.13: When enforcementAction is "reject" or "terminate", the reason
+     *  why the round was rejected or the loop was terminated. */
+    enforcementReason?: string;
+}
+/** Narrow view of the session registry the lifecycle may touch. The owning
+ *  SessionManager implements this over its private Map, so the lifecycle
+ *  never holds or mutates registry state directly. */
+export interface SessionRegistry {
+    get(sessionId: string): McpSession | undefined;
+    values(): Iterable<McpSession>;
+    upsert(session: McpSession): void;
+}
+export interface RoundLifecycleDeps {
+    store: LoopStore;
+    sessionStore: SessionStateStore | undefined;
+    registry: SessionRegistry;
+    terminalSinks: Set<LoopTerminalSink>;
+    /** Stable process-local owner token used for cross-process session leases. */
+    ownerId: string;
+    /** Session lease duration; stamped into saved session entries. */
+    leaseMs: number;
+    /** Live accessor for the mutable contextProvider field on SessionManager. */
+    getContext: () => ExternalContextProvider | undefined;
+}
+export declare function buildLoopRequest(session: McpSession, lastEval?: SelfEvaluation, verificationFlags?: VerificationFlag[]): LoopForgeRequest;
+export declare class RoundLifecycle {
+    private readonly store;
+    private readonly sessionStore;
+    private readonly registry;
+    private readonly terminalSinks;
+    private readonly ownerId;
+    private readonly leaseMs;
+    private readonly getContext;
+    constructor(deps: RoundLifecycleDeps);
+    /** Persist session state to vault for cross-process recovery.
+     *  The filtered vault and replacement entry are written once under the
+     *  backend lock, so recovery never observes the old two-write gap. */
+    save(session: McpSession): void;
+    /** Reconstruct a McpSession from a vault session_state entry.
+     *  Returns null if the entry is not "running" status.
+     *  Shared by resume() and autoResumeAll(). */
+    reconstructSession(entry: VaultEntry, allowPaused?: boolean): McpSession | null;
+    /** Apply a prepared round to the session, persist, and build the result.
+     *  Shared by reconcileCommittedRound, resume, and unpause — the three
+     *  compile-then-persist tails were previously copy-pasted. */
+    private persistPrepared;
+    private restoredPromptResult;
+    /** Reconcile the crash window where feedback committed but session_state
+     *  still points at the old prompt. Returns null when no commit is pending. */
+    private reconcileCommittedRound;
+    /** Resume tail: the session has been reconstructed and registered. Reconcile
+     *  a committed-but-undelivered round, restore the held prompt, or compile
+     *  the next prompt from current round state (legacy path). */
+    resume(session: McpSession): AdvanceResult;
+    /** Unpause tail: the session has been reconstructed and registered with
+     *  status "running". Refresh async evidence, reconcile a committed round,
+     *  restore the held prompt, or compile the next prompt. */
+    unpause(session: McpSession): Promise<AdvanceResult>;
+    /** Record a gate_opened entry when an accepted round reports a high-risk
+     *  blocker (USER_RISK hit). Idempotent per gate. The gate is a record
+     *  layer — it never blocks the round decision flow. */
+    private recordGateFromBlocked;
+    /** Undecided user gate descriptions for a loop (recorded but unresolved). */
+    listOpenGateDescriptions(loopId: string): string[];
+    /** Extract a SelfEvaluation from agent output.
+     *  Structured param preferred → regex extraction → heuristic fallback.
+     *  Returns null only when both regex and heuristic returned null. */
+    private extractEvaluation;
+    /** Execute the round transaction and apply per-rule rejection tracking.
+     *  MUTATES: session.roundSnapshot, session.consecutiveRejections,
+     *           session.lastRejectionCheck, session.lastSelfEval,
+     *           session.successTrajectory, session.driftClarificationStreak */
+    private executeRoundTransaction;
+    /** v2.12: Update the clarification streak based on the round result.
+     *  - Substantive clarification (anchors present): keep streak — genuine pivot.
+     *  - No intent_drift this round: reset streak to 0.
+     *  - Weak clarification rejected by R7: streak was already consumed by
+     *    enforceIntentDrift to decide reject vs terminate; staleness is handled
+     *    on the enforcement side. We sync the persisted counter for crash recovery.
+     *  v3.2.1: when a HIGHER-PRIORITY rule (R1–R6/R8/R9/R-EVID) rejected the
+     *  round, R7 never participated — clarificationAccepted is undefined (it
+     *  is only set on the continue path). Touching the streak there would
+     *  pollute it with rejections unrelated to drift and terminate the loop
+     *  one weak clarification early.
+     *  MUTATES: session.driftClarificationStreak */
+    private updateClarificationStreak;
+    /** Build a rejection result: compile a retry prompt, persist, return.
+     *  MUTATES: session.roundSnapshot, session.currentPrompt, session.currentLevel */
+    private buildRejectionResult;
+    /** v2.10: Build a backtrack result — roll back to last clean round.
+     *  Resets the round counter to the restore target + 1, merges preserved
+     *  discoveries, compiles from the restored state, and injects the
+     *  backtrack prompt at the top.
+     *  MUTATES: session.currentRound, session.roundSnapshot,
+     *           session.currentPrompt, session.currentLevel,
+     *           session.consecutiveRejections, session.lastSelfEval */
+    private buildBacktrackResult;
+    /** Build a termination result: persist stopped status, notify sinks.
+     *  MUTATES: session.status, session.currentPrompt */
+    private buildTerminationResult;
+    /** Build a stop result: persist stopped/stalled status, notify sinks.
+     *  MUTATES: session.status, session.currentPrompt */
+    private buildStopResult;
+    /** Compile the next round's prompt and advance the session.
+     *  Includes the commit fence (pause/delete race guard) and context provider.
+     *  MUTATES: session.currentRound, session.currentPrompt, session.currentLevel,
+     *           session.evidenceBaseline, session.roundSnapshot */
+    private advanceToNextRound;
+    private advanceUnlocked;
+    /** Core cycle entry used by SessionManager.advance after the queue + lease
+     *  dance: validate → extract → execute transaction → route disposition
+     *  → advance to next round (continue) or return terminal result.
+     *  @param roundId v3.0.1: the roundId of the round this submission reports
+     *    on (from the last start/next/resume response). Anchors the submission;
+     *    a stale or duplicate submission returns the held prompt instead of
+     *    being processed. Optional — when absent the anchor check is skipped. */
+    advance(sessionId: string, output: string, preExtractedEval?: SelfEvaluation, roundId?: string): Promise<AdvanceResult>;
+    /** Write back loop knowledge to long-term memory.
+     *  Uses shared base builder from policy.ts. Called when a loop terminates. */
+    notifyTerminal(session: McpSession, stopReason: string): Promise<void>;
+}
+//# sourceMappingURL=round-lifecycle.d.ts.map

package/dist/mcp/round-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-lifecycle.d.ts","sourceRoot":"","sources":["../../src/mcp/round-lifecycle.ts"],"names":[],"mappings":"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"}