prompt_objects 0.1.0

data/lib/prompt_objects/mcp/server.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module PromptObjects
+  module MCP
+    # MCP Server exposing PromptObjects functionality
+    # This allows any MCP client (Claude Desktop, Go TUI, etc.) to interact with POs
+    class Server
+      attr_reader :env, :mcp_server
+
+      def initialize(objects_dir: "objects", primitives_dir: nil)
+        @objects_dir = objects_dir
+        @primitives_dir = primitives_dir
+        @env = nil
+        @context = nil
+      end
+
+      def start
+        setup_environment
+        setup_mcp_server
+        run_stdio_transport
+      end
+
+      private
+
+      def setup_environment
+        @env = Environment.new(
+          objects_dir: @objects_dir,
+          primitives_dir: @primitives_dir
+        )
+        @context = @env.context(tui_mode: true)
+
+        load_all_objects
+      end
+
+      def load_all_objects
+        return unless Dir.exist?(@objects_dir)
+
+        Dir.glob(File.join(@objects_dir, "*.md")).each do |path|
+          @env.load_prompt_object(path)
+        rescue StandardError => e
+          warn "Failed to load #{path}: #{e.message}"
+        end
+
+        @env.registry.prompt_objects.each do |po|
+          @env.load_dependencies(po)
+        end
+      end
+
+      def setup_mcp_server
+        @mcp_server = ::MCP::Server.new(
+          name: "prompt_objects",
+          version: "0.1.0",
+          tools: build_tools,
+          server_context: { env: @env, context: @context }
+        )
+
+        setup_resource_handlers
+      end
+
+      def build_tools
+        [
+          Tools::ListPromptObjects,
+          Tools::SendMessage,
+          Tools::GetConversation,
+          Tools::GetPendingRequests,
+          Tools::RespondToRequest,
+          Tools::InspectPO
+        ]
+      end
+
+      def setup_resource_handlers
+        @mcp_server.resources_read_handler do |params|
+          handle_resource_read(params)
+        end
+      end
+
+      def handle_resource_read(params)
+        uri = params[:uri]
+
+        case uri
+        when %r{^po://([^/]+)/conversation$}
+          po_name = ::Regexp.last_match(1)
+          read_conversation(po_name)
+        when %r{^po://([^/]+)/config$}
+          po_name = ::Regexp.last_match(1)
+          read_config(po_name)
+        when %r{^po://([^/]+)/prompt$}
+          po_name = ::Regexp.last_match(1)
+          read_prompt(po_name)
+        when "bus://messages"
+          read_bus_messages
+        else
+          [{ uri: uri, mimeType: "text/plain", text: "Unknown resource: #{uri}" }]
+        end
+      end
+
+      def read_conversation(po_name)
+        po = @env.registry.get(po_name)
+        return [{ uri: "po://#{po_name}/conversation", mimeType: "text/plain", text: "PO not found" }] unless po
+
+        history = po.history.map do |msg|
+          { role: msg[:role].to_s, content: msg[:content] }
+        end
+
+        [{
+          uri: "po://#{po_name}/conversation",
+          mimeType: "application/json",
+          text: JSON.pretty_generate(history)
+        }]
+      end
+
+      def read_config(po_name)
+        po = @env.registry.get(po_name)
+        return [{ uri: "po://#{po_name}/config", mimeType: "text/plain", text: "PO not found" }] unless po
+
+        [{
+          uri: "po://#{po_name}/config",
+          mimeType: "application/json",
+          text: JSON.pretty_generate(po.config)
+        }]
+      end
+
+      def read_prompt(po_name)
+        po = @env.registry.get(po_name)
+        return [{ uri: "po://#{po_name}/prompt", mimeType: "text/plain", text: "PO not found" }] unless po
+
+        [{
+          uri: "po://#{po_name}/prompt",
+          mimeType: "text/markdown",
+          text: po.body
+        }]
+      end
+
+      def read_bus_messages
+        entries = @env.bus.recent(50).map do |entry|
+          {
+            from: entry[:from],
+            to: entry[:to],
+            message: entry[:message],
+            timestamp: entry[:timestamp]&.iso8601
+          }
+        end
+
+        [{
+          uri: "bus://messages",
+          mimeType: "application/json",
+          text: JSON.pretty_generate(entries)
+        }]
+      end
+
+      def run_stdio_transport
+        transport = ::MCP::Server::Transports::StdioTransport.new(@mcp_server)
+        transport.open
+      end
+    end
+  end
+end
+
+# Require tools
+require_relative "tools/list_prompt_objects"
+require_relative "tools/send_message"
+require_relative "tools/get_conversation"
+require_relative "tools/get_pending_requests"
+require_relative "tools/respond_to_request"
+require_relative "tools/inspect_po"

data/lib/prompt_objects/mcp/tools/get_conversation.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module MCP
+    module Tools
+      # Get conversation history for a prompt object
+      class GetConversation < ::MCP::Tool
+        tool_name "get_conversation"
+        description "Get the conversation history for a prompt object"
+
+        input_schema(
+          type: "object",
+          properties: {
+            po_name: {
+              type: "string",
+              description: "Name of the prompt object"
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of messages to return (default: all)"
+            }
+          },
+          required: %w[po_name]
+        )
+
+        def self.call(po_name:, limit: nil, server_context:)
+          env = server_context[:env]
+
+          po = env.registry.get(po_name)
+          unless po.is_a?(PromptObjects::PromptObject)
+            return ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.generate({ error: "Prompt object '#{po_name}' not found" })
+            }])
+          end
+
+          history = po.history.map do |msg|
+            {
+              role: msg[:role].to_s,
+              content: msg[:content],
+              from: msg[:from],
+              tool_calls: msg[:tool_calls]&.map { |tc| { name: tc.name, arguments: tc.arguments } }
+            }.compact
+          end
+
+          history = history.last(limit) if limit
+
+          ::MCP::Tool::Response.new([{
+            type: "text",
+            text: JSON.pretty_generate({
+              po_name: po_name,
+              message_count: history.length,
+              history: history
+            })
+          }])
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/mcp/tools/get_pending_requests.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module MCP
+    module Tools
+      # Get all pending human requests from the queue
+      class GetPendingRequests < ::MCP::Tool
+        tool_name "get_pending_requests"
+        description "Get all pending human requests across all prompt objects. These are questions POs have asked that await human response."
+
+        input_schema(
+          type: "object",
+          properties: {
+            po_name: {
+              type: "string",
+              description: "Optional: filter to requests from a specific PO"
+            }
+          },
+          required: []
+        )
+
+        def self.call(po_name: nil, server_context:)
+          env = server_context[:env]
+          queue = env.human_queue
+
+          requests = if po_name
+                       queue.pending_for(po_name)
+                     else
+                       queue.all_pending
+                     end
+
+          formatted = requests.map do |req|
+            {
+              id: req.id,
+              capability: req.capability,
+              question: req.question,
+              options: req.options,
+              age: req.age_string,
+              created_at: req.created_at.iso8601
+            }
+          end
+
+          ::MCP::Tool::Response.new([{
+            type: "text",
+            text: JSON.pretty_generate({
+              count: formatted.length,
+              requests: formatted
+            })
+          }])
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/mcp/tools/inspect_po.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module MCP
+    module Tools
+      # Get detailed information about a prompt object
+      class InspectPO < ::MCP::Tool
+        tool_name "inspect_po"
+        description "Get detailed information about a prompt object including its configuration, capabilities, and prompt body"
+
+        input_schema(
+          type: "object",
+          properties: {
+            po_name: {
+              type: "string",
+              description: "Name of the prompt object to inspect"
+            }
+          },
+          required: %w[po_name]
+        )
+
+        def self.call(po_name:, server_context:)
+          env = server_context[:env]
+
+          po = env.registry.get(po_name)
+          unless po.is_a?(PromptObjects::PromptObject)
+            return ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.generate({ error: "Prompt object '#{po_name}' not found" })
+            }])
+          end
+
+          # Categorize capabilities
+          declared_caps = po.config["capabilities"] || []
+          universal_caps = PromptObjects::UNIVERSAL_CAPABILITIES
+
+          # Resolve which are POs vs primitives
+          delegates = []
+          primitives = []
+
+          declared_caps.each do |cap_name|
+            cap = env.registry.get(cap_name)
+            if cap.is_a?(PromptObjects::PromptObject)
+              delegates << cap_name
+            elsif cap.is_a?(PromptObjects::Primitive)
+              primitives << cap_name
+            end
+          end
+
+          info = {
+            name: po.name,
+            description: po.description,
+            state: po.state || :idle,
+            config: po.config,
+            capabilities: {
+              universal: universal_caps,
+              primitives: primitives,
+              delegates: delegates,
+              all_declared: declared_caps
+            },
+            prompt_body: po.body,
+            history_length: po.history.length
+          }
+
+          ::MCP::Tool::Response.new([{
+            type: "text",
+            text: JSON.pretty_generate(info)
+          }])
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/mcp/tools/list_prompt_objects.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module MCP
+    module Tools
+      # List all loaded prompt objects with their current state
+      class ListPromptObjects < ::MCP::Tool
+        tool_name "list_prompt_objects"
+        description "List all loaded prompt objects with their names, descriptions, and current state"
+
+        input_schema(
+          type: "object",
+          properties: {},
+          required: []
+        )
+
+        def self.call(server_context:, **_args)
+          env = server_context[:env]
+
+          pos = env.registry.prompt_objects.map do |po|
+            {
+              name: po.name,
+              description: po.description,
+              state: po.state || :idle,
+              capabilities: po.config["capabilities"] || []
+            }
+          end
+
+          ::MCP::Tool::Response.new([{
+            type: "text",
+            text: JSON.pretty_generate(pos)
+          }])
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/mcp/tools/respond_to_request.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module MCP
+    module Tools
+      # Respond to a pending human request
+      class RespondToRequest < ::MCP::Tool
+        tool_name "respond_to_request"
+        description "Respond to a pending human request from a prompt object. This unblocks the PO that asked the question."
+
+        input_schema(
+          type: "object",
+          properties: {
+            request_id: {
+              type: "string",
+              description: "The ID of the pending request (from get_pending_requests)"
+            },
+            response: {
+              type: "string",
+              description: "Your response to the question"
+            }
+          },
+          required: %w[request_id response]
+        )
+
+        def self.call(request_id:, response:, server_context:)
+          env = server_context[:env]
+          queue = env.human_queue
+
+          # Find the request first to give better error messages
+          request = queue.all_pending.find { |r| r.id == request_id }
+
+          unless request
+            return ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.generate({
+                error: "Request not found",
+                request_id: request_id,
+                hint: "Use get_pending_requests to see available requests"
+              })
+            }])
+          end
+
+          # Respond (this unblocks the waiting thread)
+          queue.respond(request_id, response)
+
+          # Log to message bus
+          env.bus.publish(
+            from: "mcp_client",
+            to: request.capability,
+            message: "[response to ask_human] #{response}"
+          )
+
+          ::MCP::Tool::Response.new([{
+            type: "text",
+            text: JSON.generate({
+              success: true,
+              request_id: request_id,
+              capability: request.capability,
+              question: request.question,
+              response: response
+            })
+          }])
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/mcp/tools/send_message.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module MCP
+    module Tools
+      # Send a message to a prompt object and get its response
+      class SendMessage < ::MCP::Tool
+        tool_name "send_message"
+        description "Send a message to a prompt object. The PO will process it (potentially calling tools) and return a response."
+
+        input_schema(
+          type: "object",
+          properties: {
+            po_name: {
+              type: "string",
+              description: "Name of the prompt object to message"
+            },
+            message: {
+              type: "string",
+              description: "The message to send"
+            }
+          },
+          required: %w[po_name message]
+        )
+
+        def self.call(po_name:, message:, server_context:)
+          env = server_context[:env]
+          context = server_context[:context]
+
+          po = env.registry.get(po_name)
+          unless po.is_a?(PromptObjects::PromptObject)
+            return ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.generate({ error: "Prompt object '#{po_name}' not found" })
+            }])
+          end
+
+          # Log to message bus
+          env.bus.publish(from: "mcp_client", to: po_name, message: message)
+
+          # Set context for this interaction
+          context.current_capability = po_name
+          po.state = :working
+
+          begin
+            response = po.receive(message, context: context)
+            po.state = :idle
+
+            # Log response
+            env.bus.publish(from: po_name, to: "mcp_client", message: response)
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.generate({
+                po_name: po_name,
+                response: response,
+                history_length: po.history.length
+              })
+            }])
+          rescue StandardError => e
+            po.state = :idle
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.generate({ error: e.message, backtrace: e.backtrace.first(5) })
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/message_bus.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  # Message bus for routing and logging all inter-capability communication.
+  # This makes the semantic binding visible - you can see natural language
+  # being transformed into capability calls.
+  class MessageBus
+    attr_reader :log
+
+    def initialize
+      @log = []
+      @subscribers = []
+    end
+
+    # Log a message between capabilities.
+    # @param from [String] Source capability name
+    # @param to [String] Destination capability name
+    # @param message [String, Hash] The message content
+    # @return [Hash] The log entry
+    def publish(from:, to:, message:)
+      entry = {
+        timestamp: Time.now,
+        from: from,
+        to: to,
+        message: truncate_message(message)
+      }
+
+      @log << entry
+      notify_subscribers(entry)
+      entry
+    end
+
+    # Subscribe to message events.
+    # @yield [Hash] Called with each new message entry
+    def subscribe(&block)
+      @subscribers << block
+    end
+
+    # Unsubscribe from message events.
+    # @param block [Proc] The subscriber to remove
+    def unsubscribe(block)
+      @subscribers.delete(block)
+    end
+
+    # Get recent log entries.
+    # @param count [Integer] Number of entries to return
+    # @return [Array<Hash>]
+    def recent(count = 20)
+      @log.last(count)
+    end
+
+    # Clear the log.
+    def clear
+      @log.clear
+    end
+
+    # Format log entries for display.
+    # @param count [Integer] Number of entries to format
+    # @return [String]
+    def format_log(count = 20)
+      recent(count).map do |entry|
+        time = entry[:timestamp].strftime("%H:%M:%S")
+        from = entry[:from]
+        to = entry[:to]
+        msg = entry[:message]
+
+        "#{time}  #{from} → #{to}: #{msg}"
+      end.join("\n")
+    end
+
+    private
+
+    def notify_subscribers(entry)
+      @subscribers.each { |s| s.call(entry) }
+    end
+
+    def truncate_message(message, max_length = 100)
+      str = case message
+            when Hash
+              message.to_json
+            when String
+              message
+            else
+              message.to_s
+            end
+
+      # Remove newlines for cleaner log display
+      str = str.gsub(/\s+/, " ").strip
+
+      if str.length > max_length
+        str[0, max_length] + "..."
+      else
+        str
+      end
+    end
+  end
+end

data/lib/prompt_objects/primitive.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  # Base class for primitive capabilities.
+  # Primitives are deterministic Ruby implementations (no LLM interpretation).
+  class Primitive < Capability
+    # Primitives are always "idle" in terms of state since they execute synchronously
+    def initialize
+      super
+      @state = :idle
+    end
+  end
+end