collavre 0.24.0 → 0.25.0

data/app/jobs/collavre/push_notification_job.rb

@@ -1,5 +1,17 @@
 module Collavre
 class PushNotificationJob < ApplicationJob
+  # Comment bodies are unbounded and go out as the notification body verbatim,
+  # so FCM rejects the oversized ones permanently — retrying cannot help, the
+  # payload is the defect. Two rejections were observed in production: "Message
+  # is too large. The maximum is 4K (4096 bytes)." above ~4.8KB, and a bare
+  # "INVALID_ARGUMENT: Invalid argument." starting at 2440 bytes. Budget the
+  # whole request at half of FCM's documented ceiling, which also sits below the
+  # smallest payload FCM has actually refused for us. A notification body is a
+  # preview anyway; no shade renders more than a few lines.
+  MAX_REQUEST_BYTES = 2048
+  ELLIPSIS = "…".freeze
+  TITLE = "새 알림".freeze
+
   queue_as :default
 
   def perform(user_id, message:, link: nil)
@@ -27,22 +39,9 @@ class PushNotificationJob < ApplicationJob
   private
 
   def send_v1(service, project_id, token, message, link)
-    notification = Google::Apis::FcmV1::Notification.new(
-      title: "새 알림",
-      body: message
-    )
-
-    webpush = Google::Apis::FcmV1::WebpushConfig.new(
-      fcm_options: Google::Apis::FcmV1::WebpushFcmOptions.new(link: link)
-    )
-
-    msg = Google::Apis::FcmV1::Message.new(
-      token: token,
-      notification: notification,
-      webpush: webpush,
-      data: { path: link }
-    )
-    Rails.logger.info("Sending push to token: #{token} with message: #{message} and link: #{link}")
+    body = fit_body(token, message, link)
+    msg = build_message(token, body, link)
+    Rails.logger.info("Sending push to token: #{token} with #{body.bytesize} body bytes and link: #{link}")
 
     request = Google::Apis::FcmV1::SendMessageRequest.new(message: msg)
 
@@ -51,16 +50,61 @@ class PushNotificationJob < ApplicationJob
       Rails.logger.info("✅ Push sent successfully: #{token} #{response.inspect}")
       response
     rescue Google::Apis::ClientError => e
+      # A 4xx is about this one registration, not the notification: the endpoint
+      # is gone, or that push service refused the payload. Raising would abandon
+      # every device queued behind it, which is how one stale subscription used
+      # to silence a user's other browsers. Transient errors (auth, 5xx) still
+      # propagate so the job retries.
       if invalid_registration_token?(e)
         Rails.logger.warn("⚠️ Removing invalid FCM token: #{token} (#{e.message})")
         Device.where(fcm_token: token).delete_all
-        nil
       else
-        raise
+        Rails.logger.warn("⚠️ FCM rejected the push for token #{token}: #{e.message}")
       end
+      nil
     end
   end
 
+  def build_message(token, body, link)
+    Google::Apis::FcmV1::Message.new(
+      token: token,
+      notification: Google::Apis::FcmV1::Notification.new(title: TITLE, body: body),
+      webpush: Google::Apis::FcmV1::WebpushConfig.new(
+        fcm_options: Google::Apis::FcmV1::WebpushFcmOptions.new(link: link)
+      ),
+      data: { path: link }
+    )
+  end
+
+  # Everything except the body — token, title, link (twice) and the JSON
+  # envelope — is fixed, so measure it and spend whatever is left on the body.
+  # Deriving the budget instead of hardcoding a character count keeps the cap
+  # correct when a long deep link crowds out the text.
+  def fit_body(token, message, link)
+    text = message.to_s
+    return text if request_bytesize(token, text, link) <= MAX_REQUEST_BYTES
+
+    budget = MAX_REQUEST_BYTES - request_bytesize(token, "", link) - ELLIPSIS.bytesize
+    return ELLIPSIS if budget <= 0
+
+    truncate_bytes(text, budget) + ELLIPSIS
+  end
+
+  def request_bytesize(token, body, link)
+    Google::Apis::FcmV1::SendMessageRequest
+      .new(message: build_message(token, body, link))
+      .to_json
+      .bytesize
+  end
+
+  # byteslice can cut a multi-byte character in half; scrub drops the dangling
+  # bytes rather than shipping invalid UTF-8 that FCM would reject in turn.
+  def truncate_bytes(text, max_bytes)
+    return text if text.bytesize <= max_bytes
+
+    text.byteslice(0, max_bytes).scrub("")
+  end
+
   def invalid_registration_token?(error)
     status_code = error.respond_to?(:status_code) ? error.status_code : nil
     return false unless status_code == 404

data/app/jobs/collavre/restore_dropped_dispatches_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Backstop for Orchestration::DeliveryRecord.restore!, which runs from a
+  # status callback and therefore after the point where its own failure could
+  # still be undone. See DeliveryRecord.restore_missed! for why nothing has to
+  # be written down for this to work.
+  #
+  # Scheduled in config/recurring.yml.
+  class RestoreDroppedDispatchesJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      Orchestration::DeliveryRecord.restore_missed!
+    end
+  end
+end

data/app/jobs/collavre/stuck_detector_job.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Collavre
-  # StuckDetectorJob runs periodically to detect stuck tasks and creatives.
+  # StuckDetectorJob runs periodically to recover and escalate stuck tasks.
   #
   # This job should be scheduled to run every 5-10 minutes via cron or similar.
   #

data/app/jobs/collavre/touch_creative_subtree_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Collavre
+  class TouchCreativeSubtreeJob < ApplicationJob
+    queue_as :default
+
+    def perform(creative_id)
+      creative = Creative.find_by(id: creative_id)
+      return unless creative
+
+      creative.descendants.update_all(updated_at: Time.current)
+    end
+  end
+end

data/app/models/collavre/agent_gateway.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Collavre
+  class AgentGateway < ApplicationRecord
+    self.table_name = "agent_gateways"
+
+    # Must match the proxy's USER_IDENTITY_HMAC_SECRET.
+    MIN_IDENTITY_SECRET_BYTES = 32
+    DESKTOP_NATIVE_CREDENTIAL_ATTRIBUTES = %i[admin_key completion_key identity_secret].freeze
+
+    belongs_to :owner, class_name: "Collavre::User"
+    has_many :agents, class_name: "Collavre::User", dependent: :restrict_with_error
+    has_many :agent_workspaces, class_name: "Collavre::AgentWorkspace", dependent: :destroy
+
+    enum :workspace_mode, { shared: 0, per_user: 1 }, default: :shared
+
+    encrypts :admin_key, deterministic: false
+    encrypts :completion_key, deterministic: false
+    encrypts :identity_secret, deterministic: false
+
+    normalizes :name, with: ->(value) { value.to_s.strip }
+    normalizes :base_url, with: ->(value) { value.to_s.strip.sub(%r{/+\z}, "") }
+    normalizes :tenant_id, with: ->(value) { value.to_s.strip }
+
+    validates :name, :base_url, :admin_key, :tenant_id, presence: true
+    validates :name, uniqueness: { scope: :owner_id }
+    validates :tenant_id, format: { with: /\A[A-Za-z0-9][A-Za-z0-9._:@\/-]{0,199}\z/ }
+    validate :base_url_is_http
+    validate :base_url_is_safe_for_owner
+    validate :desktop_managed_base_url_is_immutable
+    validate :desktop_managed_credentials_are_immutable
+    validate :desktop_managed_gateway_uses_shared_workspace
+    validate :identity_secret_is_usable
+    validate :completion_key_is_present_when_assigned_to_agents
+    around_update :serialize_completion_key_removal
+    before_update :validate_completion_key_removal_under_lock
+    after_update :reconcile_workspaces_after_gateway_change, if: :workspace_credentials_changed?
+
+    scope :active, -> { where(active: true) }
+
+    def chat_capable?
+      completion_key.present?
+    end
+
+    def completion_base_url
+      "#{proxy_base_url}/v1"
+    end
+
+    def proxy_path(path)
+      suffix = path.start_with?("/") ? path : "/#{path}"
+      "#{proxy_base_url}#{suffix}"
+    end
+
+    # The signed native setup handoff is the only flow permitted to retarget a
+    # desktop-managed gateway. Its loopback exception must not be reusable by
+    # an owner editing the gateway through the regular settings UI.
+    def update_from_desktop_registration!(attributes)
+      @desktop_registration_update = true
+      update!(attributes)
+    ensure
+      @desktop_registration_update = false
+    end
+
+    # Desktop-managed gateways are created only by the signed native setup
+    # handoff and always target the local proxy. They remain usable when their
+    # original owner later loses the system administrator role.
+    def desktop_loopback?
+      return false unless desktop_managed?
+
+      uri = URI.parse(base_url.to_s)
+      uri.scheme == "http" &&
+        uri.host == "127.0.0.1" &&
+        uri.port.present? &&
+        uri.userinfo.blank? &&
+        uri.query.blank? &&
+        uri.fragment.blank?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    private
+
+    def proxy_base_url
+      base_url.delete_suffix("/v1")
+    end
+
+    def base_url_is_http
+      uri = URI.parse(base_url.to_s)
+      return if uri.is_a?(URI::HTTP) && uri.host.present? && uri.userinfo.blank? && uri.query.blank? && uri.fragment.blank?
+
+      errors.add(:base_url, :invalid)
+    rescue URI::InvalidURIError
+      errors.add(:base_url, :invalid)
+    end
+
+    def base_url_is_safe_for_owner
+      return if owner&.system_admin?
+      return if desktop_loopback?
+      return if CliProxy::EndpointPolicy.new.safe_literal?(base_url)
+
+      errors.add(:base_url, :unsafe)
+    end
+
+    def desktop_managed_base_url_is_immutable
+      return unless persisted? && desktop_managed? && will_save_change_to_base_url?
+      return if @desktop_registration_update
+
+      errors.add(:base_url, :immutable)
+    end
+
+    # Keychain is the source of truth for the local proxy credentials. The
+    # regular Rails settings form cannot synchronize it, so only the signed
+    # native registration handoff may rotate these values.
+    def desktop_managed_credentials_are_immutable
+      return unless persisted? && desktop_managed?
+      return if @desktop_registration_update
+
+      DESKTOP_NATIVE_CREDENTIAL_ATTRIBUTES.each do |attribute|
+        next unless public_send("will_save_change_to_#{attribute}?")
+
+        errors.add(attribute, :immutable)
+      end
+    end
+
+    # The macOS bundle deliberately runs one shared local proxy. Per-user
+    # routing requires a worker and identity secret that desktop never starts.
+    def desktop_managed_gateway_uses_shared_workspace
+      return unless desktop_managed? && !shared?
+
+      errors.add(:workspace_mode, :desktop_shared_only)
+    end
+
+    def identity_secret_is_usable
+      if identity_secret.blank?
+        # A single-agent shared gateway may fall back to the proxy's unscoped workspace.
+        errors.add(:identity_secret, :blank) if per_user? || agents.many?
+        return
+      end
+
+      return if identity_secret.to_s.bytesize >= MIN_IDENTITY_SECRET_BYTES
+
+      errors.add(:identity_secret, :too_short, count: MIN_IDENTITY_SECRET_BYTES)
+    end
+
+    def completion_key_is_present_when_assigned_to_agents
+      return if completion_key.present? || !agents.exists?
+
+      errors.add(:completion_key, :required_for_agents)
+    end
+
+    # An agent assignment and key removal both depend on the same invariant.
+    # Re-check under the gateway row lock so two requests that validated a
+    # previously key-bearing, unassigned gateway cannot both commit.
+    def serialize_completion_key_removal
+      return yield unless will_save_change_to_completion_key? && completion_key.blank?
+
+      locked_gateway = self.class.find(id)
+      locked_gateway.with_lock do
+        begin
+          @completion_key_removal_lock = locked_gateway
+          yield
+        ensure
+          @completion_key_removal_lock = nil
+        end
+      end
+    end
+
+    def validate_completion_key_removal_under_lock
+      return unless @completion_key_removal_lock&.agents&.exists?
+
+      errors.add(:completion_key, :required_for_agents)
+      throw :abort
+    end
+
+    def workspace_credentials_changed?
+      saved_change_to_base_url? || saved_change_to_tenant_id? || saved_change_to_workspace_mode? || deactivated?
+    end
+
+    def deactivated?
+      saved_change_to_active? && !active?
+    end
+
+    def reconcile_workspaces_after_gateway_change
+      if saved_change_to_base_url? || saved_change_to_tenant_id? || deactivated?
+        agent_workspaces.destroy_all
+        return
+      end
+
+      agents.find_each do |agent|
+        workspaces = agent_workspaces.where(agent: agent)
+        next unless workspaces.exists?
+
+        workspaces.destroy_all
+        next unless active?
+
+        AgentWorkspace.resolve!(agent: agent, user: per_user? ? agent.creator : nil)
+      end
+    end
+  end
+end

data/app/models/collavre/agent_subscription.rb

@@ -3,15 +3,15 @@
 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.
+  # authority for whether Claude Channel dispatch is active: a human's
+  # concurrent sessions share one agent, so dispatch stays on while ANY session
+  # holds a live row, and 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
+  # scope so it cannot keep dispatch active, and reaped opportunistically on the next
   # subscribe/unsubscribe for the agent.
   class AgentSubscription < ApplicationRecord
     self.table_name = "agent_subscriptions"

data/app/models/collavre/agent_workspace.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Collavre
+  class AgentWorkspace < ApplicationRecord
+    self.table_name = "agent_workspaces"
+
+    belongs_to :agent, class_name: "Collavre::User"
+    belongs_to :user, class_name: "Collavre::User", optional: true
+    belongs_to :agent_gateway, class_name: "Collavre::AgentGateway"
+
+    encrypts :manifest_token, deterministic: false
+    encrypts :callback_token, deterministic: false
+
+    # Mirrors the proxy's STABLE_ID_RE: the credential axis selects the OS worker.
+    CREDENTIAL_ID_FORMAT = /\A[A-Za-z0-9][A-Za-z0-9._:@\/-]{0,199}\z/
+    # Mirrors the proxy's WORKSPACE_ID_RE. Narrower than the credential format
+    # because this value becomes one path segment below the worker's HOME, so
+    # "/" and "." must stay out of it.
+    WORKSPACE_ID_FORMAT = /\A[A-Za-z0-9][A-Za-z0-9_:@-]{0,199}\z/
+
+    validates :proxy_credential_id, :proxy_workspace_id, :manifest_token,
+              :manifest_token_digest, :callback_token, presence: true
+    validates :proxy_credential_id, format: { with: CREDENTIAL_ID_FORMAT }
+    validates :proxy_workspace_id, format: { with: WORKSPACE_ID_FORMAT }
+    validates :manifest_token_digest, uniqueness: true
+
+    before_validation :derive_manifest_token_digest, if: :will_save_change_to_manifest_token?
+    before_destroy :revoke_callback_token
+
+    class << self
+      def resolve!(agent:, user:)
+        loop do
+          gateway_id = agent.class.where(id: agent.id).pick(:agent_gateway_id)
+          raise ArgumentError, "Agent has no gateway" unless gateway_id
+
+          gateway = Collavre::AgentGateway.find(gateway_id)
+          workspace = gateway.with_lock do
+            agent.with_lock do
+              # User validation takes the gateway lock before updating the agent.
+              # Use the same lock order, then verify the association under both
+              # locks. A concurrent reassignment makes this attempt retry against
+              # the newly persisted gateway instead of creating stale credentials.
+              next unless agent.agent_gateway_id == gateway.id
+
+              raise ArgumentError, "Agent gateway is inactive" unless gateway.active?
+
+              gateway.shared? ? resolve_shared!(agent, gateway) : resolve_per_user!(agent, user, gateway)
+            end
+          end
+
+          return workspace if workspace
+        end
+      end
+
+      def find_by_manifest_token!(agent_id:, token:)
+        supplied = token.to_s
+        workspace = find_by!(agent_id: agent_id, manifest_token_digest: manifest_digest(supplied))
+        return workspace if ActiveSupport::SecurityUtils.secure_compare(supplied, workspace.manifest_token.to_s)
+
+        raise ActiveRecord::RecordNotFound
+      end
+
+      def manifest_digest(token)
+        Digest::SHA256.hexdigest(token)
+      end
+
+      # The workspace axis is always the agent: skills, workspace config, and the
+      # provisioning lockfile are per agent regardless of the gateway mode.
+      def proxy_workspace_id_for(agent)
+        "agent-#{agent.id}"
+      end
+
+      # The credential axis selects the proxy worker that holds the engine
+      # logins. A per-user gateway keys it by Collavre user so one login covers
+      # every agent that user reaches; a shared gateway keys it by agent so all
+      # of its users keep sharing the one login.
+      def proxy_credential_id_for(agent, user)
+        user ? "user-#{user.id}" : "agent-#{agent.id}"
+      end
+
+      # Nothing here reads proxy_user_id; it is written so a process still
+      # running the pre-split code can resolve rows this release creates —
+      # the previous container during a Kamal rollout, or the whole app after
+      # a rollback. Drop this together with the column in the contract
+      # migration that follows this release.
+      def legacy_proxy_user_id_for(agent, user)
+        return "agent-#{agent.id}" unless user
+
+        "agent-#{agent.id}--user-#{user.id}"
+      end
+
+      private
+
+      def resolve_shared!(agent, gateway)
+        existing = find_by(agent: agent, agent_gateway: gateway, user_id: nil)
+        return existing if identity_current?(existing, agent, nil)
+
+        existing&.destroy!
+        create_workspace!(agent: agent, user: nil, gateway: gateway)
+      rescue ActiveRecord::RecordNotUnique
+        find_by!(agent: agent, agent_gateway: gateway, user_id: nil)
+      end
+
+      def resolve_per_user!(agent, user, gateway)
+        raise ArgumentError, "A user is required for a per-user workspace" unless user
+
+        existing = find_by(agent: agent, user: user, agent_gateway: gateway)
+        return existing if identity_current?(existing, agent, user)
+
+        existing&.destroy!
+
+        if user.id == agent.created_by_id
+          find_by(agent: agent, agent_gateway: gateway, user_id: nil)&.destroy!
+        end
+
+        create_workspace!(agent: agent, user: user, gateway: gateway)
+      rescue ActiveRecord::RecordNotUnique
+        find_by!(agent: agent, user: user, agent_gateway: gateway)
+      end
+
+      # A row minted under an older identity scheme addresses a proxy workspace
+      # that no longer matches its agent/user pair, so it is replaced rather than
+      # reused — its credentials would resolve to the wrong worker or directory.
+      def identity_current?(workspace, agent, user)
+        return false unless workspace
+
+        workspace.proxy_workspace_id == proxy_workspace_id_for(agent) &&
+          workspace.proxy_credential_id == proxy_credential_id_for(agent, user)
+      end
+
+      def create_workspace!(agent:, user:, gateway:)
+        transaction do
+          callback_token = issue_callback_token!(gateway: gateway, owner: user || agent)
+
+          create!(
+            agent: agent,
+            user: user,
+            agent_gateway: gateway,
+            proxy_workspace_id: proxy_workspace_id_for(agent),
+            proxy_credential_id: proxy_credential_id_for(agent, user),
+            proxy_user_id: legacy_proxy_user_id_for(agent, user),
+            manifest_token: SecureRandom.urlsafe_base64(32),
+            callback_token: callback_token
+          )
+        end
+      end
+
+      def issue_callback_token!(gateway:, owner:)
+        application = Doorkeeper::Application.find_or_create_by!(
+          owner: gateway.owner,
+          name: "Collavre Agent Gateway",
+          redirect_uri: "urn:ietf:wg:oauth:2.0:oob"
+        ) do |app|
+          app.scopes = "public"
+          app.confidential = true
+        end
+
+        access_token = Doorkeeper::AccessToken.create!(
+          application: application,
+          resource_owner_id: owner.id,
+          scopes: "public",
+          expires_in: nil,
+          use_refresh_token: false
+        )
+        plaintext = access_token.token
+        access_token.update_column(:token, Collavre::HashedAccessTokenLookup.encode(plaintext))
+
+        plaintext
+      end
+    end
+
+    def config_payload(base_url:)
+      { url: base_url.sub(%r{/+\z}, ""), token: callback_token }
+    end
+
+    def rotate_tokens!
+      gateway = agent_gateway
+      gateway.with_lock do
+        workspace_agent = agent
+        workspace_agent.with_lock do
+          raise ActiveRecord::RecordNotFound unless workspace_agent.agent_gateway_id == gateway.id
+          raise ArgumentError, "Agent gateway is inactive" unless gateway.active?
+
+          with_lock do
+            raise ActiveRecord::RecordNotFound unless agent_gateway_id == gateway.id
+
+            old_access_token = Doorkeeper::AccessToken.by_token(callback_token)
+            new_callback_token = self.class.send(:issue_callback_token!, gateway: gateway, owner: user || workspace_agent)
+            update!(callback_token: new_callback_token)
+            old_access_token&.revoke
+          end
+        end
+      end
+
+      self
+    end
+
+    private
+
+    def derive_manifest_token_digest
+      self.manifest_token_digest = self.class.manifest_digest(manifest_token.to_s)
+    end
+
+    def revoke_callback_token
+      Doorkeeper::AccessToken.by_token(callback_token)&.revoke
+    end
+  end
+end