[3/5] Add account-bound Graph audience discovery

[rebova-microsoft]

Description

Add read-only audience discovery using an independent Microsoft Graph resource token bound to the intended authoring tenant and account.

Current diff

• Search display name OR mail in one initial Graph query, preserving escaping, stable deduplication and eligibility policy.
• Keep the limits of 50 candidates per page, three pages, and 20 eligible results, with explicit exhaustion reporting.
• Preserve bounded metadata caching and rejected-token invalidation. Log only predefined benign sign-in codes or a fixed unknown marker.

Feature contract

Supported delegated credentials must establish the same tenant/account context. Missing or incompatible token claims fail closed; no tenant-only relaxation, borrowed resource token, or identity-probing workaround is added.

Stack and dependency

This is slice 3/5. Head: users/rebova/org-announcements-review-audience. Base: users/rebova/org-announcements-review-contracts. The current diff is only this slice against its immediate predecessor; these are stacked review chunks, not parallel PRs against the integration branch.

Bootstrap prerequisite: #262 merged into release/planner-landing-page on September 10, 2026. This stack remains pinned to cacb1bec056428809f1ccb0383561190d516bee4, which is an ancestor of merge commit 8a04f5f40f334e729a3497877edca655730f1be2. Unchanged prerequisite work is excluded from this slice. No rewrite is needed solely to account for that merge. The future release target remains TBD and its final promotion baseline must be confirmed separately.

Testing

166 Python tests passed from the clean committed slice, covering Graph lookup, escaping, eligibility, identity matching, cache lifetime, and authentication diagnostics. Ruff and syntax checks passed; the MCP runtime was not yet present.

Local execution used Python 3.13.15. Python 3.11 GitHub Actions validation is pending; no local 3.11 pass is claimed.

Readiness

• Live Graph, authoring-service, hosted-widget, and end-to-end integration checks are deferred and remain required before rollout.
• This is not release approval and performs no deployment. The future release branch is still TBD.
• The prerelease integration branch remains baseline-only until reviewed chunks are merged through the normal review process.
• Relevant offline tests and static checks pass.
• Python 3.11 CI results.
• Authorized live integration and end-to-end validation.

[microsoft-github-policy-service]

rebova-microsoft please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

Contribution License Agreement

This Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
and conveys certain license rights to Microsoft Corporation and its affiliates (“Microsoft”) for Your
contributions to Microsoft open source projects. This Agreement is effective as of the latest signature
date below.

1. Definitions.
   “Code” means the computer software code, whether in human-readable or machine-executable form,
   that is delivered by You to Microsoft under this Agreement.
   “Project” means any of the projects owned or managed by Microsoft and offered under a license
   approved by the Open Source Initiative (www.opensource.org).
   “Submit” is the act of uploading, submitting, transmitting, or distributing code or other content to any
   Project, including but not limited to communication on electronic mailing lists, source code control
   systems, and issue tracking systems that are managed by, or on behalf of, the Project for the purpose of
   discussing and improving that Project, but excluding communication that is conspicuously marked or
   otherwise designated in writing by You as “Not a Submission.”
   “Submission” means the Code and any other copyrightable material Submitted by You, including any
   associated comments and documentation.
2. Your Submission. You must agree to the terms of this Agreement before making a Submission to any
   Project. This Agreement covers any and all Submissions that You, now or in the future (except as
   described in Section 4 below), Submit to any Project.
3. Originality of Work. You represent that each of Your Submissions is entirely Your original work.
   Should You wish to Submit materials that are not Your original work, You may Submit them separately
   to the Project if You (a) retain all copyright and license information that was in the materials as You
   received them, (b) in the description accompanying Your Submission, include the phrase “Submission
   containing materials of a third party:” followed by the names of the third party and any licenses or other
   restrictions of which You are aware, and (c) follow any other instructions in the Project’s written
   guidelines concerning Submissions.
4. Your Employer. References to “employer” in this Agreement include Your employer or anyone else
   for whom You are acting in making Your Submission, e.g. as a contractor, vendor, or agent. If Your
   Submission is made in the course of Your work for an employer or Your employer has intellectual
   property rights in Your Submission by contract or applicable law, You must secure permission from Your
   employer to make the Submission before signing this Agreement. In that case, the term “You” in this
   Agreement will refer to You and the employer collectively. If You change employers in the future and
   desire to Submit additional Submissions for the new employer, then You agree to sign a new Agreement
   and secure permission from the new employer before Submitting those Submissions.
5. Licenses.

• Copyright License. You grant Microsoft, and those who receive the Submission directly or
  indirectly from Microsoft, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license in the
  Submission to reproduce, prepare derivative works of, publicly display, publicly perform, and distribute
  the Submission and such derivative works, and to sublicense any or all of the foregoing rights to third
  parties.
• Patent License. You grant Microsoft, and those who receive the Submission directly or
  indirectly from Microsoft, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license under
  Your patent claims that are necessarily infringed by the Submission or the combination of the
  Submission with the Project to which it was Submitted to make, have made, use, offer to sell, sell and
  import or otherwise dispose of the Submission alone or with the Project.
