anima-core 1.1.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 583896eaa09036e71d6e6b6ee013a021965acc193340ba735e4c0a0a6be6e6dc
-  data.tar.gz: f1f173f5129c37785a01119daa3cce27a0b935e0fdac256ffb0b412aad87483c
+  metadata.gz: f8a12f6624492adc6c4de4e5fbc5e28df74edf73a568b73fc0819a8d3fc45163
+  data.tar.gz: 84f3c8680deb81a5e4989abd7b9eeafaae9bdc8e5b0a04db6af27c615f31144c
 SHA512:
-  metadata.gz: 312effa8e79b480bd33a78093f192d6a6997fc0430aac6fe09528da0c95461feade771b3ecbcd13c0b7ad036d8a1c4cd2e6a443da61332baf3a8b34c57626ca5
-  data.tar.gz: 7c3578adb7158f0c32caa7f26ec3ea4d8189502e0bab27b0070f7a98a6423c6d311ddcd429edb7d451dadecd4282b5c7e874b6ce302fccdd1337103034eee1d2
+  metadata.gz: ae5c8c7ba47910544c6bb3b316bed1a90a54929cae275983c8dd36fca91cdceebbd06cd50b6a1e512d1142e38ab8ebc414b635dd0ed0ff67eea74c5e0af86d86
+  data.tar.gz: 8d8c6ddf84970520c805da2b2fb98d6b2c47faad068f5e602e89389bcc7e70bd206a0ed35dc7dc94aeef2bb8cea615e57627fcf883937d23ad2f70f5610bd6e2

data/.reek.yml

@@ -37,6 +37,8 @@ detectors:
       - "Tools::SpawnSpecialist#execute"
       # Nickname assignment operates on child session and parent's children — inherent.
       - "Tools::SubagentPrompts#assign_nickname_via_brain"
+      # Goal tools operate on goal objects — inherent to the pattern.
+      - "AnalyticalBrain::Tools::UpdateGoal#execute"
       # Validation methods naturally reference the validated value more than self.
       - "AnalyticalBrain::Tools::AssignNickname#validate"
       # Tool execute methods naturally reference input hash and shell result hash.

data/agents/codebase-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-analyzer
-description: Analyzes codebase implementation details with precise file:line references. Call when you need to understand how specific code works.
+description: Traces data flow and explains how code works. Returns file:line references.
 tools: read, bash
 ---
 

data/agents/codebase-pattern-finder.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-pattern-finder
-description: Finds similar implementations, usage examples, and existing patterns that can be modeled after. Returns concrete code examples.
+description: Finds similar implementations, usage examples, and existing patterns to model after. Returns concrete code examples.
 tools: read, bash
 ---
 

data/agents/documentation-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: documentation-researcher
-description: Fetches library and framework documentation from the web. Provides setup guides, API usage examples, and implementation patterns tailored to your use case.
+description: Fetches official docs. Returns ready-to-use code examples.
 tools: web_get, read
 color: cyan
 ---

data/agents/thoughts-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: thoughts-analyzer
-description: Extracts decisions and actionable insights from project history in thoughts/. Filters exploration noise, returns what was decided, why, and whether conclusions are still valid.
+description: "thoughts/ holds design decisions, architecture notes, and implementation rationale. Answers WHY things work the way they do and how they should work by design."
 tools: read, bash
 ---
 

data/agents/web-search-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: web-search-researcher
-description: Deep web research specialist. Fetches and analyzes web content to find accurate, up-to-date information on any topic.
+description: Researches topics across multiple web sources. Use when a single page won't answer the question.
 tools: web_get, bash, read
 color: yellow
 ---

data/app/channels/session_channel.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Streams events for a specific session to connected clients.
-# Part of the Brain/TUI separation: the Brain broadcasts events through
+# Streams messages for a specific session to connected clients.
+# Part of the Brain/TUI separation: the Brain broadcasts messages through
 # this channel, and any number of clients (TUI, web, API) can subscribe.
 #
 # On subscription, sends the session's chat history so the client can
@@ -42,10 +42,10 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, data)
   end
 
-  # Processes user input. For idle sessions, persists the event immediately
-  # so the message appears in the TUI without waiting for the background
-  # job, then schedules {AgentRequestJob} for LLM delivery. If delivery
-  # fails, the job deletes the event and emits a {Events::BounceBack}.
+  # Processes user input. For idle sessions, persists the message immediately
+  # so it appears in the TUI without waiting for the background job, then
+  # schedules {AgentRequestJob} for LLM delivery. If delivery fails, the
+  # job deletes the message and emits a {Events::BounceBack}.
   #
   # For busy sessions, emits a pending {Events::UserMessage} that queues
   # until the current agent loop completes.
@@ -63,23 +63,23 @@ class SessionChannel < ApplicationCable::Channel
   end
 
   # Recalls the most recent pending message for editing. Deletes the
-  # pending event and broadcasts the recall so all clients remove it.
+  # pending message and broadcasts the recall so all clients remove it.
   #
-  # @param data [Hash] must include "event_id" (positive integer)
+  # @param data [Hash] must include "message_id" (positive integer)
   def recall_pending(data)
-    event_id = data["event_id"].to_i
-    return if event_id <= 0
+    message_id = data["message_id"].to_i
+    return if message_id <= 0
 
-    event = Event.find_by(
-      id: event_id,
+    message = Message.find_by(
+      id: message_id,
       session_id: @current_session_id,
-      event_type: "user_message",
-      status: Event::PENDING_STATUS
+      message_type: "user_message",
+      status: Message::PENDING_STATUS
     )
-    return unless event
+    return unless message
 
-    event.destroy!
-    ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "event_id" => event_id})
+    message.destroy!
+    ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "message_id" => message_id})
   end
 
   # Requests interruption of the current tool execution. Sets a flag on the
@@ -106,7 +106,7 @@ class SessionChannel < ApplicationCable::Channel
     limit = (data["limit"] || DEFAULT_LIST_LIMIT).to_i.clamp(1, MAX_LIST_LIMIT)
     sessions = Session.root_sessions.recent(limit).includes(:child_sessions)
     all_ids = sessions.flat_map { |session| [session.id] + session.child_sessions.map(&:id) }
-    counts = Event.where(session_id: all_ids).llm_messages.group(:session_id).count
+    counts = Message.where(session_id: all_ids).llm_messages.group(:session_id).count
 
     result = sessions.map { |session| serialize_session_with_children(session, counts) }
     transmit({"action" => "sessions_list", "sessions" => result})
@@ -196,7 +196,7 @@ class SessionChannel < ApplicationCable::Channel
   # Used on initial subscription and after session switches so the
   # client can handle both paths with a single code path.
   #
-  # Payload: session_id, name, parent_session_id, message_count,
+  # Payload: session_id, name, agent_name, parent_session_id, message_count,
   # view_mode, active_skills, goals, children (when present).
   #
   # @param session [Session] the session to announce
@@ -206,8 +206,9 @@ class SessionChannel < ApplicationCable::Channel
       "action" => "session_changed",
       "session_id" => session.id,
       "name" => session.name,
+      "agent_name" => Anima::Settings.agent_name,
       "parent_session_id" => session.parent_session_id,
-      "message_count" => session.events.llm_messages.count,
+      "message_count" => session.messages.llm_messages.count,
       "view_mode" => session.view_mode,
       "active_skills" => session.active_skills,
       "active_workflow" => session.active_workflow,
@@ -244,22 +245,22 @@ class SessionChannel < ApplicationCable::Channel
     transmit({"action" => "view_mode", "view_mode" => session.view_mode})
   end
 
-  # Sends decorated context events (messages + tool interactions) from
-  # the LLM's viewport to the subscribing client. Each event is wrapped
-  # in an {EventDecorator} and the pre-rendered output is included in
-  # the transmitted payload. Tool events are included so the TUI can
+  # Sends decorated context messages (conversation + tool interactions) from
+  # the LLM's viewport to the subscribing client. Each message is wrapped
+  # in a {MessageDecorator} and the pre-rendered output is included in
+  # the transmitted payload. Tool messages are included so the TUI can
   # reconstruct tool call counters on reconnect.
   # In debug mode, prepends the assembled system prompt as a special block.
   #
-  # Snapshots the viewport so subsequent event broadcasts can compute
+  # Snapshots the viewport so subsequent message broadcasts can compute
   # eviction diffs accurately.
   #
   # @param session [Session] the session whose history to transmit
   def transmit_history(session)
     transmit_system_prompt(session) if session.view_mode == "debug"
 
-    each_viewport_event(session) do |event, payload|
-      transmit(payload)
+    each_viewport_message(session) do |_msg, msg_payload|
+      transmit(msg_payload)
     end
   end
 
@@ -267,7 +268,7 @@ class SessionChannel < ApplicationCable::Channel
   # Used after a view mode change to refresh all connected clients.
   # In debug mode, prepends the assembled system prompt as a special block.
   #
-  # Snapshots the viewport so subsequent event broadcasts can compute
+  # Snapshots the viewport so subsequent message broadcasts can compute
   # eviction diffs accurately.
   #
   # @param session [Session] the session whose viewport to broadcast
@@ -275,40 +276,40 @@ class SessionChannel < ApplicationCable::Channel
   def broadcast_viewport(session)
     broadcast_system_prompt(session) if session.view_mode == "debug"
 
-    each_viewport_event(session) do |event, payload|
-      ActionCable.server.broadcast(stream_name, payload)
+    each_viewport_message(session) do |_msg, msg_payload|
+      ActionCable.server.broadcast(stream_name, msg_payload)
     end
   end
 
   # Loads the viewport, snapshots it for eviction tracking, and yields
-  # each event with its decorated payload. Snapshot uses snapshot_viewport!
+  # each message with its decorated payload. Snapshot uses snapshot_viewport!
   # (not recalculate_viewport!) because full viewport refreshes don't need
   # eviction diffs — clients clear their store before rendering.
   #
   # @param session [Session] the session whose viewport to iterate
-  # @yieldparam event [Event] the persisted event record
+  # @yieldparam message [Message] the persisted message record
   # @yieldparam payload [Hash] decorated payload ready for transmission
   # @return [void]
-  def each_viewport_event(session)
-    viewport = session.viewport_events
+  def each_viewport_message(session)
+    viewport = session.viewport_messages
     session.snapshot_viewport!(viewport.map(&:id))
 
-    viewport.each do |event|
-      yield event, decorate_event_payload(event, session.view_mode)
+    viewport.each do |msg|
+      yield msg, decorate_message_payload(msg, session.view_mode)
     end
   end
 
-  # Decorates an event for transmission to clients. Merges the event's
+  # Decorates a message for transmission to clients. Merges the message's
   # database ID and structured decorator output into the payload.
   # Used by {#transmit_history} and {#broadcast_viewport} for historical
-  # and viewport re-broadcast — live broadcasts use {Event::Broadcasting}.
+  # and viewport re-broadcast — live broadcasts use {Message::Broadcasting}.
   #
-  # @param event [Event] persisted event record
+  # @param message [Message] persisted message record
   # @param mode [String] view mode for decoration (default: "basic")
   # @return [Hash] payload with "id" and optional "rendered" key
-  def decorate_event_payload(event, mode = "basic")
-    payload = event.payload.merge("id" => event.id)
-    decorator = EventDecorator.for(event)
+  def decorate_message_payload(message, mode = "basic")
+    payload = message.payload.merge("id" => message.id)
+    decorator = MessageDecorator.for(message)
     return payload unless decorator
 
     payload.merge("rendered" => {mode => decorator.render(mode)})
@@ -343,7 +344,7 @@ class SessionChannel < ApplicationCable::Channel
     prompt = session.system_prompt
     return unless prompt
 
