@shardflux/sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+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.6.0 (not yet published; npm `latest` is 0.5.0)
+
+### Lifecycle calls: requested or finished
+
+- `suspend`, `resume`, `snapshot`, `fork`, `delete`, `reset` and `close` take `wait`. Without it they resolve when the
+  change is **requested** (the operation is usually still `queued`), as before. With `{ wait: true }` (or
+  `WaitOptions`) they resolve when it has **finished**: they return the succeeded operation (typed
+  `FinishedOperation`) and, on a workspace handle, refresh it, so `workspace.state` is `suspended` after
+  `await workspace.suspend({ wait: true })`. A failed operation throws `OperationFailedError`; running out of time
+  throws `OperationTimeoutError` (the operation continues).
+
+### Lifecycle timing and progress
+
+- `onProgress` on `new Shardflux()`, `workspaces.open()`, `waitForOperation()`, `wake()`, every lifecycle call and
+  `workspace.cell()`. Events: `phase` (the request, each observed operation state with the server's reason such as
+  `capacity_pending` / `no_ready_host`, the view read, the first tool token), `retry` (a transient failure retried,
+  with its cause and backoff), and `done` with the call's `LifecycleTiming`.
+- `LifecycleTiming` separates the client's phases from the operation's own server timing (`queuedMs`, `runMs`,
+  start or resume path, boot to ready, host restore steps) and reports `outsideServerMs`: time spent outside the
+  operation (network, TLS, polling, view and token).
+- `workspace.lastTiming` (open, wake, waited lifecycle calls); `timing` on `OperationTimeoutError`,
+  `OperationFailedError` and `ShardfluxApiError` when a traced call fails; `formatTiming()` prints a timing.
+- Tool token fetches are traced (action `token`, reason `initial`, `expiring` or `invalidated`), and tool calls report
+  `workspace_busy` waits, replaced stale tokens and retries (action `tool`).
+- Needs an API that reports `started_at` on operations for `queuedMs` / `runMs`; with an older API they are null.
+
+### Faster opens and waits
+
+- `open()` holds the request on the server until the workspace is ready (`Prefer: wait`, up to 20 s per request) and
+  receives the first tool token in the same response; it pre-connects to the workspace's cell meanwhile.
+- `waitForOperation()` and `templates.builds.waitForBuild()` use server-held polls (at most 20 s per request) and
+  fall back to backoff (250 ms doubling to 5 s, ±20 % jitter) against a server without them.
+- On Node 26 the default `fetch` sends `Connection: close` (its bundled undici 8 can stall a request on a reused
+  keep-alive connection for tens of seconds). `SHARDFLUX_HTTP_KEEPALIVE=1` or your own `fetch` changes that.
+
+### Suspended workspaces wake on use
+
+- A tool call on a suspended workspace resumes it (or joins the resume or open already running) and then runs,
+  bounded by `transitionTimeoutMs` (default 120 000 ms); calls during a suspend or resume wait for it.
+  `workspace.wake()` does the same on demand; `workspace.cell({ wake: null })` opts out.
+
+### Workspaces
+
+- Secret bindings: `open({ secrets })`, `workspace.secrets.get()/set()`; `cloud.secrets` gained
+  `createOrganization`, `listOrganization` and `accessEvents`.
+- Sessions: `open({ lifetime: 'session' })`, `workspace.close()`, `idleTimeoutSeconds`, `endedReason`.
+- Layered workspaces: `workspace.reset()`, `saveAsTemplate()`, `changes()`, `diskLayout`, `origin`.
+- `workspaces.findByKey()` (live workspace first, then tombstones), `list({ lifetime, purpose })`, `pickByKey()`.
+- Templates: `templates.files()`, `fileEntry()`, `diff()`, `diffAll()`, and dev mode (`templates.draft(slug)`:
+  create, capture state, test instances, publish, discard).
+- `ShardfluxApiError.reason` (`details.reason`), with `KnownErrorReason`.
+
+## 0.5.0 (2026-09-26)
+
+First public release: `Shardflux` client, `workspaces.open/get/list/listAll`, lifecycle calls returning operations,
+`waitForOperation()`, the cell client (`exec`, `files`, `pty`, `processes`, `git`, `browser`), `workspaceTools()` with
+`toOpenAITools()` / `toAnthropicTools()` / `executeToolCall()`, secrets, egress, usage, billing, volumes, templates and
+custom template builds.

