collavre 0.20.3 → 0.22.0

data/app/jobs/collavre/cancel_offline_delegated_tasks_job.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Reconnect-grace cancellation for delegated tasks owned by a Claude Channel
+  # session whose WebSocket dropped without DELETE /api/v1/agent/:id.
+  #
+  # AgentChannel#unsubscribed makes the agent unroutable, but a task already
+  # in "delegated" still holds its ResourceTracker slot and (for workflow
+  # subtasks) blocks the parent workflow. The dispatch was broadcast to a
+  # now-dead stream, so no client remains to call /reply — without this job
+  # the slot stays held until StuckDetectorJob times out (minutes to hours).
+  #
+  # The grace delay lets transient WS blips self-heal: if the client
+  # reconnects before the job fires, AgentChannel#subscribe_to_agent_stream
+  # restores routing_expression to "true" and writes a fresh subscription
+  # token. The job's online-state recheck then no-ops.
+  class CancelOfflineDelegatedTasksJob < ApplicationJob
+    queue_as :default
+
+    GRACE_SECONDS = 30
+
+    def perform(agent_id, expected_token, session_id = nil)
+      agent = User.find_by(id: agent_id)
+      return unless agent&.claude_channel_agent?
+
+      # Session-scoped variant: a live sibling may keep the shared agent
+      # routable (so the agent-wide rechecks below would no-op), but the
+      # dropped session's OWN session topic is private to it — siblings filter
+      # session_topic dispatches to their own topic, so none will /reply. Cancel
+      # only that topic's delegated work. Enqueued by AgentChannel#unsubscribed
+      # when a sibling remains; mirrors the destroy path's cancel_tasks_for_topic.
+      return cancel_dropped_session_tasks(agent, session_id) if session_id.present?
+
+      # Agent came back online during the grace window — the same MCP
+      # session (or a new one) is subscribed and can answer /reply.
+      return if agent.routing_expression.present?
+
+      # A session (reconnect or a still-live sibling sharing this agent) holds
+      # a LIVE presence row — the agent is online, its delegated work is still
+      # owned. Presence is the authority now that one agent fans out to many
+      # concurrent sessions. Reap crash-orphaned rows first so a dead process's
+      # leftover row can't masquerade as a live session and strand this work.
+      AgentSubscription.reap_stale!(agent.id)
+      return if AgentSubscription.live.where(agent_id: agent.id).exists?
+
+      # A different subscription has taken over (token rotated). The new
+      # session's lifecycle owns its own cancellation; don't double-cancel.
+      if expected_token.present? &&
+         agent.routing_subscription_token.present? &&
+         agent.routing_subscription_token != expected_token
+        return
+      end
+
+      cancel_delegated_tasks(Task.where(agent_id: agent.id, status: "delegated"), agent)
+    end
+
+    private
+
+    # Cancel only the dropped session's own session-topic delegated work, unless
+    # this same session reconnected within the grace window (a fresh live row
+    # under the same session_id). Work on OTHER topics is fan-out — any live
+    # sibling can still claim it — so it is deliberately left untouched.
+    def cancel_dropped_session_tasks(agent, session_id)
+      AgentSubscription.reap_stale!(agent.id)
+      return if AgentSubscription.live.where(agent_id: agent.id, session_id: session_id).exists?
+
+      topic = Topic.find_by(primary_agent_id: agent.id, session_id: session_id)
+      return unless topic
+
+      # Cancel queued/pending/running work FIRST. Otherwise cancelling the
+      # delegated task below calls dequeue_next_for_topic, which promotes the next
+      # queued task on this session topic into "delegated" and broadcasts it — but
+      # the session that owned this private topic is gone and siblings filter
+      # session_topic dispatches to their own topic, so nothing would /reply and
+      # the promoted task would hold its slot until stuck recovery. Draining the
+      # queue first leaves nothing to promote. Mirrors cancel_tasks_for_topic.
+      cancel_pending_tasks(
+        Task.where(agent_id: agent.id, topic_id: topic.id, status: %w[queued pending running]), agent
+      )
+      cancel_delegated_tasks(
+        Task.where(agent_id: agent.id, topic_id: topic.id, status: "delegated"), agent
+      )
+    end
+
+    def cancel_pending_tasks(tasks, agent)
+      return if tasks.empty?
+
+      tracker = Orchestration::ResourceTracker.for(agent)
+      tasks.find_each do |task|
+        was_running = task.status == "running"
+        task.update!(status: "cancelled")
+        tracker.release!(task.id) if was_running
+
+        next if task.parent_task_id.blank?
+
+        begin
+          Collavre::Comments::WorkflowExecutor.new(task.parent_task).fail_subtask!(
+            task, error_message: "Claude Channel session lost connection before dispatch"
+          )
+        rescue StandardError => e
+          Rails.logger.error(
+            "[CancelOfflineDelegatedTasksJob] fail_subtask! failed for queued task #{task.id}: #{e.message}"
+          )
+        end
+      end
+    end
+
+    def cancel_delegated_tasks(tasks, agent)
+      return if tasks.empty?
+
+      tracker = Orchestration::ResourceTracker.for(agent)
+      tasks.find_each do |task|
+        task.update!(status: "cancelled")
+        tracker.release!(task.id)
+
+        if task.parent_task_id.present?
+          begin
+            Collavre::Comments::WorkflowExecutor.new(task.parent_task).fail_subtask!(
+              task, error_message: "Claude Channel session lost connection before reply"
+            )
+          rescue StandardError => e
+            Rails.logger.error(
+              "[CancelOfflineDelegatedTasksJob] fail_subtask! failed for task #{task.id}: #{e.message}"
+            )
+          end
+        end
+
+        if task.topic_id.present?
+          Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
+        end
+      end
+    end
+  end
+end

data/app/jobs/collavre/claude_channel_presence_job.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Typing-indicator / "responding" presence for Claude Channel (MCP) agents.
+  #
+  # RubyLLM agents broadcast agent_status ("thinking" → "streaming" heartbeats →
+  # "idle") from inside their long-running AiAgentJob, which is what drives the
+  # chat typing indicator and Stop button. The Claude Channel path has no such
+  # loop: AiAgentService#delegate_to_claude_channel broadcasts the dispatch and
+  # returns immediately, with the reply arriving asynchronously via /reply. So
+  # the chat showed nothing while Claude worked.
+  #
+  # This job restores parity. Enqueued once per Claude dispatch, it:
+  #   - while the task is "delegated" and a session is LIVE → broadcasts a
+  #     working agent_status and re-enqueues itself every HEARTBEAT_SECONDS
+  #     (under the frontend's 10s AGENT_STATUS_TIMEOUT) so the indicator stays up;
+  #   - when no live session remains (never connected, or dropped mid-turn) →
+  #     broadcasts "idle" to clear the indicator and posts an authorless system
+  #     notice so a human sees the channel is disconnected rather than a phantom
+  #     "thinking"; (CancelOfflineDelegatedTasksJob owns the task-state cleanup);
+  #   - once the task leaves "delegated" (a /reply completed it, or it was
+  #     cancelled) → stops without re-enqueuing. The reply path broadcasts the
+  #     final "idle" itself, so the indicator clears immediately on reply.
+  class ClaudeChannelPresenceJob < ApplicationJob
+    queue_as :default
+
+    # Re-broadcast cadence. Must stay below the frontend AGENT_STATUS_TIMEOUT
+    # (10s) so the indicator never flickers off between beats, with room for one
+    # missed beat (queue jitter, GC pause).
+    HEARTBEAT_SECONDS = 5
+
+    def perform(task_id)
+      task = Task.find_by(id: task_id)
+      return unless task
+
+      agent = task.agent
+      return unless agent&.claude_channel_agent?
+
+      # A /reply completed the task (or it was cancelled). The reply path already
+      # broadcast the final "idle"; nothing more to do, and crucially do NOT post
+      # a disconnect notice for a normally-finished turn.
+      return unless task.reload.status == "delegated"
+
+      creative = resolve_creative(task)
+      return unless creative
+
+      AgentSubscription.reap_stale!(agent.id)
+
+      # Reuse the canonical status broadcaster that drives the typing indicator
+      # for every other agent (AiAgentService#execute_llm_conversation), so the
+      # "thinking"/"idle" payload stays identical across both paths.
+      lifecycle = AiAgent::AgentLifecycleManager.new(task: task, agent: agent, creative: creative)
+
+      if AgentSubscription.live.where(agent_id: agent.id).exists?
+        lifecycle.broadcast_status("thinking")
+        self.class.set(wait: HEARTBEAT_SECONDS.seconds).perform_later(task_id)
+      else
+        lifecycle.broadcast_status("idle")
+        post_disconnect_notice(creative, task)
+      end
+    end
+
+    private
+
+    def resolve_creative(task)
+      creative_id = task.creative_id || task.trigger_event_payload&.dig("creative", "id")
+      Creative.find_by(id: creative_id)&.effective_origin
+    end
+
+    def resolve_topic_id(task)
+      task.topic_id || task.trigger_event_payload&.dig("topic", "id")
+    end
+
+    # Authorless, non-dispatching system message so the human sees the channel is
+    # offline. skip_dispatch is essential: an authorless comment that matched the
+    # agent's routing would otherwise spawn a fresh delegated task — an infinite
+    # disconnect-notice loop.
+    def post_disconnect_notice(creative, task)
+      topic_id = resolve_topic_id(task)
+      return unless topic_id
+
+      creative.comments.create!(
+        content: I18n.t("collavre.claude_channel.disconnected"),
+        topic_id: topic_id,
+        private: false,
+        skip_default_user: true,
+        skip_dispatch: true
+      )
+    end
+  end
+end

