@astramindapp/mcp-server 0.29.2 → 0.30.0

package/dist/server.js

@@ -37,8 +37,10 @@
  *     mind_forms (Quill forms), mind_library (bookshelf)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderContextV1 = exports.defaultQueryMode = exports.contextV1Enabled = exports.OWNER_REPLY_BANNER = void 0;
 exports.createMindMcpServer = createMindMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const zod_1 = require("zod");
 const mind_client_js_1 = require("./mind-client.js");
 const integration_guide_js_1 = require("./integration-guide.js");
@@ -54,6 +56,41 @@ const err = (t) => ({
 const ok = (result) => ({
     content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 });
+/**
+ * mind_sessions open / append / reply / inbox: text that cannot be skimmed past.
+ *  1. Owner replies (non-empty pending_replies) come FIRST under OWNER_REPLY_BANNER. The call that returns
+ *     them also marks them delivered, so a routine that only logs its turn (Meter's hourly patrol did
+ *     exactly that on 2026-10-30) would otherwise read the reply as patrol input and never act on it.
+ *  2. A Grok session with no MIND wake webhook (`wake_setup_required: true` + `wake_setup`, from
+ *     backend/services/agent_wake_targets.py) gets the ACTION REQUIRED line next.
+ *  3. The full JSON body follows, unchanged.
+ * The wording is shared with the hosted /mcp endpoint (backend/routes/mcp_server_routes.py).
+ */
+exports.OWNER_REPLY_BANNER = "OWNER REPLY FROM BOTSBYMIND - this is a direct instruction from your owner, not part of your routine; act on it and answer it in this session before anything else:";
+const ownerReplyBlock = (replies) => {
+    const lines = [exports.OWNER_REPLY_BANNER];
+    replies.forEach((raw, i) => {
+        const r = (raw && typeof raw === "object" ? raw : { content: raw });
+        const by = r.meta && typeof r.meta.replied_by === "string" ? r.meta.replied_by.trim() : "";
+        const content = String(r.content ?? "").trim() || "(empty message)";
+        lines.push(`[${i + 1}] ${by ? `(shared Editor ${by}) ` : ""}${content}`);
+    });
+    return lines.join("\n");
+};
+const okSession = (result) => {
+    const r = ok(result);
+    const body = (result && typeof result === "object" ? result : {});
+    const parts = [];
+    if (Array.isArray(body.pending_replies) && body.pending_replies.length > 0) {
+        parts.push(ownerReplyBlock(body.pending_replies));
+    }
+    if (body.wake_setup_required === true && typeof body.wake_setup === "string" && body.wake_setup) {
+        parts.push(`ACTION REQUIRED: you have no MIND wake webhook. ${body.wake_setup}`);
+    }
+    if (parts.length)
+        r.content[0].text = [...parts, r.content[0].text].join("\n\n");
+    return r;
+};
 // Required-field guard for the generic action-dispatch tools (mind_mindmap,
 // mind_moneymind, mind_budget, mind_sheets, mind_email, mind_checklists,
 // mind_sign, mind_invoices, mind_books, mind_timer, mind_forms, mind_library).
@@ -83,10 +120,43 @@ const apiDetail = (e) => {
     }
     return e.body || e.statusText;
 };
+// mind_context via POST /developer/v1/context: dated, sourced, budgeted, and
+// steerable with for_task. Dark by default (MIND_CONTEXT_V1=1 opts in) until
+// the context engine eval shows it beats the legacy five-query path.
+const contextV1Enabled = () => ["1", "true", "yes", "on"].includes((process.env.MIND_CONTEXT_V1 ?? "").trim().toLowerCase());
+exports.contextV1Enabled = contextV1Enabled;
+// Mode for a mind_query call that names none. hybrid reaches text chunks
+// only through extracted entities, so documents still waiting in an
+// extraction backlog are invisible to it; mix adds chunk vectors. Measured
+// 2026-09-29 on 16 claim questions: hybrid 14/16, mix 15/16, similar latency.
+// Dark by default (MIND_QUERY_DEFAULT_MIX=1 opts in), matching the hosted
+// server's MCP_QUERY_DEFAULT_MIX flag.
+const defaultQueryMode = () => ["1", "true", "yes", "on"].includes((process.env.MIND_QUERY_DEFAULT_MIX ?? "").trim().toLowerCase())
+    ? "mix"
+    : "hybrid";
+exports.defaultQueryMode = defaultQueryMode;
+const renderContextV1 = (data) => {
+    const blocks = (data.sections ?? []).map((sec) => {
+        let head = `## ${sec.section.toUpperCase()} (${sec.status}`;
+        if (sec.omitted_count)
+            head += `, ${sec.omitted_count} omitted for budget`;
+        const lines = [`${head})`];
+        if (sec.error)
+            lines.push(`error: ${sec.error}`);
+        for (const item of sec.items ?? []) {
+            const meta = [item.date, item.source].filter(Boolean).join(", ");
+            lines.push(`- ${item.text}${meta ? ` [${meta}]` : ""}`);
+        }
+        return lines.join("\n");
+    });
+    blocks.push(`(~${data.estimated_tokens} of ${data.max_tokens} tokens; ${data.total_omitted ?? 0} items omitted)`);
+    return blocks.join("\n\n");
+};
+exports.renderContextV1 = renderContextV1;
 function createMindMcpServer(client) {
     const server = new mcp_js_1.McpServer({
         name: "mind",
-        version: "0.29.2",
+        version: "0.30.0",
     }, {
         // Returned to every client in the MCP `initialize` response — the first
         // thing any connecting agent sees about how to integrate with MIND.
@@ -96,7 +166,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 45 tools, REST endpoint mapping, and common recipes.",
+        description: "Complete playbook for integrating any AI agent with MIND — the three integration paths (MCP server, Daebot, REST API), authentication, the session protocol, all 45 tools, REST endpoint mapping, and common recipes.",
         mimeType: "text/markdown",
     }, async (uri) => ({
         contents: [
@@ -181,6 +251,133 @@ function createMindMcpServer(client) {
             },
         ],
     }));
+    // ─── resume-agent-session prompt ──────────────────────────
+    // "Any AI that you tell to 'run my Meter session' taps into the Meter
+    // MIND session and picks up where it left off with the right prompting"
+    // (contract, 2026-10-06). Unlike sync-agent-session above (a static
+    // template), this one makes the LIVE mind_sessions action=resume call
+    // itself and hands back its resume_prompt verbatim — the model adopts it
+    // as-is rather than being taught the protocol from scratch.
+    server.registerPrompt("resume-agent-session", {
+        title: "Resume an agent's session",
+        description: "Resolves <agent>'s most recent session, agent file, and attached context, opens a continuation session, and returns a ready-to-adopt resume_prompt. Equivalent to calling mind_sessions action=resume yourself.",
+        argsSchema: {
+            agent: zod_1.z.string().describe('The agent to resume, e.g. "Meter". Required.'),
+        },
+    }, async ({ agent }) => {
+        const trimmed = (agent ?? "").trim();
+        if (!trimmed) {
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: { type: "text", text: "Error: 'agent' is required to resume a session." },
+                    },
+                ],
+            };
+        }
+        try {
+            const result = await client.resumeAgent({ agent: trimmed });
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `${result.resume_prompt}\n\n(session_id: ${result.session_id} — append every turn with mind_sessions action=append using this session_id)`,
+                        },
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            const message = e instanceof mind_client_js_1.MindApiError
+                ? `Resume failed (HTTP ${e.status}): ${apiDetail(e)}`
+                : `Resume error: ${e instanceof Error ? e.message : String(e)}`;
+            return {
+                messages: [{ role: "user", content: { type: "text", text: message } }],
+            };
+        }
+    });
+    // ─── mind-sync-heartbeat prompt ──────────────────────────
+    // The body of the 15-minute "MIND sync heartbeat" routine every agent
+    // creates in its OWN scheduler (AGENTS.md section 2.11). MIND cannot wake a
+    // client, so the standard is: install a recurring routine whose whole body
+    // is this prompt.
+    server.registerPrompt("mind-sync-heartbeat", {
+        title: "MIND sync heartbeat (run every 15 minutes)",
+        description: "The body of the recurring 15-minute routine named \"MIND sync heartbeat\": one mind_sessions action=heartbeat call, answer every pending owner reply in your own app, append both sides. Create the routine once at install; paste this prompt as its whole body.",
+    }, async () => ({
+        messages: [
+            { role: "user", content: { type: "text", text: (0, integration_guide_js_1.buildSyncHeartbeatPrompt)() } },
+        ],
+    }));
+    // ─── mind://sessions/pending (+ subscribe) ──────────────
+    // Pending owner replies across all of this key's sessions. A client that
+    // supports resources/subscribe gets notifications/resources/updated when a
+    // NEW reply appears, so it need not wait for the next 15-minute beat. The
+    // stdio server can push (long-lived process): it polls the REST pending feed
+    // every PENDING_POLL_MS while at least one subscription is open. The hosted
+    // /mcp route is stateless and cannot push; it serves the same resource.
+    const PENDING_URI = "mind://sessions/pending";
+    const PENDING_POLL_MS = Number(process.env.MIND_PENDING_POLL_MS) > 0 ? Number(process.env.MIND_PENDING_POLL_MS) : 30_000;
+    const pendingSubscribers = new Set();
+    let pendingSeen = null;
+    let pendingTimer = null;
+    const pendingList = async () => {
+        const res = await client.pendingAgentReplies();
+        return (res.pending ?? []).map((p) => ({
+            session_id: p.session_id,
+            reply_id: p.reply_id ?? p.message_id,
+            content: p.content,
+            created_at: p.created_at,
+            agent: p.agent,
+        }));
+    };
+    const pollPending = async () => {
+        try {
+            const ids = new Set((await pendingList()).map((p) => String(p.reply_id)));
+            const hasNew = pendingSeen !== null && [...ids].some((id) => !pendingSeen.has(id));
+            pendingSeen = ids;
+            if (hasNew)
+                await server.server.sendResourceUpdated({ uri: PENDING_URI });
+        }
+        catch {
+            /* transient; next tick retries */
+        }
+    };
+    server.server.registerCapabilities({ resources: { subscribe: true } });
+    server.server.setRequestHandler(types_js_1.SubscribeRequestSchema, async (req) => {
+        pendingSubscribers.add(req.params.uri);
+        if (req.params.uri === PENDING_URI && !pendingTimer) {
+            pendingSeen = null;
+            void pollPending();
+            pendingTimer = setInterval(() => void pollPending(), PENDING_POLL_MS);
+            pendingTimer.unref?.();
+        }
+        return {};
+    });
+    server.server.setRequestHandler(types_js_1.UnsubscribeRequestSchema, async (req) => {
+        pendingSubscribers.delete(req.params.uri);
+        if (!pendingSubscribers.has(PENDING_URI) && pendingTimer) {
+            clearInterval(pendingTimer);
+            pendingTimer = null;
+        }
+        return {};
+    });
+    server.registerResource("sessions-pending", PENDING_URI, {
+        title: "Pending owner replies",
+        description: "Owner replies typed in MINDbots / MIND Chat that no agent has answered yet, across all your open sessions, oldest first. Subscribe (resources/subscribe) to be notified when a new one arrives; otherwise read it on every 15-minute heartbeat. Reading never marks a reply delivered; an append does.",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify({ pending_replies: await pendingList() }, null, 2),
+            },
+        ],
+    }));
     // ─── 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
