@kevinrabun/judges 3.115.4 → 3.117.0

package/dist/a2a-protocol.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Agent-to-Agent (A2A) Protocol Support
+ *
+ * Implements the agent card and task exchange protocol enabling Judges
+ * to participate in multi-agent orchestration ecosystems. Compatible
+ * with Google's A2A protocol and similar agent discovery patterns.
+ *
+ * Capabilities:
+ * - Agent Card: advertises Judges' capabilities to orchestrators
+ * - Task Reception: accepts code review requests from other agents
+ * - Task Delegation: forwards specialized work to sub-agents
+ * - Result Reporting: returns structured findings to callers
+ *
+ * Wire format: JSON-RPC 2.0 over HTTP or stdio (MCP-compatible)
+ */
+import type { Finding, ReviewDecision } from "./types.js";
+export interface AgentCard {
+    /** Agent identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Version string */
+    version: string;
+    /** Description of agent capabilities */
+    description: string;
+    /** Supported input capabilities */
+    capabilities: AgentCapability[];
+    /** Supported output formats */
+    outputFormats: string[];
+    /** Communication protocols supported */
+    protocols: string[];
+    /** Authentication methods accepted */
+    authMethods: string[];
+    /** Agent metadata */
+    metadata: Record<string, unknown>;
+}
+export interface AgentCapability {
+    /** Capability name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Input schema (JSON Schema subset) */
+    inputSchema?: Record<string, unknown>;
+    /** Output schema */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Generate the Judges agent card for discovery by orchestrators.
+ */
+export declare function getAgentCard(options?: {
+    version?: string;
+    baseUrl?: string;
+}): AgentCard;
+export type TaskStatus = "pending" | "in-progress" | "completed" | "failed" | "cancelled";
+export interface A2ATask {
+    /** Unique task identifier */
+    taskId: string;
+    /** The capability being invoked */
+    capability: string;
+    /** Task status */
+    status: TaskStatus;
+    /** Input parameters */
+    input: Record<string, unknown>;
+    /** Output result (when completed) */
+    output?: A2ATaskResult;
+    /** Error details (when failed) */
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** Requesting agent ID */
+    requesterId: string;
+    /** Created timestamp */
+    createdAt: string;
+    /** Completed timestamp */
+    completedAt?: string;
+}
+export interface A2ATaskResult {
+    /** The findings from evaluation */
+    findings: Finding[];
+    /** Overall verdict */
+    verdict?: string;
+    /** Overall score (0-100) */
+    score?: number;
+    /** Review decision */
+    reviewDecision?: ReviewDecision;
+    /** Summary markdown */
+    summary?: string;
+    /** SARIF output (if requested) */
+    sarif?: unknown;
+}
+/**
+ * Create a new A2A task from an incoming request.
+ */
+export declare function createTask(capability: string, input: Record<string, unknown>, requesterId: string): A2ATask;
+/**
+ * Get a task by ID.
+ */
+export declare function getTask(taskId: string): A2ATask | undefined;
+/**
+ * Update task status and optionally set the result.
+ */
+export declare function completeTask(taskId: string, result: A2ATaskResult): A2ATask | undefined;
+/**
+ * Mark a task as failed.
+ */
+export declare function failTask(taskId: string, code: string, message: string): A2ATask | undefined;
+/**
+ * List all tasks, optionally filtered by status.
+ */
+export declare function listTasks(status?: TaskStatus): A2ATask[];
+/**
+ * Clean up completed/failed tasks older than the given age.
+ */
+export declare function pruneTasks(maxAgeMs?: number): number;
+export interface A2ARequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number;
+}
+export interface A2AResponse {
+    jsonrpc: "2.0";
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id?: string | number;
+}
+/**
+ * Handle an incoming A2A JSON-RPC request.
+ * Returns a JSON-RPC response.
+ */
+export declare function handleA2ARequest(request: A2ARequest): A2AResponse;

package/dist/a2a-protocol.js

