rubyn-code 0.5.0 → 0.7.0

data/lib/rubyn_code/teams/agent_registry.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Teams
+    # Discovery service for active agents in the system.
+    #
+    # Provides a unified view of all agents (main loop, sub-agents, teammates)
+    # with status, lineage, and messaging capabilities.
+    class AgentRegistry
+      # @param manager [Manager] the teammate manager
+      # @param mailbox [Mailbox] the team mailbox
+      def initialize(manager:, mailbox:)
+        @manager = manager
+        @mailbox = mailbox
+      end
+
+      # Returns a snapshot of all registered agents with their status
+      # and unread message counts.
+      #
+      # @return [Array<Hash>] agent snapshots
+      def snapshot
+        @manager.list.map { |t| agent_snapshot(t) }
+      end
+
+      # Returns only active agents.
+      #
+      # @return [Array<Hash>] active agent snapshots
+      def active
+        @manager.active_teammates.map { |t| agent_snapshot(t) }
+      end
+
+      # Returns the full agent tree starting from all root agents.
+      #
+      # @return [Array<Hash>] nested tree structures
+      def forest
+        @manager.roots.map { |root| build_display_tree(root) }
+      end
+
+      # Returns lineage (ancestors) for a given agent.
+      #
+      # @param agent_id [String] the agent's ID
+      # @return [Array<Teammate>] ordered from root to immediate parent
+      def lineage(agent_id)
+        ancestors = []
+        current = @manager.find_by_id(agent_id)
+        return ancestors unless current
+
+        while current&.parent_agent_id
+          parent = @manager.find_by_id(current.parent_agent_id)
+          break unless parent
+
+          ancestors.unshift(parent)
+          current = parent
+        end
+
+        ancestors
+      end
+
+      # Returns a formatted status report of all agents.
+      #
+      # @return [String] human-readable status report
+      def status_report
+        agents = snapshot
+        return 'No agents registered.' if agents.empty?
+
+        lines = ['Agent Registry Status:', '']
+        agents.each do |agent|
+          icon = status_icon(agent[:status])
+          parent_info = agent[:parent_agent_id] ? " (child of #{agent[:parent_agent_id][0, 8]})" : ' (root)'
+          lines << "  #{icon} #{agent[:name]} [#{agent[:role]}] — #{agent[:status]}#{parent_info}"
+          lines << "    Unread: #{agent[:unread_count]}" if agent[:unread_count].positive?
+        end
+        lines.join("\n")
+      end
+
+      private
+
+      # Builds a snapshot hash for a single agent.
+      #
+      # @param teammate [Teammate]
+      # @return [Hash]
+      def agent_snapshot(teammate)
+        {
+          id: teammate.id,
+          name: teammate.name,
+          role: teammate.role,
+          status: teammate.status,
+          parent_agent_id: teammate.parent_agent_id,
+          unread_count: @mailbox.unread_count(teammate.name),
+          created_at: teammate.created_at
+        }
+      end
+
+      # Recursively builds a display tree with snapshot data.
+      #
+      # @param agent [Teammate]
+      # @return [Hash]
+      def build_display_tree(agent)
+        children = @manager.children_of(agent.id)
+        {
+          **agent_snapshot(agent),
+          children: children.map { |child| build_display_tree(child) }
+        }
+      end
+
+      # Returns a status icon for display.
+      #
+      # @param status [String]
+      # @return [String]
+      def status_icon(status)
+        case status
+        when 'active' then '🟢'
+        when 'idle'   then '🟡'
+        when 'offline' then '⚫'
+        else '❓'
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/teams/mailbox.rb

@@ -9,6 +9,8 @@ module RubynCode
     #
     # Messages are stored in the `mailbox_messages` table with structured
     # JSON content. Each message tracks read/unread state per recipient.
+    # Supports structured data payloads and correlation IDs for
+    # request/response tracking.
     class Mailbox
       # @param db [DB::Connection] the database connection
       def initialize(db)
