Start only required runners in CLI if projects are provided

Author: Aksem

docs/wm-protocol.md

@@ -114,14 +114,26 @@ and optionally starts extension runners.
 **Params:**
 
 ```json
-{"dir_path": "/path/to/workspace", "start_runners": true}
+{"dir_path": "/path/to/workspace", "start_runners": true, "projects": ["my_project"]}
 ```
 
 `start_runners` is optional (default: `true`). When `false`, the server reads
 configs and collects actions without starting any extension runners. Use this
 when runner environments may not exist yet (e.g. before running `prepare-envs`).
 Actions are still available in the result so clients can validate the workspace.
 
+`projects` is optional. When provided, only the listed projects (by name) will
+be config-initialized and have their runners started. All other projects in the
+directory are still discovered (added to workspace state) but skipped for
+initialization. This avoids the cost of reading configs and spawning runner
+processes for projects that are not needed.
+
+Calling `workspace/addDir` again for the same `dir_path` with a different
+`projects` filter (or with `projects` omitted) will initialize the previously
+skipped projects — the call is **incremental**, not idempotent. Only projects
+that have not yet been config-initialized are processed on each call. This makes
+it safe to issue a filtered call followed by an unfiltered one.
+
 **Result:**
 
 ```json
@@ -132,6 +144,9 @@ Actions are still available in the result so clients can validate the workspace.
 }
 ```
 
+The `projects` list contains only the projects initialized during **this call**,
+not all projects in the workspace.
+
 `status` values: `"CONFIG_VALID"`, `"CONFIG_INVALID"`
 
 ---

mkdocs.yml

@@ -80,5 +80,5 @@ nav:
       - LSP and MCP Architecture: reference/lsp-mcp-architecture.md
   - Development:
       - Overview: development.md
-      - API Protocol: api-protocol.md
+      - WM Protocol: wm-protocol.md
       - Developing FineCode: guides/developing-finecode.md

src/finecode/cli_app/commands/dump_config_cmd.py

