@simonren/quorum 0.9.0 → 0.11.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.
Files changed (68) hide show
  1. package/README.md +91 -48
  2. package/commands/multi-consult.md +47 -72
  3. package/commands/multi-review.md +68 -99
  4. package/dist/adapters/base.d.ts +53 -70
  5. package/dist/adapters/base.js +21 -79
  6. package/dist/adapters/claude.d.ts +38 -17
  7. package/dist/adapters/claude.js +93 -185
  8. package/dist/adapters/cli-adapter.d.ts +78 -0
  9. package/dist/adapters/cli-adapter.js +217 -0
  10. package/dist/adapters/codex.d.ts +18 -13
  11. package/dist/adapters/codex.js +64 -200
  12. package/dist/adapters/gemini.d.ts +30 -20
  13. package/dist/adapters/gemini.js +56 -148
  14. package/dist/adapters/index.d.ts +8 -5
  15. package/dist/adapters/index.js +7 -8
  16. package/dist/config.d.ts +116 -28
  17. package/dist/config.js +50 -28
  18. package/dist/consult-prompt.d.ts +6 -5
  19. package/dist/consult-prompt.js +48 -23
  20. package/dist/decoders/claude.d.ts +6 -0
  21. package/dist/decoders/claude.js +10 -1
  22. package/dist/doctor.d.ts +20 -0
  23. package/dist/doctor.js +91 -0
  24. package/dist/executor.d.ts +58 -46
  25. package/dist/executor.js +218 -129
  26. package/dist/guards.d.ts +29 -0
  27. package/dist/guards.js +72 -0
  28. package/dist/handoff.d.ts +79 -229
  29. package/dist/handoff.js +411 -402
  30. package/dist/index.d.ts +8 -12
  31. package/dist/index.js +81 -106
  32. package/dist/integrity.d.ts +16 -0
  33. package/dist/integrity.js +49 -0
  34. package/dist/sections.d.ts +22 -0
  35. package/dist/sections.js +31 -0
  36. package/dist/server.d.ts +9 -0
  37. package/dist/server.js +36 -0
  38. package/dist/tools/consult.d.ts +17 -76
  39. package/dist/tools/consult.js +72 -188
  40. package/dist/tools/format.d.ts +35 -0
  41. package/dist/tools/format.js +85 -0
  42. package/dist/tools/review.d.ts +55 -0
  43. package/dist/tools/review.js +120 -0
  44. package/dist/types.d.ts +20 -103
  45. package/dist/types.js +18 -29
  46. package/package.json +7 -4
  47. package/dist/cli/check.d.ts +0 -20
  48. package/dist/cli/check.js +0 -78
  49. package/dist/cli/codex.d.ts +0 -11
  50. package/dist/cli/codex.js +0 -255
  51. package/dist/cli/gemini.d.ts +0 -12
  52. package/dist/cli/gemini.js +0 -253
  53. package/dist/context.d.ts +0 -1538
  54. package/dist/context.js +0 -383
  55. package/dist/decoders/gemini.d.ts +0 -33
  56. package/dist/decoders/gemini.js +0 -58
  57. package/dist/errors.d.ts +0 -46
  58. package/dist/errors.js +0 -198
  59. package/dist/pipeline.d.ts +0 -135
  60. package/dist/pipeline.js +0 -462
  61. package/dist/prompt-v2.d.ts +0 -38
  62. package/dist/prompt-v2.js +0 -391
  63. package/dist/prompt.d.ts +0 -71
  64. package/dist/prompt.js +0 -309
  65. package/dist/schema.d.ts +0 -660
  66. package/dist/schema.js +0 -536
  67. package/dist/tools/feedback.d.ts +0 -91
  68. package/dist/tools/feedback.js +0 -117
