@grupr/mcp-server 0.4.0 → 0.17.5

package/dist/index.js

@@ -27,7 +27,7 @@ const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const sdk_1 = require("@grupr/sdk");
 const AGENT_TOKEN = process.env.GRUPR_AGENT_TOKEN || process.env.GRUPR_API_KEY || '';
 const BASE_URL = process.env.GRUPR_BASE_URL || 'https://api.grupr.ai/api/v1/agent-hub';
-const SERVER_VERSION = '0.4.0';
+const SERVER_VERSION = '0.17.5';
 // ── Real-time wait tuning ───────────────────────────────
 /** Default block duration for grupr_wait_for_messages. */
 const DEFAULT_WAIT_SECONDS = 60;
@@ -48,7 +48,8 @@ const client = new sdk_1.GruprClient({ agentToken: AGENT_TOKEN, baseUrl: BASE_UR
 const TOOLS = [
     {
         name: 'grupr_poll_messages',
-        description: 'Poll messages in a grupr this agent is assigned to. Returns chronological message history. Pass `after` (RFC3339 timestamp from a previous message\'s created_at) to get only newer messages — the standard pattern for incremental polling.',
+        description: 'Poll messages in a grupr this agent is assigned to. Returns chronological message history. Pass `after` (RFC3339 timestamp from a previous message\'s created_at) to get only newer messages — the standard pattern for incremental polling. ' +
+            'A message may carry `attachments` (Room Files: file_id, name, size, content_type); read one with grupr_room_file_read by its name.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -99,19 +100,29 @@ const TOOLS = [
     },
     {
         name: 'grupr_send_message',
-        description: "Send a message as this agent in a grupr it's assigned to. Billable. Markdown is supported in `content`.",
+        description: "Send a message as this agent in a grupr it's assigned to. Billable. Markdown is supported in `content`. " +
+            'To hand people a file, attach Room Files (publish a workspace file there first with grupr_workspace_publish, or write one with grupr_room_doc_write); ' +
+            'they appear under the message and open in place.',
         inputSchema: {
             type: 'object',
             properties: {
                 grupr_id: { type: 'string', description: 'UUID of the target grupr.' },
-                content: { type: 'string', description: 'Message body (markdown).' },
+                content: { type: 'string', description: 'Message body (markdown). May be empty when attachments are given.' },
+                attachments: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    maxItems: 5,
+                    description: "Room Files to attach, by path (as grupr_room_files lists them, e.g. 'reports/q3.pdf') or file_id. Up to 5.",
+                },
             },
-            required: ['grupr_id', 'content'],
+            required: ['grupr_id'],
         },
     },
     {
         name: 'grupr_register_webhook',
-        description: 'Register an HTTPS webhook URL for this agent. The Grupr backend will POST event payloads (HMAC-signed with `secret`) to the URL when grupr events fire. Upsert semantics — one webhook per agent.',
+        description: 'Register an HTTPS webhook URL for this agent. The Grupr backend will POST event payloads (HMAC-signed with `secret`) to the URL when grupr events fire: ' +
+            "every message in a room this agent is in, other than its own. Upsert semantics — one webhook per agent; one URL may serve several agents, " +
+            'and every delivery names its agent (X-Grupr-Agent-ID header) and room (room_id in the body). Check it with grupr_test_webhook; see what fired with grupr_webhook_deliveries.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -129,10 +140,526 @@ const TOOLS = [
     },
     {
         name: 'grupr_delete_webhook',
-        description: "Remove this agent's webhook registration.",
+        description: "Remove this agent's webhook registration. Its delivery history is kept.",
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'grupr_webhook_deliveries',
+        description: "This agent's webhook delivery history, newest first, across every webhook it has had (removed ones included). " +
+            'Each row: id, webhook_id, event, room_id, message_id, status (pending / delivered / failed / exhausted), attempts, ' +
+            'http_status, last_error, receiver_said, duration_ms, created_at, delivered_at, next_attempt_at. ' +
+            'Pass message_id to answer "did my webhook fire for that post?". Every message in a room the agent is in, other than its own, ' +
+            'gets a delivery; failures retry with backoff (5 s, 30 s, 2 min, 10 min, then hourly). URLs and keys never appear here.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                message_id: { type: 'string', description: 'Only deliveries that carried this room message (UUID).' },
+                limit: { type: 'number', description: 'Max rows (1-200). Default 50.' },
+            },
+        },
+    },
+    {
+        name: 'grupr_test_webhook',
+        description: "Send one sample delivery to this agent's webhook now, with the same headers as a real one (X-Grupr-Agent-ID; room_id in the body), " +
+            "and return what the receiver said (status, http_status, receiver_said, duration_ms). It is kept in the delivery history, is never retried, " +
+            'and never counts toward auto-suspension. Optional room_id: a room this agent is in.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                room_id: { type: 'string', description: 'UUID of a room this agent is assigned to (optional).' },
+            },
+        },
+    },
+    // ── Workspace (AgentOS, D-144) ─────────────────────────
+    {
+        name: 'grupr_workspace_info',
+        description: "This agent's persistent workspace: a Linux sandbox that keeps its files between calls and pauses when idle. " +
+            'Returns its state (none / running / paused / lost), root path (/home/user), last use and run count. ' +
+            'The workspace is created on the first command or file operation.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'grupr_workspace_run',
+        description: 'If the owner set a daily sandbox budget and it is used up, this (and file tools) answer HTTP 429 until 00:00 UTC; grupr_workspace_info shows sandbox_budget_seconds, sandbox_seconds_today and sandbox_budget_resets_at. ' +
+            "Run a shell command in this agent's workspace. EVERY command needs a human decision first: an approval card " +
+            'appears in the room you name in grupr_id (and on the owner\'s Grupr dashboard); the call blocks up to ~2 minutes ' +
+            'for Approve/Deny. Approved → the command runs and you get exit_code, stdout, stderr. Denied → you get the reason; ' +
+            'do not retry the same command, say so in the room. No answer in time → you get status "pending" with a run_id: the command ' +
+            'RUNS THE MOMENT A HUMAN APPROVES and its result is posted into the room as you, so keep following the room ' +
+            '(grupr_wait_for_messages) or call grupr_workspace_result with the run_id. Never re-submit a pending command. ' +
+            'Standing permissions the owner has granted for this agent auto-approve (auto_approved: true). ' +
+            'Commands run under /bin/sh in /home/user by default; files persist between calls; the sandbox pauses after ~5 idle minutes ' +
+            'and resumes transparently (running processes do not survive a pause). Output is capped at 512 KB and scrubbed of credential shapes.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cmd: { type: 'string', description: 'Shell command line (sh -c). Keep it to one purpose per call — that is what the human approves.' },
+                cwd: { type: 'string', description: 'Working directory inside /home/user. Default /home/user.' },
+                grupr_id: { type: 'string', description: 'UUID of the room the approval should appear in. Always pass the room you are working in.' },
+                timeout_seconds: { type: 'number', description: 'Wall-clock cap for the command (default 60, max 300).' },
+            },
+            required: ['cmd'],
+        },
+    },
+    {
+        name: 'grupr_workspace_result',
+        description: 'Fetch a workspace run by run_id: its status (pending / running / done / failed / denied / cancelled / expired) and, once finished, exit_code, stdout and stderr. Use after grupr_workspace_run returned "pending".',
+        inputSchema: {
+            type: 'object',
+            properties: { run_id: { type: 'string', description: 'The run_id from grupr_workspace_run.' } },
+            required: ['run_id'],
+        },
+    },
+    {
+        name: 'grupr_workspace_files',
+        description: 'List one directory of the workspace (name, type, size, modified). Paths are confined to /home/user.',
+        inputSchema: {
+            type: 'object',
+            properties: { path: { type: 'string', description: 'Directory to list. Default /home/user.' } },
+        },
+    },
+    {
+        name: 'grupr_workspace_read',
+        description: 'Read a file from the workspace. Text comes back as text; binary or oversized content comes back base64-encoded with a note. Files up to 10 MB.',
+        inputSchema: {
+            type: 'object',
+            properties: { path: { type: 'string', description: 'Absolute path under /home/user, or relative to it.' } },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'grupr_workspace_write',
+        description: 'Write a text file into the workspace (parent directories are created). No approval is needed to write files; running them is what gets approved.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path under /home/user, or relative to it.' },
+                content: { type: 'string', description: 'File contents (UTF-8).' },
+            },
+            required: ['path', 'content'],
+        },
+    },
+    // ── Room Files (shared per-room store, D-144 inc. 3) ──
+    {
+        name: 'grupr_room_files',
+        description: "List a grupr's shared Files: the durable store every member of the room sees (humans upload, agents publish). " +
+            'Each entry has file_id, name (a path like reports/q3.md), size, content_type, version, who added it and when. ' +
+            'The agent must be assigned to the grupr.',
+        inputSchema: {
+            type: 'object',
+            properties: { grupr_id: { type: 'string', description: 'The grupr (room) id.' } },
+            required: ['grupr_id'],
+        },
+    },
+    {
+        name: 'grupr_room_file_read',
+        description: "Read one of a grupr's shared Files by file_id or name, as text you can reason about: Markdown, text, CSV, and the text of Word (.docx), " +
+            'PowerPoint (.pptx) and PDF files; Excel (.xlsx) comes back sheet by sheet as CSV. Images and other binaries return a short description ' +
+            '(or base64 when nothing better exists). To work on the raw file in the workspace instead, use grupr_workspace_fetch.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                grupr_id: { type: 'string', description: 'The grupr (room) id.' },
+                file: { type: 'string', description: 'file_id or the name shown by grupr_room_files.' },
+            },
+            required: ['grupr_id', 'file'],
+        },
+    },
+    {
+        name: 'grupr_workspace_publish',
+        description: "Copy a file from this agent's workspace into a grupr's shared Files so every member can download it. " +
+            'Same name replaces the previous version. The room is told, as this agent. No approval is needed: publishing is a file write, not a command.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                grupr_id: { type: 'string', description: 'The grupr (room) to publish into; the agent must be assigned to it.' },
+                path: { type: 'string', description: 'Workspace path of the file (absolute under /home/user, or relative to it).' },
+                name: { type: 'string', description: 'Name inside the room, e.g. reports/q3.md. Defaults to the file name.' },
+            },
+            required: ['grupr_id', 'path'],
+        },
+    },
+    {
+        name: 'grupr_workspace_fetch',
+        description: "Copy one of a grupr's shared Files into this agent's workspace. Default destination is /home/user/rooms/<grupr_id>/<name>; " +
+            'pass path to choose another (a trailing slash means a directory).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                grupr_id: { type: 'string', description: 'The grupr (room) id.' },
+                file: { type: 'string', description: 'file_id or the name shown by grupr_room_files.' },
+                path: { type: 'string', description: 'Destination in the workspace (optional).' },
+            },
+            required: ['grupr_id', 'file'],
+        },
+    },
+    {
+        name: 'grupr_workspace_summary',
+        description: "What this agent did recently, in numbers: sandbox time, runs (failed, denied), routine firings (failed, routines failing now), connection uses (refused), files published, " +
+            'and whether the daily sandbox budget was reached. Use it to report on yourself honestly or to notice a routine that keeps failing. The owner sees the same on the agent page and in a Monday email.',
+        inputSchema: { type: 'object', properties: { days: { type: 'number', description: 'Window in days, 1-90 (default 7).' } } },
+    },
+    // ── Connections (D-144 inc. 21) ──
+    {
+        name: 'grupr_workspace_download',
+        description: "Have Grupr fetch a URL and write the response into this agent's workspace: the body at path, plus path.meta.json (status, bytes, ms, error). " +
+            'Name a connection to fetch with a credential the owner stored: Grupr attaches it and hands back only the response, so the credential never reaches you. ' +
+            'A connection works here only if the owner opened it to the agent (grupr_workspace_connections shows which); otherwise use it from a routine input. ' +
+            'Public destinations only, GET, https with a connection, 5 MB.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Absolute http(s) URL.' },
+                path: { type: 'string', description: 'Destination file in the workspace (default downloads/<host>/<file>; a trailing slash means a directory).' },
+                connection: { type: 'string', description: "Name of one of this agent's connections; the URL must be https on its host." },
+            },
+            required: ['url'],
+        },
+    },
+    {
+        name: 'grupr_workspace_connection_request',
+        description: "Ask the owner for a connection you need: a credential for one host, stored by the owner and attached by Grupr to fetches on your behalf (you never see the value). " +
+            'Give the name you will use, the host, how the credential is sent (bearer, header with header_name, or basic) and why. The room you name is told; the owner adds the value on the agent page and the room is told when it is ready. ' +
+            'Asking again for the same name is harmless. At most 5 pending.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Lowercase letters, digits and dashes, e.g. github.' },
+                host: { type: 'string', description: 'The only host the credential will ever be sent to, e.g. api.github.com.' },
+                auth_type: { type: 'string', enum: ['bearer', 'header', 'basic'] },
+                header_name: { type: 'string', description: 'For auth_type header, e.g. X-Api-Key.' },
+                reason: { type: 'string', description: 'One line: what you will fetch with it (shown to the owner).' },
+                grupr_id: { type: 'string', description: 'The room to tell (optional; the agent must be in it). Required with then_recipe.' },
+                then_recipe: {
+                    type: 'string',
+                    description: 'Optional plan: the recipe you will run through this connection once it exists (one that takes a connection: api-watch, site-check, page-watch; see grupr_workspace_recipes). Its URLs must be on the host. Validated now; the owner sees it on the request and chooses to install it when adding the value. The routine is then the owner\'s.',
+                },
+                then_params: { type: 'object', description: "The recipe's parameters (not connection; that is this request).", additionalProperties: { type: 'string' } },
+            },
+            required: ['name', 'host', 'auth_type'],
+        },
+    },
+    {
+        name: 'grupr_workspace_connections',
+        description: "List this agent's connections: name, host, how the credential is sent, and whether the agent may use it directly. Values are never shown. " +
+            'Use a name in grupr_workspace_download, or in a routine input ({"url","path","connection"}) when proposing a schedule.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    // ── Routines (D-144 inc. 13) ──
+    {
+        name: 'grupr_workspace_schedule',
+        description: "Propose a routine: one shell command that runs in this agent's workspace on a cron, with the result posted in the room each time. " +
+            "A human must approve the proposal once (an approval card appears in the room you name and on the owner's dashboard); after that the " +
+            'routine runs on its own without asking again, so only propose commands you would be happy to see run unattended. Destructive commands ' +
+            'cannot be scheduled, the minimum interval is 5 minutes, and an agent may have at most 20 routines. Returns pending (card raised — do not ' +
+            're-submit; the room is told when it is created) or created (a standing rule allowed it).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                grupr_id: { type: 'string', description: 'The grupr (room) the routine belongs to and posts into; the agent must be assigned to it.' },
+                cmd: { type: 'string', description: 'The shell command, exactly as grupr_workspace_run would run it.' },
+                cron: {
+                    type: 'string',
+                    description: 'Five-field cron (minute hour day-of-month month day-of-week), e.g. "0 8 * * 1-5" = weekdays 08:00; or @hourly / @daily / @weekly / @monthly.',
+                },
+                timezone: { type: 'string', description: 'IANA timezone the cron is read in (default UTC), e.g. America/New_York.' },
+                label: { type: 'string', description: 'Short human label, e.g. "Morning report" (≤ 80 chars).' },
+                cwd: { type: 'string', description: 'Working directory (default /home/user).' },
+                timeout_seconds: { type: 'number', description: 'Per-run wall clock, up to 300 (default 300).' },
+                outputs: {
+                    type: 'array',
+                    description: "Up to 5 workspace files to publish into the room's Files after each successful run, e.g. " +
+                        '[{"path":"out/report.md"},{"path":"out/data.csv","name":"reports/data.csv"}]. Default name routines/<basename>; same name replaces (version history kept). ' +
+                        'This is how a scheduled report reaches people: write the file in the workspace, name it here.',
+                    items: { type: 'object', properties: { path: { type: 'string' }, name: { type: 'string' } }, required: ['path'] },
+                },
+                inputs: {
+                    type: 'array',
+                    description: 'Up to 10 URLs Grupr fetches before each run and writes into the workspace, e.g. [{"url":"https://api.example.com/status","path":"in/status.json","connection":"intranet"}]. ' +
+                        'Each lands at path with a path.meta.json sidecar (status, bytes, ms, error) for the script to read. With a connection, Grupr attaches the stored credential and the URL must be https on its host. ' +
+                        'This is how a routine reads a private API or page without the credential ever entering the workspace.',
+                    items: { type: 'object', properties: { url: { type: 'string' }, path: { type: 'string' }, connection: { type: 'string' } }, required: ['url', 'path'] },
+                },
+                render: { type: 'boolean', description: 'Render Markdown outputs through Documents: name.md + .html + .docx + .pdf in Files.' },
+                notify: {
+                    type: 'string',
+                    enum: ['always', 'failures', 'output'],
+                    description: "always (default): post every run's output in the room; failures: post only failing runs; output: post only when the run prints something or fails " +
+                        '(like cron mail-on-output: write the script to stay silent unless there is news, and a silent run also publishes its files quietly).',
+                },
+            },
+            required: ['grupr_id', 'cmd', 'cron'],
+        },
+    },
+    {
+        name: 'grupr_workspace_schedules',
+        description: "List this agent's routines: schedule, timezone, room, enabled, next and last run, run and failure counts.",
         inputSchema: { type: 'object', properties: {} },
     },
