Add progress reporting to more handlers and extend guide where progress reporting should be used

Author: Aksem

docs/guides/designing-actions.md

@@ -207,6 +207,23 @@ Partial results and progress are orthogonal:
 
 Do not put status messages into partial results just to show activity, and do not use progress updates to smuggle result data. If the client should be able to consume it as structured output, it belongs in the result. If it only helps the user understand what the action is currently doing, it belongs in progress.
 
+### Progress must reflect the user's unit of work
+
+When a user sees "file X formatted" or "file X linted", they expect **all** handlers to have been applied to that file — not that one particular handler finished its pass. The progress grain must match the user's mental model, not the handler execution model.
+
+This has a direct consequence on how multi-file, multi-handler actions structure their execution:
+
+| Execution model | Handler order | Progress grain | User perception |
+| --- | --- | --- | --- |
+| **Per-item** (iterable payload) | All handlers run on file 1, then all on file 2, … | Per-file, after all handlers | "file X done" ✓ |
+| **Per-handler batch** (flat payload) | Handler A on all files, then handler B on all files, … | Per-handler pass, or only at end | "handler A done" or no useful progress ✗ |
+
+**Rule: when an action processes multiple items through multiple handlers and reports file-level progress, prefer the iterable payload model.** This ensures each partial result — and each progress step — represents a fully processed item.
+
+The per-handler batch model is appropriate when handlers genuinely need the full file list at once (e.g. a whole-program analysis pass), or when there is only a single handler. But if the action chains several independent per-file tools (formatter A → formatter B → save), the iterable model gives correct progress semantics by construction.
+
+**Corollary: single-tool handlers in an iterable-payload action should not report their own progress.** The parent action already advances progress after all handlers complete for each item. A handler reporting "processed file X" independently would be redundant at best — and misleading at worst, since from the user's perspective the file is not done until every handler has run. Handlers should focus on doing their work and returning a result; the orchestrating action owns the progress narrative.
+
 ### Action boundaries stay explicit
 
 When one action delegates to another, neither partial results nor progress should be treated as something that "just flows through".

finecode_builtin_handlers/src/finecode_builtin_handlers/create_envs_dispatch.py

@@ -41,25 +41,28 @@ async def run(
         )
 
         tasks: list[asyncio.Task[create_envs_action.CreateEnvsRunResult]] = []
-        try:
-            async with asyncio.TaskGroup() as tg:
-                for env in run_context.envs:
-                    task = tg.create_task(
-                        self.action_runner.run_action(
-                            action=create_env_action_instance,
-                            payload=create_env_action.CreateEnvRunPayload(
-                                env=env,
-                                recreate=payload.recreate,
-                            ),
-                            meta=run_context.meta,
-                        )
-                    )
-                    tasks.append(task)
-        except ExceptionGroup as eg:
-            error_str = ". ".join([str(e) for e in eg.exceptions])
-            raise code_action.ActionFailedException(error_str) from eg
+        async with run_context.progress("Creating environments", total=len(run_context.envs)) as progress:
+            async def _create_and_advance(env):
+                result = await self.action_runner.run_action(
+                    action=create_env_action_instance,
+                    payload=create_env_action.CreateEnvRunPayload(
+                        env=env,
+                        recreate=payload.recreate,
+                    ),
+                    meta=run_context.meta,
+                )
+                await progress.advance(message=f"Created {env.name}")
+                return result
 
-        errors: list[str] = []
-        for task in tasks:
-            errors += task.result().errors
-        return create_envs_action.CreateEnvsRunResult(errors=errors)
+            try:
+                async with asyncio.TaskGroup() as tg:
+                    for env in run_context.envs:
+                        tasks.append(tg.create_task(_create_and_advance(env)))
+            except ExceptionGroup as eg:
+                error_str = ". ".join([str(e) for e in eg.exceptions])
+                raise code_action.ActionFailedException(error_str) from eg
+
+            errors: list[str] = []
+            for task in tasks:
+                errors += task.result().errors
+            return create_envs_action.CreateEnvsRunResult(errors=errors)

finecode_builtin_handlers/src/finecode_builtin_handlers/format.py

