@magnusekdahl/parallix 1.0.0

package/lib/agents/claude-telemetry.js

@@ -0,0 +1,233 @@
+'use strict';
+
+// Claude telemetry is read from the Claude CLI's `--output-format stream-json`
+// stdout stream (see claude.js `buildClaudeInvocation`). Unlike Codex — which
+// writes a per-session rollout JSONL to disk — the Claude CLI emits its usage
+// signal inline on stdout as SSE-style JSONL events, so we parse the captured
+// stdout tail directly (no on-disk transcript to read).
+//
+// The CLI runs with `--include-partial-messages`, so the Anthropic SSE events
+// are forwarded as JSONL. Two envelope shapes are handled:
+//
+//   1. Wrapped (real CLI form): each partial event is nested under a
+//      `stream_event` wrapper:
+//        {"type":"stream_event","event":{"type":"message_start","message":{"usage":{...}}}}
+//        {"type":"stream_event","event":{"type":"message_delta","usage":{"output_tokens":N}}}
+//        {"type":"stream_event","event":{"type":"content_block_start","content_block":{"type":"tool_use"}}}
+//   2. Raw (bare SSE form): the Anthropic event sits at the top level:
+//        {"type":"message_start","message":{"usage":{...}}}
+//        {"type":"message_delta","usage":{"output_tokens":N}}
+//
+// The CLI also emits top-level `system` (init), `assistant`, and `result`
+// events; `system`/`result` carry `session_id` and `model`, and `result`
+// carries a final aggregate `usage` used as a fallback when partial events were
+// truncated out of the captured stdout tail.
+//
+// Token semantics (Anthropic streaming):
+//   - `message_start.usage.input_tokens` is the prompt size for that turn. A
+//     multi-turn (tool-use) invocation re-sends the growing context each turn,
+//     so summing every turn's input would multi-count the shared prompt. We take
+//     the FIRST message_start's input_tokens as the representative prompt size.
+//   - `message_delta.usage.output_tokens` is the FINAL cumulative output count
+//     for that one message. Across turns these are independent generations, so
+//     the stage's total generated output is the SUM of each turn's final value.
+//   - `cache_read_input_tokens` / `cache_creation_input_tokens` appear on
+//     message_start.usage when prompt caching is active; summed across turns.
+
+const PROVIDER = 'anthropic';
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Unwrap a parsed JSONL line into its underlying Anthropic SSE event. The CLI's
+ * `--include-partial-messages` form nests the real event under `stream_event`;
+ * the bare form has it at the top level. Returns the inner event object.
+ */
+function unwrapEvent(evt) {
+  if (evt && evt.type === 'stream_event' && evt.event && typeof evt.event === 'object') {
+    return evt.event;
+  }
+  return evt;
+}
+
+/**
+ * Parse a Claude `stream-json` stdout string into a normalized structure of the
+ * usage-bearing events. Returns null when the content yields no usable signal
+ * (e.g. empty, garbage, or a stream with no usage events at all).
+ *
+ * Shape:
+ *   {
+ *     sessionId, model, provider: 'anthropic',
+ *     messageStarts: [{ inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, model }],
+ *     messageDeltas: [{ outputTokens }],
+ *     toolCalls,
+ *     resultUsage: { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens } | null
+ *   }
+ */
+function parseClaudeStreamJson(content) {
+  if (!content) return null;
+
+  let sessionId = null;
+  let model = null;
+  let toolCalls = 0;
+  let resultUsage = null;
+  let resultCostUsd = null;
+  const messageStarts = [];
+  const messageDeltas = [];
+
+  for (const line of String(content).split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{')) continue;
+    let outer;
+    try {
+      outer = JSON.parse(trimmed);
+    } catch (_) {
+      continue;
+    }
+    if (!outer || typeof outer !== 'object') continue;
+
+    // Top-level CLI envelope fields (present on system/result and sometimes the
+    // wrapper) carry session/model metadata.
+    if (outer.session_id) sessionId = outer.session_id;
+    if (outer.type === 'system' && outer.model) model = outer.model;
+
+    // The final `result` event carries `total_cost_usd` (direct from the CLI)
+    // and an aggregate usage object (fallback when partial events were evicted).
+    if (outer.type === 'result') {
+      if (outer.usage && typeof outer.usage === 'object') {
+        resultUsage = {
+          inputTokens: num(outer.usage.input_tokens),
+          outputTokens: num(outer.usage.output_tokens),
+          cacheReadTokens: num(outer.usage.cache_read_input_tokens),
+          cacheCreationTokens: num(outer.usage.cache_creation_input_tokens),
+        };
+      }
+      if (typeof outer.total_cost_usd === 'number' && Number.isFinite(outer.total_cost_usd)) {
+        resultCostUsd = outer.total_cost_usd;
+      }
+    }
+
+    const evt = unwrapEvent(outer);
+    if (!evt || typeof evt !== 'object') continue;
+
+    switch (evt.type) {
+      case 'message_start': {
+        const message = evt.message || {};
+        const usage = message.usage || {};
+        if (message.model) model = message.model;
+        messageStarts.push({
+          inputTokens: num(usage.input_tokens),
+          outputTokens: num(usage.output_tokens),
+          cacheReadTokens: num(usage.cache_read_input_tokens),
+          cacheCreationTokens: num(usage.cache_creation_input_tokens),
+          model: message.model || null,
+        });
+        break;
+      }
+      case 'message_delta': {
+        const usage = evt.usage || {};
+        messageDeltas.push({ outputTokens: num(usage.output_tokens) });
+        break;
+      }
+      case 'content_block_start': {
+        const block = evt.content_block || {};
+        if (block.type === 'tool_use') toolCalls += 1;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const hasSignal = messageStarts.length > 0 || messageDeltas.length > 0 || resultUsage || model || sessionId;
+  if (!hasSignal) return null;
+
+  return {
+    sessionId,
+    model: model || null,
+    provider: PROVIDER,
+    messageStarts,
+    messageDeltas,
+    toolCalls,
+    resultUsage,
+    resultCostUsd,
+  };
+}
+
+/**
+ * Aggregate token counts from a Claude `stream-json` stdout stream into a
+ * telemetry object compatible with `stats.telemetryToStatsFields()`.
+ *
+ * Aggregation rules (see token-semantics note at top of file):
+ *   - inputTokens  = first message_start's input_tokens (representative prompt
+ *                    size; avoids multi-counting the re-sent context across
+ *                    tool-use turns).
+ *   - outputTokens = sum of every message_delta's output_tokens (total
+ *                    generation across all turns).
+ *   - cachedTokens = sum of message_start cache_read_input_tokens across turns.
+ *   - totalTokens  = inputTokens + outputTokens.
+ *
+ * When partial events are absent (e.g. truncated stdout tail) but a `result`
+ * event survived, its aggregate usage is used as a fallback.
+ *
+ * Returns null when the stream yields no usable token signal.
+ */
+function extractClaudeTelemetryFromStdout(stdout) {
+  const parsed = parseClaudeStreamJson(stdout);
+  if (!parsed) return null;
+
+  const { messageStarts, messageDeltas, resultUsage, resultCostUsd } = parsed;
+
+  let inputTokens = messageStarts.length > 0 ? messageStarts[0].inputTokens : 0;
+  let outputTokens = messageDeltas.reduce((sum, d) => sum + d.outputTokens, 0);
+  let cachedTokens = messageStarts.reduce((sum, s) => sum + s.cacheReadTokens, 0);
+  let cacheCreationTokens = messageStarts.reduce((sum, s) => sum + s.cacheCreationTokens, 0);
+
+  // If partial events were truncated out of the captured tail, fall back to the
+  // final `result` event's aggregate usage so we still record real numbers.
+  if (inputTokens === 0 && outputTokens === 0 && resultUsage) {
+    inputTokens = resultUsage.inputTokens;
+    outputTokens = resultUsage.outputTokens;
+    cachedTokens = resultUsage.cacheReadTokens;
+    cacheCreationTokens = resultUsage.cacheCreationTokens;
+  }
+
+  // NOTE: a small `inputTokens` (even 1) alongside a large `cachedTokens` is NOT
+  // an artifact — it is normal prompt caching. Anthropic streaming reports only
+  // the *uncached* prompt delta as `message_start.usage.input_tokens`; the bulk
+  // of the re-sent context is billed under `cache_read_input_tokens`. We keep
+  // the parsed value truthful and surface caching honestly in the stats render
+  // rather than rewriting telemetry here (see lib/commands/stats.js render).
+
+  // No token signal at all (only metadata events): not worth a telemetry row.
+  if (inputTokens === 0 && outputTokens === 0 && cachedTokens === 0 && cacheCreationTokens === 0) {
+    return null;
+  }
+
+  return {
+    sessionId: parsed.sessionId,
+    provider: parsed.provider,
+    model: parsed.model,
+    effort: null,
+    inputTokens,
+    outputTokens,
+    cachedTokens,
+    cacheCreationTokens,
+    reasoningTokens: 0,
+    totalTokens: inputTokens + outputTokens,
+    contextWindow: 0,
+    toolCalls: parsed.toolCalls,
+    // Claude's CLI exposes no rate-limit percentage (unlike Codex); leave null
+    // so telemetryToStatsFields records openai_usage_after as 0.
+    usagePercent: null,
+    // total_cost_usd is emitted directly by the Claude CLI in the result event.
+    cost_usd: typeof resultCostUsd === 'number' ? resultCostUsd : 0,
+  };
+}
+
+module.exports = {
+  parseClaudeStreamJson,
+  extractClaudeTelemetryFromStdout,
+};

package/lib/agents/claude.js

@@ -0,0 +1,139 @@
+const { spawnAndTee } = require('../core/spawn-tee');
+const { extractClaudeTelemetryFromStdout } = require('./claude-telemetry');
+const sessions = require('../tools/sessions');
+
+// Injectable I/O for tests. Production uses the real spawn-tee / export capture.
+let _spawnAndTee = spawnAndTee;
+let _sessions = sessions;
+
+// Test hooks: override the launcher's I/O without touching the public signature.
+function __setSpawnAndTeeForTest(fn) { _spawnAndTee = fn || spawnAndTee; }
+function __setSessionsForTest(mod) { _sessions = mod || sessions; }
+
+// Claude usage telemetry is parsed from the `stream-json` stdout stream, which
+// carries `message_start` (input) and `message_delta` (output) usage events. The
+// leading `message_start` (with input_tokens) sits at the very start of the
+// stream, so the spawn-tee tail buffer must be large enough to retain it for a
+// full mission-scale invocation rather than the 64 KiB limit-hit default.
+const CLAUDE_TELEMETRY_TAIL_BYTES = 8 * 1024 * 1024;
+
+// Claude outputs "Resume this session with: claude --resume <id>" at the end.
+const CLAUDE_SESSION_ID_RE = /claude\s+--resume\s+([0-9a-f-]+)/i;
+
+function extractClaudeSessionIdFromStreamJson(stdout) {
+  if (!stdout) return null;
+  const lines = stdout.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{')) continue;
+    try {
+      const evt = JSON.parse(trimmed);
+      // stream-json 'result' events carry session_id at the top level.
+      if (evt.type === 'result' && evt.session_id) return evt.session_id;
+    } catch {
+      /* not JSON — skip */
+    }
+  }
+  return null;
+}
+
+function extractClaudeSessionId(stdout) {
+  if (!stdout) return null;
+  // Try stream-json result event first (new default format).
+  const fromStream = extractClaudeSessionIdFromStreamJson(stdout);
+  if (fromStream) return fromStream;
+  // Fall back to legacy plain-text regex.
+  const m = CLAUDE_SESSION_ID_RE.exec(stdout);
+  return m ? m[1] : null;
+}
+
+function resolveClaudeCommand() {
+  return 'claude';
+}
+
+function buildClaudeInvocation({ prompt, worktree, env, resume = false, sessionId = null, model = null }) {
+  const args = ['--dangerously-skip-permissions'];
+  if (model) args.push('--model', 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('--resume', sessionId);
+  } else if (resume) {
+    args.push('--continue');
+  }
+  // Stream human-readable intermediate progress via stream-json events.
+  // The spawn-tee tee mechanism forwards these JSONL events to the terminal
+  // in real time so the operator sees tool calls and assistant text as they
+  // happen, rather than waiting for the final result.
+  // --include-partial-messages is required: without it, the assistant event
+  // contains the full response at once and no intermediate progress is emitted.
+  args.push('--output-format', 'stream-json', '--verbose', '--include-partial-messages');
+  args.push('-p', prompt);
+  return {
+    command: resolveClaudeCommand(),
+    args,
+    options: {
+      stdio: 'inherit',
+      cwd: worktree,
+      env: { ...process.env, ...env }
+    }
+  };
+}
+
+function startClaudeAgent({ prompt, worktree, env, resume = false, sessionId = null, model = null, teeOptions = {}, slug = null, role = null }) {
+  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 processResult(result) {
+    if (result && result.stdout) {
+      result.sessionId = extractClaudeSessionId(result.stdout);
+      try {
+        const telemetry = extractClaudeTelemetryFromStdout(result.stdout);
+        if (telemetry) {
+          result.telemetry = telemetry;
+          if (telemetry.model) result.model = telemetry.model;
+          if (telemetry.provider) result.provider = telemetry.provider;
+        }
+      } catch (_) {
+        // Telemetry is best-effort; never let it break the launch result.
+      }
+    }
+    return result;
+  }
+
+  function staleSessionHandler(invocation) {
+    const teeWithTail = { maxTailBytes: CLAUDE_TELEMETRY_TAIL_BYTES, ...invocation.options, ...teeOptions };
+    return _spawnAndTee(invocation.command, invocation.args, teeWithTail)
+      .then(result => {
+        if (isStaleSessionResult(result) && worktree && resume) {
+          try {
+            _sessions.clearSession(worktree, slug, role);
+          } catch (_) { /* best-effort */ }
+          const freshInv = buildClaudeInvocation({ prompt, worktree, env, resume: false, sessionId: null, model });
+          const freshTee = { maxTailBytes: CLAUDE_TELEMETRY_TAIL_BYTES, ...freshInv.options, ...teeOptions };
+          return _spawnAndTee(freshInv.command, freshInv.args, freshTee);
+        }
+        return result;
+      })
+      .then(processResult);
+  }
+
+  const invocation = buildClaudeInvocation({ prompt, worktree, env, resume, sessionId, model });
+  const resultPromise = staleSessionHandler(invocation);
+
+  return { invocation, resultPromise };
+}
+
+module.exports = {
+  buildClaudeInvocation,
+  extractClaudeSessionId,
+  extractClaudeTelemetryFromStdout,
+  resolveClaudeCommand,
+  startClaudeAgent,
+  __setSpawnAndTeeForTest,
+  __setSessionsForTest
+};

package/lib/agents/codex-telemetry.js

@@ -0,0 +1,202 @@
+'use strict';
+
+// Codex telemetry is read from the per-session rollout JSONL that the Codex CLI
+// always writes under `$CODEX_HOME/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl`.
+// The headless launcher (codex.js) points `HOME` at `<worktree>/.workflow/codex-home`,
+// so each mission worktree owns an isolated `…/.codex/sessions` tree. Reading the
+// rollout — rather than parsing the `--json` stdout stream — keeps the human-readable
+// transcript and session-resume behaviour intact while still yielding real usage data.
+//
+// Relevant rollout events (each line is one JSON object):
+//   {"type":"session_meta","payload":{"id","model_provider","model"?,...}}
+//   {"type":"turn_context","payload":{"model","effort",...}}
+//   {"type":"response_item","payload":{"type":"function_call",...}}
+//   {"type":"event_msg","payload":{"type":"token_count","info":{...},"rate_limits":{...}}}
+
+const fs = require('fs');
+const path = require('path');
+
+function codexSessionsDir(codexHome) {
+  return path.join(codexHome, '.codex', 'sessions');
+}
+
+/**
+ * Parse a rollout JSONL string into a telemetry object. Returns null when the
+ * content yields no usable signal (e.g. a failed turn with no token_count).
+ */
+function parseCodexRollout(content) {
+  if (!content) return null;
+
+  let sessionId = null;
+  let provider = null;
+  let model = null;
+  let effort = null;
+  let toolCalls = 0;
+  let lastUsage = null;
+  let contextWindow = 0;
+  let usagePercent = null;
+
+  for (const line of String(content).split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{')) continue;
+    let evt;
+    try {
+      evt = JSON.parse(trimmed);
+    } catch (_) {
+      continue;
+    }
+    const payload = evt && evt.payload;
+    if (!payload) continue;
+
+    switch (evt.type) {
+      case 'session_meta':
+        sessionId = payload.id || sessionId;
+        provider = payload.model_provider || provider;
+        if (payload.model) model = payload.model;
+        break;
+      case 'turn_context':
+        // The latest turn_context reflects the model/effort actually used.
+        if (payload.model) model = payload.model;
+        if (payload.effort) effort = payload.effort;
+        break;
+      case 'response_item':
+        if (payload.type === 'function_call') toolCalls += 1;
+        break;
+      case 'event_msg':
+        if (payload.type === 'token_count') {
+          if (payload.info && payload.info.total_token_usage) {
+            lastUsage = payload.info.total_token_usage;
+            if (payload.info.model_context_window) {
+              contextWindow = payload.info.model_context_window;
+            }
+          }
+          const pct = payload.rate_limits
+            && payload.rate_limits.primary
+            && payload.rate_limits.primary.used_percent;
+          if (typeof pct === 'number') usagePercent = pct;
+        }
+        break;
+      default:
+        break;
+    }
+  }
+
+  if (!lastUsage && !model && !sessionId) return null;
+
+  const usage = lastUsage || {};
+  return {
+    sessionId,
+    provider: provider || null,
+    model: model || null,
+    effort: effort || null,
+    inputTokens: usage.input_tokens || 0,
+    outputTokens: usage.output_tokens || 0,
+    cachedTokens: usage.cached_input_tokens || 0,
+    reasoningTokens: usage.reasoning_output_tokens || 0,
+    totalTokens: usage.total_tokens || 0,
+    contextWindow: contextWindow || 0,
+    toolCalls,
+    usagePercent,
+  };
+}
+
+/**
+ * Collect rollout files under a Codex sessions tree modified at or after
+ * `sinceMs`, sorted oldest-first by mtime. Each `codex exec` invocation —
+ * including `exec resume` — writes a NEW rollout file with a fresh
+ * `total_token_usage` counter, so a multi-round stage produces several files
+ * whose totals must be summed to get the stage's real quota consumption.
+ */
+function collectRolloutFiles(sessionsDir, { sinceMs = 0 } = {}) {
+  if (!sessionsDir || !fs.existsSync(sessionsDir)) return [];
+
+  const found = [];
+  const stack = [sessionsDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && entry.name.startsWith('rollout-') && entry.name.endsWith('.jsonl')) {
+        let stat;
+        try {
+          stat = fs.statSync(full);
+        } catch (_) {
+          continue;
+        }
+        const mtime = stat.mtimeMs;
+        if (mtime + 1000 < sinceMs) continue; // 1s grace for clock skew
+        found.push({ full, mtime });
+      }
+    }
+  }
+  found.sort((a, b) => a.mtime - b.mtime);
+  return found.map(f => f.full);
+}
+
+/**
+ * Sum codex telemetry across every rollout written at or after `sinceMs` in
+ * `codexHome`. Token counts and tool calls are summed across all rollouts in the
+ * window (so all rounds of a resumed session are counted); model/effort/provider
+ * and the rate-limit usage snapshot are taken from the newest rollout. Returns
+ * null when no rollout/usable data is found.
+ *
+ * Idempotent by construction: it recomputes from the rollout files each call, so
+ * re-running a stage (e.g. after the workflow process is resumed mid-mission)
+ * yields the same total rather than double-counting.
+ */
+function extractCodexTelemetry(codexHome, { sinceMs = 0 } = {}) {
+  const files = collectRolloutFiles(codexSessionsDir(codexHome), { sinceMs });
+  if (files.length === 0) return null;
+
+  const agg = {
+    inputTokens: 0, outputTokens: 0, cachedTokens: 0,
+    reasoningTokens: 0, totalTokens: 0, toolCalls: 0,
+  };
+  let newest = null;
+  for (const file of files) {
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch (_) {
+      continue;
+    }
+    const t = parseCodexRollout(content);
+    if (!t) continue;
+    agg.inputTokens += t.inputTokens;
+    agg.outputTokens += t.outputTokens;
+    agg.cachedTokens += t.cachedTokens;
+    agg.reasoningTokens += t.reasoningTokens;
+    agg.totalTokens += t.totalTokens;
+    agg.toolCalls += t.toolCalls;
+    newest = t; // files are oldest-first, so the last assignment is the newest
+    newest.rolloutPath = file;
+  }
+  if (!newest) return null;
+
+  return {
+    sessionId: newest.sessionId,
+    provider: newest.provider,
+    model: newest.model,
+    effort: newest.effort,
+    contextWindow: newest.contextWindow,
+    usagePercent: newest.usagePercent,
+    rolloutPath: newest.rolloutPath,
+    rolloutCount: files.length,
+    ...agg,
+  };
+}
+
+module.exports = {
+  codexSessionsDir,
+  parseCodexRollout,
+  collectRolloutFiles,
+  extractCodexTelemetry,
+};