@shardflux/sdk 0.8.0 → 0.10.0

package/README.md

@@ -10,8 +10,8 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 > **Early access.** Shardflux is in early access. The API is versioned (`/v1`), but this SDK is
 > below 1.0: a minor release may contain breaking changes (see [Compatibility](#compatibility)).
 
-> **Versions.** This README describes 0.8.0. Anything marked **(0.8.0+)** is not in 0.7.x, **(0.7.0+)** not in 0.6.x
-> and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
+> **Versions.** This README describes 0.10.0. Anything marked **(0.10.0+)** is not in 0.9.0, **(0.9.0+)** not in 0.8.x, **(0.8.0+)** not in 0.7.x,
+> **(0.7.0+)** not in 0.6.x and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
 - ESM only, no runtime dependencies, Node.js 24 or later. Reading a YAML template file uses the optional peer
@@ -67,11 +67,12 @@ const cloud = new Shardflux({
   baseUrl: process.env.SHARDFLUX_API_URL,          // optional: default https://api.shardflux.dev
   timeoutMs: 30_000,                               // optional: per-request timeout
   maxRetries: 2,                                   // optional: retries of safe or idempotent requests
+  versionCheck: true,                              // optional (0.9.0+): see Version check
 });
 ```
 
-The SDK reads nothing from the environment by itself. `SHARDFLUX_API_KEY` and `SHARDFLUX_API_URL`
-are the conventional names (the `shard` CLI reads them); pass them in as shown.
+The SDK reads nothing from the environment by itself (except the version check's opt-out). `SHARDFLUX_API_KEY` and
+`SHARDFLUX_API_URL` are the conventional names (the `shard` CLI reads them); pass them in as shown.
 
 ## Commands and files
 
@@ -100,6 +101,70 @@ await cell.files.remove('/home/user/data.bin');
 twice. Aborting its `signal` also cancels the command in the workspace. File writes are atomic
 and durable (acknowledged after fsync).
 
+`cwd` is an absolute path (commands start in `/home/user` without one). The API refuses a relative
+`cwd` with 422 `validation_failed` (`err.reason === 'invalid_cwd'`); the message names the absolute
+path it likely means. A command that could not start (a `cwd` that is not a directory, a program
+that is not on `PATH`) rejects with `ExecStartError` **(0.10.0+)**, whose message is the workspace's
+reason; before 0.10.0 `exec.run()` resolved with `exitCode: null` and no output.
+
+```ts
+import { ExecStartError } from '@shardflux/sdk';
+
+try {
+  await cell.exec.run(['ls'], { cwd: '/home/user/app' });
+} catch (err) {
+  if (!(err instanceof ExecStartError)) throw err;
+  console.error(err.message); // The command could not start: working directory "/home/user/app" is not a directory
+}
+```
+
+### Search, patch and revisions (0.9.0+)
+
+```ts
+const hits = await cell.files.search('/home/user/project', 'TODO', { include: ['**/*.py'], contextLines: 1 });
+for (const m of hits.matches) console.log(`${m.path}:${m.line}:${m.column}: ${m.text}`);
+
+// A file's revision is the SHA-256 of its content.
+const { revision } = await cell.files.stat('/home/user/project/app.py', { revision: true });
+const patched = await cell.files.patch({
+  path: '/home/user/project/app.py',
+  edits: [{ oldText: 'DEBUG = True', newText: 'DEBUG = False' }],   // must occur exactly once (or replaceAll)
+  expectedRevision: revision,                                        // refused if the file changed meanwhile
+});
+patched.revision;                                                    // the next expectedRevision
+
+const { data, revision: current, servedFrom } = await cell.files.readWithInfo('/home/user/project/app.py');
+```
+
+- `search()` searches a directory (or one file) and returns matching lines in path order (`path`, 1-based `line` and
+  byte `column`, `text`), stopping at `maxMatches` (default 200), a 10 s budget or 4 MiB of results (`truncated`,
+  `stop_reason`). `include`/`exclude` globs are gitignore-style: `*.py` matches a name at any depth, `src/**/*.ts`
+  a path relative to the searched directory, `build/` directories only. Binary files, symbolic links, files above
+  `maxFileBytes` and `.git`/`node_modules` (unless `exclude` is given) are skipped.
+- `patch()` requests are limited to 7 MiB (413 `payload_too_large`; write larger files with `write()`) and files to
+  64 MiB.
+- `patch()` applies all edits or none, atomically and durably, and always sends an `Idempotency-Key`. `content`
+  replaces the whole file instead; `expectedRevision: 'absent'` requires that the file does not exist yet. A changed
+  file is 409 `conflict` with `reason` `revision_mismatch` and `details.current_revision`; an edit that does not match
+  exactly once is 422 `edit_not_found` or `edit_ambiguous` with `details.index`.
+- A suspended workspace whose disk is still on a host is read, listed and searched there without waking it; such
+  results say `servedFrom: 'disk'` (`served_from` on search results). Everything else wakes it as usual. This also
+  works for a handle without a tool token from before the suspend: the API issues tokens for suspended workspaces.
+- While the fleet is being upgraded, a workspace may run on a host that predates search and patches: they are 409
+  `conflict` with `reason` `host_feature_unavailable` and `details.feature` (`file_search`, `file_patch`), not
+  retryable (read and write the file, or run `grep` with `exec`, instead), and revisions are omitted.
+
+### Wake hint (0.9.0+)
+
+An idle running workspace may be parked by its host (frozen or hibernated) and is restored by the next tool call.
+`workspace.hint()` tells the host a tool call is coming so the restore starts earlier: call it when your model starts
+emitting a tool call, before its arguments are complete. It is cheap and returns at once; a suspended workspace is
+resumed in the background (`result.wake`). The agent tools below send it when each call starts.
+
+```ts
+void workspace.hint().catch(() => {});   // fire and forget
+```
+
 The same client has `exec.start/get/output/signal/cancel`, `pty`, `processes`, `git` and
 `browser` (screenshot and page content).
 
@@ -146,6 +211,29 @@ try {
 }
 ```
 
+### Suspend when idle (0.10.0+)
+
+A running workspace is billed while it is awake, and its idle policy waits a while before suspending it. When your
+agent's turn ends, ask for a suspend once the workspace has been idle for a short time instead:
+
+```ts
+const { suspendRequest } = await workspace.suspendWhenIdle({ afterSeconds: 60 }); // 30..3600
+workspace.suspendRequest;               // { requested_at, after_seconds, not_before } until it applies or is cancelled
+await workspace.cancelSuspendWhenIdle(); // idempotent
+```
+
+- The idle time counts from the later of the workspace's last work and the request; `not_before` is the earliest
+  suspend.
+- A command still running, an attached exec or terminal stream, or a keepalive postpones the suspend until
+  `afterSeconds` after it ends.
+- The next tool call on the workspace (the next turn) or a resume cancels the request. Repeating replaces it.
+- It applies under every idle policy, `never` included, and never delays a suspend the policy would do sooner.
+- When a suspend is already in progress, the result's `operation` is that suspend and nothing is recorded.
+- Errors: `ShardfluxApiError` 409 with `reason` `not_running`, `operation_in_progress`, `session_lifetime` or
+  `workspace_deleted`, and 422 `validation_failed` for `afterSeconds` outside 30..3600. A file-first workspace is never
+  suspended: `NotSupportedForModeError` (409 `not_supported_for_mode`).
+- By id: `cloud.workspaces.suspendWhenIdle(id, { afterSeconds })` and `cloud.workspaces.cancelSuspendWhenIdle(id)`.
+
 **Suspended workspaces wake on use.** A tool call 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 to finish. The call
 never runs twice: the cell executes nothing it refused.
@@ -153,8 +241,13 @@ never runs twice: the cell executes nothing it refused.
 - The wait is bounded per call by `transitionTimeoutMs` (default 120 000 ms), shared by the transition waits and at
   most 3 wakes. A resume or open still pending at the end throws `OperationTimeoutError`, naming the operation, its
   state and reason. A failed resume or open throws `OperationFailedError` at once.
+- The wake is one request (0.9.0+): the API holds the resume until the workspace runs and answers with the view and a
+  tool token for the calling client, so the refused call is retried at once (refused call, resume, the call). Its
+  timing is one `request` phase with reason `held`. An API without the held resume answers at once; the SDK then waits
+  for the operation, reads the view and fetches a token, as before.
 - Following an exec's output never wakes a workspace, so an explicit `suspend()` is respected.
-- `workspace.wake({ timeoutMs })` does the same on demand.
+- `workspace.wake({ timeoutMs })` does the same on demand (`agentLabel` / `tools` pick the token it brings back).
+  `workspace.resume({ wait: true })` is the same single held request: the handle keeps the view and the token.
 - `workspace.cell({ wake: null })` returns `workspace_not_running` instead.
 
 ```ts
@@ -273,6 +366,50 @@ const page = await ws.changes({ pathPrefix: '/home/user', summary: true });   //
 `legacy_disk_layout`. `changes()` is served by the cell from the running workspace and needs the `files` tool.
 `cell().changesAll()` follows the pages.
 
+## File-first workspaces (0.9.0+)
+
+A file-first workspace has no VM between commands. Its state is a versioned file tree under /home/user (tree
+revisions 0, 1, 2, ...). Each command runs as an execution: a fresh VM on the latest revision, whose changed files
+become the next revision. Nothing else survives an execution (processes, memory, files outside /home/user), so install
+dependencies into /home/user (for example a virtualenv) and start servers within the command that uses them. It is
+ready as soon as it is opened and is never suspended.
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'customer-42/repo', template: 'python-node-browser', mode: 'file_first' });
+const cell = ws.cell();
+await cell.files.write('/home/user/app/main.py', 'print("hi")\n', { createParents: true });
+
+const r = await ws.executions.run(['bash', '-lc', 'cd app && python3 main.py > out.txt && cat out.txt'], { timeoutMs: 600_000 });
+r.state;          // 'succeeded' (any exit code), 'failed' or 'lost' (nothing published; r.errorReason says why)
+r.exitCode;       // 0
+r.stdoutText;     // 'hi\n' (r.stdout holds the bytes)
+r.changed;        // [{ path: '/home/user/app/out.txt', change: 'added', type: 'file' }]
+r.treeRevision;   // 2: the revision the execution published (= baseRevision when it changed nothing)
+ws.treeRevision;  // 2
+
+// Conditional writes: applied only if the tree is still at that revision.
+await cell.files.write('/home/user/app/main.py', 'print("bye")\n', { ifTreeRevision: ws.treeRevision! });
+// ... else TreeRevisionMismatchError (err.currentTreeRevision): read what changed and try again.
+```
+
+- **Executions are idempotent by id.** `executionId` defaults to a fresh `ex-<uuid>`; pass your own to make a call safe
+  to repeat across processes. Network failures and retryable 5xx answers (503 `no_execution_host`: no host has room;
+  the SDK waits `Retry-After`) are retried with the same id, at most `maxRetries` (5) times, and an answer that takes
+  longer than `attemptTimeoutMs` (300 s) is awaited again with the same id. The cell runs a command once per id: a
+  repeated call gets the recorded result (`r.replayed`). The SDK never retries with a new id: a `failed` or `lost`
+  result is returned, and running it again is your decision.
+- `ws.executions.get(id, { waitMs })` reads an execution: `pending` while it runs, its result when it ended (kept 7
+  days). Use it after a call that stopped waiting (an aborted `signal`): an execution cannot be canceled.
+- While an execution runs, other executions and file writes are refused with 409 `workspace_busy`
+  (`execution_in_progress`); the SDK waits them out within `transitionTimeoutMs` (120 s).
+- Only paths under /home/user exist (`outside_tree_root` otherwise). Reads, writes, `search()` and `patch()` work as on
+  a processful workspace, on the latest revision.
+- Calls a file-first workspace does not have fail with `NotSupportedForModeError` before any request: exec sessions
+  (`cell.exec.*`), PTY, processes, git, browser, `changes()`, `suspend`, `resume`, `snapshot`, `fork`, `reset` and
+  `saveAsTemplate`. On a processful workspace `executions` and `ifTreeRevision` are refused the same way.
+- Reopening a key with another `mode` is 409 `mode_mismatch`; a deployment without file-first workspaces answers 422
+  `mode_not_available`; a legacy template 409 `layout_unsupported`.
+
 ## Templates: file tree, diff and dev mode
 
 ```ts
@@ -403,6 +540,18 @@ it.
 Your agent loop and model calls stay in your application; the workspace is the computer the tools
 act on.
 
+The tools are `exec`, `read_file`, `write_file`, `list_files`, `search_files` and `edit_file` (0.9.0+), the process,
+terminal, git and browser tools, filtered by the tools your key grants. `edit_file` replaces exact text; when the
+model passes no `expected_revision` it reads the file's revision first, so a change made in between fails the edit
+instead of being overwritten. Each call first sends `workspace.hint()` without waiting for it (`hint: false` turns
+that off, e.g. when you send the hint yourself as the model starts a tool call), except `read_file`, `list_files` and
+`search_files`: a sleeping workspace answers them from its disk without waking.
+
+For a file-first workspace (0.9.0+) the tools are `exec` and the files tools only: `exec` runs each command as an
+execution and adds `execution_id`, `state`, `tree_revision` and `changed` to its result, and the process, terminal,
+git and browser tools are not offered. `workspaceTools(ws, { mode })` builds the definitions without touching the
+workspace; `onExecution(id)` is called with each execution id before it is sent.
+
 ## Tool-call capture (0.7.0+)
 
 Your harness's tools (web search, SQL, HTTP APIs, MCP servers) run in your application, so their results reach the
@@ -480,7 +629,7 @@ never injected).
 
 **Read-your-writes.** Calls through the same client first wait for capture writes recorded before them (bounded by
 `settleTimeoutMs`, 30 s; they never fail because of capture): `exec` and files calls through `workspace.cell()`,
-`workspaceTools`, `snapshot`, `fork`, `suspend`, `saveAsTemplate` and `close` (on the workspace handle and on
+`workspaceTools`, `snapshot`, `fork`, `suspend`, `suspendWhenIdle` (0.10.0+), `saveAsTemplate` and `close` (on the workspace handle and on
 `cloud.workspaces.*(id)`). A lifecycle call's timing shows the wait as a `capture_flush` phase. `delete` and `reset`
 drop pending writes. A write to a suspended workspace wakes it (`wake: null` opts out).
 
@@ -542,6 +691,78 @@ await workspace.cell().exec.run(['python3', 'agent.py']);          // sees $OPEN
   `accessEvents`, `createOrganization` and `listOrganization`. Organization-wide secrets and access
   logs belong to organization owners and admins, so a project API key gets 403 for those.
 
+## Account (ShardfluxAccount) (0.9.0+)
+
+`ShardfluxAccount` does what a person does in the web app, with a user session instead of an API key: sign up, sign
+in (with MFA), organizations, projects, API keys, members, invitations, billing, audit, data export and account
+deletion. Two steps stay human: opening the verification email, and paying in Stripe Checkout.
+
+```ts
+import { Shardflux, ShardfluxAccount } from '@shardflux/sdk';
+
+// Before a session exists (static; no token needed). Emailed links can be passed whole.
+await ShardfluxAccount.register({ email, password, displayName: 'Ada' });     // { status: 'accepted' }
+await ShardfluxAccount.verifyEmail('https://app.shardflux.dev/auth/verify-email#token=...');
+
+const { account, result } = await ShardfluxAccount.login({ email, password, onSessionToken: (s) => save(s.token) });
+if (result.status === 'mfa_required') await account.auth.completeMfa({ code: '123456' });   // or { recoveryCode }
+
+// Later, with the saved token (sfu_<43 characters>; a malformed one throws).
+const again = new ShardfluxAccount({ sessionToken: saved, onSessionToken: (s) => save(s.token) });
+const org = await again.organizations.create({ name: 'Acme' });
+const project = await again.projects.create(org.id, { name: 'Default' });
+const { secret } = await again.apiKeys.create(project.id, { name: 'agent', toolPermissions: ['exec', 'files'] });
+const cloud = new Shardflux({ apiKey: secret });                                // the sfk_ key, shown once
+```
+
+- The session token is sent as `Authorization: Bearer sfu_...` on `/v1`. Login completion, `auth.stepUp()`,
+  `auth.changePassword()`, `auth.totp.confirm()` and `auth.totp.disable()` rotate it (the old token stops working):
+  `account.sessionToken` always holds the current token, every later call uses it, and `onSessionToken({ token,
+  expiresAt })` is called (and awaited) with each new one. Save it there. Sessions idle out after 30 days.
+- Sensitive calls (exports, deletions, TOTP changes, …) answer 403 `step_up_required` without a recent password
+  check: `await account.auth.stepUp({ password, code })`, then retry. A session still waiting for its second factor
+  gets 403 `mfa_required`; an unverified email 403 `email_unverified`.
+- Namespaces: `auth` (session, MFA, logout, sessions, step-up, password and email change, `totp`), `organizations`
+  (`list`, `listAll`, `create`, `get`, `entitlements`, `deletion`, `delete`, `exports`, `workspaces`), `projects`,
+  `apiKeys` (`create` sends an Idempotency-Key, so a retry never makes a second key; `toolPermissions` defaults to
+  `[]`), `members`, `invitations` (`accept(linkOrToken)`), `billing`, `user` (account `deletion`, `scheduleDeletion`,
+  `cancelDeletion`, `exports`), `templates` (plus `publishVersion` and `archiveVersion`), `audit` (plus `export(orgId,
+  { format: 'csv' | 'ndjson', ...filters })`, the text), and `usage`, `secrets`, `egress`, `volumes` with explicit
+  organization and project ids; `me()` and `request()`. List methods return the API's page `{ data, next_cursor }`;
+  `listAll` iterates every page.
+- `parseEmailToken(input)` returns the `token` of a link's `#token=` fragment or `?token=` query (else the trimmed
+  input), and throws for a link without one.
+
+Upgrading a plan: a person pays at the Checkout `url`; the code waits for the subscription.
+
+```ts
+const checkout = await account.billing.checkout(org.id, { planKey: 'pro' });   // 409 subscription_exists: use billing.portal()
+console.log(`Pay here: ${checkout.url}`);
+const done = await account.billing.waitForCheckout(org.id, checkout.id, { timeoutMs: 15 * 60_000 });
+if (!done.subscription_active) console.log(`checkout ${done.status}`);          // expired, canceled or failed
+// After timeoutMs: CheckoutTimeoutError (err.checkout is the last status); on abort: the signal's reason.
+```
+
+Opt-in overage and its spend cap (owners and billing members): read the policy, then change it. Every field is
+optional (give at least one); `ifMatch` (the `version` you read) makes a concurrent change a 409 `version_mismatch`
+instead of overwriting it.
+
+```ts
+const policy = await account.billing.spendPolicy(org.id);
+// overage_state: unavailable | off | on | paused; the cap range: spend_cap_min_minor..spend_cap_max_minor (the plan price)
+if (policy.overage_available) {
+  await account.billing.setSpendPolicy(org.id, { overageEnabled: true, spendCapMinor: 900, ifMatch: policy.version }); // $9.00
+}
+await account.billing.setSpendPolicy(org.id, { overageEnabled: false });           // always allowed
+await account.billing.setSpendPolicy(org.id, { alertThresholdsPercent: [50, 80, 100] });
+```
+
+A refused change is a `ShardfluxApiError` 422 `validation_failed` with `reason` `overage_unavailable`,
+`spend_cap_required`, `spend_cap_below_minimum` (`details.min_minor`), `spend_cap_above_plan_price`
+(`details.max_minor`) or `spend_cap_below_charges` (`details.charges_minor`: the cap cannot go below what overage
+already charged this period). Every owner and billing member gets an email when overage is turned on or off or the cap
+changes.
+
 ## Errors
 
 - `ShardfluxApiError`: the API or the workspace refused the request. Fields: `status`, `code`,
@@ -554,17 +775,127 @@ await workspace.cell().exec.run(['python3', 'agent.py']);          // sees $OPEN
 - `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`, `lastState`, `lastReason`,
   `deadlineAt` **(0.6.2+)** while it waits for capacity, `timing`).
 - `ShardfluxProtocolError`: a response was not the documented shape.
+- `NotSupportedForModeError` **(0.9.0+)**, a `ShardfluxApiError` (409 `conflict`, `reason` `not_supported_for_mode`):
+  the call does not exist for the workspace's `mode`; `local` is true when the SDK refused it without a request.
+- `TreeRevisionMismatchError` **(0.9.0+)**, a `ShardfluxApiError` (409 `conflict`, `reason` `tree_revision_mismatch`):
+  an `ifTreeRevision` call found the tree at `currentTreeRevision`; nothing changed.
+- `CheckoutTimeoutError` **(0.9.0+)**: `billing.waitForCheckout()` gave up; the checkout stays open (`checkout`,
+  `waitedMs`).
 
 Treat unknown error codes and reasons as generic errors: show `message`, and use `retryable`.
 
+A 402 `allowance_exhausted` (opens, resumes and forks refused while a CPU-hours or RAM GiB-hours allowance is used up)
+carries `reason` **(0.9.0+)**:
+
+| `reason` | Meaning | What to do |
+| --- | --- | --- |
+| `allowance_used` | The allowance is used up and overage is off or not on the plan. | Upgrade, or have an owner or billing member turn on overage under Usage & billing; or wait for `details.resets_at`. |
+| `overage_paused` | Overage is on but paused while a plan payment is past due. | An owner or billing member updates the payment method. |
+| `spend_cap_reached` | Overage charges reached the spend cap for this billing period. | Raise the cap (up to the plan price) or upgrade under Usage & billing; or wait for `details.resets_at`. |
+
+`details.spend_cap` is `{ cap_minor, effective_cap_minor, charges_minor, currency }` (minor units, `null` when the plan
+has no overage). An older API sends no `reason`. Do not retry these in a loop.
+
+Retryable 429/502/503/504 refusals (for example 503 `host_capacity`, when the workspace's host has no room to restore
+it right now, or `wake_failed`) are retried after `Retry-After` for reads, searches and calls that carry an
+Idempotency-Key (writes and patches); other calls surface them with `retryable: true` and `retryAfterSeconds`.
+A read of a sleeping workspace that its disk cannot answer (409 `workspace_not_running` with `reason`
+`offline_unavailable` or `offline_budget`) wakes the workspace and is retried like any `workspace_not_running`; 503
+`offline_changed` (the disk changed during the read) is retried and served by the running workspace. 409 `conflict`
+`host_feature_unavailable` (the workspace's host predates the call, `details.feature`) is neither retried nor
+woken: it lasts until the workspace runs on an upgraded host.
+
+## Usage and overage
+
+`cloud.usage` reads the organization's usage (API keys see organization totals and their own project's workspaces):
+`summary(orgId)`, `series(orgId, params)`, `workspace(workspaceId, params)`, `estimate(orgId)`, `grants(orgId)`,
+`spend(orgId)` and `spendPolicy(orgId)`.
+
+```ts
+const s = await cloud.usage.summary(orgId);
+if (s.allowance_exhausted) console.log('starts are refused:', s.exhausted_reason); // allowance_used | overage_paused | spend_cap_reached
+const cap = s.spend_cap; // opt-in overage this period (0.10.0+)
+const usd = (minor: number) => `$${(minor / 100).toFixed(2)}`; // amounts are minor units of cap.currency
+if (cap.state === 'accruing' || cap.state === 'warning') {
+  console.log(`overage ${usd(cap.charges_minor)} of ${usd(cap.effective_cap_minor)}; cap reached ${cap.projected_reached_at ?? 'not this period'}`);
+}
+```
+
+Opt-in overage **(0.10.0+)**: while an owner or billing member has turned it on, workspaces keep opening and running
+past the CPU-hours and RAM GiB-hours allowances (those allowances show `cap_state: 'overage'`), and the usage past them
+is charged on the next invoice until the charges reach the spend cap.
+
+- `summary()`, `spend()` and `estimate()` carry `spend_cap` (type `SpendCap`): `state` (`unavailable`, `off`,
+  `paused`, `within_allowance`, `accruing`, `warning`, `reached`), `cap_minor`, `effective_cap_minor`,
+  `charges_minor`, `remaining_minor`, `percent_of_cap`, `currency`, `resets_at`, `lines` (per allowance: `units_over`,
+  `billed_units`, `rate_minor`, `amount_minor`) and `projected_reached_at`. `summary()` and `spend()` also carry
+  `exhausted_reason`.
+- `spendPolicy()` returns the settings: `overage_available`, `overage_enabled`, `overage_state` (`unavailable`, `off`,
+  `on`, `paused`), `spend_cap_minor`, `spend_cap_min_minor`, `spend_cap_max_minor`, `rates` and `currency`.
+- An API key only reads them. Owners and billing members turn overage on or off and change the cap in the console,
+  or with a user session: `ShardfluxAccount.billing.setSpendPolicy()` (see below).
+
+## Feedback (0.9.0+)
+
+`cloud.sendFeedback()` sends a message straight to the Shardflux founder, who reads every one. If you or your coding
+agent hit something while building with Shardflux, send it the moment it happens: a call that failed unexpectedly, an
+error or doc that was confusing, something missing or slow, a workaround you needed. Short and specific beats polished;
+the request id and error code let the founder find the logs.
+
+```ts
+try {
+  await cloud.workspaces.open({ key: 'acme/demo', template: 'python-node-browser' });
+} catch (err) {
+  if (err instanceof ShardfluxApiError) {
+    await cloud.sendFeedback({
+      message: 'open failed with capacity_unavailable twice in 10 minutes; expected a start within a minute',
+      category: 'bug',
+      context: { requestId: err.requestId, errorCode: err.code, workspace: 'acme/demo', agent: 'claude-code' },
+    });
+  }
+  throw err;
+}
+```
+
+- `message`: 1-8000 characters. `category`: `bug` (something failed or behaved wrongly), `confusing` (an error, doc,
+  name or output was unclear), `missing` (a capability, option or template you needed), `idea`, `praise` or `other`
+  (the default).
+- `context` (all optional): `agent` (who is reporting, e.g. `claude-code`), `workspace`, `requestId`, `errorCode`,
+  `command` (the call that led to it), and `client`, which defaults to `shardflux-sdk-ts/<version>`.
+- Returns `{ id, receivedAt, duplicate }`. The same message from the same key within 24 hours returns the original
+  with `duplicate: true` and sends no second email.
+- Any API key may send feedback. Signed in with a CLI session instead, `account.sendFeedback({ message, category?,
+  context?, organizationId? })` sends it as the user (`ShardfluxAccount`; `organizationId`: one of yours). It is rate
+  limited per key or user: a `ShardfluxApiError` with `code: 'rate_limited'` and `retryAfterSeconds`. An empty or too-long message is `validation_failed`. The SDK never retries the call.
+- Anything shaped like an API key is redacted before the message is stored or emailed; still, leave secrets out.
+
 ## More of the API
 
 The `Shardflux` object also has `templates` (including custom template builds and the template editor), `volumes`
 (shared persistent storage attached to workspaces), `secrets` (see above), `egress` (outbound allowlists),
