refactor: improve project architecture

[pedronauck]

Summary by CodeRabbit

• New Features

  • Added permission approval functionality for interactive workflows.
  • Enhanced memory consolidation and workspace integration capabilities.

• Refactoring

  • Consolidated API contracts and unified handler logic across HTTP and UDS transports.
  • Centralized session, workspace, and memory management interfaces for improved maintainability.

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

This PR consolidates transport-agnostic API contracts, core handler logic, and service interfaces into shared internal/api/core and internal/api/contract packages. Both HTTP and UDS transports are refactored to embed unified handler implementations. Daemon bootstrapping, CLI components, and config/utility layers are reorganized to use centralized definitions.

Changes

Cohort / File(s)	Summary
API Contract DTOs internal/api/contract/contract.go, internal/api/contract/contract_test.go	New canonical DTO types (SessionPayload, AgentPayload, MemoryWriteRequest, WorkspacePayload, etc.) with JSON field tags. Tests validate JSON shape and round-trip encoding behavior.
Core Conversion Helpers internal/api/core/conversions.go, internal/api/core/conversions_parsers_test.go	New conversion functions from domain types to contract payloads (SessionPayloadFromInfo, AgentPayloadFromDef, etc.). Tests validate payload mapping and query parsing.
Core API Interfaces & Types internal/api/core/interfaces.go, internal/api/core/payloads.go	New transport-facing interfaces (SessionManager, Observer, WorkspaceService, DreamTrigger, AgentLoader) and SSE envelope types (SSEMessage, FlushWriter, ObserveCursor).
Core Error & Response Handling internal/api/core/errors.go, internal/api/core/session_workspace.go, internal/api/core/session_workspace_internal_test.go	New RespondError function and status-mapping helpers. Unexported (private) validation/lookup functions for session/workspace operations.
Core HTTP Handlers internal/api/core/handlers.go, internal/api/core/handlers_test.go	New BaseHandlers type embedding all session/agent/observe/workspace/memory endpoints. HTTP methods for REST operations and SSE streaming with configurable polling.
Core Query Parsers & SSE internal/api/core/parsers.go, internal/api/core/sse.go, internal/api/core/more_coverage_test.go	Query parsing (ParseSessionEventQuery, ParseObserveCursor, ParseOptionalTime, etc.). SSE preparation, writing, and cursor-based filtering logic.
Core Memory Operations internal/api/core/memory.go, internal/api/core/memory_workspace_test.go	Memory handler methods (ListMemory, ReadMemory, WriteMemory, etc.) using contract request types. Tests verify memory scope resolution, workspace filtering, consolidation.
Core Workspace Handlers internal/api/core/workspaces.go	Workspace CRUD (Create, List, Get, Update, Delete, Resolve) with session/agent/skill payload attachment. Validation of absolute paths and workspace references.
HTTP API Server & Routes internal/api/httpapi/server.go, internal/api/httpapi/helpers_test.go	Server refactored to embed core.BaseHandlers. Removed local interfaces (SessionManager, Observer, etc.) in favor of core.\ aliases. Tests provide helper scaffolding for HTTP handler tests.
HTTP API Handlers internal/api/httpapi/prompt.go, internal/api/httpapi/sessions.go, internal/api/httpapi/static.go, internal/api/httpapi/handlers_test.go, internal/api/httpapi/handlers_error_test.go	Prompt streaming and session approval handlers delegate to core helpers. Stop handler now expects 204 No Content. Tests updated for renamed stub fields.
HTTP API Test Stubs & Contracts internal/api/httpapi/shared_test.go, internal/api/httpapi/prompt_contract_test.go, internal/api/httpapi/memory_test.go, internal/api/httpapi/stream_helpers_test.go, internal/api/httpapi/httpapi_integration_test.go	Type aliases binding test-level types to contract payloads. Tests verify transport-local schemas remain distinct from contract types. Memory/stream tests use core helpers.
UDS API Server & Routes internal/api/udsapi/server.go, internal/api/udsapi/routes.go, internal/api/udsapi/helpers_test.go	Server refactored identically to HTTP; embeds *core.BaseHandlers. RegisterRoutes wires all endpoints. Test helpers mirror HTTP counterparts.
UDS API Handlers internal/api/udsapi/prompt.go, internal/api/udsapi/sessions.go, internal/api/udsapi/shared_test.go, internal/api/udsapi/memory_test.go, internal/api/udsapi/stream_helpers_test.go, internal/api/udsapi/udsapi_integration_test.go, internal/api/udsapi/handlers_test.go, internal/api/udsapi/handlers_error_test.go	UDS-specific prompt/session handlers. Sessions.approveSession returns NotImplemented. Tests follow HTTP pattern with stub field renamings.
Shared Test Utilities internal/api/testutil/apitest.go, internal/api/testutil/apitest_test.go	Stub implementations (StubSessionManager, StubObserver, StubWorkspaceService) for core interfaces. Helpers: NewTestHomePaths, WriteAgentDef, PerformRequest, ParseSSE, DiscardLogger.
ACP Handler Refactoring internal/acp/handlers.go, internal/acp/handlers_test.go, internal/acp/rawjson.go	Added emitPermissionEvent helper centralizing permission event construction. New CloneRawMessage exported function replacing local cloneRawJSON. Tests added for emitPermissionEvent.
ACP Integration Tests internal/acp/client_integration_test.go, internal/acp/client_test.go	Context creation switched from local testContext(t) to testutil.Context(t). Added testutil import.
CLI Contracts & Client internal/cli/client.go, internal/cli/client_test.go	Record/request types converted to contract type aliases (CreateSessionRequest = contract.CreateSessionRequest, etc.). Tests verify alias parity and JSON encoding equivalence.
CLI Output Formatting internal/cli/format.go, internal/cli/agent.go, internal/cli/memory.go, internal/cli/observe.go, internal/cli/session.go, internal/cli/skill.go, internal/cli/workspace.go	New listBundle generic helper centralizing table/array rendering. Agent/memory/observe/session/skill/workspace list commands refactored to use listBundle.
CLI Tests internal/cli/agent_commands_test.go, internal/cli/session_test.go, internal/cli/render_test.go, internal/cli/memory_test.go, internal/cli/skill_test.go	New tests for agent list/info, session wait/stop/status/resume/prompt, listBundle rendering, memory commands. Context sources switched to testutil.Context.
CLI Daemon & Process internal/cli/daemon.go, internal/cli/daemon_wait_test.go, internal/cli/root.go, internal/cli/command_paths_test.go, internal/cli/helpers_test.go	Daemon status helper refactored to single daemonStatusWithState function. Removed local signalProcess/processAlive; now delegate to procutil.\*. New tests for daemon start/stop/wait flows.
Config & Home internal/config/home.go, internal/config/home_test.go, internal/config/agent.go, internal/config/agent_test.go	New ResolvePath and ResolveUserAgentsSkillsDir functions for path/skills resolution with injected HOME getter. ParseAgentDef now delegates to frontmatter.Decode. Tests verify CRLF normalization and name validation.
Daemon Bootstrapping internal/daemon/boot.go	New boot() method: validates context, enforces single-boot via state guards, loads config/layout, initializes logger/memory/skills, wires prompt providers, acquires lock, detects orphans, opens DB, builds workspace resolver, starts HTTP/UDS servers, writes daemon info, reconciles sessions.
Daemon Boundary Verification internal/daemon/boundary.go	New Boundaries() method and shouldVerifyBoundaries() helper verify import restrictions (preventing CLI/API/daemon internal modules from crossing boundaries) via go/parser walk and forbidden package list.
Daemon Orchestration internal/daemon/daemon.go, internal/daemon/daemon_test.go, internal/daemon/daemon_integration_test.go	SessionManager/Observer/DreamTrigger replaced with core.\* aliases. Registry narrowed to observe.Registry. Removed inline dream spawner/runtime; now uses consolidation.Runtime. Tests use testutil.Context; dream expectations updated.
Daemon Notifier & Lock internal/daemon/notifier.go, internal/daemon/lock.go	New notifierFanout type fan-outs session/agent notifications across multiple notifiers. Lock's process-liveness check now delegates to procutil.Alive.
Daemon Orphan Cleanup internal/daemon/orphan.go	New cleanupOrphans(), waitForProcessExit(), removeStaleSocket() helpers manage stale daemon processes via ps enumeration and SIGTERM/SIGKILL escalation.
Filesystem & Utility Packages internal/filesnap/filesnap.go, internal/filesnap/filesnap_test.go, internal/fileutil/atomic.go	New filesnap package: Snapshot struct with ModTime/Size, FromPath, Equal, Clone functions for filesystem state comparison. New fileutil: AtomicWriteFile for safe file replacement.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

This is a comprehensive architectural refactoring consolidating API contracts and core handler logic across multiple packages. The changes span transport-layer unification (HTTP/UDS), daemon bootstrapping/orchestration, CLI restructuring, configuration changes, and new utility packages. High heterogeneity: distinct reasoning required for contract definitions, interface consolidation, handler method migration, daemon state management, orphan cleanup, and test infrastructure updates. Logic density is substantial in boot.go, boundary.go, and orphan.go. Scope involves 80+ files across 10+ functional areas.

Possibly related PRs

• feat: new skills system #1: Related code-level changes to internal/config/home.go for adding/adjusting home and skills path resolution functions and fields (ResolvePath, ResolveUserAgentsSkillsDir).
• feat: use acp instead of stream raw json compozy#34: Related through ACP-centric types and agent/permission event plumbing including raw JSON handling (acp/rawjson.go CloneRawMessage, emitPermissionEvent refactoring).

Poem

🐰 Contracts unified, handlers consolidated,
Core logic shared where transports dwell,
Daemon boots with grace, boundaries blessed,
Files snap, utilities shine—architecture cast its spell! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pn/refac