opencara 0.14.0 → 0.15.0

package/dist/index.js

@@ -6,8 +6,8 @@ import { Command as Command2 } from "commander";
 // src/commands/agent.ts
 import { Command } from "commander";
 import crypto from "crypto";
-import * as fs4 from "fs";
-import * as path4 from "path";
+import * as fs5 from "fs";
+import * as path5 from "path";
 
 // ../shared/dist/types.js
 function isRepoAllowed(repoConfig, targetOwner, targetRepo, agentOwner) {
@@ -117,6 +117,10 @@ import { parse, stringify } from "yaml";
 var DEFAULT_PLATFORM_URL = "https://api.opencara.dev";
 var CONFIG_DIR = path.join(os.homedir(), ".opencara");
 var CONFIG_FILE = process.env.OPENCARA_CONFIG && process.env.OPENCARA_CONFIG.trim() ? path.resolve(process.env.OPENCARA_CONFIG) : path.join(CONFIG_DIR, "config.yml");
+function ensureConfigDir() {
+  const dir = path.dirname(CONFIG_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+}
 var DEFAULT_MAX_DIFF_SIZE_KB = 100;
 var DEFAULT_MAX_CONSECUTIVE_ERRORS = 10;
 var VALID_REPO_MODES = ["all", "own", "whitelist", "blacklist"];
@@ -256,8 +260,23 @@ function validateConfigData(data, envPlatformUrl) {
     );
     overrides.maxConsecutiveErrors = DEFAULT_MAX_CONSECUTIVE_ERRORS;
   }
+  for (const field of [
+    "max_reviews_per_day",
+    "max_tokens_per_day",
+    "max_tokens_per_review"
+  ]) {
+    if (field in data && typeof data[field] === "number" && data[field] <= 0) {
+      console.warn(
+        `\u26A0 Config warning: ${field} must be > 0, got ${data[field]}, ignoring (unlimited)`
+      );
+    }
+  }
   return overrides;
 }
