synergyspec-selfevolving 1.4.0 → 2.1.0

package/dist/core/self-evolution/edits-contract.js

@@ -0,0 +1,89 @@
+/**
+ * Shared candidate-EDITS contract.
+ *
+ * The single place that (a) defines the no-op / invalid-output error classes the
+ * manual host-authored channel raises, (b) validates already-structured
+ * candidate edits against the target-scoped file set + the frozen gate-defining
+ * files, and (c) renders a whole-file-replacement unified diff. Both surviving
+ * edit channels share it byte-for-byte:
+ *   - the manual `--from-edits` / `--from-learn` host-authored path
+ *     (`commands/self-evolution.ts` → `packageHostEdits`, `promote.ts`), and
+ *   - the loop-v2 演进智能体 EVOLVING AGENT (`evolving-agent.ts`).
+ *
+ * Pure (no I/O, no spawn): this module never applies, promotes, or mutates any
+ * canonical file.
+ */
+import { GATE_DEFINING_FILES } from './candidate-gates.js';
+export class CanonicalProposerOutputInvalid extends Error {
+    constructor(message) {
+        super(`canonical proposer output invalid: ${message}`);
+        this.name = 'CanonicalProposerOutputInvalid';
+    }
+}
+/** The model declined to edit anything (empty edits). Not an error — a no-op. */
+export class CanonicalProposerNoOp extends Error {
+    constructor() {
+        super('canonical proposer returned no edits');
+        this.name = 'CanonicalProposerNoOp';
+    }
+}
+/** The headless agent invocation itself failed (crash / empty output). */
+export class CanonicalProposerInvocationError extends Error {
+    constructor(stderr) {
+        super(`canonical proposer invocation failed: ${stderr}`);
+        this.name = 'CanonicalProposerInvocationError';
+    }
+}
+/**
+ * Validate already-structured candidate edits against the allowed (target-
+ * scoped) file set and the frozen gate-defining files. Author-agnostic: this is
+ * the SINGLE place that enforces, at propose time, that every edit (a) is a
+ * well-formed `{relPath, content}` object, (b) does not touch a
+ * `GATE_DEFINING_FILES` entry (the frozen oracle/gate files), and (c) stays
+ * inside `allowedFiles`. Both the manual host-authored (`--from-edits`) path and
+ * the loop-v2 演进智能体 EVOLVING AGENT call this so their safety contract is
+ * byte-identical. relPaths are normalized to POSIX separators.
+ *
+ * Throws {@link CanonicalProposerNoOp} when `rawEdits` is empty and
+ * {@link CanonicalProposerOutputInvalid} for any shape / frozen / scope
+ * violation. Path traversal and absolute paths are rejected transitively: they
+ * can never be a member of `allowedFiles`, so they fail the scope check.
+ */
+export function validateCandidateEdits(rawEdits, allowedFiles) {
+    if (rawEdits.length === 0) {
+        throw new CanonicalProposerNoOp();
+    }
+    const allowed = new Set(allowedFiles.map((p) => p.replace(/\\/g, '/')));
+    const frozen = new Set(GATE_DEFINING_FILES.map((p) => p.replace(/\\/g, '/')));
+    const validated = [];
+    for (const e of rawEdits) {
+        if (!e || typeof e !== 'object') {
+            throw new CanonicalProposerOutputInvalid('edit entry must be an object');
+        }
+        const relPath = e.relPath;
+        const content = e.content;
+        if (typeof relPath !== 'string' || typeof content !== 'string') {
+            throw new CanonicalProposerOutputInvalid('edit must have string relPath and string content');
+        }
+        const norm = relPath.replace(/\\/g, '/');
+        if (frozen.has(norm)) {
+            throw new CanonicalProposerOutputInvalid(`edit relPath "${relPath}" is a gate-defining/frozen file and may never be proposed`);
+        }
+        if (!allowed.has(norm)) {
+            throw new CanonicalProposerOutputInvalid(`edit relPath "${relPath}" is outside the target's declared files`);
+        }
+        validated.push({ relPath: norm, content });
+    }
+    return validated;
+}
+/** Render a whole-file-replacement unified diff (human-readable; git-apply friendly). */
+export function renderUnifiedDiff(relPath, oldContent, newContent) {
+    const oldLines = oldContent.length === 0 ? [] : oldContent.replace(/\n$/, '').split('\n');
+    const newLines = newContent.replace(/\n$/, '').split('\n');
+    const oldStart = oldLines.length === 0 ? 0 : 1;
+    const header = `--- a/${relPath}\n+++ b/${relPath}\n` +
+        `@@ -${oldStart},${oldLines.length} +1,${newLines.length} @@`;
+    const body = [...oldLines.map((l) => `-${l}`), ...newLines.map((l) => `+${l}`)].join('\n');
+    return `${header}\n${body}`;
+}
+//# sourceMappingURL=edits-contract.js.map

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

@@ -0,0 +1,234 @@
+/**
+ * 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, type PolicyLedgerEntry } from './policy/policy-store.js';
+import { type EpisodeStage } from './episode-store.js';
+import { type ArmObjective, type CriticBaselineMode } from './critic-agent.js';
+import { type RewardConfig } from './reward-aggregator.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';
+/**
+ * Count the consecutive trailing rolled-back episodes in the 版本账本 ledger.
+ *
+ * A bad streak's ledger tail reads `…, evolve, rollback, evolve, rollback` — the
+ * 演进智能体 EVOLVING AGENT appends exactly one 'evolve' after each decision, so
+ * each counted rollback is reached by skipping the single 'evolve' that follows
+ * it. A 'kept' episode leaves a bare 'evolve' (no following rollback) which
+ * breaks the streak, as do 'init'/'refused'. Returns 0 when the head is not a
+ * rollback (the last episode kept). Pure.
+ */
+export declare function consecutiveRollbacks(ledger: readonly PolicyLedgerEntry[]): number;
+/**
+ * 步长 step-size schedule for the 演进智能体 EVOLVING AGENT's edit budget L.
+ *
+ * Backtracking-line-search / trust-region move (and SkillOpt's decaying edit
+ * budget): after an edit LOST ground and was rolled back, the next edit should
+ * be SMALLER — a smaller blast radius is cheaper to undo and its cause is more
+ * legible, and it keeps a struggling lineage from drifting via repeated
+ * full-size swings. HALVE the base budget once per consecutive rolled-back
+ * episode, never below `minBudget` (itself clamped to `base`, so a caller-shrunk
+ * base is never RAISED). A healthy lineage (no trailing rollback) keeps `base`.
+ * Pure.
+ */
+export declare function scheduledEditBudget(ledger: readonly PolicyLedgerEntry[], base: number, minBudget?: number): number;
+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;
+    /**
+     * 奖励智能体 REWARD AGENT judge-quality knobs (from `selfEvolution.reward`).
+     * Omitted ⇒ single sample, flag-only tamper (historical, zero extra spawns).
+     */
+    reward?: RewardConfig;
+    /**
+     * CRITIC AGENT（基线智能体）baseline construction (from `selfEvolution.critic`).
+     * Omitted ⇒ the critic's default 're-do' (regenerate the change under vN).
+     */
+    critic?: {
+        baselineMode?: CriticBaselineMode;
+    };
+    /** 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