legion-gaia 0.9.5 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efed783ab1973e460903a13135c6f62d93b9c54ca7cf5ed8f61c96735d490c4b
-  data.tar.gz: bf179f50d2832f0895e61407c7f8feb926b7cfcca02d937c285fc365de44f957
+  metadata.gz: 0c3da92d298e78cdfe5d70612f088c2a75c6625504d1199b1d4083b17422c6d5
+  data.tar.gz: de1209bf2e347ee942f3a154e37bfbd6f0cb26e0d137409abb3baf88565b2052
 SHA512:
-  metadata.gz: bde01efb8ad647c4fba8b94ec554ab1b77e77a0a30d9d34cc5784970dcb3b0ccee1e443ee1373269d910ae5c3b0020025d8c43d4fd82739f757af2f115dd6c1d
-  data.tar.gz: 04be62afef65aeb62173b4fcefe88e001169bc6a06ed2b3646fb1c0a3b03634232ec62e2d0f3be3f824b49dfb89940a9896cbd79958d31ff2f0cd3df0ee69900
+  metadata.gz: 4b99fd09215fb9af18e764bcd15e0bd3255a4d6218e9800acef5907447d27ba6538e0f1d764f5ecfaa0db4614a4bebb65294190871985317f99a5881e8b3170d
+  data.tar.gz: 031cf83da2817f3eff55d343eb44702649c7d9116d92e6254555ab4d954c72ddb66cf1c15da7f5c8e003535127675ea4e478afd5b0b7d9f428ae1721b7085d3e

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.9.6] - 2026-03-19
+
+### Added
+- `Legion::Gaia::Proactive.send_to_user` — delivers a proactive message to a user across one channel or all known channels, using `deliver_proactive` when the adapter supports it
+- `Legion::Gaia::Proactive.send_notification` — routes a notification through the OutputRouter (respects NotificationGate quiet hours, presence, and behavioral scoring); supports :ambient/:normal/:urgent/:critical priority
+- `Legion::Gaia::Proactive.start_conversation` — initiates an agent-started conversation with a user who has not messaged first; delegates to `deliver_proactive` on adapters that support it
+- `TeamsAdapter#deliver_proactive` — resolves an existing conversation reference by user (via tenant match) or creates a new one via Bot Framework `POST /v3/conversations`; delivers the OutputFrame proactively
+- `TeamsAdapter#create_proactive_conversation` — creates a new Bot Framework conversation and stores the resulting reference in ConversationStore
+- `ConversationStore::UserProfile` — new `Data.define` value object storing `user_id`, `service_url`, `tenant_id` at the user level
+- `ConversationStore#store_user_profile` / `#lookup_user_profile` — store and retrieve user-level service URL and tenant from any prior activity
+- `ConversationStore#conversations_for_user` — returns all conversation references whose tenant matches the user's stored profile (enables cross-conversation proactive targeting)
+- `ConversationStore#store_from_activity` now also populates the user profile from the `from.id` field
+- `SlackAdapter#open_dm` — opens a Slack DM channel via `conversations.open` API (requires `im:write` scope and `bot_token`)
+- `SlackAdapter#deliver_proactive` — opens a DM for the target user then delivers the OutputFrame via bot token API
+- 22 new specs (366 total) covering all new proactive methods across Proactive module, TeamsAdapter, SlackAdapter, and ConversationStore
+
 ## [0.9.5] - 2026-03-20
 
 ### Fixed

data/lib/legion/gaia/channels/slack_adapter.rb

@@ -50,6 +50,33 @@ module Legion
           deliver_via_webhook(rendered_content, target_webhook)
         end
 
+        def deliver_proactive(output_frame)
+          user_id = output_frame.metadata[:target_user]
+          return { error: :no_target_user } unless user_id
+
+          dm_result = open_dm(user_id: user_id)
+          return dm_result if dm_result.is_a?(Hash) && dm_result[:error]
+
+          channel = dm_result[:channel_id]
+          rendered = translate_outbound(output_frame).merge(channel: channel)
+          deliver_via_api_to_channel(rendered)
+        end
+
+        def open_dm(user_id:)
+          return { error: :no_bot_token } unless @bot_token
+          return { error: :slack_runner_not_available } unless slack_runner_available?
+
+          result = Legion::Extensions::Slack::Runners::Chat.open_dm(
+            user_id: user_id,
+            token: @bot_token
+          )
+          return result if result.is_a?(Hash) && result[:error]
+
+          { channel_id: result[:channel_id] || result['channel']&.dig('id') || result['channel'] }
+        rescue StandardError => e
+          { error: :open_dm_failed, message: e.message }
+        end
+
         def verify_request(signing_secret: nil, timestamp: nil, body: nil, signature: nil)
           secret = signing_secret || @signing_secret
           return { valid: false, error: :no_signing_secret } unless secret
@@ -93,6 +120,21 @@ module Legion
           { error: :not_implemented, message: 'Bot token API delivery not yet implemented' }
         end
 
+        def deliver_via_api_to_channel(content)
+          unless slack_runner_available?
+            return { error: :slack_runner_not_available,
+                     message: 'lex-slack Chat runner not loaded' }
+          end
+
+          message = content.is_a?(Hash) ? content[:text] : content.to_s
+          channel = content.is_a?(Hash) ? content[:channel] : nil
+          Legion::Extensions::Slack::Runners::Chat.send(
+            message: message,
+            channel: channel,
+            token: @bot_token
+          )
+        end
+
         def slack_runner_available?
           defined?(Legion::Extensions::Slack::Runners::Chat)
         end

data/lib/legion/gaia/channels/teams/conversation_store.rb

@@ -13,8 +13,15 @@ module Legion
             end
           end
 
+          UserProfile = Data.define(:user_id, :service_url, :tenant_id, :updated_at) do
+            def initialize(user_id:, service_url:, tenant_id: nil, updated_at: Time.now.utc)
+              super
+            end
+          end
+
           def initialize
             @references = {}
+            @user_profiles = {}
             @mutex = Mutex.new
           end
 
@@ -30,14 +37,25 @@ module Legion
             end
           end
 
+          def store_user_profile(user_id:, service_url:, tenant_id: nil)
+            return unless user_id && service_url
+
+            @mutex.synchronize do
+              @user_profiles[user_id] = UserProfile.new(
+                user_id: user_id,
+                service_url: service_url,
+                tenant_id: tenant_id
+              )
+            end
+          end
+
           def store_from_activity(activity)
