@cachly-dev/mcp-server 0.10.116 → 0.10.118

package/dist/src/ambient-hooks.js

@@ -0,0 +1,269 @@
+// Ambient Recall (Phase 4) — Claude Code hook-script generators.
+//
+// Builds the SessionStart + UserPromptSubmit hook scripts (and the
+// .claude/settings.json fragment that wires them) so recall is PUSHED into
+// context automatically, without the agent having to remember to call it
+// (roadmap §6.1). This is the packaging that turns cachly's existing recall
+// into "memory that is just there".
+//
+// Design mirrors cls-hook.ts:
+//   • Pure string builders — exhaustively unit-tested.
+//   • No untrusted input is interpolated into the script; the hook payload
+//     (which contains the user's prompt) is piped to the CLI on stdin, never
+//     spliced into shell/JS source.
+//   • Versioned so installers can upgrade old hooks in place.
+//   • Graceful: a crashing hook must NEVER block the agent — every path exits 0
+//     with no output, so Claude Code simply proceeds without the extra context
+//     (§6.3 guardrail 5).
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, chmod, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/**
+ * Bumped whenever a hook script changes so installers can upgrade old hooks.
+ * v3: hooks became Node scripts (.mjs) invoked as `node "<path>"` — the
+ * cross-platform shape from the Claude Code hooks guide. The v1/v2 POSIX shell
+ * scripts silently never ran on native Windows (no /bin/sh); Node is already a
+ * hard requirement of this package, so the hook now runs identically on
+ * Windows, macOS and Linux.
+ */
+export const AMBIENT_HOOK_VERSION = 'v3';
+/**
+ * The CLI subcommand the hooks pipe their payload to. It reads the hook JSON on
+ * stdin, runs smart_recall through the relevance gate (ambient-recall.ts), and
+ * prints the `hookSpecificOutput` JSON Claude Code injects as additionalContext.
+ * The CLI self-limits its latency budget (§6.3 guardrail 4). See ambient-cli.ts.
+ */
+export const AMBIENT_CLI_SUBCOMMAND = 'ambient-recall';
+const DEFAULT_CLI = `npx @cachly-dev/mcp-server@latest ${AMBIENT_CLI_SUBCOMMAND}`;
+/** Escape a value for embedding inside a single-quoted JS string literal. */
+function jsString(s) {
+    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+function buildHook(event, opts) {
+    const cli = opts.cliCommand ?? DEFAULT_CLI;
+    return [
+        `#!/usr/bin/env node`,
+        `// cachly Ambient Recall — ${event} ${AMBIENT_HOOK_VERSION}`,
+        `// Pushes relevant memory into context automatically. Cross-platform Node hook`,
+        `// (no shell script — runs identically on Windows/macOS/Linux). Never blocks`,
+        `// the agent: every failure path exits 0 with no output (graceful degrade).`,
+        `import { spawn } from 'node:child_process';`,
+        `process.env.CACHLY_BRAIN_INSTANCE_ID = '${jsString(opts.instanceId)}';`,
+        ...(opts.apiKey ? [`process.env.CACHLY_JWT = '${jsString(opts.apiKey)}';`] : []),
+        `process.env.CACHLY_HOOK_EVENT = '${jsString(event)}';`,
+        `try {`,
+        // Claude Code delivers the hook payload as JSON on stdin; stdio 'inherit'
+        // hands it verbatim to the CLI (no re-parsing of prompt content), and the
+        // CLI's hookSpecificOutput JSON flows straight back to Claude Code on
+        // stdout. shell:true resolves npx/npx.cmd on every platform; stderr is
+        // discarded so a noisy npm can never corrupt the hook protocol.
+        `  const child = spawn('${jsString(cli)}', { shell: true, stdio: ['inherit', 'inherit', 'ignore'] });`,
+        `  child.on('error', () => process.exit(0));`,
+        `  child.on('close', () => process.exit(0));`,
+        `} catch {`,
+        `  process.exit(0);`,
+        `}`,
+    ].join('\n');
+}
+/**
+ * SessionStart hook: emits the session briefing as additionalContext at the
+ * start of every session — the automatic replacement for "the agent should call
+ * session_start".
+ */
+export function buildSessionStartHook(opts) {
+    return buildHook('SessionStart', opts);
+}
+/**
+ * UserPromptSubmit hook — the core of Ambient Recall. Runs before every user
+ * message, recalls on the prompt through the relevance gate, and pushes gated
+ * hits into context. This is the most-forgotten call, made automatic.
+ */
+export function buildUserPromptSubmitHook(opts) {
+    return buildHook('UserPromptSubmit', opts);
+}
+/**
+ * PreToolUse hook (Ausbau) — file-open briefing. Fires before Edit/Write-class
+ * tools (settings matcher `Edit|Write|MultiEdit`); the CLI recalls file-scoped
+ * lessons and injects them as additionalContext — the automatic "prüf mal, ob's
+ * zu dieser Datei Lessons gibt" (roadmap §6.1).
+ */
+export function buildPreToolUseHook(opts) {
+    return buildHook('PreToolUse', opts);
+}
+/**
+ * Stop hook (Ausbau) — auto-learn. After a turn whose final message carries a
+ * clear fix signal, the CLI feeds one observation to auto_learn_session — the
+ * automatic replacement for the forgotten `learn_from_attempts` call.
+ */
+export function buildStopHook(opts) {
+    return buildHook('Stop', opts);
+}
+// Per-event latency budgets (seconds). The CLI self-limits recall to 3s; these
+// are the outer safety net so a wedged npx can never stall a turn for long.
+const EVENT_TIMEOUTS = {
+    SessionStart: 30,
+    UserPromptSubmit: 10,
+    PreToolUse: 10,
+    Stop: 60, // auto-learn may do a real write; Stop is not latency-critical
+};
+/** Matcher for the PreToolUse briefing: only file-mutating tools. */
+export const PRE_TOOL_USE_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+/**
+ * Build the `.claude/settings.json` `hooks` fragment that wires the scripts.
+ * The caller merges this into the user's existing settings (never overwrites).
+ * Shape matches Claude Code's hooks config: an array of matcher groups, each
+ * with a list of `{ type: "command", command, timeout }` entries.
+ */
+export function buildAmbientSettingsHooks(paths) {
+    // v3: the command is `node "<script>"` — a plain string that both /bin/sh
+    // (macOS/Linux, Windows+Git-Bash) and PowerShell (native Windows fallback)
+    // execute identically, so one settings shape covers every platform.
+    const entry = (event, scriptPath, matcher) => ({
+        ...(matcher ? { matcher } : {}),
+        hooks: [{ type: 'command', command: `node "${scriptPath}"`, timeout: EVENT_TIMEOUTS[event] }],
+    });
+    const frag = {
+        SessionStart: [entry('SessionStart', paths.sessionStart)],
+        UserPromptSubmit: [entry('UserPromptSubmit', paths.userPromptSubmit)],
+    };
+    if (paths.preToolUse)
+        frag.PreToolUse = [entry('PreToolUse', paths.preToolUse, PRE_TOOL_USE_MATCHER)];
+    if (paths.stop)
+        frag.Stop = [entry('Stop', paths.stop)];
+    return frag;
+}
+// ── Installer ────────────────────────────────────────────────────────────────
+// Writes the two hook scripts into `.claude/hooks/` and merges the settings
+// fragment into `.claude/settings.json`. Idempotent and non-destructive:
+//   • re-running upgrades the scripts in place (version marker) and never
+//     duplicates a settings entry that already points at our script,
+//   • foreign hooks in the user's settings are preserved (we append, never
+//     overwrite the arrays).
+// Never throws — returns a status the caller can log.
+const HOOK_DIR = '.claude/hooks';
+const SETTINGS_FILE = '.claude/settings.json';
+/** Script filename per event — shared marker `cachly-ambient-` drives upgrades. */
+const SCRIPT_NAMES = {
+    SessionStart: 'cachly-ambient-session-start.mjs',
+    UserPromptSubmit: 'cachly-ambient-prompt-submit.mjs',
+    PreToolUse: 'cachly-ambient-pre-tool.mjs',
+    Stop: 'cachly-ambient-stop.mjs',
+};
+const AMBIENT_SCRIPT_MARKER = '.claude/hooks/cachly-ambient-';
+/** True when this matcher group only wires cachly-ambient scripts. */
+function isAmbientGroup(g, currentPaths) {
+    const hooks = g.hooks ?? [];
+    return (hooks.length > 0 &&
+        hooks.every((h) => {
+            const cmd = h.command ?? '';
+            // Matches v1/v2 entries (bare script path), v3 entries (`node "<path>"`),
+            // and marker-less test/custom paths passed as the current fragment.
+            return (cmd.includes(AMBIENT_SCRIPT_MARKER) ||
+                currentPaths.has(cmd) ||
+                [...currentPaths].some((p) => cmd.includes(`"${p}"`)));
+        }));
+}
+/**
+ * Merge our hook entries into an existing settings object without disturbing
+ * anything else. Idempotent AND upgrade-safe: existing cachly-ambient groups
+ * (from any prior version/paths) are replaced by the current fragment rather
+ * than accumulated; foreign groups are always preserved. Pure — unit-tested.
+ */
+export function mergeAmbientSettings(existing, paths) {
+    const next = { ...existing, hooks: { ...(existing.hooks ?? {}) } };
+    const hooks = next.hooks;
+    const fragment = buildAmbientSettingsHooks(paths);
+    const currentPaths = new Set([paths.sessionStart, paths.userPromptSubmit, paths.preToolUse, paths.stop].filter((p) => !!p));
+    for (const [event, ourGroups] of Object.entries(fragment)) {
+        const foreign = (Array.isArray(hooks[event]) ? hooks[event] : []).filter((g) => !isAmbientGroup(g, currentPaths));
+        hooks[event] = [...foreign, ...ourGroups];
+    }
+    const changed = JSON.stringify(next) !== JSON.stringify(existing);
+    return { settings: next, changed };
+}
+/**
+ * Install/upgrade the Ambient Recall hooks in `projectDir`. Best-effort:
+ * a filesystem error surfaces as a thrown error only for the top-level caller,
+ * which wraps it in try/catch (the git-hook feature is non-critical).
+ */
+export async function installAmbientHooks(projectDir, instanceId, apiKey, options = {}) {
+    const hookDir = resolve(projectDir, HOOK_DIR);
+    await mkdir(hookDir, { recursive: true });
+    const opts = { instanceId, apiKey };
+    const events = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'Stop'];
+    const scriptFor = {
+        SessionStart: buildSessionStartHook(opts),
+        UserPromptSubmit: buildUserPromptSubmitHook(opts),
+        PreToolUse: buildPreToolUseHook(opts),
+        Stop: buildStopHook(opts),
+    };
+    const pathFor = (e) => resolve(hookDir, SCRIPT_NAMES[e]);
+    const readIf = async (p) => {
+        try {
+            return await readFile(p, 'utf-8');
+        }
+        catch {
+            return '';
+        }
+    };
+    let anyExisting = false;
+    let allCurrent = true;
+    for (const e of events) {
+        const prev = await readIf(pathFor(e));
+        if (prev)
+            anyExisting = true;
+        if (prev !== scriptFor[e] + '\n')
+            allCurrent = false;
+    }
+    const scripts = allCurrent ? 'unchanged' : anyExisting ? 'upgraded' : 'written';
+    if (scripts !== 'unchanged') {
+        for (const e of events) {
+            await writeFile(pathFor(e), scriptFor[e] + '\n', 'utf-8');
+            await chmod(pathFor(e), 0o755).catch(() => { });
+        }
+    }
+    // Merge the settings fragment (upgrade-safe: prior ambient groups replaced).
+    const settingsPath = resolve(projectDir, SETTINGS_FILE);
+    const settingsExisted = existsSync(settingsPath);
+    let existingSettings = {};
+    if (settingsExisted) {
+        try {
+            existingSettings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+        }
+        catch {
+            existingSettings = {};
+        } // corrupt/empty file → start fresh (still non-destructive to hooks we add)
+    }
+    // Portable installs (committed hooks) reference $CLAUDE_PROJECT_DIR so the
+    // settings work at any checkout location; local installs use absolute paths.
+    // These are SCRIPT PATHS — buildAmbientSettingsHooks wraps them as
+    // `node "<path>"`, so the portable var sits inside the double quotes and is
+    // expanded by the shell at hook time.
+    const commandFor = (e) => options.portable ? `$CLAUDE_PROJECT_DIR/${HOOK_DIR}/${SCRIPT_NAMES[e]}` : pathFor(e);
+    const { settings, changed } = mergeAmbientSettings(existingSettings, {
+        sessionStart: commandFor('SessionStart'),
+        userPromptSubmit: commandFor('UserPromptSubmit'),
+        preToolUse: commandFor('PreToolUse'),
+        stop: commandFor('Stop'),
+    });
+    let settingsStatus;
+    if (!settingsExisted)
+        settingsStatus = 'written';
+    else if (!changed)
+        settingsStatus = 'unchanged';
+    else
+        settingsStatus = 'merged';
+    if (settingsStatus !== 'unchanged') {
+        await mkdir(resolve(projectDir, '.claude'), { recursive: true });
+        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    }
+    return {
+        sessionStartPath: pathFor('SessionStart'),
+        promptSubmitPath: pathFor('UserPromptSubmit'),
+        preToolUsePath: pathFor('PreToolUse'),
+        stopPath: pathFor('Stop'),
+        scripts,
+        settings: settingsStatus,
+    };
+}
+//# sourceMappingURL=ambient-hooks.js.map

package/dist/src/ambient-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient-hooks.js","sourceRoot":"","sources":["../../src/ambient-hooks.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,mEAAmE;AACnE,2EAA2E;AAC3E,yEAAyE;AACzE,4EAA4E;AAC5E,oCAAoC;AACpC,EAAE;AACF,8BAA8B;AAC9B,uDAAuD;AACvD,2EAA2E;AAC3E,6EAA6E;AAC7E,oCAAoC;AACpC,8DAA8D;AAC9D,gFAAgF;AAChF,+EAA+E;AAC/E,0BAA0B;AAE1B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;AAgBvD,MAAM,WAAW,GAAG,qCAAqC,sBAAsB,EAAE,CAAC;AAElF,6EAA6E;AAC7E,SAAS,QAAQ,CAAC,CAAS;IACzB,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,SAAS,CAAC,KAAuB,EAAE,IAAwB;IAClE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,WAAW,CAAC;IAC3C,OAAO;QACL,qBAAqB;QACrB,8BAA8B,KAAK,IAAI,oBAAoB,EAAE;QAC7D,gFAAgF;QAChF,8EAA8E;QAC9E,6EAA6E;QAC7E,6CAA6C;QAC7C,2CAA2C,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI;QACxE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,6BAA6B,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,oCAAoC,QAAQ,CAAC,KAAK,CAAC,IAAI;QACvD,OAAO;QACP,0EAA0E;QAC1E,0EAA0E;QAC1E,sEAAsE;QACtE,uEAAuE;QACvE,gEAAgE;QAChE,0BAA0B,QAAQ,CAAC,GAAG,CAAC,+DAA+D;QACtG,6CAA6C;QAC7C,6CAA6C;QAC7C,WAAW;QACX,oBAAoB;QACpB,GAAG;KACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAwB;IAC5D,OAAO,SAAS,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAwB;IAChE,OAAO,SAAS,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAwB;IAC1D,OAAO,SAAS,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAwB;IACpD,OAAO,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACjC,CAAC;AAsBD,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,cAAc,GAA2B;IAC7C,YAAY,EAAE,EAAE;IAChB,gBAAgB,EAAE,EAAE;IACpB,UAAU,EAAE,EAAE;IACd,IAAI,EAAE,EAAE,EAAE,+DAA+D;CAC1E,CAAC;AAEF,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,mCAAmC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAuB;IAC/D,0EAA0E;IAC1E,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,KAAK,GAAG,CAAC,KAAuB,EAAE,UAAkB,EAAE,OAAgB,EAAoB,EAAE,CAAC,CAAC;QAClG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,UAAU,GAAG,EAAE,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;KAC9F,CAAC,CAAC;IACH,MAAM,IAAI,GAAuC;QAC/C,YAAY,EAAE,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;QACzD,gBAAgB,EAAE,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;KACtE,CAAC;IACF,IAAI,KAAK,CAAC,UAAU;QAAE,IAAI,CAAC,UAAU,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC,CAAC;IACtG,IAAI,KAAK,CAAC,IAAI;QAAE,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,qEAAqE;AACrE,2EAA2E;AAC3E,6BAA6B;AAC7B,sDAAsD;AAEtD,MAAM,QAAQ,GAAG,eAAe,CAAC;AACjC,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAC9C,mFAAmF;AACnF,MAAM,YAAY,GAAqC;IACrD,YAAY,EAAE,kCAAkC;IAChD,gBAAgB,EAAE,kCAAkC;IACpD,UAAU,EAAE,6BAA6B;IACzC,IAAI,EAAE,yBAAyB;CAChC,CAAC;AACF,MAAM,qBAAqB,GAAG,+BAA+B,CAAC;AAoB9D,sEAAsE;AACtE,SAAS,cAAc,CAAC,CAAmB,EAAE,YAAyB;IACpE,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;IAC5B,OAAO,CACL,KAAK,CAAC,MAAM,GAAG,CAAC;QAChB,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;YAChB,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;YAC5B,0EAA0E;YAC1E,oEAAoE;YACpE,OAAO,CACL,GAAG,CAAC,QAAQ,CAAC,qBAAqB,CAAC;gBACnC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;gBACrB,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CACtD,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAwB,EACxB,KAAuB;IAEvB,MAAM,IAAI,GAAmB,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;IACnF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAM,CAAC;IAC1B,MAAM,QAAQ,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAC/E,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CACxB,CACF,CAAC;IAEF,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1D,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CACtE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC,CACxC,CAAC;QACF,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACrC,CAAC;AAcD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAkB,EAClB,UAAkB,EAClB,MAAe,EACf,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC9C,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,MAAM,IAAI,GAAuB,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACxD,MAAM,MAAM,GAAuB,CAAC,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAC9F,MAAM,SAAS,GAAqC;QAClD,YAAY,EAAE,qBAAqB,CAAC,IAAI,CAAC;QACzC,gBAAgB,EAAE,yBAAyB,CAAC,IAAI,CAAC;QACjD,UAAU,EAAE,mBAAmB,CAAC,IAAI,CAAC;QACrC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC;KAC1B,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,CAAmB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3E,MAAM,MAAM,GAAG,KAAK,EAAE,CAAS,EAAmB,EAAE;QAClD,IAAI,CAAC;YAAC,OAAO,MAAM,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,EAAE,CAAC;QAAC,CAAC;IACjE,CAAC,CAAC;IAEF,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,UAAU,GAAG,IAAI,CAAC;IACtB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,IAAI;YAAE,WAAW,GAAG,IAAI,CAAC;QAC7B,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,UAAU,GAAG,KAAK,CAAC;IACvD,CAAC;IACD,MAAM,OAAO,GAAoC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAEjH,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;YAC1D,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACxD,MAAM,eAAe,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACjD,IAAI,gBAAgB,GAAmB,EAAE,CAAC;IAC1C,IAAI,eAAe,EAAE,CAAC;QACpB,IAAI,CAAC;YAAC,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAmB,CAAC;QAAC,CAAC;QAC/F,MAAM,CAAC;YAAC,gBAAgB,GAAG,EAAE,CAAC;QAAC,CAAC,CAAC,2EAA2E;IAC9G,CAAC;IACD,2EAA2E;IAC3E,6EAA6E;IAC7E,mEAAmE;IACnE,4EAA4E;IAC5E,sCAAsC;IACtC,MAAM,UAAU,GAAG,CAAC,CAAmB,EAAE,EAAE,CACzC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,uBAAuB,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,oBAAoB,CAAC,gBAAgB,EAAE;QACnE,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC;QACxC,gBAAgB,EAAE,UAAU,CAAC,kBAAkB,CAAC;QAChD,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC;QACpC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;KACzB,CAAC,CAAC;IACH,IAAI,cAAgD,CAAC;IACrD,IAAI,CAAC,eAAe;QAAE,cAAc,GAAG,SAAS,CAAC;SAC5C,IAAI,CAAC,OAAO;QAAE,cAAc,GAAG,WAAW,CAAC;;QAC3C,cAAc,GAAG,QAAQ,CAAC;IAC/B,IAAI,cAAc,KAAK,WAAW,EAAE,CAAC;QACnC,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,MAAM,SAAS,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACnF,CAAC;IAED,OAAO;QACL,gBAAgB,EAAE,OAAO,CAAC,cAAc,CAAC;QACzC,gBAAgB,EAAE,OAAO,CAAC,kBAAkB,CAAC;QAC7C,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC;QACrC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC;QACzB,OAAO;QACP,QAAQ,EAAE,cAAc;KACzB,CAAC;AACJ,CAAC"}

