@magnusekdahl/parallix 1.0.0

package/lib/agents/opencode-telemetry.js

@@ -0,0 +1,356 @@
+'use strict';
+
+/**
+ * Opencode Telemetry Parser
+ *
+ * Parses `opencode export` JSON output to extract real token-usage data for
+ * Qwen sessions. The exported JSON may contain token usage in various shapes
+ * depending on the opencode version, so this parser is resilient to:
+ *   - Missing token fields (substitutes 0)
+ *   - Nested vs flat structures
+ *   - Different field name conventions
+ *
+ * Provider and model fields are set to "opencode" and "qwen" respectively,
+ * matching the convention used by other telemetry modules.
+ *
+ * See task-1285 for the full telemetry credibility design.
+ */
+
+const PROVIDER = 'opencode';
+const MODEL = 'qwen';
+
+/**
+ * Safely extract a finite number from a value, defaulting to 0.
+ */
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Try to find token usage data anywhere in a parsed JSON object.
+ * Searches common nesting paths used by opencode export JSON.
+ *
+ * @param {object} obj - Parsed JSON object
+ * @returns {object|null} Normalized token usage object or null
+ */
+function findTokenUsage(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+
+  // Direct token usage fields at top level
+  if ('input_tokens' in obj || 'output_tokens' in obj) {
+    return {
+      input_tokens: obj.input_tokens,
+      output_tokens: obj.output_tokens,
+      cached_input_tokens: obj.cached_input_tokens || obj.cached_tokens || 0,
+      total_tokens: obj.total_tokens || 0,
+    };
+  }
+
+  // Nested under total_token_usage (Codex-compatible shape)
+  if (obj.total_token_usage && typeof obj.total_token_usage === 'object') {
+    return {
+      input_tokens: obj.total_token_usage.input_tokens || 0,
+      output_tokens: obj.total_token_usage.output_tokens || 0,
+      cached_input_tokens: obj.total_token_usage.cached_input_tokens || obj.total_token_usage.cached_tokens || 0,
+      total_tokens: obj.total_token_usage.total_tokens || 0,
+    };
+  }
+
+  // Nested under token_usage
+  if (obj.token_usage && typeof obj.token_usage === 'object') {
+    return {
+      input_tokens: obj.token_usage.input_tokens || 0,
+      output_tokens: obj.token_usage.output_tokens || 0,
+      cached_input_tokens: obj.token_usage.cached_input_tokens || obj.token_usage.cached_tokens || 0,
+      total_tokens: obj.token_usage.total_tokens || 0,
+    };
+  }
+
+  // Nested under usage
+  if (obj.usage && typeof obj.usage === 'object') {
+    return {
+      input_tokens: obj.usage.input_tokens || 0,
+      output_tokens: obj.usage.output_tokens || 0,
+      cached_input_tokens: obj.usage.cached_input_tokens || obj.usage.cached_tokens || 0,
+      total_tokens: obj.usage.total_tokens || 0,
+    };
+  }
+
+  // Nested under meta or metadata
+  if ((obj.meta || obj.metadata) && typeof (obj.meta || obj.metadata) === 'object') {
+    const meta = obj.meta || obj.metadata;
+    if ('input_tokens' in meta || 'output_tokens' in meta) {
+      return {
+        input_tokens: meta.input_tokens || 0,
+        output_tokens: meta.output_tokens || 0,
+        cached_input_tokens: meta.cached_input_tokens || meta.cached_tokens || 0,
+        total_tokens: meta.total_tokens || 0,
+      };
+    }
+    if (meta.total_token_usage && typeof meta.total_token_usage === 'object') {
+      return {
+        input_tokens: meta.total_token_usage.input_tokens || 0,
+        output_tokens: meta.total_token_usage.output_tokens || 0,
+        cached_input_tokens: meta.total_token_usage.cached_input_tokens || meta.total_token_usage.cached_tokens || 0,
+        total_tokens: meta.total_token_usage.total_tokens || 0,
+      };
+    }
+  }
+
+  // Nested under info (opencode v2.x export format)
+  // Shape: { info: { tokens: { input, output, cache: { read, write }, reasoning } } }
+  if (obj.info && typeof obj.info === 'object' && obj.info.tokens && typeof obj.info.tokens === 'object') {
+    const t = obj.info.tokens;
+    if ('input' in t || 'output' in t) {
+      return {
+        input_tokens: t.input || 0,
+        output_tokens: t.output || 0,
+        cached_input_tokens: (t.cache && typeof t.cache === 'object') ? (t.cache.read || 0) : 0,
+        total_tokens: t.input + t.output || 0,
+      };
+    }
+  }
+
+  // Search recursively through array elements (e.g., events array)
+  for (const key of Object.keys(obj)) {
+    const val = obj[key];
+    if (Array.isArray(val)) {
+      for (const item of val) {
+        if (item && typeof item === 'object') {
+          const found = findTokenUsage(item);
+          if (found) return found;
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract a sessionId from parsed opencode export JSON.
+ *
+ * @param {object} parsed - Parsed JSON object
+ * @returns {string|null} Session ID or null
+ */
+function extractSessionId(parsed) {
+  if (!parsed || typeof parsed !== 'object') return null;
+
+  // Direct session_id
+  if (parsed.session_id) return String(parsed.session_id);
+  if (parsed.sessionId) return String(parsed.sessionId);
+
+  // Nested under info (opencode v2.x export format)
+  if (parsed.info && typeof parsed.info === 'object') {
+    if (parsed.info.id) return String(parsed.info.id);
+  }
+
+  // Nested in metadata/meta/session
+  if (parsed.metadata && typeof parsed.metadata === 'object') {
+    if (parsed.metadata.session_id) return String(parsed.metadata.session_id);
+    if (parsed.metadata.sessionId) return String(parsed.metadata.sessionId);
+  }
+  if (parsed.meta && typeof parsed.meta === 'object') {
+    if (parsed.meta.session_id) return String(parsed.meta.session_id);
+    if (parsed.meta.sessionId) return String(parsed.meta.sessionId);
+  }
+  if (parsed.session && typeof parsed.session === 'object') {
+    if (parsed.session.id) return String(parsed.session.id);
+    if (parsed.session.session_id) return String(parsed.session.session_id);
+  }
+
+  return null;
+}
+
+/**
+ * Extract a model name from parsed opencode export JSON.
+ *
+ * @param {object} parsed - Parsed JSON object
+ * @returns {string|null} Model name or null
+ */
+function extractModelName(parsed) {
+  if (!parsed || typeof parsed !== 'object') return null;
+
+  // Direct model fields
+  if (parsed.model) return String(parsed.model);
+  if (parsed.model_name) return String(parsed.model_name);
+
+  // Nested under info.model (opencode v2.x format)
+  if (parsed.info && typeof parsed.info === 'object' && parsed.info.model && typeof parsed.info.model === 'object') {
+    if (parsed.info.model.id) return String(parsed.info.model.id);
+    if (parsed.info.model.name) return String(parsed.info.model.name);
+  }
+
+  // Nested in metadata/meta/session
+  if (parsed.metadata && typeof parsed.metadata === 'object') {
+    if (parsed.metadata.model) return String(parsed.metadata.model);
+    if (parsed.metadata.model_name) return String(parsed.metadata.model_name);
+  }
+  if (parsed.meta && typeof parsed.meta === 'object') {
+    if (parsed.meta.model) return String(parsed.meta.model);
+  }
+  if (parsed.session && typeof parsed.session === 'object') {
+    if (parsed.session.model) return String(parsed.session.model);
+  }
+
+  return null;
+}
+
+/**
+ * Count tool calls from parsed opencode export JSON.
+ *
+ * @param {object} parsed - Parsed JSON object
+ * @returns {number} Tool call count
+ */
+function countToolCalls(parsed) {
+  if (!parsed || typeof parsed !== 'object') return 0;
+
+  let count = 0;
+
+  // Direct tool_calls field
+  if (typeof parsed.tool_calls === 'number') count += parsed.tool_calls;
+  if (typeof parsed.toolCalls === 'number') count += parsed.toolCalls;
+  if (typeof parsed.usage?.tool_calls === 'number') count += parsed.usage.tool_calls;
+
+  // Real opencode v2.x export schema: tool calls live in
+  // messages[].parts[] where part.type === 'tool'.
+  if (Array.isArray(parsed.messages)) {
+    for (const msg of parsed.messages) {
+      if (msg && typeof msg === 'object' && Array.isArray(msg.parts)) {
+        for (const part of msg.parts) {
+          if (part && typeof part === 'object' && part.type === 'tool') count += 1;
+        }
+      }
+    }
+  }
+
+  // Nested arrays of tool calls
+  if (Array.isArray(parsed.events)) {
+    for (const evt of parsed.events) {
+      if (evt && typeof evt === 'object') {
+        if (evt.type === 'tool_use') count += 1;
+        if (evt.type === 'tool_call') count += 1;
+        if (evt.type === 'function_call') count += 1;
+        if (Array.isArray(evt.tool_calls)) count += evt.tool_calls.length;
+        if (Array.isArray(evt.content_block_start)) {
+          for (const cb of evt.content_block_start) {
+            if (cb && cb.type === 'tool_use') count += 1;
+          }
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(parsed.tool_use_events)) {
+    count += parsed.tool_use_events.length;
+  }
+
+  return count;
+}
+
+/**
+ * Parse an `opencode export` JSON string and return a normalized telemetry
+ * object compatible with `stats.telemetryToStatsFields()`.
+ *
+ * Returns null when the content yields no usable token signal (empty string,
+ * non-JSON, or JSON without any token-usage fields).
+ *
+ * @param {string} jsonString - Raw JSON string from `opencode export`
+ * @returns {object|null} Normalized telemetry object or null
+ */
+function extractOpencodeTelemetryFromExport(jsonString) {
+  if (!jsonString || typeof jsonString !== 'string' || !jsonString.trim()) {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonString);
+  } catch (_) {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+
+  const tokenUsage = findTokenUsage(parsed);
+  if (!tokenUsage) {
+    return null;
+  }
+
+  // Verify there is at least some non-zero token data
+  const inputTokens = num(tokenUsage.input_tokens);
+  const outputTokens = num(tokenUsage.output_tokens);
+  const cachedTokens = num(tokenUsage.cached_input_tokens);
+
+  // If all tokens are zero, treat as no signal (unless total_tokens explicitly exists and is non-zero)
+  if (inputTokens === 0 && outputTokens === 0 && cachedTokens === 0) {
+    if (num(tokenUsage.total_tokens) === 0) {
+      return null;
+    }
+    // total_tokens is set but individual fields are zero — treat total_tokens as the real signal
+    // and derive input/output from it conservatively
+    const totalTokens = num(tokenUsage.total_tokens);
+    return {
+      sessionId: extractSessionId(parsed),
+      provider: PROVIDER,
+      model: extractModelName(parsed) || MODEL,
+      inputTokens: 0,
+      outputTokens: 0,
+      cachedTokens: 0,
+      totalTokens,
+      toolCalls: countToolCalls(parsed),
+      usagePercent: null,
+    };
+  }
+
+  const totalTokens = num(tokenUsage.total_tokens) || (inputTokens + outputTokens);
+
+  return {
+    sessionId: extractSessionId(parsed),
+    provider: PROVIDER,
+    model: extractModelName(parsed) || MODEL,
+    inputTokens,
+    outputTokens,
+    cachedTokens,
+    totalTokens,
+    toolCalls: countToolCalls(parsed),
+    usagePercent: null,
+  };
+}
+
+/**
+ * Attempt to extract telemetry from an opencode launcher result.
+ * Deprecated — use extractOpencodeTelemetryFromExport directly.
+ * Kept for backward compatibility with existing call sites.
+ *
+ * @param {object} result - The launcher result object
+ * @returns {object|null} Telemetry object or null
+ */
+function extractOpencodeTelemetry(result) {
+  if (result && result.exportJson && typeof result.exportJson === 'string') {
+    return extractOpencodeTelemetryFromExport(result.exportJson);
+  }
+  if (result && result.telemetry) {
+    return result.telemetry;
+  }
+  return null;
+}
+
+/**
+ * Return the provider/model pair for opencode tasks.
+ * Used as fallback when telemetry is null.
+ *
+ * @returns {{provider: string, model: string}}
+ */
+function getOpencodeProviderModel() {
+  return { provider: PROVIDER, model: MODEL };
+}
+
+module.exports = {
+  extractOpencodeTelemetryFromExport,
+  extractOpencodeTelemetry,
+  getOpencodeProviderModel,
+  parseOpencodeExport: extractOpencodeTelemetryFromExport,
+};

package/lib/agents/opencode.js

@@ -0,0 +1,218 @@
+const { spawnAndTee } = require('../core/spawn-tee');
+const { extractOpencodeTelemetryFromExport } = require('./opencode-telemetry');
+const { captureOpencodeExport } = require('./opencode-export');
+const sessions = require('../tools/sessions');
+const { detectLimitHit } = require('./limit-hit');
+
+// Injectable I/O for tests. Production uses the real spawn-tee / export capture.
+let _spawnAndTee = spawnAndTee;
+let _captureExport = captureOpencodeExport;
+let _sessions = sessions;
+
+// Test hooks: override the launcher's I/O without touching the public signature.
+function __setSpawnAndTeeForTest(fn) { _spawnAndTee = fn || spawnAndTee; }
+function __setExportCaptureForTest(fn) { _captureExport = fn || captureOpencodeExport; }
+function __setSessionsForTest(mod) { _sessions = mod || sessions; }
+
+// Opencode outputs "Continue  opencode -s ses_<id>" at the end.
+// Telemetry: after session completion, `opencode export` is invoked to extract
+// token-usage data. See opencode-telemetry.js for the parser.
+// Stats hooks in active.js and review-loop.js call recordStageStats which
+// defaults to '0' for tokens when telemetry is null.
+const OPENCODE_SESSION_ID_RE = /opencode\s+-s\s+(ses_\S+)/i;
+
+function extractOpencodeSessionId(stdout) {
+  if (!stdout) return null;
+  const m = OPENCODE_SESSION_ID_RE.exec(stdout);
+  return m ? m[1] : null;
+}
+
+function resolveOpencodeCommand() {
+  return 'opencode';
+}
+
+function buildOpencodeInvocation({ prompt, worktree, env, resume = false, sessionId = null, model = null }) {
+  const args = ['run', '--pure', '--dangerously-skip-permissions'];
+  if (model) args.push('-m', model);
+  // Only resume when the marker explicitly says so (resume=true).
+  // sessionId from a stale cross-family marker must be ignored when resume=false.
+  if (resume && sessionId) {
+    args.push('-s', sessionId);
+  } else if (resume) {
+    args.push('--continue');
+  }
+  args.push(prompt);
+  return {
+    command: resolveOpencodeCommand(),
+    args,
+    options: {
+      stdio: 'inherit',
+      cwd: worktree,
+      env: { ...process.env, ...env }
+    }
+  };
+}
+
+// Transient qwen/vLLM backend failures that opencode surfaces as a non-zero
+// exit. These are recoverable: the same prompt frequently succeeds on a second
+// attempt, so the launcher retries once in-family before agents.js reroutes to a
+// different agent family. Limit-hit phrases are intentionally NOT listed here —
+// detectLimitHit() in agents.js owns that accounting (lib/agents/limit-hit.js).
+// Hard errors (model-not-found, auth, ENOENT/EACCES) are never retried.
+const TRANSIENT_OPENCODE_PATTERNS = [
+  /\bECONNRESET\b/i,
+  /\bECONNREFUSED\b/i,
+  /\bETIMEDOUT\b/i,
+  /\bENETUNREACH\b/i,
+  /\bENOTFOUND\b/i,
+  /\bEAI_AGAIN\b/i,
+  /\bEPIPE\b/i,
+  /socket hang ?up/i,
+  /\bfetch failed\b/i,
+  /network (?:error|timeout)/i,
+  /connection (?:error|reset|closed|refused|timed? ?out)/i,
+  /\b(?:502|503|504|529)\b/,
+  /\bbad gateway\b/i,
+  /\bservice (?:is )?unavailable\b/i,
+  /\bgateway time-?out\b/i,
+  /\b(?:server |api |model )?overloaded\b/i,
+  /\btemporarily unavailable\b/i,
+  /\bplease (?:try|retry) again\b/i,
+  /\bretry[- ]after\b/i,
+];
+
+// Hard, non-retryable failures: retrying cannot help and only wastes time/quota.
+const HARD_OPENCODE_PATTERNS = [
+  /\bmodel not found\b/i,
+  /\bno such model\b/i,
+  /\bunknown model\b/i,
+  /\binvalid (?:api )?key\b/i,
+  /\b401\b[^\n]*\bunauthorized\b/i,
+  /\bauthentication (?:failed|error)\b/i,
+];
+
+function failureText(result) {
+  return `${(result && result.stdout) || ''}\n${(result && result.stderr) || ''}`;
+}
+
+function isHardOpencodeFailure(result) {
+  if (!result) return false;
+  if (result.error && (result.error.code === 'ENOENT' || result.error.code === 'EACCES')) return true;
+  const text = failureText(result);
+  return HARD_OPENCODE_PATTERNS.some((re) => re.test(text));
+}
+
+function isTransientOpencodeFailure(result) {
+  if (!result) return false;
+  const text = failureText(result);
+  return TRANSIENT_OPENCODE_PATTERNS.some((re) => re.test(text));
+}
+
+// Decide whether a failed opencode run should be retried once in-family.
+// Only genuine non-zero exits carrying a transient backend signature qualify;
+// clean exits, spawn errors (ENOENT/EACCES), killing signals, limit-hits, and
+// hard errors never retry — so real failures still surface to the reroute loop.
+function shouldRetryOpencodeFailure(result) {
+  if (!result) return false;
+  if (result.error && (result.error.code === 'ENOENT' || result.error.code === 'EACCES')) return false;
+  if (result.signal) return false;
+  if (!(typeof result.status === 'number' && result.status !== 0)) return false;
+  if (detectLimitHit({
+    agent: 'qwen',
+    stdout: result.stdout,
+    stderr: result.stderr,
+    status: result.status,
+    signal: result.signal,
+    error: result.error,
+  })) return false;
+  if (isHardOpencodeFailure(result)) return false;
+  return isTransientOpencodeFailure(result);
+}
+
+function startOpencodeAgent({
+  prompt,
+  worktree,
+  env,
+  resume = false,
+  sessionId = null,
+  model = null,
+  teeOptions = {},
+  slug = null,
+  role = null,
+  maxTransientRetries = 1
+}) {
+  function isStaleSessionResult(result) {
+    if (!result) return false;
+    const stderr = result.stderr || '';
+    const stdout = result.stdout || '';
+    return stderr.includes('Session not found') || stdout.includes('Session not found');
+  }
+
+  function runInvocation(invocation) {
+    const spawnOptions = { ...invocation.options, ...teeOptions };
+    return _spawnAndTee(invocation.command, invocation.args, spawnOptions);
+  }
+
+  async function runInvocationWithRetry(invocation) {
+    let attempts = 0;
+    let result = await runInvocation(invocation);
+    while (attempts < maxTransientRetries && shouldRetryOpencodeFailure(result)) {
+      attempts += 1;
+      result = await runInvocation(invocation);
+    }
+    if (result) result.transientRetries = attempts;
+    return result;
+  }
+
+  async function processResult(result) {
+    if (result && result.stdout) {
+      result.sessionId = extractOpencodeSessionId(result.stdout);
+    }
+    if (result && result.sessionId) {
+      try {
+        const exportJson = await _captureExport(result.sessionId, { worktree, env });
+        if (exportJson) {
+          const telemetry = extractOpencodeTelemetryFromExport(exportJson);
+          if (telemetry) {
+            result.telemetry = telemetry;
+            if (telemetry.model) result.model = telemetry.model;
+            if (telemetry.provider) result.provider = telemetry.provider;
+          }
+        }
+      } catch (_) {
+        return result;
+      }
+    }
+    return result;
+  }
+
+  async function staleSessionHandler(invocation) {
+    let result = await runInvocationWithRetry(invocation);
+    if (isStaleSessionResult(result) && worktree && resume) {
+      try {
+        _sessions.clearSession(worktree, slug, role);
+      } catch (_) { /* best-effort */ }
+      const freshInv = buildOpencodeInvocation({ prompt, worktree, env, resume: false, sessionId: null, model });
+      result = await runInvocationWithRetry(freshInv);
+    }
+    return processResult(result);
+  }
+
+  const invocation = buildOpencodeInvocation({ prompt, worktree, env, resume, sessionId, model });
+  const resultPromise = staleSessionHandler(invocation);
+
+  return { invocation, resultPromise };
+}
+
+module.exports = {
+  buildOpencodeInvocation,
+  extractOpencodeSessionId,
+  resolveOpencodeCommand,
+  startOpencodeAgent,
+  isTransientOpencodeFailure,
+  isHardOpencodeFailure,
+  shouldRetryOpencodeFailure,
+  __setSpawnAndTeeForTest,
+  __setExportCaptureForTest,
+  __setSessionsForTest
+};

package/lib/agents/stage-telemetry.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// Shared resolution of the most faithful telemetry for a recorded workflow
+// stage (execute/review). Codex's authoritative usage is the windowed sum read
+// from its on-disk rollout — `sinceMs` bounds the read to just this stage — so
+// prefer it when present. For non-Codex agents (e.g. Claude, whose usage the
+// launcher parses from stdout via claude-telemetry.js) no codex rollout exists
+// and extractCodexTelemetry returns null *without throwing*, so we fall back to
+// the telemetry the launcher already attached.
+//
+// This lives in one place so the execute hook (commands/active.js) and the
+// review-loop hook (review/review-loop.js) cannot drift apart — the bug this
+// fixes was active.js computing `sinceMs` and then discarding it, recording
+// cumulative Codex usage for the execute phase instead of the windowed delta
+// (task-1285 review F1/F6).
+
+const { codexHomeRoot, extractCodexTelemetry } = require('./codex');
+
+/**
+ * @param {object} opts
+ * @param {string} opts.worktree - worktree root used to locate the codex home.
+ * @param {object} opts.result - launcher result; `result.telemetry` is the
+ *   launcher-attached fallback and `result.startedAt` bounds the codex window.
+ * @param {number} [opts.sinceMs] - epoch ms marking the start of this stage.
+ * @returns {object|null} normalized telemetry, or null when none is available.
+ */
+function resolveStageTelemetry({ worktree, result, sinceMs = 0 } = {}) {
+  if (!result || !result.telemetry) return null;
+  try {
+    return extractCodexTelemetry(codexHomeRoot(worktree), { sinceMs: sinceMs || 0 }) || result.telemetry;
+  } catch (_) {
+    // Codex rollout unreadable: fall back to this stage's launcher telemetry.
+    return result.telemetry;
+  }
+}
+
+module.exports = { resolveStageTelemetry };