Remove tmp files
This commit is contained in:
Onur
Peter Steinberger
@@ -1,96 +0,0 @@
|
|||||||
---
|
|
||||||
date: 2026-01-08
|
|
||||||
author: Onur <onur@textcortex.com>
|
|
||||||
title: MS Teams Permissions vs Capabilities (Clawdbot)
|
|
||||||
tags: [msteams, permissions, graph]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
This doc explains what Clawdbot can and cannot do in Microsoft Teams depending on **Teams resource-specific consent (RSC)** only versus **RSC + Microsoft Graph permissions**. It also outlines the exact steps needed to unlock each capability.
|
|
||||||
|
|
||||||
## Current Teams RSC Permissions (Manifest)
|
|
||||||
These are the **existing resourceSpecific permissions** in the Teams app manifest (already in our ZIP):
|
|
||||||
|
|
||||||
- `ChannelMessage.Read.Group` (Application)
|
|
||||||
- `ChannelMessage.Send.Group` (Application)
|
|
||||||
- `Member.Read.Group` (Application)
|
|
||||||
- `Owner.Read.Group` (Application)
|
|
||||||
- `ChannelSettings.Read.Group` (Application)
|
|
||||||
- `TeamMember.Read.Group` (Application)
|
|
||||||
- `TeamSettings.Read.Group` (Application)
|
|
||||||
|
|
||||||
These only apply **inside the team where the app is installed**.
|
|
||||||
|
|
||||||
## Capability Matrix
|
|
||||||
|
|
||||||
### With **Teams RSC only** (app installed in a team, no Graph API permissions)
|
|
||||||
Works:
|
|
||||||
- Read channel message **text** content.
|
|
||||||
- Send channel message **text** content.
|
|
||||||
- Resolve basic sender identity (AAD/user id) and channel/team context.
|
|
||||||
- Use conversation references for proactive messages **only after** a user interacts.
|
|
||||||
|
|
||||||
Does NOT work:
|
|
||||||
- **Image/file content** from channel or group chat messages (payload only includes HTML stub).
|
|
||||||
- Downloading attachments stored in SharePoint/OneDrive (requires Graph).
|
|
||||||
- Reading **message history** beyond the live webhook event (requires Graph).
|
|
||||||
- Accessing messages outside the installed team.
|
|
||||||
|
|
||||||
### With **Teams RSC + Microsoft Graph Application permissions**
|
|
||||||
Adds:
|
|
||||||
- Downloading **hosted contents** (images pasted into messages).
|
|
||||||
- Downloading **file attachments** stored in SharePoint/OneDrive.
|
|
||||||
- Full message/attachment lookup via Graph endpoints.
|
|
||||||
- Reading **channel/chat message history** via Graph.
|
|
||||||
|
|
||||||
Still **not** added automatically:
|
|
||||||
- 1:1 chat file support (requires separate Bot file flows if we want to support it).
|
|
||||||
- Cross-tenant access (blocked by tenant policies).
|
|
||||||
|
|
||||||
## Required Steps by Capability
|
|
||||||
|
|
||||||
### Phase 1 — Basic text-only channel bot
|
|
||||||
Goal: Read/send text messages in installed teams.
|
|
||||||
|
|
||||||
Steps:
|
|
||||||
1. **Teams app manifest** includes the RSC permissions listed above.
|
|
||||||
2. Admin or user installs the app into a specific team.
|
|
||||||
3. Bot receives text-only channel message payloads.
|
|
||||||
|
|
||||||
Expected behavior:
|
|
||||||
- Text is visible to the bot.
|
|
||||||
- Image/file attachments are **not** available (only HTML stub).
|
|
||||||
|
|
||||||
### Phase 2 — Image and file ingestion (Graph enabled)
|
|
||||||
Goal: Download images/files from Teams messages.
|
|
||||||
|
|
||||||
Steps:
|
|
||||||
1. In **Entra ID (Azure AD)** app registration for the bot, add **Microsoft Graph Application permissions**:
|
|
||||||
- For channel attachments: `ChannelMessage.Read.All`
|
|
||||||
- For chat/group attachments: `Chat.Read.All` (or `ChatMessage.Read.All`)
|
|
||||||
2. **Grant admin consent** in the tenant.
|
|
||||||
3. Increment Teams app **manifest version** and re-upload.
|
|
||||||
4. **Reinstall the app in Teams** (remove + add) and **fully quit/reopen Teams** to clear cached app metadata.
|
|
||||||
|
|
||||||
Expected behavior:
|
|
||||||
- Bot still receives HTML stubs in the webhook.
|
|
||||||
- Bot now fetches hosted contents and attachments via Graph and can access images.
|
|
||||||
|
|
||||||
## Why Graph Is Required for Images
|
|
||||||
Teams stores images and files in Microsoft 365 storage (SharePoint/OneDrive). The Teams bot webhook **does not send file bytes**, only a message shell. To access the actual file, the app must call **Microsoft Graph** with sufficient permissions.
|
|
||||||
|
|
||||||
If Graph tokens are unavailable (permissions missing or no admin consent), image downloads will always fail.
|
|
||||||
|
|
||||||
## Note on History Access
|
|
||||||
The Teams bot webhook only delivers **new** messages. Any attempt to fetch **prior messages**, thread history, or message lists requires Microsoft Graph permissions (for example, `ChannelMessage.Read.All` or `Chat.Read.All`). Without Graph, history lookups will always return empty or be unavailable.
|
|
||||||
|
|
||||||
## Validation Checklist
|
|
||||||
- [ ] Teams app installed in target team.
|
|
||||||
- [ ] Graph permissions added and admin consented.
|
|
||||||
- [ ] Teams app version incremented and reinstalled.
|
|
||||||
- [ ] Logs show successful Graph token acquisition.
|
|
||||||
- [ ] Logs show Graph hostedContent/attachments fetched (non-zero counts).
|
|
||||||
|
|
||||||
## References
|
|
||||||
- Teams bot file handling (channel/group requires Graph):
|
|
||||||
- https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4
|
|
||||||
File diff suppressed because it is too large
Load Diff
@@ -1,158 +0,0 @@
|
|||||||
# MS Teams provider refactor plan (production-ready)
|
|
||||||
|
|
||||||
Goal: refactor the MS Teams provider code (`src/msteams/*`) for long-term maintainability and correctness **without changing user-facing behavior** (except incidental bug fixes discovered during refactor).
|
|
||||||
|
|
||||||
Status (2026-01-08): implemented (Phases 1–3) with unit tests; `pnpm lint && pnpm build && pnpm test` pass.
|
|
||||||
|
|
||||||
## Why refactor
|
|
||||||
|
|
||||||
Current pain points in `src/msteams/monitor.ts` / `src/msteams/send.ts` / `src/msteams/conversation-store.ts`:
|
|
||||||
|
|
||||||
- **Mixed concerns**: HTTP server wiring, SDK handler, routing, policy resolution, and outbound delivery live in one file.
|
|
||||||
- **Duplicated outbound logic**: proactive vs in-thread sending is implemented in multiple places (monitor + send).
|
|
||||||
- **Weak typing boundary**: custom “SDK-like” shapes + structural casts make it harder to evolve safely.
|
|
||||||
- **Conversation store is fragile**: JSON file writes are un-locked and non-atomic; no TTL; potential corruption under concurrency.
|
|
||||||
- **Hard to test**: key logic (policy precedence and delivery behavior) is not isolated/pure.
|
|
||||||
|
|
||||||
## Non-goals
|
|
||||||
|
|
||||||
- Rewriting the provider around a different SDK.
|
|
||||||
- Introducing new configuration knobs beyond what already exists (`msteams.replyStyle`, `requireMention`, etc.).
|
|
||||||
- Changing routing semantics, payload envelope format, or session key logic.
|
|
||||||
- Adding new CLI commands (unless needed for validation/testing).
|
|
||||||
|
|
||||||
## Target architecture (module split)
|
|
||||||
|
|
||||||
### 1) Policy resolution (pure + tested)
|
|
||||||
|
|
||||||
Add `src/msteams/policy.ts` (and `src/msteams/policy.test.ts`) containing pure functions:
|
|
||||||
|
|
||||||
- `resolveMSTeamsRouteConfig({ cfg, teamId, conversationId }): { teamConfig?, channelConfig? }`
|
|
||||||
- `resolveMSTeamsReplyPolicy({ isDirectMessage, cfg, teamConfig?, channelConfig? }): { requireMention: boolean; replyStyle: "thread" | "top-level" }`
|
|
||||||
|
|
||||||
Acceptance: precedence is encoded and unit-tested:
|
|
||||||
|
|
||||||
- Channel overrides > team defaults > global defaults > implicit defaults.
|
|
||||||
- DM behavior: `replyStyle` is forced to `"thread"`, mention-gating is bypassed.
|
|
||||||
- Defaulting behavior matches existing runtime logic (e.g. `requireMention -> default replyStyle` heuristic).
|
|
||||||
|
|
||||||
### 2) Outbound delivery (single implementation)
|
|
||||||
|
|
||||||
Add `src/msteams/messenger.ts` (and `src/msteams/messenger.test.ts`) to centralize:
|
|
||||||
|
|
||||||
- chunking (`resolveTextChunkLimit`, `chunkMarkdownText`, `SILENT_REPLY_TOKEN`)
|
|
||||||
- send mode selection (`"thread"` vs `"top-level"`)
|
|
||||||
- media URL message splitting (same semantics as current)
|
|
||||||
- error formatting + consistent structured logs
|
|
||||||
|
|
||||||
Surface (current implementation):
|
|
||||||
|
|
||||||
- `renderReplyPayloadsToMessages(replies, { textChunkLimit, chunkText, mediaMode })`
|
|
||||||
- `sendMSTeamsMessages({ replyStyle, adapter, appId, conversationRef, context?, messages })`
|
|
||||||
- uses `context.sendActivity` for `"thread"`
|
|
||||||
- uses `adapter.continueConversation` for `"top-level"`
|
|
||||||
|
|
||||||
Acceptance: `src/msteams/monitor.ts` and `src/msteams/send.ts` both use the messenger, so there’s exactly one “how do we send a message” implementation.
|
|
||||||
|
|
||||||
### 3) SDK typing boundary (type-only imports; no eager runtime deps)
|
|
||||||
|
|
||||||
Add `src/msteams/sdk-types.ts` exporting the minimal types we depend on:
|
|
||||||
|
|
||||||
- Turn context type (`sendActivity`, `activity` with fields we read)
|
|
||||||
- Conversation reference type for `continueConversation`
|
|
||||||
- Adapter interface subset (`continueConversation`, `process`)
|
|
||||||
|
|
||||||
Implementation note:
|
|
||||||
|
|
||||||
- Use `import type …` from the Microsoft SDK packages (or fallback to minimal structural types if the SDK does not export them cleanly).
|
|
||||||
- Keep current dynamic runtime imports (`await import("@microsoft/agents-hosting")`) intact; type-only imports compile away.
|
|
||||||
|
|
||||||
Acceptance: eliminate bespoke `TeamsTurnContext` / ad-hoc casts where possible, while preserving lazy-load behavior (some casting may remain if SDK typings are stricter than runtime behavior).
|
|
||||||
|
|
||||||
### 4) Conversation store interface + hardened FS implementation
|
|
||||||
|
|
||||||
Introduce a store interface (e.g. `src/msteams/conversation-store.ts`) and move the current file-backed store to `src/msteams/conversation-store-fs.ts`.
|
|
||||||
|
|
||||||
Store interface:
|
|
||||||
|
|
||||||
- `upsert(conversationId, reference)`
|
|
||||||
- `get(conversationId)`
|
|
||||||
- `findByUser({ aadObjectId?, userId? })`
|
|
||||||
- `list()`
|
|
||||||
- `remove(conversationId)`
|
|
||||||
|
|
||||||
FS implementation hardening:
|
|
||||||
|
|
||||||
- **Atomic writes**: write to `*.tmp` then `rename` (or equivalent).
|
|
||||||
- **Locking**: use `proper-lockfile` (already a dependency) to guard read-modify-write.
|
|
||||||
- **TTL + pruning**:
|
|
||||||
- persist `lastSeenAt`
|
|
||||||
- prune on every write and/or on a timer
|
|
||||||
- cap size (keep existing `MAX_CONVERSATIONS` behavior, but deterministic + documented)
|
|
||||||
- **Permissions**:
|
|
||||||
- dir is already `0700`; ensure file is written with `0600`
|
|
||||||
|
|
||||||
Tests:
|
|
||||||
|
|
||||||
- Use an in-memory store implementation for unit tests.
|
|
||||||
- Add FS store tests only where stable (avoid flaky timing issues).
|
|
||||||
|
|
||||||
Acceptance: no store corruption under concurrent writes in-process; behavior preserved for CLI `send` lookup.
|
|
||||||
|
|
||||||
### 5) Monitor wiring becomes “thin”
|
|
||||||
|
|
||||||
Refactor `src/msteams/monitor.ts` so it:
|
|
||||||
|
|
||||||
- loads config + credentials
|
|
||||||
- creates adapter + express routes
|
|
||||||
- routes inbound messages to a smaller `handleInboundMessage(...)` function
|
|
||||||
- delegates:
|
|
||||||
- policy decisions to `policy.ts`
|
|
||||||
- outbound sends to `messenger.ts`
|
|
||||||
- reference persistence to the store abstraction
|
|
||||||
|
|
||||||
Acceptance: `monitor.ts` is mostly wiring and orchestration; logic-heavy parts are tested in isolation.
|
|
||||||
|
|
||||||
## Implementation phases (incremental, safe)
|
|
||||||
|
|
||||||
### Phase 1 (behavior-preserving extraction)
|
|
||||||
|
|
||||||
1. Add `src/msteams/policy.ts` + `src/msteams/policy.test.ts`.
|
|
||||||
2. Add `src/msteams/messenger.ts` + `src/msteams/messenger.test.ts` (unit test chunking + send mode selection; mock context/adapter).
|
|
||||||
3. Refactor `src/msteams/monitor.ts` to use policy + messenger (no behavior change).
|
|
||||||
4. Refactor `src/msteams/send.ts` to use messenger (no behavior change).
|
|
||||||
5. Extract inbound helpers (`stripMentionTags`, mention detection, conversation ID normalization) into `src/msteams/inbound.ts` + tests.
|
|
||||||
6. Ensure `pnpm lint && pnpm build && pnpm test` pass.
|
|
||||||
7. If testing manifest/RSC updates, fully quit/relaunch Teams and reinstall the app to flush cached app metadata.
|
|
||||||
|
|
||||||
### Phase 2 (store hardening)
|
|
||||||
|
|
||||||
1. Introduce store interface + in-memory test store.
|
|
||||||
2. Move FS store to its own module; add locking + atomic writes + TTL.
|
|
||||||
3. Update `monitor.ts` + `send.ts` to depend on the interface (inject FS store from wiring).
|
|
||||||
4. Add targeted tests.
|
|
||||||
|
|
||||||
### Phase 3 (production reliability)
|
|
||||||
|
|
||||||
1. Add retry/backoff around outbound sends (careful: avoid duplicate posts; only retry safe failures).
|
|
||||||
2. Error classification helpers (auth misconfig, transient network, throttling).
|
|
||||||
3. Improve `probeMSTeams` to validate credentials (optional; can be separate).
|
|
||||||
|
|
||||||
## Done criteria / checkpoints
|
|
||||||
|
|
||||||
- Phase 1 done:
|
|
||||||
- New policy tests cover precedence and DM behavior.
|
|
||||||
- `monitor.ts` + `send.ts` share outbound sending via messenger.
|
|
||||||
- No new runtime imports that break lazy-load behavior.
|
|
||||||
- Phase 2 done:
|
|
||||||
- Store is locked + atomic + bounded.
|
|
||||||
- Clear migration story (keep same file format/version or bump explicitly).
|
|
||||||
- Phase 3 done:
|
|
||||||
- Retries are safe and bounded; logs are structured and actionable.
|
|
||||||
|
|
||||||
## Notes / edge cases to validate during refactor
|
|
||||||
|
|
||||||
- “Channel config” keys: currently based on `conversation.id` (e.g. `19:…@thread.tacv2`). Preserve that.
|
|
||||||
- `replyStyle="top-level"` correctness: ensure the conversation reference normalization is centralized and tested.
|
|
||||||
- Mention-gating: preserve current detection behavior (`entities` mention matching `recipient.id`), but isolate it for future improvements.
|
|
||||||
- Teams client caches app manifests; after uploading a new package or changing RSC permissions, fully quit/relaunch Teams (not just close the window) and reinstall the app to force the version + permission refresh.
|
|
||||||
Reference in New Issue
Block a user