agent-relay 8.7.2 → 8.8.1

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

@@ -7,6 +7,7 @@ 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';
@@ -14,6 +15,11 @@ import { errorClassName } from './lib/telemetry-helpers.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;
+const EXIT_AFTER_TASK_INSTRUCTION = '## Post-task exit\n' +
+    'When the requested task is fully complete and you have reported the final outcome, output `/exit` on its own line so the Agent Relay harness exits cleanly. Do not output `/exit` before the task is complete.';
+function withExitAfterTaskInstruction(task) {
+    return `${task}\n\n${EXIT_AFTER_TASK_INSTRUCTION}`;
+}
 const DEFAULT_SYSTEM_PROMPT = `You are an AI agent in a collaborative workspace powered by Agent Relay. You can communicate with other agents using these MCP tools:
 
 ## Getting Started
@@ -30,6 +36,10 @@ const DEFAULT_SYSTEM_PROMPT = `You are an AI agent in a collaborative workspace
 - Reply to threads with "reply_to_thread"
 - React to messages with "add_reaction"
 
+## Fleet
+- Use "query_nodes" to find fleet nodes by capability or name
+- Use "spawn" to invoke the fleet spawn action on an eligible node
+
 ## Best Practices
 - Check your inbox regularly for new messages and mentions
 - Use channels for topic-based discussions
@@ -207,412 +217,95 @@ function createInitialSession(options) {
         wsInitAttempted: false,
     };
 }
-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;
+class SubscriptionManager {
+    subscriptions = new Set();
+    subscribe(uri) {
+        this.subscriptions.add(uri);
     }
-    if (!isSchemaObject(schema) || schema.type !== 'object') {
-        return {
-            input: z.unknown().describe('Action input payload. The action registry performs final validation.'),
-        };
+    unsubscribe(uri) {
+        this.subscriptions.delete(uri);
     }
-    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();
+    getMatchingSubscriptions(uris) {
+        return uris.filter((uri) => this.subscriptions.has(uri));
     }
-    return shape;
-}
-function actionInvocationInput(descriptor, args) {
-    const schema = descriptor.inputSchema;
-    if (zodObjectShape(schema)) {
-        return args;
+    getAll() {
+        return [...this.subscriptions];
     }
-    if (!isSchemaObject(schema) || schema.type !== 'object') {
-        return typeof args === 'object' && args !== null && 'input' in args
-            ? args.input
-            : args;
+    clear() {
+        this.subscriptions.clear();
     }
-    return args;
 }
-function zodObjectShape(schema) {
-    if (schema instanceof z.ZodObject) {
-        return schema.shape;
+function getStringEventField(event, field) {
+    if (typeof event !== 'object' || event === null) {
+        return null;
     }
-    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) } : {}),
-    };
+    const candidate = event[field];
+    return typeof candidate === 'string' ? candidate : null;
 }
-function serializableActionSchema(schema) {
-    if (isSchemaObject(schema)) {
-        return schema;
-    }
-    if (isZodLikeSchema(schema)) {
-        return {
-            type: 'zod',
-            ...(schema.description ? { description: schema.description } : {}),
-        };
+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 [];
     }
-    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;
+class RealtimeResourceBridge {
+    wsClient;
+    subscriptions;
+    notifyCallback;
+    unsubscribeFn = null;
+    constructor(wsClient, subscriptions, notifyCallback) {
+        this.wsClient = wsClient;
+        this.subscriptions = subscriptions;
+        this.notifyCallback = notifyCallback;
     }
-    /**
-     * 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 });
+    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;
             }
-            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 };
-}
-export async function registerAgentWithRebind({ session, setSession, getRelay, name, type, persona, metadata, strictAgentName, preferredAgentName, forcedAgentType, }) {
-    requireWorkspaceKey(session);
-    const configuredName = session.agentName ?? preferredAgentName?.trim() ?? null;
-    const warnings = [];
-    const effectiveName = strictAgentName && configuredName ? configuredName : name;
-    if (strictAgentName && configuredName && name.trim() !== configuredName) {
-        warnings.push(`Strict worker identity is enabled; ignoring requested name "${name}" and using "${configuredName}".`);
-    }
-    const effectiveType = forcedAgentType ?? type;
-    if (forcedAgentType && type && type !== forcedAgentType) {
-        warnings.push(`Forced worker type is enabled; ignoring requested type "${type}" and using "${forcedAgentType}".`);
-    }
-    if (session.agentToken && effectiveName && strictAgentName) {
-        // If the session tracks per-identity agents, only short-circuit when the
-        // strict-named identity is still registered. After an `agent_token_invalid`
-        // recovery the entry is dropped from the map, which lets this fall through
-        // to a fresh registerOrRotate instead of handing back the dead token.
-        const cachedAgent = session.agents?.get(effectiveName);
-        const knowsIdentities = session.agents !== undefined;
-        if (!knowsIdentities || cachedAgent) {
-            return {
-                name: effectiveName,
-                token: cachedAgent?.agentToken ?? session.agentToken,
-                registered_name: effectiveName,
-                warnings,
-            };
-        }
-    }
-    const relay = getRelay();
-    const result = await relay.agents.registerOrRotate({
-        name: effectiveName,
-        type: effectiveType,
-        persona,
-        metadata,
-    });
-    const reboundName = result.name?.trim() ? result.name : effectiveName;
-    setSession({ agentToken: result.token, agentName: reboundName });
-    return {
-        ...result,
-        registered_name: reboundName,
-        warnings,
-    };
-}
-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': {
-            const channel = getStringEventField(event, 'channel');
-            return channel ? [`relay://channels/${channel}/messages`] : [];
-        }
-        case 'action.invoked':
-        case 'action.completed':
-        case 'action.failed':
-            // Actions are not channel-scoped; surface invocations via the inbox.
-            return ['relay://inbox'];
-        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);
+            const matched = this.subscriptions.getMatchingSubscriptions(eventToResourceUris(event));
+            for (const uri of matched) {
+                this.notifyCallback(uri);
             }
         });
         this.wsClient.connect();
@@ -692,217 +385,506 @@ function formatInbox(inbox, selfName) {
             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}`);
-        }
+    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;
     }
-    return lines.length === 1 ? '' : lines.join('\n');
-}
-function readAsIdentity(args) {
-    const [input] = args;
-    if (typeof input !== 'object' || input === null)
+    catch {
         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,
-    };
+    }
 }
-const AGENT_RELAY_TOOL_CALL_METADATA = {
-    add_agent: { toolType: 'agent.create', toolCategory: 'spawn' },
-    remove_agent: { toolType: 'agent.release', toolCategory: 'release' },
-    invoke_action: { toolType: 'action.invoke', toolCategory: 'action' },
-    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' },
-    get_message: { toolType: 'message.get', toolCategory: 'message' },
-    reply_to_thread: { toolType: 'message.reply', toolCategory: 'message' },
-    get_message_thread: { toolType: 'message.thread', toolCategory: 'message' },
-    get_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' },
-    list_channel_members: { toolType: 'channel.member_list', 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 readInvokedActionName(name, args) {
-    if (name !== 'invoke_action') {
+function asInputRecord(input) {
+    if (input === undefined || input === null) {
         return undefined;
     }
-    const [input] = args;
-    if (!input || typeof input !== 'object') {
-        return undefined;
+    if (typeof input === 'object' && !Array.isArray(input)) {
+        return input;
     }
-    const actionName = input.name;
-    return typeof actionName === 'string' && actionName.trim() ? actionName : undefined;
+    return { input };
 }
-function agentRelayActionNameCategory(name) {
-    const leaf = name.split(/[._-]/).filter(Boolean).at(-1)?.toLowerCase();
-    switch (leaf) {
-        case 'create':
-        case 'spawn':
-        case 'attach':
-            return 'spawn';
-        case 'release':
-            return 'release';
-        case 'status':
-            return 'agent';
-        default:
-            return 'action';
-    }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-function agentRelayToolCallMetadata(name, args, actionToolNames) {
-    const invokedActionName = readInvokedActionName(name, args);
-    if (invokedActionName) {
-        return {
-            toolType: invokedActionName,
-            toolCategory: agentRelayActionNameCategory(invokedActionName),
-        };
+function createRegisteredAgent(agentName, agentToken) {
+    return { agentName, agentToken };
+}
+export async function registerAgentWithRebind({ session, setSession, getRelay, name, type, persona, metadata, strictAgentName, preferredAgentName, forcedAgentType, }) {
+    requireWorkspaceKey(session);
+    const configuredName = session.agentName ?? preferredAgentName?.trim() ?? null;
+    const warnings = [];
+    const effectiveName = strictAgentName && configuredName ? configuredName : name;
+    if (strictAgentName && configuredName && name.trim() !== configuredName) {
+        warnings.push(`Strict worker identity is enabled; ignoring requested name "${name}" and using "${configuredName}".`);
     }
-    const known = AGENT_RELAY_TOOL_CALL_METADATA[name];
-    if (known) {
-        return known;
+    const effectiveType = forcedAgentType ?? type;
+    if (forcedAgentType && type && type !== forcedAgentType) {
+        warnings.push(`Forced worker type is enabled; ignoring requested type "${type}" and using "${forcedAgentType}".`);
     }
-    if (actionToolNames.has(name)) {
-        return {
-            toolType: name,
-            toolCategory: agentRelayActionNameCategory(name),
-        };
+    if (session.agentToken && effectiveName && strictAgentName) {
+        // If the session tracks per-identity agents, only short-circuit when the
+        // strict-named identity is still registered. After an `agent_token_invalid`
+        // recovery the entry is dropped from the map, which lets this fall through
+        // to a fresh registerOrRotate instead of handing back the dead token.
+        const cachedAgent = session.agents?.get(effectiveName);
+        const knowsIdentities = session.agents !== undefined;
+        if (!knowsIdentities || cachedAgent) {
+            return {
+                name: effectiveName,
+                token: cachedAgent?.agentToken ?? session.agentToken,
+                registered_name: effectiveName,
+                warnings,
+            };
+        }
     }
-    return { toolType: name, toolCategory: 'tool' };
-}
-function isErrorToolResult(value) {
-    return Boolean(value && typeof value === 'object' && value.isError === true);
-}
-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 } : {}),
+    const relay = getRelay();
+    const result = await relay.agents.registerOrRotate({
+        name: effectiveName,
+        type: effectiveType,
+        persona,
+        metadata,
     });
-}
-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();
-            const toolMetadata = agentRelayToolCallMetadata(name, args, actionToolNames);
-            let result;
-            try {
-                result = await handler(...args);
-            }
-            catch (err) {
-                // `register_agent` is the recovery path itself — never invalidate a
-                // freshly-issued token, and let registration errors bubble normally.
-                if (name !== 'register_agent' && isInvalidAgentTokenError(err)) {
-                    invalidateAgentToken(asIdentity);
-                    trackAgentRelayToolCall({
-                        toolName: name,
-                        toolType: toolMetadata.toolType,
-                        toolCategory: toolMetadata.toolCategory,
-                        transport: telemetryTransport,
-                        startedAt,
-                        success: false,
-                        errorClass: errorClassName(err) ?? 'InvalidAgentToken',
-                    });
-                    return invalidAgentTokenToolResult();
-                }
-                trackAgentRelayToolCall({
-                    toolName: name,
-                    toolType: toolMetadata.toolType,
-                    toolCategory: toolMetadata.toolCategory,
-                    transport: telemetryTransport,
-                    startedAt,
-                    success: false,
-                    errorClass: errorClassName(err),
-                });
-                throw err;
-            }
-            // Successful response that still carries an "Invalid agent token" body.
-            if (name !== 'register_agent' && isInvalidAgentTokenToolResult(result)) {
-                invalidateAgentToken(asIdentity);
-                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) {
-                    // Inbox piggyback is opportunistic; the original tool result should
-                    // still win. But if the inbox fetch itself reveals an invalid token,
-                    // clear the stale identity so the next call doesn't reuse it.
-                    if (isInvalidAgentTokenError(err)) {
-                        invalidateAgentToken(asIdentity);
-                    }
-                }
-            }
-            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);
+    const reboundName = result.name?.trim() ? result.name : effectiveName;
+    setSession({ agentToken: result.token, agentName: reboundName });
+    return {
+        ...result,
+        registered_name: reboundName,
+        warnings,
     };
 }
 function resolveEmoji(input) {
@@ -1047,6 +1029,23 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
         const agents = await getRelay().agents.list(status ? { status } : undefined);
         return jsonContent({ agents });
     });
+    server.registerTool('query_nodes', {
+        title: 'Query Fleet Nodes',
+        description: 'Query registered fleet nodes by capability or name.',
+        inputSchema: {
+            capability: z.string().optional().describe('Optional capability name filter'),
+            name: z.string().optional().describe('Optional node name filter'),
+        },
+        outputSchema: {
+            nodes: z.array(z.object({}).passthrough()).describe('Fleet nodes'),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ capability, name }) => {
+        const session = getSession();
+        requireWorkspaceKey(session);
+        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.',
@@ -1338,27 +1337,94 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
     }, async ({ message_id, as }) => jsonContent({ readers: await getAgentClient(as).readers(message_id) }));
     server.registerTool('add_agent', {
         title: 'Add Agent',
-        description: 'Ask Relaycast to spawn a worker agent for a task.',
+        description: 'Spawn another AI agent (relay worker) to delegate a task to. This is how you ' +
+            'create workers — including non-Claude ones. Use it for any "spawn a <tool> agent" request. ' +
+            'Examples: "spawn a codex agent" → cli:"codex"; ' +
+            '"spawn an opus claude agent" → cli:"claude", model:"claude-opus-4-8"; ' +
+            '"spawn a sonnet claude agent" → cli:"claude", model:"claude-sonnet-4-6". ' +
+            'Do NOT use the built-in Agent/Task tool for relay workers.',
         inputSchema: {
             name: z.string().describe('Worker agent name'),
-            cli: z.enum(['claude', 'codex', 'gemini', 'aider', 'goose']).describe('AI CLI to launch'),
+            cli: z
+                .enum(['claude', 'codex', 'gemini', 'aider', 'goose', 'grok', 'opencode'])
+                .describe('Which AI CLI runs the worker: "codex agent" → codex, "gemini agent" → gemini, ' +
+                '"claude/opus claude/sonnet claude agent" → claude (default).'),
             task: z.string().describe('Task instructions'),
             channel: z.string().optional().describe('Channel to join'),
             persona: z.string().optional().describe('Worker persona'),
-            model: z.string().optional().describe('Model powering the worker'),
+            model: z
+                .string()
+                .optional()
+                .describe('Model to pin (Claude only). Required when a tier is specified: ' +
+                '"opus claude" → claude-opus-4-8, "sonnet claude" → claude-sonnet-4-6, ' +
+                '"haiku" → claude-haiku-4-5-20251001.'),
+            spawn_mode: z
+                .enum(['interactive', 'task_exit', 'task-exit', 'single_shot', 'single-shot'])
+                .optional()
+                .describe('Spawn lifecycle. Use task_exit to exit after the injected task completes.'),
+            exit_after_task: z
+                .boolean()
+                .optional()
+                .describe('Exit the worker after it completes the injected task.'),
         },
         outputSchema: jsonResult,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ name, cli, task, channel, persona, model }) => jsonContent(await getRelay().agents.spawn({
+    }, async ({ name, cli, task, channel, persona, model, spawn_mode, exit_after_task }) => jsonContent(await getRelay().agents.spawn({
         name,
-        cli,
-        task,
+        // The broker/gateway support grok and opencode at runtime, but the
+        // @relaycast/sdk SpawnAgentRequest type narrows cli to the core five.
+        // Cast to keep grok/opencode selectable from the MCP tool enum.
+        cli: cli,
+        task: exit_after_task ||
+            spawn_mode === 'task_exit' ||
+            spawn_mode === 'task-exit' ||
+            spawn_mode === 'single_shot' ||
+            spawn_mode === 'single-shot'
+            ? withExitAfterTaskInstruction(task)
+            : task,
         channel,
         persona,
-        // Pass model as a first-class spawn field so it reaches the broker and
-        // the launched CLI (--model), not just the agent's display metadata.
-        model: model ?? undefined,
+        // SpawnAgentRequest has no top-level model field; pass via metadata
+        // so the broker can extract it and forward --model to the launched CLI.
+        metadata: model ? { model } : undefined,
     })));
+    server.registerTool('spawn', {
+        title: 'Spawn Agent',
+        description: 'Invoke the fleet spawn action. Optionally target a specific node.',
+        inputSchema: {
+            name: z.string().describe('Agent name'),
+            cli: z.enum(['claude', 'codex', 'gemini', 'aider', 'goose']).describe('AI CLI to launch'),
+            task: z.string().optional().describe('Initial task instructions'),
+            channel: z.string().optional().describe('Channel to join'),
+            channels: z.array(z.string()).optional().describe('Channels to join'),
+            model: z.string().optional().describe('Model powering the worker'),
+            session_ref: z.string().optional().describe('Session reference for resumable spawns'),
+            target_node: z.string().optional().describe('Optional target fleet node name'),
+            ...identityOverrideInputShape,
+        },
+        outputSchema: jsonResult,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ name, cli, task, channel, channels, model, session_ref, target_node, as }) => {
+        const actions = getAgentClient(as).actions;
+        if (!actions) {
+            throw new Error('spawn requires an agent-scoped Relaycast actions client.');
+        }
+        const actionInput = {
+            name,
+            cli,
+            ...(task ? { task } : {}),
+            ...(model ? { model } : {}),
+            ...(session_ref ? { session_ref } : {}),
+            ...(target_node ? { target_node } : {}),
+            ...((channels ?? (channel ? [channel] : undefined)) ? { channels: channels ?? [channel] } : {}),
+        };
+        return jsonContent({ invocation: await actions.invoke('spawn', actionInput) });
+    });
     server.registerTool('remove_agent', {
         title: 'Remove Agent',
         description: 'Release a worker agent from active duty.',
@@ -1430,10 +1496,10 @@ export function createAgentRelayMcpServer(options) {
         if (session.agentToken && !session.wsBridge && !session.wsInitAttempted) {
             try {
                 const subscriptions = new SubscriptionManager();
-                const wsClient = new WsClient(withRelaycastTelemetry({
+                const wsClient = new WsClient({
                     token: session.agentToken,
                     baseUrl: options.baseUrl,
-                }));
+                });
                 const wsBridge = new RealtimeResourceBridge(wsClient, subscriptions, (uri) => {
                     mcpServer.server.sendResourceUpdated({ uri }).catch(() => undefined);
                 });
@@ -1457,9 +1523,6 @@ export function createAgentRelayMcpServer(options) {
             nextAgents.delete(targetName);
             partial.agents = nextAgents;
         }
-        // Clear the active-session token when the invalidated identity is the
-        // active one (or the caller didn't pin to a particular identity). The
-        // active workspaceKey stays intact so `register_agent` can recover.
         if (!asIdentity || asIdentity === session.agentName) {
             if (session.agentToken !== null) {
                 partial.agentToken = null;
@@ -1536,9 +1599,6 @@ export function createAgentRelayMcpServer(options) {
             return result;
         });
     }
-    if (session.agentToken && !session.wsBridge) {
-        setSession({ agentToken: session.agentToken, agentName: session.agentName });
-    }
     return mcpServer;
 }
 /** Relaycast agent tokens are opaque `at_live_<hex>` literals. Anything else