opencara 0.11.0 → 0.12.0

package/README.md

@@ -0,0 +1,126 @@
+# opencara
+
+Distributed AI code review agent for GitHub pull requests. Run review agents locally using your own AI tools and API keys — OpenCara never touches your credentials.
+
+## How It Works
+
+```
+GitHub PR → OpenCara server creates review task
+  → Your agent polls for tasks → Claims one → Fetches diff from GitHub
+  → Reviews locally with your AI tool → Submits result
+  → Server posts the review to the PR
+```
+
+## Quick Start
+
+```bash
+# 1. Install
+npm i -g opencara
+
+# 2. Create config
+mkdir -p ~/.opencara
+cat > ~/.opencara/config.yml << 'EOF'
+platform_url: https://opencara-server.opencara.workers.dev
+agents:
+  - model: claude-sonnet-4-6
+    tool: claude
+    command: claude --model claude-sonnet-4-6 --allowedTools '*' --print
+EOF
+
+# 3. Start
+opencara agent start
+```
+
+Your agent is now polling for review tasks every 10 seconds.
+
+## Supported AI Tools
+
+| Tool       | Install                              | Example models                     |
+| ---------- | ------------------------------------ | ---------------------------------- |
+| Claude     | `npm i -g @anthropic-ai/claude-code` | claude-sonnet-4-6, claude-opus-4-6 |
+| Codex      | `npm i -g @openai/codex`             | gpt-5.4-codex                      |
+| Gemini CLI | `npm i -g @google/gemini-cli`        | gemini-2.5-pro, gemini-2.5-flash   |
+| Qwen CLI   | `npm i -g qwen`                      | qwen3.5-plus, glm-5, kimi-k2.5     |
+
+Each tool requires its own API key configured per its documentation.
+
+## Configuration
+
+Edit `~/.opencara/config.yml`:
+
+```yaml
+platform_url: https://opencara-server.opencara.workers.dev
+
+agents:
+  - model: claude-sonnet-4-6
+    tool: claude
+    command: claude --model claude-sonnet-4-6 --allowedTools '*' --print
+
+  - model: gemini-2.5-pro
+    tool: gemini
+    command: gemini -m gemini-2.5-pro
+```
+
+Review prompts are delivered via **stdin** to your command. The command reads stdin, processes it with the AI model, and writes the review to stdout.
+
+### Agent Config Fields
+
+| Field          | Required | Default | Description                                            |
+| -------------- | -------- | ------- | ------------------------------------------------------ |
+| `model`        | Yes      | --      | AI model identifier (e.g., `claude-sonnet-4-6`)        |
+| `tool`         | Yes      | --      | AI tool identifier (e.g., `claude`, `codex`, `gemini`) |
+| `command`      | Yes\*    | --      | Shell command to execute reviews (stdin -> stdout)     |
+| `name`         | No       | --      | Display name in CLI logs (local only)                  |
+| `review_only`  | No       | `false` | If `true`, agent only reviews, never synthesizes       |
+| `github_token` | No       | --      | Per-agent GitHub token for private repos               |
+| `codebase_dir` | No       | --      | Local clone directory for context-aware reviews        |
+| `repos`        | No       | --      | Repo filtering (mode: all/own/whitelist/blacklist)     |
+
+\*Required unless `agent_command` is set globally.
+
+### Global Config Fields
+
+| Field                    | Default                    | Description                           |
+| ------------------------ | -------------------------- | ------------------------------------- |
+| `platform_url`           | `https://api.opencara.dev` | OpenCara server URL                   |
+| `github_token`           | --                         | GitHub token for private repo diffs   |
+| `codebase_dir`           | --                         | Default clone directory for repos     |
+| `max_diff_size_kb`       | `100`                      | Skip PRs with diffs larger than this  |
+| `max_consecutive_errors` | `10`                       | Stop agent after N consecutive errors |
+
+## CLI Reference
+
+### Commands
+
+| Command                | Description                                     |
+| ---------------------- | ----------------------------------------------- |
+| `opencara`             | Start agent in router mode (stdin/stdout relay) |
+| `opencara agent start` | Start an agent in polling mode                  |
+
+### `opencara agent start` Options
+
+| Option                      | Default | Description                              |
+| --------------------------- | ------- | ---------------------------------------- |
+| `--agent <index>`           | `0`     | Agent index from config.yml (0-based)    |
+| `--all`                     | --      | Start all configured agents concurrently |
+| `--poll-interval <seconds>` | `10`    | Poll interval in seconds                 |
+
+## Environment Variables
+
+| Variable                | Description                                                        |
+| ----------------------- | ------------------------------------------------------------------ |
+| `OPENCARA_CONFIG`       | Path to alternate config file (overrides `~/.opencara/config.yml`) |
+| `OPENCARA_PLATFORM_URL` | Override the platform URL from config                              |
+| `GITHUB_TOKEN`          | GitHub token (fallback for private repo access)                    |
+
+## Private Repos
+
+The CLI resolves GitHub tokens using a fallback chain:
+
+1. `GITHUB_TOKEN` environment variable
+2. `gh auth token` (if GitHub CLI is installed)
+3. `github_token` in config.yml (global or per-agent)
+
+## License
+
+MIT

package/dist/index.js

@@ -28,6 +28,84 @@ function isRepoAllowed(repoConfig, targetOwner, targetRepo, agentOwner) {
   }
 }
 
+// ../shared/dist/api.js
+var DEFAULT_REGISTRY = {
+  tools: [
+    {
+      name: "claude",
+      displayName: "Claude",
+      binary: "claude",
+      commandTemplate: "claude --model ${MODEL} --allowedTools '*' --print",
+      tokenParser: "claude"
+    },
+    {
+      name: "codex",
+      displayName: "Codex",
+      binary: "codex",
+      commandTemplate: "codex --model ${MODEL} exec",
+      tokenParser: "codex"
+    },
+    {
+      name: "gemini",
+      displayName: "Gemini",
+      binary: "gemini",
+      commandTemplate: "gemini -m ${MODEL}",
+      tokenParser: "gemini"
+    },
+    {
+      name: "qwen",
+      displayName: "Qwen",
+      binary: "qwen",
+      commandTemplate: "qwen --model ${MODEL} -y",
+      tokenParser: "qwen"
+    }
+  ],
+  models: [
+    {
+      name: "claude-opus-4-6",
+      displayName: "Claude Opus 4.6",
+      tools: ["claude"]
+    },
+    {
+      name: "claude-opus-4-6[1m]",
+      displayName: "Claude Opus 4.6 (1M context)",
+      tools: ["claude"]
+    },
+    {
+      name: "claude-sonnet-4-6",
+      displayName: "Claude Sonnet 4.6",
+      tools: ["claude"]
+    },
+    {
+      name: "claude-sonnet-4-6[1m]",
+      displayName: "Claude Sonnet 4.6 (1M context)",
+      tools: ["claude"]
+    },
+    {
+      name: "gpt-5-codex",
+      displayName: "GPT-5 Codex",
+      tools: ["codex"]
+    },
+    {
+      name: "gemini-2.5-pro",
+      displayName: "Gemini 2.5 Pro",
+      tools: ["gemini"]
+    },
+    {
+      name: "qwen3.5-plus",
+      displayName: "Qwen 3.5 Plus",
+      tools: ["qwen"]
+    },
+    { name: "glm-5", displayName: "GLM-5", tools: ["qwen"] },
+    { name: "kimi-k2.5", displayName: "Kimi K2.5", tools: ["qwen"] },
+    {
+      name: "minimax-m2.5",
+      displayName: "Minimax M2.5",
+      tools: ["qwen"]
+    }
+  ]
+};
+
 // ../shared/dist/review-config.js
 import { parse as parseYaml } from "yaml";
 
@@ -49,6 +127,16 @@ var RepoConfigError = class extends Error {
     this.name = "RepoConfigError";
   }
 };
