From dbb18e74fc2603f21a5f0008d73e4eb0b97a42d2 Mon Sep 17 00:00:00 2001
From: rmanjunath18 <242545101+rmanjunath18@users.noreply.github.com>
Date: Mon, 2 Nov 2026 12:52:37 +0530
Subject: [PATCH] docs(examples): add auto-resume examples for sandboxes and
 agents

auto_resume.py pauses a sandbox, then runs a command against it without
calling resume(), and reports whether the sandbox woke by itself.
agent_auto_resume.py does the same for an agent, through its backing
sandbox, and calls agent.resume() in the fallback.

Both fall back to an explicit resume() only on a 429 while still Paused,
and replay the read-only command at most once. Every 429 on the exec path
is sent before the command runs; that is how the backend behaves today,
not an API guarantee. A 503 or any other error is not replayed. The
marker read passes timeout_ms=120000, matching the JS port, and both
examples exit non-zero when deleting the sandbox or agent fails.

examples/README.md gains a step-by-step section with each example's run
command and expected output, and its table and notes now match the code.
minimal_agent's banner shows the configured model, and repo_analyzer
defaults to the repository's current URL. Both auto-resume examples are
listed in examples/README.md and docs/example-coverage.md.
---
 docs/example-coverage.md                    |   9 +-
 examples/README.md                          | 254 +++++++++++++++++++-
 examples/agent_auto_resume.py               | 120 +++++++++
 examples/agent_patterns/minimal_agent.py    |   4 +-
 examples/auto_resume.py                     | 107 +++++++++
 examples/workflow_examples/README.md        |   2 +-
 examples/workflow_examples/repo_analyzer.py |   4 +-
 7 files changed, 483 insertions(+), 17 deletions(-)
 create mode 100644 examples/agent_auto_resume.py
 create mode 100644 examples/auto_resume.py

diff --git a/docs/example-coverage.md b/docs/example-coverage.md
index ac98933..3a67c21 100644
--- a/docs/example-coverage.md
+++ b/docs/example-coverage.md
@@ -57,11 +57,11 @@ examples themselves, see [`examples/README.md`](../examples/README.md).
 | `client.agent_templates.list` | `create_agent.py` | `page = client.agent_templates.list()` |
 | `client.agent_templates.get` | — | `tpl = client.agent_templates.get(template_id)` |
 | `agent.wait_until_ready` | `create_agent.py` | `agent.wait_until_ready(timeout_ms=120_000)` |
-| `agent.refresh` | — | `agent.refresh()` |
+| `agent.refresh` | `agent_auto_resume.py` | `agent.refresh()` |
 | `agent.sandbox` | `create_agent.py` | `sandbox = agent.sandbox()` |
 | `agent.update` | `create_agent.py` | `agent.update({"resources": {"cpu": 2, "memory_gb": 4}})` |
 | `agent.pause` / `agent.delete` | `create_agent.py` | `agent.pause(); agent.delete()` |
