agent-relay 8.9.0 → 8.9.1

package/dist/cli/agent-relay-mcp.js

@@ -2,16 +2,21 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { RelayCast, SDK_VERSION, WsClient } from '@relaycast/sdk';
-import { INVALID_AGENT_TOKEN_CODE, agentTokenRecoveryMessage, isInvalidAgentTokenError, isInvalidAgentTokenToolResult, } from '@agent-relay/sdk';
 import { AgentRelay } from '@agent-relay/sdk';
 import { z } from 'zod';
-import { initTelemetry, shutdown as shutdownTelemetry, track, } from './telemetry/index.js';
-import { relaycastWorkspaceTelemetryOptions, withRelaycastTelemetry } from './lib/relaycast-telemetry.js';
-import { errorClassName } from './lib/telemetry-helpers.js';
+import { initTelemetry, shutdown as shutdownTelemetry } from './telemetry/index.js';
+import { withRelaycastTelemetry } from './lib/relaycast-telemetry.js';
+import { RealtimeResourceBridge, SubscriptionManager, registerResourceDefinitions } from './mcp/resources.js';
+import { jsonContent, jsonResult, textContent } from './mcp/tool-results.js';
+import { createWorkspace, extractWorkspaceKey, extractWorkspaceName, requireWorkspaceKey, } from './mcp/workspace.js';
+import { enableInboxPiggyback } from './mcp/telemetry.js';
+import { registerAgentRelayActionTools } from './mcp/action-tools.js';
+import { registerMessagingTools } from './mcp/messaging-tools.js';
+import { identityOverrideInputShape, messageResult } from './mcp/tool-shapes.js';
 const DEFAULT_BASE_URL = 'https://gateway.relaycast.dev';
 export const AGENT_RELAY_MCP_VERSION = process.env.AGENT_RELAY_CLI_VERSION ?? SDK_VERSION ?? 'unknown';
 let mcpTelemetryExitHookInstalled = false;
@@ -46,16 +51,6 @@ const DEFAULT_SYSTEM_PROMPT = `You are an AI agent in a collaborative workspace
 - Use threads for detailed discussions to keep channels organized
 - React with emoji to acknowledge messages
 - Keep messages concise and actionable`;
-const jsonResult = z.object({}).passthrough();
-const messageResult = {
-    message: z.string().describe('Human-readable confirmation message'),
-};
-const identityOverrideInputShape = {
-    as: z
-        .string()
-        .optional()
-        .describe('Registered agent identity to act as when multiple identities have been registered'),
-};
 /** Return env var value, or undefined if missing / an unresolved ${...} template. */
 function resolveEnv(key) {
     const v = process.env[key];
@@ -217,630 +212,6 @@ function createInitialSession(options) {
         wsInitAttempted: false,
     };
 }
-class SubscriptionManager {
-    subscriptions = new Set();
-    subscribe(uri) {
-        this.subscriptions.add(uri);
-    }
-    unsubscribe(uri) {
-        this.subscriptions.delete(uri);
-    }
-    getMatchingSubscriptions(uris) {
-        return uris.filter((uri) => this.subscriptions.has(uri));
-    }
-    getAll() {
-        return [...this.subscriptions];
-    }
-    clear() {
-        this.subscriptions.clear();
-    }
-}
-function getStringEventField(event, field) {
-    if (typeof event !== 'object' || event === null) {
-        return null;
-    }
-    const candidate = event[field];
-    return typeof candidate === 'string' ? candidate : null;
-}
-function eventToResourceUris(event) {
-    const type = getStringEventField(event, 'type');
-    switch (type) {
-        case 'message.created': {
-            const channel = getStringEventField(event, 'channel');
-            return channel ? ['relay://inbox', `relay://channels/${channel}/messages`] : ['relay://inbox'];
-        }
-        case 'message.updated': {
-            const channel = getStringEventField(event, 'channel');
-            return channel ? [`relay://channels/${channel}/messages`] : [];
-        }
-        case 'thread.reply': {
-            const parentId = getStringEventField(event, 'parentId');
-            return parentId ? ['relay://inbox', `relay://messages/${parentId}/thread`] : ['relay://inbox'];
-        }
-        case 'dm.received':
-        case 'group_dm.received': {
-            const conversationId = getStringEventField(event, 'conversationId');
-            return conversationId ? ['relay://inbox', `relay://dm/${conversationId}`] : ['relay://inbox'];
-        }
-        case 'agent.online':
-        case 'agent.offline':
-            return ['relay://agents'];
-        case 'channel.created':
-        case 'channel.updated':
-        case 'channel.archived':
-        case 'member.joined':
-        case 'member.left':
-            return ['relay://channels'];
-        case 'webhook.received':
-        case 'command.invoked': {
-            const channel = getStringEventField(event, 'channel');
-            return channel ? [`relay://channels/${channel}/messages`] : [];
-        }
-        case 'reaction.added':
-        case 'reaction.removed':
-            return ['relay://inbox'];
-        default:
-            return [];
-    }
-}
-class RealtimeResourceBridge {
-    wsClient;
-    subscriptions;
-    notifyCallback;
-    unsubscribeFn = null;
-    constructor(wsClient, subscriptions, notifyCallback) {
-        this.wsClient = wsClient;
-        this.subscriptions = subscriptions;
-        this.notifyCallback = notifyCallback;
-    }
-    start() {
-        this.unsubscribeFn = this.wsClient.on('*', (event) => {
-            const type = getStringEventField(event, 'type');
-            if (type === 'open' ||
-                type === 'close' ||
-                type === 'error' ||
-                type === 'reconnecting' ||
-                type === 'permanently_disconnected') {
-                return;
-            }
-            const matched = this.subscriptions.getMatchingSubscriptions(eventToResourceUris(event));
-            for (const uri of matched) {
-                this.notifyCallback(uri);
-            }
-        });
-        this.wsClient.connect();
-    }
-    stop() {
-        if (this.unsubscribeFn) {
-            this.unsubscribeFn();
-            this.unsubscribeFn = null;
-        }
-        this.wsClient.disconnect();
-    }
-}
-function registerResourceDefinitions(server, getAgentClient, getRelay) {
-    server.registerResource('inbox', 'relay://inbox', { title: 'Inbox', description: 'Unread messages, mentions, and DMs', mimeType: 'application/json' }, async (uri) => {
-        const inbox = await getAgentClient().inbox();
-        return { contents: [{ uri: uri.href, text: JSON.stringify(inbox) }] };
-    });
-    server.registerResource('agents', 'relay://agents', {
-        title: 'Agents',
-        description: 'Online and offline agents in the workspace',
-        mimeType: 'application/json',
-    }, async (uri) => {
-        const agents = await getRelay().agents.list();
-        return { contents: [{ uri: uri.href, text: JSON.stringify(agents) }] };
-    });
-    server.registerResource('channels', 'relay://channels', { title: 'Channels', description: 'Available channels in the workspace', mimeType: 'application/json' }, async (uri) => {
-        const channels = await getAgentClient().channels.list();
-        return { contents: [{ uri: uri.href, text: JSON.stringify(channels) }] };
-    });
-    server.registerResource('channel-messages', new ResourceTemplate('relay://channels/{name}/messages', { list: undefined }), {
-        title: 'Channel Messages',
-        description: 'Messages in a specific channel',
-        mimeType: 'application/json',
-    }, async (uri, params) => {
-        const messages = await getAgentClient().messages(String(params.name));
-        return { contents: [{ uri: uri.href, text: JSON.stringify(messages) }] };
-    });
-    server.registerResource('message-thread', new ResourceTemplate('relay://messages/{id}/thread', { list: undefined }), { title: 'Message Thread', description: 'Thread replies on a message', mimeType: 'application/json' }, async (uri, params) => {
-        const thread = await getAgentClient().thread(String(params.id));
-        return { contents: [{ uri: uri.href, text: JSON.stringify(thread) }] };
-    });
-    server.registerResource('dm-conversation', new ResourceTemplate('relay://dm/{conversation_id}', { list: undefined }), {
-        title: 'DM Conversation',
-        description: 'Direct message conversation',
-        mimeType: 'application/json',
-    }, async (uri, params) => {
-        const messages = await getAgentClient().dms.messages(String(params.conversation_id));
-        return { contents: [{ uri: uri.href, text: JSON.stringify(messages) }] };
-    });
-}
-function hasContentArray(value) {
-    return (typeof value === 'object' && value !== null && Array.isArray(value.content));
-}
-const SKIP_PIGGYBACK = new Set(['check_inbox', 'create_workspace', 'set_workspace_key', 'register_agent']);
-function formatInbox(inbox, selfName) {
-    const norm = (s) => s.trim().replace(/^@/, '').toLowerCase();
-    const selfNorm = selfName ? norm(selfName) : null;
-    const isSelf = (name) => selfNorm != null && norm(name) === selfNorm;
-    const lines = ['--- Pending Messages ---'];
-    if (inbox.unreadChannels?.length) {
-        lines.push('Unread channels:');
-        for (const ch of inbox.unreadChannels) {
-            lines.push(`  #${ch.channelName}: ${ch.unreadCount} unread`);
-        }
-    }
-    const mentions = selfNorm ? inbox.mentions?.filter((m) => !isSelf(m.agentName)) : inbox.mentions;
-    if (mentions?.length) {
-        lines.push('Mentions:');
-        for (const m of mentions) {
-            lines.push(`  @${m.agentName} in #${m.channelName}: "${m.text}"`);
-        }
-    }
-    const dms = selfNorm ? inbox.unreadDms?.filter((dm) => !isSelf(dm.from)) : inbox.unreadDms;
-    if (dms?.length) {
-        lines.push('Unread DMs:');
-        for (const dm of dms) {
-            lines.push(`  From ${dm.from}: ${dm.unreadCount} unread`);
-        }
-    }
-    const reactions = selfNorm
-        ? inbox.recentReactions?.filter((reaction) => !isSelf(reaction.agentName))
-        : inbox.recentReactions;
-    if (reactions?.length) {
-        lines.push('Reactions (informational; no response required):');
-        for (const reaction of reactions) {
-            lines.push(`  :${reaction.emoji}: on your message in #${reaction.channelName} by @${reaction.agentName}`);
-        }
-    }
-    return lines.length === 1 ? '' : lines.join('\n');
-}
-function readAsIdentity(args) {
-    const [input] = args;
-    if (typeof input !== 'object' || input === null)
-        return undefined;
-    const as = input.as;
-    return typeof as === 'string' ? as : undefined;
-}
-function invalidAgentTokenToolResult() {
-    const text = agentTokenRecoveryMessage();
-    return {
-        content: [{ type: 'text', text }],
-        structuredContent: {
-            error: { code: INVALID_AGENT_TOKEN_CODE, message: text },
-        },
-        isError: true,
-    };
-}
-function isErrorToolResult(value) {
-    return Boolean(value && typeof value === 'object' && value.isError === true);
-}
-/**
- * Owned tools that delegate to the actions surface (`actions.invoke(...)`)
- * rather than the agents/messaging APIs. Together with the dynamic per-action
- * tools (tracked via `actionToolNames`), these intentionally skip per-tool
- * telemetry so the same underlying action is not counted differently depending
- * on which MCP surface the caller used (e.g. `spawn` vs `invoke_action`).
- */
-const ACTION_ROUTED_TOOL_NAMES = new Set(['invoke_action', 'spawn']);
-/**
- * Coarse type/category metadata for the statically-registered ("owned") MCP
- * tools. Action-routed calls (see `ACTION_ROUTED_TOOL_NAMES`) and the dynamic
- * per-action tools surfaced from the actions registry are intentionally
- * excluded from per-tool telemetry (see the skip in `enableInboxPiggyback`),
- * so they have no entry.
- */
-const AGENT_RELAY_TOOL_CALL_METADATA = {
-    add_agent: { toolType: 'agent.create', toolCategory: 'spawn' },
-    remove_agent: { toolType: 'agent.release', toolCategory: 'release' },
-    list_actions: { toolType: 'action.list', toolCategory: 'action' },
-    submit_result: { toolType: 'result.submit', toolCategory: 'result' },
-    create_workspace: { toolType: 'workspace.create', toolCategory: 'workspace' },
-    set_workspace_key: { toolType: 'workspace.set_key', toolCategory: 'workspace' },
-    register_agent: { toolType: 'agent.register', toolCategory: 'agent' },
-    list_agents: { toolType: 'agent.list', toolCategory: 'agent' },
-    post_message: { toolType: 'message.post', toolCategory: 'message' },
-    send_dm: { toolType: 'message.dm', toolCategory: 'message' },
-    send_group_dm: { toolType: 'message.group_dm', toolCategory: 'message' },
-    list_dms: { toolType: 'message.dm_list', toolCategory: 'message' },
-    list_messages: { toolType: 'message.list', toolCategory: 'message' },
-    reply_to_thread: { toolType: 'message.reply', toolCategory: 'message' },
-    get_message_thread: { toolType: 'message.thread', toolCategory: 'message' },
-    search_messages: { toolType: 'message.search', toolCategory: 'message' },
-    create_channel: { toolType: 'channel.create', toolCategory: 'channel' },
-    list_channels: { toolType: 'channel.list', toolCategory: 'channel' },
-    join_channel: { toolType: 'channel.join', toolCategory: 'channel' },
-    leave_channel: { toolType: 'channel.leave', toolCategory: 'channel' },
-    set_channel_topic: { toolType: 'channel.set_topic', toolCategory: 'channel' },
-    archive_channel: { toolType: 'channel.archive', toolCategory: 'channel' },
-    invite_to_channel: { toolType: 'channel.invite', toolCategory: 'channel' },
-    add_reaction: { toolType: 'reaction.add', toolCategory: 'reaction' },
-    remove_reaction: { toolType: 'reaction.remove', toolCategory: 'reaction' },
-    check_inbox: { toolType: 'inbox.check', toolCategory: 'inbox' },
-    mark_message_read: { toolType: 'inbox.mark_read', toolCategory: 'inbox' },
-    get_message_readers: { toolType: 'inbox.reader_list', toolCategory: 'inbox' },
-};
-function agentRelayToolCallMetadata(name) {
-    const known = AGENT_RELAY_TOOL_CALL_METADATA[name];
-    return known ?? { toolType: name, toolCategory: 'tool' };
-}
-function trackAgentRelayToolCall(input) {
-    track('agent_relay_tool_call', {
-        tool_name: input.toolName,
-        tool_type: input.toolType,
-        tool_category: input.toolCategory,
-        transport: input.transport ?? 'unknown',
-        success: input.success,
-        duration_ms: Date.now() - input.startedAt,
-        ...(input.errorClass ? { error_class: input.errorClass } : {}),
-    });
-}
-function enableInboxPiggyback(mcpServer, getSession, getAgentClient, invalidateAgentToken, telemetryTransport, actionToolNames = new Set()) {
-    const original = mcpServer.registerTool.bind(mcpServer);
-    const mutableServer = mcpServer;
-    mutableServer.registerTool = (name, config, handler) => {
-        if (!handler) {
-            return original(name, config, handler);
-        }
-        const wrapped = async (...args) => {
-            const asIdentity = readAsIdentity(args);
-            const startedAt = Date.now();
-            // Action-routed calls (`invoke_action`, `spawn`, and the dynamic
-            // per-action tools) run through the actions surface and deliberately skip
-            // per-tool telemetry; only the owned tools emit `agent_relay_tool_call`.
-            const toolMetadata = !ACTION_ROUTED_TOOL_NAMES.has(name) && !actionToolNames.has(name)
-                ? agentRelayToolCallMetadata(name)
-                : undefined;
-            let result;
-            try {
-                result = await handler(...args);
-            }
-            catch (err) {
-                if (name !== 'register_agent' && isInvalidAgentTokenError(err)) {
-                    invalidateAgentToken(asIdentity);
-                    if (toolMetadata) {
-                        trackAgentRelayToolCall({
-                            toolName: name,
-                            toolType: toolMetadata.toolType,
-                            toolCategory: toolMetadata.toolCategory,
-                            transport: telemetryTransport,
-                            startedAt,
-                            success: false,
-                            errorClass: errorClassName(err) ?? 'InvalidAgentToken',
-                        });
-                    }
-                    return invalidAgentTokenToolResult();
-                }
-                if (toolMetadata) {
-                    trackAgentRelayToolCall({
-                        toolName: name,
-                        toolType: toolMetadata.toolType,
-                        toolCategory: toolMetadata.toolCategory,
-                        transport: telemetryTransport,
-                        startedAt,
-                        success: false,
-                        errorClass: errorClassName(err),
-                    });
-                }
-                throw err;
-            }
-            if (name !== 'register_agent' && isInvalidAgentTokenToolResult(result)) {
-                invalidateAgentToken(asIdentity);
-                if (toolMetadata) {
-                    trackAgentRelayToolCall({
-                        toolName: name,
-                        toolType: toolMetadata.toolType,
-                        toolCategory: toolMetadata.toolCategory,
-                        transport: telemetryTransport,
-                        startedAt,
-                        success: false,
-                        errorClass: 'InvalidAgentToken',
-                    });
-                }
-                if (hasContentArray(result)) {
-                    result.content.push({ type: 'text', text: agentTokenRecoveryMessage() });
-                }
-                return result;
-            }
-            if (!SKIP_PIGGYBACK.has(name) && getSession().agentToken && hasContentArray(result)) {
-                try {
-                    const inbox = await getAgentClient(asIdentity).inbox();
-                    const inboxText = formatInbox(inbox, asIdentity ?? getSession().agentName);
-                    if (inboxText) {
-                        result.content.push({ type: 'text', text: inboxText });
-                    }
-                }
-                catch (err) {
-                    if (isInvalidAgentTokenError(err)) {
-                        invalidateAgentToken(asIdentity);
-                    }
-                }
-            }
-            if (toolMetadata) {
-                const resultIsError = isErrorToolResult(result);
-                trackAgentRelayToolCall({
-                    toolName: name,
-                    toolType: toolMetadata.toolType,
-                    toolCategory: toolMetadata.toolCategory,
-                    transport: telemetryTransport,
-                    startedAt,
-                    success: !resultIsError,
-                    ...(resultIsError ? { errorClass: 'ToolResultError' } : {}),
-                });
-            }
-            return result;
-        };
-        return original(name, config, wrapped);
-    };
-}
-async function createWorkspace(name, baseUrl) {
-    return (await RelayCast.createWorkspace(name, {
-        baseUrl,
-        ...relaycastWorkspaceTelemetryOptions(),
-    }));
-}
-function extractWorkspaceKey(payload) {
-    const data = payload.data && typeof payload.data === 'object' ? payload.data : {};
-    const value = payload.workspaceKey ??
-        payload.workspace_key ??
-        payload.apiKey ??
-        payload.api_key ??
-        data.workspaceKey ??
-        data.workspace_key ??
-        data.apiKey ??
-        data.api_key;
-    return typeof value === 'string' && value.trim() ? value : undefined;
-}
-function extractWorkspaceName(payload, fallback) {
-    const data = payload.data && typeof payload.data === 'object' ? payload.data : {};
-    const value = payload.workspaceName ?? payload.workspace_name ?? payload.name ?? data.workspaceName;
-    return typeof value === 'string' && value.trim() ? value : fallback;
-}
-function requireWorkspaceKey(session) {
-    if (session.workspaceKey) {
-        return;
-    }
-    throw new Error('Workspace key not configured. Call "create_workspace" first, or "set_workspace_key" if someone shared a workspace key.');
-}
-function jsonContent(value) {
-    const structuredContent = typeof value === 'object' && value !== null && !Array.isArray(value)
-        ? value
-        : { value };
-    return {
-        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
-        structuredContent,
-    };
-}
-function textContent(message, structuredContent = { message }) {
-    return {
-        content: [{ type: 'text', text: message }],
-        structuredContent,
-    };
-}
-function isSchemaObject(schema) {
-    return Boolean(schema &&
-        typeof schema === 'object' &&
-        !Array.isArray(schema) &&
-        typeof schema.safeParse !== 'function');
-}
-function getSchemaDescription(schema) {
-    return isSchemaObject(schema) && typeof schema.description === 'string' ? schema.description : undefined;
-}
-function zodFromJsonSchema(schema) {
-    if (schema === false) {
-        return z.never();
-    }
-    if (!isSchemaObject(schema)) {
-        return z.unknown();
-    }
-    let zodType;
-    const schemaType = Array.isArray(schema.type) ? schema.type[0] : schema.type;
-    switch (schemaType) {
-        case 'array':
-            zodType = z.array(zodFromJsonSchema(schema.items));
-            break;
-        case 'boolean':
-            zodType = z.boolean();
-            break;
-        case 'integer':
-            zodType = z.number().int();
-            break;
-        case 'number':
-            zodType = z.number();
-            break;
-        case 'object':
-            if (schema.properties) {
-                const required = new Set(schema.required ?? []);
-                const shape = {};
-                for (const [key, childSchema] of Object.entries(schema.properties)) {
-                    const child = zodFromJsonSchema(childSchema);
-                    shape[key] = required.has(key) ? child : child.optional();
-                }
-                zodType = z.object(shape).passthrough();
-            }
-            else {
-                zodType = z.record(z.string(), z.unknown());
-            }
-            break;
-        case 'string':
-            zodType = z.string();
-            break;
-        default:
-            zodType = z.unknown();
-            break;
-    }
-    const description = getSchemaDescription(schema);
-    return description ? zodType.describe(description) : zodType;
-}
-function actionToolInputSchema(schema) {
-    const zodShape = zodObjectShape(schema);
-    if (zodShape) {
-        return zodShape;
-    }
-    if (!isSchemaObject(schema) || schema.type !== 'object') {
-        return {
-            input: z.unknown().describe('Action input payload. The action registry performs final validation.'),
-        };
-    }
-    const required = new Set(schema.required ?? []);
-    const shape = {};
-    for (const [key, childSchema] of Object.entries(schema.properties ?? {})) {
-        const child = zodFromJsonSchema(childSchema);
-        shape[key] = required.has(key) ? child : child.optional();
-    }
-    return shape;
-}
-function actionInvocationInput(descriptor, args) {
-    const schema = descriptor.inputSchema;
-    if (zodObjectShape(schema)) {
-        return args;
-    }
-    if (!isSchemaObject(schema) || schema.type !== 'object') {
-        return typeof args === 'object' && args !== null && 'input' in args
-            ? args.input
-            : args;
-    }
-    return args;
-}
-function zodObjectShape(schema) {
-    if (schema instanceof z.ZodObject) {
-        return schema.shape;
-    }
-    return undefined;
-}
-function serializableActionDescriptor(descriptor) {
-    return {
-        name: descriptor.name,
-        description: descriptor.description,
-        visibility: descriptor.visibility,
-        ...(descriptor.inputSchema ? { inputSchema: serializableActionSchema(descriptor.inputSchema) } : {}),
-        ...(descriptor.outputSchema ? { outputSchema: serializableActionSchema(descriptor.outputSchema) } : {}),
-    };
-}
-function serializableActionSchema(schema) {
-    if (isSchemaObject(schema)) {
-        return schema;
-    }
-    if (isZodLikeSchema(schema)) {
-        return {
-            type: 'zod',
-            ...(schema.description ? { description: schema.description } : {}),
-        };
-    }
-    return schema;
-}
-function isZodLikeSchema(schema) {
-    return Boolean(schema &&
-        typeof schema === 'object' &&
-        !Array.isArray(schema) &&
-        typeof schema.safeParse === 'function');
-}
-function registerAgentRelayActionTools(server, actions, getSession, onAuditEvent, getAgentClient, actionToolNames) {
-    if (!actions) {
-        return;
-    }
-    /**
-     * Fire-and-forget invocation through the relay: returns an immediate ack
-     * (with an `invocation_id`) and does NOT run the handler inline. Falls back to
-     * the local in-process registry when the relay action surface is unavailable.
-     */
-    const invokeAction = async (name, input) => {
-        const relayActions = getRelayAgentActions(getAgentClient);
-        if (relayActions) {
-            try {
-                const ack = await relayActions.invoke(name, asInputRecord(input));
-                return jsonContent({ ok: true, status: 'invoked', invocation: ack });
-            }
-            catch (error) {
-                return { ...jsonContent({ ok: false, error: errorMessage(error) }), isError: true };
-            }
-        }
-        const session = getSession();
-        const result = await actions.invoke({
-            name,
-            input,
-            context: {
-                caller: { name: session.agentName ?? 'mcp', type: 'agent' },
-                emit: onAuditEvent,
-            },
-        });
-        return result.ok ? jsonContent(result) : { ...jsonContent(result), isError: true };
-    };
-    server.registerTool('list_actions', {
-        title: 'List Actions',
-        description: 'List Agent Relay actions available to this agent.',
-        inputSchema: {},
-        outputSchema: jsonResult,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    }, async () => jsonContent({
-        actions: (await actions.list({ visibility: 'agent' })).map(serializableActionDescriptor),
-    }));
-    server.registerTool('invoke_action', {
-        title: 'Invoke Action',
-        description: 'Invoke a registered Agent Relay action by name. Fire-and-forget: returns an ack with an invocation id; the result arrives asynchronously to the action handler.',
-        inputSchema: {
-            name: z.string().describe('Registered action name'),
-            input: z.unknown().describe('Action input payload'),
-        },
-        outputSchema: jsonResult,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    }, async ({ name, input }) => invokeAction(name, input));
-    void actions
-        .list({ visibility: 'agent' })
-        .then((descriptors) => {
-        for (const descriptor of descriptors) {
-            actionToolNames?.add(descriptor.name);
-            server.registerTool(descriptor.name, {
-                title: descriptor.name,
-                description: descriptor.description,
-                inputSchema: actionToolInputSchema(descriptor.inputSchema),
-                outputSchema: jsonResult,
-                annotations: {
-                    readOnlyHint: false,
-                    destructiveHint: false,
-                    idempotentHint: false,
-                    openWorldHint: false,
-                },
-            }, async (args) => invokeAction(descriptor.name, actionInvocationInput(descriptor, args)));
-        }
-    })
-        .catch(() => undefined);
-}
-/** The relay-backed action surface on the live agent client, when available. */
-function getRelayAgentActions(getAgentClient) {
-    if (!getAgentClient) {
-        return undefined;
-    }
-    try {
-        return getAgentClient().actions;
-    }
-    catch {
-        return undefined;
-    }
-}
-function asInputRecord(input) {
-    if (input === undefined || input === null) {
-        return undefined;
-    }
-    if (typeof input === 'object' && !Array.isArray(input)) {
-        return input;
-    }
-    return { input };
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 function createRegisteredAgent(agentName, agentToken) {
     return { agentName, agentToken };
 }
@@ -887,21 +258,6 @@ export async function registerAgentWithRebind({ session, setSession, getRelay, n
         warnings,
     };
 }
-function resolveEmoji(input) {
-    const normalized = input.trim().replace(/^:/, '').replace(/:$/, '').toLowerCase();
-    const aliases = {
-        '+1': '👍',
-        thumbsup: '👍',
-        thumbs_up: '👍',
-        check: '✅',
-        white_check_mark: '✅',
-        rocket: '🚀',
-        eyes: '👀',
-        heart: '❤️',
-        clap: '👏',
-    };
-    return aliases[normalized] ?? input;
-}
 function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, setSession, baseUrl, strictAgentName, preferredAgentName, forcedAgentType) {
     server.registerTool('create_workspace', {
         title: 'Create Workspace',
@@ -1046,295 +402,7 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
         const relay = new AgentRelay({ workspaceKey: session.workspaceKey ?? undefined, baseUrl });
         return jsonContent({ nodes: await relay.nodes.list({ capability, name }) });
     });
-    server.registerTool('create_channel', {
-        title: 'Create Channel',
-        description: 'Create a new workspace channel.',
-        inputSchema: {
-            name: z.string().describe('Unique channel name'),
-            topic: z.string().optional().describe('Optional channel topic'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-    }, async ({ name, topic, as }) => jsonContent(await getAgentClient(as).channels.create({ name, topic })));
-    server.registerTool('list_channels', {
-        title: 'List Channels',
-        description: 'List channels available in the workspace.',
-        inputSchema: {
-            include_archived: z.boolean().optional().describe('Include archived channels'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: {
-            channels: z.array(z.object({}).passthrough()).describe('Channels'),
-        },
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ include_archived, as }) => {
-        const channels = await getAgentClient(as).channels.list(include_archived ? { includeArchived: include_archived } : undefined);
-        return jsonContent({ channels });
-    });
-    server.registerTool('join_channel', {
-        title: 'Join Channel',
-        description: 'Join an existing channel.',
-        inputSchema: {
-            channel: z.string().describe('Channel name'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: messageResult,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ channel, as }) => {
-        await getAgentClient(as).channels.join(channel);
-        return textContent(`Joined channel #${channel}`);
-    });
-    server.registerTool('leave_channel', {
-        title: 'Leave Channel',
-        description: 'Leave a channel.',
-        inputSchema: {
-            channel: z.string().describe('Channel name'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: messageResult,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ channel, as }) => {
-        await getAgentClient(as).channels.leave(channel);
-        return textContent(`Left channel #${channel}`);
-    });
-    server.registerTool('invite_to_channel', {
-        title: 'Invite to Channel',
-        description: 'Invite another agent to a channel.',
-        inputSchema: {
-            channel: z.string().describe('Channel name'),
-            agent: z.string().describe('Agent name to invite'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: messageResult,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ channel, agent, as }) => {
-        await getAgentClient(as).channels.invite(channel, agent);
-        return textContent(`Invited ${agent} to #${channel}`);
-    });
-    server.registerTool('set_channel_topic', {
-        title: 'Set Channel Topic',
-        description: 'Update a channel topic.',
-        inputSchema: {
-            channel: z.string().describe('Channel name'),
-            topic: z.string().describe('New topic'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ channel, topic, as }) => jsonContent(await getAgentClient(as).channels.setTopic(channel, topic)));
-    server.registerTool('archive_channel', {
-        title: 'Archive Channel',
-        description: 'Archive a channel.',
-        inputSchema: {
-            channel: z.string().describe('Channel name'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: messageResult,
-        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
-    }, async ({ channel, as }) => {
-        await getAgentClient(as).channels.archive(channel);
-        return textContent(`Archived channel #${channel}`);
-    });
-    server.registerTool('post_message', {
-        title: 'Post Message',
-        description: 'Post a new message to a channel as the current agent.',
-        inputSchema: {
-            channel: z.string().describe('Channel name'),
-            text: z.string().describe('Message text'),
-            attachments: z.array(z.string()).optional().describe('File attachment IDs'),
-            mode: z.enum(['wait', 'steer']).optional().describe('Delivery mode'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-    }, async ({ channel, text, attachments, mode, as }) => jsonContent(await getAgentClient(as).send(channel, text, { attachments, mode })));
-    server.registerTool('list_messages', {
-        title: 'Get Messages',
-        description: 'Retrieve message history from a channel.',
-        inputSchema: {
-            channel: z.string().describe('Channel name'),
-            limit: z.number().optional().describe('Maximum messages to return'),
-            before: z.string().optional().describe('Older-than cursor'),
-            after: z.string().optional().describe('Newer-than cursor'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: {
-            messages: z.array(z.object({}).passthrough()).describe('Messages'),
-        },
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ channel, limit, before, after, as }) => {
-        const messages = await getAgentClient(as).messages(channel, { limit, before, after });
-        return jsonContent({ messages });
-    });
-    server.registerTool('reply_to_thread', {
-        title: 'Reply to Thread',
-        description: 'Reply to an existing message thread.',
-        inputSchema: {
-            message_id: z.string().describe('Parent message ID'),
-            text: z.string().describe('Reply text'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-    }, async ({ message_id, text, as }) => jsonContent(await getAgentClient(as).reply(message_id, text)));
-    server.registerTool('get_message_thread', {
-        title: 'Get Thread',
-        description: 'Retrieve a message thread.',
-        inputSchema: {
-            message_id: z.string().describe('Parent message ID'),
-            limit: z.number().optional().describe('Maximum replies to return'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ message_id, limit, as }) => jsonContent(await getAgentClient(as).thread(message_id, limit ? { limit } : undefined)));
-    server.registerTool('send_dm', {
-        title: 'Send Direct Message',
-        description: 'Send a private direct message to another agent.',
-        inputSchema: {
-            to: z.string().describe('Recipient agent name'),
-            text: z.string().describe('DM text'),
-            mode: z.enum(['wait', 'steer']).optional().describe('Delivery mode'),
-            attachments: z.array(z.string()).optional().describe('File attachment IDs'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-    }, async ({ to, text, mode, attachments, as }) => jsonContent(await getAgentClient(as).dm(to, text, { mode, attachments })));
-    server.registerTool('list_dms', {
-        title: 'List DM Conversations',
-        description: 'List direct message conversations for the current agent.',
-        inputSchema: {
-            ...identityOverrideInputShape,
-        },
-        outputSchema: {
-            conversations: z.array(z.object({}).passthrough()).describe('DM conversations'),
-        },
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ as }) => jsonContent({ conversations: await getAgentClient(as).dms.conversations() }));
-    server.registerTool('send_group_dm', {
-        title: 'Send Group DM',
-        description: 'Create a group DM and send the first message.',
-        inputSchema: {
-            participants: z.array(z.string()).describe('Participant agent names'),
-            name: z.string().optional().describe('Optional group name'),
-            text: z.string().describe('Initial message'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-    }, async ({ participants, name, text, as }) => {
-        const client = getAgentClient(as);
-        const conversation = await client.dms.createGroup({ participants, name });
-        const message = await client.dms.sendMessage(conversation.id, text);
-        return jsonContent({ conversation, message });
-    });
-    server.registerTool('add_reaction', {
-        title: 'Add Reaction',
-        description: 'Add an emoji reaction to a message.',
-        inputSchema: {
-            message_id: z.string().describe('Message ID'),
-            emoji: z.string().describe('Emoji character or shortcode'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: messageResult,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ message_id, emoji, as }) => {
-        const resolved = resolveEmoji(emoji);
-        await getAgentClient(as).react(message_id, resolved);
-        return textContent(`Reacted with ${resolved}`);
-    });
-    server.registerTool('remove_reaction', {
-        title: 'Remove Reaction',
-        description: 'Remove an emoji reaction from a message.',
-        inputSchema: {
-            message_id: z.string().describe('Message ID'),
-            emoji: z.string().describe('Emoji character or shortcode'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: messageResult,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ message_id, emoji, as }) => {
-        const resolved = resolveEmoji(emoji);
-        await getAgentClient(as).unreact(message_id, resolved);
-        return textContent(`Removed reaction ${resolved}`);
-    });
-    server.registerTool('search_messages', {
-        title: 'Search Messages',
-        description: 'Search messages across the workspace.',
-        inputSchema: {
-            query: z.string().describe('Text search query'),
-            channel: z.string().optional().describe('Optional channel filter'),
-            from: z.string().optional().describe('Optional sender filter'),
-            limit: z.number().optional().describe('Maximum results'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: {
-            results: z.array(z.object({}).passthrough()).describe('Search results'),
-        },
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ query, channel, from, limit, as }) => jsonContent({ results: await getAgentClient(as).search(query, { channel, from, limit }) }));
-    server.registerTool('check_inbox', {
-        title: 'Check Inbox',
-        description: 'Check unread messages, mentions, DMs, and reactions for the current agent.',
-        inputSchema: {
-            limit: z.number().optional().describe('Maximum inbox items'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: jsonResult,
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ limit, as }) => jsonContent(await getAgentClient(as).inbox(limit != null ? { limit } : undefined)));
-    server.registerTool('mark_message_read', {
-        title: 'Mark as Read',
-        description: 'Mark a message as read for the current agent.',
-        inputSchema: {
-            message_id: z.string().describe('Message ID'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: messageResult,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ message_id, as }) => {
-        await getAgentClient(as).markRead(message_id);
-        return textContent(`Marked message ${message_id} as read`);
-    });
-    server.registerTool('get_message_readers', {
-        title: 'Get Readers',
-        description: 'List agents who have read a message.',
-        inputSchema: {
-            message_id: z.string().describe('Message ID'),
-            ...identityOverrideInputShape,
-        },
-        outputSchema: {
-            readers: z.array(z.object({}).passthrough()).describe('Readers'),
-        },
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ message_id, as }) => jsonContent({ readers: await getAgentClient(as).readers(message_id) }));
+    registerMessagingTools(server, getAgentClient);
     server.registerTool('add_agent', {
         title: 'Add Agent',
         description: 'Spawn another AI agent (relay worker) to delegate a task to. This is how you ' +