docs: add openspec for SANDBOX-1806 shared types and bash session by fbm3307 · Pull Request #2 · codeready-toolchain/cli-mcp-operator

fbm3307 · 2026-05-08T06:53:21Z

Add openspec config, proposal, design, tasks, and capability specs
shared-types spec: ExecRequest, ExecResponse, AssignRequest contracts
persistent-bash-session spec: delimiter protocol, concurrent pipe readers, SIGKILL timeout with 5s deadline, deferred crash recovery, eager init, no output truncation

Assisted By : Cursor

Summary by CodeRabbit

New Features
- Added shared HTTP exec/assign API types and a persistent sandboxed bash session enabling stateful remote command execution with serialized access, timeout enforcement, partial-output return on kill, and crash-recovery semantics.
Documentation
- Added design, proposal, and spec documents describing architecture, wire-format contracts, execution lifecycle, and behavior expectations.
Chores
- Introduced spec-driven repository configuration and metadata.

- Add openspec config, proposal, design, tasks, and capability specs - shared-types spec: ExecRequest, ExecResponse, AssignRequest contracts - persistent-bash-session spec: delimiter protocol, concurrent pipe readers, SIGKILL timeout with 5s deadline, deferred crash recovery, eager init, no output truncation Co-authored-by: Cursor <cursoragent@cursor.com> Signed-off-by: Feny Mehta <fbm3307@gmail.com>

coderabbitai · 2026-05-08T06:53:33Z

Walkthrough

Adds spec, proposal, task, and design documents plus repo metadata describing shared HTTP wire-format types (ExecRequest, ExecResponse, AssignRequest) and a persistent BashSession design (delimiter-based output isolation, concurrent I/O, process-group SIGKILL timeouts, and crash/respawn semantics).

Changes

SANDBOX-1806: shared types + persistent bash session

Layer / File(s)	Summary
Project metadata & context `openspec/config.yaml`, `openspec/changes/archive/2026-05-08-shared-types-and-bash-session/.openspec.yaml`	Adds `spec-driven` schema metadata, creation timestamp, and repository/context description for the two-binary layout (CLI MCP server + sandbox agent).
Shared HTTP wire-format types (contract) `openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/shared-types/spec.md`, `openspec/changes/archive/2026-05-08-shared-types-and-bash-session/proposal.md`	Specifies JSON wire-format for `ExecRequest` (`command`, optional `timeout` with `omitempty`), `ExecResponse` (`stdout`, `stderr`, `exit_code`, `duration_ms`), and `AssignRequest` (`token`). Mandates plain structs with no init side-effects and co-location in `pkg/agent/types.go`.
Persistent BashSession design & spec `openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/persistent-bash-session/spec.md`, `.../design.md`, `.../proposal.md`	Defines `BashSession` semantics: eager `bash --norc --noprofile` start, suppressed prompts, UUID delimiter protocol to isolate per-command stdout/exit markers, concurrent stdout/stderr reading, mutex-serialized `Execute()`, timeout behavior that SIGKILLs the command process group with a 5s hard wait and returns partial output with exit code `137`, EOF/crash detection that marks session dead and respawns on next call (with reset notice), `ExecResult` domain type including wall-clock `Duration`, `Close()` idempotency, and `IsAlive()` guarded by the mutex.
Tasks / Implementation plan `openspec/changes/archive/2026-05-08-shared-types-and-bash-session/tasks.md`, `.../proposal.md`	Lists concrete exported Go entities and functions to implement: `ExecRequest`, `ExecResponse`, `AssignRequest` (wire types), `ExecResult`, `BashConfig`, `NewDefaultBashConfig()`, `NewBashSession(cfg)`, methods `Execute(command, timeout)`, `Close()`, `IsAlive()`, and helper `respawn()`. Describes concurrency, pipe-based `os/exec` choice, and process-group `SysProcAttr{Setpgid:true}` usage.
Archive container `openspec/changes/archive/2026-05-08-shared-types-and-bash-session/*`	Adds an archive folder with the above design, specs, proposal, tasks, and manifest metadata documenting the change set.

