lex-microsoft_teams 0.6.45 → 0.6.46

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a1c2dc593a74891fd6a394c6da088eeea72e5c44ec5a13f412dfafe9ce43999
-  data.tar.gz: bd6da610d115de11d6d8196a2f8123044e77089fe2d8ad8ed9b8f27a4a69d4d2
+  metadata.gz: ad43c9c0712ae13673149df6f3a51a7ba24c977bfcef37739fc6caea74d7e989
+  data.tar.gz: 8691eecd15c48afe8849adb1e959d29a19c75b5ddfb9e4083b2070f007de8984
 SHA512:
-  metadata.gz: f90c34c0164a9350f5a5d8b345b508c94fcc45ebc4985c52bf2bef6f42582b2d58bca2681810aed7226f65d6a1f74060bdf842e6587b21614bb7c2cc18d9e7e2
-  data.tar.gz: 5a5c0f04323cd85c10cec26cf259d96c2f0770064e407e760847a412e0e1076da7afc9aabc48bc793c5d7e321393c3affb267d7256f81539e5ddffd1f1db6bb8
+  metadata.gz: 56678da313af129c9d60071cd113fc174c39983122aa4ac9b11a3c8b49e05c29672c347cd1c433a9ea623823085cef41cfa18043fb5b39ccc00329fba89b5636
+  data.tar.gz: 8ecdc1951210be162921639b7eb0c0bf05f7bce9268ea5b0548b4f6f3503869539df632575af822f230e54634a99037a9d8ae30271c96c252ab2978b1daa79a8

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+/Gemfile.lock
 
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
 ## [Unreleased]
+### Fixed
+- Bot response and observation extraction now pass explicit system and user messages to native `Legion::LLM.chat` dispatch instead of routing through the legacy nil-input `llm_chat` helper path.
 
 ## [0.6.45] - 2026-04-23
 

data/CLAUDE.md

@@ -1,273 +1,36 @@
-# lex-microsoft_teams: Microsoft Teams Integration for LegionIO
+# lex-microsoft_teams
 
