@patimweb/pi-teams 1.0.0 → 1.2.0

package/README.md

@@ -19,7 +19,9 @@ pi install /path/to/pi-teams
 
 ## Quick start
 
-1. **Register an app in Entra ID** (once per organization — see below).
+1. **Register an app in Entra ID** (once per organization) — the step-by-step
+   walkthrough, including the redirect URI and public-client settings that sign-in
+   needs, is in [docs/entra-app-registration.md](docs/entra-app-registration.md).
 2. **Configure the account:**
    ```
    teams_setup:
@@ -28,16 +30,84 @@ pi install /path/to/pi-teams
      clientId: <application (client) ID>
      setDefault: true
    ```
-3. **Sign in:** run `/teams-login`. pi shows a code and a URL; open it, enter
-   the code, sign in as yourself.
+3. **Sign in:** run `/teams-login`. Your browser opens at the Microsoft
+   sign-in page and closes itself when you are done — nothing to type.
 4. **Check it works:** `/teams-status`, then `/teams-inbox`.
 
+Full walkthrough with the exact portal paths: **[docs/entra-app-registration.md](docs/entra-app-registration.md)**.
+
+---
+
+## Listen mode
+
+Off by default. When it is on, pi polls your chats and turns an incoming message
+into a prompt it answers — as you, in the chat it arrived in.
+
+```
+/teams-listen on        # switch it on for the session's account
+/teams-listen status    # what is configured, and what is running right now
+/teams-listen off
+```
+
+```json
+"watch": {
+  "enabled": true,
+  "intervalSeconds": 60,
+  "chats": ["Anna*", "Vertrieb*"],
+  "from": ["anna.schmidt@contoso.com"],
+  "mentionOnly": false,
+  "cooldownSeconds": 300,
+  "maxTriggersPerHour": 10
+}
+```
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `enabled` | `false` | whether the watcher runs |
+| `intervalSeconds` | `60` | seconds between polls (minimum 15) |
+| `chats` | `[]` | **where** pi listens: glob patterns matched against topic, label, chat ID and participant names. Empty means every recent chat. |
+| `from` | `[]` | **who** pi listens to: glob patterns matched against display name, UPN and e-mail. Empty means any sender. |
+| `mentionOnly` | `false` | only wake where you are mentioned |
+| `cooldownSeconds` | `300` | stay quiet in a chat after waking pi for it |
+| `maxTriggersPerHour` | `10` | hard cap on wakes per hour |
+
+Set it globally, or per account (the account level wins field by field).
+`teams_watch` writes the same keys; `/teams-listen` writes to the session's
+account.
+
+What it does, and what it deliberately does not:
+
+- **Costs a model turn per wake.** That is what the filters and the hourly cap
+  are for — narrow `chats` and `from`, and enable it for a handful of
+  conversations rather than the whole company.
+- **Never answers the backlog.** The first poll records what is there; only what
+  arrives afterwards wakes pi.
+- **Never wakes for its own messages.** pi posts as you, so its own reply comes
+  back as "my own message" and stops the loop.
+- **Respects the read rules.** A chat excluded by `permissions.read.chats` is
+  not even polled.
+- **Does not bypass the safety model.** A reply it decides to send goes through
+  the same safety level and scope rules as one you asked for. At `confirm` you
+  approve each one; for hands-free answers, narrow `permissions.write.chats` and
+  set `safetyLevel: open` — deliberately, and on an account where you mean it.
+- **Chats only, not channels.** Channel polling needs `ChannelMessage.Read.All`
+  (admin consent) and multiplies the calls; answering in channels stays a
+  requested action.
+
+Why polling and not a webhook: Graph change notifications for chats need a
+publicly reachable HTTPS endpoint plus subscription renewal, which a laptop on a
+home network cannot offer. Polling costs one `/me/chats` call per interval and
+works anywhere.
+
 ---
 
 ## Entra ID app registration
 
-pi signs in with the OAuth 2.0 **device authorization grant**, so it never sees
-your password and your MFA works normally.
+Full walkthrough: **[docs/entra-app-registration.md](docs/entra-app-registration.md)**.
+The short version, with the two settings that sign-in actually depends on:
+
+pi signs in as you with a delegated OAuth 2.0 flow — the browser opens, you sign
+in with your own credentials and MFA, and pi never sees your password.
 
 ### 1. Create the registration
 
