fcloud-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{fcloud_sdk-0.2.0 → fcloud_sdk-0.3.0}/CHANGELOG.md

@@ -4,6 +4,107 @@ All notable changes to the `fcloud` Python SDK and CLI are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [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 login`: sign in through the browser (device authorization). Shows a
+  short code, opens the approval page, and saves a key minted for this
+  machine (named `cli:<hostname>`); then installs the fcloud skill for the
+  coding agents present on the machine (`--agents auto`, the default; also
+  `all`, a list, or `none`). `--no-browser` prints the URL and code instead
+  of opening a browser. A fresh install's first command starts the same
+  login, and `fcloud setup` with no key delegates to it.
+- Spend visibility: `fcloud sessions` shows `$/HR` (the rate billed on the
+  session's open usage interval while a host is held, 0 when cold), `SPENT`
+  (compute charged so far) and `AGE` (time on its current host) per row plus
+  a "Spending now" footer; `--json` rows carry `usd_per_hour`, `spent_usd`
+  and `host_age_seconds` (SDK: `Client.session_cost`). New `fcloud usage [--since DUR|TS] [--until TS]`
+  reports what the account was charged over a window (default 30 days) by
+  resource and session (SDK: `Client.billing_usage`).
+
+### Changed
+- `fcloud job ls` shows each job's COMMAND and EXIT code (from its process
+  index; `--json` rows carry `command` and `exit_code`), so rows are
+  tellable apart and failures visible without opening each job.
+
+### Fixed
+- `fcloud logs <sid> <pid>` with a pid the dispatcher has no record of now
+  exits 1 (`process_not_found`) like `wait` and `kill`, instead of printing
+  an empty stream with exit 0 (and `status: ""` in `--json`) that a poller
+  read as a finished, silent process. A just-spawned pid gets a few seconds
+  to reach the durable index before it is called unknown.
+- `fcloud wait` with a `--timeout` shorter than the unknown-pid grace window
+  exits 1 for an unknown pid, not 75 (retry), so scripted callers stop
+  retrying a typo forever.
+- Cold starts of `run`/`exec`/`job run` no longer dump every host status
+  frame (`⟵ session_status: building (phase_change) setup_timing ...`);
+  the fresh-allocation and reconnect paths now use the same quiet printer
+  as warm attaches.
+- `fcloud sweep harvest` no longer pulls the session's virtual `_logs/`
+  directory (`_logs/processes.json`) for a results glob like `*.json`; name
+  `_logs/` in the glob to fetch logs.
+- `fcloud sessions` sizes the HOST and SKU columns to the data (27-char AWS
+  host ids overflowed the fixed width on every row).
+- `fcloud volume list` shows each volume's last update time.
+- SKILL.md documents `fcloud sessions --limit N`.
+
 ## [0.2.0] - 2026-09-08
 
 ### Added

{fcloud_sdk-0.2.0 → fcloud_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fcloud-sdk
-Version: 0.2.0
+Version: 0.3.0
 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,29 +41,61 @@ 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
 
+```bash
+curl -fsSL https://fcloud-home.vercel.app/install.sh | sh
+```
+
+That installs the CLI from PyPI (via `uv` or `pipx`), signs you in through
+the browser, and installs the fcloud skill for coding agents on your machine.
+With your own Python:
+
 ```bash
 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
 
-Create an account on https://fcloud-home.vercel.app.
-Enter a credit card, and copy your API key.
-Or just run any `fcloud` command (or `fcloud login`): a fresh install
-walks you through sign-up and saves the key you paste.
+`fcloud login` opens https://fcloud-home.vercel.app to sign in (Google or
+email) and add a card, then saves a key minted for this machine. Running any
+`fcloud` command on a fresh install starts the same login.
 
 ```bash
-fcloud setup            # prompts for the key; optionally installs the agent skill
+fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
+fcloud set_token <key>  # already have a key (CI, agents, a second machine)
+fcloud setup            # save a key you already have; install agent skills
 fcloud health           # verify connectivity
 ```
 
-`fcloud setup` also installs (by default) the fcloud skill file for supported
-coding agents (Cursor, Claude Code, Codex) so an agent can drive fcloud for you.
-Use `--agents none` to skip that.
+`fcloud login` installs the fcloud skill file for the coding agents it finds
+(Cursor, Claude Code, Codex — `--agents all` for every one) so an agent can
+drive fcloud for you. `fcloud setup --agents none` skips that.
 
 ## Quick start
 
@@ -141,6 +175,7 @@ Batch
   fcloud sweeps / fcloud sweep <status|logs|retry|cancel|wait> <name>
 
 Setup
+  fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
   fcloud setup [--token KEY] [--agents all|cursor|claude|codex|none]
   fcloud set_token <api-key>
   fcloud --version
@@ -177,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.0 → fcloud_sdk-0.3.0}/README.md

@@ -5,29 +5,61 @@ 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
 
+```bash
+curl -fsSL https://fcloud-home.vercel.app/install.sh | sh
+```
+
+That installs the CLI from PyPI (via `uv` or `pipx`), signs you in through
+the browser, and installs the fcloud skill for coding agents on your machine.
+With your own Python:
+
 ```bash
 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
 
-Create an account on https://fcloud-home.vercel.app.
-Enter a credit card, and copy your API key.
-Or just run any `fcloud` command (or `fcloud login`): a fresh install
-walks you through sign-up and saves the key you paste.
+`fcloud login` opens https://fcloud-home.vercel.app to sign in (Google or
+email) and add a card, then saves a key minted for this machine. Running any
+`fcloud` command on a fresh install starts the same login.
 
 ```bash
-fcloud setup            # prompts for the key; optionally installs the agent skill
+fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
+fcloud set_token <key>  # already have a key (CI, agents, a second machine)
+fcloud setup            # save a key you already have; install agent skills
 fcloud health           # verify connectivity
 ```
 
-`fcloud setup` also installs (by default) the fcloud skill file for supported
-coding agents (Cursor, Claude Code, Codex) so an agent can drive fcloud for you.
-Use `--agents none` to skip that.
+`fcloud login` installs the fcloud skill file for the coding agents it finds
+(Cursor, Claude Code, Codex — `--agents all` for every one) so an agent can
+drive fcloud for you. `fcloud setup --agents none` skips that.
 
 ## Quick start
 
@@ -107,6 +139,7 @@ Batch
   fcloud sweeps / fcloud sweep <status|logs|retry|cancel|wait> <name>
 
 Setup
+  fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
   fcloud setup [--token KEY] [--agents all|cursor|claude|codex|none]
   fcloud set_token <api-key>
   fcloud --version
@@ -143,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.0 → fcloud_sdk-0.3.0}/SKILL.md

@@ -25,6 +25,9 @@ fcloud set_token <api_key>  # one-time; saves to ~/.fcloud/token
 fcloud health               # verify connectivity
 ```
 
+(A human sets up with `fcloud login`, which signs in through the browser and
+mints a key for the machine; agents use `set_token` with a key they were given.)
+
 Token resolution order:
 
 1. `api_key=` parameter to `Client()`
@@ -85,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
@@ -303,7 +308,8 @@ filesystem later; a **job** for batch/CI-style runs with declared outputs.
 | Command                       | Description                                          |
 | ----------------------------- | ---------------------------------------------------- |
 | `fcloud create [--sku SKU]`     | Create a session (cold — $0, no host, until first used) |
-| `fcloud sessions [--all]`       | List sessions                                        |
+| `fcloud sessions [--all] [--limit N]` | List sessions with `$/HR` (billed rate), `SPENT` (compute so far) and `AGE` (time on its host) per row and a spending-now total (`--all --json` can be large; bound it with `--limit`) |
+| `fcloud usage [--since 24h]`   | What the account has been charged over a window (default 30 days), by resource and session |
 | `fcloud stop <session-id> [--wait]` | Stop a session now: halt GPU spend (files kept). `--wait` blocks until the workspace manifest is durable |
 
 
@@ -983,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
@@ -1076,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.
 
 ---
 
@@ -1215,6 +1234,8 @@ host (files restored from cloud storage) the next time you use it. You never run
 **Warmth**: `fcloud sessions` reports a session's state — `hot` (running, spending),
 `warm` (idle host held, spending), `stopping` (finishing teardown), `cold`
 (stopped, $0, resumes on use), or `preparing` (coming online).
+The `$/HR` column is the rate billed on the session's open usage interval while a
+host is held (0 when cold); `SPENT` is compute charged so far; the footer sums `$/HR`. `fcloud usage` reports what was actually charged.
 
 **Image**: Declarative container spec. Layers are cached by content hash. First run
 on a host triggers a build (30–120s); subsequent runs with the same image are instant.

{fcloud_sdk-0.2.0 → fcloud_sdk-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fcloud-sdk"
-version = "0.2.0"
+version = "0.3.0"
 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.0 → fcloud_sdk-0.3.0}/src/fcloud/SKILL.md

@@ -25,6 +25,9 @@ fcloud set_token <api_key>  # one-time; saves to ~/.fcloud/token
 fcloud health               # verify connectivity
 ```
 
+(A human sets up with `fcloud login`, which signs in through the browser and
+mints a key for the machine; agents use `set_token` with a key they were given.)
+
 Token resolution order:
 
 1. `api_key=` parameter to `Client()`
@@ -85,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
@@ -303,7 +308,8 @@ filesystem later; a **job** for batch/CI-style runs with declared outputs.
 | Command                       | Description                                          |
 | ----------------------------- | ---------------------------------------------------- |
 | `fcloud create [--sku SKU]`     | Create a session (cold — $0, no host, until first used) |
-| `fcloud sessions [--all]`       | List sessions                                        |
+| `fcloud sessions [--all] [--limit N]` | List sessions with `$/HR` (billed rate), `SPENT` (compute so far) and `AGE` (time on its host) per row and a spending-now total (`--all --json` can be large; bound it with `--limit`) |
+| `fcloud usage [--since 24h]`   | What the account has been charged over a window (default 30 days), by resource and session |
 | `fcloud stop <session-id> [--wait]` | Stop a session now: halt GPU spend (files kept). `--wait` blocks until the workspace manifest is durable |
 
 
@@ -983,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
@@ -1076,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.
 
 ---
 
@@ -1215,6 +1234,8 @@ host (files restored from cloud storage) the next time you use it. You never run
 **Warmth**: `fcloud sessions` reports a session's state — `hot` (running, spending),
 `warm` (idle host held, spending), `stopping` (finishing teardown), `cold`
 (stopped, $0, resumes on use), or `preparing` (coming online).
+The `$/HR` column is the rate billed on the session's open usage interval while a
+host is held (0 when cold); `SPENT` is compute charged so far; the footer sums `$/HR`. `fcloud usage` reports what was actually charged.
 
 **Image**: Declarative container spec. Layers are cached by content hash. First run
 on a host triggers a build (30–120s); subsequent runs with the same image are instant.

{fcloud_sdk-0.2.0 → fcloud_sdk-0.3.0}/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.0 → fcloud_sdk-0.3.0}/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,
@@ -119,6 +120,7 @@ from fcloud.cli.sweep import (  # noqa: F401
     cmd_sweep,
     cmd_sweeps,
 )
+from fcloud.cli.usage import cmd_usage  # noqa: F401
 from fcloud.cli.volume import (  # noqa: F401
     _is_within,
     _volume_cat,