feat: persist user_context on credentials (#SKY-8074) (#5081)

Co-authored-by: Shuchang Zheng <wintonzheng0325@gmail.com>

alembic/versions/2026_03_13_0122-b37f05a2bfbf_user_context_for_credentials_table.py

@@ -0,0 +1,31 @@
+"""user_context for credentials table
+
+Revision ID: b37f05a2bfbf
+Revises: 08f585f2e7a6
+Create Date: 2026-03-13 01:22:48.294533+00:00
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "b37f05a2bfbf"
+down_revision: Union[str, None] = "08f585f2e7a6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column("credentials", sa.Column("user_context", sa.String(length=1000), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("credentials", "user_context")
+    # ### end Alembic commands ###

skyvern/forge/sdk/db/agent_db.py

@@ -5477,6 +5477,7 @@ class AgentDB(BaseAlchemyDB):
         card_brand: str | None,
         totp_identifier: str | None = None,
         secret_label: str | None = None,
+        user_context: str | None = None,
     ) -> Credential:
         async with self.Session() as session:
             credential = CredentialModel(
@@ -5491,6 +5492,7 @@ class AgentDB(BaseAlchemyDB):
                 card_last4=card_last4,
                 card_brand=card_brand,
                 secret_label=secret_label,
+                user_context=user_context,
             )
             session.add(credential)
             await session.commit()
@@ -5532,6 +5534,7 @@ class AgentDB(BaseAlchemyDB):
         name: str | None = None,
         browser_profile_id: str | None | object = _UNSET,
         tested_url: str | None | object = _UNSET,
+        user_context: str | None | object = _UNSET,
     ) -> Credential:
         async with self.Session() as session:
             credential = (
@@ -5550,6 +5553,8 @@ class AgentDB(BaseAlchemyDB):
                 credential.browser_profile_id = browser_profile_id
             if tested_url is not _UNSET:
                 credential.tested_url = tested_url
+            if user_context is not _UNSET:
+                credential.user_context = user_context
             await session.commit()
             await session.refresh(credential)
             return Credential.model_validate(credential)

skyvern/forge/sdk/db/models.py

@@ -975,6 +975,7 @@ class CredentialModel(Base):
     secret_label = Column(String, nullable=True)
     browser_profile_id = Column(String, nullable=True)
     tested_url = Column(String, nullable=True)
+    user_context = Column(String(1000), nullable=True)
 
     created_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)
     modified_at = Column(DateTime, default=datetime.datetime.utcnow, onupdate=datetime.datetime.utcnow, nullable=False)

skyvern/forge/sdk/routes/credentials.py

@@ -444,6 +444,8 @@ async def rename_credential(
     }
     if data.tested_url is not None:
         update_kwargs["tested_url"] = data.tested_url
+    if data.user_context is not None:
+        update_kwargs["user_context"] = data.user_context
     updated = await app.DATABASE.update_credential(**update_kwargs)
     if not updated:
         raise HTTPException(status_code=500, detail="Failed to update credential")
@@ -1774,6 +1776,7 @@ def _convert_to_response(credential: Credential) -> CredentialResponse:
             name=credential.name,
             browser_profile_id=credential.browser_profile_id,
             tested_url=credential.tested_url,
+            user_context=credential.user_context,
         )
     elif credential.credential_type == CredentialType.CREDIT_CARD:
         credential_response = CreditCardCredentialResponse(
@@ -1787,6 +1790,7 @@ def _convert_to_response(credential: Credential) -> CredentialResponse:
             name=credential.name,
             browser_profile_id=credential.browser_profile_id,
             tested_url=credential.tested_url,
+            user_context=credential.user_context,
         )
     elif credential.credential_type == CredentialType.SECRET:
         credential_response = SecretCredentialResponse(secret_label=credential.secret_label)
@@ -1797,6 +1801,7 @@ def _convert_to_response(credential: Credential) -> CredentialResponse:
             name=credential.name,
             browser_profile_id=credential.browser_profile_id,
             tested_url=credential.tested_url,
+            user_context=credential.user_context,
         )
     else:
         raise HTTPException(status_code=400, detail="Credential type not supported")

skyvern/forge/sdk/schemas/credentials.py

@@ -177,6 +177,10 @@ class CredentialResponse(BaseModel):
     name: str = Field(..., description="Name of the credential", examples=["Amazon Login"])
     browser_profile_id: str | None = Field(default=None, description="Browser profile ID linked to this credential")
     tested_url: str | None = Field(default=None, description="Login page URL used during the credential test")
+    user_context: str | None = Field(
+        default=None,
+        description="User-provided context describing the login sequence (e.g., 'click SSO button first')",
+    )
 
 
 class Credential(BaseModel):
@@ -208,6 +212,10 @@ class Credential(BaseModel):
     secret_label: str | None = Field(default=None, description="For secret credentials: optional label")
     browser_profile_id: str | None = Field(default=None, description="Browser profile ID linked to this credential")
     tested_url: str | None = Field(default=None, description="Login page URL used during the credential test")
+    user_context: str | None = Field(
+        default=None,
+        description="User-provided context describing the login sequence (e.g., 'click SSO button first')",
+    )
 
     created_at: datetime = Field(..., description="Timestamp when the credential was created")
     modified_at: datetime = Field(..., description="Timestamp when the credential was last modified")
@@ -228,6 +236,16 @@ class UpdateCredentialRequest(BaseModel):
         description="Optional login page URL associated with this credential",
         examples=["https://example.com/login"],
     )
+    user_context: str | None = Field(
+        default=None,
+        max_length=1000,
+        description="Optional user-provided context describing the login sequence (e.g., 'click SSO button first')",
+    )
+
+    @field_validator("user_context", mode="before")
+    @classmethod
+    def normalize_user_context(cls, v: str | None) -> str | None:
+        return _normalize_optional_str(v)
 
 
 def _normalize_optional_str(v: str | None) -> str | None: