agent-relay 8.7.1 → 8.8.0

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

@@ -7,10 +7,10 @@ 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 { initTelemetry, shutdown as shutdownTelemetry } from './telemetry/index.js';
 import { relaycastWorkspaceTelemetryOptions, withRelaycastTelemetry } from './lib/relaycast-telemetry.js';
-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;
@@ -30,6 +30,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,319 +211,6 @@ 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;
-    }
-    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 };
-}
-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) {
@@ -574,15 +265,11 @@ function eventToResourceUris(event) {
         case 'member.joined':
         case 'member.left':
             return ['relay://channels'];
-        case 'webhook.received': {
+        case 'webhook.received':
+        case 'command.invoked': {
             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'];
@@ -701,208 +388,383 @@ function formatInbox(inbox, selfName) {
             lines.push(`  :${reaction.emoji}: on your message in #${reaction.channelName} by @${reaction.agentName}`);
         }
     }
-    return lines.length === 1 ? '' : lines.join('\n');
+    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 enableInboxPiggyback(mcpServer, getSession, getAgentClient, invalidateAgentToken) {
+    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);
+            let result;
+            try {
+                result = await handler(...args);
+            }
+            catch (err) {
+                if (name !== 'register_agent' && isInvalidAgentTokenError(err)) {
+                    invalidateAgentToken(asIdentity);
+                    return invalidAgentTokenToolResult();
+                }
+                throw err;
+            }
+            if (name !== 'register_agent' && isInvalidAgentTokenToolResult(result)) {
+                invalidateAgentToken(asIdentity);
+                if (hasContentArray(result)) {
+                    result.content.push({ type: 'text', text: agentTokenRecoveryMessage() });
+                }
+                return result;
+            }
+            if (SKIP_PIGGYBACK.has(name) || !getSession().agentToken || !hasContentArray(result)) {
+                return 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);
+                }
+            }
+            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 readAsIdentity(args) {
-    const [input] = args;
-    if (typeof input !== 'object' || input === null)
-        return undefined;
-    const as = input.as;
-    return typeof as === 'string' ? as : undefined;
+function zodObjectShape(schema) {
+    if (schema instanceof z.ZodObject) {
+        return schema.shape;
+    }
+    return undefined;
 }
-function invalidAgentTokenToolResult() {
-    const text = agentTokenRecoveryMessage();
+function serializableActionDescriptor(descriptor) {
     return {
-        content: [{ type: 'text', text }],
-        structuredContent: {
-            error: { code: INVALID_AGENT_TOKEN_CODE, message: text },
-        },
-        isError: true,
+        name: descriptor.name,
+        description: descriptor.description,
+        visibility: descriptor.visibility,
+        ...(descriptor.inputSchema ? { inputSchema: serializableActionSchema(descriptor.inputSchema) } : {}),
+        ...(descriptor.outputSchema ? { outputSchema: serializableActionSchema(descriptor.outputSchema) } : {}),
     };
 }
-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') {
-        return undefined;
+function serializableActionSchema(schema) {
+    if (isSchemaObject(schema)) {
+        return schema;
     }
-    const [input] = args;
-    if (!input || typeof input !== 'object') {
-        return undefined;
+    if (isZodLikeSchema(schema)) {
+        return {
+            type: 'zod',
+            ...(schema.description ? { description: schema.description } : {}),
+        };
     }
-    const actionName = input.name;
-    return typeof actionName === 'string' && actionName.trim() ? actionName : undefined;
+    return schema;
 }
-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 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);
 }
-function agentRelayToolCallMetadata(name, args, actionToolNames) {
-    const invokedActionName = readInvokedActionName(name, args);
-    if (invokedActionName) {
-        return {
-            toolType: invokedActionName,
-            toolCategory: agentRelayActionNameCategory(invokedActionName),
-        };
+/** The relay-backed action surface on the live agent client, when available. */
+function getRelayAgentActions(getAgentClient) {
+    if (!getAgentClient) {
+        return undefined;
+    }
+    try {
+        return getAgentClient().actions;
     }
-    const known = AGENT_RELAY_TOOL_CALL_METADATA[name];
-    if (known) {
-        return known;
+    catch {
+        return undefined;
     }
-    if (actionToolNames.has(name)) {
-        return {
-            toolType: name,
-            toolCategory: agentRelayActionNameCategory(name),
-        };
+}
+function asInputRecord(input) {
+    if (input === undefined || input === null) {
+        return undefined;
+    }
+    if (typeof input === 'object' && !Array.isArray(input)) {
+        return input;
     }
-    return { toolType: name, toolCategory: 'tool' };
+    return { input };
 }
-function isErrorToolResult(value) {
-    return Boolean(value && typeof value === 'object' && value.isError === true);
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-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 createRegisteredAgent(agentName, agentToken) {
+    return { agentName, agentToken };
 }
-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);
+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 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 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,
     };
 }
 function resolveEmoji(input) {
@@ -1047,6 +909,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.',
@@ -1355,10 +1234,47 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
         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 +1346,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 +1373,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;
@@ -1492,7 +1405,7 @@ export function createAgentRelayMcpServer(options) {
             baseUrl: options.baseUrl,
         })).as(agentToken, { autoHeartbeatMs: false });
     };
-    enableInboxPiggyback(mcpServer, getSession, getAgentClient, invalidateAgentToken, options.telemetryTransport, actionToolNames);
+    enableInboxPiggyback(mcpServer, getSession, getAgentClient, invalidateAgentToken);
     registerResourceDefinitions(mcpServer, getAgentClient, getRelay);
     mcpServer.server.setRequestHandler(SubscribeRequestSchema, async (req) => {
         session.subscriptions?.subscribe(req.params.uri);
@@ -1536,9 +1449,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