-| `agent.resume` | — | `agent.resume()` — not shown in `create_agent.py`; see [getting-started.md](./getting-started.md#create-an-agent) |
+| `agent.resume` | `agent_auto_resume.py` | `agent.resume()` — then `wait_until_ready()` |
 | `agent.to_json` | — | `agent.to_json()` |
 | `client.raw.request` | `raw_request.py` | `data = client.raw.request("GET", path, query={...})` |
 | `sandbox.wait_until_ready` | tier-1 (except `raw_request.py`), `processes.py`, `process_pool.py`, `agent_patterns/*`, `workflow_examples/*` | `sandbox.wait_until_ready(timeout_ms=120_000)` — after `connect_url` is set in process examples |
@@ -89,7 +89,8 @@ examples themselves, see [`examples/README.md`](../examples/README.md).
 | `sandbox.files.upload` | — | `sandbox.files.upload("big.bin", data, chunk_size=512 << 10)` — `write()` uses it above 1 MiB |
 | `sandbox.files.download_file` | `upload_download.py` | `sandbox.files.download_file("payload.bin", copy)` → `{"bytes_written": n}` |
 | `sandbox.metrics` | `sandbox_lifecycle.py`, `sandbox_metrics.py` | `metrics = sandbox.metrics()` |
-| `sandbox.pause` | `sandbox_lifecycle.py` | `sandbox.pause()` |
+| `sandbox.pause` | `sandbox_lifecycle.py`, `auto_resume.py` | `sandbox.pause()` |
+| `sandbox.resume` | `auto_resume.py` | `sandbox.resume()` — then `wait_until_ready()` |
 | `sandbox.delete` | all examples that create sandboxes | `sandbox.delete()` / `await sandbox.delete()` |
 | `sandbox.to_json` | `sandbox_lifecycle_controller.py` | `sandbox.to_json()` |
 | `sandbox.id` / `.phase` / `.connect_url` | tier-1, `processes.py`, `process_pool.py`, `sandbox_lifecycle_controller.py`, `agent_patterns/utils/sandbox_tool.py`, `workflow_examples/*` | `print(sandbox.phase, sandbox.connect_url)` — polled until `connect_url` in process examples |
@@ -103,6 +104,8 @@ examples themselves, see [`examples/README.md`](../examples/README.md).
 | Templates list & create | `examples/templates_list.py` | List templates, get by id, create sandbox, wait, delete |
 | Agent lifecycle | `examples/create_agent.py` | List agent templates, create agent, wait, sandbox exec, update, pause, delete |
 | Sandbox lifecycle | `examples/sandbox_lifecycle.py` | Create → wait → metrics → pause → delete |
+| Auto-resume | `examples/auto_resume.py` | Create → pause → `exec` with no `resume()` → explicit `resume()` only on 429 while Paused → delete |
+| Agent auto-resume | `examples/agent_auto_resume.py` | Create agent → pause → sandbox `exec` with no `resume()` → explicit `agent.resume()` only on 429 while Paused → delete |
 | Sandbox in-place update | `examples/sandbox_update.py` | Create → wait → resize → re-scope egress → verify → delete |
 | Sandbox labels | `examples/sandbox_labels.py` | Create two labelled sandboxes → list by one label → narrow by two → delete |
 | Crash reporting | `examples/last_crash.py` | Create → mark file → force OOM → poll `last_crash` → check `storage_reset` → delete |
diff --git a/examples/README.md b/examples/README.md
index 48b6acd..7c0c843 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,7 +1,7 @@
 # Examples
 
-Runnable scripts for the NeevCloud SDK for Python (`neevai`). Each one creates real
-sandboxes and cleans them up when it finishes.
+Runnable scripts for the NeevCloud SDK for Python (`neevai`). Most create real
+sandboxes or agents and clean them up when they finish.
 
 ## Contents
 
@@ -10,6 +10,7 @@ sandboxes and cleans them up when it finishes.
 - [Agents](#agents)
 - [Agent tools](#agent-tools)
 - [Workflows](#workflows)
+- [Step-by-step: run every example](#step-by-step-run-every-example)
 - [Environment variables](#environment-variables)
 - [Notes](#notes)
 
@@ -32,7 +33,12 @@ Run any example from the repository root:
 uv run python examples/<script>.py
 ```
 
-Examples create from `sb-ubuntu-26-04-dev` unless you set `NEEV_SANDBOX_TEMPLATE_ID`.
+Most examples create from `sb-ubuntu-26-04-dev` unless you set `NEEV_SANDBOX_TEMPLATE_ID`.
+The exceptions: `code_interpreter.py` and `docker.py` use their own templates,
+`byoi_create.py` and `ssh_tunnel.py` use their own images, `update_resize_egress.py`
+and `agent_patterns/agent_tools_loop.py` use the platform default, `sandbox_labels.py`
+falls back to the first listed template, and
+`sandbox_lifecycle_controller.py create` needs `--template-id` or the variable.
 
 ## Sandboxes
 
@@ -42,8 +48,9 @@ These need only your credentials. Start with `templates_list.py`.
 | --- | --- |
 | [`templates_list.py`](templates_list.py) | List templates, get one, create a sandbox from it |
 | [`sandbox_lifecycle.py`](sandbox_lifecycle.py) | Create, wait, metrics, pause, delete |
+| [`auto_resume.py`](auto_resume.py) | Use a paused sandbox without calling `resume()`; reports whether it woke by itself |
 | [`sandbox_lifecycle_windows.py`](sandbox_lifecycle_windows.py) | Idle timeout and maximum lifetime, `keepalive`, `update_timeout` |
-| [`sandbox_update.py`](sandbox_update.py) | Resize a running sandbox, then change its egress |
+| [`sandbox_update.py`](sandbox_update.py) | Resize a running sandbox and change its egress in one call |
 | [`update_resize_egress.py`](update_resize_egress.py) | Resize and change egress in one call; `egress_add` and `egress_remove` |
 | [`e2e_live_update.py`](e2e_live_update.py) | A pass/fail check of a combined resize and egress update |
 | [`last_crash.py`](last_crash.py) | Force an out-of-memory crash and read `last_crash` |
@@ -55,7 +62,7 @@ These need only your credentials. Start with `templates_list.py`.
 | [`upload_download.py`](upload_download.py) | Upload and download a large file with progress |
 | [`preview_ports.py`](preview_ports.py) | Serve a port, get its preview URL, rotate it, revoke it |
 | [`audit_trail.py`](audit_trail.py) | Run commands, then page through the audit trail |
-| [`pty.py`](pty.py) | An interactive terminal |
+| [`pty.py`](pty.py) | A scripted terminal session (no typing needed) |
 | [`ssh_tunnel.py`](ssh_tunnel.py) | SSH, `rsync` and port forwarding through one tunnel |
 | [`streaming_exec.py`](streaming_exec.py) | Stream command output line by line |
 | [`processes.py`](processes.py) | Start, follow, read logs of and stop a process |
@@ -70,7 +77,7 @@ These need only your credentials. Start with `templates_list.py`.
 The lifecycle controller is handy for trying things by hand:
 
 ```bash
-uv run python examples/sandbox_lifecycle_controller.py create --name my-sandbox --wait
+uv run python examples/sandbox_lifecycle_controller.py create --name my-sandbox --template-id sb-ubuntu-26-04-dev --wait
 uv run python examples/sandbox_lifecycle_controller.py list --limit 20
 uv run python examples/sandbox_lifecycle_controller.py metrics <sandbox-id>
 ```
@@ -83,6 +90,7 @@ These need only your credentials.
 | --- | --- |
 | [`create_agent.py`](create_agent.py) | Create an agent, use its sandbox, update, pause, delete |
 | [`agent_ports_audit.py`](agent_ports_audit.py) | An agent's preview URL, keepalive and audit trail |
+| [`agent_auto_resume.py`](agent_auto_resume.py) | Use a paused agent without calling `resume()`; reports whether it woke by itself |
 
 ## Agent tools
 
@@ -105,7 +113,7 @@ Complete agent workflows that save their results locally.
 | Example | Shows | Saves |
 | --- | --- | --- |
 | [`workflow_examples/repo_analyzer.py`](workflow_examples/repo_analyzer.py) | Clone and review a repository | `workflow_examples/output/repo-analysis.md` |
-| [`workflow_examples/browser_agent.py`](workflow_examples/browser_agent.py) | Browse a site and summarise it | `workflow_examples/output/results.md` |
+| [`workflow_examples/browser_agent.py`](workflow_examples/browser_agent.py) | Find Hacker News titles matching a query | `workflow_examples/output/results.md` |
 
 ```bash
 uv run python examples/workflow_examples/repo_analyzer.py
@@ -114,6 +122,234 @@ uv run python examples/workflow_examples/browser_agent.py --query "AI"
 
 See [`workflow_examples/README.md`](workflow_examples/README.md) for options.
 
+## Step-by-step: run every example
+
+Do the [Setup](#setup) once, then run each example from the repository root. Almost
+every example creates real sandboxes or agents, so your project needs available credits.
+
+### Sandboxes
+
+**1. List templates**
+```bash
+uv run python examples/templates_list.py
+```
+→ `templates: … of … (page …)` → `  … — … […]` (one line per template) → `selected: … — …` → `[templates] creating sandbox (…)…` → `created … (phase: …)` → `[templates] waiting until ready…` → `ready at …` → `[templates] deleting sandbox …`.
+
+**2. Lifecycle**
+```bash
+uv run python examples/sandbox_lifecycle.py
+```
+→ `created … from … (phase: …)` → `waiting 3.0s before wait_until_ready…` → `  phase=…` (one line per poll) → `ready at …` → `waiting 3.0s before metrics…` → `metric series: […]` → `waiting 3.0s before pause…` → `paused (phase: …)` → `waiting 3.0s before delete…` → `deleted`.
+
+**3. Auto-resume**
+```bash
+uv run python examples/auto_resume.py
+```
+→ `ready: …` → `paused` → `woke in N.Ns` → `RESULT: woke automatically` (or `429 and still Paused (…); resuming explicitly` → `resumed in N.Ns` → `RESULT: resumed explicitly` where automatic wake-up is off).
+
+**4. Idle timeout, lifetime and keepalive**
+```bash
+uv run python examples/sandbox_lifecycle_windows.py
+```
+→ `ready … — windows: {…}` → `keepalive 1/5 — phase=…` … `keepalive 5/5 — phase=…` (20s apart) → `retuned — windows: {…}` → `deleted`.
+
+**5. Resize and change egress**
+```bash
+uv run python examples/sandbox_update.py
+```
+→ `ready … at …` → `resized: {…}` → `egress now allows: ['api.github.com']` → `verified via get: resources={…}` → `deleted`.
+
+**6. Resize and egress in one call, then edit egress**
+```bash
+uv run python examples/update_resize_egress.py
+```
+→ `ready … — resources: …, egress: …` → `updated … in one PATCH — resources: …, egress: github.com -> google.com` → `confirmed resources: …, egress: …` → `edited egress in place: …` → `cleaned up`.
+
+**7. Live update check**
+```bash
+uv run python examples/e2e_live_update.py
+```
+→ `ready … (name=…)` → `[PASS] …` (one line per check, 12 in all) → `cleaned up …` → `E2E PASSED — combined resize+egress verified against the live API` (the last two checks are replaced by one `[SKIP] in-sandbox allow/deny proof — …` line if the in-sandbox `exec` call itself errors; any `[FAIL]` ends with `E2E FAILED — …` and exit code 1).
+
+**8. Crash detection**
+```bash
+uv run python examples/last_crash.py
+```
+→ `ready … — last_crash=None` → `wrote /workspace/marker.txt` → `allocating past the memory limit...` → `  exec died as expected: …` → `  poll N/30 — phase=…, no crash yet` (one line per poll until the crash shows) → `crash: reason=… at=…` → `  storage_reset=…` → `  marker file present: …` → `storage_reset agrees with the filesystem: …` (`/workspace was wiped, re-provision before reusing this sandbox` or `files survived the restart`) → `deleted`.
+
+**9. Labels**
+```bash
+uv run python examples/sandbox_labels.py
+```
+→ `created … labels={…}` (twice) → `team=labels-demo-…: [… , …]` → `team=labels-demo-…, run=2: […]` → `deleted …` (twice).
+
+**10. Your own image**
+```bash
+uv run python examples/byoi_create.py
+```
+→ `ready … from image docker.io/library/python:3.12-slim` → `exec exit=0 out=Python 3.12.…` → `deleted`.
+
+**11. Snapshot, restore and fork**
+```bash
+uv run python examples/snapshot_fork_restore.py
+```
+→ `[snapshot] created sandbox …` → `[snapshot] ready: …` → `[snapshot] wrote original state` → `[snapshot] snapshot pending: … (status=…)` → `[snapshot] snapshot ready` → `before restore:` → `modified state` → `[snapshot] restored sandbox … from snapshot` → `after restore:` → `original state` → `[snapshot] forked sandbox … (snapshot-fork)` → `[snapshot] fork inherited: original state` → `[snapshot] deleting fork …` → `[snapshot] deleting restored sandbox …` → `[snapshot] deleting sandbox …` → `[snapshot] deleting snapshot …`.
+
+**12. Async client**
+```bash
+uv run python examples/async_sandbox.py
+```
+→ `[async] creating sandbox (…)…` → `created … (phase: …)` → `[async] waiting until ready…` → `ready at …` → `exec stdout: hello from async (exit 0)` → `[async] deleting sandbox …`.
+
+**13. Files**
+```bash
+uv run python examples/files_api.py
+```
+→ `[files] creating sandbox (…)…` → `[files] ready: …` → `read_text: Hello from files API` → `  …: demo/… (N bytes)` (one line per entry under `demo/`) → `stat: … is a … of N bytes` → `exists demo/hello.txt: True` → `exists demo/missing: False` → `moved: exists archive copy = True` → `removed demo/nested: exists = False` → `watch: … …` (only if a change arrives in the 2s watch) → `[files] deleting sandbox …`.
+
+**14. Upload and download a large file**
+```bash
+uv run python examples/upload_download.py
+```
+→ `uploaded N% (…/… bytes)` (one line, updated in place) → `uploaded 8388608 bytes` → `downloaded 8388608 bytes` → `sizes match`.
+
+**15. Preview URLs**
+```bash
+uv run python examples/preview_ports.py
+```
+→ `[ports] creating sandbox (…)…` → `[ports] ready: …` → `[ports] server listening on :3000` → `preview URL: …` → `exposed ports: [3000]` → `rotated preview URL: … (old URL no longer works)` → `revoked; exposed ports: []` → `[ports] deleting sandbox …`.
+
+**16. Audit trail**
+```bash
+uv run python examples/audit_trail.py
+```
+→ `ready: …` → `retention: … days, truncated: …` → `HH:MM:SS <operation> <who> <status>` (one line per event, newest first) → `exec calls:` → the same kind of line for each `exec` event.
+
+**17. Terminal (PTY)**
+```bash
+uv run python examples/pty.py
+```
+Runs a short shell session for you; nothing to type. → `[pty] creating sandbox (…)…` → `[pty] ready: …` → the raw terminal output: the shell echoes `echo hello-from-pty && uname -a`, then prints `hello-from-pty` and the `uname -a` line → `[pty] pty exited with code …` → `[pty] deleting sandbox …`.
+
+**18. SSH tunnel**
+```bash
+uv run python examples/ssh_tunnel.py
+```
+Needs `ssh`, `rsync` and `curl` on your machine. It always uses the `mcr.microsoft.com/devcontainers/python:3.12` image, whatever `NEEV_SANDBOX_TEMPLATE_ID` says. → `[ssh] creating sandbox from mcr.microsoft.com/devcontainers/python:3.12…` → `[ssh] ready: …` → `[ssh] tunnel on …:… — e.g. ssh -p … neev@localhost` → `[ssh] exec: uname + workspace listing` → the `uname -a` line and a listing of `/workspace` → `[ssh] rsync: local dir → sandbox:/workspace/uploaded` → `shipped over rsync` → `[ssh] port-forward: python http.server in sandbox → http://localhost:18080` → `shipped over rsync` (fetched with `curl` through the forward) → `[ssh] tunnel closed` → `[ssh] deleting sandbox …`.
+
+**19. Streaming exec**
+```bash
+uv run python examples/streaming_exec.py
+```
+→ `[+    Nms] creating sandbox…` → `[+…ms] stdout: Starting download...` → `stdout: Download progress: 20%` … `100%` (one line about every second) → `stdout: Download completed` → `exit 0` → `deleting sandbox…`.
+
+**20. Processes**
+```bash
+uv run python examples/processes.py
+```
+→ `[processes] creating sandbox (…)…` → `[processes] connect_url: …` → `[processes] phase=…` (one line per poll) → `[processes] ready: …` → `[processes] started process …` → `line-0` → `line-1` → `line-2` (it stops following after three lines) → `[processes] polled N log entries (cursor=…)` → `[processes] listed N process(es)` → `[processes] process exited with code …` → `[processes] deleting sandbox …`.
+
+**21. Process pool**
+```bash
+uv run python examples/process_pool.py
+```
+→ `[process-pool] creating sandbox (…)…` → `[process-pool] connect_url: …` → `[process-pool] ready: …` → `[process-pool] started worker 0: …` (and workers 1, 2) → `[process-pool] listed N process(es)` → `[process-pool] … state=…` (one per worker) → `[process-pool] kill_all signalled … process(es)` → `[process-pool] … exit_code=…` (one per worker) → `[process-pool] deleting sandbox …`.
+
+**22. Code interpreter**
+```bash
+uv run python examples/code_interpreter.py
+```
+Always uses the `sb-ubuntu-26-04-interpreter` template. → `stdout: 42` → `last value: 80 cell: … ended: …` → `ended: … - ZeroDivisionError division by zero` → `x visible in a new context: False` → `contexts: […]`.
+
+**23. Docker**
+```bash
+uv run python examples/docker.py
+```
+Always uses the `sb-ubuntu-26-04-docker` template. → `ready: …` → the `hello-world` container's output, starting `Hello from Docker!`.
+
+**24. Parallel fan-out**
+```bash
+uv run python examples/parallel_fanout.py
+```
+→ `[fanout] provisioning 3 sandboxes…` → `[fanout] analyzing repo 1…` (and 2, 3, in any order) → `[fanout] repo 1 -> … Python files` → `[fanout] repo 2 -> … TypeScript files` → `[fanout] repo 3 -> … Go files` → `Analysis complete:` → `  Total repositories: 3` → `  Total source files: …` → `[fanout] deleting sandboxes…`.
+
+**25. Metrics under load**
+```bash
+uv run python examples/sandbox_metrics.py
+```
+→ `[metrics] creating sandbox (…)…` → `[metrics] ready: …` → `[metrics] starting report generation job` → `[metrics] batch N/8 complete — checking sandbox health…` and `[metrics] batch N/8: <metric>=…(Npts) …` (one pair per 15-second batch; stops after batch 3 once any metric has data) → `metrics for sandbox … (… -> …):` → `  <metric>: N points, last=…` (one line per metric) → `[metrics] deleting sandbox …`.
+
+**26. Raw API request**
+```bash
+uv run python examples/raw_request.py
+```
+Creates no sandbox. → `raw templates: N item(s)` → `  … — …` (one line per template, up to 3) → `raw sandboxes: … total in project`.
+
+**27. Lifecycle controller**
+```bash
+uv run python examples/sandbox_lifecycle_controller.py list --limit 20
+```
+→ `total=…  page=1  limit=20` → `  …  name=…  phase=…` (one line per sandbox). `get`, `pause`, `resume` and `delete` print one result line each; `metrics` prints a header plus one line per series, and `create --wait` also prints `  phase=…` while it waits; add `--json` before the subcommand for JSON. `create` needs `--name`, plus `--template-id` or `NEEV_SANDBOX_TEMPLATE_ID`, and it does not delete the sandbox, so run `delete <sandbox-id>` afterwards.
+
+### Agents
+
+**28. Create an agent**
+```bash
+uv run python examples/create_agent.py
+```
+→ `templates: …` → `created … (status: …, sandbox: …)` → `ready` → an `ls -la` listing of the agent's workspace (includes `notes.md`) → `resized` → `paused (status: …)` → `deleted`.
+
+**29. Agent ports, keepalive and audit trail**
+```bash
+uv run python examples/agent_ports_audit.py
+```
+→ `ready: … (idle window: …)` → `preview URL: …` → `rotated to: … (the old URL no longer works)` → `exposed ports: [3000]` → `HH:MM:SS <operation> <who> <status>` (one line per audit event).
+
+**30. Agent auto-resume**
+```bash
+uv run python examples/agent_auto_resume.py
+```
+→ `created agent …, waiting for it to be Ready...` → `agent is Ready; wrote auto-resume-marker.txt into its sandbox …` → `agent paused (status: Paused)` → `reading auto-resume-marker.txt from the paused agent, without calling resume()...` → `file read back intact after N.Ns` → `agent status now: Ready` → `RESULT: woke automatically` (or `the read was refused with 429 and the agent is still Paused (…)` → `calling resume() and reading the file again...` → `file read back intact after N.Ns` → … → `RESULT: resumed explicitly` where automatic wake-up is off) → `deleted agent …`.
+
+### Agent tools
+
+These call a model. They use `NEEV_API_KEY` for inference unless you set `NEEV_INFERENCE_API_KEY`, and the model is `gpt-oss-120b` unless you set `NEEV_MODEL`.
+
+**31. Minimal agent loop**
+```bash
+uv run python examples/agent_patterns/minimal_agent.py
+```
+→ `AI code-interpreter (<model> -> Neev sandbox)` → `task: Print every prime number below 50, …` → `[sandbox] creating (template=…)…` → for each step: `━━━━━ step N ━━━━━` → `[model] calling … with N messages…` → `[model] tokens: prompt=… completion=… total=…` → `[model] requested N tool call(s)` → `[tool] run_shell` and `  $ <command>` → `  ┌─ live output ───…` → the command's output as it runs → `  └─ exit 0 ───…` → `[tool] returned N bytes to the model` … → `✅ final answer:` → the model's answer → `[sandbox] deleting …`.
+
+**32. Ready-made agent tools**
+```bash
+uv run python examples/agent_patterns/agent_tools_loop.py
+```
+→ `[sandbox] …` → `[tool] <name>({…}) -> {…}` (one line per tool call, as the model writes and runs `fib.py`) → `[answer] …` (the model's reply with the last Fibonacci number) → `[sandbox] deleted …`.
+
+**33. LangGraph agent**
+```bash
+uv sync --extra agents
+uv run --extra agents python examples/agent_patterns/langchain_agent.py
+```
+→ `[agent] LangChain · … — running (first sandbox call waits for warmup)…` → `[neev] creating sandbox (template=…)…` → `[neev] created … (…); waiting until ready…` → `[neev] ready: …` → `[neev] exec: <command>` and `[neev]   -> exit N` (one pair per command the model runs) → the model's answer, the number of `.py` and `.js` files (expected `5`) → `[neev] deleting sandbox …`.
+
+### Workflows
+
+These also call a model, and save their result under `examples/workflow_examples/output/`.
+
+**34. Repository analyzer**
+```bash
+uv run python examples/workflow_examples/repo_analyzer.py
+```
+→ `[sandbox] creating (template=…)…` → `[sandbox] created …; waiting until ready…` → `[sandbox] ready: …` → `[bootstrap] git available` and `[bootstrap] ripgrep available` (or `installing … via …` lines if the template lacks them) → `[clone] fetching https://github.com/NeevCloudAI/neev-sdk-python…` → `[clone] done (…)` → for each step: `[model] calling … (step N)…` → `  tokens: …` → `  $ <command>` with its live output between `┌─ live output` and `└─ exit N` … → the four-section report → `[artifact] saved N bytes → …/output/repo-analysis.md` → `[sandbox] deleting …`. Pass `--repo <url>` to analyze another repository.
+
+**35. Browser agent**
+```bash
+uv run python examples/workflow_examples/browser_agent.py --query "AI"
+```
+→ `[sandbox] creating browser sandbox (template=…)…` → `[sandbox] created …; waiting until ready…` → `[sandbox] ready: …` → `[bootstrap] installing playwright + chromium…` → `[bootstrap] done` → model steps as in the analyzer (`[model] calling …`, `  $ <command>`, live output) → the matching Hacker News titles → `[artifact] saved N bytes -> …/output/results.md` → `[sandbox] deleting …` (if the agent never writes `results.md`, you get `warning: results.md was not created. …` and exit code 1).
+
 ## Environment variables
 
 | Variable | Used by | Default |
@@ -122,7 +358,7 @@ See [`workflow_examples/README.md`](workflow_examples/README.md) for options.
 | `NEEV_ORG_ID` | All | Required |
 | `NEEV_PROJECT_ID` | All | Required |
 | `NEEV_SANDBOX_TEMPLATE_ID` | Sandbox examples | `sb-ubuntu-26-04-dev` |
-| `NEEV_AGENT_TEMPLATE` | `create_agent.py` | `claude-code` |
+| `NEEV_AGENT_TEMPLATE` | `create_agent.py`, `agent_ports_audit.py`, `agent_auto_resume.py` | `claude-code` |
 | `NEEV_INFERENCE_API_KEY` | Agent and workflow examples | `NEEV_API_KEY` |
 | `NEEV_INFERENCE_BASE_URL` | Agent and workflow examples | `https://inference.ai.neevcloud.com/v1` |
 | `NEEV_MODEL` | Agent and workflow examples | `gpt-oss-120b` |
@@ -136,6 +372,6 @@ See [`workflow_examples/README.md`](workflow_examples/README.md) for options.
 ## Notes
 
 - File paths are relative to the workspace, or absolute inside it.
-- Examples call `wait_until_ready()` before running commands.
+- Examples that run commands call `wait_until_ready()` first.
 - Progress goes to stderr; each example's result goes to stdout.
 - For which example covers which API, see [example coverage](../docs/example-coverage.md).
diff --git a/examples/agent_auto_resume.py b/examples/agent_auto_resume.py
new file mode 100644
index 0000000..3c1db03
--- /dev/null
+++ b/examples/agent_auto_resume.py
@@ -0,0 +1,120 @@
+"""
+Use a paused agent without resuming it first.
+
+Pausing an agent pauses its backing sandbox. Where the platform's automatic
+wake-up is enabled, a request to that sandbox wakes it and is delivered once it is
+ready: one slow response instead of an error. This pauses an agent, reads a file
+back through ``agent.sandbox().exec`` without calling ``agent.resume()``, and
+prints ``RESULT: woke automatically``, ``resumed explicitly`` or ``failed``.
+
+If ``exec`` gets a 429 and the agent is still ``Paused``, it calls
+``agent.resume()`` and runs the read-only command once more. In the current backend
+a 429 on this path is sent before the command runs; that is not an API guarantee,
+so don't replay commands that change state. A 503 is not replayed.
+
+Set NEEV_AGENT_TEMPLATE to pick a template (default "claude-code").
+
+Run::
+
+    NEEV_API_KEY=... NEEV_ORG_ID=... NEEV_PROJECT_ID=... \\
+    uv run python examples/agent_auto_resume.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+from neevai import NeevAI
+from neevai.errors import APIError, NeevAIError
+
+AGENT_TEMPLATE = os.environ.get("NEEV_AGENT_TEMPLATE", "claude-code")
+MARKER_FILE = "auto-resume-marker.txt"
+MARKER_TEXT = "written before the pause"
+PHASE_TIMEOUT_SEC = 120
+
+
+def wait_for(agent, done, expected: str) -> None:
+    """Polls until done(agent) holds, or raises after PHASE_TIMEOUT_SEC."""
+    deadline = time.monotonic() + PHASE_TIMEOUT_SEC
+    while not done(agent):
+        if time.monotonic() > deadline:
+            raise NeevAIError(f"agent still {agent.status}; expected {expected}")
+        time.sleep(2)
+        agent.refresh()
+
+
+def read_marker(sandbox) -> str:
+    """Reads the marker back; a different text means the files did not survive."""
+    result = sandbox.exec(["cat", MARKER_FILE], timeout_ms=PHASE_TIMEOUT_SEC * 1000)
+    text = result.stdout.strip()
+    if result.exit_code != 0 or text != MARKER_TEXT:
+        raise NeevAIError(f"marker not intact: {text!r} {result.stderr}")
+    return text
+
+
+def use_paused_agent(agent, sandbox) -> str:
+    """Reads the marker without resuming; returns which path made it work."""
+    print(f"reading {MARKER_FILE} from the paused agent, without calling resume()...")
+    started = time.monotonic()
+    try:
+        read_marker(sandbox)
+        print(f"file read back intact after {time.monotonic() - started:.1f}s")
+        return "woke automatically"
+    except APIError as e:
+        if e.status_code != 429:
+            raise
+        agent.refresh()
+        if agent.status != "Paused":
+            raise
+        print(f"the read was refused with 429 and the agent is still Paused ({e})")
+        print("calling resume() and reading the file again...")
+
+    agent.resume()
+    # wait_until_ready() gives up at once on Paused, so first wait for resume to take effect.
+    wait_for(agent, lambda a: a.status != "Paused", "to leave Paused")
+    agent.wait_until_ready()
+    read_marker(sandbox)
+    print(f"file read back intact after {time.monotonic() - started:.1f}s")
+    return "resumed explicitly"
+
+
+def main() -> None:
+    with NeevAI() as client:
+        agent = None
+        try:
+            agent = client.agents.create(
+                {"name": "auto-resume-demo", "agent_template": AGENT_TEMPLATE}
+            )
+            print(f"created agent {agent.id}, waiting for it to be Ready...")
+            agent.wait_until_ready()
+            sandbox = agent.sandbox()
+            sandbox.wait_until_ready()
+            sandbox.files.write(MARKER_FILE, MARKER_TEXT)
+            print(f"agent is Ready; wrote {MARKER_FILE} into its sandbox {agent.sandbox_id}")
+
+            agent.pause()
+            wait_for(agent, lambda a: a.status == "Paused", "Paused")
+            print(f"agent paused (status: {agent.status})")
+
+            result = use_paused_agent(agent, sandbox)
+            agent.refresh()
+            print(f"agent status now: {agent.status}")
+            print(f"RESULT: {result}")
+        except NeevAIError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            print("RESULT: failed")
+            sys.exit(1)
+        finally:
+            if agent is not None:
+                try:
+                    agent.delete()
+                    print(f"deleted agent {agent.id}")
+                except NeevAIError as e:
+                    print(f"cleanup failed, delete {agent.id} by hand: {e}", file=sys.stderr)
+                    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/agent_patterns/minimal_agent.py b/examples/agent_patterns/minimal_agent.py
index 6f3697e..8a12c86 100644
--- a/examples/agent_patterns/minimal_agent.py
+++ b/examples/agent_patterns/minimal_agent.py
@@ -64,7 +64,7 @@
 
 ::
 
-    AI code-interpreter (gpt-oss-120b → Neev sandbox)
+    AI code-interpreter (gpt-oss-120b -> Neev sandbox)
     task: Print every prime number below 50…
 
     [sandbox] creating (template=sb-ubuntu-26-04-dev)…
@@ -190,7 +190,7 @@ def chat(messages: list[dict[str, Any]]) -> tuple[dict[str, Any], dict[str, Any]
 
 
 def main() -> None:
-    line(_bold("AI code-interpreter (gpt-oss-120b -> Neev sandbox)"))
+    line(_bold(f"AI code-interpreter ({NEEV_MODEL} -> Neev sandbox)"))
     line(_dim(f"task: {TASK}"))
 
     with NeevAI() as client:
diff --git a/examples/auto_resume.py b/examples/auto_resume.py
new file mode 100644
index 0000000..bd0d4e2
--- /dev/null
+++ b/examples/auto_resume.py
@@ -0,0 +1,107 @@
+"""
+Use a paused sandbox without resuming it first.
+
+Where the platform's automatic wake-up is enabled, a request to a paused sandbox
+wakes it and is delivered once the sandbox is ready: one slow response instead of
+an error. This pauses a sandbox, reads a file back with ``exec`` without calling
+``resume()``, and prints ``RESULT: woke automatically``, ``resumed explicitly`` or
+``failed``.
+
+If ``exec`` gets a 429 and the sandbox is still ``Paused``, it calls ``resume()``
+and runs the read-only command once more. In the current backend a 429 on this
+path is sent before the command runs; that is not an API guarantee, so don't
+replay commands that change state. A 503 is not replayed.
+
+Run::
+
+    NEEV_API_KEY=... NEEV_ORG_ID=... NEEV_PROJECT_ID=... \\
+    uv run python examples/auto_resume.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+from neevai import NeevAI
+from neevai.errors import APIError, NeevAIError
+
+TEMPLATE = os.environ.get("NEEV_SANDBOX_TEMPLATE_ID", "sb-ubuntu-26-04-dev")
+MARKER_FILE = "auto-resume-marker.txt"
+MARKER_TEXT = "written before the pause"
+PHASE_TIMEOUT_SEC = 120
+
+
+def wait_for(sandbox, done, expected: str) -> None:
+    """Polls until done(sandbox) holds, or raises after PHASE_TIMEOUT_SEC."""
+    deadline = time.monotonic() + PHASE_TIMEOUT_SEC
+    while not done(sandbox):
+        if time.monotonic() > deadline:
+            raise NeevAIError(f"sandbox still {sandbox.phase}; expected {expected}")
+        time.sleep(2)
+        sandbox.refresh()
+
+
+def read_marker(sandbox) -> str:
+    """Reads the marker back; a different text means the files did not survive."""
+    result = sandbox.exec(["cat", MARKER_FILE], timeout_ms=PHASE_TIMEOUT_SEC * 1000)
+    text = result.stdout.strip()
+    if result.exit_code != 0 or text != MARKER_TEXT:
+        raise NeevAIError(f"marker not intact: {text!r} {result.stderr}")
+    return text
+
+
+def use_paused_sandbox(sandbox) -> str:
+    """Reads the marker without resuming; returns which path made it work."""
+    started = time.monotonic()
+    try:
+        read_marker(sandbox)
+        print(f"woke in {time.monotonic() - started:.1f}s")
+        return "woke automatically"
+    except APIError as e:
+        if e.status_code != 429:
+            raise
+        sandbox.refresh()
+        if sandbox.phase != "Paused":
+            raise
+        print(f"429 and still Paused ({e}); resuming explicitly")
+
+    sandbox.resume()
+    # wait_until_ready() gives up at once on Paused, so first wait for resume to take effect.
+    wait_for(sandbox, lambda s: s.phase != "Paused", "to leave Paused")
+    sandbox.wait_until_ready()
+    read_marker(sandbox)
+    print(f"resumed in {time.monotonic() - started:.1f}s")
+    return "resumed explicitly"
+
+
+def main() -> None:
+    with NeevAI() as client:
+        sandbox = None
+        try:
+            sandbox = client.sandboxes.create({"sandbox_template_id": TEMPLATE})
+            sandbox.wait_until_ready()
+            sandbox.files.write(MARKER_FILE, MARKER_TEXT)
+            print(f"ready: {sandbox.id}")
+
+            sandbox.pause()
+            wait_for(sandbox, lambda s: s.phase == "Paused", "Paused")
+            print("paused")
+
+            print(f"RESULT: {use_paused_sandbox(sandbox)}")
+        except NeevAIError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            print("RESULT: failed")
+            sys.exit(1)
+        finally:
+            if sandbox is not None:
+                try:
+                    sandbox.delete()
+                except NeevAIError as e:
+                    print(f"cleanup failed, delete {sandbox.id} by hand: {e}", file=sys.stderr)
+                    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/workflow_examples/README.md b/examples/workflow_examples/README.md
index 96183c4..868b7be 100644
--- a/examples/workflow_examples/README.md
+++ b/examples/workflow_examples/README.md
@@ -34,7 +34,7 @@ final answer is written to `output/repo-analysis.md` on the host (from the
 loop's return value, not a sandbox file pull).
 
 ```sh
-# defaults to https://github.com/NeevCloudAI/neevai-sdk-python
+# defaults to https://github.com/NeevCloudAI/neev-sdk-python
 uv run python examples/workflow_examples/repo_analyzer.py
 
 # analyze a different repo
diff --git a/examples/workflow_examples/repo_analyzer.py b/examples/workflow_examples/repo_analyzer.py
index b6ead34..22b04d9 100644
--- a/examples/workflow_examples/repo_analyzer.py
+++ b/examples/workflow_examples/repo_analyzer.py
@@ -389,8 +389,8 @@ def main() -> None:
     parser = argparse.ArgumentParser(description="Analyze a git repository in a sandbox.")
     parser.add_argument(
         "--repo",
-        default="https://github.com/NeevCloudAI/neevai-sdk-python",
-        help="Repository URL to clone and analyze (default: neevai-sdk-python)",
+        default="https://github.com/NeevCloudAI/neev-sdk-python",
+        help="Repository URL to clone and analyze (default: neev-sdk-python)",
     )
     args = parser.parse_args()