package/dist/src/ambient-ledger.d.ts

@@ -0,0 +1,19 @@
+import type { TurnRecord } from './ambient-recall.js';
+export interface LedgerEntry extends TurnRecord {
+    /** ISO timestamp of the turn. */
+    ts: string;
+    /** Hook event (SessionStart/UserPromptSubmit/PreToolUse) or 'credit'. */
+    event: string;
+    /** Optional free-text note (e.g. what the credit was for). */
+    note?: string;
+}
+/** Default ledger location; overridable for tests via explicit path args. */
+export declare function defaultLedgerPath(): string;
+/** One JSONL line for an entry. Pure. */
+export declare function serializeEntry(e: LedgerEntry): string;
+/** Parse ledger text into entries, silently skipping corrupt lines. Pure. */
+export declare function parseLedger(text: string): LedgerEntry[];
+/** Append an entry; auto-creates the directory, auto-rotates. Never throws. */
+export declare function appendLedgerEntry(entry: LedgerEntry, path?: string): Promise<void>;
+/** Read all entries; missing/corrupt file → []. Never throws. */
+export declare function readLedger(path?: string): Promise<LedgerEntry[]>;

package/dist/src/ambient-ledger.js

@@ -0,0 +1,95 @@
+// Ambient Recall (Phase 4 Ausbau) — the net-token ledger.
+//
+// Roadmap §6.2: the whole feature is only honest if injected tokens (cost, paid
+// now) are weighed against prevented tokens (a wrong path a lesson averted).
+// This module persists per-turn records as JSONL (~/.cachly/ambient-ledger.jsonl)
+// so `ambient-stats` can show the NET number — even when it is negative — and
+// the CLI can auto-backoff (§6.3 guardrail 3) when the recent window is net-red.
+//
+// Prevented-credit in v1 is agent-reported: the injected context carries a tiny
+// footer inviting the agent to run `ambient-credit <tokens>` when a recalled
+// lesson actually changed its path. Self-reported ≠ perfect, but it is the only
+// client-side signal that exists before the server-side dashboard (v2) — and it
+// is what makes auto-backoff meaningful instead of permanently red.
+//
+// Everything here is best-effort: a broken ledger must never break a hook.
+import { appendFile, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+/** Default ledger location; overridable for tests via explicit path args. */
+export function defaultLedgerPath() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? '.';
+    return resolve(home, '.cachly', 'ambient-ledger.jsonl');
+}
+/** One JSONL line for an entry. Pure. */
+export function serializeEntry(e) {
+    return JSON.stringify({
+        ts: e.ts,
+        event: e.event,
+        injected: Math.max(0, Math.round(e.injected)),
+        prevented: Math.max(0, Math.round(e.prevented)),
+        ...(e.note ? { note: e.note.slice(0, 200) } : {}),
+    });
+}
+/** Parse ledger text into entries, silently skipping corrupt lines. Pure. */
+export function parseLedger(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const e = JSON.parse(t);
+            if (typeof e !== 'object' || e === null)
+                continue;
+            const injected = Number(e.injected);
+            const prevented = Number(e.prevented);
+            if (!Number.isFinite(injected) || !Number.isFinite(prevented))
+                continue;
+            out.push({
+                ts: typeof e.ts === 'string' ? e.ts : '',
+                event: typeof e.event === 'string' ? e.event : 'unknown',
+                injected: Math.max(0, injected),
+                prevented: Math.max(0, prevented),
+                ...(typeof e.note === 'string' ? { note: e.note } : {}),
+            });
+        }
+        catch {
+            // corrupt line (partial write, manual edit) → skip, never throw
+        }
+    }
+    return out;
+}
+// Rotation keeps the ledger bounded: hooks run on every prompt, and an
+// unbounded append-only file would eventually slow every turn down.
+const MAX_LEDGER_BYTES = 256 * 1024;
+const KEEP_LINES_ON_ROTATE = 400;
+/** Append an entry; auto-creates the directory, auto-rotates. Never throws. */
+export async function appendLedgerEntry(entry, path = defaultLedgerPath()) {
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await appendFile(path, serializeEntry(entry) + '\n', 'utf-8');
+        const text = await readFile(path, 'utf-8');
+        if (Buffer.byteLength(text, 'utf-8') > MAX_LEDGER_BYTES) {
+            const lines = text.split('\n').filter(Boolean);
+            const kept = lines.slice(-KEEP_LINES_ON_ROTATE).join('\n') + '\n';
+            // Write-then-rename so a crash mid-rotation never truncates to nothing.
+            const tmp = path + '.tmp';
+            await writeFile(tmp, kept, 'utf-8');
+            await rename(tmp, path);
+        }
+    }
+    catch {
+        // Ledger is telemetry — never let it break a hook or a commit.
+    }
+}
+/** Read all entries; missing/corrupt file → []. Never throws. */
+export async function readLedger(path = defaultLedgerPath()) {
+    try {
+        return parseLedger(await readFile(path, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=ambient-ledger.js.map

package/dist/src/ambient-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient-ledger.js","sourceRoot":"","sources":["../../src/ambient-ledger.ts"],"names":[],"mappings":"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"}

package/dist/src/ambient-recall.d.ts

@@ -0,0 +1,59 @@
+export interface LessonCandidate {
+    id: string;
+    /** The text that would be injected into context. */
+    summary: string;
+    /** Brain confidence in the lesson, [0,1]. */
+    confidence: number;
+    /** Semantic similarity of the lesson to the current prompt, [0,1]. */
+    score: number;
+    severity?: 'critical' | 'major' | 'minor';
+}
+export interface GateOptions {
+    /** Minimum brain confidence to be eligible. */
+    minConfidence: number;
+    /** Minimum semantic similarity to the prompt. */
+    minScore: number;
+    /** Hard cap on how many lessons may be injected in one turn. */
+    topK: number;
+    /** Hard per-turn injection budget, in estimated tokens. */
+    maxTokens: number;
+}
+export declare const DEFAULT_GATE: GateOptions;
+/** Rough token estimate (~4 chars/token) — good enough for a per-turn budget. */
+export declare function estimateTokens(text: string): number;
+/**
+ * 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 declare function isTrivialPrompt(prompt: string): boolean;
+export type GateReason = 'trivial-skip' | 'no-candidate-passed-gate' | 'injected';
+export interface GateDecision {
+    inject: boolean;
+    reason: GateReason;
+    selected: LessonCandidate[];
+    /** Estimated tokens the selection would inject (0 when nothing is injected). */
+    tokens: number;
+}
+/**
+ * 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 declare function selectInjectable(prompt: string, candidates: LessonCandidate[], opts?: Partial<GateOptions>): GateDecision;
+export interface TurnRecord {
+    injected: number;
+    prevented: number;
+}
+export interface NetBalance {
+    injected: number;
+    prevented: number;
+    net: number;
+}
+export declare function netBalance(records: TurnRecord[]): NetBalance;
+/**
+ * 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 declare function shouldBackoff(records: TurnRecord[], windowN?: number, minTurns?: number): boolean;

package/dist/src/ambient-recall.js

@@ -0,0 +1,96 @@
+// 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.
+// 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,
+};
+/** 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;
+}
+//# sourceMappingURL=ambient-recall.js.map

package/dist/src/ambient-recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient-recall.js","sourceRoot":"","sources":["../../src/ambient-recall.ts"],"names":[],"mappings":"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"}

package/dist/src/doctor.d.ts

@@ -0,0 +1,47 @@
+import { type TurnRecord } from './ambient-recall.js';
+export type DoctorStatus = 'ok' | 'warn' | 'fail';
+export interface DoctorCheck {
+    /** Short stable label, e.g. "Node.js", "Credential", "Hooks". */
+    name: string;
+    status: DoctorStatus;
+    /** One line of what was found. */
+    detail: string;
+    /** Actionable next step — only set when status is not ok. */
+    hint?: string;
+}
+/** Node runtime new enough for fetch/AbortSignal (>= 18). */
+export declare function checkNodeVersion(version?: string): DoctorCheck;
+/** Credential present and roughly the right shape (cky_… API key or JWT). */
+export declare function checkCredential(jwt: string): DoctorCheck;
+type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/** API reachable at all (public /health — no auth involved). */
+export declare function checkApiReachable(apiUrl: string, fetchFn?: FetchLike): Promise<DoctorCheck>;
+/** Credential actually accepted by the API (authenticated list call). */
+export declare function checkAuthAccepted(apiUrl: string, jwt: string, fetchFn?: FetchLike): Promise<DoctorCheck>;
+/** Brain instance configured (env or auto-provisioned default). */
+export declare function checkInstance(instanceId: string | undefined): DoctorCheck;
+export interface HookInspection {
+    settingsExists: boolean;
+    wiredEvents: string[];
+    scriptFiles: {
+        path: string;
+        exists: boolean;
+        version: 'current' | 'stale' | 'unknown';
+    }[];
+}
+/** Read-only look at .claude/ in projectDir — never throws. */
+export declare function inspectAmbientHooks(projectDir: string): HookInspection;
+/** Ambient hooks wired, scripts present, version current. */
+export declare function checkHooks(inspection: HookInspection): DoctorCheck;
+/** Net-token ledger readable + backoff state. */
+export declare function checkLedger(entries: TurnRecord[], ledgerPath: string): DoctorCheck;
+/** Render the report; deterministic, no colors (CI-friendly). */
+export declare function renderDoctorReport(checks: DoctorCheck[]): string;
+/** Exit code contract: 1 only on hard failures (warnings stay 0 for CI use). */
+export declare function doctorExitCode(checks: DoctorCheck[]): 0 | 1;
+export {};