# Python SDK

> Reference for the shardflux Python package 0.6.0 (Python 3.10+). Workspaces, commands, files, templates, agent tools, capture and the account plane.

## Install

```sh
pip install shardflux
pip install 'shardflux[yaml]'   # also reads template.yaml (templates.build_from_file)
```

This page describes `shardflux` **0.6.0** on PyPI. The package:

- needs Python 3.10 or later and depends only on `httpx`; the `yaml` extra adds PyYAML;
- is typed (`py.typed`);
- exports `shardflux.__version__` and sends `User-Agent: shardflux-sdk-python/<version>`.

Tool-call capture integrations have their own extras: `shardflux[claude-agent-sdk]`, `shardflux[openai-agents]`,
`shardflux[langchain]`, `shardflux[pydantic-ai]`, `shardflux[crewai]`.

A feature marked with a version, such as **(0.6.0+)**, is not in earlier releases. Check your version with
`python -c "import shardflux; print(shardflux.__version__)"`.

The Python SDK covers workspaces, exec, files, templates, secrets, tool-call capture, from 0.4.0 agent tool
definitions with terminals, processes, git and browser, from 0.5.0 the [account plane](#account)
(`ShardfluxAccount`), and from 0.6.0 the `search_files` and `edit_file` agent tools. Volumes, egress policies and
usage are in the
[TypeScript SDK](https://docs.shardflux.dev/reference/typescript.md), or call them with `sf.request(...)` or the [HTTP API](https://docs.shardflux.dev/reference/http-api.md).

## Quick start

Create a project API key in the console (`sfk_<key id>_<secret>`). An API key is a server credential; keep it out of
client-side code.

```python
from shardflux import Shardflux, format_timing

sf = Shardflux()  # reads SHARDFLUX_API_KEY; or Shardflux(api_key="...")


def open_workspace():
    return sf.open(key="customer-42/main", template="python-node-browser")


# 1. Open the workspace (created on first use) and run a command.
ws = open_workspace()
result = ws.exec("python3 -c 'print(40 + 2)'")
if result.exit_code != 0:
    raise RuntimeError(f"python3 exited {result.exit_code}: {result.stderr}")
print(result.stdout.strip())  # 42

# 2. Write a file, then suspend the workspace and wait until the suspend has finished.
ws.files.write("/home/user/notes.txt", "hello from Python\n")
ws.suspend(wait=True)  # returns once suspended: ws.state == "suspended"

# 3. Open the same key again: the workspace resumes, and the file is still there.
again = open_workspace()
print(again.files.read_text("/home/user/notes.txt"))  # hello from Python
print(format_timing(again.last_timing))  # where the resume's time went
```

`open()` waits until the workspace is running. Opening the same key again never resets it: files, installed packages
and running processes are still there. See [Workspaces](https://docs.shardflux.dev/concepts/workspaces.md) and [Lifecycle](https://docs.shardflux.dev/concepts/lifecycle.md).

## Configuration

| Argument | Environment variable | Default |
| --- | --- | --- |
| `api_key` | `SHARDFLUX_API_KEY` | required |
| `base_url` | `SHARDFLUX_API_URL` | `https://api.shardflux.dev` |
| `timeout` | | `30.0` seconds per request |
| `max_retries` | | `2` (safe or idempotent requests only) |
| `http_client` | | a new `httpx.Client` (pass your own for proxies or custom transports) |
| `user_agent` | | `shardflux-sdk-python/<version>` |
| `on_progress` | | none: a listener for the progress of every traced call (see [Timing and progress](#timing-and-progress)) |
| `version_check` **(0.5.0+)** | `SHARDFLUX_NO_UPDATE_CHECK=1` turns it off | `True`: warn once per process when this package is outdated (see [Update check](#update-check)) |

`Shardflux` is a context manager (`with Shardflux() as sf: ...`). `close()` closes the HTTP client it created and
flushes every tool-call capture of the client. A missing API key raises `ValueError`.

| Member | What it covers |
| --- | --- |
| `sf.open(...)` | Open a workspace by key (see below). |
| `sf.workspaces` | Look up, list and wait for workspaces and operations; lifecycle calls by id. |
| `sf.templates` | Templates, file trees, diffs, builds, uploads, test instances, drafts. |
| `sf.secrets` | Customer secrets (values are write-only). |
| `sf.me()` | The API key's organization, project and tool permissions. |
| `sf.request(method, path, **kwargs)` | Any `/v1` route with the client's authentication, retries and error handling. |

`ShardfluxAccount` **(0.5.0+)** is a second client, for what a person does in the console: see [Account](#account).

## Workspaces

### Open a workspace

```python
ws = sf.open(key="customer-42/main", template="python-node-browser", secrets=["OPENAI_API_KEY"])
```

`sf.open()` creates the workspace from the template's latest published version on first use and reconnects to or
resumes it afterwards. It never resets an existing workspace. A waiting open asks the API to hold the request until the
workspace is ready; the answer carries the first tool token, so the first tool call starts at once.

| Parameter | Default | Meaning |
| --- | --- | --- |
| `key` | required | Your stable name for the workspace (1-200 characters, no control characters). Keys starting with `sf:` are reserved. |
| `template` | required | Template slug. A new workspace uses its latest published version. |
| `caps` | none | `{"cpu_millis": ..., "memory_mib": ..., "disk_gib": ...}`. The ceiling is the lowest of template, cap and plan. |
| `agent_label` | none | Attribution label for tool tokens obtained through this handle. |
| `tools` | all the key permits | Tools to request in tool tokens: `exec`, `files`, `pty`, `process`, `git`, `browser`. |
| `secrets` | unchanged | Secret names to bind. Sets the binding of a new key and replaces it on an existing key. |
| `inputs` | unchanged | **(0.3.0+)** The template version's text inputs, `{"NAME": "value"}`. |
| `lifetime` | the version's default, else `persistent` | `"persistent"` or `"session"`. Reopening a live key with another value is 409 `lifetime_mismatch`. |
| `mode` | `processful` for a new key, else the stored mode | **(0.5.0+)** `"processful"` or `"file_first"` (a [file-first workspace](https://docs.shardflux.dev/concepts/file-first.md), ready at once). Reopening with the other mode is 409 `mode_mismatch`. |
| `wait` | `True` | Wait until ready. |
| `timeout` | `300.0` | Seconds to wait. |
| `on_progress` | none | Progress of this open. |

`sf.workspaces.open(...)` takes the same arguments plus `idempotency_key` (default: a fresh key per call),
`server_wait` (`True`), `poll_interval` (`0.25`) and `max_poll_interval` (`5.0`).

### Look up workspaces

```python
for w in sf.workspaces.list_all(key_prefix="customer-42/"):
    print(w.key, w.state)
page = sf.workspaces.list(limit=50)  # page.data, page.next_cursor
same = sf.workspaces.get(ws.id)
by_key = sf.workspaces.get_by_key("customer-42/main")  # None when no workspace has the key
```

| Method | Returns |
| --- | --- |
| `get(workspace_id)` | `Workspace` |
| `get_by_key(key, include_deleted=True)` | **(0.2.0+)** `Workspace` or `None`. Searches every lifetime and purpose; the live workspace wins over tombstones. |
| `list(state=, desired_state=, key_prefix=, include_deleted=, lifetime=, purpose=, limit=, cursor=)` | `Page[Workspace]` (`data`, `next_cursor`). By default only persistent standard workspaces: pass `lifetime="any"`, `purpose="any"` for sessions, drafts and test instances. |
| `list_all(**filters)` | An iterator over every page. |
| `operations(workspace_id, state=, kind=, limit=, cursor=)` | `Page[Operation]`, newest first. |
| `get_operation(operation_id)` | `Operation` |
| `wait_for_operation(operation_id, timeout=300.0, poll_interval=0.25, max_poll_interval=5.0, server_wait=True, on_progress=None)` | The succeeded `Operation`. |

### The workspace handle

| Property | Meaning |
| --- | --- |
| `id`, `key` | Workspace id and key. |
| `state`, `desired_state`, `ready` | Observed state, desired state (`running`, `suspended`, `deleted`), and whether both are `running`. |
| `cell_endpoint` | The workspace's cell gateway. |
| `lifetime`, `is_session`, `idle_timeout_seconds`, `ended_reason`, `deleted_at` | **(0.2.0+)** Session metadata. |
| `disk_layout`, `purpose`, `origin`, `dev_template_id`, `update_policy` | **(0.2.0+)** Template metadata. `disk_layout` is `legacy` or `layered`. |
| `startup` | **(0.3.0+)** Start commands and services: `state` `pending`, `running`, `ready` or `failed` (with `step`, `service`, `exit_code`, `output_tail`, `reason`). None when the version has neither. |
| `last_timing` | **(0.2.0+)** Timing of the last open, wake or lifecycle call. |
| `mode`, `tree_revision` | **(0.5.0+)** `processful` or `file_first`; a file-first workspace's newest tree revision seen by this handle (from the view, `X-Tree-Revision` of every cell response and execution results; it never moves back), `None` for a processful one. |
| `executions` | **(0.5.0+)** File-first workspaces: `run()` and `get()` (see [Executions](#executions)). |
| `suspend_request` | **(0.6.0+)** The pending [suspend when idle](https://docs.shardflux.dev/concepts/lifecycle.md#suspend-when-idle) request, `SuspendRequest(requested_at, after_seconds, not_before)`, as of the last view; None when there is none. |
| `files`, `secrets` | File and secret-binding clients. |
| `data` | The raw view. |

Methods: `exec()`, `refresh()`, `wait_until_ready(timeout=300.0)`, `inputs()`, the lifecycle calls, `wake()`,
`hint()` **(0.5.0+)**,
`cell()`, `tokens()`, `changes()`, `save_as_template()` and `capture_tool_calls()`.

### Lifecycle calls

```python
ws.suspend(wait=True)  # memory and processes are checkpointed; returns once suspended
ws.resume(wait=True)   # or open() the key again

copy = ws.fork("customer-42/experiment")  # waits until the fork is running
copy.delete()  # tool access ends at once; keys are never reused
```

| Call | Default | Returns |
| --- | --- | --- |
| `ws.suspend(wait=False, timeout=300.0, on_progress=None)` | requested | `Operation` |
| `ws.suspend_when_idle(after_seconds=, idempotency_key=None)` | recorded | **(0.6.0+)** `SuspendWhenIdleResult(suspend_request, operation, workspace)`; see below |
| `ws.cancel_suspend_when_idle()` | cancelled | **(0.6.0+)** The `Workspace` (idempotent) |
| `ws.resume(...)` | requested | `Operation` |
| `ws.snapshot(label=None, ...)` | requested | `Operation` |
| `ws.delete(...)` | requested | `Operation` |
| `ws.close(...)` | requested | **(0.2.0+)** `Operation`, or `None` for a persistent workspace |
| `ws.reset(...)` | requested | **(0.2.0+)** `Operation` |
| `ws.fork(key, caps=None, lifetime=None, wait=True, timeout=300.0)` | **finished** | the new `Workspace` |

Without `wait` a call returns when the change is **requested**: the operation is usually still `queued` and the
workspace unchanged. With `wait=True` it returns when the change has **finished**, with the succeeded operation and the
handle refreshed. `fork()` works the other way round: it waits by default; pass `wait=False` to get the copy as soon as
the fork is requested.

On a [file-first workspace](https://docs.shardflux.dev/concepts/file-first.md), `suspend`, `resume`, `snapshot`, `fork`, `reset` and
`save_as_template` raise `NotSupportedForModeError` without a request **(0.5.0+)**.

The same calls on `sf.workspaces` take the workspace id first and `wait=False` by default:
`sf.workspaces.suspend(workspace_id, wait=True)`. `sf.workspaces.fork(workspace_id, key, ...)` returns
`(operation, workspace)`.

**(0.6.0+)** `ws.suspend_when_idle(after_seconds=60)` is [suspend when idle](https://docs.shardflux.dev/concepts/lifecycle.md#suspend-when-idle),
for the end of an agent turn: the workspace is suspended once it has been idle for `after_seconds` (30 to 3600),
counted from the later of its last work and the request. The next tool call or a resume cancels it; a running command,
attached stream or keepalive postpones it. `result.operation` is the suspend already in progress (then
`result.suspend_request` is None and nothing is recorded), else None. `ws.suspend_request` shows a pending request.
Errors: `ShardfluxApiError` 409 with `reason` `not_running`, `operation_in_progress`, `session_lifetime` or
`workspace_deleted`, and 422 `validation_failed` outside 30..3600. By id: `sf.workspaces.suspend_when_idle(workspace_id,
after_seconds=60)` and `sf.workspaces.cancel_suspend_when_idle(workspace_id)`.

A failed operation raises `OperationFailedError`. If `timeout` passes first, `OperationTimeoutError` is raised and the
operation keeps running: wait again with `sf.workspaces.wait_for_operation(err.operation_id)`. Waiting asks the API to
hold each poll until the operation changes (at most 20 s per request); against a server that does not, it polls with
backoff (250 ms doubling to 5 s, ±20 % jitter).

### Starts that wait for capacity

An open, resume or fork that no host can admit yet waits in `capacity_pending` for at most 15 minutes. The deadline is
in `error["details"]["deadline_at"]`, on the `phase` progress event as `deadline_at` **(0.2.1+)**, and on
`OperationTimeoutError.deadline_at` when your wait ends first. A start still pending at the deadline fails with
`capacity_unavailable`: nothing was started, and a suspended workspace stays suspended. `OperationFailedError.retryable`
**(0.2.1+)** is `True` for it. The client does not retry it for you.

```python
from shardflux import OperationFailedError

try:
    ws.resume(wait=True)
except OperationFailedError as err:
    if not err.retryable:
        raise
    print(f"{err.error_code}: no host had room; nothing changed. Try again later.")
```

### Sessions, reset and changes

**(0.2.0+)** A session workspace is discarded when its session ends: `close()`, or the idle timeout
(`idle_timeout_seconds`, 600 unless the template sets one). The key then opens a new, empty workspace.

```python
with sf.open(key="agent-7/task", template="python-node-browser", lifetime="session") as job:
    job.exec("python3 -c 'print(1)'")
# Leaving the block called job.close(). For a persistent workspace close() makes no API call.

ws.reset(wait=True)  # layered workspaces: wipe every change, back to the template
page = ws.changes(path_prefix="/home/user", hash=True, summary=True)
for c in page.data:
    print(c.change, c.path)  # added, modified, metadata, deleted, replaced
```

Reset, `changes()` and `save_as_template()` need a `layered` workspace; a legacy one is refused with 409
`legacy_disk_layout`. A session cannot be suspended (409 `session_lifetime`); fork it to keep its state.

### Timing and progress

**(0.2.0+)** Every open, wake and lifecycle call is traced. `ws.last_timing` (and `err.timing` when the call fails) is a
`LifecycleTiming` dataclass (`phases`, `retries`, `server`, `outside_server_ms`, ...); `format_timing()` prints it:

```text
open 34.18 s, succeeded (workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342, operation 01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33)
  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 590 ms → view 42 ms ∥ token 61 ms
  server: queued 33.40 s, ran 620 ms, total 34.02 s; start warm, boot to ready 79 ms
  outside the server: 160 ms
```

Pass `on_progress` to the client for every call, or per call (`sf.open(...)`, lifecycle calls,
`wait_for_operation()`, `ws.wake()`, `ws.cell()`):

```python
import sys

from shardflux import ProgressEvent, Shardflux, format_timing


def progress(e: ProgressEvent) -> None:
    if e.type == "phase":
        print(f"{e.action}: {e.phase} ({e.reason}) at {e.at_ms} ms", file=sys.stderr)
    elif e.type == "retry" and e.retry:
        print(f"{e.action}: retry {e.retry.request}: {e.retry.cause}", file=sys.stderr)
    elif e.type == "done" and e.timing:
        print(format_timing(e.timing), file=sys.stderr)


sf = Shardflux(on_progress=progress)
```

A `ProgressEvent` has `type` (`phase`, `retry` or `done`), `action`, `workspace_id`, `operation_id`, `at_ms`,
`phase`, `reason`, `retry`, `timing` and `deadline_at`. A listener that raises never breaks the call.

## Commands

```python
r = ws.exec("pip install requests && python3 app.py", cwd="/home/user/project", env={"DEBUG": "1"}, timeout=600)
r = ws.exec(["python3", "-V"])  # a list runs as argv, without a shell
print(r.exit_code, r.stdout, r.stderr, r.timed_out, r.ok)
```

`ws.exec(cmd, ...)` runs a command and waits for it to exit. A string runs through `bash -lc`; a list runs as argv.
If the connection drops, it resumes the output from byte offsets; it never starts the command twice. Ctrl-C cancels
the command in the workspace.

| Parameter | Default | Meaning |
| --- | --- | --- |
| `cwd`, `env`, `user` | | Working directory, an absolute path (default `/home/user`; the API refuses a relative one with 422 `invalid_cwd`), extra environment, guest user. |
| `stdin` | | `str` or `bytes` written to stdin. |
| `timeout` | | Seconds, enforced inside the workspace; the result then has `timed_out=True`. |
| `session_id` | generated | Session id; starting an existing session never runs anything again. |
| `secret_refs` | | Extra secret names injected into this process only. |
| `max_output_bytes` | `1048576` | Bytes of stdout and of stderr kept in memory. |
| `on_output` | | `on_output(stream, chunk)` for output as it arrives. |

`ExecResult`: `session_id`, `exit_code`, `term_signal`, `timed_out`, `canceled`, `stdout`, `stderr`, `stdout_bytes`,
`stderr_bytes`, `truncated`, `reconnects`, `session`, and `ok` (`exit_code == 0`).

**(0.6.0+)** A command that could not start (a `cwd` that is not a directory, a program that is not on `PATH`, an
unknown `user`) raises `ExecStartError`: nothing ran, so there is no exit code. Its message is the workspace's reason,
for example `The command could not start: working directory "/home/user/app" is not a directory`. Before 0.6.0,
`ws.exec()` returned `exit_code=None` with empty output.

```python
from shardflux import ExecStartError

try:
    ws.exec(["python3", "main.py"], cwd="/home/user/app")
except ExecStartError as err:
    print(err.message, err.session_id)
```

## Files

```python
ws.files.write("/home/user/data.bin", b"\x00\x01\x02", create_parents=True)
data = ws.files.read("/home/user/data.bin")  # bytes, the whole file
text = ws.files.read_text("/home/user/notes.txt")
ws.files.list("/home/user")  # {"entries": [...], "truncated": False}
ws.files.stat("/home/user/notes.txt")
ws.files.remove("/home/user/data.bin")
```

| Method | Returns |
| --- | --- |
| `read(path, offset=None, length=None)` | `bytes` |
| `read_text(path, encoding="utf-8")` | `str` |
| `write(path, data, mode=None, create_parents=None, append=None, idempotency_key=None)` | `dict`: `path`, `bytes_written`, `sha256`, `durable` |
| `read_with_info(path, offset=None, length=None)` | **(0.5.0+)** `FileRead(data, size, revision, served_from)`: the bytes plus `X-File-Size`, `X-File-Revision` (files up to 16 MiB) and `X-Served-From`. |
| `list(path, limit=None)` | `dict`: `entries`, `truncated` |
| `stat(path, revision=False)` | `dict`; with `revision=True` **(0.5.0+)** also `revision`, the SHA-256 of the content (regular files up to 256 MiB). |
| `remove(path, recursive=None, if_tree_revision=None)` | `None` |
| `search(path, pattern, regex=, case_insensitive=, include=, exclude=, max_matches=, max_file_bytes=, context_lines=)` | **(0.5.0+)** `dict`: `matches`, `truncated`, `stop_reason`, `files_scanned`, `served_from`. Read-only, retried like a `GET`. |
| `patch(path, edits=None, content=None, expected_revision=None, create_parents=None, mode=None, idempotency_key=None, if_tree_revision=None)` | **(0.5.0+)** `dict`: `path`, `revision`, `previous_revision`, `bytes_written`, `durable`, `replacements`, `file`. `edits` are `{"old_text", "new_text", "replace_all"?}`, each matching exactly once unless `replace_all`, all or none. Exactly one of `edits` and `content`, else `ValueError` before any request. Always sends an `Idempotency-Key`. |

Writes are atomic and durable: they are acknowledged after the file and its directory are fsynced. `write` also takes
`if_tree_revision` **(0.5.0+)**, like `remove` and `patch`: on a file-first workspace the change applies only at that
tree revision, else `TreeRevisionMismatchError`. [Search and edit files](https://docs.shardflux.dev/guides/files.md) explains search, patches,
revisions and their refusals.

## Executions

**(0.5.0+)** On a [file-first workspace](https://docs.shardflux.dev/concepts/file-first.md), `ws.executions` runs each command in a fresh VM on the
workspace's files:

```python
run = ws.executions.run("npm test", cwd="/home/user/app", timeout=600)
if run.state != "succeeded":
    raise RuntimeError(f"{run.state}: {run.error_reason}")  # nothing was published
print(run.exit_code, run.text(), run.changed, run.tree_revision)
```

| `executions.run(cmd, ...)` | Default | Meaning |
| --- | --- | --- |
| `cmd` | required | A string runs through `bash -lc`; a list runs as argv. |
| `execution_id` | a fresh `ex-<uuid>` | The idempotency key (8-128 characters of `A-Z a-z 0-9 . _ : -`, else `ValueError`). The same id with the same request returns the recorded result (`replayed=True`); with another request, 409 `execution_id_reused`. |
| `cwd`, `env`, `stdin`, `timeout`, `user`, `secret_refs` | | As for `ws.exec()` (`cwd` under `/home/user`). |
| `output_limit_bytes` | 1 MiB | stdout and stderr are each kept up to this many bytes (at most 16 MiB). |
| `max_retries` | `5` | Retries with the same id after network failures and retryable 429/502/503/504 answers such as 503 `no_execution_host` (`Retry-After` honoured up to 30 s). |
| `attempt_timeout` | `300` | Longest single wait for the answer, in seconds; then the request is sent again with the same id and joins the running execution (not counted as a failure). |

`ExecutionResult`: `execution_id`, `state` (`succeeded`, `failed`, `lost`), `exit_code`, `term_signal`, `timed_out`,
`stdout` and `stderr` (bytes) with `text()`, `stdout_truncated`, `stderr_truncated`, `base_revision`,
`tree_revision`, `changed` (`ExecutionChange(path, change, type)`), `changed_truncated`, `timings`, `error` and
`error_reason`, `created_at`, `finished_at`, `replayed`, `ok`, `pending` and `raw`. A `failed` or `lost` result is
returned, not raised, and never retried with a new id.

`ws.executions.get(execution_id, wait=None)` reads an execution: its result, or a pending one while it runs; `wait`
(seconds) polls until it ended or the time passed. Results are kept for 7 days. `new_execution_id()` makes an id. On a
processful workspace `executions` and `if_tree_revision` raise `NotSupportedForModeError` without a request, and on a
file-first workspace `ws.exec()` does (use `executions.run()`).

## Wake on use

**(0.2.0+)** A tool call (`exec`, `files`, `changes`) on a suspended workspace resumes it (or joins the resume or open
already running), then runs. A call made during a suspend or resume waits for the transition. The call never runs
twice: the workspace executes nothing it refused.

- The wait is bounded per call by `transition_timeout` (default 120 s), shared by the transition waits and at most 3
  wakes. A resume or open still pending at the end raises `OperationTimeoutError`; a failed one raises
  `OperationFailedError` at once.
- Following an exec's output never wakes a workspace, so an explicit `suspend()` is respected.
- `ws.wake(timeout=120.0)` does the same on demand: `True` when it resumed or waited, `False` when the workspace was
  already running. `agent_label` and `tools` **(0.5.0+)** choose the tool token the wake brings back.
- **(0.5.0+)** The wake is one request: a resume with `Prefer: wait` and the client's agent label and tools, answered
  once the workspace runs with the view and a tool token, so the refused call is retried at once. `resume(wait=True)`
  sends the same request (`server_wait=False` keeps the polled path). Against an API without the held resume, the
  client waits for the operation and fetches a token, as before.
- **(0.5.0+)** `read`, `read_text`, `read_with_info`, `stat`, `list` and `search` of a suspended workspace are answered
  from its disk while a host still holds it, without waking it (`served_from == "disk"`). Any other call wakes it.

**Wake hint (0.5.0+).** A running workspace that nobody uses is
[parked](https://docs.shardflux.dev/concepts/lifecycle.md#idle-running-workspaces-are-parked) by its host and woken by the next tool call.
`ws.hint(agent_label=None, tools=None, wake=True, wake_timeout=120)` tells the host a call is coming, so the wake
starts earlier: call it when your model starts writing a tool call. It returns at once with `WakeHint(residency,
wake)`: `residency` is what the host found (`resident`, `frozen`, `hibernated`, `restoring`; `None` when the workspace
was not running), and for a suspended workspace `wake` is a `concurrent.futures.Future` of the resume started in a
background thread (shared by concurrent hints; nothing needs to wait for it). `wake=False` only reports. It is never
retried and never waits out `workspace_busy`.

```python
cell = ws.cell(transition_timeout=30)  # give up waking after 30 s
cell.exec_run(["make", "test"])        # resumes the workspace first if it is suspended
no_wake = ws.cell(wake=None)           # returns workspace_not_running instead of waking
```

`ws.cell(agent_label=None, tools=None, wake=..., transition_timeout=120.0, on_progress=None)` returns the lower-level
`CellClient`: `exec_run(argv, ..., timeout_ms=, kill_grace_ms=, max_reconnects=10, cancel_on_interrupt=True)`,
`exec_start`, `exec_get`, `exec_cancel`, `files_read`, `files_write`, `files_list`, `files_stat`, `files_remove`,
`changes` and `request`; **(0.5.0+)** `files_search`, `files_patch`, `files_stat(revision=)`, `files_read_with_info`,
`wake_hint`, `execution_run` and `execution_get`; **(0.4.0+)** `processes_list`, `processes_signal`, `pty_open`, `pty_get`, `pty_input`,
`pty_resize`, `pty_close`, `pty_attach` (the attach WebSocket), `pty_read`, `git_clone`, `git_status`, `git_commit`,
`browser_screenshot` (PNG bytes) and `browser_content`.

## Templates

See [Templates](https://docs.shardflux.dev/concepts/templates.md) and [Build a template](https://docs.shardflux.dev/guides/build-a-template.md).

### List and inspect

```python
detail = sf.templates.get("python-node-browser")          # versions with their settings (0.3.0+)
sf.templates.list(owner="platform").data
sf.templates.files("python-node-browser", 3, "/home/user")  # one directory level of a version
sf.templates.file_entry("python-node-browser", 3, "/usr/bin/python3")
sf.templates.diff("my-agent", from_="base", to=2)            # .data: path, change, before, after; .summary
```

| Method | Returns |
| --- | --- |
| `list(owner=, include_archived=, limit=, cursor=)`, `list_all(...)` | Templates the key's organization can use. |
| `get(slug, owner=, include_archived=)` | One template: versions, settings, what `open` resolves to. |
| `files(slug, version, path="/", limit=, cursor=, owner=)` | **(0.2.0+)** One directory of a version's file tree. |
| `file_entry(slug, version, path, owner=)` | **(0.2.0+)** One entry. |
| `diff(slug, from_=, to=, path_prefix=, change=, limit=, cursor=, owner=)` | **(0.2.0+)** Diff between two versions (`from_` may be `"base"`). |
| `versions.recipe(slug, version)` | **(0.3.0+)** The recipe and settings a version was built from, ready to build again. |
| `languages(base)` | **(0.3.0+)** Languages a base (`<slug>@<version>`) offers `build.languages`. |
| `packages.search(ecosystem, q, base=, limit=)`, `packages.get(ecosystem, name, base=)` | **(0.3.0+)** apt, pip or npm packages. apt needs `base`. |

### Build from template.yaml

**(0.3.0+)** `template.yaml` is a recipe v2: a base, languages, packages, files, build steps and the settings every
workspace of the template gets (environment, open-time inputs, start commands, services, defaults). Reading YAML needs
`pip install 'shardflux[yaml]'`; a JSON file needs nothing, and `parse_yaml=` accepts any parser.

```yaml
base: python-node-browser@7        # services need a base whose agent runs them
build:
  languages:
    - id: go
  packages:
    apt: [jq]
    pip:
      requirements: [/home/user/app/requirements.txt]
  files:
    - from: app                   # a local folder, relative to this file: uploaded as a tar
      to: /home/user/app
      owner: user
    - from: config/settings.toml  # a local file, uploaded byte for byte
      to: /home/user/.config/app/settings.toml
      owner: user
      mode: "0600"                # quote modes: YAML reads 0600 as a number
settings:
  env:
    APP_ENV: development
  inputs:
    PROJECT_NAME: {kind: text, default: demo}
  services:
    web:
      run: python -m http.server 8000
      cwd: /home/user/app
      ready: {port: 8000}
```

```python
result = sf.templates.build_from_file("template.yaml", template_slug="my-agent", wait=True)
print(result.build["state"], result.build["registration"]["state"])  # "published", "registered" once usable
print(result.build["provenance"]["recipe_sha256"])
for u in result.uploads:  # one per local source
    print(u["from"], u["sha256"], "uploaded" if u["uploaded"] else "already there")
```

`build_from_file(path, template_slug, display_name=, description=, auto_publish=, acknowledged_scan_findings=,
organization_id=, wait=False, timeout=1800.0, parse_yaml=, on_progress=, idempotency_key=)`:

- Each `from` is packed (a folder: a reproducible, uncompressed tar, the same bytes on every machine and in the
  TypeScript SDK), hashed and uploaded unless the organization already has those bytes; the recipe is sent with
  `upload: "sha256:<hex>"` instead.
- Refused before any request, as `TemplateFileError`: `from` together with `upload`, a folder with `kind: file`, a
  compressed archive, sockets, FIFOs or devices in a folder, absolute symlinks or symlinks that leave the folder, more
  than 200,000 entries, more than 5 GiB, a schema other than `shardflux.template-recipe.v2`.
- The API validates the rest: 422 `validation_failed` with `details["field"]` and `details["reason"]`.
- Without `wait=True` the call returns the queued build; `on_progress` receives `pack`, `upload` and `build` events.

The pieces on their own:

| Call | Does |
| --- | --- |
| `pack_directory(folder, dest)` | The reproducible tar of a folder; returns `PackResult(sha256, size, entries)`. |
| `load_template_file(path, parse_yaml=None)` | Reads a template file. |
| `sf.templates.uploads.put(data, kind, sha256=, size=)` | Uploads bytes, a path or a binary file object unless the organization has them; returns `UploadResult(upload, ref, uploaded)`. |
| `sf.templates.builds.create(template_slug, recipe, ...)` | Queues a build of a recipe v1 or v2. |
| `sf.templates.builds.wait(build_id, timeout=1800.0, on_change=None)` | Waits until the build settles; raises `TemplateBuildTimeoutError` (the build continues). |
| `sf.templates.builds.get`, `list`, `list_all`, `cancel`, `log_url`, `builder_availability` | Builds of the API key's organization (`organization_id=` to choose). |

### Test instances, inputs and startup

```python
with sf.templates.version_test_instances.create("my-agent", 4, inputs={"PROJECT_NAME": "try"}) as test:
    test.exec("curl -s localhost:8000")

ws = sf.open(key="customer-42/main", template="my-agent", inputs={"PROJECT_NAME": "acme"})
ws.inputs()   # {"PROJECT_NAME": "acme"}
ws.startup    # {"state": "ready", ...}; None without start commands or services
```

A version test instance **(0.3.0+)** is a throwaway session on any version, published or not. A failed start command or
service leaves the workspace running with `startup["state"] == "failed"`; the next `open` runs the failed step again.
Inputs the version does not declare are 422 `input_unknown`; a missing required one is `input_required`.

### Dev mode (drafts)

```python
draft = sf.templates.draft("my-agent")
d = draft.create(base="python-node-browser@3")
d.workspace.exec("pip install -r requirements.txt")
state = draft.capture_state(label="deps", wait=True).result["checkpoint_id"]
with draft.open_test_instance(state_id=state) as test:  # a disposable copy of that state
    test.exec("python3 -m pytest")
draft.publish(state_id=state, description="deps")  # the next version
draft.discard()
```

`draft.get()`, `states()` and `test_instances(include_ended=)` read the draft. Drafts and test instances are for
owners, admins and API keys with a tool permission (others get 403 `template_dev_mode_role`).
`ws.save_as_template(template_slug, ...)` saves a layered workspace as the next version of an organization template.

## Secrets

Values are write-only: no API returns them. Every `exec` and terminal in a workspace receives the secrets bound to it,
plus any the call names in `secret_refs`.

```python
import os

project_id = sf.me()["api_key"]["project_id"]
sf.secrets.create(project_id, "OPENAI_API_KEY", os.environ["OPENAI_API_KEY"])

ws = sf.open(key="customer-42/main", template="python-node-browser", secrets=["OPENAI_API_KEY"])
ws.secrets.get()  # {"names": [...], "secrets": [{"name", "status", "secret_id", "scope"}]}
ws.secrets.set(["OPENAI_API_KEY", "DATABASE_URL"])  # replace; [] clears
```

`sf.secrets` has `create(project_id, name, value, description=, allowed_workspace_ids=, allowed_tools=)`, `list`,
`get`, `update`, `rotate`, `versions`, `delete`, `access_events`, `create_organization` and `list_organization`.
Permission arguments you do not pass are left alone (`UNSET`); `None` means no restriction. Organization-wide secrets
and access logs belong to owners and admins, so a project API key gets 403 for those.

- An unknown name, or a secret this workspace may not use, raises `ShardfluxApiError` 422
  (`err.reason == "secret_not_available"`, `details["names"]`); nothing changes.
- Binding status per name: `available`, `not_allowed` (starts are refused with 403 until fixed) or `deleted`.

## Agent tools

**(0.4.0+)** Your application keeps the agent loop and the model calls; the workspace is the computer the agent's tools
act on. `workspace_tools(ws)` returns the same tools as the TypeScript SDK's `workspaceTools()`, with the same names
and JSON Schemas: 17 from 0.6.0, which adds `search_files` and `edit_file` (15 before). The
[agent tools guide](https://docs.shardflux.dev/guides/agent-tools.md) lists them and has a complete loop.

```python
from shardflux import execute_tool_call, to_anthropic_tools, to_openai_tools, workspace_tools

tools = workspace_tools(ws, tools=["exec", "files"])
anthropic_tools = to_anthropic_tools(tools)                # Anthropic Messages API
responses_tools = to_openai_tools(tools, api="responses")  # OpenAI Responses API (default: Chat Completions)

output = execute_tool_call(tools, block)  # a tool_use block, an OpenAI tool call or function_call item, or a dict
```

| Function | Returns |
| --- | --- |
| `workspace_tools(ws, tools=None, agent_label=None, prefix="", max_output_bytes=65536, default_cwd=None, wake=..., transition_timeout=120.0, hint=True)` | `list[WorkspaceTool]`: `name`, `description`, `parameters`, `permission`, `execute(args, tool_call_id=None)`. Default tools: those of `ws.granted_tools`, else all six permissions. `wake=None` refuses instead of resuming. **(0.6.0+)** `hint=True` sends a wake hint in the background when a call starts, except for `read_file`, `list_files` and `search_files`; `hint=False` turns it off. |
| `to_anthropic_tools(tools)` | `[{"name", "description", "input_schema"}]` |
| `to_openai_tools(tools, api="chat")` | Chat Completions tools; with `api="responses"`, Responses API tools |
| `execute_tool_call(tools, call)` | The tool's result, a JSON-serializable dict. The call's `call_id` or `id` is passed on as `tool_call_id`. |
| `capture.tools(tools)` | Copies whose calls tool-call capture records with the model's call id. |

`execute_tool_call` raises `ToolArgumentError` for an unknown tool, arguments that are not JSON or do not match the
schema, before anything is sent; errors from the workspace (`ShardfluxApiError`) propagate. Send either back to the
model as an error result. The tools are synchronous; in async code, run them with `asyncio.to_thread`.

## Tool-call capture

**(0.3.0+)** Your harness runs the model loop and your own tools. Tool-call capture saves every call's input and output
as files in the workspace, so the agent can work on them with `jq` or pandas, and snapshots and forks keep them.

```python
capture = ws.capture_tool_calls()  # one run directory under /home/user/tool-calls
my_tools = {"web_search": lambda query: {"query": query, "results": []}}

with capture.call("web_search", {"query": "weather oslo"}, call_id="toolu_01") as call:
    call.output = my_tools["web_search"](query="weather oslo")
# or afterwards: capture.record("web_search", {"query": "weather oslo"}, output, call_id="toolu_01")

capture.flush(timeout=30)
```

- A wrapped tool returns the same object and raises the same exception; sync stays sync, async stays async.
- Writes happen on background threads. Nothing capture raises reaches your code: failures go to `on_error` (a
  `CaptureError`) and `capture.stats`.
- `@capture_tool` (late-bound to the capture made active with `with capture.activate():`), `@capture.tool` and
  `capture.wrap(fn)` wrap decorated tools. Stack `@capture_tool` directly under the framework's decorator; the
  framework still sees the same signature, docstring, type hints and async-ness.

| Framework | Integration |
| --- | --- |
| Claude Agent SDK | `from shardflux.integrations.claude_agent_sdk import capture_hooks`; `ClaudeAgentOptions(hooks=capture_hooks(capture, merge=my_hooks))` |
| OpenAI Agents SDK | `from shardflux.integrations.openai_agents import CaptureRunHooks`; `Runner.run(agent, "...", hooks=CaptureRunHooks(capture))` |
| LangChain / LangGraph | `from shardflux.integrations.langchain import CaptureCallbackHandler`; `config={"callbacks": [CaptureCallbackHandler(capture)]}` |
| Pydantic AI 2.x | `from shardflux.integrations.pydantic_ai import capture_capability`; `Agent(model, capabilities=[capture_capability(capture)])` |
| CrewAI | `from shardflux.integrations.crewai import register_hooks`; `unregister = register_hooks(capture)` |
| MCP clients | `from shardflux.integrations.mcp import instrument`; `release = instrument(session, capture, server="github")` |

Explicit capture (`record`, `call`, `wrap`, `@capture.tool`, `@capture_tool`) always records. Hook integrations record
every tool, Shardflux's own included; narrow them with `tools=` / `exclude=` (names, a compiled pattern or a predicate).
Calls are deduplicated by call id (the last 10,000).

The layout, index format and limits are the same as the TypeScript SDK's
([Tool-call capture](https://docs.shardflux.dev/reference/typescript.md#tool-call-capture)). Python-specific options of `capture_tool_calls()`:

| Option | Default | Meaning |
| --- | --- | --- |
| `dir` | `/home/user/tool-calls` | Capture directory in the workspace. |
| `tools`, `exclude` | none | Tool selection for hook integrations. |
| `transform` | none | Redact or drop a call (return `None`); if it raises, the call is dropped. |
| `max_output_bytes` | 32 MiB | Per call. |
| `max_inline_input_bytes` | 64 KiB | Larger inputs go to their own file. |
| `max_pending_bytes`, `max_pending_calls` | 128 MiB, 10,000 | Bounds on pending writes; nothing ever blocks the tool. |
| `settle_timeout` | `30.0` | Bound on the read-your-writes wait. |
| `exit_timeout` | `5.0` | Bound on the `atexit` flush. |
| `retry_window` | `120.0` | How long a write is retried. |
| `wake` | `True` | Writes resume a suspended workspace. |
| `meta` | none | Merged into every index line's `meta`. |
| `concurrency` | `4` | Writes in flight per capture. |
| `on_error` | none | Receives a `CaptureError`. |

`capture.flush(timeout)` and `await capture.aflush(timeout)` wait for everything recorded so far and return `True`
when done. `close()` / `aclose()`, `with` and `async with` stop recording and flush. On serverless platforms, flush
before the handler returns. `capture.prompt_hint()` returns a paragraph for your system prompt.

## Account

**(0.5.0+)** `ShardfluxAccount` does what a person does in the console, from a script or an agent: register, sign in
(with two-factor authentication), organizations, projects, API keys, members, invitations, billing, spend alerts, the
audit log, exports and deletion, and template publish and archive. It authenticates with a person's CLI session
(`sfu_` and 43 characters, sent as `Authorization: Bearer` on `/v1`), not with an API key. Two steps stay with a
person: opening the verification email and paying in Stripe Checkout.

```python
from shardflux import API_KEY_TOOL_PERMISSIONS, Shardflux, ShardfluxAccount

# Once: register, then pass the emailed link (or the token in it).
ShardfluxAccount.register(email="me@example.com", password=password, display_name="Me")
ShardfluxAccount.verify_email("<link from the verification email>")


def save(token: str, expires_at: str | None) -> None:
    store_secret("shardflux-session", token)  # your storage: each new token revokes the previous one


account, result = ShardfluxAccount.login(email="me@example.com", password=password, on_session_token=save)
if result["status"] == "mfa_required":
    account.auth.complete_mfa(code="123456")  # or recovery_code="..."

org = account.organizations.create("Acme")
project = account.projects.create(org["id"], "Default")
key = account.api_keys.create(project["id"], "ci-agent", tool_permissions=API_KEY_TOOL_PERMISSIONS)
sf = Shardflux(api_key=key["secret"])  # the sfk_... secret is shown once
```

Later, `ShardfluxAccount()` reads `SHARDFLUX_SESSION_TOKEN` (and `SHARDFLUX_API_URL`). A token that does not have the
session shape raises `ValueError` before any request. The client is a context manager (`close()`), and takes
`base_url`, `on_session_token` and `version_check` like `Shardflux`.

| Namespace | Methods |
| --- | --- |
| class methods (no session) | `register`, `verify_email`, `request_password_reset`, `confirm_password_reset`, `confirm_email_change`, `login` |
| `auth` | `session`, `complete_mfa`, `logout`, `logout_all`, `sessions`, `revoke_session`, `step_up`, `change_password`, `change_email`, `resend_verification`, `totp.enroll`, `totp.confirm`, `totp.disable`, `totp.regenerate_recovery_codes` |
| `organizations` | `list`, `list_all`, `create`, `get`, `entitlements`, `deletion`, `delete(id, confirmation=slug)`, `exports.create`, `exports.get`, `exports.download`, `workspaces` |
| `projects` | `list`, `list_all`, `create`, `get` |
| `api_keys` | `list`, `create(project_id, name, tool_permissions=..., expires_at=...)`, `revoke` |
| `members` | `list`, `update(org_id, user_id, role=...)`, `remove` |
| `invitations` | `list`, `create(org_id, email, role=...)`, `revoke`, `accept(link_or_token)` |
| `billing` | `catalog`, `subscription`, `checkout`, `checkout_status`, `wait_for_checkout`, `portal`, `invoices`, `spend_policy`, `set_spend_policy` |
| `user` (the signed-in person) | `deletion`, `schedule_deletion(confirmation=email)`, `cancel_deletion`, `exports.create`, `exports.get`, `exports.download` |
| `templates` | `publish_version(org_id, slug, version)`, `archive_version(...)` |
| `audit` | `list`, `list_all`, `export(org_id, format="ndjson" \| "csv", ...)` (the text) |
| `secrets` | The same API as `sf.secrets`, with the person's permissions. |

Plus `account.me()` and `account.request(method, path, ...)`. Lists return a `Page` (`data`, `next_cursor`); other
methods return the API's JSON as a dict (downloads and exports as text). Organization and project ids are always
explicit.

- **The token rotates.** Login, `auth.complete_mfa()`, `auth.step_up()`, `auth.change_password()`,
  `auth.totp.confirm()` and `auth.totp.disable()` answer with a new session token and revoke the previous one. The
  client switches at once and calls `on_session_token(token, expires_at)`; `account.session_token` is always the
  current one. A session lasts 30 days from its last use and at most 90 days.
- **Step-up.** Exports, deletions, email and two-factor changes raise `ShardfluxApiError` 403 `step_up_required` until
  `account.auth.step_up(password=..., code=...)` (the code only with two-factor authentication on). A session waiting
  for its second factor gets 403 `mfa_required`, an unverified email 403 `email_unverified`. See
  [Errors](https://docs.shardflux.dev/reference/errors.md#with-a-persons-session).
- **API keys.** `api_keys.create()` returns `{api_key, secret}` and sends an `Idempotency-Key`, so a retry returns the
  same key. `tool_permissions=None` sends `[]` (a key without workspace tools); `API_KEY_TOOL_PERMISSIONS` lists
  every tool.
- **Emailed links.** `verify_email`, `confirm_password_reset(token=...)`, `confirm_email_change` and
  `invitations.accept` take the whole link or its token. `parse_email_token(link)` returns the token (`#token=`
  fragment, else `?token=` query) and raises `ValueError` for an empty input or a link without one.

Upgrading a plan: a person pays in Checkout, and the client waits for the subscription:

```python
from shardflux import CheckoutTimeoutError

checkout = account.billing.checkout(org["id"], "developer")
print("Pay here:", checkout["url"])
try:
    done = account.billing.wait_for_checkout(org["id"], checkout["id"], timeout=900)  # polls every 2 s
    print(done["subscription_active"])  # False when the checkout expired, was canceled or failed
except CheckoutTimeoutError as err:
    print("still open:", err.checkout["url"])
account.billing.set_spend_policy(org["id"], [50, 80, 100])  # usage alerts at 50, 80 and 100 %
```

An organization that already has a subscription gets 409 `conflict` with `err.reason == "subscription_exists"` from
`checkout`: `account.billing.portal(org_id)["url"]` is where plans change.

## Feedback

**(0.5.0+)** `sf.send_feedback(message, category=..., context=...)` sends a note straight to the Shardflux founder, who
reads every one. Use it while you work, not only when you are done: when something failed unexpectedly (`bug`), an
error, doc, name or output was unclear (`confusing`), or a capability, option or template you needed does not exist
(`missing`); `idea`, `praise` and `other` for the rest. Coding agents: also pass on what your user is frustrated about
or asked for that Shardflux could not do, paraphrased, without private data, and tell the user you sent it.

```python
from shardflux import ShardfluxApiError

try:
    ws.files.read_text("/home/user/report.csv")
except ShardfluxApiError as err:
    sf.send_feedback(
        f"files.read_text failed with {err.code}: {err.message}. Expected the file written by the last exec.",
        category="bug",
        context={"agent": "claude-code", "workspace": ws.key, "request_id": err.request_id, "error_code": err.code},
    )
    raise
```

- `message`: 1-8000 characters after trimming. `context` (every field optional text): `agent`, `client`, `workspace`,
  `request_id`, `error_code`, `command`, `page`; `client` defaults to `shardflux-py/<version>`. Bad arguments raise
  `ValueError` / `TypeError` before any request.
- Returns `FeedbackResult(id, received_at, duplicate)`; `received_at` is an aware `datetime`. `duplicate` is `True`
  when the same key sent the same message in the last 24 hours: you get the original back and nothing is sent twice.
- With a CLI session instead of an API key, `account.send_feedback(..., organization_id=...)` (`ShardfluxAccount`)
  sends it as the signed-in user, optionally about one of your organizations.
- Rate limited: 10 per 10 minutes and 50 per day per key or user, 200 per day per organization:
  `ShardfluxApiError` 429 `rate_limited` with `err.retry_after` (seconds). The call is never retried automatically.
- Anything shaped like an API key, token or private key is redacted before the message is stored or emailed.

## Update check

**(0.5.0+)** After the first successful request of a process, `Shardflux` or `ShardfluxAccount` asks
`GET /v1/client-versions` in a background thread (one request, 3 s timeout, every error ignored; it never slows a
call) and emits one `ShardfluxUpdateWarning` (a `UserWarning`) when this package is outdated or no longer supported:

```text
shardflux 0.6.1 is outdated: 0.7.0 is available. Update: pip install --upgrade shardflux
```

- Turn it off with `SHARDFLUX_NO_UPDATE_CHECK=1` (also `true`, `yes`, `on`; or `NO_UPDATE_NOTIFIER` set to anything),
  `version_check=False` on the client, or `warnings.filterwarnings("ignore", category=ShardfluxUpdateWarning)`.
- A tool built on this SDK checks its own package instead, once per process too:
  `version_check={"package": "my-tool", "version": "1.2.0"}`.
- On demand, `check_client_version(base_url=, package=, version=, ecosystem=, http_client=, timeout=)` returns a
  `ClientVersionStatus` (`status`, `package`, `ecosystem`, `current`, `latest`, `minimum_supported`,
  `upgrade_command`, `release_notes_url`, `message`) and never raises. `status` is `current`, `outdated`,
  `unsupported` or `unknown` (the request failed, or no published version). `compare_versions(a, b)` returns -1, 0
  or 1 for two `major.minor.patch` versions (a pre-release sorts before its release) and raises `ValueError` for
  anything else.

## Errors

All errors derive from `ShardfluxError`.

| Class | When | Attributes |
| --- | --- | --- |
| `ShardfluxApiError` | The API or the workspace refused the request. | `status`, `code`, `message`, `request_id`, `retryable`, `details`, `operation_id`, `retry_after`, `reason` (`details["reason"]`), `source` |
| `ExecStartError` | **(0.6.0+)** `ws.exec()` / `exec_run()`: the command could not start. A `ShardfluxApiError` with `code` `conflict` and `reason` `exec_failed_to_start`. | `session_id`, `session`, `details["error"]` (the workspace's reason) |
| `OperationFailedError` | An awaited operation ended `failed` or `canceled`. | `operation`, `operation_id`, `error_code`, `retryable` **(0.2.1+)** |
| `OperationTimeoutError` | A wait gave up; the operation continues. | `operation_id`, `workspace_id`, `last_state`, `last_reason`, `deadline_at` **(0.2.1+)**, `waited` |
| `ShardfluxProtocolError` | A response was not the documented shape. | `status` |
| `TemplateFileError` | **(0.3.0+)** A template file or local path cannot be used; nothing was sent. | `path` |
| `TemplateUploadError` | **(0.3.0+)** The storage refused an upload. | `status`, `code` |
| `TemplateBuildTimeoutError` | **(0.3.0+)** A build wait ran out; the build continues. | `build_id`, `last_state` |
| `ToolArgumentError` | **(0.4.0+)** A tool call named an unknown tool or its arguments do not match the schema; nothing was sent. Also a `ValueError`. | `tool`, `issues` |
| `CheckoutTimeoutError` | **(0.5.0+)** `billing.wait_for_checkout` ran out of time; the checkout stays payable until it expires. | `checkout_id`, `last_status`, `checkout`, `waited` |
| `NotSupportedForModeError` | **(0.5.0+)** A `ShardfluxApiError` (409 `conflict`, `not_supported_for_mode`): the call does not exist for the workspace's mode. | `mode`, `operation`, `local` (refused without a request) |
| `TreeRevisionMismatchError` | **(0.5.0+)** A `ShardfluxApiError` (409 `conflict`, `tree_revision_mismatch`): an `if_tree_revision` change found the tree at another revision; nothing changed. | `current_tree_revision` |

Each has `timing` **(0.2.0+)** when a traced call failed with it.

```python
from shardflux import ShardfluxApiError

try:
    sf.open(key="customer-42/main", template="python-node-browser")
except ShardfluxApiError as err:
    print(err.code, err.reason, err.message, err.request_id, err.retryable)
```

Retryable 503 `host_capacity` and `wake_failed` (a parked workspace could not be woken right now) are retried after
`Retry-After` for reads, searches and calls with an `Idempotency-Key`. 409 `host_feature_unavailable` is neither
retried nor woken. `ShardfluxApiError.tree_revision` **(0.5.0+)** is a file-first refusal's `X-Tree-Revision`.

Treat unknown codes and reasons as generic errors: show `message`, and use `retryable`. The list is in
[Errors](https://docs.shardflux.dev/reference/errors.md).

A 402 `allowance_exhausted` (opens, resumes and forks refused while a CPU-hours or RAM GiB-hours allowance is used up)
has a `reason` **(0.6.0+, in `KnownErrorReason`)**: `allowance_used` (upgrade, or turn on
[overage](https://docs.shardflux.dev/limits.md#overage-opt-in)), `overage_paused` (a plan payment is past due) or `spend_cap_reached` (raise the
spend cap or upgrade), and `details["spend_cap"]` (`cap_minor`, `effective_cap_minor`, `charges_minor`, `currency`).
Do not retry these in a loop.

## Overage with a user session

**(0.6.0+)** Owners and billing members turn [opt-in overage](https://docs.shardflux.dev/limits.md#overage-opt-in) on and set its spend cap under
**Usage & billing** in the console, or with `ShardfluxAccount`, the client for a user session (`sfu_...` from a
sign-in; an API key gets 403):

```python
from shardflux import ShardfluxAccount

with ShardfluxAccount() as account:  # the session token from SHARDFLUX_SESSION_TOKEN
    policy = account.billing.spend_policy(org_id)
    # overage_state: unavailable | off | on | paused; the cap range: spend_cap_min_minor .. spend_cap_max_minor (cents)
    if policy["overage_available"]:
        account.billing.set_spend_policy(org_id, overage_enabled=True, spend_cap_minor=900, if_match=policy["version"])
    account.billing.set_spend_policy(org_id, overage_enabled=False)  # always allowed
```

`set_spend_policy(org_id, alert_thresholds_percent=None, *, overage_enabled=None, spend_cap_minor=None,
if_match=None)` takes at least one of the first three (`ValueError` otherwise). The cap is at least $1, at most the
plan price (`spend_cap_max_minor`), and not below what overage already charged this period. A refusal raises
`ShardfluxApiError` 422 `validation_failed` with `reason` `overage_unavailable`, `spend_cap_required`,
`spend_cap_below_minimum`, `spend_cap_above_plan_price` (`details["max_minor"]`) or `spend_cap_below_charges`
(`details["charges_minor"]`); with `if_match` (the policy `version`, or `"*"`), a concurrent change raises 409
`conflict` `version_mismatch`. This period's overage charges are in the TypeScript SDK's `usage.summary()` and
`shard usage`.

## Retries and idempotency

- Requests are retried only when a retry cannot duplicate an effect: `GET` and `HEAD`, and requests with an
  `Idempotency-Key`. The client sends a fresh key with opens, lifecycle calls, creates and file writes.
- Retried failures: network errors, and 429, 502, 503 or 504 responses whose error is `retryable`, at most
  `max_retries` times, honouring `Retry-After`.
- Exec and file calls refresh the tool token on a gateway `401` or `409 stale_epoch`, and wait out `workspace_busy`.
- A failed operation (for example `capacity_unavailable`) is never retried by the client.

## Compatibility

- The client follows the API's `/v1` contract. New fields, enum values and error codes can appear in any release;
  ignore unknown fields.
- The client is below 1.0: a minor release (0.2 to 0.3) may contain breaking changes, marked **Breaking** in the
  changelog.
- 0.2.0 changed behaviour: a tool call on a suspended workspace resumes it instead of raising `workspace_not_running`.
  `ws.cell(wake=None)` restores the old behaviour.
- 0.5.0 adds `ShardfluxAccount`, the update check, file search and patches, the wake hint and file-first
  workspaces. Its changes in behaviour: the background update check (one request per process; `version_check=False`
  turns it off), a wake of a suspended workspace is one held resume, and reads of a suspended workspace are served
  from its disk without waking it.
- 0.6.0 adds the agent tools `search_files` and `edit_file`. An agent tool call other than `read_file`, `list_files`
  and `search_files` now also sends a wake hint request in the background, which `workspace_tools(ws, hint=False)`
  turns off.