anima-core 1.3.0 → 1.5.0

data/agents/thoughts-analyzer.md

@@ -4,7 +4,15 @@ description: "thoughts/ holds design decisions, architecture notes, and implemen
 tools: read_file, bash
 ---
 
-You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.
+You are the archivist of this project's long-term memory.
+
+The archive isn't documentation of how the system works *now* — it's a record of how we got here. Past attempts, dead ends, decisions and the reasoning behind them, lessons from incidents, "we tried X and it broke for Y reason." Context, not state.
+
+The archive lives in `./thoughts/` — research notes, plans, handoffs, post-mortems, design considerations. Documentation answers `how does this work?`. The archive answers `what have we learned, tried, and decided about this?`.
+
+Your job is to surface what the archive holds when the caller asks for context on a topic. Source code is outside the archive — it describes current state. Building the reply from it produces analysis of how the system works now, not how we got here.
+
+If the archive has nothing relevant on the topic, say so. An empty archive is a real answer.
 
 **Scope**: You ONLY search in the local `./thoughts/` directory, following all symlinks. Do not search or read files outside of it. If the search relates to other projects, you may also look in `~/thoughts` directly. Never fall back to searching the broader codebase.
 
@@ -29,13 +37,10 @@ You are a specialist at extracting HIGH-VALUE insights from thoughts documents.
 
 ## Search Strategy
 
-Use `bash` with find and grep to discover and search thought documents. Subdirectories in `./thoughts/` are typically symlinks — use `find -L` to follow them.
-
-1. `ls -la ./thoughts/` — discover subdirs (shared/, username/, global/)
-2. `find -L ./thoughts/ -name "*.md"` — find all documents following symlinks
-3. `grep -rn "keyword" ./thoughts/` — search for specific topics
+`./thoughts/shared/` and most subdirs are symlinks to paths outside the repo. Lowercase `grep -r` and bare `find` skip them silently — use uppercase **`-R`** and **`-L`**.
 
-Then use `read` to analyze documents in detail.
+- `grep -Rli 'ANIMA-1234' ./thoughts/` — matches frontmatter (`tags:`, `topic:`) and body in one pass. Swap `-l` for `-n` to see matched lines.
+- `find -L ./thoughts/ -type f -name '*.md'` — enumerate when no search term applies.
 
 ## Analysis Strategy
 

data/anima-core.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "aasm", "~> 5.5"
   spec.add_dependency "certifi"
   spec.add_dependency "draper", "~> 4.0"
   spec.add_dependency "faraday", "~> 2.0"

data/app/channels/session_channel.rb

@@ -27,9 +27,7 @@ class SessionChannel < ApplicationCable::Channel
     @current_session_id = resolve_session_id
     stream_from stream_name
 
-    session = Session.find_by(id: @current_session_id)
-    return unless session
-
+    session = Session.find(@current_session_id)
     transmit_session_changed(session)
     transmit_view_mode(session)
     transmit_history(session)
@@ -42,13 +40,13 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, data)
   end
 
-  # 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, stages the message as a {PendingMessage} in a
-  # separate table until the current agent loop completes.
+  # Processes user input by enqueuing a bounce-back-flagged user_message
+  # PendingMessage on the session. The PM's +after_create_commit+ kicks
+  # off the drain pipeline — Melete → (Mneme) → {DrainJob} — when the
+  # session is idle; otherwise the PM queues silently and the idle-wake
+  # rule on {Session} picks it up on the next transition to +:idle+.
+  # If the first LLM call after promotion fails, {DrainJob} emits a
+  # {Events::BounceBack} so the TUI can restore the text to the input.
   #
   # @param data [Hash] must include "content" with the user's message text
   # @see Session#enqueue_user_message
@@ -56,10 +54,7 @@ class SessionChannel < ApplicationCable::Channel
     content = data["content"].to_s.strip
     return if content.empty?
 
-    session = Session.find_by(id: @current_session_id)
-    return unless session
-
-    session.enqueue_user_message(content, bounce_back: true)
+    Session.find(@current_session_id).enqueue_user_message(content, bounce_back: true)
   end
 
   # Recalls the most recent pending message for editing. Deletes the
@@ -75,29 +70,25 @@ class SessionChannel < ApplicationCable::Channel
     pm&.destroy!
   end
 