package/README.md

@@ -9,6 +9,10 @@ tools (exec, files, processes, PTY, git, browser) that plug into any model provi
 > **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.6.0. Anything marked **(0.6.0+)** is 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.
 - Typed from the published OpenAPI documents.
 - Retries, idempotency keys, operation polling and tool-token refresh are handled for you.
@@ -25,23 +29,33 @@ Create a project API key in the Shardflux console (`sfk_<key id>_<secret>`) and
 server. API keys are server credentials: never put one in a browser bundle.
 
 ```ts
-import { Shardflux } from '@shardflux/sdk';
+import { Shardflux, formatTiming } from '@shardflux/sdk';
 
 const cloud = new Shardflux({ apiKey: process.env.SHARDFLUX_API_KEY! });
-
-// Creates the workspace on first use; afterwards reconnects (or resumes) the same one.
-const workspace = await cloud.workspaces.open({ key: 'customer-42/main', template: 'python-node-browser' });
-
-const cell = workspace.cell();
-const result = await cell.exec.run(['python3', '-c', 'print(40 + 2)']);
-console.log(result.exitCode, result.stdout); // 0 "42\n"
-
-await cell.files.write('/home/user/notes.txt', 'hello from the SDK\n');
-console.log(await cell.files.readText('/home/user/notes.txt'));
+const open = () => cloud.workspaces.open({ key: 'customer-42/main', template: 'python-node-browser' });
+
+// 1. Open the workspace (created on first use) and run a command. Check that it worked.
+const workspace = await open();
+const run = await workspace.cell().exec.run(['python3', '-c', 'print(40 + 2)']);
+if (run.exitCode !== 0) throw new Error(`python3 exited ${run.exitCode}: ${run.stderr}`);
+console.log(run.stdout.trim());                          // 42
+
+// 2. Write a file, then suspend the workspace and wait until the suspend has finished.
+await workspace.cell().files.write('/home/user/notes.txt', 'hello from the SDK\n');
+await workspace.suspend({ wait: true });                 // (0.6.0+) resolves once suspended
+
+// 3. Open the same key again: the workspace resumes, and the file is still there.
+const again = await open();
+console.log(await again.cell().files.readText('/home/user/notes.txt'));   // hello from the SDK
+console.log(formatTiming(again.lastTiming!));            // (0.6.0+) where the resume's time went
 ```
 
 `open()` waits until the workspace is running. Opening the same key again never resets it: files,
-installed packages and running processes are still there.
+installed packages and running processes are still there. The same program is in
+[`examples/quickstart.ts`](./examples/quickstart.ts).
+
+With 0.5.0, wait for the suspend by its operation instead:
+`await cloud.workspaces.waitForOperation((await workspace.suspend()).id)`.
 
 ## Configuration
 
@@ -90,19 +104,56 @@ The same client has `exec.start/get/output/signal/cancel`, `pty`, `processes`, `
 ## Lifecycle
 
 ```ts
-await workspace.suspend();                    // memory and processes are checkpointed
-await workspace.resume();                     // or simply open() the key again
+await workspace.suspend({ wait: true });      // memory and processes are checkpointed; resolves once suspended
+await workspace.resume({ wait: true });       // or simply open() the key again
 
