Cron triggers

[shagun-singh-inkeep]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6a4599c

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agents-api	Ready	Preview, Comment	Feb 4, 2026 2:27pm
agents-docs	Ready	Preview, Comment	Feb 4, 2026 2:27pm
agents-manage-ui	Ready	Preview, Comment	Feb 4, 2026 2:27pm

[claude]

Claude finished @shagun-singh-inkeep's task —— View job

---

Code Review: Cron/Scheduled Triggers Feature

I've completed a comprehensive architectural review of this substantial scheduled triggers implementation. This feature adds cron-based and one-time scheduled execution capabilities to the Inkeep Agent Framework.

🏗️ ARCHITECTURAL OVERVIEW

This is a well-architected implementation that introduces scheduled agent invocations using a durable workflow system. The feature spans multiple architectural layers:

• Database Layer: Two new tables (scheduled_triggers in manage DB, scheduled_trigger_invocations in runtime DB)
• API Layer: Full CRUD operations with proper scoping and permissions
• Service Layer: Workflow orchestration using Vercel Workflows for durability
• Workflow Layer: Robust execution engine with retry logic and drift prevention

🎯 STRENGTHS & WELL-EXECUTED PATTERNS

Database Design ✅

• Proper separation: Configuration in manage DB, execution tracking in runtime DB
• Complete audit trail: Comprehensive invocation tracking with status, timing, and error details
• Idempotency support: Built-in deduplication via idempotencyKey
• Migration consistency: Proper Drizzle migrations with metadata management

API Design ✅

• RESTful conventions: Follows established patterns (/agents/{agentId}/triggers/{triggerId})
• Proper scoping: Agent-scoped resources with tenant/project isolation
• Permission boundaries: Appropriate RBAC with edit permissions for mutations
• Comprehensive CRUD: Full lifecycle management with invocation tracking

Workflow Architecture ✅

• Durability: Uses Vercel Workflows for persistent, resumable execution
• Drift prevention: Calculates next execution relative to last scheduled time
• Conflict resolution: Authoritative runner pattern prevents duplicate workflows
• Graceful degradation: Proper cleanup when triggers are disabled/deleted

Service Layer ✅

• Deterministic IDs: Consistent runner ID generation for workflow management
• Lifecycle hooks: Clean start/stop patterns for trigger state changes
• Error boundaries: Proper logging and error handling throughout

⚠️ CRITICAL GAPS & REQUIREMENTS

Per the repository's MANDATORY requirements in CLAUDE.md, this feature is INCOMPLETE and missing essential components:

1. MISSING: Unit Tests 🚨

# Expected locations (currently missing):
agents-api/src/__tests__/manage/routes/scheduledTriggers.test.ts
agents-api/src/__tests__/run/services/ScheduledTriggerService.test.ts  
agents-api/src/__tests__/run/workflow/scheduledTriggerRunner.test.ts
packages/agents-core/src/data-access/manage/__tests__/scheduledTriggers.test.ts

Required test coverage:

• CRUD operations and validation
• Workflow lifecycle (start/stop/restart)
• Cron expression parsing and drift prevention
• Error handling and retry logic
• Database transaction boundaries
• Permission enforcement

2. MISSING: UI Components 🚨

The existing trigger UI (agents-manage-ui/src/components/triggers/) appears to be for webhook triggers only. Scheduled triggers need:

// Required components (currently missing):
agents-manage-ui/src/components/scheduled-triggers/
├── scheduled-trigger-form.tsx      // Create/edit with cron builder
├── scheduled-triggers-table.tsx    // List view with status indicators
├── cron-expression-builder.tsx     // User-friendly cron builder
├── invocation-history.tsx          // Execution history view
└── trigger-status-badge.tsx        // Status visualization

Required pages: The scheduled trigger routes exist but likely show 404s since components are missing.

3. MISSING: Documentation 🚨

No documentation exists for scheduled triggers. Required:

# Expected location (currently missing):
agents-docs/content/typescript-sdk/scheduled-triggers.mdx

4. MISSING: Changeset ⚠️