sequenceDiagram
    participant Client as Client
    participant Server as CLI-MCP Server
    participant Agent as Sandbox Agent
    participant Bash as Bash Process

    Client->>Server: POST /exec (ExecRequest)
    Server->>Agent: Forward ExecRequest
    Agent->>Bash: Write wrapped command (START marker + command + END marker)
    Bash-->>Agent: Stream stdout/stderr (delimited)
    Agent->>Bash: If timeout → send SIGKILL to command pgid
    Bash-->>Agent: EOF / exit marker
    Agent->>Server: ExecResponse (stdout, stderr, exit_code, duration_ms)
    Server->>Client: HTTP response (ExecResponse)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

documentation, proposal

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely describes the main change: adding OpenSpec documentation for SANDBOX-1806 shared types and bash session implementation.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

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

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

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

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/shared-types/spec.md`:
- Line 23: Update the ExecResponse DurationMs requirement to allow zero for
sub-millisecond executions: change the phrase "a positive `DurationMs` value" to
"a non-negative `DurationMs` value (>= 0)" for the example assertion that the
ExecResponse SHALL contain `Stdout`, `Stderr`, `ExitCode`, and `DurationMs`, and
make the same wording change for the other identical occurrence in the file so
`DurationMs` can be 0 for very fast commands.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Enterprise

Run ID: f995674e-e3f5-468a-b5c2-c79da611d8b4

📥 Commits

Reviewing files that changed from the base of the PR and between 8c73043 and 704f02b.

📒 Files selected for processing (7)

openspec/changes/archive/2026-05-08-shared-types-and-bash-session/.openspec.yaml
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/proposal.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/persistent-bash-session/spec.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/shared-types/spec.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/tasks.md
openspec/config.yaml

📜 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/config.yaml
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/shared-types/spec.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/proposal.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/persistent-bash-session/spec.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/tasks.md

🪛 LanguageTool

openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md

[style] ~66-~66: To elevate your writing, try using a synonym here.
Context: ...ning flag) for race conditions that are hard to get right ### Decision 4: Crash rec...

(HARD_TO)

[style] ~120-~120: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...rade-offs Risk: Commands producing very large output could OOM the sandbox agent → **...

(EN_WEAK_ADJECTIVE)

Co-authored-by: Cursor <cursoragent@cursor.com> Signed-off-by: Feny Mehta <fbm3307@gmail.com>

alexeykazakov

Looks good overall. I have one question/comment regarding streaming though.

alexeykazakov · 2026-05-08T20:08:11Z

+**Rationale:**
+- Avoids pipe buffer deadlocks that occur with sequential reads (a command writing heavily to stderr blocks while we wait for stdout)
+- Simpler than channel-based approach — just accumulate into buffers
+- No streaming needed since we return the full response at the end


Ideally we would want to support streaming. MCP spec/sdk does support streaming. TARSy also supports streaming from MCP Servers.
It's not a deal breaker though. If it makes implementation significantly easier.

Thanks. I investigated how both tarsy and mcp-server-devsandbox currently handle tool results — both use batch CallTool → complete CallToolResult (TARSy's "streaming" is LLM/timeline events, not MCP tool output). Neither side consumes incremental tool results today.

That said, streaming is clearly the direction for longer-running commands. I've updated Decision 2 in the design to acknowledge this and added a "Future Extension: Streaming Execution" section to the bash session spec that sketches the ExecuteStream() API shape.

The key insight: the internal pipe readers already work line-by-line, so the architecture is streaming-ready by design. Adding ExecuteStream() later is additive (~30-40 lines) and doesn't require refactoring Execute(). When TARSy/the MCP SDK adds support for partial tool results or progress notifications, we can layer streaming on top without changing the foundation.

- Amend Decision 2 in design.md to acknowledge streaming-ready internals and batch-first rationale (TARSy consumes batch today) - Add "Future Extension: Streaming Execution" section to bash session spec with sketched ExecuteStream() API and open design questions - Reference cross-system dependency (TARSy + MCP SDK partial results) for when streaming becomes actionable Co-authored-by: cursor-agent <cursor-agent@cursor.com> Signed-off-by: Feny Mehta <fbm3307@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md (1)
134-137: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Resolve contradiction between “Open Questions: None” and streaming’s unresolved questions.

Line 136 says no open questions, but Line 50 explicitly references open design questions for ExecuteStream(). This inconsistency can mislead planning and tracking for SANDBOX-1806 follow-ups.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md`
around lines 134 - 137, The doc currently contradicts itself: replace the "Open
Questions — None" statement with an explicit list of unresolved items for
ExecuteStream() (or mark ExecuteStream() as resolved); specifically, update the
Open Questions section to list the outstanding design questions referenced
earlier for ExecuteStream() (including the SANDBOX-1806 follow-ups and any
decisions still pending), or remove/modify the earlier reference to
ExecuteStream() so both places agree.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md`:
- Around line 134-137: The doc currently contradicts itself: replace the "Open
Questions — None" statement with an explicit list of unresolved items for
ExecuteStream() (or mark ExecuteStream() as resolved); specifically, update the
Open Questions section to list the outstanding design questions referenced
earlier for ExecuteStream() (including the SANDBOX-1806 follow-ups and any
decisions still pending), or remove/modify the earlier reference to
ExecuteStream() so both places agree.

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Enterprise

Run ID: e37b947c-fd02-45fd-a6e8-d3667ef73503

📥 Commits

Reviewing files that changed from the base of the PR and between c276168 and 2bf419d.

📒 Files selected for processing (2)

openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md
openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/persistent-bash-session/spec.md

🚧 Files skipped from review as they are similar to previous changes (1)

openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/persistent-bash-session/spec.md

📜 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-08-shared-types-and-bash-session/design.md

🪛 LanguageTool

openspec/changes/archive/2026-05-08-shared-types-and-bash-session/design.md

[style] ~65-~65: To elevate your writing, try using a synonym here.
Context: ...ning flag) for race conditions that are hard to get right ### Decision 4: Crash rec...

(HARD_TO)

[style] ~119-~119: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...rade-offs Risk: Commands producing very large output could OOM the sandbox agent → **...

(EN_WEAK_ADJECTIVE)

fbm3307 requested a review from alexeykazakov May 8, 2026 06:53

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

coderabbitai Bot reviewed May 8, 2026

View reviewed changes

Comment thread openspec/changes/archive/2026-05-08-shared-types-and-bash-session/specs/shared-types/spec.md Outdated

fix: allow zero DurationMs for sub-millisecond commands

c276168

Co-authored-by: Cursor <cursoragent@cursor.com> Signed-off-by: Feny Mehta <fbm3307@gmail.com>

alexeykazakov approved these changes May 8, 2026

View reviewed changes

coderabbitai Bot reviewed May 12, 2026

View reviewed changes

fbm3307 merged commit 2ed0b2f into master May 12, 2026
4 checks passed

fbm3307 deleted the sandbox1806-spec branch May 14, 2026 10:06

coderabbitai Bot mentioned this pull request May 14, 2026

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

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

This was referenced Jul 13, 2026

SANDBOX-1813: add openspec for bash MCP tool handler #17

Merged

spec: add openspec for MCP server setup (SANDBOX-1814) #20

Merged

coderabbitai Bot mentioned this pull request Jul 28, 2026

refactor: harden session lifecycle and some minor improvements #31

Merged

coderabbitai Bot mentioned this pull request Aug 5, 2026

docs: rewrite design docs to match as-built implementation #33

Merged

Navigation Menu

Uh oh!

docs: add openspec for SANDBOX-1806 shared types and bash session - #2

docs: add openspec for SANDBOX-1806 shared types and bash session#2
fbm3307 merged 3 commits into
masterfrom
sandbox1806-spec

fbm3307 commented May 8, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 8, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

alexeykazakov left a comment

Uh oh!

alexeykazakov May 8, 2026

Uh oh!

fbm3307 May 12, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexeykazakov left a comment

Choose a reason for hiding this comment

Uh oh!

alexeykazakov May 8, 2026

Choose a reason for hiding this comment

Uh oh!

fbm3307 May 12, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fbm3307 commented May 8, 2026 •

edited

Loading

coderabbitai Bot commented May 8, 2026 •

edited

Loading