@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
@@ -1,120 +1,103 @@
1
1
  /**
2
- * Base Adapter Interface for AI Reviewers
2
+ * Reviewer adapter contract and registry.
3
3
  *
4
- * This provides a generic interface that any AI CLI can implement.
5
- * Makes it easy to add new models (Ollama, Azure, etc.) without
6
- * changing the core orchestration logic.
4
+ * An adapter wraps one external AI CLI (Codex, Gemini via agy, Claude Code).
5
+ * Adapters return the model's raw text; Claude Code (CC) interprets it. The
6
+ * shared spawn/timeout/error machinery lives in `cli-adapter.ts`; this file
7
+ * only defines the types every adapter must satisfy and the registry the tool
8
+ * handlers query.
7
9
  */
8
10
  import { FocusArea, OutputType, ReasoningEffort, ServiceTier } from '../types.js';
9
11
  export interface ReviewerCapabilities {
10
- /** Display name for this reviewer */
12
+ /** Display name, e.g. "Codex". */
11
13
  name: string;
12
- /** Short description of the reviewer's strengths */
14
+ /** One-line description shown by `quorum doctor`. */
13
15
  description: string;
14
- /** Focus areas this reviewer excels at */
15
- strengths: FocusArea[];
16
- /** Focus areas this reviewer is weaker at */
17
- weaknesses: FocusArea[];
18
- /** Whether the reviewer can read files from the filesystem */
19
- hasFilesystemAccess: boolean;
20
- /** Whether the reviewer supports JSON structured output */
21
- supportsStructuredOutput: boolean;
22
- /** Maximum context window size (tokens) */
23
- maxContextTokens: number;
24
- /** Supported reasoning effort levels (if applicable) */
25
- reasoningLevels?: ReasoningEffort[];
26
16
  }
17
+ export type ReviewMode = 'standard' | 'adversarial';
27
18
  export interface ReviewRequest {
28
- /** Working directory containing the code */
19
+ /** Working directory containing the code. */
29
20
  workingDir: string;
30
- /** Claude Code's output to review */
21
+ /** CC's structured brief (SUMMARY / UNCERTAINTIES / QUESTIONS / ...). */
31
22
  ccOutput: string;
32
- /** Type of output being reviewed */
23
+ /** What kind of work the brief describes. */
33
24
  outputType: OutputType;
34
- /** Specific files that CC analyzed */
25
+ /** Files CC created or modified — reviewers start there. */
35
26
  analyzedFiles?: string[];
36
- /** Areas to focus the review on */
27
+ /** Areas to weight in the review. */
37
28
  focusAreas?: FocusArea[];
38
- /** Custom instructions from the user */
29
+ /** Free-form steering from the user. */
39
30
  customPrompt?: string;
40
- /** Reasoning effort level (for models that support it) */
31
+ /** Git ref the change is relative to when the tree is clean (a checked-out PR). */
32
+ baseRef?: string;
33
+ /** Codex reasoning effort (config default when omitted). */
41
34
  reasoningEffort?: ReasoningEffort;
42
- /** Service tier (Codex). Omit for the review chain's default 'fast' (priority). Pass 'flex' for cheap/slow or 'default' for the Codex API default tier. */
35
+ /** Codex service tier (config default when omitted; 'default' emits no flag). */
43
36
  serviceTier?: ServiceTier;
44
- /** Review mode: standard finds bugs, adversarial challenges assumptions */
45
- reviewMode?: 'standard' | 'adversarial';
37
+ /** Standard pass finds bugs; adversarial pass attacks assumptions. */
38
+ reviewMode?: ReviewMode;
46
39
  }
47
40
  export interface ConsultRequest {
48
- /** Working directory containing the code (always passed) */
41
+ /** Working directory (always passed, even for general questions). */
49
42
  workingDir: string;
50
- /** CC-composed, self-contained question for the panel */
43
+ /** CC-composed, self-contained question for the panel. */
51
44
  question: string;
52
- /** CC-triaged file subset for code-grounded questions; omitted on general questions */
45
+ /** CC-triaged file subset for code-grounded questions; omitted on general ones. */
53
46
  relevantFiles?: string[];
54
- /** Free-form steering from $ARGUMENTS */
47
+ /** Free-form steering from the user. */
55
48
  customPrompt?: string;
56
- /** Reasoning effort (Codex). Default 'xhigh' for consult (deeper questions). */
49
+ /** Codex reasoning effort (consult config default when omitted). */
57
50
  reasoningEffort?: ReasoningEffort;
58
- /** Service tier (Codex). Same defaulting rules as ReviewRequest. */
51
+ /** Codex service tier (consult config default when omitted). */
59
52
  serviceTier?: ServiceTier;
60
53
  }
