@shardflux/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -3,7 +3,226 @@
 Every API the README shows is available from the version named here. Below 1.0, a minor release may break
 compatibility; breaking changes are marked **Breaking**.
 
-## 0.7.0 (not yet published; npm `latest` is 0.6.2)
+## 0.9.0 (not yet published; npm `latest` is 0.8.0)
+
+Elastic compute (decision 0007): file tools and wake hints for parked workspaces. Additive; older APIs and cell
+gateways keep working (the new calls answer 404 there).
+
+### File search, patches with revisions, the wake hint
+
+Needs a cell gateway with the contracts §26 routes (`files/search`, `files/patch`, `wake-hint`, revisions); an older
+gateway does not serve them and returns no revisions.
+
+- `cell.files.search(path, pattern, opts)`: content search under a directory (literal or RE2 with `regex`,
+  `caseInsensitive`, `include`/`exclude` globs, `maxMatches`, `maxFileBytes`, `contextLines`). Returns the gateway's
+  `FileSearchResult` (`matches` with `path`, 1-based `line` and byte `column`, `text`, optional `before`/`after`;
+  `truncated` and `stop_reason`; `files_scanned`) plus `served_from` (`disk` when a suspended workspace was searched on its disk
+  without waking it). It is read-only, so the HTTP layer retries it like a GET (new `RequestOptions.idempotent`).
+- `cell.files.patch({ path, edits | content, expectedRevision, createParents, mode }, { idempotencyKey })`: text
+  edits (`{ oldText, newText, replaceAll }`, each must match exactly once unless `replaceAll`, applied in order,
+  all or nothing) or a whole new `content`, atomic and durable. Every call sends an `Idempotency-Key` (like `write`),
+  so a retried call is applied once. `expectedRevision` (or `absent`) makes a concurrent change a 409.
+- Revisions: a file's revision is the SHA-256 of its content. `cell.files.stat(path, { revision: true })` returns it
+  (`FileInfo.revision`), writes and patches return it, and the new `cell.files.readWithInfo(path, opts)` returns
+  `{ data, size, revision, servedFrom }` from the read's `X-File-Size`, `X-File-Revision` and `X-Served-From` headers.
+  `read()` and `readText()` keep returning bytes and text: a separate method keeps every existing caller and return
+  type unchanged, where an options flag would have made `read()`'s return type depend on an argument. A read
+  continued over several requests reports a revision only when every part carried the same one.
+- `workspace.hint(opts)` sends `POST /wake-hint`: a hibernated workspace is restored ahead of the tool call that
+  follows. It returns `{ residency, wake }`; for a workspace that is not running (409 `workspace_not_running`, also
+  when its tool token cannot be issued) it starts `wake()` in the background and returns at once (`wake` is that
+  promise, shared by concurrent hints; `wake: null` in the options only reports it). It is never retried and never
+  waits out `workspace_busy`. `cell.wakeHint()` is the bare request.
+- Agent tools: `search_files` and `edit_file` (permission `files`), after `list_files`. `edit_file` patches with
+  `edits`; when the model gives no `expected_revision` it reads the file's revision first
+  (`stat?revision=true`) and pins the patch to it, so a change made in between is refused (`revision_mismatch`)
+  instead of edited blindly. `search_files` returns whole matches up to `maxOutputBytes` and counts the rest in
+  `omitted_matches`. The existing tools are unchanged. The tool runner sends `workspace.hint()` when a tool call
+  starts, without waiting for it; `workspaceTools(ws, { hint: false })` turns that off.
+- Errors: `KnownErrorReason` adds `revision_mismatch` (409, `details.current_revision`), `edit_not_found`,
+  `edit_ambiguous` (422, `details.index`), `edit_not_text`, `patch_invalid`, `host_capacity` and `wake_failed` (503,
+  retryable, `Retry-After`: retried by the HTTP layer for GETs, searches and requests with an Idempotency-Key, like
+  any retryable 503), `workspace_fenced` (409 `workspace_busy`, waited out like any `workspace_busy`), and for reads
+  of a sleeping workspace `offline_unavailable` and `offline_budget` (409 `workspace_not_running`: woken and retried
+  like any) and `offline_changed` (503, retried; served by the running workspace).
+- Reads of a suspended workspace without a held token: the API now issues tool tokens for a suspended workspace
+  (contracts §26.4), so `read`, `readText`, `readWithInfo`, `stat`, `list` and `search` of a suspended workspace are
+  served from its disk without waking it also for a handle that fetches its first token after the suspend (before,
+  the token was refused and the call woke the workspace). Any other call still wakes it: the cell refuses it with 409
+  `workspace_not_running`. Needs that API; with an older one the token is refused and the call wakes it as before.
+- The agent-tool runner sends no wake hint for `read_file`, `list_files` and `search_files`: a sleeping workspace
+  serves them from its disk, and the hint would wake a suspended one (or restore a hibernated one) for nothing.
+- Hosts without the features (contracts §26.7): `KnownErrorReason` adds `host_feature_unavailable` (409 `conflict`,
+  not retryable, `details.feature` `file_search` or `file_patch`): the workspace runs on a host agent that predates
+  the call, until it runs on an upgraded host. It is neither retried nor answered with a wake. Such a host also
+  returns no revisions (`FileInfo.revision`, `readWithInfo().revision` are absent).
+- `JsonSchema.pattern`, checked by `validateArgs()`.
+- Types: `FileSearchOptions`, `FileSearchResponse`, `FileSearchRequest`, `FileSearchResult`, `FileSearchMatch`,
+  `FilePatchParams`, `FilePatchEdit`, `FilePatchRequest`, `FilePatchResult`, `FileEdit`, `FileRevision`,
+  `FileReadResult`, `ServedFrom`, `Residency`, `WakeHintResult`, `HintOptions`, `HintResult`.
+
+### File-first workspaces (contracts §29)
+
+Needs an API with `FILE_FIRST_WORKSPACES` on and a cell that serves file-first workspaces (contracts §29.8). A
+file-first workspace has no VM between executions: its state is a versioned file tree under /home/user, and each
+command runs in a fresh VM whose changed files become the next tree revision. Processful workspaces are unchanged.
+
+- `workspaces.open({ mode: 'file_first' })` (`mode: 'processful' | 'file_first'`; omitted: the API's default). A
+  file-first open is ready at once (200 with a tool token, no operation). `workspace.mode` and `workspace.treeRevision`
+  (null for processful): the handle follows every `X-Tree-Revision` its cell clients see, execution results and
+  `refresh()`, and never moves backwards.
+- `workspace.executions.run(argv, opts)` / `cell.executions.run()`: runs one command as an execution and resolves when
+  it ended with an `ExecutionResult`: `stdout` / `stderr` bytes plus `text(stream)`, `stdoutText`, `stderrText`;
+  `exitCode`, `termSignal`, `timedOut`, `state` (`succeeded`, `failed`, `lost`), `baseRevision`, `treeRevision`,
+  `changed` (`{ path, change: added | modified | deleted, type }`), `changedTruncated`, the truncation flags,
+  `timings`, `error` / `errorReason`, `replayed`, `ok`, `raw`. Options: `executionId`, `cwd`, `env`, `user`, `stdin`,
+  `timeoutMs`, `killGraceMs`, `secretRefs`, `outputLimitBytes`, `maxRetries`, `attemptTimeoutMs`, `signal`.
+- Idempotent by execution id: `executionId` defaults to a fresh `ex-<uuid>` (`newExecutionId()`, checked against
+  `EXECUTION_ID` before any request). Network failures and retryable 429/5xx answers (503 `no_execution_host`, with
+  `Retry-After`, honoured up to 30 s) are retried with the same id and body at most `maxRetries` (5) times; a wait
+  longer than `attemptTimeoutMs` (300 s) re-attaches with the same id without counting as a failure. The cell answers
+  201 for the call that ran the command and 200 (`replayed`) with the recorded result for any other, so the command
+  runs at most once. `workspace_busy` `execution_in_progress` is waited out like any `workspace_busy`;
+  `execution_id_reused` is thrown at once. A `failed` or `lost` result is returned, never retried with a new id.
+- `executions.get(id, { waitMs })`: the result (`GET /executions/{id}`), or a `pending` one (202, state `queued` /
+  `running`) while it runs; `waitMs` polls (250 ms doubling to 2 s) until it ended or the wait elapsed.
+- `ifTreeRevision` on `files.write`, `remove`, `mkdir`, `move` and `patch` sends `If-Match`: the call applies only at
+  that tree revision, else `TreeRevisionMismatchError` (409 `conflict` `tree_revision_mismatch`, with
+  `currentTreeRevision`) and nothing changed.
+- Calls the mode lacks fail with `NotSupportedForModeError` (409 `conflict` `not_supported_for_mode`, `mode`,
+  `operation`, `local`): locally, without a request, when the handle knows the mode (file-first: exec sessions, PTY,
+  processes, git, browser, `changes()`, `suspend`, `resume`, `snapshot`, `fork`, `reset`, `saveAsTemplate`;
+  processful: `executions.*` and `ifTreeRevision`, which a processful cell would ignore), otherwise as the server's
+  refusal, typed the same way. On a file-first workspace `wake()` resolves `false` and `hint()` / `cell.wakeHint()`
+  answer `resident` without a request (nothing sleeps).
+- Agent tools: `workspaceTools()` of a file-first workspace offers `exec` and the files tools only; its `exec` runs an
+  execution and returns `execution_id`, `state`, `tree_revision`, `changed` (up to 200, `changed_truncated`) and
+  `error` besides the output. New options: `mode` (build definitions without touching the workspace) and
+  `onExecution(id)` (called with the execution id before it is sent, so a caller that gives up can fetch the result).
+  **Breaking:** `workspaceTools()` now reads `workspace.mode` while building the definitions unless `mode` is given; a
+  caller that builds definitions from a stand-in workspace (as the MCP server does) passes `mode`.
+- Errors: every error is built by reason, so `NotSupportedForModeError` and `TreeRevisionMismatchError` (both
+  `ShardfluxApiError`) come from any call; `ShardfluxApiError.treeRevision` is the refusal's `X-Tree-Revision`. Their
+  `name` is the subclass's (code that compared `err.name` with `'ShardfluxApiError'` should use `instanceof`).
+  `KnownErrorReason` adds `not_supported_for_mode`, `mode_mismatch`, `mode_not_available`, `layout_unsupported`,
+  `tree_revision_mismatch`, `outside_tree_root`, `execution_in_progress`, `execution_id_reused`,
+  `operation_id_reused`, `no_execution_host`, and the execution error reasons `lease_expired`, `host_unreachable`,
+  `host_restarted`, `tree_moved`, `blob_missing`, `blob_corrupt`, `exec_failed_to_start`. Retry progress causes name the
+  reason (`HTTP 503 service_unavailable no_execution_host`).
+- Types: `WorkspaceMode`, `ExecutionResult`, `ExecutionResultBody`, `ExecutionChange`, `ExecutionState`,
+  `ExecutionError`, `ExecutionRunOptions`, `ExecutionGetOptions`, `TreeRevisionOptions`.
+
+### Waking a suspended workspace is one request (contracts §22.6)
+
+Needs an API with the held resume for the single request; against an older API every call below works as in 0.7.0.
+
+- The wake of a tool call refused with `workspace_not_running` (and `hint()`'s background wake, and `wake()`) sends
+  one `POST /v1/workspaces/{id}/resume` with `Prefer: wait` and the calling client's agent label and tools. The API
+  answers once the workspace runs, with the view and a tool token minted during the restore: the handle keeps both
+  and the refused call is retried at once. On staging the automatic wake made five requests before the command
+  (refused call, resume, wait, view, token: 1,118 ms median, against 838 ms for a held reopen); it is now two.
+- Without `Preference-Applied`, or on a 202 (not finished within the hold), the wake waits for the operation and reads
+  the view as before; the retried call then fetches its token.
+- `resume({ wait })` (handle and `workspaces.resume(id)`) is the same single held request; a handle takes the view and
+  the token. `serverWait: false` keeps the polled path. A workspace that is already running still throws `conflict`
+  `already_running` (the held answer is 200 without an operation; the SDK reports it as before).
+- Timing: a held resume or wake is one `request` phase with reason `held`; `server` comes from the returned operation.
+- New options: `WakeOptions.agentLabel` / `tools` and `ResumeOptions` (`agentLabel`, `tools`; `WaitedResumeOptions`)
+  choose the token that comes back; `cell()`'s own wake passes its label and tools. `WorkspacesApi.requestResume()`
+  is the bare request (`ResumeAnswer`, `ResumeRequestOptions`, `ResumeResponse`).
+- `CellClient`: after a wake that put a new token into the client's manager, the retry uses it instead of fetching one.
+### The account plane and the version check (contracts §30)
+
+Needs an API with CLI sessions and client versions (contracts §30). Every API is additive; the one change in
+behavior is the automatic version check (below), which makes one background request per process.
+
+### Account plane: `ShardfluxAccount`
+
+- `ShardfluxAccount`: what a person does in the web app, from code, with a CLI session (`sfu_<token>`, sent as
+  `Authorization: Bearer` on `/v1`). Options: `sessionToken?`, `baseUrl?`, `fetch?`, `userAgent?`, `timeoutMs?`,
+  `maxRetries?`, `sleep?`, `onSessionToken?`, `versionCheck?`, `onProgress?`. A malformed token throws (shape
+  `^sfu_[A-Za-z0-9_-]{43}$`, also `isSessionToken()` and `SESSION_TOKEN_PATTERN`).
+- Before a session exists (static, no token): `register({ email, password, displayName? })`,
+  `verifyEmail(linkOrToken)`, `requestPasswordReset(email)`, `confirmPasswordReset({ token, newPassword })`,
+  `confirmEmailChange(linkOrToken)` and `login({ email, password, onSessionToken? })` → `{ account, result }`
+  (`result.status` `authenticated` or `mfa_required`). Each takes the client options.
+- Token rotation: login, `auth.completeMfa()`, `auth.stepUp()`, `auth.changePassword()`, `auth.totp.confirm()` and
+  `auth.totp.disable()` return a new token (the previous one is revoked). `account.sessionToken` always holds the
+  current one, every later call (the reused namespaces included) sends it, and `onSessionToken({ token, expiresAt })`
+  is called (and awaited) with each.
+- Namespaces: `auth` (`session`, `completeMfa`, `logout`, `logoutAll`, `sessions`, `revokeSession`, `stepUp`,
+  `changePassword`, `changeEmail`, `resendVerification`, `totp.enroll|confirm|disable|regenerateRecoveryCodes`),
+  `organizations` (`list`, `listAll`, `create`, `get`, `entitlements`, `deletion`, `delete`, `exports.create|get|download`,
+  `workspaces`), `projects` (`list`, `listAll`, `create`, `get`), `apiKeys` (`list`, `create`, `revoke`), `members`
+  (`list`, `update`, `remove`), `invitations` (`list`, `create`, `revoke`, `accept`), `billing` (`catalog`,
+  `subscription`, `checkout`, `checkoutStatus`, `waitForCheckout`, `portal`, `invoices`, `spendPolicy`,
+  `setSpendPolicy`), `user` (`deletion`, `scheduleDeletion`, `cancelDeletion`, `exports.create|get|download`),
+  `templates` (every `TemplatesApi` method plus `publishVersion` and `archiveVersion`), `audit` (`list`, `listAll`,
+  `export` → the CSV or NDJSON text), `usage`, `secrets`, `egress`, `volumes`, `workspaces`, `me()` and `request()`.
+  List methods return the API's page `{ data, next_cursor }`.
+- `apiKeys.create(projectId, { name, toolPermissions?, expiresAt?, idempotencyKey? })` sends an Idempotency-Key (a
+  fresh one unless given), so a retried request returns the same key and secret instead of creating a second key.
+  `toolPermissions` defaults to `[]`; `API_KEY_TOOL_PERMISSIONS` lists every tool.
+- `billing.waitForCheckout(orgId, checkoutId, { timeoutMs?, intervalMs?, signal? })` polls until the subscription is
+  active or the checkout expired, was canceled or failed, and returns that status; after `timeoutMs` (default 15 min)
+  it throws `CheckoutTimeoutError` (`checkout`, `waitedMs`), on abort the signal's reason.
+- `parseEmailToken(input)`: the `token` of an emailed link's `#token=` fragment or `?token=` query (percent-decoded),
+  else the trimmed input; throws for an empty input or a link without a token. Every method that takes an emailed
+  token accepts the whole link.
+- Errors are `ShardfluxApiError` as elsewhere; the session adds the codes `step_up_required` (call `auth.stepUp()` and
+  retry), `mfa_required` and `email_unverified` (403).
+
+### Version check
+
+- `checkClientVersion({ baseUrl?, fetch?, package?, version?, ecosystem?, timeoutMs?, signal? })` →
+  `ClientVersionStatus` `{ status, package, ecosystem, current, latest, minimumSupported, upgradeCommand,
+  releaseNotesUrl, message? }` from `GET /v1/client-versions`. `status`: `unsupported` (below `minimum_supported`),
+  `outdated` (below `latest`), `current`, or `unknown` (no entry, `latest` null, a version that does not parse, or the
+  request failed; it never throws). `compareVersions(a, b)` → -1, 0, 1, or null for a string that is not
+  `major.minor.patch` (a pre-release sorts before its release).
+- Automatic: after the first successful API response of a `Shardflux` or `ShardfluxAccount` client, once per process
+  per package identity, a background request (3 s timeout, every error swallowed; it never delays a call) emits
+  `process.emitWarning(message, { type: 'ShardfluxUpdateWarning', code: 'SHARDFLUX_UPDATE_AVAILABLE' })` when the
+  package is outdated or unsupported. Option `versionCheck?: boolean | { package, version, ecosystem? }` on both
+  clients (default `@shardflux/sdk` at `SDK_VERSION`; tools built on the SDK pass their own identity or `false`).
+  Off with `SHARDFLUX_NO_UPDATE_CHECK=1` (also `true`, `yes`, `on`) or `NO_UPDATE_NOTIFIER=1`. `fetchBillingCatalog()`
+  does not check.
+
+### Feedback straight to the founder (POST /v1/feedback)
+
+- `cloud.sendFeedback({ message, category?, context? })` sends feedback to the Shardflux founder by email and returns
+  `{ id, receivedAt, duplicate }`. `category`: `bug`, `confusing`, `missing`, `idea`, `praise` or `other` (default).
+  `context`: `agent`, `client`, `workspace`, `requestId`, `errorCode`, `command`, `page` (sent in snake_case);
+  `client` defaults to `shardflux-sdk-ts/<SDK_VERSION>`.
+- `duplicate: true`: the same message from the same key within 24 hours; the original is returned and no second email
+  is sent. 429 `rate_limited` (with `retryAfterSeconds`) and 422 `validation_failed` are `ShardfluxApiError`s. The call
+  is a POST without an idempotency key, so it is never retried.
+- `ShardfluxAccount.sendFeedback({ ..., organizationId? })`: the same with a CLI session, as the signed-in user,
+  optionally about one of their organizations (404 `not_found` for another).
+- New exports: `FeedbackCategory`, `FeedbackContext`, `FeedbackReceipt`, `SendFeedbackParams`, `AccountFeedbackParams`,
+  `FEEDBACK_CATEGORIES`, `FEEDBACK_MESSAGE_MAX_LENGTH`.
+
+## 0.8.0 (2026-09-28)
+
+Types only; nothing changes at run time and the API is unchanged.
+
+### Provider tool exports type-check without casts
+
+- `toAnthropicTools(tools)` is assignable to `Anthropic.Tool[]` (`@anthropic-ai/sdk`) and `toOpenAITools(tools, { api:
+  'responses' })` to `OpenAI.Responses.FunctionTool[]` (`openai`) under TypeScript's `strict` checks, with no `as`
+  casts. `toOpenAITools(tools)` (and `{ api: 'chat' }`) is assignable to `OpenAI.Chat.ChatCompletionTool[]`.
+- `toOpenAITools` has one return type per format (overloads): an `api` known only at run time still returns either
+  array, as before.
+- `JsonSchema` is a type alias instead of an interface, so a schema is assignable to the providers' open schema types
+  (`{ [key: string]: unknown }`). An object literal typed as `JsonSchema` still rejects a misspelt keyword.
+- `executeToolCall(tools, call)` takes `input` as `unknown`, as the Anthropic SDK's `ToolUseBlock` types it, so a
+  `tool_use` block is passed as it is (no `block.input as Record<string, unknown>`); `execute` validates it as before.
+- New exported types for the three formats: `AnthropicToolDefinition`, `OpenAIChatToolDefinition`,
+  `OpenAIResponsesToolDefinition`.
+- Checked at compile time against `@anthropic-ai/sdk` 0.128.0 and `openai` 7.23.0 (devDependencies only; the SDK still
+  has no runtime dependencies).
+
+## 0.7.0 (2026-09-28)
 
 Needs an API with the template editor (contracts §24); every new field is additive and older fields are unchanged.
 

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.7.0. Anything marked **(0.7.0+)** is 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.9.0. Anything marked **(0.9.0+)** is 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,53 @@ 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).
 
+### 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).
 
@@ -153,8 +201,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 +326,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
@@ -383,18 +480,38 @@ parameters and an `execute` function. Export them for your model provider and di
 calls:
 
 ```ts
+import Anthropic from '@anthropic-ai/sdk';
 import { executeToolCall, toAnthropicTools, toOpenAITools, workspaceTools } from '@shardflux/sdk';
 
 const tools = workspaceTools(workspace);
-const anthropicTools = toAnthropicTools(tools);   // or toOpenAITools(tools)
+const anthropicTools: Anthropic.Tool[] = toAnthropicTools(tools);
+const chatTools = toOpenAITools(tools);                               // OpenAI Chat Completions
+const responsesTools = toOpenAITools(tools, { api: 'responses' });    // OpenAI Responses API
 
-// For each tool call the model makes:
-const output = await executeToolCall(tools, { name: call.name, input: call.input });
+// For each tool call the model makes (an Anthropic tool_use block, or an OpenAI function_call item, as it is):
+const output = await executeToolCall(tools, block);
 ```
 
+**(0.8.0+)** The exports type-check as the provider SDKs' own types under `strict`, with no casts:
+`Anthropic.Tool[]`, `OpenAI.Chat.ChatCompletionTool[]` and, with `{ api: 'responses' }`,
+`OpenAI.Responses.FunctionTool[]`. `executeToolCall` takes a `tool_use` block's `unknown` input as it is and validates
+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
@@ -534,6 +651,58 @@ 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.
+```
+
 ## Errors
 
 - `ShardfluxApiError`: the API or the workspace refused the request. Fields: `status`, `code`,
@@ -546,22 +715,90 @@ 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`.
 
+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.
+
+## 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
   any release; ignore unknown fields.
-- While below 1.0, a breaking change bumps the minor version (0.6 to 0.7).
+- While below 1.0, a breaking change bumps the minor version (0.7 to 0.8).
 - `SDK_VERSION` is exported; requests send `User-Agent: shardflux-sdk-ts/<version>`.
 - Examples in this README, in `examples/` and on shardflux.dev name the version they need. The examples on the
   website and in the console are checked against the version published on npm before they ship.