frinus-mcp 3.6.3 → 3.7.0

package/dist/client/cp-client.d.ts

@@ -1,4 +1,4 @@
-import type { CpClientInterface } from "../types/index.js";
+import type { CpClientInterface, NotificationInbox } from "../types/index.js";
 export declare class CpClient implements CpClientInterface {
     private client;
     constructor(baseURL: string, apiKey: string);
@@ -13,6 +13,12 @@ export declare class CpClient implements CpClientInterface {
         description?: string;
     }): Promise<any>;
     deleteUniverse(orgId: string, universeId: string): Promise<void>;
+    getNotificationInbox(opts?: {
+        channel?: string;
+        limit?: number;
+        markDelivered?: boolean;
+    }): Promise<NotificationInbox>;
+    ackNotification(id: string): Promise<void>;
     storeCredential(integrationRef: string, data: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<any>;
     getCredential(integrationRef: string): Promise<any>;
     listCredentials(): Promise<any>;

package/dist/client/cp-client.js

@@ -4,6 +4,13 @@
 import axios from "axios";
 import { getResolvedTenantOrgId } from "./memory-client.js";
 import { getResolvedClient } from "./client-info.js";
+/**
+ * Short timeout (ms) for the platform-notification calls. These are best-effort
+ * side channels that must never slow down bootstrap/heartbeat or hold the agent
+ * hostage on a slow network, so they use a much tighter deadline than the 30s
+ * default of the rest of the Control Plane client.
+ */
+const NOTIFICATION_TIMEOUT_MS = 4000;
 export class CpClient {
     client;
     constructor(baseURL, apiKey) {
@@ -37,6 +44,25 @@ export class CpClient {
         await this.client.delete(`/api/v1/orgs/${orgId}/universes/${universeId}`);
     }
     // =========================================================================
+    // Platform Notifications (short timeout, best-effort)
+    // =========================================================================
+    async getNotificationInbox(opts = {}) {
+        const response = await this.client.get(`/api/v1/notifications/inbox`, {
+            params: {
+                channel: opts.channel ?? "mcp",
+                limit: opts.limit ?? 3,
+                mark_delivered: opts.markDelivered ?? false,
+            },
+            timeout: NOTIFICATION_TIMEOUT_MS,
+        });
+        return response.data;
+    }
+    async ackNotification(id) {
+        await this.client.post(`/api/v1/notifications/${id}/ack`, undefined, {
+            timeout: NOTIFICATION_TIMEOUT_MS,
+        });
+    }
+    // =========================================================================
     // Credential Vault
     // =========================================================================
     async storeCredential(integrationRef, data, metadata) {

package/dist/index.js

@@ -11,6 +11,7 @@
  *   tools/handlers.ts             - Tool handlers (dispatch map)
  *   types/index.ts                - Shared interfaces and types
  */
+import net from "node:net";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
@@ -26,6 +27,15 @@ import { dispatchTool } from "./tools/handlers.js";
 const MEMORY_SERVICE_URL = process.env.MEMORY_SERVICE_URL || "https://frinus-memory.rdxsec.com.br";
 const CP_URL = process.env.FRINUS_CP_URL || "https://frinus-api.rdxsec.com.br";
 const AGENT_SERVICE_URL = process.env.AGENT_SERVICE_URL || "https://frinus-agents.rdxsec.com.br";
+// Give Happy Eyeballs (RFC 8305) a realistic deadline before giving up on an
+// address family. Node's default auto-select-family attempt timeout is 250ms,
+// which on a slow network (2026-10-27 incident) made the API-key validation
+// fail with "Failed to validate API key: AggregateError" before the TCP
+// handshake could complete. 5s per attempt matches how long a cold mobile/VPN
+// link realistically needs. Guarded with typeof for older Node runtimes.
+if (typeof net.setDefaultAutoSelectFamilyAttemptTimeout === "function") {
+    net.setDefaultAutoSelectFamilyAttemptTimeout(5000);
+}
 // Main server
 async function main() {
     // Require API key (FRINUS_API_KEY preferred, FRINUS_MEMORY_API_KEY for backward compat)
@@ -40,31 +50,52 @@ async function main() {
     const cpClient = new CpClient(CP_URL, apiKey);
     const capture = new InteractionCapture(memoryClient);
     console.error(`[InteractionCapture] Session: ${capture.getSessionId()}`);
-    // Validate API key and resolve tenant identity at startup
-    try {
-        const me = await memoryClient.getAuthMe();
-        setResolvedUserEmail(me.email || me.user?.email || null);
-        setResolvedUserId(me.id || me.user?.id || me.user_id || null);
-        // Resolve tenant org ID from /auth/me response (env var takes precedence)
-        const meOrgId = me.organization_id || me.org_id || me.user?.organization_id || null;
-        if (!getResolvedTenantOrgId() && meOrgId) {
-            setResolvedTenantOrgId(meOrgId);
-        }
-        console.error(`[Auth] API key validated. User: ${getResolvedUserEmail()}, Tenant: ${getResolvedTenantOrgId() || 'none'}`);
-    }
-    catch (err) {
-        const status = err?.response?.status;
-        if (status === 401 || status === 403) {
-            console.error(`[FATAL] API key rejected (HTTP ${status}). Check FRINUS_API_KEY.`);
+    // Validate API key and resolve tenant identity at startup.
+    //
+    // Retry ONLY transient network failures (no HTTP response: DNS, connection
+    // refused/reset, timeout, AggregateError from Happy Eyeballs). A 401/403 is a
+    // real rejection and must fail fast — retrying a bad key is pointless. Backoff
+    // 1s then 3s between the 3 attempts. This, together with the auto-select-family
+    // timeout above, is the fix for the 2026-10-27 "Failed to validate API key:
+    // AggregateError" crashes on slow links.
+    const MAX_AUTH_ATTEMPTS = 3;
+    const AUTH_BACKOFFS_MS = [1000, 3000];
+    let me;
+    for (let attempt = 1;; attempt++) {
+        try {
+            me = await memoryClient.getAuthMe();
+            break;
         }
-        else {
+        catch (err) {
+            const status = err?.response?.status;
+            if (status === 401 || status === 403) {
+                console.error(`[FATAL] API key rejected (HTTP ${status}). Check FRINUS_API_KEY.`);
+                process.exit(1);
+            }
+            // No HTTP response == network/transport error -> retryable.
+            const isNetworkError = status === undefined;
+            if (isNetworkError && attempt < MAX_AUTH_ATTEMPTS) {
+                const waitMs = AUTH_BACKOFFS_MS[attempt - 1];
+                console.error(`[Auth] Network error validating API key (attempt ${attempt}/${MAX_AUTH_ATTEMPTS}): ` +
+                    `${err?.message || err}. Retrying in ${waitMs}ms...`);
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+                continue;
+            }
             console.error(`[FATAL] Failed to validate API key: ${err?.message || err}`);
+            process.exit(1);
         }
-        process.exit(1);
     }
+    setResolvedUserEmail(me.email || me.user?.email || null);
+    setResolvedUserId(me.id || me.user?.id || me.user_id || null);
+    // Resolve tenant org ID from /auth/me response (env var takes precedence)
+    const meOrgId = me.organization_id || me.org_id || me.user?.organization_id || null;
+    if (!getResolvedTenantOrgId() && meOrgId) {
+        setResolvedTenantOrgId(meOrgId);
+    }
+    console.error(`[Auth] API key validated. User: ${getResolvedUserEmail()}, Tenant: ${getResolvedTenantOrgId() || 'none'}`);
     const server = new Server({
         name: "frinus",
-        version: "3.6.3",
+        version: "3.7.0",
     }, {
         capabilities: {
             tools: {},

package/dist/notifications.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Platform notifications delivered through the MCP channel.
+ *
+ * Clients rarely come back to the web dashboard after the initial integration,
+ * so the MCP session itself becomes the way to reach them. This module fetches
+ * the Control Plane inbox and renders a compact markdown block that is appended
+ * to `agent_bootstrap` (once, forced) and `heartbeat_tick` (throttled).
+ *
+ * Design rules:
+ *  - NEVER throws. A 404, timeout or any network error yields '' plus a stderr
+ *    log. The agent's real work must never be blocked by the news channel.
+ *  - In-process state, per MCP process (= per session): which notification ids
+ *    were already shown, and when we last hit the inbox. A long-lived process
+ *    therefore shows each item at most once and polls at most once per window.
+ *  - Env toggles: FRINUS_NOTIFICATIONS=off disables everything;
+ *    FRINUS_NOTIFICATIONS_INTERVAL_MIN overrides the throttle window (default 60).
+ */
+import type { CpClientInterface } from "./types/index.js";
+/** Reset module state. Test-only; not part of the runtime surface. */
+export declare function __resetNotificationsState(): void;
+export interface FetchBlockOptions {
+    /** Bypass the throttle window (used by agent_bootstrap). */
+    force?: boolean;
+}
+/**
+ * Fetch the inbox and render the "Novidades do Frinus" block, or '' when there
+ * is nothing new to show (disabled, throttled, empty, already-shown, or any
+ * failure). Guaranteed not to throw.
+ */
+export declare function fetchNotificationsBlock(cpClient: CpClientInterface, opts?: FetchBlockOptions): Promise<string>;

package/dist/notifications.js

@@ -0,0 +1,86 @@
+/** Max characters of a notification body rendered inline. */
+const BODY_LIMIT = 600;
+/** Default throttle window for non-forced checks (minutes). */
+const DEFAULT_INTERVAL_MIN = 60;
+// ---------------------------------------------------------------------------
+// In-process session state
+// ---------------------------------------------------------------------------
+/** Notification ids already shown in this session (dedupe across bootstrap + ticks). */
+const shownIds = new Set();
+/** Epoch ms of the last inbox check (forced or throttled). 0 = never. */
+let lastCheckAt = 0;
+/** Reset module state. Test-only; not part of the runtime surface. */
+export function __resetNotificationsState() {
+    shownIds.clear();
+    lastCheckAt = 0;
+}
+function isDisabled() {
+    return (process.env.FRINUS_NOTIFICATIONS || "").trim().toLowerCase() === "off";
+}
+function throttleMs() {
+    const raw = process.env.FRINUS_NOTIFICATIONS_INTERVAL_MIN;
+    const parsed = raw !== undefined ? Number.parseInt(raw, 10) : NaN;
+    const minutes = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_INTERVAL_MIN;
+    return minutes * 60_000;
+}
+/**
+ * Fetch the inbox and render the "Novidades do Frinus" block, or '' when there
+ * is nothing new to show (disabled, throttled, empty, already-shown, or any
+ * failure). Guaranteed not to throw.
+ */
+export async function fetchNotificationsBlock(cpClient, opts = {}) {
+    if (isDisabled())
+        return "";
+    const now = Date.now();
+    if (!opts.force && now - lastCheckAt < throttleMs()) {
+        return "";
+    }
+    lastCheckAt = now;
+    let inbox;
+    try {
+        inbox = await cpClient.getNotificationInbox({
+            channel: "mcp",
+            limit: 3,
+            markDelivered: true,
+        });
+    }
+    catch (err) {
+        // 404 (CP not yet deployed), timeout, DNS, connection refused — all benign
+        // here. Swallow and keep working; log to stderr for operators.
+        console.error(`[Notifications] inbox fetch failed: ${err?.message || err}`);
+        return "";
+    }
+    const fresh = (inbox?.items || []).filter((it) => !!it && typeof it.id === "string" && !shownIds.has(it.id));
+    if (fresh.length === 0)
+        return "";
+    for (const it of fresh)
+        shownIds.add(it.id);
+    return renderBlock(fresh);
+}
+/** Render the markdown block the agent relays to the user. */
+function renderBlock(items) {
+    let out = `## 📣 Novidades do Frinus\n\n`;
+    for (const it of items) {
+        const sev = it.severity ? ` _(${it.severity})_` : "";
+        out += `### ${it.title}${sev}\n`;
+        let body = (it.body || "").trim();
+        if (body.length > BODY_LIMIT) {
+            body = body.slice(0, BODY_LIMIT).trimEnd() + "…";
+        }
+        if (body)
+            out += `${body}\n`;
+        if (it.cta_label && it.cta_url) {
+            out += `\n[${it.cta_label}](${it.cta_url})\n`;
+        }
+        else if (it.cta_url) {
+            out += `\n${it.cta_url}\n`;
+        }
+        out += `\n_id: ${it.id}_\n\n`;
+    }
+    out += `---\n`;
+    out +=
+        `Avise o usuário destas novidades de forma breve (1–3 linhas cada) no ` +
+            `início da sua próxima resposta, sem interromper a tarefa. Quando ele ` +
+            `confirmar ciência ou pedir para não ver mais, chame notification_ack(id).\n`;
+    return out;
+}

package/dist/tools/definitions.js

@@ -9,16 +9,19 @@ export const TOOLS = [
 Use this to record important information, learnings, decisions, or procedures
 that should be remembered for future reference.
 
-The backend classifies the memory by content at write time and returns a
-SUGGESTION (status "proposed"/"universe_only") of which universe/context node it
-belongs to — nothing is moved automatically. Review pending suggestions with
-memory_classification_pending and apply them with memory_classification_approve.
+The backend classifies the memory by content at write time and proposes which
+universe/context node it belongs to. When the tenant has auto-classification
+enabled and the proposal's confidence meets the tenant threshold (the platform
+target is 0.60), the backend ANCHORS the memory on that node automatically — it
+is moved without review. Below the threshold (or with auto-classification off)
+the proposal stays a PENDING suggestion: review it with
+memory_classification_pending and apply with memory_classification_approve.
 
 Passing universe_id or context_id anchors the memory THERE directly (status
 "manual"): auto-classification is skipped entirely, so no suggestion is returned
 and nothing may later move it. The response always reports the destination the
-memory actually landed in — a suggestion, when present, is labelled as pending
-and not applied.
+memory actually landed in — a suggestion that is still pending is labelled as
+such and has NOT been applied.
 
 Memory types:
 - episodic: Specific experiences and events (what happened)
@@ -678,8 +681,15 @@ Useful for maintaining consistency in the knowledge base.`,
         inputSchema: {
             type: "object",
             properties: {
-                similarity_threshold: { type: "number", description: "Similarity threshold 0-1 (default: 0.9)" },
-                limit: { type: "integer", description: "Maximum results (default: 50)" },
+                // NOTE: the backend (POST /consolidation/detect-conflicts →
+                // ConflictDetectionRequest) does NOT accept similarity_threshold for
+                // conflict detection — conflict pairs are found by the forgetting
+                // manager's own analysis, and the field is silently ignored (the
+                // request model inherits _IgnoreExtra). It is kept here only for
+                // forward compatibility; it currently has no effect. Redundant
+                // detection (consolidation_detect_redundant) DOES honour it.
+                similarity_threshold: { type: "number", description: "Currently IGNORED by the backend for conflict detection (kept for forward compatibility). Use consolidation_detect_redundant to tune a similarity threshold." },
+                limit: { type: "integer", description: "Maximum memories to analyze (default: 50)" },
             },
             required: [],
         },
@@ -1845,4 +1855,43 @@ granted it and when. No secret data.`,
             required: ["ref"],
         },
     },
+    // ==========================================================================
+    // Platform Notifications (2)
+    // ==========================================================================
+    {
+        name: "notifications_list",
+        description: `List pending Frinus platform notifications for the current user.
+
+These are platform-authored announcements: new features, maintenance windows,
+tips and alerts. This is a READ-ONLY peek — it does not mark anything as
+delivered or acknowledged, so items stay in the inbox until the user sees them.
+
+Each item includes an \`id\` you can pass to notification_ack once the user has
+read it. Use this when the user asks "what's new" or to re-check news that was
+surfaced earlier in the session.`,
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "notification_ack",
+        description: `Acknowledge a Frinus platform notification by id.
+
+Call this once the user confirms they have seen the news, or asks not to see it
+again. The notification then disappears from the inbox and will not be shown
+again (in this or future sessions). The id comes from the "📣 Novidades do
+Frinus" block or from notifications_list.`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "UUID of the notification to acknowledge (required)",
+                },
+            },
+            required: ["id"],
+        },
+    },
 ];

package/dist/tools/handlers.js

@@ -7,6 +7,7 @@
 import axios from "axios";
 import { spawn } from "node:child_process";
 import { getResolvedTenantOrgId } from "../client/memory-client.js";
+import { fetchNotificationsBlock } from "../notifications.js";
 // ---------------------------------------------------------------------------
 // Credential delivery — server-side broker, never by value
 // ---------------------------------------------------------------------------
@@ -365,14 +366,17 @@ const handlers = {
         const userId = args.user_id || resolvedUserId || undefined;
         const meta = args.metadata || {};
         const universeId = args.universe_id || meta.universe_id || undefined;
-        // Human-in-the-loop classification: the backend classifies the memory by
-        // content at write time and returns a SUGGESTION (classification_status
-        // "proposed"). Nothing is moved automatically — the user reviews via
-        // memory_classification_pending and approves with
-        // memory_classification_approve. The MCP layer no longer injects an
-        // implicit "universe" scope nor surfaces "available universes"; scope,
-        // universe_id and context_id are forwarded ONLY when the caller sets them
-        // (explicit overrides → classification_status "manual").
+        // Write-time classification: the backend classifies the memory by content
+        // and, when the tenant's `auto_classify` setting is enabled and the
+        // proposal confidence meets the tenant threshold, anchors it automatically
+        // (classification_status "proposed"/"universe_only" become real FK columns);
+        // below the threshold it stays a pending SUGGESTION the user reviews via
+        // memory_classification_pending / memory_classification_approve. See
+        // memory/src/api/routers/memories.py (classification/settings). The MCP
+        // layer no longer injects an implicit "universe" scope nor surfaces
+        // "available universes"; scope, universe_id and context_id are forwarded
+        // ONLY when the caller sets them (explicit overrides → status "manual",
+        // which anchors there directly and skips classification).
         try {
             const result = await memoryClient.storeMemory({
                 agent_id: args.agent_id,
@@ -890,7 +894,18 @@ const handlers = {
         }
         formatted += `\n`;
         results.memories.forEach((mem, i) => {
-            formatted += `${i + 1}. [${mem.memory_type}] (id: ${mem.id}) (score: ${mem.weighted_score?.toFixed(2) || mem.similarity?.toFixed(2)})\n`;
+            // Q-MEM-02: /memories/search-with-attention returns `attention_score`
+            // (re-ranked) + `base_similarity` (see memory/src/api/schemas.py
+            // MemoryWithAttentionScore). The legacy field `weighted_score` and the
+            // plain /memories/search field `similarity` are kept as fallbacks so the
+            // same renderer works across endpoints. `?? ` (not `||`) so a real 0 score
+            // is not swallowed.
+            const score = mem.attention_score ??
+                mem.weighted_score ??
+                mem.base_similarity ??
+                mem.similarity;
+            const scoreTxt = typeof score === "number" ? score.toFixed(2) : "n/a";
+            formatted += `${i + 1}. [${mem.memory_type}] (id: ${mem.id}) (score: ${scoreTxt})\n`;
             formatted += `   ${mem.content?.slice(0, 200)}...\n\n`;
         });
         return { content: [{ type: "text", text: formatted }] };
@@ -968,7 +983,7 @@ const handlers = {
     // ==========================================================================
     // Maintenance
     // ==========================================================================
-    async heartbeat_tick(args, { memoryClient }) {
+    async heartbeat_tick(args, { memoryClient, cpClient }) {
         const result = await memoryClient.heartbeatTick({
             agent_id: args.agent_id,
             context_id: args.context_id,
@@ -998,6 +1013,13 @@ const handlers = {
                 formatted += `  ${action}: at interaction ${count}\n`;
             }
         }
+        // Piggyback the notifications check on the heartbeat. fetchNotificationsBlock
+        // self-throttles (at most once per FRINUS_NOTIFICATIONS_INTERVAL_MIN) and
+        // dedupes against what this session already showed, so this is cheap and
+        // never shows the same item twice.
+        const notif = await fetchNotificationsBlock(cpClient, { force: false });
+        if (notif)
+            formatted += `\n${notif}`;
         return { content: [{ type: "text", text: formatted }] };
     },
     async sleep_run(args, { memoryClient }) {
@@ -1035,11 +1057,27 @@ const handlers = {
         if (!conflicts || conflicts.length === 0) {
             return { content: [{ type: "text", text: "No conflicts detected." }] };
         }
-        let formatted = `Detected ${result.conflicts_found || conflicts.length} potential conflicts:\n\n`;
+        let formatted = `Detected ${result.conflicts_found ?? conflicts.length} potential conflicts:\n\n`;
         conflicts.forEach((conflict, i) => {
-            formatted += `${i + 1}. Similarity: ${conflict.similarity?.toFixed(2)}\n`;
-            formatted += `   Memory 1: ${conflict.memory1?.content?.slice(0, 100)}...\n`;
-            formatted += `   Memory 2: ${conflict.memory2?.content?.slice(0, 100)}...\n\n`;
+            // Q-MEM-03: the backend emits `memory_1` / `memory_2` (ConflictPair in
+            // memory/src/api/schemas.py), each with id/content, plus `conflict_type`
+            // and `suggested_action`. The old code read `memory1`/`memory2` (no
+            // underscore) so content printed as "undefined" and the type/action were
+            // dropped. Keep the snake-less variants as a defensive fallback.
+            const m1 = conflict.memory_1 ?? conflict.memory1;
+            const m2 = conflict.memory_2 ?? conflict.memory2;
+            const simTxt = typeof conflict.similarity === "number"
+                ? conflict.similarity.toFixed(2)
+                : "n/a";
+            formatted += `${i + 1}. Similarity: ${simTxt}`;
+            if (conflict.conflict_type)
+                formatted += ` · type: ${conflict.conflict_type}`;
+            formatted += `\n`;
+            formatted += `   Memory 1 (${m1?.id ?? "?"}): ${m1?.content?.slice(0, 100) ?? "(no content)"}...\n`;
+            formatted += `   Memory 2 (${m2?.id ?? "?"}): ${m2?.content?.slice(0, 100) ?? "(no content)"}...\n`;
+            if (conflict.suggested_action)
+                formatted += `   Suggested action: ${conflict.suggested_action}\n`;
+            formatted += `\n`;
         });
         return { content: [{ type: "text", text: formatted }] };
     },
@@ -1062,12 +1100,19 @@ const handlers = {
         if (!groups || groups.length === 0) {
             return { content: [{ type: "text", text: "No redundant memories detected." }] };
         }
-        let formatted = `Detected ${result.groups_found || groups.length} redundant memory groups (${result.total_redundant || 0} total memories):\n\n`;
+        let formatted = `Detected ${result.groups_found ?? groups.length} redundant memory groups (${result.total_redundant ?? 0} redundant memories):\n\n`;
         groups.forEach((group, i) => {
-            formatted += `${i + 1}. Group similarity: ${group.avg_similarity?.toFixed(2) || 'N/A'}\n`;
-            formatted += `   Memories: ${group.memory_ids?.length || 0}\n`;
-            if (group.memories && group.memories.length > 0) {
-                formatted += `   Preview: ${group.memories[0]?.content?.slice(0, 100)}...\n`;
+            // Q-MEM-04: the backend emits `keep` (the memory to retain), `redundant`
+            // (the duplicates) and `total_in_group` (RedundantGroup in
+            // memory/src/api/schemas.py). The old code read `avg_similarity`,
+            // `memory_ids` and `memories`, none of which exist, so every group showed
+            // "N/A" and 0 memories.
+            const redundantCount = Array.isArray(group.redundant) ? group.redundant.length : 0;
+            const total = group.total_in_group ?? (redundantCount + (group.keep ? 1 : 0));
+            formatted += `${i + 1}. Memories in group: ${total} (keep 1, redundant ${redundantCount})\n`;
+            const keepPreview = group.keep?.content?.slice(0, 100);
+            if (keepPreview) {
+                formatted += `   Keep (${group.keep?.id ?? "?"}): ${keepPreview}...\n`;
             }
             formatted += `\n`;
         });
@@ -1209,7 +1254,12 @@ const handlers = {
                 }],
         };
     },
-    async agent_bootstrap(args, { agentClient }) {
+    async agent_bootstrap(args, { agentClient, cpClient }) {
+        // Kick off the notifications fetch concurrently with the bootstrap call so
+        // it adds no latency on the critical path. fetchNotificationsBlock never
+        // throws and self-limits to a 4s timeout, so bootstrap can neither fail nor
+        // stall because of it; the extra .catch is defence in depth.
+        const notifPromise = fetchNotificationsBlock(cpClient, { force: true }).catch(() => "");
         try {
             const result = await agentClient.bootstrapAgent(args.agent_id);
             const identity = result.identity || {};
@@ -1273,6 +1323,9 @@ const handlers = {
             if (delegateDigest && delegateDigest.count > 0 && delegateDigest.summary) {
                 formatted += `\n### Delegate Targets\n${delegateDigest.summary}\n`;
             }
+            const notif = await notifPromise;
+            if (notif)
+                formatted += `\n\n${notif}`;
             return { content: [{ type: "text", text: formatted }] };
         }
         catch (error) {
@@ -2279,6 +2332,81 @@ const handlers = {
             throw error;
         }
     },
+    // ==========================================================================
+    // Platform Notifications
+    // ==========================================================================
+    async notifications_list(_args, { cpClient }) {
+        try {
+            // mark_delivered=false: this is a read-only peek that must NOT consume a
+            // delivery against max_deliveries. Use a higher limit than the automatic
+            // channels so the user can see everything still pending.
+            const inbox = await cpClient.getNotificationInbox({
+                channel: "mcp",
+                limit: 10,
+                markDelivered: false,
+            });
+            const items = inbox?.items || [];
+            if (items.length === 0) {
+                return { content: [{ type: "text", text: "No pending Frinus notifications." }] };
+            }
+            let text = `${items.length} pending Frinus notification${items.length === 1 ? "" : "s"}:\n\n`;
+            items.forEach((it) => {
+                const sev = it.severity ? `[${it.severity}] ` : "";
+                text += `- ${sev}${it.title} (id: ${it.id})\n`;
+                let body = (it.body || "").trim();
+                if (body.length > 300)
+                    body = body.slice(0, 300).trimEnd() + "…";
+                if (body)
+                    text += `  ${body.replace(/\n+/g, " ")}\n`;
+                if (it.cta_url)
+                    text += `  → ${it.cta_label ? `${it.cta_label}: ` : ""}${it.cta_url}\n`;
+            });
+            text += `\nCall notification_ack(id) once the user has seen one so it stops appearing.`;
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            if (error?.response?.status === 404) {
+                // CP without the notifications endpoint yet — treat as empty, not error.
+                return { content: [{ type: "text", text: "No pending Frinus notifications." }] };
+            }
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+    },
+    async notification_ack(args, { cpClient }) {
+        const id = args.id || "";
+        if (!id) {
+            return {
+                content: [{ type: "text", text: "notification_ack requires an 'id'." }],
+                isError: true,
+            };
+        }
+        try {
+            await cpClient.ackNotification(id);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Notification ${id} acknowledged. It will no longer appear in the inbox.`,
+                    }],
+            };
+        }
+        catch (error) {
+            if (error?.response?.status === 404) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Notification ${id} not found (already acknowledged, expired, or not for you).`,
+                        }],
+                };
+            }
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+    },
 };
 // ---------------------------------------------------------------------------
 // Dispatcher: looks up the handler and executes it with error handling

package/dist/types/index.d.ts

@@ -58,6 +58,24 @@ export interface AgentClientInterface {
         timeout_seconds?: number;
     }): Promise<any>;
 }
+/** A single platform notification served by the Control Plane inbox. */
+export interface NotificationItem {
+    id: string;
+    slug: string;
+    title: string;
+    body: string;
+    kind: string;
+    severity: string;
+    cta_label?: string | null;
+    cta_url?: string | null;
+    starts_at?: string | null;
+    expires_at?: string | null;
+}
+/** Response shape of GET /api/v1/notifications/inbox. */
+export interface NotificationInbox {
+    items: NotificationItem[];
+    count: number;
+}
 /** Public surface of the CpClient used by handlers. */
 export interface CpClientInterface {
     createUniverse(orgId: string, data: {
@@ -71,6 +89,12 @@ export interface CpClientInterface {
         description?: string;
     }): Promise<any>;
     deleteUniverse(orgId: string, universeId: string): Promise<void>;
+    getNotificationInbox(opts?: {
+        channel?: string;
+        limit?: number;
+        markDelivered?: boolean;
+    }): Promise<NotificationInbox>;
+    ackNotification(id: string): Promise<void>;
     storeCredential(integrationRef: string, data: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<any>;
     getCredential(integrationRef: string): Promise<any>;
     listCredentials(): Promise<any>;

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "frinus",
   "display_name": "Frinus — Memória Cognitiva",
-  "version": "3.6.3",
+  "version": "3.7.0",
   "description": "Memória cognitiva de longo prazo para o Claude (φρήν + νοῦς). 83 ferramentas de memória, sessões, agentes e conhecimento.",
   "long_description": "O Frinus dá ao Claude memória de longo prazo, identidade e inteligência persistente entre conversas. Conecta o Claude Desktop à plataforma Frinus (Memory Engine, Control Plane e Agent Service) via MCP. Basta colar sua chave de API pessoal — nada para instalar ou compilar.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.6.3",
+  "version": "3.7.0",
   "description": "Frinus - MCP Server for Cognitive Memory (φρήν + νοῦς). Long-term memory, sessions, agents and knowledge for Claude and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "node --import tsx --test tests/*.test.ts",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "pack:mcpb": "./scripts/pack-mcpb.sh",