61
- export type ConsultResult = ReviewResult;
62
- /** @deprecated Use handoff.ts roles instead */
63
- export interface ExpertRole {
64
- name: string;
65
- description: string;
66
- systemPrompt: string;
67
- focusAreas: FocusArea[];
68
- evaluationCriteria: string[];
54
+ export type ReviewErrorType = 'cli_not_found' | 'timeout' | 'rate_limit' | 'auth_error' | 'cli_error';
55
+ export interface ReviewError {
56
+ type: ReviewErrorType;
57
+ message: string;
58
+ details?: Record<string, unknown>;
69
59
  }
70
- /** @deprecated Use handoff.ts selectRole() instead */
71
- export declare const EXPERT_ROLES: Record<string, ExpertRole>;
72
- /** @deprecated Use handoff.ts selectRole() instead */
73
- export declare function selectExpertRole(focusAreas?: FocusArea[]): ExpertRole;
74
60
  export interface ReviewSuccess {
75
61
  success: true;
62
+ /** Raw model text — CC interprets it. */
76
63
  output: string;
77
64
  executionTimeMs: number;
65
+ /** True when the executor capped the CLI's stdout at maxBufferSize. */
66
+ truncated?: boolean;
78
67
  }
79
68
  export interface ReviewFailure {
80
69
  success: false;
81
70
  error: ReviewError;
82
71
  suggestion?: string;
83
- rawOutput?: string;
84
72
  executionTimeMs: number;
85
73
  }
86
74
  export type ReviewResult = ReviewSuccess | ReviewFailure;
87
- export interface ReviewError {
88
- type: 'cli_not_found' | 'timeout' | 'rate_limit' | 'auth_error' | 'invalid_response' | 'cli_error' | 'parse_error';
89
- message: string;
90
- details?: Record<string, unknown>;
91
- }
92
- /**
93
- * Base interface that all reviewer adapters must implement.
94
- * This allows easy addition of new AI CLIs without changing orchestration logic.
95
- */
75
+ export type ConsultResult = ReviewResult;
96
76
  export interface ReviewerAdapter {
97
- /** Unique identifier for this adapter */
77
+ /** Unique id; doubles as the config section key (`codex`, `gemini`, `claude`). */
98
78
  readonly id: string;
99
- /** Get capabilities and metadata for this reviewer */
100
79
  getCapabilities(): ReviewerCapabilities;
101
- /** Check if the CLI is available and properly configured */
102
- isAvailable(): Promise<boolean>;
103
- /** Run a review and return structured output */
104
- runReview(request: ReviewRequest): Promise<ReviewResult>;
105
- /** Run a consultation (Q&A) — required on every adapter. */
106
- runConsult(request: ConsultRequest): Promise<ConsultResult>;
80
+ /** Whether the user has left this adapter enabled in config. */
81
+ isEnabled(): boolean;
107
82
  /**
108
- * Optional: Run peer review of another model's output
109
- * Future capability - not currently implemented by any adapter
83
+ * Whether the CLI is installed and runnable. Implementations may cache the
84
+ * answer briefly; pass `{ fresh: true }` to force a re-probe.
110
85
  */
111
- runPeerReview?(originalRequest: ReviewRequest, reviewToScore: string): Promise<ReviewResult>;
86
+ isAvailable(options?: {
87
+ fresh?: boolean;
88
+ }): Promise<boolean>;
89
+ runReview(request: ReviewRequest): Promise<ReviewResult>;
90
+ runConsult(request: ConsultRequest): Promise<ConsultResult>;
112
91
  }
113
92
  export declare function registerAdapter(adapter: ReviewerAdapter): void;
114
93
  export declare function getAdapter(id: string): ReviewerAdapter | undefined;
115
94
  export declare function getAllAdapters(): ReviewerAdapter[];
116
- export declare function getAvailableAdapters(): Promise<ReviewerAdapter[]>;
95
+ /** Whether config leaves the adapter with this id enabled (default: yes). */
96
+ export declare function isAdapterEnabledInConfig(id: string): boolean;
117
97
  /**
118
- * Select the best available adapter for given focus areas
98
+ * Adapters that are enabled in config AND whose CLI answers a `--version`
99
+ * probe. Availability probes run in parallel.
119
100
  */
120
- export declare function selectBestAdapter(focusAreas?: FocusArea[]): Promise<ReviewerAdapter | null>;
101
+ export declare function getAvailableAdapters(options?: {
102
+ fresh?: boolean;
103
+ }): Promise<ReviewerAdapter[]>;
@@ -1,55 +1,15 @@
1
1
  /**
2
- * Base Adapter Interface for AI Reviewers
2
+ * Reviewer adapter contract and registry.
3
3
  *
4
- * This provides a generic interface that any AI CLI can implement.
5
- * Makes it easy to add new models (Ollama, Azure, etc.) without
6
- * changing the core orchestration logic.
4
+ * An adapter wraps one external AI CLI (Codex, Gemini via agy, Claude Code).
5
+ * Adapters return the model's raw text; Claude Code (CC) interprets it. The
6
+ * shared spawn/timeout/error machinery lives in `cli-adapter.ts`; this file
7
+ * only defines the types every adapter must satisfy and the registry the tool
8
+ * handlers query.
7
9
  */
8
- /** @deprecated Use handoff.ts selectRole() instead */
9
- export const EXPERT_ROLES = {
10
- security_auditor: {
11
- name: 'Security Auditor', description: 'Security vulnerabilities',
12
- systemPrompt: 'Security auditor. Focus on injection, auth bypass, data exposure, input validation.',
13
- focusAreas: ['security'], evaluationCriteria: ['Injection', 'Auth', 'Data exposure'],
14
- },
15
- performance_engineer: {
16
- name: 'Performance Engineer', description: 'Performance optimization',
17
- systemPrompt: 'Performance engineer. Focus on complexity, N+1 queries, memory leaks.',
18
- focusAreas: ['performance', 'scalability'], evaluationCriteria: ['Complexity', 'Memory', 'I/O'],
19
- },
20
- architect: {
21
- name: 'Software Architect', description: 'Architecture and design',
22
- systemPrompt: 'Software architect. Focus on SOLID, coupling, abstractions.',
23
- focusAreas: ['architecture', 'maintainability'], evaluationCriteria: ['SOLID', 'Coupling', 'Patterns'],
24
- },
25
- correctness_analyst: {
26
- name: 'Correctness Analyst', description: 'Logic errors and bugs',
27
- systemPrompt: 'Correctness analyst. Focus on logic errors, edge cases, race conditions.',
28
- focusAreas: ['correctness', 'testing'], evaluationCriteria: ['Logic', 'Edge cases', 'Concurrency'],
29
- },
30
- general_reviewer: {
31
- name: 'General Reviewer', description: 'Balanced review',
32
- systemPrompt: 'Senior engineer. Review correctness, security, performance, maintainability.',
33
- focusAreas: ['security', 'performance', 'architecture', 'correctness', 'maintainability'],
34
- evaluationCriteria: ['Correctness', 'Security', 'Performance', 'Quality'],
35
- },
36
- };
37
- /** @deprecated Use handoff.ts selectRole() instead */
38
- export function selectExpertRole(focusAreas) {
39
- if (!focusAreas || focusAreas.length === 0)
40
- return EXPERT_ROLES.general_reviewer;
41
- if (focusAreas.includes('security'))
42
- return EXPERT_ROLES.security_auditor;
43
- if (focusAreas.includes('performance') || focusAreas.includes('scalability'))
44
- return EXPERT_ROLES.performance_engineer;
45
- if (focusAreas.includes('architecture') || focusAreas.includes('maintainability'))
46
- return EXPERT_ROLES.architect;
47
- if (focusAreas.includes('correctness') || focusAreas.includes('testing'))
48
- return EXPERT_ROLES.correctness_analyst;
49
- return EXPERT_ROLES.general_reviewer;
50
- }
10
+ import { getConfig } from '../config.js';
51
11
  // =============================================================================
52
- // ADAPTER REGISTRY
12
+ // REGISTRY
53
13
  // =============================================================================
54
14
  const adapterRegistry = new Map();
55
15
  export function registerAdapter(adapter) {
@@ -61,38 +21,20 @@ export function getAdapter(id) {
61
21
  export function getAllAdapters() {
62
22
  return Array.from(adapterRegistry.values());
63
23
  }
64
- export async function getAvailableAdapters() {
65
- const adapters = getAllAdapters();
66
- const availability = await Promise.all(adapters.map(async (adapter) => ({
67
- adapter,
68
- available: await adapter.isAvailable(),
69
- })));
70
- return availability.filter((a) => a.available).map((a) => a.adapter);
24
+ /** Whether config leaves the adapter with this id enabled (default: yes). */
25
+ export function isAdapterEnabledInConfig(id) {
26
+ const section = getConfig()[id];
27
+ if (typeof section !== 'object' || section === null)
28
+ return true;
29
+ const enabled = section.enabled;
30
+ return enabled !== false;
71
31
  }
72
32
  /**
73
- * Select the best available adapter for given focus areas
33
+ * Adapters that are enabled in config AND whose CLI answers a `--version`
34
+ * probe. Availability probes run in parallel.
74
35
  */
75
- export async function selectBestAdapter(focusAreas) {
76
- const available = await getAvailableAdapters();
77
- if (available.length === 0)
78
- return null;
79
- if (!focusAreas || focusAreas.length === 0) {
80
- return available[0]; // Return first available
81
- }
82
- // Score each adapter by how well it matches the focus areas
83
- const scored = available.map((adapter) => {
84
- const caps = adapter.getCapabilities();
85
- let score = 0;
86
- for (const focus of focusAreas) {
87
- if (caps.strengths.includes(focus))
88
- score += 2;
89
- else if (!caps.weaknesses.includes(focus))
90
- score += 1;
91
- else
92
- score -= 1;
93
- }
94
- return { adapter, score };
95
- });
96
- scored.sort((a, b) => b.score - a.score);
97
- return scored[0].adapter;
36
+ export async function getAvailableAdapters(options) {
37
+ const enabled = getAllAdapters().filter((adapter) => adapter.isEnabled());
38
+ const checks = await Promise.all(enabled.map(async (adapter) => ({ adapter, available: await adapter.isAvailable(options) })));
39
+ return checks.filter((c) => c.available).map((c) => c.adapter);
98
40
  }
@@ -1,25 +1,46 @@
1
1
  /**
2
- * Claude CLI Adapter
2
+ * Claude Code adapter.
3
3
  *
4
- * Implements the ReviewerAdapter interface for Anthropic's Claude CLI.
5
- * Spawns a FRESH Claude Code instance with zero session context.
6
- * Returns raw text — CC handles interpretation.
4
+ * Spawns a separate Claude Code instance so the reviewer shares none of CC's
5
+ * conversation. Model and effort come from config (`claude.model`, default
6
+ * `fable`; `claude.effort` / `claude.consultEffort`).
7
7
  *
8
- * Read-only enforcement (defense-in-depth):
9
- * 1. --permission-mode plan (CLI-level read-only)
10
- * 2. --disallowed-tools (write tools explicitly blocked)
11
- * 3. Handoff prompt (explicit READ-ONLY instruction)
8
+ * Read-only, single-purpose run (defense in depth):
9
+ * 1. --permission-mode default Read/Grep/Glob are auto-allowed; everything
10
+ * + --permission-prompts none else that would prompt is denied outright,
11
+ * so a headless run can never hang. Plan mode
12
+ * is deliberately NOT used: it injects Claude
13
+ * Code's planning workflow (write a plan file,
14
+ * spawn Explore agents, end with ExitPlanMode)
15
+ * which fights the review brief.
16
+ * 2. --disallowed-tools write tools and agent/plan tools removed
17
+ * 3. --allowed-tools only read-only git commands may run in Bash
18
+ * 4. --strict-mcp-config none of the user's MCP servers are started
19
+ * 5. --setting-sources '' no user/project/local settings, hooks or
20
+ * plugins from settings files
21
+ * 6. the prompt itself explicit READ-ONLY ground rules
22
+ *
23
+ * Not isolated (only `--bare` removes these, and `--bare` disables the
24
+ * keychain/OAuth read, so OAuth users could not run at all): the project's
25
+ * CLAUDE.md, Claude Code's auto-memory for the working directory, and one
26
+ * built-in SessionStart hook.
12
27
  */
13
- import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult, ConsultRequest, ConsultResult } from './base.js';
14
- export declare class ClaudeAdapter implements ReviewerAdapter {
28
+ import { ReviewerCapabilities } from './base.js';
29
+ import { CliAdapter, CliOutcome, RunContext, RunLimits } from './cli-adapter.js';
30
+ /** Write tools plus the agent/plan tools a review has no business calling. */
31
+ export declare const DISALLOWED_TOOLS = "Edit Write NotebookEdit Agent Task ExitPlanMode AskUserQuestion Workflow";
32
+ /** The only shell commands the reviewer may run: read-only git, as the prompt's ground rules promise. */
33
+ export declare const ALLOWED_TOOLS: string;
34
+ export declare class ClaudeAdapter extends CliAdapter {
15
35
  readonly id = "claude";
36
+ protected readonly binary = "claude";
37
+ protected readonly installHint = "Install Claude Code: https://docs.anthropic.com/en/docs/claude-code";
38
+ protected readonly authHint = "Run `claude auth login` (or `/login` inside claude) to authenticate";
39
+ protected extraAuthPatterns: string[];
16
40
  getCapabilities(): ReviewerCapabilities;
17
- isAvailable(): Promise<boolean>;
18
- runReview(request: ReviewRequest): Promise<ReviewResult>;
19
- private runCli;
20
- private handleException;
21
- private categorizeError;
22
- private getSuggestion;
23
- runConsult(request: ConsultRequest): Promise<ConsultResult>;
41
+ protected getLimits(): RunLimits;
42
+ /** Build the argv for a headless, read-only run. Exposed for tests. */
43
+ buildArgs(ctx: RunContext): string[];
44
+ protected runCli(prompt: string, workingDir: string, ctx: RunContext): Promise<CliOutcome>;
24
45
  }
25
46
  export declare const claudeAdapter: ClaudeAdapter;