@jmtrin/kevin-core 1.3.0

package/dist/ContextInjector.d.ts

@@ -0,0 +1,222 @@
+import type { InjectionLedger } from "./InjectionLedger.js";
+import type { MemoryService } from "./MemoryService.js";
+import { type GateReason } from "./QualityGate.js";
+import { type Metrics } from "./metrics.js";
+export declare const QUALITY_GATE_SETTING = "quality_gate_enabled";
+export declare const SNIPPET_INJECTION_SETTING = "lesson_snippet_injection";
+/**
+ * v0.6.0 (K6-023 / plan §5.8) — the effective pre-prompt budget shared by
+ * `ContextInjector.prePromptCap()` and `kevin_audit`'s channels block
+ * (budget_tokens). Single source of truth for the K6-021 clamp:
+ * default 400 when the raw value is missing/non-numeric, clamped to
+ * [0, 4000]; 0 means "push off".
+ */
+export declare function effectivePrePromptCap(raw: string | undefined): number;
+export interface ChatMessage {
+    role: string;
+    content: string;
+}
+export interface SystemTransformInput {
+    sessionID?: string;
+    messages: ChatMessage[];
+}
+export interface SystemTransformOutput {
+    system: string[];
+}
+export interface CompactingInput {
+    sessionID: string;
+    messages: ChatMessage[];
+}
+export interface CompactingOutput {
+    context: string[];
+}
+export interface InjectionPlanItem {
+    id: string;
+    type: string;
+    decision: "admitted" | "blocked";
+    /** Gate reason when blocked; null for admitted items. */
+    reason?: GateReason;
+    /** Estimated tokens this memory would contribute to the block. */
+    tokens: number;
+}
+export interface InjectionPlan {
+    query: string;
+    tag: "context" | "memory";
+    cap: number;
+    would_inject: boolean;
+    /** Estimated tokens of the block that WOULD be produced (0 when
+     * nothing would be injected). */
+    total_tokens: number;
+    admitted: InjectionPlanItem[];
+    blocked: InjectionPlanItem[];
+}
+export declare class ContextInjector {
+    private memoryService;
+    private metrics;
+    private ledger;
+    private lastRecurrenceCount;
+    /** v0.4.0 (K4-016) — session that produced the last recurrence set. */
+    private lastRecurredSession;
+    /** v0.4.0 (K4-017) — per-session seen-set (plan §5.1 rule 3). */
+    private readonly seenBySession;
+    constructor(memoryService: MemoryService, metrics?: Metrics | null, ledger?: InjectionLedger | null);
+    /**
+     * v0.4.0 (K4-017) — reset the per-session seen-set when a session is
+     * created (plan §5.1 rule 3). Wired from the `session.created` event.
+     */
+    onSessionCreated(sessionId: string): void;
+    /**
+     * v0.3.0 (K3-020) — notify the injector that the negative feedback half
+     * fired N times in the last session.idle. The next system.transform or
+     * compacting hook will prepend a HITL suggestion block.
+     * v0.4.0 (K4-016) — the session id enables the concrete suggestion:
+     * the most-recurred fingerprint's pattern + its fix_args.
+     */
+    setRecurrences(count: number, sessionId?: string): void;
+    /**
+     * v0.4.0 (K4-016) — generate a CONCRETE HITL suggestion block when
+     * recurrences occurred (plan §5.5): names the most-recurred pattern,
+     * its exact recurrence count, observed fix_args and confidence. The
+     * AGENTS.md draft line derives from the lesson's `Suggestion:` text —
+     * never a canned string, and never the anonymous "the same error
+     * pattern" without naming the pattern and count.
+     *
+     * BUG-012 — emits AT MOST ONCE per session: calling it resets the
+     * pending recurrence signal, so whichever hook (system.transform or
+     * compacting) runs first in a session consumes the block. Documented
+     * behavior; wire index.ts to match.
+     */
+    generateSuggestion(): string;
+    /**
+     * v0.4.0 (K4-016) — the AGENTS.md draft line derives from the lesson's
+     * `Suggestion:` text (kept verbatim in the pattern's `Original:` block).
+     */
+    private agentsDraftLine;
+    /**
+     * v0.2.0 (K2-024): origin-aware ranking at injection time is delegated
+     * to `MemoryService.getRelevant()` (K2-023, D2-13). The injector does
+     * NOT re-rank on its own — it consumes the already-ranked slice and
+     * applies the conditional-budget guard for opt-out (`protect: false`)
+     * callers. Plan §B6.5: "apply the same multiplier as
+     * MemoryService.recall so reflector lessons outrank agent-saved notes
+     * at injection time" — satisfied transitively via the getRelevant call.
+     *
+     * v0.4.0 (K4-017): after retrieval, every memory is filtered through
+     * `QualityGate.canInject` (session seen-set + recurrence + strength),
+     * and each admitted memory is recorded in the `InjectionLedger`
+     * (plan §5.2 — one row per injected memory).
+     *
+     * v0.5.0 (K5-014 / plan §8.10) — the pipeline is decomposed into
+     * `fetchSlice` (ranked retrieval + budget overflow) + `evaluate`
+     * (pure gate verdicts) + this orchestrator, so the read-only `plan()`
+     * can mirror it without any side effect (D5-08).
+     */
+    private inject;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10) — the ranked-retrieval stage shared by
+     * `inject` and `plan`. With `dry = true` it is a strict read:
+     *
+     *  - the probe fetch never bumps (BUG-016), like the live path;
+     *  - the overflow retry ALSO fetches with `bump: false` (the live path
+     *    lets the retry fetch bump once — that is the only difference);
+     *  - the no-retry bump is skipped.
+     *
+     * This is what lets `plan()` predict the EXACT slice the live path
+     * would inject without mutating a single relevance score.
+     */
+    private fetchSlice;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10, D5-08) — PUBLIC read-only prediction of
+     * what `inject` WOULD do for a query: same retrieval, same gate, zero
+     * side effects. Never moves a counter, never writes the seen-set, never
+     * bumps relevance, never records ledger rows. `kevin_trace` (K5-015)
+     * surfaces this to the agent; tests freeze the clock + settings around
+     * it.
+     */
+    plan(query: string, options?: {
+        tag?: "context" | "memory";
+        cap?: number;
+        sessionId?: string;
+    }): InjectionPlan;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10) — PURE gate evaluation shared by `admit`
+     * (live path) and `plan` (read-only path): returns the verdict for every
+     * candidate plus the seen-set as it WOULD look afterwards. Never writes
+     * state — the caller decides whether to persist.
+     */
+    private evaluate;
+    /**
+     * v0.5.0 (K5-017 / plan §8.11, D5-11) — the effective pre-prompt cap,
+     * read at call time from `pre_prompt_budget_tokens` (seeded "900" by
+     * migration 006). Clamped to [100, 4000]; a non-numeric value falls
+     * back to 900. `kevin_trace` reports the value used via `plan().cap`.
+     *
+     * v0.6.0 (K6-021 / plan §5.8) — default becomes "400" and the lower
+     * clamp bound drops to **0**: the roadmap's kill criterion K1 prescribes
+     * cutting the push budget to zero when coverage is poor, and v0.5's
+     * [100, 4000] clamp made that response unimplementable. A non-numeric
+     * value falls back to 400. `onSystemTransform` treats 0 as off and
+     * returns before any retrieval (see K6-021 acceptance).
+     */
+    private prePromptCap;
+    /**
+     * v0.4.0 (K4-017) — QualityGate admission: filters the ranked slice to
+     * memories that may be injected this session, updating the session
+     * seen-set.
+     *
+     * v0.5.0 (K5-007 / plan §5.2, D5-04) — uses `canInjectVerdict` and
+     * increments the matching `injections_blocked_*` counter for every
+     * rejection, so gate policy becomes measurable. When `dryRun === true`
+     * the counters stay untouched (D5-08) — and so does the seen-set
+     * (a dry run is a strict read, K5-014).
+     *
+     * BUG-005 — strength/actionability now go through the REAL
+     * `QualityGate.evaluate` semantics (plan §5.1 rules 1-2), which this
+     * class had only re-derived from `metadata.dispatch`:
+     *   - dispatched code → strong + actionable (rescued errorType);
+     *   - generic fallback suggestion + no code → weak, NOT actionable
+     *     (the generic-suggestion ban is now enforced even for legacy
+     *     lessons without dispatch metadata, as long as the `Suggestion:`
+     *     text is available);
+     *   - specific suggestion without code → strong + actionable;
+     *   - no `Suggestion:` text at all (agent-saved note) → strong +
+     *     actionable — the agent explicitly asked to remember it;
+     *   - causal patterns (type='pattern') → always strong + actionable:
+     *     they are the FIXED form of a fingerprint (K4-025).
+     */
+    private admit;
+    /**
+     * BUG-005 — the single source of truth for a memory's lesson quality,
+     * shared by `admit` (the gate) and `format` (the K4-023 `(low
+     * confidence)` marker). Routes lessons through `QualityGate.evaluate`
+     * — the production call site that was previously missing.
+     */
+    private lessonQuality;
+    /**
+     * v0.4.0 (K4-017) — one ledger row per admitted memory (plan §5.2).
+     * Token attribution uses the memory's share of the final block.
+     *
+     * v0.8.0 (K8-024 / plan §5.7) — shared projections are recorded even
+     * though they carry NO fingerprint by design (K8-017 — it is a
+     * different identity dimension): the memory id is their identity in
+     * the ledger, and recording them is what makes `injections_from_shared`
+     * observable at all. No tool call can ever match a memory id, so
+     * settle() marks the row inconclusive — excluded from the precision
+     * denominator (K5-005) — and the BUG-015 skip is unchanged for local
+     * notes without a fingerprint.
+     */
+    private recordInjections;
+    /**
+     * v0.4.0 (K4-012) — snippet injection payload (plan §5.1 rule 5,
+     * D4-05): rows show `id:` + first 2 non-empty lines + `<protect>`
+     * instead of the full body. Gated by the `lesson_snippet_injection`
+     * setting (default `'1'`); when `'0'`, full content is restored.
+     * `escapeInjectedText` is applied to snippet content by the formatter.
+     * v0.4.0 (K4-023) — weak lessons admitted in debug mode are flagged so
+     * the formatter renders the `(low confidence)` marker.
+     */
+    private format;
+    deriveQuery(messages: ChatMessage[]): string;
+    onSystemTransform(input: SystemTransformInput, output: SystemTransformOutput): void;
+    onCompacting(input: CompactingInput, output: CompactingOutput): void;
+}