nexus/.planning/milestones/v1.4-phases/29-default-provider/29-01-SUMMARY.md

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
29-default-provider	01	ui	hermes adapter onboarding probe wizard agents	phase provides 27-hermes-adapter hermes_local adapter with testEnvironment method phase provides 28-ollama-integration Hermes session and heartbeat integration	Board-auth GET /adapters/:type/probe route with no companyId required agentsApi.probeAdapter(type) client method NexusOnboardingWizard auto-detects Hermes and falls back to hermes_local Directory input optional when hermes_local is selected NewAgentDialog AGENT_TEMPLATES adapter-neutral (role+name only, no adapterType)	30-agent-templates default-provider-ux onboarding	added patterns Board-auth probe route pattern for adapter availability detection without companyId useEffect probe-on-open pattern for runtime adapter detection in wizard Adapter-neutral template navigation (role+name only, no adapterType in URL)	created modified server/src/routes/agents.ts ui/src/api/agents.ts ui/src/components/NexusOnboardingWizard.tsx ui/src/components/NewAgentDialog.tsx	Probe route uses board auth (not company-scoped) — adapter availability is instance-level, not company-level graceful probe failure keeps claude_local default — network errors or missing adapter don't break onboarding hermes_local makes directory optional (not required) — Hermes doesn't need a cwd to operate AGENT_TEMPLATES in NewAgentDialog are now adapter-neutral — /agents/new form handles its own adapter default logic	Probe-on-open pattern: useEffect with effectiveOnboardingOpen trigger for lazy adapter detection Board-auth adapter route: /adapters/:type/probe — no companyId, board auth guard only	DFLT-01 DFLT-02	8min	2026-04-02

Phase 29 Plan 01: Default Provider Summary

Board-auth hermes probe route + NexusOnboardingWizard Hermes fallback + adapter-neutral agent templates in NewAgentDialog

Performance

• Duration: ~8 min
• Started: 2026-04-02T17:29:41Z
• Completed: 2026-04-02T17:37:00Z
• Tasks: 2
• Files modified: 4

Accomplishments

• Added GET /adapters/:type/probe route with board auth guard — returns {available, status, checks} without requiring a companyId
• Added agentsApi.probeAdapter(type) client method that calls the new probe route
• NexusOnboardingWizard now probes for hermes_local on open and uses it as defaultAdapter when available
• Directory input is optional when hermes_local is selected; description text updated for local AI path
• NewAgentDialog AGENT_TEMPLATES no longer hardcode adapterType — handleTemplateSelect navigates with role+name only

Task Commits

Each task was committed atomically:

1. Task 1: Add board-auth adapter probe route and frontend client - f85ced58 (feat)
2. Task 2: Update NexusOnboardingWizard and NewAgentDialog - a2f54282 (feat)

Files Created/Modified

• server/src/routes/agents.ts - Added GET /adapters/:type/probe with board auth guard
• ui/src/api/agents.ts - Added agentsApi.probeAdapter(type) method
• ui/src/components/NexusOnboardingWizard.tsx - Hermes probe on open, defaultAdapter state, optional directory, updated UI text
• ui/src/components/NewAgentDialog.tsx - Removed adapterType from AGENT_TEMPLATES, updated handleTemplateSelect

Decisions Made

• Probe route uses board auth only (no companyId) — adapter availability is an instance-level concern
• Probe failure is silent (catches error, keeps claude_local) — graceful degradation for missing adapter or network issues
• hermes_local makes directory optional, not required — Hermes runtime doesn't need cwd
• AGENT_TEMPLATES stripped of adapterType — /agents/new form is responsible for resolving the adapter default

Deviations from Plan

None - plan executed exactly as written.

Issues Encountered

None. Pre-existing TypeScript module resolution errors (missing @paperclipai/shared, @paperclipai/adapter-utils etc.) were already present in the codebase and unrelated to these changes.

Known Stubs

None. All data paths are wired — probeAdapter calls the real route, defaultAdapter flows into all three agent creates.

User Setup Required

None - no external service configuration required.

Next Phase Readiness

• Probe route is ready; Plan 02 can use it for any additional default provider logic
• NexusOnboardingWizard now self-selects hermes_local when Hermes is installed
• NewAgentDialog templates are adapter-neutral and ready for any future adapter default logic in /agents/new

---

Phase: 29-default-provider Completed: 2026-04-02