-**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.6.34
+Microsoft Teams integration via Graph API and Bot Framework. Provides runners for chats, channels, messages, subscriptions, adaptive cards, bot communication (direct + conversation observer), presence, meetings, transcripts, local cache ingestion, cognitive profile pipeline, and delegated OAuth authentication.
 
 ## Architecture
 
 ```
 Legion::Extensions::MicrosoftTeams
-├── Runners/
-│   ├── Auth              # OAuth2 client credentials (Graph + Bot Framework) + auth_callback for hook
-│   ├── 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
-│   ├── People            # Graph API /me and /me/people (profile + relevant contacts)
-│   ├── ProfileIngest     # Four-phase cognitive pipeline (self, people, conversations, teams/meetings)
-│   ├── ApiIngest         # Graph API ingest (top contacts, 1:1 chat messages, HWM dedup)
-│   ├── AiInsights        # Graph API meeting AI insights, recordings, call records
-│   └── Ownership         # Graph API ownership sync
-├── 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
-│   ├── AuthValidator         # Once (90s delay): validates/restores delegated tokens on boot
-│   ├── TokenRefresher        # Every 15min (configurable): keeps delegated tokens fresh
-│   ├── ProfileIngest         # Once (95s delay): four-phase data pipeline after auth
-│   ├── ApiIngest             # Every 30min (95s delay): Graph API ingest with HWM dedup
-│   ├── ChannelPoller         # Every 60s: polls joined team channels for new messages
-│   ├── MeetingIngest         # Every 5min: polls online meetings, fetches transcripts and AI insights
-│   ├── PresencePoller        # Every 60s: polls Graph API presence, logs changes
-│   ├── AbsorbMeeting        # Subscription: absorbs Teams meeting data via absorber framework
-│   └── IncrementalSync       # Every 15min: periodic re-sync with HWM dedup
-├── 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, authenticated?/previously_authenticated? predicates)
-│   ├── SubscriptionRegistry # Conversation observation subscriptions (in-memory + lex-memory)
-│   ├── BrowserAuth       # Delegated OAuth orchestrator (PKCE, headless detection, browser launch, API hook detection)
-│   ├── CallbackServer    # Ephemeral TCP server for OAuth redirect callback
-│   ├── PermissionGuard   # Circuit breaker for 403 errors with exponential backoff
-│   ├── TraceRetriever    # Retrieves memory traces from the shared store for bot context (2000-token budget, strength-ranked dedup)
-│   ├── TransformDefinitions # lex-transformer definitions for conversation extraction and person summary
-│   └── GraphClient       # Graph API wrapper mixin (graph_get, graph_post, graph_paginate, GraphError)
-├── Hooks/
-│   └── Auth              # OAuth callback hook (mount '/callback') → /api/extensions/microsoft_teams/hooks/auth/handle
-├── CLI/
-│   └── Auth              # CLI module for `legion lex exec teams auth login/status`
-└── 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. When the Legion API is running, uses the hook URL (`/api/extensions/microsoft_teams/hooks/auth/handle`) with `Legion::Events` for callback notification; otherwise falls back to an ephemeral local port via `CallbackServer`
-- **Device Code** (fallback): Auto-selected in headless/SSH environments (no `DISPLAY`/`WAYLAND_DISPLAY`)
-
-Tokens stored in Vault at a per-user path (`{USER}/microsoft_teams/delegated_token`, where `{USER}` is the system username) with configurable pre-expiry silent refresh. CLI command: `legion auth teams`. Hook route: `POST /api/extensions/microsoft_teams/hooks/auth/handle` for daemon re-auth (routed through LexDispatch for RBAC/audit).
-
-Key files: `Helpers::BrowserAuth` (orchestrator), `Helpers::CallbackServer` (ephemeral TCP), `Runners::Auth` (authorize_url, exchange_code, refresh_delegated_token, auth_callback), `Helpers::TokenCache` (delegated slot), `Hooks::Auth` (hook class with mount path).
-
-## Token Lifecycle (v0.5.4)
-
-Automatic delegated token management: validate on boot, refresh on a timer, re-authenticate via browser when a previously authenticated user's token expires.
-
-- **AuthValidator** (Once actor, 2s delay): Loads token from Vault/local file on boot, attempts refresh. If refresh fails and user previously authenticated (`previously_authenticated?` — local file exists), fires BrowserAuth. Silent for users who never opted in.
-- **TokenRefresher** (Every actor, 15min default): Guards with `authenticated?` (live token in memory). Refreshes and persists on each tick. On failure, same re-auth logic as AuthValidator.
-- **TokenCache predicates**: `authenticated?` = live token in `@delegated_cache`. `previously_authenticated?` = local token file exists on disk. This distinction controls auto re-auth (returning users only) vs silence (never-authenticated users).
-
-Configuration: `settings[:microsoft_teams][:auth][:delegated][:refresh_interval]` (default 900 seconds).
-
-Design doc: `docs/plans/2026-03-19-teams-token-lifecycle-design.md`
-
-## Cognitive Pipeline (v0.6.0)
-
-Four-phase data ingestion that runs after delegated auth to build the agent's social context:
-
-1. **Self** (`ingest_self`): Fetches `/me` profile and `/me/presence`, stores as identity trace
-2. **People** (`ingest_people`): Fetches `/me/people` (top 25), stores each as semantic trace
-3. **Conversations** (`ingest_conversations`): For top N people, fetches recent chat messages, stores as episodic traces
-4. **Teams & Meetings** (`ingest_teams_and_meetings`): Fetches joined teams and recent meetings, stores as semantic + episodic traces
-
-### Actors
-
-- **ProfileIngest** (Once, 5s delay): Fires `full_ingest` after boot. Only enabled when lex-memory is available and a delegated token exists.
-- **IncrementalSync** (Every, 15min): Fires `incremental_sync` using extended high-water marks for dedup. Configurable via `settings[:microsoft_teams][:ingest][:incremental_interval]`.
-
-### Supporting Components
-
-- **Runners::People**: Graph API `/me` and `/me/people` endpoints with `user_id:` flexibility
-- **Helpers::PermissionGuard**: Circuit breaker for Graph API 403 errors with exponential backoff (60s → 5min → 30min → 2hr → 8hr cap). Wraps API calls via `guarded_request(endpoint) { block }`.
-- **Helpers::TransformDefinitions**: Structured extraction schemas for lex-transformer (`conversation_extract`, `person_summary`)
-- **Extended HWM**: `get/set/update_extended_hwm` with dual timestamps (last_message_at + last_ingested_at) and `persist_hwm_as_trace` / `restore_hwm_from_traces` for cross-boot memory
-
-### CLI
-
-`CLI::Auth` provides `legion lex exec teams auth login` and `legion lex exec teams auth status` via the LEX CLI manifest system. Uses `cli_alias: 'teams'` for short-form dispatch. The Thor command is `invoke_ext` with `exec` as an alias (`run` is a Thor reserved word).
-
-Design doc: `docs/plans/2026-03-20-teams-cognitive-pipeline-implementation.md`
-
-## 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
-  → TraceRetriever.retrieve → SessionManager.get_or_create → llm_session.ask(text) → Graph API reply
-```
-
-`TraceRetriever` (v0.6.17) fetches memory traces from the shared store (sender, teams, chat-scoped domains) before each response. Up to a 2000-token budget; strength-ranked with deduplication. Appended to the resolved system prompt via `PromptResolver#resolve_prompt(trace_context:)`. Degrades gracefully when lex-memory is unavailable.
-
-### 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"
-    delegated:
-      auto_authenticate: false # when true, opens browser OAuth on boot even for first-time users
-      refresh_interval: 900    # seconds (TokenRefresher interval)
-  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.
+├── Runners/        Auth, Teams, Chats, Messages, Channels, ChannelMessages,
+│                   Subscriptions, AdaptiveCards, Bot, Presence, Meetings,
+│                   Transcripts, LocalCache, CacheIngest, People, ProfileIngest,
+│                   ApiIngest, AiInsights, Ownership
+├── Actors/         CacheBulkIngest, CacheSync(5m), DirectChatPoller(5s),
+│                   ObservedChatPoller(30s), MessageProcessor, AuthValidator,
+│                   TokenRefresher(15m), ProfileIngest, ApiIngest(30m),
+│                   ChannelPoller(60s), MeetingIngest(5m), PresencePoller(60s),
+│                   AbsorbMeeting, IncrementalSync(15m)
+├── Transport/      teams.messages exchange + queue
+├── LocalCache/     SSTableReader, RecordParser, Extractor (LevelDB offline)
+├── Helpers/        Client, HighWaterMark, PromptResolver, SessionManager,
+│                   TokenCache, SubscriptionRegistry, BrowserAuth, CallbackServer,
+│                   PermissionGuard, TraceRetriever, TransformDefinitions, GraphClient
+├── Hooks/Auth      OAuth callback hook
+└── CLI/Auth        `legion lex exec teams auth login/status`
+```
+
+## Key Design Decisions
+
+- **Polling first, webhook later**: All connections outbound. 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/work/completed/2026-03-15-teams-ai-bot-design.md`, `docs/work/completed/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 |
-| `People.Read` | Delegated | Read relevant people for cognitive pipeline |
-
-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     # 352 specs across 44 spec files
-bundle exec rubocop   # Clean
-```
-
----
-
-**Maintained By**: Matthew Iverson (@Esity)
+- **High-water marks**: Per-chat last-seen timestamp in legion-cache prevents reprocessing.
+- **Delegated auth**: Browser-based OAuth (PKCE primary, device code fallback for headless). Tokens stored in Vault with silent refresh.
+- **Cognitive pipeline**: Four-phase data ingestion (self, people, conversations, teams/meetings) builds social context after auth.
+- **Observer disabled by default**: Compliance gate (`settings[:bot][:observe][:enabled] = false`).
+- **Session persistence**: Multi-turn sessions flush to lex-memory on threshold/idle/shutdown.
+- **Token lifecycle**: AuthValidator on boot + TokenRefresher every 15min. `authenticated?` vs `previously_authenticated?` controls auto re-auth behavior.

