mirror: sync sdk/mcp @ 0.10.104 from monorepo

Author: github-actions[bot]

CHANGELOG.md

@@ -7,6 +7,14 @@
 
 ---
 
+## [0.10.104] – 2026-06-06 — *"v4 Move 2 — Proactive briefing"*
+
+### Added
+- **`brain_briefing`** — flips the Brain from pull-only to push. Call it on `file_open` (with the file path), `pr_open` (with the PR title/body), or `deploy` (with a short description) and the Brain proactively surfaces up to 5 ranked warnings — confidence, severity, what to watch, and a known fix — *before* anything breaks. Returns an overall `risk_level` (low/medium/high) derived from the strongest match. Optional `threshold` (default 0.6) tunes signal-to-noise.
+- New API endpoint `POST /api/v1/instances/:id/briefing` — tokenises the event context (camelCase-aware, same tokeniser as PR scan), matches it against the instance's lessons above the confidence threshold, and ranks results.
+
+---
+
 ## [0.10.103] – 2026-06-05 — *"v4 Move 1 — Closed-loop CI"*
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.10.103",
+  "version": "0.10.104",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
   "description": "Your AI forgets everything between sessions. cachly fixes that permanently. Persistent memory + causal root-cause analysis for Claude Code, Cursor, Copilot & Windsurf. Learns from every bug fix, git commit, and CI run automatically. Arrives pre-briefed. Predicts failures before they happen. One-command setup (npx ... autopilot). 121 MCP tools · Free tier forever · GDPR · EU servers.",
   "type": "module",

src/__tests__/brain-briefing.test.ts

@@ -0,0 +1,88 @@
+/**
+ * brain_briefing — v4 Move 2: proactive briefing.
+ *
+ * Verifies:
+ * - rejects invalid event_type
+ * - rejects empty context
+ * - shows "no risk" message when no warnings returned
+ * - renders ranked warning table with risk level
+ * - graceful fallback when API unreachable
+ */
+
+import { describe, it, expect } from 'vitest';
+import { handleSyndicateTool } from '../handlers/syndicate.js';
+
+const INSTANCE = 'test-instance';
+
+function makeConn() {
+  return (async (_id: string) => ({})) as unknown as Parameters<typeof handleSyndicateTool>[2];
+}
+
+async function callTool(
+  name: string,
+  args: Record<string, unknown>,
+  apiFetch: Parameters<typeof handleSyndicateTool>[3],
+) {
+  return handleSyndicateTool(name, { instance_id: INSTANCE, ...args }, makeConn(), apiFetch);
+}
+
+function mockFetch(response: unknown) {
+  return (async () => response) as unknown as Parameters<typeof handleSyndicateTool>[3];
+}
+
+function failFetch() {
+  return (async () => { throw new Error('API down'); }) as unknown as Parameters<typeof handleSyndicateTool>[3];
+}
+
+describe('brain_briefing', () => {
+  it('rejects invalid event_type', async () => {
+    await expect(callTool('brain_briefing', { event_type: 'on_save', context: 'auth.ts' }, mockFetch({})))
+      .rejects.toThrow(/event_type must be/);
+  });
+
+  it('rejects empty context', async () => {
+    await expect(callTool('brain_briefing', { event_type: 'file_open', context: '   ' }, mockFetch({})))
+      .rejects.toThrow(/context is required/);
+  });
+
+  it('shows no-risk message when no warnings match', async () => {
+    const fetch = mockFetch({ event_type: 'file_open', risk_level: 'low', warnings: [], matched_lessons: 3 });
+    const result = await callTool('brain_briefing', { event_type: 'file_open', context: 'src/auth/login.ts' }, fetch);
+    expect(result).toContain('no known risk patterns matched');
+    expect(result).toContain('3 related lessons');
+  });
+
+  it('renders ranked warning table with risk level', async () => {
+    const fetch = mockFetch({
+      event_type: 'pr_open',
+      risk_level: 'high',
+      matched_lessons: 4,
+      warnings: [
+        { topic: 'auth:jwt', confidence: 0.85, severity: 'critical', message: 'JWT refresh race condition', fix: 'Lock token refresh with a mutex' },
+        { topic: 'deploy:k8s', confidence: 0.62, severity: 'major', message: 'Readiness probe too aggressive', fix: 'Increase failureThreshold to 10' },
+      ],
+    });
+    const result = await callTool('brain_briefing', { event_type: 'pr_open', context: 'Refactor auth + deploy pipeline' }, fetch);
+    expect(result).toContain('risk: HIGH');
+    expect(result).toContain('auth:jwt');
+    expect(result).toContain('85%');
+    expect(result).toContain('Lock token refresh with a mutex');
+  });
+
+  it('passes threshold through to the API when provided', async () => {
+    let capturedBody: string | undefined;
+    const fetch = (async (_path: string, opts?: RequestInit) => {
+      capturedBody = opts?.body as string;
+      return { event_type: 'deploy', risk_level: 'low', warnings: [], matched_lessons: 0 };
+    }) as unknown as Parameters<typeof handleSyndicateTool>[3];
+
+    await callTool('brain_briefing', { event_type: 'deploy', context: 'Deploy v2.4 to production', threshold: 0.8 }, fetch);
+    expect(capturedBody).toBeDefined();
+    expect(JSON.parse(capturedBody as string)).toMatchObject({ event_type: 'deploy', threshold: 0.8 });
+  });
+
+  it('falls back gracefully when API is unreachable', async () => {
+    const result = await callTool('brain_briefing', { event_type: 'file_open', context: 'src/db/migrate.go' }, failFetch());
+    expect(result).toContain('Could not reach Brain API');
+  });
+});

src/handlers/syndicate.ts

@@ -14,7 +14,7 @@ export const SYNDICATE_TOOL_NAMES = new Set([
   'brain_search', 'ckg_inspect', 'brain_predict', 'brain_plan',
   'brain_marketplace', 'brain_install',
   'brain_conflicts', 'brain_resolve_conflict',
-  'brain_confirm_ci',
+  'brain_confirm_ci', 'brain_briefing',
 ]);
 
 export async function handleSyndicateTool(
@@ -962,6 +962,72 @@ export async function handleSyndicateTool(
       return lines.join('\n');
     }
 
+    case 'brain_briefing': {
+      const {
+        instance_id,
+        event_type,
+        context,
+        threshold,
+      } = args as {
+        instance_id: string;
+        event_type: string;
+        context: string;
+        threshold?: number;
+      };
+
+      if (!['file_open', 'pr_open', 'deploy', 'manual'].includes(event_type)) {
+        throw new Error('event_type must be file_open, pr_open, deploy, or manual');
+      }
+      if (!context?.trim()) throw new Error('context is required');
+
+      type BriefingWarning = { topic: string; confidence: number; severity: string; message: string; fix: string };
+      type BriefingResult = {
+        event_type: string;
+        risk_level: 'low' | 'medium' | 'high';
+        warnings: BriefingWarning[];
+        matched_lessons: number;
+      };
+
+      let result: BriefingResult;
+      try {
+        result = await apiFetch<BriefingResult>(
+          `/api/v1/instances/${instance_id}/briefing`,
+          {
+            method: 'POST',
+            body: JSON.stringify({ event_type, context, ...(threshold !== undefined ? { threshold } : {}) }),
+          },
+        );
+      } catch {
+        return `⚠️ Could not reach Brain API — no proactive briefing available right now.`;
+      }
+
+      const eventIcon = event_type === 'file_open' ? '📂' : event_type === 'pr_open' ? '🔀' : event_type === 'deploy' ? '🚀' : '🔍';
+
+      if (result.warnings.length === 0) {
+        return [
+          `${eventIcon} **brain_briefing** — ${event_type} · ✅ no known risk patterns matched`,
+          '',
+          `Checked against ${result.matched_lessons} related lesson${result.matched_lessons !== 1 ? 's' : ''}. You're clear to proceed.`,
+        ].join('\n');
+      }
+
+      const riskIcon = result.risk_level === 'high' ? '🔴' : result.risk_level === 'medium' ? '🟡' : '🟢';
+      const lines = [
+        `${eventIcon} **brain_briefing** — ${event_type} · ${riskIcon} risk: ${result.risk_level.toUpperCase()}`,
+        '',
+        `The Brain proactively found ${result.warnings.length} known pattern${result.warnings.length !== 1 ? 's' : ''} that may apply here:`,
+        '',
+        `| Topic | Confidence | Severity | What to watch | Known fix |`,
+        `|---|---|---|---|---|`,
+      ];
+      for (const w of result.warnings) {
+        const fix = w.fix ? (w.fix.length > 80 ? w.fix.slice(0, 80) + '…' : w.fix) : '—';
+        lines.push(`| \`${w.topic}\` | ${(w.confidence * 100).toFixed(0)}% | ${w.severity} | ${w.message} | ${fix} |`);
+      }
+      lines.push('', `_Surfaced proactively — no \`smart_recall\` needed. Address the highest-confidence items first._`);
+      return lines.join('\n');
+    }
+
     // ── Layer 3: MADC ─────────────────────────────────────────────────────────
 
     default:

src/tools.ts

@@ -1971,6 +1971,36 @@ const TOOLS = [
       required: ['instance_id', 'job_status', 'topics'],
     },
   },
+  // ── v4 Move 2: Proactive briefing ─────────────────────────────────────────
+  {
+    name: 'brain_briefing',
+    description:
+      'Push-based Brain warning: instead of waiting for you to ask, the Brain proactively checks ' +
+      'whether the file you just opened, the PR you are about to raise, or the deploy you are about ' +
+      'to run matches any known failure pattern — and surfaces warnings BEFORE something breaks. ' +
+      'Call this on file_open (with the file path as context), pr_open (with the PR title/body), ' +
+      'or deploy (with a short description of what is being deployed). ' +
+      'Returns a risk_level (low/medium/high) plus up to 5 ranked warnings with confidence and a known fix.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'Brain instance ID' },
+        event_type: {
+          type: 'string', enum: ['file_open', 'pr_open', 'deploy', 'manual'],
+          description: 'What triggered this briefing — determines how the context is interpreted',
+        },
+        context: {
+          type: 'string',
+          description: 'The event context: file path for file_open, title+body for pr_open, short description for deploy/manual',
+        },
+        threshold: {
+          type: 'number',
+          description: 'Minimum confidence (0–1) for a warning to be surfaced. Default 0.6 — raise it to reduce noise.',
+        },
+      },
+      required: ['instance_id', 'event_type', 'context'],
+    },
+  },
   // ── Move 5: Privacy-preserving federation ────────────────────────────────
   {
     name: 'brain_contribute_signal',