dsh-continual-evolve 0.11.0 → 0.12.0

package/lib/approval.d.ts

@@ -1,73 +0,0 @@
-/**
- * Human approval gate for persistent-scope evolution edits. Project and
- * global edits require an explicit human "批准" before they are applied;
- * rollbacks (which restore prior recorded state) do not. The engine itself
- * stays a pure library — this is a policy at the boundary.
- */
-import type { Context } from "@deepseek-ai/cordis";
-import type { Agent } from "@deepseek-ai/dsh-agent";
-import { type RecordLanguagePreference } from "./record-language.js";
-export { type ScopeApprovalDecision } from "./types.js";
-import type { ScopeApprovalDecision } from "./types.js";
-/** Labels the approval dialog offers for each decision (parser contract). */
-export declare const APPROVE_LABELS: readonly ["批准", "Approve"];
-export declare const DECLINE_LABELS: readonly ["拒绝", "Decline"];
-export interface QuestionService {
-    ask(request: {
-        questions: {
-            id: string;
-            question: string;
-            options?: {
-                label: string;
-                description?: string;
-            }[];
-        }[];
-        agent?: Agent;
-        signal?: AbortSignal;
-    }): Promise<{
-        answers?: {
-            id: string;
-            selected?: string[];
-            custom?: string;
-        }[];
-    }>;
-}
-/**
- * Lazily resolve the userQuestions service from the context.
- * Returns undefined when the service is not loaded — callers decide
- * whether that is an error or a fallback.
- */
-export declare function questionServiceOf(ctx: Context): QuestionService | undefined;
-/**
- * Ask once for a persistent-scope edit. Only a unique, explicit approval
- * choice is accepted. A missing/ambiguous/unknown answer throws so callers
- * never interpret a lost or malformed dialog as a durable rejection.
- *
- * Copy follows the headline → details → impact shape in the resolved dialog
- * language; labels stay literal per language for parser compatibility.
- *
- * Language resolution runs the full record-language chain — explicit config,
- * then the durable client preference, then the session's own recent user text
- * — because an approval dialog raised from a tool call DOES have a session
- * behind it. Stopping at the durable tier gave a Chinese-speaking user English
- * dialogs whenever the stored preference was unset (2026-10-01).
- *
- * @param ctx Cordis context carrying the userQuestions service.
- * @param agent Agent prompting the question, if any.
- * @param signal Abort signal for the question, if any.
- * @param scope Target persistent scope.
- * @param what Edit summary; truncated to 300 chars with "…" when longer.
- * @param configured Plugin `recordLanguage` preference; `auto`/absent defers
- *                   to the durable preference and the session's user text.
- * @returns "approved" when the user picks the approval label, otherwise "declined".
- * @throws When the service is missing or the answer is not unique/explicit.
- */
-export declare function requestScopeApproval(ctx: Context, agent: Agent | undefined, signal: AbortSignal | undefined, scope: "project" | "global", what: string, configured?: RecordLanguagePreference): Promise<ScopeApprovalDecision>;
-/**
- * Ask the user to approve a global edit. Throws when the service is missing,
- * the user declines, or the question cannot be answered.
- *
- * @param configured Plugin `recordLanguage` preference (see {@link requestScopeApproval}).
- */
-export declare function requireGlobalApproval(ctx: Context, agent: Agent | undefined, signal: AbortSignal | undefined, what: string, configured?: RecordLanguagePreference): Promise<void>;
-//# sourceMappingURL=approval.d.ts.map

package/lib/approval.js

@@ -1,127 +0,0 @@
-import { approvalCopy } from "./copy.js";
-import { normalizeRecordLanguage, resolveRecordLanguage } from "./record-language.js";
-import { recentUserText } from "./inject.js";
-/** Labels the approval dialog offers for each decision (parser contract). */
-export const APPROVE_LABELS = ["批准", "Approve"];
-export const DECLINE_LABELS = ["拒绝", "Decline"];
-/**
- * Typed ("Other") answers accepted as an explicit decision once normalized.
- * Deliberately exact: a substring rule would read "不批准" as approval, and a
- * misread decision is far worse than asking the human to click the button.
- */
-const TYPED_APPROVALS = new Set(["批准", "approve"]);
-const TYPED_DECLINES = new Set(["拒绝", "decline"]);
-/** Trim case/quotes/trailing punctuation and a trailing 吧/了 from a typed answer. */
-function normalizeTypedAnswer(text) {
-    return text
-        .trim()
-        .toLowerCase()
-        .replace(/^[\s"'“”「」]+/, "")
-        .replace(/[\s"'“”「」。！!，,、]+$/, "")
-        .replace(/[吧了]$/, "");
-}
-/**
- * Read a free-text answer as a decision, or `undefined` when it matches no
- * label exactly. Never guesses.
- */
-function typedDecision(custom) {
-    if (typeof custom !== "string")
-        return undefined;
-    const normalized = normalizeTypedAnswer(custom);
-    if (TYPED_APPROVALS.has(normalized))
-        return "approved";
-    if (TYPED_DECLINES.has(normalized))
-        return "declined";
-    return undefined;
-}
-/**
- * Lazily resolve the userQuestions service from the context.
- * Returns undefined when the service is not loaded — callers decide
- * whether that is an error or a fallback.
- */
-export function questionServiceOf(ctx) {
-    return ctx.userQuestions;
-}
-/**
- * Ask once for a persistent-scope edit. Only a unique, explicit approval
- * choice is accepted. A missing/ambiguous/unknown answer throws so callers
- * never interpret a lost or malformed dialog as a durable rejection.
- *
- * Copy follows the headline → details → impact shape in the resolved dialog
- * language; labels stay literal per language for parser compatibility.
- *
- * Language resolution runs the full record-language chain — explicit config,
- * then the durable client preference, then the session's own recent user text
- * — because an approval dialog raised from a tool call DOES have a session
- * behind it. Stopping at the durable tier gave a Chinese-speaking user English
- * dialogs whenever the stored preference was unset (2026-10-01).
- *
- * @param ctx Cordis context carrying the userQuestions service.
- * @param agent Agent prompting the question, if any.
- * @param signal Abort signal for the question, if any.
- * @param scope Target persistent scope.
- * @param what Edit summary; truncated to 300 chars with "…" when longer.
- * @param configured Plugin `recordLanguage` preference; `auto`/absent defers
- *                   to the durable preference and the session's user text.
- * @returns "approved" when the user picks the approval label, otherwise "declined".
- * @throws When the service is missing or the answer is not unique/explicit.
- */
-export async function requestScopeApproval(ctx, agent, signal, scope, what, configured) {
-    const userQuestions = questionServiceOf(ctx);
-    if (!userQuestions) {
-        throw new Error("global evolution edits require the userQuestions service (load @deepseek-ai/dsh-user-questions)");
-    }
-    const lang = normalizeRecordLanguage(configured) ??
-        resolveRecordLanguage({ ctx, trajectoryText: recentUserText(agent) });
-    const copy = approvalCopy(scope, what, lang);
-    const answer = await userQuestions.ask({
-        questions: [
-            {
-                id: "approve-global-evolve",
-                question: copy.question,
-                options: copy.options,
-            },
-        ],
-        ...(agent ? { agent } : {}),
-        ...(signal ? { signal } : {}),
-    });
-    const matching = answer.answers?.filter((entry) => entry.id === "approve-global-evolve") ?? [];
-    if (matching.length !== 1 || !Array.isArray(matching[0]?.selected)) {
-        throw new Error("evolution approval returned no unique explicit decision");
-    }
-    const entry = matching[0];
-    const selected = [...new Set(entry.selected)];
-    if (selected.length === 0) {
-        // A typed "Other" answer counts only when it matches a dialog label
-        // exactly; anything fuzzier stays an error, so a lost or ambiguous
-        // reply is never recorded as a durable rejection.
-        const typed = typedDecision(entry.custom);
-        if (typed !== undefined) {
-            return typed;
-        }
-        throw new Error(`evolution approval needs one clicked option (${APPROVE_LABELS.join("/")} or ${DECLINE_LABELS.join("/")}) — a typed reply cannot serve as a decision`);
-    }
-    if (selected.length !== 1) {
-        throw new Error(`evolution approval returned an invalid decision: ${JSON.stringify(selected)}`);
-    }
-    const label = selected[0];
-    if (APPROVE_LABELS.includes(label)) {
-        return "approved";
-    }
-    if (DECLINE_LABELS.includes(label)) {
-        return "declined";
-    }
-    throw new Error(`evolution approval returned an unknown decision label: ${JSON.stringify(label)}`);
-}
-/**
- * Ask the user to approve a global edit. Throws when the service is missing,
- * the user declines, or the question cannot be answered.
- *
- * @param configured Plugin `recordLanguage` preference (see {@link requestScopeApproval}).
- */
-export async function requireGlobalApproval(ctx, agent, signal, what, configured) {
-    if ((await requestScopeApproval(ctx, agent, signal, "global", what, configured)) !== "approved") {
-        throw new Error("global evolution edit rejected by the user");
-    }
-}
-//# sourceMappingURL=approval.js.map

package/lib/audit-log.d.ts

@@ -1,19 +0,0 @@
-export interface ReviewAuditRow {
-    sessionId: string;
-    reason: string;
-    turnsSinceLastReview: number;
-    outcome: string;
-    rationale?: string;
-    [key: string]: unknown;
-}
-/** Resolve the shared audit trail path under `<baseDir>/evolve/`. */
-export declare function reviewsAuditPath(baseDir: string): string;
-/** Append one audit row and bound the trail at write time. Never throws. */
-export declare function appendReviewRecord(baseDir: string, entry: ReviewAuditRow, retain: number | undefined, onError?: (cause: unknown) => void): void;
-/**
- * Boot-time diagnostic: the armed marker proves the listener was registered
- * even when its runtime default is off, distinguishing "not registered"
- * from "off". Never throws.
- */
-export declare function writeArmedMarker(baseDir: string, rationale: string, onError?: (cause: unknown) => void): void;
-//# sourceMappingURL=audit-log.d.ts.map

package/lib/audit-log.js

@@ -1,52 +0,0 @@
-/**
- * The shared `reviews.jsonl` audit trail: the only writer for extraction
- * decisions, mechanical skips, and the boot armed marker. Writes are
- * contained — a broken ledger must never break the extraction path that
- * already made its decision.
- */
-import { appendFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { DEFAULT_REVIEWS_RETAIN, pruneJsonlFile } from "./store.js";
-/** Resolve the shared audit trail path under `<baseDir>/evolve/`. */
-export function reviewsAuditPath(baseDir) {
-    return join(baseDir, "evolve", "reviews.jsonl");
-}
-/** Append one audit row and bound the trail at write time. Never throws. */
-export function appendReviewRecord(baseDir, entry, retain, onError) {
-    try {
-        mkdirSync(join(baseDir, "evolve"), { recursive: true });
-        appendFileSync(reviewsAuditPath(baseDir), `${JSON.stringify({ ...entry, timestamp: new Date().toISOString() })}\n`, "utf8");
-    }
-    catch (cause) {
-        onError?.(cause);
-        return;
-    }
-    try {
-        pruneJsonlFile(reviewsAuditPath(baseDir), retain ?? DEFAULT_REVIEWS_RETAIN);
-    }
-    catch {
-        // ignored — the next record retries
-    }
-}
-/**
- * Boot-time diagnostic: the armed marker proves the listener was registered
- * even when its runtime default is off, distinguishing "not registered"
- * from "off". Never throws.
- */
-export function writeArmedMarker(baseDir, rationale, onError) {
-    try {
-        mkdirSync(join(baseDir, "evolve"), { recursive: true });
-        appendFileSync(reviewsAuditPath(baseDir), `${JSON.stringify({
-            timestamp: new Date().toISOString(),
-            sessionId: "boot",
-            reason: "boot",
-            turnsSinceLastReview: 0,
-            outcome: "armed",
-            rationale,
-        })}\n`, "utf8");
-    }
-    catch (cause) {
-        onError?.(cause);
-    }
-}
-//# sourceMappingURL=audit-log.js.map

package/lib/auto.d.ts

@@ -1,236 +0,0 @@
-import type { ScopeApprovalDecision } from "./approval.js";
-import type { Context } from "@deepseek-ai/cordis";
-import type { Agent } from "@deepseek-ai/dsh-agent";
-import type { HarnessState, RefinementEdit, RefinementProposal } from "./types.js";
-import type { EvolutionEngine } from "./service.js";
-import { type AutoRefineReason } from "./review.js";
-import { type ReviewScheduler } from "./review-scheduler.js";
-import { type TurnSnapshot } from "./turn-snapshot.js";
-import type { PromotionPolicy } from "./promotion.js";
-import type { PlannerPrefixCacheMode } from "./prefix-cache.js";
-import { type RecordLanguagePreference } from "./record-language.js";
-import type { RecordLanguage } from "./record-language.js";
-export interface AutoReviewConfig {
-    /** Legacy fate cadence; successful turns are no longer gated by this value. */
-    intervalTurns: number;
-    /** Initial runtime state when no runtime.json exists. */
-    enabledByDefault?: boolean;
-    /** ZCode-style minimum lexical words in one direct user text part. */
-    memoryMinUserWords?: number;
-    /**
-     * Run only the dedicated memory extraction phase. The general review,
-     * planner, prompt/skill writes, and local-fate phases are never entered.
-     */
-    memoryOnly?: boolean;
-    maxInputChars: number;
-    budgetTokens: number;
-    /** Queue a visible follow-up notice after an approved, applied gate run. */
-    notifyOnAutoReview: boolean;
-    /**
-     * Local-fate dimension (#11 P2): the gate audits the session's local
-     * entries on its own cadence and proposes promote/archive (consulted
-     * first — never written silently). Off disables the whole dimension.
-     */
-    localFate: boolean;
-    /**
-     * Minimum turns between local-fate assessments on the successful-turn path
-     * (compaction is unconditional). Independent of snapshot review cadence so
-     * eligible turns do not pay an assessment every round.
-     */
-    fateIntervalTurns: number;
-    /**
-     * Gap C1: optional model override for the review gate (cheaper model).
-     * Format: "provider/model" or just "model" (same provider as the agent).
-     * When absent, the review gate uses the agent's own provider/model.
-     */
-    reviewModel?: string;
-    /** Dedicated memory-agent writes to project/global require the normal human approval boundary. */
-    requireGlobalApproval?: boolean;
-    /**
-     * Authoring language for this run's records. Absent/`auto` resolves per
-     * call through the record-language chain (durable client preference,
-     * then trajectory detection, then `en`); `zh`/`en` pin it.
-     */
-    recordLanguage?: RecordLanguagePreference;
-    /**
-     * Prefix-cache routing for the gate input (see reviewAutoRefine).
-     * Absent mode → auto-detect; absent budget → the default prefix budget.
-     */
-    prefixCacheMode?: PlannerPrefixCacheMode;
-    prefixMaxChars?: number;
-    /**
-     * Goal-blocked trigger (D3): after this many CONSECUTIVE gate runs that
-     * observe the session goal in phase "blocked", run one local-fate
-     * assessment (the same audit → classify → consult → apply pipeline as the
-     * gate's normal fate dimension) so the blocked encounter is distilled
-     * before the session moves on. 0 disables. The streak resets on any
-     * non-blocked run and after each triggered assessment; a declined
-     * proposal then follows the normal fate cooldown.
-     */
-    goalBlockedWrapupTurns: number;
-    /**
-     * Promotion policy (2026-08-22): mechanical promote guards applied by the
-     * local-fate dimension before anything reaches the global store.
-     */
-    promotionPolicy: PromotionPolicy;
-    /**
-     * P1 auto-case capture: a gate run whose planned edits all failed to get
-     * consent captures the attempt as a draft regression scaffold in the
-     * auto-regression container benchmark (never in a user benchmark).
-     */
-    autoCase: boolean;
-    /** Resolved rubric key for the capture's encrypted scaffold rubric. */
-    rubricKey?: Buffer;
-    /**
-     * Storage hygiene (#20): tail lines kept in the shared reviews.jsonl
-     * audit trail. Absent → the store default (readers need a recent
-     * window, not the full past).
-     */
-    reviewsRetain?: number;
-    /**
-     * Session-close bounded drain (P1): how long a disposed session's
-     * in-flight extraction may settle before its owner signal aborts.
-     * Absent → 15s; 0 restores the legacy immediate abort.
-     */
-    sessionCloseDrainMs?: number;
-}
-export interface GateState {
-    turns: number;
-    /** Latest successful turn boundary seen by the listener. */
-    completedTurn: number;
-    /** Latest turn whose snapshot acquisition was reserved. */
-    lastSnapshotTurn: number;
-    /** Latest successful/no-op memory boundary, independent of later review/fate completion. */
-    memoryCheckpoint?: string;
-    /** Per-boundary/scope approval decisions retained until the memory phase settles. */
-    memoryDecisions: Record<string, ScopeApprovalDecision>;
-    lastReviewAt: number;
-    running: boolean;
-    /**
-     * Per-candidate turn at which the user last rejected a skill proposal;
-     * consulted skill proposals are not offered again within the cooldown
-     * window (skills are governed resources — no nagging).
-     */
-    skillRejects: Map<string, number>;
-    /** Turn at which the local-fate dimension last assessed (cadence). */
-    lastFateAt: number;
-    /**
-     * Per-candidate-set turn at which the user last declined a local-fate
-     * proposal; declined sets are not offered again within the cooldown
-     * window (the consultSkillEdits pattern — no nagging).
-     */
-    fateRejects: Map<string, number>;
-    /**
-     * Consecutive gate runs that observed the goal phase "blocked" (D3).
-     * Reset to 0 by any non-blocked run and after a triggered assessment —
-     * see runGoalBlockedFate.
-     */
-    goalBlockStreak: number;
-}
-/** Turns a rejected skill candidate stays silent before being offered again. */
-export declare const SKILL_CONSULT_COOLDOWN_TURNS = 10;
-/** Default session-close drain budget: an in-flight extraction gets 15s to settle. */
-export declare const SESSION_CLOSE_DRAIN_MS_DEFAULT = 15000;
-/**
- * Resolve the session-close drain budget: absent/invalid → default, 0 →
- * immediate abort (legacy). Negative or non-finite values fail back to the
- * default rather than silently disabling the drain.
- */
-export declare function resolveSessionCloseDrainMs(raw?: number): number;
-/**
- * Bounded session-close drain for one scheduler: wait for in-flight work up
- * to drainMs, then abort the owner signal and drop pending captures. Never
- * rejects — disposal must not hang the host on a stuck model call, and the
- * abort below is idempotent when the drain already settled.
- */
-export declare function drainSchedulerOnDispose(scheduler: Pick<ReviewScheduler<TurnSnapshot>, "drain" | "shutdown">, drainMs: number): Promise<void>;
-export interface ReviewRecord {
-    timestamp: string;
-    sessionId: string;
-    reason: AutoRefineReason;
-    turnsSinceLastReview: number;
-    outcome: "approved" | "declined" | "failed" | "assessed" | "deferred" | "skipped" | "armed" | "applied" | "noop";
-    rationale?: string;
-    refinementId?: string;
-    /** P1 extraction stats (§6.7): wall time of the memory phase. */
-    durationMs?: number;
-    /** Extractor loop turns / manifest searches behind this row. */
-    memoryTurns?: number;
-    memorySearches?: number;
-    /** Applied edit count carried by an applied row. */
-    appliedEdits?: number;
-}
-export declare function registerAutoReview(ctx: Context, engine: EvolutionEngine, config: AutoReviewConfig): void;
-/**
- * Gap C1: parse a "provider/model" or "model" string into its components.
- * Returns undefined when the input is empty (no override). A bare model name
- * falls back to the agent's provider, then "deepseek".
- * Exported for unit testing (the advanceGateState precedent); production
- * resolves it inside runReviewPhase.
- */
-export declare function parseReviewModel(reviewModel: string | undefined, fallbackProvider: string | undefined): {
-    provider: string;
-    model: string;
-} | undefined;
-/**
- * The state view the gate and planner judge: the session's local entries
- * merged with the project and global stores, each entry carrying its real
- * scope. Without the global half the gate cannot see that a topic is already
- * covered cross-session and happily re-sediments a local duplicate of it.
- *
- * The merged view is read-only context — applying still targets the raw
- * local state (baseline checks compare local entries only).
- */
-export declare function loadGateHarnessView(engine: EvolutionEngine, sessionId: string, opts?: {
-    projectKey?: string;
-}): HarnessState;
-/**
- * D3 (goal blocked → wrap-up coupling, reverse direction): count consecutive
- * gate runs whose goal is in phase "blocked"; when the streak reaches
- * `goalBlockedWrapupTurns`, run ONE local-fate assessment (same pipeline as
- * the normal fate dimension — audit, classify, consult, apply deterministically).
- * The streak resets on any non-blocked run and after a triggered assessment;
- * a declined proposal is then protected by the normal fate cooldown, so a
- * blocked session can never be nagged into another dialog.
- *
- * Exported for unit testing (the advanceGateState precedent); production runs
- * it from runGate.
- */
-export declare function runGoalBlockedFate(ctx: Context, engine: EvolutionEngine, agent: Agent, config: AutoReviewConfig, state: GateState, _reason: AutoRefineReason, record: (entry: Omit<ReviewRecord, "timestamp">) => void): Promise<void>;
-/**
- * Dedicated ZCode-style memory phase. It shares the scheduler snapshot and
- * snapshot with the general review, but owns its request loop, manifest and
- * memory-only tool policy. Its phase-specific checkpoint advances after a
- * successful/no-op memory outcome; later review/fate failures do not replay
- * old memory decisions, while memory failures leave the boundary retryable.
- */
-export declare function runMemoryExtractionPhase(ctx: Context, engine: EvolutionEngine, agent: Agent, config: AutoReviewConfig, state: GateState, snapshot: TurnSnapshot, record: (entry: Omit<ReviewRecord, "timestamp">) => void, signal?: AbortSignal): Promise<void>;
-/** True when the general planner returned only edits owned by the memory phase. */
-export declare function isDedicatedMemoryOnlyProposal(proposal: RefinementProposal): boolean;
-/**
- * Remove memory edits from the general auto-review planner. The dedicated
- * memory phase owns this responsibility and has already run against the same
- * snapshot; accepting a second memory proposal would reintroduce duplicates.
- */
-export declare function stripDedicatedMemoryEdits(proposal: RefinementProposal): RefinementProposal;
-/**
- * Split a proposal into skill edits and everything else. Skill edits are the
- * governed part: they need explicit user consent before the gate applies
- * them, while the remaining edits flow through the normal auto path.
- */
-export declare function splitSkillEdits(proposal: RefinementProposal): {
-    skillEdits: RefinementEdit[];
-    otherEdits: RefinementEdit[];
-};
-/**
- * Ask the user whether to solidify proposed skill edits (guidance or
- * executable) into the harness. Returns true when every skill edit is
- * consented. Never writes a skill silently:
- * - no question service available → false (conservative);
- * - the same candidate was rejected within the cooldown window → false
- *   without asking again (no nagging);
- * - the user declines → false and the rejection is recorded for cooldown;
- * - the question call fails/aborts → false (conservative).
- */
-export declare function consultSkillEdits(ctx: Context, agent: Agent, skillEdits: RefinementEdit[], gate: GateState, language?: RecordLanguage): Promise<boolean>;
-//# sourceMappingURL=auto.d.ts.map