rails_tool_views 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f0b45e8093744ab3053cb621e1b8118ef6c618b98f907e8e88b9b16f5b36fba
-  data.tar.gz: '05959be24f98969c883260f0b06cef6815d812393bf7c250d0d1dea1cc552e7b'
+  metadata.gz: 870437bec297c23b8c6dcda437fba7d02d196bcdd1b4abcaf0df3a207e689cca
+  data.tar.gz: c4af0245f4f5d7e7e94b28b225c5da2c69e7b6205e56529e0067f481faa49c39
 SHA512:
-  metadata.gz: 57ab0c782013453cc510f47402fcdae2b934a06fe69760b45411466b543c851d7b8b84e653bcef7824f3267f97319783e712754b7c321b9bd844826645f94afe
-  data.tar.gz: 2d741cf1b44e389bb3cc7a00bcf1de0da70ef3377077950fed1c4a166d9a62d7ac3ae339550779616b2c414ed23b8612531b2d2fda01f10e462cbc40d7ba6b5b
+  metadata.gz: 50b36ef77c8eae5e3f7cf515a610bb2ded488010b031a462c8ef8e18836879b6174cea0ac3d53d7fdb07a71eebe2882f18982bb5c19906c8b90e3a815b7857b1
+  data.tar.gz: e6247b022577c845a32658d3a05f46caefc38e1bbae9bffcecb7a85726a7c30f0f731eca622ae60d94953b49cde35919712c7842037baeb65858a324b20c7293

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.4.0] - 2026-10-20
+
+- Emit the existing metadata-only `action.conflict` event when database rollback or lock contention maps to a retryable conflict.
+- Keep `action.executed` and add `replayed` metadata to distinguish exact receipt replay from handler execution.
+- Add optional bounded plain-text `Transition#notice`, rendered for the action response through JSON/Turbo or scoped HTML flash. Refresh drops it; action receipts retain exact responses. Existing persistent `state["message"]` is unchanged.
+
+- Omit raw host exception messages and stack text from handled-error log lines; preserve the original exception in host-controlled `Rails.error`. Document the metadata-only event catalog.
+
+- Fence delivery acknowledgments with the existing attempt counter. Late callbacks cannot overwrite newer attempts or emit false terminal notifications. Keep durable uncertainty and host deduplication.
+- Refuse delivery inside an open host transaction with `DELIVERY_IN_TRANSACTION`; dispatch can still join it. Add host Active Job and process-death recovery checks. No new migration or runtime dependency.
+
 ## [0.3.0] - 2026-10-19
 
 - Opt-in scoped `purge_closed` preview/apply with deadlines, bounded batches, atomic receipt cleanup and durable correlation tombstones. Host business records stay intact.

data/app/controllers/rails_tool_views/surfaces_controller.rb

@@ -85,10 +85,16 @@ module RailsToolViews
       status = response[:status] == "pending" ? 202 : 200
       respond_to do |format|
         format.json { render json: response, status: status }
-        format.turbo_stream { render turbo_stream: turbo_stream.replace(surface.dom_id, RailsToolViews.render(surface, view_context: view_context, scope: current_scope)), status: status }
+        format.turbo_stream { render turbo_stream: turbo_stream.replace(surface.dom_id, RailsToolViews.render(surface, view_context: view_context, scope: current_scope, notice: result[:notice])), status: status }
         # Without Turbo, return to the page that embeds the Surface; it re-renders saved state.
         # The Engine's own helper keeps whatever mount path and name the host chose.
-        format.html { redirect_after_action(surface) }
+        format.html do
+          if result[:notice]
+            flash[:rails_tool_views_notice] = { "surface_id" => surface.id.to_s, "actor" => current_scope.actor,
+              "tenant" => current_scope.tenant, "text" => result[:notice] }
+          end
+          redirect_after_action(surface)
+        end
       end
     end
     def redirect_after_action(surface)
@@ -106,7 +112,7 @@ module RailsToolViews
       end
     end
     def render_surface_page(surface, error: nil)
-      html = surface && RailsToolViews.render(surface, view_context: view_context, scope: current_scope, error: error)
+      html = surface && view_context.rails_tool_views_surface(surface, scope: current_scope, error: error)
       render template: "rails_tool_views/surfaces/page", layout: "rails_tool_views/application",
         locals: { surface_html: html, reload_path: surface && surface_path(surface), error: error },
         status: error ? error.status : :ok

data/app/helpers/rails_tool_views/surfaces_helper.rb

@@ -14,9 +14,11 @@ module RailsToolViews
       agent_unavailable: "AI follow-up unavailable.", agent_retry: "Retry AI follow-up"
     }.freeze
 
-    # Renders the Surface with a fresh scope and optional field feedback.
-    def rails_tool_views_surface(surface, scope:, error: nil)
-      RailsToolViews.render(surface, view_context: self, scope: scope, error: error)
+    # Renders with fresh authorization, optional field feedback and a transient
+    # notice. A matching HTML redirect's scoped flash is consumed once.
+    def rails_tool_views_surface(surface, scope:, error: nil, notice: nil)
+      notice = rails_tool_views_flash_notice(surface, scope) if notice.nil?
+      RailsToolViews.render(surface, view_context: self, scope: scope, error: error, notice: notice)
     end
 
     def rails_tool_views_text(key, **values)
@@ -78,5 +80,14 @@ module RailsToolViews
       view = respond_to?(:rails_tool_views) || respond_to?(:main_app) ? self : helpers
       view.respond_to?(:rails_tool_views) ? view.rails_tool_views : view.main_app.rails_tool_views
     end
+
+    private
+    def rails_tool_views_flash_notice(surface, scope) # :nodoc:
+      return unless scope.is_a?(RailsToolViews::Scope) && respond_to?(:flash)
+      stored = flash[:rails_tool_views_notice]
+      return unless stored.is_a?(Hash) && stored.values_at("surface_id", "actor", "tenant") == [surface.id.to_s, scope.actor, scope.tenant]
+      flash.delete(:rails_tool_views_notice)
+      stored["text"]
+    end
   end
 end

data/app/views/rails_tool_views/surfaces/_surface.html.erb

@@ -4,7 +4,7 @@
     <p id="<%= surface.dom_id %>_error" role="alert" tabindex="-1" data-rails-tool-views-target="error"><%= error.message %></p>
   <% end %>
   <p id="<%= surface.dom_id %>_status" role="status" aria-live="polite" tabindex="-1" data-rails-tool-views-target="status">
-    <%= surface.state["message"].is_a?(String) ? surface.state["message"] : rails_tool_views_text(surface.revision > 1 ? :saved : :ready) %>
+    <%= notice || (surface.state["message"].is_a?(String) ? surface.state["message"] : rails_tool_views_text(surface.revision > 1 ? :saved : :ready)) %>
   </p>
   <% interaction = surface.agent_interactions.order(:id).last %>
   <% if interaction && interaction.status != "skipped" %>

data/lib/rails_tool_views/core.rb

@@ -16,6 +16,7 @@ module RailsToolViews
       "SURFACE_CLOSED" => "This view is closed. Its saved actions cannot be changed.",
       "SURFACE_PURGED" => "This view has been cleaned up and cannot be restored.",
       "LIFECYCLE_BUSY" => "This view has unfinished or uncertain delivery. Resolve it before closing.",
+      "DELIVERY_IN_TRANSACTION" => "Deliver the follow-up after the host transaction commits.",
       "INVALID_RETENTION_REQUEST" => "Choose an explicit past cutoff and a batch size from 1 to 1000.",
       "INVALID_RETENTION_WINDOW" => "Choose a future retention deadline or keep this view indefinitely.",
       "VALIDATION_FAILED" => "Check the highlighted fields and try again.",