+var ConfigValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigValidationError";
+  }
+};
+var KNOWN_TOOL_NAMES = new Set(DEFAULT_REGISTRY.tools.map((t) => t.name));
+var TOOL_ALIASES = {
+  "claude-code": "claude"
+};
 function parseRepoConfig(obj, index) {
   const raw = obj.repos;
   if (raw === void 0 || raw === null) return void 0;
@@ -92,15 +180,33 @@ function parseAgents(data) {
   for (let i = 0; i < raw.length; i++) {
     const entry = raw[i];
     if (!entry || typeof entry !== "object") {
-      console.warn(`Warning: agents[${i}] is not an object, skipping`);
+      console.warn(`\u26A0 Config warning: agents[${i}] is not an object, skipping agent`);
       continue;
     }
     const obj = entry;
     if (typeof obj.model !== "string" || typeof obj.tool !== "string") {
-      console.warn(`Warning: agents[${i}] missing required model/tool fields, skipping`);
+      console.warn(
+        `\u26A0 Config warning: agents[${i}] missing required model/tool fields, skipping agent`
+      );
       continue;
     }
-    const agent = { model: obj.model, tool: obj.tool };
+    let resolvedTool = obj.tool;
+    if (!KNOWN_TOOL_NAMES.has(resolvedTool)) {
+      const alias = TOOL_ALIASES[resolvedTool];
+      if (alias) {
+        console.warn(
+          `\u26A0 Config warning: agents[${i}].tool "${resolvedTool}" is deprecated, using "${alias}" instead`
+        );
+        resolvedTool = alias;
+      } else {
+        const toolNames = [...KNOWN_TOOL_NAMES].join(", ");
+        console.warn(
+          `\u26A0 Config warning: agents[${i}].tool "${resolvedTool}" not in registry (known: ${toolNames}), skipping agent`
+        );
+        continue;
+      }
+    }
+    const agent = { model: obj.model, tool: resolvedTool };
     if (typeof obj.name === "string") agent.name = obj.name;
     if (typeof obj.command === "string") agent.command = obj.command;
     if (obj.router === true) agent.router = true;
@@ -113,6 +219,35 @@ function parseAgents(data) {
   }
   return agents;
 }
+function isValidHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function validateConfigData(data, envPlatformUrl) {
+  const overrides = {};
+  if (!envPlatformUrl && typeof data.platform_url === "string" && !isValidHttpUrl(data.platform_url)) {
+    throw new ConfigValidationError(
+      `\u2717 Config error: platform_url "${data.platform_url}" is not a valid URL`
+    );
+  }
+  if (typeof data.max_diff_size_kb === "number" && data.max_diff_size_kb <= 0) {
+    console.warn(
+      `\u26A0 Config warning: max_diff_size_kb must be > 0, got ${data.max_diff_size_kb}, using default (${DEFAULT_MAX_DIFF_SIZE_KB})`
+    );
+    overrides.maxDiffSizeKb = DEFAULT_MAX_DIFF_SIZE_KB;
+  }
+  if (typeof data.max_consecutive_errors === "number" && data.max_consecutive_errors <= 0) {
+    console.warn(
+      `\u26A0 Config warning: max_consecutive_errors must be > 0, got ${data.max_consecutive_errors}, using default (${DEFAULT_MAX_CONSECUTIVE_ERRORS})`
+    );
+    overrides.maxConsecutiveErrors = DEFAULT_MAX_CONSECUTIVE_ERRORS;
+  }
+  return overrides;
+}
 function loadConfig() {
   const envPlatformUrl = process.env.OPENCARA_PLATFORM_URL?.trim() || null;
   const defaults = {
@@ -132,10 +267,11 @@ function loadConfig() {
   if (!data || typeof data !== "object") {
     return defaults;
   }
+  const overrides = validateConfigData(data, envPlatformUrl);
   return {
     platformUrl: envPlatformUrl || (typeof data.platform_url === "string" ? data.platform_url : DEFAULT_PLATFORM_URL),
-    maxDiffSizeKb: typeof data.max_diff_size_kb === "number" ? data.max_diff_size_kb : DEFAULT_MAX_DIFF_SIZE_KB,
-    maxConsecutiveErrors: typeof data.max_consecutive_errors === "number" ? data.max_consecutive_errors : DEFAULT_MAX_CONSECUTIVE_ERRORS,
+    maxDiffSizeKb: overrides.maxDiffSizeKb ?? (typeof data.max_diff_size_kb === "number" ? data.max_diff_size_kb : DEFAULT_MAX_DIFF_SIZE_KB),
+    maxConsecutiveErrors: overrides.maxConsecutiveErrors ?? (typeof data.max_consecutive_errors === "number" ? data.max_consecutive_errors : DEFAULT_MAX_CONSECUTIVE_ERRORS),
     githubToken: typeof data.github_token === "string" ? data.github_token : null,
     codebaseDir: typeof data.codebase_dir === "string" ? data.codebase_dir : null,
     agentCommand: typeof data.agent_command === "string" ? data.agent_command : null,
@@ -267,9 +403,10 @@ function logAuthMethod(method, log) {
 
 // src/http.ts
 var HttpError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, errorCode) {
     super(message);
     this.status = status;
+    this.errorCode = errorCode;
     this.name = "HttpError";
   }
 };
@@ -307,13 +444,17 @@ var ApiClient = class {
   async handleResponse(res, path5) {
     if (!res.ok) {
       let message = `HTTP ${res.status}`;
+      let errorCode;
       try {
         const body = await res.json();
-        if (body.error) message = body.error;
+        if (body.error && typeof body.error === "object" && "code" in body.error) {
+          errorCode = body.error.code;
+          message = body.error.message;
+        }
       } catch {
       }
       this.log(`${res.status} ${message} (${path5})`);
-      throw new HttpError(res.status, message);
+      throw new HttpError(res.status, message, errorCode);
     }
     this.log(`${res.status} OK (${path5})`);
     return await res.json();
@@ -611,12 +752,13 @@ function buildSystemPrompt(owner, repo, mode = "full") {
   const template = mode === "compact" ? COMPACT_SYSTEM_PROMPT_TEMPLATE : FULL_SYSTEM_PROMPT_TEMPLATE;
   return template.replace("{owner}", owner).replace("{repo}", repo);
 }
-function buildUserMessage(prompt, diffContent) {
-  return `${prompt}
-
----
-
-${diffContent}`;
+function buildUserMessage(prompt, diffContent, contextBlock) {
+  const parts = [prompt];
+  if (contextBlock) {
+    parts.push(contextBlock);
+  }
+  parts.push(diffContent);
+  return parts.join("\n\n---\n\n");
 }
 var SECTION_VERDICT_PATTERN = /##\s*Verdict\s*\n+\s*(APPROVE|REQUEST_CHANGES|COMMENT)\b/im;
 var LEGACY_VERDICT_PATTERN = /^VERDICT:\s*(APPROVE|REQUEST_CHANGES|COMMENT)\s*$/m;
@@ -656,7 +798,7 @@ async function executeReview(req, deps, runTool = executeTool) {
   }, effectiveTimeout);
   try {
     const systemPrompt = buildSystemPrompt(req.owner, req.repo, req.reviewMode);
-    const userMessage = buildUserMessage(req.prompt, req.diffContent);
+    const userMessage = buildUserMessage(req.prompt, req.diffContent, req.contextBlock);
     const fullPrompt = `${systemPrompt}
 
 ${userMessage}`;
@@ -728,27 +870,28 @@ For each finding, explain clearly what the problem is and how to fix it.
 ## Verdict
 APPROVE | REQUEST_CHANGES | COMMENT`;
 }
-function buildSummaryUserMessage(prompt, reviews, diffContent) {
+function buildSummaryUserMessage(prompt, reviews, diffContent, contextBlock) {
   const reviewSections = reviews.map((r) => `### Review by ${r.model}/${r.tool} (Verdict: ${r.verdict})
 ${r.review}`).join("\n\n");
-  return `Project review guidelines:
-${prompt}
-
----
-
-Pull request diff:
-
-${diffContent}
-
----
+  const parts = [`Project review guidelines:
+${prompt}`];
+  if (contextBlock) {
+    parts.push(contextBlock);
+  }
+  parts.push(`Pull request diff:
 
-Compact reviews from other agents:
+${diffContent}`);
+  parts.push(`Compact reviews from other agents:
 
-${reviewSections}`;
+${reviewSections}`);
+  return parts.join("\n\n---\n\n");
 }
-function calculateInputSize(prompt, reviews, diffContent) {
+function calculateInputSize(prompt, reviews, diffContent, contextBlock) {
   let size = Buffer.byteLength(prompt, "utf-8");
   size += Buffer.byteLength(diffContent, "utf-8");
+  if (contextBlock) {
+    size += Buffer.byteLength(contextBlock, "utf-8");
+  }
   for (const r of reviews) {
     size += Buffer.byteLength(r.review, "utf-8");
     size += Buffer.byteLength(r.model, "utf-8");
@@ -758,7 +901,7 @@ function calculateInputSize(prompt, reviews, diffContent) {
   return size;
 }
 async function executeSummary(req, deps, runTool = executeTool) {
-  const inputSize = calculateInputSize(req.prompt, req.reviews, req.diffContent);
+  const inputSize = calculateInputSize(req.prompt, req.reviews, req.diffContent, req.contextBlock);
   if (inputSize > MAX_INPUT_SIZE_BYTES) {
     throw new InputTooLargeError(
       `Summary input too large (${Math.round(inputSize / 1024)}KB > ${Math.round(MAX_INPUT_SIZE_BYTES / 1024)}KB limit)`
@@ -775,7 +918,12 @@ async function executeSummary(req, deps, runTool = executeTool) {
   }, effectiveTimeout);
   try {
     const systemPrompt = buildSummarySystemPrompt(req.owner, req.repo, req.reviews.length);
-    const userMessage = buildSummaryUserMessage(req.prompt, req.reviews, req.diffContent);
+    const userMessage = buildSummaryUserMessage(
+      req.prompt,
+      req.reviews,
+      req.diffContent,
+      req.contextBlock
+    );
     const fullPrompt = `${systemPrompt}
 
 ${userMessage}`;
@@ -874,7 +1022,7 @@ var RouterRelay = class {
       req.repo,
       req.reviewMode
     );
-    const userMessage = buildUserMessage(req.prompt, req.diffContent);
+    const userMessage = buildUserMessage(req.prompt, req.diffContent, req.contextBlock);
     return `${systemPrompt}
 
 ${userMessage}`;
@@ -882,7 +1030,12 @@ ${userMessage}`;
   /** Build the full prompt for a summary request */
   buildSummaryPrompt(req) {
     const systemPrompt = buildSummarySystemPrompt(req.owner, req.repo, req.reviews.length);
-    const userMessage = buildSummaryUserMessage(req.prompt, req.reviews, req.diffContent);
+    const userMessage = buildSummaryUserMessage(
+      req.prompt,
+      req.reviews,
+      req.diffContent,
+      req.contextBlock
+    );
     return `${systemPrompt}
 
 ${userMessage}`;
@@ -961,18 +1114,196 @@ function formatPostReviewStats(session) {
   return `  Session: ${session.tokens.toLocaleString()} tokens / ${session.reviews} reviews`;
 }
 
-// src/commands/agent.ts
-var DEFAULT_POLL_INTERVAL_MS = 1e4;
-var MAX_CONSECUTIVE_AUTH_ERRORS = 3;
-var MAX_POLL_BACKOFF_MS = 3e5;
+// src/pr-context.ts
+async function githubGet(url, deps) {
+  const headers = {
+    Accept: "application/vnd.github+json"
+  };
+  if (deps.githubToken) {
+    headers["Authorization"] = `Bearer ${deps.githubToken}`;
+  }
+  const response = await fetch(url, { headers, signal: deps.signal });
+  if (!response.ok) {
+    throw new Error(`GitHub API ${response.status}: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function fetchPRMetadata(owner, repo, prNumber, deps) {
+  try {
+    const pr = await githubGet(
+      `https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}`,
+      deps
+    );
+    return {
+      title: pr.title,
+      body: pr.body ?? "",
+      author: pr.user?.login ?? "unknown",
+      labels: pr.labels.map((l) => l.name),
+      baseBranch: pr.base.ref,
+      headBranch: pr.head.ref
+    };
+  } catch {
+    return null;
+  }
+}
+async function fetchIssueComments(owner, repo, prNumber, deps) {
+  try {
+    const comments = await githubGet(
+      `https://api.github.com/repos/${owner}/${repo}/issues/${prNumber}/comments`,
+      deps
+    );
+    return comments.map((c) => ({
+      author: c.user?.login ?? "unknown",
+      body: c.body,
+      createdAt: c.created_at
+    }));
+  } catch {
+    return [];
+  }
+}
+async function fetchReviewComments(owner, repo, prNumber, deps) {
+  try {
+    const comments = await githubGet(
+      `https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}/comments`,
+      deps
+    );
+    return comments.map((c) => ({
+      author: c.user?.login ?? "unknown",
+      body: c.body,
+      path: c.path,
+      line: c.line,
+      createdAt: c.created_at
+    }));
+  } catch {
+    return [];
+  }
+}
+async function fetchExistingReviews(owner, repo, prNumber, deps) {
+  try {
+    const reviews = await githubGet(
+      `https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}/reviews`,
+      deps
+    );
+    return reviews.filter((r) => r.state !== "PENDING").map((r) => ({
+      author: r.user?.login ?? "unknown",
+      state: r.state,
+      body: r.body ?? ""
+    }));
+  } catch {
+    return [];
+  }
+}
+async function fetchPRContext(owner, repo, prNumber, deps) {
+  const [metadata, comments, reviewThreads, existingReviews] = await Promise.all([
+    fetchPRMetadata(owner, repo, prNumber, deps),
+    fetchIssueComments(owner, repo, prNumber, deps),
+    fetchReviewComments(owner, repo, prNumber, deps),
+    fetchExistingReviews(owner, repo, prNumber, deps)
+  ]);
+  return { metadata, comments, reviewThreads, existingReviews };
+}
+function formatPRContext(context, codebaseDir) {
+  const sections = [];
+  if (context.metadata) {
+    const m = context.metadata;
+    const lines = ["## PR Context", `**Title**: ${m.title}`, `**Author**: @${m.author}`];
+    if (m.body) {
+      lines.push(`**Description**: ${m.body}`);
+    }
+    if (m.labels.length > 0) {
+      lines.push(`**Labels**: ${m.labels.join(", ")}`);
+    }
+    lines.push(`**Branches**: ${m.headBranch} \u2192 ${m.baseBranch}`);
+    sections.push(lines.join("\n"));
+  }
+  if (context.comments.length > 0) {
+    const commentLines = context.comments.map((c) => `@${c.author}: ${c.body}`);
+    sections.push(
+      `## Discussion (${context.comments.length} comment${context.comments.length === 1 ? "" : "s"})
+${commentLines.join("\n")}`
+    );
+  }
+  if (context.reviewThreads.length > 0) {
+    const threadLines = context.reviewThreads.map((t) => {
+      const location = t.line ? `\`${t.path}:${t.line}\`` : `\`${t.path}\``;
+      return `@${t.author} on ${location}: ${t.body}`;
+    });
+    sections.push(`## Review Threads (${context.reviewThreads.length})
+${threadLines.join("\n")}`);
+  }
+  if (context.existingReviews.length > 0) {
+    const reviewLines = context.existingReviews.map((r) => {
+      const body = r.body ? ` ${r.body}` : "";
+      return `@${r.author}: [${r.state}]${body}`;
+    });
+    sections.push(
+      `## Existing Reviews (${context.existingReviews.length})
+${reviewLines.join("\n")}`
+    );
+  }
+  if (codebaseDir) {
+    sections.push(`## Local Codebase
+The full repository is available at: ${codebaseDir}`);
+  }
+  return sanitizeTokens(sections.join("\n\n"));
+}
+function hasContent(context) {
+  return context.metadata !== null || context.comments.length > 0 || context.reviewThreads.length > 0 || context.existingReviews.length > 0;
+}
+
+// src/logger.ts
+import pc from "picocolors";
+var icons = {
+  start: pc.green("\u25CF"),
+  polling: pc.cyan("\u21BB"),
+  success: pc.green("\u2713"),
+  running: pc.blue("\u25B6"),
+  stop: pc.red("\u25A0"),
+  warn: pc.yellow("\u26A0"),
+  error: pc.red("\u2717")
+};
+function timestamp() {
+  const now = /* @__PURE__ */ new Date();
+  const h = String(now.getHours()).padStart(2, "0");
+  const m = String(now.getMinutes()).padStart(2, "0");
+  const s = String(now.getSeconds()).padStart(2, "0");
+  return `${h}:${m}:${s}`;
+}
 function createLogger(label) {
-  const prefix = label ? `[${label}] ` : "";
+  const labelStr = label ? ` ${pc.dim(`[${label}]`)}` : "";
   return {
-    log: (msg) => console.log(`${prefix}${sanitizeTokens(msg)}`),
-    logError: (msg) => console.error(`${prefix}${sanitizeTokens(msg)}`),
-    logWarn: (msg) => console.warn(`${prefix}${sanitizeTokens(msg)}`)
+    log: (msg) => console.log(`${pc.dim(`[${timestamp()}]`)}${labelStr} ${sanitizeTokens(msg)}`),
+    logError: (msg) => console.error(`${pc.dim(`[${timestamp()}]`)}${labelStr} ${pc.red(sanitizeTokens(msg))}`),
+    logWarn: (msg) => console.warn(`${pc.dim(`[${timestamp()}]`)}${labelStr} ${pc.yellow(sanitizeTokens(msg))}`)
   };
 }
+function createAgentSession() {
+  return {
+    startTime: Date.now(),
+    tasksCompleted: 0,
+    errorsEncountered: 0
+  };
+}
+function formatUptime(ms) {
+  const totalSeconds = Math.floor(ms / 1e3);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor(totalSeconds % 3600 / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) return `${hours}h${minutes}m${seconds}s`;
+  if (minutes > 0) return `${minutes}m${seconds}s`;
+  return `${seconds}s`;
+}
+function formatExitSummary(stats) {
+  const uptime = formatUptime(Date.now() - stats.startTime);
+  const tasks = stats.tasksCompleted === 1 ? "1 task" : `${stats.tasksCompleted} tasks`;
+  const errors = stats.errorsEncountered === 1 ? "1 error" : `${stats.errorsEncountered} errors`;
+  return `${icons.stop} Shutting down \u2014 ${tasks} completed, ${errors}, uptime ${uptime}`;
+}
+
+// src/commands/agent.ts
+var DEFAULT_POLL_INTERVAL_MS = 1e4;
+var MAX_CONSECUTIVE_AUTH_ERRORS = 3;
+var MAX_POLL_BACKOFF_MS = 3e5;
 var NON_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([401, 403, 404]);
 function toApiDiffUrl(webUrl) {
   const match = webUrl.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:\.diff)?$/);
@@ -1012,10 +1343,10 @@ async function fetchDiff(diffUrl, githubToken, signal) {
   );
 }
 var MAX_DIFF_FETCH_ATTEMPTS = 3;
-async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo, logger, options) {
+async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo, logger, agentSession, options) {
   const { pollIntervalMs, maxConsecutiveErrors, routerRelay, reviewOnly, repoConfig, signal } = options;
   const { log, logError, logWarn } = logger;
-  log(`Agent ${agentId} polling every ${pollIntervalMs / 1e3}s...`);
+  log(`${icons.polling} Polling every ${pollIntervalMs / 1e3}s...`);
   let consecutiveAuthErrors = 0;
   let consecutiveErrors = 0;
   const diffFailCounts = /* @__PURE__ */ new Map();
@@ -1023,6 +1354,9 @@ async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo,
     try {
       const pollBody = { agent_id: agentId };
       if (reviewOnly) pollBody.review_only = true;
+      if (repoConfig?.mode === "whitelist" && repoConfig.list?.length) {
+        pollBody.repos = repoConfig.list;
+      }
       const pollResponse = await client.post("/api/tasks/poll", pollBody);
       consecutiveAuthErrors = 0;
       consecutiveErrors = 0;
@@ -1039,10 +1373,12 @@ async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo,
           consumptionDeps,
           agentInfo,
           logger,
+          agentSession,
           routerRelay,
           signal
         );
         if (result.diffFetchFailed) {
+          agentSession.errorsEncountered++;
           const count = (diffFailCounts.get(task.task_id) ?? 0) + 1;
           diffFailCounts.set(task.task_id, count);
           if (count >= MAX_DIFF_FETCH_ATTEMPTS) {
@@ -1052,20 +1388,21 @@ async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo,
       }
     } catch (err) {
       if (signal?.aborted) break;
+      agentSession.errorsEncountered++;
       if (err instanceof HttpError && (err.status === 401 || err.status === 403)) {
         consecutiveAuthErrors++;
         consecutiveErrors++;
         logError(
-          `Auth error (${err.status}): ${err.message} [${consecutiveAuthErrors}/${MAX_CONSECUTIVE_AUTH_ERRORS}]`
+          `${icons.error} Auth error (${err.status}): ${err.message} [${consecutiveAuthErrors}/${MAX_CONSECUTIVE_AUTH_ERRORS}]`
         );
         if (consecutiveAuthErrors >= MAX_CONSECUTIVE_AUTH_ERRORS) {
-          logError("Authentication failed repeatedly. Exiting.");
+          logError(`${icons.error} Authentication failed repeatedly. Exiting.`);
           break;
         }
       } else {
         consecutiveAuthErrors = 0;
         consecutiveErrors++;
-        logError(`Poll error: ${err.message}`);
+        logError(`${icons.error} Poll error: ${err.message}`);
       }
       if (consecutiveErrors >= maxConsecutiveErrors) {
         logError(
@@ -1091,11 +1428,10 @@ async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo,
     await sleep2(pollIntervalMs, signal);
   }
 }
-async function handleTask(client, agentId, task, reviewDeps, consumptionDeps, agentInfo, logger, routerRelay, signal) {
+async function handleTask(client, agentId, task, reviewDeps, consumptionDeps, agentInfo, logger, agentSession, routerRelay, signal) {
   const { task_id, owner, repo, pr_number, diff_url, timeout_seconds, prompt, role } = task;
   const { log, logError, logWarn } = logger;
-  log(`
-Task ${task_id}: PR #${pr_number} on ${owner}/${repo} (role: ${role})`);
+  log(`${icons.success} Claimed task ${task_id} (${role}) \u2014 ${owner}/${repo}#${pr_number}`);
   log(`  https://github.com/${owner}/${repo}/pull/${pr_number}`);
   let claimResponse;
   try {
@@ -1110,15 +1446,14 @@ Task ${task_id}: PR #${pr_number} on ${owner}/${repo} (role: ${role})`);
       signal
     );
   } catch (err) {
-    const status = err instanceof HttpError ? ` (${err.status})` : "";
-    logError(`  Failed to claim task ${task_id}${status}: ${err.message}`);
-    return {};
-  }
-  if (!claimResponse.claimed) {
-    log(`  Claim rejected: ${claimResponse.reason}`);
+    if (err instanceof HttpError) {
+      const codeInfo = err.errorCode ? ` [${err.errorCode}]` : "";
+      logError(`  Claim rejected${codeInfo}: ${err.message}`);
+    } else {
+      logError(`  Failed to claim task ${task_id}: ${err.message}`);
+    }
     return {};
   }
-  log(`  Claimed as ${role}`);
   let diffContent;
   try {
     diffContent = await fetchDiff(diff_url, reviewDeps.githubToken, signal);
@@ -1171,6 +1506,21 @@ Task ${task_id}: PR #${pr_number} on ${owner}/${repo} (role: ${role})`);
       );
     }
   }
+  let contextBlock;
+  try {
+    const prContext = await fetchPRContext(owner, repo, pr_number, {
+      githubToken: reviewDeps.githubToken,
+      signal
+    });
+    if (hasContent(prContext)) {
+      contextBlock = formatPRContext(prContext, taskReviewDeps.codebaseDir);
+      log("  PR context fetched");
+    }
+  } catch (err) {
+    logWarn(
+      `  Warning: failed to fetch PR context: ${err.message}. Continuing without.`
+    );
+  }
   try {
     if (role === "summary" && "reviews" in claimResponse && claimResponse.reviews) {
       await executeSummaryTask(
@@ -1188,7 +1538,8 @@ Task ${task_id}: PR #${pr_number} on ${owner}/${repo} (role: ${role})`);
         consumptionDeps,
         logger,
         routerRelay,
-        signal
+        signal,
+        contextBlock
       );
     } else {
       await executeReviewTask(
@@ -1205,15 +1556,18 @@ Task ${task_id}: PR #${pr_number} on ${owner}/${repo} (role: ${role})`);
         consumptionDeps,
         logger,
         routerRelay,
-        signal
+        signal,
+        contextBlock
       );
     }
+    agentSession.tasksCompleted++;
   } catch (err) {
+    agentSession.errorsEncountered++;
     if (err instanceof DiffTooLargeError || err instanceof InputTooLargeError) {
-      logError(`  ${err.message}`);
+      logError(`  ${icons.error} ${err.message}`);
       await safeReject(client, task_id, agentId, err.message, logger);
     } else {
-      logError(`  Error on task ${task_id}: ${err.message}`);
+      logError(`  ${icons.error} Error on task ${task_id}: ${err.message}`);
       await safeError(client, task_id, agentId, err.message, logger);
     }
   } finally {
@@ -1253,18 +1607,19 @@ async function safeError(client, taskId, agentId, error, logger) {
     );
   }
 }
-async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber, diffContent, prompt, timeoutSeconds, reviewDeps, consumptionDeps, logger, routerRelay, signal) {
+async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber, diffContent, prompt, timeoutSeconds, reviewDeps, consumptionDeps, logger, routerRelay, signal, contextBlock) {
   let reviewText;
   let verdict;
   let tokensUsed;
   if (routerRelay) {
-    logger.log(`  Executing review command: [router mode]`);
+    logger.log(`  ${icons.running} Executing review: [router mode]`);
     const fullPrompt = routerRelay.buildReviewPrompt({
       owner,
       repo,
       reviewMode: "full",
       prompt,
-      diffContent
+      diffContent,
+      contextBlock
     });
     const response = await routerRelay.sendPrompt(
       "review_request",
@@ -1277,7 +1632,7 @@ async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber,
     verdict = parsed.verdict;
     tokensUsed = estimateTokens(fullPrompt) + estimateTokens(response);
   } else {
-    logger.log(`  Executing review command: ${reviewDeps.commandTemplate}`);
+    logger.log(`  ${icons.running} Executing review: ${reviewDeps.commandTemplate}`);
     const result = await executeReview(
       {
         taskId,
@@ -1287,7 +1642,8 @@ async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber,
         repo,
         prNumber,
         timeout: timeoutSeconds,
-        reviewMode: "full"
+        reviewMode: "full",
+        contextBlock
       },
       reviewDeps
     );
@@ -1308,22 +1664,23 @@ async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber,
     signal
   );
   recordSessionUsage(consumptionDeps.session, tokensUsed);
-  logger.log(`  Review submitted (${tokensUsed.toLocaleString()} tokens)`);
+  logger.log(`  ${icons.success} Review submitted (${tokensUsed.toLocaleString()} tokens)`);
   logger.log(formatPostReviewStats(consumptionDeps.session));
 }
-async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber, diffContent, prompt, timeoutSeconds, reviews, reviewDeps, consumptionDeps, logger, routerRelay, signal) {
+async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber, diffContent, prompt, timeoutSeconds, reviews, reviewDeps, consumptionDeps, logger, routerRelay, signal, contextBlock) {
   if (reviews.length === 0) {
     let reviewText;
     let verdict;
     let tokensUsed2;
     if (routerRelay) {
-      logger.log(`  Executing summary command: [router mode]`);
+      logger.log(`  ${icons.running} Executing summary: [router mode]`);
       const fullPrompt = routerRelay.buildReviewPrompt({
         owner,
         repo,
         reviewMode: "full",
         prompt,
-        diffContent
+        diffContent,
+        contextBlock
       });
       const response = await routerRelay.sendPrompt(
         "review_request",
@@ -1336,7 +1693,7 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
       verdict = parsed.verdict;
       tokensUsed2 = estimateTokens(fullPrompt) + estimateTokens(response);
     } else {
-      logger.log(`  Executing summary command: ${reviewDeps.commandTemplate}`);
+      logger.log(`  ${icons.running} Executing summary: ${reviewDeps.commandTemplate}`);
       const result = await executeReview(
         {
           taskId,
@@ -1346,7 +1703,8 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
           repo,
           prNumber,
           timeout: timeoutSeconds,
-          reviewMode: "full"
+          reviewMode: "full",
+          contextBlock
         },
         reviewDeps
       );
@@ -1367,7 +1725,9 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
       signal
     );
     recordSessionUsage(consumptionDeps.session, tokensUsed2);
-    logger.log(`  Review submitted as summary (${tokensUsed2.toLocaleString()} tokens)`);
+    logger.log(
+      `  ${icons.success} Review submitted as summary (${tokensUsed2.toLocaleString()} tokens)`
+    );
     logger.log(formatPostReviewStats(consumptionDeps.session));
     return;
   }
@@ -1381,13 +1741,14 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
   let summaryText;
   let tokensUsed;
   if (routerRelay) {
-    logger.log(`  Executing summary command: [router mode]`);
+    logger.log(`  ${icons.running} Executing summary: [router mode]`);
     const fullPrompt = routerRelay.buildSummaryPrompt({
       owner,
       repo,
       prompt,
       reviews: summaryReviews,
-      diffContent
+      diffContent,
+      contextBlock
     });
     const response = await routerRelay.sendPrompt(
       "summary_request",
@@ -1398,7 +1759,7 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
     summaryText = response;
     tokensUsed = estimateTokens(fullPrompt) + estimateTokens(response);
   } else {
-    logger.log(`  Executing summary command: ${reviewDeps.commandTemplate}`);
+    logger.log(`  ${icons.running} Executing summary: ${reviewDeps.commandTemplate}`);
     const result = await executeSummary(
       {
         taskId,
@@ -1408,7 +1769,8 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
         repo,
         prNumber,
         timeout: timeoutSeconds,
-        diffContent
+        diffContent,
+        contextBlock
       },
       reviewDeps
     );
@@ -1427,7 +1789,7 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
     signal
   );
   recordSessionUsage(consumptionDeps.session, tokensUsed);
-  logger.log(`  Summary submitted (${tokensUsed.toLocaleString()} tokens)`);
+  logger.log(`  ${icons.success} Summary submitted (${tokensUsed.toLocaleString()} tokens)`);
   logger.log(formatPostReviewStats(consumptionDeps.session));
 }
 function sleep2(ms, signal) {
@@ -1453,31 +1815,30 @@ async function startAgent(agentId, platformUrl, agentInfo, reviewDeps, consumpti
   const deps = consumptionDeps ?? { agentId, session };
   const logger = createLogger(options?.label);
   const { log, logError, logWarn } = logger;
-  log(`Agent ${agentId} starting...`);
-  log(`Platform: ${platformUrl}`);
+  const agentSession = createAgentSession();
+  log(`${icons.start} Agent started (polling ${platformUrl})`);
   log(`Model: ${agentInfo.model} | Tool: ${agentInfo.tool}`);
   if (!reviewDeps) {
-    logError("No review command configured. Set command in config.yml");
+    logError(`${icons.error} No review command configured. Set command in config.yml`);
     return;
   }
   if (reviewDeps.commandTemplate && !options?.routerRelay) {
     log("Testing command...");
     const result = await testCommand(reviewDeps.commandTemplate);
     if (result.ok) {
-      log(`Testing command... ok (${(result.elapsedMs / 1e3).toFixed(1)}s)`);
+      log(`${icons.success} Command test ok (${(result.elapsedMs / 1e3).toFixed(1)}s)`);
     } else {
-      logWarn(`Warning: command test failed (${result.error}). Reviews may fail.`);
+      logWarn(`${icons.warn} Command test failed (${result.error}). Reviews may fail.`);
     }
   }
   const abortController = new AbortController();
   process.on("SIGINT", () => {
-    log("\nShutting down...");
     abortController.abort();
   });
   process.on("SIGTERM", () => {
     abortController.abort();
   });
-  await pollLoop(client, agentId, reviewDeps, deps, agentInfo, logger, {
+  await pollLoop(client, agentId, reviewDeps, deps, agentInfo, logger, agentSession, {
     pollIntervalMs: options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
     maxConsecutiveErrors: options?.maxConsecutiveErrors ?? DEFAULT_MAX_CONSECUTIVE_ERRORS,
     routerRelay: options?.routerRelay,
@@ -1485,7 +1846,7 @@ async function startAgent(agentId, platformUrl, agentInfo, reviewDeps, consumpti
     repoConfig: options?.repoConfig,
     signal: abortController.signal
   });
-  log("Agent stopped.");
+  log(formatExitSummary(agentSession));
 }
 async function startAgentRouter() {
   const config = loadConfig();
@@ -1661,7 +2022,7 @@ agentCommand.command("start").description("Start agents in polling mode").option
 });
 
 // src/index.ts
-var program = new Command2().name("opencara").description("OpenCara \u2014 distributed AI code review agent").version("0.11.0");
+var program = new Command2().name("opencara").description("OpenCara \u2014 distributed AI code review agent").version("0.12.0");
 program.addCommand(agentCommand);
 program.action(() => {
   startAgentRouter();

package/package.json

@@ -1,17 +1,40 @@
 {
   "name": "opencara",
-  "version": "0.11.0",
+  "version": "0.12.0",
+  "description": "Distributed AI code review agent — poll, review, and submit PR reviews using your own AI tools",
   "type": "module",
+  "license": "MIT",
+  "author": "OpenCara <https://github.com/OpenCara>",
+  "homepage": "https://github.com/OpenCara/OpenCara#readme",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenCara/OpenCara.git",
     "directory": "packages/cli"
   },
+  "bugs": {
+    "url": "https://github.com/OpenCara/OpenCara/issues"
+  },
+  "keywords": [
+    "ai",
+    "code-review",
+    "github",
+    "pull-request",
+    "cli",
+    "agent",
+    "review",
+    "openai",
+    "claude",
+    "gemini"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "opencara": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -20,14 +43,15 @@
   },
   "dependencies": {
     "commander": "^13.0.0",
+    "picocolors": "^1.1.1",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@opencara/shared": "workspace:*",
-    "@opencara/server": "workspace:*",
     "@cloudflare/workers-types": "^4.20250214.0",
-    "hono": "^4.7.0",
+    "@opencara/server": "workspace:*",
+    "@opencara/shared": "workspace:*",
     "@types/node": "^22.0.0",
+    "hono": "^4.7.0",
     "tsup": "^8.5.1",
     "tsx": "^4.0.0"
   }