@cachly-dev/mcp-server 0.10.129 → 0.10.131

package/dist/src/ambient-recall.js

@@ -1,221 +1 @@
-// Ambient Recall (Phase 4) — the relevance gate + net-token accounting that make
-// push-based memory economically honest.
-//
-// Background (docs/make_cachly_great_again.md §6.2/§6.3): pushing recall into
-// every prompt COSTS tokens; it only pays off when the injected lesson prevents
-// a wrong path that would have cost far more. So the whole feature hinges on a
-// sharp relevance gate (only inject high-signal, few, small) plus honest net
-// accounting (injected vs prevented) with auto-backoff when it goes net-negative.
-//
-// This module is pure and dependency-free so it is exhaustively unit-tested; the
-// hook scripts + telemetry layer build on top of it.
-import { createHash } from 'node:crypto';
-// Deliberately conservative defaults: it is far cheaper to skip a marginal
-// lesson than to erode the "−60% tokens" credibility by injecting noise.
-export const DEFAULT_GATE = {
-    minConfidence: 0.6,
-    minScore: 0.72,
-    topK: 3,
-    maxTokens: 240,
-};
-/**
- * Derives a content-based candidate ID from a summary string. Enables
- * ID-based deduplication to suppress "the same advice" while allowing
- * "different advice" through. See PR #241.
- */
-export function candidateIdFor(summary) {
-    const hash = createHash('sha256').update(summary).digest('hex');
-    return hash.slice(0, 16);
-}
-/** Rough token estimate (~4 chars/token) — good enough for a per-turn budget. */
-export function estimateTokens(text) {
-    return Math.ceil(text.trim().length / 4);
-}
-// Pure conversational openers with no engineering payload.
-const TRIVIAL_RE = /^(hi|hello|hey|thanks|thank you|ok|okay|yes|no|yep|nope|ty|lol|danke|hallo|servus)\b/i;
-// Signals that a prompt is about code/ops, where a wrong path is expensive and a
-// relevant lesson can pay for itself. Calibrated against the golden vectors in
-// docs/spec/ambient-gate-vectors.json (ambient-gate-vectors.test.ts): the v1
-// list false-skipped short real requests like "curl returns 403 via the proxy"
-// or "rename the Settings page to Preferences" (substantive-recall 0.67), so
-// v2 adds engineering verbs, infra nouns, HTTP status codes and German
-// question words. Stems with \w* also match inflections ("migration",
-// "updated", "evicted"). Substantive-recall on the vector set: 1.0, with
-// trivial-precision unchanged at 1.0.
-const CODEY_RE = /[/\\._{}()<>;=]|\b\d{3}\b|\b(fix|bug|error|deploy|migrat\w*|test\w*|build|refactor|auth|api|db|schema|race|crash|fail\w*|revert|rollback|why|how|debug|config|hook|token|cache|add|creat\w*|implement\w*|updat\w*|remov\w*|delet\w*|renam\w*|install\w*|upgrad\w*|write|script|component|page|button|css|style\w*|log\w*|pod\w*|node\w*|docker|k8s|kubernetes|proxy|curl|http\w*|readme|lint\w*|latenc\w*|latenz|timeout\w*|evict\w*|warum|wieso|weshalb)\b/i;
-/**
- * A trivial prompt has ~zero expected wrong-path savings (§6.3 guardrail 2):
- * too short to carry risk, a pure greeting, or chit-chat with no code signal.
- * Injecting there is pure waste, so we skip recall entirely.
- */
-export function isTrivialPrompt(prompt) {
-    const p = prompt.trim();
-    if (p.length < 12)
-        return true;
-    if (TRIVIAL_RE.test(p) && p.length < 40)
-        return true;
-    if (!CODEY_RE.test(p) && p.length < 60)
-        return true;
-    return false;
-}
-/**
- * The §6.3 relevance gate: decide what (if anything) to push into context for a
- * given prompt. Applies trivial-skip, a confidence AND semantic-score floor,
- * a top-K cap, and a hard per-turn token budget — strongest candidates first.
- */
-export function selectInjectable(prompt, candidates, opts = {}) {
-    const o = { ...DEFAULT_GATE, ...opts };
-    if (isTrivialPrompt(prompt)) {
-        return { inject: false, reason: 'trivial-skip', selected: [], tokens: 0 };
-    }
-    const passed = candidates
-        .filter((c) => c.confidence >= o.minConfidence && c.score >= o.minScore)
-        .sort((a, b) => b.score - a.score || b.confidence - a.confidence);
-    const selected = [];
-    let tokens = 0;
-    for (const c of passed) {
-        if (selected.length >= o.topK)
-            break;
-        const t = estimateTokens(c.summary);
-        if (tokens + t > o.maxTokens)
-            break; // hard per-turn cap — never overshoot
-        selected.push(c);
-        tokens += t;
-    }
-    if (selected.length === 0) {
-        return { inject: false, reason: 'no-candidate-passed-gate', selected: [], tokens: 0 };
-    }
-    return { inject: true, reason: 'injected', selected, tokens };
-}
-export function netBalance(records) {
-    const injected = records.reduce((s, r) => s + r.injected, 0);
-    const prevented = records.reduce((s, r) => s + r.prevented, 0);
-    return { injected, prevented, net: prevented - injected };
-}
-/**
- * Auto-backoff (§6.3 guardrail 3): if, over the recent window, Ambient Recall is
- * net-negative, tell the caller to tighten the gate (or pause). Only fires once
- * there is enough signal (>= minTurns) so early noise doesn't trip it.
- */
-export function shouldBackoff(records, windowN = 20, minTurns = 8) {
-    const recent = records.slice(-windowN);
-    if (recent.length < minTurns)
-        return false;
-    return netBalance(recent).net < 0;
-}
-// Schritte, die man nicht zurücknehmen kann: hier ist eine verpasste Lektion
-// teuer, ein überflüssiger Hinweis dagegen billig.
-const RISKY_RE = /\b(deploy\w*|migrat\w*|rollback|revert|drop\s+(table|database|schema)|truncate|rm\s+-rf|force[- ]push|prune|restore|rotat\w*|secret\w*|credential\w*|production|prod|live|kunde\w*|customer\w*|delete|loesch\w*|lösch\w*)\b/i;
-// Reine Bestätigungen/Fortsetzungen: hier beginnt keine neue Arbeit.
-const CONTINUATION_RE = /^(ok(ay)?|ja|nein|weiter|passt|danke|thanks|go|los|mach|jup|yes|no|sure|next)\b[\s.!]*$/i;
-/**
- * Risikoeinschätzung des Auslösemoments. Sie verschiebt die Schwellen, statt
- * eine zweite, konkurrierende Entscheidung zu treffen — eine Stellschraube
- * weniger, und der Gate bleibt die einzige Wahrheit über Relevanz.
- */
-export function promptRisk(prompt) {
-    const p = prompt.trim();
-    if (CONTINUATION_RE.test(p))
-        return 'low';
-    if (RISKY_RE.test(p))
-        return 'high';
-    return 'normal';
-}
-/** Schwellen-Anpassung je Risiko (klein gehalten und bewusst begründet). */
-export function gateForRisk(risk, base = DEFAULT_GATE) {
-    if (risk === 'high') {
-        // Vor irreversiblen Schritten darf eine etwas schwächere Übereinstimmung
-        // reichen — die vermiedene Katastrophe ist jeden Token wert.
-        return { ...base, minScore: Math.max(0, base.minScore - 0.07), topK: base.topK, maxTokens: base.maxTokens + 120 };
-    }
-    if (risk === 'low') {
-        // Im Geplauder muss es sehr deutlich sein, sonst lieber schweigen.
-        return { ...base, minScore: Math.min(1, base.minScore + 0.1), topK: 1, maxTokens: Math.min(base.maxTokens, 120) };
-    }
-    return { ...base };
-}
-// Ein Einwurf pro ~3 Turns im Schnitt: oft genug, um zu helfen, selten genug,
-// dass er auffällt, wenn er kommt.
-export const DEFAULT_TIMING = {
-    repeatCooldownTurns: 12,
-    maxInjectionsPerWindow: 3,
-    windowTurns: 10,
-    minSilenceTurns: 1,
-};
-export function emptyMemory() {
-    return { turn: 0, lastInjectedTurn: {}, injectionTurns: [] };
-}
-/**
- * Die vollständige Entscheidung: Relevanz (Gate) UND Zeitpunkt (Timing).
- *
- * Reihenfolge ist Absicht: erst die billigen Ausschlüsse (Ruhe, Budget), dann
- * Dedupe, erst zuletzt der teure Relevanz-Gate — so kostet ein unterdrückter
- * Turn praktisch nichts.
- *
- * Die Funktion ist seiteneffektfrei; `commitInjection` schreibt das Gedächtnis
- * fort, damit Aufrufer selbst entscheiden, ob ein Vorschlag wirklich gezeigt
- * wurde (z. B. bei abgebrochenem Turn).
- */
-export function decideRecall(prompt, candidates, memory, gateOverrides = {}, timingOverrides = {}) {
-    const t = { ...DEFAULT_TIMING, ...timingOverrides };
-    const risk = promptRisk(prompt);
-    const none = (reason, timingReason) => ({
-        inject: false, reason, selected: [], tokens: 0, risk,
-        suppressedDuplicates: [], timingReason,
-    });
-    if (isTrivialPrompt(prompt))
-        return none('trivial-skip');
-    // Mindestruhe nach dem letzten Einwurf.
-    const last = memory.injectionTurns[memory.injectionTurns.length - 1];
-    if (last !== undefined && memory.turn - last <= t.minSilenceTurns) {
-        return none('no-candidate-passed-gate', 'silence-window');
-    }
-    // Ruhe-Budget im gleitenden Fenster.
-    const inWindow = memory.injectionTurns.filter((n) => memory.turn - n < t.windowTurns).length;
-    if (inWindow >= t.maxInjectionsPerWindow) {
-        return none('no-candidate-passed-gate', 'quiet-budget');
-    }
-    // Dedupe: was gerade erst gesagt wurde, wird nicht wiederholt.
-    const suppressedDuplicates = [];
-    const fresh = candidates.filter((c) => {
-        const seen = memory.lastInjectedTurn[c.id];
-        if (seen !== undefined && memory.turn - seen < t.repeatCooldownTurns) {
-            suppressedDuplicates.push(c.id);
-            return false;
-        }
-        return true;
-    });
-    if (candidates.length > 0 && fresh.length === 0) {
-        return { ...none('no-candidate-passed-gate', 'all-duplicates'), suppressedDuplicates };
-    }
-    const gate = selectInjectable(prompt, fresh, { ...gateForRisk(risk), ...gateOverrides });
-    return { ...gate, risk, suppressedDuplicates };
-}
-/**
- * Schreibt das Gedächtnis nach einem TATSÄCHLICH gezeigten Einwurf fort.
- * Der Turn-Zähler wird immer erhöht — auch ohne Einwurf, sonst laufen
- * Abklingzeit und Fenster nicht weiter.
- */
-export function commitInjection(memory, decision, timingOverrides = {}) {
-    const t = { ...DEFAULT_TIMING, ...timingOverrides };
-    const next = {
-        turn: memory.turn + 1,
-        lastInjectedTurn: { ...memory.lastInjectedTurn },
-        injectionTurns: [...memory.injectionTurns],
-    };
-    if (decision.inject) {
-        for (const c of decision.selected)
-            next.lastInjectedTurn[c.id] = memory.turn;
-        next.injectionTurns.push(memory.turn);
-    }
-    // Nach Ablauf der Fenster sind Eintraege bedeutungslos — sonst waechst das
-    // Gedaechtnis in langen Sitzungen unbegrenzt mit.
-    const horizon = memory.turn - Math.max(t.windowTurns, t.repeatCooldownTurns);
-    next.injectionTurns = next.injectionTurns.filter((n) => n >= horizon);
-    for (const [id, turn] of Object.entries(next.lastInjectedTurn)) {
-        if (turn < horizon)
-            delete next.lastInjectedTurn[id];
-    }
-    return next;
-}
-//# sourceMappingURL=ambient-recall.js.map
+import{createHash as T}from"node:crypto";const f={minConfidence:.6,minScore:.72,topK:3,maxTokens:240};function M(n){return T("sha256").update(n).digest("hex").slice(0,16)}function k(n){return Math.ceil(n.trim().length/4)}const g=/^(hi|hello|hey|thanks|thank you|ok|okay|yes|no|yep|nope|ty|lol|danke|hallo|servus)\b/i,j=/[/\\._{}()<>;=]|\b\d{3}\b|\b(fix|bug|error|deploy|migrat\w*|test\w*|build|refactor|auth|api|db|schema|race|crash|fail\w*|revert|rollback|why|how|debug|config|hook|token|cache|add|creat\w*|implement\w*|updat\w*|remov\w*|delet\w*|renam\w*|install\w*|upgrad\w*|write|script|component|page|button|css|style\w*|log\w*|pod\w*|node\w*|docker|k8s|kubernetes|proxy|curl|http\w*|readme|lint\w*|latenc\w*|latenz|timeout\w*|evict\w*|warum|wieso|weshalb)\b/i;function h(n){const e=n.trim();return!!(e.length<12||g.test(e)&&e.length<40||!j.test(e)&&e.length<60)}function m(n,e,t={}){const r={...f,...t};if(h(n))return{inject:!1,reason:"trivial-skip",selected:[],tokens:0};const o=e.filter(i=>i.confidence>=r.minConfidence&&i.score>=r.minScore).sort((i,u)=>u.score-i.score||u.confidence-i.confidence),c=[];let s=0;for(const i of o){if(c.length>=r.topK)break;const u=k(i.summary);if(s+u>r.maxTokens)break;c.push(i),s+=u}return c.length===0?{inject:!1,reason:"no-candidate-passed-gate",selected:[],tokens:0}:{inject:!0,reason:"injected",selected:c,tokens:s}}function x(n){const e=n.reduce((r,o)=>r+o.injected,0),t=n.reduce((r,o)=>r+o.prevented,0);return{injected:e,prevented:t,net:t-e}}function _(n,e=20,t=8){const r=n.slice(-e);return r.length<t?!1:x(r).net<0}const I=/\b(deploy\w*|migrat\w*|rollback|revert|drop\s+(table|database|schema)|truncate|rm\s+-rf|force[- ]push|prune|restore|rotat\w*|secret\w*|credential\w*|production|prod|live|kunde\w*|customer\w*|delete|loesch\w*|lösch\w*)\b/i,b=/^(ok(ay)?|ja|nein|weiter|passt|danke|thanks|go|los|mach|jup|yes|no|sure|next)\b[\s.!]*$/i;function v(n){const e=n.trim();return b.test(e)?"low":I.test(e)?"high":"normal"}function R(n,e=f){return n==="high"?{...e,minScore:Math.max(0,e.minScore-.07),topK:e.topK,maxTokens:e.maxTokens+120}:n==="low"?{...e,minScore:Math.min(1,e.minScore+.1),topK:1,maxTokens:Math.min(e.maxTokens,120)}:{...e}}const w={repeatCooldownTurns:12,maxInjectionsPerWindow:3,windowTurns:10,minSilenceTurns:1};function K(){return{turn:0,lastInjectedTurn:{},injectionTurns:[]}}function y(n,e,t,r={},o={}){const c={...w,...o},s=v(n),i=(a,l)=>({inject:!1,reason:a,selected:[],tokens:0,risk:s,suppressedDuplicates:[],timingReason:l});if(h(n))return i("trivial-skip");const u=t.injectionTurns[t.injectionTurns.length-1];if(u!==void 0&&t.turn-u<=c.minSilenceTurns)return i("no-candidate-passed-gate","silence-window");if(t.injectionTurns.filter(a=>t.turn-a<c.windowTurns).length>=c.maxInjectionsPerWindow)return i("no-candidate-passed-gate","quiet-budget");const d=[],p=e.filter(a=>{const l=t.lastInjectedTurn[a.id];return l!==void 0&&t.turn-l<c.repeatCooldownTurns?(d.push(a.id),!1):!0});return e.length>0&&p.length===0?{...i("no-candidate-passed-gate","all-duplicates"),suppressedDuplicates:d}:{...m(n,p,{...R(s),...r}),risk:s,suppressedDuplicates:d}}function A(n,e,t={}){const r={...w,...t},o={turn:n.turn+1,lastInjectedTurn:{...n.lastInjectedTurn},injectionTurns:[...n.injectionTurns]};if(e.inject){for(const s of e.selected)o.lastInjectedTurn[s.id]=n.turn;o.injectionTurns.push(n.turn)}const c=n.turn-Math.max(r.windowTurns,r.repeatCooldownTurns);o.injectionTurns=o.injectionTurns.filter(s=>s>=c);for(const[s,i]of Object.entries(o.lastInjectedTurn))i<c&&delete o.lastInjectedTurn[s];return o}export{f as DEFAULT_GATE,w as DEFAULT_TIMING,M as candidateIdFor,A as commitInjection,y as decideRecall,K as emptyMemory,k as estimateTokens,R as gateForRisk,h as isTrivialPrompt,x as netBalance,v as promptRisk,m as selectInjectable,_ as shouldBackoff};