@@ -183,8 +184,9 @@ module RailsToolViews
 
   # Policy and handler context populated by the runtime.
   Access = Struct.new(:actor, :tenant, :operation, :props, :surface, :action, :arguments, :context_ref, keyword_init: true)
-  # Handler result containing the next UI state and an optional agent flag.
-  Transition = Struct.new(:state, :agent, keyword_init: true)
+  # Handler result containing persistent UI state, an optional agent flag and
+  # plain-text notice (at most 500 bytes) displayed for this action response.
+  Transition = Struct.new(:state, :agent, :notice, keyword_init: true)
   Action = Struct.new(:key, :schema, :policy, :handler, keyword_init: true)
 
   # An immutable renderer, schema, version, and authorization contract.

data/lib/rails_tool_views/runtime.rb

@@ -62,6 +62,7 @@ module RailsToolViews
       idempotency_key = Data.identifier(idempotency_key, code: "INVALID_IDEMPOTENCY_KEY")
       request_digest = Data.digest(action: definition.key, arguments: arguments, base_revision: base_revision)
       result = nil
+      replayed = false
       surface.with_lock do
         ensure_not_purged!(surface)
         compatible_component!(surface).authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
@@ -74,6 +75,7 @@ module RailsToolViews
           # exact key, and keep the digest check as the second gate.
           raise Error.new("IDEMPOTENCY_CONFLICT", status: 409) unless prior.idempotency_key == idempotency_key && prior.request_digest == request_digest
           result = prior.result.symbolize_keys
+          replayed = true
           next
         end
         raise Error.new("SURFACE_CLOSED", status: 410) if surface.closed?
@@ -84,8 +86,10 @@ module RailsToolViews
         transition = definition.handler.call(request)
         raise Error.new("INVALID_TRANSITION", status: 422) unless transition.is_a?(Transition) && transition.state.is_a?(Hash)
         state = Data.bounded(transition.state)
+        notice = normalize_notice(transition.notice)
         surface.update!(state: state, revision: base_revision + 1)
         result = { status: "completed", surface_id: surface.id, revision: surface.revision }
+        result[:notice] = notice unless notice.nil?
         execution = ActionExecution.create!(surface: surface, actor_ref: scope.actor, action_key: definition.key,
           base_revision: base_revision, idempotency_key: idempotency_key, request_digest: request_digest, result: result)
         if transition.agent
@@ -96,14 +100,14 @@ module RailsToolViews
           execution.update!(result: result)
         end
       end
-      notify("action.executed", surface_id: surface.id, revision: result[:revision], action: definition.key)
+      notify("action.executed", surface_id: surface.id, revision: result[:revision], action: definition.key, replayed: replayed)
       result
     rescue ActiveRecord::StaleObjectError, ActiveRecord::TransactionRollbackError, ActiveRecord::LockWaitTimeout
       # The database rolled the whole action back (deadlock, serialization failure,
       # lock timeout); retrying with the same key is safe.
-      raise Error.new("CONFLICT", status: 409)
+      raise_action_conflict!
     rescue ActiveRecord::StatementInvalid => error
-      raise Error.new("CONFLICT", status: 409) if error.cause.class.name.include?("Busy") || error.cause.class.name.include?("Locked")
+      raise_action_conflict! if error.cause.class.name.include?("Busy") || error.cause.class.name.include?("Locked")
       raise
     rescue Error => error
       notify(error.code == "CONFLICT" ? "action.conflict" : "action.rejected", code: error.code)
@@ -113,7 +117,9 @@ module RailsToolViews
     # The adapter must deduplicate by delivery_key. A crash after remote acceptance
     # can leave a lease in delivering state; retry is explicit and keeps the key.
     # Delivers a saved interaction after authorization; retry_failed explicitly retries failed delivery.
+    # Call only after the host transaction commits. Stale attempts cannot acknowledge a newer claim.
     def deliver(id, scope:, adapter: configuration.agent_adapter, retry_failed: false)
