oxe-cc 0.9.1 → 0.9.3

package/vscode-extension/src/extension.js

@@ -0,0 +1,310 @@
+'use strict';
+
+const vscode = require('vscode');
+const stateReader = require('./shared/stateReader');
+const contextLoader = require('./shared/contextLoader');
+const contractBuilder = require('./shared/contractBuilder');
+
+// ---------------------------------------------------------------------------
+// Output channel para diagnóstico
+// ---------------------------------------------------------------------------
+
+/** @type {vscode.OutputChannel | null} */
+let outputChannel = null;
+
+function log(message) {
+  if (outputChannel) outputChannel.appendLine(`[OXE Agents] ${message}`);
+}
+
+// ---------------------------------------------------------------------------
+// Configuração dos 13 agentes
+// ---------------------------------------------------------------------------
+
+/** @type {Array<{ id: string, workflow: string, description: string, isSticky: boolean }>} */
+const AGENTS = [
+  { id: 'oxe.router',       workflow: 'oxe',          isSticky: false },
+  { id: 'oxe.ask',          workflow: 'ask',           isSticky: false },
+  { id: 'oxe.scan',         workflow: 'scan',          isSticky: false },
+  { id: 'oxe.spec',         workflow: 'spec',          isSticky: true  },
+  { id: 'oxe.plan',         workflow: 'plan',          isSticky: true  },
+  { id: 'oxe.quick',        workflow: 'quick',         isSticky: true  },
+  { id: 'oxe.execute',      workflow: 'execute',       isSticky: true  },
+  { id: 'oxe.debug',        workflow: 'debug',         isSticky: false },
+  { id: 'oxe.verify',       workflow: 'verify',        isSticky: true  },
+  { id: 'oxe.review',       workflow: 'review-pr',     isSticky: false },
+  { id: 'oxe.capabilities', workflow: 'capabilities',  isSticky: false },
+  { id: 'oxe.skill',        workflow: 'skill',         isSticky: false },
+  { id: 'oxe.dashboard',    workflow: 'dashboard',     isSticky: false },
+];
+
+// ---------------------------------------------------------------------------
+// Seleção de modelo
+// ---------------------------------------------------------------------------
+
+/**
+ * Seleciona o melhor modelo disponível — GPT-4o via Copilot com fallbacks.
+ * @returns {Promise<import('vscode').LanguageModelChat | null>}
+ */
+async function selectModel() {
+  if (!vscode.lm || typeof vscode.lm.selectChatModels !== 'function') {
+    log('vscode.lm.selectChatModels não disponível nesta versão do VS Code.');
+    return null;
+  }
+
+  const selectors = [
+    { vendor: 'copilot', family: 'gpt-4o' },
+    { vendor: 'copilot', family: 'claude-sonnet' },
+    { vendor: 'copilot' },
+    {},
+  ];
+
+  for (const selector of selectors) {
+    try {
+      const models = await vscode.lm.selectChatModels(selector);
+      if (models && models.length > 0) {
+        log(`Modelo selecionado: ${models[0].name || models[0].id || JSON.stringify(selector)}`);
+        return models[0];
+      }
+    } catch (err) {
+      log(`selectChatModels(${JSON.stringify(selector)}) falhou: ${err.message}`);
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Conversão de histórico — duck typing para evitar quebra em versões antigas
+// ---------------------------------------------------------------------------
+
+/**
+ * Converte as últimas N trocas do histórico em mensagens para o LM.
+ * Usa duck typing em vez de instanceof para compatibilidade.
+ * @param {readonly unknown[]} history
+ * @param {number} maxTurns
+ * @returns {import('vscode').LanguageModelChatMessage[]}
+ */
+function buildHistoryMessages(history, maxTurns = 3) {
+  if (!history || !history.length) return [];
+  if (!vscode.LanguageModelChatMessage) return [];
+
+  const messages = [];
+  const recent = history.slice(-maxTurns * 2);
+
+  for (const turn of recent) {
+    if (!turn || typeof turn !== 'object') continue;
+
+    // ChatRequestTurn: tem propriedade `prompt` (string)
+    if (typeof turn.prompt === 'string' && turn.prompt.trim()) {
+      try {
+        messages.push(vscode.LanguageModelChatMessage.User(turn.prompt));
+      } catch { /* API incompatível */ }
+      continue;
+    }
+
+    // ChatResponseTurn: tem propriedade `response` (array de parts)
+    if (Array.isArray(turn.response)) {
+      const text = turn.response
+        .filter((part) => part && typeof part === 'object' && part.value && typeof part.value.value === 'string')
+        .map((part) => part.value.value)
+        .join('');
+      if (text.trim()) {
+        try {
+          messages.push(vscode.LanguageModelChatMessage.Assistant(text));
+        } catch { /* API incompatível */ }
+      }
+    }
+  }
+
+  return messages;
+}
+
+// ---------------------------------------------------------------------------
+// Verificar se o projeto tem OXE inicializado
+// ---------------------------------------------------------------------------
+
+/**
+ * Garante que o workspace tem OXE. Retorna o root ou null com mensagem de erro.
+ * @param {import('vscode').ChatResponseStream} stream
+ * @returns {string | null}
+ */
+function requireOxeProject(stream) {
+  const root = stateReader.getProjectRoot(vscode.workspace.workspaceFolders);
+
+  if (!root) {
+    stream.markdown(
+      '⚠️ **Nenhum workspace aberto.**\n\nAbra uma pasta de projeto para usar os agentes OXE.\n\n' +
+      '```\nFile → Open Folder → selecione a pasta do seu projeto\n```'
+    );
+    return null;
+  }
+
+  if (!stateReader.hasOxe(root)) {
+    stream.markdown(
+      `⚠️ **Projeto OXE não inicializado** em \`${root}\`.\n\n` +
+      'Execute no terminal para instalar o OXE:\n\n' +
+      '```bash\nnpx oxe-cc@latest\n```'
+    );
+    return null;
+  }
+
+  return root;
+}
+
+// ---------------------------------------------------------------------------
+// Handler genérico
+// ---------------------------------------------------------------------------
+
+/**
+ * Cria o handler de um agente OXE.
+ * @param {{ id: string, workflow: string }} agentDef
+ * @returns {import('vscode').ChatRequestHandler}
+ */
+function makeHandler(agentDef) {
+  const { workflow } = agentDef;
+
+  return async (request, context, stream, token) => {
+    log(`Handler invocado: ${agentDef.id} | prompt: "${(request.prompt || '').slice(0, 60)}"${request.command ? ' | cmd: /' + request.command : ''}`);
+
+    // 1. Verificar projeto
+    const projectRoot = requireOxeProject(stream);
+    if (!projectRoot) return;
+
+    // 2. Mostrar progresso
+    stream.progress(`Carregando contexto OXE — workflow: ${workflow}…`);
+
+    // 3. Ler state
+    const stateInfo = stateReader.getProjectContext(projectRoot);
+    log(`Estado: fase=${stateInfo.phase}, sessão=${stateInfo.session}`);
+
+    // 4. Carregar context pack
+    const pack = contextLoader.loadContextPack(projectRoot, workflow);
+    log(`Context pack: ${pack ? `carregado (quality=${pack.context_quality?.score})` : 'não encontrado — usando fallback'}`);
+
+    // 5. Formatar artefatos
+    const artifactsText = contextLoader.formatArtifacts(pack);
+    const hypothesesText = contextLoader.formatHypotheses(pack);
+    const gapsText = contextLoader.formatGaps(pack);
+
+    // 6. Construir system prompt
+    const systemPrompt = contractBuilder.build(
+      workflow,
+      pack,
+      stateInfo.text,
+      request.command,
+      stateInfo,
+      artifactsText,
+      hypothesesText,
+      gapsText
+    );
+    log(`System prompt: ${systemPrompt.length} chars`);
+
+    // 7. Selecionar modelo
+    const model = await selectModel();
+    if (!model) {
+      stream.markdown(
+        '⚠️ **Nenhum modelo de linguagem disponível.**\n\n' +
+        'Verifique se o **GitHub Copilot Chat** está instalado, habilitado e autenticado no VS Code.\n\n' +
+        '> Extensão necessária: `GitHub.copilot-chat`'
+      );
+      return;
+    }
+
+    // 8. Construir mensagens
+    const historyMessages = buildHistoryMessages(context.history);
+    const userMessage = request.command
+      ? `[/${request.command}] ${request.prompt}`
+      : request.prompt;
+
+    const messages = [];
+    try {
+      messages.push(vscode.LanguageModelChatMessage.User(systemPrompt));
+    } catch (err) {
+      log(`Erro ao criar LanguageModelChatMessage: ${err.message}`);
+      stream.markdown('⚠️ API de mensagens não disponível nesta versão do VS Code. Requer VS Code 1.95+.');
+      return;
+    }
+    messages.push(...historyMessages);
+    messages.push(vscode.LanguageModelChatMessage.User(userMessage));
+
+    // 9. Enviar e fazer stream
+    try {
+      const response = await model.sendRequest(messages, {}, token);
+      for await (const chunk of response.text) {
+        if (token.isCancellationRequested) break;
+        stream.markdown(chunk);
+      }
+      log(`Resposta concluída para ${agentDef.id}`);
+    } catch (err) {
+      if (err.name === 'CancellationError' || err.code === 'Cancelled') return;
+
+      // Tratar erros conhecidos do LM de forma segura (sem depender de statics que podem não existir)
+      const errMsg = err.message || String(err);
+      if (/blocked/i.test(errMsg)) {
+        stream.markdown('⚠️ **Solicitação bloqueada** pelo modelo. Reformule a pergunta e tente novamente.');
+      } else if (/not found/i.test(errMsg) || /unavailable/i.test(errMsg)) {
+        stream.markdown('⚠️ **Modelo indisponível.** Verifique as configurações do GitHub Copilot.');
+      } else if (/permission|quota/i.test(errMsg)) {
+        stream.markdown('⚠️ **Sem permissão ou cota esgotada.** Verifique a assinatura do Copilot.');
+      } else {
+        stream.markdown(`⚠️ **Erro:** ${errMsg}`);
+      }
+      log(`Erro no handler ${agentDef.id}: ${errMsg}`);
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Activate / Deactivate
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {import('vscode').ExtensionContext} context
+ */
+function activate(context) {
+  // Criar output channel para diagnóstico
+  outputChannel = vscode.window.createOutputChannel('OXE Agents');
+  context.subscriptions.push(outputChannel);
+  log(`Extensão ativando — VS Code ${vscode.version}`);
+
+  // Guard: verificar se a API de chat está disponível
+  if (!vscode.chat || typeof vscode.chat.createChatParticipant !== 'function') {
+    const msg = 'OXE Agents requer GitHub Copilot Chat (GitHub.copilot-chat) instalado e habilitado no VS Code.';
+    log(`AVISO: ${msg}`);
+    vscode.window.showWarningMessage(msg);
+    return;
+  }
+
+  // Registrar todos os agentes
+  let registered = 0;
+  for (const agentDef of AGENTS) {
+    try {
+      const participant = vscode.chat.createChatParticipant(agentDef.id, makeHandler(agentDef));
+      participant.iconPath = new vscode.ThemeIcon('sparkle');
+      context.subscriptions.push(participant);
+      registered++;
+      log(`Agente registrado: ${agentDef.id}`);
+    } catch (err) {
+      log(`Falha ao registrar ${agentDef.id}: ${err.message}`);
+    }
+  }
+
+  log(`${registered}/${AGENTS.length} agentes registrados com sucesso.`);
+
+  // Notificar na primeira ativação
+  const key = 'oxe.agents.v2.activated';
+  if (!context.globalState.get(key)) {
+    context.globalState.update(key, true);
+    vscode.window.showInformationMessage(
+      `OXE Agents: ${registered} agentes ativos. Use @oxe, @oxe-plan, @oxe-execute e outros no chat do Copilot.`,
+      'Ver log'
+    ).then((choice) => {
+      if (choice === 'Ver log') outputChannel?.show();
+    });
+  }
+}
+
+function deactivate() {
+  log('Extensão desativada.');
+}
+
+module.exports = { activate, deactivate };

package/vscode-extension/src/shared/contextLoader.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Tenta parsear JSON do stdout do oxe-cc (pula linhas de banner antes do `{`).
+ * @param {string} stdout
+ * @returns {object | null}
+ */
+function parseJsonFromOutput(stdout) {
+  if (!stdout) return null;
+  const text = String(stdout).trim();
+  const jsonStart = text.indexOf('{');
+  if (jsonStart === -1) return null;
+  try {
+    return JSON.parse(text.slice(jsonStart));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Tenta resolver o context pack via oxe-cc CLI.
+ * Primeiro tenta o binário local em node_modules, depois npx global.
+ * @param {string} projectRoot
+ * @param {string} workflow
+ * @returns {object | null}
+ */
+function resolveViaOxeCc(projectRoot, workflow) {
+  const localBin = path.join(projectRoot, 'node_modules', 'oxe-cc', 'bin', 'oxe-cc.js');
+  const args = ['context', 'inspect', '--workflow', workflow, '--json', '--dir', projectRoot];
+  const env = { ...process.env, OXE_NO_BANNER: '1' };
+  const opts = { cwd: projectRoot, encoding: 'utf8', timeout: 12000, env };
+
+  // Tentativa 1 — binário local
+  if (fs.existsSync(localBin)) {
+    const r = spawnSync(process.execPath, [localBin, ...args], opts);
+    if (r.status === 0) {
+      const pack = parseJsonFromOutput(r.stdout);
+      if (pack) return pack;
+    }
+  }
+
+  // Tentativa 2 — npx (global ou cache)
+  const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  const r = spawnSync(npxCmd, ['oxe-cc', ...args], opts);
+  if (r.status === 0) {
+    return parseJsonFromOutput(r.stdout);
+  }
+
+  return null;
+}
+
+/**
+ * Carrega o context pack para um workflow. Tenta disco primeiro, depois CLI.
+ * @param {string} projectRoot
+ * @param {string} workflow
+ * @returns {object | null}
+ */
+function loadContextPack(projectRoot, workflow) {
+  // Tentativa 1 — ler pack já materializado em disco
+  const packPath = path.join(projectRoot, '.oxe', 'context', 'packs', `${workflow}.json`);
+  if (fs.existsSync(packPath)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(packPath, 'utf8'));
+      if (data && data.workflow) return data;
+    } catch {
+      // arquivo corrompido → tenta CLI
+    }
+  }
+
+  // Tentativa 2 — resolver on-demand via oxe-cc
+  return resolveViaOxeCc(projectRoot, workflow);
+}
+
+/**
+ * Formata os artefatos selecionados do pack em markdown legível.
+ * Usa semantic_summary quando disponível, cai para summary.
+ * @param {object | null} pack
+ * @returns {string}
+ */
+function formatArtifacts(pack) {
+  if (!pack || !Array.isArray(pack.selected_artifacts)) return '';
+
+  const artifacts = pack.selected_artifacts
+    .filter((a) => a.exists && (a.semantic_summary || a.summary))
+    .map((a) => {
+      const content = (a.semantic_summary || a.summary || '').trim();
+      if (!content) return null;
+      const label = a.alias.replace(/_/g, ' ');
+      const flags = [
+        a.using_fallback ? '[fallback]' : '',
+        a.required ? '[obrigatório]' : '',
+      ].filter(Boolean).join(' ');
+      return `### ${label}${flags ? ' ' + flags : ''}\n${content}`;
+    })
+    .filter(Boolean);
+
+  return artifacts.length > 0 ? artifacts.join('\n\n') : '';
+}
+
+/**
+ * Formata hipóteses pendentes do pack para o system prompt.
+ * @param {object | null} pack
+ * @returns {string}
+ */
+function formatHypotheses(pack) {
+  if (!pack || !Array.isArray(pack.hypotheses)) return '';
+  const pending = pack.hypotheses.filter((h) => h.status === 'pending');
+  if (pending.length === 0) return '';
+  const lines = pending.map((h) =>
+    `- **[${h.id}]** ${h.condition}${h.checkpoint ? ` *(checkpoint: ${h.checkpoint})*` : ''}`
+  );
+  return `## Hipóteses críticas pendentes\n\n${lines.join('\n')}`;
+}
+
+/**
+ * Formata gaps críticos do pack.
+ * @param {object | null} pack
+ * @returns {string}
+ */
+function formatGaps(pack) {
+  if (!pack || !Array.isArray(pack.gaps)) return '';
+  const critical = pack.gaps.filter((g) => g.severity === 'critical');
+  if (critical.length === 0) return '';
+  const lines = critical.map((g) => `- \`${g.alias}\`: ${g.reason}`);
+  return `## Artefatos críticos ausentes\n\n${lines.join('\n')}`;
+}
+
+module.exports = {
+  loadContextPack,
+  formatArtifacts,
+  formatHypotheses,
+  formatGaps,
+};

package/vscode-extension/src/shared/contractBuilder.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/** Instruções específicas por reasoning_mode */
+const MODE_INSTRUCTIONS = {
+  discovery: [
+    'Explore o repositório e os artefatos antes de perguntar.',
+    'Separe fatos confirmados, inferências e lacunas.',
+    'Pergunte apenas ambiguidades que mudem a decisão ou o artefato final.',
+  ],
+  planning: [
+    'Produza plano decision-complete — feche interfaces, validação, riscos, rollback e assumptions.',
+    'Não deixe decisões importantes abertas para quem implementar depois.',
+    'Explicite confiança e condição objetiva para replanejar.',
+  ],
+  execution: [
+    'Faça reconhecimento curto antes de editar ou executar mutações.',
+    'Trabalhe no menor write set viável e valide após cada fatia relevante.',
+    'Pare e explicite o bloqueio quando houver hipótese crítica não verificada.',
+  ],
+  review: [
+    'Apresente findings primeiro, ordenados por severidade e evidência.',
+    'Separe bug, risco, regressão e lacuna de teste.',
+    'Se não houver findings, declare isso explicitamente e liste riscos residuais.',
+  ],
+  status: [
+    'Responda com leitura curta e orientada a decisão.',
+    'Dê uma recomendação única e justifique o motivo.',
+    'Explicite a confiança quando o estado estiver incompleto ou ambíguo.',
+  ],
+};
+
+/** Instruções por sub-comando */
+const COMMAND_INSTRUCTIONS = {
+  replan: 'Sub-comando **replan**: leia LESSONS.md e lessons-metrics.json antes de replanejar. Registre o motivo do replanejamento e as lições aplicadas.',
+  agents: 'Sub-comando **agents**: identifique 2–4 domínios distintos no PLAN.md e gere um blueprint multi-agente em formato plan-agents.json.',
+  discuss: 'Sub-comando **discuss**: abra uma discussão estruturada. Pergunte sobre contexto, alternativas e trade-offs antes de gerar a spec.',
+  wave: 'Sub-comando **wave**: o usuário indicou uma onda específica. Concentre o reconhecimento e a execução nessa onda apenas.',
+  task: 'Sub-comando **task**: o usuário indicou uma tarefa específica (ex: T3). Execute apenas essa tarefa com reconhecimento mínimo.',
+  audit: 'Sub-comando **audit**: modo auditor adversarial. Avalie SPEC.md + VERIFY.md sem consultar PLAN.md nem EXECUTION-RUNTIME.md. Objetivo: falsificar, não confirmar.',
+};
+
+/**
+ * Formata o vetor de confiança do pack para o system prompt.
+ * @param {object | null} pack
+ * @returns {string}
+ */
+function formatConfidenceVector(pack) {
+  const artifacts = pack?.selected_artifacts || [];
+  const planArtifact = artifacts.find((a) => a.alias === 'plan' && a.exists);
+  if (!planArtifact || !planArtifact.semantic_summary) return '';
+
+  // Verificar se o semantic_summary contém dados de confiança
+  if (!planArtifact.semantic_summary.includes('Confiança') &&
+      !planArtifact.semantic_summary.includes('confidence')) return '';
+
+  return '';  // O semantic_summary já inclui isso via extraction_intent=planning_input
+}
+
+/**
+ * Constrói o system prompt completo para um agente OXE.
+ *
+ * @param {string} workflow - slug do workflow (ex: 'plan', 'execute')
+ * @param {object | null} pack - context pack carregado
+ * @param {string} stateText - conteúdo do STATE.md (truncado)
+ * @param {string | undefined} command - sub-comando invocado (ex: 'replan')
+ * @param {{ phase: string | null, session: string | null, nextStep: string | null }} stateInfo
+ * @param {string} artifactsText - artefatos formatados pelo contextLoader
+ * @param {string} hypothesesText - hipóteses formatadas
+ * @param {string} gapsText - gaps formatados
+ * @returns {string}
+ */
+function build(workflow, pack, stateText, command, stateInfo, artifactsText, hypothesesText, gapsText) {
+  const contract = pack?.contract || {};
+  const mode = contract.reasoning_mode || 'status';
+  const guidance = Array.isArray(contract.guidance) && contract.guidance.length > 0
+    ? contract.guidance
+    : (MODE_INSTRUCTIONS[mode] || MODE_INSTRUCTIONS.status);
+
+  const modeInstructions = MODE_INSTRUCTIONS[mode] || MODE_INSTRUCTIONS.status;
+  const commandInstruction = command && COMMAND_INSTRUCTIONS[command]
+    ? `\n\n**${COMMAND_INSTRUCTIONS[command]}**`
+    : '';
+
+  // Resumo do estado do projeto
+  const stateSection = stateText
+    ? `## Estado atual do projeto\n\n${stateText}`
+    : '';
+
+  // Info de contexto rápido
+  const contextInfo = [
+    stateInfo.phase ? `- **Fase:** ${stateInfo.phase}` : '',
+    stateInfo.session ? `- **Sessão ativa:** ${stateInfo.session}` : '',
+    stateInfo.nextStep ? `- **Próximo passo sugerido:** ${stateInfo.nextStep}` : '',
+  ].filter(Boolean).join('\n');
+
+  // Qualidade do contexto
+  let qualityNote = '';
+  if (pack) {
+    const quality = pack.context_quality;
+    if (quality && quality.status === 'critical') {
+      qualityNote = `\n> ⚠️ **Contexto crítico** (score: ${quality.score}/100) — artefatos obrigatórios ausentes. Declare fallback para leitura direta se necessário.`;
+    } else if (pack.fallback_required) {
+      qualityNote = '\n> ℹ️ **Contexto com fallback** — alguns artefatos foram resolvidos por caminhos alternativos.';
+    }
+    if (pack.freshness && pack.freshness.stale) {
+      qualityNote += `\n> 🕐 **Pack desatualizado** (${pack.freshness.reason}) — considere regenerar com \`oxe-cc context build --workflow ${workflow}\`.`;
+    }
+  }
+
+  const parts = [
+    `Você é o agente **OXE ${workflow}**, especializado na fase de ${mode} do framework OXE (Orchestrated eXperience Engineering).`,
+    '',
+    '## Contrato de raciocínio',
+    `- **Modo:** ${mode}`,
+    `- **Política de perguntas:** ${contract.question_policy || 'none'}`,
+    `- **Saída esperada:** ${contract.output_contract || 'routing'}`,
+    `- **Perfil de ferramentas:** ${contract.tool_profile || 'read_heavy'}`,
+    `- **Política de confiança:** ${contract.confidence_policy || 'explicit'}`,
+    '',
+    '## Diretrizes de raciocínio',
+    ...guidance.map((g) => `- ${g}`),
+    '',
+  ];
+
+  if (contextInfo) {
+    parts.push('## Contexto rápido', contextInfo, '');
+  }
+
+  if (stateSection) {
+    parts.push(stateSection, '');
+  }
+
+  if (artifactsText) {
+    parts.push('## Artefatos do projeto', artifactsText, '');
+  }
+
+  if (hypothesesText) {
+    parts.push(hypothesesText, '');
+  }
+
+  if (gapsText) {
+    parts.push(gapsText, '');
+  }
+
+  if (qualityNote) {
+    parts.push(qualityNote.trim(), '');
+  }
+
+  parts.push(
+    '## Instrução geral',
+    'Responda **em português**. Use evidência explícita dos artefatos acima — não invente estado. ' +
+    modeInstructions.join(' ') +
+    commandInstruction
+  );
+
+  return parts.join('\n').trim();
+}
+
+module.exports = { build };