@contextrail/code-review-agent 0.1.1-alpha.0

package/dist/mcp/mcp-tools.d.ts

@@ -0,0 +1,292 @@
+import type { McpClient } from './client.js';
+export declare const createMcpTools: (mcpClient: McpClient) => {
+    search_contexts: import("ai").Tool<{
+        query: string;
+        limit?: number | undefined;
+        tags?: string[] | undefined;
+        domain?: string | undefined;
+        team?: string | undefined;
+        organization?: string | undefined;
+        returnFullContexts?: boolean | undefined;
+    }, {
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: Record<string, unknown> | undefined;
+        isError?: boolean | undefined;
+    } | {
+        [x: string]: unknown;
+        toolResult: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    get_context: import("ai").Tool<{
+        contextId: string;
+        version?: number | undefined;
+        organization?: string | undefined;
+    }, {
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: Record<string, unknown> | undefined;
+        isError?: boolean | undefined;
+    } | {
+        [x: string]: unknown;
+        toolResult: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    resolve_dependencies: import("ai").Tool<{
+        contextIds: string[];
+        organization?: string | undefined;
+        tokenBudget?: number | undefined;
+    }, {
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: Record<string, unknown> | undefined;
+        isError?: boolean | undefined;
+    } | {
+        [x: string]: unknown;
+        toolResult: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+};

package/dist/mcp/mcp-tools.js

@@ -0,0 +1,40 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+const searchContextsSchema = z.object({
+    query: z.string(),
+    limit: z.number().int().positive().optional(),
+    tags: z.array(z.string()).optional(),
+    domain: z.string().optional(),
+    team: z.string().optional(),
+    organization: z.string().optional(),
+    returnFullContexts: z.boolean().optional(),
+});
+const getContextSchema = z.object({
+    contextId: z.string(),
+    version: z.number().int().positive().optional(),
+    organization: z.string().optional(),
+});
+const resolveDependenciesSchema = z.object({
+    contextIds: z.array(z.string()).min(1),
+    tokenBudget: z.number().int().positive().optional(),
+    organization: z.string().optional(),
+});
+export const createMcpTools = (mcpClient) => {
+    return {
+        search_contexts: tool({
+            description: 'Search ContextRail contexts',
+            inputSchema: searchContextsSchema,
+            execute: async (params) => mcpClient.searchContexts(params),
+        }),
+        get_context: tool({
+            description: 'Retrieve a specific ContextRail context',
+            inputSchema: getContextSchema,
+            execute: async (params) => mcpClient.getContext(params),
+        }),
+        resolve_dependencies: tool({
+            description: 'Resolve ContextRail context dependencies',
+            inputSchema: resolveDependenciesSchema,
+            execute: async (params) => mcpClient.resolveDependencies(params),
+        }),
+    };
+};

package/dist/mcp/token-validation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * JWT token validation utilities for MCP client.
+ * Performs client-side validation of token structure and expiration
+ * to prevent sending sensitive data to expired or invalid endpoints.
+ *
+ * **SECURITY WARNING**: These functions do NOT verify JWT signatures.
+ * They are intended for UX hints only (e.g., warning before connecting).
+ * The server MUST perform full signature verification and claim validation.
+ * Never use these functions for authorization decisions.
+ */
+/**
+ * Check if a JWT token is expired based on its payload.
+ *
+ * **SECURITY WARNING**: This function does NOT verify the token signature.
+ * It is a non-authoritative UX check only. The server will perform full
+ * cryptographic validation. Never use this for security decisions.
+ *
+ * @param token - JWT token string
+ * @returns True if token is expired or invalid
+ */
+export declare const isTokenExpired: (token: string) => boolean;
+/**
+ * Validate JWT token structure and expiration before use.
+ *
+ * @param token - JWT token string (optional)
+ * @returns Object with validation result and reason
+ */
+export declare const validateToken: (token?: string) => {
+    valid: boolean;
+    reason?: string;
+};

package/dist/mcp/token-validation.js

@@ -0,0 +1,57 @@
+import { decodeJwt } from 'jose';
+/**
+ * JWT token validation utilities for MCP client.
+ * Performs client-side validation of token structure and expiration
+ * to prevent sending sensitive data to expired or invalid endpoints.
+ *
+ * **SECURITY WARNING**: These functions do NOT verify JWT signatures.
+ * They are intended for UX hints only (e.g., warning before connecting).
+ * The server MUST perform full signature verification and claim validation.
+ * Never use these functions for authorization decisions.
+ */
+/**
+ * Check if a JWT token is expired based on its payload.
+ *
+ * **SECURITY WARNING**: This function does NOT verify the token signature.
+ * It is a non-authoritative UX check only. The server will perform full
+ * cryptographic validation. Never use this for security decisions.
+ *
+ * @param token - JWT token string
+ * @returns True if token is expired or invalid
+ */
+export const isTokenExpired = (token) => {
+    if (!token || typeof token !== 'string') {
+        return true;
+    }
+    try {
+        // Use jose library for safe JWT decoding (handles base64url correctly)
+        // Note: decodeJwt does NOT verify signatures - this is intentional for UX checks
+        const decoded = decodeJwt(token);
+        // Check expiration (exp is Unix timestamp in seconds)
+        if (decoded.exp) {
+            const expirationTime = decoded.exp * 1000; // Convert to milliseconds
+            return Date.now() >= expirationTime;
+        }
+        // No expiration claim - consider it valid (server will validate)
+        return false;
+    }
+    catch {
+        // If decoding fails, consider token invalid
+        return true;
+    }
+};
+/**
+ * Validate JWT token structure and expiration before use.
+ *
+ * @param token - JWT token string (optional)
+ * @returns Object with validation result and reason
+ */
+export const validateToken = (token) => {
+    if (!token) {
+        return { valid: false, reason: 'Token is missing' };
+    }
+    if (isTokenExpired(token)) {
+        return { valid: false, reason: 'Token is expired or invalid' };
+    }
+    return { valid: true };
+};

package/dist/mcp/tools-provider.d.ts

@@ -0,0 +1,18 @@
+import type { ToolSet } from 'ai';
+import type { McpClient } from './client.js';
+/**
+ * Tools provider that creates MCP tools from an MCP client.
+ */
+export declare class McpToolsProvider {
+    private mcpClient;
+    constructor(mcpClient: McpClient);
+    /**
+     * Create tools for LLM calls.
+     * Returns the MCP tools (search_contexts, get_context, resolve_dependencies).
+     */
+    createTools(): ToolSet;
+}
+/**
+ * Factory function to create a tools provider from an MCP client.
+ */
+export declare const createToolsProvider: (mcpClient: McpClient) => (() => ToolSet);

package/dist/mcp/tools-provider.js

@@ -0,0 +1,24 @@
+import { createMcpTools } from './mcp-tools.js';
+/**
+ * Tools provider that creates MCP tools from an MCP client.
+ */
+export class McpToolsProvider {
+    mcpClient;
+    constructor(mcpClient) {
+        this.mcpClient = mcpClient;
+    }
+    /**
+     * Create tools for LLM calls.
+     * Returns the MCP tools (search_contexts, get_context, resolve_dependencies).
+     */
+    createTools() {
+        return createMcpTools(this.mcpClient);
+    }
+}
+/**
+ * Factory function to create a tools provider from an MCP client.
+ */
+export const createToolsProvider = (mcpClient) => {
+    const provider = new McpToolsProvider(mcpClient);
+    return () => provider.createTools();
+};

package/dist/observability/index.d.ts

@@ -0,0 +1,2 @@
+export { LlmMetricsCollector } from './metrics.js';
+export type { LlmMetrics } from './metrics.js';

package/dist/observability/index.js

@@ -0,0 +1 @@
+export { LlmMetricsCollector } from './metrics.js';

package/dist/observability/metrics.d.ts

@@ -0,0 +1,48 @@
+import type { LlmCallMetadata, TokenUsage } from '../llm/types.js';
+import type { Logger } from '../logging/logger.js';
+/**
+ * Aggregated metrics for LLM operations.
+ */
+export type LlmMetrics = {
+    totalCalls: number;
+    totalTokens: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    callsByOperation: Record<string, number>;
+    tokensByOperation: Record<string, number>;
+    errorsByOperation: Record<string, number>;
+    toolCallsByTool: Record<string, number>;
+};
+/**
+ * Metrics collector for LLM operations.
+ * Provides centralized observability for all LLM calls.
+ */
+export declare class LlmMetricsCollector {
+    private metrics;
+    private logger?;
+    constructor(logger?: Logger);
+    /**
+     * Record a successful LLM call.
+     */
+    recordCall(metadata: LlmCallMetadata, usage?: TokenUsage): void;
+    /**
+     * Record a failed LLM call.
+     */
+    recordError(metadata: LlmCallMetadata, error: Error): void;
+    /**
+     * Record a tool call.
+     */
+    recordToolCall(metadata: LlmCallMetadata, toolName: string): void;
+    /**
+     * Get current metrics snapshot.
+     */
+    getMetrics(): LlmMetrics;
+    /**
+     * Reset all metrics.
+     */
+    reset(): void;
+    /**
+     * Log metrics summary.
+     */
+    logSummary(): void;
+}

package/dist/observability/metrics.js

@@ -0,0 +1,86 @@
+/**
+ * Metrics collector for LLM operations.
+ * Provides centralized observability for all LLM calls.
+ */
+export class LlmMetricsCollector {
+    metrics;
+    logger;
+    constructor(logger) {
+        this.metrics = {
+            totalCalls: 0,
+            totalTokens: 0,
+            totalPromptTokens: 0,
+            totalCompletionTokens: 0,
+            callsByOperation: {},
+            tokensByOperation: {},
+            errorsByOperation: {},
+            toolCallsByTool: {},
+        };
+        this.logger = logger;
+    }
+    /**
+     * Record a successful LLM call.
+     */
+    recordCall(metadata, usage) {
+        this.metrics.totalCalls += 1;
+        this.metrics.callsByOperation[metadata.operation] =
+            (this.metrics.callsByOperation[metadata.operation] ?? 0) + 1;
+        if (usage) {
+            this.metrics.totalTokens += usage.totalTokens;
+            this.metrics.totalPromptTokens += usage.promptTokens;
+            this.metrics.totalCompletionTokens += usage.completionTokens;
+            this.metrics.tokensByOperation[metadata.operation] =
+                (this.metrics.tokensByOperation[metadata.operation] ?? 0) + usage.totalTokens;
+        }
+    }
+    /**
+     * Record a failed LLM call.
+     */
+    recordError(metadata, error) {
+        this.metrics.errorsByOperation[metadata.operation] =
+            (this.metrics.errorsByOperation[metadata.operation] ?? 0) + 1;
+        this.logger?.warn(`[METRICS] LLM call error: ${metadata.operation}`, error);
+    }
+    /**
+     * Record a tool call.
+     */
+    recordToolCall(metadata, toolName) {
+        this.metrics.toolCallsByTool[toolName] = (this.metrics.toolCallsByTool[toolName] ?? 0) + 1;
+    }
+    /**
+     * Get current metrics snapshot.
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Reset all metrics.
+     */
+    reset() {
+        this.metrics = {
+            totalCalls: 0,
+            totalTokens: 0,
+            totalPromptTokens: 0,
+            totalCompletionTokens: 0,
+            callsByOperation: {},
+            tokensByOperation: {},
+            errorsByOperation: {},
+            toolCallsByTool: {},
+        };
+    }
+    /**
+     * Log metrics summary.
+     */
+    logSummary() {
+        this.logger?.info('[METRICS] LLM Usage Summary:', {
+            totalCalls: this.metrics.totalCalls,
+            totalTokens: this.metrics.totalTokens,
+            totalPromptTokens: this.metrics.totalPromptTokens,
+            totalCompletionTokens: this.metrics.totalCompletionTokens,
+            callsByOperation: this.metrics.callsByOperation,
+            tokensByOperation: this.metrics.tokensByOperation,
+            errorsByOperation: this.metrics.errorsByOperation,
+            toolCallsByTool: this.metrics.toolCallsByTool,
+        });
+    }
+}

package/dist/orchestrator/agentic-orchestrator.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { ReviewInputs } from '../review-inputs/index.js';
+import type { McpClient } from '../mcp/client.js';
+import type { Logger } from '../logging/logger.js';
+declare const orchestratorOutputSchema: z.ZodObject<{
+    understanding: z.ZodString;
+    reviewers: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    understanding: string;
+    reviewers: string[];
+}, {
+    understanding: string;
+    reviewers: string[];
+}>;
+export type OrchestratorOutput = z.infer<typeof orchestratorOutputSchema>;
+export type AgenticOrchestratorConfig = {
+    openRouterApiKey: string;
+    orchestratorModel: string;
+    maxSteps?: number;
+    prDescription?: string;
+    reviewDomains?: string[];
+};
+export type AgenticOrchestratorDeps = {
+    mcpClient: McpClient;
+    config: AgenticOrchestratorConfig;
+    logger?: Logger;
+};
+export declare const runOrchestrator: (inputs: ReviewInputs, outputDir: string, deps: AgenticOrchestratorDeps) => Promise<OrchestratorOutput>;
+export {};