@@ -76,41 +146,122 @@ Without this, sign-in fails with `AADSTS7000218`.
 | `Calendars.ReadWrite` | reading and creating calendar events |
 | `OnlineMeetings.ReadWrite` | Teams meeting links |
 | `Files.Read.All`, `Sites.Read.All` | channel files |
-| `offline_access` | staying signed in |
 
-Some of these require **admin consent**. Click *Grant admin consent* if you
-can, or ask an administrator. `teams_doctor` reports exactly which scopes were
-granted and which were not, so you never have to guess from a 403.
+`openid`, `profile` and `offline_access` are not listed: MSAL always requests
+them and rejects them in an explicit scope list, so the lasting sign-in they
+buy is automatic.
+
+### 4. Add the redirect URI for the browser sign-in
+
+**Authentication** → **Add a platform** → **Mobile and desktop applications** →
+tick `http://localhost`.
+
+MSAL picks a free loopback port at sign-in time, and Entra accepts any port on
+localhost for a public client, so this one entry covers every run. If your
+tenant insists on an exact URI, register e.g. `http://localhost:3000` and set
+`loopbackPort: 3000` on the account.
+
+---
+
+## Who has to approve what
+
+Two separate hurdles, and only one of them normally needs an administrator.
 
-To request fewer permissions, set `scopes` on the account — see below.
+### Creating the registration
 
-### 4. Guest and customer tenants
+By default any member of the tenant may register an application (Entra ID →
+**User settings** → *Users can register applications*). Where that is switched
+off, the least-privileged role that can do it is **Application Developer**;
+Cloud Application Administrator and Application Administrator also work.
+Changing *Allow public client flows* and adding the redirect URI need no extra
+role once the registration is yours.
+
+### Consenting to the permissions
+
+Only two of the default scopes require **admin consent**:
+
+| Scope | Consent | What you lose without it |
+|-------|---------|--------------------------|
+| `ChannelMessage.Read.All` | **admin** | reading channel messages and threads |
+| `ChannelMember.Read.All` | **admin** | channel member lists |
+| `ChannelMessage.Send` | user | — |
+| `Chat.ReadWrite`, `ChatMessage.Send` | user | — |
+| `Team.ReadBasic.All`, `Channel.ReadBasic.All` | user | — |
+| `User.Read`, `User.ReadBasic.All` | user | — |
+| `Presence.ReadWrite`, `Presence.Read.All` | user | — |
+| `Calendars.ReadWrite`, `OnlineMeetings.ReadWrite` | user | — |
+| `Files.Read.All`, `Sites.Read.All` | user | — |
+
+Posting in a channel needs no admin; *reading* the channel does. Microsoft
+treats bulk reading of channel content as the more sensitive right.
+
+**Without an administrator**, drop the two admin-consent scopes and everything
+else still works — chats in full, posting and replying in channels, presence,
+calendar, meetings and directory lookup:
+
+```json
+"scopes": [
+  "User.Read", "User.ReadBasic.All",
+  "Team.ReadBasic.All", "Channel.ReadBasic.All", "ChannelMessage.Send",
+  "Chat.ReadWrite", "ChatMessage.Send",
+  "Presence.ReadWrite", "Presence.Read.All",
+  "Calendars.ReadWrite", "OnlineMeetings.ReadWrite",
+  "Files.Read.All", "Sites.Read.All"
+]
+```
+
+One caveat: if the tenant has *Users can consent to applications* switched off,
+even the user-consentable scopes need an administrator — usually through the
+admin consent request workflow.
+
+`teams_doctor` reports exactly which scopes were actually granted, so a missing
+consent shows up as a named permission rather than a 403.
+
+### Guest and customer tenants
 
 For a tenant that is not your own:
 
 - the registration must be **multitenant**,
 - your account must be a guest in that tenant,
-- an administrator there consents to the app once.
+- an administrator **of that tenant** consents to the app once.
 
-Then add it as a tenant beneath your account (`parentAccount`) and sign in
-again against it.
+In practice this is the bigger hurdle, not your own tenant. Once it is done,
+add the tenant beneath your account (`parentAccount` in `teams_setup`) and sign
+in against it.
 
 ---
 
-## Acting as a user vs. app-only
+## How the sign-in works
+
+`teams_login` uses MSAL (`@azure/msal-node`) and picks the flow that fits the
+machine:
 