data/lex-microsoft_teams.gemspec

@@ -35,5 +35,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.3.14'
   spec.add_dependency 'legion-transport', '>= 1.3.9'
+  spec.add_dependency 'lex-identity-entra', '>= 0.3.0'
   spec.add_dependency 'snappy', '>= 0.5'
 end

data/lib/legion/extensions/microsoft_teams/absorbers/channel.rb

@@ -10,6 +10,7 @@ module Legion
           description 'Absorbs a Teams channel thread (messages, replies, members) into Apollo'
 
           def absorb(url: nil, content: nil, metadata: {}, context: {}) # rubocop:disable Lint/UnusedMethodArgument
+            log.debug("Channel#absorb url=#{url.inspect}")
             report_progress(message: 'extracting ids from url')
             ids = extract_ids(url)
             return { success: false, error: 'could not extract team/channel ids from url' } unless ids
@@ -36,9 +37,10 @@ module Legion
             ingest_members(team_id, channel_id, channel_name, results)
 
             report_progress(message: 'done', percent: 100)
+            log.info("Channel#absorb complete team_id=#{team_id} channel=#{channel_name} chunks=#{results[:chunks]}")
             results.merge(success: true)
           rescue StandardError => e
-            log.error("Channel absorber failed: #{e.message}")
+            handle_exception(e, level: :error, operation: 'Channel#absorb', url: url)
             { success: false, error: e.message }
           end
 
