feat: add timeout kwarg to get_background_job

[rasdani]

Summary

All sibling Sandbox / AsyncSandbox methods — execute_command, read_file, upload_file, download_file — already accept a per-call timeout kwarg that overrides the APIClient's 30s httpx default. get_background_job was the lone exception, so callers had no way to extend its effective timeout, even though the method internally just calls read_file (which does accept timeout).

In practice this surfaced as Read file timed out after 30s: /tmp/job_XXX.exit during RL polling loops in verifiers when the sandbox gateway had a brief slow response, bubbling up as AgentError('Agent polling failed: ...').

Change

Add timeout: Optional[int] = None to both the sync and async get_background_job signatures, and thread it through to the internal read_file calls on the exit file, stdout log, and stderr log. Default behavior is unchanged (falls back to APIClient default when timeout is not passed).

Pattern matches the existing execute_command / read_file signatures in the same file (Optional[int], default None).

Follow-up

The verifiers side — CliAgentEnv.poll_job_completion — will consume this with an explicit timeout=60.0 once a release including this change lands. Separate PR.

Test plan

• Added tests/test_background_job_timeout.py — five unit tests (sync + async) that monkeypatch read_file and assert the kwarg propagates (including the multi-read path when the job is completed, where all three reads should receive the same timeout).
• uv run --extra dev pytest tests/test_background_job_timeout.py tests/test_gateway_error_mapping.py tests/test_models.py tests/test_client_retry.py — 36 passed.
• uv run --extra dev ruff check src/ tests/ — clean.
• uv run --extra dev ruff format --check src/ tests/ — clean.
• Integration suite (test_command_execution.py, etc.) not run locally — requires real sandbox credentials; behavior should be unchanged since the default path (timeout=None) is preserved.

---

Note

Low Risk
Low risk: adds an optional timeout parameter and simply forwards it to existing read_file calls, with default behavior unchanged when omitted.

Overview
Adds an optional timeout: Optional[int] = None parameter to both sync and async get_background_job, and forwards it through to the underlying read_file calls for the exit/stdout/stderr polling files.

Introduces new unit tests (test_background_job_timeout.py) that monkeypatch read_file to assert the timeout kwarg is propagated (including the multi-read completed-job path) and that the default remains None when not provided.

^{Reviewed by Cursor Bugbot for commit 0086e99. Bugbot is set up for automated code reviews on this repo. Configure here.}