-  # Requests interruption of the current tool execution. Sets a flag on the
-  # session that the LLM client checks between tool calls. Remaining tools
-  # receive synthetic "Your human wants your attention" results to satisfy the API's
+  # Requests interruption of the current tool execution. Sets the
+  # +interrupt_requested+ flag on the session — long-running tools
+  # ({Tools::Bash}) poll it and abort early with a synthetic "Your
+  # human wants your attention" result that satisfies the Anthropic
   # tool_use/tool_result pairing requirement.
   #
   # Cascades to running sub-agent sessions to avoid burning tokens in
   # child jobs that the parent will discard anyway.
   #
-  # Atomic: a single UPDATE with WHERE avoids the read-then-write race where
-  # the session could finish processing between the SELECT and UPDATE.
-  # No-op if the session isn't currently processing.
+  # No-op on idle sessions — nothing to interrupt, and the flag would
+  # leak into the next round without an AASM transition to clear it.
   #
   # @param _data [Hash] unused
   def interrupt_execution(_data)
-    updated = Session.where(id: @current_session_id, processing: true)
-      .update_all(interrupt_requested: true)
-
-    return unless updated > 0
-
-    Session.processing_children_of(@current_session_id)
-      .update_all(interrupt_requested: true)
+    session = Session.find(@current_session_id)
+    return if session.idle?
 
-    Session.find_by(id: @current_session_id)&.broadcast_session_state("interrupting")
+    session.update!(interrupt_requested: true)
+    session.child_sessions.processing.update_all(interrupt_requested: true)
     ActionCable.server.broadcast(stream_name, {"action" => "interrupt_acknowledged"})
   end
 
@@ -185,13 +176,13 @@ class SessionChannel < ApplicationCable::Channel
   end
 
   # Resolves the session to subscribe to. Uses the client-provided ID
-  # when valid, otherwise falls back to the most recent session or
-  # creates a new one.
+  # when it identifies an existing session, otherwise falls back to the
+  # most recent session or creates a new one.
   #
   # @return [Integer] resolved session ID
   def resolve_session_id
     id = params[:session_id].to_i
-    return id if id > 0
+    return id if id > 0 && Session.exists?(id: id)
 
     (Session.recent(1).first || Session.create!).id
   end
@@ -219,11 +210,13 @@ class SessionChannel < ApplicationCable::Channel
       "goals" => session.goals_summary
     }
 
-    children = session.child_sessions.order(:created_at).select(:id, :name, :processing)
+    children = session.child_sessions
+      .where(hud_visible: true)
+      .order(:created_at)
+      .select(:id, :name, :aasm_state)
     if children.any?
       payload["children"] = children.map { |child|
-        state = child.processing? ? "llm_generating" : "idle"
-        {"id" => child.id, "name" => child.name, "processing" => child.processing?, "session_state" => state}
+        {"id" => child.id, "name" => child.name, "session_state" => child.aasm_state}
       }
     end
 
@@ -272,7 +265,7 @@ class SessionChannel < ApplicationCable::Channel
     end
 
     session.pending_messages.find_each do |pm|
-      transmit({"action" => "pending_message_created", "pending_message_id" => pm.id, "content" => pm.content})
+      transmit(pm.broadcast_payload(session.view_mode))
     end
   end
 
@@ -281,9 +274,6 @@ class SessionChannel < ApplicationCable::Channel
   # In debug mode, prepends the assembled system prompt as a special block.
   # Pending messages are sent last so the TUI shows them at the bottom.
   #
-  # Snapshots the viewport so subsequent message broadcasts can compute
-  # eviction diffs accurately.
-  #
   # @param session [Session] the session whose viewport to broadcast
   # @return [void]
   def broadcast_viewport(session)
@@ -294,29 +284,22 @@ class SessionChannel < ApplicationCable::Channel
     end
 
     session.pending_messages.find_each do |pm|
-      ActionCable.server.broadcast(stream_name, {"action" => "pending_message_created", "pending_message_id" => pm.id, "content" => pm.content})
+      ActionCable.server.broadcast(stream_name, pm.broadcast_payload(session.view_mode))
     end
   end
 
-  # Loads the viewport, snapshots it for eviction tracking, and yields
-  # each message with its decorated payload in newest-first order.
-  # Newest-first prevents render thrashing during session switches: the
-  # most recent messages fill the visible viewport immediately, while
-  # older messages are inserted above the fold without visual disruption.
-  #
-  # Snapshot uses snapshot_viewport! (not recalculate_viewport!) because
-  # full viewport refreshes don't need eviction diffs — clients clear
-  # their store before rendering.
+  # Loads the viewport and yields each message with its decorated payload
+  # in newest-first order. Newest-first prevents render thrashing during
+  # session switches: the most recent messages fill the visible viewport
+  # immediately, while older messages are inserted above the fold without
+  # visual disruption.
   #
   # @param session [Session] the session whose viewport to iterate
   # @yieldparam message [Message] the persisted message record
   # @yieldparam payload [Hash] decorated payload ready for transmission
   # @return [void]
   def each_viewport_message(session)
