@patimweb/pi-teams 1.1.0 → 1.3.0

package/README.md

@@ -7,6 +7,8 @@ from your account, in your name, in the right thread. Multiple Teams accounts
 and multiple company tenants live side by side, and a configuration file
 decides exactly which teams, channels, chats and people pi may touch.
 
+![pi-teams in the pi coding agent](screenshot.png)
+
 ## Installation
 
 ```bash
@@ -19,7 +21,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:
@@ -32,12 +36,80 @@ pi install /path/to/pi-teams
    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
 
@@ -207,8 +279,8 @@ prefer.
   "accounts": [
     {
       "name": "work",
-      "displayName": "NeoImpulse",
-      "tenantId": "neoimpulse.onmicrosoft.com",
+      "displayName": "Contoso",
+      "tenantId": "contoso.onmicrosoft.com",
       "clientId": "00000000-0000-0000-0000-000000000000",
       "authMode": "interactive",
       "safetyLevel": "confirm",
@@ -223,7 +295,7 @@ prefer.
             "deny": ["*/Announcements"]
           },
           "chats": { "allow": ["*"] },
-          "people": { "deny": ["ceo@neoimpulse.de"] }
+          "people": { "deny": ["ceo@contoso.com"] }
         }
       },
       "tenants": [
@@ -337,6 +409,7 @@ teams_permissions:
 | `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
 
@@ -354,6 +427,7 @@ teams_permissions:
 | `teams_find_user` | Directory lookup by name, e-mail or UPN |
 | `teams_list_files` | Files in a channel's SharePoint folder |
 | `teams_get_presence` | Your status, a colleague's, or a whole chat's |
+| `teams_availability` | When several people are all free, from calendar free/busy |
 | `teams_list_meetings` | Calendar events and meetings in a range |
 | `teams_get_meeting` | One meeting in full |
 
@@ -366,14 +440,23 @@ teams_permissions:
 | `teams_send_channel_message` | Post in a channel as you |
 | `teams_reply_channel_message` | Reply inside an existing thread |
 | `teams_react` | Add or remove an emoji reaction |
+| `teams_mark_read` | Mark a chat as read (or unread again) — the natural end of a catch-up |
+| `teams_update_message` | Edit a message you already sent |
+| `teams_chat_members` | Add someone to a group chat, or remove them |
 | `teams_delete_message` | Soft-delete (or restore) a message you sent |
-| `teams_create_channel` | Add a channel to a team |
 | `teams_set_presence` | Set your Teams status |
 | `teams_set_status_message` | Set the note under your name |
 | `teams_create_meeting` | Schedule a Teams meeting with invitations |
 | `teams_update_meeting` | Change a meeting you organize |
+| `teams_respond_invite` | Accept, decline or tentatively accept an invitation |
 | `teams_cancel_meeting` | Cancel a meeting |
 
+Editing and deleting apply to **chat** messages. A channel post cannot be
+created, edited or deleted through Graph with the permissions pi asks for
+(`Channel.Create`, `ChannelMessage.ReadWrite`) — that stays in the Teams client.
+Posting and replying in channels, and reacting to channel messages, work as
+usual.
+
 ## Commands
 
 | Command | Description |
@@ -381,6 +464,7 @@ teams_permissions:
 | `/teams-status` | Show the connection and permissions |
 | `/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 |
 
@@ -393,10 +477,37 @@ teams_permissions:
 | `/teams-channel-digest` | Decisions, open questions and action items in a channel |
 | `/teams-standup` | Draft and post a standup update |
 | `/teams-meeting-prep` | Context and talking points for your next meeting |
+| `/teams-schedule` | Find a time everyone is free and book it |
 | `/teams-doctor` | Guided troubleshooting |
 
 ---
 
+## 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.
@@ -449,17 +560,25 @@ 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/`** — 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/utils/slots.ts`** — availability view → the free slots everybody
+  shares. Pure, and the part of scheduling that can be wrong without looking
+  wrong.
 - **`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
 
@@ -470,23 +589,30 @@ 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, free-slot arithmetic, 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 |
+| 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: "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,243 @@
+# 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.
+
+### Optional: one capability that needs one more permission
+
+Everything above is what pi asks for by default. One action stays off until you
+add the scope — to this list **and** to `scopes` in `pi-teams.json` — and sign in
+again:
+
+| Permission | Unlocks | Consent |
+|---|---|---|
+| `ChatMember.ReadWrite` | removing someone from a chat (`teams_chat_members`) | user |
+
+Without it the tool answers with the exact scope it is missing instead of
+failing at Graph with a consent error. Editing and deleting chat messages,
+adding chat members and answering invitations all work with the default set.
+
+**Deliberately not requested:** `Channel.Create` and
+`ChannelMessage.ReadWrite`. They would unlock creating channels and editing or
+deleting a **channel** post, and pi is built not to depend on permissions that
+may never be granted. Channel posts are created, edited and deleted in the Teams
+client; posting, replying and reacting in channels work without them.
+
+**Also not covered:** `findMeetingTimes` and anything that reads another person's
+*appointments* need `Calendars.Read.Shared`. `teams_availability` uses
+`getSchedule` instead, which is free/busy only — no extra consent, and no view
+of what people are actually doing.
+
+## 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.1.0",
+  "version": "1.3.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",

package/prompts/teams-schedule.md

@@ -0,0 +1,23 @@
+---
+description: Find a time everyone is free and book the meeting
+argument-hint: "[who, what, how long]"
+---
+Organize a Teams meeting: $@
+
+1. Work out who has to be there. Resolve unclear names with `teams_find_user` —
+   never guess an e-mail address. Ask me for anything you cannot derive from the
+   request.
+
+2. Run `teams_availability` with those people and the meeting length (30 minutes
+   unless I said otherwise). If it finds nothing, widen the window with
+   `start`/`end` before giving up, and tell me what you tried.
+
+3. Show me two or three slots that fit, as weekday, date and time. **Do not book
+   anything yet.**
+
+4. Once I pick one, create it with `teams_create_meeting` in my time zone, with a
+   subject that says what the meeting is about. Confirm the slot, the people and
+   the subject in one line. Offer to add two or three lines of context from
+   `teams_search_messages` to the invitation body — only if I say yes.
+
+Do not invite anyone who was not named, and do not answer any invitation.