feat(agents): add identity storage and validation contracts

[joshua-berri]

TLDR

Problem this solves:

• Identity ownership needs durable, validated storage

How it solves it:

• Add identity records, immutable bindings and validation contracts

Adds the schema migration, typed identity contracts and identity persistence helpers. Registration and Entra request authentication are activated by later PRs, keeping this prerequisite independently reviewable

The review follow-up reuses UserApiKeyCache for positive Entra application-to-agent lookup hints. Cache hits still load current agent policy and delegated subjects from the writer. Missing identities and authorization decisions are never cached. PR #43722 activates the shared-cache wiring

Stack 1/9. Targets main. Review size: 1,835 additions + deletions, including 744 test lines and 1,091 other lines, measured against the immediate parent

User Flow

Before: the immediate parent provides the following experience

1. Open the existing agent registration screen
2. Continue using the existing registration workflow

After: this PR provides the following experience

1. Open the existing agent registration screen
2. Continue using the existing workflow; this prerequisite adds no controls

Relevant issues

Splits the approved scope from #43149 into the smaller review stack below. The nine PRs collectively replace #43149, #43229, #43230 and #43459; this PR covers only the scope described above. Original PRs remain open pending replacement review

1. feat(agents): add identity storage and validation contracts #43720
2. feat(agents): enforce authoritative agent permissions #43721
3. feat(agents): authenticate Entra identities and delegated requests #43722
4. feat(agents): add identity registration and dashboard controls #43723
5. feat(agents): enforce agent budgets #43724
6. feat(scim): add source storage and provisioning contracts #43725
7. feat(scim): add atomic agent and human provisioning operations #43726
8. feat(scim): activate source-bound provisioning and authorization #43727
9. feat(scim): add provisioning source dashboard controls #43728

Affected release

Linear ticket

Resolves LIT-8956

Pre-Submission checklist

• I have added meaningful tests
• Affected tests pass locally
• My PR passes all required CI/CD checks
• This PR isolates the stated part of the approved stack
• Greptile confidence is at least4/5 before maintainer review

Verification

Current head 605aa2e788fc75b371b458a51a39b566e9cefaf7, merge base 7e383c9f6ace54463b6c06a115b5950822cb0913

416 affected tests pass. The existing spend-log fixture now expects the five attribution fields introduced by this PR. The new read-count regression failed on the previous tip with two identity lookups, then passed with one lookup across two resolutions and two authoritative policy reads. Warm-cache tests cover disabled/deleted agents, inactive/rebound identities, role/mode changes, missing subjects and writer failures. Newly registered identities remain immediately discoverable because misses are not cached

Canonical whole-tree Ruff, test-tree lint, formatting, strict-rule, type-discipline, test-quality, basedpyright budget, E2E type, operation-boundary and import checks pass without increasing budgets. Existing Pydantic notices and an unrelated test-tree noqa warning remain

Changed executable-line coverage is 349/349 for the whole PR and 23/23 for this repair. Touched-function branch coverage is 78/80 for the whole PR, including two pre-existing API-key validator branches outside this repair; the repair's touched functions cover 26/26 branches. These are not repository-wide coverage percentages

Current-tip Veria and Cursor Bugbot both pass with no findings or annotations. Both original review threads were resolved by their respective bots. Greptile explicitly accepted the retained authoritative reads and withdrew its finding. Its summary still describes the prior tip, so current-tip summary confirmation remains pending

Independent PostgreSQL and Redis verification passed at this exact tip. The spend-log fixture failure is fixed locally. The same four external Google OpenAPI failures occurred before this repair at e3209bad8a; that test and its implementation are unchanged from the merge base. Required CI, completed hosted coverage, and contributor-agreement evidence remain pending

