docs: add openspec for SANDBOX-1807 agent HTTP handlers by fbm3307 · Pull Request #5 · codeready-toolchain/cli-mcp-operator

fbm3307 · 2026-05-14T11:04:44Z

Proposal, design, tasks, and behavioral specs for the sandbox agent HTTP layer (POST /exec, POST /assign, GET /health) and entry point
Covers agent state machine, bearer token auth, graceful shutdown, Go 1.22+ routing, and 310s shutdown timeout coordination with K8s

Summary by CodeRabbit

Documentation
- Added design and specification documentation for sandbox agent HTTP service layer, including endpoint definitions, authentication mechanisms, and startup/shutdown behavior requirements.

- Proposal, design, tasks, and behavioral specs for the sandbox agent HTTP layer (POST /exec, POST /assign, GET /health) and entry point - Covers agent state machine, bearer token auth, graceful shutdown, Go 1.22+ routing, and 310s shutdown timeout coordination with K8s Co-authored-by: Cursor <cursoragent@cursor.com> Signed-off-by: Feny Mehta <fbm3307@gmail.com>

coderabbitai · 2026-05-14T11:04:57Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: 68d8c529-77a9-4edb-ad27-1d86356cac9f

📥 Commits

Reviewing files that changed from the base of the PR and between 6b0b030 and 7f49db6.

📒 Files selected for processing (6)

openspec/changes/archive/2026-05-14-agent-http-handlers/.openspec.yaml
openspec/changes/archive/2026-05-14-agent-http-handlers/design.md
openspec/changes/archive/2026-05-14-agent-http-handlers/proposal.md
openspec/changes/archive/2026-05-14-agent-http-handlers/specs/agent-entry-point/spec.md
openspec/changes/archive/2026-05-14-agent-http-handlers/specs/agent-http-handlers/spec.md
openspec/changes/archive/2026-05-14-agent-http-handlers/tasks.md

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.

Files:

openspec/changes/archive/2026-05-14-agent-http-handlers/specs/agent-entry-point/spec.md
openspec/changes/archive/2026-05-14-agent-http-handlers/specs/agent-http-handlers/spec.md
openspec/changes/archive/2026-05-14-agent-http-handlers/tasks.md
openspec/changes/archive/2026-05-14-agent-http-handlers/design.md
openspec/changes/archive/2026-05-14-agent-http-handlers/proposal.md

🪛 LanguageTool

openspec/changes/archive/2026-05-14-agent-http-handlers/design.md

[grammar] ~113-~113: Ensure spelling is correct
Context: ...to MCP server only). Pod memory limits (512Mi) are the backstop. Rationale: - Th...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.22.1)

openspec/changes/archive/2026-05-14-agent-http-handlers/specs/agent-http-handlers/spec.md

[warning] 49-49: Spaces inside code span elements

(MD038, no-space-in-code)

openspec/changes/archive/2026-05-14-agent-http-handlers/tasks.md

[warning] 19-19: Spaces inside code span elements

(MD038, no-space-in-code)

🔇 Additional comments (6)

openspec/changes/archive/2026-05-14-agent-http-handlers/.openspec.yaml (1)

1-2: LGTM!

openspec/changes/archive/2026-05-14-agent-http-handlers/tasks.md (1)

1-43: LGTM!

openspec/changes/archive/2026-05-14-agent-http-handlers/proposal.md (1)

1-37: LGTM!

openspec/changes/archive/2026-05-14-agent-http-handlers/design.md (1)

1-136: LGTM!

openspec/changes/archive/2026-05-14-agent-http-handlers/specs/agent-entry-point/spec.md (1)

1-67: LGTM!

openspec/changes/archive/2026-05-14-agent-http-handlers/specs/agent-http-handlers/spec.md (1)

1-134: LGTM!

Walkthrough

This PR adds OpenSpec documentation for a sandbox agent HTTP layer, including design decisions, endpoint specifications, and implementation tasks for three HTTP endpoints on port 8090 serving POST /exec (bearer token auth), POST /assign (token assignment), and GET /health (readiness).

Changes

Agent HTTP Server Design, Specifications, and Tasks

Layer / File(s)	Summary
Architecture and design decisions `.openspec.yaml`, `design.md`, `proposal.md`	Overview of the two-component architecture (MCP server vs. sandbox agent), the three endpoints on port 8090, concrete implementation decisions (state management, constant-time token comparison, handler organization, graceful shutdown timeout), non-goals, and risks/trade-offs including NetworkPolicy mitigation for unauthenticated `/assign`.
Handler endpoint specifications `specs/agent-http-handlers/spec.md`	Behavioral requirements for `AgentState` (mutex-protected token/assigned flag lifecycle), `Handler` struct dependencies, and detailed specifications for `POST /exec` (bearer token auth via `hmac.Equal()`, request/response mapping, error handling), `POST /assign` (token assignment validation and conflict detection), and `GET /health` (liveness via `BashSession.IsAlive()`). Standardizes JSON error format and mandates Go 1.22+ method-based routing patterns.
Agent entry point and startup lifecycle `specs/agent-entry-point/spec.md`	Startup behavior based on `SANDBOX_AUTH_TOKEN` environment variable, eager `BashSession` creation with fatal exit on failure, HTTP server startup on port 8090 with logging, graceful shutdown handling for `SIGTERM`/`SIGINT` with 310-second `http.Server.Shutdown()` timeout, Kubernetes `terminationGracePeriodSeconds` alignment to 310, and version logging to stderr at startup.
Implementation task checklist `tasks.md`	Task breakdown for implementing `AgentState`, `Handler` type, `ErrorResponse` helper, health endpoint, `POST /exec` (auth, parsing, execution, response mapping), `POST /assign` (validation, state transition), and `cmd/agent/main.go` entry point (env reading, session creation, routing, signal handling, graceful shutdown).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

