frinus-mcp 3.6.4 → 3.8.0

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: {
@@ -1855,4 +1913,107 @@ granted it and when. No secret data.`,
             required: ["ref"],
         },
     },
+    // ==========================================================================
+    // Platform Notifications (3)
+    // ==========================================================================
+    {
+        name: "notifications_list",
+        description: `List pending Frinus notifications for the current user.
+
+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
+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"],
+        },
+    },
+    {
+        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"],
+        },
+    },
 ];