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

{driftstack_sdk-0.2.0 → driftstack_sdk-0.3.0}/CHANGELOG.md

@@ -6,6 +6,78 @@ follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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

{driftstack_sdk-0.2.0 → driftstack_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: driftstack-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: Driftstack Python SDK — stealth iPhone Safari automation. Import as `driftstack`.
 Project-URL: Homepage, https://driftstack.io
 Project-URL: Repository, https://github.com/driftstackdev/driftstack-api

{driftstack_sdk-0.2.0 → driftstack_sdk-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "driftstack-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "Driftstack Python SDK — stealth iPhone Safari automation. Import as `driftstack`."
 readme = "README.md"
 requires-python = ">=3.10"

{driftstack_sdk-0.2.0 → driftstack_sdk-0.3.0}/src/driftstack/_generated/models.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  openapi.json
-#   timestamp: 2026-09-20T08:53:40+00:00
+#   timestamp: 2026-09-21T22:53:06+00:00
 
 from __future__ import annotations
 
@@ -149,7 +149,14 @@ class EgressCapabilities(BaseModel):
     udp_associate: bool
     quic_route: Literal["proxy", "direct", "disabled"]
     dns_remote_resolve: bool
+    safeguards: Literal["passed", "failed", "unverified"] | None = None
+    """
+    Whether every egress safeguard held for this session. Absent (the key is missing entirely, never `null`) on a row written before this field existed — read an absent value as unknown, never as `unverified` and never as `passed`. `passed` — every safeguard check the device reported passed, and the device declared the full set of checks a healthy session reports, so nothing was left unchecked. `failed` — at least one safeguard check did not pass. Stop relying on the session and contact support with the session id. Takes precedence over `unverified` whenever both could apply. `unverified` — we could not establish that every safeguard held: no checks were reported, a declared check never reported back, or the device declared no expected set of checks at all. Nothing is known to have failed, but completeness could not be confirmed either — for anything that matters, treat the session the same way you would `failed`.
+    """
     warnings: list[str] | None = []
+    """
+    Codes naming anything that did not work as asked for this session. Read them as opaque strings: a code you do not recognise is ignored rather than fatal, and a new code can appear without an SDK upgrade. Published vocabulary, with what you can do about each: `udp_unsupported_by_proxy` (the proxy refused UDP, so QUIC cannot travel through it — use a UDP-capable proxy if you need HTTP/3); `quic_unavailable` (QUIC was asked for but could not be used, and traffic fell back to HTTP/2 — retry on a new session if HTTP/3 matters); `dead_proxy` (the proxy stopped answering mid-session — check it is reachable before starting another); `streaming_blank` (the live view produced no picture; the session itself kept running — reopen the view); `streaming_failed` (the live view stopped — start a new session if you need to watch it); `safeguards_unverified` (we could not confirm every egress safeguard ran — treat the egress as unverified and start a new session if that matters); `safeguard_failed` (an egress safeguard did not pass — stop relying on the session and contact support with the session id); `safeguard_failed:direct_internet_block` (the check that nothing leaves outside your proxy did not pass — contact support with the session id); `safeguard_failed:browser_integrity` (the check that the session ran the expected browser build did not pass — contact support with the session id); `safeguard_failed:proxy_egress_verification` (the check that traffic actually left through your proxy did not pass — confirm your proxy and contact support with the session id); `safeguard_failed:live_view_capture` (the live view could not be captured; the session’s own browsing is unaffected).
+    """
 
 
 class Session(BaseModel):
@@ -1462,11 +1469,19 @@ class OsFingerprint(BaseModel):
     observed_via: Literal["proxy_host", "exit_ip"]
     single_host_vantage: bool
     """
-    True only when the proxy host you entered, the machine that opened the connection and the exit address are all one machine, so the reading describes the same path a website sees. Absent or false: do not draw a match/mismatch conclusion from it.
+    True only when the proxy host you entered, the machine that opened the connection and the exit address are all one machine, so the reading describes the same path a website sees. Absent or false: do not draw a match/mismatch conclusion from it. Same fact as `direct_reading` below, kept under its original name for existing integrations.
     """
     web_port_vantage: bool
     """
-    True when the reading was taken on the standard HTTPS port at the proxy's IP address, with no CDN in front — the same path a website connects on. It describes what a site sees on that path; with observed_via "proxy_host" it is still a reading, not a guarantee.
+    True when the reading was taken on the standard HTTPS port at the proxy's IP address, with no CDN in front — the same path a website connects on. It describes what a site sees on that path; with observed_via "proxy_host" it is still a reading, not a guarantee. Same fact as `website_like_reading` below, kept under its original name for existing integrations.
+    """
+    direct_reading: bool | None = None
+    """
+    Whether nothing sat between what was read and what your traffic actually exits from: true only when the address you gave, the address that answered, and your exit address are one machine. The customer-worded name for `single_host_vantage`.
+    """
+    website_like_reading: bool | None = None
+    """
+    Whether the reading was taken the way a real website connection is — a literal address on the standard secure-web port, not a name that could route to shared infrastructure. The customer-worded name for `web_port_vantage`.
     """
 
 
@@ -1551,9 +1566,16 @@ class AccountProxyTestResult1(BaseModel):
     os_fingerprint: OsFingerprint | None = None
     os_fingerprint_at: str | None = None
     os_fingerprint_unavailable: (
-        Literal["vpn_tunnel", "not_observed", "observer_off"] | None
+        Literal["not_available_for_vpn", "not_captured", "not_offered_here"] | None
     ) = None
+    """
+    Why no OS fingerprint was taken, when Driftstack knows the cause: `not_available_for_vpn` (an openvpn or wireguard proxy has no single address of its own to read a stack from — no retry can help); `not_captured` (the reading was attempted and produced nothing this time — a retry may help); `not_offered_here` (this deployment does not take this reading at all — no retry can help).
+    """
     measured_from: Literal["fleet", "control_plane"] | None = None
+    measured_by: Literal["phone", "driftstack"] | None = None
+    """
+    Where this result was measured. `phone` — a real phone session took the measurement, the same machine `check=full` dispatches to. `driftstack` — Driftstack itself measured it: the same path `check=quick` always takes, and the honest fallback when a `check=full` request could not reach a phone in time. Present only on a `check=full` result; `check=quick` is always `driftstack` and carries no field to say so.
+    """
 
 
 class ExitObserved1(BaseModel):
@@ -1569,7 +1591,16 @@ class AccountProxyTestResult2(BaseModel):
     ok: Literal[False]
     reason: str
     measured_from: Literal["fleet", "control_plane"] | None = None
-    not_run: Literal["live_session", "node_busy", "node_error", "no_node"] | None = None
+    measured_by: Literal["phone", "driftstack"] | None = None
+    """
+    Where this result was measured. `phone` — a real phone session took the measurement, the same machine `check=full` dispatches to. `driftstack` — Driftstack itself measured it: the same path `check=quick` always takes, and the honest fallback when a `check=full` request could not reach a phone in time. Present only on a `check=full` result; `check=quick` is always `driftstack` and carries no field to say so.
+    """
+    not_run: (
+        Literal["live_session", "config_unresolvable", "check_unavailable"] | None
+    ) = None
+    """
+    Present when NOTHING RAN, so `ok:false` is not a result about the proxy: `live_session` (a full check of a VPN proxy was skipped because a live session is browsing through it — end the session to check it); `config_unresolvable` (the stored configuration could not be used, so nothing was dialled — re-add it); `check_unavailable` (the full check could not be completed on our side right now — try again shortly, or full checks are not available on this deployment).
+    """
     exit_observed: ExitObserved1 | None = None
 
 
@@ -1585,8 +1616,17 @@ class AccountProxyTestResult3(BaseModel):
     ok: bool
     reason: str | None = None
     measured_from: Literal["fleet"]
+    measured_by: Literal["phone"]
+    """
+    Where this result was measured. `phone` — a real phone session took the measurement, the same machine `check=full` dispatches to. `driftstack` — Driftstack itself measured it: the same path `check=quick` always takes, and the honest fallback when a `check=full` request could not reach a phone in time. Present only on a `check=full` result; `check=quick` is always `driftstack` and carries no field to say so.
+    """
     node_id: str
-    not_run: Literal["live_session", "node_busy", "node_error", "no_node"] | None = None
+    not_run: (
+        Literal["live_session", "config_unresolvable", "check_unavailable"] | None
+    ) = None
+    """
+    Present when NOTHING RAN, so `ok:false` is not a result about the proxy: `live_session` (a full check of a VPN proxy was skipped because a live session is browsing through it — end the session to check it); `config_unresolvable` (the stored configuration could not be used, so nothing was dialled — re-add it); `check_unavailable` (the full check could not be completed on our side right now — try again shortly, or full checks are not available on this deployment).
+    """
     reachable: bool | None = None
     auth_ok: bool | None = None
     udp_associate: bool | None = None
@@ -1607,8 +1647,11 @@ class AccountProxyTestResult3(BaseModel):
     os_fingerprint: OsFingerprint | None = None
     os_fingerprint_at: str | None = None
     os_fingerprint_unavailable: (
-        Literal["vpn_tunnel", "not_observed", "observer_off"] | None
+        Literal["not_available_for_vpn", "not_captured", "not_offered_here"] | None
     ) = None
+    """
+    Why no OS fingerprint was taken, when Driftstack knows the cause: `not_available_for_vpn` (an openvpn or wireguard proxy has no single address of its own to read a stack from — no retry can help); `not_captured` (the reading was attempted and produced nothing this time — a retry may help); `not_offered_here` (this deployment does not take this reading at all — no retry can help).
+    """
 
 
 class AccountProxyTestResult(
@@ -2024,6 +2067,7 @@ class AgentMessageResponse1(BaseModel):
             "no_progress",
             "repeated_step",
             "ai_unavailable",
+            "page_unreadable",
             "question",
             "declined",
         ]
@@ -2031,7 +2075,7 @@ class AgentMessageResponse1(BaseModel):
         | None
     ) = None
     """
-    Why the turn ended, in one word, whenever `notice` is present — never without it. `step_limit`: the task needs more steps than one message runs; send "continue". `time_limit`: the message was taking too long; send "continue". `budget_low`: too little of the session’s AI budget is left; start a new session. `no_progress`: the page stopped changing and the next step would repeat one that changed nothing; a person should say what to try instead. `repeated_step`: the next step would have repeated an action that already ran, which could do it twice; check the page, then send "continue" if it is safe. `ai_unavailable`: the next steps could not be worked out just now; send "continue" to try again. `question`: the agent asked you something part-way; `notice` is the question, and your answer is the next message. `declined`: the agent stopped rather than carry on; a person should decide what to do. Treat it as an OPEN string: match the values you know, and show `notice` for any other.
+    Why the turn ended, in one word, whenever `notice` is present — never without it. `step_limit`: the task needs more steps than one message runs; send "continue". `time_limit`: the message was taking too long; send "continue". `budget_low`: too little of the session’s AI budget is left; start a new session. `no_progress`: the page stopped changing and the next step would repeat one that changed nothing; a person should say what to try instead. `repeated_step`: the next step would have repeated an action that already ran, which could do it twice; check the page, then send "continue" if it is safe. `ai_unavailable`: the next steps could not be worked out just now; send "continue" to try again. `page_unreadable`: the page could not be read to plan the next step; send "continue" to try again. `question`: the agent asked you something part-way; `notice` is the question, and your answer is the next message. `declined`: the agent stopped rather than carry on; a person should decide what to do. Treat it as an OPEN string: match the values you know, and show `notice` for any other.
     """
     usage: AgentMessageUsage | None = None
 

{driftstack_sdk-0.2.0 → driftstack_sdk-0.3.0}/src/driftstack/_version.py

@@ -7,4 +7,4 @@ needed — useful for tools that scrape the version without installing.
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{driftstack_sdk-0.2.0 → driftstack_sdk-0.3.0}/src/driftstack/errors.py

@@ -33,6 +33,19 @@ def _coerce_int(value: Any) -> int:
         return 0
 
 
+def _coerce_optional_int(value: Any) -> int | None:
+    """Like :func:`_coerce_int`, but ``None`` stays ``None`` rather than
+    becoming 0 — for fields whose ABSENCE is meaningful (e.g. a 'balance'
+    refusal carries no ``debt_credits`` at all, which must not read as a
+    debt of exactly zero)."""
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
 class DriftstackError(Exception):
     """Base for every error raised by the Driftstack SDK.
 

{driftstack_sdk-0.2.0 → driftstack_sdk-0.3.0}/src/driftstack/resources/agent_sessions.py

@@ -115,6 +115,8 @@ CanonicalModifier = Literal["cmd", "ctrl", "shift", "option"]
 #:   ``"continue"`` if it is safe.
 #: - ``"ai_unavailable"`` — the next steps could not be worked out just now.
 #:   Send ``"continue"`` to try again.
+#: - ``"page_unreadable"`` — the page could not be read to plan the next step.
+#:   Send ``"continue"`` to try again.
 #: - ``"question"`` — the agent asked you something part-way. ``notice`` is the
 #:   question; send your answer as the next message.
 #: - ``"declined"`` — the agent stopped rather than carry on. A person should
@@ -131,6 +133,7 @@ AgentNoticeReason = (
         "no_progress",
         "repeated_step",
         "ai_unavailable",
+        "page_unreadable",
         "question",
         "declined",
     ]