@shardflux/sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,264 @@
 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.10.0 (not yet published; npm `latest` is 0.9.0)
+
+### A command that could not start rejects exec.run() (ExecStartError)
+
+A minor release for one runtime change. Production (2026-09-29): `shard ws exec <key> --cwd app -- ls` exited 1 and
+printed nothing, because the session ended `failed_to_start` and `exec.run()` dropped its reason.
+
+- **Breaking:** `cell.exec.run()` rejects with the new `ExecStartError` when the command could not start (a `cwd` that
+  is not a directory, a program not on `PATH`, an unknown user). It was resolving with `exitCode: null`, empty output
+  and the reason only in `session.error`. `ExecStartError` extends `ShardfluxApiError` as a 409 `conflict` with
+  `reason` `exec_failed_to_start` (as a file-first execution that could not start reports it), `details.session_id`,
+  `details.error`, `sessionId` and `session`; its message is `The command could not start: <the workspace's reason>`,
+  e.g. `working directory "/home/user/app" is not a directory`. Also when a start answered `starting` ends that way.
+- The `exec` agent tool (processful) returns `error: { code, message, reason }` with `exit_code: null` for such a
+  command, as the file-first `exec` tool does for a failed execution, instead of an empty result. Tool definitions
+  are unchanged.
+- The cell API now refuses a relative `cwd` on exec, execution and PTY starts with 422 `validation_failed`,
+  `details.reason` `invalid_cwd`, `details.field` `cwd` (for every SDK version); the message names the absolute path
+  it likely means, e.g. `use "/home/user/app"`. `KnownErrorReason` adds `invalid_cwd`; `RunOptions.cwd` and the cell
+  types (regenerated) document it.
+
+### Opt-in overage with a spend cap
+
+Additive: an API without overage sends no `spend_cap` and no `reason`. The usage reads change types only (regenerated
+from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overage fields.
+
+- Opt-in overage: `usage.summary()`, `spend()` and `estimate()` report `spend_cap` (new type `SpendCap`: `state`
+  `unavailable` | `off` | `paused` | `within_allowance` | `accruing` | `warning` | `reached`, `cap_minor`,
+  `effective_cap_minor`, `max_cap_minor`, `charges_minor`, `remaining_minor`, `percent_of_cap`, `currency`,
+  `resets_at`, `lines` per allowance with `units_over`, `billed_units`, `rate_minor`, `amount_minor`, and
+  `projected_reached_at`). Allowances past `included` while overage is on have `cap_state: 'overage'`; `summary()`
+  and `spend()` add `exhausted_reason`, and `spend.usage_charges_minor` and the estimate's charges are real amounts.
+- `usage.spendPolicy()` and `ShardfluxAccount.billing.spendPolicy()` return the overage settings:
+  `overage_available`, `overage_enabled`, `overage_state` (`unavailable` | `off` | `on` | `paused`),
+  `spend_cap_minor`, `spend_cap_min_minor`, `spend_cap_max_minor`, `rates`, `currency` and `version`.
+- `ShardfluxAccount.billing.setSpendPolicy(orgId, update)` (owners and billing members, with a user session; an API
+  key gets 403) takes `overageEnabled` and `spendCapMinor` besides `alertThresholdsPercent`, all optional (at least
+  one; an empty update throws before any request), and `ifMatch` (the `version` read, or `'*'`), sent as If-Match. New
+  type `SpendPolicyUpdate`. Runtime change: the body carries only the fields given.
+- 402 `allowance_exhausted` carries `details.reason` (`allowance_used`, `overage_paused`, `spend_cap_reached`; also
+  `err.reason`) and `details.spend_cap` (`cap_minor`, `effective_cap_minor`, `charges_minor`, `currency`).
+  `KnownErrorReason` adds them, the spend-policy refusals (422 `overage_unavailable`, `spend_cap_required`,
+  `spend_cap_below_minimum`, `spend_cap_above_plan_price`, `spend_cap_below_charges`) and 409 `version_mismatch`.
+
+### Suspend when idle (contracts §20.6)
+
+- `workspace.suspendWhenIdle({ afterSeconds, idempotencyKey? })` and `cloud.workspaces.suspendWhenIdle(id, {
+  afterSeconds })` (POST /v1/workspaces/{id}/suspend-when-idle): the workspace is suspended once it has been idle for
+  `afterSeconds` (30..3600), counted from the later of its last work and the request. Meant for the end of an agent
+  turn. A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.
+  Resolves with `{ suspendRequest, operation, workspace }`: `operation` is the suspend already in progress, if any
+  (then nothing is recorded).
+- `workspace.cancelSuspendWhenIdle()` and `cloud.workspaces.cancelSuspendWhenIdle(id)` (DELETE, idempotent).
+- `workspace.suspendRequest`: the pending request from the view's `idle.suspend_request`, or null.
+- Tool-call capture writes recorded before `suspendWhenIdle` land first, as for `suspend`, since a later write would
+  count as the next turn and cancel the request.
+- Types `SuspendRequest`, `SuspendWhenIdleOptions`, `SuspendWhenIdleResult`, `SuspendWhenIdleResponse`.
+
+## 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.