frinus-mcp 3.7.0 → 3.8.0

package/README.md

@@ -11,7 +11,7 @@ It does **not** run on its own. It stores nothing locally: every tool call is fo
 
 With those in place, the server exposes **70 tools** spanning cognitive memory, working memory, sessions, agents, the L0–L3 knowledge hierarchy, orchestration tasks, and training pipelines. It speaks stdio and works with any MCP-aware client.
 
-- **Version:** 3.4.1
+- **Version:** 3.8.0
 - **Tools:** 70 (see [Tools Reference](#tools-reference))
 - **Platform:** https://frinus.rdxsec.com.br (hosted SaaS — the backend this server talks to)
 - **npm package:** [`frinus-mcp`](https://www.npmjs.com/package/frinus-mcp)

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

@@ -1,4 +1,4 @@
-import type { CpClientInterface, NotificationInbox } from "../types/index.js";
+import type { CpClientInterface, NotificationInbox, OwnerNotificationCreate } from "../types/index.js";
 export declare class CpClient implements CpClientInterface {
     private client;
     constructor(baseURL: string, apiKey: string);
@@ -19,6 +19,13 @@ export declare class CpClient implements CpClientInterface {
         markDelivered?: boolean;
     }): Promise<NotificationInbox>;
     ackNotification(id: string): Promise<void>;
+    /**
+     * Publish an organization-scoped notice (owner only). The Control Plane forces
+     * scope='organization' and target_org_id to the caller's org; the owner only
+     * supplies the message and optional role/user targeting. Uses the normal 30s
+     * timeout: unlike the inbox poll, this is a deliberate user action.
+     */
+    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>;

package/dist/client/cp-client.js

@@ -62,6 +62,16 @@ export class CpClient {
             timeout: NOTIFICATION_TIMEOUT_MS,
         });
     }
+    /**
+     * Publish an organization-scoped notice (owner only). The Control Plane forces
+     * scope='organization' and target_org_id to the caller's org; the owner only
+     * supplies the message and optional role/user targeting. Uses the normal 30s
+     * timeout: unlike the inbox poll, this is a deliberate user action.
+     */
+    async createOrgNotification(data) {
+        const response = await this.client.post(`/api/v1/notifications/manage`, data);
+        return response.data;
+    }
     // =========================================================================
     // Credential Vault
     // =========================================================================

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

@@ -38,9 +38,22 @@ export declare class MemoryClient implements MemoryClientInterface {
         created_by_user_id?: string;
         metadata?: Record<string, unknown>;
         context_id?: string;
+        context_path?: string;
         credential_ref?: string;
         universe_id?: string;
     }): Promise<any>;
+    /**
+     * hierarchy_find — read-only preview of the hierarchy nodes that best match a
+     * free-text query. Reuses the write-time classifier's node index (never
+     * writes). The agent calls it before memory_store (to copy a context_path) and
+     * before a tree-specific search. Universe permission is enforced server-side;
+     * an explicit universe_id the caller cannot read returns 403.
+     */
+    findHierarchy(data: {
+        query_text: string;
+        universe_id?: string;
+        limit?: number;
+    }): Promise<any>;
     searchMemories(data: {
         query_text: string;
         agent_id?: string;

package/dist/client/memory-client.js

@@ -98,6 +98,11 @@ export class MemoryClient {
             payload.created_by_user_id = data.created_by_user_id;
         if (data.context_id)
             payload.context_id = data.context_id;
+        // Anchor by NAME (Onda 3): the backend resolves the breadcrumb to a node and
+        // uses it as the anchor target / classifier hint. Precedence is enforced by
+        // the backend: context_id (UUID) > context_path (name) > universe_id.
+        if (data.context_path)
+            payload.context_path = data.context_path;
         if (data.credential_ref)
             payload.credential_ref = data.credential_ref;
         if (data.universe_id)
@@ -105,6 +110,22 @@ export class MemoryClient {
         const response = await this.client.post("/memories", payload);
         return response.data;
     }
+    /**
+     * hierarchy_find — read-only preview of the hierarchy nodes that best match a
+     * free-text query. Reuses the write-time classifier's node index (never
+     * writes). The agent calls it before memory_store (to copy a context_path) and
+     * before a tree-specific search. Universe permission is enforced server-side;
+     * an explicit universe_id the caller cannot read returns 403.
+     */
+    async findHierarchy(data) {
+        const payload = { query_text: data.query_text };
+        if (data.universe_id)
+            payload.universe_id = data.universe_id;
+        if (typeof data.limit === "number")
+            payload.limit = data.limit;
+        const response = await this.client.post("/graph/classify-preview", payload);
+        return response.data;
+    }
     async searchMemories(data) {
         const response = await this.client.post("/memories/search", {
             query_text: data.query_text,

package/dist/index.js

@@ -22,6 +22,20 @@ import { getResolvedClient, setResolvedClient } from "./client/client-info.js";
 import { InteractionCapture } from "./capture/interaction-capture.js";
 import { TOOLS } from "./tools/definitions.js";
 import { dispatchTool } from "./tools/handlers.js";
+import { getSessionId, noteToolCall, reorientBanner, setSessionId } from "./tools/boot-state.js";
+import { MCP_VERSION } from "./version.js";
+// Irreducible boot rules injected into the client's system prompt via the MCP
+// `initialize` handshake (Claude Code places server `instructions` there). These
+// are the rules that MUST survive even if a single tool response is truncated or
+// skimmed — the structural backstop behind the Boot Contract block.
+const SERVER_INSTRUCTIONS = [
+    "Frinus MCP — regras de boot que nunca podem cair:",
+    "1. No início da sessão, chame agent_bootstrap(agent_id=...) e adote o \"Contrato de Boot\" no TOPO da resposta: identidade, ORGANIZAÇÃO (grave memórias só nela), usuário, session_id e a cadência de reorient. O system prompt longo vem depois do contrato.",
+    "2. Quando QUALQUER resposta de tool trouxer \"⚠️ REORIENT DEVIDO\", chame agent_reorient(agent_id=...) antes de continuar. O MCP conta as tool calls por você.",
+    "3. Confirme a organização do Contrato de Boot ANTES da primeira escrita de memória — nunca grave na org errada.",
+    "4. A sessão é gerenciada pelo MCP (iniciada no agent_bootstrap, encerrada no fim do processo). Não precisa fechá-la à mão.",
+    "Se o MCP/bootstrap estiver indisponível, avise \"MCP Frinus offline — capacidades reduzidas.\" e opere com cautela.",
+].join("\n");
 // Defaults point at the Frinus SaaS so `npx -y frinus-mcp` works with only an
 // API key. Local development overrides these via env (MEMORY_SERVICE_URL, etc.).
 const MEMORY_SERVICE_URL = process.env.MEMORY_SERVICE_URL || "https://frinus-memory.rdxsec.com.br";
@@ -95,11 +109,60 @@ async function main() {
     console.error(`[Auth] API key validated. User: ${getResolvedUserEmail()}, Tenant: ${getResolvedTenantOrgId() || 'none'}`);
     const server = new Server({
         name: "frinus",
-        version: "3.7.0",
+        version: MCP_VERSION,
     }, {
         capabilities: {
             tools: {},
         },
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    // --- Session lifecycle: close on process exit ---------------------------
+    // The session is OPENED by agent_bootstrap (the MCP owns it, not the model).
+    // Here we guarantee it is CLOSED when the process goes away: Claude Code
+    // closing stdin, a SIGTERM/SIGINT, or the event loop draining. We run
+    // session_summary then session_end under a short timeout so a slow/unreachable
+    // Memory Engine can never hang shutdown. Idempotent via the `closing` guard.
+    let closing = false;
+    const SHUTDOWN_TIMEOUT_MS = 3000;
+    const closeSession = async (reason) => {
+        if (closing)
+            return;
+        closing = true;
+        const sid = getSessionId();
+        if (!sid)
+            return;
+        console.error(`[Session] Closing ${sid} (${reason})`);
+        const work = (async () => {
+            try {
+                await memoryClient.getSessionSummary(sid);
+            }
+            catch (err) {
+                console.error(`[Session] summary failed: ${err?.message || err}`);
+            }
+            try {
+                await memoryClient.endSession(sid);
+            }
+            catch (err) {
+                console.error(`[Session] end failed: ${err?.message || err}`);
+            }
+        })();
+        await Promise.race([
+            work,
+            new Promise((resolve) => setTimeout(resolve, SHUTDOWN_TIMEOUT_MS)),
+        ]);
+        setSessionId(null);
+    };
+    const shutdownAndExit = (reason) => {
+        void closeSession(reason).finally(() => process.exit(0));
+    };
+    process.once("SIGTERM", () => shutdownAndExit("SIGTERM"));
+    process.once("SIGINT", () => shutdownAndExit("SIGINT"));
+    // stdin close = the MCP client (Claude Code) disconnected.
+    process.stdin.on("close", () => shutdownAndExit("stdin-close"));
+    // Last-resort backstop when the loop drains without a signal. Does not force
+    // exit (lets the natural exit proceed after a best-effort close).
+    process.once("beforeExit", () => {
+        void closeSession("beforeExit");
     });
     // List tools handler (all tools always visible; backend enforces auth)
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -125,6 +188,26 @@ async function main() {
         catch (err) {
             console.error('[MCP] Capture failed:', err.message);
         }
+        // Deterministic reorient cadence (see tools/boot-state.ts): count this call,
+        // then, if the agent is overdue, append the REORIENT DUE banner to the result
+        // so the model cannot miss it. Repeats on every call until agent_reorient
+        // resets the counter. Never throws into the response path.
+        try {
+            noteToolCall(name);
+            const banner = reorientBanner();
+            if (banner) {
+                const last = toolResult.content?.[toolResult.content.length - 1];
+                if (last && last.type === "text") {
+                    last.text += banner;
+                }
+                else {
+                    toolResult.content = [...(toolResult.content || []), { type: "text", text: banner.trimStart() }];
+                }
+            }
+        }
+        catch (err) {
+            console.error('[MCP] Reorient cadence check failed:', err?.message || err);
+        }
         return toolResult;
     });
     // Resolve the connecting MCP client's identity for the X-Client header.

package/dist/notifications.d.ts

@@ -9,13 +9,18 @@
  * 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.
+ *  - In-process session state, per MCP process (= per session): WHEN each item
+ *    was last shown, and when we last hit the inbox. Dedupe is a sliding WINDOW,
+ *    not "forever": a long-lived process re-presents an un-acked item once the
+ *    reprompt window elapses, so an ignored notice resurfaces on a later
+ *    heartbeat instead of vanishing for the whole session. The server still caps
+ *    total deliveries (counted at most once/day per user), so this cannot spam.
  *  - Env toggles: FRINUS_NOTIFICATIONS=off disables everything;
- *    FRINUS_NOTIFICATIONS_INTERVAL_MIN overrides the throttle window (default 60).
+ *    FRINUS_NOTIFICATIONS_INTERVAL_MIN overrides the FETCH throttle (default 60);
+ *    FRINUS_NOTIFICATIONS_REPROMPT_MIN overrides how long an already-shown item
+ *    stays suppressed before it may be re-presented (default 1440 = 24h).
  */
-import type { CpClientInterface } from "./types/index.js";
+import type { CpClientInterface, NotificationItem } from "./types/index.js";
 /** Reset module state. Test-only; not part of the runtime surface. */
 export declare function __resetNotificationsState(): void;
 export interface FetchBlockOptions {
@@ -28,3 +33,12 @@ export interface FetchBlockOptions {
  * failure). Guaranteed not to throw.
  */
 export declare function fetchNotificationsBlock(cpClient: CpClientInterface, opts?: FetchBlockOptions): Promise<string>;
+/**
+ * Render the markdown block the agent relays to the user. Exported so another
+ * frente can insert it at the TOP of the boot contract (the preferred place —
+ * appended at the end, a ~15k-token bootstrap buries it and the model skips it).
+ *
+ * The block is self-contained: it tells the agent to relay briefly, to ack on
+ * the user's confirmation, and — for `critical` items — to relay IMMEDIATELY.
+ */
+export declare function renderBlock(items: NotificationItem[]): string;

package/dist/notifications.js

@@ -1,17 +1,22 @@
 /** Max characters of a notification body rendered inline. */
 const BODY_LIMIT = 600;
-/** Default throttle window for non-forced checks (minutes). */
+/** Default FETCH throttle window for non-forced checks (minutes). */
 const DEFAULT_INTERVAL_MIN = 60;
+/** Default reprompt window: how long a shown item stays suppressed (minutes). */
+const DEFAULT_REPROMPT_MIN = 1440; // 24h — aligns with the server's per-day delivery count.
 // ---------------------------------------------------------------------------
 // In-process session state
 // ---------------------------------------------------------------------------
-/** Notification ids already shown in this session (dedupe across bootstrap + ticks). */
-const shownIds = new Set();
+/**
+ * Epoch ms each notification id was last SHOWN in this session. Used for a
+ * windowed dedupe: an item is re-presentable once `now - shownAt > reprompt`.
+ */
+const shownAt = new Map();
 /** 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();
+    shownAt.clear();
     lastCheckAt = 0;
 }
 function isDisabled() {
@@ -23,6 +28,12 @@ function throttleMs() {
     const minutes = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_INTERVAL_MIN;
     return minutes * 60_000;
 }
+function repromptMs() {
+    const raw = process.env.FRINUS_NOTIFICATIONS_REPROMPT_MIN;
+    const parsed = raw !== undefined ? Number.parseInt(raw, 10) : NaN;
+    const minutes = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_REPROMPT_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
@@ -50,19 +61,47 @@ export async function fetchNotificationsBlock(cpClient, opts = {}) {
         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));
+    const now2 = Date.now();
+    const window = repromptMs();
+    const fresh = (inbox?.items || []).filter((it) => {
+        if (!it || typeof it.id !== "string")
+            return false;
+        const last = shownAt.get(it.id);
+        // Unseen this session, or last shown long enough ago to re-present.
+        return last === undefined || now2 - last >= window;
+    });
     if (fresh.length === 0)
         return "";
     for (const it of fresh)
-        shownIds.add(it.id);
+        shownAt.set(it.id, now2);
     return renderBlock(fresh);
 }
-/** Render the markdown block the agent relays to the user. */
-function renderBlock(items) {
+/** Human label for a notification scope, used in the rendered header. */
+function scopeLabel(scope) {
+    if (scope === "organization")
+        return "Organização";
+    if (scope === "system")
+        return "Sistema";
+    return "Sistema"; // default/unknown: treat as a platform notice.
+}
+/**
+ * Render the markdown block the agent relays to the user. Exported so another
+ * frente can insert it at the TOP of the boot contract (the preferred place —
+ * appended at the end, a ~15k-token bootstrap buries it and the model skips it).
+ *
+ * The block is self-contained: it tells the agent to relay briefly, to ack on
+ * the user's confirmation, and — for `critical` items — to relay IMMEDIATELY.
+ */
+export function renderBlock(items) {
+    const hasCritical = items.some((it) => it.severity === "critical");
     let out = `## 📣 Novidades do Frinus\n\n`;
     for (const it of items) {
-        const sev = it.severity ? ` _(${it.severity})_` : "";
-        out += `### ${it.title}${sev}\n`;
+        const label = scopeLabel(it.scope);
+        const sev = it.severity ? ` · _${it.severity}_` : "";
+        out += `### [${label}] ${it.title}${sev}\n`;
+        if (it.severity === "critical") {
+            out += `> ⚠️ CRÍTICO — repasse ao usuário IMEDIATAMENTE, antes de seguir com a tarefa.\n`;
+        }
         let body = (it.body || "").trim();
         if (body.length > BODY_LIMIT) {
             body = body.slice(0, BODY_LIMIT).trimEnd() + "…";
@@ -78,9 +117,18 @@ function renderBlock(items) {
         out += `\n_id: ${it.id}_\n\n`;
     }
     out += `---\n`;
+    if (hasCritical) {
+        out +=
+            `Há um aviso CRÍTICO acima: repasse-o ao usuário IMEDIATAMENTE, no início ` +
+                `da sua próxima resposta. `;
+    }
+    else {
+        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. `;
+    }
     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`;
+        `Avisos marcados [Sistema] vêm do Frinus; [Organização] vêm da própria ` +
+            `organização do usuário. Quando ele confirmar ciência ou pedir para não ` +
+            `ver mais, chame notification_ack(id).\n`;
     return out;
 }

package/dist/tools/boot-state.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Boot-contract state for the MCP process (one instance per stdio session).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The thin-client boot protocol used to depend entirely on the model
+ * remembering to call `agent_reorient` "every N answers". Models forget. This
+ * module makes the reorient cadence DETERMINISTIC and server-side (here, inside
+ * the MCP process) instead of a hope:
+ *
+ *   - `agent_bootstrap` calls `markBooted()` with the agent's reorient config
+ *     (read from the authoritative Control Plane row via the bootstrap payload).
+ *   - Every subsequent tool call increments a counter (`noteToolCall`).
+ *   - Once the counter reaches `reorientEveryN`, `reorientBanner()` returns a
+ *     "REORIENT DUE" notice that `index.ts` appends to EVERY tool result until
+ *     `agent_reorient` is actually called, which resets the counter.
+ *
+ * The context-percentage trigger (`reorientOnContextPct`) cannot be enforced
+ * here — the MCP has no visibility into the model's token window — so it stays a
+ * model-side heuristic documented in the Boot Contract and the server
+ * `instructions`. The N-count is the half we CAN guarantee, and we guarantee it.
+ *
+ * State is per-process (= per session). Nothing here is persisted.
+ */
+/** Reorientation cadence knobs, mirrored from `org_agents` via the bootstrap. */
+export interface ReorientConfig {
+    reorientEveryN: number;
+    reorientOnContextPct: number;
+}
+/** Mark the process as booted and (re)seed the reorient cadence + session id. */
+export declare function markBooted(opts: {
+    agentId: string;
+    sessionId?: string | null;
+    config?: Partial<ReorientConfig>;
+}): void;
+/** Reset the cadence counter (called when the agent actually reorients). */
+export declare function resetReorientCounter(): void;
+/**
+ * Record a tool call. Exempt tools do not increment; `agent_reorient` resets.
+ * No-op until the process has booted, so pre-boot probing never arms the banner.
+ */
+export declare function noteToolCall(name: string): void;
+/** True once at least `reorientEveryN` counted tool calls have elapsed. */
+export declare function reorientDue(): boolean;
+/**
+ * The "REORIENT DUE" banner, or null when not due. Deliberately imperative and
+ * self-explaining so it survives even if the model ignored the Boot Contract.
+ */
+export declare function reorientBanner(): string | null;
+export declare function getBootAgentId(): string | null;
+export declare function getSessionId(): string | null;
+export declare function setSessionId(id: string | null): void;
+export declare function isBooted(): boolean;
+export declare function getReorientConfig(): ReorientConfig;
+/** Test-only: reset all module state. Not part of the runtime surface. */
+export declare function __resetBootState(): void;

package/dist/tools/boot-state.js

@@ -0,0 +1,115 @@
+/**
+ * Boot-contract state for the MCP process (one instance per stdio session).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The thin-client boot protocol used to depend entirely on the model
+ * remembering to call `agent_reorient` "every N answers". Models forget. This
+ * module makes the reorient cadence DETERMINISTIC and server-side (here, inside
+ * the MCP process) instead of a hope:
+ *
+ *   - `agent_bootstrap` calls `markBooted()` with the agent's reorient config
+ *     (read from the authoritative Control Plane row via the bootstrap payload).
+ *   - Every subsequent tool call increments a counter (`noteToolCall`).
+ *   - Once the counter reaches `reorientEveryN`, `reorientBanner()` returns a
+ *     "REORIENT DUE" notice that `index.ts` appends to EVERY tool result until
+ *     `agent_reorient` is actually called, which resets the counter.
+ *
+ * The context-percentage trigger (`reorientOnContextPct`) cannot be enforced
+ * here — the MCP has no visibility into the model's token window — so it stays a
+ * model-side heuristic documented in the Boot Contract and the server
+ * `instructions`. The N-count is the half we CAN guarantee, and we guarantee it.
+ *
+ * State is per-process (= per session). Nothing here is persisted.
+ */
+const DEFAULT_CONFIG = {
+    reorientEveryN: 10,
+    reorientOnContextPct: 70,
+};
+let config = { ...DEFAULT_CONFIG };
+let booted = false;
+let bootAgentId = null;
+let sessionId = null;
+let toolCallsSinceReorient = 0;
+/**
+ * Tools that must never count toward the cadence: `agent_bootstrap` seeds it and
+ * `agent_reorient` IS the reorientation (and resets the counter).
+ */
+const EXEMPT_TOOLS = new Set(["agent_bootstrap", "agent_reorient"]);
+/** Mark the process as booted and (re)seed the reorient cadence + session id. */
+export function markBooted(opts) {
+    booted = true;
+    bootAgentId = opts.agentId;
+    if (opts.sessionId)
+        sessionId = opts.sessionId;
+    if (opts.config) {
+        const n = opts.config.reorientEveryN;
+        if (typeof n === "number" && Number.isFinite(n) && n >= 1) {
+            config.reorientEveryN = Math.floor(n);
+        }
+        const pct = opts.config.reorientOnContextPct;
+        if (typeof pct === "number" && Number.isFinite(pct) && pct >= 1 && pct <= 100) {
+            config.reorientOnContextPct = Math.floor(pct);
+        }
+    }
+    toolCallsSinceReorient = 0;
+}
+/** Reset the cadence counter (called when the agent actually reorients). */
+export function resetReorientCounter() {
+    toolCallsSinceReorient = 0;
+}
+/**
+ * Record a tool call. Exempt tools do not increment; `agent_reorient` resets.
+ * No-op until the process has booted, so pre-boot probing never arms the banner.
+ */
+export function noteToolCall(name) {
+    if (!booted)
+        return;
+    if (EXEMPT_TOOLS.has(name)) {
+        if (name === "agent_reorient")
+            resetReorientCounter();
+        return;
+    }
+    toolCallsSinceReorient += 1;
+}
+/** True once at least `reorientEveryN` counted tool calls have elapsed. */
+export function reorientDue() {
+    return booted && toolCallsSinceReorient >= config.reorientEveryN;
+}
+/**
+ * The "REORIENT DUE" banner, or null when not due. Deliberately imperative and
+ * self-explaining so it survives even if the model ignored the Boot Contract.
+ */
+export function reorientBanner() {
+    if (!reorientDue())
+        return null;
+    const id = bootAgentId ?? "<agent_id>";
+    return (`\n\n---\n` +
+        `⚠️ REORIENT DEVIDO: ${toolCallsSinceReorient} tool calls desde o último ` +
+        `boot/reorient (limite ${config.reorientEveryN}). Chame ` +
+        `\`agent_reorient(agent_id="${id}")\` agora para se re-fundamentar antes de ` +
+        `continuar. Este aviso repete a cada tool call até você reorientar.`);
+}
+export function getBootAgentId() {
+    return bootAgentId;
+}
+export function getSessionId() {
+    return sessionId;
+}
+export function setSessionId(id) {
+    sessionId = id;
+}
+export function isBooted() {
+    return booted;
+}
+export function getReorientConfig() {
+    return { ...config };
+}
+/** Test-only: reset all module state. Not part of the runtime surface. */
+export function __resetBootState() {
+    config = { ...DEFAULT_CONFIG };
+    booted = false;
+    bootAgentId = null;
+    sessionId = null;
+    toolCallsSinceReorient = 0;
+}

package/dist/tools/definitions.js

@@ -9,6 +9,19 @@ export const TOOLS = [
 Use this to record important information, learnings, decisions, or procedures
 that should be remembered for future reference.
 
+ANCHORING (do this first): memory lives in a tree — Universe > Concept > Theme >
+Topic > Point. Before storing, call hierarchy_find("<subject>") and copy the best
+candidate's context_path (BY NAME, e.g. "Plataforma Frinus > Memory Engine") into
+context_path below. The path raises the classifier's confidence and anchors the
+memory on the right node. Never invent a UUID — you get names right, UUIDs wrong.
+
+PRECEDENCE of the placement arguments (highest first):
+  context_id (UUID) > context_path (name) > universe_id > the agent's own
+  universe > auto-classification > the org's "Geral" (floor, never NULL).
+A context_path that is ambiguous or whose segments don't all match never creates
+a node and never fails the write: it anchors to the deepest segment that matched
+and the response carries a non-fatal context_path_warning saying so.
+
 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
@@ -17,11 +30,11 @@ 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 that is still pending is labelled as
-such and has NOT been applied.
+Passing context_path, universe_id or context_id anchors the memory accordingly
+(status "manual" for UUIDs): auto-classification is skipped and nothing may later
+move it. The response always reports the destination the 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)
@@ -88,7 +101,11 @@ Scopes:
                 },
                 context_id: {
                     type: "string",
-                    description: "Optional UUID of a hierarchy node (universe, concept, theme, topic, or point). When provided, the memory is automatically linked to this node and all its ancestors. Takes precedence over universe_id for hierarchy placement.",
+                    description: "Optional UUID of a hierarchy node (universe, concept, theme, topic, or point). When provided, the memory is automatically linked to this node and all its ancestors. Highest-precedence placement argument (above context_path and universe_id).",
+                },
+                context_path: {
+                    type: "string",
+                    description: "Anchor the memory BY NAME with a breadcrumb like 'Universe > Concept > Theme' (separators /, > or › all work). Call hierarchy_find first and copy the best candidate's context_path here — this is the preferred way to place a memory. The backend resolves names to a node deterministically (never creates nodes). Takes precedence over universe_id, but not over context_id. If a segment is ambiguous or unknown the write still succeeds, anchors to the deepest matched segment, and returns a context_path_warning.",
                 },
                 credential_ref: {
                     type: "string",
@@ -98,6 +115,43 @@ Scopes:
             required: ["agent_id", "content"],
         },
     },
+    {
+        name: "hierarchy_find",
+        description: `Find where something belongs in the memory tree (Universe >
+Concept > Theme > Topic > Point).
+
+Read-only: it never writes a memory or a node. It runs the same classifier the
+backend uses at write time and returns the top candidate nodes for your query,
+each with its full path BY NAME and a confidence in [0,1].
+
+Call it in two moments:
+- BEFORE memory_store — copy the best candidate's context_path (by name) into
+  memory_store(context_path=...) so the memory anchors on the right node and
+  clears the 0.60 auto-anchor threshold instead of landing in the review queue.
+- BEFORE a tree-specific search — to confirm which branch to look in.
+
+Copy the context_path (the names), never the context_id (UUID). Universe
+permission is enforced: a restricted caller only sees candidates in universes it
+may read, and an explicit universe_id it cannot read is rejected (403).`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                query_text: {
+                    type: "string",
+                    description: "What to situate in the tree — the subject of the memory you are about to store, or the search you are about to run.",
+                },
+                universe_id: {
+                    type: "string",
+                    description: "Optional UUID to restrict candidates to one universe (must be one you may read). Omit to search every universe you can access.",
+                },
+                limit: {
+                    type: "integer",
+                    description: "Max candidates to return (default 5, max 25).",
+                },
+            },
+            required: ["query_text"],
+        },
+    },
     {
         name: "memory_search",
         description: `Search memories by semantic similarity.
@@ -860,7 +914,11 @@ Memories created by the agent are NOT deleted.`,
         name: "agent_bootstrap",
         description: `Bootstrap completo do agente — chame no início da sessão para carregar identidade, system prompt e contexto runtime. O agente thin-client chama isto como regra única de boot.
 
-Retorna identity, system_prompt, runtime (working_memory, recent_memories, skills, delegate_digest) e persona_version em uma única chamada.
+A resposta começa por um "Contrato de Boot" no TOPO com o que não pode se perder: identidade (id), organização (grave memórias só nela), usuário, versão do MCP, session_id, persona_version e a cadência de reorient. O system prompt longo vem depois.
+
+Efeitos colaterais: inicia a sessão de memória (session_id devolvido no contrato; o MCP a encerra no fim do processo) e arma a cadência de reorient — a partir daqui o MCP conta as tool calls e anexa um aviso "REORIENT DEVIDO" quando vencer.
+
+Retorna identity, system_prompt, runtime (working_memory, recent_memories, skills, delegate_digest), config (reorient_every_n, reorient_on_context_pct, max_memories) e persona_version.
 
 O roster de especialistas NÃO vem no bootstrap — apenas um resumo (quantos e em quais universos). Use \`agent_list\` no momento da delegação para obter nomes e IDs.`,
         inputSchema: {
@@ -1856,15 +1914,16 @@ granted it and when. No secret data.`,
         },
     },
     // ==========================================================================
-    // Platform Notifications (2)
+    // Platform Notifications (3)
     // ==========================================================================
     {
         name: "notifications_list",
-        description: `List pending Frinus platform notifications for the current user.
+        description: `List pending Frinus 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.
+Two scopes appear here: (Sistema) = platform-authored (new features, maintenance,
+tips, alerts), and (Organização) = authored by an owner of the user's own org.
+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
@@ -1894,4 +1953,67 @@ Frinus" block or from notifications_list.`,
             required: ["id"],
         },
     },
+    {
+        name: "notification_create",
+        description: `Publish an ORGANIZATION notification to the members of your org (OWNER only).
+
+Use this when an org owner wants to broadcast something to their team through the
+Frinus channel: a process change, a reminder, a heads-up. The notice is delivered
+on each member's next agent_bootstrap / heartbeat and leaves their inbox when they
+acknowledge it (or after max_deliveries days of being shown-and-ignored).
+
+Scope is forced server-side: the notice is bound to YOUR org and cannot target
+other orgs (that is a platform_admin "system" notice, created elsewhere). Optional
+targeting narrows WITHIN your org by role and/or specific users. Requires owner
+role — a 403 means the account is not an owner. Use severity "critical" only for
+things the member must see immediately (it is relayed before other work).`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Short headline (required, 1–200 chars)" },
+                body: {
+                    type: "string",
+                    description: "Message body, markdown allowed (optional, up to 2000 chars)",
+                },
+                kind: {
+                    type: "string",
+                    enum: ["feature", "announcement", "maintenance", "tip", "alert"],
+                    description: "Category (default 'announcement')",
+                },
+                severity: {
+                    type: "string",
+                    enum: ["info", "success", "warning", "critical"],
+                    description: "Visual/priority level (default 'info'; 'critical' is relayed immediately)",
+                },
+                target_roles: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional: only members with one of these roles (e.g. ['trainer']). Empty = all members.",
+                },
+                target_user_keys: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional: only these specific users (user id/sub or email). Empty = all members.",
+                },
+                cta_label: { type: "string", description: "Optional call-to-action label" },
+                cta_url: {
+                    type: "string",
+                    description: "Optional call-to-action URL (must be https://)",
+                },
+                starts_at: {
+                    type: "string",
+                    description: "Optional ISO-8601 start time (default: now)",
+                },
+                expires_at: {
+                    type: "string",
+                    description: "Optional ISO-8601 expiry time (default: never)",
+                },
+                max_deliveries: {
+                    type: "number",
+                    description: "How many days an unseen notice is shown before it drops off (default 3, 1–100)",
+                },
+            },
+            required: ["title"],
+        },
+    },
 ];

package/dist/tools/handlers.js

@@ -8,6 +8,8 @@ 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
 // ---------------------------------------------------------------------------
@@ -330,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
@@ -342,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) {
@@ -350,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 = {
     // ==========================================================================
@@ -387,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,
@@ -400,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)
     // ==========================================================================
@@ -1254,7 +1300,7 @@ const handlers = {
                 }],
         };
     },
-    async agent_bootstrap(args, { agentClient, cpClient }) {
+    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
@@ -1264,20 +1310,69 @@ const handlers = {
             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`;
@@ -1295,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 || [];
@@ -1309,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`;
             }
@@ -1323,9 +1431,19 @@ 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}`;
+            // 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) {
@@ -1338,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`;
@@ -2352,7 +2474,8 @@ const handlers = {
             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`;
+                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() + "…";
@@ -2407,6 +2530,75 @@ const handlers = {
             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

@@ -66,11 +66,28 @@ export interface NotificationItem {
     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[];
@@ -95,6 +112,7 @@ export interface CpClientInterface {
         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>;
@@ -132,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>;
@@ -141,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.7.0",
-  "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.7.0",
+  "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",