lex-microsoft_teams 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c9f65eaac56b416e05eb5d96d914d6e3a88b86c91fdd083162fa09e5a6c887f4
+  data.tar.gz: ba6cd5f7d0d1b08cc8bc880cd8ab0db61d799ba66afaca8ae1938df057149a16
+SHA512:
+  metadata.gz: e996a958fbffca134f301089fcc9c3be7abd03ef73f7b756f975198d3653dcbefaaa53a3ddf26c3afd33c92aea574f33336200604912088383e7ac6acdff54d5
+  data.tar.gz: 800d036ddcb4a99ee833b3abb3ff255a60f1102625ed8ef1ec0ea9ad90c0e0195b654b8b14a0fff41835eb4288191c62fd0aaf03fcb8b58b087c752b1c32f20e

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# local credentials
+.env
+test_device_code.rb

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,56 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ParameterLists:
+  Max: 8
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## [0.5.0] - 2026-03-16
+
+### Added
+- Delegated OAuth browser flow with Authorization Code + PKCE
+- Automatic Device Code fallback for headless environments
+- `Helpers::BrowserAuth` orchestrator (PKCE generation, headless detection, browser opening)
+- `Helpers::CallbackServer` ephemeral TCP server for OAuth redirect
+- `Runners::Auth#authorize_url`, `#exchange_code`, `#refresh_delegated_token` methods
+- `Helpers::TokenCache` delegated token slot with Vault persistence and silent refresh
+- `legion auth teams` CLI command (in LegionIO) for interactive authentication
+- `GET /api/oauth/microsoft_teams/callback` Sinatra route (in LegionIO) for daemon re-auth
+
+### Fixed
+- `poll_device_code` now persists `slow_down` interval increase per RFC 8628
+- `poll_device_code` returns error hash on timeout instead of raising RuntimeError
+
+## [0.4.1] - 2026-03-15
+
+### Added
+- Preference commands: `prefer <value>`, `preferences`, `reset preferences`
+- PromptResolver queries PreferenceProfile for per-user system prompt customization
+- SessionManager passes owner_id through to PromptResolver
+- `SessionManager#refresh_prompt` rebuilds system prompt without clearing history
+
+## [0.4.0] - 2026-03-15
+
+### Added
+- Meetings runner: list, get, create, update, delete online meetings, lookup by join URL, attendance reports
+- Transcripts runner: list, get metadata, get content (VTT/DOCX format support)
+- New Graph API permissions: `OnlineMeeting.Read.All`, `OnlineMeetingTranscript.Read.All`
+
+## [0.3.0] - 2026-03-15
+
+### Added
+- Token cache helper with 60-second pre-expiry automatic refresh
+- Subscription registry with in-memory store and lex-memory persistence
+- Command handler for bot DMs: watch, unwatch, list, pause, resume
+- Token cache wired into DirectChatPoller and ObservedChatPoller
+- Subscription registry wired into ObservedChatPoller
+
+## [0.2.0] - 2026-03-15
+
+### Added
+- AI bot with direct chat mode (LLM-powered 1:1 responses via polling)
+- Conversation observer mode (task/context extraction from watched chats, default disabled)
+- AMQP-based message routing (teams.messages exchange and queue)
+- Session manager with lex-memory persistence for multi-turn conversations
+- Layered prompt resolver (settings -> mode -> per-conversation overrides)
+- High-water mark tracking for message deduplication
+- DirectChatPoller actor (5s interval, Graph API polling)
+- ObservedChatPoller actor (30s interval, compliance-gated)
+- MessageProcessor subscription actor (AMQP consumer, routes by mode)
+
+## [0.1.0] - 2026-03-13
+
+### Added
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,206 @@
+# lex-microsoft_teams: Microsoft Teams Integration for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent (Level 2)**: `/Users/miverso2/rubymine/legion/extensions/CLAUDE.md`
+- **Parent (Level 1)**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Legion Extension that connects LegionIO to Microsoft Teams via Graph API and Bot Framework. Provides runners for chats, channels, messages, subscriptions (change notifications), adaptive cards, bot communication, and an AI-powered bot with conversation observation.
+
+**GitHub**: https://github.com/LegionIO/lex-microsoft_teams
+**License**: MIT
+**Version**: 0.5.0
+
+## Architecture
+
+```
+Legion::Extensions::MicrosoftTeams
+├── Runners/
+│   ├── Auth              # OAuth2 client credentials (Graph + Bot Framework)
+│   ├── Teams             # List/get teams, members
+│   ├── Chats             # 1:1 and group chat CRUD
+│   ├── Messages          # Chat message send/read/reply
+│   ├── Channels          # Team channel CRUD
+│   ├── ChannelMessages   # Channel message send/read/reply
+│   ├── Subscriptions     # Graph change notification webhooks
+│   ├── AdaptiveCards     # Adaptive Card payload builder
+│   ├── Bot               # Bot Framework + AI bot (handle_message, handle_command, observe_message)
+│   ├── Presence          # Graph API user presence
+│   ├── Meetings          # Online meeting CRUD, join URL lookup, attendance reports
+│   ├── Transcripts       # Meeting transcript list/get/content (VTT/DOCX)
+│   ├── LocalCache        # Offline message extraction from local LevelDB cache
+│   └── CacheIngest       # Ingest cached messages into lex-memory as episodic traces
+├── Actors/
+│   ├── CacheBulkIngest       # Once: full cache ingest at startup (imprint window support)
+│   ├── CacheSync             # Every 5min: incremental ingest of new messages
+│   ├── DirectChatPoller      # Every 5s: polls bot DM chats via Graph API
+│   ├── ObservedChatPoller    # Every 30s: polls subscribed human conversations (compliance-gated)
+│   └── MessageProcessor      # Subscription: consumes AMQP queue, routes by mode
+├── Transport/
+│   ├── Exchanges/Messages    # teams.messages topic exchange
+│   ├── Queues/MessagesProcess # teams.messages.process durable queue
+│   └── Messages/TeamsMessage  # Message schema with routing key
+├── LocalCache/
+│   ├── SSTableReader     # Pure Ruby LevelDB .ldb file reader (Snappy decompression)
+│   ├── RecordParser      # Chromium IndexedDB value parser (field-value pairing)
+│   └── Extractor         # Message extraction, filtering, dedup from local cache
+├── Helpers/
+│   ├── Client            # Three connection builders (Graph, Bot, OAuth)
+│   ├── HighWaterMark     # Per-chat message dedup via legion-cache (with in-memory fallback)
+│   ├── PromptResolver    # Layered system prompt resolution (settings -> mode -> per-conversation)
+│   ├── SessionManager    # Multi-turn LLM session lifecycle with lex-memory persistence
+│   ├── TokenCache        # In-memory OAuth token cache with pre-expiry refresh (app + delegated slots)
+│   ├── SubscriptionRegistry # Conversation observation subscriptions (in-memory + lex-memory)
+│   ├── BrowserAuth       # Delegated OAuth orchestrator (PKCE, headless detection, browser launch)
+│   └── CallbackServer    # Ephemeral TCP server for OAuth redirect callback
+└── Client                # Standalone client (includes all runners)
+```
+
+## Delegated Authentication (v0.5.0)
+
+Opt-in browser-based OAuth for delegated Microsoft Graph permissions. Two flows:
+
+- **Authorization Code + PKCE** (primary): Opens browser for Entra ID login, captures callback on ephemeral local port, exchanges code with PKCE verification
+- **Device Code** (fallback): Auto-selected in headless/SSH environments (no `DISPLAY`/`WAYLAND_DISPLAY`)
+
+Tokens stored in Vault (`legionio/microsoft_teams/delegated_token`) with configurable pre-expiry silent refresh. CLI command: `legion auth teams`. Sinatra route: `GET /api/oauth/microsoft_teams/callback` for daemon re-auth.
+
+Key files: `Helpers::BrowserAuth` (orchestrator), `Helpers::CallbackServer` (ephemeral TCP), `Runners::Auth` (authorize_url, exchange_code, refresh_delegated_token), `Helpers::TokenCache` (delegated slot).
+
+## AI Bot (v0.2.0)
+
+Two operating modes, both using polling (Graph API) with AMQP-based message routing:
+
+### Mode 1: Direct Chat
+User DMs the bot 1:1. Bot responds via legion-llm with multi-turn session context.
+
+```
+DirectChatPoller (5s) → AMQP exchange → MessageProcessor → Bot::handle_message
+  → SessionManager.get_or_create → llm_session.ask(text) → Graph API reply
+```
+
+### Mode 2: Conversation Observer
+User subscribes the bot to watch a human 1:1 conversation. Bot passively extracts tasks, context, and relationship data.
+
+```
+ObservedChatPoller (30s) → AMQP exchange → MessageProcessor → Bot::observe_message
+  → LLM extraction → lex-memory episodic trace → optional notification to owner
+```
+
+**Observer is disabled by default** (`settings[:bot][:observe][:enabled] = false`). Compliance gate — must be explicitly enabled.
+
+### Message Flow
+
+Both pollers publish to the same `teams.messages` AMQP exchange. The MessageProcessor subscription actor consumes from the queue and routes by `mode` field (`:direct` → `handle_message`, `:observe` → `observe_message`). This architecture supports a future webhook path: a `POST /api/hooks/microsoft_teams/bot` endpoint would publish to the same exchange with zero runner changes.
+
+### Configuration
+
+Layered config cascade in `Legion::Settings[:microsoft_teams]`:
+
+```yaml
+microsoft_teams:
+  auth:
+    tenant_id: "..."
+    client_id: "..."
+    client_secret: "vault://secret/teams/client_secret"
+  bot:
+    bot_id: "28:your-bot-id"
+    direct_poll_interval: 5      # seconds
+    observe_poll_interval: 30    # seconds
+    system_prompt: "You are a helpful assistant."
+    direct:
+      system_prompt: ~           # nil = inherit base
+    observe:
+      enabled: false             # compliance gate
+      notify: false              # DM notifications for action items
+      system_prompt: "Extract action items. Return structured JSON."
+    llm:
+      model: ~                   # nil = use legion-llm router
+      intent:
+        capability: moderate
+    session:
+      flush_threshold: 20        # messages before auto-persist
+      idle_timeout: 900          # seconds (15 min)
+      max_recent_messages: 5     # kept raw on persist
+```
+
+Per-conversation overrides stored in lex-memory (system_prompt_append, llm model/intent).
+
+### Key Design Decisions
+
+- **Polling first, webhook later**: All connections outbound from user's local LegionIO instance. No public endpoint needed.
+- **AMQP-first routing**: Pollers and future webhooks publish to the same exchange. Decouples ingestion from processing.
+- **High-water marks**: Per-chat last-seen timestamp in legion-cache prevents reprocessing. Falls back to in-memory when cache unavailable.
+- **Session persistence**: Multi-turn sessions flush to lex-memory on threshold (20 msgs), idle timeout (15 min), or shutdown. Restored on restart via summary + recent messages.
+- **Token caching**: In-memory OAuth token cache refreshes 60 seconds before expiry. Both pollers share a `TokenCache` instance instead of hitting OAuth every cycle.
+- **Subscription registry**: In-memory working set of observed conversations, persisted to lex-memory on change. No legion-data migration needed.
+- **Design docs**: `docs/plans/2026-03-15-teams-ai-bot-design.md`, `docs/plans/2026-03-15-teams-bot-commands-design.md`
+
+### Bot Commands (v0.3.0)
+
+Keyword-based command detection in bot DMs, checked before LLM response:
+
+| Command | Action |
+|---------|--------|
+| `watch <name>` | Find chat via Graph API, subscribe to observe |
+| `stop watching <name>` / `unwatch <name>` | Unsubscribe |
+| `watching` / `list` / `subscriptions` | List active subscriptions |
+| `pause <name>` | Disable subscription temporarily |
+| `resume <name>` | Re-enable paused subscription |
+| `prefer <value>` | Set preference (concise, detailed, formal, casual, etc.) |
+| `preferences` / `my preferences` | Show current resolved preferences |
+| `reset preferences` | Clear explicit preferences, fall back to observed/defaults |
+| anything else | LLM response (existing flow) |
+
+## API Surface
+
+Four distinct APIs accessed via Faraday + one local data source:
+- **Microsoft Graph API** (`graph.microsoft.com/v1.0`) — chats, channels, messages, teams, subscriptions, presence
+- **Bot Framework Service** (`service_url` per conversation) — send activities, create conversations
+- **Entra ID OAuth** (`login.microsoftonline.com`) — client_credentials token acquisition
+- **Local LevelDB Cache** (Chromium IndexedDB) — offline message extraction from Teams 2.x local storage
+
+## Graph API Permissions Required
+
+| Permission | Type | Purpose |
+|-----------|------|---------|
+| `Chat.Read.All` | Application | Read chat messages |
+| `Chat.ReadWrite.All` | Application | Send chat messages |
+| `ChannelMessage.Read.All` | Application | Read channel messages |
+| `ChannelMessage.Send` | Delegated | Send channel messages |
+| `Team.ReadBasic.All` | Application | List teams and members |
+| `Channel.ReadBasic.All` | Application | List channels |
+| `Presence.Read.All` | Application | Read user presence |
+| `OnlineMeetings.Read` | Delegated | Read online meetings (user context) |
+| `OnlineMeetings.Read.All` | Application | Read online meetings |
+| `OnlineMeetingTranscript.Read.All` | Application/Delegated | Read meeting transcripts |
+
+For bot scenarios, register the Entra app as a Teams Bot via Bot Framework portal.
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `faraday` (>= 2.0) | HTTP client for Graph API, Bot Framework, and OAuth |
+| `snappy` (>= 0.5) | Snappy decompression for LevelDB SSTable blocks |
+| `base64` (>= 0.1) | Base64 encoding for PKCE (removed from Ruby 3.4 default gems) |
+
+Optional framework dependencies (guarded with `defined?`, not in gemspec):
+- `legion-transport` — AMQP exchange/queue/message for bot message routing
+- `legion-llm` — LLM routing for bot responses (`llm_chat`, `llm_session`)
+- `legion-cache` — High-water mark storage for message dedup
+- `lex-memory` — Session persistence and episodic trace storage
+- `lex-mesh` — PreferenceProfile for per-user preference resolution
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec     # 185 specs (as of v0.5.0)
+bundle exec rubocop   # Clean
+```
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Dockerfile

@@ -0,0 +1,6 @@
+FROM legionio/legion
+
+COPY . /usr/src/app/lex-microsoft_teams
+
+WORKDIR /usr/src/app/lex-microsoft_teams
+RUN bundle install

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop'
+  gem 'simplecov'
+end

data/Gemfile.lock

@@ -0,0 +1,103 @@
+PATH
+  remote: .
+  specs:
+    lex-microsoft_teams (0.5.0)
+      base64 (>= 0.1)
+      faraday (>= 2.0)
+      snappy (>= 0.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    faraday (2.14.1)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rspec_junit_formatter (0.6.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    snappy (0.5.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  lex-microsoft_teams!
+  rake
+  rspec
+  rspec_junit_formatter
+  rubocop
+  simplecov
+
+BUNDLED WITH
+   2.6.9

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Esity
+
+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.