collavre 0.24.0 → 0.25.0

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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Posts one public message into an existing topic and starts the topic's
+  # normal orchestration route.
+  class TopicMessageCreateService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "topic_message_create"
+    tool_description <<~DESC.strip
+      Post a public message to an existing Collavre topic.
+
+      Use this after topic_create to give the topic's primary agent its initial
+      instruction. A primary-agent pin is exclusive, so an ambient message here
+      starts that agent and no other agent. Messages posted to different topics
+      can run concurrently; messages posted to the same topic queue behind the
+      topic's current work.
+
+      The caller remains the message author. Human-authored messages use normal
+      comment dispatch, while agent-authored messages are dispatched as A2A work
+      so an agent can fan work out without impersonating a human. The content is
+      stored as written and may use Markdown. An agent cannot post to the topic
+      it is currently handling; continue that work in the current turn instead.
+
+      Requires feedback permission or better on the topic's creative. Archived
+      creatives, archived topics, and an inbox's reserved System topic do not
+      accept messages through this tool.
+    DESC
+
+    tool_param :topic_id, description: "The topic to post the message to."
+    tool_param :content, description: "The public message body or initial instruction. Markdown is supported."
+
+    sig { params(topic_id: Integer, content: String).returns(T::Hash[Symbol, T.untyped]) }
+    def call(topic_id:, content:)
+      user = Current.user || raise(I18n.t("collavre.tools.topic_message_create.errors.current_user_required"))
+      topic = Topic.find(topic_id)
+      TopicAuthorizer.authorize_feedback!(topic, user: user)
+      principal = workspace_user(user)
+
+      comment = create_comment(topic, content, user, principal)
+      if user.ai_user?
+        selection = prepare_selection(comment, principal)
+        reject_selected_self_route!(selection.agents, user, principal)
+        dispatch_agent_message(comment, user, principal, selection)
+      end
+
+      serialize(comment)
+    end
+
+    private
+
+    def create_comment(topic, content, user, principal)
+      Comment.transaction do
+        topic.lock!
+        TopicAuthorizer.authorize_feedback!(topic, user: user)
+        reject_closed_topic!(topic)
+        reject_unrunnable_self_dispatch!(topic, user, principal)
+
+        comment = topic.comments.create!(
+          creative: topic.creative,
+          content: content,
+          user: user,
+          private: false,
+          skip_dispatch: user.ai_user?
+        )
+        selection = prepare_selection(comment, principal) if user.ai_user?
+        reject_selected_self_route!(selection&.agents, user, principal)
+
+        comment
+      end
+    end
+
+    def reject_closed_topic!(topic)
+      if topic.creative.archived?
+        raise ArgumentError, I18n.t("collavre.tools.topic_message_create.errors.archived_creative")
+      end
+      if topic.archived?
+        raise ArgumentError, I18n.t("collavre.tools.topic_message_create.errors.archived_topic")
+      end
+      return unless topic.creative.inbox? && topic.name == Creative::SYSTEM_TOPIC_NAME
+
+      raise ArgumentError, I18n.t("collavre.tools.topic_message_create.errors.system_topic")
+    end
+
+    def reject_unrunnable_self_dispatch!(topic, user, principal)
+      return unless user.ai_user?
+
+      same_topic = Current.agent_turn&.dig(:task)&.topic_id == topic.id
+      return unless same_topic || (principal.nil? && topic.primary_agent_id == user.id)
+
+      raise ArgumentError, I18n.t("collavre.tools.topic_message_create.errors.current_topic")
+    end
+
+    def prepare_selection(comment, principal)
+      Orchestration::AgentOrchestrator.prepare_selection(
+        "comment_created", dispatch_payload(comment, principal),
+        candidate_overrides: candidate_overrides(comment.user, principal)
+      )
+    end
+
+    def dispatch_agent_message(comment, user, principal, selection)
+      selected_agents = selection.agents
+      context_for = lambda do |agent|
+        next {} unless agent.id == user.id && principal
+
+        { "sender" => SystemEvents::ContextBuilder.sender_context_for(principal) }
+      end
+      payload = dispatch_payload(comment, principal)
+      if selected_agents.any? { |agent| agent.id == user.id }
+        payload[Orchestration::DeferredTriggerScope::SELF_AUTHORED_COMMENT_ID_KEY] = comment.id
+      end
+      SystemEvents::Dispatcher.dispatch(
+        "comment_created", payload, source: "a2a", parent: parent_envelope,
+        selection: selection, context_for: context_for,
+        scheduling_hooks: scheduling_hooks(user, comment)
+      )
+    end
+
+    def scheduling_hooks(user, comment)
+      Orchestration::SchedulingHooks.new(
+        interaction_callback: ->(agent) { interaction_for(agent, user, comment.creative_id) },
+        scheduled_callback: ->(agents) { record_interactions(agents, user, comment.creative_id) }
+      )
+    end
+
+    def candidate_overrides(user, principal)
+      return {} unless principal
+
+      { user.id => { "sender" => SystemEvents::ContextBuilder.sender_context_for(principal) } }
+    end
+
+    def dispatch_payload(comment, principal)
+      comment.dispatch_payload.merge(workspace_user_id: principal&.id).tap do |payload|
+        payload[:comment][:from_ai] = comment.user.ai_user?
+      end
+    end
+
+    def reject_selected_self_route!(selected_agents, user, principal)
+      return if selected_agents.nil?
+
+      self_selected = selected_agents.any? { |agent| agent.id == user.id }
+      return unless self_selected && principal.nil?
+
+      raise ArgumentError, I18n.t("collavre.tools.topic_message_create.errors.self_route")
+    end
+
+    def parent_envelope
+      SystemEvents::Envelope.in(Current.agent_turn&.dig(:task)&.trigger_event_payload)
+    end
+
+    def record_interactions(selected_agents, user, creative_id)
+      context = { "creative" => { "id" => creative_id } }
+      selected_agents.each do |agent|
+        interaction = interaction_for(agent, user, creative_id)
+        next unless interaction
+
+        Orchestration::LoopBreaker.new(context).record_interaction(
+          interaction[:from_agent_id], interaction[:to_agent_id], creative_id
+        )
+      end
+    end
+
+    def interaction_for(agent, user, creative_id)
+      return if agent.id == user.id
+
+      { from_agent_id: user.id, to_agent_id: agent.id, creative_id: creative_id }
+    end
+
+    def workspace_user(user)
+      return Current.agent_turn[:user] if Current.agent_turn
+
+      creator = user.creator
+      creator if creator && !creator.ai_user?
+    end
+
+    def serialize(comment)
+      {
+        id: comment.id,
+        topic_id: comment.topic_id,
+        creative_id: comment.creative_id,
+        content: comment.content,
+        author: { id: comment.user_id, name: comment.user.display_name },
+        created_at: comment.created_at.iso8601
+      }
+    end
+  end
+end
+end

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

@@ -0,0 +1,346 @@
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Reads a page of messages from one or more topics.
+  #
+  # Multi-topic in one call, but never interleaved: each topic is windowed and
+  # reported on its own. A merged cross-topic timeline would be the wrong answer
+  # to the question people actually ask ("summarize #a, #b and #c") — three
+  # conversations shuffled by timestamp read as none of them — and it would make
+  # offset meaningless, since a merged offset moves when any of the topics grows.
+  #
+  # Per-topic windows keep offset reproducible, and max_chars keeps the total
+  # bounded so asking for three topics cannot return three times the context you
+  # planned for.
+  class TopicMessagesService
+    extend T::Sig
+    extend ToolMeta
+
+    # Roughly a mid-sized page of prose per call. The cap is on the whole
+    # response rather than per topic because the caller's context is the shared
+    # resource: five topics at a comfortable per-topic size is not a comfortable
+    # call.
+    DEFAULT_MAX_CHARS = 40_000
+    MAX_MAX_CHARS = 200_000
+
+    # A successful bounded fallback needs enough room to explain why the
+    # requested response was omitted. Values below this are raised to the
+    # minimum instead of returning a response wider than the cap just to spell
+    # out that the cap was too small.
+    MIN_MAX_CHARS = 160
+
+    # Each topic also pays for its own heading, totals line and "More:" call —
+    # or, if it does not fit, its not-fetched notice, which is about the same
+    # size. Charged separately from the messages so that a call for many topics
+    # cannot overrun the cap on section furniture alone.
+    #
+    # json restates the same section as the seventeen keys of the entry hash
+    # plus their delimiters — around 285 characters measured, against the two
+    # lines markdown prints — so the reserve is per format rather than one
+    # constant that is right for one of them and wrong for the other.
+    TOPIC_HEADER_CHARS = { "markdown" => 350, "json" => 525 }.freeze
+
+    # The trailing "output hit max_chars" notice, which only exists when the
+    # budget ran out and so cannot be paid for out of what is left of it.
+    TRUNCATION_CHARS = 120
+    NOTHING_FITS_REASON = "max_chars is too small to return anything for this topic"
+
+    tool_name "topic_messages"
+    tool_description <<~DESC.strip
+      Read messages from one or more Collavre topics, newest first, with paging.
+
+      Messages are selected from the newest end: offset 0 is the latest message,
+      offset 100 starts 100 messages back. Within the returned window they are
+      rendered oldest-to-newest by default so the transcript reads forwards
+      (pass order: "desc" for newest-first rendering).
+
+      Multiple topics per call are windowed independently and returned grouped
+      by topic — offset/limit apply to EACH topic, never to a merged timeline.
+      Use this to summarize several topics at once, e.g.
+      topic_messages(topic_ids: "12,45,78", limit: 100).
+      Multi-topic calls are first-page reads: each topic returns its own cursor
+      and snapshot, so continue each topic in a separate call rather than
+      applying one topic's continuation state to the whole batch.
+
+      Every topic reports total_count and total_chars for the whole topic, so
+      you can tell how much you have not read yet, plus has_more, next_offset,
+      and next_cursor for the next call. Pass next_cursor and the returned
+      newest_message_id back on follow-up pages. The snapshot id excludes newly
+      created messages; the cursor also excludes older messages moved into the
+      topic later and keeps paging stable when earlier rows leave. It binds a
+      clipped continuation to that row's content version, so an edit restarts
+      the changed message at character zero rather than applying a stale offset.
+
+      If one message is too large for the response cap, its row remains at the
+      same next_offset and next_content_offset identifies the next character to
+      read. Repeat those values with next_cursor and the snapshot id until
+      next_content_offset is absent; only then has that message row been
+      consumed.
+
+      Markdown "More:" calls repeat the resolved limit and max_chars as well
+      as the cursor, snapshot, order, scope, and content offset, so following
+      one keeps the same context budget and paging semantics.
+
+      Image attachments are appended to message content as explicit markers
+      with filename, content type, byte size, and a readable public-asset URL.
+      Image-only comments therefore remain visible, and attachment metadata is
+      covered by the same max_chars/content_offset continuation as prose.
+
+      The response is capped at max_chars in total, measured against the format
+      you asked for — json is charged for its field names and string escaping,
+      so the same call returns fewer messages as json than as markdown. A topic
+      that does not fit is returned partially or marked not-fetched rather than
+      silently trimmed — check "truncated" and each topic's next_offset. A
+      single message wider than the whole cap is clipped rather than dropped,
+      given a content continuation and counted in the topic's clipped_count. If
+      fixed
+      metadata such as a topic name cannot fit, the tool returns a bounded
+      error instead of exceeding max_chars or silently omitting a topic.
+
+      Long topics: call topic_list first to see message_count, then page. To
+      summarize a whole large topic, follow next_cursor while keeping
+      max_message_id fixed, until has_more is false.
+
+      Requires read permission on each topic's creative. Private messages you
+      cannot see and approval prompts are always excluded; authorless system
+      notices are excluded by default (see include_system). Unknown or
+      unreadable ids are reported per topic instead of failing the call.
+    DESC
+
+    tool_param :topic_ids, description: "Topic ids to read. Comma-separated for several, e.g. \"12,45,78\" (max #{TopicSelection::MAX_TOPICS} per call — asking for more is an error, not a silent trim). A single id also works."
+    tool_param :offset, description: "How many messages back from the newest to start, applied per topic (default: 0).", required: false
+    tool_param :cursor, description: "Opaque per-topic snapshot/keyset cursor returned as next_cursor. Pass it on a single-topic follow-up page so later move-ins stay excluded and moved or deleted earlier messages cannot shift and skip unread rows.", required: false
+    tool_param :limit, description: "Messages per topic (default: #{Topics::MessagePage::DEFAULT_LIMIT}, max #{Topics::MessagePage::MAX_LIMIT}).", required: false
+    tool_param :order, description: "Rendering order within the returned window: 'asc' (default, oldest-to-newest — reads as a transcript) or 'desc' (newest first). Does not change which messages the window selects.", required: false, enum: Topics::MessagePage::ORDERS
+    tool_param :max_message_id, description: "Only consider messages with id <= this. Pass the newest_message_id from your first page on every single-topic follow-up page so paging stays on one snapshot of a live topic.", required: false
+    tool_param :content_offset, description: "Character offset within the first selected message (default: 0). For a clipped message, make a single-topic follow-up that repeats next_offset and next_cursor, and pass next_content_offset here with the same max_message_id until the whole row has been returned.", required: false
+    tool_param :include_system, description: "Include authorless system notices such as concurrency and channel announcements (default: false). Approval prompts are never returned.", required: false
+    tool_param :max_chars, description: "Character cap for the whole response across all topics, measured in the format you requested (default: #{DEFAULT_MAX_CHARS}, min #{MIN_MAX_CHARS}, max #{MAX_MAX_CHARS}). Values below the minimum are raised to it.", required: false
+    tool_param :format, description: "'markdown' (default, compact transcript) or 'json' (same data, structured; costs noticeably more of max_chars for the same messages, since field names and string escaping are charged too).", required: false, enum: Topics::CharBudget::FORMATS
+
+    sig do
+      params(
+        topic_ids: T.any(String, Integer, T::Array[T.untyped]),
+        options: T.untyped
+      ).returns(T.any(String, T::Hash[Symbol, T.untyped]))
+    end
+    def call(topic_ids:, **options)
+      options.assert_valid_keys(
+        :offset, :limit, :order, :cursor, :max_message_id, :content_offset, :include_system, :max_chars, :format
+      )
+      user = Current.user || raise("Current.user is required")
+      ids = IdList.parse(topic_ids)
+      raise ArgumentError, "topic_ids is required" if ids.empty?
+      reject_batch_continuation!(ids, options)
+
+      # The cap and the format it counts in are resolved together and carried
+      # through as one object, because what a message costs is what emitting it
+      # in this format costs. Budgeting in markdown's units and then returning
+      # json is how a 40k cap emits 60k.
+      budget = Topics::CharBudget.new(chars: clamp_chars(options[:max_chars]), format: options[:format])
+
+      payload = build_payload(
+        ids: ids, user: user,
+        options: page_options(options, budget)
+      )
+
+      response = budget.json? ? payload : Topics::MessagePageMarkdown.call(payload)
+      enforce_cap(response, budget)
+    end
+
+    private
+
+    def reject_batch_continuation!(ids, options)
+      return if ids.one?
+      return unless options[:cursor].present? || options[:max_message_id].present? ||
+        options[:content_offset].to_i.positive?
+
+      raise ArgumentError,
+        "cursor, max_message_id, and content_offset continuation values belong to one topic; " \
+        "continue each topic in a separate topic_messages call."
+    end
+
+    def page_options(options, budget)
+      {
+        offset: options.fetch(:offset, 0).to_i,
+        cursor: options[:cursor],
+        limit: options[:limit],
+        order: options[:order],
+        max_message_id: options[:max_message_id],
+        content_offset: options.fetch(:content_offset, 0).to_i,
+        include_system: options.fetch(:include_system, false),
+        budget: budget
+      }
+    end
+
+    def build_payload(ids:, user:, options:)
+      topics, errors = TopicSelection.resolve(ids, user: user)
+      entries = collect(topics, errors, user, options)
+
+      {
+        topics: entries + errors,
+        truncated: entries.any? { |entry| entry[:skipped_reason] || entry[:budget_limited] || entry[:clipped_count] },
+        max_chars: options[:budget].chars
+      }
+    end
+
+    # Topics are served in request order and the budget is spent as it goes, so
+    # an early huge topic can leave later ones unfetched. That is reported per
+    # topic rather than smoothed over: the caller asked for a specific order and
+    # needs to know which of its topics it is still missing.
+    #
+    # What is charged is what is emitted — message envelopes as well as prose.
+    # Counting content alone let a few hundred one-word messages print their
+    # ids, timestamps and authors for free and sail past the cap.
+    #
+    # Every requested topic prints a section whether or not it fits, so all the
+    # headers are reserved before any topic spends on messages. Reserving them
+    # one at a time would charge only the topics that succeed, and the
+    # not-fetched notices — which exist precisely because the budget ran out —
+    # would push the response over the cap that skipping them was enforcing.
+    def collect(topics, errors, user, options)
+      budget = options[:budget]
+      remaining = budget.chars - reserved_chars(topics, errors, budget.format)
+      served = false
+
+      topics.map do |topic|
+        next not_fetched(topic, options[:offset], options[:content_offset], options[:cursor], served) if remaining <= 0
+
+        entry = page_entry(topic, user, options, remaining)
+        remaining -= entry[:billed_chars].to_i
+        served = true
+        entry
+      end
+    end
+
+    def reserved_chars(topics, errors, format)
+      per_topic = TOPIC_HEADER_CHARS.fetch(format)
+      TRUNCATION_CHARS + topics.sum { |topic| per_topic + topic.name.to_s.length } +
+        error_chars(errors, format)
+    end
+
+    def error_chars(errors, format)
+      return errors.sum { |error| error.to_json.length + 1 } if format == "json"
+
+      errors.sum { |error| Topics::MessagePageMarkdown.render_error(error).length + 1 }
+    end
+
+    def page_entry(topic, user, options, remaining)
+      page = Topics::MessagePage.new(
+        topic: topic, user: user,
+        offset: options[:offset], limit: options[:limit], order: options[:order] || Topics::MessagePage::DEFAULT_ORDER,
+        include_system: options[:include_system], max_message_id: options[:max_message_id],
+        content_offset: options[:content_offset], cursor: options[:cursor],
+        budget: options[:budget].with(chars: remaining)
+      ).call
+
+      serialize(page, include_system: options[:include_system], max_chars: options[:budget].chars)
+    end
+
+    def serialize(page, include_system:, max_chars:)
+      {
+        topic_id: page.topic.id,
+        topic_name: page.topic.name,
+        creative_id: page.topic.creative_id,
+        total_count: page.total_count,
+        total_chars: page.total_chars,
+        offset: page.offset,
+        limit: page.limit,
+        max_chars: max_chars,
+        order: page.order,
+        returned_count: page.returned_count,
+        returned_chars: page.returned_chars,
+        # What this topic charged against max_chars: what emitting these
+        # messages in the requested format costs, not what their prose measures.
+        billed_chars: page.billed_chars,
+        has_more: page.has_more?,
+        next_offset: page.next_offset,
+        next_cursor: page.next_cursor,
+        next_content_offset: page.next_content_offset,
+        newest_message_id: page.newest_message_id,
+        # Echoed so the rendered "More:" line can repeat it. A continuation
+        # that drops it pages a narrower set at the same offset and skips
+        # whatever the wider first page had already counted.
+        include_system: (true if include_system),
+        # Only present when the shared max_chars budget, rather than `limit`,
+        # is what ended this topic's window — the caller's fix differs: raise
+        # max_chars or ask for fewer topics, not just page again.
+        budget_limited: page.budget_exhausted.presence,
+        # Present only when max_chars cut a message short rather than cutting
+        # the window between rows. next_content_offset resumes the same row.
+        clipped_count: page.clipped_count.nonzero?,
+        skipped_reason: nothing_fits_reason(page),
+        messages: page.messages
+      }.compact
+    end
+
+    def nothing_fits_reason(page)
+      NOTHING_FITS_REASON if page.returned_count.zero? && page.budget_exhausted
+    end
+
+    # Carries has_more/next_offset so the caller can resume this topic without
+    # having to work out that "no messages" here means "not read yet" rather
+    # than "empty topic".
+    #
+    # The reason distinguishes the two ways to run out of room, because the
+    # fixes differ: drop topics from the call, or raise the cap. Blaming
+    # "earlier topics" when this was the first one sends the caller the wrong way.
+    def not_fetched(topic, offset, content_offset, cursor, served)
+      reason = if served
+        "max_chars budget spent on earlier topics"
+      else
+        NOTHING_FITS_REASON
+      end
+
+      {
+        topic_id: topic.id,
+        topic_name: topic.name,
+        creative_id: topic.creative_id,
+        offset: offset,
+        next_content_offset: content_offset.presence,
+        returned_count: 0,
+        returned_chars: 0,
+        billed_chars: 0,
+        has_more: true,
+        next_offset: offset,
+        next_cursor: cursor.presence,
+        skipped_reason: reason,
+        messages: []
+      }
+    end
+
+    def clamp_chars(max_chars)
+      value = max_chars.to_i
+      return DEFAULT_MAX_CHARS if value <= 0
+
+      value.clamp(MIN_MAX_CHARS, MAX_MAX_CHARS)
+    end
+
+    # Message budgeting normally keeps the rendered response below max_chars,
+    # but fixed metadata can be wider than its budget by itself: a tiny cap, a
+    # batch of skipped topics, or one unrestricted topic name is enough. The
+    # final emitted form is the only authoritative measurement, so replace an
+    # oversized result with a bounded error instead of silently chopping a
+    # topic name or returning malformed JSON/Markdown.
+    def enforce_cap(response, budget)
+      emitted_chars = budget.json? ? response.to_json.length : response.length
+      return response if emitted_chars <= budget.chars
+
+      bounded_error(budget, required_chars: emitted_chars)
+    end
+
+    def bounded_error(budget, required_chars:)
+      return {
+        error: "topic_messages metadata exceeds max_chars",
+        required_chars: required_chars,
+        max_chars: budget.chars,
+        truncated: true
+      } if budget.json?
+
+      "> topic_messages metadata needs #{required_chars} chars; max_chars is #{budget.chars}. " \
+        "Request fewer topics or raise max_chars.\n"
+    end
+  end
+end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Collavre
+require "sorbet-runtime"
+require "rails_mcp_engine"
+module Tools
+  # Moves one complete topic to another creative using the same relocation
+  # primitive as the drag-and-drop UI.
+  class TopicMoveService
+    extend T::Sig
+    extend ToolMeta
+
+    tool_name "topic_move"
+    tool_description <<~DESC.strip
+      Move a complete topic to another creative while keeping its topic id,
+      messages, archive state, and read cursors.
+
+      The primary-agent pin moves too when that agent can still respond on the
+      destination. Otherwise the pin is released and the result explains why,
+      so the moved topic remains routable. Creative permissions do not move:
+      people who could read the source may lose access at the destination.
+
+      Requires admin permission on the topic's current creative and write
+      permission on the destination. The destination id may be a linked
+      creative; the topic moves to its origin. Topic names are unique per
+      creative. Main, an inbox's System topic, and live agent session topics
+      cannot be moved. Wait for or cancel active agent work before moving its
+      topic, and wait for any dropped-message restoration to settle. Cancel
+      recurring cron jobs targeting the topic and recreate them after the move.
+      A topic referenced by a Drop Trigger loop cannot move.
+    DESC
+
+    tool_param :topic_id, description: "The topic to move."
+    tool_param :creative_id, description: "The destination creative. Linked creatives resolve to their origin."
+
+    sig { params(topic_id: Integer, creative_id: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    def call(topic_id:, creative_id:)
+      user = Current.user || raise(I18n.t("collavre.tools.topic_move.errors.current_user_required"))
+      topic = Topic.find(topic_id)
+      authorize_source!(topic, user)
+      target = Creative.find(creative_id).effective_origin
+      authorize_target!(target, user)
+      source = topic.creative.effective_origin
+
+      released_agent, released_reason = move(topic, target, source, user)
+
+      Topics::Serializer.for_tool(topic).merge(
+        moved_from_creative_id: source.id,
+        released_primary_agent: released_agent_payload(released_agent, released_reason, target)
+      ).compact
+    end
+
+    private
+
+    def move(topic, target, source, user)
+      effects = Topics::TopicMoveEffects.new(topic, source, target)
+      Topics::TopicMove.new(topic: topic, target_creative: target).call(after_commit: effects.method(:call)) do |locked_topic|
+        authorize_source!(locked_topic, user)
+        authorize_target!(target, user)
+        validate_move!(locked_topic, target)
+      end
+    end
+
+    def authorize_source!(topic, user)
+      TopicAuthorizer.authorize_admin!(topic, user: user)
+    rescue PermissionDeniedError
+      raise PermissionDeniedError, I18n.t("collavre.tools.topic_move.errors.source_permission")
+    end
+
+    def authorize_target!(target, user)
+      TopicAuthorizer.authorize_creative!(target, :write, user: user)
+    rescue PermissionDeniedError
+      raise PermissionDeniedError, I18n.t("collavre.tools.topic_move.errors.target_permission")
+    end
+
+    def validate_move!(topic, target)
+      raise ArgumentError, I18n.t("collavre.tools.topic_move.errors.same_creative") if topic.creative_id == target.id
+      raise ArgumentError, I18n.t("collavre.tools.topic_move.errors.reserved_topic") if reserved?(topic, target)
+      raise ArgumentError, I18n.t("collavre.tools.topic_move.errors.session_topic") if topic.session_id.present?
+      return unless target.topics.where(name: topic.name).exists?
+
+      raise ArgumentError, I18n.t("collavre.tools.topic_move.errors.duplicate_name", name: topic.name)
+    end
+
+    def reserved?(topic, target)
+      Topics::ReservedName.reserved?(topic.creative, topic.name) ||
+        Topics::ReservedName.reserved?(target, topic.name)
+    end
+
+    def released_agent_payload(agent, reason, target)
+      return unless agent
+
+      {
+        id: agent.id,
+        name: agent.display_name,
+        reason: reason.to_s,
+        message: released_agent_message(agent, reason, target)
+      }
+    end
+
+    def released_agent_message(agent, reason, target)
+      key = reason == :session_agent_outside_session_topic ?
+        "primary_agent_released_session_agent" : "primary_agent_released"
+      I18n.t("collavre.topics.move.#{key}", agent: agent.display_name, creative: target.creative_snippet)
+    end
+  end
+end
+end