@@ -22,8 +24,11 @@ module RubynCode
       # @param to [String] recipient agent name
       # @param content [String] message body
       # @param message_type [String] type of message (default: "message")
+      # @param correlation_id [String, nil] optional correlation ID for request/response pairing
+      # @param data [Hash, nil] optional structured data payload
       # @return [String] the message id
-      def send(from:, to:, content:, message_type: 'message')
+      # rubocop:disable Metrics/ParameterLists
+      def send(from:, to:, content:, message_type: 'message', correlation_id: nil, data: nil)
         id = SecureRandom.uuid
         now = Time.now.utc.iso8601
 
@@ -36,25 +41,54 @@ module RubynCode
                                   timestamp: now
                                 })
 
+        data_json = data ? JSON.generate(data) : nil
+
         @db.execute(
           <<~SQL,
-            INSERT INTO mailbox_messages (id, sender, recipient, message_type, payload, read, created_at)
-            VALUES (?, ?, ?, ?, ?, 0, ?)
+            INSERT INTO mailbox_messages (id, sender, recipient, message_type, payload, correlation_id, data, read, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?)
           SQL
-          [id, from, to, message_type, payload, now]
+          [id, from, to, message_type, payload, correlation_id, data_json, now]
         )
 
         id
       end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Sends a structured message with typed data payload.
+      # Convenience wrapper around #send for machine-to-machine communication.
+      #
+      # @param from [String] sender agent name
+      # @param to [String] recipient agent name
+      # @param type [String] message type (e.g. 'task', 'result', 'error')
+      # @param data [Hash] structured data payload
+      # @param content [String] human-readable summary (default: auto-generated)
+      # @param correlation_id [String, nil] optional correlation ID
+      # @return [String] the message id
+      # rubocop:disable Metrics/ParameterLists
+      def send_structured(from:, to:, type:, data:, content: nil, correlation_id: nil)
+        content ||= "#{type}: #{data.inspect}"[0, 200]
+        correlation_id ||= SecureRandom.uuid
+
+        send(
+          from: from,
+          to: to,
+          content: content,
+          message_type: type,
+          correlation_id: correlation_id,
+          data: data
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
 
       # Reads all unread messages for the given agent and marks them as read.
       #
       # @param name [String] the recipient agent name
-      # @return [Array<Hash>] parsed message hashes
+      # @return [Array<Hash>] parsed message hashes with optional :data key
       def read_inbox(name)
         rows = @db.query(
           <<~SQL,
-            SELECT id, payload FROM mailbox_messages
+            SELECT id, payload, correlation_id, data FROM mailbox_messages
             WHERE recipient = ? AND read = 0
             ORDER BY created_at ASC
           SQL
@@ -64,7 +98,7 @@ module RubynCode
         return [] if rows.empty?
 
         ids = rows.map { |r| r['id'] }
-        messages = rows.map { |r| JSON.parse(r['payload'], symbolize_names: true) }
+        messages = rows.map { |r| parse_message_row(r) }
 
         # Mark all fetched messages as read in a single statement
         placeholders = ids.map { '?' }.join(', ')
@@ -76,6 +110,24 @@ module RubynCode
         messages
       end
 
+      # Finds all messages matching a correlation ID.
+      # Useful for tracking request/response chains.
+      #
+      # @param correlation_id [String] the correlation ID to search for
+      # @return [Array<Hash>] matched messages ordered by creation time
+      def find_by_correlation_id(correlation_id)
+        rows = @db.query(
+          <<~SQL,
+            SELECT id, payload, correlation_id, data FROM mailbox_messages
+            WHERE correlation_id = ?
+            ORDER BY created_at ASC
+          SQL
+          [correlation_id]
+        ).to_a
+
+        rows.map { |r| parse_message_row(r) }
+      end
+
       # Broadcasts a message from one agent to all other agents.
       #
       # @param from [String] sender agent name
@@ -98,14 +150,14 @@ module RubynCode
       def pending_for(name)
         rows = @db.query(
           <<~SQL,
-            SELECT payload FROM mailbox_messages
+            SELECT id, payload, correlation_id, data FROM mailbox_messages
             WHERE recipient = ? AND read = 0
             ORDER BY created_at ASC
           SQL
           [name]
         ).to_a
 
-        rows.map { |r| JSON.parse(r['payload'], symbolize_names: true) }
+        rows.map { |r| parse_message_row(r) }
       end
 
       # Returns the count of unread messages for the given agent.
@@ -122,8 +174,22 @@ module RubynCode
 
       private
 
+      # Parses a message row into a hash, merging structured data if present.
+      #
+      # @param row [Hash] database row
+      # @return [Hash] parsed message with optional :data and :correlation_id keys
+      def parse_message_row(row)
+        msg = JSON.parse(row['payload'], symbolize_names: true)
+        msg[:correlation_id] = row['correlation_id'] if row['correlation_id']
+        msg[:data] = JSON.parse(row['data'], symbolize_names: true) if row['data']
+        msg
+      rescue JSON::ParserError
+        { content: row['payload'].to_s, parse_error: true }
+      end
+
       # Creates the mailbox_messages table if it does not already exist.
-      # Schema must stay in sync with db/migrations/009_create_teams.sql.
+      # Schema must stay in sync with db/migrations/009_create_teams.sql
+      # and 014_multi_agent_upgrade.rb.
       def ensure_table!
         @db.execute(<<~SQL)
           CREATE TABLE IF NOT EXISTS mailbox_messages (
@@ -133,15 +199,38 @@ module RubynCode
             message_type TEXT NOT NULL DEFAULT 'message'
               CHECK(message_type IN ('message','task','result','error','broadcast','shutdown_request','shutdown_response','status_change')),
             payload TEXT NOT NULL,
+            correlation_id TEXT,
+            data TEXT,
             read INTEGER NOT NULL DEFAULT 0,
             created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
           )
         SQL
 
+        # Self-heal: add the columns the original migration lacked so
+        # that test databases bootstrapped before the multi-agent
+        # upgrade don't end up with a half-built table.  Each ALTER
+        # is a no-op if the column already exists (SQLite returns an
+        # error which we swallow).
+        add_mailbox_column_if_missing('correlation_id')
+        add_mailbox_column_if_missing('data')
+
         @db.execute(<<~SQL)
           CREATE INDEX IF NOT EXISTS idx_mailbox_recipient_read
           ON mailbox_messages (recipient, read)
         SQL
+
+        @db.execute(<<~SQL)
+          CREATE INDEX IF NOT EXISTS idx_mailbox_correlation
+          ON mailbox_messages (correlation_id)
+        SQL
+      end
+
+      # @return [Boolean] true if the column was added
+      def add_mailbox_column_if_missing(column)
+        @db.execute("ALTER TABLE mailbox_messages ADD COLUMN #{column} TEXT")
+        true
+      rescue SQLite3::SQLException
+        false
       end
     end
   end

data/lib/rubyn_code/teams/manager.rb

@@ -9,7 +9,7 @@ module RubynCode
     # CRUD manager for teammates backed by SQLite.
     #
     # Provides lifecycle management for agent teammates: spawning,
-    # listing, status updates, and removal.
+    # listing, status updates, removal, and parent-child discovery.
     class Manager
       # @param db [DB::Connection] the database connection
       # @param mailbox [Mailbox] the team mailbox for inter-agent messaging
@@ -25,9 +25,10 @@ module RubynCode
       # @param role [String] the teammate's role description
       # @param persona [String, nil] optional persona prompt
       # @param model [String, nil] optional LLM model override
+      # @param parent_agent_id [String, nil] ID of the parent agent that spawned this teammate
       # @return [Teammate] the newly created teammate
       # @raise [Error] if a teammate with the given name already exists
-      def spawn(name:, role:, persona: nil, model: nil)
+      def spawn(name:, role:, persona: nil, model: nil, parent_agent_id: nil)
         existing = get(name)
         raise Error, "Teammate '#{name}' already exists" if existing
 
@@ -37,10 +38,10 @@ module RubynCode
 
         @db.execute(
           <<~SQL,
-            INSERT INTO teammates (id, name, role, persona, model, status, metadata, created_at)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            INSERT INTO teammates (id, name, role, persona, model, status, parent_agent_id, metadata, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
           SQL
-          [id, name, role, persona, model, 'idle', metadata_json, now]
+          [id, name, role, persona, model, 'idle', parent_agent_id, metadata_json, now]
         )
 
         Teammate.new(
@@ -50,6 +51,7 @@ module RubynCode
           persona: persona,
           model: model,
           status: 'idle',
+          parent_agent_id: parent_agent_id,
           metadata: {},
           created_at: now
         )
@@ -74,6 +76,51 @@ module RubynCode
         row_to_teammate(rows.first)
       end
 
+      # Finds a teammate by ID.
+      #
+      # @param id [String]
+      # @return [Teammate, nil]
+      def find_by_id(id)
+        rows = @db.query('SELECT * FROM teammates WHERE id = ? LIMIT 1', [id]).to_a
+        return nil if rows.empty?
+
+        row_to_teammate(rows.first)
+      end
+
+      # Returns all direct children of the given parent agent.
+      #
+      # @param parent_id [String] the parent agent's ID
+      # @return [Array<Teammate>]
+      def children_of(parent_id)
+        rows = @db.query(
+          'SELECT * FROM teammates WHERE parent_agent_id = ? ORDER BY created_at ASC',
+          [parent_id]
+        ).to_a
+        rows.map { |row| row_to_teammate(row) }
+      end
+
+      # Returns all root agents (those with no parent).
+      #
+      # @return [Array<Teammate>]
+      def roots
+        rows = @db.query(
+          'SELECT * FROM teammates WHERE parent_agent_id IS NULL ORDER BY created_at ASC'
+        ).to_a
+        rows.map { |row| row_to_teammate(row) }
+      end
+
+      # Builds a full agent tree from a root agent ID.
+      # Returns a nested hash: { agent: Teammate, children: [{ agent:, children: }, ...] }
+      #
+      # @param root_id [String] the root agent's ID
+      # @return [Hash, nil] nested tree structure or nil if root not found
+      def agent_tree(root_id)
+        root = find_by_id(root_id)
+        return nil unless root
+
+        build_tree_node(root)
+      end
+
       # Updates a teammate's status.
       #
       # @param name [String]
@@ -120,6 +167,18 @@ module RubynCode
 
       private
 
+      # Recursively builds a tree node for an agent and its children.
+      #
+      # @param agent [Teammate]
+      # @return [Hash]
+      def build_tree_node(agent)
+        kids = children_of(agent.id)
+        {
+          agent: agent,
+          children: kids.map { |child| build_tree_node(child) }
+        }
+      end
+
       # Converts a database row hash to a Teammate value object.
       #
       # @param row [Hash]
@@ -134,6 +193,7 @@ module RubynCode
           persona: row['persona'],
           model: row['model'],
           status: row['status'],
+          parent_agent_id: row['parent_agent_id'],
           metadata: metadata,
           created_at: row['created_at']
         )
@@ -161,14 +221,32 @@ module RubynCode
             persona TEXT,
             model TEXT,
             status TEXT NOT NULL DEFAULT 'idle',
+            parent_agent_id TEXT,
             metadata TEXT NOT NULL DEFAULT '{}',
             created_at TEXT NOT NULL
           )
         SQL
 
+        # Self-heal: add columns that later migrations added to legacy
+        # tables.  Same pattern as Mailbox#ensure_table!.
+        add_teammate_column_if_missing('parent_agent_id')
+        add_teammate_column_if_missing('metadata')
+
         @db.execute(<<~SQL)
           CREATE UNIQUE INDEX IF NOT EXISTS idx_teammates_name ON teammates (name)
         SQL
+
+        @db.execute(<<~SQL)
+          CREATE INDEX IF NOT EXISTS idx_teammates_parent ON teammates (parent_agent_id)
+        SQL
+      end
+
+      # @return [Boolean] true if the column was added
+      def add_teammate_column_if_missing(column)
+        @db.execute("ALTER TABLE teammates ADD COLUMN #{column} TEXT")
+        true
+      rescue SQLite3::SQLException
+        false
       end
     end
   end

data/lib/rubyn_code/teams/teammate.rb

@@ -8,7 +8,7 @@ module RubynCode
     VALID_STATUSES = %w[idle active offline].freeze
 
     Teammate = Data.define(
-      :id, :name, :role, :persona, :model, :status, :metadata, :created_at
+      :id, :name, :role, :persona, :model, :status, :parent_agent_id, :metadata, :created_at
     ) do
       # @return [Boolean]
       def idle? = status == 'idle'
@@ -19,6 +19,9 @@ module RubynCode
       # @return [Boolean]
       def offline? = status == 'offline'
 
+      # @return [Boolean] true if this teammate was not spawned by another agent
+      def root? = parent_agent_id.nil?
+
       # @return [Hash]
       def to_h
         {
@@ -28,6 +31,7 @@ module RubynCode
           persona: persona,
           model: model,
           status: status,
+          parent_agent_id: parent_agent_id,
           metadata: metadata,
           created_at: created_at
         }

data/lib/rubyn_code/tools/ask_user.rb

@@ -20,10 +20,24 @@ module RubynCode
       }.freeze
       RISK_LEVEL = :read # Never needs approval — it IS the approval mechanism
 
+      # The user may take a while to answer, so allow far longer than the
+      # default RPC timeout before giving up on the IDE round-trip.
+      IDE_ASK_TIMEOUT = 300 # seconds
+
       attr_writer :prompt_callback
 
+      def initialize(project_root:, ide_client: nil)
+        super(project_root: project_root)
+        @ide_client = ide_client
+      end
+
       def execute(question:)
-        if @prompt_callback
+        if @ide_client
+          # IDE mode: round-trip the question through the extension's UI.
+          response = @ide_client.request('ide/askUser', { question: question }, timeout: IDE_ASK_TIMEOUT)
+          answer = response && response['answer']
+          answer.nil? || answer.empty? ? '[no response]' : answer
+        elsif @prompt_callback
           @prompt_callback.call(question)
         elsif $stdin.respond_to?(:tty?) && $stdin.tty?
           # Interactive fallback: prompt on stdin

data/lib/rubyn_code/tools/executor.rb

@@ -56,8 +56,10 @@ module RubynCode
 
       def build_tool(tool_name)
         tool_class = Registry.get(tool_name)
-        # IDE-aware tools accept an ide_client parameter.
-        if @ide_client && tool_class.method(:new).parameters.any? { |_, name| name == :ide_client }
+        # IDE-aware tools accept an ide_client parameter. Inspect #initialize,
+        # not .method(:new) — the latter reports Class#new's own [[:rest]]
+        # signature and never forwards to the constructor.
+        if @ide_client && tool_class.instance_method(:initialize).parameters.any? { |_, name| name == :ide_client }
           tool = tool_class.new(project_root: project_root, ide_client: @ide_client)
         else
           tool = tool_class.new(project_root: project_root)
@@ -140,7 +142,7 @@ module RubynCode
         path = resolve_cache_path(params)
         return unless path&.end_with?('.rb')
 
-        @codebase_index.update!
+        @codebase_index.update_file!(path)
       rescue StandardError => e
         RubynCode::Debug.warn("CodebaseIndex incremental update failed: #{e.message}")
       end