@spec-wave/cli 0.15.0 → 0.16.0

package/src/agent/openrouter-agent.mjs

@@ -0,0 +1,378 @@
+// Backend OpenRouter: loop de tool-calling contra o /chat/completions
+// compatível com OpenAI. Porte de `agent-cli/src/openrouterAgent.ts`.
+//
+// Não há subprocesso aqui — este processo é dono do loop do modelo E da
+// execução das tools (ver `tools.mjs`), e fala com a rede por `fetch` puro.
+// Não adicione SDK de provider para ele.
+//
+// Três capacidades que o agent-cli não tinha e a spec-wave depende:
+//
+//  1. `maxTokens` — teto de saída por ação (`ai.maxTokensByAction`).
+//  2. Detecção de TRUNCAMENTO — `finish_reason: "length"` vira erro. Um
+//     documento cortado no meio de uma frase PASSA na validação de seções e
+//     vale menos que documento nenhum, então a geração falha e nada é gravado.
+//  3. Saída ESTRUTURADA — `responseSchema` força uma tool call única com
+//     schema, que é como a crítica adversarial garante `severity` no enum.
+//     Sem isso, um payload fora do contrato viraria texto livre parseado "na
+//     tolerância" — exatamente o bug que rebaixava um finding grave a menor.
+
+import {
+  createToolContext,
+  executeTool,
+  toolDefinitionsFor,
+} from './tools.mjs';
+import { withTrace, startObservation, updateSpan, endObservation } from './tracing.mjs';
+import { TruncatedOutputError, isTruncationReason } from './errors.mjs';
+
+const DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
+const DEFAULT_TOOLS = ['Read', 'Glob', 'Grep'];
+const MAX_TURNS = 25;
+const REQUEST_TIMEOUT_MS = 300_000;
+const MAX_ATTEMPTS = 3;
+const RETRY_STATUS = new Set([408, 409, 429, 500, 502, 503, 504]);
+
+/**
+ * Não há preset `claude_code` para construir em cima aqui, então as instruções
+ * base do agente são nossas. O `systemPromptAppend` (o model-prompt da skill)
+ * vem depois disto.
+ */
+export const OPENROUTER_SYSTEM_PROMPT = `You are an autonomous CLI coding agent working in the directory {{CWD}}.
+
+Use the provided tools to inspect and change files — never guess at file contents you have not read, and never claim to have written a file you did not write with the Write tool.
+Work in small, verifiable steps: locate the relevant files first (Glob/Grep), read them, then act.
+Tool calls are executed by the CLI that hosts you; some paths are blocked by policy, and a refusal comes back as the tool result. If a call is refused, adapt instead of retrying it unchanged.
+When the task is done, stop calling tools and reply with a short summary of what you did.`;
+
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+async function postChatCompletion(body, apiKey, verbose) {
+  const baseUrl = process.env.OPENROUTER_BASE_URL ?? DEFAULT_BASE_URL;
+  const headers = {
+    Authorization: `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+    'X-Title': process.env.OPENROUTER_APP_NAME ?? 'spec-wave',
+  };
+  if (process.env.OPENROUTER_SITE_URL) headers['HTTP-Referer'] = process.env.OPENROUTER_SITE_URL;
+
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const response = await fetch(`${baseUrl.replace(/\/$/, '')}/chat/completions`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+      if (!response.ok) {
+        const detail = (await response.text().catch(() => '')).slice(0, 500);
+        const err = new Error(
+          `OpenRouter request failed: ${response.status} ${response.statusText}${detail ? ` — ${detail}` : ''}`,
+        );
+        if (RETRY_STATUS.has(response.status) && attempt < MAX_ATTEMPTS) {
+          lastError = err;
+          if (verbose) console.log(`[Agent] ${err.message}; retrying (${attempt}/${MAX_ATTEMPTS - 1})`);
+          await sleep(1_000 * 2 ** (attempt - 1));
+          continue;
+        }
+        throw err;
+      }
+      // Lê como texto e parseia aqui (em vez de `response.json()`) para que um
+      // corpo não-JSON entre na mensagem de erro. "Unexpected token <" sem o
+      // corpo não diz nada sobre uma página de erro do gateway.
+      const raw = await response.text();
+      let json;
+      try {
+        json = JSON.parse(raw);
+      } catch {
+        throw new Error(`OpenRouter devolveu um corpo não-JSON: ${raw.slice(0, 500)}`);
+      }
+      // O OpenRouter reporta falha do provider upstream com HTTP 200.
+      if (json.error) {
+        throw new Error(`OpenRouter returned an error: ${json.error.message ?? JSON.stringify(json.error)}`);
+      }
+      return json;
+    } catch (err) {
+      lastError = err;
+      const retryable =
+        attempt < MAX_ATTEMPTS &&
+        (err instanceof TypeError || (err instanceof Error && err.name === 'TimeoutError'));
+      if (!retryable) throw err;
+      if (verbose) console.log(`[Agent] ${errorMessage(err)}; retrying (${attempt}/${MAX_ATTEMPTS - 1})`);
+      await sleep(1_000 * 2 ** (attempt - 1));
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+/**
+ * Corpo EXATO de POST /chat/completions (função PURA — testável sem HTTP).
+ *
+ * Com `schema`, força a ferramenta via `tool_choice`: o modelo não tem como
+ * responder em texto livre, que é o que produzia JSON sujo na crítica. Sem
+ * schema, as tools de leitura entram com `tool_choice: "auto"`.
+ *
+ * @param {object} params
+ * @returns {object}
+ */
+export function buildChatCompletionBody({
+  model, messages, tools = [], schema = null, maxTokens, temperature,
+}) {
+  return {
+    model,
+    messages,
+    ...(maxTokens ? { max_tokens: maxTokens } : {}),
+    ...(temperature !== undefined ? { temperature } : {}),
+    ...(schema
+      ? {
+          tools: [{
+            type: 'function',
+            function: {
+              name: schema.name,
+              description: schema.description,
+              parameters: schema.jsonSchema,
+              ...(schema.strict ? { strict: true } : {}),
+            },
+          }],
+          tool_choice: { type: 'function', function: { name: schema.name } },
+        }
+      : tools.length > 0
+        ? { tools, tool_choice: 'auto' }
+        : {}),
+    // Pede ao OpenRouter que inclua a contabilidade de custo em `usage`.
+    usage: { include: true },
+  };
+}
+
+/**
+ * Roda o agente no OpenRouter.
+ *
+ * @param {string} prompt
+ * @param {import('./run-types.mjs').AgentRunOptions} options
+ * @returns {Promise<import('./run-types.mjs').AgentRunResult>}
+ */
+export async function runOpenRouterAgent(prompt, options) {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    throw new Error('OPENROUTER_API_KEY não definida — adicione-a como secret do repositório.');
+  }
+
+  const schema = options.responseSchema ?? null;
+  // Com schema, o modelo não explora nada: a resposta é UMA tool call com o
+  // payload. Misturar as duas coisas daria ao modelo a saída de escape de
+  // "chamar Read de novo" em vez de fechar o contrato.
+  const tools = schema ? [] : (options.tools ?? DEFAULT_TOOLS);
+  const toolDefinitions = toolDefinitionsFor(tools);
+  const toolContext = createToolContext({
+    tools,
+    cwd: options.cwd ?? process.cwd(),
+    allowedWritePaths: options.allowedWritePaths,
+  });
+  const maxTurns = schema ? 1 : (options.maxTurns ?? MAX_TURNS);
+  const runResult = {
+    resultSubtype: null,
+    outputText: '',
+    costUsd: null,
+    numTurns: 0,
+    structured: null,
+    usage: { inputTokens: 0, outputTokens: 0 },
+  };
+  const quiet = options.quiet !== false;
+
+  await withTrace(
+    {
+      name: options.traceName ?? 'agent-execution',
+      sessionId: options.sessionId,
+      userId: options.userId,
+      tags: ['spec-wave', 'agent', 'openrouter', ...(options.extraTags ?? [])],
+      metadata: { model: options.model, provider: 'openrouter' },
+      nested: options.nested === true,
+    },
+    async span => {
+      updateSpan(span, { input: prompt });
+
+      const systemPrompt = [
+        schema ? null : OPENROUTER_SYSTEM_PROMPT.replace('{{CWD}}', toolContext.cwd),
+        options.systemPromptAppend,
+      ]
+        .filter(Boolean)
+        .join('\n\n');
+
+      const messages = [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: prompt },
+      ];
+
+      let turns = 0;
+      let totalCost = 0;
+      let sawCost = false;
+      let finalText = '';
+      let openGeneration = null;
+
+      try {
+        while (turns < maxTurns) {
+          turns++;
+          const generation = startObservation(
+            span,
+            'generate-response',
+            { model: options.model, ...(turns === 1 ? { input: prompt } : {}) },
+            'generation',
+          );
+          openGeneration = generation;
+
+          const response = await postChatCompletion(
+            buildChatCompletionBody({
+              model: options.model,
+              messages,
+              tools: toolDefinitions,
+              schema,
+              maxTokens: options.maxTokens,
+              temperature: options.temperature,
+            }),
+            apiKey,
+            options.verbose === true,
+          );
+
+          const choice = response.choices?.[0];
+          const message = choice?.message;
+          const text = message?.content ?? '';
+          const toolCalls = message?.tool_calls ?? [];
+          const usage = response.usage;
+          const cost = typeof usage?.cost === 'number' ? usage.cost : null;
+          if (cost !== null) {
+            totalCost += cost;
+            sawCost = true;
+          }
+          runResult.usage.inputTokens += usage?.prompt_tokens ?? 0;
+          runResult.usage.outputTokens += usage?.completion_tokens ?? 0;
+
+          if (!quiet && text.trim() !== '') console.log(`\nAssistant: ${text}`);
+
+          updateSpan(generation, {
+            model: response.model ?? options.model,
+            output: toolCalls.length > 0
+              ? { role: 'assistant', content: text, tool_calls: toolCalls }
+              : text,
+            usageDetails: {
+              input: usage?.prompt_tokens ?? 0,
+              output: usage?.completion_tokens ?? 0,
+              cache_read_input_tokens: usage?.prompt_tokens_details?.cached_tokens ?? 0,
+            },
+            ...(cost !== null ? { costDetails: { total: cost } } : {}),
+          });
+          endObservation(generation);
+          openGeneration = null;
+
+          // TRUNCAMENTO: o corte tem de virar erro ANTES de qualquer coisa ser
+          // gravada. Repetir a mesma requisição dá o mesmo corte, então este
+          // erro não é transitório e não entra no retry.
+          if (isTruncationReason(choice?.finish_reason)) {
+            throw new TruncatedOutputError({
+              provider: 'openrouter',
+              model: response.model ?? options.model,
+              maxTokens: options.maxTokens ?? null,
+              // `native_finish_reason` preserva o motivo cru do provedor
+              // upstream — sem ele o diagnóstico perde de qual camada veio o
+              // corte, que é o que distingue teto nosso de teto do provider.
+              reason: `${choice.finish_reason}${choice.native_finish_reason ? `/${choice.native_finish_reason}` : ''}`,
+              chars: (runResult.outputText + text).length,
+            });
+          }
+
+          // Saída estruturada: a tool forçada é o resultado, não um passo.
+          if (schema) {
+            const call = toolCalls.find(c => c.function?.name === schema.name) ?? toolCalls[0];
+            if (!call) {
+              // Alguns modelos ainda respondem em texto apesar do tool_choice
+              // forçado. TRANSITÓRIO de propósito: repetir a mesma requisição
+              // costuma resolver, ao contrário de truncamento (mesmo corte).
+              const err = new Error(
+                `O modelo não chamou a ferramenta "${schema.name}" ` +
+                `(finish_reason: ${choice?.finish_reason ?? 'desconhecido'}).`,
+              );
+              err.transient = true;
+              throw err;
+            }
+            runResult.structured = JSON.parse(call.function.arguments || '{}');
+            runResult.outputText = call.function.arguments ?? '';
+            runResult.resultSubtype = 'success';
+            break;
+          }
+
+          if (toolCalls.length === 0) {
+            finalText = text;
+            runResult.outputText = text;
+            runResult.resultSubtype = 'success';
+            break;
+          }
+
+          messages.push({
+            role: 'assistant',
+            content: text === '' ? null : text,
+            tool_calls: toolCalls,
+          });
+
+          for (const call of toolCalls) {
+            let parsedInput;
+            let parseError = null;
+            try {
+              parsedInput = call.function.arguments.trim() === ''
+                ? {}
+                : JSON.parse(call.function.arguments);
+            } catch (err) {
+              parseError = `Could not parse tool arguments as JSON: ${errorMessage(err)}`;
+            }
+
+            if (options.verbose) console.log(`\n[Tool] ${call.function.name}(${call.function.arguments})`);
+
+            const observation = startObservation(
+              span,
+              `tool-${call.function.name}`,
+              { input: parseError === null ? parsedInput : call.function.arguments },
+              'tool',
+            );
+
+            const result = parseError !== null
+              ? { output: parseError, isError: true }
+              : executeTool(call.function.name, parsedInput, toolContext);
+
+            updateSpan(observation, {
+              output: result.isError ? `[tool failed] ${result.output}` : result.output,
+              ...(result.isError ? { level: 'ERROR' } : {}),
+            });
+            endObservation(observation);
+
+            messages.push({ role: 'tool', tool_call_id: call.id, content: result.output });
+          }
+        }
+
+        if (runResult.resultSubtype === null) {
+          runResult.resultSubtype = 'error_max_turns';
+          console.warn(`\n[Agent] Run ended without success: error_max_turns (${maxTurns} turns)`);
+        }
+
+        updateSpan(span, {
+          output: runResult.resultSubtype === 'success' ? finalText || runResult.outputText : `[${runResult.resultSubtype}]`,
+          metadata: {
+            total_cost_usd: sawCost ? totalCost : null,
+            num_turns: turns,
+            provider: 'openrouter',
+            permission_denials: toolContext.denials,
+          },
+        });
+        runResult.costUsd = sawCost ? totalCost : null;
+        runResult.numTurns = turns;
+      } finally {
+        endObservation(openGeneration);
+        if (runResult.resultSubtype === null) {
+          updateSpan(span, { output: '[run ended without a result]' });
+        }
+      }
+    },
+  );
+
+  return runResult;
+}

package/src/agent/run-types.mjs

@@ -0,0 +1,59 @@
+// Contrato de execução que os DOIS backends implementam, para que quem chama
+// nunca ramifique por provider. Porte de `agent-cli/src/runTypes.ts`: lá são
+// `interface`s de TypeScript, aqui typedefs de JSDoc — este pacote não tem
+// etapa de build.
+//
+// Os campos marcados como "extensão spec-wave" não existem no agent-cli; foram
+// acrescentados porque a CLI depende deles (ver `openrouter-agent.mjs`).
+
+/**
+ * @typedef {object} ResponseSchema
+ * Saída estruturada: força UMA tool call com este schema. Extensão spec-wave —
+ * é o que garante `severity` dentro do enum na crítica adversarial.
+ * @property {string} name nome da ferramenta forçada
+ * @property {string} description
+ * @property {object} jsonSchema JSON Schema dos parâmetros
+ * @property {boolean} [strict] envia `strict: true` (nem todo modelo aceita)
+ * @property {(payload: object) => object} [validate] valida/normaliza; lançar
+ *   aqui dispara o re-pedido de quem chama
+ */
+
+/**
+ * @typedef {object} AgentRunOptions
+ * @property {string} model
+ * @property {string} sessionId
+ * @property {string} userId
+ * @property {boolean} [verbose]
+ * @property {string[]} [tools] superfície de tools. Default: Read/Glob/Grep —
+ *   somente leitura, ao contrário do agent-cli (que inclui Write): aqui quem
+ *   grava documento é o comando, não o modelo
+ * @property {string} [systemPromptAppend] anexado ao preset `claude_code`
+ *   (anthropic) ou ao OPENROUTER_SYSTEM_PROMPT (openrouter)
+ * @property {string[]} [allowedWritePaths] quando presente, Write só passa nestes
+ * @property {number} [maxTurns] teto de turnos. Default: 25
+ * @property {string[]} [extraTags] tags extras da trace
+ * @property {string} [traceName] nome da observação raiz. Default: agent-execution
+ * @property {boolean} [nested] herda o contexto OTel ambiente em vez de abrir trace
+ * @property {boolean} [quiet] silencia o stdout por turno. Default aqui: true
+ *   (o agent-cli tem stdout como produto; esta CLI tem o documento)
+ * @property {string} [cwd] extensão spec-wave: raiz do repositório do usuário
+ * @property {number} [maxTokens] extensão spec-wave: teto de tokens de saída
+ * @property {number} [temperature] extensão spec-wave
+ * @property {ResponseSchema} [responseSchema] extensão spec-wave
+ * @property {string} [action] extensão spec-wave: spec|plan|decompose|critique,
+ *   usado nas mensagens de erro e no relatório de custo
+ */
+
+/**
+ * @typedef {object} AgentRunResult
+ * @property {string|null} resultSubtype "success", "error_max_turns", ...
+ * @property {string} outputText resposta final; vazia quando o run não produziu
+ *   texto. Um backend que a deixe vazia quebra quem consome em silêncio
+ * @property {number|null} costUsd custo total, ou null se o backend não reportou
+ * @property {number} numTurns turnos consumidos
+ * @property {object|null} structured extensão spec-wave: payload da tool forçada
+ * @property {{inputTokens: number, outputTokens: number}} usage extensão
+ *   spec-wave: alimenta o relatório de uso comentado na issue
+ */
+
+export {};

package/src/agent/telemetry.mjs

@@ -0,0 +1,54 @@
+// OpenTelemetry + Langfuse. Porte de `agent-cli/src/telemetry.ts`.
+//
+// Por que o NodeSDK importa: o SDK v4 do Langfuse é OTel-nativo — sem
+// `NodeSDK.start()` registrando o tracer provider e o context manager, TODA
+// chamada de observação vira no-op silencioso. E o `shutdown()` é load-bearing:
+// spans exportam em lote, e um processo curto (que é o caso de todo comando
+// desta CLI dentro de um Action) sai antes do último lote sem ele.
+//
+// Diferença em relação ao agent-cli: lá a telemetria é obrigatória. Aqui ela é
+// OPCIONAL — sem as chaves do Langfuse a CLI segue rodando sem tracing, porque
+// gerar a spec.md não pode depender de um serviço de observabilidade.
+
+let sdk = null;
+
+/** True quando há credenciais do Langfuse no ambiente. */
+export function telemetryConfigured(env = process.env) {
+  return Boolean(env.LANGFUSE_PUBLIC_KEY && env.LANGFUSE_SECRET_KEY);
+}
+
+/**
+ * Inicializa a telemetria, se configurada. Idempotente e best-effort: falha ao
+ * subir o SDK NUNCA derruba o comando — no pior caso o run roda sem traces.
+ *
+ * @returns {Promise<boolean>} true se a telemetria ficou ativa
+ */
+export async function initTelemetry({ env = process.env } = {}) {
+  if (sdk) return true;
+  if (!telemetryConfigured(env)) return false;
+  try {
+    const [{ NodeSDK }, { LangfuseSpanProcessor }] = await Promise.all([
+      import('@opentelemetry/sdk-node'),
+      import('@langfuse/otel'),
+    ]);
+    sdk = new NodeSDK({ spanProcessors: [new LangfuseSpanProcessor()] });
+    sdk.start();
+    return true;
+  } catch (err) {
+    console.warn(`[spec-wave] telemetria desativada: ${err.message}`);
+    sdk = null;
+    return false;
+  }
+}
+
+/** Faz o flush do último lote de spans. Best-effort, como o init. */
+export async function shutdownTelemetry() {
+  if (!sdk) return;
+  try {
+    await sdk.shutdown();
+  } catch (err) {
+    console.warn(`[spec-wave] falha ao encerrar a telemetria: ${err.message}`);
+  } finally {
+    sdk = null;
+  }
+}