@@ -53,20 +55,17 @@ module Legion
           end
 
           def graph_token
-            return @graph_token if defined?(@graph_token)
-
-            @graph_token = begin
-              Helpers::TokenCache.instance.cached_delegated_token if defined?(Helpers::TokenCache)
-            rescue StandardError => e
-              log.warn("graph_token unavailable: #{e.message}")
-              nil
-            end
+            Legion::Extensions::Identity::Entra::Helpers::TokenManager.load_token(:delegated)
+          rescue StandardError => e
+            handle_exception(e, level: :debug, operation: 'Channel#graph_token')
+            nil
           end
 
           # Teams channel URL formats:
           #   /l/channel/<encoded_channel_id>/<channel_name>?groupId=<team_id>&...
           #   /l/message/<encoded_channel_id>/<message_id>?groupId=<team_id>&...
           def extract_ids(url)
+            log.debug("Channel#extract_ids url=#{url.inspect}")
             return nil unless url.is_a?(String)
 
             uri    = URI.parse(url)
@@ -86,22 +85,25 @@ module Legion
 
             { team_id: team_id, channel_id: channel_id, message_id: message_id }
           rescue StandardError => e
-            log.debug("extract_ids failed: #{e.message}")
+            handle_exception(e, level: :debug, operation: 'Channel#extract_ids', url: url)
             nil
           end
 
           def resolve_channel(team_id, channel_id)
+            log.debug("Channel#resolve_channel team_id=#{team_id} channel_id=#{channel_id}")
             response = channels_runner.get_channel(team_id: team_id, channel_id: channel_id, token: graph_token)
             body = response.is_a?(Hash) ? response[:result] : nil
             return nil unless body.is_a?(Hash) && !body['error'] && !body[:error]
 
             body
           rescue StandardError => e
-            log.warn("resolve_channel failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Channel#resolve_channel',
+                             team_id: team_id, channel_id: channel_id)
             nil
           end
 
           def ingest_messages(team_id, channel_id, channel_name, results)