-    viewport = session.viewport_messages
-    session.snapshot_viewport!(viewport.map(&:id))
-
-    viewport.reverse_each do |msg|
+    session.viewport_messages.reverse_each do |msg|
       yield msg, decorate_message_payload(msg, session.view_mode)
     end
   end
@@ -324,17 +307,14 @@ class SessionChannel < ApplicationCable::Channel
   # 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 {Message::Broadcasting}.
+  # and viewport re-broadcast — live broadcasts use {Events::Subscribers::MessageBroadcaster}.
   #
   # @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_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)})
+    payload.merge("rendered" => {mode => message.decorate.render(mode)})
   end
 
   # Transmits the assembled system prompt to the subscribing client.
@@ -402,7 +382,7 @@ class SessionChannel < ApplicationCable::Channel
       {
         id: child.id,
         name: child.name,
-        processing: child.processing?,
+        session_state: child.aasm_state,
         message_count: counts[child.id] || 0,
         created_at: child.created_at.iso8601
       }

data/app/decorators/agent_message_decorator.rb

@@ -22,9 +22,14 @@ class AgentMessageDecorator < MessageDecorator
     render_verbose.merge(token_info)
   end
 
-  # @return [String] agent message for the analytical brain, middle-truncated
+  # @return [String] agent message for Melete, middle-truncated
   #   if very long (preserves opening context and final conclusion)
-  def render_brain
+  def render_melete
     "Assistant: #{truncate_middle(content)}"
   end
+
+  # @return [String] transcript line for Mneme's eviction/context zones
+  def render_mneme
+    "message #{id} Assistant: #{content}"
+  end
 end

data/app/decorators/message_decorator.rb

@@ -1,34 +1,29 @@
 # frozen_string_literal: true
 
 # Base decorator for {Message} records, providing multi-resolution rendering
-# for the TUI and analytical brain. Each message type has a dedicated subclass
+# for the TUI and Melete. Each message type has a dedicated subclass
 # that implements rendering methods for each view mode:
 #
 # - **basic** / **verbose** / **debug** — TUI display modes returning structured hashes
-# - **brain** — analytical brain transcript returning plain strings (or nil to skip)
+# - **melete** — Melete transcript lines as plain strings (or nil to skip)
 #
 # TUI decorators return structured hashes (not pre-formatted strings) so that
 # the TUI can style and lay out content based on semantic role, without
 # fragile regex parsing. The TUI receives structured data via ActionCable
 # and formats it for display.
 #
-# Brain mode returns condensed single-line strings for the analytical brain's
-# message transcript. Returns nil to exclude a message from the brain's view.
+# Melete mode returns condensed single-line strings for her message
+# transcript. Returns nil to exclude a message from her view.
 #
-# Subclasses must override {#render_basic}. Verbose, debug, and brain modes
+# Subclasses must override {#render_basic}. Verbose, debug, and melete modes
 # delegate to basic until subclasses provide their own implementations.
 #
-# @example Decorate a Message AR model
-#   decorator = MessageDecorator.for(message)
-#   decorator.render_basic  #=> {role: :user, content: "hello"} or nil
+# Instantiate via +message.decorate+ — {Message#decorator_class} picks the
+# concrete subclass based on +message_type+.
 #
-# @example Render for a specific view mode
-#   decorator = MessageDecorator.for(message)
-#   decorator.render("verbose")  #=> {role: :user, content: "hello", timestamp: 1709312325000000000}
-#
-# @example Decorate a raw payload hash (from EventBus)
-#   decorator = MessageDecorator.for(type: "user_message", content: "hello")
-#   decorator.render_basic  #=> {role: :user, content: "hello"}
+# @example Decorate a message and render it
+#   decorator = message.decorate
+#   decorator.render("basic")  #=> {role: :user, content: "hello"} or nil
 class MessageDecorator < ApplicationDecorator
   delegate_all
 
@@ -37,63 +32,20 @@ class MessageDecorator < ApplicationDecorator
   ERROR_ICON = "\u274C"
   MIDDLE_TRUNCATION_MARKER = "\n[...truncated...]\n"
 
