@patimweb/pi-teams 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Weppelmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# pi-teams
+
+Microsoft Teams integration for the [pi coding agent](https://github.com/earendil-works/pi).
+
+pi acts **as you**: it reads what you can read, and anything it sends comes
+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.
+
+## Installation
+
+```bash
+# From npm
+pi install npm:@patimweb/pi-teams
+
+# From a local checkout during development
+pi install /path/to/pi-teams
+```
+
+## Quick start
+
+1. **Register an app in Entra ID** (once per organization — see below).
+2. **Configure the account:**
+   ```
+   teams_setup:
+     name: work
+     tenantId: contoso.onmicrosoft.com
+     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.
+4. **Check it works:** `/teams-status`, then `/teams-inbox`.
+
+---
+
+## 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.
+
+### 1. Create the registration
+
+Entra admin center → **App registrations** → **New registration**
+
+| Field | Value |
+|-------|-------|
+| Name | `pi-teams` (anything you like) |
+| Supported account types | **Accounts in any organizational directory (multitenant)** — required if pi should also reach customer or guest tenants. Single tenant is fine for one company. |
+| Redirect URI | leave empty |
+
+Note the **Application (client) ID** and **Directory (tenant) ID**.
+
+### 2. Enable public client flows
+
+**Authentication** → *Advanced settings* → **Allow public client flows** →
+**Yes**.
+
+Without this, sign-in fails with `AADSTS7000218`.
+
+### 3. Add delegated permissions
+
+**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 |
+| `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 |
+| `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.
+
+To request fewer permissions, set `scopes` on the account — see below.
+
+### 4. 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.
+
+Then add it as a tenant beneath your account (`parentAccount`) and sign in
+again against it.
+
+---
+
+## Acting as a user vs. app-only
+
+| | `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 |
+
+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
+everything that speaks in your name.
+
+---
+
+## Configuration
+
+Everything lives in `~/.pi/agent/pi-teams.json` (mode `0600`, created from a
+template on first run). `teams_setup` writes the same file — use whichever you
+prefer.
+
+```json
+{
+  "accounts": [
+    {
+      "name": "work",
+      "displayName": "NeoImpulse",
+      "tenantId": "neoimpulse.onmicrosoft.com",
+      "clientId": "00000000-0000-0000-0000-000000000000",
+      "authMode": "device-code",
+      "safetyLevel": "confirm",
+      "permissions": {
+        "read": {
+          "teams": { "allow": ["*"] },
+          "chats": { "allow": ["*"] }
+        },
+        "write": {
+          "channels": {
+            "allow": ["Engineering/*", "Project Alpha/General"],
+            "deny": ["*/Announcements"]
+          },
+          "chats": { "allow": ["*"] },
+          "people": { "deny": ["ceo@neoimpulse.de"] }
+        }
+      },
+      "tenants": [
+        {
+          "name": "customer-alpha",
+          "tenantId": "customeralpha.onmicrosoft.com",
+          "safetyLevel": "readonly",
+          "permissions": {
+            "read": { "channels": { "allow": ["Project Alpha/*"] } }
+          }
+        }
+      ]
+    },
+    {
+      "name": "private",
+      "tenantId": "othercompany.onmicrosoft.com",
+      "clientId": "11111111-1111-1111-1111-111111111111",
+      "safetyLevel": "open"
+    }
+  ],
+  "defaultAccount": "work",
+  "safetyLevel": "confirm",
+  "maxMessages": 25,
+  "audit": true
+}
+```
+
+### Accounts and tenants
+
+- An **account** is a Teams identity you sign in as. Each has its own saved
+  session.
+- A **tenant** beneath an account is another directory that identity reaches:
+  a customer, a subsidiary, a guest tenant. It gets its own sign-in, its own
+  safety level and its own rules.
+
+Every tool takes `account` and `tenant`:
+
+```yaml
+teams_send_channel_message:
+  account: work
+  tenant: customer-alpha
+  channel: "Project Alpha/General"
+  body: "Sprint review moved to Thursday."
+```
+
+### Safety levels
+
+| Level | Effect |
+|-------|--------|
+| `open` | writes go through without asking |
+| `confirm` | every write shows a confirmation with the destination and the exact text (**default**) |
+| `readonly` | writes are blocked entirely |
+
+Set globally, per account, or per tenant — the most specific setting wins. So
+your own company can be `confirm` while a customer tenant stays `readonly`.
+
+### Scope rules
+
+Rules exist per **category** (`teams`, `channels`, `chats`, `people`) and per
+**mode** (`read`, `write`). Category keys written directly in the block apply
+to both modes; a `read` or `write` block refines one of them.
+
+```json
+"permissions": {
+  "channels": { "deny": ["*/Announcements"] },
+  "write": { "channels": { "allow": ["Engineering/*"] } }
+}
+```
+
+- **`deny` accumulates** across global → account → tenant and always wins.
+- **`allow` narrows**: the most specific level that defines one wins. Nothing
+  configured means everything the signed-in user can reach.
+- Patterns are case-insensitive globs: `*` matches any run of characters
+  (including `/`), `?` matches one.
+- A target matches if **any** of its identifiers does: channels match on
+  `Team/Channel`, their name or their ID; chats match on topic, participant
+  names and e-mail addresses; people match on name, UPN and e-mail.
+
+Check a rule without touching anything:
+
+```yaml
+teams_permissions:
+  action: test
+  category: channels
+  mode: write
+  target: "Engineering/Announcements"
+```
+
+### Other settings
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `defaultAccount` | first account | account used when a tool omits `account` |
+| `maxMessages` | `25` | default page size for message listings |
+| `audit` | `true` | append every write to `~/.pi/agent/pi-teams-audit.jsonl` |
+| `scopes` | see above | override the requested Graph scopes per account/tenant |
+| `graphBaseUrl` / `authorityHost` | Microsoft public cloud | sovereign cloud endpoints |
+
+---
+
+## Tools
+
+### Session and configuration
+
+| Tool | Description |
+|------|-------------|
+| `teams_setup` | Write an account or tenant to the config file |
+| `teams_login` | Sign in as yourself (device code flow) |
+| `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 |
+
+### 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_teams` | Teams you belong to |
+| `teams_list_channels` | Channels of a team |
+| `teams_read_channel` | Posts in a channel |
+| `teams_read_thread` | One thread: opener plus every reply |
+| `teams_search_messages` | Full-text search across chats and channels |
+| `teams_list_members` | Members of a team or channel |
+| `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_list_meetings` | Calendar events and meetings in a range |
+| `teams_get_meeting` | One meeting in full |
+
+### Writing
+
+| Tool | Description |
+|------|-------------|
+| `teams_send_chat_message` | Send a chat message as you |
+| `teams_create_chat` | Start a 1:1 or group chat, optionally with the first message |
+| `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_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_cancel_meeting` | Cancel a meeting |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/teams-status` | Show the connection and permissions |
+| `/teams-login` | Start the device code sign-in |
+| `/teams-inbox` | What needs your attention right now |
+| `/teams-permissions` | What pi may and may not do |
+| `/teams-doctor` | Diagnose the setup |
+
+## Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `/teams-catch-up` | Summarize what happened while you were away |
+| `/teams-triage` | Work through unanswered messages one by one |
+| `/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-doctor` | Guided troubleshooting |
+
+---
+
+## Addressing things
+
+**Channels** — a `Team/Channel` path, or `team` and `channel` separately.
+Names resolve case-insensitively; an ambiguous name is reported, never guessed.
+
+```yaml
+teams_read_channel:
+  channel: "Engineering/General"
+  limit: 20
+```
+
+**Chats** — an ID, a group chat topic, or a participant's name or e-mail. If
+more than one chat matches, the tool lists the candidates instead of picking
+one.
+
+```yaml
+teams_send_chat_message:
+  chat: "anna@contoso.com"
+  body: "Running five minutes late."
+```
+
+**Mentions** — pass `mentions` and write `@Display Name` in the body where the
+mention belongs:
+
+```yaml
+teams_send_channel_message:
+  channel: "Engineering/General"
+  body: "@Anna Schmidt the pipeline is green again."
+  mentions: ["anna@contoso.com"]
+```
+
+---
+
+## Files pi writes
+
+| 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-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
+an atomic rename, so an interrupted write cannot truncate them. To revoke
+pi's access entirely, run `teams_logout` with `all: true` and remove the app's
+consent in Entra ID.
+
+## Architecture
+
+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/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/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/utils/formatting.ts`** — domain types → display strings. 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.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+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.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---------|---------------|
+| `AADSTS7000218` | "Allow public client flows" is off in the app registration |
+| `AADSTS65001` | Consent missing — sign in again, or have an admin consent |
+| `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 |
+| "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 |
+| 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.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/extension/index.ts";

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@patimweb/pi-teams",
+  "version": "1.0.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",
+    "microsoft-teams",
+    "teams",
+    "microsoft-graph",
+    "pi-extension"
+  ],
+  "author": "Patrick Weppelmann",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Smotherer007/pi-teams.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Smotherer007/pi-teams/issues"
+  },
+  "scripts": {
+    "build": "echo 'No build step defined'",
+    "test": "node scripts/test.mjs",
+    "test:watch": "node scripts/test.mjs --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "typebox": "^1.2.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.70.0",
+    "typebox": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.80.3",
+    "@semantic-release/git": "^10.0.0",
+    "@types/node": "^22.0.0",
+    "semantic-release": "^25.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "image": "https://raw.githubusercontent.com/Smotherer007/pi-teams/main/screenshot.png"
+  }
+}

package/prompts/teams-catch-up.md

@@ -0,0 +1,24 @@
+---
+description: Summarize what happened in Microsoft Teams while you were away
+argument-hint: "[hours, e.g. 24]"
+---
+Catch me up on Microsoft Teams.
+
+1. Run `teams_inbox` with `hours` set to $@ (default 24 if nothing was given).
+
+2. For every chat with new messages, run `teams_read_chat` to read the actual
+   messages — the preview alone is not enough to judge whether something needs
+   an answer.
+
+3. For every mention, run `teams_read_thread` (channel) or `teams_read_chat`
+   (chat) to get the surrounding context.
+
+4. Summarize as:
+   - **Needs a reply from me** — who is waiting, on what, and since when
+   - **FYI** — decisions, announcements and progress I should know about
+   - **Noise** — one line, just the count
+
+   Keep each item to one or two sentences and name the people involved.
+
+5. For anything in "Needs a reply", propose a short draft reply, but do not
+   send anything. Ask me which drafts to send.

package/prompts/teams-channel-digest.md

@@ -0,0 +1,23 @@
+---
+description: Summarize what happened in a Teams channel
+argument-hint: "<Team/Channel> [days]"
+---
+Summarize a Microsoft Teams channel: $@
+
+1. Resolve the channel with `teams_read_channel` (a `Team/Channel` path works
+   directly). If no channel was named, ask which one — do not guess.
+
+2. Read the recent posts. For every post that has replies, run
+   `teams_read_thread` so the summary reflects the discussion, not just the
+   opening message.
+
+3. Produce:
+   - **Decisions** — what was decided, by whom
+   - **Open questions** — what is still unanswered, and who asked
+   - **Action items** — who owes what, with any dates mentioned
+   - **Notable** — anything else worth knowing
+
+4. Reference the people by name and include the `messageId` for anything I
+   might want to reply to.
+
+Do not post anything in the channel.

package/prompts/teams-doctor.md

@@ -0,0 +1,21 @@
+---
+description: Diagnose and fix the Microsoft Teams connection
+---
+Something is wrong with my Teams connection.
+
+1. Run `teams_doctor` for every configured account.
+
+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
+   - "Allow public client flows" disabled → the setting is in Entra ID →
+     App registrations → Authentication
+   - 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
+
+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.
+
+4. Propose the concrete next step. Do not change my configuration without
+   asking first.

package/prompts/teams-meeting-prep.md

@@ -0,0 +1,22 @@
+---
+description: Prepare for your next Teams meeting
+argument-hint: "[meeting subject or 'next']"
+---
+Prepare me for a Teams meeting: $@
+
+1. Run `teams_list_meetings` to find the meeting. If nothing was specified,
+   take the next one starting from now. Show me which meeting you picked.
+
+2. Run `teams_get_meeting` for the full details — attendees, agenda, join link.
+
+3. Search Teams for context with `teams_search_messages`: the meeting subject,
+   and the names of the attendees. Read the relevant threads with
+   `teams_read_thread` or `teams_read_chat`.
+
+4. Give me:
+   - **When and who** — time, join link, attendees and their roles if visible
+   - **Context** — what has been discussed about this recently, with dates
+   - **Open items** — questions left unanswered in the threads
+   - **Suggested talking points** — three to five, grounded in what you read
+
+Do not message anyone.

package/prompts/teams-standup.md

@@ -0,0 +1,21 @@
+---
+description: Draft and post a standup update to a Teams channel
+argument-hint: "<Team/Channel>"
+---
+Help me post a standup update to: $@
+
+1. If no channel was given, ask for one.
+
+2. Read the channel's last few posts with `teams_read_channel` so the update
+   fits what the team has been discussing, and so I do not repeat something
+   that was already said.
+
+3. Ask me for anything you cannot know: what I did yesterday, what I am doing
+   today, and what is blocking me. Do not invent progress, and do not carry
+   over items from an old update as if they were new.
+
+4. Draft the update in my voice — short, plain, no headings unless the channel
+   uses them. Match the format of the previous standups in that channel.
+
+5. Show me the draft and the exact destination channel. Only after I approve,
+   post it with `teams_send_channel_message`.

package/prompts/teams-triage.md

@@ -0,0 +1,22 @@
+---
+description: Work through unanswered Teams messages one by one
+argument-hint: "[hours]"
+---
+Triage my Microsoft Teams messages from the last $@ hours (default 24).
+
+1. Run `teams_inbox` to find what is waiting.
+
+2. For each item, read enough context (`teams_read_chat` or
+   `teams_read_thread`) to judge it, then classify it as:
+   - **Answer now** — a short reply unblocks someone
+   - **Needs me** — requires a decision or information only I have
+   - **Delegate** — someone else should handle it; say who
+   - **Ignore** — no action needed
+
+3. Present the list as a table: who, what, classification, and the chat or
+   channel it lives in.
+
+4. For everything in "Answer now", draft a reply in my voice. Show me all the
+   drafts together, then send only the ones I approve, one tool call each.
+
+5. Do not react, reply or change anything before I approve it.