@@ -205,21 +402,33 @@ function createMindMcpServer(client) {
     // ─── mind_query ─────────────────────────────────────────
     // Semantic search across the user's knowledge graph.
     // Replaces flat MEMORY.md — returns only relevant memories.
-    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.", {
+    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. Omit mode to get the server 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"])
             .optional()
-            .default("hybrid")
-            .describe("Search mode: hybrid (default, best results — combines semantic + graph traversal), mix (balanced), global (broad graph search), local (focused graph search), naive (simple vector search)"),
+            .optional()
+            .describe("Search mode. Omit it to use the server default (hybrid, or mix where the server enables it). mix: graph plus raw document text, the most complete, and it also finds documents still waiting for graph extraction. hybrid: combines local and global graph reasoning. global: broad graph search. local: focused graph search. naive: simple vector search over document text."),
         retrieve_only: zod_1.z
             .boolean()
             .optional()
             .default(true)
             .describe("Default true: return raw graph context for YOU to synthesize, 0 credits. Set false to have MIND's own LLM write the answer (spends credits)."),
-    }, async ({ query, mode, retrieve_only }) => {
+        max_context_tokens: zod_1.z
+            .number()
+            .int()
+            .min(1000)
+            .max(30000)
+            .optional()
+            .describe("Optional ceiling on retrieved context in tokens (default 30000, about 120K characters). Lower it (e.g. 6000-10000) for a focused payload, and always when retrieve_only=false: MIND's LLM reads the whole context before answering, and a length instruction in the query only bounds the answer, not what is read."),
+        instructions: zod_1.z
+            .string()
+            .max(4000)
+            .optional()
+            .describe("Optional: how MIND's writer should answer (shape, length, audience) when retrieve_only=false. Keep `query` to the question itself and put everything about the answer here: instruction text inside `query` becomes search terms and measurably lowers retrieval quality (relevant documents 62% clean vs 46% wrapped, 2026-09-29). Ignored when retrieve_only=true."),
+    }, async ({ query, mode, retrieve_only, max_context_tokens, instructions }) => {
         try {
-            const result = await client.query({ query, mode, retrieve_only });
+            const result = await client.query({ query, mode: mode ?? (0, exports.defaultQueryMode)(), retrieve_only, max_context_tokens, instructions });
             const text = [
                 result.response,
                 "",
@@ -264,7 +473,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.\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.", {
+    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: titles are plain natural language, written as a person would name the thing. No type prefixes (\"Journal Entry\", \"Agent Entry\", \"Document\"), no ids or hashes, no ISO timestamps; never put '/' or parentheses in a title, the card is derived from it. Lessons keep the 'Lesson - Failure - <behavior>' / 'Lesson - Behavior - <behavior>' / 'Lesson - Win - <behavior>' shape exactly as written (MIND never rewrites a lesson title) and files them under Lessons.\n\nFILING: every write is filed, nothing lands loose. Pass `folder` (a folder id, a folder name, or a 'Parent/Child' path) when you know where it belongs; otherwise leave it out and MIND files it by what it is (agent entries, automation logs, lessons, mistakes, decisions, documents). An explicit folder always wins; a secure folder is refused. One living document per entity: when a person, project, focus, calendar event or recurring job already has a record, update that record (mind_crm, mind_life, mind_focuses) or supersede the earlier note with `supersedes`; do not write a new entry that restates 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()
@@ -279,7 +488,7 @@ function createMindMcpServer(client) {
         title: zod_1.z
             .string()
             .optional()
-            .describe("Title for documents and entries (auto-generated if omitted for feed posts)"),
+            .describe("Title for documents and entries: plain natural language, no type prefixes, no ids (auto-generated if omitted for feed posts)"),
         tags: zod_1.z
             .array(zod_1.z.string())
             .optional()
@@ -305,7 +514,16 @@ function createMindMcpServer(client) {
             .number()
             .optional()
             .describe("Max items to return for list/search"),
-    }, async ({ action, content, type, title, tags, source, item_id, query, page, limit }) => {
+        folder: zod_1.z
+            .string()
+            .optional()
+            .describe("Where to file this write: a folder id, a folder name, or a 'Parent/Child' path (mind_folders list shows them). Optional: omit it and MIND files the write by what it is. An explicit folder always wins; a secure folder is refused. Applies to documents and entries."),
+        supersedes: zod_1.z
+            .array(zod_1.z.string())
+            .max(10)
+            .optional()
+            .describe("Entries only: earlier records of yours this entry replaces, by id, exact title, or the exact reference title retrieval shows (e.g. \"Agent Entry: <title>\"; older entries show \"Journal Entry: <title>\"). They are tagged superseded, never deleted, and stop being retrieved once the server enables it. Use it whenever you record a fix, reversal or newer version, so MIND stops serving the old fact."),
+    }, async ({ action, content, type, title, tags, source, folder, item_id, query, page, limit, supersedes }) => {
         try {
             switch (action) {
                 case "create": {
@@ -323,6 +541,8 @@ function createMindMcpServer(client) {
                                 title: title ?? `Agent Document — ${new Date().toISOString().slice(0, 10)}`,
                                 content,
                                 source: source ?? "mcp-agent",
+                                ...(tags && tags.length ? { tags } : {}),
+                                ...(folder ? { folder } : {}),
                             });
                             storedAs = "document";
                             break;
@@ -337,6 +557,8 @@ function createMindMcpServer(client) {
                                 title,
                                 content,
                                 tags,
+                                ...(folder ? { folder } : {}),
+                                ...(supersedes && supersedes.length ? { supersedes } : {}),
                             });
                             storedAs = "entry";
                             break;
@@ -452,7 +674,7 @@ 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, secure, unsecure, unlock, reset_request, reset (Secure Folders — password-gate a 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. Every write is already filed by MIND, so you rarely need to move anything: pass `folder` to mind_remember when you know where it belongs, and use move_documents to correct a filing. 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",
@@ -853,8 +1075,43 @@ function createMindMcpServer(client) {
             .optional()
             .default(["soul", "user", "rules", "priorities", "recent"])
             .describe("Which context sections to load: soul (identity/personality), user (who the user is), rules (operating constraints), priorities (current goals/tasks), recent (latest activity)"),
-    }, async ({ sections }) => {
+        for_task: zod_1.z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Optional: one or two sentences describing the task you are about to do. Steers retrieval for soul/user/rules/priorities toward what that task needs."),
+        max_tokens: zod_1.z
+            .number()
+            .int()
+            .min(200)
+            .max(50000)
+            .optional()
+            .describe("Optional soft ceiling on the returned context size (rough tokens, default 6000). Lowest-priority items are dropped first and the response says how many."),
+        action: zod_1.z
+            .enum(["load", "get_pins", "set_pins"])
+            .optional()
+            .default("load")
+            .describe("load (default) returns context. get_pins / set_pins read or replace the owner's pinned canonical document ids for soul, user and rules; pinned sections are read directly instead of retrieved, so no look-alike document can take their place."),
+        pins: zod_1.z
+            .object({
+            soul: zod_1.z.array(zod_1.z.string()).max(5).optional(),
+            user: zod_1.z.array(zod_1.z.string()).max(5).optional(),
+            rules: zod_1.z.array(zod_1.z.string()).max(5).optional(),
+        })
+            .optional()
+            .describe("For set_pins: document ids per section (max 5). Omit a section to keep it, [] to clear it. Only your own documents are accepted."),
+    }, async ({ sections, for_task, max_tokens, action, pins }) => {
         try {
+            if (action === "get_pins") {
+                return ok(await client.getContextPins());
+            }
+            if (action === "set_pins") {
+                return ok(await client.setContextPins(pins ?? {}));
+            }
+            if ((0, exports.contextV1Enabled)()) {
+                const data = await client.context({ sections, for_task, max_tokens });
+                return { content: [{ type: "text", text: (0, exports.renderContextV1)(data) }] };
+            }
             const sectionQueries = {
                 soul: "my identity, mission, personality, who I am, my role and purpose",
                 user: "user profile, preferences, timezone, communication style, who is the user",
@@ -3139,14 +3396,20 @@ function createMindMcpServer(client) {
     // 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. Your real source is derived from runtime x installation (device/platform/env), never the literal source_key — the response's own `source_key` tells you what it actually resolved to. If you're a named agent within a shared runtime (a scheduled job, a persona, a bot on a shared account), pass `agent` (a bare name, or {key,label}) so sessions attribute to WHO ran them, not just where — this works for every runtime, not only shared/cloud ones. If `resumed` is true, read `tail` before answering, and answer everything in `pending_replies` first — those arrived while you were away. " +
+        "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. Your real source is derived from runtime x installation (device/platform/env), never the literal source_key — the response's own `source_key` tells you what it actually resolved to. If you're a named agent within a shared runtime (a scheduled job, a persona, a bot on a shared account), pass `agent` (a bare name, or {key,label}) so sessions attribute to WHO ran them, not just where — this works for every runtime, not only shared/cloud ones. If you know which Life project the work is for, pass its item id as `project_id` so the Agent Activity Map files the session there (otherwise MIND infers it). 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. " +
-        "6) SHARE — to let another MIND user follow this session, call action=share with grantee_username and role (\"viewer\" read-only, the default, or \"replier\" which also lets them reply — a reply is a live action that wakes your process via wake_url, so grant it deliberately). It's a live mirror, never a copy: they always see the current transcript, and revoking (action=revoke_share) removes their access immediately. Never share a session with anyone who shouldn't see its full transcript.\n" +
+        "6) SHARE — to let another MIND user follow this session, call action=share with grantee_username and role (\"viewer\" read-only, the default, or \"replier\" which also lets them reply — a reply is a live action that wakes your process via wake_url, so grant it deliberately). It's a live mirror, never a copy: they always see the current transcript, and revoking (action=revoke_share) removes their access immediately. Never share a session with anyone who shouldn't see its full transcript. " +
+        "7) AGENT FILE — if you are a named, standing agent (not a bare runtime), keep your agent file current with action=agent_doc_update (editor=\"agent\", with a `note`) whenever your role, rules or standing work change; read it anytime with action=agent_doc_get. " +
+        "8) RESUME ANYWHERE — when the user says \"run my <Agent> session\" / \"be <Agent>\" / \"resume <Agent>\", call action=resume with agent=<Agent> and adopt its `resume_prompt` verbatim as your operating brief for the rest of the turn — it already carries your agent file, attached context, where you left off, and any pending replies.\n" +
+        "9) HEARTBEAT — every 15 minutes from YOUR OWN scheduler (MIND cannot wake you): action=heartbeat with source_key, agent, runtime (+ optional unsynced turns). Returns pending_replies across your open sessions, oldest first (session_id, reply_id, content, created_at), plus next_beat_seconds. Answer each in your own app, then append both sides; the append marks it delivered, a heartbeat never does. Install once: a recurring routine named \"MIND sync heartbeat\" whose body is the MCP prompt mind-sync-heartbeat. MINDbots shows \"Sync stale\" after 20 minutes of silence.\n" +
+        "10) " + integration_guide_js_1.AGENT_SESSION_REPLIES_RULE + "\n" +
         "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), share (grant another MIND account viewer or replier access — owner only), list_shares (owner only), revoke_share (owner only).", {
+        "Actions: open, append, close, list, get, reply (alias for append of one assistant message), heartbeat (the 15-minute sync beat), wake_target_set (agent, url, secret, runtime default \"grok\": register a Grok Bot \"MIND wake\" webhook routine so MIND POSTs it the moment your owner replies; the secret is sent as `Authorization: Bearer` and is never echoed back), wake_targets (list registered wake targets, masked), wake_target_clear (agent, runtime: remove one), 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), share (grant another MIND account viewer or replier access — owner only), list_shares (owner only), revoke_share (owner only), activity (Agent Activity Map: which agents worked on which Life projects over `days`, with sessions, turns, tool calls, active minutes and Anthony's replies per project, plus sessions that still need a project), set_project (assign a session to a Life project by `project_id`, or clear it with project_id omitted; `learn` (default true) makes the session's working folder or repo route future sessions to the same project), agent_doc_get (read a standing agent's file — its role/rules/tools/standing-work doc, identified by `agent_key`; returns a starter template when none exists yet), agent_doc_update (save a new version of that file; `editor` is \"user\" or \"agent\" — \"agent\" requires a `note` saying what changed and why; a stale `base_version` 409s with the current doc instead of clobbering a concurrent edit), attach (replace the full list of Life projects/focuses/workspaces/repos an agent is connected to, by `agent_key` and `attachments`), mentions (read/mark-delivered this key's pending @mentions), group_create, group_list, group_get, group_post, group_inbox, group_delete (see GROUP CHATS / @ MENTIONS below), resume (pick up a named agent — `agent` — wherever it last left off: its agent file, attached context with live summaries, the previous session's tail/summary, any pending replies, and a ready-to-adopt `resume_prompt`; also opens a fresh continuation session for you to keep working in).\n\n" +
+        "GROUP CHATS — group_create (title, participant_keys: 2-20 source keys) opens a group thread; group_post (group_id, author_key, content) appends a message and delivers it into every OTHER participant's durable @mention inbox (see action=mentions) — group membership is an implicit mention of everyone else in the room; group_get (group_id) reads the full thread; group_list lists your groups; group_inbox (group_id, as_key) is a group-scoped view of the same inbox action=mentions reads; group_delete removes a group and its thread. " +
+        "@ MENTIONS — writing \"@<source_key>\" inside ANY posted content (a 1:1 session's append/reply, or a group_post) durably queues a pending mention for that key, independent of whether it has an open session right now or lives in a different chat/group entirely. action=mentions (as_key) returns and marks delivered every pending mention of that key — poll it the same way you poll action=inbox.", {
         action: zod_1.z
             .enum([
             "open",
@@ -3161,12 +3424,30 @@ function createMindMcpServer(client) {
             "share",
             "list_shares",
             "revoke_share",
+            "activity",
+            "set_project",
+            "agent_doc_get",
+            "agent_doc_update",
+            "attach",
+            "resume",
+            "mentions",
+            "group_create",
+            "group_list",
+            "group_get",
+            "group_post",
+            "group_inbox",
+            "group_delete",
+            "wake_target",
+            "wake_target_set",
+            "wake_targets",
+            "wake_target_clear",
+            "heartbeat",
         ])
             .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."),
+        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; wake_target_set / wake_target_clear (default \"grok\")."),
         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."),
@@ -3188,9 +3469,12 @@ function createMindMcpServer(client) {
         agent: zod_1.z
             .union([zod_1.z.string(), zod_1.z.object({ key: zod_1.z.string(), label: zod_1.z.string().optional() })])
             .optional()
-            .describe("Who is actually running this session — an attribute OF the session, never a source key, and unconditional on runtime (a claude-code cron run can carry agent=\"Chief of Staff\" exactly like a grok run carries agent=\"Dae\"). Bare string used as both key and label, or {key, label}. Falls back to a legacy alias for a bot-shaped source_key (\"dae\"→Dae, \"meter\"→Meter, \"grok-bot\"→Helm, \"n8n\"→n8n), then to the runtime's own display name — open only."),
+            .describe("Who is actually running this session — an attribute OF the session, never a source key, and unconditional on runtime (a claude-code cron run can carry agent=\"Chief of Staff\" exactly like a grok run carries agent=\"Dae\"). Bare string used as both key and label, or {key, label}. Falls back to a legacy alias for a bot-shaped source_key (\"dae\"→Dae, \"meter\"→Meter, \"grok-bot\"→Helm, \"n8n\"→n8n), then to the runtime's own display name — open only. For resume, a plain string naming the agent to pick up, e.g. \"Meter\" — required."),
+        project_id: zod_1.z.string().optional().describe("Life project item id this session works on — open (declared) and set_project (omit to clear)."),
+        days: zod_1.z.number().positive().max(90).optional().describe("Lookback window in days for activity (default 7, max 90)."),
+        learn: zod_1.z.boolean().optional().describe("set_project: remember this session's working folder or repo for future sessions (default true)."),
         // append / reply
-        session_id: zod_1.z.string().optional().describe("Session id returned by open — required for append/close/get/inbox/handoff."),
+        session_id: zod_1.z.string().optional().describe("Session id returned by open — required for append/close/get/inbox/handoff/set_project."),
         messages: zod_1.z
             .array(zod_1.z.object({
             role: zod_1.z.enum(["user", "assistant", "system", "tool"]),
@@ -3201,7 +3485,7 @@ function createMindMcpServer(client) {
         }))
             .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)."),
+        content: zod_1.z.string().optional().describe("Message text — required for reply (appended as a single role=assistant message). Also used for agent_doc_update: the agent file's full markdown content — required there too."),
         // 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
@@ -3220,10 +3504,37 @@ function createMindMcpServer(client) {
         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."),
+        // wake_target (Grok Bot webhook routine push)
+        wake_action: zod_1.z.enum(["set", "list", "clear"]).optional().describe("Sub-action for action=wake_target (default set): set registers this bot's webhook-routine URL, list shows registered bots (masked), clear removes one."),
+        url: zod_1.z.string().optional().describe("wake_target_set (or wake_target set): the https URL of this bot's \"MIND wake\" webhook routine. Owner-private, never echoed back."),
+        secret: zod_1.z.string().optional().describe("wake_target_set (or wake_target set): the webhook routine's API key; MIND sends it as 'Authorization: Bearer <secret>' and never in the body. Owner-private, never echoed back."),
         // share / list_shares / revoke_share
         grantee_username: zod_1.z.string().optional().describe("MIND username to share with — required for share."),
         role: zod_1.z.enum(["viewer", "replier"]).optional().describe("Role to grant — share (default \"viewer\"). \"replier\" additionally allows the grantee to reply, which reaches you via wake_url."),
         share_id: zod_1.z.string().optional().describe("Share grant id (from share or list_shares) — required for revoke_share."),
+        // agent_doc_get / agent_doc_update / attach
+        agent_key: zod_1.z.string().optional().describe("The agent's persona key, e.g. \"meter\" or \"Meter\" (any casing — the server normalizes it) — required for agent_doc_get, agent_doc_update, attach."),
+        editor: zod_1.z.enum(["user", "agent"]).optional().describe("Who is saving this version — required for agent_doc_update. \"agent\" requires `note`."),
+        note: zod_1.z.string().optional().describe("What changed and why — required for agent_doc_update when editor=\"agent\"."),
+        base_version: zod_1.z.number().int().optional().describe("The version you last read, for agent_doc_update — a stale value 409s with the current doc instead of silently overwriting a concurrent edit."),
+        attachments: zod_1.z
+            .array(zod_1.z.object({
+            kind: zod_1.z.enum(["project", "focus", "workspace", "repo"]),
+            id: zod_1.z.string(),
+            label: zod_1.z.string().optional(),
+        }))
+            .optional()
+            .describe("The FULL replacement list of what this agent is connected to — required for attach. kind=\"project\"/\"focus\" ids are Life item ids, \"workspace\" is a workspace id, \"repo\" is \"owner/name\"."),
+        // heartbeat
+        unsynced: zod_1.z
+            .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
+            .optional()
+            .describe("heartbeat: turns since your last append that MIND has not seen. Each item {session_id, role, content} or {session_id, messages:[...]}. Appended WITHOUT marking pending replies delivered."),
+        // groups / mentions
+        as_key: zod_1.z.string().optional().describe("Which agent key is asking — required for mentions / group_inbox: whose durable @mention inbox to read (and mark delivered)."),
+        group_id: zod_1.z.string().optional().describe("A group's id, returned by group_create — required for group_get/group_post/group_inbox/group_delete."),
+        participant_keys: zod_1.z.array(zod_1.z.string()).optional().describe("Source keys (2-20) of every agent in the group — required for group_create."),
+        author_key: zod_1.z.string().optional().describe("Which participant is posting — required for group_post. Must be one of the group's participant_keys."),
     }, async (args) => {
         const { action } = args;
         try {
@@ -3234,7 +3545,7 @@ function createMindMcpServer(client) {
                         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({
+                    return okSession(await client.openAgentSession({
                         source_key,
                         external_session_id,
                         runtime: args.runtime,
@@ -3250,15 +3561,27 @@ function createMindMcpServer(client) {
                         platform: args.platform,
                         env: args.env,
                         agent: args.agent,
+                        project_id: args.project_id,
                     }));
                 }
+                case "activity":
+                    return ok(await client.getAgentActivity(args.days));
+                case "set_project": {
+                    const { session_id } = args;
+                    if (!session_id)
+                        return err("Error: 'session_id' is required for set_project.");
+                    return ok(await client.setAgentSessionProject(session_id, args.project_id ?? null, args.learn));
+                }
                 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));
+                    const { device, platform, env } = args;
+                    return okSession(device || platform || env
+                        ? await client.appendAgentSession(session_id, messages, args.title, { device, platform, env })
+                        : await client.appendAgentSession(session_id, messages, args.title));
                 }
                 case "reply": {
                     const { session_id, content } = args;
@@ -3266,7 +3589,7 @@ function createMindMcpServer(client) {
                         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 }]));
+                    return okSession(await client.appendAgentSession(session_id, [{ role: "assistant", content }]));
                 }
                 case "close": {
                     const { session_id } = args;
@@ -3294,11 +3617,22 @@ function createMindMcpServer(client) {
                         before_seq: args.before_seq,
                     }));
                 }
+                case "heartbeat": {
+                    const { source_key } = args;
+                    if (!source_key)
+                        return err("Error: 'source_key' is required for heartbeat.");
+                    return ok(await client.agentSessionHeartbeat({
+                        source_key,
+                        agent: args.agent,
+                        runtime: args.runtime,
+                        unsynced: args.unsynced,
+                    }));
+                }
                 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));
+                    return okSession(await client.agentSessionInbox(session_id));
                 }
                 case "handoff": {
                     const { session_id, to_source_key } = args;
@@ -3353,6 +3687,39 @@ function createMindMcpServer(client) {
                         }
                     }
                 }
+                // Flat aliases for the three wake_target sub-actions (additive; the
+                // wake_target + wake_action form below keeps working). The secret is
+                // owner-private: the backend never returns it, so neither do we.
+                case "wake_targets":
+                    return ok(await client.listAgentWakeTargets());
+                case "wake_target_set":
+                case "wake_target_clear": {
+                    if (!args.agent)
+                        return err(`Error: 'agent' is required for ${action}.`);
+                    const wakeAgent = typeof args.agent === "string" ? args.agent : args.agent.label ?? args.agent.key;
+                    if (!wakeAgent)
+                        return err(`Error: 'agent' must be a bot name for ${action}.`);
+                    if (action === "wake_target_clear")
+                        return ok(await client.clearAgentWakeTarget(wakeAgent, args.runtime ?? "grok"));
+                    if (!args.url)
+                        return err("Error: 'url' (the webhook routine URL) is required for wake_target_set.");
+                    return ok(await client.setAgentWakeTarget({ agent: wakeAgent, url: args.url, secret: args.secret, runtime: args.runtime ?? "grok" }));
+                }
+                case "wake_target": {
+                    const wakeAction = args.wake_action ?? "set";
+                    if (wakeAction === "list")
+                        return ok(await client.listAgentWakeTargets());
+                    if (!args.agent)
+                        return err(`Error: 'agent' is required for wake_target wake_action=${wakeAction}.`);
+                    const agentName = typeof args.agent === "string" ? args.agent : args.agent.label ?? args.agent.key;
+                    if (!agentName)
+                        return err("Error: 'agent' must be a bot name for wake_target.");
+                    if (wakeAction === "clear")
+                        return ok(await client.clearAgentWakeTarget(agentName, args.runtime));
+                    if (!args.url)
+                        return err("Error: 'url' (the webhook routine URL) is required for wake_target wake_action=set.");
+                    return ok(await client.setAgentWakeTarget({ agent: agentName, url: args.url, secret: args.secret, runtime: args.runtime }));
+                }
                 case "share": {
                     const { session_id, grantee_username } = args;
                     if (!session_id)
@@ -3379,6 +3746,94 @@ function createMindMcpServer(client) {
                     await client.revokeAgentSessionShare(session_id, share_id);
                     return ok({ ok: true, session_id, share_id });
                 }
+                case "agent_doc_get": {
+                    const { agent_key } = args;
+                    if (!agent_key)
+                        return err("Error: 'agent_key' is required for agent_doc_get.");
+                    return ok(await client.getAgentDoc(agent_key));
+                }
+                case "agent_doc_update": {
+                    const { agent_key, content, editor } = args;
+                    if (!agent_key)
+                        return err("Error: 'agent_key' is required for agent_doc_update.");
+                    if (content === undefined)
+                        return err("Error: 'content' is required for agent_doc_update.");
+                    if (!editor)
+                        return err("Error: 'editor' is required for agent_doc_update.");
+                    return ok(await client.updateAgentDoc(agent_key, {
+                        content,
+                        editor,
+                        note: args.note,
+                        base_version: args.base_version,
+                    }));
+                }
+                case "attach": {
+                    const { agent_key, attachments } = args;
+                    if (!agent_key)
+                        return err("Error: 'agent_key' is required for attach.");
+                    if (!attachments)
+                        return err("Error: 'attachments' is required for attach.");
+                    return ok(await client.setAgentAttachments(agent_key, attachments));
+                }
+                case "resume": {
+                    const { agent } = args;
+                    if (!agent || typeof agent !== "string") {
+                        return err("Error: 'agent' (a plain string naming the agent) is required for resume.");
+                    }
+                    return ok(await client.resumeAgent({
+                        agent,
+                        runtime: args.runtime,
+                        source_key: args.source_key,
+                        external_session_id: args.external_session_id,
+                        title: args.title,
+                    }));
+                }
+                case "mentions": {
+                    const as_key = args.as_key;
+                    if (!as_key)
+                        return err("Error: 'as_key' is required for mentions.");
+                    return ok(await client.getAgentMentions(as_key));
+                }
+                case "group_create": {
+                    const { participant_keys } = args;
+                    if (!participant_keys || participant_keys.length === 0) {
+                        return err("Error: 'participant_keys' (at least 2) is required for group_create.");
+                    }
+                    return ok(await client.createAgentSessionGroup(args.title ?? "New group", participant_keys));
+                }
+                case "group_list":
+                    return ok(await client.listAgentSessionGroups());
+                case "group_get": {
+                    const { group_id } = args;
+                    if (!group_id)
+                        return err("Error: 'group_id' is required for group_get.");
+                    return ok(await client.getAgentSessionGroup(group_id, args.limit));
+                }
+                case "group_post": {
+                    const { group_id, author_key, content } = args;
+                    if (!group_id)
+                        return err("Error: 'group_id' is required for group_post.");
+                    if (!author_key)
+                        return err("Error: 'author_key' is required for group_post.");
+                    if (!content)
+                        return err("Error: 'content' is required for group_post.");
+                    return ok(await client.postAgentSessionGroupMessage(group_id, author_key, content));
+                }
+                case "group_inbox": {
+                    const { group_id, as_key } = args;
+                    if (!group_id)
+                        return err("Error: 'group_id' is required for group_inbox.");
+                    if (!as_key)
+                        return err("Error: 'as_key' is required for group_inbox.");
+                    return ok(await client.getAgentSessionGroupInbox(group_id, as_key));
+                }
+                case "group_delete": {
+                    const { group_id } = args;
+                    if (!group_id)
+                        return err("Error: 'group_id' is required for group_delete.");
+                    await client.deleteAgentSessionGroup(group_id);
+                    return ok({ ok: true });
+                }
                 default: {
                     const _exhaustive = action;
                     return err(`Unknown action: ${_exhaustive}`);