Repository navigation
feat(python): Native async Python sandbox clients #5164
Description
User Story
I use the OpenShell Python SDK from asynchronous workload controllers and need typed sandbox operations without blocking the event loop.
Problem Statement
The generated bindings support grpc.aio, but the public sandbox, template, provider-credential, and workspace helpers are synchronous. Applications must assemble requests and manage transport details themselves.
Impact / Why This Matters
Callers duplicate request construction and lifecycle handling outside the SDK, making reliable controller integrations harder to maintain.
Proposed Design
Add AsyncSandboxClient and matching async helper clients with the existing method structure. Preserve authentication, structured errors, lazy pagination, cancellation, and channel ownership. Expose per-call deadlines and request IDs on supported RPC operations.
Suggested UX
async with AsyncSandboxClient(target) as client:
sandbox = await client.get("worker", workspace="default")Acceptance Criteria
- Native async lifecycle, exec, and lazy pagination preserve typed results.
- Managed authentication and borrowed channels have documented lifecycles.
- Owner-replica exec routing retains its pre-response fallback without replaying output.
- Runtime transport tests, consumer type checks, and wheel verification pass.
Alternatives Considered
Continue using generated RPC stubs and application-specific wrappers. The stubs remain available, but these common operations belong in the existing SDK clients; a new client hierarchy or server-side extension is unnecessary.
Activity
TaylorMutch commentedon Nov 2, 2026
Technically valid SDK feature request, ready for human review. The user story supplies first-hand async-controller use, the raw-stub workaround and its maintenance cost, a notional API, and observable acceptance criteria.
Upstream
mainat5dfb225a9f61a4b7880a50fc2adc85183d63fe08still constructs synchronous gRPC channels inSandboxClientand exposes synchronous sandbox/template/workspace helpers.ProviderClientlikewise uses synchronous calls. Merged #5040 supplies typed sync/async generated RPC bindings; it does not provide these high-level async clients. Server middleware or interceptors cannot supply Python event-loop-safe client calls and lifecycle management. Native async counterparts fit the existing SDK surface.There is overlapping implementation work: #5168 directly closes this issue, while open #2645 implements native async clients against earlier #1820 (now closed as not planned). SDK owners should reconcile those PRs and clarify which API surface to pursue before starting further implementation; the old issue's closure alone does not resolve this request.
For acceptance, make the tests explicitly cover cancellation during failed context entry and streaming, cleanup of owned channels/auth resources without closing borrowed channels, lazy async pagination, structured errors, per-call deadline overrides versus command execution timeouts, and request IDs only on supported RPCs. Preserve owner-replica fallback only before any response; a later failure must propagate without replay. #2645 already has reported failed-entry cleanup evidence worth considering, though I have not independently reproduced it.
This is an issue assessment based on source and related-work inspection, not an implementation approval or verification of either PR's reported test results. The next decision is maintainer acceptance and coordination of the existing implementations.