-const { operation, workspace: copy } = await workspace.fork({ key: 'customer-42/experiment' });
-await cloud.workspaces.waitForOperation(operation.id);
+const { workspace: copy } = await workspace.fork({ key: 'customer-42/experiment' }, { wait: true });
 
 await copy.delete();                          // tool access ends immediately; keys are never reused
 ```
 
+### Requested or finished
+
+`suspend`, `resume`, `snapshot`, `fork`, `delete`, `reset` and `close` start a lifecycle operation. What the promise
+means depends on `wait`:
+
+| Call | Resolves when | Returns |
+| --- | --- | --- |
+| `await workspace.suspend()` | the suspend is **requested** (usually `queued`; the workspace is still running) | the operation (`Operation`) |
+| `await workspace.suspend({ wait: true })` **(0.6.0+)** | the suspend has **finished** (`workspace.state` is then `suspended`) | the succeeded operation (`FinishedOperation`) |
+
+`wait` also takes `WaitOptions` (`timeoutMs`, default 5 minutes; `signal`; `onProgress`). A failed operation throws
+`OperationFailedError`. Running out of time throws `OperationTimeoutError`, and the operation continues server side:
+wait again with `cloud.workspaces.waitForOperation(err.operationId)`. Without `wait`, the returned operation is the
+handle for the work in progress: pass its `id` to `waitForOperation()` when you need it finished.
+
+**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.
+
+- 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.
+- Following an exec's output never wakes a workspace, so an explicit `suspend()` is respected.
+- `workspace.wake({ timeoutMs })` does the same on demand.
+- `workspace.cell({ wake: null })` returns `workspace_not_running` instead.
+
+```ts
+const cell = workspace.cell({ transitionTimeoutMs: 30_000 }); // give up waking after 30 s
+await cell.exec.run(['make', 'test']);                         // resumes the workspace first if it is suspended
+```
+
 `suspend`, `resume`, `fork`, `snapshot` and `delete` return the lifecycle operation.
-`cloud.workspaces.waitForOperation(id)` polls it with backoff (250 ms doubling to 5 s, ±20 %
-jitter, default timeout 5 minutes). If the timeout passes, it throws `OperationTimeoutError`
-and the operation keeps running server side; wait for it again with the same call.
+`cloud.workspaces.waitForOperation(id)` waits for it (default timeout 5 minutes): each poll asks the API to hold
+the response until the operation changes (`Prefer: wait`, at most 20 s per request), so completion arrives within
+one round trip of the commit. Against an API without bounded waits (or with `serverWait: false`) it polls with
+backoff (250 ms doubling to 5 s, ±20 % jitter). If the timeout passes, it throws `OperationTimeoutError` and the
+operation keeps running server side; wait for it again with the same call. `templates.builds.waitForBuild()` waits
+the same way. A waited `open()` issues the first tool token together with the final workspace read, so the first
+tool call starts at once.
+
+On Node 26 the default fetch sends `Connection: close`: its bundled undici 8 can stall a request on a reused
+keep-alive connection for tens of seconds. Pass your own `fetch`, or set `SHARDFLUX_HTTP_KEEPALIVE=1`, to change that.
 
 List and look up workspaces:
 
@@ -110,8 +161,128 @@ List and look up workspaces:
 const page = await cloud.workspaces.list({ keyPrefix: 'customer-42/' });
 for await (const ws of cloud.workspaces.listAll()) console.log(ws.key, ws.state);
 const same = await cloud.workspaces.get(workspace.id);
+const byKey = await cloud.workspaces.findByKey('customer-42/main');   // null when no workspace has the key
 ```
 
