refactor: enforce canonical server module ownership (#2744)

* chore: add server module boundary harness

* refactor: establish Studio server module foundation

* refactor: move Studio update behind module boundary

* refactor: move shared server infrastructure into Studio

* refactor: move Studio state into repositories

* refactor: classify common Studio services

* refactor: migrate Studio theme vertical slice

* refactor: migrate Studio network and app relay modules

* refactor: migrate Studio device networking slice

* refactor: migrate Studio social messages slice

* refactor: isolate coding agents module

* refactor: isolate Ekko agent module

* refactor: establish Hermes runtime history and kanban modules

* refactor: migrate Hermes profiles jobs bundles and files

* refactor: isolate Hermes bridge gateway and providers

* refactor: migrate Hermes control plane slices

* refactor: migrate Hermes skills plugins and files

* refactor: migrate runtime webhooks and monitoring slices

* refactor: centralize cross-agent webhooks pets and logs

* refactor: centralize Studio voice and media services

* refactor: isolate Hermes terminal socket

* refactor: migrate Studio workflow orchestration

* refactor: migrate Studio single chat runtime

* refactor: migrate Studio global agent runtime

* refactor: migrate Studio group chat runtime

* refactor: migrate Studio auth and context services

* refactor: migrate Studio session orchestration

* refactor: isolate Hermes profile model adapters

* refactor: complete server bootstrap boundaries

* refactor: enforce canonical server module ownership

* chore: consolidate server migration harness

* fix: preserve legacy App API compatibility

* fix: preserve Studio session listing semantics

* fix: retain delegated OpenAPI request bodies

Author: EKKOLearnAI

.github/workflows/build.yml

@@ -23,8 +23,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

AGENTS.md

@@ -11,6 +11,7 @@ and keep this file small enough to fit into every task context.
 - `docs/harness/validation.md` - which checks to run for each change type.
 - `docs/harness/worktree-runbook.md` - isolated local dev and test setup.
 - `docs/harness/pr-review.md` - self-review checklist before pushing.
+- `docs/harness/server-module-boundaries.md` - target backend modules, ownership, and dependency rules.
 
 ## Common Commands
 
@@ -38,6 +39,7 @@ Use the smallest relevant check while iterating. Before a broad PR, run
 ## Hard Rules
 
 - Keep routes thin: put request handling in controllers and reusable behavior in services.
+- Put new server code under `modules/studio`, `modules/hermes`, `modules/ekko`, or `modules/coding-agents`; compose modules only from `bootstrap`.
 - Keep Web UI state under `HERMES_WEB_UI_HOME` or `HERMES_WEBUI_STATE_DIR`.
 - Keep Hermes Agent state separate from Web UI state.
 - Register local API routes before proxy catch-all routes.

ARCHITECTURE.md

@@ -17,7 +17,7 @@ backend, and an Electron desktop distribution around Hermes Agent.
 
 1. The browser loads the Vite-built client from the Koa server.
 2. Client modules call API helpers from `packages/client/src/api`.
-3. Server routes in `packages/server/src/routes` wire HTTP paths to controllers.
+3. Server routes in `packages/server/src/modules/*/routes` wire HTTP paths to controllers.
 4. Controllers validate request concerns and delegate reusable behavior to services.
 5. Services own side effects: files, SQLite, Hermes profiles, subprocesses, bridges, and credentials.
 6. Long-running chat and group-chat flows use Socket.IO namespaces managed by server services.
@@ -36,17 +36,22 @@ should not duplicate server persistence rules.
 
 ## Server Structure
 
-- `routes/` registers HTTP and WebSocket entry points.
-- `controllers/` handles request-level behavior.
-- `services/` owns reusable IO, domain behavior, external process calls, and integration logic.
-- `db/` owns SQLite schemas and stores.
-- `middleware/` owns request middleware such as user auth.
-- `shared/` contains cross-server constants and helpers.
+Server code is separated by business ownership under `modules/studio`,
+`modules/hermes`, `modules/ekko`, and `modules/coding-agents`; concrete module
+composition belongs in `bootstrap`.
+See `docs/harness/server-module-boundaries.md` for the complete target tree,
+ownership decisions, allowed dependency matrix, and migration rules.
+
+- Module `routes/` register HTTP entry points; `sockets/` own Socket.IO transports.
+- Module `controllers/` handle request-level behavior.
+- Module `services/` own reusable IO, domain behavior, processes, and integrations.
+- Studio `repositories/` and `infrastructure/` own application persistence.
+- Studio `middleware/legacy-app-api.ts` is the only old-App URL compatibility map.
 
 Architecture rules:
 
 - Register local API routes before proxy catch-all routes.
-- Keep auth behavior centralized in `packages/server/src/services/auth.ts`.
+- Keep auth behavior under `packages/server/src/modules/studio/services/auth`.
 - Prefer `execFile` or `spawn` with argument arrays over shell command strings.
 - Use structured file and YAML/JSON parsers when editing structured data.
 

bin/hermes-studio-mcp.mjs

@@ -303,7 +303,7 @@ function validateRequiredObjectFields(schema, value, location) {
 }
 
 async function validateApiRequest(method, path, args) {
-  if (pathWithoutQuery(path) === '/api/openapi.json' || pathWithoutQuery(path) === '/api/hermes/openapi.json') return null
+  if (pathWithoutQuery(path) === '/api/openapi.json') return null
   const openapi = await openApiDocument(withAuthArgs(args))
   const match = findOpenApiOperation(openapi, method, path)
   if (!match) return `Unknown endpoint in OpenAPI document: ${method} ${pathWithoutQuery(path)}`
@@ -923,7 +923,7 @@ const tools = [
     inputSchema: inputSchema({
         path: {
           type: 'string',
-          description: 'Optional exact endpoint path filter for on-demand details, for example /api/chat-run/runs.',
+          description: 'Optional exact endpoint path filter for on-demand details, for example /api/studio/chat-run/runs.',
         },
         method: {
           type: 'string',
@@ -943,7 +943,7 @@ const tools = [
   {
     name: 'hermes_studio_api_request',
     toolset: 'api',
-    description: 'Execute a Hermes Studio operation by calling an endpoint path. Use hermes_studio_api_openapi_get first as the operation manual to inspect method, parameters, requestBody, and responses. Do not use /api/chat-run/* or /api/hermes/sessions/* as an internal delegation mechanism.',
+    description: 'Execute a Hermes Studio operation by calling an endpoint path. Use hermes_studio_api_openapi_get first as the operation manual to inspect method, parameters, requestBody, and responses. Do not use /api/studio/chat-run/* or /api/studio/sessions/* as an internal delegation mechanism.',
     inputSchema: inputSchema({
         method: {
           type: 'string',
@@ -952,7 +952,7 @@ const tools = [
         },
         path: {
           type: 'string',
-          description: 'Relative Hermes Studio endpoint path from the operation manual, for example /api/hermes/sessions?limit=20. Full URLs and // paths are rejected.',
+          description: 'Relative Hermes Studio endpoint path from the operation manual, for example /api/studio/sessions?limit=20. Full URLs and // paths are rejected.',
         },
         body: {
           type: ['object', 'array', 'string', 'number', 'boolean', 'null'],
@@ -1814,7 +1814,7 @@ async function callTool(name, args = {}) {
       return jsonText(await requestEnvelope(path, options))
     }
     case 'hermes_studio_use_chat_run':
-      return jsonText(await request('/api/chat-run/runs', withAuthArgs(args, {
+      return jsonText(await request('/api/studio/chat-run/runs', withAuthArgs(args, {
         method: 'POST',
         body: pickDefined(args, [
           'input',
@@ -1838,34 +1838,34 @@ async function callTool(name, args = {}) {
         ]),
       })))
     case 'hermes_studio_use_sessions_list':
-      return jsonText(await request('/api/hermes/sessions', withAuthArgs(args, {
+      return jsonText(await request('/api/studio/sessions', withAuthArgs(args, {
         query: pickDefined(args, ['limit', 'source']),
       })))
     case 'hermes_studio_use_sessions_count':
-      return jsonText(await request('/api/hermes/sessions/count', withAuthArgs(args, {
+      return jsonText(await request('/api/studio/sessions/count', withAuthArgs(args, {
         query: pickDefined(args, ['source']),
       })))
     case 'hermes_studio_use_usage_stats':
-      return jsonText(await request('/api/hermes/usage/stats', withAuthArgs(args, {
+      return jsonText(await request('/api/studio/usage/stats', withAuthArgs(args, {
         query: pickDefined(args, ['days']),
       })))
     case 'hermes_studio_use_session_get':
-      return jsonText(await request(`/api/hermes/sessions/${encodeURIComponent(args.session_id)}`, withAuthArgs(args)))
+      return jsonText(await request(`/api/studio/sessions/${encodeURIComponent(args.session_id)}`, withAuthArgs(args)))
     case 'hermes_studio_use_session_messages':
-      return jsonText(await request(`/api/hermes/sessions/conversations/${encodeURIComponent(args.session_id)}/messages`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/sessions/conversations/${encodeURIComponent(args.session_id)}/messages`, withAuthArgs(args, {
         query: args.include_internal ? { humanOnly: '0' } : undefined,
       })))
     case 'hermes_studio_use_session_context':
       return jsonText(cleanSessionContextPayload(
-        await request(`/api/hermes/sessions/${encodeURIComponent(args.session_id)}/context`, withAuthArgs(args)),
+        await request(`/api/studio/sessions/${encodeURIComponent(args.session_id)}/context`, withAuthArgs(args)),
         args,
       ))
     case 'hermes_studio_use_session_delete':
-      return jsonText(await request(`/api/hermes/sessions/${encodeURIComponent(args.session_id)}`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/sessions/${encodeURIComponent(args.session_id)}`, withAuthArgs(args, {
         method: 'DELETE',
       })))
     case 'hermes_studio_use_session_rename':
-      return jsonText(await request(`/api/hermes/sessions/${encodeURIComponent(args.session_id)}/rename`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/sessions/${encodeURIComponent(args.session_id)}/rename`, withAuthArgs(args, {
         method: 'POST',
         body: { title: args.title },
       })))
@@ -1901,16 +1901,16 @@ async function callTool(name, args = {}) {
       })))
     case 'hermes_studio_use_worker_status':
       return jsonText(summarizeWorkerRuntime(
-        await request('/api/hermes/performance/runtime', withAuthArgs(args)),
+        await request('/api/studio/performance/runtime', withAuthArgs(args)),
       ))
     case 'hermes_studio_use_workflows_list':
-      return jsonText(await request('/api/hermes/workflows', withAuthArgs(args, {
+      return jsonText(await request('/api/studio/workflows', withAuthArgs(args, {
         query: pickDefined(args, ['profile']),
       })))
     case 'hermes_studio_use_workflow_get':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}`, withAuthArgs(args)))
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}`, withAuthArgs(args)))
     case 'hermes_studio_use_workflow_create':
-      return jsonText(await request('/api/hermes/workflows', withAuthArgs(args, {
+      return jsonText(await request('/api/studio/workflows', withAuthArgs(args, {
         method: 'POST',
         body: pickDefined(args, [
           'name',
@@ -1922,7 +1922,7 @@ async function callTool(name, args = {}) {
         ]),
       })))
     case 'hermes_studio_use_workflow_update':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}`, withAuthArgs(args, {
         method: 'PATCH',
         body: pickDefined(args, [
           'name',
@@ -1933,15 +1933,15 @@ async function callTool(name, args = {}) {
         ]),
       })))
     case 'hermes_studio_use_workflow_delete':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}`, withAuthArgs(args, {
         method: 'DELETE',
       })))
     case 'hermes_studio_use_workflow_runs_list':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}/runs`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}/runs`, withAuthArgs(args, {
         query: pickDefined(args, ['limit']),
       })))
     case 'hermes_studio_use_workflow_run_start':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}/run`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}/run`, withAuthArgs(args, {
         method: 'POST',
         body: pickDefined(args, [
           'start_node_ids',
@@ -1950,11 +1950,11 @@ async function callTool(name, args = {}) {
         ]),
       })))
     case 'hermes_studio_use_workflow_run_stop':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}/runs/${encodeURIComponent(args.run_id)}/stop`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}/runs/${encodeURIComponent(args.run_id)}/stop`, withAuthArgs(args, {
         method: 'POST',
       })))
     case 'hermes_studio_use_workflow_rerun_node':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}/runs/${encodeURIComponent(args.run_id)}/rerun-from-node`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}/runs/${encodeURIComponent(args.run_id)}/rerun-from-node`, withAuthArgs(args, {
         method: 'POST',
         body: pickDefined(args, [
           'node_id',
@@ -1963,7 +1963,7 @@ async function callTool(name, args = {}) {
         ]),
       })))
     case 'hermes_studio_use_workflow_run_delete':
-      return jsonText(await request(`/api/hermes/workflows/${encodeURIComponent(args.workflow_id)}/runs/${encodeURIComponent(args.run_id)}`, withAuthArgs(args, {
+      return jsonText(await request(`/api/studio/workflows/${encodeURIComponent(args.workflow_id)}/runs/${encodeURIComponent(args.run_id)}`, withAuthArgs(args, {
         method: 'DELETE',
       })))
     case 'hermes_studio_lan_devices_list':

docs/agent-runner.md

@@ -1,6 +1,6 @@
 # Coding Agent services
 
-`packages/server/src/services/coding-agents/` is the implementation home for
+`packages/server/src/modules/coding-agents/` is the implementation home for
 managed Claude Code, Codex, and Pi runs. The services share one canonical event
 pipeline, one stream subscription model, and one persistence path while keeping
 agent-specific process and protocol behavior in named subdirectories.
@@ -353,6 +353,3 @@ Minimum checks for each phase:
 - `npm run test -- tests/server/run-chat-content-blocks.test.ts` when touching
   chat input conversion.
 - `npm run build` before merging shared TypeScript contracts.
-
-For chat session behavior changes, also add a fragment under
-`docs/chat-chain-changes/` according to the repository validation guide.

docs/app-relay.md

@@ -115,7 +115,7 @@ existing takeover behavior so a restarted desktop can recover stale connections.
 
 ## Forwarded protocols
 
-- HTTP RPC accepts Studio `/api/**`, `/upload`, and `/health` paths.
+- HTTP RPC accepts Studio `/api/**` and `/health` paths.
 - Request headers, methods, paths, and Socket.IO client events are allowlisted.
 - Request and response bodies are capped at 20 MiB.
 - Socket RPC accepts `/chat-run` and `/group-chat` only.