feat(keycardai-langchain): add Access factory API for run identity (ECO-317)

[devin-ai-integration]

Summary

ECO-317. Adds keycardai.langchain.Access, a namespace of three factories that build the KeycardIdentity for a run, so a call site names its access pattern instead of setting a field:

context=Access.on_behalf_of(caller_token) # KeycardIdentity(subject_token=...)context=Access.as_self() # KeycardIdentity(as_self=True)context=Access.impersonate("user@example.com") # KeycardIdentity(user_identifier=...)

Access is not a type and not the context schema: context_schema=KeycardIdentity is unchanged everywhere, Access.__init__ raises TypeError, and direct KeycardIdentity(...) construction keeps working with no deprecation warning (the existing test_middleware.py cases still construct it directly, which is the regression proof).

Validation lives in the factories, not the dataclass: on_behalf_of and impersonate raise ValueError on empty or whitespace-only input, while KeycardIdentity stays permissive so the middleware's own identity resolution is unaffected.

Docs and messages switched to the new spelling: the package README (quick start, access-pattern table, grant()/agrant() and fallback_identity snippets), both runnable examples and their READMEs, the middleware's missing_identity error text, get_access_context's RuntimeError, and the grant() docstring examples. access.py imports from middleware.py and not the reverse, so the middleware text changes are text only, no new import edge.

Docs generation: docs/sdk/*.mdx is generated only for keycardai.oauth, keycardai.mcp, and keycardai.mcp.integrations.fastmcp (see the sdk-ref-* recipes in the justfile). No mdx page covers keycardai.langchain, so there is nothing to regenerate for this change.

Verification: just test-package langchain passes (45 tests), coverage 92.47% against the 85 gate, ruff check and ruff format clean. just typecheck was not run: ty is not installed in this workspace and uv run --frozen ty check fails to spawn on main as well.

Open questions

• The README repeats from keycardai.langchain import Access in each standalone snippet to keep every example copy-paste runnable. Happy to drop the repeated imports if the house preference is a single import block at the top of the README.
• Out of scope here, per the ticket split: the TS package (ECO-221), any spec change, DCR (ECO-318), and deprecating direct KeycardIdentity construction.

Link to Devin session: https://app.devin.ai/sessions/4c0f387bd7364321a2283ade1cd120a9
Requested by: @Larry-Osakwe

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring