@cachly-dev/mcp-server 0.10.129 → 0.10.130

package/dist/src/toolspecs.js

@@ -1,121 +1 @@
-/**
- * Agent-framework tool-spec exporter.
- *
- * cachly exposes 122 MCP tools. MCP-native clients (Claude Code, Cursor,
- * Windsurf, Copilot) speak MCP directly. But the wider agent ecosystem —
- * OpenAI Assistants / function calling, the Anthropic Messages API, LangChain,
- * CrewAI, AutoGen — each want the SAME tool definitions in their own dialect.
- *
- * Rather than hand-maintain four copies, we derive every dialect from the single
- * TOOLS source of truth. Zero new runtime dependencies: these are just shape
- * transforms over the JSON-Schema input schemas the tools already declare.
- *
- * CLI:  npx @cachly-dev/mcp-server tool-specs --format=openapi|openai|anthropic|langchain
- */
-const SERVER_TITLE = 'cachly AI Brain — MCP tools';
-/** OpenAI function-calling / Assistants tool array. */
-export function toOpenAITools(tools) {
-    return tools.map(t => ({
-        type: 'function',
-        function: {
-            name: t.name,
-            description: t.description,
-            parameters: t.inputSchema ?? { type: 'object', properties: {} },
-        },
-    }));
-}
-/** Anthropic Messages API tool array (input_schema, not parameters). */
-export function toAnthropicTools(tools) {
-    return tools.map(t => ({
-        name: t.name,
-        description: t.description,
-        input_schema: t.inputSchema ?? { type: 'object', properties: {} },
-    }));
-}
-/**
- * LangChain / CrewAI StructuredTool descriptors. LangChain consumes a name +
- * description + JSON-schema args; this shape is accepted by
- * `convertToOpenAITool`-style helpers and by CrewAI's tool adapters.
- */
-export function toLangChainTools(tools) {
-    return tools.map(t => ({
-        name: t.name,
-        description: t.description,
-        schema: t.inputSchema ?? { type: 'object', properties: {} },
-    }));
-}
-/**
- * OpenAPI 3.1 document. Each MCP tool becomes a POST operation under
- * /mcp/tools/{name}, with the tool's input schema as the request body. This lets
- * any OpenAPI-driven agent (OpenAI Assistants "from OpenAPI", Postman, codegen)
- * wrap cachly automatically. The operation maps 1:1 onto an MCP tools/call.
- */
-export function toOpenAPI(tools, version, serverUrl = 'https://api.cachly.dev') {
-    const paths = {};
-    for (const t of tools) {
-        paths[`/mcp/tools/${t.name}`] = {
-            post: {
-                operationId: t.name,
-                summary: t.description.split('. ')[0],
-                description: t.description,
-                requestBody: {
-                    required: (t.inputSchema?.required?.length ?? 0) > 0,
-                    content: {
-                        'application/json': {
-                            schema: t.inputSchema ?? { type: 'object', properties: {} },
-                        },
-                    },
-                },
-                responses: {
-                    '200': {
-                        description: 'Tool result (MCP content blocks).',
-                        content: {
-                            'application/json': {
-                                schema: {
-                                    type: 'object',
-                                    properties: {
-                                        content: {
-                                            type: 'array',
-                                            items: {
-                                                type: 'object',
-                                                properties: { type: { type: 'string' }, text: { type: 'string' } },
-                                            },
-                                        },
-                                    },
-                                },
-                            },
-                        },
-                    },
-                },
-            },
-        };
-    }
-    return {
-        openapi: '3.1.0',
-        info: {
-            title: SERVER_TITLE,
-            version,
-            description: 'OpenAPI projection of the cachly MCP tool surface. Each path maps 1:1 onto an MCP ' +
-                'tools/call. Authenticate with a bearer token (CACHLY_JWT, a cky_ API key, or an ' +
-                'OAuth2 client_credentials access token).',
-        },
-        servers: [{ url: serverUrl }],
-        components: {
-            securitySchemes: {
-                bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
-            },
-        },
-        security: [{ bearerAuth: [] }],
-        paths,
-    };
-}
-/** Render the requested format as a pretty-printed JSON string. */
-export function renderToolSpecs(tools, format, version) {
-    switch (format) {
-        case 'openapi': return JSON.stringify(toOpenAPI(tools, version), null, 2);
-        case 'openai': return JSON.stringify({ tools: toOpenAITools(tools) }, null, 2);
-        case 'anthropic': return JSON.stringify({ tools: toAnthropicTools(tools) }, null, 2);
-        case 'langchain': return JSON.stringify({ tools: toLangChainTools(tools) }, null, 2);
-    }
-}
-//# sourceMappingURL=toolspecs.js.map
+const i="cachly AI Brain \u2014 MCP tools";function p(t){return t.map(e=>({type:"function",function:{name:e.name,description:e.description,parameters:e.inputSchema??{type:"object",properties:{}}}}))}function c(t){return t.map(e=>({name:e.name,description:e.description,input_schema:e.inputSchema??{type:"object",properties:{}}}))}function s(t){return t.map(e=>({name:e.name,description:e.description,schema:e.inputSchema??{type:"object",properties:{}}}))}function a(t,e,o="https://api.cachly.dev"){const r={};for(const n of t)r[`/mcp/tools/${n.name}`]={post:{operationId:n.name,summary:n.description.split(". ")[0],description:n.description,requestBody:{required:(n.inputSchema?.required?.length??0)>0,content:{"application/json":{schema:n.inputSchema??{type:"object",properties:{}}}}},responses:{200:{description:"Tool result (MCP content blocks).",content:{"application/json":{schema:{type:"object",properties:{content:{type:"array",items:{type:"object",properties:{type:{type:"string"},text:{type:"string"}}}}}}}}}}}};return{openapi:"3.1.0",info:{title:i,version:e,description:"OpenAPI projection of the cachly MCP tool surface. Each path maps 1:1 onto an MCP tools/call. Authenticate with a bearer token (CACHLY_JWT, a cky_ API key, or an OAuth2 client_credentials access token)."},servers:[{url:o}],components:{securitySchemes:{bearerAuth:{type:"http",scheme:"bearer",bearerFormat:"JWT"}}},security:[{bearerAuth:[]}],paths:r}}function u(t,e,o){switch(e){case"openapi":return JSON.stringify(a(t,o),null,2);case"openai":return JSON.stringify({tools:p(t)},null,2);case"anthropic":return JSON.stringify({tools:c(t)},null,2);case"langchain":return JSON.stringify({tools:s(t)},null,2)}}export{u as renderToolSpecs,c as toAnthropicTools,s as toLangChainTools,p as toOpenAITools,a as toOpenAPI};

package/dist/src/upgrade-nudge.js

@@ -1,29 +1 @@
-/**
- * Builds a plain-language upgrade nudge for a free-tier user who is close to
- * or over their monthly recall limit. Returns null when there is nothing to
- * say: an unlimited or unknown limit, or usage below 80 percent.
- *
- * Deliberately carries no price and no percentage — a number that lives in
- * two places drifts apart (see RES-017: a stale German price table quoted
- * 9/29 EUR while Stripe charged 19/49).
- */
-export function upgradeNudge({ used, limit, savedMins }) {
-    if (!Number.isFinite(limit) || limit <= 0)
-        return null;
-    if (!Number.isFinite(used))
-        return null;
-    const ratio = used / limit;
-    if (ratio < 0.8)
-        return null;
-    const remaining = Math.max(0, limit - used);
-    const unit = remaining === 1 ? 'recall' : 'recalls';
-    let text = `📈 ${remaining} ${unit} left this month on the free plan — see cachly.dev/pricing to keep going.`;
-    if (Number.isFinite(savedMins) && savedMins >= 60) {
-        const h = Math.floor(savedMins / 60);
-        const m = Math.round(savedMins % 60);
-        const timeStr = h > 0 ? `${h}h${m > 0 ? ` ${m}m` : ''}` : `${m}m`;
-        text += ` You've already saved ~${timeStr} with Brain — keep that going.`;
-    }
-    return text;
-}
-//# sourceMappingURL=upgrade-nudge.js.map
+function h({used:n,limit:t,savedMins:e}){if(!Number.isFinite(t)||t<=0||!Number.isFinite(n)||n/t<.8)return null;const i=Math.max(0,t-n);let o=`\u{1F4C8} ${i} ${i===1?"recall":"recalls"} left this month on the free plan \u2014 see cachly.dev/pricing to keep going.`;if(Number.isFinite(e)&&e>=60){const u=Math.floor(e/60),r=Math.round(e%60),a=u>0?`${u}h${r>0?` ${r}m`:""}`:`${r}m`;o+=` You've already saved ~${a} with Brain \u2014 keep that going.`}return o}export{h as upgradeNudge};

package/dist/src/utils.js

@@ -1,89 +1 @@
-// Safely parses a JSON string. Returns `fallback` on null, empty, or malformed
-// input instead of throwing a SyntaxError that would fail the entire tool call.
-export function safeJsonParse(raw, fallback) {
-    if (!raw)
-        return fallback;
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return fallback;
-    }
-}
-/**
- * Runs a promise with a hard timeout. If it doesn't settle within `ms`, resolves
- * with `fallback` instead of hanging. A memory tool must NEVER block the agent's
- * turn — a slow Redis scan or unreachable backend degrades gracefully to a fallback.
- */
-export async function withTimeout(p, ms, fallback) {
-    let timer;
-    const guard = new Promise((resolve) => {
-        timer = setTimeout(() => resolve(fallback), ms);
-    });
-    try {
-        return await Promise.race([p, guard]);
-    }
-    catch {
-        return fallback;
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
-/**
- * Collects keys matching a pattern with a hard cap and timeout. Prevents a tool
- * from hanging on a huge keyspace: stops early at `max` keys, and resolves with
- * whatever was gathered if the scan exceeds `timeoutMs`. Never rejects.
- */
-export function scanKeys(redis, pattern, opts = {}) {
-    const max = opts.max ?? 1000;
-    const timeoutMs = opts.timeoutMs ?? 3000;
-    return new Promise((resolve) => {
-        const keys = [];
-        let done = false;
-        const finish = () => { if (!done) {
-            done = true;
-            resolve(keys);
-        } };
-        const timer = setTimeout(finish, timeoutMs);
-        try {
-            const stream = redis.scanStream({ match: pattern, count: opts.count ?? 200 });
-            stream.on('data', (batch) => {
-                for (const k of batch) {
-                    keys.push(k);
-                    if (keys.length >= max) {
-                        clearTimeout(timer);
-                        finish();
-                        return;
-                    }
-                }
-            });
-            stream.on('end', () => { clearTimeout(timer); finish(); });
-            stream.on('error', () => { clearTimeout(timer); finish(); });
-        }
-        catch {
-            clearTimeout(timer);
-            finish();
-        }
-    });
-}
-/**
- * Normalizes a git path that may come from `--name-only` with rename notation,
- * e.g. `src/{old => new}/file.ts` → `src/new/file.ts`, and `a => b` → `b`.
- * Returns the post-rename path so file nodes don't fragment on renames.
- */
-export function normalizeGitPath(raw) {
-    let p = raw.trim();
-    if (!p)
-        return p;
-    // Brace rename: dir/{old => new}/file  →  dir/new/file
-    p = p.replace(/\{[^}]*=>\s*([^}]*)\}/g, (_m, after) => after.trim());
-    // Bare rename: old => new  →  new
-    const arrow = p.split('=>');
-    if (arrow.length === 2)
-        p = arrow[1].trim();
-    // Collapse any double slashes introduced by an empty rename segment.
-    return p.replace(/\/{2,}/g, '/').replace(/^\/|\/$/g, '');
-}
-//# sourceMappingURL=utils.js.map
+function h(r,t){if(!r)return t;try{return JSON.parse(r)}catch{return t}}async function p(r,t,e){let n;const o=new Promise(s=>{n=setTimeout(()=>s(e),t)});try{return await Promise.race([r,o])}catch{return e}finally{n&&clearTimeout(n)}}function T(r,t,e={}){const n=e.max??1e3,o=e.timeoutMs??3e3;return new Promise(s=>{const a=[];let m=!1;const i=()=>{m||(m=!0,s(a))},c=setTimeout(i,o);try{const u=r.scanStream({match:t,count:e.count??200});u.on("data",f=>{for(const l of f)if(a.push(l),a.length>=n){clearTimeout(c),i();return}}),u.on("end",()=>{clearTimeout(c),i()}),u.on("error",()=>{clearTimeout(c),i()})}catch{clearTimeout(c),i()}})}function y(r){let t=r.trim();if(!t)return t;t=t.replace(/\{[^}]*=>\s*([^}]*)\}/g,(n,o)=>o.trim());const e=t.split("=>");return e.length===2&&(t=e[1].trim()),t.replace(/\/{2,}/g,"/").replace(/^\/|\/$/g,"")}export{y as normalizeGitPath,h as safeJsonParse,T as scanKeys,p as withTimeout};

