feat: WebSocket session API for interactive agent steering

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+on:
+  push:
+    branches: [feat/paop-steering, main]
+  pull_request:
+    branches: [feat/paop-steering, main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go: ["1.21", "1.22"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - name: Build
+        working-directory: components/execd
+        run: go build ./...
+      - name: Vet
+        working-directory: components/execd
+        run: go vet ./...
+      - name: Test
+        working-directory: components/execd
+        run: go test ./... -race -timeout 60s

FORK.md

@@ -0,0 +1,57 @@
+# OpenSandbox Fork — PAOP WebSocket Steering Integration
+
+This is `danieliser/OpenSandbox`, a fork of [`alibaba/OpenSandbox`](https://github.com/alibaba/OpenSandbox).
+
+## Purpose
+
+This fork adds WebSocket-based steering support to `execd` so that PAOP (Persistent Agent
+Orchestration Platform) can replace its tmux/poll executor with a push-based, in-container
+execution model.
+
+Key goals:
+
+- Add `GET /ws/session/:sessionId` WebSocket endpoint to `components/execd` (Phase 1)
+- Add PTY opt-in via `?pty=1` query parameter for interactive programs (Phase 2)
+- Fix residual bugs from upstream PR #104 (`feat/bash-session`) (Phase 0)
+
+The PAOP-side counterpart lives in the `persistence` repo under `paop/executor/`.
+
+## Working Branch
+
+All active development happens on `feat/paop-steering`.
+
+## Upstream Sync
+
+To pull in upstream changes from `alibaba/OpenSandbox`:
+
+```bash
+git fetch upstream
+git checkout feat/paop-steering
+git merge upstream/main
+# Resolve conflicts, then push
+git push origin feat/paop-steering
+```
+
+If the `upstream` remote is not yet configured:
+
+```bash
+git remote add upstream https://github.com/alibaba/OpenSandbox.git
+```
+
+## What's PAOP-Only vs. Upstream Candidates
+
+| Phase | Changes | Upstream candidate? |
+|-------|---------|---------------------|
+| Phase 0 | Bug fixes for PR #104 (TOCTOU race, stderr routing, sentinel collision, context leak, shutdown race) | **Yes** — these are correctness fixes valuable to all users |
+| Phase 1 | `GET /ws/session/:sessionId` WebSocket endpoint | **Possibly** — generic enough; needs upstream discussion |
+| Phase 2 | PTY opt-in (`?pty=1`) | **Possibly** — generic; needs upstream discussion |
+| Phase 3 | PAOP `WSExecutor` integration (lives in `persistence` repo) | **No** — PAOP-specific, stays here / in persistence repo |
+
+Phase 0 bug fixes are the strongest upstream PR candidates. They fix real correctness issues
+independent of any PAOP integration and should be submitted back once validated.
+
+## CI
+
+GitHub Actions runs on every push and pull request targeting `feat/paop-steering` or `main`.
+Matrix: Go 1.21 and 1.22. Steps: build, vet, race-detector test suite (60s timeout).
+See `.github/workflows/ci.yml`.

components/execd/go.mod

@@ -23,6 +23,7 @@ require (
 	github.com/bytedance/sonic/loader v0.1.1 // indirect
 	github.com/cloudwego/base64x v0.1.4 // indirect
 	github.com/cloudwego/iasm v0.2.0 // indirect
+	github.com/creack/pty v1.1.24 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.10 // indirect

components/execd/go.sum

@@ -11,6 +11,8 @@ github.com/cloudwego/base64x v0.1.4/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJ
 github.com/cloudwego/iasm v0.2.0 h1:1KNIy1I1H9hNNFEEH3DVnI4UujN+1zjpuk6gwHLTssg=
 github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
+github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=