Feat: General agents + presentations

[AshishKumar4]

Summary

This PR refactors the agent architecture to separate behavior logic from infrastructure, enabling support for multiple agent behaviors (phasic and agentic modes).

Changes

Core Architecture

• Renamed simpleGeneratorAgent.ts → baseAgent.ts with extracted base behavior class
• Added AgentInfrastructure<TState> interface to decouple behavior from Durable Objects
• Added BaseAgentBehavior<TState> abstract class with common agent functionality
• Added worker/agents/core/phasic/behavior.ts (852 lines) - phasic behavior implementation
• Added smartGeneratorAgent.ts - thin wrapper implementing AgentInfrastructure

State Management

• Modified state.ts - split state into BaseProjectState, PhasicState, AgenticState
• Modified types.ts - added BehaviorType, generic AgentInitArgs<TState>
• Breaking: Replaced agentMode: 'deterministic' | 'smart' with behaviorType: 'phasic' | 'agentic'

Operations & Services

• Modified 38 files in worker/agents/ to use ICodingAgent interface
• Deleted ScreenshotAnalysisOperation.ts - screenshot handling moved/removed
• Modified All tool files to accept ICodingAgent instead of concrete class
• Modified PhaseImplementation.ts - simplified, moved logic to behavior
• Modified GenerationContext.ts - added PhasicGenerationContext variant

Interface Changes

• Modified ICodingAgent.ts - formalized interface for all agent behaviors
• All tools now work through interface rather than concrete implementation

Motivation

The previous architecture tightly coupled agent behavior to Durable Objects infrastructure, making it difficult to:

1. Support multiple agent behaviors (deterministic phasic vs autonomous agentic)
2. Test agent logic without Durable Objects overhead
3. Reuse agent logic in different execution contexts

This refactoring enables:

• Behavior Switching: Select phasic or agentic mode per session
• Testing: Mock AgentInfrastructure for unit tests
• Extensibility: Add new behaviors without modifying infrastructure

Testing

Manual Testing:

1. Create new session and verify phasic behavior works
2. Test all LLM tools (generate_files, deep_debug, etc.)
3. Verify state persistence across DO hibernation
4. Test user conversation flow and file regeneration

Areas Requiring Extra Attention:

• State migration for existing sessions (old agentMode → new behaviorType)
• Screenshot upload functionality (ScreenshotAnalysis operation removed)
• Deep debugger integration with new interface

Breaking Changes

State Schema:

• Removed: agentMode: 'deterministic' | 'smart'
• Added: behaviorType: 'phasic' | 'agentic'

Impact: Existing Durable Object sessions may need migration logic or will default to phasic mode.

Related Issues

• Part 1 of agent generalization effort
• Enables future agentic behavior implementation
• May affect Improve Screenshot Workflow #249 (screenshot workflow) due to ScreenshotAnalysisOperation removal

---

_{This PR description was automatically generated by Claude Code}

[github-actions]

Claude finished @AshishKumar4's task —— View job

---

Code Quality & Security Review

Recommendation: REQUEST CHANGES (Critical bug found)

---

Executive Summary

This is a significant architectural refactoring that successfully decouples agent behavior from Durable Objects infrastructure. The overall design is solid, but there is one critical bug in state migration that must be fixed before merging, plus several code quality improvements needed per CLAUDE.md standards.

---

Critical Issues

1. CRITICAL: State Migration Bug - Data Loss Risk

Location: worker/agents/core/stateMigration.ts:236-246
Severity: HIGH - Data Integrity Issue

The migration code computes migratedBehaviorType but never applies it to newState. This means:

• Existing Durable Object sessions with agentMode will lose their behavior preference
• Sessions will default to undefined/unknown behavior type
• User experience will break for existing sessions

Impact: Affects all existing production sessions during deployment.

See inline comment for fix

---

Code Quality Issues (CLAUDE.md Violations)

2. Type Safety: 'any' Type Usage

Location: worker/agents/core/stateMigration.ts:98
CLAUDE.md Rule #1: "NEVER use any type"

const getTimestamp = (msg: any) => {

The parameter is already typed as ConversationMessage from the array iteration. Use proper types.

Other instances found:

• worker/agents/inferutils/schemaFormatters.ts - Multiple any usages (lines 384, 763, 979, 1093)
• These appear to be in schema transformation utilities where any may be intentional for dynamic schema handling, but should be reviewed

---

Architecture Review

Positive Changes

Well-Designed Abstractions:

• AgentInfrastructure<TState> interface cleanly separates infrastructure from behavior
• BaseAgentBehavior<TState> provides good foundation for multiple behaviors
• State split into BaseProjectState, PhasicState, AgenticState is logical
• Operations properly refactored to use ICodingAgent interface

Code Organization:

• 1750 lines in base.ts, 717 in phasic.ts, 392 in agentic.ts - reasonable distribution
• Clear separation of concerns between behaviors and infrastructure
• Proper use of TypeScript discriminated unions for state types

Migration Strategy:

• Good migration logic for legacy fields (latestScreenshot, templateDetails)
• Conversation deduplication logic is solid
• Proper cleanup of internal memos

Areas of Concern

1. Type Assertions in Phasic Behavior
The code at worker/agents/core/behaviors/phasic.ts:201-214 uses a type guard which is GOOD:

const context = GenerationContext.from(this.state, this.getTemplateDetails(), this.logger);
if (!GenerationContext.isPhasic(context)) {
    throw new Error('Expected PhasicGenerationContext');
}

This is the correct approach and addresses previous review comments about unsafe type assertions.

2. Missing Import - Agentic Behavior
Previous review comments noted missing AgenticAgentBehavior import in smartGeneratorAgent.ts. Checking current code:

• File worker/agents/core/smartGeneratorAgent.ts was DELETED
• File worker/agents/core/codingAgent.ts now handles behavior instantiation (lines 14-15):

import { PhasicCodingBehavior } from './behaviors/phasic';
import { AgenticCodingBehavior } from './behaviors/agentic';

This issue is RESOLVED - imports are present and correct.

3. State Machine Complexity
The phasic behavior state machine (lines 284-313) is complex but well-structured with clear state transitions. No concerns.

---

Security Analysis

Reviewed critical paths: worker/api/, worker/database/, worker/agents/

Findings:

• No SQL injection vulnerabilities found
• No authentication/authorization issues introduced
• Git operations properly use parameterized queries via isomorphic-git
• WebSocket message handling maintains proper validation
• File system operations properly sanitized via normalizePath and isPathSafe
• Image upload uses proper validation via uploadImage utility

Note: This PR primarily refactors internal architecture without touching security-sensitive authentication, database queries, or API endpoints. The main security concern is the state migration bug which could cause availability issues.

---

Breaking Changes Review

Breaking Change: agentMode → behaviorType

The PR description acknowledges this. The migration logic exists but is buggy (see Critical Issue #1). Once fixed, the migration should handle backward compatibility correctly.

Missing from Migration:

• Should also delete the old agentMode field after migration (currently only logs it)
• Fix has been provided in inline comment

---

Testing Recommendations

Given the scope of this refactor, recommend:

1. Manual Testing:

   • ✓ Create new phasic session
   • ✓ Create new agentic session
   • CRITICAL: Test state migration from old session with agentMode field
   • ✓ Verify state persistence across DO hibernation
   • ✓ Test all LLM tools work through new interface

2. Edge Cases:

   • Session with agentMode: 'smart' → should become behaviorType: 'agentic'
   • Session with agentMode: 'deterministic' → should become behaviorType: 'phasic'
   • Session with neither field → should default appropriately

---

Summary

Must Fix Before Merge:

1. State migration bug in stateMigration.ts:236-246 - CRITICAL

Should Fix (CLAUDE.md compliance):
2. Remove any type usage in stateMigration.ts:98

Optional Improvements:
3. Simplify type guard in AgenticProjectBuilder.ts:154-157
4. Review any usage in schemaFormatters.ts for necessity

Overall Assessment:
Excellent architectural refactoring with clean abstractions and proper separation of concerns. The critical state migration bug is straightforward to fix. Once addressed, this will significantly improve the codebase's testability and extensibility.

---

[github-actions]

CRITICAL: State Migration Bug - behaviorType Not Applied

The migration logic computes migratedBehaviorType (lines 236-244) but NEVER assigns it to the newState object. This means:

1. The migration is logged but not actually applied
2. Existing sessions with agentMode will lose their behavior preference
3. They will default to whatever state.behaviorType was (likely undefined/unknown)

Fix Required:

Suggested change

	let migratedBehaviorType = state.behaviorType;
	if (isStateWithAgentMode(state)) {
	migratedBehaviorType = state.agentMode === 'smart' ? 'agentic' : 'phasic';
	needsMigration = true;
	logger.info('Migrating agentMode to behaviorType', {
	oldMode: state.agentMode,
	newType: migratedBehaviorType
	});
	}
	return newState;
	let migratedBehaviorType = state.behaviorType;
	if (isStateWithAgentMode(state)) {
	migratedBehaviorType = state.agentMode === 'smart' ? 'agentic' : 'phasic';
	needsMigration = true;
	logger.info('Migrating agentMode to behaviorType', {
	oldMode: state.agentMode,
	newType: migratedBehaviorType
	});
	// Apply the migrated value
	newState.behaviorType = migratedBehaviorType;
	delete stateWithDeprecated.agentMode;
	}
	return newState;

This is a data integrity issue that could break existing user sessions.

[github-actions]

Low Priority: Inline Type Guard Can Be Simplified

While this is functional, the type guard doesn't need to be this verbose. TypeScript can infer from the property check alone:

Suggested change

	const isAgenticBlueprint = (bp?: Blueprint): bp is AgenticBlueprint => {
	if (!bp) return false;
	return 'plan' in bp && Array.isArray(bp.plan);
	};
	const isAgenticBlueprint = (bp?: Blueprint): bp is AgenticBlueprint => {
	return !!bp && 'plan' in bp && Array.isArray(bp.plan);
	};

Note: Previous review comment suggested avoiding (bp as any).plan which has been correctly fixed here. This is just a minor simplification suggestion.