@@ -66,14 +66,18 @@ async def run(
         format_files_action_instance = self.action_runner.get_action_by_source(
             format_files_action.FormatFilesAction
         )
-        async for partial in self.action_runner.run_action_iter(
-            action=format_files_action_instance,
-            payload=format_files_action.FormatFilesRunPayload(
-                file_paths=file_uris,
-                save=payload.save,
-            ),
-            meta=run_meta,
-        ):
-            yield format_action.FormatRunResult(
-                result_by_file_path=partial.result_by_file_path
-            )
+        async with run_context.progress("Formatting files", total=len(file_uris)) as progress:
+            async for partial in self.action_runner.run_action_iter(
+                action=format_files_action_instance,
+                payload=format_files_action.FormatFilesRunPayload(
+                    file_paths=file_uris,
+                    save=payload.save,
+                ),
+                meta=run_meta,
+            ):
+                files = list(partial.result_by_file_path.keys())
+                msg = str(files[0]) if files else None
+                await progress.advance(message=msg)
+                yield format_action.FormatRunResult(
+                    result_by_file_path=partial.result_by_file_path
+                )

finecode_builtin_handlers/src/finecode_builtin_handlers/install_env_install_deps.py

@@ -45,42 +45,45 @@ async def run(
             install_deps_in_env_action.InstallDepsInEnvAction,
         )
 
-        deps_groups = project_def.get("dependency-groups", {})
-        env_raw_deps = deps_groups.get(env.name, [])
-        env_deps_config = (
-            project_def.get("tool", {})
-            .get("finecode", {})
-            .get("env", {})
-            .get(env.name, {})
-            .get("dependencies", {})
-        )
-        project_def_path = resource_uri_to_path(env.project_def_path)
-        dependencies: list[dict] = []
-        process_raw_deps(
-            env_raw_deps,
-            env_deps_config,
-            dependencies,
-            deps_groups,
-            project_def_path=project_def_path,
-        )
+        async with run_context.progress(f"Installing {env.name}") as progress:
+            await progress.report("Reading configuration")
+            deps_groups = project_def.get("dependency-groups", {})
+            env_raw_deps = deps_groups.get(env.name, [])
+            env_deps_config = (
+                project_def.get("tool", {})
+                .get("finecode", {})
+                .get("env", {})
+                .get(env.name, {})
+                .get("dependencies", {})
+            )
+            project_def_path = resource_uri_to_path(env.project_def_path)
+            dependencies: list[dict] = []
+            process_raw_deps(
+                env_raw_deps,
+                env_deps_config,
+                dependencies,
+                deps_groups,
+                project_def_path=project_def_path,
+            )
 
-        install_deps_payload = install_deps_in_env_action.InstallDepsInEnvRunPayload(
-            env_name=env.name,
-            venv_dir_path=env.venv_dir_path,
-            project_dir_path=path_to_resource_uri(project_def_path.parent),
-            dependencies=[
-                install_deps_in_env_action.Dependency(
-                    name=dep["name"],
-                    version_or_source=dep["version_or_source"],
-                    editable=dep["editable"],
-                )
-                for dep in dependencies
-            ],
-        )
+            install_deps_payload = install_deps_in_env_action.InstallDepsInEnvRunPayload(
+                env_name=env.name,
+                venv_dir_path=env.venv_dir_path,
+                project_dir_path=path_to_resource_uri(project_def_path.parent),
+                dependencies=[
+                    install_deps_in_env_action.Dependency(
+                        name=dep["name"],
+                        version_or_source=dep["version_or_source"],
+                        editable=dep["editable"],
+                    )
+                    for dep in dependencies
+                ],
+            )
 
-        result = await self.action_runner.run_action(
-            action=install_deps_in_env_action_instance,
-            payload=install_deps_payload,
-            meta=run_context.meta,
-        )
-        return InstallEnvsRunResult(errors=result.errors)
+            await progress.report("Installing dependencies")
+            result = await self.action_runner.run_action(
+                action=install_deps_in_env_action_instance,
+                payload=install_deps_payload,
+                meta=run_context.meta,
+            )
+            return InstallEnvsRunResult(errors=result.errors)

finecode_builtin_handlers/src/finecode_builtin_handlers/install_envs_dispatch.py

@@ -43,24 +43,25 @@ async def run(
         tasks: list[
             asyncio.Task[install_envs_action.InstallEnvsRunResult]
         ] = []
-        try:
-            async with asyncio.TaskGroup() as tg:
-                for env in run_context.envs:
-                    task = tg.create_task(
-                        self.action_runner.run_action(
-                            action=install_env_action_instance,
-                            payload=install_env_action.InstallEnvRunPayload(
-                                env=env,
-                            ),
-                            meta=run_context.meta,
-                        )
-                    )
-                    tasks.append(task)
-        except ExceptionGroup as eg:
-            error_str = ". ".join([str(e) for e in eg.exceptions])
-            raise code_action.ActionFailedException(error_str) from eg
+        async with run_context.progress("Installing environments", total=len(run_context.envs)) as progress:
+            async def _install_and_advance(env):
+                result = await self.action_runner.run_action(
+                    action=install_env_action_instance,
+                    payload=install_env_action.InstallEnvRunPayload(env=env),
+                    meta=run_context.meta,
+                )
+                await progress.advance(message=f"Installed {env.name}")
+                return result
 
-        errors: list[str] = []
-        for task in tasks:
-            errors += task.result().errors
-        return install_envs_action.InstallEnvsRunResult(errors=errors)
+            try:
+                async with asyncio.TaskGroup() as tg:
+                    for env in run_context.envs:
+                        tasks.append(tg.create_task(_install_and_advance(env)))
+            except ExceptionGroup as eg:
+                error_str = ". ".join([str(e) for e in eg.exceptions])
+                raise code_action.ActionFailedException(error_str) from eg
+
+            errors: list[str] = []
+            for task in tasks:
+                errors += task.result().errors
+            return install_envs_action.InstallEnvsRunResult(errors=errors)