+function parsePositiveInt(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  return null;
+}
 function loadConfig() {
   const envPlatformUrl = process.env.OPENCARA_PLATFORM_URL?.trim() || null;
   const defaults = {
@@ -269,7 +288,12 @@ function loadConfig() {
     githubUsername: null,
     codebaseDir: null,
     agentCommand: null,
-    agents: null
+    agents: null,
+    usageLimits: {
+      maxReviewsPerDay: null,
+      maxTokensPerDay: null,
+      maxTokensPerReview: null
+    }
   };
   if (!fs.existsSync(CONFIG_FILE)) {
     return defaults;
@@ -289,7 +313,12 @@ function loadConfig() {
     githubUsername: typeof data.github_username === "string" ? data.github_username : null,
     codebaseDir: typeof data.codebase_dir === "string" ? data.codebase_dir : null,
     agentCommand: typeof data.agent_command === "string" ? data.agent_command : null,
-    agents: parseAgents(data)
+    agents: parseAgents(data),
+    usageLimits: {
+      maxReviewsPerDay: parsePositiveInt(data.max_reviews_per_day),
+      maxTokensPerDay: parsePositiveInt(data.max_tokens_per_day),
+      maxTokensPerReview: parsePositiveInt(data.max_tokens_per_review)
+    }
   };
 }
 function resolveGithubToken(agentToken, globalToken) {
@@ -465,24 +494,24 @@ var ApiClient = class {
     }
     return h;
   }
-  async get(path5) {
-    this.log(`GET ${path5}`);
-    const res = await fetch(`${this.baseUrl}${path5}`, {
+  async get(path6) {
+    this.log(`GET ${path6}`);
+    const res = await fetch(`${this.baseUrl}${path6}`, {
       method: "GET",
       headers: this.headers()
     });
-    return this.handleResponse(res, path5);
+    return this.handleResponse(res, path6);
   }
-  async post(path5, body) {
-    this.log(`POST ${path5}`);
-    const res = await fetch(`${this.baseUrl}${path5}`, {
+  async post(path6, body) {
+    this.log(`POST ${path6}`);
+    const res = await fetch(`${this.baseUrl}${path6}`, {
       method: "POST",
       headers: this.headers(),
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
-    return this.handleResponse(res, path5);
+    return this.handleResponse(res, path6);
   }
-  async handleResponse(res, path5) {
+  async handleResponse(res, path6) {
     if (!res.ok) {
       let message = `HTTP ${res.status}`;
       let errorCode;
@@ -494,10 +523,10 @@ var ApiClient = class {
         }
       } catch {
       }
-      this.log(`${res.status} ${message} (${path5})`);
+      this.log(`${res.status} ${message} (${path6})`);
       throw new HttpError(res.status, message, errorCode);
     }
-    this.log(`${res.status} OK (${path5})`);
+    this.log(`${res.status} OK (${path6})`);
     return await res.json();
   }
 };
@@ -629,18 +658,35 @@ function parseClaudeTokens(text) {
   const inputMatch = text.match(/"input_tokens"\s*:\s*(\d+)/);
   const outputMatch = text.match(/"output_tokens"\s*:\s*(\d+)/);
   if (inputMatch && outputMatch) {
-    return parseInt(inputMatch[1], 10) + parseInt(outputMatch[1], 10);
+    return {
+      input: parseInt(inputMatch[1], 10),
+      output: parseInt(outputMatch[1], 10)
+    };
   }
   return null;
 }
 function parseTokenUsage(stdout, stderr) {
   const codexMatch = stdout.match(/tokens\s+used[\s:]*([0-9,]+)/i);
-  if (codexMatch) return { tokens: parseInt(codexMatch[1].replace(/,/g, ""), 10), parsed: true };
-  const claudeTotal = parseClaudeTokens(stdout) ?? parseClaudeTokens(stderr);
-  if (claudeTotal !== null) return { tokens: claudeTotal, parsed: true };
+  if (codexMatch) {
+    const total = parseInt(codexMatch[1].replace(/,/g, ""), 10);
+    return { tokens: total, parsed: true, input: 0, output: total };
+  }
+  const claudeResult = parseClaudeTokens(stdout) ?? parseClaudeTokens(stderr);
+  if (claudeResult !== null) {
+    return {
+      tokens: claudeResult.input + claudeResult.output,
+      parsed: true,
+      input: claudeResult.input,
+      output: claudeResult.output
+    };
+  }
   const qwenMatch = stdout.match(/"tokens"\s*:\s*\{[^}]*"total"\s*:\s*(\d+)/);
-  if (qwenMatch) return { tokens: parseInt(qwenMatch[1], 10), parsed: true };
-  return { tokens: estimateTokens(stdout), parsed: false };
+  if (qwenMatch) {
+    const total = parseInt(qwenMatch[1], 10);
+    return { tokens: total, parsed: true, input: 0, output: total };
+  }
+  const estimated = estimateTokens(stdout);
+  return { tokens: estimated, parsed: false, input: 0, output: estimated };
 }
 function executeTool(commandTemplate, prompt, timeoutMs, signal, vars, cwd) {
   const promptViaArg = commandTemplate.includes("${PROMPT}");
@@ -729,7 +775,18 @@ function executeTool(commandTemplate, prompt, timeoutMs, signal, vars, cwd) {
             console.warn(`Tool stderr: ${stderr.slice(0, MAX_STDERR_LENGTH)}`);
           }
           const usage2 = parseTokenUsage(stdout, stderr);
-          resolve2({ stdout, stderr, tokensUsed: usage2.tokens, tokensParsed: usage2.parsed });
+          resolve2({
+            stdout,
+            stderr,
+            tokensUsed: usage2.tokens,
+            tokensParsed: usage2.parsed,
+            tokenDetail: {
+              input: usage2.input,
+              output: usage2.output,
+              total: usage2.tokens,
+              parsed: usage2.parsed
+            }
+          });
           return;
         }
         const errMsg = stderr ? `Tool "${command}" failed (exit code ${code}): ${stderr.slice(0, MAX_STDERR_LENGTH)}` : `Tool "${command}" failed with exit code ${code}`;
@@ -737,7 +794,18 @@ function executeTool(commandTemplate, prompt, timeoutMs, signal, vars, cwd) {
         return;
       }
       const usage = parseTokenUsage(stdout, stderr);
-      resolve2({ stdout, stderr, tokensUsed: usage.tokens, tokensParsed: usage.parsed });
+      resolve2({
+        stdout,
+        stderr,
+        tokensUsed: usage.tokens,
+        tokensParsed: usage.parsed,
+        tokenDetail: {
+          input: usage.input,
+          output: usage.output,
+          total: usage.tokens,
+          parsed: usage.parsed
+        }
+      });
     });
   });
 }
@@ -861,11 +929,19 @@ ${userMessage}`;
     );
     const { verdict, review } = extractVerdict(result.stdout);
     const inputTokens = result.tokensParsed ? 0 : estimateTokens(fullPrompt);
+    const detail = result.tokenDetail;
+    const tokenDetail = result.tokensParsed ? detail : {
+      input: inputTokens,
+      output: detail.output,
+      total: inputTokens + detail.output,
+      parsed: false
+    };
     return {
       review,
       verdict,
       tokensUsed: result.tokensUsed + inputTokens,
-      tokensEstimated: !result.tokensParsed
+      tokensEstimated: !result.tokensParsed,
+      tokenDetail
     };
   } finally {
     clearTimeout(abortTimer);
@@ -985,10 +1061,18 @@ ${userMessage}`;
       deps.codebaseDir ?? void 0
     );
     const inputTokens = result.tokensParsed ? 0 : estimateTokens(fullPrompt);
+    const detail = result.tokenDetail;
+    const tokenDetail = result.tokensParsed ? detail : {
+      input: inputTokens,
+      output: detail.output,
+      total: inputTokens + detail.output,
+      parsed: false
+    };
     return {
       summary: result.stdout,
       tokensUsed: result.tokensUsed + inputTokens,
-      tokensEstimated: !result.tokensParsed
+      tokensEstimated: !result.tokensParsed,
+      tokenDetail
     };
   } finally {
     clearTimeout(abortTimer);
@@ -1153,16 +1237,190 @@ var RouterTimeoutError = class extends Error {
 
 // src/consumption.ts
 function createSessionTracker() {
-  return { tokens: 0, reviews: 0 };
+  return { tokens: 0, reviews: 0, tokenBreakdown: { input: 0, output: 0, estimated: 0 } };
 }
-function recordSessionUsage(session, tokensUsed) {
-  session.tokens += tokensUsed;
-  session.reviews += 1;
+function recordSessionUsage(session, tokensOrOptions) {
+  if (typeof tokensOrOptions === "number") {
+    session.tokens += tokensOrOptions;
+    session.reviews += 1;
+    session.tokenBreakdown.estimated += tokensOrOptions;
+  } else {
+    session.tokens += tokensOrOptions.totalTokens;
+    session.reviews += 1;
+    if (tokensOrOptions.estimated) {
+      session.tokenBreakdown.estimated += tokensOrOptions.totalTokens;
+    } else {
+      session.tokenBreakdown.input += tokensOrOptions.inputTokens;
+      session.tokenBreakdown.output += tokensOrOptions.outputTokens;
+    }
+  }
 }
 function formatPostReviewStats(session) {
-  return `  Session: ${session.tokens.toLocaleString()} tokens / ${session.reviews} reviews`;
+  const { input, output, estimated } = session.tokenBreakdown;
+  const hasBreakdown = input > 0 || output > 0;
+  let detail = "";
+  if (hasBreakdown) {
+    const parts = [];
+    if (input > 0) parts.push(`${input.toLocaleString()} in`);
+    if (output > 0) parts.push(`${output.toLocaleString()} out`);
+    if (estimated > 0) parts.push(`${estimated.toLocaleString()} est`);
+    detail = ` (${parts.join(" + ")})`;
+  }
+  return `  Session: ${session.tokens.toLocaleString()} tokens${detail} / ${session.reviews} reviews`;
 }
 
+// src/usage-tracker.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+var USAGE_FILE = path4.join(CONFIG_DIR, "usage.json");
+var MAX_HISTORY_DAYS = 30;
+var WARNING_THRESHOLD = 0.8;
+function todayKey() {
+  const now = /* @__PURE__ */ new Date();
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, "0");
+  const d = String(now.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+function totalTokens(t) {
+  return t.input + t.output + t.estimated;
+}
+var UsageTracker = class {
+  data;
+  filePath;
+  constructor(filePath = USAGE_FILE) {
+    this.filePath = filePath;
+    this.data = this.load();
+    this.pruneHistory();
+  }
+  load() {
+    try {
+      if (fs4.existsSync(this.filePath)) {
+        const raw = fs4.readFileSync(this.filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.days)) {
+          return parsed;
+        }
+      }
+    } catch {
+    }
+    return { days: [] };
+  }
+  save() {
+    ensureConfigDir();
+    fs4.writeFileSync(this.filePath, JSON.stringify(this.data, null, 2), {
+      encoding: "utf-8",
+      mode: 384
+    });
+  }
+  /** Get or create today's usage record. Prunes old history. */
+  getToday() {
+    const key = todayKey();
+    let today = this.data.days.find((d) => d.date === key);
+    if (!today) {
+      today = { date: key, reviews: 0, tokens: { input: 0, output: 0, estimated: 0 } };
+      this.data.days.push(today);
+      this.pruneHistory();
+    }
+    return today;
+  }
+  /** Record a completed review with its token usage. */
+  recordReview(tokens) {
+    const today = this.getToday();
+    today.reviews += 1;
+    if (tokens.estimated) {
+      today.tokens.estimated += tokens.input + tokens.output;
+    } else {
+      today.tokens.input += tokens.input;
+      today.tokens.output += tokens.output;
+    }
+    this.save();
+  }
+  /** Check whether a new review is allowed under the configured limits. */
+  checkLimits(limits) {
+    const today = this.getToday();
+    const todayTokenTotal = totalTokens(today.tokens);
+    if (limits.maxReviewsPerDay !== null && today.reviews >= limits.maxReviewsPerDay) {
+      return {
+        allowed: false,
+        reason: `Daily review limit reached (${today.reviews}/${limits.maxReviewsPerDay})`
+      };
+    }
+    if (limits.maxTokensPerDay !== null && todayTokenTotal >= limits.maxTokensPerDay) {
+      return {
+        allowed: false,
+        reason: `Daily token budget exhausted (${todayTokenTotal.toLocaleString()}/${limits.maxTokensPerDay.toLocaleString()})`
+      };
+    }
+    const warnings = [];
+    if (limits.maxReviewsPerDay !== null) {
+      const ratio = today.reviews / limits.maxReviewsPerDay;
+      if (ratio >= WARNING_THRESHOLD) {
+        warnings.push(
+          `Reviews: ${today.reviews}/${limits.maxReviewsPerDay} (${Math.round(ratio * 100)}%)`
+        );
+      }
+    }
+    if (limits.maxTokensPerDay !== null) {
+      const ratio = todayTokenTotal / limits.maxTokensPerDay;
+      if (ratio >= WARNING_THRESHOLD) {
+        warnings.push(
+          `Tokens: ${todayTokenTotal.toLocaleString()}/${limits.maxTokensPerDay.toLocaleString()} (${Math.round(ratio * 100)}%)`
+        );
+      }
+    }
+    return { allowed: true, warning: warnings.length > 0 ? warnings.join("; ") : void 0 };
+  }
+  /** Check whether a specific review's estimated token count exceeds the per-review limit. */
+  checkPerReviewLimit(estimatedTokens, limits) {
+    if (limits.maxTokensPerReview !== null && estimatedTokens > limits.maxTokensPerReview) {
+      return {
+        allowed: false,
+        reason: `Estimated tokens (${estimatedTokens.toLocaleString()}) exceed per-review limit (${limits.maxTokensPerReview.toLocaleString()})`
+      };
+    }
+    return { allowed: true };
+  }
+  /** Remove entries older than MAX_HISTORY_DAYS. */
+  pruneHistory() {
+    if (this.data.days.length <= MAX_HISTORY_DAYS) return;
+    this.data.days.sort((a, b) => b.date.localeCompare(a.date));
+    this.data.days = this.data.days.slice(0, MAX_HISTORY_DAYS);
+  }
+  /** Format a usage summary for display on shutdown. */
+  formatSummary(limits) {
+    const today = this.getToday();
+    const todayTokenTotal = totalTokens(today.tokens);
+    const lines = ["Usage Summary:"];
+    lines.push(`  Date: ${today.date}`);
+    lines.push(
+      `  Reviews: ${today.reviews}${limits.maxReviewsPerDay !== null ? `/${limits.maxReviewsPerDay}` : ""}`
+    );
+    const tokenParts = [];
+    if (today.tokens.input > 0) tokenParts.push(`${today.tokens.input.toLocaleString()} in`);
+    if (today.tokens.output > 0) tokenParts.push(`${today.tokens.output.toLocaleString()} out`);
+    if (today.tokens.estimated > 0)
+      tokenParts.push(`${today.tokens.estimated.toLocaleString()} est`);
+    const breakdown = tokenParts.length > 0 ? ` (${tokenParts.join(" + ")})` : "";
+    lines.push(
+      `  Tokens: ${todayTokenTotal.toLocaleString()}${limits.maxTokensPerDay !== null ? `/${limits.maxTokensPerDay.toLocaleString()}` : ""}${breakdown}`
+    );
+    if (limits.maxTokensPerDay !== null) {
+      const remaining = Math.max(0, limits.maxTokensPerDay - todayTokenTotal);
+      lines.push(`  Remaining token budget: ${remaining.toLocaleString()}`);
+    }
+    if (limits.maxReviewsPerDay !== null) {
+      const remaining = Math.max(0, limits.maxReviewsPerDay - today.reviews);
+      lines.push(`  Remaining reviews: ${remaining}`);
+    }
+    return lines.join("\n");
+  }
+  /** Get all stored usage data (for testing/inspection). */
+  getData() {
+    return this.data;
+  }
+};
+
 // src/pr-context.ts
 async function githubGet(url, deps) {
   const headers = {
@@ -1365,7 +1623,8 @@ function computeRoles(agent) {
   if (agent.synthesizer_only) return ["summary"];
   return ["review", "summary"];
 }
-async function fetchDiff(diffUrl, githubToken, signal) {
+async function fetchDiff(diffUrl, githubToken, signal, maxDiffSizeKb) {
+  const maxBytes = maxDiffSizeKb ? maxDiffSizeKb * 1024 : Infinity;
   return withRetry(
     async () => {
       const headers = {};
@@ -1390,13 +1649,56 @@ async function fetchDiff(diffUrl, githubToken, signal) {
         }
         throw new Error(msg);
       }
+      if (maxBytes < Infinity) {
+        const contentLength = parseInt(response.headers.get("content-length") ?? "", 10);
+        if (!isNaN(contentLength) && contentLength > maxBytes) {
+          if (response.body) {
+            void response.body.cancel();
+          }
+          throw new DiffTooLargeError(
+            `Diff too large (${Math.round(contentLength / 1024)}KB > ${maxDiffSizeKb}KB, from Content-Length)`
+          );
+        }
+        if (response.body) {
+          const reader = response.body.getReader();
+          const chunks = [];
+          let totalBytes = 0;
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            totalBytes += value.length;
+            if (totalBytes > maxBytes) {
+              void reader.cancel();
+              throw new DiffTooLargeError(`Diff too large (>${maxDiffSizeKb}KB)`);
+            }
+            chunks.push(value);
+          }
+          return new TextDecoder().decode(concatUint8Arrays(chunks, totalBytes));
+        }
+      }
       return response.text();
     },
     { maxAttempts: 2 },
     signal
   );
 }
+function concatUint8Arrays(chunks, totalLength) {
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
 var MAX_DIFF_FETCH_ATTEMPTS = 3;
+function appendContributorAttribution(text, githubUsername) {
+  if (!githubUsername) return text;
+  return `${text}
+
+---
+Contributed by [@${githubUsername}](https://github.com/${githubUsername})`;
+}
 async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo, logger, agentSession, options) {
   const {
     pollIntervalMs,
@@ -1415,6 +1717,16 @@ async function pollLoop(client, agentId, reviewDeps, consumptionDeps, agentInfo,
   let consecutiveErrors = 0;
   const diffFailCounts = /* @__PURE__ */ new Map();
   while (!signal?.aborted) {
+    if (consumptionDeps.usageTracker && consumptionDeps.usageLimits) {
+      const limitStatus = consumptionDeps.usageTracker.checkLimits(consumptionDeps.usageLimits);
+      if (!limitStatus.allowed) {
+        log(`${icons.stop} ${limitStatus.reason}. Stopping.`);
+        break;
+      }
+      if (limitStatus.warning) {
+        logWarn(`${icons.warn} Approaching limits: ${limitStatus.warning}`);
+      }
+    }
     try {
       const pollBody = { agent_id: agentId };
       if (githubUsername) pollBody.github_username = githubUsername;
@@ -1528,7 +1840,12 @@ async function handleTask(client, agentId, task, reviewDeps, consumptionDeps, ag
   }
   let diffContent;
   try {
-    diffContent = await fetchDiff(diff_url, reviewDeps.githubToken, signal);
+    diffContent = await fetchDiff(
+      diff_url,
+      reviewDeps.githubToken,
+      signal,
+      reviewDeps.maxDiffSizeKb
+    );
     log(`  Diff fetched (${Math.round(diffContent.length / 1024)}KB)`);
   } catch (err) {
     logError(`  Failed to fetch diff for task ${task_id}: ${err.message}`);
@@ -1567,8 +1884,8 @@ async function handleTask(client, agentId, task, reviewDeps, consumptionDeps, ag
       validatePathSegment(owner, "owner");
       validatePathSegment(repo, "repo");
       validatePathSegment(task_id, "task_id");
-      const repoScopedDir = path4.join(CONFIG_DIR, "repos", owner, repo, task_id);
-      fs4.mkdirSync(repoScopedDir, { recursive: true });
+      const repoScopedDir = path5.join(CONFIG_DIR, "repos", owner, repo, task_id);
+      fs5.mkdirSync(repoScopedDir, { recursive: true });
       taskCheckoutPath = repoScopedDir;
       taskReviewDeps = { ...reviewDeps, codebaseDir: repoScopedDir };
       log(`  Working directory: ${repoScopedDir}`);
@@ -1611,7 +1928,8 @@ async function handleTask(client, agentId, task, reviewDeps, consumptionDeps, ag
         logger,
         routerRelay,
         signal,
-        contextBlock
+        contextBlock,
+        githubUsername
       );
     } else {
       await executeReviewTask(
@@ -1629,7 +1947,8 @@ async function handleTask(client, agentId, task, reviewDeps, consumptionDeps, ag
         logger,
         routerRelay,
         signal,
-        contextBlock
+        contextBlock,
+        githubUsername
       );
     }
     agentSession.tasksCompleted++;
@@ -1679,10 +1998,21 @@ 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, contextBlock) {
+async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber, diffContent, prompt, timeoutSeconds, reviewDeps, consumptionDeps, logger, routerRelay, signal, contextBlock, githubUsername) {
+  if (consumptionDeps.usageLimits?.maxTokensPerReview != null && consumptionDeps.usageTracker) {
+    const estimatedInput = estimateTokens(diffContent + prompt + (contextBlock ?? ""));
+    const perReviewCheck = consumptionDeps.usageTracker.checkPerReviewLimit(
+      estimatedInput,
+      consumptionDeps.usageLimits
+    );
+    if (!perReviewCheck.allowed) {
+      throw new Error(perReviewCheck.reason);
+    }
+  }
   let reviewText;
   let verdict;
   let tokensUsed;
+  let usageOpts;
   if (routerRelay) {
     logger.log(`  ${icons.running} Executing review: [router mode]`);
     const fullPrompt = routerRelay.buildReviewPrompt({
@@ -1703,6 +2033,12 @@ async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber,
     reviewText = parsed.review;
     verdict = parsed.verdict;
     tokensUsed = estimateTokens(fullPrompt) + estimateTokens(response);
+    usageOpts = {
+      inputTokens: estimateTokens(fullPrompt),
+      outputTokens: estimateTokens(response),
+      totalTokens: tokensUsed,
+      estimated: true
+    };
   } else {
     logger.log(`  ${icons.running} Executing review: ${reviewDeps.commandTemplate}`);
     const result = await executeReview(
@@ -1722,8 +2058,14 @@ async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber,
     reviewText = result.review;
     verdict = result.verdict;
     tokensUsed = result.tokensUsed;
+    usageOpts = {
+      inputTokens: result.tokenDetail.input,
+      outputTokens: result.tokenDetail.output,
+      totalTokens: result.tokensUsed,
+      estimated: result.tokensEstimated
+    };
   }
-  const sanitizedReview = sanitizeTokens(reviewText);
+  const sanitizedReview = appendContributorAttribution(sanitizeTokens(reviewText), githubUsername);
   await withRetry(
     () => client.post(`/api/tasks/${taskId}/result`, {
       agent_id: agentId,
@@ -1735,15 +2077,23 @@ async function executeReviewTask(client, agentId, taskId, owner, repo, prNumber,
     { maxAttempts: 3 },
     signal
   );
-  recordSessionUsage(consumptionDeps.session, tokensUsed);
+  recordSessionUsage(consumptionDeps.session, usageOpts);
+  if (consumptionDeps.usageTracker) {
+    consumptionDeps.usageTracker.recordReview({
+      input: usageOpts.inputTokens,
+      output: usageOpts.outputTokens,
+      estimated: usageOpts.estimated
+    });
+  }
   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, contextBlock) {
+async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber, diffContent, prompt, timeoutSeconds, reviews, reviewDeps, consumptionDeps, logger, routerRelay, signal, contextBlock, githubUsername) {
   if (reviews.length === 0) {
     let reviewText;
     let verdict;
     let tokensUsed2;
+    let usageOpts2;
     if (routerRelay) {
       logger.log(`  ${icons.running} Executing summary: [router mode]`);
       const fullPrompt = routerRelay.buildReviewPrompt({
@@ -1764,6 +2114,12 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
       reviewText = parsed.review;
       verdict = parsed.verdict;
       tokensUsed2 = estimateTokens(fullPrompt) + estimateTokens(response);
+      usageOpts2 = {
+        inputTokens: estimateTokens(fullPrompt),
+        outputTokens: estimateTokens(response),
+        totalTokens: tokensUsed2,
+        estimated: true
+      };
     } else {
       logger.log(`  ${icons.running} Executing summary: ${reviewDeps.commandTemplate}`);
       const result = await executeReview(
@@ -1783,8 +2139,17 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
       reviewText = result.review;
       verdict = result.verdict;
       tokensUsed2 = result.tokensUsed;
+      usageOpts2 = {
+        inputTokens: result.tokenDetail.input,
+        outputTokens: result.tokenDetail.output,
+        totalTokens: result.tokensUsed,
+        estimated: result.tokensEstimated
+      };
     }
-    const sanitizedReview = sanitizeTokens(reviewText);
+    const sanitizedReview = appendContributorAttribution(
+      sanitizeTokens(reviewText),
+      githubUsername
+    );
     await withRetry(
       () => client.post(`/api/tasks/${taskId}/result`, {
         agent_id: agentId,
@@ -1796,7 +2161,14 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
       { maxAttempts: 3 },
       signal
     );
-    recordSessionUsage(consumptionDeps.session, tokensUsed2);
+    recordSessionUsage(consumptionDeps.session, usageOpts2);
+    if (consumptionDeps.usageTracker) {
+      consumptionDeps.usageTracker.recordReview({
+        input: usageOpts2.inputTokens,
+        output: usageOpts2.outputTokens,
+        estimated: usageOpts2.estimated
+      });
+    }
     logger.log(
       `  ${icons.success} Review submitted as summary (${tokensUsed2.toLocaleString()} tokens)`
     );
@@ -1812,6 +2184,7 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
   }));
   let summaryText;
   let tokensUsed;
+  let usageOpts;
   if (routerRelay) {
     logger.log(`  ${icons.running} Executing summary: [router mode]`);
     const fullPrompt = routerRelay.buildSummaryPrompt({
@@ -1830,6 +2203,12 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
     );
     summaryText = response;
     tokensUsed = estimateTokens(fullPrompt) + estimateTokens(response);
+    usageOpts = {
+      inputTokens: estimateTokens(fullPrompt),
+      outputTokens: estimateTokens(response),
+      totalTokens: tokensUsed,
+      estimated: true
+    };
   } else {
     logger.log(`  ${icons.running} Executing summary: ${reviewDeps.commandTemplate}`);
     const result = await executeSummary(
@@ -1848,8 +2227,17 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
     );
     summaryText = result.summary;
     tokensUsed = result.tokensUsed;
+    usageOpts = {
+      inputTokens: result.tokenDetail.input,
+      outputTokens: result.tokenDetail.output,
+      totalTokens: result.tokensUsed,
+      estimated: result.tokensEstimated
+    };
   }
-  const sanitizedSummary = sanitizeTokens(summaryText);
+  const sanitizedSummary = appendContributorAttribution(
+    sanitizeTokens(summaryText),
+    githubUsername
+  );
   await withRetry(
     () => client.post(`/api/tasks/${taskId}/result`, {
       agent_id: agentId,
@@ -1860,7 +2248,14 @@ async function executeSummaryTask(client, agentId, taskId, owner, repo, prNumber
     { maxAttempts: 3 },
     signal
   );
-  recordSessionUsage(consumptionDeps.session, tokensUsed);
+  recordSessionUsage(consumptionDeps.session, usageOpts);
+  if (consumptionDeps.usageTracker) {
+    consumptionDeps.usageTracker.recordReview({
+      input: usageOpts.inputTokens,
+      output: usageOpts.outputTokens,
+      estimated: usageOpts.estimated
+    });
+  }
   logger.log(`  ${icons.success} Summary submitted (${tokensUsed.toLocaleString()} tokens)`);
   logger.log(formatPostReviewStats(consumptionDeps.session));
 }
@@ -1884,7 +2279,17 @@ function sleep2(ms, signal) {
 async function startAgent(agentId, platformUrl, agentInfo, reviewDeps, consumptionDeps, options) {
   const client = new ApiClient(platformUrl, { apiKey: options?.apiKey });
   const session = consumptionDeps?.session ?? createSessionTracker();
-  const deps = consumptionDeps ?? { agentId, session };
+  const usageTracker = consumptionDeps?.usageTracker ?? new UsageTracker();
+  const usageLimits = options?.usageLimits ?? {
+    maxReviewsPerDay: null,
+    maxTokensPerDay: null,
+    maxTokensPerReview: null
+  };
+  const deps = consumptionDeps ? {
+    ...consumptionDeps,
+    usageTracker: consumptionDeps.usageTracker ?? usageTracker,
+    usageLimits: consumptionDeps.usageLimits ?? usageLimits
+  } : { agentId, session, usageTracker, usageLimits };
   const logger = createLogger(options?.label);
   const { log, logError, logWarn } = logger;
   const agentSession = createAgentSession();
@@ -1921,6 +2326,9 @@ async function startAgent(agentId, platformUrl, agentInfo, reviewDeps, consumpti
     githubUsername: options?.githubUsername,
     signal: abortController.signal
   });
+  if (deps.usageTracker) {
+    log(deps.usageTracker.formatSummary(deps.usageLimits ?? usageLimits));
+  }
   log(formatExitSummary(agentSession));
 }
 async function startAgentRouter() {
@@ -1952,6 +2360,7 @@ async function startAgentRouter() {
     codebaseDir
   };
   const session = createSessionTracker();
+  const usageTracker = new UsageTracker();
   const model = agentConfig?.model ?? "unknown";
   const tool = agentConfig?.tool ?? "unknown";
   const label = agentConfig?.name ?? "agent[0]";
@@ -1963,7 +2372,9 @@ async function startAgentRouter() {
     reviewDeps,
     {
       agentId,
-      session
+      session,
+      usageTracker,
+      usageLimits: config.usageLimits
     },
     {
       maxConsecutiveErrors: config.maxConsecutiveErrors,
@@ -1974,7 +2385,8 @@ async function startAgentRouter() {
       synthesizeRepos: agentConfig?.synthesize_repos,
       githubUsername,
       label,
-      apiKey: config.apiKey
+      apiKey: config.apiKey,
+      usageLimits: config.usageLimits
     }
   );
   router.stop();
@@ -2021,6 +2433,7 @@ function startAgentByIndex(config, agentIndex, pollIntervalMs, auth, githubUsern
     routerRelay.start();
   }
   const session = createSessionTracker();
+  const usageTracker = new UsageTracker();
   const model = agentConfig?.model ?? "unknown";
   const tool = agentConfig?.tool ?? "unknown";
   const roles = agentConfig ? computeRoles(agentConfig) : void 0;
@@ -2029,7 +2442,7 @@ function startAgentByIndex(config, agentIndex, pollIntervalMs, auth, githubUsern
     config.platformUrl,
     { model, tool },
     reviewDeps,
-    { agentId, session },
+    { agentId, session, usageTracker, usageLimits: config.usageLimits },
     {
       pollIntervalMs,
       maxConsecutiveErrors: config.maxConsecutiveErrors,
@@ -2040,7 +2453,8 @@ function startAgentByIndex(config, agentIndex, pollIntervalMs, auth, githubUsern
       synthesizeRepos: agentConfig?.synthesize_repos,
       githubUsername,
       label,
-      apiKey: config.apiKey
+      apiKey: config.apiKey,
+      usageLimits: config.usageLimits
     }
   ).finally(() => {
     routerRelay?.stop();
@@ -2115,7 +2529,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.14.0");
+var program = new Command2().name("opencara").description("OpenCara \u2014 distributed AI code review agent").version("0.15.0");
 program.addCommand(agentCommand);
 program.action(() => {
   startAgentRouter();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencara",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Distributed AI code review agent — poll, review, and submit PR reviews using your own AI tools",
   "type": "module",
   "license": "MIT",