-`usage`, `billing`, `me()`, `entitlements(orgId)` and `request(method, path)` for any `/v1`
+`usage`, `billing`, `me()`, `entitlements(orgId)`, `sendFeedback()` and `request(method, path)` for any `/v1`
 route. The package exports the OpenAPI-generated types as well (`paths`, `components`,
 `WorkspaceView`, `Operation` and more).
 
+## Version check (0.9.0+)
+
+After the first successful API response of the process, the SDK asks `GET /v1/client-versions` in the background
+(once per process, 3 s timeout, every error ignored; it never delays or fails a call). When this version is outdated
+or no longer supported, it emits one warning:
+
+```
+(node:1234) [SHARDFLUX_UPDATE_AVAILABLE] ShardfluxUpdateWarning: @shardflux/sdk 0.9.0 is outdated: 0.10.0 is available. Update: npm install @shardflux/sdk@latest
+```
+
+- Turn it off with `versionCheck: false` (on `Shardflux` or `ShardfluxAccount`), `SHARDFLUX_NO_UPDATE_CHECK=1` (also
+  `true`, `yes`, `on`) or `NO_UPDATE_NOTIFIER=1`. Handle it with `process.on('warning', (w) => ...)`
+  (`w.name === 'ShardfluxUpdateWarning'`).
+- A tool built on the SDK checks its own package instead: `versionCheck: { package: '@acme/tool', version: '1.2.3' }`.
+- On demand: `await checkClientVersion()` returns `{ status, package, ecosystem, current, latest, minimumSupported,
+  upgradeCommand, releaseNotesUrl, message? }` with `status` `current`, `outdated`, `unsupported` or `unknown` (the
+  request failed, or the package is not listed yet). `compareVersions(a, b)` compares two `major.minor.patch` versions
+  (a pre-release sorts first; `null` when one does not parse).
+
 ## Compatibility
 
 - The SDK follows the API's `/v1` contract. New fields, enum values and error codes can appear in