feat: Enhance AuthAgentInvocation with step and last activity tracking

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 89
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-13214b99e392aab631aa1ca99b6a51a58df81e34156d21b8d639bea779566123.yml
-openapi_spec_hash: a88d175fc3980de3097ac1411d8dcbff
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-2cf104c4b88159c6a50713b019188f83983748b9cacec598089cf9068dc5b1cd.yml
+openapi_spec_hash: 84ea30ae65ad7ebcc04d2f3907d1e73b
 config_hash: 179f33af31ece83563163d5b3d751d13

src/kernel/resources/agents/auth/invocations.py

@@ -116,10 +116,9 @@ def retrieve(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AgentAuthInvocationResponse:
-        """Returns invocation details including app_name and target_domain.
-
-        Uses the JWT
-        returned by the exchange endpoint, or standard API key or JWT authentication.
+        """
+        Returns invocation details including status, app_name, and target_domain.
+        Supports both API key and JWT (from exchange endpoint) authentication.
 
         Args:
           extra_headers: Send extra headers
@@ -155,7 +154,7 @@ def discover(
         """
         Inspects the target site to detect logged-in state or discover required fields.
         Returns 200 with success: true when fields are found, or 4xx/5xx for failures.
-        Requires the JWT returned by the exchange endpoint.
+        Supports both API key and JWT (from exchange endpoint) authentication.
 
         Args:
           login_url: Optional login page URL. If provided, will override the stored login URL for
@@ -233,7 +232,8 @@ def submit(
     ) -> AgentAuthSubmitResponse:
         """
         Submits field values for the discovered login form and may return additional
-        auth fields or success. Requires the JWT returned by the exchange endpoint.
+        auth fields or success. Supports both API key and JWT (from exchange endpoint)
+        authentication.
 
         Args:
           field_values: Values for the discovered login fields
@@ -342,10 +342,9 @@ async def retrieve(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AgentAuthInvocationResponse:
-        """Returns invocation details including app_name and target_domain.
-
-        Uses the JWT
-        returned by the exchange endpoint, or standard API key or JWT authentication.
+        """
+        Returns invocation details including status, app_name, and target_domain.
+        Supports both API key and JWT (from exchange endpoint) authentication.
 
         Args:
           extra_headers: Send extra headers
@@ -381,7 +380,7 @@ async def discover(
         """
         Inspects the target site to detect logged-in state or discover required fields.
         Returns 200 with success: true when fields are found, or 4xx/5xx for failures.
-        Requires the JWT returned by the exchange endpoint.
+        Supports both API key and JWT (from exchange endpoint) authentication.
 
         Args:
           login_url: Optional login page URL. If provided, will override the stored login URL for
@@ -461,7 +460,8 @@ async def submit(
     ) -> AgentAuthSubmitResponse:
         """
         Submits field values for the discovered login form and may return additional
-        auth fields or success. Requires the JWT returned by the exchange endpoint.
+        auth fields or success. Supports both API key and JWT (from exchange endpoint)
+        authentication.
 
         Args:
           field_values: Values for the discovered login fields

src/kernel/types/agents/agent_auth_invocation_response.py

@@ -20,5 +20,8 @@ class AgentAuthInvocationResponse(BaseModel):
     status: Literal["IN_PROGRESS", "SUCCESS", "EXPIRED", "CANCELED"]
     """Invocation status"""
 
+    step: Literal["initialized", "discovering", "awaiting_input", "submitting", "completed", "expired"]
+    """Current step in the invocation workflow"""
+
     target_domain: str
     """Target domain for authentication"""

src/kernel/types/agents/auth_agent_invocation_create_response.py

@@ -13,7 +13,7 @@
 class AuthAgentAlreadyAuthenticated(BaseModel):
     """Response when the agent is already authenticated."""
 
-    status: Literal["already_authenticated"]
+    status: Literal["ALREADY_AUTHENTICATED"]
     """Indicates the agent is already authenticated and no invocation was created."""
 
 
@@ -32,7 +32,7 @@ class AuthAgentInvocationCreated(BaseModel):
     invocation_id: str
     """Unique identifier for the invocation."""
 
-    status: Literal["invocation_created"]
+    status: Literal["INVOCATION_CREATED"]
     """Indicates an invocation was created."""
 
 

src/kernel/types/agents/reauth_response.py

@@ -11,7 +11,7 @@
 class ReauthResponse(BaseModel):
     """Response from triggering re-authentication"""
 
-    status: Literal["reauth_started", "already_authenticated", "cannot_reauth"]
+    status: Literal["REAUTH_STARTED", "ALREADY_AUTHENTICATED", "CANNOT_REAUTH"]
     """Result of the re-authentication attempt"""
 
     invocation_id: Optional[str] = None