-    tokens = [(prompt.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+    tokens = [(prompt.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
     {
       "type" => "system_prompt",
       "rendered" => {

data/app/decorators/agent_message_decorator.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-# Decorates agent_message events for display in the TUI.
+# Decorates agent_message records for display in the TUI.
 # Basic mode returns role and content. Verbose mode adds a timestamp.
 # Debug mode adds token count (exact when counted, estimated when not).
-class AgentMessageDecorator < EventDecorator
+class AgentMessageDecorator < MessageDecorator
   # @return [Hash] structured agent message data
   #   `{role: :assistant, content: String}`
   def render_basic

data/app/decorators/{event_decorator.rb → message_decorator.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Base decorator for {Event} records, providing multi-resolution rendering
-# for the TUI and analytical brain. Each event type has a dedicated subclass
+# Base decorator for {Message} records, providing multi-resolution rendering
+# for the TUI and analytical brain. Each message type has a dedicated subclass
 # that implements rendering methods for each view mode:
 #
 # - **basic** / **verbose** / **debug** — TUI display modes returning structured hashes
@@ -13,23 +13,23 @@
 # and formats it for display.
 #
 # Brain mode returns condensed single-line strings for the analytical brain's
-# event transcript. Returns nil to exclude an event from the brain's view.
+# message transcript. Returns nil to exclude a message from the brain's view.
 #
 # Subclasses must override {#render_basic}. Verbose, debug, and brain modes
 # delegate to basic until subclasses provide their own implementations.
 #
-# @example Decorate an Event AR model
-#   decorator = EventDecorator.for(event)
+# @example Decorate a Message AR model
+#   decorator = MessageDecorator.for(message)
 #   decorator.render_basic  #=> {role: :user, content: "hello"} or nil
 #
 # @example Render for a specific view mode
-#   decorator = EventDecorator.for(event)
+#   decorator = MessageDecorator.for(message)
 #   decorator.render("verbose")  #=> {role: :user, content: "hello", timestamp: 1709312325000000000}
 #
 # @example Decorate a raw payload hash (from EventBus)
-#   decorator = EventDecorator.for(type: "user_message", content: "hello")
+#   decorator = MessageDecorator.for(type: "user_message", content: "hello")
 #   decorator.render_basic  #=> {role: :user, content: "hello"}
-class EventDecorator < ApplicationDecorator
+class MessageDecorator < ApplicationDecorator
   delegate_all
 
   TOOL_ICON = "\u{1F527}"
@@ -46,36 +46,36 @@ class EventDecorator < ApplicationDecorator
   }.freeze
   private_constant :DECORATOR_MAP
 
-  # Normalizes hash payloads into an Event-like interface so decorators
-  # can use {#payload}, {#event_type}, etc. uniformly on both AR models
+  # Normalizes hash payloads into a Message-like interface so decorators
+  # can use {#payload}, {#message_type}, etc. uniformly on both AR models
   # and raw EventBus hashes.
   #
-  # @!attribute event_type [r] the event's type (e.g. "user_message")
-  # @!attribute payload [r] string-keyed hash of event data
+  # @!attribute message_type [r] the message's type (e.g. "user_message")
+  # @!attribute payload [r] string-keyed hash of message data
   # @!attribute timestamp [r] nanosecond-precision timestamp
   # @!attribute token_count [r] cumulative token count
-  EventPayload = Struct.new(:event_type, :payload, :timestamp, :token_count, keyword_init: true) do
-    # Heuristic token estimate matching {Event#estimate_tokens} so decorators
+  MessagePayload = Struct.new(:message_type, :payload, :timestamp, :token_count, keyword_init: true) do
+    # Heuristic token estimate matching {Message#estimate_tokens} so decorators
     # can call it uniformly on both AR models and hash payloads.
     # @return [Integer] at least 1
     def estimate_tokens
-      text = if event_type.to_s.in?(%w[tool_call tool_response])
+      text = if message_type.to_s.in?(%w[tool_call tool_response])
         payload.to_json
       else
         payload&.dig("content").to_s
       end
-      [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+      [(text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
     end
   end
 
-  # Factory returning the appropriate subclass decorator for the given event.
-  # Hashes are normalized via {EventPayload} to provide a uniform interface.
+  # Factory returning the appropriate subclass decorator for the given message.
+  # Hashes are normalized via {MessagePayload} to provide a uniform interface.
   #
-  # @param event [Event, Hash] an Event AR model or a raw payload hash
-  # @return [EventDecorator, nil] decorated event, or nil for unknown types
-  def self.for(event)
-    source = wrap_source(event)
-    klass_name = DECORATOR_MAP[source.event_type]
+  # @param message [Message, Hash] a Message AR model or a raw payload hash
+  # @return [MessageDecorator, nil] decorated message, or nil for unknown types
+  def self.for(message)
+    source = wrap_source(message)
+    klass_name = DECORATOR_MAP[source.message_type]
     return nil unless klass_name
 
     klass_name.constantize.new(source)
@@ -92,8 +92,8 @@ class EventDecorator < ApplicationDecorator
   # Dispatches to the render method for the given view mode.
   #
   # @param mode [String] one of "basic", "verbose", "debug", "brain"
-  # @return [Hash, String, nil] structured event data (basic/verbose/debug),
-  #   plain string (brain), or nil to hide the event
+  # @return [Hash, String, nil] structured message data (basic/verbose/debug),
+  #   plain string (brain), or nil to hide the message
   # @raise [ArgumentError] if the mode is not a valid view mode
   def render(mode)
     method = RENDER_DISPATCH[mode]
@@ -102,29 +102,29 @@ class EventDecorator < ApplicationDecorator
     public_send(method)
   end
 
-  # @abstract Subclasses must implement to render the event for basic view mode.
-  # @return [Hash, nil] structured event data, or nil to hide the event
+  # @abstract Subclasses must implement to render the message for basic view mode.
+  # @return [Hash, nil] structured message data, or nil to hide the message
   def render_basic
     raise NotImplementedError, "#{self.class} must implement #render_basic"
   end
 
   # Verbose view mode with timestamps and tool details.
   # Delegates to {#render_basic} until subclasses provide their own implementations.
-  # @return [Hash, nil] structured event data, or nil to hide the event
+  # @return [Hash, nil] structured message data, or nil to hide the message
   def render_verbose
     render_basic
   end
 
   # Debug view mode with token counts and system prompts.
   # Delegates to {#render_basic} until subclasses provide their own implementations.
-  # @return [Hash, nil] structured event data, or nil to hide the event
+  # @return [Hash, nil] structured message data, or nil to hide the message
   def render_debug
     render_basic
   end
 
   # Analytical brain view — condensed single-line string for the brain's
-  # event transcript. Returns nil to exclude from the brain's context.
-  # Subclasses override to provide event-type-specific formatting.
+  # message transcript. Returns nil to exclude from the brain's context.
+  # Subclasses override to provide message-type-specific formatting.
   # @return [String, nil] formatted transcript line, or nil to skip
   def render_brain
     nil
@@ -132,7 +132,7 @@ class EventDecorator < ApplicationDecorator
 
   private
 
-  # Token count for display: exact count from {CountEventTokensJob} when
+  # Token count for display: exact count from {CountMessageTokensJob} when
   # available, heuristic estimate otherwise. Estimated counts are flagged
   # so the TUI can prefix them with a tilde.
   #
@@ -147,14 +147,14 @@ class EventDecorator < ApplicationDecorator
   end
 
   # Delegates to the underlying object's heuristic token estimator.
-  # Both {Event} AR models and {EventPayload} structs implement this.
+  # Both {Message} AR models and {MessagePayload} structs implement this.
   #
   # @return [Integer] at least 1
   def estimate_token_count
     object.estimate_tokens
   end
 
-  # Extracts display content from the event payload.
+  # Extracts display content from the message payload.
   # @return [String, nil]
   def content
     payload["content"]
@@ -190,14 +190,14 @@ class EventDecorator < ApplicationDecorator
   end
 
   # Normalizes input to something Draper can wrap.
-  # Event AR models pass through; hashes become EventPayload structs
+  # Message AR models pass through; hashes become MessagePayload structs
   # with string-normalized keys.
-  def self.wrap_source(event)
-    return event unless event.is_a?(Hash)
+  def self.wrap_source(message)
+    return message unless message.is_a?(Hash)
 
-    normalized = event.transform_keys(&:to_s)
-    EventPayload.new(
-      event_type: normalized["type"].to_s,
+    normalized = message.transform_keys(&:to_s)
+    MessagePayload.new(
+      message_type: normalized["type"].to_s,
       payload: normalized,
       timestamp: normalized["timestamp"],
       token_count: normalized["token_count"]&.to_i || 0

data/app/decorators/system_message_decorator.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-# Decorates system_message events for display in the TUI.
+# Decorates system_message records for display in the TUI.
 # Hidden in basic mode. Verbose and debug modes return timestamped system info.
-class SystemMessageDecorator < EventDecorator
+class SystemMessageDecorator < MessageDecorator
   # @return [nil] system messages are hidden in basic mode
   def render_basic
     nil

data/app/decorators/tool_call_decorator.rb

@@ -2,7 +2,7 @@
 
 require "toon"
 
-# Decorates tool_call events for display in the TUI.
+# Decorates tool_call records for display in the TUI.
 # Hidden in basic mode — tool activity is represented by the
 # aggregated tool counter instead. Verbose mode returns tool name
 # and a formatted preview of the input arguments. Debug mode shows
@@ -12,7 +12,7 @@ require "toon"
 # Think tool calls are special: "aloud" thoughts are shown in all
 # view modes (with a thought bubble), while "inner" thoughts are
 # visible only in verbose and debug modes.
-class ToolCallDecorator < EventDecorator
+class ToolCallDecorator < MessageDecorator
   THINK_TOOL = "think"
 
   # In basic mode, only "aloud" think calls are visible.

data/app/decorators/tool_decorator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Base class for server-side tool response decoration. Transforms raw tool
-# results into LLM-optimized formats before they enter the event stream.
+# results into LLM-optimized formats before they enter the message stream.
 #
-# This is a separate decorator type from {EventDecorator}: EventDecorator
-# formats events for clients (TUI/web), while ToolDecorator formats tool
+# This is a separate decorator type from {MessageDecorator}: MessageDecorator
+# formats messages for clients (TUI/web), while ToolDecorator formats tool
 # responses for the LLM. They sit at different points in the pipeline:
 #
-#   Tool executes → ToolDecorator transforms → event stream → EventDecorator renders
+#   Tool executes → ToolDecorator transforms → message stream → MessageDecorator renders
 #
 # Subclasses implement {#call} to transform a tool's raw result into an
 # LLM-friendly string. Each tool can have its own ToolDecorator subclass

data/app/decorators/tool_response_decorator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Decorates tool_response events for display in the TUI.
+# Decorates tool_response records for display in the TUI.
 # Hidden in basic mode — tool activity is represented by the
 # aggregated tool counter instead. Verbose mode returns truncated
 # output with a success/failure indicator and tool name for per-tool
@@ -9,7 +9,7 @@
 #
 # Think tool responses ("OK") are hidden in basic and verbose modes
 # because the value is in the tool_call (the thoughts), not the response.
-class ToolResponseDecorator < EventDecorator
+class ToolResponseDecorator < MessageDecorator
   THINK_TOOL = "think"
 
   # @return [nil] tool responses are hidden in basic mode

data/app/decorators/user_message_decorator.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-# Decorates user_message events for display in the TUI.
+# Decorates user_message records for display in the TUI.
 # Basic mode returns role and content. Verbose mode adds a timestamp.
 # Debug mode adds token count (exact when counted, estimated when not).
 # Pending messages include `status: "pending"` so the TUI renders them
 # with a visual indicator (dimmed, clock icon).
-class UserMessageDecorator < EventDecorator
+class UserMessageDecorator < MessageDecorator
   # @return [Hash] structured user message data
   #   `{role: :user, content: String}` or with `status: "pending"` when queued
   def render_basic
@@ -36,6 +36,6 @@ class UserMessageDecorator < EventDecorator
 
   # @return [Boolean] true when this message is queued but not yet sent to LLM
   def pending?
-    payload["status"] == Event::PENDING_STATUS
+    payload["status"] == Message::PENDING_STATUS
   end
 end

data/app/decorators/web_get_tool_decorator.rb

@@ -19,9 +19,14 @@ require "toon"
 #   decorator.call(body: "<h1>Hi</h1>", content_type: "text/html")
 #   #=> "[Converted: HTML → Markdown]\n\n# Hi"
 class WebGetToolDecorator < ToolDecorator
-  # HTML elements that carry no useful content for an LLM.
-  NOISE_TAGS = %w[script style nav footer aside form noscript iframe
-    svg header menu menuitem].freeze
+  # Tags that never contain readable content — always removed.
+  RENDER_TAGS = %w[script style noscript iframe svg].freeze
+
+  # Structural elements stripped only when no semantic content container is found.
+  STRUCTURAL_TAGS = %w[nav footer aside form header menu menuitem].freeze
+
+  # Semantic HTML5 containers in preference order (first match wins).
+  CONTENT_SELECTORS = ["main", "article", "[role='main']"].freeze
 
   # @param result [Hash] `{body: String, content_type: String}`
   # @return [String] LLM-optimized content with conversion metadata tag
@@ -57,14 +62,19 @@ class WebGetToolDecorator < ToolDecorator
     {text: body, meta: nil}
   end
 
-  # Strips noise elements (scripts, styles, nav, ads) and converts
-  # semantic HTML to Markdown for clean LLM consumption.
+  # Strips noise elements and converts semantic HTML to Markdown.
+  # Warns when the extracted content is suspiciously short.
   #
   # @param body [String] HTML response body
   # @return [Hash] `{text: String, meta: String}`
   def text_html(body)
     markdown = html_to_markdown(body)
-    {text: markdown, meta: "[Converted: HTML → Markdown]"}
+    meta = "[Converted: HTML → Markdown]"
+    char_count = markdown.length
+    if !body.empty? && char_count < Anima::Settings.min_web_content_chars
+      meta += " [Warning: only #{char_count} chars extracted — content may be incomplete]"
+    end
+    {text: markdown, meta: meta}
   end
 
   # Passthrough for unregistered content types.
@@ -80,18 +90,40 @@ class WebGetToolDecorator < ToolDecorator
 
   private
 
-  # Strips noise HTML elements then converts to Markdown.
+  # Converts HTML to Markdown using content-aware extraction.
+  #
+  # Prefers semantic containers (+<main>+, +<article>+, +[role="main"]+)
+  # when available. Falls back to stripping structural noise from the
+  # +<body>+. Rendering artifacts (scripts, styles, iframes, SVGs) are
+  # always removed.
   #
   # @param html [String] raw HTML
   # @return [String] clean Markdown
   def html_to_markdown(html)
     doc = Nokogiri::HTML(html)
-    doc.css(NOISE_TAGS.join(", ")).remove
-    clean_html = doc.at("body")&.inner_html || doc.to_html
+    doc.css(RENDER_TAGS.join(", ")).remove
+
+    clean_html = extract_content(doc)
     markdown = ReverseMarkdown.convert(clean_html, unknown_tags: :bypass, github_flavored: true)
     collapse_whitespace(markdown)
   end
 
+  # Extracts the primary content from a parsed HTML document.
+  #
+  # Prefers semantic containers ({CONTENT_SELECTORS}) and returns the first
+  # match. When none exist, strips {STRUCTURAL_TAGS} from the +<body>+ and
+  # returns what remains.
+  #
+  # @param doc [Nokogiri::HTML::Document]
+  # @return [String] inner HTML of the best content node
+  def extract_content(doc)
+    content = CONTENT_SELECTORS.lazy.filter_map { |sel| doc.at_css(sel) }.first
+    return content.inner_html if content
+
+    doc.css(STRUCTURAL_TAGS.join(", ")).remove
+    doc.at("body")&.inner_html || doc.to_html
+  end
+
   # Collapses excessive blank lines down to a single blank line.
   #
   # @param text [String]