-  DECORATOR_MAP = {
-    "user_message" => "UserMessageDecorator",
-    "agent_message" => "AgentMessageDecorator",
-    "tool_call" => "ToolCallDecorator",
-    "tool_response" => "ToolResponseDecorator",
-    "system_message" => "SystemMessageDecorator"
-  }.freeze
-  private_constant :DECORATOR_MAP
-
-  # 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 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
-  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 message_type.to_s.in?(%w[tool_call tool_response])
-        payload.to_json
-      else
-        payload&.dig("content").to_s
-      end
-      [(text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
-    end
-  end
-
-  # Factory returning the appropriate subclass decorator for the given message.
-  # Hashes are normalized via {MessagePayload} to provide a uniform interface.
-  #
-  # @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)
-  end
-
   RENDER_DISPATCH = {
     "basic" => :render_basic,
     "verbose" => :render_verbose,
     "debug" => :render_debug,
-    "brain" => :render_brain
+    "melete" => :render_melete,
+    "mneme" => :render_mneme
   }.freeze
   private_constant :RENDER_DISPATCH
 
   # Dispatches to the render method for the given view mode.
   #
-  # @param mode [String] one of "basic", "verbose", "debug", "brain"
+  # @param mode [String] one of "basic", "verbose", "debug", "melete", "mneme"
   # @return [Hash, String, nil] structured message data (basic/verbose/debug),
-  #   plain string (brain), or nil to hide the message
+  #   plain string (melete), or nil to hide the message
   # @raise [ArgumentError] if the mode is not a valid view mode
   def render(mode)
     method = RENDER_DISPATCH[mode]
@@ -122,36 +74,31 @@ class MessageDecorator < ApplicationDecorator
     render_basic
   end
 
-  # Analytical brain view — condensed single-line string for the brain's
-  # message transcript. Returns nil to exclude from the brain's context.
+  # Melete view — condensed single-line string for her message
+  # transcript. Returns nil to exclude from her context.
   # Subclasses override to provide message-type-specific formatting.
   # @return [String, nil] formatted transcript line, or nil to skip
-  def render_brain
+  def render_melete
+    nil
+  end
+
+  # Mneme memory view — transcript line for eviction/context zones.
+  # Conversation and think messages return a prefixed string.
+  # Regular tool calls return +:tool_call+ (counter marker).
+  # Tool responses return +nil+ (silent).
+  # @return [String, Symbol, nil]
+  def render_mneme
     nil
   end
 
   private
 
-  # 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.
+  # Token count for display: heuristic estimate seeded by the
+  # {TokenEstimation} callback, refined later by {CountTokensJob}.
   #
-  # @return [Hash] `{tokens: Integer, estimated: Boolean}`
+  # @return [Hash] `{tokens: Integer}`
   def token_info
-    count = token_count.to_i
-    if count > 0
-      {tokens: count, estimated: false}
-    else
-      {tokens: estimate_token_count, estimated: true}
-    end
-  end
-
-  # Delegates to the underlying object's heuristic token estimator.
-  # Both {Message} AR models and {MessagePayload} structs implement this.
-  #
-  # @return [Integer] at least 1
-  def estimate_token_count
-    object.estimate_tokens
+    {tokens: token_count.to_i}
   end
 
   # Extracts display content from the message payload.
@@ -173,7 +120,7 @@ class MessageDecorator < ApplicationDecorator
   end
 
   # Truncates long text by cutting the middle, preserving the start and end
-  # so context and conclusions aren't lost. Used for brain transcripts where
+  # so context and conclusions aren't lost. Used for Melete transcripts where
   # both the opening (intent) and closing (result) matter.
   #
   # @param text [String, nil] text to truncate
@@ -188,20 +135,4 @@ class MessageDecorator < ApplicationDecorator
     tail = keep - head
     "#{str[0, head]}#{MIDDLE_TRUNCATION_MARKER}#{str[-tail, tail]}"
   end
-
-  # Normalizes input to something Draper can wrap.
-  # Message AR models pass through; hashes become MessagePayload structs
-  # with string-normalized keys.
-  def self.wrap_source(message)
-    return message unless message.is_a?(Hash)
-
-    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
-    )
-  end
-  private_class_method :wrap_source
 end

data/app/decorators/pending_from_melete_decorator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Shared base for the three Melete-activation pending decorators (skill,
+# workflow, goal). All three share the same TUI shape — a dimmed
+# +pending_melete+ payload with +kind+ + +source+ + truncated content
+# — and only differ on the +KIND+ constant and the per-type Melete
+# transcript line. Subclasses override +KIND+ and +render_melete+; this
+# base owns everything else.
+class PendingFromMeleteDecorator < PendingMessageDecorator
+  # @return [nil] Melete activations are hidden in basic mode
+  def render_basic
+    nil
+  end
+
+  # @return [Hash] dimmed Melete-activation payload
+  def render_verbose
+    {
+      role: :pending_melete,
+      kind: self.class::KIND,
+      source: source_name,
+      content: truncate_lines(content, max_lines: 3),
+      status: "pending"
+    }
+  end
+
+  # @return [Hash] full Melete-activation payload
+  def render_debug
+    {
+      role: :pending_melete,
+      kind: self.class::KIND,
+      source: source_name,
+      content: content,
+      status: "pending"
+    }
+  end
+end

data/app/decorators/pending_from_melete_goal_decorator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Decorates a +from_melete_goal+ {PendingMessage} — a goal event Melete
+# logged for the upcoming turn (created/updated/closed). See
+# {PendingFromMeleteDecorator} for the shared TUI rendering shape.
+class PendingFromMeleteGoalDecorator < PendingFromMeleteDecorator
+  KIND = "goal"
+
+  # @return [String] Melete transcript line — goal id and content
+  def render_melete
+    "Melete logged goal #{source_name}: #{truncate_middle(content)}"
+  end
+end

data/app/decorators/pending_from_melete_skill_decorator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Decorates a +from_melete_skill+ {PendingMessage} — a skill that Melete
+# activated for the upcoming turn. Promotes into a phantom
+# +from_melete_skill+ tool_call/tool_response pair so the LLM sees it as
+# its own past invocation; while pending, it shows in the TUI as a
+# Melete badge so the user knows the skill is about to enter context.
+#
+# TUI rendering shape lives in {PendingFromMeleteDecorator} — only the
+# +KIND+ constant and the Melete transcript line differ across the
+# skill/workflow/goal trio.
+class PendingFromMeleteSkillDecorator < PendingFromMeleteDecorator
+  KIND = "skill"
+
+  # @return [String] Melete transcript line (header only — content is the skill body)
+  def render_melete
+    "Melete activated skill: #{source_name}"
+  end
+end

data/app/decorators/pending_from_melete_workflow_decorator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Decorates a +from_melete_workflow+ {PendingMessage} — a workflow that
+# Melete activated for the upcoming turn. See
+# {PendingFromMeleteDecorator} for the shared TUI rendering shape.
+class PendingFromMeleteWorkflowDecorator < PendingFromMeleteDecorator
+  KIND = "workflow"
+
+  # @return [String] Melete transcript line (header only — content is the workflow body)
+  def render_melete
+    "Melete activated workflow: #{source_name}"
+  end
+end

data/app/decorators/pending_from_mneme_decorator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Decorates a +from_mneme+ {PendingMessage} — an associative recall
+# enqueued by Mneme that will become a phantom +from_mneme+
+# tool_call/tool_response pair on promotion. Background-kind, so it
+# rides the next active drain instead of triggering one.
+#
+# Hidden in basic. Visible from verbose with a +[Mneme recall]+ badge.
+class PendingFromMnemeDecorator < PendingMessageDecorator
+  # @return [nil] Mneme recalls are hidden in basic mode
+  def render_basic
+    nil
+  end
+
+  # @return [Hash] dimmed Mneme recall payload
+  def render_verbose
+    {
+      role: :pending_mneme,
+      content: truncate_lines(content, max_lines: 3),
+      status: "pending"
+    }
+  end
+
+  # @return [Hash] full Mneme recall payload
+  def render_debug
+    {
+      role: :pending_mneme,
+      content: content,
+      status: "pending"
+    }
+  end
+
+  # @return [String] Melete transcript line — Mneme recalls become part
+  #   of Melete's extended-context view (her "what's about to land" peek).
+  def render_melete
+    "Mneme recalled (pending): #{truncate_middle(content)}"
+  end
+
+  # +render_mneme+ is intentionally NOT overridden — Mneme runs recall
+  # over the conversation transcript, and surfacing pending Mneme
+  # recalls back to herself would create a circular injection where
+  # she keeps re-discovering her own queued contributions. Inherits
+  # the base nil so they stay invisible to her recall mode.
+end