feat: expose sandbox preview in the Python and Node SDKs

[alongubkin]

Fixes ALIEN-1117.

Problem

The Rust sandbox binding has preview(sandbox_id, port): it mints an authenticated, port-scoped capability to reach a service inside a sandbox (endpoint, headers, allowed ports, expiry). The Python and Node SDKs didn't expose it. Node's capabilities() even hid preview on purpose, because there was no method to call. An application that talks to a server inside its sandbox had no supported way to do it from Python or TypeScript.

Change

• Python (alienplatform): Sandbox.preview(sandbox_id, port) -> SandboxPreview (endpoint, headers, allowed_ports, expires_in_seconds), exported from the package, and preview in capabilities().
• Node (napi): SandboxHandle.preview(sandboxId, port) returning SandboxPreviewJs; a port outside u16 is rejected with InvalidArg. preview is now advertised in capabilities().
• TypeScript (@alienplatform/bindings): SandboxPreview type, Sandbox.preview, and the raw handle type. The remote-deployment sandbox gets it too, since it shares the wrapper.

Tests

Both SDKs are tested through the real native module against a loopback server that stands in for the local sandbox route:

• packages/bindings/tests/sandbox.test.ts: capabilities() includes preview; preview("s1", 8080) returns the route's endpoint and ports; the request carries the route token and the port; port 70000 is refused.
• crates/alien-bindings-python/tests/test_bindings.py: the same, returning a SandboxPreview.
• tests/remote.test.ts (addon members check) now expects preview on the native SandboxHandle.

Local runs: Node bindings suites (81 tests) against a locally built addon, tsc, biome; Python tests (11) against a locally built wheel, ruff, mypy.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds sandbox preview endpoint to SDK bindings.

The PR appears safe to merge, with two previously reported non-blocking test issues still open.

Findings

1.  Authenticated previews lack coverage ▶
2.  Temporary tokens remain after tests ▶

Fix with agent prompt

### Issue 1
packages/bindings/tests/sandbox.test.ts:90-95
This real-addon test checks only empty headers and a zero expiry, as does the new Python test. AWS previews return authentication and port headers with a nonzero expiry, so a regression in converting those fields through either native SDK would go undetected. Please cover a preview with nonempty headers and a nonzero lifetime.

### Issue 2
packages/bindings/tests/sandbox.test.ts:78-79
The test creates a temporary directory and token file, but `finally` closes only the HTTP server. Repeated runs leave those files behind. Please remove the temporary directory during cleanup.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR exposes sandbox previews through the Python and Node SDKs and their TypeScript types. The changes since the previous review clarify that a zero-second expiry means the local preview has no time-based expiry.

• The earlier zero-expiry documentation finding is fixed.
• The earlier gaps in authenticated-preview test coverage and temporary-file cleanup remain.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Python or TypeScript caller] --> B[Native sandbox handle]
  B --> C[Sandbox preview backend]
  C --> D[Endpoint, headers, ports, expiry]

Loading

_{Reviews (2) · Last reviewed commit: "docs: say a zero preview expiry means it..."}

[alongubkin]

@greptileai