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

{driftstack_sdk-0.4.0 → driftstack_sdk-0.5.0}/CHANGELOG.md

@@ -6,6 +6,195 @@ follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-04
+
+**The client methods remove nothing; the generated models change shape.**
+Every method, error class and exported name 0.4.0 published is still there,
+and the methods still return plain `dict`s. If you import classes from
+`driftstack._generated.models` to validate or build a turn's `intents` or
+`results`, read **Changed — BREAKING** below first. The headline is
+`agent_sessions.run_steps()`: run a list of steps you write, as written, with
+no AI planning. Some answers change for the same request — an empty `type`
+value now clears the field, and `ok` is `False` in more cases; read
+**Changed** below before upgrading. Every change below applies to both
+`Driftstack` and `AsyncDriftstack`.
+
+### Changed — BREAKING
+
+- **The generated models for a step and its result are one class each.** The
+  published spec now references `AgentIntent` and `IntentResult` from every
+  turn result, list-of-steps result and conflict problem, where each of those
+  used to carry its own copy. In `driftstack._generated.models`, `intents` is
+  `list[AgentIntent]`, `results` and `partial_results` are
+  `list[IntentResult]`, and an `IntentResult`'s `intent` is an `AgentIntent`.
+  The 135 numbered copies are gone: `Intent` and `Intent1` to `Intent107`,
+  `Intents` and `Intents1` to `Intents17`, `Results` and `Results1` to
+  `Results5`, and `PartialResults`, `PartialResults1` and `PartialResults2`.
+  `AgentIntent` and `IntentResult` are root models: read the step or result
+  through `.root` (`response.intents[0].root.kind`,
+  `response.results[0].root.intent.root.kind`), and replace an import or an
+  `isinstance` check of a numbered copy with `AgentIntent` or `IntentResult`.
+  Nothing changes for the client methods, which return the response as a
+  `dict`, and nothing changes on the wire.
+
+### Added
+
+- **`agent_sessions.run_steps(agent_session_id, steps, ...)`: run steps you
+  already know, without the AI** (`POST /v1/agent-sessions/{id}/steps`), sync
+  and async. `steps` is a list of up to 8 step dicts, the vocabulary a
+  message's `intents` use; they run in order, as written, through the same
+  checks a message's steps go through, with no planning, no read-back and none
+  of the AI budget (no `usage` and no `answer` on the result). The result is a
+  `dict` keyed by `kind`: `plan-executed` (`intents`, `results`, `ok`, and
+  `notice` / `notice_reason` when the run ended early for a reason no step
+  says) or `stopped` when you called `stop()`. A step the session cannot run —
+  one outside the vocabulary, an address on a private network or carrying a
+  user name or password, a key no iPhone keyboard has, a native list, a frame
+  the page did not list or this device cannot act in — is a failed row in
+  `results` whose `reason` says why; nothing after it is sent, and the steps
+  after it are listed in `intents` with no result. A `type` step with text
+  adds to what the field holds; one with an empty `value` clears it. A wait
+  that times out does not stop the run. More than 8 steps raises a 400
+  `ValidationError`; nothing is cut. `approve_consequential_actions` approves
+  a step a previous call stopped at (`confirmation_required`); it counts only
+  when that call is the session's latest and `steps` is the rest of its list
+  from the stopped step on. `idempotency_key`, `timeout_s`, `on_step` and
+  `on_event` work as on `message()`; a key used for a message cannot be reused
+  here. It needs an account key with `write`, and shares the message rate
+  limit and the running-turns limit with `message()`. A session a person has
+  control of, or one in manual mode, raises a 409 `ConflictError`
+  (`ai_control_unavailable`) and nothing runs. New generated models describe
+  the result: `AgentStepsResponse` (a root model over `AgentStepsResponse1`,
+  `plan-executed`, and `AgentStepsResponse2`, `stopped`, with the numbered
+  `Session6`, `Session7`, `CapabilityReport6` and `CapabilityReport7` they
+  carry) and `AgentStepsResponseStream`.
+
+- **A transcript entry's `origin`.** `"steps"` on the one entry a `run_steps`
+  call writes (steps you sent and ran as written, not planned by the agent);
+  absent on every other entry.
+
+- **A turn's `answer` can name the selector of any control on the page, and
+  is no longer cut at 512 characters.** Asked "what is the selector of the Pay
+  button?" or to list a page's buttons with their selectors, the answer quotes
+  the selectors the agent was shown for the page it ended on (`#pay`).
+  `answer` is now at most 4,000 characters (it was cut at 512, which could stop
+  inside a selector); a longer one is cut after its last whole line and ends
+  with `… (the rest was cut for length)` on a line of its own. Its line breaks
+  are kept, so a list asked for one control per line comes back one per line;
+  the transcript entry holds the same text on one line. A CSS selector written
+  in the message is used exactly as written.
+
+- **An `extract` step can read one attribute of an element.** A step with
+  `"kind": "extract"` and a `"selector"` can carry `"attribute"` — never with
+  `"body"` or a frame — naming the attribute that was read instead of the
+  element's text (`"href"`, `"src"`, `"data-order-id"`; the generated model's
+  field allows 1-128 characters of an attribute name). The step's summary reads
+  `extracted attribute href from #terms: …`, and an element without the
+  attribute is said to have none
+  (`extracted nothing: the element #terms has no href attribute`), which is not
+  the same answer as a selector that matched nothing.
+
+- **`Session.proxy_id`: which of your saved proxies a session runs through.**
+  Additive. `sessions.create()`, `sessions.get()`, `sessions.list()` and
+  `profiles.launch()` now report the saved proxy the session's traffic goes
+  out through: the `proxy_id` the create named, or the proxy the launched
+  profile is bound to (on a team, a session an admin started with a proxy
+  saved on the admin's own account reports that admin's proxy). It is kept
+  after the session ends. `None` for a session started without a saved proxy,
+  and when it is not reported: on a read by a team member without admin role,
+  on a read that could not look it up at that moment, and on an older
+  server. `None` alone does not tell those apart; this does:
+  `"proxy_id" in session.model_fields_set` is true only when the server sent
+  the key. A `None` with the key present means no saved proxy, and a `None`
+  without it means not reported (never read that as "no proxy"). Before
+  this, a session started through a proxy did not say which one.
+
+- **On a session whose device supports it, a tap or a wait can name a frame.**
+  Additive, and nothing changes on any other session. On a session whose
+  device can act inside an embedded frame (an iframe), a step in a turn's
+  `intents` can carry `frame` on an `interact` with `"action": "tap"`, and on a
+  `wait` with `"condition": "selector_visible"` — the generated `wait` models
+  gain an optional `frame`, the same path of positions as a read's. The tap's
+  selector is matched, and the element is waited for, inside that frame. A
+  `"scroll"` or `"press"` never carries `frame`: both act on the page itself.
+  Such a step succeeded only when the session confirmed it was done inside
+  exactly that frame; one it did not confirm fails and is not tried again
+  (`diagnosis.category` `"unknown"` for a tap, `"condition_not_met"` for a
+  wait). A tap inside a frame that pays, buys or deletes an account asks for
+  approval as one on the page does.
+
+- **Session secrets: `agent_sessions.register_secret()`, `list_secrets()` and
+  `delete_secret()`**, sync and async. `register_secret` takes the session id
+  and the keyword arguments `label`, `secret` and `sites` (and optionally
+  `include_subdomains` and `ttl_seconds`), holds a password, a one-time code or
+  a payment card number for that one agent session, and returns its handle
+  (`sec_…`); write `{{credential:<handle>}}` in a `message()` as the whole value
+  of the step that types it. The plan, the transcript and every response carry
+  the handle, and the value is typed only on an `https://` page on one of
+  `sites`. Once typed it is on the page; where the page shows it again it is
+  replaced by its placeholder in what the model is shown, the step results and
+  the transcript, as for a saved credential (a card number however its digits
+  are grouped, but not part of it). `label` appears in refusals the model reads,
+  so put nothing secret in it. It is held in server memory only and dropped
+  when the session ends, when deleted, when the service restarts, or when
+  `ttl_seconds` runs out (default 3600); one a step has typed, or tried to, is
+  kept past `ttl_seconds`, never typed again, only to keep hiding it from the
+  model. The answer is an `AgentSessionSecret` (exported from `driftstack`);
+  the generated models gain `CreateAgentSessionSecret`, `AgentSessionSecret`
+  and `AgentSessionSecretList`.
+  `register_secret` is not retried on a network error, since a retry could
+  register the value twice.
+
+- **`frame_match` on `sessions.capture`** (the generated `FrameMatch` model, or a
+  dict). With `kind="dom_snapshot"`, reads one embedded frame (an iframe) named
+  by its address instead of the page: `host` (required; exact, letter case
+  aside, port not compared), `path_prefix` (whole path segments) and `query`
+  (each parameter with exactly that value; at most 10). Exactly one frame must
+  match. With none or several, nothing is read, the session stays ready, and
+  the call raises a 409 `ConflictError` whose `problem["code"]` is
+  `"frame_not_found"`, `"frame_match_ambiguous"` (`problem["matched_frames"]`
+  is the count) or `"frame_match_unconfirmed"`. A `query` parameter whose value
+  the browser removes before it reaches Driftstack (`client_secret`, `token`,
+  `code_verifier`, ...; the full list is in the Sessions reference), or
+  `frame_match` on a screenshot or a PDF, raises a 400 `BadRequestError`; a key
+  `frame_match` does not know, a 400 `ValidationError` (built with the
+  `FrameMatch` model, pydantic refuses it before anything is sent). A session started with a `proxy_id` cannot run
+  it yet, like every step-by-step operation.
+
+### Changed
+
+- **A `type` step with an empty `value` clears the field.** The session
+  deletes what the field holds, one key at a time as a person would, types
+  nothing, and the step's summary says `cleared #email`, never `typed`. To
+  replace what a field holds, send an empty `type` and then one with the new
+  text; the agent now plans a replacement that way. A `type` step with text
+  still adds to what the field holds. A field that cannot be emptied key by
+  key (over 200 characters, or one whose page puts characters back, such as a
+  fixed prefix or an input mask) is not cleared and the step fails with
+  nothing typed; a session whose browser cannot empty a field refuses the
+  step without sending it, and the turn stops there.
+- **`ok` is `False` in more cases.** A planned step that would have acted on
+  the page but could not be sent is now a failed row
+  (`diagnosis.category` `"invalid_request"`) that halts its plan like any
+  failed step; the steps planned after it are listed in `intents` with no
+  result instead of disappearing, and `ok` stays `False` unless a later step
+  acts on the page. `ok` is also `False` when the turn delivered nothing — no
+  step that changed the page or scrolled it, no screenshot and no `answer` —
+  unless the message only asked to wait, and when an English message asks for
+  more things to be done than distinct steps that changed the page ran. Every
+  entry of `results` can then be a success: read `notice`, or
+  `answer_unavailable` when the answer asked for could not be read.
+- **`recipes.create()` leaves out steps that never ran.** A recipe's
+  `intent_log` no longer includes a step the agent planned but could not send,
+  nor the steps planned after it in that plan.
+- **The `refuse` result is documented in full.** No step was planned or run
+  and the session stays active, but the turn is still recorded: the refusal is
+  added to the transcript, and the tokens used to read the message are charged
+  to the session's token budget like any other turn (not when the AI was
+  briefly unavailable or the session stopped answering). Resending cannot
+  repeat anything on the page, but each resend is a new turn; use a new
+  idempotency key. Nothing about the response changed.
+
 ## [0.4.0] - 2026-10-03
 
 **Breaking: the SDK now covers what a program needs to run Driftstack, and

{driftstack_sdk-0.4.0 → driftstack_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: driftstack-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: Driftstack Python SDK — iPhone Safari browser automation. Import as `driftstack`.
 Project-URL: Homepage, https://driftstack.io
 Project-URL: Repository, https://github.com/driftstackdev/driftstack-api
@@ -26,7 +26,7 @@ Requires-Python: >=3.10
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic[email]<3.0,>=2.5
 Provides-Extra: dev
-Requires-Dist: datamodel-code-generator[http]>=0.25; extra == 'dev'
+Requires-Dist: datamodel-code-generator[http]==0.83.0; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'

{driftstack_sdk-0.4.0 → driftstack_sdk-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "driftstack-sdk"
-version = "0.4.0"
+version = "0.5.0"
 description = "Driftstack Python SDK — iPhone Safari browser automation. Import as `driftstack`."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -46,7 +46,10 @@ dev = [
   # Bump this deliberately, running `ruff format` in the same commit.
   "ruff==0.15.13",
   "mypy>=1.10",
-  "datamodel-code-generator[http]>=0.25",
+  # Pinned (2026-10-04): 0.56.1 silently dropped the `extra="allow"` config
+  # of the Problem models (a problem's extra fields were thrown away) while
+  # 0.83.0 keeps it. A different version must regenerate in the same commit.
+  "datamodel-code-generator[http]==0.83.0",
 ]
 
 [project.urls]

{driftstack_sdk-0.4.0 → driftstack_sdk-0.5.0}/src/driftstack/__init__.py

@@ -64,6 +64,7 @@ from driftstack.errors import (
 from driftstack.resources.agent_sessions import (
     AgentCapture,
     AgentNoticeReason,
+    AgentSessionSecret,
     AgentTranscriptEvent,
     LiveKitInfo,
 )
@@ -127,6 +128,7 @@ __all__ = [
     "DeviceUnavailableError",
     "LiveKitInfo",
     "AgentCapture",
+    "AgentSessionSecret",
     "AgentNoticeReason",
     "AgentTranscriptEvent",
     "ListArchetypesResponse",