@aitne/daemon 0.1.10 → 0.1.11

package/dist/core/feedback/tuning-recommender.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Self-Tuning Review Cycle — Recommend stage (SELF_TUNING_REVIEW_CYCLE_DESIGN.md
+ * §3.2, Phase 2).
+ *
+ * The daemon-side, deterministic Recommend step ($0 — LLM tokens buy judgment
+ * only, P1). On the weekly-review dispatch it consumes the same
+ * {@link SelfPerformanceData} the Measure stage (§3.1) already gathered —
+ * current + baseline window = the 14-day evidence span the v1 rules read —
+ * and emits at most {@link MAX_RECOMMENDATIONS_PER_CYCLE} bounded
+ * `TuningRecommendation`s, rendered as one `<tuning_recommendations>` block
+ * for the weekly session's Phase 3c verdict step (§3.3).
+ *
+ * Guards live in code, not prompt (§3.2): per-rule ladders with hard
+ * floors/caps, hysteresis (no re-proposal of a key changed < 14 days ago;
+ * 28 days after a revert), minimum sample sizes, and the max-3 ranking by
+ * estimated $ impact. Numeric *enforcement* stays where it already lives —
+ * `runtimeSettingsSchema` + `env-writer.ts:NUMERIC_RANGE` behind the
+ * `applyConfigUpdates` chokepoint (P4); the `bounds` field on a
+ * recommendation documents the rule's own ladder, it is not a third copy of
+ * the schema bounds.
+ *
+ * The shadow period (§7): recommendations are generated, persisted under
+ * {@link TUNING_PENDING_CYCLE_STATE_KEY}, and verdicted via
+ * `POST /api/tuning/verdicts`. While `selfTuningEnabled` is `false` (the
+ * shipped default) nothing is actuated; once flipped, the Phase 3 actuator
+ * (`tuning-actuator.ts`) applies `apply` verdicts through the config
+ * chokepoint. Verdict ids are single-use: each weekly cycle overwrites the
+ * pending blob, expiring the prior cycle's ids (§3.4).
+ */
+import type Database from "better-sqlite3";
+import type { LessonStoreUtilization, SelfPerformanceData, SelfTuningLedgerEntry } from "./self-performance-prep.js";
+/**
+ * §3.4 — runtime_state key for the current cycle's pending recommendations
+ * + verdicts. Deliberately uses a `.` separator, NOT the
+ * `SELF_TUNING_LEDGER_PREFIX` (`self_tuning:`) namespace — the Measure
+ * stage's `gatherLedger` does a `LIKE 'self_tuning:%'` scan and must never
+ * pick the pending blob up as a phantom ledger entry.
+ */
+export declare const TUNING_PENDING_CYCLE_STATE_KEY = "self_tuning.pending_cycle";
+/** §3.2 — max recommendations per weekly cycle, ranked by estimated $ impact. */
+export declare const MAX_RECOMMENDATIONS_PER_CYCLE = 3;
+/** §3.2 — no re-proposal of a key changed less than this many days ago. */
+export declare const TUNING_HYSTERESIS_DAYS = 14;
+/** §3.4 — extended cool-down after an auto-revert, so apply→revert can't flap. */
+export declare const TUNING_REVERT_COOLDOWN_DAYS = 28;
+export declare const R1_KNOB = "activityScanPrePassFreshnessMinutes";
+export declare const R1_EMPTY_RATE_STEP_UP = 0.7;
+export declare const R1_EMPTY_RATE_STEP_DOWN = 0.2;
+export declare const R1_MIN_RUNS = 10;
+/**
+ * §3.2 — the freshness ladder. Step up = smallest notch above the current
+ * value (cap 480); step down = largest notch below it (floor 120). Today's
+ * schema caps the knob at 240 — the 360/480 notches become appliable when
+ * Phase 3 widens `.max()` to 480 (§6); in the Phase 2 shadow period they are
+ * recorded-and-judged only, so proposing them is safe.
+ */
+export declare const R1_FRESHNESS_NOTCHES: readonly [120, 240, 360, 480];
+export declare const R2_IGNORED_RATE = 0.6;
+export declare const R2_MIN_SENT = 5;
+/**
+ * The loop's own DM channel — apply notices ("Reply `!revert tuning` to
+ * undo") and auto-revert notices land in `notification_log` under this
+ * type. R2 must never propose demoting it: the per-change DM is the D1/D6
+ * safety invariant (daemon-sent, mandatory, deliberately not a tunable
+ * notification surface), so an owner who lets those DMs sit unreacted
+ * would otherwise have the loop spend one of its max-3 weekly slots
+ * recommending that its own safety channel go quiet.
+ */
+export declare const SELF_TUNING_NOTIFICATION_TYPE = "self_tuning";
+export declare const R3_KNOB = "activityScanLowSignalPendingCeiling";
+export declare const R3_LOW_NOVELTY_SHARE = 0.5;
+/** Minimum stage-3 escalations over 14d before the share is meaningful. */
+export declare const R3_MIN_STAGE3 = 4;
+/**
+ * Conservative ladder for the silent-skip band. The schema allows up to 20;
+ * the rule never proposes past 8 — a wider band is an operator decision.
+ */
+export declare const R3_CEILING_NOTCHES: readonly [2, 4, 8];
+export declare const R5_KNOB = "feedbackLessonMaxBytesGlobal";
+export declare const R5_UTILIZATION_THRESHOLD = 0.9;
+export declare const R5_MEDIAN_EV_CEILING = 1;
+/** Floor for the R5 step-down; matches the per-agent default cap. */
+export declare const R5_MIN_BYTES = 4096;
+/** R5 proposes a 25% reduction, rounded down to a 1 KiB multiple. */
+export declare const R5_STEP_FACTOR = 0.75;
+export type TuningRuleId = "R1" | "R2" | "R3" | "R4" | "R5";
+/**
+ * What the Actuate stage would touch. `config` → `applyConfigUpdates`
+ * chokepoint (Phase 3); `lesson` → consumed as task-flow guidance via the
+ * existing lesson loop (R2 v1 — no per-type knob exists yet, §3.2);
+ * `schedule` → `recurring_schedules.enabled` flag (R4, propose-only in v1).
+ */
+export type TuningActuator = "config" | "lesson" | "schedule";
+export interface TuningRecommendation {
+    /** Daemon-generated, single-use id: `<cycleId>:<rule>:<key>`. */
+    id: string;
+    rule: TuningRuleId;
+    actuator: TuningActuator;
+    /** Config knob name, `notification:<type>`, or `recurring_schedules:<id>`. */
+    key: string;
+    currentValue: number | string;
+    proposedValue: number | string;
+    /**
+     * The rule's own ladder floor/cap — informational for the judge. Numeric
+     * enforcement stays in `runtimeSettingsSchema` / `env-writer.ts` (P4).
+     */
+    bounds: {
+        min: number;
+        max: number;
+    } | null;
+    /** One-line, number-bearing evidence string (≤ {@link MAX_EVIDENCE_CHARS}). */
+    evidence: string;
+    /** Deterministic heuristic, used only for the max-3 ranking. */
+    estWeeklySavingUsd: number;
+}
+export type TuningVerdict = "apply" | "reject" | "defer";
+export interface TuningVerdictRecord {
+    verdict: TuningVerdict;
+    reason: string;
+    recordedAt: string;
+}
+export interface PendingTuningCycle {
+    /** ISO date of the generating weekly run — doubles as the id namespace. */
+    cycleId: string;
+    generatedAt: string;
+    recommendations: TuningRecommendation[];
+    /** Verdicts recorded so far, keyed by recommendation id. */
+    verdicts: Record<string, TuningVerdictRecord>;
+}
+/** R4 input row — gathered by {@link gatherFailingRecurringSchedules}. */
+export interface FailingRecurringSchedule {
+    id: number;
+    taskType: string;
+    description: string | null;
+    /** Length of the trailing all-failed streak (= the qualifying window, 3). */
+    lastFailures: number;
+}
+export interface TuningKnobValues {
+    activityScanPrePassFreshnessMinutes: number;
+    activityScanLowSignalPendingCeiling: number;
+    feedbackLessonMaxBytesGlobal: number;
+}
+export interface TuningRecommenderInput {
+    /** Measure-stage output; current + baseline = the 14-day evidence span. */
+    data: SelfPerformanceData;
+    knobs: TuningKnobValues;
+    /** §3.5 store-side byte pressure; only the global `agent` scope feeds R5. */
+    lessonStores?: ReadonlyArray<LessonStoreUtilization>;
+    failingSchedules?: ReadonlyArray<FailingRecurringSchedule>;
+    now: Date;
+}
+export declare const MAX_EVIDENCE_CHARS = 200;
+/**
+ * §3.2 hysteresis guard. A key with a ledger entry applied within
+ * {@link TUNING_HYSTERESIS_DAYS} (or reverted within
+ * {@link TUNING_REVERT_COOLDOWN_DAYS}) is off the table this cycle. A ledger
+ * entry whose timestamps fail to parse blocks conservatively.
+ */
+export declare function isKeyInCooldown(ledger: ReadonlyArray<SelfTuningLedgerEntry>, key: string, now: Date): boolean;
+/** Smallest notch strictly above `current`, or null at/above the cap. */
+export declare function stepUpNotch(notches: ReadonlyArray<number>, current: number): number | null;
+/** Largest notch strictly below `current`, or null at/below the floor. */
+export declare function stepDownNotch(notches: ReadonlyArray<number>, current: number): number | null;
+/**
+ * The rule table (§3.2). Pure: every input is passed in; the only
+ * non-determinism allowed is the caller's `now`. Applies the code-side
+ * guards — hysteresis against the ledger, per-rule minimum samples, and the
+ * max-3 ranking by estimated weekly $ impact (ties: rule order, then key).
+ */
+export declare function buildTuningRecommendations(input: TuningRecommenderInput): TuningRecommendation[];
+/** Cycle id = the generating run's UTC date (`YYYY-MM-DD`). */
+export declare function cycleIdForDate(now: Date): string;
+/**
+ * Wrap a recommendation set as the persisted pending-cycle blob. Written to
+ * `runtime_state` even when empty — overwriting is what expires the previous
+ * cycle's single-use ids (§3.4).
+ *
+ * Same-day regeneration (a weekly-review re-run via `!run` / crash retry)
+ * produces the SAME cycle id and — for any rule still firing on the same
+ * key — the same recommendation ids. Those ids are not expired (§3.4 expiry
+ * is the *next* weekly cycle), so verdicts already recorded against them
+ * carry forward: without this, the regenerated blob's empty `verdicts` map
+ * would silently reopen judged ids, and the re-run session's re-POST would
+ * record fresh verdicts — double-posting the rejection `self_critique`
+ * signals the route's per-id idempotency exists to prevent. Verdicts for
+ * ids the regenerated set no longer contains are dropped (the evidence
+ * that produced them is gone); a different-day cycle starts clean.
+ */
+export declare function createPendingTuningCycle(recommendations: ReadonlyArray<TuningRecommendation>, generatedAtIso: string, previousCycle?: PendingTuningCycle | null): PendingTuningCycle;
+/** Trailing settled-run window R4 inspects per recurring row. */
+export declare const R4_FAILURE_STREAK = 3;
+/**
+ * R4 input — enabled `recurring_schedules` rows whose last
+ * {@link R4_FAILURE_STREAK} *settled* materialized runs (`completed` /
+ * `failed` / `skipped`; pending and running rows are not evidence) all
+ * failed. SQL over `agent_schedule` grouped by `recurring_schedule_id` —
+ * no new columns (§3.2). A `skipped` run breaks the streak deliberately:
+ * the rule targets "fires and fails every time", not gate-skipped rows.
+ */
+export declare function gatherFailingRecurringSchedules(db: Database.Database): FailingRecurringSchedule[];
+export interface RenderTuningRecommendationsOptions {
+    /**
+     * Phase 3 — `shadow` (default) means verdicts are recorded but never
+     * actuated; `live` means the daemon applies `apply` verdicts through the
+     * config chokepoint (`selfTuningEnabled=true`). The attribute is what the
+     * weekly task-flow's Phase 3c branches on, so the prompt never has to
+     * guess the flag state.
+     */
+    mode?: "shadow" | "live";
+}
+/**
+ * Render the `<tuning_recommendations>` block for the weekly session's
+ * Phase 3c verdict step. Returns `null` when the cycle holds no
+ * recommendations — the design requires zero bytes in that case (§3.2).
+ * Output is bounded by construction: ≤ {@link MAX_RECOMMENDATIONS_PER_CYCLE}
+ * rows with ≤ {@link MAX_EVIDENCE_CHARS}-char evidence strings.
+ *
+ * Carried-forward verdicts (a same-day re-run regenerates the same ids, and
+ * `createPendingTuningCycle` preserves verdicts already recorded against
+ * them) surface as a `verdict` attribute on the row, so the re-run session
+ * skips already-judged rows instead of re-POSTing them — the route's per-id
+ * idempotency would absorb the duplicates, but not the wasted judgment
+ * tokens.
+ */
+export declare function renderTuningRecommendationsBlock(cycle: PendingTuningCycle, opts?: RenderTuningRecommendationsOptions): string | null;
+export interface VerdictEntry {
+    id: string;
+    verdict: TuningVerdict;
+    reason: string;
+}
+export type VerdictStatus = "recorded" | "duplicate" | "conflict";
+export interface VerdictApplicationResult {
+    cycle: PendingTuningCycle;
+    results: Array<{
+        id: string;
+        status: VerdictStatus;
+    }>;
+}
+/**
+ * Record verdicts onto a pending cycle, idempotently per id (§3.4): a
+ * retried POST with the same verdict is a `duplicate` no-op; a different
+ * verdict for an already-verdicted id is a `conflict` — first verdict wins
+ * (re-judging a recommendation mid-cycle is not a supported operation).
+ * Callers must have validated every id against `cycle.recommendations`
+ * first; an unknown id here is a programming error and throws.
+ */
+export declare function applyVerdictsToCycle(cycle: PendingTuningCycle, entries: ReadonlyArray<VerdictEntry>, nowIso: string): VerdictApplicationResult;