frinus-mcp 3.6.4 → 3.8.0

package/dist/tools/handlers.js

@@ -7,6 +7,9 @@
 import axios from "axios";
 import { spawn } from "node:child_process";
 import { getResolvedTenantOrgId } from "../client/memory-client.js";
+import { fetchNotificationsBlock } from "../notifications.js";
+import { MCP_VERSION } from "../version.js";
+import { getSessionId, markBooted, resetReorientCounter } from "./boot-state.js";
 // ---------------------------------------------------------------------------
 // Credential delivery — server-side broker, never by value
 // ---------------------------------------------------------------------------
@@ -329,6 +332,12 @@ function renderStoreResult(result) {
     const id = result?.id;
     const status = result?.classification_status;
     const head = `✓ Salva`;
+    // Non-fatal note when a supplied context_path did not fully resolve by name
+    // (ambiguous or missing segment). The memory WAS stored; this is appended to
+    // whatever destination line we render below so the caller can fix the path.
+    const warning = typeof result?.context_path_warning === "string" && result.context_path_warning
+        ? `\n  ⚠ context_path: ${result.context_path_warning}`
+        : "";
     const applied = appliedLabel(result);
     const pending = status === "proposed" || status === "universe_only";
     // Anchored: a real destination exists. Report it, and only then mention a
@@ -341,7 +350,7 @@ function renderStoreResult(result) {
                 out += `\n  ↳ sugestão pendente (NÃO aplicada): ${sug} — revise com memory_classification_pending`;
             }
         }
-        return out;
+        return out + warning;
     }
     // Not anchored anywhere: the suggestion is all we have to offer.
     if (pending) {
@@ -349,12 +358,12 @@ function renderStoreResult(result) {
         const conf = confidenceLabel(result?.classification_confidence);
         if (sug) {
             const confTxt = conf ? `, confiança ${conf}` : "";
-            return `${head} · sem destino aplicado · sugestão: ${sug} (auto${confTxt}) — aprove com memory_classification_approve`;
+            return `${head} · sem destino aplicado · sugestão: ${sug} (auto${confTxt}) — aprove com memory_classification_approve` + warning;
         }
-        return `${head} · sem destino aplicado e sem sugestão confiável — use memory_classification_pending para revisar`;
+        return `${head} · sem destino aplicado e sem sugestão confiável — use memory_classification_pending para revisar` + warning;
     }
     // Defensive: older backend without classification fields, or no hierarchy at all.
-    return `${head}\nID: ${id}\nType: ${result?.memory_type}\nScope: ${result?.scope}`;
+    return `${head}\nID: ${id}\nType: ${result?.memory_type}\nScope: ${result?.scope}` + warning;
 }
 const handlers = {
     // ==========================================================================
@@ -386,6 +395,7 @@ const handlers = {
                 created_by_user_id: createdByUser,
                 metadata: args.metadata,
                 context_id: args.context_id,
+                context_path: args.context_path,
                 credential_ref: args.credential_ref,
                 universe_id: universeId,
                 scope: args.scope,
@@ -399,6 +409,43 @@ const handlers = {
             throw error;
         }
     },
+    async hierarchy_find(args, { memoryClient }) {
+        let result;
+        try {
+            result = await memoryClient.findHierarchy({
+                query_text: args.query_text,
+                universe_id: args.universe_id,
+                limit: args.limit,
+            });
+        }
+        catch (error) {
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+        const candidates = Array.isArray(result?.candidates) ? result.candidates : [];
+        if (candidates.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Nenhum nó candidato para esta consulta. Salve mesmo assim (o backend classifica ou cai no universo/Geral), ou refine a consulta.",
+                    }],
+            };
+        }
+        let formatted = "Nós candidatos (copie o caminho POR NOME para memory_store(context_path=...)):\n\n";
+        candidates.forEach((c, i) => {
+            const path = typeof c?.context_path === "string" ? c.context_path : "(sem caminho)";
+            const conf = confidenceLabel(c?.confidence);
+            const confTxt = typeof c?.confidence === "number"
+                ? ` (confiança ${c.confidence.toFixed(2)}${conf ? ` · ${conf}` : ""})`
+                : "";
+            const level = c?.level ? ` [${c.level}]` : "";
+            formatted += `${i + 1}. ${path}${level}${confTxt}\n`;
+        });
+        formatted += "\nCopie o caminho (os nomes), não o context_id. Confiança ≥ 0,60 ancora sozinho; abaixo disso vai para a fila de revisão.";
+        return { content: [{ type: "text", text: formatted }] };
+    },
     // ==========================================================================
     // Auto-classification (human-in-the-loop)
     // ==========================================================================
@@ -982,7 +1029,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,
@@ -1012,6 +1059,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 }) {
@@ -1246,25 +1300,79 @@ const handlers = {
                 }],
         };
     },
-    async agent_bootstrap(args, { agentClient }) {
+    async agent_bootstrap(args, { agentClient, cpClient, memoryClient, capture, resolvedUserEmail, resolvedUserId }) {
+        // 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 || {};
             const runtime = result.runtime || {};
+            const bootConfig = result.config || {};
+            const agentIdStr = String(identity.id || args.agent_id || "");
+            // --- Session lifecycle: the MCP owns it ------------------------------
+            // The boot protocol must not depend on the model remembering to call
+            // session_start / session_end. We start the formal session HERE (once per
+            // process) and record it in the boot state; the process-exit hooks in
+            // index.ts close it (session_summary + session_end). Best-effort: a
+            // Memory Engine hiccup must never make bootstrap fail.
+            let activeSessionId = getSessionId();
+            if (!activeSessionId) {
+                try {
+                    const s = await memoryClient.startSession({ agent_id: agentIdStr });
+                    activeSessionId = s?.session_id || null;
+                    if (activeSessionId)
+                        capture.sessionId = activeSessionId;
+                }
+                catch (err) {
+                    console.error("[MCP] bootstrap session_start failed:", err?.message || err);
+                }
+            }
+            // Arm the deterministic reorient cadence from the authoritative config.
+            const reorientEveryN = Number(bootConfig.reorient_every_n) || 10;
+            const reorientPct = Number(bootConfig.reorient_on_context_pct) || 70;
+            markBooted({
+                agentId: agentIdStr,
+                sessionId: activeSessionId,
+                config: { reorientEveryN, reorientOnContextPct: reorientPct },
+            });
+            // --- Boot Contract (TOP: highest-attention, never-truncated-away) -----
+            // Everything the agent cannot afford to lose goes here, ABOVE the long
+            // system prompt (which the model tends to skim at the tail). Identity,
+            // the org it may write to, the user, the session, and the reorient
+            // cadence. The long persona/protocol text follows.
+            const orgId = identity.org_id || getResolvedTenantOrgId() || "unknown";
+            const orgName = identity.org_name ? `${identity.org_name} ` : "";
+            const userEmail = resolvedUserEmail || "desconhecido";
+            const userId = resolvedUserId ? ` \`${resolvedUserId}\`` : "";
+            const roleTxt = identity.role || identity.specialization;
+            // Notifications (system + org) go at the very TOP, above the contract:
+            // a critical notice must be the first thing the agent reads. The fetch
+            // ran concurrently with bootstrapAgent, so awaiting here adds no latency.
+            const notif = await notifPromise;
             let formatted = `# Agent Bootstrap\n\n`;
-            formatted += `## Identity\n`;
-            if (identity.id)
-                formatted += `ID: ${identity.id}\n`;
-            if (identity.name)
-                formatted += `Name: ${identity.name}\n`;
-            if (identity.role || identity.specialization)
-                formatted += `Role: ${identity.role || identity.specialization}\n`;
+            formatted += `<!-- ALERTS_SLOT -->\n`;
+            if (notif)
+                formatted += `${notif.trimEnd()}\n\n`;
+            formatted += `## ⚙️ Contrato de Boot (CRÍTICO — leia e adote ANTES de tudo)\n`;
+            formatted += `- Agente: ${identity.name || "?"} \`${agentIdStr}\`\n`;
+            if (roleTxt)
+                formatted += `- Papel: ${roleTxt}\n`;
+            formatted += `- Organização: ${orgName}\`${orgId}\` — grave memórias SOMENTE nesta org (confira antes da 1ª escrita)\n`;
+            formatted += `- Usuário: ${userEmail}${userId}\n`;
+            formatted += `- MCP: frinus v${MCP_VERSION}`;
+            if (activeSessionId)
+                formatted += ` · Sessão: ${activeSessionId}`;
+            if (result.persona_version !== undefined)
+                formatted += ` · Persona: ${result.persona_version}`;
+            formatted += `\n`;
+            formatted += `- Reorient: a cada ${reorientEveryN} tool calls OU ~${reorientPct}% de contexto → \`agent_reorient(agent_id="${agentIdStr}")\`. O MCP conta as chamadas e anexa um aviso automático quando vencer — não dependa da sua memória.\n`;
             if (identity.universe_id)
-                formatted += `Universe: ${identity.universe_id}\n`;
+                formatted += `- Universe: \`${identity.universe_id}\`\n`;
             if (identity.team_id)
-                formatted += `Team: ${identity.team_id}\n`;
-            if (result.persona_version !== undefined)
-                formatted += `Persona Version: ${result.persona_version}\n`;
+                formatted += `- Team: \`${identity.team_id}\`\n`;
             formatted += `\n`;
             if (result.system_prompt) {
                 formatted += `## System Prompt\n${result.system_prompt}\n\n`;
@@ -1282,7 +1390,14 @@ const handlers = {
             if (recentMemories.length > 0) {
                 formatted += `\n### Recent Memories (${recentMemories.length})\n`;
                 recentMemories.forEach((mem, i) => {
-                    formatted += `${i + 1}. [${mem.memory_type || "memory"}] ${mem.content?.slice(0, 150)}\n`;
+                    // The server sends `type` (not `memory_type`); accept both so the
+                    // label is real instead of a constant "[memory]". Surface the id so
+                    // the agent can reinforce/weaken/get it, and the importance so it can
+                    // weight it. Content cut raised from 150 to 400 chars.
+                    const t = mem.type || mem.memory_type || "memory";
+                    const idTxt = mem.id ? ` (id: ${mem.id})` : "";
+                    const imp = typeof mem.importance === "number" ? ` (importance: ${mem.importance.toFixed(2)})` : "";
+                    formatted += `${i + 1}. [${t}]${idTxt}${imp} ${mem.content?.slice(0, 400)}\n`;
                 });
             }
             const skills = runtime.skills || [];
@@ -1296,8 +1411,14 @@ const handlers = {
                 skills.forEach((s) => {
                     const name = s.skill_name || s.name || s.slug || s;
                     const slug = s.slug ? ` \`${s.slug}\`` : "";
+                    // version/permission come from the server (skill_version / permission)
+                    // and were previously discarded. They tell the agent which revision it
+                    // holds and whether it may edit the playbook.
+                    const ver = s.version || s.skill_version;
+                    const verTxt = ver ? ` v${ver}` : "";
+                    const perm = s.permission ? ` [${s.permission}]` : "";
                     const desc = s.description ? ` — ${s.description}` : "";
-                    formatted += `- ${name}${slug}${desc}\n`;
+                    formatted += `- ${name}${slug}${verTxt}${perm}${desc}\n`;
                 });
                 formatted += `</skills_catalog>\n`;
             }
@@ -1310,6 +1431,19 @@ const handlers = {
             if (delegateDigest && delegateDigest.count > 0 && delegateDigest.summary) {
                 formatted += `\n### Delegate Targets\n${delegateDigest.summary}\n`;
             }
+            // Shallow tree map (universe → concept) for orientation. The lines are
+            // already composed and truncated server-side; print them verbatim. Use
+            // hierarchy_find(query) for the exact node, universe_hierarchy for the
+            // full tree.
+            const hierarchyMap = runtime.hierarchy_map || [];
+            if (Array.isArray(hierarchyMap) && hierarchyMap.length > 0) {
+                formatted += `\n### Árvore (navegação)\n`;
+                formatted += `Mapa raso para orientação; use hierarchy_find(query) para achar o nó exato e universe_hierarchy para a árvore completa.\n`;
+                hierarchyMap.forEach((line) => {
+                    if (typeof line === "string" && line)
+                        formatted += `- ${line}\n`;
+                });
+            }
             return { content: [{ type: "text", text: formatted }] };
         }
         catch (error) {
@@ -1322,6 +1456,10 @@ const handlers = {
     async agent_reorient(args, { memoryClient }) {
         try {
             const result = await memoryClient.reorientAgent(args.agent_id, args.focus);
+            // Deterministic cadence: reorienting clears the "reorient due" counter so
+            // the auto-appended banner stops until the next N tool calls elapse. Done
+            // regardless of what the server returns.
+            resetReorientCounter();
             const identity = result.identity || {};
             let formatted = `# Agent Reorient\n\n`;
             formatted += `## Identity\n`;
@@ -2316,6 +2454,151 @@ 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}] ` : "";
+                const scope = it.scope === "organization" ? "(Organização) " : "(Sistema) ";
+                text += `- ${scope}${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;
+        }
+    },
+    async notification_create(args, { cpClient }) {
+        const title = args.title?.trim() || "";
+        if (!title) {
+            return {
+                content: [{ type: "text", text: "notification_create requires a non-empty 'title'." }],
+                isError: true,
+            };
+        }
+        // Owner scope only: the Control Plane forces scope='organization' and binds
+        // the notice to the caller's own org — the owner cannot target other orgs.
+        const payload = { title };
+        if (typeof args.body === "string")
+            payload.body = args.body;
+        if (typeof args.kind === "string")
+            payload.kind = args.kind;
+        if (typeof args.severity === "string")
+            payload.severity = args.severity;
+        if (Array.isArray(args.target_roles))
+            payload.target_roles = args.target_roles;
+        if (Array.isArray(args.target_user_keys))
+            payload.target_user_keys = args.target_user_keys;
+        if (typeof args.cta_label === "string")
+            payload.cta_label = args.cta_label;
+        if (typeof args.cta_url === "string")
+            payload.cta_url = args.cta_url;
+        if (typeof args.starts_at === "string")
+            payload.starts_at = args.starts_at;
+        if (typeof args.expires_at === "string")
+            payload.expires_at = args.expires_at;
+        if (typeof args.max_deliveries === "number")
+            payload.max_deliveries = args.max_deliveries;
+        try {
+            const created = await cpClient.createOrgNotification(payload);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Organization notification created (id: ${created?.id ?? "?"}). It will reach the ` +
+                            `members of your org on their next bootstrap/heartbeat, newest-critical first, ` +
+                            `and leaves each member's inbox on ack or after max_deliveries days unseen.`,
+                    }],
+            };
+        }
+        catch (error) {
+            const status = error?.response?.status;
+            if (status === 403) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Only an org owner can create organization notifications. This account is not an owner of the org.",
+                        }],
+                    isError: true,
+                };
+            }
+            if (status === 422) {
+                const detail = error?.response?.data?.detail;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `notification_create rejected: ${typeof detail === "string" ? detail : JSON.stringify(detail)}`,
+                        }],
+                    isError: true,
+                };
+            }
+            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,41 @@ 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;
+    /** "system" (platform-wide) or "organization" (owner of this org). */
+    scope?: string;
+    cta_label?: string | null;
+    cta_url?: string | null;
+    starts_at?: string | null;
+    expires_at?: string | null;
+}
+/** Payload an org owner sends to publish an organization-scoped notice. */
+export interface OwnerNotificationCreate {
+    title: string;
+    body?: string;
+    kind?: string;
+    severity?: string;
+    target_roles?: string[];
+    target_user_keys?: string[];
+    cta_label?: string | null;
+    cta_url?: string | null;
+    starts_at?: string | null;
+    expires_at?: string | null;
+    max_deliveries?: number;
+    is_active?: boolean;
+}
+/** 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 +106,13 @@ 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>;
+    createOrgNotification(data: OwnerNotificationCreate): Promise<any>;
     storeCredential(integrationRef: string, data: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<any>;
     getCredential(integrationRef: string): Promise<any>;
     listCredentials(): Promise<any>;
@@ -108,6 +150,7 @@ export interface MemoryClientInterface {
         created_by_user_id?: string;
         metadata?: Record<string, unknown>;
         context_id?: string;
+        context_path?: string;
         credential_ref?: string;
         universe_id?: string;
     }): Promise<any>;
@@ -117,6 +160,11 @@ export interface MemoryClientInterface {
         memory_types?: string[];
         limit?: number;
     }): Promise<any>;
+    findHierarchy(data: {
+        query_text: string;
+        universe_id?: string;
+        limit?: number;
+    }): Promise<any>;
     getMemory(memoryId: string): Promise<any>;
     getAgentMemories(agentId: string, memoryType?: string, limit?: number): Promise<any>;
     deleteMemory(memoryId: string): Promise<any>;

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Single source of truth for the MCP server version.
+ *
+ * Imported by `index.ts` (server `name`/`version` handshake) and by the
+ * `agent_bootstrap` Boot Contract block so the version the user sees always
+ * matches the running build. Keep in sync with `package.json` and
+ * `manifest.json` at release time.
+ */
+export declare const MCP_VERSION = "3.8.0";

package/dist/version.js

@@ -0,0 +1,9 @@
+/**
+ * Single source of truth for the MCP server version.
+ *
+ * Imported by `index.ts` (server `name`/`version` handshake) and by the
+ * `agent_bootstrap` Boot Contract block so the version the user sees always
+ * matches the running build. Keep in sync with `package.json` and
+ * `manifest.json` at release time.
+ */
+export const MCP_VERSION = "3.8.0";

package/manifest.json

@@ -2,8 +2,8 @@
   "manifest_version": "0.3",
   "name": "frinus",
   "display_name": "Frinus — Memória Cognitiva",
-  "version": "3.6.4",
-  "description": "Memória cognitiva de longo prazo para o Claude (φρήν + νοῦς). 83 ferramentas de memória, sessões, agentes e conhecimento.",
+  "version": "3.8.0",
+  "description": "Memória cognitiva de longo prazo para o Claude (φρήν + νοῦς). 91 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": {
     "name": "Frinus",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.6.4",
+  "version": "3.8.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",