@contextrail/code-review-agent 0.1.2-alpha.3 → 0.1.2-alpha.6

package/README.md

@@ -34,14 +34,17 @@ npm i -g @contextrail/code-review-agent
 code-review-agent review --help
 ```
 
-## Required Environment Variables
+## Configuration
+
+### Required (sensitive — use environment variables)
 
 ```bash
-export CONTEXTRAIL_MCP_SERVER_URL="https://<your-mcp-host>"
 export CONTEXTRAIL_MCP_JWT_TOKEN="<your-contextrail-jwt-token>"
 export OPENROUTER_API_KEY="<your-openrouter-key>"
 ```
 
+These contain credentials and should not be passed as CLI flags to avoid exposure in shell history and process listings.
+
 ### Getting Your ContextRail MCP Token
 
 To get your `CONTEXTRAIL_MCP_JWT_TOKEN`:
@@ -51,14 +54,22 @@ To get your `CONTEXTRAIL_MCP_JWT_TOKEN`:
 
 The token is used to authenticate with the ContextRail MCP server to retrieve your organization's review standards and contexts.
 
-Optional:
+### Required (env var or CLI flag)
+
+```bash
+export CONTEXTRAIL_MCP_SERVER_URL="https://<your-mcp-host>"
+# or pass inline:
+# --mcp-server-url https://<your-mcp-host>
+```
+
+### Optional
 
 ```bash
-export LLM_MODEL_ORCHESTRATOR="google/gemini-3-flash-preview"
-export LLM_MODEL_REVIEWER="qwen/qwen3-coder-next"
-export LLM_MODEL_CRITIC="qwen/qwen3-coder-next"
-export REVIEW_DOMAINS="security,architecture"
-export PR_DESCRIPTION="Optional PR context"
+export LLM_MODEL_ORCHESTRATOR="google/gemini-3-flash-preview"  # or --orchestrator-model
+export LLM_MODEL_REVIEWER="qwen/qwen3-coder-next"              # or --reviewer-model
+export LLM_MODEL_CRITIC="qwen/qwen3-coder-next"                # or --critic-model
+export REVIEW_DOMAINS="security,architecture"                   # or --domains
+export PR_DESCRIPTION="Optional PR context"                     # or --pr-description
 ```
 
 ## Run Against a PR Diff
@@ -153,7 +164,8 @@ Exit codes:
 - **`Command "code-review-agent" not found`**
     - use `npx -y @contextrail/code-review-agent ...` or install globally
 - **Missing required env vars**
-    - set `CONTEXTRAIL_MCP_SERVER_URL`, `CONTEXTRAIL_MCP_JWT_TOKEN`, and `OPENROUTER_API_KEY`
+    - set `CONTEXTRAIL_MCP_JWT_TOKEN` and `OPENROUTER_API_KEY` as environment variables
+    - set `CONTEXTRAIL_MCP_SERVER_URL` as an environment variable or pass `--mcp-server-url`
 - **One reviewer failed with structured-output/schema errors**
     - inspect `./.review/reviewers/<reviewer>/failures.md`
     - inspect `./.review/reviewers/<reviewer>/progress.json`

package/dist/cli/help.js

@@ -10,34 +10,41 @@ Commands:
   review    Run code review on git diff
 
 Options:
-  --repo <path>              Repository path (default: current directory)
-  --from <sha>               Base commit SHA (required)
-  --to <sha>                  Head commit SHA (required)
-  --files <list>              Comma-separated list of files to review
-  --file <path>               File to review (repeatable)
-  --output <dir>              Output directory (default: ./review)
-  --log-level <lv>            Log level: debug|info|warn|error|silent (overrides DEBUG)
-  --max-steps <n>             Maximum LLM steps per call (default: 10)
-  --max-iterations <n>        Maximum reviewer validation iterations (default: 2)
-  --aggregation-max-steps <n> Maximum steps for aggregation (default: 5)
-  --max-tokens-per-file <n>   Token budget for surrounding context per file (default: 20000)
-  --context-lines <n>         Lines of context around changes (default: 10)
-  --pr-description <text>     PR description to include as context (optional)
-  --domains <list>            Comma-separated review focus domains (optional)
-  -h, --help                  Show this help message
+  --repo <path>                Repository path (default: current directory)
+  --from <sha>                 Base commit SHA (required)
+  --to <sha>                   Head commit SHA (required)
+  --files <list>               Comma-separated list of files to review
+  --file <path>                File to review (repeatable)
+  --output <dir>               Output directory (default: ./review)
+  --mcp-server-url <url>       ContextRail MCP server URL (overrides CONTEXTRAIL_MCP_SERVER_URL)
+  --orchestrator-model <model> Model for orchestrator (overrides LLM_MODEL_ORCHESTRATOR)
+  --reviewer-model <model>     Model for reviewers (overrides LLM_MODEL_REVIEWER)
+  --critic-model <model>       Model for critic pass (overrides LLM_MODEL_CRITIC)
+  --log-level <lv>             Log level: debug|info|warn|error|silent (overrides DEBUG)
+  --max-steps <n>              Maximum LLM steps per call (default: 10)
+  --max-iterations <n>         Maximum reviewer validation iterations (default: 2)
+  --aggregation-max-steps <n>  Maximum steps for aggregation (default: 5)
+  --max-tokens-per-file <n>    Token budget for surrounding context per file (default: 20000)
+  --context-lines <n>          Lines of context around changes (default: 10)
+  --pr-description <text>      PR description to include as context (optional)
+  --domains <list>             Comma-separated review focus domains (optional)
+  -h, --help                   Show this help message
 
-Environment Variables:
-  CONTEXTRAIL_MCP_SERVER_URL  ContextRail MCP server URL (required)
+Environment Variables (sensitive — use env vars, not CLI flags):
   CONTEXTRAIL_MCP_JWT_TOKEN   ContextRail MCP authentication token (required)
-  OPENROUTER_API_KEY      OpenRouter API key (required)
-  LLM_MODEL_ORCHESTRATOR  Model for orchestrator (default: anthropic/claude-haiku-4.5)
-  LLM_MODEL_REVIEWER      Model for reviewers (default: anthropic/claude-haiku-4.5)
-  MAX_STEPS               Maximum LLM steps per call (default: 10)
-  MAX_ITERATIONS          Maximum reviewer validation iterations (default: 2)
-  AGGREGATION_MAX_STEPS   Maximum steps for aggregation (default: 5)
-  MAX_TOKENS_PER_FILE     Token budget for surrounding context per file (default: 20000)
-  CONTEXT_LINES           Lines of context around changes (default: 10)
-  REVIEW_DOMAINS          Comma-separated review focus domains (optional)
+  OPENROUTER_API_KEY          OpenRouter API key (required)
+
+Environment Variables (can also be set via CLI flags above):
+  CONTEXTRAIL_MCP_SERVER_URL  ContextRail MCP server URL (required)
+  LLM_MODEL_ORCHESTRATOR      Model for orchestrator
+  LLM_MODEL_REVIEWER          Model for reviewers
+  LLM_MODEL_CRITIC            Model for critic pass
+  MAX_STEPS                   Maximum LLM steps per call (default: 10)
+  MAX_ITERATIONS              Maximum reviewer validation iterations (default: 2)
+  AGGREGATION_MAX_STEPS       Maximum steps for aggregation (default: 5)
+  MAX_TOKENS_PER_FILE         Token budget for surrounding context per file (default: 20000)
+  CONTEXT_LINES               Lines of context around changes (default: 10)
+  REVIEW_DOMAINS              Comma-separated review focus domains (optional)
 
 Examples:
   code-review-agent review --repo . --from HEAD^ --to HEAD

package/dist/cli/parser.js

@@ -56,6 +56,22 @@ export const parseArgs = (args) => {
             parsed.logLevel = args[i + 1];
             i += 2;
         }
+        else if (arg === '--mcp-server-url' && i + 1 < args.length) {
+            parsed.mcpServerUrl = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--orchestrator-model' && i + 1 < args.length) {
+            parsed.orchestratorModel = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--reviewer-model' && i + 1 < args.length) {
+            parsed.reviewerModel = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--critic-model' && i + 1 < args.length) {
+            parsed.criticModel = args[i + 1];
+            i += 2;
+        }
         else if (arg === '--pr-description' && i + 1 < args.length) {
             parsed.prDescription = args[i + 1];
             i += 2;

package/dist/cli/types.d.ts

@@ -7,6 +7,10 @@ export interface CliArgs {
     logLevel?: string;
     files?: string[];
     help?: boolean;
+    mcpServerUrl?: string;
+    orchestratorModel?: string;
+    reviewerModel?: string;
+    criticModel?: string;
     maxSteps?: number;
     maxIterations?: number;
     aggregationMaxSteps?: number;

package/dist/config/defaults.d.ts

@@ -51,7 +51,7 @@ export declare const getDefaultCriticModel: (reviewerModel: string | undefined)
  */
 export declare const DEFAULT_SURROUNDING_CONTEXT_CONFIG: {
     readonly enabled: true;
-    readonly maxTokensPerFile: 20000;
+    readonly maxTokensPerFile: 10000;
     readonly contextLines: 10;
 };
 /**

package/dist/config/defaults.js

@@ -65,7 +65,7 @@ export const getDefaultCriticModel = (reviewerModel) => {
  */
 export const DEFAULT_SURROUNDING_CONTEXT_CONFIG = {
     enabled: true,
-    maxTokensPerFile: 20_000,
+    maxTokensPerFile: 10_000,
     contextLines: 10,
 };
 /**

package/dist/config/index.js

@@ -55,15 +55,17 @@ export const loadConfig = () => {
         prDescription: normalizeOptionalString(process.env.PR_DESCRIPTION),
         reviewDomains,
     };
-    // Fail fast when required environment variables are missing.
-    // Note: CLI --help bypasses loadConfig in src/index.ts so help remains accessible.
-    const missingRequired = getMissingRequiredEnvVars(config);
-    if (missingRequired.length > 0) {
-        throw new Error(`Missing required environment variables: ${missingRequired.join(', ')}`);
-    }
     return config;
 };
 export const applyCliArgs = (config, args) => {
+    if (args.mcpServerUrl !== undefined)
+        config.mcpServerUrl = args.mcpServerUrl;
+    if (args.orchestratorModel !== undefined)
+        config.orchestratorModel = args.orchestratorModel;
+    if (args.reviewerModel !== undefined)
+        config.reviewerModel = args.reviewerModel;
+    if (args.criticModel !== undefined)
+        config.criticModel = args.criticModel;
     if (args.maxSteps !== undefined)
         config.maxSteps = args.maxSteps;
     if (args.maxIterations !== undefined)

package/dist/reviewers/executor.js

@@ -218,6 +218,7 @@ export const runReviewerLoop = async (reviewer, inputs, understanding, outputDir
             const chunkToolCalls = [];
             const chunkContextIds = [];
             const chunkUsages = [];
+            let iterationChunkError = null;
             for (let chunkIdx = 0; chunkIdx < chunks.length; chunkIdx++) {
                 const chunk = chunks[chunkIdx];
                 if (!chunk) {
@@ -246,10 +247,26 @@ export const runReviewerLoop = async (reviewer, inputs, understanding, outputDir
                         ? error.message
                         : `[REVIEWER] Failed to run reviewer iteration for chunk ${chunkIdx + 1}`;
                     const details = buildFailureDetails(error, `Chunk ${chunkIdx + 1} of ${chunks.length} failed`);
-                    await recordFailureAndBlock(errorMsg, details);
-                    throw error;
+                    iterationChunkError = { msg: errorMsg, details, err: error };
+                    break;
                 }
             }
+            if (iterationChunkError !== null) {
+                if (iteration < maxIterations) {
+                    await appendFailure(reviewersDir, reviewer, {
+                        gate: 'validation',
+                        message: iterationChunkError.msg,
+                        details: iterationChunkError.details,
+                    });
+                    logger?.debug(`[${reviewer}] Chunk error at iteration ${iteration}; retrying (${iteration + 1}/${maxIterations})`);
+                    await logContinuation(reviewersDir, reviewer, iteration + 1);
+                    continue;
+                }
+                await recordFailureAndBlock(iterationChunkError.msg, iterationChunkError.details);
+                throw iterationChunkError.err instanceof Error
+                    ? iterationChunkError.err
+                    : new Error(iterationChunkError.msg);
+            }
             // Merge findings from all chunks
             const mergedFindings = mergeChunkFindings(chunkFindings);
             findings = mergedFindings;
@@ -287,6 +304,12 @@ export const runReviewerLoop = async (reviewer, inputs, understanding, outputDir
             catch (error) {
                 const errorMsg = error instanceof Error ? error.message : '[REVIEWER] Failed to run reviewer iteration';
                 const details = buildFailureDetails(error, 'generateText returned no object output');
+                if (iteration < maxIterations) {
+                    await appendFailure(reviewersDir, reviewer, { gate: 'validation', message: errorMsg, details });
+                    logger?.debug(`[${reviewer}] Iteration ${iteration} threw an error; retrying (${iteration + 1}/${maxIterations})`);
+                    await logContinuation(reviewersDir, reviewer, iteration + 1);
+                    continue;
+                }
                 await recordFailureAndBlock(errorMsg, details);
                 throw error;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@contextrail/code-review-agent",
-    "version": "0.1.2-alpha.3",
+    "version": "0.1.2-alpha.6",
     "description": "CLI tool for orchestrating ContextRail-powered code reviews",
     "homepage": "https://contextrail.app",
     "repository": {