-            conversation = activity['conversation'] || activity[:conversation] || {}
-            store(
-              conversation_id: conversation['id'] || conversation[:id],
-              service_url: activity['serviceUrl'] || activity[:serviceUrl],
-              tenant_id: conversation['tenantId'] || conversation[:tenantId],
-              bot_id: (activity['recipient'] || activity[:recipient] || {})['id'],
-              activity_id: activity['id'] || activity[:id]
+            parsed = parse_activity(activity)
+            store(**parsed.slice(:conversation_id, :service_url, :tenant_id, :bot_id, :activity_id))
+            store_user_profile(
+              user_id: parsed[:user_id],
+              service_url: parsed[:service_url],
+              tenant_id: parsed[:tenant_id]
             )
           end
 
@@ -45,6 +63,16 @@ module Legion
             @mutex.synchronize { @references[conversation_id] }
           end
 
+          def lookup_user_profile(user_id)
+            @mutex.synchronize { @user_profiles[user_id] }
+          end
+
+          def conversations_for_user(user_id)
+            @mutex.synchronize do
+              @references.values.select { |ref| ref.tenant_id && user_related?(ref, user_id) }
+            end
+          end
+
           def remove(conversation_id)
             @mutex.synchronize { @references.delete(conversation_id) }
           end
@@ -58,7 +86,37 @@ module Legion
           end
 
           def clear
-            @mutex.synchronize { @references.clear }
+            @mutex.synchronize do
+              @references.clear
+              @user_profiles.clear
+            end
+          end
+
+          private
+
+          def user_related?(ref, user_id)
+            profile = @user_profiles[user_id]
+            return false unless profile
+
+            profile.tenant_id == ref.tenant_id
+          end
+
+          def parse_activity(activity)
+            conversation = fetch(activity, 'conversation') || {}
+            recipient = fetch(activity, 'recipient') || {}
+            from = fetch(activity, 'from') || {}
+            {
+              conversation_id: fetch(conversation, 'id'),
+              service_url: fetch(activity, 'serviceUrl'),
+              tenant_id: fetch(conversation, 'tenantId'),
+              bot_id: recipient['id'],
+              activity_id: fetch(activity, 'id'),
+              user_id: from['id']
+            }
+          end
+
+          def fetch(hash, string_key)
+            hash[string_key] || hash[string_key.to_sym]
           end
         end
       end

data/lib/legion/gaia/channels/teams_adapter.rb

@@ -63,6 +63,44 @@ module Legion
           deliver_via_bot(rendered_content, ref)
         end
 
+        def deliver_proactive(output_frame)
+          user_id = output_frame.metadata[:target_user]
+          return { error: :no_target_user } unless user_id
+
+          conversation_id = resolve_proactive_conversation(user_id)
+          return conversation_id if conversation_id.is_a?(Hash) && conversation_id[:error]
+
+          rendered = translate_outbound(output_frame)
+          deliver(rendered, conversation_id: conversation_id)
+        end
+
+        def create_proactive_conversation(user_id:, tenant_id: nil)
+          profile = conversation_store.lookup_user_profile(user_id)
+          service_url = profile&.service_url
+          resolved_tenant = tenant_id || profile&.tenant_id
+          return { error: :no_service_url } unless service_url
+          return { error: :bot_runner_not_available } unless bot_runner_available?
+
+          bot = Legion::Extensions::MicrosoftTeams::Client.new
+          result = bot.create_conversation(
+            service_url: service_url,
+            bot_id: app_id,
+            user_id: user_id,
+            tenant_id: resolved_tenant
+          )
+          return result if result.is_a?(Hash) && result[:error]
+
+          conversation_id = result[:conversation_id] || result['id']
+          conversation_store.store(
+            conversation_id: conversation_id,
+            service_url: service_url,
+            tenant_id: resolved_tenant
+          )
+          conversation_id
+        rescue StandardError => e
+          { error: :create_conversation_failed, message: e.message }
+        end
+
         def validate_inbound(token, allow_emulator: false)
           return { valid: false, error: :no_app_id } unless app_id
 
@@ -147,6 +185,13 @@ module Legion
         def bot_runner_available?
           defined?(Legion::Extensions::MicrosoftTeams::Client)
         end
+
+        def resolve_proactive_conversation(user_id)
+          existing = conversation_store.conversations_for_user(user_id)
+          return existing.first.conversation_id unless existing.empty?
+
+          create_proactive_conversation(user_id: user_id)
+        end
       end
     end
   end

data/lib/legion/gaia/proactive.rb

@@ -24,6 +24,82 @@ module Legion
           { error: e.message }
         end
 
+        def send_to_user(user_id:, content:, channel_id: nil, content_type: :text)
+          registry = Legion::Gaia.channel_registry
+          return { error: 'channel registry not available' } unless registry
+
+          if channel_id
+            deliver_to_user_on_channel(
+              registry: registry,
+              user_id: user_id,
+              channel_id: channel_id,
+              content: content,
+              content_type: content_type
+            )
+          else
+            deliver_to_user_all_channels(
+              registry: registry,
+              user_id: user_id,
+              content: content,
+              content_type: content_type
+            )
+          end
+        rescue StandardError => e
+          { error: e.message }
+        end
+
+        def send_notification(content:, priority: :normal, channel_id: nil, user_id: nil)
+          registry = Legion::Gaia.channel_registry
+          return { error: 'channel registry not available' } unless registry
+
+          output_router = Legion::Gaia.output_router
+          return { error: 'output router not available' } unless output_router
+
+          channels = channel_id ? [channel_id] : registry.active_channels
+          results = {}
+
+          channels.each do |ch|
+            adapter = registry.adapter_for(ch)
+            next unless adapter
+
+            frame = OutputFrame.new(
+              content: content,
+              channel_id: ch,
+              metadata: { proactive: true, priority: priority, target_user: user_id }
+            )
+            results[ch] = output_router.route(frame)
+          end
+
+          results
+        rescue StandardError => e
+          { error: e.message }
+        end
+
+        def start_conversation(channel_id:, user_id:, content:)
+          registry = Legion::Gaia.channel_registry
+          return { error: 'channel registry not available' } unless registry
+
+          adapter = registry.adapter_for(channel_id)
+          return { error: "no adapter for channel: #{channel_id}" } unless adapter
+
+          frame = OutputFrame.new(
+            content: content,
+            channel_id: channel_id,
+            metadata: { proactive: true, target_user: user_id, start_conversation: true }
+          )
+
+          if adapter.respond_to?(:deliver_proactive)
+            result = adapter.deliver_proactive(frame)
+            return result if result.is_a?(Hash) && result[:error]
+
+          else
+            registry.deliver(frame)
+          end
+          { started: true, channel: channel_id, user_id: user_id }
+        rescue StandardError => e
+          { error: e.message }
+        end
+
         def broadcast(content:, channels: nil)
           registry = Legion::Gaia.channel_registry
           return { error: 'channel registry not available' } unless registry
@@ -35,6 +111,46 @@ module Legion
           end
           results
         end
+
+        private
+
+        def deliver_to_user_on_channel(registry:, user_id:, channel_id:, content:, content_type:)
+          adapter = registry.adapter_for(channel_id)
+          return { error: "no adapter for channel: #{channel_id}" } unless adapter
+
+          frame = OutputFrame.new(
+            content: content,
+            content_type: content_type,
+            channel_id: channel_id,
+            metadata: { proactive: true, target_user: user_id }
+          )
+
+          if adapter.respond_to?(:deliver_proactive)
+            result = adapter.deliver_proactive(frame)
+            return result if result.is_a?(Hash) && result[:error]
+          else
+            registry.deliver(frame)
+          end
+
+          { sent: true, frame_id: frame.id, channel: channel_id, user_id: user_id }
+        end
+
+        def deliver_to_user_all_channels(registry:, user_id:, content:, content_type:)
+          channels = registry.active_channels
+          return { error: 'no active channels' } if channels.empty?
+
+          results = {}
+          channels.each do |ch|
+            results[ch] = deliver_to_user_on_channel(
+              registry: registry,
+              user_id: user_id,
+              channel_id: ch,
+              content: content,
+              content_type: content_type
+            )
+          end
+          { sent: true, results: results }
+        end
       end
     end
   end

data/lib/legion/gaia/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Gaia
-    VERSION = '0.9.5'
+    VERSION = '0.9.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-gaia
 version: !ruby/object:Gem::Version
-  version: 0.9.5
+  version: 0.9.6
 platform: ruby
 authors:
 - Esity