package/dist/src/versuch.js

@@ -1,264 +1 @@
-/**
- * Messtechnik fuer den Rueckfall-Versuch (dev.to "rules-before-the-run").
- *
- * ── Worum es geht ────────────────────────────────────────────────────────────
- *
- * Der Artikel sagt zu: wir messen, ob eine abgerufene Lektion, die WIRKLICH bis
- * ins Modell kommt, den Rueckfall senkt (dieselbe Lektion muss kein zweites Mal
- * geschrieben werden). Diese Datei baut nur das Messgeraet. Sie startet nichts.
- *
- * Ohne den Schalter `CACHLY_VERSUCH=an` (siehe `versuchStart`) aendert sich am
- * Verhalten des Recall-Pfads NICHTS — kein Zurueckhalten, kein Schreiben nach
- * Redis, keine Markierung im Text. Das ist keine Nebenbedingung, das ist der
- * ganze Zweck: der Versuch soll erst beginnen, wenn Heinrich ihn startet.
- *
- * ── Der Kanarienvogel ────────────────────────────────────────────────────────
- *
- * Zu pruefen ist nicht, ob eine Lektion ABGERUFEN wurde. Zu pruefen ist, ob ihr
- * Text VOLLSTAENDIG in der Antwort landet, die das Modell sieht. Anlass: eine
- * Lektion trug die gesuchte Adresse an Zeichen 323 von `what_worked`, die
- * Anzeige schnitt bei 100 Zeichen ab (siehe lesson-preview.ts). Die Lektion war
- * eingeblendet, der Fehler passierte trotzdem — genau der Zustand, den ein
- * "wurde abgerufen"-Zaehler nie sieht.
- *
- * Die Markierung sitzt deshalb am Ende von `what_worked` — dem Feld, an dem der
- * Anlass hing, und dem Feld, das `lessonPreviewLines` als Erstes und am
- * grosszuegigsten kuerzt. Sie besteht aus acht Zero-Width-Space-Zeichen
- * (U+200B): unsichtbar in jedem Renderer (Terminal, Markdown, HTML), und sie
- * uebersteht sowohl `flat()`s Leerzeichen-Kollaps als auch `String#trim()` —
- * beide fassen nur "richtige" Leerzeichen an, U+200B gehoert zu keiner der
- * beiden Kategorien. Acht Wiederholungen, damit ein einzelnes zufaelliges
- * Zero-Width-Zeichen in echtem Nutzertext die Markierung nicht vortaeuscht.
- *
- * WICHTIG: die Markierung wird NICHT roh ans Ende des JSON-Strings gehaengt.
- * Das wuerde `JSON.parse` in `recallVorschau` brechen und den Fallback-Pfad
- * (rohes `trimTo` ueber das GANZE JSON-Objekt) erzwingen — einen Pfad, den
- * echte, unmarkierte Lektionen nie durchlaufen. Das Ergebnis waere ein
- * Fehlalarm, kein Messwert. Die Markierung wird darum in die geparste
- * `what_worked`-Zeichenkette eingefuegt, das Objekt bleibt gueltiges JSON, und
- * der Kanarienvogel durchlaeuft exakt den Pfad, den eine echte Lektion auch
- * durchlaeuft.
- *
- * Geprueft wird am Ende die WIRKLICH zusammengebaute Antwort (`lines.join`),
- * nicht eine Nebenrechnung — siehe `schliesseVersuchAb`. Die Markierung wird
- * danach aus dem Text entfernt, bevor er den Nutzer erreicht.
- */
-import { randomBytes, createHash } from 'node:crypto';
-import { meldeEinmal, meldeUndVermerke, VERSUCH_LEER } from './aussetzer.js';
-// ── Der Schalter ─────────────────────────────────────────────────────────────
-export const VERSUCH_ENV = 'CACHLY_VERSUCH';
-export const VERSUCH_SALZ_ENV = 'CACHLY_VERSUCH_SALZ';
-/** Grund fuer `meldeEinmal`: Versuch eingeschaltet, aber kein Salz gesetzt. */
-export const OHNE_SALZ = 'versuch-ohne-salz';
-/**
- * Der einzige Einstiegspunkt fuer die Frage "soll der Versuch jetzt laufen?".
- *
- * Gibt das Salz zurueck, wenn ja — sonst `null`. Zwei Faelle enden bei `null`:
- * der Schalter steht nicht auf "an", oder er steht auf "an", aber das Salz
- * fehlt. Der zweite Fall meldet sich einmal je Prozess nach stderr (ueber
- * `meldeEinmal`) und verhaelt sich danach wie der erste — still weiterlaufen
- * waere die Fehlerklasse, gegen die `aussetzer.ts` gebaut wurde.
- */
-export function versuchStart(speicher) {
-    if (process.env[VERSUCH_ENV] !== 'an')
-        return null;
-    const salz = process.env[VERSUCH_SALZ_ENV];
-    if (!salz) {
-        const text = `${VERSUCH_ENV}=an, aber ${VERSUCH_SALZ_ENV} fehlt — der Versuch verhaelt sich wie "aus"`;
-        if (speicher) {
-            // Ohne Speicher stand die Meldung nur im Arbeitsspeicher und war nach
-            // jedem Deploy weg (Karte opupbt3l9wcq, gefunden von der Gegenrede,
-            // Rolle: Der Betreiber). Der Versuch konnte damit WOCHENLANG leer
-            // laufen: "keine Daten" sah genauso aus wie "noch nicht genug Daten".
-            //
-            // meldeUndVermerke faengt jeden eigenen Fehler ab und gibt eine
-            // Zusage zurueck, die niemand einloesen muss — deshalb `void`. Diese
-            // Funktion bleibt synchron, weil ihre Aufrufer es sind.
-            void meldeUndVermerke(speicher, VERSUCH_LEER, text);
-        }
-        else {
-            meldeEinmal(OHNE_SALZ, text);
-        }
-        return null;
-    }
-    return salz;
-}
-// ── Turn-Kennung ─────────────────────────────────────────────────────────────
-/**
- * Eine neue, stabile Kennung je Recall-Aufruf.
- *
- * Im Recall-Pfad gibt es keine vorhandene Anfrage- oder Turn-Kennung, die man
- * verlaengern koennte — `requester` ist ein Autorenname, `cachly:session:current`
- * haelt Zustand je INSTANZ, nicht je Aufruf. Darum: Zeitstempel (sortierbar,
- * in einer Zeile lesbar) plus vier zufaellige Byte, damit zwei Aufrufe in
- * derselben Millisekunde nicht kollidieren.
- */
-export function neueKennung() {
-    const zeit = new Date().toISOString().replace(/[-:.]/g, '').slice(0, 15); // 20260820T171523
-    const zufall = randomBytes(4).toString('hex');
-    return `${zeit}-${zufall}`;
-}
-/**
- * Reine Funktion, ohne Netz testbar: Kennung + Salz -> HOLD oder DELIVER.
- *
- * Berechnung exakt wie oeffentlich angekuendigt: Kennung und Salz aneinander-
- * haengen, SHA-256, die ersten VIER Hex-Ziffern als Zahl lesen, modulo 100.
- * Unter 50 heisst HOLD, sonst DELIVER.
- */
-export function zuteilung(kennung, salz) {
-    const hash = createHash('sha256').update(`${kennung}${salz}`).digest('hex');
-    const ersteVier = hash.slice(0, 4);
-    const zahl = parseInt(ersteVier, 16) % 100;
-    return zahl < 50 ? 'HOLD' : 'DELIVER';
-}
-// ── Zulassung ────────────────────────────────────────────────────────────────
-/** Ohne einen Treffer ueber dieser Punktzahl gibt es nichts zu messen. */
-export const ZULASSUNGS_SCHWELLE = 0;
-/** Gibt es ueberhaupt einen Treffer, der ueber der Schwelle liegt? */
-export function istZulassungsfaehig(hoechstePunktzahl, schwelle = ZULASSUNGS_SCHWELLE) {
-    return hoechstePunktzahl > schwelle;
-}
-/** Der Grund, warum eine Anfrage NICHT zulassungsfaehig ist — oder `undefined`. */
-export function zulassungsGrund(hoechstePunktzahl, schwelle = ZULASSUNGS_SCHWELLE) {
-    if (istZulassungsfaehig(hoechstePunktzahl, schwelle))
-        return undefined;
-    return `hoechste Punktzahl ${hoechstePunktzahl.toFixed(3)} liegt nicht ueber der Schwelle ${schwelle}`;
-}
-// ── Kanarienvogel ────────────────────────────────────────────────────────────
-/**
- * Acht Zero-Width-Spaces. Siehe Dateikopf fuer die Begruendung der Wahl.
- *
- * Ueber String.fromCharCode, nicht als roher Unicode-Buchstabe im
- * Quelltext — ein unsichtbares Zeichen zwischen Anfuehrungszeichen ist beim
- * Lesen und in `git diff` nicht von "kein Zeichen" zu unterscheiden.
- */
-export const KANARIEN_MARKIERUNG = String.fromCharCode(0x200b).repeat(8);
-/**
- * Setzt die Kanarien-Markierung ans Ende des `what_worked`-Feldes.
- *
- * `inhalt` ist der rohe Redis-Wert, wie ihn `recallVorschau` bekommt — meist
- * das JSON einer Lektion, manchmal (Kontext-Eintraege, Index) einfacher Text.
- * Ist es eine Lektion mit `what_worked`, wandert die Markierung dorthin und
- * das Objekt bleibt gueltiges JSON (Begruendung siehe Dateikopf). Sonst wird
- * roh ans Ende angehaengt — das ist fuer Nicht-Lektionen korrekt, weil
- * `recallVorschau` sie ohnehin nur als Rohtext kuerzt.
- */
-export function markiereDatensatz(inhalt, markierung = KANARIEN_MARKIERUNG) {
-    try {
-        const objekt = JSON.parse(inhalt);
-        if (typeof objekt.what_worked === 'string') {
-            objekt.what_worked = `${objekt.what_worked}${markierung}`;
-            return JSON.stringify(objekt);
-        }
-    }
-    catch {
-        // kein JSON — Markierung ans Ende des Rohtexts, siehe unten
-    }
-    return `${inhalt}${markierung}`;
-}
-/**
- * Ueberlebt die Markierung in der fertig zusammengebauten Antwort?
- *
- * Ueberlebt sie: der ganze Datensatz kam durch. Fehlt sie: er wurde gekuerzt.
- */
-export function kanarienUeberlebt(fertigeAntwort, markierung = KANARIEN_MARKIERUNG) {
-    return fertigeAntwort.includes(markierung);
-}
-/** Entfernt die Markierung, bevor der Text den Nutzer erreicht. */
-export function entferneMarkierung(text, markierung = KANARIEN_MARKIERUNG) {
-    return text.split(markierung).join('');
-}
-// ── Themenschluessel ─────────────────────────────────────────────────────────
-const LEKTION_PRAEFIX = 'cachly:lesson:best:';
-/** Redis-Schluessel einer Lektion -> ihr Themenname (ohne Praefix). */
-export function themaVon(key) {
-    return key.startsWith(LEKTION_PRAEFIX) ? key.slice(LEKTION_PRAEFIX.length) : key;
-}
-// ── Protokoll je Turn ────────────────────────────────────────────────────────
-/** Hash der Frage — die Frage selbst wird nie gespeichert (Zusage des Artikels). */
-export function hashFrage(frage) {
-    return createHash('sha256').update(frage).digest('hex');
-}
-const TURN_TTL_SEKUNDEN = 90 * 24 * 60 * 60; // 90 Tage — der Versuch dauert 14
-/** Redis-Schluessel fuer den Protokoll-Eintrag einer Kennung. */
-export function turnSchluessel(kennung) {
-    return `cachly:versuch:turn:${kennung}`;
-}
-/**
- * Schreibt den Turn-Eintrag. Schlaegt das fehl, wird NICHTS geworfen — der
- * Nutzer wartet auf eine Antwort, nicht auf ein Protokoll.
- */
-export async function schreibeTurnProtokoll(redis, kennung, protokoll) {
-    try {
-        await redis.set(turnSchluessel(kennung), JSON.stringify(protokoll), 'EX', TURN_TTL_SEKUNDEN);
-    }
-    catch {
-        // Ein fehlendes Protokoll ist besser als eine gescheiterte Suche.
-    }
-}
-/**
- * Wendet Zulassung + Zuteilung auf eine Trefferliste an. Reine Funktion,
- * mutiert `treffer` nicht.
- *
- * Ohne zulassungsfaehigen Treffer passiert nichts — Zuteilung wird trotzdem
- * berechnet und protokolliert, aber es gibt nichts zurueckzuhalten oder zu
- * markieren. Bei HOLD verschwindet der beste Treffer aus der Liste, die
- * uebrigen bleiben unveraendert. Bei DELIVER traegt der beste Treffer danach
- * die Kanarien-Markierung.
- */
-export function wendeZuteilungAn(treffer, kennung, salz, hoechstePunktzahl, schwelle = ZULASSUNGS_SCHWELLE) {
-    const zulassungsfaehig = istZulassungsfaehig(hoechstePunktzahl, schwelle);
-    const grund = zulassungsGrund(hoechstePunktzahl, schwelle);
-    const entscheidung = zuteilung(kennung, salz);
-    if (!zulassungsfaehig || treffer.length === 0) {
-        return {
-            treffer: [...treffer],
-            zuteilung: entscheidung,
-            zulassungsfaehig,
-            zulassungsGrund: grund,
-            markierungGesetzt: false,
-        };
-    }
-    const [bester, ...rest] = treffer;
-    if (entscheidung === 'HOLD') {
-        return {
-            treffer: rest,
-            zuteilung: entscheidung,
-            zulassungsfaehig,
-            zulassungsGrund: grund,
-            markierungGesetzt: false,
-            weggelassenesThema: themaVon(bester.key),
-        };
-    }
-    const markiert = { ...bester, content: markiereDatensatz(bester.content) };
-    return {
-        treffer: [markiert, ...rest],
-        zuteilung: entscheidung,
-        zulassungsfaehig,
-        zulassungsGrund: grund,
-        markierungGesetzt: true,
-    };
-}
-/**
- * Letzter Schritt: prueft den Kanarienvogel gegen die WIRKLICH zusammen-
- * gebaute Antwort, entfernt die Markierung, schreibt das Protokoll (fire-and-
- * forget) und gibt den bereinigten Text zurueck — den, den der Nutzer sieht.
- */
-export function schliesseVersuchAb(redis, kennung, teil, fertigeAntwort) {
-    const kanarienBestanden = teil.markierungGesetzt ? kanarienUeberlebt(fertigeAntwort) : false;
-    const bereinigt = entferneMarkierung(fertigeAntwort);
-    const protokoll = {
-        ts: new Date().toISOString(),
-        frageHash: hashFrage(teil.frage),
-        hoechstePunktzahl: teil.hoechstePunktzahl,
-        themen: teil.themen,
-        zulassungsfaehig: teil.zulassungsfaehig,
-        zulassungsGrund: teil.zulassungsGrund,
-        zuteilung: teil.zuteilung,
-        weggelassenesThema: teil.weggelassenesThema,
-        kanarienBestanden,
-    };
-    void schreibeTurnProtokoll(redis, kennung, protokoll);
-    return bereinigt;
-}
-//# sourceMappingURL=versuch.js.map
+import{randomBytes as x,createHash as l}from"node:crypto";import{meldeEinmal as S,meldeUndVermerke as m,VERSUCH_LEER as E}from"./aussetzer.js";const f="CACHLY_VERSUCH",p="CACHLY_VERSUCH_SALZ",k="versuch-ohne-salz";function O(e){if(process.env[f]!=="an")return null;const t=process.env[p];if(!t){const n=`${f}=an, aber ${p} fehlt \u2014 der Versuch verhaelt sich wie "aus"`;return e?m(e,E,n):S(k,n),null}return t}function v(){const e=new Date().toISOString().replace(/[-:.]/g,"").slice(0,15),t=x(4).toString("hex");return`${e}-${t}`}function _(e,t){const r=l("sha256").update(`${e}${t}`).digest("hex").slice(0,4);return parseInt(r,16)%100<50?"HOLD":"DELIVER"}const c=0;function d(e,t=c){return e>t}function L(e,t=c){if(!d(e,t))return`hoechste Punktzahl ${e.toFixed(3)} liegt nicht ueber der Schwelle ${t}`}const g="\u200B".repeat(8);function N(e,t=g){try{const n=JSON.parse(e);if(typeof n.what_worked=="string")return n.what_worked=`${n.what_worked}${t}`,JSON.stringify(n)}catch{}return`${e}${t}`}function H(e,t=g){return e.includes(t)}function V(e,t=g){return e.split(t).join("")}const z="cachly:lesson:best:";function $(e){return e.startsWith(z)?e.slice(z.length):e}function w(e){return l("sha256").update(e).digest("hex")}const C=2160*60*60;function G(e){return`cachly:versuch:turn:${e}`}async function R(e,t,n){try{await e.set(G(t),JSON.stringify(n),"EX",C)}catch{}}function y(e,t,n,r,u=c){const s=d(r,u),o=L(r,u),a=_(t,n);if(!s||e.length===0)return{treffer:[...e],zuteilung:a,zulassungsfaehig:s,zulassungsGrund:o,markierungGesetzt:!1};const[i,...h]=e;return a==="HOLD"?{treffer:h,zuteilung:a,zulassungsfaehig:s,zulassungsGrund:o,markierungGesetzt:!1,weggelassenesThema:$(i.key)}:{treffer:[{...i,content:N(i.content)},...h],zuteilung:a,zulassungsfaehig:s,zulassungsGrund:o,markierungGesetzt:!0}}function I(e,t,n,r){const u=n.markierungGesetzt?H(r):!1,s=V(r),o={ts:new Date().toISOString(),frageHash:w(n.frage),hoechstePunktzahl:n.hoechstePunktzahl,themen:n.themen,zulassungsfaehig:n.zulassungsfaehig,zulassungsGrund:n.zulassungsGrund,zuteilung:n.zuteilung,weggelassenesThema:n.weggelassenesThema,kanarienBestanden:u};return R(e,t,o),s}export{g as KANARIEN_MARKIERUNG,k as OHNE_SALZ,f as VERSUCH_ENV,p as VERSUCH_SALZ_ENV,c as ZULASSUNGS_SCHWELLE,V as entferneMarkierung,w as hashFrage,d as istZulassungsfaehig,H as kanarienUeberlebt,N as markiereDatensatz,v as neueKennung,I as schliesseVersuchAb,R as schreibeTurnProtokoll,$ as themaVon,G as turnSchluessel,O as versuchStart,y as wendeZuteilungAn,L as zulassungsGrund,_ as zuteilung};