+`list()` shows persistent standard workspaces by default. Pass `lifetime`
+(`persistent` | `session` | `any`) and `purpose` (`standard` | `template_draft` | `template_test` | `any`) to see
+sessions, template drafts and test instances. `findByKey()` searches every lifetime and purpose. It returns the live
+workspace, and a tombstone only when no live workspace has the key. Use it rather than `listAll({ keyPrefix })` for
+lookups by key.
+
+### Timing and progress (0.6.0+)
+
+Every open, wake and waited lifecycle call is traced. `workspace.lastTiming` (and `err.timing` when the call fails)
+says where the time went, and `formatTiming()` prints it:
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'customer-42/main', template: 'python-node-browser' });
+console.log(formatTiming(ws.lastTiming!));
+```
+
+A slow open (34 s instead of the usual second) then reads, for example:
+
+```text
+open 34.18 s, succeeded (workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342, operation 01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33)
+  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 0.59 s → view 42 ms ∥ token 61 ms
+  server: queued 33.40 s, ran 0.62 s, total 34.02 s; start warm, boot to ready 79 ms
+  outside the server: 0.16 s
+```
+
+Here the time went to waiting for a host with capacity; the network and the VM start were fast.
+
+- **client** phases are on your monotonic clock: the request (a held open waits on the server, `held`), then each
+  operation state the SDK observed while waiting, with the server's reason (`capacity_pending` / `no_ready_host`:
+  waiting for a host; `running` / `template_downloading`: fetching the template), then reading the workspace and
+  issuing the first tool token (together).
+- **server** timing comes from the operation itself (one database clock): `queued` is creation until it began
+  running, including any wait for capacity; `ran` is the cell's work (placement, boot or restore, guest readiness).
+  `start` / `resume from` and `boot to ready` / `host …` are what the cell reported.
+- **outside the server** is your total minus the operation's: network, TLS, polling latency, view and token. A large
+  value with a small server total points at the connection between you and the API, not at the workspace.
+- **retries** lists transient failures the SDK retried (cause and backoff).
+
+Watch it live with `onProgress` (on the client for every call, or per call):
+
+```ts
+const cloud = new Shardflux({
+  apiKey: process.env.SHARDFLUX_API_KEY!,
+  onProgress: (e) => {
+    if (e.type === 'phase') console.error(`${e.action}: ${e.phase}${e.reason ? ` (${e.reason})` : ''} at ${e.atMs} ms`);
+    if (e.type === 'retry') console.error(`${e.action}: retry ${e.retry.request}: ${e.retry.cause}`);
+    if (e.type === 'done') console.error(formatTiming(e.timing));
+  },
+});
+```
+
+Events are `phase` (a phase began), `retry` and `done` (with the `LifecycleTiming`). Tool calls add `token` traces
+(a tool token fetched: `initial`, `expiring` or `invalidated`) and `tool` events (a `busy` wait, a stale token
+replaced, a retry). `queued`/`ran` need an API that reports the operation's `started_at`; otherwise they are null.
+
+### Sessions
+
+A session workspace is discarded when its session ends. The session ends on `close()`, or after it has been idle for
+the idle timeout (10 minutes unless the template sets one). The key then opens a new, empty workspace with a new id.
+
+```ts
+const ws = await cloud.workspaces.open({ key: `job-${jobId}`, template: 'python-node-browser', lifetime: 'session' });
+try {
+  await ws.cell().exec.run(['python3', 'job.py']);
+} finally {
+  await ws.close();   // sessions: ends it (returns the delete operation); persistent: no request, returns null
+}
+```
+
+- `close()` is safe in `finally` for any workspace. It always aborts the handle's local streams (exec output, PTY
+  reads and in-flight cell requests); commands keep running. Only for a session does it call
+  `POST /v1/workspaces/{id}/close`.
+- Disconnecting, a closed WebSocket or an expired token never ends a session.
+- A session cannot be suspended (409, `details.reason` `session_lifetime`). Fork it to keep its state. `fork()`
+  takes its own `lifetime` (default `persistent`).
+- Reopening a live key with a different `lifetime` is 409 `lifetime_mismatch`.
+
+### Reset, save as template, changes (layered workspaces)
+
+```ts
+await ws.reset();                                   // wipes every change; restarts on the template (7-day recovery point)
+const { operation, build } = await ws.saveAsTemplate({ templateSlug: 'acme-dev', description: 'deps installed' });
+await cloud.templates.builds.waitForBuild(build.organization_id, build.id);
+const page = await ws.changes({ pathPrefix: '/home/user', summary: true });   // added | modified | metadata | deleted | replaced
+```
+
+`ws.diskLayout` says whether a workspace is `layered`. A legacy workspace is refused with 409
+`legacy_disk_layout`. `changes()` is served by the cell from the running workspace and needs the `files` tool.
+`cell().changesAll()` follows the pages.
+
+## Templates: file tree, diff and dev mode
+
+```ts
+const dir = await cloud.templates.files('python-node-browser', 5, { path: '/usr/local/bin' });
+const entry = await cloud.templates.fileEntry('acme-dev', 3, '/home/user/.bashrc');
+const diff = await cloud.templates.diff('acme-dev', { from: 2, to: 3 });   // diff.summary on the first page; from: 'base' too
+for await (const d of cloud.templates.diffAll('acme-dev', { from: 2, to: 3 })) console.log(d.change, d.path);
+```
+
+Versions published before file lists answer 409 `file_list_unavailable`. A version that is still being indexed
+answers `file_list_indexing` (retryable).
+
+Develop an organization template in a draft: a layered workspace you edit live.
+
+```ts
+const draft = cloud.templates.draft('acme-dev');
+const { workspace } = await draft.create({ base: 'python-node-browser@5' });  // one live draft per template
+await workspace.cell().exec.run(['bash', '-lc', 'npm ci']);
+await draft.captureState({ label: 'deps installed' });
+const test = await draft.openTestInstance();         // a session on a copy of the state; the draft never sees its writes
+await test.close();
+const { build } = await draft.publish({ description: 'npm ci' });   // 409 draft_stale if the template moved on
+await draft.discard();                               // deletes the draft and ends its test instances
+```
+
+`draft.get()` throws 404 `draft_not_found` when there is no draft. `draft.find()` returns null instead.
+`states()`, `statesAll()` and `testInstances({ includeEnded })` list the draft's states and test instances. Only
+owners, admins and API keys with a tool permission may change drafts; others get 403 `template_dev_mode_role`.
+
 ## Agent tools
 
 `workspaceTools(workspace)` returns tools with a name, a description, a JSON Schema for the
@@ -131,21 +302,52 @@ const output = await executeToolCall(tools, { name: call.name, input: call.input
 Your agent loop and model calls stay in your application; the workspace is the computer the tools
 act on.
 
+## Secrets
+
+Store credentials once and give them to a workspace's processes as environment variables. Values
+are write-only: no API returns them. Every exec and terminal in the workspace receives the secrets
+bound to it, plus any the call names in `secretRefs`.
+
+```ts
+const project = (await cloud.me()).api_key!.project_id;
+await cloud.secrets.create(project, { name: 'OPENAI_API_KEY', value: process.env.OPENAI_API_KEY! });
+
+// Bind by name when opening (a new key gets the binding; an existing key has it replaced).
+const workspace = await cloud.workspaces.open({ key: 'customer-42/main', template: 'python-node-browser', secrets: ['OPENAI_API_KEY'] });
+
+await workspace.secrets.get();                          // { names, secrets: [{ name, status, ... }] }
+await workspace.secrets.set(['OPENAI_API_KEY', 'DATABASE_URL']);   // replace; [] clears
+await workspace.cell().exec.run(['python3', 'agent.py']);          // sees $OPENAI_API_KEY and $DATABASE_URL
+```
+
+- A name that is unknown, or a secret this workspace may not use, is refused with
+  `ShardfluxApiError` 422 (`details.reason` `secret_not_available`, `details.names`); nothing
+  changes. A bound secret must allow the `exec` and `pty` tools (the default).
+- `status` per bound name: `available`, `not_allowed` (its permissions no longer cover this
+  workspace; starts are refused with 403 `secret_not_available` until fixed) or `deleted`.
+- Deleting a secret removes it from every binding. Forks keep the binding, but secrets limited to
+  specific workspaces are checked against the fork's own id.
+- A bound name that is also passed in `env` is refused (422).
+- `cloud.secrets` also has `list`, `get`, `update`, `rotate`, `versions`, `delete`,
+  `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.
+
 ## Errors
 
 - `ShardfluxApiError`: the API or the workspace refused the request. Fields: `status`, `code`,
