@cachly-dev/mcp-server 0.10.117 → 0.10.118

package/README.md

@@ -63,7 +63,7 @@ hundreds of teams lose the same knowledge the same way, and we built the fix:
 - **It learns automatically** — from every commit, every fix, every session. No extra calls.
 - **It arrives pre-briefed** — your AI opens each session already knowing your stack.
 - **It's shared** — one engineer's solved bug becomes the whole team's reflex.
-- **It's provable** — quality-aware recall beats raw text search by **+22.2 % Precision@1**
+- **It's provable** — quality-aware recall beats raw text search by **+33.3 % Precision@1**
   ([see the benchmark](./BENCH.md)). A claim without a number is marketing; this is the number.
 - **It's neutral** — speaks [MCP](https://modelcontextprotocol.io), so it works with
   Claude, Cursor, Copilot, Windsurf, Cline, Zed. Switch models anytime — **your brain stays.**
@@ -177,7 +177,7 @@ using only Claude, alone.** That's not the game we're playing. Here's the honest
 | Works across **models & tools** | ✅ MCP — Claude, Cursor, Copilot, Windsurf, Zed… | ❌ Claude + Anthropic API only |
 | **Structured** knowledge | ✅ topic · outcome · severity · causal graph | ⚠️ flat text files, read linearly |
 | **Causal root-cause** (`causal_trace`) | ✅ problem → chain → proven fix | ❌ |
-| **Provable recall quality** | ✅ +22.2 % Precision@1 vs. BM25 ([benchmark](./BENCH.md)) | ❌ no public metric |
+| **Provable recall quality** | ✅ +33.3 % Precision@1 vs. BM25 ([benchmark](./BENCH.md)) | ❌ no public metric |
 | **Governance** (review, attribution, audit) | ✅ `team_confirm`, roles, audit trail | ❌ |
 | **Self-hosting / BYOK / VPC** | ✅ data stays in your infra | ❌ Anthropic-hosted |
 | Survives a **model switch** | ✅ your brain is yours | ❌ memory is gone or fragmented |

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

@@ -0,0 +1,85 @@
+import { type LessonCandidate, type GateOptions } from './ambient-recall.js';
+/** The subset of the Claude Code hook payload we care about. */
+export interface HookPayload {
+    hook_event_name?: string;
+    /** Present on UserPromptSubmit — the text the user just typed. */
+    prompt?: string;
+    /** Present on SessionStart — 'startup' | 'resume' | 'clear' | 'compact'. */
+    source?: string;
+    /** Present on PreToolUse — the tool about to run and its input. */
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+        [k: string]: unknown;
+    };
+    /** Present on Stop — what the assistant just said (auto-learn signal). */
+    last_assistant_message?: string;
+    cwd?: string;
+}
+/** Parse the hook payload from stdin. Never throws — returns null on any problem. */
+export declare function parseHookPayload(raw: string): HookPayload | null;
+/**
+ * The query to recall on for a payload, or null when recall should be skipped
+ * before any brain call:
+ *   • UserPromptSubmit → the prompt, unless it is trivial (§6.3 guardrail 2).
+ *   • SessionStart     → a fixed briefing query (there is no user prompt yet);
+ *     skipped on 'compact'/'clear' resumes where a mid-session briefing is noise.
+ *   • PreToolUse       → a file-scoped query for Edit/Write-class tools only.
+ *   • Stop             → never recalls (it learns instead — see stopObservation).
+ */
+export declare function recallQueryFor(payload: HookPayload): string | null;
+export interface StopObservation {
+    action: string;
+    outcome: 'success';
+    details: string;
+    severity: 'minor';
+}
+/**
+ * Derive an auto-learn observation from a Stop payload, or null when the turn
+ * carries no clear fix signal. Pure — the caller feeds it to auto_learn_session.
+ */
+export declare function stopObservation(payload: HookPayload): StopObservation | null;
+/** Truncate text to fit an estimated token budget (~4 chars/token), on a word edge. */
+export declare function truncateToTokens(text: string, maxTokens: number): string;
+/**
+ * Tiny footer that closes the net-token loop (§6.2): the agent self-reports
+ * prevented tokens via `ambient-credit` when a recalled lesson changed its path.
+ * Kept to one short line — its own token cost is counted as injected.
+ */
+export declare const CREDIT_FOOTER = "(If this memory just saved you from a wrong path, record it: `npx @cachly-dev/mcp-server@latest ambient-credit <tokens-saved>`)";
+/**
+ * Render the gated lessons into a context block for the agent.
+ *   • A single already-formatted briefing (multi-line summary — what smart_recall
+ *     returns) is injected verbatim; it carries its own headings.
+ *   • Multiple short lessons are rendered as a titled bullet list.
+ * `withCreditFooter` appends the self-report line (per-prompt events only —
+ * a SessionStart briefing is ambience, not a decision-changing recall).
+ */
+export declare function formatContextBlock(lessons: LessonCandidate[], withCreditFooter?: boolean): string;
+/**
+ * Build the JSON Claude Code expects from a hook. `additionalContext` is spliced
+ * into the model's context for the turn. Empty context → empty string (no output),
+ * which Claude Code treats as "hook contributed nothing".
+ */
+export declare function buildHookOutput(event: string, additionalContext: string): string;
+export interface AmbientDeps {
+    /** Fetch candidate lessons for a query. Should already be scoped to the brain. */
+    recall: (query: string, event: string) => Promise<LessonCandidate[]>;
+    /** Overrides for the relevance gate. */
+    gate?: Partial<GateOptions>;
+    /** Hard latency budget for the whole recall step (ms). Default 3000. */
+    timeoutMs?: number;
+    /**
+     * Auto-backoff probe (§6.3 guardrail 3): return true when the recent ledger
+     * window is net-negative — recall is then skipped BEFORE any brain call.
+     */
+    backoff?: () => boolean | Promise<boolean>;
+    /** Called with the estimated injected tokens whenever context is emitted. */
+    onInject?: (tokens: number, event: string) => void;
+}
+/**
+ * The whole ambient-recall CLI flow, as a pure function of (stdin, deps).
+ * Returns the string to print on stdout — either the hookSpecificOutput JSON or
+ * '' (nothing to inject). Never throws.
+ */
+export declare function runAmbient(raw: string, deps: AmbientDeps): Promise<string>;

package/dist/src/ambient-cli.js

@@ -0,0 +1,199 @@
+// Ambient Recall (Phase 4) — the CLI core that the hook scripts pipe to.
+//
+// The SessionStart / UserPromptSubmit hooks (ambient-hooks.ts) pipe Claude Code's
+// hook payload JSON on stdin to `npx @cachly-dev/mcp-server ambient-recall`. This
+// module is that command's brain: it parses the payload, runs the §6.3 relevance
+// gate (ambient-recall.ts), and prints the `hookSpecificOutput` JSON Claude Code
+// injects as additionalContext — or nothing at all when the gate says skip.
+//
+// Design constraints (roadmap §6.3):
+//   • Pure + dependency-injected (recall is passed in) so it is exhaustively
+//     unit-tested without any network.
+//   • Graceful: EVERY failure path returns '' (no output) — the caller exits 0 so
+//     a crashing hook can never block or corrupt the agent's turn.
+//   • Self-limited: recall runs under a hard timeout budget; a slow brain never
+//     stalls the user's prompt.
+import { isTrivialPrompt, selectInjectable, estimateTokens, } from './ambient-recall.js';
+/** Parse the hook payload from stdin. Never throws — returns null on any problem. */
+export function parseHookPayload(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (!trimmed)
+        return null;
+    try {
+        const p = JSON.parse(trimmed);
+        if (p && typeof p === 'object')
+            return p;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// PreToolUse fires for every tool; only file-mutating tools carry a wrong-path
+// risk worth a recall (roadmap §6.1: file-open briefing on Edit/Write).
+const FILE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+/**
+ * The query to recall on for a payload, or null when recall should be skipped
+ * before any brain call:
+ *   • UserPromptSubmit → the prompt, unless it is trivial (§6.3 guardrail 2).
+ *   • SessionStart     → a fixed briefing query (there is no user prompt yet);
+ *     skipped on 'compact'/'clear' resumes where a mid-session briefing is noise.
+ *   • PreToolUse       → a file-scoped query for Edit/Write-class tools only.
+ *   • Stop             → never recalls (it learns instead — see stopObservation).
+ */
+export function recallQueryFor(payload) {
+    const event = payload.hook_event_name ?? 'UserPromptSubmit';
+    if (event === 'SessionStart') {
+        if (payload.source === 'compact' || payload.source === 'clear')
+            return null;
+        return 'session start: recent lessons, active pitfalls, and known failure modes for this project';
+    }
+    if (event === 'PreToolUse') {
+        if (payload.tool_name && !FILE_TOOLS.has(payload.tool_name))
+            return null;
+        const filePath = payload.tool_input?.file_path;
+        if (typeof filePath !== 'string' || !filePath.trim())
+            return null;
+        return `known pitfalls, past bugs and lessons for file ${filePath.trim()}`;
+    }
+    if (event === 'Stop')
+        return null;
+    const prompt = (payload.prompt ?? '').trim();
+    if (!prompt || isTrivialPrompt(prompt))
+        return null;
+    return prompt;
+}
+// Conservative fix-signal: only turns whose final message clearly reports a
+// resolved problem become auto-lessons. Anything looser floods the brain with
+// junk on every turn-end — the exact noise §6.4 warns about.
+const FIX_SIGNAL_RE = /\b(fixed|resolved|behoben|gefixt|root cause|the bug was|der fehler (lag|war)|ursache (war|gefunden)|now passes|tests? (are|is|sind) (green|grün)|deployed successfully)\b/i;
+/**
+ * Derive an auto-learn observation from a Stop payload, or null when the turn
+ * carries no clear fix signal. Pure — the caller feeds it to auto_learn_session.
+ */
+export function stopObservation(payload) {
+    const msg = (payload.last_assistant_message ?? '').trim();
+    if (msg.length < 80)
+        return null; // too short to describe a real fix
+    if (!FIX_SIGNAL_RE.test(msg))
+        return null;
+    const firstLine = msg.split('\n').find((l) => l.trim().length > 0)?.trim() ?? msg;
+    return {
+        action: firstLine.slice(0, 200),
+        outcome: 'success',
+        details: msg.slice(0, 500),
+        severity: 'minor',
+    };
+}
+/** Truncate text to fit an estimated token budget (~4 chars/token), on a word edge. */
+export function truncateToTokens(text, maxTokens) {
+    const t = text.trim();
+    if (estimateTokens(t) <= maxTokens)
+        return t;
+    const maxChars = Math.max(0, maxTokens * 4);
+    const cut = t.slice(0, maxChars);
+    const lastSpace = cut.lastIndexOf(' ');
+    return (lastSpace > maxChars * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd() + '…';
+}
+/**
+ * Tiny footer that closes the net-token loop (§6.2): the agent self-reports
+ * prevented tokens via `ambient-credit` when a recalled lesson changed its path.
+ * Kept to one short line — its own token cost is counted as injected.
+ */
+export const CREDIT_FOOTER = '(If this memory just saved you from a wrong path, record it: `npx @cachly-dev/mcp-server@latest ambient-credit <tokens-saved>`)';
+/**
+ * Render the gated lessons into a context block for the agent.
+ *   • A single already-formatted briefing (multi-line summary — what smart_recall
+ *     returns) is injected verbatim; it carries its own headings.
+ *   • Multiple short lessons are rendered as a titled bullet list.
+ * `withCreditFooter` appends the self-report line (per-prompt events only —
+ * a SessionStart briefing is ambience, not a decision-changing recall).
+ */
+export function formatContextBlock(lessons, withCreditFooter = false) {
+    if (lessons.length === 0)
+        return '';
+    const body = lessons.length === 1 && lessons[0].summary.includes('\n')
+        ? lessons[0].summary.trim()
+        : `🧠 Relevant memory from your cachly brain (auto-recalled):\n` +
+            lessons.map((l) => `- ${l.summary.trim()}`).join('\n');
+    return withCreditFooter ? `${body}\n${CREDIT_FOOTER}` : body;
+}
+/**
+ * Build the JSON Claude Code expects from a hook. `additionalContext` is spliced
+ * into the model's context for the turn. Empty context → empty string (no output),
+ * which Claude Code treats as "hook contributed nothing".
+ */
+export function buildHookOutput(event, additionalContext) {
+    if (!additionalContext)
+        return '';
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: event,
+            additionalContext,
+        },
+    });
+}
+/** Resolve a promise to a fallback if it does not settle within `ms`. */
+async function withTimeout(p, ms, fallback) {
+    let timer;
+    const timeout = new Promise((res) => {
+        timer = setTimeout(() => res(fallback), ms);
+    });
+    try {
+        return await Promise.race([p, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * The whole ambient-recall CLI flow, as a pure function of (stdin, deps).
+ * Returns the string to print on stdout — either the hookSpecificOutput JSON or
+ * '' (nothing to inject). Never throws.
+ */
+export async function runAmbient(raw, deps) {
+    const payload = parseHookPayload(raw);
+    if (!payload)
+        return '';
+    const event = payload.hook_event_name ?? 'UserPromptSubmit';
+    const query = recallQueryFor(payload);
+    if (query === null)
+        return ''; // trivial / non-recallable event → skip before any brain call
+    // Auto-backoff (§6.3 guardrail 3): when the recent net balance is red, stop
+    // paying — checked after trivial-skip but before any brain call.
+    try {
+        if (deps.backoff && (await deps.backoff()))
+            return '';
+    }
+    catch {
+        // a broken backoff probe must not disable recall
+    }
+    let candidates = [];
+    try {
+        candidates = await withTimeout(deps.recall(query, event), deps.timeoutMs ?? 3000, []);
+    }
+    catch {
+        return ''; // recall failed → inject nothing, never block the turn
+    }
+    if (!Array.isArray(candidates) || candidates.length === 0)
+        return '';
+    // SessionStart/PreToolUse have no user prompt, so their trivial-skip is
+    // meaningless; pass the recall query itself so the gate's non-trivial branch runs.
+    const gateInput = event === 'UserPromptSubmit' ? (payload.prompt ?? query) : query;
+    const decision = selectInjectable(gateInput, candidates, deps.gate);
+    if (!decision.inject)
+        return '';
+    // Credit footer only where a recall can change a decision mid-flight.
+    const withFooter = event === 'UserPromptSubmit' || event === 'PreToolUse';
+    const context = formatContextBlock(decision.selected, withFooter);
+    const injectedTokens = estimateTokens(context); // includes the footer's own cost
+    try {
+        deps.onInject?.(injectedTokens, event);
+    }
+    catch {
+        // ledger is telemetry — never block the injection over it
+    }
+    return buildHookOutput(event, context);
+}
+//# sourceMappingURL=ambient-cli.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ambient-cli.js","sourceRoot":"","sources":["../../src/ambient-cli.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,kFAAkF;AAClF,kFAAkF;AAClF,iFAAiF;AACjF,iFAAiF;AACjF,4EAA4E;AAC5E,EAAE;AACF,qCAAqC;AACrC,6EAA6E;AAC7E,uCAAuC;AACvC,kFAAkF;AAClF,mEAAmE;AACnE,gFAAgF;AAChF,gCAAgC;AAEhC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,GAGf,MAAM,qBAAqB,CAAC;AAiB7B,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;QACzC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAgB,CAAC;QACxD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,wEAAwE;AACxE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAAoB;IACjD,MAAM,KAAK,GAAG,OAAO,CAAC,eAAe,IAAI,kBAAkB,CAAC;IAC5D,IAAI,KAAK,KAAK,cAAc,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QAC5E,OAAO,0FAA0F,CAAC;IACpG,CAAC;IACD,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;QAC3B,IAAI,OAAO,CAAC,SAAS,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QACzE,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC;QAC/C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE;YAAE,OAAO,IAAI,CAAC;QAClE,OAAO,kDAAkD,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;IAC7E,CAAC;IACD,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,OAAO,MAAM,CAAC;AAChB,CAAC;AASD,4EAA4E;AAC5E,8EAA8E;AAC9E,6DAA6D;AAC7D,MAAM,aAAa,GACjB,4KAA4K,CAAC;AAE/K;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAoB;IAClD,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1D,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,mCAAmC;IACrE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC;IAClF,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC/B,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC1B,QAAQ,EAAE,OAAO;KAClB,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,SAAiB;IAC9D,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IACtB,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,SAAS;QAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACjC,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,OAAO,CAAC,SAAS,GAAG,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC;AACtF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,iIAAiI,CAAC;AAEpI;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA0B,EAAE,gBAAgB,GAAG,KAAK;IACrF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GACR,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QACvD,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE;QAC3B,CAAC,CAAC,8DAA8D;YAC9D,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,OAAO,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,iBAAyB;IACtE,IAAI,CAAC,iBAAiB;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,kBAAkB,EAAE;YAClB,aAAa,EAAE,KAAK;YACpB,iBAAiB;SAClB;KACF,CAAC,CAAC;AACL,CAAC;AAkBD,yEAAyE;AACzE,KAAK,UAAU,WAAW,CAAI,CAAa,EAAE,EAAU,EAAE,QAAW;IAClE,IAAI,KAAgD,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,EAAE;QACrC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW,EAAE,IAAiB;IAC7D,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,KAAK,GAAG,OAAO,CAAC,eAAe,IAAI,kBAAkB,CAAC;IAE5D,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC,CAAC,8DAA8D;IAE7F,4EAA4E;IAC5E,iEAAiE;IACjE,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YAAE,OAAO,EAAE,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;IAED,IAAI,UAAU,GAAsB,EAAE,CAAC;IACvC,IAAI,CAAC;QACH,UAAU,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,uDAAuD;IACpE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErE,wEAAwE;IACxE,mFAAmF;IACnF,MAAM,SAAS,GAAG,KAAK,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACpE,IAAI,CAAC,QAAQ,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAEhC,sEAAsE;IACtE,MAAM,UAAU,GAAG,KAAK,KAAK,kBAAkB,IAAI,KAAK,KAAK,YAAY,CAAC;IAC1E,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAClE,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,iCAAiC;IACjF,IAAI,CAAC;QACH,IAAI,CAAC,QAAQ,EAAE,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;IACD,OAAO,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC"}

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

@@ -0,0 +1,128 @@
+/**
+ * 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 declare 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 declare const AMBIENT_CLI_SUBCOMMAND = "ambient-recall";
+export type AmbientHookEvent = 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse' | 'Stop';
+export interface AmbientHookOptions {
+    instanceId: string;
+    /** Optional cky_… / JWT embedded so the CLI can authenticate. */
+    apiKey?: string;
+    /**
+     * Command that resolves the ambient-recall CLI. Defaults to the published
+     * package via npx; an installer SHOULD pass a resolved local binary to avoid
+     * npx resolution latency on every prompt (UserPromptSubmit runs per-turn).
+     */
+    cliCommand?: string;
+}
+/**
+ * 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 declare function buildSessionStartHook(opts: AmbientHookOptions): string;
+/**
+ * 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 declare function buildUserPromptSubmitHook(opts: AmbientHookOptions): string;
+/**
+ * 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 declare function buildPreToolUseHook(opts: AmbientHookOptions): string;
+/**
+ * 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 declare function buildStopHook(opts: AmbientHookOptions): string;
+export interface AmbientHookPaths {
+    sessionStart: string;
+    userPromptSubmit: string;
+    /** Ausbau hooks — optional so MVP-era (v1) callers keep working. */
+    preToolUse?: string;
+    stop?: string;
+}
+export interface HookCommand {
+    type: 'command';
+    command: string;
+    /** Per-hook timeout in seconds (Claude Code hooks config). */
+    timeout?: number;
+}
+export interface HookMatcherGroup {
+    /** Tool matcher — only meaningful for PreToolUse/PostToolUse. */
+    matcher?: string;
+    hooks: HookCommand[];
+}
+/** Matcher for the PreToolUse briefing: only file-mutating tools. */
+export declare 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 declare function buildAmbientSettingsHooks(paths: AmbientHookPaths): Record<string, HookMatcherGroup[]>;
+export interface AmbientInstallResult {
+    sessionStartPath: string;
+    promptSubmitPath: string;
+    preToolUsePath: string;
+    stopPath: string;
+    scripts: 'written' | 'upgraded' | 'unchanged';
+    settings: 'written' | 'merged' | 'unchanged';
+}
+interface HookCommandEntry {
+    matcher?: string;
+    hooks?: Array<{
+        type?: string;
+        command?: string;
+        timeout?: number;
+    }>;
+}
+interface ClaudeSettings {
+    hooks?: Record<string, HookCommandEntry[]>;
+    [k: string]: unknown;
+}
+/**
+ * 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 declare function mergeAmbientSettings(existing: ClaudeSettings, paths: AmbientHookPaths): {
+    settings: ClaudeSettings;
+    changed: boolean;
+};
+export interface AmbientInstallOptions {
+    /**
+     * Write `"$CLAUDE_PROJECT_DIR"/.claude/hooks/…` commands into settings.json
+     * instead of absolute paths. Use for hooks that are COMMITTED to a repo
+     * (dogfooding/team setups): the settings stay valid on every checkout
+     * location. Claude Code sets $CLAUDE_PROJECT_DIR when running hooks.
+     * NOTE: never pass an apiKey together with portable — committed scripts
+     * must not embed credentials; the CLI falls back to the env's CACHLY_JWT.
+     */
+    portable?: boolean;
+}
+/**
+ * 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 declare function installAmbientHooks(projectDir: string, instanceId: string, apiKey?: string, options?: AmbientInstallOptions): Promise<AmbientInstallResult>;
+export {};