-| | `device-code` (default) | `client-credentials` |
-|---|---|---|
-| Identity | you | the application |
-| Sign-in | once, interactive | none |
-| Reading chats/channels | yes | only via protected APIs |
-| **Sending messages** | **yes** | **no** — refused with an explanation |
-| Presence, calendar | yes | partially |
+| | `interactive` (default) | `device-code` | `client-credentials` |
+|---|---|---|---|
+| What you do | browser opens, you sign in | type a short code elsewhere | nothing |
+| Identity | you | you | the application |
+| Needs a browser | yes | no | no |
+| Reading chats/channels | yes | yes | only via protected APIs |
+| **Sending messages** | **yes** | **yes** | **no** — refused with an explanation |
+| Presence, calendar | yes | yes | partially |
+
+**Interactive** is chosen automatically wherever a browser can actually be
+reached. MSAL opens the system browser, listens on a loopback port for the
+redirect, and handles PKCE — nothing to copy or type.
+
+**Device code** takes over automatically over SSH, in containers, and on any
+machine without a display server, because a browser opened there would appear
+where nobody is looking. Force it anywhere with `PI_TEAMS_NO_BROWSER=1`, per
+account with `"authMode": "device-code"`, or per call with
+`teams_login mode: device-code`.
+
+Either way the session is cached on disk and renewed silently, so signing in is
+a once-per-account affair.
 
 Microsoft Graph only permits app-only writes to chats and channels for
 migration scenarios (`Teamwork.Migrate.All`), so pi-teams refuses those calls
 up front instead of letting them fail deep inside a Graph request. Use
-`client-credentials` for unattended read-only jobs, `device-code` for
+`client-credentials` for unattended read-only jobs, and a delegated flow for
 everything that speaks in your name.
 
 ---
