Agents mono api

[miles-kt-inkeep]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
agents-eval-api	Error		Jan 20, 2026 10:34pm
agents-manage-api	Error		Jan 20, 2026 10:34pm
agents-manage-ui	Ready	Preview, Comment	Jan 20, 2026 10:34pm
agents-run-api	Error		Jan 20, 2026 10:34pm

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
agents-docs	Skipped		Jan 20, 2026 10:34pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6f580da

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[claude]

Claude finished @miles-kt-inkeep's task —— View job

---

Staff Engineer Code Review - Agents Mono API

I've completed my comprehensive review of this significant architectural PR. This consolidates manage, run, and eval APIs into a unified deployment package.

🎯 Overall Assessment: Strong Architectural Foundation

This PR demonstrates solid engineering practices with a well-structured domain-driven approach. The consolidation strategy is sound and the implementation shows attention to security, testing, and maintainability.

🏗️ Architectural Strengths

✅ Excellent Domain Organization

• Clean separation of concerns under /src/domains/{manage,run,evals}/
• Shared infrastructure (middleware, types, database clients) properly abstracted
• Domain-specific routing with clear API boundaries

✅ Comprehensive Security Design

• Multi-layered authentication (API keys, sessions, tenant access)
• Route-specific CORS policies with granular origin controls
• RBAC permissions middleware for manage operations
• Proper credential store abstraction

✅ Robust Testing Strategy

• 65 test files with excellent coverage across domains
• Isolated in-memory databases per test worker
• Integration and unit test separation
• Proper mocking of logger and external dependencies

🔍 Key Areas for Enhancement

🚨 Critical: Database Layer Architecture

Issue: The current database client setup creates potential architectural confusion:

// agents-api/src/data/db/manageDbClient.ts
const manageDbClient = createAgentsManageDatabaseClient({
  connectionString: env.INKEEP_AGENTS_MANAGE_DATABASE_URL,
});

Concerns:

1. Singleton Pattern: Each domain imports shared database clients, but there's no clear connection pooling strategy
2. Resource Management: No explicit connection lifecycle management in the unified API
3. Database Separation: Having separate manage/run databases but sharing a single app instance could lead to confusion about data access patterns

Recommendations:

• Consider implementing a database client factory pattern
• Add explicit connection pooling configuration
• Document the database separation strategy and when each should be used
• Add health checks for both database connections

🚨 Moderate: CORS Configuration Complexity

The CORS setup in createApp.ts is quite complex with route-specific middleware:

// Multiple CORS configurations layered on different routes
app.use('/api/auth/*', cors(authCorsConfig));
app.use('/run/*', cors(runCorsConfig));
app.use('/manage/tenants/*/playground/token', cors(playgroundCorsConfig));

Concerns:

• Complex middleware ordering that could be fragile
• Multiple origin validation functions with overlapping logic
• Potential for CORS bypass if route patterns don't match exactly

Recommendations:

• Consolidate CORS logic into a single middleware with route-aware configuration
• Add tests specifically for CORS middleware ordering
• Consider using a more declarative CORS configuration approach

⚠️ Moderate: Error Handling Consistency

Good: RFC 7807 Problem Details format is excellent
Concern: Error handling varies between domains

// Inconsistent error formatting across different route handlers
// Some use handleApiError, others create errors differently

Recommendations:

• Standardize error creation patterns across all domains
• Add error boundary tests for each domain
• Consider domain-specific error enhancement middleware

⚠️ Minor: Type Safety & API Design

Observations:

1. Good: Strong Zod schemas for request validation
2. Good: OpenAPI integration with proper typing
3. Enhancement Opportunity: Some any types in variable definitions could be more specific

type AppVariables = {
  requestBody?: unknown; // Could be more specific per route
  sandboxConfig?: SandboxConfig; // Good typing
};

🔧 Implementation Recommendations

1. Database Client Management

// Consider this pattern for better resource management
export interface DatabaseClients {
  manage: AgentsManageDatabaseClient;
  run: AgentsRunDatabaseClient;
  healthCheck(): Promise<{ manage: boolean; run: boolean }>;
  close(): Promise<void>;
}

2. Simplified CORS Architecture

// Consider a more declarative approach
const corsConfig = {
  '/api/auth/*': authCorsConfig,
  '/run/*': runCorsConfig,
  '/manage/tenants/*/playground/token': playgroundCorsConfig,
  default: defaultCorsConfig
};

3. Domain-Specific Error Enhancement

// Add domain context to error handling
export function domainErrorHandler(domain: 'manage' | 'run' | 'evals') {
  return async (err: Error, c: Context) => {
    // Add domain-specific error context
    const errorWithDomain = { ...err, domain };
    return errorHandler(errorWithDomain, c);
  };
}

🎉 Notable Engineering Excellence

Middleware Design

• Clean separation of concerns (auth, CORS, error handling)
• Proper dependency injection pattern
• Good use of Hono's middleware composition

Testing Infrastructure

• Excellent test isolation with in-memory databases
• Comprehensive mocking strategy
• Good separation of unit vs integration tests

API Design

• OpenAPI 3.1 specification compliance
• Consistent request/response patterns
• Proper HTTP semantics usage

📋 Pre-Merge Checklist

• Database Health Checks: Add monitoring for both manage and run database connections
• Performance Testing: Test connection pooling under load with the unified API
• CORS Testing: Add comprehensive tests for all CORS configurations and edge cases
• Documentation: Update deployment docs to reflect the unified API architecture
• Migration Strategy: Document how existing separate API deployments will transition to this unified approach

🎯 Summary

This is a well-executed architectural consolidation that maintains clean domain boundaries while providing deployment efficiency. The core patterns are solid, and the implementation demonstrates strong engineering practices.

The identified issues are primarily about operational robustness rather than fundamental design flaws. With the database client management enhancements and CORS simplification, this will be an excellent foundation for the unified agents platform.

Recommended Action: ✅ Approve with suggested enhancements

The architectural benefits significantly outweigh the concerns, and the suggested improvements can be addressed in follow-up work without blocking this foundational change.

---