package/dist/src/aussetzer.js

@@ -1,225 +1 @@
-/**
- * Meldestelle fuer stille Aussetzer.
- *
- * ── Warum es das gibt ───────────────────────────────────────────────────────
- *
- * Am 20.08.2026 wurde am Produktionsspeicher gemessen: `cachly:lesson:vec:*`
- * war LEER — 0 Vektoren bei 506 Lektionen. Der Recall-Pfad steigt bei
- * `vektorbestand.groesse === 0` aus und faellt auf den reinen Wortabgleich
- * zurueck. Er tut das STUMM.
- *
- * Von aussen ist dieser Zustand von "alles in Ordnung" nicht zu
- * unterscheiden: die Suche liefert weiter Ergebnisse, nur schlechtere. Die am
- * 19.08. gemessene Verbesserung von 21 auf 40 Prozent existierte in
- * Produktion nie, und nichts hat es gesagt.
- *
- * Das ist die Fehlerklasse "Stille wird als gruen gebucht". Diese Datei ist
- * die Gegenmassnahme an der billigsten Stelle: eine Zeile im Protokoll.
- *
- * ── Warum nur EINMAL je Grund ───────────────────────────────────────────────
- *
- * Der Recall-Pfad laeuft bei jeder Anfrage. Eine Zeile je Anfrage waere nach
- * einer Stunde ein Protokoll, das niemand mehr liest — und ein Protokoll, das
- * niemand liest, ist wieder Stille. Einmal je Grund und Prozess ist die
- * Menge, die auffaellt, ohne zu ermueden.
- *
- * ── Warum stderr und nicht stdout ───────────────────────────────────────────
- *
- * Ueber stdout laeuft das MCP-Protokoll. Eine Zeile Text dort ist kein
- * Hinweis, sondern ein Verbindungsabbruch.
- */
-/** Welche Gruende schon gemeldet wurden. Je Prozess, nicht je Anfrage. */
-const gemeldet = new Set();
-/**
- * Aus einem geworfenen Wert einen lesbaren Grund machen.
- *
- * JavaScript laesst zu, dass ALLES geworfen wird — ein Error, ein String, ein
- * undefined. `String(e)` auf einem leeren Objekt ergibt "[object Object]", und
- * das ist als Ursachenangabe wertlos.
- *
- * Gekuerzt auf 200 Zeichen: der Grund gehoert in EINE Protokollzeile. Manche
- * Anbieter antworten mit einer ganzen HTML-Seite, und ein Protokoll, das
- * niemand mehr liest, ist wieder Stille.
- */
-export function fehlerText(e) {
-    if (e instanceof Error)
-        return (e.message || e.name || 'Error').slice(0, 200);
-    if (typeof e === 'string')
-        return e.slice(0, 200) || 'leerer Text geworfen';
-    if (e === undefined)
-        return 'undefined geworfen (kein Grund mitgegeben)';
-    if (e === null)
-        return 'null geworfen (kein Grund mitgegeben)';
-    try {
-        const j = JSON.stringify(e);
-        return j && j !== '{}' ? j.slice(0, 200) : `${typeof e} ohne Inhalt geworfen`;
-    }
-    catch {
-        return `${typeof e} geworfen, nicht darstellbar`;
-    }
-}
-/**
- * Meldet einen Aussetzer genau einmal je Grund und Prozess.
- *
- * @param grund kurzer Schluessel, z. B. 'bedeutung-ohne-vektoren'
- * @param text  was ausgefallen ist und was das fuer das Ergebnis heisst
- * @returns true, wenn diese Meldung wirklich hinausging
- */
-export function meldeEinmal(grund, text) {
-    if (gemeldet.has(grund))
-        return false;
-    gemeldet.add(grund);
-    console.error(`[aussetzer] ${grund}: ${text}`);
-    return true;
-}
-/**
- * Wurde dieser Grund in diesem Prozess schon gemeldet?
- *
- * Fuer `brain_doctor`: dort soll stehen, was hier passiert ist, ohne dass
- * jemand ein Protokoll durchsuchen muss.
- */
-export function schonGemeldet(grund) {
-    return gemeldet.has(grund);
-}
-/** Alle bisher gemeldeten Gruende, in der Reihenfolge des Auftretens. */
-export function gemeldeteGruende() {
-    return [...gemeldet];
-}
-/**
- * Setzt die Merkliste zurueck.
- *
- * Nur fuer Tests. Ohne das wuerde die erste Testdatei alle weiteren blind
- * machen — genau der Fehler, gegen den diese Datei antritt.
- */
-export function setzeAussetzerZurueck() {
-    gemeldet.clear();
-}
-/** Der Grund, um den es beim Anlass ging: Bedeutungsabgleich ohne Vektoren. */
-export const OHNE_VEKTOREN = 'bedeutung-ohne-vektoren';
-/** Der Nachbarfall: es gibt gar keinen Dienst zum Einbetten. */
-export const OHNE_DIENST = 'bedeutung-ohne-dienst';
-/**
- * Der Bestand ist da, aber die FRAGE liess sich nicht einbetten.
- *
- * Eigener Grund und nicht mit OHNE_VEKTOREN zusammengelegt: hier ist der
- * Bestand gesund und der fremde Dienst hat gerade nicht geantwortet. Das ist
- * ein Netzproblem und keine fehlende Nachruestung — wer beides unter einem
- * Namen fuehrt, sucht spaeter an der falschen Stelle.
- */
-export const OHNE_FRAGEVEKTOR = 'bedeutung-ohne-fragevektor';
-/**
- * Der Auffang-catch am Ende des Bedeutungspfads.
- *
- * Eigener Grund, weil er etwas anderes bedeutet als die drei darueber: die
- * sind BENANNTE Ausstiege ("kein Dienst", "keine Vektoren", "Frage nicht
- * einbettbar") — hier ist etwas Unerwartetes passiert. Wer beides unter einem
- * Namen fuehrt, sieht nicht, dass er einen Fehler hat statt einer Luecke.
- */
-export const SINNPFAD_ABBRUCH = 'bedeutung-abbruch';
-/**
- * Die Einbettung BEIM SCHREIBEN einer Lektion ist fehlgeschlagen.
- *
- * ── Warum dieser Grund am 22.08.2026 dazukam ────────────────────────────────
- *
- * Alle Gruende darueber betreffen das SUCHEN. Das Schreiben hatte keinen: in
- * handlers/brain.ts standen drei leere `catch { }` um die drei Einbettungen
- * (Volltext, Themenname, Eingaenge). Sie sind mit Absicht fehlertolerant —
- * eine Lektion muss auch ohne Netz gespeichert werden koennen — aber sie
- * warfen den GRUND weg.
- *
- * Gemessen am 22.08.2026 ueber den Admin-Endpunkt: von 50 gezogenen Instanzen
- * hatten drei Lektionen (10, 2 und 46) und NULL Vektoren. Warum, konnte
- * niemand sagen — kein Protokoll, keine Zahl, nichts. Der Wachhund meldete
- * seit zwei Tagen "Bedeutungsabgleich AUS", ohne dass eine Ursache
- * feststellbar war.
- *
- * Die Fehlerklasse ist bekannt: "Stille wird als gruen gebucht". Der
- * Unterschied hier ist, dass nicht einmal der Ausfall still war, sondern nur
- * sein Grund. Ein Alarm ohne Ursache ist ein Alarm, den man abschaltet.
- *
- * Die Lektion wird weiterhin gespeichert. Es aendert sich NUR, dass der Grund
- * einmal je Prozess im Protokoll steht.
- */
-export const OHNE_SCHREIBVEKTOR = 'einbettung-beim-schreiben';
-/** Der Versuch ist eingeschaltet, laeuft aber ohne Wirkung (siehe versuch.ts). */
-export const VERSUCH_LEER = 'versuch-laeuft-leer';
-// ── Der Vermerk, der einen Neustart ueberlebt ───────────────────────────────
-//
-// meldeEinmal schreibt nach stderr und merkt sich den Grund im
-// Arbeitsspeicher. Beides ist nach einem Neustart weg — bei jedem Deploy,
-// jedem Absturz, jeder Skalierung. Gemessen am 20.08.2026 (Karte
-// opupbt3l9wcq): eine Fehlkonfiguration konnte so WOCHENLANG bestehen, ohne
-// dass jemand sie sah, weil "keine Daten" und "noch nicht genug Daten" von
-// aussen gleich aussehen.
-//
-// Deshalb zusaetzlich ein Vermerk in Valkey: Zaehler, letzter Zeitpunkt,
-// letzter Text. `brain_doctor` liest ihn, also braucht niemand ein Protokoll
-// zu durchsuchen.
-//
-// Die Lebensdauer wird bei JEDEM Vermerk erneuert. Damit heisst "vorhanden"
-// immer "in den letzten 30 Tagen passiert" — ein Aussetzer von vor einem
-// halben Jahr steht nicht mehr im Weg, und ein laufender verschwindet nie.
-/** Schluessel-Vorsatz der Vermerke. */
-export const AUSSETZER_VORSATZ = 'cachly:aussetzer:';
-/** 30 Tage. Wird bei jedem Vermerk erneuert. */
-export const AUSSETZER_TTL_SEKUNDEN = 30 * 24 * 60 * 60;
-/**
- * Meldet den Aussetzer (einmal je Prozess) UND vermerkt ihn dauerhaft.
- *
- * Der Vermerk darf die Anfrage NIE zum Scheitern bringen: wer eine Suche
- * abbricht, weil er den Ausfall nicht aufschreiben konnte, hat aus einer
- * Verschlechterung einen Ausfall gemacht. Scheitert das Schreiben, bleibt es
- * bei der stderr-Zeile — gemeldet ueber meldeEinmal, damit auch dieser
- * Rueckfall nicht still ist.
- *
- * @returns true, wenn die stderr-Meldung wirklich hinausging
- */
-export async function meldeUndVermerke(redis, grund, text) {
-    const gemeldetJetzt = meldeEinmal(grund, text);
-    if (!redis)
-        return gemeldetJetzt;
-    try {
-        const key = `${AUSSETZER_VORSATZ}${grund}`;
-        await redis.hincrby(key, 'anzahl', 1);
-        await redis.hset(key, { zuletzt: new Date().toISOString(), text: text.slice(0, 500) });
-        await redis.expire(key, AUSSETZER_TTL_SEKUNDEN);
-    }
-    catch (e) {
-        meldeEinmal(`${grund}-vermerk`, `der Aussetzer liess sich nicht vermerken (${e instanceof Error ? e.message : String(e)}) `
-            + '— er steht nur in diesem Protokoll und ist nach einem Neustart weg');
-    }
-    return gemeldetJetzt;
-}
-/**
- * Alle Vermerke der letzten 30 Tage, der haeufigste zuerst.
- *
- * Fuer `brain_doctor`. Ein Fehler beim Lesen liefert eine leere Liste — aber
- * NICHT still: der Aufrufer bekommt `null` und kann "nicht gemessen" von
- * "nichts gefunden" unterscheiden. Genau dieser Unterschied fehlte an allen
- * Stellen, aus denen diese Datei entstanden ist.
- */
-export async function leseVermerke(redis) {
-    if (!redis)
-        return null;
-    try {
-        const keys = await redis.keys(`${AUSSETZER_VORSATZ}*`);
-        const vermerke = [];
-        for (const key of keys) {
-            const h = await redis.hgetall(key);
-            if (!h || !h.anzahl)
-                continue;
-            vermerke.push({
-                grund: key.slice(AUSSETZER_VORSATZ.length),
-                anzahl: Number(h.anzahl) || 0,
-                zuletzt: h.zuletzt ?? '',
-                text: h.text ?? '',
-            });
-        }
-        vermerke.sort((a, b) => b.anzahl - a.anzahl || a.grund.localeCompare(b.grund));
-        return vermerke;
-    }
-    catch {
-        return null;
-    }
-}
-//# sourceMappingURL=aussetzer.js.map
+const u=new Set;function i(e){if(e instanceof Error)return(e.message||e.name||"Error").slice(0,200);if(typeof e=="string")return e.slice(0,200)||"leerer Text geworfen";if(e===void 0)return"undefined geworfen (kein Grund mitgegeben)";if(e===null)return"null geworfen (kein Grund mitgegeben)";try{const n=JSON.stringify(e);return n&&n!=="{}"?n.slice(0,200):`${typeof e} ohne Inhalt geworfen`}catch{return`${typeof e} geworfen, nicht darstellbar`}}function c(e,n){return u.has(e)?!1:(u.add(e),console.error(`[aussetzer] ${e}: ${n}`),!0)}function l(e){return u.has(e)}function f(){return[...u]}function h(){u.clear()}const g="bedeutung-ohne-vektoren",E="bedeutung-ohne-dienst",m="bedeutung-ohne-fragevektor",p="bedeutung-abbruch",x="einbettung-beim-schreiben",d="versuch-laeuft-leer",s="cachly:aussetzer:",a=720*60*60;async function z(e,n,o){const r=c(n,o);if(!e)return r;try{const t=`${s}${n}`;await e.hincrby(t,"anzahl",1),await e.hset(t,{zuletzt:new Date().toISOString(),text:o.slice(0,500)}),await e.expire(t,a)}catch(t){c(`${n}-vermerk`,`der Aussetzer liess sich nicht vermerken (${t instanceof Error?t.message:String(t)}) \u2014 er steht nur in diesem Protokoll und ist nach einem Neustart weg`)}return r}async function k(e){if(!e)return null;try{const n=await e.keys(`${s}*`),o=[];for(const r of n){const t=await e.hgetall(r);!t||!t.anzahl||o.push({grund:r.slice(s.length),anzahl:Number(t.anzahl)||0,zuletzt:t.zuletzt??"",text:t.text??""})}return o.sort((r,t)=>t.anzahl-r.anzahl||r.grund.localeCompare(t.grund)),o}catch{return null}}export{a as AUSSETZER_TTL_SEKUNDEN,s as AUSSETZER_VORSATZ,E as OHNE_DIENST,m as OHNE_FRAGEVEKTOR,x as OHNE_SCHREIBVEKTOR,g as OHNE_VEKTOREN,p as SINNPFAD_ABBRUCH,d as VERSUCH_LEER,i as fehlerText,f as gemeldeteGruende,k as leseVermerke,c as meldeEinmal,z as meldeUndVermerke,l as schonGemeldet,h as setzeAussetzerZurueck};

package/dist/src/auth.js

@@ -1,140 +1,9 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { cachlyUrl } from './cachly-url.js';
-export function jwtExpiryMs(token) {
-    try {
-        const parts = token.split('.');
-        if (parts.length !== 3)
-            return null;
-        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
-        return payload.exp ? payload.exp * 1000 : null;
-    }
-    catch {
-        return null;
-    }
-}
-// ── Self-healing auth ─────────────────────────────────────────────────────────
-// The silent-failure mode we guard against: a token that is missing, expired, or
-// about to expire degrades the brain into "0 recalls" without the user ever being
-// told why. Instead of failing silently (or only at the moment a network call
-// finally 401s), we diagnose the credential up front and either heal it
-// automatically (mint a fresh long-lived key while the current one is still valid)
-// or surface a single, actionable instruction.
-/** Long-lived API keys cannot expire silently; raw access tokens can. */
-export const API_KEY_PREFIX = 'cky_';
-/** A long-lived API key (cky_live_… / cky_…) has no exp and never expires silently. */
-export function isLongLivedApiKey(token) {
-    return token.startsWith(API_KEY_PREFIX);
-}
-// Refresh a token this close to expiry (or already expired) the moment we touch it.
-export const NEAR_EXPIRY_MS = 10 * 60 * 1000; // 10 minutes
-const SETUP_URL = cachlyUrl('/setup-ai', 'auth-diagnosis');
-/**
- * Diagnose the current credential without making any network call. Pure +
- * deterministic (pass `now` in tests).
- */
-export function diagnoseAuth(jwt, now = Date.now()) {
-    if (!jwt) {
-        return {
-            state: 'no_jwt',
-            usable: false,
-            expiresInMs: null,
-            message: `No CACHLY_JWT set — the brain can't persist or recall anything (you'd silently get 0 recalls).\n\nGet your token at ${SETUP_URL} and add it to your MCP config, or just call any tool to start the one-time device-flow sign-in.`,
-        };
-    }
-    const expMs = jwtExpiryMs(jwt);
-    // No exp claim → long-lived API key. These are the healthy steady state.
-    if (expMs === null) {
-        return {
-            state: isLongLivedApiKey(jwt) ? 'long_lived' : 'healthy',
-            usable: true,
-            expiresInMs: null,
-            message: '',
-        };
-    }
-    const remaining = expMs - now;
-    if (remaining <= 0) {
-        return {
-            state: 'expired',
-            usable: false,
-            expiresInMs: remaining,
-            message: `CACHLY_JWT expired at ${new Date(expMs).toISOString()} — recalls will silently return nothing until you re-authenticate.\n\nGet a fresh token at ${SETUP_URL}, or call any tool to re-run the device-flow sign-in.`,
-        };
-    }
-    if (remaining <= NEAR_EXPIRY_MS) {
-        const mins = Math.max(1, Math.round(remaining / 60_000));
-        return {
-            state: 'near_expiry',
-            usable: true,
-            expiresInMs: remaining,
-            message: `CACHLY_JWT expires in ~${mins} min. cachly will refresh it automatically into a long-lived key while it's still valid.`,
-        };
-    }
-    return { state: 'healthy', usable: true, expiresInMs: remaining, message: '' };
-}
-/**
- * Decide what self-healing step (if any) to take for a diagnosis. Pure so the
- * decision is unit-testable independently of the network-bound executor.
- */
-export function planAuthHeal(d) {
-    switch (d.state) {
-        case 'no_jwt':
-        case 'expired':
-            return 'reauth';
-        case 'near_expiry':
-            return 'refresh';
-        case 'healthy':
-        case 'long_lived':
-            return 'none';
-    }
-}
-export function checkJwt(jwt) {
-    const d = diagnoseAuth(jwt);
-    if (!d.usable) {
-        throw new McpError(ErrorCode.InvalidRequest, d.message);
-    }
-}
-// ── M2M / headless auth (OAuth2 client_credentials) ──────────────────────────
-// For machine-to-machine callers — CI runners, agent orchestrators, AI-to-AI
-// pipelines — there is no human to complete a device flow. When CACHLY_CLIENT_ID
-// and CACHLY_CLIENT_SECRET are present we run the standard OAuth2
-// client_credentials grant against Keycloak and use the resulting access token
-// exactly like a CACHLY_JWT. Fully non-interactive.
-export const DEFAULT_AUTH_BASE = 'https://auth.cachly.dev/realms/cachly/protocol/openid-connect';
-/** Read M2M client credentials from the environment, if both are present. */
-export function readClientCredentialsFromEnv(env = process.env) {
-    const clientId = env.CACHLY_CLIENT_ID;
-    const clientSecret = env.CACHLY_CLIENT_SECRET;
-    if (!clientId || !clientSecret)
-        return null;
-    return {
-        clientId,
-        clientSecret,
-        scope: env.CACHLY_CLIENT_SCOPE || 'openid',
-        authBase: env.CACHLY_AUTH_URL || DEFAULT_AUTH_BASE,
-    };
-}
-/** Build the application/x-www-form-urlencoded body for a client_credentials grant. */
-export function buildClientCredentialsBody(c) {
-    const params = new URLSearchParams({
-        grant_type: 'client_credentials',
-        client_id: c.clientId,
-        client_secret: c.clientSecret,
-    });
-    if (c.scope)
-        params.set('scope', c.scope);
-    return params.toString();
-}
-/** Token endpoint URL for a given credentials/realm config. */
-export function clientCredentialsTokenUrl(c) {
-    return `${c.authBase ?? DEFAULT_AUTH_BASE}/token`;
-}
-export function handleApiError(status, detail) {
-    if (status === 401) {
-        throw new McpError(ErrorCode.InvalidRequest, `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at ${SETUP_URL}`);
-    }
-    if (status === 403) {
-        throw new McpError(ErrorCode.InvalidRequest, `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`);
-    }
-    throw new McpError(ErrorCode.InternalError, `cachly API error ${status}: ${detail}`);
-}
-//# sourceMappingURL=auth.js.map
+import{ErrorCode as o,McpError as s}from"@modelcontextprotocol/sdk/types.js";import{cachlyUrl as c}from"./cachly-url.js";function u(e){try{const t=e.split(".");if(t.length!==3)return null;const n=JSON.parse(Buffer.from(t[1],"base64url").toString("utf-8"));return n.exp?n.exp*1e3:null}catch{return null}}const p="cky_";function h(e){return e.startsWith(p)}const d=600*1e3,i=c("/setup-ai","auth-diagnosis");function f(e,t=Date.now()){if(!e)return{state:"no_jwt",usable:!1,expiresInMs:null,message:`No CACHLY_JWT set \u2014 the brain can't persist or recall anything (you'd silently get 0 recalls).
+
+Get your token at ${i} and add it to your MCP config, or just call any tool to start the one-time device-flow sign-in.`};const n=u(e);if(n===null)return{state:h(e)?"long_lived":"healthy",usable:!0,expiresInMs:null,message:""};const r=n-t;if(r<=0)return{state:"expired",usable:!1,expiresInMs:r,message:`CACHLY_JWT expired at ${new Date(n).toISOString()} \u2014 recalls will silently return nothing until you re-authenticate.
+
+Get a fresh token at ${i}, or call any tool to re-run the device-flow sign-in.`};if(r<=d){const l=Math.max(1,Math.round(r/6e4));return{state:"near_expiry",usable:!0,expiresInMs:r,message:`CACHLY_JWT expires in ~${l} min. cachly will refresh it automatically into a long-lived key while it's still valid.`}}return{state:"healthy",usable:!0,expiresInMs:r,message:""}}function y(e){switch(e.state){case"no_jwt":case"expired":return"reauth";case"near_expiry":return"refresh";case"healthy":case"long_lived":return"none"}}function x(e){const t=f(e);if(!t.usable)throw new s(o.InvalidRequest,t.message)}const a="https://auth.cachly.dev/realms/cachly/protocol/openid-connect";function g(e=process.env){const t=e.CACHLY_CLIENT_ID,n=e.CACHLY_CLIENT_SECRET;return!t||!n?null:{clientId:t,clientSecret:n,scope:e.CACHLY_CLIENT_SCOPE||"openid",authBase:e.CACHLY_AUTH_URL||a}}function m(e){const t=new URLSearchParams({grant_type:"client_credentials",client_id:e.clientId,client_secret:e.clientSecret});return e.scope&&t.set("scope",e.scope),t.toString()}function A(e){return`${e.authBase??a}/token`}function w(e,t){throw e===401?new s(o.InvalidRequest,`Authentication failed (401): ${t}
+
+Your CACHLY_JWT may be expired or invalid. Get a fresh token at ${i}`):e===403?new s(o.InvalidRequest,`Access denied (403): ${t}
+
+Check that your CACHLY_JWT belongs to an account with access to this resource.`):new s(o.InternalError,`cachly API error ${e}: ${t}`)}export{p as API_KEY_PREFIX,a as DEFAULT_AUTH_BASE,d as NEAR_EXPIRY_MS,m as buildClientCredentialsBody,x as checkJwt,A as clientCredentialsTokenUrl,f as diagnoseAuth,w as handleApiError,h as isLongLivedApiKey,u as jwtExpiryMs,y as planAuthHeal,g as readClientCredentialsFromEnv};

package/dist/src/autor-abzeichen.js

@@ -1,56 +1 @@
-/**
- * Wer hat diese Lektion geschrieben — ich oder jemand anderes?
- *
- * `session_start_summary` nimmt seit jeher einen Parameter `author` entgegen
- * und beschreibt ihn in der Werkzeug-Spezifikation so:
- *
- *   "Your name or handle (optional). Same as session_start — used for team
- *    lesson filtering."
- *
- * Die Zusage wurde nie eingeloest. Der Handler holte den Wert aus den
- * Argumenten und benutzte ihn danach nirgends; eslint meldete ihn seit
- * Monaten als ungenutzte Variable. Wer den Parameter setzte, bekam exakt
- * dieselbe Ausgabe wie ohne ihn.
- *
- * Fehlerklasse: eine Zusage an zwei Orten — hier in der Spezifikation, dort
- * im Code — und nur einer wurde gepflegt. Dieselbe Form wie die Kommentarzeile
- * am Frei-Limit, die "the #1 result is always returned" versprach, waehrend
- * der Zweig darunter null lieferte.
- *
- * Reines Modul, weil die Entscheidung eine Rechnung ist: dieselbe Regel, die
- * `smart_recall` schon anwendet, an EINER Stelle statt zweimal abgeschrieben.
- */
-/**
- * Das Abzeichen hinter einer Lektion — leer, wenn sie von mir selbst stammt
- * oder niemand als Autor eingetragen ist.
- *
- * Bewusst KEIN Abzeichen fuer die eigenen Lektionen: in einem Brain, das
- * ueberwiegend einer Person gehoert, stuende sonst hinter jeder Zeile derselbe
- * Name, und das Abzeichen verlöre genau die Aussage, für die es da ist.
- */
-export function autorAbzeichen(lektionsAutor, anfragender) {
-    const autor = (lektionsAutor ?? '').trim();
-    if (!autor)
-        return '';
-    const ich = (anfragender ?? '').trim();
-    if (ich && autor === ich)
-        return '';
-    return ` · 👤 ${autor}`;
-}
-/**
- * Wie viele der gezeigten Lektionen von jemand anderem stammen.
- *
- * Das ist der Wert, den nur ein GETEILTES Gedaechtnis liefert — und deshalb
- * die Zahl, die es zu nennen lohnt. Ist sie null, wird auch nichts gesagt:
- * "0 von Teamkollegen" ist keine Nachricht, sondern Rauschen.
- */
-export function fremdanteil(lektionen, anfragender) {
-    const ich = (anfragender ?? '').trim();
-    if (!ich)
-        return 0;
-    return lektionen.filter(l => {
-        const autor = (l.author ?? '').trim();
-        return autor.length > 0 && autor !== ich;
-    }).length;
-}
-//# sourceMappingURL=autor-abzeichen.js.map
+function o(n,e){const t=(n??"").trim();if(!t)return"";const r=(e??"").trim();return r&&t===r?"":` \xB7 \u{1F464} ${t}`}function u(n,e){const t=(e??"").trim();return t?n.filter(r=>{const i=(r.author??"").trim();return i.length>0&&i!==t}).length:0}export{o as autorAbzeichen,u as fremdanteil};