[maxdubrinsky]

Summary

Async Python applications currently drop to raw RPCs or wrap the synchronous SDK in worker threads. Add native async counterparts with the same client structure, generated concrete method signatures, managed authentication, cancellation, pagination, and channel ownership.

Related Issue

Closes #5164

Changes

• Generate concrete async methods from synchronous operation bodies; keep native async transport and resource ownership handwritten.
• Preserve OIDC/client-credential refresh behavior off the event loop and owner-replica exec routing.
• Add request IDs on supported operations, borrowed-channel construction, consumer type tests, and packaging verification.

Release Notes

Testing

• Python suite: 278 passed.
• Ruff lint/format and ty checks, including consumer signatures and generated async methods.
• Loopback gRPC tests cover authentication, pagination, cancellation, channel ownership, client-level deadlines, and exec routing.
• Live gateway integration (not run; this change does not modify sandbox infrastructure).

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).
• Python implementation and public SDK documentation updated.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5168.docs.buildwithfern.com/openshell

[github-actions]

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. python-sdk — No explicit risk acceptance found

The RPM's openshell initializer previously imported installed synchronous modules but now unconditionally imports _async_runtime and aio, neither included by openshell.spec.

• Impact: Existing python3-openshell consumers using from openshell import SandboxClient encounter ModuleNotFoundError: No module named 'openshell._async_runtime', preventing even synchronous SDK use.
• Action: Include _async_runtime.py and generated aio.py in the python3-openshell RPM installation before v0.1.7 so existing synchronous imports remain compatible.
• PR: feat(python): add native async sandbox clients #5168

Review details

• Execution: complete
• Candidate: PR #5168 (582048d476593390cca68c648e99aaabb30afc77)
• Baseline: b35e39f64bcef8cc904d8d981db423c50f1076b0 (b35e39f64bcef8cc904d8d981db423c50f1076b0)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

[TaylorMutch]

Reviewed commit d2c03fb86327661287ce0cce2f3fca9cdd225bee. Requesting changes for the following findings:

1. RPM installs break existing synchronous imports. python/openshell/__init__.py:8-15 now unconditionally imports _async_runtime and aio, but openshell.spec installs neither module. Staging the exact top-level files selected by the spec, plus generated RPC modules, confirms that from openshell import SandboxClient succeeds at the base (b35e39f64bcef8cc904d8d981db423c50f1076b0) and fails at this head with ModuleNotFoundError: No module named 'openshell._async_runtime'. Please install both _async_runtime.py and generated aio.py in the RPM and add an installed-package import check covering the synchronous and asynchronous exports.

2. Per-call deadline overrides are missing. The generated async methods retain timeout=self._timeout and expose no RPC deadline argument; for example, AsyncSandboxClient.get() accepts only name and workspace. Before using these high-level helpers, consumers can supply deadlines directly on raw RPC calls; the new helpers cannot express different deadlines for concurrent operations on a shared client. Issue #5164 explicitly requests per-call deadlines. Please expose and forward a per-operation deadline override, preserving the client default when omitted, and test concurrent calls with different deadlines. timeout_seconds for command execution is a separate server-side execution limit and should not substitute for an RPC deadline. Relevant sources: tasks/scripts/generate_python_async.py and the generated client methods.

3. Request IDs stop at exec_stream(). python/openshell/sandbox.py:1355 adds request_id to exec_stream(), but exec() (:1459), exec_python() (:1496), and session wrappers cannot accept or forward it. The generator preserves this omission in the async API. As a result, callers using the ordinary execution helpers must drop to streaming or raw RPCs to supply an execution request ID, despite the issue's requirement to expose IDs on supported RPC operations. Please thread the optional ID through the execution helpers and session wrappers, and verify that the supplied value reaches ExecSandboxRequest.

The overall approach sensibly shares request construction through generation while keeping async transport and cleanup handwritten. Validation against this head: 238 affected SDK and wheel-verifier unit tests passed, including all nine new async transport/routing tests, using Python 3.14.5 and grpcio 1.78.0. The RPM import comparison above is a staged-file reproduction, not a full RPM build. Full typing and wheel-build verification remain unverified; local typed generation lacked protoc-gen-mypy_grpc.