feat: Let Vaults fill credentials from 1Password

Stainless-Generated-From: 6d937aebb18d99636c515de11d6958083e7ca24c

Author: kernel-internal[bot]

api.md

@@ -555,6 +555,8 @@ from kernel.types.vaults import (
     CardVaultItemSpec,
     CardVaultItemState,
     CollectVaultItemOperationRequest,
+    CredentialAccountVaultItem,
+    CredentialAccountVaultItemRequest,
     CredentialCollectionAction,
     CredentialVaultFieldDefinition,
     CredentialVaultFieldInput,
@@ -570,6 +572,19 @@ from kernel.types.vaults import (
     CredentialVaultItemUpdateRequest,
     FillVaultItemOperationRequest,
     FillVaultItemOperationResult,
+    KernelCredentialVaultItemSpec,
+    KernelCredentialVaultItemSpecInput,
+    KernelCredentialVaultItemState,
+    OnePasswordCredentialAccountSpec,
+    OnePasswordCredentialAccountState,
+    OnePasswordCredentialVaultItemSpec,
+    OnePasswordCredentialVaultItemSpecInput,
+    OnePasswordCredentialVaultItemState,
+    OnePasswordFillVaultItemOperationRequest,
+    OnePasswordFillVaultItemOperationResult,
+    OnePasswordOAuthAction,
+    OnePasswordRecoverVaultItemOperationRequest,
+    OnePasswordRequestAccessVaultItemOperationRequest,
     PrepareCheckoutVaultItemOperationRequest,
     VaultCardAliases,
     VaultCardFillField,

src/kernel/resources/vaults/items.py

@@ -20,6 +20,7 @@
 from .wallet_vault_item_spec import WalletVaultItemSpec as WalletVaultItemSpec
 from .vault_fill_field_result import VaultFillFieldResult as VaultFillFieldResult
 from .wallet_vault_item_state import WalletVaultItemState as WalletVaultItemState
+from .one_password_oauth_action import OnePasswordOAuthAction as OnePasswordOAuthAction
 from .card_vault_item_spec_param import CardVaultItemSpecParam as CardVaultItemSpecParam
 from .credential_vault_item_spec import CredentialVaultItemSpec as CredentialVaultItemSpec
 from .credential_vault_field_type import CredentialVaultFieldType as CredentialVaultFieldType
@@ -28,15 +29,22 @@
 from .credential_collection_action import CredentialCollectionAction as CredentialCollectionAction
 from .credential_vault_field_state import CredentialVaultFieldState as CredentialVaultFieldState
 from .vault_checkout_context_param import VaultCheckoutContextParam as VaultCheckoutContextParam
+from .credential_account_vault_item import CredentialAccountVaultItem as CredentialAccountVaultItem
 from .item_perform_operation_params import ItemPerformOperationParams as ItemPerformOperationParams
 from .vault_item_operation_response import VaultItemOperationResponse as VaultItemOperationResponse
 from .agentcard_checkout_preparation import AgentcardCheckoutPreparation as AgentcardCheckoutPreparation
 from .agentcard_checkout_authorization import AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization
 from .fill_vault_item_operation_result import FillVaultItemOperationResult as FillVaultItemOperationResult
 from .credential_vault_field_definition import CredentialVaultFieldDefinition as CredentialVaultFieldDefinition
+from .kernel_credential_vault_item_spec import KernelCredentialVaultItemSpec as KernelCredentialVaultItemSpec
 from .credential_vault_field_input_param import CredentialVaultFieldInputParam as CredentialVaultFieldInputParam
+from .kernel_credential_vault_item_state import KernelCredentialVaultItemState as KernelCredentialVaultItemState
 from .credential_vault_field_update_param import CredentialVaultFieldUpdateParam as CredentialVaultFieldUpdateParam
 from .credential_vault_item_request_param import CredentialVaultItemRequestParam as CredentialVaultItemRequestParam
+from .one_password_credential_account_spec import OnePasswordCredentialAccountSpec as OnePasswordCredentialAccountSpec
+from .one_password_credential_account_state import (
+    OnePasswordCredentialAccountState as OnePasswordCredentialAccountState,
+)
 from .credential_vault_item_spec_input_param import (
     CredentialVaultItemSpecInputParam as CredentialVaultItemSpecInputParam,
 )
@@ -46,15 +54,45 @@
 from .fill_vault_item_operation_request_param import (
     FillVaultItemOperationRequestParam as FillVaultItemOperationRequestParam,
 )
+from .one_password_credential_vault_item_spec import (
+    OnePasswordCredentialVaultItemSpec as OnePasswordCredentialVaultItemSpec,
+)
+from .one_password_credential_vault_item_state import (
+    OnePasswordCredentialVaultItemState as OnePasswordCredentialVaultItemState,
+)
 from .collect_vault_item_operation_request_param import (
     CollectVaultItemOperationRequestParam as CollectVaultItemOperationRequestParam,
 )
 from .credential_vault_item_update_request_param import (
     CredentialVaultItemUpdateRequestParam as CredentialVaultItemUpdateRequestParam,
 )
+from .one_password_credential_account_spec_param import (
+    OnePasswordCredentialAccountSpecParam as OnePasswordCredentialAccountSpecParam,
+)
+from .credential_account_vault_item_request_param import (
+    CredentialAccountVaultItemRequestParam as CredentialAccountVaultItemRequestParam,
+)
 from .authorize_vault_item_operation_request_param import (
     AuthorizeVaultItemOperationRequestParam as AuthorizeVaultItemOperationRequestParam,
 )
+from .kernel_credential_vault_item_spec_input_param import (
+    KernelCredentialVaultItemSpecInputParam as KernelCredentialVaultItemSpecInputParam,
+)
+from .one_password_fill_vault_item_operation_result import (
+    OnePasswordFillVaultItemOperationResult as OnePasswordFillVaultItemOperationResult,
+)
+from .one_password_credential_vault_item_spec_input_param import (
+    OnePasswordCredentialVaultItemSpecInputParam as OnePasswordCredentialVaultItemSpecInputParam,
+)
 from .prepare_checkout_vault_item_operation_request_param import (
     PrepareCheckoutVaultItemOperationRequestParam as PrepareCheckoutVaultItemOperationRequestParam,
 )
+from .one_password_fill_vault_item_operation_request_param import (
+    OnePasswordFillVaultItemOperationRequestParam as OnePasswordFillVaultItemOperationRequestParam,
+)
+from .one_password_recover_vault_item_operation_request_param import (
+    OnePasswordRecoverVaultItemOperationRequestParam as OnePasswordRecoverVaultItemOperationRequestParam,
+)
+from .one_password_request_access_vault_item_operation_request_param import (
+    OnePasswordRequestAccessVaultItemOperationRequestParam as OnePasswordRequestAccessVaultItemOperationRequestParam,
+)

src/kernel/types/vaults/__init__.py

@@ -0,0 +1,73 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Optional
+from datetime import datetime
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+from .one_password_oauth_action import OnePasswordOAuthAction
+from .one_password_credential_account_spec import OnePasswordCredentialAccountSpec
+from .one_password_credential_account_state import OnePasswordCredentialAccountState
+
+__all__ = ["CredentialAccountVaultItem", "AvailableExpansion", "AvailableOperation"]
+
+
+class AvailableExpansion(BaseModel):
+    """
+    Live data that can currently be requested by passing its type to the item GET expand parameter.
+    """
+
+    description: str
+
+    type: Literal["payment_methods"]
+
+
+class AvailableOperation(BaseModel):
+    """An operation that is currently valid for this item.
+
+    Read the description before invoking it through the item operations endpoint.
+    """
+
+    description: str
+
+    type: Literal[
+        "authorize",
+        "collect",
+        "prepare_checkout",
+        "fill",
+        "1pw_create_access_request",
+        "1pw_access_request_status",
+        "1pw_fill",
+        "1pw_recover",
+        "1pw_update_access_token",
+    ]
+
+
+class CredentialAccountVaultItem(BaseModel):
+    id: str
+
+    available_expansions: List[AvailableExpansion]
+
+    available_operations: List[AvailableOperation]
+    """Advertises 1pw_recover when Kernel can recover a failed account link.
+
+    Recovery is unavailable while authorization is pending or after the connection
+    has already been reset.
+    """
+
+    created_at: datetime
+
+    key: str
+    """Immutable item key assigned when the item is created."""
+
+    spec: OnePasswordCredentialAccountSpec
+
+    state: OnePasswordCredentialAccountState
+
+    type: Literal["credential_account"]
+
+    updated_at: datetime
+
+    action: Optional[OnePasswordOAuthAction] = None
+
+    expires_at: Optional[datetime] = None

src/kernel/types/vaults/credential_account_vault_item.py

@@ -0,0 +1,15 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, TypedDict
+
+from .one_password_credential_account_spec_param import OnePasswordCredentialAccountSpecParam
+
+__all__ = ["CredentialAccountVaultItemRequestParam"]
+
+
+class CredentialAccountVaultItemRequestParam(TypedDict, total=False):
+    spec: Required[OnePasswordCredentialAccountSpecParam]
+
+    type: Required[Literal["credential_account"]]

src/kernel/types/vaults/credential_account_vault_item_request_param.py

@@ -1,15 +1,22 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import List, Optional
+from typing import List, Union, Optional
 from datetime import datetime
-from typing_extensions import Literal
+from typing_extensions import Literal, Annotated, TypeAlias
 
+from ..._utils import PropertyInfo
 from ..._models import BaseModel
 from .credential_vault_item_spec import CredentialVaultItemSpec
 from .credential_vault_item_state import CredentialVaultItemState
 from .credential_collection_action import CredentialCollectionAction
 
-__all__ = ["CredentialVaultItem", "AvailableExpansion", "AvailableOperation"]
+__all__ = [
+    "CredentialVaultItem",
+    "AvailableExpansion",
+    "AvailableOperation",
+    "Action",
+    "ActionOnePasswordAccessApprovalAction",
+]
 
 
 class AvailableExpansion(BaseModel):
@@ -30,7 +37,39 @@ class AvailableOperation(BaseModel):
 
     description: str
 
-    type: Literal["authorize", "collect", "prepare_checkout", "fill"]
+    type: Literal[
+        "authorize",
+        "collect",
+        "prepare_checkout",
+        "fill",
+        "1pw_create_access_request",
+        "1pw_access_request_status",
+        "1pw_fill",
+        "1pw_recover",
+        "1pw_update_access_token",
+    ]
+
+
+class ActionOnePasswordAccessApprovalAction(BaseModel):
+    instructions: str
+    """
+    Steps for the agent to hand approval to the human and poll the resulting
+    decision.
+    """
+
+    name: Literal["1password_access_approval"]
+
+    url: str
+    """Native 1Password approval link.
+
+    Present it to the account owner without modifying it; it does not grant access
+    until they approve in their app.
+    """
+
+
+Action: TypeAlias = Annotated[
+    Union[CredentialCollectionAction, ActionOnePasswordAccessApprovalAction], PropertyInfo(discriminator="name")
+]
 
 
 class CredentialVaultItem(BaseModel):
@@ -39,9 +78,11 @@ class CredentialVaultItem(BaseModel):
     available_expansions: List[AvailableExpansion]
 
     available_operations: List[AvailableOperation]
-    """Advertises collect for ready and pending_collection items.
+    """Kernel credentials advertise collect and fill when eligible.
 
-    Browser fill is advertised only when separately implemented and eligible.
+    1Password credentials advertise 1pw_create_access_request until a request is
+    made, 1pw_access_request_status while its approval is pending, and 1pw_fill
+    after access is granted.
     """
 
     created_at: datetime
@@ -50,6 +91,10 @@ class CredentialVaultItem(BaseModel):
     """Immutable item key assigned when the item is created."""
 
     spec: CredentialVaultItemSpec
+    """
+    Stored-token credentials omit account and never return access_token or
+    integration_key.
+    """
 
     state: CredentialVaultItemState
 
@@ -63,7 +108,7 @@ class CredentialVaultItem(BaseModel):
     collection-link renewal.
     """
 
-    action: Optional[CredentialCollectionAction] = None
+    action: Optional[Action] = None
     """
     One schema-derived form for the item, available in ready or pending_collection
     state. Render every form-supported field as editable; omit totp fields and

src/kernel/types/vaults/credential_vault_item.py

@@ -11,19 +11,18 @@
 
 class CredentialVaultItemRequestParam(TypedDict, total=False):
     """
-    Create a credential item without a wallet or external provider.
-    Do not use credential items to store, collect, or fill credit card data,
-    including card numbers (PANs), security codes (CVV/CVC), or expiration dates.
-    Use wallet and card item types for credit cards and payment checkout instead.
-    If all required fields have values, return ready without a collection action;
-    collect can still open its form. Otherwise return pending_collection with
-    a time-scoped Kernel-hosted collection action. Missing
-    optional fields alone do not trigger collection. Repeating the original
-    creation request returns the current item without overwriting later edits;
-    a different request at the same key returns 409. Use PATCH for updates.
-    Required totp fields must include a valid seed on creation; otherwise return
-    400 rather than opening a form that cannot collect it. Optional totp fields
-    may be unset and populated later through PATCH.
+    Ask the end-user whether to link their site credential through 1Password.
+    If they choose 1Password, connect their account and request access to a login
+    in their own non-shared vault; passkeys are not supported. If they decline
+    or that path fails, collect a Kernel-hosted credential item instead. Never
+    automatically retry an uncertain 1Password request or fill.
+    Do not use credential items for credit card data. Use wallet and card item types instead.
+    Kernel credentials declare fields and may enter pending_collection.
+    1Password credentials either reference a connected credential_account or
+    store a supplied access token and integration key encrypted on the item.
+    They store no login values or selectors. Repeating the original creation
+    request returns the current item without overwriting later state. A
+    different request at the same key returns 409.
     """
 
     spec: Required[CredentialVaultItemSpecInputParam]

src/kernel/types/vaults/credential_vault_item_request_param.py

@@ -1,22 +1,14 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import List, Optional
+from typing import Union
+from typing_extensions import Annotated, TypeAlias
 
-from ..._models import BaseModel
-from .credential_vault_field_definition import CredentialVaultFieldDefinition
+from ..._utils import PropertyInfo
+from .kernel_credential_vault_item_spec import KernelCredentialVaultItemSpec
+from .one_password_credential_vault_item_spec import OnePasswordCredentialVaultItemSpec
 
 __all__ = ["CredentialVaultItemSpec"]
 
-
-class CredentialVaultItemSpec(BaseModel):
-    fields: List[CredentialVaultFieldDefinition]
-    """
-    Ordered field definitions rendered in this order by credential collection forms.
-    """
-
-    description: Optional[str] = None
-    """
-    Recognizable site or service name displayed verbatim as the form title, without
-    suffixes such as sign-in credentials. Display text only, not an enforced
-    destination policy.
-    """
+CredentialVaultItemSpec: TypeAlias = Annotated[
+    Union[KernelCredentialVaultItemSpec, OnePasswordCredentialVaultItemSpec], PropertyInfo(discriminator="provider")
+]

src/kernel/types/vaults/credential_vault_item_spec.py

@@ -2,31 +2,14 @@
 
 from __future__ import annotations
 
-from typing import Iterable
-from typing_extensions import Required, TypedDict
+from typing import Union
+from typing_extensions import TypeAlias
 
-from .credential_vault_field_input_param import CredentialVaultFieldInputParam
+from .kernel_credential_vault_item_spec_input_param import KernelCredentialVaultItemSpecInputParam
+from .one_password_credential_vault_item_spec_input_param import OnePasswordCredentialVaultItemSpecInputParam
 
 __all__ = ["CredentialVaultItemSpecInputParam"]
 
-
-class CredentialVaultItemSpecInputParam(TypedDict, total=False):
-    """Credential fields are for login and other non-payment credentials.
-
-    Do not store, collect, or fill credit card data in credential items. Use wallet and card item types for credit cards and payment checkout instead. Field order is preserved in the user-facing collection form, so list fields in the same top-to-bottom order as the website.
-    """
-
-    fields: Required[Iterable[CredentialVaultFieldInputParam]]
-    """Ordered field definitions.
-
-    Use the website's top-to-bottom field order; the collection form renders this
-    order unchanged.
-    """
-
-    description: str
-    """
-    The site's recognizable display name, used verbatim as the user-facing form
-    title (for example, Hacker News). Use only the site or service name; do not
-    append sign-in, login, credentials, or task instructions. This is display text,
-    not an enforced destination policy. At most 16 KiB in UTF-8 bytes.
-    """
+CredentialVaultItemSpecInputParam: TypeAlias = Union[
+    KernelCredentialVaultItemSpecInputParam, OnePasswordCredentialVaultItemSpecInputParam
+]