driftstack-sdk 0.3.0__tar.gz → 0.4.0__tar.gz

driftstack_sdk-0.4.0/CHANGELOG.md

@@ -0,0 +1,1184 @@
+# Changelog
+
+All notable changes to the `driftstack` Python SDK. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
+follows [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-03
+
+**Breaking: the SDK now covers what a program needs to run Driftstack, and
+nothing a person manages in the dashboard.** Sign-up and sign-in, two-factor,
+API keys, team members and invites, billing, checkout and crypto orders,
+account and notification settings, the audit log and legal acceptance are
+done in the [Driftstack dashboard](https://app.driftstack.io). Their methods
+are removed, and their endpoints are no longer in the API reference. Sessions,
+agent sessions, profiles and snapshots, saved proxies, archetypes, recipes,
+webhooks, usage and rate limits stay in the SDK. Every change below applies
+to both `Driftstack` and `AsyncDriftstack`.
+
+0.4.0 also runs every session through a proxy of yours:
+`agent_sessions.create()`, and on hosted Driftstack `sessions.create()` and
+`profiles.launch()`, are refused when there is no proxy to use. See
+**Changed — BREAKING** below.
+
+### Removed
+
+- **Resources:** `api_keys`, `auth`, `mfa`, `team`, `billing`,
+  `crypto_orders`, `audit_log`, `email_preferences` and `legal`, with the
+  `ApiKeyList`, `Team*` and `AcceptInviteResponse` exports.
+- **`account`:** `update_me`, `upload_avatar`, `clear_avatar`,
+  `list_web_sessions`, `revoke_web_session`, `revoke_all_other_web_sessions`,
+  `get_bundled_llm_settings`, `update_bundled_llm_settings` and the four
+  `…_byok_anthropic_key` methods. The monthly AI cap and a stored Anthropic
+  key are set in dashboard Settings; a key for one agent session is still
+  passed to `agent_sessions.create`.
+- **`agent_sessions`:** `set_mode`, `takeover`, `handback` and
+  `send_input_event`. They control a session a person drives in the
+  Driftstack desktop app, which is not part of this API. `livekit_token`
+  stays: live video is part of the public API.
+- **`profiles.transfer`:** giving a profile to another account is not part of
+  the public API. To hand one over, `profiles.export` it and have the other
+  account `profiles.import_` the file.
+- **Generated models** (`driftstack._generated.models`) for the endpoints
+  above and for Driftstack's own staff and internal endpoints, which the
+  committed `openapi.json` no longer describes. Import the public models from
+  `driftstack`; a model you imported from `_generated` for one of these
+  endpoints is gone.
+- **`examples/billing_flow.py` and `examples/crypto_checkout.py`.**
+- **`CANONICAL_MODIFIER_NAMES` and `CanonicalModifier`** (in
+  `driftstack.resources.agent_sessions`): the modifier vocabulary of the
+  desktop app's live-input channel, which is not part of this API.
+- **`PublicArchetype.canvas_family`**, which the API reference leaves out. A
+  response that still carries it parses; the field is ignored.
+- **`pair_mode_state` on the generated `AgentSession` model**, with the
+  `PairModeState` model. It describes the desktop app's takeover state, which
+  is not part of this API. A response that still carries it parses; the field
+  is ignored. The dicts the `agent_sessions` methods return still have the
+  key while the server sends it.
+- **`measured_from` on the generated `AccountProxyTestResult1`,
+  `AccountProxyTestResult2` and `AccountProxyTestResult3` models, and
+  `node_id` on `AccountProxyTestResult3`** (the result of a proxy test). Read
+  `measured_by`, which the same models have carried since 0.3.0, for where a
+  test ran. A response that still carries either field parses; the field is
+  ignored.
+
+### Changed — BREAKING
+
+- **`agent_sessions.create()` needs a proxy: `proxy_id` in its body.** Every
+  agent session now runs through a proxy you chose, so a create without
+  `proxy_id` (or with `proxy_id` set to `None` or `""`) is refused with the
+  new **`ProxyRequiredError`** (HTTP 422, type
+  `https://errors.driftstack.dev/proxy-required`, `code` `"proxy_required"`)
+  before anything is created — no session, no charge, nothing recorded under
+  your `idempotency_key` — unless its `profile_id` names a profile bound to a
+  proxy (`proxy_choice` `"bound"`), which then runs through that proxy. A
+  profile whose proxy was deleted (`"detached"`) is a 409 (`ConflictError`,
+  `err.problem["code"]` `"proxy_detached"`) instead. `body` no longer has a
+  default, so `create()` with no argument is a `TypeError`; the body is a
+  plain `dict`, so a missing key is caught only by the server: set
+  `proxy_id` on every create.
+  **What to do:** pass the id of one of your saved proxies:
+  `client.agent_sessions.create({"mode": "ai", "proxy_id": "b1d7…"})`.
+  `client.egress.list_proxies()` lists the ids you have and
+  `client.egress.create_proxy(...)` saves a new one; both need a key with the
+  `account_owner` scope. A proxy you add in the desktop app is saved to your
+  account the first time the app tests it or launches through it. In the
+  published OpenAPI document (`openapi.json`) the request body is now
+  required; `proxy_id` stays optional in its schema, and its description
+  says when it may be left out.
+- **`sessions.create()` and `profiles.launch()`** (`POST /v1/sessions`,
+  `POST /v1/profiles/{id}/launch`) **take `proxy_id`** in their body: the id
+  of one of your saved proxies; the session's traffic goes out through it.
+  Hosted Driftstack runs every session through a proxy of yours, so a create
+  without one is refused with the same `ProxyRequiredError` (from a profile
+  bound to a proxy, that proxy is used when `proxy_id` is omitted). The key
+  is optional in `CreateSessionRequest` and in a plain `dict` body, so a
+  missing one is caught only by the server: pass it on every create. A
+  session started with a `proxy_id` cannot run the
+  step-by-step operations (navigate, interact, capture, ...) yet: they answer
+  503 and leave the session ready. It ends, and reads `destroyed`, when its
+  agent session is closed or it stops on its own (30 minutes without
+  activity, or its time limit).
+
+### Added
+
+- **`account.whoami()`** — `GET /v1/whoami`: the `account_id`, `api_key_id`,
+  `tier` and `scopes` behind the key. It needs no scope, so a read-only key
+  can call it.
+- **`ready` and `ready_at` on an agent session.** `status` reads `"active"`
+  from the moment a session is created; `ready` turns `True` only once the
+  session reports that its browser has finished starting, and
+  `ready_at` says when. Wait for `ready` before sending the first message. A
+  session on a VPN can take longer to become ready. A session that closes while
+  `ready` is still `False` failed to start; `closed_reason` says why. `None` from
+  an older server, which does not hold messages either: treat `None` as ready.
+- **`SessionNotReadyError`** (HTTP 409, type
+  `https://errors.driftstack.dev/session-not-ready`, a `ConflictError`
+  subclass). A message sent before the session is ready waits for it, for up to
+  45 seconds on the streamed response the SDK uses; if it is still starting
+  then, nothing ran and the message is
+  refused with this error. `is_retryable()` returns `True`;
+  `retry_after_seconds` says how long to wait, and the same `idempotency_key` is
+  safe to reuse.
+- **Two more agent-session models: `"claude-fable-5-1"` (Claude Fable 5.1) and
+  `"claude-opus-5-5"` (Claude Opus 5.5).** Both run only on your own Anthropic
+  key, like every Opus model: when a session would run on Driftstack's included
+  AI, creating it (and every message) raises a 403 `ForbiddenError` whose
+  `requires_own_key` is true. The default model is unchanged
+  (`"claude-sonnet-5"`).
+- **The generated `AgentIntent` model lists every step kind the API
+  returns.** It gains `{"kind": "back"}`, `{"kind": "extract"}` with optional
+  `selector`, `body` and `frame` (the text of one element, or of the whole
+  page) and `{"kind": "tap_at", "x": ..., "y": ...}` (a tap at a point, in
+  viewport pixels from the top-left corner), and so do the step models of
+  `intents`, of each result's `intent` and of a recipe's `intent_log`. The
+  API already returned these steps; validating one against the 0.3.0 models
+  failed. The dicts the SDK returns are unchanged.
+- **`frame` on a read step.** A step with `"kind": "capture"` and
+  `"capture": "dom_snapshot"`, and one with `"kind": "extract"` and
+  `"body": True`, can now carry `"frame"`: a list of ints naming the embedded
+  document (an iframe) the step read instead of the page, as a path of
+  positions — the frame's position among the page's frames, then its position
+  inside that frame for a nested one, outermost first (`[0]`, `[0, 1]`). Each
+  position is 0 to 512, and a path is 1 to 8 levels deep. Frames are numbered
+  by the session's own frame list, in the order the browser created them, which
+  is not always the order of the iframe tags in the markup. `"frame"` also
+  appears on an `interact` with `"action": "type"`: the step typed into an
+  element inside that frame. It never appears on a screenshot, a PDF, an
+  `extract` by selector or a step that taps, scrolls, presses or waits, so no
+  step can name a frame to tap into. A `tap_at` step taps a point on the
+  screen, and that point can be inside a frame. No `"frame"` key means the step read
+  the page itself. You see it in the steps a turn reports (`intents`, and each
+  result's `intent`) and in a recipe's `intent_log`; the generated models
+  (`driftstack._generated.models`) carry it as `frame: list[FrameItem] | None`.
+- **`account.list_credentials()`** — `GET /v1/account/me/credentials`: the
+  `handle`, `label`, `sites`, `include_subdomains` and `created_at` of each
+  saved credential on the account, never the value. Write a handle into an
+  agent task as `{{credential:<handle>}}`, as the text of a type step. Each
+  credential is locked to its `sites`: a step types it only on an `https://`
+  page on one of them, and is refused elsewhere with `diagnosis.category`
+  `"credential_site_not_allowed"` (now one of the listed categories). Saving
+  and deleting a credential are done in the dashboard. With
+  `effective_account` set, a team member of either role lists the account
+  owner's saved credentials — the ones agent tasks in that workspace use — as
+  the same fields, never a value; a workspace you are not a member of
+  answers 403.
+- **`"session_unresponsive"`** joins the `diagnosis.category` values and the
+  `AgentNoticeReason` values. The session stopped answering automated steps (the live view may still show the page): it had already failed to answer one, and a quick check sent just before the next step got no answer either, so that step was not sent. The step fails
+  with `diagnosis = {"category": "session_unresponsive", "retryable": False}` and
+  the turn stops there with `notice_reason == "session_unresponsive"`; a turn
+  that hit it before planning anything answers `kind == "refuse"` with the
+  same `notice_reason == "session_unresponsive"` (a `refuse` carries
+  `notice_reason` only when the refusal was not the agent's choice). **What to
+  do:** end the session and launch a new one — sending `"continue"` will not
+  help. If the session answers the check again, steps run as normal. Both are
+  open strings, so an older install still parses the value.
+- **Five `notice_reason` values for a paused session** (`AgentNoticeReason`).
+  A step was refused because a verification check appeared, and nothing
+  carries on until the session is resumed (`agent_sessions.resume()`, or
+  Resume in the live view). `"challenge_solver_pending"`: the check was
+  handed to your configured solver; wait for the page to clear, then resume
+  and send `"continue"`. `"challenge_customer_handoff"`: the check needs a
+  person, because no solver is configured or it cannot solve this kind;
+  solve it in the live view, resume, then send `"continue"`.
+  `"verification_email"` and `"verification_sms"`: the site sent a code by
+  email or by text message; enter it in the live view, resume, then send
+  `"continue"`. `"unexplained_pause"`: the session is paused and no check is
+  showing, or the reason could not be confirmed; open the live view, resume,
+  then send `"continue"`. No solver provider is offered yet, so today every
+  such check is handed to you (`"challenge_customer_handoff"`).
+  `AgentNoticeReason` is an open union (`Literal[...] | str`), so an older
+  install still parses these values.
+- **`warning` on a successful step result** — present on a `results` entry of
+  kind `"success"` when there is something worth knowing about the step, and
+  absent otherwise. `"http_error_status"`: a navigation
+  reached the site and the site answered with an HTTP status of 400 or above,
+  carried in `status`. The step still succeeded — the page that loaded may be
+  an error page, a page asking to sign in or to complete a verification step,
+  or the whole page served under that status — and its `summary` says what the
+  site answered. `"effect_unknown"`: a tap whose effect on the page could not
+  be checked (see **Changed**). The generated models list the known kinds and
+  accept any other string: treat a kind you do not recognise as a note and
+  read `summary`.
+- **`AgentSession.proxy_id`** (optional, `str | None`, on the generated
+  models): the id of the account proxy (`GET /v1/account/me/proxies`) the
+  session's traffic goes out through. That is the `proxy_id` the create named
+  (when it named none, the proxy its profile is bound to), or the one a
+  successful `POST /v1/agent-sessions/{id}/egress` moved it to.
+  It is set from the create's response onwards and does not follow a
+  profile's proxy setting. Every agent session created since proxy_id became required has one;
+  `None` means an older session created without a proxy of yours, and also
+  that an older server did not send the field. Use
+  `"proxy_id" in model.model_fields_set` to tell the two apart.
+- **`profile_id` on an agent session** (optional, `str | None`, on the
+  generated models): the saved profile the session runs (`prof_…`), or `None`
+  for a session started without one. Absent from older servers.
+- **`upload_max_file_bytes` on an agent session** (optional, `int | None`, on
+  the generated models): the largest file, in bytes, that one upload to the
+  session (`POST /v1/agent-sessions/{id}/files`) can carry right now. Each
+  session takes a file up to its own size, so this is often smaller than the
+  64 MiB per-file maximum, and it can change while the session runs.
+  `agent_sessions.get()` returns it while the session is running and has
+  reported it; a missing key means not known, not "no limit". A larger file
+  is refused with a 413 (`payload-too-large`) and nothing is sent.
+- **`ProxyRequiredError`** — see **Changed — BREAKING** above. `err.code` is
+  `"proxy_required"`, and the message is a sentence you can show your user.
+  `is_retryable()` is False: the same request is refused the same way.
+- **`DashboardOnlyError`** (403, `https://errors.driftstack.dev/dashboard-only`):
+  raised when a request made with an API key asks for something that is done
+  in the dashboard — checkout and the billing portal, creating, editing or
+  cancelling a crypto order, creating an API key, accepting a team invite or
+  the legal terms, and signing dashboard sessions out. It subclasses
+  `ForbiddenError`.
+- **`DeviceUnavailableError`** (409, problem type `device-unavailable`,
+  subclasses `ConflictError`): a create on a profile whose device is not
+  offered right now — on hold until its evidence exists, or still in
+  development — is refused before any session exists, so nothing starts and no
+  concurrent-session slot is used. `err.archetype` is the profile's device id,
+  `err.held_reason` the reason for the hold in one plain sentence (`None` when
+  there is none), and the message a sentence you can show.
+- **`AiCreditsExhaustedError`** (HTTP 402, type
+  `https://errors.driftstack.dev/ai-credits-exhausted`): an AI turn could not
+  run on your account's AI credits, and nothing ran. `reason` is `"balance"`
+  (the credits your plan includes are used up; `available_credits`,
+  `required_credits` and, when known, `resets_at`), `"debt"` (AI is paused on
+  the account; `debt_reason`) or `"task_too_large"` (shorten the request or
+  start a new chat). `reason` is also `"balance"` when a paid plan has ended
+  and the account has fallen back to the trial plan, which has no AI: no
+  credit figures are sent, the message reads _Your plan has ended. Choose a
+  plan to use Driftstack’s AI again._, and only choosing a plan lets the
+  turn run. Otherwise, on a plan that takes a key of your own, that key
+  still runs the turn. Not retryable as-is.
+- **`TrialEndedError`** (HTTP 402, type
+  `https://errors.driftstack.dev/trial-ended`): your free trial has ended, or a
+  paid plan has, so a new session is refused until you choose a plan. When a
+  paid plan ended, `err.problem["code"]` is `"plan_ended"` and the message
+  says the plan ended; after a trial the problem has no `code`. Not retryable
+  as-is. Reads keep working; everything else runs under the trial's limits
+  (see **The trial's limits** below). That includes an account whose paid
+  plan ended, which is moved to the trial: its AI messages raise the
+  plan-ended `AiCreditsExhaustedError` above; it keeps one saved profile, so
+  `profiles.create()`, `clone()`, `import_()` and
+  `profile_snapshots.restore()` raise a 429 `QuotaExceededError`
+  (`tier-limit`) while it holds one or more; and creating or updating an
+  OpenVPN or WireGuard proxy raises a 403 (`ForbiddenError`). An account
+  whose trial ended without a plan being chosen is sent an email 30 days
+  later, and may be closed 7 days after that email, which revokes its API
+  keys; an account whose paid plan ended is not closed this way.
+- **`PayloadTooLargeError`** (HTTP 413, type
+  `https://errors.driftstack.dev/payload-too-large`): the request is too
+  large for where it has to go, and nothing was sent there — a body over the
+  endpoint's size limit, or a file or cookie jar larger than the session takes
+  at once. When the session is the limit, `limit_bytes` is the most that fits
+  and `size_bytes` what was sent; both are `None` otherwise. A 413 used to
+  arrive as a plain `BadRequestError`, so this one subclasses
+  `BadRequestError` and an existing `except BadRequestError` still catches it.
+- **`UpgradeRequiredError`** (HTTP 426, type
+  `https://errors.driftstack.dev/upgrade-required`): a write or a launch made
+  with a Driftstack desktop app sign-in whose app build is older than the
+  server's minimum, or that sent no build. Reads still work. It is never
+  raised for an API key; SDK code sees it only when it runs on a credential
+  the desktop app provisioned. `code` is `"desktop_update_required"` and
+  `min_desktop_build` names the build to update to.
+- **The 2026-09 plans** in the generated models' `tier` values: `"trial"`
+  (the 7-day free trial a new account starts on), `"starter_v3"`, `"pro_v3"`,
+  `"team_v3"` and `"scale_v3"`. They are available from 2026-09-29:
+  `"starter_v3"`, `"pro_v3"` and `"team_v3"` can be bought in the dashboard,
+  and Scale (`"scale_v3"`) is sold by talking to us. The earlier plans stay
+  valid for the accounts that hold them. No new id reuses an old one.
+  `usage.current_period()` now works for an account on one of these plans;
+  0.3.0 raised `TransportError` there, because its `UsagePeriodSummary.tier`
+  did not list them.
+- **`trial_ends_at` and `trial_ended` on the account (`account.me()`).** When
+  the account's free trial ends (or ended), `None` when it is not on a trial;
+  and whether it has ended. An account whose trial has ended can still sign in
+  and read everything, but starting a session is refused until it subscribes.
+- **`profile_trash_count`, `proxy_cap` and `proxy_count` on the account
+  (`account.me()`).** `profile_trash_count` is the number of profiles in the
+  trash: they count against `profile_cap` together with `profile_count`, so
+  the two add up to what a new profile is checked against. `proxy_cap` is
+  the number of saved proxies the account's plan keeps (`None` when
+  unmetered), and `proxy_count` the saved proxies of the account itself.
+- **The trial's limits (`"trial"`).** A trial account runs one session at a
+  time and keeps one saved profile. Its sessions run as the iPhone 13 or
+  iPhone 13 mini only: `profiles.create()` with any other device raises a
+  403 (`ForbiddenError`), and a profile set up as another device cannot
+  launch (`"device_not_on_plan"`, see **Changed**). The trial has no AI
+  agent, on any funding source, a key of your own included:
+  `agent_sessions.create()` with `"mode"` `"ai"` (the default) or `"pair"`
+  raises a 403 `ForbiddenError` whose `err.problem` carries
+  `"ai_not_on_plan": True` and `"tier"`, and no session starts;
+  `"mode": "manual"` is allowed. `agent_sessions.message()` raises too, on
+  every turn (see **A plan with no AI runs no AI turn** under **Changed**).
+  The trial has no VPN proxies: `egress.create_proxy()` of an OpenVPN or
+  WireGuard proxy, and `update_proxy()` of one that stays OpenVPN or
+  WireGuard, raise a 403 (`ForbiddenError`), and so do
+  `agent_sessions.create()`, `sessions.create()` and `profiles.launch()`
+  through one saved earlier (`err.problem["feature"]` is `"vpnEgress"`),
+  before any session starts. SOCKS5 proxies work. A trial session runs for
+  at most 20 minutes, and the trial includes 120 minutes of session time in
+  total, counted from the day it started across every session the account
+  runs. A new session gets 20 minutes or what is left of the 120, whichever
+  is shorter. An agent session closed at its 20 minutes has `closed_reason`
+  `"trial_session_limit"`, and one still running when the 120 minutes run
+  out has `"trial_time_used"`; a session from `sessions.create()` or
+  `profiles.launch()` is ended the same way and reads `destroyed`. Once the
+  120 minutes are used, `agent_sessions.create()`, `sessions.create()` and
+  `profiles.launch()` raise a 429 `QuotaExceededError` (`tier-limit`) whose
+  `err.problem["code"]` is `"trial_session_time_used"` (`err.limit` is 120
+  and `err.record_type` is `"session_minutes"`), and no session starts.
+  `usage.current_period().quotas.session_minute` is 120 on the trial, the
+  allowance for the whole trial; it is `None` on every other plan, as it was
+  on every plan before. `totals.session_minute` still counts the calendar
+  month.
+- **`capability_report.egress_state` can read `"default_connection_down"`**
+  (the generated `CapabilityReport` model's `Literal` lists it) — only on a
+  session created before proxy_id became required, without a proxy of its own: the connection
+  Driftstack provided then stopped carrying traffic while the session ran. It
+  was on our side. No session created since reports it, because every one
+  runs through a proxy of yours. `"dead_proxy"` keeps
+  its meaning — your own proxy stopped. On `GET /v1/sessions/{id}` the same
+  fact arrives as the `default_connection_down` code in
+  `egress_capabilities.warnings`, and for that session a connection without
+  UDP reads `quic_unavailable` and a failed check that its traffic left the
+  right way reads `safeguard_failed` — never `udp_unsupported_by_proxy` or
+  `safeguard_failed:proxy_egress_verification`, which name a proxy it does
+  not have.
+- **Error code `"default_egress_unavailable"`** in an agent session's
+  `error_event.code`, and as its `closed_reason` — only on a session created
+  before proxy_id became required, without a proxy of its own, whose connection (the one
+  Driftstack provided then) failed. It arrives with `customer_actionable`
+  `False` — ours to fix. No session created since can report it. `code` stays a `str`, so nothing to change
+  unless you branch on it.
+- **`"agent_sessions:live"`** can appear as a `bucket_key` in
+  `account.rate_limits()`: the bucket for what a live window reads and
+  controls on one agent session, kept apart so list calls on `"global"`
+  cannot slow a session you are watching. `agent_sessions.get()`, `stop()`
+  and `livekit_token()` now count against it instead of `"global"`; listing
+  agent sessions stays on `"global"`. It grows with the number of sessions
+  your plan runs at once. The response is a plain `dict`, so no type changes;
+  code that handles every bucket key by name has this one to handle.
+- **`egress.create_proxy(body, idempotency_key=...)`.** The key is sent as
+  the `Idempotency-Key` header: a retry with the same key returns the proxy
+  already created under it — the same id, one row — so a create lost to a
+  timeout is safe to repeat. In a team workspace (`effective_account`) the
+  proxy is created on the owner's account under the owner's plan, and the
+  caller needs the admin role there.
+- **More on each saved proxy** (keys of what `egress.list_proxies()`,
+  `create_proxy()` and `update_proxy()` return, and fields of the generated
+  `AccountProxyMetadata` model): `revision`, which moves on every edit you
+  make and never on a background reading; `config`, the part of a VPN proxy's
+  configuration that is not secret (the WireGuard `peer_public_key`,
+  `endpoint`, `allowed_ips`, `address` and `dns`, or the OpenVPN `username`;
+  `None` on a SOCKS5 or HTTP proxy; the generated `Config` model), while the
+  private key, the pre-shared key and the `.ovpn` file stay write-only;
+  `has_preshared_key`; and `full_check_ok` and `full_check_at`, the outcome
+  of the last full test that ran where sessions run (`measured_by` `"phone"`)
+  and when it ran, `None` when no such test has run since the proxy's
+  address, scheme or credentials last changed. The list also carries `cap`
+  (the workspace's saved-proxy allowance, `None` when unmetered) and `count`.
+  An older server does not send them.
+- **A team member's rows in `egress.list_proxies()`.** A team member listing
+  a team's proxies (`effective_account` set to the team owner's account)
+  gets a narrow row for each: `member_view` (`True`), `id`, `label`,
+  `scheme`, `country`, `status`, `revision`, `created_at` and `updated_at` —
+  never the address, the username or whether a password is stored (the
+  generated `AccountProxyMemberView`; `AccountProxyList.data` holds either
+  kind). An admin of the team, and any call without `effective_account`,
+  gets full rows (before, `effective_account` was ignored here: see **Saved
+  proxies follow the team workspace** under **Changed**). Check for
+  `"member_view"` before reading `host`, `port` or `has_password` from a row.
+  `status` is `"ok"` or `"failing"` from the last full check Driftstack ran
+  through the proxy, or `"unknown"` when none has run since the proxy last
+  changed, and `country` is where it was last seen exiting, or `None`.
+- **`expected_revision` on `egress.update_proxy()`.** Send the `revision` you
+  last read, and an update to a proxy that another computer changed first is
+  refused with a 409 `ConflictError` (`err.problem["code"]` is
+  `"stale_revision"`, with `err.problem["current_revision"]`) and nothing
+  changes. Omit it to write unconditionally, as before.
+- **A profile's proxy and launch settings** (keys of the profile dict that
+  `profiles.get()`, `list()`, `create()`, `update()` and every other call
+  that returns a profile give back). `default_proxy_id` is the saved proxy
+  the profile launches through, or `None`; set it in the body of `create()`
+  or `update()` (`None` unsets it). A proxy that is not one of yours is a
+  404, and an `http` proxy, which cannot carry a session, is a 400.
+  `proxy_choice` is set by the server: `"unset"` (never chosen: a launch
+  without a `proxy_id` is refused, as before), `"bound"` (a launch of the
+  profile without a `proxy_id`, by `profiles.launch()`, or by
+  `sessions.create()` or `agent_sessions.create()` with its `profile_id`,
+  uses `default_proxy_id`) or
+  `"detached"` (its proxy was deleted: a launch without a `proxy_id` is a 409
+  until you choose one, and it is never given another proxy on its own).
+  `update()` takes `{"proxy_choice": "detached"}` to mark a profile detached
+  yourself; beside a non-`None` `default_proxy_id` that is a 400.
+  `geolocation` (`{"latitude", "longitude", "accuracy"?}` or `None`) and
+  `stop_on_exit_ip_change`, set on `create()` or `update()`, apply to a
+  session created with the profile unless the create sets its own. `clone()`
+  copies these settings; `import_()` and `profile_snapshots.restore()` start
+  the new profile `"unset"` with no location. An older server does not send
+  them.
+- **`notes` on a profile** (`str | None`): free-text notes kept with the
+  profile, plain text of at most 16 KiB of UTF-8, `None` until something is
+  written. Set them with `update(profile_id, {"notes": ...})` (`None` clears
+  them). They travel with `clone()` and in what `profiles.export()` returns
+  (`profile["notes"]`), which `profiles.import_()` reads back; a file
+  exported before notes existed still imports, with `None`.
+- **`revision` on a profile, and `expected_revision` in the body of
+  `profiles.update()`.** `revision` moves on every edit (a launch, or a
+  session saving its state back, does not move it). Send it back as
+  `expected_revision`, and an update to a profile another computer changed
+  first is refused with a 409 `ConflictError` (`err.problem["code"]` is
+  `"stale_revision"`, with `err.problem["current_revision"]`) and nothing
+  changes. Omit it to write unconditionally, as before.
+- **`pages_withheld` in what `profiles.activity()` returns.** The pages and
+  session ids come from agent-session records, so they are shown only to a
+  caller who could read those sessions: the key needs the `read:sessions`
+  scope as well, and in a teammate's workspace (`effective_account`) the
+  caller must be an admin there. Anyone else gets `data` empty and
+  `pages_withheld` `True`, with `sessions_scanned` and `truncated` as before.
+  An older server does not send it.
+- **`client.support`**: your Help conversations with Driftstack, the same
+  ones the desktop app and the dashboard show. `list(cursor=..., limit=...)`
+  returns a `SupportConversationList` (`data` newest first, `next_cursor`,
+  `unread_count`, `open_count`); `create(body, ...)`, with the keyword
+  arguments `subject`, `topic_hint`, `context` and `idempotency_key`, opens
+  one with its first message and returns a `SupportConversationMessage` (a
+  retry with the same key returns the original conversation instead of
+  opening a second); `get(id)` returns a `SupportConversationDetail` with its
+  messages; `add_message(id, body)`
+  sends a follow-up and reopens a closed conversation; `mark_read(id)` and
+  `close(id)` return the `SupportConversation`. The models
+  (`SupportConversation`, `SupportMessage`, `SupportConversationList`,
+  `SupportConversationDetail`, `SupportConversationMessage`) are exported
+  from `driftstack`. A person reads and approves every reply; replies appear
+  here, and a copy goes to the account's email address. Conversations
+  started by email are not listed. An account can have 3 open
+  conversations, start at most one every 10 seconds and 5 an hour, and send
+  30 messages in 24 hours; past a limit, `create()` and `add_message()`
+  raise a 429 `RateLimitError` whose `err.problem["reason"]` is
+  `"support_limit_reached"`, with `err.retry_after_seconds`. A `body` over
+  8,000 characters or a `subject` over 200 is a 400 (`ValidationError`).
+- **`os_fingerprint` and `exit_tcp_stack` on the generated `CapabilityReport`
+  model** (an agent session's `capability_report`). `os_fingerprint` is the
+  last reading Driftstack took of the operating system of the session's
+  proxy: `os`, `confidence`, `at` (when it was taken; it can be any age) and
+  how it was taken. `None` means not measured, never "no OS".
+  `exit_tcp_stack` (the generated `ExitTcpStack` model) says whether the
+  network stack of the session's proxy looks like an iPhone's, measured once
+  when the session starts: `"match"`, `"mismatch"` or `"unknown"` (read a
+  value you do not recognise as `"unknown"`), with `measured_at` and
+  `proxy_id`, the proxy it describes. A `"mismatch"` is a warning: nothing is
+  blocked and the session keeps running. `None` means it was not measured.
+
+### Changed
+
+- **A tap that changed nothing is a failed step, and a turn that stopped
+  because nothing was changing is not `ok`.** A tap the browser made and then
+  saw change nothing on the page now comes back as a `failure` with
+  `diagnosis["category"] == "no_effect"` (added to the generated `Diagnosis`
+  literals), not as a `success`; the agent looks at the page again and tries
+  something else. A tap where whether it changed anything could not be checked
+  is still a `success`, now with `warning == {"kind": "effect_unknown"}` (added
+  to the generated warning literals) and a summary that says so. A
+  `plan-executed` result with `notice_reason == "no_progress"` now always has
+  `ok` false. A `type` step the browser could type only part of is a `failure`.
+- **The AI agent does not leave your page for a website your message does
+  not name.** On a turn that starts on an open page, a plan that would
+  navigate to a site the message does not name — by its address or domain,
+  or by the site's name after a word such as _open_, _visit_ or _go to_ — or
+  step `back` off that page when the message does not ask to go back, is not
+  run. The agent plans once more, and if it would still leave, the turn
+  answers `kind` `"clarify"` with the `clarifying_question` _I stayed on the
+  page you’re on, because your message doesn’t name another website. Should
+  I work on this page, or which website should I open?_ (or _Which website
+  should I open? Please give its name or address._). A message that asks
+  the agent to choose sites itself ("visit a few popular websites", "search
+  the web"), or a turn that starts with no page open, still lets it go to
+  sites it picks, but never to Driftstack's own. Site names are recognised
+  in English; in another language, give the address. A task with no site,
+  sent to a session already on a page, now gets this question where the
+  agent used to choose a site: name the site in the message.
+- The transport-error scrub redacts `authorization` and every header whose
+  name ends in `-key` from the request an error chains, instead of a fixed
+  list of header names.
+- **`purpose`** on `Session`, `CreateSessionRequest` and
+  `CreateSessionResponse` is typed `Literal["production_customer"]`, the one
+  customer value and the default. The two validation values are for
+  Driftstack's own validation runs and are not part of the API reference,
+  and the server now refuses them: a create with any `"purpose"` other
+  than `"production_customer"` raises a 400 (`ValidationError`) that names only `"production_customer"`, where 0.3.0
+  created the session. A plain `dict` body that sends either value has to
+  drop it.
+- `sessions.search`, `sessions.login` and `agent_sessions.set_egress` stay,
+  marked **not available yet** in their docstrings: the server does not serve
+  them on any deployment today, and they are not in the API reference until it
+  does. The request and response models of `search` and `login` are kept by
+  hand, with the same fields; the request models no longer check selector
+  lengths or the `timeout_seconds` range themselves.
+- **`egress.update_proxy` refuses `"password": ""`** with a 400
+  (`BadRequestError`), and nothing changes. An empty string used to clear the
+  stored password, so a blank field in an editor removed a credential without
+  anyone asking; send `None` to clear it, and leave `password` out to keep
+  it.
+- **Recipes follow the team workspace.** With `effective_account` set to a
+  team owner's account, `recipes.create()`, `list()`, `iterate()`, `get()`
+  and `delete()` act in the owner's workspace and need the admin role there:
+  without it, each one, reads included, raises a 403 (`ForbiddenError`).
+  `create()` takes a session of the owner's, files the recipe under the
+  owner's account and counts it against the owner's plan; the other four
+  read and delete the owner's recipes. Before, `effective_account` was
+  ignored here: a recipe was filed under, and listed from, your own account
+  whichever workspace you worked in. `recipes.suggest()` is unchanged.
+  Without `effective_account`, `create()` takes only a session of your
+  own account, so saving a team owner's session from your own workspace is
+  now a 404; set `effective_account` to the owner instead. A recipe saved
+  before this change stays in the account it was filed in.
+- **A limit on recipes, and a session is saved once.** Each plan keeps up to
+  a set number of recipes (the API reference lists them); a save past it
+  raises a 429 `QuotaExceededError` (`err.record_type` `"recipe"`, with
+  `err.limit` and `err.current`). A session already saved as a recipe cannot
+  be saved again under another label or description: that is a 409
+  `ConflictError` with the saved recipe's id in `err.problem["recipe_id"]`.
+  Repeating the exact same save returns the recipe already saved instead of
+  storing a second copy.
+- **Saved proxies follow the team workspace.** With `effective_account` set
+  to a team owner's account, `egress.list_proxies()`, `create_proxy()`,
+  `update_proxy()`, `delete_proxy()` and `test_proxy()` act on the owner's
+  saved proxies, under the owner's plan. Any member of the team can list
+  them (a member who is not an admin gets the narrow rows described under
+  **Added**); `create_proxy()`, `update_proxy()`, `delete_proxy()` and
+  `test_proxy()` need the admin role there, and without it raise a 403
+  (`ForbiddenError`). Before, `effective_account` was ignored here: each of
+  these acted on your own account's proxies, so an admin who set it listed,
+  changed, deleted and tested their own proxies, not the owner's. Without
+  `effective_account` they act on your own account, as before.
+- **In a team workspace, a session can go out through the admin's own saved
+  proxy.** With `effective_account` set to a team owner's account,
+  `agent_sessions.create()`, `sessions.create()` and `profiles.launch()`
+  take a `proxy_id` saved on your own account as well as one the owner
+  saved. The proxy stays on your account: the owner cannot list it or
+  launch through it. Any other id raises a 404 (`NotFoundError`,
+  `err.problem["resource"]` `"proxy"`). Before, `agent_sessions.create()`
+  looked the id up only among the owner's proxies, so your own was a 404. A
+  member without the admin role gets a 403 (`ForbiddenError`); from
+  `agent_sessions.create()` its `err.problem["required_role"]` is `"admin"`,
+  and from the other two it carries no such key.
+- **The quick proxy check is limited on the Free plan.** On `"free"`,
+  `egress.test_proxy()` runs at most 5 times a day (UTC). Every further call
+  that day raises a 429 (`RateLimitError`) until midnight UTC, and a check
+  counts even when it could not finish. Other plans are not limited.
+- **More saved proxies on the earlier Team and Agency plans.**
+  `"team_manual"` keeps 50 saved proxies instead of 25, and `"agency_manual"`
+  200 instead of 50: the same number as the saved profiles each keeps.
+  `egress.create_proxy()` on those plans now succeeds up to the new number,
+  where it used to raise a 400 (`BadRequestError`, _Proxy limit reached_),
+  and the new `cap` in what `egress.list_proxies()` returns, and `proxy_cap`
+  on `account.me()`, report it.
+- **An account holding more than its plan keeps launches only what it used
+  most recently.** When an account holds more saved profiles than its plan
+  keeps (after moving to a smaller plan, for example), nothing is deleted,
+  but only the profiles it used most recently, as many as the plan keeps,
+  can launch. `agent_sessions.create()` with a `profile_id`,
+  `sessions.create()` with a `profile_id` and `profiles.launch()` on any
+  other profile raise a 429 `QuotaExceededError` (`tier-limit`) whose
+  `err.problem["code"]` is `"over_plan_limit"` (`err.record_type`
+  `"profile"`, `err.limit` the number the plan keeps and `err.current` the
+  number the account holds), and nothing starts. Profiles in the trash count
+  toward `err.current` until they are deleted permanently. Saved proxies
+  follow the same rule: a launch through a saved proxy that is not among the
+  ones used most recently, as many saved proxies as the plan keeps, raises
+  the same 429 with `err.record_type` `"proxy"`. To launch the others,
+  delete some or move to a plan that keeps more. A plan without a limit
+  never refuses.
+- **A profile whose device the plan does not include cannot launch.**
+  `agent_sessions.create()` with a `profile_id`, `sessions.create()` with a
+  `profile_id` and `profiles.launch()` raise a 403 `ForbiddenError` whose
+  `err.problem["code"]` is `"device_not_on_plan"` (with `"resource"`
+  `"profile"`, `"archetype"`, the profile's device id, and `"tier"`) when
+  the profile is set up as a device the account's plan does not include,
+  and nothing starts. The plans limited to the iPhone 13 and iPhone 13 mini,
+  the trial and Free, are the ones that refuse it. The profile is not
+  changed, and launches again on a plan that includes its device. Before, a
+  profile's device was checked only when the profile was made, so it could
+  go on launching as a device the plan no longer included.
+- **A plan with no AI runs no AI turn.** On Free and the trial,
+  `agent_sessions.message()` is refused on every turn before anything runs,
+  whichever key would have run it, a key of your own included: it raises a
+  403 `ForbiddenError` whose `err.problem` carries `"ai_not_on_plan": True`
+  and `"tier"`, or, for an account whose paid plan ended, the plan-ended 402
+  `AiCreditsExhaustedError` (see **Added**). The plan is read on each turn,
+  so an AI session created before the account moved to Free or the trial
+  stops at its next message. Before, whether the plan included the AI agent
+  was settled only when a session was created or its mode was changed, never
+  on a message.
+- **An agent session created without a profile runs as the iPhone 17**
+  (`iphone17_ios18_7_safari26_4`: iOS 18.7, Safari 26.4), the device a
+  profile created without an `archetype` gets, instead of the iPhone 16 Pro
+  (`iphone16pro_ios18_6_safari18_6`: iOS 18.6, Safari 18.6). That is the
+  device and browser the sites it visits see. On a plan that does not
+  include the iPhone 17, the session runs as the plan's own default device
+  instead: an iPhone 13 on the trial. To keep a session on one device,
+  create it with a `profile_id`.
+- **`agent_sessions.get_capture()` serves a screenshot only while its
+  session is active, and for at most 30 minutes.** On a session whose
+  `status` is not `"active"` (paused, or closed) it raises `NotFoundError`
+  (404). Each screenshot also expires 30 minutes after it was taken, even
+  while the session keeps taking more. Before, a screenshot could be removed
+  only once 30 minutes passed without a new one in that session, and it
+  could still be fetched after its session ended. At most the 20 most recent
+  per session are kept, as before, so fetch one as soon as its turn ends.
+- **A paused webhook endpoint holds its deliveries, and counts toward the
+  limit.** After `webhooks.update(webhook_id, {"active": False})`, the
+  endpoint's deliveries are not attempted, not dead-lettered and not counted
+  as failures, and events raised while it is paused are queued for it;
+  `update(webhook_id, {"active": True})` resumes it and they are delivered.
+  Before, an event raised during a pause never reached the endpoint. The
+  limit of 10 endpoints an account can have now counts paused ones:
+  `webhooks.create()` on an account that has 10, some of them paused, raises
+  a 409 (`ConflictError`) where it used to succeed, and resuming an endpoint
+  while the account's other endpoints number 10 is a 409 that leaves it
+  paused. Delete an endpoint to make room.
+- **A second `webhooks.rotate_secret()` within the grace window succeeds.**
+  It replaces only the new secret: the original keeps working until its
+  `grace_expires_at`, which the second rotation does not move (its response
+  carries the same time). It used to raise a 409 until the first rotation's
+  grace window ended.
+- **`webhooks.replay_delivery()` on a delivery that is being attempted right
+  now** (`status` `"in_flight"`) raises a 409 (`ConflictError`) instead of a
+  404, and nothing changes. Check its status again in a few minutes, and
+  replay it if it was not delivered.
+- **Eight devices are no longer offered.** `archetypes.list()` no longer
+  returns `iphone16_ios18_6_safari26_0`, `iphone16_ios18_7_safari26_3`,
+  `iphone16pro_ios18_6_safari26_0`, `iphone16pro_ios18_6_safari26_3`,
+  `iphone16pro_ios18_7_safari26_3`, `iphone16promax_ios18_6_safari26_0` and
+  `iphone16promax_ios18_7_safari26_3`, now on hold until their canvas parity
+  is shown, or `iphone17promax_ios18_7_safari26_0_1`, now in development. A
+  session on a profile set to one of them is refused with
+  `DeviceUnavailableError` before anything starts.
+- **Generated model names moved.** The generator numbers models that share a
+  name (`Intent27`, `Session1`, `CapabilityReport1`, …) in the order the API
+  reference lists them, and this release's reference has more of them, so a
+  numbered name can be a different model than in 0.3.0. `OsFingerprint` is
+  now the reading on an agent session's `capability_report`; a saved proxy's
+  is `OsFingerprint1`. Import a generated model by a name without a number
+  where there is one, and do not rely on a numbered name staying the same
+  between releases.
+- **The generated problem models** (`Problem` and the `Agent…Problem`
+  models) keep members they do not declare (`extra="allow"`) instead of
+  dropping them, and `AgentMessageConflictProblem` declares `code`,
+  `retryable` and `retry_after_seconds`, the fields of the 409 a message gets
+  while the session is not ready. The errors the client raises read the
+  problem document directly, so they are unchanged by this.
+
+### Deprecated
+
+- **`egress.attach_to_session` and `egress.get_session_proxy`.** The server
+  retired `/v1/sessions/:id/proxy`: both answer 410 (`FeatureUnavailableError`,
+  `code: "endpoint_retired"`) on every deployment. Choose the proxy when you
+  create the session, with `proxy_id`. Each call emits a `DeprecationWarning`
+  naming the replacement.
+- **`EmailAlreadyRegisteredError`, `InvalidCredentialsError`,
+  `InvalidAuthTokenError`, `EmailNotVerifiedError`, `MfaStepUpRequiredError`
+  and `LegalAcceptanceRequiredError`.** Only dashboard sign-in and dashboard
+  actions raise them, so a program using an API key does not receive them.
+  They stay so code that catches them keeps working.
+- **`account.me()`** — the dashboard's profile read, not part of the public
+  API. Use `account.whoami()`. It keeps working until a future minor release,
+  and its first call in a process emits a `DeprecationWarning`.
+
+### Fixed
+
+- **`webhooks.list_deliveries()` and `iterate_deliveries()` no longer skip
+  deliveries at a page break.** A delivery created in the same millisecond
+  as the last one on a page was left off every page. The cursor now carries
+  the full time, and a cursor from an earlier call still works.
+- **A dead-lettered webhook delivery counts every attempt.** A delivery that
+  used all 6 attempts reached `status` `"dlq"` with `attempts` 5; it now
+  reads 6. Deliveries dead-lettered before this release still read one
+  fewer. Its `last_response_excerpt` is now the final attempt's response
+  body (`None` when that attempt got no response), to match
+  `last_response_status`; before, it kept an earlier attempt's body.
+- **A turn refused before the AI model was called costs nothing.** A turn
+  on Driftstack's included AI that was refused before the model saw it (the
+  usage-policy check refused the task, or the session's token budget was
+  spent) reported `cost_usd_cents` 10 in its `usage` and counted 10¢
+  against the month's included-AI budget. It now reports 0 and counts
+  nothing.
+- **Two `egress.test_proxy()` readings were wrong.** A SOCKS5 proxy that
+  accepts the tunnel and closes it at once could fail only after about 12
+  seconds, with the `reason` for a slow proxy (_The proxy was too slow to
+  respond…_). It now fails at once with _The proxy connected but could not
+  reach the internet. Check with your proxy provider._, and a launch through
+  it raises `ProxyValidationFailedError` with `reason` `"egress_blocked"`
+  instead of `"timeout"`. A test now records `udp_probe` `True` on a SOCKS5
+  proxy only when traffic went both ways over UDP through the proxy, and
+  records nothing otherwise. Before, it recorded the answer of Driftstack's
+  own side, which accepts UDP before your proxy is contacted, so a proxy
+  that refuses or drops UDP read `True`. Every SOCKS5 `udp_probe` recorded
+  earlier was cleared, so it reads `None` until a test records a new one.
+
+### Security
+
+- **Webhook changes in a team workspace need the `account_owner` scope.**
+  With `effective_account` set to a team owner's account,
+  `webhooks.create()`, `update()`, `delete()`, `rotate_secret()`,
+  `send_test()` and `replay_delivery()` need a key with the `account_owner`
+  scope as well as the admin role there, as they always did on your own
+  account; a key without it raises a 403 (`ForbiddenError`). Before, the
+  scope was not checked on a team owner's endpoints, so a team admin's key
+  with a narrower scope could create an endpoint on the owner, and receive
+  its secret and the owner's events, or rotate or delete the owner's
+  endpoints.
+- **`egress.update_proxy` needs `password` when the address changes.** A body
+  that changes `host`, `port` or `scheme` (`socks5` ↔ `http`) of a saved proxy
+  that stores a password must now carry `password` too — the password, or
+  `None` to clear it. Without it the server answers `400`
+  (`BadRequestError`) and nothing changes: _To change this proxy’s address,
+  send its password again (or null to remove it). A saved password is never
+  sent to a new server on its own._ Before, a `password` left out was always
+  kept, so anyone able to edit a proxy could send its password to a server of
+  their choosing. Omitting `password` on an update that keeps the address — a
+  `label` or `username` change, or a resend of the same address — keeps the
+  stored password as before. On an `openvpn` or `wireguard` proxy, change
+  `host` or `port` by sending `scheme` with the full VPN configuration. On
+  both `Driftstack` and `AsyncDriftstack`. The refused attempt is recorded in
+  the account's audit log (read it in the dashboard) as `"proxy.move_refused"`. Shipped without a deprecation window under the
+  API's [security-fix policy](https://docs.driftstack.io/api/versioning/#security-fixes).
+- **`agent_sessions.livekit_token()` needs the `read:sessions` scope as well
+  as `write`.** The token it returns shows the session's live screen as well
+  as sending it input, and `agent_sessions.get()` and `get_capture()` already
+  needed `read:sessions`. A key whose scopes give it `write` but neither
+  `read` nor `read:sessions` (`write` alone, or `write` with another
+  `read:…` scope) now raises a 403 (`ForbiddenError`) and no token is made;
+  before, it got a token. A key with `read` or `read:sessions` beside
+  `write`, or with `account_owner`, works as before.
+
+## [0.3.0] - 2026-09-22
+
+**Nothing was removed.** Every name 0.2.0 exported, every method, every
+keyword argument and every error class is still here and still means the
+same thing, so upgrading takes no code change on its own — except where
+**Migration** below says a string comparison needs updating. Every addition
+below exists on **both** `Driftstack` and `AsyncDriftstack`.
+
+### Added
+
+- **`EgressCapabilities.safeguards`** — `"passed"`, `"failed"` or
+  `"unverified"`, summarising whether every egress safeguard held for a
+  session. `"failed"` wins whenever any check did not pass; `"passed"` only
+  when the device declared the full set of checks a healthy session reports
+  and every one of them reported back; `"unverified"` otherwise. The field is
+  **absent**, not `None`, on a session reported before it existed — do not
+  read an absent value as `"unverified"` or `"passed"`. Rides everywhere
+  `egress_capabilities` already does: `sessions.get()` / `.list()` /
+  `.create()`, `profiles.launch()`, and the
+  `session.egress_capability_changed` webhook payload.
+- **`measured_by`** on a `?check=full` proxy test result
+  (`egress.test_proxy(proxy_id)`) — `"phone"` when a real phone session took
+  the measurement, `"driftstack"` when Driftstack itself did because no phone
+  could be reached in time. The field this replaces, `measured_from`, is
+  still sent beside it with its original values for existing integrations,
+  but is no longer documented; read `measured_by` from here on.
+- **`direct_reading` and `website_like_reading`** on `os_fingerprint` — the
+  same two facts `single_host_vantage` and `web_port_vantage` already carry,
+  under plainer names, added beside the originals rather than replacing
+  them. Present on the proxy test result **and** on each saved
+  proxy returned by `egress.list_proxies()` / `.update_proxy(proxy_id, body)`.
+- **`"page_unreadable"`** joins the `AgentNoticeReason` values a
+  `plan-executed` result can carry: the page could not be read to plan the
+  next step, so the task stopped rather than guess. Send `continue` to try
+  again.
+
+### Changed
+
+- **Two dead `egress_capabilities.warnings` codes are retired from the
+  documentation**: `quic_disabled_fallback_http2` and
+  `dns_remote_resolve_unsupported_by_proxy`. Neither has ever been sent, so
+  this is a documentation correction, not a behavioural change.
+
+### Migration
+
+Two closed-string fields were narrowed — values removed, not added — inside
+the `?check=full` proxy test result. `egress.test_proxy()` and
+`egress.list_proxies()` return a plain `dict`, not a validated model, so the
+affected `AccountProxyTestResult*` / `OsFingerprint` models in
+`driftstack._generated.models` are typing-only for these two fields: neither
+change raises at call time, and code comparing a value against one of the old
+strings simply stops matching, silently. The server has sent the new values
+only since 2026-09-21.
+
+- **`not_run`** — `"node_busy"`, `"node_error"` and `"no_node"` merged into
+  `"check_unavailable"` (you can do exactly one thing about any of the
+  three: try again shortly, or contact support if it persists);
+  `"unresolvable"` is now `"config_unresolvable"`, matching the word the
+  "why a launch is refused" vocabulary already used for the identical fact.
+  `"live_session"` is unchanged.
+- **`os_fingerprint_unavailable`** — `"vpn_tunnel"` is now
+  `"not_available_for_vpn"`, `"not_observed"` is now `"not_captured"`, and
+  `"observer_off"` is now `"not_offered_here"`.
+
+Update any code that compares `not_run` or `os_fingerprint_unavailable`
+against one of the old strings to compare against its replacement instead.
+
+### Pre-1.0 stability
+
+The SDK is pre-1.0. Pin `driftstack-sdk~=0.3.0` rather than an exact version
+and read this file before bumping.
+
+## [0.2.0] - 2026-09-20
+
+The release the guide [Run AI tasks from your
+code](https://docs.driftstack.io/guides/run-ai-tasks-from-code/) is written
+against — 0.1.5 cannot run any of its examples, because the AI agent was not
+reachable from it at all.
+
+**Nothing was removed.** Every name 0.1.5 exported, every method, every
+keyword argument and every error class is still here and still means the same
+thing, so upgrading takes no code change. What grew: both clients went from 4
+resources to 19, and `driftstack.__all__` from 22 names to 56. Every addition
+below exists on **both** `Driftstack` and `AsyncDriftstack`. Read **Changed**
+before you upgrade anyway — a few behaviours differ, and one of them changes
+which exception an `except` clause sees.
+
+### Added
+
+#### Run an AI task end to end
+
+`client.agent_sessions` is new, and is the whole AI surface.
+
+- **Start it, send the task, close it** — `create(body, ...)` opens a
+  session, on a saved profile if you pass one; `message(id, text, ...)` sends
+  the task in plain words and returns what happened; `get(id)`,
+  `list(...)` and `iterate(...)` read sessions back; `close(id)` ends one and
+  saves the profile's sign-in. A new session is `provisioning` until its
+  browser is ready, then `active`.
+- **Every way a turn can end is a named result kind** — `plan-executed` (the
+  steps ran, with `answer` when you asked a question), `clarify` (the agent
+  is asking you something), `refuse` (it will not do this), `stopped`, and a
+  step held for your approval. `answer_unavailable` says why there is no
+  `answer` when you asked for one.
+- **Live progress while it runs** — `message(..., on_step=..., on_event=...)`
+  parses the turn's stream as it arrives: `on_step(step)` gets each step
+  (`{"index", "result"}`) and `on_event(name, data)` every other progress
+  event (`phase`, `plan`, `step_start`, `answer`, `notice`, and any added
+  later). On the async client either callback may be `async def`.
+- **Approve a step, or don't** — a step with real-world consequences (a
+  payment, a message sent, something deleted) pauses the turn and comes back
+  as `confirmation_required`. Send the same task again with
+  `approve_consequential_actions=` to release it; it accepts the step result
+  exactly as it was returned, as well as `{"category", "matched_text"}`
+  dicts, and raises `ValueError` before sending anything if an entry is
+  neither. An unattended job simply never approves.
+- **Stop a task that runs too long** — `stop(id)` asks the running turn to
+  stop; the waiting `message()` then returns kind `stopped` rather than
+  raising.
+- **Screenshots** — `get_capture(id, capture_id)` returns the image behind a
+  `capture` step's `captureId` as `{"content_type", "bytes"}` (`image/png` or
+  `image/jpeg`). Screenshots are kept only briefly, so fetch one as soon as
+  its turn ends; one that is no longer kept raises `NotFoundError`.
+- **Transcripts** — `transcript(id, last_event_id=..., timeout_s=...)`
+  iterates the session's conversation — an iterator on the sync client, an
+  async iterator on the async one: every entry so far, then each new one as
+  it is written. `last_event_id` resumes after the last `index` you saw, and
+  closing the iterator closes the connection.
+- **Why a turn handed back, in one word** — a `plan-executed` result carries
+  `notice_reason` beside the `notice` sentence: `"step_limit"`,
+  `"time_limit"`, `"budget_low"`, `"no_progress"`, `"repeated_step"`,
+  `"ai_unavailable"`, `"question"` or `"declined"`, exported as the open
+  union `AgentNoticeReason` (`Literal[...] | str`), so an ending this SDK has
+  never heard of still type-checks and still parses — match the ones you know
+  and show `notice` for the rest.
+- **When it is safe to retry a message** — a refusal that did no work leaves
+  its `Idempotency-Key` free: after a 409 whose `turn_in_progress` is set, a
+  429, a 402, a 403 about the plan's AI or the model, or a 502 whose
+  `key_rejected` is false, send the same request again with the **same**
+  `idempotency_key=`. Any other failure gets a new one. One message is one
+  key, always.
+- **Typed refusals you can act on** — `ForbiddenError.requires_own_key` /
+  `.model` (this model needs your own Anthropic key);
+  `ConflictError.turn_in_progress`, `.session_status`, `.idempotency_status`,
+  `.ai_control_unavailable`, `.phase`, `.tokens_consumed`, `.usage`,
+  `.partial_results` and `.closed_reason` (why a closed session ended,
+  without a second call); `FeatureUnavailableError.stop_unconfirmed` (the one
+  `stop()` 503 worth calling again); and
+  `ByokAnthropicRequiredError.key_rejected` / `.key_source` /
+  `.key_rejected_reason` (your own key was refused, which key, and why).
+- **Send your own Anthropic key** — `byok_api_key=` on `create()`, so a
+  session can run on a model that requires one without storing anything.
+- **Bound the whole call** — `timeout_s=` on `message()` (default 50
+  minutes).
+- **Why a step failed** — a failed step's `Diagnosis.category` explains it,
+  including `"target_unverified"` (the tap was not made because its target
+  could not be checked first — not retryable as the same step; the agent
+  re-plans).
+- **`examples/agent_chat.py`** is the complete flow end to end: create, wait
+  until ready, send a task with a fresh idempotency key and live progress,
+  handle every result kind, close in `finally`.
+
+#### Watch one live, or take the wheel
+
+- **`livekit_token(id)`** — a token for the live video view of a running
+  session, so a person can watch it work. Returns `LiveKitInfo`.
+- **`set_mode(id, body)`**, **`takeover(id, client_id)`** and
+  **`handback(id)`** — hand control of a running session between the agent
+  and a person, and hand it back. **`send_input_event(id, body)`** drives it
+  while a person holds it, and **`resume(id)`** picks a session back up.
+- **`set_egress(id, body)`** changes which of your proxies a running session
+  goes out through.
+
+#### The rest of the API
+
+`client.sessions`, `client.api_keys`, `client.usage` and `client.webhooks`
+were the whole client in 0.1.5, and each of the four gained methods:
+`sessions` gained `get` / `iterate` / `extract` (pull structured data off the
+page) / `search` / `login`; `usage` gained `series()` for usage over time;
+`api_keys` gained
+`rotate()` (issue the replacement and keep the old key working for a grace
+window); `webhooks` gained `update()` (partial update — it does not rotate
+the signing secret), `rotate_secret()` (fresh secret shown once, previous one
+valid for 24h, both signatures sent during the window), `send_test()` (a
+synthetic `test.ping` delivery so you can check your handler before depending
+on it), `replay_delivery()` and `iterate_deliveries()`.
+
+And fourteen resources are new:
+
+- **`client.profiles`** — create, list, iterate, get, update, delete, plus
+  `clone(profile_id, body=None)` (pass `None` to let the server name it
+  "(copy)", "(copy 2)", …) and `trim()`.
+- **`client.profile_snapshots`** — immutable point-in-time copies of a
+  profile: `capture`, `list_for_profile`, `list`, `iterate`, `get`,
+  `restore`, `delete`. `restore` creates a NEW profile; the original is never
+  modified.
+- **`client.account`** — `me()` (the full account profile: timezone, slug,
+  region, avatar, whether MFA is enrolled, team memberships),
+  `update_me()`, `upload_avatar()` / `clear_avatar()`,
+  `list_web_sessions()` / `revoke_web_session(id)` /
+  `revoke_all_other_web_sessions()`, and `rate_limits()` for the limits
+  actually in force on your account.
+- **`client.auth`** — sign-up, e-mail verification, log in, magic links,
+  password reset, refresh, log out, and the three-call activation flow a CLI
+  or desktop app uses instead of asking for a pasted key
+  (`cli_authorize_initiate` → open the returned `browser_url` → poll
+  `cli_authorize_exchange`, which delivers the key once, then reports
+  `expired`).
+- **`client.mfa`** — `status`, `enroll`, `verify`, `disable`,
+  `regenerate_recovery_codes`; plus `auth.mfa_challenge()` to exchange a
+  login challenge for a session (the response says whether it was satisfied
+  by `"totp"` or `"recovery"`) and `auth.mfa_step_up()` to refresh the
+  freshness window an operation asked for.
+- **`client.team`** — members, invites, roles, and `list_owners()` for the
+  workspaces your account has joined.
+- **`client.audit_log`** — `list` / `iterate`, and `export()`: a single-call
+  JSON export of your account's audit log, up to 10,000 rows, with
+  `truncated` set when there were more.
+- **`client.billing`** — current state, checkout, and the billing portal.
+- **`client.crypto_orders`** — `quote`, `create_checkout` (takes
+  `idempotency_key=` so a retry cannot mint a second order), `list`,
+  `iterate` (walks every page for you; narrow it with `status`,
+  `created_after`, `created_before`), `get`, `update_note`, `cancel`,
+  `receipt`. Crypto payments are not refundable, and cancelling only works
+  while an order is pending.
+- **`client.egress`** and account proxies — manage saved proxies and route a
+  session's traffic through one with `proxy_id` on create.
+- **`client.archetypes`** — the device archetypes your plan can use.
+- **`client.recipes`** — `create(agent_session_id=, label=, description=)`
+  snapshots a finished agent session's steps and transcript into a recipe you
+  can replay.
+- **`client.email_preferences`** — `list` / `set` / `opt_in` / `opt_out`.
+- **`client.legal`** — record acceptance of a document version.
+
+#### Errors and retries
+
+- **`is_retryable(err)`** is exported, so the predicate the built-in retry
+  loop uses is one you can call yourself.
+- **New error classes**, all importable from `driftstack`:
+  `BadRequestError`, `InternalError`, `FeatureUnavailableError`,
+  `MfaStepUpRequiredError`, `EmailAlreadyRegisteredError`,
+  `InvalidCredentialsError`, `InvalidAuthTokenError`,
+  `EmailNotVerifiedError`, `ByokAnthropicRequiredError`,
+  `ProxyValidationFailedError`, `StorageQuotaExceededError`,
+  `ProfileInUseError`, `BundledLlmConsentRequiredError`,
+  `BundledLlmBudgetExhaustedError`, `PairModeConflictError` and
+  `PairModeStateInvalidTransitionError`.
+- **`verify_webhook_signature` accepts `header_prev=`** — an optional second
+  signature header. You rarely need it: during a rotation grace window both
+  signatures arrive inside the one `x-driftstack-signature` header, which the
+  verifier already checks.
+
+### Changed
+
+- **Too many AI turns is a `RateLimitError` now.** This refusal answers as
+  `rate-limited` with `retry_after_seconds` 5, so `message()` raises
+  `RateLimitError` where it raised `ConcurrencyLimitError`.
+  `ConcurrencyLimitError` still means exactly what it always meant on
+  `create()`: your plan's limit on sessions running at once.
+- **A generic 400 raises `BadRequestError` now**, not `ValidationError`. A
+  400 that carries field-level issues is still a `ValidationError`. Callers
+  with `except ValidationError` around a generic 400 should switch to
+  `except BadRequestError`; `except DriftstackError` catch-alls and
+  `is_retryable` are unaffected.
+- **The agent-session docstrings describe what the API does** — result kinds,
+  how an approval resumes paused steps, when a key may be reused, the
+  progress event names — and no longer describe how the service is built. The
+  README no longer claims every resource returns a Pydantic model
+  (`agent_sessions` returns dicts) and now says that `ForbiddenError` is a
+  subclass of `AuthError`.
+
+### Fixed
+
+- **A failure category newer than the SDK no longer breaks parsing.**
+  `Diagnosis.category` is `Literal[...] | str`, so a category the server adds
+  after this release is kept as a plain string. ⚠️ **This is the one reason
+  to upgrade before you need to.** In 0.1.5 the field is a closed `Literal`,
+  so a response carrying a category that SDK has never seen raises a pydantic
+  `ValidationError` for the **whole** response — not just that field. Treat a
+  value you do not recognise as `"unknown"`; code comparing `category`
+  against known strings needs no change.
+- **The account profile matches the full response** — `me()` returns every
+  field the API sends, including the ones added since 0.1.5.
+
+### Pre-1.0 stability
+
+The SDK is pre-1.0. The surface is stable enough to build against, but a
+MINOR bump may still carry additive changes — new methods, new fields, new
+error subclasses. **Patch** releases (0.2.x) are fixes and additive types
+only. Breaking changes that would stop shipping customer code are deferred to
+1.0; until then pin `driftstack-sdk~=0.2.0` rather than an exact version, and
+read this file before bumping.
+
+## [0.1.5] - 2026-05-03
+
+Written on 2026-09-20 from the published wheel: 0.1.5 went to PyPI without a
+CHANGELOG heading of its own.
+
+### Added
+
+- **`LegalAcceptanceRequiredError`** — a 409 that asks you to accept a
+  document version is its own exception now, carrying the pending
+  acceptances (`document_key` + `current_version` for each) as
+  `pending_acceptances`. Exported from the package root.
+
+## [0.1.4] - 2026-05-03
+
+### Added
+
+- **`SessionTimeoutError`** — new typed error subclass mapping
+  the `https://errors.driftstack.dev/session-timeout` problem type
+  (status 504). Distinguished from `DriverError` so callers can
+  react specifically to "the operation didn't finish within the
+  per-call timeout I supplied" without conflating with downstream
+  driver failures. Carries `timeout_ms: int | None` from the
+  problem extension. Re-exported at `driftstack.SessionTimeoutError`
+  for convenient `isinstance` checks.
+
+  ```python
+  from driftstack import SessionTimeoutError
+
+  try:
+      client.sessions.interact(sid, body)
+  except SessionTimeoutError as e:
+      # Retry with a longer timeout, or surface to the user.
+      print(f"Op timed out after {e.timeout_ms} ms")
+  ```
+
+- Test coverage at `tests/test_errors.py::test_session_timeout_extracts_timeout_ms`.
+
+## [0.1.3] - 2026-05-03
+
+### Removed
+
+- `tap.offset` field stripped from the public `InteractAction.tap`
+  shape. Same reason as `tap_at`: a coordinate primitive on the
+  customer-facing schema lets the customer bypass the behavioral
+  simulation layer. Bounded coordinates are still coordinates.
+
+### Migration
+
+If your code passes `offset={"x": ..., "y": ...}` to a `tap`
+action, the value is now silently dropped (Pydantic strips unknown
+keys by default). Re-express the intent through selector
+specificity — better selectors, child-element targeting, ARIA-role
+qualifiers, text-content matching:
+
+```python
+# Before (0.1.x):
+client.sessions.interact(
+    session_id,
+    InteractRequest(action={"kind": "tap", "selector": "button.cta", "offset": {"x": 0, "y": 50}}),
+)
+
+# After (0.1.3+):
+client.sessions.interact(
+    session_id,
+    InteractRequest(action={"kind": "tap", "selector": "button.cta .icon-arrow"}),
+)
+```
+
+Coordinate-level addressing for screenshot-driven workflows is not
+part of the public API, and is not exposed in this SDK.
+
+## [0.1.2] - 2026-05-03
+
+### Added
+
+- Wire-shape regression tests at `tests/test_wire_shape.py` (10
+  tests). Locks the canonical JSON shape for `InteractRequest`,
+  `WaitRequest`, `NavigateRequest`. Asserts rejection of `tap_at` /
+  `type_focused` (they are not part of the public API).
+
+### Fixed
+
+- `tests/test_client.py::test_version_string_matches_pyproject_default`
+  was pinning `__version__ == "0.0.1"` (stale from the pre-publish
+  era). Fixed to assert SemVer shape, not exact value.
+
+## [0.1.1] - 2026-05-02
+
+### Changed
+
+- Re-cut: `tap_at` and `type_focused` removed from
+  `InteractAction`. They were briefly added in 0.1.0+ for the
+  self-hosted GUI's manual-control input forwarding, and reverted.
+  Customer-facing schemas stay intent-only — coordinate primitives
+  bypass the behavioral simulation layer. The desktop app now uses
+  a separate endpoint that is not part of the public API.
+
+## [0.1.0] - 2026-05-02
+
+### Added
+
+- Inaugural PyPI publish (under a maintainer account pre-entity;
+  will transfer to a company-owned account once the legal entity
+  is registered).
+- Pydantic models regenerated from updated OpenAPI spec.
+
+## [0.0.1] - 2026-05-02
+
+### Added
+
+- `Driftstack` (sync) and `AsyncDriftstack` (async) clients.
+- Resource accessors mounted on the client: `sessions` (9 methods),
+  `api_keys` (3), `usage` (1), `webhooks` (5).
+- Typed Pydantic v2 models generated from the API's OpenAPI 3.1 spec.
+- Error hierarchy: `DriftstackError` base + 14 subclasses covering
+  every documented RFC 7807 problem type. `RateLimitError`,
+  `ConcurrencyLimitError`, `QuotaExceededError` carry the relevant
+  payload fields.
+- Retry policy (`RetryConfig` + `with_retry`) with exponential
+  backoff and full jitter; honours `Retry-After`.
+- `verify_webhook_signature` helper (Stripe-style HMAC-SHA256,
+  constant-time).
+- 85 tests covering errors, retry, webhook signatures, every
+  resource method, and end-to-end customer-journey workflows.
+- Examples: `quickstart`, `error_handling`, `webhook_receiver`,
+  `langchain_tool`, `pytest_fixture`.
+
+### Build
+
+- Hatchling backend, `py.typed` marker for PEP 561.
+- Runtime deps: `httpx>=0.27,<1.0`, `pydantic[email]>=2.5,<3.0`.
+- Dev deps: `pytest`, `pytest-asyncio`, `respx`, `ruff`, `mypy`,
+  `datamodel-code-generator`.
+- CI: lint + format + mypy + pytest on Ubuntu / Python 3.10.