@sbissoli/mcp-evals 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# @sbissoli/mcp-evals
+
+Harness de evals de **seleção de tool** para servidores MCP: mede a acurácia com que um
+modelo escolhe a tool certa do catálogo, dada uma consulta realista na persona do
+usuário-alvo do servidor. Generalização do harness do senado-br-mcp-cloudflare
+(`evals/`), promovido a componente do portfólio na Fase 0 (Entregável 5).
+
+O núcleo (extrator de catálogo + validação de fixtures + scorer + gate) roda **offline em
+`npm test`**, sem rede e sem modelo — renomear/remover uma tool quebra o teste de
+fixtures do projeto imediatamente, de graça. A rodada cara (modelo real via Anthropic
+Messages API) só é necessária quando você quer o número de acurácia em si.
+
+> **Custo**: o runner com modelo real cobra uso de API separado de qualquer assinatura
+> Claude. Nunca rode `evals/run.ts` com `ANTHROPIC_API_KEY` sem decisão explícita.
+
+## Módulos
+
+| Módulo | Papel |
+|---|---|
+| `catalog` | **Extrator de catálogo.** `CapturingServer` (fake McpServer) grava cada registro de tool ao rodar os `registerXTools` do servidor — sem rede, sem runtime de Worker. Captura as duas formas do portfólio: `server.tool(name, desc, shape, cb)` (senado) e `server.registerTool(name, {description, inputSchema}, cb)` (template Cloudflare / SDK v2). Converte zod → JSON-schema via `z.toJSONSchema` nativo (modo `io: "input"`: campo com `.default()` não é required). |
+| `fixtures` | Contrato `EvalFixture` + `validateFixtures(fixtures, catalog, opts)`: contagem mínima/máxima, ids e queries únicos, `expectedTools` não-vazio e existente no catálogo, cobertura mínima de áreas. O teste de fixtures de um projeto vira `expect(validateFixtures(...)).toEqual([])`. |
+| `score` | **Scorer puro.** top-1 / top-k / por-área + gate parametrizável (`evaluateGate`, limiares padrão 85%/90%). |
+| `retry` | Classificação de erro da API (transitório × fatal) + backoff com Retry-After. Dropout de infra nunca é pontuado como escolha errada. |
+| `report` | Formatação pura do relatório (linhas + exit code): cobertura, acurácias, erros por kind, gate — marcado PRELIMINAR quando a rodada é incompleta. |
+| `runner` | `runEval(config)`: manda cada fixture + o catálogo inteiro à Messages API com `tool_choice: any`, com concorrência limitada, retry e curto-circuito em falha fatal (auth/billing). Sem `ANTHROPIC_API_KEY`, imprime instruções e devolve exit 0 — nunca quebra CI. `fetch` puro, sem SDK. |
+
+## Instanciando num projeto
+
+```
+meu-servidor/
+  evals/
+    catalog.ts     # GROUPS do projeto → buildCatalog(GROUPS)
+    fixtures/queries.ts
+    run.ts
+  tests/evals/
+    fixtures.test.ts
+```
+
+`evals/catalog.ts` — a única parte específica do servidor é a lista de grupos:
+
+```ts
+import { buildCatalog, type CatalogGroup } from "@sbissoli/mcp-evals";
+import { registerFooTools } from "../src/tools/foo.js";
+
+const GROUPS: CatalogGroup[] = [
+  { area: "foo", register: (s) => registerFooTools(s as never, BASE_URL) },
+  // ... um por grupo de src/server.ts — grupo faltando encolhe o eval em silêncio
+];
+
+export const CATALOG = buildCatalog(GROUPS);
+```
+
+`tests/evals/fixtures.test.ts` — o sinal offline de regressão:
+
+```ts
+import { validateFixtures } from "@sbissoli/mcp-evals";
+import { CATALOG } from "../../evals/catalog.js";
+import { FIXTURES } from "../../evals/fixtures/queries.js";
+
+it("fixtures válidas contra o catálogo vivo", () => {
+  expect(validateFixtures(FIXTURES, CATALOG, { minFixtures: 30, maxFixtures: 50, minAreas: 12 }))
+    .toEqual([]);
+});
+```
+
+`evals/run.ts` — a rodada com modelo real:
+
+```ts
+import { runEval } from "@sbissoli/mcp-evals";
+import { CATALOG } from "./catalog.js";
+import { FIXTURES } from "./fixtures/queries.js";
+
+const { exitCode } = await runEval({
+  catalog: CATALOG,
+  fixtures: FIXTURES,
+  systemPrompt: "Você é o roteador de ferramentas do MCP <nome>. ... apenas chame a ferramenta.",
+});
+process.exit(exitCode);
+```
+
+Variáveis de ambiente do runner (opcionais): `EVAL_MODEL` (padrão `claude-opus-4-8`),
+`EVAL_CONCURRENCY` (padrão 4), `EVAL_LIMIT` (smoke com as N primeiras fixtures).
+
+## Gate
+
+A partir da acurácia **top-1** (`evaluateGate`, limiares configuráveis por servidor):
+
+| Acurácia top-1 | Decisão | Recomendação |
+|---|---|---|
+| `< 85%` | `remediar` | Abrir sessão de remediação (deferred loading / Code Mode / agrupamento). |
+| `85%–90%` | `zona-cinzenta` | Manter sob observação; reavaliar após a próxima mudança de tool/descrição. |
+| `>= 90%` | `despriorizar-refatoracao` | Despriorizar refatoração de catálogo; seguir consolidando via enums. |
+
+Exit codes do runner: `0` = rodada completa (gate autoritativo) ou pulada sem API key;
+`2` = uma ou mais fixtures não chegaram ao modelo (gate PRELIMINAR — não usar para
+decisão).
+
+## Migração do harness do senado (adoção na Fase 1)
+
+A adoção troca imports sem mudar comportamento — as mensagens de gate são reproduzidas
+byte-a-byte (teste de compatibilidade em `tests/score.test.ts`). Mapa:
+
+| senado `evals/*` | `@sbissoli/mcp-evals` |
+|---|---|
+| `buildCatalog()` (sem args, memoizado, GROUPS embutido) | `buildCatalog(GROUPS)` — GROUPS fica no projeto; memoize no módulo do projeto (`export const CATALOG = buildCatalog(GROUPS)`) |
+| `catalogToolNames()` / `catalogAreaByName()` | `CATALOG.toolNames` / `CATALOG.areaByName` |
+| `catalogAsAnthropicTools()` | `catalogAsAnthropicTools(CATALOG)` |
+| invariantes de `tests/evals/fixtures.test.ts` | `validateFixtures(FIXTURES, CATALOG, { minFixtures: 30, maxFixtures: 50, minAreas: 12 })` (os testes de contagem exata do catálogo e prefixo `senado_` permanecem no projeto) |
+| `evaluateGate(acc)` (mensagem cita "67 tools") | `evaluateGate(acc, { toolCount: 67 })` — o runner preenche `toolCount` do catálogo automaticamente |
+| `run.ts` inteiro (main/printReport/retry loop) | `runEval({ catalog, fixtures, systemPrompt })` — mesmo protocolo (`tool_choice: any`), mesmas env vars, mesmos exit codes |
+| `retry.ts` / `score.ts` | idênticos (portados; `EvalApiError.retryAfterSeconds` virou campo declarado) |
+
+Duas camadas de eval (ver FASE0_PROMPT_SESSAO.md): este pacote mede **seleção de tool**;
+a camada de **completude de tarefa** (o modelo responde certo usando as tools?) é coberta
+pelo `evaluation.py` do mcp-builder (assets em `fase0-insumos/mcp-builder-evaluation/`)
+e/ou MCPJam Inspector — complementares, não substitutos.
+
+## Desenvolvimento
+
+```bash
+npm run typecheck
+npm test        # 61 testes offline (catálogo, fixtures, scorer, retry, report, runner com fetch injetado)
+npm run build
+```
+
+Dependências: `zod` ^4 como peer (para `z.toJSONSchema` no extrator); nada mais.

