@pulsehub/runner 0.1.11 → 0.1.12

package/README.md

@@ -105,3 +105,22 @@ Los ZIPs tienen un límite de 30 MiB comprimidos/256 MiB expandidos por repo;
 enlaces, archivos especiales y traversal se rechazan con diagnóstico visible.
 La limpieza y recuperación eliminan también snapshots interrumpidos de sólo
 lectura. Este protocolo requiere desplegar la versión compatible del backend.
+
+### Diagnóstico de QA Codex
+
+QA Codex usa `exec --json`. `runner.jsonl` registra la versión del CLI, los
+permisos efectivos, la presencia de la credencial (boolean), el número de
+snapshots y el ciclo de llamadas MCP a Pulse, correlacionados por `jobId`.
+Los eventos `codex.mcp.call` se originan en eventos del CLI, no en menciones
+al nombre de una herramienta dentro del texto del modelo. `hasResult` indica
+que llegó un resultado; no demuestra que la revisión se haya reclamado ni
+que el veredicto haya sido aceptado. Eso se verifica en el estado de Pulse.
+
+`codex.diagnostics.summary` cuenta llamadas iniciadas/completadas/fallidas,
+líneas malformadas y truncamiento de eventos. Cero llamadas observadas permite
+distinguir un proceso que termina sin usar MCP. Los mensajes de startup conocidos
+se convierten a estados fijos; stderr restante se cuenta en bytes. Argumentos,
+resultados, errores libres, prompts y transcripts nunca se guardan ni se envían
+en el reporte QA. Los nombres de herramientas desconocidas se registran como
+`other`. Las líneas se limitan a 256 KiB y se emiten como máximo 500 eventos
+más el resumen. Un fallo al escribir el diagnóstico no interrumpe el job.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsehub/runner",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Local, credential-safe Pulse Runner",
   "repository": {
     "type": "git",

package/src/diagnostics.js

@@ -0,0 +1,73 @@
+// Provider output is untrusted and can contain credentials. Only emit constants,
+// counts and explicitly approved Pulse tool names; never forward payload fields.
+const tools = new Set(['pulse_next_review', 'pulse_get_review_context', 'pulse_submit_review', 'pulse_report_review_incomplete', 'pulse_whoami', 'pulse_get_issue', 'pulse_get_project', 'pulse_list_comments']);
+export function codexDiagnostic(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (['thread.started', 'turn.started', 'turn.completed', 'turn.failed', 'error'].includes(value.type)) {
+    return { event: `codex.${value.type}` };
+  }
+  if (!['item.started', 'item.updated', 'item.completed'].includes(value.type)) return null;
+  const item = value.item;
+  if (item?.type !== 'mcp_tool_call' || item.server !== 'pulse') return null;
+  if (!['in_progress', 'completed', 'failed'].includes(item.status)) return null;
+  return { event: 'codex.mcp.call', lifecycle: value.type, server: 'pulse', tool: tools.has(item.tool) ? item.tool : 'other', status: item.status, hasResult: item.result != null, hasError: item.error != null };
+}
+
+export function codexDiagnostics(emit) {
+  let pending = '';
+  let dropping = false;
+  let lines = 0;
+  let malformed = 0;
+  let observed = 0;
+  let mcpStarted = 0;
+  let mcpCompleted = 0;
+  let mcpFailed = 0;
+  let emitted = 0;
+  const line = (raw) => {
+    lines++;
+    let value;
+    try { value = JSON.parse(raw); } catch { malformed++; return; }
+    const safe = codexDiagnostic(value);
+    if (!safe) return;
+    observed++;
+    if (safe.event === 'codex.mcp.call') {
+      if (safe.lifecycle === 'item.started') mcpStarted++;
+      if (safe.lifecycle === 'item.completed') {
+        if (safe.status === 'completed') mcpCompleted++;
+        else if (safe.status === 'failed') mcpFailed++;
+      }
+    }
+    if (emitted++ < 500) emit(safe);
+  };
+  return {
+    // Split by newline with a bounded buffer, even for huge or malformed lines.
+    push(chunk) {
+      for (const part of String(chunk).split(/(?<=\n)/)) {
+        const end = part.endsWith('\n');
+        if (!dropping) {
+          if (pending.length + part.length > 256 * 1024) { pending = ''; dropping = true; }
+          else pending += part;
+        }
+        if (end) {
+          if (dropping) { lines++; malformed++; } else line(pending);
+          pending = ''; dropping = false;
+        }
+      }
+    },
+    finish() {
+      if (dropping) { lines++; malformed++; } else if (pending) line(pending);
+      pending = ''; dropping = false;
+      const summary = { event: 'codex.diagnostics.summary', lines, malformed, observed, mcpStarted, mcpCompleted, mcpFailed, truncated: emitted > 500 };
+      emit(summary);
+      return summary;
+    },
+  };
+}
+
+// Classify startup stderr using constants only, without retaining messages.
+export function codexStartupDiagnostic(line) {
+  if (/^mcp: pulse ready\s*$/.test(line.trim())) return { event: 'codex.mcp.startup', server: 'pulse', status: 'ready' };
+  if (/^mcp: pulse failed:/.test(line.trim())) return { event: 'codex.mcp.startup', server: 'pulse', status: 'failed' };
+  if (/^error: unexpected argument /.test(line.trim())) return { event: 'codex.startup.error', category: 'cli_arguments' };
+  return null;
+}

package/src/process.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { mkdir, writeFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
+import { codexDiagnostics, codexStartupDiagnostic } from './diagnostics.js';
 
 export function command(executable, args, options = {}) {
   return new Promise((resolve, reject) => {
@@ -29,8 +30,10 @@ export function command(executable, args, options = {}) {
     options.signal?.addEventListener('abort', abort, { once: true });
     const timer = options.timeout ? setTimeout(abort, options.timeout) : null;
     let output = '';
-    const append = (chunk) => { output = (output + chunk).slice(-(options.maxOutput || 1_000_000)); };
-    child.stdout.on('data', append); child.stderr.on('data', append);
+    const append = (chunk) => { if (options.captureOutput !== false) output = (output + chunk).slice(-(options.maxOutput || 1_000_000)); };
+    child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { append(chunk); options.onStdout?.(chunk); });
+    child.stderr.on('data', (chunk) => { append(chunk); options.onStderr?.(chunk); });
     const cleanup = () => {
       if (timer) clearTimeout(timer);
       // Kill any descendants before releasing the process group on cancellation.
@@ -85,7 +88,7 @@ async function mcpConfig(dir, credential, endpoint) {
 export function providerInvocation(kind, worktree, additionalDirs, config, mcp, prompt, mode = 'task') {
   if (kind === 'codex') {
     const reviewArgs = mode === 'review'
-      ? ['--skip-git-repo-check', '-c', 'mcp_servers.pulse.default_tools_approval_mode="approve"']
+      ? ['--json', '--skip-git-repo-check', '-c', 'mcp_servers.pulse.default_tools_approval_mode="approve"']
       : [];
     return {
       executable: resolveExecutable('codex'),
@@ -117,6 +120,44 @@ export async function runAgent(kind, job, worktree, additionalWorktrees, config,
     const invocation = providerInvocation(kind, agentDirectory, additionalDirs, config, mcp, prompt, job.mode);
     if (options.profile?.model) invocation.args.splice(kind === 'codex' ? 1 : 0, 0, '--model', options.profile.model);
     const env = kind === 'codex' ? { ...process.env, PULSE_RUNNER_MCP_CREDENTIAL: `Bearer ${credential}` } : process.env;
-    return await command(invocation.executable, invocation.args, { cwd: agentDirectory, env, signal: options.signal });
+    const diagnosticMode = kind === 'codex' && job.mode === 'review';
+    let writes = Promise.resolve();
+    let stderrBytes = 0;
+    let stderrLine = '';
+    const stderrEvents = new Set();
+    const emit = (details) => {
+      // Keep order and drain writes before completion; sink failures are nonfatal.
+      writes = writes.then(() => options.onDiagnostic?.(details)).catch(() => {});
+    };
+    const diagnostics = diagnosticMode ? codexDiagnostics(emit) : null;
+    if (diagnosticMode) {
+      const version = await command(invocation.executable, ['--version'], { signal: options.signal, timeout: 10_000, maxOutput: 1000 }).catch(() => ({ output: '' }));
+      const cliVersion = /^codex-cli (\d+\.\d+\.\d+)\s*$/.exec(version.output.trim())?.[1] || 'unknown';
+      emit({ event: 'codex.startup', cliVersion, sandbox: 'read-only', ephemeral: true, json: true, mcpApproval: 'approve', credentialPresent: Boolean(credential), snapshotCount: reviewWorktrees.length });
+    }
+    try {
+      const result = await command(invocation.executable, invocation.args, { cwd: agentDirectory, env, signal: options.signal, captureOutput: !diagnosticMode, onStdout: diagnostics ? (chunk) => diagnostics.push(chunk) : undefined, onStderr: diagnosticMode ? (chunk) => {
+        stderrBytes += Buffer.byteLength(chunk);
+        for (const part of String(chunk).split(/(?<=\n)/)) {
+          stderrLine = (stderrLine + part).slice(-4096);
+          if (!part.endsWith('\n')) continue;
+          const safe = codexStartupDiagnostic(stderrLine);
+          stderrLine = '';
+          if (safe && !stderrEvents.has(JSON.stringify(safe))) { stderrEvents.add(JSON.stringify(safe)); emit(safe); }
+        }
+      } : undefined });
+      if (diagnostics) {
+        emit({ event: 'codex.process.exited', exitCode: result.code, stderrBytes });
+        const summary = diagnostics.finish();
+        result.output = `Codex QA: events=${summary.observed}, MCP started=${summary.mcpStarted}, completed=${summary.mcpCompleted}, failed=${summary.mcpFailed}, malformed=${summary.malformed}.`;
+      }
+      return result;
+    } catch (error) {
+      // Do not forward a spawn error that can include the executable's path.
+      if (!diagnosticMode) throw error;
+      diagnostics.finish();
+      emit({ event: 'codex.spawn.failed' });
+      throw new Error('Codex QA process could not start.');
+    } finally { await writes; }
   } finally { await rm(mcp, { force: true }); }
 }

package/src/runtime.js

@@ -235,7 +235,7 @@ export async function runOnce(config, options = {}) {
       controller.signal.throwIfAborted();
       jobPhase = 'run-agent';
       await logEvent('agent.started', { jobId: job.id, repo: primary.repo, mode: job.mode });
-      const result = await runAgent(agent.kind, job, primary.worktree, checkouts.filter((entry) => entry !== primary), config, delivery.mcpCredential, temp, { signal: controller.signal, profile });
+      const result = await runAgent(agent.kind, job, primary.worktree, checkouts.filter((entry) => entry !== primary), config, delivery.mcpCredential, temp, { signal: controller.signal, profile, onDiagnostic: ({ event, ...details }) => logEvent(event, { jobId: job.id, ...details }) });
       controller.signal.throwIfAborted();
       await checkActive();
       await logEvent(result.code === 0 ? 'agent.completed' : 'agent.failed', { jobId: job.id, exitCode: result.code, ...(result.code === 0 ? {} : { error: failureDetail(result.output) }) });

package/test/diagnostics.test.js

@@ -0,0 +1,55 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { codexDiagnostic, codexDiagnostics, codexStartupDiagnostic } from '../src/diagnostics.js';
+import { command, runAgent } from '../src/process.js';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+const secret = 'opaque-session-secret';
+const item = { id: secret, type: 'mcp_tool_call', server: 'pulse', tool: 'pulse_next_review', status: 'completed', arguments: { token: secret }, result: { content: [{ text: secret }] }, error: { message: secret } };
+
+test('only allow-listed metadata survives untrusted MCP payloads', () => {
+  assert.deepEqual(codexDiagnostic({ type: 'item.completed', item }), { event: 'codex.mcp.call', lifecycle: 'item.completed', server: 'pulse', tool: 'pulse_next_review', status: 'completed', hasResult: true, hasError: true });
+  for (const changes of [{ server: secret }, { status: secret }, { type: 'agent_message', text: secret }]) assert.equal(codexDiagnostic({ type: 'item.completed', item: { ...item, ...changes } }), null);
+  assert.equal(codexDiagnostic({ type: 'item.completed', item: { ...item, tool: secret } }).tool, 'other');
+  assert.deepEqual(codexDiagnostic({ type: 'turn.failed', error: { message: secret } }), { event: 'codex.turn.failed' });
+});
+test('split, malformed, oversized and final lines remain bounded and safe', () => {
+  const events = [], stream = codexDiagnostics(e => events.push(e));
+  const started = JSON.stringify({ type: 'item.started', item: { ...item, status: 'in_progress' } });
+  stream.push(started.slice(0,35)); stream.push(started.slice(35)+'\n');
+  stream.push(secret+'\n'); stream.push('x'.repeat(300_000)); stream.push('\n');
+  stream.push(JSON.stringify({ type: 'item.completed', item }));
+  const summary = stream.finish();
+  assert.equal(summary.mcpStarted,1); assert.equal(summary.mcpCompleted,1); assert.equal(summary.malformed,2);
+  assert(!JSON.stringify(events).includes(secret));
+});
+test('zero MCP calls and bounded emission are explicit', () => {
+  const events = [], stream = codexDiagnostics(e => events.push(e));
+  for (let i=0;i<600;i++) stream.push('{"type":"turn.started"}\n');
+  assert.equal(stream.finish().mcpStarted,0); assert.equal(events.length,501); assert.equal(events.at(-1).truncated,true);
+});
+test('QA child JSONL is observed and secrets in stdout/stderr are discarded on failure', async () => {
+  const root = await mkdtemp(join(tmpdir(),'pulse-diagnostics-')), previous = process.env.PULSE_RUNNER_CODEX_BIN;
+  try {
+    const fake = join(root,'codex.mjs');
+    await writeFile(fake, `if (process.argv.includes('--version')) console.log('codex-cli 0.159.2'); else { console.log(${JSON.stringify(JSON.stringify({ type:'item.started', item:{...item,status:'in_progress'} }))}); console.log(${JSON.stringify(JSON.stringify({ type:'item.completed',item:{...item,status:'failed'} }))}); console.error(${JSON.stringify(secret)}); process.exitCode=1; }`);
+    process.env.PULSE_RUNNER_CODEX_BIN=fake;
+    const events=[];
+    const result=await runAgent('codex',{mode:'review',issueId:'issue-fixture',repoFullName:'owner/repo'},root,[],{endpoint:'https://example.invalid'},secret,join(root,'temp'),{onDiagnostic:async e=>events.push(e)});
+    assert.equal(result.code,1); assert.equal(events[0].cliVersion,'0.159.2'); assert.equal(events.at(-1).mcpFailed,1);
+    assert(!JSON.stringify({result,events}).includes(secret));
+    assert.equal(events.find(e=>e.event==='codex.process.exited').stderrBytes,Buffer.byteLength(secret+'\n'));
+    assert.equal((await command(fake,[],{captureOutput:false})).output,'');
+  } finally {
+    if(previous===undefined) delete process.env.PULSE_RUNNER_CODEX_BIN; else process.env.PULSE_RUNNER_CODEX_BIN=previous;
+    await rm(root,{recursive:true,force:true});
+  }
+});
+
+test('startup stderr recognizes only fixed Pulse states and CLI incompatibility', () => {
+  assert.deepEqual(codexStartupDiagnostic('mcp: pulse ready'), {event:'codex.mcp.startup', server:'pulse', status:'ready'});
+  assert.deepEqual(codexStartupDiagnostic('mcp: pulse failed: '+secret), {event:'codex.mcp.startup', server:'pulse', status:'failed'});
+  assert.deepEqual(codexStartupDiagnostic('error: unexpected argument '+secret), {event:'codex.startup.error', category:'cli_arguments'});
+  assert.equal(codexStartupDiagnostic(secret),null);
+});

package/test/integration.test.js

@@ -255,6 +255,15 @@ for (const kind of ['codex','claude']) test(`integration: ${kind} QA reads all p
   assert.equal(f.calls.filter(c=>c.path==='/pulseQaSource' && c.body.repo).length,3);
   assert.equal(published,false);
   assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'completed');
+  if (kind === 'codex') {
+    const raw = await readFile(join(paths().logs, 'runner.jsonl'), 'utf8');
+    const events = raw.trim().split('\n').map(JSON.parse);
+    assert.equal(events.find(e => e.event === 'codex.startup').snapshotCount, 3);
+    assert.equal(events.find(e => e.event === 'codex.diagnostics.summary').jobId, f.job.id);
+    assert.equal(events.find(e => e.event === 'codex.diagnostics.summary').mcpStarted, 0);
+    assert(!raw.includes('fixture-secret'));
+    assert(!JSON.stringify(f.calls.find(c=>c.path==='/pulseRunnerComplete').body).includes('fixture-secret'));
+  }
 }));
 
 test('integration: signed multi-repo worktrees are passed to the adapter and all cleaned',()=>fixture('codex',async f=>{