msteams — maintainer documentation

References name symbols in the files listed rather than line numbers, so they stay valid as the code moves. For the complete, current config and tool reference, see the published Microsoft Teams & Microsoft 365 page.

Four files, no overlap:

• maintainer.md (this file) — what the plugin is, what it needs, what it exposes, which file owns what.
• architecture.md — how a message actually travels through the code, and what is persisted.
• operations.md — Azure/Teams setup, config semantics, failure modes, redeploy behaviour.
• permissions.md — every Microsoft Graph and Teams permission the plugin can need, which of the four consent surfaces it belongs to, and the checklist for standing a new tenant up the same way.

What it is

A Microsoft Teams platform adapter built on the Azure Bot Framework. Inbound Bot Framework activities arrive on the daemon webhook /hooks/msteams/messages; outbound replies, typing indicators, card edits and images go out through the Bot Connector REST API. It registers itself as an Elowen PlatformAdapter (register in index.mjs), so a Teams conversation becomes a brain channel session the same way a Discord channel or a Telegram chat does.

On top of plain chat it provides: a live tool trace edited in place, AskUserQuestion rendered as Adaptive Cards, slash commands with card pickers, per-chat model/reasoning/display overrides, image round-trips, proactive (host-initiated) pushes, and a downloadable Teams app package.

It can also write to a person first rather than only reply: it builds a people directory out of traffic it already sees, and TeamsMessagePerson opens the 1:1 chat itself. See "Proactive messaging" below and the detail in architecture.md.

What it needs to run

Credential gate

The plugin registers the app-package API route unconditionally, then requires all three of appId, appPassword and tenantId before it does anything else (register in index.mjs). With any of them missing it logs enabled but appId/appPassword/tenantId are not all configured — not connecting and returns: no platform, no webhook, no tools. Pinned by tests/msteams.test.ts (no platform and no HTTP routes without credentials, and both appear once they are configured).

Azure / Teams prerequisites

Summarised here, with the click-path in operations.md:

1. An Entra app registration (single tenant) — its Application (client) ID is appId, the directory ID is tenantId, and a client secret is appPassword.
2. An Azure Bot resource bound to that app id, with the messaging endpoint set to https://<your-domain>/hooks/msteams/messages and the Microsoft Teams channel enabled.
3. The Teams app package (downloadable from this plugin — see below) uploaded to the org's Teams app catalog so users can install the bot.

Nothing beyond the bot credentials is required for normal chat: the member and roster lookups the plugin uses for UPN/e-mail resolution are Bot Connector calls (ConnectorClient.member and ConnectorClient.members in lib/connector.mjs), not Graph calls. Microsoft Graph is a separate, optional layer — see graphLookup below.

Config fields

Declared in the configSchema of elowen-plugin.json; Czech and Slovak translations of every label and hint live in i18n/cs.json and i18n/sk.json.

The table covers the core adapter settings. Every other key in configSchema (personal-chat sign-in, Microsoft sign-in on the web login page, Microsoft 365 access, channel history, app branding, reply behaviour) is documented with its current default in the Configuration section of the published page. agentName is in configSchema; see operations.md for how empty values fall back.

Two further keys are read by the code but are not in configSchema, so the settings UI never offers them. Both are E2E seams used by tests/e2e/msteams/:

• openIdMetadataUrl (makeTokenVerifier in lib/auth.mjs), the Bot Framework OpenID metadata URL.
• oauthTokenUrl (the ConnectorClient constructor in lib/connector.mjs, read by TokenSource.tokenUrl in lib/token.mjs), the token endpoint override.

Tools it exposes

Registered by registerTools in lib/tools.mjs and declared in elowen-plugin.json. Tool availability is decided by the linked account's plugin grants and per-user tool deny-list in the users modal.

That is 9 Teams* tools; the plugin also exposes 8 Microsoft* tools for the signed-in person's delegated Microsoft 365 access (directory, SharePoint, files, Outlook, tasks, OneNote, Excel, Teams as that person) — see microsoft-365-plugin.md for the full list and their access mode. readOnlyTools covers exactly the five read-only Teams* tools listed above the table split, plus MicrosoftDirectory, whose actions are all reads. The tools that write are deliberately absent, so plan mode and read-only sub-agents withhold them. The manifest also makes every Teams tool's output visible in the transcript.

The permission behavior is pinned by tests in tests/msteams.test.ts: a project-scoped, non-owner session can reach curated and raw connector tools when the registry exposes them, while input validation such as requiring a named recipient still applies.

Proactive messaging

The Bot Connector cannot be addressed by e-mail — it only takes a conversationId. So the plugin builds a people directory (lib/directory.mjs) out of what it already sees: every inbound activity and every conversation roster carries a 29: account id, an Entra aadObjectId, a display name and (from the roster) a UPN/e-mail. No extra Microsoft permission is involved. Once a person is known, their 1:1 chat is opened once and remembered.

When the recipient has a linked Elowen account, TeamsMessagePerson first hands the text to that account's own durable channel session through the host relay control (relayToPerson in lib/proactive.mjs). The relayed turn denies the Teams send, message and file tools, the raw connector tool and every Microsoft 365 tool (MICROSOFT_TOOLS in lib/microsoftTools.mjs), and the original text is framed as untrusted JSON data. A direct send happens only when no relay reply came back, when the recipient is the sender's own account, or when the recipient is not mapped.

graphLookup is a second, optional layer (lib/graph.mjs), off by default. It exists only for people the bot has never met: it resolves an e-mail against the tenant directory and installs the Teams app for that user so a chat can be opened. It requires the application permissions User.ReadBasic.All and TeamsAppInstallation.ReadWriteSelfForUser.All with tenant admin consent, plus graphCatalogAppId for the install. What an admin must do, and what happens when they have not done it, is in operations.md.

Test tests/msteams.test.ts asserts that with the switch off nothing leaves the process on an unknown e-mail — the stubbed global fetch records zero calls.

File map

The entry's browser-safe exports are peopleForUi and notificationDestinationsForUi. Helper modules are imported directly from their owners. tests/msteams.test.ts also exercises the plugin through the host loader.

Verify it works

In the repo, from the registry repository root:

npx vitest run tests/msteams.test.ts tests/msteamsConnector.test.ts tests/msteamsAccountLinking.test.ts tests/msteamsIdentityControl.test.ts --maxWorkers=1
node scripts/check-languages.mjs                     # i18n covers every manifest string
npm run test:e2e:msteams                             # builds, then a real daemon + a fake Bot Framework

The E2E scenario (tests/e2e/msteams/run.mjs) drives a signed activity into the real webhook, checks the async threaded reply and the in-place live-trace edits, and asserts that a garbage JWT bounces with 401 without ever reaching the brain.

On a running instance:

1. The daemon log should carry msteams platform registered (webhook /hooks/msteams/messages + Teams and delegated Microsoft 365 tools) (from register in index.mjs) and then msteams webhook locally available (app <appId>); provider transport unknown (from connect in lib/adapter.mjs). This confirms local credential initialization, not provider health. msteams credential check failed: … rejects initialization and withdraws readiness; it does not claim the adapter is available.
2. GET /plugins/msteams/app-package (admin) returns the ZIP. It returns 503 while the plugin is enabled but not configured — deliberately 503 rather than 404. Any non-empty sub-path under that mount is a 404.
3. Send the bot a direct message from a mapped sender. You should see a typing indicator, then a reply threaded under your message.
4. /help in that chat answers with the command list (TeamsCommands.handleCommand in lib/commands.mjs); /stats reports the live model and context for an operator.