@@ -0,0 +1,218 @@
+/**
+ * Agent-to-Agent (A2A) Protocol Support
+ *
+ * Implements the agent card and task exchange protocol enabling Judges
+ * to participate in multi-agent orchestration ecosystems. Compatible
+ * with Google's A2A protocol and similar agent discovery patterns.
+ *
+ * Capabilities:
+ * - Agent Card: advertises Judges' capabilities to orchestrators
+ * - Task Reception: accepts code review requests from other agents
+ * - Task Delegation: forwards specialized work to sub-agents
+ * - Result Reporting: returns structured findings to callers
+ *
+ * Wire format: JSON-RPC 2.0 over HTTP or stdio (MCP-compatible)
+ */
+/**
+ * Generate the Judges agent card for discovery by orchestrators.
+ */
+export function getAgentCard(options) {
+    return {
+        id: "judges-code-reviewer",
+        name: "Judges — AI Code Review Tribunal",
+        version: options?.version || "3.116.0",
+        description: "Automated code review system with 45 specialized judges covering security, " +
+            "performance, reliability, AI-generated code safety, and 40+ rule categories. " +
+            "Uses a tribunal of LLM judges with deterministic pre-screening for high-confidence " +
+            "findings plus human escalation for uncertain cases.",
+        capabilities: [
+            {
+                name: "evaluate-code",
+                description: "Evaluate a code snippet or file for issues across all judge categories",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        code: { type: "string", description: "Source code to evaluate" },
+                        language: { type: "string", description: "Programming language" },
+                        filePath: { type: "string", description: "File path for context" },
+                        preset: { type: "string", enum: ["default", "strict", "lenient", "security-only"] },
+                    },
+                    required: ["code", "language"],
+                },
+            },
+            {
+                name: "evaluate-diff",
+                description: "Evaluate a code diff (PR or commit) for introduced issues",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        diff: { type: "string", description: "Unified diff content" },
+                        baseRef: { type: "string", description: "Base commit/branch reference" },
+                    },
+                    required: ["diff"],
+                },
+            },
+            {
+                name: "review-project",
+                description: "Full project-level review with cross-file analysis",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        files: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    path: { type: "string" },
+                                    content: { type: "string" },
+                                    language: { type: "string" },
+                                },
+                            },
+                        },
+                    },
+                    required: ["files"],
+                },
+            },
+            {
+                name: "explain-finding",
+                description: "Provide detailed explanation of a specific finding",
+            },
+            {
+                name: "suggest-fix",
+                description: "Generate fix suggestions for detected findings",
+            },
+        ],
+        outputFormats: ["json", "sarif", "markdown", "csv", "github-actions"],
+        protocols: ["mcp", "json-rpc-2.0", "http-rest"],
+        authMethods: ["none", "api-key", "github-token"],
+        metadata: {
+            judgeCount: 45,
+            tribunalJudges: 40,
+            ruleCategories: 40,
+            supportsDeterministicMode: true,
+            supportsLlmTribunal: true,
+            supportsStreaming: true,
+            supportsEscalation: true,
+            supportsAuditTrail: true,
+        },
+    };
+}
+// ─── Task Management ─────────────────────────────────────────────────────────
+const taskQueue = new Map();
+function generateTaskId() {
+    return `task_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Create a new A2A task from an incoming request.
+ */
+export function createTask(capability, input, requesterId) {
+    const task = {
+        taskId: generateTaskId(),
+        capability,
+        status: "pending",
+        input,
+        requesterId,
+        createdAt: new Date().toISOString(),
+    };
+    taskQueue.set(task.taskId, task);
+    return task;
+}
+/**
+ * Get a task by ID.
+ */
+export function getTask(taskId) {
+    return taskQueue.get(taskId);
+}
+/**
+ * Update task status and optionally set the result.
+ */
+export function completeTask(taskId, result) {
+    const task = taskQueue.get(taskId);
+    if (!task)
+        return undefined;
+    task.status = "completed";
+    task.output = result;
+    task.completedAt = new Date().toISOString();
+    return task;
+}
+/**
+ * Mark a task as failed.
+ */
+export function failTask(taskId, code, message) {
+    const task = taskQueue.get(taskId);
+    if (!task)
+        return undefined;
+    task.status = "failed";
+    task.error = { code, message };
+    task.completedAt = new Date().toISOString();
+    return task;
+}
+/**
+ * List all tasks, optionally filtered by status.
+ */
+export function listTasks(status) {
+    const tasks = Array.from(taskQueue.values());
+    return status ? tasks.filter((t) => t.status === status) : tasks;
+}
+/**
+ * Clean up completed/failed tasks older than the given age.
+ */
+export function pruneTasks(maxAgeMs = 3600000) {
+    const cutoff = Date.now() - maxAgeMs;
+    let pruned = 0;
+    for (const [id, task] of taskQueue) {
+        if ((task.status === "completed" || task.status === "failed") &&
+            task.completedAt &&
+            new Date(task.completedAt).getTime() < cutoff) {
+            taskQueue.delete(id);
+            pruned++;
+        }
+    }
+    return pruned;
+}
+/**
+ * Handle an incoming A2A JSON-RPC request.
+ * Returns a JSON-RPC response.
+ */
+export function handleA2ARequest(request) {
+    const { method, params, id } = request;
+    switch (method) {
+        case "agent/discover":
+            return { jsonrpc: "2.0", result: getAgentCard(), id };
+        case "agent/capabilities":
+            return { jsonrpc: "2.0", result: getAgentCard().capabilities, id };
+        case "task/create": {
+            if (!params?.capability || !params?.input) {
+                return {
+                    jsonrpc: "2.0",
+                    error: { code: -32602, message: "Missing required params: capability, input" },
+                    id,
+                };
+            }
+            const task = createTask(params.capability, params.input, params.requesterId || "unknown");
+            return { jsonrpc: "2.0", result: { taskId: task.taskId, status: task.status }, id };
+        }
+        case "task/status": {
+            if (!params?.taskId) {
+                return { jsonrpc: "2.0", error: { code: -32602, message: "Missing taskId" }, id };
+            }
+            const task = getTask(params.taskId);
+            if (!task) {
+                return { jsonrpc: "2.0", error: { code: -32001, message: "Task not found" }, id };
+            }
+            return { jsonrpc: "2.0", result: task, id };
+        }
+        case "task/list":
+            return {
+                jsonrpc: "2.0",
+                result: listTasks(params?.status),
+                id,
+            };
+        default:
+            return {
+                jsonrpc: "2.0",
+                error: { code: -32601, message: `Method not found: ${method}` },
+                id,
+            };
+    }
+}

package/dist/api.d.ts

@@ -8,12 +8,16 @@
  * const result = evaluateCode("const x = eval(input);", "typescript");
  * ```
  */
-export type { Severity, Verdict, Finding, Patch, LangFamily, JudgesConfig, RuleOverride, ProjectFile, ProjectVerdict, DiffVerdict, DependencyEntry, DependencyVerdict, JudgeEvaluation, TribunalVerdict, JudgeDefinition, EvaluationContextV2, EvidenceBundleV2, SpecializedFindingV2, TribunalVerdictV2, MustFixGateOptions, MustFixGateResult, AppBuilderWorkflowResult, PlainLanguageFinding, WorkflowTask, PolicyProfile, SuppressionRecord, SuppressionResult, } from "./types.js";
+export type { Severity, Verdict, Finding, Patch, LangFamily, JudgesConfig, RuleOverride, ProjectFile, ProjectVerdict, DiffVerdict, DependencyEntry, DependencyVerdict, JudgeEvaluation, TribunalVerdict, JudgeDefinition, EvaluationContextV2, EvidenceBundleV2, SpecializedFindingV2, TribunalVerdictV2, MustFixGateOptions, MustFixGateResult, AppBuilderWorkflowResult, PlainLanguageFinding, WorkflowTask, PolicyProfile, SuppressionRecord, SuppressionResult, ExecutionTrace, RuleTrace, StreamingBatch, JudgeSelectionContext, JudgeSelectionResult, SessionContext, } from "./types.js";
 export { JudgesError, ConfigError, EvaluationError, ParseError } from "./errors.js";
 export { parseConfig, defaultConfig, mergeConfigs, discoverCascadingConfigs, loadCascadingConfig, loadPluginJudges, validatePluginSpecifiers, isValidJudgeDefinition, applyOverridesForFile, applyLanguageProfile, resolveExtendsConfig, } from "./config.js";
 export { JUDGES, getJudge, getJudgeSummaries } from "./judges/index.js";
-export { evaluateWithJudge, evaluateWithTribunal, evaluateProject, evaluateDiff, analyzeDependencies, enrichWithPatches, crossEvaluatorDedup, diffFindings, formatFindingDiff, evaluateNetChangeGate, applyInlineSuppressions, applyInlineSuppressionsWithAudit, runAppBuilderWorkflow, formatVerdictAsMarkdown, formatEvaluationAsMarkdown, clearEvaluationCaches, scanProjectWideSecurityPatterns, } from "./evaluators/index.js";
-export type { FindingDiff, NetChangeGateOptions, NetChangeGateResult } from "./evaluators/index.js";
+export { evaluateWithJudge, evaluateWithTribunal, evaluateWithTribunalStreaming, evaluateProject, evaluateDiff, analyzeDependencies, enrichWithPatches, crossEvaluatorDedup, diffFindings, formatFindingDiff, evaluateNetChangeGate, applyInlineSuppressions, applyInlineSuppressionsWithAudit, runAppBuilderWorkflow, formatVerdictAsMarkdown, formatEvaluationAsMarkdown, clearEvaluationCaches, scanProjectWideSecurityPatterns, } from "./evaluators/index.js";
+export type { FindingDiff, NetChangeGateOptions, NetChangeGateResult, EvaluationOptions } from "./evaluators/index.js";
+export { selectJudges } from "./evaluators/judge-selector.js";
+export { EvaluationSession, getGlobalSession, resetGlobalSession } from "./evaluation-session.js";
+export { getPreset, composePresets, PRESETS } from "./presets.js";
+export type { Preset } from "./presets.js";
 export { evaluateCodeV2, evaluateProjectV2, getSupportedPolicyProfiles } from "./evaluators/v2.js";
 export { analyzeCrossFileTaint } from "./ast/cross-file-taint.js";
 export { buildSingleJudgeDeepReviewSection, buildTribunalDeepReviewSection, buildSimplifiedDeepReviewSection, isContentPolicyRefusal, DEEP_REVIEW_PROMPT_INTRO, DEEP_REVIEW_IDENTITY, } from "./tools/deep-review.js";
@@ -28,6 +32,18 @@ export { findingsToSarif, evaluationToSarif, verdictToSarif, validateSarifLog }
 export type { SarifValidationError } from "./formatters/sarif.js";
 export { verdictToCsvRows, verdictsToCsv, findingsToCsv } from "./formatters/csv.js";
 export { verdictToGitHubActions } from "./formatters/github-actions.js";
+export { evaluateEscalations, resolveEscalation, computeEscalationSummary, shouldBlockOnEscalations, enhanceReviewWithEscalations, loadEscalationStore, saveEscalationStore, } from "./escalation.js";
+export type { EscalatedFinding, EscalationStore, EscalationSummary, EscalationPolicy, EscalationReason, EscalationStatus, EscalationRouting, } from "./escalation.js";
+export { appendAuditEvent, readAuditTrail, verifyAuditIntegrity, recordEvaluationStart, recordEvaluationComplete, recordFindings, recordSuppression, recordOverride, recordEscalation, recordReviewDecision, recordTriageAction, computeAuditSummary, queryAuditTrail, } from "./audit-trail.js";
+export type { AuditEvent, AuditEventType, AuditPayload, AuditSummary } from "./audit-trail.js";
+export { registerSastProvider, getSastProvider, listSastProviders, ingestSarifFile, ingestSarifContent, mergeSastFindings, } from "./sast-integration.js";
+export type { SastProvider } from "./sast-integration.js";
+export { startReviewConversation, processMessage, getOutstandingFindings, isConversationResolved, exportConversationAsMarkdown, } from "./review-conversation.js";
+export type { ReviewConversation, ConversationMessage, ConversationRole, MessageIntent, ConversationState, DeveloperContext, } from "./review-conversation.js";
+export { getAgentCard, createTask, getTask, completeTask, failTask, listTasks, pruneTasks, handleA2ARequest, } from "./a2a-protocol.js";
+export type { AgentCard, AgentCapability, A2ATask, A2ATaskResult, TaskStatus, A2ARequest, A2AResponse, } from "./a2a-protocol.js";
+export { runFeedbackLoop, formatFeedbackLoopReport } from "./feedback-loop.js";
+export type { FeedbackLoopResult, ConfidenceAdjustment, FeedbackLoopStats } from "./feedback-loop.js";
 export { registerPlugin, unregisterPlugin, getRegisteredPlugins, getCustomRules, getPluginJudges, evaluateCustomRules, runBeforeHooks, runAfterHooks, clearPlugins, } from "./plugins.js";
 export type { CustomRule, JudgesPlugin, PluginRegistration } from "./plugins.js";
 export { JudgeRegistry, defaultRegistry } from "./judge-registry.js";
@@ -56,6 +72,8 @@ export type { BenchmarkCase, BenchmarkResult, BenchmarkGateOptions, BenchmarkGat
 export { parseLlmRuleIds, constructPerJudgePrompt, constructTribunalPrompt, selectStratifiedSample, scoreLlmCase, computeLlmMetrics, formatLlmSnapshotMarkdown, formatLayerComparisonMarkdown, extractValidatedLlmFindings, getValidRulePrefixes, } from "./commands/llm-benchmark.js";
 export type { LlmBenchmarkSnapshot, LlmCaseResult } from "./commands/llm-benchmark.js";
 export type { LlmFinding, ValidationResult } from "./probabilistic/llm-response-validator.js";
+export { optimizeBenchmark, formatAmendmentSection, createEmptyStore, mergeAmendments, } from "./commands/llm-benchmark-optimizer.js";
+export type { PromptAmendment, OptimizerInsight, OptimizationResult, AmendmentStore, } from "./commands/llm-benchmark-optimizer.js";
 export { runReviewAutopilot, dedupeComments, filterAlreadyPostedComments } from "./commands/review.js";
 export { buildContextSnippets } from "./context/context-snippets.js";
 export { EmbeddingCache, FallbackEmbeddingProvider, getOrCreateEmbedding } from "./context/embedding-cache.js";

package/dist/api.js

@@ -15,7 +15,13 @@ export { parseConfig, defaultConfig, mergeConfigs, discoverCascadingConfigs, loa
 // ─── Judge Registry ──────────────────────────────────────────────────────────
 export { JUDGES, getJudge, getJudgeSummaries } from "./judges/index.js";
 // ─── Core Evaluation Functions ───────────────────────────────────────────────
-export { evaluateWithJudge, evaluateWithTribunal, evaluateProject, evaluateDiff, analyzeDependencies, enrichWithPatches, crossEvaluatorDedup, diffFindings, formatFindingDiff, evaluateNetChangeGate, applyInlineSuppressions, applyInlineSuppressionsWithAudit, runAppBuilderWorkflow, formatVerdictAsMarkdown, formatEvaluationAsMarkdown, clearEvaluationCaches, scanProjectWideSecurityPatterns, } from "./evaluators/index.js";
+export { evaluateWithJudge, evaluateWithTribunal, evaluateWithTribunalStreaming, evaluateProject, evaluateDiff, analyzeDependencies, enrichWithPatches, crossEvaluatorDedup, diffFindings, formatFindingDiff, evaluateNetChangeGate, applyInlineSuppressions, applyInlineSuppressionsWithAudit, runAppBuilderWorkflow, formatVerdictAsMarkdown, formatEvaluationAsMarkdown, clearEvaluationCaches, scanProjectWideSecurityPatterns, } from "./evaluators/index.js";
+// ─── Adaptive Judge Selection ────────────────────────────────────────────────
+export { selectJudges } from "./evaluators/judge-selector.js";
+// ─── Evaluation Session ─────────────────────────────────────────────────────
+export { EvaluationSession, getGlobalSession, resetGlobalSession } from "./evaluation-session.js";
+// ─── Presets ─────────────────────────────────────────────────────────────────
+export { getPreset, composePresets, PRESETS } from "./presets.js";
 // ─── V2 Policy-Aware API ────────────────────────────────────────────────────
 export { evaluateCodeV2, evaluateProjectV2, getSupportedPolicyProfiles } from "./evaluators/v2.js";
 // ─── Cross-File Taint Analysis ───────────────────────────────────────────────
@@ -34,6 +40,18 @@ export { clearProjectCache } from "./evaluators/project.js";
 export { findingsToSarif, evaluationToSarif, verdictToSarif, validateSarifLog } from "./formatters/sarif.js";
 export { verdictToCsvRows, verdictsToCsv, findingsToCsv } from "./formatters/csv.js";
 export { verdictToGitHubActions } from "./formatters/github-actions.js";
+// ─── Escalation Protocol ────────────────────────────────────────────────────
+export { evaluateEscalations, resolveEscalation, computeEscalationSummary, shouldBlockOnEscalations, enhanceReviewWithEscalations, loadEscalationStore, saveEscalationStore, } from "./escalation.js";
+// ─── Audit Trail ─────────────────────────────────────────────────────────────
+export { appendAuditEvent, readAuditTrail, verifyAuditIntegrity, recordEvaluationStart, recordEvaluationComplete, recordFindings, recordSuppression, recordOverride, recordEscalation, recordReviewDecision, recordTriageAction, computeAuditSummary, queryAuditTrail, } from "./audit-trail.js";
+// ─── SAST Integration ────────────────────────────────────────────────────────
+export { registerSastProvider, getSastProvider, listSastProviders, ingestSarifFile, ingestSarifContent, mergeSastFindings, } from "./sast-integration.js";
+// ─── Multi-Turn Review Conversation ──────────────────────────────────────────
+export { startReviewConversation, processMessage, getOutstandingFindings, isConversationResolved, exportConversationAsMarkdown, } from "./review-conversation.js";
+// ─── A2A Protocol ────────────────────────────────────────────────────────────
+export { getAgentCard, createTask, getTask, completeTask, failTask, listTasks, pruneTasks, handleA2ARequest, } from "./a2a-protocol.js";
+// ─── Fix-Outcome Feedback Loop ───────────────────────────────────────────────
+export { runFeedbackLoop, formatFeedbackLoopReport } from "./feedback-loop.js";
 // ─── Plugin API ──────────────────────────────────────────────────────────────
 export { registerPlugin, unregisterPlugin, getRegisteredPlugins, getCustomRules, getPluginJudges, evaluateCustomRules, runBeforeHooks, runAfterHooks, clearPlugins, } from "./plugins.js";
 // ─── Judge Registry ──────────────────────────────────────────────────────────
@@ -61,6 +79,8 @@ export { compareCapabilities, formatComparisonReport, formatFullComparisonMatrix
 export { runBenchmarkSuite, benchmarkGate, formatBenchmarkReport, formatBenchmarkMarkdown, analyzeL2Coverage, formatL2CoverageReport, ingestFindingsAsBenchmarkCases, deduplicateIngestCases, BENCHMARK_CASES, } from "./commands/benchmark.js";
 // ─── LLM Benchmark ──────────────────────────────────────────────────────────
 export { parseLlmRuleIds, constructPerJudgePrompt, constructTribunalPrompt, selectStratifiedSample, scoreLlmCase, computeLlmMetrics, formatLlmSnapshotMarkdown, formatLayerComparisonMarkdown, extractValidatedLlmFindings, getValidRulePrefixes, } from "./commands/llm-benchmark.js";
+// ─── LLM Benchmark Optimizer (Self-Teaching) ────────────────────────────────
+export { optimizeBenchmark, formatAmendmentSection, createEmptyStore, mergeAmendments, } from "./commands/llm-benchmark-optimizer.js";
 // Review autopilot (GitHub App / scripts)
 export { runReviewAutopilot, dedupeComments, filterAlreadyPostedComments } from "./commands/review.js";
 export { buildContextSnippets } from "./context/context-snippets.js";