-  `message`, `requestId`, `retryable`, `details`, `operationId`, `retryAfterSeconds`.
+  `message`, `requestId`, `retryable`, `details`, `operationId`, `retryAfterSeconds`, and `reason`
+  (`details.reason`, e.g. `not_session`, `draft_not_found`, `legacy_disk_layout`; see `KnownErrorReason`).
 - `OperationFailedError`: an awaited operation ended `failed` or `canceled` (`errorCode`,
-  `operation`).
-- `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`).
+  `operation`, `timing`).
+- `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`, `timing`).
 - `ShardfluxProtocolError`: a response was not the documented shape.
 
-Treat unknown error codes as generic errors: show `message`, and use `retryable`.
+Treat unknown error codes and reasons as generic errors: show `message`, and use `retryable`.
 
 ## More of the API
 
 The `Shardflux` object also has `templates` (including custom template builds), `volumes`
-(shared persistent storage attached to workspaces), `secrets`, `egress` (outbound allowlists),
+(shared persistent storage attached to workspaces), `secrets` (see above), `egress` (outbound allowlists),
 `usage`, `billing`, `me()`, `entitlements(orgId)` and `request(method, path)` for any `/v1`
 route. The package exports the OpenAPI-generated types as well (`paths`, `components`,
 `WorkspaceView`, `Operation` and more).
@@ -156,6 +358,8 @@ route. The package exports the OpenAPI-generated types as well (`paths`, `compon
   any release; ignore unknown fields.
 - While below 1.0, a breaking change bumps the minor version (0.5 to 0.6).
 - `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.
 
 ## License
 

package/dist/cell.d.ts

@@ -7,6 +7,9 @@
  * (token expired or revoked early) invalidates the token and retries once with
  * a fresh one; the retried request is safe because the gateway rejected the
  * first before any effect (and exec/PTY starts are idempotent by session_id).
+ * The same holds for lifecycle refusals (contracts §20.4): `workspace_busy` is
+ * waited out and `workspace_not_running` wakes the workspace, then the call is
+ * retried, all within one bounded transition budget per call.
  *
  * Exec output is retained in the guest and addressed by byte offsets, so
  * `exec.run()` survives gateway restarts/disconnects by reconnecting with the
@@ -14,6 +17,7 @@
  */
 import type { components, paths } from './generated/cell-api.js';
 import type { RequestOptions } from './http.js';
+import type { ProgressListener } from './progress.js';
 import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
 export type ExecStartRequest = S['ExecStartRequest'];
@@ -34,6 +38,24 @@ export type BrowserScreenshotRequest = S['BrowserScreenshotRequest'];
 export type BrowserContentRequest = S['BrowserContentRequest'];
 export type BrowserContent = S['BrowserContent'];
 export type Signal = S['SignalValue'];
+/** One entry of a workspace's changes against its template (contracts §19.10). */
+export type WorkspaceChange = S['WorkspaceChange'];
+export type WorkspaceChangeKind = WorkspaceChange['change'];
+export type WorkspaceChangesSummary = S['WorkspaceChangesSummary'];
+/** One page of changes in raw path-byte order; `summary` only when requested. */
+export type WorkspaceChangesPage = S['WorkspaceChangesPage'];
+export interface WorkspaceChangesParams {
+    /** Absolute path; only entries at or below it (default `/`). */
+    pathPrefix?: string;
+    /** 1..1000 (gateway default 1000). */
+    limit?: number;
+    /** `next_cursor` of the previous page. */
+    cursor?: string;
+    /** Hash regular files of 16 MiB or less (reports `metadata` when content equals the template's). */
+    hash?: boolean;
+    /** Also return totals over everything under pathPrefix. */
+    summary?: boolean;
+}
 type CellPath = keyof paths;
 /** Fills a path template that must exist in cell-api.yaml. */
 export declare function cellPath<P extends CellPath>(template: P, params: Record<string, string | number>): string;
@@ -44,7 +66,33 @@ export interface CellClientOptions {
     /** Retries for idempotent calls on transient failures (default 2). */
     maxRetries?: number;
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Wakes a suspended workspace (resume, or join the active resume/open) within `timeoutMs` and resolves once it runs;
+     * resolves `false` when there was nothing to wake (the API already reports it running), and the refusal then
+     * surfaces. It throws when the wake fails (OperationFailedError) or outlasts `timeoutMs` (OperationTimeoutError).
+     * Workspace.cell() supplies `workspace.wake()`. A call refused with `workspace_not_running` wakes the workspace and is
+     * retried; a refused call was never executed (contracts §20.4), so the retry cannot duplicate it. `null` surfaces
+     * the refusal instead.
+     */
+    wake?: ((timeoutMs: number, signal?: AbortSignal) => Promise<boolean | void>) | null;
+    /**
+     * Total time one call spends waiting for lifecycle transitions: `workspace_busy` waits plus wakes (default
+     * 120 000 ms). The wake hook gets what is left of it.
+     */
+    transitionTimeoutMs?: number;
+    /**
+     * Progress of this client's tool calls: tool token fetches (action `token`, with their timing), and `tool` events for
+     * `workspace_busy` waits (phase `busy`), stale or rejected tokens and transient failures retried (type `retry`).
+     * Through Workspace.cell() a wake reports here too (action `wake`).
+     */
+    onProgress?: ProgressListener;
+}
+/** Per-request transition handling (internal to CellClient). */
+interface TransitionOptions {
+    /** Wake a suspended workspace for this call (default true; exec output follow reconnects pass false). */
+    wake?: boolean;
 }
+export declare const DEFAULT_TRANSITION_TIMEOUT_MS = 120000;
 export interface RunResult {
     sessionId: string;
     exitCode: number | null;
@@ -94,8 +142,21 @@ export declare class CellClient {
     readonly workspaceId: string;
     readonly tokens: ToolTokenManager;
     constructor(workspaceId: string, tokens: ToolTokenManager, opts?: CellClientOptions);
-    /** One authorized request; refreshes the token once on stale_epoch / 401. */
-    request(method: string, path: string, init?: RequestOptions): Promise<Response>;
+    /** True after close(): every request (and stream) of this client is aborted. */
+    get closed(): boolean;
+    /**
+     * Aborts every in-flight and future request of this client, including exec output streams and PTY reads (commands
+     * keep running in the workspace: nothing is canceled there). Workspace.close() calls it.
+     */
+    close(): void;
+    /**
+     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions (contracts §20.4),
+     * bounded in total by `transitionTimeoutMs`: a call refused with `workspace_busy` is retried after `Retry-After`; one
+     * refused with `workspace_not_running` (or whose token cannot be minted because the workspace is not running) wakes
+     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call.
+     * Refused calls were never executed, so retrying is safe. When the budget is spent the refusal surfaces.
+     */
+    request(method: string, path: string, init?: RequestOptions & TransitionOptions): Promise<Response>;
     readonly exec: {
         /** Starts argv (no shell). Idempotent by session_id: an existing session is returned, never re-run. */
         start: (req: ExecStartRequest, signal?: AbortSignal) => Promise<ExecSession>;
@@ -182,6 +243,10 @@ export declare class CellClient {
             overwrite?: boolean;
         }) => Promise<FileInfo>;
     };
+    /** One page of the workspace's changes against its template (needs the `files` tool). */
+    changes(params?: WorkspaceChangesParams): Promise<WorkspaceChangesPage>;
+    /** Every change under `pathPrefix`, following next_cursor. */
+    changesAll(params?: Omit<WorkspaceChangesParams, 'cursor' | 'summary'>): AsyncGenerator<WorkspaceChange>;
     readonly git: {
         clone: (req: GitCloneRequest) => Promise<GitResult>;
         status: (path: string) => Promise<GitStatus>;