2.0.0 — wallet-auth types + AgentScoreError.details + create_session args + drop verify_webhook_signature

.claude/CLAUDE.md

@@ -4,16 +4,18 @@ Python client for the AgentScore trust and reputation API.
 
 ## Identity Model
 
+Two identity paths: `X-Wallet-Address` (wallet-based) and `X-Operator-Token` (credential-based). Wallet addresses accept both EVM (`0x...` 40-hex) and Solana (base58, 32–44 chars) formats — network is auto-detected from the address shape. `assess` responses include `resolved_operator` and `linked_wallets[]` (same-operator sibling wallets, normalized per network — EVM lowercased, Solana base58 verbatim; may mix chains for cross-chain operators). `create_session` and `create_credential` responses include an `agent_memory` cross-merchant pattern hint. `create_session` also returns `next_steps.action="deliver_verify_url_and_poll"` + polling instructions. `poll_session` returns `next_steps.action` values: `continue_polling`, `retry_merchant_request_with_operator_token`, `use_stored_operator_token`, `create_new_session`, `verification_failed`, `contact_support`.
+
 ## Methods (sync + async)
 
 - `get_reputation` / `aget_reputation` — cached reputation lookup (free)
-- `assess` / `aassess` — identity gate with policy (paid). Accepts `operator_token` for non-wallet agents.
-- `create_session` / `acreate_session` — create verification session
-- `poll_session` / `apoll_session` — poll session status, returns credential when verified
-- `create_credential` / `acreate_credential` — create operator credential (24h TTL default)
+- `assess` / `aassess` — identity gate with policy (paid). Accepts `operator_token` for non-wallet agents. Response includes `linked_wallets[]` and `resolved_operator`.
+- `create_session` / `acreate_session` — create verification session. Returns `agent_memory` + `next_steps`.
+- `poll_session` / `apoll_session` — poll session status, returns credential when verified, plus `next_steps.action`.
+- `create_credential` / `acreate_credential` — create operator credential (24h TTL default). Response includes `agent_memory`.
 - `list_credentials` / `alist_credentials` — list active credentials
 - `revoke_credential` / `arevoke_credential` — revoke a credential
-- `associate_wallet` / `aassociate_wallet` — report a signer wallet seen paying under a credential (TEC-189). Accepts optional `idempotency_key` (payment intent id / tx hash) so retries don't inflate transaction_count.
+- `associate_wallet` / `aassociate_wallet` — report a signer wallet seen paying under a credential. Accepts optional `idempotency_key` (payment intent id / tx hash) so retries don't inflate transaction_count.
 
 ## Architecture
 
@@ -37,6 +39,7 @@ Single-package Python library published to PyPI.
 
 ```bash
 uv sync --all-extras
+uv run lefthook install   # one-time per clone — wires pre-commit + pre-push
 uv run ruff check .
 uv run ruff format .
 uv run ty check agentscore/

.github/workflows/ci.yml

@@ -19,9 +19,9 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: useblacksmith/checkout@v1
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.1.0
       - run: uv python install 3.12
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/.cache/uv

.github/workflows/publish.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.1.0
 
       - name: Set version from tag
         run: sed -i "s/^version = .*/version = \"${GITHUB_REF_NAME#v}\"/" pyproject.toml

.github/workflows/security.yml

@@ -23,19 +23,19 @@ jobs:
 
       - name: Install osv-scanner
         run: |
-          curl -fsSL https://github.com/google/osv-scanner/releases/download/v2.3.2/osv-scanner_linux_amd64 -o osv-scanner
+          curl -fsSL https://github.com/google/osv-scanner/releases/download/v2.3.5/osv-scanner_linux_arm64 -o osv-scanner
           chmod +x osv-scanner
 
       - name: Scan dependencies
-        run: ./osv-scanner --lockfile=uv.lock --format=table || true
+        run: ./osv-scanner scan source --lockfile=uv.lock --format=table
 
   pip-audit:
     name: Python Audit
     runs-on: blacksmith-2vcpu-ubuntu-2404-arm
     timeout-minutes: 5
     steps:
       - uses: useblacksmith/checkout@v1
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.1.0
       - uses: actions/setup-python@v6
         with:
           python-version: "3.13"
@@ -46,5 +46,5 @@ jobs:
       - name: Audit dependencies
         run: |
           uv export --format requirements-txt --no-hashes > requirements.txt
-          pip-audit -r requirements.txt --disable-pip --no-deps || true
+          pip-audit -r requirements.txt --disable-pip --no-deps
 

README.md

@@ -52,17 +52,27 @@ print(result["decision"])  # "allow" | "deny"
 
 ### Verification Sessions
 
-Bootstrap identity for first-time agents:
+Bootstrap identity for first-time agents. The success body carries structured `next_steps` (with `action: "deliver_verify_url_and_poll"`) and a cross-merchant `agent_memory` hint. Poll responses carry `next_steps.action` from the typed `NextStepsAction` Literal (`continue_polling`, `retry_merchant_request_with_operator_token`, `use_stored_operator_token`, `create_new_session`, `verification_failed`, `contact_support`).
 
 ```python
 session = client.create_session()
 print(session["verify_url"], session["poll_url"], session["poll_secret"])