• Other Rights Reserved. Each party reserves all rights not expressly granted in this Agreement.
  No additional licenses or rights whatsoever (including, without limitation, any implied licenses) are
  granted by implication, exhaustion, estoppel or otherwise.

6. Representations and Warranties. You represent that You are legally entitled to grant the above
   licenses. You represent that each of Your Submissions is entirely Your original work (except as You may
   have disclosed under Section 3). You represent that You have secured permission from Your employer to
   make the Submission in cases where Your Submission is made in the course of Your work for Your
   employer or Your employer has intellectual property rights in Your Submission by contract or applicable
   law. If You are signing this Agreement on behalf of Your employer, You represent and warrant that You
   have the necessary authority to bind the listed employer to the obligations contained in this Agreement.
   You are not expected to provide support for Your Submission, unless You choose to do so. UNLESS
   REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING, AND EXCEPT FOR THE WARRANTIES
   EXPRESSLY STATED IN SECTIONS 3, 4, AND 6, THE SUBMISSION PROVIDED UNDER THIS AGREEMENT IS
   PROVIDED WITHOUT WARRANTY OF ANY KIND, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY OF
   NONINFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
7. Notice to Microsoft. You agree to notify Microsoft in writing of any facts or circumstances of which
   You later become aware that would make Your representations in this Agreement inaccurate in any
   respect.
8. Information about Submissions. You agree that contributions to Projects and information about
   contributions may be maintained indefinitely and disclosed publicly, including Your name and other
   information that You submit with Your Submission.
9. Governing Law/Jurisdiction. This Agreement is governed by the laws of the State of Washington, and
   the parties consent to exclusive jurisdiction and venue in the federal courts sitting in King County,
   Washington, unless no federal subject matter jurisdiction exists, in which case the parties consent to
   exclusive jurisdiction and venue in the Superior Court of King County, Washington. The parties waive all
   defenses of lack of personal jurisdiction and forum non-conveniens.
10. Entire Agreement/Assignment. This Agreement is the entire agreement between the parties, and
    supersedes any and all prior agreements, understandings or communications, written or oral, between
    the parties relating to the subject matter hereof. This Agreement may be assigned by Microsoft.

[rebova-microsoft]

File-by-file walkthrough of audience-group discovery, display metadata, and supporting tests. This is an explanatory review only, not code approval or resolution of existing feedback. This PR adds a directory client; selecting the target ESS agent remains separate, and MCP announcement runtime wiring is not added here.

[rebova-microsoft]

Walkthrough — Add directory-client coverage to the existing job.

This one-line change adds test_graph_directory.py to the Org Announcements test command introduced in the previous PR. The job now selects directory behavior alongside authoring requests and draft models, using the same Python setup and dependencies. It extends the intended automated checks; it neither performs a live Graph lookup nor establishes that the tests have passed.

[rebova-microsoft]

Walkthrough — Find audience groups and turn stored IDs into readable labels.

This client discovers announcement audiences, not the target ESS agent; shared core agent list/search handles that separate choice.

• Authentication uses a separate Graph resource token for the same authoring tenant and account, reusing the shared cache. Acquisition is lazy and runs off the async event loop. Local tid/oid checks guard identity consistency; they are not authorization. Tokens without readable matching claims are rejected. The services remain responsible for authorization and save validity.
• search_groups combines display-name and email search in one initial request, then follows pages within bounds: at most 20 eligible results or three pages. It keeps first-seen order, removes duplicate results, and distinguishes exhausted results from a capped search. Eligibility includes non-dynamic security groups, mail-enabled security groups, and classic distribution lists; Unified and dynamic-membership groups are excluded.
• resolve_groups batches IDs and caches only successful metadata for five minutes, with a 512-entry cap. build_audience_metadata restores each saved audience's order and repeated entries. Unresolved or unsupported IDs stay present as invalid entries labeled “Unavailable group,” rather than disappearing.
• A 401 clears the rejected credentials and metadata cache so a later call can acquire credentials again; the failed request is not automatically replayed.

This supplies directory data and error handling for later wiring, not UI controls, announcement persistence, or a running MCP announcement server.

[rebova-microsoft]

Walkthrough — Extend isolated loading for directory tests.

The new directory-specific helper loads client, drafts, and graph_directory_client through the existing feature-isolated importer. This keeps the directory tests aligned with the same announcement model/client objects while avoiding clashes with similarly named modules in other feature folders. It deliberately stops short of loading telemetry or the MCP server, so this PR can exercise its directory layer without depending on later runtime wiring.

[rebova-microsoft]

Walkthrough — Check audience lookup rules and recovery with controlled responses.

The tests supply fake groups, token claims, authentication results, and HTTP responses. Search cases exercise one combined name/email query, eligible group types, escaping, paging bounds, and duplicate removal. Metadata cases check expiry, bounded positive caching, readable fallback labels, and preservation of stored order and repeated IDs. Authentication cases check lazy acquisition, matching tenant/account selection, rejection of opaque or missing-account tokens, and recovery on a later call after a 401 without replaying the failed request. These are local behavior checks, not live Graph consent or authorization verification.