synergyspec-selfevolving 1.4.0 → 2.1.0

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

@@ -0,0 +1,208 @@
+/**
+ * 演进智能体 EVOLVING AGENT (optimizer.step) — loop v2 (self-evolution as
+ * in-context RL).
+ *
+ * The EVOLVING AGENT is the ONLY agent in the loop that EDITS. Given the
+ * 奖励智能体 REWARD AGENT's diagnosis (errors, gaps with section anchors, the
+ * 文本梯度 textual gradient, advantage), the 否决缓冲 reject-buffer (directions
+ * already vetoed), and the 成功保护 success protections (do-not-prune), it makes
+ * ONE bounded edit of ≤ L changed lines (added + removed) with a checkable
+ * prediction, OR it refuses when the diagnosis is too weak to name a concrete
+ * edit. It NEVER scores — scoring belongs to the 奖励智能体 REWARD AGENT.
+ *
+ * The 策略 POLICY ＝ design template（主智能体的「权重」）lives in the user's
+ * repo; this agent's accepted edit is written back as the NEXT policy version
+ * via {@link import('./policy/policy-store.js').advancePolicyVersion}. There is
+ * NO candidate dir, NO fitness sidecar, and NO verdict.json on the accept path
+ * (those belonged to the GA loop, removed in a later changeset). The episode
+ * stage advances to 'evolved' on accept, 'evolution-refused' on refusal.
+ *
+ * Gates, all must pass before the edit is written back:
+ *   IN the bounded repair loop (a content-driven failure is REPAIRABLE — it is
+ *   re-prompted, bounded by maxRepairAttempts, rather than thrown past the loop):
+ *     - static        — frozen/gate-defining-file freeze + target-file scope
+ *                        ({@link validateCandidateEdits}) and the tool-evolution
+ *                        static guard ({@link evaluateToolEvolutionCandidate},
+ *                        the engine `runStaticCandidateGate` runs — adapted to a
+ *                        package-free in-memory call since loop v2 has no
+ *                        candidate dir);
+ *     - 范围⊆诊断     — every changed (file, section) is covered by a diagnosis
+ *                        gap ({@link checkScopeWithinDiagnosis});
+ *     - countChangedLines ≤ editBudget (L), and a present/valid prediction.
+ *   AFTER the loop (NOT repairable — the edit cannot influence it, so a re-prompt
+ *   would be a category error):
+ *     - observed-GREEN — the MAIN arm's objective.json must carry a real,
+ *                        trajectory-VERIFIED green signal ({@link isEvidenceComplete}).
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { type CanonicalTarget } from './canonical-targets.js';
+import { type TargetProtection } from './success-channel.js';
+import { type RejectBufferEntry } from './policy/reject-buffer.js';
+import { type PolicyPrediction, type PolicyLedgerEntry } from './policy/policy-store.js';
+import { type DiagnosisGap } from './scope-gate.js';
+import type { WeaknessClass, GapSeverity } from './reward-agent.js';
+/** Default edit budget L: at most this many changed lines (added + removed). */
+export declare const DEFAULT_EVOLVING_AGENT_EDIT_BUDGET = 40;
+/**
+ * Floor for the orchestrator's failure-driven 步长 step-size schedule: after a
+ * rolled-back edit the next episode's budget is halved toward this floor (never
+ * below it), so a struggling lineage takes smaller, more legible steps instead
+ * of another full-size swing — the backtracking-line-search / trust-region move
+ * (shrink the step after a step that lost ground; SkillOpt's decaying edit
+ * budget). The flat default above stays the ceiling for a healthy lineage. The
+ * schedule itself lives in the orchestrator (`scheduledEditBudget`); the
+ * 演进智能体 EVOLVING AGENT just receives the resolved budget as `editBudget`.
+ */
+export declare const MIN_EVOLVING_AGENT_EDIT_BUDGET = 8;
+/**
+ * The slice of the 奖励智能体 REWARD AGENT's `diagnosis.json` the EVOLVING
+ * AGENT reads. Kept STRUCTURAL (not a hard import of a Diagnosis type) — the
+ * reward agent is a sibling changeset; mirroring the {@link EvidenceReport}
+ * idiom in `promote.ts`, this stays a defensive shape so a test can drive it
+ * with a hand-built object and additive future fields pass through.
+ */
+export interface EvolvingAgentDiagnosis {
+    /** 弃权 abstain: the reward agent found no nameable gap. Refuse-to-spawn. */
+    abstained?: boolean;
+    /** Named gaps (with section anchors) the edit's scope must be a subset of. */
+    gaps?: AnnotatedDiagnosisGap[];
+    /** Observed errors the edit should address (rendered into the prompt). */
+    errors?: string[];
+    /** 文本梯度 textual gradient — the natural-language improvement direction. */
+    textualGradient?: string;
+    /** advantage ＝ reward(主臂) − reward(基线臂), when measured. */
+    advantage?: number | null;
+}
+/**
+ * A diagnosis gap as the EVOLVING AGENT carries it: the scope-gate's structural
+ * `{file, section}` augmented with the 奖励智能体 REWARD AGENT's OPTIONAL
+ * `weaknessClass`/`severity` annotations (⑥). The scope gate only reads
+ * file/section, so these extra fields pass through harmlessly; the prompt
+ * renderer surfaces them when present to AIM the bounded edit. Old diagnoses
+ * carry neither field and behave exactly as before.
+ */
+export interface AnnotatedDiagnosisGap extends DiagnosisGap {
+    weaknessClass?: WeaknessClass;
+    severity?: GapSeverity;
+}
+export interface AssembleEvolvingAgentPromptInput {
+    /** Resolved canonical target whose `files[]` bound the editable surface. */
+    target: CanonicalTarget;
+    /** Current on-disk contents of each editable lineage file. */
+    currentFiles: {
+        relPath: string;
+        content: string;
+    }[];
+    /** The reward agent's diagnosis (already read from diagnosis.json). */
+    diagnosis: EvolvingAgentDiagnosis;
+    /** Edit budget L (changed lines, added + removed). */
+    editBudget: number;
+    /** Most-recent 否决缓冲 reject-buffer entries for this target (newest last). */
+    rejectBuffer?: RejectBufferEntry[];
+    /** Pre-rendered DO-NOT-PRUNE block (成功保护). Omitted when empty. */
+    doNotPrune?: string;
+    /**
+     * One-line 预测校准 prediction-calibration note: the proposer's recent
+     * checkable predictions' hit/miss record, settled by later measurements.
+     * Read-only context (it never scores); omitted when there is no settled
+     * prediction history, so prompts on early episodes stay byte-identical.
+     */
+    calibrationNote?: string;
+}
+/**
+ * Assemble the EVOLVING AGENT prompt. Order is stable and sections are
+ * omitted-when-empty so prompts on runs with no reject-buffer / no protections
+ * stay byte-identical. The editable files are fenced as `<<FILE: relPath>>`.
+ */
+export declare function assembleEvolvingAgentPrompt(input: AssembleEvolvingAgentPromptInput): string;
+/** The agent declined: no concrete edit was nameable. Not an error. */
+export interface EvolvingAgentRefusal {
+    kind: 'refusal';
+    reason: string;
+}
+/** A concrete bounded edit with its checkable prediction. */
+export interface EvolvingAgentEdit {
+    kind: 'edit';
+    rationale: string;
+    prediction: PolicyPrediction;
+    edits: {
+        relPath: string;
+        content: string;
+    }[];
+}
+export type ParsedEvolvingAgentResponse = EvolvingAgentRefusal | EvolvingAgentEdit;
+/**
+ * Parse the model's single `json:patch` block. Accepts EITHER the refusal shape
+ * (`{edits: [], refusal: string}`) OR a concrete edit (`{rationale, prediction,
+ * edits[]}`). Throws {@link CanonicalProposerOutputInvalid} on a malformed
+ * block, the wrong block count, a missing/invalid prediction, or
+ * {@link CanonicalProposerNoOp} on empty edits WITHOUT a refusal reason.
+ *
+ * Edits are NOT yet scope-validated here (the caller runs the static gate over
+ * them); this only enforces the SHAPE of the contract.
+ */
+export declare function parseEvolvingAgentResponse(text: string): ParsedEvolvingAgentResponse;
+export interface RunEvolvingAgentOptions {
+    repoRoot: string;
+    episodeId: string;
+    targetId: string;
+    /** Edit budget L (changed lines, added + removed). Default 40. */
+    editBudget?: number;
+    /** Injected spawn seam for tests; defaults to node's spawn. */
+    spawn?: typeof nodeSpawn;
+    /** At most this many parse/budget/gate-3 repair re-prompts. Default 2. */
+    maxRepairAttempts?: number;
+    /** Override the agent binary; defaults to env or 'claude'. */
+    binary?: string;
+    /**
+     * 成功保护 protections feeding the DO-NOT-PRUNE block. Defaults to a FRESH
+     * `readProtections` from disk (the green-run-mined, load-bearing sections);
+     * tests pass it directly to keep the flow hermetic. An absent file reads as
+     * `[]`, so a run with no mined protections renders no block (byte-identical).
+     */
+    protections?: TargetProtection[];
+    /**
+     * Exemplar file paths for the DO-NOT-PRUNE block's `exemplars:` line. Defaults
+     * to a FRESH `listExemplarFiles` from disk; tests pass it directly.
+     */
+    exemplarPaths?: string[];
+    /**
+     * One-line 预测校准 prediction-calibration note surfaced to the proposer
+     * (read-only, advisory). Defaults to absent; the orchestrator computes it from
+     * the prediction-reconcile ledger via `summarizeCalibration`.
+     */
+    calibrationNote?: string;
+}
+/** Outcome: the agent was not spawned (code-side refuse). */
+export interface EvolvingAgentNotSpawned {
+    kind: 'not-spawned';
+    reason: string;
+}
+/** Outcome: the model refused; recorded as a 'refused' ledger entry. */
+export interface EvolvingAgentRefused {
+    kind: 'refused';
+    reason: string;
+    ledgerEntry: PolicyLedgerEntry;
+}
+/** Outcome: the edit passed all gates and became the next policy version. */
+export interface EvolvingAgentEvolved {
+    kind: 'evolved';
+    ledgerEntry: PolicyLedgerEntry;
+}
+export type RunEvolvingAgentResult = EvolvingAgentNotSpawned | EvolvingAgentRefused | EvolvingAgentEvolved;
+/**
+ * Run the 演进智能体 EVOLVING AGENT against an already-scored episode.
+ *
+ * Flow:
+ *   0. Code-side refuse-to-spawn: diagnosis.abstained or no gaps ⇒ not-spawned.
+ *   1. Assemble + spawn (fresh context) and parse with repair ×N; over-budget
+ *      and 范围⊆诊断 (gate-3) violations are repairable too (re-prompt with the
+ *      violation appended).
+ *   2. Model refusal ⇒ {kind:'refused'} + a 'refused' ledger entry.
+ *   3. GATES ×3 (static → observed-GREEN → 范围⊆诊断), each ANDed with the
+ *      ≤ L budget and a valid prediction.
+ *   4. All green ⇒ advancePolicyVersion writes the next version; episode stage
+ *      advances to 'evolved' (or 'evolution-refused' on refusal).
+ */
+export declare function runEvolvingAgent(opts: RunEvolvingAgentOptions): Promise<RunEvolvingAgentResult>;
+//# sourceMappingURL=evolving-agent.d.ts.map