@@ -13,6 +13,9 @@ export interface ClaudeEvent {
13
13
  model?: string;
14
14
  result?: string;
15
15
  is_error?: boolean;
16
+ /** Present on failed results (e.g. error_during_execution). */
17
+ errors?: string[];
18
+ api_error_status?: number;
16
19
  duration_ms?: number;
17
20
  message?: {
18
21
  content?: Array<{
@@ -40,12 +43,15 @@ export declare class ClaudeEventDecoder {
40
43
  private _finalResponse;
41
44
  private _usage;
42
45
  private _error;
46
+ private _resultIsError;
43
47
  private _eventCount;
44
48
  private _durationMs;
45
49
  processLine(line: string): void;
46
50
  getFinalResponse(): string | null;
47
51
  getUsage(): ClaudeEvent['usage'] | null;
48
52
  getError(): string | null;
53
+ /** True when the final `result` event carried `is_error: true` — terminal, whatever the exit code. */
54
+ isResultError(): boolean;
49
55
  getDurationMs(): number | null;
50
56
  hasNoOutput(): boolean;
51
57
  private _handleEvent;
@@ -14,6 +14,7 @@ export class ClaudeEventDecoder {
14
14
  _finalResponse = null;
15
15
  _usage = null;
16
16
  _error = null;
17
+ _resultIsError = false;
17
18
  _eventCount = 0;
18
19
  _durationMs = null;
19
20
  // =============================================================================
@@ -46,6 +47,10 @@ export class ClaudeEventDecoder {
46
47
  getError() {
47
48
  return this._error;
48
49
  }
50
+ /** True when the final `result` event carried `is_error: true` — terminal, whatever the exit code. */
51
+ isResultError() {
52
+ return this._resultIsError;
53
+ }
49
54
  getDurationMs() {
50
55
  return this._durationMs;
51
56
  }
@@ -64,7 +69,11 @@ export class ClaudeEventDecoder {
64
69
  this._finalResponse = event.result;
65
70
  }
66
71
  if (event.is_error) {
67
- this._error = event.result || 'Claude review failed';
72
+ this._resultIsError = true;
73
+ const detail = event.result
74
+ || (Array.isArray(event.errors) ? event.errors.filter((e) => typeof e === 'string' && e).join('; ') : '')
75
+ || (event.api_error_status != null ? `API error status ${event.api_error_status}` : '');
76
+ this._error = detail || `Claude ${event.subtype || 'run'} failed`;
68
77
  }
69
78
  if (event.usage) {
70
79
  this._usage = event.usage;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * `quorum doctor` — show what the server would detect, without starting it.
3
+ *
4
+ * Also backs the start-up status log on stderr.
5
+ */
6
+ export interface AdapterStatus {
7
+ id: string;
8
+ name: string;
9
+ enabled: boolean;
10
+ available: boolean;
11
+ version: string | null;
12
+ settings: string;
13
+ }
14
+ export declare function collectAdapterStatus(options?: {
15
+ fresh?: boolean;
16
+ }): Promise<AdapterStatus[]>;
17
+ /** Start-up log on stderr (stdout is the MCP transport). */
18
+ export declare function logCliStatus(): Promise<void>;
19
+ /** `quorum doctor`: full report on stdout. Returns the process exit code. */
20
+ export declare function runDoctor(version: string): Promise<number>;
package/dist/doctor.js ADDED
@@ -0,0 +1,91 @@
1
+ /**
2
+ * `quorum doctor` — show what the server would detect, without starting it.
3
+ *
4
+ * Also backs the start-up status log on stderr.
5
+ */
6
+ import { existsSync } from 'fs';
7
+ import { getAllAdapters } from './adapters/index.js';
8
+ import { CliAdapter } from './adapters/cli-adapter.js';
9
+ import { getConfig, getConfigPath } from './config.js';
10
+ import { getCommandPaths } from './commands.js';
11
+ function describeSettings(id) {
12
+ const cfg = getConfig();
13
+ switch (id) {
14
+ case 'codex': {
15
+ const c = cfg.codex;
16
+ return `model=${c.model} review=${c.reasoningEffort}/${c.serviceTier} consult=${c.consultReasoningEffort}/${c.consultServiceTier}`;
17
+ }
18
+ case 'claude': {
19
+ const c = cfg.claude;
20
+ const fallback = c.fallbackModel
21
+ ? ` fallback=${c.fallbackModel}${c.fallbackModel === c.model ? ' (same as model — set claude.fallbackModel to another alias or null)' : ''}`
22
+ : '';
23
+ return `model=${c.model}${fallback} effort=${c.effort ?? 'cli-default'} consultEffort=${c.consultEffort ?? 'cli-default'}`;
24
+ }
25
+ case 'gemini': {
26
+ const c = cfg.gemini;
27
+ return `model=${c.model ?? 'agy-default'}`;
28
+ }
29
+ default:
30
+ return '';
31
+ }
32
+ }
33
+ export async function collectAdapterStatus(options) {
34
+ const adapters = getAllAdapters();
35
+ return Promise.all(adapters.map(async (adapter) => {
36
+ const enabled = adapter.isEnabled();
37
+ const available = await adapter.isAvailable(options);
38
+ const version = adapter instanceof CliAdapter ? await adapter.getVersion(options) : null;
39
+ return {
40
+ id: adapter.id,
41
+ name: adapter.getCapabilities().name,
42
+ enabled,
43
+ available,
44
+ version,
45
+ settings: describeSettings(adapter.id),
46
+ };
47
+ }));
48
+ }
49
+ function formatStatusLine(s) {
50
+ const state = !s.enabled
51
+ ? '– disabled in config'
52
+ : s.available
53
+ ? `✓ ${s.version ?? 'available'}`
54
+ : '✗ not found';
55
+ return ` - ${s.name.padEnd(7)} ${state}`;
56
+ }
57
+ /** Start-up log on stderr (stdout is the MCP transport). */
58
+ export async function logCliStatus() {
59
+ const statuses = await collectAdapterStatus();
60
+ console.error('[quorum] Reviewer CLIs:');
61
+ for (const s of statuses)
62
+ console.error(formatStatusLine(s));
63
+ if (!statuses.some((s) => s.enabled && s.available)) {
64
+ console.error('[quorum] Warning: no reviewer CLI available. Install codex, agy, or claude — or run `quorum doctor`.');
65
+ }
66
+ }
67
+ /** `quorum doctor`: full report on stdout. Returns the process exit code. */
68
+ export async function runDoctor(version) {
69
+ const configPath = getConfigPath();
70
+ const { target } = getCommandPaths();
71
+ const statuses = await collectAdapterStatus({ fresh: true });
72
+ console.log(`quorum v${version}`);
73
+ console.log(`node ${process.version}`);
74
+ console.log(`config: ${configPath}${existsSync(configPath) ? '' : ' (not created yet — starts on first server launch)'}`);
75
+ console.log(`slash commands: ${target}`);
76
+ console.log('');
77
+ console.log('Reviewer CLIs:');
78
+ for (const s of statuses) {
79
+ console.log(formatStatusLine(s));
80
+ if (s.settings)
81
+ console.log(` ${s.settings}`);
82
+ }
83
+ const usable = statuses.filter((s) => s.enabled && s.available);
84
+ console.log('');
85
+ if (usable.length === 0) {
86
+ console.log('✗ No usable reviewer. Install at least one CLI (see README) or re-enable one in the config.');
87
+ return 1;
88
+ }
89
+ console.log(`✓ ${usable.length} reviewer${usable.length === 1 ? '' : 's'} ready: ${usable.map((s) => s.id).join(', ')}`);
90
+ return 0;
91
+ }
@@ -1,23 +1,52 @@
1
1
  /**
2
- * CliExecutor — Shared process management for external AI CLI tools.
2
+ * CliExecutor — shared process management for external AI CLI tools.
3
3
  *
4
- * Extracted from the duplicated spawn logic in codex.ts and gemini.ts to
5
- * provide a single, well-tested implementation of:
6
- * - Child-process spawning with stdin delivery
7
- * - Line-buffered stdout parsing (JSONL-friendly)
8
- * - Inactivity and absolute-max timeouts
9
- * - Max buffer size enforcement with truncation flag
10
- * - Settled guard to prevent double resolve/reject
11
- * - Dynamic inactivity timeout adjustment via setInactivityTimeout()
4
+ * One implementation of everything that is easy to get subtly wrong:
5
+ * - child-process spawning with stdin delivery
6
+ * - UTF-8-safe, line-buffered stdout parsing (JSONL-friendly)
7
+ * - inactivity and absolute-max timeouts, with out-of-band liveness resets
8
+ * - process-group SIGTERM → SIGKILL escalation so a stuck CLI — and anything
9
+ * it forked — cannot outlive its timeout
10
+ * - a registry of live children so the server can reap them on shutdown
11
+ * - max buffer enforcement with a truncation flag
12
+ * - a settled guard against double resolve/reject
12
13
  */
14
+ import { ChildProcess } from 'child_process';
15
+ /**
16
+ * Signal a child and, on POSIX, its whole process group. Children are spawned
17
+ * detached (own group) so that whatever the CLI forked — a launcher's native
18
+ * binary, a reviewer's shell or MCP children — dies with it. A wrapper can
19
+ * forward SIGTERM but never SIGKILL, so signalling only the direct pid would
20
+ * orphan the real worker on escalation.
21
+ */
22
+ export declare function killTree(child: ChildProcess, signal: NodeJS.Signals): boolean;
23
+ /** Number of CLI processes currently running under this server. */
24
+ export declare function activeChildCount(): number;
25
+ /**
26
+ * Send `signal` to every live child. Returns how many were signalled.
27
+ * Idempotent and safe to call when nothing is running.
28
+ */
29
+ export declare function shutdownChildren(signal?: NodeJS.Signals): number;
30
+ /**
31
+ * Install process-level hooks (once) so that the server exiting — normally,
32
+ * on SIGINT/SIGTERM/SIGHUP, or because the MCP client hung up — never leaves
33
+ * a Codex/Claude/agy process behind burning tokens. Called lazily on the
34
+ * first spawn; `index.ts` also calls it explicitly.
35
+ */
36
+ export declare function installChildCleanupHooks(): void;
37
+ /**
38
+ * Terminate children politely, wait briefly for them to go, then exit.
39
+ * Survivors are SIGKILLed by the `exit` hook.
40
+ */
41
+ export declare function gracefulExit(code: number, graceMs?: number): Promise<never>;
13
42
  export interface CliExecutorOptions {
14
- /** Executable to spawn (e.g. 'codex', 'gemini', 'bash'). */
43
+ /** Executable to spawn (e.g. 'codex', 'agy', 'claude'). */
15
44
  command: string;
16
45
  /** Arguments passed to the command. */
17
46
  args: string[];
18
47
  /** Working directory for the spawned process. */
19
48
  cwd: string;
20
- /** Optional content to write to the process's stdin then close it. */
49
+ /** Optional content to write to the process's stdin, after which stdin is closed. */
21
50
  stdin?: string;
22
51
  /** Additional environment variables merged over process.env. */
23
52
  env?: Record<string, string>;
@@ -33,8 +62,7 @@ export interface CliExecutorOptions {
33
62
  onStderr?: (data: string) => void;
34
63
  /**
35
64
  * Milliseconds of stdout/stderr inactivity before the process is killed
36
- * and the promise rejects with Error('TIMEOUT').
37
- * Default: 120_000 (2 minutes).
65
+ * and the promise rejects with Error('TIMEOUT'). Default: 120_000.
38
66
  */
39
67
  inactivityTimeoutMs?: number;
40
68
  /**
@@ -44,18 +72,22 @@ export interface CliExecutorOptions {
44
72
  */
45
73
  maxTimeoutMs?: number;
46
74
  /**
47
- * Maximum number of bytes accumulated in rawStdout before truncation.
48
- * Once exceeded, rawStdout is capped and truncated is set to true.
49
- * Default: 1_048_576 (1 MB).
75
+ * Maximum number of characters accumulated in rawStdout (and, separately,
76
+ * stderr) before truncation. Default: 1_048_576.
50
77
  */
51
78
  maxBufferSize?: number;
79
+ /**
80
+ * How long after SIGTERM to wait before escalating to SIGKILL.
81
+ * Default: 5_000.
82
+ */
83
+ killGraceMs?: number;
52
84
  }
53
85
  export interface CliResult {
54
86
  /** Lines split on '\n', excluding the trailing empty string from a final newline. */
55
87
  stdoutLines: string[];
56
88
  /** Raw accumulated stdout string (may be truncated). */
57
89
  rawStdout: string;
58
- /** Accumulated stderr string. */
90
+ /** Accumulated stderr string (may be truncated). */
59
91
  stderr: string;
60
92
  /** Process exit code; -1 if the process was killed without an exit code. */
61
93
  exitCode: number;
@@ -64,46 +96,26 @@ export interface CliResult {
64
96
  }
65
97
  export declare class CliExecutor {
66
98
  private readonly opts;
67
- /**
68
- * Mutable inactivity timeout — callers can tighten it after first streaming
69
- * event via setInactivityTimeout(). Changing it clears and restarts the
70
- * currently running inactivity timer immediately.
71
- */
99
+ /** Mutable inactivity timeout — see setInactivityTimeout(). */
72
100
  private currentInactivityMs;
73
- /**
74
- * Handle to the live inactivity timer (kept here so setInactivityTimeout
75
- * can reset it from outside the Promise closure via the shared ref below).
76
- */
77
101
  private inactivityTimer;
78
- /**
79
- * Injected by run() so setInactivityTimeout can restart the timer using
80
- * the correct reject handle while the process is still running.
81
- */
102
+ /** Injected by run() so the timer can be restarted from outside the closure. */
82
103
  private resetInactivityFn;
83
104
  constructor(options: CliExecutorOptions);
84
105
  /**
85
- * Dynamically adjust the inactivity timeout.
86
- *
87
- * If the process is currently running, the active inactivity timer is
88
- * cancelled and restarted with the new duration immediately. Subsequent
89
- * activity resets will also use this new value.
90
- *
91
- * Typical use: tighten the timeout once the first streaming event arrives,
92
- * so a stalled process is detected sooner after it starts responding.
106
+ * Dynamically adjust the inactivity timeout. If the process is running, the
107
+ * active timer is restarted with the new duration immediately.
93
108
  */
94
109
  setInactivityTimeout(ms: number): void;
95
110
  /**
96
111
  * Reset the inactivity timer without any stdout/stderr byte having arrived.
97
112
  *
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.
113
+ * For a CLI whose event stream goes silent while it is still working (Codex
114
+ * emits nothing during a reasoning block) stdout bytes are not a liveness
115
+ * signal. Callers that can prove liveness out of band (a growing rollout
116
+ * file) call this to keep the process alive.
104
117
  *
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.
118
+ * No-op before run() and after the process has settled.
107
119
  */
108
120
  noteActivity(): void;
109
121
  /**