cleveragents/cleveragents-core

Fork 3

UAT: `agents server` missing `start` subcommand for background daemon mode — only foreground `serve` is implemented #3548

New issue

Open

opened 2026-04-05 19:17:31 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 19:17:31 +00:00

Owner

Metadata

Branch: fix/server-start-daemon-subcommand
Commit Message: fix(cli): add missing \agents server start` background daemon subcommand`
Milestone: None (backlog — see note below)
Parent Epic: #399

Backlog note: This issue was discovered during autonomous operation
on milestone v3.5.0 (M6). It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Summary

The agents server command group in src/cleveragents/cli/commands/server.py implements connect, status, and serve (foreground) subcommands, but is missing the start subcommand for running the server as a background daemon process.

Expected Behavior (from spec)

The spec describes two ways to start the server:

agents server serve — starts the server in the foreground (implemented ✅)
agents server start — starts the server in the background as a daemon (missing ❌)

The start command is the recommended production deployment mode, allowing the server to run as a background process while the user continues to use the terminal.

Actual Behavior

Running agents server start produces:

Error: No such command 'start'.

Only agents server serve is available for starting the server, which blocks the terminal.

Code Location

src/cleveragents/cli/commands/server.py — missing @app.command("start") function

Expected Command Behavior

agents server start [--host HOST] [--port PORT] [--workers N] [--log-level LEVEL] [--pid-file PATH]

Should:

Start the ASGI server as a background daemon process
Write the PID to a file (default: ~/.cleveragents/server.pid)
Print the server URL and PID on success
Return immediately (non-blocking)

Spec References

The spec describes agents server start as the background daemon mode for the CleverAgents server
spec §Server Deployment: describes Docker/Kubernetes deployment, implying the server must be startable as a background process

Subtasks

Write failing Behave unit tests (BDD/Gherkin) for the start subcommand (TDD — tests first)
Implement @app.command("start") in src/cleveragents/cli/commands/server.py with full static type annotations
Implement daemon process forking logic (detach from terminal, redirect stdio)
Implement PID file management: write PID on start, validate no existing process before starting
Add --pid-file PATH option (default: ~/.cleveragents/server.pid)
Print server URL and PID to stdout on successful daemon launch
Write Robot Framework integration test for agents server start / agents server stop round-trip
Update CLI help text and any relevant documentation

Definition of Done

agents server start starts the ASGI server as a non-blocking background daemon process
PID is written to ~/.cleveragents/server.pid by default (overridable via --pid-file)
Server URL and PID are printed to stdout on successful launch
Command returns immediately (non-blocking) — terminal is not held
Running agents server start when a server is already running produces a clear error (not a silent duplicate)
All new code has complete static type annotations passing nox -e typecheck
All nox stages pass (nox / nox -s ci)
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/server-start-daemon-subcommand` - **Commit Message**: `fix(cli): add missing \`agents server start\` background daemon subcommand` - **Milestone**: None (backlog — see note below) - **Parent Epic**: #399 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.0 (M6). It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- ## Summary The `agents server` command group in `src/cleveragents/cli/commands/server.py` implements `connect`, `status`, and `serve` (foreground) subcommands, but is missing the `start` subcommand for running the server as a background daemon process. ## Expected Behavior (from spec) The spec describes two ways to start the server: - `agents server serve` — starts the server in the foreground (implemented ✅) - `agents server start` — starts the server in the background as a daemon (missing ❌) The `start` command is the recommended production deployment mode, allowing the server to run as a background process while the user continues to use the terminal. ## Actual Behavior Running `agents server start` produces: ``` Error: No such command 'start'. ``` Only `agents server serve` is available for starting the server, which blocks the terminal. ## Code Location - `src/cleveragents/cli/commands/server.py` — missing `@app.command("start")` function ## Expected Command Behavior ``` agents server start [--host HOST] [--port PORT] [--workers N] [--log-level LEVEL] [--pid-file PATH] ``` Should: 1. Start the ASGI server as a background daemon process 2. Write the PID to a file (default: `~/.cleveragents/server.pid`) 3. Print the server URL and PID on success 4. Return immediately (non-blocking) ## Spec References - The spec describes `agents server start` as the background daemon mode for the CleverAgents server - spec §Server Deployment: describes Docker/Kubernetes deployment, implying the server must be startable as a background process --- ## Subtasks - [ ] Write failing Behave unit tests (BDD/Gherkin) for the `start` subcommand (TDD — tests first) - [ ] Implement `@app.command("start")` in `src/cleveragents/cli/commands/server.py` with full static type annotations - [ ] Implement daemon process forking logic (detach from terminal, redirect stdio) - [ ] Implement PID file management: write PID on start, validate no existing process before starting - [ ] Add `--pid-file PATH` option (default: `~/.cleveragents/server.pid`) - [ ] Print server URL and PID to stdout on successful daemon launch - [ ] Write Robot Framework integration test for `agents server start` / `agents server stop` round-trip - [ ] Update CLI help text and any relevant documentation ## Definition of Done - [ ] `agents server start` starts the ASGI server as a non-blocking background daemon process - [ ] PID is written to `~/.cleveragents/server.pid` by default (overridable via `--pid-file`) - [ ] Server URL and PID are printed to stdout on successful launch - [ ] Command returns immediately (non-blocking) — terminal is not held - [ ] Running `agents server start` when a server is already running produces a clear error (not a silent duplicate) - [ ] All new code has complete static type annotations passing `nox -e typecheck` - [ ] All nox stages pass (`nox` / `nox -s ci`) - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 19:17:45 +00:00

#399 Epic: Post-MVP Server & Clients

freemo referenced this issue

2026-04-05 19:18:24 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo commented

2026-04-05 19:34:25 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — The serve (foreground) command exists and is functional. The start (daemon) command is a production deployment convenience, not a blocker for development or testing workflows.
Milestone: v3.8.0 — Server deployment features belong to the Post-MVP Server milestone.
Story Points: 5 — L — Requires daemon process forking, PID file management, signal handling, and integration tests. Moderate complexity with OS-level concerns.
MoSCoW: Should Have — Background daemon mode is important for production deployment but not strictly essential for milestone demos or development workflows. The foreground serve command covers all functional requirements.
Parent Epic: #399 (Post-MVP Server & Clients)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — The `serve` (foreground) command exists and is functional. The `start` (daemon) command is a production deployment convenience, not a blocker for development or testing workflows. - **Milestone**: v3.8.0 — Server deployment features belong to the Post-MVP Server milestone. - **Story Points**: 5 — L — Requires daemon process forking, PID file management, signal handling, and integration tests. Moderate complexity with OS-level concerns. - **MoSCoW**: Should Have — Background daemon mode is important for production deployment but not strictly essential for milestone demos or development workflows. The foreground `serve` command covers all functional requirements. - **Parent Epic**: #399 (Post-MVP Server & Clients) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.8.0 milestone

2026-04-05 19:35:03 +00:00

freemo referenced this issue

2026-04-05 19:36:17 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 19:38:18 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 19:45:38 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo removed this from the v3.8.0 milestone