@simonren/quorum 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,6 +10,7 @@ import { existsSync } from 'fs';
10
10
  import { registerAdapter, } from './base.js';
11
11
  import { CliExecutor } from '../executor.js';
12
12
  import { CodexEventDecoder } from '../decoders/index.js';
13
+ import { watchCodexThreadLiveness } from '../codex-liveness.js';
13
14
  import { buildSimpleHandoff, buildHandoffPrompt, buildAdversarialHandoffPrompt, selectRole, } from '../handoff.js';
14
15
  import { buildConsultPrompt } from '../consult-prompt.js';
15
16
  import { getConfig } from '../config.js';
@@ -89,7 +90,6 @@ export class CodexAdapter {
89
90
  '-m', cfg.model,
90
91
  '-c', `model_reasoning_effort=${reasoningEffort}`,
91
92
  '-c', 'model_reasoning_summary_format=experimental',
92
- '--full-auto',
93
93
  '--sandbox', 'read-only',
94
94
  '--skip-git-repo-check',
95
95
  '-C', workingDir,
@@ -110,6 +110,14 @@ export class CodexAdapter {
110
110
  const detailStr = detail ? ` — ${detail}` : '';
111
111
  console.error(`[codex] ${eventType}${detailStr} (${elapsed}s)`);
112
112
  };
113
+ // `codex exec --json` stays byte-silent for the whole of a reasoning block
114
+ // — minutes at a time on xhigh — so stdout alone cannot distinguish
115
+ // "thinking hard" from "hung", and the inactivity timer kills healthy runs
116
+ // mid-thought. Codex keeps appending reasoning summaries to its session
117
+ // rollout file throughout, so watch that file and treat growth as liveness.
118
+ // The watcher is best-effort: if the rollout file cannot be found we simply
119
+ // fall back to the stdout-only behaviour.
120
+ let stopLiveness;
113
121
  const executor = new CliExecutor({
114
122
  command: 'codex',
115
123
  args,
@@ -120,16 +128,25 @@ export class CodexAdapter {
120
128
  maxBufferSize: cfg.maxBufferSize,
121
129
  onLine: (line) => {
122
130
  decoder.processLine(line);
131
+ const threadId = decoder.getThreadId();
132
+ if (stopLiveness === undefined && threadId !== null) {
133
+ stopLiveness = watchCodexThreadLiveness({
134
+ threadId,
135
+ onActivity: () => executor.noteActivity(),
136
+ });
137
+ }
123
138
  },
124
139
  });
125
- const result = await executor.run();
140
+ // `.finally` rather than a try/finally so a TIMEOUT/MAX_TIMEOUT rejection
141
+ // still tears the watcher down before it propagates.
142
+ const result = await executor.run().finally(() => stopLiveness?.());
126
143
  const elapsed = Math.round((Date.now() - cliStartTime) / 1000);
127
144
  console.error(`[codex] ✓ complete (${elapsed}s)`);
128
145
  // A genuine fatal error (a top-level `error` event or `turn.failed`) is
129
146
  // TERMINAL and wins even when a — possibly intermediate/stale — agent_message
130
- // exists. `--full-auto` runs a multi-turn loop, so a turn can emit a message
131
- // and a later turn can fail; without this check, that failure would be
132
- // reported as a successful review with stale content.
147
+ // exists. `codex exec` runs a multi-turn agent loop, so a turn can emit a
148
+ // message and a later turn can fail; without this check, that failure would
149
+ // be reported as a successful review with stale content.
133
150
  const fatalError = decoder.getFatalError();
134
151
  if (fatalError) {
135
152
  const combined = result.stderr ? `${fatalError}\n\nCLI stderr: ${result.stderr}` : fatalError;
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Codex thread liveness watcher.
3
+ *
4
+ * `codex exec --json` emits nothing on stdout while the model reasons. A single
5
+ * xhigh reasoning block runs minutes with zero bytes on the wire, which is
6
+ * byte-identical to a wedged process — so an inactivity timeout driven only by
7
+ * stdout SIGTERMs healthy runs mid-thought.
8
+ *
9
+ * Codex does keep working during that silence: it appends reasoning summaries
10
+ * to the session rollout file every few seconds for the whole block. That
11
+ * file's mtime is therefore an out-of-band proof of life, and watching it lets
12
+ * the inactivity timeout mean what it is supposed to mean — "this process has
13
+ * stopped doing anything" — instead of "this process has stopped talking".
14
+ *
15
+ * Rollout path:
16
+ * $CODEX_HOME/sessions/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<thread_id>.jsonl
17
+ *
18
+ * The date directories and the filename timestamp are LOCAL time, not UTC.
19
+ *
20
+ * Every failure path here is silent and non-fatal: if the file cannot be found
21
+ * or read, the watcher simply stops poking and the caller falls back to plain
22
+ * stdout-driven timeouts. Liveness detection must never be able to break a run.
23
+ */
24
+ export interface CodexLivenessOptions {
25
+ /** Thread id from the `thread.started` event. */
26
+ threadId: string;
27
+ /** Invoked each time the rollout file grows — i.e. Codex is alive. */
28
+ onActivity: () => void;
29
+ /** How often to stat the rollout file. Default 15_000 (15s). */
30
+ pollMs?: number;
31
+ /** Override the Codex home dir. Defaults to $CODEX_HOME or ~/.codex. */
32
+ codexHome?: string;
33
+ /**
34
+ * How many polls to spend looking for the rollout file before giving up.
35
+ * Codex creates it within a second or two of `thread.started`; if it is still
36
+ * missing after this many attempts it does not exist for this run (`--ephemeral`,
37
+ * a relocated CODEX_HOME, a future layout change), and we stop scanning
38
+ * rather than readdir'ing once a poll for the next hour. Default 8.
39
+ */
40
+ maxDiscoveryAttempts?: number;
41
+ }
42
+ /** Codex's home directory — `$CODEX_HOME` if set, else `~/.codex`. */
43
+ export declare function getCodexHome(): string;
44
+ /**
45
+ * Locate the rollout file for a thread, or `null` if it is not there (yet).
46
+ *
47
+ * Only today's and yesterday's local-date directories are scanned: a run that
48
+ * started before local midnight lands in yesterday's directory, and nothing
49
+ * older can belong to a live process (the caller's absolute max timeout is
50
+ * measured in minutes).
51
+ */
52
+ export declare function findRolloutFile(threadId: string, codexHome?: string): string | null;
53
+ /**
54
+ * Poll a Codex run's rollout file and call `onActivity` whenever it grows.
55
+ *
56
+ * Returns a stop function. It is idempotent and MUST be called when the run
57
+ * settles — the caller owns that (a `finally`), because a watcher left running
58
+ * would keep polling a dead thread's file forever.
59
+ */
60
+ export declare function watchCodexThreadLiveness(options: CodexLivenessOptions): () => void;
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Codex thread liveness watcher.
3
+ *
4
+ * `codex exec --json` emits nothing on stdout while the model reasons. A single
5
+ * xhigh reasoning block runs minutes with zero bytes on the wire, which is
6
+ * byte-identical to a wedged process — so an inactivity timeout driven only by
7
+ * stdout SIGTERMs healthy runs mid-thought.
8
+ *
9
+ * Codex does keep working during that silence: it appends reasoning summaries
10
+ * to the session rollout file every few seconds for the whole block. That
11
+ * file's mtime is therefore an out-of-band proof of life, and watching it lets
12
+ * the inactivity timeout mean what it is supposed to mean — "this process has
13
+ * stopped doing anything" — instead of "this process has stopped talking".
14
+ *
15
+ * Rollout path:
16
+ * $CODEX_HOME/sessions/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<thread_id>.jsonl
17
+ *
18
+ * The date directories and the filename timestamp are LOCAL time, not UTC.
19
+ *
20
+ * Every failure path here is silent and non-fatal: if the file cannot be found
21
+ * or read, the watcher simply stops poking and the caller falls back to plain
22
+ * stdout-driven timeouts. Liveness detection must never be able to break a run.
23
+ */
24
+ import { readdirSync, statSync } from 'fs';
25
+ import { homedir } from 'os';
26
+ import { join } from 'path';
27
+ // =============================================================================
28
+ // PUBLIC API
29
+ // =============================================================================
30
+ /** Codex's home directory — `$CODEX_HOME` if set, else `~/.codex`. */
31
+ export function getCodexHome() {
32
+ return process.env.CODEX_HOME || join(homedir(), '.codex');
33
+ }
34
+ /**
35
+ * Locate the rollout file for a thread, or `null` if it is not there (yet).
36
+ *
37
+ * Only today's and yesterday's local-date directories are scanned: a run that
38
+ * started before local midnight lands in yesterday's directory, and nothing
39
+ * older can belong to a live process (the caller's absolute max timeout is
40
+ * measured in minutes).
41
+ */
42
+ export function findRolloutFile(threadId, codexHome) {
43
+ const sessions = join(codexHome ?? getCodexHome(), 'sessions');
44
+ const now = Date.now();
45
+ for (const dayOffset of [0, -1]) {
46
+ const d = new Date(now + dayOffset * 86_400_000);
47
+ const dir = join(sessions, String(d.getFullYear()), String(d.getMonth() + 1).padStart(2, '0'), String(d.getDate()).padStart(2, '0'));
48
+ let names;
49
+ try {
50
+ names = readdirSync(dir);
51
+ }
52
+ catch {
53
+ // Directory absent (no sessions that day) — try the next candidate.
54
+ continue;
55
+ }
56
+ const hit = names.find((n) => n.endsWith('.jsonl') && n.includes(threadId));
57
+ if (hit)
58
+ return join(dir, hit);
59
+ }
60
+ return null;
61
+ }
62
+ /**
63
+ * Poll a Codex run's rollout file and call `onActivity` whenever it grows.
64
+ *
65
+ * Returns a stop function. It is idempotent and MUST be called when the run
66
+ * settles — the caller owns that (a `finally`), because a watcher left running
67
+ * would keep polling a dead thread's file forever.
68
+ */
69
+ export function watchCodexThreadLiveness(options) {
70
+ const { threadId, onActivity } = options;
71
+ const pollMs = options.pollMs ?? 15_000;
72
+ const codexHome = options.codexHome ?? getCodexHome();
73
+ const maxDiscoveryAttempts = options.maxDiscoveryAttempts ?? 8;
74
+ let path = null;
75
+ let discoveryAttempts = 0;
76
+ let lastMtimeMs = -1;
77
+ let timer;
78
+ const stop = () => {
79
+ if (timer !== undefined) {
80
+ clearInterval(timer);
81
+ timer = undefined;
82
+ }
83
+ };
84
+ const tick = () => {
85
+ if (path === null) {
86
+ path = findRolloutFile(threadId, codexHome);
87
+ if (path === null) {
88
+ if (++discoveryAttempts >= maxDiscoveryAttempts)
89
+ stop();
90
+ return;
91
+ }
92
+ }
93
+ let mtimeMs;
94
+ try {
95
+ mtimeMs = statSync(path).mtimeMs;
96
+ }
97
+ catch {
98
+ // Transient read failure — keep the timer and retry on the next poll.
99
+ return;
100
+ }
101
+ // The first successful stat only establishes the baseline. Treating it as
102
+ // activity would hand a free reset to a process that has already wedged.
103
+ if (lastMtimeMs < 0) {
104
+ lastMtimeMs = mtimeMs;
105
+ return;
106
+ }
107
+ if (mtimeMs !== lastMtimeMs) {
108
+ lastMtimeMs = mtimeMs;
109
+ try {
110
+ onActivity();
111
+ }
112
+ catch {
113
+ // Intentionally swallowed — a watcher must not break the run.
114
+ }
115
+ }
116
+ };
117
+ timer = setInterval(tick, pollMs);
118
+ // Never hold the event loop open on account of the watcher.
119
+ timer.unref?.();
120
+ return stop;
121
+ }
package/dist/config.d.ts CHANGED
@@ -22,6 +22,16 @@ export declare const CodexConfigSchema: z.ZodDefault<z.ZodObject<{
22
22
  * these to cap cost without affecting review behavior. */
23
23
  consultReasoningEffort: z.ZodDefault<z.ZodEnum<["high", "xhigh"]>>;
24
24
  consultServiceTier: z.ZodDefault<z.ZodEnum<["default", "fast", "flex"]>>;
25
+ /**
26
+ * Fallback ceiling for how long Codex may go silent on stdout.
27
+ *
28
+ * Normally the rollout-file liveness watcher (`codex-liveness.ts`) resets
29
+ * this timer while the model reasons, so it only fires on a genuinely dead
30
+ * process. These values are what protects a run when that watcher cannot
31
+ * find the rollout file (`--ephemeral`, a relocated CODEX_HOME, a layout
32
+ * change), and they must therefore exceed a realistic reasoning block:
33
+ * an xhigh block has been measured at 287s of unbroken silence.
34
+ */
25
35
  inactivityTimeoutMs: z.ZodDefault<z.ZodObject<{
26
36
  high: z.ZodDefault<z.ZodNumber>;
27
37
  xhigh: z.ZodDefault<z.ZodNumber>;
@@ -76,6 +86,13 @@ export declare const ClaudeConfigSchema: z.ZodDefault<z.ZodObject<{
76
86
  maxBufferSize?: number | undefined;
77
87
  }>>;
78
88
  export declare const GeminiConfigSchema: z.ZodDefault<z.ZodObject<{
89
+ /**
90
+ * `agy --print` emits nothing until it is done, so there is no activity to
91
+ * reset this timer and no way to tell a working run from a wedged one —
92
+ * it is effectively a total-runtime cap, and anything under a realistic
93
+ * review duration just kills healthy runs. Same failure mode as Codex's
94
+ * silent reasoning blocks, minus any out-of-band liveness signal to watch.
95
+ */
79
96
  inactivityTimeoutMs: z.ZodDefault<z.ZodNumber>;
80
97
  maxTimeoutMs: z.ZodDefault<z.ZodNumber>;
81
98
  maxBufferSize: z.ZodDefault<z.ZodNumber>;
@@ -98,6 +115,16 @@ export declare const ConfigSchema: z.ZodDefault<z.ZodObject<{
98
115
  * these to cap cost without affecting review behavior. */
99
116
  consultReasoningEffort: z.ZodDefault<z.ZodEnum<["high", "xhigh"]>>;
100
117
  consultServiceTier: z.ZodDefault<z.ZodEnum<["default", "fast", "flex"]>>;
118
+ /**
119
+ * Fallback ceiling for how long Codex may go silent on stdout.
120
+ *
121
+ * Normally the rollout-file liveness watcher (`codex-liveness.ts`) resets
122
+ * this timer while the model reasons, so it only fires on a genuinely dead
123
+ * process. These values are what protects a run when that watcher cannot
124
+ * find the rollout file (`--ephemeral`, a relocated CODEX_HOME, a layout
125
+ * change), and they must therefore exceed a realistic reasoning block:
126
+ * an xhigh block has been measured at 287s of unbroken silence.
127
+ */
101
128
  inactivityTimeoutMs: z.ZodDefault<z.ZodObject<{
102
129
  high: z.ZodDefault<z.ZodNumber>;
103
130
  xhigh: z.ZodDefault<z.ZodNumber>;
@@ -152,6 +179,13 @@ export declare const ConfigSchema: z.ZodDefault<z.ZodObject<{
152
179
  maxBufferSize?: number | undefined;
153
180
  }>>;
154
181
  gemini: z.ZodDefault<z.ZodObject<{
182
+ /**
183
+ * `agy --print` emits nothing until it is done, so there is no activity to
184
+ * reset this timer and no way to tell a working run from a wedged one —
185
+ * it is effectively a total-runtime cap, and anything under a realistic
186
+ * review duration just kills healthy runs. Same failure mode as Codex's
187
+ * silent reasoning blocks, minus any out-of-band liveness signal to watch.
188
+ */
155
189
  inactivityTimeoutMs: z.ZodDefault<z.ZodNumber>;
156
190
  maxTimeoutMs: z.ZodDefault<z.ZodNumber>;
157
191
  maxBufferSize: z.ZodDefault<z.ZodNumber>;
package/dist/config.js CHANGED
@@ -29,10 +29,20 @@ export const CodexConfigSchema = z
29
29
  * these to cap cost without affecting review behavior. */
30
30
  consultReasoningEffort: z.enum(['high', 'xhigh']).default('xhigh'),
31
31
  consultServiceTier: z.enum(['default', 'fast', 'flex']).default('fast'),
32
+ /**
33
+ * Fallback ceiling for how long Codex may go silent on stdout.
34
+ *
35
+ * Normally the rollout-file liveness watcher (`codex-liveness.ts`) resets
36
+ * this timer while the model reasons, so it only fires on a genuinely dead
37
+ * process. These values are what protects a run when that watcher cannot
38
+ * find the rollout file (`--ephemeral`, a relocated CODEX_HOME, a layout
39
+ * change), and they must therefore exceed a realistic reasoning block:
40
+ * an xhigh block has been measured at 287s of unbroken silence.
41
+ */
32
42
  inactivityTimeoutMs: z
33
43
  .object({
34
- high: z.number().int().positive().default(180_000),
35
- xhigh: z.number().int().positive().default(300_000),
44
+ high: z.number().int().positive().default(300_000),
45
+ xhigh: z.number().int().positive().default(600_000),
36
46
  })
37
47
  .default({}),
38
48
  maxTimeoutMs: z.number().int().positive().default(3_600_000),
@@ -52,7 +62,14 @@ export const ClaudeConfigSchema = z
52
62
  // enforces them regardless of the underlying CLI.
53
63
  export const GeminiConfigSchema = z
54
64
  .object({
55
- inactivityTimeoutMs: z.number().int().positive().default(300_000),
65
+ /**
66
+ * `agy --print` emits nothing until it is done, so there is no activity to
67
+ * reset this timer and no way to tell a working run from a wedged one —
68
+ * it is effectively a total-runtime cap, and anything under a realistic
69
+ * review duration just kills healthy runs. Same failure mode as Codex's
70
+ * silent reasoning blocks, minus any out-of-band liveness signal to watch.
71
+ */
72
+ inactivityTimeoutMs: z.number().int().positive().default(900_000),
56
73
  maxTimeoutMs: z.number().int().positive().default(3_600_000),
57
74
  maxBufferSize: z.number().int().positive().default(1_048_576),
58
75
  })
@@ -40,6 +40,7 @@ export declare class CodexEventDecoder {
40
40
  * @param detail - A human-readable detail string for logging (may be undefined).
41
41
  */
42
42
  onProgress?: (eventType: string, detail?: string) => void;
43
+ private _threadId;
43
44
  private _finalResponse;
44
45
  private _usage;
45
46
  private _error;
@@ -49,6 +50,11 @@ export declare class CodexEventDecoder {
49
50
  * Parse a single JSONL line. Silently skips malformed or empty input.
50
51
  */
51
52
  processLine(line: string): void;
53
+ /**
54
+ * Returns the `thread_id` from `thread.started`, or `null` if that event has
55
+ * not been seen. Used to locate the session rollout file on disk.
56
+ */
57
+ getThreadId(): string | null;
52
58
  /**
53
59
  * Returns the text from the LAST `item.completed` event whose item type is
54
60
  * `"agent_message"`, or `null` if no such event has been seen.
@@ -21,6 +21,9 @@ export class CodexEventDecoder {
21
21
  * @param detail - A human-readable detail string for logging (may be undefined).
22
22
  */
23
23
  onProgress;
24
+ // The thread id from `thread.started` — arrives within the first second and
25
+ // identifies the session rollout file used for out-of-band liveness checks.
26
+ _threadId = null;
24
27
  // The text from the most recently seen item.completed with item.type === "agent_message"
25
28
  _finalResponse = null;
26
29
  // Token usage from the most recently seen turn.completed
@@ -59,6 +62,13 @@ export class CodexEventDecoder {
59
62
  }
60
63
  this._handleEvent(event);
61
64
  }
65
+ /**
66
+ * Returns the `thread_id` from `thread.started`, or `null` if that event has
67
+ * not been seen. Used to locate the session rollout file on disk.
68
+ */
69
+ getThreadId() {
70
+ return this._threadId;
71
+ }
62
72
  /**
63
73
  * Returns the text from the LAST `item.completed` event whose item type is
64
74
  * `"agent_message"`, or `null` if no such event has been seen.
@@ -102,6 +112,10 @@ export class CodexEventDecoder {
102
112
  // =============================================================================
103
113
  _handleEvent(event) {
104
114
  this._eventCount++;
115
+ // Track the thread id so callers can find this run's rollout file
116
+ if (event.type === 'thread.started' && typeof event.thread_id === 'string') {
117
+ this._threadId = event.thread_id;
118
+ }
105
119
  // Track the last agent_message text
106
120
  if (event.type === 'item.completed' &&
107
121
  event.item?.type === 'agent_message' &&
@@ -92,6 +92,20 @@ export declare class CliExecutor {
92
92
  * so a stalled process is detected sooner after it starts responding.
93
93
  */
94
94
  setInactivityTimeout(ms: number): void;
95
+ /**
96
+ * Reset the inactivity timer without any stdout/stderr byte having arrived.
97
+ *
98
+ * For a CLI whose event stream goes silent while it is still working — Codex
99
+ * emits nothing on stdout for the whole of a reasoning block — stdout bytes
100
+ * are not a liveness signal, and a timer driven only by them kills healthy
101
+ * processes mid-thought. Callers that can prove liveness out of band (a
102
+ * growing session/log file, a status socket) call this to keep the process
103
+ * alive.
104
+ *
105
+ * No-op before run() and after the process has settled, so a watcher that
106
+ * fires late cannot resurrect a finished run's timer.
107
+ */
108
+ noteActivity(): void;
95
109
  /**
96
110
  * Spawn the process and return a promise that resolves with CliResult on
97
111
  * normal completion (any exit code) or rejects with:
package/dist/executor.js CHANGED
@@ -62,6 +62,22 @@ export class CliExecutor {
62
62
  // Restart the running timer (if any) with the new duration.
63
63
  this.resetInactivityFn?.();
64
64
  }
65
+ /**
66
+ * Reset the inactivity timer without any stdout/stderr byte having arrived.
67
+ *
68
+ * For a CLI whose event stream goes silent while it is still working — Codex
69
+ * emits nothing on stdout for the whole of a reasoning block — stdout bytes
70
+ * are not a liveness signal, and a timer driven only by them kills healthy
71
+ * processes mid-thought. Callers that can prove liveness out of band (a
72
+ * growing session/log file, a status socket) call this to keep the process
73
+ * alive.
74
+ *
75
+ * No-op before run() and after the process has settled, so a watcher that
76
+ * fires late cannot resurrect a finished run's timer.
77
+ */
78
+ noteActivity() {
79
+ this.resetInactivityFn?.();
80
+ }
65
81
  /**
66
82
  * Spawn the process and return a promise that resolves with CliResult on
67
83
  * normal completion (any exit code) or rejects with:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simonren/quorum",
3
- "version": "0.8.1",
3
+ "version": "0.9.0",
4
4
  "description": "MCP server for Claude Code — a quorum of AI models (Codex, Gemini, Claude) for adversarial review and consultation, synthesized by Claude Code",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",