The e171b8c follow-up reuses UserApiKeyCache and get_management_object_ttl for positive application-to-agent lookup hints; #43722 passes the shared cache at both authentication sites. Repeated resolution now performs one identity lookup across two requests while re-reading policy twice. Policy and delegated-subject reads intentionally remain authoritative: caching them by TTL would delay disablement, role/mode changes and subject revocation across workers. Existing get_user_object also performs authoritative email-backfill reads on applicable cache hits (auth_checks.py:2582-2643), so the existing helper pattern does not guarantee zero request-time SQL. Greptile accepted this bounded optimization under the explicit freshness requirement and withdrew the finding, as linked above.

Screenshots / Proof of Fix

This foundation PR activates no endpoint. Independent source builds used isolated PostgreSQL databases with 190 migrations and the existing UserApiKeyCache, both in-memory and backed by Redis. No LLM call is needed for storage verification. Harness and SQL logs are retained in the verification artifacts

Before (7e383c9f6ace54463b6c06a115b5950822cb0913)

1. Inspect the identity-store module and AgentIdentity schema at the merge base
2. Neither exists; managed identity storage is unavailable

After (605aa2e788fc75b371b458a51a39b566e9cefaf7)

1. In the isolated source checkout, run CACHE_MODE=redis DATABASE_URL=<isolated-database> .venv/bin/python cache_store_live.py S1-605aa2e7-redis, then repeat with CACHE_MODE=memory
2. Warm the identity lookup and resolve five autonomous/delegated requests. Compared with previous tip e3209bad8a, identity lookup calls drop from five to zero and PostgreSQL identity SELECTs from ten to five. Current policy and delegated subject reads, plus authentication writes, remain unchanged
3. Resolve from a second process: Redis reuses the shared hint with zero identity lookup calls; an independent in-memory cache requires one cold lookup
4. Disable the agent, deactivate its identity, change its required role/mode or delete the verified human: each denies access immediately. Actual agent, identity and subject table outages fail closed. Unknown clients remain uncached and resolve immediately after binding
5. Both memory and Redis harness runs exit zero with empty stderr, importing this exact source commit (processes 58182/58297 and 58880/58999)

For Bugbot's reassignment concern, the separate registration follow-up at 60915a7b672e30d239dfc5da03f33a3738924ab9 passed 17 live checks: another agent's POST/PUT/PATCH claim to an owned application returns HTTP 409, while same-owner reactivation succeeds. This is guard evidence at that separate commit, not a combined cache-plus-registration build. SQL-only reassignment at the current tip denies access until hint expiry and never admits the old agent

Type

New Feature

Caveats (if any)

Medium

• Runtime cache wiring is activated by feat(agents): authenticate Entra identities and delegated requests #43722
• Authoritative policy/subject reads and authentication writes remain intentional

Final Attestation

• Final current-tip CI, coverage and automated review checks complete

[greptile-apps]

Confidence Score: 5/5

[Critical risk] Adds database schema and identity validation for agent authentication.

The PR appears safe to merge based on the reviewed changes and resolved prior finding.

Summary

This PR adds managed-agent identity storage, validation contracts, and persistence helpers without activating an identity-writing endpoint. The change since the previous review updates a spend-log test fixture to match the new metadata fields.

_{Reviews (3) · Last reviewed commit: "test(agents): include identity attributi..."}

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_agent_split_identity_contracts (605aa2e) with main (d463049)}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[joshua-berri]

@greptileai Please reassess the positive lookup cache and retained authoritative reads at e171b8c; current verification details are in the description

[joshua-berri]

bugbot run. Please review the current identity lookup cache changes, including warm-cache revocation and authoritative policy failure behavior

[cursor]

Stale Bugbot comment from a previous run.

[joshua-berri]

@greptileai Please review 605aa2e. Production code is unchanged; the description documents live cache results, authoritative-read rationale, and the registration ownership guard

[joshua-berri]

bugbot run. Please reassess the cross-agent reassignment finding using the documented live HTTP 409 evidence and registration ownership guard at this tip

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 605aa2e. Configure here.}