No changeset created for this significant feature addition. Should be minor due to schema changes.

🛡️ SECURITY & PERFORMANCE CONSIDERATIONS

Security ✅

• Proper authorization: Agent-scoped operations with tenant isolation
• Input validation: Comprehensive Zod schemas with cron expression validation
• SQL injection protection: Parameterized queries via Drizzle ORM

Performance ⚠️

• Batch operations: Good use of Promise.all() for parallel operations
• Potential concern: No mention of workflow cleanup for one-time triggers after execution
• Monitoring gap: No metrics/telemetry for workflow performance

🔧 TECHNICAL DEBT & IMPROVEMENT OPPORTUNITIES

Code Quality Issues

1. Duplicate Logic (DRY Violation)

// scheduledTriggerRunner.ts:47 & ScheduledTriggerService.ts:25
function generateDeterministicRunnerId(/*...*/) {
  return `runner_${tenantId}_${projectId}_${agentId}_${scheduledTriggerId}`;
}

Fix: Extract to shared utility function in agents-core/src/utils/

2. Missing Error Context

scheduledTriggerRunner.ts:150+ - Workflow steps lack sufficient error context for debugging
Fix: Add structured logging with trigger/invocation IDs

3. Hard-coded Constants

// Multiple locations
const diffMs = target.getTime() - now.getTime();
return Math.max(diffMs, 1000); // Hard-coded 1 second minimum

Fix: Make configurable via trigger settings

4. Transaction Boundary Concerns

Cross-database operations (manage→runtime) lack explicit transaction coordination
Consideration: Document failure scenarios and recovery procedures

Architectural Improvements

1. Workflow Lifecycle Management

// Missing: Cleanup completed one-time triggers
if (isOneTime && invocation.status === 'completed') {
  await cleanupWorkflow(runnerId);
}

2. Observable Metrics

Add OpenTelemetry spans for:

• Workflow execution duration
• Retry attempt counts
• Drift measurements
• Queue depth for pending invocations

3. Configuration Validation

Enhanced cron expression validation:

// Consider adding business rules validation
const validateCronExpression = (expr: string) => {
  // Basic syntax validation ✅ (exists)
  // Missing: Frequency limits (e.g., max 1/minute)
  // Missing: Time zone support consideration
};

📊 SCHEMA EVOLUTION CONSIDERATIONS

The database migrations look correct, but consider future extensibility:

// Current schema is restrictive - consider for v2:
type ScheduledTriggerV2 = {
  timezone?: string;           // Time zone support
  conditions?: object;         // Conditional execution rules  
  maxConcurrentRuns?: number; // Prevent overlap
  alertOnFailure?: boolean;   // Notification settings
};

🚦 RECOMMENDATIONS

Immediate (Blocking)

1. Add comprehensive unit tests - Required per CLAUDE.md
2. Implement UI components - Feature unusable without frontend
3. Create documentation - Required for feature completion
4. Add changeset - Required for proper versioning

Short-term (Quality)

1. Extract duplicate runner ID logic to shared utility
2. Add workflow cleanup for completed one-time triggers
3. Enhanced error logging with structured context
4. Add basic telemetry for workflow execution

Medium-term (Enhancement)

1. Time zone support for global deployments
2. Advanced cron features (frequency limits, conditional execution)
3. Bulk operations for trigger management
4. Webhook integration for execution notifications

📋 FEATURE COMPLETENESS CHECKLIST

Based on repository requirements:

• Tests written and passing (pnpm test)
• UI components implemented in agents-manage-ui
• Documentation added to /agents-docs/
• All linting passes (pnpm lint)
• Code is formatted (pnpm format)
• Changeset created for version bump

FINAL VERDICT

This is a high-quality architectural foundation for scheduled triggers with excellent separation of concerns, durability guarantees, and proper security boundaries. However, it's incomplete per the mandatory repository requirements and cannot be merged until the missing components (tests, UI, docs, changeset) are implemented.

The core workflow engine and service layer are production-ready, but the feature needs the complete surface area implementation to be truly usable.

---