paseo/REPORT-new-agent-page-review.md

Review Report: New Agent Page (/agent/new) Feature Gap Analysis

Date: 2025-12-25 Reviewer: Agent Files Reviewed:

• packages/app/src/app/agent/new.tsx (560 lines) - New agent creation page
• packages/app/src/components/create-agent-modal.tsx (~2700 lines) - Old modal with full features
• packages/app/src/components/home-footer.tsx - Entry points for agent creation

---

Executive Summary

The new /agent/new page is a partial implementation that handles basic agent creation but is missing critical features from the old modal. The old modal code is still in the codebase but unused (dead code). This review identifies all gaps and provides implementation recommendations.

---

Current State

Entry Points

Button	Action	Status
"New Agent"	router.push("/agent/new")	Uses new page (incomplete)
"Import"	setShowImportModal(true)	Uses old modal (works)
Dead code: CreateAgentModal	showCreateModal never set to true	Unused

What Works in New Page

1. Host selection - Dropdown with connection states
2. Provider selection - AssistantDropdown with provider definitions
3. Mode selection - PermissionsDropdown with mode options
4. Model selection - ModelDropdown with loading/error states
5. Working directory - WorkingDirectoryDropdown with suggestions
6. Agent creation - Basic createAgent() call with config
7. Navigation - Redirects to /agent/[serverId]/[agentId] on success

---

Missing Features (Critical)

1. Git Options Section

Location in old modal: create-agent-modal.tsx:1936-1993 and GitOptionsSection component at line 2398-2565

Features missing:

• Base branch selection dropdown (fetches branches from repo)
• "Create new branch" toggle + branch name input with auto-slug
• "Create worktree" toggle + worktree slug input
• Git validation errors display
• Dirty working directory warning
• Non-git directory detection and handling

Impact: Users cannot create agents on feature branches or worktrees - a core workflow.

Implementation Effort: HIGH (~200 lines of state + UI + validation logic)

---

2. Image Attachments

Location in old modal: Uses useImageAttachmentPicker hook, but the new page already has this via AgentInputArea!

Current new page behavior (new.tsx:216-218):

if (images && images.length > 0) {
  return;  // Silently returns without creating agent!
}

Fix required: Remove the early return and include images in the createAgent() call:

const config: AgentSessionConfig = {
  provider: selectedProvider,
  cwd: trimmedPath,
  images, // Add this
  // ...
};

Impact: CRITICAL - Users cannot create agents with image attachments.

Implementation Effort: LOW (5 lines to fix)

---

3. Error Message Display

Location in old modal: errorMessage state + setErrorMessage() calls + display in UI

Current new page behavior:

• No errorMessage state
• No error display to user
• Errors like "Working directory is required" are not shown

Fix required: Add errorMessage state and display it in the UI.

Implementation Effort: LOW (~20 lines)

---

4. Loading State During Creation

Location in old modal: isLoading state + setIsLoading(true) before create + button spinner

Current new page behavior:

• No isLoading state
• Button doesn't disable during creation
• No spinner/loading indicator

Fix required: Add isLoading state, disable button, show spinner.

Implementation Effort: LOW (~15 lines)

---

5. Daemon Availability Error Handling

Location in old modal: daemonAvailabilityError + display when daemon offline

Current new page behavior:

• Checks selectedServerId exists before calling createAgent
• Does NOT show error when daemon is offline
• Silent failures possible

Fix required: Add offline detection and display friendly error message.

Implementation Effort: LOW (~20 lines)

---

6. Creation Failure Handling

Location in old modal: Listens for agent_create_failed status and displays payload.error

Current new page behavior (new.tsx:269-271):

if (payload.status === "agent_create_failed") {
  pendingRequestIdRef.current = null;
  return;  // Does nothing! User sees no error.
}

Fix required: Add setErrorMessage(payload.error) to show the failure reason.

Implementation Effort: LOW (2 lines)

---

7. Dictation Support

Location in old modal: Full useDictation integration with:

• handleDictationStart/Cancel/Confirm handlers
• PromptDictationControls component
• DictationStatusNotice for retry/error toasts
• Audio debug notices

Current new page behavior:

• AgentInputArea already has dictation support built-in!
• No additional work needed if AgentInputArea is correctly configured

Verification needed: Check if AgentInputArea dictation works for draft agent creation.

Impact: Likely already works via AgentInputArea - needs testing.

---

8. Import Flow

Location in old modal: flow: "create" | "import" prop, import list, resume logic

Current state:

• Import button already uses ImportAgentModal (old modal with flow="import")
• This is intentional separation - import stays in modal

No action needed: Import flow is separate and working.

---

Dead Code to Remove

After completing the new page, the following can be deleted from home-footer.tsx:

// Line 25 - unused state
const [showCreateModal, setShowCreateModal] = useState(false);

// Lines 206-209 - unused modal
<CreateAgentModal
  isVisible={showCreateModal}
  onClose={() => setShowCreateModal(false)}
/>

Additionally, if CreateAgentModal is no longer used anywhere after this:

• Consider removing the isVisible wrapper logic
• Or rename to AgentFlowModal since it's only used for Import

---

Implementation Priority

Priority	Feature	Effort	Impact
P0	Fix image attachments (remove early return)	5 lines	CRITICAL
P0	Add creation failure error display	2 lines	HIGH
P0	Add error message state + display	20 lines	HIGH
P1	Add loading state + button disable	15 lines	MEDIUM
P1	Add daemon offline error handling	20 lines	MEDIUM
P2	Git Options Section	~200 lines	HIGH (workflow)
P2	Verify dictation works	Testing	LOW

Recommendation: Complete P0/P1 items first (~60 lines), then tackle Git Options as a separate task.

---

Verification Steps

After implementation:

1. Image test: Attach image, create agent - should include image in request
2. Error test: Enter empty working directory - should show error message
3. Loading test: Create agent - button should show spinner, be disabled
4. Offline test: Disconnect daemon - should show "host offline" message
5. Failure test: Create with invalid path - should show server error
6. Git test: Select base branch, create new branch, create worktree

---

Conclusion

The new /agent/new page needs ~60 lines of fixes for critical functionality (P0/P1), plus ~200 lines for Git options (P2). The AgentInputArea component already provides dictation and image picker, so those features just need proper wiring.

Dead code cleanup should happen after feature parity is achieved.