frinus-mcp 3.6.4 → 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 } 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);
@@ -13,6 +13,19 @@ export declare class CpClient implements CpClientInterface {
         description?: string;
     }): Promise<any>;
     deleteUniverse(orgId: string, universeId: string): Promise<void>;
+    getNotificationInbox(opts?: {
+        channel?: string;
+        limit?: number;
+        markDelivered?: boolean;
+    }): Promise<NotificationInbox>;
+    ackNotification(id: string): Promise<void>;
+    /**
+     * 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

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

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

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

@@ -0,0 +1,44 @@
+/**
+ * Platform notifications delivered through the MCP channel.
+ *
+ * Clients rarely come back to the web dashboard after the initial integration,
+ * so the MCP session itself becomes the way to reach them. This module fetches
+ * the Control Plane inbox and renders a compact markdown block that is appended
+ * to `agent_bootstrap` (once, forced) and `heartbeat_tick` (throttled).
+ *
+ * Design rules:
+ *  - NEVER throws. A 404, timeout or any network error yields '' plus a stderr
+ *    log. The agent's real work must never be blocked by the news channel.
+ *  - In-process 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 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, NotificationItem } from "./types/index.js";
+/** Reset module state. Test-only; not part of the runtime surface. */
+export declare function __resetNotificationsState(): void;
+export interface FetchBlockOptions {
+    /** Bypass the throttle window (used by agent_bootstrap). */
+    force?: boolean;
+}
+/**
+ * Fetch the inbox and render the "Novidades do Frinus" block, or '' when there
+ * is nothing new to show (disabled, throttled, empty, already-shown, or any
+ * failure). Guaranteed not to throw.
+ */
+export declare function fetchNotificationsBlock(cpClient: CpClientInterface, opts?: FetchBlockOptions): Promise<string>;
+/**
+ * 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

@@ -0,0 +1,134 @@
+/** Max characters of a notification body rendered inline. */
+const BODY_LIMIT = 600;
+/** 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
+// ---------------------------------------------------------------------------
+/**
+ * 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() {
+    shownAt.clear();
+    lastCheckAt = 0;
+}
+function isDisabled() {
+    return (process.env.FRINUS_NOTIFICATIONS || "").trim().toLowerCase() === "off";
+}
+function throttleMs() {
+    const raw = process.env.FRINUS_NOTIFICATIONS_INTERVAL_MIN;
+    const parsed = raw !== undefined ? Number.parseInt(raw, 10) : NaN;
+    const minutes = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_INTERVAL_MIN;
+    return minutes * 60_000;
+}
+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
+ * failure). Guaranteed not to throw.
+ */
+export async function fetchNotificationsBlock(cpClient, opts = {}) {
+    if (isDisabled())
+        return "";
+    const now = Date.now();
+    if (!opts.force && now - lastCheckAt < throttleMs()) {
+        return "";
+    }
+    lastCheckAt = now;
+    let inbox;
+    try {
+        inbox = await cpClient.getNotificationInbox({
+            channel: "mcp",
+            limit: 3,
+            markDelivered: true,
+        });
+    }
+    catch (err) {
+        // 404 (CP not yet deployed), timeout, DNS, connection refused — all benign
+        // here. Swallow and keep working; log to stderr for operators.
+        console.error(`[Notifications] inbox fetch failed: ${err?.message || err}`);
+        return "";
+    }
+    const 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)
+        shownAt.set(it.id, now2);
+    return renderBlock(fresh);
+}
+/** 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 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() + "…";
+        }
+        if (body)
+            out += `${body}\n`;
+        if (it.cta_label && it.cta_url) {
+            out += `\n[${it.cta_label}](${it.cta_url})\n`;
+        }
+        else if (it.cta_url) {
+            out += `\n${it.cta_url}\n`;
+        }
+        out += `\n_id: ${it.id}_\n\n`;
+    }
+    out += `---\n`;
+    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 +=
+        `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;