collavre 0.24.0 → 0.25.0

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Collavre
+  module SystemEvents
+    # The registry of event names orchestration can dispatch.
+    module Vocabulary
+      UnknownEvent = Class.new(ArgumentError)
+      Definition = Data.define(:name, :required_keys, :sources)
+
+      EVENTS = {
+        "comment_created" => Definition.new(
+          name: "comment_created",
+          required_keys: %w[comment creative],
+          sources: %w[comment_callback cron a2a drop_trigger trigger_restart]
+        )
+      }.freeze
+
+      def self.names
+        EVENTS.keys
+      end
+
+      def self.known?(name)
+        EVENTS.key?(name.to_s)
+      end
+
+      def self.fetch(name)
+        EVENTS.fetch(name.to_s) do
+          raise UnknownEvent,
+            "Unknown system event #{name.inspect}. Known events: #{names.join(', ')}"
+        end
+      end
+
+      # Required keys are advisory. The dispatcher warns rather than refusing
+      # a malformed payload, preserving the behavior of existing callers.
+      def self.missing_keys(name, payload)
+        return [] unless known?(name)
+
+        payload ||= {}
+        fetch(name).required_keys.reject do |key|
+          !payload[key].nil? || !payload[key.to_sym].nil?
+        end
+      end
+    end
+  end
+end

data/app/services/collavre/tools/creative_retrieval_service.rb

@@ -177,7 +177,7 @@ module Tools
       if include_comments
         result[:recent_comments] = creative.comments.order(created_at: :desc).limit(3).map do |comment|
           {
-            content: ActionView::Base.full_sanitizer.sanitize(comment.content).strip.truncate(200),
+            content: Collavre::HtmlText.plain(comment.content).strip.truncate(200),
             user: comment.user&.display_name || comment.user&.name,
             created_at: comment.created_at&.iso8601
           }

data/app/services/collavre/tools/cron_create_service.rb

@@ -33,8 +33,8 @@ module Tools
         return { error: "No write permission on this Creative", id: creative_id }
       end
 
-      topic_id = resolve_topic_id(creative, topic_name)
-      return topic_id if topic_id.is_a?(Hash) && topic_id[:error]
+      topic = resolve_topic(creative, topic_name)
+      return topic if topic.is_a?(Hash) && topic[:error]
 
       parsed = Fugit.parse(schedule)
       unless parsed.is_a?(Fugit::Cron)
@@ -44,20 +44,11 @@ module Tools
       suffix = SecureRandom.hex(4)
       key = "cron_#{creative_id}_#{suffix}"
 
-      task = SolidQueue::RecurringTask.create!(
-        key: key,
-        class_name: "Collavre::CronActionJob",
-        schedule: schedule,
-        queue_name: "default",
-        static: false,
-        description: description || "Cron job for creative #{creative_id}",
-        arguments: [ {
-          creative_id: creative_id,
-          topic_id: topic_id,
-          agent_id: Current.user.id,
-          message: message
-        } ]
+      task = create_task(
+        topic: topic, creative: creative, creative_id: creative_id,
+        key: key, schedule: schedule, message: message, description: description
       )
+      return task if task.is_a?(Hash) && task[:error]
 
       {
         success: true,
@@ -72,15 +63,38 @@ module Tools
 
     private
 
-    def resolve_topic_id(creative, topic_name)
+    def create_task(topic:, creative:, creative_id:, key:, schedule:, message:, description:)
+      topic.with_lock do
+        unless topic.creative_id == creative.effective_origin.id
+          return { error: I18n.t("collavre.comments.invalid_topic") }
+        end
+
+        SolidQueue::RecurringTask.create!(
+          key: key,
+          class_name: "Collavre::CronActionJob",
+          schedule: schedule,
+          queue_name: "default",
+          static: false,
+          description: description || "Cron job for creative #{creative_id}",
+          arguments: [ {
+            creative_id: creative_id,
+            topic_id: topic.id,
+            agent_id: Current.user.id,
+            message: message
+          } ]
+        )
+      end
+    end
+
+    def resolve_topic(creative, topic_name)
       origin = creative.effective_origin
       if topic_name.casecmp(Creative::MAIN_TOPIC_NAME).zero?
-        origin.main_topic(fallback_user: Current.user).id
+        origin.main_topic(fallback_user: Current.user)
       else
         topic = Topic.find_by(name: topic_name, creative_id: origin.id)
         return { error: "Topic '#{topic_name}' not found for this creative" } unless topic
 
-        topic.id
+        topic
       end
     end
   end

data/app/services/collavre/tools/id_list.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Tools
+    # Parses the "list of ids" parameters the topic tools take.
+    #
+    # MCP schemas describe a list, but what actually arrives depends on the
+    # calling model: "12,45", ["12", 45], 12 and "12" are all things an agent
+    # writes when it means the same thing. Rejecting four fifths of those is a
+    # tool that fails for a reason the caller cannot see in its own request, so
+    # every shape is accepted here instead of at four separate call sites.
+    #
+    # Lenient about shape, strict about content. A token that is not entirely
+    # digits raises rather than coercing: to_i turns "12.5" into 12 and
+    # "123oops" into 123, and topic_create/topic_branch would then move a
+    # different message than the one named and report success. A tool that
+    # silently acts on a neighbouring id is worse than one that fails.
+    module IdList
+      module_function
+
+      DIGITS = /\A\d+\z/
+
+      def parse(value)
+        Array(value)
+          .flat_map { |entry| entry.to_s.split(",") }
+          .filter_map { |token| token.strip.presence }
+          .map { |token| cast(token) }
+          .uniq
+      end
+
+      def cast(token)
+        raise ArgumentError, "#{token.inspect} is not a valid id — ids must be whole numbers" unless token.match?(DIGITS)
+
+        token.to_i
+      end
+    end
+  end
+end

data/app/services/collavre/tools/topic_authorizer.rb

@@ -2,22 +2,76 @@
 
 module Collavre
   module Tools
-    # Topic write authorization for MCP tool services. Mirrors
-    # CreativePermissionGuard#require_creative_write! but is callable outside a
-    # controller request. Attaching a channel injects external messages into a
-    # topic, so it is a write-equivalent mutation — restrict to users with
-    # write permission on the topic's effective_origin creative.
+    # Topic authorization for MCP tool services. Mirrors
+    # CreativePermissionGuard's require_creative_{read,write,admin}! but is
+    # callable outside a controller request. Every check resolves the topic's
+    # effective_origin creative first, because that is where shares live — a
+    # linked creative carries none of its own.
+    #
+    # The owner short-circuit matches CreativePermissionGuard: an owner can hold
+    # no explicit share on their own creative, so has_permission? alone would
+    # lock them out of their own topics.
     module TopicAuthorizer
       module_function
 
+      # Reading a topic's messages exposes every participant's words, so it is
+      # gated at :read — the same level the creative's own body needs.
+      def authorize_read!(topic, user: Collavre::Current.user)
+        authorize!(topic, :read, user: user)
+      end
+
+      # Posting a message is the topic equivalent of commenting through
+      # CommentsController, so it uses the same feedback permission floor.
+      def authorize_feedback!(topic, user: Collavre::Current.user)
+        authorize!(topic, :feedback, user: user)
+      end
+
+      # Attaching a channel injects external messages into a topic, and creating
+      # or archiving one restructures where conversation lands, so both are
+      # write-equivalent mutations.
       def authorize_write!(topic, user: Collavre::Current.user)
+        authorize!(topic, :write, user: user)
+      end
+
+      # Renaming a topic rewrites a name other members' links and habits point
+      # at, so TopicsController gates it at :admin. Tools must not be the softer
+      # door onto the same mutation.
+      def authorize_admin!(topic, user: Collavre::Current.user)
+        authorize!(topic, :admin, user: user)
+      end
+
+      # Topic creation has no topic to authorize against yet, so the creative is
+      # the subject. Kept here so every topic-shaped permission decision reads
+      # from one place.
+      def authorize_creative!(creative, level, user: Collavre::Current.user)
+        origin = creative&.effective_origin
+        raise ArgumentError, "Creative is required" unless origin
+        return if origin.user == user
+        return if user && origin.has_permission?(user, level)
+
+        raise Collavre::Tools::PermissionDeniedError,
+          "No #{level} permission on creative #{origin.id}"
+      end
+
+      def authorize!(topic, level, user: Collavre::Current.user)
         creative = topic.creative&.effective_origin
         raise ArgumentError, "Topic has no creative" unless creative
         return if creative.user == user
-        return if user && creative.has_permission?(user, :write)
+        return if user && creative.has_permission?(user, level)
 
         raise Collavre::Tools::PermissionDeniedError,
-          "No write permission on topic #{topic.id}"
+          "No #{level} permission on topic #{topic.id}"
+      end
+
+      # True when the user may read the topic. Used by the multi-topic read
+      # tools, which report an inaccessible topic as a per-topic error entry
+      # rather than failing the whole call — one unreadable id in a batch of
+      # three should not discard the two that worked.
+      def readable?(topic, user: Collavre::Current.user)
+        authorize_read!(topic, user: user)
+        true
+      rescue Collavre::Tools::PermissionDeniedError, ArgumentError
+        false
       end
     end
   end

data/app/services/collavre/tools/topic_branch_service.rb

@@ -0,0 +1,85 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Branches selected messages of a topic into a new topic, copying them.
+  #
+  # The context-length escape hatch. A topic that has run long is expensive for
+  # every agent that reads it and hard for a person to re-enter, but the history
+  # is not disposable. Branching carries the few messages the next stretch of
+  # work actually depends on into a fresh topic and leaves the original intact
+  # as the record.
+  class TopicBranchService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "topic_branch"
+    tool_description <<~DESC.strip
+      Branch a topic: create a new topic containing COPIES of selected messages
+      from an existing one. The originals stay where they are.
+
+      Use this to reset a conversation that has grown too long to carry, or to
+      split one thread that has drifted into two subjects, while keeping the
+      source topic as the record. To move messages instead of copying them, use
+      topic_create with comment_ids.
+
+      Get the message ids from topic_messages. At most
+      #{::Collavre::TopicBranchService::MAX_BRANCH_COMMENTS} messages per branch
+      — pick the ones the next stretch of work depends on rather than the whole
+      history. Asking for more is an error, not a silent trim.
+
+      The new topic is created on the same creative and records the source in
+      source_topic_id. Requires feedback permission or better on the creative.
+      Main and an inbox's System name are reserved and cannot be assigned to
+      the branch.
+
+      Approval prompts cannot be branched — a copy would lose the approval
+      action and read as ordinary history. Passing one is an error.
+    DESC
+
+    tool_param :source_topic_id, description: "The topic to branch from."
+    tool_param :comment_ids, description: "Comma-separated ids of the messages to copy, e.g. \"991,994,1002\". They must all belong to the source topic and be visible to you. Get ids from topic_messages."
+    tool_param :name, description: "Name for the new topic. Defaults to a generated \"branch:<source name>\" name.", required: false
+
+    sig do
+      params(
+        source_topic_id: Integer,
+        comment_ids: T.any(String, Integer, T::Array[T.untyped]),
+        name: T.nilable(String)
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def call(source_topic_id:, comment_ids:, name: nil)
+      user = Current.user || raise("Current.user is required")
+      source = Topic.find(source_topic_id)
+      TopicAuthorizer.authorize_read!(source, user: user)
+
+      ids = IdList.parse(comment_ids)
+      validate_ids!(ids)
+
+      # Fully qualified: inside Collavre::Tools, a bare TopicBranchService is
+      # this tool, not the branching service it wraps.
+      topic = ::Collavre::TopicBranchService.new(
+        creative: source.creative, user: user, source_topic: source, name: name
+      ).call(comment_ids: ids)
+
+      Topics::Serializer.for_tool(topic).merge(source_topic_id: source.id, copied_count: ids.size)
+    end
+
+    private
+
+    # TopicBranchService trims an oversized selection to its cap and reports
+    # success for the shortened list, which is right for a UI that already
+    # capped the selection but wrong here: a caller that pasted 150 ids would be
+    # told it branched them and be missing 50 with nothing to read that says so.
+    def validate_ids!(ids)
+      cap = ::Collavre::TopicBranchService::MAX_BRANCH_COMMENTS
+      raise ArgumentError, "comment_ids is required" if ids.empty?
+      return if ids.size <= cap
+
+      raise ArgumentError,
+        "#{ids.size} messages requested but a branch copies at most #{cap}. " \
+        "Select fewer messages, or branch more than once."
+    end
+  end
+end
+end

data/app/services/collavre/tools/topic_create_service.rb

@@ -0,0 +1,117 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Creates a topic on a creative, optionally pinning a primary agent and
+  # optionally moving existing messages into it.
+  #
+  # This is the fan-out primitive. Topics are the concurrency unit — tasks in
+  # one topic queue behind each other, tasks in different topics run in parallel
+  # — so an agent that can only create creatives can split work up on paper but
+  # cannot actually run it in parallel. Creating a topic per unit of work, with
+  # the agent that owns it pinned, is what turns a plan into concurrent work.
+  class TopicCreateService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "topic_create"
+    tool_description <<~DESC.strip
+      Create a topic (conversation thread) on a creative.
+
+      Topics are how work runs in parallel in Collavre: tasks dispatched in the
+      same topic are serialized — one holds the topic's slot while the rest
+      queue — while tasks in different topics run concurrently. Split work into
+      one topic per independently-runnable unit; do not pile parallel work into
+      one topic expecting it to overlap.
+
+      primary_agent pins one agent to the topic. A pin is EXCLUSIVE: the pinned
+      agent alone answers ambient messages there and no other agent responds, so
+      use it for a dedicated 1:1 working channel and leave it unset for a thread
+      several participants should hear. The agent must already have feedback
+      permission or better on the creative, otherwise the pin is refused (a
+      pinned agent that cannot answer would silence the topic for everyone).
+
+      Accepts an agent id, email, or exact name for primary_agent. Searchable
+      agents, agents created by the caller, and private agents already shared
+      on this creative can be resolved. Omit `name` to get the next default
+      name ("Topic 3"). Main and an inbox's System name are reserved and
+      cannot be assigned to a new topic.
+
+      comment_ids moves existing messages out of their current topic into the
+      new one. To copy messages and leave the originals in place, use
+      topic_branch instead.
+
+      Requires write permission on the creative.
+    DESC
+
+    tool_param :creative_id, description: "The creative to create the topic on."
+    tool_param :name, description: "Topic name. Must be unique on the creative. Defaults to the next generated name, e.g. \"Topic 3\".", required: false
+    tool_param :primary_agent, description: "Agent to pin to this topic — id, email, or exact name. The pin is exclusive: only this agent answers here. The agent needs feedback permission or better on the creative.", required: false
+    tool_param :comment_ids, description: "Comma-separated ids of existing messages to MOVE into the new topic. Use topic_branch to copy instead of move.", required: false
+
+    sig do
+      params(
+        creative_id: Integer,
+        name: T.nilable(String),
+        primary_agent: T.nilable(String),
+        comment_ids: T.nilable(T.any(String, Integer, T::Array[T.untyped]))
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def call(creative_id:, name: nil, primary_agent: nil, comment_ids: nil)
+      user = Current.user || raise("Current.user is required")
+      creative = Creative.find(creative_id).effective_origin
+      TopicAuthorizer.authorize_creative!(creative, :write, user: user)
+
+      agent = resolve_agent(primary_agent, creative)
+      topic = build_topic(creative, name, user)
+
+      Topic.transaction do
+        topic.save!
+        topic.set_primary_agent!(agent) if agent
+        move_comments(creative, user, topic, comment_ids)
+      end
+
+      broadcast(creative, topic, agent, user)
+      Topics::Serializer.for_tool(topic)
+    end
+
+    private
+
+    # Checked before the topic exists, exactly as TopicsController#create does:
+    # a topic created here never carries a session_id, so a Claude Channel
+    # session agent can never be routed on it and pinning one would produce a
+    # dead topic rather than an error.
+    def resolve_agent(primary_agent, creative)
+      resolved = Topics::AgentResolver.call(primary_agent, creative: creative)
+      return nil if resolved.nil? || resolved == Topics::AgentResolver::CLEAR
+
+      rejection = Topic.primary_agent_rejection(creative, resolved)
+      raise ArgumentError, Topics::PinRejection.message(resolved, rejection) if rejection
+
+      resolved
+    end
+
+    def build_topic(creative, name, user)
+      topic_name = name.presence || Topics::NextName.for(creative)
+      Topics::ReservedName.reject!(creative, topic_name)
+      creative.topics.build(name: topic_name, user: user)
+    end
+
+    def move_comments(creative, user, topic, comment_ids)
+      ids = IdList.parse(comment_ids)
+      return if ids.empty?
+
+      CommentMoveService.new(creative: creative, user: user).call(comment_ids: ids, target_topic_id: topic.id)
+    end
+
+    # user_id in the payload is what makes the creating user's own client select
+    # the new topic. Included for parity with TopicsController#create: a user
+    # asking an agent to open a topic expects to land in it, the same as if they
+    # had made it themselves.
+    def broadcast(creative, topic, agent, user)
+      payload = agent ? Topics::Serializer.with_agent(topic, agent) : topic.slice(:id, :name)
+      TopicsChannel.broadcast_to(creative, { action: "created", topic: payload, user_id: user.id })
+    end
+  end
+end
+end

data/app/services/collavre/tools/topic_list_service.rb

@@ -0,0 +1,101 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Lists a creative's topics, or describes specific topics by id.
+  #
+  # This is the planning call. A topic is a Collavre conversation's concurrency
+  # unit — work in separate topics runs in parallel, work piled into one topic
+  # queues — so an agent deciding how to split a job needs to see what topics
+  # already exist, who is pinned to them, and how much conversation each one
+  # holds, before it reads a single message.
+  class TopicListService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "topic_list"
+    tool_description <<~DESC.strip
+      List the topics of a creative, or describe specific topics by id.
+
+      A topic is a conversation thread on a creative, and it is also the unit of
+      agent concurrency: tasks in different topics run in parallel, tasks in the
+      same topic queue behind each other. Use this before splitting work up, and
+      before calling topic_messages — the per-topic message_count and
+      message_chars tell you how much conversation you would be pulling in, so
+      you can pick an offset/limit that fits your context.
+
+      Pass creative_id to list a creative's topics, or topic_ids to describe
+      known topics (which may live on different creatives). Returns, per topic:
+      id, name, creative_id, archived, main/system flags, source_topic_id (set
+      when the topic was branched off another), primary_agent, agent_locked, and
+      the message totals.
+
+      message_chars combines stored message HTML length with a conservative
+      estimate for image attachment markers. It is useful for relative sizing,
+      not exact budgeting.
+
+      Requires read permission on each topic's creative. Unknown or unreadable
+      ids come back in "errors" instead of failing the call.
+    DESC
+
+    tool_param :creative_id, description: "List every topic on this creative. Either this or topic_ids is required.", required: false
+    tool_param :topic_ids, description: "Describe these specific topics. Comma-separated ids, e.g. \"12,45,78\" (max #{TopicSelection::MAX_TOPICS} per call — asking for more is an error, not a silent trim). Either this or creative_id is required.", required: false
+    tool_param :include_archived, description: "Include archived topics when listing by creative_id (default: false). Archived topics keep their messages and stay readable by id.", required: false
+    tool_param :include_stats, description: "Include message_count / message_chars / last_message_at (default: true). Pass false to skip the totals query on a creative with very many topics.", required: false
+    tool_param :include_system, description: "Count authorless system messages in the totals (default: false). Approval prompts are never counted. Matches the topic_messages default so the counts describe the same set of messages you would read back.", required: false
+
+    sig do
+      params(
+        creative_id: T.nilable(Integer),
+        topic_ids: T.nilable(T.any(String, Integer, T::Array[T.untyped])),
+        include_archived: T.nilable(T::Boolean),
+        include_stats: T.nilable(T::Boolean),
+        include_system: T.nilable(T::Boolean)
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def call(creative_id: nil, topic_ids: nil, include_archived: false, include_stats: true, include_system: false)
+      user = require_user!
+      include_stats = true if include_stats.nil?
+
+      topics, errors = select_topics(creative_id, topic_ids, user, include_archived)
+      stats = include_stats ? Topics::MessageStats.for(topics, user: user, include_system: include_system) : {}
+
+      { topics: topics.map { |topic| describe(topic, stats[topic.id]) }, errors: errors }
+    end
+
+    private
+
+    def require_user!
+      Current.user || raise("Current.user is required")
+    end
+
+    def select_topics(creative_id, topic_ids, user, include_archived)
+      ids = IdList.parse(topic_ids)
+      return TopicSelection.resolve(ids, user: user) if ids.any?
+      raise ArgumentError, "Either creative_id or topic_ids is required" if creative_id.blank?
+
+      [ topics_of(creative_id, user, include_archived), [] ]
+    end
+
+    # effective_origin because topics hang off the origin creative, not off a
+    # link to it — passing a linked creative's id would otherwise list nothing.
+    def topics_of(creative_id, user, include_archived)
+      creative = Creative.find(creative_id).effective_origin
+      TopicAuthorizer.authorize_creative!(creative, :read, user: user)
+
+      scope = creative.topics
+      scope = scope.active unless include_archived
+      scope.includes(:primary_agent).to_a
+    end
+
+    def describe(topic, stat)
+      Topics::Serializer.for_tool(
+        topic,
+        message_count: stat&.count,
+        message_chars: stat&.chars,
+        last_message_at: stat&.last_at
+      )
+    end
+  end
+end
+end