+            log.debug("Channel#ingest_messages team_id=#{team_id} channel_id=#{channel_id}")
             report_progress(message: 'fetching channel messages', percent: 25)
             response = channel_messages_runner.list_channel_messages(
               team_id: team_id, channel_id: channel_id, top: 50, token: graph_token
@@ -114,10 +116,12 @@ module Legion
               ingest_single_message(team_id, channel_id, msg, channel_name, results)
             end
           rescue StandardError => e
-            log.warn("Channel message ingest failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Channel#ingest_messages',
+                             team_id: team_id, channel_id: channel_id)
           end
 
           def ingest_thread(team_id, channel_id, message_id, channel_name, results)
+            log.debug("Channel#ingest_thread team_id=#{team_id} channel_id=#{channel_id} message_id=#{message_id}")
             report_progress(message: 'fetching thread root message', percent: 20)
             response = channel_messages_runner.get_channel_message(
               team_id: team_id, channel_id: channel_id, message_id: message_id, token: graph_token
@@ -127,7 +131,8 @@ module Legion
 
             ingest_single_message(team_id, channel_id, body, channel_name, results, scoped_thread: true)
           rescue StandardError => e
-            log.warn("Thread ingest failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Channel#ingest_thread',
+                             team_id: team_id, channel_id: channel_id, message_id: message_id)
           end
 
           def ingest_single_message(team_id, channel_id, msg, channel_name, results, scoped_thread: false)
@@ -135,7 +140,8 @@ module Legion
             return if msg['deletedDateTime'] || msg[:deletedDateTime]
             return if (msg['messageType'] || msg[:messageType]) == 'unknownFutureValue'
 
-            msg_id       = msg['id'] || msg[:id]
+            msg_id = msg['id'] || msg[:id]
+            log.debug("Channel#ingest_single_message msg_id=#{msg_id} channel=#{channel_name}")
             sender       = msg.dig('from', 'user', 'displayName') ||
                            msg.dig(:from, :user, :displayName) ||
                            'unknown'
@@ -166,12 +172,14 @@ module Legion
             )
             results[:chunks] += 1
           rescue StandardError => e
-            log.warn("ingest_single_message failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Channel#ingest_single_message',
+                             msg_id: msg_id, channel: channel_name)
           end
 
           def fetch_reply_lines(team_id, channel_id, message_id)
             return [] unless message_id
 
+            log.debug("Channel#fetch_reply_lines team_id=#{team_id} channel_id=#{channel_id} message_id=#{message_id}")
             response = channel_messages_runner.list_channel_message_replies(
               team_id: team_id, channel_id: channel_id, message_id: message_id, top: 50, token: graph_token
             )
@@ -193,11 +201,13 @@ module Legion
               "  ↳ [#{timestamp}] #{sender}: #{text}"
             end
           rescue StandardError => e
-            log.debug("fetch_reply_lines failed: #{e.message}")
+            handle_exception(e, level: :debug, operation: 'Channel#fetch_reply_lines',
+                             team_id: team_id, channel_id: channel_id, message_id: message_id)
             []
           end
 
           def ingest_members(team_id, channel_id, channel_name, results)
+            log.debug("Channel#ingest_members team_id=#{team_id} channel_id=#{channel_id}")
             report_progress(message: 'fetching channel members', percent: 85)
             response = channels_runner.list_channel_members(
               team_id: team_id, channel_id: channel_id, token: graph_token
@@ -216,8 +226,10 @@ module Legion
               metadata:     { team_id: team_id, channel_id: channel_id, member_count: names.length }
             )
             results[:chunks] += 1
+            log.info("Channel#ingest_members stored #{names.length} members for channel=#{channel_name}")
           rescue StandardError => e
-            log.warn("Member ingest failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Channel#ingest_members',
+                             team_id: team_id, channel_id: channel_id)
           end
         end
       end

data/lib/legion/extensions/microsoft_teams/absorbers/chat.rb

@@ -10,6 +10,7 @@ module Legion
           description 'Absorbs a Teams chat thread (messages, replies, participants) into Apollo'
 
           def absorb(url: nil, content: nil, metadata: {}, context: {}) # rubocop:disable Lint/UnusedMethodArgument
+            log.debug("Chat#absorb url=#{url.inspect}")
             report_progress(message: 'extracting chat id from url')
             chat_id = extract_chat_id(url)
             return { success: false, error: 'could not extract chat id from url' } unless chat_id
@@ -25,9 +26,10 @@ module Legion
             ingest_members(chat_id, topic, results)
 
             report_progress(message: 'done', percent: 100)
+            log.info("Chat#absorb complete chat_id=#{chat_id} topic=#{topic} chunks=#{results[:chunks]}")
             results.merge(success: true)
           rescue StandardError => e
-            log.error("Chat absorber failed: #{e.message}")
+            handle_exception(e, level: :error, operation: 'Chat#absorb', url: url)
             { success: false, error: e.message }
           end
 
@@ -42,17 +44,14 @@ module Legion
           end
 
           def graph_token
-            return @graph_token if defined?(@graph_token)
-
-            @graph_token = begin
-              Helpers::TokenCache.instance.cached_delegated_token if defined?(Helpers::TokenCache)
-            rescue StandardError => e
-              log.warn("graph_token unavailable: #{e.message}")
-              nil
-            end
+            Legion::Extensions::Identity::Entra::Helpers::TokenManager.load_token(:delegated)
+          rescue StandardError => e
+            handle_exception(e, level: :debug, operation: 'Chat#graph_token')
+            nil
           end
 
           def extract_chat_id(url)
+            log.debug("Chat#extract_chat_id url=#{url.inspect}")
             return nil unless url.is_a?(String)
 
             # teams.microsoft.com/l/chat/19:XXXXX@unq.gbl.spaces/...
@@ -61,22 +60,24 @@ module Legion
 
             URI.decode_uri_component(match[1])
           rescue StandardError => e
-            log.debug("extract_chat_id failed: #{e.message}")
+            handle_exception(e, level: :debug, operation: 'Chat#extract_chat_id', url: url)
             nil
           end
 
           def resolve_chat(chat_id)
+            log.debug("Chat#resolve_chat chat_id=#{chat_id}")
             response = chats_runner.get_chat(chat_id: chat_id, token: graph_token)
             body = response.is_a?(Hash) ? response[:result] : nil
             return nil unless body.is_a?(Hash) && !body['error'] && !body[:error]
 
             body
           rescue StandardError => e
-            log.warn("resolve_chat failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Chat#resolve_chat', chat_id: chat_id)
             nil
           end
 
           def ingest_messages(chat_id, topic, results)
+            log.debug("Chat#ingest_messages chat_id=#{chat_id} topic=#{topic}")
             report_progress(message: 'fetching messages', percent: 25)
             response = messages_runner.list_chat_messages(chat_id: chat_id, top: 50, token: graph_token)
             body = response.is_a?(Hash) ? response[:result] : nil
@@ -118,13 +119,15 @@ module Legion
               content_type: 'teams_chat_thread'
             )
             results[:chunks] += 1
+            log.info("Chat#ingest_messages stored #{lines.length} lines for chat_id=#{chat_id}")
           rescue StandardError => e
-            log.warn("Message ingest failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Chat#ingest_messages', chat_id: chat_id)
           end
 
           def fetch_reply_lines(chat_id, message_id, _topic)
             return [] unless message_id
 
+            log.debug("Chat#fetch_reply_lines chat_id=#{chat_id} message_id=#{message_id}")
             response = messages_runner.list_message_replies(
               chat_id: chat_id, message_id: message_id, top: 50, token: graph_token
             )
@@ -146,11 +149,13 @@ module Legion
               "  ↳ [#{timestamp}] #{sender}: #{text}"
             end
           rescue StandardError => e
-            log.debug("fetch_reply_lines failed: #{e.message}")
+            handle_exception(e, level: :debug, operation: 'Chat#fetch_reply_lines',
+                             chat_id: chat_id, message_id: message_id)
             []
           end
 
           def ingest_members(chat_id, topic, results)
+            log.debug("Chat#ingest_members chat_id=#{chat_id} topic=#{topic}")
             report_progress(message: 'fetching members', percent: 80)
             response = chats_runner.list_chat_members(chat_id: chat_id, token: graph_token)
             body = response.is_a?(Hash) ? response[:result] : nil
@@ -171,8 +176,9 @@ module Legion
               metadata:     { chat_id: chat_id, participant_count: names.length }
             )
             results[:chunks] += 1
+            log.info("Chat#ingest_members stored #{names.length} participants for chat_id=#{chat_id}")
           rescue StandardError => e
-            log.warn("Member ingest failed: #{e.message}")
+            handle_exception(e, level: :warn, operation: 'Chat#ingest_members', chat_id: chat_id)
           end
         end
       end