@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/agents/opencode.js

@@ -3,20 +3,28 @@ const { extractOpencodeTelemetryFromExport } = require('./opencode-telemetry');
 const { captureOpencodeExport } = require('./opencode-export');
 const sessions = require('../tools/sessions');
 const { detectLimitHit } = require('./limit-hit');
+const { buildSubagentLimitPrefix } = require('../core/subagent-limit');
 
 // Injectable I/O for tests. Production uses the real spawn-tee / export capture.
+/** @type {Function} */
 let _spawnAndTee = spawnAndTee;
+/** @type {Function} */
 let _captureExport = captureOpencodeExport;
+/** @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 {Function} fn */
 function __setExportCaptureForTest(fn) { _captureExport = fn || captureOpencodeExport; }
+/** @param {object} mod */
 function __setSessionsForTest(mod) { _sessions = mod || sessions; }
 
 // Test hook: override the cached feature-detect for `--format json` support.
 // Set to true/false to force inclusion/exclusion of the flag regardless of
 // the real binary.  Pass null to reset to the live detect.
+/** @param {boolean|null} val */
 function __setJsonFormatSupportForTest(val) {
   _jsonFormatSupported = val;
   _jsonFormatDetectFn = null;
@@ -24,6 +32,7 @@ function __setJsonFormatSupportForTest(val) {
 
 // Test hook: inject a feature-detect function for tests.  This replaces the
 // live shell-out with a stubbed function, making tests hermetic.
+/** @param {Function} fn */
 function __setJsonFormatDetectForTest(fn) {
   _jsonFormatDetectFn = fn;
   _jsonFormatSupported = null;  // invalidate cache so the detect fn runs
@@ -45,10 +54,11 @@ function __setJsonFormatDetectForTest(fn) {
 const OPENCODE_SESSION_ID_RE = /opencode\s+-s\s+(ses_\S+)/i;
 const OPENCODE_JSON_SESSION_ID_RE = /"sessionID"\s*:\s*"(ses_[^"]+)"/;
 
+/** @param {string} stdout */
 function extractOpencodeSessionId(stdout) {
-  if (!stdout) return null;
+  if (!stdout) {return null;}
   const footer = OPENCODE_SESSION_ID_RE.exec(stdout);
-  if (footer) return footer[1];
+  if (footer) {return footer[1];}
   const json = OPENCODE_JSON_SESSION_ID_RE.exec(stdout);
   return json ? json[1] : null;
 }
@@ -56,10 +66,12 @@ function extractOpencodeSessionId(stdout) {
 // Cached feature-detect for `--format json` support. Set to `false` only when
 // a real invocation proves the flag is rejected (older opencode versions).
 // Tests can inject a canned result via __setJsonFormatSupportForTest.
+/** @type {boolean | null} */
 let _jsonFormatSupported = null;
 
 // Injectable feature-detect function for tests.  When set, checkJsonFormatSupport()
 // calls this function instead of shelling out, making tests hermetic.
+/** @type {Function | null} */
 let _jsonFormatDetectFn = null;
 
 function resolveOpencodeCommand() {
@@ -72,7 +84,7 @@ function resolveOpencodeCommand() {
 // Results are cached so the check runs at most once in production.
 // Tests can inject a canned result via __setJsonFormatSupportForTest.
 function checkJsonFormatSupport() {
-  if (_jsonFormatSupported !== null) return _jsonFormatSupported;
+  if (_jsonFormatSupported !== null) {return _jsonFormatSupported;}
   if (_jsonFormatDetectFn) {
     _jsonFormatSupported = _jsonFormatDetectFn();
     return _jsonFormatSupported;
@@ -99,6 +111,9 @@ function checkJsonFormatSupport() {
   }
 }
 
+/**
+ * @param {{ prompt: string, worktree: string, env?: object, resume?: boolean, sessionId?: string | null, model?: string | null, preferJson?: boolean }} opts
+ */
 function buildOpencodeInvocation({ prompt, worktree, env, resume = false, sessionId = null, model = null, preferJson = true }) {
   // `--format json` makes opencode stream NDJSON events that each carry a
   // "sessionID":"ses_..." field. opencode v2.0.0's default `run` output no
@@ -111,8 +126,8 @@ function buildOpencodeInvocation({ prompt, worktree, env, resume = false, sessio
   // invocation, preserving launch behaviour at the cost of telemetry.
   const useJson = preferJson && checkJsonFormatSupport();
   const args = ['run', '--pure', '--dangerously-skip-permissions'];
-  if (useJson) args.push('--format', 'json');
-  if (model) args.push('-m', model);
+  if (useJson) {args.push('--format', 'json');}
+  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) {
@@ -170,13 +185,19 @@ const HARD_OPENCODE_PATTERNS = [
   /\bauthentication (?:failed|error)\b/i,
 ];
 
+/**
+ * @param {{stdout?: string, stderr?: string}} result
+ */
 function failureText(result) {
   return `${(result && result.stdout) || ''}\n${(result && result.stderr) || ''}`;
 }
 
+/**
+ * @param {{stdout?: string, stderr?: string, error?: {code?: string}}} result
+ */
 function isHardOpencodeFailure(result) {
-  if (!result) return false;
-  if (result.error && (result.error.code === 'ENOENT' || result.error.code === 'EACCES')) return true;
+  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));
 }
@@ -186,16 +207,22 @@ function isHardOpencodeFailure(result) {
 // When the transcript contains a valid "reason":"stop" completion event and
 // no "type":"error" event, the exit is spurious – the agent actually
 // completed successfully. See opencode issues #31446 and #33653.
+/**
+ * @param {{status?: number, stdout?: string, stderr?: string}} result
+ */
 function isSpuriousOpencodeExit(result) {
-  if (!result || result.status !== 1) return false;
+  if (!result || result.status !== 1) {return false;}
   const text = failureText(result);
   const hasStop = /"reason"\s*:\s*"stop"/.test(text);
   const hasError = /"type"\s*:\s*"error"/.test(text);
   return hasStop && !hasError;
 }
 
+/**
+ * @param {{stdout?: string, stderr?: string, error?: {code?: string}, signal?: string, status?: number}} result
+ */
 function isTransientOpencodeFailure(result) {
-  if (!result) return false;
+  if (!result) {return false;}
   const text = failureText(result);
   return TRANSIENT_OPENCODE_PATTERNS.some((re) => re.test(text));
 }
@@ -204,11 +231,12 @@ function isTransientOpencodeFailure(result) {
 // 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.
+/** @param {{stdout?: string, stderr?: string, status?: number | null, signal?: string | null, error?: {code?: string}, sessionId?: string | null}} result */
 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 (!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: 'custom',
     stdout: result.stdout,
@@ -216,11 +244,14 @@ function shouldRetryOpencodeFailure(result) {
     status: result.status,
     signal: result.signal,
     error: result.error,
-  })) return false;
-  if (isHardOpencodeFailure(result)) return false;
-  return isTransientOpencodeFailure(result);
+  })) {return false;}
+  if (isHardOpencodeFailure(result)) {return false;}
+  return isTransientOpencodeFailure(/** @type {any} */(result));
 }
 
+/**
+ * @param {{ prompt: string, worktree: string, env?: object, resume?: boolean, sessionId?: string | null, model?: string | null, teeOptions?: object, slug?: string | null, role?: string | null, maxTransientRetries?: number }} opts
+ */
 function startOpencodeAgent({
   prompt,
   worktree,
@@ -233,18 +264,32 @@ function startOpencodeAgent({
   role = null,
   maxTransientRetries = 1
 }) {
+  // Prepend the subagent-limit advisory prefix to the prompt.
+  // When maxParallel is unset/null/zero the prefix is empty (no-op).
+  const subagentPrefix = buildSubagentLimitPrefix();
+  const injectedPrompt = subagentPrefix + prompt;
+
+  /**
+   * @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 {{command: string, args: string[], options?: object}} invocation
+   */
   function runInvocation(invocation) {
     const spawnOptions = { ...invocation.options, ...teeOptions };
     return _spawnAndTee(invocation.command, invocation.args, spawnOptions);
   }
 
+  /**
+   * @param {{command: string, args: string[], options?: object}} invocation
+   */
   async function runInvocationWithRetry(invocation) {
     let attempts = 0;
     let result = await runInvocation(invocation);
@@ -252,7 +297,7 @@ function startOpencodeAgent({
       attempts += 1;
       result = await runInvocation(invocation);
     }
-    if (result) result.transientRetries = attempts;
+    if (result) {result.transientRetries = attempts;}
     return result;
   }
 
@@ -260,25 +305,31 @@ function startOpencodeAgent({
   // that wasn't caught by the feature-detect).  If so, retry the invocation
   // without the flag so the prompt still runs (telemetry will be lost but the
   // agent won't fail outright).
+  /**
+   * @param {{stdout?: string, stderr?: string}} result
+   */
   function isJsonFlagError(result) {
-    if (!result) return false;
+    if (!result) {return false;}
     const text = failureText(result);
     return (/\bunrecognized option\b|\bunknown option\b|\bno such option\b|\binvalid option\b|\bunrecognized flag\b|\bunknown flag\b/i).test(text);
   }
 
+  /**
+   * @param {{stdout?: string, sessionId?: string, telemetry?: object, model?: string, provider?: string, transientRetries?: number, _jsonFallback?: boolean}} result
+   */
   async function processResult(result) {
     if (result && result.stdout) {
-      result.sessionId = extractOpencodeSessionId(result.stdout);
+      result.sessionId = extractOpencodeSessionId(result.stdout) || undefined;
     }
     if (result && result.sessionId) {
       try {
         const exportJson = await _captureExport(result.sessionId, { worktree, env });
         if (exportJson) {
-          const telemetry = extractOpencodeTelemetryFromExport(exportJson, model);
+          const telemetry = extractOpencodeTelemetryFromExport(exportJson, model || undefined);
           if (telemetry) {
-            result.telemetry = telemetry;
-            if (telemetry.model) result.model = telemetry.model;
-            if (telemetry.provider) result.provider = telemetry.provider;
+            /** @type {any} */(result).telemetry = telemetry;
+            if (/** @type {any} */(telemetry).model) {/** @type {any} */(result).model = /** @type {any} */(telemetry).model;}
+            if (/** @type {any} */(telemetry).provider) {/** @type {any} */(result).provider = /** @type {any} */(telemetry).provider;}
           }
         }
       } catch (_) {
@@ -288,34 +339,40 @@ function startOpencodeAgent({
     return result;
   }
 
+  /**
+   * @param {{command: string, args: string[], options?: object}} invocation
+   */
   async function runWithJsonFallback(invocation) {
     let result = await runInvocationWithRetry(invocation);
     // Runtime fallback: if the first invocation used --format json but the
     // binary rejected it, retry without the flag so the prompt still executes.
     if (isJsonFlagError(result) && invocation.args.includes('--format')) {
       const legacyInv = buildOpencodeInvocation({
-        prompt, worktree, env, resume, sessionId, model, preferJson: false,
+        prompt: injectedPrompt, worktree, env, resume, sessionId, model, preferJson: false,
       });
       result = await runInvocationWithRetry(legacyInv);
       // Mark that we fell back so callers know telemetry may be absent.
-      if (result) result._jsonFallback = true;
+      if (result) {result._jsonFallback = true;}
     }
     return result;
   }
 
+  /**
+   * @param {{command: string, args: string[], options?: object}} invocation
+   */
   async function staleSessionHandler(invocation) {
     let result = await runWithJsonFallback(invocation);
     if (isStaleSessionResult(result) && worktree && resume) {
       try {
-        _sessions.clearSession(worktree, slug, role);
+        /** @type {any} */(_sessions).clearSession(worktree, slug || '', role || '');
       } catch (_) { /* best-effort */ }
-      const freshInv = buildOpencodeInvocation({ prompt, worktree, env, resume: false, sessionId: null, model });
+      const freshInv = buildOpencodeInvocation({ prompt: injectedPrompt, worktree, env, resume: false, sessionId: null, model });
       result = await runWithJsonFallback(freshInv);
     }
     return processResult(result);
   }
 
-  const invocation = buildOpencodeInvocation({ prompt, worktree, env, resume, sessionId, model });
+  const invocation = buildOpencodeInvocation({ prompt: injectedPrompt, worktree, env, resume, sessionId, model });
   const resultPromise = staleSessionHandler(invocation);
 
   return { invocation, resultPromise };

package/lib/agents/stage-telemetry.js

@@ -17,15 +17,11 @@
 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.
+ * @param {{ worktree: string, result: { telemetry?: { provider?: string } & object }, sinceMs?: number }} opts
  * @returns {object|null} normalized telemetry, or null when none is available.
  */
-function resolveStageTelemetry({ worktree, result, sinceMs = 0 } = {}) {
-  if (!result || !result.telemetry) return null;
+function resolveStageTelemetry({ worktree, result, sinceMs = 0 } = /** @type {{ worktree: string, result: { telemetry?: { provider?: string } & object }, sinceMs?: number }} */({})) {
+  if (!result || !result.telemetry) {return null;}
   try {
     const codexT = extractCodexTelemetry(codexHomeRoot(worktree), { sinceMs: sinceMs || 0 });
     // Guard against stale Codex rollouts bleeding into non-Codex stages: