feat(cli): add beta background process execution tools

[sestinj]

Summary by cubic

Adds beta support for running terminal commands in the background with a new BackgroundProcessService and tools to monitor and manage them. Enables Bash run_in_background, incremental output reads, process listing, and cleanup on exit, gated behind --beta-persistent-terminal-tools.

• New Features

  • Bash: run_in_background parameter to start long-running commands without blocking.
  • BackgroundProcessService: spawns processes, tracks PID/status/exit code, buffers output (10k lines), max 10 concurrent, cleans up on exit, marks spawn errors as exited.
  • Tools: ReadBackgroundProcessOutput (incremental output with optional regex filter), ListProcesses, KillProcess.
  • CLI flag: --beta-persistent-terminal-tools to enable these tools; tools are registered only when the flag is set.
  • Docs: BACKGROUND_PROCESSES.md with usage and limitations.

• Migration

  • Start CLI with --beta-persistent-terminal-tools.
  • Use Bash({ command, run_in_background: true }) to start; then ReadBackgroundProcessOutput({ bash_id[, filter] }) to read logs; KillProcess({ bash_id }) to stop.
  • Processes are session-scoped and will be terminated on CLI exit.

^{Written for commit 74fd449. Summary will update automatically on new commits.}

[continue]

Keep this PR in a mergeable state →

Learn more

---

All Green is an AI agent that automatically:

✅ Addresses code review comments

✅ Fixes failing CI checks

✅ Resolves merge conflicts

[continue-development-app]

Keep this PR in a mergeable state →

Learn more

---

All Green is an AI agent that automatically:

✅ Addresses code review comments

✅ Fixes failing CI checks

✅ Resolves merge conflicts

[continue-development-app]

Keep this PR in a mergeable state →

Learn more

---

All Green is an AI agent that automatically:

✅ Addresses code review comments

✅ Fixes failing CI checks

✅ Resolves merge conflicts

[github-actions]

✅ Review Complete

Code Review Summary

⚠️ Continue configuration error. Please verify that the assistant exists in Continue Hub.

---

[continue]

📚 Documentation updates have been added in PR #9075

Created user-facing documentation for the beta background process execution feature, including:

• New /docs/cli/beta-background-processes.mdx page with usage examples and technical details
• Updated CLI overview to link to the new documentation
• Added page to the docs navigation structure

The documentation maintains consistency with existing CLI docs and focuses on practical usage patterns.

[continue]

🤖 All Green agent started: View agent

[cubic-dev-ai]

1 issue found across 13 files

Prompt for AI agents (all 1 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="extensions/cli/src/services/BackgroundProcessService.ts">

<violation number="1" location="extensions/cli/src/services/BackgroundProcessService.ts:209">
P1: The error handler doesn&#39;t update process status to &#39;exited&#39;. When a process fails to spawn (e.g., command not found), Node.js emits the &#39;error&#39; event but may not emit the &#39;close&#39; event. This leaves the process incorrectly marked as &#39;running&#39; indefinitely, which could also cause issues with the `runningCount` check in `startProcess` since failed processes would still count against `maxProcesses`.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[cubic-dev-ai]

P1: The error handler doesn't update process status to 'exited'. When a process fails to spawn (e.g., command not found), Node.js emits the 'error' event but may not emit the 'close' event. This leaves the process incorrectly marked as 'running' indefinitely, which could also cause issues with the runningCount check in startProcess since failed processes would still count against maxProcesses.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At extensions/cli/src/services/BackgroundProcessService.ts, line 209:

<comment>The error handler doesn&#39;t update process status to &#39;exited&#39;. When a process fails to spawn (e.g., command not found), Node.js emits the &#39;error&#39; event but may not emit the &#39;close&#39; event. This leaves the process incorrectly marked as &#39;running&#39; indefinitely, which could also cause issues with the `runningCount` check in `startProcess` since failed processes would still count against `maxProcesses`.</comment>

<file context>
@@ -0,0 +1,344 @@
+      this.emit(&quot;processExited&quot;, { id, exitCode: code });
+    });
+
+    child.on(&quot;error&quot;, (error) =&gt; {
+      logger.debug(`Background process ${id} error: ${error.message}`);
+      processInfo.stderrBuffer.append(`Process error: ${error.message}`);
</file context>

✅ Addressed in f2cf8fc

[continue]

Fixed - now updates process status to exited and emits processExited event

[continue]

@cubic-dev-ai This issue has been fixed in commit f2cf8fc. The error handler now properly updates the process status to exited, sets the exit code, updates state, and emits the processExited event when a spawn error occurs.

[Patrick-Erichsen]

Feels like the name could be more descriptive, eg ReadBackgroundProcessOutput

[Patrick-Erichsen]

Could we just use https://www.npmjs.com/package/ringbufferjs ?

[Patrick-Erichsen]

Probably should mention KillProcess and ListProcesses as well. Ideally just import the obj and use the name property to avoid drift.

Also wondering if it's worth providing an example flow in the description. In general wondering how well the agent will be able to follow the expected usage pattern here, were you able to test much? It feels reasonably complicated and there isn't much guidance for the agent to follow.