From a52381dab71a1f931714d4bbd212b86be418f4d2 Mon Sep 17 00:00:00 2001 From: CMGS Date: Mon, 9 Nov 2026 21:38:16 +0800 Subject: [PATCH 1/2] docs: fixture coverage, e2e usage and the proxy port doc say what the code does Python round-trips the corpus's request frames and only decodes each response to its type; the README, sdk-python.md and the test docstring said it round-trips the whole corpus. The three e2e usage lines named an rt2:24.04 template no image build produces. The silkd LOOPBACK_PORT doc named proxy.internal, which only a test uses as a placeholder host. --- docs/sdk-python.md | 5 +++-- mcp/e2e.py | 2 +- sdk/openai/e2e.py | 2 +- sdk/python/README.md | 5 +++-- sdk/python/e2e.py | 2 +- sdk/python/tests/test_fixtures.py | 2 +- silkd/src/net_egress.rs | 2 +- 7 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/sdk-python.md b/docs/sdk-python.md index 7b7f4d7c2..64ea3c37c 100644 --- a/docs/sdk-python.md +++ b/docs/sdk-python.md @@ -21,8 +21,9 @@ wire is chunked, the caller's copy is not). Two behaviors differ as well: `Session.close()` and `Lsp.stop()` swallow `not_found` where Go returns it, and a failed session command puts its merged output in `ExitError.stdout` with `stderr` empty, where Go's `ExitError.Stderr` holds it. Wire fidelity is -pinned by the shared protocol fixture corpus that the Rust guest, Go, and -Python all round-trip in CI. +pinned by the shared protocol fixture corpus: the Rust guest and Go +round-trip it in CI, and Python round-trips its requests and decodes each +response. ## A complete example diff --git a/mcp/e2e.py b/mcp/e2e.py index 12db4c7cb..03a049d00 100644 --- a/mcp/e2e.py +++ b/mcp/e2e.py @@ -2,7 +2,7 @@ to the built binary against a live node — the exact protocol an MCP client uses. Prints MCP-E2E PASS. - python3 e2e.py --bin ./sandbox-mcp --addr 127.0.0.1:7777 --token e2e --template rt2:24.04 + python3 e2e.py --bin ./sandbox-mcp --addr 127.0.0.1:7777 --token e2e --template rt:24.04 """ from __future__ import annotations diff --git a/sdk/openai/e2e.py b/sdk/openai/e2e.py index 0925723d1..0457d3494 100644 --- a/sdk/openai/e2e.py +++ b/sdk/openai/e2e.py @@ -3,7 +3,7 @@ a real sandboxd node — the exact path the Agents runner takes. Prints OPENAI-ADAPTER-E2E PASS. - python3 e2e.py --addr 127.0.0.1:7777 --token e2e --template rt2:24.04 + python3 e2e.py --addr 127.0.0.1:7777 --token e2e --template rt:24.04 """ import argparse diff --git a/sdk/python/README.md b/sdk/python/README.md index 1363a0177..9a663976d 100644 --- a/sdk/python/README.md +++ b/sdk/python/README.md @@ -21,7 +21,8 @@ watch, persistent sessions, git verbs, pty, port dial/proxy/preview URLs, background processes (spawn/ps/kill/ logs/attach), renew, fork, hibernate, promote, checkpoints, and the LSP broker. -Wire fidelity is pinned by the shared protocol fixture corpus (Rust + Go + -Python all round-trip it in CI). +Wire fidelity is pinned by the shared protocol fixture corpus: Rust and Go +round-trip it in CI, and Python round-trips its requests and decodes each +response. Full reference: https://cocoonstack.github.io/sandbox/sdk-python diff --git a/sdk/python/e2e.py b/sdk/python/e2e.py index 53793c647..e74c94caf 100644 --- a/sdk/python/e2e.py +++ b/sdk/python/e2e.py @@ -1,7 +1,7 @@ """Hardware e2e for the Python SDK: drives the full surface against a real sandboxd node. Mirrors the Go smoke's step discipline; prints PY-E2E PASS. - python3 e2e.py --addr 127.0.0.1:7777 --token e2e --template rt2:24.04 + python3 e2e.py --addr 127.0.0.1:7777 --token e2e --template rt:24.04 """ from __future__ import annotations diff --git a/sdk/python/tests/test_fixtures.py b/sdk/python/tests/test_fixtures.py index 145f807e9..90364826a 100644 --- a/sdk/python/tests/test_fixtures.py +++ b/sdk/python/tests/test_fixtures.py @@ -1,4 +1,4 @@ -"""Round-trips the protocol fixture corpus, the same drift guard the Rust and Go implementations run.""" +"""Round-trips the protocol corpus's request frames and decodes each response frame to its type.""" import base64 import json diff --git a/silkd/src/net_egress.rs b/silkd/src/net_egress.rs index 33bc97c77..8d9009df5 100644 --- a/silkd/src/net_egress.rs +++ b/silkd/src/net_egress.rs @@ -5,7 +5,7 @@ use std::net::{Ipv4Addr, SocketAddrV4}; use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt}; -/// Loopback port the guest reaches the proxy at (`proxy.internal:3128`). +/// Loopback port the guest reaches the proxy at. pub const LOOPBACK_PORT: u16 = 3128; /// Host vsock port the VMM maps to sandboxd's `_` UDS. pub const HOST_VSOCK_PORT: u32 = 2049; From e4492bee5bd74d266a707adcb5438d3f442fa74f Mon Sep 17 00:00:00 2001 From: CMGS Date: Mon, 9 Nov 2026 22:36:39 +0800 Subject: [PATCH 2/2] docs: state what each language's fixture test checks: Go round-trips, Rust parses requests, Python decodes responses --- README.md | 2 +- docs/sdk-python.md | 6 +++--- sdk/python/README.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ab913bc52..11fc1f2ce 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ sandboxd](docs/deploy.md) covers release binaries, the full config and systemd. - `sdk/langchain/` — `cocoonstack-sandbox-langchain`, a [LangChain toolkit](docs/langchain.md) - `protocol/wire/` — the frame vocabulary and `fixtures/`, the golden corpus the - Rust, Go and Python tests all round-trip, so wire drift fails CI + Rust, Go and Python tests check, so wire drift fails CI - `e2e/` — in-process full-stack tests (real pool/engine/relay/SDK, fake cocoon + guest) and the [bare-metal drivers](docs/deploy.md#acceptance-drivers) - `boot/kernel/` — kernel version pin (`VERSION` + matching tarball `SHA256`, diff --git a/docs/sdk-python.md b/docs/sdk-python.md index 64ea3c37c..2ef322220 100644 --- a/docs/sdk-python.md +++ b/docs/sdk-python.md @@ -21,9 +21,9 @@ wire is chunked, the caller's copy is not). Two behaviors differ as well: `Session.close()` and `Lsp.stop()` swallow `not_found` where Go returns it, and a failed session command puts its merged output in `ExitError.stdout` with `stderr` empty, where Go's `ExitError.Stderr` holds it. Wire fidelity is -pinned by the shared protocol fixture corpus: the Rust guest and Go -round-trip it in CI, and Python round-trips its requests and decodes each -response. +pinned by the shared protocol fixture corpus: Go round-trips it in CI, the +Rust guest parses its requests and round-trips its responses, and Python +round-trips its requests and decodes each response. ## A complete example diff --git a/sdk/python/README.md b/sdk/python/README.md index 9a663976d..95f38dd0a 100644 --- a/sdk/python/README.md +++ b/sdk/python/README.md @@ -21,8 +21,8 @@ watch, persistent sessions, git verbs, pty, port dial/proxy/preview URLs, background processes (spawn/ps/kill/ logs/attach), renew, fork, hibernate, promote, checkpoints, and the LSP broker. -Wire fidelity is pinned by the shared protocol fixture corpus: Rust and Go -round-trip it in CI, and Python round-trips its requests and decodes each -response. +Wire fidelity is pinned by the shared protocol fixture corpus: Go round-trips +it in CI, Rust parses its requests and round-trips its responses, and Python +round-trips its requests and decodes each response. Full reference: https://cocoonstack.github.io/sandbox/sdk-python