synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/core/self-evolution/reward-agent.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 奖励智能体 REWARD AGENT — loop v2 (self-evolution as in-context RL).
+ *
+ * LLM as judge. Reads ONE episode's two arms from the {@link import('./episode-store.js')}
+ * episode store and CALCULATES 算分 reward(主臂) and reward(基线臂), each in
+ * [0,1], anchored on the objective evidence on disk (tests · health · 轨迹度量).
+ * advantage ＝ reward(主臂) − reward(基线臂). It finds errors / names gaps with a
+ * suggested direction ＝ 文本梯度 textual gradient; it NEVER edits any file; when
+ * there is no nameable gap it 弃权 abstains.
+ *
+ * It is a SIBLING of the 演进智能体 EVOLVING AGENT (optimizer.step; ONE bounded
+ * edit ≤L; never scores) — never parent-child. The reward agent runs FIRST (it
+ * scores), the 演进智能体 runs AFTER (it edits); each is code-spawned in a fresh
+ * context via {@link runHeadlessAgent} from `./host-harness.js` — NOT a skill,
+ * the same headless-spawn seam the canonical proposer uses.
+ *
+ * Write boundary: this module's ONLY write path is the episode dir — it calls
+ * {@link writeDiagnosis} and {@link advanceEpisodeStage} (to `scored`). It never
+ * touches a canonical target file, a 策略 POLICY snapshot, or the change dir
+ * (which it reads, never copies). The loss/health numbers from
+ * `src/core/fitness/loss.ts` stay on disk as ANCHORS — the reward score itself
+ * is the JUDGE'S OWN, anchored on but not equal to the loss.
+ *
+ * Uses the same fenced-block agent idiom as the EVOLVING AGENT: one fenced-block
+ * output discipline, a bounded repair loop on parse/validation failure,
+ * fail-closed plain (Zod-free) validation, and atomic episode-store writes.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { type EpisodeRecord } from './episode-store.js';
+export declare class RewardAgentOutputInvalid extends Error {
+    constructor(message: string);
+}
+export declare class RewardAgentInvocationError extends Error {
+    constructor(stderr: string);
+}
+/**
+ * The objective record each arm persists as `objective.json`, as the 奖励智能体
+ * REWARD AGENT READS it. A null-safe SUPERSET of the canonical on-disk
+ * {@link import('./critic-agent.js').ArmObjective} (which is the flat shape both
+ * arms WRITE): the MAIN ARM may instead carry the nested-learn fallback fields
+ * (`testMetrics`, `healthSignal`, a nested {@link import('../fitness/loss.js').PerChangeLoss}
+ * `loss`) when an older capture path wrote a raw {@link import('../fitness/sample.js').FitnessSample}.
+ * This module reads ONLY the fields it maps to anchors and is null-safe to
+ * either shape, so a divergence in the exact layout cannot crash the judge.
+ *
+ * Named distinctly from the canonical `ArmObjective` (the barrel re-exports the
+ * critic-agent declaration) so there is no ambiguous duplicate export.
+ */
+export interface RewardArmObjectiveInput {
+    /** Flat pass rate in [0,1] (CRITIC AGENT shape). */
+    passRate?: number | null;
+    testsTotal?: number | null;
+    testsFailed?: number | null;
+    /** Flat normalized health penalty in [0,1] (CRITIC AGENT shape). */
+    healthPenalty?: number | null;
+    /** Flat blended loss in [0,1] (CRITIC AGENT shape) OR nested PerChangeLoss (MAIN ARM shape). */
+    loss?: number | null | {
+        functionalLoss?: number | null;
+        healthPenalty?: number | null;
+        loss?: number | null;
+    };
+    verified?: boolean;
+    observedStatus?: string | null;
+    measuredAt?: string | null;
+    /** MAIN ARM shape (FitnessSample): functional metrics live under testMetrics. */
+    testMetrics?: {
+        passRate?: number | null;
+    } | null;
+    /** MAIN ARM shape (FitnessSample): the raw health signal, distinct from loss.healthPenalty. */
+    healthSignal?: number | null;
+    /** Additive/forward-compatible fields pass through unread. */
+    [key: string]: unknown;
+}
+/** The anchors block mapped from both arms' objectives (nulls where skipped). */
+export interface DiagnosisAnchors {
+    mainLoss: number | null;
+    baselineLoss: number | null;
+    mainPassRate: number | null;
+    baselinePassRate: number | null;
+    mainHealthPenalty: number | null;
+    baselineHealthPenalty: number | null;
+}
+/** One named error the judge found, addressed to a quoted span in a real file. */
+export interface DiagnosisError {
+    arm: 'main' | 'baseline';
+    description: string;
+    evidence: {
+        file: string;
+        quote: string;
+    };
+}
+/** One nameable gap, addressed to a heading (`section`) in a target file. */
+export interface DiagnosisGap {
+    file: string;
+    /** A heading in the target file; the `'*'` wildcard is allowed. */
+    section: string;
+    description: string;
+}
+/**
+ * The `diagnosis.json` the 奖励智能体 REWARD AGENT writes (schemaVersion 1).
+ * advantage ＝ reward(主臂) − reward(基线臂); `null` when the baseline arm was
+ * skipped (no comparison possible) OR when the judge 弃权 abstained.
+ */
+export interface RewardDiagnosis {
+    schemaVersion: 1;
+    episodeId: string;
+    changeName: string;
+    targetId: string;
+    policyVersions: {
+        main: number | null;
+        baseline: number | null;
+    };
+    rewardMain: number;
+    /** null when the baseline arm was skipped. */
+    rewardBaseline: number | null;
+    /** reward(主臂) − reward(基线臂); null when baseline skipped or abstained. */
+    advantage: number | null;
+    anchors: DiagnosisAnchors;
+    errors: DiagnosisError[];
+    gaps: DiagnosisGap[];
+    /** 文本梯度 textual gradient; null only when abstained. */
+    textualGradient: string | null;
+    abstained: boolean;
+    abstainReason?: string;
+}
+/** Assembled input for {@link assembleRewardAgentPrompt}. */
+export interface RewardAgentPromptInput {
+    changeName: string;
+    targetId: string;
+    policyVersions: {
+        main: number | null;
+        baseline: number | null;
+    };
+    /** 主智能体 MAIN AGENT (policy vN+1) capture. */
+    mainArm: {
+        skeleton: object | null;
+        /** Raw transcript text (jsonl) — bounded by {@link assembleRewardAgentPrompt}. */
+        transcript: string | null;
+        objective: RewardArmObjectiveInput;
+    };
+    /**
+     * CRITIC AGENT（基线智能体 baseline agent, policy vN）capture. `null` when the
+     * baseline arm was SKIPPED — the BASELINE ARM block is OMITTED entirely and
+     * the prompt states no comparison is possible (null rewardBaseline/advantage).
+     */
+    baselineArm: {
+        skeleton: object | null;
+        transcript: string | null;
+        objective: RewardArmObjectiveInput;
+    } | null;
+    /** Bounded excerpts of the 5 artifacts + test-report.md read from the change dir. */
+    artifacts: {
+        file: string;
+        content: string;
+    }[];
+    /** Pre-mapped anchors (loss/health/passRate) from both arms. */
+    anchors: DiagnosisAnchors;
+}
+/**
+ * Assemble the 奖励智能体 REWARD AGENT prompt. Pure (no I/O); exported for golden
+ * tests. Ordered blocks:
+ *   1. PRELUDE — the judge contract.
+ *   2. MAIN ARM (主智能体, policy vN+1) — skeleton + bounded transcript excerpt.
+ *   3. BASELINE ARM (CRITIC AGENT（基线智能体）, policy vN) — same; OMITTED
+ *      ENTIRELY when the baseline arm was skipped (a one-line note replaces it,
+ *      demanding null rewardBaseline/advantage).
+ *   4. ARTIFACTS — the 5 artifacts + test-report.md, bounded excerpts.
+ *   5. OBJECTIVE EVIDENCE — both arms' anchors verbatim (the on-disk loss/health
+ *      numbers that anchor the score).
+ */
+export declare function assembleRewardAgentPrompt(input: RewardAgentPromptInput): string;
+interface ParsedDiagnosis {
+    rewardMain: number;
+    rewardBaseline: number | null;
+    advantage: number | null;
+    errors: DiagnosisError[];
+    gaps: DiagnosisGap[];
+    textualGradient: string | null;
+    abstained: boolean;
+    abstainReason?: string;
+}
+/**
+ * Parse the judge's `json:diagnosis` block with a strict one-block discipline:
+ * exactly one fenced block, well-formed JSON, then fail-closed shape + range
+ * validation.
+ *
+ * Throws {@link RewardAgentOutputInvalid} on any violation (the repair loop
+ * re-prompts with the concrete message appended).
+ */
+export declare function parseRewardAgentResponse(text: string): ParsedDiagnosis;
+/** Map an arm's objective to its (loss, passRate, healthPenalty) anchors. */
+export declare function mapArmAnchors(objective: RewardArmObjectiveInput | null | undefined): {
+    loss: number | null;
+    passRate: number | null;
+    healthPenalty: number | null;
+};
+/** Build the {@link DiagnosisAnchors} block from both arms' objectives. */
+export declare function buildAnchors(mainObjective: RewardArmObjectiveInput, baselineObjective: RewardArmObjectiveInput | null): DiagnosisAnchors;
+export interface RunRewardAgentOptions {
+    repoRoot: string;
+    episodeId: string;
+    /** Injected for tests; defaults to node's spawn. */
+    spawn?: typeof nodeSpawn;
+    /** Override the agent binary; defaults to the host harness's default. */
+    binary?: string;
+    /** Bounded re-prompts on parse/validation failure (default 2 ⇒ at most 3 spawns). */
+    maxRepairAttempts?: number;
+}
+export interface RunRewardAgentResult {
+    diagnosis: RewardDiagnosis;
+    /** Absolute path of the written `diagnosis.json`. */
+    diagnosisPath: string;
+    /** The episode record after advancing to `scored`. */
+    episode: EpisodeRecord;
+}
+/**
+ * Run the 奖励智能体 REWARD AGENT end-to-end for one episode:
+ *   1. read the episode + both arms (baseline omitted when skipped),
+ *   2. map anchors and assemble the prompt,
+ *   3. spawn the judge (fresh context) and parse with a bounded repair loop —
+ *      on a parse/validation failure, re-prompt with the concrete error appended
+ *      (same pattern as `runCanonicalProposerAgentWithRepair`),
+ *   4. RECOMPUTE advantage from the claimed rewards and REJECT a mismatch
+ *      (|recomputed − claimed| > 1e-9 ⇒ repairable error); when the baseline was
+ *      skipped, rewardBaseline and advantage MUST both be null,
+ *   5. write `diagnosis.json` via {@link writeDiagnosis} and advance the episode
+ *      stage to `scored` via {@link advanceEpisodeStage}.
+ *
+ * The ONLY write path is the episode dir. Invocation errors (agent crash) are
+ * NOT repaired — they propagate as {@link RewardAgentInvocationError}.
+ */
+export declare function runRewardAgent(opts: RunRewardAgentOptions): Promise<RunRewardAgentResult>;
+export {};
+//# sourceMappingURL=reward-agent.d.ts.map