package/dist/src/vorspann.js

@@ -1,146 +1 @@
-/**
- * Der Vorspann einer Lektion — die ersten 100 Zeichen, und nur die.
- *
- * GEMESSEN am 16.08.2026: Das Session-Briefing zeigt je Lektion rund 100
- * Zeichen. In `node4:einrichtung-contabo-und-fallen` stand die gesuchte
- * Adresse `10.8.0.7` an Zeichen 323, und die passende Warnung im Feld
- * `what_failed`, das im Briefing gar nicht erscheint. Die Lektion war
- * eingeblendet. Der Fehler passierte trotzdem.
- *
- * Die Abhilfe war eine SCHREIBREGEL, kein Codefix: die entscheidende Tatsache
- * gehoert in die ersten 100 Zeichen — die Zahl, die Adresse, der Befehl. Nicht
- * der Anlass, nicht die Ausstattung, nicht die Vorgeschichte.
- *
- * Eine Regel, die kein Skript prueft, ist aber kein Gesetz, sondern ein
- * Wunsch. Dieses Modul prueft sie — im Moment des Schreibens, wo der Autor
- * (Mensch oder Agent) die Lektion noch in der Hand hat.
- *
- * Bewusst ein HINWEIS und keine Ablehnung: es gibt Lektionen ohne harte Zahl
- * (eine Entscheidung, eine Richtung), und eine abgelehnte Lektion ist immer
- * schlechter als eine unscharf formulierte.
- */
-/** So viel sieht die naechste Sitzung im Briefing. Gemessen, nicht geschaetzt. */
-export const VORSPANN_ZEICHEN = 100;
-/**
- * Was als "harte Tatsache" zaehlt.
- *
- * Jedes Muster steht fuer etwas, das man beim naechsten Mal ABSCHREIBEN will
- * und nicht neu herausfinden: eine Adresse, ein Port, eine Zahl mit Einheit,
- * ein Pfad, ein Befehl, eine Version, ein Schluessel-Wert-Paar.
- */
-const HARTE_MUSTER = [
-    { name: 'IP-Adresse', re: /\b\d{1,3}(?:\.\d{1,3}){3}\b/ },
-    { name: 'Port', re: /:\d{2,5}\b/ },
-    { name: 'Zahl', re: /\b\d+(?:[.,]\d+)?\s*(?:%|s|ms|m|h|d|MB|GB|TB|KB|k|x|×|EUR|€|\$)?\b/ },
-    { name: 'Pfad', re: /(?:^|\s)(?:\/[\w.-]+){2,}|[A-Za-z]:\\[\w\\.-]+/ },
-    { name: 'Befehl oder Datei', re: /`[^`]+`|\b[\w-]+\.(?:ts|tsx|go|js|mjs|py|sh|yml|yaml|json|sql|env)\b/ },
-    // Ein Name in Grossbuchstaben mit mindestens zwei Unterstrichen ist in der
-    // Praxis immer eine Umgebungsvariable oder ein Schalter — also etwas zum
-    // Abschreiben. Zwei Unterstriche, damit nicht jedes betonte Wort greift.
-    // Der Doppelpunkt ist bewusst NICHT dabei. Er war zuerst erlaubt, und die
-    // Gegenprobe fing sofort den Fehlalarm: "WICHTIG:" ist ein betontes Wort,
-    // keine Angabe. Bleibt das Gleichheitszeichen (PORT=3095) und der Name mit
-    // mindestens zwei Unterstrichen, der in der Praxis immer eine
-    // Umgebungsvariable ist.
-    { name: 'Schluessel', re: /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+){2,}\b|\b[A-Z][A-Z0-9_]{3,}\s*=/ },
-    { name: 'Version', re: /\bv?\d+\.\d+(?:\.\d+)?\b/ },
-];
-/**
- * Steht im Vorspann ein abgeschlossener Gedanke?
- *
- * Mechanisch, nicht inhaltlich: gesucht wird ein Satzende (Punkt, Semikolon,
- * Ausrufe- oder Fragezeichen) innerhalb der ersten 100 Zeichen. Findet sich
- * keines, endet der Vorspann mitten im Satz.
- *
- * Absichtlich KEINE Bedeutungspruefung. Ein Waechter, der raet, ob ein Satz
- * "vollstaendig genug" ist, schlaegt bei jeder zweiten Lektion falschen Alarm
- * — und ein Waechter, der zu oft Nein sagt, wird abgeschaltet. Ein fehlendes
- * Satzzeichen ist dagegen eine Tatsache.
- *
- * Ein Text, der insgesamt kuerzer ist als der Vorspann, gilt NICHT als
- * abgeschnitten: dort steht alles, was es gibt.
- */
-function endetMittenImSatz(text) {
-    if (text.length <= VORSPANN_ZEICHEN)
-        return false;
-    const vorspann = text.slice(0, VORSPANN_ZEICHEN);
-    // Zwei Feinheiten, beide am echten Fall gelernt:
-    //
-    // 1. Ein Punkt in "10.8.0.7" oder "v1.2" beendet keinen Satz — deshalb muss
-    //    auf das Satzzeichen ein Leerzeichen oder das Textende folgen.
-    // 2. Der DOPPELPUNKT zaehlt NICHT. Er leitet ein, er schliesst nicht ab.
-    //    Genau daran scheiterte die erste Fassung: "GEMESSEN 19.08.2026: 109
-    //    Testdateien ... 13 davon GRUEN weil" galt als abgeschlossen, weil der
-    //    Doppelpunkt nach dem Datum mitzaehlte. Der Satz endet dort aber nicht,
-    //    er faengt an.
-    return !/[.;!?](?:\s|$)/.test(vorspann);
-}
-/** Frueheste Fundstelle irgendeines harten Musters, oder -1. */
-function ersteFundstelle(text) {
-    let best = -1;
-    for (const m of HARTE_MUSTER) {
-        const treffer = m.re.exec(text);
-        if (!treffer)
-            continue;
-        const i = treffer.index;
-        if (best === -1 || i < best)
-            best = i;
-    }
-    return best;
-}
-/**
- * Prueft den Vorspann von `what_worked`.
- *
- * Leerer oder fehlender Text ergibt einen Befund ohne Tatsache und ohne
- * "steht spaeter" — es gibt dann nichts umzustellen, sondern nichts zu lesen.
- */
-export function pruefeVorspann(whatWorked) {
-    const text = typeof whatWorked === 'string' ? whatWorked : '';
-    const vorspann = text.slice(0, VORSPANN_ZEICHEN);
-    const gefunden = HARTE_MUSTER.filter(m => m.re.test(vorspann)).map(m => m.name);
-    const ersteTatsacheBei = ersteFundstelle(text);
-    return {
-        vorspann,
-        traegtTatsache: gefunden.length > 0,
-        gefunden,
-        tatsacheStehtSpaeter: gefunden.length === 0 && ersteTatsacheBei >= VORSPANN_ZEICHEN,
-        ersteTatsacheBei,
-        abgeschnitten: endetMittenImSatz(text),
-    };
-}
-/**
- * Ein Satz fuer den Autor — oder null, wenn alles in Ordnung ist.
- *
- * Der Hinweis nennt die POSITION, wenn die Tatsache nur zu weit hinten steht.
- * Ohne Zahl waere er eine Ermahnung; mit Zahl ist er eine Anweisung, die man
- * in zehn Sekunden befolgen kann.
- */
-export function vorspannHinweis(whatWorked) {
-    const b = pruefeVorspann(whatWorked);
-    if (!b.vorspann.trim())
-        return null;
-    /*
-     * Die Zahl ist da, aber der Satz ist es nicht.
-     *
-     * Dieser Fall kam am 19.08.2026 dazu und ist der feinere: die alte Pruefung
-     * war zufrieden, weil drei Zahlen in den ersten 100 Zeichen standen — und
-     * genau bei "weil" war Schluss. Zahlen ohne ihre Wirkung sind im Briefing
-     * kein Wissen, sondern ein Raetsel.
-     */
-    if (b.traegtTatsache && b.abgeschnitten) {
-        return (`📏 **Der Vorspann endet mitten im Satz** — die Zahl steht vorn, ihre Wirkung nicht. ` +
-            `Das Briefing der nächsten Sitzung bricht bei ${VORSPANN_ZEICHEN} Zeichen ab und zeigt dann ` +
-            `eine Zahl ohne Bedeutung. Ein abgeschlossener Satz in den ersten ${VORSPANN_ZEICHEN} Zeichen ` +
-            `genügt: nicht „13 davon grün weil", sondern „13 Wächter waren grün, ohne etwas zu prüfen."`);
-    }
-    if (b.traegtTatsache)
-        return null;
-    if (b.tatsacheStehtSpaeter) {
-        return (`📏 **Die entscheidende Tatsache steht bei Zeichen ${b.ersteTatsacheBei}** — das Briefing der nächsten ` +
-            `Sitzung endet bei ${VORSPANN_ZEICHEN}. Stell die Zahl, Adresse oder den Befehl an den Anfang von ` +
-            `\`what_worked\`; die Vorgeschichte gehört ans Ende oder in \`context\`.`);
-    }
-    return (`📏 **In den ersten ${VORSPANN_ZEICHEN} Zeichen steht keine Zahl, Adresse oder Befehl** — nur so viel sieht ` +
-        `die nächste Sitzung im Briefing. Trägt diese Lektion eine harte Tatsache, gehört sie nach vorn.`);
-}
-//# sourceMappingURL=vorspann.js.map
+const d=100,a=[{name:"IP-Adresse",re:/\b\d{1,3}(?:\.\d{1,3}){3}\b/},{name:"Port",re:/:\d{2,5}\b/},{name:"Zahl",re:/\b\d+(?:[.,]\d+)?\s*(?:%|s|ms|m|h|d|MB|GB|TB|KB|k|x|×|EUR|€|\$)?\b/},{name:"Pfad",re:/(?:^|\s)(?:\/[\w.-]+){2,}|[A-Za-z]:\\[\w\\.-]+/},{name:"Befehl oder Datei",re:/`[^`]+`|\b[\w-]+\.(?:ts|tsx|go|js|mjs|py|sh|yml|yaml|json|sql|env)\b/},{name:"Schluessel",re:/\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+){2,}\b|\b[A-Z][A-Z0-9_]{3,}\s*=/},{name:"Version",re:/\bv?\d+\.\d+(?:\.\d+)?\b/}];function h(n){if(n.length<=100)return!1;const e=n.slice(0,100);return!/[.;!?](?:\s|$)/.test(e)}function c(n){let e=-1;for(const s of a){const t=s.re.exec(n);if(!t)continue;const r=t.index;(e===-1||r<e)&&(e=r)}return e}function o(n){const e=typeof n=="string"?n:"",s=e.slice(0,100),t=a.filter(i=>i.re.test(s)).map(i=>i.name),r=c(e);return{vorspann:s,traegtTatsache:t.length>0,gefunden:t,tatsacheStehtSpaeter:t.length===0&&r>=100,ersteTatsacheBei:r,abgeschnitten:h(e)}}function l(n){const e=o(n);return e.vorspann.trim()?e.traegtTatsache&&e.abgeschnitten?'\u{1F4CF} **Der Vorspann endet mitten im Satz** \u2014 die Zahl steht vorn, ihre Wirkung nicht. Das Briefing der n\xE4chsten Sitzung bricht bei 100 Zeichen ab und zeigt dann eine Zahl ohne Bedeutung. Ein abgeschlossener Satz in den ersten 100 Zeichen gen\xFCgt: nicht \u201E13 davon gr\xFCn weil", sondern \u201E13 W\xE4chter waren gr\xFCn, ohne etwas zu pr\xFCfen."':e.traegtTatsache?null:e.tatsacheStehtSpaeter?`\u{1F4CF} **Die entscheidende Tatsache steht bei Zeichen ${e.ersteTatsacheBei}** \u2014 das Briefing der n\xE4chsten Sitzung endet bei 100. Stell die Zahl, Adresse oder den Befehl an den Anfang von \`what_worked\`; die Vorgeschichte geh\xF6rt ans Ende oder in \`context\`.`:"\u{1F4CF} **In den ersten 100 Zeichen steht keine Zahl, Adresse oder Befehl** \u2014 nur so viel sieht die n\xE4chste Sitzung im Briefing. Tr\xE4gt diese Lektion eine harte Tatsache, geh\xF6rt sie nach vorn.":null}export{d as VORSPANN_ZEICHEN,o as pruefeVorspann,l as vorspannHinweis};