@@ -126,10 +277,10 @@ prefer.
   "accounts": [
     {
       "name": "work",
-      "displayName": "NeoImpulse",
-      "tenantId": "neoimpulse.onmicrosoft.com",
+      "displayName": "Contoso",
+      "tenantId": "contoso.onmicrosoft.com",
       "clientId": "00000000-0000-0000-0000-000000000000",
-      "authMode": "device-code",
+      "authMode": "interactive",
       "safetyLevel": "confirm",
       "permissions": {
         "read": {
@@ -142,7 +293,7 @@ prefer.
             "deny": ["*/Announcements"]
           },
           "chats": { "allow": ["*"] },
-          "people": { "deny": ["ceo@neoimpulse.de"] }
+          "people": { "deny": ["ceo@contoso.com"] }
         }
       },
       "tenants": [
@@ -250,20 +401,20 @@ teams_permissions:
 | Tool | Description |
 |------|-------------|
 | `teams_setup` | Write an account or tenant to the config file |
-| `teams_login` | Sign in as yourself (device code flow) |
+| `teams_login` | Sign in as yourself (browser, or device code where there is none) |
 | `teams_logout` | Remove a saved session |
 | `teams_accounts` | List accounts, switch the default, change a safety level, delete |
 | `teams_status` | Which account is active, who pi acts as, what it may do |
 | `teams_permissions` | Show, test or change the allow/deny rules |
 | `teams_doctor` | Diagnose config, sign-in, consent and connectivity |
+| `teams_watch` | Listen mode: status, enable, disable, and the filters for who and where |
 
 ### Reading
 
 | Tool | Description |
 |------|-------------|
 | `teams_inbox` | Chats with new messages plus recent mentions of you |
-| `teams_list_chats` | Recent chats with a preview of the last message |
-| `teams_read_chat` | Messages of one chat |
+| `teams_list_chats` | Recent chats with a preview of the last message || `teams_read_chat` | Messages of one chat |
 | `teams_list_teams` | Teams you belong to |
 | `teams_list_channels` | Channels of a team |
 | `teams_read_channel` | Posts in a channel |
@@ -298,8 +449,9 @@ teams_permissions:
 | Command | Description |
 |---------|-------------|
 | `/teams-status` | Show the connection and permissions |
-| `/teams-login` | Start the device code sign-in |
+| `/teams-login` | Sign in to Teams as yourself |
 | `/teams-inbox` | What needs your attention right now |
+| `/teams-listen` | Listen mode: `on`, `off`, or `status` |
 | `/teams-permissions` | What pi may and may not do |
 | `/teams-doctor` | Diagnose the setup |
 
@@ -316,6 +468,32 @@ teams_permissions:
 
 ---
 
+## How messages are formatted
+
+A message body is treated as **lightweight markdown** and converted to the HTML
+subset Teams renders in a chat bubble:
+
+| You write | Teams shows |
+|-----------|-------------|
+| `**bold**`, `*italic*`, `~~struck~~` | bold, italic, struck through |
+| `` `code` ``, fenced blocks | inline code, code block |
+| `- item`, `1. item` | bullet list, numbered list |
+| `[label](https://…)` | link |
+| `# Heading` | a bold line — Teams has no headings in a chat |
+
+Tables and images are deliberately **not** translated: Teams renders neither in
+a chat, so passing them through would look worse than plain text. Put a table in
+a file and link it instead.
+
+Pass `html: true` on a send tool to bypass the conversion and supply raw HTML
+instead. Everything else is escaped, so a message body cannot inject markup.
+
+This is also why pi writes the way it does: see *How to format a Teams message*
+in the bundled skill. Short, answer-first, bullets for anything enumerable — the
+medium is a chat bubble, not a document.
+
+---
+
 ## Addressing things
 
 **Channels** — a `Team/Channel` path, or `team` and `channel` separately.
@@ -354,7 +532,7 @@ teams_send_channel_message:
 | File | Contents | Mode |
 |------|----------|------|
 | `~/.pi/agent/pi-teams.json` | accounts, tenants, safety levels, scope rules | `0600` |
-| `~/.pi/agent/pi-teams-tokens.json` | access and refresh tokens per account+tenant | `0600` |
+| `~/.pi/agent/pi-teams-tokens/` | one MSAL token cache per account+tenant | `0600` |
 | `~/.pi/agent/pi-teams-audit.jsonl` | one line per write: when, who, where, what | `0600` |
 
 Both the config and the token cache are written through a private temp file and
@@ -368,17 +546,22 @@ Data-oriented: plain immutable data, I/O at the edges, pure functions in the
 middle.
 
 - **`src/types.ts`** — domain data as plain interfaces. No behavior.
-- **`src/config/index.ts`** — accounts, tenants, the safety cascade, persistence.
+- **`src/config/index.ts`** — accounts, tenants, the safety cascade, listen-mode settings, persistence.
 - **`src/config/scope.ts`** — allow/deny matching. Pure, and the most heavily
   tested module in the package.
-- **`src/auth/`** — device code flow, client credentials, token cache, JWT claims.
+- **`src/auth/`** — MSAL applications, the file-backed token cache, JWT claims.
 - **`src/graph/client.ts`** — fetch wrapper: bearer token, paging, throttling.
 - **`src/graph/*.ts`** — one module per resource area, returning domain types.
 - **`src/graph/mappers.ts`** — Graph JSON → domain types. Pure.
+- **`src/watch/`** — listen mode: the decision rules (`index.ts`, pure), the
+  polling loop (`loop.ts`), and the prompt an incoming message turns into
+  (`prompt.ts`).
 - **`src/utils/formatting.ts`** — domain types → display strings. Pure.
+- **`src/utils/richtext.ts`** — markdown → the HTML subset Teams renders. Pure.
 - **`src/safety/`** — the three gates and the audit log.
 - **`src/tools/`** — one module per tool.
-- **`src/extension/index.ts`** — registration, commands, the `tool_call` interceptor.
+- **`src/extension/index.ts`** — registration, commands, the `tool_call`
+  interceptor, and the listen-mode lifecycle.
 
 ## Development
 
@@ -389,20 +572,29 @@ npm test
 ```
 
 Tests cover the pure logic — scope matching, the config cascade, message body
-construction, HTML flattening, the safety gates — and run without a tenant or
-a network connection.
+construction, markdown rendering, HTML flattening, the listen-mode decision
+rules, the safety gates — and run without a tenant or a network connection.
 
 ## Troubleshooting
 
 | Symptom | Cause and fix |
 |---------|---------------|
+| `AADSTS500113` (no reply address) | The registration has no redirect URI. Add `http://localhost` under *Mobile and desktop applications* — see [docs/entra-app-registration.md](docs/entra-app-registration.md) |
 | `AADSTS7000218` | "Allow public client flows" is off in the app registration |
 | `AADSTS65001` | Consent missing — sign in again, or have an admin consent |
+| `AADSTS50011` (redirect URI mismatch) | Add `http://localhost` under *Mobile and desktop applications*, or pin `loopbackPort` |
 | `AADSTS50020` | The account is not a member/guest of that tenant, or the app is single-tenant |
-| "Not signed in" | Run `teams_login`; the refresh token may have been revoked |
+| Signed out after about an hour | The tenant grants no `offline_access`, so there is no refresh token. `teams_doctor` names the missing scope; otherwise sign in again when it expires |
+| Browser never opens | No browser is reachable here; `teams_doctor` says why. `teams_login mode: device-code` always works |
+| Browser opens, page never returns | A firewall is blocking the loopback port. Pin `loopbackPort` and allow it, or use the device code flow |
+| "Not signed in" | Run `teams_login`; the saved session may have been revoked |
+| Status line says "not signed in" although sign-in worked | The line is written at session start and after every auth tool; if it lags, `/teams-status` repaints it |
 | "Blocked by configuration" | Your own scope rules. `teams_permissions action: test` shows which rule |
-| "cannot run on an app-only token" | Set `authMode: "device-code"` and run `teams_login` |
-| 403 on channel messages | `ChannelMessage.Read.All` / `ChannelMessage.Send` not consented |
+| "cannot run on an app-only token" | Set `authMode: "interactive"` and run `teams_login` |
+| 403 reading channel messages | `ChannelMessage.Read.All` needs **admin** consent — see "Who has to approve what" |
+| Listen mode does nothing | `teams_watch action: status` says whether it is enabled and running. Only messages arriving *after* it was switched on wake pi |
+| Listen mode answers too much | Narrow `watch.chats` and `watch.from`, raise `cooldownSeconds`, lower `maxTriggersPerHour` |
+| Listen mode stopped by itself | `teams_watch action: status` shows the last polling error; a revoked session or a sleeping laptop is the usual cause, and it resumes on its own |
 | Throttled | Graph rate limit; the client retries with back-off, then reports it |
 
 Run `teams_doctor` first — it checks all of the above at once.

package/docs/entra-app-registration.md

@@ -0,0 +1,218 @@
+# Entra ID app registration for pi-teams
+
+The one-time setup that lets pi sign in as you. Fifteen minutes, once per
+organization, and nothing in it needs a build or a server.
+
+Everything below uses placeholders. Wherever you see
+
+| Placeholder | Where it comes from |
+|---|---|
+| `<APPLICATION_CLIENT_ID>` | *Overview* → **Application (client) ID** |
+| `<DIRECTORY_TENANT_ID>` | *Overview* → **Directory (tenant) ID** |
+| `<TENANT_DOMAIN>` | e.g. `contoso.onmicrosoft.com`, or your verified domain |
+
+…substitute your own values locally. Do not paste real tenant or client IDs into
+a README, a ticket, a screenshot or a chat — they identify your organization,
+and the client ID is half of what an attacker needs to start a sign-in flow
+against your tenant.
+
+---
+
+## 1. Create the registration
+
+**Entra admin center** → [entra.microsoft.com](https://entra.microsoft.com) →
+**App registrations** → **New registration**
+
+| Field | Value |
+|---|---|
+| Name | `pi-teams` (anything recognizable) |
+| Supported account types | **Accounts in any organizational directory (multitenant)** if pi should also reach guest or customer tenants; **single tenant** is fine for one company |
+| Redirect URI | leave empty here — it goes in step 2, on the right platform |
+
+Two things to copy out of **Overview** before moving on:
+
+- **Application (client) ID** → `<APPLICATION_CLIENT_ID>`
+- **Directory (tenant) ID** → `<DIRECTORY_TENANT_ID>`
+
+## 2. Authentication — the part that actually decides whether sign-in works
+
+**App registrations** → your app → **Authentication**. Two settings matter, and
+they are needed for two different reasons. Both are in this one blade.
+
+Direct link, with your own application ID substituted:
+
+```
+https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Authentication/appId/<APPLICATION_CLIENT_ID>
+```
+
+### 2a. A reply address, for the browser sign-in
+
+**Authentication** → **Add a platform** → **Mobile and desktop applications** →
+tick **`http://localhost`** → **Configure**.
+
+MSAL picks a free loopback port when the browser sign-in starts, and Entra
+treats the port-less `http://localhost` entry as matching *any* port for a
+public client. One entry therefore covers every run — no per-port registration
+and no fixed port needed.
+
+Skipping this is the single most common setup mistake, and it fails *after* the
+user has typed their password, with:
+
+```
+AADSTS500113: No reply address is registered for the application.
+```
+
+If your tenant insists on an exact URI, register e.g. `http://localhost:3000`
+instead and pin the same number in pi (`loopbackPort` under the account, or
+`teams_login port: 3000`).
+
+### 2b. Public client flows, for the device code sign-in
+
+Same blade → **Advanced settings** → **Allow public client flows** → **Yes** →
+**Save**.
+
+pi uses delegated OAuth flows and never handles a client secret for sign-in, so
+Entra must treat the app as a public client. Without this, sign-in fails with:
+
+```
+AADSTS7000218: The request body must contain the following parameter:
+'client_assertion' or 'client_secret'.
+```
+
+## 3. API permissions
+
+**App registrations** → your app → **API permissions** → **Add a permission** →
+**Microsoft Graph** → **Delegated permissions**:
+
+| Permission | Needed for |
+|---|---|
+| `User.Read`, `User.ReadBasic.All` | identity, looking colleagues up |
+| `Team.ReadBasic.All`, `Channel.ReadBasic.All` | listing teams and channels |
+| `ChannelMessage.Read.All` | reading channel messages and threads |
+| `ChannelMessage.Send` | posting and replying in channels |
+| `ChannelMember.Read.All` | channel member lists |
+| `Chat.ReadWrite` | reading chats, creating chats |
+| `ChatMessage.Send` | sending chat messages |
+| `Presence.ReadWrite`, `Presence.Read.All` | your status, colleagues' availability |
+| `Calendars.ReadWrite` | reading and creating calendar events |
+| `OnlineMeetings.ReadWrite` | Teams meeting links |
+| `Files.Read.All`, `Sites.Read.All` | channel files |
+
+`openid`, `profile` and `offline_access` are deliberately absent: MSAL always
+requests them and rejects them in an explicit scope list.
+
+**What is not needed:** no client secret, no certificate, no redirect URI beyond
+step 2, no application (as opposed to delegated) permissions.
+
+## 4. Consent
+
+**API permissions** → **Grant admin consent** — only for the two scopes that
+require it:
+
+| Scope | Consent | Without it |
+|---|---|---|
+| `ChannelMessage.Read.All` | **admin** | cannot read channel messages or threads |
+| `ChannelMember.Read.All` | **admin** | cannot list channel members |
+| everything else above | user | a normal sign-in consent prompt covers it |
+
+Without an administrator, drop those two scopes from the configuration and
+everything else still works: chats in full, posting and replying in channels,
+presence, calendar, meetings, directory lookup. See the README, *Who has to
+approve what*, for the reduced scope list.
+
+If the tenant has *Users can consent to applications* switched off, even the
+user-consentable scopes need an administrator — usually through the admin
+consent request workflow.
+
+## 5. Give it to pi
+
+```yaml
+teams_setup:
+  name: work
+  displayName: Contoso
+  tenantId: "<DIRECTORY_TENANT_ID or <TENANT_DOMAIN>>"
+  clientId: "<APPLICATION_CLIENT_ID>"
+  setDefault: true
+```
+
+Or edit `~/.pi/agent/pi-teams.json` directly — the same file, mode `0600`:
+
+```json
+{
+  "accounts": [
+    {
+      "name": "work",
+      "tenantId": "<TENANT_DOMAIN>",
+      "clientId": "<APPLICATION_CLIENT_ID>",
+      "authMode": "interactive",
+      "safetyLevel": "confirm"
+    }
+  ],
+  "defaultAccount": "work"
+}
+```
+
+## 6. Sign in and verify
+
+1. `teams_login` — the browser opens at the Microsoft sign-in page, you sign in
+   with your own credentials and MFA, and the page closes itself. Nothing to
+   copy or type. Over SSH or in a container, pi falls back to the device code
+   flow and shows a short code to enter on any device.
+2. `teams_status` — who pi acts as, which token is cached, what it may do.
+3. `teams_doctor` — checks configuration, sign-in, granted scopes and
+   connectivity in one go. It reports a missing consent as a **named
+   permission**, which is the quickest way to see whether the admin consent of
+   step 4 actually landed.
+
+A successful sign-in is cached on disk and renewed silently, so this is a
+once-per-account affair — as long as the tenant grants the session a refresh
+token (see below).
+
+## 7. Guest and customer tenants
+
+For a tenant that is not your own:
+
+1. the registration must be **multitenant** (step 1),
+2. your account must be a **guest in that tenant**,
+3. an administrator **of that tenant** consents to the app once.
+
+In practice the third step is the hurdle, not your own tenant. Once it is done:
+
+```yaml
+teams_setup:
+  parentAccount: work
+  name: customer-alpha
+  tenantId: "customeralpha.onmicrosoft.com"
+```
+
+then `teams_login` with `tenant: customer-alpha`, and `teams_doctor` to confirm
+that tenant on its own.
+
+---
+
+## Troubleshooting the registration
+
+| Error | Cause | Fix |
+|---|---|---|
+| `AADSTS500113` — *No reply address is registered* | no redirect URI on the registration | step 2a: add `http://localhost` under **Mobile and desktop applications** |
+| `AADSTS50011` — *redirect URI mismatch* | an exact URI is registered that does not match the chosen port | register the port-less `http://localhost`, or pin the port in the same file |
+| `AADSTS7000218` — *client_assertion or client_secret* | **Allow public client flows** is off | step 2b |
+| `AADSTS65001` — *consent required* | permissions added but never consented | sign in again; for the two admin scopes, step 4 |
+| `AADSTS50020` — *not a member of the tenant* | wrong tenant, no guest account, or the app is single-tenant | steps 1 and 7 |
+| `AADSTS700016` — *application not found in directory* | wrong tenant ID or client ID | recheck `<DIRECTORY_TENANT_ID>` and `<APPLICATION_CLIENT_ID>` |
+| signed out after about an hour | the tenant grants no `offline_access` | the app needs a refresh token to renew silently; without it, run `teams_login` when the session expires. `teams_doctor` names the missing scope |
+
+Run `teams_doctor` first for anything in this table: it validates the
+configuration, the cached session, the granted scopes and the connection to
+Graph, and it says which of them failed rather than only that something did.
+
+## Rotating or revoking access
+
+- **To sign out of pi:** `teams_logout` (per account), or `all: true` for every
+  account. This deletes the cached session, not the app.
+- **To revoke pi's access for everyone:** Entra admin center → **Enterprise
+  applications** → your app → **Properties** → *User assignment required*, or
+  delete the registration. Deleting it invalidates every cached session at once.
+- **To change the registration:** editing scopes or redirect URIs does not touch
+  the local configuration — but it does invalidate a *new* consent, so sign in
+  again afterwards.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Microsoft Teams integration for pi coding agent — acts fully as the signed-in user across multiple accounts and tenants: chats, channels, meetings, presence, with configurable guardrails",
   "keywords": [
     "pi-package",
@@ -29,7 +29,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "typebox": "^1.2.8"
+    "@azure/msal-node": "^6.0.0",
+    "typebox": ">=1.0.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.70.0",

package/prompts/teams-doctor.md

@@ -7,12 +7,19 @@ Something is wrong with my Teams connection.
 
 2. Explain each problem in plain language, and say who can fix it — me or a
    tenant administrator. In particular:
-   - missing consent → name the exact Graph scope and what it is needed for
+   - missing consent → name the exact Graph scope and what it is needed for,
+     and say whether it needs an admin (`ChannelMessage.Read.All` and
+     `ChannelMember.Read.All` do; the rest I can consent to myself)
    - "Allow public client flows" disabled → the setting is in Entra ID →
      App registrations → Authentication
+   - a redirect URI mismatch → `http://localhost` must be registered under
+     "Mobile and desktop applications"
+   - the browser sign-in unavailable → say why, and that
+     `teams_login mode: device-code` works anywhere
    - expired or revoked sign-in → I need to run `teams_login` again
    - a guest tenant that rejects the sign-in → the app registration must be
-     multi-tenant and I must be invited to that tenant
+     multi-tenant, I must be invited there, and an admin of that tenant must
+     have consented
 
 3. Run `teams_permissions` with `action: "show"` and tell me, in one short
    paragraph, what you are currently allowed to do and what you are not.