package/dist/catalog.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Extrator de catálogo — a fonte de verdade do harness.
+ *
+ * Nunca toca a rede. Um "fake McpServer" (`CapturingServer`) grava cada registro de tool
+ * feito pelos `registerXTools` do servidor, exatamente como o `server.ts` real os liga.
+ * O resultado é a lista viva de tools (nome, descrição, JSON-schema do input) contra a
+ * qual as fixtures são validadas — renomear/remover uma tool quebra o teste offline
+ * imediatamente, sem rede e sem modelo.
+ *
+ * Duas formas de registro são capturadas, cobrindo os dois padrões do portfólio:
+ *   - `server.tool(name, description, shape, cb)` — forma clássica (shape zod cru);
+ *   - `server.registerTool(name, { description, inputSchema }, cb)` — forma SDK v2
+ *     (inputSchema pode ser um `z.object(...)` pronto ou um shape cru).
+ *
+ * Os callbacks das tools (que tocariam upstream/cache/bindings) são capturados mas nunca
+ * invocados — por isso nenhum runtime de Worker é necessário.
+ */
+import { type ZodTypeAny } from "zod";
+/** JSON-schema mínimo (subconjunto do draft 2020-12) descrevendo o input de uma tool. */
+export interface JsonSchema {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+    additionalProperties: false;
+}
+export interface CatalogTool {
+    name: string;
+    description: string;
+    /** Área funcional grossa, herdada do grupo que registrou a tool. */
+    area: string;
+    /** Visão JSON-schema do shape zod de input (para a definição de tool do modelo). */
+    inputSchema: JsonSchema;
+}
+export type ZodShape = Record<string, ZodTypeAny>;
+/** O que a captura aceita como "shape": shape cru, schema zod pronto, ou nada. */
+export type CapturedShape = ZodShape | ZodTypeAny | undefined;
+/**
+ * Fake McpServer que só grava registros de tool. Passe-o (com cast, ex.: `as never`)
+ * aos `registerXTools` do servidor real; nada além de `.tool`/`.registerTool` é chamado
+ * em tempo de registro nos servidores do portfólio.
+ */
+export declare class CapturingServer {
+    readonly captured: {
+        name: string;
+        description: string;
+        shape: CapturedShape;
+    }[];
+    /** Forma clássica: `server.tool(name, description, shape, cb)`. */
+    tool(name: string, description: string, shape?: unknown, _cb?: unknown): void;
+    /** Forma SDK v2: `server.registerTool(name, { description, inputSchema }, cb)`. */
+    registerTool(name: string, config: {
+        title?: string;
+        description?: string;
+        inputSchema?: unknown;
+    }, _cb?: unknown): void;
+}
+/** Um grupo de tools do servidor: a área funcional + o registrar que a popula. */
+export interface CatalogGroup {
+    area: string;
+    register: (server: CapturingServer) => void;
+}
+/** Catálogo extraído + índices derivados (nomes e área por nome). */
+export interface Catalog {
+    tools: CatalogTool[];
+    /** Conjunto de nomes, para validação O(1) de fixtures. */
+    toolNames: Set<string>;
+    /** Nome da tool -> área grossa (para o relatório de acurácia por área). */
+    areaByName: Map<string, string>;
+}
+/** Converte o shape capturado (cru ou `z.object` pronto) em JSON-schema de input. */
+export declare function shapeToJsonSchema(shape: CapturedShape): JsonSchema;
+/** Monta o catálogo completo rodando o registrar de cada grupo. */
+export declare function buildCatalog(groups: CatalogGroup[]): Catalog;
+/** Definição de tool no formato do array `tools` da Anthropic Messages API. */
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: JsonSchema;
+}
+/** Array `tools` da Anthropic Messages API construído a partir do catálogo. */
+export declare function catalogAsAnthropicTools(catalog: Catalog): AnthropicTool[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAK,KAAK,UAAU,EAAoB,MAAM,KAAK,CAAC;AAE3D,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oBAAoB,EAAE,KAAK,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,WAAW,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAElD,kFAAkF;AAClF,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,aAAa,CAAA;KAAE,EAAE,CAAM;IAEtF,mEAAmE;IACnE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI;IAI7E,mFAAmF;IACnF,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,EACvE,GAAG,CAAC,EAAE,OAAO,GACZ,IAAI;CAOR;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;CAC7C;AAED,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,0DAA0D;IAC1D,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,2EAA2E;IAC3E,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAiBD,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAYlE;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAmB5D;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,UAAU,CAAC;CAC1B;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,CAMzE"}

package/dist/catalog.js

@@ -0,0 +1,92 @@
+/**
+ * Extrator de catálogo — a fonte de verdade do harness.
+ *
+ * Nunca toca a rede. Um "fake McpServer" (`CapturingServer`) grava cada registro de tool
+ * feito pelos `registerXTools` do servidor, exatamente como o `server.ts` real os liga.
+ * O resultado é a lista viva de tools (nome, descrição, JSON-schema do input) contra a
+ * qual as fixtures são validadas — renomear/remover uma tool quebra o teste offline
+ * imediatamente, sem rede e sem modelo.
+ *
+ * Duas formas de registro são capturadas, cobrindo os dois padrões do portfólio:
+ *   - `server.tool(name, description, shape, cb)` — forma clássica (shape zod cru);
+ *   - `server.registerTool(name, { description, inputSchema }, cb)` — forma SDK v2
+ *     (inputSchema pode ser um `z.object(...)` pronto ou um shape cru).
+ *
+ * Os callbacks das tools (que tocariam upstream/cache/bindings) são capturados mas nunca
+ * invocados — por isso nenhum runtime de Worker é necessário.
+ */
+import { z } from "zod";
+/**
+ * Fake McpServer que só grava registros de tool. Passe-o (com cast, ex.: `as never`)
+ * aos `registerXTools` do servidor real; nada além de `.tool`/`.registerTool` é chamado
+ * em tempo de registro nos servidores do portfólio.
+ */
+export class CapturingServer {
+    captured = [];
+    /** Forma clássica: `server.tool(name, description, shape, cb)`. */
+    tool(name, description, shape, _cb) {
+        this.captured.push({ name, description, shape: shape });
+    }
+    /** Forma SDK v2: `server.registerTool(name, { description, inputSchema }, cb)`. */
+    registerTool(name, config, _cb) {
+        this.captured.push({
+            name,
+            description: config.description ?? "",
+            shape: config.inputSchema,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Conversão zod -> JSON-schema.
+//
+// O zod 4 traz `z.toJSONSchema` nativo e estável entre versões — o harness não adiciona
+// dependência nova nem alcança internals privados. Convertemos em modo `io: "input"`:
+// um param é required sse não é `.optional()` nem `.default()` (campo com default é
+// suprido pelo servidor, o modelo não precisa enviá-lo). O resultado é normalizado ao
+// contrato JsonSchema deste harness: a saída nativa omite `additionalProperties` e
+// descarta `required` quando vazio.
+// ---------------------------------------------------------------------------
+function isZodType(x) {
+    return !!x && typeof x.safeParse === "function";
+}
+/** Converte o shape capturado (cru ou `z.object` pronto) em JSON-schema de input. */
+export function shapeToJsonSchema(shape) {
+    const objectSchema = isZodType(shape) ? shape : z.object((shape ?? {}));
+    const raw = z.toJSONSchema(objectSchema, { io: "input" });
+    return {
+        type: "object",
+        properties: raw.properties ?? {},
+        required: raw.required ?? [],
+        additionalProperties: false,
+    };
+}
+/** Monta o catálogo completo rodando o registrar de cada grupo. */
+export function buildCatalog(groups) {
+    const tools = [];
+    for (const group of groups) {
+        const server = new CapturingServer();
+        group.register(server);
+        for (const t of server.captured) {
+            tools.push({
+                name: t.name,
+                description: t.description,
+                area: group.area,
+                inputSchema: shapeToJsonSchema(t.shape),
+            });
+        }
+    }
+    return {
+        tools,
+        toolNames: new Set(tools.map((t) => t.name)),
+        areaByName: new Map(tools.map((t) => [t.name, t.area])),
+    };
+}
+/** Array `tools` da Anthropic Messages API construído a partir do catálogo. */
+export function catalogAsAnthropicTools(catalog) {
+    return catalog.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+    }));
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/fixtures.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Contrato de fixtures + validação offline.
+ *
+ * Cada projeto do portfólio mantém seu próprio conjunto de fixtures (consultas realistas
+ * na persona do usuário-alvo, com as tools aceitáveis para o PRIMEIRO passo da resposta).
+ * `validateFixtures` codifica os invariantes que no senado viviam num teste ad-hoc:
+ * o teste de fixtures de cada projeto vira uma asserção única de lista vazia.
+ */
+import type { Catalog } from "./catalog.js";
+export interface EvalFixture {
+    id: string;
+    /** Consulta realista, no idioma e na persona do servidor. */
+    query: string;
+    /** Tools aceitáveis como primeiro passo. Predição correta = qualquer membro do conjunto. */
+    expectedTools: string[];
+    /** Por que essas tools (e não as vizinhas) são a resposta certa. */
+    note: string;
+}
+export interface FixtureValidationOptions {
+    /** Mínimo de fixtures no conjunto. Padrão: 10. */
+    minFixtures?: number;
+    /** Máximo de fixtures (evita conjunto inchado/caro). Padrão: sem teto. */
+    maxFixtures?: number;
+    /** Comprimento mínimo da query. Padrão: 10. */
+    minQueryLength?: number;
+    /** Exigir `note` não-vazia em toda fixture. Padrão: true. */
+    requireNote?: boolean;
+    /**
+     * Mínimo de áreas funcionais distintas cobertas (área da primeira expectedTool).
+     * Padrão: 0 (sem exigência).
+     */
+    minAreas?: number;
+}
+/**
+ * Valida um conjunto de fixtures contra o catálogo vivo. Retorna a lista de problemas
+ * encontrados (vazia = válido) — cada string é autoexplicativa para o log do teste.
+ * O invariante central: toda tool em `expectedTools` deve existir no catálogo, para que
+ * um rename de tool quebre o teste offline imediatamente.
+ */
+export declare function validateFixtures(fixtures: EvalFixture[], catalog: Catalog, options?: FixtureValidationOptions): string[];
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,wBAA6B,GACrC,MAAM,EAAE,CAuEV"}

package/dist/fixtures.js

@@ -0,0 +1,78 @@
+/**
+ * Contrato de fixtures + validação offline.
+ *
+ * Cada projeto do portfólio mantém seu próprio conjunto de fixtures (consultas realistas
+ * na persona do usuário-alvo, com as tools aceitáveis para o PRIMEIRO passo da resposta).
+ * `validateFixtures` codifica os invariantes que no senado viviam num teste ad-hoc:
+ * o teste de fixtures de cada projeto vira uma asserção única de lista vazia.
+ */
+/**
+ * Valida um conjunto de fixtures contra o catálogo vivo. Retorna a lista de problemas
+ * encontrados (vazia = válido) — cada string é autoexplicativa para o log do teste.
+ * O invariante central: toda tool em `expectedTools` deve existir no catálogo, para que
+ * um rename de tool quebre o teste offline imediatamente.
+ */
+export function validateFixtures(fixtures, catalog, options = {}) {
+    const { minFixtures = 10, maxFixtures, minQueryLength = 10, requireNote = true, minAreas = 0, } = options;
+    const problems = [];
+    if (fixtures.length < minFixtures) {
+        problems.push(`conjunto tem ${fixtures.length} fixtures (mínimo ${minFixtures})`);
+    }
+    if (maxFixtures !== undefined && fixtures.length > maxFixtures) {
+        problems.push(`conjunto tem ${fixtures.length} fixtures (máximo ${maxFixtures})`);
+    }
+    const seenIds = new Set();
+    const seenQueries = new Set();
+    for (const f of fixtures) {
+        if (!f.id) {
+            problems.push(`fixture sem id (query: ${JSON.stringify(f.query.slice(0, 40))})`);
+        }
+        else if (seenIds.has(f.id)) {
+            problems.push(`id duplicado: ${f.id}`);
+        }
+        else {
+            seenIds.add(f.id);
+        }
+        const normQuery = f.query.trim().toLowerCase();
+        if (seenQueries.has(normQuery)) {
+            problems.push(`[${f.id}] query duplicada`);
+        }
+        else {
+            seenQueries.add(normQuery);
+        }
+        if (f.query.trim().length < minQueryLength) {
+            problems.push(`[${f.id}] query curta demais (< ${minQueryLength} caracteres)`);
+        }
+        if (requireNote && (!f.note || f.note.trim().length === 0)) {
+            problems.push(`[${f.id}] note vazia`);
+        }
+        if (!Array.isArray(f.expectedTools) || f.expectedTools.length === 0) {
+            problems.push(`[${f.id}] expectedTools vazio`);
+            continue;
+        }
+        if (new Set(f.expectedTools).size !== f.expectedTools.length) {
+            problems.push(`[${f.id}] expectedTools com duplicata`);
+        }
+        for (const tool of f.expectedTools) {
+            if (!catalog.toolNames.has(tool)) {
+                problems.push(`[${f.id}] tool inexistente no catálogo: ${tool}`);
+            }
+        }
+    }
+    if (minAreas > 0) {
+        const areas = new Set();
+        for (const f of fixtures) {
+            const first = f.expectedTools[0];
+            if (first === undefined)
+                continue;
+            const area = catalog.areaByName.get(first);
+            if (area)
+                areas.add(area);
+        }
+        if (areas.size < minAreas) {
+            problems.push(`cobertura de áreas insuficiente: ${areas.size} distintas (mínimo ${minAreas})`);
+        }
+    }
+    return problems;
+}
+//# sourceMappingURL=fixtures.js.map

package/dist/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { CapturingServer, buildCatalog, catalogAsAnthropicTools, shapeToJsonSchema, type AnthropicTool, type CapturedShape, type Catalog, type CatalogGroup, type CatalogTool, type JsonSchema, type ZodShape, } from "./catalog.js";
+export { validateFixtures, type EvalFixture, type FixtureValidationOptions, } from "./fixtures.js";
+export { GATE_DEPRIORITIZE_THRESHOLD, GATE_REMEDIATION_THRESHOLD, aggregate, evaluateGate, scoreAll, scoreItem, type AreaAccuracy, type GateDecision, type GateOptions, type GateResult, type Prediction, type ScoreReport, type ScoredItem, } from "./score.js";
+export { BASE_BACKOFF_MS, EvalApiError, MAX_BACKOFF_MS, MAX_RETRIES, backoffMs, classifyApiError, isFatalInfra, parseRetryAfter, type ErrorKind, } from "./retry.js";
+export { formatReport, type FixtureError, type FormattedReport, } from "./report.js";
+export { runEval, type EvalRunResult, type EvalRunnerConfig, } from "./runner.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,OAAO,EACP,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { CapturingServer, buildCatalog, catalogAsAnthropicTools, shapeToJsonSchema, } from "./catalog.js";
+export { validateFixtures, } from "./fixtures.js";
+export { GATE_DEPRIORITIZE_THRESHOLD, GATE_REMEDIATION_THRESHOLD, aggregate, evaluateGate, scoreAll, scoreItem, } from "./score.js";
+export { BASE_BACKOFF_MS, EvalApiError, MAX_BACKOFF_MS, MAX_RETRIES, backoffMs, classifyApiError, isFatalInfra, parseRetryAfter, } from "./retry.js";
+export { formatReport, } from "./report.js";
+export { runEval, } from "./runner.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,GAQlB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,GAGjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,SAAS,GAQV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,eAAe,GAEhB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,GAGb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,OAAO,GAGR,MAAM,aAAa,CAAC"}

package/dist/report.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Formatação pura do relatório da rodada. Sem I/O — devolve linhas + código de saída,
+ * para que o teste offline possa asserir o comportamento (cobertura incompleta, dicas
+ * de remédio, gate PRELIMINAR) sem capturar console.
+ */
+import { type GateOptions, type GateResult, type ScoredItem, type ScoreReport } from "./score.js";
+import { type ErrorKind } from "./retry.js";
+/** Fixture que nunca chegou ao modelo — dropout de infra, NÃO escolha errada de tool. */
+export interface FixtureError {
+    id: string;
+    kind: ErrorKind;
+    status: number;
+    message: string;
+}
+export interface FormattedReport {
+    lines: string[];
+    /**
+     * 0 → toda fixture foi avaliada (a decisão de gate é autoritativa).
+     * 2 → uma ou mais fixtures nunca chegaram ao modelo (dropout de infra); o gate sobre
+     *     o subconjunto avaliado aparece marcado PRELIMINAR — fixtures não tentadas não
+     *     podem ser pontuadas silenciosamente como erro de seleção.
+     */
+    exitCode: 0 | 2;
+    /** Relatório agregado apenas sobre as fixtures que chegaram ao modelo. */
+    report: ScoreReport;
+    gate: GateResult;
+}
+/** Monta o relatório completo da rodada (cobertura, acurácias, erros, gate). */
+export declare function formatReport(items: ScoredItem[], errors: FixtureError[], model: string, gateOptions?: GateOptions): FormattedReport;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA2B,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC3H,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,0EAA0E;IAC1E,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,UAAU,CAAC;CAClB;AAMD,gFAAgF;AAChF,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,YAAY,EAAE,EACtB,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,WAAgB,GAC5B,eAAe,CAwEjB"}

package/dist/report.js

@@ -0,0 +1,82 @@
+/**
+ * Formatação pura do relatório da rodada. Sem I/O — devolve linhas + código de saída,
+ * para que o teste offline possa asserir o comportamento (cobertura incompleta, dicas
+ * de remédio, gate PRELIMINAR) sem capturar console.
+ */
+import { aggregate, evaluateGate } from "./score.js";
+import { isFatalInfra } from "./retry.js";
+function pct(n) {
+    return `${(n * 100).toFixed(1)}%`;
+}
+/** Monta o relatório completo da rodada (cobertura, acurácias, erros, gate). */
+export function formatReport(items, errors, model, gateOptions = {}) {
+    // Só pontua as fixtures que de fato chegaram ao modelo — dropouts de infra ficam de
+    // fora, para que rate-limit/billing não se disfarce de acurácia ruim de seleção.
+    const erroredIds = new Set(errors.map((e) => e.id));
+    const evaluated = items.filter((it) => !erroredIds.has(it.id));
+    const report = aggregate(evaluated, 3);
+    const complete = errors.length === 0;
+    const lines = [];
+    lines.push("");
+    lines.push("=".repeat(64));
+    lines.push(`  Eval de seleção de tool — modelo: ${model}`);
+    lines.push("=".repeat(64));
+    lines.push(`  Cobertura:          ${evaluated.length}/${items.length} fixtures avaliadas` +
+        (complete ? "" : ` · ${errors.length} não avaliadas (falha de infra)`));
+    lines.push(`  Acurácia top-1:     ${pct(report.top1Accuracy)} (${report.top1Correct}/${report.total} avaliadas)`);
+    lines.push(`  Acurácia top-2:     ${pct(report.topKAccuracy[2] ?? 0)}`);
+    lines.push(`  Acurácia top-3:     ${pct(report.topKAccuracy[3] ?? 0)}`);
+    lines.push("");
+    lines.push("  Por área (acurácia top-1 entre as avaliadas, pior → melhor):");
+    for (const a of report.byArea) {
+        lines.push(`    ${a.area.padEnd(18)} ${pct(a.top1Accuracy).padStart(6)}  (${a.top1Correct}/${a.total})`);
+    }
+    const misses = evaluated.filter((it) => !it.top1);
+    if (misses.length > 0) {
+        lines.push("");
+        lines.push("  Escolhas erradas (top-1 fora do esperado):");
+        for (const m of misses) {
+            const got = m.predictedTools[0] ?? "(nenhuma)";
+            lines.push(`    [${m.id}] esperado ${JSON.stringify(m.expectedTools)} · obteve ${got}`);
+        }
+    }
+    if (errors.length > 0) {
+        const byKind = new Map();
+        for (const e of errors)
+            byKind.set(e.kind, (byKind.get(e.kind) ?? 0) + 1);
+        const kindSummary = [...byKind.entries()].map(([k, n]) => `${k}×${n}`).join(", ");
+        lines.push("");
+        lines.push(`  ⚠ RODADA INCOMPLETA — ${errors.length} fixtures não avaliadas (${kindSummary}):`);
+        for (const e of errors) {
+            lines.push(`    [${e.id}] ${e.kind} (HTTP ${e.status})`);
+        }
+        const fatal = errors.find((e) => isFatalInfra(e.kind));
+        lines.push("");
+        if (fatal?.kind === "billing") {
+            lines.push("    Causa fatal: saldo de créditos insuficiente. Reponha créditos em");
+            lines.push("    https://console.anthropic.com/settings/billing e rode de novo.");
+        }
+        else if (fatal) {
+            lines.push("    Causa fatal: chave rejeitada (auth). Verifique a ANTHROPIC_API_KEY e rode de novo.");
+        }
+        else {
+            lines.push("    Dica: rate-limit. Rode com EVAL_CONCURRENCY=1 e/ou um modelo menor (EVAL_MODEL).");
+        }
+    }
+    const gate = evaluateGate(report.top1Accuracy, gateOptions);
+    lines.push("");
+    lines.push("  Gate de seleção de tool:");
+    if (complete) {
+        lines.push(`    decisão: ${gate.decision}`);
+        lines.push(`    ${gate.message}`);
+    }
+    else {
+        lines.push(`    decisão: PRELIMINAR/${gate.decision} (rodada incompleta — NÃO usar para decisão)`);
+        lines.push(`    ${gate.message}`);
+        lines.push("    Complete a cobertura (100%) antes de tratar o gate como definitivo.");
+    }
+    lines.push("=".repeat(64));
+    lines.push("");
+    return { lines, exitCode: complete ? 0 : 2, report, gate };
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"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"}

package/dist/retry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Núcleo puro de retry/classificação de erro do runner. Sem rede, sem I/O — os testes
+ * offline o exercitam diretamente.
+ *
+ * O runner manda cada fixture à Anthropic Messages API. Duas classes de falha precisam
+ * ser distinguidas, porque nenhuma delas é sinal de acurácia (uma fixture que nunca
+ * chegou ao modelo não foi "respondida errado"):
+ *   - infra transitória (429 rate-limit, 529 overloaded, 5xx, rede) → vale retry;
+ *   - infra fatal (401 auth, 400 "credit balance too low") → retry nunca ajuda; a rodada
+ *     inteira deve falhar rápido com remédio claro em vez de martelar a API.
+ */
+export type ErrorKind = "rate_limit" | "overloaded" | "server" | "network" | "auth" | "billing" | "other";
+export declare class EvalApiError extends Error {
+    readonly status: number;
+    readonly kind: ErrorKind;
+    readonly retryable: boolean;
+    /** Dica Retry-After (segundos) vinda da API, quando presente. */
+    retryAfterSeconds: number | undefined;
+    constructor(message: string, status: number, kind: ErrorKind, retryable: boolean);
+}
+/** Kinds fatais curto-circuitam a rodada inteira — toda fixture bateria na mesma parede. */
+export declare function isFatalInfra(kind: ErrorKind): boolean;
+/**
+ * Classifica um erro HTTP da Anthropic API (status + corpo) em kind + retryable.
+ * Puro; o corpo só é inspecionado para distinguir um 400 de billing ("credit balance
+ * is too low") dos demais 400.
+ */
+export declare function classifyApiError(status: number, body: string): {
+    kind: ErrorKind;
+    retryable: boolean;
+};
+export declare const BASE_BACKOFF_MS = 2000;
+export declare const MAX_BACKOFF_MS = 30000;
+export declare const MAX_RETRIES = 5;
+/**
+ * Backoff base (ms) antes da tentativa de retry (0-based). Honra a dica Retry-After
+ * (segundos) da API quando presente — importante no 429, onde a janela de rate-limit
+ * precisa rolar antes da próxima tentativa. O chamador adiciona jitter; mantido puro
+ * para o teste unitário poder asserir valores exatos.
+ */
+export declare function backoffMs(attempt: number, retryAfterSeconds?: number): number;
+/** Interpreta um header `Retry-After` (só a forma inteiro-segundos) em segundos. */
+export declare function parseRetryAfter(headerValue: string | null): number | undefined;
+//# sourceMappingURL=retry.d.ts.map