oxe-cc 1.7.0 → 1.8.3

package/bin/lib/oxe-operational.cjs

@@ -79,6 +79,31 @@ function loadRuntimeModule() {
   }
 }
 
+// Gap 1: factory that always wires GateManager into ctx
+function createExecutionContext(projectRoot, activeSession, options = {}) {
+  const runtime = loadRuntimeModule();
+  const runId = options.runId || makeRunId();
+  const gateManager = (runtime && typeof runtime.GateManager === 'function')
+    ? new runtime.GateManager(projectRoot, activeSession || null, runId)
+    : null;
+  return {
+    projectRoot,
+    sessionId: activeSession || null,
+    runId,
+    executor: options.executor || null,
+    workspaceManager: options.workspaceManager || null,
+    gateManager,
+    policyEngine: options.policyEngine || null,
+    policyActor: options.policyActor || 'runtime',
+    quota: options.quota || null,
+    pluginRegistry: options.pluginRegistry || null,
+    auditTrail: options.auditTrail || null,
+    evidenceStore: options.evidenceStore || null,
+    onEvent: options.onEvent || null,
+    options: options.schedulerOptions || {},
+  };
+}
+
 function buildRuntimePluginRegistry(projectRoot) {
   const runtime = loadRuntimeModule();
   if (!runtime || typeof runtime.PluginRegistry !== 'function') return null;
@@ -431,6 +456,61 @@ function reduceCanonicalRunState(projectRoot, activeSession, options = {}) {
   return serializeCanonicalState(reduceCanonicalRunStateLive(projectRoot, activeSession, options));
 }
 
+/**
+ * Static-analysis lints for common pitfalls detectable before execution.
+ * Returns hint strings to be appended to validationErrors (shown at compile time).
+ */
+function lintPlanForCommonPitfalls(parsedPlan, parsedSpec, projectRoot, rawSpecText = '') {
+  const hints = [];
+  const specText = (parsedSpec && parsedSpec.objective ? parsedSpec.objective : '') +
+    JSON.stringify(parsedSpec && parsedSpec.criteria ? parsedSpec.criteria : []) +
+    (rawSpecText || '');
+  const planTasks = parsedPlan && Array.isArray(parsedPlan.tasks) ? parsedPlan.tasks : [];
+
+  // ── Lint 1: HTML/JS SPA sem restrição de file:// ──────────────────────────
+  // Detects: spec mentions HTML/SPA + no files restriction, but no verify command
+  // checks for fetch() absence. Warns to add a fetch-detection verify.
+  const isHtmlApp = /html|spa|browser|page|frontend|estático|static|aplicação web|web app|web page|interface web|\.html/i.test(specText);
+  if (isHtmlApp) {
+    const hasFetchGuard = planTasks.some(t =>
+      t.verifyCommand && /fetch|XMLHttpRequest|file:\/\//i.test(t.verifyCommand)
+    );
+    const specMentionsServer = /servidor|server|http-server|localhost|npx serve|vite|webpack/i.test(specText);
+    const specMentionsFileProtocol = /file:\/\/|sem servidor|without server|no.server/i.test(specText);
+    if (!hasFetchGuard && !specMentionsServer && !specMentionsFileProtocol) {
+      hints.push(
+        'HINT(html-fetch): SPEC não declara se o app precisa de servidor HTTP. ' +
+        'Se abrir em file://, adicione à SPEC: "sem servidor HTTP" e um verify que detecte fetch(): ' +
+        '`node -e "if(require(\'fs\').readFileSync(\'app.js\',\'utf8\').includes(\'fetch(\'))throw new Error(\'fetch not allowed in file://\')"`'
+      );
+    }
+  }
+
+  // ── Lint 2: Verify commands que só verificam existência de função, não comportamento ──
+  const existenceOnlyVerify = planTasks.filter(t =>
+    t.verifyCommand &&
+    /s\.includes\(/.test(t.verifyCommand) &&
+    !/existsSync|readFileSync.*utf8|require\(/.test(t.verifyCommand)
+  );
+  if (existenceOnlyVerify.length > 2) {
+    hints.push(
+      `HINT(verify-depth): ${existenceOnlyVerify.length} tarefa(s) verificam apenas presença de string no código ` +
+      `(s.includes). Considere adicionar verificações de comportamento: executar o código, não só inspecioná-lo.`
+    );
+  }
+
+  // ── Lint 3: Tarefas sem verify command (T-level) ──────────────────────────
+  const noVerify = planTasks.filter(t => !t.verifyCommand && !t.done);
+  if (noVerify.length > 0) {
+    hints.push(
+      `HINT(no-verify): ${noVerify.length} tarefa(s) sem Comando de verificação: ${noVerify.map(t => t.id).join(', ')}. ` +
+      `Tarefas sem verify não serão testadas inline pelo scheduler.`
+    );
+  }
+
+  return hints;
+}
+
 function compileExecutionGraphFromArtifacts(projectRoot, activeSession, options = {}) {
   const runtime = loadRuntimeModule();
   const parsers = loadSdkParsers();
@@ -443,12 +523,17 @@ function compileExecutionGraphFromArtifacts(projectRoot, activeSession, options
   const artifactPaths = resolveRuntimeArtifactPaths(projectRoot, activeSession);
   const specText = readTextIfExists(artifactPaths.spec);
   const planText = readTextIfExists(artifactPaths.plan);
-  if (!specText) throw new Error(`SPEC.md ausente em ${artifactPaths.spec}`);
-  if (!planText) throw new Error(`PLAN.md ausente em ${artifactPaths.plan}`);
+  if (!specText) throw new Error(`SPEC.md ausente em ${artifactPaths.spec}\n  Crie .oxe/SPEC.md com /oxe-spec no seu agente, ou use o template em oxe/templates/SPEC.template.md`);
+  if (!planText) throw new Error(`PLAN.md ausente em ${artifactPaths.plan}\n  Crie .oxe/PLAN.md com /oxe-plan no seu agente (requer SPEC.md), ou use o template em oxe/templates/PLAN.template.md`);
   const parsedSpec = parsers.parseSpec(specText);
   const parsedPlan = parsers.parsePlan(planText);
   const graph = runtime.compile(parsedPlan, parsedSpec, options.compilerOptions || {});
   const validationErrors = typeof runtime.validateGraph === 'function' ? runtime.validateGraph(graph) : [];
+
+  // Static-analysis lints: detect common patterns that cause runtime failures
+  const lintHints = lintPlanForCommonPitfalls(parsedPlan, parsedSpec, projectRoot, specText);
+  if (lintHints.length) validationErrors.push(...lintHints);
+
   const compiledGraph = runtime.toSerializable(graph);
   const current = options.runState || readRunState(projectRoot, activeSession) || {};
   const runId = current.run_id || makeRunId();
@@ -637,11 +722,108 @@ async function resolveRuntimeGate(projectRoot, activeSession, options = {}) {
   };
 }
 
-function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
-  const runtime = loadRuntimeModule();
-  const current = readRunState(projectRoot, activeSession);
-  const runId = options.runId || (current && current.run_id) || null;
-  if (!runId) {
+// Gap 5: route execution to MultiAgentCoordinator when plan-agents.json exists
+async function runRuntimeExecute(projectRoot, activeSession, options = {}) {
+  const runtime = loadRuntimeModule();
+  if (!runtime) throw new Error('Runtime package não está disponível. Rode npm run build:runtime.');
+  const parsers = loadSdkParsers();
+  if (!parsers) throw new Error('SDK parsers não disponíveis.');
+
+  // Auto-wire LlmTaskExecutor if providerConfig is supplied
+  let executor = options.executor || null;
+  if (!executor && options.providerConfig) {
+    if (typeof runtime.LlmTaskExecutor !== 'function') throw new Error('Runtime não exporta LlmTaskExecutor.');
+    executor = new runtime.LlmTaskExecutor(options.providerConfig, null, options.onProgress || null);
+  }
+  // Auto-wire InplaceWorkspaceManager as default
+  let workspaceManager = options.workspaceManager || null;
+  if (!workspaceManager) {
+    if (typeof runtime.InplaceWorkspaceManager === 'function') {
+      workspaceManager = new runtime.InplaceWorkspaceManager(projectRoot);
+    }
+  }
+
+  // Resolve compiled graph from run state or compile on demand
+  let current = options.runState || readRunState(projectRoot, activeSession);
+  if (!current || !current.compiled_graph) {
+    current = compileExecutionGraphFromArtifacts(projectRoot, activeSession, { runState: current }).run;
+  }
+  if (!current || !current.compiled_graph) {
+    throw new Error('Nenhum grafo compilado encontrado. Execute oxe-cc runtime compile primeiro.');
+  }
+  const graph = runtime.fromSerializable
+    ? runtime.fromSerializable(current.compiled_graph)
+    : current.compiled_graph;
+
+  // Detect plan-agents.json (session path takes priority over root)
+  const rootAgentPlan = path.join(projectRoot, '.oxe', 'plan-agents.json');
+  const sessAgentPlan = activeSession
+    ? path.join(projectRoot, '.oxe', activeSession, 'plan', 'plan-agents.json')
+    : null;
+  const agentPlanPath = (sessAgentPlan && fs.existsSync(sessAgentPlan))
+    ? sessAgentPlan
+    : (fs.existsSync(rootAgentPlan) ? rootAgentPlan : null);
+
+  // Build ctx with GateManager (Gap 1)
+  const ctx = createExecutionContext(projectRoot, activeSession, {
+    runId: current.run_id,
+    executor,
+    workspaceManager,
+    pluginRegistry: options.pluginRegistry || buildRuntimePluginRegistry(projectRoot),
+    schedulerOptions: options.schedulerOptions || {},
+    onEvent: (event) => {
+      appendEvent(projectRoot, activeSession, event);
+      options.onProgress?.(event);
+    },
+  });
+
+  // Gap 5: multi-agent path if plan-agents.json exists
+  if (agentPlanPath) {
+    let agentPlan;
+    try {
+      agentPlan = JSON.parse(fs.readFileSync(agentPlanPath, 'utf8'));
+    } catch (err) {
+      throw new Error(`plan-agents.json inválido: ${err.message}`);
+    }
+    if (!Array.isArray(agentPlan.agents) || agentPlan.agents.length === 0) {
+      throw new Error('plan-agents.json não contém agentes válidos (campo "agents" vazio ou ausente).');
+    }
+    if (typeof runtime.MultiAgentCoordinator !== 'function') {
+      throw new Error('Runtime não exporta MultiAgentCoordinator. Verifique a versão do runtime.');
+    }
+    const agents = agentPlan.agents.map((spec) => ({
+      id: spec.id,
+      executor: options.executorFactory ? options.executorFactory(spec) : (options.executor || null),
+      workspaceManager: options.workspaceManager || null,
+      assignedTaskIds: Array.isArray(spec.tasks) ? spec.tasks : [],
+    }));
+    const coordinator = new runtime.MultiAgentCoordinator();
+    const result = await coordinator.run(graph, {
+      mode: agentPlan.mode || 'parallel',
+      agents,
+      projectRoot,
+      sessionId: activeSession || null,
+      runId: current.run_id,
+      heartbeatTimeoutMs: options.heartbeatTimeoutMs ?? 120000,
+      onEvent: ctx.onEvent,
+    });
+    return { mode: agentPlan.mode || 'parallel', agentPlan, result, run: current };
+  }
+
+  // Single-agent fallback
+  if (typeof runtime.Scheduler !== 'function') {
+    throw new Error('Runtime não exporta Scheduler. Verifique a versão do runtime.');
+  }
+  const scheduler = new runtime.Scheduler();
+  const result = await scheduler.run(graph, ctx);
+  return { mode: 'single', agentPlan: null, result, run: current };
+}
+
+function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
+  const runtime = loadRuntimeModule();
+  const current = readRunState(projectRoot, activeSession);
+  const runId = options.runId || (current && current.run_id) || null;
+  if (!runId) {
     return {
       path: null,
       enabled: false,
@@ -649,40 +831,40 @@ function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
       mode: null,
       workspaceIsolationEnforced: false,
       agents: [],
-      ownership: [],
-      orphanReassignments: [],
-      handoffs: [],
-      arbitrationResults: [],
-      summary: null,
-    };
-  }
-  const runDir = path.join(projectRoot, '.oxe', 'runs', runId);
-  const statePath = path.join(runDir, 'multi-agent-state.json');
-  const summaryPath = path.join(runDir, 'multi-agent-summary.json');
-  const handoffsPath = path.join(runDir, 'handoffs.json');
-  const arbitrationPath = path.join(runDir, 'arbitration-results.json');
-  const state = runtime && typeof runtime.loadMultiAgentState === 'function'
-    ? runtime.loadMultiAgentState(projectRoot, runId)
-    : readJsonIfExists(statePath);
-  const summary = runtime && typeof runtime.loadMultiAgentSummary === 'function'
-    ? runtime.loadMultiAgentSummary(projectRoot, runId)
-    : readJsonIfExists(summaryPath);
-  const handoffs = readJsonIfExists(handoffsPath);
-  const arbitrationResults = readJsonIfExists(arbitrationPath);
-  return {
-    path: statePath,
-    enabled: Boolean(state),
+      ownership: [],
+      orphanReassignments: [],
+      handoffs: [],
+      arbitrationResults: [],
+      summary: null,
+    };
+  }
+  const runDir = path.join(projectRoot, '.oxe', 'runs', runId);
+  const statePath = path.join(runDir, 'multi-agent-state.json');
+  const summaryPath = path.join(runDir, 'multi-agent-summary.json');
+  const handoffsPath = path.join(runDir, 'handoffs.json');
+  const arbitrationPath = path.join(runDir, 'arbitration-results.json');
+  const state = runtime && typeof runtime.loadMultiAgentState === 'function'
+    ? runtime.loadMultiAgentState(projectRoot, runId)
+    : readJsonIfExists(statePath);
+  const summary = runtime && typeof runtime.loadMultiAgentSummary === 'function'
+    ? runtime.loadMultiAgentSummary(projectRoot, runId)
+    : readJsonIfExists(summaryPath);
+  const handoffs = readJsonIfExists(handoffsPath);
+  const arbitrationResults = readJsonIfExists(arbitrationPath);
+  return {
+    path: statePath,
+    enabled: Boolean(state),
     runId,
     mode: state && state.mode ? state.mode : null,
     workspaceIsolationEnforced: Boolean(state && state.workspace_isolation_enforced),
     agents: state && Array.isArray(state.agent_results) ? state.agent_results : [],
     ownership: state && Array.isArray(state.ownership) ? state.ownership : [],
-    orphanReassignments: state && Array.isArray(state.orphan_reassignments) ? state.orphan_reassignments : [],
-    handoffs: Array.isArray(handoffs) ? handoffs : [],
-    arbitrationResults: Array.isArray(arbitrationResults) ? arbitrationResults : [],
-    summary: summary || null,
-  };
-}
+    orphanReassignments: state && Array.isArray(state.orphan_reassignments) ? state.orphan_reassignments : [],
+    handoffs: Array.isArray(handoffs) ? handoffs : [],
+    arbitrationResults: Array.isArray(arbitrationResults) ? arbitrationResults : [],
+    summary: summary || null,
+  };
+}
 
 function loadRuntimeVerificationArtifacts(projectRoot, runState) {
   const runtime = loadRuntimeModule();
@@ -801,6 +983,11 @@ function buildRecoveryConsistency(projectRoot, activeSession, runState, journal,
   const runDir = runState && runState.run_id ? path.join(projectRoot, '.oxe', 'runs', runState.run_id) : null;
   const allEvents = readEvents(projectRoot, activeSession);
   const runEvents = runState && runState.run_id ? allEvents.filter((event) => event.run_id === runState.run_id) : [];
+  // Detect if execution has ever started (at least one attempt recorded)
+  const attemptCount = runState && runState.canonical_state && runState.canonical_state.summary
+    ? (runState.canonical_state.summary.attempt_count || 0)
+    : 0;
+  const executionStarted = attemptCount > 0;
   const issues = [];
   if (!activeRunRef || activeRunRef.run_id !== (runState && runState.run_id)) {
     issues.push('ACTIVE-RUN.json não referencia o mesmo run persistido em .oxe/runs/.');
@@ -808,10 +995,12 @@ function buildRecoveryConsistency(projectRoot, activeSession, runState, journal,
   if (!runFile || !fs.existsSync(runFile)) {
     issues.push('Arquivo canónico da run ausente em .oxe/runs/<run>.json.');
   }
-  if (!journal) {
+  // Journal is only created after execution starts — skip this check pre-execution
+  if (!journal && executionStarted) {
     issues.push('Journal ausente para recover/replay.');
   }
-  if (runEvents.length === 0) {
+  // Events for this run only exist after execution — skip pre-execution
+  if (runEvents.length === 0 && executionStarted) {
     issues.push('Nenhum evento NDJSON encontrado para a run ativa.');
   }
   if (!runState || !runState.canonical_state) {
@@ -1041,7 +1230,7 @@ function projectRuntimeArtifacts(projectRoot, activeSession, options = {}) {
   const paths = resolveRuntimeArtifactPaths(projectRoot, activeSession);
   const op = operationalPaths(projectRoot, activeSession);
   const projectionRefs = {
-    plan_ref: path.relative(projectRoot, paths.plan).replace(/\\/g, '/'),
+    plan_ref: path.relative(projectRoot, paths.plan.replace(/PLAN\.md$/, 'PLAN-STATUS.md')).replace(/\\/g, '/'),
     verify_ref: path.relative(projectRoot, paths.verify).replace(/\\/g, '/'),
     state_ref: path.relative(projectRoot, paths.state).replace(/\\/g, '/'),
     run_summary_ref: path.relative(projectRoot, path.join(op.executionRoot, 'RUN-SUMMARY.md')).replace(/\\/g, '/'),
@@ -1051,10 +1240,12 @@ function projectRuntimeArtifacts(projectRoot, activeSession, options = {}) {
     generated_at: new Date().toISOString(),
   };
   if (options.write !== false) {
-    ensureDirForFile(paths.plan);
+    // Write plan projection to PLAN-STATUS.md — never overwrite the source PLAN.md
+    const planStatusPath = paths.plan.replace(/PLAN\.md$/, 'PLAN-STATUS.md');
+    ensureDirForFile(planStatusPath);
     ensureDirForFile(paths.verify);
     ensureDirForFile(paths.state);
-    fs.writeFileSync(paths.plan, projections.plan + '\n', 'utf8');
+    fs.writeFileSync(planStatusPath, projections.plan + '\n', 'utf8');
     fs.writeFileSync(paths.verify, projections.verify + '\n', 'utf8');
     fs.writeFileSync(paths.state, projections.state + '\n', 'utf8');
     fs.writeFileSync(path.join(op.executionRoot, 'RUN-SUMMARY.md'), projections.runSummary + '\n', 'utf8');
@@ -2138,6 +2329,8 @@ module.exports = {
   buildRecoveryConsistency,
   readRuntimeGates,
   resolveRuntimeGate,
+  createExecutionContext,
+  runRuntimeExecute,
   runRuntimeVerify,
   projectRuntimeArtifacts,
   runRuntimeCiChecks,