+    {
+        name: 'grupr_workspace_unschedule',
+        description: "Remove one of this agent's routines by schedule_id. The room is told. (Owners can also pause or remove routines from the agent page.)",
+        inputSchema: {
+            type: 'object',
+            properties: { schedule_id: { type: 'string' } },
+            required: ['schedule_id'],
+        },
+    },
+    {
+        name: 'grupr_workspace_schedule_runs',
+        description: "What one of this agent's routines did on its recent firings: when, exit code, how long, an excerpt of the output, and what it published to the room's Files. " +
+            'Use it to check a routine is healthy before telling a person it is, or to see why it failed. Full output of one run: grupr_workspace_result with its run_id.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                schedule_id: { type: 'string', description: 'From grupr_workspace_schedules.' },
+                limit: { type: 'number', description: 'How many firings, newest first (default 10, max 100).' },
+            },
+            required: ['schedule_id'],
+        },
+    },
+    // ── Recipes (D-144 inc. 16–17) ──
+    {
+        name: 'grupr_workspace_recipes',
+        description: 'List the ready-made routines (recipes) this server offers: what each does, how often it runs, what it needs from you (parameters) and what it publishes. ' +
+            'Prefer a recipe over writing your own routine when one fits: its script is tested, quiet by default, and a person only has to approve it once.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'grupr_workspace_recipe',
+        description: "Ask for a recipe to be installed for this agent: Grupr writes the recipe's script into the workspace and schedules it. A human must approve first " +
+            '(an approval card shows the recipe and exactly what it will check); nothing is installed until then. Returns pending (do not re-submit; the room is told when it is created) ' +
+            'or created (a standing rule allowed it). Asking again for a recipe you already run updates its parameters after approval and keeps the one routine. ' +
+            'If params.connection names a connection this agent does not have yet, the owner is asked for it instead (a connection request carrying this recipe as its plan; returns awaiting_connection): when they add the value and say yes, the routine is installed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                recipe_id: { type: 'string', description: 'From grupr_workspace_recipes, e.g. site-check, page-watch, workspace-report.' },
+                grupr_id: { type: 'string', description: 'The grupr (room) the routine belongs to and posts into; the agent must be assigned to it.' },
+                params: {
+                    type: 'object',
+                    description: 'The recipe parameters as strings, e.g. {"urls": "https://a.example\nhttps://b.example"} for site-check or {"url": "https://example.com/pricing"} for page-watch. http(s) URLs only. ' +
+                        'site-check and page-watch also take an optional "connection" (a name from grupr_workspace_connections): Grupr then fetches with that credential and the script reads what came back.',
+                    additionalProperties: { type: 'string' },
+                },
+                timezone: { type: 'string', description: 'IANA timezone for the schedule (default UTC).' },
+                cron: { type: 'string', description: "Optional five-field cron to replace the recipe's own schedule (minimum interval 5 minutes)." },
+            },
+            required: ['recipe_id', 'grupr_id'],
+        },
+    },
+    // ── Documents (D-144 inc. 4) ──
+    {
+        name: 'grupr_room_doc_write',
+        description: "Write a document into a grupr's shared Files from Markdown. Grupr renders it to <name>.md, <name>.html, a real Word file <name>.docx and a PDF <name>.pdf " +
+            '(headings, bold/italic/code/links, bullet and numbered lists, tables, code blocks, quotes). Members read it in the room (click the file) ' +
+            'or download the .docx. Same name replaces. The room is told once, as this agent. Prefer this over writing files in the workspace when a ' +
+            'human needs to read the result.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                grupr_id: { type: 'string', description: 'The grupr (room) id; the agent must be assigned to it.' },
+                name: { type: 'string', description: 'Document name without extension, folders allowed (e.g. reports/q3-review). Defaults to a slug of the title / first heading.' },
+                title: { type: 'string', description: 'Document title (defaults to the first # heading).' },
+                markdown: { type: 'string', description: 'The document body in Markdown (≤ 1 MB).' },
+                formats: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['md', 'html', 'docx', 'pdf'] },
+                    description: 'Which files to produce. Default: md, html, docx, pdf.',
+                },
+            },
+            required: ['grupr_id', 'markdown'],
+        },
+    },
+    {
+        name: 'grupr_room_sheet_write',
+        description: "Write a spreadsheet into a grupr's shared Files from a table spec: Grupr produces <name>.xlsx (bold frozen header, autofilter, numbers as " +
+            'numbers) and <name>.csv of the first sheet. Up to 20 sheets / 256 columns / 200k cells. Same name replaces. The room is told once, as this agent.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                grupr_id: { type: 'string', description: 'The grupr (room) id; the agent must be assigned to it.' },
+                name: { type: 'string', description: 'Workbook name without extension, folders allowed. Defaults to the first sheet name.' },
+                sheets: {
+                    type: 'array',
+                    minItems: 1,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string', description: 'Sheet tab name (≤ 31 chars).' },
+                            columns: { type: 'array', items: { type: 'string' }, description: 'Header row.' },
+                            rows: {
+                                type: 'array',
+                                items: { type: 'array', items: {} },
+                                description: 'Data rows; values are numbers, strings, booleans or null. Numeric strings become numbers.',
+                            },
+                        },
+                        required: ['name', 'columns'],
+                    },
+                },
+                formats: { type: 'array', items: { type: 'string', enum: ['xlsx', 'csv'] }, description: 'Default: both.' },
+            },
+            required: ['grupr_id', 'sheets'],
+        },
+    },
+    // ── Mail (D-144 inc. 5, outbound) ──
+    {
+        name: 'grupr_mail_send',
+        description: 'Email someone on behalf of the room. NOTHING is sent until a human approves: an approval card with the recipients, subject, ' +
+            'preview and attachments appears in the grupr you name. The call waits up to ~2 minutes; if approved it sends and returns ' +
+            '"sent", if denied you get the reason (do not retry), otherwise it returns "pending" and the mail goes out the moment someone ' +
+            'approves (receipt posted in the room; check with grupr_mail_status). The message leaves as "<agent name> via Grupr" from the ' +
+            'shared agent address, with a footer naming the agent and its owner. Attachments must be files in that grupr\'s shared Files ' +
+            '(by name or file_id) — write them first with grupr_room_doc_write / grupr_room_sheet_write / grupr_workspace_publish.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                grupr_id: { type: 'string', description: 'The grupr (room) this mail is sent from; the agent must be assigned to it.' },
+                to: { type: 'array', items: { type: 'string' }, description: 'Recipients ("Name <addr>" or bare addresses). Max 10 with cc.' },
+                cc: { type: 'array', items: { type: 'string' } },
+                subject: { type: 'string' },
+                markdown: { type: 'string', description: 'Body in Markdown (rendered to HTML + plain text).' },
+                attachments: { type: 'array', items: { type: 'string' }, description: 'Room File names or ids (max 5, 8 MB total).' },
+                in_reply_to: { type: 'string', description: 'mail_id of an inbound mail you are answering (from grupr_mail_inbox). Threads the reply and prefixes "Re:".' },
+            },
+            required: ['grupr_id', 'to', 'subject', 'markdown'],
+        },
+    },
+    {
+        name: 'grupr_mail_inbox',
+        description: "Mail that arrived FOR this agent (people replying to its mail, or writing to its address). Each inbound mail was also posted into a room as \"📨 Mail for <agent>\", so you usually see it there first; use this to list or re-check. " +
+            'Returns mail_id, from, subject, when, which room it landed in, and attachment names (saved in that room\'s Files under mail/). Read the full text with grupr_mail_read; answer with grupr_mail_send and in_reply_to.',
+        inputSchema: {
+            type: 'object',
+            properties: { limit: { type: 'number', description: 'How many (default 10, max 100).' } },
+        },
+    },
+    {
+        name: 'grupr_mail_read',
+        description: 'Full text of one mail (inbound or sent) by mail_id: headers, body text, attachments, status.',
+        inputSchema: {
+            type: 'object',
+            properties: { mail_id: { type: 'string' } },
+            required: ['mail_id'],
+        },
+    },
+    {
+        name: 'grupr_mail_status',
+        description: 'Status of a mail this agent asked to send: pending / sending / sent / failed / denied / cancelled / expired, with the provider id or error.',
+        inputSchema: {
+            type: 'object',
+            properties: { mail_id: { type: 'string' } },
+            required: ['mail_id'],
+        },
+    },
 ];
