collavre 0.24.0 → 0.25.0

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Tools
+    # Turns the `topic_ids` parameter of the read tools into topics, and reports
+    # the ones it could not turn into topics instead of raising.
+    #
+    # A caller asking about three topics has usually copied the ids out of a
+    # conversation, so one of them being stale or unshared is ordinary. Failing
+    # the whole call there would throw away the two that worked and give no way
+    # to tell which id was the bad one.
+    module TopicSelection
+      # A ceiling on topics per call, not on messages — that is max_chars' job.
+      # This one exists because each topic costs a header, a totals query and a
+      # window query, and a caller that pastes forty ids has stopped planning
+      # and started dumping.
+      MAX_TOPICS = 20
+
+      module_function
+
+      # Returns [topics, errors], preserving the caller's id order so a numbered
+      # request reads back in the order it was asked.
+      def resolve(ids, user: Collavre::Current.user)
+        enforce_cap!(ids)
+        by_id = Topic.where(id: ids).index_by(&:id)
+
+        ids.each_with_object([ [], [] ]) do |id, (topics, errors)|
+          error = rejection_for(by_id[id], user)
+          error ? errors << { topic_id: id, error: error } : topics << by_id[id]
+        end
+      end
+
+      # An oversized batch is an error, not a trim. Silently keeping the first
+      # twenty returns a response that looks complete — every topic asked for
+      # that appears, appears in full — while whole conversations are missing
+      # with nothing in the payload that says so, and a caller summarizing
+      # "all of these" would report on a subset believing it had them all.
+      # Unreadable ids are still reported per topic rather than raised: those
+      # the caller can see and act on, one entry each.
+      def enforce_cap!(ids)
+        return if ids.size <= MAX_TOPICS
+
+        raise ArgumentError,
+          "#{ids.size} topics requested but at most #{MAX_TOPICS} can be read per call. " \
+          "Split the ids across several calls."
+      end
+
+      # Deliberately the same message for missing and unreadable. Distinguishing
+      # them would let a caller probe which topic ids exist on creatives they
+      # cannot see.
+      def rejection_for(topic, user)
+        return "Topic not found or not readable" if topic.nil?
+        return nil if TopicAuthorizer.readable?(topic, user: user)
+
+        "Topic not found or not readable"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Renames a topic, archives/unarchives it, or changes its primary agent.
+  #
+  # One tool rather than three because these are the three ways a topic changes
+  # after it exists, and they are routinely done together — an agent finishing a
+  # unit of work archives the topic and releases the pin in the same breath.
+  # They do not share a permission level, so each field is authorized for what
+  # it actually does.
+  class TopicUpdateService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "topic_update"
+    tool_description <<~DESC.strip
+      Rename a topic, archive or unarchive it, or set/clear its primary agent.
+      Pass only the fields you want to change.
+
+      Archiving is how a finished thread is put away: the topic leaves the
+      active sidebar but keeps every message, and topic_messages can still read
+      it by id. Archive a topic when its conversation has reached its
+      conclusion, rather than reusing it for the next subject — a topic is one
+      thread of one conclusion, and it is also the concurrency unit, so reusing
+      one serializes unrelated work behind it.
+
+      primary_agent pins one agent to the topic, EXCLUSIVELY: the pinned agent
+      alone answers ambient messages and no other agent responds. The agent must
+      already have feedback permission or better on the creative. Pass "none" to
+      clear the pin and let normal routing resume. Accepts an agent id, email,
+      or exact name; private agents already shared on this creative resolve too.
+
+      Permissions: renaming needs admin on the creative (a rename changes what
+      everyone else's links and habits point at); archiving and pin changes need
+      write. Main and an inbox's System topic are reserved: their names and
+      archive state cannot change, and those names cannot be assigned to another
+      topic, but their pin can. A Claude Channel session topic's pin is part of
+      its session identity and cannot be changed here.
+    DESC
+
+    tool_param :topic_id, description: "The topic to update."
+    tool_param :name, description: "New name. Must be unique on the creative. Requires admin permission.", required: false
+    tool_param :archived, description: "true archives the topic (hides it from the active list, keeps all messages); false unarchives it.", required: false
+    tool_param :primary_agent, description: "Agent to pin — id, email, or exact name. Pass \"none\" to clear the pin. The pin is exclusive: only this agent answers in the topic.", required: false
+
+    sig do
+      params(
+        topic_id: Integer,
+        name: T.nilable(String),
+        archived: T.nilable(T::Boolean),
+        primary_agent: T.nilable(String)
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def call(topic_id:, name: nil, archived: nil, primary_agent: nil)
+      Current.user || raise("Current.user is required")
+      topic = Topic.find(topic_id)
+
+      # Authorize before resolving the agent: resolution reports whether a name
+      # matches an accessible agent, and a caller with no rights on the topic
+      # should not be able to ask.
+      authorize!(topic, name)
+      changed = requested(name, archived, primary_agent)
+      raise ArgumentError, "Nothing to update: pass name, archived, or primary_agent" if changed.empty?
+
+      agent = apply(topic, name, archived, primary_agent)
+      broadcast_all(topic.reload, changed, archived, agent)
+
+      Topics::Serializer.for_tool(topic).merge(changed: changed)
+    end
+
+    private
+
+    # A rename is gated at :admin to match TopicsController#update. Everything
+    # else here is a :write action, so the stricter gate is only applied when a
+    # rename is actually requested — otherwise archiving would silently need
+    # admin through this door and not through the UI.
+    def authorize!(topic, name)
+      name.present? ? TopicAuthorizer.authorize_admin!(topic) : TopicAuthorizer.authorize_write!(topic)
+    end
+
+    def requested(name, archived, primary_agent)
+      changed = []
+      changed << "name" if name.present?
+      changed << "archived" unless archived.nil?
+      changed << "primary_agent" unless primary_agent.nil?
+      changed
+    end
+
+    # Every requested field is checked before any of them is written, and the
+    # writes share one transaction. A call that renames, archives, and pins an
+    # agent the creative has not shared with must report failure over a topic
+    # that is still named what it was — not one that was quietly renamed and
+    # archived on the way to the error. Nothing broadcasts until the whole set
+    # has committed, for the same reason.
+    def apply(topic, name, archived, primary_agent)
+      agent = nil
+      Topic.transaction do
+        topic.lock!
+        authorize!(topic, name)
+        reject_reserved_mutation!(topic, name, archived)
+        agent = resolve_agent(topic, primary_agent)
+        topic.update!(name: name) if name.present?
+        set_archived(topic, archived) unless archived.nil?
+        topic.set_primary_agent!(agent) unless primary_agent.nil?
+      end
+
+      agent
+    end
+
+    def resolve_agent(topic, primary_agent)
+      change = Topics::AgentResolver.call(primary_agent, creative: topic.creative)
+      change ? validated_agent(topic, change) : nil
+    end
+
+    def reject_reserved_mutation!(topic, name, archived)
+      return unless name.present? || !archived.nil?
+      return unless reserved_topic?(topic) || Topics::ReservedName.reserved?(topic.creative, name)
+
+      raise ArgumentError,
+        "Reserved topic names cannot be assigned or changed, and reserved topics cannot be archived."
+    end
+
+    def reserved_topic?(topic)
+      Topics::ReservedName.reserved?(topic.creative, topic.name)
+    end
+
+    def set_archived(topic, archived)
+      archived ? topic.archive! : topic.unarchive!
+    end
+
+    # Mirrors TopicsController#set_primary_agent, including the session lock:
+    # on a Claude Channel session topic primary_agent_id is session identity,
+    # not a routing preference — Matcher needs it to route the agent at all and
+    # SessionProvisioner reuses the topic by it, so rewriting it would leave a
+    # live session unroutable and fork the next registration into a second topic.
+    def validated_agent(topic, agent_change)
+      raise ArgumentError, "This is a session topic; its agent assignment is locked." if topic.session_id.present?
+
+      agent = agent_change == Topics::AgentResolver::CLEAR ? nil : agent_change
+      reject_unassignable!(topic, agent)
+      agent
+    end
+
+    def broadcast_all(topic, changed, archived, agent)
+      broadcast(topic, "updated", topic: Topics::Serializer.call(topic)) if changed.include?("name")
+      broadcast(topic, archived ? "archived" : "unarchived", topic: topic.slice(:id, :name, :archived_at)) if changed.include?("archived")
+      broadcast(topic, "updated", topic: Topics::Serializer.with_agent(topic, agent)) if changed.include?("primary_agent")
+    end
+
+    def reject_unassignable!(topic, agent)
+      return if agent.nil?
+
+      rejection = Topic.primary_agent_rejection(topic.creative, agent, topic: topic)
+      return unless rejection
+
+      raise ArgumentError, Topics::PinRejection.message(agent, rejection)
+    end
+
+    def broadcast(topic, action, payload)
+      TopicsChannel.broadcast_to(topic.creative, { action: action, **payload })
+    end
+  end
+end
+end

data/app/services/collavre/topic_branch_service.rb

@@ -18,15 +18,21 @@ module Collavre
     # does not apply.
     # auto_select: false omits user_id from the topic-created broadcast so
     # background/system branches do not hijack the owner's current selection.
-    def call(comment_ids:, enforce_limit: true, auto_select: true)
+    # skip_approval_actions is reserved for system history copies that already
+    # selected an approval-free set but must tolerate a row becoming an approval
+    # prompt before the locked fetch. Interactive branches keep the default
+    # all-or-nothing rejection.
+    def call(comment_ids:, enforce_limit: true, auto_select: true, skip_approval_actions: false)
       comment_ids = Array(comment_ids).map(&:presence).compact.map(&:to_i)
       comment_ids = comment_ids.first(MAX_BRANCH_COMMENTS) if enforce_limit
       raise BranchError, I18n.t("collavre.comments.branch.no_selection") if comment_ids.empty?
 
-      validate_permissions!
-      originals = fetch_comments(comment_ids)
-
       Topic.transaction do
+        lock_source!
+        validate_permissions!
+        originals = fetch_comments(comment_ids)
+        originals = originals.reject(&:approval_action?) if skip_approval_actions
+        reject_approval_actions!(originals)
         @new_topic = create_branch_topic
         copy_comments(originals)
       end
@@ -40,6 +46,16 @@ module Collavre
 
     attr_reader :creative, :user, :source_topic, :name
 
+    def lock_source!
+      return unless source_topic
+
+      # The topic can move after a caller's preflight authorization. Pin its
+      # current creative under the same lock that protects the comment fetch so
+      # permissions and the branch destination cannot refer to stale state.
+      source_topic.lock!
+      @creative = source_topic.creative
+    end
+
     def validate_permissions!
       unless creative.has_permission?(user, :feedback)
         raise BranchError, I18n.t("collavre.comments.branch.not_authorized")
@@ -48,15 +64,22 @@ module Collavre
 
     def fetch_comments(comment_ids)
       scope = source_topic ? source_topic.comments.visible_to(user) : creative.comments.visible_to(user)
-      comments = scope.where(id: comment_ids).order(:created_at).to_a
+      comments = scope.where(id: comment_ids).order(:created_at).lock.to_a
       if comments.length != comment_ids.length
         raise BranchError, I18n.t("collavre.comments.branch.comments_not_found")
       end
       comments
     end
 
+    def reject_approval_actions!(comments)
+      return unless comments.any?(&:approval_action?)
+
+      raise BranchError, I18n.t("collavre.comments.branch.approval_action_not_branchable")
+    end
+
     def create_branch_topic
       topic_name = name.presence || default_branch_name
+      Topics::ReservedName.reject!(creative, topic_name, error_class: BranchError)
 
       creative.topics.create!(
         name: topic_name,
@@ -88,6 +111,12 @@ module Collavre
           user_id: original.user_id,
           content: original.content,
           private: original.private,
+          # Carried with `private`, not separately from it: visible_to reads a
+          # private comment for its author *and* its approver, so copying the
+          # flag without the approver narrows who can see the copy. The user who
+          # selected the message can be the approver rather than the author, and
+          # would then get a branch reporting a message it cannot show them.
+          approver_id: original.approver_id,
           review_type: original.review_type,
           skip_default_user: true,
           skip_dispatch: true
@@ -98,13 +127,13 @@ module Collavre
           new_comment.quoted_comment_id = id_mapping[original.quoted_comment_id]
         end
 
+        # Attach before validation so an image-only comment still satisfies the
+        # Comment content-or-images invariant. Reuse the blobs without copying
+        # file data, as the post-save loop did previously.
+        new_comment.images.attach(original.images.map(&:blob)) if original.images.attached?
+
         new_comment.save!
         id_mapping[original.id] = new_comment.id
-
-        # Share image blobs (no duplication of file data)
-        original.images.each do |image|
-          new_comment.images.attach(image.blob)
-        end
       end
     end
 

data/app/services/collavre/topics/agent_resolver.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Topics
+    # Resolves the `primary_agent` string an MCP caller passes into a User.
+    #
+    # The UI picks an agent from a palette and sends an id; an agent calling a
+    # tool has read a name out of a conversation and has no palette to click.
+    # Accepting id / email / display name is what makes topic_create and
+    # topic_update usable without a preceding lookup round-trip.
+    #
+    # Candidates are the owned-or-searchable set plus agents already shared on
+    # the target Creative. The latter matches User.mentionable_for and the UI's
+    # agent palette. Resolving over every agent row would let a caller confirm a
+    # private agent's existence by name, and would let them pin one they are not
+    # allowed to see.
+    module AgentResolver
+      # Sentinel distinguishing "clear the pin" from "no change". A blank string
+      # cannot carry that difference on its own: topic_update omitting the
+      # parameter and topic_update asking to unassign both arrive as falsy.
+      CLEAR = :clear
+
+      # What a caller writes to mean "unassign". Spelled out because an agent
+      # that guesses will guess one of these.
+      CLEAR_TOKENS = %w[none clear null nil unassign].freeze
+
+      class AmbiguousAgentError < ArgumentError; end
+      class UnknownAgentError < ArgumentError; end
+
+      module_function
+
+      # Returns nil (no change), CLEAR (unassign), or a User.
+      def call(value, actor: Collavre::Current.user, creative: nil)
+        token = value.to_s.strip
+        return nil if value.nil?
+        return CLEAR if token.empty? || CLEAR_TOKENS.include?(token.downcase)
+
+        candidates = candidates_for(actor, creative)
+        find_by_id(candidates, token) ||
+          find_by_email(candidates, token) ||
+          find_by_name(candidates, token) ||
+          raise(UnknownAgentError, unknown_message(token))
+      end
+
+      def candidates_for(actor, creative)
+        accessible = User.accessible_ai_agents_for(actor)
+        return accessible unless creative
+
+        shared = User.mentionable_for(creative).ai_agents
+        base = User.ai_agents
+        base.where(id: accessible.reorder(nil).select(:id))
+            .or(base.where(id: shared.reorder(nil).select(:id)))
+            .distinct.order(:name)
+      end
+
+      def find_by_id(candidates, token)
+        return nil unless token.match?(/\A\d+\z/)
+
+        candidates.find_by(id: token.to_i)
+      end
+
+      def find_by_email(candidates, token)
+        return nil unless token.include?("@")
+
+        candidates.find_by(email: token.downcase)
+      end
+
+      # Names are not unique, so an exact-match tie is reported with the ids
+      # rather than silently resolved to the first row — picking one would
+      # quietly dedicate a topic to the wrong agent.
+      def find_by_name(candidates, token)
+        matches = candidates.where(name: token).to_a
+        return matches.first if matches.one?
+        return nil if matches.empty?
+
+        raise AmbiguousAgentError,
+          "Multiple agents named #{token.inspect}: ids #{matches.map(&:id).join(', ')}. Pass the id instead."
+      end
+
+      def unknown_message(token)
+        "No accessible AI agent matches #{token.inspect}. " \
+          "Pass an agent id, email, or exact name; the agent must be searchable, created by you, " \
+          "or already shared on this creative."
+      end
+    end
+  end
+end

data/app/services/collavre/topics/char_budget.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Topics
+    # A character cap and the unit it is measured in.
+    #
+    # The two travel together because neither is meaningful alone. A cap of
+    # 40,000 buys a different amount of conversation depending on whether the
+    # response is a markdown transcript or a JSON object, and budgeting in one
+    # unit while emitting the other is exactly how a cap gets exceeded by half
+    # again. Keeping them in one object means a caller cannot supply a cap and
+    # forget to say what it counts.
+    class CharBudget
+      FORMATS = %w[markdown json].freeze
+      DEFAULT_FORMAT = "markdown"
+
+      # Markdown's per-message overhead: the id, the ISO-8601 timestamp, the
+      # author separator and two newlines. Measured rather than guessed —
+      # content-only accounting hands this out for free, and a few hundred short
+      # messages is then an entire budget spent off the books.
+      ENVELOPE_CHARS = 36
+
+      # Markdown tags an AI author with a " (agent)" suffix on its byline. Eight
+      # characters is nothing on one message and a page's worth on a stretch of
+      # short agent turns, which is exactly the shape a busy topic has — and it
+      # is more than the margin the per-topic reserve leaves to absorb it.
+      AGENT_SUFFIX_CHARS = " (agent)".length
+
+      attr_reader :chars, :format
+
+      def self.normalize_format(value)
+        FORMATS.include?(value.to_s) ? value.to_s : DEFAULT_FORMAT
+      end
+
+      def initialize(chars: nil, format: DEFAULT_FORMAT)
+        @chars = chars
+        @format = self.class.normalize_format(format)
+      end
+
+      def unlimited? = @chars.nil?
+
+      def json? = @format == "json"
+
+      def with(chars:) = self.class.new(chars: chars, format: @format)
+
+      # What emitting this message costs, which is a property of the format
+      # rather than of the record.
+      #
+      # json is measured against the serialized form instead of estimated from
+      # it: the field names are a fixed ~120 characters the prose never sees,
+      # and the escaping ratio varies with the message, so no constant tracks
+      # both. The trailing character is the comma that joins it to the next one.
+      def cost(message)
+        return message.to_json.length + 1 if json?
+
+        ENVELOPE_CHARS + message[:content].to_s.length + message[:clip_notice].to_s.length +
+          message[:author].to_s.length +
+          (message[:agent] ? AGENT_SUFFIX_CHARS : 0)
+      end
+
+      # Whether a message of this cost still fits alongside what has been spent.
+      # Takes the cost rather than the message so the caller can charge what it
+      # measured instead of serializing the same message twice.
+      #
+      # Deciding before keeping is the point: appending first and checking
+      # afterwards let a message wider than the entire cap through untouched.
+      def fits?(cost, spent: 0) = unlimited? || (spent + cost) <= @chars
+    end
+  end
+end

data/app/services/collavre/topics/last_topic_preference_payload.rb

@@ -0,0 +1,18 @@
+module Collavre
+  module Topics
+    class LastTopicPreferencePayload
+      def initialize(creative:, user:)
+        @creative = creative
+        @user = user
+      end
+
+      def call
+        preference = UserCreativePreference.find_by(user_id: @user&.id, creative_id: @creative.id)
+        {
+          last_topic_id: preference&.last_topic_id,
+          last_topic_revision: preference && [ preference.id, preference.last_topic_revision ]
+        }
+      end
+    end
+  end
+end