MCP Fusion 5.0.10: descrições menores, erros lançados recuperados

Lançada em 17 de setembro de 2026, a 5.0.10 é um release de manutenção, e todo o código que mudou vive dentro do @mcpfusion/core; as notas do release confirmam que os outros 15 pacotes do workspace seguem buildando limpos, intocados (notas do release · MCP Fusion no GitHub). Dois defeitos P2 e uma queda latente compõem o release. Os três importam, e os três só se observam de onde o modelo de linguagem está.

Bug 152: o resumo, dito 1 + N vezes

Sob o toolExposition: 'grouped', a ferramenta expõe um nome com um campo discriminante action em vez de N ferramentas planas, e a descrição é em camadas. A camada 1 abre com o resumo da ferramenta, a lista de módulos/ações e a instrução de despacho; a camada 2 leva uma linha por ação: o bloco Workflow: no markdown, a coluna desc: no TOON. Quando o builder define um .description() mas as ações individuais não têm, o resumo da ferramenta é herdado por cada ação (correto, a exposição plana se apoia nesse fallback), e era então ecoado uma vez por ação na camada 2. O modelo via o resumo 1 + N vezes, sem nenhuma informação nova depois da primeira. Descrição redundante não é só inflar o prompt; ela dilui justamente o sinal que o modelo deveria pesar. A correção trata uma descrição igual ao resumo da ferramenta como "não específica da ação" e a omite da camada 2; descrições específicas de ação passam intactas.

Bug 153: o hint que o validador rejeitava

O hint "quais campos eu preciso passar", a linha Requires:, era calculado só do schema por ação. Ele nunca olhava o commonSchema do nível da ferramenta e não aplicava omitCommonFields. A consequência na prática: um workspace_id obrigatório declarado via .commonSchema() aparecia em inputSchema.required, mas não no hint. O modelo omitia o campo, a validação rejeitava a chamada, o agente lia o erro, chamava de novo com o campo que faltava, e acertava. Um rebote de auto-cura desnecessário, pago em toda chamada agrupada que compartilhava campo comum. A correção faz o getActionRequiredFields() refletir o mesmo schema fundido que o buildValidationSchema() aplica, com omitCommonFields incluído, o hint e o validador deixam de poder divergir.

O parâmetro commonSchema adicionado a getActionRequiredFields / generateDescription / generateToonDescription é opcional, o que mantém a mudança visível no wire mas não quebrante: nada de API, tipo ou forma de schema mudou; a saída da exposição plana é byte a byte idêntica, e descrições agrupadas só encolhem. A consequência operacional única: o integrityDigest do mcpfusion.lock muda para servidores agrupados que tinham descrições herdadas; regere o lockfile.

O catch que engolia o significado

O idiom que o framework ensina é classificar falhas, não só lançá-las: handlers e middlewares podem throw uma resposta já classificada (throw toolError('NOT_FOUND', {...}), throw error('Unauthorized')) em vez de devolvê-la. O bloco catch do runChain() reconhecia uma ToolResponse simples e nada mais, então uma resposta lançada chegava sem o código de erro, sem o guia de recuperação e sem a severidade de aviso-contra-erro, e saía reempacotada como um INTERNAL_ERROR genérico.

Duas formas eram piores que mero "perdido". Um HandoffResponse lançado carrega a marca de resposta de ferramenta, mas não tem array content; a checagem só de isToolResponse() o encaminhava para código que indexa content, uma queda no caminho de handoff federado. Um ResponseBuilder lançado era descartado em vez de montado, perdendo todos os blocos de conteúdo compostos. O catch agora espelha a ordem do postProcessResult() (isHandoffResponse → isResponseBuilder → isToolResponse), e só o resíduo genuinamente inesperado vira INTERNAL_ERROR.

O que mais pesa na fronteira do modelo: esse fallback não afirma mais que a falha é transitória. Uma falha permanente (id ruim, recurso ausente, auth vencida) de outro modo mandaria o agente para um loop de retry com parâmetros idênticos. O novo erro reporta a origem [ferramenta/ação] e diz ao modelo para inspecionar a mensagem em vez de retry de olhos fechados, a diferença entre um agente que escala e um que martela a mesma chamada até o timeout.

Fixado e embarcado

• DescriptionInheritance-bug152-153.test.ts (18 casos) e ThrownResponseRecovery.test.ts (12 casos) fixam os dois comportamentos, segundo as notas do release.
• Suíte completa do core: 5.243 passando, 0 falhando; tsc --noEmit limpo; os 16 pacotes do workspace buildam.

Instalar é uma linha:

npm install @mcpfusion/core@5.0.10

Roda exposição agrupada? Regere seu mcpfusion.lock para o integrityDigest conferir com a descrição (agora menor), e nada mais muda no código dos seus handlers; o idiom de lançar resposta classificada passa a funcionar do jeito que a doc sempre disse que funcionaria.