+// ── Workspace HTTP (raw fetch; the SDK predates these endpoints) ───────────
+class HubError extends Error {
+    status;
+    code;
+    approvalId;
+    constructor(status, code, message, approvalId) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.approvalId = approvalId;
+    }
+}
+async function hubFetch(path, init = {}) {
+    const headers = {
+        Authorization: `Bearer ${AGENT_TOKEN}`,
+        'User-Agent': `grupr-mcp-server/${SERVER_VERSION}`,
+        ...(init.headers || {}),
+    };
+    return fetch(`${BASE_URL}${path}`, { ...init, headers });
+}
+async function hubJSON(path, init = {}) {
+    const res = await hubFetch(path, init);
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = null;
+    }
+    if (!res.ok) {
+        const e = body?.errors?.[0];
+        throw new HubError(res.status, e?.code || 'error', e?.message || body?.error || `HTTP ${res.status}`, res.headers.get('x-approval-id') || undefined);
+    }
+    return (body?.data ?? body);
+}
+// previewToText flattens the api's structured preview into text an agent can
+// read. Returns null when the raw download is the better answer.
+function previewToText(p) {
+    const head = `${p.name ?? ''} (${p.content_type ?? ''}, ${p.size ?? '?'} B)`;
+    const csv = (rows) => rows
+        .map((r) => r.map((c) => (/[",\n]/.test(c ?? '') ? `"${String(c ?? '').replace(/"/g, '""')}"` : (c ?? ''))).join(','))
+        .join('\n');
+    switch (p.kind) {
+        case 'markdown': {
+            const src = p.source ? ` — text extracted from ${String(p.source).toUpperCase()}; formatting approximate` : '';
+            const body = typeof p.text === 'string' && p.text ? p.text : blocksToText(p.blocks ?? []);
+            return `${head}${src}${p.truncated ? ' [truncated]' : ''}\n\n${body}`;
+        }
+        case 'table':
+            return `${head}${p.truncated ? ' [truncated]' : ''}\n\n${csv([p.header ?? [], ...(p.rows ?? [])])}`;
+        case 'workbook': {
+            const parts = (p.sheets ?? []).map((sh) => `### ${sh.name}${sh.truncated ? ' [truncated]' : ''}\n${csv([sh.header ?? [], ...(sh.rows ?? [])])}`);
+            return `${head} — ${(p.sheets ?? []).length} sheet(s)\n\n${parts.join('\n\n')}`;
+        }
+        case 'text':
+            return `${head}${p.truncated ? ' [truncated]' : ''}\n\n${p.text ?? ''}`;
+        case 'pdf':
+            return typeof p.text === 'string' && p.text
+                ? `${head} — text extracted from PDF; layout not preserved\n\n${p.text}`
+                : `${head} — a PDF whose text could not be extracted (scanned or custom fonts). Download it with grupr_workspace_fetch if you need the bytes.`;
+        case 'image':
+            return `${head} — an image. Fetch it into the workspace with grupr_workspace_fetch to process it.`;
+        default:
+            return null;
+    }
+}
+function blocksToText(blocks) {
+    const spans = (ss) => (ss ?? []).map((s) => (s.break ? '\n' : s.text ?? '')).join('');
+    const out = [];
+    for (const b of blocks) {
+        switch (b.kind) {
+            case 'heading':
+                out.push('#'.repeat(b.level ?? 1) + ' ' + spans(b.spans));
+                break;
+            case 'paragraph':
+            case 'quote':
+                out.push(spans(b.spans));
+                break;
+            case 'code':
+                out.push('```\n' + (b.text ?? '') + '\n```');
+                break;
+            case 'list':
+                out.push((b.items ?? []).map((it, i) => `${b.ordered ? i + 1 + '.' : '-'} ${spans(it.spans)}`).join('\n'));
+                break;
+            case 'table':
+                out.push([b.header ?? [], ...(b.rows ?? [])].map((r) => '| ' + r.map((c) => spans(c.spans)).join(' | ') + ' |').join('\n'));
+                break;
+            case 'hr':
+                out.push('---');
+                break;
+        }
+    }
+    return out.join('\n\n');
+}
+function textOrBase64(buf) {
+    const isText = !buf.subarray(0, 8000).includes(0);
+    if (isText && buf.length <= 200 * 1024) {
+        return { text: buf.toString('utf8') };
+    }
+    return {
+        base64: buf.toString('base64'),
+        note: isText
+            ? 'Text file over 200 KB returned as base64.'
+            : 'Binary content returned as base64.',
+    };
+}
 // ── Real-time wait ──────────────────────────────────────
 //
 // Wraps the SDK's WebSocket-backed streamEvents() in a bounded, blocking
@@ -260,7 +787,20 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'grupr_send_message': {
-                const msg = await client.sendMessage(String(args.grupr_id), String(args.content));
+                const content = typeof args.content === 'string' ? args.content : '';
+                const attachments = Array.isArray(args.attachments)
+                    ? args.attachments.filter((a) => typeof a === 'string' && a.trim() !== '')
+                    : [];
+                if (!content.trim() && attachments.length === 0) {
+                    throw new Error('content or attachments is required');
+                }
+                const msg = attachments.length > 0
+                    ? await hubJSON(`/grups/${encodeURIComponent(String(args.grupr_id))}/messages`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ content, attachments }),
+                    })
+                    : await client.sendMessage(String(args.grupr_id), content);
                 return {
                     content: [
                         {
@@ -287,14 +827,557 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case 'grupr_delete_webhook': {
                 await client.deleteWebhook();
                 return {
-                    content: [{ type: 'text', text: 'Webhook removed.' }],
+                    content: [{ type: 'text', text: 'Webhook removed. Its delivery history is kept (grupr_webhook_deliveries).' }],
+                };
+            }
+            case 'grupr_webhook_deliveries': {
+                const q = new URLSearchParams();
+                if (typeof args.message_id === 'string' && args.message_id.trim())
+                    q.set('message_id', args.message_id.trim());
+                if (typeof args.limit === 'number')
+                    q.set('limit', String(Math.min(Math.max(1, Math.floor(args.limit)), 200)));
+                const res = await hubFetch(`/deliveries${q.toString() ? `?${q}` : ''}`);
+                const body = await res.json().catch(() => null);
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code || 'error', e?.message || `HTTP ${res.status}`);
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ count: body?.meta?.count ?? 0, webhook_id: body?.meta?.webhook_id ?? null, deliveries: body?.data ?? [] }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'grupr_test_webhook': {
+                const room = typeof args.room_id === 'string' && args.room_id.trim() ? { room_id: args.room_id.trim() } : {};
+                const d = await hubJSON('/webhooks/test', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(room),
+                });
+                return { content: [{ type: 'text', text: JSON.stringify(d, null, 2) }] };
+            }
+            case 'grupr_workspace_info': {
+                const info = await hubJSON('/workspace');
+                return { content: [{ type: 'text', text: JSON.stringify(info, null, 2) }] };
+            }
+            case 'grupr_workspace_run': {
+                const res = await hubJSON('/workspace/run', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        cmd: String(args.cmd),
+                        cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
+                        grupr_id: typeof args.grupr_id === 'string' ? args.grupr_id : undefined,
+                        timeout_seconds: typeof args.timeout_seconds === 'number' ? args.timeout_seconds : undefined,
+                    }),
+                });
+                return { content: [{ type: 'text', text: JSON.stringify(res, null, 2) }] };
+            }
+            case 'grupr_workspace_result': {
+                const run = await hubJSON(`/workspace/runs/${encodeURIComponent(String(args.run_id))}`);
+                return { content: [{ type: 'text', text: JSON.stringify(run, null, 2) }] };
+            }
+            case 'grupr_workspace_files': {
+                const p = typeof args.path === 'string' && args.path ? args.path : '/home/user';
+                const res = await hubFetch(`/workspace/files?path=${encodeURIComponent(p)}`);
+                const body = await res.json().catch(() => null);
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code || 'error', e?.message || `HTTP ${res.status}`);
+                }
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify({ path: body?.meta?.path ?? p, entries: body?.data ?? [] }, null, 2) },
+                    ],
+                };
+            }
+            case 'grupr_workspace_read': {
+                const p = String(args.path);
+                const res = await hubFetch(`/workspace/file?path=${encodeURIComponent(p)}`);
+                if (!res.ok) {
+                    const body = await res.json().catch(() => null);
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code || 'error', e?.message || `HTTP ${res.status}`);
+                }
+                const buf = Buffer.from(await res.arrayBuffer());
+                return { content: [{ type: 'text', text: JSON.stringify({ path: p, size: buf.length, ...textOrBase64(buf) }, null, 2) }] };
+            }
+            case 'grupr_room_files': {
+                const gid = encodeURIComponent(String(args.grupr_id));
+                const res = await hubFetch(`/grups/${gid}/files`);
+                const body = await res.json().catch(() => null);
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code || 'error', e?.message || `HTTP ${res.status}`);
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ files: body?.data ?? [], used_bytes: body?.meta?.used_bytes, quota_bytes: body?.meta?.quota_bytes }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'grupr_room_file_read': {
+                const gid = encodeURIComponent(String(args.grupr_id));
+                const ref = String(args.file);
+                const isId = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref);
+                // Documents first: the api's preview carries extracted text for
+                // Word / PowerPoint / PDF, sheets for Excel, blocks for Markdown.
+                let fileId = isId ? ref : '';
+                if (!fileId) {
+                    const lr = await hubFetch(`/grups/${gid}/files`);
+                    const lb = await lr.json().catch(() => null);
+                    const hit = (lb?.data ?? []).find((f) => f.name === ref || f.name === ref.replace(/^\/+/, ''));
+                    if (hit)
+                        fileId = hit.file_id;
+                }
+                if (fileId) {
+                    const pr = await hubFetch(`/grups/${gid}/files/${fileId}/preview`);
+                    const pb = await pr.json().catch(() => null);
+                    if (pr.ok && pb?.data) {
+                        const rendered = previewToText(pb.data);
+                        if (rendered !== null) {
+                            return { content: [{ type: 'text', text: rendered }] };
+                        }
+                    }
+                }
+                const res = await hubFetch(isId ? `/grups/${gid}/files/${ref}` : `/grups/${gid}/file?name=${encodeURIComponent(ref)}`);
+                if (!res.ok) {
+                    const body = await res.json().catch(() => null);
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code || 'error', e?.message || `HTTP ${res.status}`);
+                }
+                const buf = Buffer.from(await res.arrayBuffer());
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ file: ref, size: buf.length, content_type: res.headers.get('content-type') || undefined, ...textOrBase64(buf) }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'grupr_workspace_publish': {
+                const f = await hubJSON('/workspace/publish', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        grupr_id: String(args.grupr_id),
+                        path: String(args.path),
+                        name: typeof args.name === 'string' && args.name ? args.name : undefined,
+                    }),
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Published ${f.name ?? '?'} (${f.size ?? '?'} bytes, v${f.version ?? 1}) to the room's Files. file_id ${f.file_id ?? '?'}.`,
+                        },
+                    ],
+                };
+            }
+            case 'grupr_workspace_fetch': {
+                const ref = String(args.file);
+                const isId = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref);
+                const r = await hubJSON('/workspace/fetch', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        grupr_id: String(args.grupr_id),
+                        file_id: isId ? ref : undefined,
+                        name: isId ? undefined : ref,
+                        path: typeof args.path === 'string' && args.path ? args.path : undefined,
+                    }),
+                });
+                return { content: [{ type: 'text', text: `Fetched ${r.name ?? ref} (${r.size ?? '?'} bytes) into ${r.path ?? '?'}.` }] };
+            }
+            case 'grupr_workspace_summary': {
+                const days = typeof args.days === 'number' && args.days > 0 ? Math.min(90, Math.floor(args.days)) : 7;
+                const s = await hubJSON(`/workspace/summary?days=${days}`);
+                const min = (sec) => {
+                    const m = Math.round((sec ?? 0) / 60);
+                    return m < 60 ? `${m} min` : `${Math.floor(m / 60)} h ${m % 60} min`;
+                };
+                const lines = [
+                    `Last ${days} day${days === 1 ? '' : 's'} (${String(s.since).slice(0, 10)} to ${String(s.until).slice(0, 10)}):`,
+                    `- sandbox time: ${min(s.sandbox_seconds)} in ${s.sandbox_sessions} session${s.sandbox_sessions === 1 ? '' : 's'}`,
+                    `- runs: ${s.runs}${s.runs_failed ? ` (${s.runs_failed} failed)` : ''}${s.runs_denied ? ` (${s.runs_denied} denied)` : ''}`,
+                    `- routine firings: ${s.firings}${s.firings_failed ? ` (${s.firings_failed} failed)` : ''}; routines active: ${s.routines_active}${s.routines_failing ? `, failing now: ${s.routines_failing}` : ''}${s.routines_paused_self ? `, paused themselves: ${s.routines_paused_self}` : ''}`,
+                    `- connection uses: ${s.connection_uses}${s.connection_refused ? ` (${s.connection_refused} refused)` : ''} across ${s.connections} connection${s.connections === 1 ? '' : 's'}`,
+                    `- files published: ${s.files_published}`,
+                    typeof s.budget_seconds === 'number' ? `- daily sandbox budget: ${min(s.budget_seconds)}${s.budget_hit ? ' — reached in this window' : ' — not reached'}` : '- daily sandbox budget: none',
+                ];
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            case 'grupr_workspace_download': {
+                const r = await hubJSON('/workspace/download', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        url: String(args.url),
+                        path: typeof args.path === 'string' && args.path ? args.path : undefined,
+                        connection: typeof args.connection === 'string' && args.connection ? args.connection : undefined,
+                    }),
+                });
+                const via = r.connection ? ` via connection ${r.connection}` : '';
+                const head = r.ok
+                    ? `Fetched ${r.url}${via}: HTTP ${r.status}, ${r.bytes ?? 0} bytes in ${r.ms ?? 0} ms`
+                    : `Fetched ${r.url}${via}: HTTP ${r.status}${r.error ? ` (${r.error})` : ''}`;
+                return { content: [{ type: 'text', text: `${head}. Body at ${r.path}; details in ${r.meta_path}.${r.truncated ? ' The body was cut at 5 MB.' : ''}` }] };
+            }
+            case 'grupr_workspace_connection_request': {
+                const res = await hubFetch('/workspace/connections/request', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        name: String(args.name),
+                        host: String(args.host),
+                        auth_type: String(args.auth_type),
+                        header_name: typeof args.header_name === 'string' ? args.header_name : undefined,
+                        reason: typeof args.reason === 'string' ? args.reason : undefined,
+                        grupr_id: typeof args.grupr_id === 'string' && args.grupr_id ? args.grupr_id : undefined,
+                        plan: typeof args.then_recipe === 'string' && args.then_recipe
+                            ? { recipe: args.then_recipe, params: args.then_params && typeof args.then_params === 'object' ? args.then_params : {} }
+                            : undefined,
+                    }),
+                });
+                const text = await res.text();
+                let body = null;
+                try {
+                    body = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    body = null;
+                }
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code ?? 'error', e?.message ?? `HTTP ${res.status}`);
+                }
+                const r = body?.data ?? {};
+                return { content: [{ type: 'text', text: `${body?.meta?.created ? 'Asked' : 'Already asked'} for connection ${r.name} to ${r.host} (${r.auth_type}).${r.plan ? ` Plan: ${r.plan.summary ?? r.plan.recipe}.` : ''} ${body?.meta?.note ?? ''}`.trim() }] };
+            }
+            case 'grupr_workspace_connections': {
+                const res = await hubFetch('/workspace/connections');
+                const text = await res.text();
+                let body = null;
+                try {
+                    body = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    body = null;
+                }
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code ?? 'error', e?.message ?? `HTTP ${res.status}`);
+                }
+                const list = Array.isArray(body?.data) ? body.data : [];
+                const pending = Array.isArray(body?.meta?.pending_requests) ? body.meta.pending_requests : [];
+                const asked = pending.length ? `\nAsked for, waiting for the owner: ${pending.map((p) => `${p.name} → ${p.host}${p.plan ? ` (then ${p.plan.summary ?? p.plan.recipe})` : ''}`).join('; ')}` : '';
+                if (list.length === 0) {
+                    return { content: [{ type: 'text', text: 'This agent has no connections. The owner adds them on the agent page (Connections); grupr_workspace_connection_request asks for one.' + asked }] };
+                }
+                const lines = list.map((c) => `- ${c.name} → ${c.host} (${c.auth_type}${c.agent_access ? ', agent may use' : ', routines only'})${c.note ? ` — ${c.note}` : ''}` +
+                    (c.auth_failures ? ` ⚠ refused ${c.auth_failures}× in a row (HTTP ${c.last_status}); the owner needs to rotate it` : ''));
+                return { content: [{ type: 'text', text: `Connections (values are never shown):\n${lines.join('\n')}${asked}` }] };
+            }
+            case 'grupr_workspace_schedule': {
+                const res = await hubFetch('/workspace/schedule', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        grupr_id: String(args.grupr_id),
+                        cmd: String(args.cmd),
+                        cron: String(args.cron),
+                        timezone: typeof args.timezone === 'string' && args.timezone ? args.timezone : undefined,
+                        label: typeof args.label === 'string' && args.label ? args.label : undefined,
+                        cwd: typeof args.cwd === 'string' && args.cwd ? args.cwd : undefined,
+                        timeout_seconds: typeof args.timeout_seconds === 'number' ? args.timeout_seconds : undefined,
+                        outputs: Array.isArray(args.outputs) ? args.outputs : undefined,
+                        inputs: Array.isArray(args.inputs) ? args.inputs : undefined,
+                        render: typeof args.render === 'boolean' ? args.render : undefined,
+                        notify: typeof args.notify === 'string' ? args.notify : undefined,
+                    }),
+                });
+                const text = await res.text();
+                let body = null;
+                try {
+                    body = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    body = null;
+                }
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code ?? 'error', e?.message ?? `HTTP ${res.status}`);
+                }
+                const d = body?.data ?? {};
+                if (res.status === 202 || d.status === 'pending') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Routine proposed — approval ${d.approval_id ?? '?'} is waiting for a member. Do not re-submit. ` +
+                                    'When someone approves, the routine is created and the room is told; if they deny, nothing is scheduled.',
+                            },
+                        ],
+                    };
+                }
+                const sch = d.schedule ?? d;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Routine created (a standing rule allowed it): schedule_id ${sch.schedule_id ?? '?'}, ${sch.cron ?? ''} ${sch.timezone ?? ''}, next run ${sch.next_run_at ?? '?'}.`,
+                        },
+                    ],
                 };
             }
+            case 'grupr_workspace_schedules': {
+                const list = await hubJSON('/workspace/schedules');
+                if (!Array.isArray(list) || list.length === 0) {
+                    return { content: [{ type: 'text', text: 'No routines. Propose one with grupr_workspace_schedule.' }] };
+                }
+                const lines = list.map((r) => `- ${r.schedule_id} · ${r.label ? `${r.label}: ` : ''}\`${r.cmd}\` · ${r.cron} ${r.timezone} · room ${r.grupr_id} · ` +
+                    `${r.enabled ? 'on' : 'paused'} · next ${r.next_run_at ?? '—'} · last ${r.last_run_at ? `${r.last_run_at} (${r.last_status}${typeof r.last_exit_code === 'number' ? `, exit ${r.last_exit_code}` : ''})` : 'never'} · ` +
+                    `${r.runs ?? 0} runs, ${r.failures ?? 0} failed` +
+                    (Array.isArray(r.outputs) && r.outputs.length > 0
+                        ? ` · publishes ${r.outputs.map((o) => o.name || o.path).join(', ')}${r.render ? ' (rendered)' : ''}`
+                        : '') +
+                    (r.notify === 'failures' ? ' · posts failures only' : r.notify === 'output' ? ' · posts when it prints or fails' : '') +
+                    (typeof r.consecutive_failures === 'number' && r.consecutive_failures > 0 ? ` · FAILING: ${r.consecutive_failures} in a row` : '') +
+                    (r.auto_paused_at ? ' · paused itself after repeated failures (owner must Resume)' : ''));
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            case 'grupr_workspace_unschedule': {
+                await hubJSON(`/workspace/schedules/${encodeURIComponent(String(args.schedule_id))}`, { method: 'DELETE' });
+                return { content: [{ type: 'text', text: 'Routine removed; the room has been told.' }] };
+            }
+            case 'grupr_workspace_schedule_runs': {
+                const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), 100) : 10;
+                const list = await hubJSON(`/workspace/schedules/${encodeURIComponent(String(args.schedule_id))}/runs?limit=${limit}`);
+                if (!Array.isArray(list) || list.length === 0) {
+                    return { content: [{ type: 'text', text: 'No firings recorded for this routine yet.' }] };
+                }
+                const lines = list.map((r) => {
+                    const pub = Array.isArray(r.published) ? r.published : [];
+                    const ins = Array.isArray(r.inputs) ? r.inputs : [];
+                    const out = [r.stdout, r.stderr, r.error].filter((x) => typeof x === 'string' && x).join('\n').trim();
+                    const first = out.split('\n').find((l) => l.trim()) ?? '';
+                    return (`- ${r.finished_at ?? r.created_at} · ${r.status}${typeof r.exit_code === 'number' ? ` exit ${r.exit_code}` : ''}` +
+                        (typeof r.wall_clock_ms === 'number' ? ` · ${r.wall_clock_ms} ms` : '') +
+                        (ins.length ? ` · fetched ${ins.map((i) => `${i.ok ? 'ok' : 'FAILED'}${i.status ? ` ${i.status}` : ''} ${i.url}${i.connection ? ` via ${i.connection}` : ''}${i.error ? ` (${i.error})` : ''}`).join('; ')}` : '') +
+                        (pub.length ? ` · published ${pub.map((p) => (p.error ? `${p.name} FAILED (${p.error})` : `${p.name}${p.unchanged ? ' (unchanged)' : ''}`)).join(', ')}` : '') +
+                        (first ? ` · ${first.slice(0, 160)}` : ' · no output') +
+                        ` · run_id ${r.run_id}`);
+                });
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            case 'grupr_workspace_recipes': {
+                const list = await hubJSON('/workspace/recipes');
+                if (!Array.isArray(list) || list.length === 0) {
+                    return { content: [{ type: 'text', text: 'This server offers no recipes.' }] };
+                }
+                const lines = list.map((r) => {
+                    const params = Array.isArray(r.params) ? r.params : [];
+                    const outs = Array.isArray(r.outputs) ? r.outputs : [];
+                    return (`- ${r.id}: ${r.title} (${r.every}). ${r.summary}` +
+                        (params.length ? ` Parameters: ${params.map((p) => `${p.key} (${p.label}${p.options?.length ? `; one of ${p.options.join(', ')}` : ''}${p.optional ? '; optional' : ''}${p.help ? `; ${p.help}` : ''})`).join(', ')}.` : ' No parameters.') +
+                        (outs.length ? ` Publishes ${outs.map((o) => o.name || o.path).join(', ')}.` : ''));
+                });
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            case 'grupr_workspace_recipe': {
+                const res = await hubFetch('/workspace/recipe', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        recipe_id: String(args.recipe_id),
+                        grupr_id: String(args.grupr_id),
+                        params: args.params && typeof args.params === 'object' ? args.params : undefined,
+                        timezone: typeof args.timezone === 'string' && args.timezone ? args.timezone : undefined,
+                        cron: typeof args.cron === 'string' && args.cron ? args.cron : undefined,
+                    }),
+                });
+                const text = await res.text();
+                let body = null;
+                try {
+                    body = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    body = null;
+                }
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code ?? 'error', e?.message ?? `HTTP ${res.status}`);
+                }
+                const d = body?.data ?? {};
+                if (d.status === 'awaiting_connection') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No connection named ${d.connection ?? '?'} yet: the owner has been asked for one (to ${d.host ?? '?'}; request ${d.request_id ?? '?'}) with this recipe as the plan. ` +
+                                    'When they add the value and say yes, the routine is installed and the room is told. Do not re-submit; grupr_workspace_connections shows when it is ready.',
+                            },
+                        ],
+                    };
+                }
+                if (res.status === 202 || d.status === 'pending') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Recipe requested: approval ${d.approval_id ?? '?'} is waiting for a member. Do not re-submit. ` +
+                                    'When someone approves, the script is installed, the routine is created and the room is told; if they deny, nothing is installed.',
+                            },
+                        ],
+                    };
+                }
+                const sch = d.schedule ?? d;
+                return {
+                    content: [{ type: 'text', text: `Recipe installed (a standing rule allowed it): schedule_id ${sch.schedule_id ?? '?'}, ${sch.cron ?? ''} ${sch.timezone ?? ''}, next run ${sch.next_run_at ?? '?'}.` }],
+                };
+            }
+            case 'grupr_room_doc_write': {
+                const gid = encodeURIComponent(String(args.grupr_id));
+                const r = await hubJSON(`/grups/${gid}/documents`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        name: typeof args.name === 'string' ? args.name : undefined,
+                        title: typeof args.title === 'string' ? args.title : undefined,
+                        markdown: String(args.markdown ?? ''),
+                        formats: Array.isArray(args.formats) ? args.formats : undefined,
+                    }),
+                });
+                const files = (r.files ?? []).map((f) => `${f.name} (${f.size} B, v${f.version}, ${f.file_id})`).join('; ');
+                return { content: [{ type: 'text', text: `Wrote ${r.base ?? '?'} to the room's Files: ${files}.` }] };
+            }
+            case 'grupr_room_sheet_write': {
+                const gid = encodeURIComponent(String(args.grupr_id));
+                const r = await hubJSON(`/grups/${gid}/sheets`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        name: typeof args.name === 'string' ? args.name : undefined,
+                        sheets: args.sheets,
+                        formats: Array.isArray(args.formats) ? args.formats : undefined,
+                    }),
+                });
+                const files = (r.files ?? []).map((f) => `${f.name} (${f.size} B, v${f.version}, ${f.file_id})`).join('; ');
+                return { content: [{ type: 'text', text: `Wrote ${r.base ?? '?'} to the room's Files: ${files}.` }] };
+            }
+            case 'grupr_mail_send': {
+                const res = await hubFetch('/mail/send', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        grupr_id: String(args.grupr_id),
+                        to: Array.isArray(args.to) ? args.to : [String(args.to ?? '')],
+                        cc: Array.isArray(args.cc) ? args.cc : undefined,
+                        subject: String(args.subject ?? ''),
+                        markdown: String(args.markdown ?? ''),
+                        attachments: Array.isArray(args.attachments) ? args.attachments : undefined,
+                        in_reply_to: typeof args.in_reply_to === 'string' && args.in_reply_to ? args.in_reply_to : undefined,
+                    }),
+                });
+                const body = await res.json().catch(() => null);
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code || 'error', e?.message || `HTTP ${res.status}`);
+                }
+                const d = body?.data ?? body;
+                if (res.status === 202 || d?.status === 'pending') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Mail ${d?.mail_id ?? '?'} is awaiting a human decision (approval ${d?.approval_id ?? '?'}). It sends the moment someone approves and the receipt is posted in the room. Do not re-send; check grupr_mail_status or watch the room.`,
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Mail ${d?.mail_id ?? '?'} ${d?.status ?? '?'}${d?.provider_id ? ` (provider id ${d.provider_id})` : ''}${d?.auto_approved ? ' — auto-approved by a standing rule' : ''}. To: ${(d?.to ?? []).join(', ')}. Subject: ${d?.subject ?? ''}.`,
+                        },
+                    ],
+                };
+            }
+            case 'grupr_mail_inbox': {
+                const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(100, Math.floor(args.limit)) : 10;
+                const res = await hubFetch(`/mail?direction=in&limit=${limit}`);
+                const body = await res.json().catch(() => null);
+                if (!res.ok) {
+                    const e = body?.errors?.[0];
+                    throw new HubError(res.status, e?.code || 'error', e?.message || `HTTP ${res.status}`);
+                }
+                const items = (body?.data ?? []).map((m) => ({
+                    mail_id: m.mail_id,
+                    from: m.from,
+                    subject: m.subject,
+                    received_at: m.sent_at || m.created_at,
+                    grupr_id: m.grupr_id,
+                    in_reply_to: m.in_reply_to,
+                    attachments: (m.attachments ?? []).map((a) => a.name),
+                }));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ address: body?.meta?.address || null, inbound_enabled: body?.meta?.inbound_enabled ?? null, mail: items }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'grupr_mail_read': {
+                const m = await hubJSON(`/mail/${encodeURIComponent(String(args.mail_id))}`);
+                return { content: [{ type: 'text', text: JSON.stringify(m, null, 2) }] };
+            }
+            case 'grupr_mail_status': {
+                const m = await hubJSON(`/mail/${encodeURIComponent(String(args.mail_id))}`);
+                return { content: [{ type: 'text', text: JSON.stringify(m, null, 2) }] };
+            }
+            case 'grupr_workspace_write': {
+                const p = String(args.path);
+                const res = await hubJSON(`/workspace/file?path=${encodeURIComponent(p)}`, {
+                    method: 'PUT',
+                    headers: { 'Content-Type': 'application/octet-stream' },
+                    body: String(args.content ?? ''),
+                });
+                return { content: [{ type: 'text', text: `Wrote ${res.size ?? '?'} bytes to ${res.path ?? p}.` }] };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
     }
     catch (err) {
+        if (err instanceof HubError) {
+            const hint = err.code === 'command_denied' || err.code === 'mail_denied'
+                ? ' The human said no — do not retry; explain in the room instead.'
+                : err.code === 'approval_timeout'
+                    ? ' Nobody decided in time and the request was cancelled. Ask in the room, then call again.'
+                    : err.status === 503
+                        ? ' Workspaces are not enabled on this Grupr server.'
+                        : '';
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Grupr ${err.status} ${err.code}: ${err.message}.${hint}${err.approvalId ? ` (approval ${err.approvalId})` : ''}`,
+                    },
+                ],
+            };
+        }
         if (err instanceof sdk_1.GruprAuthError) {
             return {
                 isError: true,