+      raise Error.new("DELIVERY_IN_TRANSACTION", status: 409) if AgentInteraction.connection.transaction_open?
       interaction = AgentInteraction.find_by(id: id)
       raise Error.new("NOT_FOUND", status: 404) unless interaction
       surface = restore(interaction.surface_id, scope: scope)
@@ -148,23 +154,32 @@ module RailsToolViews
         end
       end
       return interaction.reload unless claimed
+      attempt = interaction.attempts
+      failure = nil
       begin
         adapter.call(Data.freeze_deep(Data.normalize(interaction.payload)), delivery_key: interaction.delivery_key)
-        interaction.update!(status: "completed", claimed_at: nil)
-        notify("agent_returned", surface_id: interaction.surface_id, interaction_id: interaction.id)
       rescue StandardError => error
-        interaction.update!(status: "failed", error_code: "AGENT_UNAVAILABLE", claimed_at: nil)
-        report(error, "agent_failed", surface_id: interaction.surface_id, interaction_id: interaction.id)
+        failure = error
+      end
+      # Compare-and-set fences both success and failure. The lease may expire
+      # while the callback runs; its acknowledgment belongs only to its attempt.
+      acknowledged = AgentInteraction.where(id: interaction.id, status: "delivering", attempts: attempt).update_all(
+        status: failure ? "failed" : "completed", error_code: failure ? "AGENT_UNAVAILABLE" : nil,
+        claimed_at: nil, updated_at: Time.current)
+      if acknowledged == 1
+        metadata = { surface_id: interaction.surface_id, interaction_id: interaction.id }
+        failure ? report(failure, "agent_failed", **metadata) : notify("agent_returned", **metadata)
       end
       interaction.reload
     end
 
-    # Renders the trusted component after a fresh restore and authorization check.
-    def render(surface, view_context:, scope:, error: nil)
+    # Renders the trusted component after fresh authorization. Optional notice
+    # is plain-text response feedback; it never changes the Surface snapshot.
+    def render(surface, view_context:, scope:, error: nil, notice: nil)
       # Never trust an already-loaded object as an authorization decision.
       surface = restore(surface.id, scope: scope)
       component = compatible_component!(surface)
-      view_context.render(partial: "rails_tool_views/surfaces/surface", formats: [:html], locals: { surface: surface, definition: component, error: error })
+      view_context.render(partial: "rails_tool_views/surfaces/surface", formats: [:html], locals: { surface: surface, definition: component, error: error, notice: normalize_notice(notice) })
     rescue Error => failure
       view_context.render(partial: "rails_tool_views/surfaces/error", formats: [:html], locals: { error: failure })
     end
@@ -199,10 +214,20 @@ module RailsToolViews
     def report(error, event, **payload) # :nodoc:
       notify(event, **payload, error_class: error.class.name)
       Rails.error.report(error, handled: true, severity: :error, context: payload, source: "rails_tool_views")
-      Rails.logger&.error("RailsToolViews #{event} handled #{error.class} (#{error.message}) - #{error.backtrace&.first}")
+      Rails.logger&.error("RailsToolViews #{event} handled #{error.class}; inspect the host Rails.error report")
     end
 
     private
+    def raise_action_conflict! # :nodoc:
+      notify("action.conflict", code: "CONFLICT")
+      raise Error.new("CONFLICT", status: 409)
+    end
+    def normalize_notice(notice) # :nodoc:
+      return if notice.nil?
+      raise Error.new("INVALID_TRANSITION", status: 422) unless notice.is_a?(String) && notice.bytesize <= 500
+      # A host SafeBuffer must still be rendered as escaped text.
+      Data.bounded(String.new(notice))
+    end
     def ensure_not_purged!(surface)
       raise Error.new("SURFACE_PURGED", status: 410) if surface.purged?
     end

data/lib/rails_tool_views/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module RailsToolViews
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_tool_views
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails