@astramindapp/mcp-server 0.25.0 → 0.27.0

package/dist/server.js

@@ -12,13 +12,15 @@
  * integration path to use for its runtime, how to authenticate, and the
  * session protocol — without having to be told.
  *
- * Tools (44):
+ * Tools (45):
  *   Memory & knowledge — mind_query, mind_remember, mind_folders,
  *     mind_folder_routes, mind_folder_suggest, mind_share (document share
  *     links), mind_context, mind_graph, mind_insights, mind_research,
  *     mind_train
  *   Life & work — mind_life, mind_focuses, mind_tasks, mind_automate,
  *     mind_notify, mind_checklists (Kanon checklists)
+ *   Agent sessions — mind_sessions (log this session into MIND Chat →
+ *     Agents; see the AGENT SESSION PROTOCOL in ./integration-guide)
  *   People — mind_crm
  *   Social & profile — mind_social, mind_social_analytics, mind_profile,
  *     mind_personas
@@ -84,7 +86,7 @@ const apiDetail = (e) => {
 function createMindMcpServer(client) {
     const server = new mcp_js_1.McpServer({
         name: "mind",
-        version: "0.25.0",
+        version: "0.27.0",
     }, {
         // Returned to every client in the MCP `initialize` response — the first
         // thing any connecting agent sees about how to integrate with MIND.
@@ -94,7 +96,7 @@ function createMindMcpServer(client) {
     // The full integration playbook, readable on demand by any MCP client.
     server.registerResource("integration-guide", "mind://integration-guide", {
         title: "MIND Integration Guide",
-        description: "Complete playbook for integrating any AI agent with MIND — the three integration paths (MCP server, OpenClaw plugin, REST API), authentication, the session protocol, all 44 tools, REST endpoint mapping, and common recipes.",
+        description: "Complete playbook for integrating any AI agent with MIND — the three integration paths (MCP server, OpenClaw plugin, REST API), authentication, the session protocol, all 45 tools, REST endpoint mapping, and common recipes.",
         mimeType: "text/markdown",
     }, async (uri) => ({
         contents: [
@@ -105,10 +107,105 @@ function createMindMcpServer(client) {
             },
         ],
     }));
+    // ─── mind://agent-standard ──────────────────────────────
+    // The full MIND Agent Operating Standard (AGENTS.md, verbatim — see
+    // AGENT_STANDARD_MD in ./integration-guide.ts for provenance and the
+    // refresh recipe). SERVER_INSTRUCTIONS names this resource as mandatory
+    // reading in its "═══ MANDATORY PROTOCOLS ═══" section so an unauthenticated
+    // client sees the pointer even before it can read this resource.
+    server.registerResource("agent-standard", "mind://agent-standard", {
+        title: "The MIND Agent Operating Standard",
+        description: "The full, binding operating constitution for a MIND-connected agent (AGENTS.md, verbatim) — Law Zero, the boot protocol, session sync, the inactivity and termination protocols, the action-time gates, the sense catalog, and the memory contract. SERVER_INSTRUCTIONS names this as mandatory reading; this resource is the complete text.",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: integration_guide_js_1.AGENT_STANDARD_MD,
+            },
+        ],
+    }));
+    // ─── sync-local-docs-to-mind prompt ─────────────────────
+    // Standard prompt shipped WITH the server so any connected agent can back
+    // up the user's durable local documents into MIND without being taught
+    // the procedure from scratch. Body lives in integration-guide.ts beside
+    // SERVER_INSTRUCTIONS and INTEGRATION_GUIDE so all shipped copy is in one
+    // place. MCP prompt arguments are always strings.
+    server.registerPrompt("sync-local-docs-to-mind", {
+        title: "Sync local documents into MIND",
+        description: "Back up every durable document on this machine into the user's MIND, skipping code, junk and secrets. Safe by default: reports what it would upload before uploading anything.",
+        argsSchema: {
+            root: zod_1.z.string().optional().describe("Directory to scan. Default: the current working directory."),
+            dry_run: zod_1.z
+                .string()
+                .optional()
+                .describe('"true" (default) reports the plan without writing. "false" performs the upload.'),
+            since: zod_1.z.string().optional().describe("Only consider files modified after this ISO date."),
+        },
+    }, async ({ root, dry_run, since }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: (0, integration_guide_js_1.buildSyncLocalDocsPrompt)({ root, dry_run, since }),
+                },
+            },
+        ],
+    }));
+    // ─── sync-agent-session prompt ───────────────────────────
+    // Standard prompt shipped WITH the server so any connected agent can adopt
+    // the AGENT SESSION PROTOCOL (see integration-guide.ts) without being
+    // taught the procedure from scratch. Body lives in integration-guide.ts
+    // beside SERVER_INSTRUCTIONS and buildSyncLocalDocsPrompt so all shipped
+    // copy is in one place — see AGENT_SESSION_PROTOCOL_BODY there, which is
+    // also embedded verbatim in SERVER_INSTRUCTIONS and (compact) in the
+    // mind_sessions tool description below, so a client that only reads tool
+    // descriptions still follows it.
+    server.registerPrompt("sync-agent-session", {
+        title: "Adopt the Agent Session Protocol",
+        description: "Log this agent's live session into MIND Chat → Agents so Anthony can read and reply to it. Returns the full open/append/close/handoff protocol, addressed to your runtime.",
+        argsSchema: {
+            runtime: zod_1.z.string().optional().describe('Your runtime name, e.g. "claude-code", "codex", "cursor". Default: "your runtime".'),
+            source_key: zod_1.z.string().optional().describe('The MIND Chat sidebar toggle you were assigned, e.g. "claude-code-1". Default: "your-source-key".'),
+        },
+    }, async ({ runtime, source_key }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: (0, integration_guide_js_1.buildSyncAgentSessionPrompt)({ runtime, source_key }),
+                },
+            },
+        ],
+    }));
+    // ─── adopt-agent-standard prompt ─────────────────────────
+    // Same content as the mind://agent-standard resource (AGENT_STANDARD_MD —
+    // see integration-guide.ts for provenance and the refresh recipe), offered
+    // as a prompt for clients that call prompts/get rather than reading MCP
+    // resources. SERVER_INSTRUCTIONS points every connecting agent at whichever
+    // of the two ("the resource ... or the adopt-agent-standard prompt") its
+    // host actually supports.
+    server.registerPrompt("adopt-agent-standard", {
+        title: "Adopt the MIND Agent Operating Standard",
+        description: "Returns the full MIND Agent Operating Standard (AGENTS.md, verbatim) — Law Zero, the boot protocol, session sync, the inactivity and termination protocols, the action-time gates, the sense catalog, and the memory contract. Read this before acting on behalf of an owner for the first time.",
+    }, async () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: integration_guide_js_1.AGENT_STANDARD_MD,
+                },
+            },
+        ],
+    }));
     // ─── mind_query ─────────────────────────────────────────
     // Semantic search across the user's knowledge graph.
     // Replaces flat MEMORY.md — returns only relevant memories.
-    server.tool("mind_query", "Search your MIND knowledge graph. Returns RETRIEVED CONTEXT from the graph — documents, entries, entities and relationships — NOT a finished answer. YOU must read that context and write the answer yourself. Does not use MIND's LLM and costs 0 credits. Use this BEFORE making decisions — MIND is your memory. (Pass retrieve_only=false to have MIND synthesize the answer instead, which spends credits.)", {
+    server.tool("mind_query", "Search the user's MIND knowledge graph — their persistent memory of people, projects, decisions, outcomes and history. Returns RETRIEVED CONTEXT for YOU to read and synthesize — documents, entries, entities and relationships — NOT a finished answer. Does not use MIND's LLM and costs 0 credits. Call this before asserting anything about the user's world, and before saying something does not exist. (Pass retrieve_only=false to have MIND's own LLM write the answer instead, which spends credits.)\n\nHOW TO ASK — this changes answer quality more than any parameter. Ask a rich, specific, full-sentence question; \"what is X\" retrieves poorly. Best results come from retrieve-then-write in one ask: \"Find everything about X, Y and Z, then write <deliverable> in this shape: <template>. Use only what you found; mark anything missing as unknown and do not invent it.\" Name the thing you expect to find — a document title, a person, a project, a date range. If the first answer is thin, change the QUESTION, not the mode — chain a narrower ask.\n\nPICKING A MODE (mechanical): naive reads document text only — best for recalling an exact passage or wording. local walks a named entity and its immediate graph neighbours — best for one specific person, company or thing. global reasons over relationships and themes across the whole graph — best for cross-cutting patterns. hybrid combines local+global graph reasoning but reads no raw document text. mix adds raw document text on top of hybrid and is the most complete; reach for it when hybrid feels thin. hybrid is the default — drop to naive/local/global only when you specifically need that narrower lens.\n\nNEGATIVES ARE THE HIGHEST-RISK ANSWER. An empty or thin result means your query missed — it is never proof the thing does not exist. Before reporting that something is absent, re-ask with different wording and say what you searched.", {
         query: zod_1.z.string().describe("What to search for in your knowledge graph"),
         mode: zod_1.z
             .enum(["mix", "hybrid", "global", "local", "naive"])
@@ -167,7 +264,7 @@ function createMindMcpServer(client) {
     // ─── mind_remember ──────────────────────────────────────
     // Store/manage content in the knowledge graph. Auto-categorized by type.
     // Enhanced: now supports create, delete, search, get, list actions.
-    server.tool("mind_remember", "Store and manage content in your MIND knowledge graph. Use for facts, decisions, learnings, research, notes — anything worth remembering. Auto-categorized. Always log outcomes here after completing tasks. Supports create (default), delete, search, get, and list.\n\n⚠️ PRIVATE vs PUBLIC: `document` and `entry` are PRIVATE to the user's knowledge graph. `feed_post` is a PUBLIC social-media post that appears on the user's public feed for everyone to see. Default to `entry` for all agent outcomes, logs, decisions, and research. NEVER use `feed_post` unless the user explicitly says \"post\", \"share\", \"tweet\", \"feed\", or \"thought to my feed\" — deploy logs, PR notes, work outcomes, and agent activity belong in `entry`, NOT on the public feed.\n\nTitle rule: lessons are titled 'Lesson - Failure - <behavior>' / 'Lesson - Behavior - <behavior>' / 'Lesson - Win - <behavior>'; never put '/' or parentheses in a title, the card is derived from it.", {
+    server.tool("mind_remember", "Store and manage content in your MIND knowledge graph. Use for facts, decisions, learnings, research, notes — anything worth remembering. Auto-categorized. Always log outcomes here after completing tasks. Supports create (default), delete, search, get, and list.\n\n⚠️ PRIVATE vs PUBLIC: `document` and `entry` are PRIVATE to the user's knowledge graph. `feed_post` is a PUBLIC social-media post that appears on the user's public feed for everyone to see. Default to `entry` for all agent outcomes, logs, decisions, and research. NEVER use `feed_post` unless the user explicitly says \"post\", \"share\", \"tweet\", \"feed\", or \"thought to my feed\" — deploy logs, PR notes, work outcomes, and agent activity belong in `entry`, NOT on the public feed.\n\nTitle rule: lessons are titled 'Lesson - Failure - <behavior>' / 'Lesson - Behavior - <behavior>' / 'Lesson - Win - <behavior>'; never put '/' or parentheses in a title, the card is derived from it.\n\nWRITE FOR THE AGENT WHO WILL SEARCH FOR THIS LATER — retrieval quality is decided here, not at query time. State facts in the words someone will later search for. Put the entity name in the first sentence. Inline dates, ids, file paths and numbers rather than saying \"the PR\" or \"yesterday\" — a note that only says \"fixed it\" is unfindable. If this supersedes an earlier note, say so explicitly and name what it replaces, so the older fact can be closed off instead of silently competing with this one.", {
         action: zod_1.z
             .enum(["create", "delete", "search", "get", "list"])
             .optional()
@@ -355,15 +452,28 @@ function createMindMcpServer(client) {
     // ─── mind_folders ───────────────────────────────────────
     // Organize documents into folders. Folders are a presentation layer — the
     // knowledge graph still indexes every document regardless of folder.
-    server.tool("mind_folders", "Organize your MIND documents into folders. Folders are a presentation layer — the knowledge graph still indexes and retrieves across every document regardless of folder. Use mind_remember to create a document, then mind_folders move_documents to file it. Actions: list, create, rename, move, delete, move_documents, set_hint (set the agent-routing hint read by mind_folder_suggest).", {
+    server.tool("mind_folders", "Organize your MIND documents into folders. Folders are a presentation layer — the knowledge graph still indexes and retrieves across every document regardless of folder. Use mind_remember to create a document, then mind_folders move_documents to file it. Actions: list, create, rename, move, delete, move_documents, set_hint, secure, unsecure, unlock, reset_request, reset (Secure Folders — password-gate a folder).", {
         action: zod_1.z
-            .enum(["list", "create", "rename", "move", "delete", "move_documents", "set_hint"])
-            .describe("list (all folders + counts + routing hints), create (new folder; pass routing_hint to enable agent-routing), rename (change a folder's name), move (re-nest a folder), delete (remove a folder — its documents and subfolders move up a level, nothing is deleted), move_documents (file documents into a folder), set_hint (write/clear the routing_hint that mind_folder_suggest reads)"),
+            .enum([
+            "list",
+            "create",
+            "rename",
+            "move",
+            "delete",
+            "move_documents",
+            "set_hint",
+            "secure",
+            "unsecure",
+            "unlock",
+            "reset_request",
+            "reset",
+        ])
+            .describe("list (all folders + counts + routing hints + secure/locked flags), create (new folder; pass routing_hint to enable agent-routing), rename (change a folder's name), move (re-nest a folder), delete (remove a folder — its documents and subfolders move up a level, nothing is deleted), move_documents (file documents into a folder), set_hint (write/clear the routing_hint that mind_folder_suggest reads), secure (password-gate folder_id — pass passphrase; changing an existing passphrase needs an active unlock first), unsecure (turn off secure mode — needs an active unlock), unlock (verify passphrase, mints a 15-minute unlock kept in memory for this session and sent on every later call), reset_request (email a one-time reset link to the account email), reset (complete a reset — pass token + new_passphrase)"),
         name: zod_1.z.string().optional().describe("Folder name — required for create and rename"),
         folder_id: zod_1.z
             .string()
             .optional()
-            .describe("Folder id — the folder to rename/move/delete/set_hint, or the destination for move_documents (omit or pass 'root' to file documents at the top level)"),
+            .describe("Folder id — the folder to rename/move/delete/set_hint/secure/unsecure/unlock/reset_request/reset, or the destination for move_documents (omit or pass 'root' to file documents at the top level)"),
         parent_id: zod_1.z
             .string()
             .optional()
@@ -376,7 +486,23 @@ function createMindMcpServer(client) {
             .string()
             .optional()
             .describe("Free-text instruction answering \"when should MIND save things to this folder?\". Read by mind_folder_suggest to LLM-route new content. Pass on create to set up-front; pass on set_hint to update. Pass empty string to clear (disables the folder from auto-routing)."),
-    }, async ({ action, name, folder_id, parent_id, doc_ids, routing_hint }) => {
+        passphrase: zod_1.z
+            .string()
+            .optional()
+            .describe("Folder passphrase — required for secure and unlock"),
+        new_passphrase: zod_1.z
+            .string()
+            .optional()
+            .describe("New passphrase — required for reset"),
+        token: zod_1.z
+            .string()
+            .optional()
+            .describe("One-time reset token from the reset email — required for reset"),
+        unlock_token: zod_1.z
+            .string()
+            .optional()
+            .describe("Pass the exact `unlock_token` string returned by a prior 'unlock' call here to carry a 15-minute unlock into a later 'secure' (passphrase change) or 'unsecure' call. Not needed for the first time a folder is secured, and not used by list/create/rename/move/delete/move_documents/set_hint/unlock/reset_request/reset. This stdio server keeps unlock tokens in memory for the whole session and normally attaches them automatically (see 'unlock'), so passing this explicitly is usually redundant — but when supplied it takes precedence over the remembered token, so the same request shape works on both this server and the hosted MCP."),
+    }, async ({ action, name, folder_id, parent_id, doc_ids, routing_hint, passphrase, new_passphrase, token, unlock_token }) => {
         try {
             switch (action) {
                 case "list": {
@@ -396,7 +522,8 @@ function createMindMcpServer(client) {
                         const parent = f.parent_id ? byId.get(f.parent_id)?.name ?? "?" : "(top level)";
                         const hint = (f.routing_hint || "").trim();
                         const hintTail = hint ? ` · hint: ${hint.length > 80 ? hint.slice(0, 80) + "…" : hint}` : "";
-                        return `• ${f.name} — ${f.document_count ?? 0} doc(s) · id: ${f.id} · parent: ${parent}${hintTail}`;
+                        const secureTail = f.secure ? (f.locked ? " · 🔒 secure (locked)" : " · 🔓 secure (unlocked)") : "";
+                        return `• ${f.name} — ${f.document_count ?? 0} doc(s) · id: ${f.id} · parent: ${parent}${hintTail}${secureTail}`;
                     });
                     return {
                         content: [
@@ -490,6 +617,73 @@ function createMindMcpServer(client) {
                         ],
                     };
                 }
+                case "secure": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to secure a folder");
+                    if (!passphrase)
+                        throw new Error("'passphrase' is required to secure a folder");
+                    const res = await client.secureFolder(folder_id, passphrase, unlock_token);
+                    return {
+                        content: [
+                            { type: "text", text: `Folder ${res.folder_id} is now secure. Unlock it with action 'unlock' before reading its contents.` },
+                        ],
+                    };
+                }
+                case "unsecure": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to unsecure a folder");
+                    const res = await client.unsecureFolder(folder_id, unlock_token);
+                    client.clearSecureFolderUnlockToken(folder_id);
+                    return {
+                        content: [{ type: "text", text: `Folder ${res.folder_id} is no longer secure.` }],
+                    };
+                }
+                case "unlock": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to unlock a folder");
+                    if (!passphrase)
+                        throw new Error("'passphrase' is required to unlock a folder");
+                    const res = await client.unlockFolder(folder_id, passphrase);
+                    client.setSecureFolderUnlockToken(folder_id, res.unlock_token);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Unlocked. Expires at ${res.expires_at} (15 minutes) — every mind_query / mind_folders / document call this session will see inside it until then.`,
+                            },
+                        ],
+                    };
+                }
+                case "reset_request": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to request a passphrase reset");
+                    const res = await client.requestFolderReset(folder_id);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: res.status === "sent"
+                                    ? `Reset email sent to the account's email address (expires in 15 minutes).`
+                                    : `Reset requested, but email delivery is not configured on this deployment.`,
+                            },
+                        ],
+                    };
+                }
+                case "reset": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to reset a passphrase");
+                    if (!token)
+                        throw new Error("'token' (from the reset email) is required to reset a passphrase");
+                    if (!new_passphrase)
+                        throw new Error("'new_passphrase' is required to reset a passphrase");
+                    const res = await client.resetFolder(folder_id, token, new_passphrase);
+                    client.clearSecureFolderUnlockToken(folder_id);
+                    return {
+                        content: [
+                            { type: "text", text: `Passphrase reset for folder ${res.folder_id}. Unlock it with the new passphrase.` },
+                        ],
+                    };
+                }
                 default:
                     throw new Error(`Unknown action: ${action}`);
             }
@@ -653,7 +847,7 @@ function createMindMcpServer(client) {
     // Get structured always-loaded context.
     // Equivalent to OpenClaw's SOUL.md + USER.md + AGENTS.md bootstrap injection,
     // but backed by the knowledge graph.
-    server.tool("mind_context", "Get your persistent context from MIND — identity, preferences, rules, and recent activity. Returns RETRIEVED CONTEXT (not a finished briefing). YOU synthesize who you are and what matters. Does not use MIND's LLM and costs 0 credits. Call this at the start of every session.", {
+    server.tool("mind_context", "Load the user's persistent context from MIND at session start — identity, preferences, operating rules, current priorities and recent activity. Returns RETRIEVED CONTEXT for YOU to synthesize, NOT a finished briefing. Does not use MIND's LLM and costs 0 credits. Call this at the start of every session.\n\nPass only the `sections` you actually need for the task at hand — a focused payload measurably outperforms the full default set, because the model attends better to fewer, more relevant facts. Every fact carries a date; when two facts conflict, the newer one wins, and say so if you rely on it. An empty `recent` section means nothing was logged, not that nothing happened — follow up with mind_query before assuming a quiet day. This is a snapshot, not the whole graph; for anything specific, follow up with mind_query.", {
         sections: zod_1.z
             .array(zod_1.z.enum(["soul", "user", "rules", "priorities", "recent"]))
             .optional()
@@ -1230,7 +1424,7 @@ function createMindMcpServer(client) {
     // ─── mind_tasks ─────────────────────────────────────────
     // Site-wide tasks: assignable, completable work items that attach to a
     // Life project, a CRM contact, an agent, or stand alone.
-    server.tool("mind_tasks", "Manage site-wide tasks in MIND — assignable, completable, reportable work items. A task can attach to a Life project (parent_type=life_item), a CRM contact (parent_type=contact), an agent (parent_type=agent), or stand alone. Assign tasks to a MIND member, an agent, or an external email. Use action=reports for completion analytics.", {
+    server.tool("mind_tasks", "Manage site-wide tasks — assignable, completable work items that are lighter-weight than a Life project/outcome and simpler than a Kanon checklist item. Reach for mind_tasks for a single actionable to-do (optionally attached to a Life project via parent_type=life_item, a CRM contact via parent_type=contact, or an agent) that needs an owner and a done/not-done state; reach for mind_life when the work is itself a deliverable inside the Focus→Project→Outcome hierarchy, and mind_checklists when you need a multi-item checklist with a progress rollup. Assign tasks to a MIND member, an agent, or an external email. Actions: list/create/get/update/complete/reopen/assign/delete, reports (completion analytics). An empty list means no tasks exist under that filter, not that no work is happening — check mind_life and mind_checklists for the same window before concluding nothing is tracked.", {
         action: zod_1.z
             .enum([
             "list", "create", "get", "update", "complete", "reopen",
@@ -1436,7 +1630,7 @@ function createMindMcpServer(client) {
     // ─── mind_crm ───────────────────────────────────────────
     // Read/write contacts, interactions, and activities.
     // Enhanced: delete, get, log_activity, list_activities.
-    server.tool("mind_crm", "Manage contacts and relationships in MIND CRM. Use for tracking people, companies, leads, interaction history, and activity logging.", {
+    server.tool("mind_crm", "Manage contacts and relationships in MIND CRM — the system of record for people, companies, leads and prospects, separate from the knowledge graph's document/entry memory. Reach for this (not mind_query) when you need to create, update, or list a specific contact record, or log/read a dated interaction history — reach for mind_query when you want a synthesized answer about a relationship drawn from everything MIND knows. Actions: list/create/update/delete/get contacts, log_activity (record an interaction), list_activities (interaction history). An empty list or 'No contacts found' means no CRM records exist yet, not that the person is unknown to MIND — check mind_query before concluding a relationship is undocumented.", {
         action: zod_1.z
             .enum(["list", "create", "update", "delete", "get", "log_activity", "list_activities"])
             .describe("What to do: list/create/update/delete/get contacts, log_activity (record interaction), list_activities (view interaction history)"),
@@ -1588,7 +1782,7 @@ function createMindMcpServer(client) {
     // ─── mind_graph ─────────────────────────────────────────
     // Get graph statistics, diagnostics, and labels.
     // Enhanced: action param with stats (default), diagnostics, labels.
-    server.tool("mind_graph", "Get MIND knowledge graph statistics, diagnostics, and label details. Use to check graph health, growth, and entity breakdown.", {
+    server.tool("mind_graph", "Get MIND knowledge graph statistics and diagnostics — entity/relationship counts, growth, label breakdown, and health status. Use this for a quantitative pulse-check on the graph itself (e.g. before a large ingestion, or to cite \"MIND has N entities\"); it does not search or retrieve content, so for facts, people or history use mind_query instead. Actions: stats (default overview), diagnostics (health check), labels (entity type breakdown). A low or zero count can mean an empty tenant OR a scoping/auth issue reading the wrong account — verify with mind_query on a known fact before treating a small graph as evidence nothing has been logged.", {
         action: zod_1.z
             .enum(["stats", "diagnostics", "labels"])
             .optional()
@@ -2044,7 +2238,7 @@ function createMindMcpServer(client) {
     // ═══════════════════════════════════════════════════════════
     // ─── mind_sense ─────────────────────────────────────────
     // MINDsense emotional intelligence layer.
-    server.tool("mind_sense", "Access MINDsense emotional intelligence — the user's living emotional state, signal history, emotional timeline, and KG entity weights. Use this to understand how the user is feeling and what emotionally significant events have occurred.", {
+    server.tool("mind_sense", "Access MINDsense — the user's live emotional state, signal history, spikes and emotionally-weighted entities, derived from valence/arousal signal processing rather than asked directly. Reach for this before a sensitive conversation, when deciding how hard to push on a topic, or when asked \"how am I feeling\" / \"read the room\"; reach for mind_query instead for factual history about what happened. Actions: state (current snapshot), signals (recent raw signals), timeline (historical trend), kg_weights (which entities carry emotional weight), spikes (notable events, some unacknowledged), acknowledge (clear a spike), summary (AI-written recap). No signals in the lookback window means nothing was captured in that period, not that the user was neutral — widen `days` before concluding calm.", {
         action: zod_1.z
             .enum(["state", "signals", "timeline", "kg_weights", "spikes", "acknowledge", "summary"])
             .describe("Action: state (current emotion), signals (recent signals), timeline (historical), kg_weights (emotionally weighted entities), spikes (recent spikes), acknowledge (ack a spike), summary (AI emotional summary)"),
@@ -2143,7 +2337,7 @@ function createMindMcpServer(client) {
     });
     // ─── mind_research ──────────────────────────────────────
     // Deep research agent jobs.
-    server.tool("mind_research", "Launch and manage deep research jobs. Research runs autonomously — it gathers information, analyzes it, and stores findings in the knowledge graph. Use for competitive analysis, market research, technical deep-dives.", {
+    server.tool("mind_research", "Launch and track autonomous deep-research jobs — MIND gathers sources, synthesizes them, and writes findings into the knowledge graph as it goes. Use this for a genuinely open-ended investigation (competitive analysis, market research, a technical deep-dive) that would take multiple search rounds; use mind_query for a quick fact lookup instead. Actions: start (launch, returns job_id), status (poll progress and read the summary once complete), list (all jobs). A job still 'running' has no findings yet — poll status again rather than treating a thin or missing summary as a negative result; once complete, read the findings via mind_query rather than re-reading the raw job.", {
         action: zod_1.z
             .enum(["start", "status", "list"])
             .describe("Action: start (launch research), status (check job progress), list (view all jobs)"),
@@ -2210,7 +2404,7 @@ function createMindMcpServer(client) {
     });
     // ─── mind_train ─────────────────────────────────────────
     // Self-training and chat-to-KG sessions.
-    server.tool("mind_train", "Train MIND's knowledge graph. Start guided training sessions to teach it about yourself, or save existing chat conversations into the knowledge graph for persistent memory.", {
+    server.tool("mind_train", "Run guided or freeform sessions that teach MIND about the user through conversation, or extract an existing chat transcript into the knowledge graph as durable memories — this is how unstructured conversation becomes queryable facts, distinct from mind_remember (one explicit fact) or mind_query (reading facts back). Actions: start (begin a session, optionally typed: basics/network/expertise/history/goals/freeform), chat (send the next training message), status (progress + items learned so far), list_sessions, pause/resume, save_chat (extract a chat session_id into the graph). 'Items learned: 0' or an empty list_sessions means no training has happened yet in this account, not that the user has nothing worth learning — check mind_query for what's already there before starting a duplicate session.", {
         action: zod_1.z
             .enum(["start", "chat", "status", "list_sessions", "pause", "resume", "save_chat"])
             .describe("Action: start (begin training), chat (send message), status (check progress), list_sessions (view past), pause/resume (control session), save_chat (save chat to KG)"),
@@ -2533,7 +2727,7 @@ function createMindMcpServer(client) {
     });
     // ─── mind_profile ───────────────────────────────────────
     // Profile, prompts, and model preferences.
-    server.tool("mind_profile", "Manage your MIND profile, AI prompt settings, and model preferences. Update your bio, set custom system prompts for chat and thought generation, and choose your preferred LLM model.", {
+    server.tool("mind_profile", "Manage the user's own MIND profile, public-chat prompt, and model preferences — bio, display name, the system prompt used at their public /m/{username} chat surface, and their default LLM model. This is account/identity settings, not knowledge-graph content — for what MIND knows about the user, use mind_context or mind_query instead. Actions: get/update (profile fields), get_chat_prompt/set_chat_prompt, get_thought_prompt/set_thought_prompt, get_model/set_model/list_models. 'No custom prompt set' on get_chat_prompt/get_thought_prompt means the platform default applies, not that chat is unconfigured — call list_models before set_model if unsure a model id is valid, since an unrecognized id fails at the provider, not here.", {
         action: zod_1.z
             .enum([
             "get", "update",
@@ -2653,7 +2847,7 @@ function createMindMcpServer(client) {
     });
     // ─── mind_insights ──────────────────────────────────────
     // ALE insights and analytics.
-    server.tool("mind_insights", "Access insights from MIND's Autonomous Learning Engine — patterns detected in your knowledge graph, weekly summaries, and proactive intelligence. Also trigger on-demand analysis.", {
+    server.tool("mind_insights", "Read what MIND's Autonomous Learning Engine has already noticed about the user without being asked — patterns, weekly summaries, and proactive intelligence generated in the background — or trigger a fresh analysis pass on demand. Reach for this when the user asks \"what have you noticed\" or \"anything I'm missing\"; reach for mind_query when you already know what you're looking for. Actions: list (recent insights), unread_count, view (read one, marks it seen), feedback (rate helpful/not_helpful — tunes future insights), analyze (trigger a new pass now), weekly_summary, context (raw ALE state). 'No insights available' means the engine hasn't generated any yet for this account or period — call analyze to trigger a fresh pass rather than assuming nothing is happening in the graph.", {
         action: zod_1.z
             .enum(["list", "unread_count", "view", "feedback", "analyze", "weekly_summary", "context"])
             .describe("Action: list (recent insights), unread_count, view (mark seen), feedback (rate), analyze (trigger analysis), weekly_summary, context (ALE context)"),
@@ -2743,7 +2937,7 @@ function createMindMcpServer(client) {
     });
     // ─── mind_automate ──────────────────────────────────────
     // Automations and triggers.
-    server.tool("mind_automate", "Create and manage automations in MIND — scheduled workflows, event triggers, and rules that run automatically. Connect CRM events to actions, schedule recurring tasks, and build custom pipelines.", {
+    server.tool("mind_automate", "Create and manage MIND-native automations — scheduled or event-triggered rules that run without a human or agent invoking them each time (e.g. a weekly CRM digest, a webhook that logs an event to a life project). This is for recurring MIND-internal work, not a general task scheduler for external systems. Actions: list/create/update/delete, run_now (fire immediately for testing), history (execution log). `trigger_config`/`action_config` are JSON strings, not objects — pass valid JSON or the call throws. An empty list means no automations are configured in this account yet, not that scheduled work isn't happening elsewhere.", {
         action: zod_1.z
             .enum(["list", "create", "update", "delete", "run_now", "history"])
             .describe("Action: list/create/update/delete automations, run_now (trigger immediately), history (execution log)"),
@@ -2879,7 +3073,7 @@ function createMindMcpServer(client) {
     });
     // ─── mind_notify ────────────────────────────────────────
     // Notifications management.
-    server.tool("mind_notify", "Read and manage MIND notifications — alerts, reminders, insight notifications, and system messages.", {
+    server.tool("mind_notify", "Read and manage the user's MIND notification inbox — alerts, reminders, insight pings, and system messages generated by other MIND features. It is not a way to send a notification yourself. Use this to check what MIND has already surfaced to the user, or to clear it down; for the underlying event (why an insight fired, what an alert refers to) follow up with the originating tool (mind_insights, mind_sense, etc.) or mind_query. Actions: list, mark_read, mark_all_read, stats (total/unread/read counts). 'No notifications' or unread:0 means nothing has been pushed to the inbox — a quiet inbox and a quiet graph are different claims.", {
         action: zod_1.z
             .enum(["list", "mark_read", "mark_all_read", "stats"])
             .describe("Action: list (view notifications), mark_read (single), mark_all_read (all), stats (overview)"),
@@ -2934,6 +3128,207 @@ function createMindMcpServer(client) {
             };
         }
     });
+    // ─── mind_sessions ──────────────────────────────────────
+    // "Agent Sessions in MIND Chat" — logs THIS agent's own live session into
+    // MIND as a tagged Agent Session so Anthony can read the transcript and
+    // reply from MIND Chat → Agents. Backed by
+    // backend/routes/agent_session_routes.py, prefix
+    // /developer/v1/agent-sessions. See the full AGENT SESSION PROTOCOL in
+    // integration-guide.ts (embedded verbatim in SERVER_INSTRUCTIONS and the
+    // sync-agent-session prompt) — the compact version below is repeated here
+    // so a client that only ever reads tool descriptions still gets it.
+    server.tool("mind_sessions", "Log THIS agent's own live session into MIND Chat → Agents, so Anthony can read the transcript and reply — his reply reaches you on your next turn. Distinct from mind_remember (one durable fact) and mind_train (teaching the KG): this is the live, turn-by-turn session log, mirrored into a MIND document when you close it.\n\n" +
+        "PROTOCOL (do this every session): " +
+        "1) CONNECT — as soon as mind_context succeeds, call action=open with source_key (your assigned MIND Chat toggle, e.g. \"claude-code-1\"), external_session_id (your runtime's own session id), runtime, title (first user ask, 6-10 words), machine/cwd/repo/branch/model. If `resumed` is true, read `tail` before answering, and answer everything in `pending_replies` first — those arrived while you were away. " +
+        "2) EVERY TURN — after you finish replying, call action=append with the user's message and your final reply (role user / assistant); tool calls go in as role=tool one-line summaries, never raw payloads. Check `pending_replies` on the response and answer them next turn. action=reply is a shortcut for appending a single assistant-role message when you have no user message to log alongside it. " +
+        "3) IDLE — MIND marks the session idle after 30 minutes with no append; the next append revives it, nothing to do meanwhile. " +
+        "4) TERMINATE — on exit, compaction, or \"done\", call action=close with a summary (what was asked, what shipped with ids/PR numbers, what is still undone); MIND mirrors the transcript into your Sessions folder as a document. " +
+        "5) HANDOFF — to pass the conversation to another agent, call action=handoff with to_source_key=<their toggle>; they see it in their session list with the transcript as context. " +
+        "Never claim a session is synced without the session_id MIND returned. Never log secrets or raw tool payloads.\n\n" +
+        "Actions: open, append, close, list, get, reply (alias for append of one assistant message), inbox (undelivered mind-origin replies), handoff, sources (source_action=list|create|update|delete manages the MIND Chat sidebar toggles — auto-created on first open with an unknown source_key).", {
+        action: zod_1.z
+            .enum(["open", "append", "close", "list", "get", "reply", "inbox", "handoff", "sources"])
+            .describe("Which agent-session operation to perform."),
+        // open
+        source_key: zod_1.z.string().optional().describe("Your assigned MIND Chat sidebar toggle slug, e.g. \"claude-code-1\" — required for open; also filters list; also required for sources action=create (as the new source's key)."),
+        external_session_id: zod_1.z.string().optional().describe("Your runtime's own session id — required for open. Idempotent: opening the same (source_key, external_session_id) again resumes the existing session instead of creating a new one."),
+        runtime: zod_1.z.string().optional().describe("Runtime name, e.g. \"claude-code\", \"codex\", \"cursor\", \"openclaw\", \"grok\", \"n8n\", \"custom\" — open (used if the source is auto-created); sources action=create/update."),
+        source_label: zod_1.z.string().optional().describe("Human-readable label for an auto-created source on open, e.g. \"Claude Code 1\" — defaults to the titlecased source_key if omitted."),
+        title: zod_1.z.string().optional().describe("Session title (first user ask, 6-10 words) — open (initial) or append (updates it)."),
+        machine: zod_1.z.string().optional().describe("Machine identifier — open."),
+        cwd: zod_1.z.string().optional().describe("Working directory — open."),
+        repo: zod_1.z.string().optional().describe("Repository name — open."),
+        branch: zod_1.z.string().optional().describe("Git branch — open."),
+        model: zod_1.z.string().optional().describe("LLM model in use — open."),
+        tags: zod_1.z.array(zod_1.z.string()).optional().describe("Freeform tags — open."),
+        // append / reply
+        session_id: zod_1.z.string().optional().describe("Session id returned by open — required for append/close/get/inbox/handoff."),
+        messages: zod_1.z
+            .array(zod_1.z.object({
+            role: zod_1.z.enum(["user", "assistant", "system", "tool"]),
+            content: zod_1.z.string(),
+            origin: zod_1.z.enum(["agent"]).optional(),
+            meta: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+            created_at: zod_1.z.string().optional(),
+        }))
+            .optional()
+            .describe("Messages to append, in order — required for append. Tool-call messages should be role=tool, one-line summaries only, never raw payloads."),
+        content: zod_1.z.string().optional().describe("Message text — required for reply (appended as a single role=assistant message)."),
+        // close
+        summary: zod_1.z.string().optional().describe("What was asked, what shipped (with ids/PR numbers), what is still undone — close. If omitted, MIND builds one from the transcript."),
+        // list / close (status set) share this field
+        status: zod_1.z.enum(["active", "idle", "ended"]).optional().describe("close: pass \"ended\" to explicitly close (default when summary is given). list: filter sessions by status."),
+        q: zod_1.z.string().optional().describe("Free-text search over title/preview — list."),
+        limit: zod_1.z.number().int().optional().describe("Max results — list (default 30) / get (default 200, messages)."),
+        before: zod_1.z.string().optional().describe("Pagination cursor (last_activity_at) — list."),
+        before_seq: zod_1.z.number().int().optional().describe("Return messages with seq before this value — get."),
+        // handoff
+        to_source_key: zod_1.z.string().optional().describe("Target source's key to hand this session off to — required for handoff."),
+        // sources
+        source_action: zod_1.z.enum(["list", "create", "update", "delete"]).optional().describe("Sub-action for action=sources (default list)."),
+        source_id: zod_1.z.string().optional().describe("Source id — required for sources action=update/delete."),
+        key: zod_1.z.string().optional().describe("New source's key slug — required for sources action=create."),
+        label: zod_1.z.string().optional().describe("Source label, e.g. \"Claude Code 1\" — sources action=create (required) / update."),
+        color: zod_1.z.string().optional().describe("Sidebar chip color — sources action=create/update."),
+        wake_url: zod_1.z.string().optional().describe("Optional push endpoint MIND POSTs {session_id, reply} to (fire-and-forget, 5s timeout) when the user replies — sources action=create/update."),
+        force: zod_1.z.boolean().optional().describe("sources action=delete: also delete the source's sessions instead of failing 409 when sessions exist."),
+    }, async (args) => {
+        const { action } = args;
+        try {
+            switch (action) {
+                case "open": {
+                    const { source_key, external_session_id } = args;
+                    if (!source_key)
+                        return err("Error: 'source_key' is required for open.");
+                    if (!external_session_id)
+                        return err("Error: 'external_session_id' is required for open.");
+                    return ok(await client.openAgentSession({
+                        source_key,
+                        external_session_id,
+                        runtime: args.runtime,
+                        source_label: args.source_label,
+                        title: args.title,
+                        machine: args.machine,
+                        cwd: args.cwd,
+                        repo: args.repo,
+                        branch: args.branch,
+                        model: args.model,
+                        tags: args.tags,
+                    }));
+                }
+                case "append": {
+                    const { session_id, messages } = args;
+                    if (!session_id)
+                        return err("Error: 'session_id' is required for append.");
+                    if (!messages?.length)
+                        return err("Error: 'messages' (at least one) is required for append.");
+                    return ok(await client.appendAgentSession(session_id, messages, args.title));
+                }
+                case "reply": {
+                    const { session_id, content } = args;
+                    if (!session_id)
+                        return err("Error: 'session_id' is required for reply.");
+                    if (!content)
+                        return err("Error: 'content' is required for reply.");
+                    return ok(await client.appendAgentSession(session_id, [{ role: "assistant", content }]));
+                }
+                case "close": {
+                    const { session_id } = args;
+                    if (!session_id)
+                        return err("Error: 'session_id' is required for close.");
+                    return ok(await client.closeAgentSession(session_id, {
+                        summary: args.summary,
+                        status: args.status === "ended" ? "ended" : undefined,
+                    }));
+                }
+                case "list":
+                    return ok(await client.listAgentSessions({
+                        source_key: args.source_key,
+                        status: args.status,
+                        q: args.q,
+                        limit: args.limit,
+                        before: args.before,
+                    }));
+                case "get": {
+                    const { session_id } = args;
+                    if (!session_id)
+                        return err("Error: 'session_id' is required for get.");
+                    return ok(await client.getAgentSession(session_id, {
+                        limit: args.limit,
+                        before_seq: args.before_seq,
+                    }));
+                }
+                case "inbox": {
+                    const { session_id } = args;
+                    if (!session_id)
+                        return err("Error: 'session_id' is required for inbox.");
+                    return ok(await client.agentSessionInbox(session_id));
+                }
+                case "handoff": {
+                    const { session_id, to_source_key } = args;
+                    if (!session_id)
+                        return err("Error: 'session_id' is required for handoff.");
+                    if (!to_source_key)
+                        return err("Error: 'to_source_key' is required for handoff.");
+                    return ok(await client.handoffAgentSession(session_id, to_source_key));
+                }
+                case "sources": {
+                    const sourceAction = args.source_action ?? "list";
+                    switch (sourceAction) {
+                        case "list":
+                            return ok(await client.listAgentSessionSources());
+                        case "create": {
+                            const { key, label, runtime } = args;
+                            if (!key)
+                                return err("Error: 'key' is required for sources action=create.");
+                            if (!label)
+                                return err("Error: 'label' is required for sources action=create.");
+                            if (!runtime)
+                                return err("Error: 'runtime' is required for sources action=create.");
+                            return ok(await client.createAgentSessionSource({
+                                key,
+                                label,
+                                runtime,
+                                color: args.color,
+                                wake_url: args.wake_url,
+                            }));
+                        }
+                        case "update": {
+                            const { source_id } = args;
+                            if (!source_id)
+                                return err("Error: 'source_id' is required for sources action=update.");
+                            return ok(await client.updateAgentSessionSource(source_id, {
+                                label: args.label,
+                                runtime: args.runtime,
+                                color: args.color,
+                                wake_url: args.wake_url,
+                            }));
+                        }
+                        case "delete": {
+                            const { source_id } = args;
+                            if (!source_id)
+                                return err("Error: 'source_id' is required for sources action=delete.");
+                            await client.deleteAgentSessionSource(source_id, args.force);
+                            return ok({ ok: true, source_id });
+                        }
+                        default: {
+                            const _exhaustive = sourceAction;
+                            return err(`Unknown source_action: ${_exhaustive}`);
+                        }
+                    }
+                }
+                default: {
+                    const _exhaustive = action;
+                    return err(`Unknown action: ${_exhaustive}`);
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof mind_client_js_1.MindApiError)
+                return err(`mind_sessions ${action} failed (HTTP ${e.status}): ${apiDetail(e)}`);
+            return err(`mind_sessions error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     // ─── MIND Front Layer (typed-document taxonomy / "MIND Sense") ─────────────
     // Three tools that expose the 16 typed-document templates and the typed-save flow.
     // The same templates power the developer API endpoints under /v1/templates.