collavre 0.3.2 → 0.5.0

data/app/services/collavre/markdown_converter.rb

@@ -0,0 +1,240 @@
+require "base64"
+require "securerandom"
+require "nokogiri"
+
+module Collavre
+  # Converts between Markdown and HTML for creative descriptions.
+  #
+  # Extracted from CreativesHelper to keep conversion logic testable
+  # outside of view contexts and reusable from services (e.g. MarkdownImporter).
+  class MarkdownConverter
+    class << self
+      # Convert lightweight Markdown (links, bold, images) to HTML.
+      def markdown_to_html(text, image_refs = {})
+        return "" if text.nil?
+        html = text.dup
+
+        # Collect reference-style data-URI images: [alt]: <data:...>
+        html.gsub!(/^\s*\[([^\]]+)\]:\s*<\s*(data:image\/[^>]+)\s*>\s*$/) do
+          image_refs[$1] = $2.strip
+          ""
+        end
+
+        # Reference-style images: ![alt][ref]
+        html.gsub!(/(?<!\\)!\[([^\]]*)\]\[([^\]]+)\]/) do
+          if (data_url = image_refs[$2])
+            data_image_to_attachment(data_url, $1)
+          else
+            "![#{$1}][#{$2}]"
+          end
+        end
+
+        # Inline data-URI images: ![alt](data:...)
+        html.gsub!(/(?<!\\)!\[([^\]]*)\]\((data:image\/[^)]+)\)/) do
+          data_image_to_attachment($2, $1)
+        end
+
+        # Inline links: [text](url)
+        html.gsub!(/(?<!\\)\[([^\]]+)\]\(([^)]+)\)/) do
+          "<a href=\"#{$2}\">#{$1}</a>"
+        end
+
+        # Bold: **text** or __text__
+        html.gsub!(/(?<!\\)(\*\*|__)(.+?)\1/m) do
+          "<strong>#{$2}</strong>"
+        end
+
+        # Unescape backslash-escaped chars
+        html.gsub!(/\\([\\*_\[\]()!#~+\-])/, '\\1')
+        html.gsub!(/\\\\/, "\\")
+        html.strip!
+        html
+      end
+
+      # Convert HTML (links, bold, images, tables) back to Markdown.
+      def html_to_markdown(text)
+        return "" if text.nil?
+        markdown = text.dup
+        placeholders = {}
+        index = 0
+
+        # Tables → Markdown tables
+        markdown.gsub!(%r{<table\b[^>]*>.*?</table>}im) do |match|
+          token = "__TABLE#{index}__"; index += 1
+          placeholders[token] = table_to_markdown(match)
+          token
+        end
+
+        # Action-text attachments → data-URI images
+        markdown.gsub!(%r{<action-text-attachment ([^>]+)>(?:</action-text-attachment>)?}) do |_match|
+          attrs = Hash[$1.scan(/(\S+?)="([^"]*)"/)]
+          sgid = attrs["sgid"]
+          caption = attrs["caption"] || ""
+          if (blob = GlobalID::Locator.locate_signed(sgid, for: "attachable"))
+            data = Base64.strict_encode64(blob.download)
+            token = "__IMG#{index}__"; index += 1
+            placeholders[token] = "![#{caption}](data:#{blob.content_type};base64,#{data})"
+            token
+          else
+            ""
+          end
+        end
+
+        # Active Storage blob images → data-URI
+        markdown.gsub!(%r{<img [^>]*src=["'](/rails/active_storage/blobs/[^"']+)["'][^>]*alt=["']([^"']*)["'][^>]*>}) do |match|
+          blob_path = $1
+          alt_text = $2
+          if blob_path =~ %r{/rails/active_storage/blobs/(?:redirect|proxy)/([^/]+)/}
+            signed_id = $1
+            begin
+              blob = ActiveStorage::Blob.find_signed(signed_id)
+              data = Base64.strict_encode64(blob.download)
+              token = "__IMG#{index}__"; index += 1
+              placeholders[token] = "![#{alt_text}](data:#{blob.content_type};base64,#{data})"
+              token
+            rescue
+              match
+            end
+          else
+            match
+          end
+        end
+
+        # Inline data-URI images (src before alt)
+        markdown.gsub!(/<img [^>]*src=['"](data:[^'"]+)['"][^>]*alt=['"]([^'"]*)['"][^>]*>/) do
+          token = "__IMG#{index}__"; index += 1
+          placeholders[token] = "![#{$2}](#{$1})"
+          token
+        end
+
+        # Inline data-URI images (alt before src)
+        markdown.gsub!(/<img [^>]*alt=['"]([^'"]*)['"][^>]*src=['"](data:[^'"]+)['"][^>]*>/) do
+          token = "__IMG#{index}__"; index += 1
+          placeholders[token] = "![#{$1}](#{$2})"
+          token
+        end
+
+        # Links → [text](url)
+        markdown.gsub!(/<a [^>]*href=['"]([^'"]+)['"][^>]*>(.*?)<\/a>/m) do
+          inner = ActionView::Base.full_sanitizer.sanitize($2)
+          token = "__LINK#{index}__"; index += 1
+          placeholders[token] = "[#{inner}](#{$1})"
+          token
+        end
+
+        # Bold → **text**
+        markdown.gsub!(/<(strong|b)(?:\s+[^>]*)?>(.*?)<\/\1>/im) do
+          token = "__BOLD#{index}__"; index += 1
+          placeholders[token] = "**#{$2.strip}**"
+          token
+        end
+
+        # Escape markdown special chars in remaining text
+        markdown.gsub!(/([\\*\[\]()!#~+\-])/) { "\\#{$1}" }
+
+        # Restore placeholders
+        placeholders.each { |k, v| markdown.gsub!(k, v) }
+
+        # Strip remaining HTML tags
+        markdown.gsub!(/<[^>]+>/, "")
+        markdown
+      end
+
+      # Check whether text looks like a Markdown table block.
+      def table_block?(text)
+        lines = text.to_s.strip.split("\n")
+        return false if lines.length < 2
+
+        header_line = lines[0]
+        alignment_line = lines[1]
+        return false unless header_line.match?(/\A\|.*\|\z/)
+        return false unless alignment_line.match?(/\A\|[ \-:\|]+\|\z/)
+
+        true
+      end
+
+      # Convert an HTML <table> fragment to a Markdown table string.
+      def table_to_markdown(table_html)
+        fragment = Nokogiri::HTML::DocumentFragment.parse(table_html)
+        table = fragment.at_css("table")
+        return "" unless table
+
+        header_row = table.at_css("thead tr") || table.css("tr").first
+        return "" unless header_row
+
+        header_cells = header_row.css("th,td")
+        headers = header_cells.map { |cell| escape_table_cell(html_to_markdown(cell.inner_html).strip) }
+        alignments = header_cells.map { |cell| alignment_from_cell(cell) }
+
+        body_rows = table.css("tbody tr")
+        if body_rows.empty?
+          all_rows = table.css("tr")
+          body_rows = all_rows.drop(1)
+        end
+
+        body_lines = body_rows.map do |row|
+          cells = row.css("th,td").map { |cell| escape_table_cell(html_to_markdown(cell.inner_html).strip) }
+          normalized = pad_cells(cells, headers.length)
+          "| #{normalized.join(' | ')} |"
+        end
+
+        alignment_cells = pad_cells(alignments, headers.length).map { |align| alignment_marker(align) }
+        header_line = "| #{headers.map(&:strip).join(' | ')} |"
+        alignment_line = "| #{alignment_cells.join(' | ')} |"
+
+        ([ header_line, alignment_line ] + body_lines).join("\n")
+      end
+
+      # Convert a data-URI image to an Active Storage attachment <img> tag.
+      def data_image_to_attachment(data_url, alt)
+        if data_url =~ %r{\Adata:(image/[\w.+-]+);base64,(.+)\z}
+          content_type = Regexp.last_match(1)
+          data = Base64.decode64(Regexp.last_match(2))
+          ext = Mime::Type.lookup(content_type).symbol.to_s
+          filename = "import-#{SecureRandom.hex}.#{ext}"
+          blob = ActiveStorage::Blob.create_and_upload!(io: StringIO.new(data), filename: filename, content_type: content_type)
+          "<img src=\"#{Rails.application.routes.url_helpers.rails_blob_url(blob, only_path: true)}\" alt=\"#{alt}\" />"
+        else
+          "<img src=\"#{data_url}\" alt=\"#{alt}\" />"
+        end
+      end
+
+      private
+
+      def escape_table_cell(text)
+        text.to_s.gsub(/(?<!\\)\|/, '\\|')
+      end
+
+      def alignment_from_cell(cell)
+        style = cell["style"].to_s
+        align = cell["align"].to_s
+        case
+        when style =~ /text-align\s*:\s*center/i || align =~ /center/i
+          :center
+        when style =~ /text-align\s*:\s*right/i || align =~ /right/i
+          :right
+        when style =~ /text-align\s*:\s*left/i || align =~ /left/i
+          :left
+        else
+          nil
+        end
+      end
+
+      def alignment_marker(alignment)
+        case alignment
+        when :center then ":---:"
+        when :right  then "---:"
+        when :left   then ":---"
+        else "---"
+        end
+      end
+
+      def pad_cells(cells, expected_length)
+        values = cells.dup
+        values = values.first(expected_length)
+        values.fill("", values.length...expected_length)
+        values
+      end
+    end
+  end
+end

data/app/services/collavre/mention_parser.rb

@@ -0,0 +1,63 @@
+module Collavre
+  # Centralized mention parsing and resolution.
+  # All @mention logic should go through this module so changes
+  # to the mention format only need to be made in one place.
+  module MentionParser
+    # Characters allowed before @ in mentions (besides start-of-text)
+    MENTION_PREFIX_CHARS = /[\s:.,;\n\r]/
+
+    # Canonical mention: @name: (with colon separator)
+    # Matches at start of text or after whitespace/punctuation/newline
+    MENTION_PATTERN = /(?:\A|(?<=#{MENTION_PREFIX_CHARS}))@([^:]+?):\s*/
+
+    # Mention without colon: @name followed by whitespace (start-of-text only
+    # to avoid false positives like email addresses)
+    MENTION_LOOSE_PATTERN = /\A@(\S+)\s+/
+
+    # Scan pattern: finds all @name: mentions anywhere in text
+    MENTION_SCAN_PATTERN = /(?:^|(?<=#{MENTION_PREFIX_CHARS}))@([^:]+?):/
+
+    # Extract the first mentioned name from text (returns nil if no mention found)
+    def self.extract_name(text)
+      return nil if text.blank?
+
+      match = text.match(MENTION_PATTERN) || text.match(MENTION_LOOSE_PATTERN)
+      match ? match[1].strip : nil
+    end
+
+    # Extract all mentioned names from text
+    def self.extract_all_names(text)
+      return [] if text.blank?
+
+      text.scan(MENTION_SCAN_PATTERN).flatten.map(&:strip).uniq
+    end
+
+    # Find a User by case-insensitive name match
+    def self.find_user_by_name(name)
+      return nil if name.blank?
+
+      User.where("LOWER(name) = ?", name.strip.downcase).first
+    end
+
+    # Extract mention and resolve to a User in one step
+    def self.resolve_user(text)
+      name = extract_name(text)
+      name ? find_user_by_name(name) : nil
+    end
+
+    # Resolve all mentioned users from text (finds mentions anywhere)
+    def self.resolve_all_users(text)
+      extract_all_names(text).filter_map { |name| find_user_by_name(name) }.uniq
+    end
+
+    # Strip self-mention prefix from text (both @name: and @name formats)
+    def self.strip_self_mention(text, agent_name)
+      return text if text.blank? || agent_name.blank?
+
+      escaped = Regexp.escape(agent_name)
+      text
+        .sub(/\A@#{escaped}:\s*/i, "")
+        .sub(/\A@#{escaped}\s+/i, "")
+    end
+  end
+end

data/app/services/collavre/orchestration/agent_context_builder.rb

@@ -19,10 +19,11 @@ module Collavre
         "read" => "reference"       # Can request information from
       }.freeze
 
-      def initialize(agent:, creative:, sender: nil)
+      def initialize(agent:, creative:, sender: nil, policy_resolver: nil)
         @agent = agent
         @creative = creative
         @sender = sender
+        @policy_resolver = policy_resolver
       end
 
       def a2a_request?
@@ -45,6 +46,7 @@ module Collavre
       # Generates markdown-formatted collaboration section for system prompt
       def to_collaboration_prompt
         sections = []
+        collab = collaboration_policy_config
 
         # Add A2A request context if this is an agent-to-agent call
         if a2a_request?
@@ -52,9 +54,16 @@ module Collavre
           sections << ""
           sections << I18n.t("collavre.ai_agent.a2a.request_description",
                              sender_name: @sender["name"], sender_type: @sender["type"])
-          sections << I18n.t("collavre.ai_agent.a2a.focus_instruction")
-          sections << I18n.t("collavre.ai_agent.a2a.completion_instruction")
-          sections << I18n.t("collavre.ai_agent.a2a.followup_instruction")
+          sections << (collab["a2a_focus_instruction"] || I18n.t("collavre.ai_agent.a2a.focus_instruction"))
+          sections << (collab["a2a_completion_instruction"] ||
+                       I18n.t("collavre.ai_agent.a2a.completion_instruction",
+                              sender_name: @sender["name"]))
+          sections << (collab["a2a_followup_instruction"] || I18n.t("collavre.ai_agent.a2a.followup_instruction"))
+          sections << ""
+        elsif @sender
+          # Human-triggered request: instruct agent to report back
+          sections << I18n.t("collavre.ai_agent.a2a.human_completion_instruction",
+                             sender_name: @sender["name"])
           sections << ""
         end
 
@@ -100,10 +109,13 @@ module Collavre
         end
 
         sections << I18n.t("collavre.ai_agent.collaboration.rules_header")
-        sections << I18n.t("collavre.ai_agent.collaboration.mention_rule")
-        sections << I18n.t("collavre.ai_agent.collaboration.confidence_rule")
-        sections << I18n.t("collavre.ai_agent.collaboration.escalation_rule")
-        sections << I18n.t("collavre.ai_agent.collaboration.review_rule")
+        sections << (collab["mention_rule"] || I18n.t("collavre.ai_agent.collaboration.mention_rule"))
+        sections << (collab["confidence_rule"] || I18n.t("collavre.ai_agent.collaboration.confidence_rule"))
+        if @policy_resolver&.self_reflection_enabled?
+          sections << I18n.t("collavre.ai_agent.collaboration.confidence_format_instruction")
+        end
+        sections << (collab["escalation_rule"] || I18n.t("collavre.ai_agent.collaboration.escalation_rule"))
+        sections << (collab["review_rule"] || I18n.t("collavre.ai_agent.collaboration.review_rule"))
         sections << ""
 
         sections.join("\n")
@@ -196,6 +208,10 @@ module Collavre
           "review_hint" => I18n.t("collavre.ai_agent.collaboration.review_rule")
         }
       end
+
+      def collaboration_policy_config
+        @policy_resolver&.collaboration_config || {}
+      end
     end
   end
 end

data/app/services/collavre/orchestration/agent_orchestrator.rb

@@ -23,6 +23,7 @@ module Collavre
         updated = Task.where(id: task.id, status: "queued").update_all(status: "pending")
         if updated > 0
           task.reload
+          cleanup_waiting_notices!(task)
           refresh_deferred_context!(task)
 
           if task.status == "cancelled"
@@ -35,6 +36,19 @@ module Collavre
         end
       end
 
+      # Remove waiting notice comments (system messages) for this task's creative/topic.
+      def self.cleanup_waiting_notices!(task)
+        context = task.trigger_event_payload
+        creative_id = context&.dig("creative", "id")
+        topic_id = context&.dig("topic", "id")
+        return unless creative_id
+
+        Comment.where(creative_id: creative_id, topic_id: topic_id, user_id: nil)
+               .where("content LIKE ?", "⏳%")
+               .destroy_all
+      end
+      private_class_method :cleanup_waiting_notices!
+
       # Refresh trigger_event_payload so the deferred agent sees the latest
       # conversation state instead of the stale snapshot from enqueue time.
       # Skips AI agent's own comments to prevent self-response loops.
@@ -47,7 +61,7 @@ module Collavre
         topic_id = context.dig("topic", "id")
         scope = Comment
           .where(creative_id: creative_id, topic_id: topic_id, private: false)
-          .where.not(user_id: task.agent_id)
+          .where.not(user_id: [ task.agent_id, nil ])
           .order(created_at: :desc)
         latest_comment = scope.first
 
@@ -110,33 +124,68 @@ module Collavre
 
       def enqueue_jobs(decisions)
         decisions.filter_map do |decision|
+          agent = decision[:agent]
+          log_decision(decision)
+
           case decision[:timing]
           when :immediate
-            AiAgentJob.perform_later(decision[:agent].id, @event_name, @context)
-            decision[:agent]
+            AiAgentJob.perform_later(agent.id, @event_name, @context)
+            agent
           when :deferred
             Task.create!(
               name: "Response to #{@event_name}",
               status: "queued",
               trigger_event_name: @event_name,
               trigger_event_payload: @context,
-              agent: decision[:agent],
+              agent: agent,
               topic_id: @context.dig("topic", "id")
             )
-            decision[:agent]
+            post_waiting_notice(agent, decision)
+            agent
           when :delayed
             AiAgentJob.set(wait: decision[:delay]).perform_later(
-              decision[:agent].id, @event_name, @context
+              agent.id, @event_name, @context
             )
-            decision[:agent]
+            post_waiting_notice(agent, decision)
+            agent
           when :rejected
-            Rails.logger.info(
-              "[Orchestrator] Agent #{decision[:agent].id} rejected: #{decision[:reason]}"
-            )
             nil
           end
         end
       end
+
+      def log_decision(decision)
+        agent = decision[:agent]
+        topic_id = @context.dig("topic", "id") || "main"
+        detail = [ decision[:timing], decision[:reason] ].compact.join(": ")
+        detail += " #{decision[:delay]}s" if decision[:delay]
+        Rails.logger.info(
+          "[Orchestrator] Agent #{agent.id} (#{agent.name}) → #{detail} " \
+          "(event=#{@event_name}, topic=#{topic_id})"
+        )
+      end
+
+      def post_waiting_notice(agent, decision)
+        creative_id = @context.dig("creative", "id")
+        topic_id = @context.dig("topic", "id")
+        return unless creative_id
+
+        creative = Creative.find_by(id: creative_id)
+        return unless creative
+
+        reason_key = decision[:reason] || :unknown
+        reason_text = I18n.t(
+          "collavre.orchestration.waiting_reasons.#{reason_key}",
+          default: reason_key.to_s.humanize
+        )
+
+        creative.comments.create!(
+          content: I18n.t("collavre.orchestration.waiting_notice", reason: reason_text),
+          topic_id: topic_id,
+          private: false,
+          skip_default_user: true
+        )
+      end
     end
   end
 end

data/app/services/collavre/orchestration/loop_breaker.rb

@@ -67,9 +67,12 @@ module Collavre
         Rails.cache.write(key, interactions, expires_in: CACHE_EXPIRY)
       end
 
-      # Record a task creation for creative retry detection
-      def record_task(creative_id, agent_id)
-        key = creative_tasks_key(creative_id)
+      # Record a task creation for creative retry detection (per-topic)
+      # Skips recording for user-initiated messages (only agent-to-agent counts as potential loop)
+      def record_task(creative_id, agent_id, topic_id: nil, triggered_by_user: false)
+        return if triggered_by_user
+
+        key = topic_tasks_key(creative_id, topic_id)
         tasks = Rails.cache.read(key) || []
         tasks << { at: Time.current.to_i, agent_id: agent_id }
 
@@ -136,12 +139,13 @@ module Collavre
         safe_result
       end
 
-      # Detect too many tasks on same creative
+      # Detect too many tasks on same topic (per-topic, not per-creative)
       def check_creative_retry
         creative_id = @context.dig("creative", "id")
+        topic_id = @context.dig("topic", "id")
         return safe_result unless creative_id
 
-        key = creative_tasks_key(creative_id)
+        key = topic_tasks_key(creative_id, topic_id)
         tasks = Rails.cache.read(key) || []
 
         # Filter to window
@@ -154,6 +158,7 @@ module Collavre
             reason: :creative_retry_exceeded,
             details: {
               creative_id: creative_id,
+              topic_id: topic_id,
               task_count: recent_tasks.size,
               threshold: creative_retry_threshold,
               window_minutes: @config["creative_retry_window_minutes"]
@@ -253,8 +258,8 @@ module Collavre
         "#{CACHE_PREFIX}:ping_pong:#{sorted[0]}-#{sorted[1]}:#{creative_id}"
       end
 
-      def creative_tasks_key(creative_id)
-        "#{CACHE_PREFIX}:creative:#{creative_id}:tasks"
+      def topic_tasks_key(creative_id, topic_id)
+        "#{CACHE_PREFIX}:creative:#{creative_id}:topic:#{topic_id || "main"}:tasks"
       end
 
       def token_usage_key(agent_id)

data/app/services/collavre/orchestration/policy_resolver.rb

@@ -34,7 +34,7 @@ module Collavre
           "max_retries" => 3,
           "retry_delay_seconds" => 5,
           # Loop breaker settings
-          "loop_breaker_enabled" => false,
+          "loop_breaker_enabled" => true,
           "ping_pong_threshold" => 5,           # Max back-and-forth between same agents
           "creative_retry_threshold" => 10,     # Max tasks on same creative in time window
           "creative_retry_window_minutes" => 30,
@@ -43,10 +43,19 @@ module Collavre
           "token_spike_window_minutes" => 10
         },
         "stuck_detection" => {
-          "enabled" => true,
+          "enabled" => false,
           "task_stuck_threshold_minutes" => 30,       # Task running for > N minutes
           "creative_stall_threshold_minutes" => 120,  # Creative no progress for > N minutes
           "create_system_comment" => true             # Create system comment on escalation
+        },
+        "collaboration" => {
+          "a2a_focus_instruction" => nil,         # nil = locale default
+          "a2a_completion_instruction" => nil,
+          "a2a_followup_instruction" => nil,
+          "mention_rule" => nil,
+          "confidence_rule" => nil,
+          "escalation_rule" => nil,
+          "review_rule" => nil
         }
       }.freeze
 
@@ -135,6 +144,11 @@ module Collavre
         }
       end
 
+      # Collaboration config
+      def collaboration_config
+        @collaboration_config ||= merge_policies("collaboration")
+      end
+
       # Stuck detection settings
       def stuck_detection_enabled?
         stuck_detection_config["enabled"] == true

data/app/services/collavre/orchestration/scheduler.rb

@@ -77,7 +77,7 @@ module Collavre
         if topic_max && @context.key?("topic")
           topic_id = @context.dig("topic", "id")
           if (Task.running_for_topic(topic_id).count + topic_immediate_count) >= topic_max
-            return deferred_decision(agent)
+            return deferred_decision(agent, :topic_concurrency)
           end
         end
 
@@ -101,10 +101,11 @@ module Collavre
         }
       end
 
-      def deferred_decision(agent)
+      def deferred_decision(agent, reason = nil)
         {
           agent: agent,
-          timing: :deferred
+          timing: :deferred,
+          reason: reason
         }
       end
 

data/app/services/collavre/orchestration/stuck_detector.rb

@@ -267,7 +267,7 @@ module Collavre
           [
             "collavre.stuck_detection.creative_stalled",
             {
-              creative_title: creative.description&.truncate(50) || "Untitled",
+              creative_title: creative.creative_snippet,
               hours: hours_stuck,
               progress: ((creative.progress || 0) * 100).round
             }

data/app/services/collavre/system_events/context_builder.rb

@@ -55,12 +55,7 @@ module Collavre
         content = chat_context["content"]
         return nil unless content
 
-        # Canonical mention format: @name: (with colon)
-        match = content.match(/\A@([^:]+?):\s*/)
-        return nil unless match
-
-        name = match[1].strip
-        user = User.where("LOWER(name) = ?", name.downcase).first
+        user = MentionParser.resolve_user(content)
         user&.as_json(only: [ :id, :name, :email ])
       end
     end