@@ -30,7 +30,7 @@ async def dump_config(
         client = ApiClient()
         await client.connect("127.0.0.1", port)
         try:
-            result = await client.add_dir(workdir_path)
+            result = await client.add_dir(workdir_path, projects=[project_name])
             projects = result.get("projects", [])
             project = next(
                 (p for p in projects if p["name"] == project_name), None

src/finecode/cli_app/commands/run_cmd.py

@@ -53,9 +53,10 @@ async def run_actions(
                         "Warning: --config overrides are ignored in --shared-server mode. ",
                         err=True,
                     )
-            # TODO: could it be optimized: if projects are provided, parse only them?
-            # the same also in other CLI commands
-            await client.add_dir(workdir_path)
+            await client.add_dir(
+                workdir_path,
+                projects=projects_names if own_server else None,
+            )
 
             params_by_project: dict[str, dict[str, typing.Any]] = {}
             if map_payload_fields:

src/finecode/wm_client.py

@@ -236,17 +236,27 @@ async def run_action(
             body["params"] = params
         return await self.request("actions/run", body)
 
-    async def add_dir(self, dir_path: pathlib.Path, start_runners: bool = True) -> dict:
+    async def add_dir(
+        self,
+        dir_path: pathlib.Path,
+        start_runners: bool = True,
+        projects: list[str] | None = None,
+    ) -> dict:
         """Add a workspace directory. Returns {projects: [...]}.
 
         When ``start_runners=False`` the server reads configs and collects
         actions without starting any extension runners.  Use this when runner
         environments may not exist yet (e.g. before ``prepare-envs``).
+
+        When ``projects`` is provided, only those projects (by name) will have
+        their configs read and runners started — the rest are still discovered
+        but not initialised.  Only use this in own-server mode where the server
+        lifetime matches a single CLI invocation.
         """
-        return await self.request(
-            "workspace/addDir",
-            {"dir_path": str(dir_path), "start_runners": start_runners},
-        )
+        body: dict = {"dir_path": str(dir_path), "start_runners": start_runners}
+        if projects is not None:
+            body["projects"] = projects
+        return await self.request("workspace/addDir", body)
 
     async def start_runners(self, projects: list[str] | None = None) -> None:
         """Start extension runners for all (or specified) projects.

src/finecode/wm_server/wm_server.py

@@ -249,6 +249,11 @@ async def _handle_add_dir(
         When false, configs are read and actions collected without starting any
         runners. Useful when runner environments may not exist yet (e.g. before
         running prepare-envs).
+      projects: list[str] | null - optional list of project names to initialize.
+        Projects not in this list are discovered but not config-initialized or
+        started. Omit (or pass null) to initialize all projects.
+        Calling add_dir again for the same dir with a different filter (or no
+        filter) will initialize the previously skipped projects.
     """
     from finecode.wm_server.config import collect_actions, read_configs
     from finecode.wm_server.runner import runner_manager
@@ -257,23 +262,38 @@ async def _handle_add_dir(
     params = params or {}
     dir_path = pathlib.Path(params["dir_path"])
     start_runners: bool = params.get("start_runners", True)
+    projects_filter: set[str] | None = (
+        set(params["projects"]) if params.get("projects") else None
+    )
     logger.trace(f"Add ws dir: {dir_path}")
 
-    if dir_path in ws_context.ws_dirs_paths:
-        return {"projects": []}
+    if dir_path not in ws_context.ws_dirs_paths:
+        ws_context.ws_dirs_paths.append(dir_path)
+
+    # Discover new projects in this dir (idempotent — skips already-known ones).
+    await read_configs.read_projects_in_dir(dir_path, ws_context)
+
+    # Collect all projects in this dir that haven't been config-initialized yet.
+    # This covers both newly discovered projects and ones that were filtered out
+    # by a previous add_dir call with a projects filter.
+    projects_to_init = [
+        p for p in ws_context.ws_projects.values()
+        if p.dir_path.is_relative_to(dir_path)
+        and p.dir_path not in ws_context.ws_projects_raw_configs
+    ]
 
-    ws_context.ws_dirs_paths.append(dir_path)
-    new_projects = await read_configs.read_projects_in_dir(dir_path, ws_context)
+    if projects_filter is not None:
+        projects_to_init = [p for p in projects_to_init if p.name in projects_filter]
 
-    for project in new_projects:
+    for project in projects_to_init:
         await read_configs.read_project_config(
             project=project, ws_context=ws_context, resolve_presets=False
         )
 
     if not start_runners:
         # Collect actions directly from raw config without needing runners.
         from finecode.wm_server.config import config_models
-        for project in new_projects:
+        for project in projects_to_init:
             if project.status == domain.ProjectStatus.CONFIG_VALID:
                 try:
                     collect_actions.collect_actions(
@@ -283,11 +303,11 @@ async def _handle_add_dir(
                     logger.warning(
                         f"Failed to collect actions for {project.name}: {exc.message}"
                     )
-        return {"projects": [_project_to_dict(p) for p in new_projects]}
+        return {"projects": [_project_to_dict(p) for p in projects_to_init]}
 
     try:
         await runner_manager.start_runners_with_presets(
-            projects=new_projects,
+            projects=projects_to_init,
             ws_context=ws_context,
             initialize_all_handlers=True,
         )
@@ -300,12 +320,12 @@ async def _handle_add_dir(
 
     # If config overrides were set before this addDir call (e.g. standalone CLI mode),
     # apply them to the newly discovered projects and push to their running runners.
-    if ws_context.handler_config_overrides and new_projects:
+    if ws_context.handler_config_overrides and projects_to_init:
         action_names = list(ws_context.handler_config_overrides.keys())
-        _apply_config_overrides_to_projects(new_projects, action_names, ws_context.handler_config_overrides)
+        _apply_config_overrides_to_projects(projects_to_init, action_names, ws_context.handler_config_overrides)
         try:
             async with asyncio.TaskGroup() as tg:
-                for project in new_projects:
+                for project in projects_to_init:
                     runners = ws_context.ws_projects_extension_runners.get(project.dir_path, {})
                     for runner in runners.values():
                         if runner.status == RunnerStatus.RUNNING:
@@ -320,7 +340,7 @@ async def _handle_add_dir(
             for exc in eg.exceptions:
                 logger.warning(f"Failed to push config update to runner: {exc}")
 
-    return {"projects": [_project_to_dict(p) for p in new_projects]}
+    return {"projects": [_project_to_dict(p) for p in projects_to_init]}
 
 
 async def _handle_remove_dir(