Let CreateSessionOnMissing mint a sign_in session (#133)

## Summary

`CreateSessionOnMissing` gains an optional `kind` (`"kyc" | "sign_in"`)
that rides through to `POST /v1/sessions`. A gate running an empty
compliance policy that only needs an account to key durable state on (a
prepaid balance, say) could previously auto-mint only the KYC kind,
which asks the buyer for identity documents nothing in that merchant
ever checks; `sign_in` is registration-only and still yields an operator
token. When the kind is `sign_in` the minted denial carries a `message`
describing an account sign-in instead of the KYC default, so a merchant
using the default 403 body does not tell the agent something false. When
`kind` is `None` nothing changes: the body omits it and the API default
applies. Parity with the node library change of the same day. Takes
`agentscore-py` 2.6.9, which carries the option.

## Type of change

- [ ] Bug fix (no breaking change)
- [x] New feature (no breaking change)
- [ ] Breaking change (existing callers must update)
- [ ] Docs, tests, or internal maintenance only

## Public API

`CreateSessionOnMissing.kind: Literal["kyc", "sign_in"] | None = None`
(new, optional). No migration for existing callers.

## Test plan

`tests/test_sessions.py`: a new case asserts the POST body carries
`kind: "sign_in"` and that the returned reason's `message` talks about
signing in with an AgentScore account and not about KYC; the existing
forwarding case additionally asserts `kind` is absent when unset.
Locally: `uv run ruff check`, `uv run ruff format --check`, `uv run ty
check agentscore_commerce/`, `uv run pytest` (1869 passed, 4 skipped,
95.37% coverage against the 95% floor).

## Checklist

- [x] Tests cover the new behavior, and the suite passes locally
- [x] Lint, format, and type checks pass
- [x] Docs and README examples updated if the public surface changed
- [x] No secrets, credentials, or personal data in the diff or the tests

Worked with Varun. Version bumped to 2.9.0; the tag follows the merge.
The README carries no `CreateSessionOnMissing` example today, so the
field's docstring is its documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: vvillait88

agentscore_commerce/identity/sessions.py

@@ -7,7 +7,7 @@
 import logging
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
-from typing import Any, cast
+from typing import Any, Literal, cast
 
 from agentscore import AgentScore, AgentScoreError
 
@@ -46,6 +46,13 @@ class CreateSessionOnMissing:
     base_url: str = "https://api.agentscore.com"
     context: str | None = None
     product_name: str | None = None
+    # Session kind sent to POST /v1/sessions. "kyc" (the API default) runs identity
+    # verification; "sign_in" is registration-only (the buyer signs in with an AgentScore
+    # account, no identity documents) and mints a sign_in-scoped credential. Use it when the
+    # gate runs with an EMPTY compliance policy and only needs an account to key state on
+    # (a prepaid balance, say): a KYC session there asks for documents nothing will check.
+    # The denial's default error.message follows the kind.
+    kind: Literal["kyc", "sign_in"] | None = None
     # Per-request override of context / product_name. Receives the framework request
     # object; returns a dict with optional "context" and/or "product_name" keys.
     get_session_options: Callable[[Any], _Hookable] | None = None
@@ -91,12 +98,22 @@ def _resolved_session_options(cfg: CreateSessionOnMissing, dynamic: Any) -> dict
         options["context"] = cfg.context
     if cfg.product_name is not None:
         options["product_name"] = cfg.product_name
+    if cfg.kind is not None:
+        options["kind"] = cfg.kind
     return _apply_dynamic_options(options, dynamic)
 
 
+SIGN_IN_REQUIRED_MESSAGE = (
+    "Sign-in is required to access this resource. Visit verify_url to sign in with an "
+    "AgentScore account (no identity documents), then poll poll_url for the operator token "
+    "and retry."
+)
+
+
 def _session_denial_reason(
     data: dict[str, Any],
     extra: dict[str, Any] | None = None,
+    kind: Literal["kyc", "sign_in"] | None = None,
 ) -> DenialReason | None:
     # Validate required fields before trusting the response. A misbehaving (or
     # mocked-wrong) API could 200 without session_id/poll_secret/verify_url, which
@@ -116,6 +133,9 @@ def _session_denial_reason(
     agent_instructions = json.dumps(next_steps) if next_steps else None
     return DenialReason(
         code="identity_verification_required",
+        # The per-code default message talks about KYC, which a sign_in session never runs;
+        # say what this session actually asks for so a merchant's default 403 is not a lie.
+        message=SIGN_IN_REQUIRED_MESSAGE if kind == "sign_in" else None,
         verify_url=data["verify_url"],
         session_id=data["session_id"],
         poll_secret=data["poll_secret"],
@@ -171,7 +191,7 @@ async def try_create_session_denial_reason(
             except Exception as err:
                 logger.warning("on_before_session hook failed: %s", err)
 
-        return _session_denial_reason(data, extra)
+        return _session_denial_reason(data, extra, cfg.kind)
     except Exception:
         return None
 
@@ -219,6 +239,6 @@ def try_create_session_denial_reason_sync(
             except Exception as err:
                 logger.warning("on_before_session hook failed: %s", err)
 
-        return _session_denial_reason(data, extra)
+        return _session_denial_reason(data, extra, cfg.kind)
     except Exception:
         return None

pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-commerce"
-version = "2.8.3"
+version = "2.9.0"
 description = "Agentic commerce SDK for Python: identity middleware (FastAPI, Flask, Django, AIOHTTP, Sanic, ASGI) + payment helpers + 402 builders + discovery + Stripe multichain. The full merchant-side toolkit for AgentScore-powered agentic commerce."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.11"
 keywords = ["agentscore", "agent-commerce", "agentic-payments", "402", "x402", "mpp", "machine-payments-protocol", "fastapi", "starlette", "flask", "django", "aiohttp", "sanic", "middleware", "trust", "reputation", "kyc", "identity", "stripe", "tempo", "solana", "base", "ai-agent"]
 dependencies = [
     "httpx>=0.25.0,<1.0.0",
-    "agentscore-py>=2.6.8",
+    "agentscore-py>=2.6.9",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",

tests/test_sessions.py

@@ -81,6 +81,24 @@ def test_forwards_context_and_product_name(self):
         body = json.loads(route.calls[0].request.content)
         assert body["context"] == "purchase_flow"
         assert body["product_name"] == "Example Merchant"
+        assert "kind" not in body
+
+    @respx.mock
+    def test_forwards_kind_and_swaps_the_kyc_message_for_sign_in(self):
+        route = respx.post(SESSIONS_URL).mock(return_value=httpx.Response(200, json=SESSION_RESPONSE))
+        reason = try_create_session_denial_reason_sync(
+            CreateSessionOnMissing(api_key="ask_test", kind="sign_in"),
+            user_agent="agentscore-commerce/1.0",
+        )
+        import json
+
+        body = json.loads(route.calls[0].request.content)
+        assert body["kind"] == "sign_in"
+        assert reason is not None
+        assert reason.code == "identity_verification_required"
+        assert reason.message is not None
+        assert "sign in with an AgentScore account" in reason.message
+        assert "KYC" not in reason.message
 
     @respx.mock
     def test_omits_context_and_product_name_when_not_provided(self):