fcloud-sdk 0.2.1__tar.gz → 0.3.1__tar.gz

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/CHANGELOG.md

@@ -6,6 +6,105 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-22
+
+### Fixed
+- `fcloud credits buy` no longer turns auto-refill on by default. It used to
+  consent on behalf of anyone who had never consented before, so buying less
+  than the auto-refill threshold enrolled the account and then charged the
+  saved card for the full top-up seconds later — `buy 10` against the default
+  $25 threshold cost $110. Consent is now opt-in via `--autorefill`, and
+  `--autorefill` also turns the setting back on for an account that had it
+  off, which consent alone cannot do. `--no-autorefill` is still accepted and
+  is now the default; passing both is an error.
+- Before a purchase that will trigger a top-up, the CLI now says so and names
+  the amount. What triggers one is the balance a purchase *leaves behind*,
+  not its size, and the refill is sized to clear the threshold — so $10
+  against a $200 threshold charges the card a further $195, not the $50 the
+  setting says. Both numbers are worked out and printed before anything is
+  charged, including under `--yes`, and including for an account that was
+  already armed.
+- `fcloud credits` no longer claims auto-refill "turns on with your first
+  purchase". It turns on with a purchase made with `--autorefill`, and the
+  status line now says so and names that command.
+- `fcloud credits buy` no longer sends buyers to a dead address after paying.
+  The return URL was built from a domain baked in at release time, which
+  outlived its DNS record: the charge succeeded and the browser landed on a
+  404. The CLI now names no return address and the dispatcher supplies one
+  from its own allowlist, which redeploys with the web app instead of going
+  stale in a published wheel. Setting `FCLOUD_WEB_URL` returns you to
+  `/dashboard`, the page that reads the result, rather than to
+  `/dashboard/billing`, which ignores it.
+
+### Changed
+- `resolve_web_url()` returns `None` when no web URL is configured, and
+  `DEFAULT_WEB_URL` is gone. `Client.start_credit_checkout()` takes
+  `success_url` and `cancel_url` as optional and omits them from the request
+  when unset. Set `FCLOUD_WEB_URL` only to override where a buyer is returned
+  to. **Needs a dispatcher carrying the matching server change**; against an
+  older one, set `FCLOUD_WEB_URL` or buy from the dashboard.
+
+### Added
+- `fcloud.billing_types.predicted_topup_micros()` — what auto-refill would
+  charge once a given purchase has posted. Mirrors the dispatcher's own
+  `topUpAmount` and daily-cap clamp so a confirmation can name the second
+  charge before the card is saved.
+
+## [0.3.0] - 2026-09-16
+
+### Fixed
+- `exec` no longer returns empty output for a command whose last write lands
+  at process exit. The host mirrors a process's durable log on a background
+  goroutine, so a read issued the instant the process reports "exited" can
+  beat that write and come back empty; the client was answering with that
+  empty read even though it had already drained the output off the live
+  stream. It now keeps whichever of the two saw more bytes. The symptom was
+  `stdout: ""` alongside `returncode: 0` — most often for a block-buffered
+  program, which flushes everything during interpreter teardown
+  microseconds before it dies. A training run's final `print(metrics)` is
+  exactly that shape.
+
+### Added
+- `fcloud map --no-bake` opts a sweep out of canary auto-bake. By default,
+  packages the canary pip-installs are baked into the sweep's image before
+  the fan-out; the canary pass line now names them and points at
+  `image.pip` in `fcloud.json` as the permanent home.
+- `fcloud credits`: the prepaid wallet from the terminal. `fcloud credits`
+  shows the posted balance, what is available after unbilled usage,
+  auto-refill state and the saved card; `fcloud credits buy <usd>` opens a
+  hosted checkout and waits for the purchase to post; `fcloud credits
+  autorefill on|off|set` changes the top-up rule (turning it off warns that
+  work stops at $0 and needs a confirmation); `fcloud credits statement`
+  lists ledger rows with a running balance.
+- `InsufficientCreditError` (HTTP 402, `code: insufficient_credit`) — raised
+  when the prepaid balance is exhausted, and mapped to **exit code 4** in
+  the CLI with the top-up command named. It is a sibling of `FcloudError`,
+  not of `PaymentOverdueError`: nothing is owed, so the remedy is to add
+  credit, not to settle a bill. Code that catches `PaymentOverdueError`
+  alone will not catch it.
+- `Client.credit_balance()`, `credit_ledger()`, `set_autorefill()` and
+  `start_credit_checkout()`, with typed payloads in `fcloud.billing_types`.
+- A low-balance warning before `exec`/`run`/`shell`/`create`/`job run`/`map`
+  provision anything, shown once per process and only when nothing will top
+  the account up. Best-effort: a failed billing read never blocks a run.
+
+### Changed
+- An out-of-credit refusal is no longer reported as a missed payment. Both
+  error paths now branch on the dispatcher's `code` before falling back on
+  the bare 402 status, so `payment_overdue`, `insufficient_credit` and an
+  older dispatcher's codeless 402 are told apart.
+- A session closed for want of credit says so ("stopped: out of credits")
+  and exits 4, instead of exiting 75 as if it were briefly unreachable.
+- `fcloud sweep` offers the fast lane only for waits more capacity can fix.
+  Tasks blocked on billing get a top-up hint — boosting past that block
+  buys nothing.
+- Python 3.9 is now supported (`requires-python >= 3.9`), and 3.14 is
+  tested. The README has a support grid; CI runs the suite on 3.9 through
+  3.14. The installer script falls back to `uv` instead of `pipx`/`pip`
+  when the system Python is older than 3.9.
+- The CLI no longer prints urllib3's LibreSSL warning on macOS's bundled
+  Python.
+
 ## [0.2.1] - 2026-09-14
 
 ### Added

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fcloud-sdk
-Version: 0.2.1
+Version: 0.3.1
 Summary: Python SDK and CLI for the fcloud GPU compute platform
 Author: fcloud
 License-Expression: Apache-2.0
@@ -11,14 +11,16 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
@@ -39,7 +41,7 @@ hosts, run commands and scripts on them, keep a persistent workspace between
 runs, move files in and out, and drive long-running or batch jobs — from a
 terminal, from Python, or from an AI coding agent.
 
-Requires Python 3.10+.
+Requires Python 3.9+ (see [Python versions](#python-versions)).
 
 ## Install
 
@@ -56,6 +58,28 @@ pip install fcloud-sdk
 fcloud login
 ```
 
+fcloud is prepaid — `fcloud credits buy 25` before your first run, and
+`fcloud credits` to see the balance.
+
+### Python versions
+
+Every row runs the full test suite in CI on every push (the matrix in
+`.github/workflows/unit-tests.yml` is the source of truth; a CI check fails
+if `pyproject.toml`'s classifiers drift from it).
+
+| Python | Status |
+|--------|--------|
+| 3.14   | supported |
+| 3.13   | supported |
+| 3.12   | supported |
+| 3.11   | supported |
+| 3.10   | supported |
+| 3.9    | supported (macOS command-line-tools Python, Debian 11) |
+| 3.8 and older | not supported; the installer script bootstraps `uv`, which fetches a supported Python |
+
+The installer only uses your system Python (`pipx`/`pip`) when it is 3.9 or
+newer; otherwise it installs `uv`, which brings its own.
+
 ## Setup
 
 `fcloud login` opens https://fcloud-home.vercel.app to sign in (Google or
@@ -188,6 +212,49 @@ with project.session(sku="gpu_1x_l4") as s:
 
 Errors raise `fcloud.FcloudError` (or a subclass such as `PaymentOverdueError`).
 
+## Porting from Modal
+
+`fcloud` exposes a Modal-compatible surface, so most Modal scripts port with an
+import rename:
+
+```python
+import fcloud as modal  # was: import modal
+
+app = modal.App("demo")
+image = modal.Image.debian_slim().pip_install("torch", "numpy")
+
+@app.function(image=image, gpu="H100", timeout=600)
+def train(steps: int) -> float:
+    ...
+
+@app.cls(gpu="L4", volumes={"/data": modal.Volume.from_name("weights", create_if_missing=True)})
+class Model:
+    @modal.enter()
+    def load(self): ...
+    @modal.method()
+    def predict(self, x): ...
+
+@app.local_entrypoint()
+def main(steps: int = 100):
+    print(train.remote(steps))
+    print(Model().predict.remote(1))
+```
+
+Run it with `fcloud run demo.py [--steps 500]` (the Modal-style `demo.py::name`
+picks an entrypoint or function). Each `(gpu, image, volumes)` combination gets
+one warm session; `.remote()` pickles the args, runs the function on the host
+and returns the pickled result, streaming stdout back live.
+
+Supported: `App`, `@app.function` / `@app.cls` / `@app.local_entrypoint`,
+`.remote()` / `.spawn()` / `.map()`, `Image.*` (varargs or list),
+`Volume.from_name`, `Secret.from_dict` / `from_dotenv` / `from_local_environ`,
+`gpu="H100"`, `"A100-80GB:8"`, etc. `cpu=`, `memory=`, `retries=` and similar
+options are accepted and ignored with a warning.
+
+Not supported: web endpoints, `Dict` / `Queue`, schedules, sandboxes,
+`Secret.from_name` (no hosted secret store), `modal deploy`. `.map()` runs
+inputs sequentially on one session; use `fcloud map` for real fan-out.
+
 ## Configuration
 
 API key, in order of precedence:

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/README.md

@@ -5,7 +5,7 @@ hosts, run commands and scripts on them, keep a persistent workspace between
 runs, move files in and out, and drive long-running or batch jobs — from a
 terminal, from Python, or from an AI coding agent.
 
-Requires Python 3.10+.
+Requires Python 3.9+ (see [Python versions](#python-versions)).
 
 ## Install
 
@@ -22,6 +22,28 @@ pip install fcloud-sdk
 fcloud login
 ```
 
+fcloud is prepaid — `fcloud credits buy 25` before your first run, and
+`fcloud credits` to see the balance.
+
+### Python versions
+
+Every row runs the full test suite in CI on every push (the matrix in
+`.github/workflows/unit-tests.yml` is the source of truth; a CI check fails
+if `pyproject.toml`'s classifiers drift from it).
+
+| Python | Status |
+|--------|--------|
+| 3.14   | supported |
+| 3.13   | supported |
+| 3.12   | supported |
+| 3.11   | supported |
+| 3.10   | supported |
+| 3.9    | supported (macOS command-line-tools Python, Debian 11) |
+| 3.8 and older | not supported; the installer script bootstraps `uv`, which fetches a supported Python |
+
+The installer only uses your system Python (`pipx`/`pip`) when it is 3.9 or
+newer; otherwise it installs `uv`, which brings its own.
+
 ## Setup
 
 `fcloud login` opens https://fcloud-home.vercel.app to sign in (Google or
@@ -154,6 +176,49 @@ with project.session(sku="gpu_1x_l4") as s:
 
 Errors raise `fcloud.FcloudError` (or a subclass such as `PaymentOverdueError`).
 
+## Porting from Modal
+
+`fcloud` exposes a Modal-compatible surface, so most Modal scripts port with an
+import rename:
+
+```python
+import fcloud as modal  # was: import modal
+
+app = modal.App("demo")
+image = modal.Image.debian_slim().pip_install("torch", "numpy")
+
+@app.function(image=image, gpu="H100", timeout=600)
+def train(steps: int) -> float:
+    ...
+
+@app.cls(gpu="L4", volumes={"/data": modal.Volume.from_name("weights", create_if_missing=True)})
+class Model:
+    @modal.enter()
+    def load(self): ...
+    @modal.method()
+    def predict(self, x): ...
+
+@app.local_entrypoint()
+def main(steps: int = 100):
+    print(train.remote(steps))
+    print(Model().predict.remote(1))
+```
+
+Run it with `fcloud run demo.py [--steps 500]` (the Modal-style `demo.py::name`
+picks an entrypoint or function). Each `(gpu, image, volumes)` combination gets
+one warm session; `.remote()` pickles the args, runs the function on the host
+and returns the pickled result, streaming stdout back live.
+
+Supported: `App`, `@app.function` / `@app.cls` / `@app.local_entrypoint`,
+`.remote()` / `.spawn()` / `.map()`, `Image.*` (varargs or list),
+`Volume.from_name`, `Secret.from_dict` / `from_dotenv` / `from_local_environ`,
+`gpu="H100"`, `"A100-80GB:8"`, etc. `cpu=`, `memory=`, `retries=` and similar
+options are accepted and ignored with a warning.
+
+Not supported: web endpoints, `Dict` / `Queue`, schedules, sandboxes,
+`Secret.from_name` (no hosted secret store), `modal deploy`. `.map()` runs
+inputs sequentially on one session; use `fcloud map` for real fan-out.
+
 ## Configuration
 
 API key, in order of precedence:

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/SKILL.md

@@ -88,6 +88,8 @@ ignored.
 | ---------------------- | ----------------------------------------- |
 | `fcloud health`          | Check API connectivity                    |
 | `fcloud set_token <key>` | Save API key                              |
+| `fcloud credits`         | Prepaid balance, auto-refill, card         |
+| `fcloud credits buy <usd>` | Buy credit (opens hosted checkout)      |
 
 
 ### Execution
@@ -987,6 +989,16 @@ fcloud wait s-abc123 "$PID" --timeout 0
 > alive (`fcloud logs <sid>` lists it as `running`) rather than assuming `rc=75`
 > means your job is gone.
 >
+> **Out of credit (`rc=4`).** A 402 with `code: insufficient_credit` means the
+> prepaid balance is exhausted: sessions are closed and queued jobs canceled.
+> **This is not retryable** — retrying returns the same refusal until credit
+> lands. Distinguish it from `rc=3` (`payment_overdue`, a failed payment on a
+> bill) and from `rc=75` (transient unreachability, which *is* retryable). The
+> remedy is `fcloud credits buy 25` or `fcloud credits autorefill on`; the block
+> clears about a minute after the credit posts. In the SDK it raises
+> `fcloud.InsufficientCreditError`, a sibling of `PaymentOverdueError` — code
+> that catches only `PaymentOverdueError` will not catch it.
+>
 > **Migration rides honor `--wait`.** When a foreground `exec` rides a
 > checkpoint/restore, the ride is bounded by your `--wait` budget — it never
 > blocks past it (`--wait 0` disables the bound; the ride then uses the full
@@ -1080,7 +1092,10 @@ fcloud exec --on s-abc123 /workspace/venv/bin/python train.py
 ```
 
 Better yet, put packages in the image spec (`pip_install([...])`) so every
-resume rebuilds them from the content-addressed image cache.
+resume rebuilds them from the content-addressed image cache. A sweep whose
+canary pip-installs packages gets them baked into its image automatically
+before the fan-out (the pass line names them; `--no-bake` disables) — but
+the pins still belong in `fcloud.json` so the *next* sweep never pays them.
 
 ---
 

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fcloud-sdk"
-version = "0.2.1"
+version = "0.3.1"
 description = "Python SDK and CLI for the fcloud GPU compute platform"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 authors = [{ name = "fcloud" }]
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 keywords = ["gpu", "cloud", "compute", "ml", "training", "cli"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -19,10 +19,12 @@ classifiers = [
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: System :: Distributed Computing",
     "Typing :: Typed",
@@ -61,13 +63,14 @@ testpaths = ["tests"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py39"
 
 [tool.ruff.lint]
-select = ["E", "F", "W", "I", "UP", "B"]
+select = ["E", "F", "W", "I", "UP", "B", "FA"]
 ignore = ["E741"]
 
 [tool.mypy]
+# mypy >= 1.19 cannot target 3.9; ruff (py39) and the CI 3.9 job cover the floor.
 python_version = "3.10"
 files = ["src/fcloud"]
 ignore_missing_imports = true

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/src/fcloud/SKILL.md

@@ -88,6 +88,8 @@ ignored.
 | ---------------------- | ----------------------------------------- |
 | `fcloud health`          | Check API connectivity                    |
 | `fcloud set_token <key>` | Save API key                              |
+| `fcloud credits`         | Prepaid balance, auto-refill, card         |
+| `fcloud credits buy <usd>` | Buy credit (opens hosted checkout)      |
 
 
 ### Execution
@@ -987,6 +989,16 @@ fcloud wait s-abc123 "$PID" --timeout 0
 > alive (`fcloud logs <sid>` lists it as `running`) rather than assuming `rc=75`
 > means your job is gone.
 >
+> **Out of credit (`rc=4`).** A 402 with `code: insufficient_credit` means the
+> prepaid balance is exhausted: sessions are closed and queued jobs canceled.
+> **This is not retryable** — retrying returns the same refusal until credit
+> lands. Distinguish it from `rc=3` (`payment_overdue`, a failed payment on a
+> bill) and from `rc=75` (transient unreachability, which *is* retryable). The
+> remedy is `fcloud credits buy 25` or `fcloud credits autorefill on`; the block
+> clears about a minute after the credit posts. In the SDK it raises
+> `fcloud.InsufficientCreditError`, a sibling of `PaymentOverdueError` — code
+> that catches only `PaymentOverdueError` will not catch it.
+>
 > **Migration rides honor `--wait`.** When a foreground `exec` rides a
 > checkpoint/restore, the ride is bounded by your `--wait` budget — it never
 > blocks past it (`--wait 0` disables the bound; the ride then uses the full
@@ -1080,7 +1092,10 @@ fcloud exec --on s-abc123 /workspace/venv/bin/python train.py
 ```
 
 Better yet, put packages in the image spec (`pip_install([...])`) so every
-resume rebuilds them from the content-addressed image cache.
+resume rebuilds them from the content-addressed image cache. A sweep whose
+canary pip-installs packages gets them baked into its image automatically
+before the fan-out (the pass line names them; `--no-bake` disables) — but
+the pins still belong in `fcloud.json` so the *next* sweep never pays them.
 
 ---
 

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/src/fcloud/__init__.py

@@ -22,6 +22,7 @@ import fcloud._legacy_env  # noqa: F401 — must run before any env read below
 from fcloud.client import (
     Client,
     FcloudError,
+    InsufficientCreditError,
     NoApiKeyError,
     PaymentOverdueError,
     SessionNotFoundError,
@@ -37,6 +38,16 @@ from fcloud.errors import (
 )
 from fcloud.image import Image
 from fcloud.job import Job  # noqa: F401
+from fcloud.modal_compat import (  # Modal-compatible surface: `import fcloud as modal`
+    App,
+    RemoteError,
+    Secret,
+    Volume,
+    enter,
+    exit,  # noqa: A004 — mirrors modal.exit
+    method,
+    parameter,
+)
 from fcloud.session import Project, Session
 from fcloud.sweeps import MapSpecError, SweepHandle  # noqa: F401
 from fcloud.types import (
@@ -61,6 +72,15 @@ __all__ = [
     "Image",
     "set_token",
     "get_token",
+    # Modal-compatible surface
+    "App",
+    "Secret",
+    "Volume",
+    "enter",
+    "exit",
+    "method",
+    "parameter",
+    "RemoteError",
     # Handles
     "Project",
     "Session",
@@ -76,6 +96,7 @@ __all__ = [
     "ClientTooOldError",
     "FcloudError",
     "FcloudRuntimeError",
+    "InsufficientCreditError",
     "MapSpecError",
     "NoApiKeyError",
     "PaymentOverdueError",

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/src/fcloud/__main__.py

@@ -50,6 +50,7 @@ from fcloud.cli.context import (  # noqa: F401
     _resolve_project,
     _resolve_volume_mounts,
 )
+from fcloud.cli.credits import cmd_credits  # noqa: F401
 from fcloud.cli.exec_cmd import _parse_exec_args, cmd_exec  # noqa: F401
 from fcloud.cli.files import (  # noqa: F401
     _download_file,

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/src/fcloud/_direct_bridge.py

@@ -99,6 +99,9 @@ _INLINE_BATCH_BYTES = 8 * 1024 * 1024
 # (connect, read) timeouts for direct S3 PUT/GET. The long read budget
 # covers multi-hundred-MB transfers.
 _BLOB_HTTP_TIMEOUT = (30, 3600)
+# How long _download_blob rides out 503 promotion_pending (a
+# region-local blob still promoting into R2) before giving up.
+_BLOB_PROMOTION_WAIT_S = 300.0
 # Pre-signed URLs expire (dispatcher TTL: 15 min) and the dispatcher caps
 # one presign request at 1000 hashes — so URLs are minted in small
 # per-chunk batches right before each chunk's PUTs. One up-front batch
@@ -333,6 +336,43 @@ def _config_from_env() -> _BridgeConfig:
     return _BridgeConfig(dispatcher_url=resolve_url(None))
 
 
+def _prefer_complete_output(
+    durable: ExecResult, captured: ExecResult,
+) -> ExecResult:
+    """Answer with whichever read saw more of the process's output.
+
+    The durable log is authoritative for retention accounting — it is the
+    host's own copy, and it holds output this client never streamed (frames
+    shed to a slow subscriber, a reconnect mid-run). But the host mirrors it
+    on a background goroutine that nothing joins against process exit, so a
+    read issued the instant `poll` reports "exited" can beat that write and
+    come back empty. That is not rare: it is the normal shape of a
+    block-buffered program, which flushes everything inside interpreter
+    teardown microseconds before the process dies. Returning that empty read
+    over bytes we already drained off the stream loses a user's last line —
+    the final `print(metrics)` of a training run.
+
+    So: never regress below what we already have. The host applies the same
+    rule to itself for combined reads (handle_request.go, "prefer it ...
+    whenever it has more bytes than the durable copy has flushed so far");
+    this is that rule for the per-stream reads the exec path makes.
+
+    A tie keeps the durable result, which carries the truthful truncation
+    and retention accounting.
+    """
+    if captured.stdout_total_bytes > durable.stdout_total_bytes:
+        durable.stdout = captured.stdout
+        durable.stdout_truncated = captured.stdout_truncated
+        durable.stdout_total_bytes = captured.stdout_total_bytes
+        durable.stdout_retained_bytes = captured.stdout_retained_bytes
+        durable.stdout_range = captured.stdout_range
+    # stderr carries no byte accounting on ExecResult, so length is the only
+    # comparison available.
+    if len(captured.stderr) > len(durable.stderr):
+        durable.stderr = captured.stderr
+    return durable
+
+
 class _DirectBridge:
     """Owns a background asyncio loop and one DirectClient per live
     session. Every public method is sync — callers don't see the
@@ -1106,24 +1146,25 @@ class _DirectBridge:
                 captured_err = capture_err.result(
                     output_limit_bytes, output_range,
                 )
-                durable = await self._durable_exec_result(
-                    client,
+                captured_result = self._captured_exec_result(
                     proc,
                     data,
                     start,
-                    output_limit_bytes,
-                    output_range,
+                    "exited",
+                    captured,
+                    captured_err,
                 )
-                if durable is not None:
-                    return durable
-                return self._captured_exec_result(
+                durable = await self._durable_exec_result(
+                    client,
                     proc,
                     data,
                     start,
-                    "exited",
-                    captured,
-                    captured_err,
+                    output_limit_bytes,
+                    output_range,
                 )
+                if durable is None:
+                    return captured_result
+                return _prefer_complete_output(durable, captured_result)
             if time.time() >= deadline:
                 await self._cancel_output_collection(collector)
                 captured = capture.result(output_limit_bytes, output_range)
@@ -1615,18 +1656,45 @@ class _DirectBridge:
 
     def _download_blob(self, file_hash: str) -> bytes:
         """Fetch a content-addressed blob from S3 via a dispatcher-minted
-        pre-signed GET URL."""
+        pre-signed GET URL.
+
+        A blob that lives only in a region-local bucket has no global (R2)
+        object to sign yet: the presign call funds its promotion and, if
+        that outlasts the server's wait budget, answers 503
+        promotion_pending + Retry-After. That is the common case for a
+        just-closed session's large outputs (small files come back inline
+        over the WS and never take this path), so wait it out rather than
+        surfacing it as a download failure."""
+        import time as _time
+
         import requests as _requests
 
         headers = _dispatcher_headers(self._cfg.api_key)
-        resp = _requests.post(
-            self._cfg.dispatcher_url + "/v1/blobs/download-url",
-            json={"hashes": [file_hash]},
-            headers=headers,
-            timeout=30,
-        )
-        data = resp.json()
-        _raise_if_client_too_old(resp.status_code, data)
+        deadline = _time.monotonic() + _BLOB_PROMOTION_WAIT_S
+        notified = False
+        while True:
+            resp = _requests.post(
+                self._cfg.dispatcher_url + "/v1/blobs/download-url",
+                json={"hashes": [file_hash]},
+                headers=headers,
+                timeout=30,
+            )
+            data = resp.json()
+            _raise_if_client_too_old(resp.status_code, data)
+            pending = (resp.status_code == 503
+                       and data.get("error") == "promotion_pending")
+            if pending and _time.monotonic() < deadline:
+                if not notified:
+                    print("fetching from cold storage — waiting for the file "
+                          "to be promoted…", file=sys.stderr)
+                    notified = True
+                try:
+                    delay = float(resp.headers.get("Retry-After", "5"))
+                except ValueError:
+                    delay = 5.0
+                _time.sleep(min(max(delay, 1.0), 30.0))
+                continue
+            break
         if resp.status_code >= 400 or "error" in data:
             raise FcloudRuntimeError(
                 data.get("error")

{fcloud_sdk-0.2.1 → fcloud_sdk-0.3.1}/src/fcloud/_legacy_env.py

@@ -7,6 +7,11 @@ spelling a value arrived under.
 """
 
 import os
+import warnings
+
+# macOS's bundled Python 3.9 links LibreSSL, and urllib3 warns on every import.
+# Nothing here needs TLS 1.3-era OpenSSL features; keep the CLI quiet.
+warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL")
 
 # ponytail: drop once nobody exports FOOM_* any more.
 for _k in [k for k in os.environ if k.startswith("FOOM_")]: