feat: Expire stuck IN_PROGRESS managed auth sessions via background worker

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 112
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-e14974fd90680e5745b35d8718a1ccce2181f6d17a6e0a1fd35fc5bca88795ae.yml
-openapi_spec_hash: 1b3aa75f0ab48b122d514047f9c82873
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-a674e3c4c0063942621d1b4e7f67b72f7e240c12dd88564fe16627618ba33dd6.yml
+openapi_spec_hash: 8b97c87f0dafe5fc5e5a7365f3687755
 config_hash: 08d55086449943a8fec212b870061a3f

src/kernel/types/auth/managed_auth.py

@@ -197,7 +197,12 @@ class ManagedAuth(BaseModel):
     """
 
     flow_expires_at: Optional[datetime] = None
-    """When the current flow expires (null when no flow in progress)"""
+    """When the current flow expires (null when no flow in progress).
+
+    A flow past this timestamp is no longer valid and its `flow_status` will be
+    `EXPIRED`. Clients may start a new login to supersede a stale `IN_PROGRESS` flow
+    past this timestamp.
+    """
 
     flow_status: Optional[Literal["IN_PROGRESS", "SUCCESS", "FAILED", "EXPIRED", "CANCELED"]] = None
     """Current flow status (null when no flow in progress)"""
@@ -223,7 +228,20 @@ class ManagedAuth(BaseModel):
     """URL to redirect user to for hosted login (present when flow in progress)"""
 
     last_auth_at: Optional[datetime] = None
-    """When the profile was last successfully authenticated"""
+    """Deprecated alias for `last_auth_check_at`.
+
+    Despite the name, this is the last health-check timestamp, not the last
+    successful authentication. Use `last_auth_check_at` instead.
+    """
+
+    last_auth_check_at: Optional[datetime] = None
+    """
+    When the most recent auth health check ran for this connection, regardless of
+    outcome. Updated on every health check and does not by itself indicate that the
+    profile is currently authenticated - use `status` for that. May be newer than
+    `flow_expires_at` when a flow is still in progress because health checks
+    continue to run in parallel.
+    """
 
     live_view_url: Optional[str] = None
     """Browser live view URL for debugging (present when flow in progress)"""