data/app/jobs/collavre/drop_trigger_job.rb

@@ -8,6 +8,8 @@ module Collavre
     # This triggers retry_on instead of silently succeeding.
     class DispatchFailedError < StandardError; end
 
+    DROP_TRIGGER_TOPIC_NAME = "Drop Trigger"
+
     retry_on DispatchFailedError, wait: 5.seconds, attempts: 3
 
     # End-to-end idempotent: safe to retry at any point.
@@ -57,9 +59,8 @@ module Collavre
     private
 
     def post_trigger_failure_notice(child, parent)
-      topic = child.topics.find_or_create_by!(name: "Drop Trigger") do |t|
-        t.user = child.user
-      end
+      topic = child.topics.find_by(name: DROP_TRIGGER_TOPIC_NAME) ||
+              create_drop_trigger_topic(child)
       post_system_notice(child, topic, I18n.t(
         "collavre.drop_trigger.no_agent",
         parent_description: parent.creative_snippet
@@ -82,17 +83,45 @@ module Collavre
     end
 
     def find_or_create_trigger_topic(creative, agent)
-      topic = creative.topics.find_by(name: "Drop Trigger")
+      topic = creative.topics.find_by(name: DROP_TRIGGER_TOPIC_NAME)
       return topic if topic
 
-      topic = creative.topics.create!(
-        name: "Drop Trigger",
-        user: creative.user
-      )
+      topic = create_drop_trigger_topic(creative)
       topic.set_primary_agent!(agent)
       topic
     end
 
+    # Creates the Drop Trigger topic, branching from the creative's Main topic
+    # when Main has messages. Equivalent to the user manually selecting every
+    # Main message and pressing "branch" — only the resulting topic name is
+    # fixed to "Drop Trigger".
+    def create_drop_trigger_topic(creative)
+      main = creative.main_topic(fallback_user: creative.user)
+      # Mirror the manual "select all → branch" flow: only comments the owner
+      # can see are copied. enforce_limit: false bypasses the UI's 100-comment
+      # selection cap so full Main history transfers regardless of length.
+      main_comment_ids = main.comments
+                             .visible_to(creative.user)
+                             .order(:created_at)
+                             .pluck(:id)
+
+      if main_comment_ids.any?
+        # auto_select: false prevents the broadcast from hijacking the owner's
+        # current topic selection while this background job runs.
+        TopicBranchService.new(
+          creative: creative,
+          user: creative.user,
+          source_topic: main,
+          name: DROP_TRIGGER_TOPIC_NAME
+        ).call(comment_ids: main_comment_ids, enforce_limit: false, auto_select: false)
+      else
+        creative.topics.create!(
+          name: DROP_TRIGGER_TOPIC_NAME,
+          user: creative.user
+        )
+      end
+    end
+
     def trigger_content_key(child, parent)
       I18n.t(
         "collavre.drop_trigger.child_entered",

data/app/mailers/collavre/application_mailer.rb

@@ -1,6 +1,6 @@
 module Collavre
   class ApplicationMailer < ActionMailer::Base
-    default from: ENV.fetch("DEFAULT_MAILER_FROM", "no-reply@example.com")
+    default from: -> { Collavre::IntegrationSettings.fetch(:default_mailer_from, default: "no-reply@example.com") }
     layout "mailer"
 
     private

data/app/models/collavre/agent_subscription.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Presence record for one live Claude Channel session subscription on the
+  # per-agent ActionCable stream. The set of LIVE rows for an agent_id is the
+  # authority for whether routing_expression should be active: a human's
+  # concurrent sessions share one agent, so routing stays on while ANY session
+  # holds a live row, and only turns off when the last one is gone.
+  #
+  # Liveness is leased, not assumed. Rows are deleted only by
+  # AgentChannel#unsubscribed, so a Puma/ActionCable crash or deploy orphans a
+  # row. last_seen_at is refreshed by the channel's periodic heartbeat; a row
+  # whose last_seen_at falls outside STALE_AFTER is dead — ignored by the live
+  # scope so it cannot pin routing on, and reaped opportunistically on the next
+  # subscribe/unsubscribe for the agent.
+  class AgentSubscription < ApplicationRecord
+    self.table_name = "agent_subscriptions"
+
+    belongs_to :agent, class_name: Collavre.configuration.user_class_name
+
+    # Heartbeat cadence (see AgentChannel#subscribe_to_agent_stream). STALE_AFTER
+    # is a multiple of it so a single missed beat (GC pause, brief stall) does
+    # not flap a live session to "dead".
+    HEARTBEAT_SECONDS = 15
+    STALE_AFTER = 45.seconds
+
+    before_validation :ensure_last_seen_at, on: :create
+
+    scope :live, -> { where(arel_table[:last_seen_at].gt(STALE_AFTER.ago)) }
+    scope :stale, -> { where(arel_table[:last_seen_at].lteq(STALE_AFTER.ago)) }
+
+    # Refresh the heartbeat for one session's row. No-op if the row is already
+    # gone (a newer subscribe rotated it, or it was reaped) — the periodic
+    # callback must not resurrect a removed presence row.
+    def self.touch!(agent_id, token)
+      where(agent_id: agent_id, token: token).update_all(last_seen_at: Time.current)
+    end
+
+    # Drop crash-orphaned rows for an agent so a plain presence check is
+    # accurate. Scoped to one agent_id: cheap, and called on the agent's own
+    # subscribe/unsubscribe path.
+    def self.reap_stale!(agent_id)
+      stale.where(agent_id: agent_id).delete_all
+    end
+
+    private
+
+    def ensure_last_seen_at
+      self.last_seen_at ||= Time.current
+    end
+  end
+end

data/app/models/collavre/channel/injected_message.rb

@@ -0,0 +1,5 @@
+module Collavre
+  class Channel
+    InjectedMessage = Data.define(:speaker, :message, :label, :link)
+  end
+end

data/app/models/collavre/channel.rb

@@ -0,0 +1,87 @@
+module Collavre
+  class Channel < ApplicationRecord
+    BOT_EMAIL = "channel@collavre.local"
+    BOT_NAME = "Channel"
+
+    self.table_name = "channels"
+
+    belongs_to :topic, class_name: "Collavre::Topic"
+
+    enum :state, { active: 0, detached: 1 }, default: :active
+
+    scope :not_dismissed, -> { where(dismissed_at: nil) }
+
+    def handle(event:, payload:)
+      raise NotImplementedError, "#{self.class} must implement #handle"
+    end
+
+    # Chip fallbacks rendered before any webhook event populates latest_label /
+    # latest_link. Base class returns nil; subclasses override when they can
+    # derive a stable label/link from their own config (e.g. PR #N + URL).
+    def default_label
+      nil
+    end
+
+    def default_link
+      nil
+    end
+
+    # Badge interface for the typing-indicator chip. Subclasses override
+    # `badge_state` to drive the chip badge color (the value becomes a CSS
+    # modifier: channel-chip-badge--<state>), and `badge_title` to provide a
+    # localized title / aria-label string. Returning nil from `badge_state`
+    # hides the badge entirely.
+    def badge_state
+      nil
+    end
+
+    def badge_title
+      nil
+    end
+
+    def detach!
+      update!(state: :detached)
+    end
+
+    def dismissed?
+      dismissed_at.present?
+    end
+
+    # Hide the chip from the typing-indicator row. Performs detach! as a
+    # side-effect when the channel is still active so dismissal is a single
+    # user-facing action — clicking the X always removes the chip regardless
+    # of prior state.
+    def dismiss!
+      transaction do
+        detach! if active?
+        update!(dismissed_at: Time.current) if dismissed_at.nil?
+      end
+    end
+
+    def record_event!(label:, link:)
+      update!(latest_label: label, latest_link: link, last_event_at: Time.current)
+    end
+
+    def inject_into_topic!(injected_message)
+      transaction do
+        comment = topic.creative.comments.create!(
+          user: injected_message.speaker,
+          topic_id: topic.id,
+          content: injected_message.message,
+          private: false
+        )
+        record_event!(label: injected_message.label, link: injected_message.link)
+        comment
+      end
+    end
+
+    after_create_commit  :broadcast_chips_changed
+    after_update_commit  :broadcast_chips_changed
+
+    private
+
+    def broadcast_chips_changed
+      Collavre::CommentsPresenceChannel.broadcast_channel_chips_changed(topic.creative_id, topic_id: topic_id)
+    end
+  end
+end

data/app/models/collavre/comment/claude_channel_permission.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Collavre
+  class Comment < ApplicationRecord
+    # A native Claude Code tool-permission prompt surfaced into a topic as a
+    # structured approval comment (built by Api::V1::AgentsController#notify when
+    # the relayed notify carries a permission_request_id). It reuses the native
+    # approval comment UI — approver gate, approve button, ✅/🚫 decided label —
+    # but a decision does NOT execute a tool server-side (the tool runs inside
+    # the remote Claude Code process). Instead approve/deny relays the decision
+    # over the agent stream so the MCP plugin resolves the paused tool call.
+    module ClaudeChannelPermission
+      extend ActiveSupport::Concern
+
+      ACTION_TYPE = "claude_channel_permission"
+
+      # Raised when a decision was already recorded, so a double-click (or a
+      # concurrent approve+deny) resolves to exactly one decision.
+      class AlreadyDecided < StandardError; end
+
+      class_methods do
+        # Re-broadcast the recorded decision for each given request_id that belongs
+        # to this agent and has been decided. Called when a Claude Channel session
+        # sends the request_ids it still holds pending after a (re)subscribe
+        # (pull-on-resubscribe): broadcast_claude_channel_permission_decision fires
+        # once into the transient agent:user:<id> stream, so a decision clicked
+        # while the plugin's WebSocket was reconnecting lands in a subscriber-less
+        # stream and is lost — leaving the suspended tool hung with no retry path.
+        #
+        # The plugin's pending set is the SOLE bound: there is no wall-clock window,
+        # so a decision made during an outage of any length is still redelivered,
+        # and a decision the plugin already consumed is simply never requested. The
+        # coarse action LIKE filter (one per requested id) is narrowed by an exact
+        # request_id match per row before re-broadcasting; replay is idempotent
+        # (PermissionCoordinator.claim ignores a request_id it no longer holds), so
+        # an over-broad LIKE match is a harmless no-op on the plugin side.
+        def replay_claude_channel_permission_decisions_for(agent_id, request_ids)
+          ids = Array(request_ids).filter_map { |r| r.to_s.presence }.uniq
+          return if ids.empty?
+
+          # Build the coarse "action LIKE '%<rid>%'" prefilter with Arel matchers
+          # rather than a raw SQL fragment so the wildcards stay bound parameters
+          # (the surrounding %…% is ours; sanitize_sql_like escapes any %/_ inside
+          # the id). No interpolation into SQL — Brakeman-clean and identical
+          # semantics to the old OR-joined LIKE.
+          matcher = ids
+            .map { |rid| arel_table[:action].matches("%#{sanitize_sql_like(rid)}%") }
+            .reduce(:or)
+          where(user_id: agent_id)
+            .where.not(action_executed_at: nil)
+            .where(matcher)
+            .find_each do |comment|
+              next unless comment.claude_channel_permission?
+              next unless ids.include?(comment.claude_channel_permission_request_id)
+
+              comment.rebroadcast_claude_channel_permission_decision
+            end
+        end
+      end
+
+      # True when this comment's action payload is a Claude Channel permission
+      # prompt (vs. a native execute_tool/approve_tool action).
+      def claude_channel_permission?
+        claude_channel_permission_action.present?
+      end
+
+      def claude_channel_permission_request_id
+        claude_channel_permission_action&.dig("request_id")
+      end
+
+      # The decision, once made, is persisted into the action payload so the
+      # rendered comment can distinguish ✅ approved from 🚫 denied.
+      def claude_channel_permission_denied?
+        claude_channel_permission_action&.dig("decision") == "deny"
+      end
+
+      # Atomically record the human's allow/deny: stamp action_executed_at/by
+      # (which hides the buttons and marks the comment decided) and persist the
+      # decision into the action payload. Raises AlreadyDecided if a decision was
+      # already recorded.
+      def decide_claude_channel_permission!(behavior, by:)
+        behavior = behavior.to_s
+        raise ArgumentError, "behavior must be allow or deny" unless %w[allow deny].include?(behavior)
+
+        with_lock do
+          reload
+          raise AlreadyDecided if action_executed_at.present?
+
+          payload = claude_channel_permission_action
+          raise ArgumentError, "not a Claude Channel permission comment" unless payload
+
+          payload["decision"] = behavior
+          update!(
+            action: JSON.pretty_generate(payload),
+            action_executed_at: Time.current,
+            action_executed_by: by
+          )
+        end
+      end
+
+      # Relay the decision to the suspended session over the agent stream. The
+      # MCP plugin matches request_id against the prompts it surfaced, so sibling
+      # sessions sharing this (shared) agent ignore a request_id they never
+      # raised. task_id is intentionally absent: the decision only unblocks the
+      # paused tool call; the in-flight delegated task completes later via /reply.
+      def broadcast_claude_channel_permission_decision(behavior)
+        request_id = claude_channel_permission_request_id
+        return false if request_id.blank? || user_id.blank?
+
+        AgentChannel.broadcast_to_agent(user_id, {
+          type: "permission_decision",
+          request_id: request_id,
+          behavior: behavior.to_s,
+          agent_id: user_id
+        })
+        true
+      end
+
+      # Replay this comment's already-recorded decision (used by the resubscribe
+      # path). Unlike broadcast_claude_channel_permission_decision the behavior is
+      # read from the persisted payload rather than passed in, and only a comment
+      # that is both a permission prompt and decided re-broadcasts — a still-
+      # pending prompt has no decision to deliver.
+      def rebroadcast_claude_channel_permission_decision
+        return false unless claude_channel_permission?
+
+        decision = claude_channel_permission_action&.dig("decision")
+        return false if decision.blank?
+
+        broadcast_claude_channel_permission_decision(decision)
+      end
+
+      private
+
+      def claude_channel_permission_action
+        return nil if action.blank?
+
+        parsed = JSON.parse(action)
+        parsed.is_a?(Hash) && parsed["action"] == ACTION_TYPE ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end