JoinCloud

Instructions

Implementation Reference

• src/server/protocols/a2a/routes.ts:60-120 (handler)

  The `handleSendMessage` function acts as the main entry point for the `SendMessage` JSON-RPC method. It processes the request, resolves actions from the message metadata, and delegates execution to registered methods within the system.

  return async function handleSendMessage(
    params: SendMessageParams,
  ): Promise<A2AMessage | A2ATask> {
    const msg = params.message;
    const text = msg.parts.find((p) => p.text)?.text ?? "";
    let contextId = msg.contextId;
    const metadata = msg.metadata as Record<string, unknown> | undefined;
  
    const rawAction = metadata?.action as string | undefined;
    const action = rawAction ? (ACTION_ALIASES[rawAction] ?? rawAction) : undefined;
  
    // Resolve room name to ID for room.* methods
    if (contextId && action?.startsWith("room.") && action !== "room.create" && action !== "room.list") {
      const colonIdx = contextId.indexOf(":");
      if (colonIdx !== -1 && !metadata?.password) {
        if (metadata) {
          metadata.password = contextId.slice(colonIdx + 1);
        }
      }
      const room = await store.getRoom(contextId);
      if (room) contextId = room.id;
    }
  
    if (action && registry.hasMethod(action)) {
      const a2aAdapter = registry.getA2aAdapter(action);
      const methodParams = a2aAdapter?.mapParams
        ? a2aAdapter.mapParams({ text, contextId, metadata })
        : { ...metadata, ...(text && { text }), ...(contextId && { roomId: contextId }) };
  
      const ctx: MethodContext = {
        store,
        method: action,
        roomId: contextId,
        protocol: "a2a",
        protocolMeta: { contextId, metadata, text },
      };
  
      try {
        const result = await registry.call(action, methodParams, ctx);
        return toA2aResponse(result);
      } catch (e: any) {
        return errorMsg(e.message);
      }
    }
  
    if (action === "help") {
      const { generateDocs, generateStructuredDocs } = await import("../../website/docs.js");
      return reply(generateDocs(registry), undefined, { documentation: generateStructuredDocs(registry) });
    }
  
    if (action) {
      return errorMsg(`Unknown action: ${action}. Send metadata.action: "help" for full documentation.`);
    }
  
    // No action — default chat (send message if in room) or docs
    if (contextId && metadata?.agentToken) {
      if (registry.hasMethod("message.send")) {
        const a2aAdapter = registry.getA2aAdapter("message.send");
        const methodParams = a2aAdapter?.mapParams
          ? a2aAdapter.mapParams({ text, contextId, metadata })
          : { text, agentToken: metadata.agentToken, ...(metadata.to ? { to: metadata.to as string } : {}) };

• src/server/protocols/a2a/types.ts:92-99 (schema)

  The `SendMessageParams` interface defines the input structure expected by the `SendMessage` tool/method.

  export interface SendMessageParams {
    message: A2AMessage;
    configuration?: {
      acceptedOutputModes?: string[];
      returnImmediately?: boolean;
    };
    metadata?: Record<string, unknown>;
  }

• src/server/protocols/a2a/routes.ts:216-216 (registration)

  Registration of the "SendMessage" method description.

  { name: "SendMessage", description: "A2A standard — all Join.cloud operations go through this method via metadata.action" },