+print(session["next_steps"]["action"])  # "deliver_verify_url_and_poll"
 
 status = client.poll_session(session["session_id"], session["poll_secret"])
 if status["status"] == "verified":
     print(status["operator_token"])  # "opc_..." — use for future requests
+
+# Optional pre-association: attach the session to a known wallet or refresh KYC
+# for an existing operator credential.
+client.create_session(address="0x...")
+client.create_session(operator_token="opc_...")  # KYC refresh
 ```
 
+### Wallet resolution
+
+`assess()` responses include `resolved_operator` and `linked_wallets` — all same-operator sibling wallets (claimed via SIWE or captured via prior `associate_wallet`). The list may mix EVM addresses (`0x...` lowercased) and Solana addresses (base58, case-preserved) for cross-chain operators; merchants doing wallet-signer-match checks should accept a payment signed by any address in the list, regardless of chain. The `address` parameter on `assess()` and `get_reputation()` accepts either format — network is auto-detected from the address shape.
+
 ### Credential Management
 
 ```python
@@ -124,6 +134,8 @@ with AgentScore(api_key="as_live_...") as client:
 | `timeout`     | `10.0`                      | Request timeout (seconds)|
 | `user_agent`  | `None`                      | Prepended to the default `User-Agent` as `"{user_agent} (agentscore-py/{version})"`. Use to attribute API calls to your app. |
 
+`AgentScoreError.status` is a property aliasing `.status_code` so polyglot codebases can use the same attribute name regardless of which SDK raised the error.
+
 ## Error Handling
 
 ```python
@@ -135,6 +147,18 @@ except AgentScoreError as e:
     print(e.code, e.status_code, str(e))
 ```
 
+`AgentScoreError.details` carries the rest of the response body — `verify_url`, `linked_wallets`, `claimed_operator`, `actual_signer`, `expected_signer`, `reasons`, `agent_memory` — so callers can branch on granular denial codes without re-parsing:
+
+```python
+try:
+    client.assess("0xabc...", policy={"require_kyc": True})
+except AgentScoreError as e:
+    if e.code == "wallet_signer_mismatch":
+        print("Re-sign from one of:", e.details.get("linked_wallets"))
+    elif e.code == "token_expired":
+        print("Verify at:", e.details.get("verify_url"))
+```
+
 ## Documentation
 
 - [API Reference](https://docs.agentscore.sh)

agentscore/__init__.py

@@ -2,16 +2,24 @@
 
 from agentscore.client import AgentScore
 from agentscore.errors import AgentScoreError
+from agentscore.test_mode import AGENTSCORE_TEST_ADDRESSES, is_agentscore_test_address
 from agentscore.types import (
+    AccountVerification,
+    AgentMemoryHint,
+    AgentMemoryIdentityPaths,
     AssessResponse,
     AssociateWalletResponse,
+    CredentialCreateErrorResponse,
     CredentialCreateResponse,
     CredentialItem,
     CredentialListResponse,
+    CredentialRevokeResponse,
     DecisionPolicy,
+    DenialCode,
     EntityType,
     Grade,
     Network,
+    NextStepsAction,
     OperatorVerification,
     Reputation,
     ReputationResponse,
@@ -20,22 +28,32 @@
     SessionCreateResponse,
     SessionPollResponse,
     VerificationLevel,
+    WalletAuthRequiresSigningBody,
+    WalletSignerMismatchBody,
 )
 
 __version__ = _pkg_version("agentscore-py")
 
 __all__ = [
+    "AGENTSCORE_TEST_ADDRESSES",
+    "AccountVerification",
+    "AgentMemoryHint",
+    "AgentMemoryIdentityPaths",
     "AgentScore",
     "AgentScoreError",
     "AssessResponse",
     "AssociateWalletResponse",
+    "CredentialCreateErrorResponse",
     "CredentialCreateResponse",
     "CredentialItem",
     "CredentialListResponse",
+    "CredentialRevokeResponse",
     "DecisionPolicy",
+    "DenialCode",
     "EntityType",
     "Grade",
     "Network",
+    "NextStepsAction",
     "OperatorVerification",
     "Reputation",
     "ReputationResponse",
@@ -44,5 +62,8 @@
     "SessionCreateResponse",
     "SessionPollResponse",
     "VerificationLevel",
+    "WalletAuthRequiresSigningBody",
+    "WalletSignerMismatchBody",
     "__version__",
+    "is_agentscore_test_address",
 ]