@bbigbang/channel-bridge 0.1.0

package/dist/index.js

@@ -0,0 +1,2065 @@
+#!/usr/bin/env node
+/**
+ * channel-bridge — MCP server for bigbang agents.
+ *
+ * Mirrors Slock's chat-bridge.js: exposes send_message, check_messages,
+ * list_server, read_history, and task board tools over MCP stdio transport.
+ * The tools call bigbang's internal agent API (/api/internal/agent/:id/*).
+ *
+ * Usage:
+ *   channel-bridge --agent-id <id> --server-url <url> [--auth-token <token>]
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { buildCachedAssetFilePath, findCachedAssetFile, readCachedAssetMetadata, resolveConversationAssetCacheRoot, writeCachedAssetMetadata, } from './assetCache.js';
+import { formatBeijingPromptTimestamp, formatHistoryMessages, formatMessages } from './messageFormat.js';
+import { buildCompactRuntimePresenceData, buildCompactSelfStateData, formatConversationListText, formatConversationSummaryToolText, formatRuntimePresenceToolText, formatSendMessageDiagnostics, formatSelfStateToolText, formatToolResult, } from './surfaceFormats.js';
+import { buildCompactWorkspaceInspectData, formatWorkspaceFileToolText, formatWorkspaceInspectToolText, formatWorkspaceTreeToolText } from './workspaceFormats.js';
+import { formatContextBundleToolText } from './contextBundleFormat.js';
+import { formatTaskUpdateDeliveriesSection, formatTaskUpdateDeliveryText } from './taskUpdateFormat.js';
+import { buildInlineTextPreview } from './textPreview.js';
+import { formatComponentRegistry, formatPanelState, formatPanelRows, formatPanelEvents, formatPanelCollaborators, formatRenderPanelSuccess, formatRenderPanelError, formatUpsertPanelError, formatPatchPanelSuccess, formatPatchPanelError, } from './panelFormat.js';
+// ─── CLI args ─────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+let agentId = '';
+let conversationId = '';
+let runId = '';
+let runContextPath = '';
+let serverUrl = 'http://localhost:3100';
+let authToken = process.env.CHANNEL_BRIDGE_AUTH_TOKEN ?? '';
+let workspacePath = '';
+let assetCacheRootArg = '';
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--agent-id' && args[i + 1])
+        agentId = args[++i];
+    if (args[i] === '--conversation-id' && args[i + 1])
+        conversationId = args[++i];
+    if (args[i] === '--run-id' && args[i + 1])
+        runId = args[++i];
+    if (args[i] === '--run-context-path' && args[i + 1])
+        runContextPath = args[++i];
+    if (args[i] === '--server-url' && args[i + 1])
+        serverUrl = args[++i];
+    if (args[i] === '--auth-token' && args[i + 1])
+        authToken = args[++i];
+    if (args[i] === '--workspace-path' && args[i + 1])
+        workspacePath = args[++i];
+    if (args[i] === '--asset-cache-root' && args[i + 1])
+        assetCacheRootArg = args[++i];
+}
+if (!agentId || !conversationId) {
+    console.error('[channel-bridge] Missing --agent-id or --conversation-id');
+    process.exit(1);
+}
+const panelActionParamFieldSchema = z.object({
+    name: z.string().trim().min(1),
+    label: z.string().trim().min(1).optional(),
+    description: z.string().trim().min(1).optional(),
+    input: z.enum(['text', 'number', 'checkbox', 'select']).optional(),
+    required: z.boolean().optional(),
+    placeholder: z.string().optional(),
+    defaultValue: z.unknown().optional(),
+    min: z.number().finite().optional(),
+    max: z.number().finite().optional(),
+    options: z.array(z.object({
+        label: z.string().trim().min(1),
+        value: z.string().trim().min(1),
+    })).optional(),
+});
+const panelActionSchema = z.object({
+    id: z.string().trim().min(1),
+    label: z.string().trim().min(1),
+    mode: z.enum(['notify_agent', 'platform_exec']).optional().describe('Optional action mode. Omit for legacy defaults: command or legacy rpcCommand means platform_exec, otherwise notify_agent.'),
+    toolKind: z.enum(['start', 'stop', 'status', 'restart', 'custom']).optional().describe('Promotion hint only: when this panel is upgraded to a Workspace Tool, map the action to this tool action kind. Ignored by ordinary panel action execution.'),
+    variant: z.enum(['primary', 'secondary', 'danger']).optional(),
+    description: z.string().optional(),
+    command: z.string().optional().describe('Required for mode="platform_exec" while the panel is used directly, except commandless toolKind="stop" is allowed as a promotion hint.'),
+    cwd: z.string().optional().describe('Optional workspace-relative cwd for command.'),
+    persistent: z.boolean().optional().describe('Promotion hint copied to Workspace Tool actions; persistent true defaults direct promotion to toolKind="start" when toolKind is omitted.'),
+    maxRunSeconds: z.number().int().positive().optional().describe('Promotion hint copied to Workspace Tool persistent start/restart actions.'),
+    idleTimeoutSeconds: z.number().int().positive().optional().describe('Promotion hint copied to Workspace Tool persistent start/restart actions.'),
+    paramsSchema: z.array(panelActionParamFieldSchema).optional().describe('Promotion hint copied to Workspace Tool actions. Ordinary panel action execution does not prompt for these parameters; the Tools surface does after upgrade.'),
+    rpcCommand: z.string().optional().describe('Deprecated legacy alias for command; accepted for compatibility.'),
+    rpcCwd: z.string().optional().describe('Deprecated legacy alias for cwd; accepted for compatibility.'),
+});
+void workspacePath;
+// ─── HTTP helpers ─────────────────────────────────────────────────────────────
+const commonHeaders = { 'Content-Type': 'application/json' };
+if (authToken)
+    commonHeaders['Authorization'] = `Bearer ${authToken}`;
+commonHeaders['X-Bigbang-Agent-Surface'] = 'mcp';
+const MIME_BY_EXTENSION = {
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp',
+    '.txt': 'text/plain', '.md': 'text/markdown', '.log': 'text/plain',
+    '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml',
+    '.xml': 'application/xml', '.csv': 'text/csv',
+    '.js': 'text/javascript', '.mjs': 'text/javascript', '.ts': 'text/typescript', '.tsx': 'text/typescript',
+    '.jsx': 'text/javascript', '.py': 'text/x-python', '.sh': 'text/x-shellscript',
+    '.css': 'text/css', '.html': 'text/html', '.sql': 'text/plain',
+};
+const base = `${serverUrl}/api/internal/agent/${agentId}`;
+function currentRunId() {
+    if (runContextPath) {
+        try {
+            const parsed = JSON.parse(readFileSync(runContextPath, 'utf8'));
+            const candidate = typeof parsed.runId === 'string' ? parsed.runId.trim() : '';
+            if (candidate)
+                return candidate;
+        }
+        catch {
+            // The bridge may start before the first prompt writes run context.
+        }
+    }
+    return runId || undefined;
+}
+async function apiFetch(path, options) {
+    const res = await fetch(`${base}${path}`, {
+        method: options?.method ?? 'GET',
+        headers: commonHeaders,
+        body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+    const data = await res.json().catch(() => ({}));
+    return { ok: res.ok, status: res.status, data };
+}
+function errText(data, fallback) {
+    if (data && typeof data === 'object') {
+        const record = data;
+        if (typeof record.error_code === 'string') {
+            return `${String(record.error ?? fallback)}\n\nStructured error:\n${JSON.stringify({
+                error_code: record.error_code,
+                required_action: record.required_action ?? null,
+                source_target: record.source_target ?? null,
+                requested_target: record.requested_target ?? null,
+            }, null, 2)}`;
+        }
+        if ('error' in record)
+            return String(record.error);
+    }
+    return fallback;
+}
+function toText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function formatTaskIdentity(agentTaskRef, taskNumber) {
+    if (agentTaskRef && taskNumber != null)
+        return `${agentTaskRef} · #t${taskNumber}`;
+    if (agentTaskRef)
+        return agentTaskRef;
+    if (taskNumber != null)
+        return `#t${taskNumber}`;
+    return 'task';
+}
+function normalizeMessageIdForThreadShortId(messageId) {
+    const trimmed = messageId.trim().toLowerCase();
+    const withoutClientPrefix = trimmed.startsWith('client-') ? trimmed.slice('client-'.length) : trimmed;
+    const normalized = withoutClientPrefix.replace(/[^a-z0-9]/g, '');
+    return normalized || trimmed.replace(/[^a-z0-9]/g, '');
+}
+function buildThreadShortId(messageId) {
+    return normalizeMessageIdForThreadShortId(messageId).slice(0, 16);
+}
+function isThreadTarget(target) {
+    if (target.startsWith('dm:@'))
+        return target.split(':').length >= 3;
+    if (target.startsWith('#'))
+        return target.includes(':');
+    return false;
+}
+function buildThreadTarget(target, messageId) {
+    if (!target || !messageId)
+        return null;
+    const normalizedTarget = target.trim();
+    if (!(normalizedTarget.startsWith('dm:@') || normalizedTarget.startsWith('#')))
+        return null;
+    if (isThreadTarget(normalizedTarget))
+        return normalizedTarget;
+    return `${normalizedTarget}:${buildThreadShortId(messageId)}`;
+}
+// ─── MCP server ───────────────────────────────────────────────────────────────
+const server = new McpServer({ name: 'chat', version: '1.0.0' });
+// ── send_message ──────────────────────────────────────────────────────────────
+server.tool('send_message', 'Send a visible message to the current conversation by default. Do not call this tool when you have no user-visible or peer-visible value to add. You may optionally override the target only when replying on this same surface\'s exact target. Do not use target override to move work to another DM, channel, or thread of the same agent; use handoff_to_target first. Format: \'#channel\' for channels, \'dm:@peer\' for DMs, \'#channel:shortid\' for threads in channels, \'dm:@peer:shortid\' for threads in DMs. To start a NEW DM, use \'dm:@person-name\'.', {
+    target: z.string().optional().describe('Optional override for where to send. If omitted, the message replies to the current conversation. Use this only when staying on the same surface\'s exact target after normalization. To move work to another same-agent surface, use handoff_to_target instead. Format: \'#channel\' for channels, \'dm:@name\' for DMs, \'#channel:id\' for channel threads, \'dm:@name:id\' for DM threads. Examples: \'#general\', \'dm:@alice\', \'#general:abcd1234ef567890\'.'),
+    content: z
+        .string()
+        .trim()
+        .min(1, 'content must not be empty')
+        .describe('The message content. Must not be empty or whitespace-only.'),
+    kind: z
+        .enum(['progress', 'final'])
+        .optional()
+        .describe('Optional message kind. Use "progress" for interim updates and "final" for the final user-visible answer that completes this run. If omitted, the platform treats the message as a legacy untyped reply.'),
+    peer_delivery: z
+        .enum(['silent', 'batch', 'immediate'])
+        .optional()
+        .describe('Optional peer notification delivery for shared channel/thread updates only; do not set this in DMs. Omit this for coordination-relevant updates so peers receive the default "batch" peer inbox delivery. Use "silent" only for visible no-action status, local bookkeeping, duplicate presence, or waiting updates that should not ordinary-notify peers. If unsure, omit this field. Use "immediate" only when collaborators must see this update now; explicit @mentions are already immediate and override silent.'),
+    attachment_ids: z.array(z.string()).optional().describe('Optional attachment IDs to include'),
+    panel_ids: z.array(z.string()).optional().describe('Optional panel IDs to include with the message. Panels are interactive UI components rendered in the chat. Use render_panel(...) to create a panel, then pass its panel_id here.'),
+    tool_ids: z.array(z.string()).optional().describe('Optional Workspace Tool IDs to include with the message. After publish_workspace_tool returns a tool_id, pass it here so the tool is attached to the visible chat bubble.'),
+}, async ({ target, content, kind, peer_delivery, attachment_ids, panel_ids, tool_ids }) => {
+    const normalizedContent = content.trim();
+    if (!normalizedContent) {
+        throw new Error('content must not be empty');
+    }
+    const { ok, data } = await apiFetch('/send', {
+        method: 'POST',
+        body: {
+            target,
+            content: normalizedContent,
+            kind,
+            peer_delivery,
+            conversationId,
+            runId: currentRunId(),
+            attachmentIds: attachment_ids,
+            panelIds: panel_ids,
+            toolIds: tool_ids,
+        },
+    });
+    if (!ok) {
+        throw new Error(errText(data, 'send failed'));
+    }
+    const d = data;
+    if (d.suppressed === true) {
+        const message = typeof d.message === 'string' && d.message.trim()
+            ? d.message.trim()
+            : 'Message suppressed by platform policy.';
+        return toText(message);
+    }
+    if (d.held === true && d.stale === true) {
+        const message = typeof d.message === 'string' && d.message.trim()
+            ? d.message.trim()
+            : 'Your draft was not sent because newer messages exist on this surface.';
+        const readHistory = typeof d.readHistory === 'string' && d.readHistory.trim()
+            ? d.readHistory.trim()
+            : 'read_history(...)';
+        const blockedSeqRange = typeof d.blockedSeqRange === 'string' && d.blockedSeqRange.trim()
+            ? d.blockedSeqRange.trim()
+            : 'unknown';
+        const latestMessages = Array.isArray(d.latestMessages)
+            ? d.latestMessages
+                .map((item) => item && typeof item === 'object' ? item : null)
+                .filter((item) => item !== null)
+                .map((item) => {
+                const sender = typeof item.senderName === 'string' ? item.senderName : String(item.senderId ?? 'unknown');
+                const seq = typeof item.seq === 'number' ? item.seq : String(item.seq ?? '?');
+                const content = typeof item.content === 'string' ? item.content : '';
+                return `seq=${seq} ${sender}: ${content}`;
+            })
+                .join('\n')
+            : '';
+        const latestSection = latestMessages ? `\n\nLatest messages:\n${latestMessages}` : '';
+        return toText(`${message}\n\nDraft held; nothing was posted. Newer seq range: ${blockedSeqRange}.${latestSection}\n\nNext: ${readHistory}, then decide whether to send a revised message or stop.`);
+    }
+    const msgId = String(d.messageId ?? '');
+    if (!msgId.trim()) {
+        throw new Error('send_message returned success without a messageId. Nothing was confirmed posted; read_history(...) before deciding whether to retry.');
+    }
+    const deliveredTarget = String(d.target ?? target ?? 'current conversation');
+    const threadTarget = buildThreadTarget(deliveredTarget, msgId);
+    const replyHint = threadTarget
+        ? ` (to reply in this message's thread, use target "${threadTarget}")`
+        : '';
+    const notificationNote = typeof d.notificationNote === 'string' && d.notificationNote.trim()
+        ? `\n\nNotification note: ${d.notificationNote.trim()}`
+        : '';
+    const diagnosticsNote = formatSendMessageDiagnostics(d);
+    return toText(`Message sent to ${deliveredTarget}. Message ID: ${msgId}${replyHint}${notificationNote}${diagnosticsNote}`);
+});
+// ── check_messages ────────────────────────────────────────────────────────────
+server.tool('check_messages', "Check for new messages without waiting. Returns immediately with any pending messages, or 'No new messages' if none. Use this freely during work — at natural breakpoints or whenever you want to see if anything new came in. Optionally filter to a specific channel or DM.", {
+    channel: z.string().optional().describe("Optional: filter to a specific channel or DM (e.g. '#general', 'dm:@alice'). Omit to check all channels."),
+}, async ({ channel }) => {
+    try {
+        const params = new URLSearchParams();
+        if (channel)
+            params.set('channel', channel);
+        params.set('conversationId', conversationId);
+        const activeRunId = currentRunId();
+        if (activeRunId)
+            params.set('runId', activeRunId);
+        const qs = `?${params.toString()}`;
+        const { ok, data } = await apiFetch(`/receive${qs}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'receive failed')}`);
+        const d = data;
+        if (d.messages && d.messages.length > 0) {
+            const formatted = formatMessages(d.messages);
+            return toText(formatted +
+                '\n\n--- IMPORTANT: The [Message metadata] block is system metadata for routing and context. Do NOT quote or repeat it back to the user. Reply using mcp__chat__send_message(content="...") for the current conversation. Do not use send_message(target=...) to move work to another same-agent surface; use handoff_to_target first. Do NOT output text directly. ---');
+        }
+        return toText('No new messages.');
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── list_server ───────────────────────────────────────────────────────────────
+server.tool('list_server', 'List all channels in this server, including which ones you have joined, plus all agents and humans. Use this to discover who and where you can message.', {}, async () => {
+    try {
+        const { ok, data } = await apiFetch('/server');
+        if (!ok)
+            return toText(`Error: ${errText(data, 'server list failed')}`);
+        const d = data;
+        let text = '## Server\n\n';
+        text += '### Channels\n';
+        text += "Use `#channel-name` with send_message to post in a channel. `joined` means you currently belong to that channel.\n";
+        if (d.channels?.length) {
+            for (const ch of d.channels) {
+                const status = ch.joined ? 'joined' : 'not joined';
+                text += ch.description
+                    ? `  - #${ch.name} [${status}] — ${ch.description}\n`
+                    : `  - #${ch.name} [${status}]\n`;
+            }
+        }
+        else {
+            text += '  (none)\n';
+        }
+        text += '\n### Agents\n';
+        text += 'Other AI agents in this server.\n';
+        if (d.agents?.length) {
+            for (const a of d.agents)
+                text += `  - @${a.name} (${a.status})\n`;
+        }
+        else {
+            text += '  (none)\n';
+        }
+        text += '\n### Humans\n';
+        text += 'To start a new DM: send_message(target="dm:@name"). To reply in an existing DM: reuse the target from received messages.\n';
+        if (d.humans?.length) {
+            for (const u of d.humans)
+                text += `  - @${u.name}\n`;
+        }
+        else {
+            text += '  (none)\n';
+        }
+        return toText(text);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── get_self_state ───────────────────────────────────────────────────────────
+server.tool('get_self_state', 'Return your global work overview across DM/channel/thread surfaces: current surface, other active surfaces, unread/queued work, recent tasks, and recent handoffs.', {
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. Prefer text. json/both return a compact structured summary, not the full raw state dump.'),
+}, async ({ format }) => {
+    try {
+        const params = new URLSearchParams();
+        params.set('conversationId', conversationId);
+        const { ok, data } = await apiFetch(`/self-state?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'self-state fetch failed')}`);
+        const d = data;
+        return toText(formatToolResult(format, formatSelfStateToolText(d), buildCompactSelfStateData(d)));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── get_runtime_presence ─────────────────────────────────────────────────────
+server.tool('get_runtime_presence', 'Return node / host / runtime facts for this agent, including current host state, node online/offline status, runtime drivers, and capability inventory.', {
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. Prefer text. json/both return a compact structured summary.'),
+}, async ({ format }) => {
+    try {
+        const params = new URLSearchParams();
+        params.set('conversationId', conversationId);
+        const { ok, data } = await apiFetch(`/runtime-presence?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'runtime-presence fetch failed')}`);
+        return toText(formatToolResult(format, formatRuntimePresenceToolText(data), buildCompactRuntimePresenceData(data)));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── inspect_workspace ───────────────────────────────────────────────────────
+server.tool('inspect_workspace', 'Inspect the current agent workspace root. Returns git / directory facts for the current workspace only.', {
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. Prefer text. json/both return structured inspect data.'),
+}, async ({ format }) => {
+    try {
+        const { ok, data } = await apiFetch('/workspace-inspect');
+        if (!ok)
+            return toText(`Error: ${errText(data, 'workspace inspect failed')}`);
+        const d = data;
+        return toText(formatToolResult(format, formatWorkspaceInspectToolText(d), buildCompactWorkspaceInspectData(d)));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── list_workspace_tree ─────────────────────────────────────────────────────
+server.tool('list_workspace_tree', 'List directory entries from the current agent workspace. This is read-only and scoped to the current workspace root.', {
+    path: z.string().optional().describe('Optional relative directory path inside the current workspace. Defaults to the workspace root.'),
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. Prefer text. json/both return the structured tree result.'),
+}, async ({ path, format }) => {
+    try {
+        const params = new URLSearchParams();
+        if (path?.trim())
+            params.set('path', path.trim());
+        const qs = params.toString();
+        const { ok, data } = await apiFetch(`/workspace-tree${qs ? `?${qs}` : ''}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'workspace tree fetch failed')}`);
+        const d = data;
+        return toText(formatToolResult(format, formatWorkspaceTreeToolText(d), d));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── read_workspace_file ─────────────────────────────────────────────────────
+server.tool('read_workspace_file', 'Read a text file from the current agent workspace. This is read-only and scoped to the current workspace root.', {
+    path: z.string().trim().min(1, 'path is required').describe('Relative file path inside the current workspace.'),
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. text returns the content with a short header, json returns the structured payload, both returns both.'),
+}, async ({ path, format }) => {
+    try {
+        const params = new URLSearchParams();
+        params.set('path', path.trim());
+        const { ok, data } = await apiFetch(`/workspace-file?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'workspace file fetch failed')}`);
+        const d = data;
+        return toText(formatToolResult(format, formatWorkspaceFileToolText(d), d));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── list_my_conversations ────────────────────────────────────────────────────
+server.tool('list_my_conversations', 'Bulk-discover your known DM/channel/thread work surfaces with current status, unread count, queued prompts, and a compact structured summary.', {
+    status: z
+        .enum(['all', 'idle', 'queued', 'active', 'recovering', 'awaiting_approval', 'failed'])
+        .default('all')
+        .describe('Optional status filter (default: all)'),
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. text returns a concise report, json returns the full structured payload, both returns both.'),
+}, async ({ status, format }) => {
+    try {
+        const params = new URLSearchParams();
+        if (status !== 'all')
+            params.set('status', status);
+        const { ok, data } = await apiFetch(`/my-conversations?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'my-conversations fetch failed')}`);
+        const d = data;
+        if (!d.conversations?.length) {
+            return toText(`No${status !== 'all' ? ` ${status}` : ''} conversations found.`);
+        }
+        return toText(formatToolResult(format, formatConversationListText(d.conversations), data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── get_conversation_summary ────────────────────────────────────────────────
+server.tool('get_conversation_summary', 'Return one-surface detail for a known work surface. Query by target such as "dm:@oldpan" or "#channel:threadid", or by conversation_id if you already know it.', {
+    target: z.string().optional().describe('Optional target to summarize, for example "dm:@oldpan" or "#all:abcd1234".'),
+    conversation_id: z.string().optional().describe('Optional conversation ID to summarize.'),
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. text returns a concise report, json returns the full structured payload, both returns both.'),
+}, async ({ target, conversation_id, format }) => {
+    try {
+        if (!target?.trim() && !conversation_id?.trim()) {
+            return toText('Error: target or conversation_id is required');
+        }
+        const params = new URLSearchParams();
+        if (target?.trim())
+            params.set('target', target.trim());
+        if (conversation_id?.trim())
+            params.set('conversation_id', conversation_id.trim());
+        const { ok, data } = await apiFetch(`/conversation-summary?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'conversation summary fetch failed')}`);
+        const d = data;
+        if (!d.conversation)
+            return toText('Error: conversation summary unavailable');
+        return toText(formatToolResult(format, formatConversationSummaryToolText(d.conversation), d.conversation));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── get_relevant_context_bundle ─────────────────────────────────────────────
+server.tool('get_relevant_context_bundle', 'Return a ranked shortlist of the most relevant neighboring surfaces, tasks, and handoffs for the current conversation. This is a narrowing tool, not the canonical state source.', {
+    max_surfaces: z.number().default(4).describe('Maximum number of related surfaces to include (default 4, max 8).'),
+    max_tasks: z.number().default(3).describe('Maximum number of related tasks to include (default 3, max 8).'),
+    max_handoffs: z.number().default(3).describe('Maximum number of related handoffs to include (default 3, max 8).'),
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. text returns a concise ranked bundle, json returns the structured payload, both returns both.'),
+}, async ({ max_surfaces, max_tasks, max_handoffs, format }) => {
+    try {
+        const { ok, data } = await apiFetch('/context-bundle', {
+            method: 'POST',
+            body: {
+                conversationId,
+                maxSurfaces: max_surfaces,
+                maxTasks: max_tasks,
+                maxHandoffs: max_handoffs,
+                format,
+            },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'context bundle fetch failed')}`);
+        const d = data;
+        if (!d.bundle)
+            return toText('Error: context bundle unavailable');
+        return toText(formatToolResult(format, formatContextBundleToolText(d.bundle), d.bundle));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── handoff_to_target ───────────────────────────────────────────────────────
+server.tool('handoff_to_target', 'Create a same-agent cross-surface handoff to another target such as a DM, channel root, or thread. Use continue_there to move detailed execution there, or delegate_only / collab to keep the current surface active.', {
+    target: z.string().trim().min(1).describe('Target surface to hand off to, for example "#proj", "#proj:abcd1234", "dm:@oldpan", or "dm:@oldpan:abcd1234".'),
+    mode: z.enum(['delegate_only', 'continue_there', 'collab']).default('delegate_only').describe('Handoff mode.'),
+    goal: z.string().trim().min(1).describe('Primary goal for the target surface.'),
+    why_now: z.string().optional().describe('Optional short explanation of why the handoff is happening now.'),
+    constraints: z.array(z.string()).optional().describe('Optional constraints for the work.'),
+    already_done: z.array(z.string()).optional().describe('Optional bullet list of work already completed.'),
+    expected_output: z.string().optional().describe('Optional expected output or done condition.'),
+    related_task_ref: z.string().optional().describe('Optional related task ref such as "task_xxx" or "#t12".'),
+    optional_refs: z.array(z.string()).optional().describe('Optional channels/DMs/tasks to consult if needed.'),
+}, async ({ target, mode, goal, why_now, constraints, already_done, expected_output, related_task_ref, optional_refs, }) => {
+    try {
+        const { ok, data } = await apiFetch('/handoff', {
+            method: 'POST',
+            body: {
+                conversationId,
+                target: target.trim(),
+                mode,
+                goal: goal.trim(),
+                context: {
+                    ...(why_now?.trim() ? { why_now: why_now.trim() } : {}),
+                    ...(constraints?.length ? { constraints } : {}),
+                    ...(already_done?.length ? { already_done } : {}),
+                    ...(expected_output?.trim() ? { expected_output: expected_output.trim() } : {}),
+                    ...(related_task_ref?.trim() ? { related_task_ref: related_task_ref.trim() } : {}),
+                    ...(optional_refs?.length ? { optional_refs } : {}),
+                },
+            },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'handoff failed')}`);
+        const d = data;
+        if (!d.handoff)
+            return toText('Error: handoff failed');
+        const statusLine = d.handoff.reportText?.trim()
+            || `${d.handoff.mode} [${d.handoff.status}] -> ${d.handoff.targetReplyTarget}`;
+        const queueLine = d.handoff.queued ? 'Target surface was queued.' : 'Target surface was dispatched immediately.';
+        const continueNote = d.handoff.mode === 'continue_there'
+            ? '\n\nDetailed execution should now continue on the target surface. End work on the current surface here.'
+            : '';
+        const cancelLine = d.handoff.cancelRequested
+            ? `\nSource run cancel requested (${d.handoff.cancelRunId ?? 'run id unavailable'}).`
+            : '';
+        const errorLine = d.handoff.error ? `\nError detail: ${d.handoff.error}` : '';
+        return toText(`Started handoff ${d.handoff.handoffId}.\n${statusLine}\n${queueLine}${cancelLine}${errorLine}${continueNote}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── read_history ──────────────────────────────────────────────────────────────
+server.tool('read_history', "Read message history for a channel, DM, or thread. Use the same target format: '#channel', 'dm:@name', '#channel:id' for threads. Supports pagination with 'before' / 'after' and centered context jumps with 'around' (messageId or seq).", {
+    channel: z.string().describe("The target to read history from — e.g. '#general', 'dm:@alice', '#general:abcd1234ef567890'"),
+    limit: z.number().default(50).describe('Max number of messages to return (default 50, max 100)'),
+    around: z.union([z.string(), z.number()]).optional().describe('Center the history window around a messageId prefix or seq in this exact target.'),
+    before: z.number().optional().describe('Return messages before this seq number (backward pagination).'),
+    after: z.number().optional().describe('Return messages after this seq number (catching up on unread).'),
+    include_root: z.boolean().optional().describe('When reading a thread target, optionally prepend the thread root message for context.'),
+}, async ({ channel, limit, around, before, after, include_root }) => {
+    try {
+        const params = new URLSearchParams();
+        params.set('channel', channel);
+        params.set('limit', String(Math.min(limit, 100)));
+        if (around !== undefined)
+            params.set('around', String(around));
+        if (before !== undefined)
+            params.set('before', String(before));
+        if (after !== undefined)
+            params.set('after', String(after));
+        if (include_root)
+            params.set('include_root', 'true');
+        params.set('conversationId', conversationId);
+        const activeRunId = currentRunId();
+        if (activeRunId)
+            params.set('runId', activeRunId);
+        const { ok, data } = await apiFetch(`/history?${params}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'history fetch failed')}`);
+        const d = data;
+        if (!d.messages?.length)
+            return toText('No messages in this channel.');
+        const formatted = formatHistoryMessages(d.messages);
+        let footer = '';
+        if (around !== undefined && d.messages.length > 0 && (d.has_older || d.has_newer)) {
+            const minSeq = d.messages[0].seq;
+            const maxSeq = d.messages[d.messages.length - 1].seq;
+            footer = `\n\n--- Context window shown. Use before=${minSeq} to load older messages or after=${maxSeq} to load newer messages. ---`;
+        }
+        else if (d.has_more && d.messages.length > 0) {
+            if (after !== undefined) {
+                const maxSeq = d.messages[d.messages.length - 1].seq;
+                footer = `\n\n--- ${d.messages.length} messages shown. Use after=${maxSeq} to load more recent messages. ---`;
+            }
+            else {
+                const minSeq = d.messages[0].seq;
+                footer = `\n\n--- ${d.messages.length} messages shown. Use before=${minSeq} to load older messages. ---`;
+            }
+        }
+        const aroundHeader = around !== undefined ? ` around ${String(around)}` : '';
+        return toText(`## Message History for ${channel}${aroundHeader} (${d.messages.length} messages)\n\n${formatted}\n\n--- IMPORTANT: The [Message metadata] block is system metadata for routing and context. Do NOT quote or repeat it back to the user. ---${footer}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('get_handoff_status', 'Look up one same-agent handoff by handoff_id and return its current status, source/target, and preserved context.', {
+    handoff_id: z.string().trim().min(1, 'handoff_id is required').describe('The handoff id returned by handoff_to_target.'),
+    format: z.enum(['text', 'json', 'both']).default('text').describe('Output format. text returns a concise report, json returns the full structured payload, both returns both.'),
+}, async ({ handoff_id, format }) => {
+    try {
+        const { ok, data } = await apiFetch(`/handoffs/${encodeURIComponent(handoff_id.trim())}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'handoff status lookup failed')}`);
+        const d = data;
+        if (!d.handoff)
+            return toText('Error: handoff not found');
+        const lines = [
+            `Handoff: ${d.handoff.handoffId}`,
+            `Status: ${d.handoff.status}`,
+            `Mode: ${d.handoff.mode}`,
+            `Target: ${d.handoff.targetReplyTarget}`,
+        ];
+        if (d.handoff.sourceReplyTarget)
+            lines.push(`Source: ${d.handoff.sourceReplyTarget}`);
+        if (d.handoff.reportText?.trim())
+            lines.push('', d.handoff.reportText.trim());
+        return toText(formatToolResult(format, lines.join('\n'), d.handoff));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── search_messages ──────────────────────────────────────────────────────────
+server.tool('search_messages', 'Search messages visible to this agent. Use this to find relevant older context, then inspect a hit with read_history(channel="<target>", around="<messageId>").', {
+    query: z.string().describe('Search query'),
+    channel: z.string().optional().describe("Optional target to scope the search, e.g. '#general', 'dm:@alice', '#general:abcd1234ef567890'"),
+    limit: z.number().default(10).describe('Max number of search results to return (default 10, max 20)'),
+}, async ({ query, channel, limit }) => {
+    try {
+        const trimmed = query.trim();
+        if (!trimmed)
+            return toText('Search query cannot be empty.');
+        const params = new URLSearchParams();
+        params.set('q', trimmed);
+        params.set('limit', String(Math.min(limit, 20)));
+        if (channel)
+            params.set('channel', channel);
+        const { ok, data } = await apiFetch(`/search?${params}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'search failed')}`);
+        const d = data;
+        if (!d.results?.length)
+            return toText('No search results.');
+        const formatted = d.results.map((result, index) => [
+            `[${index + 1}] msg=${result.id} seq=${result.seq} time=${formatBeijingPromptTimestamp(result.createdAt)}`,
+            `target: ${result.target}`,
+            `sender: @${result.senderName}${result.senderType === 'agent' ? ' (agent)' : ''}`,
+            `content: ${result.content}`,
+            `match: ${result.snippet}`,
+            `next: read_history(channel="${result.target}", around="${result.id}", limit=20)`,
+        ].join('\n')).join('\n\n');
+        return toText(`## Search Results for "${trimmed}" (${d.results.length} results)\n\n${formatted}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── list_tasks ────────────────────────────────────────────────────────────────
+server.tool('list_tasks', "List task-messages on a channel's board. Returns each task-message with its local board number (#t1, #t2...), stable global task ref, title, status, assignee, and message root when available.", {
+    channel: z.string().describe("The channel whose task board to view — e.g. '#general'"),
+    status: z
+        .enum(['all', 'todo', 'in_progress', 'in_review', 'done'])
+        .default('all')
+        .describe('Filter by status (default: all)'),
+}, async ({ channel, status }) => {
+    try {
+        const params = new URLSearchParams({ channel });
+        if (status !== 'all')
+            params.set('status', status);
+        const { ok, data } = await apiFetch(`/tasks?${params}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'list tasks failed')}`);
+        const d = data;
+        if (!d.tasks?.length) {
+            return toText(`No${status !== 'all' ? ` ${status}` : ''} tasks in ${channel}.`);
+        }
+        const formatted = d.tasks.map((t) => {
+            const assignee = t.claimedByName ? ` → @${t.claimedByName}` : '';
+            const creator = t.createdByName ? ` (by @${t.createdByName})` : '';
+            const msgShort = t.messageId ? t.messageId.slice(0, 8) : null;
+            const msgTag = msgShort ? `  msg=${msgShort}` : '';
+            const descLine = t.description
+                ? `\n  desc: ${t.description.length > 80 ? t.description.slice(0, 80) + '...' : t.description}`
+                : '';
+            return `${formatTaskIdentity(t.agentTaskRef, t.taskNumber)} [${t.status}] "${t.title}"${assignee}${creator}${msgTag}${descLine}`;
+        }).join('\n');
+        const threadHints = d.tasks
+            .filter((t) => t.messageId)
+            .map((t) => `#t${t.taskNumber} → send_message to "${channel}:${buildThreadShortId(t.messageId)}"`)
+            .join('\n');
+        const hint = threadHints ? `\n\nTo reply in a task's thread:\n${threadHints}` : '';
+        return toText(`## Task Board for ${channel} (${d.tasks.length} tasks)\n\n${formatted}${hint}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('list_my_tasks', 'Bulk-rediscover your own tasks across DMs and channels. By default this returns tasks you created or have been assigned to, and includes each task\'s stable global task ref for later lookup.', {
+    status: z
+        .enum(['all', 'todo', 'in_progress', 'in_review', 'done'])
+        .default('all')
+        .describe('Filter by status (default: all)'),
+    scope: z
+        .enum(['all', 'dm', 'channel'])
+        .default('all')
+        .describe('Filter to DM tasks, channel tasks, or both (default: all)'),
+}, async ({ status, scope }) => {
+    try {
+        const params = new URLSearchParams();
+        if (status !== 'all')
+            params.set('status', status);
+        if (scope !== 'all')
+            params.set('scope', scope);
+        const { ok, data } = await apiFetch(`/my-tasks?${params}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'list my tasks failed')}`);
+        const d = data;
+        if (!d.tasks?.length) {
+            return toText(`No${status !== 'all' ? ` ${status}` : ''} ${scope !== 'all' ? scope : ''} tasks found for you.`.replace(/\s+/g, ' ').trim());
+        }
+        const formatted = d.tasks.map((t) => {
+            const identity = formatTaskIdentity(t.agentTaskRef, t.taskNumber);
+            const assignee = t.claimedByName ? ` → @${t.claimedByName}` : '';
+            const msgTag = t.messageId ? `  msg=${t.messageId.slice(0, 8)}` : '';
+            const threadTag = t.threadTarget ? `  thread=${t.threadTarget}` : '';
+            return `${identity} [${t.status}] "${t.title}"${assignee}  source=${t.sourceLabel ?? t.sourceTarget ?? t.channelId}${msgTag}${threadTag}`;
+        }).join('\n');
+        return toText(`## My Tasks (${d.tasks.length} tasks)\n\n${formatted}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('get_task_status', 'Look up one known task by its stable global task ref and return its current status, source, assignee, and thread hint.', {
+    task_ref: z.string().trim().min(1, 'task_ref is required').describe('Stable global task ref, for example task_ab12cd34ef56'),
+}, async ({ task_ref }) => {
+    try {
+        const params = new URLSearchParams({ task_ref: task_ref.trim().toLowerCase() });
+        const { ok, data } = await apiFetch(`/tasks/by-ref?${params}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'task status lookup failed')}`);
+        const d = data;
+        if (d.deletedTask) {
+            const task = d.deletedTask;
+            const identity = formatTaskIdentity(task.agentTaskRef, task.taskNumber);
+            const details = [
+                `Task: ${identity}`,
+                `Title: ${task.title}`,
+                'Status: deleted',
+                `Previous status: ${task.status}`,
+                `Source: ${task.sourceLabel ?? task.sourceTarget ?? task.channelId}`,
+                `Deleted: ${task.deletedAt ? formatBeijingPromptTimestamp(task.deletedAt) : 'unknown'}`,
+            ];
+            if (task.deletedByName)
+                details.push(`Deleted by: @${task.deletedByName}`);
+            return toText(details.join('\n'));
+        }
+        const task = d.task;
+        if (!task)
+            return toText(`Error: task ${task_ref} not found`);
+        const identity = formatTaskIdentity(task.agentTaskRef, task.taskNumber);
+        const threadTarget = task.threadTarget ?? buildThreadTarget(task.sourceTarget, task.messageId ?? null);
+        const details = [
+            `Task: ${identity}`,
+            `Title: ${task.title}`,
+            `Status: ${task.status}`,
+            `Source: ${task.sourceLabel ?? task.sourceTarget ?? task.channelId}`,
+            `Assignee: ${task.claimedByName ? `@${task.claimedByName}` : 'unclaimed'}`,
+            `Creator: ${task.createdByName ? `@${task.createdByName}` : 'unknown'}`,
+            `Updated: ${task.updatedAt ? formatBeijingPromptTimestamp(task.updatedAt) : 'unknown'}`,
+        ];
+        if (task.messageId)
+            details.push(`Root message: ${task.messageId}`);
+        if (threadTarget)
+            details.push(`Thread target: ${threadTarget}`);
+        return toText(details.join('\n'));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('get_task_history', 'Look up one task you claimed or participated in by its stable global task ref and return its structured lifecycle history. Events are returned newest first. Prefer get_task_status when you only need the current state. Use read_history when you need the actual thread discussion or work output.', {
+    task_ref: z.string().trim().min(1, 'task_ref is required').describe('Stable global task ref, for example task_ab12cd34ef56'),
+    limit: z.number().default(50).describe('Maximum number of history events to return (default 50, max 200)'),
+}, async ({ task_ref, limit }) => {
+    try {
+        const params = new URLSearchParams({
+            task_ref: task_ref.trim().toLowerCase(),
+            limit: String(Math.min(limit, 200)),
+        });
+        const { ok, data } = await apiFetch(`/tasks/history?${params}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'task history lookup failed')}`);
+        const d = data;
+        if (d.deletedTask) {
+            const task = d.deletedTask;
+            const identity = formatTaskIdentity(task.agentTaskRef, task.taskNumber);
+            const header = [
+                `Task: ${identity}`,
+                `Title: ${task.title}`,
+                'Status: deleted',
+                `Previous status: ${task.status}`,
+                `Source: ${task.sourceLabel ?? task.sourceTarget ?? task.channelId}`,
+            ];
+            if (task.deletedAt)
+                header.push(`Deleted: ${formatBeijingPromptTimestamp(task.deletedAt)}`);
+            const timeline = d.events?.length
+                ? d.events.map((event) => {
+                    const parts = [
+                        formatBeijingPromptTimestamp(event.createdAt),
+                        event.type,
+                    ];
+                    if (event.actorName)
+                        parts.push(event.actorType === 'system' ? event.actorName : `@${event.actorName}`);
+                    if (event.fromStatus || event.toStatus)
+                        parts.push(`status ${event.fromStatus ?? 'unknown'} → ${event.toStatus ?? 'unknown'}`);
+                    if (event.claimedByNameAfter)
+                        parts.push(`assignee @${event.claimedByNameAfter}`);
+                    if (event.threadTarget)
+                        parts.push(`thread ${event.threadTarget}`);
+                    return `- ${parts.join(' · ')}`;
+                }).join('\n')
+                : '- No structured task events recorded yet.';
+            return toText(`${header.join('\n')}\nOrder: newest first\nAccess: deleted task tombstone for tasks you claimed or participated in.\n\n## History\n${timeline}`);
+        }
+        const task = d.task;
+        if (!task)
+            return toText(`Error: task ${task_ref} not found`);
+        const identity = formatTaskIdentity(task.agentTaskRef, task.taskNumber);
+        const header = [
+            `Task: ${identity}`,
+            `Title: ${task.title}`,
+            `Status: ${task.status}`,
+            `Source: ${task.sourceLabel ?? task.sourceTarget ?? task.channelId}`,
+        ];
+        const timeline = d.events?.length
+            ? d.events.map((event) => {
+                const parts = [
+                    formatBeijingPromptTimestamp(event.createdAt),
+                    event.type,
+                ];
+                if (event.actorName)
+                    parts.push(event.actorType === 'system' ? event.actorName : `@${event.actorName}`);
+                if (event.fromStatus || event.toStatus)
+                    parts.push(`status ${event.fromStatus ?? 'unknown'} → ${event.toStatus ?? 'unknown'}`);
+                if (event.claimedByNameAfter)
+                    parts.push(`assignee @${event.claimedByNameAfter}`);
+                if (event.threadTarget)
+                    parts.push(`thread ${event.threadTarget}`);
+                return `- ${parts.join(' · ')}`;
+            }).join('\n')
+            : '- No structured task events recorded yet.';
+        return toText(`${header.join('\n')}\nOrder: newest first\nAccess: only tasks you claimed or participated in are visible here.\n\n## History\n${timeline}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── create_tasks ──────────────────────────────────────────────────────────────
+server.tool('create_tasks', "Create one or more new task-messages in a top-level channel or DM. Use this only for genuinely new work or subtasks, not to convert an existing message — use claim_tasks with message_ids for that. In a primary DM, default to a direct reply. In that context, only use this when the user explicitly wants task tracking or the request clearly needs multi-step tracked work. If a primary-DM task is created, the platform opens the task thread automatically and mirrors lifecycle status in the main DM.", {
+    channel: z.string().describe("The channel or DM to create tasks in — e.g. '#general' or 'dm:@User'"),
+    tasks: z
+        .array(z.object({
+        title: z.string().describe('Task title'),
+        description: z.string().trim().min(1, 'description is required').describe('Required task brief / goal / done criteria'),
+    }))
+        .describe('Array of tasks to create'),
+    collaborator_names: z.array(z.string()).optional().describe('Optional collaborator agent names to pull into the same shared task-thread. The current agent remains the owner.'),
+}, async ({ channel, tasks, collaborator_names }) => {
+    try {
+        const { ok, data } = await apiFetch('/tasks', {
+            method: 'POST',
+            body: { channel, tasks, collaborator_names, conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'create tasks failed')}`);
+        const d = data;
+        const created = d.tasks?.map((t) => {
+            const msgShort = t.messageId ? t.messageId.slice(0, 8) : null;
+            const handoff = t.handoffError
+                ? ` → handoff failed: ${t.handoffError}`
+                : t.handoffStarted && t.threadTarget
+                    ? ` → handoff started in ${t.threadTarget}`
+                    : '';
+            const identity = formatTaskIdentity(t.agentTaskRef, t.taskNumber);
+            return msgShort ? `${identity} msg=${msgShort} "${t.title}"${handoff}` : `${identity} "${t.title}"${handoff}`;
+        }).join('\n') ?? '';
+        const hasHandoff = d.tasks?.some((t) => t.handoffStarted) ?? false;
+        const threadHints = hasHandoff ? '' : d.tasks
+            ?.filter((t) => t.messageId)
+            .map((t) => `#t${t.taskNumber} → send_message to "${channel}:${buildThreadShortId(t.messageId)}"`)
+            .join('\n') ?? '';
+        const hint = threadHints ? `\n\nTo follow up in each task's thread:\n${threadHints}` : '';
+        const deliverySection = formatTaskUpdateDeliveriesSection((d.tasks ?? []).flatMap((t) => t.delivery ? [t.delivery] : []));
+        const handoffNote = hasHandoff
+            ? '\n\nPrimary DM handoff started automatically. End this main-DM turn here. Detailed work continues in the task thread. This is an expected phase transition, not a failure or interruption. Do not manually send any follow-up in the main DM; the platform will mirror task status there.'
+            : '';
+        return toText(`Created ${d.tasks?.length ?? 0} task(s) in ${channel}:\n${created}${deliverySection}${hint}${handoffNote}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── claim_message ─────────────────────────────────────────────────────────────
+server.tool('claim_message', `[DEPRECATED] Use claim_tasks instead. Compatibility alias for claim_tasks(message_ids=[...]). Promote one or more existing top-level channel or DM messages into task-messages and claim them. Use the 8-character msg= ID from received messages or read_history. In the current primary DM, you may use message_ids=["current"] for the latest user request instead of manually picking an older msg id. In a primary DM, default to a direct reply. In that context, only use this when the user explicitly wants task tracking or the request clearly needs multi-step tracked work. Each promoted message becomes the task root and default thread. If a primary-DM task is claimed, the platform hands it off to the task thread automatically and mirrors lifecycle status in the main DM. If a message is already a task-message, the claim fails. Thread messages cannot be converted. The task brief is required; use separate calls when promoted messages need different briefs.`, {
+    channel: z.string().describe("The channel or DM — e.g. '#engineering' or 'dm:@User'"),
+    message_ids: z.array(z.string()).describe("8-char message IDs (the msg= value from check_messages or read_history, e.g. ['a1b2c3d4']). In the current primary DM you may use ['current'] to claim the latest user request."),
+    title: z.string().optional().describe('Optional task title override. If omitted, uses the message content (truncated to 120 chars).'),
+    description: z.string().trim().min(1, 'description is required').describe('Required task brief / goal / done criteria. Use one call per message when briefs differ.'),
+    collaborator_names: z.array(z.string()).optional().describe('Optional collaborator agent names to pull into the same shared task-thread. The current agent remains the owner.'),
+}, async ({ channel, message_ids, title, description, collaborator_names }) => {
+    try {
+        const { ok, data } = await apiFetch('/tasks/claim', {
+            method: 'POST',
+            body: { channel, message_ids, title, description, collaborator_names, conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'claim-message failed')}`);
+        const d = data;
+        const lines = (d.results ?? []).map((r) => {
+            const msgShort = r.messageId.slice(0, 8);
+            if (r.success) {
+                const identity = formatTaskIdentity(r.agentTaskRef, r.taskNumber);
+                if (r.handoffError)
+                    return `msg:${msgShort} → ${identity}: claimed, handoff failed — ${r.handoffError}`;
+                if (r.handoffStarted && r.threadTarget)
+                    return `msg:${msgShort} → ${identity}: claimed, handoff started in ${r.threadTarget}`;
+                return `msg:${msgShort} → ${identity}: claimed`;
+            }
+            return `msg:${msgShort}: FAILED — ${r.reason ?? 'unknown error'}`;
+        });
+        const succeeded = (d.results ?? []).filter((r) => r.success).length;
+        const failed = (d.results ?? []).length - succeeded;
+        let summary = `${succeeded} claimed`;
+        if (failed > 0)
+            summary += `, ${failed} failed`;
+        const contextBlocks = (d.results ?? [])
+            .filter((r) => r.success && r.context?.length)
+            .map((r) => {
+            const msgs = r.context.map((m) => `  @${m.senderName}: ${m.content.length > 100 ? m.content.slice(0, 100) + '...' : m.content}`).join('\n');
+            return `${formatTaskIdentity(r.agentTaskRef, r.taskNumber)} context:\n${msgs}`;
+        }).join('\n\n');
+        const contextSection = contextBlocks ? `\n\n${contextBlocks}` : '';
+        const hasHandoff = (d.results ?? []).some((r) => r.handoffStarted);
+        const threadHints = hasHandoff ? '' : (d.results ?? [])
+            .filter((r) => r.success)
+            .map((r) => `${formatTaskIdentity(r.agentTaskRef, r.taskNumber)} → send_message to "${channel}:${buildThreadShortId(r.messageId)}"`)
+            .join('\n');
+        const hint = threadHints ? `\n\nFollow up in each task's thread:\n${threadHints}` : '';
+        const deliverySection = formatTaskUpdateDeliveriesSection((d.results ?? []).flatMap((r) => r.delivery ? [r.delivery] : []));
+        const handoffNote = hasHandoff
+            ? '\n\nPrimary DM handoff started automatically. End this main-DM turn here. Detailed work continues in the task thread. This is an expected phase transition, not a failure or interruption. Do not manually send any follow-up in the main DM; the platform will mirror task status there.'
+            : '';
+        return toText(`Claim results (${summary}):\n${lines.join('\n')}${contextSection}${deliverySection}${hint}${handoffNote}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── update_task_details ───────────────────────────────────────────────────────
+server.tool('update_task_details', 'Update a task title and brief. Use this when the task goal, scope, or done criteria need to be clarified after creation.', {
+    channel: z.string().describe("The channel — e.g. '#general'"),
+    task_number: z.number().describe('The task number to update (e.g. 3)'),
+    title: z.string().trim().min(1, 'title is required').describe('Updated task title'),
+    description: z.string().trim().min(1, 'description is required').describe('Updated task brief / goal / done criteria'),
+}, async ({ channel, task_number, title, description }) => {
+    try {
+        const { ok, data } = await apiFetch('/tasks/update-details', {
+            method: 'POST',
+            body: { channel, task_number, title, description, conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'update task details failed')}`);
+        const d = data;
+        if (d.delivery)
+            return toText(formatTaskUpdateDeliveryText(d.delivery));
+        return toText(`#t${task_number} details updated.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── claim_tasks ───────────────────────────────────────────────────────────────
+server.tool('claim_tasks', `Claim tasks so you are assigned to work on them. Two modes:
+1. By task number: claim existing tasks shown in list_tasks. Use task_numbers=[1, 3].
+2. By message ID: convert a regular top-level channel or DM message into a task and claim it. Use message_ids=["a1b2c3d4"] with description="goal and done criteria". In the current primary DM, prefer message_ids=["current"] for the latest user request.
+
+Thread messages cannot be claimed or converted into tasks. If a task is in "todo" status, claiming auto-advances it to "in_progress". If another agent already claimed it, the claim fails — do not work on that task, move on. In a primary DM, default to a direct reply. In that context, only claim there when the user explicitly wants task tracking or the request clearly needs multi-step tracked work. In a primary DM, a successful claim is handed off to the task thread automatically; stop the current run and let the thread continue the work. Claim before starting trackable execution work.`, {
+    channel: z.string().describe("The channel or DM whose tasks to claim — e.g. '#general' or 'dm:@User'"),
+    task_numbers: z.array(z.number()).optional().describe('Task numbers to claim (e.g. [1, 3, 5])'),
+    message_ids: z.array(z.string()).optional().describe("Message IDs or short ID prefixes (the 8-char msg= value, e.g. ['a1b2c3d4']). In the current primary DM you may use ['current'] to claim the latest user request. Converts a regular top-level message to a task and claims it. Thread messages are not allowed."),
+    title: z.string().optional().describe('Optional task title override when claiming regular top-level messages by message ID.'),
+    description: z.string().optional().describe('Required task brief / goal / done criteria when claiming regular top-level messages by message ID.'),
+    collaborator_names: z.array(z.string()).optional().describe('Optional collaborator agent names to pull into the same shared task-thread. The current agent remains the owner. Supported for claim_message and for claim_tasks when using message_ids or a single existing channel task_number.'),
+}, async ({ channel, task_numbers, message_ids, title, description, collaborator_names }) => {
+    try {
+        if ((!task_numbers || task_numbers.length === 0) && (!message_ids || message_ids.length === 0)) {
+            return toText('Error: provide at least one of task_numbers or message_ids');
+        }
+        const { ok, data } = await apiFetch('/tasks/claim', {
+            method: 'POST',
+            body: { channel, task_numbers, message_ids, title, description, collaborator_names, conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'claim tasks failed')}`);
+        const d = data;
+        const lines = (d.results ?? []).map((r) => {
+            const identity = formatTaskIdentity(r.agentTaskRef, r.taskNumber);
+            if (!r.success)
+                return `${identity}: FAILED — ${r.reason ?? 'already claimed'}`;
+            if (r.handoffError)
+                return `${identity}: claimed, handoff failed — ${r.handoffError}`;
+            if (r.handoffStarted && r.threadTarget)
+                return `${identity}: claimed, handoff started in ${r.threadTarget}`;
+            return `${identity}: claimed`;
+        });
+        const succeeded = (d.results ?? []).filter((r) => r.success).length;
+        const failed = (d.results ?? []).length - succeeded;
+        let summary = `${succeeded} claimed`;
+        if (failed > 0)
+            summary += `, ${failed} failed`;
+        const contextBlocks = (d.results ?? [])
+            .filter((r) => r.success && r.context?.length)
+            .map((r) => {
+            const msgs = r.context.map((m) => `  @${m.senderName}: ${m.content.length > 100 ? m.content.slice(0, 100) + '...' : m.content}`).join('\n');
+            return `${formatTaskIdentity(r.agentTaskRef, r.taskNumber)} context:\n${msgs}`;
+        }).join('\n\n');
+        const contextSection = contextBlocks ? `\n\n${contextBlocks}` : '';
+        const hasHandoff = (d.results ?? []).some((r) => r.handoffStarted);
+        const threadHints = hasHandoff ? '' : (d.results ?? [])
+            .filter((r) => r.success && r.messageId)
+            .map((r) => `${formatTaskIdentity(r.agentTaskRef, r.taskNumber)} → send_message to "${channel}:${buildThreadShortId(r.messageId)}"`)
+            .join('\n');
+        const hint = threadHints ? `\n\nFollow up in each task's thread:\n${threadHints}` : '';
+        const deliverySection = formatTaskUpdateDeliveriesSection((d.results ?? []).flatMap((r) => r.delivery ? [r.delivery] : []));
+        const handoffNote = hasHandoff
+            ? '\n\nPrimary DM handoff started automatically. End this main-DM turn here. Detailed work continues in the task thread. This is an expected phase transition, not a failure or interruption. Do not manually send any follow-up in the main DM; the platform will mirror task status there.'
+            : '';
+        return toText(`Claim results (${summary}):\n${lines.join('\n')}${contextSection}${deliverySection}${hint}${handoffNote}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── unclaim_task ──────────────────────────────────────────────────────────────
+server.tool('unclaim_task', 'Release your claim on a task so someone else can pick it up. Only use this if you can no longer work on the task — not as a way to mark it done.', {
+    channel: z.string().describe("The channel — e.g. '#general'"),
+    task_number: z.number().describe('The task number to unclaim (e.g. 3)'),
+}, async ({ channel, task_number }) => {
+    try {
+        const { ok, data } = await apiFetch('/tasks/unclaim', {
+            method: 'POST',
+            body: { channel, task_number, conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'unclaim failed')}`);
+        const d = data;
+        if (d.delivery)
+            return toText(formatTaskUpdateDeliveryText(d.delivery));
+        return toText(`#t${task_number} unclaimed — now open.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── update_task_status ────────────────────────────────────────────────────────
+server.tool('update_task_status', 'Update a task\'s progress status. Valid transitions for agents: todo→in_progress, in_progress→in_review, in_review→in_progress. Agents cannot mark a task done; move ordinary tasks to in_review when the work is ready for human validation, and let a human decide done or send it back. For one-time reminder task-threads, prefer submit_reminder_occurrence_for_review so the linked reminder occurrence also moves into awaiting_review.', {
+    channel: z.string().describe("The channel — e.g. '#general'"),
+    task_number: z.number().describe('The task number to update (e.g. 3)'),
+    status: z
+        .enum(['todo', 'in_progress', 'in_review'])
+        .describe('The new status'),
+}, async ({ channel, task_number, status }) => {
+    try {
+        const { ok, data } = await apiFetch('/tasks/update-status', {
+            method: 'POST',
+            body: { channel, task_number, status, conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'update status failed')}`);
+        const d = data;
+        if (d.delivery)
+            return toText(formatTaskUpdateDeliveryText(d.delivery));
+        return toText(`#t${task_number} moved to ${status}.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── reminders ────────────────────────────────────────────────────────────────
+const REMINDER_ID_HINT = 'Reminder ID is an opaque system ID. Reminder title is not reminder_id; if you only know the title, call list_my_reminders first. Never invent placeholder reminder_id values such as dummy, dummy2, test, or a title string.';
+const OCCURRENCE_ID_HINT = 'Occurrence ID is an opaque system ID. If you do not already have it, call get_current_reminder_occurrence or list_reminder_occurrences first. Never invent placeholder occurrence_id values such as dummy, dummy2, or test.';
+const REMINDER_TRUST_HINT = 'Treat successful reminder tool results as authoritative. Reminder mutations are live user-visible state. Do not create placeholder, probe, throwaway, or scratch reminders just to test whether reminder tools work.';
+server.tool('list_my_reminders', `List reminders bound to the current agent and current DM user scope. All times are interpreted and displayed in Asia/Shanghai. Recurring reminders create a new DM task-thread on each trigger. ${REMINDER_ID_HINT} ${REMINDER_TRUST_HINT}`, {}, async () => {
+    try {
+        const params = new URLSearchParams();
+        params.set('conversationId', conversationId);
+        const { ok, data } = await apiFetch(`/reminders?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'list reminders failed')}`);
+        const reminders = (data.reminders ?? []);
+        if (reminders.length === 0)
+            return toText('No reminders in the current DM scope.');
+        const lines = reminders.map((reminder) => {
+            const reminderId = String(reminder.reminderId ?? '');
+            const title = String(reminder.title ?? 'untitled');
+            const status = String(reminder.status ?? 'unknown');
+            const scheduleKind = String(reminder.scheduleKind ?? 'one_time');
+            const intervalUnit = reminder.intervalUnit ? String(reminder.intervalUnit) : null;
+            const intervalValue = typeof reminder.intervalValue === 'number' ? reminder.intervalValue : null;
+            const nextRunAt = typeof reminder.nextRunAt === 'number' ? reminder.nextRunAt : null;
+            const recentOccurrences = Array.isArray(reminder.recentOccurrences) ? reminder.recentOccurrences : [];
+            const openOccurrence = recentOccurrences.find((occurrence) => {
+                const occurrenceStatus = String(occurrence.status ?? '');
+                return occurrenceStatus === 'pending' || occurrenceStatus === 'dispatched' || occurrenceStatus === 'failed' || occurrenceStatus === 'snoozed';
+            });
+            const schedule = scheduleKind === 'recurring'
+                ? `every ${intervalValue ?? '?'} ${intervalUnit ?? ''}`.trim()
+                : 'once';
+            const nextRun = nextRunAt ? formatBeijingPromptTimestamp(new Date(nextRunAt).toISOString()) : 'none';
+            const openLine = openOccurrence
+                ? ` open_occurrence_id=${String(openOccurrence.occurrenceId ?? '')} ${String(openOccurrence.status ?? '')}`
+                : '';
+            return `- reminder_id=${reminderId} title="${title}" [${status}] ${schedule} next=${nextRun}${openLine}`;
+        }).join('\n');
+        return toText(`Current reminders:\n${lines}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('create_reminder', `Create a reminder for the current agent in the current DM user scope. All times are Asia/Shanghai wall-clock times. Recurring reminders generate a fresh DM task-thread every time they trigger. This is a live user-visible mutation, not a scratchpad. The returned Reminder ID is the opaque ID you must reuse for update/run/pause/resume/cancel operations. Call this once per real reminder you intend to keep. After a successful create_reminder result, trust it and do not call create_reminder again for the same reminder unless the user explicitly asked for another one. ${REMINDER_TRUST_HINT}`, {
+    title: z.string().trim().min(1, 'title is required').describe('Reminder title shown in the UI and reused as the DM task title.'),
+    prompt_text: z.string().trim().min(1, 'prompt_text is required').describe('Task brief to execute whenever the reminder fires.'),
+    schedule_kind: z.enum(['one_time', 'recurring']).describe('Reminder type.'),
+    start_at: z.number().describe('First trigger time as unix milliseconds, interpreted in Asia/Shanghai when chosen by the caller.'),
+    interval_unit: z.enum(['hour', 'day', 'week']).optional().describe('Required for recurring reminders.'),
+    interval_value: z.number().optional().describe('Required for recurring reminders.'),
+    end_at: z.number().optional().describe('Optional end time in unix milliseconds.'),
+    max_occurrences: z.number().optional().describe('Optional cap for recurring reminders.'),
+}, async ({ title, prompt_text, schedule_kind, start_at, interval_unit, interval_value, end_at, max_occurrences }) => {
+    try {
+        const { ok, data } = await apiFetch('/reminders', {
+            method: 'POST',
+            body: {
+                conversationId,
+                title,
+                promptText: prompt_text,
+                scheduleKind: schedule_kind,
+                startAt: start_at,
+                intervalUnit: interval_unit,
+                intervalValue: interval_value,
+                endAt: end_at,
+                maxOccurrences: max_occurrences,
+            },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'create reminder failed')}`);
+        const reminder = data;
+        const nextRunAt = typeof reminder.nextRunAt === 'number' ? reminder.nextRunAt : null;
+        const nextRun = nextRunAt ? formatBeijingPromptTimestamp(new Date(nextRunAt).toISOString()) : 'none';
+        return toText([
+            `Created reminder "${String(reminder.title ?? title)}".`,
+            `Reminder ID: ${String(reminder.reminderId ?? '')}`,
+            `Schedule: ${String(reminder.scheduleKind ?? schedule_kind)}`,
+            `Next run: ${nextRun}`,
+            'Live reminder created and persisted. Reuse this Reminder ID for later actions instead of creating another reminder to verify the result.',
+        ].join('\n'));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('update_reminder', `Update a reminder in the current DM user scope. All times are Asia/Shanghai wall-clock times. Recurring reminders still generate a fresh DM task-thread on each trigger. ${REMINDER_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+    title: z.string().optional().describe('Optional new reminder title.'),
+    prompt_text: z.string().optional().describe('Optional new reminder task brief.'),
+    schedule_kind: z.enum(['one_time', 'recurring']).optional().describe('Optional new reminder type.'),
+    start_at: z.number().optional().describe('Optional new start time as unix milliseconds.'),
+    interval_unit: z.enum(['hour', 'day', 'week']).optional().describe('Optional new recurring interval unit.'),
+    interval_value: z.number().optional().describe('Optional new recurring interval value.'),
+    end_at: z.number().optional().describe('Optional new end time as unix milliseconds.'),
+    max_occurrences: z.number().optional().describe('Optional new recurring cap.'),
+}, async ({ reminder_id, title, prompt_text, schedule_kind, start_at, interval_unit, interval_value, end_at, max_occurrences }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}`, {
+            method: 'PATCH',
+            body: {
+                conversationId,
+                ...(title !== undefined ? { title } : {}),
+                ...(prompt_text !== undefined ? { promptText: prompt_text } : {}),
+                ...(schedule_kind !== undefined ? { scheduleKind: schedule_kind } : {}),
+                ...(start_at !== undefined ? { startAt: start_at } : {}),
+                ...(interval_unit !== undefined ? { intervalUnit: interval_unit } : {}),
+                ...(interval_value !== undefined ? { intervalValue: interval_value } : {}),
+                ...(end_at !== undefined ? { endAt: end_at } : {}),
+                ...(max_occurrences !== undefined ? { maxOccurrences: max_occurrences } : {}),
+            },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'update reminder failed')}`);
+        const reminder = data;
+        return toText(`Updated reminder "${String(reminder.title ?? reminder_id)}".`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('pause_reminder', `Pause a reminder in the current DM user scope. While paused, it will not schedule new DM task-thread executions. ${REMINDER_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/pause`, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'pause reminder failed')}`);
+        return toText(`Paused reminder ${reminder_id}.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('resume_reminder', `Resume a paused reminder in the current DM user scope. When active again, it resumes scheduling DM task-thread executions. ${REMINDER_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/resume`, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'resume reminder failed')}`);
+        return toText(`Resumed reminder ${reminder_id}.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('cancel_reminder', `Cancel a reminder in the current DM user scope. This stops future scheduled runs for that reminder. ${REMINDER_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/cancel`, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'cancel reminder failed')}`);
+        return toText(`Cancelled reminder ${reminder_id}.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('abandon_reminder', `Abandon a triggered one-time reminder in the current DM user scope. This cancels the reminder and closes the active reminder task thread without marking the linked task done. Use this when the user explicitly wants to stop a one-time reminder after it already started. ${REMINDER_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/abandon`, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'abandon reminder failed')}`);
+        const payload = data;
+        const taskNote = payload.task?.taskNumber != null
+            ? ` Linked task #t${payload.task.taskNumber} remains ${String(payload.task.status ?? 'in_progress')}.`
+            : '';
+        return toText(`Abandoned reminder ${String(payload.reminder?.reminderId ?? reminder_id)}.${taskNote}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('list_reminder_occurrences', `List recent occurrences for one reminder in the current DM scope. Use this when you need exact occurrence IDs or status history. ${REMINDER_ID_HINT} ${OCCURRENCE_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const params = new URLSearchParams();
+        params.set('conversationId', conversationId);
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/occurrences?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'list reminder occurrences failed')}`);
+        const payload = data;
+        const occurrences = payload.occurrences ?? [];
+        if (occurrences.length === 0) {
+            return toText(`Reminder ${reminder_id} has no occurrences yet.`);
+        }
+        const lines = occurrences.slice(0, 10).map((occurrence) => {
+            const scheduledFor = typeof occurrence.scheduledFor === 'number'
+                ? formatBeijingPromptTimestamp(new Date(occurrence.scheduledFor).toISOString())
+                : 'unknown';
+            const taskNote = occurrence.taskNumber != null ? ` task=#t${occurrence.taskNumber}` : '';
+            return `- occurrence_id=${String(occurrence.occurrenceId ?? '')} ${String(occurrence.status ?? 'unknown')} at ${scheduledFor}${taskNote}`;
+        }).join('\n');
+        return toText(`Occurrences for "${String(payload.reminder?.title ?? reminder_id)}" (reminder_id=${String(payload.reminder?.reminderId ?? reminder_id)}):\n${lines}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('get_current_reminder_occurrence', `Get the current open occurrence and latest occurrence for a reminder in the current DM scope. Overdue is derived from the current open occurrence. ${REMINDER_ID_HINT} ${OCCURRENCE_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const params = new URLSearchParams();
+        params.set('conversationId', conversationId);
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/current-occurrence?${params.toString()}`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'get current reminder occurrence failed')}`);
+        const payload = data;
+        const formatOccurrence = (label, occurrence) => {
+            if (!occurrence)
+                return `${label}: none`;
+            const scheduledFor = typeof occurrence.scheduledFor === 'number'
+                ? formatBeijingPromptTimestamp(new Date(occurrence.scheduledFor).toISOString())
+                : 'unknown';
+            return `${label}: occurrence_id=${String(occurrence.occurrenceId ?? '')} ${String(occurrence.status ?? 'unknown')} at ${scheduledFor}`;
+        };
+        return toText(`Reminder "${String(payload.reminder?.title ?? reminder_id)}" (reminder_id=${String(payload.reminder?.reminderId ?? reminder_id)})\n${formatOccurrence('Current', payload.currentOccurrence)}\n${formatOccurrence('Latest', payload.latestOccurrence)}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('submit_reminder_occurrence_for_review', `Submit a one-time reminder occurrence for user review. Use this when the reminder work is ready for approval but should not directly mark the linked DM task done. If you pass reminder_id instead of occurrence_id, the tool submits the current open occurrence for that reminder. ${REMINDER_ID_HINT} ${OCCURRENCE_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    occurrence_id: z.string().optional().describe(`Specific occurrence ID to submit for review. ${OCCURRENCE_ID_HINT}`),
+    reminder_id: z.string().optional().describe(`Optional reminder ID; submits the current open occurrence for that reminder when occurrence_id is omitted. ${REMINDER_ID_HINT}`),
+}, async ({ occurrence_id, reminder_id }) => {
+    try {
+        if (!occurrence_id?.trim() && !reminder_id?.trim()) {
+            return toText('Error: occurrence_id or reminder_id is required');
+        }
+        const path = occurrence_id?.trim()
+            ? `/reminder-occurrences/${encodeURIComponent(occurrence_id.trim())}/submit-for-review`
+            : `/reminders/${encodeURIComponent(reminder_id.trim())}/submit-current-for-review`;
+        const { ok, data } = await apiFetch(path, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'submit reminder occurrence for review failed')}`);
+        const payload = data;
+        const occurrenceLabel = payload.occurrence?.occurrenceId ?? occurrence_id ?? reminder_id ?? '';
+        const taskNote = payload.task?.taskNumber != null
+            ? ` Linked task #t${payload.task.taskNumber} is now ${String(payload.task.status ?? 'in_review')}.`
+            : '';
+        return toText(`Submitted reminder occurrence ${occurrenceLabel} for review.${taskNote}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('complete_current_reminder_occurrence', `Complete the current open occurrence for a reminder in the current DM scope. This remains the recurring-reminder completion path. One-time reminders must use submit_reminder_occurrence_for_review instead. ${REMINDER_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/complete-current`, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'complete current reminder occurrence failed')}`);
+        const payload = data;
+        const taskNote = payload.task?.taskNumber != null ? ` Linked task #t${payload.task.taskNumber} is now done.` : '';
+        return toText([
+            `Reminder ID: ${reminder_id}`,
+            `Completed occurrence ID: ${String(payload.occurrence?.occurrenceId ?? '')}`,
+            `${taskNote.trim() || 'Linked task: none'}`,
+        ].join('\n'));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('run_reminder_now', `Immediately create and dispatch one extra reminder occurrence in the current DM scope. This requires that the reminder has no other open occurrence, except a one-time reminder may use this to retry its current failed occurrence when that failure never created a linked task/thread. ${REMINDER_ID_HINT} Use the exact reminder_id from a reminder tool result; do not pass title text. ${REMINDER_TRUST_HINT}`, {
+    reminder_id: z.string().trim().min(1, 'reminder_id is required').describe(REMINDER_ID_HINT),
+}, async ({ reminder_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminders/${encodeURIComponent(reminder_id)}/run-now`, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'run reminder now failed')}`);
+        const payload = data;
+        return toText([
+            `Reminder ID: ${reminder_id}`,
+            `Occurrence ID: ${String(payload.occurrence?.occurrenceId ?? '')}`,
+            `Status: ${String(payload.occurrence?.status ?? '')}`,
+            payload.task?.taskNumber != null ? `Task: #t${payload.task.taskNumber}` : 'Task: none',
+            'Run-now succeeded. Reuse this Reminder ID and Occurrence ID for follow-up actions instead of probing with extra reminder mutations.',
+        ].join('\n'));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('skip_reminder_occurrence', `Skip an open reminder occurrence in the current DM scope. Use this when the current run should be ended without marking it complete. ${OCCURRENCE_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    occurrence_id: z.string().trim().min(1, 'occurrence_id is required').describe(OCCURRENCE_ID_HINT),
+    reason: z.string().optional().describe('Optional short reason to store with the skip event.'),
+}, async ({ occurrence_id, reason }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminder-occurrences/${encodeURIComponent(occurrence_id)}/skip`, {
+            method: 'POST',
+            body: { conversationId, ...(reason?.trim() ? { reason: reason.trim() } : {}) },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'skip reminder occurrence failed')}`);
+        const payload = data;
+        return toText(`Skipped occurrence ${occurrence_id} (${String(payload.occurrence?.status ?? 'skipped')}).`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('snooze_reminder_occurrence', `Snooze an open reminder occurrence in the current DM scope until a specific unix-millisecond timestamp. This keeps the same occurrence and does not change the long-term reminder cadence. ${OCCURRENCE_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    occurrence_id: z.string().trim().min(1, 'occurrence_id is required').describe(OCCURRENCE_ID_HINT),
+    until: z.number().describe('Future unix timestamp in milliseconds, interpreted in Asia/Shanghai when chosen by the caller.'),
+}, async ({ occurrence_id, until }) => {
+    try {
+        const { ok, data } = await apiFetch(`/reminder-occurrences/${encodeURIComponent(occurrence_id)}/snooze`, {
+            method: 'POST',
+            body: { conversationId, until },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'snooze reminder occurrence failed')}`);
+        const payload = data;
+        const scheduledFor = typeof payload.occurrence?.scheduledFor === 'number'
+            ? formatBeijingPromptTimestamp(new Date(payload.occurrence.scheduledFor).toISOString())
+            : 'unknown';
+        return toText(`Snoozed occurrence ${occurrence_id} until ${scheduledFor} (${String(payload.occurrence?.status ?? 'snoozed')}).`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('complete_reminder_occurrence', `Explicitly complete a reminder occurrence. Completion is never automatic: use this after recurring reminder work is really done. One-time reminders must use submit_reminder_occurrence_for_review first and wait for user approval to reach done. If you pass reminder_id instead of occurrence_id, the tool completes the current open occurrence for that reminder. ${REMINDER_ID_HINT} ${OCCURRENCE_ID_HINT} ${REMINDER_TRUST_HINT}`, {
+    occurrence_id: z.string().optional().describe(`Specific occurrence ID to complete. ${OCCURRENCE_ID_HINT}`),
+    reminder_id: z.string().optional().describe(`Optional reminder ID; completes the current open occurrence for that reminder when occurrence_id is omitted. ${REMINDER_ID_HINT}`),
+}, async ({ occurrence_id, reminder_id }) => {
+    try {
+        if (!occurrence_id?.trim() && !reminder_id?.trim()) {
+            return toText('Error: occurrence_id or reminder_id is required');
+        }
+        const path = occurrence_id?.trim()
+            ? `/reminder-occurrences/${encodeURIComponent(occurrence_id.trim())}/complete`
+            : `/reminders/${encodeURIComponent(reminder_id.trim())}/complete-current`;
+        const { ok, data } = await apiFetch(path, {
+            method: 'POST',
+            body: { conversationId },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'complete reminder occurrence failed')}`);
+        const payload = data;
+        const occurrenceLabel = payload.occurrence?.occurrenceId ?? occurrence_id ?? reminder_id ?? '';
+        const taskNote = payload.task?.taskNumber != null ? ` Linked task #t${payload.task.taskNumber} is now done.` : '';
+        return toText(`Completed reminder occurrence ${occurrenceLabel}.${taskNote}`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── upload_file ───────────────────────────────────────────────────────────────
+server.tool('upload_file', 'Upload a file (image, text, JSON, code, or binary; max 5MB) to the platform. Returns an attachment_id you can pass to send_message to attach it to a message.', {
+    file_path: z.string().describe('Absolute path to the file on your local filesystem'),
+    channel: z.string().optional().describe("Optional channel target override where this file will be used, such as '#general', '#general:threadid', or a raw channelId. If omitted, the current conversation scope is used."),
+}, async ({ file_path, channel }) => {
+    let fileBuffer;
+    try {
+        fileBuffer = readFileSync(file_path);
+    }
+    catch {
+        return toText(`Error: File not found or unreadable: ${file_path}`);
+    }
+    const ext = extname(file_path).toLowerCase();
+    const mimeType = MIME_BY_EXTENSION[ext] ?? 'application/octet-stream';
+    if (fileBuffer.length > 5 * 1024 * 1024)
+        return toText('Error: File too large (max 5MB)');
+    const filename = basename(file_path);
+    const blob = new Blob([new Uint8Array(fileBuffer)], { type: mimeType });
+    const form = new FormData();
+    const channelOverride = channel?.trim();
+    if (channelOverride) {
+        form.append('channelId', channelOverride);
+    }
+    else {
+        form.append('conversationId', conversationId);
+    }
+    form.append('file', blob, filename);
+    const uploadHeaders = {};
+    if (authToken)
+        uploadHeaders['Authorization'] = `Bearer ${authToken}`;
+    try {
+        const res = await fetch(`${base}/assets/upload`, { method: 'POST', headers: uploadHeaders, body: form });
+        const d = await res.json();
+        if (!res.ok)
+            return toText(`Error: ${d.error ?? 'upload failed'}`);
+        return toText(`Uploaded: ${d.filename} (${(d.sizeBytes / 1024).toFixed(1)}KB)\n` +
+            `Attachment ID: ${d.id}\n` +
+            `Kind: ${String(d.kind ?? 'unknown')}\n\n` +
+            `Pass this ID in send_message attachment_ids to attach it to a message.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ── view_file ─────────────────────────────────────────────────────────────────
+server.tool('view_file', 'Download an attachment by its ID and view it directly. Returns an inline image preview for images, text for text-like files, and metadata for other binaries.', {
+    attachment_id: z.string().describe('Attachment UUID returned by upload_file or shown in a message'),
+}, async ({ attachment_id }) => {
+    const cacheRoot = resolveConversationAssetCacheRoot({
+        explicitCacheRoot: assetCacheRootArg,
+        agentId,
+        conversationId,
+    });
+    const downloadHeaders = {};
+    if (authToken)
+        downloadHeaders['Authorization'] = `Bearer ${authToken}`;
+    try {
+        const metadataRes = await fetch(`${serverUrl}/api/assets/${attachment_id}/meta?agentId=${encodeURIComponent(agentId)}&conversationId=${encodeURIComponent(conversationId)}`, { headers: downloadHeaders });
+        if (!metadataRes.ok)
+            return toText(`Error: Failed to authorize attachment access (${metadataRes.status})`);
+        const metadata = await metadataRes.json();
+        const existing = findCachedAssetFile(cacheRoot, attachment_id);
+        const cachedMetadata = readCachedAssetMetadata(cacheRoot, attachment_id);
+        let fileBuffer;
+        const fallbackFilename = metadata.filename?.trim() || cachedMetadata?.filename?.trim() || attachment_id;
+        const fallbackMimeType = MIME_BY_EXTENSION[extname(fallbackFilename).toLowerCase()] ?? 'application/octet-stream';
+        const mimeType = metadata.mimeType?.trim() || cachedMetadata?.mimeType?.trim() || fallbackMimeType;
+        if (existing) {
+            fileBuffer = Buffer.from(readFileSync(existing));
+            if ((metadata.filename?.trim() || metadata.mimeType?.trim()) && (metadata.filename?.trim() !== cachedMetadata?.filename?.trim()
+                || metadata.mimeType?.trim() !== cachedMetadata?.mimeType?.trim())) {
+                writeCachedAssetMetadata(cacheRoot, attachment_id, metadata);
+            }
+        }
+        else {
+            const res = await fetch(`${serverUrl}/api/assets/${attachment_id}?agentId=${encodeURIComponent(agentId)}&conversationId=${encodeURIComponent(conversationId)}`, { headers: downloadHeaders });
+            if (!res.ok)
+                return toText(`Error: Failed to download attachment (${res.status})`);
+            fileBuffer = Buffer.from(await res.arrayBuffer());
+            writeFileSync(buildCachedAssetFilePath(cacheRoot, attachment_id, metadata.filename ?? attachment_id), fileBuffer);
+            writeCachedAssetMetadata(cacheRoot, attachment_id, metadata);
+        }
+        const sizeLabel = `${(fileBuffer.length / 1024).toFixed(1)} KB`;
+        if (mimeType.startsWith('image/')) {
+            return {
+                content: [
+                    { type: 'text', text: `Attachment ${attachment_id} (${mimeType}, ${sizeLabel}):` },
+                    { type: 'image', data: fileBuffer.toString('base64'), mimeType },
+                ],
+            };
+        }
+        if (mimeType.startsWith('text/') || mimeType === 'application/json' || mimeType === 'application/xml') {
+            return toText(buildInlineTextPreview({
+                attachmentId: attachment_id,
+                mimeType,
+                sizeLabel,
+                fileBuffer,
+            }));
+        }
+        return toText(`Attachment ${attachment_id} (${mimeType}, ${sizeLabel}) downloaded. This binary type does not have an inline viewer.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── list_ui_components ──────────────────────────────────────────────────────
+server.tool('list_ui_components', 'List the curated registry of available UI panel components. Each component has a name, human-readable description, data model, props schema, dataset schema, state schema, and supported actions. Treat this as the canonical current-run source for component-level props, dataset, state, and supported actions before the first render_panel call. In /panel:plan or /tool:plan, use this to prepare a chat wireframe and wait for confirmation; do not call render_panel or publish_workspace_tool in that planning run. Dataset source kinds currently accepted by render_panel are workspace_jsonl, inline_rows, attachment_manifest, query_handle, and api_jsonl. For detailed RowTemplateGrid template grammar, use the mounted ui-panel skill docs, including ComputedValue fixed row operations. In RowTemplateGrid, top-level panel.actions is an action registry; use ActionBar or ActionButton for explicit visible action controls. For dashboard/status/tool views, prefer RowTemplateGrid Columns plus concise field labels.', {}, async () => {
+    try {
+        const { ok, data } = await apiFetch('/ui-components');
+        if (!ok)
+            return toText(`Error: ${errText(data, 'list_ui_components failed')}`);
+        const d = data;
+        const contracts = (d.components ?? []);
+        return toText(formatComponentRegistry(contracts));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── render_panel ─────────────────────────────────────────────────────────────
+server.tool('render_panel', 'Create a new interactive UI panel from a curated component and a dataset source. Returns a panel_id that can be attached to messages via send_message(panel_ids=[...]). For continuing the same annotation/evaluation/workbench across turns, prefer upsert_panel(handle=...) instead of render_panel so the existing panel is updated in place. If you have not already read the exact component contract in this run, call list_ui_components() first. In /panel:plan, do not call this; send a chat wireframe and wait for confirmation first. For detailed RowTemplateGrid template grammar, consult the mounted ui-panel skill docs instead of guessing template nodes or dataset shape; ComputedValue supports only fixed row operations, not arbitrary formulas or JavaScript. Dataset source kinds include workspace_jsonl, inline_rows, attachment_manifest, query_handle, and api_jsonl; query_handle uses handle="workspace_jsonl:<path>" for one dynamic paged workspace JSONL file, or handle="workspace_jsonl_list:[\\"a.jsonl\\",\\"b.jsonl\\"]" for ordered multi-file JSONL aggregation. api_jsonl uses url:"http://localhost:.../rows.jsonl" or urls:[...] for one or more JSONL endpoints on the agent node, explicitly allowlisted remote origins, or explicitly allowlisted remote URL prefixes. api_jsonl auth uses node-side named auth profiles only; never put header values or tokens in panel payloads. In RowTemplateGrid, top-level panel.actions only declares actions; use ActionBar or ActionButton when those actions must be visibly clickable in the panel body. Use RowTemplateGrid Columns plus field labels for dashboard/status layouts. Use action mode="notify_agent" for agent-waking actions, or mode="platform_exec" with command and optional workspace-relative cwd for direct execution on the agent node. Panel-to-tool promotion can copy action hints toolKind, paramsSchema, persistent, maxRunSeconds, and idleTimeoutSeconds into the Workspace Tool manifest; ordinary panel clicks do not prompt for paramsSchema. Legacy rpcCommand/rpcCwd action input remains accepted for compatibility.', {
+    component: z.string().trim().min(1, 'component is required').describe('Component name from the curated registry (e.g. "ImageReviewGrid").'),
+    props: z.record(z.string(), z.unknown()).optional().describe('Optional props object matching the component\'s propsSchema.'),
+    dataset: z.object({
+        source: z.union([
+            z.object({
+                kind: z.literal('workspace_jsonl').describe('Dataset source kind: workspace_jsonl.'),
+                path: z.string().trim().min(1, 'dataset.source.path is required').describe('Path to a JSONL file where each line is a dataset row matching the component\'s datasetSchema. Relative paths are resolved from the agent workspace; absolute paths are only allowed when the agent node config allowlists that root via panelAbsolutePathRoots.'),
+            }),
+            z.object({
+                kind: z.literal('inline_rows').describe('Dataset source kind: inline_rows. For small datasets (< 1000 rows).'),
+                rows: z.array(z.record(z.string(), z.unknown())).min(0).describe('Inline rows array. Each element is a row object with fields and media matching the component\'s datasetSchema. Maximum 1000 rows.'),
+            }),
+            z.object({
+                kind: z.literal('attachment_manifest').describe('Dataset source kind: attachment_manifest. Reads an uploaded JSONL asset/attachment scoped to the current panel conversation.'),
+                attachmentId: z.string().trim().min(1, 'dataset.source.attachmentId is required').optional().describe('Uploaded attachment ID containing JSONL rows.'),
+                assetId: z.string().trim().min(1, 'dataset.source.assetId is required').optional().describe('Alias for attachmentId when using asset upload results.'),
+            }).refine((value) => Boolean(value.attachmentId || value.assetId), {
+                message: 'dataset.source.attachmentId or dataset.source.assetId is required',
+            }),
+            z.object({
+                kind: z.literal('query_handle').describe('Dataset source kind: query_handle. Supports workspace_jsonl:<path> for one dynamic paged JSONL file or workspace_jsonl_list:["a.jsonl","b.jsonl"] for ordered multi-file JSONL aggregation without ingesting all rows into panel_rows.'),
+                handle: z.string().trim().min(1, 'dataset.source.handle is required').describe('Query handle. Use workspace_jsonl:<path> for one JSONL file, or workspace_jsonl_list:["a.jsonl","b.jsonl"] for 1-16 JSONL files read in declaration order; relative paths resolve from the agent workspace, absolute paths are allowed only when the agent node config allowlists that root via panelAbsolutePathRoots.'),
+            }),
+            z.object({
+                kind: z.literal('api_jsonl').describe('Dataset source kind: api_jsonl. Reads dynamic JSONL rows from one or more loopback HTTP endpoints on the agent node, agent-node allowlisted remote origins, or agent-node allowlisted URL prefixes without ingesting all rows into panel_rows.'),
+                url: z.string().trim().min(1, 'dataset.source.url is required').optional().describe('Single HTTP URL returning JSONL rows matching the component dataset schema. Use either url or urls, not both.'),
+                urls: z.array(z.string().trim().min(1)).min(1).max(16).optional().describe('Ordered list of 1-16 HTTP URLs returning JSONL rows. Rows are aggregated in URL order. Use either urls or url, not both.'),
+                auth: z.object({
+                    profile: z.string().trim().regex(/^[A-Za-z0-9_.:-]{1,64}$/u, 'dataset.source.auth.profile must be a safe profile name'),
+                }).optional().describe('Optional node-side auth profile name for authenticated api_jsonl endpoints. This is only a profile name advertised by the agent node; never include header names, tokens, or secrets here.'),
+            }).refine((value) => Boolean(value.url) !== Boolean(value.urls), {
+                message: 'dataset.source must specify exactly one of url or urls',
+            }).describe('http://localhost, http://127.0.0.1, and http://[::1] are supported by default; remote http(s) endpoints require the agent node to advertise PANEL_API_JSONL_ALLOWED_ORIGINS or the narrower PANEL_API_JSONL_ALLOWED_URL_PREFIXES. Credentials and arbitrary unallowlisted remote URLs are rejected. Optional auth.profile must match an agent-node PANEL_API_JSONL_AUTH_PROFILES entry.'),
+        ]).optional(),
+        rows: z.string().trim().min(1, 'dataset.rows path is required').optional().describe('Legacy JSONL path. Relative paths are resolved from the agent workspace; absolute paths are only allowed when the agent node config allowlists that root via panelAbsolutePathRoots. Prefer dataset.source={kind:"workspace_jsonl", path:"..."}, dataset.source={kind:"inline_rows", rows:[...]}, dataset.source={kind:"attachment_manifest", attachmentId:"..."}, dataset.source={kind:"query_handle", handle:"workspace_jsonl:<path>"}, dataset.source={kind:"query_handle", handle:"workspace_jsonl_list:[\\"a.jsonl\\",\\"b.jsonl\\"]"}, or dataset.source={kind:"api_jsonl", url:"http://localhost:..."} for new calls.'),
+    }).superRefine((value, ctx) => {
+        const hasSource = value.source !== undefined;
+        const hasLegacyRows = value.rows !== undefined;
+        if (hasSource && hasLegacyRows) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'dataset.source and legacy dataset.rows are mutually exclusive',
+            });
+        }
+        if (!hasSource && !hasLegacyRows) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'dataset.source or legacy dataset.rows is required',
+            });
+        }
+    })
+        .describe('Dataset source. Prefer source.kind="workspace_jsonl" for bounded workspace JSONL files, source.kind="inline_rows" for small datasets (< 1000 rows), source.kind="attachment_manifest" for uploaded JSONL assets, source.kind="query_handle" for dynamic paged workspace JSONL reads, or source.kind="api_jsonl" for dynamic HTTP JSONL reads from one or more loopback endpoints, explicitly allowlisted origins, or explicitly allowlisted URL prefixes; legacy rows path remains accepted for compatibility.'),
+    actions: z.array(panelActionSchema).optional().describe('Optional panel actions that the user can trigger from the panel UI.'),
+}, async ({ component, props, dataset, actions }) => {
+    try {
+        const { ok, data } = await apiFetch('/panels', {
+            method: 'POST',
+            body: {
+                component,
+                props: props ?? {},
+                dataset,
+                actions: actions ?? [],
+                conversationId,
+                runId: currentRunId(),
+            },
+        });
+        if (!ok) {
+            return toText(formatRenderPanelError(data));
+        }
+        const d = data;
+        const panelId = typeof d.panel_id === 'string' ? d.panel_id : '';
+        if (!panelId) {
+            return toText('Panel creation succeeded but no panel_id was returned. This is unexpected.');
+        }
+        return toText(formatRenderPanelSuccess(panelId, data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── upsert_panel ─────────────────────────────────────────────────────────────
+server.tool('upsert_panel', 'Create or update the same curated UI panel using a stable handle scoped to this user, agent, and conversation. Use this by default when continuing an existing annotation/evaluation/workbench panel across turns, instead of creating duplicates. Good handles are semantic and stable within the conversation, such as "pigai-eval-results", "image-review-batch", or "model-compare-workbench"; do not use random UUID handles unless this is intentionally one-off. The component must stay the same for an existing handle; use render_panel for explicit new panels. Dataset semantics match render_panel, and updates replace the target panel definition in place.', {
+    handle: z.string().trim().min(1, 'handle is required').regex(/^[A-Za-z0-9_.:-]{1,96}$/u, 'handle must be 1-96 safe chars').describe('Stable semantic panel handle for this conversation, e.g. "pigai-eval-results", "image-review-batch", or "model-compare-workbench". Avoid random UUIDs unless the panel is intentionally one-off.'),
+    expected_version: z.number().int().positive().optional().describe('Optional optimistic concurrency guard for an existing panel.'),
+    component: z.string().trim().min(1, 'component is required').describe('Component name from the curated registry (e.g. "RowTemplateGrid"). Existing handles cannot switch component.'),
+    props: z.record(z.string(), z.unknown()).optional().describe('Full props object for the desired panel state. On update this replaces prior props instead of shallow merging.'),
+    dataset: z.object({
+        source: z.union([
+            z.object({
+                kind: z.literal('workspace_jsonl'),
+                path: z.string().trim().min(1, 'dataset.source.path is required'),
+            }),
+            z.object({
+                kind: z.literal('inline_rows'),
+                rows: z.array(z.record(z.string(), z.unknown())).min(0),
+            }),
+            z.object({
+                kind: z.literal('attachment_manifest'),
+                attachmentId: z.string().trim().min(1, 'dataset.source.attachmentId is required').optional(),
+                assetId: z.string().trim().min(1, 'dataset.source.assetId is required').optional(),
+            }).refine((value) => Boolean(value.attachmentId || value.assetId), {
+                message: 'dataset.source.attachmentId or dataset.source.assetId is required',
+            }),
+            z.object({
+                kind: z.literal('query_handle'),
+                handle: z.string().trim().min(1, 'dataset.source.handle is required'),
+            }),
+            z.object({
+                kind: z.literal('api_jsonl'),
+                url: z.string().trim().min(1, 'dataset.source.url is required').optional(),
+                urls: z.array(z.string().trim().min(1)).min(1).max(16).optional(),
+                auth: z.object({
+                    profile: z.string().trim().regex(/^[A-Za-z0-9_.:-]{1,64}$/u, 'dataset.source.auth.profile must be a safe profile name'),
+                }).optional(),
+            }).refine((value) => Boolean(value.url) !== Boolean(value.urls), {
+                message: 'dataset.source must specify exactly one of url or urls',
+            }),
+        ]).optional(),
+        rows: z.string().trim().min(1, 'dataset.rows path is required').optional(),
+    }).superRefine((value, ctx) => {
+        const hasSource = value.source !== undefined;
+        const hasLegacyRows = value.rows !== undefined;
+        if (hasSource && hasLegacyRows) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'dataset.source and legacy dataset.rows are mutually exclusive',
+            });
+        }
+        if (!hasSource && !hasLegacyRows) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'dataset.source or legacy dataset.rows is required',
+            });
+        }
+    }).describe('Dataset source. Same accepted shape as render_panel.'),
+    actions: z.array(panelActionSchema).optional().describe('Replacement action list for the desired panel state.'),
+}, async ({ handle, expected_version, component, props, dataset, actions }) => {
+    try {
+        const { ok, data } = await apiFetch('/panels/upsert', {
+            method: 'POST',
+            body: {
+                handle,
+                component,
+                props: props ?? {},
+                dataset,
+                actions: actions ?? [],
+                conversationId,
+                runId: currentRunId(),
+                ...(expected_version !== undefined ? { expectedVersion: expected_version } : {}),
+            },
+        });
+        if (!ok) {
+            return toText(formatUpsertPanelError(data));
+        }
+        const d = data;
+        const panelId = typeof d.panel_id === 'string' ? d.panel_id : '';
+        const version = typeof d.version === 'number' ? d.version : undefined;
+        if (!panelId) {
+            return toText('Panel upsert succeeded but no panel_id was returned. This is unexpected.');
+        }
+        const versionText = version ? ` version=${version}` : '';
+        return toText(`Panel upserted. panel_id=${panelId} handle=${handle}${versionText}\n\nUse send_message(panel_ids=["${panelId}"]) to share it when needed, and use upsert_panel(handle="${handle}", ...) for future same-panel updates.`);
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── patch_panel ──────────────────────────────────────────────────────────────
+server.tool('patch_panel', 'Patch an existing UI panel in place without changing its curated component. Prefer this for precise follow-up refinements when you already know the panel_id. For recurring evaluation/annotation/workbench updates across turns, prefer upsert_panel(handle=...) so the agent does not create duplicates or depend on remembering panel_id. Supports shallow props patch, action replacement, row append/upsert/remove by rowId, status, progress, and result updates. Returns the new panel version. On version_conflict, read latest state/events/rows, merge user changes, and retry with currentVersion; do not blindly overwrite saved user state or annotations.', {
+    panel_id: z.string().trim().min(1, 'panel_id is required').describe('Panel ID returned by render_panel.'),
+    expected_version: z.number().int().positive().optional().describe('Optional optimistic concurrency guard. If supplied, the patch fails when the current panel version differs.'),
+    component: z.string().trim().min(1).optional().describe('Optional current component name. Passing a different component is rejected; patch_panel cannot switch renderer classes.'),
+    props_patch: z.record(z.string(), z.unknown()).optional().describe('Shallow patch merged into existing panel props.'),
+    actions: z.array(panelActionSchema).optional().describe('Replacement action list for the panel.'),
+    rows: z.object({
+        append: z.array(z.object({
+            rowId: z.string().trim().min(1).optional(),
+            fields: z.record(z.string(), z.unknown()),
+            media: z.record(z.string(), z.object({
+                kind: z.enum(['workspace_path', 'asset']),
+                value: z.string(),
+            })).optional(),
+        })).optional().describe('Rows appended at the end. Missing rowId is generated by the server.'),
+        upsert: z.array(z.object({
+            rowId: z.string().trim().min(1),
+            fields: z.record(z.string(), z.unknown()),
+            media: z.record(z.string(), z.object({
+                kind: z.enum(['workspace_path', 'asset']),
+                value: z.string(),
+            })).optional(),
+        })).optional().describe('Rows updated or inserted by rowId. Existing rows merge fields/media shallowly.'),
+        remove_row_ids: z.array(z.string().trim().min(1)).optional().describe('Stable row IDs to remove. Remaining rows are reindexed.'),
+    }).optional().describe('Row mutations keyed by stable rowId.'),
+    status: z.enum(['idle', 'running', 'completed', 'failed']).optional().describe('Panel status.'),
+    progress: z.record(z.string(), z.unknown()).nullable().optional().describe('Small structured progress object, or null to clear.'),
+    result: z.record(z.string(), z.unknown()).nullable().optional().describe('Small structured result object, or null to clear.'),
+}, async ({ panel_id, expected_version, component, props_patch, actions, rows, status, progress, result }) => {
+    try {
+        const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}`, {
+            method: 'PATCH',
+            body: {
+                conversationId,
+                ...(expected_version !== undefined ? { expectedVersion: expected_version } : {}),
+                ...(component ? { component } : {}),
+                ...(props_patch ? { props_patch } : {}),
+                ...(actions ? { actions } : {}),
+                ...(rows ? { rows } : {}),
+                ...(status ? { status } : {}),
+                ...(progress !== undefined ? { progress } : {}),
+                ...(result !== undefined ? { result } : {}),
+            },
+        });
+        if (!ok) {
+            return toText(formatPatchPanelError(data));
+        }
+        return toText(formatPatchPanelSuccess(data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── read_panel_state ────────────────────────────────────────────────────────
+server.tool('read_panel_state', 'Read the current saved state of a panel (filters, sort, and selection) for the triggering user. Returns empty defaults if no state has been saved yet.', {
+    panel_id: z.string().trim().min(1, 'panel_id is required').describe('The panel ID returned by render_panel.'),
+}, async ({ panel_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}/state`);
+        if (!ok) {
+            if (data && typeof data === 'object' && 'error' in data) {
+                return toText(`Error: ${String(data.error)}`);
+            }
+            return toText(`Error: ${errText(data, 'read_panel_state failed')}`);
+        }
+        const d = data;
+        // For non-direct panels, API returns { perUser, shared, version } envelope.
+        // For direct panels, API returns { state: {...} } wrapper.
+        const state = ('perUser' in d || 'shared' in d) ? d : d.state;
+        return toText(formatPanelState(state));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── panel collaborators ────────────────────────────────────────────────────
+server.tool('list_panel_collaborators', 'List owner/collaborator agents registered for a panel surface. Use this before coordinating multi-agent panel maintenance.', {
+    panel_id: z.string().trim().min(1, 'panel_id is required').describe('Panel ID returned by render_panel.'),
+}, async ({ panel_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}/collaborators`);
+        if (!ok)
+            return toText(`Error: ${errText(data, 'list_panel_collaborators failed')}`);
+        return toText(formatPanelCollaborators(data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('add_panel_collaborator', 'Owner-only: add another agent as a collaborator on an existing panel surface so that agent can read/patch/delete and attach the panel in messages. This does not change human viewer visibility.', {
+    panel_id: z.string().trim().min(1, 'panel_id is required').describe('Panel ID returned by render_panel.'),
+    collaborator_agent_id: z.string().trim().min(1).optional().describe('Agent ID to add. Prefer this when known.'),
+    collaborator_name: z.string().trim().min(1).optional().describe('Agent display name to add when the ID is not known.'),
+}, async ({ panel_id, collaborator_agent_id, collaborator_name }) => {
+    try {
+        const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}/collaborators`, {
+            method: 'POST',
+            body: {
+                ...(collaborator_agent_id ? { collaboratorAgentId: collaborator_agent_id } : {}),
+                ...(collaborator_name ? { collaboratorName: collaborator_name } : {}),
+            },
+        });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'add_panel_collaborator failed')}`);
+        return toText(formatPanelCollaborators(data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('remove_panel_collaborator', 'Owner-only: remove a non-owner collaborator agent from a panel surface. The owner row cannot be removed with this tool.', {
+    panel_id: z.string().trim().min(1, 'panel_id is required').describe('Panel ID returned by render_panel.'),
+    collaborator_agent_id: z.string().trim().min(1, 'collaborator_agent_id is required').describe('Agent ID to remove.'),
+}, async ({ panel_id, collaborator_agent_id }) => {
+    try {
+        const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}/collaborators/${encodeURIComponent(collaborator_agent_id)}`, { method: 'DELETE' });
+        if (!ok)
+            return toText(`Error: ${errText(data, 'remove_panel_collaborator failed')}`);
+        return toText(formatPanelCollaborators(data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── read_panel_rows ─────────────────────────────────────────────────────────
+server.tool('read_panel_rows', 'Read panel row details by row_indices, or page through rows with optional filter/sort/cursor/limit. Use this after a Panel Submit Payload references selected rows, or immediately after render_panel to spot-check 1-3 rows before presenting the panel. Payloads intentionally do not inline complete row data. Large row_indices lists are read in internal batches. Dynamic query_handle and api_jsonl panels support cursor pagination, filtering, sorting by declared sortable fields, and row_indices scanning.', {
+    panel_id: z.string().trim().min(1, 'panel_id is required').describe('The panel ID returned by render_panel or shown in a Panel Submit Payload.'),
+    conversation_id: z.string().trim().min(1).optional().describe('Optional panel owner conversation ID. Omit for panels from the current conversation; pass this when reading a collaborator panel created in another conversation.'),
+    row_indices: z.array(z.number().int().nonnegative()).optional().describe('Specific row indices to read, typically from submitPayload.refs.selectedRowIndices.'),
+    filter: z.object({
+        field: z.string().trim().min(1),
+        value: z.union([z.string(), z.number(), z.boolean()]),
+    }).optional().describe('Optional exact-match filter over a declared filterable field.'),
+    sort: z.object({
+        field: z.string().trim().min(1),
+        direction: z.enum(['asc', 'desc']),
+    }).optional().describe('Optional sort over a declared sortable field.'),
+    cursor: z.string().optional().describe('Pagination cursor returned by a previous read_panel_rows call.'),
+    limit: z.number().int().positive().max(200).optional().describe('Maximum rows to return. Defaults to 50.'),
+}, async ({ panel_id, conversation_id, row_indices, filter, sort, cursor, limit }) => {
+    try {
+        const panelConversationId = conversation_id?.trim() || conversationId;
+        if (row_indices && row_indices.length > 200) {
+            const rows = [];
+            for (let start = 0; start < row_indices.length; start += 200) {
+                const batch = row_indices.slice(start, start + 200);
+                const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}/rows/read`, {
+                    method: 'POST',
+                    body: {
+                        conversationId: panelConversationId,
+                        row_indices: batch,
+                    },
+                });
+                if (!ok) {
+                    if (data && typeof data === 'object' && 'error' in data) {
+                        return toText(`Error: ${String(data.error)}`);
+                    }
+                    return toText(`Error: ${errText(data, 'read_panel_rows failed')}`);
+                }
+                const record = data && typeof data === 'object' ? data : {};
+                if (Array.isArray(record.rows))
+                    rows.push(...record.rows);
+            }
+            return toText(formatPanelRows({ panelId: panel_id, rows, nextCursor: null }));
+        }
+        const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}/rows/read`, {
+            method: 'POST',
+            body: {
+                conversationId: panelConversationId,
+                ...(row_indices ? { row_indices } : {}),
+                ...(filter ? { filter } : {}),
+                ...(sort ? { sort } : {}),
+                ...(cursor ? { cursor } : {}),
+                ...(limit ? { limit } : {}),
+            },
+        });
+        if (!ok) {
+            if (data && typeof data === 'object' && 'error' in data) {
+                return toText(`Error: ${String(data.error)}`);
+            }
+            return toText(`Error: ${errText(data, 'read_panel_rows failed')}`);
+        }
+        return toText(formatPanelRows(data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── read_panel_events ────────────────────────────────────────────────────────
+const panelEventTypeSchema = z.enum([
+    'created',
+    'patched',
+    'submitted',
+    'actioned',
+    'failed',
+    'archived',
+    'selection_committed',
+    'annotation_saved',
+    'state_saved',
+]);
+server.tool('read_panel_events', 'Read semantic panel events from the panel audit log. Use this after a user saves annotations, commits selection, submits a form, or triggers an action, then use read_panel_rows for detailed row refs. This returns summaries, wake policy, actor/version/timestamp, and row refs instead of full row or media payloads.', {
+    panel_id: z.string().trim().min(1, 'panel_id is required').describe('The panel ID returned by render_panel/upsert_panel or shown in a Panel Submit Payload.'),
+    conversation_id: z.string().trim().min(1).optional().describe('Optional panel owner conversation ID. Omit for panels from the current conversation; pass this when reading a collaborator panel created in another conversation.'),
+    event_types: z.array(panelEventTypeSchema).optional().describe('Optional event type filter, e.g. ["annotation_saved", "submitted"].'),
+    after_event_id: z.number().int().nonnegative().optional().describe('Only return events with eventId greater than this value. Use the previous next cursor.'),
+    since: z.number().int().nonnegative().optional().describe('Only return events at or after this millisecond timestamp.'),
+    limit: z.number().int().positive().max(100).optional().describe('Maximum events to return. Defaults to 50, max 100.'),
+}, async ({ panel_id, conversation_id, event_types, after_event_id, since, limit }) => {
+    try {
+        const panelConversationId = conversation_id?.trim() || conversationId;
+        const { ok, data } = await apiFetch(`/panels/${encodeURIComponent(panel_id)}/events/read`, {
+            method: 'POST',
+            body: {
+                conversationId: panelConversationId,
+                ...(event_types ? { event_types } : {}),
+                ...(after_event_id != null ? { after_event_id } : {}),
+                ...(since != null ? { since } : {}),
+                ...(limit ? { limit } : {}),
+            },
+        });
+        if (!ok) {
+            if (data && typeof data === 'object' && 'error' in data) {
+                return toText(`Error: ${String(data.error)}`);
+            }
+            return toText(`Error: ${errText(data, 'read_panel_events failed')}`);
+        }
+        return toText(formatPanelEvents(data));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+server.tool('publish_workspace_tool', 'Publish or update a reusable workspace tool mini app from the current agent workspace. Before calling this, write the tool bundle under .agent-tools/<slug>/ and ensure the manifest exists at .agent-tools/<slug>/tool.json. In /tool:plan, do not call this; send a chat wireframe covering actions/status/view layout and wait for confirmation first. New tool creation requires a /tool run or tool maintenance chat; ordinary same-agent follow-up surfaces may only republish an existing same user+agent tool with the same slug. Registered maintainer agents may republish an existing tool only from the same node/workspace as the owner agent; cross-workspace maintainer republish is rejected to avoid implicit execution-owner transfer. For persistent start/restart actions, declare maxRunSeconds when there is a safe upper bound and idleTimeoutSeconds when a silent stdout period should be treated as stale. Use manifest env.condaEnv, env.vars, and env.cwd for shared execution setup instead of repeating conda/env/cd boilerplate in every action command. The platform validates the manifest path, stores the tool, and returns a stable tool URL for the user-facing Tools surface.', {
+    manifest_path: z.string().trim().min(1, 'manifest_path is required').describe('Manifest path inside the current agent workspace. Must resolve to .agent-tools/<slug>/tool.json.'),
+}, async ({ manifest_path }) => {
+    try {
+        let manifestContent;
+        try {
+            manifestContent = readFileSync(manifest_path, 'utf8');
+        }
+        catch {
+            manifestContent = undefined;
+        }
+        const { ok, data } = await apiFetch('/tools/publish', {
+            method: 'POST',
+            body: {
+                conversationId,
+                runId: currentRunId(),
+                manifestPath: manifest_path,
+                ...(typeof manifestContent === 'string' ? { manifestContent } : {}),
+            },
+        });
+        if (!ok) {
+            return toText(`Error: ${errText(data, 'publish_workspace_tool failed')}`);
+        }
+        const record = data && typeof data === 'object' ? data : {};
+        const toolId = typeof record.toolId === 'string' ? record.toolId : '';
+        const toolUrl = typeof record.toolUrl === 'string' ? record.toolUrl : '';
+        const revision = typeof record.revision === 'number' ? record.revision : null;
+        const diagnostics = Array.isArray(record.diagnostics) ? record.diagnostics : [];
+        const diagnosticLines = diagnostics.flatMap((diagnostic) => {
+            if (!diagnostic || typeof diagnostic !== 'object')
+                return [];
+            const entry = diagnostic;
+            const severity = typeof entry.severity === 'string' ? entry.severity : 'warning';
+            const code = typeof entry.code === 'string' ? entry.code : 'workspace_tool_publish_diagnostic';
+            const message = typeof entry.message === 'string' ? entry.message : '';
+            const actionIds = Array.isArray(entry.actionIds)
+                ? entry.actionIds.filter((actionId) => typeof actionId === 'string' && actionId.length > 0)
+                : [];
+            if (!message)
+                return [];
+            return [`diagnostic_${severity}: [${code}] ${message}${actionIds.length ? ` actions=${actionIds.join(',')}` : ''}`];
+        });
+        const lines = [
+            toolId ? `tool_id: ${toolId}` : 'tool published',
+            toolUrl ? `tool_url: ${toolUrl}` : null,
+            revision != null ? `revision: ${revision}` : null,
+            ...diagnosticLines,
+        ].filter(Boolean);
+        return toText(lines.join('\n'));
+    }
+    catch (err) {
+        return toText(`Error: ${err.message}`);
+    }
+});
+// ─── Transport ────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);