synergyspec-selfevolving 1.4.0 → 2.0.0

package/dist/core/self-evolution/episode-orchestrator.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Episode orchestrator — the rollback-before-evolution heart of loop v2
+ * (self-evolution as in-context RL).
+ *
+ * One `runEpisode` runs ONE synergyspec-selfevolving change through the full
+ * loop, in a STRICT, durably-persisted order — correctness of ordering is the
+ * design contract:
+ *
+ *   a. acquireInFlight                    — one in-flight episode per target.
+ *   b. ensure 单一血统 single lineage      — init v0 from resolved files when new;
+ *                                            policyVersionMain = lineage head.
+ *   c. createEpisode + writeArmCapture     — record the 主智能体 MAIN AGENT (frozen
+ *                                            actor, policy vN+1) arm; advance
+ *                                            'main-arm-captured'.
+ *   d. CRITIC AGENT（基线智能体 baseline    — runCriticAgent reruns LAST episode's
+ *      agent）                              policy vN on the SAME change, OR skip
+ *                                            ('baseline-skipped') when the lineage
+ *                                            has < 2 versions / last action refused.
+ *   e. 奖励智能体 REWARD AGENT             — runRewardAgent CALCULATES 算分
+ *                                            reward(主臂)＆reward(基线臂), advantage
+ *                                            ＝ reward(主臂) − reward(基线臂), the
+ *                                            文本梯度 textual gradient; writes
+ *                                            diagnosis.json; advances 'scored'.
+ *   f. DECISION on the main arm's edits:
+ *        - 弃权 abstained / no gaps        → advance 'abstained'; SKIP evolution.
+ *        - bad advantage (< threshold)     → ROLLBACK the 策略 POLICY to the prior
+ *                                            good version, THEN append the 否决缓冲
+ *                                            reject-buffer entry — BOTH durably on
+ *                                            disk — THEN advance 'rolled-back'.
+ *        - otherwise                        → advance 'kept'.
+ *   g. 演进智能体 EVOLVING AGENT           — ONLY after (f) persisted: runEvolvingAgent
+ *      (optimizer.step)                     reads the reject-buffer FRESH from disk
+ *                                            (so THIS episode's just-written entry is
+ *                                            in its prompt) and either not-spawned /
+ *                                            refused / evolved.
+ *   h. advance 'closed' + releaseInFlight  — ALWAYS, even on error.
+ *
+ * ORDERING GUARANTEE: the rollback + reject-buffer write are SEQUENTIAL awaits
+ * that BOTH complete (and the stage reads 'rolled-back'/'kept') before
+ * {@link runEvolvingAgent} is even called. (f) and (g) are never parallelized
+ * and never share a Promise.all.
+ *
+ * This module orchestrates; it never spawns an agent itself — the three agents
+ * own their own {@link runHeadlessAgent} spawns (the `spawn` seam threads to all
+ * three). The only state it owns is the ordering + the rollback/reject decision.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { LearnReport } from '../learn.js';
+import type { TrajectorySource } from '../trajectory/source.js';
+import { type PolicyResolveFiles } from './policy/policy-store.js';
+import { type EpisodeStage } from './episode-store.js';
+import { type ArmObjective } from './critic-agent.js';
+import { type RunEvolvingAgentResult } from './evolving-agent.js';
+/** The 主智能体 MAIN AGENT (policy vN+1) capture the orchestrator records. */
+export interface MainArmCapture {
+    /** Raw session transcript text, when provided; persisted as `transcript.jsonl`. */
+    transcript?: string;
+    /** Bounded action skeleton of the observed run, when discoverable. */
+    skeleton?: object;
+    /**
+     * The arm objective, byte-shape-IDENTICAL to the CRITIC AGENT's
+     * {@link ArmObjective} so the 奖励智能体 REWARD AGENT reads both arms uniformly.
+     */
+    objective: ArmObjective;
+}
+export interface CaptureMainArmOptions {
+    repoRoot: string;
+    changeName: string;
+    /**
+     * An ALREADY-COMPUTED learn report (from `generateLearnReport`). Its
+     * `fitnessSample` carries the graded pass rate / health / observed-trajectory
+     * facts — the orchestrator REUSES that grading rather than re-running it.
+     */
+    report: LearnReport;
+    /**
+     * Optional trajectory handles. When the learn report did not carry an
+     * `observedRun` skeleton (older capture paths), these let the caller hand a
+     * skeleton / raw transcript directly, OR the orchestrator re-discovers the
+     * skeleton via {@link getTrajectoryForChange}. A `trajectorySource` override is
+     * honored first (tests / explicit harness selection).
+     */
+    trajectoryHandles?: {
+        /** Verbatim session transcript text to persist as `transcript.jsonl`. */
+        transcript?: string;
+        /** Pre-computed action skeleton (else derived from the discovered trajectory). */
+        skeleton?: object;
+        /** Trajectory-source override (tests); else the registry auto-detects. */
+        trajectorySource?: TrajectorySource;
+    };
+}
+/**
+ * Build the 主智能体 MAIN AGENT arm `{transcript?, skeleton?, objective}` from an
+ * already-computed learn report's {@link FitnessSample} + the discovered
+ * trajectory.
+ *
+ * REUSES the learn/fitness grading verbatim — it never re-grades:
+ *   - `objective.passRate` prefers the OBSERVED pass rate
+ *     (`fitnessSample.trajectoryFacts.observedPassRate` when a runner ran), else
+ *     the authored `testMetrics.passRate`, else `null` (never fabricated);
+ *   - `objective.healthPenalty` is `fitnessSample.healthSignal` (the raw
+ *     "no signal ⇒ null" health reading, distinct from the `?? 0`-defaulted
+ *     `loss.healthPenalty`);
+ *   - `objective.loss` is the blended `fitnessSample.loss.loss` (or `null`);
+ *   - `verified` / `observedStatus` come from `trajectoryFacts`.
+ * The shape is byte-identical to {@link ArmObjective} so both arms read uniformly.
+ */
+export declare function captureMainArm(opts: CaptureMainArmOptions): Promise<MainArmCapture>;
+/** The decision the orchestrator made on the main arm's edits. */
+export type EpisodeDecision = 'rolled-back' | 'kept' | 'abstained';
+export interface RunEpisodeOptions {
+    repoRoot: string;
+    targetId: string;
+    changeName: string;
+    /** Absolute path of the change dir; recorded in episode.json, never copied. */
+    changeDirPath: string;
+    /** The 主智能体 MAIN AGENT arm (from {@link captureMainArm}). */
+    mainArm: MainArmCapture;
+    /**
+     * advantage ＝ reward(主臂) − reward(基线臂) threshold below which the 策略
+     * POLICY is rolled back to the prior version BEFORE the 演进智能体 EVOLVING
+     * AGENT runs. Default 0 (a non-positive advantage triggers a rollback).
+     */
+    advantageRollbackThreshold?: number;
+    /** Edit budget L for the 演进智能体 EVOLVING AGENT. Default 40. */
+    editBudget?: number;
+    /** Injectable spawn seam — threaded to ALL THREE agents. Defaults to node's spawn. */
+    spawn?: typeof nodeSpawn;
+    /** Injectable clock for the lock + episode id; defaults to `new Date()`. */
+    now?: Date;
+    /**
+     * TEST seam: the file resolver {@link initPolicyLineage} uses to snapshot v0
+     * when the lineage is new. Defaults to the real `resolveTargetLocalFiles`.
+     */
+    resolveFiles?: PolicyResolveFiles;
+}
+export interface RunEpisodeResult {
+    episodeId: string;
+    /** True when the CRITIC AGENT（基线智能体 baseline agent）arm was skipped. */
+    baselineSkipped: boolean;
+    /** advantage ＝ reward(主臂) − reward(基线臂); null when skipped or abstained. */
+    advantage: number | null;
+    decision: EpisodeDecision;
+    /** The 演进智能体 EVOLVING AGENT outcome, or `null` when it was never spawned. */
+    evolution: RunEvolvingAgentResult | null;
+    /** The lineage head version AFTER the episode (post-rollback / post-evolve). */
+    newPolicyVersion: number | null;
+}
+/** Returned (not thrown) when the target already has a non-stale in-flight lock. */
+export interface RunEpisodeBusy {
+    episodeId: null;
+    busy: true;
+    reason: string;
+}
+/**
+ * Run ONE episode through the loop in the strict, durably-persisted order
+ * documented at the top of this module. See {@link RunEpisodeResult}.
+ *
+ * The in-flight lock is released in a finally guard so a throw mid-episode never
+ * wedges the target's slot.
+ */
+export declare function runEpisode(opts: RunEpisodeOptions): Promise<RunEpisodeResult | RunEpisodeBusy>;
+export interface ResumeEpisodeOptions {
+    repoRoot: string;
+    episodeId: string;
+    /** Injectable spawn seam — threaded to the remaining agents. */
+    spawn?: typeof nodeSpawn;
+    /** advantage rollback threshold (default 0), for an episode resumed before the decision. */
+    advantageRollbackThreshold?: number;
+    /** Edit budget L (default 40). */
+    editBudget?: number;
+}
+export interface ResumeEpisodeResult {
+    episodeId: string;
+    /** The stage the episode was at when resume was called. */
+    resumedFrom: EpisodeStage;
+    /** The stage it reached after the resume re-ran the remaining steps. */
+    stage: EpisodeStage;
+    evolution: RunEvolvingAgentResult | null;
+}
+/**
+ * Re-enter a partially-run episode at its recorded stage and idempotently run
+ * the REMAINING steps. Best-effort — used by the CLI `episode resume`. The
+ * episode stage machine is monotonic, so this picks up from the first not-yet-
+ * done step rather than re-advancing a stage already entered:
+ *
+ *   - 'scored'                    → run the decision (f) then the 演进智能体 (g).
+ *   - 'rolled-back' / 'kept'      → run the 演进智能体 EVOLVING AGENT (g) then close.
+ *   - 'evolved'/'evolution-refused'/'abstained' → close.
+ *   - earlier stages              → not auto-resumable here (the arms / reward
+ *                                   agent need their own re-entry); reported as-is.
+ *
+ * NOTE: resume does NOT re-acquire the in-flight lock — the original
+ * {@link runEpisode} already released it; a resume is an operator-driven
+ * recovery, not a concurrent run.
+ */
+export declare function resumeEpisode(opts: ResumeEpisodeOptions): Promise<ResumeEpisodeResult>;
+//# sourceMappingURL=episode-orchestrator.d.ts.map