feat: operator UI for Teams agent identities + end-to-end smoke

[Weegy]

Wave W2a of epic #860, integrated from 12 parallel units into one branch. The provisioning chain built in W1a had no operator surface — everything ran through curl. This gives it one, and adds an end-to-end smoke that drives the real chain against a throwaway tenant.

Refs #866, part of #860.

What the operator can do now

Create a Teams identity for an orchestrator. Bot slug and display name are optional (the server derives both from the agent); the target team is required, because the server requires it and provisioning installs the app into it.

Read the provisioning status. The state machine (pending → app_registered → bot_created → package_built → catalog_uploaded → installed) renders as a live chain with a badge, polled while the run is non-terminal and torn down on a terminal state or unmount.

Act on a last_error. The middleware classifies the failure server-side, next to the only code that writes those sentences, and the route emits identity.last_error_detail alongside the unchanged last_error. The panel renders what happened, the captured scopes or setup fields, and what to do next — plus a link to Microsoft's admin-consent step for a consent failure. The raw English sentence is a collapsed technical detail, never the message. arm_not_configured on app_registered reads as a legitimate stop (registration-only), not as a broken agent.

Copy the teams_bot block — the channel-teams teams_bots[] entry, verbatim in parseTeamsBotsConfig key order, with the bot password present only as its opaque vault ref. The copy says plainly that pasting it into the plugin's setup field is a manual step and that nothing syncs it; automatic config sync stays a documented follow-up.

Assign a team. Installed teams, consent status, install — and an honest 501 for uninstall, because teamsProvisioner@1 publishes none and clearing team_id would only make the middleware forget an install that is still live in Teams.

Open the native Agent Builder. Persona and behaviour design stays there; the detail page deep-links to the draft that published this orchestrator's agent plugin, or to the overview when no single draft matches — never a guessed [id].

Browse chat-context memory outside dev. /memory now reads the new authenticated GET /api/v1/operator/memory/contexts/{list,file} instead of the dev-only router. The endpoint's path guard normalizes every request into the /memories/contexts subtree segment-wise (a startsWith check would have handed over /memories/contextsX) and rejects traversal before the store is touched; a second, rooted accessor cannot emit an out-of-scope path even if the first layer were wrong. The agent tier and the shared kernel are deliberately not reachable through it.

Findings fixed during integration

#	Severity	Finding	Fix
1	blocker	Two units projected identity.last_error_detail on the same key with different wire shapes (camelCase vs snake_case); a merge keeping both would have produced a duplicate object key — legal JS, last one silently wins	One owner: the camelCase TeamsProvisioningErrorDetail from classifyTeamsProvisioningError. The duplicate snake_case projection and its second classifier are deleted; the round-trip test moves onto the kept producers
2	blocker	Create form omitted team_id when left empty, but TeamsIdentityProvisionSchema declares it z.string().min(1) — the hints literally invited an input that could only 400	Target team is a required field, submit is blocked while empty, both hints corrected in en/de
3	blocker	onRerun={() => void provision({})} — the re-run action posted an empty body, so it 400'd in 100% of cases	GET …/teams-identity additionally returns identity.team_id; the re-run resends it. No recorded target → disabled button with a reason, not an action that cannot succeed
4	blocker	POST /:slug/teams wrote the new team_id before enqueueing, and the runner refuses a conflicting enqueue with a resolved {status:'rejected'} — never a rejection — so the .catch() never fired and the route answered 202 while run #1 installed into the old team	refuseConflictingTeamRetarget() answers 409 before any write, using the new TeamsProvisioningJobRunner.runningTeamId(). A refused enqueue is now recorded via recordEnqueueFailure instead of dropped
5	blocker	POST /:slug/teams-identity rewrote team_id on an already-installed row with no guard, while the runner returns early on installed — producing a read model that published an install that never happened	Same guard; the 409 covers the installed case too
6	major	The choke-point pin asserted projectTeamsBotConfig(row) against a router built without a clientSecretRef, so both sides collapsed to the default ref: dropping the second argument at the call site would have stayed green while operators pasted a config pointing at a nonexistent vault key	A second router is mounted with an overriding clientSecretRef, and the GET's appPasswordSecretRef is asserted against it
7	major	errors.throttled hardcoded {seconds} with detail.retryAfterSeconds ?? 0 — a throttle that exhausts its budget without a Retry-After header rendered "It can be retried in about 0 seconds", i.e. retry immediately at the exact moment the runner gave up	The wait line is emitted only when the server actually sent the hint
8	major	builderDraftId === null conflated "still loading" with "resolved to no match": the page stated a false negative on every load, and a click before both fetches settled dropped the deep link	An explicit draftsSettled flag; while resolving, neither the hint nor a followable fallback href renders
9	major	canInstall gated on installed.length === 0, but teams is empty for every state except installed — so the install control stayed enabled through the whole in-flight window, and the route's non-installed branch does not 409	pending_team_id === null && !running added to the conjunction
10	major	pendingHint claimed "a provisioning run is targeting team X" for every non-installed state, terminal failures included — a panel that renders neither state nor last_error had nothing to contradict it	The hint branches on running; a stopped chain gets its own copy pointing at the Teams identity section
11	major	A 404 mapped unconditionally to "This path no longer exists in the memory store", and listDir turned a root 404 into an empty branch — so an unmounted router rendered as "No agent memory yet" over a store full of context trees	A 404 on the contexts ROOT (or one that is not the router's own {"error":"not_found"} JSON) reads as an unreachable endpoint; listDir surfaces it instead of returning []
12	major	Duplicate primitive: app/_lib/teamsIdentityErrors.ts was a second last_error sentence parser, dead since the middleware started projecting the structured detail	Deleted. Its richer failure copy is what the panel renders now; one classifier, pinned by a round-trip test against the real producers
13	blocker (smoke)	pollUntilTerminal honoured last_error_detail from the FIRST poll, but nothing clears a previous run's last_error on a re-run — the exact flow the handoff prescribes (fix the ARM fields, re-run) could report a green "registration only" for a run that had done nothing	The pre-POST snapshot is kept; no terminal verdict is accepted until the row has demonstrably changed since it. The arm_not_configured branch is constrained to app_registered/bot_created, as its own doc comment already claimed
14	major (smoke)	The production-host refusal compared url.host, which includes the port — https://app.omadia.ai:8443 slipped past the guard documented as having no override	Compares url.hostname
15	major (smoke)	assertMessagingEndpointBound accepted any status >= 400 && !== 404 as proof that Bot Framework auth is enforced, so a 500 from the deliberately malformed probe passed identically to a clean 401	Only 401/403 (or 400 for a rejected malformed activity) pass; 5xx is a hard failure with the body echoed

Two units were flagged clean (smoke-hub-artifact-ingest, operator-memory-contexts-endpoint); the hub-artifact unit produced no tracked changes at all, since the smoke scripts are gitignored.

The E2E smoke — not in this diff, on purpose

middleware/scripts/smoke-teams-e2e.ts (stage 1) and smoke-teams-e2e-stage2.ts are matched by middleware/scripts/smoke-*.ts in .gitignore and are deliberately absent from this PR — they hit byte5-internal endpoints. npm run smoke:teams-e2e is registered in middleware/package.json; stage 1 imports and calls stage 2.

What it does. Stage 1 downloads the real published plugin artifact from the hub and runs it through the production extractZipToDir. Stage 2 then drives the live chain: POST /api/v1/operator/agents/:slug/teams-identity (202), polls GET …/teams-identity through the full state machine, asserts the teams_bot projection and teams_app_id are complete, and probes the new bot's /api/teams/<botSlug>/messages route with an unsigned payload to prove it is live and rejects it.

How to run it against a throwaway environment.

cd middleware
export SMOKE_MW_BASE_URL=https://<scratch-host>          # no default exists
export SMOKE_TEAMS_E2E_TARGET=<scratch-host>             # echo back the exact host
npm run smoke:teams-e2e

It needs the M365 connector plugin installed and active in that environment, admin consent granted in the scratch tenant, and the ARM setup fields configured for the full chain — without them the run legitimately stops at app_registered and reports success-with-caveat. docs/middleware-agent-handoff.md carries the long form.

Why it must never run against production. A provisioning call persists an agent_teams_identities row and creates real Entra app registrations, Azure bot resources and Teams catalog entries in the target tenant — none of which this script can undo, and teamsProvisioner@1 publishes no uninstall. The guard is fail-closed and layered: no default target, an explicit opt-in, a host the caller has to echo back verbatim, a hostname-matched refusal of known production hosts with no override switch, and an abort when the shell carries a non-scratch DATABASE_URL.

Known limitation. The smoke does not send a genuine Bot Framework turn — signing one needs the freshly created app's secret, which never leaves the connector's vault. The visible reply in Teams stays a one-line manual step the run prints out.

Gates

Gate	Result
middleware && npm run typecheck	clean
middleware && npm test	7733 tests, 0 fail (16 skipped)
web-ui && npm run lint	0 errors (51 pre-existing warnings, none in this diff)
web-ui && npm run typecheck	clean
web-ui && npm run test	107 files, 964 tests, 0 fail
web-ui && npm run i18n:check	OK — 4050 keys, en + de

One flake was observed and is documented rather than papered over: AgentToolGrants.test.tsx ("shows the latest grant epoch in the heading summary") failed once in a full run and passed in every subsequent full run, in an isolated run, and in a run of its whole directory. This diff touches neither that component nor its test — the known cross-file pollution class, not a regression from this branch.

Notes for review

• No schema change and no migration anywhere in this wave. identity.team_id and identity.last_error_detail are both additive projections of columns that already exist.
• agent_teams_identities keeps ONE team_id (migration 0049), documented as resume evidence. The installed-teams read model is therefore derived, never plural, and it refuses to publish a team the runner did not actually install into — which is what findings 4 and 5 were about.
• No secret material anywhere: appPasswordSecretRef is the opaque teams_bot_password:<appId> handle, and the shape check drops the whole block rather than render a value that is not ref-shaped.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}