codeready-toolchain/cli-mcp-server#2: The agent HTTP handlers spec builds directly on the shared ExecRequest, ExecResponse, and AssignRequest types from SANDBOX-1806 and the BashSession contract used by the /exec and /health handlers.

Suggested labels

documentation, proposal

Suggested reviewers

alexeykazakov

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: adding OpenSpec documentation for SANDBOX-1807 agent HTTP handlers, which is the exclusive focus of all files in this changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch sandbox1807-spec

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

alexeykazakov

Looks good overall. But please take a look at my comments.

alexeykazakov · 2026-05-14T16:59:23Z

+Use `mux.HandleFunc("POST /exec", ...)` instead of manual method checks.
+
+**Rationale:**
+- Repo is Go 1.24+; `use-modern-go` skill says to use modern idioms


Not related to this design but let's switch to Go 1.25, as a separate task.

Agreed — tracked as a separate task. The Go 1.22+ routing features we reference here work fine on 1.24 and will continue to work on 1.25

alexeykazakov · 2026-05-14T17:04:37Z

+- Update `cmd/agent/main.go` with:
+  - `SANDBOX_AUTH_TOKEN` env var reading for initial state
+  - `BashSession` creation with eager initialization
+  - HTTP mux with Go 1.22+ method-based routing (`POST /exec`, `POST /assign`, `GET /health`)


Have you considered using some lightweight frameworks like https://github.com/labstack/echo (v. 5+)? This is what we use in tarsy, GC, reg-service. I don't know if it gives us anything in the agent context though. The agent needs are pretty minimal.

@alexeykazakov i did consider it — Echo is a good fit for services with rich routing, middleware stacks, and request binding (tarsy, reg-service). The sandbox agent has 3 endpoints, no middleware, and the stdlib net/http with Go 1.22+ method routing covers everything we need (automatic 405, no boilerplate method checks). Adding Echo would be a dependency with no functional benefit here. mcp-server-devsandbox also uses stdlib net/http for the same reason.
WDYT?

I'm fine with sticking with plain Go for now.

fbm3307 requested a review from alexeykazakov May 14, 2026 11:04

coderabbitai Bot added documentation Improvements or additions to documentation proposal labels May 14, 2026

alexeykazakov approved these changes May 14, 2026

View reviewed changes

fbm3307 merged commit 2333a25 into master Jun 1, 2026
4 checks passed

fbm3307 deleted the sandbox1807-spec branch June 1, 2026 06:32

coderabbitai Bot mentioned this pull request Jun 2, 2026

feat: add sandbox agent HTTP handlers and entry point #7

Merged

coderabbitai Bot mentioned this pull request Jun 22, 2026

spec: add openspec for pod cache and session manager (SANDBOX-1810) #10

Merged

This was referenced Jul 1, 2026

SANDBOX-1811: add openspec for warm pod pool #13

Merged

SANDBOX-1812: add openspec for agent HTTP client #15

Merged

Navigation Menu

Uh oh!

docs: add openspec for SANDBOX-1807 agent HTTP handlers - #5

docs: add openspec for SANDBOX-1807 agent HTTP handlers#5
fbm3307 merged 1 commit into
masterfrom
sandbox1807-spec

fbm3307 commented May 14, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 14, 2026 •

edited

Loading

Uh oh!

alexeykazakov left a comment

Uh oh!

alexeykazakov May 14, 2026

Uh oh!

fbm3307 May 28, 2026

Uh oh!

alexeykazakov May 14, 2026

Uh oh!

fbm3307 May 28, 2026

Uh oh!

alexeykazakov May 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

fbm3307 commented May 14, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Uh oh!

alexeykazakov left a comment

Choose a reason for hiding this comment

Uh oh!

alexeykazakov May 14, 2026

Choose a reason for hiding this comment

Uh oh!

fbm3307 May 28, 2026

Choose a reason for hiding this comment

Uh oh!

alexeykazakov May 14, 2026

Choose a reason for hiding this comment

Uh oh!

fbm3307 May 28, 2026

Choose a reason for hiding this comment

Uh oh!

alexeykazakov May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fbm3307 commented May 14, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 14, 2026 •

edited

Loading