fix(agents-cli): add backwards compatibility for legacy profiles.yaml…

[amikofalvy]

… schema

Adds support for migrating legacy profiles.yaml format that used manageApi/runApi fields to the new api field. When a legacy profile is detected during load, it is automatically migrated and saved.

• Add isLegacyRemote() to detect old format with manageApi field
• Add migrateLegacyRemote() to convert manageApi -> api
• Update loadProfiles() to migrate legacy profiles on first load
• Update documentation to show new schema format
• Add comprehensive tests for legacy profile migration

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2f210c4

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	Review	Updated (UTC)
agents-api	Ready	Preview, Comment	Jan 21, 2026 10:31pm
agents-docs	Error		Jan 21, 2026 10:31pm
agents-manage-ui	Ready	Preview, Comment	Jan 21, 2026 10:31pm

[claude]

Claude finished @amikofalvy's task —— View job

---

Staff Engineer Code Review Complete

Review Tasks:

• Analyze changed files and understand implementation approach
• Research existing codebase patterns for context
• Evaluate migration logic for correctness and robustness
• Review test coverage and quality
• Assess documentation updates
• Check for architectural and system-level considerations
• Provide comprehensive feedback on engineering quality and customer impact

---

Summary

This PR implements backwards compatibility for legacy profiles.yaml schema migration in a well-structured way. The migration automatically converts the old manageApi/runApi format to the new api field format. While the implementation is solid, there are several architectural and process considerations to address.

Engineering Quality Assessment

✅ Strengths

Robust Migration Logic (types.ts:42-61)

• Type-safe detection with proper null/object checks
• Clean mapping: manageApi → api (conceptually sound)
• Sensible handling of deprecated runApi field (ignored in new format)

Atomic File Operations (profile-manager.ts:214-263)

• Excellent atomic write pattern using temp files + rename
• Proper cleanup on errors
• Validation before saving

Comprehensive Test Coverage

• 210 new test lines covering all migration scenarios
• Edge cases: mixed formats, invalid data, re-migration safety
• Round-trip validation ensures persistence works correctly

⚠️ Areas for Consideration

1. Missing Changeset (Process)

The changeset-bot indicates this PR needs a changeset. Since this affects CLI behavior, it should include:

---
"@inkeep/agents-cli": patch
---

Add backwards compatibility for legacy profiles.yaml schema. Legacy profiles with manageApi/runApi fields are automatically migrated to the new api field format.

2. Migration Logging Strategy

Current: logger.info({}, 'Migrated legacy profile format (manageApi/runApi -> api)')

Consideration: Users may not see this info-level log. For a schema migration, consider:

• More prominent user notification (console.log)
• Specific per-profile logging showing what changed
• Optional backup creation before migration

// Suggested enhancement
console.log(chalk.yellow(`📦 Migrated legacy profile '${name}': manageApi -> api`));

3. Field Semantics Validation

Question: The migration maps manageApi → api. Based on context:

• Legacy manageApi: Management API endpoint
• New api: Agents API endpoint
• Legacy runApi: Agents run API (deprecated)

Is manageApi actually the same as the new api field semantically? The docs suggest api is the "agents API endpoint" while manageApi was the "management API endpoint". If these are different services, this migration could break users.

Recommendation: Verify this mapping is correct, or add validation that warns users if the endpoints seem incorrect.

4. Type Safety Enhancement

The migrateLegacyProfiles method uses unknown types extensively. Consider stronger typing:

// Current
const parsedObj = parsed as Record<string, unknown>;

// Enhanced
interface LegacyProfilesConfig {
  activeProfile: string;
  profiles: Record<string, {
    remote: LegacyExplicitRemote | ExplicitRemote | 'cloud';
    credential: string;
    environment: string;
  }>;
}

// With proper discrimination
function isLegacyProfilesConfig(obj: unknown): obj is LegacyProfilesConfig { /* ... */ }

5. Error Handling Edge Cases

Partial migration failures: If migration succeeds for some profiles but fails for others, the current implementation saves partial results. Consider:

• All-or-nothing migration approach
• Better error reporting for which specific profiles failed

6. Performance Consideration

Migration runs on every loadProfiles() call. While properly guarded, consider:

• Adding a migration version flag to profiles.yaml to skip future checks
• Or migration marker: _migratedFrom: "legacy-v1"

7. Documentation Update Quality

The MDX documentation update is well done, clearly explaining:

• The new schema format
• Legacy format automatic migration
• Note about backwards compatibility

Minor suggestion: Consider adding a troubleshooting section for users who might encounter issues.

Customer Impact Assessment

✅ Positive Impact

1. Seamless Migration: Users with legacy profiles will not experience breaking changes
2. Zero Downtime: Migration happens automatically on first CLI usage
3. Clear Documentation: Users understand the new format and migration

⚠️ Potential Issues

1. Silent Migration: Users may not realize their profiles.yaml was changed
2. Rollback Complexity: No easy way to revert to legacy format if needed
3. Multi-Version CLI: If users switch between CLI versions, newer files may not work with older versions

🔍 Validation Recommendations

Before merging, validate:

1. Field Mapping Accuracy: Confirm manageApi and new api point to the same logical service
2. Integration Testing: Test with real legacy profiles from production/staging
3. CLI Version Compatibility: Ensure older CLI versions handle the new format gracefully (or fail clearly)

Architecture Assessment

This sets a good precedent for future schema migrations:

• Type-safe detection functions
• Atomic operations
• Comprehensive testing
• Clear documentation

Suggested Template for Future Migrations:

interface MigrationResult<T> {
  migrated: boolean;
  result: T;
  errors?: string[];
  warnings?: string[];
}

Final Recommendation

✅ Approve with minor adjustments:

1. Add changeset (process requirement)
2. Verify field mapping semantics (critical for correctness)
3. Consider enhanced user notification (UX improvement)
4. Add integration test with real legacy data (quality assurance)

The implementation is architecturally sound and follows good TypeScript practices. The test coverage is excellent. The main concerns are around process (changeset) and ensuring the semantic mapping is correct.