@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/agents/claude-telemetry.js

@@ -36,6 +36,7 @@
 
 const PROVIDER = 'anthropic';
 
+/** @param {*} value */
 function num(value) {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
@@ -45,6 +46,7 @@ function num(value) {
  * `--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.
  */
+/** @param {any} evt */
 function unwrapEvent(evt) {
   if (evt && evt.type === 'stream_event' && evt.event && typeof evt.event === 'object') {
     return evt.event;
@@ -66,8 +68,9 @@ function unwrapEvent(evt) {
  *     resultUsage: { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens } | null
  *   }
  */
+/** @param {string} content */
 function parseClaudeStreamJson(content) {
-  if (!content) return null;
+  if (!content) {return null;}
 
   let sessionId = null;
   let model = null;
@@ -79,19 +82,19 @@ function parseClaudeStreamJson(content) {
 
   for (const line of String(content).split('\n')) {
     const trimmed = line.trim();
-    if (!trimmed.startsWith('{')) continue;
+    if (!trimmed.startsWith('{')) {continue;}
     let outer;
     try {
       outer = JSON.parse(trimmed);
     } catch (_) {
       continue;
     }
-    if (!outer || typeof outer !== 'object') 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;
+    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).
@@ -110,13 +113,13 @@ function parseClaudeStreamJson(content) {
     }
 
     const evt = unwrapEvent(outer);
-    if (!evt || typeof evt !== 'object') continue;
+    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;
+        if (message.model) {model = message.model;}
         messageStarts.push({
           inputTokens: num(usage.input_tokens),
           outputTokens: num(usage.output_tokens),
@@ -133,7 +136,7 @@ function parseClaudeStreamJson(content) {
       }
       case 'content_block_start': {
         const block = evt.content_block || {};
-        if (block.type === 'tool_use') toolCalls += 1;
+        if (block.type === 'tool_use') {toolCalls += 1;}
         break;
       }
       default:
@@ -142,7 +145,7 @@ function parseClaudeStreamJson(content) {
   }
 
   const hasSignal = messageStarts.length > 0 || messageDeltas.length > 0 || resultUsage || model || sessionId;
-  if (!hasSignal) return null;
+  if (!hasSignal) {return null;}
 
   return {
     sessionId,
@@ -174,9 +177,10 @@ function parseClaudeStreamJson(content) {
  *
  * Returns null when the stream yields no usable token signal.
  */
+/** @param {string} stdout */
 function extractClaudeTelemetryFromStdout(stdout) {
   const parsed = parseClaudeStreamJson(stdout);
-  if (!parsed) return null;
+  if (!parsed) {return null;}
 
   const { messageStarts, messageDeltas, resultUsage, resultCostUsd } = parsed;
 

package/lib/agents/claude.js

@@ -3,11 +3,15 @@ const { extractClaudeTelemetryFromStdout } = require('./claude-telemetry');
 const sessions = require('../tools/sessions');
 
 // Injectable I/O for tests. Production uses the real spawn-tee / export capture.
+/** @type {Function} */
 let _spawnAndTee = spawnAndTee;
+/** @type {object} */
 let _sessions = sessions;
 
 // Test hooks: override the launcher's I/O without touching the public signature.
+/** @param {Function} fn */
 function __setSpawnAndTeeForTest(fn) { _spawnAndTee = fn || spawnAndTee; }
+/** @param {object} mod */
 function __setSessionsForTest(mod) { _sessions = mod || sessions; }
 
 // Claude usage telemetry is parsed from the `stream-json` stdout stream, which
@@ -20,16 +24,17 @@ 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;
 
+/** @param {string} stdout */
 function extractClaudeSessionIdFromStreamJson(stdout) {
-  if (!stdout) return null;
+  if (!stdout) {return null;}
   const lines = stdout.split('\n');
   for (const line of lines) {
     const trimmed = line.trim();
-    if (!trimmed.startsWith('{')) continue;
+    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;
+      if (evt.type === 'result' && evt.session_id) {return evt.session_id;}
     } catch {
       /* not JSON — skip */
     }
@@ -37,11 +42,12 @@ function extractClaudeSessionIdFromStreamJson(stdout) {
   return null;
 }
 
+/** @param {string} stdout */
 function extractClaudeSessionId(stdout) {
-  if (!stdout) return null;
+  if (!stdout) {return null;}
   // Try stream-json result event first (new default format).
   const fromStream = extractClaudeSessionIdFromStreamJson(stdout);
-  if (fromStream) return fromStream;
+  if (fromStream) {return fromStream;}
   // Fall back to legacy plain-text regex.
   const m = CLAUDE_SESSION_ID_RE.exec(stdout);
   return m ? m[1] : null;
@@ -51,9 +57,12 @@ function resolveClaudeCommand() {
   return 'claude';
 }
 
+/**
+ * @param {{ prompt: string, worktree: string, env?: object, resume?: boolean, sessionId?: string | null, model?: string | null }} opts
+ */
 function buildClaudeInvocation({ prompt, worktree, env, resume = false, sessionId = null, model = null }) {
   const args = ['--dangerously-skip-permissions'];
-  if (model) args.push('--model', model);
+  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) {
@@ -80,14 +89,23 @@ function buildClaudeInvocation({ prompt, worktree, env, resume = false, sessionI
   };
 }
 
+/**
+ * @param {{ prompt: string, worktree: string, env?: object, resume?: boolean, sessionId?: string | null, model?: string | null, teeOptions?: object, slug?: string | null, role?: string | null }} opts
+ */
 function startClaudeAgent({ prompt, worktree, env, resume = false, sessionId = null, model = null, teeOptions = {}, slug = null, role = null }) {
+  /**
+   * @param {{stdout?: string, stderr?: string}} result
+   */
   function isStaleSessionResult(result) {
-    if (!result) return false;
+    if (!result) {return false;}
     const stderr = result.stderr || '';
     const stdout = result.stdout || '';
     return (stderr.includes('Session not found') || stdout.includes('Session not found'));
   }
 
+  /**
+   * @param {{stdout?: string, sessionId?: string, telemetry?: object, model?: string, provider?: string}} result
+   */
   function processResult(result) {
     if (result && result.stdout) {
       result.sessionId = extractClaudeSessionId(result.stdout);
@@ -95,8 +113,8 @@ function startClaudeAgent({ prompt, worktree, env, resume = false, sessionId = n
         const telemetry = extractClaudeTelemetryFromStdout(result.stdout);
         if (telemetry) {
           result.telemetry = telemetry;
-          if (telemetry.model) result.model = telemetry.model;
-          if (telemetry.provider) result.provider = telemetry.provider;
+          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.
@@ -105,13 +123,16 @@ function startClaudeAgent({ prompt, worktree, env, resume = false, sessionId = n
     return result;
   }
 
+  /**
+   * @param {{command: string, args: string[], options?: object}} invocation
+   */
   function staleSessionHandler(invocation) {
     const teeWithTail = { maxTailBytes: CLAUDE_TELEMETRY_TAIL_BYTES, ...invocation.options, ...teeOptions };
     return _spawnAndTee(invocation.command, invocation.args, teeWithTail)
-      .then(result => {
+      .then(/** @param {object} result */ (result) => {
         if (isStaleSessionResult(result) && worktree && resume) {
           try {
-            _sessions.clearSession(worktree, slug, role);
+            /** @type {any} */(_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 };

package/lib/agents/codex-telemetry.js

@@ -16,6 +16,7 @@
 const fs = require('fs');
 const path = require('path');
 
+/** @param {string} codexHome */
 function codexSessionsDir(codexHome) {
   return path.join(codexHome, '.codex', 'sessions');
 }
@@ -24,8 +25,9 @@ function codexSessionsDir(codexHome) {
  * 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).
  */
+/** @param {string} content */
 function parseCodexRollout(content) {
-  if (!content) return null;
+  if (!content) {return null;}
 
   let sessionId = null;
   let provider = null;
@@ -38,7 +40,7 @@ function parseCodexRollout(content) {
 
   for (const line of String(content).split('\n')) {
     const trimmed = line.trim();
-    if (!trimmed.startsWith('{')) continue;
+    if (!trimmed.startsWith('{')) {continue;}
     let evt;
     try {
       evt = JSON.parse(trimmed);
@@ -46,21 +48,21 @@ function parseCodexRollout(content) {
       continue;
     }
     const payload = evt && evt.payload;
-    if (!payload) continue;
+    if (!payload) {continue;}
 
     switch (evt.type) {
       case 'session_meta':
         sessionId = payload.id || sessionId;
         provider = payload.model_provider || provider;
-        if (payload.model) model = payload.model;
+        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;
+        if (payload.model) {model = payload.model;}
+        if (payload.effort) {effort = payload.effort;}
         break;
       case 'response_item':
-        if (payload.type === 'function_call') toolCalls += 1;
+        if (payload.type === 'function_call') {toolCalls += 1;}
         break;
       case 'event_msg':
         if (payload.type === 'token_count') {
@@ -73,7 +75,7 @@ function parseCodexRollout(content) {
           const pct = payload.rate_limits
             && payload.rate_limits.primary
             && payload.rate_limits.primary.used_percent;
-          if (typeof pct === 'number') usagePercent = pct;
+          if (typeof pct === 'number') {usagePercent = pct;}
         }
         break;
       default:
@@ -81,7 +83,7 @@ function parseCodexRollout(content) {
     }
   }
 
-  if (!lastUsage && !model && !sessionId) return null;
+  if (!lastUsage && !model && !sessionId) {return null;}
 
   const usage = lastUsage || {};
   return {
@@ -107,8 +109,12 @@ function parseCodexRollout(content) {
  * `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.
  */
+/**
+ * @param {string} sessionsDir
+ * @param {{ sinceMs?: number }} [opts]
+ */
 function collectRolloutFiles(sessionsDir, { sinceMs = 0 } = {}) {
-  if (!sessionsDir || !fs.existsSync(sessionsDir)) return [];
+  if (!sessionsDir || !fs.existsSync(sessionsDir)) {return [];}
 
   const found = [];
   const stack = [sessionsDir];
@@ -116,12 +122,14 @@ function collectRolloutFiles(sessionsDir, { sinceMs = 0 } = {}) {
     const dir = stack.pop();
     let entries;
     try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
+      entries = /** @type {Array<import('fs').Dirent>} */(/** @type {any} */(fs).readdirSync(dir, { withFileTypes: true }));
     } catch (_) {
       continue;
     }
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
+    for (const entry of /** @type {Array<{name: string, isDirectory: () => boolean, isFile: () => boolean}>} */(entries)) {
+      if (!entry.name) {continue;}
+      const /** @type {string} */ name = entry.name ?? '';
+      const full = path.join(dir || '', name);
       if (entry.isDirectory()) {
         stack.push(full);
       } else if (entry.isFile() && entry.name.startsWith('rollout-') && entry.name.endsWith('.jsonl')) {
@@ -132,7 +140,7 @@ function collectRolloutFiles(sessionsDir, { sinceMs = 0 } = {}) {
           continue;
         }
         const mtime = stat.mtimeMs;
-        if (mtime + 1000 < sinceMs) continue; // 1s grace for clock skew
+        if (mtime + 1000 < sinceMs) {continue;} // 1s grace for clock skew
         found.push({ full, mtime });
       }
     }
@@ -152,15 +160,20 @@ function collectRolloutFiles(sessionsDir, { sinceMs = 0 } = {}) {
  * re-running a stage (e.g. after the workflow process is resumed mid-mission)
  * yields the same total rather than double-counting.
  */
+/**
+ * @param {string} codexHome
+ * @param {{ sinceMs?: number }} [opts]
+ */
 function extractCodexTelemetry(codexHome, { sinceMs = 0 } = {}) {
   const files = collectRolloutFiles(codexSessionsDir(codexHome), { sinceMs });
-  if (files.length === 0) return null;
+  if (files.length === 0) {return null;}
 
   const agg = {
     inputTokens: 0, outputTokens: 0, cachedTokens: 0,
     reasoningTokens: 0, totalTokens: 0, toolCalls: 0,
   };
   let newest = null;
+  let newestPath = null;
   for (const file of files) {
     let content;
     try {
@@ -169,7 +182,7 @@ function extractCodexTelemetry(codexHome, { sinceMs = 0 } = {}) {
       continue;
     }
     const t = parseCodexRollout(content);
-    if (!t) continue;
+    if (!t) {continue;}
     agg.inputTokens += t.inputTokens;
     agg.outputTokens += t.outputTokens;
     agg.cachedTokens += t.cachedTokens;
@@ -177,9 +190,9 @@ function extractCodexTelemetry(codexHome, { sinceMs = 0 } = {}) {
     agg.totalTokens += t.totalTokens;
     agg.toolCalls += t.toolCalls;
     newest = t; // files are oldest-first, so the last assignment is the newest
-    newest.rolloutPath = file;
+    newestPath = file;
   }
-  if (!newest) return null;
+  if (!newest) {return null;}
 
   return {
     sessionId: newest.sessionId,
@@ -188,7 +201,7 @@ function extractCodexTelemetry(codexHome, { sinceMs = 0 } = {}) {
     effort: newest.effort,
     contextWindow: newest.contextWindow,
     usagePercent: newest.usagePercent,
-    rolloutPath: newest.rolloutPath,
+    rolloutPath: newestPath,
     rolloutCount: files.length,
     ...agg,
   };

package/lib/agents/codex.js

@@ -6,11 +6,15 @@ const { extractCodexTelemetry } = require('./codex-telemetry');
 const sessions = require('../tools/sessions');
 
 // Injectable I/O for tests. Production uses the real spawn-tee / export capture.
+/** @type {Function} */
 let _spawnAndTee = spawnAndTee;
+/** @type {object} */
 let _sessions = sessions;
 
 // Test hooks: override the launcher's I/O without touching the public signature.
+/** @param {Function} fn */
 function __setSpawnAndTeeForTest(fn) { _spawnAndTee = fn || spawnAndTee; }
+/** @param {object} mod */
 function __setSessionsForTest(mod) { _sessions = mod || sessions; }
 
 // Codex outputs "To continue this session, run codex resume <id>" at the end.
@@ -18,12 +22,13 @@ function __setSessionsForTest(mod) { _sessions = mod || sessions; }
 const CODEX_SESSION_ID_RE = /codex\s+resume\s+([0-9a-f-]+)/i;
 const CODEX_SESSION_ID_ALT_RE = /Session ID:\s*([0-9a-f-]+)/i;
 
+/** @param {string} stdout */
 function extractCodexSessionId(stdout) {
-  if (!stdout) return null;
+  if (!stdout) {return null;}
   const m = CODEX_SESSION_ID_RE.exec(stdout);
-  if (m) return m[1];
+  if (m) {return m[1];}
   const m2 = CODEX_SESSION_ID_ALT_RE.exec(stdout);
-  if (m2) return m2[1];
+  if (m2) {return m2[1];}
   return null;
 }
 
@@ -35,6 +40,9 @@ function hasLiveTty() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
+/**
+ * @param {{ prompt: string, worktree: string, interactive?: boolean, env?: {[key: string]: string}, resume?: boolean, sessionId?: string | null, model?: string | null }} opts
+ */
 function buildCodexDraftInvocation({ prompt, worktree, interactive = hasLiveTty(), env = {}, resume = false, sessionId = null, model = null }) {
   if (resume) {
     const args = ['exec', 'resume'];
@@ -43,7 +51,7 @@ function buildCodexDraftInvocation({ prompt, worktree, interactive = hasLiveTty(
     } else {
       args.push('--last');
     }
-    if (model) args.push('-m', model);
+    if (model) {args.push('-m', model);}
     args.push(prompt);
     return {
       command: resolveCodexCommand(),
@@ -77,6 +85,9 @@ function buildCodexDraftInvocation({ prompt, worktree, interactive = hasLiveTty(
   };
 }
 
+/**
+ * @param {{ prompt: string, worktree: string, env?: {[key: string]: string}, resume?: boolean, sessionId?: string | null, model?: string | null, teeOptions?: object, slug?: string | null, role?: string | null }} opts
+ */
 function startCodexDraftAgent({ prompt, worktree, env = {}, resume = false, sessionId = null, model = null, teeOptions = {}, slug = null, role = null }) {
   // The launcher always tees through spawnAndTee for limit-hit detection, which
   // forces child stdio to ['inherit', 'pipe', 'pipe']. Codex's `--full-auto`
@@ -84,16 +95,22 @@ function startCodexDraftAgent({ prompt, worktree, env = {}, resume = false, sess
   // `exec` path here regardless of whether the parent has a TTY.
   ensureCodexHome(worktree);
 
+  /**
+   * @param {{stdout?: string, stderr?: string}} result
+   */
   function isStaleSessionResult(result) {
-    if (!result) return false;
+    if (!result) {return false;}
     const stderr = result.stderr || '';
     const stdout = result.stdout || '';
     return (stderr.includes('Session not found') || stdout.includes('Session not found'));
   }
 
+  /**
+   * @param {{stdout?: string, sessionId?: string, telemetry?: object, model?: string, provider?: string}} result
+   */
   function processResult(result) {
     if (result && result.stdout) {
-      result.sessionId = extractCodexSessionId(result.stdout);
+      result.sessionId = extractCodexSessionId(result.stdout) || undefined;
     }
     if (result) {
       // Real usage telemetry comes from the codex rollout JSONL written under the
@@ -102,8 +119,8 @@ function startCodexDraftAgent({ prompt, worktree, env = {}, resume = false, sess
         const telemetry = extractCodexTelemetry(codexHomeRoot(worktree), { sinceMs: Date.now() });
         if (telemetry) {
           result.telemetry = telemetry;
-          if (telemetry.model) result.model = telemetry.model;
-          if (telemetry.provider) result.provider = telemetry.provider;
+          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.
@@ -112,12 +129,15 @@ function startCodexDraftAgent({ prompt, worktree, env = {}, resume = false, sess
     return result;
   }
 
+  /**
+   * @param {{command: string, args: string[], options?: object}} invocation
+   */
   function staleSessionHandler(invocation) {
     return _spawnAndTee(invocation.command, invocation.args, { ...invocation.options, ...teeOptions })
-      .then(result => {
+      .then(/** @param {object} result */ (result) => {
         if (isStaleSessionResult(result) && worktree && resume) {
           try {
-            _sessions.clearSession(worktree, slug, role);
+            /** @type {any} */(_sessions).clearSession(worktree, slug, role);
           } catch (_) { /* best-effort */ }
           const freshInv = buildCodexDraftInvocation({ prompt, worktree, interactive: false, env, resume: false, sessionId: null, model });
           return _spawnAndTee(freshInv.command, freshInv.args, { ...freshInv.options, ...teeOptions });
@@ -127,21 +147,23 @@ function startCodexDraftAgent({ prompt, worktree, env = {}, resume = false, sess
       .then(processResult);
   }
 
-  const startedMs = Date.now();
   const invocation = buildCodexDraftInvocation({ prompt, worktree, interactive: false, env, resume, sessionId, model });
   const resultPromise = staleSessionHandler(invocation);
 
   return { invocation, resultPromise };
 }
 
+/** @param {string} worktree */
 function codexHomeRoot(worktree) {
   return path.join(worktree, '.workflow', 'codex-home');
 }
 
+/** @param {string} worktree */
 function codexConfigPath(worktree) {
   return path.join(codexHomeRoot(worktree), '.codex', 'config.toml');
 }
 
+/** @param {string} worktree */
 function codexAuthPath(worktree) {
   return path.join(codexHomeRoot(worktree), '.codex', 'auth.json');
 }
@@ -150,6 +172,7 @@ function userCodexAuthPath() {
   return path.join(os.homedir(), '.codex', 'auth.json');
 }
 
+/** @param {*} value */
 function tomlString(value) {
   return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
@@ -157,6 +180,7 @@ function tomlString(value) {
 // Graphify's Codex skill requires multi_agent = true for spawn_agent subagent
 // dispatch (skill-codex.md line 233). Without this, the copied Graphify skill
 // cannot launch semantic extraction subagents and parallel graph building fails.
+/** @param {string} worktree */
 function headlessCodexConfig(worktree) {
   const worktreeParent = path.dirname(path.resolve(worktree));
   return [
@@ -176,6 +200,7 @@ function headlessCodexConfig(worktree) {
   ].join('\n');
 }
 
+/** @param {string} worktree */
 function ensureCodexHome(worktree) {
   fs.mkdirSync(codexHomeRoot(worktree), { recursive: true });
   fs.mkdirSync(path.dirname(codexConfigPath(worktree)), { recursive: true });